@nanobpm/urban 0.14.0 → 0.16.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,8 +42,18 @@ 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 === "--code-first")
+            f.style = "code";
+        else if (a === "--style") {
+            const v = need(++i, a);
+            if (v !== "model" && v !== "code")
+                throw new Error(`flag --style requires "model" or "code" (got "${v}")`);
+            f.style = v;
+        }
         else if (a === "--")
             continue; // tolerate a bare "--" some runners inject (not an option terminator here)
         else if (a === "--root")
@@ -68,9 +78,11 @@ function parse(argv) {
 const USAGE = `urban — build and run Urban apps (nano.app.json)
 
 Usage:
-  urban new <name> [--root <path>] [--deno]    scaffold a new Urban app
+  urban new <name> [--root <path>] [--deno] [--style model|code]    scaffold a new Urban app
+                                    (--code-first is shorthand for --style code)
   urban check                       validate the manifest
   urban gen [--check]               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 +129,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,
@@ -147,14 +192,16 @@ async function cmdDeploy(f) {
 async function cmdNew(f) {
     const name = f._[1];
     if (!name) {
-        console.error("usage: urban new <name> [--root <path>] [--deno]");
+        console.error("usage: urban new <name> [--root <path>] [--deno] [--style model|code] (or --code-first)");
         return 1;
     }
     const dir = f.root !== "." ? f.root : `./${slugify(name)}`;
-    const res = await scaffold({ name, dir, deno: f.deno });
+    const res = await scaffold({ name, dir, deno: f.deno, style: f.style });
     console.log(`✔ scaffolded "${res.id}" in ${res.dir} (${res.files.length} files)`);
     console.log(`  cd ${res.dir}`);
     console.log(`  npm install && npm start`);
+    if (f.style === "code")
+        console.log(`  npm run greet -- Adam   # start a code-first instance`);
     if (f.deno)
         console.log(`  # or on Deno: deno task start`);
     return 0;
@@ -185,6 +232,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/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/worker";\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/dist/worker.d.ts

@@ -0,0 +1,3 @@
+export type { AppJobHandler } from "./runtime/core/modules/workers.ts";
+export type { EngineJob, JobHandler } from "./runtime/core/host.ts";
+export type { AppApi } from "./runtime/core/context.ts";

package/dist/worker.js

@@ -0,0 +1,18 @@
+// `@nanobpm/urban/worker` — the runtime-free worker-authoring surface.
+//
+// A service-task handler only needs a handful of *types*: the handler signature and the
+// shapes it is handed. Those all live under `runtime/core/`, which is guaranteed free of any
+// `node:*` import or `Deno` reference (the ADR 0052 purity invariant, enforced by
+// core/purity.test.ts). Importing them from the package barrel (`@nanobpm/urban`) instead
+// drags in `runtime/index.ts`, which re-exports the Node and Deno host adapters — so the
+// barrel's type graph transitively references `node:*` and a consumer must have `@types/node`
+// resolvable (or `skipLibCheck` on) just to typecheck a handler.
+//
+// This entry re-exports ONLY those core authoring types, so a worker module (e.g. a scaffolded
+// stub, ADR 0056) typechecks on Node or Deno, with or without `skipLibCheck`, and never needs
+// `@types/node`. It is types-only: nothing here emits runtime code.
+//
+// (One caveat: `AppApi.sdk` exposes the full `@nanobpm/nano-sdk` client by design, so the
+// handler surface also reaches the SDK's types. Those are kept node-free by the
+// `@nanobpm/nano-sdk` >= 1.2.2 floor in package.json — see ADR 0056.)
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/urban",
-  "version": "0.14.0",
+  "version": "0.16.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",
@@ -43,6 +43,10 @@
       "types": "./dist/toolkit/index.d.ts",
       "default": "./dist/toolkit/index.js"
     },
+    "./worker": {
+      "types": "./dist/worker.d.ts",
+      "default": "./dist/worker.js"
+    },
     "./source": "./src/index.ts"
   },
   "files": [
@@ -58,10 +62,10 @@
     "test:deno": "deno test -A --no-check src/"
   },
   "dependencies": {
-    "@nanobpm/nano-sdk": "^1.2.0",
+    "@nanobpm/nano-sdk": "^1.2.2",
     "@nanobpm/workflow": "^0.7.0",
     "bpmn-auto-layout": "^2.0.0-alpha.2",
-    "create-urban-app": "^0.4.0"
+    "create-urban-app": "^0.5.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",

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,14 +42,16 @@ interface Flags {
   manifest: string;
   port?: number;
   check: boolean;
+  write: boolean;
   deno: boolean;
+  style?: "model" | "code";
   help: boolean;
   version: boolean;
   _: string[];
 }
 
 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,7 +62,14 @@ 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 === "--code-first") f.style = "code";
+    else if (a === "--style") {
+      const v = need(++i, a);
+      if (v !== "model" && v !== "code") throw new Error(`flag --style requires "model" or "code" (got "${v}")`);
+      f.style = v;
+    }
     else if (a === "--") continue; // tolerate a bare "--" some runners inject (not an option terminator here)
     else if (a === "--root") f.root = need(++i, a);
     else if (a === "--manifest") f.manifest = need(++i, a);
@@ -80,9 +89,11 @@ function parse(argv: string[]): Flags {
 const USAGE = `urban — build and run Urban apps (nano.app.json)
 
 Usage:
-  urban new <name> [--root <path>] [--deno]    scaffold a new Urban app
+  urban new <name> [--root <path>] [--deno] [--style model|code]    scaffold a new Urban app
+                                    (--code-first is shorthand for --style code)
   urban check                       validate the manifest
   urban gen [--check]               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 +140,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,
@@ -162,14 +205,15 @@ async function cmdDeploy(f: Flags): Promise<number> {
 async function cmdNew(f: Flags): Promise<number> {
   const name = f._[1];
   if (!name) {
-    console.error("usage: urban new <name> [--root <path>] [--deno]");
+    console.error("usage: urban new <name> [--root <path>] [--deno] [--style model|code] (or --code-first)");
     return 1;
   }
   const dir = f.root !== "." ? f.root : `./${slugify(name)}`;
-  const res = await scaffold({ name, dir, deno: f.deno });
+  const res = await scaffold({ name, dir, deno: f.deno, style: f.style });
   console.log(`✔ scaffolded "${res.id}" in ${res.dir} (${res.files.length} files)`);
   console.log(`  cd ${res.dir}`);
   console.log(`  npm install && npm start`);
+  if (f.style === "code") console.log(`  npm run greet -- Adam   # start a code-first instance`);
   if (f.deno) console.log(`  # or on Deno: deno task start`);
   return 0;
 }
@@ -199,6 +243,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/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,197 @@
+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 \{ AppJobHandler \} from "@nanobpm\/urban\/worker";/);
+  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/worker";\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 };
+}

package/src/worker.test.ts

@@ -0,0 +1,104 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { dirname, join, normalize } from "node:path";
+
+// Guard for the `@nanobpm/urban/worker` authoring surface. Its job is to keep urban's OWN
+// host adapters (runtime/adapters/node.ts, runtime/adapters/deno.ts and their node:* imports)
+// out of the type graph a worker handler imports — the coupling that otherwise forces
+// `@types/node` / `skipLibCheck` on a consumer just to typecheck a handler.
+//
+// This walks the *relative*-import closure from worker.ts, so it covers urban's own reachable
+// sources. It does NOT follow the bare `@nanobpm/nano-sdk` dependency behind `AppApi.sdk`
+// (engine/sdk.ts) — that dependency's own node-freeness is enforced separately by the
+// `@nanobpm/nano-sdk` >= 1.2.2 floor in package.json (which pulls @camunda8 >= 10.0.0-alpha.20,
+// whose public types no longer reference node:worker_threads). Together, urban's node-free
+// relative closure + that SDK floor make a scaffolded stub (ADR 0056) typecheck on Node or Deno
+// with no `@types/node` and no `skipLibCheck`.
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+/** Collect relative-specifier imports/re-exports from a source file. */
+function relativeSpecifiers(src: string): string[] {
+  const out: string[] = [];
+  const re = /\bfrom\s+["'](\.[^"']+)["']/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(src)) !== null) {
+    // Skip template-placeholder specifiers (e.g. `./${DOMAIN_DTS}` emitted as codegen strings),
+    // which are not real static import paths.
+    if (!m[1].includes("${")) out.push(m[1]);
+  }
+  return out;
+}
+
+/** Resolve a relative specifier (with explicit .ts) against a containing file. */
+function resolveSpec(fromFile: string, spec: string): string {
+  return normalize(join(dirname(fromFile), spec));
+}
+
+async function closureFrom(entry: string): Promise<string[]> {
+  const seen = new Set<string>();
+  const stack = [entry];
+  while (stack.length > 0) {
+    const file = stack.pop()!;
+    if (seen.has(file)) continue;
+    seen.add(file);
+    let src: string;
+    try {
+      src = await readFile(file, "utf8");
+    } catch {
+      // A statically-extracted specifier that doesn't resolve to a real file (dynamic/generated
+      // path). Skip it — the purity assertions below only care about files that actually exist.
+      continue;
+    }
+    for (const spec of relativeSpecifiers(src)) {
+      stack.push(resolveSpec(file, spec));
+    }
+  }
+  return [...seen];
+}
+
+test("@nanobpm/urban/worker closure is free of node:* and Deno", async () => {
+  const files = await closureFrom(join(here, "worker.ts"));
+  // Sanity: the walk actually reached the core authoring modules.
+  assert.ok(
+    files.some((f) => f.endsWith(join("core", "modules", "workers.ts"))),
+    "closure should include core/modules/workers.ts",
+  );
+  const offenders: string[] = [];
+  for (const file of files) {
+    const src = await readFile(file, "utf8");
+    if (/from\s+["']node:/.test(src)) offenders.push(`${file}: imports node:*`);
+    if (/\bDeno\s*\./.test(src)) offenders.push(`${file}: references Deno.*`);
+  }
+  assert.deepEqual(offenders, [], `worker surface purity violations:\n${offenders.join("\n")}`);
+});
+
+test("@nanobpm/urban/worker excludes urban's host adapters (the barrel includes them)", async () => {
+  const workerClosure = await closureFrom(join(here, "worker.ts"));
+  const barrelClosure = await closureFrom(join(here, "index.ts"));
+  const adapters = [
+    join("runtime", "adapters", "node.ts"),
+    join("runtime", "adapters", "deno.ts"),
+  ];
+  for (const a of adapters) {
+    assert.ok(
+      !workerClosure.some((f) => f.endsWith(a)),
+      `worker closure must NOT include ${a}`,
+    );
+    assert.ok(
+      barrelClosure.some((f) => f.endsWith(a)),
+      `barrel closure is expected to include ${a} (control)`,
+    );
+  }
+});
+
+test("@nanobpm/urban/worker re-exports the authoring types", async () => {
+  const src = await readFile(join(here, "worker.ts"), "utf8");
+  for (const sym of ["AppJobHandler", "EngineJob", "JobHandler", "AppApi"]) {
+    assert.match(src, new RegExp(`\\b${sym}\\b`), `worker.ts should export ${sym}`);
+  }
+  // Types-only surface: no value exports (nothing that would emit runtime code).
+  assert.doesNotMatch(src, /^export\s+(?!type\b)/m, "worker.ts must be a types-only re-export");
+});

package/src/worker.ts

@@ -0,0 +1,21 @@
+// `@nanobpm/urban/worker` — the runtime-free worker-authoring surface.
+//
+// A service-task handler only needs a handful of *types*: the handler signature and the
+// shapes it is handed. Those all live under `runtime/core/`, which is guaranteed free of any
+// `node:*` import or `Deno` reference (the ADR 0052 purity invariant, enforced by
+// core/purity.test.ts). Importing them from the package barrel (`@nanobpm/urban`) instead
+// drags in `runtime/index.ts`, which re-exports the Node and Deno host adapters — so the
+// barrel's type graph transitively references `node:*` and a consumer must have `@types/node`
+// resolvable (or `skipLibCheck` on) just to typecheck a handler.
+//
+// This entry re-exports ONLY those core authoring types, so a worker module (e.g. a scaffolded
+// stub, ADR 0056) typechecks on Node or Deno, with or without `skipLibCheck`, and never needs
+// `@types/node`. It is types-only: nothing here emits runtime code.
+//
+// (One caveat: `AppApi.sdk` exposes the full `@nanobpm/nano-sdk` client by design, so the
+// handler surface also reaches the SDK's types. Those are kept node-free by the
+// `@nanobpm/nano-sdk` >= 1.2.2 floor in package.json — see ADR 0056.)
+
+export type { AppJobHandler } from "./runtime/core/modules/workers.ts";
+export type { EngineJob, JobHandler } from "./runtime/core/host.ts";
+export type { AppApi } from "./runtime/core/context.ts";