@nanobpm/urban 0.34.0 → 0.36.0

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),
 };

package/dist/toolkit/gen.js

@@ -98,7 +98,10 @@ async function collectAll(opts) {
     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 };
 }

package/dist/toolkit/generate.d.ts

@@ -0,0 +1,27 @@
+import type { GenOptions, GenResult } from "./gen.ts";
+import type { OperationStubOutcome, StubOutcome } from "./scaffold.ts";
+import type { StubManifestEntry } from "./scaffold/workers.ts";
+export interface GenerateResult extends GenResult {
+    /** Worker-stub scaffolding outcomes (created / kept / would-create). */
+    workerStubs: StubOutcome[];
+    /** Operation-delegate scaffolding outcomes (created / kept / would-create). */
+    operationStubs: OperationStubOutcome[];
+    /** Worker manifest entries wired into `workers[]` (write mode only). */
+    wiredWorkers: StubManifestEntry[];
+    /** True when `workers[]` was patched (write mode, unwired workers present). */
+    manifestPatched: boolean;
+    /**
+     * App-relative paths of stubs that would be created — the scaffolding equivalent of `drift`.
+     * Populated in `check` mode (nothing is written); a caller should fail CI when non-empty.
+     */
+    missingStubs: string[];
+}
+/**
+ * Derive artifacts and scaffold the write-once handler stubs they reference, in one pass.
+ * In `check` mode nothing is written and any would-be-created stub is reported in `missingStubs`.
+ * Scaffolding is skipped when derivation is `incomplete` (never scaffold from a half-derived model);
+ * the caller reports the derivation failure first.
+ */
+export declare function generate(opts: GenOptions & {
+    check?: boolean;
+}): Promise<GenerateResult>;

package/dist/toolkit/generate.js

@@ -0,0 +1,47 @@
+// `urban gen`: the whole generation concern in one pass — derive artifacts (migrations, worker-I/O,
+// code-first models, OpenAPI contracts + controller) AND scaffold the write-once handler stubs those
+// artifacts reference (worker stubs from the model, operation-delegate stubs from the OpenAPI spec).
+//
+// This composes the pure derivation (`runGen`, gen.ts) with the write-once scaffolders (scaffold.ts)
+// WITHOUT a cycle: scaffold.ts already depends on gen.ts, so this leaf module depends on both and
+// neither depends back. Scaffolding is write-once (an existing, human-owned stub is never clobbered),
+// so folding it into `gen` is idempotent. `--check` writes nothing: a missing stub surfaces in
+// `missingStubs` exactly like a drifted artifact surfaces in `drift`, so CI fails when a stub the
+// generated controller imports isn't committed.
+import { runGen } from "./gen.js";
+import { scaffoldOperations, scaffoldWorkers } from "./scaffold.js";
+/**
+ * Derive artifacts and scaffold the write-once handler stubs they reference, in one pass.
+ * In `check` mode nothing is written and any would-be-created stub is reported in `missingStubs`.
+ * Scaffolding is skipped when derivation is `incomplete` (never scaffold from a half-derived model);
+ * the caller reports the derivation failure first.
+ */
+export async function generate(opts) {
+    const res = await runGen(opts);
+    const empty = {
+        ...res,
+        workerStubs: [],
+        operationStubs: [],
+        wiredWorkers: [],
+        manifestPatched: false,
+        missingStubs: [],
+    };
+    if (res.incomplete)
+        return empty;
+    const write = !opts.check;
+    const scaffoldOpts = { root: opts.root, io: opts.io, manifestFile: opts.manifestFile, write };
+    const workers = await scaffoldWorkers(scaffoldOpts);
+    const operations = await scaffoldOperations(scaffoldOpts);
+    const missingStubs = [
+        ...workers.outcomes.filter((o) => o.status === "would-create").map((o) => o.handlerPath),
+        ...operations.outcomes.filter((o) => o.status === "would-create").map((o) => o.handlerPath),
+    ];
+    return {
+        ...res,
+        workerStubs: workers.outcomes,
+        operationStubs: operations.outcomes,
+        wiredWorkers: workers.wired,
+        manifestPatched: workers.manifestPatched,
+        missingStubs,
+    };
+}

package/dist/toolkit/index.d.ts

@@ -13,7 +13,7 @@ export { deriveMeta, emitMeta, foldMeta, metaDeriver, scanModelMeta, META_TS, }
 export type { MetaDecl } from "./derivers/meta.ts";
 export { deriveMessageBindings, emitMessageBindings, emitMessageBindingsRuntime, messagesDeriver, scanModelMessages, MESSAGE_BINDINGS_DTS, MESSAGE_BINDINGS_TS, } from "./derivers/messages.ts";
 export type { MessageIo, MessageBindingDecl } from "./derivers/messages.ts";
-export { apiDeriver, deriveApi, emitApiBindings, emitApiBindingsRuntime, schemaToTs, API_BINDINGS_DTS, API_BINDINGS_TS, } from "./derivers/api.ts";
+export { apiDeriver, deriveApi, emitApiBindings, emitApiBindingsRuntime, emitApiController, schemaToTs, API_BINDINGS_DTS, API_BINDINGS_TS, API_CONTROLLER_TS, } from "./derivers/api.ts";
 export { collectOperations, HTTP_METHODS, isSafeOperationId, operationsWithoutId, operationsWithUnsafeId, parseSpec, refName, resolveSchema, toRouteMatcher, undeclaredPathParams, validateValue, } from "../openapi/spec.ts";
 export type { HttpMethodLower, OpenApiDoc, OpenApiParameter, OpenApiSchema, OperationInfo, } from "../openapi/spec.ts";
 export declare const DERIVERS: readonly [import("./artifact.ts").Deriver<import("./derivers/migrations.ts").ToolkitManifest>, import("./artifact.ts").Deriver<import("./derivers/migrations.ts").ToolkitManifest>, import("./artifact.ts").Deriver<{
@@ -26,9 +26,12 @@ export declare const DERIVERS: readonly [import("./artifact.ts").Deriver<import(
     declaredTypeIds: Iterable<string>;
 }>, import("./artifact.ts").Deriver<{
     doc: import("../openapi/spec.ts").OpenApiDoc;
+    operationsDir?: string;
 }>];
 export { collectArtifacts, runGen, joinPath, readModels, expandPattern, previewModels } from "./gen.ts";
 export type { GenIO, GenOptions, GenResult } from "./gen.ts";
+export { generate } from "./generate.ts";
+export type { GenerateResult } from "./generate.ts";
 export { createNodeGenIO } from "./fsio.ts";
 export { deriveModels, isWorkflow, bpmnFilename, processesOutDir, DEFAULT_WORKFLOW_PATTERNS, PROCESSES_DIR, MODEL_PROVENANCE, } from "./models.ts";
 export type { DerivedModels, DerivedModelInfo, ModelError, ModelsManifest } from "./models.ts";
@@ -36,5 +39,9 @@ export { planWorkerScaffold, renderWorkerStub, slugifyTaskType, } from "./scaffo
 export type { ScaffoldWorker, SkippedWorker, SkipReason, StubManifestEntry, WorkerScaffoldPlan, WorkerStubPlan, } from "./scaffold/workers.ts";
 export { scaffoldWorkers } from "./scaffold.ts";
 export type { ScaffoldOptions, ScaffoldRun, StubOutcome, StubStatus } from "./scaffold.ts";
+export { planOperationScaffold, renderOperationStub } from "./scaffold/operations.ts";
+export type { OperationStubPlan } from "./scaffold/operations.ts";
+export { scaffoldOperations } from "./scaffold.ts";
+export type { OperationScaffoldRun, OperationStubOutcome } from "./scaffold.ts";
 export { addConnector } from "./addConnector.ts";
 export type { AddConnectorOptions, AddConnectorResult } from "./addConnector.ts";

package/dist/toolkit/index.js

@@ -11,7 +11,7 @@ export { deriveWorkerBindings, emitWorkerBindings, emitWorkerBindingsRuntime, ov
 export { byModelPath, typeRefFor } from "./derivers/worker-io.js";
 export { deriveMeta, emitMeta, foldMeta, metaDeriver, scanModelMeta, META_TS, } from "./derivers/meta.js";
 export { deriveMessageBindings, emitMessageBindings, emitMessageBindingsRuntime, messagesDeriver, scanModelMessages, MESSAGE_BINDINGS_DTS, MESSAGE_BINDINGS_TS, } from "./derivers/messages.js";
-export { apiDeriver, deriveApi, emitApiBindings, emitApiBindingsRuntime, schemaToTs, API_BINDINGS_DTS, API_BINDINGS_TS, } from "./derivers/api.js";
+export { apiDeriver, deriveApi, emitApiBindings, emitApiBindingsRuntime, emitApiController, schemaToTs, API_BINDINGS_DTS, API_BINDINGS_TS, API_CONTROLLER_TS, } from "./derivers/api.js";
 // The OpenAPI machinery the deriver + runtime share (ADR 0058).
 export { collectOperations, HTTP_METHODS, isSafeOperationId, operationsWithoutId, operationsWithUnsafeId, parseSpec, refName, resolveSchema, toRouteMatcher, undeclaredPathParams, validateValue, } from "../openapi/spec.js";
 // The registry of all derivers (for discovery / IDE migration).
@@ -31,10 +31,14 @@ export const DERIVERS = [
 ];
 // Gen orchestrator + IO
 export { collectArtifacts, runGen, joinPath, readModels, expandPattern, previewModels } from "./gen.js";
+export { generate } from "./generate.js";
 export { createNodeGenIO } from "./fsio.js";
 // Code-first model derivation (workflows/*.ts → BPMN)
 export { deriveModels, isWorkflow, bpmnFilename, processesOutDir, DEFAULT_WORKFLOW_PATTERNS, PROCESSES_DIR, MODEL_PROVENANCE, } from "./models.js";
 // Worker-stub scaffolder (ADR 0056): write-once handler stubs from the model.
 export { planWorkerScaffold, renderWorkerStub, slugifyTaskType, } from "./scaffold/workers.js";
 export { scaffoldWorkers } from "./scaffold.js";
+// Operation-delegate scaffolder (ADR 0059): write-once typed delegate stubs from the OpenAPI spec.
+export { planOperationScaffold, renderOperationStub } from "./scaffold/operations.js";
+export { scaffoldOperations } from "./scaffold.js";
 export { addConnector } from "./addConnector.js";

package/dist/toolkit/scaffold/operations.d.ts

@@ -0,0 +1,21 @@
+import { DEFAULT_OPERATIONS_DIR } from "../api-dir.ts";
+import { type OpenApiDoc } from "../../openapi/spec.ts";
+export { DEFAULT_OPERATIONS_DIR };
+/** One planned operation-delegate stub. */
+export interface OperationStubPlan {
+    operationId: string;
+    /** App-relative delegate path: `<dir>/<operationId>.ts`. */
+    handlerPath: string;
+    /** The stub file contents (a typed `defineOperation` that throws `NotImplemented` → HTTP 501). */
+    stub: string;
+}
+/** Render a stub matching a real hand-authored operation delegate (default-exported, typed via the
+ *  generated `defineOperation`). It throws `NotImplemented` so the endpoint returns 501 until the
+ *  body is implemented — never a silent 500, never a drift from the contract. */
+export declare function renderOperationStub(operationId: string, dir?: string): string;
+/**
+ * Plan write-once delegate stubs from the spec: one per declared `operationId` (collectOperations
+ * already skips ops without a safe id). The planner emits a plan for every operation; the impure
+ * edge (`scaffoldOperations`) keeps an existing file verbatim and creates only the absent ones.
+ */
+export declare function planOperationScaffold(doc: OpenApiDoc, dir?: string): OperationStubPlan[];

package/dist/toolkit/scaffold/operations.js

@@ -0,0 +1,55 @@
+// Pure planner for the write-once operation-delegate scaffolder (ADR 0059). Given a parsed OpenAPI
+// document, it plans one typed delegate stub per declared `operationId` — the ONE part of the HTTP
+// surface that cannot be derived from the spec (the handler *body* is human logic). Everything here
+// is pure and testable like a deriver; the impure write-if-absent edge lives in `../scaffold.ts`.
+//
+// scaffold ≠ derive: stubs are human-owned files under `<dir>/<operationId>.ts`, so they are planned
+// once and never overwritten — unlike the derived `nano-generated/` tree (which includes the
+// controller registry that statically imports these delegates and type-checks the whole set).
+import { DEFAULT_OPERATIONS_DIR, normalizeApiDir } from "../api-dir.js";
+import { assertUniqueOperationIds, collectOperations } from "../../openapi/spec.js";
+export { DEFAULT_OPERATIONS_DIR };
+/** Normalize an `api.dir` to a clean relative segment (see `normalizeApiDir`); rejects absolute
+ *  paths and `..` segments so stubs are scaffolded where the runtime resolves delegates from. */
+function normalizeDir(dir) {
+    return normalizeApiDir(dir);
+}
+/** Number of `../` hops from `<dir>/<file>.ts` back up to the app root (dir may be nested). */
+function upToRoot(dir) {
+    const depth = dir.split("/").filter((s) => s.length > 0).length;
+    return "../".repeat(depth);
+}
+/** Render a stub matching a real hand-authored operation delegate (default-exported, typed via the
+ *  generated `defineOperation`). It throws `NotImplemented` so the endpoint returns 501 until the
+ *  body is implemented — never a silent 500, never a drift from the contract. */
+export function renderOperationStub(operationId, dir = DEFAULT_OPERATIONS_DIR) {
+    const up = upToRoot(normalizeDir(dir));
+    const key = JSON.stringify(operationId);
+    return (`// Operation delegate stub for the \`${operationId}\` endpoint, scaffolded from the OpenAPI spec\n` +
+        `// (ADR 0059). This file is yours to edit — \`urban gen\` will never overwrite it. The\n` +
+        `// generated controller (nano-generated/controller.ts) imports this default export and\n` +
+        `// type-checks it against the spec, so the signature cannot drift. Implement the body below\n` +
+        `// (the validated \`{ req, params, query, body }\` input + the injected \`app\`) and delete the throw.\n` +
+        `import { NotImplemented } from "@nanobpm/urban";\n` +
+        `import { defineOperation } from ${JSON.stringify(`${up}nano-generated/operations.ts`)};\n` +
+        `\n` +
+        `export default defineOperation(${key}, async (input, app) => {\n` +
+        `  // \`input\` is the validated request (params/query/body/req); reach app state + services\n` +
+        `  // through the injected \`app\` API. Return \`{ status?, headers?, body? }\` (or nothing → 204).\n` +
+        `  throw new NotImplemented(${key});\n` +
+        `});\n`);
+}
+/**
+ * Plan write-once delegate stubs from the spec: one per declared `operationId` (collectOperations
+ * already skips ops without a safe id). The planner emits a plan for every operation; the impure
+ * edge (`scaffoldOperations`) keeps an existing file verbatim and creates only the absent ones.
+ */
+export function planOperationScaffold(doc, dir = DEFAULT_OPERATIONS_DIR) {
+    assertUniqueOperationIds(doc);
+    const cleanDir = normalizeDir(dir);
+    return collectOperations(doc).map((op) => ({
+        operationId: op.operationId,
+        handlerPath: `${cleanDir}/${op.operationId}.ts`,
+        stub: renderOperationStub(op.operationId, cleanDir),
+    }));
+}

package/dist/toolkit/scaffold/workers.js

@@ -41,7 +41,7 @@ export function renderWorkerStub(taskType, typedIn, typedOut) {
         ? `  // \`job.variables\` is typed as WorkerInputs[${key}].`
         : `  // \`job.variables\` is an open Record<string, unknown> (no declared input type).`;
     return (`// Handler stub for the \`${taskType}\` service task, scaffolded from the model (ADR 0056).\n` +
-        `// This file is yours to edit — \`urban stubs\` will never overwrite it. Implement the body\n` +
+        `// This file is yours to edit — \`urban gen\` will never overwrite it. Implement the body\n` +
         `// below (use \`app.data.table(...)\` for state) and delete the throw.\n` +
         `import type { AppJobHandler } from "@nanobpm/urban/worker";\n` +
         generatedImport +

package/dist/toolkit/scaffold.d.ts

@@ -29,3 +29,19 @@ export interface ScaffoldRun {
 }
 /** Scaffold write-once worker stubs from the model, wiring them into `manifest.workers[]`. */
 export declare function scaffoldWorkers(opts: ScaffoldOptions): Promise<ScaffoldRun>;
+/** One planned operation-delegate outcome (write-once). */
+export interface OperationStubOutcome {
+    operationId: string;
+    handlerPath: string;
+    status: StubStatus;
+}
+export interface OperationScaffoldRun {
+    outcomes: OperationStubOutcome[];
+    write: boolean;
+}
+/**
+ * Scaffold write-once operation-delegate stubs from the app's OpenAPI spec (ADR 0059). One typed
+ * `defineOperation` stub per declared `operationId`, created only if absent (human-owned files are
+ * kept verbatim). Dry-run by default. A no-op when the app declares no `api.spec`.
+ */
+export declare function scaffoldOperations(opts: ScaffoldOptions): Promise<OperationScaffoldRun>;

package/dist/toolkit/scaffold.js

@@ -4,6 +4,8 @@
 // human-owned, so an existing file is KEPT verbatim, never clobbered (the opposite of `runGen`).
 import { joinPath, readModels } from "./gen.js";
 import { planWorkerScaffold, } from "./scaffold/workers.js";
+import { planOperationScaffold } from "./scaffold/operations.js";
+import { parseSpec } from "../openapi/spec.js";
 /** Scaffold write-once worker stubs from the model, wiring them into `manifest.workers[]`. */
 export async function scaffoldWorkers(opts) {
     const { root, io } = opts;
@@ -52,3 +54,41 @@ export async function scaffoldWorkers(opts) {
     }
     return { outcomes, skipped, wired, manifestPatched, write };
 }
+/**
+ * Scaffold write-once operation-delegate stubs from the app's OpenAPI spec (ADR 0059). One typed
+ * `defineOperation` stub per declared `operationId`, created only if absent (human-owned files are
+ * kept verbatim). Dry-run by default. A no-op when the app declares no `api.spec`.
+ */
+export async function scaffoldOperations(opts) {
+    const { root, io } = opts;
+    const write = opts.write ?? false;
+    const manifestFile = opts.manifestFile ?? "nano.app.json";
+    const manifestPath = joinPath(root, manifestFile);
+    const manifest = JSON.parse(await io.readText(manifestPath));
+    const specRef = typeof manifest.api?.spec === "string" ? manifest.api.spec.trim() : "";
+    if (specRef.length === 0)
+        return { outcomes: [], write };
+    const specText = await io.readText(joinPath(root, specRef));
+    const dir = typeof manifest.api?.dir === "string" && manifest.api.dir.trim().length > 0
+        ? manifest.api.dir.trim()
+        : undefined;
+    const plans = planOperationScaffold(parseSpec(specText), dir);
+    const outcomes = [];
+    for (const plan of plans) {
+        const abs = joinPath(root, plan.handlerPath);
+        const exists = await io.exists(abs);
+        let status;
+        if (exists) {
+            status = "kept"; // human-owned — never clobber
+        }
+        else if (write) {
+            await io.writeText(abs, plan.stub);
+            status = "created";
+        }
+        else {
+            status = "would-create";
+        }
+        outcomes.push({ operationId: plan.operationId, handlerPath: plan.handlerPath, status });
+    }
+    return { outcomes, write };
+}