@nanobpm/urban 0.17.1 → 0.18.0

package/src/cli.ts

@@ -2,7 +2,8 @@
 //
 //   urban new <name>     scaffold a new app (delegates to create-urban-app)
 //   urban check          load + validate the manifest, report issues
-//   urban gen            derive generated artifacts (migrations, worker I/O)
+//   urban gen            derive generated artifacts (migrations, worker I/O, code-first models)
+//   urban derive         derive code-first models only (workflows/*.ts → processes/*.bpmn)
 //   urban run            materialize + serve the app (deploy, data, workers, surfaces, triggers)
 //   urban dev            like run, plus watch sources and hot-reload on change
 //   urban deploy         deploy models only, then exit
@@ -19,7 +20,7 @@ import {
   selectHost,
 } from "./runtime/index.ts";
 import { scaffold, slugify } from "create-urban-app";
-import { createNodeGenIO, runGen, scaffoldWorkers } from "./toolkit/index.ts";
+import { createNodeGenIO, previewModels, runGen, scaffoldWorkers } from "./toolkit/index.ts";
 import { pathToFileURL } from "node:url";
 import { readFileSync } from "node:fs";
 
@@ -44,6 +45,8 @@ interface Flags {
   check: boolean;
   write: boolean;
   deno: boolean;
+  models: boolean;
+  stdout: boolean;
   style?: "model" | "code";
   help: boolean;
   version: boolean;
@@ -51,7 +54,7 @@ interface Flags {
 }
 
 function parse(argv: string[]): Flags {
-  const f: Flags = { root: ".", manifest: "nano.app.json", check: false, write: false, deno: false, help: false, version: false, _: [] };
+  const f: Flags = { root: ".", manifest: "nano.app.json", check: false, write: false, deno: false, models: true, stdout: 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`);
@@ -64,6 +67,9 @@ 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 === "--no-models") f.models = false;
+    else if (a === "--models") f.models = true;
+    else if (a === "--stdout") f.stdout = true;
     else if (a === "--code-first") f.style = "code";
     else if (a === "--style") {
       const v = need(++i, a);
@@ -92,7 +98,10 @@ Usage:
   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 gen [--check] [--no-models] derive artifacts (migrations, worker-io, + code-first models)
+                                    (--no-models: skip writing derived .bpmn; type-contracts only)
+  urban derive [--check|--stdout]   derive code-first models only (workflows/*.ts → processes/*.bpmn)
+                                    (--stdout: print {models,incomplete} JSON without writing)
   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
@@ -125,7 +134,12 @@ async function cmdCheck(f: Flags): Promise<number> {
 
 async function cmdGen(f: Flags): Promise<number> {
   const io = createNodeGenIO();
-  const res = await runGen({ root: f.root, io, manifestFile: f.manifest, check: f.check });
+  const res = await runGen({ root: f.root, io, manifestFile: f.manifest, check: f.check, emitModels: f.models });
+  if (res.incomplete) {
+    console.error(`✖ ${res.modelErrors.length} workflow(s) failed to derive:`);
+    for (const e of res.modelErrors) console.error(`  • ${e.path}: ${e.message}`);
+    return 1;
+  }
   if (f.check) {
     if (res.drift.length === 0) {
       console.log(`✔ generated artifacts are up to date (${res.artifacts.length} checked)`);
@@ -140,6 +154,55 @@ async function cmdGen(f: Flags): Promise<number> {
   return 0;
 }
 
+async function cmdDerive(f: Flags): Promise<number> {
+  // `urban derive` IS model derivation, so `--no-models` is contradictory. Reject it explicitly
+  // rather than silently ignoring it (flags are global, so it's easy to pass by accident).
+  if (!f.models) {
+    console.error(
+      "✖ `urban derive` derives models — `--no-models` is contradictory. Use `urban gen --no-models` for type-contracts only.",
+    );
+    return 2;
+  }
+  const io = createNodeGenIO();
+
+  // Non-writing preview: emit `{ models: [{ id, kind, xml }], incomplete }` to stdout for the
+  // console's read-only model viewer (never touches `processes/`).
+  if (f.stdout) {
+    const d = await previewModels({ root: f.root, io, manifestFile: f.manifest });
+    process.stdout.write(
+      JSON.stringify({
+        models: d.list.map((m) => ({ id: m.id, kind: m.kind, xml: m.xml })),
+        incomplete: d.incomplete,
+      }) + "\n",
+    );
+    if (d.incomplete) {
+      for (const e of d.errors) console.error(`  • ${e.path}: ${e.message}`);
+      return 1;
+    }
+    return 0;
+  }
+
+  // Derive + write models only (skip the type-contract derivers); `generate_models` delegates here.
+  const res = await runGen({ root: f.root, io, manifestFile: f.manifest, check: f.check, modelsOnly: true });
+  if (res.incomplete) {
+    console.error(`✖ ${res.modelErrors.length} workflow(s) failed to derive:`);
+    for (const e of res.modelErrors) console.error(`  • ${e.path}: ${e.message}`);
+    return 1;
+  }
+  if (f.check) {
+    if (res.drift.length === 0) {
+      console.log(`✔ derived models are up to date (${res.artifacts.length} checked)`);
+      return 0;
+    }
+    console.error(`✖ ${res.drift.length} derived model(s) are out of date — run \`urban derive\`:`);
+    for (const p of res.drift) console.error(`  • ${p}`);
+    return 1;
+  }
+  console.log(`✔ derived ${res.artifacts.length} model(s):`);
+  for (const a of res.artifacts) console.log(`  • ${a.path}`);
+  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 });
@@ -243,6 +306,8 @@ export async function main(argv: string[]): Promise<number> {
       return cmdCheck(f);
     case "gen":
       return cmdGen(f);
+    case "derive":
+      return cmdDerive(f);
     case "stubs":
       return cmdStubs(f);
     case "run":

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");
+});

package/src/toolkit/gen.ts

@@ -10,6 +10,7 @@ import { deriveDomain } from "./derivers/domain.ts";
 import { deriveWorkerBindings, type ModelSource } from "./derivers/worker-io.ts";
 import { deriveMeta } from "./derivers/meta.ts";
 import { deriveMessageBindings } from "./derivers/messages.ts";
+import { deriveModels, type DerivedModels, type ModelError, MODEL_PROVENANCE } from "./models.ts";
 
 /** Minimal filesystem port. Node/Deno impls live in `fsio.ts`. */
 export interface GenIO {
@@ -18,18 +19,40 @@ export interface GenIO {
   /** File names (not paths) in a directory; empty if it does not exist. */
   listDir(path: string): Promise<string[]>;
   exists(path: string): Promise<boolean>;
+  /**
+   * Import an app module and return its exports. Optional: only present when the caller runs on
+   * a runtime that can load the app's TypeScript (Node with type-stripping, or Deno). Code-first
+   * model derivation (`workflows/*.ts` → BPMN) needs it; when absent, gen still derives everything
+   * else (migrations, domain, worker I/O from authored/derived models).
+   */
+  importModule?(path: string): Promise<Record<string, unknown>>;
+  /** Delete a file. Optional: enables the provenance-scoped stale-model sweep (skipped when absent). */
+  remove?(path: string): Promise<void>;
 }
 
 export interface GenOptions {
   root: string;
   io: GenIO;
   manifestFile?: string;
+  /**
+   * Whether to emit (write) derived `.bpmn` models. Default true. When false, code-first models
+   * are still derived *in-memory* to feed the type-contract derivers (worker I/O, meta, messages)
+   * — they are just not written to disk or swept. This is the `urban gen --no-models` path, so
+   * the console's type-contract regen never mutates `processes/*.bpmn`.
+   */
+  emitModels?: boolean;
+  /** Derive ONLY the models (skip migrations/domain/worker-I/O). The `urban derive` path. */
+  modelsOnly?: boolean;
 }
 
 export interface GenResult {
   artifacts: DerivedArtifact[];
   /** Paths that differ from disk (only populated by `check`). */
   drift: string[];
+  /** True if any code-first workflow failed to import/derive. */
+  incomplete: boolean;
+  /** Per-file model-derivation errors (empty on success). */
+  modelErrors: ModelError[];
 }
 
 function join(root: string, rel: string): string {
@@ -44,7 +67,7 @@ function dirOf(p: string): string {
 }
 
 /** Resolve a `dir/*.ext` (or literal) manifest pattern to file paths relative to root. */
-async function expandPattern(root: string, io: GenIO, pattern: string): Promise<string[]> {
+export async function expandPattern(root: string, io: GenIO, pattern: string): Promise<string[]> {
   const star = pattern.indexOf("*");
   if (star === -1) {
     return (await io.exists(join(root, pattern))) ? [pattern] : [];
@@ -78,36 +101,55 @@ export async function readModels(
 
 /** Collect all artifacts a run would produce, without touching disk beyond reads. */
 export async function collectArtifacts(opts: GenOptions): Promise<DerivedArtifact[]> {
+  return (await collectAll(opts)).artifacts;
+}
+
+/** Internal: collect artifacts AND the model-derivation details (needed by `runGen` for the
+ * incomplete signal + the provenance-scoped stale sweep). */
+async function collectAll(opts: GenOptions): Promise<{ artifacts: DerivedArtifact[]; derived: DerivedModels }> {
   const { root, io } = opts;
+  const emitModels = opts.emitModels ?? true;
   const manifestPath = join(root, opts.manifestFile ?? "nano.app.json");
   const manifest = JSON.parse(await io.readText(manifestPath)) as ToolkitManifest & {
-    models?: { processes?: string[] };
+    models?: { processes?: string[]; workflows?: string[] };
   };
 
   const artifacts: DerivedArtifact[] = [];
 
   // 1. types → migrations + domain row types (DomainTables spine + DomainTypes registry)
-  if (manifest.types && Object.keys(manifest.types).length > 0) {
+  if (!opts.modelsOnly && manifest.types && Object.keys(manifest.types).length > 0) {
     artifacts.push(...deriveMigrations(manifest));
     artifacts.push(...deriveDomain(manifest));
   }
 
-  // 2. models → worker I/O index + model-metadata accessor + message payload map
-  const models = await readModels(root, io, manifest);
-  if (models.length > 0) {
-    const declaredTypeIds = Object.keys(manifest.types ?? {});
-    artifacts.push(...deriveWorkerBindings(models, declaredTypeIds));
-    artifacts.push(...deriveMeta(models));
-    artifacts.push(...deriveMessageBindings(models, declaredTypeIds));
+  // 2. code-first models → derive BPMN from `workflows/*.ts` (executes the app's TS). The derived
+  //    `.bpmn` are emitted only when `emitModels` (default), but always fed to the type-contract
+  //    derivers below so worker I/O works for a code-first app even on a `--no-models` run.
+  const derived = await deriveModels(root, io, manifest);
+  if (emitModels) artifacts.push(...derived.artifacts);
+
+  // 3. models (authored on-disk + derived) → worker I/O index + meta accessor + message map.
+  //    Drop any on-disk model whose path a derived model already covers, to avoid double-counting.
+  if (!opts.modelsOnly) {
+    const derivedPaths = new Set(derived.artifacts.map((a) => a.path));
+    const diskModels = (await readModels(root, io, manifest)).filter((m) => !derivedPaths.has(m.path));
+    const models = [...diskModels, ...derived.models];
+    if (models.length > 0) {
+      const declaredTypeIds = Object.keys(manifest.types ?? {});
+      artifacts.push(...deriveWorkerBindings(models, declaredTypeIds));
+      artifacts.push(...deriveMeta(models));
+      artifacts.push(...deriveMessageBindings(models, declaredTypeIds));
+    }
   }
 
-  return sortArtifacts(artifacts);
+  return { artifacts: sortArtifacts(artifacts), derived };
 }
 
 /** Run the derivers and write artifacts (or, with `check`, report drift without writing). */
 export async function runGen(opts: GenOptions & { check?: boolean }): Promise<GenResult> {
-  const artifacts = await collectArtifacts(opts);
+  const { artifacts, derived } = await collectAll(opts);
   const { root, io } = opts;
+  const emitModels = opts.emitModels ?? true;
   const drift: string[] = [];
 
   for (const a of artifacts) {
@@ -119,7 +161,33 @@ export async function runGen(opts: GenOptions & { check?: boolean }): Promise<Ge
       await io.writeText(abs, a.content);
     }
   }
-  return { artifacts, drift };
+
+  // Provenance-scoped stale sweep: delete derived `.bpmn` for flows that no longer exist. Only
+  // in write mode, only when we emitted models, only on a complete derivation (never delete when
+  // a workflow failed to load), and only files bearing our marker (authored models are untouched).
+  if (!opts.check && emitModels && derived.attempted && !derived.incomplete && io.remove) {
+    const keep = new Set(derived.artifacts.map((a) => a.path));
+    for (const name of await io.listDir(join(root, derived.outDir))) {
+      if (!name.endsWith(".bpmn")) continue;
+      const rel = `${derived.outDir}/${name}`;
+      if (keep.has(rel)) continue;
+      const content = await io.readText(join(root, rel));
+      if (content.includes(MODEL_PROVENANCE)) await io.remove(join(root, rel));
+    }
+  }
+
+  return { artifacts, drift, incomplete: derived.incomplete, modelErrors: derived.errors };
 }
 
 export { dirOf, join as joinPath };
+
+/** Derive code-first models in-memory (no writes) — backs `urban derive --stdout`, the
+ * non-mutating preview the console's read-only model viewer uses. */
+export async function previewModels(opts: GenOptions): Promise<DerivedModels> {
+  const { root, io } = opts;
+  const manifestPath = join(root, opts.manifestFile ?? "nano.app.json");
+  const manifest = JSON.parse(await io.readText(manifestPath)) as {
+    models?: { processes?: string[]; workflows?: string[] };
+  };
+  return deriveModels(root, io, manifest);
+}

package/src/toolkit/index.ts

@@ -83,10 +83,22 @@ import { messagesDeriver } from "./derivers/messages.ts";
 export const DERIVERS = [migrationsDeriver, domainDeriver, workerIoDeriver, metaDeriver, messagesDeriver] as const;
 
 // Gen orchestrator + IO
-export { collectArtifacts, runGen, joinPath, readModels } from "./gen.ts";
+export { collectArtifacts, runGen, joinPath, readModels, expandPattern, previewModels } from "./gen.ts";
 export type { GenIO, GenOptions, GenResult } from "./gen.ts";
 export { createNodeGenIO } from "./fsio.ts";
 
+// Code-first model derivation (workflows/*.ts → BPMN)
+export {
+  deriveModels,
+  isWorkflow,
+  bpmnFilename,
+  processesOutDir,
+  DEFAULT_WORKFLOW_PATTERNS,
+  PROCESSES_DIR,
+  MODEL_PROVENANCE,
+} from "./models.ts";
+export type { DerivedModels, DerivedModelInfo, ModelError, ModelsManifest } from "./models.ts";
+
 // Worker-stub scaffolder (ADR 0056): write-once handler stubs from the model.
 export {
   planWorkerScaffold,

package/src/toolkit/models.test.ts

@@ -0,0 +1,159 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { defineFlow, envelope } from "@nanobpm/workflow";
+import { deriveModels, isWorkflow, bpmnFilename, processesOutDir, MODEL_PROVENANCE } from "./models.ts";
+import type { GenIO } from "./gen.ts";
+
+/** In-memory GenIO whose `importModule` returns pre-registered module exports by path. */
+function memIO(
+  files: Record<string, string>,
+  modules: Record<string, Record<string, unknown>> = {},
+): GenIO {
+  return {
+    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 || p in modules;
+    },
+    importModule(p) {
+      const key = Object.keys(modules).find((k) => p.endsWith(k));
+      if (!key) return Promise.reject(new Error(`ENOENT ${p}`));
+      return Promise.resolve(modules[key]);
+    },
+  };
+}
+
+const GreetIn = envelope("GreetIn", { who: "string" });
+const GreetOut = envelope("GreetOut", { message: "string" });
+
+/** A real one-step declarative flow (exercises the actual toBpmn + layout pipeline). */
+const greet = defineFlow("greet", { hello: { in: GreetIn, out: GreetOut } }, (w) => {
+  w.run("hello", async () => ({ message: "hi" }));
+});
+
+const CODE_FIRST_MANIFEST = { models: { workflows: ["workflows/*.ts"] } };
+
+test("isWorkflow recognizes defineFlow exports, rejects everything else", () => {
+  assert.equal(isWorkflow(greet), true);
+  assert.equal(isWorkflow({ id: "x", kind: "imperative" }), true);
+  assert.equal(isWorkflow({ id: "x", kind: "nope" }), false);
+  assert.equal(isWorkflow({ kind: "declarative" }), false);
+  assert.equal(isWorkflow(null), false);
+  assert.equal(isWorkflow("greet"), false);
+});
+
+test("bpmnFilename sanitizes ids into safe .bpmn filenames", () => {
+  assert.equal(bpmnFilename("greet"), "greet.bpmn");
+  assert.equal(bpmnFilename("orders/place"), "orders-place.bpmn");
+  assert.equal(bpmnFilename("a b:c"), "a-b-c.bpmn");
+});
+
+test("processesOutDir defaults to processes/, or the dir of a models.processes glob", () => {
+  assert.equal(processesOutDir({}), "processes");
+  assert.equal(processesOutDir({ models: { processes: ["resources/processes/*.bpmn"] } }), "resources/processes");
+  assert.equal(processesOutDir({ models: { processes: ["src/models/*.bpmn"] } }), "src/models");
+});
+
+test("deriveModels turns workflows/*.ts into a provenance-stamped processes/<id>.bpmn", async () => {
+  const io = memIO(
+    { "/app/workflows/greet.ts": "// source" },
+    { "workflows/greet.ts": { greet } },
+  );
+  const d = await deriveModels("/app", io, CODE_FIRST_MANIFEST);
+
+  assert.equal(d.attempted, true);
+  assert.equal(d.incomplete, false);
+  assert.deepEqual(d.ids, ["greet"]);
+  assert.equal(d.artifacts.length, 1);
+  assert.equal(d.artifacts[0].path, "processes/greet.bpmn");
+  assert.match(d.artifacts[0].content, /<!--.*@nanobpm\/urban/);
+  assert.ok(d.artifacts[0].content.includes(MODEL_PROVENANCE));
+  assert.match(d.artifacts[0].content, /greet/);
+  // the in-memory ModelSource is fed to the type-contract derivers
+  assert.deepEqual(d.models.map((m) => m.path), ["processes/greet.bpmn"]);
+  assert.equal(d.list[0].id, "greet");
+  assert.equal(d.list[0].kind, "declarative");
+});
+
+test("deriveModels is a no-op without a module loader (pure/IDE callers)", async () => {
+  const io = memIO({ "/app/workflows/greet.ts": "// source" });
+  delete (io as { importModule?: unknown }).importModule;
+  const d = await deriveModels("/app", io, CODE_FIRST_MANIFEST);
+  assert.equal(d.attempted, false);
+  assert.equal(d.artifacts.length, 0);
+});
+
+test("deriveModels writes into the manifest's models.processes dir when declared", async () => {
+  const io = memIO(
+    { "/app/workflows/greet.ts": "// source" },
+    { "workflows/greet.ts": { greet } },
+  );
+  const d = await deriveModels("/app", io, {
+    models: { workflows: ["workflows/*.ts"], processes: ["resources/processes/*.bpmn"] },
+  });
+  assert.equal(d.outDir, "resources/processes");
+  assert.equal(d.artifacts[0].path, "resources/processes/greet.bpmn");
+});
+
+test("deriveModels records a failing workflow as incomplete without throwing", async () => {
+  const io = memIO(
+    { "/app/workflows/bad.ts": "// source" },
+    {}, // no module registered → importModule rejects
+  );
+  const d = await deriveModels("/app", io, CODE_FIRST_MANIFEST);
+  assert.equal(d.attempted, true);
+  assert.equal(d.incomplete, true);
+  assert.equal(d.errors.length, 1);
+  assert.equal(d.errors[0].path, "workflows/bad.ts");
+});
+
+test("deriveModels flags a duplicate flow id across two files", async () => {
+  const io = memIO(
+    { "/app/workflows/a.ts": "// a", "/app/workflows/b.ts": "// b" },
+    { "workflows/a.ts": { greet }, "workflows/b.ts": { greet } },
+  );
+  const d = await deriveModels("/app", io, CODE_FIRST_MANIFEST);
+  assert.equal(d.incomplete, true);
+  assert.ok(d.errors.some((e) => /duplicate flow id "greet"/.test(e.message)));
+  assert.equal(d.ids.length, 1); // first wins
+});
+
+test("deriveModels flags two distinct flows sharing an id in the same module", async () => {
+  // two SEPARATE defineFlow objects, same id, same file — a real collision, not a re-export.
+  const greetA = defineFlow("greet", { hello: { in: GreetIn, out: GreetOut } }, (w) => {
+    w.run("hello", async () => ({ message: "a" }));
+  });
+  const greetB = defineFlow("greet", { hello: { in: GreetIn, out: GreetOut } }, (w) => {
+    w.run("hello", async () => ({ message: "b" }));
+  });
+  const io = memIO({ "/app/workflows/dup.ts": "// dup" }, { "workflows/dup.ts": { greetA, greetB } });
+  const d = await deriveModels("/app", io, CODE_FIRST_MANIFEST);
+  assert.equal(d.incomplete, true);
+  assert.ok(d.errors.some((e) => /duplicate flow id "greet" \(also defined in the same module\)/.test(e.message)));
+  assert.equal(d.ids.length, 1); // only the first is derived
+});
+
+test("deriveModels treats a genuine same-module re-export as one model, no error", async () => {
+  // the SAME flow object exported under two names in one file — harmless.
+  const io = memIO({ "/app/workflows/re.ts": "// re" }, { "workflows/re.ts": { greet, alsoGreet: greet } });
+  const d = await deriveModels("/app", io, CODE_FIRST_MANIFEST);
+  assert.equal(d.incomplete, false);
+  assert.deepEqual(d.errors, []);
+  assert.equal(d.ids.length, 1);
+});