@nanobpm/nano-workforce 0.129.0 → 0.130.0

package/.github/workflows/pr-title-lint.yml

@@ -1,9 +1,11 @@
 name: PR title lint
 
 # Squash-merge uses the PR title as the commit subject on `main`, and
-# semantic-release (Angular preset) only cuts a release for `feat:`/`fix:`/`perf:`.
-# A non-conventional title therefore lands on `main` and is silently skipped by
-# the release job — so gate the title against the Conventional Commits grammar.
+# semantic-release (conventionalcommits preset) cuts a release for
+# `feat:`/`fix:`/`perf:`/`refactor:`/`build:`/`revert:`/`docs:` (see
+# `.releaserc.json` releaseRules). A non-conventional title therefore lands on
+# `main` and is silently skipped by the release job — so gate the title against
+# the Conventional Commits grammar.
 on:
   pull_request:
     types: [opened, edited, synchronize, reopened]

package/.releaserc.json

@@ -1,8 +1,42 @@
 {
   "branches": ["main"],
   "plugins": [
-    "@semantic-release/commit-analyzer",
-    "@semantic-release/release-notes-generator",
+    [
+      "@semantic-release/commit-analyzer",
+      {
+        "preset": "conventionalcommits",
+        "releaseRules": [
+          { "type": "feat", "release": "minor" },
+          { "type": "fix", "release": "patch" },
+          { "type": "perf", "release": "patch" },
+          { "type": "refactor", "release": "patch" },
+          { "type": "build", "release": "patch" },
+          { "type": "revert", "release": "patch" },
+          { "type": "docs", "release": "patch" }
+        ]
+      }
+    ],
+    [
+      "@semantic-release/release-notes-generator",
+      {
+        "preset": "conventionalcommits",
+        "presetConfig": {
+          "types": [
+            { "type": "feat", "section": "Features" },
+            { "type": "fix", "section": "Bug Fixes" },
+            { "type": "perf", "section": "Performance Improvements" },
+            { "type": "refactor", "section": "Code Refactoring" },
+            { "type": "build", "section": "Build System" },
+            { "type": "revert", "section": "Reverts" },
+            { "type": "docs", "section": "Documentation" },
+            { "type": "test", "hidden": true },
+            { "type": "ci", "hidden": true },
+            { "type": "chore", "hidden": true },
+            { "type": "style", "hidden": true }
+          ]
+        }
+      }
+    ],
     "@semantic-release/changelog",
     "@semantic-release/npm",
     "@semantic-release/github",

package/AGENTS.md

@@ -353,16 +353,20 @@ agents:
 - **DCO sign-off is enforced.** Every commit needs a `Signed-off-by` trailer —
   use `git commit -s` (or `git rebase --signoff`). A missing sign-off fails the
   DCO check.
-- **Conventional Commits.** `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`,
-  `test:`, imperative mood. Review-comment fix-ups are `chore:`, not `fix:`.
+- **Conventional Commits.** `feat:`, `fix:`, `perf:`, `refactor:`, `build:`,
+  `revert:`, `docs:`, `chore:`, `ci:`, `test:`, `style:`, imperative mood — see the
+  next bullet for which of these trigger a release. Review-comment fix-ups are
+  `chore:`, not `fix:`.
 - **PR titles must be Conventional too — they become the release trigger.** PRs
   land on `main` via **squash merge**, so the **PR title is the commit subject**
-  semantic-release analyses. Only `feat:` (minor) and `fix:`/`perf:` (patch) cut a
-  release; any other type — or a non-conventional title like `Redesign …` or
-  `Foundation: …` — lands on `main` and is **silently skipped** by the release job
+  semantic-release analyses. `feat:` cuts a **minor**; `fix:`, `perf:`,
+  `refactor:`, `build:`, `revert:`, and `docs:` cut a **patch** (see
+  `.releaserc.json` `releaseRules`); a `BREAKING CHANGE:` footer cuts a **major**.
+  Only `chore:`, `ci:`, `test:`, and `style:` are **no-release** — a PR titled
+  with one of those lands on `main` and is **silently skipped** by the release job
   (no version, no changelog, no deploy). A user-facing feature **must** be titled
   `feat:`. The `PR title lint` workflow (`.github/workflows/pr-title-lint.yml`)
-  enforces this; if a non-conventional title ever slips through, push one empty
+  enforces this; if a non-releasing title ever slips through, push one empty
   releasable commit (`git commit --allow-empty -s -m "feat(scope): …"`) to release
   the accumulated changes.
 - **Feature work in a worktree** off `origin/main`, one branch per change; open a

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.130.0](https://github.com/nanobpm/nano-workforce/compare/v0.129.1...v0.130.0) (2026-08-23)
+
+### Features
+
+* **delivery-unit:** one derived delivery-unit status union (ADR 0006, S1) ([#494](https://github.com/nanobpm/nano-workforce/issues/494)) ([47245d3](https://github.com/nanobpm/nano-workforce/commit/47245d37599a2f220c9835672c37656b6b0e6a6d)), closes [#464](https://github.com/nanobpm/nano-workforce/issues/464)
+
+## [0.129.1](https://github.com/nanobpm/nano-workforce/compare/v0.129.0...v0.129.1) (2026-08-23)
+
+### Code Refactoring
+
+* **merge-loop:** sub-process topology + behavioural guards ([#466](https://github.com/nanobpm/nano-workforce/issues/466)) ([#490](https://github.com/nanobpm/nano-workforce/issues/490)) ([ac6f130](https://github.com/nanobpm/nano-workforce/commit/ac6f130d19e545c4d3da23d738c30c1cb6f2b981)), closes [Magikcraft/nano-bpm#971](https://github.com/Magikcraft/nano-bpm/issues/971)
+
 # [0.129.0](https://github.com/nanobpm/nano-workforce/compare/v0.128.0...v0.129.0) (2026-08-23)
 
 

package/app/delivery.ts

@@ -78,7 +78,7 @@ export function deriveDelivery(
 /** The `plan.status` values that mean the epic's fan-out lifecycle is still LIVE — the planner is
  * decomposing (`planning`) or the fleet is implementing (`dispatched`). Both are unambiguously
  * in-flight, so an epic in either status is always in the Active bucket regardless of `delivery`. */
-export const EPIC_LIVE_STATUSES: readonly string[] = ["planning", "dispatched"];
+export const EPIC_LIVE_STATUSES = ["planning", "dispatched"] as const;
 
 /** The Active/History partition for an EPIC (issue #298), the twin of feature runs'
  * `deriveListBucket` (app/stage.ts). It exists because an epic must NOT vanish from the Active list
@@ -108,7 +108,7 @@ export function deriveEpicBucket(
   delivery: string | null | undefined,
   acknowledgedAt: string | null | undefined,
 ): "active" | "history" {
-  if (EPIC_LIVE_STATUSES.includes(status)) return "active";
+  if (EPIC_LIVE_STATUSES.some((s) => s === status)) return "active";
   if (status === "done") {
     // A still-`converging` epic is Active regardless of any (stray) acknowledged_at — it is genuinely
     // working and is not acknowledgeable, so it can never be ticked off mid-flight (fail-closed).

package/app/deliveryUnitStatus.test.ts

@@ -0,0 +1,143 @@
+// Coverage for ADR 0006 slice S1 — the ONE canonical delivery-unit status union and the per-shape
+// derivations that map each bespoke source union into it (app/deliveryUnitStatus.ts).
+//
+// Guards THREE things:
+//   1. TOTALITY — every member of each source union (feature / plan aggregate / plan-task node /
+//      delivery-graph run) maps to a valid canonical member, and the compiled `fnFor` agrees with the
+//      declared map object (so the DSL derivation and the TS map cannot drift).
+//   2. TERMINALITY PRECEDENCE — a source SETTLED/terminal status always maps to a canonical
+//      settled/terminal status, so a reconciler reading the union never mistakes a finished unit for a
+//      live one (or vice-versa).
+//   3. FRAMEWORK PARITY — for each of the four read models, `assertReadModelParity` proves the SQL VIEW
+//      lowering and the TS `fnFor` lowering agree over the full source-status matrix.
+import { DatabaseSync } from "node:sqlite";
+import { test } from "node:test";
+import { assertReadModelParity, type ParityDb, type ParitySample } from "@nanobpm/urban";
+import { assert, assertEquals } from "#test-assert";
+import { DELIVERY_GRAPH_RUN_STATUSES, DELIVERY_GRAPH_TERMINAL_STATUSES } from "./deliveryGraphRun.ts";
+import {
+  DELIVERY_GRAPH_STATUS_TO_UNIT,
+  DELIVERY_STATUS_COLUMN,
+  DELIVERY_UNIT_SETTLED_STATUSES,
+  DELIVERY_UNIT_STATUSES,
+  DELIVERY_UNIT_TERMINAL_STATUSES,
+  type DeliveryUnitStatus,
+  deliveryGraphDeliveryStatus,
+  FEATURE_STATUS_TO_UNIT,
+  featureDeliveryStatus,
+  isDeliveryUnitSettled,
+  isDeliveryUnitTerminal,
+  PLAN_STATUS_TO_UNIT,
+  PLAN_STATUSES,
+  PLAN_TASK_STATUS_TO_UNIT,
+  planDeliveryStatus,
+  planTaskDeliveryStatus,
+  toDeliveryUnitStatus,
+} from "./deliveryUnitStatus.ts";
+import { FEATURE_RUN_STATUSES, FEATURE_TERMINAL_STATUSES } from "./feature.ts";
+import { PLAN_TASK_STATUSES, PLAN_TERMINAL_STATUSES } from "./plan.ts";
+
+const CANONICAL = new Set<string>(DELIVERY_UNIT_STATUSES);
+
+// ── Type-level No-Drift guard (issue #464 review) ────────────────────────────────────────────────
+// `PLAN_STATUSES` is DERIVED from `EPIC_LIVE_STATUSES` (app/delivery.ts) + `PLAN_TERMINAL_STATUSES`
+// (app/plan.ts). If either source is declared as a widened `readonly string[]` instead of an `as const`
+// literal tuple, `(typeof PLAN_STATUSES)[number]` collapses to `string`, `PLAN_STATUS_TO_UNIT` degrades
+// to `Record<string, …>`, and the exhaustiveness guard silently evaporates — `tsc` would no longer fail
+// when the plan vocabulary gains a member without a canonical mapping. This assertion fails to COMPILE
+// if that widening ever returns (the `false` branch makes `true` unassignable).
+type _IsLiteralUnion<T extends string> = string extends T ? false : true;
+const _planStatusesAreLiteral: _IsLiteralUnion<(typeof PLAN_STATUSES)[number]> = true;
+void _planStatusesAreLiteral;
+
+// A `ParityDb` over node:sqlite's `DatabaseSync` for `assertReadModelParity` (which needs positional
+// exec/all/run, whereas `DatabaseSync` exposes query methods on prepared statements).
+function parityDb(db: DatabaseSync): ParityDb {
+  return {
+    exec: (sql) => db.exec(sql),
+    all: <T = Record<string, unknown>>(sql: string, params: unknown[] = []) =>
+      db.prepare(sql).all(...(params as never[])) as T[],
+    run: (sql, params: unknown[] = []) => {
+      const r = db.prepare(sql).run(...(params as never[]));
+      return { changes: Number(r.changes), lastInsertRowid: r.lastInsertRowid };
+    },
+  };
+}
+
+const shapes = [
+  { name: "feature", model: featureDeliveryStatus, sources: FEATURE_RUN_STATUSES, map: FEATURE_STATUS_TO_UNIT },
+  { name: "plan", model: planDeliveryStatus, sources: PLAN_STATUSES, map: PLAN_STATUS_TO_UNIT },
+  { name: "plan-task", model: planTaskDeliveryStatus, sources: PLAN_TASK_STATUSES, map: PLAN_TASK_STATUS_TO_UNIT },
+  { name: "delivery-graph", model: deliveryGraphDeliveryStatus, sources: DELIVERY_GRAPH_RUN_STATUSES, map: DELIVERY_GRAPH_STATUS_TO_UNIT },
+] as const;
+
+test("TOTALITY: every source status maps to a valid canonical member, and fnFor agrees with the declared map", () => {
+  for (const { name, model, sources, map } of shapes) {
+    for (const source of sources) {
+      const declared = (map as Record<string, DeliveryUnitStatus>)[source];
+      assert(declared !== undefined, `${name}: source status "${source}" has no canonical mapping`);
+      assert(CANONICAL.has(declared), `${name}: "${source}" maps to non-canonical "${declared}"`);
+      // The DSL-compiled TS lowering must produce the SAME canonical value as the declared map object.
+      assertEquals(toDeliveryUnitStatus(model, source), declared, `${name}: fnFor drift for "${source}"`);
+    }
+    // An out-of-band status is NULL (never an invented member), matching the VIEW's ELSE NULL.
+    assertEquals(toDeliveryUnitStatus(model, "not-a-real-status"), null, `${name}: unmapped status must be null`);
+    assertEquals(toDeliveryUnitStatus(model, null), null, `${name}: null status must be null`);
+  }
+});
+
+test("TERMINALITY PRECEDENCE: a source SETTLED/terminal status maps to a canonical settled/terminal status", () => {
+  // Feature counts opened/converging as SETTLED-for-redispatch (live PR stages), so check against the
+  // settled set; the plan aggregate and delivery-graph terminals are truly DONE, so check the done tier.
+  for (const s of FEATURE_TERMINAL_STATUSES) {
+    assert(isDeliveryUnitSettled(FEATURE_STATUS_TO_UNIT[s]), `feature terminal "${s}" must map to a settled canonical status`);
+  }
+  for (const s of PLAN_TERMINAL_STATUSES as readonly (keyof typeof PLAN_STATUS_TO_UNIT)[]) {
+    assert(isDeliveryUnitTerminal(PLAN_STATUS_TO_UNIT[s]), `plan terminal "${s}" must map to a done-tier canonical status`);
+  }
+  for (const s of DELIVERY_GRAPH_TERMINAL_STATUSES) {
+    assert(isDeliveryUnitTerminal(DELIVERY_GRAPH_STATUS_TO_UNIT[s]), `graph terminal "${s}" must map to a done-tier canonical status`);
+  }
+  // The non-terminal parked waits must NOT be classified terminal (a reconciler must keep polling them).
+  for (const nonTerminal of ["escalated", "awaiting_operator", "waiting", "running", "requested"] as DeliveryUnitStatus[]) {
+    assert(!isDeliveryUnitTerminal(nonTerminal), `"${nonTerminal}" must be non-terminal`);
+  }
+});
+
+test("NODE-VS-AGGREGATE decision (ADR 0006 §4): a plan-task node maps into the SAME union; its lane wait becomes the canonical `waiting`", () => {
+  assertEquals(PLAN_TASK_STATUS_TO_UNIT["waiting-for-lane"], "waiting", "the node lane/dependency wait is the canonical `waiting`");
+  assertEquals(PLAN_TASK_STATUS_TO_UNIT.pending, "requested", "a queued (not-yet-run) node is pre-dispatch `requested`");
+  // Every node status resolves to a member of the one canonical union — no separate node vocabulary.
+  for (const s of PLAN_TASK_STATUSES) {
+    assert(CANONICAL.has(PLAN_TASK_STATUS_TO_UNIT[s]), `node status "${s}" must be a canonical member`);
+  }
+});
+
+test("the settled set is exactly the terminal (done-tier) set plus the two live PR resting stages", () => {
+  assertEquals(
+    [...DELIVERY_UNIT_SETTLED_STATUSES].sort(),
+    [...DELIVERY_UNIT_TERMINAL_STATUSES, "opened", "converging"].sort(),
+    "settled = terminal ∪ {opened, converging}",
+  );
+  for (const t of DELIVERY_UNIT_TERMINAL_STATUSES) assert(isDeliveryUnitSettled(t), `terminal "${t}" is settled`);
+});
+
+test("no dead canonical members: every DELIVERY_UNIT_STATUSES value is reachable from at least one source mapping", () => {
+  const reached = new Set<string>();
+  for (const { map } of shapes) for (const v of Object.values(map)) reached.add(v as string);
+  for (const canonical of DELIVERY_UNIT_STATUSES) {
+    assert(reached.has(canonical), `canonical "${canonical}" is unreachable — a dead member or a missing mapping`);
+  }
+});
+
+test("FRAMEWORK PARITY: each per-shape delivery_status model's SQL and TS lowerings agree over the full source-status matrix", () => {
+  for (const { name, model, sources } of shapes) {
+    const samples: ParitySample[] = sources.map((status) => ({ baseRow: { status } }));
+    // Also exercise the ELSE NULL arm with an out-of-band value.
+    samples.push({ baseRow: { status: "out-of-band" } });
+    const db = new DatabaseSync(":memory:");
+    assertReadModelParity(model, parityDb(db), samples, { columns: [DELIVERY_STATUS_COLUMN] });
+    db.close();
+    assert(true, `${name} parity holds`);
+  }
+});

package/app/deliveryUnitStatus.ts

@@ -0,0 +1,242 @@
+// The ONE delivery-unit status union — ADR 0006 slice **S1** (status lifecycle).
+//
+// Background (ADR 0006, issue #464). nano-workforce models the same aggregate — a *scheduled unit of
+// work driven to a delivery outcome* — in three separate representations, each with its OWN bespoke
+// status union:
+//
+//   * feature   — `FEATURE_RUN_STATUSES` (11: running/escalated/opened/converging/awaiting_operator/
+//                 merged/converged/blocked/skipped/failed/abandoned) — app/feature.ts
+//   * epic      — the `plans` aggregate (`planning`/`dispatched`/`done`/`failed`/`abandoned`, the union
+//                 of `EPIC_LIVE_STATUSES` + `PLAN_TERMINAL_STATUSES`, app/delivery.ts + app/plan.ts)
+//                 AND its `plan_tasks` NODE status `PLAN_TASK_STATUSES` (7) — app/plan.ts
+//   * graph     — `DELIVERY_GRAPH_RUN_STATUSES` (5: awaiting-approval/running/done/failed/abandoned)
+//                 — app/deliveryGraphRun.ts
+//
+// A change to "what states a unit of work can be in" therefore has to be made, by hand, in three (four,
+// counting the epic's two levels) places that can silently drift — exactly the "No drift surfaces /
+// derivation over duplication" hazard this repo treats as a defect class (AGENTS.md).
+//
+// This module is S1's deliverable: it defines the SINGLE canonical aggregate union
+// ({@link DELIVERY_UNIT_STATUSES}) and, via ADR-0065's `defineReadModel`, the per-shape derivations that
+// map each bespoke union INTO it — declared ONCE and compiled to BOTH the SQLite VIEW select-list
+// (`sqlSelectFor`, for S2's `delivery_units`-backed VIEWs) AND the runtime TS oracle (`fnFor`, for the
+// reconcilers). There is nothing to keep in lockstep: the two lowerings fall out of the same closed-DSL
+// AST, and `assertReadModelParity` (app/deliveryUnitStatus.test.ts) proves they agree.
+//
+// SCOPE (S1). This slice OWNS the canonical vocabulary, the per-shape mapping, the terminal/settled
+// precedence, and the node-vs-aggregate decision (below). It does NOT repoint any existing VIEW or move
+// any writer/`instanceTracking` binding onto the new union — the legacy tables stay the physical write
+// target through S2, and the `instanceTracking` bindings + `senior:*` doors collapse in S3 (ADR 0006
+// rollout). The derivations here are the single source those later slices reference, not a second
+// projection alongside them.
+
+import { caseWhen, col, defineReadModel, type Expr, eq, lit, type ReadModel, when } from "@nanobpm/urban";
+import { EPIC_LIVE_STATUSES } from "./delivery.ts";
+import type { DeliveryGraphRunStatus } from "./deliveryGraphRun.ts";
+import type { FeatureRunStatus } from "./feature.ts";
+import { PLAN_TERMINAL_STATUSES, type PlanTaskStatus } from "./plan.ts";
+
+/**
+ * The ONE canonical delivery-unit status union — the single source of truth for "what state a unit of
+ * work is in", replacing the three bespoke unions. A superset that preserves every source union's
+ * distinctions without loss (feature is the reference shape, so its members pass through by name):
+ *
+ *  - `requested`         — created, not yet dispatched to an executor (no live engine instance yet).
+ *  - `running`           — an executor (agent/probe/connector) is actively working the unit.
+ *  - `escalated`         — NON-terminal: parked awaiting a HUMAN answer (an open escalation user task).
+ *  - `awaiting_operator` — NON-terminal: parked awaiting an OPERATOR acknowledgement (blocked wait).
+ *  - `waiting`           — NON-terminal: parked on a lane / dependency gate (a wave barrier).
+ *  - `opened`            — a PR was raised and the unit rests here (convergence was not requested).
+ *  - `converging`        — the opened PR is in its review-convergence loop.
+ *  - `converged`         — TERMINAL: review converged but the PR did not merge (auto-merge off).
+ *  - `merged`            — TERMINAL: the PR landed (the win).
+ *  - `done`              — TERMINAL: an aggregate settled successfully WITHOUT a single-PR terminal
+ *                          (an epic/graph whose members all landed) — the PR-less success outcome.
+ *  - `skipped`           — TERMINAL: nothing to do.
+ *  - `blocked`           — TERMINAL: could not proceed / gave up (distinct from the non-terminal
+ *                          `awaiting_operator` wait — a `blocked` unit is settled, not parked).
+ *  - `failed`            — TERMINAL: an unexpected failure.
+ *  - `abandoned`         — TERMINAL: the PR was abandoned, or the process instance was cancelled.
+ */
+export const DELIVERY_UNIT_STATUSES = [
+  "requested",
+  "running",
+  "escalated",
+  "awaiting_operator",
+  "waiting",
+  "opened",
+  "converging",
+  "converged",
+  "merged",
+  "done",
+  "skipped",
+  "blocked",
+  "failed",
+  "abandoned",
+] as const;
+export type DeliveryUnitStatus = (typeof DELIVERY_UNIT_STATUSES)[number];
+
+/**
+ * The TRULY-terminal ("done tier") statuses — a unit in one of these has settled to a final outcome and
+ * will not advance again. Mirrors the union of the source terminal sets (`FEATURE_TERMINAL_STATUSES`
+ * minus its live PR stages, `PLAN_TERMINAL_STATUSES`, `DELIVERY_GRAPH_TERMINAL_STATUSES`). Distinct from
+ * {@link DELIVERY_UNIT_SETTLED_STATUSES}: `opened`/`converging` are settled FOR RE-DISPATCH but are LIVE
+ * pipeline stages, not `done`.
+ */
+export const DELIVERY_UNIT_TERMINAL_STATUSES: readonly DeliveryUnitStatus[] = [
+  "converged",
+  "merged",
+  "done",
+  "skipped",
+  "blocked",
+  "failed",
+  "abandoned",
+];
+
+/**
+ * The SETTLED-FOR-RE-DISPATCH statuses — {@link DELIVERY_UNIT_TERMINAL_STATUSES} plus the two live PR
+ * resting stages (`opened`/`converging`) a unit stops at without a further wave restart. Mirrors
+ * `FEATURE_TERMINAL_STATUSES` (app/feature.ts), which likewise counts `opened`/`converging` as terminal
+ * for re-dispatch gating even though they are LIVE (not `done`). A re-dispatch of the same unit
+ * short-circuits IFF its prior run is in one of these; the NON-terminal parked waits
+ * (`escalated`/`awaiting_operator`/`waiting`) and `running`/`requested` are excluded, so a live or
+ * parked unit is never orphaned by a parallel restart.
+ */
+export const DELIVERY_UNIT_SETTLED_STATUSES: readonly DeliveryUnitStatus[] = [
+  ...DELIVERY_UNIT_TERMINAL_STATUSES,
+  "opened",
+  "converging",
+];
+
+/** True iff `status` is a truly-terminal ("done tier") delivery-unit status. */
+export const isDeliveryUnitTerminal = (status: DeliveryUnitStatus): boolean =>
+  DELIVERY_UNIT_TERMINAL_STATUSES.includes(status);
+
+/** True iff `status` is settled for RE-DISPATCH (terminal, or a live PR resting stage). */
+export const isDeliveryUnitSettled = (status: DeliveryUnitStatus): boolean =>
+  DELIVERY_UNIT_SETTLED_STATUSES.includes(status);
+
+/**
+ * The plan AGGREGATE lifecycle values — the union of the two existing sources (`EPIC_LIVE_STATUSES` +
+ * `PLAN_TERMINAL_STATUSES`), NOT re-listed here, so this stays a derived view of them and cannot drift.
+ */
+export const PLAN_STATUSES = [...EPIC_LIVE_STATUSES, ...PLAN_TERMINAL_STATUSES] as const;
+
+// ── Per-shape mappings — declared ONCE, keyed by the SOURCE union so `tsc` fails if a source union
+//    gains a member without a canonical mapping (the type-level No-Drift guard). ──────────────────────
+
+/**
+ * Feature is the REFERENCE shape: every `FEATURE_RUN_STATUSES` member has a same-named canonical member,
+ * so the map is the identity. The distinct feature waits survive intact — `escalated` (human),
+ * `awaiting_operator` (operator), and the terminal `blocked` (gave up) stay three different states.
+ */
+export const FEATURE_STATUS_TO_UNIT: Record<FeatureRunStatus, DeliveryUnitStatus> = {
+  running: "running",
+  escalated: "escalated",
+  opened: "opened",
+  converging: "converging",
+  awaiting_operator: "awaiting_operator",
+  merged: "merged",
+  converged: "converged",
+  blocked: "blocked",
+  skipped: "skipped",
+  failed: "failed",
+  abandoned: "abandoned",
+};
+
+/**
+ * Plan AGGREGATE → canonical. `planning` (decomposing, no fan-out yet) is pre-dispatch ⇒ `requested`;
+ * `dispatched` (fan-out running) ⇒ `running`; the three terminals pass through. Keyed by the plan
+ * aggregate value (a bare string in `Plan.status`), covering every {@link PLAN_STATUSES} member.
+ */
+export const PLAN_STATUS_TO_UNIT: Record<(typeof PLAN_STATUSES)[number], DeliveryUnitStatus> = {
+  planning: "requested",
+  dispatched: "running",
+  done: "done",
+  failed: "failed",
+  abandoned: "abandoned",
+};
+
+/**
+ * Plan-task NODE → canonical. **Node-vs-aggregate decision (ADR 0006 §4):** a node is a DEGENERATE
+ * delivery unit, so its status maps into the SAME canonical union rather than carrying a separate node
+ * contract — there is ONE vocabulary. The node-specific lane/dependency wait (`waiting-for-lane`) is
+ * expressed by the canonical `waiting` member (a state the aggregate level never enters); `pending`
+ * (queued, not yet run in its wave) is pre-dispatch ⇒ `requested`.
+ */
+export const PLAN_TASK_STATUS_TO_UNIT: Record<PlanTaskStatus, DeliveryUnitStatus> = {
+  pending: "requested",
+  opened: "opened",
+  blocked: "blocked",
+  skipped: "skipped",
+  escalated: "escalated",
+  "waiting-for-lane": "waiting",
+  abandoned: "abandoned",
+};
+
+/**
+ * Delivery-graph RUN → canonical. `awaiting-approval` (reserved, pre-dispatch: no live instance, parked
+ * before launch — issue #460) ⇒ `requested`; `running` passes through; the three terminals pass through.
+ */
+export const DELIVERY_GRAPH_STATUS_TO_UNIT: Record<DeliveryGraphRunStatus, DeliveryUnitStatus> = {
+  "awaiting-approval": "requested",
+  running: "running",
+  done: "done",
+  failed: "failed",
+  abandoned: "abandoned",
+};
+
+/**
+ * Build the canonical `delivery_status` derivation for one shape as a closed-DSL {@link Expr}: a
+ * `CASE` over the base row's `status` column, one `WHEN status = '<source>' THEN '<canonical>'` per map
+ * entry. The map is TOTAL over its source union, so the `ELSE` is unreachable in practice; it falls back
+ * to `null` (never an invented status) so an out-of-band source value surfaces as NULL rather than a
+ * silent mis-map. Both backends (`sqlSelectFor` VIEW body, `fnFor` runtime) fall out of this one AST.
+ */
+export const deliveryStatusExpr = (map: Readonly<Record<string, DeliveryUnitStatus>>): Expr =>
+  caseWhen(
+    Object.entries(map).map(([source, unit]) => when(eq(col("status"), lit(source)), lit(unit))),
+    lit(null),
+  );
+
+/** The single derived column every per-shape delivery-unit read model exposes. */
+export const DELIVERY_STATUS_COLUMN = "delivery_status";
+
+/** The base alias the managed VIEWs give each source table — pinned so emitted SQL is stable/testable. */
+export const DELIVERY_UNIT_STATUS_BASE_ALIAS = "du";
+
+const statusReadModel = (name: string, baseTable: string, map: Readonly<Record<string, DeliveryUnitStatus>>): ReadModel =>
+  defineReadModel({
+    name,
+    baseTable,
+    selectBaseColumns: false,
+    derive: { [DELIVERY_STATUS_COLUMN]: deliveryStatusExpr(map) },
+  });
+
+/**
+ * The four per-shape derivations of the ONE canonical union, each a `defineReadModel` exposing a single
+ * `delivery_status` column over its source table. S2 provisions these as VIEWs over `delivery_units`;
+ * the reconcilers consume `fnFor(DELIVERY_STATUS_COLUMN)`. They all target {@link DELIVERY_UNIT_STATUSES}
+ * — the union is single-sourced; only the per-shape MAPPING differs.
+ */
+export const featureDeliveryStatus: ReadModel = statusReadModel("feature_delivery_status", "feature_runs", FEATURE_STATUS_TO_UNIT);
+export const planDeliveryStatus: ReadModel = statusReadModel("plan_delivery_status", "plans", PLAN_STATUS_TO_UNIT);
+export const planTaskDeliveryStatus: ReadModel = statusReadModel("plan_task_delivery_status", "plan_tasks", PLAN_TASK_STATUS_TO_UNIT);
+export const deliveryGraphDeliveryStatus: ReadModel = statusReadModel("delivery_graph_delivery_status", "delivery_graph_runs", DELIVERY_GRAPH_STATUS_TO_UNIT);
+
+/** All four per-shape delivery-status read models, for bulk registration/validation by later slices. */
+export const DELIVERY_STATUS_READ_MODELS: readonly ReadModel[] = [
+  featureDeliveryStatus,
+  planDeliveryStatus,
+  planTaskDeliveryStatus,
+  deliveryGraphDeliveryStatus,
+];
+
+/**
+ * Map a source status to the canonical union in-process (the TS backend of {@link deliveryStatusExpr},
+ * via the compiled `fnFor`) — the reconciler-facing helper. Returns `null` for an unmapped value,
+ * matching the VIEW's `ELSE NULL`.
+ */
+export const toDeliveryUnitStatus = (model: ReadModel, status: string | null): DeliveryUnitStatus | null =>
+  // biome-ignore lint/plugin: runtime/framework contract boundary — `fnFor` returns `unknown`; the derived column yields one of its declared `lit(...)` canonical statuses (or null on the ELSE arm).
+  model.fnFor(DELIVERY_STATUS_COLUMN)({ status }) as DeliveryUnitStatus | null;

package/app/mergeEscalationUserTask.test.ts

@@ -1,71 +1,37 @@
-// Structural + cross-layer regression guard for converging the merge-loop escalation onto the ONE
-// native user-task answer pathway (#256).
+// Cross-layer drift guard: the merge-loop escalation user task the model parks on must be one the
+// canonical completer (`agentCompletion.ts`) actually accepts and validates (#256, #466).
 //
-// Before #256 the merge loop parked on a durable `escalation-answered` message catch answered by a
-// bespoke `answerEscalation()` publish — a SECOND answer pathway invisible to the Tasks inbox, so a
-// merge escalation could not be answered from the nwf UI at all. It now parks on a native
-// `wait-merge-answer` userTask (backed by `pr-escalation.form`) followed by the SAME
-// `pr.answer-escalation` reconcile step the review loop's `wait-answer` runs, so both loops answer
-// through the one canonical `completeUserTask` door and surface in the one Tasks inbox.
-//
-// These are pure text assertions over the committed BPMN (no engine), matching the repo's
-// lightweight model-guard style (see mergeRebaseArm.test.ts), plus a drift guard tying the model's
-// user-task element id to the completer's accepted escalation set so the two can't silently diverge.
+// The merge escalation converges on ONE native `wait-merge-answer` userTask (backed by the shared
+// `pr-escalation` form) so it is answerable from the one Tasks inbox. The *behavioural* invariants —
+// that the loop parks on that task, that answering it reconciles the escalations row and re-arms the
+// poller — are exercised end-to-end by the WASM engine in `mergeLoopBehaviour.test.ts`. But that
+// engine harness completes the task through the engine, NOT through nwf's application-level
+// completer, so it cannot catch the specific silent-drift failure this guard closes: the model
+// deploys and parks on `wait-merge-answer`, yet `agentCompletion.ts` refuses to drive it because the
+// id fell out of `ESCALATION_TASK_ELEMENTS` (or its form contract drifted) — a task no worker will
+// ever answer. This guard ties the model's user-task id to the completer's accepted set + form
+// contract so the two layers cannot diverge unnoticed.
 
 import { test } from "node:test";
-import { assert, assertStringIncludes } from "#test-assert";
+import { assert } from "#test-assert";
 import { readFileSync } from "node:fs";
 import { ESCALATION_TASK_ELEMENTS, validateEscalationVariables } from "./agentCompletion.ts";
 
-const bpmn = readFileSync("resources/processes/merge-loop.bpmn", "utf8");
-const flat = bpmn.replace(/\s+/g, " ");
-
-function hasFlow(source: string, target: string): boolean {
-  const re = new RegExp(
-    `<bpmn:sequenceFlow\\b[^>]*\\bsourceRef="${source}"[^>]*\\btargetRef="${target}"|` +
-      `<bpmn:sequenceFlow\\b[^>]*\\btargetRef="${target}"[^>]*\\bsourceRef="${source}"`,
-  );
-  return re.test(flat);
-}
-
-test("the merge escalation parks on a native wait-merge-answer userTask backed by pr-escalation.form", () => {
-  const task = flat.match(/<bpmn:userTask\b[^>]*\bid="wait-merge-answer"[\s\S]*?<\/bpmn:userTask>/);
-  assert(task, "wait-merge-answer must be a <bpmn:userTask>");
-  assertStringIncludes(task![0], 'formId="pr-escalation"', "it must render the shared pr-escalation form");
-  assertStringIncludes(task![0], "<zeebe:userTask", "it must be a native (Zeebe) user task");
-});
+const flat = readFileSync("resources/processes/merge-loop.bpmn", "utf8").replace(/\s+/g, " ");
 
-test("the answered task reconciles the escalations row, then re-arms the merge poller", () => {
-  // wait-merge-answer → record-merge-answer (pr.answer-escalation) → arm-merge, mirroring the review
-  // loop's wait-answer → record-answer. Without the reconcile step the escalations row would stay
-  // `open` forever after the task completes (a phantom on /status).
-  const record = flat.match(/<bpmn:serviceTask\b[^>]*\bid="record-merge-answer"[\s\S]*?<\/bpmn:serviceTask>/);
-  assert(record, "record-merge-answer service task must exist");
-  assertStringIncludes(record![0], 'type="pr.answer-escalation"', "it must run the shared reconcile worker");
-  assert(hasFlow("wait-merge-answer", "record-merge-answer"), "wait-merge-answer → record-merge-answer missing");
-  assert(hasFlow("record-merge-answer", "arm-merge"), "record-merge-answer → arm-merge (re-arm) missing");
-});
-
-test("the legacy escalation-answered message pathway is gone", () => {
-  assert(!flat.includes("escalation-answered"), "the escalation-answered message must be removed");
-  assert(!flat.includes("Message_mergeEscAnswered"), "the merge escalation message declaration must be removed");
-  // The answer wait must no longer be a message catch — it is now a user task.
+test("drift guard: the model's merge user-task element is one the canonical completer accepts", () => {
+  // (1) The model actually parks on `wait-merge-answer` as a native user task...
   assert(
-    !/<bpmn:intermediateCatchEvent\b[^>]*\bid="wait-merge-answer"/.test(flat),
-    "wait-merge-answer must no longer be an intermediateCatchEvent",
+    /<bpmn:userTask\b[^>]*\bid="wait-merge-answer"/.test(flat),
+    "the model must park the merge escalation on a userTask id='wait-merge-answer'",
   );
-});
-
-test("drift guard: the model's merge user-task element is one the canonical completer accepts", () => {
-  // The completer refuses any user task outside ESCALATION_TASK_ELEMENTS, so a model that parks on
-  // `wait-merge-answer` while the code doesn't accept it would deploy but never be answerable — the
-  // exact silent-drift failure mode this guard closes.
+  // (2) ...and the completer accepts that exact id (else it deploys but is never answerable)...
   assert(
     ESCALATION_TASK_ELEMENTS.has("wait-merge-answer"),
     "ESCALATION_TASK_ELEMENTS must accept wait-merge-answer",
   );
-  // And it must map to the pr-escalation form contract (answer required) — a missing answer is
-  // rejected, proving the element resolves to the same form the model renders.
+  // (3) ...resolving to the pr-escalation form contract (a missing answer is rejected; a present
+  // one accepted), proving the element maps to the same form the model renders.
   assert(
     validateEscalationVariables("wait-merge-answer", {}) !== null,
     "wait-merge-answer must enforce the pr-escalation form contract (answer required)",