@nanobpm/nano-workforce 0.123.1 → 0.124.0

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");
+  });
+});

package/app/deliveryGraphProposals.ts

@@ -0,0 +1,269 @@
+// app/deliveryGraphProposals.ts — the `staged` delivery-graph proposal AGGREGATE (ADR 0005 Decision 7,
+// issue #460). The seam that makes dispatch OPERATOR-ONLY: the agent-facing compile door persists a
+// valid compiled graph HERE as a `staged` proposal and hands the agent only a preview + a navigational
+// `reviewUrl`. There is no run key, token, or dispatch handle in that response — nothing the agent can
+// replay to start a run. A human previews the staged proposal in the cockpit and dispatches it.
+//
+// This dissolves the self-approval hole the old `approvalToken` left open: the token was a REPLAYABLE
+// content digest returned to the same caller, so any holder of the API credential self-approved. By
+// removing the dispatch affordance from the agent surface entirely (capability by absence, not by an
+// auth check), there is nothing to replay — the boundary becomes self-documenting.
+//
+// The pure helpers (`proposalLogicalKey`, `proposalExpiry`, `isProposalExpired`, `buildProposalPreview`,
+// `buildProposalRow`) are DB-free so they unit-test in isolation; `stageProposal` / `getStagedProposal`
+// supply the I/O and the supersede-by-logical-key + TTL semantics.
+
+import type { DataLayer } from "@nanobpm/urban";
+import type {
+  CompileDeliveryGraphResult,
+  DeliveryHumanStop,
+  DeliverySideEffect,
+} from "../nano-generated/api-io.d.ts";
+import { publicBaseUrl } from "./blackboard.ts";
+
+const now = () => new Date().toISOString();
+
+/** The staged-proposal TTL (24h). A staged proposal an operator never dispatches ages out of the
+ * cockpit list at `created_at + TTL`, so the surface only ever shows live, dispatchable proposals. */
+export const DELIVERY_PROPOSAL_TTL_MS = 24 * 60 * 60 * 1000;
+
+/** The NAVIGATIONAL cockpit deep-link to a staged proposal — a pointer the agent can hand the human,
+ * NOT a dispatch handle. Points at the Delivery Graphs cockpit page (where the staged-proposals grid
+ * lives), fragment-scoped to the proposal's digest so the operator can find it. */
+export function proposalReviewUrl(digest: string, base: string = publicBaseUrl()): string {
+  return `${base}/app/pages/delivery-graphs#proposal-${encodeURIComponent(digest)}`;
+}
+
+/** The proposal lifecycle. `staged` = awaiting operator review/dispatch; `superseded` = replaced by a
+ * newer digest for the same logical graph; `dispatched` = the operator launched it; `expired` = it aged
+ * out of its TTL before an operator dispatched it. `superseded`/`dispatched`/`expired` all drop out of
+ * the cockpit's staged list (which filters to `status = 'staged'`). */
+export const DELIVERY_PROPOSAL_STATUSES = ["staged", "superseded", "dispatched", "expired"] as const;
+export type DeliveryProposalStatus = typeof DELIVERY_PROPOSAL_STATUSES[number];
+
+/** One staged delivery-graph proposal — the durable row keyed by content `digest`. `side_effecting`
+ * is a SQLite boolean (0/1); `graph`/`preview` are JSON text columns. */
+export interface DeliveryGraphProposal {
+  digest: string;
+  logical_key: string;
+  title: string | null;
+  /** The original `DeliveryGraph` JSON — retained so the cockpit dispatch action can run the previewed
+   * digest without the agent re-submitting anything. */
+  graph: string;
+  /** The rendered preview JSON (`{ diagram, sideEffects, humanNodes }`), stamped at stage time so the
+   * cockpit list renders without recompiling. */
+  preview: string;
+  node_count: number;
+  human_node_count: number;
+  side_effect_count: number;
+  side_effecting: number;
+  status: DeliveryProposalStatus;
+  created_at: string;
+  updated_at: string;
+  expires_at: string;
+}
+
+/** The rendered preview a staged proposal carries — the operator-facing view of WHAT the graph does
+ * (its diagram, the side effects a dispatch authorises, and where it parks on a person). It carries no
+ * dispatch handle by construction. */
+export interface DeliveryProposalPreview {
+  diagram: string;
+  sideEffects: DeliverySideEffect[];
+  humanNodes: DeliveryHumanStop[];
+}
+
+/** The `delivery_graph_proposals` aggregate accessor — the durable staged-proposal store keyed by
+ * content `digest`. */
+export const deliveryGraphProposals = (data: DataLayer) =>
+  data.table<DeliveryGraphProposal>("delivery_graph_proposals", "digest");
+
+/** The LOGICAL graph identity used to supersede: the graph's `name` (trimmed, when non-blank), else
+ * the content `digest`. A re-compile of a CHANGED graph (new digest) with the SAME name replaces the
+ * prior staged proposal; an unnamed graph is its own logical key (it supersedes only an identical
+ * recompile of itself). */
+export function proposalLogicalKey(name: string | undefined | null, digest: string): string {
+  const trimmed = typeof name === "string" ? name.trim() : "";
+  return trimmed || digest;
+}
+
+/** The TTL horizon for a proposal staged at `createdAt` — `createdAt + DELIVERY_PROPOSAL_TTL_MS`. */
+export function proposalExpiry(createdAtIso: string): string {
+  const created = Date.parse(createdAtIso);
+  const base = Number.isNaN(created) ? Date.now() : created;
+  return new Date(base + DELIVERY_PROPOSAL_TTL_MS).toISOString();
+}
+
+/** Whether a staged proposal has aged out (its `expires_at` is at or before `at`). A corrupt/blank
+ * `expires_at` is treated as expired so a bad row can never linger undismissable in the cockpit. */
+export function isProposalExpired(expiresAtIso: string | null | undefined, at: Date = new Date()): boolean {
+  if (typeof expiresAtIso !== "string" || expiresAtIso.trim() === "") return true;
+  const expires = Date.parse(expiresAtIso);
+  if (Number.isNaN(expires)) return true;
+  return expires <= at.getTime();
+}
+
+/** Extract the operator-facing preview from a successful compile — the diagram, the side effects a
+ * dispatch authorises, and the human stop-points. No BPMN, no digest handle beyond the content
+ * address; a preview, not a dispatch affordance. */
+export function buildProposalPreview(compiled: CompileDeliveryGraphResult): DeliveryProposalPreview {
+  return {
+    diagram: compiled.diagram,
+    sideEffects: compiled.sideEffects,
+    humanNodes: compiled.humanNodes,
+  };
+}
+
+/** Build the durable proposal row for a compiled graph at stage time. `graph` is the original
+ * `DeliveryGraph` JSON (serialised) the cockpit dispatch action re-runs; `createdAt` is preserved
+ * across an idempotent re-stage of a still-live proposal so the TTL stays anchored to the first stage
+ * (omit it — defaulting to now — to re-anchor the TTL when re-staging an already-expired digest). */
+export function buildProposalRow(input: {
+  digest: string;
+  logicalKey: string;
+  title: string | null;
+  graphJson: string;
+  preview: DeliveryProposalPreview;
+  nodeCount: number;
+  humanNodeCount: number;
+  sideEffectCount: number;
+  sideEffecting: boolean;
+  createdAt?: string;
+}): DeliveryGraphProposal {
+  const at = now();
+  const createdAt = input.createdAt ?? at;
+  return {
+    digest: input.digest,
+    logical_key: input.logicalKey,
+    title: input.title,
+    graph: input.graphJson,
+    preview: JSON.stringify(input.preview),
+    node_count: input.nodeCount,
+    human_node_count: input.humanNodeCount,
+    side_effect_count: input.sideEffectCount,
+    side_effecting: input.sideEffecting ? 1 : 0,
+    status: "staged",
+    created_at: createdAt,
+    updated_at: at,
+    expires_at: proposalExpiry(createdAt),
+  };
+}
+
+/** Persist a compiled graph as a `staged` proposal and SUPERSEDE any prior staged proposal for the
+* same logical graph. Idempotent on `digest` (a re-stage of an identical, still-live digest refreshes
+* `updated_at` but preserves `created_at`, so the TTL stays anchored to the first stage; a re-stage of
+* a digest that has already aged out re-anchors the TTL to now so it is dispatchable again). After the
+* upsert, every
+ * OTHER `staged` proposal sharing this `logical_key` is flipped to `superseded` — so the cockpit shows
+ * exactly one live proposal per logical graph (the latest digest the operator would dispatch). The
+ * supersede RECONCILES to the globally-newest staged row (`updated_at`, `digest`-tie-broken) rather than
+ * flipping only rows older than the just-written one, so concurrent stages of two different digests
+ * converge to EXACTLY ONE live proposal — never zero, and never two — regardless of arrival order. */
+export async function stageProposal(data: DataLayer, row: DeliveryGraphProposal): Promise<DeliveryGraphProposal> {
+  const table = deliveryGraphProposals(data);
+  const existing = await table.get(row.digest);
+  const toWrite = existing
+    ? buildProposalRow({
+        digest: row.digest,
+        logicalKey: row.logical_key,
+        title: row.title,
+        graphJson: row.graph,
+        preview: JSON.parse(row.preview),
+        nodeCount: row.node_count,
+        humanNodeCount: row.human_node_count,
+        sideEffectCount: row.side_effect_count,
+        sideEffecting: row.side_effecting === 1,
+        // Re-stage: if the existing row is STILL LIVE, preserve its original stage time so the TTL
+        // stays anchored to the first stage. But if it has already aged out of its TTL (or was
+        // dispatched/superseded long ago), reusing the stale `created_at` would yield a past
+        // `expires_at`, leaving the "re-staged" row immediately non-dispatchable (`getStagedProposal`
+        // rejects it as expired) while the preview claims it is staged. In that case re-anchor the TTL
+        // to now (omit `createdAt`) so a re-proposed digest is genuinely live again.
+        createdAt: isProposalExpired(existing.expires_at) ? undefined : existing.created_at,
+      })
+    : row;
+  if (existing) {
+    const { digest, ...patch } = toWrite;
+    await table.update(row.digest, patch);
+  } else {
+    await table.insert(toWrite);
+  }
+  // Reconcile to EXACTLY ONE live proposal per logical graph: supersede every `staged` row for this
+  // `logical_key` that has a strictly-NEWER staged sibling (by `updated_at`, with a deterministic
+  // `digest` tie-breaker), leaving only the globally-newest live. This is ORDER-INDEPENDENT — it never
+  // references the just-written digest, so it converges to a single live row regardless of the
+  // interleaving of concurrent stages. A supersede pass keyed to "only flip rows older than the one *I*
+  // just wrote" leaves TWO live proposals when an OLDER stage's pass runs AFTER a newer stage already
+  // committed (the older pass won't flip the newer row, and the newer pass ran before the older row
+  // existed) — and an unordered supersede-all leaves ZERO. Anchoring on the newest staged sibling avoids
+  // both: the newest row is never superseded (no newer sibling), so it stays staged throughout the
+  // statement and every older row's `EXISTS` is satisfied by it. Idempotent: a no-op once one row remains.
+  await data
+    .open()
+    .exec(
+      `UPDATE "delivery_graph_proposals" SET "status" = 'superseded', "updated_at" = ? WHERE "logical_key" = ? AND "status" = 'staged' AND EXISTS (SELECT 1 FROM "delivery_graph_proposals" AS "newer" WHERE "newer"."logical_key" = "delivery_graph_proposals"."logical_key" AND "newer"."status" = 'staged' AND ("newer"."updated_at" > "delivery_graph_proposals"."updated_at" OR ("newer"."updated_at" = "delivery_graph_proposals"."updated_at" AND "newer"."digest" > "delivery_graph_proposals"."digest")))`,
+      [now(), row.logical_key],
+    );
+  return toWrite;
+}
+
+/** Load a proposal that is live and dispatchable RIGHT NOW: it exists, is `staged` (not superseded or
+ * already dispatched), and has not aged out of its TTL. Returns null otherwise, so the cockpit
+ * dispatch action refuses a stale/unknown/already-dispatched digest cleanly. */
+export async function getStagedProposal(
+  data: DataLayer,
+  digest: string,
+  at: Date = new Date(),
+): Promise<DeliveryGraphProposal | null> {
+  const row = await deliveryGraphProposals(data).get(digest);
+  if (!row) return null;
+  if (row.status !== "staged") return null;
+  if (isProposalExpired(row.expires_at, at)) return null;
+  return row;
+}
+
+/** Mark a staged proposal `dispatched` once the operator launches it — it drops out of the cockpit's
+ * staged list (the run then shows in the in-flight grid). */
+export async function markProposalDispatched(data: DataLayer, digest: string): Promise<void> {
+  await deliveryGraphProposals(data).update(digest, { status: "dispatched", updated_at: now() });
+}
+
+/** Retire a proposal by flipping it to `expired` — its `graph` payload is unusable (e.g. corrupt JSON
+ * detected at dispatch), so it can never launch. Reuses the terminal `expired` status the sweep already
+ * uses, so a fail-closed retirement drops the row out of the cockpit's staged grid instead of leaving an
+ * undismissable `staged` row that fails every dispatch attempt the same way. */
+export async function markProposalExpired(data: DataLayer, digest: string): Promise<void> {
+  await deliveryGraphProposals(data).update(digest, { status: "expired", updated_at: now() });
+}
+
+/** Age out every `staged` proposal whose TTL has elapsed by flipping it to `expired`, so it drops out
+ * of the cockpit's staged grid (which filters to `status = 'staged'`). The grid's datasource filter can
+ * only express equality/set-membership — not an `expires_at > now` comparison — so an expired-but-still-
+ * `staged` row would otherwise linger in the list indefinitely, only to fail dispatch with "no live
+ * staged proposal". This reconciliation sweep (driven by the poller) is the single writer that realises
+ * the TTL, reusing the canonical `isProposalExpired` predicate so there is no second definition of
+ * "expired". Returns the number of proposals swept. Idempotent: a proposal already terminal (superseded/
+ * dispatched/expired) is left untouched.
+ *
+ * The expiry flip is a GUARDED UPDATE (`... WHERE digest=? AND status='staged'`), not a blind
+ * update-by-key. The initial `find()` and the per-row write are separate statements, so a proposal can
+ * be dispatched (or superseded) in the window between them; a blind `table.update(digest, …)` would
+ * clobber that newer terminal status back to `expired`, silently re-hiding a run the operator just
+ * launched. The `status='staged'` guard makes the write a no-op when the row has already moved on, and
+ * we count only rows that actually changed (`res.changed`) so the returned tally stays honest. */
+export async function sweepExpiredProposals(data: DataLayer, at: Date = new Date()): Promise<number> {
+  const table = deliveryGraphProposals(data);
+  const staged = await table.find({ status: "staged" });
+  const ts = now();
+  const db = data.open();
+  let swept = 0;
+  for (const row of staged) {
+    if (isProposalExpired(row.expires_at, at)) {
+      const res = await db.exec(
+        `UPDATE "delivery_graph_proposals" SET "status" = 'expired', "updated_at" = ? WHERE "digest" = ? AND "status" = 'staged'`,
+        [ts, row.digest],
+      );
+      swept += res.changed;
+    }
+  }
+  return swept;
+}

package/app/deliveryGraphRun.test.ts

@@ -1,9 +1,9 @@
-// Unit coverage for the S5 dispatch-door aggregate (ADR 0005 Decision 7) — the pure decision helpers
-// (the idempotency key, the approval gate, the parked human-label map, the derived parked-node phase),
-// plus the durable at-most-once launch-claim fence (`claimRunForLaunch`) exercised against the real
-// provisioned SQLite data layer so its actual `status <> 'running'` compare-and-swap SQL is validated,
-// not just modelled. The integration test (operations/startDeliveryGraph.integration.test.ts) proves
-// the COMPOSED behaviour at the edge.
+// Unit coverage for the delivery-graph run aggregate (ADR 0005 Decision 7) — the pure decision helpers
+// (the idempotency key, the parked human-label map, the derived parked-node phase), plus the durable
+// at-most-once launch-claim fence (`claimRunForLaunch`) exercised against the real provisioned SQLite
+// data layer so its actual `status <> 'running'` compare-and-swap SQL is validated, not just modelled.
+// The COMPOSED dispatch behaviour at the edge is proven by operations/dispatchDeliveryGraph.test.ts
+// and app/deliveryGraphDispatch.test.ts (the operator dispatch action).
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
@@ -21,8 +21,6 @@ import {
   DELIVERY_PHASE,
   deliveryGraphRuns,
   humanTaskElementId,
-  isDeliveryGraphApproved,
-  parkRunFencedAgainstLaunch,
   parseHumanLabels,
 } from "./deliveryGraphRun.ts";
 import { pollDeliveryGraphPhase } from "./service.ts";
@@ -124,36 +122,6 @@ test("pollDeliveryGraphPhase: a numeric engine processInstanceKey still matches
   });
 });
 
-// ── parkRunFencedAgainstLaunch: the approval-park write never clobbers a launched claim ────────────
-test("parkRunFencedAgainstLaunch: an approval-park write onto a launched `running` claim is a no-op — the at-most-once dispatch fence survives (no clobber back to awaiting-approval, no nulled process_key)", async () => {
-  await withData(async (data) => {
-    const runs = deliveryGraphRuns(data);
-    // A concurrent APPROVED submit already launched: the row is `running` with a live instance key.
-    await runs.insert({ ...claimRow("running"), process_key: "PI-1" });
-    // A racing UNAPPROVED submit that read the pre-launch row now tries to (re-)park it. The guarded
-    // write must refuse to overwrite the launched claim — otherwise a later re-submit double-launches.
-    await parkRunFencedAgainstLaunch(data, true, claimRow("awaiting-approval"));
-    const row = await runs.get("rk");
-    assertEquals(row?.status, "running"); // NOT clobbered back to awaiting-approval
-    assertEquals(row?.process_key, "PI-1"); // instance key preserved
-  });
-});
-
-test("parkRunFencedAgainstLaunch: a first park INSERTs the row; a park onto a still-parked row idempotently re-parks it (metadata refreshed, status stays awaiting-approval)", async () => {
-  await withData(async (data) => {
-    const runs = deliveryGraphRuns(data);
-    // First unapproved submit: no row yet → INSERT.
-    await parkRunFencedAgainstLaunch(data, false, claimRow("awaiting-approval"));
-    assertEquals((await runs.get("rk"))?.status, "awaiting-approval");
-    // A second unapproved submit onto the existing parked row: guarded UPDATE re-parks it (status is
-    // not `running`, so it applies) without duplicating the row.
-    await parkRunFencedAgainstLaunch(data, true, { ...claimRow("awaiting-approval"), digest: "d2" });
-    const row = await runs.get("rk");
-    assertEquals(row?.status, "awaiting-approval");
-    assertEquals(row?.digest, "d2");
-  });
-});
-
 // ── computeRunKey ─────────────────────────────────────────────────────────────
 test("computeRunKey: a non-blank caller key wins; a blank/absent key falls back to the digest", () => {
   assertEquals(computeRunKey("run-1", "digestX"), "run-1");
@@ -164,20 +132,6 @@ test("computeRunKey: a non-blank caller key wins; a blank/absent key falls back
   assertEquals(computeRunKey(undefined, "digestX"), "digestX");
 });
 
-// ── isDeliveryGraphApproved ───────────────────────────────────────────────────
-test("isDeliveryGraphApproved: a non-side-effecting graph needs no approval", () => {
-  assertEquals(isDeliveryGraphApproved(false, null, "d"), true);
-  assertEquals(isDeliveryGraphApproved(false, "wrong", "d"), true);
-});
-
-test("isDeliveryGraphApproved: a side-effecting graph dispatches ONLY with the matching content token", () => {
-  assertEquals(isDeliveryGraphApproved(true, "d", "d"), true);
-  assertEquals(isDeliveryGraphApproved(true, "  d  ", "d"), true); // trimmed
-  assertEquals(isDeliveryGraphApproved(true, "wrong", "d"), false);
-  assertEquals(isDeliveryGraphApproved(true, null, "d"), false);
-  assertEquals(isDeliveryGraphApproved(true, "", "d"), false);
-});
-
 // ── buildHumanLabels / parseHumanLabels ───────────────────────────────────────
 test("buildHumanLabels: maps each human node's compiled user-task element id → its instruction label", async () => {
   const graph = {