@nanobpm/urban 0.35.0 → 0.36.0

package/src/runtime/core/modules/api.test.ts

@@ -5,7 +5,7 @@ import type { AppManifest } from "../manifest.ts";
 import type { EngineClient, HostContext, HttpRequest } from "../host.ts";
 import { makeRouter } from "../router.ts";
 import { DataLayer } from "./datasource.ts";
-import { mountApi, resolveOperationHandler, apiDocsPath, type ApiHandle, type OperationHandler } from "./api.ts";
+import { mountApi, resolveOperationHandler, apiDocsPath, NotImplemented, type ApiHandle, type OperationHandler } from "./api.ts";
 
 function req(
   method: string,
@@ -87,15 +87,17 @@ function build(
   modules: Record<string, Record<string, unknown>>,
   specText = spec,
   env: (v: string) => string | undefined = () => undefined,
+  existsPaths: string[] = [],
 ): Built {
   const imported: string[] = [];
   const logs: Array<{ level: string; msg: string }> = [];
+  const existsSet = new Set(existsPaths);
   const host: HostContext = {
     runtime: "node",
     env,
     readTextFile: async () => specText,
     listDir: async () => [],
-    exists: async () => false,
+    exists: async (p: string) => existsSet.has(p),
     openSqlite: () => {
       throw new Error("sqlite not used in this test");
     },
@@ -597,3 +599,103 @@ test("secured operation: an unset secret env fails closed with 500 (misconfigura
   assert.equal(res.status, 500);
   assert.ok(logs.some((l) => l.level === "error" && /security is misconfigured/.test(l.msg)));
 });
+
+// ── Generated controller registry (ADR 0059) ────────────────────────────────────────────────────
+// When `nano-generated/controller.ts` is present, dispatch resolves delegates from its exported
+// `operations` map (deterministic, drift-checked) instead of per-op path imports.
+
+test("controller present: dispatch uses the registry, not a per-op import", async () => {
+  const seen: unknown[] = [];
+  const handler: OperationHandler = (input) => {
+    seen.push(input.params);
+    return { status: 200, body: { ok: true } };
+  };
+  const { router, imported } = build(
+    { spec: "openapi.json" },
+    {
+      "/app/nano-generated/controller": { operations: { getInvoice: handler } },
+    },
+    spec,
+    () => undefined,
+    ["/app/nano-generated/controller.ts"],
+  );
+  const res = await router(req("GET", "/app/api/invoices/7"));
+  assert.equal(res.status, 200);
+  assert.deepEqual(seen, [{ id: "7" }]);
+  // Only the controller barrel is imported — never a per-operation delegate path.
+  assert.deepEqual(imported, ["/app/nano-generated/controller"]);
+});
+
+test("controller present: request validation still runs before the registry delegate", async () => {
+  const handler: OperationHandler = () => ({ status: 201, body: { id: "i", amount: 1 } });
+  const { router } = build(
+    { spec: "openapi.json" },
+    { "/app/nano-generated/controller": { operations: { createInvoice: handler } } },
+    spec,
+    () => undefined,
+    ["/app/nano-generated/controller.ts"],
+  );
+  // amount:0 violates minimum:1 → a 400 from validation, before the delegate.
+  const res = await router(req("POST", "/app/api/invoices", { body: JSON.stringify({ id: "i", amount: 0 }) }));
+  assert.equal(res.status, 400);
+  assert.match(JSON.parse(res.body!).error, /request validation failed/);
+});
+
+test("controller present but missing a delegate key → 500 with a run-`urban gen` hint", async () => {
+  const { router, logs } = build(
+    { spec: "openapi.json" },
+    { "/app/nano-generated/controller": { operations: {} } }, // stale: getInvoice not registered
+    spec,
+    () => undefined,
+    ["/app/nano-generated/controller.ts"],
+  );
+  const res = await router(req("GET", "/app/api/invoices/7"));
+  assert.equal(res.status, 500);
+  assert.match(JSON.parse(res.body!).error, /is not registered/);
+  assert.ok(logs.some((l) => l.level === "error" && /not registered in the generated controller/.test(l.msg)));
+});
+
+test("a NotImplemented throw from a delegate maps to HTTP 501", async () => {
+  const stub: OperationHandler = () => {
+    throw new NotImplemented("getInvoice");
+  };
+  const { router } = build(
+    { spec: "openapi.json" },
+    { "/app/nano-generated/controller": { operations: { getInvoice: stub } } },
+    spec,
+    () => undefined,
+    ["/app/nano-generated/controller.ts"],
+  );
+  const res = await router(req("GET", "/app/api/invoices/7"));
+  assert.equal(res.status, 501);
+  const bodyJson = JSON.parse(res.body!);
+  assert.equal(bodyJson.operationId, "getInvoice");
+  assert.match(bodyJson.error, /not implemented/);
+});
+
+test("no controller present → back-compat per-op import path still works", async () => {
+  const { router, imported } = build(
+    { spec: "openapi.json" },
+    { "/app/operations/getInvoice": { default: () => ({ body: { ok: true } }) } },
+    // no exists paths → controller absent
+  );
+  const res = await router(req("GET", "/app/api/invoices/9"));
+  assert.equal(res.status, 200);
+  assert.deepEqual(imported, ["/app/operations/getInvoice"]);
+});
+
+test("compiled app: controller.js present (no .ts) → still uses the registry", async () => {
+  // A published / `urban run` build ships controller.js with TS sources absent. Probing only .ts
+  // would wrongly report the registry missing and fall back to per-op imports; probe all extensions.
+  const handler: OperationHandler = () => ({ status: 200, body: { ok: true } });
+  const { router, imported } = build(
+    { spec: "openapi.json" },
+    { "/app/nano-generated/controller": { operations: { getInvoice: handler } } },
+    spec,
+    () => undefined,
+    ["/app/nano-generated/controller.js"], // only the compiled artifact exists on disk
+  );
+  const res = await router(req("GET", "/app/api/invoices/7"));
+  assert.equal(res.status, 200);
+  assert.deepEqual(imported, ["/app/nano-generated/controller"]);
+});

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

@@ -15,6 +15,7 @@
 import type { AppApi, RuntimeContext } from "../context.ts";
 import { errorMessage } from "../guards.ts";
 import type { HttpRequest, HttpResponse } from "../host.ts";
+import { MODULE_EXTENSION_CANDIDATES } from "../module-path.ts";
 import { html, json, normalizeRoutePath, type Route } from "../router.ts";
 import { resolveAppPath } from "./datasource.ts";
 import {
@@ -91,18 +92,24 @@ window.ui = SwaggerUIBundle({ url: ${JSON.stringify(specUrl)}, dom_id: '#swagger
 </html>`;
 }
 
-/** The `{ params, query, body }` contract a typed operation is generic over. */
+/** The `{ params, query, body }` contract a typed operation is generic over. `body` is optional so
+ *  a generated request type for an operation without a required requestBody (its `body?` is
+ *  optional/`undefined`) still satisfies the constraint — see the generated `operations.ts` /
+ *  `controller.ts`, which parameterise `OperationHandler` over the per-op request type. */
 export interface OperationContract {
   params: unknown;
   query: unknown;
-  body: unknown;
+  body?: unknown;
 }
 
-/** The loose contract an untyped delegate sees (strings on the wire; unknown JSON body). */
+/** The loose contract an untyped delegate sees (strings on the wire; unknown JSON body). `body` is
+ *  optional so a raw (untyped) delegate typed `OperationHandler<DefaultContract>` still satisfies the
+ *  generated registry's per-operation `OperationHandler<ReqFor<K>>` slot — an op whose request body
+ *  is optional/absent must be a subtype of the default contract (handler args are contravariant). */
 export interface DefaultContract {
   params: Record<string, string>;
   query: Record<string, string | string[] | undefined>;
-  body: unknown;
+  body?: unknown;
 }
 
 /** The input handed to an operation delegate: the raw request plus the parsed (and, unless ejected,
@@ -127,6 +134,27 @@ export type OperationHandler<Req extends OperationContract = DefaultContract, Re
   app: AppApi,
 ) => Promise<OperationResult<Res> | void> | OperationResult<Res> | void;
 
+/**
+ * Thrown by a write-once operation stub to signal the endpoint exists but has no implementation
+ * yet; the dispatcher maps it to HTTP `501 Not Implemented` (ADR 0059). Delete the throw once you
+ * implement the handler body. A brand property makes the check robust across module realms.
+ */
+export class NotImplemented extends Error {
+  readonly urbanNotImplemented = true as const;
+  constructor(operationId: string) {
+    super(`operation not implemented: ${operationId}`);
+    this.name = "NotImplemented";
+  }
+}
+
+/** True for a `NotImplemented` throw (instanceof, or the brand — resilient to realm/dup-copy). */
+function isNotImplemented(e: unknown): boolean {
+  return (
+    e instanceof NotImplemented ||
+    (typeof e === "object" && e !== null && Reflect.get(e, "urbanNotImplemented") === true)
+  );
+}
+
 /**
  * Typed-identity helper the generated `operations.ts` wrapper re-types per operationId. Authoring:
  * `export default defineOperation("createInvoice", async ({ params, query, body }, app) => { ... })`
@@ -145,6 +173,10 @@ function isFunction(v: unknown): v is OperationHandler {
   return typeof v === "function";
 }
 
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
 /** Resolve an operation delegate from a loaded module: `default` (when a function) else `handler`. */
 export function resolveOperationHandler(mod: Record<string, unknown>): OperationHandler | undefined {
   if (isFunction(mod.default)) return mod.default;
@@ -290,7 +322,8 @@ export function mountApi(ctx: RuntimeContext, app: AppApi): ApiHandle {
     return docPromise;
   };
 
-  // Lazily import + cache each delegate module, mirroring mountActions.
+  // Lazily import + cache each delegate module, mirroring mountActions. This is the back-compat
+  // fallback for apps without a generated controller registry (see loadController below).
   const moduleCache = new Map<string, Promise<Record<string, unknown>>>();
   const loadModule = (operationId: string): Promise<Record<string, unknown>> => {
     // Defense-in-depth at the import sink: collectOperations already skips unsafe ids, but never
@@ -310,6 +343,43 @@ export function mountApi(ctx: RuntimeContext, app: AppApi): ApiHandle {
     return pending;
   };
 
+  // Prefer the generated delegate registry (ADR 0059): one statically-typed barrel the toolkit
+  // emits from the spec, so a missing/mismatched/orphan delegate is a `tsc` error, and dispatch is
+  // a deterministic map lookup rather than a per-request path import. Imported ONCE and cached.
+  // Absent (an app that hasn't re-genned) → `null`, and dispatch falls back to `loadModule`. A
+  // present-but-broken controller (a delegate that throws at import) is NOT swallowed — it retries
+  // and surfaces as a 500 with the reason, exactly like a bad delegate does today.
+  let controllerPromise: Promise<Record<string, unknown> | null> | undefined;
+  const loadController = (): Promise<Record<string, unknown> | null> => {
+    if (!controllerPromise) {
+      const rel = "nano-generated/controller";
+      controllerPromise = (async () => {
+        // Probe every supported module extension (compiled .js first, mirroring resolveModulePath),
+        // NOT just `.ts`: a published / `urban run` app ships `controller.js` with the TS sources
+        // absent, and probing only `.ts` there would wrongly report the registry missing and fall
+        // back to per-op dynamic imports — defeating deterministic dispatch in production.
+        let present = false;
+        for (const ext of MODULE_EXTENSION_CANDIDATES) {
+          if (await ctx.host.exists(resolveAppPath(ctx.root, rel + ext))) {
+            present = true;
+            break;
+          }
+        }
+        if (!present) return null;
+        const mod = await ctx.host.importModule(resolveAppPath(ctx.root, rel));
+        const ops = mod.operations;
+        if (!isRecord(ops)) {
+          throw new Error("nano-generated/controller must export an `operations` registry");
+        }
+        return ops;
+      })().catch((e) => {
+        controllerPromise = undefined; // don't cache the failure — let a later request retry
+        throw e;
+      });
+    }
+    return controllerPromise;
+  };
+
   // Build the operation table lazily from the loaded doc (cached).
   let opsPromise: Promise<MountedOp[]> | undefined;
   const loadOps = (): Promise<MountedOp[]> => {
@@ -496,7 +566,21 @@ export function mountApi(ctx: RuntimeContext, app: AppApi): ApiHandle {
 
     let handler: OperationHandler | undefined;
     try {
-      handler = resolveOperationHandler(await loadModule(op.operationId));
+      const controller = await loadController();
+      if (controller) {
+        // Deterministic dispatch: the generated registry guarantees (at `tsc` time) one delegate
+        // per operationId. A missing/non-function key here means the controller is stale vs the spec.
+        const candidate = controller[op.operationId];
+        if (!isFunction(candidate)) {
+          ctx.host.log("error", "operation not registered in the generated controller (run `urban gen`)", {
+            operationId: op.operationId,
+          });
+          return json({ error: `operation ${op.operationId} is not registered — run \`urban gen\`` }, 500);
+        }
+        handler = candidate;
+      } else {
+        handler = resolveOperationHandler(await loadModule(op.operationId));
+      }
     } catch (e) {
       ctx.host.log("error", "operation delegate failed to load", {
         operationId: op.operationId,
@@ -541,11 +625,14 @@ export function mountApi(ctx: RuntimeContext, app: AppApi): ApiHandle {
         body: result.body === undefined ? undefined : JSON.stringify(result.body),
       };
     } catch (e) {
+      // A write-once stub (or any delegate) can signal "endpoint exists, not implemented yet" with
+      // a NotImplemented throw → 501, distinct from an unexpected fault (500).
+      if (isNotImplemented(e)) {
+        return json({ error: errorMessage(e), operationId: op.operationId }, 501);
+      }
       return json({ error: errorMessage(e) }, 500);
     }
   };
-
-  // Categorical safety net: any unexpected throw during dispatch — e.g. a malformed spec
   // `pattern` surfacing from validation — becomes a controlled 500 rather than escaping into
   // the host request handler, which has no top-level catch of its own.
   const dispatch = async (req: HttpRequest): Promise<HttpResponse> => {

package/src/runtime/core/runtime.test.ts

@@ -1,10 +1,11 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtemp, mkdir, writeFile, rm } from "node:fs/promises";
+import { mkdtemp, mkdir, writeFile, readFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { createNodeHost } from "../adapters/node.ts";
 import { createUrbanApp, resolvePort } from "./runtime.ts";
+import type { SchedulerDeps } from "./modules/scheduler.ts";
 import { runFromEnv } from "../run.ts";
 import { isRecord } from "./guards.ts";
 import type {
@@ -405,3 +406,54 @@ test("treats NANOBPMN_APP_HANDSHAKE other than \"1\" as opt-out", async () => {
     await rm(dir, { recursive: true, force: true });
   }
 });
+
+// A minimal deterministic scheduler seam: records armed timers so a test can assert the
+// injected scheduler — not the live one — drives createUrbanApp's background loops.
+function countingScheduler(): SchedulerDeps & { armed: () => number } {
+  let clock = 0;
+  let armed = 0;
+  return {
+    now: () => clock,
+    setTimer: (_fn, _ms) => {
+      armed += 1;
+      return armed;
+    },
+    clearTimer: () => {},
+    armed: () => armed,
+  };
+}
+
+async function makeTrackingFixture(): Promise<string> {
+  const dir = await makeFixture();
+  const manifestPath = join(dir, "nano.app.json");
+  const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+  manifest.instanceTracking = [
+    {
+      table: "crew_tasks",
+      keyField: "id",
+      statusField: "status",
+      activeStatuses: ["claimed"],
+      onTerminated: { set: { status: "abandoned" } },
+      pollMs: 1000,
+    },
+  ];
+  await writeFile(manifestPath, JSON.stringify(manifest, null, 2));
+  return dir;
+}
+
+test("threads an injected scheduler into the instance-tracking reconciler loop", async () => {
+  const dir = await makeTrackingFixture();
+  const host = createNodeHost({ cwd: dir, log: () => {} });
+  const engine = new FakeEngine();
+  const sched = countingScheduler();
+  const app = await createUrbanApp({ host, engine, root: ".", port: 0, scheduler: sched });
+  try {
+    await app.start();
+    // The reconciler arms its first poll on the injected scheduler, not the live one — so the
+    // whole-app settle loop can drive it deterministically over a virtual clock.
+    assert.ok(sched.armed() >= 1, "injected scheduler armed the reconciler poll");
+  } finally {
+    await app.stop();
+    await rm(dir, { recursive: true, force: true });
+  }
+});

package/src/runtime/core/runtime.ts

@@ -18,6 +18,7 @@ import { mountConnectors } from "./modules/connectors.ts";
 import { mountSurfaces } from "./modules/surfaces.ts";
 import { mountTriggers } from "./modules/triggers.ts";
 import { mountInstanceTracking } from "./modules/instance-tracking.ts";
+import type { SchedulerDeps } from "./modules/scheduler.ts";
 import { mountSecurity, type SecurityPolicy } from "./modules/security.ts";
 
 /** Resolve the HTTP port: explicit option, else $PORT, else 8090. Throws a clear
@@ -76,6 +77,15 @@ export interface CreateUrbanAppOptions {
    *  `name → content` map). Merged over the manifest's `models.templates` (this wins on
    *  collision). See `deployModels`. */
   templates?: TemplateSource;
+  /**
+   * Injectable timer + clock seam driving every background loop (the cron trigger loops
+   * and the instance-tracking reconciler). Defaults to the live scheduler (real timers,
+   * wall clock). The e2e test kit injects a manual scheduler so those loops advance
+   * deterministically over a virtual clock — the single seam that makes a whole-app
+   * `settle()` possible. Threaded verbatim into `mountTriggers` and `mountInstanceTracking`
+   * so one injected scheduler drives them both (no per-module wiring, no drift).
+   */
+  scheduler?: SchedulerDeps;
 }
 
 export interface UrbanApp {
@@ -210,13 +220,13 @@ export async function createUrbanApp(opts: CreateUrbanAppOptions): Promise<Urban
           describe.surfaces = s.describe();
         }
         if (flags.triggers) {
-          const t = mountTriggers(ctx, api);
+          const t = mountTriggers(ctx, api, opts.scheduler);
           routes.push(...t.routes);
           mounted.push(t);
           describe.triggers = t.describe?.();
         }
         if (flags.instanceTracking && (manifest.instanceTracking?.length ?? 0) > 0) {
-          const it = mountInstanceTracking(ctx, api);
+          const it = mountInstanceTracking(ctx, api, opts.scheduler);
           mounted.push(it);
           describe.instanceTracking = it.describe?.();
         }

package/src/runtime/index.ts

@@ -87,7 +87,7 @@ 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 { defineOperation, mountApi, resolveOperationHandler, NotImplemented } from "./core/modules/api.ts";
 export type {
   ApiBinding,
   ApiHandle,
@@ -119,6 +119,8 @@ export { evalCorrelation } from "./core/modules/triggers.ts";
 export { deployModels } from "./core/modules/deploy.ts";
 export { applyTemplates, resolveTemplates } from "./core/modules/templates.ts";
 export type { TemplateApplication, TemplateSource } from "./core/modules/templates.ts";
+export { defaultScheduler, MAX_TIMER_DELAY_MS } from "./core/modules/scheduler.ts";
+export type { SchedulerDeps } from "./core/modules/scheduler.ts";
 
 // Adapters + engine + run entrypoint
 export { createNodeHost } from "./adapters/node.ts";

package/src/toolkit/api-dir.test.ts

@@ -0,0 +1,32 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { DEFAULT_OPERATIONS_DIR, normalizeApiDir } from "./api-dir.ts";
+
+test("normalizeApiDir: empty/whitespace falls back to the default", () => {
+  assert.equal(normalizeApiDir(""), DEFAULT_OPERATIONS_DIR);
+  assert.equal(normalizeApiDir("   "), DEFAULT_OPERATIONS_DIR);
+});
+
+test("normalizeApiDir: strips leading ./ and surrounding slashes, folds backslashes", () => {
+  assert.equal(normalizeApiDir("ops"), "ops");
+  assert.equal(normalizeApiDir("./ops/"), "ops");
+  assert.equal(normalizeApiDir("api\\ops"), "api/ops");
+  assert.equal(normalizeApiDir("nested/ops/"), "nested/ops");
+});
+
+test("normalizeApiDir: rejects absolute POSIX paths", () => {
+  assert.throws(() => normalizeApiDir("/ops"), /app-relative/);
+});
+
+test("normalizeApiDir: rejects absolute Windows paths", () => {
+  assert.throws(() => normalizeApiDir("C:\\ops"), /app-relative/);
+  assert.throws(() => normalizeApiDir("C:/ops"), /app-relative/);
+  assert.throws(() => normalizeApiDir("\\ops"), /app-relative/);
+});
+
+test("normalizeApiDir: rejects .. traversal segments", () => {
+  assert.throws(() => normalizeApiDir("../ops"), /\.\./);
+  assert.throws(() => normalizeApiDir("ops/../escape"), /\.\./);
+  assert.throws(() => normalizeApiDir("a/../../b"), /\.\./);
+});

package/src/toolkit/api-dir.ts

@@ -0,0 +1,41 @@
+// Shared normalization + validation for the OpenAPI surface's `api.dir` (the directory operation
+// delegates live in). Used by BOTH the deriver (which bakes `<dir>/<operationId>` into the generated
+// controller's static import paths) and the scaffolder (which writes stubs to `<dir>/<operationId>.ts`)
+// so the two can never disagree on where a delegate lives — a single rule, one place.
+//
+// The rule is intentionally strict: `api.dir` must be a safe app-relative directory. An absolute path
+// or a `..` segment is REJECTED with a clear error rather than silently rewritten, because a silent
+// rewrite would let `urban gen` scaffold into one directory while the runtime resolves delegates
+// from another (drift), and a `..` segment could escape the app root when later joined.
+
+/** The default directory operation delegates live in (mirrors the runtime's `api.dir` default). */
+export const DEFAULT_OPERATIONS_DIR = "operations";
+
+/**
+ * Normalize an `api.dir` to a clean, app-relative directory segment (no leading/trailing slashes,
+ * backslashes folded to `/`). An empty value falls back to {@link DEFAULT_OPERATIONS_DIR}.
+ *
+ * Throws if `dir` is absolute (POSIX `/…` or Windows `C:\…`/`\…`) or contains a `..` traversal
+ * segment — both would let the generated controller's import paths or the scaffolder's write target
+ * diverge from (or escape) the app root.
+ */
+export function normalizeApiDir(dir: string): string {
+  const raw = dir.trim();
+  if (raw.length === 0) return DEFAULT_OPERATIONS_DIR;
+
+  if (isAbsolutePath(raw)) {
+    throw new Error(`api.dir must be an app-relative directory, not an absolute path: ${dir}`);
+  }
+
+  const cleaned = raw.replace(/\\/g, "/").replace(/^\.?\/+/, "").replace(/\/+$/, "");
+  if (cleaned.split("/").some((seg) => seg === "..")) {
+    throw new Error(`api.dir must not contain ".." path segments: ${dir}`);
+  }
+
+  return cleaned.length > 0 ? cleaned : DEFAULT_OPERATIONS_DIR;
+}
+
+/** True for a POSIX absolute path (`/…`) or a Windows absolute/drive path (`C:\…`, `C:/…`, `\…`). */
+function isAbsolutePath(path: string): boolean {
+  return /^([/\\]|[A-Za-z]:[/\\])/.test(path);
+}

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

@@ -1,6 +1,6 @@
 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 { deriveApi, emitApiBindings, emitApiBindingsRuntime, emitApiController, schemaToTs, API_BINDINGS_DTS, API_BINDINGS_TS, API_CONTROLLER_TS } from "./api.ts";
 import type { OpenApiDoc } from "../../openapi/spec.ts";
 
 const doc: OpenApiDoc = {
@@ -55,10 +55,48 @@ test("emitApiBindingsRuntime re-types the runtime defineOperation", () => {
   assert.match(out, /return defineOperationRaw\(id, handler\);/);
 });
 
-test("deriveApi emits both artifacts under nano-generated/", () => {
+test("deriveApi emits the type map, typed defineOperation, and the controller 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}`]);
+  assert.deepEqual(paths, [
+    `nano-generated/${API_BINDINGS_DTS}`,
+    `nano-generated/${API_BINDINGS_TS}`,
+    `nano-generated/${API_CONTROLLER_TS}`,
+  ].sort());
+});
+
+test("emitApiController statically imports each delegate + asserts the set with satisfies", () => {
+  const out = emitApiController(doc);
+  // one default import per operation, from the default operations/ dir, with an explicit .ts ext
+  assert.match(out, /import op0 from "\.\.\/operations\/getInvoice\.ts";/);
+  // the registry maps the real operationId to the imported delegate
+  assert.match(out, /"getInvoice": op0,/);
+  // the load-bearing completeness assertion
+  assert.match(out, /satisfies \{\s*\[K in ApiOperationId\]: OperationHandler<ReqFor<K>, ResFor<K>>;\s*\}/);
+  assert.match(out, /import type \{ OperationHandler \} from "@nanobpm\/urban";/);
+});
+
+test("emitApiController honors a custom api.dir for the delegate import path", () => {
+  const out = emitApiController(doc, "handlers");
+  assert.match(out, /import op0 from "\.\.\/handlers\/getInvoice\.ts";/);
+});
+
+test("emitApiController on an empty spec is a valid empty registry (never = {})", () => {
+  const empty: OpenApiDoc = { openapi: "3.0.0", paths: {} };
+  const out = emitApiController(empty);
+  assert.doesNotMatch(out, /^import op\d/m); // no delegate imports
+  assert.match(out, /export const operations = \{\s*\} satisfies \{/);
+});
+
+test("emitApiController throws on a duplicate operationId (would silently overwrite a map key)", () => {
+  const dupe: OpenApiDoc = {
+    openapi: "3.0.0",
+    paths: {
+      "/a": { get: { operationId: "same", responses: { "200": {} } } },
+      "/b": { get: { operationId: "same", responses: { "200": {} } } },
+    },
+  };
+  assert.throws(() => emitApiController(dupe), /duplicate operationId\(s\): same/);
 });
 
 test("emitted object types mirror runtime additionalProperties semantics", () => {