@nanobpm/nano-workforce 0.138.2 → 0.139.0

package/app/deliveryGraphProposals.test.ts

@@ -16,7 +16,9 @@ import {
   deliveryGraphProposals,
   getStagedProposal,
   isProposalExpired,
+  markProposalDismissed,
   markProposalDispatched,
+  markProposalExpired,
   proposalExpiry,
   proposalLogicalKey,
   proposalReviewUrl,
@@ -265,3 +267,137 @@ test("sweepExpiredProposals: a dispatch racing between the read and the write is
     assertEquals((await deliveryGraphProposals(data).get("d1"))?.status, "dispatched");
   });
 });
+
+test("markProposalDismissed: flipping a live `staged` row returns true and lands it `dismissed`", async () => {
+  await withData(async (data) => {
+    await stageProposal(data, row());
+    const flipped = await markProposalDismissed(data, "d1");
+    // A real flip reports success (res.changed > 0) so the door can return 200/ok:true.
+    assertEquals(flipped, true);
+    assertEquals((await deliveryGraphProposals(data).get("d1"))?.status, "dismissed");
+  });
+});
+
+test("markProposalDismissed: only a `staged` row is flipped; an already-terminal (dispatched) row is left untouched", async () => {
+  await withData(async (data) => {
+    await stageProposal(data, row());
+    await markProposalDispatched(data, "d1");
+    // A dismiss landing after the row already moved on must NOT clobber the terminal status, and must
+    // report the lost race by returning `false` so the door can 400 instead of misreporting success.
+    const flipped = await markProposalDismissed(data, "d1");
+    assertEquals(flipped, false);
+    assertEquals((await deliveryGraphProposals(data).get("d1"))?.status, "dispatched");
+  });
+});
+
+test("markProposalDismissed: a dispatch racing between the door's liveness read and the write is NOT clobbered to `dismissed`", async () => {
+  await withData(async (data) => {
+    // A live staged proposal — the door's `getStagedProposal` sees it as `staged` before the write.
+    await stageProposal(data, row());
+
+    // Wrap the data layer so that, in the window between the door's liveness read and `markProposalDismissed`'s
+    // guarded `exec`, the operator dispatches the proposal (status: staged -> dispatched). A blind
+    // update-by-key would clobber that dispatch back to `dismissed`; 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 flipped = await markProposalDismissed(racyData as DataLayer, "d1");
+    assert(raced, "the racing dispatch should have fired");
+    // The guarded UPDATE changed 0 rows (row was `dispatched` at write time) → returns false so the door 400s.
+    assertEquals(flipped, false);
+    assertEquals((await deliveryGraphProposals(data).get("d1"))?.status, "dispatched");
+  });
+});
+
+test("markProposalExpired: flipping a live `staged` row returns true and lands it `expired`", async () => {
+  await withData(async (data) => {
+    await stageProposal(data, row());
+    const flipped = await markProposalExpired(data, "d1");
+    // A real flip reports success (res.changed > 0).
+    assertEquals(flipped, true);
+    assertEquals((await deliveryGraphProposals(data).get("d1"))?.status, "expired");
+  });
+});
+
+test("markProposalExpired: only a `staged` row is flipped; an already-terminal (dispatched) row is left untouched", async () => {
+  await withData(async (data) => {
+    await stageProposal(data, row());
+    await markProposalDispatched(data, "d1");
+    // A retirement landing after the row already moved on must NOT clobber the terminal status back to
+    // `expired`, and must report the lost race by returning `false`.
+    const flipped = await markProposalExpired(data, "d1");
+    assertEquals(flipped, false);
+    assertEquals((await deliveryGraphProposals(data).get("d1"))?.status, "dispatched");
+  });
+});
+
+test("markProposalExpired: a dismiss racing between the dispatch door's liveness read and the write is NOT clobbered to `expired`", async () => {
+  await withData(async (data) => {
+    // A live staged proposal — the dispatch door's `getStagedProposal` sees it as `staged` before the write.
+    await stageProposal(data, row());
+
+    // Wrap the data layer so that, in the window between the door's liveness read and `markProposalExpired`'s
+    // guarded `exec`, the operator dismisses the proposal (status: staged -> dismissed). A blind
+    // update-by-key would clobber that dismiss back to `expired`; the guarded UPDATE (`WHERE status='staged'`)
+    // must instead no-op and leave the row `dismissed`.
+    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 markProposalDismissed(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 flipped = await markProposalExpired(racyData as DataLayer, "d1");
+    assert(raced, "the racing dismiss should have fired");
+    // The guarded UPDATE changed 0 rows (row was `dismissed` at write time) → returns false.
+    assertEquals(flipped, false);
+    assertEquals((await deliveryGraphProposals(data).get("d1"))?.status, "dismissed");
+  });
+});

package/app/deliveryGraphProposals.ts

@@ -36,9 +36,10 @@ export function proposalReviewUrl(digest: string, base: string = publicBaseUrl()
 
 /** 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;
+ * out of its TTL before an operator dispatched it; `dismissed` = an operator explicitly discarded it as
+ * noise. `superseded`/`dispatched`/`expired`/`dismissed` all drop out of the cockpit's staged list
+ * (which filters to `status = 'staged'`). */
+export const DELIVERY_PROPOSAL_STATUSES = ["staged", "superseded", "dispatched", "expired", "dismissed"] as const;
 export type DeliveryProposalStatus = typeof DELIVERY_PROPOSAL_STATUSES[number];
 
 /** One staged delivery-graph proposal — the durable row keyed by content `digest`. `side_effecting`
@@ -246,9 +247,56 @@ export async function markProposalDispatched(data: DataLayer, digest: string): P
 /** 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() });
+ * undismissable `staged` row that fails every dispatch attempt the same way.
+ *
+ * Like `sweepExpiredProposals`/`markProposalDismissed`, the flip is a GUARDED UPDATE
+ * (`... WHERE digest=? AND status='staged'`), not a blind update-by-key. The dispatch door's
+ * `getStagedProposal` liveness read and this write are separate statements, so a proposal can leave
+ * `staged` in the window between them (an operator dismisses it, or it's superseded/dispatched by another
+ * concurrent action); a blind `table.update(digest, …)` would clobber that newer terminal status back to
+ * `expired`, breaking monotonic lifecycle transitions. The `status='staged'` guard makes the write a no-op
+ * when the row has already moved on.
+ *
+ * Returns whether the guarded UPDATE actually flipped a row (`res.changed > 0`), mirroring
+ * `markProposalDismissed`/`sweepExpiredProposals`. A `false` return means the row was no longer `staged`
+ * at write time (a dismiss/supersede/dispatch race won), so the caller must not treat the retirement as
+ * having happened. */
+export async function markProposalExpired(data: DataLayer, digest: string): Promise<boolean> {
+  const db = data.open();
+  const res = await db.exec(
+    `UPDATE "delivery_graph_proposals" SET "status" = 'expired', "updated_at" = ? WHERE "digest" = ? AND "status" = 'staged'`,
+    [now(), digest],
+  );
+  return res.changed > 0;
+}
+
+/** Dismiss a staged proposal at an operator's explicit request — flip it to the terminal `dismissed`
+ * status so it drops out of the cockpit's staged grid (which filters to `status = 'staged'`), exactly
+ * like `superseded`/`expired`. Unlike `expired` (a TTL sweep) or `superseded` (a newer digest landed),
+ * `dismissed` records a deliberate operator "this is noise, hide it" — the proposal was neither aged out
+ * nor replaced. Callers (the `dismissProposal` door) gate this behind a `getStagedProposal` liveness
+ * check so an unknown or already-terminal digest is refused before this runs, keeping the dismiss
+ * idempotent.
+ *
+ * Like `sweepExpiredProposals`, the flip is a GUARDED UPDATE (`... WHERE digest=? AND status='staged'`),
+ * not a blind update-by-key. The door's `getStagedProposal` check and this write are separate statements,
+ * so a dispatch (or a supersede/expiry sweep) can move the row off `staged` in the window between them; a
+ * blind `table.update(digest, …)` would clobber that newer terminal status back to `dismissed`, 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, preserving monotonic lifecycle transitions under concurrent operator actions.
+ *
+ * Returns whether the guarded UPDATE actually flipped a row (`res.changed > 0`), mirroring how
+ * `sweepExpiredProposals` counts `res.changed`. A `false` return means the row was no longer `staged` at
+ * write time (the dispatch/supersede/expiry race above won), so the caller (the `dismissProposal` door)
+ * must NOT report success — the dismiss lost the race and its idempotency contract routes that to a clean
+ * 400, exactly as an already-terminal digest does. */
+export async function markProposalDismissed(data: DataLayer, digest: string): Promise<boolean> {
+  const db = data.open();
+  const res = await db.exec(
+    `UPDATE "delivery_graph_proposals" SET "status" = 'dismissed', "updated_at" = ? WHERE "digest" = ? AND "status" = 'staged'`,
+    [now(), digest],
+  );
+  return res.changed > 0;
 }
 
 /** Age out every `staged` proposal whose TTL has elapsed by flipping it to `expired`, so it drops out

package/app/deliveryGraphShape.test.ts

@@ -0,0 +1,66 @@
+// Unit coverage for `validateDeliveryGraphShape` — the reused OpenAPI `DeliveryGraph` shape gate
+// (PR #533 review). It must (a) reject the nested-type/unknown-property violations the semantic
+// validator deliberately does not re-enumerate, with path-qualified errors, and (b) accept a
+// structurally-valid graph — INCLUDING a not-yet-resolvable capability/pr probe, whose late-binding
+// is deferred to the runner and must NOT be a shape-time failure.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import { validateDeliveryGraphShape } from "./deliveryGraphShape.ts";
+
+test("accepts a structurally-valid graph (agent + human)", () => {
+  assertEquals(
+    validateDeliveryGraphShape({
+      name: "ok",
+      nodes: [
+        { id: "a", kind: "agent", agent: { jobType: "senior:feature" } },
+        { id: "h", kind: "human", human: { prompt: "do X" } },
+      ],
+      edges: [{ from: "a", to: "h" }],
+    }).length,
+    0,
+  );
+});
+
+test("accepts a not-yet-resolvable capability/pr wait probe (shape only, resolution deferred)", () => {
+  assertEquals(
+    validateDeliveryGraphShape({
+      nodes: [
+        { id: "c", kind: "wait", wait: { kind: "capability", target: "pkg@1.0.0", match: { package: "pkg", capabilityRef: "o/r#1" } } },
+        { id: "p", kind: "wait", wait: { kind: "pr", target: "o/r#1", match: { prState: "merged" } } },
+      ],
+    }).length,
+    0,
+  );
+});
+
+test("rejects a nested wrong-typed optional field with a path-qualified error", () => {
+  const errors = validateDeliveryGraphShape({
+    // biome-ignore lint/suspicious/noExplicitAny: deliberately malformed.
+    nodes: [{ id: "h", kind: "human", human: { prompt: 42 } } as any],
+  });
+  assert(errors.length > 0);
+  assert(errors.some((e) => e.path.includes("nodes[0]/human/prompt")));
+});
+
+test("rejects a wrong-typed nested wait.poll.backoff", () => {
+  const errors = validateDeliveryGraphShape({
+    // biome-ignore lint/suspicious/noExplicitAny: deliberately malformed.
+    nodes: [{ id: "w", kind: "wait", wait: { kind: "http", target: "http://x", poll: { backoff: 42 } } } as any],
+  });
+  assert(errors.length > 0);
+  assert(errors.some((e) => e.path.includes("nodes[0]/wait/poll/backoff")));
+});
+
+test("rejects an unknown top-level property", () => {
+  const errors = validateDeliveryGraphShape({
+    nodes: [{ id: "a", kind: "agent", agent: { jobType: "senior:feature" } }],
+    // biome-ignore lint/suspicious/noExplicitAny: deliberately malformed.
+    bogus: 1,
+  } as any);
+  assert(errors.length > 0);
+  assert(errors.some((e) => e.path.includes("bogus")));
+});
+
+test("rejects an empty-nodes graph (nodes.minItems: 1)", () => {
+  assert(validateDeliveryGraphShape({ name: "x", nodes: [] }).length > 0);
+});

package/app/deliveryGraphShape.ts

@@ -0,0 +1,67 @@
+// app/deliveryGraphShape.ts — reuse the RUNTIME's OWN OpenAPI request-body validator to shape-check a
+// delivery graph that reached the compiler through a TEXT-ingress door (preview/stage/save/import).
+//
+// The typed agent door (`compileDeliveryGraph`) has its body validated against the openapi
+// `DeliveryGraph` schema by the runtime BEFORE the delegate runs (`@nanobpm/urban`
+// runtime/core/modules/api.js → `validateValue`). The four human-facing doors instead receive a raw
+// `graphJson` STRING, which the runtime cannot shape-check — so the parsed object reaches
+// `compileDeliveryGraph` having BYPASSED that gate, and only the SEMANTIC validator
+// (`validateDeliveryGraph`) sees it. That validator, by design, does not re-enumerate every nested
+// optional-field type (the drift surface it explicitly forbids — see `REQUIRED_CONFIG_FIELDS` in
+// `app/deliveryGraph.ts`), so malformed nested values (`nodes[0].human.prompt: 42`,
+// `wait.poll.backoff: 42`, unknown properties) slipped through, were persisted, and later made
+// `parseProbe` throw downstream in `prepareDeliveryGraph`.
+//
+// Rather than hand-write those nested checks (drift) or add a new JSON-Schema dependency, we reuse the
+// EXACT validator the runtime applies at the typed edge — `validateValue` from `@nanobpm/urban/toolkit`
+// — against the SAME canonical `DeliveryGraph` schema in `openapi.yaml`. ONE schema, ONE validator, no
+// second source of truth: the text doors now get byte-identical shape enforcement to the typed door.
+// It is PURELY structural, so a shape-valid but not-yet-resolvable `capability`/`pr` wait probe passes
+// (its late-binding is the runner's job, not the edge's) — exactly the deferred-resolution contract the
+// canonical `parseProbe` intentionally keeps out of validate time.
+
+import { readFileSync } from "node:fs";
+import {
+  type OpenApiDoc,
+  type OpenApiSchema,
+  parseSpec,
+  resolveSchema,
+  validateValue,
+} from "@nanobpm/urban/toolkit";
+import type { CompileDeliveryGraphErrors } from "../nano-generated/api-io.d.ts";
+
+/** The wire error pair the compiler/doors forward (`{ path, message }`) — the stable schema `code`
+ * stays server-side, mirroring how `validateDeliveryGraph` errors are stripped for the wire. */
+type WireError = CompileDeliveryGraphErrors["errors"][number];
+
+// The spec ships at the repo root; this module lives in `app/`, so `..` is the repo root. Mirrors the
+// app's existing runtime-repo-file reads (`agentGuide.ts`, `agentSkill.ts`, `agentCompletion.ts`).
+const SPEC_URL = new URL("../openapi.yaml", import.meta.url);
+
+let cached: { doc: OpenApiDoc; schema: OpenApiSchema } | undefined;
+
+/** Load + parse `openapi.yaml` ONCE and resolve the `DeliveryGraph` component schema (cached — the
+ * spec is immutable for a process lifetime, so re-reading per compile would be pure waste). */
+function deliveryGraphSchema(): { doc: OpenApiDoc; schema: OpenApiSchema } {
+  if (!cached) {
+    const doc = parseSpec(readFileSync(SPEC_URL, "utf8"));
+    const schema = resolveSchema(doc, { $ref: "#/components/schemas/DeliveryGraph" });
+    if (!schema) {
+      throw new Error("openapi.yaml is missing the #/components/schemas/DeliveryGraph schema");
+    }
+    cached = { doc, schema };
+  }
+  return cached;
+}
+
+/** Shape-check `graph` against the canonical openapi `DeliveryGraph` schema using the runtime's OWN
+ * validator — the SAME gate the typed `compileDeliveryGraph` edge applies. Returns path-qualified
+ * `{ path, message }` errors (empty = the shape is valid). Structural only: a shape-valid but
+ * not-yet-resolvable `capability`/`pr` probe passes (late-binding is deferred to the runner). */
+export function validateDeliveryGraphShape(graph: unknown): WireError[] {
+  const { doc, schema } = deliveryGraphSchema();
+  return validateValue(doc, schema, graph).map((issue) => ({
+    path: issue.path === "" ? "/" : issue.path,
+    message: issue.message,
+  }));
+}

package/app/deliveryGraphTextIngress.test.ts

@@ -0,0 +1,137 @@
+// Coverage for the shared text-ingress helper's "never throws / never a 500" promise
+// (`parseAndCompileText`). The four doors that call it (preview/stage/save/import) DON'T wrap the
+// call, so a throw from the compiler's layout pass (`layoutDeliveryDiagram` fails loud when
+// `layoutBpmn` produces no DI — e.g. the `bpmn-auto-layout` peer is missing) would otherwise escape
+// as a raw, unhandled 500. That fault is a server-side infra condition, not reproducible from input
+// alone, so we inject a rejecting compiler through the helper's test seam to pin the guard.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import { parseAndCompileText } from "./deliveryGraphTextIngress.ts";
+
+// A SHAPE-valid graph (the openapi `DeliveryGraph` schema requires `nodes.minItems: 1`) so it reaches
+// the injected compiler seam — the shape gate now runs BEFORE compile, so an empty-nodes body would be
+// rejected as malformed and never exercise the never-throws guard.
+const VALID_BODY = {
+  graphJson: JSON.stringify({
+    name: "x",
+    nodes: [{ id: "a", kind: "agent", agent: { jobType: "senior:feature" } }],
+  }),
+};
+
+test("a compiler that throws is mapped to a clean 400 — never an unhandled 500", async () => {
+  const result = await parseAndCompileText(VALID_BODY, {
+    compile: () => Promise.reject(new Error("layoutBpmn produced no bpmndi:BPMNDiagram")),
+  });
+  assert(!result.ok, "a thrown compile must surface as ok:false, not a resolved success");
+  assertEquals(result.status, 400, "a caught compile throw must be the door's clean 400, not a 500");
+  assert(
+    result.body.error.includes("layoutBpmn produced no bpmndi:BPMNDiagram"),
+    "the 400 body must carry the underlying compile failure message",
+  );
+});
+
+test("a non-Error thrown value is still caught and reported, never rethrown", async () => {
+  const result = await parseAndCompileText(VALID_BODY, {
+    // biome-ignore lint/suspicious/useError: exercising the non-Error catch branch on purpose.
+    compile: () => Promise.reject("kaboom"),
+  });
+  assert(!result.ok, "a non-Error rejection must also be caught as ok:false");
+  assertEquals(result.status, 400, "a non-Error compile throw is still a clean 400");
+  assert(result.body.error.includes("kaboom"), "the stringified non-Error cause must be surfaced");
+});
+
+test("a shape-validator that throws (unreadable/corrupt openapi.yaml) is mapped to a clean 400 — never a 500", async () => {
+  let compileCalled = false;
+  const result = await parseAndCompileText(VALID_BODY, {
+    validateShape: () => {
+      throw new Error("ENOENT: openapi.yaml not found");
+    },
+    compile: () => {
+      compileCalled = true;
+      return Promise.reject(new Error("compile must not run when the shape gate itself faults"));
+    },
+  });
+  assert(!result.ok, "a thrown shape-validator fault must surface as ok:false, not a resolved success");
+  assertEquals(result.status, 400, "a caught spec-load fault must be the door's clean 400, not a 500");
+  assert(!compileCalled, "the compiler must not run when the shape gate itself throws");
+  assert(
+    result.body.error.includes("graph shape check unavailable"),
+    "the 400 body must report the shape gate as unavailable",
+  );
+  assert(
+    result.body.error.includes("ENOENT: openapi.yaml not found"),
+    "the 400 body must carry the underlying spec-load failure cause",
+  );
+});
+
+
+// semantic validator does NOT re-enumerate is now rejected at the door with a path-qualified error,
+// BEFORE compile runs (so a throwing compiler is never reached for these malformed bodies).
+for (const [label, graph, needle] of [
+  [
+    "wait.poll.backoff wrong type",
+    { nodes: [{ id: "w", kind: "wait", wait: { kind: "http", target: "http://x", poll: { backoff: 42 } } }] },
+    "nodes[0]/wait/poll/backoff",
+  ],
+  [
+    "human.prompt wrong type",
+    { nodes: [{ id: "h", kind: "human", human: { prompt: 42 } }] },
+    "nodes[0]/human/prompt",
+  ],
+  [
+    "unknown top-level property",
+    { nodes: [{ id: "a", kind: "agent", agent: { jobType: "senior:feature" } }], bogus: 1 },
+    "bogus",
+  ],
+] as const) {
+  test(`shape gate rejects a nested-shape violation before compile: ${label}`, async () => {
+    let compileCalled = false;
+    const result = await parseAndCompileText(
+      { graphJson: JSON.stringify(graph) },
+      {
+        compile: () => {
+          compileCalled = true;
+          return Promise.reject(new Error("compile must not run on a shape-invalid graph"));
+        },
+      },
+    );
+    assert(!result.ok, "a shape-invalid graph must be ok:false");
+    assertEquals(result.status, 400, "a shape-invalid graph is a clean 400");
+    assert(!compileCalled, "the shape gate must short-circuit BEFORE the compiler runs");
+    assert(
+      Array.isArray(result.body.errors) && result.body.errors.length > 0,
+      "the 400 body must carry path-qualified shape errors",
+    );
+    assert(
+      result.body.errors.some((e: { path: string; message: string }) => e.path.includes(needle)),
+      `a shape error must point at ${needle}`,
+    );
+  });
+}
+
+test("shape gate accepts a valid graph — a not-yet-resolvable capability probe passes structurally", async () => {
+  let compileCalled = false;
+  const result = await parseAndCompileText(
+    {
+      graphJson: JSON.stringify({
+        nodes: [
+          {
+            id: "c",
+            kind: "wait",
+            wait: { kind: "capability", target: "pkg@1.0.0", match: { capabilityRef: "o/r#1", package: "pkg" } },
+          },
+        ],
+      }),
+    },
+    {
+      compile: () => {
+        compileCalled = true;
+        return Promise.reject(new Error("reached compile"));
+      },
+    },
+  );
+  // The shape gate passed (compile was reached — it only rejects because the seam is a stub), proving a
+  // structurally-valid but deferred-resolution probe is NOT falsely rejected at shape time.
+  assert(compileCalled, "a shape-valid capability probe must pass the shape gate and reach compile");
+  assert(!result.ok, "the injected stub compiler still rejects");
+});

package/app/deliveryGraphTextIngress.ts

@@ -12,6 +12,7 @@
 import type { DeliveryGraphTextResult } from "../nano-generated/api-io.d.ts";
 import { compileDeliveryGraph } from "./deliveryGraphCompiler.ts";
 import { proposalReviewUrl } from "./deliveryGraphProposals.ts";
+import { validateDeliveryGraphShape } from "./deliveryGraphShape.ts";
 import { parseDeliveryGraphText } from "./deliveryGraphText.ts";
 import { deliveryGraphDigest } from "./deliveryRunner.ts";
 
@@ -37,15 +38,84 @@ export interface TextIngressOk {
 
 export type TextIngressResult = TextIngressOk | TextIngressFailure;
 
+/** Injectable seam for {@link parseAndCompileText}. `compile` defaults to the real
+ * {@link compileDeliveryGraph}; a test overrides it to drive the never-throws guard with a compiler
+ * that REJECTS — the real layout pass only throws on a server-side fault (a missing `bpmn-auto-layout`
+ * peer, so no DI is produced), which is not reproducible from input alone. */
+export interface ParseAndCompileDeps {
+  compile?: (graph: unknown) => Promise<CompileResult>;
+  /** Injectable seam for the reused OpenAPI shape gate — defaults to the real
+   * {@link validateDeliveryGraphShape}. A test overrides it to drive the spec-load guard with a
+   * validator that THROWS, standing in for a stripped/corrupt deployment whose `openapi.yaml` cannot
+   * be read/parsed — not reproducible from input alone. */
+  validateShape?: (graph: unknown) => ReturnType<typeof validateDeliveryGraphShape>;
+}
+
 /** Parse a UI JSON-paste body (`{ graphJson }`), then run the SAME pure compiler the agent door uses.
  * A blank/invalid paste or a graph that fails validation is returned as a ready-to-send 400; success
- * carries the compiled graph plus its content `digest` and human `name`. Never throws / never a 500. */
-export async function parseAndCompileText(body: unknown): Promise<TextIngressResult> {
+ * carries the compiled graph plus its content `digest` and human `name`. Never throws / never a 500 —
+ * even a server-side layout fault is caught and mapped to the door's clean 400/no-persist shape. */
+export async function parseAndCompileText(
+  body: unknown,
+  deps: ParseAndCompileDeps = {},
+): Promise<TextIngressResult> {
   const parsed = parseDeliveryGraphText(body);
   if (!parsed.ok) {
     return { ok: false, status: 400, body: { ok: false, error: parsed.error } };
   }
-  const compiled = await compileDeliveryGraph(parsed.graph);
+  // Re-apply the OpenAPI `DeliveryGraph` SHAPE gate the runtime runs at the typed `compileDeliveryGraph`
+  // edge (its `validateValue`). These text doors receive a raw `graphJson` STRING, so the runtime never
+  // shape-checked the parsed object — without this, malformed NESTED values (`nodes[0].human.prompt: 42`,
+  // `wait.poll.backoff: 42`, unknown properties) reach the semantic validator, which deliberately does
+  // not re-enumerate every optional-field type, and are persisted / later throw in `parseProbe`. Reusing
+  // the SAME validator against the SAME canonical schema (no ajv, no drift-surface hand checks) gives the
+  // text doors byte-identical shape enforcement to the agent door. Structural only, so a not-yet-
+  // resolvable capability/pr probe still passes — its late-binding stays the runner's job.
+  let shapeErrors: ReturnType<typeof validateDeliveryGraphShape>;
+  try {
+    shapeErrors = (deps.validateShape ?? validateDeliveryGraphShape)(parsed.graph);
+  } catch (err) {
+    // `validateDeliveryGraphShape` reads/parses `openapi.yaml` (once, cached) to reuse the runtime's
+    // OWN validator. A stripped or corrupted deployment where the spec is missing/unparseable — or the
+    // `DeliveryGraph` schema cannot be resolved — makes that read THROW. Left uncaught it would escape
+    // whichever door called us (none wrap this call) as a raw, unhandled 500, breaking the "never throws
+    // / never a 500" promise every caller depends on. This is a server-side fault (like the layout fault
+    // caught below), not bad input, so map it to the SAME clean 400/no-persist shape — ONE contract for
+    // every server fault this pipeline can hit, no partial/unhandled leak.
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      ok: false,
+      status: 400,
+      body: { ok: false, error: `graph shape check unavailable: ${message}` },
+    };
+  }
+  if (shapeErrors.length > 0) {
+    return {
+      ok: false,
+      status: 400,
+      body: {
+        ok: false,
+        error: `graph failed shape validation: ${shapeErrors.length} error(s)`,
+        errors: shapeErrors,
+      },
+    };
+  }
+  const compile = deps.compile ?? compileDeliveryGraph;
+  let compiled: CompileResult;
+  try {
+    compiled = await compile(parsed.graph);
+  } catch (err) {
+    // `compileDeliveryGraph` returns ok:false for every INPUT failure, but its layout pass
+    // (`layoutDeliveryDiagram` → `layoutBpmn`) can still THROW on a server-side fault — e.g. the
+    // `bpmn-auto-layout` peer missing, so no DI block is produced. Uncaught, that rejection would
+    // escape whichever door called us (preview/stage/save/import — none wrap this call) as a raw,
+    // unhandled 500, breaking the "never throws / never a 500" promise every caller depends on. Map it
+    // to the SAME clean 400 shape a compile error produces, so ONE guard keeps the door's documented
+    // "compile failure → clean 400, nothing persisted" contract honest for this edge case across all
+    // four doors, rather than leaking a partial/unhandled failure.
+    const message = err instanceof Error ? err.message : String(err);
+    return { ok: false, status: 400, body: { ok: false, error: `graph failed to compile: ${message}` } };
+  }
   if (!compiled.ok) {
     return {
       ok: false,

package/app/planReadModel.test.ts

@@ -49,6 +49,7 @@ const MIGRATION_CHAIN = [
   "080_plan_read_model_derive_terminal.sql",
   ROLLUPS_MIGRATION,
   READ_MODEL_MIGRATION,
+  "084_plan_wave_tasks_effective_status.sql",
 ];
 
 // The base `plans` / `plan_tasks` / `pull_requests` shapes the VIEWs read, plus a stand-in for the
@@ -430,6 +431,28 @@ test("plan_wave_tasks carries each task's PR url + process_key link targets (unc
   assertEquals({ pr_url: rows[1].pr_url, process_key: rows[1].process_key }, { pr_url: null, process_key: null });
 });
 
+test("plan_wave_tasks derives status=merged from the PR (never strands a landed slice at 'opened') — matching the summary bar", () => {
+  // The reported defect (#530): a slice whose PR converged + merged kept reading Status "opened" in
+  // the wave-state grid, because nothing writes `plan_tasks.status='merged'` on merge and the VIEW
+  // exposed the raw task status. The fix DERIVES the displayed status the SAME way the count VIEWs
+  // bucket `merged` — `pull_requests__tracking.derived_status = 'merged'` overrides the raw status —
+  // so the per-task grid and the per-wave summary bar agree.
+  const db = viewDb();
+  addPlan(db, "o/r#eff", { status: "done" });
+  addTask(db, "o/r#eff", { status: "opened", wave: 0, prStatus: "merged" }); // landed slice, task row frozen at "opened"
+  addTask(db, "o/r#eff", { status: "opened", wave: 0, prStatus: "converging" }); // still converging → stays "opened"
+  addTask(db, "o/r#eff", { status: "blocked", wave: 0 }); // no PR → raw status untouched
+  // A DERIVE-ONLY merged edge (base PR status frozen, tracking recomputes to `merged`) also reads merged.
+  addTask(db, "o/r#eff", { status: "opened", wave: 1, prStatus: "converging", prDerivedOverride: "merged" });
+  const byWaveIdx = db
+    .prepare("SELECT wave, task_index, status FROM plan_wave_tasks WHERE plan_key = ? ORDER BY task_index")
+    .all("o/r#eff") as Array<Record<string, unknown>>;
+  assertEquals(byWaveIdx.map((r) => r.status), ["merged", "opened", "blocked", "merged"]);
+  // The count VIEW and the per-task grid now agree on the merged tally for wave 0 (3 slices, 1 merged).
+  const c = db.prepare("SELECT merged, total FROM plan_wave_counts WHERE plan_key = ? AND wave = 0").get("o/r#eff") as Record<string, unknown>;
+  assertEquals({ merged: Number(c.merged), total: Number(c.total) }, { merged: 1, total: 3 });
+});
+
 test("the operator pages bind the derived plan-family VIEWs (never the raw plans table)", () => {
   // Overview + Epic index + Epic detail all read the composite `plan_read_model`; the epic-detail
   // per-wave summary reads `plan_wave_summary` (the bar), and the wave-state grid `plan_wave_tasks`.