@nanobpm/urban 0.34.0 → 0.36.0

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 {
@@ -29,6 +30,8 @@ import {
   resolveSchema,
   toRouteMatcher,
   undeclaredPathParams,
+  undeclaredSecuritySchemes,
+  evaluateSecurity,
   validateValue,
   type ValidationIssue,
 } from "../../../openapi/spec.ts";
@@ -89,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,
@@ -125,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) => { ... })`
@@ -143,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;
@@ -288,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
@@ -308,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[]> => {
@@ -336,6 +408,14 @@ export function mountApi(ctx: RuntimeContext, app: AppApi): ApiHandle {
               { unsafe },
             );
           }
+          const undeclaredSchemes = undeclaredSecuritySchemes(d);
+          if (undeclaredSchemes.length > 0) {
+            ctx.host.log(
+              "warn",
+              "OpenAPI operations require a security scheme not declared in components.securitySchemes — those requests are rejected with 500 (ADR 0059)",
+              { undeclared: undeclaredSchemes },
+            );
+          }
           const mounted = collectOperations(d).map((op) => {
             const { pattern, paramNames } = toRouteMatcher(base, op.path);
             return { op, pattern, paramNames };
@@ -384,6 +464,26 @@ export function mountApi(ctx: RuntimeContext, app: AppApi): ApiHandle {
     const { op } = match;
     const ejected = surfaceEject || op.eject;
 
+    // Enforce the operation's security requirements (ADR 0059) before touching the body or the
+    // delegate: an unauthorized request should do no work and reveal nothing. Enforced even for
+    // ejected ops (eject changes body handling, not who may call the operation).
+    const authz = evaluateSecurity(
+      d,
+      op,
+      (name) => req.headers.get(name) ?? undefined,
+      (name) => req.query.get(name) ?? undefined,
+      (envVar) => ctx.host.env(envVar),
+    );
+    if (!authz.ok) {
+      if (authz.status === 500) {
+        ctx.host.log("error", "OpenAPI operation security is misconfigured (ADR 0059)", {
+          operationId: op.operationId,
+          reason: authz.error,
+        });
+      }
+      return json({ error: authz.error ?? "unauthorized" }, authz.status ?? 401);
+    }
+
     // Path params from the capture groups; query as a single-or-array map.
     const captures = match.pattern.exec(req.path) ?? [];
     const params: Record<string, string> = {};
@@ -466,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,
@@ -511,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", () => {

package/src/toolkit/derivers/api.ts

@@ -8,8 +8,10 @@
 
 import type { DerivedArtifact, Deriver } from "../artifact.ts";
 import { GENERATED_DIR } from "../artifact.ts";
+import { DEFAULT_OPERATIONS_DIR, normalizeApiDir } from "../api-dir.ts";
 import {
   collectOperations,
+  assertUniqueOperationIds,
   isObjectSchema,
   type OpenApiDoc,
   type OpenApiSchema,
@@ -20,6 +22,13 @@ import {
 /** 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";
+/** The generated delegate registry: statically imports every operation delegate and asserts the
+ *  complete, correctly-typed set via `satisfies` — so a missing/mismatched/orphan delegate fails
+ *  `tsc` (ADR 0059). The runtime dispatches through this map instead of per-op path imports. */
+export const API_CONTROLLER_TS = "controller.ts";
+
+export { DEFAULT_OPERATIONS_DIR };
+
 
 /** A TS identifier form of an operationId (used for the per-op type names). */
 function typeStem(operationId: string): string {
@@ -240,16 +249,77 @@ export function emitApiBindingsRuntime(): string {
   );
 }
 
-/** Derive the api artifacts from a parsed OpenAPI document. */
-export function deriveApi(doc: OpenApiDoc): DerivedArtifact[] {
+/** Normalize an `api.dir` to a clean relative segment (see `normalizeApiDir`); rejects absolute
+ *  paths and `..` segments so the generated import paths stay app-relative and can't drift. */
+function normalizeOperationsDir(dir: string): string {
+  return normalizeApiDir(dir);
+}
+
+/**
+ * Emit `controller.ts`: the generated delegate registry (ADR 0059). It statically imports every
+ * operation delegate (`<dir>/<operationId>.ts`) and asserts the whole set against the spec-derived
+ * contract with a single `satisfies { [K in ApiOperationId]: OperationHandler<ReqFor<K>, ResFor<K>> }`.
+ * That one assertion gives four compile-time drift guarantees, all surfaced by `tsc`:
+ *   • a missing delegate file            → the static `import` fails ("Cannot find module");
+ *   • an op in the spec, missing here     → the mapped type requires key `K` ("Property is missing");
+ *   • a delegate with the wrong signature → not assignable to `OperationHandler<Req, Res>`;
+ *   • an orphan delegate (no spec op)     → an excess property vs the mapped type.
+ * The runtime imports this ONE barrel and dispatches via `operations[operationId]`, so existing
+ * endpoints cannot drift from the contract. Delegates are keyed by their real operationId; the
+ * import binding is index-based (`op0`, `op1`, …) because an operationId is a safe path segment but
+ * not necessarily a valid TS identifier. Requires each delegate to be a default export.
+ */
+export function emitApiController(doc: OpenApiDoc, operationsDir: string = DEFAULT_OPERATIONS_DIR): string {
+  assertUniqueOperationIds(doc);
+  const ops = collectOperations(doc);
+  const dir = normalizeOperationsDir(operationsDir);
+
+  const header =
+    "// AUTO-GENERATED by @nanobpm/urban from the app's OpenAPI spec (ADR 0059): the delegate\n" +
+    "// registry. Statically imports every operation delegate and asserts the complete, correctly-\n" +
+    "// typed set via `satisfies` — a missing, mismatched, or orphan delegate fails `tsc`. The\n" +
+    "// runtime dispatches through this map, so endpoints cannot drift from the spec. Do not edit —\n" +
+    "// regenerated from the spec.\n" +
+    "// eslint-disable\n\n";
+
+  const typeImports =
+    `import type { OperationHandler } from "@nanobpm/urban";\n` +
+    `import type { ApiOperationId, ApiOperations } from "./${API_BINDINGS_DTS}";\n`;
+
+  const delegateImports = ops
+    .map((op, i) => `import op${i} from ${JSON.stringify(`../${dir}/${op.operationId}.ts`)};`)
+    .join("\n");
+
+  const mapEntries = ops.map((op, i) => `  ${JSON.stringify(op.operationId)}: op${i},`).join("\n");
+
+  return (
+    header +
+    typeImports +
+    (delegateImports ? `${delegateImports}\n` : "") +
+    `\n` +
+    `type ReqFor<K extends ApiOperationId> = ApiOperations[K]["request"];\n` +
+    `type ResFor<K extends ApiOperationId> = ApiOperations[K]["response"];\n\n` +
+    `/** Every operationId → its default-exported delegate. The \`satisfies\` clause makes \`tsc\`\n` +
+    ` *  reject a missing, wrongly-typed, or orphan delegate (ADR 0059). */\n` +
+    `export const operations = {\n${mapEntries}${mapEntries ? "\n" : ""}} satisfies {\n` +
+    `  [K in ApiOperationId]: OperationHandler<ReqFor<K>, ResFor<K>>;\n` +
+    `};\n`
+  );
+}
+
+/** Derive the api artifacts from a parsed OpenAPI document. `operationsDir` is the manifest's
+ *  `api.dir` (default `operations/`) — the controller's static delegate imports resolve into it. */
+export function deriveApi(doc: OpenApiDoc, operationsDir: string = DEFAULT_OPERATIONS_DIR): DerivedArtifact[] {
   return [
     { path: `${GENERATED_DIR}/${API_BINDINGS_DTS}`, content: emitApiBindings(doc) },
     { path: `${GENERATED_DIR}/${API_BINDINGS_TS}`, content: emitApiBindingsRuntime() },
+    { path: `${GENERATED_DIR}/${API_CONTROLLER_TS}`, content: emitApiController(doc, operationsDir) },
   ];
 }
 
-export const apiDeriver: Deriver<{ doc: OpenApiDoc }> = {
+export const apiDeriver: Deriver<{ doc: OpenApiDoc; operationsDir?: string }> = {
   id: "openapi->api-io",
-  describe: "Derive api-io.d.ts (typed request/response per operationId) + the typed defineOperation.",
-  derive: ({ doc }) => deriveApi(doc),
+  describe:
+    "Derive api-io.d.ts (typed request/response per operationId) + the typed defineOperation + the delegate registry.",
+  derive: ({ doc, operationsDir }) => deriveApi(doc, operationsDir),
 };

package/src/toolkit/gen.ts

@@ -122,7 +122,7 @@ async function collectAll(opts: GenOptions): Promise<{ artifacts: DerivedArtifac
   const manifestPath = join(root, opts.manifestFile ?? "nano.app.json");
   const manifest: ToolkitManifest & {
     models?: { processes?: string[]; workflows?: string[] };
-    api?: { spec?: string };
+    api?: { spec?: string; dir?: string };
   } = JSON.parse(await io.readText(manifestPath));
 
   const artifacts: DerivedArtifact[] = [];
@@ -159,7 +159,10 @@ async function collectAll(opts: GenOptions): Promise<{ artifacts: DerivedArtifac
   const specRef = typeof manifest.api?.spec === "string" ? manifest.api.spec.trim() : "";
   if (!opts.modelsOnly && specRef.length > 0) {
     const specText = await io.readText(join(root, specRef));
-    artifacts.push(...deriveApi(parseSpec(specText)));
+    const opsDir = typeof manifest.api?.dir === "string" && manifest.api.dir.trim().length > 0
+      ? manifest.api.dir.trim()
+      : undefined;
+    artifacts.push(...deriveApi(parseSpec(specText), opsDir));
   }
 
   return { artifacts: sortArtifacts(artifacts), derived };