@nanobpm/urban 0.80.0 → 0.81.0

package/dist/runtime/core/modules/open-user-tasks-store.d.ts

@@ -56,6 +56,11 @@ export declare class OpenUserTasksStore {
     syncInstance(processInstanceKey: string, openTasks: readonly UserTaskSummary[]): void;
     /** Retire every projected open task for an instance (e.g. it terminated). Idempotent. */
     clearInstance(processInstanceKey: string): void;
+    /** Every distinct instance key currently projected as having ≥1 open user task. Used by the
+     *  reconciler to re-probe (and, when answered, RETIRE) keys that have dropped out of a binding's
+     *  `activeStatuses` allow-list — a projected row must be retired independently of the base-row
+     *  selector, or an answered escalation's row would linger and the derived edge tear (ADR 0065). */
+    instanceKeys(): string[];
     /** True iff the instance currently has any open user task — the "parked on a human" predicate. */
     hasOpenTask(processInstanceKey: string): boolean;
     /** The projected open tasks for an instance, in insertion order. */

package/dist/runtime/core/modules/open-user-tasks-store.js

@@ -113,6 +113,14 @@ export class OpenUserTasksStore {
             return;
         this.#db.run(`DELETE FROM ${OPEN_USER_TASKS_TABLE} WHERE process_instance_key = ?`, [processInstanceKey]);
     }
+    /** Every distinct instance key currently projected as having ≥1 open user task. Used by the
+     *  reconciler to re-probe (and, when answered, RETIRE) keys that have dropped out of a binding's
+     *  `activeStatuses` allow-list — a projected row must be retired independently of the base-row
+     *  selector, or an answered escalation's row would linger and the derived edge tear (ADR 0065). */
+    instanceKeys() {
+        const rows = this.#db.all(`SELECT DISTINCT process_instance_key FROM ${OPEN_USER_TASKS_TABLE}`);
+        return rows.map((r) => r.process_instance_key);
+    }
     /** True iff the instance currently has any open user task — the "parked on a human" predicate. */
     hasOpenTask(processInstanceKey) {
         if (!processInstanceKey)

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

@@ -32,6 +32,7 @@ import { FORMJS_JS } from "./formjs.gen.js";
 import { completeUserTaskResponse, resolveFormResponse } from "./forms.js";
 import { quoteIdent } from "./gateway.js";
 import { RENDERER_JS } from "./runtime.gen.js";
+import { isSqlIdentifier } from "../read-model.js";
 /** A JavaScript-body response (the renderer module served at the fingerprinted
  * `/app/runtime.<hash>.js`, and its `/app/runtime.js` back-compat route). */
 function javascript(body, status = 200, extraHeaders) {
@@ -118,9 +119,10 @@ async function serveAsset(read, filePath) {
         return { status: 404, headers: { "content-type": "text/plain; charset=utf-8" }, body: "not found" };
     }
 }
-/** A SQL identifier guard — a table name must be a bare identifier *and* a known table
- * (checked against `schema()`), so `/app/data/:table` can never inject SQL. */
-const IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** A table name must be a bare SQL identifier ({@link isSqlIdentifier}, the runtime-wide single source
+ * of truth) *and* a known table (checked against `schema()`), so `/app/data/:table` can never inject
+ * SQL. Reusing the shared guard (rather than a private regex) keeps this surface from drifting from
+ * manifest / read-model / data-source identifier validation. */
 // A query flag (e.g. ?count=1) is "on" when present and not one of the falsy
 // spellings. A bare `?count` (empty string) still counts as on, so a caller can
 // opt in without inventing a value.
@@ -299,7 +301,7 @@ export function createPagesRoutes(opts, deps) {
             // source is rejected rather than silently served off the default.
             if (source !== sourceName)
                 return json({ error: `unknown datasource "${source}"` }, 404);
-            if (!IDENT.test(table))
+            if (!isSqlIdentifier(table))
                 return json({ error: "invalid table name" }, 400);
             let tables;
             try {

package/dist/runtime/core/read-model.d.ts

@@ -128,7 +128,27 @@ export interface SqlCompileOptions {
     /** Resolve a projection NAME to its physical SQL table/view. Defaults to {@link projectionRegistry}. */
     readonly resolveProjectionTable?: (name: string) => string;
 }
+/** A conservative SQL identifier guard — we interpolate names directly into DDL/SQL. This is the
+ *  single source of truth for "is this a legal identifier"; the manifest validator imports it (rather
+ *  than re-declaring the regex) so a name accepted at author time is accepted at VIEW provisioning too
+ *  (No Drift Surfaces — a divergence would let a manifest validate but fail at boot). */
+export declare const SQL_IDENT: RegExp;
+/** True iff `name` is a legal SQL identifier per {@link SQL_IDENT}. The boolean twin of
+ *  {@link assertSqlIdentifier}, for callers (e.g. the manifest validator) that collect issues rather
+ *  than throw. */
+export declare function isSqlIdentifier(name: string): boolean;
 export declare function assertSqlIdentifier(kind: string, name: string): string;
+/** Object-name prefixes reserved for engine/runtime internals. Tables and views whose names begin
+ *  with one of these are Nano bookkeeping (`_urban_*` / `_nano_*`) or SQLite internals (`sqlite_*`):
+ *  the provenance recorder skips them (`modules/datasource.ts`) and the datasource `schema()` surface
+ *  filters them out (`modules/gateway.ts`), so they are invisible to `/app/data`, DB Manager, and forms.
+ *  This is the single source of truth for that prefix set (No Drift Surfaces — a manifest that provisions
+ *  a `_urban_*` VIEW would otherwise validate yet be unreadable by the documented pages surface). */
+export declare const RESERVED_OBJECT_PREFIXES: readonly ["_urban_", "_nano_", "sqlite_"];
+/** True iff `name` begins with a {@link RESERVED_OBJECT_PREFIXES} prefix. Case-insensitive, matching
+ *  SQLite's ASCII identifier folding (a `_URBAN_x` table resolves to the same reserved object as
+ *  `_urban_x`), so a reserved name cannot slip through by casing. */
+export declare function isReservedObjectName(name: string): boolean;
 /**
  * Compile ONE derivation expression to a SQLite select-list expression string — the derived column's
  * body inside the managed VIEW. Both backends walk the SAME AST, so the SQL here and the function
@@ -143,6 +163,14 @@ export type DerivationFn = (baseRow: BaseRow, projections?: ProjectionRows) => u
  * named projection's rows (the TS side of the projection-name seam). Both backends walk the SAME AST.
  */
 export declare function compileToFn(expr: Expr): DerivationFn;
+/** Resolve a column value the way SQLite resolves an identifier: an exact-key match first, then a
+ *  case-insensitive fallback. SQLite folds ASCII identifier case even for quoted identifiers, so the
+ *  VIEW's `col("Status")` binds to a table declared with column `status`; a plain case-sensitive JS
+ *  `row["Status"]` would miss it and return null, breaking VIEW/TS parity on the no-edge fallback and on
+ *  `keyField` correlation. Fold here so both backends read the same column. (A table cannot declare two
+ *  columns differing only in case, so the fallback is unambiguous.) Returns `null` for a missing column,
+ *  preserving the previous `?? null` contract. */
+export declare function lookupColumn(row: Record<string, unknown>, name: string): unknown;
 /** The declarative read-model input passed to {@link defineReadModel}. */
 export interface ReadModelDecl {
     /** The managed VIEW name (also the read-model identifier). */

package/dist/runtime/core/read-model.js

@@ -133,14 +133,37 @@ const DEFAULT_BASE_ALIAS = "base";
 function resolveBaseAlias(alias) {
     return assertSqlIdentifier("base alias", alias ?? DEFAULT_BASE_ALIAS);
 }
-/** A conservative SQL identifier guard — we interpolate names directly into DDL/SQL. */
-const SQL_IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** A conservative SQL identifier guard — we interpolate names directly into DDL/SQL. This is the
+ *  single source of truth for "is this a legal identifier"; the manifest validator imports it (rather
+ *  than re-declaring the regex) so a name accepted at author time is accepted at VIEW provisioning too
+ *  (No Drift Surfaces — a divergence would let a manifest validate but fail at boot). */
+export const SQL_IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** True iff `name` is a legal SQL identifier per {@link SQL_IDENT}. The boolean twin of
+ *  {@link assertSqlIdentifier}, for callers (e.g. the manifest validator) that collect issues rather
+ *  than throw. */
+export function isSqlIdentifier(name) {
+    return SQL_IDENT.test(name);
+}
 export function assertSqlIdentifier(kind, name) {
     if (!SQL_IDENT.test(name)) {
         throw new Error(`invalid ${kind} "${name}": must match ${SQL_IDENT.source}`);
     }
     return name;
 }
+/** Object-name prefixes reserved for engine/runtime internals. Tables and views whose names begin
+ *  with one of these are Nano bookkeeping (`_urban_*` / `_nano_*`) or SQLite internals (`sqlite_*`):
+ *  the provenance recorder skips them (`modules/datasource.ts`) and the datasource `schema()` surface
+ *  filters them out (`modules/gateway.ts`), so they are invisible to `/app/data`, DB Manager, and forms.
+ *  This is the single source of truth for that prefix set (No Drift Surfaces — a manifest that provisions
+ *  a `_urban_*` VIEW would otherwise validate yet be unreadable by the documented pages surface). */
+export const RESERVED_OBJECT_PREFIXES = ["_urban_", "_nano_", "sqlite_"];
+/** True iff `name` begins with a {@link RESERVED_OBJECT_PREFIXES} prefix. Case-insensitive, matching
+ *  SQLite's ASCII identifier folding (a `_URBAN_x` table resolves to the same reserved object as
+ *  `_urban_x`), so a reserved name cannot slip through by casing. */
+export function isReservedObjectName(name) {
+    const folded = name.toLowerCase();
+    return RESERVED_OBJECT_PREFIXES.some((p) => folded.startsWith(p));
+}
 function quoteIdent(name) {
     return `"${name.replace(/"/g, '""')}"`;
 }
@@ -365,11 +388,11 @@ export function compileToFn(expr) {
             case "lit":
                 return node.value;
             case "col":
-                return baseRow[node.name] ?? null;
+                return lookupColumn(baseRow, node.name);
             case "pcol":
                 if (!projRow)
                     throw new Error(`pcol("${node.name}") evaluated outside an EXISTS projection context`);
-                return projRow[node.name] ?? null;
+                return lookupColumn(projRow, node.name);
             case "compare":
                 return compareValues(node.op, evalNode(node.left, baseRow, projections, projRow), evalNode(node.right, baseRow, projections, projRow));
             case "and":
@@ -394,6 +417,23 @@ export function compileToFn(expr) {
     };
     return (baseRow, projections = {}) => evalNode(expr, baseRow, projections);
 }
+/** Resolve a column value the way SQLite resolves an identifier: an exact-key match first, then a
+ *  case-insensitive fallback. SQLite folds ASCII identifier case even for quoted identifiers, so the
+ *  VIEW's `col("Status")` binds to a table declared with column `status`; a plain case-sensitive JS
+ *  `row["Status"]` would miss it and return null, breaking VIEW/TS parity on the no-edge fallback and on
+ *  `keyField` correlation. Fold here so both backends read the same column. (A table cannot declare two
+ *  columns differing only in case, so the fallback is unambiguous.) Returns `null` for a missing column,
+ *  preserving the previous `?? null` contract. */
+export function lookupColumn(row, name) {
+    if (Object.hasOwn(row, name))
+        return row[name] ?? null;
+    const folded = name.toLowerCase();
+    for (const key of Object.keys(row)) {
+        if (key.toLowerCase() === folded)
+            return row[key] ?? null;
+    }
+    return null;
+}
 function collectProjectionNames(expr, into) {
     switch (expr.kind) {
         case "exists":

package/dist/runtime/core/validate.js

@@ -10,6 +10,8 @@
 import schema from "@nanobpm/nano-app-schema/schema" with { type: "json" };
 import { isRecord } from "./guards.js";
 import { BIND_MODES, NETWORK_KEYS, isBindMode, isConfiguredStatusSelector } from "./manifest.js";
+import { DEFAULT_DERIVED_STATUS_COLUMN, defaultInstanceTrackingViewName, } from "./modules/instance-status-read-model.js";
+import { SQL_IDENT, isReservedObjectName } from "./read-model.js";
 export class ManifestValidationError extends Error {
     issues;
     constructor(issues) {
@@ -169,12 +171,47 @@ export function collectManifestIssues(m) {
     if (tracking) {
         tracking.forEach((t, i) => {
             const b = isRecord(t) ? t : undefined;
+            // Only a status-bearing binding builds a derived VIEW; a status-less binding just feeds projections
+            // and is polled through `api.data.table()`, whose `Table<T>` gateway safely `quoteIdent`s the base
+            // table and key column (so a name like `external-orders` works). The SQL_IDENT restriction below is
+            // therefore required ONLY when a VIEW is actually built (`table`/`keyField` are interpolated raw into
+            // its DDL/edge predicates then) — enforcing it on a status-less binding wrongly rejects a valid name
+            // that provisioning never touches. Gate on `buildsView` so validation and provisioning agree exactly
+            // (No Drift — a name is rejected here iff it would break at VIEW build).
+            const buildsView = typeof b?.statusField === "string" && b.statusField.length > 0;
             if (typeof b?.table !== "string" || b.table.length === 0) {
                 issues.push({ path: `instanceTracking[${i}].table`, message: "missing table" });
             }
+            else if (buildsView && !SQL_IDENT.test(b.table)) {
+                // The base `table` is compiled directly into the derived VIEW's DDL (`defineReadModel` asserts
+                // `baseTable` matches SQL_IDENT). Manifest validation historically only checked non-empty, so a
+                // name like `external-orders` validated and was polled while the VIEW was silently skipped at
+                // mount (read-model construction throws). Enforce the identifier rule at author time so validation
+                // and provisioning agree (No Drift — a name accepted here is accepted at VIEW build).
+                issues.push({
+                    path: `instanceTracking[${i}].table`,
+                    message: `table must be a SQL identifier (${SQL_IDENT.source})`,
+                });
+            }
             if (typeof b?.keyField !== "string" || b.keyField.length === 0) {
                 issues.push({ path: `instanceTracking[${i}].keyField`, message: "missing keyField" });
             }
+            else if (buildsView && !SQL_IDENT.test(b.keyField)) {
+                // `keyField` is interpolated into the derived VIEW's edge predicates (`terminatedEdgeExpr`), so it
+                // must be a bare identifier for the same reason `table` must — but only when a VIEW is built.
+                issues.push({
+                    path: `instanceTracking[${i}].keyField`,
+                    message: `keyField must be a SQL identifier (${SQL_IDENT.source})`,
+                });
+            }
+            // `statusField`, when present, becomes a VIEW output column (`col(statusField)`), so it must also be
+            // a bare identifier — a non-identifier would fail opaquely at VIEW construction.
+            if (typeof b?.statusField === "string" && b.statusField.length > 0 && !SQL_IDENT.test(b.statusField)) {
+                issues.push({
+                    path: `instanceTracking[${i}].statusField`,
+                    message: `statusField must be a SQL identifier (${SQL_IDENT.source})`,
+                });
+            }
             const onTerminated = isRecord(b?.onTerminated) ? b.onTerminated : undefined;
             const set = isRecord(onTerminated?.set) ? onTerminated.set : undefined;
             if (!set || Object.keys(set).length === 0) {
@@ -183,6 +220,9 @@ export function collectManifestIssues(m) {
                     message: "missing onTerminated.set patch (a non-empty column → value map)",
                 });
             }
+            // The single derived-status target for this binding (used by the readModel.statusColumn collision
+            // guard below). Undefined when absent/blank.
+            const statusFieldName = typeof b?.statusField === "string" && b.statusField.length > 0 ? b.statusField : undefined;
             // `onWaitingHuman` (issue #355) is the optional wait-on-human edge — the twin of
             // `onTerminated`. It is optional (a binding may reconcile only the terminal edge), but when
             // present its `set` must be a non-empty column → value patch for the same reason
@@ -246,6 +286,158 @@ export function collectManifestIssues(m) {
                     message: "pollMs must be a finite positive number of milliseconds",
                 });
             }
+            // `readModel` (ADR 0065, the writer→source inversion) overrides the derived status VIEW name /
+            // column the runtime provisions. Both are compiled into SQL identifiers, so a non-identifier
+            // value would fail opaquely at VIEW provisioning; validate them here. The VIEW must differ from
+            // the base `table` (SQLite forbids a view and a table sharing a name).
+            if (b?.readModel !== undefined) {
+                const rm = isRecord(b.readModel) ? b.readModel : undefined;
+                if (!rm) {
+                    issues.push({
+                        path: `instanceTracking[${i}].readModel`,
+                        message: "readModel must be an object with optional `view` / `statusColumn`",
+                    });
+                }
+                else {
+                    // Mirror the schema's `additionalProperties: false` intent (as the `network` block does): reject
+                    // unknown keys so a typo like `statusColum` fails loudly instead of silently falling back to the
+                    // default derived column while the page reads the wrong field.
+                    for (const k of Object.keys(rm)) {
+                        if (k !== "view" && k !== "statusColumn") {
+                            issues.push({
+                                path: `instanceTracking[${i}].readModel.${k}`,
+                                message: "unknown key (readModel additionalProperties: false)",
+                            });
+                        }
+                    }
+                    for (const field of ["view", "statusColumn"]) {
+                        const v = rm[field];
+                        if (v !== undefined && (typeof v !== "string" || !SQL_IDENT.test(v))) {
+                            issues.push({
+                                path: `instanceTracking[${i}].readModel.${field}`,
+                                message: `readModel.${field} must be a SQL identifier (${SQL_IDENT.source})`,
+                            });
+                        }
+                    }
+                    // Fold case before comparing: `defineReadModel`/SQLite treat identifiers case-insensitively,
+                    // so `table:"plans"` + `readModel.view:"Plans"` would pass a case-sensitive check here yet be
+                    // rejected as a base-table collision at VIEW construction. Compare folded so author-time
+                    // validation matches provisioning behavior.
+                    if (typeof rm.view === "string" && typeof b?.table === "string" && rm.view.toLowerCase() === b.table.toLowerCase()) {
+                        issues.push({
+                            path: `instanceTracking[${i}].readModel.view`,
+                            message: "readModel.view must differ from the base table (a view cannot shadow its table)",
+                        });
+                    }
+                    // The VIEW emits `${statusColumn} AS ...` after `base.*`; if the derived status column folds to
+                    // the same identifier as the base `statusField`, SQLite exposes two output columns of that name
+                    // and keeps the base (stored) one — so consumers read the STALE value, silently defeating the
+                    // derivation. Reject the collision at author time (case-insensitive, matching SQLite's folding).
+                    if (typeof rm.statusColumn === "string" && statusFieldName !== undefined &&
+                        rm.statusColumn.toLowerCase() === statusFieldName.toLowerCase()) {
+                        issues.push({
+                            path: `instanceTracking[${i}].readModel.statusColumn`,
+                            message: `readModel.statusColumn must differ from statusField "${statusFieldName}" (a same-named derived column is shadowed by the stored base column and reads stale)`,
+                        });
+                    }
+                }
+            }
+            // Validate the EFFECTIVE default target too, not just an explicit override. When
+            // `readModel.statusColumn` is omitted (or `readModel` entirely), the VIEW derives the status
+            // under the default column `derived_status`. A binding with `statusField: "derived_status"` and
+            // no override therefore collides with the default derived column exactly as an explicit override
+            // would — SQLite keeps the stored base column and the derived read is stale. The explicit-override
+            // collision is caught above; this closes the omitted-override path (which the runtime would
+            // otherwise only discover at boot, then skip the VIEW).
+            const rmRec = isRecord(b?.readModel) ? b.readModel : undefined;
+            const hasExplicitStatusColumn = typeof rmRec?.statusColumn === "string" && rmRec.statusColumn.length > 0;
+            if (statusFieldName !== undefined && !hasExplicitStatusColumn &&
+                DEFAULT_DERIVED_STATUS_COLUMN.toLowerCase() === statusFieldName.toLowerCase()) {
+                issues.push({
+                    path: `instanceTracking[${i}].statusField`,
+                    message: `statusField "${statusFieldName}" collides with the default derived status column "${DEFAULT_DERIVED_STATUS_COLUMN}" (set readModel.statusColumn to a distinct name, or rename statusField)`,
+                });
+            }
+            // Reserved-base-table guard (ADR 0065): the base `table` must not itself be a reserved runtime
+            // object (`_urban_` / `_nano_` / `sqlite_`). The reserved-VIEW guard below only rejects a reserved
+            // *effective view name*, so a binding like `table: "_urban_instance_state", readModel: { view:
+            // "tracking" }` slips through — it would publish a NON-reserved `tracking` VIEW that SELECTs the
+            // runtime's hidden instance-state sidecar, and `gateway.schema()` filters only the object NAME, so
+            // `/app/data/.../tracking` would expose those internal rows. A tracking binding over a reserved
+            // runtime table is never legitimate; reject it at author time regardless of statusField.
+            if (typeof b?.table === "string" && b.table.length > 0 && isReservedObjectName(b.table)) {
+                issues.push({
+                    path: `instanceTracking[${i}].table`,
+                    message: `base table "${b.table}" uses a reserved prefix (_urban_ / _nano_ / sqlite_); tracking a reserved runtime table would publish a derived VIEW over hidden runtime state (choose an application base table)`,
+                });
+            }
+            // Reserved-prefix guard (ADR 0065): the effective managed VIEW name (`readModel.view` or the
+            // default `<table>__tracking`) must not begin with a reserved object prefix (`_urban_` / `_nano_`
+            // / `sqlite_`). Such a VIEW provisions fine but is filtered out of the datasource `schema()`
+            // surface (`gateway.ts`), so the operator page configured for it reads `unknown table`. Reject at
+            // author time rather than let it fail opaquely at read. Only bindings with a `statusField`
+            // provision a VIEW, so only those can hit this.
+            if (statusFieldName !== undefined && typeof b?.table === "string" && b.table.length > 0) {
+                const rmView = typeof rmRec?.view === "string" && rmRec.view.length > 0 ? rmRec.view : undefined;
+                const effectiveView = rmView ?? defaultInstanceTrackingViewName(b.table);
+                if (isReservedObjectName(effectiveView)) {
+                    issues.push({
+                        path: rmView ? `instanceTracking[${i}].readModel.view` : `instanceTracking[${i}].table`,
+                        message: `managed VIEW name "${effectiveView}" uses a reserved prefix (_urban_ / _nano_ / sqlite_); such a view is hidden from the datasource surface and cannot be read by a page (choose a non-reserved readModel.view or base table name)`,
+                    });
+                }
+            }
+        });
+        // Duplicate managed-VIEW names across bindings (ADR 0065): each binding's read model DROP+CREATEs a
+        // VIEW named `readModel.view` or, by default, `<table>__tracking`. Two bindings that fold to the same
+        // VIEW name (two bindings on one base table with no distinct override, or names differing only by
+        // case) would silently clobber each other at provisioning — the later CREATE wins and the earlier
+        // binding loses its derivation. Reject the collision here, folded (SQLite folds identifiers), naming
+        // both bindings. Only bindings with a `statusField` provision a VIEW, so only those can collide.
+        const viewOwners = new Map();
+        // Also reserve every binding's BASE TABLE name: SQLite shares one namespace for tables and views,
+        // so a managed VIEW `orders__tracking` for one binding collides with another binding whose base
+        // `table` is `orders__tracking`. The manifest would pass validation, then `CREATE VIEW` fails at boot
+        // and the first binding loses its derived surface. Collect base tables first (folded), then flag any
+        // managed-view name that lands on one.
+        const baseTableOwners = new Map();
+        tracking.forEach((t, i) => {
+            const b = isRecord(t) ? t : undefined;
+            if (typeof b?.table !== "string" || b.table.length === 0)
+                return;
+            const folded = b.table.toLowerCase();
+            if (!baseTableOwners.has(folded))
+                baseTableOwners.set(folded, i);
+        });
+        tracking.forEach((t, i) => {
+            const b = isRecord(t) ? t : undefined;
+            if (typeof b?.table !== "string" || b.table.length === 0)
+                return;
+            if (typeof b?.statusField !== "string" || b.statusField.length === 0)
+                return; // no VIEW ⇒ no collision
+            const rm = isRecord(b.readModel) ? b.readModel : undefined;
+            const view = typeof rm?.view === "string" && rm.view.length > 0 ? rm.view : defaultInstanceTrackingViewName(b.table);
+            const folded = view.toLowerCase();
+            const prev = viewOwners.get(folded);
+            if (prev !== undefined) {
+                issues.push({
+                    path: `instanceTracking[${i}].readModel.view`,
+                    message: `managed VIEW name "${view}" collides with instanceTracking[${prev}] (identifiers fold case-insensitively); give each binding a distinct readModel.view`,
+                });
+            }
+            else {
+                viewOwners.set(folded, i);
+            }
+            // A managed VIEW name that folds to another binding's base table shares SQLite's table/view
+            // namespace and would fail `CREATE VIEW` at boot. (Its own base table is already rejected above as
+            // "view cannot shadow its table"; here we catch collisions with a DIFFERENT binding's base table.)
+            const tableOwner = baseTableOwners.get(folded);
+            if (tableOwner !== undefined && tableOwner !== i) {
+                issues.push({
+                    path: `instanceTracking[${i}].readModel.view`,
+                    message: `managed VIEW name "${view}" collides with the base table of instanceTracking[${tableOwner}] (SQLite shares one table/view namespace); give this binding a distinct readModel.view`,
+                });
+            }
         });
     }
     return issues;

package/dist/runtime/index.d.ts

@@ -5,7 +5,7 @@ export type { DispatchMode, Disposer, EmitChannel, ErrorSink, EventBusOptions, L
 export { URBAN_EVENT_MODES, createUrbanEvents, mountExtensions, urbanEventMode } from "./core/extensions.ts";
 export type { DispatchRequest, DispatchResponse, ExtensionHost, ExtensionRegistered, ExtensionSetupContext, GateDecision, GateRequest, LifecycleEvent, MountExtensionsOptions, ReconcileEvent, UrbanEventName, UrbanEvents, UrbanExtension, } from "./core/extensions.ts";
 export { bindModeToHost, expandEnv, expandEnvString, isBindMode, loadManifest, parseManifest, resolveBindHost, resolveBindMode, workerJobType, ALL_INTERFACES_HOST, BIND_ENV_VAR, LOOPBACK_HOST, } from "./core/manifest.ts";
-export type { ActionDecl, AppManifest, BindMode, ChatSurface, DataSource, DomainField, DomainType, LlmBinding, NetworkConfig, PagesSurface, Surfaces, TaskInboxSurface, Trigger, Worker, } from "./core/manifest.ts";
+export type { ActionDecl, AppManifest, BindMode, ChatSurface, DataSource, DomainField, DomainType, InstanceTracking, LlmBinding, NetworkConfig, PagesSurface, Surfaces, TaskInboxSurface, Trigger, Worker, } from "./core/manifest.ts";
 export { collectManifestIssues, ManifestValidationError, validateManifest, } from "./core/validate.ts";
 export type { ValidationIssue } from "./core/validate.ts";
 export type { EngineClient, EngineJob, FormSchema, HostContext, HttpHandler, HttpRequest, HttpResponse, HttpServer, JobHandler, ProcessInstanceSnapshot, ProcessInstanceState, SqliteDb, UserTaskState, UserTaskSummary, UserTaskFilter, WatchHandle, WorkerSubscription, } from "./core/host.ts";
@@ -47,6 +47,7 @@ export { OPEN_USER_TASKS_PROJECTION, OPEN_USER_TASKS_SCHEMA_SQL, OPEN_USER_TASKS
 export type { OpenUserTaskRow, OpenUserTasksStoreOptions, } from "./core/modules/open-user-tasks-store.ts";
 export { INSTANCE_STATE_PROJECTION, INSTANCE_STATE_SCHEMA_SQL, INSTANCE_STATE_TABLE, InstanceStateStore, } from "./core/modules/instance-state-store.ts";
 export type { InstanceStateRow, InstanceStateStoreOptions, } from "./core/modules/instance-state-store.ts";
+export { DEFAULT_DERIVED_STATUS_COLUMN, defaultInstanceTrackingViewName, defineInstanceTrackingReadModel, deriveInstanceStatusExpr, instanceTrackingReadModelTarget, TERMINATED_STATE, terminatedEdgeExpr, waitingHumanEdgeExpr, } from "./core/modules/instance-status-read-model.ts";
 export { buildScopeIndex, derivePhase, deriveInstancePhases, furthestReached, rollupLineagePhase, SCOPE_CONTAINERS, } from "./core/phase.ts";
 export type { CrumbKind, CrumbSource, DerivePhaseOptions, FurthestReached, InstancePhase, LineagePhaseRollup, Phase, PhaseCrumb, PhaseGranularity, ProvenanceProgressRow, ScopeElement, ScopeIndex, } from "./core/phase.ts";
 export { deployModels, RESOURCES_DIR } from "./core/modules/deploy.ts";

package/dist/runtime/index.js

@@ -61,6 +61,11 @@ export { and, assertReadModelParity, assertSqlIdentifier, caseWhen, col, compile
 export { CANONICAL_PROJECTIONS, registerCanonicalProjections, } from "./core/modules/canonical-projections.js";
 export { OPEN_USER_TASKS_PROJECTION, OPEN_USER_TASKS_SCHEMA_SQL, OPEN_USER_TASKS_TABLE, OpenUserTasksStore, } from "./core/modules/open-user-tasks-store.js";
 export { INSTANCE_STATE_PROJECTION, INSTANCE_STATE_SCHEMA_SQL, INSTANCE_STATE_TABLE, InstanceStateStore, } from "./core/modules/instance-state-store.js";
+// The DERIVED half of the instanceTracking writer→source inversion (ADR 0065, #439-L1 / #318): the
+// builder that declares a binding's effective-status read model — the terminal + wait-on-human edges —
+// as ONE `defineReadModel` derivation over the canonical projections, compiled to both the managed
+// SQLite VIEW and the TS function. The reconciler feeds the projections; this derives the status edge.
+export { DEFAULT_DERIVED_STATUS_COLUMN, defaultInstanceTrackingViewName, defineInstanceTrackingReadModel, deriveInstanceStatusExpr, instanceTrackingReadModelTarget, TERMINATED_STATE, terminatedEdgeExpr, waitingHumanEdgeExpr, } from "./core/modules/instance-status-read-model.js";
 // instance in?" from the BPMN scope hierarchy + write-provenance (Tier 0, zero declaration), an
 // optional `nano:phase` override (Tier 1), and a lineage rollup for the epic frontier (Tier 2).
 export { buildScopeIndex, derivePhase, deriveInstancePhases, furthestReached, rollupLineagePhase, SCOPE_CONTAINERS, } from "./core/phase.js";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.80.0",
+	"version": "0.81.0",
 	"description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
 	"license": "Apache-2.0",
 	"type": "module",

package/src/runtime/core/manifest.ts

@@ -55,25 +55,58 @@ 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;
+  };
 };
 
 /**