@nanobpm/urban 0.28.0 → 0.30.0

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

@@ -2,6 +2,7 @@ import { test } from "node:test";
 import assert from "node:assert/strict";
 import {
   createNanoSdkEngineClient,
+  normalizeProcessInstanceState,
   requireProcessInstanceKey,
   SdkEngineClient,
   type NanoSdkActivatedJob,
@@ -66,6 +67,10 @@ function fakeSdkClient(overrides: Partial<NanoSdkClient> = {}): NanoSdkClient &
       calls.push("searchUserTasks");
       return { items: [] };
     },
+    async searchProcessInstances() {
+      calls.push("searchProcessInstances");
+      return { items: [] };
+    },
     async completeUserTask() {
       calls.push("completeUserTask");
       return {};
@@ -202,6 +207,74 @@ test("completeUserTask routes through the SDK", async () => {
   assert.deepEqual(seen, { userTaskKey: "utk", variables: { done: true } });
 });
 
+test("searchProcessInstances filters by keys ($in) + state with a matching page cap", async () => {
+  let seenInput: unknown;
+  let seenConsistency: unknown;
+  const client = fakeSdkClient({
+    searchProcessInstances: async (input, c) => {
+      seenInput = input;
+      seenConsistency = c;
+      return {
+        items: [
+          { processInstanceKey: 7, state: "TERMINATED" },
+          { processInstanceKey: "8", state: "ACTIVE" },
+        ],
+      };
+    },
+  });
+  const engine = new SdkEngineClient(client);
+  const out = await engine.searchProcessInstances({
+    processInstanceKeys: ["7", "8", ""], // empty key dropped from the $in
+    state: "TERMINATED",
+  });
+  assert.deepEqual(seenInput, {
+    filter: { state: "TERMINATED", processInstanceKey: { $in: ["7", "8"] } },
+    page: { limit: 2 },
+  });
+  assert.deepEqual(seenConsistency, { consistency: { waitUpToMs: 0 } });
+  assert.deepEqual(out, [
+    { processInstanceKey: "7", state: "TERMINATED" },
+    { processInstanceKey: "8", state: "ACTIVE" },
+  ]);
+});
+
+test("searchProcessInstances with no keys sends no key filter and no page cap", async () => {
+  let seenInput: unknown;
+  const client = fakeSdkClient({
+    searchProcessInstances: async (input) => {
+      seenInput = input;
+      return { items: [] };
+    },
+  });
+  const engine = new SdkEngineClient(client);
+  await engine.searchProcessInstances();
+  assert.deepEqual(seenInput, { filter: {} });
+});
+
+test("searchProcessInstances skips keyless and unrecognized-state rows", async () => {
+  const client = fakeSdkClient({
+    searchProcessInstances: async () => ({
+      items: [
+        { processInstanceKey: "", state: "TERMINATED" }, // keyless → skipped
+        { processInstanceKey: 9, state: "SUSPENDED" }, // unknown state → skipped
+        { processInstanceKey: 10, state: "completed" }, // case-insensitive → mapped
+      ],
+    }),
+  });
+  const engine = new SdkEngineClient(client);
+  const out = await engine.searchProcessInstances();
+  assert.deepEqual(out, [{ processInstanceKey: "10", state: "COMPLETED" }]);
+});
+
+test("normalizeProcessInstanceState maps the terminal set and rejects others", () => {
+  assert.equal(normalizeProcessInstanceState("ACTIVE"), "ACTIVE");
+  assert.equal(normalizeProcessInstanceState("completed"), "COMPLETED");
+  assert.equal(normalizeProcessInstanceState("Terminated"), "TERMINATED");
+  assert.equal(normalizeProcessInstanceState("SUSPENDED"), undefined);
+  assert.equal(normalizeProcessInstanceState(42), undefined);
+  assert.equal(normalizeProcessInstanceState(undefined), undefined);
+});
+
 test("registerWorker creates a worker the SDK auto-starts, and dispatches + completes", async () => {
   const client = fakeSdkClient();
   const engine = new SdkEngineClient(client);
@@ -266,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 () => {
@@ -303,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";
     },
@@ -318,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 () => {
@@ -327,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: {},
@@ -337,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";
     },
@@ -345,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

@@ -15,6 +15,8 @@ import type {
   EngineClient,
   EngineJob,
   JobHandler,
+  ProcessInstanceSnapshot,
+  ProcessInstanceState,
   WorkerSubscription,
 } from "../core/host.ts";
 import { isBpmnError } from "../core/host.ts";
@@ -30,6 +32,26 @@ export function requireProcessInstanceKey(key: string | number | null | undefine
   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: unknown,
+): ProcessInstanceState | undefined {
+  if (typeof raw !== "string") return undefined;
+  switch (raw.toUpperCase()) {
+    case "ACTIVE":
+      return "ACTIVE";
+    case "COMPLETED":
+      return "COMPLETED";
+    case "TERMINATED":
+      return "TERMINATED";
+    default:
+      return 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 {
@@ -103,6 +125,11 @@ export interface NanoSdkClient {
     input: { 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
@@ -213,6 +240,42 @@ export class SdkEngineClient implements EngineClient {
     await this.client.completeUserTask({ userTaskKey, variables: variables ?? {} });
   }
 
+  async searchProcessInstances(filter?: {
+    processInstanceKeys?: string[];
+    state?: ProcessInstanceState;
+  }): Promise<ProcessInstanceSnapshot[]> {
+    const f: Record<string, unknown> = {};
+    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: string,
     handler: JobHandler,
@@ -237,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
@@ -267,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);
+});