@nanobpm/urban 0.29.0 → 0.31.0

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

@@ -16,6 +16,7 @@
 //   POST /app/actions/message                       → engine.publishMessage
 import { errorMessage, isRecord } from "../guards.js";
 import { html, json } from "../router.js";
+import { cancelInstanceReconciling } from "./cancel.js";
 import { quoteIdent } from "./gateway.js";
 /** A JavaScript-body response (the renderer module served at /app/runtime.js). */
 function javascript(body, status = 200) {
@@ -34,7 +35,7 @@ export function createPagesRoutes(opts, deps) {
     const rowLimitRaw = opts.rowLimit ?? 200;
     const rowLimit = Number.isFinite(rowLimitRaw) ? Math.max(0, Math.floor(rowLimitRaw)) : 200;
     const sourceName = opts.sourceName ?? "app";
-    const { db, engine, readPage, listPages } = deps;
+    const { db, engine, readPage, listPages, cancel } = deps;
     // The table-name whitelist is memoised: an Urban app runs its migrations at boot
     // (before serving), so the schema is stable for the process lifetime, and the renderer
     // refreshes grids repeatedly — re-introspecting on every `/app/data` hit would be a hot
@@ -257,6 +258,19 @@ export function createPagesRoutes(opts, deps) {
             }
             if (key === undefined || key === "")
                 return json({ error: "processInstanceKey is required" }, 400);
+            // The reconcile-aware primitive verifies the real post-cancel state and flips the tracked
+            // row immediately; a !ok result means the engine did NOT stop the instance, so surface 502.
+            if (cancel) {
+                try {
+                    const result = await cancel(String(key));
+                    return json(result, result.ok ? 200 : 502);
+                }
+                catch (e) {
+                    // Defensive: the primitive is designed not to throw, but if it ever does, mirror the
+                    // fallback path's honest 502 rather than letting the request reject as a 500.
+                    return json({ ok: false, processInstanceKey: String(key), error: errorMessage(e) }, 502);
+                }
+            }
             try {
                 await engine.cancelInstance({ processInstanceKey: String(key) });
                 return json({ ok: true });
@@ -323,9 +337,11 @@ export function mountPages(ctx, app) {
         sourceName: typeof decl.sourceName === "string" ? decl.sourceName : undefined,
     };
     const sourceName = opts.sourceName ?? "app";
+    const bindings = ctx.manifest.instanceTracking ?? [];
     const routes = createPagesRoutes(opts, {
         db: app.data.open(sourceName),
         engine: app.engine,
+        cancel: (key) => cancelInstanceReconciling(app, bindings, key),
         readPage: (p) => ctx.host.readTextFile(p),
         listPages: async () => {
             const dir = opts.pagesDir ?? "pages";
@@ -564,12 +580,20 @@ function renderText(node) {
   return el(v === "heading" ? "h1" : "p", { class: cls }, node.props.text || "");
 }
 
-// A grid td cell. When the column declares linkField, the cell text (the
-// column's own value) becomes a link to the URL held in that other field,
-// opened in a new tab. Only http(s) hrefs are linked — anything else (e.g. a
-// javascript: URL smuggled through row data) falls back to plain text — and
-// external links get rel=noopener noreferrer so the opened page can't reach
-// window.opener. Shared by the top-level grid and child grids.
+// A grid td cell. Two column-declared linking modes, checked in order:
+//   1. linkField — the cell text becomes a link to the URL held in that other
+//      field. Only http(s) hrefs are linked (a javascript:/other-scheme URL
+//      smuggled through row data falls back to plain text).
+//   2. link: { kind: "processExplorer", keyField } — a structured, engine-aware
+//      link: the cell text links to the Nano console's explorer view for the
+//      process instance whose key is held in the row's keyField. The console
+//      path is constructed HERE (never taken from row data) and the key is
+//      URL-encoded, so row data can't smuggle a path or scheme; only a
+//      non-empty key (after trimming surrounding whitespace) produces a link.
+//      Unknown link kinds fall back to plain text so an unrecognised schema
+//      can't render a broken anchor.
+// Both open in a new tab with rel=noopener noreferrer so the opened page can't
+// reach window.opener. Shared by the top-level grid and child grids.
 function gridCell(col, row) {
   const text = row[col.field] == null ? "" : String(row[col.field]);
   if (col.linkField) {
@@ -582,6 +606,18 @@ function gridCell(col, row) {
       );
     }
   }
+  if (col.link && col.link.kind === "processExplorer" && col.link.keyField) {
+    const key = row[col.link.keyField];
+    const keyStr = key == null ? "" : String(key).trim();
+    if (text !== "" && keyStr !== "") {
+      const href = "/console/explorer?instance=" + encodeURIComponent(keyStr);
+      return el(
+        "td",
+        {},
+        el("a", { class: "pc-link", href, target: "_blank", rel: "noopener noreferrer" }, text),
+      );
+    }
+  }
   return el("td", {}, text);
 }
 

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

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

package/dist/runtime/engine/nanosdk.js

@@ -169,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:
@@ -201,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";

package/dist/toolkit/index.js

@@ -11,13 +11,24 @@ export { deriveWorkerBindings, emitWorkerBindings, emitWorkerBindingsRuntime, ov
 export { byModelPath, typeRefFor } from "./derivers/worker-io.js";
 export { deriveMeta, emitMeta, foldMeta, metaDeriver, scanModelMeta, META_TS, } from "./derivers/meta.js";
 export { deriveMessageBindings, emitMessageBindings, emitMessageBindingsRuntime, messagesDeriver, scanModelMessages, MESSAGE_BINDINGS_DTS, MESSAGE_BINDINGS_TS, } from "./derivers/messages.js";
+export { apiDeriver, deriveApi, emitApiBindings, emitApiBindingsRuntime, schemaToTs, API_BINDINGS_DTS, API_BINDINGS_TS, } from "./derivers/api.js";
+// The OpenAPI machinery the deriver + runtime share (ADR 0058).
+export { collectOperations, HTTP_METHODS, isSafeOperationId, operationsWithoutId, operationsWithUnsafeId, parseSpec, refName, resolveSchema, toRouteMatcher, undeclaredPathParams, validateValue, } from "../openapi/spec.js";
 // The registry of all derivers (for discovery / IDE migration).
 import { migrationsDeriver } from "./derivers/migrations.js";
 import { domainDeriver } from "./derivers/domain.js";
 import { workerIoDeriver } from "./derivers/worker-io.js";
 import { metaDeriver } from "./derivers/meta.js";
 import { messagesDeriver } from "./derivers/messages.js";
-export const DERIVERS = [migrationsDeriver, domainDeriver, workerIoDeriver, metaDeriver, messagesDeriver];
+import { apiDeriver } from "./derivers/api.js";
+export const DERIVERS = [
+    migrationsDeriver,
+    domainDeriver,
+    workerIoDeriver,
+    metaDeriver,
+    messagesDeriver,
+    apiDeriver,
+];
 // Gen orchestrator + IO
 export { collectArtifacts, runGen, joinPath, readModels, expandPattern, previewModels } from "./gen.js";
 export { createNodeGenIO } from "./fsio.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/urban",
-  "version": "0.29.0",
+  "version": "0.31.0",
   "description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
   "license": "Apache-2.0",
   "type": "module",