@nanobpm/nano-workforce 0.167.1 → 0.167.3

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.167.3](https://github.com/nanobpm/nano-workforce/compare/v0.167.2...v0.167.3) (2026-08-31)
+
+### Bug Fixes
+
+* **acknowledge:** gate all four ack ops on read-model ack_open via one shared helper ([#654](https://github.com/nanobpm/nano-workforce/issues/654)) ([#655](https://github.com/nanobpm/nano-workforce/issues/655)) ([598aa80](https://github.com/nanobpm/nano-workforce/commit/598aa80470d307c7499caa26bc9b6137c6daf1fa)), closes [#652](https://github.com/nanobpm/nano-workforce/issues/652)
+
+## [0.167.2](https://github.com/nanobpm/nano-workforce/compare/v0.167.1...v0.167.2) (2026-08-31)
+
+### Bug Fixes
+
+* gate acknowledgePr on the read model's folded status, not the base column ([#653](https://github.com/nanobpm/nano-workforce/issues/653)) ([80446e2](https://github.com/nanobpm/nano-workforce/commit/80446e24af3c62570c041a109eef85eb34f8bb23)), closes [#652](https://github.com/nanobpm/nano-workforce/issues/652)
+
 ## [0.167.1](https://github.com/nanobpm/nano-workforce/compare/v0.167.0...v0.167.1) (2026-08-31)
 
 ### Bug Fixes

package/app/acknowledge.ts

@@ -0,0 +1,98 @@
+// The ONE shared "operator dismiss / tick-off" acknowledge helper, gating every acknowledge op on the
+// read model's derived `ack_open` (issue #654). Introduced to kill a CATEGORICAL drift: each of the
+// four acknowledge/dismiss ops (`acknowledgePr` / `acknowledgeDone` / `acknowledgeDeliveryGraph` /
+// `acknowledgeEpic`) used to re-derive terminality from its BASE `status` column, while the Dismiss
+// affordance the UI renders reads the read model's `ack_open` (folded from the terminal-folded
+// `derived_status`). When base ≠ derived — any out-of-band terminate freezes base `status` at
+// `running`/`escalated`/`dispatched` while the read model folds `derived_status='abandoned'` — the
+// button showed "Dismiss" but the op 409'd "not terminal" (manifested for PR, #652; latent for the
+// other three).
+//
+// The fix: gate on the SAME `ack_open` the button consumes, so the affordance and the guard read one
+// oracle and cannot drift. Each op collapses to a one-liner passing its own read-model VIEW + key
+// column; this helper does the rest:
+//
+//   1. Look up the row in the read-model VIEW (the `..._read_model` VIEW exposing `ack_open`) by key.
+//   2. 404 if the row is absent.
+//   3. 409 if `ack_open !== 1` and the row is NOT already acknowledged (a live / non-dismissable row).
+//   4. An already-acknowledged row (`ack_open=0` because `acknowledged_at` is set) is an idempotent
+//      no-op → 200 (no double-stamp), not an error.
+//   5. Stamp `acknowledged_at = now()` (+ `updated_at`) on the base RECORD table (writes never go to
+//      the VIEW). The VIEW then folds the row to `list_bucket='history'` / `ack_open=0` at read time.
+
+import type { AppApi } from "@nanobpm/urban";
+
+/** A dismissable surface: the read-model VIEW the Dismiss affordance + this guard both read `ack_open`
+ * off, the base RECORD table the `acknowledged_at` stamp lands on, the primary-key column both are
+ * keyed on, and a human label for the log/error text. */
+export interface AckSurface {
+  /** The read-model VIEW exposing the derived `ack_open` + pass-through `acknowledged_at` — the SINGLE
+   * oracle the page's `showWhenField` Dismiss button also consumes (so guard and button cannot drift). */
+  readonly view: string;
+  /** The base RECORD table the `acknowledged_at` stamp is written to (urban forbids writing a VIEW). */
+  readonly baseTable: string;
+  /** The primary-key column both the VIEW and the base table are keyed on. */
+  readonly keyColumn: string;
+  /** Human-readable noun for the op's log lines and 404/409 error bodies (e.g. "pull request"). */
+  readonly label: string;
+  /** The 409 error message for a NON-dismissable (still-live / not-terminal) row. */
+  readonly notDismissableError: string;
+}
+
+/** The row shape the helper reads off the read-model VIEW. */
+interface AckViewRow {
+  ack_open: number | null;
+  acknowledged_at: string | null;
+}
+
+/** The uniform op result the four acknowledge ops return verbatim. */
+export interface AckResult {
+  status: number;
+  body: { ok: boolean; error?: string; message?: string };
+}
+
+/**
+ * Acknowledge (operator-dismiss / tick-off) the `key` row of a dismissable {@link AckSurface}, gating
+ * on the read model's derived `ack_open` — the ONE oracle the Dismiss button also reads, so the guard
+ * and the affordance cannot drift (issue #654). Returns the uniform op result:
+ *
+ * - 404 — no such row in the read-model VIEW.
+ * - 200 (idempotent no-op) — the row is already acknowledged (`acknowledged_at` set), so re-dismissing
+ *   is a no-op that does NOT re-stamp.
+ * - 409 — the row is not dismissable (`ack_open=0` and not acknowledged: still live / non-terminal).
+ * - 200 (stamped) — `ack_open=1`: stamp `acknowledged_at = now()` on the base record table; the VIEW
+ *   folds the row to History (`list_bucket='history'`, `ack_open=0`) on the next read.
+ */
+export async function acknowledgeVia(app: AppApi, surface: AckSurface, key: string): Promise<AckResult> {
+  const view = app.data.table<AckViewRow>(surface.view, surface.keyColumn);
+  const row = await view.get(key);
+  if (!row) {
+    app.log.warn(`acknowledge: no such ${surface.label}`, { key });
+    return { status: 404, body: { ok: false, error: `no such ${surface.label}` } };
+  }
+
+  // The button and this guard consume the SAME derived `ack_open` from the SAME read-model VIEW, so
+  // they cannot drift: `ack_open=1` ⇔ the row is terminal-folded AND not yet acknowledged ⇔ dismissable.
+  if (Number(row.ack_open) !== 1) {
+    // `ack_open=0` is EITHER an already-acknowledged terminal row OR a still-live / non-terminal one.
+    // An already-acknowledged row (its `acknowledged_at` set — the whole reason `ack_open` folded to 0)
+    // is an idempotent no-op → 200, NOT an error; we do not re-stamp it.
+    if (row.acknowledged_at != null) {
+      app.log.info(`${surface.label} already acknowledged — idempotent no-op`, { key });
+      return { status: 200, body: { ok: true, message: "acknowledged" } };
+    }
+    app.log.warn(`acknowledge rejected: ${surface.label} is not dismissable`, { key });
+    return { status: 409, body: { ok: false, error: surface.notDismissableError } };
+  }
+
+  // Stamp the dismissal on the base RECORD table (never the VIEW). `list_bucket` (→ 'history') and
+  // `ack_open` (→ 0) are derived by the read-model VIEW from the now-acknowledged row, so we never
+  // hand-set them here.
+  const now = new Date().toISOString();
+  await app.data
+    .table<{ acknowledged_at: string | null; updated_at: string }>(surface.baseTable, surface.keyColumn)
+    .update(key, { acknowledged_at: now, updated_at: now });
+
+  app.log.info(`operator acknowledged ${surface.label}`, { key });
+  return { status: 200, body: { ok: true, message: "acknowledged" } };
+}

package/app/featureReadModel.test.ts

@@ -31,7 +31,7 @@ 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"));
 
-const MIGRATION_LATEST = "081_feature_read_model_derive_terminal.sql";
+const MIGRATION_LATEST = "099_feature_read_model_ack_open.sql";
 
 // The base `feature_runs` shape the VIEW reads, plus the `user_tasks` inbox (034) the `attention`
 // derivation `EXISTS`-reads, plus a stand-in for the managed `feature_runs__tracking` derived VIEW
@@ -118,7 +118,7 @@ function addRun(db: DatabaseSync, feature_key: string, run: SampleRun): void {
 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 = ?",
+      "SELECT stage, stage_state, stage_skipped, attention, list_bucket, ack_open FROM feature_read_model WHERE feature_key = ?",
     )
     .get(feature_key) as Record<string, unknown>;
   return { ...r };
@@ -267,6 +267,7 @@ test("the migration 080 VIEW IGNORES any stale STORED projection columns — it
     stage_skipped: "Converging Merging",
     attention: null,
     list_bucket: "history",
+    ack_open: 0,
   });
 });
 
@@ -323,7 +324,8 @@ test("RED/GREEN GUARD: a RAW-datasource feature_runs.status write (the instanceT
   assertEquals(row.stage_state, oracle.state);
   assertEquals(row.attention, null, "the stale ⚠ badge is gone");
   assertEquals(row.attention, oracle.attention);
-  assert(row.stage_state != null, "Dismiss is renderable (stage_state is non-null) so the run can be ticked off");
+  assert(row.stage_state != null, "the run is terminal (stage_state is non-null)");
+  assertEquals(row.ack_open, 1, "Dismiss is renderable (ack_open=1) so the run can be ticked off");
   assertEquals(row.list_bucket, "active", "a just-cancelled run sits in Active until dismissed");
   assertEquals(row.list_bucket, deriveListBucket("abandoned", null));
 });
@@ -355,6 +357,7 @@ test("RED/GREEN #503: a DERIVE-ONLY terminated run (base status frozen at 'runni
   assertEquals(row.stage_state, oracle.state);
   assertEquals(row.attention, null, "the stale ⚠ badge is gone once the run is terminated");
   assertEquals(row.list_bucket, "active", "a just-cancelled run sits in Active until dismissed");
+  assertEquals(row.ack_open, 1, "the derive-only terminated run is dismissable (ack_open=1) though base status is frozen non-terminal");
 });
 
 test("the Feature page binds the derived feature_read_model VIEW (not the raw feature_runs table)", () => {

package/app/featureReadModel.ts

@@ -31,7 +31,7 @@
 // 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";
-import { deriveListBucketExpr } from "./listBucket.ts";
+import { deriveAckOpenExpr, deriveListBucketExpr } from "./listBucket.ts";
 
 /** 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
@@ -137,16 +137,25 @@ const attention: Expr = caseWhen(
  * reproduces this model's `isDone`/`isNotNull` forms exactly). */
 const listBucket: Expr = deriveListBucketExpr(EFFECTIVE_STATUS_COLUMN, STAGE_DONE_STATUSES);
 
-/** The keys of {@link featureReadModel}'s DERIVED columns, in the order migration 076 emits them.
+/** The operator "Dismiss" (tick-off) affordance flag — `1` IFF the run is terminal AND not yet
+ * acknowledged (so the page's `showWhenField` Dismiss button renders only for a terminal-but-
+ * unacknowledged run), else `0`. The feature twin of the PR/Delivery-Graph/Epic `ack_open`, from the
+ * ONE shared oracle (app/listBucket.ts, issue #641) parameterised by the SAME {@link
+ * STAGE_DONE_STATUSES} terminal set `list_bucket` uses — so the Dismiss button and the
+ * `acknowledgeDone` guard consume the identical predicate and cannot drift (issue #654). */
+const ackOpen: Expr = deriveAckOpenExpr(EFFECTIVE_STATUS_COLUMN, STAGE_DONE_STATUSES);
+
+/** The keys of {@link featureReadModel}'s DERIVED columns, in the order migration 099 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 const FEATURE_READ_MODEL_DERIVED = ["stage", "stage_state", "stage_skipped", "attention", "list_bucket", "ack_open"] 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
+ * columns are plain identity pass-throughs enumerated in the latest superseding migration (099, which
+ * re-emits the whole VIEW body — see also 076/081) (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
+ * only the six 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({
@@ -159,6 +168,7 @@ export const featureReadModel: ReadModel = defineReadModel({
     stage_skipped: stageSkipped,
     attention,
     list_bucket: listBucket,
+    ack_open: ackOpen,
   },
 });
 

package/app/planReadModel.test.ts

@@ -29,19 +29,26 @@ import { DatabaseSync } from "node:sqlite";
 import { test } from "node:test";
 import { fileURLToPath } from "node:url";
 import { assertReadModelParity, assertRollupParity, type ParityDb, type ParitySample, type RollupInputs } from "@nanobpm/urban";
+import type { AppApi } from "@nanobpm/urban";
 import { assert, assertEquals } from "#test-assert";
+import { acknowledgeVia } from "./acknowledge.ts";
 import { deriveDelivery, deriveEpicBucket, epicIsAcknowledgeable } from "./delivery.ts";
 import { planReadModel, PLAN_READ_MODEL_BASE_ALIAS, PLAN_READ_MODEL_DERIVED } from "./planReadModel.ts";
 import { PLAN_ROLLUPS, planDeliveryCounts, planWaveCounts, planWaveProgress } from "./planRollups.ts";
+import { noopLog } from "../test/log.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"));
 
 const ROLLUPS_MIGRATION = "082_plan_rollups_declare_once.sql";
 const READ_MODEL_MIGRATION = "097_plan_read_model_terminal_dismiss.sql";
+// Passes `acknowledged_at` through the plan_read_model VIEW (issue #654) — the column the shared
+// `acknowledgeVia` helper reads to tell an already-acknowledged epic (idempotent 200) from a live one
+// (409). Supersedes 097's VIEW body verbatim except for that one added base pass-through.
+const READ_MODEL_ACK_PASSTHROUGH_MIGRATION = "100_plan_read_model_pass_acknowledged_at.sql";
 // The forward chain whose net effect the end-to-end tests exercise: the original hand-authored VIEWs
 // (059/060/061/074/080), the declare-once supersessions (082/083), then the terminal-dismiss
-// supersession (097). Mirrors the runtime migrator.
+// supersession (097), then the `acknowledged_at` pass-through (100). Mirrors the runtime migrator.
 const MIGRATION_CHAIN = [
   "059_plan_wave_summary.sql",
   "060_plan_wave_rollup.sql",
@@ -52,6 +59,7 @@ const MIGRATION_CHAIN = [
   "083_plan_read_model_declare_once.sql",
   "084_plan_wave_tasks_effective_status.sql",
   READ_MODEL_MIGRATION,
+  READ_MODEL_ACK_PASSTHROUGH_MIGRATION,
 ];
 
 // The base `plans` / `plan_tasks` / `pull_requests` shapes the VIEWs read, plus a stand-in for the
@@ -209,6 +217,77 @@ test("DRIFT GUARD: migration 097 embeds each derived column VERBATIM from planRe
   }
 });
 
+// A minimal `AppApi` over node:sqlite so the shared `acknowledgeVia` helper (app/acknowledge.ts) can be
+// driven against the REAL migration VIEW + base table — not a mock that could paper over a missing VIEW
+// column. `data.table(name, key)` reads/writes `name` keyed on `key`, exactly as urban's does.
+function sqliteApp(db: DatabaseSync): AppApi {
+  return {
+    data: {
+      table: (name: string, key: string) => ({
+        get: async (id: unknown) => db.prepare(`SELECT * FROM ${name} WHERE ${key} = ?`).get(id) ?? undefined,
+        update: async (id: unknown, patch: Record<string, unknown>) => {
+          const cols = Object.keys(patch);
+          const set = cols.map((c) => `${c} = ?`).join(", ");
+          const r = db.prepare(`UPDATE ${name} SET ${set} WHERE ${key} = ?`).run(...(cols.map((c) => patch[c]) as never[]), id as never);
+          return Number(r.changes);
+        },
+      }),
+    },
+    log: noopLog(),
+  } as unknown as AppApi;
+}
+
+const EPIC_ACK_SURFACE = {
+  view: planReadModel.decl.name,
+  baseTable: "plans",
+  keyColumn: "plan_key",
+  label: "epic",
+  notDismissableError: "not terminal",
+} as const;
+
+test("DRIFT GUARD: migration 100 supersedes the plan_read_model VIEW, adding the acknowledged_at pass-through while re-embedding every derived column VERBATIM from planReadModel.sqlSelectFor", () => {
+  const sql = MIG(READ_MODEL_ACK_PASSTHROUGH_MIGRATION);
+  assert(/DROP VIEW IF EXISTS plan_read_model;/.test(sql), "100 must DROP the superseded plan_read_model first");
+  assert(/CREATE VIEW plan_read_model AS/.test(sql), "100 must (re)create plan_read_model");
+  // The one reason this migration exists: expose `acknowledged_at` as a projected column (the shared
+  // acknowledgeVia helper reads it to distinguish an already-acknowledged epic from a live one).
+  assert(sql.includes("pl.acknowledged_at AS acknowledged_at"), "100 must PROJECT the acknowledged_at pass-through");
+  // Every derived column stays byte-identical to the declaration — no drift is smuggled in.
+  for (const col of PLAN_READ_MODEL_DERIVED) {
+    const emitted = planReadModel.sqlSelectFor(col, { baseAlias: PLAN_READ_MODEL_BASE_ALIAS });
+    assert(
+      sql.includes(`${emitted} AS ${col}`),
+      `migration ${READ_MODEL_ACK_PASSTHROUGH_MIGRATION} no longer embeds the declaration's SQL for "${col}" — regenerate it ` +
+        `from app/planReadModel.ts (or add a new superseding migration). Expected to contain:\n  ${emitted} AS ${col}`,
+    );
+  }
+  for (const base of ["plan_key", "repo", "issue_number", "title", "process_key", "epic_phase", "promotion_pr", "promotion_state"]) {
+    assert(sql.includes(`pl.${base} AS ${base}`), `100 must keep base column "${base}" as a pass-through`);
+  }
+});
+
+test("issue #654: the plan_read_model VIEW PROJECTS acknowledged_at so acknowledgeVia can tell an already-acknowledged epic (idempotent 200) from a live one (409)", async () => {
+  const db = viewDb();
+  const stamp = "2026-02-02T00:00:00Z";
+  // A `done` epic already dismissed (its `acknowledged_at` stamped): the VIEW folds it to History with
+  // the Dismiss affordance closed (`ack_open=0`).
+  addPlan(db, "o/r#1", { status: "done", acknowledged_at: stamp });
+  const row = readModel(db, "o/r#1");
+  // The bug (Copilot review, PR #655): `plan_read_model` only READ `acknowledged_at` inside its CASE
+  // bodies and never PROJECTED it — unlike the PR / feature / delivery-graph read models — so the helper
+  // saw `undefined` and could not tell "already acknowledged" from "still live". Assert the projection.
+  assert("acknowledged_at" in row, "plan_read_model must PROJECT acknowledged_at (the helper depends on it)");
+  assertEquals(row.acknowledged_at, stamp);
+  assertEquals(row.ack_open, 0, "an acknowledged terminal epic has ack_open=0");
+
+  // End-to-end: re-dismissing an already-acknowledged epic through the REAL VIEW is an idempotent 200,
+  // NOT a spurious 409 — and it does not re-stamp.
+  const res = await acknowledgeVia(sqliteApp(db), EPIC_ACK_SURFACE, "o/r#1");
+  assertEquals(res.status, 200, "re-dismissing an already-acknowledged epic is an idempotent 200");
+  assertEquals(res.body.ok, true);
+  assertEquals(readModel(db, "o/r#1").acknowledged_at, stamp, "idempotent no-op must NOT re-stamp");
+});
+
 test("FRAMEWORK PARITY GUARD: each plan-family rollup's VIEW and TS reduce agree (assertRollupParity)", () => {
   // Sample leaf rows spanning: multi-wave plans, every task/PR status, dangling pr_key (no PR row),
   // un-levelized (NULL wave) tasks, and taskless plans — the predicates the rollups turn on.

package/app/pullRequestReadModel.ts

@@ -22,6 +22,11 @@
 import { defineReadModel, type Expr, type ReadModel } from "@nanobpm/urban";
 import { deriveAckOpenExpr, deriveListBucketExpr } from "./listBucket.ts";
 
+/** The read model's VIEW name — the single source of truth for the table an operation queries when it
+ * must gate on the folded/effective status (e.g. `acknowledgePr`, issue #652) rather than re-derive
+ * terminality off the frozen base `pull_requests.status` column. */
+export const PULL_REQUEST_READ_MODEL_NAME = "pull_requests_read_model";
+
 /** The base table the read model reads: the auto-provisioned `pull_requests__tracking` derived VIEW
  * (ADR-0065), NOT the raw `pull_requests` table — so the status-classifying derivations read the
  * terminal-folded `derived_status` and a terminated PR drops to History with no worker write. */
@@ -66,7 +71,7 @@ export type PullRequestReadModelDerivedColumn = (typeof PULL_REQUEST_READ_MODEL_
  * generated from THIS single declaration.
  */
 export const pullRequestReadModel: ReadModel = defineReadModel({
-  name: "pull_requests_read_model",
+  name: PULL_REQUEST_READ_MODEL_NAME,
   baseTable: PULL_REQUEST_READ_MODEL_BASE_TABLE,
   selectBaseColumns: false,
   derive: {

package/db/migrations/099_feature_read_model_ack_open.sql

@@ -0,0 +1,58 @@
+-- Feature-run read model: fold the operator "Dismiss" affordance flag `ack_open` into the
+-- `feature_read_model` VIEW (issue #654). SUPERSEDES 081's VIEW body — every DERIVED column is emitted
+-- VERBATIM from the ONE declaration in app/featureReadModel.ts, now extended with the shared Dismiss-
+-- affordance oracle (app/listBucket.ts `deriveAckOpenExpr`). 081 is a MERGED, IMMUTABLE migration —
+-- never edited; this is a NEW migration superseding its VIEW body (the same pattern by which 081
+-- superseded 076, and 096/097 added `ack_open` to the Delivery-Graph / Plan read models).
+--
+-- WHY. `acknowledgeDone` was the one acknowledge op still gating on the base `feature_runs.status`
+-- allowlist (`STAGE_DONE_STATUSES.includes(run.status)`) while its Dismiss button rendered off the
+-- read model — a latent twin of the PR drift (#652): when an out-of-band terminate freezes base
+-- `status` non-terminal but the tracking VIEW folds `derived_status='abandoned'`, the button showed
+-- Dismiss yet the op 409'd. Issue #654 gates every acknowledge op on the read model's `ack_open` (the
+-- single oracle both the button and the guard consume), which requires `feature_read_model` to expose
+-- `ack_open` uniformly with the other three surfaces. This VIEW adds that declared `ack_open` column.
+--
+-- Every DERIVED column below is emitted VERBATIM from `featureReadModel.sqlSelectFor(col,
+-- { baseAlias: "fr" })` (which ALSO drives the runtime TS via `fnFor`); the `stage`/`stage_state`/
+-- `stage_skipped`/`attention`/`list_bucket` bodies are unchanged from 081 and `ack_open` is the ONE new
+-- derived column (terminal ∧ unacknowledged, from the shared oracle over `STAGE_DONE_STATUSES`). The
+-- drift guard (app/featureReadModel.test.ts) fails if this file stops matching the declaration, and
+-- `assertReadModelParity` proves the SQL and TS lowerings agree.
+--
+-- SEMANTICS unchanged from 081 EXCEPT the one new `ack_open` column: the status-classifying columns
+-- still read the terminal-folded `feature_runs__tracking.derived_status`; base columns stay aliased
+-- identity pass-throughs; `acknowledged_at` still passes through so the read model can classify on it.
+--
+-- Forward-only VIEW redefinition (DROP then CREATE). `feature_runs__tracking` is the managed VIEW urban
+-- provisions at mount; SQLite does not validate a view body at CREATE time, so this migration (which
+-- runs before that mount) is created fine and resolves once the managed VIEW exists. The runner wraps
+-- each file in its own transaction, so this file must NOT contain BEGIN/COMMIT. Numbered after 098.
+
+DROP VIEW IF EXISTS feature_read_model;
+
+CREATE VIEW feature_read_model AS
+SELECT
+  fr.feature_key AS feature_key,
+  fr.repo AS repo,
+  fr.issue_number AS issue_number,
+  fr.issue_url AS issue_url,
+  fr.title AS title,
+  fr.base_branch AS base_branch,
+  fr.status AS status,
+  fr.process_key AS process_key,
+  fr.pr_key AS pr_key,
+  fr.converge AS converge,
+  fr.auto_merge AS auto_merge,
+  fr.outcome AS outcome,
+  fr.delivery_label AS delivery_label,
+  fr.acknowledged_at AS acknowledged_at,
+  fr.created_at AS created_at,
+  fr.updated_at AS updated_at,
+  CASE WHEN COALESCE((COALESCE(("fr"."derived_status" = 'merged'), 0) OR COALESCE(("fr"."derived_status" = 'converged'), 0) OR COALESCE(("fr"."derived_status" = 'blocked'), 0) OR COALESCE(("fr"."derived_status" = 'failed'), 0) OR COALESCE(("fr"."derived_status" = 'skipped'), 0) OR COALESCE(("fr"."derived_status" = 'abandoned'), 0)), 0) THEN 'Done' WHEN COALESCE(("fr"."derived_status" = 'converging'), 0) THEN 'Converging' WHEN COALESCE((COALESCE(("fr"."pr_key" <> ''), 0) OR COALESCE(("fr"."derived_status" = 'opened'), 0)), 0) THEN 'PR open' WHEN COALESCE((COALESCE(("fr"."derived_status" = 'running'), 0) OR COALESCE(("fr"."derived_status" = 'escalated'), 0) OR COALESCE(("fr"."derived_status" = 'awaiting_operator'), 0)), 0) THEN 'Implementing' ELSE 'Requested' END AS stage,
+  CASE WHEN COALESCE((COALESCE(("fr"."derived_status" = 'merged'), 0) OR COALESCE(("fr"."derived_status" = 'converged'), 0)), 0) THEN 'ok' WHEN COALESCE(("fr"."derived_status" = 'blocked'), 0) THEN 'blocked' WHEN COALESCE((COALESCE(("fr"."derived_status" = 'failed'), 0) OR COALESCE(("fr"."derived_status" = 'skipped'), 0) OR COALESCE(("fr"."derived_status" = 'abandoned'), 0)), 0) THEN 'failed' ELSE NULL END AS stage_state,
+  CASE WHEN (NOT COALESCE("fr"."converge", 0)) THEN 'Converging Merging' WHEN (NOT COALESCE("fr"."auto_merge", 0)) THEN 'Merging' ELSE '' END AS stage_skipped,
+  CASE WHEN EXISTS (SELECT 1 FROM "user_tasks" AS "__urban_proj_0" WHERE COALESCE((COALESCE(("__urban_proj_0"."subject_type" = 'feature'), 0) AND COALESCE(("__urban_proj_0"."subject_key" = "fr"."feature_key"), 0) AND COALESCE(("__urban_proj_0"."element_id" = 'feature-blocked'), 0)), 0)) THEN 'blocked' WHEN EXISTS (SELECT 1 FROM "user_tasks" AS "__urban_proj_0" WHERE COALESCE((COALESCE(("__urban_proj_0"."subject_type" = 'feature'), 0) AND COALESCE(("__urban_proj_0"."subject_key" = "fr"."feature_key"), 0) AND COALESCE(("__urban_proj_0"."element_id" = 'feature-escalation'), 0)), 0)) THEN '⚠' ELSE NULL END AS attention,
+  CASE WHEN COALESCE((COALESCE((COALESCE(("fr"."derived_status" = 'merged'), 0) OR COALESCE(("fr"."derived_status" = 'converged'), 0) OR COALESCE(("fr"."derived_status" = 'blocked'), 0) OR COALESCE(("fr"."derived_status" = 'failed'), 0) OR COALESCE(("fr"."derived_status" = 'skipped'), 0) OR COALESCE(("fr"."derived_status" = 'abandoned'), 0)), 0) AND COALESCE(("fr"."acknowledged_at" = "fr"."acknowledged_at"), 0)), 0) THEN 'history' ELSE 'active' END AS list_bucket,
+  CASE WHEN COALESCE((COALESCE((COALESCE(("fr"."derived_status" = 'merged'), 0) OR COALESCE(("fr"."derived_status" = 'converged'), 0) OR COALESCE(("fr"."derived_status" = 'blocked'), 0) OR COALESCE(("fr"."derived_status" = 'failed'), 0) OR COALESCE(("fr"."derived_status" = 'skipped'), 0) OR COALESCE(("fr"."derived_status" = 'abandoned'), 0)), 0) AND (NOT COALESCE(COALESCE(("fr"."acknowledged_at" = "fr"."acknowledged_at"), 0), 0))), 0) THEN 1 ELSE 0 END AS ack_open
+FROM feature_runs__tracking fr;

package/db/migrations/100_plan_read_model_pass_acknowledged_at.sql

@@ -0,0 +1,63 @@
+-- Plan (Epic) read model: pass `acknowledged_at` through the `plan_read_model` VIEW (issue #654).
+-- SUPERSEDES 097's VIEW body — every DERIVED column (`delivery`/`list_bucket`/`ack_open`) is emitted
+-- VERBATIM from the ONE declaration in app/planReadModel.ts, unchanged from 097; the ONLY difference is
+-- the added `pl.acknowledged_at AS acknowledged_at` base pass-through. 097 is a MERGED, IMMUTABLE
+-- migration — never edited; this is a NEW migration superseding its VIEW body (the same pattern by which
+-- 097 superseded 083's plan_read_model body, and 099 the feature_read_model body).
+--
+-- WHY. The shared `acknowledgeVia` helper (app/acknowledge.ts, #654) reads BOTH `ack_open` AND
+-- `acknowledged_at` off the read-model VIEW: `ack_open=0` is EITHER an already-acknowledged terminal row
+-- (idempotent no-op → 200) OR a still-live / non-terminal one (→ 409), and it disambiguates the two on
+-- whether `acknowledged_at` is set. The PR / feature / delivery-graph read models (094/099/096) each
+-- already pass `acknowledged_at` through, but `plan_read_model` only READ it inside the `list_bucket` /
+-- `ack_open` CASE bodies and never PROJECTED it — so `acknowledgeEpic` saw `row.acknowledged_at ===
+-- undefined` and re-dismissing an already-acknowledged epic incorrectly 409'd instead of returning the
+-- idempotent 200. This VIEW adds the missing pass-through so all four dismissable surfaces expose the
+-- same columns the one helper depends on (parity, no drift).
+--
+-- SEMANTICS unchanged from 097 EXCEPT the one added `acknowledged_at` pass-through: the status-
+-- classifying columns still read the terminal-folded `plans__tracking.derived_status`; base columns stay
+-- aliased identity pass-throughs; the derived `delivery`/`list_bucket`/`ack_open`/display columns are
+-- byte-identical to 097 (still drift-guarded against app/planReadModel.ts).
+--
+-- Forward-only VIEW redefinition (DROP then CREATE). `plans__tracking` is the managed VIEW urban
+-- provisions at mount; SQLite does not validate a view body at CREATE time, so this migration (which
+-- runs before that mount) is created fine and resolves once the managed VIEW exists. The runner wraps
+-- each file in its own transaction, so this file must NOT contain BEGIN/COMMIT. Numbered after 099.
+
+DROP VIEW IF EXISTS plan_read_model;
+
+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,
+  COALESCE(pl.derived_status, 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.acknowledged_at AS acknowledged_at,
+  CASE WHEN COALESCE(((NOT COALESCE(COALESCE(("pl"."status" = 'done'), 0), 0)) OR COALESCE((COALESCE("dc"."prs_opened", 0) = 0), 0)), 0) THEN NULL WHEN COALESCE((COALESCE("dc"."prs_in_flight", 0) > 0), 0) THEN 'converging' WHEN COALESCE((COALESCE("dc"."prs_merged", 0) = COALESCE("dc"."prs_opened", 0)), 0) THEN 'landed' ELSE NULL END AS delivery,
+  "wp"."wave_count" AS wave_count,
+  "wp"."current_wave" AS current_wave,
+  CASE WHEN COALESCE((COALESCE((COALESCE((COALESCE(("pl"."derived_status" = 'done'), 0) OR COALESCE(("pl"."derived_status" = 'failed'), 0) OR COALESCE(("pl"."derived_status" = 'abandoned'), 0)), 0) AND (NOT COALESCE(COALESCE((CASE WHEN COALESCE(((NOT COALESCE(COALESCE(("pl"."status" = 'done'), 0), 0)) OR COALESCE((COALESCE("dc"."prs_opened", 0) = 0), 0)), 0) THEN NULL WHEN COALESCE((COALESCE("dc"."prs_in_flight", 0) > 0), 0) THEN 'converging' WHEN COALESCE((COALESCE("dc"."prs_merged", 0) = COALESCE("dc"."prs_opened", 0)), 0) THEN 'landed' ELSE NULL END = 'converging'), 0), 0))), 0) AND COALESCE(("pl"."acknowledged_at" = "pl"."acknowledged_at"), 0)), 0) THEN 'history' ELSE 'active' END AS list_bucket,
+  CASE WHEN COALESCE((COALESCE((COALESCE((COALESCE(("pl"."derived_status" = 'done'), 0) OR COALESCE(("pl"."derived_status" = 'failed'), 0) OR COALESCE(("pl"."derived_status" = 'abandoned'), 0)), 0) AND (NOT COALESCE(COALESCE((CASE WHEN COALESCE(((NOT COALESCE(COALESCE(("pl"."status" = 'done'), 0), 0)) OR COALESCE((COALESCE("dc"."prs_opened", 0) = 0), 0)), 0) THEN NULL WHEN COALESCE((COALESCE("dc"."prs_in_flight", 0) > 0), 0) THEN 'converging' WHEN COALESCE((COALESCE("dc"."prs_merged", 0) = COALESCE("dc"."prs_opened", 0)), 0) THEN 'landed' ELSE NULL END = 'converging'), 0), 0))), 0) AND (NOT COALESCE(COALESCE(("pl"."acknowledged_at" = "pl"."acknowledged_at"), 0), 0))), 0) THEN 1 ELSE 0 END AS ack_open,
+  CASE
+    WHEN pl.status IS NOT 'done' OR COALESCE(dc.prs_opened, 0) = 0 THEN NULL
+    WHEN COALESCE(dc.prs_in_flight, 0) > 0 THEN dc.prs_merged || '/' || dc.prs_opened || ' slices merged, ' || dc.prs_in_flight || ' converging'
+    WHEN dc.prs_merged = dc.prs_opened THEN dc.prs_opened || '/' || dc.prs_opened || ' slices merged'
+    ELSE NULL
+  END AS delivery_label,
+  (wp.current_wave + 1) || '/' || wp.wave_count AS wave_label
+FROM plans__tracking pl
+LEFT JOIN plan_delivery_counts dc ON pl.plan_key = dc.plan_key
+LEFT JOIN plan_wave_progress wp ON pl.plan_key = wp.plan_key;