@nanobpm/nano-workforce 0.109.0 → 0.111.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [0.111.0](https://github.com/nanobpm/nano-workforce/compare/v0.110.0...v0.111.0) (2026-08-20)
+
+
+### Features
+
+* **readiness:** add pr/merge-state ReadinessProbe kind (ADR 0005 S2) ([#385](https://github.com/nanobpm/nano-workforce/issues/385)) ([860e031](https://github.com/nanobpm/nano-workforce/commit/860e03134b428c73426621acb14ccd9a3ab94149)), closes [#258](https://github.com/nanobpm/nano-workforce/issues/258) [owner/repo#N](https://github.com/owner/repo/issues/N) [#377](https://github.com/nanobpm/nano-workforce/issues/377) [owner/repo#N](https://github.com/owner/repo/issues/N)
+
+# [0.110.0](https://github.com/nanobpm/nano-workforce/compare/v0.109.0...v0.110.0) (2026-08-20)
+
+
+### Features
+
+* DeliveryGraph JSON contract + pure validator (ADR 0005 S0) ([#384](https://github.com/nanobpm/nano-workforce/issues/384)) ([ae85e1a](https://github.com/nanobpm/nano-workforce/commit/ae85e1af220844f961f6161d4f676aa289d86693)), closes [#375](https://github.com/nanobpm/nano-workforce/issues/375) [#227](https://github.com/nanobpm/nano-workforce/issues/227)
+
 # [0.109.0](https://github.com/nanobpm/nano-workforce/compare/v0.108.0...v0.109.0) (2026-08-20)
 
 

package/app/contracts.ts

@@ -375,6 +375,15 @@ export const WIRE_CONTRACTS = {
       "The mind/world checkpoint JOIN shape (issue #324, ADR 0062 Slice 4/5, the WORLD half). At each push the app derives ONE `{commitSha, effectLedger}` and records it in the durable world store (`world_checkpoints`/`world_effects`) AND passes the SAME object to the mind's `session.checkpoint(commitSha, effectLedger)` (Slice 1, `@nanobpm/agentic/session`), so mind + world commit at the SAME per-PR monotonic offset — closing the divergence failure (harness thinks it hasn't pushed but the push landed, or vice-versa). `effectLedger` entries carry a fence idempotency key (push→commit SHA, PR comment→comment id, `gh merge`→merge key); on a re-lease `restoreWorld` inverts the push (`git fetch && git checkout <commitSha>`) then fence-replays the tail so an already-applied effect is skipped, not repeated. Consume this ONE shape from app/world — do not re-declare a synonym.",
     shape: '{ commitSha: string, effectLedger: Array<{ kind: "push"|"pr-comment"|"merge", idempotencyKey: string, description?: string }> }',
   },
+  DeliveryGraph: {
+    category: "wire",
+    name: "DeliveryGraph",
+    owner: "app/deliveryGraph.ts",
+    semantics:
+      "The agent-authored delivery graph (ADR 0005, slice S0) — the SINGLE agent-facing artifact for a heterogeneous, partly-human, cross-repo delivery runbook, crossing the ingest boundary as DATA (a JSON DAG, never an executable artifact). Declared in openapi.yaml as `DeliveryGraph`; ingest validates the SHAPE there and the SEMANTICS (acyclicity, edge integrity, fact resolution) in the pure `validateDeliveryGraph` (`app/deliveryGraph.ts`). Nodes each name a `kind` from a CLOSED allowlist (`agent`/`wait`/`human`/`connector` — Decision 1/2, the trust boundary) plus their typed `emits[]`; edges name DISCOVERED facts (Decision 3) — `from` is a bare `<nodeId>` or a qualified `<nodeId>.<fact>`. Later slices (compiler/dispatch/execution) build on this ONE shape — consume it, do not re-declare a synonym.",
+    shape:
+      '{ name?: string, nodes: Array<{ id: string, kind: "agent"|"wait"|"human"|"connector", emits?: Array<{ name: string, type: "string"|"number"|"boolean"|"artifact"|"version"|"url", description?: string }>, agent?: { jobType: string, prompt?: string }, wait?: ReadinessProbe, human?: { formKey?: string, prompt?: string }, connector?: { target: string, dedupeKey?: string, payload?: object } }>, edges?: Array<{ from: string, to: string }> }',
+  },
 } as const satisfies Record<string, WireContract>;
 
 export const TYPE_CONTRACTS = {

package/app/deliveryGraph.test.ts

@@ -0,0 +1,357 @@
+// Unit coverage for the pure delivery-graph validator `validateDeliveryGraph` (ADR 0005, slice S0).
+// It exercises the SEMANTIC rules the openapi schema cannot express — the closed-kind allowlist,
+// node-id uniqueness, edge integrity (dangling / self), typed-fact resolution (`from: <node>.<fact>`),
+// and acyclicity — directly, with no HTTP and no side effects, mirroring how app/epicSetValidation
+// unit-tests `validateEpicSet`. Each error class (unknown-kind / dangling / bad-`from` / cycle) has a
+// dedicated case, and a fully-worked well-formed graph proves the happy path returns no errors.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import {
+  DELIVERY_NODE_KINDS,
+  type DeliveryGraphError,
+  type DeliveryGraphErrorCode,
+  validateDeliveryGraph,
+} from "./deliveryGraph.ts";
+
+/** The single error in the result, asserting there is exactly one. */
+function only(errors: DeliveryGraphError[]): DeliveryGraphError {
+  assertEquals(errors.length, 1, `expected exactly one error, got ${JSON.stringify(errors)}`);
+  return errors[0];
+}
+
+/** Assert the result contains at least one error of the given code. */
+function hasCode(errors: DeliveryGraphError[], code: DeliveryGraphErrorCode): DeliveryGraphError {
+  const found = errors.find((e) => e.code === code);
+  assert(found !== undefined, `expected an error with code "${code}", got ${JSON.stringify(errors)}`);
+  return found;
+}
+
+// A realistic, fully-worked graph mirroring the ADR's motivating case: an agent opens PR #B, a `pr`
+// wait node (S2's kind, referenced by shape only here) watches it merge and emits `mergedSha`, a
+// human does the manual OTP publish emitting `resolvedArtifact`, and a downstream wait consumes that
+// published artifact. Proves nodes, per-kind config, typed emits, and both edge shapes validate.
+const WELL_FORMED = {
+  name: "release runbook",
+  nodes: [
+    { id: "open-b", kind: "agent", agent: { jobType: "senior:feature", prompt: "un-draft + merge #B" } },
+    {
+      id: "watch-b",
+      kind: "wait",
+      wait: { kind: "github-check", target: "owner/repo@main" },
+      emits: [{ name: "mergedSha", type: "string" }],
+    },
+    {
+      id: "manual-publish",
+      kind: "human",
+      human: { prompt: "do the manual OTP publish + set up OIDC" },
+      emits: [{ name: "resolvedArtifact", type: "artifact" }],
+    },
+    {
+      id: "consume-c",
+      kind: "wait",
+      wait: { kind: "capability", target: "github-releases:owner/repo" },
+    },
+    { id: "notify", kind: "connector", connector: { target: "slack:#releases", dedupeKey: "notify-1" } },
+  ],
+  edges: [
+    { from: "open-b", to: "watch-b" },
+    { from: "watch-b.mergedSha", to: "manual-publish" },
+    { from: "manual-publish.resolvedArtifact", to: "consume-c" },
+    { from: "consume-c", to: "notify" },
+  ],
+};
+
+test("a well-formed delivery graph produces no errors", () => {
+  assertEquals(validateDeliveryGraph(WELL_FORMED), []);
+});
+
+test("an empty node set is rejected", () => {
+  const err = only(validateDeliveryGraph({ nodes: [] }));
+  assertEquals(err.code, "empty-graph");
+});
+
+test("a non-object graph is rejected without throwing", () => {
+  assertEquals(validateDeliveryGraph(null).length, 1);
+  assertEquals(validateDeliveryGraph(undefined)[0].code, "empty-graph");
+  assertEquals(validateDeliveryGraph({ nodes: "nope" })[0].code, "empty-graph");
+});
+
+test("unknown-kind: a node kind outside the closed allowlist is rejected, path-qualified", () => {
+  const errors = validateDeliveryGraph({
+    nodes: [{ id: "x", kind: "script", script: { run: "rm -rf /" } }],
+  });
+  const err = hasCode(errors, "unknown-kind");
+  assertEquals(err.path, "nodes[0].kind");
+  assert(err.message.includes(DELIVERY_NODE_KINDS.join(", ")), "message should list the allowlist");
+});
+
+test("unknown-kind: the closed allowlist is exactly the four ADR-0005 kinds", () => {
+  assertEquals([...DELIVERY_NODE_KINDS], ["agent", "wait", "human", "connector"]);
+});
+
+test("dangling edge: a `to` that names no node is rejected, path-qualified", () => {
+  const errors = validateDeliveryGraph({
+    nodes: [{ id: "a", kind: "agent", agent: { jobType: "j" } }],
+    edges: [{ from: "a", to: "ghost" }],
+  });
+  const err = hasCode(errors, "dangling-edge");
+  assertEquals(err.path, "edges[0].to");
+});
+
+test("dangling edge: a `from` that names no node is rejected, path-qualified", () => {
+  const errors = validateDeliveryGraph({
+    nodes: [{ id: "a", kind: "agent", agent: { jobType: "j" } }],
+    edges: [{ from: "ghost", to: "a" }],
+  });
+  const err = hasCode(errors, "dangling-edge");
+  assertEquals(err.path, "edges[0].from");
+});
+
+test("bad-from: a `<node>.<fact>` reference to an undeclared fact is rejected, path-qualified", () => {
+  const errors = validateDeliveryGraph({
+    nodes: [
+      { id: "a", kind: "agent", agent: { jobType: "j" }, emits: [{ name: "version", type: "version" }] },
+      { id: "b", kind: "agent", agent: { jobType: "j" } },
+    ],
+    edges: [{ from: "a.sha", to: "b" }],
+  });
+  const err = hasCode(errors, "bad-from");
+  assertEquals(err.path, "edges[0].from");
+  assert(err.message.includes("sha"), "message should name the missing fact");
+});
+
+test("bad-from: a declared fact reference resolves cleanly", () => {
+  const errors = validateDeliveryGraph({
+    nodes: [
+      { id: "a", kind: "agent", agent: { jobType: "j" }, emits: [{ name: "version", type: "version" }] },
+      { id: "b", kind: "agent", agent: { jobType: "j" } },
+    ],
+    edges: [{ from: "a.version", to: "b" }],
+  });
+  assertEquals(errors, []);
+});
+
+test("a node id containing dots resolves as a whole node, not a fact split", () => {
+  const errors = validateDeliveryGraph({
+    nodes: [
+      { id: "repo.owner.a", kind: "agent", agent: { jobType: "j" } },
+      { id: "b", kind: "agent", agent: { jobType: "j" } },
+    ],
+    edges: [{ from: "repo.owner.a", to: "b" }],
+  });
+  assertEquals(errors, []);
+});
+
+test("bad-from: an edge that resolves as both a whole node id and a `<node>.<fact>` reference is rejected as ambiguous", () => {
+  const errors = validateDeliveryGraph({
+    nodes: [
+      { id: "a.b", kind: "agent", agent: { jobType: "j" }, emits: [{ name: "c", type: "version" }] },
+      { id: "a.b.c", kind: "agent", agent: { jobType: "j" } },
+      { id: "d", kind: "agent", agent: { jobType: "j" } },
+    ],
+    edges: [{ from: "a.b.c", to: "d" }],
+  });
+  const err = hasCode(errors, "bad-from");
+  assertEquals(err.path, "edges[0].from");
+  assert(err.message.includes("ambiguous"), "message should call out the ambiguity");
+});
+
+test("cycle: a self-edge is rejected", () => {
+  const errors = validateDeliveryGraph({
+    nodes: [{ id: "a", kind: "agent", agent: { jobType: "j" } }],
+    edges: [{ from: "a", to: "a" }],
+  });
+  const err = hasCode(errors, "self-edge");
+  assertEquals(err.path, "edges[0]");
+});
+
+test("cycle: a multi-node dependency cycle is rejected, naming the cycle", () => {
+  const errors = validateDeliveryGraph({
+    nodes: [
+      { id: "a", kind: "agent", agent: { jobType: "j" } },
+      { id: "b", kind: "agent", agent: { jobType: "j" } },
+      { id: "c", kind: "agent", agent: { jobType: "j" } },
+    ],
+    edges: [
+      { from: "a", to: "b" },
+      { from: "b", to: "c" },
+      { from: "c", to: "a" },
+    ],
+  });
+  const err = hasCode(errors, "cycle");
+  assertEquals(err.path, "edges");
+  assert(err.message.includes("→"), "cycle message should render the cycle path");
+});
+
+test("duplicate-id: two nodes sharing an id is rejected", () => {
+  const errors = validateDeliveryGraph({
+    nodes: [
+      { id: "a", kind: "agent", agent: { jobType: "j" } },
+      { id: "a", kind: "human" },
+    ],
+  });
+  const err = hasCode(errors, "duplicate-id");
+  assertEquals(err.path, "nodes[1].id");
+});
+
+test("missing-config: a non-human node without its per-kind config is rejected", () => {
+  const errors = validateDeliveryGraph({ nodes: [{ id: "a", kind: "wait" }] });
+  const err = hasCode(errors, "missing-config");
+  assertEquals(err.path, "nodes[0].wait");
+});
+
+test("missing-required-field: an agent node whose `agent` config omits `jobType` is rejected", () => {
+  const errors = validateDeliveryGraph({ nodes: [{ id: "a", kind: "agent", agent: {} }] });
+  const err = hasCode(errors, "missing-required-field");
+  assertEquals(err.path, "nodes[0].agent.jobType");
+});
+
+test("missing-required-field: a wait node whose probe omits `kind`/`target` is rejected per field", () => {
+  const errors = validateDeliveryGraph({ nodes: [{ id: "a", kind: "wait", wait: {} }] });
+  hasCode(errors, "missing-required-field");
+  assertEquals(
+    errors.filter((e) => e.code === "missing-required-field").map((e) => e.path).sort(),
+    ["nodes[0].wait.kind", "nodes[0].wait.target"],
+  );
+});
+
+test("missing-required-field: a connector node whose config has an empty `target` is rejected", () => {
+  const errors = validateDeliveryGraph({
+    nodes: [{ id: "a", kind: "connector", connector: { target: "" } }],
+  });
+  const err = hasCode(errors, "missing-required-field");
+  assertEquals(err.path, "nodes[0].connector.target");
+});
+
+test("a human node may omit its config (generic-fallback resolution lands in S3)", () => {
+  assertEquals(validateDeliveryGraph({ nodes: [{ id: "done", kind: "human" }] }), []);
+});
+
+test("duplicate-fact: two emits sharing a name on one node is rejected", () => {
+  const errors = validateDeliveryGraph({
+    nodes: [
+      {
+        id: "a",
+        kind: "agent",
+        agent: { jobType: "j" },
+        emits: [{ name: "v", type: "version" }, { name: "v", type: "string" }],
+      },
+    ],
+  });
+  const err = hasCode(errors, "duplicate-fact");
+  assertEquals(err.path, "nodes[0].emits[1].name");
+});
+
+test("all errors are collected in one pass, not just the first", () => {
+  const errors = validateDeliveryGraph({
+    nodes: [
+      { id: "a", kind: "bogus" },
+      { id: "a", kind: "agent", agent: { jobType: "j" } },
+    ],
+    edges: [{ from: "ghost", to: "a" }],
+  });
+  hasCode(errors, "unknown-kind");
+  hasCode(errors, "duplicate-id");
+  hasCode(errors, "dangling-edge");
+  assert(errors.length >= 3, `expected the pass to collect every error, got ${errors.length}`);
+});
+
+test("a graph with no edges (independent roots) is valid", () => {
+  assertEquals(
+    validateDeliveryGraph({
+      nodes: [
+        { id: "a", kind: "agent", agent: { jobType: "j" } },
+        { id: "b", kind: "agent", agent: { jobType: "j" } },
+      ],
+    }),
+    [],
+  );
+});
+
+test("a non-array `edges` is rejected as a shape error (`invalid-edges`), not silently treated as no edges", () => {
+  const errors = validateDeliveryGraph({
+    nodes: [{ id: "a", kind: "agent", agent: { jobType: "j" } }],
+    edges: "nope",
+  });
+  const err = hasCode(errors, "invalid-edges");
+  assertEquals(err.path, "edges");
+});
+
+test("a non-object edge entry is a shape error (`invalid-edges`), not `dangling-edge`", () => {
+  const errors = validateDeliveryGraph({
+    nodes: [{ id: "a", kind: "agent", agent: { jobType: "j" } }],
+    edges: ["nope"],
+  });
+  const err = hasCode(errors, "invalid-edges");
+  assertEquals(err.path, "edges[0]");
+});
+
+test("an edge missing string `from`/`to` is a shape error (`invalid-edges`), not `dangling-edge`", () => {
+  const errors = validateDeliveryGraph({
+    nodes: [{ id: "a", kind: "agent", agent: { jobType: "j" } }],
+    edges: [{ from: "", to: 3 }],
+  });
+  const fromErr = hasCode(errors, "invalid-edges");
+  assertEquals(fromErr.path, "edges[0].from");
+  assert(
+    errors.some((e) => e.code === "invalid-edges" && e.path === "edges[0].to"),
+    "expected the missing `to` to also be an invalid-edges shape error",
+  );
+});
+
+test("invalid-id: a node id violating the openapi id pattern is rejected so downstream id use stays safe", () => {
+  const errors = validateDeliveryGraph({
+    nodes: [{ id: "1 bad id", kind: "agent", agent: { jobType: "j" } }],
+  });
+  const err = hasCode(errors, "invalid-id");
+  assertEquals(err.path, "nodes[0].id");
+});
+
+test("a `human` node whose `human` config is not an object is rejected, path-qualified", () => {
+  const errors = validateDeliveryGraph({
+    nodes: [{ id: "done", kind: "human", human: "just do it" }],
+  });
+  const err = hasCode(errors, "missing-config");
+  assertEquals(err.path, "nodes[0].human");
+});
+
+test("invalid-fact-name: an emitted fact name containing a dot is rejected so qualified `from` stays unambiguous", () => {
+  const errors = validateDeliveryGraph({
+    nodes: [{ id: "a", kind: "agent", agent: { jobType: "j" }, emits: [{ name: "sha.short", type: "string" }] }],
+  });
+  const err = hasCode(errors, "invalid-fact-name");
+  assertEquals(err.path, "nodes[0].emits[0].name");
+});
+
+test("invalid-fact-name: an emitted fact name over the openapi 128-char cap is rejected so a length-trusting consumer can't be overrun", () => {
+  const errors = validateDeliveryGraph({
+    nodes: [{ id: "a", kind: "agent", agent: { jobType: "j" }, emits: [{ name: "f".repeat(129), type: "string" }] }],
+  });
+  const err = hasCode(errors, "invalid-fact-name");
+  assertEquals(err.path, "nodes[0].emits[0].name");
+});
+
+test("invalid-fact-type: an emitted fact with a type outside the allowlist is rejected, path-qualified", () => {
+  const errors = validateDeliveryGraph({
+    nodes: [
+      {
+        id: "a",
+        kind: "agent",
+        agent: { jobType: "j" },
+        emits: [{ name: "sha", type: "bogus" }],
+      },
+    ],
+  });
+  const err = hasCode(errors, "invalid-fact-type");
+  assertEquals(err.path, "nodes[0].emits[0].type");
+});
+
+test("invalid-fact-type: an emitted fact missing its `type` is rejected", () => {
+  const errors = validateDeliveryGraph({
+    nodes: [
+      { id: "a", kind: "agent", agent: { jobType: "j" }, emits: [{ name: "sha" }] },
+    ],
+  });
+  const err = hasCode(errors, "invalid-fact-type");
+  assertEquals(err.path, "nodes[0].emits[0].type");
+});