@nanobpm/nano-workforce 0.123.2 → 0.125.0

package/app/featureReadModel.test.ts

@@ -1,39 +1,41 @@
-// 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").
+// Read-model coverage for the feature-run pipeline projection (issues #412 → #439 → #422), now
+// authored via Urban's ADR-0065 declare-once primitive (`defineReadModel`, app/featureReadModel.ts).
 //
-// 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. 075_feature_read_model_attention_
-// from_user_tasks.sql then moves `attention` off the drift-prone `status` variable onto ENGINE TRUTH
-// — an OPEN `feature-blocked`/`feature-escalation` row in the `user_tasks` inbox (issue #422).
+// 039_feature_pipeline_stage.sql denormalised the projection (`stage`/`stage_state`/`stage_skipped`/
+// `attention`/`list_bucket`) onto the `feature_runs` row at WRITE TIME; 073 retired that into a VIEW
+// over each row's own columns; 075 moved `attention` onto ENGINE TRUTH (an OPEN `user_tasks` row,
+// issue #422). Each of those hand-wired the derived columns TWICE — the SQL CASE/EXISTS AND the TS
+// oracle (`deriveStage`/`deriveListBucket`) — kept in lockstep by a bespoke parity test (drift
+// surface #2). 076_feature_read_model_declare_once.sql supersedes them: every derived column is now
+// emitted from the ONE `featureReadModel` declaration, which ALSO drives the TS via `fnFor`. This
+// suite therefore guards THREE things:
 //
-// This exercises the REAL SQLite view (073+075 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 × open-task matrix — the
-// SAME pure helpers the acknowledge operations guard on — plus RED/GREEN guards reproducing the
-// reconciler bypass (a RAW-datasource `status` write must leave the projection correct) and the #422
-// answered-escalation drift (a sticky `status='escalated'` with no open task must show no ⚠).
+//   1. DRIFT GUARD — migration 076 embeds each derived column's SQL VERBATIM from
+//      `featureReadModel.sqlSelectFor(...)`, so the checked-in VIEW cannot drift from the declaration.
+//   2. FRAMEWORK PARITY GUARD — `assertReadModelParity` proves the SQL and TS lowerings the ONE
+//      declaration compiles to agree (the role the old hand-written lockstep test played, now
+//      framework-owned).
+//   3. END-TO-END BEHAVIOUR on the REAL migration VIEW (076 applied to an in-memory DB): the full
+//      status × open-task matrix vs the model-derived oracle, the stale-stored-column ignore, the
+//      reconciler `status`-bypass, the #422 answered-escalation drift, and the page binding.
 import { readFileSync } from "node:fs";
 import { DatabaseSync } from "node:sqlite";
 import { test } from "node:test";
 import { fileURLToPath } from "node:url";
+import { assertReadModelParity, type ParityDb, type ParitySample } from "@nanobpm/urban";
 import { assert, assertEquals } from "#test-assert";
 import { FEATURE_RUN_STATUSES } from "./feature.ts";
+import { FEATURE_READ_MODEL_BASE_ALIAS, FEATURE_READ_MODEL_DERIVED, featureReadModel } from "./featureReadModel.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.
+const MIGRATION_076 = "076_feature_read_model_declare_once.sql";
+
+// The base `feature_runs` shape the VIEW reads, plus the `user_tasks` inbox (034) the `attention`
+// derivation `EXISTS`-reads. 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(
@@ -43,16 +45,12 @@ function viewDb(): DatabaseSync {
        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);`,
   );
-  // The `user_tasks` inbox (034_user_tasks_inbox.sql) — the engine-truth source the 075 VIEW derives
-  // `attention` from (a row IFF an escalation user task is OPEN). Minimal shape: the three columns the
-  // correlated EXISTS lookups read, plus its PK.
   db.exec(
     `CREATE TABLE user_tasks (
        user_task_key TEXT PRIMARY KEY, element_id TEXT NOT NULL, subject_type TEXT NOT NULL,
        subject_key TEXT NOT NULL);`,
   );
-  db.exec(MIG("073_feature_read_model.sql"));
-  db.exec(MIG("075_feature_read_model_attention_from_user_tasks.sql"));
+  db.exec(MIG(MIGRATION_076));
   return db;
 }
 
@@ -71,7 +69,7 @@ interface SampleRun {
   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`.
+  // in a different status). The VIEW must ignore these and re-derive.
   stored?: Partial<Record<"stage" | "stage_state" | "stage_skipped" | "attention" | "list_bucket", string>>;
 }
 
@@ -114,7 +112,67 @@ function projection(db: DatabaseSync, feature_key: string): Record<string, unkno
   return { ...r };
 }
 
-test("feature_read_model derives stage/stage_state/stage_skipped/attention EXACTLY like deriveStage, over every status × converge/auto_merge/pr_key × open-task combination", () => {
+// A `ParityDb` over node:sqlite's `DatabaseSync` for `assertReadModelParity` (which needs positional
+// `exec`/`all`/`run`, whereas `DatabaseSync` exposes query methods on prepared statements).
+function parityDb(db: DatabaseSync): ParityDb {
+  return {
+    exec: (sql) => db.exec(sql),
+    all: <T = Record<string, unknown>>(sql: string, params: unknown[] = []) =>
+      db.prepare(sql).all(...(params as never[])) as T[],
+    run: (sql, params: unknown[] = []) => {
+      const r = db.prepare(sql).run(...(params as never[]));
+      return { changes: Number(r.changes), lastInsertRowid: r.lastInsertRowid };
+    },
+  };
+}
+
+test("DRIFT GUARD: migration 076 embeds each derived column VERBATIM from featureReadModel.sqlSelectFor (the VIEW cannot drift from the declaration)", () => {
+  const sql = MIG(MIGRATION_076);
+  for (const col of FEATURE_READ_MODEL_DERIVED) {
+    const emitted = featureReadModel.sqlSelectFor(col, { baseAlias: FEATURE_READ_MODEL_BASE_ALIAS });
+    assert(
+      sql.includes(`${emitted} AS ${col}`),
+      `migration ${MIGRATION_076} no longer embeds the declaration's SQL for "${col}" — regenerate it ` +
+        `from featureReadModel (or add a new superseding migration). Expected to contain:\n  ${emitted} AS ${col}`,
+    );
+  }
+  // The VIEW is a DROP+CREATE that supersedes 073/075, and keeps every base column as an aliased
+  // pass-through so the static pages↔schema contract guard still sees them.
+  assert(/DROP VIEW IF EXISTS feature_read_model;/.test(sql), "076 must DROP the superseded VIEW first");
+  assert(/CREATE VIEW feature_read_model AS/.test(sql), "076 must (re)create feature_read_model");
+  for (const base of ["feature_key", "status", "pr_key", "converge", "auto_merge", "acknowledged_at", "title", "repo"]) {
+    assert(sql.includes(`fr.${base} AS ${base}`), `076 must pass base column "${base}" through the VIEW`);
+  }
+});
+
+test("FRAMEWORK PARITY GUARD: featureReadModel's SQL and TS lowerings agree over the full status × open-task matrix (assertReadModelParity)", () => {
+  const samples: ParitySample[] = [];
+  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"]) {
+          for (const acknowledged_at of [null, "2026-02-02T00:00:00Z"]) {
+            const el = status === "escalated" ? "feature-escalation" : status === "awaiting_operator" ? "feature-blocked" : null;
+            for (const openTask of el !== null ? [false, true] : [false]) {
+              const userTasks =
+                openTask && el !== null ? [{ subject_type: "feature", subject_key: "self", element_id: el }] : [];
+              samples.push({
+                baseRow: { feature_key: "self", status, pr_key, converge, auto_merge, acknowledged_at },
+                projections: { user_tasks: userTasks },
+              });
+            }
+          }
+        }
+      }
+    }
+  }
+  // A bare in-memory handle: the guard builds/drops its OWN TEMP fixtures, so it needs no schema.
+  const db = new DatabaseSync(":memory:");
+  assertReadModelParity(featureReadModel, parityDb(db), samples);
+  db.close();
+});
+
+test("the migration 076 VIEW derives stage/stage_state/stage_skipped/attention EXACTLY like deriveStage, over every status × converge/auto_merge/pr_key × open-task combination", () => {
   const db = viewDb();
   const cases: Array<{ key: string; run: SampleRun; hasOpenBlockedTask: boolean; hasOpenEscalationTask: boolean }> = [];
   let i = 0;
@@ -123,10 +181,7 @@ test("feature_read_model derives stage/stage_state/stage_skipped/attention EXACT
       for (const auto_merge of [0, 1]) {
         for (const pr_key of [null, `o/r#pr${i}`]) {
           // The open-task dimension only matters for the two human-wait statuses (escalated/
-          // awaiting_operator), whose derivation reads open tasks — for them exercise BOTH
-          // task-present and task-absent (the #422 drift case = the task already gone). Every other
-          // status ignores open tasks (`el` is null, so no task is ever created), so iterating the
-          // dimension there would only duplicate identical cases; iterate [false] alone.
+          // awaiting_operator); every other status ignores open tasks, so iterate [false] alone there.
           const el = status === "escalated" ? "feature-escalation" : status === "awaiting_operator" ? "feature-blocked" : null;
           for (const openTask of el !== null ? [false, true] : [false]) {
             const key = `o/r#${i++}`;
@@ -162,7 +217,7 @@ test("feature_read_model derives stage/stage_state/stage_skipped/attention EXACT
   }
 });
 
-test("feature_read_model derives list_bucket EXACTLY like deriveListBucket (history iff terminal AND acknowledged)", () => {
+test("the migration 076 VIEW 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 }> = [];
@@ -182,7 +237,7 @@ test("feature_read_model derives list_bucket EXACTLY like deriveListBucket (hist
   }
 });
 
-test("feature_read_model IGNORES any stale STORED projection columns — it reads only from status et al.", () => {
+test("the migration 076 VIEW 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", {
@@ -202,10 +257,10 @@ test("feature_read_model IGNORES any stale STORED projection columns — it read
 test("RED/GREEN GUARD #422: an ANSWERED escalation (status sticky 'escalated', no open user task) shows NO ⚠; the badge tracks the OPEN task, not status", () => {
   // The `feature` process answer-loop returns the token to `implement-task` without resetting the
   // `status` variable, so a run whose escalation was already answered still reads `status="escalated"`
-  // until its next agent job completes (observed live on merlin: feature instance 31779). The OLD VIEW
-  // derived `attention` from that value and rendered a stale ⚠ on Overview. The badge now derives from
-  // engine truth — the presence of an OPEN `feature-escalation` user task (`pollUserTasks` deletes the
-  // row the moment it is answered) — so it clears immediately regardless of the stale status.
+  // until its next agent job completes (observed live on merlin: feature instance 31779). The badge
+  // now derives from engine truth — the presence of an OPEN `feature-escalation` user task
+  // (`pollUserTasks` deletes the row the moment it is answered) — so it clears immediately regardless
+  // of the stale status.
   const db = viewDb();
 
   // Answered escalation: status STILL 'escalated' (stale) + a stored ⚠ that lied, but NO open task.
@@ -233,44 +288,32 @@ test("RED/GREEN GUARD #422: an ANSWERED escalation (status sticky 'escalated', n
 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.
+  // bypassing the (now retired) projecting `featureRuns` gateway. Because the projection is 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");

package/app/featureReadModel.ts

@@ -0,0 +1,152 @@
+// The `feature_read_model` derived read model — DECLARED ONCE and compiled to BOTH backends via
+// Urban's ADR-0065 reconciling-read-model primitive (`defineReadModel`, `@nanobpm/urban`).
+//
+// Background (issues #412 → #439 → #422). The Feature Runs surface renders DERIVED state — a run's
+// pipeline `stage`, its `stage_state`/`stage_skipped`, its `attention` badge, its Active/History
+// `list_bucket`. None of these are ground truth: each is a pure function of the row's own
+// `status`/`pr_key`/`converge`/`auto_merge`/`acknowledged_at` plus, for `attention`, the engine's
+// open-user-task set. #412/#439 retired the WRITE-TIME denormalised projection into a SQLite VIEW
+// (`feature_read_model`) so no writer can freeze a stored column; #458 (migration 075) then re-pointed
+// `attention` off the drift-prone `status` variable onto ENGINE TRUTH — an OPEN `user_tasks` row.
+//
+// Two drift surfaces survived that hand-wired VIEW (ADR-0065, nano-ide#452):
+//   * #2 — every derived column was authored TWICE: the SQL `CASE`/`EXISTS` inside the migration VIEW
+//     AND the TypeScript oracle (`deriveStage`/`deriveListBucket`, app/stage.ts), kept in lockstep by
+//     a hand-written parity test. The lockstep test does not remove the duplication; it only alarms
+//     when the two copies diverge.
+//   * #3 — the migration, the VIEW DDL and the parity test were all hand-wired per projection.
+//
+// This module closes surface #2 STRUCTURALLY (ADR-0065 rollout step 2 — "declare once → compile to
+// both", no engine-truth change): each derivation is expressed ONCE in Urban's closed expression DSL,
+// and Urban compiles it to BOTH the SQLite VIEW select-list (`sqlSelectFor` — emitted verbatim into
+// migration 076, drift-guarded) AND the runtime TS function (`fnFor` — the sole engine behind the
+// `deriveStage`/`deriveListBucket` adapters in app/stage.ts). There is nothing left to keep in
+// lockstep: the two lowerings fall out of the SAME AST, and `assertReadModelParity` (app/
+// featureReadModel.test.ts) is now a framework-owned regression guard that the two lowerings agree,
+// not an app-authored mirror of two hand-maintained copies.
+//
+// SCOPE (step 2). The `attention` derivation reads the app's own `user_tasks` inbox by name (the same
+// engine-truth source migration 075 used) via the DSL's `exists(...)`; promoting that to the framework
+// canonical `urban_open_user_tasks` projection and inverting `instanceTracking` writer→source are the
+// LATER ADR-0065 rollout steps (3/4), deliberately out of scope here.
+
+import { and, caseWhen, col, defineReadModel, type Expr, eq, exists, lit, neq, not, or, pcol, type ReadModel, when } from "@nanobpm/urban";
+
+/** The 6 TRULY-terminal statuses that map to the `Done` stage — the single source of truth for the
+ * terminal tier of BOTH the pipeline `stage`/`stage_state` derivations and the `list_bucket` history
+ * partition. Distinct from `FEATURE_TERMINAL_STATUSES` (app/feature.ts), the redispatch-settled set,
+ * which also counts `opened`/`converging` as terminal — those are LIVE pipeline stages (`PR open`/
+ * `Converging`), NOT `Done`, so the two lists must stay separate. Re-exported from app/stage.ts for
+ * back-compat with its existing importers. */
+export const STAGE_DONE_STATUSES: readonly string[] = ["merged", "converged", "blocked", "failed", "skipped", "abandoned"];
+
+/** The DSL projection name the `attention` derivation `exists(...)`-reads. Unregistered in the
+ * `projectionRegistry`, so it resolves to the same-named physical table — the app's own `user_tasks`
+ * inbox (034_user_tasks_inbox.sql), reconciled by `pollUserTasks` (app/service.ts): a row exists IFF a
+ * native operator user task is currently OPEN, deleted the moment it closes. (ADR-0065 step 3 will
+ * promote this to the framework's canonical `urban_open_user_tasks` projection.) */
+export const USER_TASKS_PROJECTION = "user_tasks";
+
+/** `status IN (…)` as a closed-DSL predicate: an OR of equalities over the base row's `status`. */
+const statusIn = (...statuses: readonly string[]): Expr => or(...statuses.map((s) => eq(col("status"), lit(s))));
+
+/** The terminal tier — the row's `status` is one of the 6 `Done` statuses. */
+const isDone: Expr = statusIn(...STAGE_DONE_STATUSES);
+
+/** The canonical pipeline `stage`. TOTAL over all 11 statuses. Terminal → `Done`; else `converging`
+ * → `Converging`; else a raised PR (`pr_key` set, mirroring `(pr_key ?? "") !== ""`) or `opened` →
+ * `PR open`; else a live/parked implementation status → `Implementing`; else `Requested`. */
+const stage: Expr = caseWhen(
+  [
+    when(isDone, lit("Done")),
+    when(eq(col("status"), lit("converging")), lit("Converging")),
+    when(or(neq(col("pr_key"), lit("")), eq(col("status"), lit("opened"))), lit("PR open")),
+    when(statusIn("running", "escalated", "awaiting_operator"), lit("Implementing")),
+  ],
+  lit("Requested"),
+);
+
+/** The active stage's render state in the `kind:"pipeline"` column's vocabulary: `ok` (merged/
+ * converged), `blocked` (terminal blocked), `failed` (failed/skipped/abandoned), else NULL (in
+ * progress). A pure function of `status`, so it is correct even for a parked/live status (NULL). */
+const stageState: Expr = caseWhen(
+  [
+    when(statusIn("merged", "converged"), lit("ok")),
+    when(eq(col("status"), lit("blocked")), lit("blocked")),
+    when(statusIn("failed", "skipped", "abandoned"), lit("failed")),
+  ],
+  lit(null),
+);
+
+/** The space-separated set of pipeline stages NOT in this row's path, purely from `converge`/
+ * `auto_merge`: no converge ⇒ both `Converging` and `Merging` are skipped; converge but no auto-merge
+ * ⇒ only `Merging`; else none. (`not(col(...))` mirrors the TS `!truthy(...)` under the shared
+ * "NULL → false" rule.) */
+const stageSkipped: Expr = caseWhen(
+  [
+    when(not(col("converge")), lit("Converging Merging")),
+    when(not(col("auto_merge")), lit("Merging")),
+  ],
+  lit(""),
+);
+
+/** The correlation predicate for an OPEN operator user task of `elementId` on this feature run: a
+ * `user_tasks` row keyed `subject_type='feature'`, `subject_key=<this row's feature_key>` (how
+ * `pollUserTasks` keys them — app/service.ts `DEFAULT_SUBJECT_TYPE`/`contextFor`). */
+const openTaskWhere = (elementId: string): Expr =>
+  and(eq(pcol("subject_type"), lit("feature")), eq(pcol("subject_key"), col("feature_key")), eq(pcol("element_id"), lit(elementId)));
+
+/** The `attention` badge, derived from ENGINE TRUTH — the presence of an OPEN native user task — NOT
+ * from the drift-prone `status` variable (issue #422). `blocked` glyph IFF an open `feature-blocked`
+ * task exists; `⚠` IFF an open `feature-escalation` task exists; else no badge. Once a task is
+ * answered its `user_tasks` row is gone, so the badge clears immediately even while `status` still
+ * reads a stale `"escalated"` on the answer-loop back into `implement-task`. */
+const attention: Expr = caseWhen(
+  [
+    when(exists(USER_TASKS_PROJECTION, openTaskWhere("feature-blocked")), lit("blocked")),
+    when(exists(USER_TASKS_PROJECTION, openTaskWhere("feature-escalation")), lit("⚠")),
+  ],
+  lit(null),
+);
+
+/** `<col> IS NOT NULL` in the closed DSL, which has no dedicated null-test operator: a SELF-equality.
+ * `eq` collapses a nullish operand to false in BOTH backends (`COALESCE(x = x, 0)` in SQL, the nullish
+ * guard in `compareValues` for TS), and any NON-null value equals itself, so this is true IFF the column
+ * is non-NULL — faithful to 073/075's `acknowledged_at IS NOT NULL` and free of the SQLite string→number
+ * truthiness coercion a bare `col(...)` boolean predicate would otherwise rely on (e.g. `''`/`'abc'`). */
+const isNotNull = (name: string): Expr => eq(col(name), col(name));
+
+/** The Active/History partition: `history` IFF the row is in a truly-terminal status AND has been
+ * acknowledged; otherwise `active` (live runs + terminal-but-UNACKNOWLEDGED runs). `acknowledged_at IS
+ * NOT NULL` is expressed via {@link isNotNull} so it stays byte-equivalent to 073/075's VIEW and does
+ * not depend on string→number coercion in either backend. */
+const listBucket: Expr = caseWhen([when(and(isDone, isNotNull("acknowledged_at")), lit("history"))], lit("active"));
+
+/** The keys of {@link featureReadModel}'s DERIVED columns, in the order migration 076 emits them.
+ * Base columns are identity pass-throughs (not derivations) and are listed in the migration directly. */
+export const FEATURE_READ_MODEL_DERIVED = ["stage", "stage_state", "stage_skipped", "attention", "list_bucket"] as const;
+export type FeatureReadModelDerivedColumn = (typeof FEATURE_READ_MODEL_DERIVED)[number];
+
+/**
+ * The declare-once `feature_read_model` derived columns. `selectBaseColumns: false` because the base
+ * columns are plain identity pass-throughs enumerated in migration 076 (so the static pages↔schema
+ * contract guard, which reads a VIEW's columns off an aliased select-list, sees them); this model owns
+ * only the five real DERIVATIONS. Both the migration VIEW (`sqlSelectFor`, drift-guarded) and the
+ * runtime TS oracle (`fnFor`, behind app/stage.ts) are generated from THIS single declaration.
+ */
+export const featureReadModel: ReadModel = defineReadModel({
+  name: "feature_read_model",
+  baseTable: "feature_runs",
+  selectBaseColumns: false,
+  derive: {
+    stage,
+    stage_state: stageState,
+    stage_skipped: stageSkipped,
+    attention,
+    list_bucket: listBucket,
+  },
+});
+
+/** The base alias the managed VIEW gives `feature_runs` — pinned so the emitted derived-column SQL
+ * (`fr."col"`) matches migration 076 exactly (the drift guard compares against this alias). */
+export const FEATURE_READ_MODEL_BASE_ALIAS = "fr";

package/app/service.ts

@@ -28,6 +28,7 @@ import {
 } from "./conformance.ts";
 import { isUniqueConstraintFence } from "./dbFence.ts";
 import { deriveDelivery, TERMINAL_STATUSES } from "./delivery.ts";
+import { sweepExpiredProposals } from "./deliveryGraphProposals.ts";
 import { deliveryGraphRuns, deriveDeliveryPhase, parseHumanLabels } from "./deliveryGraphRun.ts";
 import { isDeliveryHumanElement } from "./deliveryHuman.ts";
 import { fleetSupportsDurableResume } from "./durableResume.ts";
@@ -2304,6 +2305,19 @@ export async function pollDeliveryGraphPhase(
   }
 }
 
+/** Poll pass (ADR 0005 Decision 7): age out staged delivery-graph proposals whose TTL has elapsed by
+ * flipping them to `expired`, so they drop out of the cockpit's staged grid rather than lingering there
+ * only to fail dispatch. The grid filters purely on `status = 'staged'` (its datasource cannot express an
+ * `expires_at > now` comparison), so this reconciliation sweep is what realises the proposal TTL. It is
+ * data-only and idempotent — a proposal already terminal is left untouched. */
+export async function pollDeliveryProposals(data: DataLayer) {
+  try {
+    await sweepExpiredProposals(data);
+  } catch (err) {
+    console.error(`[poller] delivery graph proposals sweep: ${err}`);
+  }
+}
+
 export async function pollUserTasks(
   data: DataLayer,
   engine: EngineClient,
@@ -2479,6 +2493,7 @@ export async function pollOnce(
   await pollLineage(data);
   await pollUserTasks(data, engine, engineRest);
   await pollDeliveryGraphPhase(data, engine);
+  await pollDeliveryProposals(data);
   if (engineRest) {
     const base = engineRest.restAddress.replace(/\/+$/, "");
     const headers: Record<string, string> = { "content-type": "application/json" };