@nanobpm/nano-workforce 0.119.0 → 0.120.0

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+# [0.120.0](https://github.com/nanobpm/nano-workforce/compare/v0.119.0...v0.120.0) (2026-08-22)
+
+
+### Features
+
+* **lineage:** derive view-expressible lineage_threads columns via SQL VIEW ([#437](https://github.com/nanobpm/nano-workforce/issues/437)) ([f25c824](https://github.com/nanobpm/nano-workforce/commit/f25c824bf9c72c3757a58794065a5c86b208dbe0)), closes [nano-ide#424](https://github.com/nano-ide/issues/424) [nanobpm/nano-workforce#412](https://github.com/nanobpm/nano-workforce/issues/412)
+* **velocity:** back merged-per-day with a SQL VIEW, repoint Velocity page ([#412](https://github.com/nanobpm/nano-workforce/issues/412)) ([#436](https://github.com/nanobpm/nano-workforce/issues/436)) ([5be81e4](https://github.com/nanobpm/nano-workforce/commit/5be81e466f2593622ae837d6e63b00f0287c305d)), closes [nano-ide#424](https://github.com/nano-ide/issues/424) [#411](https://github.com/nanobpm/nano-workforce/issues/411) [#361](https://github.com/nanobpm/nano-workforce/issues/361)
+
 # [0.119.0](https://github.com/nanobpm/nano-workforce/compare/v0.118.2...v0.119.0) (2026-08-22)
 
 

package/app/lineage.ts

@@ -330,6 +330,31 @@ export interface LineageThreadRow {
 const lineageThreads = (data: DataLayer) =>
   data.table<LineageThreadRow>("lineage_threads", "root_request_key");
 
+/** Read-only handle on the `lineage_thread_view` VIEW (migration 064) the Lineage page now binds.
+ *  Same shape as `LineageThreadRow`: the view PASSES THROUGH the procedural frontier columns from
+ *  `lineage_threads` (`stage`/`stage_label`/`process_key`/`pr_keys`/`pr_count`/`active`/timestamps)
+ *  and DERIVES the view-expressible identity columns (`kind`, `issue_url`, and an epic/feature
+ *  thread's `title`) from the `plans`/`feature_runs` origin joins — the single source of truth,
+ *  eliminating those columns' drift surface (epic #412). A self-rooted PR's `title` falls back to
+ *  the poller-written value, since it is a procedural representative-PR pick. */
+const lineageThreadView = (data: DataLayer) =>
+  data.table<LineageThreadRow>("lineage_thread_view", "root_request_key");
+
+/** All lineage threads off the same `lineage_thread_view` VIEW the Lineage page binds, in this
+ *  module's own active-frontier-first, then-by-key stable order (matching {@link listLineage}) —
+ *  NOT the page datasource's `orderBy: updated_at desc` + tab-specific `active` filter, which the
+ *  page applies on top of this table. Additive: this reads the derived view rather than recomputing
+ *  via {@link collectThreads}, so it reflects the identity columns' single source of truth (origin
+ *  joins) while the frontier columns come through from the still-poller-written `lineage_threads`. */
+export async function listLineageView(data: DataLayer): Promise<LineageThreadRow[]> {
+  const rows = await lineageThreadView(data).all();
+  return rows.sort(
+    (a, b) =>
+      Number(b.active) - Number(a.active) ||
+      a.root_request_key.localeCompare(b.root_request_key),
+  );
+}
+
 function toLineagePr(row: PrRow): LineagePr {
   return {
     prKey: row.pr_key,

package/app/mergesPerDayView.test.ts

@@ -0,0 +1,166 @@
+// Coverage for the merged-per-day VIEW that retires the denormalised `merges_per_day` table
+// (epic #412; the read model originally shipped in issue #344 / 051_merges_per_day.sql).
+//
+// The whole point of #412 is that this aggregate — merged-per-day throughput + burn-up + a
+// pre-formatted proportional bar — is now a derived SQL VIEW (enabled by nano-ide#424) instead of a
+// worker-written flat table, so it is a single source of truth with no drift. This test therefore
+// exercises the REAL SQLite view (062_merges_per_day_view.sql applied to an in-memory DB, mirroring
+// migration053.test.ts / planWaveSummary.test.ts) and pins that it reproduces the previous
+// projection's EXACT values: the DISTINCT-per-day count, the ascending burn-up `cumulative`, and the
+// byte-for-byte pre-formatted `bar` string the Velocity `prose` renderer draws.
+//
+// `deriveMergesPerDay` (app/mergesPerDay.ts) is the pure function the retired `pollMergesPerDay`
+// write-path used, so it is the authoritative oracle for "what the table held". We assert the view
+// equals it over sample `merges` rows. Bucketing is local-calendar-day (issue #361 — the view uses
+// `date(at, 'localtime')`, which resolves against the host zone). To keep the SQLite `localtime`
+// bucketing and the JS oracle in lockstep WITHOUT mutating the process-global `process.env.TZ`
+// (which `node --test` runs concurrently across FILES, so a `TZ` flip could leak into the
+// timezone-specific assertions in app/mergesPerDay.test.ts), we drive the oracle with the SAME host
+// zone SQLite uses by omitting its `timeZone` argument — `deriveMergesPerDay(rows)` defaults to the
+// host zone. Both sides therefore bucket identically in any host zone, so no `day` string is
+// hard-coded.
+
+import { readFileSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import { test } from "node:test";
+import { fileURLToPath } from "node:url";
+import { assert, assertEquals } from "#test-assert";
+import { deriveMergesPerDay, type MergeAuditRow } from "./mergesPerDay.ts";
+
+const MIGRATION = fileURLToPath(new URL("../db/migrations/062_merges_per_day_view.sql", import.meta.url));
+
+/** A DB with the `merges` audit shape (004_merge.sql, FK-free like migration053.test.ts) + the view. */
+function viewDb(): DatabaseSync {
+  const db = new DatabaseSync(":memory:");
+  db.exec(
+    `CREATE TABLE merges (
+       id INTEGER PRIMARY KEY AUTOINCREMENT, pr_key TEXT NOT NULL, outcome TEXT NOT NULL,
+       method TEXT, detail TEXT, at TEXT NOT NULL);`,
+  );
+  db.exec(readFileSync(MIGRATION, "utf8"));
+  return db;
+}
+
+function seed(db: DatabaseSync, rows: readonly MergeAuditRow[]): void {
+  const ins = db.prepare("INSERT INTO merges (pr_key, outcome, at) VALUES (?, ?, ?)");
+  for (const r of rows) ins.run(r.pr_key, r.outcome, r.at);
+}
+
+/** The view's rows as `[day, merged, cumulative, bar]`, ordered like the Velocity page (day asc). */
+function view(db: DatabaseSync): Array<[string, number, number, string]> {
+  return (
+    db.prepare("SELECT day, merged, cumulative, bar FROM merges_per_day_view ORDER BY day").all() as Array<
+      Record<string, unknown>
+    >
+  ).map((r) => [r.day as string, Number(r.merged), Number(r.cumulative), r.bar as string]);
+}
+
+const merged = (pr_key: string, at: string): MergeAuditRow => ({ pr_key, outcome: "merged", at });
+
+test("merges_per_day_view reproduces the retired projection exactly (count, burn-up, bar)", () => {
+  const db = viewDb();
+  const rows: MergeAuditRow[] = [
+    // day A: 4 distinct PRs (the busiest day → widest bar), including a duplicate merged row.
+    merged("o/r#1", "2026-01-01T01:00:00Z"),
+    merged("o/r#2", "2026-01-01T02:00:00Z"),
+    merged("o/r#3", "2026-01-01T03:00:00Z"),
+    merged("o/r#4", "2026-01-01T04:00:00Z"),
+    merged("o/r#4", "2026-01-01T05:00:00Z"), // retry / already-merged short-circuit → counts once
+    // day B: 1 PR → short but visible bar.
+    merged("o/r#5", "2026-01-02T10:00:00Z"),
+    // day C: 2 PRs.
+    merged("o/r#6", "2026-01-03T10:00:00Z"),
+    merged("o/r#7", "2026-01-03T11:00:00Z"),
+    // non-merged attempts must be ignored entirely.
+    { pr_key: "o/r#8", outcome: "queued", at: "2026-01-02T12:00:00Z" },
+    { pr_key: "o/r#9", outcome: "blocked", at: "2026-01-03T12:00:00Z" },
+  ];
+  seed(db, rows);
+
+  const expected = deriveMergesPerDay(rows).map(
+    (d) => [d.day, d.merged, d.cumulative, d.bar] as [string, number, number, string],
+  );
+  assertEquals(view(db), expected);
+});
+
+test("merges_per_day_view bar: full glyph run for the busiest day, min one glyph for a lone merge", () => {
+  const db = viewDb();
+  seed(db, [
+    merged("o/r#1", "2026-01-01T01:00:00Z"),
+    merged("o/r#2", "2026-01-01T02:00:00Z"),
+    merged("o/r#3", "2026-01-01T03:00:00Z"),
+    merged("o/r#4", "2026-01-01T04:00:00Z"),
+    merged("o/r#5", "2026-01-02T01:00:00Z"),
+  ]);
+  const rows = view(db);
+  const [a, b] = rows;
+  assertEquals(a[3], "█".repeat(30), "the busiest day fills the configured bar width (30)");
+  assert(a[3].length > b[3].length, "the busier day draws a longer bar");
+  assert([...b[3]].length >= 1, "a day with any merge draws at least one glyph");
+  assertEquals(view(db), deriveMergesPerDay([
+    merged("o/r#1", "2026-01-01T01:00:00Z"),
+    merged("o/r#2", "2026-01-01T02:00:00Z"),
+    merged("o/r#3", "2026-01-01T03:00:00Z"),
+    merged("o/r#4", "2026-01-01T04:00:00Z"),
+    merged("o/r#5", "2026-01-02T01:00:00Z"),
+  ]).map((d) => [d.day, d.merged, d.cumulative, d.bar]));
+});
+
+test("merges_per_day_view is empty when no merges are recorded", () => {
+  const db = viewDb();
+  seed(db, [{ pr_key: "o/r#1", outcome: "queued", at: "2026-01-01T01:00:00Z" }]);
+  assertEquals(view(db), []);
+});
+
+test("merges_per_day_view buckets on the LOCAL calendar day, matching deriveMergesPerDay (issue #361)", () => {
+  // The view's `date(at, 'localtime')` and the oracle's default zone both resolve against the host
+  // zone, so two merges either side of a local-day boundary bucket identically on both sides — no
+  // matter which host zone the suite runs under.
+  const db = viewDb();
+  const rows: MergeAuditRow[] = [
+    merged("o/r#1", "2026-01-01T23:30:00Z"),
+    merged("o/r#2", "2026-01-02T00:30:00Z"),
+  ];
+  seed(db, rows);
+  assertEquals(view(db), deriveMergesPerDay(rows).map((d) => [d.day, d.merged, d.cumulative, d.bar]));
+});
+
+// A tiny deterministic PRNG (mulberry32) so the property check runs the SAME audit rows every time —
+// non-determinism (`Math.random()`) would make a failure impossible to reproduce (see "no flaky
+// tests" in AGENTS.md). Seeded once with a fixed constant.
+function mulberry32(seed: number): () => number {
+  let a = seed >>> 0;
+  return () => {
+    a = (a + 0x6d2b79f5) >>> 0;
+    let t = a;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+test("merges_per_day_view reproduces the projection across many random audits (property check)", () => {
+  const db = viewDb();
+  const outcomes = ["merged", "merged", "merged", "queued", "blocked"];
+  const rand = mulberry32(0x9e3779b9); // fixed seed → the same 200 trials on every run.
+  for (let trial = 0; trial < 200; trial++) {
+    db.exec("DELETE FROM merges");
+    const rows: MergeAuditRow[] = [];
+    const n = 1 + Math.floor(rand() * 40);
+    for (let i = 0; i < n; i++) {
+      const day = 1 + Math.floor(rand() * 9);
+      const hh = String(Math.floor(rand() * 24)).padStart(2, "0");
+      rows.push({
+        pr_key: `o/r#${1 + Math.floor(rand() * 12)}`,
+        outcome: outcomes[Math.floor(rand() * outcomes.length)],
+        at: `2026-01-0${day}T${hh}:00:00Z`,
+      });
+    }
+    seed(db, rows);
+    assertEquals(
+      view(db),
+      deriveMergesPerDay(rows).map((d) => [d.day, d.merged, d.cumulative, d.bar]),
+      `random trial ${trial} diverged from the projection`,
+    );
+  }
+});

package/app/migration064.test.ts

@@ -0,0 +1,176 @@
+// Read-model guard for migration 064's `lineage_thread_view` VIEW (epic #412: retire the
+// worker-maintained `lineage_threads` denormalisation in favour of SQL VIEWs for the parts that are
+// clean rollups). Mirrors the derived-read-model test style of app/migration037.test.ts and
+// app/planWaveSummary.test.ts: apply the migration to a real in-memory SQLite DB and assert the
+// VIEW's output over sample rows — so this exercises the real view, not a re-implementation.
+//
+// The view DERIVES the view-expressible identity columns (`kind`, `issue_url`, and an epic/feature
+// thread's `title`) from the `plans` / `feature_runs` origin joins, and PASSES THROUGH the
+// procedural frontier columns (`stage`/`stage_label`/`process_key`/`pr_keys`/`pr_count`/`active`/
+// timestamps) from `lineage_threads`. It must reproduce EXACTLY what `pollLineage` wrote for the
+// migrated columns, so a future drop of those `lineage_threads` columns is behaviour-preserving.
+import { readFileSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import { test } from "node:test";
+import { fileURLToPath } from "node:url";
+import { assertEquals } from "#test-assert";
+
+const MIGRATION = fileURLToPath(new URL("../db/migrations/064_lineage_thread_view.sql", import.meta.url));
+
+/** A DB with the base shapes the view reads (`lineage_threads`, `plans`, `feature_runs`) plus the
+ *  view applied. The `lineage_threads` schema also models `kind`/`issue_url`, which the view does
+ *  NOT read (it derives them from the `plans`/`feature_runs` origin joins) — they are kept here so
+ *  `addThread` can write exactly what `pollLineage` denormalises. */
+function viewDb(): DatabaseSync {
+  const db = new DatabaseSync(":memory:");
+  db.exec(
+    `CREATE TABLE lineage_threads (
+       root_request_key TEXT PRIMARY KEY, kind TEXT, title TEXT, issue_url TEXT, stage TEXT,
+       stage_label TEXT, process_key TEXT, pr_keys TEXT, pr_count INTEGER, active INTEGER,
+       created_at TEXT, updated_at TEXT);
+     CREATE TABLE plans (plan_key TEXT PRIMARY KEY, title TEXT, issue_url TEXT);
+     CREATE TABLE feature_runs (feature_key TEXT PRIMARY KEY, title TEXT, issue_url TEXT);`,
+  );
+  db.exec(readFileSync(MIGRATION, "utf8"));
+  return db;
+}
+
+/** Insert a `lineage_threads` row exactly as `pollLineage` denormalises one. */
+function addThread(
+  db: DatabaseSync,
+  row: {
+    root_request_key: string;
+    kind: string;
+    title: string | null;
+    issue_url: string | null;
+    stage: string;
+    stage_label: string | null;
+    process_key: string | null;
+    pr_keys: string | null;
+    pr_count: number;
+    active: number;
+  },
+): void {
+  db.prepare(
+    `INSERT INTO lineage_threads (root_request_key, kind, title, issue_url, stage, stage_label,
+       process_key, pr_keys, pr_count, active, created_at, updated_at)
+     VALUES (@root_request_key, @kind, @title, @issue_url, @stage, @stage_label, @process_key,
+       @pr_keys, @pr_count, @active, 't0', 't1')`,
+  ).run(row);
+}
+
+test("lineage_thread_view derives kind/issue_url/title for an epic thread from the plans origin", () => {
+  const db = viewDb();
+  db.prepare("INSERT INTO plans (plan_key, title, issue_url) VALUES (?, ?, ?)").run(
+    "o/r#2",
+    "Epic: retire projections",
+    "https://github.com/o/r/issues/2",
+  );
+  // pollLineage wrote the same identity values (denormalised) alongside the procedural frontier.
+  addThread(db, {
+    root_request_key: "o/r#2",
+    kind: "epic",
+    title: "Epic: retire projections",
+    issue_url: "https://github.com/o/r/issues/2",
+    stage: "converging",
+    stage_label: "3/5 slices merged, 2 converging",
+    process_key: "P-epic",
+    pr_keys: '["o/r#20","o/r#21"]',
+    pr_count: 5,
+    active: 1,
+  });
+
+  const v = db
+    .prepare("SELECT * FROM lineage_thread_view WHERE root_request_key = ?")
+    .get("o/r#2") as Record<string, unknown>;
+  // Derived from the plans join — identical to what the poller denormalised.
+  assertEquals(v.kind, "epic");
+  assertEquals(v.title, "Epic: retire projections");
+  assertEquals(v.issue_url, "https://github.com/o/r/issues/2");
+  // Procedural frontier columns pass through unchanged from lineage_threads.
+  assertEquals(v.stage, "converging");
+  assertEquals(v.stage_label, "3/5 slices merged, 2 converging");
+  assertEquals(v.process_key, "P-epic");
+  assertEquals(v.pr_keys, '["o/r#20","o/r#21"]');
+  assertEquals(v.pr_count, 5);
+  assertEquals(v.active, 1);
+});
+
+test("lineage_thread_view derives kind/issue_url/title for a feature thread from the feature_runs origin", () => {
+  const db = viewDb();
+  db.prepare("INSERT INTO feature_runs (feature_key, title, issue_url) VALUES (?, ?, ?)").run(
+    "o/r#1",
+    "Feature: add widget",
+    "https://github.com/o/r/issues/1",
+  );
+  addThread(db, {
+    root_request_key: "o/r#1",
+    kind: "feature",
+    title: "Feature: add widget",
+    issue_url: "https://github.com/o/r/issues/1",
+    stage: "merged",
+    stage_label: "Merged",
+    process_key: "P-feat",
+    pr_keys: '["o/r#10"]',
+    pr_count: 1,
+    active: 0,
+  });
+
+  const v = db
+    .prepare("SELECT * FROM lineage_thread_view WHERE root_request_key = ?")
+    .get("o/r#1") as Record<string, unknown>;
+  assertEquals(v.kind, "feature");
+  assertEquals(v.title, "Feature: add widget");
+  assertEquals(v.issue_url, "https://github.com/o/r/issues/1");
+  assertEquals(v.stage, "merged");
+  assertEquals(v.active, 0);
+});
+
+test("lineage_thread_view self-roots an origin-less PR: kind 'pr', NULL issue_url, title falls back to the poller value", () => {
+  const db = viewDb();
+  // No plans / feature_runs row for this root — it is a human/webhook PR that is its own root.
+  addThread(db, {
+    root_request_key: "o/r#30",
+    kind: "pr",
+    title: "hotfix: bump dep",
+    issue_url: null,
+    stage: "converging",
+    stage_label: "Converging (round 2)",
+    process_key: "P-pr",
+    pr_keys: '["o/r#30"]',
+    pr_count: 1,
+    active: 1,
+  });
+
+  const v = db
+    .prepare("SELECT * FROM lineage_thread_view WHERE root_request_key = ?")
+    .get("o/r#30") as Record<string, unknown>;
+  assertEquals(v.kind, "pr");
+  // issue_url is always NULL for a self-rooted PR, exactly as deriveLineage sets it.
+  assertEquals(v.issue_url, null);
+  // The PR title is the procedural representative-PR pick, so it comes through from lineage_threads.
+  assertEquals(v.title, "hotfix: bump dep");
+  assertEquals(v.stage_label, "Converging (round 2)");
+});
+
+test("lineage_thread_view reproduces the migrated columns for every thread the poller wrote", () => {
+  const db = viewDb();
+  db.prepare("INSERT INTO plans (plan_key, title, issue_url) VALUES ('o/r#2', 'Epic', 'u-epic')").run();
+  db.prepare("INSERT INTO feature_runs (feature_key, title, issue_url) VALUES ('o/r#1', 'Feat', 'u-feat')").run();
+  const rows = [
+    { root_request_key: "o/r#2", kind: "epic", title: "Epic", issue_url: "u-epic", stage: "converging", stage_label: "…", process_key: "a", pr_keys: "[]", pr_count: 2, active: 1 },
+    { root_request_key: "o/r#1", kind: "feature", title: "Feat", issue_url: "u-feat", stage: "merged", stage_label: "Merged", process_key: "b", pr_keys: "[]", pr_count: 1, active: 0 },
+    { root_request_key: "o/r#30", kind: "pr", title: "PR", issue_url: null, stage: "opened", stage_label: "Opened", process_key: null, pr_keys: "[]", pr_count: 1, active: 1 },
+  ];
+  for (const r of rows) addThread(db, r);
+
+  // The view's migrated columns must equal what pollLineage denormalised, for all three kinds.
+  for (const r of rows) {
+    const v = db
+      .prepare("SELECT kind, title, issue_url FROM lineage_thread_view WHERE root_request_key = ?")
+      .get(r.root_request_key) as Record<string, unknown>;
+    assertEquals(v.kind, r.kind);
+    assertEquals(v.title, r.title);
+    assertEquals(v.issue_url, r.issue_url);
+  }
+});

package/app/planWaveSummary.test.ts

@@ -126,10 +126,12 @@ test("epic-detail projects the wave banner, the per-wave summary, and task→rep
   const page = JSON.parse(readFileSync(PAGE, "utf8"));
   const byId = (id: string) => page.nodes.find((n: { id: string }) => n.id === id);
 
-  // 1. The epic-level wave banner: a prose node reading wave_label + epic_phase off `plans`.
+  // 1. The epic-level wave banner: a prose node reading wave_label + epic_phase off the derived
+  //    `plan_read_model` VIEW (epic #412 — retiring the worker-maintained plans.wave_label column;
+  //    the banner now reads the single-source-of-truth view instead of the raw `plans` table).
   const banner = byId("wave-banner");
   assert(banner, "epic detail must show the epic-level wave banner");
-  assertEquals(banner.props.data.table, "plans");
+  assertEquals(banner.props.data.table, "plan_read_model");
   assert(
     banner.props.data.filter.some((f: { field: string; eqParam?: boolean }) => f.field === "plan_key" && f.eqParam),
     "the banner is scoped to this epic",

package/app/plansReadModel.test.ts

@@ -0,0 +1,262 @@
+// Read-model VIEW coverage for the plans-table wave (022) and delivery (029) projections (epic #412
+// — "Retire worker-maintained denormalized projections in favour of SQL VIEWs").
+//
+// Historically `plans.wave_count`/`current_wave`/`wave_label` (022_plan_wave_progress.sql) were
+// written by the wave workers, and `plans.delivery`/`delivery_label` (029_plan_delivery.sql) by
+// `pollDelivery` (app/service.ts) via the pure `deriveDelivery` (app/delivery.ts) — both denormalised
+// onto `plans` only because "Urban's datasource cannot read a SQL VIEW". That constraint is gone
+// (nano-ide#424), so 060/061 express the SAME projections as DERIVED views. This asserts the views
+// reproduce the previous projections' EXACT values — including the pre-formatted `wave_label` /
+// `delivery_label` display strings — over sample `plans` × `plan_tasks` × `pull_requests` rows, so
+// the wave-1 cleanup can drop the worker write-paths + columns with no behavioural change.
+//
+// The delivery assertions cross-check against the real `deriveDelivery` (the single source of truth
+// the poller used), not a re-implementation; the wave assertions pin the frontier derivation that
+// reproduces the workers' `current_wave` (record-plan starts at 0, advances per landed wave, pins to
+// wave_count-1 on completion).
+import { readFileSync } from "node:fs";
+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";
+
+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"));
+
+// A DB with the base `plans` / `plan_tasks` / `pull_requests` shapes the views read (the `plans`
+// columns `plan_read_model` projects, and the full `plan_tasks` shape 059's `plan_wave_tasks`
+// reads), plus 059→061 applied in order.
+function viewDb(): DatabaseSync {
+  const db = new DatabaseSync(":memory:");
+  db.exec(
+    `CREATE TABLE plans (
+       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);
+     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,
+       wave INTEGER, open_question TEXT, answer TEXT, draft_pr_key TEXT, corr_key TEXT);
+     CREATE TABLE pull_requests (pr_key TEXT PRIMARY KEY, url TEXT, status TEXT, process_key TEXT);`,
+  );
+  db.exec(MIG("059_plan_wave_summary.sql"));
+  db.exec(MIG("060_plan_wave_rollup.sql"));
+  db.exec(MIG("061_plan_delivery_rollup.sql"));
+  return db;
+}
+
+interface SampleTask {
+  status: string;
+  wave: number | null;
+  pr?: { status: string };
+  // A slice that OPENED a PR (so `pr_key` is set and it counts toward `prs_opened`) but whose
+  // `pull_requests` row is ABSENT — a DB desync. Mirrors `pollDelivery`'s `MISSING_PR_STATUS`
+  // sentinel: the LEFT JOIN yields `status IS NULL`, which `plan_delivery_counts` treats as
+  // in-flight (non-terminal), so it can never wrongly promote an epic to `landed`.
+  danglingPr?: boolean;
+}
+
+// Sentinel mirroring `pollDelivery`'s `MISSING_PR_STATUS` — the status fed to `deriveDelivery` for a
+// `pr_key` with no `pull_requests` row. Any non-terminal string works (it's counted as in-flight); it
+// exists only to keep the `deriveDelivery` cross-check aligned with the view's `status IS NULL` branch.
+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[] {
+  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");
+  const prStatuses: string[] = [];
+  tasks.forEach((t, i) => {
+    const prKey = t.pr || t.danglingPr ? `${plan_key}::pr${i}` : null;
+    db.prepare(
+      "INSERT INTO plan_tasks (plan_key, task_index, task_id, status, pr_key, wave) VALUES (?, ?, ?, ?, ?, ?)",
+    ).run(plan_key, i, `t${i}`, t.status, prKey, t.wave);
+    if (t.danglingPr) {
+      // Opened a PR (pr_key set → counts toward prs_opened) but NO `pull_requests` row: the DB desync
+      // `pollDelivery` feeds to `deriveDelivery` as MISSING_PR_STATUS (in-flight).
+      prStatuses.push(MISSING_PR_STATUS);
+    } else if (t.pr && prKey) {
+      db.prepare("INSERT INTO pull_requests (pr_key, url, status, process_key) VALUES (?, ?, ?, ?)").run(
+        prKey,
+        `https://gh/${prKey}`,
+        t.pr.status,
+        `P${i}`,
+      );
+      prStatuses.push(t.pr.status);
+    }
+  });
+  return prStatuses;
+}
+
+function delivery(db: DatabaseSync, plan_key: string): { delivery: unknown; delivery_label: unknown } {
+  return db.prepare("SELECT delivery, delivery_label FROM plan_delivery WHERE plan_key = ?").get(plan_key) as {
+    delivery: unknown;
+    delivery_label: unknown;
+  };
+}
+
+function counts(db: DatabaseSync, plan_key: string): { prs_opened: number; prs_merged: number; prs_in_flight: number } {
+  const r = db
+    .prepare("SELECT prs_opened, prs_merged, prs_in_flight FROM plan_delivery_counts WHERE plan_key = ?")
+    .get(plan_key) as { prs_opened: number; prs_merged: number; prs_in_flight: number };
+  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>
+    | undefined;
+  return r === undefined ? undefined : { ...r };
+}
+
+test("plan_delivery reproduces deriveDelivery exactly (converging / landed / not-done / resolved-not-landed / taskless)", () => {
+  const db = viewDb();
+  // A `done` epic with slices still in flight → converging.
+  const a = addPlan(db, "o/r#1", "done", [
+    { status: "opened", wave: 0, pr: { status: "merged" } },
+    { status: "opened", wave: 0, pr: { status: "merged" } },
+    { status: "opened", wave: 1, pr: { status: "converging" } },
+    { status: "blocked", wave: 1 },
+  ]);
+  // A `done` epic with every slice PR merged → landed.
+  const b = addPlan(db, "o/r#2", "done", [
+    { status: "opened", wave: 0, pr: { status: "merged" } },
+    { status: "opened", wave: 0, pr: { status: "merged" } },
+  ]);
+  // A `dispatched` (not-done) epic → no positive delivery signal yet, even with an open PR.
+  const c = addPlan(db, "o/r#3", "dispatched", [
+    { status: "opened", wave: 0, pr: { status: "converging" } },
+    { status: "pending", wave: 1 },
+    { status: "pending", wave: 2 },
+  ]);
+  // A `done` epic where every PR is terminal but not all merged (one abandoned) → resolved, NOT landed.
+  const d = addPlan(db, "o/r#4", "done", [
+    { status: "opened", wave: 0, pr: { status: "merged" } },
+    { status: "opened", wave: 0, pr: { status: "abandoned" } },
+  ]);
+  // A `planning` epic with no tasks → no PRs → null.
+  const e = addPlan(db, "o/r#5", "planning", []);
+
+  for (const [plan_key, status, prStatuses] of [
+    ["o/r#1", "done", a],
+    ["o/r#2", "done", b],
+    ["o/r#3", "dispatched", c],
+    ["o/r#4", "done", d],
+    ["o/r#5", "planning", e],
+  ] as const) {
+    const expected = deriveDelivery(status, prStatuses);
+    const row = delivery(db, plan_key);
+    assertEquals(row.delivery, expected.delivery, `${plan_key}: delivery`);
+    assertEquals(row.delivery_label, expected.label, `${plan_key}: delivery_label`);
+  }
+
+  // Pin the exact pre-formatted strings so a formatting drift can't hide behind the cross-check.
+  assertEquals(delivery(db, "o/r#1").delivery_label, "2/3 slices merged, 1 converging");
+  assertEquals(delivery(db, "o/r#2").delivery_label, "2/2 slices merged");
+  assertEquals(delivery(db, "o/r#4").delivery, null);
+});
+
+test("plan_delivery_counts pins the two subtle predicates: `converged` is terminal, a dangling pr_key is in-flight", () => {
+  const db = viewDb();
+  // `converged` is in TERMINAL_STATUSES (review-only mode): a `done` epic whose only remaining PR is
+  // `converged` (not `merged`) is resolved-not-landed. It must NOT count as in-flight — so delivery is
+  // NULL, never `converging`. This pins the hard-coded terminal set in the view's SQL against
+  // TERMINAL_STATUSES; drop `converged` from either and prs_in_flight becomes 1 here.
+  const conv = addPlan(db, "o/r#c", "done", [
+    { status: "opened", wave: 0, pr: { status: "merged" } },
+    { status: "opened", wave: 0, pr: { status: "converged" } },
+  ]);
+  assertEquals(counts(db, "o/r#c"), { prs_opened: 2, prs_merged: 1, prs_in_flight: 0 });
+  assertEquals(delivery(db, "o/r#c").delivery, null, "converged is terminal-not-merged → resolved, not landed");
+  assertEquals({ ...delivery(db, "o/r#c") }, { delivery: deriveDelivery("done", conv).delivery, delivery_label: deriveDelivery("done", conv).label });
+
+  // A dangling `pr_key` (task opened a PR but the `pull_requests` row is absent — the poller's
+  // MISSING_PR_STATUS desync). The LEFT JOIN yields `status IS NULL`, which the view's
+  // `p.status IS NULL OR …` branch counts as in-flight — so even though every OTHER PR merged, the
+  // epic stays `converging` and can never be wrongly promoted to `landed`.
+  const dangling = addPlan(db, "o/r#d", "done", [
+    { status: "opened", wave: 0, pr: { status: "merged" } },
+    { status: "opened", wave: 0, danglingPr: true },
+  ]);
+  assertEquals(counts(db, "o/r#d"), { prs_opened: 2, prs_merged: 1, prs_in_flight: 1 });
+  assertEquals(delivery(db, "o/r#d").delivery, "converging", "a dangling pr_key keeps the epic in flight (never landed)");
+  assertEquals({ ...delivery(db, "o/r#d") }, {
+    delivery: deriveDelivery("done", dangling).delivery,
+    delivery_label: deriveDelivery("done", dangling).label,
+  });
+});
+
+test("plan_wave_label reproduces the workers' wave_count / current_wave / wave_label projection", () => {
+  const db = viewDb();
+  // Wave 0 fully merged, wave 1 still converging → frontier is wave 1 (the gating wave). "2/2".
+  addPlan(db, "o/r#1", "done", [
+    { status: "opened", wave: 0, pr: { status: "merged" } },
+    { status: "opened", wave: 0, pr: { status: "merged" } },
+    { status: "opened", wave: 1, pr: { status: "converging" } },
+    { status: "blocked", wave: 1 },
+  ]);
+  // Single wave, all merged → frontier pins to the last index (0). "1/1".
+  addPlan(db, "o/r#2", "done", [
+    { status: "opened", wave: 0, pr: { status: "merged" } },
+    { status: "opened", wave: 0, pr: { status: "merged" } },
+  ]);
+  // Three waves, freshly dispatched (all in flight) → frontier is wave 0. "1/3".
+  addPlan(db, "o/r#3", "dispatched", [
+    { status: "opened", wave: 0, pr: { status: "converging" } },
+    { status: "pending", wave: 1 },
+    { status: "pending", wave: 2 },
+  ]);
+  // No levelized tasks → no wave rollup row (matches the workers leaving a taskless plan NULL).
+  addPlan(db, "o/r#5", "planning", []);
+
+  assertEquals(waveLabel(db, "o/r#1"), { wave_count: 2, current_wave: 1, wave_label: "2/2" });
+  assertEquals(waveLabel(db, "o/r#2"), { wave_count: 1, current_wave: 0, wave_label: "1/1" });
+  assertEquals(waveLabel(db, "o/r#3"), { wave_count: 3, current_wave: 0, wave_label: "1/3" });
+  assertEquals(waveLabel(db, "o/r#5"), undefined);
+});
+
+test("plan_read_model joins the derived wave + delivery projections onto the plans row", () => {
+  const db = viewDb();
+  addPlan(db, "o/r#1", "done", [
+    { status: "opened", wave: 0, pr: { status: "merged" } },
+    { status: "opened", wave: 1, pr: { status: "converging" } },
+  ]);
+  addPlan(db, "o/r#5", "planning", []);
+
+  const row = db.prepare("SELECT * FROM plan_read_model WHERE plan_key = ?").get("o/r#1") as Record<string, unknown>;
+  assertEquals(row.plan_key, "o/r#1");
+  assertEquals(row.status, "done");
+  assertEquals(row.list_bucket, "active");
+  assertEquals(row.wave_label, "2/2");
+  assertEquals(row.wave_count, 2);
+  assertEquals(row.current_wave, 1);
+  assertEquals(row.delivery, "converging");
+  assertEquals(row.delivery_label, "1/2 slices merged, 1 converging");
+
+  // A taskless plan still appears (LEFT JOINs), with the derived columns NULL.
+  const empty = db.prepare("SELECT wave_label, delivery, delivery_label FROM plan_read_model WHERE plan_key = ?").get("o/r#5") as Record<string, unknown>;
+  assertEquals({ ...empty }, { wave_label: null, delivery: null, delivery_label: null });
+});
+
+test("the operator pages read the derived plan_read_model VIEW for the wave/delivery cells", () => {
+  // Overview epics grid — binds the view and still surfaces wave_label + delivery_label.
+  const overview = PAGE("overview.page.json");
+  const epics = (overview.nodes ?? []).find((n: { id: string }) => n.id === "overview-epics");
+  assert(epics, "overview must keep the Active Epics grid");
+  assertEquals(epics.props.data.table, "plan_read_model");
+  const epicCols: string[] = epics.props.columns.map((c: { field: string }) => c.field);
+  assert(epicCols.includes("wave_label") && epicCols.includes("delivery_label"), "overview epics grid surfaces wave_label + delivery_label");
+
+  // Epic-detail wave banner + plan grid both read the view.
+  const detail = PAGE("epic-detail.page.json");
+  const byId = (id: string) => (detail.nodes ?? []).find((n: { id: string }) => n.id === id);
+  assertEquals(byId("wave-banner").props.data.table, "plan_read_model");
+  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");
+});

package/db/migrations/060_plan_wave_rollup.sql

@@ -0,0 +1,52 @@
+-- Wave-progress read model as a derived VIEW (epic #412 — retire worker-maintained projections).
+--
+-- 022_plan_wave_progress.sql denormalised `plans.wave_count` / `plans.current_wave` /
+-- `plans.wave_label` — a per-epic "wave X/N" at-a-glance projection — onto the `plans` row, written
+-- by the wave workers (`record-plan`, `select-wave`, `record-wave`). Its comment cites the sole
+-- reason it was a worker-maintained table rather than a VIEW: "Urban's datasource cannot read a SQL
+-- VIEW". That constraint is gone (nano-ide#424: `gateway.schema()` now introspects
+-- `type IN ('table','view')`), so — exactly like 059 did for the wave-summary rollup — this expresses
+-- the same projection as a DERIVED view: a single source of truth with NO write-path and no drift
+-- from `plan_tasks`.
+--
+-- Reuses 059's `plan_wave_counts` (one row per (plan_key, wave), with the six-way task partition,
+-- including `in_flight`) so the frontier can be derived purely, layered so each view stays a plain
+-- `CREATE VIEW <name> AS SELECT … FROM …` (no CTE / no select-list subquery) — which keeps them
+-- parseable by the static pages↔schema contract guard (scripts/pages-contract.test.ts).
+--
+--   • plan_wave_progress — one row per plan_key with the two numeric projections:
+--       - wave_count   = MAX(wave)+1 (the levelizer emits contiguous waves 0..N-1, so this equals
+--                        `app/waves.ts` `waveCount`). A plan with no LEVELIZED tasks contributes no
+--                        `plan_wave_counts` row, so it is absent here and reads NULL through the
+--                        downstream LEFT JOIN — matching the workers, which leave a taskless plan's
+--                        wave columns NULL.
+--       - current_wave = the live FRONTIER, derived (not process-state-tracked): the lowest wave
+--                        that still has an `in_flight` task (the wave the fleet is actively
+--                        implementing / the wave the merge-barrier is gating), else — once every
+--                        wave has settled (in_flight = 0 everywhere) — pinned to the last index
+--                        MAX(wave). This reproduces the workers' projection: `record-plan` starts it
+--                        at 0 (wave 0 is in flight), `record-wave`/`select-wave` advance it to the
+--                        next gating wave as each wave's PRs merge, and it pins to wave_count-1 on
+--                        completion (a finished epic reads N/N).
+--   • plan_wave_label    — the same two numbers PLUS `wave_label`, the PRE-FORMATTED 1-based "X/N"
+--                          display string (`(current_wave+1)/wave_count`) the epics-index and epic
+--                          banner render, because the dataGrid has no per-cell templating.
+--
+-- Forward-only, additive (a new read model; no schema change to any base table). The runner wraps
+-- each file in its own transaction, so this file must NOT contain BEGIN/COMMIT.
+
+CREATE VIEW plan_wave_progress AS
+SELECT
+  c.plan_key AS plan_key,
+  MAX(c.wave) + 1 AS wave_count,
+  COALESCE(MIN(CASE WHEN c.in_flight > 0 THEN c.wave END), MAX(c.wave)) AS current_wave
+FROM plan_wave_counts c
+GROUP BY c.plan_key;
+
+CREATE VIEW plan_wave_label AS
+SELECT
+  w.plan_key AS plan_key,
+  w.wave_count AS wave_count,
+  w.current_wave AS current_wave,
+  (w.current_wave + 1) || '/' || w.wave_count AS wave_label
+FROM plan_wave_progress w;

package/db/migrations/061_plan_delivery_rollup.sql

@@ -0,0 +1,98 @@
+-- Epic delivery read model as a derived VIEW, plus the composite `plans` read model the pages bind
+-- (epic #412 — retire worker-maintained projections).
+--
+-- 029_plan_delivery.sql denormalised `plans.delivery` ('converging'|'landed'|NULL) and
+-- `plans.delivery_label` onto the `plans` row, recomputed each poll pass by `pollDelivery`
+-- (app/service.ts) which joins each `plan_tasks.pr_key` → `pull_requests.status`. The PURE derivation
+-- lives in `deriveDelivery`/`TERMINAL_STATUSES` (app/delivery.ts). Its comment cites the sole reason
+-- it was a poller-maintained table rather than a VIEW: "Urban's datasource cannot read a SQL VIEW".
+-- That constraint is gone (nano-ide#424), so this expresses the SAME `deriveDelivery` logic as a
+-- DERIVED view — a single source of truth with NO write-path and no drift.
+--
+-- Layered so each view stays a plain `CREATE VIEW <name> AS SELECT … FROM …` (no CTE / no
+-- select-list subquery), parseable by scripts/pages-contract.test.ts:
+--
+--   • plan_delivery_counts — one row per plan_key with the three counts `deriveDelivery` folds over
+--                            the slice PRs (only tasks that OPENED a PR — `pr_key IS NOT NULL` —
+--                            count, mirroring `pollDelivery`'s `if (!t.pr_key) continue`):
+--                              - prs_opened   = number of slice tasks with a PR.
+--                              - prs_merged   = those whose PR reached `status = 'merged'`.
+--                              - prs_in_flight = those whose PR is NON-terminal (`status` NOT IN
+--                                `TERMINAL_STATUSES` = converged/merged/abandoned). A `pr_key` with
+--                                no `pull_requests` row (status NULL, the poller's MISSING_PR_STATUS
+--                                sentinel) is non-terminal, so it counts as in flight — a DB desync
+--                                can never wrongly promote an epic to `landed`.
+--   • plan_delivery        — the derived signal + PRE-FORMATTED label, per `deriveDelivery`:
+--                              - NULL when the plan is not `done` or opened no PRs (no positive
+--                                signal yet), OR every PR is terminal but not all merged
+--                                (resolved-not-landed).
+--                              - 'converging' + "M/O slices merged, F converging" when ≥1 PR is in
+--                                flight.
+--                              - 'landed' + "O/O slices merged" when every slice PR merged
+--                                (prs_in_flight = 0 AND prs_merged = prs_opened > 0).
+--   • plan_read_model      — the `plans` row with its wave (060) and delivery projections DERIVED
+--                            from the views instead of read from the denormalised columns. This is
+--                            the datasource the operator pages (overview / epic-detail) bind, so that
+--                            when the wave-1 cleanup task DROPs plans.wave_label / plans.current_wave
+--                            / plans.wave_count / plans.delivery / plans.delivery_label, every page
+--                            already reads the single-source-of-truth views. It projects only the
+--                            `plans` columns those pages reference, plus the five derived columns.
+--
+-- Forward-only, additive. NO BEGIN/COMMIT — the runner wraps each file in its own transaction.
+
+CREATE VIEW plan_delivery_counts AS
+SELECT
+  t.plan_key AS plan_key,
+  COUNT(t.pr_key) AS prs_opened,
+  SUM(CASE WHEN t.pr_key IS NOT NULL AND p.status = 'merged' THEN 1 ELSE 0 END) AS prs_merged,
+  SUM(CASE WHEN t.pr_key IS NOT NULL AND (p.status IS NULL OR p.status NOT IN ('converged', 'merged', 'abandoned')) THEN 1 ELSE 0 END) AS prs_in_flight
+FROM plan_tasks t
+LEFT JOIN pull_requests p ON p.pr_key = t.pr_key
+GROUP BY t.plan_key;
+
+CREATE VIEW plan_delivery AS
+SELECT
+  pl.plan_key AS plan_key,
+  CASE
+    WHEN pl.status IS NOT 'done' OR COALESCE(c.prs_opened, 0) = 0 THEN NULL
+    WHEN COALESCE(c.prs_in_flight, 0) > 0 THEN 'converging'
+    WHEN c.prs_merged = c.prs_opened THEN 'landed'
+    ELSE NULL
+  END AS delivery,
+  CASE
+    WHEN pl.status IS NOT 'done' OR COALESCE(c.prs_opened, 0) = 0 THEN NULL
+    WHEN COALESCE(c.prs_in_flight, 0) > 0 THEN c.prs_merged || '/' || c.prs_opened || ' slices merged, ' || c.prs_in_flight || ' converging'
+    WHEN c.prs_merged = c.prs_opened THEN c.prs_opened || '/' || c.prs_opened || ' slices merged'
+    ELSE NULL
+  END AS delivery_label
+FROM plans pl
+LEFT JOIN plan_delivery_counts c ON c.plan_key = pl.plan_key;
+
+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,
+  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,
+  pl.list_bucket AS list_bucket,
+  pl.ack_open AS ack_open,
+  wl.wave_count AS wave_count,
+  wl.current_wave AS current_wave,
+  wl.wave_label AS wave_label,
+  d.delivery AS delivery,
+  d.delivery_label AS delivery_label
+FROM plans pl
+LEFT JOIN plan_wave_label wl ON wl.plan_key = pl.plan_key
+LEFT JOIN plan_delivery d ON d.plan_key = pl.plan_key;

package/db/migrations/062_merges_per_day_view.sql

@@ -0,0 +1,72 @@
+-- Merged-per-day throughput / burn-up as a derived SQL VIEW (epic #412, retiring the 051 flat table).
+--
+-- 051_merges_per_day.sql created the DENORMALISED `merges_per_day` read table (day / merged /
+-- cumulative / bar) that `pollMergesPerDay` (app/mergesPerDay.ts) recomputes each poll pass from the
+-- `merges` audit rows (004_merge.sql). Its comment cites the ONE reason it could not simply be a
+-- VIEW: "Urban's page datasource cannot read a SQL VIEW" (gateway.ts `schema()` whitelisted
+-- `type='table'` only). That constraint is GONE — nano-ide#424 made `gateway.schema()` introspect
+-- `type IN ('table','view')` and tag a view read-only, and #411 (059_plan_wave_summary.sql)
+-- established the layered-VIEW pattern. So the aggregate becomes what AGENTS.md always wanted
+-- ("Derivation over duplication"): a VIEW that is a single source of truth with NO write-path and no
+-- possibility of drift from the `merges` audit trail.
+--
+-- This migration is WAVE-0 / PURELY ADDITIVE: it adds the VIEW and the Velocity page is repointed
+-- onto it, but the `merges_per_day` TABLE and its `pollMergesPerDay` write-path are LEFT IN PLACE (a
+-- harmless duplicate) so the surface never goes stale while both coexist. A wave-1 cleanup task
+-- ("retire-projection-writepaths-cleanup") drops the table and deletes the write-path AFTER this
+-- merges.
+--
+-- The VIEW must reproduce the CURRENT projection EXACTLY, including two subtleties beyond the 051
+-- comment's canonical `SELECT date(at) AS day, COUNT(DISTINCT pr_key) …`:
+--   • the day is bucketed in the operator's LOCAL calendar day (issue #361) — `date(at, 'localtime')`,
+--     not UTC — matching `deriveMergesPerDay`, so a merge either side of a local midnight lands on the
+--     day the operator saw it;
+--   • `bar` is the SAME pre-formatted proportional block-character string the `prose` renderer draws
+--     today (the renderer has no per-cell templating / no chart node, so the bar must arrive
+--     ready-to-show): a run of `█` glyphs whose length is `max(1, round((merged / busiest) * 30))`
+--     (min one glyph for any non-zero day; the busiest day is 30 wide), i.e. exactly
+--     `barFor()`/`BAR_WIDTH`/`BAR_FULL` in app/mergesPerDay.ts.
+--
+-- Layered into TWO plain views so each is a `CREATE VIEW <name> AS SELECT … FROM …` with NO CTE and
+-- NO select-list subquery — which keeps them parseable by the static pages↔schema contract guard
+-- (scripts/pages-contract.test.ts), exactly as 059 layers its counts → summary:
+--
+--   • merges_per_day_counts — one row per local calendar day: `day` + `merged`
+--     (COUNT(DISTINCT pr_key) so a PR with several `merged` audit rows on one day — an
+--     already-merged short-circuit or a retry — counts once; `queued`/`blocked` rows are excluded).
+--   • merges_per_day_view   — the same rows PLUS the burn-up `cumulative`
+--     (`SUM(merged) OVER (ORDER BY day)` — a window function in the select list, allowed by the
+--     guard) and the pre-formatted `bar`. The bar length uses `MAX(merged) OVER ()` (the busiest
+--     day) as the scale; the block run is built with SQLite string funcs
+--     (`hex(zeroblob(n))` → 2n '0' chars → `substr` to n → `replace` to the `█` glyph), the same
+--     trick 059 uses for its progress bar. Both live in the SELECT list, not a subquery, so the
+--     guard can still read every output column.
+--
+-- Forward-only, additive (a new read model, no change to any base table). The runner wraps each file
+-- in its own transaction, so this file must NOT contain BEGIN/COMMIT.
+
+CREATE VIEW merges_per_day_counts AS
+SELECT
+  date(m.at, 'localtime') AS day,
+  COUNT(DISTINCT m.pr_key) AS merged
+FROM merges m
+WHERE m.outcome = 'merged'
+GROUP BY date(m.at, 'localtime');
+
+CREATE VIEW merges_per_day_view AS
+SELECT
+  c.day AS day,
+  c.merged AS merged,
+  SUM(c.merged) OVER (ORDER BY c.day) AS cumulative,
+  CASE
+    WHEN c.merged <= 0 OR MAX(c.merged) OVER () <= 0 THEN ''
+    ELSE replace(
+      substr(
+        hex(zeroblob(max(1, CAST(round((c.merged * 1.0 / MAX(c.merged) OVER ()) * 30.0) AS INTEGER)))),
+        1,
+        max(1, CAST(round((c.merged * 1.0 / MAX(c.merged) OVER ()) * 30.0) AS INTEGER))
+      ),
+      '0', '█'
+    )
+  END AS bar
+FROM merges_per_day_counts c;

package/db/migrations/064_lineage_thread_view.sql

@@ -0,0 +1,75 @@
+-- Lineage read-model: derive the view-expressible identity columns of `lineage_threads` (epic
+-- #412 — "Retire worker-maintained denormalized projections in favour of SQL VIEWs").
+--
+-- `lineage_threads` (037_lineage.sql) is a denormalised read table `pollLineage` (app/lineage.ts)
+-- rewrites every poll pass, stitching request → implementation → PR(s) → convergence → merge into
+-- one narrative per `root_request_key`. Its comment cited "Urban's datasource cannot read a SQL
+-- VIEW" as the sole reason to denormalise; nano-ide#424 removed that constraint (gateway.schema()
+-- now introspects `type IN ('table','view')`), so the parts that are plain rollups of data that
+-- ALREADY exists should be DERIVED, not duplicated (AGENTS.md "Derivation over duplication / no
+-- drift surfaces"), exactly as 059_plan_wave_summary.sql did for the plans wave/delivery rollups.
+--
+-- AUDIT — per column, is it a clean rollup or genuinely procedural?
+--
+--   VIEW-EXPRESSIBLE (pure structural function of which origin table the root matches — no frontier
+--   logic, no representative-PR selection, no formatting — so a plain parseable view reproduces them
+--   EXACTLY as `deriveLineage` does):
+--     • `kind`      — 'epic' when the root is a `plans.plan_key`, 'feature' when it is a
+--                     `feature_runs.feature_key`, else 'pr' (self-rooted human/webhook PR). The
+--                     epic-before-feature precedence mirrors `collectThreads`, which sets the plan
+--                     thread after the feature thread for the same key.
+--     • `issue_url` — the matched origin's `issue_url` (`plans`/`feature_runs`), NULL for a
+--                     self-rooted PR — exactly `deriveLineage`'s `origin.kind === "pr" ? null : …`.
+--     • `title`     — the matched origin's `title` for an epic/feature thread. A self-rooted PR's
+--                     title is the PROCEDURAL representative-PR pick, so it falls back to the
+--                     poller-written `lineage_threads.title` for kind 'pr' (see below).
+--
+--   PROCEDURAL (multi-stage frontier / ordering logic in the pure `deriveLineage`, which selects a
+--   representative PR — "first non-terminal by pr_key, else last by pr_key" — branches on origin
+--   kind + feature pre-hand-off, rolls epic fan-out up via `deriveDelivery`, and formats round /
+--   slice-count label strings; none of this is a plain no-CTE / no-select-list-subquery view, and
+--   forcing it would risk diverging from the tested derivation): `stage`, `stage_label`,
+--   `process_key`, `active`, plus the membership columns `pr_count` / `pr_keys` (which union a
+--   root's threaded PRs with its origin's own `pr_key` / `plan_tasks.pr_key` and dedupe across
+--   roots — not a clean grouped join) and the self-rooted `title`. These stay written by
+--   `pollLineage` for the wave-1 cleanup task to trim; this view PASSES THEM THROUGH from
+--   `lineage_threads` so the single Lineage grid keeps rendering identically.
+--
+-- The view is a plain `CREATE VIEW <name> AS SELECT … FROM …` — no CTE, no select-list subquery,
+-- every column aliased — so the static pages↔schema contract guard (scripts/pages-contract.test.ts)
+-- can introspect its output columns to whitelist the repointed page. CASE / COALESCE in the select
+-- list are fine (they are not subqueries).
+--
+-- Forward-only, additive: a new read model, no schema change to any base table, no DROP. The runner
+-- wraps each file in its own transaction, so this file must NOT contain BEGIN/COMMIT. This task owns
+-- the disjoint migration block 064-069; a single view suffices, so 065-069 are left unused.
+
+CREATE VIEW lineage_thread_view AS
+SELECT
+  lt.root_request_key AS root_request_key,
+  CASE
+    WHEN pl.plan_key IS NOT NULL THEN 'epic'
+    WHEN fr.feature_key IS NOT NULL THEN 'feature'
+    ELSE 'pr'
+  END AS kind,
+  CASE
+    WHEN pl.plan_key IS NOT NULL THEN pl.title
+    WHEN fr.feature_key IS NOT NULL THEN fr.title
+    ELSE lt.title
+  END AS title,
+  CASE
+    WHEN pl.plan_key IS NOT NULL THEN pl.issue_url
+    WHEN fr.feature_key IS NOT NULL THEN fr.issue_url
+    ELSE NULL
+  END AS issue_url,
+  lt.stage AS stage,
+  lt.stage_label AS stage_label,
+  lt.process_key AS process_key,
+  lt.pr_keys AS pr_keys,
+  lt.pr_count AS pr_count,
+  lt.active AS active,
+  lt.created_at AS created_at,
+  lt.updated_at AS updated_at
+FROM lineage_threads lt
+LEFT JOIN plans pl ON pl.plan_key = lt.root_request_key
+LEFT JOIN feature_runs fr ON fr.feature_key = lt.root_request_key;

package/package.json

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

package/pages/epic-detail.page.json

@@ -92,7 +92,7 @@
         "data": {
           "kind": "datasource",
           "source": "app",
-          "table": "plans",
+          "table": "plan_read_model",
           "orderBy": { "field": "updated_at", "dir": "desc" },
           "filter": [{ "field": "plan_key", "eqParam": true }]
         },
@@ -137,7 +137,7 @@
         "data": {
           "kind": "datasource",
           "source": "app",
-          "table": "plans",
+          "table": "plan_read_model",
           "orderBy": { "field": "updated_at", "dir": "desc" },
           "filter": [{ "field": "plan_key", "eqParam": true }]
         },

package/pages/lineage.page.json

@@ -87,7 +87,7 @@
         "data": {
           "kind": "datasource",
           "source": "app",
-          "table": "lineage_threads",
+          "table": "lineage_thread_view",
           "orderBy": { "field": "updated_at", "dir": "desc" },
           "filter": [{ "field": "active", "in": [1] }]
         },

package/pages/overview.page.json

@@ -140,7 +140,7 @@
         "data": {
           "kind": "datasource",
           "source": "app",
-          "table": "plans",
+          "table": "plan_read_model",
           "orderBy": { "field": "updated_at", "dir": "desc" },
           "filter": [{ "field": "list_bucket", "in": ["active"] }]
         },

package/pages/velocity.page.json

@@ -85,7 +85,7 @@
         "data": {
           "kind": "datasource",
           "source": "app",
-          "table": "merges_per_day",
+          "table": "merges_per_day_view",
           "orderBy": { "field": "day", "dir": "asc" }
         },
         "header": "{{day}} \u00b7 {{merged}} merged \u00b7 \u03a3 {{cumulative}}",

package/scripts/pages-contract.test.ts

@@ -323,12 +323,14 @@ test("issue #205: overview is the landing page and first nav item", async () =>
   // EPIC surface buckets on the DERIVED `list_bucket` (issue #298) — NOT raw `status` — so a `done`
   // epic still converging, or landed-but-unpromoted, does not vanish from the in-flight Epics section
   // the instant `status=done`. Guarding the field here is the regression guard for that defect class.
+  // The epic surface binds the derived `plan_read_model` VIEW (epic #412 — the single source of truth
+  // for the wave/delivery projections it also renders), not the raw `plans` table.
   const expected: Record<string, { field: string; in: string[] }> = {
     pull_requests: {
       field: "status",
       in: ["converging", "waiting_review", "escalated", "waiting_deps", "waiting_merge", "queued", "merging"],
     },
-    plans: { field: "list_bucket", in: ["active"] },
+    plan_read_model: { field: "list_bucket", in: ["active"] },
     feature_runs: { field: "status", in: ["running", "escalated", "awaiting_operator"] },
     // The 4th dispatch surface (issue #386) — active delivery graphs. Both in-flight statuses
     // (`awaiting-approval` parked at the gate, `running` dispatched) show here.