H-6819: Add status views, identities and a Kanban board to Petrinaut (experimental)

.changeset/status-views-core.md

@@ -0,0 +1,5 @@
+---
+"@hashintel/petrinaut-core": patch
+---
+
+SDCPN documents carry optional `identities` (named instance identities that colour elements reference via `identityRef`) and `statusViews` (ordered, place-mapped status labels with optional token conditions and an optional exit label); both validate against the entity schemas and survive file import/export. Actual-mode transition firings carry the attribute values of the tokens they consumed and produced (`inputTokens` / `outputTokens`), and recordings carry version 2. A token record for a place with a colour must carry exactly the colour's elements, each a value of its element's type, and a record for an uncoloured place must be empty; a place whose colour has elements lists token records, not a token count. Replaying a firing whose records break that rule, or that consumes a token the marking does not hold, throws, and a recording containing one fails to parse. New evaluators derive per-instance status, time-in-state, and dwell summaries from simulation frames.

.changeset/status-views-ui.md

@@ -0,0 +1,5 @@
+---
+"@hashintel/petrinaut": patch
+---
+
+Behind the experimental **Status views** setting (off by default): the simulate panel displays and allows editing of a net's status views, token type attributes can be keyed to an identity, the events panel shows per-instance status changes, and the view switcher gains a Kanban board that lays out instances by status label with each instance's time-in-state. Component-instance nodes show a status badge tinted by the active label whenever the net declares a status view.

apps/hash-api/src/petrinaut-optimizer/shared/optimization-run-test-harness.ts

@@ -28,6 +28,8 @@ export const validOptimizationInput = {
       parameters: [],
       subnets: [],
       componentInstances: [],
+      identities: [],
+      statusViews: [],
       scenarios: [
         {
           id: "baseline",

apps/petrinaut-website/scripts/brunch-sse-fixture.ts

@@ -26,12 +26,15 @@ import http, { type ServerResponse } from "node:http";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
 
+import { ACTUAL_MODE_RECORDING_VERSION } from "@hashintel/petrinaut-core";
+
 import type {
   BrunchNetDefinitionInput,
   BrunchTransitionInput,
 } from "../src/main/app/brunch-demo/brunch-protocol";
 import type {
   ActualModeReceivedEvent,
+  ActualModeTokenValues,
   ActualModeTransitionFiring,
 } from "@hashintel/petrinaut-core";
 
@@ -192,25 +195,27 @@ const parseNumericMarking = (data: unknown, label: string): NumericMarking => {
   return marking;
 };
 
-const parseTransitionEffect = (
+const parseTokenValues = (
   data: unknown,
   label: string,
-): ActualModeTransitionFiring["input"] => {
+): ActualModeTokenValues => {
   if (!isRecord(data)) {
     throw new Error(`Recording ${label} must be an object.`);
   }
 
-  const effect: ActualModeTransitionFiring["input"] = {};
+  const tokenValues: ActualModeTokenValues = {};
 
-  for (const [placeId, value] of Object.entries(data)) {
-    if (typeof value !== "number" || !Number.isFinite(value)) {
-      throw new Error(`Recording ${label}.${placeId} must be a finite number.`);
+  for (const [placeId, tokens] of Object.entries(data)) {
+    if (!Array.isArray(tokens) || !tokens.every(isRecord)) {
+      throw new Error(
+        `Recording ${label}.${placeId} must be an array of token records.`,
+      );
     }
 
-    effect[placeId] = value;
+    tokenValues[placeId] = tokens as ActualModeTokenValues[string];
   }
 
-  return effect;
+  return tokenValues;
 };
 
 const parseTransitionFiring = (
@@ -233,8 +238,8 @@ const parseTransitionFiring = (
 
   return {
     transitionId: data.transitionId,
-    input: parseTransitionEffect(data.input, `${label}.input`),
-    output: parseTransitionEffect(data.output, `${label}.output`),
+    inputTokens: parseTokenValues(data.inputTokens, `${label}.inputTokens`),
+    outputTokens: parseTokenValues(data.outputTokens, `${label}.outputTokens`),
     ts: data.ts,
   };
 };
@@ -413,6 +418,12 @@ const parseRecordingEvents = (data: unknown): ActualModeReceivedEvent[] => {
     throw new Error("Recording root must be an object.");
   }
 
+  if (data.version !== ACTUAL_MODE_RECORDING_VERSION) {
+    throw new Error(
+      `Recording version must be ${ACTUAL_MODE_RECORDING_VERSION}, got ${String(data.version)}.`,
+    );
+  }
+
   if ("events" in data) {
     return parseReceivedEventsRecording(data);
   }
@@ -426,7 +437,7 @@ const parseRecordingEvents = (data: unknown): ActualModeReceivedEvent[] => {
   }
 
   throw new Error(
-    "Recording must be an Actual Events export with `events` or an older normalized recording.",
+    "Recording must be an Actual Events export with `events` or a normalized recording with `transitionFirings`.",
   );
 };
 
@@ -517,12 +528,12 @@ const applyFiringToMarking = (
   marking: NumericMarking,
   firing: ActualModeTransitionFiring,
 ): void => {
-  for (const [placeId, value] of Object.entries(firing.input)) {
-    marking[placeId] = (marking[placeId] ?? 0) - value;
+  for (const [placeId, tokens] of Object.entries(firing.inputTokens)) {
+    marking[placeId] = (marking[placeId] ?? 0) - tokens.length;
   }
 
-  for (const [placeId, value] of Object.entries(firing.output)) {
-    marking[placeId] = (marking[placeId] ?? 0) + value;
+  for (const [placeId, tokens] of Object.entries(firing.outputTokens)) {
+    marking[placeId] = (marking[placeId] ?? 0) + tokens.length;
   }
 };
 
@@ -609,32 +620,40 @@ const canFire = (marking: NumericMarking, transitionId: string): boolean => {
   );
 };
 
+/** The fixture's places are uncoloured, so each moved token is an empty record. */
+const emptyTokens = (count: number): ActualModeTokenValues[string] =>
+  Array.from({ length: count }, () => ({}));
+
 const applyTransition = (
   marking: NumericMarking,
   transitionId: string,
 ): ActualModeTransitionFiring => {
   const transition = getTransition(transitionId);
-  const input: ActualModeTransitionFiring["input"] = {};
-  const output: ActualModeTransitionFiring["output"] = {};
+  const inputTokens: ActualModeTokenValues = {};
+  const outputTokens: ActualModeTokenValues = {};
 
   for (const arc of transition.inputArcs) {
     if ((arc.type ?? "standard") !== "standard") {
       continue;
     }
 
-    input[arc.placeId] = (input[arc.placeId] ?? 0) + arc.weight;
+    inputTokens[arc.placeId] = (inputTokens[arc.placeId] ?? []).concat(
+      emptyTokens(arc.weight),
+    );
     marking[arc.placeId] = (marking[arc.placeId] ?? 0) - arc.weight;
   }
 
   for (const arc of transition.outputArcs) {
-    output[arc.placeId] = (output[arc.placeId] ?? 0) + arc.weight;
+    outputTokens[arc.placeId] = (outputTokens[arc.placeId] ?? []).concat(
+      emptyTokens(arc.weight),
+    );
     marking[arc.placeId] = (marking[arc.placeId] ?? 0) + arc.weight;
   }
 
   return {
     transitionId,
-    input,
-    output,
+    inputTokens,
+    outputTokens,
     ts: new Date().toISOString(),
   };
 };
@@ -864,6 +883,16 @@ const server = http.createServer((request, response) => {
   );
 });
 
+const producedTokensPerPlace = (
+  outputTokens: ActualModeTokenValues,
+): Record<string, number> =>
+  Object.fromEntries(
+    Object.entries(outputTokens).map(([placeId, tokens]) => [
+      placeId,
+      tokens.length,
+    ]),
+  );
+
 const broadcastLiveFiring = (): void => {
   const firing = nextLiveFiring();
 
@@ -877,7 +906,7 @@ const broadcastLiveFiring = (): void => {
 
   console.log(
     `[${firing.ts}] transition_firing ${firing.transitionId} -> ${JSON.stringify(
-      firing.output,
+      producedTokensPerPlace(firing.outputTokens),
     )}`,
   );
 };

apps/petrinaut-website/src/examples/example-search.ts

@@ -24,12 +24,13 @@ import {
  */
 export const sharedModes = ["edit", "simulate", "actual"] as const;
 
-export const sharedEditViews = ["canvas", "definitions"] as const;
+export const sharedEditViews = ["canvas", "definitions", "kanban"] as const;
 
 export const sharedSimulateViews = [
   "scenarios",
   "metrics",
   "experiments",
+  "status-views",
 ] as const;
 
 export const sharedOverlays = [
@@ -38,6 +39,7 @@ export const sharedOverlays = [
   "create-scenario",
   "create-metric",
   "create-experiment",
+  "create-status-view",
 ] as const;
 
 export const sharedSettingsSections = ["general", "viewport", "labs"] as const;
@@ -46,6 +48,7 @@ export const sharedResourceTypes = [
   "scenario",
   "metric",
   "experiment",
+  "status-view",
 ] as const;
 
 export type SharedEditView = (typeof sharedEditViews)[number];

apps/petrinaut-website/src/examples/navigation-search.ts

@@ -100,7 +100,9 @@ export const sharedSearchToNavigationState = (
         ? "scenarios"
         : search.resourceType === "experiment"
           ? "experiments"
-          : "metrics"
+          : search.resourceType === "status-view"
+            ? "status-views"
+            : "metrics"
       : (search.view ?? baseline.simulateView),
   simulateResource:
     search.resourceType && search.resourceId

apps/petrinaut-website/src/main/app/brunch-demo/brunch-actual-mode-provider.test.tsx

@@ -0,0 +1,148 @@
+// @vitest-environment jsdom
+
+import { act, render } from "@testing-library/react";
+import { use } from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { ActualModeContext } from "@hashintel/petrinaut/react";
+
+import { BrunchActualModeProvider } from "./brunch-actual-mode-provider";
+
+class FakeEventSource {
+  static latest: FakeEventSource | null = null;
+
+  readonly listeners = new Map<string, ((event: Event) => void)[]>();
+
+  constructor() {
+    FakeEventSource.latest = this;
+  }
+
+  addEventListener(type: string, listener: (event: Event) => void) {
+    this.listeners.set(type, [...(this.listeners.get(type) ?? []), listener]);
+  }
+
+  removeEventListener() {}
+
+  close() {}
+
+  emit(type: string, data: unknown) {
+    const event = new MessageEvent(type, { data: JSON.stringify(data) });
+    for (const listener of this.listeners.get(type) ?? []) {
+      listener(event);
+    }
+  }
+}
+
+const emit = (type: string, data: unknown) => {
+  act(() => {
+    FakeEventSource.latest!.emit(type, data);
+  });
+};
+
+const emitDefinition = async () => {
+  await act(async () => {
+    FakeEventSource.latest!.emit("definition", {
+      places: [
+        { id: "queued", name: "Queued", x: 0, y: 0 },
+        { id: "done", name: "Done", x: 100, y: 0 },
+      ],
+      transitions: [],
+    });
+  });
+};
+
+const StatusProbe = () => {
+  const actualMode = use(ActualModeContext);
+  return (
+    <output>
+      {actualMode.status}|{actualMode.transitionFirings.length}|
+      {actualMode.error ?? ""}
+    </output>
+  );
+};
+
+const renderProvider = () =>
+  render(
+    <BrunchActualModeProvider endpoint="https://brunch.example/events">
+      <StatusProbe />
+    </BrunchActualModeProvider>,
+  );
+
+const finishFiring = (inputTokens: Record<string, unknown[]>) => ({
+  transitionId: "finish",
+  inputTokens,
+  outputTokens: { done: [{}] },
+  ts: "2026-06-05T10:00:00.000Z",
+});
+
+describe("BrunchActualModeProvider", () => {
+  beforeEach(() => {
+    vi.stubGlobal("EventSource", FakeEventSource);
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    FakeEventSource.latest = null;
+  });
+
+  it("appends a firing that the marking absorbs", async () => {
+    const { container } = renderProvider();
+
+    await emitDefinition();
+    emit("initial_state", { queued: 1, done: 0 });
+    emit("transition_firing", finishFiring({ queued: [{}] }));
+
+    expect(container.textContent).toBe("streaming|1|");
+  });
+
+  it("ends the stream with an error for a firing that consumes a token the marking does not hold", async () => {
+    const { container } = renderProvider();
+
+    await emitDefinition();
+    emit("initial_state", { queued: 1, done: 0 });
+    emit("transition_firing", finishFiring({ queued: [{}] }));
+    emit("transition_firing", finishFiring({ queued: [{}] }));
+
+    expect(container.textContent).toBe(
+      'error|1|Invalid Brunch transition_firing frame: Transition firing of "finish" at 2026-06-05T10:00:00.000Z consumes 1 token from place "queued", which holds 0',
+    );
+  });
+
+  it("checks firings received before the initial state once it arrives", async () => {
+    const { container } = renderProvider();
+
+    await emitDefinition();
+    emit("transition_firing", finishFiring({ queued: [{}, {}] }));
+    emit("initial_state", { queued: 1, done: 0 });
+
+    expect(container.textContent).toBe(
+      'error|1|Invalid Brunch transition_firing frame: Transition firing of "finish" at 2026-06-05T10:00:00.000Z consumes 2 tokens from place "queued", which holds 1',
+    );
+  });
+
+  it("checks frames received before the definition once it arrives", async () => {
+    const { container } = renderProvider();
+
+    emit("initial_state", { queued: 1, done: 0 });
+    emit("transition_firing", finishFiring({ queued: [{}, {}] }));
+    expect(container.textContent).toBe("streaming|1|");
+
+    await emitDefinition();
+
+    expect(container.textContent).toBe(
+      'error|1|Invalid Brunch transition_firing frame: Transition firing of "finish" at 2026-06-05T10:00:00.000Z consumes 2 tokens from place "queued", which holds 1',
+    );
+  });
+
+  it("ends the stream with an error for a firing whose token record does not fit its place", async () => {
+    const { container } = renderProvider();
+
+    await emitDefinition();
+    emit("initial_state", { queued: 1, done: 0 });
+    emit("transition_firing", finishFiring({ queued: [{ ticket_id: "a" }] }));
+
+    expect(container.textContent).toBe(
+      'error|0|Invalid Brunch transition_firing frame: Transition firing of "finish" at 2026-06-05T10:00:00.000Z consumes token {"ticket_id":"a"} from place "queued", which carries attribute "ticket_id" although the place has no colour',
+    );
+  });
+});