@nanobpm/nano-workforce 0.136.0 → 0.137.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.137.0](https://github.com/nanobpm/nano-workforce/compare/v0.136.0...v0.137.0) (2026-08-24)
+
+### Features
+
+* single-source plan-family read models onto @nanobpm/urban defineRollup/defineReadModel ([#493](https://github.com/nanobpm/nano-workforce/issues/493)) ([#512](https://github.com/nanobpm/nano-workforce/issues/512)) ([2837636](https://github.com/nanobpm/nano-workforce/commit/283763689cc2d0780393efe7c51b09d7c2bef767)), closes [468/#469](https://github.com/468/nano-workforce/issues/469) [#2](https://github.com/nanobpm/nano-workforce/issues/2) [#503](https://github.com/nanobpm/nano-workforce/issues/503)
+
 ## [0.136.0](https://github.com/nanobpm/nano-workforce/compare/v0.135.0...v0.136.0) (2026-08-24)
 
 ### Features

package/app/delivery.ts

@@ -3,13 +3,38 @@
 // without importing `service.ts` — which imports `pollLineage` back from `lineage.ts` and would
 // otherwise form a `service.ts` ↔ `lineage.ts` module cycle (fragile in ESM). This is the single
 // source of truth for both; `service.ts` re-uses it and remains free to import `pollLineage`.
+//
+// ADR-0065 / issue #493. `deriveDelivery`/`deriveEpicBucket`/`epicIsAcknowledgeable` are no longer
+// hand-authored oracles: they are now THIN ADAPTERS over the ONE `plan_read_model` declaration
+// (app/planReadModel.ts) and the `plan_delivery_counts` rollup (app/planRollups.ts). Each routes
+// through the framework's runtime backend — `planDeliveryCounts.reduce` (the TS group-reduce) for the
+// slice-PR counts, and `planReadModel.evaluate` (the TS derivation) for the per-row `delivery` /
+// `list_bucket` / `ack_open` signals — so these façades and the superseding SQLite VIEWs (migrations
+// 082/083) compute byte-identical values by construction, guarded by `assertReadModelParity` /
+// `assertRollupParity` (app/planReadModel.test.ts). Only the pre-formatted `label` display string is
+// still assembled here (D3 — display formatting stays out of the framework AST).
 
-/** A PR is "done" in exactly these states; everything else (converging, waiting_review,
- * escalated, and the merge-stage waiting_deps/waiting_merge/waiting_lane/queued) is in flight. `converged`
+import { TERMINAL_STATUSES } from "./deliveryStatuses.ts";
+import {
+  DELIVERY_COUNTS_LOOKUP,
+  EFFECTIVE_STATUS_COLUMN,
+  planReadModel,
+  WAVE_PROGRESS_LOOKUP,
+} from "./planReadModel.ts";
+import { PR_TRACKING_RELATION, planDeliveryCounts } from "./planRollups.ts";
+
+/** The synthetic correlation key threaded through the adapters: the base row's `plan_key` and each
+ * synthesised slice `plan_tasks`/`plan_delivery_counts` row share this value so the compiled rollup
+ * lookup / group-reduce correlate exactly as they do on real rows (mirrors app/stage.ts `SELF_KEY`). */
+const SELF_KEY = "self";
+
+/** The PR statuses that are TERMINAL for delivery — re-exported from the canonical leaf module
+ * (app/deliveryStatuses.ts) that BOTH this façade's consumers and the `plan_delivery_counts` rollup
+ * (app/planRollups.ts) read, so the SQL VIEW counts and the TS adapters can never drift. `converged`
  * is terminal only in review-only mode (AUTO_MERGE off); with auto-merge on, a converged PR
- * transitions into the merge stage and lands as `merged`. The status endpoint and the cancel
- * guard both key off this set. */
-export const TERMINAL_STATUSES: readonly string[] = ["converged", "merged", "abandoned"];
+ * transitions into the merge stage and lands as `merged`. The status endpoint and the cancel guard
+ * both key off this set. */
+export { TERMINAL_STATUSES };
 
 /** The derived epic delivery signal (issue #171). Distinct from `plan.status`: `status = done`
  * means "the fan-out finished and ≥1 slice opened a PR, dispatched to convergence" (record-results
@@ -41,38 +66,35 @@ export function deriveDelivery(
   planStatus: string,
   prStatuses: readonly string[],
 ): DeliveryRollup {
-  const prsOpened = prStatuses.length;
-  let prsMerged = 0;
-  let prsInFlight = 0;
-  for (const s of prStatuses) {
-    if (s === "merged") prsMerged++;
-    else if (!TERMINAL_STATUSES.includes(s)) prsInFlight++;
-  }
-  // `delivery` is only meaningful once the fan-out has been dispatched (`status = done`) and at
-  // least one slice PR exists; otherwise there is nothing to have landed yet.
-  if (planStatus !== "done" || prsOpened === 0) {
-    return { delivery: null, label: null, prsOpened, prsMerged, prsInFlight };
-  }
-  if (prsInFlight > 0) {
-    return {
-      delivery: "converging",
-      label: `${prsMerged}/${prsOpened} slices merged, ${prsInFlight} converging`,
-      prsOpened,
-      prsMerged,
-      prsInFlight,
-    };
-  }
-  if (prsMerged === prsOpened) {
-    return {
-      delivery: "landed",
-      label: `${prsOpened}/${prsOpened} slices merged`,
-      prsOpened,
-      prsMerged,
-      prsInFlight,
-    };
-  }
-  // Every slice PR is terminal but not all merged (some abandoned/converged): resolved, not landed.
-  return { delivery: null, label: null, prsOpened, prsMerged, prsInFlight };
+  // Lower the caller's per-slice PR statuses into the two LEAF relations the `plan_delivery_counts`
+  // rollup reduces over (`plan_tasks` LEFT JOIN `pull_requests__tracking`): one opened slice per PR
+  // status. Callers already resolve the PR's terminal-folded `derived_status` (service.ts reads it via
+  // `prsTracking`), so it is fed under the tracking relation's `derived_status` column — the SAME
+  // column the managed VIEW joins — and the framework group-reduce folds the SAME three counts
+  // (`prs_opened`/`prs_merged`/`prs_in_flight`) the VIEW does; a missing/dangling PR status counts as
+  // in-flight, never false-`landed`.
+  const taskRows = prStatuses.map((_, i) => ({ plan_key: SELF_KEY, pr_key: `pr${i}`, wave: null, status: "opened" }));
+  const prRows = prStatuses.map((s, i) => ({ pr_key: `pr${i}`, derived_status: s }));
+  const [counts] = planDeliveryCounts.reduce({ plan_tasks: taskRows, [PR_TRACKING_RELATION]: prRows });
+  const prsOpened = Number(counts?.prs_opened ?? 0);
+  const prsMerged = Number(counts?.prs_merged ?? 0);
+  const prsInFlight = Number(counts?.prs_in_flight ?? 0);
+
+  // Derive the `delivery` signal from the ONE `plan_read_model` declaration, feeding the folded counts
+  // as the `plan_delivery_counts` lookup's single candidate row (the TS twin of the VIEW's LEFT JOIN).
+  const raw = planReadModel.evaluate(
+    { plan_key: SELF_KEY, status: planStatus, [EFFECTIVE_STATUS_COLUMN]: planStatus, acknowledged_at: null },
+    undefined,
+    { [DELIVERY_COUNTS_LOOKUP]: counts ? [counts] : [], [WAVE_PROGRESS_LOOKUP]: [] },
+  ).delivery;
+  const delivery: Delivery | null = raw === "converging" || raw === "landed" ? raw : null;
+
+  // The pre-formatted human label stays hand-authored here (D3 — display formatting is out of the
+  // framework AST); it mirrors the `plan_read_model` VIEW's `delivery_label` display column (083).
+  let label: string | null = null;
+  if (delivery === "converging") label = `${prsMerged}/${prsOpened} slices merged, ${prsInFlight} converging`;
+  else if (delivery === "landed") label = `${prsOpened}/${prsOpened} slices merged`;
+  return { delivery, label, prsOpened, prsMerged, prsInFlight };
 }
 
 /** The `plan.status` values that mean the epic's fan-out lifecycle is still LIVE — the planner is
@@ -108,16 +130,8 @@ export function deriveEpicBucket(
   delivery: string | null | undefined,
   acknowledgedAt: string | null | undefined,
 ): "active" | "history" {
-  if (EPIC_LIVE_STATUSES.some((s) => s === status)) return "active";
-  if (status === "done") {
-    // A still-`converging` epic is Active regardless of any (stray) acknowledged_at — it is genuinely
-    // working and is not acknowledgeable, so it can never be ticked off mid-flight (fail-closed).
-    if (delivery === "converging") return "active";
-    // Otherwise `done` — landed or resolved-not-landed/poller-pending (`delivery = null`): stay Active
-    // until the operator dismisses it, so a just-`done` epic never flickers into History.
-    return (acknowledgedAt ?? null) === null ? "active" : "history";
-  }
-  return "history";
+  const raw = evalEpicRow(status, delivery, acknowledgedAt).list_bucket;
+  return raw === "active" ? "active" : "history";
 }
 
 /** True iff an epic carries the operator "Dismiss" (acknowledge) affordance — a `done` epic whose
@@ -133,5 +147,43 @@ export function epicIsAcknowledgeable(
   status: string,
   delivery: string | null | undefined,
 ): boolean {
-  return status === "done" && delivery !== "converging";
+  // The `ack_open` derivation folds in the `acknowledged_at IS NULL` gate; evaluate it with a null
+  // acknowledgement to isolate the "acknowledgeABLE" predicate (`done` ∧ resolved) from "ack OPEN".
+  return evalEpicRow(status, delivery, null).ack_open === 1;
+}
+
+/** Evaluate the `plan_read_model` per-row derivations (`list_bucket`/`ack_open`) for an epic whose
+ * effective status, already-computed `delivery`, and acknowledgement the caller supplies. The model
+ * recomputes `delivery` internally from its `plan_delivery_counts` lookup + base status, so — the twin
+ * of app/stage.ts's `openTaskRows` synthesis — we SYNTHESISE the lookup row + base status that make the
+ * model's internal `delivery` equal the passed value: `converging`/`landed` need a `done` base status
+ * with an in-flight / all-merged count row; a null/other `delivery` needs an empty count (`prs_opened =
+ * 0` ⇒ the model's first CASE arm ⇒ null). The status-classifying arms read the effective status under
+ * `derived_status`, so the caller's `status` is fed there verbatim. */
+function evalEpicRow(
+  status: string,
+  delivery: string | null | undefined,
+  acknowledgedAt: string | null | undefined,
+): Record<string, unknown> {
+  const merged = delivery === "landed";
+  const inFlight = delivery === "converging";
+  const opened = merged || inFlight;
+  const dcRow = {
+    plan_key: SELF_KEY,
+    prs_opened: opened ? 1 : 0,
+    prs_merged: merged ? 1 : 0,
+    prs_in_flight: inFlight ? 1 : 0,
+  };
+  return planReadModel.evaluate(
+    {
+      plan_key: SELF_KEY,
+      // Force the model's internal `delivery` to the passed value: a `done` base status enables the
+      // non-null arms for converging/landed; any status with a zero-opened count folds to null.
+      status: opened ? "done" : status,
+      [EFFECTIVE_STATUS_COLUMN]: status,
+      acknowledged_at: acknowledgedAt ?? null,
+    },
+    undefined,
+    { [DELIVERY_COUNTS_LOOKUP]: [dcRow], [WAVE_PROGRESS_LOOKUP]: [] },
+  );
 }

package/app/deliveryStatuses.ts

@@ -0,0 +1,13 @@
+// The PR statuses that are TERMINAL for epic delivery — a slice PR in any of these is resolved (not
+// in flight). This is the ONE canonical set, factored into a dependency-neutral leaf module (imports
+// nothing) so BOTH sides of the single-sourced delivery derivation read the SAME value and can never
+// drift: the runtime adapters + consumers via `app/delivery.ts` (which re-exports it as
+// `TERMINAL_STATUSES`), and the `plan_delivery_counts` / `plan_wave_counts` rollups' in-flight fold via
+// `app/planRollups.ts`. Adding or removing a terminal state here changes both the SQL VIEW counts and
+// the TS reduce at once.
+//
+// `converged` is terminal only in review-only mode (AUTO_MERGE off); with auto-merge on, a converged PR
+// transitions into the merge stage and lands as `merged`. `merged` is the landed state; `abandoned` is
+// the resolved-not-landed state. Everything else (converging, waiting_review, escalated, and the
+// merge-stage waiting_deps/waiting_merge/waiting_lane/queued) is in flight.
+export const TERMINAL_STATUSES: readonly string[] = ["converged", "merged", "abandoned"];