@nanobpm/nano-workforce 0.167.1 → 0.167.3

package/operations/acknowledge.parity.test.ts

@@ -0,0 +1,242 @@
+// Categorical parity test for the FOUR acknowledge/dismiss ops (issue #654), driven off the read
+// models' derived `ack_open` — NOT a hand-maintained per-op terminal-status list. It proves the ONE
+// shared `acknowledgeVia` helper (app/acknowledge.ts) gates every op on the SAME oracle the UI's
+// Dismiss button consumes (`ack_open`), so the affordance and the guard cannot drift.
+//
+// The bug this guards against (manifested for PR as #652, latent for the other three): each op used to
+// re-derive terminality from its BASE `status` column while the button read the read model's folded
+// `derived_status`. When an instance is terminated OUT-OF-BAND the base `status` freezes non-terminal
+// (`running`/`escalated`/`dispatched`) while the read model folds `derived_status='abandoned'` — so the
+// button showed Dismiss but the op 409'd "not terminal". Each surface's RED case below is exactly that
+// shape: a DERIVE-ONLY terminated row (base status frozen non-terminal, `derived_status='abandoned'`).
+//
+// FIDELITY. The fake `data.table(<view>)` computes each row's `ack_open`/`list_bucket` from the REAL
+// read model applied to the base store row (PR/feature/DG via `ReadModel.evaluate`; epic via the
+// `deriveEpicBucket`/`epicIsAcknowledgeable` oracles the `plan_read_model` VIEW mirrors) — so the fake
+// VIEW is genuinely the read model over the base row, and stamping `acknowledged_at` on the base store
+// re-folds the row to History on the next read, exactly as the SQL VIEW does in production.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import type { AppApi } from "@nanobpm/urban";
+import { acknowledgeVia } from "../app/acknowledge.ts";
+import { deliveryGraphReadModel, PR_COUNTS_LOOKUP } from "../app/deliveryGraphReadModel.ts";
+import { deriveEpicBucket, epicIsAcknowledgeable } from "../app/delivery.ts";
+import { featureReadModel, USER_TASKS_PROJECTION } from "../app/featureReadModel.ts";
+import { planReadModel } from "../app/planReadModel.ts";
+import { pullRequestReadModel } from "../app/pullRequestReadModel.ts";
+import { noopLog } from "../test/log.ts";
+import doneHandler from "./acknowledgeDone.ts";
+import dgHandler from "./acknowledgeDeliveryGraph.ts";
+import epicHandler from "./acknowledgeEpic.ts";
+import prHandler from "./acknowledgePr.ts";
+
+// biome-ignore lint/suspicious/noExplicitAny: test-only dynamic row shapes.
+type Row = any;
+// biome-ignore lint/suspicious/noExplicitAny: test-only op handler signature.
+type Handler = (ctx: any, app: AppApi) => Promise<any>;
+
+/** One dismissable surface under test: how to seed its base row, which VIEW the op reads `ack_open`
+ * off, and how that VIEW derives from the base row (the real read model, not a duplicated status set). */
+interface Surface {
+  readonly id: string;
+  /** The read-model VIEW name the op reads `ack_open` off. */
+  readonly view: string;
+  /** The base RECORD store the op stamps `acknowledged_at` onto. */
+  readonly baseStore: string;
+  /** The primary-key column both are keyed on. */
+  readonly keyColumn: string;
+  /** The op handler. */
+  readonly handler: Handler;
+  /** The op's request-body key field (for 400/200 bodies). */
+  readonly bodyKey: string;
+  /** Base row for a DERIVE-ONLY terminated (dismissable) row: base `status` frozen NON-terminal, the
+   * derive edge folds `derived_status='abandoned'` — the exact out-of-band-terminate shape that
+   * manifested for PR. Extra join fields (`delivery`) let the epic VIEW fold from its slices. */
+  readonly terminalRow: (key: string) => Row;
+  /** Base row for a LIVE, non-dismissable row (`ack_open=0`, unacknowledged). */
+  readonly liveRow: (key: string) => Row;
+  /** Compute the read-model VIEW row (`ack_open`/`list_bucket` + pass-throughs) from the base row —
+   * the REAL read model over the base row. */
+  readonly deriveView: (baseRow: Row) => Row;
+}
+
+/** The effective (terminal-folded) status the tracking VIEW exposes: an explicit `derived_status`
+ * override (a terminated instance) else the frozen base `status` (the `ELSE base.status` branch). */
+const effective = (row: Row): string => row.derived_status ?? row.status;
+
+const SURFACES: Surface[] = [
+  {
+    id: "acknowledgePr",
+    view: pullRequestReadModel.decl.name,
+    baseStore: "pull_requests",
+    keyColumn: "pr_key",
+    handler: prHandler as Handler,
+    bodyKey: "pr_key",
+    terminalRow: (key) => ({ pr_key: key, status: "converging", derived_status: "abandoned", acknowledged_at: null }),
+    liveRow: (key) => ({ pr_key: key, status: "converging", acknowledged_at: null }),
+    deriveView: (r) => ({ ...r, ...pullRequestReadModel.evaluate({ ...r, derived_status: effective(r) }) }),
+  },
+  {
+    id: "acknowledgeDone",
+    view: featureReadModel.decl.name,
+    baseStore: "feature_runs",
+    keyColumn: "feature_key",
+    handler: doneHandler as Handler,
+    bodyKey: "feature_key",
+    terminalRow: (key) => ({ feature_key: key, status: "running", derived_status: "abandoned", acknowledged_at: null }),
+    liveRow: (key) => ({ feature_key: key, status: "running", acknowledged_at: null }),
+    deriveView: (r) => ({
+      ...r,
+      ...featureReadModel.evaluate({ ...r, derived_status: effective(r) }, { [USER_TASKS_PROJECTION]: [] }),
+    }),
+  },
+  {
+    id: "acknowledgeDeliveryGraph",
+    view: deliveryGraphReadModel.decl.name,
+    baseStore: "delivery_graph_runs",
+    keyColumn: "run_key",
+    handler: dgHandler as Handler,
+    bodyKey: "run_key",
+    terminalRow: (key) => ({ run_key: key, status: "running", derived_status: "abandoned", acknowledged_at: null }),
+    liveRow: (key) => ({ run_key: key, status: "running", acknowledged_at: null }),
+    deriveView: (r) => ({
+      ...r,
+      ...deliveryGraphReadModel.evaluate({ ...r, derived_status: effective(r) }, undefined, { [PR_COUNTS_LOOKUP]: [] }),
+    }),
+  },
+  {
+    id: "acknowledgeEpic",
+    view: planReadModel.decl.name,
+    baseStore: "plans",
+    keyColumn: "plan_key",
+    handler: epicHandler as Handler,
+    bodyKey: "plan_key",
+    // A `done` epic whose base status is frozen (modelled here) while the derive edge folds it
+    // `abandoned` — resolved-not-landed (`delivery=null`), so dismissable.
+    terminalRow: (key) => ({ plan_key: key, status: "dispatched", derived_status: "abandoned", delivery: null, acknowledged_at: null }),
+    liveRow: (key) => ({ plan_key: key, status: "dispatched", delivery: null, acknowledged_at: null }),
+    deriveView: (r) => {
+      const eff = effective(r);
+      const ackable = epicIsAcknowledgeable(eff, r.delivery ?? null);
+      return {
+        ...r,
+        ack_open: ackable && r.acknowledged_at == null ? 1 : 0,
+        list_bucket: deriveEpicBucket(eff, r.delivery ?? null, r.acknowledged_at ?? null),
+      };
+    },
+  },
+];
+
+/** A fake `AppApi` whose `data.table(name)` serves the four read-model VIEWs off the base stores by
+ * applying the surface's real `deriveView`, and serves the base RECORD stores for the `acknowledged_at`
+ * stamp. Writes to a VIEW are never attempted (the helper stamps the base store). */
+function memApp(surface: Surface, seed: Row[]): { app: AppApi; rows: Row[] } {
+  const stores: Record<string, Row[]> = { [surface.baseStore]: seed };
+  function baseTbl(name: string) {
+    const rows = (stores[name] ??= []);
+    return {
+      async get(id: unknown) {
+        return rows.find((r) => r[surface.keyColumn] === id);
+      },
+      async update(id: unknown, patch: Row) {
+        const r = rows.find((row) => row[surface.keyColumn] === id);
+        if (r) Object.assign(r, patch);
+        return r ? 1 : 0;
+      },
+    };
+  }
+  function viewTbl() {
+    const rows = stores[surface.baseStore];
+    return {
+      async get(id: unknown) {
+        const base = rows.find((r) => r[surface.keyColumn] === id);
+        return base ? surface.deriveView(base) : undefined;
+      },
+    };
+  }
+  const app = {
+    data: { table: (n: string) => (n === surface.view ? viewTbl() : baseTbl(n)) },
+    log: noopLog(),
+  } as unknown as AppApi;
+  return { app, rows: stores[surface.baseStore] };
+}
+
+async function call(app: AppApi, handler: Handler, body: unknown) {
+  return (await handler({ req: {} as unknown, params: {}, query: {}, body } as unknown, app)) as {
+    status: number;
+    body: { ok: boolean; error?: string; message?: string };
+  };
+}
+
+for (const s of SURFACES) {
+  test(`${s.id}: a derive-only-terminated row (base status frozen, derived_status='abandoned') is dismissable → 200, stamps, and folds to History`, async () => {
+    const key = "o/r#1";
+    const { app, rows } = memApp(s, [s.terminalRow(key)]);
+    // Precondition: the read-model VIEW offers Dismiss (ack_open=1) even though base status is frozen
+    // non-terminal — the exact drift that used to 409 the op.
+    assertEquals((await memApp(s, [s.terminalRow(key)]).app.data.table(s.view).get(key)).ack_open, 1);
+
+    const res = await call(app, s.handler, { [s.bodyKey]: key });
+
+    assertEquals(res.status, 200, `${s.id}: dismissable row returns 200`);
+    assertEquals(res.body.ok, true);
+    assertEquals(typeof rows[0].acknowledged_at, "string", `${s.id}: acknowledged_at stamped`);
+    // After the stamp the VIEW re-folds the row to History with the Dismiss affordance closed.
+    const folded = await app.data.table(s.view).get(key);
+    assertEquals(folded.list_bucket, "history", `${s.id}: folds to history`);
+    assertEquals(folded.ack_open, 0, `${s.id}: ack_open closes after dismissal`);
+  });
+
+  test(`${s.id}: a live (non-terminal) row is NOT dismissable → 409 and stays unstamped`, async () => {
+    const key = "o/r#2";
+    const { app, rows } = memApp(s, [s.liveRow(key)]);
+    assertEquals((await app.data.table(s.view).get(key)).ack_open, 0, `${s.id}: precondition ack_open=0`);
+
+    const res = await call(app, s.handler, { [s.bodyKey]: key });
+
+    assertEquals(res.status, 409, `${s.id}: live row rejected`);
+    assertEquals(res.body.ok, false);
+    assertEquals(rows[0].acknowledged_at, null, `${s.id}: no premature stamp`);
+  });
+
+  test(`${s.id}: an already-acknowledged row is an idempotent no-op → 200, no double-stamp`, async () => {
+    const key = "o/r#3";
+    const stamp = "2026-02-02T00:00:00Z";
+    const { app, rows } = memApp(s, [{ ...s.terminalRow(key), acknowledged_at: stamp }]);
+    // An acknowledged terminal row reads ack_open=0 (folded to History) via the VIEW.
+    assertEquals((await app.data.table(s.view).get(key)).ack_open, 0);
+
+    const res = await call(app, s.handler, { [s.bodyKey]: key });
+
+    assertEquals(res.status, 200, `${s.id}: re-acknowledge is idempotent 200`);
+    assertEquals(res.body.ok, true);
+    assertEquals(rows[0].acknowledged_at, stamp, `${s.id}: NOT re-stamped (no double-stamp)`);
+  });
+
+  test(`${s.id}: no such row → 404`, async () => {
+    const { app } = memApp(s, []);
+    assertEquals((await call(app, s.handler, { [s.bodyKey]: "o/r#404" })).status, 404);
+  });
+
+  test(`${s.id}: a missing/blank key → 400`, async () => {
+    const { app } = memApp(s, []);
+    assertEquals((await call(app, s.handler, {})).status, 400);
+    assertEquals((await call(app, s.handler, { [s.bodyKey]: "  " })).status, 400);
+  });
+}
+
+// A direct helper-level guard: the 404 path when the read-model VIEW has no such row, independent of
+// any single op's body parsing.
+test("acknowledgeVia: absent VIEW row → 404", async () => {
+  const app = {
+    data: { table: () => ({ get: async () => undefined }) },
+    log: noopLog(),
+  } as unknown as AppApi;
+  const res = await acknowledgeVia(
+    app,
+    { view: "v", baseTable: "t", keyColumn: "k", label: "thing", notDismissableError: "not terminal" },
+    "missing",
+  );
+  assertEquals(res.status, 404);
+  assertEquals(res.body.ok, false);
+});

package/operations/acknowledgeDeliveryGraph.ts

@@ -1,23 +1,21 @@
-// POST /app/api/actions/acknowledge-delivery-graph → operationId `acknowledgeDeliveryGraph` (issue #641).
-// The nwf UI's "Dismiss" (Done ✓) affordance for a TERMINAL delivery-graph run: an operator dismisses a
-// finished run (done / failed / abandoned) directly from the Overview "Active Delivery Graphs" or
-// delivery-graphs "In-flight delivery graphs" grid so it drops out of the Active list into History. It
-// is the delivery-graph twin of `acknowledgeDone` / `acknowledgeEpic` / `acknowledgePr` — a terminal
-// run is NOT parked at a user task, so this op completes no user task and touches no engine/ledger: it
-// simply stamps `acknowledged_at` on the `delivery_graph_runs` row.
+// POST /app/api/actions/acknowledge-delivery-graph → operationId `acknowledgeDeliveryGraph` (issue
+// #641; generalised by #654). The nwf UI's "Dismiss" (Done ✓) affordance for a TERMINAL delivery-graph
+// run: an operator dismisses a finished run (done / failed / abandoned) directly from the Overview
+// "Active Delivery Graphs" or delivery-graphs "In-flight delivery graphs" grid so it drops out of the
+// Active list into History. A terminal run is NOT parked at a user task, so this op completes no user
+// task and touches no engine/ledger: it simply stamps `acknowledged_at` on the `delivery_graph_runs`
+// row. The delivery-graph twin of `acknowledgeDone` / `acknowledgeEpic` / `acknowledgePr`.
 //
-// `list_bucket`/`ack_open` are DERIVED by the `delivery_graph_read_model` VIEW (096, issue #641) from
-// the terminal-folded `derived_status` + `acknowledged_at` — a terminal, now-acknowledged run reads
-// `list_bucket` = 'history' and `ack_open` = 0 — so this op NEVER writes a derived projection. Keyed on
-// the row's `run_key`. Idempotent-safe: re-acknowledging re-stamps the timestamp and keeps it in
-// History.
-//
-// It rejects (409) a run that is NOT terminal (still awaiting-approval/running), so it can never pre-
-// seed the tick-off on a live run. The terminal check reads the base `status`: the delivery-graph
-// poller (app/deliveryGraphRun.ts) persists the terminal outcome to base `status` (done/failed/
-// abandoned), and the reconciler's `onTerminated` edge covers an out-of-band terminate.
-
-import { DELIVERY_GRAPH_TERMINAL_STATUSES, deliveryGraphRuns } from "../app/deliveryGraphRun.ts";
+// This op is now a one-liner over the shared `acknowledgeVia` helper (issue #654), which gates on the
+// `delivery_graph_read_model` VIEW's derived `ack_open` — the SAME oracle the Dismiss button reads via
+// `showWhenField` — so the affordance and the guard cannot drift. This retires the old base-`status`
+// guard (`DELIVERY_GRAPH_TERMINAL_STATUSES.includes(run.status)`), a latent twin of the PR drift
+// (#652): a run terminated out-of-band froze base `status` while the tracking VIEW folded
+// `derived_status='abandoned'`, so the button offered Dismiss but the op 409'd. The guard now reads the
+// terminal-folded `ack_open`, never the base `status`.
+
+import { acknowledgeVia } from "../app/acknowledge.ts";
+import { deliveryGraphReadModel } from "../app/deliveryGraphReadModel.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
 
 const str = (v: unknown): string => (typeof v === "string" ? v.trim() : "");
@@ -31,28 +29,15 @@ export default defineOperation("acknowledgeDeliveryGraph", async ({ body }, app)
   const runKey = str(body.run_key);
   if (!runKey) return { status: 400, body: { ok: false, error: "run_key is required" } };
 
-  const table = deliveryGraphRuns(app.data);
-  const run = await table.get(runKey);
-  if (!run) {
-    app.log.warn("acknowledge-delivery-graph: no such run", { runKey });
-    return { status: 404, body: { ok: false, error: "no such delivery-graph run" } };
-  }
-
-  // Guard: only a TERMINAL run (a `DELIVERY_GRAPH_TERMINAL_STATUSES` status — the same set the read
-  // model's `list_bucket` folds to History) carries the Dismiss affordance. Acknowledging a live run
-  // would pre-seed `acknowledged_at`, so the moment it later settled the VIEW would drop it straight
-  // into History, skipping the operator tick-off this op exists to require.
-  if (!DELIVERY_GRAPH_TERMINAL_STATUSES.includes(run.status)) {
-    app.log.warn("acknowledge-delivery-graph rejected: run is not terminal", { runKey, status: run.status });
-    return { status: 409, body: { ok: false, error: "delivery-graph run is not terminal" } };
-  }
-
-  // Stamp the dismissal. `list_bucket` (→ 'history') and `ack_open` (→ 0) are derived by the
-  // `delivery_graph_read_model` VIEW from the terminal, now-acknowledged row, so we never hand-set them
-  // here. Idempotent: re-acknowledging re-stamps and stays in History.
-  const now = new Date().toISOString();
-  await table.update(runKey, { acknowledged_at: now, updated_at: now });
-
-  app.log.info("operator dismissed terminal delivery-graph run", { runKey });
-  return { status: 200, body: { ok: true, message: "acknowledged" } };
+  return acknowledgeVia(
+    app,
+    {
+      view: deliveryGraphReadModel.decl.name,
+      baseTable: "delivery_graph_runs",
+      keyColumn: "run_key",
+      label: "delivery-graph run",
+      notDismissableError: "delivery-graph run is not terminal",
+    },
+    runKey,
+  );
 });

package/operations/acknowledgeDone.ts

@@ -1,20 +1,20 @@
-// POST /app/api/actions/acknowledge-done → operationId `acknowledgeDone` (issue #254 §5).
-// The nwf UI's "tick off" affordance for a TERMINAL feature run: an operator dismisses a finished
-// run (Done ✓ / Done ✕) directly from the Feature / Overview pages so it drops out of the primary
-// Active list into History. It is the DONE twin of `acknowledgeBlocked` — but a terminal run is NOT
-// parked at a user task, so this op does NOT complete a user task and touches no engine/ledger: it
-// simply stamps `acknowledged_at` on the row via the plain `feature_runs` record table (the projecting
-// gateway this PR retired). It rejects (409) a run that
-// is not yet truly terminal, so it can never pre-seed the tick-off on a still-live run.
+// POST /app/api/actions/acknowledge-done → operationId `acknowledgeDone` (issue #254 §5; generalised by
+// #654). The nwf UI's "tick off" affordance for a TERMINAL feature run: an operator dismisses a
+// finished run (Done ✓ / Done ✕) directly from the Feature / Overview pages so it drops out of the
+// primary Active list into History. A terminal run is NOT parked at a user task, so this op completes
+// no user task and touches no engine/ledger: it simply stamps `acknowledged_at` on the `feature_runs`
+// row. The DONE twin of `acknowledgePr` / `acknowledgeDeliveryGraph` / `acknowledgeEpic`.
 //
-// The `list_bucket` partition is DERIVED by the `feature_read_model` VIEW (073, issue #439) from
-// `status` + `acknowledged_at` — a terminal row with `acknowledged_at` set reads as 'history' — so
-// this op NEVER writes `list_bucket` (or any projection): stamping `acknowledged_at` is the whole
-// contract. Keyed on the row's `feature_key`. Idempotent-safe: re-acknowledging simply re-stamps the
-// timestamp and keeps the row in History.
-
-import { featureRuns } from "../app/feature.ts";
-import { STAGE_DONE_STATUSES } from "../app/stage.ts";
+// This op is now a one-liner over the shared `acknowledgeVia` helper (issue #654), which gates on the
+// `feature_read_model` VIEW's derived `ack_open` (added by migration 099) — the SAME oracle the Dismiss
+// button reads via `showWhenField` — so the affordance and the guard cannot drift. This retires the
+// old base-`status` guard (`STAGE_DONE_STATUSES.includes(run.status)`), a latent twin of the PR drift
+// (#652): a feature run terminated out-of-band froze base `status` at `running`/`escalated` while the
+// tracking VIEW folded `derived_status='abandoned'`, so the button offered Dismiss but the op 409'd.
+// The guard now reads the terminal-folded `ack_open`, never the base `status`.
+
+import { acknowledgeVia } from "../app/acknowledge.ts";
+import { featureReadModel } from "../app/featureReadModel.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
 
 const str = (v: unknown): string => (typeof v === "string" ? v.trim() : "");
@@ -28,28 +28,15 @@ export default defineOperation("acknowledgeDone", async ({ body }, app) => {
   const featureKey = str(body.feature_key);
   if (!featureKey) return { status: 400, body: { ok: false, error: "feature_key is required" } };
 
-  const runs = featureRuns(app.data);
-  const run = await runs.get(featureKey);
-  if (!run) {
-    app.log.warn("acknowledge-done: no such feature run", { featureKey });
-    return { status: 404, body: { ok: false, error: "no such feature run" } };
-  }
-
-  // Guard: only a TRULY-terminal run (a `Done`-stage status — the same set `deriveListBucket` moves to
-  // History) may be ticked off. Acknowledging a still-live run (e.g. `running`/`opened`/`converging`)
-  // would pre-seed `acknowledged_at`, so the moment it later settles `deriveListBucket` would drop it
-  // straight into History, skipping the operator tick-off this op exists to require.
-  if (!STAGE_DONE_STATUSES.includes(run.status)) {
-    app.log.warn("acknowledge-done rejected: run is not terminal", { featureKey, status: run.status });
-    return { status: 409, body: { ok: false, error: "feature run is not terminal" } };
-  }
-
-  // Stamp the dismissal. `list_bucket` is derived by the `feature_read_model` VIEW (→ 'history' for a
-  // terminal, acknowledged row), so we never hand-set it here. Idempotent: re-acknowledging re-stamps
-  // and stays in History.
-  const now = new Date().toISOString();
-  await runs.update(featureKey, { acknowledged_at: now, updated_at: now });
-
-  app.log.info("operator ticked off feature run", { featureKey });
-  return { status: 200, body: { ok: true, message: "acknowledged" } };
+  return acknowledgeVia(
+    app,
+    {
+      view: featureReadModel.decl.name,
+      baseTable: "feature_runs",
+      keyColumn: "feature_key",
+      label: "feature run",
+      notDismissableError: "feature run is not terminal",
+    },
+    featureKey,
+  );
 });

package/operations/acknowledgeEpic.ts

@@ -1,26 +1,21 @@
-// POST /app/api/actions/acknowledge-epic → operationId `acknowledgeEpic` (issue #298).
-// The nwf UI's "Dismiss" affordance for a RESOLVED epic: an operator dismisses a `done` epic whose
-// fan-out has finished (all slice PRs reached a terminal state — whether all merged/landed or
-// resolved-not-landed) directly from the Epic / Overview pages so it drops out of the Active epic list
-// into History. It is the epic twin of `acknowledgeDone` (the feature-run tick-off) — a resolved epic
-// is NOT parked at a user task, so this op completes no user task and touches no engine/ledger: it
-// simply stamps `acknowledged_at` on the `plans` row.
+// POST /app/api/actions/acknowledge-epic → operationId `acknowledgeEpic` (issue #298; generalised by
+// #654). The nwf UI's "Dismiss" affordance for a RESOLVED epic: an operator dismisses a `done` epic
+// whose fan-out has finished (all slice PRs reached a terminal state — whether all merged/landed or
+// resolved-not-landed), OR a `failed`/`abandoned` epic, directly from the Epic / Overview pages so it
+// drops out of the Active epic list into History. A resolved epic is NOT parked at a user task, so this
+// op completes no user task and touches no engine/ledger: it simply stamps `acknowledged_at` on the
+// `plans` row. The epic twin of `acknowledgeDone` / `acknowledgePr` / `acknowledgeDeliveryGraph`.
 //
-// `list_bucket`/`ack_open` are DERIVED by the `plan_read_model` VIEW (074, issue #439) from
-// `status` + `acknowledged_at` + the derived `plan_delivery` signal — a landed, now-acknowledged epic
-// reads `list_bucket` = 'history' and `ack_open` = 0 — so this op NEVER writes a derived projection.
-// Keyed on the row's `plan_key`. Idempotent-safe: re-acknowledging re-stamps the timestamp and keeps
-// the row in History.
-//
-// It rejects (409) an epic that is NOT yet resolved — i.e. anything the `epicIsAcknowledgeable`
-// guard refuses: a non-`done` status (`planning`/`dispatched`), or `done` but still `converging`. A
-// resolved epic is acknowledgeable whether all slices merged (`delivery=landed`) or it resolved-not-
-// landed (`delivery=null`); only a still-live or still-converging epic is refused, so those stay
-// visible in Active and can never pre-seed the tick-off.
-
-import { epicIsAcknowledgeable } from "../app/delivery.ts";
-import { plans } from "../app/plan.ts";
-import { derivePlanDelivery } from "../app/service.ts";
+// This op is now a one-liner over the shared `acknowledgeVia` helper (issue #654), which gates on the
+// `plan_read_model` VIEW's derived `ack_open` — the SAME oracle the Dismiss button reads via
+// `showWhenField`. The epic's `ack_open` additionally excludes a still-`converging` done epic (the
+// VIEW folds delivery from the slice PRs), so a converging epic is correctly non-dismissable (409) and
+// stays Active. This retires the op's bespoke `epicIsAcknowledgeable(plan.status, delivery)` guard: the
+// affordance and the guard now read one oracle and cannot drift, and a `done` epic frozen non-terminal
+// on base `status` while the read model folds it terminal no longer trips the guard.
+
+import { acknowledgeVia } from "../app/acknowledge.ts";
+import { planReadModel } from "../app/planReadModel.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
 
 const str = (v: unknown): string => (typeof v === "string" ? v.trim() : "");
@@ -34,35 +29,15 @@ export default defineOperation("acknowledgeEpic", async ({ body }, app) => {
   const planKey = str(body.plan_key);
   if (!planKey) return { status: 400, body: { ok: false, error: "plan_key is required" } };
 
-  const table = plans(app.data);
-  const plan = await table.get(planKey);
-  if (!plan) {
-    app.log.warn("acknowledge-epic: no such plan", { planKey });
-    return { status: 404, body: { ok: false, error: "no such epic" } };
-  }
-
-  // Guard: only a RESOLVED epic (`status=done` and no longer `converging`) carries the Dismiss
-  // affordance. Acknowledging a live/converging epic would pre-seed `acknowledged_at`, so the moment
-  // it later resolved `deriveEpicBucket` would drop it straight into History, skipping the operator
-  // tick-off this op exists to require — and a converging epic must stay visible while its slices land.
-  // The `plans.delivery` column was retired (epic #412), so derive the signal at read time from the
-  // slice PRs (the same pure `deriveDelivery` the `plan_delivery` VIEW encodes).
-  const delivery = await derivePlanDelivery(app.data, plan);
-  if (!epicIsAcknowledgeable(plan.status, delivery)) {
-    app.log.warn("acknowledge-epic rejected: epic is not resolved", {
-      planKey,
-      status: plan.status,
-      delivery,
-    });
-    return { status: 409, body: { ok: false, error: "epic is not resolved" } };
-  }
-
-  // Stamp the dismissal. `list_bucket` (→ 'history') and `ack_open` (→ 0) are derived by the
-  // `plan_read_model` VIEW from the resolved, now-acknowledged row, so we never hand-set them here.
-  // Idempotent: re-acknowledging re-stamps and stays in History.
-  const now = new Date().toISOString();
-  await table.update(planKey, { acknowledged_at: now, updated_at: now });
-
-  app.log.info("operator dismissed resolved epic", { planKey });
-  return { status: 200, body: { ok: true, message: "acknowledged" } };
+  return acknowledgeVia(
+    app,
+    {
+      view: planReadModel.decl.name,
+      baseTable: "plans",
+      keyColumn: "plan_key",
+      label: "epic",
+      notDismissableError: "epic is not resolved",
+    },
+    planKey,
+  );
 });

package/operations/acknowledgePr.ts

@@ -1,24 +1,20 @@
-// POST /app/api/actions/acknowledge-pr → operationId `acknowledgePr` (issue #641).
+// POST /app/api/actions/acknowledge-pr → operationId `acknowledgePr` (issue #641; generalised by #654).
 // The nwf UI's "Dismiss" (Done ✓) affordance for a TERMINAL pull request: an operator dismisses a
 // finished PR (merged / converged / abandoned / closed / failed) directly from the Overview "Active PR
 // convergences" or home "Pull requests" grid so it drops out of the Active convergence list into
-// History. It is the PR twin of `acknowledgeDone` (the feature-run tick-off) and `acknowledgeEpic` — a
+// History. It is the PR twin of `acknowledgeDone` / `acknowledgeDeliveryGraph` / `acknowledgeEpic` — a
 // terminal PR is NOT parked at a user task, so this op completes no user task and touches no engine/
 // ledger: it simply stamps `acknowledged_at` on the `pull_requests` row.
 //
-// `list_bucket`/`ack_open` are DERIVED by the `pull_requests_read_model` VIEW (094, issue #641) from
-// the terminal-folded `derived_status` + `acknowledged_at` — a terminal, now-acknowledged PR reads
-// `list_bucket` = 'history' and `ack_open` = 0 — so this op NEVER writes a derived projection. Keyed on
-// the row's `pr_key`. Idempotent-safe: re-acknowledging re-stamps the timestamp and keeps it in
-// History.
-//
-// It rejects (409) a PR that is NOT terminal (still converging/waiting_review/…), so it can never
-// pre-seed the tick-off on a live PR: were `acknowledged_at` set early, the moment the PR later settled
-// the VIEW would drop it straight into History, skipping the operator dismiss this op exists to
-// require. The terminal check reads the base `status` — the reconciler's `onTerminated` edge persists
-// an out-of-band terminate to base `status` = 'abandoned', so a resolved PR is matched here too.
-
-import { PR_TERMINAL_STATUSES } from "../app/pullRequestReadModel.ts";
+// This op is now a one-liner over the shared `acknowledgeVia` helper (issue #654), which gates on the
+// `pull_requests_read_model` VIEW's derived `ack_open` — the SAME oracle the Dismiss button reads via
+// `showWhenField` — so the affordance and the guard cannot drift. That folds in the #652 fix (a PR
+// terminated out-of-band freezes base `status` non-terminal while the read model's `derived_status`
+// reads `abandoned`, so the old base-`status` guard 409'd a Dismiss the UI offered) categorically: the
+// guard now reads the terminal-folded `ack_open`, never the base `status`.
+
+import { acknowledgeVia } from "../app/acknowledge.ts";
+import { pullRequestReadModel } from "../app/pullRequestReadModel.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
 
 const str = (v: unknown): string => (typeof v === "string" ? v.trim() : "");
@@ -32,31 +28,15 @@ export default defineOperation("acknowledgePr", async ({ body }, app) => {
   const prKey = str(body.pr_key);
   if (!prKey) return { status: 400, body: { ok: false, error: "pr_key is required" } };
 
-  const table = app.data.table<{ pr_key: string; status: string; acknowledged_at: string | null; updated_at: string }>(
-    "pull_requests",
-    "pr_key",
+  return acknowledgeVia(
+    app,
+    {
+      view: pullRequestReadModel.decl.name,
+      baseTable: "pull_requests",
+      keyColumn: "pr_key",
+      label: "pull request",
+      notDismissableError: "pull request is not terminal",
+    },
+    prKey,
   );
-  const pr = await table.get(prKey);
-  if (!pr) {
-    app.log.warn("acknowledge-pr: no such pull request", { prKey });
-    return { status: 404, body: { ok: false, error: "no such pull request" } };
-  }
-
-  // Guard: only a TERMINAL PR (a `PR_TERMINAL_STATUSES` status — the same set the read model's
-  // `list_bucket` folds to History) carries the Dismiss affordance. Acknowledging a live PR would
-  // pre-seed `acknowledged_at`, so the moment it later settled the VIEW would drop it straight into
-  // History, skipping the operator tick-off this op exists to require.
-  if (!PR_TERMINAL_STATUSES.includes(pr.status)) {
-    app.log.warn("acknowledge-pr rejected: PR is not terminal", { prKey, status: pr.status });
-    return { status: 409, body: { ok: false, error: "pull request is not terminal" } };
-  }
-
-  // Stamp the dismissal. `list_bucket` (→ 'history') and `ack_open` (→ 0) are derived by the
-  // `pull_requests_read_model` VIEW from the terminal, now-acknowledged row, so we never hand-set them
-  // here. Idempotent: re-acknowledging re-stamps and stays in History.
-  const now = new Date().toISOString();
-  await table.update(prKey, { acknowledged_at: now, updated_at: now });
-
-  app.log.info("operator dismissed terminal pull request", { prKey });
-  return { status: 200, body: { ok: true, message: "acknowledged" } };
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.167.1",
+  "version": "0.167.3",
   "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/feature.page.json

@@ -137,7 +137,7 @@
           {
             "label": "Dismiss",
             "confirm": "Tick off this finished run? It acknowledges the run as done and files it under History.",
-            "showWhenField": "stage_state",
+            "showWhenField": "ack_open",
             "action": {
               "path": "/app/api/actions/acknowledge-done",
               "body": { "feature_key": "{{row.feature_key}}" }

package/pages/overview.page.json

@@ -189,7 +189,7 @@
           {
             "label": "Dismiss",
             "confirm": "Tick off this finished run? It acknowledges the run as done and files it under History.",
-            "showWhenField": "stage_state",
+            "showWhenField": "ack_open",
             "action": {
               "path": "/app/api/actions/acknowledge-done",
               "body": { "feature_key": "{{row.feature_key}}" }