@jr2/orchestrator 0.3.0 → 0.5.1

package/console/main.ts

@@ -25,9 +25,29 @@
 // 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,
+  failureReason,
+  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 +69,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 +121,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 +135,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 +144,36 @@ 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 {
+        status?: string;
+        output?: unknown;
+        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 reason of a run that ended `failed` (ADR-0073). A 404 says nothing about it, so a reason
+  // the page has stays.
+  if (res.ok) dispatch({ kind: "failure", runId, reason: failureReason(body) });
 }
 
 // ---- The two writes (start-run + gate delivery — ADR-0033) --------------------------------------
@@ -215,34 +253,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 +323,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 +365,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 +378,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 +401,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 +410,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 +451,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
   }