@nanobpm/nano-workforce 0.122.0 → 0.123.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.123.0](https://github.com/nanobpm/nano-workforce/compare/v0.122.0...v0.123.0) (2026-08-22)
+
+
+### Features
+
+* derive feature/epic display projections as SQL VIEWs ([#439](https://github.com/nanobpm/nano-workforce/issues/439)) ([#448](https://github.com/nanobpm/nano-workforce/issues/448)) ([5c79718](https://github.com/nanobpm/nano-workforce/commit/5c797184e65250afea1224bb6227d4cb7687ce8b)), closes [#412](https://github.com/nanobpm/nano-workforce/issues/412) [#412](https://github.com/nanobpm/nano-workforce/issues/412) [#412](https://github.com/nanobpm/nano-workforce/issues/412)
+
 # [0.122.0](https://github.com/nanobpm/nano-workforce/compare/v0.121.0...v0.122.0) (2026-08-22)
 
 

package/app/delivery.test.ts

@@ -3,44 +3,11 @@
 // (epic #412 retired the stored `plans.delivery` / `plans.delivery_label` columns). It must cleanly
 // distinguish an epic whose fan-out is `done` but whose slices are still CONVERGING from one where
 // every slice PR has LANDED, and count abandoned/converged PRs as resolved-not-landed (never
-// `landed`). `pollPlanBucket` (app/service.ts) is the reader that applies the delivery-aware
-// `list_bucket`/`ack_open` correction from that signal.
+// `landed`). The delivery-aware `list_bucket`/`ack_open` bucket derivation now lives in the
+// `plan_read_model` VIEW (074), cross-checked against the pure helpers in app/plansReadModel.test.ts.
 import { test } from "node:test";
 import { assert, assertEquals } from "#test-assert";
-import type { DataLayer } from "@nanobpm/urban";
 import { deriveDelivery, TERMINAL_STATUSES } from "./delivery.ts";
-import { pollPlanBucket } from "./service.ts";
-
-// A tiny in-memory record gateway (all/find/update/insert), mirroring the fake-app style used
-// across the app tests (see app/taskDelta.test.ts), enough to exercise the `pollPlanBucket` pass.
-function memData(): { data: DataLayer; stores: Record<string, any[]> } {
-  const stores: Record<string, any[]> = {};
-  function tbl(name: string, pk = "id") {
-    const rows = (stores[name] ??= [] as any[]);
-    const match = (r: any, where: any) => Object.entries(where).every(([k, v]) => r[k] === v);
-    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) => match(r, where));
-      },
-      async insert(row: any) {
-        rows.push({ ...row });
-        return row[pk];
-      },
-      async update(id: any, patch: any) {
-        const r = rows.find((row) => row[pk] === id);
-        if (r) Object.assign(r, patch);
-      },
-    };
-  }
-  const data = { table: (n: string, pk?: string) => tbl(n, pk) } as any as DataLayer;
-  return { data, stores };
-}
 
 test("all slice PRs merged -> landed", () => {
   const r = deriveDelivery("done", ["merged", "merged", "merged"]);
@@ -107,102 +74,3 @@ test("every non-terminal status counts as in flight", () => {
     assertEquals(r.prsInFlight, 1, `status ${s}`);
   }
 });
-
-test("pollPlanBucket: a still-converging done epic suppresses the Dismiss flag (ack_open=0) and stays Active", async () => {
-  const { data, stores } = memData();
-  // A `done` epic the delivery-free gateway left as a Dismiss candidate (ack_open=1); pollPlanBucket
-  // derives `converging` at read time and clears it.
-  stores.plans = [
-    { plan_key: "epic-1", status: "done", acknowledged_at: null, list_bucket: "active", ack_open: 1 },
-  ];
-  stores.plan_tasks = [
-    { id: 1, plan_key: "epic-1", pr_key: "o/r#1" },
-    { id: 2, plan_key: "epic-1", pr_key: "o/r#2" },
-  ];
-  stores.pull_requests = [
-    { pr_key: "o/r#1", status: "merged" },
-    { pr_key: "o/r#2", status: "converging" },
-  ];
-
-  await pollPlanBucket(data);
-
-  assertEquals(stores.plans[0].list_bucket, "active");
-  assertEquals(stores.plans[0].ack_open, 0, "converging epic must not offer Dismiss");
-});
-
-test("pollPlanBucket: a fully landed done epic opens the Dismiss flag (ack_open=1), still Active", async () => {
-  const { data, stores } = memData();
-  stores.plans = [
-    { plan_key: "epic-2", status: "done", acknowledged_at: null, list_bucket: "active", ack_open: 0 },
-  ];
-  stores.plan_tasks = [
-    { id: 1, plan_key: "epic-2", pr_key: "o/r#10" },
-    { id: 2, plan_key: "epic-2", pr_key: "o/r#11" },
-  ];
-  stores.pull_requests = [
-    { pr_key: "o/r#10", status: "merged" },
-    { pr_key: "o/r#11", status: "merged" },
-  ];
-
-  await pollPlanBucket(data);
-
-  assertEquals(stores.plans[0].list_bucket, "active");
-  assertEquals(stores.plans[0].ack_open, 1);
-});
-
-test("pollPlanBucket: a dangling pr_key keeps the epic converging (ack_open stays 0)", async () => {
-  const { data, stores } = memData();
-  stores.plans = [
-    { plan_key: "epic-3", status: "done", acknowledged_at: null, list_bucket: "active", ack_open: 1 },
-  ];
-  stores.plan_tasks = [
-    { id: 1, plan_key: "epic-3", pr_key: "o/r#1" },
-    { id: 2, plan_key: "epic-3", pr_key: "o/r#2" }, // no matching pull_requests row (DB desync)
-  ];
-  stores.pull_requests = [{ pr_key: "o/r#1", status: "merged" }];
-
-  await pollPlanBucket(data);
-
-  // Without the dangling PR counting as in-flight this would wrongly land → open Dismiss.
-  assertEquals(stores.plans[0].ack_open, 0);
-});
-
-test("pollPlanBucket: an acknowledged landed epic buckets to History", async () => {
-  const { data, stores } = memData();
-  stores.plans = [
-    {
-      plan_key: "epic-4",
-      status: "done",
-      acknowledged_at: "2024-01-01T00:00:00Z",
-      list_bucket: "active",
-      ack_open: 1,
-    },
-  ];
-  stores.plan_tasks = [{ id: 1, plan_key: "epic-4", pr_key: "o/r#20" }];
-  stores.pull_requests = [{ pr_key: "o/r#20", status: "merged" }];
-
-  await pollPlanBucket(data);
-
-  assertEquals(stores.plans[0].list_bucket, "history");
-  assertEquals(stores.plans[0].ack_open, 0);
-});
-
-test("pollPlanBucket: a steady-state pass rewrites nothing (idempotent)", async () => {
-  const { data, stores } = memData();
-  stores.plans = [
-    {
-      plan_key: "epic-5",
-      status: "done",
-      acknowledged_at: null,
-      list_bucket: "active",
-      ack_open: 1,
-      updated_at: "2020-01-01T00:00:00.000Z",
-    },
-  ];
-  stores.plan_tasks = [{ id: 1, plan_key: "epic-5", pr_key: "o/r#30" }];
-  stores.pull_requests = [{ pr_key: "o/r#30", status: "merged" }]; // landed → ack_open already 1
-
-  await pollPlanBucket(data);
-
-  assertEquals(stores.plans[0].updated_at, "2020-01-01T00:00:00.000Z", "no-op pass must not re-stamp");
-});

package/app/feature.ts

@@ -18,7 +18,6 @@ import type { DataLayer, EngineClient } from "@nanobpm/urban";
 import { coalesceTitle, fetchIssueTitle } from "./github.ts";
 import { ESCALATION_SLA_TIMEOUT, normalizeBaseBranch, type ParsedIssue, renderBaseBranchBrief } from "./plan.ts";
 import type { ReadinessProbe } from "./readiness.ts";
-import { deriveListBucket, deriveStage } from "./stage.ts";
 
 /** Optional intake-time readiness gate for a feature run (issue #295): the `capability`/`command`/…
  * probes the run must ALL satisfy before its implementation agent is dispatched (parked, durably, at
@@ -68,21 +67,26 @@ export interface FeatureRun {
   /** Timestamp an operator dismissed a TERMINAL run (§5, `acknowledge-done`); NULL until then. When
    * set on a terminal row, `list_bucket` flips from 'active' to 'history'. Projection surface. */
   acknowledged_at: string | null;
-  /** Projection maintained by the feature_runs gateway (like `delivery_label`): the canonical pipeline
-   * stage key from `deriveStage` (Requested|Implementing|PR open|Converging|Merging|Done). The page's
-   * pipeline column binds `activeField` to it. NULL only on legacy rows before `backfillFeatureStages`. */
+  /** RETIRED as a write-time projection (issue #439): the pipeline `stage` is now DERIVED by the
+   * `feature_read_model` VIEW (073) from `status`/`pr_key`/`converge`/`auto_merge`, mirroring
+   * `deriveStage` (app/stage.ts). The Feature page binds the VIEW's `stage`, never this base column,
+   * so a raw-datasource `status` write (the `instanceTracking` reconciler) can no longer leave it
+   * stale. The base column survives (expand/contract — a later migration drops it) but is no longer
+   * written or read; NULL on rows written after the projection was removed. */
   stage: string | null;
-  /** Gateway projection: the active stage's render state from `deriveStage` (`ok`|`failed`|`blocked`|
-   * NULL). The page binds `stateField` to it; NULL means in-progress (renderer shows `active`). */
+  /** RETIRED as a write-time projection (issue #439): `stage_state` is DERIVED by `feature_read_model`
+   * (073). See `stage`. The page binds the VIEW's `stateField`; this base column is vestigial. */
   stage_state: string | null;
-  /** Gateway projection: space-separated set of stage keys NOT in this row's path from `deriveStage`
-   * (derived from `converge`/`auto_merge`). The page binds `notInPathField` to it. */
+  /** RETIRED as a write-time projection (issue #439): `stage_skipped` is DERIVED by `feature_read_model`
+   * (073). See `stage`. The page binds the VIEW's `notInPathField`; this base column is vestigial. */
   stage_skipped: string | null;
-  /** Gateway projection: a short attention badge (`blocked` / `⚠`) for the active stage, or NULL, from
-   * `deriveStage`. The page binds `badgeField` to it. */
+  /** RETIRED as a write-time projection (issue #439): `attention` is DERIVED by `feature_read_model`
+   * (073). See `stage`. The page binds the VIEW's `badgeField`; this base column is vestigial. */
   attention: string | null;
-  /** Gateway projection: the Active/History partition label ('active'|'history'), 'history' iff a
-   * terminal row has been acknowledged. The page's tabs filter on it with flat `in` clauses (§5). */
+  /** RETIRED as a write-time projection (issue #439): the Active/History `list_bucket` ('active'|
+   * 'history', 'history' iff a terminal row is acknowledged) is DERIVED by `feature_read_model` (073)
+   * from `status`/`acknowledged_at`, mirroring `deriveListBucket`. The page's tabs filter the VIEW's
+   * `list_bucket`; this base column is vestigial. */
   list_bucket: string | null;
   created_at: string;
   updated_at: string;
@@ -214,122 +218,20 @@ export async function recordFeatureEscalation(
  * Tasks inbox. */
 export const FEATURE_BLOCKED_ELEMENT = "feature-blocked";
 
-/** The feature_runs fields the projection reads. A patch touching none of these cannot change the
- * derived `stage`/`stage_state`/`stage_skipped`/`attention`/`list_bucket`, so the gateway can skip the
- * read-back+reproject for it (see the `update` proxy). Kept adjacent to `projectFeatureRun` so the two
- * stay in lockstep — every field `projectFeatureRun` reads MUST appear here. */
-const PROJECTION_INPUT_KEYS: readonly (keyof FeatureRun)[] = [
-  "status",
-  "pr_key",
-  "converge",
-  "auto_merge",
-  "acknowledged_at",
-];
-
-/** The feature_runs fields the projection WRITES. Included in the reproject trigger so a caller who
- * writes a derived column directly (e.g. `stage`/`list_bucket`) can never bypass derivation: the
- * gateway re-reads, recomputes, and OVERRIDES the raw value with the canonical derived one, keeping
- * "the gateway is the one projection source" a true invariant. Must mirror `projectFeatureRun`'s keys. */
-const PROJECTION_OUTPUT_KEYS: readonly (keyof FeatureRun)[] = [
-  "stage",
-  "stage_state",
-  "stage_skipped",
-  "attention",
-  "list_bucket",
-];
-
-/** True when a patch changes at least one field the projection derives from OR one it writes — i.e. the
- * projection must be recomputed. A patch touching only projection-irrelevant fields (e.g. `updated_at`)
- * leaves the stored projection correct, since the gateway is the sole write path (see `featureRuns`); a
- * patch that writes a derived column directly still forces a reproject so derivation can't be bypassed. */
-function patchAffectsProjection(patch: Partial<FeatureRun>): boolean {
-  return PROJECTION_INPUT_KEYS.some((k) => k in patch) || PROJECTION_OUTPUT_KEYS.some((k) => k in patch);
-}
-
-/** Compute the write-time projection columns for a fully-merged feature_runs row. Centralised so the
- * gateway is the ONE place `deriveStage` / `deriveListBucket` are applied — the page, SQL, pollers and
- * workers never re-derive the mapping (AGENTS.md "derivation over duplication"). */
-function projectFeatureRun(row: Partial<FeatureRun>): Partial<FeatureRun> {
-  if (!row.status) return {};
-  const { stage, state, skipped, attention } = deriveStage({
-    status: row.status,
-    pr_key: row.pr_key ?? null,
-    converge: row.converge ?? null,
-    auto_merge: row.auto_merge ?? null,
-  });
-  return {
-    stage,
-    stage_state: state,
-    stage_skipped: skipped,
-    attention,
-    list_bucket: deriveListBucket(row.status, row.acknowledged_at ?? null),
-  };
-}
-
-/** The feature_runs record gateway (keyed on `feature_key`). Wrapped in a thin projecting proxy so the
- * derived pipeline columns (`stage`/`stage_state`/`stage_skipped`/`attention`/`list_bucket`) CANNOT be
- * missed by any writer: `insert` and `update` merge the incoming values over the current stored row,
- * then recompute the projection from that post-write field set and write it alongside — exactly the
- * `delivery_label`-style write-time projection, but hoisted to the single gateway so the many scattered
- * status writers (startFeature, the service pollers/reconcilers, the acknowledge operations, and the
- * feature workers) all stay UNCHANGED and automatically get a correct, fresh projection. `update`
- * skips the read-back+reproject for a patch that touches no projection input (e.g. an `updated_at`-only
- * poller write), avoiding a needless `get` roundtrip — the stored projection is already correct since
- * this gateway is the sole write path. Every other method delegates straight through. This is the sole
- * runtime/app-layer WRITE path to feature_runs (no app-code raw SQL, no other `data.table("feature_runs")`
- * mutation — read-only direct reads in e2e tests, and forward-only data migrations such as
- * `db/migrations/036_backfill_titles.sql`, notwithstanding), so
- * `stage`/`stage_state`/`stage_skipped`/`attention`/`list_bucket` are
- * always populated and correct for every row and every transition. */
-export const featureRuns = (data: DataLayer) => {
-  const table = data.table<FeatureRun>("feature_runs", "feature_key");
-  return new Proxy(table, {
-    get(target, prop) {
-      if (prop === "insert") {
-        return (row: Partial<FeatureRun>) => target.insert({ ...row, ...projectFeatureRun(row) });
-      }
-      if (prop === "update") {
-        return async (id: unknown, patch: Partial<FeatureRun>) => {
-          // Only re-read + reproject when the patch changes a projection input. A projection-irrelevant
-          // patch (e.g. an `updated_at`-only poller write) leaves the stored projection correct — the
-          // gateway is the sole write path — so skip the extra `get` roundtrip and delegate straight.
-          if (!patchAffectsProjection(patch)) return target.update(id, patch);
-          const existing = await target.get(id);
-          const merged: Partial<FeatureRun> = { ...existing, ...patch };
-          return target.update(id, { ...patch, ...projectFeatureRun(merged) });
-        };
-      }
-      // Delegate every other method straight through. Bind functions to the real target so the
-      // gateway's private class fields (`#src`) resolve — a Proxy `this` would not carry them.
-      const value = Reflect.get(target, prop, target);
-      return typeof value === "function" ? value.bind(target) : value;
-    },
-  });
-};
-
-/** Re-project every feature_runs row through the gateway so rows missing any projection column get
- * correct `stage`/`stage_state`/`stage_skipped`/`attention`/`list_bucket` values. Catches rows written
- * before migration 039 (the pipeline columns). 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. */
-export async function backfillFeatureStages(data: DataLayer): Promise<number> {
-  const table = featureRuns(data);
-  const rows = await table.all();
-  let stamped = 0;
-  for (const row of rows) {
-    // Only touch rows the projection has never reached — a legacy row whose `stage` (pre-039) column is
-    // still NULL. The gateway keeps every write fresh, so a fully-projected row needs no re-write;
-    // skipping them avoids a full-table rewrite on every boot and keeps `stamped` an honest count of
-    // rows actually backfilled (not the total row count).
-    if (row.stage != null) continue;
-    // Re-derive the projection from the legacy row's own stored fields and write it. (An empty patch
-    // would now short-circuit the projecting proxy — it only reprojects on a projection-input change —
-    // so backfill projects explicitly rather than relying on an empty-patch reproject.)
-    await table.update(row.feature_key, projectFeatureRun(row));
-    stamped++;
-  }
-  return stamped;
-}
+/** The feature_runs record gateway (keyed on `feature_key`) — a plain record table.
+ *
+ * The pipeline projection (`stage`/`stage_state`/`stage_skipped`/`attention`/`list_bucket`) is NO
+ * LONGER a write-time projection here (issue #439): it is a DERIVED SQL VIEW, `feature_read_model`
+ * (073), computed from each row's own `status`/`pr_key`/`converge`/`auto_merge`/`acknowledged_at`. The
+ * Feature page binds the VIEW, never this table's stored derived columns. Removing the write-time
+ * projection closes the drift the framework `instanceTracking` reconciler opened: it writes
+ * `feature_runs.status` through the RAW datasource (`{status:"abandoned"}` on a terminated instance),
+ * bypassing the old projecting gateway and leaving the display columns frozen — now there is no stored
+ * derived column and no write-path for any writer to leave stale. `deriveStage`/`deriveListBucket`
+ * (app/stage.ts) remain the canonical implementation the VIEW mirrors and the acknowledge operations
+ * reuse; app/featureReadModel.test.ts pins the VIEW to them (including a raw-datasource `status` write
+ * that reproduces the reconciler bypass). */
+export const featureRuns = (data: DataLayer) => data.table<FeatureRun>("feature_runs", "feature_key");
 
 /** The deterministic task id for a single-issue run — the implementation agent branches
  * `feat/<task.id>` (see resources/prompts/feature.md), so it MUST be derivable from the issue alone

package/app/featureReadModel.test.ts

@@ -0,0 +1,210 @@
+// Read-model VIEW coverage for the feature-run pipeline projection (issue #439 — the status-driven
+// follow-up to epic #412, "Retire worker-maintained denormalized projections in favour of SQL
+// VIEWs").
+//
+// 039_feature_pipeline_stage.sql denormalised the pipeline projection
+// (`stage`/`stage_state`/`stage_skipped`/`attention`/`list_bucket`) onto the `feature_runs` row,
+// written by the `featureRuns()` gateway (app/feature.ts) at WRITE TIME from the pure `deriveStage` /
+// `deriveListBucket` (app/stage.ts). That "the gateway is the sole write path" invariant did NOT hold
+// for the framework `instanceTracking` reconciler, which writes `feature_runs.status` through the RAW
+// datasource on a terminated instance — bypassing the gateway and freezing the display columns.
+// 073_feature_read_model.sql retires the write-time projection: the derived columns are now a VIEW
+// over each row's own `status`/`pr_key`/`converge`/`auto_merge`/`acknowledged_at`, so there is no
+// stored column and no write-path for any writer to leave stale.
+//
+// This exercises the REAL SQLite view (073 applied to an in-memory DB, mirroring
+// app/plansReadModel.test.ts / app/mergesPerDayView.test.ts) and pins that its CASE expressions
+// reproduce `deriveStage` / `deriveListBucket` EXACTLY over the full status matrix — the SAME pure
+// helpers the acknowledge operations guard on — plus a RED/GREEN guard reproducing the reconciler
+// bypass: a RAW-datasource `status` write must leave the projection correct.
+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 { FEATURE_RUN_STATUSES } from "./feature.ts";
+import { deriveListBucket, deriveStage } from "./stage.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"));
+
+// The base `feature_runs` shape the view reads (028 + 030's delivery_label + 035's title + 039's
+// acknowledged_at & the now-vestigial stored stage/… columns), plus migration 073. The stored derived
+// columns are present precisely so the tests can seed STALE values and prove the VIEW ignores them.
+function viewDb(): DatabaseSync {
+  const db = new DatabaseSync(":memory:");
+  db.exec(
+    `CREATE TABLE feature_runs (
+       feature_key TEXT PRIMARY KEY, repo TEXT, issue_number INTEGER, issue_url TEXT, title TEXT,
+       base_branch TEXT, status TEXT, process_key TEXT, pr_key TEXT, converge INTEGER, auto_merge INTEGER,
+       outcome TEXT, delivery_label TEXT, acknowledged_at TEXT, created_at TEXT, updated_at TEXT,
+       stage TEXT, stage_state TEXT, stage_skipped TEXT, attention TEXT, list_bucket TEXT);`,
+  );
+  db.exec(MIG("073_feature_read_model.sql"));
+  return db;
+}
+
+interface SampleRun {
+  status: string;
+  pr_key?: string | null;
+  converge?: number;
+  auto_merge?: number;
+  acknowledged_at?: string | null;
+  // Deliberately-stale STORED projection columns (simulating a row the gateway last projected while
+  // in a different status). The VIEW must ignore these and re-derive from `status`.
+  stored?: Partial<Record<"stage" | "stage_state" | "stage_skipped" | "attention" | "list_bucket", string>>;
+}
+
+function addRun(db: DatabaseSync, feature_key: string, run: SampleRun): void {
+  const s = run.stored ?? {};
+  db.prepare(
+    `INSERT INTO feature_runs
+       (feature_key, repo, issue_number, issue_url, title, base_branch, status, pr_key, converge,
+        auto_merge, acknowledged_at, created_at, updated_at,
+        stage, stage_state, stage_skipped, attention, list_bucket)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+  ).run(
+    feature_key,
+    "o/r",
+    1,
+    `https://gh/${feature_key}`,
+    `Feature ${feature_key}`,
+    "main",
+    run.status,
+    run.pr_key ?? null,
+    run.converge ?? 0,
+    run.auto_merge ?? 0,
+    run.acknowledged_at ?? null,
+    "2026-01-01T00:00:00Z",
+    "2026-01-01T00:00:00Z",
+    s.stage ?? null,
+    s.stage_state ?? null,
+    s.stage_skipped ?? null,
+    s.attention ?? null,
+    s.list_bucket ?? null,
+  );
+}
+
+function projection(db: DatabaseSync, feature_key: string): Record<string, unknown> {
+  const r = db
+    .prepare(
+      "SELECT stage, stage_state, stage_skipped, attention, list_bucket FROM feature_read_model WHERE feature_key = ?",
+    )
+    .get(feature_key) as Record<string, unknown>;
+  return { ...r };
+}
+
+test("feature_read_model derives stage/stage_state/stage_skipped/attention EXACTLY like deriveStage, over every status × converge/auto_merge/pr_key combination", () => {
+  const db = viewDb();
+  const cases: Array<{ key: string; run: SampleRun }> = [];
+  let i = 0;
+  for (const status of FEATURE_RUN_STATUSES) {
+    for (const converge of [0, 1]) {
+      for (const auto_merge of [0, 1]) {
+        for (const pr_key of [null, `o/r#pr${i}`]) {
+          const key = `o/r#${i++}`;
+          cases.push({ key, run: { status, converge, auto_merge, pr_key } });
+          addRun(db, key, { status, converge, auto_merge, pr_key });
+        }
+      }
+    }
+  }
+
+  for (const { key, run } of cases) {
+    const oracle = deriveStage({
+      status: run.status,
+      pr_key: run.pr_key ?? null,
+      converge: run.converge ?? 0,
+      auto_merge: run.auto_merge ?? 0,
+    });
+    const row = projection(db, key);
+    assertEquals(row.stage, oracle.stage, `${key} (status=${run.status}): stage`);
+    assertEquals(row.stage_state, oracle.state, `${key} (status=${run.status}): stage_state`);
+    assertEquals(row.stage_skipped, oracle.skipped, `${key} (status=${run.status}): stage_skipped`);
+    assertEquals(row.attention, oracle.attention, `${key} (status=${run.status}): attention`);
+  }
+});
+
+test("feature_read_model derives list_bucket EXACTLY like deriveListBucket (history iff terminal AND acknowledged)", () => {
+  const db = viewDb();
+  let i = 0;
+  const cases: Array<{ key: string; status: string; ackAt: string | null }> = [];
+  for (const status of FEATURE_RUN_STATUSES) {
+    for (const ackAt of [null, "2026-02-02T00:00:00Z"]) {
+      const key = `o/r#lb${i++}`;
+      cases.push({ key, status, ackAt });
+      addRun(db, key, { status, acknowledged_at: ackAt });
+    }
+  }
+  for (const { key, status, ackAt } of cases) {
+    assertEquals(
+      projection(db, key).list_bucket,
+      deriveListBucket(status, ackAt),
+      `${key} (status=${status}, acknowledged=${ackAt !== null}): list_bucket`,
+    );
+  }
+});
+
+test("feature_read_model IGNORES any stale STORED projection columns — it reads only from status et al.", () => {
+  const db = viewDb();
+  // A merged run whose STORED columns lie (frozen from when it was `running`). The VIEW must re-derive.
+  addRun(db, "o/r#stale", {
+    status: "merged",
+    acknowledged_at: "2026-02-02T00:00:00Z",
+    stored: { stage: "Implementing", stage_state: undefined, attention: "⚠", list_bucket: "active" },
+  });
+  assertEquals(projection(db, "o/r#stale"), {
+    stage: "Done",
+    stage_state: "ok",
+    stage_skipped: "Converging Merging",
+    attention: null,
+    list_bucket: "history",
+  });
+});
+
+test("RED/GREEN GUARD: a RAW-datasource feature_runs.status write (the instanceTracking reconciler bypass) leaves the projection CORRECT (stage=Done, terminal stage_state, attention=null, Dismiss renderable, still Active)", () => {
+  // Reproduce the framework `instanceTracking` reconciler class of bug: on a terminated (cancelled)
+  // process instance it writes `{status:"abandoned"}` to `feature_runs` through the RAW datasource,
+  // bypassing the (now retired) projecting `featureRuns` gateway. Under the OLD write-time projection
+  // the stored `stage`/`stage_state`/`attention`/`list_bucket` would FREEZE at their pre-terminal
+  // values — the merlin symptom: a cancelled run wedged in Active as a live-looking `Implementing ⚠`,
+  // its Dismiss gated shut on a NULL stage_state. Because the projection is now a VIEW over `status`,
+  // the read model stays correct with no write-path for any writer to leave it stale.
+  const db = viewDb();
+  // A live run mid-flight — its (soon-stale) stored projection says Implementing / ⚠ / active.
+  addRun(db, "o/r#kill", {
+    status: "running",
+    stored: { stage: "Implementing", stage_state: undefined, attention: undefined, list_bucket: "active" },
+  });
+  assertEquals(projection(db, "o/r#kill").stage, "Implementing", "precondition: live run renders Implementing");
+
+  // 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 none of the display columns.
+  db.prepare("UPDATE feature_runs SET status = 'abandoned' WHERE feature_key = ?").run("o/r#kill");
+
+  const row = projection(db, "o/r#kill");
+  const oracle = deriveStage({ status: "abandoned", pr_key: null, converge: 0, auto_merge: 0 });
+  // The projection tracks `status` through the VIEW — the merlin drift can no longer happen.
+  assertEquals(row.stage, "Done", "an abandoned run is Done, not wedged at Implementing");
+  assertEquals(row.stage, oracle.stage);
+  assertEquals(row.stage_state, "failed", "abandoned renders a terminal FAILED state (was frozen NULL)");
+  assertEquals(row.stage_state, oracle.state);
+  assertEquals(row.attention, null, "the stale ⚠ badge is gone");
+  assertEquals(row.attention, oracle.attention);
+  // Dismiss's `showWhenField` is `stage_state`: a non-null terminal state makes it renderable.
+  assert(row.stage_state != null, "Dismiss is renderable (stage_state is non-null) so the run can be ticked off");
+  // Unacknowledged terminal → still Active (History only after the operator dismisses it).
+  assertEquals(row.list_bucket, "active", "a just-cancelled run sits in Active until dismissed");
+  assertEquals(row.list_bucket, deriveListBucket("abandoned", null));
+});
+
+test("the Feature page binds the derived feature_read_model VIEW (not the raw feature_runs table)", () => {
+  // `feature.page.json`'s runs grid is the ONLY thing making the UI consume the derived projection.
+  // `feature_runs` remains a valid schema table, so reverting this binding would leave every SQL-view
+  // test green while the display silently resumed reading the stale stored columns; pin it here
+  // (suppressed advisory feature.page.json — issue #439).
+  const page = PAGE("feature.page.json");
+  const runs = (page.nodes ?? []).find((n: { id: string }) => n.id === "feature-runs");
+  assert(runs, "feature page must keep the Feature runs grid");
+  assertEquals(runs.props.data.table, "feature_read_model");
+});