@nanobpm/urban 0.80.0 → 0.82.0

package/dist/runtime/core/modules/instance-tracking.js

@@ -2,35 +2,42 @@
 //
 // The problem it closes: an Urban app derives a row's status from the workers that run
 // along a process's *happy path*. When an instance instead reaches an engine-truth state with
-// no worker to record it, the read-model row lies. Two such edges are reconciled declaratively:
+// no worker to record it, the read-model row lies. Two such edges are derived from engine truth:
 //
 //  - The **terminal** edge (`onTerminated`): each binding's poll asks the engine which of its
-//    active instances are `TERMINATED` and applies `onTerminated.set` (→ e.g. `abandoned`). A
-//    terminated instance runs no completion worker, so nothing else would ever close the row.
+//    active instances are `TERMINATED`. A terminated instance runs no completion worker, so nothing
+//    else would ever close the row.
 //
 //  - The **wait-on-human** edge (`onWaitingHuman`, issue #355): the symmetric primitive for
 //    "this instance is parked waiting on a human." That state is authoritatively knowable — an
 //    instance is waiting on a human *iff* it has an open user task (`openUserTasks` =
-//    `searchUserTasks({state:"CREATED"})`) — for every process, forever, with no per-element
-//    registry. On each poll, an active, non-terminated row whose instance has any open user task
-//    has `onWaitingHuman.set` applied (typically `status = "awaiting_operator"`). This retires the
-//    per-subject imperative pattern (workers writing the status on escalate/answer plus a bespoke
-//    self-heal poller): the parked status becomes a derived view over the one user-task
-//    projection, so there is no second surface to drift (No Drift Surfaces).
+//    `searchUserTasks({state:"CREATED"})`) — for every process, forever, with no per-element registry.
 //
-// Precedence per active row, all derived from engine truth (never a worker write):
-//   terminated              -> onTerminated.set   (e.g. abandoned)      // terminal edge
-//   else has open user task  -> onWaitingHuman.set  (e.g. awaiting_operator)  // wait-on-human edge
-//   else                     -> leave the worker-owned transient status (running / converging / …)
+// SOURCE, NOT WRITER (ADR 0065, surface #1; #439-L1 / #318). This reconciler used to *write* those
+// derived edges — `reconcileTerminatedKey` / `reconcileWaitingHumanKey` applied `onTerminated.set` /
+// `onWaitingHuman.set` as `table.update` patches on the app's base row. A stored derived value tears
+// from its inputs (nano-workforce#422: an answered escalation still showed a stale ⚠). The inversion
+// makes the reconciler a SOURCE: each poll FEEDS engine truth into the canonical projections
+// (`urban_instance_state` gets the `TERMINATED` fact; `urban_open_user_tasks` gets the instance's
+// current open-task set), and the two edges are DERIVED — recomputed on every read — by a
+// `defineReadModel` VIEW over those projections (see `instance-status-read-model.ts`). Because the
+// wait-on-human edge is an `EXISTS` over the live open-task projection, retiring an answered task via
+// `OpenUserTasksStore.syncInstance` makes the edge go false on the next read by construction, so the
+// #422 staleness cannot recur.
 //
-// It deliberately reconciles the terminal edge only on `TERMINATED` — the state that by
-// definition runs no completion worker — and never on `COMPLETED`, whose terminal row-write the
-// app's own finalize worker owns (reconciling it here would race that worker and could clobber a
-// legitimately-completed row). The wait-on-human edge reads *open* user tasks via `openUserTasks`
-// (never a bare `searchUserTasks`, which lags a completion and would latch `awaiting_operator`
-// onto a just-answered task). The poll is driven through the shared `SchedulerDeps` seam so tests
-// are deterministic.
+// Precedence (terminated wins over waiting-human) is preserved in the derivation, not in a write
+// order. It deliberately records the terminal source only on `TERMINATED` — the state that by
+// definition runs no completion worker — and never on `COMPLETED`, whose terminal row-write the app's
+// own finalize worker owns. The wait-on-human edge reads *open* user tasks via `openUserTasks` (never
+// a bare `searchUserTasks`, which lags a completion). Real business-outcome writes owned by app workers
+// (e.g. a finalize worker's terminal outcome) are untouched — only the derivable edges are inverted.
+// The poll is driven through the shared `SchedulerDeps` seam so tests are deterministic.
 import { isConfiguredStatusSelector } from "../manifest.js";
+import { assertSqlIdentifier, lookupColumn, readModelRegistry } from "../read-model.js";
+import { registerCanonicalProjections } from "./canonical-projections.js";
+import { defineInstanceTrackingReadModel, instanceTrackingReadModelTarget, TERMINATED_STATE } from "./instance-status-read-model.js";
+import { INSTANCE_STATE_PROJECTION, InstanceStateStore } from "./instance-state-store.js";
+import { OpenUserTasksStore } from "./open-user-tasks-store.js";
 import { defaultScheduler, MAX_TIMER_DELAY_MS } from "./scheduler.js";
 /** Default poll interval when a binding does not set `pollMs`. */
 export const DEFAULT_INSTANCE_TRACKING_POLL_MS = 15_000;
@@ -40,89 +47,130 @@ export const DEFAULT_INSTANCE_TRACKING_POLL_MS = 15_000;
  *  Probing in bounded-parallel batches makes wall-clock time scale with max latency rather than
  *  N×latency, while the cap keeps in-flight load on the engine bounded. */
 export const WAITING_HUMAN_PROBE_CONCURRENCY = 8;
-/** 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 async function reconcileTerminatedKey(api, bindings, processInstanceKey) {
-    const key = String(processInstanceKey);
-    let reconciled = 0;
-    for (const binding of bindings) {
-        const table = api.data.table(binding.table, binding.keyField);
-        const changed = await table.update(key, binding.onTerminated.set);
-        if (changed > 0) {
-            reconciled += changed;
-            api.log("info", "instanceTracking: reconciled terminated instance", {
-                table: binding.table,
-                keyField: binding.keyField,
-                processInstanceKey: key,
-                rowsChanged: changed,
-            });
-        }
+/**
+ * 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 function tryInstanceProjections(api) {
+    if (!api.data.hasDefaultSource()) {
+        api.log("debug", "instanceTracking: no default data source; projection feed disabled");
+        return undefined;
+    }
+    try {
+        const { db } = api.data.source();
+        const instanceState = new InstanceStateStore(db);
+        const openUserTasks = new OpenUserTasksStore(db);
+        instanceState.ensureSchema();
+        openUserTasks.ensureSchema();
+        return { instanceState, openUserTasks };
+    }
+    catch (err) {
+        api.log("warn", "instanceTracking: failed to provision projection stores; feed disabled", {
+            error: String(err),
+        });
+        return undefined;
     }
-    return reconciled;
 }
-/** Whether `row` already satisfies `patch` on every column it sets — used to make the
- *  wait-on-human writer quiet-idempotent. Unlike a terminated row (which flips to a terminal
- *  status and then drops out of the active set), a row parked at a user task stays active and is
- *  re-polled every tick, so re-writing/re-logging the same `awaiting_operator` patch on every poll
- *  would be noise; skip the write when it would be a no-op. */
-function patchAlreadyApplied(row, set) {
-    return Object.entries(set).every(([col, value]) => row[col] === value);
+/** 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 function reconcileTerminatedKey(api, projections, processInstanceKey) {
+    const key = String(processInstanceKey ?? "");
+    if (!projections || !key)
+        return 0;
+    try {
+        // Retire the open tasks BEFORE recording TERMINATED so no reader can observe a terminated instance
+        // that still looks parked on a human (terminated wins over waiting-human, at the source as in the
+        // derivation). Both writes are idempotent.
+        projections.openUserTasks.clearInstance(key);
+        // `recordState` returns false when the state is unchanged (an already-recorded TERMINATED re-fed on a
+        // later tick or by the cancel path). Only log/count a REAL transition: without this, every repeated
+        // terminal poll of a settled instance emits an info log and inflates `reconciled` as if it wrote,
+        // producing one spurious "recorded terminated instance" line per settled instance per tick.
+        const changed = projections.instanceState.recordState(key, TERMINATED_STATE, false);
+        if (!changed)
+            return 0;
+        api.log("info", "instanceTracking: recorded terminated instance", {
+            projection: INSTANCE_STATE_PROJECTION,
+            processInstanceKey: key,
+        });
+        return 1;
+    }
+    catch (err) {
+        api.log("warn", "instanceTracking: failed to record terminated instance", {
+            processInstanceKey: key,
+            error: String(err),
+        });
+        return 0;
+    }
 }
-/** 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 async function reconcileWaitingHumanKey(api, bindings, processInstanceKey) {
-    const key = String(processInstanceKey);
-    let reconciled = 0;
-    for (const binding of bindings) {
-        const onWaitingHuman = binding.onWaitingHuman;
-        if (!onWaitingHuman)
-            continue;
-        const table = api.data.table(binding.table, binding.keyField);
-        // Quiet-idempotence must consider EVERY row sharing this key, not just one. `keyField` need not
-        // be a unique column (e.g. a read model keyed on a non-PK `process_key`), and `table.update`
-        // patches ALL matching rows — so a `get()` (LIMIT 1) that happens to hit one already-patched row
-        // would skip the write and leave the OTHER matching rows unreconciled. Skip only when every
-        // matching row already carries the patch; otherwise fall through and re-patch them all.
-        const current = await table.find({ [binding.keyField]: key });
-        if (current.length > 0 && current.every((row) => patchAlreadyApplied(row, onWaitingHuman.set))) {
-            continue;
-        }
-        const changed = await table.update(key, onWaitingHuman.set);
-        if (changed > 0) {
-            reconciled += changed;
-            api.log("info", "instanceTracking: reconciled instance awaiting operator", {
-                table: binding.table,
-                keyField: binding.keyField,
-                processInstanceKey: key,
-                rowsChanged: changed,
-            });
+/** 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 function reconcileWaitingHumanKey(api, projections, processInstanceKey, openTasks) {
+    const key = String(processInstanceKey ?? "");
+    if (!projections || !key)
+        return 0;
+    try {
+        // Re-check the terminal source IMMEDIATELY before the sync. `openTasks` was probed with an `await`
+        // that yields the event loop, so a concurrent cancel (or another binding's poll) can record this
+        // instance TERMINATED and retire its tasks WHILE the probe is in flight. Terminated wins, so
+        // re-inserting the (now stale) open tasks here would strand a row `reconcileTerminatedKey` already
+        // cleared — the key is then classified settled and never re-probed, leaving a permanent stale
+        // projection row. If it went terminal, ensure the tasks stay retired and skip the sync.
+        if (projections.instanceState.getState(key)?.state === TERMINATED_STATE) {
+            projections.openUserTasks.clearInstance(key);
+            return 0;
         }
+        projections.openUserTasks.syncInstance(key, openTasks);
+        return 1;
+    }
+    catch (err) {
+        api.log("warn", "instanceTracking: failed to record open user tasks", {
+            processInstanceKey: key,
+            error: String(err),
+        });
+        return 0;
     }
-    return reconciled;
 }
-/** Poll one binding's instances once. Selects the active rows, asks the engine which of their
- *  instances are TERMINATED, and applies `onTerminated.set` to each; then, for the binding's
- *  wait-on-human edge (`onWaitingHuman`, issue #355), applies `onWaitingHuman.set` to every
- *  non-terminated active row whose instance has an open user task. Returns how many keys were
- *  scanned and how many rows were reconciled this tick. */
-async function reconcileOnce(api, binding) {
+/** Poll one binding's instances once. Selects the active rows, asks the engine which of their instances
+ *  are TERMINATED, and FEEDS that terminal fact into the canonical `urban_instance_state` projection;
+ *  then, for the binding's wait-on-human edge (`onWaitingHuman`, issue #355), FEEDS each non-terminated
+ *  active row's current open-user-task set into `urban_open_user_tasks`. It writes NO derivable status
+ *  column on the base row — the two edges are DERIVED from the projections by the managed read-model VIEW
+ *  (ADR 0065). Returns how many keys were scanned and how many projection sources were fed this tick. */
+async function reconcileOnce(api, binding, projections) {
+    // A binding mounted without a default data source (e.g. `mount.data: false`) has no table to poll and
+    // no VIEW to derive: `provisionInstanceTrackingViews`/`tryInstanceProjections` already degraded to
+    // no-ops at mount. Return the honest zero-count no-op here rather than falling through to
+    // `api.data.table(...)`, which THROWS with no default source and would log `reconcile failed` on every
+    // interval (the timer is still armed) — noise masquerading as a real failure.
+    if (!api.data.hasDefaultSource())
+        return { scanned: 0, reconciled: 0 };
     const table = api.data.table(binding.table, binding.keyField);
     // Select the rows worth polling. Three modes, in precedence order:
     //  - `terminalStatuses` (fail-open exclusion): poll every row whose `statusField` is NOT
     //    a terminal value. A newly-added non-terminal status is polled by default, so it can't
     //    silently fall out of reconciliation; only already-terminal rows are excluded (bounded).
     //  - `activeStatuses` (fail-closed allow-list): poll only rows in an enumerated active status.
-    //  - neither: poll every row; a terminal instance's row is idempotently re-patched (the engine
-    //    query returns only TERMINATED instances and the patch is a no-op once applied).
+    //  - neither: poll every row; the engine query returns only TERMINATED instances and the projection
+    //    feed is idempotent, so re-feeding a settled row is a harmless no-op.
     // `terminalStatuses` and `activeStatuses` are mutually exclusive per binding (validation rejects
     // both); if both are somehow present, `terminalStatuses` wins (the fail-open selector). Each
     // selector is gated through the shared `isConfiguredStatusSelector` predicate (a non-empty array
@@ -134,7 +182,7 @@ async function reconcileOnce(api, binding) {
     if (statusField && isConfiguredStatusSelector(binding.terminalStatuses)) {
         const terminal = new Set(binding.terminalStatuses);
         const all = await table.all();
-        candidates = all.filter((row) => !terminal.has(String(row[statusField])));
+        candidates = all.filter((row) => !terminal.has(String(lookupColumn(row, statusField))));
     }
     else if (statusField && isConfiguredStatusSelector(binding.activeStatuses)) {
         const perStatus = await Promise.all(binding.activeStatuses.map((s) => table.find({ [statusField]: s })));
@@ -144,10 +192,14 @@ async function reconcileOnce(api, binding) {
         candidates = await table.all();
     }
     // Map each active row to its tracked instance key. A row with no/empty key can't be
-    // reconciled (it never started an instance, or the column is unset) — skip it.
+    // reconciled (it never started an instance, or the column is unset) — skip it. Resolve `keyField`
+    // with the SAME case-insensitive column lookup the read-model VIEW compiler uses (SQLite folds
+    // identifier case, so a binding `keyField: "Process_Key"` over a `process_key` column correlates in
+    // the derived VIEW): a plain case-sensitive `row[binding.keyField]` would read `undefined` here and
+    // feed NO keys into either projection, so neither terminal nor waiting-human status could derive.
     const keyToRows = new Map();
     for (const row of candidates) {
-        const raw = row[binding.keyField];
+        const raw = lookupColumn(row, binding.keyField);
         if (raw == null || raw === "")
             continue;
         const key = String(raw);
@@ -158,15 +210,38 @@ async function reconcileOnce(api, binding) {
             keyToRows.set(key, [row]);
     }
     const keys = [...keyToRows.keys()];
-    if (keys.length === 0)
-        return { scanned: 0, reconciled: 0 };
-    const snapshots = await api.engine.searchProcessInstances({
-        processInstanceKeys: keys,
-        state: "TERMINATED",
-    });
-    // Apply the terminal patch through the shared `reconcileTerminatedKey` — the one place that
-    // writes `onTerminated.set` and logs the reconcile — so the poll path and the cancel primitive
-    // can never drift on the patch or its logging (No Drift Surfaces).
+    // NB: do NOT early-return on an empty active set. A key that LEFT the active selector (its task was
+    // answered and its worker flipped it to a non-active status) still has a stale open-task projection to
+    // retire below — returning early here would strand it, re-tearing the derived edge (ADR 0065). The
+    // engine query and human probe both degrade to no-ops on an empty set, so falling through is cheap.
+    // Skip keys already recorded TERMINATED in the canonical projection: a settled instance never leaves
+    // TERMINATED, and the base row keeps its (unchanged) `statusField`, so with `activeStatuses`/no-selector
+    // it would pass the selector on every tick and be re-queried + re-fed forever (the old `table.update`
+    // moved it out of the active set; the inversion deliberately does not). The projection is the
+    // authoritative settled-set, so exclude those keys from both the engine query and the wait-on-human
+    // probe below — a pure efficiency win (the re-feed was already an idempotent no-op).
+    // `settled` drives a projection `getState` — a real SQL round trip (SELECT … WHERE
+    // process_instance_key = ?) — and is consulted for the same key up to three times per pass (the
+    // live-key filter here, then the wait-on-human `humanKeySet` build and its projected-open scan). The
+    // settled set cannot change mid-pass except for keys THIS pass terminates, and those are already
+    // excluded downstream via `terminatedKeys`, so caching the first result per key is behaviour-preserving
+    // and caps the projection at one query per distinct key (bounding a large-backlog pass's SQL fan-out).
+    const settledCache = new Map();
+    const settled = (key) => {
+        const cached = settledCache.get(key);
+        if (cached !== undefined)
+            return cached;
+        const value = projections?.instanceState.getState(key)?.state === TERMINATED_STATE;
+        settledCache.set(key, value);
+        return value;
+    };
+    const liveKeys = keys.filter((key) => !settled(key));
+    const snapshots = liveKeys.length > 0
+        ? await api.engine.searchProcessInstances({ processInstanceKeys: liveKeys, state: "TERMINATED" })
+        : [];
+    // Feed the terminal fact through the shared `reconcileTerminatedKey` — the one place that records the
+    // terminal source into `urban_instance_state` — so the poll path and the cancel primitive can never
+    // drift (No Drift Surfaces). No base-row write: the terminal status edge is DERIVED from the projection.
     let reconciled = 0;
     const terminatedKeys = new Set();
     for (const snap of snapshots) {
@@ -175,27 +250,54 @@ async function reconcileOnce(api, binding) {
         if (!keyToRows.has(snap.processInstanceKey))
             continue; // not one we were tracking
         terminatedKeys.add(snap.processInstanceKey);
-        reconciled += await reconcileTerminatedKey(api, [binding], snap.processInstanceKey);
+        reconciled += reconcileTerminatedKey(api, projections, snap.processInstanceKey);
     }
-    // Wait-on-human edge (issue #355), symmetric to onTerminated. Precedence: terminated wins, so a
-    // key reconciled as terminated above is excluded here. An instance is "waiting on a human" iff
-    // it has an open user task — the authoritative engine truth — so read `openUserTasks` (never a
-    // bare `searchUserTasks`, which lags a completion and would latch `awaiting_operator` onto a
-    // just-answered task; issue #355 "instance B"). When there is no open user task the row is left
-    // untouched, so a worker-owned transient status (running / converging / merging) survives and a
-    // stale `awaiting_operator` is not re-latched. Because the condition is derived every tick, a
-    // re-escalation after an answer re-flips to `awaiting_operator` on the next poll by construction
-    // (issue #355 "instance A"). Probe in bounded-parallel batches (`WAITING_HUMAN_PROBE_CONCURRENCY`)
-    // so a pass over a large active backlog scales with max latency rather than N×latency.
+    // Wait-on-human edge (issue #355), symmetric to onTerminated. Precedence: terminated wins, so a key
+    // recorded as terminated above (or already settled) is excluded here (its open tasks were retired). An
+    // instance is "waiting on a human" iff it has an open user task — the authoritative engine truth — so
+    // read `openUserTasks` (never a bare `searchUserTasks`, which lags a completion and would latch a closed
+    // task; issue #355 "instance B") and FEED that current open set into the projection via
+    // `reconcileWaitingHumanKey`. Feed EVERY probed key, including those with NO open task: an empty set
+    // RETIRES a just-answered task so the derived edge re-flips to non-parked by construction — this is the
+    // nano-workforce#422 fix (a stored write would have left `awaiting_operator` stale). Probe in
+    // bounded-parallel batches (`WAITING_HUMAN_PROBE_CONCURRENCY`) so a pass over a large active backlog
+    // scales with max latency rather than N×latency.
     if (binding.onWaitingHuman) {
-        const humanKeys = keys.filter((key) => !terminatedKeys.has(key)); // terminated already won
+        const humanKeySet = new Set(keys.filter((key) => !terminatedKeys.has(key) && !settled(key)));
+        // Retire stale projections INDEPENDENTLY of the active-status selector. With `activeStatuses`, a key
+        // can be projected while its task is open and then move to a non-active worker status when the task is
+        // answered — it then never passes the selector again, so its `urban_open_user_tasks` row would linger
+        // and the VIEW keep deriving `awaiting_operator` (a fresh #422 tear). Re-probe every key STILL
+        // projected as open so an answered/closed one is retired (`syncInstance([])`). The projection is
+        // app-wide, but re-syncing a key another binding owns is a harmless idempotent no-op against engine
+        // truth, so probing the whole projected set is always safe.
+        if (projections) {
+            for (const key of projections.openUserTasks.instanceKeys()) {
+                if (!terminatedKeys.has(key) && !settled(key))
+                    humanKeySet.add(key);
+            }
+        }
+        const humanKeys = [...humanKeySet];
         for (let i = 0; i < humanKeys.length; i += WAITING_HUMAN_PROBE_CONCURRENCY) {
             const batch = humanKeys.slice(i, i + WAITING_HUMAN_PROBE_CONCURRENCY);
             const perKey = await Promise.all(batch.map(async (key) => {
-                const openTasks = await api.engine.openUserTasks({ processInstanceKey: key });
-                if (openTasks.length === 0)
-                    return 0; // not parked on a human ⇒ leave the transient status
-                return reconcileWaitingHumanKey(api, [binding], key);
+                // Isolate each key's probe: one engine `openUserTasks` rejection must NOT reject the whole
+                // `Promise.all` batch. Batches are awaited sequentially, so a single permanently-failing key in
+                // an early batch would otherwise starve every key in later batches on every tick, letting their
+                // stale open-task projections persist indefinitely. On a per-key failure, log and skip (count 0)
+                // — the projection is left as-is and re-probed next pass — so one bad engine response cannot
+                // stall the rest of the backlog.
+                try {
+                    const openTasks = await api.engine.openUserTasks({ processInstanceKey: key });
+                    return reconcileWaitingHumanKey(api, projections, key, openTasks);
+                }
+                catch (err) {
+                    api.log("warn", "instanceTracking: openUserTasks probe failed; key skipped this pass", {
+                        key,
+                        error: String(err),
+                    });
+                    return 0;
+                }
             }));
             for (const n of perKey)
                 reconciled += n;
@@ -203,16 +305,242 @@ async function reconcileOnce(api, binding) {
     }
     return { scanned: keys.length, reconciled };
 }
+/** Is there a NON-view object (a real table) named `name` in the database? SQLite shares one namespace
+ *  for tables and views, so a real table shadows a managed VIEW: `DROP VIEW IF EXISTS` won't remove it
+ *  and `CREATE VIEW IF NOT EXISTS` then silently no-ops. Provisioning must refuse rather than appear to
+ *  succeed while a page reads the wrong object. The name match is `COLLATE NOCASE`: SQLite resolves
+ *  object names case-insensitively, so a real table `plans__tracking` shadows a configured view
+ *  `Plans__tracking` at DROP/CREATE time — a binary `=` here would miss it and defeat this guard. */
+function nonViewObjectExists(db, name) {
+    const rows = db.all(`SELECT type FROM sqlite_master WHERE name = ? COLLATE NOCASE AND type <> 'view'`, [name]);
+    return rows.length > 0;
+}
+/** Retire (DROP) a previously-managed tracking VIEW by name. Used on every skip path (a binding with no
+ *  `statusField`, a base-column collision) so a manifest change or a schema drift cannot leave a stale,
+ *  still-readable derived surface behind. Only ever drops a VIEW (never a real table of the same name),
+ *  and never throws through — a retire failure must not break the mount. */
+function retireManagedTrackingView(api, db, viewName, table) {
+    try {
+        db.exec(`DROP VIEW IF EXISTS main."${viewName}";`);
+    }
+    catch (err) {
+        api.log("warn", `instanceTracking: failed to retire stale derived VIEW "${viewName}"`, {
+            table,
+            error: String(err),
+        });
+    }
+}
+/** Retire (DROP) every managed tracking VIEW for these bindings, used when the projection feed is
+ *  unavailable (`tryInstanceProjections` returned undefined because projection-store provisioning
+ *  failed). Without this, a VIEW an earlier successful boot published is left readable and keeps
+ *  deriving a value over projection tables this mount has no coherent source for — a silent stale
+ *  surface. Retiring turns that into an honest "no such object" instead. Absent- and error-safe: with
+ *  no default data source there is no db and nothing managed to retire, and a retire failure never
+ *  breaks the mount. Deduplicates by folded VIEW name (a status-bearing + status-less binding on one
+ *  table share the default name) so we DROP each once. */
+function retireInstanceTrackingViews(api, bindings) {
+    if (bindings.length === 0)
+        return;
+    if (!api.data.hasDefaultSource())
+        return;
+    let db;
+    try {
+        db = api.data.source().db;
+    }
+    catch (err) {
+        api.log("warn", "instanceTracking: failed to resolve default source; stale derived VIEWs not retired", {
+            error: String(err),
+        });
+        return;
+    }
+    const retired = new Set();
+    for (const binding of bindings) {
+        let viewName;
+        try {
+            viewName = assertSqlIdentifier("instanceTracking.readModel.view", instanceTrackingReadModelTarget(binding).view);
+        }
+        catch {
+            // A non-identifier view name was never provisionable, so there is nothing managed to retire.
+            continue;
+        }
+        const folded = viewName.toLowerCase();
+        if (retired.has(folded))
+            continue;
+        retired.add(folded);
+        retireManagedTrackingView(api, db, viewName, binding.table);
+    }
+}
+/** Provision each binding's DERIVED read-model VIEW on the app's default data source (ADR 0065, the
+ *  writer→source inversion). The VIEW re-exports `base.*` plus a derived effective-status column computed
+ *  by a `defineReadModel` derivation over the canonical projections, so the operator page reads the
+ *  derived status with no stored write. Registers the canonical projection NAME→physical-table mapping
+ *  first (idempotent) so the VIEW's `EXISTS` resolves to the `_urban_*` tables even if the worker mount
+ *  did not run. Truly MANAGED — DROP+CREATE — so a changed derivation always replaces a stale VIEW body.
+ *  Absent- and error-safe like lineage: no default source provisions nothing, and a VIEW failure never
+ *  breaks the mount. A binding with no `statusField` has no derivable status, so no VIEW is provisioned
+ *  (its projections are still fed). */
+function provisionInstanceTrackingViews(api, bindings) {
+    if (bindings.length === 0)
+        return;
+    // Make the DSL projection names (`urban_instance_state` / `urban_open_user_tasks`) resolve to their
+    // physical `_urban_*` tables. Idempotent; safe even when the worker mount already registered them.
+    registerCanonicalProjections();
+    if (!api.data.hasDefaultSource()) {
+        api.log("debug", "instanceTracking: no default data source; derived VIEW provisioning skipped");
+        return;
+    }
+    let db;
+    try {
+        db = api.data.source().db;
+    }
+    catch (err) {
+        api.log("warn", "instanceTracking: failed to resolve default source; derived VIEWs not provisioned", {
+            error: String(err),
+        });
+        return;
+    }
+    // View names claimed by a CURRENT status-bearing binding (folded — SQLite folds identifiers). A
+    // status-less binding shares its base table's default `<table>__tracking` name with a status-bearing
+    // binding on the same table, and its retire path (below) would otherwise DROP the view that binding
+    // just created (iteration-order dependent). Validation guarantees no two status-bearing bindings share
+    // a view name, so this set is unambiguous. Retirement consults it so it only drops UNCLAIMED names.
+    const claimedByStatusful = new Set();
+    for (const b of bindings) {
+        if (typeof b.statusField !== "string" || b.statusField.length === 0)
+            continue;
+        claimedByStatusful.add(instanceTrackingReadModelTarget(b).view.toLowerCase());
+    }
+    for (const binding of bindings) {
+        // Resolve the managed VIEW name (config override or `<table>__tracking`) up front — we need it even
+        // on the skip paths below to RETIRE a previously-managed VIEW, so a manifest change (statusField
+        // dropped) or a collision cannot leave a stale, still-readable derived surface behind.
+        const { view: targetView, statusColumn } = instanceTrackingReadModelTarget(binding);
+        let viewName;
+        try {
+            viewName = assertSqlIdentifier("instanceTracking.readModel.view", targetView);
+        }
+        catch (err) {
+            api.log("warn", "instanceTracking: invalid read-model view name; derived VIEW skipped", {
+                table: binding.table,
+                error: String(err),
+            });
+            continue;
+        }
+        let model;
+        try {
+            model = defineInstanceTrackingReadModel(binding);
+        }
+        catch (err) {
+            api.log("warn", "instanceTracking: invalid read-model config; derived VIEW skipped", {
+                table: binding.table,
+                error: String(err),
+            });
+            continue;
+        }
+        if (!model) {
+            // No statusField ⇒ nothing derivable to project. Retire any VIEW an earlier boot managed under
+            // this name — UNLESS a current status-bearing binding claims the same name (a status-bearing +
+            // status-less binding on one table share the default view name; retiring here would drop the view
+            // the owner provisions). Without the retire, dropping `statusField` from a binding would otherwise
+            // leave the old derived surface discoverable/readable while the runtime believes it provisioned
+            // nothing.
+            if (!claimedByStatusful.has(viewName.toLowerCase())) {
+                retireManagedTrackingView(api, db, viewName, binding.table);
+            }
+            continue;
+        }
+        // Base-column collision guard (ADR 0065): the VIEW selects `base.*` and appends the derived status as
+        // `${statusColumn} AS ...`. If the base table ALREADY has a column of that name (the default
+        // `derived_status`, or an override that happens to match a real column), SQLite keeps the base column
+        // under that name and auto-renames the derived one — provisioning "succeeds" but a page querying
+        // `statusColumn` reads the STALE stored value. Detect it and skip (loudly) rather than publish a VIEW
+        // that silently defeats the derivation. `readModel.statusColumn === statusField` is already rejected at
+        // manifest validation; this catches collisions with ANY other base column, which needs the live schema.
+        try {
+            const cols = db.all(`PRAGMA table_info("${assertSqlIdentifier("instanceTracking.table", binding.table)}")`);
+            const folded = statusColumn.toLowerCase();
+            if (cols.some((c) => typeof c.name === "string" && c.name.toLowerCase() === folded)) {
+                api.log("warn", `instanceTracking: derived status column "${statusColumn}" collides with an existing "${binding.table}" column; derived VIEW skipped (set readModel.statusColumn to a non-colliding name)`, { table: binding.table, statusColumn });
+                // Retire any stale VIEW managed under this name — a collision means we can't publish a CORRECT
+                // derivation, and leaving an earlier boot's VIEW in place would keep serving a stale surface.
+                retireManagedTrackingView(api, db, viewName, binding.table);
+                continue;
+            }
+        }
+        catch (err) {
+            api.log("warn", "instanceTracking: failed to introspect base columns; derived VIEW skipped", {
+                table: binding.table,
+                error: String(err),
+            });
+            continue;
+        }
+        // A real (non-view) object of this name shares SQLite's table/view namespace: `DROP VIEW IF EXISTS`
+        // won't remove it and `CREATE VIEW IF NOT EXISTS` then silently no-ops, so a page configured for this
+        // view would read the wrong object with no derived column while the mount looks successful. Refuse
+        // explicitly rather than pretend to provision. (Cross-binding name/table collisions are rejected at
+        // manifest validation; this catches an undeclared app table that happens to share the name.)
+        try {
+            if (nonViewObjectExists(db, viewName)) {
+                api.log("warn", `instanceTracking: managed VIEW name "${viewName}" is taken by an existing non-view object; derived VIEW skipped (choose a distinct readModel.view)`, { table: binding.table, view: viewName });
+                continue;
+            }
+        }
+        catch (err) {
+            api.log("warn", "instanceTracking: failed to inspect existing objects; derived VIEW skipped", {
+                table: binding.table,
+                error: String(err),
+            });
+            continue;
+        }
+        // A registered read model (seam (a): `readModelRegistry`) already OWNS a VIEW of this name —
+        // `mountWorkers` provisioned it before this mount. Our unconditional `DROP VIEW … ; CREATE VIEW …`
+        // below would silently clobber that registered derivation (and a later worker mount could clobber
+        // ours back), with neither side detecting the conflict the registry itself rejects for two registered
+        // models. Refuse rather than fight over the name, mirroring the `nonViewObjectExists` guard above.
+        if (readModelRegistry.get(viewName)) {
+            api.log("warn", `instanceTracking: managed VIEW name "${viewName}" collides with a registered read model; derived VIEW skipped (choose a distinct readModel.view)`, { table: binding.table, view: viewName });
+            continue;
+        }
+        try {
+            // Qualify the DROP to `main.` for the same reason `ReadModelRegistry.ensureViews` does: an
+            // unqualified DROP resolves a stray TEMP view of the same name first (e.g. leaked from a parity
+            // run), leaving the managed `main` view stale.
+            db.exec(`DROP VIEW IF EXISTS main."${viewName}";`);
+            db.exec(model.viewDdl());
+        }
+        catch (err) {
+            api.log("warn", `instanceTracking: failed to provision derived VIEW "${model.decl.name}"`, {
+                error: String(err),
+            });
+        }
+    }
+}
 /**
- * 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.
+ * 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 function mountInstanceTracking(ctx, api, sched = defaultScheduler()) {
     const bindings = ctx.manifest.instanceTracking ?? [];
     const timers = new Set();
     const armed = [];
     let stopped = false;
+    // Ensure the canonical projection tables (`_urban_*`) exist BEFORE creating the derived VIEWs that
+    // SELECT over them: a VIEW built on missing sidecar tables is created fine (SQLite does not validate a
+    // view body) but then reads `no such table`, so the mount would look successful while the page fails.
+    // Both are absent-safe: with no default data source `projections` is undefined and no VIEW is
+    // provisioned, so each poll degrades to a pure engine query that feeds nothing (never throwing). When
+    // projection setup FAILS after an earlier boot succeeded (undefined despite a default source), there is
+    // nothing coherent to derive over, so instead of leaving a prior boot's VIEW readable over an
+    // unavailable/stale projection we RETIRE the managed VIEWs — an honest missing surface, not a silent
+    // stale one.
+    const projections = tryInstanceProjections(api);
+    if (projections)
+        provisionInstanceTrackingViews(api, bindings);
+    else
+        retireInstanceTrackingViews(api, bindings);
     for (const binding of bindings) {
         // `pollMs` feeds a self-rescheduling timer, so a non-number/NaN/zero/negative value would
         // clamp to a 0-delay hot loop. `??` only guards null/undefined; sanitize to a finite positive
@@ -238,7 +566,7 @@ export function mountInstanceTracking(ctx, api, sched = defaultScheduler()) {
                     return;
                 void (async () => {
                     try {
-                        await reconcileOnce(api, binding);
+                        await reconcileOnce(api, binding, projections);
                     }
                     catch (err) {
                         api.log("error", `instanceTracking "${label}": reconcile failed`, {