@nanobpm/urban 0.29.0 → 0.31.0

package/src/runtime/core/modules/pages.ts

@@ -19,6 +19,7 @@ import type { AppApi, RuntimeContext } from "../context.ts";
 import { errorMessage, isRecord } from "../guards.ts";
 import type { EngineClient } from "../host.ts";
 import { html, json, type Route } from "../router.ts";
+import { cancelInstanceReconciling, type CancelInstanceResult } from "./cancel.ts";
 import { quoteIdent } from "./gateway.ts";
 
 /** The subset of the datasource gateway the page runtime needs. */
@@ -49,6 +50,13 @@ export interface PagesDeps {
    * Optional; when absent the index is empty. Injectable for tests.
    */
   listPages?(): Promise<string[]>;
+  /**
+   * Cancel a process instance honestly: terminate it, verify it is actually gone, and reconcile
+   * any `instanceTracking` row bound to its key. Injected by `mountPages` (bound to the app's
+   * engine, datasource, and instanceTracking bindings). When absent, the `/app/actions/cancel`
+   * route falls back to a bare `engine.cancelInstance` (used by tests that inject no cancel dep).
+   */
+  cancel?(processInstanceKey: string): Promise<CancelInstanceResult>;
 }
 
 /** A JavaScript-body response (the renderer module served at /app/runtime.js). */
@@ -70,7 +78,7 @@ export function createPagesRoutes(opts: PagesOptions, deps: PagesDeps): Route[]
   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
@@ -285,6 +293,18 @@ export function createPagesRoutes(opts: PagesOptions, deps: PagesDeps): Route[]
         return json({ error: "body must be JSON" }, 400);
       }
       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 });
@@ -354,9 +374,11 @@ export function mountPages(ctx: RuntimeContext, app: AppApi): PagesHandle {
     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";
@@ -599,12 +621,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) {
@@ -617,6 +647,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/src/runtime/core/modules/surfaces.ts

@@ -6,6 +6,7 @@
 import type { AppApi, RuntimeContext } from "../context.ts";
 import { html, json, normalizeRoutePath, type Route } from "../router.ts";
 import { mountActions } from "./actions.ts";
+import { mountApi } from "./api.ts";
 import { mountPages } from "./pages.ts";
 
 /** Escape HTML-significant characters before embedding a value in markup. */
@@ -109,6 +110,15 @@ export function mountSurfaces(ctx: RuntimeContext, app: AppApi): SurfacesHandle
     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/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);
+});