@nanobpm/nano-workforce 0.109.0 → 0.110.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [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");
+});

package/app/deliveryGraph.ts

@@ -0,0 +1,463 @@
+// nano-workforce — the pure, side-effect-free SEMANTIC validator for an agent-authored delivery
+// graph (ADR 0005, slice S0). The `DeliveryGraph` SHAPE is validated at the edge by the openapi
+// schema (`openapi.yaml` → generated `DeliveryGraph` contract); this module validates the semantics
+// the JSON Schema CANNOT express and that a compiler/runner must be able to trust before it does
+// anything:
+//
+//   • unknown `kind` — a node whose `kind` is not in the CLOSED allowlist (the trust boundary,
+//     Decision 1/2). Defensive because the body arrives untyped from a request.
+//   • duplicate node id — two nodes sharing an id, which would make every edge to it ambiguous.
+//   • dangling edge — an edge endpoint (`from`/`to`) that names no node in the graph.
+//   • bad `from` reference — a qualified `<nodeId>.<fact>` whose fact is not declared in that node's
+//     typed `emits[]` (Decision 3/4 — binds are validated, not stringly).
+//   • cycle — the edge set must be a DAG (discovered-fact dependencies flow forward only).
+//
+// It is modelled on the epic-set validator `validateEpicSet` (app/plan.ts): a PURE in-memory walk
+// that runs BEFORE any side effect. Unlike `validateEpicSet` (which throws at the first offending
+// edge), this COLLECTS every error and returns them, so a co-designing agent gets ONE actionable,
+// path-qualified list per compile attempt (the S1 compiler surfaces them as `{ ok:false, errors }`).
+// Every error carries a JSON-path-qualified `path` (`nodes[2].kind`, `edges[1].from`, …) so the
+// caller can point the author straight at the offending input.
+
+/** The CLOSED node-kind allowlist (ADR 0005 Decision 2) — the trust boundary. Extensible only by a
+ * deliberate ADR/PR (add the openapi variant + a case here), never by a graph author. Kept as the
+ * single source of truth for "which kinds are legal" so the validator and any future compiler agree. */
+export const DELIVERY_NODE_KINDS = ["agent", "wait", "human", "connector"] as const;
+
+/** A node's `kind`, narrowed to the closed allowlist. */
+export type DeliveryNodeKind = (typeof DELIVERY_NODE_KINDS)[number];
+
+/** The CLOSED emitted-fact type allowlist (ADR 0005 Decision 3/4) — mirrors the `DeliveryFact.type`
+ * enum in `openapi.yaml`. Kept as the single source of truth so the semantic validator rejects an
+ * untyped/unknown fact type even when the OpenAPI shape validator is bypassed (a directly-invoked
+ * delegate), since later compilation/execution steps rely on this allowlist. */
+export const DELIVERY_FACT_TYPES = ["string", "number", "boolean", "artifact", "version", "url"] as const;
+
+/** An emitted fact's declared `type`, narrowed to the closed allowlist. */
+export type DeliveryFactType = (typeof DELIVERY_FACT_TYPES)[number];
+
+/** A machine-readable classification of a semantic failure, so a caller can branch on the error
+ * class (unknown-kind / dangling / cycle / bad-`from`) without string-matching the message. */
+export type DeliveryGraphErrorCode =
+  | "empty-graph"
+  | "missing-id"
+  | "invalid-id"
+  | "duplicate-id"
+  | "unknown-kind"
+  | "missing-config"
+  | "missing-required-field"
+  | "duplicate-fact"
+  | "invalid-fact-name"
+  | "invalid-fact-type"
+  | "invalid-edges"
+  | "dangling-edge"
+  | "bad-from"
+  | "self-edge"
+  | "cycle";
+
+/** A single semantic validation failure. `path` is a JSON-path-qualified pointer at the offending
+ * input (`nodes[2].kind`, `edges[1].from`, `nodes[0].emits[1].name`), `message` is human-actionable,
+ * and `code` is the stable error class. Shaped so the S1 compiler can forward it verbatim as one of
+ * its `{ ok:false, errors:[{ path, message }] }` entries. */
+export interface DeliveryGraphError {
+  readonly path: string;
+  readonly message: string;
+  readonly code: DeliveryGraphErrorCode;
+}
+
+/** Narrow an untyped value to a plain object so its fields can be read as `unknown`. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** True when `kind` is a member of the closed allowlist. */
+function isDeliveryNodeKind(kind: unknown): kind is DeliveryNodeKind {
+  if (typeof kind !== "string") return false;
+  for (const k of DELIVERY_NODE_KINDS) if (k === kind) return true;
+  return false;
+}
+
+/** True when `type` is a member of the closed emitted-fact type allowlist. */
+function isDeliveryFactType(type: unknown): type is DeliveryFactType {
+  if (typeof type !== "string") return false;
+  for (const t of DELIVERY_FACT_TYPES) if (t === type) return true;
+  return false;
+}
+
+/** A fact `name` must be a bare identifier (no dots) — mirrors openapi's `DeliveryFact.name`
+ * `^[A-Za-z_][A-Za-z0-9_]*$`. `resolveFrom` RELIES on fact names being dot-free (a node id MAY
+ * contain dots) to disambiguate a qualified edge `from`, so the semantic validator re-enforces the
+ * pattern INDEPENDENTLY of the OpenAPI shape gate: if that gate is bypassed (a direct delegate call,
+ * a test, a future internal use), a dotted fact name could otherwise make `<nodeId>.<fact>` resolution
+ * ambiguous and quietly build the wrong DAG — undermining the trust boundary this validator exists to
+ * hold. */
+const FACT_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const FACT_NAME_MAX_LENGTH = 128;
+
+/** A node `id` must match openapi's `DeliveryNodeCommon.id` `^[A-Za-z_][A-Za-z0-9_.-]*$` and stay
+ * within its 128-char cap. Re-enforced here INDEPENDENTLY of the OpenAPI shape gate because later
+ * compile/render steps trust these ids: an id with whitespace, a leading digit, or an over-long value
+ * could otherwise pass semantic validation (a bypassed shape gate — a direct delegate call, a test)
+ * and then break id-based compilation/rendering downstream. Unlike a fact name, an id MAY contain
+ * dots/hyphens — `resolveFrom` splits a qualified `from` on the LAST dot, so a dotted id stays
+ * resolvable while dot-free fact names keep `<nodeId>.<fact>` unambiguous. */
+const NODE_ID_PATTERN = /^[A-Za-z_][A-Za-z0-9_.-]*$/;
+const NODE_ID_MAX_LENGTH = 128;
+
+/** The per-kind config key a node of the given kind must carry (`agent` → `agent`, etc.). */
+const CONFIG_KEY: Record<DeliveryNodeKind, string> = {
+  agent: "agent",
+  wait: "wait",
+  human: "human",
+  connector: "connector",
+};
+
+/** The REQUIRED non-empty-string fields inside each kind's per-kind config object, mirroring the
+ * `required` lists in openapi (`DeliveryNodeAgent.agent.jobType`, the `ReadinessProbe.kind`/`target`
+ * a `wait` reuses, `DeliveryNodeConnector.connector.target`). Re-enforced here INDEPENDENTLY of the
+ * OpenAPI shape gate so that, when that gate is bypassed (a direct delegate call, a test, a future
+ * internal use), a config object present-but-missing its required fields (e.g. `{ kind:"agent",
+ * agent:{} }`) is rejected with an actionable error rather than passing semantic validation and
+ * crashing a downstream compiler/runner that assumes those fields exist. `human` has no required
+ * config field (its config is optional). Kept as the single source of truth so this list and openapi
+ * agree. NOTE: field PRESENCE + non-emptiness is enforced here, not the `ReadinessProbe.kind` enum —
+ * that enum evolves per slice (S2 adds `pr`), so enumerating it here would drift; the enum stays
+ * owned by the shape gate / `app/readiness.ts`. */
+const REQUIRED_CONFIG_FIELDS: Record<DeliveryNodeKind, readonly string[]> = {
+  agent: ["jobType"],
+  wait: ["kind", "target"],
+  human: [],
+  connector: ["target"],
+};
+
+/** Resolve an edge `from` endpoint against the known node set. A node id MAY itself contain dots (the
+ * openapi id pattern allows them) while a fact name (an identifier) cannot, so resolution is
+ * disambiguated by the node set rather than by naive splitting: (1) if the WHOLE string is a node id
+ * it is a bare completion-fact reference (`nodeId`, no fact); (2) else split at the LAST dot and, if
+ * the prefix is a node id, it is a qualified `<nodeId>.<fact>` reference; (3) else it is dangling —
+ * return the whole string as the (unresolvable) node id so the caller reports it against `from`.
+ * When BOTH interpretations resolve — the whole string is a node id AND its last-dot prefix is a
+ * node that emits the suffix as a fact — the reference is genuinely ambiguous; surface it via
+ * `ambiguousWith` so the caller rejects it (`bad-from`) rather than silently choosing the whole-node
+ * reading and producing an unintended DAG. */
+function resolveFrom(
+  from: string,
+  nodeFacts: ReadonlyMap<string, ReadonlySet<string>>,
+): { nodeId: string; fact?: string; ambiguousWith?: { nodeId: string; fact: string } } {
+  const dot = from.lastIndexOf(".");
+  const split =
+    dot > 0 && dot < from.length - 1 ? { prefix: from.slice(0, dot), suffix: from.slice(dot + 1) } : undefined;
+  if (nodeFacts.has(from)) {
+    if (split !== undefined && nodeFacts.get(split.prefix)?.has(split.suffix)) {
+      return { nodeId: from, ambiguousWith: { nodeId: split.prefix, fact: split.suffix } };
+    }
+    return { nodeId: from };
+  }
+  if (split !== undefined && nodeFacts.has(split.prefix)) return { nodeId: split.prefix, fact: split.suffix };
+  return { nodeId: from };
+}
+
+/**
+ * Pure, side-effect-free SEMANTIC validation of a delivery graph (ADR 0005 slice S0). Accepts the
+ * graph as `unknown` because it arrives from an untyped request body — every field is read
+ * defensively, so a malformed input maps to a clean {@link DeliveryGraphError} (never an uncaught
+ * TypeError). Returns every error found (empty array ⇒ the graph is semantically valid), each
+ * path-qualified — one entry per offending node/edge/fact, except cycle detection, which reports at
+ * most ONE cycle per call to keep the output actionable (fix it and re-validate to surface the next).
+ * Run this BEFORE any compile/deploy so a cycle, dangling edge, unknown kind, or unresolvable fact
+ * reference is rejected with nothing started.
+ */
+export function validateDeliveryGraph(graph: unknown): DeliveryGraphError[] {
+  const errors: DeliveryGraphError[] = [];
+
+  if (!isRecord(graph) || !Array.isArray(graph.nodes)) {
+    return [
+      {
+        path: "nodes",
+        message: "delivery graph must be an object with a `nodes` array",
+        code: "empty-graph",
+      },
+    ];
+  }
+  const nodes = graph.nodes;
+  if (nodes.length === 0) {
+    errors.push({
+      path: "nodes",
+      message: "delivery graph is empty — declare at least one node",
+      code: "empty-graph",
+    });
+  }
+
+  // Pass 1: node ids + kinds + per-kind config + declared facts. Build the id → declared-facts map
+  // used to resolve edge `from` references in pass 2.
+  const nodeFacts = new Map<string, Set<string>>();
+  nodes.forEach((rawNode, i) => {
+    const path = `nodes[${i}]`;
+    if (!isRecord(rawNode)) {
+      errors.push({ path, message: "each node must be an object", code: "missing-config" });
+      return;
+    }
+    const id = rawNode.id;
+    if (typeof id !== "string" || id.length === 0) {
+      errors.push({ path: `${path}.id`, message: "node is missing a string `id`", code: "missing-id" });
+    } else {
+      if (id.length > NODE_ID_MAX_LENGTH || !NODE_ID_PATTERN.test(id)) {
+        // Mirror openapi's `DeliveryNodeCommon.id` pattern/length so an invalid id can't slip past a
+        // bypassed shape gate and break id-based compilation/rendering in a later slice.
+        errors.push({
+          path: `${path}.id`,
+          message:
+            `node id "${id}" must be a bare identifier (\`^[A-Za-z_][A-Za-z0-9_.-]*$\`, ` +
+            `\u2264 ${NODE_ID_MAX_LENGTH} chars) so downstream id-based compilation stays safe`,
+          code: "invalid-id",
+        });
+      }
+      if (nodeFacts.has(id)) {
+        errors.push({
+          path: `${path}.id`,
+          message: `duplicate node id "${id}" — every node id must be unique in the graph`,
+          code: "duplicate-id",
+        });
+      }
+    }
+
+    const kind = rawNode.kind;
+    if (!isDeliveryNodeKind(kind)) {
+      errors.push({
+        path: `${path}.kind`,
+        message:
+          `unknown node kind ${JSON.stringify(kind)} — must be one of ` +
+          `${DELIVERY_NODE_KINDS.join(", ")} (the closed vocabulary is the trust boundary)`,
+        code: "unknown-kind",
+      });
+    } else if (kind !== "human") {
+      // Every kind but `human` REQUIRES its per-kind config object.
+      const configKey = CONFIG_KEY[kind];
+      const config = rawNode[configKey];
+      if (!isRecord(config)) {
+        errors.push({
+          path: `${path}.${configKey}`,
+          message: `${kind} node is missing its required \`${configKey}\` config`,
+          code: "missing-config",
+        });
+      } else {
+        // The config object is present — re-enforce the fields openapi marks REQUIRED (a bypassed
+        // shape gate could otherwise let `{ kind:"agent", agent:{} }` through and crash a downstream
+        // compiler/runner that trusts those fields exist).
+        for (const field of REQUIRED_CONFIG_FIELDS[kind]) {
+          const value = config[field];
+          if (typeof value !== "string" || value.length === 0) {
+            errors.push({
+              path: `${path}.${configKey}.${field}`,
+              message: `${kind} node's \`${configKey}.${field}\` is required and must be a non-empty string`,
+              code: "missing-required-field",
+            });
+          }
+        }
+      }
+    } else if (rawNode.human !== undefined && !isRecord(rawNode.human)) {
+      // `human` config is OPTIONAL (formKey/prompt both resolve to a generic fallback in S3), but
+      // when PRESENT it must be a plain object so later slices can safely read `human.formKey` /
+      // `human.prompt` — a string/array/null `human` would crash them downstream.
+      errors.push({
+        path: `${path}.human`,
+        message: "`human` config, when present, must be an object",
+        code: "missing-config",
+      });
+    }
+
+    // Collect + validate this node's typed emitted facts (uniqueness within the node). Registered
+    // under the id even when other fields are invalid, so downstream edge resolution is best-effort.
+    const facts = new Set<string>();
+    if (rawNode.emits !== undefined) {
+      if (!Array.isArray(rawNode.emits)) {
+        errors.push({
+          path: `${path}.emits`,
+          message: "`emits` must be an array of typed fact declarations",
+          code: "missing-config",
+        });
+      } else {
+        rawNode.emits.forEach((rawFact, j) => {
+          if (!isRecord(rawFact) || typeof rawFact.name !== "string" || rawFact.name.length === 0) {
+            errors.push({
+              path: `${path}.emits[${j}].name`,
+              message: "each emitted fact needs a non-empty string `name`",
+              code: "missing-config",
+            });
+            return;
+          }
+          if (facts.has(rawFact.name)) {
+            errors.push({
+              path: `${path}.emits[${j}].name`,
+              message: `duplicate emitted fact "${rawFact.name}" on node "${String(id)}"`,
+              code: "duplicate-fact",
+            });
+            return;
+          }
+          if (rawFact.name.length > FACT_NAME_MAX_LENGTH || !FACT_NAME_PATTERN.test(rawFact.name)) {
+            // A fact name must be a dot-free identifier within openapi's 128-char cap (openapi's
+            // `DeliveryFact.name` `pattern` + `maxLength`) so a qualified edge `from`
+            // "<nodeId>.<fact>" resolves unambiguously and a later step trusting the cap can't be
+            // overrun — enforced here too, in case the OpenAPI shape gate is bypassed.
+            errors.push({
+              path: `${path}.emits[${j}].name`,
+              message:
+                `emitted fact name "${rawFact.name}" must be a bare identifier ` +
+                "(`^[A-Za-z_][A-Za-z0-9_]*$`, no dots) of " +
+                `\u2264 ${FACT_NAME_MAX_LENGTH} chars so qualified edge \`from\` references stay unambiguous`,
+              code: "invalid-fact-name",
+            });
+            return;
+          }
+          if (!isDeliveryFactType(rawFact.type)) {
+            // emits are TYPED (Decision 3/4). An invalid/missing `type` must be rejected even when the
+            // OpenAPI shape validator is bypassed, or a later step reading the type allowlist breaks.
+            errors.push({
+              path: `${path}.emits[${j}].type`,
+              message:
+                `emitted fact "${rawFact.name}" has an invalid \`type\` — must be one of ` +
+                `${DELIVERY_FACT_TYPES.join(", ")}`,
+              code: "invalid-fact-type",
+            });
+          }
+          facts.add(rawFact.name);
+        });
+      }
+    }
+    if (typeof id === "string" && id.length > 0 && !nodeFacts.has(id)) {
+      nodeFacts.set(id, facts);
+    }
+  });
+
+  // Pass 2: edges. Resolve each endpoint against the node set and each qualified `from` against the
+  // upstream node's declared facts, and build the adjacency for the cycle check.
+  const edges: readonly unknown[] = Array.isArray(graph.edges) ? graph.edges : [];
+  if (graph.edges !== undefined && !Array.isArray(graph.edges)) {
+    // A non-array `edges` must not be silently treated as "no edges" — that would let a malformed
+    // body pass semantic validation when the OpenAPI shape validator is bypassed. This is a
+    // shape/type error (not an endpoint-resolution failure), so it carries `invalid-edges` — callers
+    // branching on error codes must distinguish "edges isn't a list" from a genuine dangling endpoint.
+    errors.push({
+      path: "edges",
+      message: "`edges`, when present, must be an array of `{ from, to }` dependency edges",
+      code: "invalid-edges",
+    });
+  }
+  // consumer (`to`) → set of upstream node ids (`from`'s node) — the dependency direction.
+  const adjacency = new Map<string, Set<string>>();
+  edges.forEach((rawEdge, i) => {
+    const path = `edges[${i}]`;
+    // A non-object entry or a missing/empty `from`/`to` is an edge *shape* error, not an
+    // endpoint-resolution failure — so it carries `invalid-edges` (like the non-array `edges` case
+    // above), reserving `dangling-edge` for a well-formed endpoint that names no node/fact.
+    if (!isRecord(rawEdge)) {
+      errors.push({ path, message: "each edge must be an object with `from` and `to`", code: "invalid-edges" });
+      return;
+    }
+    const from = rawEdge.from;
+    const to = rawEdge.to;
+    if (typeof from !== "string" || from.length === 0) {
+      errors.push({ path: `${path}.from`, message: "edge is missing a string `from`", code: "invalid-edges" });
+    }
+    if (typeof to !== "string" || to.length === 0) {
+      errors.push({ path: `${path}.to`, message: "edge is missing a string `to`", code: "invalid-edges" });
+    }
+    if (typeof from !== "string" || typeof to !== "string" || from.length === 0 || to.length === 0) {
+      return;
+    }
+
+    if (!nodeFacts.has(to)) {
+      errors.push({
+        path: `${path}.to`,
+        message: `edge \`to\` "${to}" names no node in the graph`,
+        code: "dangling-edge",
+      });
+    }
+
+    const { nodeId, fact, ambiguousWith } = resolveFrom(from, nodeFacts);
+    if (ambiguousWith !== undefined) {
+      errors.push({
+        path: `${path}.from`,
+        message:
+          `edge \`from\` "${from}" is ambiguous — it names both node "${from}" (a completion ` +
+          `dependency) and fact "${ambiguousWith.fact}" of node "${ambiguousWith.nodeId}"; rename ` +
+          "a node id or choose a different fact to disambiguate",
+        code: "bad-from",
+      });
+    }
+    const upstreamFacts = nodeFacts.get(nodeId);
+    if (upstreamFacts === undefined) {
+      errors.push({
+        path: `${path}.from`,
+        message: `edge \`from\` "${from}" names no node in the graph`,
+        code: "dangling-edge",
+      });
+    } else if (fact !== undefined && !upstreamFacts.has(fact)) {
+      errors.push({
+        path: `${path}.from`,
+        message:
+          `edge \`from\` "${from}" references fact "${fact}" that node "${nodeId}" does not ` +
+          "declare in its `emits[]`",
+        code: "bad-from",
+      });
+    }
+
+    if (nodeId === to) {
+      errors.push({
+        path,
+        message: `node "${to}" cannot depend on itself`,
+        code: "self-edge",
+      });
+      return;
+    }
+
+    // Only wire the cycle graph for edges whose endpoints both resolve — a dangling edge is already
+    // reported and must not crash the walk.
+    if (nodeFacts.has(to) && upstreamFacts !== undefined) {
+      const ups = adjacency.get(to) ?? new Set<string>();
+      ups.add(nodeId);
+      adjacency.set(to, ups);
+    }
+  });
+
+  collectCycle(adjacency, errors);
+  return errors;
+}
+
+/** Depth-first cycle detection over the consumer(`to`)→producer(`from`) graph. Pushes ONE
+ * {@link DeliveryGraphError} naming the offending cycle (the "reject at the offending edge"
+ * guarantee) — a pure in-memory walk, no I/O. Reports at most one cycle so the message stays
+ * actionable; the author fixes it and re-validates to surface any next one. */
+function collectCycle(adjacency: Map<string, Set<string>>, errors: DeliveryGraphError[]): void {
+  const VISITING = 1;
+  const DONE = 2;
+  const state = new Map<string, number>();
+  let reported = false;
+  const visit = (node: string, stack: string[]): void => {
+    if (reported) return;
+    state.set(node, VISITING);
+    stack.push(node);
+    for (const next of adjacency.get(node) ?? []) {
+      if (reported) break;
+      const s = state.get(next);
+      if (s === VISITING) {
+        const cycleStart = stack.indexOf(next);
+        const cycle = [...stack.slice(cycleStart), next];
+        errors.push({
+          path: "edges",
+          message: `dependency cycle detected: ${cycle.join(" → ")} — the graph must be a DAG`,
+          code: "cycle",
+        });
+        reported = true;
+        return;
+      }
+      if (s !== DONE) visit(next, stack);
+    }
+    stack.pop();
+    state.set(node, DONE);
+  };
+  for (const node of adjacency.keys()) {
+    if (reported) break;
+    if (state.get(node) !== DONE) visit(node, []);
+  }
+}

package/openapi.yaml

@@ -1253,6 +1253,250 @@ components:
             everyMs: { type: integer, description: Interval between poll attempts (ms). }
             timeoutMs: { type: integer, description: Bounded budget (ms) before the gate escalates. }
             backoff: { type: string, enum: [fixed, exponential], description: Backoff shape between attempts. }
+    DeliveryGraph:
+      description: >-
+        An agent-authored delivery graph (ADR 0005) — the SINGLE agent-facing artifact for a
+        heterogeneous, partly-human, cross-repo delivery runbook. It is DATA, never an executable
+        artifact: a JSON DAG whose nodes each name a `kind` from a CLOSED allowlist
+        (`agent`/`wait`/`human`/`connector` — Decision 1/2, the trust boundary) and whose `edges`
+        name DISCOVERED facts (Decision 3). Ingest validates the SHAPE here and the SEMANTICS
+        (acyclicity, edge integrity, fact resolution) in the pure `validateDeliveryGraph`
+        (`app/deliveryGraph.ts`). This slice (S0) defines the vocabulary + validation surface ONLY —
+        no compiler, dispatch, or execution (those land in later slices).
+      type: object
+      additionalProperties: false
+      required:
+        - nodes
+      properties:
+        name:
+          type: string
+          maxLength: 255
+          description: OPTIONAL human-readable label for the graph (shown in the rendered preview).
+        nodes:
+          type: array
+          minItems: 1
+          maxItems: 256
+          items:
+            $ref: "#/components/schemas/DeliveryNode"
+          description: >-
+            The graph's nodes. Each carries a unique `id` and a `kind` from the closed allowlist,
+            plus its per-kind config and its typed `emits[]` declaration. Node ids must be unique
+            across the graph (enforced by `validateDeliveryGraph`).
+        edges:
+          type: array
+          maxItems: 1024
+          items:
+            $ref: "#/components/schemas/DeliveryEdge"
+          description: >-
+            The dependency edges — the graph's discovered-fact topology (Decision 3). Each edge means
+            "`to` proceeds once fact `from` about the upstream node is observable". `from` is either a
+            bare `<nodeId>` (the degenerate "wait for the upstream node's completion" fact) or a
+            qualified `<nodeId>.<fact>` referencing one of that node's declared `emits`. Omit/`[]` for
+            a set of independent (root) nodes. The edge set must be a DAG.
+    DeliveryNode:
+      description: >-
+        One node in a delivery graph. A discriminated union on `kind` over the CLOSED allowlist; the
+        matching per-kind config object (`agent`/`wait`/`connector`) is REQUIRED and names the
+        engine-native body the node delegates to (Decision 2 — the graph schedules, it does not
+        re-implement execution). The `human` config is the sole exception — it is OPTIONAL (a bare
+        `human` node resolves to a generic emit-capturing form fallback in S3).
+      oneOf:
+        - $ref: "#/components/schemas/DeliveryNodeAgent"
+        - $ref: "#/components/schemas/DeliveryNodeWait"
+        - $ref: "#/components/schemas/DeliveryNodeHuman"
+        - $ref: "#/components/schemas/DeliveryNodeConnector"
+      discriminator:
+        propertyName: kind
+        mapping:
+          agent: "#/components/schemas/DeliveryNodeAgent"
+          wait: "#/components/schemas/DeliveryNodeWait"
+          human: "#/components/schemas/DeliveryNodeHuman"
+          connector: "#/components/schemas/DeliveryNodeConnector"
+    DeliveryFact:
+      description: >-
+        A typed output a node declares it will EMIT (ADR 0005 Decision 3/4 — emitted-fact typing).
+        A downstream edge references it as `from: "<nodeId>.<fact>"`, so a bind is validated against
+        this declaration, not stringly. A "click done" human node or a pass-through node declares no
+        facts (`emits` absent/empty) — the degenerate no-emit case.
+      type: object
+      additionalProperties: false
+      required:
+        - name
+        - type
+      properties:
+        name:
+          type: string
+          minLength: 1
+          maxLength: 128
+          pattern: '^[A-Za-z_][A-Za-z0-9_]*$'
+          description: The fact's identifier, referenced downstream as `<nodeId>.<name>`. Must be unique within the node.
+        type:
+          type: string
+          enum: [string, number, boolean, artifact, version, url]
+          description: >-
+            The fact's declared type. `artifact` is a `pkg@version` handle, `version` a bare version
+            string, `url` a location — mirrors the values `capability`/`pr` probes late-bind.
+        description:
+          type: string
+          maxLength: 512
+          description: OPTIONAL human note describing what the fact carries.
+    DeliveryNodeCommon:
+      type: object
+      properties:
+        id:
+          type: string
+          minLength: 1
+          maxLength: 128
+          pattern: '^[A-Za-z_][A-Za-z0-9_.-]*$'
+          description: The node's identifier, unique within the graph and referenced by edges.
+        emits:
+          type: array
+          maxItems: 32
+          items:
+            $ref: "#/components/schemas/DeliveryFact"
+          description: >-
+            The typed facts this node hands forward when it completes (Decision 3/4). Absent/empty for
+            a node that emits nothing. Downstream edges bind these via `from: "<nodeId>.<fact>"`.
+    DeliveryNodeAgent:
+      description: >-
+        An `agent` node — a worker executes an agent job type (the existing fan-out body). Bounded
+        (timeout → escalate) and resumable like every node.
+      allOf:
+        - $ref: "#/components/schemas/DeliveryNodeCommon"
+        - type: object
+          additionalProperties: false
+          required:
+            - id
+            - kind
+            - agent
+          properties:
+            id: { type: string }
+            kind: { type: string, enum: [agent] }
+            emits: { type: array, items: { $ref: "#/components/schemas/DeliveryFact" } }
+            agent:
+              type: object
+              additionalProperties: false
+              required:
+                - jobType
+              properties:
+                jobType:
+                  type: string
+                  minLength: 1
+                  description: The agent job type a worker executes for this node (e.g. `senior:feature`).
+                prompt:
+                  type: string
+                  maxLength: 20000
+                  description: OPTIONAL steering prompt appended to the node's job brief.
+    DeliveryNodeWait:
+      description: >-
+        A `wait` node — a durable `ReadinessProbe` (ADR 0001 §2) watching an external fact. Reuses the
+        existing `ReadinessProbe` shape verbatim (Decision 3 — never a second wait loop); the `pr`
+        merge-state kind is added to that shape by slice S2 and flows in here automatically.
+      allOf:
+        - $ref: "#/components/schemas/DeliveryNodeCommon"
+        - type: object
+          additionalProperties: false
+          required:
+            - id
+            - kind
+            - wait
+          properties:
+            id: { type: string }
+            kind: { type: string, enum: [wait] }
+            emits: { type: array, items: { $ref: "#/components/schemas/DeliveryFact" } }
+            wait:
+              $ref: "#/components/schemas/ReadinessProbe"
+    DeliveryNodeHuman:
+      description: >-
+        A `human` node — a scheduled user task + form (ADR 0002 machinery promoted from exception to
+        node, Decision 4). Surfaces "now do X" on the Tasks inbox, blocks dependents, is answerable by
+        a human OR an agent, is SLA-bounded, and can EMIT a typed fact its form captures.
+      allOf:
+        - $ref: "#/components/schemas/DeliveryNodeCommon"
+        - type: object
+          additionalProperties: false
+          required:
+            - id
+            - kind
+          properties:
+            id: { type: string }
+            kind: { type: string, enum: [human] }
+            emits: { type: array, items: { $ref: "#/components/schemas/DeliveryFact" } }
+            human:
+              type: object
+              additionalProperties: false
+              description: >-
+                OPTIONAL human-node config. `formKey` explicitly attaches a form (else a form is
+                selected by node category, else a generic emit-capturing fallback — resolved in S3).
+                The node's typed output is declared via the node-level `emits[]`.
+              properties:
+                formKey:
+                  type: string
+                  minLength: 1
+                  description: OPTIONAL explicit form to attach at authoring time (specific-else-generic resolution, S3).
+                prompt:
+                  type: string
+                  maxLength: 20000
+                  description: OPTIONAL instruction shown to the human/agent completing the task ("now do X").
+    DeliveryNodeConnector:
+      description: >-
+        A `connector` node — an automated, side-effecting outbound action (the connector I/O surface).
+        Side-effecting, so it carries a `dedupeKey` and tolerates at-least-once execution. The
+        `payload` schema is a minimal forward-declared stub in this slice (ADR 0005 non-goal — the
+        concrete connector I/O lands later).
+      allOf:
+        - $ref: "#/components/schemas/DeliveryNodeCommon"
+        - type: object
+          additionalProperties: false
+          required:
+            - id
+            - kind
+            - connector
+          properties:
+            id: { type: string }
+            kind: { type: string, enum: [connector] }
+            emits: { type: array, items: { $ref: "#/components/schemas/DeliveryFact" } }
+            connector:
+              type: object
+              additionalProperties: false
+              required:
+                - target
+              properties:
+                target:
+                  type: string
+                  minLength: 1
+                  description: The connector action target (forward-declared — the concrete scheme lands in a later slice).
+                dedupeKey:
+                  type: string
+                  minLength: 1
+                  description: >-
+                    OPTIONAL idempotency key so an at-least-once resume cannot double-fire this
+                    side-effecting node (ADR 0005 Decision 7). Author-supplied or graph-derived.
+                payload:
+                  type: object
+                  additionalProperties: true
+                  description: Minimal forward-declared payload stub — the concrete connector payload schema is deferred (ADR non-goal).
+    DeliveryEdge:
+      description: >-
+        A dependency edge — "`to` proceeds once fact `from` is observable" (ADR 0005 Decision 3).
+        `from` is either a bare `<nodeId>` (wait for the upstream node's completion fact) or a
+        qualified `<nodeId>.<fact>` referencing a declared `emits` fact of that node. Both endpoints
+        must resolve to a node in the graph, the referenced fact must be declared, and the whole edge
+        set must be a DAG — all enforced by `validateDeliveryGraph`.
+      type: object
+      additionalProperties: false
+      required:
+        - from
+        - to
+      properties:
+        from:
+          type: string
+          minLength: 1
+          description: The upstream endpoint — `<nodeId>` (completion) or `<nodeId>.<fact>` (a declared emitted fact).
+        to:
+          type: string
+          minLength: 1
+          description: The dependent node's id — proceeds once `from` is observed.
     FeatureStart:
       description: The start-feature request body — a SINGLE-issue feature run. Names the target issue
         by EXACTLY ONE of `issue` (an `owner/repo#123` reference) or `url` (a bare issue URL), plus a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.109.0",
+  "version": "0.110.0",
   "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",