@jr2/orchestrator 0.2.1 → 0.4.1

package/console/main.ts

@@ -25,9 +25,28 @@
 // hand-rolled memo()/paint() machinery did. This file is the BOOTSTRAP and owns only working
 // state — the machine-doc cache, the input-schema cache, the fetch serials, the zoom readout; the
 // diagram's own working state (fold set, viewport, what is shown) lives in canvas.ts.
+//
+// A run that binds a Chart (ADR-0070) draws ITS Machine, not the Workflow's: the definition's doc
+// has the Open body as one opaque child, and a Chart one cannot watch is a Chart one cannot trust.
+// So the doc the center pane draws is chosen per selection (`machineDocSource`): the Workflow's
+// Machine, or, when the selected run's observation says `bound`, the run's own from
+// `GET /workflows/:name/runs/:runId/machine`, cached per run id. The live child still joins its
+// subgraph by `src`, which the per-run doc keeps as the body's slot key.
 
 import { h, render } from "preact";
-import { applyFrame, emptyStore, type Frame, type GateCard, type ObservedRun, type Store } from "./store.ts";
+import {
+  applyFrame,
+  emptyStore,
+  machineDocSource,
+  selectedRun,
+  type Frame,
+  type GateCard,
+  type ObservedRun,
+  type Store,
+  type HeldLine,
+  type WaitingLine,
+  type WorkflowListing,
+} from "./store.ts";
 import { zoomFit, zoomIn, zoomOut, zoomReset, type MachineDoc } from "./canvas.ts";
 import { App, type AppApi, type MachineView } from "./components/app.ts";
 
@@ -49,6 +68,9 @@ function rerender(): void {
 function dispatch(frame: Frame): void {
   store = applyFrame(store, frame);
   rerender();
+  // A frame can change which doc the pane draws: a new selection, a run selected, a run that now
+  // binds a Chart. The check is a key compare; only a change fetches.
+  void syncMachine();
 }
 
 // ---- The token (ADR-0032) -----------------------------------------------------------------------
@@ -98,7 +120,7 @@ async function validateToken(): Promise<void> {
   dispatch({ kind: "token", state: "live" });
   const runs = (await res.json()) as Array<{ runId: string; workflow: string }>;
   if (serial !== tokenSerial) return;
-  for (const r of runs) void refreshGates(r.runId, r.workflow);
+  for (const r of runs) void refreshRun(r.runId, r.workflow);
 }
 
 function setToken(value: string): void {
@@ -112,7 +134,7 @@ function setToken(value: string): void {
   void validateToken();
 }
 
-// ---- Gate discovery (frame-triggered — ADR-0032) ------------------------------------------------
+// ---- Gate discovery and waits (frame-triggered — ADR-0032, ADR-0064) ----------------------------
 
 /** Per-run re-fetch serials — fetch bookkeeping like `docs`, not belief. The browser runs these
  *  requests on parallel connections, so answers can land out of ORDER: a re-fetch triggered by the
@@ -121,21 +143,25 @@ function setToken(value: string): void {
  *  emptied — pinning the ⚑ and inviting a second delivery until the run's next frame, which a run
  *  parked in a long agent step may not land for minutes. Only the latest-STARTED re-fetch may
  *  speak for a run; superseded answers are dropped before they reach the store. */
-const gateFetchSerial = new Map<string, number>();
+const runFetchSerial = new Map<string, number>();
 
 /** Re-read one run's open gates off the guarded surface and fold the WHOLE answer in. Called on
  *  every frame that touches the run — that is the synchronization: a gate opens with a state entry
  *  and closes with its exit, and every entry/exit lands a frame. A delivery's success is the next
- *  re-fetch coming back empty; nothing here concludes anything on its own. */
-async function refreshGates(runId: string, workflow: string): Promise<void> {
+ *  re-fetch coming back empty; nothing here concludes anything on its own. The same answer carries
+ *  why the run's Workspaces in `placing` wait (ADR-0064), folded as its own frame by the same rules:
+ *  a Workspace enters and leaves `placing` with a frame too. */
+async function refreshRun(runId: string, workflow: string): Promise<void> {
   if (store.token !== "live") return; // observer mode: the inbox does not exist
-  const serial = (gateFetchSerial.get(runId) ?? 0) + 1;
-  gateFetchSerial.set(runId, serial);
+  const serial = (runFetchSerial.get(runId) ?? 0) + 1;
+  runFetchSerial.set(runId, serial);
   const res = await gfetch(`/runs/${encodeURIComponent(runId)}`);
   if (!res) return; // 401 already dropped the page to observer
-  const gates = res.ok ? (((await res.json()) as { gates?: GateCard[] }).gates ?? []) : []; // !ok: settled + evicted
-  if (gateFetchSerial.get(runId) !== serial) return; // superseded — a newer re-fetch owns the answer
-  dispatch({ kind: "gates", runId, workflow, gates });
+  // !ok: settled + evicted — no gates, and nothing waits.
+  const body = res.ok ? ((await res.json()) as { gates?: GateCard[]; waiting?: WaitingLine[]; held?: HeldLine[] }) : {};
+  if (runFetchSerial.get(runId) !== serial) return; // superseded — a newer re-fetch owns the answer
+  dispatch({ kind: "gates", runId, workflow, gates: body.gates ?? [] });
+  dispatch({ kind: "waiting", runId, workflow, waiting: body.waiting ?? [], held: body.held ?? [] });
 }
 
 // ---- The two writes (start-run + gate delivery — ADR-0033) --------------------------------------
@@ -215,34 +241,68 @@ async function selectWorkflow(
   const moved = name !== store.workflow;
   if (push && moved) history.pushState({}, "", name ? `/workflows/${encodeURIComponent(name)}` : "/");
   document.title = name ? `jr2 · ${name}` : "jr2 · Console";
-  dispatch({ kind: "select", workflow: name });
+  // Re-selecting the selection (a popstate re-fire) with its diagram in hand keeps the feed.
+  const reconnect = moved || !view.doc;
+  if (reconnect) {
+    feed?.close();
+    feed = null;
+    // Forget the old diagram NOW, before the `select` frame: the new feed's frames start landing
+    // before the new doc is in hand, and they must not re-layout (or highlight) the machine the
+    // reader just left — the render reaches the canvas effect, which clears it.
+    view = { doc: null, placeholder: name ? null : "select a workflow from the fleet", note: null };
+    shownKey = null;
+  }
+  dispatch({ kind: "select", workflow: name }); // the dispatch starts the doc's fetch (syncMachine)
   if (runId) dispatch({ kind: "selectRun", runId });
-  if (!moved && view.doc) return; // re-selecting the selection (a popstate re-fire): nothing to do
-  feed?.close();
-  feed = null;
-  // Forget the old diagram NOW: the new feed's frames start landing before the new doc is in hand,
-  // and they must not re-layout (or highlight) the machine the reader just left — the render below
-  // reaches the canvas effect, which clears it.
-  view = { doc: null, placeholder: name ? null : "select a workflow from the fleet", note: null };
-  rerender();
-  if (!name) return;
+  if (!reconnect || !name) return;
   connectFeed(name);
-  await loadMachine(name);
+  await syncMachine();
 }
 
-/** The selected workflow's Machine docs, kept across navigations — structure does not change under
- *  a running orchestrator, so going back to a workflow is instant. Misses are NOT cached: a name
- *  can be registered after this page loaded, and re-selecting it should find it. */
+/** Machine docs, kept across navigations and keyed by `machineDocSource`: a Workflow's doc is one
+ *  per name (structure does not change under a running orchestrator, so going back is instant), and
+ *  a run that binds a Chart has its own per run id (ADR-0070). Misses are NOT cached: a name can be
+ *  registered after this page loaded, and re-selecting it should find it. */
 const docs = new Map<string, MachineDoc>();
 
-async function loadMachine(name: string): Promise<void> {
-  let doc: MachineDoc | null | undefined = docs.get(name);
-  if (doc === undefined) {
-    const res = await fetch(`/workflows/${encodeURIComponent(name)}/machine`);
-    doc = res.ok ? ((await res.json()) as MachineDoc) : null;
-    if (doc) docs.set(name, doc);
+/** The doc key the pane draws or is fetching — so a frame that changes nothing fetches nothing, and
+ *  an answer for a key the reader has left is dropped. */
+let shownKey: string | null = null;
+
+async function fetchDoc(source: { key: string; path: string }): Promise<MachineDoc | null> {
+  const cached = docs.get(source.key);
+  if (cached) return cached;
+  try {
+    const res = await fetch(source.path);
+    const doc = res.ok ? ((await res.json()) as MachineDoc) : null;
+    if (doc) docs.set(source.key, doc);
+    return doc;
+  } catch {
+    return null; // network trouble reads as a miss; the next selection retries
+  }
+}
+
+/** Bring the pane's doc in line with the selection: the selected run's bound Machine when it binds
+ *  a Chart, else the Workflow's (`machineDocSource`, ADR-0070). */
+async function syncMachine(): Promise<void> {
+  const name = store.workflow;
+  if (!name) return;
+  const source = machineDocSource(name, selectedRun(store));
+  if (source.key === shownKey) return;
+  shownKey = source.key;
+  let doc = await fetchDoc(source);
+  if (shownKey !== source.key) return; // the reader moved on while the fetch was out
+  let note: MachineView["note"] = null;
+  if (!doc && source.key.startsWith("run:")) {
+    // The run's own Machine could not be read (an Orchestrator older than the route, or the run
+    // left the store): draw the Workflow's, and say the Chart's states are not in it.
+    doc = await fetchDoc(machineDocSource(name, null));
+    if (shownKey !== source.key) return;
+    note = {
+      text: "this run binds a Chart, and its Machine could not be read: the Chart's states are not shown",
+      notice: true,
+    };
   }
-  if (store.workflow !== name) return; // the reader moved on while the fetch was out
   if (!doc) {
     view = { doc: null, placeholder: null, note: { text: `no workflow "${name}"`, notice: false } };
     rerender();
@@ -251,10 +311,21 @@ async function loadMachine(name: string): Promise<void> {
   // Nothing live yet: every child machine renders once, as a dimmed template (the canvas effect
   // picks the doc up from here). The first status frame of a run with children swaps those for
   // one subgraph per instance.
-  view = { doc, placeholder: null, note: opaqueNotice(doc) };
+  view = { doc, placeholder: null, note: note ?? notDrawnNotice(doc) ?? opaqueNotice(doc) };
   rerender();
 }
 
+/** Say so when a run's doc could not draw a Chart the run binds (ADR-0070, D-B): its Open body then
+ *  shows the slot's own subgraph, and the server names why (`MachineDoc.chartsNotDrawn`). */
+function notDrawnNotice(doc: MachineDoc): MachineView["note"] {
+  const missing = doc.chartsNotDrawn ?? [];
+  if (!missing.length) return null;
+  return {
+    notice: true,
+    text: `this run binds a Chart this diagram does not draw — ${missing.map((m) => `body "${m.src}" (${m.path}): ${m.reason}`).join("; ")}`,
+  };
+}
+
 /** Say so when the diagram is knowingly incomplete: a child spawned inside an `enqueueActions`
  *  closure cannot be found by the static walk, so those states may be missing children entirely.
  *  Computed server-side (`MachineDoc.opaqueStates`) and surfaced HERE, where the reader is. */
@@ -282,12 +353,12 @@ function connectFeed(name: string): void {
   feed.addEventListener("runs", (e) => {
     const runs = JSON.parse((e as MessageEvent<string>).data) as ObservedRun[];
     dispatch({ kind: "runs", runs });
-    for (const r of runs) void refreshGates(r.runId, name);
+    for (const r of runs) void refreshRun(r.runId, name);
   });
   feed.addEventListener("status", (e) => {
     const status = JSON.parse((e as MessageEvent<string>).data) as ObservedRun;
     dispatch({ kind: "status", status });
-    void refreshGates(status.runId, name);
+    void refreshRun(status.runId, name);
   });
   feed.addEventListener("gone", (e) => {
     const { runId } = JSON.parse((e as MessageEvent<string>).data) as { runId: string };
@@ -295,7 +366,7 @@ function connectFeed(name: string): void {
     // The reducer already dropped the card (a gate exists only while its state is entered —
     // ADR-0011); the re-fetch is the same frame-triggered discipline as `runs`/`status`, and its
     // 404 converges on the same empty answer.
-    void refreshGates(runId, name);
+    void refreshRun(runId, name);
   });
   feed.addEventListener("emit", (e) => {
     const { runId, type } = JSON.parse((e as MessageEvent<string>).data) as { runId: string; type: string };
@@ -318,7 +389,7 @@ async function snapshotWorkflow(name: string): Promise<void> {
     if (!res.ok) return;
     const runs = (await res.json()) as ObservedRun[];
     dispatch({ kind: "fleet", workflow: name, runs });
-    for (const r of runs) void refreshGates(r.runId, name);
+    for (const r of runs) void refreshRun(r.runId, name);
   } catch {
     // transient — the next tick tries again
   }
@@ -327,7 +398,7 @@ async function snapshotWorkflow(name: string): Promise<void> {
 async function snapshotFleet(): Promise<void> {
   try {
     const res = await fetch("/workflows");
-    if (res.ok) dispatch({ kind: "workflows", workflows: (await res.json()) as string[] });
+    if (res.ok) dispatch({ kind: "workflows", workflows: (await res.json()) as WorkflowListing[] });
   } catch {
     // transient — the next tick tries again
   }
@@ -368,7 +439,7 @@ async function boot(): Promise<void> {
   // observation), then the selection the address carries — deep links work on load.
   try {
     const res = await fetch("/workflows");
-    if (res.ok) dispatch({ kind: "workflows", workflows: (await res.json()) as string[] });
+    if (res.ok) dispatch({ kind: "workflows", workflows: (await res.json()) as WorkflowListing[] });
   } catch {
     // the interval retries; the rail says "no workflows registered" until then
   }

package/console/store.ts

@@ -24,6 +24,43 @@ export type ObservedRun = {
   status: string;
   value: unknown;
   children: Array<Record<string, unknown>>;
+  /** The run binds at least one Chart (ADR-0070): its Machine is the Chart wrapper's with each bound
+   *  Open body's Chart compiled in, served per run. Absent when it binds none. */
+  bound?: true;
+  /** The hashes of the Charts the run binds now, distinct and sorted. A run can bind a second Chart
+   *  in its life, so these, with the run id, key its doc. Absent from an older Orchestrator. */
+  chartHashes?: string[];
+};
+
+/** Where a Workflow came from (ADR-0070): a Machine or a Chart file in the Assembly, or a runtime
+ *  Chart put on the Instance. */
+export type WorkflowOrigin = "machine" | "file" | "runtime";
+
+/** One entry of `GET /workflows` (ADR-0070) — mirrors `WorkflowListing` in run-host.ts. A Chart
+ *  wrapper's named Charts are inside its entry, not beside it. */
+export type WorkflowListing = {
+  name: string;
+  origin: WorkflowOrigin;
+  wrapper?: {
+    body: string;
+    oneShot: boolean;
+    charts: Array<{ name: string; origin: "file" | "runtime"; unrunnable?: string }>;
+  };
+  unrunnable?: string;
+};
+
+/** One row of the fleet rail: a Workflow, or a named Chart indented under its Chart wrapper. */
+export type FleetEntry = {
+  name: string;
+  origin: WorkflowOrigin;
+  /** 0 for a Workflow, 1 for a Chart under its wrapper. */
+  depth: 0 | 1;
+  /** A Chart wrapper's Open body slot, and whether its door takes a Chart one-shot. */
+  wrapper?: { body: string; oneShot: boolean };
+  unrunnable?: string;
+  /** A runtime Chart of the same name that this Chart file shadows (ADR-0070): one row per name,
+   *  so the rail keys stay distinct; the shadowed Chart is unrunnable, and this says why. */
+  shadows?: { origin: WorkflowOrigin; unrunnable?: string };
 };
 
 /** One open gate as `GET /runs/:id` reports it — mirrors `GateView` in run-host.ts. */
@@ -34,6 +71,15 @@ export type GateCard = {
   meta?: Record<string, unknown>;
 };
 
+/** One Workspace waiting for capacity as `GET /runs/:id` reports it (ADR-0064) — mirrors
+ *  `RunWaiting` in run-host.ts. Guarded: `message` is the scheduler's or the quota's own words. */
+export type WaitingLine = { child: string; on: "node" | "quota"; message: string; since: string };
+
+/** One outstanding pick as `GET /runs/:id` reports it (ADR-0024) — mirrors `RunHeld` in
+ *  run-host.ts. There is no default time bound on a held Turn: "held since" is how a human sees one.
+ *  Guarded like the reason a Workspace waits: a pick names what an Agent did. */
+export type HeldLine = { agent: string; pick: string; since: string };
+
 /** The credential's state — never its value, which stays in sessionStorage (ADR-0032). */
 export type TokenState = "none" | "checking" | "live" | "invalid";
 
@@ -45,7 +91,7 @@ export type Frame =
   | { kind: "gone"; runId: string }
   | { kind: "emit"; runId: string; type: string }
   | { kind: "connection"; state: Store["connection"] }
-  | { kind: "workflows"; workflows: string[] }
+  | { kind: "workflows"; workflows: ReadonlyArray<WorkflowListing | string> }
   | { kind: "select"; workflow: string | null }
   | { kind: "selectRun"; runId: string | null }
   | { kind: "selectNode"; nodeId: string | null }
@@ -53,6 +99,7 @@ export type Frame =
   | { kind: "toggleWorkflow"; workflow: string }
   | { kind: "token"; state: TokenState }
   | { kind: "gates"; runId: string; workflow: string; gates: GateCard[] }
+  | { kind: "waiting"; runId: string; workflow: string; waiting: WaitingLine[]; held?: HeldLine[] }
   | { kind: "inboxScope"; all: boolean }
   | { kind: "startForm"; workflow: string | null };
 
@@ -66,7 +113,10 @@ export type Frame =
  * `emits`    newest-first, across the selected workflow's runs — each tagged with its run.
  * `connection` the socket's state, owned by the page, never by a frame off the wire.
  * `workflow` the selection the ADDRESS carries (`/workflows/:name`); null at `/`.
- * `workflows` the registered names (`GET /workflows`) — what the fleet rail lists.
+ * `workflows` every registered name (`GET /workflows`), Machines and named Charts alike — what the
+ *            fleet polls and selects. A Chart's name is `<wrapper>/<name>` (ADR-0070).
+ * `listing`  the same answer with its structure: each Workflow's origin, a Chart wrapper's Charts
+ *            inside its entry — what the fleet rail draws ({@link fleetEntries}).
  * `fleet`    REST snapshots per workflow (`GET /workflows/:name/runs`), for the workflows that do
  *            NOT hold the feed. Never more than one EventSource — the rest of the fleet is polled.
  * `expanded` which workflows the rail shows runs for (the reader's folding, plus auto-expand on
@@ -76,6 +126,9 @@ export type Frame =
  *            "invalid". Anything but "live" means observer mode.
  * `gates`    the gate inbox: runId -> { workflow, gates } from `GET /runs/:id` re-fetches. Guarded
  *            data (Instance band), so it cannot outlive the credential that read it.
+ * `waiting`  why each run's Workspaces in `placing` wait (ADR-0064): runId -> { workflow, waiting },
+ *            off the SAME `GET /runs/:id` re-fetch as `gates`, under the same rules — guarded, whole
+ *            per run, gone with the credential. The open band sees `placing` lit and nothing more.
  * `inboxAll` the widen control: false = the inbox follows the selection, true = every workflow.
  * `startFormFor` which workflow's start-run form is open, if any.
  * `selectedNodeId` the diagram node the reader clicked — an elk node id (scope + state id), one at
@@ -93,10 +146,12 @@ export type Store = {
   connection: "connecting" | "live" | "retrying";
   workflow: string | null;
   workflows: string[];
+  listing: WorkflowListing[];
   fleet: Map<string, ObservedRun[]>;
   expanded: Set<string>;
   token: TokenState;
   gates: Map<string, { workflow: string; gates: GateCard[] }>;
+  waiting: Map<string, { workflow: string; waiting: WaitingLine[]; held: HeldLine[] }>;
   inboxAll: boolean;
   startFormFor: string | null;
 };
@@ -119,10 +174,12 @@ export function emptyStore(): Store {
     connection: "connecting",
     workflow: null,
     workflows: [],
+    listing: [],
     fleet: new Map(),
     expanded: new Set(),
     token: "none",
     gates: new Map(),
+    waiting: new Map(),
     inboxAll: false,
     startFormFor: null,
   };
@@ -141,6 +198,7 @@ export function applyFrame(store: Store, frame: Frame): Store {
         ...store,
         runs: new Map(frame.runs.map((r): [string, ObservedRun] => [r.runId, r])),
         gates: dropAbsent(store.gates, store.workflow, new Set(frame.runs.map((r) => r.runId))),
+        waiting: dropAbsent(store.waiting, store.workflow, new Set(frame.runs.map((r) => r.runId))),
       });
 
     case "status":
@@ -152,13 +210,14 @@ export function applyFrame(store: Store, frame: Frame): Store {
       // a reconnect window, which is ordinary. Its inbox card goes either way: a gate exists exactly
       // while its invoking state is entered (ADR-0011), and this run has no entered states left.
       const gates = mapWithout(store.gates, frame.runId);
+      const waiting = mapWithout(store.waiting, frame.runId);
       const departing = store.runs.get(frame.runId);
-      if (!departing) return store.gates === gates ? store : { ...store, gates };
+      if (!departing) return store.gates === gates && store.waiting === waiting ? store : { ...store, gates, waiting };
       const runs = new Map(store.runs);
       runs.delete(frame.runId);
       const settled = new Map(store.settled).set(frame.runId, departing);
       while (settled.size > SETTLED_CAP) settled.delete(settled.keys().next().value!);
-      return select({ ...store, runs, settled, gates });
+      return select({ ...store, runs, settled, gates, waiting });
     }
 
     case "emit":
@@ -167,8 +226,14 @@ export function applyFrame(store: Store, frame: Frame): Store {
     case "connection":
       return { ...store, connection: frame.state };
 
-    case "workflows":
-      return { ...store, workflows: frame.workflows };
+    case "workflows": {
+      // Replaced wholesale. An Orchestrator older than ADR-0070 answers bare names: each reads as
+      // a Machine, so the rail has one shape to draw.
+      const listing = frame.workflows.map(
+        (w): WorkflowListing => (typeof w === "string" ? { name: w, origin: "machine" } : w),
+      );
+      return { ...store, listing, workflows: fleetEntries(listing).map((e) => e.name) };
+    }
 
     case "select": {
       // The address moved. The feed's state belongs to the OLD selection — the new feed's opening
@@ -206,8 +271,9 @@ export function applyFrame(store: Store, frame: Frame): Store {
       // so it settles that workflow's inbox cards the same way (a run the snapshot does not carry
       // will never be re-fetched again).
       const fleet = new Map(store.fleet).set(frame.workflow, frame.runs);
-      const gates = dropAbsent(store.gates, frame.workflow, new Set(frame.runs.map((r) => r.runId)));
-      return { ...store, fleet, gates };
+      const present = new Set(frame.runs.map((r) => r.runId));
+      const gates = dropAbsent(store.gates, frame.workflow, present);
+      return { ...store, fleet, gates, waiting: dropAbsent(store.waiting, frame.workflow, present) };
     }
 
     case "toggleWorkflow": {
@@ -221,7 +287,7 @@ export function applyFrame(store: Store, frame: Frame): Store {
       // "invalid" (the any-later-401 drop of ADR-0032) empties the inbox. "checking" keeps it — a
       // re-validation of a token that turns out fine should not flash the inbox empty.
       if (frame.state === "none" || frame.state === "invalid") {
-        return { ...store, token: frame.state, gates: new Map() };
+        return { ...store, token: frame.state, gates: new Map(), waiting: new Map() };
       }
       return { ...store, token: frame.state };
 
@@ -238,6 +304,24 @@ export function applyFrame(store: Store, frame: Frame): Store {
       return { ...store, gates };
     }
 
+    case "waiting": {
+      // The same guarded re-fetch's other half (ADR-0064), folded the same way: whole per run, and
+      // nothing folded without the credential that read it.
+      // The run's outstanding picks (ADR-0024) ride the same frame: one re-fetch, one fold.
+      if (store.token !== "live") return store;
+      const held = frame.held ?? [];
+      if (!frame.waiting.length && !held.length) {
+        const waiting = mapWithout(store.waiting, frame.runId);
+        return waiting === store.waiting ? store : { ...store, waiting };
+      }
+      const waiting = new Map(store.waiting).set(frame.runId, {
+        workflow: frame.workflow,
+        waiting: frame.waiting,
+        held,
+      });
+      return { ...store, waiting };
+    }
+
     case "inboxScope":
       return { ...store, inboxAll: frame.all };
 
@@ -258,15 +342,20 @@ function mapWithout<K, V>(map: Map<K, V>, key: K): Map<K, V> {
   return next;
 }
 
-/** Drop `workflow`'s inbox entries for runs a whole-set frame did not mention. Those runs will
- *  never be re-fetched again (frames and snapshots are per-run triggers), so a card kept here would
- *  be stale forever — this is the level-triggered idiom applied to the inbox, not bookkeeping. */
-function dropAbsent(gates: Store["gates"], workflow: string | null, present: Set<string>): Store["gates"] {
-  if (!workflow) return gates;
-  let next = gates;
-  for (const [runId, entry] of gates) {
+/** Drop `workflow`'s guarded entries (inbox cards, waits) for runs a whole-set frame did not
+ *  mention. Those runs will never be re-fetched again (frames and snapshots are per-run triggers),
+ *  so an entry kept here would be stale forever — this is the level-triggered idiom applied to the
+ *  guarded maps, not bookkeeping. */
+function dropAbsent<V extends { workflow: string }>(
+  entries: Map<string, V>,
+  workflow: string | null,
+  present: Set<string>,
+): Map<string, V> {
+  if (!workflow) return entries;
+  let next = entries;
+  for (const [runId, entry] of entries) {
     if (entry.workflow !== workflow || present.has(runId)) continue;
-    if (next === gates) next = new Map(gates);
+    if (next === entries) next = new Map(entries);
     next.delete(runId);
   }
   return next;
@@ -310,6 +399,71 @@ export function fleetRuns(store: Store, workflow: string): Array<{ run: Observed
   return (store.fleet.get(workflow) ?? []).map((run) => ({ run, settled: false }));
 }
 
+/**
+ * The fleet rail's rows (ADR-0070): each Workflow in the listing's order, a Chart wrapper's named
+ * Charts indented under it as `<wrapper>/<name>`. A Chart the listing also gives at the top level
+ * is drawn once, under its wrapper; one whose wrapper the listing does not give stays at the top.
+ */
+export function fleetEntries(listing: readonly WorkflowListing[]): FleetEntry[] {
+  const full = (wrapper: string, name: string): string => (name.includes("/") ? name : `${wrapper}/${name}`);
+  const nested = new Set<string>();
+  for (const w of listing) for (const c of w.wrapper?.charts ?? []) nested.add(full(w.name, c.name));
+  const rows: FleetEntry[] = [];
+  for (const w of listing) {
+    if (w.origin !== "machine" && nested.has(w.name)) continue;
+    rows.push({
+      name: w.name,
+      origin: w.origin,
+      depth: 0,
+      ...(w.wrapper ? { wrapper: { body: w.wrapper.body, oneShot: w.wrapper.oneShot } } : {}),
+      ...(w.unrunnable ? { unrunnable: w.unrunnable } : {}),
+    });
+    for (const c of w.wrapper?.charts ?? []) {
+      const name = full(w.name, c.name);
+      // A Chart file and a runtime Chart of one name: the listing gives both, the file wins
+      // (ADR-0070). One row per name, the shadowed Chart a note on it, so no two rows share a key.
+      const twin = rows.find((r) => r.depth === 1 && r.name === name);
+      if (twin) {
+        const fileFirst = twin.origin === "file" || c.origin !== "file";
+        const shadowed = fileFirst ? c : { origin: twin.origin, unrunnable: twin.unrunnable };
+        if (!fileFirst) {
+          twin.origin = c.origin;
+          if (c.unrunnable) twin.unrunnable = c.unrunnable;
+          else delete twin.unrunnable;
+        }
+        twin.shadows = { origin: shadowed.origin, ...(shadowed.unrunnable ? { unrunnable: shadowed.unrunnable } : {}) };
+        continue;
+      }
+      rows.push({
+        name,
+        origin: c.origin,
+        depth: 1,
+        ...(c.unrunnable ? { unrunnable: c.unrunnable } : {}),
+      });
+    }
+  }
+  return rows;
+}
+
+/**
+ * Which Machine doc the center pane draws (ADR-0070), as a cache key and the route that serves it.
+ * A run that binds a Chart draws its own Machine, the Chart compiled into the Open body, so its doc
+ * is per run id; every other selection draws the Workflow's Machine, shared by all its runs. The
+ * Workflow name rides the route as one encoded segment (`<wrapper>%2F<name>` for a named Chart).
+ */
+export function machineDocSource(
+  workflow: string,
+  run: Pick<ObservedRun, "runId" | "bound" | "chartHashes"> | null,
+): { key: string; path: string } {
+  const base = `/workflows/${encodeURIComponent(workflow)}`;
+  if (run?.bound === true) {
+    // The run id and the Charts it binds now: a second Chart in the run's life is a new doc.
+    const charts = run.chartHashes?.length ? `:${run.chartHashes.join(",")}` : "";
+    return { key: `run:${run.runId}${charts}`, path: `${base}/runs/${encodeURIComponent(run.runId)}/machine` };
+  }
+  return { key: `workflow:${workflow}`, path: `${base}/machine` };
+}
+
 /** The inbox as the Attention tab draws it: every card, or the selection's slice. The inbox itself
  *  is GLOBAL (every workflow the fleet knows) — the filter is presentation, which is why it lives
  *  in a selector and not in `applyFrame`. */
@@ -327,6 +481,56 @@ export function selectedRunGates(store: Store): GateCard[] {
   return store.gates.get(store.selectedRunId)?.gates ?? [];
 }
 
+/** Why the SELECTED run's Workspaces wait for capacity (ADR-0064) — empty in observer mode, where
+ *  the diagram still lights `placing` but the reason is not the page's to know. */
+export function selectedRunWaiting(store: Store): WaitingLine[] {
+  if (store.selectedRunId === null) return [];
+  return store.waiting.get(store.selectedRunId)?.waiting ?? [];
+}
+
+/** The SELECTED run's outstanding picks, each with since when it is held (ADR-0024) — empty in
+ *  observer mode. */
+export function selectedRunHeld(store: Store): HeldLine[] {
+  if (store.selectedRunId === null) return [];
+  return store.waiting.get(store.selectedRunId)?.held ?? [];
+}
+
+/** One party's seat on one state (ADR-0015): who may send which names there — mirrors
+ *  `MachineSeat` in vocabulary.ts. */
+export type Seat = { state: string; party: "agent" | "gate"; agent?: string; names: string[] };
+
+/** The part of a Machine doc the seats are read from: each body's `seats` and `warnings`, and the
+ *  child Machines below its states (canvas.ts's `MachineBodyDoc`, structurally). */
+export type SeatedBody = {
+  seats?: Seat[];
+  warnings?: string[];
+  root: SeatedState;
+};
+type SeatedState = { states: SeatedState[]; children: Array<{ machine?: SeatedBody }> };
+
+/**
+ * Who may send what, per state, and what the build found suspect (ADR-0015) — for the Machine and
+ * every Machine it composes, in the order `jr2 up` prints them: the root's body, then each child
+ * Machine's, depth-first in state order. A function of the doc, not of the store: the doc is
+ * structure the server serves (app.ts's `MachineView`), and this is the one piece of it worth a
+ * unit test outside the canvas.
+ */
+export function docSeats(doc: SeatedBody | null): { seats: Seat[]; warnings: string[] } {
+  const seats: Seat[] = [];
+  const warnings: string[] = [];
+  const body = (b: SeatedBody): void => {
+    seats.push(...(b.seats ?? []));
+    warnings.push(...(b.warnings ?? []));
+    state(b.root);
+  };
+  const state = (s: SeatedState): void => {
+    for (const child of s.children) if (child.machine) body(child.machine);
+    s.states.forEach(state);
+  };
+  if (doc) body(doc);
+  return { seats, warnings };
+}
+
 /** What the nav badge counts: every open gate everywhere — attention is global even when the
  *  inbox view is filtered. */
 export function gateCount(store: Store): number {