@nanobpm/urban 0.80.0 → 0.81.0

package/dist/runtime/core/manifest.d.ts

@@ -18,27 +18,60 @@ export type InstanceTracking = SchemaInstanceTracking & {
      *  is polled (fail-open). Requires `statusField`; mutually exclusive with `activeStatuses`. */
     readonly terminalStatuses?: readonly string[];
     /**
-     * The reconciliation applied to a row whose instance is **parked waiting on a human** — the
-     * wait-state twin of {@link SchemaInstanceTracking.onTerminated} (issue #355). An instance is
-     * waiting on a human *iff* it has an open user task, so the runtime derives this edge from
-     * engine truth (`openUserTasks`) rather than from a written column: on each poll, an active,
-     * non-terminated row whose instance has any open user task has this patch applied (typically
-     * `status = "awaiting_operator"`). Terminated wins over waiting-human (the {@link
-     * SchemaInstanceTracking.onTerminated} edge is applied first and excludes the key from this
-     * pass); a row with neither a terminated instance nor an open user task is left untouched, so
-     * the worker-owned transient status (running / converging / merging) survives.
+     * The reconciliation for a row whose instance is **parked waiting on a human** — the wait-state
+     * twin of {@link SchemaInstanceTracking.onTerminated} (issue #355). An instance is waiting on a
+     * human *iff* it has an open user task, so the runtime derives this edge from engine truth
+     * (`openUserTasks`); terminated wins over waiting-human, and a row with neither is left carrying
+     * its worker-owned transient status (running / converging / merging).
+     *
+     * Since ADR 0065 (the writer→source inversion, #439-L1 / #318) this is a DERIVED, not a stored,
+     * edge: the reconciler no longer writes `set` into the base row with `table.update`. Instead it
+     * feeds the canonical `urban_open_user_tasks` projection, and the read model derives the effective
+     * status from it via `defineReadModel` — so an answered escalation re-flips by construction and the
+     * stored-derived tearing of nano-workforce#422 cannot recur. `set[statusField]` now supplies the
+     * VALUE the derived wait-on-human edge resolves to (rather than a patch); any secondary columns in
+     * `set` are no longer written (a VIEW cannot reset a stored column). See {@link readModel}.
      *
      * Optional and, like `terminalStatuses`, bridged locally until the canonical schema
      * (`@nanobpm/nano-app-schema`) folds it in; drop this augmentation and re-export once the dep
      * bump lands (No Drift Surfaces).
      */
     readonly onWaitingHuman?: {
-        /** Column → literal value patch written to a row whose instance has an open user task
-         *  (e.g. set the status to a "waiting on human" value). */
+        /** Column → literal patch. Its `statusField` entry supplies the VALUE the derived wait-on-human
+         *  edge resolves to (an instance with an open user task ⇒ this status); no longer a stored write.
+         *  Since the inversion the reconciler makes NO base-row write at all, so only the `statusField` entry
+         *  is consumed — any other key is intentionally IGNORED (an app-owned column is the app worker's job,
+         *  not the reconciler's; ADR 0065). */
         readonly set: {
             readonly [k: string]: string | number | boolean | null;
         };
     };
+    /**
+     * Optional overrides for the DERIVED read-model VIEW the runtime provisions per binding (ADR 0065,
+     * the writer→source inversion). The reconciler feeds engine truth into the canonical projections
+     * (`urban_instance_state`, `urban_open_user_tasks`) and the runtime provisions a managed SQLite VIEW
+     * over the binding's base table that re-exports `base.*` plus a derived status column — the terminal
+     * (`onTerminated`) and wait-on-human (`onWaitingHuman`) edges computed by `defineReadModel` over the
+     * projections, precedence-correct (terminated wins). The operator page reads this derived column; the
+     * base `statusField` column now holds only the worker-owned / business-outcome status. Both fields
+     * default sensibly (`view` → `<table>__tracking`, `statusColumn` → `derived_status`); override them to
+     * avoid a collision (e.g. more than one binding on one base table, or a base column already named
+     * `derived_status`). A binding with no `statusField` provisions no VIEW (nothing to derive), but the
+     * reconciler still feeds the projections.
+     *
+     * The VIEW is a first-class readable pages surface, not a separate wiring step: `SqliteGateway.schema()`
+     * introspects views (`type IN ('table','view')`) and `/app/data/<source>/<view>` serves `SELECT *`
+     * verbatim, so an operator page reads the derived status simply by pointing its page `data.table` at
+     * this managed VIEW (which re-exports `base.*`, so it is a drop-in for the base table) and its column at
+     * `statusColumn`. This is opt-in by design: the base table stays readable carrying the worker-owned
+     * status; the runtime does NOT silently rebind every page off the base table.
+     */
+    readonly readModel?: {
+        /** Managed VIEW name (must be a SQL identifier and differ from the base table). */
+        readonly view?: string;
+        /** Derived effective-status column name in that VIEW (must be a SQL identifier). */
+        readonly statusColumn?: string;
+    };
 };
 /**
  * A status selector (`activeStatuses`/`terminalStatuses`) counts as *configured* only when it is

package/dist/runtime/core/modules/cancel.d.ts

@@ -7,29 +7,34 @@ 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;
 }
 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 declare function cancelInstanceReconciling(api: CancelApi, bindings: InstanceTracking[], processInstanceKey: string): Promise<CancelInstanceResult>;
 export {};

package/dist/runtime/core/modules/cancel.js

@@ -6,36 +6,42 @@
 //   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 { errorMessage } from "../guards.js";
-import { reconcileTerminatedKey } from "./instance-tracking.js";
+import { reconcileTerminatedKey, tryInstanceProjections } from "./instance-tracking.js";
 /**
  * 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, bindings, processInstanceKey) {
     const key = String(processInstanceKey);
@@ -56,7 +62,7 @@ export async function cancelInstanceReconciling(api, bindings, processInstanceKe
         //     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,
@@ -65,15 +71,28 @@ export async function cancelInstanceReconciling(api, bindings, processInstanceKe
         return { ok: false, processInstanceKey: key, state, reconciled: 0, error: errorMessage(threw) };
     }
     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/dist/runtime/core/modules/datasource.js

@@ -5,6 +5,7 @@
 import { makeGateway, } from "./gateway.js";
 import { currentJobContext } from "../execContext.js";
 import { isAbsolutePath } from "../../../toolkit/artifact.js";
+import { SQL_IDENT, isReservedObjectName } from "../read-model.js";
 export function sqlitePathFromUrl(url) {
     // Accept "file:./x.db", "file:x.db", "sqlite:./x.db" or a bare path.
     return url.replace(/^(file|sqlite):(\/\/)?/, "");
@@ -74,7 +75,7 @@ export function ensureProvenanceTable(db) {
  *  a throw here can never break the app insert. */
 export function makeProvenanceRecorder(host, db, source) {
     return (table, pk) => {
-        if (table.startsWith("_urban_") || table.startsWith("_nano_") || table.startsWith("sqlite_")) {
+        if (isReservedObjectName(table)) {
             return;
         }
         const ctx = currentJobContext();
@@ -121,9 +122,11 @@ export async function openSqliteSource(host, root, url) {
     db.exec("PRAGMA journal_mode=WAL");
     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, name) {
     if (!SQL_IDENT.test(name)) {
         throw new Error(`invalid ${kind} "${name}": must match ${SQL_IDENT.source}`);

package/dist/runtime/core/modules/gateway.js

@@ -11,6 +11,7 @@
 //   const orders = db.table<Order>("orders");   // a typed gateway over one table
 //   await orders.insert({ id, status: "new" });
 //   const o = await orders.get(id);
+import { RESERVED_OBJECT_PREFIXES } from "../read-model.js";
 /** Double-quote a SQL identifier (table/column), escaping embedded quotes. */
 export function quoteIdent(name) {
     return `"${name.replaceAll('"', '""')}"`;
@@ -158,10 +159,10 @@ class SqliteGateway {
         // 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.
-        const tables = this.#db.all("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");
+        // 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(`SELECT name, type FROM sqlite_master WHERE type IN ('table','view') ${reservedClause} ORDER BY name`);
         const out = [];
         for (const t of tables) {
             // `PRAGMA table_info(<view>)` returns the view's columns (pk/notnull report 0, which is

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

@@ -0,0 +1,56 @@
+import type { InstanceTracking } from "../manifest.ts";
+import { type Expr, type ReadModel } from "../read-model.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 declare 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 declare 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 declare function defaultInstanceTrackingViewName(table: string): string;
+/** `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 declare function terminatedEdgeExpr(keyField: string): Expr;
+/** `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 declare function waitingHumanEdgeExpr(keyField: string): Expr;
+/**
+ * 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 declare function deriveInstanceStatusExpr(binding: InstanceTracking, statusField: string): Expr;
+/** The managed-VIEW name + derived-status column a binding's read model uses (config overrides applied). */
+export declare function instanceTrackingReadModelTarget(binding: InstanceTracking): {
+    readonly view: string;
+    readonly statusColumn: string;
+};
+/**
+ * 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 declare function defineInstanceTrackingReadModel(binding: InstanceTracking): ReadModel | undefined;

package/dist/runtime/core/modules/instance-status-read-model.js

@@ -0,0 +1,127 @@
+// 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 { and, caseWhen, col, defineReadModel, eq, exists, lit, not, pcol, when, } from "../read-model.js";
+import { INSTANCE_STATE_PROJECTION } from "./instance-state-store.js";
+import { OPEN_USER_TASKS_PROJECTION } from "./open-user-tasks-store.js";
+/** 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) {
+    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) {
+    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) {
+    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, statusField) {
+    const terminated = terminatedEdgeExpr(binding.keyField);
+    const whens = [];
+    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, statusField) {
+    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) {
+    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) {
+    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) },
+    });
+}

package/dist/runtime/core/modules/instance-tracking.d.ts

@@ -1,5 +1,7 @@
 import type { AppApi, Mounted, RuntimeContext } from "../context.ts";
-import { type InstanceTracking } from "../manifest.ts";
+import type { UserTaskSummary } from "../host.ts";
+import { InstanceStateStore } from "./instance-state-store.ts";
+import { OpenUserTasksStore } from "./open-user-tasks-store.ts";
 import { type SchedulerDeps } from "./scheduler.ts";
 /** Default poll interval when a binding does not set `pollMs`. */
 export declare const DEFAULT_INSTANCE_TRACKING_POLL_MS = 15000;
@@ -13,24 +15,50 @@ export interface InstanceTrackingHandle extends Mounted {
     /** `table.keyField` labels of the armed bindings, for `inspect()`. */
     readonly bindings: string[];
 }
-/** Apply a binding's `onTerminated.set` patch to the single row keyed by `processInstanceKey`.
- *  Only the binding whose table owns that key has a matching row, so callers can fan this over
- *  every binding and let the no-match ones be no-ops. Returns rows changed. The single place that
- *  writes the terminal patch (and logs the reconcile): both the poll reconciler below (`reconcileOnce`,
- *  once per TERMINATED key it discovers) and the cancel primitive (immediately when it terminates an
- *  instance) route through here, so the two can never drift on the patch or the log. */
-export declare function reconcileTerminatedKey(api: Pick<AppApi, "data" | "log">, bindings: InstanceTracking[], processInstanceKey: string): Promise<number>;
-/** Apply a binding's `onWaitingHuman.set` patch to the single row keyed by `processInstanceKey`
- *  — the wait-on-human twin of {@link reconcileTerminatedKey} (issue #355). The caller establishes
- *  the precondition (the instance is non-terminated and has an open user task); this is the single
- *  place that writes `onWaitingHuman.set` and logs the reconcile. Bindings without an
- *  `onWaitingHuman` edge are no-ops, so callers can fan this over every binding. It skips the write
- *  when the row already carries the patch (quiet-idempotent — a long-parked instance is re-polled
- *  every tick and must not re-log). Returns rows changed. */
-export declare function reconcileWaitingHumanKey(api: Pick<AppApi, "data" | "log">, bindings: InstanceTracking[], processInstanceKey: string): Promise<number>;
 /**
- * Mount the `instanceTracking` reconciler: arm one poll loop per binding. Each loop selects
- * the active rows, asks the engine which of their instances are terminated, and applies the
- * declared patch. `stop()` cancels every armed timer.
+ * The canonical engine-truth projections the reconciler feeds as a SOURCE (ADR 0065, the writer→source
+ * inversion): the instance-state projection (feeds the terminal edge) and the open-user-tasks projection
+ * (feeds the wait-on-human edge). Both are sidecars on the app's own default data source; the derived
+ * status read model `EXISTS`-derives its edges from them.
+ */
+export interface InstanceProjections {
+    readonly instanceState: InstanceStateStore;
+    readonly openUserTasks: OpenUserTasksStore;
+}
+/**
+ * Construct the canonical projection stores over the app's default data source and ensure their schema
+ * (idempotent), exactly the per-source boot path `tryLineageStore` / `tryProvisionCanonicalProjections`
+ * use. Absent-safe: with no default source there is nothing to feed, so return `undefined` at `debug`
+ * (the expected sidecar-absent case). A genuine provisioning fault (missing named source, schema error)
+ * degrades to `undefined` at `warn` rather than breaking the mount — a projection feed must never break
+ * a job.
+ */
+export declare function tryInstanceProjections(api: Pick<AppApi, "data" | "log">): InstanceProjections | undefined;
+/** Record engine-truth that an instance is TERMINATED into the canonical `urban_instance_state`
+ *  projection and retire its open-user-task rows — the writer→source replacement for the old
+ *  `onTerminated.set` `table.update` patch (ADR 0065; #439-L1 / #318). The derived terminal status edge
+ *  (a VIEW / function over the projection) reflects this on the next read, so there is no stored-derived
+ *  column to tear from its inputs (nano-workforce#422). This is the SINGLE place that records the terminal
+ *  source: both the poll reconciler (`reconcileOnce`, once per TERMINATED key it discovers) and the cancel
+ *  primitive (`cancel.ts`, immediately when it terminates an instance) route through it, so the two can
+ *  never drift. Absent-safe (no projections / blank key ⇒ 0) and never throws through — a projection write
+ *  must never break a job or a cancel. Returns 1 when it recorded the terminal source, else 0. */
+export declare function reconcileTerminatedKey(api: Pick<AppApi, "log">, projections: InstanceProjections | undefined, processInstanceKey: string): number;
+/** Feed an instance's CURRENT open-user-task set into the canonical `urban_open_user_tasks` projection
+ *  — the wait-on-human twin of {@link reconcileTerminatedKey} (issue #355). `syncInstance` is
+ *  authoritative-per-instance: it inserts the still-open tasks and RETIRES any previously-projected task
+ *  that is no longer open, so an answered/closed escalation makes the derived wait-on-human edge go false
+ *  on the next read by construction (nano-workforce#422 — no stored column to leave stale). Passing an
+ *  EMPTY `openTasks` clears the instance, which is exactly the answered-escalation transition; callers
+ *  MUST therefore feed every probed non-terminated key, including those with no open task, or a retired
+ *  task would linger and the edge would tear. Absent-safe (no projections / blank key ⇒ 0) and never
+ *  throws through. Returns 1 when it fed the projection, else 0. */
+export declare function reconcileWaitingHumanKey(api: Pick<AppApi, "log">, projections: InstanceProjections | undefined, processInstanceKey: string, openTasks: readonly UserTaskSummary[]): number;
+/**
+ * Mount the `instanceTracking` reconciler: provision each binding's derived read-model VIEW, construct
+ * the canonical projection stores once, and arm one poll loop per binding. Each loop selects the active
+ * rows, asks the engine which of their instances are terminated / parked on a human, and FEEDS that
+ * engine truth into the canonical projections (never a base-row write — the status edges are DERIVED;
+ * ADR 0065). `stop()` cancels every armed timer.
  */
 export declare function mountInstanceTracking(ctx: RuntimeContext, api: AppApi, sched?: SchedulerDeps): InstanceTrackingHandle;