@nanobpm/urban 0.79.0 → 0.81.0

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

@@ -6,8 +6,9 @@
 // base/api/complete`). A task with no linked form keeps the bare key-list + raw-complete
 // behavior. The `chat` surface is stubbed as a mount point (LLM wiring is a separate concern).
 // Surfaces contribute routes to the shared server.
-import { presentFormIdentifier } from "../host.js";
-import { html, json, noContent, normalizeRoutePath } from "../router.js";
+import { html, json, normalizeRoutePath } from "../router.js";
+import { FORMJS_JS } from "./formjs.gen.js";
+import { completeUserTaskResponse, resolveFormResponse } from "./forms.js";
 import { mountActions } from "./actions.js";
 import { mountAgent } from "./agent.js";
 import { mountApi } from "./api.js";
@@ -30,13 +31,15 @@ function inboxPage() {
 ul{list-style:none;padding:0}li{margin:.4rem 0;display:flex;align-items:center;gap:.5rem}
 code{background:#f4f4f4;padding:.1rem .3rem;border-radius:3px}
 button{font:inherit;padding:.2rem .6rem;cursor:pointer}
-form label{display:block;margin:.6rem 0 .2rem;font-weight:600}
-form .field input,form .field textarea,form .field select{font:inherit;padding:.3rem;width:100%;box-sizing:border-box;max-width:24rem}
-form .field input[type=checkbox],form .field input[type=radio]{width:auto}
+.njf-field label{display:block;margin:.6rem 0 .2rem;font-weight:600}
+.njf-field input,.njf-field textarea,.njf-field select{font:inherit;padding:.3rem;width:100%;box-sizing:border-box;max-width:24rem}
+.njf-field input[type=checkbox],.njf-field input[type=radio]{width:auto}
+.njf-actions{margin-top:.6rem}
 #form{margin-top:1.5rem;border-top:1px solid #ddd;padding-top:1rem}
 .muted{color:#666}</style>
 <h1>Task inbox</h1><ul id="tasks"><li>loading…</li></ul>
 <div id="form"></div>
+<script>${FORMJS_JS}</script>
 <script>
 const BASE=location.pathname.replace(/[/]+$/,'');
 const tasksEl=document.getElementById('tasks');
@@ -71,7 +74,14 @@ function openForm(t){
   api('/api/form?'+q).then(f=>{
     formEl.replaceChildren();
     if(!f||!f.schema){renderNoForm(t);return;}
-    renderForm(t,f.schema);
+    // Reuse the ONE shared form-js renderer (NanoFormJs) — no fork with the pages surface.
+    formEl.appendChild(NanoFormJs.renderForm(f.schema,{
+      heading:'Task '+(t.elementId||t.userTaskKey),
+      submitLabel:'Submit',
+      cancelLabel:'Cancel',
+      onSubmit:(variables)=>complete(t.userTaskKey,variables),
+      onCancel:loadTasks,
+    }));
   }).catch(err=>{formEl.replaceChildren(el('p',{class:'muted'},'Failed to load form: '+err.message));});
 }
 
@@ -83,93 +93,6 @@ function renderNoForm(t){
   formEl.appendChild(bar);
 }
 
-function renderForm(t,schema){
-  const form=document.createElement('form');
-  form.appendChild(el('h2',{},'Task '+(t.elementId||t.userTaskKey)));
-  const components=Array.isArray(schema.components)?schema.components:[];
-  const inputs=[];
-  for(const c of components){
-    const built=buildField(c);
-    if(!built)continue;
-    form.appendChild(built.field);
-    if(built.read)inputs.push(built.read);
-  }
-  const submit=btn('Submit',null);submit.type='submit';
-  const bar=el('div',{});bar.appendChild(submit);bar.appendChild(btn('Cancel',loadTasks));
-  form.appendChild(bar);
-  form.addEventListener('submit',e=>{
-    e.preventDefault();
-    // Null-prototype: field keys come from the engine-supplied form schema. A component
-    // keyed '__proto__'/'constructor' must land as a plain own property (and round-trip
-    // through JSON), never mutate a prototype — no prototype pollution in the page runtime.
-    const variables=Object.create(null);
-    for(const read of inputs){const kv=read();if(kv)variables[kv.key]=kv.value;}
-    submit.disabled=true;
-    complete(t.userTaskKey,variables).catch(()=>{submit.disabled=false;});
-  });
-  formEl.appendChild(form);
-}
-
-function buildField(c){
-  const type=c&&c.type;
-  // Static (keyless) components: show text as a paragraph, ignore layout-only ones.
-  if(type==='text'){return {field:el('p',{class:'muted'},typeof c.text==='string'?c.text:'')};}
-  const key=c&&c.key;
-  if(!key)return null;
-  const wrap=el('div',{class:'field'});
-  const label=typeof c.label==='string'&&c.label?c.label:key;
-  if(type==='checkbox'){
-    const input=document.createElement('input');input.type='checkbox';
-    const lab=el('label',{});lab.appendChild(input);lab.appendChild(document.createTextNode(' '+label));
-    wrap.appendChild(lab);
-    return {field:wrap,read:()=>({key,value:input.checked})};
-  }
-  const labelEl=el('label',{},label);
-  wrap.appendChild(labelEl);
-  let input;
-  if(type==='textarea'){input=document.createElement('textarea');}
-  else if(type==='select'){
-    input=document.createElement('select');
-    input.appendChild(el('option',{value:''},'—'));
-    for(const o of (Array.isArray(c.values)?c.values:[])){
-      input.appendChild(el('option',{value:String(o.value)},String(o.label!=null?o.label:o.value)));
-    }
-  }
-  else if(type==='radio'){
-    const name='r'+Math.random().toString(36).slice(2);
-    const group=el('div',{});
-    for(const o of (Array.isArray(c.values)?c.values:[])){
-      const rlab=el('label',{});
-      const r=document.createElement('input');r.type='radio';r.name=name;r.value=String(o.value);
-      rlab.appendChild(r);rlab.appendChild(document.createTextNode(' '+String(o.label!=null?o.label:o.value)));
-      group.appendChild(rlab);
-    }
-    wrap.appendChild(group);
-    return {field:wrap,read:()=>{const sel=group.querySelector('input:checked');return sel?{key,value:sel.value}:null;}};
-  }
-  else{
-    input=document.createElement('input');
-    input.type=(type==='number')?'number':(type==='datetime'?'datetime-local':'text');
-  }
-  // Associate the label with the input (for/id) so screen readers announce it on focus.
-  const fieldId='f'+Math.random().toString(36).slice(2);
-  input.id=fieldId;labelEl.setAttribute('for',fieldId);
-  wrap.appendChild(input);
-  const isNumber=type==='number';
-  return {field:wrap,read:()=>{
-    const raw=input.value;
-    if(raw===''||raw==null)return null;
-    if(isNumber){
-      const n=Number(raw);
-      // A non-numeric value in a number field is only reachable via tampering (the browser
-      // blanks invalid type=number input). Treat it as absent rather than silently submitting
-      // NaN, which JSON.stringify serializes as null — quietly changing the submitted value.
-      return Number.isFinite(n)?{key,value:n}:null;
-    }
-    return {key,value:raw};
-  }};
-}
-
 function complete(userTaskKey,variables){
   return api('/api/complete',{method:'POST',headers:{'content-type':'application/json'},
     body:JSON.stringify({userTaskKey,variables})}).then(loadTasks);
@@ -222,42 +145,13 @@ export function mountSurfaces(ctx, app) {
             method: "GET",
             path: `${base}/api/form`,
             source: "surface:taskInbox",
-            handler: async (req) => {
-                const formKey = req.query.get("formKey") ?? undefined;
-                const formId = req.query.get("formId") ?? undefined;
-                // Reject only when *neither* identifier is present. Presence follows getForm's
-                // canonical rule (`presentFormIdentifier`: empty/whitespace = absent) so a
-                // whitespace-only `?formKey=   ` request 400s here instead of slipping past a raw
-                // truthiness check and returning a spurious 204. The raw values are still passed
-                // through unchanged — resolving a blank key to its `formId` fallback is getForm's
-                // single responsibility.
-                if (!presentFormIdentifier(formKey) && !presentFormIdentifier(formId))
-                    return json({ error: "formKey or formId required" }, 400);
-                const form = await app.engine.getForm({ formKey, formId });
-                // A task whose form can't be resolved returns 204: the client renders the
-                // no-form fallback rather than erroring.
-                if (!form)
-                    return noContent();
-                return json(form);
-            },
+            handler: async (req) => resolveFormResponse(app.engine, req.query.get("formKey") ?? undefined, req.query.get("formId") ?? undefined),
         });
         routes.push({
             method: "POST",
             path: `${base}/api/complete`,
             source: "surface:taskInbox",
-            handler: async (req) => {
-                let body;
-                try {
-                    body = JSON.parse((await req.text()) || "{}");
-                }
-                catch {
-                    return json({ error: "invalid JSON body" }, 400);
-                }
-                if (!body.userTaskKey)
-                    return json({ error: "userTaskKey required" }, 400);
-                await app.engine.completeUserTask(body.userTaskKey, body.variables);
-                return json({ ok: true });
-            },
+            handler: async (req) => completeUserTaskResponse(app.engine, await req.text()),
         });
     }
     const chat = surfaces.chat;

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.79.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",