@nanobpm/nano-workforce 0.121.0 → 0.123.0

package/app/mergesPerDay.test.ts

@@ -1,16 +1,14 @@
-// Read-model derivation + projection test for the merged-per-day throughput chart (issue #344).
+// Read-model derivation test for the merged-per-day throughput chart (issue #344).
 //
-// `deriveMergesPerDay` is the single source of truth behind the denormalised `merges_per_day` table
-// the Velocity page reads. It must: count DISTINCT PRs per calendar day (a PR with several `merged`
-// audit rows on one day — an `already-merged` short-circuit or a retry — counts once); ignore
-// `queued`/`blocked` attempts entirely; order days ascending; carry a running burn-up `cumulative`;
-// and scale each day's `bar` against the busiest day. `pollMergesPerDay` must project that onto the
-// read table idempotently — a steady-state re-run writes nothing, and a day dropped from the audit is
-// pruned.
+// `deriveMergesPerDay` is the single source of truth the `merges_per_day_view` VIEW (062) mirrors —
+// the worker-maintained `merges_per_day` table + its `pollMergesPerDay` write-path were RETIRED (epic
+// #412). It must: count DISTINCT PRs per calendar day (a PR with several `merged` audit rows on one
+// day — an `already-merged` short-circuit or a retry — counts once); ignore `queued`/`blocked`
+// attempts entirely; order days ascending; carry a running burn-up `cumulative`; and scale each day's
+// `bar` against the busiest day.
 import { test } from "node:test";
 import { assert, assertEquals } from "#test-assert";
-import type { DataLayer } from "@nanobpm/urban";
-import { deriveMergesPerDay, type MergeAuditRow, pollMergesPerDay } from "./mergesPerDay.ts";
+import { deriveMergesPerDay, type MergeAuditRow } from "./mergesPerDay.ts";
 
 // The bucketing is now LOCAL-calendar-day (issue #361: use the viewer's timezone, not UTC). The
 // derivation buckets in an explicit IANA `timeZone` argument (via `Intl.DateTimeFormat`), so these
@@ -19,49 +17,6 @@ import { deriveMergesPerDay, type MergeAuditRow, pollMergesPerDay } from "./merg
 // reorder unrelated date-handling tests. The UTC-based assertions pass `"UTC"`; the
 // timezone-specific ones pass the zone they exercise.
 
-// A tiny in-memory record gateway (all/find/insert/update/delete), mirroring the fake-app style used
-// across the app tests (see app/delivery.test.ts), enough to exercise the `pollMergesPerDay`
-// projection.
-function memData(): { data: DataLayer; stores: Record<string, any[]>; writes: () => number } {
-  const stores: Record<string, any[]> = {};
-  let writes = 0;
-  function tbl(name: string, pk = "id") {
-    const rows = (stores[name] ??= [] as any[]);
-    return {
-      async all() {
-        return rows.slice();
-      },
-      async get(id: any) {
-        return rows.find((r) => r[pk] === id);
-      },
-      async find(where: any = {}) {
-        return rows.filter((r) => Object.entries(where).every(([k, v]) => r[k] === v));
-      },
-      async insert(row: any) {
-        writes++;
-        rows.push({ ...row });
-        return row[pk];
-      },
-      async update(id: any, patch: any) {
-        writes++;
-        const r = rows.find((row) => row[pk] === id);
-        if (r) Object.assign(r, patch);
-        return 1;
-      },
-      async delete(id: any) {
-        const i = rows.findIndex((row) => row[pk] === id);
-        if (i >= 0) {
-          writes++;
-          rows.splice(i, 1);
-        }
-        return 1;
-      },
-    };
-  }
-  const data = { table: (n: string, pk?: string) => tbl(n, pk) } as any as DataLayer;
-  return { data, stores, writes: () => writes };
-}
-
 const merged = (pr_key: string, at: string): MergeAuditRow => ({ pr_key, outcome: "merged", at });
 
 test("counts DISTINCT merged PRs per calendar day", () => {
@@ -216,42 +171,3 @@ test("an invalid IANA timeZone falls back to the host zone instead of throwing (
   assertEquals(days[0].merged, 1);
   assert(/^\d{4}-\d{2}-\d{2}$/.test(days[0].day));
 });
-
-test("pollMergesPerDay projects the aggregate onto merges_per_day", async () => {
-  const { data, stores } = memData();
-  stores.merges = [
-    { id: 1, pr_key: "o/r#1", outcome: "merged", at: "2026-01-01T09:00:00Z" },
-    { id: 2, pr_key: "o/r#1", outcome: "merged", at: "2026-01-01T09:05:00Z" }, // dup same day
-    { id: 3, pr_key: "o/r#2", outcome: "merged", at: "2026-01-02T09:00:00Z" },
-    { id: 4, pr_key: "o/r#3", outcome: "queued", at: "2026-01-02T09:10:00Z" }, // ignored
-  ];
-  await pollMergesPerDay(data, "UTC");
-  const rows = (stores.merges_per_day ?? []).slice().sort((x, y) => x.day.localeCompare(y.day));
-  assertEquals(rows.map((r) => [r.day, r.merged, r.cumulative]), [
-    ["2026-01-01", 1, 1],
-    ["2026-01-02", 1, 2],
-  ]);
-  for (const r of rows) assert(typeof r.updated_at === "string" && r.updated_at.length > 0);
-});
-
-test("pollMergesPerDay is idempotent — a steady-state re-run writes nothing", async () => {
-  const { data, stores, writes } = memData();
-  stores.merges = [{ id: 1, pr_key: "o/r#1", outcome: "merged", at: "2026-01-01T09:00:00Z" }];
-  await pollMergesPerDay(data, "UTC");
-  const afterFirst = writes();
-  assert(afterFirst > 0, "the first pass must project at least one row");
-  await pollMergesPerDay(data, "UTC");
-  assertEquals(writes(), afterFirst, "a steady-state re-run must not write");
-});
-
-test("pollMergesPerDay prunes a day that no longer derives from the audit", async () => {
-  const { data, stores } = memData();
-  stores.merges_per_day = [
-    { day: "2025-12-31", merged: 3, cumulative: 3, bar: "███", updated_at: "old" },
-  ];
-  stores.merges = [{ id: 1, pr_key: "o/r#1", outcome: "merged", at: "2026-01-01T09:00:00Z" }];
-  await pollMergesPerDay(data, "UTC");
-  const days = (stores.merges_per_day ?? []).map((r: any) => r.day);
-  assert(!days.includes("2025-12-31"), "a stale day must be pruned");
-  assert(days.includes("2026-01-01"), "the derived day must be present");
-});

package/app/mergesPerDay.ts

@@ -14,23 +14,18 @@
 //   SELECT date(at, 'localtime') AS day, COUNT(DISTINCT pr_key) AS merged
 //   FROM merges WHERE outcome = 'merged' GROUP BY date(at, 'localtime');
 //
-// Two halves, mirroring the `deriveDelivery`/`pollDelivery` and `deriveLineage`/`pollLineage`
-// convention:
+// The `deriveMergesPerDay` PURE function (issue #344), formerly the derive-half of the
+// `deriveMergesPerDay`/`pollMergesPerDay` split. The merges-per-day read model is now a DERIVED SQL
+// VIEW (`merges_per_day_view`, 062) — the worker-maintained `merges_per_day` table and its
+// `pollMergesPerDay` write-path were RETIRED (epic #412). This pure derivation stays: it is the
+// single source of truth the view's SQL mirrors, and is still exercised by its unit tests +
+// the view's read-model guard.
 //   • `deriveMergesPerDay` — a PURE function: merge audit rows → one ordered `MergeDay` per calendar
 //     day (merged count, burn-up cumulative, a proportional bar string). No I/O, fully tested. Counts
 //     `COUNT(DISTINCT pr_key)` — a PR with several `merged` rows on one day (an `already-merged`
 //     short-circuit or retry) counts once — and ignores `queued`/`blocked` rows entirely.
-//   • `pollMergesPerDay` — the gateway glue: read the `merges` rows and project them onto the
-//     `merges_per_day` read table (051_merges_per_day.sql) the schema-driven Velocity page binds. A
-//     denormalised flat table because Urban's datasource cannot read a SQL VIEW (gateway.ts
-//     `schema()` whitelists `type='table'` only — same reason `lineage_threads`/`plans.delivery` are
-//     flat tables). Writes only when a day's projection actually changes, so a steady-state pass is a
-//     no-op.
-import type { DataLayer } from "@nanobpm/urban";
 
-const now = () => new Date().toISOString();
-
-/** The subset of a `merges` audit row (004_merge.sql) the projection reads. */
+/** The subset of a `merges` audit row (004_merge.sql) the derivation reads. */
 export interface MergeAuditRow {
   pr_key: string;
   outcome: string;
@@ -166,51 +161,3 @@ export function deriveMergesPerDay(rows: readonly MergeAuditRow[], timeZone?: st
   }
   return out;
 }
-
-/** The denormalised read-table row `pollMergesPerDay` projects, one per calendar day. */
-interface MergesPerDayRow extends MergeDay {
-  updated_at: string;
-}
-
-const mergesPerDay = (data: DataLayer) => data.table<MergesPerDayRow>("merges_per_day", "day");
-const mergesAudit = (data: DataLayer) => data.table<MergeAuditRow>("merges", "id");
-
-/** Idempotent read-model pass: recompute merged-per-day from the `merges` audit table and denormalise
- * it onto the `merges_per_day` read table the Velocity page reads. Additive/derived only — never
- * touches `merges`. Upserts a day only when its projection actually changes (so a steady-state pass is
- * a no-op) and prunes any stale day row that no longer derives (defensive — days are append-only in
- * practice, but a purge/rewrite of the audit must not leave a phantom). Buckets in `timeZone` (an
- * IANA zone) when given; the production caller omits it to use the host's resolved zone. */
-export async function pollMergesPerDay(data: DataLayer, timeZone?: string): Promise<void> {
-  try {
-    // Only `outcome === "merged"` rows contribute to the aggregate, so filter at the read rather than
-    // scanning queued/blocked rows as the audit grows (deriveMergesPerDay ignores non-merged rows too).
-    const audit = await mergesAudit(data).find({ outcome: "merged" });
-    const want = deriveMergesPerDay(audit, timeZone);
-    const wantByDay = new Map(want.map((d) => [d.day, d]));
-
-    const existing = await mergesPerDay(data).all();
-    const existingByDay = new Map(existing.map((r) => [r.day, r]));
-
-    for (const d of want) {
-      const cur = existingByDay.get(d.day);
-      if (!cur) {
-        await mergesPerDay(data).insert({ ...d, updated_at: now() });
-      } else if (cur.merged !== d.merged || cur.cumulative !== d.cumulative || cur.bar !== d.bar) {
-        await mergesPerDay(data).update(d.day, {
-          merged: d.merged,
-          cumulative: d.cumulative,
-          bar: d.bar,
-          updated_at: now(),
-        });
-      }
-    }
-
-    // Prune any projected day that no longer derives from the audit trail.
-    for (const r of existing) {
-      if (!wantByDay.has(r.day)) await mergesPerDay(data).delete(r.day);
-    }
-  } catch (err) {
-    console.error(`[poller] merges-per-day: ${err}`);
-  }
-}

package/app/plan.ts

@@ -12,7 +12,6 @@
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
 import { blackboardUrl, mintBlackboardToken, renderCoordinationBrief } from "./blackboard.ts";
 import { capsWaitTimeout, DEFAULT_CAPS_WAIT_TIMEOUT } from "./capsWait.ts";
-import { deriveEpicBucket, epicIsAcknowledgeable } from "./delivery.ts";
 import { EPIC_PHASE } from "./epicPhase.ts";
 import { DEFAULT_ESCALATION_SLA_TIMEOUT, escalationSlaTimeout } from "./escalationSla.ts";
 import {
@@ -74,18 +73,11 @@ export interface Plan {
   // Wave-merge barrier (007_wave_gate.sql): the wave index whose PRs the plan is currently
   // waiting to see MERGED before dispatching the next wave, or null when not parked at the barrier.
   gate_wave: number | null;
-  // Operator-visibility wave progress (022_plan_wave_progress.sql, #137): denormalised so the
-  // epics-index can show wave X/N at a glance. `wave_count` is the total waves (N); `current_wave`
-  // is the 0-based index of the wave the fleet is actively implementing (advanced by select-wave,
-  // pinned to wave_count-1 on completion). Display-only — never gates control flow. NULL until the
-  // plan is dispatched with tasks.
-  wave_count: number | null;
-  current_wave: number | null;
-  // Pre-formatted 1-based "X/N" progress string for the epics-index at-a-glance column
-  // (022_plan_wave_progress.sql, #137). The dataGrid has no per-cell templating (nano-ide#214),
-  // so this is projected alongside the numeric columns by the same worker writes. NULL until
-  // dispatched with tasks.
-  wave_label: string | null;
+  // Operator-visibility wave progress is now a DERIVED read model (epic #412): the `wave_count` /
+  // `current_wave` / `wave_label` columns (022_plan_wave_progress.sql) were RETIRED — the pages read
+  // them from the `plan_wave_label` / `plan_read_model` SQL VIEWs (060/061), and `pollWaitGate`
+  // derives "has the epic fanned out?" at read time from `plan_tasks`. There is no write-path and no
+  // stored column any more, so nothing on `plans` denormalises wave progress.
   // Per-plan capability token for the coordination blackboard (009_plan_blackboard.sql, #51).
   // Minted at plan start; baked into the blackboard URL handed to implementer agents. NULL for
   // plans created before the blackboard shipped.
@@ -96,13 +88,13 @@ export interface Plan {
   // admission); the column stays NULLABLE ONLY to grandfather pre-ADR-0003 / in-flight rows that
   // carry NULL — those must remain readable, so do NOT add a NOT NULL migration.
   base_branch: string | null;
-  // Derived epic delivery signal (029_plan_delivery.sql, #171): separates "fan-out dispatched to
-  // convergence" (status=done) from "all slice PRs actually merged". Recomputed idempotently by the
-  // poller's `pollDelivery` pass by joining each plan_tasks.pr_key → pull_requests.status — never
-  // written by the plan lifecycle. `delivery` is 'converging' | 'landed' | NULL (see deriveDelivery
-  // in app/service.ts); `delivery_label` is the human rollup for the epic detail view. Display-only.
-  delivery: string | null;
-  delivery_label: string | null;
+  // The derived epic delivery signal (029_plan_delivery.sql) was RETIRED as a stored column (epic
+  // #412): `delivery` / `delivery_label` are now a DERIVED SQL VIEW (`plan_delivery` /
+  // `plan_read_model`, 061), computed from the SAME pure `deriveDelivery`/`TERMINAL_STATUSES`
+  // (app/delivery.ts). The pages read them off the view; the pollers that still need the signal
+  // (`pollPromotion` for `isPromotable`) recompute it at
+  // read time via `deriveDelivery`, as does the `plan_read_model` VIEW's bucket derivation (074).
+  // There is no stored column and no write-path any more.
   // Derived epic domain phase (038_plan_epic_phase.sql, #261): the epic's own lifecycle phase —
   // Planning / Reviewing / Implementing (wave n/t) / Trial merging / Finalizing / Dispatched —
   // projected at write time from plan-fanout.bpmn's named activities (app/epicPhase.ts), so the epic
@@ -120,16 +112,18 @@ export interface Plan {
   //                       which has nothing to promote). Display-only; projected by the poller.
   promotion_pr: string | null;
   promotion_state: string | null;
-  // Active/History partition + operator tick-off (044_plan_list_bucket.sql, #298). Derived,
-  // write-time-projected by the `plans` gateway (below) from the pure `deriveEpicBucket` /
-  // `epicIsAcknowledgeable` helpers (app/delivery.ts) — never written by the plan lifecycle or a
-  // poller directly. Bucket epics on the derived `delivery` rollup, not raw `status`, so a `done`
-  // epic still converging — or landed-but-unpromoted — does not vanish from Active.
+  // Active/History partition + operator tick-off (044_plan_list_bucket.sql, #298). RETIRED as a
+  // write-time projection (issue #439): `list_bucket`/`ack_open` are now DERIVED by the
+  // `plan_read_model` VIEW (074) from `status`, `acknowledged_at`, and the derived `plan_delivery`
+  // signal — mirroring the pure `deriveEpicBucket` / `epicIsAcknowledgeable` (app/delivery.ts). The
+  // Epics pages bind the VIEW, never these base columns, so a raw-datasource `status` write (the
+  // `instanceTracking` reconciler) can no longer leave them stale, and the delivery-aware
+  // `pollPlanBucket` correction is retired (the VIEW sees the live signal). The base columns survive
+  // (expand/contract — a later migration drops them) but are no longer written or read.
   //   • acknowledged_at — NULL until an operator dismisses a resolved `done` epic (acknowledge-epic).
-  //   • list_bucket     — 'active' | 'history': the page tabs filter on this flat column.
-  //   • ack_open        — 1 | 0: 1 iff a resolved (`done`, not converging) but unacknowledged epic,
-  //                       gating the Dismiss button's `showWhenField`. NULL only on pre-#298 rows
-  //                       until `backfillPlanBuckets`.
+  //                       Still written; the sole live input the derivation reads off the row.
+  //   • list_bucket     — 'active' | 'history': VESTIGIAL base column; the pages filter the VIEW's.
+  //   • ack_open        — 1 | 0: VESTIGIAL base column; the pages gate Dismiss on the VIEW's.
   acknowledged_at: string | null;
   list_bucket: string | null;
   ack_open: number | null;
@@ -190,85 +184,19 @@ export const PLAN_TASK_STATUSES = [
 ] as const;
 export type PlanTaskStatus = typeof PLAN_TASK_STATUSES[number];
 
-export const plans = (data: DataLayer) => {
-  const table = data.table<Plan>("plans", "plan_key");
-  return new Proxy(table, {
-    get(target, prop) {
-      if (prop === "insert") {
-        return (row: Partial<Plan>) => target.insert({ ...row, ...projectPlanBucket(row) });
-      }
-      if (prop === "update") {
-        return async (id: unknown, patch: Partial<Plan>) => {
-          // Only re-read + reproject when the patch changes a projection input (status / delivery /
-          // acknowledged_at) or writes a derived column directly. A projection-irrelevant patch (e.g.
-          // an `updated_at`- or `wave_label`-only write — including the direct `data.table` writes in
-          // e.g. `app/retro.ts` that stamp `retro_started_at`) leaves the stored projection correct, so
-          // skip the extra `get` roundtrip and delegate straight. Any bucket-relevant write
-          // (status/delivery/acknowledged_at or a derived column) MUST go through this gateway to stay
-          // reprojected.
-          if (!patchAffectsPlanProjection(patch)) return target.update(id, patch);
-          const existing = await target.get(id);
-          const merged: Partial<Plan> = { ...existing, ...patch };
-          return target.update(id, { ...patch, ...projectPlanBucket(merged) });
-        };
-      }
-      // Delegate every other method straight through. Bind functions to the real target so the
-      // gateway's private class fields resolve — a Proxy `this` would not carry them.
-      const value = Reflect.get(target, prop, target);
-      return typeof value === "function" ? value.bind(target) : value;
-    },
-  });
-};
-
-/** The `plans` fields the bucket projection READS: a patch touching none of these (and none it
- * writes) cannot change `list_bucket`/`ack_open`, so the gateway skips the read-back+reproject. Kept
- * adjacent to {@link projectPlanBucket} so the two stay in lockstep. */
-const PLAN_PROJECTION_INPUT_KEYS: readonly (keyof Plan)[] = ["status", "delivery", "acknowledged_at"];
-
-/** The `plans` fields the bucket projection WRITES. Included in the reproject trigger so a caller who
- * writes a derived column directly (e.g. `list_bucket`/`ack_open`) can never bypass derivation: the
- * gateway re-reads, recomputes, and OVERRIDES the raw value with the canonical derived one. */
-const PLAN_PROJECTION_OUTPUT_KEYS: readonly (keyof Plan)[] = ["list_bucket", "ack_open"];
-
-/** True when a patch changes at least one field the bucket projection derives from OR one it writes —
- * i.e. the projection must be recomputed (mirrors feature.ts `patchAffectsProjection`). */
-function patchAffectsPlanProjection(patch: Partial<Plan>): boolean {
-  return (
-    PLAN_PROJECTION_INPUT_KEYS.some((k) => k in patch) ||
-    PLAN_PROJECTION_OUTPUT_KEYS.some((k) => k in patch)
-  );
-}
-
-/** Compute the write-time bucket projection columns for a merged `plans` row. Centralised so the
- * gateway is the ONE place `deriveEpicBucket` / `epicIsAcknowledgeable` are applied — the page, SQL,
- * pollers and workers never re-derive the mapping (AGENTS.md "derivation over duplication"). */
-function projectPlanBucket(row: Partial<Plan>): Partial<Plan> {
-  if (!row.status) return {};
-  return {
-    list_bucket: deriveEpicBucket(row.status, row.delivery ?? null, row.acknowledged_at ?? null),
-    ack_open:
-      epicIsAcknowledgeable(row.status, row.delivery ?? null) && (row.acknowledged_at ?? null) === null
-        ? 1
-        : 0,
-  };
-}
-
-/** Re-project every `plans` row through the gateway so rows written before migration 042 (whose
- * `list_bucket`/`ack_open` are NULL) get a correct Active/History bucket. Idempotent and safe to
- * re-run: it re-derives from each row's own stored fields, so a second pass is a no-op. Runs once at
- * boot (pollOnce) — the gateway keeps every future write fresh, so this only needs to catch legacy
- * rows. Returns the count actually stamped. Mirrors `backfillFeatureStages` (app/feature.ts). */
-export async function backfillPlanBuckets(data: DataLayer): Promise<number> {
-  const table = plans(data);
-  let stamped = 0;
-  for (const row of await table.all()) {
-    // Only touch rows the projection has never reached — a legacy row whose `list_bucket` is NULL.
-    if (row.list_bucket != null) continue;
-    await table.update(row.plan_key, projectPlanBucket(row));
-    stamped++;
-  }
-  return stamped;
-}
+/** The `plans` record gateway (keyed on `plan_key`) — a plain record table.
+ *
+ * The epic-bucket projection (`list_bucket`/`ack_open`) is NO LONGER a write-time projection here
+ * (issue #439): it is DERIVED by the `plan_read_model` VIEW (074) from each row's own `status` /
+ * `acknowledged_at` and the derived `plan_delivery` signal, mirroring `deriveEpicBucket` /
+ * `epicIsAcknowledgeable` (app/delivery.ts). The Epics pages bind the VIEW, never this table's stored
+ * derived columns. Removing the write-time projection closes the drift the framework
+ * `instanceTracking` reconciler opened (a raw-datasource `{status:"abandoned"}` write on a terminated
+ * instance bypassed the projecting gateway and froze the bucket) AND retires the read-time
+ * `pollPlanBucket` correction: the VIEW sees the live delivery signal, so a still-converging epic never
+ * offers Dismiss without a poller pass. The pure helpers stay the acknowledge-epic guard and the VIEW's
+ * test oracle (app/plansReadModel.test.ts). */
+export const plans = (data: DataLayer) => data.table<Plan>("plans", "plan_key");
 export const planTasks = (data: DataLayer) => data.table<PlanTask>("plan_tasks", "id");
 
 /** One dependency edge in the plan DAG (issue #20): `task_id` waits for `depends_on_task_id`.

package/app/plansReadModel.test.ts

@@ -19,7 +19,7 @@ import { DatabaseSync } from "node:sqlite";
 import { test } from "node:test";
 import { fileURLToPath } from "node:url";
 import { assert, assertEquals } from "#test-assert";
-import { deriveDelivery } from "./delivery.ts";
+import { deriveDelivery, deriveEpicBucket, epicIsAcknowledgeable } from "./delivery.ts";
 
 const MIG = (name: string) => readFileSync(fileURLToPath(new URL(`../db/migrations/${name}`, import.meta.url)), "utf8");
 const PAGE = (name: string) => JSON.parse(readFileSync(fileURLToPath(new URL(`../pages/${name}`, import.meta.url)), "utf8"));
@@ -34,7 +34,7 @@ function viewDb(): DatabaseSync {
        plan_key TEXT PRIMARY KEY, repo TEXT, issue_number INTEGER, issue_url TEXT, title TEXT,
        status TEXT, task_count INTEGER, process_key TEXT, outcome TEXT, created_at TEXT,
        updated_at TEXT, epic_phase TEXT, base_branch TEXT, wait_gate_label TEXT, bound_artifacts TEXT,
-       promotion_pr TEXT, promotion_state TEXT, list_bucket TEXT, ack_open INTEGER);
+       promotion_pr TEXT, promotion_state TEXT, acknowledged_at TEXT, list_bucket TEXT, ack_open INTEGER);
      CREATE TABLE plan_tasks (
        id INTEGER PRIMARY KEY, plan_key TEXT, task_index INTEGER, task_id TEXT, title TEXT,
        prompt TEXT, status TEXT, pr_key TEXT, summary TEXT, created_at TEXT, updated_at TEXT,
@@ -44,6 +44,9 @@ function viewDb(): DatabaseSync {
   db.exec(MIG("059_plan_wave_summary.sql"));
   db.exec(MIG("060_plan_wave_rollup.sql"));
   db.exec(MIG("061_plan_delivery_rollup.sql"));
+  // 074 redefines plan_read_model to DERIVE list_bucket/ack_open from status + acknowledged_at + the
+  // derived plan_delivery signal (issue #439), instead of reading the denormalised base columns.
+  db.exec(MIG("074_plan_read_model_derive_bucket.sql"));
   return db;
 }
 
@@ -66,10 +69,16 @@ const MISSING_PR_STATUS = "missing";
 // Insert a plan plus its tasks (and each task's PR, if any). PR keys are derived so the test rows
 // stay terse. Returns the flat `pull_requests.status` list `deriveDelivery` consumes (only tasks
 // that opened a PR), so the delivery assertions can cross-check the view against it.
-function addPlan(db: DatabaseSync, plan_key: string, status: string, tasks: SampleTask[]): string[] {
+function addPlan(
+  db: DatabaseSync,
+  plan_key: string,
+  status: string,
+  tasks: SampleTask[],
+  opts: { acknowledged_at?: string | null } = {},
+): string[] {
   db.prepare(
-    "INSERT INTO plans (plan_key, repo, issue_number, issue_url, status, task_count, updated_at, list_bucket) VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
-  ).run(plan_key, "o/r", 1, `https://gh/${plan_key}`, status, tasks.length, "2026-01-01T00:00:00Z", "active");
+    "INSERT INTO plans (plan_key, repo, issue_number, issue_url, status, task_count, updated_at, acknowledged_at, list_bucket) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
+  ).run(plan_key, "o/r", 1, `https://gh/${plan_key}`, status, tasks.length, "2026-01-01T00:00:00Z", opts.acknowledged_at ?? null, "active");
   const prStatuses: string[] = [];
   tasks.forEach((t, i) => {
     const prKey = t.pr || t.danglingPr ? `${plan_key}::pr${i}` : null;
@@ -107,6 +116,16 @@ function counts(db: DatabaseSync, plan_key: string): { prs_opened: number; prs_m
   return { ...r };
 }
 
+// The derived Active/History bucket flags the epics pages bind — read straight off `plan_read_model`
+// (074), plus the delivery signal the derivation folds in, so the assertions can cross-check the
+// VIEW against the pure `deriveEpicBucket` / `epicIsAcknowledgeable` oracles.
+function bucket(db: DatabaseSync, plan_key: string): { list_bucket: unknown; ack_open: unknown; delivery: string | null } {
+  const r = db
+    .prepare("SELECT list_bucket, ack_open, delivery FROM plan_read_model WHERE plan_key = ?")
+    .get(plan_key) as { list_bucket: unknown; ack_open: unknown; delivery: string | null };
+  return { ...r };
+}
+
 function waveLabel(db: DatabaseSync, plan_key: string): Record<string, unknown> | undefined {
   const r = db.prepare("SELECT wave_count, current_wave, wave_label FROM plan_wave_label WHERE plan_key = ?").get(plan_key) as
     | Record<string, unknown>
@@ -259,4 +278,92 @@ test("the operator pages read the derived plan_read_model VIEW for the wave/deli
   assertEquals(byId("epic-plan").props.data.table, "plan_read_model");
   assert(/\{\{\s*wave_label\s*\}\}/.test(byId("wave-banner").props.header), "the banner surfaces wave_label");
   assertEquals(byId("wave-banner").props.body, "delivery_label", "the banner body is the delivery_label");
+
+  // Epic INDEX page (epic.page.json) — the standalone Epics grid must also read the derived VIEW, not
+  // the raw `plans` table. `plans` stays a valid schema table, so a regression here (reverting the
+  // binding) would leave every OTHER test green while the index silently resumed reading stale
+  // list_bucket/ack_open; this pins it (suppressed advisory epic.page.json — issue #439).
+  const epicIndex = PAGE("epic.page.json");
+  const epicPlans = (epicIndex.nodes ?? []).find((n: { id: string }) => n.id === "epic-plans");
+  assert(epicPlans, "epic index must keep the Epics grid");
+  assertEquals(epicPlans.props.data.table, "plan_read_model");
+});
+
+test("plan_read_model DERIVES list_bucket / ack_open from status + delivery + acknowledged_at, matching deriveEpicBucket / epicIsAcknowledgeable (issue #439)", () => {
+  const db = viewDb();
+  // done, still converging (a slice in flight): Active, Dismiss suppressed — never ticked off mid-flight.
+  const converging = addPlan(db, "o/r#conv", "done", [
+    { status: "opened", wave: 0, pr: { status: "merged" } },
+    { status: "opened", wave: 1, pr: { status: "converging" } },
+  ]);
+  // done, fully landed, unacknowledged: Active with Dismiss OPEN (ack_open=1).
+  const landed = addPlan(db, "o/r#land", "done", [
+    { status: "opened", wave: 0, pr: { status: "merged" } },
+    { status: "opened", wave: 0, pr: { status: "merged" } },
+  ]);
+  // done, landed AND acknowledged: History, Dismiss closed.
+  const acked = addPlan(
+    db,
+    "o/r#ack",
+    "done",
+    [{ status: "opened", wave: 0, pr: { status: "merged" } }],
+    { acknowledged_at: "2026-02-02T00:00:00Z" },
+  );
+  // resolved-not-landed (one abandoned), unacknowledged: delivery null → acknowledgeable, Active + Dismiss.
+  const resolved = addPlan(db, "o/r#res", "done", [
+    { status: "opened", wave: 0, pr: { status: "merged" } },
+    { status: "opened", wave: 0, pr: { status: "abandoned" } },
+  ]);
+  // live (dispatched) epic: Active, not acknowledgeable.
+  const live = addPlan(db, "o/r#live", "dispatched", [{ status: "opened", wave: 0, pr: { status: "converging" } }]);
+
+  for (const [plan_key, status, prStatuses, ackAt] of [
+    ["o/r#conv", "done", converging, null],
+    ["o/r#land", "done", landed, null],
+    ["o/r#ack", "done", acked, "2026-02-02T00:00:00Z"],
+    ["o/r#res", "done", resolved, null],
+    ["o/r#live", "dispatched", live, null],
+  ] as const) {
+    const b = bucket(db, plan_key);
+    const expectedDelivery = deriveDelivery(status, prStatuses).delivery;
+    assertEquals(b.delivery, expectedDelivery, `${plan_key}: delivery`);
+    // Cross-check the VIEW against the pure helpers — the SAME oracle the acknowledge-epic op guards on.
+    assertEquals(
+      b.list_bucket,
+      deriveEpicBucket(status, expectedDelivery, ackAt),
+      `${plan_key}: list_bucket must equal deriveEpicBucket`,
+    );
+    const expectedAckOpen = epicIsAcknowledgeable(status, expectedDelivery) && ackAt === null ? 1 : 0;
+    assertEquals(b.ack_open, expectedAckOpen, `${plan_key}: ack_open must equal epicIsAcknowledgeable`);
+  }
+
+  // Pin the human-visible outcomes so a derivation drift can't hide behind the cross-check.
+  assertEquals(bucket(db, "o/r#conv"), { list_bucket: "active", ack_open: 0, delivery: "converging" });
+  assertEquals(bucket(db, "o/r#land"), { list_bucket: "active", ack_open: 1, delivery: "landed" });
+  assertEquals(bucket(db, "o/r#ack"), { list_bucket: "history", ack_open: 0, delivery: "landed" });
+  assertEquals(bucket(db, "o/r#res"), { list_bucket: "active", ack_open: 1, delivery: null });
+  assertEquals(bucket(db, "o/r#live"), { list_bucket: "active", ack_open: 0, delivery: null });
+});
+
+test("RED/GREEN GUARD: a RAW-datasource plans.status write (the instanceTracking reconciler bypass) leaves plan_read_model's bucket CONSISTENT", () => {
+  // Reproduce the framework `instanceTracking` reconciler class of bug: on a terminated process
+  // instance it writes `{status:"abandoned"}` to `plans` through the RAW datasource — bypassing the
+  // (now retired) projecting `plans` gateway. Under the OLD write-time projection the stored
+  // `list_bucket`/`ack_open` would freeze at their pre-terminal values; because they are now a VIEW
+  // over `status`, the read model stays correct with no write-path for any writer to leave stale.
+  const db = viewDb();
+  // A live epic mid-flight — Active, its (stale) stored projection says active/converging.
+  addPlan(db, "o/r#kill", "dispatched", [{ status: "opened", wave: 0, pr: { status: "converging" } }]);
+  assertEquals(bucket(db, "o/r#kill").list_bucket, "active");
+
+  // The reconciler flips status terminal via the RAW table — NOT the gateway. (Simulated with a raw
+  // UPDATE, exactly what the raw datasource emits.) It touches neither list_bucket nor ack_open.
+  db.prepare("UPDATE plans SET status = 'abandoned' WHERE plan_key = ?").run("o/r#kill");
+
+  // `abandoned` is a terminal non-`done` status: History, never acknowledgeable — matches the oracle.
+  const b = bucket(db, "o/r#kill");
+  assertEquals(b.list_bucket, deriveEpicBucket("abandoned", b.delivery, null), "list_bucket tracks status via the VIEW");
+  assertEquals(b.list_bucket, "history", "an abandoned epic is filed under History, not wedged in Active");
+  assertEquals(b.ack_open, epicIsAcknowledgeable("abandoned", b.delivery) ? 1 : 0);
+  assertEquals(b.ack_open, 0, "no phantom Dismiss on a reconciler-cancelled epic");
 });