@nanobpm/nano-workforce 0.123.2 → 0.125.0

package/CHANGELOG.md

@@ -1,3 +1,23 @@
+# [0.125.0](https://github.com/nanobpm/nano-workforce/compare/v0.124.0...v0.125.0) (2026-08-23)
+
+
+### Features
+
+* **read-model:** declare feature_read_model once via Urban defineReadModel (ADR-0065 step 2) ([#472](https://github.com/nanobpm/nano-workforce/issues/472)) ([6424efb](https://github.com/nanobpm/nano-workforce/commit/6424efbeabec60366567e218f12edd996bb96780)), closes [#422](https://github.com/nanobpm/nano-workforce/issues/422)
+
+# [0.124.0](https://github.com/nanobpm/nano-workforce/compare/v0.123.2...v0.124.0) (2026-08-23)
+
+
+### Bug Fixes
+
+* **cockpit:** anchor supply/transcript endpoints to import.meta.url so the shell finds the API ([#468](https://github.com/nanobpm/nano-workforce/issues/468)) ([4ff4b99](https://github.com/nanobpm/nano-workforce/commit/4ff4b99767b915902be19cdecd5973c1ce6efc4c)), closes [279/#280](https://github.com/nanobpm/nano-workforce/issues/280) [#467](https://github.com/nanobpm/nano-workforce/issues/467)
+* **migrations:** grandfather prefix 075 collision to unblock main + releases ([#471](https://github.com/nanobpm/nano-workforce/issues/471)) ([508194e](https://github.com/nanobpm/nano-workforce/commit/508194e7be0f58ba3f12d2b67d4d6212d243c609)), closes [#458](https://github.com/nanobpm/nano-workforce/issues/458) [460/#463](https://github.com/nanobpm/nano-workforce/issues/463) [#357](https://github.com/nanobpm/nano-workforce/issues/357) [#470](https://github.com/nanobpm/nano-workforce/issues/470)
+
+
+### Features
+
+* **delivery-graph:** make dispatch operator-only ([#460](https://github.com/nanobpm/nano-workforce/issues/460)) ([#463](https://github.com/nanobpm/nano-workforce/issues/463)) ([cd6d2b8](https://github.com/nanobpm/nano-workforce/commit/cd6d2b819b32c5c7daf047dbb6e077a26d4b09e6))
+
 ## [0.123.2](https://github.com/nanobpm/nano-workforce/compare/v0.123.1...v0.123.2) (2026-08-22)
 
 

package/README.md

@@ -254,11 +254,15 @@ run an **arbitrary, heterogeneous, cross-repo, partly-human delivery graph** —
 the just-published version*. You author the graph as **JSON over a closed node vocabulary**
 (`agent` | `wait` | `human` | `connector`) — never BPMN or code — whose edges are
 **discovered facts** (`from: "<node>.<fact>"`). A deterministic compiler turns it into an
-engine-native process; a human approves the rendered preview before any side effect runs.
-
-Two doors: a **pure** `POST /app/api/actions/compile-delivery-graph` (validate + preview,
-side-effect-free — hammer it while drafting) and a **gated, idempotent**
-`POST /app/api/actions/start/delivery-graph` (approve → dispatch).
+engine-native process; a human previews the staged proposal and dispatches it from the
+cockpit before any side effect runs.
+
+Two doors — and the second is **operator-only** (issue #460): a
+`POST /app/api/actions/compile-delivery-graph` on the agent surface that validates + previews
+the graph and **stages** it as a proposal (the agent surface ends there — no run key or token
+comes back), and a `POST /app/api/actions/delivery-graph/dispatch` the **cockpit** uses to
+dispatch a staged proposal by its content `digest` (idempotent, at-most-once). There is no
+agent `start` door to replay — the human clicking Dispatch in the cockpit is the approval.
 
 The agent guide served at `GET /app/api/agent` documents the full vocabulary, both
 operation contracts, and a complete worked example — see §9 there, or point your coding

package/app/deliveryGraphDispatch.test.ts

@@ -0,0 +1,143 @@
+// Unit coverage for `dispatchDeliveryGraphRun` (app/deliveryGraphDispatch.ts) — the retained
+// delivery-graph DISPATCH core extracted out of the removed agent `start` door (ADR 0005 Decision 7,
+// issue #460). It has NO approval gate: the authorization lives in the fact that only the cockpit
+// dispatch seam reaches this code (never the agent surface). What it DOES keep is the durable
+// at-most-once launch fence + idempotency short-circuit, so a double-dispatch never double-launches a
+// graph's side effects. These tests drive it against an in-memory app/data/engine faithful to the run
+// aggregate's PRIMARY KEY fence and the guarded raw UPDATE the claim issues.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import type { AppApi } from "@nanobpm/urban";
+import { dispatchDeliveryGraphRun } from "./deliveryGraphDispatch.ts";
+import { noopLog } from "../test/log.ts";
+
+function makeApp() {
+  const tables = new Map<string, Record<string, unknown>[]>();
+  const started: { processDefinitionId: string }[] = [];
+  const table = (name: string, key: string) => {
+    const rows =
+      tables.get(name) ??
+      (() => {
+        const fresh: Record<string, unknown>[] = [];
+        tables.set(name, fresh);
+        return fresh;
+      })();
+    return {
+      get: (k: unknown) => Promise.resolve(rows.find((r) => r[key] === k) ?? null),
+      find: (q: Record<string, unknown>) =>
+        Promise.resolve(rows.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
+      all: () => Promise.resolve([...rows]),
+      insert: (r: Record<string, unknown>) => {
+        if (rows.some((existing) => existing[key] === r[key])) {
+          return Promise.reject(new Error(`UNIQUE constraint failed: ${name}.${key}`));
+        }
+        rows.push(r);
+        return Promise.resolve(r);
+      },
+      update: (k: unknown, patch: Record<string, unknown>) => {
+        const row = rows.find((r) => r[key] === k);
+        if (row) Object.assign(row, patch);
+        return Promise.resolve(row);
+      },
+      delete: (k: unknown) => {
+        const i = rows.findIndex((r) => r[key] === k);
+        if (i >= 0) rows.splice(i, 1);
+        return Promise.resolve();
+      },
+    };
+  };
+  const app = {
+    data: {
+      table,
+      open: () => ({
+        exec: (sql: string, params: unknown[]) =>
+          Promise.resolve().then(() => {
+            const cols = [...sql.matchAll(/"(\w+)"\s*=\s*\?/g)].map((m) => m[1]);
+            const runKey = params[params.length - 1];
+            const rows = tables.get("delivery_graph_runs") ?? [];
+            const row = rows.find((r) => r["run_key"] === runKey);
+            if (row && row["status"] !== "running") {
+              for (let i = 0; i < cols.length - 1; i++) row[cols[i]] = params[i];
+              return { changed: 1 };
+            }
+            return { changed: 0 };
+          }),
+      }),
+    },
+    engine: {
+      deployResources: () => Promise.resolve([]),
+      createInstance: (req: { processDefinitionId: string }) => {
+        started.push(req);
+        return Promise.resolve({ processInstanceKey: "PI-1", processDefinitionId: req.processDefinitionId });
+      },
+    },
+    log: noopLog(),
+  } as unknown as AppApi;
+  return { app, started, runs: () => tables.get("delivery_graph_runs") ?? [] };
+}
+
+const HUMAN_ONLY = {
+  name: "manual gate",
+  nodes: [{ id: "ack", kind: "human", human: { prompt: "click done" } }],
+};
+const SIDE_EFFECTING = {
+  name: "release runbook",
+  nodes: [
+    { id: "open-b", kind: "agent", agent: { jobType: "senior:demo", prompt: "merge #B" } },
+    { id: "publish", kind: "human", human: { prompt: "run the manual OTP publish" } },
+  ],
+  edges: [{ from: "open-b", to: "publish" }],
+};
+
+test("dispatchDeliveryGraphRun: a human-only graph launches straight away (running), one engine instance", async () => {
+  const { app, started, runs } = makeApp();
+  const res = await dispatchDeliveryGraphRun(app, HUMAN_ONLY);
+  assertEquals(res.ok, true);
+  if (!res.ok) return;
+  assertEquals(res.status, "running");
+  assertEquals(res.alreadyRunning, false);
+  assertEquals(res.sideEffecting, false);
+  assertEquals(started.length, 1);
+  assertEquals(runs()[0].status, "running");
+});
+
+test("dispatchDeliveryGraphRun: a side-effecting graph dispatches with NO approval token — the operator seam IS the approval", async () => {
+  const { app, started, runs } = makeApp();
+  const res = await dispatchDeliveryGraphRun(app, SIDE_EFFECTING);
+  assertEquals(res.ok, true);
+  if (!res.ok) return;
+  assertEquals(res.status, "running");
+  assertEquals(res.sideEffecting, true);
+  assertEquals(started.length, 1);
+  assertEquals(runs()[0].status, "running");
+});
+
+test("dispatchDeliveryGraphRun: a re-dispatch of a still-running run short-circuits (alreadyRunning) — the side effect launches at most once", async () => {
+  const { app, started } = makeApp();
+  const first = await dispatchDeliveryGraphRun(app, SIDE_EFFECTING);
+  assert(first.ok);
+  const second = await dispatchDeliveryGraphRun(app, SIDE_EFFECTING);
+  assertEquals(second.ok, true);
+  if (!second.ok) return;
+  assertEquals(second.alreadyRunning, true);
+  assertEquals(started.length, 1); // never a second launch
+});
+
+test("dispatchDeliveryGraphRun: an explicit idempotency key forces a distinct run row", async () => {
+  const { app, started } = makeApp();
+  await dispatchDeliveryGraphRun(app, HUMAN_ONLY);
+  await dispatchDeliveryGraphRun(app, HUMAN_ONLY, { runKey: "second-run" });
+  assertEquals(started.length, 2);
+});
+
+test("dispatchDeliveryGraphRun: a malformed graph → ok:false with path-qualified errors, nothing launched", async () => {
+  const { app, started } = makeApp();
+  const res = await dispatchDeliveryGraphRun(app, { name: "empty", nodes: [] });
+  assertEquals(res.ok, false);
+  if (res.ok) return;
+  assert(Array.isArray(res.errors) && res.errors.length > 0);
+  for (const e of res.errors) {
+    assert(typeof e.path === "string" && typeof e.message === "string");
+  }
+  assertEquals(started.length, 0);
+});

package/app/deliveryGraphDispatch.ts

@@ -0,0 +1,168 @@
+// app/deliveryGraphDispatch.ts — the delivery-graph DISPATCH core (ADR 0005 Decision 7, issue #460).
+// This is the retained run-launch logic (compile → content-address → idempotent at-most-once claim →
+// deploy+start the S4 runner → stamp the instance) extracted out of the removed agent `start` door so
+// it is invoked ONLY from the cockpit dispatch action — never an agent-callable operation.
+//
+// The old `start` door gated dispatch on a REPLAYABLE `approvalToken` (the content digest handed back
+// to the same caller), which let any holder of the API credential self-approve. Under issue #460 the
+// human clicking Dispatch in the cockpit IS the approval — so there is NO approval gate here; the
+// authorization lives in the fact that only the cockpit dispatch seam reaches this code, not the agent
+// surface. What IS retained is the durable at-most-once launch fence (`claimRunForLaunch`) and the
+// idempotency short-circuit, so a double-click or a re-dispatch never double-launches a graph's side
+// effects.
+
+import type { AppApi } from "@nanobpm/urban";
+import type { DeliveryGraph } from "../nano-generated/api-io.d.ts";
+import { validateDeliveryGraph } from "./deliveryGraph.ts";
+import { compileDeliveryGraph } from "./deliveryGraphCompiler.ts";
+import {
+  buildDeliveryGraphRunRow,
+  buildHumanLabels,
+  claimRunForLaunch,
+  computeRunKey,
+  DELIVERY_PHASE,
+  deliveryGraphRuns,
+} from "./deliveryGraphRun.ts";
+import { deliveryGraphDigest, runDeliveryGraph } from "./deliveryRunner.ts";
+
+/** The outcome of a dispatch attempt — mirrors the retained run lifecycle. `ok:false` carries the
+ * path-qualified compile/validation errors (a staged graph should always recompile, but a corrupt
+ * stored graph is refused cleanly rather than throwing). */
+export type DispatchDeliveryGraphResult =
+  | {
+      ok: true;
+      status: "running";
+      runKey: string;
+      digest: string;
+      sideEffecting: boolean;
+      alreadyRunning: boolean;
+      processInstanceKey?: string;
+      processDefinitionId?: string;
+    }
+  | { ok: false; errors: { path: string; message: string }[] };
+
+/** Dispatch a delivery graph as a running engine-native process — the operator action. Re-validates
+ * and re-compiles the (already-staged) graph to derive its content digest + run-row shape, then
+ * launches it through the durable at-most-once fence. Idempotent: a re-dispatch of an already-running
+ * run short-circuits with `alreadyRunning` instead of double-launching. */
+export async function dispatchDeliveryGraphRun(
+  app: Pick<AppApi, "data" | "engine" | "log">,
+  graph: unknown,
+  options: { runKey?: string | null; title?: string | null } = {},
+): Promise<DispatchDeliveryGraphResult> {
+  const validationErrors = validateDeliveryGraph(graph);
+  if (validationErrors.length > 0) {
+    return { ok: false, errors: validationErrors };
+  }
+  // The graph passed the semantic validator above, so it is safe to narrow to the typed contract.
+  // biome-ignore lint/plugin: validated external body narrowed to its contract after validateDeliveryGraph
+  const typedGraph = graph as DeliveryGraph;
+  const compiled = await compileDeliveryGraph(typedGraph);
+  if (!compiled.ok) {
+    return { ok: false, errors: compiled.errors };
+  }
+
+  const digest = deliveryGraphDigest(compiled.bpmn);
+  const runKey = computeRunKey(options.runKey, digest);
+  const sideEffecting = compiled.sideEffects.length > 0;
+  const explicitTitle = typeof options.title === "string" && options.title.trim() !== "" ? options.title.trim() : "";
+  const graphName = typeof typedGraph.name === "string" && typedGraph.name.trim() !== "" ? typedGraph.name.trim() : "";
+  const title = explicitTitle || graphName || runKey;
+  const runs = deliveryGraphRuns(app.data);
+
+  // Idempotency short-circuit — a re-dispatch onto a still-running run does NOT double-launch.
+  const existing = await runs.get(runKey);
+  if (existing && existing.status === "running") {
+    app.log.info("dispatch-delivery-graph short-circuit: already running", { runKey });
+    return {
+      ok: true,
+      status: "running",
+      runKey,
+      digest: existing.digest,
+      sideEffecting: existing.side_effecting === 1,
+      alreadyRunning: true,
+      processInstanceKey: existing.process_key ?? undefined,
+      processDefinitionId: existing.process_definition_id ?? undefined,
+    };
+  }
+
+  const rowBase = {
+    runKey,
+    digest,
+    sideEffecting,
+    nodeCount: compiled.resolved.nodes.length,
+    humanNodeCount: compiled.humanNodes.length,
+    sideEffectCount: compiled.sideEffects.length,
+    title,
+    humanLabels: buildHumanLabels(compiled),
+    createdAt: existing?.created_at,
+  };
+
+  // Claim the run durably BEFORE the side effect (the at-most-once dispatch fence). A losing racer
+  // never reaches `runDeliveryGraph` — it re-reads the winner's row and short-circuits.
+  const claim = buildDeliveryGraphRunRow({ ...rowBase, status: "running", phase: DELIVERY_PHASE.RUNNING, processKey: null });
+  const wonClaim = await claimRunForLaunch(app.data, Boolean(existing), claim);
+  if (!wonClaim) {
+    const won = await runs.get(runKey);
+    app.log.info("dispatch-delivery-graph short-circuit: launch claim raced a concurrent dispatch", { runKey });
+    return {
+      ok: true,
+      status: "running",
+      runKey,
+      digest: won?.digest ?? digest,
+      sideEffecting: won ? won.side_effecting === 1 : sideEffecting,
+      alreadyRunning: true,
+      processInstanceKey: won?.process_key ?? undefined,
+      processDefinitionId: won?.process_definition_id ?? undefined,
+    };
+  }
+  if (existing) {
+    const { run_key, created_at, ...patch } = claim;
+    await runs.update(runKey, patch);
+  }
+
+  // Launch — deploy + start the compiled definition. On ANY launch failure flip the claimed row to
+  // `failed` so no null-process_key `running` row is ever stranded.
+  const markClaimFailed = async () => {
+    const failed = buildDeliveryGraphRunRow({ ...rowBase, status: "failed", phase: DELIVERY_PHASE.FAILED, processKey: null });
+    const { run_key, created_at, ...patch } = failed;
+    await runs.update(runKey, patch);
+  };
+  let launched: Awaited<ReturnType<typeof runDeliveryGraph>>;
+  try {
+    launched = await runDeliveryGraph(app.engine, typedGraph, { runKey });
+  } catch (err) {
+    await markClaimFailed();
+    app.log.error("dispatch-delivery-graph launch threw", { runKey });
+    throw err;
+  }
+  if (!launched.ok) {
+    await markClaimFailed();
+    app.log.error("dispatch-delivery-graph launch failed", { runKey, count: launched.errors.length });
+    return { ok: false, errors: launched.errors };
+  }
+
+  // Stamp the started instance key onto the claimed row.
+  {
+    const running = buildDeliveryGraphRunRow({
+      ...rowBase,
+      status: "running",
+      phase: DELIVERY_PHASE.RUNNING,
+      processKey: launched.handle.processInstanceKey,
+      processDefinitionId: launched.handle.processDefinitionId,
+    });
+    const { run_key, created_at, ...patch } = running;
+    await runs.update(runKey, patch);
+  }
+  app.log.info("delivery graph dispatched", { runKey, processInstanceKey: launched.handle.processInstanceKey });
+  return {
+    ok: true,
+    status: "running",
+    runKey,
+    digest,
+    sideEffecting,
+    alreadyRunning: false,
+    processInstanceKey: launched.handle.processInstanceKey,
+    processDefinitionId: launched.handle.processDefinitionId,
+  };
+}

package/app/deliveryGraphProposals.test.ts

@@ -0,0 +1,267 @@
+// Unit coverage for the `staged` delivery-graph proposal aggregate (app/deliveryGraphProposals.ts,
+// ADR 0005 Decision 7, issue #460). Two layers: the PURE helpers (logical key, TTL horizon, expiry,
+// review-url, row builder) tested in isolation, and the I/O (`stageProposal` supersede-by-logical-key
+// + idempotent re-stage; `getStagedProposal` staged-and-live gate; `markProposalDispatched`) exercised
+// against the REAL provisioned SQLite data layer so the raw supersede UPDATE is validated, not modelled.
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import type { DataLayer } from "@nanobpm/urban";
+import { bootTestApp } from "@nanobpm/urban-testkit";
+import {
+  buildProposalRow,
+  DELIVERY_PROPOSAL_TTL_MS,
+  deliveryGraphProposals,
+  getStagedProposal,
+  isProposalExpired,
+  markProposalDispatched,
+  proposalExpiry,
+  proposalLogicalKey,
+  proposalReviewUrl,
+  stageProposal,
+  sweepExpiredProposals,
+} from "./deliveryGraphProposals.ts";
+
+const APP_ROOT = resolve(import.meta.dirname, "..");
+
+async function withData(fn: (data: DataLayer) => Promise<void>): Promise<void> {
+  const dir = mkdtempSync(join(tmpdir(), "nwf-dgprop-"));
+  const app = await bootTestApp(APP_ROOT, { env: { NANO_APP_DB_URL: `file:${join(dir, "app.db")}` } });
+  try {
+    await fn(app.db);
+  } finally {
+    await app.stop?.();
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+const row = (over: Partial<Parameters<typeof buildProposalRow>[0]> = {}) =>
+  buildProposalRow({
+    digest: "d1",
+    logicalKey: "runbook",
+    title: "runbook",
+    graphJson: JSON.stringify({ name: "runbook", nodes: [] }),
+    preview: { diagram: "flowchart", sideEffects: [], humanNodes: [] },
+    nodeCount: 1,
+    humanNodeCount: 0,
+    sideEffectCount: 0,
+    sideEffecting: false,
+    ...over,
+  });
+
+// ── pure helpers ──────────────────────────────────────────────────────────────
+test("proposalLogicalKey: a non-blank name wins; a blank/absent name falls back to the digest", () => {
+  assertEquals(proposalLogicalKey("runbook", "dX"), "runbook");
+  assertEquals(proposalLogicalKey("  runbook  ", "dX"), "runbook");
+  assertEquals(proposalLogicalKey("", "dX"), "dX");
+  assertEquals(proposalLogicalKey("   ", "dX"), "dX");
+  assertEquals(proposalLogicalKey(null, "dX"), "dX");
+  assertEquals(proposalLogicalKey(undefined, "dX"), "dX");
+});
+
+test("proposalExpiry: is createdAt + TTL; a corrupt createdAt anchors to now", () => {
+  const created = "2024-01-01T00:00:00.000Z";
+  assertEquals(proposalExpiry(created), new Date(Date.parse(created) + DELIVERY_PROPOSAL_TTL_MS).toISOString());
+  const now = Date.now();
+  const fallback = Date.parse(proposalExpiry("not-a-date"));
+  assert(Math.abs(fallback - (now + DELIVERY_PROPOSAL_TTL_MS)) < 5000);
+});
+
+test("isProposalExpired: past → true, future → false, blank/corrupt → true (fail-closed)", () => {
+  const at = new Date("2024-06-01T00:00:00.000Z");
+  assertEquals(isProposalExpired("2024-05-31T23:59:59.000Z", at), true);
+  assertEquals(isProposalExpired("2024-06-01T00:00:01.000Z", at), false);
+  assertEquals(isProposalExpired(at.toISOString(), at), true); // at the horizon = expired
+  assertEquals(isProposalExpired(null, at), true);
+  assertEquals(isProposalExpired("", at), true);
+  assertEquals(isProposalExpired("garbage", at), true);
+});
+
+test("proposalReviewUrl: a navigational deep-link to the cockpit page — NOT a dispatch endpoint", () => {
+  const url = proposalReviewUrl("abc123", "https://cockpit.example");
+  assertEquals(url, "https://cockpit.example/app/pages/delivery-graphs#proposal-abc123");
+  assert(!/\/actions\//.test(url), "reviewUrl points at a page, never an API action");
+});
+
+test("buildProposalRow: stamps status staged, boolean→0/1, and TTL from createdAt", () => {
+  const r = row({ sideEffecting: true, createdAt: "2024-01-01T00:00:00.000Z" });
+  assertEquals(r.status, "staged");
+  assertEquals(r.side_effecting, 1);
+  assertEquals(r.created_at, "2024-01-01T00:00:00.000Z");
+  assertEquals(r.expires_at, proposalExpiry("2024-01-01T00:00:00.000Z"));
+});
+
+// ── I/O: stage / supersede / get / dispatch ────────────────────────────────────
+test("stageProposal: stages a proposal that getStagedProposal then returns as live", async () => {
+  await withData(async (data) => {
+    await stageProposal(data, row());
+    const live = await getStagedProposal(data, "d1");
+    assert(live);
+    assertEquals(live?.status, "staged");
+  });
+});
+
+test("stageProposal: a re-stage of an identical, STILL-LIVE digest is idempotent — one row, created_at (TTL anchor) preserved", async () => {
+  await withData(async (data) => {
+    const firstStage = new Date().toISOString(); // live: expires_at is in the future
+    await stageProposal(data, row({ createdAt: firstStage }));
+    await stageProposal(data, row({ createdAt: "2030-01-01T00:00:00.000Z" })); // a later re-stage
+    const rows = await deliveryGraphProposals(data).all();
+    assertEquals(rows.length, 1);
+    assertEquals(rows[0].created_at, firstStage); // first (live) stage wins the TTL anchor
+  });
+});
+
+test("stageProposal: a re-stage of an EXPIRED digest RE-ANCHORS the TTL so it is dispatchable again", async () => {
+  await withData(async (data) => {
+    // First stage long ago so its TTL has already elapsed (expires_at is in the past).
+    await stageProposal(data, row({ createdAt: "2024-01-01T00:00:00.000Z" }));
+    assertEquals(await getStagedProposal(data, "d1"), null); // aged out — not dispatchable
+
+    await stageProposal(data, row({ createdAt: "2030-01-01T00:00:00.000Z" })); // re-propose the same bytes
+    const rows = await deliveryGraphProposals(data).all();
+    assertEquals(rows.length, 1);
+    // The stale created_at must NOT be reused (that would keep expires_at in the past); the re-stage
+    // re-anchors the TTL to now, so the re-proposed digest is genuinely live and dispatchable again.
+    assert(!isProposalExpired(rows[0].expires_at), "re-staged expired proposal must have a future TTL");
+    const live = await getStagedProposal(data, "d1");
+    assert(live, "a re-staged (previously expired) proposal is dispatchable again");
+    assertEquals(live?.status, "staged");
+  });
+});
+
+test("stageProposal: a new digest for the SAME logical key supersedes the prior staged proposal", async () => {
+  await withData(async (data) => {
+    await stageProposal(data, row({ digest: "d1" }));
+    await stageProposal(data, row({ digest: "d2" })); // same logical_key "runbook", new digest
+    assertEquals((await deliveryGraphProposals(data).get("d1"))?.status, "superseded");
+    assertEquals((await deliveryGraphProposals(data).get("d2"))?.status, "staged");
+    // The superseded digest is no longer live/dispatchable.
+    assertEquals(await getStagedProposal(data, "d1"), null);
+    assert(await getStagedProposal(data, "d2"));
+  });
+});
+
+test("stageProposal: proposals with DIFFERENT logical keys coexist — supersede is scoped per logical graph", async () => {
+  await withData(async (data) => {
+    await stageProposal(data, row({ digest: "d1", logicalKey: "runbook-a" }));
+    await stageProposal(data, row({ digest: "d2", logicalKey: "runbook-b" }));
+    assertEquals((await deliveryGraphProposals(data).get("d1"))?.status, "staged");
+    assertEquals((await deliveryGraphProposals(data).get("d2"))?.status, "staged");
+  });
+});
+
+test("stageProposal: reconciles to EXACTLY ONE live proposal — an older stage whose supersede pass runs AFTER a newer stage neither clobbers it (zero) nor coexists with it (two)", async () => {
+  await withData(async (data) => {
+    const table = deliveryGraphProposals(data);
+    // A NEWER stage (d2) has already committed its row for logical_key "runbook" — the winner of a
+    // concurrent double-stage, with a later `updated_at`. Its TTL is live (createdAt defaults to now).
+    const newer = row({ digest: "d2" });
+    newer.updated_at = "2999-01-01T00:00:00.000Z";
+    await table.insert(newer);
+    // Now the OLDER racer (d1) runs its supersede pass LAST. An "only-flip-rows-older-than-me" pass would
+    // leave BOTH d1 and d2 staged (it won't flip the newer d2, and d2's own pass ran before d1 existed);
+    // an unordered supersede-all would flip d2 too, leaving ZERO. Reconciling to the newest sibling must
+    // supersede d1 (it has a newer staged sibling d2) and keep exactly d2 live.
+    await stageProposal(data, row({ digest: "d1" }));
+    assertEquals((await table.get("d2"))?.status, "staged", "the newer proposal must survive the older stage's supersede");
+    assertEquals((await table.get("d1"))?.status, "superseded", "the older stage must supersede itself when a newer staged sibling exists");
+    // EXACTLY ONE live proposal remains for the logical key — never zero, never two.
+    const stillStaged = (await table.all()).filter((r) => r.status === "staged" && r.logical_key === "runbook");
+    assertEquals(stillStaged.length, 1, "exactly one live proposal per logical graph");
+    assertEquals(stillStaged[0]?.digest, "d2", "the globally-newest stage is the one that survives");
+  });
+});
+
+test("getStagedProposal: an EXPIRED staged proposal is not live", async () => {
+  await withData(async (data) => {
+    await stageProposal(data, row());
+    const past = new Date(Date.now() - 1000);
+    // Query from a time AFTER its TTL horizon.
+    const future = new Date(Date.now() + DELIVERY_PROPOSAL_TTL_MS + 1000);
+    assert(await getStagedProposal(data, "d1", past));
+    assertEquals(await getStagedProposal(data, "d1", future), null);
+  });
+});
+
+test("markProposalDispatched: a dispatched proposal is no longer live", async () => {
+  await withData(async (data) => {
+    await stageProposal(data, row());
+    await markProposalDispatched(data, "d1");
+    assertEquals((await deliveryGraphProposals(data).get("d1"))?.status, "dispatched");
+    assertEquals(await getStagedProposal(data, "d1"), null);
+  });
+});
+
+test("sweepExpiredProposals: flips aged-out staged proposals to `expired` so they drop out of the cockpit grid", async () => {
+  await withData(async (data) => {
+    // Two staged proposals with different logical keys so neither supersedes the other.
+    await stageProposal(data, row({ digest: "d1", logicalKey: "a", createdAt: "2024-01-01T00:00:00.000Z" }));
+    await stageProposal(data, row({ digest: "d2", logicalKey: "b" }));
+    // Sweep from a time past d1's TTL horizon but before d2's.
+    const at = new Date(Date.parse("2024-01-01T00:00:00.000Z") + DELIVERY_PROPOSAL_TTL_MS + 1000);
+    const swept = await sweepExpiredProposals(data, at);
+    assertEquals(swept, 1);
+    assertEquals((await deliveryGraphProposals(data).get("d1"))?.status, "expired");
+    assertEquals((await deliveryGraphProposals(data).get("d2"))?.status, "staged");
+    // Idempotent: a re-sweep at the same instant flips nothing more.
+    assertEquals(await sweepExpiredProposals(data, at), 0);
+  });
+});
+
+test("sweepExpiredProposals: leaves superseded/dispatched proposals untouched (only `staged` is swept)", async () => {
+  await withData(async (data) => {
+    await stageProposal(data, row({ digest: "d1", createdAt: "2024-01-01T00:00:00.000Z" }));
+    await markProposalDispatched(data, "d1");
+    const at = new Date(Date.parse("2024-01-01T00:00:00.000Z") + DELIVERY_PROPOSAL_TTL_MS + 1000);
+    assertEquals(await sweepExpiredProposals(data, at), 0);
+    assertEquals((await deliveryGraphProposals(data).get("d1"))?.status, "dispatched");
+  });
+});
+
+test("sweepExpiredProposals: a dispatch racing between the read and the write is NOT clobbered back to `expired`", async () => {
+  await withData(async (data) => {
+    // One aged-out staged proposal — the sweep's `find()` will see it as `staged`.
+    await stageProposal(data, row({ digest: "d1", createdAt: "2024-01-01T00:00:00.000Z" }));
+    const at = new Date(Date.parse("2024-01-01T00:00:00.000Z") + DELIVERY_PROPOSAL_TTL_MS + 1000);
+
+    // Wrap the data layer so that, in the window between the sweep's `find()` and its per-row guarded
+    // `exec`, the operator dispatches the proposal (status: staged -> dispatched). A blind
+    // update-by-key would clobber that dispatch back to `expired`; the guarded UPDATE
+    // (`WHERE status='staged'`) must instead no-op and leave the row `dispatched`.
+    let raced = false;
+    const racyData = new Proxy(data, {
+      get(target, prop, receiver) {
+        if (prop === "open") {
+          return () => {
+            const src = target.open();
+            return new Proxy(src, {
+              get(s, p) {
+                if (p === "exec") {
+                  return async (sql: string, params?: unknown[]) => {
+                    if (!raced) {
+                      raced = true;
+                      await markProposalDispatched(data, "d1");
+                    }
+                    return s.exec(sql, params);
+                  };
+                }
+                const v = Reflect.get(s, p, s);
+                return typeof v === "function" ? v.bind(s) : v;
+              },
+            });
+          };
+        }
+        const v = Reflect.get(target, prop, target);
+        return typeof v === "function" ? v.bind(target) : v;
+      },
+    });
+
+    const swept = await sweepExpiredProposals(racyData as DataLayer, at);
+    assert(raced, "the racing dispatch should have fired");
+    assertEquals(swept, 0);
+    assertEquals((await deliveryGraphProposals(data).get("d1"))?.status, "dispatched");
+  });
+});