@nanobpm/urban 0.13.0 → 0.15.0

package/dist/cli.js

@@ -11,7 +11,7 @@
 //               --port <n>, -h/--help, -v/--version.
 import { collectManifestIssues, installSignalHandlers, loadManifest, runDev, runFromEnv, selectHost, } from "./runtime/index.js";
 import { scaffold, slugify } from "create-urban-app";
-import { createNodeGenIO, runGen } from "./toolkit/index.js";
+import { createNodeGenIO, runGen, scaffoldWorkers } from "./toolkit/index.js";
 import { pathToFileURL } from "node:url";
 import { readFileSync } from "node:fs";
 // Read the package version from package.json (one hop up from both src/cli.ts and the
@@ -27,7 +27,7 @@ function readVersion() {
 }
 const VERSION = readVersion();
 function parse(argv) {
-    const f = { root: ".", manifest: "nano.app.json", check: false, deno: false, help: false, version: false, _: [] };
+    const f = { root: ".", manifest: "nano.app.json", check: false, write: false, deno: false, help: false, version: false, _: [] };
     const need = (i, flag) => {
         const v = argv[i];
         if (v === undefined || v.startsWith("-"))
@@ -42,6 +42,8 @@ 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 === "--")
@@ -71,6 +73,7 @@ Usage:
   urban new <name> [--root <path>] [--deno]    scaffold a new Urban app
   urban check                       validate the manifest
   urban gen [--check]               derive artifacts (migrations, worker-io)
+  urban stubs [--write]             scaffold write-once handler stubs from the model
   urban run                         materialize + serve the app
   urban dev                         run + watch sources, hot-reload on change
   urban deploy                      deploy models only, then exit
@@ -117,6 +120,39 @@ async function cmdGen(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,
@@ -185,6 +221,8 @@ export async function main(argv) {
             return cmdCheck(f);
         case "gen":
             return cmdGen(f);
+        case "stubs":
+            return cmdStubs(f);
         case "run":
             return cmdRun(f);
         case "dev":

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

@@ -74,13 +74,17 @@ export interface HostContext {
     /** Structured log sink. */
     log(level: "info" | "warn" | "error", msg: string, fields?: Record<string, unknown>): void;
 }
-/** A job handed to a worker handler, plus the ack/fail callbacks. */
-export interface EngineJob {
+/** A job handed to a worker handler, plus the ack/fail callbacks. `In` types the process
+ *  variables carried on the job; it defaults to an open record when a handler doesn't
+ *  declare a concrete input shape. The `object` bound (rather than `Record<string, unknown>`)
+ *  lets plain `interface` shapes be used as `In` — interfaces lack the implicit index
+ *  signature that a `Record` bound would demand. */
+export interface EngineJob<In extends object = Record<string, unknown>> {
     jobKey: string;
     jobType: string;
     processInstanceKey?: string;
     elementId?: string;
-    variables: Record<string, unknown>;
+    variables: In;
 }
 export type JobHandler = (job: EngineJob) => Promise<Record<string, unknown> | void> | Record<string, unknown> | void;
 /** A registered worker subscription. */

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

@@ -6,8 +6,23 @@ import { type DecisionEvaluator } from "./llm.ts";
  *  SDK shape and adds decision context to a parse failure rather than surfacing a raw
  *  "is not a function" / `JSON.parse` error. */
 export declare function sdkDecisionEvaluator(sdk: unknown): DecisionEvaluator;
-/** A handler as authored by an app: the job plus the injected app API. */
-export type AppJobHandler = (job: EngineJob, app: AppApi) => Promise<Record<string, unknown> | void> | Record<string, unknown> | void;
+/**
+ * A handler as authored by an app: the job plus the injected app API.
+ *
+ * Both type parameters are optional:
+ *   - `In`  types `job.variables` (the process variables the job carries).
+ *   - `Out` types the completion **variables map** the handler returns to the engine.
+ * Each defaults to an open `Record<string, unknown>`, so `AppJobHandler`,
+ * `AppJobHandler<In>`, and `AppJobHandler<In, Out>` are all valid.
+ *
+ * The bound is `extends object` (not `Record<string, unknown>`) so a plain `interface In {…}`
+ * / `interface Out {…}` can be supplied — interfaces have no implicit index signature and so
+ * don't satisfy a `Record` bound. The looser bound means `Out` is not *forced* to be a plain
+ * variables map at the type level; authors are expected to return a JSON-object of completion
+ * variables (not a `Date`, `Map`, array, etc.), which is what the engine sends on job
+ * completion. Both parameters are erased at runtime — they only shape authoring-time types.
+ */
+export type AppJobHandler<In extends object = Record<string, unknown>, Out extends object = Record<string, unknown>> = (job: EngineJob<In>, app: AppApi) => Promise<Out | void> | Out | void;
 /**
  * Resolve a handler for `jobType` from a loaded module, in priority order:
  *   1. `handlers[jobType]`            (a map keyed by job type — the multi-type module case)

package/dist/toolkit/gen.d.ts

@@ -1,4 +1,5 @@
 import type { DerivedArtifact } from "./artifact.ts";
+import { type ModelSource } from "./derivers/worker-io.ts";
 /** Minimal filesystem port. Node/Deno impls live in `fsio.ts`. */
 export interface GenIO {
     readText(path: string): Promise<string>;
@@ -19,6 +20,12 @@ export interface GenResult {
 }
 declare function join(root: string, rel: string): string;
 declare function dirOf(p: string): string;
+/** Read + resolve the app's process models from the manifest's `models.processes` patterns. */
+export declare function readModels(root: string, io: GenIO, manifest: {
+    models?: {
+        processes?: string[];
+    };
+}): Promise<ModelSource[]>;
 /** Collect all artifacts a run would produce, without touching disk beyond reads. */
 export declare function collectArtifacts(opts: GenOptions): Promise<DerivedArtifact[]>;
 /** Run the derivers and write artifacts (or, with `check`, report drift without writing). */

package/dist/toolkit/gen.js

@@ -30,6 +30,17 @@ async function expandPattern(root, io, pattern) {
         .map((n) => (dir === "." ? n : `${dir}/${n}`))
         .sort();
 }
+/** Read + resolve the app's process models from the manifest's `models.processes` patterns. */
+export async function readModels(root, io, manifest) {
+    const procPatterns = manifest.models?.processes ?? [];
+    const models = [];
+    for (const pat of procPatterns) {
+        for (const rel of await expandPattern(root, io, pat)) {
+            models.push({ path: rel, xml: await io.readText(join(root, rel)) });
+        }
+    }
+    return models;
+}
 /** Collect all artifacts a run would produce, without touching disk beyond reads. */
 export async function collectArtifacts(opts) {
     const { root, io } = opts;
@@ -41,13 +52,7 @@ export async function collectArtifacts(opts) {
         artifacts.push(...deriveMigrations(manifest));
     }
     // 2. models → worker I/O index
-    const procPatterns = manifest.models?.processes ?? [];
-    const models = [];
-    for (const pat of procPatterns) {
-        for (const rel of await expandPattern(root, io, pat)) {
-            models.push({ path: rel, xml: await io.readText(join(root, rel)) });
-        }
-    }
+    const models = await readModels(root, io, manifest);
     if (models.length > 0) {
         const declaredTypeIds = Object.keys(manifest.types ?? {});
         artifacts.push(...deriveWorkerBindings(models, declaredTypeIds));

package/dist/toolkit/index.d.ts

@@ -8,6 +8,10 @@ export declare const DERIVERS: readonly [import("./artifact.ts").Deriver<import(
     models: import("./derivers/worker-io.ts").ModelSource[];
     declaredTypeIds: Iterable<string>;
 }>];
-export { collectArtifacts, runGen, joinPath } from "./gen.ts";
+export { collectArtifacts, runGen, joinPath, readModels } from "./gen.ts";
 export type { GenIO, GenOptions, GenResult } from "./gen.ts";
 export { createNodeGenIO } from "./fsio.ts";
+export { planWorkerScaffold, renderWorkerStub, slugifyTaskType, } from "./scaffold/workers.ts";
+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";

package/dist/toolkit/index.js

@@ -11,5 +11,8 @@ import { migrationsDeriver } from "./derivers/migrations.js";
 import { workerIoDeriver } from "./derivers/worker-io.js";
 export const DERIVERS = [migrationsDeriver, workerIoDeriver];
 // Gen orchestrator + IO
-export { collectArtifacts, runGen, joinPath } from "./gen.js";
+export { collectArtifacts, runGen, joinPath, readModels } from "./gen.js";
 export { createNodeGenIO } from "./fsio.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";

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

@@ -0,0 +1,48 @@
+import { type ModelSource } from "../derivers/worker-io.ts";
+/** A worker to plan against: the manifest's already-wired workers. */
+export interface ScaffoldWorker {
+    taskType: string;
+    handler?: string;
+    llm?: string;
+}
+/** The `workers[]` manifest entry a stub is wired in as. */
+export interface StubManifestEntry {
+    taskType: string;
+    handler: string;
+}
+/** One planned handler stub. */
+export interface WorkerStubPlan {
+    taskType: string;
+    process?: string;
+    elementId?: string;
+    /** Directory slug under `workers/` (unique across the plan). */
+    slug: string;
+    /** App-relative handler path: `workers/<slug>/worker.ts`. */
+    handlerPath: string;
+    /** True when the data-envelope `in`/`out` names a declared domain type (so it is typed). */
+    typedIn: boolean;
+    typedOut: boolean;
+    /** The stub file contents. */
+    stub: string;
+    manifestEntry: StubManifestEntry;
+}
+export type SkipReason = "already-wired" | "orchestrator" | "duplicate";
+export interface SkippedWorker {
+    taskType: string;
+    reason: SkipReason;
+}
+export interface WorkerScaffoldPlan {
+    plans: WorkerStubPlan[];
+    skipped: SkippedWorker[];
+}
+/** Turn a task type into a filesystem-safe directory slug. */
+export declare function slugifyTaskType(taskType: string): string;
+/** Render a stub matching a real hand-authored worker (default-exported AppJobHandler). */
+export declare function renderWorkerStub(taskType: string, typedIn: boolean, typedOut: boolean): string;
+/**
+ * Plan write-once handler stubs from the models. A stub is planned for each service-task
+ * `taskType` that is NOT already wired in the manifest, NOT the imperative orchestrator, and
+ * not a duplicate of one already planned. `declaredTypeIds` are the manifest `types` ids — an
+ * envelope `in`/`out` is typed only when it names one (matching the worker-io deriver).
+ */
+export declare function planWorkerScaffold(models: ModelSource[], workers?: ScaffoldWorker[], declaredTypeIds?: Iterable<string>): WorkerScaffoldPlan;

package/dist/toolkit/scaffold/workers.js

@@ -0,0 +1,114 @@
+// Pure planner for the write-once worker-stub scaffolder (ADR 0056). Given the app's models,
+// its manifest workers, and the set of declared domain type ids, it plans one typed handler
+// stub per un-wired service task — the ONE part of an Urban app that cannot be derived from
+// the model (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 `workers/<slug>/worker.ts`, so they are
+// planned once and never overwritten — unlike the derived `nano-generated/` tree.
+import { scanModelWorkers } from "../derivers/worker-io.js";
+/** Suffix the imperative orchestrator task type carries (ADR 0054 / defineWorkflow). */
+const ORCHESTRATOR_SUFFIX = ":__orchestrate";
+/** Relative import from `workers/<slug>/worker.ts` to the generated worker-io types. */
+const GENERATED_IMPORT = "../../nano-generated/worker-io.d.ts";
+/** Turn a task type into a filesystem-safe directory slug. */
+export function slugifyTaskType(taskType) {
+    const s = taskType
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return s.length > 0 ? s : "worker";
+}
+/** Render a stub matching a real hand-authored worker (default-exported AppJobHandler). */
+export function renderWorkerStub(taskType, typedIn, typedOut) {
+    const key = JSON.stringify(taskType); // e.g. "pr.finalize" — matches the deriver's property keys
+    const syms = [];
+    if (typedIn)
+        syms.push("WorkerInputs");
+    if (typedOut)
+        syms.push("WorkerOutputs");
+    const generatedImport = syms.length > 0
+        ? `import type { ${syms.join(", ")} } from ${JSON.stringify(GENERATED_IMPORT)};\n`
+        : "";
+    let generic = "";
+    if (typedIn && typedOut)
+        generic = `<WorkerInputs[${key}], WorkerOutputs[${key}]>`;
+    else if (typedIn)
+        generic = `<WorkerInputs[${key}]>`;
+    else if (typedOut)
+        generic = `<Record<string, unknown>, WorkerOutputs[${key}]>`;
+    const varsNote = typedIn
+        ? `  // \`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` +
+        `// below (use \`app.data.table(...)\` for state) and delete the throw.\n` +
+        `import type { AppJobHandler } from "@nanobpm/urban";\n` +
+        generatedImport +
+        `\n` +
+        `const handler: AppJobHandler${generic} = async (job, app) => {\n` +
+        varsNote +
+        `\n` +
+        `  // Reach app state and services through the injected \`app\` API.\n` +
+        `  throw new Error(${JSON.stringify(`worker not implemented: ${taskType}`)});\n` +
+        `};\n` +
+        `\n` +
+        `export default handler;\n`);
+}
+/**
+ * Plan write-once handler stubs from the models. A stub is planned for each service-task
+ * `taskType` that is NOT already wired in the manifest, NOT the imperative orchestrator, and
+ * not a duplicate of one already planned. `declaredTypeIds` are the manifest `types` ids — an
+ * envelope `in`/`out` is typed only when it names one (matching the worker-io deriver).
+ */
+export function planWorkerScaffold(models, workers = [], declaredTypeIds = []) {
+    const wired = new Set(workers
+        .map((w) => w?.taskType)
+        .filter((t) => typeof t === "string" && t.length > 0));
+    const declared = new Set(declaredTypeIds);
+    const plans = [];
+    const skipped = [];
+    const seenTaskTypes = new Set();
+    const usedSlugs = new Set();
+    for (const model of [...models].sort((a, b) => a.path.localeCompare(b.path))) {
+        for (const io of scanModelWorkers(model.xml)) {
+            const taskType = io.taskType;
+            if (taskType.endsWith(ORCHESTRATOR_SUFFIX)) {
+                skipped.push({ taskType, reason: "orchestrator" });
+                continue;
+            }
+            if (wired.has(taskType)) {
+                skipped.push({ taskType, reason: "already-wired" });
+                continue;
+            }
+            if (seenTaskTypes.has(taskType)) {
+                skipped.push({ taskType, reason: "duplicate" });
+                continue;
+            }
+            seenTaskTypes.add(taskType);
+            let slug = slugifyTaskType(taskType);
+            if (usedSlugs.has(slug)) {
+                let n = 2;
+                while (usedSlugs.has(`${slug}-${n}`))
+                    n++;
+                slug = `${slug}-${n}`;
+            }
+            usedSlugs.add(slug);
+            const typedIn = io.in != null && declared.has(io.in);
+            const typedOut = io.out != null && declared.has(io.out);
+            const handlerPath = `workers/${slug}/worker.ts`;
+            plans.push({
+                taskType,
+                process: io.process,
+                elementId: io.elementId,
+                slug,
+                handlerPath,
+                typedIn,
+                typedOut,
+                stub: renderWorkerStub(taskType, typedIn, typedOut),
+                manifestEntry: { taskType, handler: handlerPath },
+            });
+        }
+    }
+    return { plans, skipped };
+}

package/dist/toolkit/scaffold.d.ts

@@ -0,0 +1,31 @@
+import type { GenIO } from "./gen.ts";
+import { type SkippedWorker, type StubManifestEntry } from "./scaffold/workers.ts";
+export interface ScaffoldOptions {
+    root: string;
+    io: GenIO;
+    manifestFile?: string;
+    /** Apply changes (create files + patch manifest). Default false = dry-run. */
+    write?: boolean;
+}
+export type StubStatus = "created" | "would-create" | "kept";
+export interface StubOutcome {
+    taskType: string;
+    handlerPath: string;
+    status: StubStatus;
+    typedIn: boolean;
+    typedOut: boolean;
+}
+export interface ScaffoldRun {
+    outcomes: StubOutcome[];
+    skipped: SkippedWorker[];
+    /**
+     * Manifest entries that would be appended to `workers[]` — one per planned stub, so this is
+     * populated on a dry-run too (letting a caller preview the wiring). They are actually written
+     * to the manifest only when `write` is set (see `manifestPatched`).
+     */
+    wired: StubManifestEntry[];
+    manifestPatched: boolean;
+    write: boolean;
+}
+/** Scaffold write-once worker stubs from the model, wiring them into `manifest.workers[]`. */
+export declare function scaffoldWorkers(opts: ScaffoldOptions): Promise<ScaffoldRun>;

package/dist/toolkit/scaffold.js

@@ -0,0 +1,54 @@
+// The stub-scaffolder's one impure edge (ADR 0056): read the manifest + models, run the pure
+// planner, and — write-if-absent only — create each handler stub and wire it into the manifest.
+// Dry-run by default (`write: false`); nothing is touched unless `write` is set. Stubs are
+// 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";
+/** Scaffold write-once worker stubs from the model, wiring them into `manifest.workers[]`. */
+export async function scaffoldWorkers(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 models = await readModels(root, io, manifest);
+    const declaredTypeIds = Object.keys(manifest.types ?? {});
+    const { plans, skipped } = planWorkerScaffold(models, manifest.workers ?? [], declaredTypeIds);
+    const outcomes = [];
+    const wired = [];
+    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({
+            taskType: plan.taskType,
+            handlerPath: plan.handlerPath,
+            status,
+            typedIn: plan.typedIn,
+            typedOut: plan.typedOut,
+        });
+        // The planner already excluded already-wired task types, so every plan needs wiring —
+        // including an orphan stub file that exists on disk but isn't in the manifest yet.
+        wired.push(plan.manifestEntry);
+    }
+    let manifestPatched = false;
+    if (write && wired.length > 0) {
+        const withWorkers = {
+            ...manifest,
+            workers: [...(manifest.workers ?? []), ...wired],
+        };
+        await io.writeText(manifestPath, `${JSON.stringify(withWorkers, null, 2)}\n`);
+        manifestPatched = true;
+    }
+    return { outcomes, skipped, wired, manifestPatched, write };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/urban",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
   "license": "Apache-2.0",
   "type": "module",

package/src/cli.ts

@@ -19,7 +19,7 @@ import {
   selectHost,
 } from "./runtime/index.ts";
 import { scaffold, slugify } from "create-urban-app";
-import { createNodeGenIO, runGen } from "./toolkit/index.ts";
+import { createNodeGenIO, runGen, scaffoldWorkers } from "./toolkit/index.ts";
 import { pathToFileURL } from "node:url";
 import { readFileSync } from "node:fs";
 
@@ -42,6 +42,7 @@ interface Flags {
   manifest: string;
   port?: number;
   check: boolean;
+  write: boolean;
   deno: boolean;
   help: boolean;
   version: boolean;
@@ -49,7 +50,7 @@ interface Flags {
 }
 
 function parse(argv: string[]): Flags {
-  const f: Flags = { root: ".", manifest: "nano.app.json", check: false, deno: false, help: false, version: false, _: [] };
+  const f: Flags = { root: ".", manifest: "nano.app.json", check: false, write: false, deno: false, help: false, version: false, _: [] };
   const need = (i: number, flag: string): string => {
     const v = argv[i];
     if (v === undefined || v.startsWith("-")) throw new Error(`flag ${flag} requires a value`);
@@ -60,6 +61,7 @@ function parse(argv: string[]): Flags {
     if (a === "-h" || a === "--help") f.help = true;
     else if (a === "-v" || a === "--version") 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 === "--") continue; // tolerate a bare "--" some runners inject (not an option terminator here)
     else if (a === "--root") f.root = need(++i, a);
@@ -83,6 +85,7 @@ Usage:
   urban new <name> [--root <path>] [--deno]    scaffold a new Urban app
   urban check                       validate the manifest
   urban gen [--check]               derive artifacts (migrations, worker-io)
+  urban stubs [--write]             scaffold write-once handler stubs from the model
   urban run                         materialize + serve the app
   urban dev                         run + watch sources, hot-reload on change
   urban deploy                      deploy models only, then exit
@@ -129,6 +132,38 @@ async function cmdGen(f: Flags): Promise<number> {
   return 0;
 }
 
+async function cmdStubs(f: Flags): Promise<number> {
+  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: { typedIn: boolean; typedOut: boolean }) =>
+    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: Flags, mount?: Record<string, boolean>): Promise<number> {
   const app = await runFromEnv({
     root: f.root,
@@ -199,6 +234,8 @@ export async function main(argv: string[]): Promise<number> {
       return cmdCheck(f);
     case "gen":
       return cmdGen(f);
+    case "stubs":
+      return cmdStubs(f);
     case "run":
       return cmdRun(f);
     case "dev":

package/src/runtime/core/host.ts

@@ -83,13 +83,17 @@ export interface HostContext {
   log(level: "info" | "warn" | "error", msg: string, fields?: Record<string, unknown>): void;
 }
 
-/** A job handed to a worker handler, plus the ack/fail callbacks. */
-export interface EngineJob {
+/** A job handed to a worker handler, plus the ack/fail callbacks. `In` types the process
+ *  variables carried on the job; it defaults to an open record when a handler doesn't
+ *  declare a concrete input shape. The `object` bound (rather than `Record<string, unknown>`)
+ *  lets plain `interface` shapes be used as `In` — interfaces lack the implicit index
+ *  signature that a `Record` bound would demand. */
+export interface EngineJob<In extends object = Record<string, unknown>> {
   jobKey: string;
   jobType: string;
   processInstanceKey?: string;
   elementId?: string;
-  variables: Record<string, unknown>;
+  variables: In;
 }
 
 export type JobHandler = (

package/src/runtime/core/modules/workers.test.ts

@@ -3,7 +3,7 @@ import assert from "node:assert/strict";
 import type { AppApi, RuntimeContext } from "../context.ts";
 import type { EngineJob, JobHandler, WorkerSubscription } from "../host.ts";
 import type { AppManifest } from "../manifest.ts";
-import { mountWorkers, sdkDecisionEvaluator } from "./workers.ts";
+import { mountWorkers, sdkDecisionEvaluator, type AppJobHandler } from "./workers.ts";
 
 /** A tiny engine that records registrations and can deliver a job to a handler. */
 class MiniEngine {
@@ -156,3 +156,55 @@ test("sdkDecisionEvaluator throws a clear error when the SDK lacks evaluateDecis
   const evaluate = sdkDecisionEvaluator({});
   await assert.rejects(evaluate("risk", {}), /does not support evaluateDecision.*"risk"/);
 });
+
+// ── AppJobHandler generics: optional In/Out type parameters ──────────────────────────────
+// These are primarily compile-time assertions (the suite is typechecked by `tsc --noEmit`),
+// with a runtime smoke that a typed handler still returns its output when delivered a job.
+test("AppJobHandler carries optional In/Out variable types", async () => {
+  // `In` is a plain interface — the `object` bound (not `Record<string, unknown>`) makes this
+  // work, since interfaces have no implicit index signature.
+  interface In {
+    prKey: string;
+    round: number;
+    summary?: string;
+  }
+  interface Out {
+    ok: boolean;
+  }
+
+  // In + Out: job.variables is typed as In, the return must be Out (or void).
+  const typed: AppJobHandler<In, Out> = async (job) => {
+    const key: string = job.variables.prKey; // typed access compiles
+    const n: number = job.variables.round;
+    return { ok: key.length > 0 && n >= 0 };
+  };
+
+  // In only: Out defaults to an open variables map, so any plain object of completion
+  // variables may be returned.
+  const inOnly: AppJobHandler<In> = (job) => ({ echoed: job.variables.prKey });
+
+  // No parameters: fully open — the pre-generics behaviour.
+  const open: AppJobHandler = (job) => ({ count: Object.keys(job.variables).length });
+
+  // Returning nothing (void) is allowed under any parameterisation.
+  const voidReturn: AppJobHandler<In> = () => {};
+
+  const job: EngineJob<In> = {
+    jobKey: "1",
+    jobType: "pr.finalize",
+    variables: { prKey: "p1", round: 2 },
+  };
+  // The open handler defaults `In` to a record; interface-typed jobs aren't assignable to it,
+  // so hand it a plainly-typed job (the pre-generics shape).
+  const openJob: EngineJob = {
+    jobKey: "2",
+    jobType: "pr.finalize",
+    variables: { prKey: "p1", round: 2 },
+  };
+  const app = {} as AppApi;
+
+  assert.deepEqual(await typed(job, app), { ok: true });
+  assert.deepEqual(await inOnly(job, app), { echoed: "p1" });
+  assert.deepEqual(await open(openJob, app), { count: 2 });
+  assert.equal(await voidReturn(job, app), undefined);
+});

package/src/runtime/core/modules/workers.ts

@@ -42,11 +42,26 @@ export function sdkDecisionEvaluator(sdk: unknown): DecisionEvaluator {
   };
 }
 
-/** A handler as authored by an app: the job plus the injected app API. */
-export type AppJobHandler = (
-  job: EngineJob,
+/**
+ * A handler as authored by an app: the job plus the injected app API.
+ *
+ * Both type parameters are optional:
+ *   - `In`  types `job.variables` (the process variables the job carries).
+ *   - `Out` types the completion **variables map** the handler returns to the engine.
+ * Each defaults to an open `Record<string, unknown>`, so `AppJobHandler`,
+ * `AppJobHandler<In>`, and `AppJobHandler<In, Out>` are all valid.
+ *
+ * The bound is `extends object` (not `Record<string, unknown>`) so a plain `interface In {…}`
+ * / `interface Out {…}` can be supplied — interfaces have no implicit index signature and so
+ * don't satisfy a `Record` bound. The looser bound means `Out` is not *forced* to be a plain
+ * variables map at the type level; authors are expected to return a JSON-object of completion
+ * variables (not a `Date`, `Map`, array, etc.), which is what the engine sends on job
+ * completion. Both parameters are erased at runtime — they only shape authoring-time types.
+ */
+export type AppJobHandler<In extends object = Record<string, unknown>, Out extends object = Record<string, unknown>> = (
+  job: EngineJob<In>,
   app: AppApi,
-) => Promise<Record<string, unknown> | void> | Record<string, unknown> | void;
+) => Promise<Out | void> | Out | void;
 
 /**
  * Resolve a handler for `jobType` from a loaded module, in priority order:

package/src/toolkit/gen.ts

@@ -57,6 +57,22 @@ async function expandPattern(root: string, io: GenIO, pattern: string): Promise<
     .sort();
 }
 
+/** Read + resolve the app's process models from the manifest's `models.processes` patterns. */
+export async function readModels(
+  root: string,
+  io: GenIO,
+  manifest: { models?: { processes?: string[] } },
+): Promise<ModelSource[]> {
+  const procPatterns = manifest.models?.processes ?? [];
+  const models: ModelSource[] = [];
+  for (const pat of procPatterns) {
+    for (const rel of await expandPattern(root, io, pat)) {
+      models.push({ path: rel, xml: await io.readText(join(root, rel)) });
+    }
+  }
+  return models;
+}
+
 /** Collect all artifacts a run would produce, without touching disk beyond reads. */
 export async function collectArtifacts(opts: GenOptions): Promise<DerivedArtifact[]> {
   const { root, io } = opts;
@@ -73,13 +89,7 @@ export async function collectArtifacts(opts: GenOptions): Promise<DerivedArtifac
   }
 
   // 2. models → worker I/O index
-  const procPatterns = manifest.models?.processes ?? [];
-  const models: ModelSource[] = [];
-  for (const pat of procPatterns) {
-    for (const rel of await expandPattern(root, io, pat)) {
-      models.push({ path: rel, xml: await io.readText(join(root, rel)) });
-    }
-  }
+  const models = await readModels(root, io, manifest);
   if (models.length > 0) {
     const declaredTypeIds = Object.keys(manifest.types ?? {});
     artifacts.push(...deriveWorkerBindings(models, declaredTypeIds));

package/src/toolkit/index.ts

@@ -32,6 +32,23 @@ import { workerIoDeriver } from "./derivers/worker-io.ts";
 export const DERIVERS = [migrationsDeriver, workerIoDeriver] as const;
 
 // Gen orchestrator + IO
-export { collectArtifacts, runGen, joinPath } from "./gen.ts";
+export { collectArtifacts, runGen, joinPath, readModels } from "./gen.ts";
 export type { GenIO, GenOptions, GenResult } from "./gen.ts";
 export { createNodeGenIO } from "./fsio.ts";
+
+// Worker-stub scaffolder (ADR 0056): write-once handler stubs from the model.
+export {
+  planWorkerScaffold,
+  renderWorkerStub,
+  slugifyTaskType,
+} from "./scaffold/workers.ts";
+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";

package/src/toolkit/scaffold/workers.test.ts

@@ -0,0 +1,196 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  planWorkerScaffold,
+  renderWorkerStub,
+  slugifyTaskType,
+  type ScaffoldWorker,
+} from "./workers.ts";
+import type { ModelSource } from "../derivers/worker-io.ts";
+import { scaffoldWorkers } from "../scaffold.ts";
+import type { GenIO } from "../gen.ts";
+
+// A service task with a data-envelope in/out contract; `type` is the taskType, and the
+// io.nanobpm.dataEnvelope.in/out zeebe:property carry the envelope type ids.
+function serviceTask(id: string, taskType: string, inType?: string, outType?: string): string {
+  const props = [
+    inType ? `<zeebe:property name="io.nanobpm.dataEnvelope.in" value="${inType}" />` : "",
+    outType ? `<zeebe:property name="io.nanobpm.dataEnvelope.out" value="${outType}" />` : "",
+  ].join("");
+  return `<bpmn:serviceTask id="${id}"><bpmn:extensionElements>
+      <zeebe:taskDefinition type="${taskType}" />
+      ${props ? `<zeebe:taskHeaders>${props}</zeebe:taskHeaders>` : ""}
+    </bpmn:extensionElements></bpmn:serviceTask>`;
+}
+
+function model(path: string, procId: string, ...tasks: string[]): ModelSource {
+  return {
+    path,
+    xml: `<bpmn:process id="${procId}" xmlns:bpmn="x" xmlns:zeebe="y">
+      ${tasks.join("\n")}
+    </bpmn:process>`,
+  };
+}
+
+test("slugifyTaskType makes a filesystem-safe slug", () => {
+  assert.equal(slugifyTaskType("pr.finalize"), "pr-finalize");
+  assert.equal(slugifyTaskType("Orders::Charge Card!"), "orders-charge-card");
+  assert.equal(slugifyTaskType("---"), "worker");
+});
+
+test("typed in+out stub imports both symbols and parameterises the handler", () => {
+  const stub = renderWorkerStub("pr.finalize", true, true);
+  assert.match(stub, /import type \{ WorkerInputs, WorkerOutputs \} from "\.\.\/\.\.\/nano-generated\/worker-io\.d\.ts";/);
+  assert.match(stub, /AppJobHandler<WorkerInputs\["pr\.finalize"\], WorkerOutputs\["pr\.finalize"\]>/);
+  assert.match(stub, /export default handler;/);
+  assert.match(stub, /throw new Error\("worker not implemented: pr\.finalize"\)/);
+});
+
+test("untyped stub imports no generated types and uses bare AppJobHandler", () => {
+  const stub = renderWorkerStub("demo.do", false, false);
+  assert.doesNotMatch(stub, /worker-io\.d\.ts/);
+  assert.match(stub, /const handler: AppJobHandler = async \(job, app\) =>/);
+});
+
+test("typed-out-only stub fills In with the open default", () => {
+  const stub = renderWorkerStub("demo.out", false, true);
+  assert.match(stub, /import type \{ WorkerOutputs \} from/);
+  assert.match(stub, /AppJobHandler<Record<string, unknown>, WorkerOutputs\["demo\.out"\]>/);
+});
+
+test("planWorkerScaffold: typed vs untyped from declared types", () => {
+  const m = model(
+    "a.bpmn",
+    "orders",
+    serviceTask("A", "orders.charge", "ChargeIn", "ChargeOut"),
+    serviceTask("B", "orders.ship"),
+  );
+  const { plans } = planWorkerScaffold([m], [], ["ChargeIn", "ChargeOut"]);
+  assert.equal(plans.length, 2);
+  const charge = plans.find((p) => p.taskType === "orders.charge")!;
+  assert.equal(charge.typedIn, true);
+  assert.equal(charge.typedOut, true);
+  assert.equal(charge.handlerPath, "workers/orders-charge/worker.ts");
+  assert.deepEqual(charge.manifestEntry, { taskType: "orders.charge", handler: "workers/orders-charge/worker.ts" });
+  const ship = plans.find((p) => p.taskType === "orders.ship")!;
+  assert.equal(ship.typedIn, false);
+  assert.equal(ship.typedOut, false);
+});
+
+test("planWorkerScaffold: an in/out that is not a declared type stays untyped", () => {
+  const m = model("a.bpmn", "p", serviceTask("A", "t.a", "Undeclared", "AlsoUndeclared"));
+  const { plans } = planWorkerScaffold([m], [], ["SomethingElse"]);
+  assert.equal(plans[0].typedIn, false);
+  assert.equal(plans[0].typedOut, false);
+});
+
+test("planWorkerScaffold: skips already-wired, orchestrator, and duplicates", () => {
+  const wired: ScaffoldWorker[] = [{ taskType: "t.wired", handler: "workers/x/worker.ts" }];
+  const models = [
+    model("a.bpmn", "p1", serviceTask("A", "t.wired"), serviceTask("B", "t.new"), serviceTask("O", "wf:__orchestrate")),
+    model("b.bpmn", "p2", serviceTask("C", "t.new")), // duplicate taskType across models
+  ];
+  const { plans, skipped } = planWorkerScaffold(models, wired, []);
+  assert.deepEqual(plans.map((p) => p.taskType), ["t.new"]);
+  const reasons = Object.fromEntries(skipped.map((s) => [s.taskType, s.reason]));
+  assert.equal(reasons["t.wired"], "already-wired");
+  assert.equal(reasons["wf:__orchestrate"], "orchestrator");
+  assert.equal(reasons["t.new"], "duplicate");
+});
+
+test("planWorkerScaffold: colliding slugs get a numeric suffix", () => {
+  const m = model("a.bpmn", "p", serviceTask("A", "orders.charge"), serviceTask("B", "orders-charge"));
+  const { plans } = planWorkerScaffold([m], [], []);
+  const slugs = plans.map((p) => p.slug).sort();
+  assert.deepEqual(slugs, ["orders-charge", "orders-charge-2"]);
+});
+
+// ── runner (impure edge, in-memory IO) ──────────────────────────────────────────────────
+
+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",
+      models: { processes: ["processes/*.bpmn"] },
+      workers: [{ taskType: "t.wired", handler: "workers/wired/worker.ts" }],
+    }),
+    "/app/processes/p.bpmn": model("p.bpmn", "p",
+      serviceTask("A", "t.new"),
+      serviceTask("B", "t.wired"),
+    ).xml,
+  };
+}
+
+test("scaffoldWorkers dry-run writes nothing and reports would-create", async () => {
+  const io = memIO(appFixture());
+  const before = Object.keys(io.files).length;
+  const run = await scaffoldWorkers({ 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), ["would-create"]);
+  assert.equal(run.outcomes[0].taskType, "t.new");
+  assert.equal(run.manifestPatched, false);
+  assert.ok(run.skipped.some((s) => s.taskType === "t.wired" && s.reason === "already-wired"));
+});
+
+test("scaffoldWorkers --write creates the stub and patches the manifest once", async () => {
+  const io = memIO(appFixture());
+  const run = await scaffoldWorkers({ root: "/app", io, write: true });
+  assert.equal(run.outcomes[0].status, "created");
+  const stub = io.files["/app/workers/t-new/worker.ts"];
+  assert.ok(stub, "stub file written");
+  assert.match(stub, /worker not implemented: t\.new/);
+  const manifest = JSON.parse(io.files["/app/nano.app.json"]);
+  assert.deepEqual(manifest.workers.map((w: { taskType: string }) => w.taskType), ["t.wired", "t.new"]);
+  assert.ok(io.files["/app/nano.app.json"].endsWith("\n"), "manifest ends with newline");
+});
+
+test("scaffoldWorkers never clobbers an existing stub (keeps it), still wires it", async () => {
+  const files = appFixture();
+  files["/app/workers/t-new/worker.ts"] = "// hand-edited, do not touch\n";
+  const io = memIO(files);
+  const run = await scaffoldWorkers({ root: "/app", io, write: true });
+  assert.equal(run.outcomes[0].status, "kept");
+  assert.equal(io.files["/app/workers/t-new/worker.ts"], "// hand-edited, do not touch\n");
+  const manifest = JSON.parse(io.files["/app/nano.app.json"]);
+  assert.ok(manifest.workers.some((w: { taskType: string }) => w.taskType === "t.new"), "orphan stub gets wired");
+});
+
+test("scaffoldWorkers is idempotent: a second --write run is a no-op", async () => {
+  const io = memIO(appFixture());
+  await scaffoldWorkers({ root: "/app", io, write: true });
+  const snapshot = JSON.stringify(io.files);
+  const run2 = await scaffoldWorkers({ root: "/app", io, write: true });
+  // t.new is now wired in the manifest, so the planner skips it entirely (nothing to do).
+  assert.deepEqual(run2.outcomes, []);
+  assert.ok(run2.skipped.some((s) => s.taskType === "t.new" && s.reason === "already-wired"));
+  assert.equal(run2.manifestPatched, false, "no new wiring on the second run");
+  assert.equal(JSON.stringify(io.files), snapshot, "files unchanged on re-run");
+});

package/src/toolkit/scaffold/workers.ts

@@ -0,0 +1,178 @@
+// Pure planner for the write-once worker-stub scaffolder (ADR 0056). Given the app's models,
+// its manifest workers, and the set of declared domain type ids, it plans one typed handler
+// stub per un-wired service task — the ONE part of an Urban app that cannot be derived from
+// the model (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 `workers/<slug>/worker.ts`, so they are
+// planned once and never overwritten — unlike the derived `nano-generated/` tree.
+
+import { scanModelWorkers, type ModelSource } from "../derivers/worker-io.ts";
+
+/** A worker to plan against: the manifest's already-wired workers. */
+export interface ScaffoldWorker {
+  taskType: string;
+  handler?: string;
+  llm?: string;
+}
+
+/** The `workers[]` manifest entry a stub is wired in as. */
+export interface StubManifestEntry {
+  taskType: string;
+  handler: string;
+}
+
+/** One planned handler stub. */
+export interface WorkerStubPlan {
+  taskType: string;
+  process?: string;
+  elementId?: string;
+  /** Directory slug under `workers/` (unique across the plan). */
+  slug: string;
+  /** App-relative handler path: `workers/<slug>/worker.ts`. */
+  handlerPath: string;
+  /** True when the data-envelope `in`/`out` names a declared domain type (so it is typed). */
+  typedIn: boolean;
+  typedOut: boolean;
+  /** The stub file contents. */
+  stub: string;
+  manifestEntry: StubManifestEntry;
+}
+
+export type SkipReason = "already-wired" | "orchestrator" | "duplicate";
+
+export interface SkippedWorker {
+  taskType: string;
+  reason: SkipReason;
+}
+
+export interface WorkerScaffoldPlan {
+  plans: WorkerStubPlan[];
+  skipped: SkippedWorker[];
+}
+
+/** Suffix the imperative orchestrator task type carries (ADR 0054 / defineWorkflow). */
+const ORCHESTRATOR_SUFFIX = ":__orchestrate";
+
+/** Relative import from `workers/<slug>/worker.ts` to the generated worker-io types. */
+const GENERATED_IMPORT = "../../nano-generated/worker-io.d.ts";
+
+/** Turn a task type into a filesystem-safe directory slug. */
+export function slugifyTaskType(taskType: string): string {
+  const s = taskType
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return s.length > 0 ? s : "worker";
+}
+
+/** Render a stub matching a real hand-authored worker (default-exported AppJobHandler). */
+export function renderWorkerStub(
+  taskType: string,
+  typedIn: boolean,
+  typedOut: boolean,
+): string {
+  const key = JSON.stringify(taskType); // e.g. "pr.finalize" — matches the deriver's property keys
+  const syms: string[] = [];
+  if (typedIn) syms.push("WorkerInputs");
+  if (typedOut) syms.push("WorkerOutputs");
+
+  const generatedImport = syms.length > 0
+    ? `import type { ${syms.join(", ")} } from ${JSON.stringify(GENERATED_IMPORT)};\n`
+    : "";
+
+  let generic = "";
+  if (typedIn && typedOut) generic = `<WorkerInputs[${key}], WorkerOutputs[${key}]>`;
+  else if (typedIn) generic = `<WorkerInputs[${key}]>`;
+  else if (typedOut) generic = `<Record<string, unknown>, WorkerOutputs[${key}]>`;
+
+  const varsNote = typedIn
+    ? `  // \`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` +
+    `// below (use \`app.data.table(...)\` for state) and delete the throw.\n` +
+    `import type { AppJobHandler } from "@nanobpm/urban";\n` +
+    generatedImport +
+    `\n` +
+    `const handler: AppJobHandler${generic} = async (job, app) => {\n` +
+    varsNote +
+    `\n` +
+    `  // Reach app state and services through the injected \`app\` API.\n` +
+    `  throw new Error(${JSON.stringify(`worker not implemented: ${taskType}`)});\n` +
+    `};\n` +
+    `\n` +
+    `export default handler;\n`
+  );
+}
+
+/**
+ * Plan write-once handler stubs from the models. A stub is planned for each service-task
+ * `taskType` that is NOT already wired in the manifest, NOT the imperative orchestrator, and
+ * not a duplicate of one already planned. `declaredTypeIds` are the manifest `types` ids — an
+ * envelope `in`/`out` is typed only when it names one (matching the worker-io deriver).
+ */
+export function planWorkerScaffold(
+  models: ModelSource[],
+  workers: ScaffoldWorker[] = [],
+  declaredTypeIds: Iterable<string> = [],
+): WorkerScaffoldPlan {
+  const wired = new Set(
+    workers
+      .map((w) => w?.taskType)
+      .filter((t): t is string => typeof t === "string" && t.length > 0),
+  );
+  const declared = new Set(declaredTypeIds);
+
+  const plans: WorkerStubPlan[] = [];
+  const skipped: SkippedWorker[] = [];
+  const seenTaskTypes = new Set<string>();
+  const usedSlugs = new Set<string>();
+
+  for (const model of [...models].sort((a, b) => a.path.localeCompare(b.path))) {
+    for (const io of scanModelWorkers(model.xml)) {
+      const taskType = io.taskType;
+      if (taskType.endsWith(ORCHESTRATOR_SUFFIX)) {
+        skipped.push({ taskType, reason: "orchestrator" });
+        continue;
+      }
+      if (wired.has(taskType)) {
+        skipped.push({ taskType, reason: "already-wired" });
+        continue;
+      }
+      if (seenTaskTypes.has(taskType)) {
+        skipped.push({ taskType, reason: "duplicate" });
+        continue;
+      }
+      seenTaskTypes.add(taskType);
+
+      let slug = slugifyTaskType(taskType);
+      if (usedSlugs.has(slug)) {
+        let n = 2;
+        while (usedSlugs.has(`${slug}-${n}`)) n++;
+        slug = `${slug}-${n}`;
+      }
+      usedSlugs.add(slug);
+
+      const typedIn = io.in != null && declared.has(io.in);
+      const typedOut = io.out != null && declared.has(io.out);
+      const handlerPath = `workers/${slug}/worker.ts`;
+
+      plans.push({
+        taskType,
+        process: io.process,
+        elementId: io.elementId,
+        slug,
+        handlerPath,
+        typedIn,
+        typedOut,
+        stub: renderWorkerStub(taskType, typedIn, typedOut),
+        manifestEntry: { taskType, handler: handlerPath },
+      });
+    }
+  }
+
+  return { plans, skipped };
+}

package/src/toolkit/scaffold.ts

@@ -0,0 +1,104 @@
+// The stub-scaffolder's one impure edge (ADR 0056): read the manifest + models, run the pure
+// planner, and — write-if-absent only — create each handler stub and wire it into the manifest.
+// Dry-run by default (`write: false`); nothing is touched unless `write` is set. Stubs are
+// human-owned, so an existing file is KEPT verbatim, never clobbered (the opposite of `runGen`).
+
+import type { GenIO } from "./gen.ts";
+import { joinPath, readModels } from "./gen.ts";
+import {
+  planWorkerScaffold,
+  type ScaffoldWorker,
+  type SkippedWorker,
+  type StubManifestEntry,
+} from "./scaffold/workers.ts";
+
+/** The manifest fields the scaffolder reads. */
+interface ScaffoldManifest {
+  types?: Record<string, unknown>;
+  models?: { processes?: string[] };
+  workers?: ScaffoldWorker[];
+}
+
+export interface ScaffoldOptions {
+  root: string;
+  io: GenIO;
+  manifestFile?: string;
+  /** Apply changes (create files + patch manifest). Default false = dry-run. */
+  write?: boolean;
+}
+
+export type StubStatus = "created" | "would-create" | "kept";
+
+export interface StubOutcome {
+  taskType: string;
+  handlerPath: string;
+  status: StubStatus;
+  typedIn: boolean;
+  typedOut: boolean;
+}
+
+export interface ScaffoldRun {
+  outcomes: StubOutcome[];
+  skipped: SkippedWorker[];
+  /**
+   * Manifest entries that would be appended to `workers[]` — one per planned stub, so this is
+   * populated on a dry-run too (letting a caller preview the wiring). They are actually written
+   * to the manifest only when `write` is set (see `manifestPatched`).
+   */
+  wired: StubManifestEntry[];
+  manifestPatched: boolean;
+  write: boolean;
+}
+
+/** Scaffold write-once worker stubs from the model, wiring them into `manifest.workers[]`. */
+export async function scaffoldWorkers(opts: ScaffoldOptions): Promise<ScaffoldRun> {
+  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)) as ScaffoldManifest;
+  const models = await readModels(root, io, manifest);
+  const declaredTypeIds = Object.keys(manifest.types ?? {});
+
+  const { plans, skipped } = planWorkerScaffold(models, manifest.workers ?? [], declaredTypeIds);
+
+  const outcomes: StubOutcome[] = [];
+  const wired: StubManifestEntry[] = [];
+
+  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({
+      taskType: plan.taskType,
+      handlerPath: plan.handlerPath,
+      status,
+      typedIn: plan.typedIn,
+      typedOut: plan.typedOut,
+    });
+    // The planner already excluded already-wired task types, so every plan needs wiring —
+    // including an orphan stub file that exists on disk but isn't in the manifest yet.
+    wired.push(plan.manifestEntry);
+  }
+
+  let manifestPatched = false;
+  if (write && wired.length > 0) {
+    const withWorkers = {
+      ...manifest,
+      workers: [...(manifest.workers ?? []), ...wired],
+    };
+    await io.writeText(manifestPath, `${JSON.stringify(withWorkers, null, 2)}\n`);
+    manifestPatched = true;
+  }
+
+  return { outcomes, skipped, wired, manifestPatched, write };
+}