@nanobpm/nano-workforce 0.155.0 → 0.156.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [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

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/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.155.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",