@nanobpm/nano-workforce 0.136.0 → 0.138.0

package/app/planRollups.ts

@@ -0,0 +1,127 @@
+// The plan-family GROUP-BY rollups — DECLARED ONCE and compiled to BOTH backends via Urban's ADR-0065
+// rollup primitive (`defineRollup`, `@nanobpm/urban`, capability nano-ide#468 / `@nanobpm/urban@0.82.0`).
+//
+// Background (issues #411 → #412 → #493). The Epic surfaces render DERIVED aggregate state — each epic's
+// per-wave six-way task partition (059's `plan_wave_counts`), its wave FRONTIER (`wave_count`/
+// `current_wave`, 060's `plan_wave_progress`), and its slice-PR landing counts (061's
+// `plan_delivery_counts`). None of these are ground truth: each is a pure GROUP BY over `plan_tasks`
+// joined to `pull_requests`. 059/060/061 expressed them as hand-authored SQL VIEWs *and* the runtime
+// TS (`deriveDelivery` folded the same counts; the wave frontier was reproduced in the poller), kept in
+// lockstep by hand-written parity tests — the ADR-0065 drift surface #2 (each aggregate authored twice).
+//
+// This module closes surface #2 for the aggregates STRUCTURALLY: each rollup is declared ONCE in Urban's
+// closed GROUP-BY spec (`defineRollup`), and Urban compiles it to BOTH the managed `*_counts` VIEW
+// (`viewDdl`/`sqlAggFor`, emitted verbatim into the superseding migration, drift-guarded) AND the
+// runtime TS group-reduce (`reduce`, the sole engine behind the `deriveDelivery` façade in app/
+// delivery.ts). The two lowerings fall out of the SAME closed spec, and `assertRollupParity` (app/
+// planReadModel.test.ts) is the framework-owned regression guard that they agree.
+//
+// The per-row signals that CONSUME these counts (delivery / list_bucket / ack_open) live in
+// app/planReadModel.ts (`defineReadModel` + key-correlated rollup lookups); the pre-formatted display
+// strings (`bar`, `wave_label`, `delivery_label`) stay hand-authored over these derived columns (D3 —
+// display formatting is out of the framework AST). Use app/featureReadModel.ts as the exemplar.
+
+import { add, and, coalesce, col, count, countWhere, defineRollup, eq, fromRollup, gt, isNotNull, joinSource, lit, max, minWhere, not, or, type Rollup } from "@nanobpm/urban";
+import { TERMINAL_STATUSES } from "./deliveryStatuses.ts";
+
+/** The slice-PR relation the delivery/wave rollups join: the auto-provisioned `pull_requests__tracking`
+ * derived VIEW (ADR-0065), NOT the raw `pull_requests` table. It re-exports `pull_requests.*` plus a
+ * terminal-folded `derived_status` (`abandoned` on an out-of-band-terminated PR instance, else the base
+ * `pull_requests.status`). Reading `derived_status` here — the SAME column the canonical runtime reads
+ * via `prsTracking` (app/service.ts `derivePlanDelivery`) — keeps the SQL VIEW counts and the runtime
+ * in agreement: an out-of-band-terminated converging slice reads `abandoned` (resolved), so the VIEW
+ * can never wedge an epic at `delivery = 'converging'` after its PR was cancelled. Exported so the
+ * app/delivery.ts adapter feeds its synthesised leaf rows under the same relation name. */
+export const PR_TRACKING_RELATION = "pull_requests__tracking";
+
+/** `plan_tasks t LEFT JOIN pull_requests__tracking p ON p.pr_key = t.pr_key` as a rollup source, with a
+ * FLAT output namespace so the closed aggregate/predicate machinery reads unqualified column names.
+ * `pr_status` is the tracking VIEW's terminal-folded `derived_status` (see {@link PR_TRACKING_RELATION}).
+ * The two plan-family count rollups both fold over this two-hop join (D4). */
+const planTasksJoinPrs = joinSource({
+  left: { relation: "plan_tasks", alias: "t" },
+  right: { relation: PR_TRACKING_RELATION, alias: "p" },
+  on: [{ left: "pr_key", right: "pr_key" }],
+  columns: {
+    plan_key: ["left", "plan_key"],
+    wave: ["left", "wave"],
+    task_status: ["left", "status"],
+    pr_key: ["left", "pr_key"],
+    pr_status: ["right", "derived_status"],
+  },
+});
+
+/** `<pr_status> <> 'merged'` under the shared "NULL → not-merged" rule: `not(eq(...))` compiles to
+ * `NOT COALESCE((pr_status = 'merged'), 0)` in SQL and the nullish-guarded negation in TS, so a task
+ * whose PR row is absent (`pr_status` NULL) is treated as NOT merged in BOTH backends — matching 059's
+ * `WHEN p.status = 'merged' THEN 0 …` fall-through (a NULL `p.status` never matches the merged arm). */
+const prNotMerged = not(eq(col("pr_status"), lit("merged")));
+
+/** `<task_status> = <value>` for a NON-merged task — the priority-ordered five-way bucket predicate the
+ * 059 partition uses (`WHEN p.status = 'merged' THEN 0 WHEN t.status = '<b>' THEN 1 ELSE 0`), so the
+ * five named buckets stay DISJOINT with `merged` and sum to `total`. */
+const nonMergedTaskIs = (bucket: string) => and(prNotMerged, eq(col("task_status"), lit(bucket)));
+
+/**
+ * `plan_wave_counts` — one row per `(plan_key, wave)` with the six-way task partition (059). A task is
+ * `merged` iff its PR reached `pull_requests.status = 'merged'`; otherwise it falls to its
+ * `plan_tasks.status` bucket, and everything else (pending/opened/waiting-for-lane/abandoned) is
+ * `in_flight`. The CASE priority (encoded as disjoint `countWhere` predicates) keeps the five named
+ * buckets DISJOINT so they always sum to `total`. `WHERE wave IS NOT NULL` drops un-levelized tasks.
+ */
+export const planWaveCounts: Rollup = defineRollup({
+  name: "plan_wave_counts",
+  source: planTasksJoinPrs,
+  groupBy: ["plan_key", "wave"],
+  where: isNotNull(col("wave")),
+  aggregates: {
+    total: count(),
+    merged: countWhere(eq(col("pr_status"), lit("merged"))),
+    skipped: countWhere(nonMergedTaskIs("skipped")),
+    blocked: countWhere(nonMergedTaskIs("blocked")),
+    escalated: countWhere(nonMergedTaskIs("escalated")),
+    in_flight: countWhere(and(prNotMerged, not(or(eq(col("task_status"), lit("skipped")), eq(col("task_status"), lit("blocked")), eq(col("task_status"), lit("escalated")))))),
+  },
+});
+
+/**
+ * `plan_wave_progress` — one row per `plan_key` with the two wave-frontier projections (060), COMPOSED
+ * over `plan_wave_counts` (a rollup source — D1's composability):
+ *   - `wave_count`   = `MAX(wave) + 1` (the levelizer emits contiguous waves 0..N-1).
+ *   - `current_wave` = the live FRONTIER: the lowest wave that still has an `in_flight` task, else —
+ *                      once every wave has settled — pinned to the last index `MAX(wave)`.
+ * A plan with no levelized tasks contributes no `plan_wave_counts` row, so it is absent here and reads
+ * NULL through the downstream read-model LEFT JOIN — matching the workers' taskless-plan behaviour.
+ */
+export const planWaveProgress: Rollup = defineRollup({
+  name: "plan_wave_progress",
+  source: fromRollup(planWaveCounts),
+  groupBy: ["plan_key"],
+  aggregates: {
+    wave_count: add(max("wave"), 1),
+    current_wave: coalesce(minWhere("wave", gt(col("in_flight"), lit(0))), max("wave")),
+  },
+});
+
+/**
+ * `plan_delivery_counts` — one row per `plan_key` with the three counts `deriveDelivery` folds over the
+ * slice PRs (061). Only tasks that OPENED a PR count (`prs_opened = COUNT(pr_key)`, non-NULL). A
+ * `pr_key` with no `pull_requests` row (`pr_status` NULL, the poller's `MISSING_PR_STATUS` sentinel) is
+ * non-terminal, so it counts as `prs_in_flight` — a DB desync can never wrongly promote an epic to
+ * `landed`. `prs_in_flight` = opened PRs whose status is NOT in {@link TERMINAL_STATUSES}
+ * (a NULL status is not terminal), exactly `deriveDelivery`'s in-flight fold.
+ */
+export const planDeliveryCounts: Rollup = defineRollup({
+  name: "plan_delivery_counts",
+  source: planTasksJoinPrs,
+  groupBy: ["plan_key"],
+  aggregates: {
+    prs_opened: count("pr_key"),
+    prs_merged: countWhere(and(isNotNull(col("pr_key")), eq(col("pr_status"), lit("merged")))),
+    prs_in_flight: countWhere(and(isNotNull(col("pr_key")), not(or(...TERMINAL_STATUSES.map((s) => eq(col("pr_status"), lit(s))))))),
+  },
+});
+
+/** Every plan-family rollup, in managed-VIEW dependency order (a composed rollup after the rollup it
+ * reads). The superseding migration emits their VIEW DDL in this order; the parity guard iterates it. */
+export const PLAN_ROLLUPS: readonly Rollup[] = [planWaveCounts, planDeliveryCounts, planWaveProgress];

package/db/migrations/082_plan_rollups_declare_once.sql

@@ -0,0 +1,74 @@
+-- Plan-family GROUP-BY rollups, authored ONCE via Urban's ADR-0065 rollup primitive (`defineRollup`,
+-- app/planRollups.ts, `@nanobpm/urban@0.82.0` / nano-ide#468) — issue #493 (the plan-family twin of
+-- 076's feature read-model declare-once).
+--
+-- 059_plan_wave_summary.sql, 060_plan_wave_rollup.sql and 061_plan_delivery_rollup.sql hand-authored
+-- the three plan-family aggregates — `plan_wave_counts` (per-(plan_key, wave) six-way task partition),
+-- `plan_wave_progress` (the wave frontier `wave_count`/`current_wave`), and `plan_delivery_counts` (the
+-- slice-PR landing counts) — as SQL VIEWs, AND folded the SAME counts a SECOND time in the runtime TS
+-- (`deriveDelivery` folded the delivery counts; the poller reproduced the wave frontier). That is the
+-- ADR-0065 drift surface #2 (each aggregate authored twice, kept in lockstep by hand-written parity
+-- tests). This migration SUPERSEDES the three VIEW bodies with the VERBATIM DDL Urban compiles from the
+-- ONE `defineRollup` declaration for each (app/planRollups.ts) — which ALSO drives the runtime TS
+-- group-reduce (`reduce`, the sole engine behind `deriveDelivery` in app/delivery.ts). The two
+-- lowerings fall out of the same closed GROUP-BY spec and cannot diverge; the drift guard
+-- (app/planReadModel.test.ts) fails if this file stops matching the declaration, and
+-- `assertRollupParity` proves the VIEW and TS reduce agree. 059/060/061 are MERGED, IMMUTABLE
+-- migrations — never edited; this is a NEW migration superseding their VIEW bodies (the pattern by
+-- which 081 superseded 076's feature VIEW).
+--
+-- SEMANTICS are unchanged from 059/060/061 (validated byte-identical over a random corpus): a task is
+-- `merged` iff its PR reached `pull_requests__tracking.derived_status = 'merged'`, otherwise it falls to its
+-- `plan_tasks.status` bucket; the five named buckets stay DISJOINT and sum to `total`; the delivery
+-- counts fold only tasks that OPENED a PR, and a dangling `pr_key` (NULL status) counts as in-flight so
+-- a DB desync can never wrongly promote an epic to `landed`. Each rollup emits `CREATE VIEW <name> AS
+-- SELECT … FROM … GROUP BY …` (aggregates aliased in the select-list) so the static pages↔schema
+-- contract guard (scripts/pages-contract.test.ts) still reads each VIEW's output columns.
+--
+-- Layered in dependency order: `plan_wave_counts` first (the leaf GROUP BY over `plan_tasks` LEFT JOIN
+-- `pull_requests__tracking` (ADR-0065 derived VIEW; reads the terminal-folded `derived_status`, the
+-- SAME column the canonical runtime reads), then `plan_delivery_counts` (a sibling GROUP BY over the same join), then
+-- `plan_wave_progress` (COMPOSED over `plan_wave_counts` — D1's composability). The retained
+-- `plan_wave_summary` (059, the `bar` glyph) and `plan_wave_label` (060) VIEWs read the recreated
+-- `plan_wave_counts`/`plan_wave_progress` unchanged. A merged VIEW is not editable in place, so each is
+-- DROP+CREATE; nothing structural changes, so every dependent VIEW and page binding stays valid.
+--
+-- Forward-only VIEW redefinition (DROP then CREATE). The runner wraps each file in its own transaction,
+-- so this file must NOT contain BEGIN/COMMIT. Numbered after 081.
+
+DROP VIEW IF EXISTS plan_wave_counts;
+
+CREATE VIEW IF NOT EXISTS "plan_wave_counts" AS
+SELECT
+  "t"."plan_key" AS "plan_key",
+  "t"."wave" AS "wave",
+  SUM(CASE WHEN COALESCE(((NOT COALESCE(COALESCE(("p"."derived_status" = 'merged'), 0), 0)) AND COALESCE(("t"."status" = 'blocked'), 0)), 0) THEN 1 ELSE 0 END) AS "blocked",
+  SUM(CASE WHEN COALESCE(((NOT COALESCE(COALESCE(("p"."derived_status" = 'merged'), 0), 0)) AND COALESCE(("t"."status" = 'escalated'), 0)), 0) THEN 1 ELSE 0 END) AS "escalated",
+  SUM(CASE WHEN COALESCE(((NOT COALESCE(COALESCE(("p"."derived_status" = 'merged'), 0), 0)) AND (NOT COALESCE(COALESCE((COALESCE(("t"."status" = 'skipped'), 0) OR COALESCE(("t"."status" = 'blocked'), 0) OR COALESCE(("t"."status" = 'escalated'), 0)), 0), 0))), 0) THEN 1 ELSE 0 END) AS "in_flight",
+  SUM(CASE WHEN COALESCE(("p"."derived_status" = 'merged'), 0) THEN 1 ELSE 0 END) AS "merged",
+  SUM(CASE WHEN COALESCE(((NOT COALESCE(COALESCE(("p"."derived_status" = 'merged'), 0), 0)) AND COALESCE(("t"."status" = 'skipped'), 0)), 0) THEN 1 ELSE 0 END) AS "skipped",
+  COUNT(*) AS "total"
+FROM "plan_tasks" "t" LEFT JOIN "pull_requests__tracking" "p" ON "t"."pr_key" = "p"."pr_key"
+WHERE (NOT COALESCE(("t"."wave" IS NULL), 0))
+GROUP BY "t"."plan_key", "t"."wave";
+
+DROP VIEW IF EXISTS plan_delivery_counts;
+
+CREATE VIEW IF NOT EXISTS "plan_delivery_counts" AS
+SELECT
+  "t"."plan_key" AS "plan_key",
+  SUM(CASE WHEN COALESCE(((NOT COALESCE(("t"."pr_key" IS NULL), 0)) AND (NOT COALESCE(COALESCE((COALESCE(("p"."derived_status" = 'converged'), 0) OR COALESCE(("p"."derived_status" = 'merged'), 0) OR COALESCE(("p"."derived_status" = 'abandoned'), 0)), 0), 0))), 0) THEN 1 ELSE 0 END) AS "prs_in_flight",
+  SUM(CASE WHEN COALESCE(((NOT COALESCE(("t"."pr_key" IS NULL), 0)) AND COALESCE(("p"."derived_status" = 'merged'), 0)), 0) THEN 1 ELSE 0 END) AS "prs_merged",
+  COUNT("t"."pr_key") AS "prs_opened"
+FROM "plan_tasks" "t" LEFT JOIN "pull_requests__tracking" "p" ON "t"."pr_key" = "p"."pr_key"
+GROUP BY "t"."plan_key";
+
+DROP VIEW IF EXISTS plan_wave_progress;
+
+CREATE VIEW IF NOT EXISTS "plan_wave_progress" AS
+SELECT
+  "__urban_rollup_src"."plan_key" AS "plan_key",
+  COALESCE(MIN(CASE WHEN COALESCE(("__urban_rollup_src"."in_flight" > 0), 0) THEN "__urban_rollup_src"."wave" END), MAX("__urban_rollup_src"."wave")) AS "current_wave",
+  (MAX("__urban_rollup_src"."wave") + 1) AS "wave_count"
+FROM "plan_wave_counts" "__urban_rollup_src"
+GROUP BY "__urban_rollup_src"."plan_key";

package/db/migrations/083_plan_read_model_declare_once.sql

@@ -0,0 +1,84 @@
+-- Epic `plan_read_model` per-row signals, authored ONCE via Urban's ADR-0065 reconciling-read-model
+-- primitive (`defineReadModel` + key-correlated rollup lookups, app/planReadModel.ts,
+-- `@nanobpm/urban@0.82.0` / nano-ide#468) — issue #493 (the plan-family twin of 076/081's feature
+-- read-model declare-once; the exemplar is app/featureReadModel.ts).
+--
+-- 061_plan_delivery_rollup.sql, 074_plan_read_model_derive_bucket.sql and
+-- 080_plan_read_model_derive_terminal.sql hand-authored the epic per-row signals — `delivery`
+-- (converging/landed/NULL), the Active/History `list_bucket`, and the operator-Dismiss `ack_open`
+-- flag — as SQL `CASE` expressions inside the `plan_delivery` / `plan_read_model` VIEWs, AND a SECOND
+-- time in the runtime TS (`deriveDelivery`/`deriveEpicBucket`/`epicIsAcknowledgeable`, app/delivery.ts),
+-- kept in lockstep by hand-written parity tests (ADR-0065 drift surface #2). This migration SUPERSEDES
+-- 080's `plan_read_model` VIEW body: every DERIVED column below is emitted VERBATIM from the ONE
+-- `planReadModel` declaration (`planReadModel.sqlSelectFor(col, { baseAlias: "pl" })`), which ALSO
+-- drives the runtime TS via `fnFor` (behind the app/delivery.ts adapters). The two lowerings fall out
+-- of the same closed-DSL AST and cannot diverge; the drift guard (app/planReadModel.test.ts) fails if
+-- this file stops matching the declaration, and `assertReadModelParity` proves the SQL and TS lowerings
+-- agree. 061/074/080 are MERGED, IMMUTABLE migrations — never edited; this is a NEW migration
+-- superseding 080's VIEW body (the pattern by which 080 superseded 074).
+--
+-- SEMANTICS are unchanged from 080 (validated byte-identical over a random corpus): the status-
+-- classifying `list_bucket`/`ack_open` arms read the terminal-folded `derived_status` off the
+-- auto-provisioned `plans__tracking` derived VIEW (so a cancelled epic drops out of Active with no
+-- worker write, issue #503); `delivery` reads the base `plans.status` (`done` is already terminal, so
+-- base and effective agree on the `= 'done'` gate, and this keeps `delivery` byte-identical to the
+-- retired `plan_delivery` VIEW and to `deriveDelivery(plan.status, …)`'s call sites). The single-valued
+-- rollup lookups the CASEs consume are `LEFT JOIN plan_delivery_counts dc` (slice-PR counts, defaulted
+-- to 0 on a miss) and `LEFT JOIN plan_wave_progress wp` (the wave frontier), the D1 per-row half over
+-- the rollups single-sourced in 082.
+--
+-- The pre-formatted DISPLAY strings stay hand-authored over these derived structured columns (D3 —
+-- display formatting is out of the framework AST, so they carry no TS twin): `delivery_label` mirrors
+-- the retired `plan_delivery` label CASE (over the base status + `dc` counts) and `wave_label` is the
+-- 1-based "X/N" string over the `wp` frontier. The wave `bar` glyph stays in the retained
+-- `plan_wave_summary` VIEW (059). Base columns stay aliased pass-throughs (so the static pages↔schema
+-- contract guard still reads the VIEW's columns), sourced off `plans__tracking`'s re-export of the base
+-- `plans.*`; `plans__tracking pl` is the sole top-level FROM.
+--
+-- The retired intermediate VIEWs `plan_delivery` (061) and `plan_wave_label` (060) were consumed ONLY
+-- by `plan_read_model`; this migration folds their derivations/display into the composite and DROPs
+-- them. `plan_read_model` is a leaf (no VIEW builds on it) and its output column set is UNCHANGED, so
+-- the pages↔schema contract guard and every page binding stay valid. `plans__tracking` is the managed
+-- VIEW urban provisions at mount; SQLite does not validate a view body at CREATE time, so this
+-- migration (which runs before that mount) is created fine and resolves once the managed VIEW exists.
+--
+-- Forward-only VIEW redefinition (DROP then CREATE). The runner wraps each file in its own transaction,
+-- so this file must NOT contain BEGIN/COMMIT. Numbered after 082.
+
+DROP VIEW IF EXISTS plan_read_model;
+DROP VIEW IF EXISTS plan_delivery;
+DROP VIEW IF EXISTS plan_wave_label;
+
+CREATE VIEW plan_read_model AS
+SELECT
+  pl.plan_key AS plan_key,
+  pl.repo AS repo,
+  pl.issue_number AS issue_number,
+  pl.issue_url AS issue_url,
+  pl.title AS title,
+  COALESCE(pl.derived_status, pl.status) AS status,
+  pl.task_count AS task_count,
+  pl.process_key AS process_key,
+  pl.outcome AS outcome,
+  pl.updated_at AS updated_at,
+  pl.epic_phase AS epic_phase,
+  pl.base_branch AS base_branch,
+  pl.wait_gate_label AS wait_gate_label,
+  pl.bound_artifacts AS bound_artifacts,
+  pl.promotion_pr AS promotion_pr,
+  pl.promotion_state AS promotion_state,
+  CASE WHEN COALESCE(((NOT COALESCE(COALESCE(("pl"."status" = 'done'), 0), 0)) OR COALESCE((COALESCE("dc"."prs_opened", 0) = 0), 0)), 0) THEN NULL WHEN COALESCE((COALESCE("dc"."prs_in_flight", 0) > 0), 0) THEN 'converging' WHEN COALESCE((COALESCE("dc"."prs_merged", 0) = COALESCE("dc"."prs_opened", 0)), 0) THEN 'landed' ELSE NULL END AS delivery,
+  "wp"."wave_count" AS wave_count,
+  "wp"."current_wave" AS current_wave,
+  CASE WHEN COALESCE((COALESCE(("pl"."derived_status" = 'planning'), 0) OR COALESCE(("pl"."derived_status" = 'dispatched'), 0)), 0) THEN 'active' WHEN COALESCE((COALESCE(("pl"."derived_status" = 'done'), 0) AND COALESCE((CASE WHEN COALESCE(((NOT COALESCE(COALESCE(("pl"."status" = 'done'), 0), 0)) OR COALESCE((COALESCE("dc"."prs_opened", 0) = 0), 0)), 0) THEN NULL WHEN COALESCE((COALESCE("dc"."prs_in_flight", 0) > 0), 0) THEN 'converging' WHEN COALESCE((COALESCE("dc"."prs_merged", 0) = COALESCE("dc"."prs_opened", 0)), 0) THEN 'landed' ELSE NULL END = 'converging'), 0)), 0) THEN 'active' WHEN COALESCE((COALESCE(("pl"."derived_status" = 'done'), 0) AND ("pl"."acknowledged_at" IS NULL)), 0) THEN 'active' WHEN COALESCE(("pl"."derived_status" = 'done'), 0) THEN 'history' ELSE 'history' END AS list_bucket,
+  CASE WHEN COALESCE((COALESCE(("pl"."derived_status" = 'done'), 0) AND (NOT COALESCE(COALESCE((CASE WHEN COALESCE(((NOT COALESCE(COALESCE(("pl"."status" = 'done'), 0), 0)) OR COALESCE((COALESCE("dc"."prs_opened", 0) = 0), 0)), 0) THEN NULL WHEN COALESCE((COALESCE("dc"."prs_in_flight", 0) > 0), 0) THEN 'converging' WHEN COALESCE((COALESCE("dc"."prs_merged", 0) = COALESCE("dc"."prs_opened", 0)), 0) THEN 'landed' ELSE NULL END = 'converging'), 0), 0)) AND ("pl"."acknowledged_at" IS NULL)), 0) THEN 1 ELSE 0 END AS ack_open,
+  CASE
+    WHEN pl.status IS NOT 'done' OR COALESCE(dc.prs_opened, 0) = 0 THEN NULL
+    WHEN COALESCE(dc.prs_in_flight, 0) > 0 THEN dc.prs_merged || '/' || dc.prs_opened || ' slices merged, ' || dc.prs_in_flight || ' converging'
+    WHEN dc.prs_merged = dc.prs_opened THEN dc.prs_opened || '/' || dc.prs_opened || ' slices merged'
+    ELSE NULL
+  END AS delivery_label,
+  (wp.current_wave + 1) || '/' || wp.wave_count AS wave_label
+FROM plans__tracking pl
+LEFT JOIN plan_delivery_counts dc ON pl.plan_key = dc.plan_key
+LEFT JOIN plan_wave_progress wp ON pl.plan_key = wp.plan_key;

package/openapi.yaml

@@ -1590,12 +1590,30 @@ components:
         message:
           type: string
           description: Human-actionable description of the failure.
-    DeliveryGraphTextSubmit:
+    DeliveryGraphPreviewSubmit:
       description: >-
-        The human-facing UI JSON-paste PREVIEW request (issue #386). The Delivery Graphs page's text
-        field cannot submit a structured object, so the operator's pasted delivery-graph is carried as
+        The human-facing UI JSON-paste PREVIEW request (issues #386 + #516). The Delivery Graphs page's
+        "Preview" action cannot submit a structured object, so the operator's pasted delivery-graph is
+        carried as a raw JSON STRING (`graphJson`), parsed server-side and handed to the SAME pure
+        `compileDeliveryGraph` compiler the agent-facing door uses. Preview compiles WITHOUT persisting.
+        Per-operation schema (not shared with the stage door) so each door's request stays independently
+        evolvable.
+      type: object
+      additionalProperties: false
+      required:
+        - graphJson
+      properties:
+        graphJson:
+          type: string
+          description: The pasted delivery-graph JSON (a serialised `DeliveryGraph`), parsed server-side.
+    DeliveryGraphStageSubmit:
+      description: >-
+        The human-facing UI JSON-paste STAGE request (issue #516) — the commit half of the preview/stage
+        split. The Delivery Graphs page's "Stage" action carries the operator's pasted delivery-graph as
         a raw JSON STRING (`graphJson`), parsed server-side and handed to the SAME pure
-        `compileDeliveryGraph` compiler the agent-facing door uses. No parallel compile path.
+        `compileDeliveryGraph` compiler the preview/agent doors use, then persisted as a `staged`
+        proposal. Per-operation schema (not shared with the preview door) so each door's request stays
+        independently evolvable.
       type: object
       additionalProperties: false
       required:
@@ -1820,6 +1838,13 @@ components:
           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).
+        bpmn:
+          type: string
+          description: >-
+            The compiled BPMN 2.0 XML INCLUDING diagram interchange (`bpmndi:BPMNDiagram`) — returned by
+            the PURE preview door (`previewDeliveryGraph`) only, so the Delivery Graphs page can render
+            the laid-out BPMN in the host explorer WITHOUT staging (#516). Byte-identical to what a
+            dispatch would deploy. Omitted by the stage/dispatch outcomes.
     ResolvedDeliveryNode:
       description: >-
         A normalised node in the compiled graph (ADR 0005 slice S1) — its `id`, `kind`, the
@@ -2887,24 +2912,56 @@ paths:
   /actions/delivery-graph/preview:
     post:
       operationId: previewDeliveryGraph
-      summary: UI JSON-paste PREVIEW+STAGE — parse a pasted delivery-graph JSON string, compile it and stage it for operator dispatch. (ADR 0005 Decision 7 / #460)
+      summary: UI JSON-paste PURE PREVIEW — parse a pasted delivery-graph JSON string and compile it, without staging. (ADR 0005 Decision 7 / #460 / #516)
+      description: >-
+        The human-facing UI JSON-paste PURE PREVIEW ingress. The Delivery Graphs page's "Preview"
+        action posts the operator's pasted JSON as a STRING; this door parses it and runs the SAME
+        `compileDeliveryGraph` compiler the agent-facing door uses, but — unlike the compile/stage doors
+        — it does NOT persist anything (#516: preview and staging are separate operator actions). It
+        returns a compact preview summary (`staged:false`, the `digest`, node/human/side-effect counts,
+        the mermaid `diagram`, the human stops and side effects) PLUS the compiled `bpmn` (with diagram
+        interchange) so the page can render the laid-out BPMN in the host explorer without staging. It
+        never deploys, stages or dispatches. A blank/invalid JSON string, or a graph that fails
+        validation, is a 400 carrying a human `error` (and path-qualified `errors` for a compile failure).
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/DeliveryGraphPreviewSubmit"
+      responses:
+        "200":
+          description: The pasted graph parsed, validated and compiled — the preview summary and compiled BPMN are returned; nothing is staged.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DeliveryGraphTextResult"
+        "400":
+          description: The pasted text was not valid JSON, or the graph failed validation/compilation.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DeliveryGraphTextResult"
+  /actions/delivery-graph/stage:
+    post:
+      operationId: stageDeliveryGraph
+      summary: UI JSON-paste STAGE — parse a pasted delivery-graph JSON string, compile it and stage it for operator dispatch. (ADR 0005 Decision 7 / #460 / #516)
       description: >-
-        The human-facing UI JSON-paste PREVIEW+STAGE ingress. The Delivery Graphs page's "Preview &
-        stage" action posts the operator's pasted JSON as a STRING; this door parses it and runs the
-        SAME `compileDeliveryGraph` compiler the agent-facing door uses, and — like the agent compile
-        door (issue #460) — persists the compiled graph as a `staged` proposal (content-addressed by its
-        `digest`). It returns a compact preview summary (the `digest`, node/human/side-effect counts,
-        the mermaid `diagram`, the human stops and side effects) plus a navigational `reviewUrl`. It
-        never deploys or dispatches — dispatch is a separate operator action on the staged proposal
-        (the Dispatch button on the staged-proposals grid). A blank/invalid JSON string, or a graph that
-        fails validation, is a 400 carrying a human `error` (and path-qualified `errors` for a compile
-        failure); nothing is staged.
+        The human-facing UI JSON-paste STAGE ingress — the deliberate commit half of the preview/stage
+        split (#516). The Delivery Graphs page's "Stage" action posts the operator's pasted JSON as a
+        STRING; this door parses it, runs the SAME `compileDeliveryGraph` compiler the preview/agent
+        doors use, and — on success — persists the compiled graph as a `staged` proposal
+        (content-addressed by its `digest`). It returns the same preview summary as the preview door but
+        with `staged:true`. It never deploys or dispatches — dispatch is a separate operator action on
+        the staged proposal (the Dispatch button on the staged-proposals grid). A blank/invalid JSON
+        string, or a graph that fails validation, is a 400 carrying a human `error` (and path-qualified
+        `errors` for a compile failure); nothing is staged.
       requestBody:
         required: true
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/DeliveryGraphTextSubmit"
+              $ref: "#/components/schemas/DeliveryGraphStageSubmit"
       responses:
         "200":
           description: The pasted graph parsed, validated and compiled — staged for operator dispatch; the preview summary is returned.

package/operations/previewDeliveryGraph.test.ts

@@ -1,9 +1,9 @@
 // Tests for the POST /app/api/actions/delivery-graph/preview operation `previewDeliveryGraph` (ADR
-// 0005 Decision 7, issue #460) — the human-facing UI JSON-paste PREVIEW+STAGE ingress. It parses the
-// operator's pasted JSON STRING, runs the SAME `compileDeliveryGraph` compiler the agent door uses,
-// and — like the agent compile door — persists the compiled graph as a `staged` proposal, returning a
-// compact summary (200, `staged:true` + `reviewUrl`) or a human `error` + path-qualified `errors`
-// (400). It never dispatches — that is a separate operator action on the staged proposal.
+// 0005 Decision 7, issues #460 + #516) — the human-facing UI JSON-paste PURE PREVIEW ingress. It
+// parses the operator's pasted JSON STRING, runs the SAME `compileDeliveryGraph` compiler the agent
+// door uses, and returns a compact summary (200, `staged:false`, + the compiled `bpmn`) or a human
+// `error` + path-qualified `errors` (400). Unlike the stage door it persists NOTHING — preview and
+// staging are separate operator actions (#516).
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
@@ -42,12 +42,13 @@ const GOOD = JSON.stringify({
   edges: [{ from: "a", to: "b" }],
 });
 
-test("preview-delivery-graph: a pasted well-formed graph → 200 summary, staged, with digest + counts", async () => {
+test("preview-delivery-graph: a pasted well-formed graph → 200 summary, NOT staged, with digest + counts + bpmn", async () => {
   await withApp(async (app, data) => {
     const res = await call(app, { graphJson: GOOD });
     assertEquals(res.status, 200);
     assertEquals(res.body.ok, true);
-    assertEquals(res.body.staged, true);
+    // #516: preview is PURE — it compiles but never stages.
+    assertEquals(res.body.staged, false);
     assert(typeof res.body.digest === "string" && res.body.digest.length > 0);
     assert(typeof res.body.reviewUrl === "string" && res.body.reviewUrl.length > 0);
     assertEquals(res.body.nodeCount, 2);
@@ -56,8 +57,9 @@ test("preview-delivery-graph: a pasted well-formed graph → 200 summary, staged
     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.
+    // The PURE preview returns the laid-out BPMN so the page can render the DI without staging (#516).
+    assert(typeof res.body.bpmn === "string" && res.body.bpmn.includes("bpmndi:BPMNDiagram"));
+    // The FULL preview detail (#441) — the human stop-points and side-effecting actions the page renders.
     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");
@@ -65,19 +67,19 @@ test("preview-delivery-graph: a pasted well-formed graph → 200 summary, staged
     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);
-    // A staged proposal now exists for the operator to dispatch — and NO dispatch handle came back.
-    assertEquals((await deliveryGraphProposals(data).get(res.body.digest))?.status, "staged");
+    // NOTHING was staged, and no dispatch handle came back.
+    assertEquals((await deliveryGraphProposals(data).all()).length, 0);
     assertEquals(res.body.runKey, undefined);
     assertEquals(res.body.processInstanceKey, undefined);
   });
 });
 
-test("preview-delivery-graph: repeated previews stage the identical digest idempotently (one live row)", async () => {
+test("preview-delivery-graph: repeated previews are pure — the identical digest, still nothing staged", async () => {
   await withApp(async (app, data) => {
     const a = await call(app, { graphJson: GOOD });
     const b = await call(app, { graphJson: GOOD });
     assertEquals(a.body.digest, b.body.digest);
-    assertEquals((await deliveryGraphProposals(data).find({ digest: a.body.digest })).length, 1);
+    assertEquals((await deliveryGraphProposals(data).all()).length, 0);
   });
 });
 

package/operations/previewDeliveryGraph.ts

@@ -1,92 +1,34 @@
 // POST /app/api/actions/delivery-graph/preview → operationId `previewDeliveryGraph` (ADR 0005
-// Decision 7, issue #460). The human-facing UI JSON-paste PREVIEW+STAGE ingress: the Delivery Graphs
-// page's "Preview & stage" action posts the operator's pasted delivery-graph as a raw JSON STRING;
-// this door parses it (`parseDeliveryGraphText`) and runs the SAME `compileDeliveryGraph` compiler the
-// agent-facing door uses, and — like the agent compile door — persists the compiled graph as a
-// `staged` proposal (content-addressed by its `digest`).
+// Decision 7, issues #460 + #516). The human-facing UI JSON-paste PURE PREVIEW ingress: the Delivery
+// Graphs page's "Preview" action posts the operator's pasted delivery-graph as a raw JSON STRING; this
+// door parses it (`parseDeliveryGraphText`) and runs the SAME `compileDeliveryGraph` compiler the
+// agent-facing door uses — but, unlike the compile/stage doors, it does NOT persist anything. It is a
+// side-effect-free compile: preview and STAGING are now separate operator actions (#516), so an
+// operator can compile-and-inspect a graph (its diagram, human stop-points, side-effects) and iterate
+// before committing it to the staged-proposals list via the separate "Stage" action (stageDeliveryGraph).
 //
-// It returns a compact preview summary (the `digest`, node/human/side-effect counts, the mermaid
-// `diagram`, and the full human-stop / side-effect detail) plus a navigational `reviewUrl`. It never
-// deploys or dispatches — dispatch is a separate OPERATOR action on the staged proposal (the Dispatch
-// button on the staged-proposals grid). A blank/invalid paste, or a graph that fails validation, is a
-// 400 carrying a human `error` (and path-qualified `errors` for a compile failure); nothing is staged.
+// It returns a compact preview summary (`staged:false`, the `digest`, node/human/side-effect counts,
+// the mermaid `diagram`, the human stops and side effects) PLUS the compiled `bpmn` (with diagram
+// interchange) so the page can render the laid-out BPMN in the host explorer WITHOUT staging. It never
+// deploys or dispatches — dispatch is a separate operator action on a staged proposal. A blank/invalid
+// JSON string, or a graph that fails validation, is a 400 carrying a human `error` (and path-qualified
+// `errors` for a compile failure); nothing is compiled past the failure.
 
-import { compileDeliveryGraph } from "../app/deliveryGraphCompiler.ts";
-import {
-  buildProposalPreview,
-  buildProposalRow,
-  proposalLogicalKey,
-  proposalReviewUrl,
-  stageProposal,
-} from "../app/deliveryGraphProposals.ts";
-import { parseDeliveryGraphText } from "../app/deliveryGraphText.ts";
-import { deliveryGraphDigest } from "../app/deliveryRunner.ts";
+import { buildTextPreviewBody, parseAndCompileText } from "../app/deliveryGraphTextIngress.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
 
 export default defineOperation("previewDeliveryGraph", async ({ body }, app) => {
-  const parsed = parseDeliveryGraphText(body);
-  if (!parsed.ok) {
-    app.log.warn("preview-delivery-graph rejected: parse", { message: parsed.error });
-    return { status: 400, body: { ok: false, error: parsed.error } };
+  const ingress = await parseAndCompileText(body);
+  if (!ingress.ok) {
+    app.log.warn("preview-delivery-graph rejected", { message: ingress.body.error });
+    return { status: ingress.status, body: ingress.body };
   }
-  const compiled = await compileDeliveryGraph(parsed.graph);
-  if (!compiled.ok) {
-    app.log.warn("preview-delivery-graph rejected: compile", { errors: compiled.errors.length });
-    return {
-      status: 400,
-      body: {
-        ok: false,
-        error: `graph failed validation: ${compiled.errors.length} error(s)`,
-        errors: compiled.errors,
-      },
-    };
-  }
-
-  const digest = deliveryGraphDigest(compiled.bpmn);
-  const name =
-    typeof compiled.resolved.name === "string" && compiled.resolved.name.trim() !== ""
-      ? compiled.resolved.name.trim()
-      : null;
-  const preview = buildProposalPreview(compiled);
-  await stageProposal(
-    app.data,
-    buildProposalRow({
-      digest,
-      logicalKey: proposalLogicalKey(name, digest),
-      title: name,
-      graphJson: JSON.stringify(parsed.graph),
-      preview,
-      nodeCount: compiled.resolved.nodes.length,
-      humanNodeCount: compiled.humanNodes.length,
-      sideEffectCount: compiled.sideEffects.length,
-      sideEffecting: compiled.sideEffects.length > 0,
-    }),
-  );
 
-  app.log.info("preview-delivery-graph staged", {
-    nodes: compiled.resolved.nodes.length,
-    humanNodes: compiled.humanNodes.length,
-    sideEffects: compiled.sideEffects.length,
-    digest,
+  app.log.info("preview-delivery-graph compiled (not staged)", {
+    nodes: ingress.compiled.resolved.nodes.length,
+    humanNodes: ingress.compiled.humanNodes.length,
+    sideEffects: ingress.compiled.sideEffects.length,
+    digest: ingress.digest,
   });
-  return {
-    status: 200,
-    body: {
-      ok: true,
-      staged: true,
-      digest,
-      reviewUrl: proposalReviewUrl(digest),
-      ...(name !== null ? { title: name } : {}),
-      sideEffecting: compiled.sideEffects.length > 0,
-      nodeCount: compiled.resolved.nodes.length,
-      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 Delivery Graphs page renders these so the operator sees WHERE it
-      // parks on a person and WHAT it will do — the "preview before dispatch" principle made visible.
-      humanNodes: compiled.humanNodes,
-      sideEffects: compiled.sideEffects,
-    },
-  };
+  return { status: 200, body: buildTextPreviewBody(ingress, { staged: false, includeBpmn: true }) };
 });