@nanobpm/urban 0.17.1 → 0.19.0

package/src/runtime/engine/nanosdk.ts

@@ -17,6 +17,7 @@ import type {
   JobHandler,
   WorkerSubscription,
 } from "../core/host.ts";
+import { isBpmnError } from "../core/host.ts";
 import type { EngineSdkClient } from "./sdk.ts";
 
 /** Coerce an engine response's process-instance key to a non-empty string, or
@@ -38,6 +39,10 @@ export interface NanoSdkActivatedJob {
   variables?: Record<string, unknown>;
   complete(variables?: Record<string, unknown>): Promise<unknown>;
   fail(body: { errorMessage: string; retries?: number }): Promise<unknown>;
+  /** Raise a BPMN error (Zeebe `ThrowError`) routed to an error boundary/event.
+   *  Present on the nano-sdk enriched job at runtime; typed here so the adapter
+   *  can honour a handler's {@link BpmnError} (ADR 0050). */
+  error?(e: { errorCode: string; errorMessage?: string }): Promise<unknown>;
 }
 
 /** Config for a nano-sdk job worker (the subset this adapter sets). */
@@ -233,6 +238,31 @@ export class SdkEngineClient implements EngineClient {
           const out = await handler(engineJob);
           return await job.complete((out as Record<string, unknown> | undefined) ?? {});
         } catch (err) {
+          // A handler-raised BPMN error is a modelled, non-retryable outcome:
+          // report it as a BPMN error (routed to an error boundary/event) rather
+          // than a plain failure. If the transport lacks `error` (older SDK) — or
+          // the `error` call itself fails — fall through to the `fail` path below
+          // so the job is still acknowledged rather than left to lock-timeout.
+          if (isBpmnError(err) && typeof job.error === "function") {
+            // `message` is typed loosely (the guard survives module duplication),
+            // so coerce to a string before slicing to avoid a secondary crash.
+            const raw = (err as { message?: unknown }).message;
+            const message = typeof raw === "string" && raw.length > 0 ? raw : err.errorCode;
+            this.log("info", `handler ${jobType} raised BPMN error`, {
+              errorCode: err.errorCode,
+            });
+            try {
+              return await job.error({
+                errorCode: err.errorCode,
+                errorMessage: message.slice(0, 500),
+              });
+            } catch (errReportErr) {
+              this.log("warn", `handler ${jobType}: BPMN error report failed, failing the job`, {
+                err: errReportErr instanceof Error ? errReportErr.message : String(errReportErr),
+              });
+              // fall through to the fail path
+            }
+          }
           const message = err instanceof Error ? err.message : String(err);
           this.log("error", `handler ${jobType} threw`, { err: message });
           try {

package/src/runtime/index.ts

@@ -55,6 +55,18 @@ export type {
 } from "./core/host.ts";
 export type { AppApi, Mounted, RuntimeContext } from "./core/context.ts";
 
+// BPMN error contract: a handler throws `BpmnError(code)` to raise a modelled
+// error routed to an error boundary (ADR 0050), instead of a retryable failure.
+export { BpmnError, isBpmnError } from "./core/host.ts";
+
+// Connector packs (ADR 0050, in-process port)
+export {
+  adaptConnectorHandler,
+  mountConnectors,
+  resolveInstalledConnectors,
+} from "./core/modules/connectors.ts";
+export type { ConnectorsHandle } from "./core/modules/connectors.ts";
+
 // Data layer
 export { DataLayer, TypeRepo } from "./core/modules/datasource.ts";
 export type { ProvisionedSource } from "./core/modules/datasource.ts";

package/src/toolkit/addConnector.test.ts

@@ -0,0 +1,161 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import type { GenIO } from "./gen.ts";
+import { addConnector } from "./addConnector.ts";
+
+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() {
+      return [];
+    },
+    async exists(p) {
+      return p in files;
+    },
+    async remove(p) {
+      delete files[p];
+    },
+  };
+}
+
+const PKG = "@nanobpm/nano-ide-connector-slack";
+const PACK_ID = "nano-ide-connector-slack";
+
+function baseFiles(appManifest: Record<string, unknown> = { schemaVersion: 1, id: "t", name: "T" }) {
+  return {
+    "app/nano.app.json": JSON.stringify(appManifest),
+    [`app/node_modules/${PKG}/nano-ide.ext.json`]: JSON.stringify({
+      id: PACK_ID,
+      workers: [
+        {
+          type: "slack:send-message",
+          entry: "worker.ts",
+          configFields: [{ key: "botToken", env: "SLACK_BOT_TOKEN" }],
+        },
+      ],
+    }),
+  };
+}
+
+test("addConnector wires a pack-backed worker + a connection into nano.app.json", async () => {
+  const io = memIO(baseFiles());
+  const res = await addConnector({ root: "app", pkg: PKG, io });
+
+  assert.equal(res.packId, PACK_ID);
+  assert.deepEqual(res.wired, [{ taskType: "slack:send-message", alreadyPresent: false }]);
+  assert.deepEqual(res.requiredEnv, ["SLACK_BOT_TOKEN"]);
+  assert.equal(res.connection, "nano-ide-connector-slack");
+
+  const app = JSON.parse(io.files["app/nano.app.json"]);
+  assert.deepEqual(app.workers, [
+    {
+      taskType: "slack:send-message",
+      connector: PACK_ID,
+      connection: "nano-ide-connector-slack",
+    },
+  ]);
+  assert.deepEqual(app.connections["nano-ide-connector-slack"], {
+    type: PACK_ID,
+    botToken: "${SLACK_BOT_TOKEN}",
+  });
+});
+
+test("addConnector is idempotent — re-running does not duplicate entries", async () => {
+  const io = memIO(baseFiles());
+  await addConnector({ root: "app", pkg: PKG, io });
+  const res2 = await addConnector({ root: "app", pkg: PKG, io });
+  assert.deepEqual(res2.wired, [{ taskType: "slack:send-message", alreadyPresent: true }]);
+  const app = JSON.parse(io.files["app/nano.app.json"]);
+  assert.equal(app.workers.length, 1);
+  assert.equal(Object.keys(app.connections).length, 1);
+});
+
+test("addConnector throws on a taskType already backed by a handler (conflict)", async () => {
+  const io = memIO(
+    baseFiles({
+      schemaVersion: 1,
+      id: "t",
+      name: "T",
+      workers: [{ taskType: "slack:send-message", handler: "handlers/slack.ts" }],
+    }),
+  );
+  await assert.rejects(() => addConnector({ root: "app", pkg: PKG, io }), /already declared with handler/);
+});
+
+test("addConnector throws when the package is not an Urban connector", async () => {
+  const io = memIO({ "app/nano.app.json": JSON.stringify({ schemaVersion: 1, id: "t", name: "T" }) });
+  await assert.rejects(() => addConnector({ root: "app", pkg: PKG, io }), /not an Urban connector/);
+});
+
+test("addConnector reports which app manifest fails to parse", async () => {
+  const io = memIO({
+    "app/nano.app.json": "{ not json",
+    [`app/node_modules/${PKG}/nano-ide.ext.json`]: JSON.stringify({
+      id: PACK_ID,
+      workers: [{ type: "slack:send-message", entry: "worker.ts" }],
+    }),
+  });
+  await assert.rejects(() => addConnector({ root: "app", pkg: PKG, io }), /failed to parse .*nano\.app\.json/);
+});
+
+test("addConnector rejects a manifest whose connections is not an object", async () => {
+  const io = memIO(baseFiles({ schemaVersion: 1, id: "t", name: "T", connections: "nope" }));
+  await assert.rejects(() => addConnector({ root: "app", pkg: PKG, io }), /"connections" must be an object/);
+});
+
+test("addConnector rejects an existing connection of a different type", async () => {
+  const io = memIO(
+    baseFiles({
+      schemaVersion: 1,
+      id: "t",
+      name: "T",
+      connections: { [PACK_ID]: { type: "other" } },
+    }),
+  );
+  await assert.rejects(
+    () => addConnector({ root: "app", pkg: PKG, io }),
+    /already exists with type "other"/,
+  );
+});
+
+test("addConnector rejects an existing connection that is not an object", async () => {
+  const io = memIO(
+    baseFiles({ schemaVersion: 1, id: "t", name: "T", connections: { [PACK_ID]: "nope" } }),
+  );
+  await assert.rejects(
+    () => addConnector({ root: "app", pkg: PKG, io }),
+    /already exists and is not an object/,
+  );
+});
+
+test("addConnector backfills missing env pointers on a matching existing connection", async () => {
+  const io = memIO(
+    baseFiles({ schemaVersion: 1, id: "t", name: "T", connections: { [PACK_ID]: { type: PACK_ID } } }),
+  );
+  await addConnector({ root: "app", pkg: PKG, io });
+  const app = JSON.parse(io.files["app/nano.app.json"]);
+  assert.deepEqual(app.connections[PACK_ID], { type: PACK_ID, botToken: "${SLACK_BOT_TOKEN}" });
+});
+
+test("addConnector omits a connection when the pack needs no env credentials", async () => {
+  const io = memIO({
+    "app/nano.app.json": JSON.stringify({ schemaVersion: 1, id: "t", name: "T" }),
+    [`app/node_modules/${PKG}/nano-ide.ext.json`]: JSON.stringify({
+      id: PACK_ID,
+      workers: [{ type: "noop:run", entry: "worker.ts" }],
+    }),
+  });
+  const res = await addConnector({ root: "app", pkg: PKG, io });
+  assert.equal(res.connection, undefined);
+  assert.deepEqual(res.requiredEnv, []);
+  const app = JSON.parse(io.files["app/nano.app.json"]);
+  assert.deepEqual(app.workers, [{ taskType: "noop:run", connector: PACK_ID }]);
+  assert.equal(app.connections, undefined);
+});

package/src/toolkit/addConnector.ts

@@ -0,0 +1,233 @@
+// addConnector — enable an installed connector pack into an app's nano.app.json.
+//
+// A connector pack ships a `nano-ide.ext.json` manifest declaring one or more
+// workers (a `taskType`, a worker `entry`, and its config fields). "Enabling" it
+// means the pure, idempotent manifest edit the `urban add` CLI performs after
+// `npm install <pkg>` (ADR 0050 §5): for every worker the pack declares, append a
+// pack-backed `workers[]` entry (`{ taskType, connector: <pack-id>, connection }`)
+// and, when the pack needs credentials, a named `connections[]` entry whose values
+// are env-pointer templates (never inline secrets, ADR 0025 §1 / 0027 §5).
+//
+// This module only reads/writes files through the GenIO port — installing the
+// package (a subprocess) is the CLI's job, so this stays runtime-agnostic and
+// unit-testable.
+
+import type { GenIO } from "./gen.ts";
+
+/** A config field a pack declares (subset of ext-types `ConfigField`). */
+interface PackConfigField {
+  key: string;
+  label?: string;
+  env?: string;
+  default?: string;
+}
+
+/** A worker a pack declares (subset of ext-types `WorkerSpec`). */
+interface PackWorkerSpec {
+  type: string;
+  entry: string;
+  displayName?: string;
+  maxParallelJobs?: number;
+  configFields?: PackConfigField[];
+}
+
+/** The pack manifest (`nano-ide.ext.json`) fields `addConnector` reads. */
+interface PackManifest {
+  id: string;
+  workers?: PackWorkerSpec[];
+}
+
+export interface AddConnectorOptions {
+  /** App root directory. */
+  root: string;
+  /** The installed npm package name (already present under node_modules). */
+  pkg: string;
+  /** Manifest filename under root. Default "nano.app.json". */
+  manifestFile?: string;
+  io: GenIO;
+}
+
+export interface AddConnectorResult {
+  /** The pack id (`nano-ide.ext.json` `id`) written to each worker's `connector`. */
+  packId: string;
+  /** Workers considered, with whether one was already wired (idempotent). */
+  wired: { taskType: string; alreadyPresent: boolean }[];
+  /** The named connection created/reused, if the pack needs credentials. */
+  connection?: string;
+  /** Env vars the operator must set for the enabled workers to run. */
+  requiredEnv: string[];
+}
+
+const MANIFEST_FILE = "nano-ide.ext.json";
+
+function joinPath(a: string, b: string): string {
+  // Trim both slash styles (as toolkit/gen.ts joinPath does) so a Windows-style
+  // root does not produce an invalid path.
+  return `${a.replace(/[/\\]+$/, "")}/${b.replace(/^[/\\]+/, "")}`;
+}
+
+/** A stable, slug-ish connection name for a pack id (kebab, no leading scope). */
+function connectionNameFor(packId: string): string {
+  const base = packId.includes("/") ? packId.slice(packId.lastIndexOf("/") + 1) : packId;
+  return base.replace(/[^a-z0-9]+/gi, "-").replace(/^-+|-+$/g, "").toLowerCase() || packId;
+}
+
+/**
+ * Read the installed pack manifest, then wire its workers into the app manifest.
+ * Idempotent: re-running never duplicates a `workers[]`/`connections[]` entry.
+ * The app manifest object is mutated in place and written back.
+ */
+export async function addConnector(opts: AddConnectorOptions): Promise<AddConnectorResult> {
+  const { root, pkg, io } = opts;
+  const manifestFile = opts.manifestFile ?? "nano.app.json";
+
+  const packManifestPath = joinPath(joinPath(joinPath(root, "node_modules"), pkg), MANIFEST_FILE);
+  if (!(await io.exists(packManifestPath))) {
+    throw new Error(
+      `"${pkg}" is not an Urban connector: no ${MANIFEST_FILE} found at ${packManifestPath}. ` +
+        `Install the package first (\`npm install ${pkg}\`), and check it is a connector pack.`,
+    );
+  }
+  let pack: PackManifest;
+  try {
+    pack = JSON.parse(await io.readText(packManifestPath)) as PackManifest;
+  } catch (err) {
+    throw new Error(`failed to parse ${packManifestPath}: ${(err as Error).message}`);
+  }
+  if (typeof pack.id !== "string" || !pack.id) {
+    throw new Error(`${packManifestPath} has no string "id" (a pack must declare its id).`);
+  }
+  const specs = Array.isArray(pack.workers) ? pack.workers : [];
+  if (specs.length === 0) {
+    throw new Error(`connector pack "${pack.id}" declares no workers[] — nothing to enable.`);
+  }
+  // `type` comes from JSON; a malformed pack must fail loudly rather than wire an
+  // invalid worker entry (or manufacture a confusing conflict).
+  for (const spec of specs) {
+    if (typeof spec.type !== "string" || spec.type.length === 0) {
+      throw new Error(
+        `connector pack "${pack.id}" has a worker with a missing/non-string "type" in ${packManifestPath}.`,
+      );
+    }
+  }
+
+  const appManifestPath = joinPath(root, manifestFile);
+  if (!(await io.exists(appManifestPath))) {
+    throw new Error(`no ${manifestFile} at ${appManifestPath} — run this inside an Urban app.`);
+  }
+  let app: {
+    workers?: { taskType?: string; connector?: string; connection?: string; handler?: string; llm?: string }[];
+    connections?: Record<string, Record<string, unknown>>;
+    [k: string]: unknown;
+  };
+  try {
+    app = JSON.parse(await io.readText(appManifestPath));
+  } catch (err) {
+    throw new Error(`failed to parse ${appManifestPath}: ${(err as Error).message}`);
+  }
+  if (app === null || typeof app !== "object" || Array.isArray(app)) {
+    throw new Error(`${appManifestPath} is not a JSON object.`);
+  }
+  if (app.workers !== undefined && !Array.isArray(app.workers)) {
+    throw new Error(`${appManifestPath} "workers" must be an array.`);
+  }
+  if (
+    app.connections !== undefined &&
+    (app.connections === null || typeof app.connections !== "object" || Array.isArray(app.connections))
+  ) {
+    throw new Error(`${appManifestPath} "connections" must be an object.`);
+  }
+  const workers = (app.workers ??= []);
+
+  // Required env across the pack's workers (env-pointer fields without a default).
+  const envFields: PackConfigField[] = [];
+  const requiredEnvSet = new Set<string>();
+  for (const spec of specs) {
+    for (const f of spec.configFields ?? []) {
+      if (f.env) {
+        envFields.push(f);
+        if (f.default === undefined || f.default === "") requiredEnvSet.add(f.env);
+      }
+    }
+  }
+
+  // Create/reuse a named connection when the pack carries credential config, so the
+  // required env pointers are documented in the manifest (secrets stay templates).
+  let connection: string | undefined;
+  if (envFields.length > 0) {
+    connection = connectionNameFor(pack.id);
+    const connections = (app.connections ??= {});
+    const existing = connections[connection];
+    if (existing === undefined) {
+      const conn: Record<string, unknown> = { type: pack.id };
+      for (const f of envFields) {
+        if (!(f.key in conn) && f.env) conn[f.key] = `\${${f.env}}`;
+      }
+      connections[connection] = conn;
+    } else {
+      // A pre-existing connection of this name must be a compatible object of the
+      // same pack `type`; otherwise wiring workers to it would produce an invalid
+      // or misleading manifest. Fail loudly instead of silently reusing it.
+      if (existing === null || typeof existing !== "object" || Array.isArray(existing)) {
+        throw new Error(`connection "${connection}" already exists and is not an object.`);
+      }
+      const conn = existing as Record<string, unknown>;
+      if (conn.type !== undefined && conn.type !== pack.id) {
+        throw new Error(
+          `connection "${connection}" already exists with type "${String(conn.type)}", ` +
+            `not "${pack.id}".`,
+        );
+      }
+      // Backfill the pack's `type` and any missing env-pointer templates.
+      if (conn.type === undefined) conn.type = pack.id;
+      for (const f of envFields) {
+        if (!(f.key in conn) && f.env) conn[f.key] = `\${${f.env}}`;
+      }
+    }
+  }
+
+  const wired: { taskType: string; alreadyPresent: boolean }[] = [];
+  for (const spec of specs) {
+    const existing = workers.find((w) => w.taskType === spec.type);
+    if (existing) {
+      // A same-taskType worker backed by a handler/llm or a different connector is
+      // a real conflict — enabling this pack would not take effect. Fail loudly
+      // instead of reporting a false success.
+      if (existing.connector !== pack.id) {
+        const backing = existing.handler
+          ? `handler "${existing.handler}"`
+          : existing.llm
+            ? `llm "${existing.llm}"`
+            : existing.connector
+              ? `connector "${existing.connector}"`
+              : "another backing";
+        throw new Error(
+          `worker "${spec.type}" is already declared with ${backing}; ` +
+            `remove it before enabling connector "${pack.id}" for that taskType.`,
+        );
+      }
+      wired.push({ taskType: spec.type, alreadyPresent: true });
+      // Heal an entry that references the pack but predates the connection.
+      if (connection && !existing.connection) {
+        existing.connection = connection;
+      }
+      continue;
+    }
+    const entry: { taskType: string; connector: string; connection?: string } = {
+      taskType: spec.type,
+      connector: pack.id,
+    };
+    if (connection) entry.connection = connection;
+    workers.push(entry);
+    wired.push({ taskType: spec.type, alreadyPresent: false });
+  }
+
+  await io.writeText(appManifestPath, JSON.stringify(app, null, 2) + "\n");
+
+  return {
+    packId: pack.id,
+    wired,
+    connection,
+    requiredEnv: [...requiredEnvSet],
+  };
+}

package/src/toolkit/fsio.test.ts

@@ -19,3 +19,26 @@ test("listDir returns empty for a missing directory", async () => {
   const io = createNodeGenIO();
   assert.deepEqual(await io.listDir(join(tmpdir(), "urban-fsio-does-not-exist-xyz")), []);
 });
+
+test("importModule caches on mtime: unchanged reuses, edit reloads", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "urban-fsio-imp-"));
+  const file = join(dir, "mod.mjs");
+  await writeFile(file, "export const v = 1;");
+  const io = createNodeGenIO();
+
+  const first = await io.importModule!(file);
+  assert.equal(first.v, 1);
+  // Same mtime → same module URL → cached instance (same object identity).
+  const again = await io.importModule!(file);
+  assert.equal(again, first);
+
+  // Edit with a strictly newer mtime → new URL → fresh module with the new value.
+  await new Promise((r) => setTimeout(r, 10));
+  await writeFile(file, "export const v = 2;");
+  const utimes = (await import("node:fs/promises")).utimes;
+  const t = Date.now() / 1000 + 5;
+  await utimes(file, t, t);
+  const edited = await io.importModule!(file);
+  assert.equal(edited.v, 2);
+  assert.notEqual(edited, first);
+});

package/src/toolkit/fsio.ts

@@ -1,8 +1,9 @@
 // Node/Deno filesystem implementation of the GenIO port. Uses node:fs/promises, which both
 // Node and Deno provide, so a single implementation serves both runtimes.
 
-import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
-import { dirname } from "node:path";
+import { mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
 import type { GenIO } from "./gen.ts";
 
 export function createNodeGenIO(): GenIO {
@@ -32,5 +33,24 @@ export function createNodeGenIO(): GenIO {
         return false;
       }
     },
+    async remove(path: string): Promise<void> {
+      await rm(path, { force: true });
+    },
+    // Import an app module for code-first model derivation. `import()` of a file URL loads TS on
+    // Deno natively and on Node with type-stripping (≥22.18 default, or `--experimental-strip-types`).
+    // The cache key is the file's mtime, not a monotonic clock: an unchanged workflow reuses the
+    // cached module instance (bounding the ESM module map in long-lived processes like `urban dev`)
+    // while an edited one still reloads.
+    async importModule(path: string): Promise<Record<string, unknown>> {
+      const abs = resolve(path);
+      let version = "";
+      try {
+        version = `?v=${(await stat(abs)).mtimeMs}`;
+      } catch {
+        // stat failed (e.g. a virtual path); fall back to no cache key and let import() surface it.
+      }
+      const href = `${pathToFileURL(abs).href}${version}`;
+      return import(href) as Promise<Record<string, unknown>>;
+    },
   };
 }

package/src/toolkit/gen.test.ts

@@ -1,9 +1,14 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { runGen, collectArtifacts, type GenIO } from "./gen.ts";
+import { defineFlow, envelope } from "@nanobpm/workflow";
+import { MODEL_PROVENANCE } from "./models.ts";
 
 /** In-memory filesystem for deterministic, IO-free gen tests. */
-function memIO(files: Record<string, string>): GenIO & { files: Record<string, string> } {
+function memIO(
+  files: Record<string, string>,
+  modules: Record<string, Record<string, unknown>> = {},
+): GenIO & { files: Record<string, string> } {
   return {
     files,
     async readText(p) {
@@ -27,6 +32,13 @@ function memIO(files: Record<string, string>): GenIO & { files: Record<string, s
     async exists(p) {
       return p in files;
     },
+    async remove(p) {
+      delete files[p];
+    },
+    async importModule(p) {
+      if (!(p in modules)) throw new Error(`no module registered for ${p}`);
+      return modules[p];
+    },
   };
 }
 
@@ -90,3 +102,66 @@ test("collectArtifacts touches no writes", async () => {
   await collectArtifacts({ root: "/app", io });
   assert.equal(Object.keys(io.files).length, before);
 });
+
+// --- code-first model derivation (urban gen / urban derive) ---
+
+const GreetIn = envelope("GreetIn", { who: "string" });
+const GreetOut = envelope("GreetOut", { message: "string" });
+const greetFlow = defineFlow("greet", { hello: { in: GreetIn, out: GreetOut } }, (w) => {
+  w.run("hello", async () => ({ message: "hi" }));
+});
+
+const CODE_FIRST_MANIFEST = JSON.stringify({
+  id: "cf",
+  data: { default: "app" },
+  models: { workflows: ["workflows/*.ts"] },
+  types: { greeting: { table: "greetings", fields: { who: { type: "string" } } } },
+});
+
+function codeFirstIO() {
+  return memIO(
+    {
+      "/cf/nano.app.json": CODE_FIRST_MANIFEST,
+      "/cf/workflows/greet.ts": "// derived in-memory via importModule stub",
+    },
+    { "/cf/workflows/greet.ts": { greet: greetFlow } },
+  );
+}
+
+test("runGen derives processes/<id>.bpmn from workflows/*.ts and feeds worker-io off it", async () => {
+  const io = codeFirstIO();
+  const res = await runGen({ root: "/cf", io });
+  const bpmn = io.files["/cf/processes/greet.bpmn"];
+  assert.ok(bpmn, "expected a derived processes/greet.bpmn");
+  assert.ok(bpmn.includes(MODEL_PROVENANCE), "derived .bpmn must be provenance-stamped");
+  assert.ok(bpmn.includes('type="greet:hello"'), "derived .bpmn carries the task type");
+  // worker-io is derived FROM the in-memory model, not from any on-disk file.
+  assert.ok(io.files["/cf/nano-generated/worker-io.d.ts"].includes("greet:hello"));
+  assert.equal(res.incomplete, false);
+  assert.deepEqual(res.modelErrors, []);
+});
+
+test("gen --no-models derives in-memory for worker-io but writes no .bpmn", async () => {
+  const io = codeFirstIO();
+  const res = await runGen({ root: "/cf", io, emitModels: false });
+  assert.equal(io.files["/cf/processes/greet.bpmn"], undefined, "must not write .bpmn");
+  // still derives the model in-memory so worker-io is populated.
+  assert.ok(io.files["/cf/nano-generated/worker-io.d.ts"].includes("greet:hello"));
+  assert.equal(res.incomplete, false);
+});
+
+test("the provenance sweep removes a stale derived .bpmn no longer backed by a workflow", async () => {
+  const io = codeFirstIO();
+  // a leftover derived model from a since-deleted flow, provenance-stamped.
+  io.files["/cf/processes/stale.bpmn"] = `<?xml version="1.0"?>\n${MODEL_PROVENANCE}\n<bpmn:x/>`;
+  await runGen({ root: "/cf", io });
+  assert.ok(io.files["/cf/processes/greet.bpmn"], "keeps the live derived model");
+  assert.equal(io.files["/cf/processes/stale.bpmn"], undefined, "sweeps the stale derived model");
+});
+
+test("the sweep never touches an authored (un-stamped) .bpmn", async () => {
+  const io = codeFirstIO();
+  io.files["/cf/processes/authored.bpmn"] = `<?xml version="1.0"?>\n<bpmn:authored/>`;
+  await runGen({ root: "/cf", io });
+  assert.ok(io.files["/cf/processes/authored.bpmn"], "authored .bpmn must survive the sweep");
+});