@nanobpm/urban 0.28.0 → 0.30.0

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/api.d.ts

@@ -0,0 +1,61 @@
+import type { AppApi, RuntimeContext } from "../context.ts";
+import type { HttpRequest } from "../host.ts";
+import { type Route } from "../router.ts";
+/** The manifest `api` binding (ADR 0058). Mirrored locally until `@nanobpm/nano-app-schema`
+ *  republishes with the `api` field folded into `AppManifest` (the schema PR lands first). */
+export interface ApiBinding {
+    spec: string;
+    dir?: string;
+    base?: string;
+    validateResponses?: "dev" | "always" | "never";
+    eject?: boolean;
+}
+/** The `{ params, query, body }` contract a typed operation is generic over. */
+export interface OperationContract {
+    params: unknown;
+    query: unknown;
+    body: unknown;
+}
+/** The loose contract an untyped delegate sees (strings on the wire; unknown JSON body). */
+export interface DefaultContract {
+    params: Record<string, string>;
+    query: Record<string, string | string[] | undefined>;
+    body: unknown;
+}
+/** The input handed to an operation delegate: the raw request plus the parsed (and, unless ejected,
+ *  validated) path params, query, and JSON body. */
+export interface OperationInput<Req extends OperationContract = DefaultContract> {
+    req: HttpRequest;
+    params: Req["params"];
+    query: Req["query"];
+    body: Req["body"];
+}
+/** What a delegate returns; the runtime serializes `body` as JSON. Empty return → `204`. */
+export interface OperationResult<Res = unknown> {
+    status?: number;
+    headers?: Record<string, string>;
+    body?: Res;
+}
+/** An app-authored operation delegate: validated/typed input + the injected AppApi. */
+export type OperationHandler<Req extends OperationContract = DefaultContract, Res = unknown> = (input: OperationInput<Req>, app: AppApi) => Promise<OperationResult<Res> | void> | OperationResult<Res> | void;
+/**
+ * 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 declare function defineOperation<Req extends OperationContract = DefaultContract, Res = unknown>(_id: string, handler: OperationHandler<Req, Res>): OperationHandler<Req, Res>;
+/** Resolve an operation delegate from a loaded module: `default` (when a function) else `handler`. */
+export declare function resolveOperationHandler(mod: Record<string, unknown>): OperationHandler | undefined;
+export interface ApiHandle {
+    readonly name: string;
+    routes: Route[];
+    describe(): Record<string, unknown>;
+}
+/**
+ * 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 declare function mountApi(ctx: RuntimeContext, app: AppApi): ApiHandle;

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";
+    }
+}