@nanobpm/urban 0.29.0 → 0.30.0

package/src/runtime/engine/nanosdk.test.ts

@@ -339,7 +339,41 @@ test("registerWorker fails the job when the handler throws", async () => {
   };
   await rec.dispatch(job);
   assert.equal(failBody?.errorMessage, "boom");
-  assert.equal(failBody?.retries, 0);
+  // No retry count is pinned: the SDK decrements the job's remaining retries
+  // (`job.retries - 1`), so a transient handler failure self-heals on redelivery and
+  // only parks as an incident once the budget is exhausted.
+  assert.equal(failBody?.retries, undefined);
+  assert.equal("retries" in (failBody ?? {}), false);
+});
+
+test("registerWorker leaves a job for redelivery when complete() fails (transport error, not a handler bug)", async () => {
+  const client = fakeSdkClient();
+  const engine = new SdkEngineClient(client);
+  let handlerRan = false;
+  await engine.registerWorker("svc", () => {
+    handlerRan = true;
+    return { ok: true };
+  });
+  const rec = client.workers[0];
+  let failCalled = false;
+  const job: NanoSdkActivatedJob = {
+    jobKey: "j1",
+    variables: {},
+    // The handler succeeded, but reporting the result to the engine fails transiently.
+    async complete() {
+      throw new Error("FOREIGN KEY constraint failed");
+    },
+    async fail() {
+      failCalled = true;
+      throw new Error("must not hard-park a job whose handler succeeded");
+    },
+  };
+  // Must not throw, and must NOT call fail(retries:0) — the job is left locked for the
+  // engine to redeliver on lock timeout.
+  const result = await rec.dispatch(job);
+  assert.equal(handlerRan, true);
+  assert.equal(failCalled, false);
+  assert.equal(result, undefined);
 });
 
 test("registerWorker routes a thrown BpmnError to the engine's error()", async () => {
@@ -376,14 +410,14 @@ test("registerWorker falls back to fail() for a BpmnError when the SDK has no er
     throw new BpmnError("NOT_FOUND", "no such record");
   });
   const rec = client.workers[0];
-  let failBody: { errorMessage: string } | undefined;
+  let failBody: { errorMessage: string; retries?: number } | undefined;
   const job: NanoSdkActivatedJob = {
     jobKey: "j1",
     variables: {},
     async complete() {
       throw new Error("should not complete");
     },
-    async fail(body: { errorMessage: string }) {
+    async fail(body: { errorMessage: string; retries?: number }) {
       failBody = body;
       return "failed";
     },
@@ -391,6 +425,9 @@ test("registerWorker falls back to fail() for a BpmnError when the SDK has no er
   };
   await rec.dispatch(job);
   assert.equal(failBody?.errorMessage, "no such record");
+  // A BpmnError is a modelled, deterministic outcome: pin retries:0 so it does NOT consume the
+  // retry budget (unlike a generic handler failure, which omits retries to self-heal).
+  assert.equal(failBody?.retries, 0);
 });
 
 test("registerWorker falls back to fail() when the BPMN error report itself throws", async () => {
@@ -400,7 +437,7 @@ test("registerWorker falls back to fail() when the BPMN error report itself thro
     throw new BpmnError("NOT_FOUND", "no such record");
   });
   const rec = client.workers[0];
-  let failBody: { errorMessage: string } | undefined;
+  let failBody: { errorMessage: string; retries?: number } | undefined;
   const job: NanoSdkActivatedJob = {
     jobKey: "j1",
     variables: {},
@@ -410,7 +447,7 @@ test("registerWorker falls back to fail() when the BPMN error report itself thro
     async error() {
       throw new Error("transport down");
     },
-    async fail(body: { errorMessage: string }) {
+    async fail(body: { errorMessage: string; retries?: number }) {
       failBody = body;
       return "failed";
     },
@@ -418,6 +455,9 @@ test("registerWorker falls back to fail() when the BPMN error report itself thro
   await rec.dispatch(job);
   // The job must still be acknowledged via fail() rather than silently dropped.
   assert.equal(failBody?.errorMessage, "no such record");
+  // A BpmnError is a modelled, deterministic outcome: pin retries:0 so it does NOT consume the
+  // retry budget (unlike a generic handler failure, which omits retries to self-heal).
+  assert.equal(failBody?.retries, 0);
 });
 
 test("close stops every worker and closes the SDK client", async () => {

package/src/runtime/engine/nanosdk.ts

@@ -300,9 +300,9 @@ export class SdkEngineClient implements EngineClient {
           elementId: job.elementId,
           variables: job.variables ?? {},
         };
+        let out: Record<string, unknown> | void;
         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:
           // report it as a BPMN error (routed to an error boundary/event) rather
@@ -330,16 +330,48 @@ export class SdkEngineClient implements EngineClient {
             }
           }
           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: string; retries?: number } = {
+              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/src/runtime/index.ts

@@ -83,8 +83,20 @@ export type {
 } 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 {

package/src/toolkit/artifact.ts

@@ -27,3 +27,11 @@ export const GENERATED_DIR = "nano-generated";
 export function sortArtifacts(a: DerivedArtifact[]): DerivedArtifact[] {
   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: string): boolean {
+  return /^(\/|\\|[A-Za-z]:[/\\])/.test(p);
+}

package/src/toolkit/derivers/api.test.ts

@@ -0,0 +1,219 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { deriveApi, emitApiBindings, emitApiBindingsRuntime, schemaToTs, API_BINDINGS_DTS, API_BINDINGS_TS } from "./api.ts";
+import type { OpenApiDoc } from "../../openapi/spec.ts";
+
+const doc: OpenApiDoc = {
+  openapi: "3.0.0",
+  components: {
+    schemas: {
+      Invoice: {
+        type: "object",
+        properties: { id: { type: "string" }, amount: { type: "integer" }, status: { type: "string", enum: ["draft", "sent"] } },
+        required: ["id", "amount"],
+      },
+    },
+  },
+  paths: {
+    "/invoices/{id}": {
+      get: {
+        operationId: "getInvoice",
+        summary: "Fetch one invoice",
+        parameters: [
+          { name: "id", in: "path", required: true, schema: { type: "string" } },
+          { name: "expand", in: "query", schema: { type: "string" } },
+        ],
+        responses: { "200": { content: { "application/json": { schema: { $ref: "#/components/schemas/Invoice" } } } } },
+      },
+    },
+  },
+};
+
+test("schemaToTs renders primitives, enums, arrays, refs, and unknown fallback", () => {
+  assert.equal(schemaToTs({ type: "string" }), "string");
+  assert.equal(schemaToTs({ type: "integer" }), "number");
+  assert.equal(schemaToTs({ type: "string", enum: ["a", "b"] }), '"a" | "b"');
+  assert.equal(schemaToTs({ type: "array", items: { type: "string" } }), "Array<string>");
+  assert.equal(schemaToTs({ $ref: "#/components/schemas/Invoice" }), "Invoice");
+  assert.equal(schemaToTs(undefined), "unknown");
+});
+
+test("emitApiBindings emits component types + per-op request/response + the id map", () => {
+  const out = emitApiBindings(doc);
+  assert.match(out, /export type Invoice = \{/);
+  assert.match(out, /export interface GetInvoiceRequest \{/);
+  assert.match(out, /params: \{ "id": string \}/);
+  assert.match(out, /export type GetInvoiceResponse = Invoice;/);
+  assert.match(out, /export type ApiOperationId = "getInvoice";/);
+  assert.match(out, /"getInvoice": \{ request: GetInvoiceRequest; response: GetInvoiceResponse \};/);
+});
+
+test("emitApiBindingsRuntime re-types the runtime defineOperation", () => {
+  const out = emitApiBindingsRuntime();
+  assert.match(out, /import \{ defineOperation as defineOperationRaw \} from "@nanobpm\/urban";/);
+  assert.match(out, /export function defineOperation<K extends ApiOperationId>/);
+  assert.match(out, /return defineOperationRaw\(id, handler\);/);
+});
+
+test("deriveApi emits both artifacts under nano-generated/", () => {
+  const arts = deriveApi(doc);
+  const paths = arts.map((a) => a.path).sort();
+  assert.deepEqual(paths, [`nano-generated/${API_BINDINGS_DTS}`, `nano-generated/${API_BINDINGS_TS}`]);
+});
+
+test("emitted object types mirror runtime additionalProperties semantics", () => {
+  // default (absent) → extras allowed at runtime, so the emitted type carries an index signature
+  assert.match(schemaToTs({ type: "object", properties: { a: { type: "string" } } }), /\[key: string\]: unknown/);
+  // additionalProperties: false → closed object, no index signature
+  assert.doesNotMatch(
+    schemaToTs({ type: "object", properties: { a: { type: "string" } }, additionalProperties: false }),
+    /\[key: string\]/,
+  );
+  // typed additionalProperties → typed index signature
+  assert.match(
+    schemaToTs({ type: "object", properties: {}, additionalProperties: { type: "number" } }),
+    /\[key: string\]: number/,
+  );
+  // a closed, empty object is Record<string, never>, not a loose Record<string, unknown>
+  assert.equal(schemaToTs({ type: "object", additionalProperties: false }), "Record<string, never>");
+});
+
+test("a typeless schema with properties is emitted as an object (matches the validator)", () => {
+  const out = schemaToTs({ properties: { a: { type: "string" } }, required: ["a"] });
+  assert.match(out, /"a": string/);
+  assert.match(out, /\[key: string\]: unknown/);
+});
+
+test("required query params aren't undefined-widened; optional ones use the ? modifier", () => {
+  const qdoc: OpenApiDoc = {
+    openapi: "3.0.0",
+    paths: {
+      "/search": {
+        get: {
+          operationId: "search",
+          parameters: [
+            { name: "q", in: "query", required: true, schema: { type: "string" } },
+            { name: "page", in: "query", schema: { type: "string" } },
+          ],
+          responses: { "200": {} },
+        },
+      },
+    },
+  };
+  const out = emitApiBindings(qdoc);
+  assert.match(out, /"q": string \| string\[\]/); // required → present, not optional
+  assert.doesNotMatch(out, /"q"\?:/); // not optional
+  assert.doesNotMatch(out, /"q": string \| string\[\] \| undefined/); // not undefined-widened
+  assert.match(out, /"page"\?: string \| string\[\]/); // optional → ? modifier
+});
+
+test("request body optionality follows requestBody.required (runtime passes undefined when absent)", () => {
+  const mk = (required: boolean): OpenApiDoc => ({
+    openapi: "3.0.0",
+    paths: {
+      "/n": {
+        post: {
+          operationId: "op",
+          requestBody: {
+            required,
+            content: { "application/json": { schema: { type: "object", properties: { text: { type: "string" } } } } },
+          },
+          responses: { "200": {} },
+        },
+      },
+    },
+  });
+  assert.match(emitApiBindings(mk(false)), /body\?: \{/); // optional body → `?`
+  const req = emitApiBindings(mk(true));
+  assert.match(req, /\n {2}body: \{/); // required body → no `?`
+  assert.doesNotMatch(req, /body\?:/);
+});
+
+test("typed additionalProperties alongside declared props falls back to unknown (valid TS, no TS2411)", () => {
+  // A narrow index type (number) would make `{ "a": string; [key: string]: number }` invalid TS,
+  // so with declared properties the index signature widens to unknown; a pure map keeps its type.
+  const withProps = schemaToTs({
+    type: "object",
+    properties: { a: { type: "string" } },
+    required: ["a"],
+    additionalProperties: { type: "number" },
+  });
+  assert.match(withProps, /"a": string/);
+  assert.match(withProps, /\[key: string\]: unknown/);
+  assert.doesNotMatch(withProps, /\[key: string\]: number/);
+  // No declared properties → precise map type is safe.
+  assert.match(
+    schemaToTs({ type: "object", additionalProperties: { type: "number" } }),
+    /\[key: string\]: number/,
+  );
+});
+
+test("a required body with no JSON schema is typed `unknown`, not `undefined`", () => {
+  const mk = (required: boolean): OpenApiDoc => ({
+    openapi: "3.0.0",
+    paths: {
+      "/n": {
+        post: {
+          operationId: "op",
+          // requestBody with no parseable JSON schema (e.g. unsupported content)
+          requestBody: { required, content: { "text/plain": {} } },
+          responses: { "200": {} },
+        },
+      },
+    },
+  });
+  assert.match(emitApiBindings(mk(true)), /\n {2}body: unknown;/); // required → body IS present
+  assert.match(emitApiBindings(mk(false)), /body\?: undefined;/); // optional/absent
+});
+
+test("request body types derive only from JSON media types (JSON-only surface)", () => {
+  const doc2: OpenApiDoc = {
+    openapi: "3.0.0",
+    paths: {
+      "/n": {
+        post: {
+          operationId: "op",
+          requestBody: {
+            required: true,
+            content: {
+              "application/xml": { schema: { type: "string" } }, // ignored
+              "application/vnd.acme+json": { schema: { type: "object", properties: { a: { type: "string" } } } },
+            },
+          },
+          responses: { "200": {} },
+        },
+      },
+    },
+  };
+  const out = emitApiBindings(doc2);
+  assert.match(out, /body: \{ "a"\?: string/); // picked the +json schema, not the xml string
+});
+
+test("emitApiBindings fails closed on operationIds that collapse to the same TS type name", () => {
+  const clash: OpenApiDoc = {
+    openapi: "3.0.0",
+    paths: {
+      "/a": { get: { operationId: "get-invoice", responses: { "200": {} } } },
+      "/b": { get: { operationId: "get_invoice", responses: { "200": {} } } },
+    },
+  };
+  assert.throws(() => emitApiBindings(clash), /duplicate TypeScript type "GetInvoiceRequest"/);
+});
+
+test("emitApiBindings fails closed on component schema names that collapse to the same TS type name", () => {
+  const clash: OpenApiDoc = {
+    openapi: "3.0.0",
+    components: { schemas: { "Foo-Bar": { type: "object" }, "Foo_Bar": { type: "object" } } },
+    paths: {},
+  };
+  assert.throws(() => emitApiBindings(clash), /duplicate TypeScript type "FooBar"/);
+});
+
+test("apiDeriver is registered in the DERIVERS discovery registry", async () => {
+  const { DERIVERS, apiDeriver } = await import("../index.ts");
+  assert.ok(DERIVERS.includes(apiDeriver), "apiDeriver must be in DERIVERS");
+  assert.ok(DERIVERS.some((d) => d.id === "openapi->api-io"));
+  // Registry hygiene: no deriver is registered twice and every id is unique.
+  const ids = DERIVERS.map((d) => d.id);
+  assert.equal(new Set(ids).size, ids.length);
+});

package/src/toolkit/derivers/api.ts

@@ -0,0 +1,255 @@
+// 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 type { DerivedArtifact, Deriver } from "../artifact.ts";
+import { GENERATED_DIR } from "../artifact.ts";
+import {
+  collectOperations,
+  isObjectSchema,
+  type OpenApiDoc,
+  type OpenApiSchema,
+  type OperationInfo,
+  refName,
+} from "../../openapi/spec.ts";
+
+/** 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: string): string {
+  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: OpenApiSchema | undefined, depth = 0): string {
+  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: string) => (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: OpenApiSchema, depth: number): string {
+  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: OperationInfo, where: "path" | "query"): string {
+  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: OpenApiDoc): string {
+  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<string, string>();
+  const claimTypeName = (typeName: string, source: string): void => {
+    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(): string {
+  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: OpenApiDoc): DerivedArtifact[] {
+  return [
+    { path: `${GENERATED_DIR}/${API_BINDINGS_DTS}`, content: emitApiBindings(doc) },
+    { path: `${GENERATED_DIR}/${API_BINDINGS_TS}`, content: emitApiBindingsRuntime() },
+  ];
+}
+
+export const apiDeriver: Deriver<{ doc: OpenApiDoc }> = {
+  id: "openapi->api-io",
+  describe: "Derive api-io.d.ts (typed request/response per operationId) + the typed defineOperation.",
+  derive: ({ doc }) => deriveApi(doc),
+};