@nanobpm/urban 0.28.0 → 0.30.0

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,8 @@
 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";
+import { isAbsolutePath } from "../../../toolkit/artifact.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
@@ -9,8 +10,10 @@ export declare function sqlitePathFromUrl(url: string): string;
  * that starts with a single backslash ("\data\app.db") and a Windows UNC path
  * ("\\\\server\\share"). A single leading backslash covers both the drive-root and UNC cases,
  * matching Node's `path.win32.isAbsolute`. Used by `resolveAppPath` so a caller-supplied absolute
- * path is never incorrectly prefixed with the app root. */
-export declare function isAbsolutePath(p: string): boolean;
+ * path is never incorrectly prefixed with the app root. Defined once in `toolkit/artifact.ts` (the
+ * shared, dependency-free layer) and re-exported here so the toolkit's gen path-join and this
+ * runtime resolver apply the identical rule (no gen/runtime drift). */
+export { isAbsolutePath };
 /** Resolve `p` against the app `root`: an absolute `p` (see `isAbsolutePath`) is returned as-is;
  * a relative `p` is joined onto `root`. Trims a trailing separator of either kind off `root` so
  * we never emit a doubled separator. The join separator matches the root's own style so we never
@@ -29,6 +32,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,9 @@
 // `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";
+import { isAbsolutePath } from "../../../toolkit/artifact.js";
 export function sqlitePathFromUrl(url) {
     // Accept "file:./x.db", "file:x.db", "sqlite:./x.db" or a bare path.
     return url.replace(/^(file|sqlite):(\/\/)?/, "");
@@ -13,10 +15,10 @@ export function sqlitePathFromUrl(url) {
  * that starts with a single backslash ("\data\app.db") and a Windows UNC path
  * ("\\\\server\\share"). A single leading backslash covers both the drive-root and UNC cases,
  * matching Node's `path.win32.isAbsolute`. Used by `resolveAppPath` so a caller-supplied absolute
- * path is never incorrectly prefixed with the app root. */
-export function isAbsolutePath(p) {
-    return /^(\/|\\|[A-Za-z]:[/\\])/.test(p);
-}
+ * path is never incorrectly prefixed with the app root. Defined once in `toolkit/artifact.ts` (the
+ * shared, dependency-free layer) and re-exported here so the toolkit's gen path-join and this
+ * runtime resolver apply the identical rule (no gen/runtime drift). */
+export { isAbsolutePath };
 /** Resolve `p` against the app `root`: an absolute `p` (see `isAbsolutePath`) is returned as-is;
  * a relative `p` is joined onto `root`. Trims a trailing separator of either kind off `root` so
  * we never emit a doubled separator. The join separator matches the root's own style so we never
@@ -43,6 +45,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 +306,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 +320,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,22 @@
+import type { AppApi, Mounted, RuntimeContext } from "../context.ts";
+import type { InstanceTracking } from "../manifest.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[];
+}
+/** Apply a binding's `onTerminated.set` patch to the single row keyed by `processInstanceKey`.
+ *  Only the binding whose table owns that key has a matching row, so callers can fan this over
+ *  every binding and let the no-match ones be no-ops. Returns rows changed. The single place that
+ *  writes the terminal patch (and logs the reconcile): both the poll reconciler below (`reconcileOnce`,
+ *  once per TERMINATED key it discovers) and the cancel primitive (immediately when it terminates an
+ *  instance) route through here, so the two can never drift on the patch or the log. */
+export declare function reconcileTerminatedKey(api: Pick<AppApi, "data" | "log">, bindings: InstanceTracking[], processInstanceKey: string): Promise<number>;
+/**
+ * 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,158 @@
+// 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;
+/** Apply a binding's `onTerminated.set` patch to the single row keyed by `processInstanceKey`.
+ *  Only the binding whose table owns that key has a matching row, so callers can fan this over
+ *  every binding and let the no-match ones be no-ops. Returns rows changed. The single place that
+ *  writes the terminal patch (and logs the reconcile): both the poll reconciler below (`reconcileOnce`,
+ *  once per TERMINATED key it discovers) and the cancel primitive (immediately when it terminates an
+ *  instance) route through here, so the two can never drift on the patch or the log. */
+export async function reconcileTerminatedKey(api, bindings, processInstanceKey) {
+    const key = String(processInstanceKey);
+    let reconciled = 0;
+    for (const binding of bindings) {
+        const table = api.data.table(binding.table, binding.keyField);
+        const changed = await table.update(key, binding.onTerminated.set);
+        if (changed > 0) {
+            reconciled += changed;
+            api.log("info", "instanceTracking: reconciled terminated instance", {
+                table: binding.table,
+                keyField: binding.keyField,
+                processInstanceKey: key,
+                rowsChanged: changed,
+            });
+        }
+    }
+    return reconciled;
+}
+/** Poll one binding's instances once. Selects the active rows, asks the engine which of their
+ *  instances are TERMINATED, and applies `onTerminated.set` to each. 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",
+    });
+    // Apply the terminal patch through the shared `reconcileTerminatedKey` — the one place that
+    // writes `onTerminated.set` and logs the reconcile — so the poll path and the cancel primitive
+    // can never drift on the patch or its logging (No Drift Surfaces).
+    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
+        reconciled += await reconcileTerminatedKey(api, [binding], snap.processInstanceKey);
+    }
+    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

@@ -1,6 +1,7 @@
 import type { AppApi, RuntimeContext } from "../context.ts";
 import type { EngineClient } from "../host.ts";
 import { type Route } from "../router.ts";
+import { type CancelInstanceResult } from "./cancel.ts";
 /** The subset of the datasource gateway the page runtime needs. */
 export interface PagesDataSource {
     query(sql: string, params?: unknown[]): Promise<Record<string, unknown>[]>;
@@ -29,6 +30,13 @@ export interface PagesDeps {
      * Optional; when absent the index is empty. Injectable for tests.
      */
     listPages?(): Promise<string[]>;
+    /**
+     * Cancel a process instance honestly: terminate it, verify it is actually gone, and reconcile
+     * any `instanceTracking` row bound to its key. Injected by `mountPages` (bound to the app's
+     * engine, datasource, and instanceTracking bindings). When absent, the `/app/actions/cancel`
+     * route falls back to a bare `engine.cancelInstance` (used by tests that inject no cancel dep).
+     */
+    cancel?(processInstanceKey: string): Promise<CancelInstanceResult>;
 }
 /**
  * Build the page-runtime routes over an injected datasource + engine. Pure over its deps

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

@@ -16,6 +16,7 @@
 //   POST /app/actions/message                       → engine.publishMessage
 import { errorMessage, isRecord } from "../guards.js";
 import { html, json } from "../router.js";
+import { cancelInstanceReconciling } from "./cancel.js";
 import { quoteIdent } from "./gateway.js";
 /** A JavaScript-body response (the renderer module served at /app/runtime.js). */
 function javascript(body, status = 200) {
@@ -34,7 +35,7 @@ export function createPagesRoutes(opts, deps) {
     const rowLimitRaw = opts.rowLimit ?? 200;
     const rowLimit = Number.isFinite(rowLimitRaw) ? Math.max(0, Math.floor(rowLimitRaw)) : 200;
     const sourceName = opts.sourceName ?? "app";
-    const { db, engine, readPage, listPages } = deps;
+    const { db, engine, readPage, listPages, cancel } = deps;
     // The table-name whitelist is memoised: an Urban app runs its migrations at boot
     // (before serving), so the schema is stable for the process lifetime, and the renderer
     // refreshes grids repeatedly — re-introspecting on every `/app/data` hit would be a hot
@@ -257,6 +258,19 @@ export function createPagesRoutes(opts, deps) {
             }
             if (key === undefined || key === "")
                 return json({ error: "processInstanceKey is required" }, 400);
+            // The reconcile-aware primitive verifies the real post-cancel state and flips the tracked
+            // row immediately; a !ok result means the engine did NOT stop the instance, so surface 502.
+            if (cancel) {
+                try {
+                    const result = await cancel(String(key));
+                    return json(result, result.ok ? 200 : 502);
+                }
+                catch (e) {
+                    // Defensive: the primitive is designed not to throw, but if it ever does, mirror the
+                    // fallback path's honest 502 rather than letting the request reject as a 500.
+                    return json({ ok: false, processInstanceKey: String(key), error: errorMessage(e) }, 502);
+                }
+            }
             try {
                 await engine.cancelInstance({ processInstanceKey: String(key) });
                 return json({ ok: true });
@@ -323,9 +337,11 @@ export function mountPages(ctx, app) {
         sourceName: typeof decl.sourceName === "string" ? decl.sourceName : undefined,
     };
     const sourceName = opts.sourceName ?? "app";
+    const bindings = ctx.manifest.instanceTracking ?? [];
     const routes = createPagesRoutes(opts, {
         db: app.data.open(sourceName),
         engine: app.engine,
+        cancel: (key) => cancelInstanceReconciling(app, bindings, key),
         readPage: (p) => ctx.host.readTextFile(p),
         listPages: async () => {
             const dir = opts.pagesDir ?? "pages";

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

@@ -0,0 +1,11 @@
+/** Injectable timer + clock seam so background scheduling is deterministic under test. */
+export interface SchedulerDeps {
+    setTimer: (fn: () => void, delayMs: number) => unknown;
+    clearTimer: (handle: unknown) => void;
+    /** Current wall-clock time in ms since epoch. */
+    now: () => number;
+}
+/** Max delay a single `setTimeout` honours before its 32-bit signed overflow (~24.8 days). */
+export declare const MAX_TIMER_DELAY_MS = 2147483647;
+/** Default (live) scheduler seam, backed by the global timer functions. */
+export declare function defaultScheduler(): SchedulerDeps;

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

@@ -0,0 +1,21 @@
+// The injectable timer + clock seam shared by every background loop in urban (cron
+// triggers, the instance-tracking reconciler). Keeping one definition here — rather
+// than a copy per module — means a test's fake scheduler drives them all the same
+// way, and the "clamp a far-future delay to setTimeout's 32-bit range" rule has a
+// single home.
+/** Max delay a single `setTimeout` honours before its 32-bit signed overflow (~24.8 days). */
+export const MAX_TIMER_DELAY_MS = 2_147_483_647;
+function isTimerHandle(handle) {
+    return typeof handle === "number" || (typeof handle === "object" && handle !== null);
+}
+/** Default (live) scheduler seam, backed by the global timer functions. */
+export function defaultScheduler() {
+    return {
+        setTimer: (fn, ms) => globalThis.setTimeout(fn, ms),
+        clearTimer: (h) => {
+            if (isTimerHandle(h))
+                globalThis.clearTimeout(h);
+        },
+        now: () => Date.now(),
+    };
+}

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

@@ -4,6 +4,7 @@
 // (LLM wiring is a separate concern). Surfaces contribute routes to the shared server.
 import { html, json, normalizeRoutePath } from "../router.js";
 import { mountActions } from "./actions.js";
+import { mountApi } from "./api.js";
 import { mountPages } from "./pages.js";
 /** Escape HTML-significant characters before embedding a value in markup. */
 function escapeHtml(s) {
@@ -93,6 +94,14 @@ export function mountSurfaces(ctx, app) {
         routes.push(...actions.routes);
         enabled.push(`actions(${actions.routes.length})`);
     }
+    // The OpenAPI endpoint surface (ADR 0058) mounts AFTER actions (so an exact `actions[]` route
+    // still shadows an operation) and BEFORE the generic pages routes. It owns the `api.base`
+    // namespace via a regex dispatcher, so it only contributes routes when the app declares `api`.
+    const api = mountApi(ctx, app);
+    if (api.routes.length > 0) {
+        routes.push(...api.routes);
+        enabled.push("api");
+    }
     // The pages surface (the schema-driven page runtime) mounts its own routes.
     const pages = mountPages(ctx, app);
     if (pages.routes.length > 0) {

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

@@ -1,15 +1,10 @@
 import type { AppApi, Mounted, RuntimeContext } from "../context.ts";
 import { type Route } from "../router.ts";
+import { type SchedulerDeps } from "./scheduler.ts";
+export type { SchedulerDeps };
 export interface TriggersHandle extends Mounted {
     routes: Route[];
 }
-/** Injectable timer + clock seam so cron scheduling is deterministic under test. */
-export interface SchedulerDeps {
-    setTimer: (fn: () => void, delayMs: number) => unknown;
-    clearTimer: (handle: unknown) => void;
-    /** Current wall-clock time in ms since epoch. */
-    now: () => number;
-}
 type Scope = {
     body: unknown;
     headers: Record<string, string>;
@@ -58,4 +53,3 @@ export declare function runTriggerAction(app: AppApi, action: RuntimeTriggerActi
 /** Mount webhook + cron triggers. Webhooks contribute HTTP routes; cron triggers arm
  *  background timers that fire their action on schedule. `stop()` clears every timer. */
 export declare function mountTriggers(ctx: RuntimeContext, app: AppApi, sched?: SchedulerDeps): TriggersHandle;
-export {};

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

@@ -5,6 +5,7 @@
 import { isRecord } from "../guards.js";
 import { json, normalizeRoutePath } from "../router.js";
 import { nextCronFire, parseCron } from "./cron.js";
+import { defaultScheduler, MAX_TIMER_DELAY_MS } from "./scheduler.js";
 /**
  * Resolve a tiny FEEL-ish expression against the event scope: a `= body.a.b` path walk
  * returns the raw value at that path (or `undefined` if any segment is missing); a literal
@@ -92,22 +93,6 @@ export async function runTriggerAction(app, action, scope) {
     return { kind: "none" };
 }
 const emptyScope = { body: {}, headers: {}, query: {} };
-/** Max delay a single `setTimeout` honours before its 32-bit signed overflow (~24.8 days). */
-const MAX_TIMER_DELAY_MS = 2_147_483_647;
-/** Default (live) scheduler seam, backed by the global timer functions. */
-function defaultScheduler() {
-    return {
-        setTimer: (fn, ms) => globalThis.setTimeout(fn, ms),
-        clearTimer: (h) => {
-            if (isTimerHandle(h))
-                globalThis.clearTimeout(h);
-        },
-        now: () => Date.now(),
-    };
-}
-function isTimerHandle(handle) {
-    return typeof handle === "number" || (typeof handle === "object" && handle !== null);
-}
 /** Mount webhook + cron triggers. Webhooks contribute HTTP routes; cron triggers arm
  *  background timers that fire their action on schedule. `stop()` clears every timer. */
 export function mountTriggers(ctx, app, sched = defaultScheduler()) {

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

@@ -4,6 +4,7 @@
 import { isRecord } from "../guards.js";
 import { workerJobType } from "../manifest.js";
 import { runLlmJob } from "./llm.js";
+import { runInJobContext } from "../execContext.js";
 /** Adapt an engine SDK client into the LLM module's `DecisionEvaluator`, parsing the
  *  decision's JSON-string `output` into the value fed back to the LLM job. Validates the
  *  SDK shape and adds decision context to a parse failure rather than surfacing a raw
@@ -98,7 +99,7 @@ export async function mountWorkers(ctx, app) {
                 env: (n) => app.env(n),
                 evaluateDecision: app.sdk ? sdkDecisionEvaluator(app.sdk) : undefined,
             };
-            const wrapped = (job) => runLlmJob(job.variables, binding, rt);
+            const wrapped = (job) => runInJobContext({ instanceKey: job.processInstanceKey, elementId: job.elementId, jobType }, () => runLlmJob(job.variables, binding, rt));
             const sub = await ctx.engine.registerWorker(jobType, wrapped, {
                 workerName: `${ctx.manifest.id}:${jobType}`,
             });
@@ -113,7 +114,7 @@ export async function mountWorkers(ctx, app) {
             throw new Error(`worker "${jobType}": ${decl.handler} exports no handler for it ` +
                 `(expected handlers["${jobType}"], a named export, or a default function)`);
         }
-        const wrapped = (job) => handler(job, app);
+        const wrapped = (job) => runInJobContext({ instanceKey: job.processInstanceKey, elementId: job.elementId, jobType }, () => handler(job, app));
         const sub = await ctx.engine.registerWorker(jobType, wrapped, {
             workerName: `${ctx.manifest.id}:${jobType}`,
         });