@nanobpm/nano-workforce 0.112.0 → 0.113.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.113.0](https://github.com/nanobpm/nano-workforce/compare/v0.112.0...v0.113.0) (2026-08-20)
+
+
+### Features
+
+* **delivery-graph:** `human` node as a scheduled user task that emits a typed fact (ADR 0005 S3) ([#389](https://github.com/nanobpm/nano-workforce/issues/389)) ([2266f9c](https://github.com/nanobpm/nano-workforce/commit/2266f9c36f194a7b1bfa995925968353131040e4)), closes [#378](https://github.com/nanobpm/nano-workforce/issues/378)
+
 # [0.112.0](https://github.com/nanobpm/nano-workforce/compare/v0.111.1...v0.112.0) (2026-08-20)
 
 

package/app/agentCompletion.ts

@@ -23,6 +23,7 @@
 import { readFileSync } from "node:fs";
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
 import { CONFORMANCE_ESCALATION_ELEMENT } from "./conformance.ts";
+import { DELIVERY_HUMAN_ELEMENT } from "./deliveryHuman.ts";
 
 const now = () => new Date().toISOString();
 
@@ -70,6 +71,7 @@ export const ESCALATION_TASK_ELEMENTS: ReadonlySet<string> = new Set([
   "trial-merge-decision",
   "wait-answer", // PR review-loop escalation (convergence-loop.bpmn, U3)
   "wait-merge-answer", // PR merge-loop escalation (merge-loop.bpmn) — same native user-task path (#256)
+  DELIVERY_HUMAN_ELEMENT, // delivery-graph `human` node (ADR 0005 S3) — a scheduled user task, answerable by a human OR an agent (ADR 0046)
 ]);
 
 /** The `feature-blocked` operator user-task element id (feature.bpmn) — the native wait a run parks on
@@ -110,6 +112,14 @@ const ESCALATION_FORM_BY_ELEMENT: Readonly<Record<string, string>> = {
   "wait-merge-answer": "pr-escalation",
   "feature-blocked": "feature-blocked",
   [CONFORMANCE_ESCALATION_TASK_ELEMENT]: "conformance-escalation",
+  // NOTE: the delivery-graph `human` node (`DELIVERY_HUMAN_ELEMENT`, ADR 0005 S3) is intentionally
+  // ABSENT here. Unlike the fixed-form escalations above, ONE `delivery-human-task` element is DESIGNED
+  // to render DIFFERENT forms per node (explicit → category → generic → agent-router, `app/deliveryHuman.ts`
+  // `resolveHumanForm`) — the S4 runner selects one at activation; this S3 slice deploys the generic
+  // form as the static default. Either way a single static required-field contract cannot fit it. Its typed-emit
+  // contract is enforced instead by `bindHumanEmits` against the node's declared `emits[]` (binds are
+  // validated, not stringly — Decision 3/4), so `validateEscalationVariables` leaves it unenforced
+  // (returns `null`) and the completer accepts the captured form variables for the emit binder to type.
 };
 
 /** A field's `conditional.hide` rule, parsed from the FEEL subset the `.form` files use

package/app/deliveryGraph.ts

@@ -91,8 +91,8 @@ function isDeliveryFactType(type: unknown): type is DeliveryFactType {
  * 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;
+export const FACT_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+export 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

package/app/deliveryHuman.test.ts

@@ -0,0 +1,306 @@
+// Tests for the `human` delivery-graph node (ADR 0005, slice S3): form resolution (specific-else-
+// generic + gated agent-router), typed-emit binding, and the #289 late-binding surfaces. Pure logic
+// (no engine), plus a structural + cross-layer guard tying the committed BPMN body / `.form` files to
+// the completer allowlist and the inbox read-model so the two can't silently diverge.
+
+import { test } from "node:test";
+import { readFileSync } from "node:fs";
+import { assert, assertEquals, assertStringIncludes } from "#test-assert";
+import type { DeliveryFact } from "../nano-generated/api-io.d.ts";
+import {
+  bindHumanEmits,
+  DELIVERY_HUMAN_ELEMENT,
+  deriveHumanCategory,
+  GENERIC_HUMAN_FORM,
+  HUMAN_ACK_FORM,
+  HUMAN_PUBLISH_FORM,
+  humanEmitBind,
+  needsAgentFormRouter,
+  normalizeEmits,
+  renderHumanEmitBrief,
+  resolveHumanForm,
+} from "./deliveryHuman.ts";
+import { ESCALATION_TASK_ELEMENTS } from "./agentCompletion.ts";
+import { USER_TASK_KIND_LABELS } from "./userTasks.ts";
+
+const artifact = (name = "resolvedArtifact"): DeliveryFact => ({ name, type: "artifact" });
+const version = (name = "publishedVersion"): DeliveryFact => ({ name, type: "version" });
+const str = (name: string): DeliveryFact => ({ name, type: "string" });
+
+// ── Form resolution: explicit → category → generic → agent-router ──────────────────────────────
+
+test("resolveHumanForm: an explicit formKey always wins, even over a category match", () => {
+  const r = resolveHumanForm({ emits: [artifact()], human: { formKey: "my-bespoke-form" } });
+  assertEquals(r.source, "explicit");
+  assertEquals(r.formKey, "my-bespoke-form");
+  assertEquals(r.category, null);
+});
+
+test("resolveHumanForm: a blank/whitespace explicit formKey does not count as explicit", () => {
+  const r = resolveHumanForm({ emits: [], human: { formKey: "   " } });
+  assertEquals(r.source, "category");
+  assertEquals(r.formKey, HUMAN_ACK_FORM);
+});
+
+test("resolveHumanForm: no emits selects the ack (click-done) category form", () => {
+  const r = resolveHumanForm({ emits: [], human: {} });
+  assertEquals(r.source, "category");
+  assertEquals(r.category, "ack");
+  assertEquals(r.formKey, HUMAN_ACK_FORM);
+});
+
+test("resolveHumanForm: a single artifact emit selects the publish category form", () => {
+  const r = resolveHumanForm({ emits: [artifact()], human: {} });
+  assertEquals(r.source, "category");
+  assertEquals(r.category, "publish");
+  assertEquals(r.formKey, HUMAN_PUBLISH_FORM);
+});
+
+test("resolveHumanForm: a single bare-version emit falls through to the generic form", () => {
+  // The publish form captures a pkg@version `resolvedArtifact`, which fails `version` validation in
+  // bindHumanEmits — so a lone `version` must use the generic single-value form, not publish.
+  const r = resolveHumanForm({ emits: [version()], human: {} });
+  assertEquals(r.source, "generic");
+  assertEquals(r.formKey, GENERIC_HUMAN_FORM);
+  assertEquals(r.category, null);
+});
+
+test("resolveHumanForm: a single non-artifact scalar emit falls through to the generic form", () => {
+  const r = resolveHumanForm({ emits: [str("approvalNote")], human: {} });
+  assertEquals(r.source, "generic");
+  assertEquals(r.formKey, GENERIC_HUMAN_FORM);
+  assertEquals(r.category, null);
+});
+
+test("regression: a single version resolves to a form whose capture key binds against `version`", () => {
+  // Guards the class: the resolved form's canonical capture key must produce a value that coerces
+  // against the emitted fact's type. The publish form captures `resolvedArtifact` (pkg@version),
+  // which FAILS `version` coercion — so a lone version must route to the generic `value` form.
+  const emit = version("publishedVersion");
+  const r = resolveHumanForm({ emits: [emit], human: {} });
+  assertEquals(r.formKey, GENERIC_HUMAN_FORM);
+  // Generic form's `value` capture binds cleanly against the version fact.
+  assertEquals(bindHumanEmits([emit], { value: "1.4.0" }).errors, []);
+  // Whereas the publish form's `resolvedArtifact` (a pkg@version) would NOT — the mismatch avoided.
+  assert(
+    bindHumanEmits([emit], { resolvedArtifact: "@nanobpm/urban@0.54.0" }).errors.length > 0,
+    "a pkg@version resolvedArtifact must not satisfy a bare-version emit",
+  );
+});
+
+test("resolveHumanForm: two-plus heterogeneous emits with no form gate the agent-router (null form)", () => {
+  const node = { emits: [artifact(), str("changelog")], human: {} };
+  const r = resolveHumanForm(node);
+  assertEquals(r.source, "agent-router");
+  assertEquals(r.formKey, null);
+  assert(needsAgentFormRouter(node), "needsAgentFormRouter must agree the router fires");
+});
+
+test("resolveHumanForm: an explicit form suppresses the agent-router even with many emits", () => {
+  const node = { emits: [artifact(), str("changelog"), version("v")], human: { formKey: "multi" } };
+  assertEquals(resolveHumanForm(node).source, "explicit");
+  assert(!needsAgentFormRouter(node), "an explicit form must pre-empt the router");
+});
+
+test("deriveHumanCategory: ack for empty, publish for one artifact, null for a lone version/scalar", () => {
+  assertEquals(deriveHumanCategory([]), "ack");
+  assertEquals(deriveHumanCategory([artifact()]), "publish");
+  // A lone bare `version` is NOT publish — the publish form captures a pkg@version resolvedArtifact,
+  // which fails `version` coercion; it falls through to the generic single-value form.
+  assertEquals(deriveHumanCategory([version()]), null);
+  assertEquals(deriveHumanCategory([str("x")]), null);
+  assertEquals(deriveHumanCategory([artifact(), version()]), null);
+});
+
+test("normalizeEmits: drops malformed declarations (non-record, blank name, unknown type)", () => {
+  const emits = [
+    artifact("good"),
+    { name: "", type: "string" },
+    { name: "bad", type: "nope" },
+    "junk",
+    { type: "string" },
+  ] as unknown as DeliveryFact[];
+  const out = normalizeEmits({ emits });
+  assertEquals(out.length, 1);
+  assertEquals(out[0].name, "good");
+});
+
+test("normalizeEmits: drops names the S0 validator would reject (dotted/non-identifier, over-long, duplicate)", () => {
+  const emits = [
+    str("good"),
+    { name: "dotted.name", type: "string" }, // fails FACT_NAME_PATTERN (would make <nodeId>.<fact> ambiguous)
+    { name: "1leading", type: "string" }, // leading digit — not a bare identifier
+    { name: "has space", type: "string" }, // whitespace — not an identifier
+    { name: `${"x".repeat(129)}`, type: "string" }, // exceeds FACT_NAME_MAX_LENGTH (128)
+    { name: "good", type: "version" }, // duplicate name — first (string) wins, this is dropped
+  ] as unknown as DeliveryFact[];
+  const out = normalizeEmits({ emits });
+  assertEquals(out.length, 1);
+  assertEquals(out[0].name, "good");
+  assertEquals(out[0].type, "string");
+});
+
+test("normalizeEmits: a name at exactly the 128-char cap is kept", () => {
+  const emits = [{ name: "x".repeat(128), type: "string" }] as unknown as DeliveryFact[];
+  const out = normalizeEmits({ emits });
+  assertEquals(out.length, 1);
+});
+
+// ── Typed emit binding ─────────────────────────────────────────────────────────────────────────
+
+test("bindHumanEmits: a no-emit node yields no facts and no errors regardless of captured form", () => {
+  const r = bindHumanEmits([], { note: "did it", value: "ignored" });
+  assertEquals(r.facts.length, 0);
+  assertEquals(r.errors.length, 0);
+});
+
+test("bindHumanEmits: a single artifact binds from the canonical resolvedArtifact capture key", () => {
+  const r = bindHumanEmits([artifact()], { resolvedArtifact: "@nanobpm/urban@0.54.0", note: "n" });
+  assertEquals(r.errors, []);
+  assertEquals(r.facts.length, 1);
+  assertEquals(r.facts[0].value, "@nanobpm/urban@0.54.0");
+  assertEquals(r.facts[0].type, "artifact");
+});
+
+test("bindHumanEmits: a single scalar binds from the generic form's `value` capture key", () => {
+  const r = bindHumanEmits([str("approvalNote")], { value: "ship it" });
+  assertEquals(r.errors, []);
+  assertEquals(r.facts[0].value, "ship it");
+});
+
+test("bindHumanEmits: a fact keyed by its own name wins over the canonical fallback", () => {
+  const r = bindHumanEmits([version("publishedVersion")], { publishedVersion: "1.4.0", value: "9.9.9" });
+  assertEquals(r.facts[0].value, "1.4.0");
+});
+
+test("bindHumanEmits: multi-emit binds each fact by its own name (no canonical fallback)", () => {
+  const emits = [artifact("art"), str("changelog")];
+  const r = bindHumanEmits(emits, { art: "@a/b@1.0.0", changelog: "notes" });
+  assertEquals(r.errors, []);
+  assertEquals(r.facts.length, 2);
+});
+
+test("bindHumanEmits: a missing declared fact is a path-qualified error", () => {
+  const r = bindHumanEmits([artifact("art")], { note: "n" });
+  assertEquals(r.facts.length, 0);
+  assertEquals(r.errors.length, 1);
+  assertStringIncludes(r.errors[0], "emits.art");
+});
+
+test("bindHumanEmits: an ill-typed artifact/version/url/number/boolean each errors", () => {
+  assertStringIncludes(bindHumanEmits([artifact("a")], { a: "no-at-sign" }).errors[0], "pkg@version");
+  assertStringIncludes(bindHumanEmits([version("v")], { v: "not a version" }).errors[0], "version");
+  assertStringIncludes(bindHumanEmits([{ name: "u", type: "url" }], { u: "not a url" }).errors[0], "URL");
+  assertStringIncludes(bindHumanEmits([{ name: "n", type: "number" }], { n: "abc" }).errors[0], "number");
+  assertStringIncludes(bindHumanEmits([{ name: "b", type: "boolean" }], { b: "maybe" }).errors[0], "boolean");
+});
+
+test("bindHumanEmits: an artifact with an ill-formed version segment errors", () => {
+  // A well-formed `pkg@version` shape but a version segment that is not a valid version must reject —
+  // the version segment validates the same way a bare `version` fact does (#263, shared VERSION_PATTERN).
+  assertStringIncludes(
+    bindHumanEmits([artifact("a")], { a: "@nanobpm/urban@not-a-version" }).errors[0],
+    "pkg@version",
+  );
+  assertEquals(bindHumanEmits([artifact("a")], { a: "@nanobpm/urban@not-a-version" }).facts.length, 0);
+  // A valid digit-led (optionally `v`-prefixed) version segment still passes.
+  assertEquals(bindHumanEmits([artifact("a")], { a: "@nanobpm/urban@0.54.0" }).facts[0].value, "@nanobpm/urban@0.54.0");
+  assertEquals(bindHumanEmits([artifact("a")], { a: "pkg@v2.0.0-rc.1" }).facts[0].value, "pkg@v2.0.0-rc.1");
+});
+
+test("bindHumanEmits: number/boolean/url coerce to canonical string serialisations", () => {
+  assertEquals(bindHumanEmits([{ name: "n", type: "number" }], { n: "42" }).facts[0].value, "42");
+  assertEquals(bindHumanEmits([{ name: "b", type: "boolean" }], { b: true }).facts[0].value, "true");
+  // A string boolean is trimmed before validating (like version/artifact/url), so a generic textfield
+  // capture with surrounding whitespace still binds to the canonical serialisation.
+  assertEquals(bindHumanEmits([{ name: "b", type: "boolean" }], { b: " true " }).facts[0].value, "true");
+  assertEquals(bindHumanEmits([{ name: "b", type: "boolean" }], { b: "false " }).facts[0].value, "false");
+  assertEquals(
+    bindHumanEmits([{ name: "u", type: "url" }], { u: "https://x.test/p" }).facts[0].value,
+    "https://x.test/p",
+  );
+  // A string fact is trimmed before returning (like version/artifact/url), so the canonical
+  // serialisation does not depend on incidental surrounding whitespace.
+  assertEquals(bindHumanEmits([{ name: "s", type: "string" }], { s: " foo " }).facts[0].value, "foo");
+});
+
+// ── Late-binding surfaces (#289) ─────────────────────────────────────────────────────────────────
+
+test("humanEmitBind: builds a `<nodeId>.<fact>` qualified bind map (empty for a no-emit node)", () => {
+  const { facts } = bindHumanEmits([artifact("resolvedArtifact")], { resolvedArtifact: "@a/b@1.0.0" });
+  assertEquals(humanEmitBind("manual-publish", facts), { "manual-publish.resolvedArtifact": "@a/b@1.0.0" });
+  assertEquals(humanEmitBind("x", []), {});
+});
+
+test("renderHumanEmitBrief: empty for no facts; pins each name→value otherwise", () => {
+  assertEquals(renderHumanEmitBrief([]), "");
+  const { facts } = bindHumanEmits([artifact("resolvedArtifact")], { resolvedArtifact: "@nanobpm/urban@0.54.0" });
+  const brief = renderHumanEmitBrief(facts);
+  assertStringIncludes(brief, "Human-emitted facts");
+  assertStringIncludes(brief, "`resolvedArtifact` (artifact) → `@nanobpm/urban@0.54.0`");
+});
+
+test("renderHumanEmitBrief: neutralises backticks/newlines in a value so the inline-code span can't break or inject", () => {
+  const { facts } = bindHumanEmits([str("note")], { note: "a`b\nc" });
+  const brief = renderHumanEmitBrief(facts);
+  assertStringIncludes(brief, "`note` (string) → `a'b c`");
+  assert(!brief.includes("a`b"), "raw backtick must not survive into the inline-code span");
+});
+
+// ── Cross-layer / structural guards ──────────────────────────────────────────────────────────────
+
+const bpmn = readFileSync("resources/processes/delivery-human.bpmn", "utf8");
+const flat = bpmn.replace(/\s+/g, " ");
+
+test("BPMN: the human node is a native SLA-bounded userTask backed by the generic form", () => {
+  const task = flat.match(
+    new RegExp(`<bpmn:userTask\\b[^>]*\\bid="${DELIVERY_HUMAN_ELEMENT}"[\\s\\S]*?</bpmn:userTask>`),
+  );
+  assert(task, `${DELIVERY_HUMAN_ELEMENT} must be a <bpmn:userTask>`);
+  assertStringIncludes(task![0], "<zeebe:userTask", "must be a native (Zeebe) user task");
+  assertStringIncludes(task![0], `formId="${GENERIC_HUMAN_FORM}"`, "must attach the generic typed-emit form");
+  assertStringIncludes(task![0], 'candidateGroups="operators"', "must surface to operators");
+  // The interrupting SLA boundary timer bounds the node — it nags/times out, never silently wedges.
+  const boundary = flat.match(
+    new RegExp(`<bpmn:boundaryEvent\\b[^>]*\\battachedToRef="${DELIVERY_HUMAN_ELEMENT}"[\\s\\S]*?</bpmn:boundaryEvent>`),
+  );
+  assert(boundary, "an SLA boundary timer must be attached to the human task");
+  assertStringIncludes(boundary![0], "=escalationSlaTimeout", "the SLA reuses the escalation timeout var");
+  assertStringIncludes(boundary![0], "<bpmn:timerEventDefinition", "the SLA arm must be a timer");
+});
+
+test("BPMN: humanOutcome is set on BOTH the completion and the SLA-timeout path", () => {
+  // Symmetry with readiness-gate.bpmn's `gateOutcome`: a caller reading process variables must be
+  // able to distinguish a completed human step from one the SLA timer escalated. The userTask sets
+  // "completed" on the normal path; the timeout end event must set "escalated" — otherwise the
+  // escalation path ends with humanOutcome unset and the two outcomes are indistinguishable.
+  assertStringIncludes(
+    flat,
+    '<zeebe:output source="=&#34;completed&#34;" target="humanOutcome" />',
+    "the completion path must set humanOutcome=completed",
+  );
+  const escalated = flat.match(
+    /<bpmn:endEvent\b[^>]*\bid="human-escalated"[\s\S]*?<\/bpmn:endEvent>/,
+  );
+  assert(escalated, "the SLA-timeout end event human-escalated must exist");
+  assertStringIncludes(
+    escalated![0],
+    '<zeebe:input source="=&#34;escalated&#34;" target="humanOutcome" />',
+    "the SLA-timeout path must set humanOutcome=escalated",
+  );
+});
+
+test("drift guard: the human element is completer-answerable and surfaces on the inbox", () => {
+  // The canonical completer refuses any user task outside ESCALATION_TASK_ELEMENTS, so a model that
+  // parks on delivery-human-task while the code doesn't accept it would deploy but be unanswerable
+  // (by human OR agent, ADR 0046) — the silent-drift failure this guard closes.
+  assert(
+    ESCALATION_TASK_ELEMENTS.has(DELIVERY_HUMAN_ELEMENT),
+    "ESCALATION_TASK_ELEMENTS must accept the delivery human node",
+  );
+  // And it must carry an inbox label, or the parked task is invisible on the Tasks cockpit.
+  assert(
+    typeof USER_TASK_KIND_LABELS[DELIVERY_HUMAN_ELEMENT] === "string",
+    "USER_TASK_KIND_LABELS must label the delivery human node",
+  );
+});

package/app/deliveryHuman.ts

@@ -0,0 +1,371 @@
+// nano-workforce — the `human` delivery-graph node (ADR 0005, slice S3). A `human` node promotes
+// ADR 0002's user-task+form machinery from an *exception* (something broke) to a *scheduled node* (a
+// planned "now do X" stop that BLOCKS its dependents, is answerable by a human OR an agent — ADR 0046
+// — is SLA-bounded so it nags and cannot silently wedge the graph, and can EMIT a typed fact its form
+// captures which late-binds downstream). It is the emit-side of #263's emit-vs-poll dual: a *human*
+// emitter is the same shape as an automated one (the `capability`/`pr` probe's `resolvedArtifact`
+// bind), which is what unifies human and automated steps in one graph.
+//
+// This module owns the PURE, side-effect-free machinery the compiler (S1, author-time) and the
+// runner (S4, runtime) reuse — it never itself creates a user task or completes one. Execution stays
+// engine-native (Decision 2): the human node's body is the deployed `delivery-human` `bpmn:userTask`
+// (`resources/processes/delivery-human.bpmn`, an SLA-bounded scheduled user task), completion routes
+// through the ONE canonical completer (`completeEscalationAsAgent`/`completeEscalationAsHuman`,
+// `app/agentCompletion.ts`) because `DELIVERY_HUMAN_ELEMENT` is registered in
+// `ESCALATION_TASK_ELEMENTS`, and the emitted fact threads downstream via the #289 brief-appender /
+// bound-output pattern (`renderResolvedDepsBrief` / the `caps-resolved` → `appendPrompt` recipe).
+//
+// The three pure concerns:
+//   1. FORM RESOLUTION — specific-else-generic (Decision 4): an explicit `human.formKey` on the node,
+//      else a form SELECTED by node category (derived from the node's typed emits), else a GENERIC
+//      fallback form that STILL captures a typed emitted fact — so every human node can emit even with
+//      no bespoke form. A runtime agent-form-router is a GATED exception: it fires ONLY when a node
+//      activates with no statically resolvable form (multiple heterogeneous emits, no explicit/bespoke
+//      form), never in the common path — the same "deterministic default, agent judgment as the escape
+//      hatch" grain as the capability probe's empirical verifier.
+//   2. TYPED EMIT — validate + coerce the completed form output against the node's declared `emits[]`
+//      (Decision 3/4 — binds are validated, not stringly), producing the typed facts the node hands
+//      forward. A "click done" node declares no emits — the degenerate no-emit case.
+//   3. LATE-BINDING — render the emitted facts into a downstream node's brief (`renderHumanEmitBrief`,
+//      mirroring `renderResolvedDepsBrief`) and into a qualified bind map keyed `<nodeId>.<fact>`
+//      (`humanEmitBind`, mirroring the probe `bind`) so a downstream `capability`/`npm`/`pr` edge
+//      binds and pins exactly the value the human handed forward.
+import type { DeliveryFact, DeliveryNodeHuman } from "../nano-generated/api-io.d.ts";
+import { DELIVERY_FACT_TYPES, type DeliveryFactType, FACT_NAME_MAX_LENGTH, FACT_NAME_PATTERN } from "./deliveryGraph.ts";
+
+/** The single BPMN `bpmn:userTask` element id every `human` delivery-graph node schedules its work
+ *  as (`resources/processes/delivery-human.bpmn`). One reusable engine-native body, instantiated once
+ *  per human node (mirroring the one `readiness-gate` process instantiated per `wait` node). It is
+ *  registered in `ESCALATION_TASK_ELEMENTS` (`app/agentCompletion.ts`) so a human OR an agent
+ *  (ADR 0046) can complete it through the ONE canonical `complete-user-task` / `agent-complete` door,
+ *  and in `USER_TASK_KIND_LABELS` (`app/userTasks.ts`) so it surfaces on the Tasks inbox. */
+export const DELIVERY_HUMAN_ELEMENT = "delivery-human-task";
+
+/** The GENERIC fallback form (Decision 4, step 3): captures ONE typed value into the node's single
+ *  declared emitted fact, so a human node with no explicit/category form can STILL emit downstream. */
+export const GENERIC_HUMAN_FORM = "delivery-human-generic";
+
+/** The "click done" category form: a degenerate no-emit acknowledgement ("now do X" → done). */
+export const HUMAN_ACK_FORM = "delivery-human-ack";
+
+/** The manual-publish category form: captures a `resolvedArtifact` (`pkg@version`) — the motivating
+ *  case where a human hands a just-published version forward to a downstream `capability`/`npm`/`pr`
+ *  edge. */
+export const HUMAN_PUBLISH_FORM = "delivery-human-publish";
+
+/** A human node's derived CATEGORY — a coarse classification of what the node emits, used to SELECT a
+ *  bespoke form (Decision 4, step 2) without the author naming one. Derived from the node's typed
+ *  `emits[]` so the same typed-fact declaration that drives late-binding also drives form selection —
+ *  one source of truth, no second author-facing knob (the frozen S0 `human` config carries only
+ *  `formKey`/`prompt`). `null` ⇒ no bespoke category form applies (fall through to generic/router). */
+export type HumanNodeCategory = "ack" | "publish";
+
+/** Category → its bespoke form. Kept as the single source of truth for "which form a category selects"
+ *  so {@link resolveHumanForm} and any preview/compile step agree. */
+export const HUMAN_CATEGORY_FORMS: Readonly<Record<HumanNodeCategory, string>> = {
+  ack: HUMAN_ACK_FORM,
+  publish: HUMAN_PUBLISH_FORM,
+};
+
+/** How a human node's form was resolved. `explicit` — the node named a `human.formKey`; `category` —
+ *  a form was selected by the node's derived category; `generic` — the typed-emit-capturing fallback;
+ *  `agent-router` — NOTHING statically resolved, so a runtime agent must pick/assemble one (the gated
+ *  exception). */
+export type HumanFormSource = "explicit" | "category" | "generic" | "agent-router";
+
+/** The resolved form for a human node (Decision 4). `formKey` is the `.form` to attach — `null` ONLY
+ *  for `agent-router`, where the runtime supplies it. `category` records the derived category when one
+ *  applied. `reason` is a human-readable one-liner for the compiled preview. */
+export interface HumanFormResolution {
+  readonly source: HumanFormSource;
+  readonly formKey: string | null;
+  readonly category: HumanNodeCategory | null;
+  readonly emits: readonly DeliveryFact[];
+  readonly reason: string;
+}
+
+/** A typed fact a completed human node hands forward — its declared `name`/`type` plus the validated,
+ *  canonically-serialised `value` (a string, like the probe `bind`, so it threads uniformly into
+ *  prompts, messages, and qualified bind maps). */
+export interface BoundFact {
+  readonly name: string;
+  readonly type: DeliveryFactType;
+  readonly value: string;
+}
+
+/** The outcome of binding a completed form's output to a node's declared emits: the typed `facts` in
+ *  declaration order plus any path-qualified `errors` (a missing/ill-typed declared fact). An empty
+ *  `emits` yields `{ facts: [], errors: [] }` — the degenerate no-emit "click done" case. */
+export interface HumanEmitResult {
+  readonly facts: readonly BoundFact[];
+  readonly errors: readonly string[];
+}
+
+/** Narrow an untyped value to a plain object so its fields can be read defensively. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** True when `value` is one of the closed set of delivery fact types (a type guard, so the pure
+ *  form/emit logic narrows without an `as` assertion). */
+function isDeliveryFactType(value: unknown): value is DeliveryFactType {
+  return typeof value === "string" && DELIVERY_FACT_TYPES.some((t) => t === value);
+}
+
+/** Normalise a human node's `emits[]` to the well-formed, typed declarations, dropping anything the
+ *  S0 validator would already have rejected (a non-record entry, a blank name, a name that is not a
+ *  dot-free identifier within the 128-char cap, a duplicate name, or an unknown type) so the pure
+ *  form/emit logic never trips on a malformed declaration — the graph is validated upstream by
+ *  `validateDeliveryGraph`, this is defence in depth. Fact-name pattern/length are the SAME canonical
+ *  constants the validator enforces (`FACT_NAME_PATTERN`/`FACT_NAME_MAX_LENGTH`), so a dotted /
+ *  over-long / duplicate name can't slip through here and make `<nodeId>.<fact>` binding ambiguous. */
+export function normalizeEmits(node: Pick<DeliveryNodeHuman, "emits">): DeliveryFact[] {
+  const raw = node.emits;
+  if (!Array.isArray(raw)) return [];
+  const facts: DeliveryFact[] = [];
+  const seen = new Set<string>();
+  for (const entry of raw) {
+    if (!isRecord(entry)) continue;
+    const name = entry.name;
+    const type = entry.type;
+    if (typeof name !== "string" || name.length === 0) continue;
+    if (name.length > FACT_NAME_MAX_LENGTH || !FACT_NAME_PATTERN.test(name)) continue;
+    if (seen.has(name)) continue;
+    if (!isDeliveryFactType(type)) continue;
+    seen.add(name);
+    facts.push({ name, type, ...(typeof entry.description === "string" ? { description: entry.description } : {}) });
+  }
+  return facts;
+}
+
+/** Derive a human node's CATEGORY from its typed emits (Decision 4, step 2), or `null` when no bespoke
+ *  category form applies:
+ *   - `ack` — the node emits NOTHING (a "click done" acknowledgement).
+ *   - `publish` — the node emits EXACTLY ONE `artifact` fact (a `pkg@version` handle — the manual-
+ *     publish-hands-a-version-forward case), which the bespoke publish form captures as a
+ *     `resolvedArtifact`. A lone `version` (a BARE version, e.g. `1.4.0`) does NOT map here: the
+ *     publish form captures a `pkg@version` into `resolvedArtifact`, which fails `version` coercion in
+ *     {@link bindHumanEmits} — so a single `version` falls through to the generic single-value form
+ *     (which captures a bare `value`, validated against the `version` type).
+ *   - `null` — a single non-artifact scalar/url/version fact (the generic fallback captures it), OR
+ *     two-or-more facts (no bespoke or generic single-value form can hold them → the agent-router
+ *     territory).
+ *  Kept coarse ON PURPOSE: bespoke category forms are a deterministic convenience, not an open
+ *  taxonomy; anything they don't cover falls through to the generic fallback or the gated router. */
+export function deriveHumanCategory(emits: readonly DeliveryFact[]): HumanNodeCategory | null {
+  if (emits.length === 0) return "ack";
+  if (emits.length === 1 && emits[0].type === "artifact") return "publish";
+  return null;
+}
+
+/** Resolve which form a human node uses, specific-else-generic (ADR 0005 Decision 4). Preference:
+ *    1. `explicit`     — the node carries a non-blank `human.formKey`.
+ *    2. `category`     — the node's derived category selects a bespoke form ({@link deriveHumanCategory}).
+ *    3. `generic`      — the node emits ≤1 fact, captured by the generic typed-emit fallback form.
+ *    4. `agent-router` — NOTHING statically resolved (≥2 heterogeneous emits, no explicit/bespoke
+ *                        form): a runtime agent must pick/assemble a form. This is the GATED escape
+ *                        hatch — it fires ONLY here, never in the common path.
+ *  Pure and total (never throws): the graph is shape/semantic-validated upstream, and malformed emits
+ *  are normalised away, so this always returns a resolution. Author-time callers (the S1 compiler)
+ *  attach `formKey` deterministically so the resolved form is visible in the preview; only the
+ *  `agent-router` case defers to runtime. */
+export function resolveHumanForm(node: Pick<DeliveryNodeHuman, "emits" | "human">): HumanFormResolution {
+  const emits = normalizeEmits(node);
+  const explicit = node.human?.formKey;
+  if (typeof explicit === "string" && explicit.trim().length > 0) {
+    return {
+      source: "explicit",
+      formKey: explicit.trim(),
+      category: null,
+      emits,
+      reason: `explicit form "${explicit.trim()}" attached on the node`,
+    };
+  }
+  const category = deriveHumanCategory(emits);
+  if (category !== null) {
+    return {
+      source: "category",
+      formKey: HUMAN_CATEGORY_FORMS[category],
+      category,
+      emits,
+      reason:
+        category === "ack"
+          ? "no emitted fact — the generic acknowledgement (click-done) form"
+          : `emits a single ${emits[0].type} fact — the manual-publish form (captures a resolvedArtifact)`,
+    };
+  }
+  if (emits.length <= 1) {
+    return {
+      source: "generic",
+      formKey: GENERIC_HUMAN_FORM,
+      category: null,
+      reason: `emits a single ${emits[0].type} fact — the generic typed-emit fallback form`,
+      emits,
+    };
+  }
+  return {
+    source: "agent-router",
+    formKey: null,
+    category: null,
+    emits,
+    reason:
+      `emits ${emits.length} typed facts and carries no explicit/bespoke form — no static form can ` +
+      "capture them, so a runtime agent-form-router must assemble one (the gated exception)",
+  };
+}
+
+/** True when a human node resolves to the gated runtime agent-form-router — i.e. nothing statically
+ *  resolved. A thin predicate over {@link resolveHumanForm} so callers can branch without re-deriving. */
+export function needsAgentFormRouter(node: Pick<DeliveryNodeHuman, "emits" | "human">): boolean {
+  return resolveHumanForm(node).source === "agent-router";
+}
+
+/** The canonical form-field keys a bespoke/generic form captures its single typed value under, tried
+ *  (in addition to the fact's own name) when binding a single-fact node's output. The generic form
+ *  captures `value`; the publish form captures `resolvedArtifact`. */
+const CANONICAL_VALUE_KEYS = ["resolvedArtifact", "value"] as const;
+
+/** The ONE accepted shape of a bare version string (an optional `v` then a digit-led `[\w.+-]` run,
+ *  e.g. `1.4.0`, `v2.0.0-rc.1`). The single source of truth shared by the `version` fact type AND the
+ *  version segment of an `artifact` handle — so a `pkg@version` artifact validates its version the
+ *  same way a bare `version` does, with no second notion of "valid version" to drift. */
+const VERSION_PATTERN = /^v?\d[\w.+-]*$/;
+
+/** Coerce + validate one raw form value against a declared fact type, returning the canonical string
+ *  serialisation or an error message. Typed so a bind is validated, not stringly (Decision 3/4): an
+ *  `artifact` must be `pkg@version` (with a well-formed version segment), a `version` a bare version, a
+ *  `url` a parseable location, a `number` finite, a `boolean` a real boolean. */
+function coerceFactValue(type: DeliveryFactType, raw: unknown): { value: string } | { error: string } {
+  switch (type) {
+    case "string": {
+      if (typeof raw !== "string" || raw.trim() === "") return { error: "expected a non-empty string" };
+      // Return the trimmed value, mirroring the other string-like types (version/artifact/url) so the
+      // canonical serialisation does not depend on incidental surrounding whitespace.
+      return { value: raw.trim() };
+    }
+    case "number": {
+      const n = typeof raw === "number" ? raw : typeof raw === "string" && raw.trim() !== "" ? Number(raw) : Number.NaN;
+      if (!Number.isFinite(n)) return { error: "expected a finite number" };
+      return { value: String(n) };
+    }
+    case "boolean": {
+      if (typeof raw === "boolean") return { value: String(raw) };
+      // Trim before validating, mirroring the other string-like types (version/artifact/url) so a
+      // boolean captured via the generic textfield (e.g. " true ") is not needlessly brittle.
+      const trimmed = typeof raw === "string" ? raw.trim() : raw;
+      if (trimmed === "true" || trimmed === "false") return { value: trimmed };
+      return { error: "expected a boolean (true/false)" };
+    }
+    case "version": {
+      if (typeof raw !== "string" || !VERSION_PATTERN.test(raw.trim())) {
+        return { error: "expected a version string (e.g. 1.4.0)" };
+      }
+      return { value: raw.trim() };
+    }
+    case "artifact": {
+      if (typeof raw !== "string") return { error: "expected a pkg@version artifact handle" };
+      const at = raw.trim().lastIndexOf("@");
+      const name = raw.trim().slice(0, at);
+      const version = raw.trim().slice(at + 1);
+      if (at <= 0 || name.length === 0 || version.length === 0 || !VERSION_PATTERN.test(version)) {
+        return { error: "expected a pkg@version artifact handle (e.g. @nanobpm/urban@0.54.0)" };
+      }
+      return { value: raw.trim() };
+    }
+    case "url": {
+      if (typeof raw !== "string" || raw.trim() === "") return { error: "expected a URL" };
+      try {
+        new URL(raw.trim());
+      } catch {
+        return { error: "expected a valid URL (with a scheme)" };
+      }
+      return { value: raw.trim() };
+    }
+    default:
+      return { error: `unknown fact type "${type}"` };
+  }
+}
+
+/** Bind a completed human node's form `output` to its declared `emits[]` (Decision 3/4). For each
+ *  declared fact, read its value from the output — preferring the fact's own `name` key, then, for a
+ *  single-fact node, the canonical capture keys the generic/publish forms use (`resolvedArtifact` /
+ *  `value`) — and validate/coerce it against the fact's type. Returns the typed facts in declaration
+ *  order plus one error per missing/ill-typed declared fact. A node with no declared emits yields no
+ *  facts and no errors (the degenerate "click done" case) regardless of what the form captured.
+ *
+ *  This is the typed-emit contract the runner (S4) enforces on completion before threading the facts
+ *  downstream via {@link humanEmitBind} / {@link renderHumanEmitBrief} — the emit-side of #263. */
+export function bindHumanEmits(
+  emits: readonly DeliveryFact[],
+  output: Record<string, unknown> | null | undefined,
+): HumanEmitResult {
+  const out = isRecord(output) ? output : {};
+  const facts: BoundFact[] = [];
+  const errors: string[] = [];
+  const single = emits.length === 1;
+  for (const fact of emits) {
+    let raw = out[fact.name];
+    if (raw === undefined && single) {
+      for (const key of CANONICAL_VALUE_KEYS) {
+        if (out[key] !== undefined) {
+          raw = out[key];
+          break;
+        }
+      }
+    }
+    if (raw === undefined || raw === null) {
+      errors.push(`emits.${fact.name}: no value captured for the declared ${fact.type} fact`);
+      continue;
+    }
+    const coerced = coerceFactValue(fact.type, raw);
+    if ("error" in coerced) {
+      errors.push(`emits.${fact.name}: ${coerced.error}`);
+      continue;
+    }
+    facts.push({ name: fact.name, type: fact.type, value: coerced.value });
+  }
+  return { facts, errors };
+}
+
+/** Build the qualified bind map a human node's emitted facts publish downstream, keyed exactly as a
+ *  delivery edge references them — `<nodeId>.<fact>` (mirroring the probe `bind: Record<string,string>`
+ *  and the `capability` kind's `resolvedArtifact`). A downstream edge `from: "<nodeId>.<fact>"` binds
+ *  and PINS the human-handed value from this map. Empty for a no-emit node. */
+export function humanEmitBind(nodeId: string, facts: readonly BoundFact[]): Record<string, string> {
+  const bind: Record<string, string> = {};
+  for (const fact of facts) bind[`${nodeId}.${fact.name}`] = fact.value;
+  return bind;
+}
+
+/** Neutralise a human-submitted value before it is embedded in a Markdown inline-code span in the
+ *  brief. A raw backtick would terminate the span (corrupting the brief and letting free-form form
+ *  text inject unintended prompt content into the downstream agent's prompt), and a newline would
+ *  break the span; collapse both. Display-only — the authoritative value published downstream via
+ *  {@link humanEmitBind} is untouched, so the pinned contract is unaffected. */
+function inlineCodeSafe(value: string): string {
+  return value.replace(/`/g, "'").replace(/\r?\n/g, " ");
+}
+
+/** Render the "human-emitted facts" brief appended to a downstream node's prompt once a human node
+ *  completes and hands its typed facts forward (#289 §3), mirroring `renderResolvedDepsBrief`. It pins
+ *  each `name → value` the human declared + captured so a downstream agent/edge consumes EXACTLY that
+ *  value — no re-derivation, no human re-entry. Returns "" for a no-emit node so callers concatenate
+ *  unconditionally (the same `if X = null then "" else X` FEEL convention as the other briefs). */
+export function renderHumanEmitBrief(facts: readonly BoundFact[]): string {
+  if (facts.length === 0) return "";
+  const lines = [
+    "",
+    "",
+    "---",
+    "",
+    "**Human-emitted facts (authoritative — a scheduled human step handed these forward):**",
+    "",
+    "A `human` node upstream captured and emitted the typed values below. Consume/pin exactly these —",
+    "do NOT re-derive, float, or re-request them:",
+    "",
+  ];
+  for (const fact of facts) lines.push(`- \`${fact.name}\` (${fact.type}) → \`${inlineCodeSafe(fact.value)}\``);
+  lines.push("");
+  lines.push("These are the contract the human handed forward; a different value is a different run.");
+  return lines.join("\n");
+}

package/app/userTasks.ts

@@ -19,6 +19,7 @@
 // it open.
 import type { DataLayer } from "@nanobpm/urban";
 import { CONFORMANCE_ESCALATION_ELEMENT } from "./conformance.ts";
+import { DELIVERY_HUMAN_ELEMENT } from "./deliveryHuman.ts";
 import { FEATURE_BLOCKED_ELEMENT, FEATURE_ESCALATION_ELEMENT, type FeatureEscalationRow } from "./feature.ts";
 import type { PlanReview } from "./plan.ts";
 import type { TrialMergeAuditRow } from "./trialMerge.ts";
@@ -76,13 +77,14 @@ export const USER_TASK_KIND_LABELS: Readonly<Record<string, string>> = {
   [PR_WAIT_ANSWER_ELEMENT]: "PR review",
   [PR_WAIT_MERGE_ANSWER_ELEMENT]: "PR merge",
   [CONFORMANCE_ESCALATION_ELEMENT]: "Conformance review",
+  [DELIVERY_HUMAN_ELEMENT]: "Delivery: human step",
 };
 
 /** The denormalised context the poller has resolved for an open escalation user task. */
 export interface UserTaskContext {
   userTaskKey: string;
   elementId: string;
-  subjectType: "feature" | "plan" | "pr";
+  subjectType: "feature" | "plan" | "pr" | "delivery";
   subjectKey: string;
   /** The subject's human-readable title from its own row (`feature_runs`/`plans`/`pull_requests`.
    *  `title`). Optional/blank tolerated — `buildUserTaskRow` coalesces it to `subjectKey` so the

package/package.json

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

package/resources/forms/delivery-human-ack.form

@@ -0,0 +1,19 @@
+{
+  "id": "delivery-human-ack",
+  "schemaVersion": 18,
+  "type": "default",
+  "components": [
+    {
+      "type": "textarea",
+      "key": "prompt",
+      "label": "Now do this",
+      "description": "The scheduled human step this delivery graph is waiting on. Complete it once done — this node emits nothing (the degenerate click-done case) and simply unblocks its dependents.",
+      "readonly": true
+    },
+    {
+      "type": "textarea",
+      "key": "note",
+      "label": "Note (optional)"
+    }
+  ]
+}

package/resources/forms/delivery-human-generic.form

@@ -0,0 +1,28 @@
+{
+  "id": "delivery-human-generic",
+  "schemaVersion": 18,
+  "type": "default",
+  "components": [
+    {
+      "type": "textarea",
+      "key": "prompt",
+      "label": "Now do this",
+      "description": "The scheduled human step this delivery graph is waiting on.",
+      "readonly": true
+    },
+    {
+      "type": "textfield",
+      "key": "value",
+      "label": "Emitted value",
+      "description": "The typed value this step hands forward to its downstream dependents. Validated against the node's declared emitted fact.",
+      "validate": {
+        "required": true
+      }
+    },
+    {
+      "type": "textarea",
+      "key": "note",
+      "label": "Note (optional)"
+    }
+  ]
+}

package/resources/forms/delivery-human-publish.form

@@ -0,0 +1,28 @@
+{
+  "id": "delivery-human-publish",
+  "schemaVersion": 18,
+  "type": "default",
+  "components": [
+    {
+      "type": "textarea",
+      "key": "prompt",
+      "label": "Now do this (manual publish)",
+      "description": "The manual step no automation can cross — e.g. an OTP publish + OIDC trusted-publishing setup. Complete it once the artifact is published.",
+      "readonly": true
+    },
+    {
+      "type": "textfield",
+      "key": "resolvedArtifact",
+      "label": "Resolved artifact (pkg@version)",
+      "description": "The exact published handle to hand forward, e.g. @nanobpm/urban@0.54.0. A downstream capability/npm/pr edge binds and pins this.",
+      "validate": {
+        "required": true
+      }
+    },
+    {
+      "type": "textarea",
+      "key": "note",
+      "label": "Note (optional)"
+    }
+  ]
+}

package/resources/processes/delivery-human.bpmn

@@ -0,0 +1,87 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI" xmlns:dc="http://www.omg.org/spec/DD/20100524/DC" xmlns:di="http://www.omg.org/spec/DD/20100524/DI" xmlns:zeebe="http://camunda.org/schema/zeebe/1.0" id="Definitions_nano_workforce_delivery_human" targetNamespace="http://nanobpm.io/nano-workforce">
+  <bpmn:process id="delivery-human" name="Delivery graph — human node (scheduled user task)" isExecutable="true">
+    <bpmn:startEvent id="Start" name="Human node scheduled">
+      <bpmn:outgoing>f_start</bpmn:outgoing>
+    </bpmn:startEvent>
+    <bpmn:userTask id="delivery-human-task" name="Delivery: human step (now do X)">
+      <bpmn:extensionElements>
+        <zeebe:formDefinition formId="delivery-human-generic" />
+        <zeebe:userTask />
+        <zeebe:assignmentDefinition candidateGroups="operators" assignee="=if (is defined(escalationAssignee) and escalationAssignee != null and trim(string(escalationAssignee)) != &#34;&#34;) then escalationAssignee else null" />
+        <zeebe:ioMapping>
+          <zeebe:output source="=&#34;completed&#34;" target="humanOutcome" />
+          <zeebe:output source="=if (is defined(value)) then value else null" target="humanEmitValue" />
+          <zeebe:output source="=if (is defined(resolvedArtifact)) then resolvedArtifact else null" target="humanEmitArtifact" />
+          <zeebe:output source="=if (is defined(note)) then note else null" target="humanNote" />
+        </zeebe:ioMapping>
+      </bpmn:extensionElements>
+      <bpmn:incoming>f_start</bpmn:incoming>
+      <bpmn:outgoing>f_done</bpmn:outgoing>
+    </bpmn:userTask>
+    <bpmn:boundaryEvent id="be_delivery_human_sla" name="SLA elapsed" attachedToRef="delivery-human-task">
+      <bpmn:outgoing>f_sla</bpmn:outgoing>
+      <bpmn:timerEventDefinition id="ted_delivery_human_sla">
+        <bpmn:timeDuration xsi:type="bpmn:tFormalExpression">=escalationSlaTimeout</bpmn:timeDuration>
+      </bpmn:timerEventDefinition>
+    </bpmn:boundaryEvent>
+    <bpmn:endEvent id="human-done" name="Human step done (fact emitted)">
+      <bpmn:incoming>f_done</bpmn:incoming>
+    </bpmn:endEvent>
+    <bpmn:endEvent id="human-escalated" name="Human step timed out (escalated)">
+      <bpmn:extensionElements>
+        <zeebe:ioMapping>
+          <zeebe:input source="=&#34;escalated&#34;" target="humanOutcome" />
+        </zeebe:ioMapping>
+      </bpmn:extensionElements>
+      <bpmn:incoming>f_sla</bpmn:incoming>
+    </bpmn:endEvent>
+    <bpmn:sequenceFlow id="f_start" sourceRef="Start" targetRef="delivery-human-task" />
+    <bpmn:sequenceFlow id="f_done" sourceRef="delivery-human-task" targetRef="human-done" />
+    <bpmn:sequenceFlow id="f_sla" sourceRef="be_delivery_human_sla" targetRef="human-escalated" />
+  </bpmn:process>
+  <bpmndi:BPMNDiagram id="BPMNDiagram_delivery-human">
+    <bpmndi:BPMNPlane id="BPMNPlane_delivery-human" bpmnElement="delivery-human">
+      <bpmndi:BPMNShape id="BPMNShape_Start" bpmnElement="Start">
+        <dc:Bounds x="80" y="102" width="36" height="36" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="60" y="143" width="76" height="28" />
+        </bpmndi:BPMNLabel>
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_delivery-human-task" bpmnElement="delivery-human-task">
+        <dc:Bounds x="216" y="80" width="100" height="80" />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_human-done" bpmnElement="human-done">
+        <dc:Bounds x="416" y="102" width="36" height="36" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="396" y="143" width="76" height="42" />
+        </bpmndi:BPMNLabel>
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_human-escalated" bpmnElement="human-escalated">
+        <dc:Bounds x="416" y="262" width="36" height="36" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="394" y="303" width="81" height="42" />
+        </bpmndi:BPMNLabel>
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_be_delivery_human_sla" bpmnElement="be_delivery_human_sla">
+        <dc:Bounds x="248" y="142" width="36" height="36" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="164" y="183" width="84" height="14" />
+        </bpmndi:BPMNLabel>
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_start" bpmnElement="f_start">
+        <di:waypoint x="116" y="120" />
+        <di:waypoint x="216" y="120" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_done" bpmnElement="f_done">
+        <di:waypoint x="316" y="120" />
+        <di:waypoint x="416" y="120" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_sla" bpmnElement="f_sla">
+        <di:waypoint x="266" y="178" />
+        <di:waypoint x="266" y="280" />
+        <di:waypoint x="416" y="280" />
+      </bpmndi:BPMNEdge>
+    </bpmndi:BPMNPlane>
+  </bpmndi:BPMNDiagram>
+</bpmn:definitions>

package/test/derivation-parity/derivation-parity.test.ts

@@ -50,11 +50,12 @@ test("every corpus model is either ported or has a documented blocker", () => {
     "convergence-loop",
     "merge-loop",
     "plan-fanout",
+    "delivery-human",
   ];
   assertEquals(
     PORTS.map((p) => p.model),
     expected,
-    "PORTS must cover all seven goldens in the epic's authoring order",
+    "PORTS must cover all eight goldens in the epic's authoring order",
   );
   for (const port of PORTS) {
     assert(
@@ -66,14 +67,21 @@ test("every corpus model is either ported or has a documented blocker", () => {
 
 // The blockers are not guesses — prove each against the goldens themselves.
 //
-// CLASS 1 — five goldens have MORE THAN ONE top-level start and/or end event,
+// CLASS 1 — six goldens have MORE THAN ONE top-level start and/or end event,
 // which the published `@nanobpm/workflow@0.12.0` compiler (a single
 // `<startEvent id="Start">` + single `<endEvent id="End">`) cannot derive.
 test("class-1 blocked goldens genuinely have multiple top-level start/end events", () => {
   const countTag = (xml: string, tag: string): number =>
     (xml.match(new RegExp(`<bpmn:${tag}\\b`, "g")) ?? []).length;
 
-  const multiStartEndBlocked = new Set(["spine-demo", "readiness-gate", "feature", "merge-loop", "plan-fanout"]);
+  const multiStartEndBlocked = new Set([
+    "spine-demo",
+    "readiness-gate",
+    "feature",
+    "merge-loop",
+    "plan-fanout",
+    "delivery-human",
+  ]);
   for (const model of multiStartEndBlocked) {
     const xml = readFileSync(goldenPath(model), "utf8");
     const starts = countTag(xml, "startEvent");

package/test/derivation-parity/flows.ts

@@ -9,13 +9,13 @@
 // the structurally-derivable goldens at full whole-model parity, park the rest
 // pending an upstream construct, and do NOT relax to node-surface parity):
 //
-//   • `retro` is a GREEN whole-model parity port (see below). The remaining six
+//   • `retro` is a GREEN whole-model parity port (see below). The remaining seven
 //     goldens are `blockedReason`-parked, in TWO distinct classes, each awaiting
 //     an upstream `@nanobpm/workflow` (nano-ide) construct + re-release — never a
 //     golden edit and never relaxed acceptance:
 //
 //     (1) MULTI top-level start/end (spine-demo, readiness-gate, feature,
-//         merge-loop, plan-fanout). `@nanobpm/workflow` derives EXACTLY
+//         merge-loop, plan-fanout, delivery-human). `@nanobpm/workflow` derives EXACTLY
 //         ONE `<bpmn:startEvent id="Start">` + ONE `<bpmn:endEvent id="End">`,
 //         converging every dangler into that single end (see `Compiler.compile`
 //         in the package's `declarative.ts`). Needs a terminal/explicit-end
@@ -146,7 +146,7 @@ const MULTI_START_END_BLOCK =
   "cannot reproduce. Awaits an upstream terminal/explicit-end (+ multi-start) " +
   "construct in @nanobpm/workflow (nano-ide).";
 
-/** All seven ports, keyed by model, in the epic's stated authoring order. */
+/** All ports, keyed by model, in the epic's stated authoring order. */
 export const PORTS: readonly PortEntry[] = [
   { model: "retro", flow: retroFlow },
   {
@@ -183,4 +183,8 @@ export const PORTS: readonly PortEntry[] = [
     model: "plan-fanout",
     blockedReason: `${MULTI_START_END_BLOCK} (plan-fanout: 3 starts, 3 ends)`,
   },
+  {
+    model: "delivery-human",
+    blockedReason: `${MULTI_START_END_BLOCK} (delivery-human: 1 start, 2 ends)`,
+  },
 ];