@nanobpm/urban 0.80.0 → 0.82.0

package/src/runtime/core/modules/cancel.test.ts

@@ -9,9 +9,17 @@ import { makeGateway } from "./gateway.ts";
 import type { Table } from "./gateway.ts";
 import { DataLayer, type ProvisionedSource } from "./datasource.ts";
 import type { AppApi } from "../context.ts";
-import type { EngineClient, ProcessInstanceSnapshot } from "../host.ts";
+import type { EngineClient, ProcessInstanceSnapshot, SqliteDb } from "../host.ts";
 import type { InstanceTracking } from "../manifest.ts";
 import { cancelInstanceReconciling } from "./cancel.ts";
+import { INSTANCE_STATE_TABLE } from "./instance-state-store.ts";
+
+// ADR 0065 — the instanceTracking writer→source inversion. Cancel no longer WRITES a terminal patch on
+// the base row; it records the terminal fact into the canonical `_urban_instance_state` projection
+// through the SAME `reconcileTerminatedKey` the poll reconciler uses (so cancel and poll cannot drift),
+// and the terminal status is DERIVED from the projection by the read model. These tests therefore assert
+// on the recorded projection state and `reconciled` (1 = terminal source recorded) — never a base-row
+// mutation.
 
 type State = ProcessInstanceSnapshot["state"];
 
@@ -27,8 +35,9 @@ interface PrRow {
   status: string;
 }
 
-// The pull_requests binding: an ACTIVE row flips to `abandoned` (and drops the process pointer)
-// when its instance terminates — the exact patch the poll reconciler applies.
+// The pull_requests binding: an ACTIVE row derives to `abandoned` when its instance terminates — the
+// value the derived terminal edge resolves to (no longer a stored patch). Cancel feeds the projection;
+// the read model derives the status.
 const PR_BINDING: InstanceTracking = {
   table: "pull_requests",
   keyField: "process_key",
@@ -85,6 +94,7 @@ function cancelEngine(opts: {
 interface Harness {
   api: AppApi;
   table: Table<PrRow>;
+  db: SqliteDb;
   logs: { level: string; msg: string }[];
   close: () => Promise<void>;
 }
@@ -120,6 +130,7 @@ async function withHarness(engine: EngineClient, seedStatus = "converging"): Pro
   return {
     api,
     table,
+    db,
     logs,
     close: async () => {
       db.close();
@@ -128,7 +139,22 @@ async function withHarness(engine: EngineClient, seedStatus = "converging"): Pro
   };
 }
 
-test("terminating a tracked instance reconciles its row immediately", async () => {
+/** The recorded engine lifecycle state for a key in the `_urban_instance_state` projection, or
+ *  undefined when it was never recorded. The projection table is created lazily by cancel's own
+ *  `ensureSchema`; return undefined if it does not exist yet (nothing was ever recorded). */
+function projectedState(db: SqliteDb, key: string): string | undefined {
+  try {
+    const rows = db.all<{ state: string }>(
+      `SELECT state FROM ${INSTANCE_STATE_TABLE} WHERE process_instance_key = ?`,
+      [key],
+    );
+    return rows[0]?.state;
+  } catch {
+    return undefined; // projection table not provisioned ⇒ nothing recorded
+  }
+}
+
+test("terminating a tracked instance records its terminal source immediately (no base write)", async () => {
   // cancelInstance succeeds (no throw) and the engine commits the termination.
   const { engine, cancels } = cancelEngine({
     states: { "100": "ACTIVE" },
@@ -143,19 +169,21 @@ test("terminating a tracked instance reconciles its row immediately", async () =
     assert.equal(r.ok, true);
     assert.equal(r.state, "TERMINATED");
     assert.equal(r.reconciled, 1);
+    // The terminal fact was recorded into the canonical projection …
+    assert.equal(projectedState(h.db, "100"), "TERMINATED");
+    // … and the base row was left UNTOUCHED (source-not-writer); the derived read model surfaces the
+    // terminal status without a stored write.
     const row = await h.table.get("100");
-    assert.equal(row, undefined); // process_key was cleared to null, so no row keyed by "100"
-    const byPr = (await h.table.all()).find((x) => x.pr_key === "pr-1");
-    assert.equal(byPr?.status, "abandoned");
-    assert.equal(byPr?.process_key, null);
+    assert.equal(row?.status, "converging");
+    assert.equal(row?.process_key, "100");
   } finally {
     await h.close();
   }
 });
 
-test("a cancel that throws but reads back TERMINATED is idempotent success + reconciles", async () => {
+test("a cancel that throws but reads back TERMINATED is idempotent success + records the source", async () => {
   // The instance was already terminated; the engine rejects a second cancel, but the verify read
-  // confirms it is gone — treat as success and still reconcile the (stale-active) row.
+  // confirms it is gone — treat as success and still record the terminal source.
   const { engine } = cancelEngine({
     states: { "100": "TERMINATED" },
     onCancel: () => {
@@ -168,14 +196,13 @@ test("a cancel that throws but reads back TERMINATED is idempotent success + rec
     assert.equal(r.ok, true);
     assert.equal(r.state, "TERMINATED");
     assert.equal(r.reconciled, 1);
-    const byPr = (await h.table.all()).find((x) => x.pr_key === "pr-1");
-    assert.equal(byPr?.status, "abandoned");
+    assert.equal(projectedState(h.db, "100"), "TERMINATED");
   } finally {
     await h.close();
   }
 });
 
-test("a failed cancel with a still-ACTIVE instance is an honest failure and touches no row", async () => {
+test("a failed cancel with a still-ACTIVE instance is an honest failure and records nothing", async () => {
   const { engine } = cancelEngine({
     states: { "100": "ACTIVE" },
     onCancel: () => {
@@ -189,15 +216,38 @@ test("a failed cancel with a still-ACTIVE instance is an honest failure and touc
     assert.equal(r.state, "ACTIVE");
     assert.equal(r.reconciled, 0);
     assert.match(r.error ?? "", /permission denied/);
+    assert.equal(projectedState(h.db, "100"), undefined); // instance still running — nothing recorded
     const row = await h.table.get("100");
-    assert.equal(row?.status, "converging"); // untouched — instance still running
+    assert.equal(row?.status, "converging"); // untouched
     assert.ok(h.logs.some((l) => l.level === "error"));
   } finally {
     await h.close();
   }
 });
 
-test("a COMPLETED instance is not reconciled (the app's finalize logic owns that row)", async () => {
+test("an accepted cancel that still reads ACTIVE (engine lag) records the terminal source", async () => {
+  // The engine accepted the 204 but its query store still lags at ACTIVE. The cancel IS committed, so
+  // the terminal source must be recorded now — otherwise the derived view stays on the stored worker
+  // status until a poll catches up (and never, if the instance is later cleaned up). accepted-cancel/lag.
+  const { engine } = cancelEngine({
+    states: { "100": "ACTIVE" },
+    onCancel: () => {}, // accepted (204); state deliberately NOT flipped, to model read-model lag
+  });
+  const h = await withHarness(engine);
+  try {
+    const r = await cancelInstanceReconciling(h.api, [PR_BINDING], "100");
+    assert.equal(r.ok, true);
+    assert.equal(r.state, "ACTIVE");
+    assert.equal(r.reconciled, 1);
+    assert.equal(projectedState(h.db, "100"), "TERMINATED");
+    const row = await h.table.get("100");
+    assert.equal(row?.status, "converging"); // base row untouched (source-not-writer)
+  } finally {
+    await h.close();
+  }
+});
+
+test("a COMPLETED instance is not recorded (the app's finalize logic owns that outcome)", async () => {
   const { engine } = cancelEngine({
     states: { "100": "COMPLETED" },
     onCancel: () => {}, // engine accepts the request; instance had already completed
@@ -208,16 +258,17 @@ test("a COMPLETED instance is not reconciled (the app's finalize logic owns that
     assert.equal(r.ok, true);
     assert.equal(r.state, "COMPLETED");
     assert.equal(r.reconciled, 0);
+    assert.equal(projectedState(h.db, "100"), undefined); // COMPLETED never recorded here
     const row = await h.table.get("100");
-    assert.equal(row?.status, "converging"); // left for the finalize worker, not clobbered
+    assert.equal(row?.status, "converging"); // left for the finalize worker
   } finally {
     await h.close();
   }
 });
 
-test("a gone/unknown instance is idempotent success with no reconcile", async () => {
+test("an accepted cancel that reads back gone (engine cleanup) records the terminal source", async () => {
   const { engine } = cancelEngine({
-    states: {}, // the engine has no record of this key
+    states: {}, // the engine no longer exposes the key (already cleaned up)
     onCancel: () => {},
   });
   const h = await withHarness(engine);
@@ -225,13 +276,21 @@ test("a gone/unknown instance is idempotent success with no reconcile", async ()
     const r = await cancelInstanceReconciling(h.api, [PR_BINDING], "999999");
     assert.equal(r.ok, true);
     assert.equal(r.state, "gone");
-    assert.equal(r.reconciled, 0);
+    // The accepted 204 is a committed termination, so record the terminal source even though the read
+    // model no longer exposes the instance — otherwise the derived view could never leave the stored
+    // worker status (the poll cannot observe a gone instance either). accepted-cancel/read-lag.
+    assert.equal(r.reconciled, 1);
+    assert.equal(projectedState(h.db, "999999"), "TERMINATED");
   } finally {
     await h.close();
   }
 });
 
-test("a TERMINATED instance with no matching binding row reconciles nothing", async () => {
+test("records the terminal source even when no base row matches (the projection is binding-independent)", async () => {
+  // Post-inversion the terminal fact is recorded into the canonical projection for the cancelled key
+  // regardless of which base rows reference it — the projection is the engine-truth store, and the
+  // derived read model only surfaces the fact for rows that point at the key (none here). This agrees
+  // with the poll path (both record TERMINATED for the same key), so they cannot drift.
   const { engine } = cancelEngine({
     states: { "555": "TERMINATED" },
     onCancel: () => {},
@@ -242,37 +301,47 @@ test("a TERMINATED instance with no matching binding row reconciles nothing", as
     const r = await cancelInstanceReconciling(h.api, [PR_BINDING], "555");
     assert.equal(r.ok, true);
     assert.equal(r.state, "TERMINATED");
-    assert.equal(r.reconciled, 0);
+    assert.equal(r.reconciled, 1);
+    assert.equal(projectedState(h.db, "555"), "TERMINATED");
     const row = await h.table.get("100");
-    assert.equal(row?.status, "converging");
+    assert.equal(row?.status, "converging"); // the unrelated tracked row is untouched
   } finally {
     await h.close();
   }
 });
 
-test("a reconcile write failure does not fail the cancel (the engine already terminated it)", async () => {
+test("cancel succeeds and records nothing when there is no default data source (absent-safe)", async () => {
+  // The projection feed is a sidecar on the app's own data source. With no default source there is
+  // nothing to record into — but a successful engine termination must STILL be reported as a success:
+  // a projection feed must never break a cancel. `reconcileTerminatedKey` is absent-safe (returns 0).
   const { engine } = cancelEngine({
     states: { "100": "ACTIVE" },
     onCancel: (key, states) => {
       states[key] = "TERMINATED";
     },
   });
-  const h = await withHarness(engine);
+  const dir = await mkdtemp(join(tmpdir(), "urban-cancel-nosrc-"));
+  const logs: { level: string; msg: string }[] = [];
+  const data = new DataLayer(new Map(), undefined, {}); // no default source configured
+  const api: AppApi = {
+    manifest: { schemaVersion: 1, id: "app", name: "App" },
+    data,
+    engine,
+    env: () => undefined,
+    now: () => 0,
+    wait: () => Promise.resolve(),
+    log: createLogger((level, msg) => {
+      logs.push({ level, msg });
+    }),
+  };
   try {
-    // A binding pointing at a table that does not exist makes the reconcile UPDATE throw.
-    const badBinding: InstanceTracking = {
-      table: "does_not_exist",
-      keyField: "process_key",
-      onTerminated: { set: { status: "abandoned" } },
-    };
-    const r = await cancelInstanceReconciling(h.api, [badBinding], "100");
-    assert.equal(r.ok, true); // engine termination succeeded — the cancel is a success
+    const r = await cancelInstanceReconciling(api, [PR_BINDING], "100");
+    assert.equal(r.ok, true); // the engine termination committed — a success
     assert.equal(r.state, "TERMINATED");
-    assert.equal(r.reconciled, 0);
-    assert.ok(r.error); // the reconcile failure is surfaced, not swallowed
-    assert.ok(h.logs.some((l) => l.level === "error"));
+    assert.equal(r.reconciled, 0); // nothing to record into
+    assert.equal(r.error, undefined); // absent-safe: not surfaced as an error
   } finally {
-    await h.close();
+    await rm(dir, { recursive: true, force: true });
   }
 });
 
@@ -287,7 +356,10 @@ test("an accepted cancel whose verify read fails is trusted (gone) — the 204 c
     const r = await cancelInstanceReconciling(h.api, [PR_BINDING], "100");
     assert.equal(r.ok, true);
     assert.equal(r.state, "gone");
-    assert.equal(r.reconciled, 0);
+    // Accepted 204 → committed termination; record the terminal source even though the verify read
+    // could not confirm it (read-model lag / cleanup must not strand the derived status).
+    assert.equal(r.reconciled, 1);
+    assert.equal(projectedState(h.db, "100"), "TERMINATED");
     assert.ok(h.logs.some((l) => l.level === "warn"));
   } finally {
     await h.close();
@@ -309,6 +381,7 @@ test("a thrown cancel whose verify read also fails is reported as an honest fail
     assert.equal(r.state, "ACTIVE");
     assert.equal(r.reconciled, 0);
     assert.match(r.error ?? "", /transport error/);
+    assert.equal(projectedState(h.db, "100"), undefined);
     const row = await h.table.get("100");
     assert.equal(row?.status, "converging");
   } finally {
@@ -336,8 +409,9 @@ test("a thrown cancel whose verify read comes back empty (gone) is an unverified
     assert.equal(r.state, "gone");
     assert.equal(r.reconciled, 0);
     assert.match(r.error ?? "", /fetch failed/);
+    assert.equal(projectedState(h.db, "100"), undefined); // never record a possibly-live run as terminal
     const row = await h.table.get("100");
-    assert.equal(row?.status, "converging"); // never flip a possibly-live run to a terminal status
+    assert.equal(row?.status, "converging");
     assert.ok(h.logs.some((l) => l.level === "error"));
   } finally {
     await h.close();

package/src/runtime/core/modules/cancel.ts

@@ -6,21 +6,23 @@
 //   1. Report the *real* outcome. A cancel can fail (permissions, the instance already gone,
 //      a transport error). Swallowing that and reporting success leaves an instance running in
 //      the engine while the UI claims it stopped — the worst possible lie for a "cancel" button.
-//   2. Reconcile the tracked row immediately. Apps bind process instances to rows via
-//      `instanceTracking`; the poll reconciler flips a row to its terminal status within a few
-//      seconds of the instance terminating. When *we* are the one terminating it, we can apply
-//      that same declared patch right away instead of waiting for the next poll tick.
+//   2. Reconcile the tracked instance immediately. Apps bind process instances to rows via
+//      `instanceTracking`; since ADR 0065 the reconciler is a SOURCE, not a writer — its poll feeds
+//      engine truth into the canonical `urban_instance_state` projection and the terminal status edge
+//      is DERIVED from it (no stored column to tear; nano-workforce#422). When *we* are the one
+//      terminating the instance, we can record that same terminal source right away instead of waiting
+//      for the next poll tick, and the derived read model reflects it on the next read.
 //
 // This primitive keys success on the engine's response, then reconciles off the read model: a
 // non-throwing `cancelInstance` is a committed termination (trusted even if the read model still
 // lags at ACTIVE), while a throw that does not read back a positively-terminal state (still ACTIVE,
-// or absent from the read model) is an honest failure. It reuses the instanceTracking bindings'
-// `onTerminated.set` patch, so the immediate reconcile can never drift from the poll reconciler's.
+// or absent from the read model) is an honest failure. It records the terminal source through the
+// SAME `reconcileTerminatedKey` the poll reconciler uses, so cancel and poll can never drift.
 
 import type { AppApi } from "../context.ts";
 import type { InstanceTracking } from "../manifest.ts";
 import { errorMessage } from "../guards.ts";
-import { reconcileTerminatedKey } from "./instance-tracking.ts";
+import { reconcileTerminatedKey, tryInstanceProjections } from "./instance-tracking.ts";
 
 export type CancelInstanceState = "ACTIVE" | "COMPLETED" | "TERMINATED" | "gone";
 
@@ -30,7 +32,8 @@ export interface CancelInstanceResult {
   /** The instance state as read back from the engine after the cancel attempt.
    *  `"gone"` means the engine has no record of the key (already cleaned up / never existed). */
   state: CancelInstanceState;
-  /** Rows flipped to their terminal status by the immediate instanceTracking reconcile. */
+  /** 1 when the immediate reconcile recorded the terminal source into the canonical instance-state
+   *  projection (so the derived terminal status edge reflects it at once), else 0. */
   reconciled: number;
   error?: string;
 }
@@ -39,22 +42,26 @@ type CancelApi = Pick<AppApi, "engine" | "data" | "log">;
 
 /**
  * Cancel a process instance honestly: terminate it, verify it is actually gone, and immediately
- * reconcile any instanceTracking row bound to its key.
+ * record the terminal source for its key into the canonical instance-state projection.
  *
  * Outcome rules:
  *  - `cancelInstance` returns without throwing → the engine accepted the termination (a committed
- *    204); trust it even if the read model still lags at ACTIVE.
+ *    204); trust it even if the read model still lags at ACTIVE or has already cleaned the instance
+ *    up ("gone"), and record the terminal source for the key so the derived view flips at once.
  *  - `cancelInstance` throws but the instance reads back positively terminal (TERMINATED/COMPLETED)
- *    → the cancel was effectively idempotent; treat as success. Only a TERMINATED read reconciles a
- *    row here (see below); a COMPLETED read intentionally reconciles nothing.
+ *    → the cancel was effectively idempotent; treat as success. A TERMINATED read records a terminal
+ *    source here; a COMPLETED read intentionally records nothing.
  *  - `cancelInstance` throws and the read is NOT positively terminal — still ACTIVE, or "gone"
  *    (absent from the read model, which after an engine restart can transiently lack a live
- *    instance) → an honest failure: report it and do NOT touch any row (the instance may still be
+ *    instance) → an honest failure: report it and do NOT record anything (the instance may still be
  *    running). A throw is not a committed cancel, and absence from the read model is not proof of
  *    termination, so success is never inferred from it.
  *
- * Reconcile only on `TERMINATED`: a COMPLETED instance's terminal row-write is owned by the app's
- * own finalize logic, and a gone/ACTIVE instance has nothing to flip here.
+ * Record when the cancellation is CONFIRMED — an accepted (non-throwing) cancel of any non-COMPLETED
+ * readback (ACTIVE lag / gone / TERMINATED), or a throw that reads back TERMINATED. A COMPLETED
+ * instance's terminal outcome is owned by the app's own finalize logic, so it records nothing. When
+ * the app declares no `instanceTracking` bindings there is nothing to reconcile, so the feed is
+ * skipped.
  */
 export async function cancelInstanceReconciling(
   api: CancelApi,
@@ -81,7 +88,7 @@ export async function cancelInstanceReconciling(
     //     before it rehydrates, so "gone" is absence-of-evidence, NOT proof of termination.
     // Trust neither as success: claiming a cancel that may not have happened (while the run keeps
     // executing) is the worst possible lie for a cancel button. Report ok:false so the caller
-    // surfaces it and retries; never flip a tracked row to terminal while the instance may live.
+    // surfaces it and retries; never record a terminal source while the instance may live.
     api.log("error", "cancel: engine termination not confirmed, instance may still be active", {
       processInstanceKey: key,
       state,
@@ -91,14 +98,27 @@ export async function cancelInstanceReconciling(
   }
 
   let reconciled = 0;
-  if (state === "TERMINATED") {
+  // Record the terminal source whenever the cancellation is CONFIRMED — not only on a positively
+  // TERMINATED readback. An accepted (non-throwing) `cancelInstance` is a committed 204: the instance
+  // WILL terminate, even if the read model still lags at ACTIVE or the engine has already cleaned the
+  // instance up ("gone"). A throw that nonetheless reads back TERMINATED is idempotently confirmed too.
+  // Excluded: COMPLETED (its terminal outcome is owned by the app's own finalize logic) and the honest-
+  // failure case (a throw with a non-terminal read), which already returned ok:false above. Without
+  // recording on the accepted-but-lagging read, a committed cancel returned ok:true / reconciled:0 and
+  // the derived view stayed on the stored worker status until a poll caught up — and NEVER, if the
+  // engine no longer exposes the instance for the poll to observe (issue: accepted-cancel/read-lag).
+  const cancelConfirmed = !threw || state === "TERMINATED";
+  if (cancelConfirmed && state !== "COMPLETED" && bindings.length > 0) {
+    // Record through the SAME `reconcileTerminatedKey` the poll path uses, over the app's own
+    // projection stores, so cancel and poll can never drift. It is internally absent-safe and never
+    // throws through — a projection-write failure logs a warn and returns 0 rather than turning a
+    // successful engine termination into a 500; the poll reconciler catches the projection up on its
+    // next tick. The extra try/catch is belt-and-suspenders against a store construction fault.
     try {
-      reconciled = await reconcileTerminatedKey(api, bindings, key);
+      const projections = tryInstanceProjections(api);
+      reconciled = reconcileTerminatedKey(api, projections, key);
     } catch (error) {
-      // The engine termination itself succeeded — a reconcile *write* failure (bad binding,
-      // transient DB error) must not turn that into an unhandled 500. Log it and let the
-      // instanceTracking poll reconciler catch the row up on its next tick.
-      api.log("error", "cancel: instance terminated but row reconcile failed", {
+      api.log("error", "cancel: instance terminated but projection reconcile failed", {
         processInstanceKey: key,
         error: errorMessage(error),
       });

package/src/runtime/core/modules/datasource.ts

@@ -14,6 +14,7 @@ import {
 } from "./gateway.ts";
 import { currentJobContext } from "../execContext.ts";
 import { isAbsolutePath } from "../../../toolkit/artifact.ts";
+import { SQL_IDENT, isReservedObjectName } from "../read-model.ts";
 
 export function sqlitePathFromUrl(url: string): string {
   // Accept "file:./x.db", "file:x.db", "sqlite:./x.db" or a bare path.
@@ -95,7 +96,7 @@ export function makeProvenanceRecorder(
   source: string,
 ): InsertObserver {
   return (table, pk) => {
-    if (table.startsWith("_urban_") || table.startsWith("_nano_") || table.startsWith("sqlite_")) {
+    if (isReservedObjectName(table)) {
       return;
     }
     const ctx = currentJobContext();
@@ -153,9 +154,11 @@ export async function openSqliteSource(
   return db;
 }
 
-/** A safe unquoted SQL identifier. Table/column names are interpolated directly into SQL,
- * so reject anything that isn't a plain identifier to prevent invalid SQL / injection. */
-const SQL_IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** A safe unquoted SQL identifier check. Table/column names are interpolated directly into SQL, so
+ * reject anything that isn't a plain identifier to prevent invalid SQL / injection. The regex itself
+ * is the runtime-wide single source of truth in `read-model.ts` (No Drift Surfaces — a divergent copy
+ * could let table validation and read-model/manifest validation disagree); we reuse it here rather than
+ * re-declaring it, keeping this module's own error message. */
 function assertSqlIdent(kind: string, name: string): string {
   if (!SQL_IDENT.test(name)) {
     throw new Error(`invalid ${kind} "${name}": must match ${SQL_IDENT.source}`);

package/src/runtime/core/modules/gateway.ts

@@ -13,6 +13,7 @@
 //   const o = await orders.get(id);
 
 import type { SqliteDb } from "../host.ts";
+import { RESERVED_OBJECT_PREFIXES } from "../read-model.ts";
 
 export type Row = Record<string, unknown>;
 
@@ -264,11 +265,13 @@ class SqliteGateway implements DataSource {
     // Exclude SQLite internals (`sqlite_%`) and Nano's own bookkeeping tables (`_urban_%` /
     // `_nano_%`, e.g. the migrations ledger): neither is a user/domain object, so they must
     // never surface in the domain model, DB Manager, or forms. The same exclusions apply to
-    // views.
+    // views. The prefix set is derived from RESERVED_OBJECT_PREFIXES (No Drift Surfaces) so this
+    // read-side filter cannot diverge from the write-side skip / manifest-validation rejection.
+    const reservedClause = RESERVED_OBJECT_PREFIXES.map(
+      (p) => `AND name NOT LIKE '${p.replace(/_/g, "\\_")}%' ESCAPE '\\'`,
+    ).join(" ");
     const tables = this.#db.all<{ name: string; type: string }>(
-      "SELECT name, type FROM sqlite_master WHERE type IN ('table','view') " +
-        "AND name NOT LIKE 'sqlite_%' AND name NOT LIKE '\\_urban\\_%' ESCAPE '\\' " +
-        "AND name NOT LIKE '\\_nano\\_%' ESCAPE '\\' ORDER BY name",
+      `SELECT name, type FROM sqlite_master WHERE type IN ('table','view') ${reservedClause} ORDER BY name`,
     );
     const out: TableMeta[] = [];
     for (const t of tables) {

package/src/runtime/core/modules/instance-status-read-model.ts

@@ -0,0 +1,156 @@
+// instance-status-read-model — the DERIVED half of the `instanceTracking` writer→source inversion
+// (ADR 0065, surface #1; #439-L1 / #318). The reconciler used to WRITE the derivable status edges
+// (`onTerminated.set` / `onWaitingHuman.set` applied as `table.update` patches); that stored-derived
+// value tore from its inputs (nano-workforce#422: an answered escalation still showed a stale ⚠).
+//
+// After the inversion, the reconciler is a SOURCE — it feeds engine truth into the canonical
+// projections (`urban_instance_state`, `urban_open_user_tasks`, ADR 0065 #1) — and the two derivable
+// status edges are DERIVED here, once, in the closed `defineReadModel` expression DSL:
+//
+//   terminal edge:      EXISTS(urban_instance_state    WHERE process_instance_key = base.<keyField>
+//                                                        AND state = 'TERMINATED')  -> onTerminated value
+//   wait-on-human edge: EXISTS(urban_open_user_tasks   WHERE process_instance_key = base.<keyField>)
+//                                                                                   -> onWaitingHuman value
+//
+// authored ONCE and compiled to BOTH the SQLite VIEW and the in-process TS function (surface #2 is
+// closed by the two-backend compiler). Because a derived edge is recomputed on every read over the
+// LIVE projections, a re-escalation after an answer re-flips by construction and #422 cannot recur:
+// once `OpenUserTasksStore.syncInstance` retires the answered task, the `EXISTS` goes false on the
+// next read — no stored column to leave stale.
+
+import type { InstanceTracking } from "../manifest.ts";
+import {
+  and,
+  caseWhen,
+  col,
+  defineReadModel,
+  eq,
+  type Expr,
+  exists,
+  lit,
+  not,
+  pcol,
+  type ReadModel,
+  type WhenClause,
+  when,
+} from "../read-model.ts";
+import { INSTANCE_STATE_PROJECTION } from "./instance-state-store.ts";
+import { OPEN_USER_TASKS_PROJECTION } from "./open-user-tasks-store.ts";
+
+/** The engine-truth terminal lifecycle state the terminal edge keys on (mirrors
+ *  `ProcessInstanceState`'s `TERMINATED`). Reconciled only on `TERMINATED` — never `COMPLETED`, whose
+ *  terminal row-write the app's own finalize worker owns — exactly as the pre-inversion reconciler was. */
+export const TERMINATED_STATE = "TERMINATED";
+
+/** The default derived-status column name a binding's read-model VIEW exposes. Distinct from the base
+ *  `statusField` on purpose: the managed VIEW re-exports `base.*` (so pages keep every base column),
+ *  and SQLite lets the base column win over a same-named derived alias — so the EFFECTIVE (derived)
+ *  status is surfaced under its own column, which the operator page reads instead of the stored one.
+ *  A binding may override it via `readModel.statusColumn`. */
+export const DEFAULT_DERIVED_STATUS_COLUMN = "derived_status";
+
+/** The default managed-VIEW name for a binding: `<table>__tracking`. Distinct from the base table
+ *  (SQLite forbids a VIEW and a table sharing a name). An app with more than one binding on the same
+ *  base table must give each a distinct `readModel.view`. */
+export function defaultInstanceTrackingViewName(table: string): string {
+  return `${table}__tracking`;
+}
+
+/** `EXISTS(urban_instance_state WHERE process_instance_key = base.<keyField> AND state = 'TERMINATED')`
+ *  — the terminal edge, derived over the canonical instance-state projection. Authored once; compiles
+ *  to both the SQLite VIEW `EXISTS` and the TS `projections["urban_instance_state"].some(...)`. */
+export function terminatedEdgeExpr(keyField: string): Expr {
+  return exists(
+    INSTANCE_STATE_PROJECTION,
+    and(eq(pcol("process_instance_key"), col(keyField)), eq(pcol("state"), lit(TERMINATED_STATE))),
+  );
+}
+
+/** `EXISTS(urban_open_user_tasks WHERE process_instance_key = base.<keyField>)` — the wait-on-human
+ *  edge, derived over the canonical open-user-tasks projection (an instance is parked on a human iff it
+ *  has an open user task). Authored once; compiles to both backends. */
+export function waitingHumanEdgeExpr(keyField: string): Expr {
+  return exists(OPEN_USER_TASKS_PROJECTION, eq(pcol("process_instance_key"), col(keyField)));
+}
+
+/**
+ * The effective-status derivation for one binding, in the closed expression DSL:
+ *
+ *   CASE
+ *     WHEN <terminated>                    THEN <onTerminated.set[statusField]>   -- terminal wins
+ *     WHEN <waiting-on-human> AND NOT <terminated> THEN <onWaitingHuman.set[statusField]>
+ *     ELSE base.<statusField>              -- the worker-owned / business-outcome transient status
+ *   END
+ *
+ * Precedence (terminated over waiting-human) is preserved: the terminal `WHEN` is emitted first, and
+ * the waiting `WHEN` is additionally guarded by `NOT <terminated>` so it is correct even when the two
+ * patches touch disjoint columns. When a binding's patch does not set the `statusField` (it reconciles
+ * only secondary columns), that edge contributes no `WHEN` and the derived status passes the stored
+ * value through — a derived read model never re-introduces a stored derivable write.
+ */
+export function deriveInstanceStatusExpr(binding: InstanceTracking, statusField: string): Expr {
+  const terminated = terminatedEdgeExpr(binding.keyField);
+  const whens: WhenClause[] = [];
+
+  const terminalStatus = patchValueForColumn(binding.onTerminated?.set, statusField);
+  if (terminalStatus !== undefined) {
+    whens.push(when(terminated, lit(terminalStatus)));
+  }
+
+  const waitingStatus = patchValueForColumn(binding.onWaitingHuman?.set, statusField);
+  if (waitingStatus !== undefined) {
+    whens.push(when(and(waitingHumanEdgeExpr(binding.keyField), not(terminated)), lit(waitingStatus)));
+  }
+
+  // No edge touches the status column ⇒ the derived status is exactly the stored transient (no CASE).
+  return whens.length > 0 ? caseWhen(whens, col(statusField)) : col(statusField);
+}
+
+/** Read the patch value a `*.set` map assigns to the status COLUMN, matching the key case-insensitively.
+ *  SQL column identifiers fold case (SQLite), but a JS `set[statusField]` lookup is case-sensitive, so a
+ *  binding with `statusField: "Status"` and `onTerminated.set: { status: "abandoned" }` would emit no
+ *  terminal `WHEN` and silently fall through to the base column. Fold the comparison so the derivation
+ *  matches the column the equivalent SQL UPDATE would have addressed. */
+function patchValueForColumn(set: unknown, statusField: string): string | number | boolean | null | undefined {
+  if (set === null || typeof set !== "object") return undefined;
+  const folded = statusField.toLowerCase();
+  for (const [k, v] of Object.entries(set)) {
+    if (k.toLowerCase() !== folded) continue;
+    if (v === undefined) return undefined;
+    if (v === null || typeof v === "string" || typeof v === "number" || typeof v === "boolean") return v;
+    return undefined;
+  }
+  return undefined;
+}
+
+/** The managed-VIEW name + derived-status column a binding's read model uses (config overrides applied). */
+export function instanceTrackingReadModelTarget(binding: InstanceTracking): {
+  readonly view: string;
+  readonly statusColumn: string;
+} {
+  return {
+    view: binding.readModel?.view ?? defaultInstanceTrackingViewName(binding.table),
+    statusColumn: binding.readModel?.statusColumn ?? DEFAULT_DERIVED_STATUS_COLUMN,
+  };
+}
+
+/**
+ * Build the derived read model for one `instanceTracking` binding: a managed VIEW over the binding's
+ * base table that re-exports `base.*` plus one derived `statusColumn` computed by
+ * {@link deriveInstanceStatusExpr} over the canonical projections. Returns `undefined` when the binding
+ * declares no `statusField` (there is no single status column to derive — the projections still get fed,
+ * but nothing well-defined can be projected as "the effective status").
+ *
+ * The two backends (SQLite VIEW select-list + in-process TS function) fall out of the one AST, so they
+ * cannot drift; `assertReadModelParity` verifies it in tests.
+ */
+export function defineInstanceTrackingReadModel(binding: InstanceTracking): ReadModel | undefined {
+  const statusField = binding.statusField;
+  if (typeof statusField !== "string" || statusField.length === 0) return undefined;
+  const { view, statusColumn } = instanceTrackingReadModelTarget(binding);
+  return defineReadModel({
+    name: view,
+    baseTable: binding.table,
+    derive: { [statusColumn]: deriveInstanceStatusExpr(binding, statusField) },
+  });
+}