@nanobpm/urban 0.27.0 → 0.29.0

package/dist/runtime/adapters/deno.js

@@ -13,6 +13,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 import { isAbsolute, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { DatabaseSync } from "node:sqlite";
+import { AsyncLocalStorage } from "node:async_hooks";
 function sqliteParams(params) {
     return params.map((param) => {
         if (param === null ||
@@ -103,6 +104,10 @@ export function createDenoHost(opts = {}) {
             };
         },
         now: () => Date.now(),
+        createAsyncStore() {
+            const als = new AsyncLocalStorage();
+            return { run: (value, fn) => als.run(value, fn), current: () => als.getStore() };
+        },
         log,
     };
 }

package/dist/runtime/adapters/node.js

@@ -16,6 +16,7 @@ import { register } from "node:module";
 import { isAbsolute, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { DatabaseSync } from "node:sqlite";
+import { AsyncLocalStorage } from "node:async_hooks";
 function sqliteParams(params) {
     return params.map((param) => {
         if (param === null ||
@@ -154,6 +155,10 @@ export function createNodeHost(opts = {}) {
             return { close: () => w.close() };
         },
         now: () => Date.now(),
+        createAsyncStore() {
+            const als = new AsyncLocalStorage();
+            return { run: (value, fn) => als.run(value, fn), current: () => als.getStore() };
+        },
         log,
     };
 }

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

@@ -0,0 +1,28 @@
+import type { AsyncStore } from "./host.ts";
+/** The ambient context of the job currently executing on a worker. All fields are optional so a
+ *  job dispatched without an instance/element still runs; provenance is only recorded when an
+ *  `instanceKey` is present. */
+export interface JobExecContext {
+    /** The process instance that dispatched the running job. */
+    instanceKey?: string;
+    /** The BPMN element (e.g. service task) the job is for. */
+    elementId?: string;
+    /** The job type (worker) currently executing. */
+    jobType?: string;
+}
+/**
+ * Install the host-backed ambient store once per process. Idempotent — the first store created
+ * wins: every Node/Deno store is an equivalent `AsyncLocalStorage` instance, and a process that
+ * hosts several apps shares one async store safely (values are keyed by async execution context,
+ * not by app). A `factory` that returns undefined (a host without the capability) leaves capture
+ * disabled, but a later capable host may still install the process store.
+ */
+export declare function installExecStore(factory: () => AsyncStore<JobExecContext> | undefined): void;
+/** Run `fn` with `ctx` as the ambient job context. A transparent pass-through when no store is
+ *  installed (returns `fn()` directly). */
+export declare function runInJobContext<R>(ctx: JobExecContext, fn: () => R): R;
+/** The ambient job context of the current async execution, or undefined outside a job (or when
+ *  no store is installed). */
+export declare function currentJobContext(): JobExecContext | undefined;
+/** Test seam: drop the installed store so a subsequent {@link installExecStore} re-installs. */
+export declare function __resetExecStoreForTests(): void;

package/dist/runtime/core/execContext.js

@@ -0,0 +1,39 @@
+// Ambient job execution context — threads the active job's process instance / element through
+// to DataLayer writes so write-provenance capture (ProcessOS domain-signal plane, D0) can join
+// written rows back to the instance/element that wrote them, WITHOUT plumbing the job through
+// every call. Entirely domain-free: it knows nothing about any app's tables or their meaning.
+//
+// The async primitive (`AsyncLocalStorage`) is a host capability (`node:async_hooks`), so it is
+// injected through the `HostContext` seam; core stays `node:*`-free per the host contract. When
+// no store is installed — a host that doesn't provide one, or a plain unit test — `run()` just
+// calls `fn` and `current()` returns undefined, so capture degrades to a no-op. Absent-safe and
+// zero-cost when off, by construction.
+let store;
+/**
+ * Install the host-backed ambient store once per process. Idempotent — the first store created
+ * wins: every Node/Deno store is an equivalent `AsyncLocalStorage` instance, and a process that
+ * hosts several apps shares one async store safely (values are keyed by async execution context,
+ * not by app). A `factory` that returns undefined (a host without the capability) leaves capture
+ * disabled, but a later capable host may still install the process store.
+ */
+export function installExecStore(factory) {
+    if (store)
+        return;
+    const next = factory();
+    if (next)
+        store = next;
+}
+/** Run `fn` with `ctx` as the ambient job context. A transparent pass-through when no store is
+ *  installed (returns `fn()` directly). */
+export function runInJobContext(ctx, fn) {
+    return store ? store.run(ctx, fn) : fn();
+}
+/** The ambient job context of the current async execution, or undefined outside a job (or when
+ *  no store is installed). */
+export function currentJobContext() {
+    return store?.current();
+}
+/** Test seam: drop the installed store so a subsequent {@link installExecStore} re-installs. */
+export function __resetExecStoreForTests() {
+    store = undefined;
+}

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

@@ -25,6 +25,16 @@ export interface HttpServer {
 export interface WatchHandle {
     close(): void;
 }
+/** A minimal ambient async-scoped store — the subset of `AsyncLocalStorage` the runtime needs
+ *  to thread a job's execution context to DataLayer writes for write-provenance capture. Backed
+ *  by `node:async_hooks` in both the Node and Deno adapters (both provide it); core depends only
+ *  on this interface, never on `node:*`. */
+export interface AsyncStore<T> {
+    /** Run `fn` with `value` as the current store value, restoring the prior value afterwards. */
+    run<R>(value: T, fn: () => R): R;
+    /** The current store value, or undefined outside any `run`. */
+    current(): T | undefined;
+}
 /** A tiny synchronous SQLite handle — the subset the runtime needs. */
 export interface SqliteDb {
     /** Execute one or more statements with no result (DDL, PRAGMA, migrations). */
@@ -81,6 +91,12 @@ export interface HostContext {
     watch?(onChange: (path: string) => void): WatchHandle;
     /** Current wall-clock time in ms since epoch (seam for tests). */
     now(): number;
+    /**
+     * Create an ambient async-scoped store (backed by `AsyncLocalStorage`). Used to thread the
+     * active job's execution context to DataLayer writes for write-provenance capture. Optional:
+     * a host that cannot provide one leaves provenance capture disabled (absent-safe).
+     */
+    createAsyncStore?<T>(): AsyncStore<T>;
     /** Structured log sink. */
     log(level: "info" | "warn" | "error", msg: string, fields?: Record<string, unknown>): void;
 }
@@ -122,6 +138,19 @@ export interface WorkerSubscription {
     readonly jobType: string;
     unsubscribe(): Promise<void>;
 }
+/**
+ * A process instance's terminal-relevant lifecycle state, as the engine reports it.
+ * `ACTIVE` (still running), `COMPLETED` (ended normally at an end event), or
+ * `TERMINATED` (cancelled/terminated — via a row-cancel, an operator, or a crash).
+ * Deliberately the small set the instance-tracking reconciler keys on, not the richer
+ * element-instance state set (which adds SKIPPED/CANCELED/FAILED for tokens).
+ */
+export type ProcessInstanceState = "ACTIVE" | "COMPLETED" | "TERMINATED";
+/** A single process instance's lifecycle snapshot returned by {@link EngineClient.searchProcessInstances}. */
+export interface ProcessInstanceSnapshot {
+    readonly processInstanceKey: string;
+    readonly state: ProcessInstanceState;
+}
 /**
  * EngineClient is the seam onto a Nano engine. The SDK/REST-backed adapter implements
  * it against a live engine; tests implement it in-memory. Core modules depend only on this.
@@ -166,6 +195,18 @@ export interface EngineClient {
     }[]>;
     /** Complete a user task. */
     completeUserTask(userTaskKey: string, variables?: Record<string, unknown>): Promise<void>;
+    /**
+     * Search process instances by key and/or lifecycle state. The instance-tracking
+     * reconciler uses this to detect a tracked instance reaching a terminal state
+     * (`TERMINATED`/`COMPLETED`) even though no completion worker ran for it — the
+     * read-model row it backs would otherwise stay "active" forever. An eventually
+     * consistent read (zero-wait); pass the keys currently marked active in the
+     * read model and, optionally, a `state` to narrow the result.
+     */
+    searchProcessInstances(filter?: {
+        processInstanceKeys?: string[];
+        state?: ProcessInstanceState;
+    }): Promise<ProcessInstanceSnapshot[]>;
     /** Register a push worker for a job type. Draining is handled by the adapter. */
     registerWorker(jobType: string, handler: JobHandler, options?: {
         workerName?: string;

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

@@ -1,6 +1,6 @@
 import type { HostContext } from "./host.ts";
 import type { AppManifest, Worker } from "@nanobpm/nano-app-schema";
-export type { ActionDecl, AppManifest, AppUi, ChatSurface, Connection, Data, DataSource, DomainField, DomainType, LlmBinding, Models, PagesSurface, Runtime, Security, Surfaces, TaskInboxSurface, Trigger, TriggerAction, Worker, } from "@nanobpm/nano-app-schema";
+export type { ActionDecl, AppManifest, AppUi, ChatSurface, Connection, Data, DataSource, DomainField, DomainType, InstanceTracking, LlmBinding, Models, PagesSurface, Runtime, Security, Surfaces, TaskInboxSurface, Trigger, TriggerAction, Worker, } from "@nanobpm/nano-app-schema";
 /** The job type a worker subscribes to (schema key: `taskType`). */
 export declare function workerJobType(w: Worker): string | undefined;
 /**

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

@@ -18,6 +18,7 @@ import { errorMessage, isRecord } from "../guards.js";
 import { BpmnError } from "../host.js";
 import { workerJobType } from "../manifest.js";
 import { drainDefinedWorkers, } from "../../connector-worker-sdk.js";
+import { runInJobContext } from "../execContext.js";
 function joinRoot(root, p) {
     return p.startsWith("/") ? p : `${root.replace(/\/+$/, "")}/${p.replace(/^\/+/, "")}`;
 }
@@ -181,7 +182,8 @@ export async function mountConnectors(ctx, app) {
             throw new Error(`connector pack "${packId}" entry "${spec.entry}" did not register a worker for ` +
                 `"${jobType}" (its defineWorker call declares a different type).`);
         }
-        const wrapped = adaptConnectorHandler(worker);
+        const inner = adaptConnectorHandler(worker);
+        const wrapped = (job) => runInJobContext({ instanceKey: job.processInstanceKey, elementId: job.elementId, jobType }, () => inner(job));
         const sub = await ctx.engine.registerWorker(jobType, wrapped, {
             workerName: `${ctx.manifest.id}:${jobType}`,
             // The pack's `defineWorker({ maxParallelJobs })` is the authoritative runtime

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

@@ -1,7 +1,7 @@
 import type { RuntimeContext } from "../context.ts";
 import type { HostContext, SqliteDb } from "../host.ts";
 import type { DomainType } from "../manifest.ts";
-import { Table, type DataSource as GatewayDataSource } from "./gateway.ts";
+import { Table, type DataSource as GatewayDataSource, type InsertObserver } from "./gateway.ts";
 export declare function sqlitePathFromUrl(url: string): string;
 /** True when `p` is already an absolute path on any host `urban data` targets. `urban data` runs
  * on a Node host that may be Windows, so absolute-path detection can't assume POSIX: this matches
@@ -29,6 +29,23 @@ export declare function resolveAppPath(root: string, p: string): string;
  * for this identifier: `applyMigrations` writes it and `dataops`' `migrations` op reads it, so
  * both import this constant and the ledger name can never drift between application and listing. */
 export declare const MIGRATIONS_TABLE = "_urban_migrations";
+/** Name of the urban-owned write-provenance sidecar table (ProcessOS domain-signal plane, D0).
+ *  One append per app `Table.insert` performed inside a job, linking the written row —
+ *  `(source, table_name, pk_value)` — to the process instance/element that wrote it. Follows the
+ *  `_urban_` convention so it is automatically excluded from domain-model introspection,
+ *  DB Manager, and forms (see `gateway.ts` `schema()`), and never collides with an app table. */
+export declare const WRITE_PROVENANCE_TABLE = "_urban_write_provenance";
+/** Provision the write-provenance sidecar on a source (idempotent). Domain-free: it records only
+ *  the join key + timestamps, never any row content. */
+export declare function ensureProvenanceTable(db: SqliteDb): void;
+/** Build the {@link InsertObserver} that captures write-provenance for one source. Best-effort:
+ *  it records a row only when a job execution context with an instance key is active (a worker
+ *  handler is running) — writes outside a job (e.g. HTTP actions) record nothing, degrading
+ *  gracefully. It skips urban/engine-internal tables so the provenance table never records
+ *  itself. It runs on the same connection as the insert, so inside a `tx` the provenance row is
+ *  committed/rolled back atomically with the app write. `Table.insert` wraps this defensively, so
+ *  a throw here can never break the app insert. */
+export declare function makeProvenanceRecorder(host: HostContext, db: SqliteDb, source: string): InsertObserver;
 /** Resolve a datasource `url` to its on-disk SQLite path against `root`. The result is absolute
  * when the resolved path is absolute (either because `url` names an absolute path or `root` is
  * absolute); if `root` is relative (e.g. "." as used by the CLI/tests) a relative `url` stays

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

@@ -2,7 +2,8 @@
 // `types` domain model. Only the `sqlite` driver is implemented; other drivers hit an
 // explicit seam (they are declared in the manifest but not yet provisioned). This is the
 // runtime side of ADR 0024 (datasource) + ADR 0040 (domain model), scoped to what an app needs.
-import { makeGateway } from "./gateway.js";
+import { makeGateway, } from "./gateway.js";
+import { currentJobContext } from "../execContext.js";
 export function sqlitePathFromUrl(url) {
     // Accept "file:./x.db", "file:x.db", "sqlite:./x.db" or a bare path.
     return url.replace(/^(file|sqlite):(\/\/)?/, "");
@@ -43,6 +44,54 @@ export function resolveAppPath(root, p) {
  * for this identifier: `applyMigrations` writes it and `dataops`' `migrations` op reads it, so
  * both import this constant and the ledger name can never drift between application and listing. */
 export const MIGRATIONS_TABLE = "_urban_migrations";
+/** Name of the urban-owned write-provenance sidecar table (ProcessOS domain-signal plane, D0).
+ *  One append per app `Table.insert` performed inside a job, linking the written row —
+ *  `(source, table_name, pk_value)` — to the process instance/element that wrote it. Follows the
+ *  `_urban_` convention so it is automatically excluded from domain-model introspection,
+ *  DB Manager, and forms (see `gateway.ts` `schema()`), and never collides with an app table. */
+export const WRITE_PROVENANCE_TABLE = "_urban_write_provenance";
+/** Provision the write-provenance sidecar on a source (idempotent). Domain-free: it records only
+ *  the join key + timestamps, never any row content. */
+export function ensureProvenanceTable(db) {
+    db.exec(`CREATE TABLE IF NOT EXISTS ${WRITE_PROVENANCE_TABLE} (` +
+        "seq INTEGER PRIMARY KEY AUTOINCREMENT, " +
+        "source TEXT NOT NULL, " +
+        "table_name TEXT NOT NULL, " +
+        "pk_value TEXT NOT NULL, " +
+        "instance_key TEXT, " +
+        "element_id TEXT, " +
+        "job_type TEXT, " +
+        "op TEXT NOT NULL DEFAULT 'insert', " +
+        "at TEXT NOT NULL)");
+}
+/** Build the {@link InsertObserver} that captures write-provenance for one source. Best-effort:
+ *  it records a row only when a job execution context with an instance key is active (a worker
+ *  handler is running) — writes outside a job (e.g. HTTP actions) record nothing, degrading
+ *  gracefully. It skips urban/engine-internal tables so the provenance table never records
+ *  itself. It runs on the same connection as the insert, so inside a `tx` the provenance row is
+ *  committed/rolled back atomically with the app write. `Table.insert` wraps this defensively, so
+ *  a throw here can never break the app insert. */
+export function makeProvenanceRecorder(host, db, source) {
+    return (table, pk) => {
+        if (table.startsWith("_urban_") || table.startsWith("_nano_") || table.startsWith("sqlite_")) {
+            return;
+        }
+        const ctx = currentJobContext();
+        if (!ctx || ctx.instanceKey == null)
+            return;
+        db.run(`INSERT INTO ${WRITE_PROVENANCE_TABLE} ` +
+            "(source, table_name, pk_value, instance_key, element_id, job_type, op, at) " +
+            "VALUES (?, ?, ?, ?, ?, ?, 'insert', ?)", [
+            source,
+            table,
+            String(pk),
+            ctx.instanceKey,
+            ctx.elementId ?? null,
+            ctx.jobType ?? null,
+            new Date(host.now()).toISOString(),
+        ]);
+    };
+}
 /** Resolve a datasource `url` to its on-disk SQLite path against `root`. The result is absolute
  * when the resolved path is absolute (either because `url` names an absolute path or `root` is
  * absolute); if `root` is relative (e.g. "." as used by the CLI/tests) a relative `url` stays
@@ -256,6 +305,11 @@ async function provisionSqlite(ctx, name, src) {
     const migrationsApplied = src.migrations
         ? await applyMigrations(ctx.host, db, ctx.root, src.migrations)
         : [];
+    // Provision the write-provenance sidecar and wire the gateway's insert observer to it, so
+    // every app `Table.insert` performed inside a job is linked to its process instance/element
+    // (ProcessOS domain-signal capture, D0). Domain-free and non-invasive — the sidecar lives
+    // outside the domain model.
+    ensureProvenanceTable(db);
     ctx.host.log("info", `datasource: provisioned "${name}"`, {
         driver: "sqlite",
         path: resolveSqlitePath(ctx.root, src.url),
@@ -265,7 +319,7 @@ async function provisionSqlite(ctx, name, src) {
         name,
         driver: "sqlite",
         db,
-        source: makeGateway(db),
+        source: makeGateway(db, makeProvenanceRecorder(ctx.host, db, name)),
         migrationsApplied,
         close: () => db.close(),
     };

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

@@ -1,5 +1,10 @@
 import type { SqliteDb } from "../host.ts";
 export type Row = Record<string, unknown>;
+/** Best-effort observer invoked after a successful {@link Table.insert}, with the table name and
+ *  the new primary-key value. The DataLayer uses it to capture write-provenance. It MUST NOT
+ *  throw — an app insert must never fail because provenance capture did — but {@link Table.insert}
+ *  also wraps it defensively. */
+export type InsertObserver = (table: string, pk: number | bigint) => void;
 export interface ExecResult {
     /** Rows changed by an INSERT/UPDATE/DELETE. */
     changed: number;
@@ -58,7 +63,7 @@ export declare class Table<T extends object = Row> {
     #private;
     readonly name: string;
     readonly pk: string;
-    constructor(src: DataSource, name: string, pk?: string);
+    constructor(src: DataSource, name: string, pk?: string, onInsert?: InsertObserver);
     /** Insert one row; returns the new primary-key value (the inserted rowid for an INTEGER
      * PRIMARY KEY). Keys whose value is `undefined` are omitted, so the table's own column
      * `DEFAULT`/`NULL` governs — `undefined` means "not provided, let the schema decide", never
@@ -81,5 +86,7 @@ export declare class Table<T extends object = Row> {
     /** Count rows matching an equality filter (all rows when omitted). */
     count(where?: Partial<T>): Promise<number>;
 }
-/** Wrap a provisioned `SqliteDb` as the record-oriented `DataSource` gateway. */
-export declare function makeGateway(db: SqliteDb): DataSource;
+/** Wrap a provisioned `SqliteDb` as the record-oriented `DataSource` gateway. An optional
+ *  `onInsert` observer is invoked after every successful `Table.insert` (used for
+ *  write-provenance capture); it is threaded to each `Table` this gateway creates. */
+export declare function makeGateway(db: SqliteDb, onInsert?: InsertObserver): DataSource;

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

@@ -34,10 +34,12 @@ export class Table {
     name;
     pk;
     #src;
-    constructor(src, name, pk = "id") {
+    #onInsert;
+    constructor(src, name, pk = "id", onInsert) {
         this.#src = src;
         this.name = name;
         this.pk = pk;
+        this.#onInsert = onInsert;
     }
     /** Insert one row; returns the new primary-key value (the inserted rowid for an INTEGER
      * PRIMARY KEY). Keys whose value is `undefined` are omitted, so the table's own column
@@ -59,6 +61,17 @@ export class Table {
             // silently returning 0, which a caller could mistake for a real primary key.
             throw new Error(`Table(${this.name}).insert: driver reported no lastInsertId`);
         }
+        if (this.#onInsert) {
+            // Provenance capture is strictly observational: never let it break the app insert, which
+            // executed successfully above. If this insert runs inside a transaction, commit/rollback
+            // semantics still belong to that surrounding transaction.
+            try {
+                this.#onInsert(this.name, r.lastInsertId);
+            }
+            catch {
+                // swallow — an insert must never fail because provenance capture did
+            }
+        }
         return r.lastInsertId;
     }
     /** Fetch the row with the given primary key, or `undefined`. */
@@ -111,8 +124,10 @@ export class Table {
  * are async to hold the app-facing contract; the work underneath is synchronous. */
 class SqliteGateway {
     #db;
-    constructor(db) {
+    #onInsert;
+    constructor(db, onInsert) {
         this.#db = db;
+        this.#onInsert = onInsert;
     }
     async query(sql, params = []) {
         return this.#db.all(sql, params);
@@ -167,10 +182,12 @@ class SqliteGateway {
         return out;
     }
     table(name, pk = "id") {
-        return new Table(this, name, pk);
+        return new Table(this, name, pk, this.#onInsert);
     }
 }
-/** Wrap a provisioned `SqliteDb` as the record-oriented `DataSource` gateway. */
-export function makeGateway(db) {
-    return new SqliteGateway(db);
+/** Wrap a provisioned `SqliteDb` as the record-oriented `DataSource` gateway. An optional
+ *  `onInsert` observer is invoked after every successful `Table.insert` (used for
+ *  write-provenance capture); it is threaded to each `Table` this gateway creates. */
+export function makeGateway(db, onInsert) {
+    return new SqliteGateway(db, onInsert);
 }

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

@@ -0,0 +1,14 @@
+import type { AppApi, Mounted, RuntimeContext } from "../context.ts";
+import { type SchedulerDeps } from "./scheduler.ts";
+/** Default poll interval when a binding does not set `pollMs`. */
+export declare const DEFAULT_INSTANCE_TRACKING_POLL_MS = 15000;
+export interface InstanceTrackingHandle extends Mounted {
+    /** `table.keyField` labels of the armed bindings, for `inspect()`. */
+    readonly bindings: string[];
+}
+/**
+ * Mount the `instanceTracking` reconciler: arm one poll loop per binding. Each loop selects
+ * the active rows, asks the engine which of their instances are terminated, and applies the
+ * declared patch. `stop()` cancels every armed timer.
+ */
+export declare function mountInstanceTracking(ctx: RuntimeContext, api: AppApi, sched?: SchedulerDeps): InstanceTrackingHandle;

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

@@ -0,0 +1,141 @@
+// instance-tracking — the process-instance lifecycle reconciler (manifest `instanceTracking`).
+//
+// The problem it closes: an Urban app derives a row's status from the workers that run
+// along a process's *happy path*. When an instance instead reaches a terminal state with
+// no completion job — an operator/`cancelInstance` termination, or a crash — no worker
+// runs, so the read-model row stays "active" forever and any UI derived from it lies.
+//
+// Each `instanceTracking` binding names a datasource table whose rows track an instance by
+// a key column. This module polls the engine for those rows' instances and, when one is
+// `TERMINATED`, applies the binding's `onTerminated.set` patch to the row. It deliberately
+// reconciles only on `TERMINATED` — the state that by definition runs no completion worker
+// — and never on `COMPLETED`, whose terminal row-write the app's own finalize worker owns
+// (reconciling it here would race that worker and could clobber a legitimately-completed
+// row). The poll is driven through the shared `SchedulerDeps` seam so tests are deterministic.
+import { defaultScheduler, MAX_TIMER_DELAY_MS } from "./scheduler.js";
+/** Default poll interval when a binding does not set `pollMs`. */
+export const DEFAULT_INSTANCE_TRACKING_POLL_MS = 15_000;
+/** Poll one binding's instances once. Selects the active rows, asks the engine which of their
+ *  instances are TERMINATED, and applies `onTerminated.set` to each. Returns how many keys were
+ *  scanned and how many rows were reconciled this tick. */
+async function reconcileOnce(api, binding) {
+    const table = api.data.table(binding.table, binding.keyField);
+    // Select the rows worth polling. With a statusField + activeStatuses, only rows in an
+    // active status are candidates, so a row already in a terminal status is skipped; without
+    // them every row is polled and a terminal instance's row is idempotently re-patched (the
+    // engine query returns only TERMINATED instances and the patch is a no-op once applied).
+    let candidates;
+    const statusField = binding.statusField;
+    if (statusField && binding.activeStatuses && binding.activeStatuses.length > 0) {
+        const perStatus = await Promise.all(binding.activeStatuses.map((s) => table.find({ [statusField]: s })));
+        candidates = perStatus.flat();
+    }
+    else {
+        candidates = await table.all();
+    }
+    // Map each active row to its tracked instance key. A row with no/empty key can't be
+    // reconciled (it never started an instance, or the column is unset) — skip it.
+    const keyToRows = new Map();
+    for (const row of candidates) {
+        const raw = row[binding.keyField];
+        if (raw == null || raw === "")
+            continue;
+        const key = String(raw);
+        const list = keyToRows.get(key);
+        if (list)
+            list.push(row);
+        else
+            keyToRows.set(key, [row]);
+    }
+    const keys = [...keyToRows.keys()];
+    if (keys.length === 0)
+        return { scanned: 0, reconciled: 0 };
+    const snapshots = await api.engine.searchProcessInstances({
+        processInstanceKeys: keys,
+        state: "TERMINATED",
+    });
+    const patch = binding.onTerminated.set;
+    let reconciled = 0;
+    for (const snap of snapshots) {
+        if (snap.state !== "TERMINATED")
+            continue; // defensive; we asked for TERMINATED only
+        if (!keyToRows.has(snap.processInstanceKey))
+            continue; // not one we were tracking
+        const changed = await table.update(snap.processInstanceKey, patch);
+        if (changed > 0) {
+            reconciled += changed;
+            api.log("info", "instanceTracking: reconciled terminated instance", {
+                table: binding.table,
+                keyField: binding.keyField,
+                processInstanceKey: snap.processInstanceKey,
+                rowsChanged: changed,
+            });
+        }
+    }
+    return { scanned: keys.length, reconciled };
+}
+/**
+ * Mount the `instanceTracking` reconciler: arm one poll loop per binding. Each loop selects
+ * the active rows, asks the engine which of their instances are terminated, and applies the
+ * declared patch. `stop()` cancels every armed timer.
+ */
+export function mountInstanceTracking(ctx, api, sched = defaultScheduler()) {
+    const bindings = ctx.manifest.instanceTracking ?? [];
+    const timers = new Set();
+    const armed = [];
+    let stopped = false;
+    for (const binding of bindings) {
+        // `pollMs` feeds a self-rescheduling timer, so a non-number/NaN/zero/negative value would
+        // clamp to a 0-delay hot loop. `??` only guards null/undefined; sanitize to a finite positive
+        // number and otherwise fall back to the default. (Manifest validation rejects bad values up
+        // front; this is belt-and-suspenders for a binding mounted without validation.)
+        const rawPoll = binding.pollMs;
+        const pollMs = typeof rawPoll === "number" && Number.isFinite(rawPoll) && rawPoll > 0
+            ? rawPoll
+            : DEFAULT_INSTANCE_TRACKING_POLL_MS;
+        // A single setTimeout delay overflows its 32-bit signed range (~24.8 days) and fires
+        // immediately — which for a self-rescheduling poll would become a hot loop. Clamp through
+        // the one shared constant the cron trigger loop uses (derive-don't-duplicate).
+        const delayMs = Math.min(pollMs, MAX_TIMER_DELAY_MS);
+        const label = `${binding.table}.${binding.keyField}`;
+        armed.push(label);
+        const arm = () => {
+            if (stopped)
+                return;
+            let handle;
+            handle = sched.setTimer(() => {
+                timers.delete(handle);
+                if (stopped)
+                    return;
+                void (async () => {
+                    try {
+                        await reconcileOnce(api, binding);
+                    }
+                    catch (err) {
+                        api.log("error", `instanceTracking "${label}": reconcile failed`, {
+                            error: String(err),
+                        });
+                    }
+                    finally {
+                        arm(); // reschedule regardless of outcome (at-least-once, idempotent)
+                    }
+                })();
+            }, delayMs);
+            timers.add(handle);
+        };
+        arm();
+    }
+    return {
+        name: "instanceTracking",
+        bindings: armed,
+        async stop() {
+            stopped = true;
+            for (const h of timers)
+                sched.clearTimer(h);
+            timers.clear();
+        },
+        describe() {
+            return { bindings: armed };
+        },
+    };
+}

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

@@ -23,6 +23,12 @@ export interface PagesDeps {
     engine: EngineClient;
     /** Read a page file; injectable for tests. */
     readPage(path: string): Promise<string>;
+    /**
+     * List the available page ids (the `*.page.json` basenames under `pagesDir`),
+     * powering the `/app/pages` index endpoint and a `nav` node's `items: "auto"`.
+     * Optional; when absent the index is empty. Injectable for tests.
+     */
+    listPages?(): Promise<string[]>;
 }
 /**
  * Build the page-runtime routes over an injected datasource + engine. Pure over its deps