@nanobpm/nano-workforce 0.120.2 → 0.122.0

package/app/planGateway.test.ts

@@ -1,8 +1,14 @@
 // Tests for the `plans` gateway's write-time epic-bucket projection (issue #298) and its one-shot
 // backfill. The gateway wraps the plain table so EVERY writer — startPlan, the record workers, the
-// delivery poller, the acknowledge-epic op — automatically gets a fresh `list_bucket`/`ack_open`
-// projection without passing them: the single write path is the only place `deriveEpicBucket` /
-// `epicIsAcknowledgeable` are applied. Mirrors app/featureGateway.test.ts.
+// acknowledge-epic op — automatically gets a fresh `list_bucket`/`ack_open` projection without
+// passing them: the single write path is the only place `deriveEpicBucket` / `epicIsAcknowledgeable`
+// are applied. Mirrors app/featureGateway.test.ts.
+//
+// Since epic #412 retired the stored `plans.delivery` column, the gateway projects with `delivery`
+// treated as UNKNOWN (null): `list_bucket` is provably identical to the delivery-aware value for
+// every reachable state, and `ack_open` becomes a *candidate* (any unacknowledged `done` epic) that
+// the `pollPlanBucket` read-model pass (implemented in app/service.ts, tested in app/delivery.test.ts)
+// corrects with the read-time signal.
 import { test } from "node:test";
 import { assert, assertEquals } from "#test-assert";
 import type { DataLayer } from "@nanobpm/urban";
@@ -46,21 +52,20 @@ test("insert projects list_bucket/ack_open from status without the caller passin
   assertEquals(rows[0].ack_open, 0);
 });
 
-test("status flip to done+converging keeps the epic Active (no vanish)", async () => {
+test("status flip to done keeps the epic Active and marks a Dismiss candidate (delivery-free gateway)", async () => {
   const { data, rows } = memData();
-  rows.push({ plan_key: "o/r#2", status: "dispatched", delivery: null });
-  // record-results marks the epic done; the delivery poller then sets converging.
+  rows.push({ plan_key: "o/r#2", status: "dispatched" });
+  // record-results marks the epic done. The delivery-free gateway keeps it Active and — not seeing
+  // the read-time delivery signal — marks it a Dismiss candidate (ack_open=1); `pollPlanBucket`
+  // clears ack_open while the epic is still converging.
   await plans(data).update("o/r#2", { status: "done" });
   assertEquals(rows[0].list_bucket, "active");
-  await plans(data).update("o/r#2", { delivery: "converging", delivery_label: "1/2 slices merged, 1 converging" });
-  assertEquals(rows[0].list_bucket, "active");
-  assertEquals(rows[0].ack_open, 0);
+  assertEquals(rows[0].ack_open, 1);
 });
 
-test("delivery landing opens the Dismiss affordance (ack_open=1) but keeps it Active until acknowledged", async () => {
+test("acknowledging a done epic flips it to History and closes the Dismiss affordance", async () => {
   const { data, rows } = memData();
-  rows.push({ plan_key: "o/r#3", status: "done", delivery: "converging" });
-  await plans(data).update("o/r#3", { delivery: "landed", delivery_label: "2/2 slices merged" });
+  await plans(data).insert({ plan_key: "o/r#3", status: "done" });
   assertEquals(rows[0].list_bucket, "active");
   assertEquals(rows[0].ack_open, 1);
   // Operator dismisses → gateway reprojects to History, ack_open closes.
@@ -69,30 +74,31 @@ test("delivery landing opens the Dismiss affordance (ack_open=1) but keeps it Ac
   assertEquals(rows[0].ack_open, 0);
 });
 
-test("a projection-irrelevant patch (wave_label only) does not disturb the stored bucket", async () => {
+test("a projection-irrelevant patch (epic_phase only) does not disturb the stored bucket", async () => {
   const { data, rows } = memData();
-  rows.push({ plan_key: "o/r#4", status: "done", delivery: "landed", list_bucket: "active", ack_open: 1 });
-  await plans(data).update("o/r#4", { wave_label: "2/2" });
+  rows.push({ plan_key: "o/r#4", status: "done", list_bucket: "active", ack_open: 1 });
+  await plans(data).update("o/r#4", { epic_phase: "Finalizing" });
   assertEquals(rows[0].list_bucket, "active");
   assertEquals(rows[0].ack_open, 1);
 });
 
 test("a direct write to list_bucket is overridden by the canonical derivation (no bypass)", async () => {
   const { data, rows } = memData();
-  rows.push({ plan_key: "o/r#5", status: "done", delivery: "converging" });
-  // A caller tries to force History; the gateway re-derives from status+delivery and overrides it.
+  rows.push({ plan_key: "o/r#5", status: "done" });
+  // A caller tries to force History; the gateway re-derives from status (delivery-free) and overrides it.
   await plans(data).update("o/r#5", { list_bucket: "history" });
   assertEquals(rows[0].list_bucket, "active");
 });
 
 test("backfillPlanBuckets stamps only legacy (NULL list_bucket) rows, idempotently", async () => {
   const { data, rows } = memData();
-  rows.push({ plan_key: "o/r#legacy", status: "done", delivery: "converging", list_bucket: null, ack_open: null });
+  rows.push({ plan_key: "o/r#legacy", status: "done", list_bucket: null, ack_open: null });
   rows.push({ plan_key: "o/r#fresh", status: "planning", list_bucket: "active", ack_open: 0 });
   const stamped = await backfillPlanBuckets(data);
   assertEquals(stamped, 1);
   assertEquals(rows[0].list_bucket, "active");
-  assertEquals(rows[0].ack_open, 0);
+  // Delivery-free gateway marks the done epic a Dismiss candidate; pollPlanBucket corrects it later.
+  assertEquals(rows[0].ack_open, 1);
   // Second pass is a no-op: every row is now projected.
   assertEquals(await backfillPlanBuckets(data), 0);
 });

package/app/service.ts

@@ -27,7 +27,7 @@ import {
   conformanceEscalationQuestion,
 } from "./conformance.ts";
 import { isUniqueConstraintFence } from "./dbFence.ts";
-import { deriveDelivery, TERMINAL_STATUSES } from "./delivery.ts";
+import { deriveDelivery, deriveEpicBucket, epicIsAcknowledgeable, TERMINAL_STATUSES } from "./delivery.ts";
 import { deliveryGraphRuns, deriveDeliveryPhase, parseHumanLabels } from "./deliveryGraphRun.ts";
 import { isDeliveryHumanElement } from "./deliveryHuman.ts";
 import { fleetSupportsDurableResume } from "./durableResume.ts";
@@ -52,19 +52,19 @@ import {
 import { pollLineage } from "./lineage.ts";
 import { mergeLanes, readExclusions } from "./mergeExclusion.ts";
 import { freshHeadRunAction, headRunPresenceCount, loadMergeProtocol } from "./mergeProtocol.ts";
-import { pollMergesPerDay } from "./mergesPerDay.ts";
 import { type PrLaneDecision, planPrLane, taskDependencyDepths } from "./mergeTrain.ts";
 import {
   backfillPlanBuckets,
   capabilityGates,
   inboundPlanDeps,
+  type Plan,
   planReviews,
   plans,
   planTaskDeps,
   planTaskNeeds,
   planTasks,
 } from "./plan.ts";
-import { derivePromotionState, isPromotable, promotionPrBody, promotionPrTitle } from "./promotion.ts";
+import { derivePromotionState, isEpicIntegrationBranch, isPromotable, promotionPrBody, promotionPrTitle } from "./promotion.ts";
 import {
   defaultProbeExec,
   type ProbeExec,
@@ -1862,54 +1862,75 @@ export async function pollCapabilityGatesImpl(
   }
 }
 
-/** Idempotent read-model pass: recompute each plan's derived `delivery` signal (issue #171) by
- * joining its slice tasks' `pr_key` → `pull_requests.status`, and denormalise it onto the `plans`
- * row so the epics overview / detail views can read it as a flat column (Urban's datasource can't
- * read a SQL VIEW). Never touches `plan.status` — additive/derived only. Writes only when the
- * projection actually changes, so a steady-state pass is a no-op. */
 /** Sentinel status fed to `deriveDelivery` for a `plan_tasks.pr_key` whose `pull_requests` row is
  * missing (DB desync). It is deliberately non-terminal and not `merged`, so a dangling PR counts as
  * in-flight — never a false-positive `landed` from a silently-dropped slice. */
 const MISSING_PR_STATUS = "missing";
 
-export async function pollDelivery(data: DataLayer) {
-  // Preload every PR status once per pass into a pr_key→status map (avoids the prior N+1
-  // `prs(data).get` per task; mirrors how `activePrs` reads `prs(data).all()` once).
+/** Recompute an epic's derived `delivery` signal at READ TIME (epic #412) from the SAME pure
+ * `deriveDelivery` the `plan_delivery` VIEW encodes — by joining each slice `plan_tasks.pr_key` →
+ * `pull_requests.status` (a dangling `pr_key` counts as in-flight, never false-`landed`). The
+ * `plans.delivery` column was RETIRED, so the pollers that still need the signal derive it here
+ * rather than reading a denormalised column. Non-`done` plans short-circuit to `null` (the view's
+ * behaviour) without the per-plan task join. `statusByPrKey` is an optional once-per-pass PR-status
+ * map (the pollers preload it to avoid an N+1); when omitted (a one-off caller like the
+ * acknowledge-epic op) it loads only THIS plan's slice PRs on demand — never the whole table. */
+export async function derivePlanDelivery(
+  data: DataLayer,
+  plan: Plan,
+  statusByPrKey?: Map<string, string>,
+): Promise<string | null> {
+  if (plan.status !== "done") return null;
+  const tasks = await planTasks(data).find({ plan_key: plan.plan_key });
+  const prStatuses: string[] = [];
+  for (const t of tasks) {
+    if (!t.pr_key) continue;
+    let status = statusByPrKey?.get(t.pr_key);
+    if (status === undefined && !statusByPrKey) {
+      // On-demand caller: fetch just this slice's PR row rather than loading the whole table.
+      status = (await prs(data).get(t.pr_key))?.status;
+    }
+    prStatuses.push(status ?? MISSING_PR_STATUS);
+  }
+  return deriveDelivery(plan.status, prStatuses).delivery;
+}
+
+/** Idempotent read-model pass (epic #412 — successor to the retired `pollDelivery`): keep each
+ * epic's Active/History `list_bucket` + `ack_open` tick-off flags fresh now that the `plans.delivery`
+ * column is gone. The `plans` gateway projects both at write time, but with `delivery` treated as
+ * UNKNOWN (null) — provably correct for `list_bucket`, but it cannot clear `ack_open` while a `done`
+ * epic is still CONVERGING (its slices not all merged). This pass supplies the delivery-aware
+ * correction: it recomputes `delivery` at read time via {@link derivePlanDelivery} and re-derives
+ * `list_bucket`/`ack_open` from the pure `deriveEpicBucket`/`epicIsAcknowledgeable` helpers, writing
+ * the result via the RAW `plans` table so the gateway's delivery-free reprojection can't clobber the
+ * corrected value. Writes only when the projection actually changes, so a steady-state pass is a
+ * no-op. Never touches `plan.status` — additive/derived only. */
+export async function pollPlanBucket(data: DataLayer) {
+  // Preload every PR status once per pass into a pr_key→status map (avoids an N+1 `prs(data).get`).
   const statusByPrKey = new Map<string, string>();
   for (const pr of await prs(data).all()) statusByPrKey.set(pr.pr_key, pr.status);
+  // Write through the RAW table, NOT the `plans` gateway: the gateway reprojects `list_bucket`/
+  // `ack_open` with `delivery=null` (it can't see the read-time signal), which would undo the
+  // delivery-aware `ack_open` correction below. This pass is the authoritative writer of the
+  // delivery-aware bucket flags.
+  const plansTable = data.table<Plan>("plans", "plan_key");
   for (const plan of await plans(data).all()) {
     try {
-      // `deriveDelivery` always yields `{null, null}` for a non-`done` plan, so skip the per-plan
-      // task join for those — but still clear any stale projection defensively (e.g. a plan that
-      // regressed out of `done`) so the read model never keeps a phantom `converging`/`landed`.
-      if (plan.status !== "done") {
-        if (plan.delivery !== null || plan.delivery_label !== null) {
-          await plans(data).update(plan.plan_key, {
-            delivery: null,
-            delivery_label: null,
-            updated_at: now(),
-          });
-        }
-        continue;
-      }
-      const tasks = await planTasks(data).find({ plan_key: plan.plan_key });
-      const prStatuses: string[] = [];
-      for (const t of tasks) {
-        if (!t.pr_key) continue;
-        // A dangling pr_key (row missing) is treated as in-flight, not dropped, so a DB desync
-        // can never wrongly promote an epic to `landed`.
-        prStatuses.push(statusByPrKey.get(t.pr_key) ?? MISSING_PR_STATUS);
-      }
-      const { delivery, label } = deriveDelivery(plan.status, prStatuses);
-      if (plan.delivery !== delivery || plan.delivery_label !== label) {
-        await plans(data).update(plan.plan_key, {
-          delivery,
-          delivery_label: label,
+      const delivery = await derivePlanDelivery(data, plan, statusByPrKey);
+      const listBucket = deriveEpicBucket(plan.status, delivery, plan.acknowledged_at ?? null);
+      const ackOpen =
+        epicIsAcknowledgeable(plan.status, delivery) && (plan.acknowledged_at ?? null) === null
+          ? 1
+          : 0;
+      if (plan.list_bucket !== listBucket || plan.ack_open !== ackOpen) {
+        await plansTable.update(plan.plan_key, {
+          list_bucket: listBucket,
+          ack_open: ackOpen,
           updated_at: now(),
         });
       }
     } catch (err) {
-      console.error(`[poller] delivery ${plan.plan_key}: ${err}`);
+      console.error(`[poller] plan-bucket ${plan.plan_key}: ${err}`);
     }
   }
 }
@@ -1926,12 +1947,30 @@ export async function pollDelivery(data: DataLayer) {
  * a prior edge (e.g. an edge later removed) is cleared defensively so the read model never keeps a
  * phantom gate. */
 export async function pollWaitGate(data: DataLayer) {
+  // Preload every plan_tasks row once per pass and group by plan_key, so deriving each plan's
+  // fanned-out signal below is a map lookup rather than a per-plan `planTasks(data).find` (avoids
+  // an N+1 that would double this pass's DB work alongside the per-plan `inboundPlanDeps` lookup).
+  const wavesByPlanKey = new Map<string, number[]>();
+  for (const t of await planTasks(data).all()) {
+    if (t.wave == null) continue;
+    const list = wavesByPlanKey.get(t.plan_key) ?? [];
+    list.push(t.wave);
+    wavesByPlanKey.set(t.plan_key, list);
+  }
   for (const plan of await plans(data).all()) {
     try {
       const edges = await inboundPlanDeps(data, plan.plan_key);
+      // `plans.current_wave` was retired (epic #412); `deriveWaitGate` only consumes its
+      // NULL-ness (proof the epic's fan-out began). Derive that at read time: an epic has fanned out
+      // iff it has ≥1 levelized `plan_tasks` row (a wave assigned). The value's magnitude is never
+      // surfaced here — the epic index/detail read the display `current_wave` off the
+      // `plan_wave_label`/`plan_read_model` VIEWs — so any non-null (the frontier's min wave) is
+      // faithful for the gate's "has this epic ever fanned out?" test.
+      const assignedWaves = wavesByPlanKey.get(plan.plan_key) ?? [];
+      const current_wave = assignedWaves.length > 0 ? Math.min(...assignedWaves) : null;
       const { wait_gate, wait_gate_label } = deriveWaitGate(edges, {
         status: plan.status,
-        current_wave: plan.current_wave,
+        current_wave,
         bound_artifacts: plan.bound_artifacts,
         created_at: plan.created_at,
       });
@@ -1951,8 +1990,8 @@ export async function pollWaitGate(data: DataLayer) {
 /** Idempotent promotion pass (issue #299): open — and then track — the `epic/* → <default>`
  * promotion PR for every epic that has LANDED on a custom integration branch. This is the missing
  * counterpart to `ensureBaseBranch`: that creates the `epic/*` branch slices merge into; this
- * delivers the fully-landed branch to the default branch. Runs AFTER `pollDelivery` so it reads the
- * freshly-projected `delivery = landed` signal.
+ * delivers the fully-landed branch to the default branch. Derives each epic's `delivery` signal at
+ * read time (epic #412 — the `plans.delivery` column was retired) via the same pure `deriveDelivery`.
  *
  * Per promotable plan (`isPromotable`: `delivery = landed` AND base is `epic/*`):
  *   • No promotion PR yet → open ONE `epic/* → <default>` PR (idempotent against a remote head-branch
@@ -1972,10 +2011,15 @@ export async function pollPromotion(data: DataLayer, engine: EngineClient, token
   const statusByPrKey = new Map<string, string>();
   for (const pr of await prs(data).all()) statusByPrKey.set(pr.pr_key, pr.status);
   for (const plan of await plans(data).all()) {
-    if (!isPromotable(plan)) continue;
     const base = plan.base_branch;
-    if (!base) continue; // narrowed by isPromotable, but keep the type-checker honest
+    // A non-`epic/*` base is never promotable — short-circuit before the per-plan delivery join.
+    if (!isEpicIntegrationBranch(base)) continue;
     try {
+      // `plans.delivery` was retired (epic #412) — derive the landed signal at READ TIME from the
+      // slice PRs (same pure `deriveDelivery` the `plan_delivery` VIEW encodes) instead of reading a
+      // denormalised column, then apply the pure `isPromotable` predicate.
+      const delivery = await derivePlanDelivery(data, plan, statusByPrKey);
+      if (!isPromotable({ delivery, base_branch: base })) continue;
       // Already opened → project state from the promotion PR's live status, and re-enroll it if its
       // convergence row went missing (a prior submit failed, or the app/engine store desynced).
       if (plan.promotion_pr) {
@@ -2433,12 +2477,11 @@ export async function pollOnce(
   }
   await pollReviews(data, engine, token);
   await pollMerges(data, engine, token);
-  await pollDelivery(data);
+  await pollPlanBucket(data);
   await pollWaitGate(data);
   await pollPromotion(data, engine, token);
   await pollFeatureDelivery(data);
   await pollLineage(data);
-  await pollMergesPerDay(data);
   await pollUserTasks(data, engine, engineRest);
   await pollDeliveryGraphPhase(data, engine);
   if (engineRest) {

package/db/migrations/070_drop_plan_projection_columns.sql

@@ -0,0 +1,31 @@
+-- Contract phase for the worker-maintained `plans` projection columns (epic #412: retire
+-- worker-maintained denormalised projections in favour of SQL VIEWs).
+--
+-- Wave-0 of this epic re-expressed every one of these denormalised `plans` columns as a DERIVED SQL
+-- VIEW computed from the SAME pure helpers that used to feed the write-path, and repointed every
+-- operator page onto those views:
+--   • `wave_count` / `current_wave` / `wave_label` (022_plan_wave_progress.sql) → `plan_wave_progress`
+--     / `plan_wave_label` / `plan_read_model` (060/061), derived from the levelized `plan_tasks`.
+--   • `delivery` / `delivery_label` (029_plan_delivery.sql) → `plan_delivery` / `plan_read_model`
+--     (061), derived via the pure `deriveDelivery`/`TERMINAL_STATUSES` (app/delivery.ts) by joining
+--     each slice `plan_tasks.pr_key` → `pull_requests.status`.
+--
+-- This wave-1 cleanup deletes the now-dead write-paths (the `record-plan`/`record-wave`/`select-wave`
+-- worker writes and the `pollDelivery` poller) and repoints the last internal readers onto read-time
+-- derivation (`pollPlanBucket`/`pollPromotion` recompute `delivery` via `deriveDelivery`;
+-- `pollWaitGate` derives "has the epic fanned out?" from `plan_tasks`). With no remaining writer or
+-- reader, these five columns are dead schema — a drift surface with no source of truth behind them —
+-- so drop them. The `plan_read_model` / `plan_wave_label` / `plan_delivery` VIEWs DERIVE their
+-- wave/delivery columns from the join surfaces, never from these `plans` columns, so the pages the
+-- views back are unaffected.
+--
+-- Forward-only contract migration numbered in this task's disjoint 070-079 block (029/022 are
+-- forward-only and immutable, so this is the standard expand→contract follow-up, not an edit to
+-- them). All five columns were nullable with no default and have no remaining writer or reader, and
+-- no index references them, so a plain `ALTER TABLE … DROP COLUMN` suffices. The runner wraps each
+-- file in its own transaction, so this file must NOT contain BEGIN/COMMIT.
+ALTER TABLE plans DROP COLUMN wave_count;
+ALTER TABLE plans DROP COLUMN current_wave;
+ALTER TABLE plans DROP COLUMN wave_label;
+ALTER TABLE plans DROP COLUMN delivery;
+ALTER TABLE plans DROP COLUMN delivery_label;

package/db/migrations/071_drop_merges_per_day_table.sql

@@ -0,0 +1,21 @@
+-- Contract phase for the worker-maintained `merges_per_day` read table (epic #412: retire
+-- worker-maintained denormalised projections in favour of SQL VIEWs).
+--
+-- 051_merges_per_day.sql created the flat `merges_per_day` read table the Velocity page bound, kept
+-- fresh each poll pass by `pollMergesPerDay` (app/mergesPerDay.ts) projecting the pure
+-- `deriveMergesPerDay` over the `merges` audit trail. Wave-0 re-expressed that aggregate as the
+-- DERIVED `merges_per_day_view` VIEW (062) — computed directly from `merges` with the same
+-- `COUNT(DISTINCT pr_key)` / local-day bucketing — and repointed `pages/velocity.page.json` onto it.
+--
+-- This wave-1 cleanup deletes the `pollMergesPerDay` write-path and its base-table accessors. With no
+-- remaining writer or reader, the `merges_per_day` table is dead schema, so drop it. The pure
+-- `deriveMergesPerDay`/`barFor` helpers (app/mergesPerDay.ts) stay — they are the single source of
+-- truth the view's SQL mirrors and are still exercised by the view's read-model guard. The
+-- `merges_per_day_view` reads the `merges` audit table, NOT this dropped table, so the Velocity page
+-- is unaffected.
+--
+-- Forward-only contract migration numbered in this task's disjoint 070-079 block. The table has no
+-- remaining writer or reader and nothing references it by foreign key, so a plain `DROP TABLE`
+-- suffices. The runner wraps each file in its own transaction, so this file must NOT contain
+-- BEGIN/COMMIT.
+DROP TABLE merges_per_day;

package/db/migrations/072_drop_lineage_view_backed_columns.sql

@@ -0,0 +1,23 @@
+-- Contract phase for the view-migrated `lineage_threads` identity columns (epic #412: retire
+-- worker-maintained denormalised projections in favour of SQL VIEWs).
+--
+-- 064_lineage_thread_view.sql introduced the `lineage_thread_view` VIEW the Lineage page now binds.
+-- The lineage audit (lineage-views-audit) split `lineage_threads`' columns into two groups:
+--   • VIEW-BACKED (fully derivable from the `plans`/`feature_runs` origin joins): `kind` and
+--     `issue_url`. The view DERIVES both — `kind` from which origin table the root matches, `issue_url`
+--     from that origin's `issue_url` (NULL for a self-rooted PR) — and NEVER reads `lt.kind` /
+--     `lt.issue_url`. `pollLineage` (app/lineage.ts) no longer writes them (this wave-1 cleanup).
+--   • PROCEDURAL (kept, still poller-written, still read by the view): `title` (a self-rooted PR's
+--     representative-PR pick), `stage`, `stage_label`, `process_key`, `pr_keys`, `pr_count`, `active`,
+--     `created_at`, `updated_at`. These are NOT dropped — the view passes them through from
+--     `lineage_threads`, and `pollLineage` remains their single writer.
+--
+-- So drop ONLY the two fully view-backed columns; the procedural remainder stays. Both dropped
+-- columns were nullable with no default and now have no writer or reader, and no index references
+-- them, so a plain `ALTER TABLE … DROP COLUMN` suffices. Because a procedural remainder survives, the
+-- `lineage_threads` table itself is NOT dropped.
+--
+-- Forward-only contract migration numbered in this task's disjoint 070-079 block. The runner wraps
+-- each file in its own transaction, so this file must NOT contain BEGIN/COMMIT.
+ALTER TABLE lineage_threads DROP COLUMN kind;
+ALTER TABLE lineage_threads DROP COLUMN issue_url;

package/openapi.yaml

@@ -1616,6 +1616,20 @@ components:
         diagram:
           type: string
           description: The mermaid flowchart of the compiled graph (preview).
+        humanNodes:
+          type: array
+          items:
+            $ref: "#/components/schemas/DeliveryHumanStop"
+          description: >-
+            The human stop-points the compiled graph parks on (preview) — where it waits for a person
+            (or an agent answering on their behalf), rendered by the Delivery Graphs page (#441).
+        sideEffects:
+          type: array
+          items:
+            $ref: "#/components/schemas/DeliverySideEffect"
+          description: >-
+            The side-effecting (`agent`/`connector`) actions the compiled graph WILL perform (preview)
+            — what an approval authorises (Decision 7), rendered by the Delivery Graphs page (#441).
     ResolvedDeliveryNode:
       description: >-
         A normalised node in the compiled graph (ADR 0005 slice S1) — its `id`, `kind`, the

package/operations/acknowledgeEpic.test.ts

@@ -1,9 +1,14 @@
 // Tests for the POST /app/api/actions/acknowledge-epic operation `acknowledgeEpic` (issue #298).
-// The nwf UI's "Dismiss" affordance for a RESOLVED epic — landed (`delivery=landed`) or
-// resolved-not-landed (`delivery=null`); only still-`converging` epics are rejected. It stamps
+// The nwf UI's "Dismiss" affordance for a RESOLVED epic — landed (delivery=landed) or
+// resolved-not-landed (delivery=null); only still-`converging` epics are rejected. It stamps
 // `acknowledged_at` via the plans gateway, which recomputes `list_bucket` to 'history' (and
 // `ack_open` to 0), dropping the resolved epic from Active into History. Unlike acknowledge-blocked
 // it completes NO user task (a resolved epic is not parked). The epic twin of acknowledge-done.
+//
+// Since epic #412 retired the stored `plans.delivery` column, the op derives the delivery signal at
+// READ TIME (`derivePlanDelivery` → the pure `deriveDelivery`) by joining the epic's slice
+// `plan_tasks.pr_key` → `pull_requests.status`. So these tests seed `plan_tasks` + `pull_requests`
+// (not a `plans.delivery` column) to model a landed / converging / resolved-not-landed epic.
 import { test } from "node:test";
 import { assertEquals } from "#test-assert";
 import type { AppApi } from "@nanobpm/urban";
@@ -12,9 +17,13 @@ import { noopLog } from "../test/log.ts";
 import handler from "./acknowledgeEpic.ts";
 
 // An in-memory data layer wired through the REAL plans gateway proxy, so the test exercises the
-// gateway's list_bucket/ack_open projection exactly as production does.
-function memApp(seed: any[]): { app: AppApi; rows: any[] } {
-  const stores: Record<string, any[]> = { plans: seed };
+// gateway's list_bucket/ack_open projection exactly as production does. `extra` seeds the join
+// surfaces (`plan_tasks` / `pull_requests`) the read-time delivery derivation reads.
+function memApp(
+  seed: any[],
+  extra: Record<string, any[]> = {},
+): { app: AppApi; rows: any[] } {
+  const stores: Record<string, any[]> = { plans: seed, ...extra };
   function tbl(name: string, pk = "id") {
     const rows = (stores[name] ??= [] as any[]);
     const match = (r: any, where: any) => Object.entries(where).every(([k, v]) => r[k] === v);
@@ -50,10 +59,21 @@ async function call(app: AppApi, body: unknown) {
   return (await handler({ req: {} as any, params: {}, query: {}, body } as any, app)) as any;
 }
 
+/** Fire a projecting gateway write (re-writing `status`) so `list_bucket`/`ack_open` reflect the
+ *  delivery-free gateway projection, mirroring the last real write before the op runs. */
+async function project(app: AppApi, key: string, status: string) {
+  await plans(app.data).update(key, { status });
+}
+
 test("acknowledge-epic: stamps acknowledged_at and flips list_bucket to 'history' on a landed epic", async () => {
-  const { app, rows } = memApp([{ plan_key: "o/r#1", status: "done", delivery: "landed", acknowledged_at: null }]);
-  // Seed the projection as the gateway would have on the last write (landed, unacknowledged → active).
-  await plans(app.data).update("o/r#1", { delivery: "landed" });
+  const { app, rows } = memApp(
+    [{ plan_key: "o/r#1", status: "done", acknowledged_at: null }],
+    {
+      plan_tasks: [{ id: 1, plan_key: "o/r#1", pr_key: "o/r#100" }],
+      pull_requests: [{ pr_key: "o/r#100", status: "merged" }], // landed
+    },
+  );
+  await project(app, "o/r#1", "done");
   assertEquals(rows[0].list_bucket, "active");
   assertEquals(rows[0].ack_open, 1);
 
@@ -67,8 +87,20 @@ test("acknowledge-epic: stamps acknowledged_at and flips list_bucket to 'history
 });
 
 test("acknowledge-epic: a still-converging epic is rejected (409) and stays Active", async () => {
-  const { app, rows } = memApp([{ plan_key: "o/r#2", status: "done", delivery: "converging", acknowledged_at: null }]);
-  await plans(app.data).update("o/r#2", { delivery: "converging" });
+  const { app, rows } = memApp(
+    [{ plan_key: "o/r#2", status: "done", acknowledged_at: null }],
+    {
+      plan_tasks: [
+        { id: 1, plan_key: "o/r#2", pr_key: "o/r#200" },
+        { id: 2, plan_key: "o/r#2", pr_key: "o/r#201" },
+      ],
+      pull_requests: [
+        { pr_key: "o/r#200", status: "merged" },
+        { pr_key: "o/r#201", status: "converging" }, // still in flight → converging
+      ],
+    },
+  );
+  await project(app, "o/r#2", "done");
 
   const res = await call(app, { plan_key: "o/r#2" });
 
@@ -80,9 +112,20 @@ test("acknowledge-epic: a still-converging epic is rejected (409) and stays Acti
 });
 
 test("acknowledge-epic: a resolved-not-landed epic (delivery=null) is accepted (200) and flips to History", async () => {
-  const { app, rows } = memApp([{ plan_key: "o/r#2b", status: "done", delivery: null, acknowledged_at: null }]);
-  // Seed the projection as the gateway would have on the last write (resolved-not-landed, unacknowledged → active).
-  await plans(app.data).update("o/r#2b", { delivery: null });
+  const { app, rows } = memApp(
+    [{ plan_key: "o/r#2b", status: "done", acknowledged_at: null }],
+    {
+      plan_tasks: [
+        { id: 1, plan_key: "o/r#2b", pr_key: "o/r#210" },
+        { id: 2, plan_key: "o/r#2b", pr_key: "o/r#211" },
+      ],
+      pull_requests: [
+        { pr_key: "o/r#210", status: "merged" },
+        { pr_key: "o/r#211", status: "abandoned" }, // all terminal, not all merged → delivery null
+      ],
+    },
+  );
+  await project(app, "o/r#2b", "done");
   assertEquals(rows[0].list_bucket, "active");
   assertEquals(rows[0].ack_open, 1);
 
@@ -96,7 +139,7 @@ test("acknowledge-epic: a resolved-not-landed epic (delivery=null) is accepted (
 });
 
 test("acknowledge-epic: a live (dispatched) epic is rejected (409)", async () => {
-  const { app } = memApp([{ plan_key: "o/r#3", status: "dispatched", delivery: null, acknowledged_at: null }]);
+  const { app } = memApp([{ plan_key: "o/r#3", status: "dispatched", acknowledged_at: null }]);
   const res = await call(app, { plan_key: "o/r#3" });
   assertEquals(res.status, 409);
 });
@@ -114,8 +157,14 @@ test("acknowledge-epic: no matching epic → 404", async () => {
 });
 
 test("acknowledge-epic: idempotent — re-acknowledging a landed epic keeps it in History", async () => {
-  const { app, rows } = memApp([{ plan_key: "o/r#5", status: "done", delivery: "landed", acknowledged_at: null }]);
-  await plans(app.data).update("o/r#5", { delivery: "landed" });
+  const { app, rows } = memApp(
+    [{ plan_key: "o/r#5", status: "done", acknowledged_at: null }],
+    {
+      plan_tasks: [{ id: 1, plan_key: "o/r#5", pr_key: "o/r#500" }],
+      pull_requests: [{ pr_key: "o/r#500", status: "merged" }], // landed
+    },
+  );
+  await project(app, "o/r#5", "done");
 
   assertEquals((await call(app, { plan_key: "o/r#5" })).status, 200);
   const firstStamp = rows[0].acknowledged_at;

package/operations/acknowledgeEpic.ts

@@ -19,6 +19,7 @@
 
 import { epicIsAcknowledgeable } from "../app/delivery.ts";
 import { plans } from "../app/plan.ts";
+import { derivePlanDelivery } from "../app/service.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
 
 const str = (v: unknown): string => (typeof v === "string" ? v.trim() : "");
@@ -43,11 +44,14 @@ export default defineOperation("acknowledgeEpic", async ({ body }, app) => {
   // affordance. Acknowledging a live/converging epic would pre-seed `acknowledged_at`, so the moment
   // it later resolved `deriveEpicBucket` would drop it straight into History, skipping the operator
   // tick-off this op exists to require — and a converging epic must stay visible while its slices land.
-  if (!epicIsAcknowledgeable(plan.status, plan.delivery ?? null)) {
+  // The `plans.delivery` column was retired (epic #412), so derive the signal at read time from the
+  // slice PRs (the same pure `deriveDelivery` the `plan_delivery` VIEW encodes).
+  const delivery = await derivePlanDelivery(app.data, plan);
+  if (!epicIsAcknowledgeable(plan.status, delivery)) {
     app.log.warn("acknowledge-epic rejected: epic is not resolved", {
       planKey,
       status: plan.status,
-      delivery: plan.delivery ?? null,
+      delivery,
     });
     return { status: 409, body: { ok: false, error: "epic is not resolved" } };
   }

package/operations/previewDeliveryGraph.test.ts

@@ -35,6 +35,15 @@ test("preview-delivery-graph: a pasted well-formed graph → 200 summary with di
   assertEquals(res.body.sideEffecting, true);
   assert(typeof res.body.diagram === "string" && res.body.diagram.length > 0);
   assertEquals(res.body.title, "runbook");
+  // The FULL preview detail (#441) — the human stop-points and side-effecting actions the page
+  // renders, not just the counts. `a` is the side-effecting agent node; `b` is the human stop.
+  assert(Array.isArray(res.body.humanNodes) && res.body.humanNodes.length === 1);
+  assertEquals(res.body.humanNodes[0].nodeId, "b");
+  assertEquals(res.body.humanNodes[0].prompt, "do X");
+  assert(Array.isArray(res.body.sideEffects) && res.body.sideEffects.length === 1);
+  assertEquals(res.body.sideEffects[0].nodeId, "a");
+  assertEquals(res.body.sideEffects[0].kind, "agent");
+  assert(typeof res.body.sideEffects[0].description === "string" && res.body.sideEffects[0].description.length > 0);
 });
 
 test("preview-delivery-graph: is PURE — repeated previews return the identical digest", async () => {

package/operations/previewDeliveryGraph.ts

@@ -54,6 +54,12 @@ export default defineOperation("previewDeliveryGraph", async ({ body }, app) =>
       humanNodeCount: compiled.humanNodes.length,
       sideEffectCount: compiled.sideEffects.length,
       diagram: compiled.diagram,
+      // The FULL extracted preview detail (not just the counts): the human stop-points and the
+      // side-effecting actions the operator is being asked to approve (Decision 7). The Delivery
+      // Graphs page renders these lists so the operator sees WHERE it parks on a person and WHAT it
+      // will do before dispatching — the "preview before dispatch" principle made visible (#441).
+      humanNodes: compiled.humanNodes,
+      sideEffects: compiled.sideEffects,
     },
   };
 });

package/package.json

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