@nanobpm/urban 0.35.0 → 0.36.0

package/dist/cli.d.ts

@@ -3,7 +3,6 @@ interface Flags {
     manifest: string;
     port?: number;
     check: boolean;
-    write: boolean;
     deno: boolean;
     models: boolean;
     stdout: boolean;

package/dist/cli.js

@@ -15,7 +15,7 @@ import { collectManifestIssues, installSignalHandlers, loadManifest, runDataOp,
 import { denoGlobal, processGlobal } from "./runtime/adapters/globals.js";
 import { errorMessage, isRecord } from "./runtime/core/guards.js";
 import { scaffold, slugify } from "create-urban-app";
-import { addConnector, createNodeGenIO, previewModels, runGen, scaffoldWorkers } from "./toolkit/index.js";
+import { addConnector, createNodeGenIO, previewModels, generate, runGen } from "./toolkit/index.js";
 import { pathToFileURL } from "node:url";
 import { readFileSync } from "node:fs";
 import { spawnSync } from "node:child_process";
@@ -33,7 +33,7 @@ function readVersion() {
 }
 const VERSION = readVersion();
 function parse(argv) {
-    const f = { root: ".", manifest: "nano.app.json", check: false, write: false, deno: false, models: true, stdout: false, install: true, help: false, version: false, _: [] };
+    const f = { root: ".", manifest: "nano.app.json", check: false, deno: false, models: true, stdout: false, install: true, help: false, version: false, _: [] };
     const need = (i, flag) => {
         const v = argv[i];
         if (v === undefined || v.startsWith("-"))
@@ -48,8 +48,6 @@ function parse(argv) {
             f.version = true;
         else if (a === "--check")
             f.check = true;
-        else if (a === "--write")
-            f.write = true;
         else if (a === "--deno")
             f.deno = true;
         else if (a === "--no-models")
@@ -97,11 +95,12 @@ Usage:
   urban new <name> [--root <path>] [--deno] [--style model|code]    scaffold a new Urban app
                                     (--code-first is shorthand for --style code)
   urban check                       validate the manifest
-  urban gen [--check] [--no-models] derive artifacts (migrations, worker-io, + code-first models)
+  urban gen [--check] [--no-models] derive artifacts + scaffold write-once handler stubs
+                                    (--check: verify up-to-date without writing; a missing stub or
+                                    drifted artifact fails — run \`urban gen\`)
                                     (--no-models: skip writing derived .bpmn; type-contracts only)
   urban derive [--check|--stdout]   derive code-first models only (workflows/*.ts → processes/*.bpmn)
                                     (--stdout: print {models,incomplete} JSON without writing)
-  urban stubs [--write]             scaffold write-once handler stubs from the model
   urban add <pkg> [--no-install]    install a connector pack + wire it into nano.app.json
   urban run                         materialize + serve the app
   urban dev                         run + watch sources, hot-reload on change
@@ -136,7 +135,7 @@ async function cmdCheck(f) {
 }
 async function cmdGen(f) {
     const io = createNodeGenIO();
-    const res = await runGen({ root: f.root, io, manifestFile: f.manifest, check: f.check, emitModels: f.models });
+    const res = await generate({ root: f.root, io, manifestFile: f.manifest, check: f.check, emitModels: f.models });
     if (res.incomplete) {
         console.error(`✖ ${res.modelErrors.length} workflow(s) failed to derive:`);
         for (const e of res.modelErrors)
@@ -144,18 +143,39 @@ async function cmdGen(f) {
         return 1;
     }
     if (f.check) {
-        if (res.drift.length === 0) {
-            console.log(`✔ generated artifacts are up to date (${res.artifacts.length} checked)`);
+        if (res.drift.length === 0 && res.missingStubs.length === 0) {
+            console.log(`✔ generated artifacts + handler stubs are up to date (${res.artifacts.length} checked)`);
             return 0;
         }
-        console.error(`✖ ${res.drift.length} generated artifact(s) are out of date — run \`urban gen\`:`);
-        for (const p of res.drift)
-            console.error(`  • ${p}`);
+        if (res.drift.length > 0) {
+            console.error(`✖ ${res.drift.length} generated artifact(s) are out of date — run \`urban gen\`:`);
+            for (const p of res.drift)
+                console.error(`  • ${p}`);
+        }
+        if (res.missingStubs.length > 0) {
+            console.error(`✖ ${res.missingStubs.length} handler stub(s) missing — run \`urban gen\`:`);
+            for (const p of res.missingStubs)
+                console.error(`  • ${p}`);
+        }
         return 1;
     }
     console.log(`✔ generated ${res.artifacts.length} artifact(s):`);
     for (const a of res.artifacts)
         console.log(`  • ${a.path}`);
+    // Write-once handler stubs scaffolded as part of generation (workers from the model, operation
+    // delegates from the OpenAPI spec). Existing, human-owned stubs are kept verbatim.
+    const created = [
+        ...res.workerStubs.filter((o) => o.status === "created").map((o) => o.handlerPath),
+        ...res.operationStubs.filter((o) => o.status === "created").map((o) => o.handlerPath),
+    ];
+    if (created.length > 0) {
+        console.log(`✔ scaffolded ${created.length} handler stub(s):`);
+        for (const p of created)
+            console.log(`  + ${p}`);
+    }
+    if (res.manifestPatched) {
+        console.log(`✔ wired ${res.wiredWorkers.length} worker(s) into ${f.manifest}`);
+    }
     return 0;
 }
 async function cmdDerive(f) {
@@ -204,39 +224,6 @@ async function cmdDerive(f) {
         console.log(`  • ${a.path}`);
     return 0;
 }
-async function cmdStubs(f) {
-    const io = createNodeGenIO();
-    const run = await scaffoldWorkers({ root: f.root, io, manifestFile: f.manifest, write: f.write });
-    const created = run.outcomes.filter((o) => o.status === "created");
-    const would = run.outcomes.filter((o) => o.status === "would-create");
-    const kept = run.outcomes.filter((o) => o.status === "kept");
-    const typing = (o) => o.typedIn || o.typedOut ? ` (typed${o.typedIn ? " in" : ""}${o.typedOut ? " out" : ""})` : "";
-    if (run.write) {
-        console.log(`✔ scaffolded ${created.length} worker stub(s):`);
-        for (const o of created)
-            console.log(`  + ${o.handlerPath}${typing(o)}`);
-        if (run.manifestPatched) {
-            console.log(`✔ wired ${run.wired.length} worker(s) into ${f.manifest}`);
-        }
-    }
-    else {
-        if (would.length === 0) {
-            console.log(`✔ no new worker stubs to scaffold`);
-        }
-        else {
-            console.log(`Would scaffold ${would.length} worker stub(s) — run with --write to apply:`);
-            for (const o of would)
-                console.log(`  + ${o.handlerPath}${typing(o)}`);
-        }
-    }
-    for (const o of kept)
-        console.log(`  = ${o.handlerPath} (kept — already exists)`);
-    if (run.skipped.length > 0) {
-        console.log(`  skipped ${run.skipped.length}: ` +
-            run.skipped.map((s) => `${s.taskType} (${s.reason})`).join(", "));
-    }
-    return 0;
-}
 async function cmdRun(f, mount) {
     const app = await runFromEnv({
         root: f.root,
@@ -417,8 +404,6 @@ export async function main(argv) {
             return cmdGen(f);
         case "derive":
             return cmdDerive(f);
-        case "stubs":
-            return cmdStubs(f);
         case "add":
             return cmdAdd(f);
         case "data":

package/dist/openapi/spec.d.ts

@@ -118,6 +118,15 @@ export declare function resolveSchema(doc: OpenApiDoc, schema: OpenApiSchema | u
  *  (path, method) order. Operations without an operationId are skipped here; the runtime mount logs
  *  them at `warn` and skips them too — this keeps the pure collector total. */
 export declare function collectOperations(doc: OpenApiDoc): OperationInfo[];
+/**
+ * Throw if the document declares the same `operationId` on more than one operation. An operationId
+ * must be unique across the whole OpenAPI document (it names the delegate module `<dir>/<operationId>`
+ * AND the generated controller registry key), so a duplicate would silently overwrite an earlier
+ * entry in the emitted object literal — dispatching the wrong delegate while still type-checking — and
+ * make the scaffolder plan the same stub twice. Called by the gen/scaffold path so `urban gen`
+ * fails loudly on an incoherent spec instead of shipping a mis-dispatching registry.
+ */
+export declare function assertUniqueOperationIds(doc: OpenApiDoc): void;
 /** "method path" pointers for every operation that declares no `operationId`. Such operations are
  *  unroutable (no delegate to bind), so the runtime mount logs them at `warn` and skips them. */
 export declare function operationsWithoutId(doc: OpenApiDoc): string[];

package/dist/openapi/spec.js

@@ -148,6 +148,28 @@ export function collectOperations(doc) {
     }
     return out;
 }
+/**
+ * Throw if the document declares the same `operationId` on more than one operation. An operationId
+ * must be unique across the whole OpenAPI document (it names the delegate module `<dir>/<operationId>`
+ * AND the generated controller registry key), so a duplicate would silently overwrite an earlier
+ * entry in the emitted object literal — dispatching the wrong delegate while still type-checking — and
+ * make the scaffolder plan the same stub twice. Called by the gen/scaffold path so `urban gen`
+ * fails loudly on an incoherent spec instead of shipping a mis-dispatching registry.
+ */
+export function assertUniqueOperationIds(doc) {
+    const seen = new Set();
+    const duplicates = new Set();
+    for (const op of collectOperations(doc)) {
+        if (seen.has(op.operationId))
+            duplicates.add(op.operationId);
+        seen.add(op.operationId);
+    }
+    if (duplicates.size > 0) {
+        const list = [...duplicates].sort().join(", ");
+        throw new Error(`OpenAPI spec declares duplicate operationId(s): ${list}. Each operationId must be unique — ` +
+            "it names the delegate module and the generated controller registry key.");
+    }
+}
 /** "method path" pointers for every operation that declares no `operationId`. Such operations are
  *  unroutable (no delegate to bind), so the runtime mount logs them at `warn` and skips them. */
 export function operationsWithoutId(doc) {

package/dist/runtime/core/modules/api.d.ts

@@ -13,17 +13,23 @@ export interface ApiBinding {
      *  for free — the UI reads the SAME OpenAPI document the runtime routes + validates from. */
     docs?: boolean | string;
 }
-/** 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,
  *  validated) path params, query, and JSON body. */
@@ -41,6 +47,15 @@ export interface OperationResult<Res = unknown> {
 }
 /** An app-authored operation delegate: validated/typed input + the injected AppApi. */
 export type OperationHandler<Req extends OperationContract = DefaultContract, Res = unknown> = (input: OperationInput<Req>, 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 declare class NotImplemented extends Error {
+    readonly urbanNotImplemented: true;
+    constructor(operationId: string);
+}
 /**
  * Typed-identity helper the generated `operations.ts` wrapper re-types per operationId. Authoring:
  * `export default defineOperation("createInvoice", async ({ params, query, body }, app) => { ... })`

package/dist/runtime/core/modules/api.js

@@ -12,6 +12,7 @@
 // `x-urban-eject: true` OpenAPI vendor extension. The delegate is always additively imperative: it
 // gets the raw `req` and full `AppApi` on top of the validated input.
 import { errorMessage } from "../guards.js";
+import { MODULE_EXTENSION_CANDIDATES } from "../module-path.js";
 import { html, json, normalizeRoutePath } from "../router.js";
 import { resolveAppPath } from "./datasource.js";
 import { collectOperations, isSafeOperationId, operationsWithoutId, operationsWithUnsafeId, parseSpec, resolveSchema, toRouteMatcher, undeclaredPathParams, undeclaredSecuritySchemes, evaluateSecurity, validateValue, } from "../../../openapi/spec.js";
@@ -51,6 +52,23 @@ window.ui = SwaggerUIBundle({ url: ${JSON.stringify(specUrl)}, dom_id: '#swagger
 </body>
 </html>`;
 }
+/**
+ * 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 {
+    urbanNotImplemented = true;
+    constructor(operationId) {
+        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) {
+    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) => { ... })`
@@ -64,6 +82,9 @@ export function defineOperation(_id, handler) {
 function isFunction(v) {
     return typeof v === "function";
 }
+function isRecord(v) {
+    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) {
     if (isFunction(mod.default))
@@ -190,7 +211,8 @@ export function mountApi(ctx, app) {
         }
         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();
     const loadModule = (operationId) => {
         // Defense-in-depth at the import sink: collectOperations already skips unsafe ids, but never
@@ -209,6 +231,43 @@ export function mountApi(ctx, app) {
         }
         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;
+    const loadController = () => {
+        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;
     const loadOps = () => {
@@ -375,7 +434,22 @@ export function mountApi(ctx, app) {
         }
         let handler;
         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", {
@@ -418,10 +492,14 @@ export function mountApi(ctx, app) {
             };
         }
         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) => {

package/dist/runtime/core/runtime.d.ts

@@ -2,6 +2,7 @@ import type { EngineClient, HostContext } from "./host.ts";
 import { type AppManifest } from "./manifest.ts";
 import type { TemplateSource } from "./modules/templates.ts";
 import { DataLayer } from "./modules/datasource.ts";
+import type { SchedulerDeps } from "./modules/scheduler.ts";
 import { type SecurityPolicy } from "./modules/security.ts";
 /** Resolve the HTTP port: explicit option, else $PORT, else 8090. Throws a clear
  * error when $PORT is set but not a valid integer in 0..65535. */
@@ -34,6 +35,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 {
     readonly manifest: AppManifest;

package/dist/runtime/core/runtime.js

@@ -146,13 +146,13 @@ export async function createUrbanApp(opts) {
                     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/dist/runtime/index.d.ts

@@ -21,7 +21,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, 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";
@@ -31,6 +31,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";
 export { createNodeHost } from "./adapters/node.ts";
 export { createDenoHost } from "./adapters/deno.ts";
 export { isDeno, selectHost } from "./adapters/detect.ts";

package/dist/runtime/index.js

@@ -17,13 +17,14 @@ export { makeGateway, Table } from "./core/modules/gateway.js";
 export { createPagesRoutes, mountPages } from "./core/modules/pages.js";
 export { cancelInstanceReconciling } from "./core/modules/cancel.js";
 export { mountActions, resolveActionHandler } from "./core/modules/actions.js";
-export { defineOperation, mountApi, resolveOperationHandler } from "./core/modules/api.js";
+export { defineOperation, mountApi, resolveOperationHandler, NotImplemented } from "./core/modules/api.js";
 export { resolveHandler, sdkDecisionEvaluator } from "./core/modules/workers.js";
 export { buildMessages, callLlm, resolveProvider, runLlmJob, } from "./core/modules/llm.js";
 export { evalCorrelation } from "./core/modules/triggers.js";
 // Model deploy + `{{name}}` template substitution
 export { deployModels } from "./core/modules/deploy.js";
 export { applyTemplates, resolveTemplates } from "./core/modules/templates.js";
+export { defaultScheduler, MAX_TIMER_DELAY_MS } from "./core/modules/scheduler.js";
 // Adapters + engine + run entrypoint
 export { createNodeHost } from "./adapters/node.js";
 export { createDenoHost } from "./adapters/deno.js";

package/dist/toolkit/api-dir.d.ts

@@ -0,0 +1,11 @@
+/** The default directory operation delegates live in (mirrors the runtime's `api.dir` default). */
+export declare 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 declare function normalizeApiDir(dir: string): string;

package/dist/toolkit/api-dir.js

@@ -0,0 +1,36 @@
+// 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) {
+    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) {
+    return /^([/\\]|[A-Za-z]:[/\\])/.test(path);
+}

package/dist/toolkit/derivers/api.d.ts

@@ -1,8 +1,14 @@
 import type { DerivedArtifact, Deriver } from "../artifact.ts";
+import { DEFAULT_OPERATIONS_DIR } from "../api-dir.ts";
 import { type OpenApiDoc, type OpenApiSchema } from "../../openapi/spec.ts";
 /** Filenames of the emitted artifacts (siblings of worker-io.d.ts in nano-generated/). */
 export declare const API_BINDINGS_DTS = "api-io.d.ts";
 export declare 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 declare const API_CONTROLLER_TS = "controller.ts";
+export { DEFAULT_OPERATIONS_DIR };
 /** Render a JSON-Schema (OpenAPI subset) as a TS type expression. Local component `$ref`s render as
  *  their component name (emitted as named interfaces); unknown shapes fall back to `unknown`. */
 export declare function schemaToTs(schema: OpenApiSchema | undefined, depth?: number): string;
@@ -12,8 +18,25 @@ export declare function emitApiBindings(doc: OpenApiDoc): string;
  *  generated typed `defineWorker`). Written verbatim (it never changes with the spec) — it only
  *  re-types the runtime's `defineOperation`. */
 export declare function emitApiBindingsRuntime(): string;
-/** Derive the api artifacts from a parsed OpenAPI document. */
-export declare function deriveApi(doc: OpenApiDoc): DerivedArtifact[];
+/**
+ * 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 declare function emitApiController(doc: OpenApiDoc, operationsDir?: string): string;
+/** 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 declare function deriveApi(doc: OpenApiDoc, operationsDir?: string): DerivedArtifact[];
 export declare const apiDeriver: Deriver<{
     doc: OpenApiDoc;
+    operationsDir?: string;
 }>;

package/dist/toolkit/derivers/api.js

@@ -6,10 +6,16 @@
 // (`runtime/core/modules/api.ts`) is the matching half: it validates + routes from the SAME spec via
 // the shared `openapi/spec.ts`, so types and runtime never drift.
 import { GENERATED_DIR } from "../artifact.js";
-import { collectOperations, isObjectSchema, refName, } from "../../openapi/spec.js";
+import { DEFAULT_OPERATIONS_DIR, normalizeApiDir } from "../api-dir.js";
+import { collectOperations, assertUniqueOperationIds, isObjectSchema, refName, } from "../../openapi/spec.js";
 /** 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) {
     const cleaned = operationId.replace(/[^A-Za-z0-9]+/g, " ").trim();
@@ -210,15 +216,64 @@ export function emitApiBindingsRuntime() {
         `  return defineOperationRaw(id, handler);\n` +
         `}\n`);
 }
-/** Derive the api artifacts from a parsed OpenAPI document. */
-export function deriveApi(doc) {
+/** 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) {
+    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, operationsDir = DEFAULT_OPERATIONS_DIR) {
+    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, operationsDir = DEFAULT_OPERATIONS_DIR) {
     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 = {
     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),
 };