@nanobpm/urban 0.15.0 → 0.16.1

package/dist/cli.js

@@ -46,6 +46,14 @@ function parse(argv) {
             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")
@@ -70,7 +78,8 @@ 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
@@ -183,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;

package/dist/runtime/core/modules/datasource.js

@@ -48,8 +48,17 @@ export class TypeRepo {
     }
     insert(row) {
         this.assertFields(row);
-        const keys = Object.keys(row);
+        // Omit keys whose value is `undefined` so the column's own `DEFAULT`/`NULL` governs;
+        // `undefined` means "not provided", never a bound value. An explicit `null` is preserved.
+        const provided = Object.keys(row);
+        const keys = provided.filter((k) => row[k] !== undefined);
         if (keys.length === 0) {
+            // A present-but-all-undefined payload throws (parity with Table.insert): the caller
+            // meant to write those values, so silently inserting a full DEFAULT row would create
+            // an unintended record. A genuinely empty `insert({})` is the explicit "default row".
+            if (provided.length > 0) {
+                throw new Error(`insert into type "${this.typeName}": no columns to insert (all values were undefined)`);
+            }
             return this.db.run(`INSERT INTO ${this.table()} DEFAULT VALUES`, []);
         }
         const cols = keys.join(", ");

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

@@ -59,8 +59,10 @@ export declare class Table<T extends object = Row> {
     readonly name: string;
     readonly pk: string;
     constructor(src: DataSource, name: string, pk?: string);
-    /** Insert one row (only the present keys are written); returns the new primary-key value
-     * (the inserted rowid for an INTEGER PRIMARY KEY). */
+    /** Insert one row; returns the new primary-key value (the inserted rowid for an INTEGER
+     * PRIMARY KEY). Keys whose value is `undefined` are omitted, so the table's own column
+     * `DEFAULT`/`NULL` governs — `undefined` means "not provided, let the schema decide", never
+     * a bound value. An explicit `null` is preserved (it stores `NULL`). */
     insert(row: Partial<T>): Promise<number | bigint>;
     /** Fetch the row with the given primary key, or `undefined`. */
     get(id: unknown): Promise<T | undefined>;
@@ -70,7 +72,9 @@ export declare class Table<T extends object = Row> {
     find(where?: Partial<T>): Promise<T[]>;
     /** The first row matching an equality filter, or `undefined`. */
     findOne(where?: Partial<T>): Promise<T | undefined>;
-    /** Patch the row with the given primary key; returns rows changed. */
+    /** Patch the row with the given primary key; returns rows changed. Keys whose value is
+     * `undefined` are skipped (that column is left unchanged); an explicit `null` clears the
+     * column to `NULL`. A patch with no defined keys is a no-op. */
     update(id: unknown, patch: Partial<T>): Promise<number>;
     /** Delete the row with the given primary key; returns rows changed. */
     delete(id: unknown): Promise<number>;

package/dist/runtime/core/modules/gateway.js

@@ -40,12 +40,17 @@ export class Table {
         this.name = name;
         this.pk = pk;
     }
-    /** Insert one row (only the present keys are written); returns the new primary-key value
-     * (the inserted rowid for an INTEGER PRIMARY KEY). */
+    /** Insert one row; returns the new primary-key value (the inserted rowid for an INTEGER
+     * PRIMARY KEY). Keys whose value is `undefined` are omitted, so the table's own column
+     * `DEFAULT`/`NULL` governs — `undefined` means "not provided, let the schema decide", never
+     * a bound value. An explicit `null` is preserved (it stores `NULL`). */
     async insert(row) {
-        const keys = Object.keys(row);
+        const provided = Object.keys(row);
+        const keys = provided.filter((k) => row[k] !== undefined);
         if (keys.length === 0) {
-            throw new Error(`Table(${this.name}).insert: no columns to insert`);
+            throw new Error(provided.length === 0
+                ? `Table(${this.name}).insert: no columns to insert (empty row)`
+                : `Table(${this.name}).insert: no columns to insert (all values were undefined)`);
         }
         const cols = keys.map(quoteIdent).join(", ");
         const ph = keys.map(() => "?").join(", ");
@@ -80,9 +85,11 @@ export class Table {
         const rows = await this.#src.query(`SELECT * FROM ${quoteIdent(this.name)}${clause} LIMIT 1`, params);
         return rows[0];
     }
-    /** Patch the row with the given primary key; returns rows changed. */
+    /** Patch the row with the given primary key; returns rows changed. Keys whose value is
+     * `undefined` are skipped (that column is left unchanged); an explicit `null` clears the
+     * column to `NULL`. A patch with no defined keys is a no-op. */
     async update(id, patch) {
-        const keys = Object.keys(patch);
+        const keys = Object.keys(patch).filter((k) => patch[k] !== undefined);
         if (keys.length === 0)
             return 0;
         const set = keys.map((k) => `${quoteIdent(k)} = ?`).join(", ");

package/dist/toolkit/scaffold/workers.js

@@ -43,7 +43,7 @@ export function renderWorkerStub(taskType, typedIn, typedOut) {
     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` +
+        `import type { AppJobHandler } from "@nanobpm/urban/worker";\n` +
         generatedImport +
         `\n` +
         `const handler: AppJobHandler${generic} = async (job, app) => {\n` +

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.15.0",
+  "version": "0.16.1",
   "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.3",
     "@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

@@ -44,6 +44,7 @@ interface Flags {
   check: boolean;
   write: boolean;
   deno: boolean;
+  style?: "model" | "code";
   help: boolean;
   version: boolean;
   _: string[];
@@ -63,6 +64,12 @@ function parse(argv: string[]): Flags {
     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);
@@ -82,7 +89,8 @@ 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
@@ -197,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;
 }

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

@@ -60,8 +60,19 @@ export class TypeRepo {
 
   insert(row: Record<string, unknown>): { changes: number; lastInsertRowid: number | bigint } {
     this.assertFields(row);
-    const keys = Object.keys(row);
+    // Omit keys whose value is `undefined` so the column's own `DEFAULT`/`NULL` governs;
+    // `undefined` means "not provided", never a bound value. An explicit `null` is preserved.
+    const provided = Object.keys(row);
+    const keys = provided.filter((k) => row[k] !== undefined);
     if (keys.length === 0) {
+      // A present-but-all-undefined payload throws (parity with Table.insert): the caller
+      // meant to write those values, so silently inserting a full DEFAULT row would create
+      // an unintended record. A genuinely empty `insert({})` is the explicit "default row".
+      if (provided.length > 0) {
+        throw new Error(
+          `insert into type "${this.typeName}": no columns to insert (all values were undefined)`,
+        );
+      }
       return this.db.run(`INSERT INTO ${this.table()} DEFAULT VALUES`, []);
     }
     const cols = keys.join(", ");

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

@@ -162,3 +162,60 @@ test("query/exec run raw parameterised SQL", async () => {
     assert.equal(Number((rows[0] as { total: number }).total), 42);
   });
 });
+
+test("insert omits undefined-valued keys so the column DEFAULT applies", async () => {
+  await withGateway(async (src) => {
+    const orders = src.table<Order>("orders");
+    // `total` is `NOT NULL DEFAULT 0`; passing it as undefined must omit the column
+    // (not bind NULL, which would violate NOT NULL), letting the DEFAULT fill it.
+    const id = await orders.insert({ status: "new", total: undefined });
+    assert.equal((await orders.get(id))?.total, 0);
+  });
+});
+
+test("insert preserves an explicit null; omits undefined", async () => {
+  await withGateway(async (src) => {
+    await src.exec("CREATE TABLE notes (id INTEGER PRIMARY KEY, body TEXT, tag TEXT DEFAULT 'none')");
+    const notes = src.table("notes");
+    const id = await notes.insert({ body: null, tag: undefined });
+    const row = await notes.get(id);
+    assert.equal(row?.body, null); // explicit null is stored as NULL
+    assert.equal(row?.tag, "none"); // undefined omitted → column DEFAULT
+  });
+});
+
+test("update skips undefined keys and clears on explicit null", async () => {
+  await withGateway(async (src) => {
+    await src.exec("CREATE TABLE notes (id INTEGER PRIMARY KEY, body TEXT, tag TEXT DEFAULT 'none')");
+    const notes = src.table("notes");
+    const id = await notes.insert({ body: "hello", tag: "x" });
+    // tag:undefined must be left unchanged; body updated.
+    await notes.update(id, { tag: undefined, body: "world" });
+    let row = await notes.get(id);
+    assert.equal(row?.body, "world");
+    assert.equal(row?.tag, "x");
+    // explicit null clears the column.
+    await notes.update(id, { body: null });
+    row = await notes.get(id);
+    assert.equal(row?.body, null);
+    // a patch of only-undefined keys is a no-op.
+    assert.equal(await notes.update(id, { tag: undefined }), 0);
+  });
+});
+
+test("insert throws when every provided value is undefined", async () => {
+  await withGateway(async (src) => {
+    const orders = src.table<Order>("orders");
+    await assert.rejects(
+      orders.insert({ status: undefined, total: undefined }),
+      /all values were undefined/,
+    );
+  });
+});
+
+test("insert throws a distinct message for a genuinely empty row", async () => {
+  await withGateway(async (src) => {
+    const orders = src.table<Order>("orders");
+    await assert.rejects(orders.insert({} as Partial<Order>), /empty row/);
+  });
+});

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

@@ -100,12 +100,19 @@ export class Table<T extends object = Row> {
     this.pk = pk;
   }
 
-  /** Insert one row (only the present keys are written); returns the new primary-key value
-   * (the inserted rowid for an INTEGER PRIMARY KEY). */
+  /** Insert one row; returns the new primary-key value (the inserted rowid for an INTEGER
+   * PRIMARY KEY). Keys whose value is `undefined` are omitted, so the table's own column
+   * `DEFAULT`/`NULL` governs — `undefined` means "not provided, let the schema decide", never
+   * a bound value. An explicit `null` is preserved (it stores `NULL`). */
   async insert(row: Partial<T>): Promise<number | bigint> {
-    const keys = Object.keys(row);
+    const provided = Object.keys(row);
+    const keys = provided.filter((k) => (row as Row)[k] !== undefined);
     if (keys.length === 0) {
-      throw new Error(`Table(${this.name}).insert: no columns to insert`);
+      throw new Error(
+        provided.length === 0
+          ? `Table(${this.name}).insert: no columns to insert (empty row)`
+          : `Table(${this.name}).insert: no columns to insert (all values were undefined)`,
+      );
     }
     const cols = keys.map(quoteIdent).join(", ");
     const ph = keys.map(() => "?").join(", ");
@@ -158,9 +165,11 @@ export class Table<T extends object = Row> {
     return rows[0] as T | undefined;
   }
 
-  /** Patch the row with the given primary key; returns rows changed. */
+  /** Patch the row with the given primary key; returns rows changed. Keys whose value is
+   * `undefined` are skipped (that column is left unchanged); an explicit `null` clears the
+   * column to `NULL`. A patch with no defined keys is a no-op. */
   async update(id: unknown, patch: Partial<T>): Promise<number> {
-    const keys = Object.keys(patch);
+    const keys = Object.keys(patch).filter((k) => (patch as Row)[k] !== undefined);
     if (keys.length === 0) return 0;
     const set = keys.map((k) => `${quoteIdent(k)} = ?`).join(", ");
     const r = await this.#src.exec(

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

@@ -152,6 +152,12 @@ test("runtime materializes the manifest end-to-end against a fake engine", async
 
     // field-drift guard
     assert.throws(() => app.data!.repo("task").insert({ bogus: 1 }));
+    // all-declared-but-undefined payload throws (parity with Table.insert): the caller
+    // meant to write those columns, so we don't silently insert a DEFAULT VALUES row.
+    assert.throws(
+      () => app.data!.repo("task").insert({ title: undefined, status: undefined }),
+      /all values were undefined/,
+    );
   } finally {
     await app.stop();
     await rm(dir, { recursive: true, force: true });

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

@@ -40,6 +40,7 @@ test("slugifyTaskType makes a filesystem-safe slug", () => {
 
 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;/);

package/src/toolkit/scaffold/workers.ts

@@ -94,7 +94,7 @@ export function renderWorkerStub(
     `// 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` +
+    `import type { AppJobHandler } from "@nanobpm/urban/worker";\n` +
     generatedImport +
     `\n` +
     `const handler: AppJobHandler${generic} = async (job, app) => {\n` +

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";