@nanobpm/nano-workforce 0.123.2 → 0.125.0

package/app/stage.ts

@@ -1,41 +1,36 @@
-// Canonical feature-run pipeline stage model (issue #254 §1) — the ONE source of truth for the
-// derived pipeline surface the Feature view renders. Mirrors the single-source-of-truth style of
-// `deriveDelivery` (app/delivery.ts) and `classifyEscalation` (app/escalationTaxonomy.ts): a PURE,
-// read-only function with no data access. The feature_runs gateway (app/feature.ts) projects its
-// output onto the stored `stage`/`stage_state`/`stage_skipped`/`attention` columns at write time,
-// exactly as `delivery_label` is projected — so the declarative dataGrid page consumes ready, stored
-// columns (bound by `{"field":…}`) and never has to call TS or express OR/null in its flat filter DSL.
+// Canonical feature-run pipeline stage model (issue #254 §1) — the ergonomic TS façade over the ONE
+// derived-read-model declaration in app/featureReadModel.ts. The pipeline surface the Feature view
+// renders (`stage`/`stage_state`/`stage_skipped`/`attention`/`list_bucket`) is DERIVED, never ground
+// truth: each column is a pure function of a feature run's own `status`/`pr_key`/`converge`/
+// `auto_merge`/`acknowledged_at` plus, for `attention`, the engine's OPEN-user-task set.
 //
-// The mapping is TOTAL and DETERMINISTIC over all 11 FEATURE_RUN_STATUSES, computed from ONLY the
-// fields stored on the row — never a "previous"/"underlying" stage, because a FeatureRun stores only
-// its CURRENT status (any prior stage was overwritten on transition). Do NOT duplicate this mapping
-// anywhere (not in SQL, not in the page, not in each poller/worker): every writer flows through the
-// gateway, which is the single caller.
+// SINGLE SOURCE OF TRUTH (ADR-0065, nano-ide#452). These derivations are declared ONCE, in Urban's
+// closed expression DSL (`featureReadModel`, app/featureReadModel.ts), and compiled to BOTH the SQLite
+// VIEW (migration 076) and the runtime TS functions used here. `deriveStage`/`deriveListBucket` are
+// now thin ADAPTERS that evaluate that declaration's compiled functions (`fnFor`) — they do NOT
+// re-express the CASE/EXISTS logic in TypeScript, so the SQL and TS lowerings cannot drift (the former
+// hand-written parity test becomes the framework-owned `assertReadModelParity` regression guard). The
+// mapping remains TOTAL and DETERMINISTIC over all 11 FEATURE_RUN_STATUSES. Do NOT duplicate it
+// anywhere (not in SQL, not in the page, not in each poller/worker): every reader flows through the
+// VIEW or these adapters, both sourced from the one declaration.
+
+import { type FeatureReadModelDerivedColumn, featureReadModel, STAGE_DONE_STATUSES, USER_TASKS_PROJECTION } from "./featureReadModel.ts";
+
+// Re-exported for back-compat with existing importers (operations/acknowledgeDone.ts). Its canonical
+// home is now app/featureReadModel.ts, where it feeds the terminal tier of the derived columns.
+export { STAGE_DONE_STATUSES };
 
 /** The canonical pipeline stage keys, in path order. `Merging` is a path/visual stage the renderer
  * fills as upcoming — no status maps to it as the ACTIVE stage (intentional). */
 export const STAGE_KEYS = ["Requested", "Implementing", "PR open", "Converging", "Merging", "Done"] as const;
 export type StageKey = (typeof STAGE_KEYS)[number];
 
-/** The active stage's render state, in the urban 0.53.0 `kind:"pipeline"` column's EXACT vocabulary:
+/** The active stage's render state, in the urban `kind:"pipeline"` column's EXACT vocabulary:
  * `ok` (Done ✓ success), `failed` (Done ✕ failure), `blocked` (blocked glyph), or `null` (in-progress
  * → the renderer treats it as `active`). Any OTHER string silently degrades to `active` in the
  * renderer, so a failed run MUST emit `'failed'` (not `'fail'`) to render as a failure. */
 export type StageState = "ok" | "failed" | "blocked" | null;
 
-/** The 6 TRULY-terminal statuses that map to the `Done` stage. Distinct from
- * `FEATURE_TERMINAL_STATUSES` (app/feature.ts), which is the redispatch-settled set and also counts
- * `opened`/`converging` as terminal — those are LIVE pipeline stages (`PR open`/`Converging`), NOT
- * Done, so this list must stay separate. Also the basis of the `list_bucket` history partition. */
-export const STAGE_DONE_STATUSES: readonly string[] = [
-  "merged",
-  "converged",
-  "blocked",
-  "failed",
-  "skipped",
-  "abandoned",
-];
-
 /** The subset of a FeatureRun `deriveStage` reads. FeatureRun (app/feature.ts) structurally satisfies
  * this; keeping the input structural avoids a stage.ts ↔ feature.ts import cycle. */
 export interface StageInput {
@@ -48,7 +43,8 @@ export interface StageInput {
    * authoritative "who is waiting on a human" set). `attention` derives from THESE, never from the
    * drift-prone `status` variable — so once an escalation is answered (its `user_tasks` row deleted)
    * the badge clears immediately even while `status` still reads a stale `"escalated"`. Omitted/false
-   * ⇒ no open task ⇒ no badge. `feature_read_model` (075) mirrors this with correlated EXISTS lookups. */
+   * ⇒ no open task ⇒ no badge. These booleans are lowered into synthetic `user_tasks` projection rows
+   * so this façade evaluates the SAME `exists(...)` derivation the VIEW compiles. */
   hasOpenBlockedTask?: boolean | null;
   hasOpenEscalationTask?: boolean | null;
 }
@@ -62,60 +58,58 @@ export interface DerivedStage {
   attention: string | null;
 }
 
-const truthy = (v: number | boolean | null | undefined): boolean => v === true || (typeof v === "number" && v !== 0);
-
-/** Derive the canonical pipeline stage, its render state, its not-in-path set, and its attention badge
- * for one feature run. Pure and read-only — TOTAL over all 11 statuses (never returns undefined). */
-export function deriveStage(run: StageInput): DerivedStage {
-  const { status } = run;
+/** The synthetic correlation key threaded through the `attention` derivation: the base row's
+ * `feature_key` and each synthesised open-task row's `subject_key` share this value so the compiled
+ * `exists(... WHERE subject_key = feature_key ...)` predicate matches. Its concrete value is
+ * immaterial (it never leaves this function); it only has to be consistent between the two. */
+const SELF_KEY = "self";
 
-  // TERMINAL tier — the 6 truly-terminal statuses collapse to Done. Unconditional: terminal `blocked`
-  // is the issue §1 'Done ✕' row (state `blocked`), NOT Implementing.
-  let stage: StageKey;
-  let state: StageState;
-  if (STAGE_DONE_STATUSES.includes(status)) {
-    stage = "Done";
-    state =
-      status === "merged" || status === "converged"
-        ? "ok"
-        : status === "blocked"
-          ? "blocked"
-          : "failed"; // failed / skipped / abandoned
-  } else {
-    // LIVE/PARKED tier — one shared rule for every non-terminal status. `escalated`/`awaiting_operator`
-    // are parked but their stored fields still describe WHERE in the pipeline they stalled, so they run
-    // through the same rule as a live run; their attention comes from the badge (below), not the stage.
-    if (status === "converging") stage = "Converging";
-    else if ((run.pr_key ?? "") !== "" || status === "opened") stage = "PR open";
-    else if (status === "running" || status === "escalated" || status === "awaiting_operator") stage = "Implementing";
-    else stage = "Requested";
-    state = null;
-  }
-
-  // `skipped`: stages not in this row's path, purely from converge/auto_merge.
-  const converge = truthy(run.converge);
-  const autoMerge = truthy(run.auto_merge);
-  const skippedKeys: StageKey[] = !converge ? ["Converging", "Merging"] : !autoMerge ? ["Merging"] : [];
+/** The `user_tasks` projection rows a `StageInput`'s open-task booleans stand for — one row per OPEN
+ * operator user task, keyed exactly as `pollUserTasks` records them, so the compiled `attention`
+ * derivation sees the same engine-truth shape at runtime and here. */
+function openTaskRows(run: StageInput): Array<Record<string, unknown>> {
+  const rows: Array<Record<string, unknown>> = [];
+  if (run.hasOpenBlockedTask === true) rows.push({ subject_type: "feature", subject_key: SELF_KEY, element_id: "feature-blocked" });
+  if (run.hasOpenEscalationTask === true) rows.push({ subject_type: "feature", subject_key: SELF_KEY, element_id: "feature-escalation" });
+  return rows;
+}
 
-  // `attention`: a short badge for the active stage (the renderer colours it from `state`). This is how
-  // a parked `awaiting_operator`/`escalated` run surfaces as attention WITHOUT altering its stage.
-  // Derived from ENGINE TRUTH — the presence of an OPEN native user task (issue #422), NOT from the
-  // `status` variable. `status` is worker-written imperatively and goes stale on the answer-loop back
-  // into `implement-task` (the process does not reset it), so a run whose escalation was already
-  // ANSWERED still reads `status="escalated"` until its next job completes; sourcing the badge from
-  // that value made the read model lie (a resolved run flagged ⚠ on Overview). The authoritative
-  // "who is waiting on a human" set is the `user_tasks` inbox (`pollUserTasks`), which holds a row
-  // IFF the task is open and deletes it the moment it is answered — so a run shows the blocked glyph
-  // IFF an open `feature-blocked` task exists, and ⚠ IFF an open `feature-escalation` task exists.
-  // Once answered, the row is gone and the badge clears regardless of the stale `status`.
-  const attention = truthy(run.hasOpenBlockedTask) ? "blocked" : truthy(run.hasOpenEscalationTask) ? "⚠" : null;
+/** Evaluate one derived column from the ONE `featureReadModel` declaration for a base row (plus any
+ * projection rows the derivation correlates against). This is the single seam where the framework's
+ * compiled-function boundary is crossed: `fnFor(column)` returns `unknown` (a derivation can compile to
+ * any DSL value), while the caller statically knows the declared `lit(...)` shape of each column. */
+function evalDerived<T>(column: FeatureReadModelDerivedColumn, baseRow: Record<string, unknown>, projections?: Record<string, Array<Record<string, unknown>>>): T {
+  // biome-ignore lint/plugin: runtime/framework contract boundary — `fnFor` returns `unknown`; each derived column yields one of its declared DSL `lit(...)` values, whose type the caller knows.
+  return featureReadModel.fnFor(column)(baseRow, projections) as T;
+}
 
-  return { stage, state, skipped: skippedKeys.join(" "), attention };
+/** Derive the canonical pipeline stage, its render state, its not-in-path set, and its attention badge
+ * for one feature run. Pure and read-only — TOTAL over all 11 statuses (never returns undefined). The
+ * four columns are evaluated from the ONE `featureReadModel` declaration (app/featureReadModel.ts), so
+ * this façade and the SQLite VIEW compute byte-identical values by construction. */
+export function deriveStage(run: StageInput): DerivedStage {
+  const baseRow = {
+    feature_key: SELF_KEY,
+    status: run.status,
+    pr_key: run.pr_key ?? null,
+    converge: run.converge ?? null,
+    auto_merge: run.auto_merge ?? null,
+  };
+  const projections = { [USER_TASKS_PROJECTION]: openTaskRows(run) };
+  return {
+    stage: evalDerived<StageKey>("stage", baseRow, projections),
+    state: evalDerived<StageState>("stage_state", baseRow, projections),
+    skipped: evalDerived<string>("stage_skipped", baseRow, projections),
+    attention: evalDerived<string | null>("attention", baseRow, projections),
+  };
 }
 
-/** The Active/History partition label (§5), maintained at write time so the flat-DSL page tabs filter
- * on a stored `list_bucket` column with only `in` clauses. `history` iff the row is in a truly-terminal
- * status AND acknowledged; otherwise `active` (live runs + terminal-but-UNACKNOWLEDGED runs). */
+/** The Active/History partition label (§5): `history` iff the row is in a truly-terminal status AND
+ * acknowledged; otherwise `active` (live runs + terminal-but-UNACKNOWLEDGED runs). DERIVED on read from
+ * the ONE `featureReadModel` `list_bucket` declaration — the same AST the VIEW compiles (migration 076),
+ * NOT a write-time projection: the page's tabs filter the VIEW's derived `list_bucket`, and the stored
+ * `feature_runs.list_bucket` base column is vestigial (retired as a write projection, issue #439). This
+ * adapter is the TS lowering of that derivation, used off the write path (redispatch gating, tests). */
 export function deriveListBucket(status: string, acknowledgedAt: string | null | undefined): "active" | "history" {
-  return STAGE_DONE_STATUSES.includes(status) && acknowledgedAt != null ? "history" : "active";
+  return evalDerived<"active" | "history">("list_bucket", { status, acknowledged_at: acknowledgedAt ?? null });
 }

package/db/migrations/075_delivery_graph_proposals.sql

@@ -0,0 +1,48 @@
+-- The `staged` delivery-graph proposal store (ADR 0005 Decision 7, issue #460). This realises
+-- `propose → preview → approve → dispatch` as intended: the agent-facing surface ends at
+-- propose → compile → STAGE, and a HUMAN dispatches the staged proposal from the cockpit. The old
+-- `approvalToken` was a REPLAYABLE content digest handed back to the same caller, so any holder of
+-- the API credential self-approved. Removing the dispatch affordance from the agent surface (there is
+-- no `start` endpoint) dissolves that hole: the compile door persists the compiled graph HERE as a
+-- `staged` proposal and returns only a preview + a navigational `reviewUrl` — nothing that can trigger
+-- a run. The cockpit lists these rows, renders the preview, and dispatches the one the operator picks.
+--
+--   • digest (PK) — the content address of the compiled graph (`sha256(compiled.bpmn)[:12]`), the
+--     SAME digest the runner uses for the content-addressed deploy id. It NAMES the proposal so the
+--     agent can hand the operator an unambiguous "dispatch <digest>" and the operator dispatches
+--     EXACTLY the digest they previewed. A re-compile of the same bytes is idempotent (same PK).
+--   • logical_key — the LOGICAL graph identity (the graph's `name`, else the digest) used to
+--     SUPERSEDE: staging a changed graph (new digest) for the same logical key retires the prior
+--     staged proposal, so the cockpit shows one live proposal per logical graph, not every recompile.
+--   • graph — the original `DeliveryGraph` JSON, retained so the cockpit dispatch action can run the
+--     runner for the previewed digest without the agent re-submitting anything.
+--   • preview — the rendered preview JSON (`{ diagram, sideEffects, humanNodes }`) the cockpit shows,
+--     stamped at stage time so the list renders without recompiling.
+--   • status — `staged` (awaiting operator review), `superseded` (replaced by a newer digest for its
+--     logical key), `dispatched` (the operator launched it), or `expired` (aged out of its TTL before
+--     dispatch). Only `staged` rows show in the cockpit; the poller sweeps aged-out `staged` rows to
+--     `expired` (the grid's datasource filter is equality-only, so expiry is realised by that status
+--     flip, not an `expires_at > now` clause).
+--   • expires_at — the TTL horizon. Staged proposals age out of the cockpit list so a stale entry an
+--     operator never dispatched does not linger; the poller flips an aged-out `staged` row to `expired`.
+CREATE TABLE IF NOT EXISTS delivery_graph_proposals (
+  digest TEXT PRIMARY KEY,
+  logical_key TEXT NOT NULL,
+  title TEXT,
+  graph TEXT NOT NULL,
+  preview TEXT NOT NULL,
+  node_count INTEGER NOT NULL DEFAULT 0,
+  human_node_count INTEGER NOT NULL DEFAULT 0,
+  side_effect_count INTEGER NOT NULL DEFAULT 0,
+  side_effecting INTEGER NOT NULL DEFAULT 0,
+  status TEXT NOT NULL DEFAULT 'staged',
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  expires_at TEXT NOT NULL
+);
+
+-- Supersede scans by logical_key; the cockpit list filters by status + expiry.
+CREATE INDEX IF NOT EXISTS ix_delivery_graph_proposals_logical
+  ON delivery_graph_proposals (logical_key);
+CREATE INDEX IF NOT EXISTS ix_delivery_graph_proposals_status
+  ON delivery_graph_proposals (status);

package/db/migrations/076_feature_read_model_declare_once.sql

@@ -0,0 +1,53 @@
+-- Feature-run read model: DECLARE ONCE, compile to BOTH backends (ADR-0065, nano-ide#452).
+--
+-- This migration SUPERSEDES the hand-wired `feature_read_model` VIEW of 073_feature_read_model.sql and
+-- 075_feature_read_model_attention_from_user_tasks.sql. Those authored each derived column TWICE — the
+-- SQL CASE/EXISTS here AND the TypeScript oracle (deriveStage/deriveListBucket, app/stage.ts) — kept in
+-- lockstep by a hand-written parity test (drift surface #2, ADR-0065). This VIEW is no longer
+-- hand-written: every DERIVED column body below is emitted VERBATIM from the ONE declaration in
+-- app/featureReadModel.ts (`featureReadModel.sqlSelectFor(col, { baseAlias: "fr" })`), which ALSO drives the
+-- runtime TS via `fnFor` — the two lowerings fall out of the same closed-DSL AST and cannot diverge.
+-- A drift guard (app/featureReadModel.test.ts) fails if this file stops matching the declaration, and
+-- `assertReadModelParity` proves the SQL and TS lowerings agree.
+--
+-- SEMANTICS ARE UNCHANGED from 075: `attention` still derives from ENGINE TRUTH — an OPEN native user
+-- task in the `user_tasks` inbox (a `feature-blocked` row => blocked glyph, a `feature-escalation` row
+-- => `⚠`), NOT the drift-prone `status` variable (issue #422); `stage`/`stage_state`/`stage_skipped`/
+-- `list_bucket` are the same pure functions of the row. Only the AUTHORING moves to the framework
+-- primitive; the projected values are identical.
+--
+-- Forward-only VIEW redefinition (DROP then CREATE). 073/075 are MERGED, IMMUTABLE migrations — never
+-- edited; this is a NEW migration superseding their VIEW body. `feature_runs` (028+) and `user_tasks`
+-- (034) already exist earlier in the chain, and 075 already created the supporting
+-- `idx_user_tasks_subject_element` index the correlated attention EXISTS lookups seek, so it is not
+-- re-created here. Base columns are plain identity pass-throughs (aliased so the static pages<->schema
+-- contract guard sees the VIEW columns); `feature_runs fr` stays the sole top-level FROM (the user_tasks
+-- lookups are nested EXISTS subqueries at paren depth >= 1). The runner wraps each file in its own
+-- transaction, so this file must NOT contain BEGIN/COMMIT.
+
+DROP VIEW IF EXISTS feature_read_model;
+
+CREATE VIEW feature_read_model AS
+SELECT
+  fr.feature_key AS feature_key,
+  fr.repo AS repo,
+  fr.issue_number AS issue_number,
+  fr.issue_url AS issue_url,
+  fr.title AS title,
+  fr.base_branch AS base_branch,
+  fr.status AS status,
+  fr.process_key AS process_key,
+  fr.pr_key AS pr_key,
+  fr.converge AS converge,
+  fr.auto_merge AS auto_merge,
+  fr.outcome AS outcome,
+  fr.delivery_label AS delivery_label,
+  fr.acknowledged_at AS acknowledged_at,
+  fr.created_at AS created_at,
+  fr.updated_at AS updated_at,
+  CASE WHEN COALESCE((COALESCE(("fr"."status" = 'merged'), 0) OR COALESCE(("fr"."status" = 'converged'), 0) OR COALESCE(("fr"."status" = 'blocked'), 0) OR COALESCE(("fr"."status" = 'failed'), 0) OR COALESCE(("fr"."status" = 'skipped'), 0) OR COALESCE(("fr"."status" = 'abandoned'), 0)), 0) THEN 'Done' WHEN COALESCE(("fr"."status" = 'converging'), 0) THEN 'Converging' WHEN COALESCE((COALESCE(("fr"."pr_key" <> ''), 0) OR COALESCE(("fr"."status" = 'opened'), 0)), 0) THEN 'PR open' WHEN COALESCE((COALESCE(("fr"."status" = 'running'), 0) OR COALESCE(("fr"."status" = 'escalated'), 0) OR COALESCE(("fr"."status" = 'awaiting_operator'), 0)), 0) THEN 'Implementing' ELSE 'Requested' END AS stage,
+  CASE WHEN COALESCE((COALESCE(("fr"."status" = 'merged'), 0) OR COALESCE(("fr"."status" = 'converged'), 0)), 0) THEN 'ok' WHEN COALESCE(("fr"."status" = 'blocked'), 0) THEN 'blocked' WHEN COALESCE((COALESCE(("fr"."status" = 'failed'), 0) OR COALESCE(("fr"."status" = 'skipped'), 0) OR COALESCE(("fr"."status" = 'abandoned'), 0)), 0) THEN 'failed' ELSE NULL END AS stage_state,
+  CASE WHEN (NOT COALESCE("fr"."converge", 0)) THEN 'Converging Merging' WHEN (NOT COALESCE("fr"."auto_merge", 0)) THEN 'Merging' ELSE '' END AS stage_skipped,
+  CASE WHEN EXISTS (SELECT 1 FROM "user_tasks" AS "__urban_proj_0" WHERE COALESCE((COALESCE(("__urban_proj_0"."subject_type" = 'feature'), 0) AND COALESCE(("__urban_proj_0"."subject_key" = "fr"."feature_key"), 0) AND COALESCE(("__urban_proj_0"."element_id" = 'feature-blocked'), 0)), 0)) THEN 'blocked' WHEN EXISTS (SELECT 1 FROM "user_tasks" AS "__urban_proj_0" WHERE COALESCE((COALESCE(("__urban_proj_0"."subject_type" = 'feature'), 0) AND COALESCE(("__urban_proj_0"."subject_key" = "fr"."feature_key"), 0) AND COALESCE(("__urban_proj_0"."element_id" = 'feature-escalation'), 0)), 0)) THEN '⚠' ELSE NULL END AS attention,
+  CASE WHEN COALESCE((COALESCE((COALESCE(("fr"."status" = 'merged'), 0) OR COALESCE(("fr"."status" = 'converged'), 0) OR COALESCE(("fr"."status" = 'blocked'), 0) OR COALESCE(("fr"."status" = 'failed'), 0) OR COALESCE(("fr"."status" = 'skipped'), 0) OR COALESCE(("fr"."status" = 'abandoned'), 0)), 0) AND COALESCE(("fr"."acknowledged_at" = "fr"."acknowledged_at"), 0)), 0) THEN 'history' ELSE 'active' END AS list_bucket
+FROM feature_runs fr;

package/docs/adr/0005-agent-authored-delivery-graphs.md

@@ -160,6 +160,11 @@ shared JSON contract means either can be swapped in later without touching the a
 
 ### 7. Submission is propose → preview → approve → dispatch, idempotent, over the self-describing endpoint
 
+> **Superseded — see the *Amendment (issue #460)* at the end of this section.** The `POST
+> /actions/start/delivery-graph` agent endpoint described in the following paragraph was **never
+> shipped and has been removed**; the agent surface ends at propose → compile → stage and dispatch is
+> operator-only. The paragraph below is retained as the original (Proposed) decision record.
+
 Graphs are submitted exactly as epics are today — via a **new (proposed)** `POST
 /actions/start/delivery-graph` endpoint (paths are relative to the agent guide's `__BASE__` prefix,
 matching the guide's style) with the JSON body, discovered via the agent guide (which already
@@ -174,6 +179,19 @@ at-least-once execution (mirroring the release workflow's `npx semantic-release`
 "skip already-published" discipline — `.github/workflows/release.yml`) so a
 resume cannot double-fire.
 
+> **Amendment (issue #460): dispatch is operator-only.** As implemented, the "approve → dispatch"
+> half of this decision is **not** an agent endpoint. The agent surface ends at **propose → compile →
+> stage**: the `POST /actions/compile-delivery-graph` door validates + previews the graph and, on
+> success, **stages** it as a proposal (a durable `delivery_graph_proposals` row, content-addressed by
+> `digest`, superseded per logical graph + TTL-bounded), returning only a preview + a navigational
+> `reviewUrl` — no run key, token, or PIK. A **human dispatches** the staged proposal from the cockpit's
+> Delivery Graphs page (`POST /actions/delivery-graph/dispatch` by `digest`, an operator route). The
+> originally-proposed agent `POST /actions/start/delivery-graph` door — where the same caller was handed
+> a content-addressed `approvalToken` to re-submit with — was **removed**: that "approval" was a
+> **replayable** digest returned to the approver, so any holder of the API credential self-approved.
+> Dispatch-by-absence (there is no agent start door) closes that hole categorically; the idempotent
+> at-most-once launch fence is retained on the operator dispatch path.
+
 ## Consequences
 
 - nwf gains a **generic delivery-graph runner** that composes its existing primitives; the motivating

package/docs/adr/0006-delivery-units-one-representation.md

@@ -0,0 +1,221 @@
+# ADR 0006 — Delivery units: one representation for feature / epic / delivery-graph
+
+Status: **Proposed.**
+Date: 2026-08-22.
+
+> **Scope note.** This is a **nano-workforce-local** ADR — it governs how *this app* represents a
+> unit of delivery work internally. Platform-wide ADRs live in `Magikcraft/nano-bpm/docs/adr`
+> (referenced by number + repo). nano-workforce's own series continues here after ADR 0005.
+
+Relates to:
+nano-workforce **ADR 0005** (agent-authored delivery graphs — this ADR carries out 0005's
+already-stated framing that the delivery graph is the *general* form, of which an epic is a waved DAG
+and a feature a degenerate 1-node graph, by converging the data and process encodings onto it),
+nano-workforce **ADR 0001** (cross-repo epics + the generic `ReadinessProbe` wait-gate — the epic
+substrate being consolidated),
+nano-workforce **ADR 0002** (escalations are user tasks + forms — the human-escalation cell that is
+one of the copy-pasted subprocesses),
+nano-bpm **ADR 0065** (reconciling read models / `defineReadModel` — the derivation mechanism S1 uses
+to collapse three bespoke status unions into one),
+nano-ide **#424** (datasource can read a SQL VIEW — the *data-level* unlock),
+nano-workforce **#416** (the PR bumping the testkit to engine-wasm 0.7.2, which executes `callActivity`
+— the *process-level* unlock),
+nano-workforce **#464** (the tracking issue with slices S1–S5),
+nano-workforce **#305** (consolidate escalations on native `user_tasks` — a natural sub-step of S1/S3).
+
+## Context
+
+### One aggregate, encoded three times
+
+nano-workforce models the same real-world thing — **a scheduled unit of work driven to a delivery
+outcome** (typically an agent taking one slice to one merged PR, but a unit may instead `wait`, ask a
+`human`, call a `connector`, or — for a feature — terminate `opened`/`converged` without a merged PR;
+and an epic aggregates *many* such units/PRs) — in three separate representations, each with its own
+table, status union, operator read-surface, `instanceTracking` binding, and dispatch door:
+
+| Representation | Data | Process | Shape |
+|---|---|---|---|
+| **Feature** | `feature_runs` (mig. 028) | `resources/processes/feature.bpmn` | one issue → one PR (1-node) |
+| **Epic** | `plans` + `plan_tasks` (mig. 004) | `resources/processes/plan-fanout.bpmn` | fan-out of slices → waves (N-node) |
+| **Delivery graph** | `delivery_graph_runs` (mig. 058) + compiled nodes | compiled BPMN (`app/deliveryGraphCompiler.ts`) | arbitrary DAG |
+
+All three are keyed by an issue/run key and carry their own status union. Feature and epic each also
+project a dedicated display read-model VIEW; delivery-graph pages instead bind **directly** to
+`delivery_graph_runs` (`pages/delivery-graphs.page.json`, `pages/delivery-graph-detail.page.json`).
+Feature and epic execute through **hand-authored** BPMN (`feature.bpmn`, `plan-fanout.bpmn`) and
+dispatch hard-coded `senior:*` implementation jobs that funnel downstream to the *same* `pull_requests`
+table (keyed by `pr_key`) — the convergence/merge loop, which they correctly do **not** duplicate.
+Delivery graphs are the exception: only they are **compiled** to BPMN from JSON at runtime, they accept
+the submitted node kind and `agent.jobType` (including `wait`, `human`, and `connector` nodes), and
+`delivery_graph_runs` carries no `pr_key`, so a graph is not inherently PR-producing. So for the
+feature/epic implementation path the *downstream* half of the aggregate is already factored to a single
+source of truth; only the *upstream* "unit of work" half is triplicated.
+
+ADR 0005 already names this: "plan-fanout is an epic — a `RecordPlanTask[]` + `dependsOn[]` DAG with
+waves", "convergence-loop is one PR", and a feature is the degenerate one-node graph. The delivery
+graph is the general form. What 0005 did *not* do is converge the data and process encodings onto that
+general form — so we still carry three near-duplicate sources of truth for one aggregate. That is
+precisely the "no drift surfaces / derivation over duplication" hazard this project treats as a defect
+class: a change to the meaning of "a unit of work" has to be made, by hand, in three places that can
+silently drift.
+
+### The duplication was *forced* by two "can't-reference" constraints — both now lifted
+
+The triplication is not a design preference; it was compelled by two symmetric constraints, one on
+each encoding. Both have now been removed on `main`, which is why consolidation becomes possible now
+rather than earlier.
+
+**Data — "the datasource can't read a SQL VIEW."** Because the read layer could not read a VIEW, every
+*display projection* had to be a physically **denormalized table** — or denormalized columns
+hand-maintained on a source table (e.g. migrations 022/029 on `plans`) — rather than a VIEW derived
+from its source. That is what made a *shared* display projection impossible: each representation grew
+its own hand-maintained projection. (The delivery-unit source tables themselves —
+`feature_runs`/028, `plans`+`plan_tasks`/004, `delivery_graph_runs`/058 — are domain stores, not
+projection artifacts.) **Unlocked by nano-ide#424** (the datasource can now read a VIEW) → the derived
+read-model VIEWs added in migrations 059–062, 064, and 073 (later refined by 074/075), with 070–072
+dropping the now-redundant denormalized columns/tables. **Live today.**
+
+**Process — "the pinned WASM engine no-ops `callActivity`."** `app/deliveryGraphCompiler.ts:47-51`
+(and again at 604-607) records the constraint verbatim: `callActivity` is "a no-op on the pinned WASM
+engine (the child is never instantiated)", so the compiler — and every hand-written process —
+**inlines** the subprocess body instead of referencing it. The consequence is that the atomic
+*"agent-implement cell"* (`implement-task (senior:*) → "escalated?" gateway → record-escalation →
+user-task → SLA boundary → answer gateway`) exists as **two hand-authored copies** — `feature.bpmn` and
+the multi-instance `implement` subprocess in `plan-fanout.bpmn` — plus a **third generator** in the
+compiler that re-emits it once per graph node. Sibling cells
+(readiness-poll, human-escalation) duplicate the same way. **No `callActivity` exists in any diagram**
+because it did nothing. **Unlocked by #416** (engine-wasm 0.4.0 → **0.7.2**). engine-core executes
+`callActivity` by inline-expanding the called process at deploy (`engine-core/src/model.rs:1217/1255`).
+**Verified live:** a `callActivity` parent+child model deployed through engine-wasm 0.7.2 runs to
+`COMPLETED`. Caveat: #416 bumps only the **dev-only** `@nanobpm/urban-testkit`; the production
+`@nanobpm/urban` broker does not itself pin `engine-wasm`, so this verification proves the in-process
+testkit, not the broker/runtime that will execute future `callActivity` models. S4/S5 therefore also
+carry a **deployment-runtime prerequisite** — the deployed broker's `engine-core` must carry the same
+`callActivity` support — which green testkit CI does not by itself guarantee.
+
+### The two constraints are the *same* constraint
+
+Both are "an encoding can't *reference* a shared definition, so it *inlines a copy* of it." Data
+inlined projection tables; process inlined subprocess bodies. Both share the same aggregate (the
+delivery unit), the same fix shape (remove the can't-reference constraint, then reference instead of
+copy), and both already have their downstream half factored correctly (`pull_requests`; the
+convergence/merge loop). Removing one constraint without the other would leave the aggregate
+half-consolidated; removing both is what makes a single representation reachable.
+
+## Decision
+
+Adopt a single internal aggregate — the **delivery unit** — defined around its **nodes**: a node is one
+**scheduled unit of work** whose executor may be an **agent, probe, human, or connector** (ADR 0005
+`wait`/`human`/`connector` nodes are first-class, not exceptions). Its terminal is *typically* one merged
+PR, but PR-less nodes and delivery graphs (`delivery_graph_runs` has no `pr_key`) make PR production
+**optional**.
+It has **two encodings**, each of which now *references* the shared definition rather than inlining
+a copy — expressed here as the **target** state:
+
+### 1. Data encoding — one `delivery_unit` aggregate
+
+- A `delivery_units` table is the single source of truth for "a unit of work." Feature = a 1-node
+  unit; Epic = an N-node waved unit; DeliveryGraph = an arbitrary-DAG unit — a **shape**, not a
+  separate table.
+- `feature_runs` / `plans` + `plan_tasks` / `delivery_graph_runs` become **derived VIEWs / rows** over
+  `delivery_units` (using the nano-ide#424 VIEW capability), not independent tables. The epic case
+  covers **both** levels: the `plans` aggregate row (process key, status, title, lifecycle) becomes a
+  row/VIEW over `delivery_units`, and each `plan_tasks` slice becomes a node under it.
+- The three `instanceTracking` bindings and `senior:*` dispatch doors collapse toward one, keyed on
+  the delivery unit.
+- **Identity.** `delivery_units` carries a stable `unit_id` plus `(unit_id, node_id)` for the N-node
+  cases. The legacy keys are not interchangeable — a feature run and an active epic may share one
+  `<owner>/<repo>#<N>` key (`app/feature.ts`), while delivery graphs key on a caller idempotency key or
+  content digest (`app/deliveryGraphRun.ts` `computeRunKey`) — so S2's compatibility VIEWs map each
+  legacy key onto the new identity, ensuring unrelated runs are never merged onto one row.
+
+### 2. Process encoding — shared cells composed by `callActivity`
+
+- Extract the atomic *implement-cell* (and its sibling wait-gate and human-escalation cells) into
+  standalone processes (`resources/processes/implement-cell.bpmn`, …).
+- Compose them by reference — replacing only the inlined *implement/escalation segment*, not the
+  surrounding orchestration: in **feature** (`feature.bpmn`) the readiness preflight, base-branch setup,
+  `record-feature`, and convergence handoff are retained; only the implement-cell segment becomes one
+  `callActivity`. **Epic** = the multi-instance `implement` body is a `callActivity`; **delivery graph**
+  = the compiler *emits* `callActivity` references, not inlined subprocess copies.
+- This is gated on the engine-wasm 0.7.2 unlock, which is now live on `main`.
+
+### 3. Status lifecycle — one derived union
+
+The three bespoke status unions collapse into **one derived union** via ADR 0065's `defineReadModel`,
+so a change to lifecycle semantics is made once and derived everywhere, not re-declared per
+representation. These unions are **not** identical today — features use
+`running`/`escalated`/`awaiting_operator`/…, plans use `planning`/`dispatched`/`done`, and graphs use
+`running`/`done` with a reserved `awaiting-approval` (`app/feature.ts`, `app/plan.ts`,
+`app/deliveryGraphRun.ts`); §1 additionally makes each `plan_tasks` row a **node**, which carries its own
+`PlanTaskStatus` (`pending`/`waiting-for-lane`/…, `app/plan.ts`). So S1 owns defining the canonical
+**aggregate** state set *and* explicitly deciding whether **node** status is part of that union or a
+separate node contract — plus the per-shape mapping and precedence and the write/`instanceTracking`
+behavior — not merely projecting an existing value.
+
+### 4. Preserve — the static-vs-adaptive execution axis (do NOT bundle it)
+
+This ADR consolidates the *representation*, not the *execution strategy*. ADR 0005's deliberate
+distinction stays intact: **plan-fanout remains adaptive** (agent-discovered slices, waves that adapt),
+**delivery graphs remain static/compiled**. Both are still *delivery units*; they differ only in how
+their topology is produced. Unifying that axis is explicitly out of scope here.
+
+## Consequences
+
+- **Single source of truth for a unit of work.** A change to the meaning of "a delivery unit" — a new
+  status, a lifecycle rule, a step in the implement cell — is made once and derived into every
+  representation, eliminating the three-way drift surface this project treats as a defect class.
+- **Renderability + executability both improve.** One implement-cell process is one thing to keep
+  deploy-valid and lay out, instead of **two hand-authored copies plus a compiler generator** that can
+  silently diverge (a graph can render and still fail deploy — the copies are exactly where that
+  divergence hides).
+- **Migration is incremental and forward-only.** The VIEWs preserve every current read shape while the
+  physical model consolidates underneath, and each slice below is independently shippable. Consistent
+  with this repo's forward-only, expand-and-contract migration contract (see
+  `070_drop_plan_projection_columns.sql`, which treats dropping projection columns as a later contract
+  phase), a slice is **not** reverted by reverting the app: rolling back a writer-repointing or
+  table-to-VIEW slice requires a **separately designed recovery/compatibility migration**, not a plain
+  revert.
+- **Cost.** A backfill/migration for `delivery_units`; a one-time extraction of the shared cells; and
+  the process slices are sequenced behind the (now-live) engine-wasm unlock. No behaviour change is
+  intended — this is a representation consolidation, guarded by parity tests against the existing VIEWs
+  and by the deploy+run engine tests.
+
+## Rollout (see #464 for the live checklist)
+
+Each slice is independently shippable; the process slices (S4/S5) are sequenced behind the engine-wasm
+0.7.2 unlock. The **dev-testkit** side of that unlock has landed (#416, verified in-process above); S4/S5
+additionally gate on the **deployed broker/runtime** carrying verified `callActivity` support (the
+deployment-runtime prerequisite noted above), not on #416 alone.
+
+- **S0 · ADR** — this record.
+- **S1 · status lifecycle** — one derived status union via ADR 0065 `defineReadModel`, replacing the
+  three bespoke unions. This **depends on and overlaps** #305 (consolidate escalations on native
+  `user_tasks`) but does not subsume it: #305 additionally retires the `feature_runs` escalation
+  columns and the bespoke completion doors and updates the escalation UI/forms, which remain #305's
+  scope (an adjacent sub-step of S1/S3 per #464).
+- **S2 · `delivery_units` table** — the aggregate. Because current code still **writes**
+  `feature_runs` / `plans` / `plan_tasks` / `delivery_graph_runs` directly (`app/feature.ts`,
+  `app/plan.ts`, `app/deliveryGraphRun.ts`) — **and** the framework's `instanceTracking` bindings in
+  `nano.app.json` write termination status to `feature_runs`, `plans`, and `delivery_graph_runs` — and a
+  SQLite VIEW is read-only, follow expand/contract **order**: (a) add `delivery_units` and dual-write it
+  alongside the legacy tables; (b) backfill existing/legacy rows; (c) repoint reads to VIEWs/rows derived
+  from `delivery_units`, guarded by read-model parity tests. The legacy tables stay **physical
+  (writable) through S2** — they must **not** become read-only VIEWs while any writer, including the
+  `instanceTracking` termination-reconciliation bindings, still targets them, or reconciliation fails
+  with no writable target left for S3 to move. (d) Only after **S3** has moved those `instanceTracking`
+  bindings and every other writer off the legacy tables does the table-to-VIEW contract phase retire the
+  legacy write paths.
+- **S3 · collapse doors** — unify the three `instanceTracking` bindings + `senior:*` dispatch doors.
+- **S4 · shared cells** — extract the atomic `implement-cell.bpmn` **and its sibling wait-gate and
+  human-escalation cells** (Decision §2) into standalone processes; `feature.bpmn` + the `plan-fanout`
+  MI body compose them via `callActivity`.
+- **S5 · compiler emits calls** — `deliveryGraphCompiler` references shared cells instead of inlining
+  per-node copies.
+
+## Non-goals / deferred
+
+- **Unifying the static-vs-adaptive execution axis** (see Decision §4) — preserved deliberately.
+- **Changing the downstream PR/convergence loop** — already single-sourced (`pull_requests`); untouched.
+- **Cross-repo/platform representation** — this ADR is nano-workforce-local; any platform-wide delivery
+  aggregate would be a separate nano-bpm ADR.