@nanobpm/urban 0.34.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

@@ -50,6 +50,26 @@ export interface OpenApiResponse {
     description?: string;
     content?: Record<string, OpenApiMediaType>;
 }
+/**
+ * A security scheme (OpenAPI Components Object → `securitySchemes`). The supported profile is the
+ * `apiKey` type carried in a request header (ADR 0059): a webhook/operation is guarded by a shared
+ * secret. The expected value is never inlined — it is read from an environment variable named by
+ * the `x-nano-secret-env` extension (ADR 0025/0027: secrets stay env pointers).
+ */
+export interface OpenApiSecurityScheme {
+    type?: string;
+    /** For `apiKey`: where the key travels. `header` and `query` are enforced in this slice. */
+    in?: "header" | "query" | "cookie";
+    /** For `apiKey`: the header (or query) name carrying the key, e.g. `X-Webhook-Key`. */
+    name?: string;
+    /** Env var holding the expected secret value. Required to enforce an `apiKey` scheme. */
+    "x-nano-secret-env"?: string;
+    description?: string;
+}
+/** A security requirement: scheme name → scopes (scopes are unused for `apiKey`, always `[]`). An
+ *  operation is authorized when ANY one requirement object is fully satisfied (OR across the list,
+ *  AND within an object). An empty list (`security: []`) means the operation is explicitly open. */
+export type OpenApiSecurityRequirement = Record<string, string[]>;
 export interface OpenApiDoc {
     openapi?: string;
     info?: {
@@ -59,7 +79,10 @@ export interface OpenApiDoc {
     paths?: Record<string, Record<string, unknown>>;
     components?: {
         schemas?: Record<string, OpenApiSchema>;
+        securitySchemes?: Record<string, OpenApiSecurityScheme>;
     };
+    /** Document-level default security, applied to any operation that declares none. */
+    security?: OpenApiSecurityRequirement[];
 }
 /** The HTTP methods we mount, lowercase as they appear as path-item keys. */
 export declare const HTTP_METHODS: readonly ["get", "put", "post", "delete", "patch", "options", "head"];
@@ -76,6 +99,9 @@ export interface OperationInfo {
     requestBodyRequired: boolean;
     /** Schema of the first 2xx (else default) JSON response, when declared. */
     responseSchema?: OpenApiSchema;
+    /** Effective security requirements (op-level if declared — including an explicit empty list —
+     *  else the document-level default, else `[]`). An empty list means the operation is open. */
+    security: OpenApiSecurityRequirement[];
     eject: boolean;
     summary?: string;
 }
@@ -92,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[];
@@ -109,6 +144,34 @@ export declare function isSafeOperationId(id: string): boolean;
  *  path segment. collectOperations skips these (they never mount or drive an import); the runtime
  *  surfaces them at `warn`. */
 export declare function operationsWithUnsafeId(doc: OpenApiDoc): string[];
+/** The outcome of enforcing an operation's security: `ok` when authorized, otherwise the HTTP
+ *  status to return — `401` (the request presented no/invalid credential) or `500` (the app is
+ *  misconfigured: an operation references an unknown scheme, an unsupported scheme type, or a
+ *  scheme whose secret env var is unset). */
+export interface SecurityDecision {
+    ok: boolean;
+    status?: 401 | 500;
+    error?: string;
+}
+/**
+ * Enforce an operation's effective security requirements (ADR 0059). Pure: the caller supplies the
+ * request's header/query readers and an env reader, so all policy lives here (and is unit-tested)
+ * while the impure lookups stay in the runtime.
+ *
+ * Semantics follow OpenAPI: authorized when ANY one requirement object is satisfied (OR), and a
+ * requirement object is satisfied only when ALL its schemes are (AND). An empty requirement list
+ * means the operation is open. Only `apiKey` schemes (in `header` or `query`) are enforced; the
+ * expected value comes from the scheme's `x-nano-secret-env` env var.
+ *
+ * A referenced scheme that is unknown, not `apiKey`, or missing its secret env var is a server
+ * misconfiguration → `500` (fail closed), reported in preference to a `401` so operators see the
+ * real cause. A well-formed scheme with a wrong/absent presented credential → `401`.
+ */
+export declare function evaluateSecurity(doc: OpenApiDoc, op: OperationInfo, getHeader: (name: string) => string | undefined, getQuery: (name: string) => string | undefined, getSecret: (envVar: string) => string | undefined): SecurityDecision;
+/** "scheme (op)" pointers for every operation security requirement that names a scheme absent from
+ *  components.securitySchemes — an app-drift the runtime rejects at request time (500) and the
+ *  `--check` gate can surface ahead of time. */
+export declare function undeclaredSecuritySchemes(doc: OpenApiDoc): string[];
 /** Turn an OpenAPI path template ("/invoices/{id}") into a matcher under `base` ("/app/api"):
  *  a RegExp that captures each `{param}` positionally, plus the ordered path-parameter names. The
  *  runtime matches concrete request paths, so a templated segment becomes a single-segment capture. */

package/dist/openapi/spec.js

@@ -126,6 +126,12 @@ export function collectOperations(doc) {
             const requestBody = isRecord(opRaw.requestBody) ? opRaw.requestBody : undefined;
             const requestBodySchema = firstJsonSchema(isRecord(requestBody?.content) ? requestBody.content : undefined);
             const responses = isRecord(opRaw.responses) ? opRaw.responses : {};
+            // Effective security: an operation's own `security` (even an explicit `[]`, which opts out of
+            // a document-level default) wins; otherwise inherit the document-level default; otherwise open.
+            const rawSecurity = Object.prototype.hasOwnProperty.call(opRaw, "security")
+                ? opRaw.security
+                : doc.security;
+            const security = normalizeSecurity(rawSecurity);
             out.push({
                 operationId,
                 method,
@@ -134,6 +140,7 @@ export function collectOperations(doc) {
                 requestBodySchema,
                 requestBodyRequired: requestBody?.required === true,
                 responseSchema: firstSuccessSchema(responses),
+                security,
                 eject: opRaw["x-urban-eject"] === true,
                 summary: typeof opRaw.summary === "string" ? opRaw.summary : undefined,
             });
@@ -141,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) {
@@ -205,6 +234,145 @@ export function operationsWithUnsafeId(doc) {
     }
     return out;
 }
+const MALFORMED_SECURITY_REQUIREMENT = "__nano_malformed_security_requirement__";
+function malformedSecurityRequirement() {
+    return { [MALFORMED_SECURITY_REQUIREMENT]: [] };
+}
+/** Normalize a raw `security` value into a clean requirement list. Missing → `[]` (open).
+ *  Present-but-malformed values become an impossible marker requirement so enforcement fails closed
+ *  as a 500 misconfiguration instead of silently opening a guarded operation. */
+function normalizeSecurity(raw) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw))
+        return [malformedSecurityRequirement()];
+    const out = [];
+    for (const entry of raw) {
+        if (!isRecord(entry)) {
+            out.push(malformedSecurityRequirement());
+            continue;
+        }
+        const req = {};
+        let malformed = false;
+        for (const [name, scopes] of Object.entries(entry)) {
+            if (!Array.isArray(scopes) || scopes.some((s) => typeof s !== "string")) {
+                malformed = true;
+                break;
+            }
+            req[name] = scopes;
+        }
+        out.push(malformed ? malformedSecurityRequirement() : req);
+    }
+    return out;
+}
+const SECURITY_OK = { ok: true };
+const TEXT_ENCODER = new TextEncoder();
+/** Constant-time string comparison — avoids leaking how many leading characters of a secret matched
+ *  via response timing. Unequal lengths short-circuit (an acceptable length oracle for API keys). */
+function timingSafeEqual(a, b) {
+    const ab = TEXT_ENCODER.encode(a);
+    const bb = TEXT_ENCODER.encode(b);
+    if (ab.length !== bb.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < ab.length; i++)
+        diff |= ab[i] ^ bb[i];
+    return diff === 0;
+}
+/**
+ * Enforce an operation's effective security requirements (ADR 0059). Pure: the caller supplies the
+ * request's header/query readers and an env reader, so all policy lives here (and is unit-tested)
+ * while the impure lookups stay in the runtime.
+ *
+ * Semantics follow OpenAPI: authorized when ANY one requirement object is satisfied (OR), and a
+ * requirement object is satisfied only when ALL its schemes are (AND). An empty requirement list
+ * means the operation is open. Only `apiKey` schemes (in `header` or `query`) are enforced; the
+ * expected value comes from the scheme's `x-nano-secret-env` env var.
+ *
+ * A referenced scheme that is unknown, not `apiKey`, or missing its secret env var is a server
+ * misconfiguration → `500` (fail closed), reported in preference to a `401` so operators see the
+ * real cause. A well-formed scheme with a wrong/absent presented credential → `401`.
+ */
+export function evaluateSecurity(doc, op, getHeader, getQuery, getSecret) {
+    if (op.security.length === 0)
+        return SECURITY_OK;
+    const schemes = doc.components?.securitySchemes ?? {};
+    let misconfig;
+    for (const requirement of op.security) {
+        const names = Object.keys(requirement);
+        if (names.length === 0)
+            return SECURITY_OK; // an empty object is a "no auth" alternative
+        let satisfied = true;
+        for (const name of names) {
+            if (name === MALFORMED_SECURITY_REQUIREMENT) {
+                misconfig ??= "malformed security requirement";
+                satisfied = false;
+                break;
+            }
+            const scheme = schemes[name];
+            if (!scheme) {
+                misconfig ??= `security scheme "${name}" is not declared in components.securitySchemes`;
+                satisfied = false;
+                break;
+            }
+            if (scheme.type !== "apiKey") {
+                misconfig ??= `security scheme "${name}" has unsupported type "${scheme.type ?? "(none)"}" (only apiKey is enforced)`;
+                satisfied = false;
+                break;
+            }
+            const where = scheme.in ?? "header";
+            if (where !== "header" && where !== "query") {
+                misconfig ??= `security scheme "${name}" apiKey location "${where}" is unsupported (use header or query)`;
+                satisfied = false;
+                break;
+            }
+            if (!scheme.name) {
+                misconfig ??= `security scheme "${name}" is missing its apiKey \`name\``;
+                satisfied = false;
+                break;
+            }
+            const envVar = scheme["x-nano-secret-env"];
+            if (!envVar) {
+                misconfig ??= `security scheme "${name}" is missing \`x-nano-secret-env\` (the env var holding the expected key)`;
+                satisfied = false;
+                break;
+            }
+            const expected = getSecret(envVar);
+            if (expected === undefined || expected === "") {
+                misconfig ??= `security scheme "${name}" secret env ${envVar} is not set`;
+                satisfied = false;
+                break;
+            }
+            const presented = where === "header" ? getHeader(scheme.name) : getQuery(scheme.name);
+            if (presented === undefined || !timingSafeEqual(presented, expected)) {
+                satisfied = false; // a wrong/absent credential → 401 (not a misconfig)
+                break;
+            }
+        }
+        if (satisfied)
+            return SECURITY_OK;
+    }
+    return misconfig
+        ? { ok: false, status: 500, error: `security misconfigured: ${misconfig}` }
+        : { ok: false, status: 401, error: "unauthorized" };
+}
+/** "scheme (op)" pointers for every operation security requirement that names a scheme absent from
+ *  components.securitySchemes — an app-drift the runtime rejects at request time (500) and the
+ *  `--check` gate can surface ahead of time. */
+export function undeclaredSecuritySchemes(doc) {
+    const declared = new Set(Object.keys(doc.components?.securitySchemes ?? {}));
+    const out = [];
+    for (const op of collectOperations(doc)) {
+        for (const requirement of op.security) {
+            for (const name of Object.keys(requirement)) {
+                if (name !== MALFORMED_SECURITY_REQUIREMENT && !declared.has(name)) {
+                    out.push(`${name} (${op.method.toUpperCase()} ${op.path})`);
+                }
+            }
+        }
+    }
+    return out;
+}
 function normalizeParameters(raw) {
     // OpenAPI: parameters are uniquely identified by (name, in). A path-level parameter can be
     // overridden by an operation-level one with the same (name, in) — never duplicated. Callers pass

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,9 +12,10 @@
 // `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, validateValue, } from "../../../openapi/spec.js";
+import { collectOperations, isSafeOperationId, operationsWithoutId, operationsWithUnsafeId, parseSpec, resolveSchema, toRouteMatcher, undeclaredPathParams, undeclaredSecuritySchemes, evaluateSecurity, validateValue, } from "../../../openapi/spec.js";
 /** The canonical, non-configurable mount prefix for an app's OpenAPI operations. Operations always
  *  live under `/app/api` so page actions, links, and any `callRoute` can name an operation path as a
  *  stable framework constant (`/app/api/<op path>`) — there is no per-app `base` knob to drift. */
@@ -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 = () => {
@@ -229,6 +288,10 @@ export function mountApi(ctx, app) {
                 if (unsafe.length > 0) {
                     ctx.host.log("warn", "OpenAPI operationIds that are not a safe path segment are skipped (ADR 0058)", { 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 };
@@ -270,6 +333,19 @@ export function mountApi(ctx, app) {
         }
         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 = {};
@@ -358,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", {
@@ -401,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) => {