@nanobpm/urban 0.29.0 → 0.31.0

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

@@ -0,0 +1,359 @@
+// api — the OpenAPI endpoint surface (ADR 0058). The contract-first counterpart to `actions[]`:
+// instead of hand-rolled imperative handlers, an author declares `api: { spec }` in the manifest and
+// writes one delegate module per `operationId`. This runtime reads the SAME OpenAPI document the
+// toolkit deriver turns into types (via the shared `openapi/spec.ts`), mounts one dispatcher over the
+// `api.base` namespace, and for each request: parses → validates params/query/body against the spec →
+// 400 with a structured error → resolves + calls the operationId delegate (validated, typed input +
+// the injected AppApi, exactly like a worker/action handler) → serializes the result.
+//
+// Coexistence + eject (ADR 0058): this mounts AFTER `mountActions` (so an exact `actions[]` route
+// still shadows) and BEFORE the generic pages routes. Ejecting skips generated validation and hands
+// the delegate the raw request — whole-surface via `api.eject`, or per-operation via the
+// `x-urban-eject: true` OpenAPI vendor extension. The delegate is always additively imperative: it
+// gets the raw `req` and full `AppApi` on top of the validated input.
+import { errorMessage } from "../guards.js";
+import { json, normalizeRoutePath } from "../router.js";
+import { resolveAppPath } from "./datasource.js";
+import { collectOperations, isSafeOperationId, operationsWithoutId, operationsWithUnsafeId, parseSpec, resolveSchema, toRouteMatcher, undeclaredPathParams, validateValue, } from "../../../openapi/spec.js";
+/**
+ * Typed-identity helper the generated `operations.ts` wrapper re-types per operationId. Authoring:
+ * `export default defineOperation("createInvoice", async ({ params, query, body }, app) => { ... })`
+ * — the handler's first argument is the validated `OperationInput` (params/query/body/req), not the
+ * raw request. The runtime resolves a delegate by its module path (`<dir>/<operationId>`), so the id
+ * here is a documentation + typing aid; it is returned unchanged.
+ */
+export function defineOperation(_id, handler) {
+    return handler;
+}
+function isFunction(v) {
+    return typeof v === "function";
+}
+/** Resolve an operation delegate from a loaded module: `default` (when a function) else `handler`. */
+export function resolveOperationHandler(mod) {
+    if (isFunction(mod.default))
+        return mod.default;
+    if (isFunction(mod.handler))
+        return mod.handler;
+    return undefined;
+}
+function readApiBinding(manifest) {
+    const raw = manifest && typeof manifest === "object" ? Reflect.get(manifest, "api") : undefined;
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const spec = Reflect.get(raw, "spec");
+    if (typeof spec !== "string" || spec.trim().length === 0)
+        return undefined;
+    const dir = Reflect.get(raw, "dir");
+    const base = Reflect.get(raw, "base");
+    const validateResponses = Reflect.get(raw, "validateResponses");
+    const eject = Reflect.get(raw, "eject");
+    // Trim benign manifest whitespace so it can't produce hard-to-diagnose path/import failures.
+    return {
+        spec: spec.trim(),
+        dir: typeof dir === "string" && dir.trim().length > 0 ? dir.trim() : undefined,
+        base: typeof base === "string" && base.trim().length > 0 ? base.trim() : undefined,
+        validateResponses: validateResponses === "dev" || validateResponses === "always" || validateResponses === "never"
+            ? validateResponses
+            : undefined,
+        eject: eject === true,
+    };
+}
+/** Coerce a wire string to the type its parameter schema declares, so numeric/boolean bounds
+ *  validate. A value that will not coerce is left as-is and fails the type check with a clear
+ *  message. The delegate still receives the original string(s). */
+function coerceParam(doc, schema, raw) {
+    const s = resolveSchema(doc, schema);
+    if (!s)
+        return raw;
+    if (s.type === "integer" || s.type === "number") {
+        const n = Number(raw);
+        return raw.trim() !== "" && !Number.isNaN(n) ? n : raw;
+    }
+    if (s.type === "boolean") {
+        if (raw === "true")
+            return true;
+        if (raw === "false")
+            return false;
+    }
+    return raw;
+}
+/**
+ * Mount the OpenAPI endpoint surface. Returns no routes when the app declares no `api` binding, so
+ * it is a no-op for apps that use only `actions[]`. A malformed spec (bad JSON / not an object)
+ * mounts a single route under the base that returns a clear 500, rather than failing app boot.
+ */
+export function mountApi(ctx, app) {
+    const binding = readApiBinding(ctx.manifest);
+    if (!binding)
+        return { name: "api", routes: [], describe: () => ({ api: "disabled" }) };
+    // Normalize the manifest base the same way actions[] routes do (shared normalizeRoutePath):
+    // ensure a leading "/", strip trailing slashes, and fall back when empty — otherwise a base
+    // like "app/api" would never match request paths, which always start with "/".
+    const base = normalizeRoutePath(binding.base, "/app/api");
+    const dir = binding.dir ?? "operations";
+    const surfaceEject = binding.eject === true;
+    // Resolve + parse the spec lazily on first request and cache it (mirroring the lazy module load
+    // pattern). A malformed/unreadable spec surfaces as a 500 on request — with the reason — rather
+    // than failing app boot.
+    let docPromise;
+    const loadDoc = () => {
+        if (!docPromise) {
+            docPromise = ctx.host
+                .readTextFile(resolveAppPath(ctx.root, binding.spec))
+                .then((text) => parseSpec(text))
+                .catch((e) => {
+                docPromise = undefined; // let a later request retry (e.g. after the file is fixed)
+                throw new Error(`OpenAPI spec ${binding.spec} failed to load: ${errorMessage(e)}`);
+            });
+        }
+        return docPromise;
+    };
+    // Lazily import + cache each delegate module, mirroring mountActions.
+    const moduleCache = new Map();
+    const loadModule = (operationId) => {
+        // Defense-in-depth at the import sink: collectOperations already skips unsafe ids, but never
+        // build an import path from an operationId that isn't a single safe segment.
+        if (!isSafeOperationId(operationId)) {
+            return Promise.reject(new Error(`unsafe operationId (not a single path segment): ${operationId}`));
+        }
+        const key = resolveAppPath(ctx.root, `${dir.replace(/[/\\]+$/, "")}/${operationId}`);
+        let pending = moduleCache.get(key);
+        if (!pending) {
+            pending = ctx.host.importModule(key).catch((err) => {
+                moduleCache.delete(key);
+                throw err;
+            });
+            moduleCache.set(key, pending);
+        }
+        return pending;
+    };
+    // Build the operation table lazily from the loaded doc (cached).
+    let opsPromise;
+    const loadOps = () => {
+        if (!opsPromise) {
+            opsPromise = loadDoc()
+                .then((d) => {
+                const missing = operationsWithoutId(d);
+                if (missing.length > 0) {
+                    ctx.host.log("warn", "OpenAPI operations without operationId are skipped (ADR 0058)", {
+                        missing,
+                    });
+                }
+                const undeclared = undeclaredPathParams(d);
+                if (undeclared.length > 0) {
+                    ctx.host.log("warn", "OpenAPI path-template params are not declared as parameters — captured at runtime but neither typed nor validated (ADR 0058)", { undeclared });
+                }
+                const unsafe = operationsWithUnsafeId(d);
+                if (unsafe.length > 0) {
+                    ctx.host.log("warn", "OpenAPI operationIds that are not a safe path segment are skipped (ADR 0058)", { unsafe });
+                }
+                const mounted = collectOperations(d).map((op) => {
+                    const { pattern, paramNames } = toRouteMatcher(base, op.path);
+                    return { op, pattern, paramNames };
+                });
+                // Dispatch matches the first route in order, so sort most-specific first: fewer path-template
+                // params (a static segment beats a `{param}` capture), then longer path. This keeps a static
+                // route (e.g. /x/active) from being shadowed by a templated one (e.g. /x/{id}).
+                mounted.sort((a, b) => {
+                    if (a.paramNames.length !== b.paramNames.length) {
+                        return a.paramNames.length - b.paramNames.length;
+                    }
+                    return b.op.path.length - a.op.path.length;
+                });
+                return mounted;
+            })
+                .catch((e) => {
+                opsPromise = undefined; // don't cache the rejection — let a later request retry (mirrors loadDoc)
+                throw e;
+            });
+        }
+        return opsPromise;
+    };
+    const dispatchInner = async (req) => {
+        let d;
+        let ops;
+        try {
+            d = await loadDoc();
+            ops = await loadOps();
+        }
+        catch (e) {
+            return json({ error: errorMessage(e) }, 500);
+        }
+        const method = req.method.toUpperCase();
+        const match = ops.find((m) => m.op.method.toUpperCase() === method && m.pattern.test(req.path));
+        if (!match) {
+            // Path is in our namespace but no operation matches: is it a known path on another method?
+            const pathKnown = ops.some((m) => m.pattern.test(req.path));
+            return json({ error: pathKnown ? "method not allowed" : "no such operation" }, pathKnown ? 405 : 404);
+        }
+        const { op } = match;
+        const ejected = surfaceEject || op.eject;
+        // Path params from the capture groups; query as a single-or-array map.
+        const captures = match.pattern.exec(req.path) ?? [];
+        const params = {};
+        try {
+            match.paramNames.forEach((name, i) => {
+                const v = captures[i + 1];
+                if (v !== undefined)
+                    params[name] = decodeURIComponent(v);
+            });
+        }
+        catch {
+            // Malformed percent-encoding is client input, not a server fault — a clear 400 beats a 500.
+            return json({ error: "malformed path parameter encoding" }, 400);
+        }
+        const query = {};
+        for (const key of new Set(req.query.keys())) {
+            const all = req.query.getAll(key);
+            query[key] = all.length > 1 ? all : all[0];
+        }
+        // Parse the JSON body (empty body → undefined). Invalid JSON is a 400 unless the op is ejected
+        // (then the delegate reads the raw request itself).
+        const raw = await req.text();
+        let body = {};
+        let bodyParseFailed = false;
+        if (raw) {
+            try {
+                body = JSON.parse(raw);
+            }
+            catch {
+                bodyParseFailed = true;
+                body = undefined;
+            }
+        }
+        else {
+            body = undefined;
+        }
+        if (bodyParseFailed && !ejected) {
+            return json({ error: "request body must be JSON" }, 400);
+        }
+        if (!ejected) {
+            const issues = [];
+            for (const p of op.parameters) {
+                if (p.in === "path") {
+                    const val = params[p.name];
+                    if (val === undefined) {
+                        if (p.required)
+                            issues.push({ path: `params/${p.name}`, message: "is required" });
+                        continue;
+                    }
+                    issues.push(...validateValue(d, p.schema, coerceParam(d, p.schema, val), `params/${p.name}`));
+                }
+                else if (p.in === "query") {
+                    const val = query[p.name];
+                    if (val === undefined) {
+                        if (p.required)
+                            issues.push({ path: `query/${p.name}`, message: "is required" });
+                        continue;
+                    }
+                    const values = Array.isArray(val) ? val : [val];
+                    const ps = resolveSchema(d, p.schema);
+                    if (ps?.type === "array") {
+                        // Repeated keys (?tag=a&tag=b) form the array; coerce + validate each item, then the
+                        // whole array against the schema's array constraints (minItems, items, ...).
+                        const items = ps.items ? values.map((v) => coerceParam(d, ps.items, v)) : values;
+                        issues.push(...validateValue(d, ps, items, `query/${p.name}`));
+                    }
+                    else {
+                        // Scalar param: validate EVERY provided value, not just the first, so extra repeated
+                        // values can't bypass validation.
+                        values.forEach((v, i) => {
+                            const at = values.length > 1 ? `query/${p.name}[${i}]` : `query/${p.name}`;
+                            issues.push(...validateValue(d, p.schema, coerceParam(d, p.schema, v), at));
+                        });
+                    }
+                }
+            }
+            if (op.requestBodyRequired && (raw === "" || body === undefined)) {
+                issues.push({ path: "body", message: "request body is required" });
+            }
+            else if (op.requestBodySchema && body !== undefined) {
+                issues.push(...validateValue(d, op.requestBodySchema, body, "body"));
+            }
+            if (issues.length > 0) {
+                return json({ error: "request validation failed", issues }, 400);
+            }
+        }
+        let handler;
+        try {
+            handler = resolveOperationHandler(await loadModule(op.operationId));
+        }
+        catch (e) {
+            ctx.host.log("error", "operation delegate failed to load", {
+                operationId: op.operationId,
+                dir,
+                error: errorMessage(e),
+            });
+            return json({ error: `operation ${op.operationId} delegate failed to load` }, 500);
+        }
+        if (!handler) {
+            return json({
+                error: `operation ${op.operationId} delegate exports no default function or named \`handler\``,
+            }, 500);
+        }
+        // Keep the runtime body in lockstep with the derived type: the deriver types `body` as
+        // `undefined` exactly when the op declares no usable request body (no JSON schema and not
+        // required), so pass `undefined` to those handlers rather than leaking a parsed value through
+        // a body-less type.
+        const handlerBody = op.requestBodySchema !== undefined || op.requestBodyRequired ? body : undefined;
+        try {
+            const result = await handler({ req, params, query, body: handlerBody }, app);
+            if (!result)
+                return { status: 204 };
+            // Optional response validation (dev by default): warn-only, never blocks the response.
+            const mode = binding.validateResponses ?? "dev";
+            const doValidate = mode === "always" || (mode === "dev" && ctx.host.env("NODE_ENV") !== "production");
+            if (doValidate && op.responseSchema && result.body !== undefined) {
+                const rIssues = validateValue(d, op.responseSchema, result.body, "response");
+                if (rIssues.length > 0) {
+                    ctx.host.log("warn", "operation response failed schema validation (ADR 0058)", {
+                        operationId: op.operationId,
+                        issues: rIssues,
+                    });
+                }
+            }
+            return {
+                status: result.status ?? 200,
+                headers: { "content-type": "application/json", ...(result.headers ?? {}) },
+                body: result.body === undefined ? undefined : JSON.stringify(result.body),
+            };
+        }
+        catch (e) {
+            return json({ error: errorMessage(e) }, 500);
+        }
+    };
+    // Categorical safety net: any unexpected throw during dispatch — e.g. a malformed spec
+    // `pattern` surfacing from validation — becomes a controlled 500 rather than escaping into
+    // the host request handler, which has no top-level catch of its own.
+    const dispatch = async (req) => {
+        try {
+            return await dispatchInner(req);
+        }
+        catch (e) {
+            return json({ error: errorMessage(e) }, 500);
+        }
+    };
+    // One prefix route over the base namespace does regex dispatch across all operations — the shared
+    // router only does exact/prefix matches, so path-param templates are handled here. A trailing
+    // slash keeps the prefix boundary-safe.
+    const route = {
+        method: "*",
+        path: `${base}/`,
+        prefix: true,
+        source: `api:${binding.spec}`,
+        handler: dispatch,
+    };
+    // Also serve the base path exactly (an operation could live at the namespace root).
+    const rootRoute = {
+        method: "*",
+        path: base,
+        prefix: false,
+        source: `api:${binding.spec}`,
+        handler: dispatch,
+    };
+    return {
+        name: "api",
+        routes: [rootRoute, route],
+        describe: () => ({ api: { spec: binding.spec, base, dir, eject: surfaceEject } }),
+    };
+}

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

@@ -0,0 +1,31 @@
+import type { AppApi } from "../context.ts";
+import type { InstanceTracking } from "../manifest.ts";
+export type CancelInstanceState = "ACTIVE" | "COMPLETED" | "TERMINATED" | "gone";
+export interface CancelInstanceResult {
+    ok: boolean;
+    processInstanceKey: string;
+    /** The instance state as read back from the engine after the cancel attempt.
+     *  `"gone"` means the engine has no record of the key (already cleaned up / never existed). */
+    state: CancelInstanceState;
+    /** Rows flipped to their terminal status by the immediate instanceTracking reconcile. */
+    reconciled: number;
+    error?: string;
+}
+type CancelApi = Pick<AppApi, "engine" | "data" | "log">;
+/**
+ * Cancel a process instance honestly: terminate it, verify it is actually gone, and immediately
+ * reconcile any instanceTracking row bound to its key.
+ *
+ * Outcome rules:
+ *  - `cancelInstance` returns without throwing → the engine accepted the termination (a committed
+ *    204); trust it even if the read model still lags at ACTIVE.
+ *  - `cancelInstance` throws but the instance reads back non-ACTIVE (already TERMINATED/COMPLETED
+ *    /gone) → the cancel was effectively idempotent; treat as success.
+ *  - `cancelInstance` throws and the instance is still ACTIVE → an honest failure: report it and
+ *    do NOT touch any row (the instance is still running).
+ *
+ * Reconcile only on `TERMINATED`: a COMPLETED instance's terminal row-write is owned by the app's
+ * own finalize logic, and a gone/ACTIVE instance has nothing to flip here.
+ */
+export declare function cancelInstanceReconciling(api: CancelApi, bindings: InstanceTracking[], processInstanceKey: string): Promise<CancelInstanceResult>;
+export {};

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

@@ -0,0 +1,90 @@
+// The Urban-native "cancel a process instance" primitive.
+//
+// Cancelling a running process from a page action must do two honest things that a bare
+// `engine.cancelInstance` call does not:
+//
+//   1. Report the *real* outcome. A cancel can fail (permissions, the instance already gone,
+//      a transport error). Swallowing that and reporting success leaves an instance running in
+//      the engine while the UI claims it stopped — the worst possible lie for a "cancel" button.
+//   2. Reconcile the tracked row immediately. Apps bind process instances to rows via
+//      `instanceTracking`; the poll reconciler flips a row to its terminal status within a few
+//      seconds of the instance terminating. When *we* are the one terminating it, we can apply
+//      that same declared patch right away instead of waiting for the next poll tick.
+//
+// This primitive keys success on the engine's response, then reconciles off the read model: a
+// non-throwing `cancelInstance` is a committed termination (trusted even if the read model still
+// lags at ACTIVE), while a throw whose instance reads back still-ACTIVE is an honest failure. It
+// reuses the instanceTracking bindings' `onTerminated.set` patch, so the immediate reconcile can
+// never drift from the poll reconciler's.
+import { errorMessage } from "../guards.js";
+import { reconcileTerminatedKey } from "./instance-tracking.js";
+/**
+ * Cancel a process instance honestly: terminate it, verify it is actually gone, and immediately
+ * reconcile any instanceTracking row bound to its key.
+ *
+ * Outcome rules:
+ *  - `cancelInstance` returns without throwing → the engine accepted the termination (a committed
+ *    204); trust it even if the read model still lags at ACTIVE.
+ *  - `cancelInstance` throws but the instance reads back non-ACTIVE (already TERMINATED/COMPLETED
+ *    /gone) → the cancel was effectively idempotent; treat as success.
+ *  - `cancelInstance` throws and the instance is still ACTIVE → an honest failure: report it and
+ *    do NOT touch any row (the instance is still running).
+ *
+ * Reconcile only on `TERMINATED`: a COMPLETED instance's terminal row-write is owned by the app's
+ * own finalize logic, and a gone/ACTIVE instance has nothing to flip here.
+ */
+export async function cancelInstanceReconciling(api, bindings, processInstanceKey) {
+    const key = String(processInstanceKey);
+    let threw;
+    try {
+        await api.engine.cancelInstance({ processInstanceKey: key });
+    }
+    catch (error) {
+        threw = error;
+    }
+    const state = await readState(api, key, threw);
+    if (threw && state === "ACTIVE") {
+        // The cancel genuinely failed and the instance is still running — never flip a row to a
+        // terminal status while the engine keeps executing it.
+        api.log("error", "cancel: engine termination failed, instance still active", {
+            processInstanceKey: key,
+            error: errorMessage(threw),
+        });
+        return { ok: false, processInstanceKey: key, state, reconciled: 0, error: errorMessage(threw) };
+    }
+    let reconciled = 0;
+    if (state === "TERMINATED") {
+        try {
+            reconciled = await reconcileTerminatedKey(api, bindings, key);
+        }
+        catch (error) {
+            // The engine termination itself succeeded — a reconcile *write* failure (bad binding,
+            // transient DB error) must not turn that into an unhandled 500. Log it and let the
+            // instanceTracking poll reconciler catch the row up on its next tick.
+            api.log("error", "cancel: instance terminated but row reconcile failed", {
+                processInstanceKey: key,
+                error: errorMessage(error),
+            });
+            return { ok: true, processInstanceKey: key, state, reconciled: 0, error: errorMessage(error) };
+        }
+    }
+    return { ok: true, processInstanceKey: key, state, reconciled };
+}
+/** Read the instance state back from the engine to verify what actually happened. When the read
+ *  itself fails we fall back to the cancel call's own result: a thrown cancel with an unverifiable
+ *  state is reported as still-ACTIVE (honest worst case); an accepted cancel is trusted as gone. */
+async function readState(api, key, threw) {
+    try {
+        const [snapshot] = await api.engine.searchProcessInstances({ processInstanceKeys: [key] });
+        if (snapshot)
+            return snapshot.state;
+        return "gone";
+    }
+    catch (error) {
+        api.log("warn", "cancel: could not verify post-cancel state", {
+            processInstanceKey: key,
+            error: errorMessage(error),
+        });
+        return threw ? "ACTIVE" : "gone";
+    }
+}

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

@@ -2,6 +2,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, 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

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

@@ -4,6 +4,7 @@
 // runtime side of ADR 0024 (datasource) + ADR 0040 (domain model), scoped to what an app needs.
 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):(\/\/)?/, "");
@@ -14,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

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

@@ -1,4 +1,5 @@
 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;
@@ -6,6 +7,13 @@ 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

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

@@ -15,6 +15,30 @@
 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. */
@@ -54,23 +78,16 @@ async function reconcileOnce(api, binding) {
         processInstanceKeys: keys,
         state: "TERMINATED",
     });
-    const patch = binding.onTerminated.set;
+    // 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
-        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,
-            });
-        }
+        reconciled += await reconcileTerminatedKey(api, [binding], snap.processInstanceKey);
     }
     return { scanned: keys.length, reconciled };
 }

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