@nanobpm/urban 0.80.0 → 0.82.0

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";
@@ -40,13 +40,14 @@ export { applyAmbientLineage, buildLineageTree, deriveLineage, LINEAGE_KEY, LINE
 export type { ApplyLineageOptions, LineageAttachment, LineageEdge, LineageEdgeType, LineageEnvelope, LineageNode, LineageTree, } from "./core/lineage.ts";
 export { LINEAGE_ATTACHMENTS_TABLE, LINEAGE_EDGES_TABLE, LINEAGE_SCHEMA_SQL, LineageStore, systemClock as lineageSystemClock, } from "./core/modules/lineage-store.ts";
 export type { Clock as LineageClock, LineageJobLike, LineageStoreOptions, } from "./core/modules/lineage-store.ts";
-export { and, assertReadModelParity, assertSqlIdentifier, caseWhen, col, compileToFn, compileToSqlSelect, defineReadModel, deriveReadModelViewDdl, eq, exists, gt, gte, lit, lt, lte, neq, not, or, pcol, ProjectionRegistry, projectionRegistry, ReadModelRegistry, readModelRegistry, when, } from "./core/read-model.ts";
-export type { AndExpr, BaseRow, CaseExpr, ColExpr, CompareExpr, CompareOp, DerivationFn, ExistsExpr, Expr, Literal, LitExpr, NotExpr, OrExpr, ParityDb, ParityOptions, ParitySample, ProjColExpr, ProjectionRows, ProjectionSource, ReadModel, ReadModelDecl, SqlCompileOptions, WhenClause, } from "./core/read-model.ts";
+export { add, and, assertReadModelParity, assertRollupParity, assertSqlIdentifier, caseWhen, coalesce, col, compileToFn, compileToSqlSelect, count, countWhere, defineReadModel, defineRollup, deriveReadModelViewDdl, eq, exists, fromProjection, fromRollup, fromTable, gt, gte, isNotNull, isNull, joinSource, lit, lt, lte, max, minWhere, neq, not, or, pcol, ProjectionRegistry, projectionRegistry, rcol, ReadModelRegistry, readModelRegistry, RollupRegistry, rollupRegistry, when, } from "./core/read-model.ts";
+export type { AddAgg, AggExpr, AndExpr, BaseRow, CaseExpr, ColExpr, CoalesceAgg, CompareExpr, CompareOp, CountAgg, CountWhereAgg, DerivationFn, ExistsExpr, Expr, IsNullExpr, Literal, LitExpr, LookupRows, MaxAgg, MinWhereAgg, NotExpr, OrExpr, ParityDb, ParityOptions, ParitySample, ProjColExpr, ProjectionRows, ProjectionSource, ReadModel, ReadModelDecl, RollupColExpr, Rollup, RollupDecl, RollupInputs, RollupJoinSource, RollupLookupDecl, RollupParityOptions, RollupProjectionSource, RollupRelation, RollupRollupSource, RollupSource, RollupTableSource, SqlCompileOptions, WhenClause, } from "./core/read-model.ts";
 export { CANONICAL_PROJECTIONS, registerCanonicalProjections, } from "./core/modules/canonical-projections.ts";
 export { OPEN_USER_TASKS_PROJECTION, OPEN_USER_TASKS_SCHEMA_SQL, OPEN_USER_TASKS_TABLE, OpenUserTasksStore, } from "./core/modules/open-user-tasks-store.ts";
 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

@@ -52,7 +52,12 @@ export { LINEAGE_ATTACHMENTS_TABLE, LINEAGE_EDGES_TABLE, LINEAGE_SCHEMA_SQL, Lin
 //     workers.ts) applies its managed VIEW. The `writer-source-inversion` task registers here.
 //   • `projectionRegistry` — register a canonical engine-truth projection NAME usable in `exists(...)`.
 //     The `canonical-projections` task registers `urban_open_user_tasks` / `urban_instance_state`.
-export { and, assertReadModelParity, assertSqlIdentifier, caseWhen, col, compileToFn, compileToSqlSelect, defineReadModel, deriveReadModelViewDdl, eq, exists, gt, gte, lit, lt, lte, neq, not, or, pcol, ProjectionRegistry, projectionRegistry, ReadModelRegistry, readModelRegistry, when, } from "./core/read-model.js";
+// The GROUP-BY sibling `defineRollup` (ADR 0065, #468): a declare-once aggregate rollup compiled to
+// BOTH a managed `*_counts` VIEW and a TS group-reduce (closed aggregate op set: `count`/`countWhere`/
+// `max`/`minWhere`/`coalesce`/`add`), registered as a canonical projection via `rollupRegistry` and
+// parity-guarded by `assertRollupParity`. `defineReadModel` gains a key-correlated rollup lookup
+// (`ReadModelDecl.lookups` + `rcol`) so per-row derivations read a rollup's columns for the base row.
+export { add, and, assertReadModelParity, assertRollupParity, assertSqlIdentifier, caseWhen, coalesce, col, compileToFn, compileToSqlSelect, count, countWhere, defineReadModel, defineRollup, deriveReadModelViewDdl, eq, exists, fromProjection, fromRollup, fromTable, gt, gte, isNotNull, isNull, joinSource, lit, lt, lte, max, minWhere, neq, not, or, pcol, ProjectionRegistry, projectionRegistry, rcol, ReadModelRegistry, readModelRegistry, RollupRegistry, rollupRegistry, when, } from "./core/read-model.js";
 // Canonical engine-truth projection sidecars (ADR 0065, proposal point #1): two framework-owned,
 // per-source projections the DSL `exists(...)` derives over — `urban_open_user_tasks` (which instances
 // are parked on a human) and `urban_instance_state` (per-instance engine lifecycle state). Provisioned
@@ -61,6 +66,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.82.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;
+  };
 };
 
 /**