@nanobpm/nano-workforce 0.154.0 → 0.156.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.156.0](https://github.com/nanobpm/nano-workforce/compare/v0.155.0...v0.156.0) (2026-08-29)
+
+### Features
+
+* **delivery-units:** single (kind, instanceId) dispatch door on delivery_units (ADR 0006 S3) ([#602](https://github.com/nanobpm/nano-workforce/issues/602)) ([f736b4b](https://github.com/nanobpm/nano-workforce/commit/f736b4bfaf838b4b4b000b0b84d76330a05edf7c)), closes [#590](https://github.com/nanobpm/nano-workforce/issues/590)
+
+## [0.155.0](https://github.com/nanobpm/nano-workforce/compare/v0.154.0...v0.155.0) (2026-08-29)
+
+### Features
+
+* **delivery-units:** delivery_units aggregate table (ADR 0006 S2, [#589](https://github.com/nanobpm/nano-workforce/issues/589)) ([#601](https://github.com/nanobpm/nano-workforce/issues/601)) ([6949fc4](https://github.com/nanobpm/nano-workforce/commit/6949fc4d3ee567b95497e43391ba15e9367a88e0))
+
 ## [0.154.0](https://github.com/nanobpm/nano-workforce/compare/v0.153.0...v0.154.0) (2026-08-29)
 
 ### Features

package/app/deliveryDispatch.test.ts

@@ -0,0 +1,248 @@
+// Coverage for ADR 0006 slice S3 (#590) — the SINGLE dispatch door (`app/deliveryDispatch.ts`) and
+// its one `delivery_units` `instanceTracking` binding, which collapse the three per-representation
+// `senior:*` dispatch paths onto the aggregate.
+//
+// Proves:
+//   1. VERB PARITY — the door's kind → `senior:*` target map uses the SAME job-type names the
+//      pre-collapse BPMN models dispatch (`senior:feature`, `senior:plan`). Collapsing the doors never
+//      renames a dispatch target; every mapped verb is a real prompt-bearing agent task in the
+//      deployed models.
+//   2. KEY IDENTITY — `(kind, instanceId)` names exactly the S2 `unit_id` the identity helpers build,
+//      so the two-arg door key IS the aggregate key (no per-representation key builder survives).
+//   3. GATE PARITY — the one re-dispatch gate matches the S1/S2 `isDeliveryUnitSettled` /
+//      `dispatchStatusForDelivery` short-circuit for EVERY canonical status: only `requested`(pending)
+//      dispatches; every live/parked/terminal state short-circuits — the exact rule each pre-collapse
+//      launcher re-implemented.
+//   4. BINDING — the single `delivery_units` binding drives the door: it is the ONLY new binding, keys
+//      on `dispatch_status`, lists no `settled` state active, and provisions its `__tracking` VIEW
+//      against a REAL migrated DB.
+import { DatabaseSync } from "node:sqlite";
+import { readFileSync } from "node:fs";
+import { test } from "node:test";
+import type { DataLayer } from "@nanobpm/urban";
+import { applyMigrationSet, readMigrationSetFromDisk } from "#test-migrations";
+import { assert, assertEquals } from "#test-assert";
+import { withTrackingViews } from "../test/trackingViews.ts";
+import {
+  DELIVERY_UNITS_TABLE,
+  DISPATCH_JOB_TYPE_BY_KIND,
+  deliveryUnitKey,
+  dispatchGate,
+  dispatchJobTypeForKind,
+  resolveDeliveryDispatch,
+} from "./deliveryDispatch.ts";
+import {
+  DELIVERY_UNIT_KINDS,
+  deliveryGraphUnitId,
+  dispatchStatusForDelivery,
+  epicUnitId,
+  featureUnitId,
+  planTaskUnitId,
+} from "./deliveryUnit.ts";
+import { DELIVERY_UNIT_STATUSES, type DeliveryUnitStatus, isDeliveryUnitSettled } from "./deliveryUnitStatus.ts";
+import { promptBearingTaskTypes } from "./agentic/vocab/job-types.ts";
+
+interface Binding {
+  table: string;
+  keyField?: string;
+  statusField?: string;
+  activeStatuses?: string[];
+  onTerminated: { set: Record<string, unknown> };
+}
+
+function manifestBindings(): Binding[] {
+  const manifest = JSON.parse(readFileSync(new URL("../nano.app.json", import.meta.url), "utf8"));
+  return manifest.instanceTracking as Binding[];
+}
+
+// The deployed process models — scanned for their prompt-bearing agent tasks, the real dispatch
+// corpus the door's verbs must already exist in.
+const MODEL_FILES = [
+  "feature.bpmn",
+  "plan-fanout.bpmn",
+  "convergence-loop.bpmn",
+  "merge-loop.bpmn",
+  "retro.bpmn",
+];
+
+function deployedAgentJobTypes(): Set<string> {
+  const types = new Set<string>();
+  for (const file of MODEL_FILES) {
+    const xml = readFileSync(new URL(`../resources/processes/${file}`, import.meta.url), "utf8");
+    for (const t of promptBearingTaskTypes(xml)) types.add(t);
+  }
+  return types;
+}
+
+test("VERB PARITY: every mapped dispatch verb is a real senior:* agent task in the deployed models", () => {
+  const deployed = deployedAgentJobTypes();
+  for (const kind of DELIVERY_UNIT_KINDS) {
+    const verb = DISPATCH_JOB_TYPE_BY_KIND[kind];
+    if (verb === null) continue; // delivery-graph is runner-launched, no single verb
+    assert(verb.startsWith("senior:"), `${kind} must dispatch a senior:* verb, got ${verb}`);
+    assert(deployed.has(verb), `${kind} dispatches ${verb}, which must be a deployed agent task`);
+  }
+});
+
+test("VERB PARITY: the implementation kinds keep the pre-collapse senior:feature target", () => {
+  // feature.bpmn's implement task and plan-fanout.bpmn's per-slice implement task both dispatch
+  // senior:feature today — the door preserves that for the single-issue implementation kinds.
+  assertEquals(dispatchJobTypeForKind("feature"), "senior:feature");
+  assertEquals(dispatchJobTypeForKind("plan-task"), "senior:feature");
+  assertEquals(dispatchJobTypeForKind("bugfix"), "senior:feature");
+  assertEquals(dispatchJobTypeForKind("chore"), "senior:feature");
+});
+
+test("VERB PARITY: an epic dispatches the pre-collapse senior:plan decomposition target", () => {
+  assertEquals(dispatchJobTypeForKind("epic"), "senior:plan");
+});
+
+test("VERB PARITY: a delivery-graph unit has no single agent verb (runner-launched)", () => {
+  assertEquals(dispatchJobTypeForKind("delivery-graph"), null);
+});
+
+test("VERB PARITY: the map covers exactly the closed kind enum (no drift)", () => {
+  assertEquals(Object.keys(DISPATCH_JOB_TYPE_BY_KIND).sort(), [...DELIVERY_UNIT_KINDS].sort());
+});
+
+test("KEY IDENTITY: (kind, instanceId) names exactly the S2 unit_id the identity helpers build", () => {
+  assertEquals(deliveryUnitKey("feature", "owner/repo#42"), featureUnitId("owner/repo#42"));
+  assertEquals(deliveryUnitKey("epic", "plan-key-1"), epicUnitId("plan-key-1"));
+  assertEquals(deliveryUnitKey("plan-task", "plan-key-1#3"), planTaskUnitId("plan-key-1", 3));
+  assertEquals(deliveryUnitKey("delivery-graph", "run-key-1"), deliveryGraphUnitId("run-key-1"));
+});
+
+test("GATE PARITY: the door dispatches iff pending, and matches isDeliveryUnitSettled for every status", () => {
+  for (const status of DELIVERY_UNIT_STATUSES as readonly DeliveryUnitStatus[]) {
+    const dispatchStatus = dispatchStatusForDelivery(status);
+    const gate = dispatchGate(dispatchStatus);
+    // Only the pre-dispatch canonical `requested` (⇒ pending) launches a fresh executor.
+    assertEquals(gate.dispatch, status === "requested", `dispatch decision for canonical ${status}`);
+    if (isDeliveryUnitSettled(status)) {
+      assertEquals(gate.reason, "settled", `${status} is settled-for-re-dispatch ⇒ short-circuit`);
+    } else if (status === "requested") {
+      assertEquals(gate.reason, "pending");
+    } else {
+      assertEquals(gate.reason, "in-flight", `${status} has a live executor ⇒ at-most-once skip`);
+    }
+  }
+});
+
+test("GATE PARITY: a unit the aggregate never recorded short-circuits as unknown-unit", () => {
+  assertEquals(dispatchGate(null), { dispatch: false, reason: "unknown-unit" });
+});
+
+test("BINDING: exactly one new delivery_units binding drives the door", () => {
+  const du = manifestBindings().filter((b) => b.table === DELIVERY_UNITS_TABLE);
+  assertEquals(du.length, 1, "there must be exactly one delivery_units instanceTracking binding");
+  const b = du[0];
+  assertEquals(b.keyField, "process_key");
+  assertEquals(b.statusField, "dispatch_status");
+  assertEquals(b.onTerminated.set, { dispatch_status: "settled" });
+  // A settled unit is terminal/resting — listing it active would let the reconciler clobber it.
+  assert(!b.activeStatuses?.includes("settled"), "settled must not be an active dispatch status");
+  // `pending` is NOT instance-tracked: it has no engine instance yet, and some pending rows (e.g.
+  // kind="plan-task") carry a NULL process_key, so a process_key-keyed reconciler would treat them as
+  // "vanished" and wrongly apply onTerminated. Only the instance-backed `dispatched` is tracked —
+  // mirroring the delivery_graph_runs binding's invariant.
+  assert(!b.activeStatuses?.includes("pending"), "pending must not be an active dispatch status");
+  assertEquals(b.activeStatuses, ["dispatched"]);
+});
+
+test("BINDING: the delivery_units__tracking VIEW provisions against the migrated schema", () => {
+  const db = new DatabaseSync(":memory:");
+  db.exec("PRAGMA foreign_keys = ON;");
+  applyMigrationSet(db, readMigrationSetFromDisk());
+  // The base aggregate exists with the door's status column; the derived tracking VIEW the binding
+  // provisions (delivery_units__tracking) is created by urban at gen/deploy time, not migration time,
+  // so here we assert the base columns the binding names are present and typed for the door to read.
+  const cols = db.prepare("PRAGMA table_info(delivery_units)").all() as { name: string }[];
+  const names = new Set(cols.map((c) => c.name));
+  assert(names.has("process_key"), "keyField process_key must exist on delivery_units");
+  assert(names.has("dispatch_status"), "statusField dispatch_status must exist on delivery_units");
+  db.close();
+});
+
+// A fake DataLayer whose `delivery_units` store is keyed on `unit_id` and whose `delivery_units__tracking`
+// derived VIEW is served by `withTrackingViews` (projecting `derived_status := seeded ?? base.dispatch_status`,
+// exactly the ADR-0065 fall-through the real runtime computes). This lets a test seed a base row whose
+// `derived_status` DIVERGES from its base `dispatch_status` — the terminated-executor case the door's
+// derived-view read exists to fold in — without a live engine.
+function memData(): DataLayer {
+  // biome-ignore lint/suspicious/noExplicitAny: test-only fake over dynamic row shapes.
+  const stores: Record<string, any[]> = {};
+  function tbl(name: string, pk = "unit_id") {
+    // biome-ignore lint/suspicious/noExplicitAny: test-only dynamic row store.
+    const rows = (stores[name] ??= [] as any[]);
+    return {
+      // biome-ignore lint/suspicious/noExplicitAny: test-only dynamic row.
+      async insert(row: any) {
+        rows.push({ ...row });
+        return row[pk];
+      },
+      async get(key: unknown) {
+        return rows.find((r) => r[pk] === key);
+      },
+    };
+  }
+  return { table: withTrackingViews((n: string, pk?: string) => tbl(n, pk)) } as any as DataLayer;
+}
+
+async function seedUnit(
+  data: DataLayer,
+  unit_id: string,
+  dispatch_status: string | null,
+  derived_status?: string,
+) {
+  const row: Record<string, unknown> = { unit_id, dispatch_status };
+  if (derived_status !== undefined) row.derived_status = derived_status;
+  await data.table(DELIVERY_UNITS_TABLE, "unit_id").insert(row);
+}
+
+test("DOOR: resolveDeliveryDispatch dispatches a pending unit off the derived VIEW", async () => {
+  const data = memData();
+  await seedUnit(data, deliveryUnitKey("feature", "owner/repo#7"), "pending");
+  const decision = await resolveDeliveryDispatch(data, "feature", "owner/repo#7");
+  assertEquals(decision, {
+    unitId: "feature:owner/repo#7",
+    kind: "feature",
+    dispatch: true,
+    jobType: "senior:feature",
+    reason: "pending",
+  });
+});
+
+test("DOOR: resolveDeliveryDispatch skips a still-dispatched unit as in-flight (at-most-once)", async () => {
+  const data = memData();
+  await seedUnit(data, deliveryUnitKey("plan-task", "plan-1#3"), "dispatched");
+  const decision = await resolveDeliveryDispatch(data, "plan-task", "plan-1#3");
+  assertEquals(decision.dispatch, false);
+  assertEquals(decision.reason, "in-flight");
+  assertEquals(decision.jobType, null);
+});
+
+test("DOOR: resolveDeliveryDispatch reads derived_status, so a terminated executor is settled not stranded dispatched", async () => {
+  // The base row still reads `dispatched` (the worker-owned transient the reconciler no longer
+  // overwrites), but the executor terminated out-of-band so the __tracking VIEW's `derived_status`
+  // is `settled` (the binding's onTerminated edge). Reading the base column would strand the unit as
+  // `in-flight`; the door MUST read `derived_status` and report `settled`. This is the regression the
+  // Copilot review flagged — a guard against reading the base table/statusField instead of the view.
+  const data = memData();
+  await seedUnit(data, deliveryUnitKey("feature", "owner/repo#9"), "dispatched", "settled");
+  const decision = await resolveDeliveryDispatch(data, "feature", "owner/repo#9");
+  assertEquals(decision.reason, "settled", "derived terminal status must win over the base dispatched");
+  assertEquals(decision.dispatch, false);
+  assertEquals(decision.jobType, null);
+});
+
+test("DOOR: resolveDeliveryDispatch refuses to launch a unit the aggregate never recorded", async () => {
+  const data = memData();
+  const decision = await resolveDeliveryDispatch(data, "feature", "owner/repo#404");
+  assertEquals(decision, {
+    unitId: "feature:owner/repo#404",
+    kind: "feature",
+    dispatch: false,
+    jobType: null,
+    reason: "unknown-unit",
+  });
+});

package/app/deliveryDispatch.ts

@@ -0,0 +1,153 @@
+// ADR 0006 slice S3 (#590) — the SINGLE dispatch door, keyed on `(kind, instanceId)`.
+//
+// Before S3 the fleet had THREE parallel dispatch paths — one per delivery-unit REPRESENTATION
+// (`feature` via feature.bpmn, `epic`/`plan-task` via plan-fanout.bpmn, `delivery-graph` via the
+// engine-native runner) — each choosing its own `senior:*` implementation job and each gating
+// re-dispatch off its own bespoke status union. ADR 0006 §2 collapses those onto ONE door that reads
+// the aggregate's `delivery_units.dispatch_status` and dispatches on the two universal facts a unit
+// carries — its `kind` and its `instanceId` — instead of three representation-specific launchers.
+//
+// What this door owns:
+//   1. The `(kind, instanceId) → unit_id` key derivation (the aggregate's universal identity; the
+//      unit_id IS `<kind>:<instanceId>`, so the door's two args ARE the delivery unit's key).
+//   2. The kind → STABLE `senior:*` dispatch-target verb map. Per #464 ("What survives" #3) the
+//      `senior:*` names are DISPATCH TARGETS, not implementations — they stay the stable verbs the
+//      deployed fleet already answers (`senior:feature`, `senior:plan`), so collapsing the doors never
+//      renames a job type.
+//   3. The single re-dispatch gate, read straight off `dispatch_status` (the S2 lifecycle derived from
+//      the S1 canonical union): dispatch ONLY when `pending`; a `dispatched` unit has a live executor
+//      (at-most-once) and a `settled` unit already reached a terminal/resting outcome — both
+//      short-circuit. This is exactly the `isDeliveryUnitSettled` re-dispatch semantics S1/S2 defined,
+//      so the one door matches every pre-collapse launcher's short-circuit without re-deriving it.
+//
+// The active/tracking half is wired in `nano.app.json`: a single `delivery_units` `instanceTracking`
+// binding (keyField `process_key`, statusField `dispatch_status`) is ADDED as the SOURCE the door is
+// driven by — `deliveryUnitActiveDispatchStatuses()` reads that one binding, so the door and the
+// framework reconciler can never drift on "what counts as in-flight". The legacy per-representation
+// bindings (`feature_runs`, `plans`, `delivery_graph_runs`, …) are retained in this slice and retired
+// onto this single binding in the later contract phase, not by this diff.
+//
+// Only `dispatched` is instance-tracked (an executor/engine instance backs it): a `pending` unit has
+// no instance yet — and some `pending` rows (e.g. `kind="plan-task"`) carry a NULL `process_key` — so
+// tracking `pending` would make the `process_key`-keyed reconciler treat those rows as "vanished" and
+// wrongly apply `onTerminated`. `settled` is terminal/resting. This mirrors the `delivery_graph_runs`
+// binding's invariant (only instance-backed statuses are instance-tracked).
+
+import type { DataLayer } from "@nanobpm/urban";
+import type { DeliveryUnitDispatchStatus, DeliveryUnitKind } from "./deliveryUnit.ts";
+import { activeStatusesFor, derivedTrackingTable } from "./instanceTracking.ts";
+
+/** The base table the single dispatch door is keyed on — the S2 aggregate. */
+export const DELIVERY_UNITS_TABLE = "delivery_units";
+
+/** Narrow a raw `derived_status` string to the closed dispatch-status domain (no `as`). Any value
+ * outside the domain — including a missing row / NULL — resolves to `null` (⇒ `unknown-unit`). */
+function asDispatchStatus(value: string | null | undefined): DeliveryUnitDispatchStatus | null {
+  return value === "pending" || value === "dispatched" || value === "settled" ? value : null;
+}
+
+/**
+ * The stable `senior:*` dispatch-target verb each delivery-unit KIND dispatches to — the collapse of
+ * the per-representation launchers onto one map (#464 "What survives" #3). The verbs are unchanged
+ * from the pre-collapse models (`app/deliveryDispatch.test.ts` pins them against the deployed BPMN):
+ *  - `feature` / `plan-task` — a single-issue implementation ⇒ `senior:feature` (feature.bpmn's
+ *    implement task and plan-fanout.bpmn's per-slice implement task both dispatch this today).
+ *  - `epic` — decomposed into a wave of slices by the planner ⇒ `senior:plan` (plan-fanout.bpmn's
+ *    decomposition task).
+ *  - `bugfix` / `chore` — reserved §2 implementation units with no legacy table yet; they implement an
+ *    issue like a feature ⇒ `senior:feature`.
+ *  - `delivery-graph` — dispatched by the engine-native runner (`app/deliveryRunner.ts`), NOT a single
+ *    agent verb: every node in the graph carries its OWN `jobType`, so the unit has no single dispatch
+ *    target. `null` records that the runner, not this verb map, launches a delivery-graph unit.
+ */
+export const DISPATCH_JOB_TYPE_BY_KIND: Readonly<Record<DeliveryUnitKind, string | null>> = {
+  feature: "senior:feature",
+  "plan-task": "senior:feature",
+  epic: "senior:plan",
+  bugfix: "senior:feature",
+  chore: "senior:feature",
+  "delivery-graph": null,
+};
+
+/** The dispatch-target verb for a kind, or `null` for a runner-launched (`delivery-graph`) unit. */
+export function dispatchJobTypeForKind(kind: DeliveryUnitKind): string | null {
+  return DISPATCH_JOB_TYPE_BY_KIND[kind];
+}
+
+/**
+ * The universal `unit_id` a `(kind, instanceId)` pair names — `<kind>:<instanceId>`. The S2 identity
+ * helpers (`featureUnitId` = `feature:<key>`, `epicUnitId` = `epic:<key>`, `planTaskUnitId` =
+ * `plan-task:<key>#<idx>`, `deliveryGraphUnitId` = `delivery-graph:<runKey>`) are all exactly this
+ * shape, so the door's two args ARE the aggregate key — no per-representation key builder survives.
+ */
+export function deliveryUnitKey(kind: DeliveryUnitKind, instanceId: string): string {
+  return `${kind}:${instanceId}`;
+}
+
+/** The non-`settled` dispatch statuses the single `delivery_units` binding declares in-flight, read
+ * from nano.app.json (the one source of truth). The door never hard-codes this set — it derives from
+ * the same binding the framework reconciler polls, so "in-flight" can't drift between the two. */
+export function deliveryUnitActiveDispatchStatuses(): readonly string[] {
+  return activeStatusesFor(DELIVERY_UNITS_TABLE);
+}
+
+/** Why the single door did or did not dispatch — a closed reason set the caller can log/route on. */
+export type DispatchReason = "pending" | "in-flight" | "settled" | "unknown-unit";
+
+/** The single dispatch door's decision for one `(kind, instanceId)`. `dispatch` is the gate; `jobType`
+ * is the stable `senior:*` target when a fresh dispatch is due (and the kind has an agent verb). */
+export interface DispatchDecision {
+  unitId: string;
+  kind: DeliveryUnitKind;
+  dispatch: boolean;
+  jobType: string | null;
+  reason: DispatchReason;
+}
+
+/**
+ * The single re-dispatch gate, applied to a `dispatch_status`. This is the ONE short-circuit rule the
+ * three pre-collapse launchers each re-implemented against their own union:
+ *  - `pending`    ⇒ dispatch (created, no executor yet — the canonical `requested`).
+ *  - `dispatched` ⇒ skip, a live executor already holds the unit (at-most-once).
+ *  - `settled`    ⇒ skip, the prior run reached a terminal / live-PR resting outcome
+ *                   (`isDeliveryUnitSettled`) — re-dispatch short-circuits onto it.
+ *  - missing row  ⇒ skip (`unknown-unit`): the door refuses to launch a unit the aggregate never saw
+ *                   rather than dispatch blind.
+ */
+export function dispatchGate(status: DeliveryUnitDispatchStatus | null): { dispatch: boolean; reason: DispatchReason } {
+  if (status === null) return { dispatch: false, reason: "unknown-unit" };
+  if (status === "pending") return { dispatch: true, reason: "pending" };
+  if (status === "dispatched") return { dispatch: false, reason: "in-flight" };
+  return { dispatch: false, reason: "settled" };
+}
+
+/**
+ * Resolve the single dispatch door for a `(kind, instanceId)`: read the unit's EFFECTIVE dispatch
+ * status off the ADR-0065 `delivery_units__tracking` VIEW's `derived_status` (NOT the base
+ * `dispatch_status`, which the reconciler no longer writes) and apply {@link dispatchGate}, returning
+ * the stable `senior:*` target verb when a fresh dispatch is due. Reading `derived_status` folds in the
+ * binding's `onTerminated` edge, so a unit whose executor terminated out-of-band is seen `settled` and
+ * re-dispatchable rather than stranded `dispatched`. A row the aggregate never recorded resolves to
+ * `unknown-unit` (no dispatch) — the door never launches blind.
+ */
+export async function resolveDeliveryDispatch(
+  data: DataLayer,
+  kind: DeliveryUnitKind,
+  instanceId: string,
+): Promise<DispatchDecision> {
+  const unitId = deliveryUnitKey(kind, instanceId);
+  const view = derivedTrackingTable<{ unit_id: string; derived_status: string | null }>(
+    data,
+    DELIVERY_UNITS_TABLE,
+    "unit_id",
+  );
+  const unit = await view.get(unitId);
+  const { dispatch, reason } = dispatchGate(asDispatchStatus(unit?.derived_status));
+  return {
+    unitId,
+    kind,
+    dispatch,
+    jobType: dispatch ? dispatchJobTypeForKind(kind) : null,
+    reason,
+  };
+}

package/app/deliveryUnit.test.ts

@@ -0,0 +1,244 @@
+// Coverage for ADR 0006 slice S2 (#589) — the `delivery_units` aggregate and its DB-level sync.
+//
+// Proves, against a REAL in-memory SQLite with the full migration set applied:
+//   1. VOCABULARY PARITY — the TS `DELIVERY_UNIT_KINDS` closed enum matches the `CHECK (kind IN (…))`
+//      constraint in migration 088 (the two lowerings of the §2 kind enum can't drift).
+//   2. DERIVATION PARITY — for every source status of every shape, the DB triggers/backfill derive the
+//      same canonical `delivery_status` as the S1 read models (app/deliveryUnitStatus.ts) and the same
+//      `dispatch_status` as the TS `dispatchStatusForDelivery` (the SQL and TS lowerings agree).
+//   3. IDENTITY — the derived `unit_id` matches the TS `*UnitId` helpers, and an epic slice node hangs
+//      under its epic (`parent_unit_id`), so the aggregate's universal key is what the door will name.
+//   4. COMPAT-VIEW PARITY — each legacy-shaped `<table>__units` VIEW is row-for-row identical to its
+//      base table over insert/update/delete, so a read path can swap onto the aggregate losslessly.
+import { DatabaseSync } from "node:sqlite";
+import { test } from "node:test";
+import { applyMigrationSet, readMigrationSetFromDisk } from "#test-migrations";
+import { assert, assertEquals } from "#test-assert";
+import {
+  DELIVERY_UNIT_KINDS,
+  deliveryGraphUnitId,
+  dispatchStatusForDelivery,
+  epicUnitId,
+  featureUnitId,
+  planTaskUnitId,
+} from "./deliveryUnit.ts";
+import {
+  type DeliveryUnitStatus,
+  deliveryGraphDeliveryStatus,
+  featureDeliveryStatus,
+  planDeliveryStatus,
+  PLAN_STATUSES,
+  planTaskDeliveryStatus,
+  toDeliveryUnitStatus,
+} from "./deliveryUnitStatus.ts";
+import { DELIVERY_GRAPH_RUN_STATUSES } from "./deliveryGraphRun.ts";
+import { FEATURE_RUN_STATUSES } from "./feature.ts";
+import { PLAN_TASK_STATUSES } from "./plan.ts";
+
+function freshDb(): DatabaseSync {
+  const db = new DatabaseSync(":memory:");
+  db.exec("PRAGMA foreign_keys = ON;");
+  applyMigrationSet(db, readMigrationSetFromDisk());
+  return db;
+}
+
+const NOW = "2026-01-01T00:00:00Z";
+const row = (db: DatabaseSync, sql: string, ...p: unknown[]) => db.prepare(sql).get(...(p as never[])) as Record<string, unknown>;
+const rows = (db: DatabaseSync, sql: string, ...p: unknown[]) => db.prepare(sql).all(...(p as never[])) as Record<string, unknown>[];
+const exec = (db: DatabaseSync, sql: string, ...p: unknown[]) => db.prepare(sql).run(...(p as never[]));
+
+test("VOCABULARY PARITY: DELIVERY_UNIT_KINDS matches migration 088's CHECK (kind IN (…))", () => {
+  const mig = readMigrationSetFromDisk().find((m) => m.name === "088_delivery_units.sql");
+  assert(mig, "088_delivery_units.sql must exist");
+  const m = mig.sql.match(/kind IN \(([^)]*)\)/);
+  assert(m, "088 must declare a CHECK (kind IN (…)) constraint");
+  const declared = m[1].split(",").map((s) => s.trim().replace(/^'|'$/g, ""));
+  assertEquals(declared, [...DELIVERY_UNIT_KINDS], "the SQL kind enum and the TS enum must agree");
+});
+
+test("DERIVATION PARITY: feature triggers derive the S1 canonical + dispatch status for every source status", () => {
+  const db = freshDb();
+  FEATURE_RUN_STATUSES.forEach((status, i) => {
+    const key = `o/r#${100 + i}`;
+    exec(
+      db,
+      `INSERT INTO feature_runs(feature_key,repo,issue_number,issue_url,base_branch,status,created_at,updated_at)
+       VALUES(?,?,?,?,?,?,?,?)`,
+      key, "o/r", 100 + i, "u", "main", status, NOW, NOW,
+    );
+    const u = row(db, "SELECT * FROM delivery_units WHERE unit_id=?", featureUnitId(key));
+    const canonical = toDeliveryUnitStatus(featureDeliveryStatus, status) as DeliveryUnitStatus;
+    assertEquals(u.kind, "feature");
+    assertEquals(u.delivery_status, canonical, `feature ${status} → canonical`);
+    assertEquals(u.dispatch_status, dispatchStatusForDelivery(canonical), `feature ${status} → dispatch`);
+    assertEquals(u.status, status, "raw legacy status is preserved verbatim");
+  });
+});
+
+test("DERIVATION PARITY: epic (plans) triggers derive the S1 canonical + dispatch status for every source status", () => {
+  const db = freshDb();
+  PLAN_STATUSES.forEach((status, i) => {
+    const key = `o/r#${200 + i}`;
+    exec(
+      db,
+      `INSERT INTO plans(plan_key,repo,issue_number,issue_url,status,created_at,updated_at)
+       VALUES(?,?,?,?,?,?,?)`,
+      key, "o/r", 200 + i, "u", status, NOW, NOW,
+    );
+    const u = row(db, "SELECT * FROM delivery_units WHERE unit_id=?", epicUnitId(key));
+    const canonical = toDeliveryUnitStatus(planDeliveryStatus, status) as DeliveryUnitStatus;
+    assertEquals(u.kind, "epic");
+    assertEquals(u.delivery_status, canonical, `epic ${status} → canonical`);
+    assertEquals(u.dispatch_status, dispatchStatusForDelivery(canonical), `epic ${status} → dispatch`);
+  });
+});
+
+test("DERIVATION PARITY + IDENTITY: plan-task nodes derive status and hang under their epic", () => {
+  const db = freshDb();
+  const planKey = "o/r#300";
+  exec(
+    db,
+    `INSERT INTO plans(plan_key,repo,issue_number,issue_url,status,created_at,updated_at) VALUES(?,?,?,?,?,?,?)`,
+    planKey, "o/r", 300, "u", "dispatched", NOW, NOW,
+  );
+  PLAN_TASK_STATUSES.forEach((status, i) => {
+    exec(
+      db,
+      `INSERT INTO plan_tasks(plan_key,task_index,task_id,status,created_at,updated_at) VALUES(?,?,?,?,?,?)`,
+      planKey, i, `t${i}`, status, NOW, NOW,
+    );
+    const u = row(db, "SELECT * FROM delivery_units WHERE unit_id=?", planTaskUnitId(planKey, i));
+    const canonical = toDeliveryUnitStatus(planTaskDeliveryStatus, status) as DeliveryUnitStatus;
+    assertEquals(u.kind, "plan-task");
+    assertEquals(u.delivery_status, canonical, `plan-task ${status} → canonical`);
+    assertEquals(u.dispatch_status, dispatchStatusForDelivery(canonical), `plan-task ${status} → dispatch`);
+    assertEquals(u.parent_unit_id, epicUnitId(planKey), "a node hangs under its epic composition");
+    assertEquals(u.node_index, i, "the node carries its slice ordinal");
+  });
+});
+
+test("DERIVATION PARITY: delivery-graph triggers derive the S1 canonical + dispatch status for every source status", () => {
+  const db = freshDb();
+  DELIVERY_GRAPH_RUN_STATUSES.forEach((status, i) => {
+    const key = `dg${i}`;
+    exec(
+      db,
+      `INSERT INTO delivery_graph_runs(run_key,digest,status,created_at,updated_at) VALUES(?,?,?,?,?)`,
+      key, "abc", status, NOW, NOW,
+    );
+    const u = row(db, "SELECT * FROM delivery_units WHERE unit_id=?", deliveryGraphUnitId(key));
+    const canonical = toDeliveryUnitStatus(deliveryGraphDeliveryStatus, status) as DeliveryUnitStatus;
+    assertEquals(u.kind, "delivery-graph");
+    assertEquals(u.delivery_status, canonical, `delivery-graph ${status} → canonical`);
+    assertEquals(u.dispatch_status, dispatchStatusForDelivery(canonical), `delivery-graph ${status} → dispatch`);
+  });
+});
+
+test("FAIL CLOSED: an unknown legacy status yields NULL delivery_status AND NULL dispatch_status (no inconsistent row)", () => {
+  // The legacy `status` columns are plain TEXT NOT NULL without a CHECK, so an unexpected value can
+  // reach the triggers. `dispatch_status` is derived FROM the canonical `delivery_status`, so when the
+  // status is unrecognised (delivery_status → NULL) dispatch_status MUST also be NULL — never a
+  // dangling 'dispatched'/'settled' on a row whose delivery_status is NULL.
+  const db = freshDb();
+  const cases: [string, () => void, string][] = [
+    [
+      "feature",
+      () =>
+        exec(
+          db,
+          `INSERT INTO feature_runs(feature_key,repo,issue_number,issue_url,base_branch,status,created_at,updated_at) VALUES(?,?,?,?,?,?,?,?)`,
+          "o/r#900", "o/r", 900, "u", "main", "bogus-status", NOW, NOW,
+        ),
+      featureUnitId("o/r#900"),
+    ],
+    [
+      "epic",
+      () =>
+        exec(
+          db,
+          `INSERT INTO plans(plan_key,repo,issue_number,issue_url,status,created_at,updated_at) VALUES(?,?,?,?,?,?,?)`,
+          "o/r#901", "o/r", 901, "u", "bogus-status", NOW, NOW,
+        ),
+      epicUnitId("o/r#901"),
+    ],
+    [
+      "delivery-graph",
+      () =>
+        exec(
+          db,
+          `INSERT INTO delivery_graph_runs(run_key,digest,status,created_at,updated_at) VALUES(?,?,?,?,?)`,
+          "dg900", "abc", "bogus-status", NOW, NOW,
+        ),
+      deliveryGraphUnitId("dg900"),
+    ],
+  ];
+  for (const [kind, insert, unitId] of cases) {
+    insert();
+    const u = row(db, "SELECT delivery_status, dispatch_status FROM delivery_units WHERE unit_id=?", unitId);
+    assertEquals(u.delivery_status, null, `${kind} unknown status → NULL delivery_status`);
+    assertEquals(u.dispatch_status, null, `${kind} unknown status → NULL dispatch_status (fail closed)`);
+  }
+
+  // plan-task needs a parent epic row first.
+  exec(db, `INSERT INTO plans(plan_key,repo,issue_number,issue_url,status,created_at,updated_at) VALUES(?,?,?,?,?,?,?)`, "o/r#902", "o/r", 902, "u", "planning", NOW, NOW);
+  exec(db, `INSERT INTO plan_tasks(plan_key,task_index,task_id,status,created_at,updated_at) VALUES(?,?,?,?,?,?)`, "o/r#902", 0, "t0", "bogus-status", NOW, NOW);
+  const pt = row(db, "SELECT delivery_status, dispatch_status FROM delivery_units WHERE unit_id=?", planTaskUnitId("o/r#902", 0));
+  assertEquals(pt.delivery_status, null, "plan-task unknown status → NULL delivery_status");
+  assertEquals(pt.dispatch_status, null, "plan-task unknown status → NULL dispatch_status (fail closed)");
+});
+
+// ── COMPAT-VIEW PARITY — each `<table>__units` VIEW is byte-identical to its base table. ────────────
+const norm = (r: Record<string, unknown>[]) =>
+  JSON.stringify(r.map((x) => Object.fromEntries(Object.entries(x).sort())));
+
+function assertViewParity(db: DatabaseSync, base: string, view: string) {
+  assertEquals(norm(rows(db, `SELECT * FROM ${base} ORDER BY 1`)), norm(rows(db, `SELECT * FROM ${view} ORDER BY 1`)), `${view} must equal ${base}`);
+}
+
+test("COMPAT-VIEW PARITY: every legacy surface is served row-for-row from the aggregate across insert/update/delete", () => {
+  const db = freshDb();
+  exec(
+    db,
+    `INSERT INTO feature_runs(feature_key,repo,issue_number,issue_url,base_branch,status,converge,auto_merge,outcome,delivery_label,title,created_at,updated_at)
+     VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?)`,
+    "o/r#1", "o/r", 1, "u", "main", "running", 1, 0, null, null, "Feat", NOW, NOW,
+  );
+  exec(
+    db,
+    `INSERT INTO plans(plan_key,repo,issue_number,issue_url,title,status,task_count,base_branch,epic_phase,created_at,updated_at)
+     VALUES(?,?,?,?,?,?,?,?,?,?,?)`,
+    "o/r#2", "o/r", 2, "u", "Epic", "planning", 2, "main", "Planning", NOW, NOW,
+  );
+  exec(
+    db,
+    `INSERT INTO plan_tasks(plan_key,task_index,task_id,title,prompt,status,pr_key,summary,wave,created_at,updated_at)
+     VALUES(?,?,?,?,?,?,?,?,?,?,?)`,
+    "o/r#2", 0, "t0", "Slice", "do it", "pending", null, null, 1, NOW, NOW,
+  );
+  exec(
+    db,
+    `INSERT INTO delivery_graph_runs(run_key,process_key,digest,status,side_effecting,node_count,human_node_count,side_effect_count,title,created_at,updated_at)
+     VALUES(?,?,?,?,?,?,?,?,?,?,?)`,
+    "dg1", null, "deadbeef", "awaiting-approval", 1, 5, 2, 3, "Graph", NOW, NOW,
+  );
+
+  const pairs: [string, string][] = [
+    ["feature_runs", "feature_runs__units"],
+    ["plans", "plans__units"],
+    ["plan_tasks", "plan_tasks__units"],
+    ["delivery_graph_runs", "delivery_graph_runs__units"],
+  ];
+  for (const [b, v] of pairs) assertViewParity(db, b, v);
+
+  // UPDATE — a status transition (and a projected column) must re-project onto the aggregate.
+  exec(db, "UPDATE feature_runs SET status=?, pr_key=?, updated_at=? WHERE feature_key=?", "merged", "o/r#5", "2026-02", "o/r#1");
+  const fu = row(db, "SELECT delivery_status, dispatch_status FROM delivery_units WHERE unit_id=?", featureUnitId("o/r#1"));
+  assertEquals(fu.delivery_status, "merged");
+  assertEquals(fu.dispatch_status, "settled");
+  for (const [b, v] of pairs) assertViewParity(db, b, v);
+
+  // DELETE — the aggregate row is dropped with the legacy row.
+  exec(db, "DELETE FROM plan_tasks WHERE plan_key=?", "o/r#2");
+  assertEquals(rows(db, "SELECT * FROM delivery_units WHERE kind='plan-task'").length, 0, "deleting a slice drops its node unit");
+  assertViewParity(db, "plan_tasks", "plan_tasks__units");
+});

package/app/deliveryUnit.ts

@@ -0,0 +1,109 @@
+// ADR 0006 slice S2 (#589) — the `delivery_units` aggregate, TS side.
+//
+// S2 collapses the four legacy delivery-unit representations (`feature_runs`, `plans`, `plan_tasks`,
+// `delivery_graph_runs`) onto ONE kind-tagged aggregate table (`db/migrations/088_delivery_units.sql`).
+// The data-level sync is done at the DB layer — triggers mirror every legacy write into the aggregate
+// (089), a backfill seeds pre-existing rows (090), and legacy-shaped compat VIEWs are served FROM the
+// aggregate (091) — so this module carries NO write path of its own; it is the canonical TS home for
+// the aggregate's VOCABULARY (the closed `kind` enum, the `dispatch_status` lifecycle), the universal
+// `unit_id` derivation, and the `dispatch_status` derivation. The last two are also lowered to SQL in
+// the trigger/backfill migrations; app/deliveryUnit.test.ts proves the two lowerings agree over the
+// full status/shape matrix (the same declare-once / parity-guard discipline S1 uses for the status
+// union — derivation over duplication).
+//
+// SCOPE (S2). This owns the aggregate's identity + dispatch vocabulary and a read gateway. The single
+// dispatch door (S3) will key on `dispatch_status`; repointing live writers onto `delivery_units` and
+// retiring the legacy write paths is the later CONTRACT phase (S3), sequenced after the
+// `instanceTracking` doors move. Nothing here changes existing behaviour.
+
+import type { DataLayer, Table } from "@nanobpm/urban";
+import { type DeliveryUnitStatus, isDeliveryUnitSettled } from "./deliveryUnitStatus.ts";
+
+/**
+ * The closed §2 `kind` enum covering every delivery unit. A run of an epic is ONE unit (`kind='epic'`,
+ * a composition over its slices); each slice is a `plan-task` node under it. `feature` is the
+ * degenerate 1-node unit; `delivery-graph` is the arbitrary-DAG unit. `bugfix`/`chore` are reserved
+ * §2 members with no legacy table yet. Kept in lockstep with the `CHECK (kind IN (…))` constraint in
+ * migration 088 — a parity test pins the two.
+ */
+export const DELIVERY_UNIT_KINDS = ["feature", "epic", "plan-task", "delivery-graph", "bugfix", "chore"] as const;
+export type DeliveryUnitKind = (typeof DELIVERY_UNIT_KINDS)[number];
+
+/**
+ * The `dispatch_status` lifecycle — the single dispatch door's status (ADR 0006 §4; the S3 door
+ * collapses onto it). Derived from the canonical {@link DeliveryUnitStatus}:
+ *  - `pending`    — created, not yet dispatched to an executor (canonical `requested`).
+ *  - `dispatched` — a live executor/instance is working the unit (a live/parked non-terminal status).
+ *  - `settled`    — terminal, or a live PR resting stage (`opened`/`converging`): re-dispatchable. This
+ *                   is exactly the {@link isDeliveryUnitSettled} predicate, so the dispatch door's
+ *                   short-circuit gate matches the redispatch-settled semantics S1 defined.
+ */
+export const DISPATCH_STATUSES = ["pending", "dispatched", "settled"] as const;
+export type DeliveryUnitDispatchStatus = (typeof DISPATCH_STATUSES)[number];
+
+/**
+ * Derive the `dispatch_status` from a canonical delivery-unit status — the TS lowering of the CASE the
+ * sync-trigger/backfill migrations (089/090) apply in SQL. `requested` ⇒ `pending`; a settled status
+ * (terminal or a PR resting stage) ⇒ `settled`; every other (live/parked) status ⇒ `dispatched`.
+ */
+export function dispatchStatusForDelivery(status: DeliveryUnitStatus): DeliveryUnitDispatchStatus {
+  if (status === "requested") return "pending";
+  if (isDeliveryUnitSettled(status)) return "settled";
+  return "dispatched";
+}
+
+// ── Universal `unit_id` — the cross-representation fact every agent can name and the dispatch door
+//    keys on (#464 "What survives" #4). Kept in lockstep with the `unit_id` expressions the
+//    trigger/backfill migrations build; app/deliveryUnit.test.ts pins the two. ─────────────────────
+
+/** The `feature:<feature_key>` unit id for a single-issue feature run. */
+export const featureUnitId = (featureKey: string): string => `feature:${featureKey}`;
+
+/** The `epic:<plan_key>` unit id for an epic (the `plans` aggregate row). */
+export const epicUnitId = (planKey: string): string => `epic:${planKey}`;
+
+/**
+ * The `plan-task:<plan_key>#<task_index>` unit id for one epic slice NODE. Its composition parent is
+ * {@link epicUnitId}(planKey) — the epic unit it hangs under.
+ */
+export const planTaskUnitId = (planKey: string, taskIndex: number): string => `plan-task:${planKey}#${taskIndex}`;
+
+/** The `delivery-graph:<run_key>` unit id for a delivery-graph run. */
+export const deliveryGraphUnitId = (runKey: string): string => `delivery-graph:${runKey}`;
+
+/**
+ * One row of the `delivery_units` aggregate. `unit_id`/`kind` are the identity pair; `delivery_status`
+ * is the canonical S1 union value; `status` is the raw legacy source status (kept verbatim so the
+ * compat VIEWs reconstruct legacy rows losslessly); `dispatch_status` is the door lifecycle. The
+ * per-shape legacy columns ride the same row (nullable off-kind). Read-only for S2 — the physical
+ * write target stays the legacy tables (the triggers mirror in).
+ */
+export interface DeliveryUnitRow {
+  unit_id: string;
+  kind: DeliveryUnitKind;
+  legacy_key: string | null;
+  legacy_id: number | null;
+  parent_unit_id: string | null;
+  node_index: number | null;
+  delivery_status: DeliveryUnitStatus | null;
+  dispatch_status: DeliveryUnitDispatchStatus | null;
+  status: string | null;
+  repo: string | null;
+  issue_number: number | null;
+  issue_url: string | null;
+  title: string | null;
+  base_branch: string | null;
+  process_key: string | null;
+  pr_key: string | null;
+  outcome: string | null;
+  created_at: string | null;
+  updated_at: string | null;
+}
+
+/**
+ * The read gateway over the `delivery_units` aggregate, keyed on the universal `unit_id`. Read-only in
+ * S2 (writes flow through the legacy tables + the sync triggers); the S3 dispatch door will own the
+ * write path once the legacy writers retire.
+ */
+export const deliveryUnits = (data: DataLayer): Table<DeliveryUnitRow> =>
+  data.table<DeliveryUnitRow>("delivery_units", "unit_id");

package/db/migrations/088_delivery_units.sql

@@ -0,0 +1,94 @@
+-- ADR 0006 slice S2 (#589) — the `delivery_units` aggregate: ONE kind-tagged table consolidating the
+-- four legacy delivery-unit representations (`feature_runs`, `plans`, `plan_tasks`,
+-- `delivery_graph_runs`) that ADR 0006 §2 declared to be one aggregate. S1 (#494) delivered the derived
+-- status union (app/deliveryUnitStatus.ts); this is its data-aggregate half.
+--
+-- EXPAND phase (ADR 0006 §S2 rollout, expand-and-contract): this migration + 089 (sync triggers) + 090
+-- (backfill) ADD the aggregate and keep it in lockstep with the legacy tables, which stay the physical
+-- WRITE target through S2 (the framework `instanceTracking` bindings + every app writer still target
+-- them; ADR 0065 makes `instanceTracking` a SOURCE that no longer writes base rows, so the legacy base
+-- `status` is only ever written through the app gateways — mirrored here at the DB level). 091 adds the
+-- legacy-shaped compat VIEWs served FROM this aggregate, parity-tested against the base tables
+-- (app/deliveryUnit.test.ts). Repointing live writers onto `delivery_units` and retiring the legacy
+-- write paths is the later CONTRACT phase (S3), which the ADR sequences after the `instanceTracking`
+-- doors move.
+--
+-- Identity (#464 "What survives"): `unit_id` is the universal, human-nameable cross-representation key
+-- the dispatch door (S3) keys on — `feature:<key>` / `epic:<plan_key>` / `plan-task:<plan_key>#<idx>` /
+-- `delivery-graph:<run_key>`. A run of an epic is ONE unit (`kind='epic'`); each of its slices is a
+-- `kind='plan-task'` node under it (`parent_unit_id = 'epic:<plan_key>'`). `kind` is the closed §2 enum.
+-- `dispatch_status` is the single dispatch door's status (S3 collapses onto it): 'pending' (created,
+-- not yet dispatched), 'dispatched' (a live executor/instance), 'settled' (terminal or a live PR
+-- resting stage — re-dispatchable), derived from the canonical `delivery_status`.
+--
+-- Every column except the identity pair (`unit_id`/`kind`) is nullable so a sync trigger over a
+-- partial legacy row can never trip a NOT NULL. `delivery_status` is the canonical S1 union value;
+-- `status` is the raw legacy source status (kept verbatim so the compat VIEWs reconstruct the legacy
+-- rows losslessly). The runner wraps each file in its own transaction — no BEGIN/COMMIT here. Numbered
+-- after the current highest prefix (087).
+
+CREATE TABLE IF NOT EXISTS delivery_units (
+  unit_id TEXT PRIMARY KEY,
+  kind TEXT NOT NULL CHECK (kind IN ('feature', 'epic', 'plan-task', 'delivery-graph', 'bugfix', 'chore')),
+  legacy_key TEXT,
+  legacy_id INTEGER,
+  parent_unit_id TEXT,
+  node_index INTEGER,
+  delivery_status TEXT,
+  dispatch_status TEXT,
+  repo TEXT,
+  issue_number INTEGER,
+  issue_url TEXT,
+  title TEXT,
+  base_branch TEXT,
+  status TEXT,
+  process_key TEXT,
+  pr_key TEXT,
+  outcome TEXT,
+  acknowledged_at TEXT,
+  list_bucket TEXT,
+  created_at TEXT,
+  updated_at TEXT,
+  converge INTEGER,
+  auto_merge INTEGER,
+  delivery_label TEXT,
+  stage TEXT,
+  stage_state TEXT,
+  stage_skipped TEXT,
+  attention TEXT,
+  task_count INTEGER,
+  gate_wave INTEGER,
+  blackboard_token TEXT,
+  retro_started_at TEXT,
+  epic_phase TEXT,
+  promotion_pr TEXT,
+  promotion_state TEXT,
+  ack_open INTEGER,
+  wait_gate TEXT,
+  wait_gate_label TEXT,
+  bound_artifacts TEXT,
+  task_id TEXT,
+  prompt TEXT,
+  summary TEXT,
+  wave INTEGER,
+  open_question TEXT,
+  answer TEXT,
+  draft_pr_key TEXT,
+  corr_key TEXT,
+  process_definition_id TEXT,
+  digest TEXT,
+  side_effecting INTEGER,
+  node_count INTEGER,
+  human_node_count INTEGER,
+  side_effect_count INTEGER,
+  phase TEXT,
+  phase_node_id TEXT,
+  human_labels TEXT
+);
+
+CREATE INDEX IF NOT EXISTS ix_delivery_units_kind ON delivery_units (kind);
+CREATE INDEX IF NOT EXISTS ix_delivery_units_dispatch_status ON delivery_units (dispatch_status);
+CREATE INDEX IF NOT EXISTS ix_delivery_units_parent ON delivery_units (parent_unit_id);
+CREATE INDEX IF NOT EXISTS ix_delivery_units_process_key ON delivery_units (process_key);
+CREATE INDEX IF NOT EXISTS ix_delivery_units_pr_key ON delivery_units (pr_key);
+CREATE INDEX IF NOT EXISTS ix_delivery_units_legacy_key ON delivery_units (legacy_key);

package/db/migrations/089_delivery_units_sync_triggers.sql

@@ -0,0 +1,94 @@
+-- ADR 0006 slice S2 (#589) — DB-level sync triggers mirroring every legacy delivery-unit write into
+-- the `delivery_units` aggregate (088). AFTER INSERT/UPDATE/DELETE on each of the four legacy tables
+-- keeps the aggregate in perfect lockstep regardless of WHICH writer touched the base row — the app
+-- gateways (app/feature.ts, app/plan.ts, app/deliveryGraphRun.ts), the plan/wave/results workers, the
+-- service pollers, AND the raw-SQL compare-and-swap in `claimRunForLaunch` (app/deliveryGraphRun.ts)
+-- that bypasses the gateway. A trigger fires at the DB level, so there is no drift surface and no
+-- write-path code to keep in sync (derivation over duplication). ADR 0065 makes `instanceTracking` a
+-- SOURCE that no longer writes base rows, so the base `status` these triggers read is always the
+-- worker-owned transient — the terminal fold stays derived on the legacy `__tracking` VIEWs.
+--
+-- `INSERT OR REPLACE` on the derived `unit_id` makes each trigger idempotent (an update re-projects
+-- the whole row). `delivery_status` (canonical S1 union) and `dispatch_status` are computed by the
+-- same CASE lowerings app/deliveryUnit.ts mirrors in TS, guarded at parity by app/deliveryUnit.test.ts.
+-- The runner wraps each file in its own transaction — no BEGIN/COMMIT here.
+
+DROP TRIGGER IF EXISTS feature_runs__du_ai;
+CREATE TRIGGER feature_runs__du_ai AFTER INSERT ON feature_runs
+BEGIN
+  INSERT OR REPLACE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, repo, issue_number, issue_url, title, base_branch, status, process_key, pr_key, converge, auto_merge, outcome, delivery_label, acknowledged_at, stage, stage_state, stage_skipped, attention, list_bucket, created_at, updated_at)
+  VALUES ('feature:' || NEW.feature_key, 'feature', NEW.feature_key, NULL, NULL, NULL, CASE WHEN NEW.status = 'running' THEN 'running' WHEN NEW.status = 'escalated' THEN 'escalated' WHEN NEW.status = 'opened' THEN 'opened' WHEN NEW.status = 'converging' THEN 'converging' WHEN NEW.status = 'awaiting_operator' THEN 'awaiting_operator' WHEN NEW.status = 'merged' THEN 'merged' WHEN NEW.status = 'converged' THEN 'converged' WHEN NEW.status = 'blocked' THEN 'blocked' WHEN NEW.status = 'skipped' THEN 'skipped' WHEN NEW.status = 'failed' THEN 'failed' WHEN NEW.status = 'abandoned' THEN 'abandoned' ELSE NULL END, CASE WHEN NEW.status IN ('opened', 'converging', 'merged', 'converged', 'blocked', 'skipped', 'failed', 'abandoned') THEN 'settled' WHEN NEW.status IN ('running', 'escalated', 'awaiting_operator') THEN 'dispatched' ELSE NULL END, NEW.repo, NEW.issue_number, NEW.issue_url, NEW.title, NEW.base_branch, NEW.status, NEW.process_key, NEW.pr_key, NEW.converge, NEW.auto_merge, NEW.outcome, NEW.delivery_label, NEW.acknowledged_at, NEW.stage, NEW.stage_state, NEW.stage_skipped, NEW.attention, NEW.list_bucket, NEW.created_at, NEW.updated_at);
+END;
+
+DROP TRIGGER IF EXISTS feature_runs__du_au;
+CREATE TRIGGER feature_runs__du_au AFTER UPDATE ON feature_runs
+BEGIN
+  INSERT OR REPLACE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, repo, issue_number, issue_url, title, base_branch, status, process_key, pr_key, converge, auto_merge, outcome, delivery_label, acknowledged_at, stage, stage_state, stage_skipped, attention, list_bucket, created_at, updated_at)
+  VALUES ('feature:' || NEW.feature_key, 'feature', NEW.feature_key, NULL, NULL, NULL, CASE WHEN NEW.status = 'running' THEN 'running' WHEN NEW.status = 'escalated' THEN 'escalated' WHEN NEW.status = 'opened' THEN 'opened' WHEN NEW.status = 'converging' THEN 'converging' WHEN NEW.status = 'awaiting_operator' THEN 'awaiting_operator' WHEN NEW.status = 'merged' THEN 'merged' WHEN NEW.status = 'converged' THEN 'converged' WHEN NEW.status = 'blocked' THEN 'blocked' WHEN NEW.status = 'skipped' THEN 'skipped' WHEN NEW.status = 'failed' THEN 'failed' WHEN NEW.status = 'abandoned' THEN 'abandoned' ELSE NULL END, CASE WHEN NEW.status IN ('opened', 'converging', 'merged', 'converged', 'blocked', 'skipped', 'failed', 'abandoned') THEN 'settled' WHEN NEW.status IN ('running', 'escalated', 'awaiting_operator') THEN 'dispatched' ELSE NULL END, NEW.repo, NEW.issue_number, NEW.issue_url, NEW.title, NEW.base_branch, NEW.status, NEW.process_key, NEW.pr_key, NEW.converge, NEW.auto_merge, NEW.outcome, NEW.delivery_label, NEW.acknowledged_at, NEW.stage, NEW.stage_state, NEW.stage_skipped, NEW.attention, NEW.list_bucket, NEW.created_at, NEW.updated_at);
+END;
+
+DROP TRIGGER IF EXISTS feature_runs__du_ad;
+CREATE TRIGGER feature_runs__du_ad AFTER DELETE ON feature_runs
+BEGIN
+  DELETE FROM delivery_units WHERE unit_id = 'feature:' || OLD.feature_key;
+END;
+
+DROP TRIGGER IF EXISTS plans__du_ai;
+CREATE TRIGGER plans__du_ai AFTER INSERT ON plans
+BEGIN
+  INSERT OR REPLACE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, repo, issue_number, issue_url, title, status, task_count, process_key, outcome, gate_wave, blackboard_token, retro_started_at, base_branch, epic_phase, promotion_pr, promotion_state, acknowledged_at, list_bucket, ack_open, wait_gate, wait_gate_label, bound_artifacts, created_at, updated_at)
+  VALUES ('epic:' || NEW.plan_key, 'epic', NEW.plan_key, NULL, NULL, NULL, CASE WHEN NEW.status = 'planning' THEN 'requested' WHEN NEW.status = 'dispatched' THEN 'running' WHEN NEW.status = 'done' THEN 'done' WHEN NEW.status = 'failed' THEN 'failed' WHEN NEW.status = 'abandoned' THEN 'abandoned' ELSE NULL END, CASE WHEN NEW.status IN ('planning') THEN 'pending' WHEN NEW.status IN ('done', 'failed', 'abandoned') THEN 'settled' WHEN NEW.status IN ('dispatched') THEN 'dispatched' ELSE NULL END, NEW.repo, NEW.issue_number, NEW.issue_url, NEW.title, NEW.status, NEW.task_count, NEW.process_key, NEW.outcome, NEW.gate_wave, NEW.blackboard_token, NEW.retro_started_at, NEW.base_branch, NEW.epic_phase, NEW.promotion_pr, NEW.promotion_state, NEW.acknowledged_at, NEW.list_bucket, NEW.ack_open, NEW.wait_gate, NEW.wait_gate_label, NEW.bound_artifacts, NEW.created_at, NEW.updated_at);
+END;
+
+DROP TRIGGER IF EXISTS plans__du_au;
+CREATE TRIGGER plans__du_au AFTER UPDATE ON plans
+BEGIN
+  INSERT OR REPLACE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, repo, issue_number, issue_url, title, status, task_count, process_key, outcome, gate_wave, blackboard_token, retro_started_at, base_branch, epic_phase, promotion_pr, promotion_state, acknowledged_at, list_bucket, ack_open, wait_gate, wait_gate_label, bound_artifacts, created_at, updated_at)
+  VALUES ('epic:' || NEW.plan_key, 'epic', NEW.plan_key, NULL, NULL, NULL, CASE WHEN NEW.status = 'planning' THEN 'requested' WHEN NEW.status = 'dispatched' THEN 'running' WHEN NEW.status = 'done' THEN 'done' WHEN NEW.status = 'failed' THEN 'failed' WHEN NEW.status = 'abandoned' THEN 'abandoned' ELSE NULL END, CASE WHEN NEW.status IN ('planning') THEN 'pending' WHEN NEW.status IN ('done', 'failed', 'abandoned') THEN 'settled' WHEN NEW.status IN ('dispatched') THEN 'dispatched' ELSE NULL END, NEW.repo, NEW.issue_number, NEW.issue_url, NEW.title, NEW.status, NEW.task_count, NEW.process_key, NEW.outcome, NEW.gate_wave, NEW.blackboard_token, NEW.retro_started_at, NEW.base_branch, NEW.epic_phase, NEW.promotion_pr, NEW.promotion_state, NEW.acknowledged_at, NEW.list_bucket, NEW.ack_open, NEW.wait_gate, NEW.wait_gate_label, NEW.bound_artifacts, NEW.created_at, NEW.updated_at);
+END;
+
+DROP TRIGGER IF EXISTS plans__du_ad;
+CREATE TRIGGER plans__du_ad AFTER DELETE ON plans
+BEGIN
+  DELETE FROM delivery_units WHERE unit_id = 'epic:' || OLD.plan_key;
+END;
+
+DROP TRIGGER IF EXISTS plan_tasks__du_ai;
+CREATE TRIGGER plan_tasks__du_ai AFTER INSERT ON plan_tasks
+BEGIN
+  INSERT OR REPLACE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, title, prompt, status, pr_key, summary, wave, open_question, answer, draft_pr_key, corr_key, created_at, updated_at, task_id)
+  VALUES ('plan-task:' || NEW.plan_key || '#' || NEW.task_index, 'plan-task', NEW.plan_key, NEW.id, 'epic:' || NEW.plan_key, NEW.task_index, CASE WHEN NEW.status = 'pending' THEN 'requested' WHEN NEW.status = 'opened' THEN 'opened' WHEN NEW.status = 'blocked' THEN 'blocked' WHEN NEW.status = 'skipped' THEN 'skipped' WHEN NEW.status = 'escalated' THEN 'escalated' WHEN NEW.status = 'waiting-for-lane' THEN 'waiting' WHEN NEW.status = 'abandoned' THEN 'abandoned' ELSE NULL END, CASE WHEN NEW.status IN ('pending') THEN 'pending' WHEN NEW.status IN ('opened', 'blocked', 'skipped', 'abandoned') THEN 'settled' WHEN NEW.status IN ('escalated', 'waiting-for-lane') THEN 'dispatched' ELSE NULL END, NEW.title, NEW.prompt, NEW.status, NEW.pr_key, NEW.summary, NEW.wave, NEW.open_question, NEW.answer, NEW.draft_pr_key, NEW.corr_key, NEW.created_at, NEW.updated_at, NEW.task_id);
+END;
+
+DROP TRIGGER IF EXISTS plan_tasks__du_au;
+CREATE TRIGGER plan_tasks__du_au AFTER UPDATE ON plan_tasks
+BEGIN
+  INSERT OR REPLACE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, title, prompt, status, pr_key, summary, wave, open_question, answer, draft_pr_key, corr_key, created_at, updated_at, task_id)
+  VALUES ('plan-task:' || NEW.plan_key || '#' || NEW.task_index, 'plan-task', NEW.plan_key, NEW.id, 'epic:' || NEW.plan_key, NEW.task_index, CASE WHEN NEW.status = 'pending' THEN 'requested' WHEN NEW.status = 'opened' THEN 'opened' WHEN NEW.status = 'blocked' THEN 'blocked' WHEN NEW.status = 'skipped' THEN 'skipped' WHEN NEW.status = 'escalated' THEN 'escalated' WHEN NEW.status = 'waiting-for-lane' THEN 'waiting' WHEN NEW.status = 'abandoned' THEN 'abandoned' ELSE NULL END, CASE WHEN NEW.status IN ('pending') THEN 'pending' WHEN NEW.status IN ('opened', 'blocked', 'skipped', 'abandoned') THEN 'settled' WHEN NEW.status IN ('escalated', 'waiting-for-lane') THEN 'dispatched' ELSE NULL END, NEW.title, NEW.prompt, NEW.status, NEW.pr_key, NEW.summary, NEW.wave, NEW.open_question, NEW.answer, NEW.draft_pr_key, NEW.corr_key, NEW.created_at, NEW.updated_at, NEW.task_id);
+END;
+
+DROP TRIGGER IF EXISTS plan_tasks__du_ad;
+CREATE TRIGGER plan_tasks__du_ad AFTER DELETE ON plan_tasks
+BEGIN
+  DELETE FROM delivery_units WHERE unit_id = 'plan-task:' || OLD.plan_key || '#' || OLD.task_index;
+END;
+
+DROP TRIGGER IF EXISTS delivery_graph_runs__du_ai;
+CREATE TRIGGER delivery_graph_runs__du_ai AFTER INSERT ON delivery_graph_runs
+BEGIN
+  INSERT OR REPLACE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, process_key, process_definition_id, digest, status, side_effecting, node_count, human_node_count, side_effect_count, title, phase, phase_node_id, human_labels, created_at, updated_at)
+  VALUES ('delivery-graph:' || NEW.run_key, 'delivery-graph', NEW.run_key, NULL, NULL, NULL, CASE WHEN NEW.status = 'awaiting-approval' THEN 'requested' WHEN NEW.status = 'running' THEN 'running' WHEN NEW.status = 'done' THEN 'done' WHEN NEW.status = 'failed' THEN 'failed' WHEN NEW.status = 'abandoned' THEN 'abandoned' ELSE NULL END, CASE WHEN NEW.status IN ('awaiting-approval') THEN 'pending' WHEN NEW.status IN ('done', 'failed', 'abandoned') THEN 'settled' WHEN NEW.status IN ('running') THEN 'dispatched' ELSE NULL END, NEW.process_key, NEW.process_definition_id, NEW.digest, NEW.status, NEW.side_effecting, NEW.node_count, NEW.human_node_count, NEW.side_effect_count, NEW.title, NEW.phase, NEW.phase_node_id, NEW.human_labels, NEW.created_at, NEW.updated_at);
+END;
+
+DROP TRIGGER IF EXISTS delivery_graph_runs__du_au;
+CREATE TRIGGER delivery_graph_runs__du_au AFTER UPDATE ON delivery_graph_runs
+BEGIN
+  INSERT OR REPLACE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, process_key, process_definition_id, digest, status, side_effecting, node_count, human_node_count, side_effect_count, title, phase, phase_node_id, human_labels, created_at, updated_at)
+  VALUES ('delivery-graph:' || NEW.run_key, 'delivery-graph', NEW.run_key, NULL, NULL, NULL, CASE WHEN NEW.status = 'awaiting-approval' THEN 'requested' WHEN NEW.status = 'running' THEN 'running' WHEN NEW.status = 'done' THEN 'done' WHEN NEW.status = 'failed' THEN 'failed' WHEN NEW.status = 'abandoned' THEN 'abandoned' ELSE NULL END, CASE WHEN NEW.status IN ('awaiting-approval') THEN 'pending' WHEN NEW.status IN ('done', 'failed', 'abandoned') THEN 'settled' WHEN NEW.status IN ('running') THEN 'dispatched' ELSE NULL END, NEW.process_key, NEW.process_definition_id, NEW.digest, NEW.status, NEW.side_effecting, NEW.node_count, NEW.human_node_count, NEW.side_effect_count, NEW.title, NEW.phase, NEW.phase_node_id, NEW.human_labels, NEW.created_at, NEW.updated_at);
+END;
+
+DROP TRIGGER IF EXISTS delivery_graph_runs__du_ad;
+CREATE TRIGGER delivery_graph_runs__du_ad AFTER DELETE ON delivery_graph_runs
+BEGIN
+  DELETE FROM delivery_units WHERE unit_id = 'delivery-graph:' || OLD.run_key;
+END;

package/db/migrations/090_delivery_units_backfill.sql

@@ -0,0 +1,120 @@
+-- ADR 0006 slice S2 (#589) — backfill the `delivery_units` aggregate (088) from the existing rows of
+-- the four legacy tables, using the SAME projection the sync triggers (089) apply going forward. Idempotent
+-- (`INSERT OR IGNORE` on the `unit_id` PK) so re-running the migration set — or upgrading an install
+-- whose triggers already mirrored some rows — never double-inserts. Runs AFTER the triggers so a fresh
+-- install with seeded legacy rows is fully covered either way (triggers fire on live writes; this seeds
+-- pre-existing rows). The runner wraps each file in its own transaction — no BEGIN/COMMIT here.
+
+INSERT OR IGNORE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, repo, issue_number, issue_url, title, base_branch, status, process_key, pr_key, converge, auto_merge, outcome, delivery_label, acknowledged_at, stage, stage_state, stage_skipped, attention, list_bucket, created_at, updated_at)
+  SELECT 'feature:' || feature_runs.feature_key AS unit_id,
+         'feature' AS kind,
+         feature_runs.feature_key AS legacy_key,
+         NULL AS legacy_id,
+         NULL AS parent_unit_id,
+         NULL AS node_index,
+         CASE WHEN feature_runs.status = 'running' THEN 'running' WHEN feature_runs.status = 'escalated' THEN 'escalated' WHEN feature_runs.status = 'opened' THEN 'opened' WHEN feature_runs.status = 'converging' THEN 'converging' WHEN feature_runs.status = 'awaiting_operator' THEN 'awaiting_operator' WHEN feature_runs.status = 'merged' THEN 'merged' WHEN feature_runs.status = 'converged' THEN 'converged' WHEN feature_runs.status = 'blocked' THEN 'blocked' WHEN feature_runs.status = 'skipped' THEN 'skipped' WHEN feature_runs.status = 'failed' THEN 'failed' WHEN feature_runs.status = 'abandoned' THEN 'abandoned' ELSE NULL END AS delivery_status,
+         CASE WHEN feature_runs.status IN ('opened', 'converging', 'merged', 'converged', 'blocked', 'skipped', 'failed', 'abandoned') THEN 'settled' WHEN feature_runs.status IN ('running', 'escalated', 'awaiting_operator') THEN 'dispatched' ELSE NULL END AS dispatch_status,
+         feature_runs.repo AS repo,
+         feature_runs.issue_number AS issue_number,
+         feature_runs.issue_url AS issue_url,
+         feature_runs.title AS title,
+         feature_runs.base_branch AS base_branch,
+         feature_runs.status AS status,
+         feature_runs.process_key AS process_key,
+         feature_runs.pr_key AS pr_key,
+         feature_runs.converge AS converge,
+         feature_runs.auto_merge AS auto_merge,
+         feature_runs.outcome AS outcome,
+         feature_runs.delivery_label AS delivery_label,
+         feature_runs.acknowledged_at AS acknowledged_at,
+         feature_runs.stage AS stage,
+         feature_runs.stage_state AS stage_state,
+         feature_runs.stage_skipped AS stage_skipped,
+         feature_runs.attention AS attention,
+         feature_runs.list_bucket AS list_bucket,
+         feature_runs.created_at AS created_at,
+         feature_runs.updated_at AS updated_at
+  FROM feature_runs;
+
+INSERT OR IGNORE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, repo, issue_number, issue_url, title, status, task_count, process_key, outcome, gate_wave, blackboard_token, retro_started_at, base_branch, epic_phase, promotion_pr, promotion_state, acknowledged_at, list_bucket, ack_open, wait_gate, wait_gate_label, bound_artifacts, created_at, updated_at)
+  SELECT 'epic:' || plans.plan_key AS unit_id,
+         'epic' AS kind,
+         plans.plan_key AS legacy_key,
+         NULL AS legacy_id,
+         NULL AS parent_unit_id,
+         NULL AS node_index,
+         CASE WHEN plans.status = 'planning' THEN 'requested' WHEN plans.status = 'dispatched' THEN 'running' WHEN plans.status = 'done' THEN 'done' WHEN plans.status = 'failed' THEN 'failed' WHEN plans.status = 'abandoned' THEN 'abandoned' ELSE NULL END AS delivery_status,
+         CASE WHEN plans.status IN ('planning') THEN 'pending' WHEN plans.status IN ('done', 'failed', 'abandoned') THEN 'settled' WHEN plans.status IN ('dispatched') THEN 'dispatched' ELSE NULL END AS dispatch_status,
+         plans.repo AS repo,
+         plans.issue_number AS issue_number,
+         plans.issue_url AS issue_url,
+         plans.title AS title,
+         plans.status AS status,
+         plans.task_count AS task_count,
+         plans.process_key AS process_key,
+         plans.outcome AS outcome,
+         plans.gate_wave AS gate_wave,
+         plans.blackboard_token AS blackboard_token,
+         plans.retro_started_at AS retro_started_at,
+         plans.base_branch AS base_branch,
+         plans.epic_phase AS epic_phase,
+         plans.promotion_pr AS promotion_pr,
+         plans.promotion_state AS promotion_state,
+         plans.acknowledged_at AS acknowledged_at,
+         plans.list_bucket AS list_bucket,
+         plans.ack_open AS ack_open,
+         plans.wait_gate AS wait_gate,
+         plans.wait_gate_label AS wait_gate_label,
+         plans.bound_artifacts AS bound_artifacts,
+         plans.created_at AS created_at,
+         plans.updated_at AS updated_at
+  FROM plans;
+
+INSERT OR IGNORE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, title, prompt, status, pr_key, summary, wave, open_question, answer, draft_pr_key, corr_key, created_at, updated_at, task_id)
+  SELECT 'plan-task:' || plan_tasks.plan_key || '#' || plan_tasks.task_index AS unit_id,
+         'plan-task' AS kind,
+         plan_tasks.plan_key AS legacy_key,
+         plan_tasks.id AS legacy_id,
+         'epic:' || plan_tasks.plan_key AS parent_unit_id,
+         plan_tasks.task_index AS node_index,
+         CASE WHEN plan_tasks.status = 'pending' THEN 'requested' WHEN plan_tasks.status = 'opened' THEN 'opened' WHEN plan_tasks.status = 'blocked' THEN 'blocked' WHEN plan_tasks.status = 'skipped' THEN 'skipped' WHEN plan_tasks.status = 'escalated' THEN 'escalated' WHEN plan_tasks.status = 'waiting-for-lane' THEN 'waiting' WHEN plan_tasks.status = 'abandoned' THEN 'abandoned' ELSE NULL END AS delivery_status,
+         CASE WHEN plan_tasks.status IN ('pending') THEN 'pending' WHEN plan_tasks.status IN ('opened', 'blocked', 'skipped', 'abandoned') THEN 'settled' WHEN plan_tasks.status IN ('escalated', 'waiting-for-lane') THEN 'dispatched' ELSE NULL END AS dispatch_status,
+         plan_tasks.title AS title,
+         plan_tasks.prompt AS prompt,
+         plan_tasks.status AS status,
+         plan_tasks.pr_key AS pr_key,
+         plan_tasks.summary AS summary,
+         plan_tasks.wave AS wave,
+         plan_tasks.open_question AS open_question,
+         plan_tasks.answer AS answer,
+         plan_tasks.draft_pr_key AS draft_pr_key,
+         plan_tasks.corr_key AS corr_key,
+         plan_tasks.created_at AS created_at,
+         plan_tasks.updated_at AS updated_at,
+         plan_tasks.task_id AS task_id
+  FROM plan_tasks;
+
+INSERT OR IGNORE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, process_key, process_definition_id, digest, status, side_effecting, node_count, human_node_count, side_effect_count, title, phase, phase_node_id, human_labels, created_at, updated_at)
+  SELECT 'delivery-graph:' || delivery_graph_runs.run_key AS unit_id,
+         'delivery-graph' AS kind,
+         delivery_graph_runs.run_key AS legacy_key,
+         NULL AS legacy_id,
+         NULL AS parent_unit_id,
+         NULL AS node_index,
+         CASE WHEN delivery_graph_runs.status = 'awaiting-approval' THEN 'requested' WHEN delivery_graph_runs.status = 'running' THEN 'running' WHEN delivery_graph_runs.status = 'done' THEN 'done' WHEN delivery_graph_runs.status = 'failed' THEN 'failed' WHEN delivery_graph_runs.status = 'abandoned' THEN 'abandoned' ELSE NULL END AS delivery_status,
+         CASE WHEN delivery_graph_runs.status IN ('awaiting-approval') THEN 'pending' WHEN delivery_graph_runs.status IN ('done', 'failed', 'abandoned') THEN 'settled' WHEN delivery_graph_runs.status IN ('running') THEN 'dispatched' ELSE NULL END AS dispatch_status,
+         delivery_graph_runs.process_key AS process_key,
+         delivery_graph_runs.process_definition_id AS process_definition_id,
+         delivery_graph_runs.digest AS digest,
+         delivery_graph_runs.status AS status,
+         delivery_graph_runs.side_effecting AS side_effecting,
+         delivery_graph_runs.node_count AS node_count,
+         delivery_graph_runs.human_node_count AS human_node_count,
+         delivery_graph_runs.side_effect_count AS side_effect_count,
+         delivery_graph_runs.title AS title,
+         delivery_graph_runs.phase AS phase,
+         delivery_graph_runs.phase_node_id AS phase_node_id,
+         delivery_graph_runs.human_labels AS human_labels,
+         delivery_graph_runs.created_at AS created_at,
+         delivery_graph_runs.updated_at AS updated_at
+  FROM delivery_graph_runs;

package/db/migrations/091_delivery_units_read_models.sql

@@ -0,0 +1,111 @@
+-- ADR 0006 slice S2 (#589) — legacy-shaped compatibility VIEWs served FROM the `delivery_units`
+-- aggregate (088). Each VIEW reconstructs one legacy table's exact column set from the kind-tagged
+-- aggregate row, so a read path can swap onto the aggregate with byte-identical results — the
+-- "legacy tables become VIEWs/rows over the aggregate" surface of ADR 0006 §2, guarded by the parity
+-- tests in app/deliveryUnit.test.ts (each VIEW is proven row-for-row equal to its base table over the
+-- full status/shape matrix). These are ADDITIVE read surfaces; the live pages/read-models keep binding
+-- the physical base tables until S3 moves the writers, so no behaviour changes here.
+--
+-- A single plain `CREATE VIEW … SELECT … FROM delivery_units` per shape (one top-level FROM, every
+-- column aliased) so the static pages<->schema contract guard can parse the column list. The runner
+-- wraps each file in its own transaction — no BEGIN/COMMIT here.
+
+DROP VIEW IF EXISTS feature_runs__units;
+CREATE VIEW feature_runs__units AS
+SELECT
+  du.legacy_key AS feature_key,
+  du.repo AS repo,
+  du.issue_number AS issue_number,
+  du.issue_url AS issue_url,
+  du.base_branch AS base_branch,
+  du.status AS status,
+  du.process_key AS process_key,
+  du.pr_key AS pr_key,
+  du.converge AS converge,
+  du.auto_merge AS auto_merge,
+  du.outcome AS outcome,
+  du.created_at AS created_at,
+  du.updated_at AS updated_at,
+  du.delivery_label AS delivery_label,
+  du.title AS title,
+  du.acknowledged_at AS acknowledged_at,
+  du.stage AS stage,
+  du.stage_state AS stage_state,
+  du.stage_skipped AS stage_skipped,
+  du.attention AS attention,
+  du.list_bucket AS list_bucket
+FROM delivery_units du
+WHERE du.kind = 'feature';
+
+DROP VIEW IF EXISTS plans__units;
+CREATE VIEW plans__units AS
+SELECT
+  du.legacy_key AS plan_key,
+  du.repo AS repo,
+  du.issue_number AS issue_number,
+  du.issue_url AS issue_url,
+  du.title AS title,
+  du.status AS status,
+  du.task_count AS task_count,
+  du.process_key AS process_key,
+  du.outcome AS outcome,
+  du.created_at AS created_at,
+  du.updated_at AS updated_at,
+  du.gate_wave AS gate_wave,
+  du.blackboard_token AS blackboard_token,
+  du.retro_started_at AS retro_started_at,
+  du.base_branch AS base_branch,
+  du.epic_phase AS epic_phase,
+  du.promotion_pr AS promotion_pr,
+  du.promotion_state AS promotion_state,
+  du.acknowledged_at AS acknowledged_at,
+  du.list_bucket AS list_bucket,
+  du.ack_open AS ack_open,
+  du.wait_gate AS wait_gate,
+  du.wait_gate_label AS wait_gate_label,
+  du.bound_artifacts AS bound_artifacts
+FROM delivery_units du
+WHERE du.kind = 'epic';
+
+DROP VIEW IF EXISTS plan_tasks__units;
+CREATE VIEW plan_tasks__units AS
+SELECT
+  du.legacy_id AS id,
+  du.legacy_key AS plan_key,
+  du.node_index AS task_index,
+  du.task_id AS task_id,
+  du.title AS title,
+  du.prompt AS prompt,
+  du.status AS status,
+  du.pr_key AS pr_key,
+  du.summary AS summary,
+  du.created_at AS created_at,
+  du.updated_at AS updated_at,
+  du.wave AS wave,
+  du.open_question AS open_question,
+  du.answer AS answer,
+  du.draft_pr_key AS draft_pr_key,
+  du.corr_key AS corr_key
+FROM delivery_units du
+WHERE du.kind = 'plan-task';
+
+DROP VIEW IF EXISTS delivery_graph_runs__units;
+CREATE VIEW delivery_graph_runs__units AS
+SELECT
+  du.legacy_key AS run_key,
+  du.process_key AS process_key,
+  du.process_definition_id AS process_definition_id,
+  du.digest AS digest,
+  du.status AS status,
+  du.side_effecting AS side_effecting,
+  du.node_count AS node_count,
+  du.human_node_count AS human_node_count,
+  du.side_effect_count AS side_effect_count,
+  du.title AS title,
+  du.phase AS phase,
+  du.phase_node_id AS phase_node_id,
+  du.human_labels AS human_labels,
+  du.created_at AS created_at,
+  du.updated_at AS updated_at
+FROM delivery_units du
+WHERE du.kind = 'delivery-graph';

package/nano.app.json

@@ -95,6 +95,20 @@
         }
       },
       "pollMs": 5000
+    },
+    {
+      "table": "delivery_units",
+      "keyField": "process_key",
+      "statusField": "dispatch_status",
+      "activeStatuses": [
+        "dispatched"
+      ],
+      "onTerminated": {
+        "set": {
+          "dispatch_status": "settled"
+        }
+      },
+      "pollMs": 5000
     }
   ],
   "workers": [

package/package.json

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