@nanobpm/urban 0.35.0 → 0.36.0

package/src/toolkit/derivers/api.ts

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

package/src/toolkit/gen.ts

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

package/src/toolkit/generate.test.ts

@@ -0,0 +1,135 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { generate } from "./generate.ts";
+import type { GenIO } from "./gen.ts";
+
+/** In-memory filesystem mirroring gen.test.ts's memIO (IO-free, deterministic). */
+function memIO(files: Record<string, string>): GenIO & { files: Record<string, string> } {
+  return {
+    files,
+    async readText(p) {
+      if (!(p in files)) throw new Error(`ENOENT ${p}`);
+      return files[p];
+    },
+    async writeText(p, c) {
+      files[p] = c;
+    },
+    async listDir(p) {
+      const prefix = p.replace(/\/+$/, "") + "/";
+      const names = new Set<string>();
+      for (const f of Object.keys(files)) {
+        if (f.startsWith(prefix)) {
+          const rest = f.slice(prefix.length);
+          if (!rest.includes("/")) names.add(rest);
+        }
+      }
+      return [...names];
+    },
+    async exists(p) {
+      return p in files;
+    },
+    async remove(p) {
+      delete files[p];
+    },
+  };
+}
+
+const MANIFEST = JSON.stringify({
+  id: "demo",
+  data: { default: "app" },
+  models: { processes: ["processes/*.bpmn"] },
+  types: { greeting: { table: "greetings", fields: { who: { type: "string" } } } },
+  api: { spec: "openapi.json" },
+});
+
+const BPMN = `<bpmn:process id="p" xmlns:bpmn="x" xmlns:zeebe="y">
+  <bpmn:serviceTask id="T"><bpmn:extensionElements>
+    <zeebe:taskDefinition type="demo.do" />
+  </bpmn:extensionElements></bpmn:serviceTask>
+</bpmn:process>`;
+
+const OPENAPI = JSON.stringify({
+  openapi: "3.0.0",
+  paths: {
+    "/ping": { get: { operationId: "ping", responses: { "200": {} } } },
+  },
+});
+
+function fixture(): Record<string, string> {
+  return {
+    "/app/nano.app.json": MANIFEST,
+    "/app/processes/p.bpmn": BPMN,
+    "/app/openapi.json": OPENAPI,
+  };
+}
+
+test("generate write mode scaffolds worker + operation stubs alongside derived artifacts", async () => {
+  const io = memIO(fixture());
+  const res = await generate({ root: "/app", io });
+
+  // Derived artifacts landed (the runGen half).
+  assert.ok(io.files["/app/nano-generated/worker-io.d.ts"], "expected derived worker-io");
+  assert.ok(io.files["/app/nano-generated/app.schema.sql"], "expected derived migrations");
+
+  // Worker stub created + wired into the manifest.
+  assert.deepEqual(
+    res.workerStubs.map((s) => s.status),
+    ["created"],
+  );
+  assert.ok(io.files["/app/workers/demo-do/worker.ts"], "expected a worker stub on disk");
+  assert.ok(res.manifestPatched, "expected workers[] to be patched");
+  assert.equal(res.wiredWorkers.length, 1);
+
+  // Operation stub created.
+  assert.deepEqual(
+    res.operationStubs.map((s) => s.status),
+    ["created"],
+  );
+  assert.ok(io.files["/app/operations/ping.ts"], "expected an operation stub on disk");
+
+  // Write mode never reports missing stubs.
+  assert.deepEqual(res.missingStubs, []);
+});
+
+test("generate --check writes nothing and reports would-create stubs as missing", async () => {
+  const io = memIO(fixture());
+  // Pre-derive so the only drift under --check comes from the missing stubs.
+  await generate({ root: "/app", io });
+  const before = { ...io.files };
+
+  const res = await generate({ root: "/app", io, check: true });
+
+  // Nothing changed on disk (both derivation and scaffolding are write-free under --check).
+  assert.deepEqual(io.files, before, "--check must not write");
+
+  // The already-created stubs are kept, so nothing is missing this run.
+  assert.deepEqual(res.missingStubs, []);
+  assert.deepEqual(res.drift, []);
+});
+
+test("generate --check surfaces an uncommitted stub via missingStubs (the CI drift catch)", async () => {
+  const io = memIO(fixture());
+  const before = { ...io.files };
+
+  const res = await generate({ root: "/app", io, check: true });
+
+  assert.deepEqual(io.files, before, "--check must not write");
+  assert.deepEqual(
+    res.missingStubs.sort(),
+    ["operations/ping.ts", "workers/demo-do/worker.ts"],
+  );
+});
+
+test("generate keeps existing human-owned stubs (write-once, never clobbered)", async () => {
+  const io = memIO(fixture());
+  io.files["/app/workers/demo-do/worker.ts"] = "// hand-authored body";
+  io.files["/app/operations/ping.ts"] = "// hand-authored delegate";
+
+  const res = await generate({ root: "/app", io });
+
+  assert.equal(io.files["/app/workers/demo-do/worker.ts"], "// hand-authored body");
+  assert.equal(io.files["/app/operations/ping.ts"], "// hand-authored delegate");
+  assert.deepEqual(res.workerStubs.map((s) => s.status), ["kept"]);
+  assert.deepEqual(res.operationStubs.map((s) => s.status), ["kept"]);
+  assert.deepEqual(res.missingStubs, []);
+});

package/src/toolkit/generate.ts

@@ -0,0 +1,71 @@
+// `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 type { GenOptions, GenResult } from "./gen.ts";
+import { runGen } from "./gen.ts";
+import type { OperationStubOutcome, StubOutcome } from "./scaffold.ts";
+import { scaffoldOperations, scaffoldWorkers } 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 async function generate(opts: GenOptions & { check?: boolean }): Promise<GenerateResult> {
+  const res = await runGen(opts);
+
+  const empty: GenerateResult = {
+    ...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/src/toolkit/index.ts

@@ -103,9 +103,11 @@ export {
   deriveApi,
   emitApiBindings,
   emitApiBindingsRuntime,
+  emitApiController,
   schemaToTs,
   API_BINDINGS_DTS,
   API_BINDINGS_TS,
+  API_CONTROLLER_TS,
 } from "./derivers/api.ts";
 
 // The OpenAPI machinery the deriver + runtime share (ADR 0058).
@@ -149,6 +151,8 @@ export const DERIVERS = [
 // Gen orchestrator + IO
 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";
 
 // Code-first model derivation (workflows/*.ts → BPMN)
@@ -180,5 +184,11 @@ export type {
 export { scaffoldWorkers } from "./scaffold.ts";
 export type { ScaffoldOptions, ScaffoldRun, StubOutcome, StubStatus } from "./scaffold.ts";
 
+// Operation-delegate scaffolder (ADR 0059): write-once typed delegate stubs from the OpenAPI spec.
+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/src/toolkit/scaffold/operations.test.ts

@@ -0,0 +1,136 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { planOperationScaffold, renderOperationStub } from "./operations.ts";
+import { scaffoldOperations } from "../scaffold.ts";
+import type { GenIO } from "../gen.ts";
+import type { OpenApiDoc } from "../../openapi/spec.ts";
+
+const doc: OpenApiDoc = {
+  openapi: "3.0.0",
+  paths: {
+    "/invoices/{id}": {
+      get: {
+        operationId: "getInvoice",
+        parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }],
+        responses: { "200": {} },
+      },
+    },
+    "/invoices": {
+      post: { operationId: "createInvoice", responses: { "201": {} } },
+    },
+  },
+};
+
+test("renderOperationStub is a typed default-exported delegate that throws NotImplemented", () => {
+  const stub = renderOperationStub("getInvoice");
+  assert.match(stub, /import \{ NotImplemented \} from "@nanobpm\/urban";/);
+  assert.match(stub, /import \{ defineOperation \} from "\.\.\/nano-generated\/operations\.ts";/);
+  assert.match(stub, /export default defineOperation\("getInvoice", async \(input, app\) =>/);
+  assert.match(stub, /throw new NotImplemented\("getInvoice"\);/);
+});
+
+test("renderOperationStub adjusts the generated-import depth for a nested api.dir", () => {
+  const stub = renderOperationStub("getInvoice", "api/handlers");
+  assert.match(stub, /import \{ defineOperation \} from "\.\.\/\.\.\/nano-generated\/operations\.ts";/);
+});
+
+test("planOperationScaffold plans one stub per declared operationId", () => {
+  const plans = planOperationScaffold(doc);
+  const byId = Object.fromEntries(plans.map((p) => [p.operationId, p.handlerPath]));
+  assert.deepEqual(byId, {
+    getInvoice: "operations/getInvoice.ts",
+    createInvoice: "operations/createInvoice.ts",
+  });
+});
+
+test("planOperationScaffold honors a custom api.dir", () => {
+  const plans = planOperationScaffold(doc, "handlers");
+  assert.ok(plans.every((p) => p.handlerPath.startsWith("handlers/")));
+});
+
+test("planOperationScaffold throws on a duplicate operationId (incoherent spec)", () => {
+  const dupe: OpenApiDoc = {
+    openapi: "3.0.0",
+    paths: {
+      "/a": { get: { operationId: "same", responses: { "200": {} } } },
+      "/b": { get: { operationId: "same", responses: { "200": {} } } },
+    },
+  };
+  assert.throws(() => planOperationScaffold(dupe), /duplicate operationId\(s\): same/);
+});
+
+function memIO(files: Record<string, string>): GenIO & { files: Record<string, string> } {
+  return {
+    files,
+    async readText(p) {
+      if (!(p in files)) throw new Error(`ENOENT ${p}`);
+      return files[p];
+    },
+    async writeText(p, c) {
+      files[p] = c;
+    },
+    async listDir(p) {
+      const prefix = p.replace(/\/+$/, "") + "/";
+      const names = new Set<string>();
+      for (const f of Object.keys(files)) {
+        if (f.startsWith(prefix)) {
+          const rest = f.slice(prefix.length);
+          if (!rest.includes("/")) names.add(rest);
+        }
+      }
+      return [...names];
+    },
+    async exists(p) {
+      return p in files;
+    },
+  };
+}
+
+function appFixture(): Record<string, string> {
+  return {
+    "/app/nano.app.json": JSON.stringify({ id: "demo", api: { spec: "openapi.json" } }),
+    "/app/openapi.json": JSON.stringify(doc),
+  };
+}
+
+test("scaffoldOperations is a no-op when the app declares no api binding", async () => {
+  const io = memIO({ "/app/nano.app.json": JSON.stringify({ id: "demo" }) });
+  const run = await scaffoldOperations({ root: "/app", io, write: true });
+  assert.deepEqual(run.outcomes, []);
+});
+
+test("scaffoldOperations dry-run writes nothing and reports would-create per op", async () => {
+  const io = memIO(appFixture());
+  const before = Object.keys(io.files).length;
+  const run = await scaffoldOperations({ root: "/app", io });
+  assert.equal(run.write, false);
+  assert.equal(Object.keys(io.files).length, before, "dry-run must not write");
+  assert.deepEqual(run.outcomes.map((o) => o.status).sort(), ["would-create", "would-create"]);
+});
+
+test("scaffoldOperations --write creates one typed stub per op", async () => {
+  const io = memIO(appFixture());
+  const run = await scaffoldOperations({ root: "/app", io, write: true });
+  assert.ok(run.outcomes.every((o) => o.status === "created"));
+  assert.match(io.files["/app/operations/getInvoice.ts"], /NotImplemented\("getInvoice"\)/);
+  assert.match(io.files["/app/operations/createInvoice.ts"], /NotImplemented\("createInvoice"\)/);
+});
+
+test("scaffoldOperations never clobbers an existing delegate (keeps it)", async () => {
+  const files = appFixture();
+  files["/app/operations/getInvoice.ts"] = "// hand-written, do not touch\n";
+  const io = memIO(files);
+  const run = await scaffoldOperations({ root: "/app", io, write: true });
+  assert.equal(io.files["/app/operations/getInvoice.ts"], "// hand-written, do not touch\n");
+  assert.equal(run.outcomes.find((o) => o.operationId === "getInvoice")?.status, "kept");
+  assert.equal(run.outcomes.find((o) => o.operationId === "createInvoice")?.status, "created");
+});
+
+test("scaffoldOperations is idempotent: a second --write run keeps everything", async () => {
+  const io = memIO(appFixture());
+  await scaffoldOperations({ root: "/app", io, write: true });
+  const snapshot = JSON.stringify(io.files);
+  const run2 = await scaffoldOperations({ root: "/app", io, write: true });
+  assert.ok(run2.outcomes.every((o) => o.status === "kept"));
+  assert.equal(JSON.stringify(io.files), snapshot, "files unchanged on re-run");
+});

package/src/toolkit/scaffold/operations.ts

@@ -0,0 +1,75 @@
+// 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.ts";
+import { assertUniqueOperationIds, collectOperations, 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;
+}
+
+/** 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: string): string {
+  return normalizeApiDir(dir);
+}
+
+/** Number of `../` hops from `<dir>/<file>.ts` back up to the app root (dir may be nested). */
+function upToRoot(dir: string): string {
+  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: string, dir: string = DEFAULT_OPERATIONS_DIR): string {
+  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: OpenApiDoc,
+  dir: string = DEFAULT_OPERATIONS_DIR,
+): OperationStubPlan[] {
+  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/src/toolkit/scaffold/workers.ts

@@ -92,7 +92,7 @@ export function renderWorkerStub(
 
   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/src/toolkit/scaffold.ts

@@ -11,12 +11,15 @@ import {
   type SkippedWorker,
   type StubManifestEntry,
 } from "./scaffold/workers.ts";
+import { planOperationScaffold } from "./scaffold/operations.ts";
+import { parseSpec } from "../openapi/spec.ts";
 
 /** The manifest fields the scaffolder reads. */
 interface ScaffoldManifest {
   types?: Record<string, unknown>;
   models?: { processes?: string[] };
   workers?: ScaffoldWorker[];
+  api?: { spec?: string; dir?: string };
 }
 
 export interface ScaffoldOptions {
@@ -102,3 +105,56 @@ export async function scaffoldWorkers(opts: ScaffoldOptions): Promise<ScaffoldRu
 
   return { outcomes, skipped, wired, manifestPatched, write };
 }
+
+/** 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 async function scaffoldOperations(opts: ScaffoldOptions): Promise<OperationScaffoldRun> {
+  const { root, io } = opts;
+  const write = opts.write ?? false;
+  const manifestFile = opts.manifestFile ?? "nano.app.json";
+  const manifestPath = joinPath(root, manifestFile);
+
+  const manifest: ScaffoldManifest = 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: OperationStubOutcome[] = [];
+  for (const plan of plans) {
+    const abs = joinPath(root, plan.handlerPath);
+    const exists = await io.exists(abs);
+    let status: StubStatus;
+    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 };
+}