@nanobpm/nano-workforce 0.159.0 → 0.159.1

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.159.1](https://github.com/nanobpm/nano-workforce/compare/v0.159.0...v0.159.1) (2026-08-29)
+
+### Bug Fixes
+
+* **delivery-graph:** read-after-write consistency for listStagedProposals (S2) ([#617](https://github.com/nanobpm/nano-workforce/issues/617)) ([bd0246c](https://github.com/nanobpm/nano-workforce/commit/bd0246cc81241041320aa483b0a0789f5e372031)), closes [#608](https://github.com/nanobpm/nano-workforce/issues/608)
+
 ## [0.159.0](https://github.com/nanobpm/nano-workforce/compare/v0.158.1...v0.159.0) (2026-08-29)
 
 ### Features

package/app/deliveryGraphProposals.test.ts

@@ -15,6 +15,7 @@ import {
   DELIVERY_PROPOSAL_TTL_MS,
   deliveryGraphProposals,
   getStagedProposal,
+  isLiveStaged,
   isProposalExpired,
   markProposalDismissed,
   markProposalDispatched,
@@ -82,6 +83,21 @@ test("isProposalExpired: past → true, future → false, blank/corrupt → true
   assertEquals(isProposalExpired("garbage", at), true);
 });
 
+test("isLiveStaged: the ONE liveness predicate — only a `staged`, not-yet-expired row is live (#608)", () => {
+  const at = new Date("2024-06-01T00:00:00.000Z");
+  const live = row({ createdAt: "2024-05-31T23:00:00.000Z" }); // staged, TTL a day out → live
+  assertEquals(isLiveStaged(live, at), true);
+  // A future-created staged row is trivially live too (TTL further out).
+  assertEquals(isLiveStaged(row(), new Date()), true);
+  // Every non-`staged` status is NOT live, regardless of TTL.
+  for (const status of ["superseded", "dispatched", "expired", "dismissed"] as const) {
+    assertEquals(isLiveStaged({ ...live, status }, at), false);
+  }
+  // A `staged` row whose TTL has elapsed is NOT live (mirrors isProposalExpired, fail-closed).
+  assertEquals(isLiveStaged({ ...live, expires_at: "2024-05-30T00:00:00.000Z" }, at), false);
+  assertEquals(isLiveStaged({ ...live, expires_at: "" }, at), false);
+});
+
 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");

package/app/deliveryGraphProposals.ts

@@ -207,9 +207,25 @@ export async function stageProposal(data: DataLayer, row: DeliveryGraphProposal)
   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. */
+/** The ONE definition of "a live, dispatchable-RIGHT-NOW staged proposal" (issue #608): the row is
+ * `staged` (not superseded / dispatched / expired / dismissed) AND has not aged out of its TTL. This is
+ * the SINGLE SOURCE OF TRUTH the digest read (`getStagedProposal`), the list read
+ * (`listStagedProposals`), and — through them — the cockpit App-View, the dispatch/preview/dismiss
+ * doors, and the MCP `listStagedProposals` tool all resolve liveness through, so no two readers can ever
+ * drift on which rows are live (AGENTS.md "Derivation over duplication"). A read-after-write from
+ * `compileDeliveryGraph` is trustworthy because this predicate is evaluated over the SAME durable
+ * `delivery_graph_proposals` store the compile door commits the row to (the app's single default
+ * `app.data` source) — a freshly staged row (`status: 'staged'`, `expires_at` a full TTL in the future)
+ * is live by construction, with no projection/read-model between the write and the read to lag behind. */
+export function isLiveStaged(row: DeliveryGraphProposal, at: Date = new Date()): boolean {
+  return row.status === "staged" && !isProposalExpired(row.expires_at, at);
+}
+
+/** Load a proposal that is live and dispatchable RIGHT NOW: it exists and satisfies {@link isLiveStaged}
+ * (it 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. Reads the authoritative `delivery_graph_proposals` row by primary key from the same
+ * `app.data` store the compile door stages into — a read-your-writes lookup, no read-model in between. */
 export async function getStagedProposal(
   data: DataLayer,
   digest: string,
@@ -217,24 +233,28 @@ export async function getStagedProposal(
 ): 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;
+  return isLiveStaged(row, at) ? row : null;
 }
 
-/** Every LIVE staged proposal — `status = 'staged'` AND not aged out of its TTL — newest first. The
- * staged App-View (`pages/delivery-graphs/staged.mount.js`) polls this to render the Preview-DI +
- * Dispatch list. Mirrors `getStagedProposal`'s freshness guard (`isProposalExpired`) so an
- * expired-but-not-yet-swept row is never offered for preview/dispatch, unlike a raw
- * `status = 'staged'` datasource filter which cannot express a `expires_at > now` cutoff and so lingers
- * an aged-out row until the sweep realises the TTL. Read-only; no write. */
+/** Every LIVE staged proposal — {@link isLiveStaged} (`status = 'staged'` AND not aged out of its TTL) —
+ * newest first. The staged App-View (`pages/delivery-graphs/staged.mount.js`) and the MCP
+ * `listStagedProposals` tool both poll THIS door to render/answer the Preview-DI + Dispatch list.
+ *
+ * READ-AFTER-WRITE GUARANTEE (issue #608). The list is served by a fresh query against the authoritative
+ * `delivery_graph_proposals` table on the app's single default `app.data` source — the SAME store, in
+ * the SAME scope, the `compileDeliveryGraph`/`stageProposal` write commits to. There is no
+ * projection/read-model or cache between the write and this read, so a digest `compileDeliveryGraph`
+ * just returned is listed on the very next call with NO intervening delay (the write is committed before
+ * the compile door responds). Liveness is decided by the shared {@link isLiveStaged} predicate — NOT a
+ * second `status = 'staged'` datasource filter, which cannot express an `expires_at > now` cutoff and so
+ * would linger an aged-out row until the poller's sweep realises the TTL. Read-only; no write. */
 export async function listStagedProposals(
   data: DataLayer,
   at: Date = new Date(),
 ): Promise<DeliveryGraphProposal[]> {
   const rows = await deliveryGraphProposals(data).find({ status: "staged" });
   return rows
-    .filter((row) => !isProposalExpired(row.expires_at, at))
+    .filter((row) => isLiveStaged(row, at))
     .sort((a, b) => b.created_at.localeCompare(a.created_at));
 }
 

package/e2e/delivery-graph-read-after-write.e2e.ts

@@ -0,0 +1,132 @@
+// Delivery-graph read-after-write regression net (epic #605 slice S2, issue #608).
+//
+// PINS the acceptance guarantee: immediately after `compileDeliveryGraph` returns a staged `digest`,
+// `listStagedProposals` returns THAT digest — with NO intervening delay. In the evidence session
+// (issue #608) a `compileDeliveryGraph` that returned `status:"ready"` with `digest:"ca8fb90a1b0c"`
+// was followed by a `listStagedProposals` that answered `{"count":0,"proposals":[]}` — the read and
+// the write had disagreed, so an agent could not confirm its own staging. The fix serves both from a
+// single source of truth: the read (`listStagedProposals` / `getStagedProposal`, unified through the
+// one `isLiveStaged` predicate) queries the SAME `delivery_graph_proposals` store, in the SAME scope,
+// that the compile/stage write commits to — no read-model or cache in between.
+//
+// This case is RUNNABLE VIA THE SLICE S1 HARNESS (`e2e/support/mcp-harness.ts`): it imports
+// `bootMcpHarness` and drives the REAL runtime-served `/app/mcp` surface over the client handshake —
+// the exact transport an agent uses — so a regression that reintroduces the disagreement (a lagging
+// projection, a divergent read filter, a supersede that drops the just-written row) fails the build.
+// It does NOT re-implement the handshake (see the harness module header's EXTENSION SEAM).
+//
+// Run with `npm run e2e`.
+import assert from "node:assert/strict";
+import { after, before, describe, test } from "node:test";
+import { assertObjectBodyAccepted, bootMcpHarness, type McpHarness } from "./support/mcp-harness.ts";
+
+/** A minimal side-effecting graph — `compileDeliveryGraph` STAGES it (unlike the pure `previewDelivery
+ *  Graph`), which is exactly the write whose visibility we verify. Two agent nodes → two side effects. */
+const STAGES_A_PROPOSAL = {
+  name: "S2 read-after-write A",
+  nodes: [
+    { id: "open", kind: "agent", agent: { jobType: "senior:demo", prompt: "un-draft + merge #B" } },
+    { id: "cut", kind: "agent", agent: { jobType: "senior:demo", prompt: "cut the release" } },
+  ],
+  edges: [{ from: "open", to: "cut" }],
+};
+
+/** A dedicated logical key for the supersede test, distinct from the first test's key so the case is
+ *  SELF-CONTAINED — it stages BOTH its own V1 and V2 in-test and asserts per-logical-key, rather than
+ *  depending on an earlier test having staged a predecessor. */
+const SUPERSEDE_KEY = "S2 supersede key";
+
+/** V1 for the supersede test — the predecessor that staging V2 must retire. */
+const SUPERSEDE_V1 = {
+  name: SUPERSEDE_KEY,
+  nodes: [
+    { id: "open", kind: "agent", agent: { jobType: "senior:demo", prompt: "un-draft + merge #B" } },
+    { id: "cut", kind: "agent", agent: { jobType: "senior:demo", prompt: "cut the release" } },
+  ],
+  edges: [{ from: "open", to: "cut" }],
+};
+
+/** V2 — a STRUCTURALLY different graph (an extra node → different compiled BPMN → different content
+ *  digest) sharing the SAME `name` (logical key) as V1, so staging it supersedes V1. The read after it
+ *  must show the SECOND digest (the one the compile just returned), never the superseded first. */
+const SUPERSEDE_V2 = {
+  name: SUPERSEDE_KEY,
+  nodes: [
+    { id: "open", kind: "agent", agent: { jobType: "senior:demo", prompt: "un-draft + merge #B" } },
+    { id: "notes", kind: "agent", agent: { jobType: "senior:demo", prompt: "draft the release notes" } },
+    { id: "cut", kind: "agent", agent: { jobType: "senior:demo", prompt: "cut the release" } },
+  ],
+  edges: [
+    { from: "open", to: "notes" },
+    { from: "notes", to: "cut" },
+  ],
+};
+
+interface StagedRow { digest: string; title: string | null }
+interface ListBody { count: number; proposals: StagedRow[] }
+
+/** Compile a graph over MCP and return the staged digest the door reports (asserting it staged). */
+async function compileAndStage(h: McpHarness, graph: unknown): Promise<string> {
+  const res = await h.callTool("compileDeliveryGraph", { body: graph });
+  assertObjectBodyAccepted(res, "compileDeliveryGraph"); // the object body was NOT stringified
+  assert.ok(!res.isError, `compileDeliveryGraph must stage a valid graph: ${res.text}`);
+  const json = res.json as { status?: string; digest?: string } | undefined;
+  assert.equal(json?.status, "ready", `compileDeliveryGraph must report status:"ready": ${res.text}`);
+  assert.ok(typeof json?.digest === "string" && json.digest.length > 0, `a staged digest is required: ${res.text}`);
+  return json.digest;
+}
+
+/** The current live staged list, read over the SAME MCP surface. */
+async function listStaged(h: McpHarness): Promise<ListBody> {
+  const res = await h.callTool("listStagedProposals", {});
+  assert.ok(!res.isError, `listStagedProposals must not error: ${res.text}`);
+  const json = res.json as ListBody | undefined;
+  assert.ok(json && Array.isArray(json.proposals), `listStagedProposals must return a proposals array: ${res.text}`);
+  return json;
+}
+
+describe("S2 — listStagedProposals read-after-write is trustworthy (#608)", () => {
+  let h: McpHarness;
+  before(async () => { h = await bootMcpHarness(); });
+  after(async () => { await h.stop(); });
+
+  test("a digest compileDeliveryGraph just returned is listed on the very next call — no delay", async () => {
+    const digest = await compileAndStage(h, STAGES_A_PROPOSAL);
+    // The immediate read — no sleep, no retry, no poll — must show the write.
+    const list = await listStaged(h);
+    const digests = list.proposals.map((p) => p.digest);
+    assert.ok(
+      digests.includes(digest),
+      `the digest ${digest} compileDeliveryGraph just returned must appear in listStagedProposals ` +
+        `immediately (got ${JSON.stringify(digests)})`,
+    );
+  });
+
+  test("supersede keeps read-after-write honest: the read shows the LATEST returned digest, not the superseded one", async () => {
+    // SELF-CONTAINED: stage V1 then V2 for the SAME logical key inside this test — V2 supersedes V1. The
+    // read must reflect the digest THIS compile returned (the live one) and the superseded predecessor
+    // must be gone, with no dependence on any other test having staged first.
+    const digestV1 = await compileAndStage(h, SUPERSEDE_V1);
+    const digestV2 = await compileAndStage(h, SUPERSEDE_V2);
+    assert.notEqual(digestV1, digestV2, "V1 and V2 must differ in content so V2 genuinely supersedes V1");
+    const list = await listStaged(h);
+    const digests = list.proposals.map((p) => p.digest);
+    assert.ok(
+      digests.includes(digestV2),
+      `after superseding, listStagedProposals must show the latest digest ${digestV2} (got ${JSON.stringify(digests)})`,
+    );
+    assert.ok(
+      !digests.includes(digestV1),
+      `the superseded predecessor digest ${digestV1} must be gone from listStagedProposals (got ${JSON.stringify(digests)})`,
+    );
+    // Exactly one live proposal FOR THIS logical key — filter by title so the assertion is per-logical-key
+    // and does not couple to how many other proposals exist in the shared store.
+    const forLogicalKey = list.proposals.filter((p) => p.title === SUPERSEDE_KEY);
+    assert.equal(
+      forLogicalKey.length,
+      1,
+      `exactly one live staged proposal must remain for the logical key ${JSON.stringify(SUPERSEDE_KEY)} (got ${JSON.stringify(forLogicalKey.map((p) => p.digest))})`,
+    );
+    assert.equal(forLogicalKey[0]?.digest, digestV2, "the sole remaining live proposal must be the latest digest");
+  });
+});

package/openapi.yaml

@@ -4029,11 +4029,25 @@ paths:
       operationId: listStagedProposals
       summary: List the LIVE staged delivery-graph proposals awaiting dispatch (issue #511), newest first.
       description: >-
-        The read behind the staged-proposals App-View: every `staged` delivery-graph proposal that has
-        not aged out of its TTL, newest first, projected to the Preview-DI + Dispatch metadata (the
-        `graph`/`preview` payloads are omitted — the App-View recompiles by `digest` for the DI preview).
-        Mirrors the `previewProposalBpmn`/`dispatchDeliveryGraph` freshness guard so an expired-but-not-
-        yet-swept row is never listed. Read-only.
+        The read behind the staged-proposals App-View AND the MCP `listStagedProposals` tool: every
+        `staged` delivery-graph proposal that has not aged out of its TTL, newest first, projected to the
+        Preview-DI + Dispatch metadata (the `graph`/`preview` payloads are omitted — the App-View
+        recompiles by `digest` for the DI preview). Mirrors the
+        `previewProposalBpmn`/`dispatchDeliveryGraph` freshness guard so an expired-but-not-yet-swept row
+        is never listed. Read-only.
+
+
+        FRESHNESS / CONSISTENCY (issue #608). This read is READ-AFTER-WRITE consistent with
+        `compileDeliveryGraph`: it is served by a fresh query against the SAME durable
+        `delivery_graph_proposals` store, in the SAME scope, that the compile/stage write commits to (the
+        app's single default data source) — there is no projection, read-model, or cache between the
+        write and this read. So a `digest` that `compileDeliveryGraph` just returned as `status: "ready"`
+        is guaranteed to appear here on the very next call, with NO intervening delay and no polling
+        needed (the row is committed before the compile door responds). The one caveat is scope: the MCP
+        endpoint and the cockpit must resolve the SAME app deployment — point the MCP client at the same
+        instance/mount whose `reviewUrl` the compile door returned, or the read and the write address
+        different databases and disagree. Returns an empty list only when nothing is genuinely staged
+        (or every staged row has aged out of its TTL).
       security:
         - hookSecret: []
         - {}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.159.0",
+  "version": "0.159.1",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",