@nanobpm/urban 0.28.0 → 0.30.0

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

@@ -13,6 +13,9 @@ export interface MountFlags {
     surfaces?: boolean;
     triggers?: boolean;
     security?: boolean;
+    /** The `instanceTracking` reconciler poll loop. Shares no HTTP surface; safe to disable
+     *  in hosts that only render surfaces (e.g. the console preview). */
+    instanceTracking?: boolean;
 }
 export interface CreateUrbanAppOptions {
     host: HostContext;

package/dist/runtime/core/runtime.js

@@ -7,10 +7,12 @@ import { validateManifest } from "./validate.js";
 import { makeRouter } from "./router.js";
 import { deployModels } from "./modules/deploy.js";
 import { provisionData, DataLayer } from "./modules/datasource.js";
+import { installExecStore } from "./execContext.js";
 import { mountWorkers } from "./modules/workers.js";
 import { mountConnectors } from "./modules/connectors.js";
 import { mountSurfaces } from "./modules/surfaces.js";
 import { mountTriggers } from "./modules/triggers.js";
+import { mountInstanceTracking } from "./modules/instance-tracking.js";
 import { mountSecurity } from "./modules/security.js";
 /** Resolve the HTTP port: explicit option, else $PORT, else 8090. Throws a clear
  * error when $PORT is set but not a valid integer in 0..65535. */
@@ -43,8 +45,13 @@ export async function createUrbanApp(opts) {
         surfaces: opts.mount?.surfaces ?? true,
         triggers: opts.mount?.triggers ?? true,
         security: opts.mount?.security ?? true,
+        instanceTracking: opts.mount?.instanceTracking ?? true,
     };
     const ctx = { manifest, host, engine, root, templates: opts.templates };
+    // Install the ambient job-execution store once per process (idempotent) so worker dispatch can
+    // stamp write-provenance onto DataLayer inserts. Absent-safe: a host without `createAsyncStore`
+    // leaves provenance capture disabled.
+    installExecStore(() => host.createAsyncStore?.());
     let data;
     let security;
     let server;
@@ -144,6 +151,11 @@ export async function createUrbanApp(opts) {
                     mounted.push(t);
                     describe.triggers = t.describe?.();
                 }
+                if (flags.instanceTracking && (manifest.instanceTracking?.length ?? 0) > 0) {
+                    const it = mountInstanceTracking(ctx, api);
+                    mounted.push(it);
+                    describe.instanceTracking = it.describe?.();
+                }
                 if (security)
                     describe.security = security.describe();
                 if (data)

package/dist/runtime/core/validate.js

@@ -131,6 +131,44 @@ export function collectManifestIssues(m) {
                 issues.push({ path: `triggers[${i}].type`, message: "missing type" });
         });
     }
+    // instanceTracking: each binding must name the table + key column it tracks and a
+    // non-empty `onTerminated.set` patch — a reconciler with nothing to write is inert
+    // and almost certainly a mistake. `activeStatuses` without `statusField` is incoherent
+    // (no column to read the statuses from), so the runtime would silently poll every row.
+    const tracking = Array.isArray(obj.instanceTracking) ? obj.instanceTracking : undefined;
+    if (tracking) {
+        tracking.forEach((t, i) => {
+            const b = isRecord(t) ? t : undefined;
+            if (typeof b?.table !== "string" || b.table.length === 0) {
+                issues.push({ path: `instanceTracking[${i}].table`, message: "missing table" });
+            }
+            if (typeof b?.keyField !== "string" || b.keyField.length === 0) {
+                issues.push({ path: `instanceTracking[${i}].keyField`, message: "missing keyField" });
+            }
+            const onTerminated = isRecord(b?.onTerminated) ? b.onTerminated : undefined;
+            const set = isRecord(onTerminated?.set) ? onTerminated.set : undefined;
+            if (!set || Object.keys(set).length === 0) {
+                issues.push({
+                    path: `instanceTracking[${i}].onTerminated.set`,
+                    message: "missing onTerminated.set patch (a non-empty column → value map)",
+                });
+            }
+            if (Array.isArray(b?.activeStatuses) && (typeof b?.statusField !== "string" || b.statusField.length === 0)) {
+                issues.push({
+                    path: `instanceTracking[${i}].activeStatuses`,
+                    message: "activeStatuses requires statusField",
+                });
+            }
+            // `pollMs`, when set, schedules a self-rescheduling timer; a non-number/NaN/non-positive
+            // value would become a 0-delay hot loop at runtime, so reject it at author time.
+            if (b?.pollMs !== undefined && (typeof b.pollMs !== "number" || !Number.isFinite(b.pollMs) || b.pollMs <= 0)) {
+                issues.push({
+                    path: `instanceTracking[${i}].pollMs`,
+                    message: "pollMs must be a finite positive number of milliseconds",
+                });
+            }
+        });
+    }
     return issues;
 }
 export function assertValidManifest(m) {

package/dist/runtime/engine/nanosdk.d.ts

@@ -1,8 +1,13 @@
-import type { EngineClient, JobHandler, WorkerSubscription } from "../core/host.ts";
+import type { EngineClient, JobHandler, ProcessInstanceSnapshot, ProcessInstanceState, WorkerSubscription } from "../core/host.ts";
 import type { EngineSdkClient } from "./sdk.ts";
 /** Coerce an engine response's process-instance key to a non-empty string, or
  * throw — a missing key means a malformed/partial response, not a real instance. */
 export declare function requireProcessInstanceKey(key: string | number | null | undefined): string;
+/** Map the engine's process-instance `state` onto the transport-agnostic
+ *  {@link ProcessInstanceState} union, or `undefined` for an unrecognized value
+ *  (which the caller skips rather than mis-reconciling). Case-insensitive so a
+ *  future casing tweak on the engine side doesn't silently drop instances. */
+export declare function normalizeProcessInstanceState(raw: unknown): ProcessInstanceState | undefined;
 /** A job as delivered to a nano-sdk job handler: the frame fields plus the
  *  acknowledgement actions the handler must call. */
 export interface NanoSdkActivatedJob {
@@ -76,6 +81,10 @@ export interface NanoSdkClient {
         userTaskKey: string;
         variables?: Record<string, unknown>;
     }, options?: unknown): Promise<unknown>;
+    searchProcessInstances(input: {
+        filter?: Record<string, unknown>;
+        page?: Record<string, unknown>;
+    }, consistency?: unknown, options?: unknown): Promise<Record<string, unknown>>;
     createJobWorker(cfg: NanoSdkJobWorkerConfig): NanoSdkJobWorker;
     /** Stop every worker created on this client. Used on teardown to also drain a
      * REST-fallback worker, whose handle the `createJobWorker` proxy starts internally
@@ -134,6 +143,10 @@ export declare class SdkEngineClient implements EngineClient {
         variables?: Record<string, unknown>;
     }[]>;
     completeUserTask(userTaskKey: string, variables?: Record<string, unknown>): Promise<void>;
+    searchProcessInstances(filter?: {
+        processInstanceKeys?: string[];
+        state?: ProcessInstanceState;
+    }): Promise<ProcessInstanceSnapshot[]>;
     registerWorker(jobType: string, handler: JobHandler, options?: {
         workerName?: string;
         maxParallelJobs?: number;

package/dist/runtime/engine/nanosdk.js

@@ -28,6 +28,24 @@ export function requireProcessInstanceKey(key) {
     }
     return String(key);
 }
+/** Map the engine's process-instance `state` onto the transport-agnostic
+ *  {@link ProcessInstanceState} union, or `undefined` for an unrecognized value
+ *  (which the caller skips rather than mis-reconciling). Case-insensitive so a
+ *  future casing tweak on the engine side doesn't silently drop instances. */
+export function normalizeProcessInstanceState(raw) {
+    if (typeof raw !== "string")
+        return undefined;
+    switch (raw.toUpperCase()) {
+        case "ACTIVE":
+            return "ACTIVE";
+        case "COMPLETED":
+            return "COMPLETED";
+        case "TERMINATED":
+            return "TERMINATED";
+        default:
+            return undefined;
+    }
+}
 /**
  * An `EngineClient` backed entirely by a `@nanobpm/nano-sdk` client. Deploy, create,
  * message, and user-task calls map one-to-one onto the SDK's client methods; workers
@@ -101,6 +119,37 @@ export class SdkEngineClient {
     async completeUserTask(userTaskKey, variables) {
         await this.client.completeUserTask({ userTaskKey, variables: variables ?? {} });
     }
+    async searchProcessInstances(filter) {
+        const f = {};
+        if (filter?.state)
+            f.state = filter.state;
+        const keys = filter?.processInstanceKeys?.filter((k) => k != null && k !== "");
+        if (keys && keys.length > 0)
+            f.processInstanceKey = { $in: keys };
+        // A process-instance search is an eventually consistent read; ask for zero-wait
+        // consistency so it reflects what is currently visible without blocking. Cap the page
+        // to the number of keys asked for (each key matches at most one instance), so a bounded
+        // reconcile query never silently truncates on the API's default page size.
+        const page = keys && keys.length > 0 ? { limit: keys.length } : undefined;
+        const body = await this.client.searchProcessInstances({ filter: f, ...(page ? { page } : {}) }, { consistency: { waitUpToMs: 0 } });
+        const items = Array.isArray(body.items) ? body.items.filter(isRecord) : [];
+        return items.flatMap((it) => {
+            const key = it.processInstanceKey;
+            if (key == null || key === "") {
+                this.log("warn", "skipping process instance with no key in engine response");
+                return [];
+            }
+            const state = normalizeProcessInstanceState(it.state);
+            if (!state) {
+                this.log("warn", "skipping process instance with unrecognized state", {
+                    processInstanceKey: String(key),
+                    state: String(it.state),
+                });
+                return [];
+            }
+            return [{ processInstanceKey: String(key), state }];
+        });
+    }
     async registerWorker(jobType, handler, options) {
         const worker = this.client.createJobWorker({
             jobType,
@@ -120,9 +169,9 @@ export class SdkEngineClient {
                     elementId: job.elementId,
                     variables: job.variables ?? {},
                 };
+                let out;
                 try {
-                    const out = await handler(engineJob);
-                    return await job.complete(out ?? {});
+                    out = await handler(engineJob);
                 }
                 catch (err) {
                     // A handler-raised BPMN error is a modelled, non-retryable outcome:
@@ -152,17 +201,51 @@ export class SdkEngineClient {
                         }
                     }
                     const message = err instanceof Error ? err.message : String(err);
-                    this.log("error", `handler ${jobType} threw`, { err: message });
+                    this.log("error", `handler ${jobType} threw`, {
+                        err: message,
+                        jobKey: engineJob.jobKey,
+                        processInstanceKey: engineJob.processInstanceKey,
+                        elementId: engineJob.elementId,
+                    });
                     try {
-                        // Best-effort failure report; the engine redelivers after the lock
-                        // times out (at-least-once → handlers must be idempotent). Await +
-                        // swallow so a rejected `fail` cannot escape as an unhandled rejection.
-                        return await job.fail({ errorMessage: message.slice(0, 500), retries: 0 });
+                        // A generic handler failure omits the retry count so the SDK decrements the job's
+                        // remaining retries (`job.retries - 1`): a transient failure (e.g. a fleeting store
+                        // error) self-heals on redelivery and only parks as an incident once the budget is
+                        // exhausted. A `BpmnError` reaching here (no `job.error()` transport, or the error
+                        // report itself threw) is the exception: it is a modelled, DETERMINISTIC outcome, so
+                        // retrying would re-throw the same error and burn the budget for nothing — pin
+                        // `retries: 0` to keep it non-retryable. Await + swallow so a rejected `fail` cannot
+                        // escape as an unhandled rejection.
+                        const body = {
+                            errorMessage: message.slice(0, 500),
+                        };
+                        if (isBpmnError(err))
+                            body.retries = 0;
+                        return await job.fail(body);
                     }
                     catch {
                         return undefined;
                     }
                 }
+                // The handler resolved: its work is done. Reporting that result to the engine
+                // (`complete`) is a SEPARATE concern — a failure here is a transport/engine problem
+                // (e.g. a transient store error), NOT a handler bug. Failing it (even with a decrementing
+                // retry) would burn the job's retry budget for a completion we can't confirm didn't land.
+                // Instead, log and leave the job locked so the engine redelivers it on lock timeout;
+                // handlers are idempotent (at-least-once), so a redelivery re-completes cleanly.
+                try {
+                    return await job.complete(out ?? {});
+                }
+                catch (completeErr) {
+                    const message = completeErr instanceof Error ? completeErr.message : String(completeErr);
+                    this.log("error", `complete ${jobType} failed; leaving job for engine redelivery`, {
+                        err: message,
+                        jobKey: engineJob.jobKey,
+                        processInstanceKey: engineJob.processInstanceKey,
+                        elementId: engineJob.elementId,
+                    });
+                    return undefined;
+                }
             },
         });
         // The nano-sdk job worker owns its own start lifecycle: `createJobWorker` runs

package/dist/runtime/index.d.ts

@@ -17,8 +17,12 @@ export { makeGateway, Table } from "./core/modules/gateway.ts";
 export type { ColumnMeta, DataSource as GatewayDataSource, ExecResult, ForeignKeyMeta, Row, TableMeta, } from "./core/modules/gateway.ts";
 export { createPagesRoutes, mountPages } from "./core/modules/pages.ts";
 export type { PagesDataSource, PagesDeps, PagesHandle, PagesOptions } from "./core/modules/pages.ts";
+export { cancelInstanceReconciling } from "./core/modules/cancel.ts";
+export type { CancelInstanceResult, CancelInstanceState } from "./core/modules/cancel.ts";
 export { mountActions, resolveActionHandler } from "./core/modules/actions.ts";
 export type { ActionHandler, ActionRequest, ActionResult, ActionsHandle } from "./core/modules/actions.ts";
+export { defineOperation, mountApi, resolveOperationHandler } from "./core/modules/api.ts";
+export type { ApiBinding, ApiHandle, DefaultContract, OperationContract, OperationHandler, OperationInput, OperationResult, } from "./core/modules/api.ts";
 export type { AppJobHandler } from "./core/modules/workers.ts";
 export { resolveHandler, sdkDecisionEvaluator } from "./core/modules/workers.ts";
 export { buildMessages, callLlm, resolveProvider, runLlmJob, } from "./core/modules/llm.ts";

package/dist/runtime/index.js

@@ -15,7 +15,9 @@ export { DataLayer, TypeRepo } from "./core/modules/datasource.js";
 export { runDataOp } from "./core/modules/dataops.js";
 export { makeGateway, Table } from "./core/modules/gateway.js";
 export { createPagesRoutes, mountPages } from "./core/modules/pages.js";
+export { cancelInstanceReconciling } from "./core/modules/cancel.js";
 export { mountActions, resolveActionHandler } from "./core/modules/actions.js";
+export { defineOperation, mountApi, resolveOperationHandler } from "./core/modules/api.js";
 export { resolveHandler, sdkDecisionEvaluator } from "./core/modules/workers.js";
 export { buildMessages, callLlm, resolveProvider, runLlmJob, } from "./core/modules/llm.js";
 export { evalCorrelation } from "./core/modules/triggers.js";

package/dist/toolkit/artifact.d.ts

@@ -17,3 +17,8 @@ export interface Deriver<I> {
 export declare const GENERATED_DIR = "nano-generated";
 /** Stable ordering so artifact lists compare deterministically. */
 export declare function sortArtifacts(a: DerivedArtifact[]): DerivedArtifact[];
+/** True when `p` is an absolute path — POSIX root (`/`), a drive-letter root (`C:\` or `C:/`), or a
+ *  Windows UNC/drive-root backslash (`\`). The single source of truth for the absolute-path rule,
+ *  shared by the toolkit's path join (gen.ts) and the runtime's resolveAppPath so both agree on
+ *  whether a manifest path is app-root-relative or absolute (no gen/runtime drift). */
+export declare function isAbsolutePath(p: string): boolean;

package/dist/toolkit/artifact.js

@@ -9,3 +9,10 @@ export const GENERATED_DIR = "nano-generated";
 export function sortArtifacts(a) {
     return [...a].sort((x, y) => (x.path < y.path ? -1 : x.path > y.path ? 1 : 0));
 }
+/** True when `p` is an absolute path — POSIX root (`/`), a drive-letter root (`C:\` or `C:/`), or a
+ *  Windows UNC/drive-root backslash (`\`). The single source of truth for the absolute-path rule,
+ *  shared by the toolkit's path join (gen.ts) and the runtime's resolveAppPath so both agree on
+ *  whether a manifest path is app-root-relative or absolute (no gen/runtime drift). */
+export function isAbsolutePath(p) {
+    return /^(\/|\\|[A-Za-z]:[/\\])/.test(p);
+}

package/dist/toolkit/derivers/api.d.ts

@@ -0,0 +1,19 @@
+import type { DerivedArtifact, Deriver } from "../artifact.ts";
+import { type OpenApiDoc, type OpenApiSchema } from "../../openapi/spec.ts";
+/** Filenames of the emitted artifacts (siblings of worker-io.d.ts in nano-generated/). */
+export declare const API_BINDINGS_DTS = "api-io.d.ts";
+export declare const API_BINDINGS_TS = "operations.ts";
+/** Render a JSON-Schema (OpenAPI subset) as a TS type expression. Local component `$ref`s render as
+ *  their component name (emitted as named interfaces); unknown shapes fall back to `unknown`. */
+export declare function schemaToTs(schema: OpenApiSchema | undefined, depth?: number): string;
+/** Emit `api-io.d.ts`: named component types + per-operation Request/Response + the id union. */
+export declare function emitApiBindings(doc: OpenApiDoc): string;
+/** Emit `operations.ts`: the typed `defineOperation` wrapper, keyed by operationId (mirrors the
+ *  generated typed `defineWorker`). Written verbatim (it never changes with the spec) — it only
+ *  re-types the runtime's `defineOperation`. */
+export declare function emitApiBindingsRuntime(): string;
+/** Derive the api artifacts from a parsed OpenAPI document. */
+export declare function deriveApi(doc: OpenApiDoc): DerivedArtifact[];
+export declare const apiDeriver: Deriver<{
+    doc: OpenApiDoc;
+}>;

package/dist/toolkit/derivers/api.js

@@ -0,0 +1,224 @@
+// Deriver: an OpenAPI document → `api-io.d.ts` (the endpoint type map) + `operations.ts` (the typed
+// `defineOperation` wrapper). ADR 0058: the contract-first endpoint surface. This is the authoring
+// half — per `operationId` it emits a `Request`/`Response` type from the operation's parameters,
+// requestBody, and first success response, plus an `ApiOperationId` union — mirroring how
+// `worker-io.d.ts` types `defineWorker` from the model (ADR 0033 §3). The runtime
+// (`runtime/core/modules/api.ts`) is the matching half: it validates + routes from the SAME spec via
+// the shared `openapi/spec.ts`, so types and runtime never drift.
+import { GENERATED_DIR } from "../artifact.js";
+import { collectOperations, isObjectSchema, refName, } from "../../openapi/spec.js";
+/** Filenames of the emitted artifacts (siblings of worker-io.d.ts in nano-generated/). */
+export const API_BINDINGS_DTS = "api-io.d.ts";
+export const API_BINDINGS_TS = "operations.ts";
+/** A TS identifier form of an operationId (used for the per-op type names). */
+function typeStem(operationId) {
+    const cleaned = operationId.replace(/[^A-Za-z0-9]+/g, " ").trim();
+    const pascal = cleaned
+        .split(/\s+/)
+        .map((w) => (w.length > 0 ? w[0].toUpperCase() + w.slice(1) : ""))
+        .join("");
+    return /^[A-Za-z_]/.test(pascal) ? pascal : `Op${pascal}`;
+}
+/** Render a JSON-Schema (OpenAPI subset) as a TS type expression. Local component `$ref`s render as
+ *  their component name (emitted as named interfaces); unknown shapes fall back to `unknown`. */
+export function schemaToTs(schema, depth = 0) {
+    if (!schema || depth > 20)
+        return "unknown";
+    if (schema.$ref) {
+        const name = refName(schema.$ref);
+        return name ? typeStem(name) : "unknown";
+    }
+    const nullable = schema.nullable === true;
+    const wrap = (t) => (nullable ? `${t} | null` : t);
+    if (Array.isArray(schema.enum) && schema.enum.length > 0) {
+        return wrap(schema.enum.map((v) => JSON.stringify(v)).join(" | "));
+    }
+    if (schema.const !== undefined)
+        return wrap(JSON.stringify(schema.const));
+    if (Array.isArray(schema.oneOf) && schema.oneOf.length > 0) {
+        return wrap(schema.oneOf.map((s) => schemaToTs(s, depth + 1)).join(" | "));
+    }
+    if (Array.isArray(schema.anyOf) && schema.anyOf.length > 0) {
+        return wrap(schema.anyOf.map((s) => schemaToTs(s, depth + 1)).join(" | "));
+    }
+    if (Array.isArray(schema.allOf) && schema.allOf.length > 0) {
+        return wrap(schema.allOf.map((s) => schemaToTs(s, depth + 1)).join(" & "));
+    }
+    switch (schema.type) {
+        case "string":
+            return wrap("string");
+        case "integer":
+        case "number":
+            return wrap("number");
+        case "boolean":
+            return wrap("boolean");
+        case "null":
+            return "null";
+        case "array":
+            return wrap(`Array<${schemaToTs(schema.items, depth + 1)}>`);
+        case "object":
+            return wrap(objectToTs(schema, depth));
+        default:
+            // No `type`: infer object-ness from object-only keywords (shared with the runtime
+            // validator via isObjectSchema so types and validation agree); otherwise unknown.
+            if (isObjectSchema(schema))
+                return wrap(objectToTs(schema, depth));
+            return "unknown";
+    }
+}
+function objectToTs(schema, depth) {
+    const props = schema.properties ?? {};
+    const required = new Set(schema.required ?? []);
+    const entries = Object.entries(props).map(([key, ps]) => {
+        const opt = required.has(key) ? "" : "?";
+        const doc = typeof ps.description === "string" ? ps.description.replace(/\*\//g, "*\\/") : undefined;
+        const jsdoc = doc ? `/** ${doc} */ ` : "";
+        return `${jsdoc}${JSON.stringify(key)}${opt}: ${schemaToTs(ps, depth + 1)}`;
+    });
+    const extra = schema.additionalProperties;
+    if (extra && typeof extra === "object") {
+        // TS requires every named property type to be assignable to the index signature. When the
+        // schema also declares properties, a narrow index type (e.g. `number`) would make the emitted
+        // type invalid (TS2411), so fall back to `unknown`; with no declared properties we can use the
+        // precise additionalProperties type (the common "map" case).
+        const hasProps = Object.keys(props).length > 0;
+        entries.push(`[key: string]: ${hasProps ? "unknown" : schemaToTs(extra, depth + 1)}`);
+    }
+    else if (extra !== false) {
+        // OpenAPI/JSON-Schema default: additional properties are allowed. Emit an index
+        // signature so the emitted type isn't stricter than the runtime validator, which only
+        // rejects extras when additionalProperties === false (otherwise excess-property errors
+        // on object literals would reject bodies the runtime accepts).
+        entries.push("[key: string]: unknown");
+    }
+    if (entries.length > 0)
+        return `{ ${entries.join("; ")} }`;
+    // No declared properties and additionalProperties: false → a closed, empty object.
+    return "Record<string, never>";
+}
+/** The `params`/`query` object type for an operation, from its parameters (strings on the wire). */
+function paramsTs(op, where) {
+    const ps = op.parameters.filter((p) => p.in === where);
+    if (ps.length === 0)
+        return "{}";
+    const fields = ps.map((p) => {
+        const opt = p.required ? "" : "?";
+        // Query values arrive as strings (or string[] for repeated keys); path params are single
+        // strings. Optionality is carried by the `?` modifier — don't fold `undefined` into the
+        // value type, or required query params would still accept undefined.
+        const t = where === "query" ? "string | string[]" : "string";
+        return `${JSON.stringify(p.name)}${opt}: ${t}`;
+    });
+    return `{ ${fields.join("; ")} }`;
+}
+/** Emit `api-io.d.ts`: named component types + per-operation Request/Response + the id union. */
+export function emitApiBindings(doc) {
+    const ops = collectOperations(doc);
+    const components = doc.components?.schemas ?? {};
+    // Fail-closed on TypeScript name collisions: typeStem is lossy (non-alphanumerics collapse), so
+    // distinct component/operation names ("get-invoice" vs "get_invoice") can map to the same TS
+    // identifier and emit duplicate declarations that break typechecking. Surface it here (where
+    // `urban gen`/`urban check` reports it) rather than shipping broken generated types.
+    const emittedTypeNames = new Map();
+    const claimTypeName = (typeName, source) => {
+        const prior = emittedTypeNames.get(typeName);
+        if (prior !== undefined) {
+            throw new Error(`OpenAPI spec produces a duplicate TypeScript type "${typeName}" from ${prior} and ${source} ` +
+                `— their names collapse to the same identifier; rename one to disambiguate (ADR 0058).`);
+        }
+        emittedTypeNames.set(typeName, source);
+    };
+    for (const name of Object.keys(components)) {
+        claimTypeName(typeStem(name), `component schema "${name}"`);
+    }
+    for (const op of ops) {
+        claimTypeName(`${typeStem(op.operationId)}Request`, `operationId "${op.operationId}"`);
+        claimTypeName(`${typeStem(op.operationId)}Response`, `operationId "${op.operationId}"`);
+    }
+    const header = "// AUTO-GENERATED by @nanobpm/urban from the app's OpenAPI spec (ADR 0058).\n" +
+        "// The endpoint type map: each operationId maps to its typed request (path/query params +\n" +
+        "// JSON body) and success response, derived from the spec. Do not edit — regenerated from\n" +
+        "// the spec; erased to plain JS at compile.\n" +
+        "// eslint-disable\n\n";
+    const componentDecls = Object.entries(components)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([name, schema]) => `export type ${typeStem(name)} = ${schemaToTs(schema)};`)
+        .join("\n");
+    const opDecls = ops
+        .map((op) => {
+        const stem = typeStem(op.operationId);
+        // With a schema → the typed body. Required but no JSON schema → `unknown` (a body IS
+        // required at runtime, just of an unknown shape). Otherwise (optional, absent) → `undefined`.
+        const bodyType = op.requestBodySchema
+            ? schemaToTs(op.requestBodySchema)
+            : op.requestBodyRequired
+                ? "unknown"
+                : "undefined";
+        // An optional (or absent) request body is passed to the delegate as `undefined` at runtime,
+        // so mark it optional in the type rather than forcing handlers to treat it as always-present.
+        const bodyOpt = op.requestBodyRequired ? "" : "?";
+        const resp = op.responseSchema ? schemaToTs(op.responseSchema) : "unknown";
+        const summary = op.summary ? `/** ${op.summary.replace(/\*\//g, "*\\/")} */\n` : "";
+        return (`${summary}export interface ${stem}Request {\n` +
+            `  params: ${paramsTs(op, "path")};\n` +
+            `  query: ${paramsTs(op, "query")};\n` +
+            `  body${bodyOpt}: ${bodyType};\n` +
+            `}\n` +
+            `export type ${stem}Response = ${resp};`);
+    })
+        .join("\n\n");
+    const idUnion = ops.length > 0
+        ? ops.map((o) => JSON.stringify(o.operationId)).join(" | ")
+        : "never";
+    const mapEntries = ops
+        .map((op) => {
+        const stem = typeStem(op.operationId);
+        return `  ${JSON.stringify(op.operationId)}: { request: ${stem}Request; response: ${stem}Response };`;
+    })
+        .join("\n");
+    return (header +
+        (componentDecls ? `${componentDecls}\n\n` : "") +
+        (opDecls ? `${opDecls}\n\n` : "") +
+        `/** Every declared operationId (ADR 0058): the delegate key set. */\n` +
+        `export type ApiOperationId = ${idUnion};\n\n` +
+        `/** Request/response contract per operationId. */\n` +
+        `export interface ApiOperations {\n${mapEntries}\n}\n`);
+}
+/** Emit `operations.ts`: the typed `defineOperation` wrapper, keyed by operationId (mirrors the
+ *  generated typed `defineWorker`). Written verbatim (it never changes with the spec) — it only
+ *  re-types the runtime's `defineOperation`. */
+export function emitApiBindingsRuntime() {
+    return ("// AUTO-GENERATED by @nanobpm/urban (ADR 0058): the typed `defineOperation`.\n" +
+        "// Re-exports the operation SDK and overrides `defineOperation` with an operationId-keyed\n" +
+        "// signature (the delegate's validated request + result typed from the spec). Erased to a\n" +
+        "// pass-through at runtime. Do not edit.\n" +
+        "// eslint-disable\n\n" +
+        `import { defineOperation as defineOperationRaw } from "@nanobpm/urban";\n` +
+        `import type { OperationHandler } from "@nanobpm/urban";\n` +
+        `import type { ApiOperationId, ApiOperations } from "./${API_BINDINGS_DTS}";\n\n` +
+        `type ReqFor<K extends ApiOperationId> = ApiOperations[K]["request"];\n` +
+        `type ResFor<K extends ApiOperationId> = ApiOperations[K]["response"];\n\n` +
+        `/**\n` +
+        ` * Typed \`defineOperation\`: \`id\` is constrained to the spec's declared operationIds\n` +
+        ` * (ADR 0058) so it autocompletes and rejects unknown ops, and the handler's request\n` +
+        ` * (validated params/query/body) + result are typed from the operation's schemas.\n` +
+        ` */\n` +
+        `export function defineOperation<K extends ApiOperationId>(\n` +
+        `  id: K,\n` +
+        `  handler: OperationHandler<ReqFor<K>, ResFor<K>>,\n` +
+        `): OperationHandler<ReqFor<K>, ResFor<K>> {\n` +
+        `  return defineOperationRaw(id, handler);\n` +
+        `}\n`);
+}
+/** Derive the api artifacts from a parsed OpenAPI document. */
+export function deriveApi(doc) {
+    return [
+        { path: `${GENERATED_DIR}/${API_BINDINGS_DTS}`, content: emitApiBindings(doc) },
+        { path: `${GENERATED_DIR}/${API_BINDINGS_TS}`, content: emitApiBindingsRuntime() },
+    ];
+}
+export const apiDeriver = {
+    id: "openapi->api-io",
+    describe: "Derive api-io.d.ts (typed request/response per operationId) + the typed defineOperation.",
+    derive: ({ doc }) => deriveApi(doc),
+};

package/dist/toolkit/gen.js

@@ -2,17 +2,28 @@
 // models, runs the pure derivers, and either writes the artifacts to disk (`urban gen`) or
 // compares them against what's on disk and reports drift (`urban gen --check`). The derivers stay
 // pure; all IO is confined here behind a tiny FS port so the same code runs on Node and Deno.
-import { sortArtifacts } from "./artifact.js";
+import { isAbsolutePath, sortArtifacts } from "./artifact.js";
 import { deriveMigrations } from "./derivers/migrations.js";
 import { deriveDomain } from "./derivers/domain.js";
 import { deriveWorkerBindings } from "./derivers/worker-io.js";
 import { deriveMeta } from "./derivers/meta.js";
 import { deriveMessageBindings } from "./derivers/messages.js";
+import { deriveApi } from "./derivers/api.js";
+import { parseSpec } from "../openapi/spec.js";
 import { deriveModels, MODEL_PROVENANCE } from "./models.js";
 function join(root, rel) {
-    // Trim either separator so callers may pass Windows-style paths; GenIO
-    // implementations accept forward slashes on all platforms.
-    return `${root.replace(/[/\\]+$/, "")}/${rel.replace(/^[/\\]+/, "")}`;
+    // Normalize Windows-style separators to forward slashes (GenIO uses forward slashes on all
+    // platforms — matching the runtime's resolveAppPath) and trim edge separators, so callers may
+    // pass either style without gen/runtime drift over where a file resolves.
+    const norm = (s) => s.replace(/\\/g, "/");
+    // An absolute `rel` resolves to itself — never prefixed with `root` — mirroring the runtime's
+    // resolveAppPath (isAbsolutePath is the shared SoT in artifact.ts). Without this an absolute
+    // manifest path (e.g. "/abs/openapi.json") would be stripped to root-relative and gen would
+    // read/derive a different file than the runtime resolves. Trailing edge separators are still
+    // trimmed for stable, comparable artifact keys.
+    if (isAbsolutePath(rel))
+        return norm(rel).replace(/\/+$/, "");
+    return `${norm(root).replace(/\/+$/, "")}/${norm(rel).replace(/^\/+/, "")}`;
 }
 function dirOf(p) {
     const i = p.lastIndexOf("/");
@@ -81,6 +92,14 @@ async function collectAll(opts) {
             artifacts.push(...deriveMessageBindings(models, declaredTypeIds));
         }
     }
+    // 4. OpenAPI `api` binding → typed endpoint contracts (ADR 0058). Fail-closed: a declared spec
+    //    that is missing or malformed throws here so `urban gen`/`urban check` surfaces it. Trim the
+    //    spec path so benign whitespace matches the runtime's readApiBinding (no gen/runtime drift).
+    const specRef = typeof manifest.api?.spec === "string" ? manifest.api.spec.trim() : "";
+    if (!opts.modelsOnly && specRef.length > 0) {
+        const specText = await io.readText(join(root, specRef));
+        artifacts.push(...deriveApi(parseSpec(specText)));
+    }
     return { artifacts: sortArtifacts(artifacts), derived };
 }
 /** Run the derivers and write artifacts (or, with `check`, report drift without writing). */

package/dist/toolkit/index.d.ts

@@ -13,6 +13,9 @@ export { deriveMeta, emitMeta, foldMeta, metaDeriver, scanModelMeta, META_TS, }
 export type { MetaDecl } from "./derivers/meta.ts";
 export { deriveMessageBindings, emitMessageBindings, emitMessageBindingsRuntime, messagesDeriver, scanModelMessages, MESSAGE_BINDINGS_DTS, MESSAGE_BINDINGS_TS, } from "./derivers/messages.ts";
 export type { MessageIo, MessageBindingDecl } from "./derivers/messages.ts";
+export { apiDeriver, deriveApi, emitApiBindings, emitApiBindingsRuntime, schemaToTs, API_BINDINGS_DTS, API_BINDINGS_TS, } from "./derivers/api.ts";
+export { collectOperations, HTTP_METHODS, isSafeOperationId, operationsWithoutId, operationsWithUnsafeId, parseSpec, refName, resolveSchema, toRouteMatcher, undeclaredPathParams, validateValue, } from "../openapi/spec.ts";
+export type { HttpMethodLower, OpenApiDoc, OpenApiParameter, OpenApiSchema, OperationInfo, } from "../openapi/spec.ts";
 export declare const DERIVERS: readonly [import("./artifact.ts").Deriver<import("./derivers/migrations.ts").ToolkitManifest>, import("./artifact.ts").Deriver<import("./derivers/migrations.ts").ToolkitManifest>, import("./artifact.ts").Deriver<{
     models: import("./derivers/worker-io.ts").ModelSource[];
     declaredTypeIds: Iterable<string>;
@@ -21,6 +24,8 @@ export declare const DERIVERS: readonly [import("./artifact.ts").Deriver<import(
 }>, import("./artifact.ts").Deriver<{
     models: import("./derivers/worker-io.ts").ModelSource[];
     declaredTypeIds: Iterable<string>;
+}>, import("./artifact.ts").Deriver<{
+    doc: import("../openapi/spec.ts").OpenApiDoc;
 }>];
 export { collectArtifacts, runGen, joinPath, readModels, expandPattern, previewModels } from "./gen.ts";
 export type { GenIO, GenOptions, GenResult } from "./gen.ts";