@nanobpm/urban 0.17.1 → 0.19.0

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,
@@ -103,3 +115,6 @@ export type {
 } from "./scaffold/workers.ts";
 export { scaffoldWorkers } from "./scaffold.ts";
 export type { ScaffoldOptions, ScaffoldRun, StubOutcome, StubStatus } from "./scaffold.ts";
+
+export { addConnector } from "./addConnector.ts";
+export type { AddConnectorOptions, AddConnectorResult } from "./addConnector.ts";

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

package/src/toolkit/models.ts

@@ -0,0 +1,193 @@
+// Model derivation for code-first apps — the toolkit's one *executing* edge.
+//
+// Unlike the pure derivers (migrations, domain, worker I/O), which transform strings, this
+// imports the app's `workflows/*.ts`, turns each `defineFlow` into executable BPMN via
+// `@nanobpm/workflow` (`toBpmn` + `bpmn-auto-layout` DI), and writes `processes/<id>.bpmn`.
+// Executing the app's TypeScript needs a runtime module loader, so this is gated on the
+// optional `GenIO.importModule` (present on Node with type-stripping, and on Deno). When the
+// loader is absent — or the app authors its models directly (model-first) — derivation is a
+// no-op and the rest of `urban gen` proceeds on the authored/derived models unchanged.
+
+import { toDeployableBpmn } from "@nanobpm/workflow";
+import type { Workflow } from "@nanobpm/workflow";
+import type { DerivedArtifact } from "./artifact.ts";
+import type { GenIO } from "./gen.ts";
+import { expandPattern, joinPath } from "./gen.ts";
+import type { ModelSource } from "./derivers/worker-io.ts";
+
+/** Default source glob for code-first flows (matches the code-first scaffold layout). */
+export const DEFAULT_WORKFLOW_PATTERNS = ["workflows/*.ts"];
+
+/** Default output dir for derived models (matches the model-first scaffold, so a derived
+ * model is ejectable to model-first and picked up by `models.processes: ["processes/*.bpmn"]`). */
+export const PROCESSES_DIR = "processes";
+
+/** Marker stamped into every derived `.bpmn` (an XML comment) so re-gen overwrites and the
+ * stale sweep deletes ONLY derived output — never an authored, human-owned model. */
+export const MODEL_PROVENANCE =
+  "Generated by @nanobpm/urban from workflows/*.ts — do not edit; edit the flow and re-run `urban gen`.";
+
+/** Minimal shape a code-first manifest declares for model derivation. */
+export interface ModelsManifest {
+  models?: { processes?: string[]; workflows?: string[] };
+}
+
+/** A `defineFlow` export: has a string `id` and an `imperative`/`declarative` `kind`. */
+export function isWorkflow(v: unknown): v is Workflow {
+  if (!v || typeof v !== "object") return false;
+  const o = v as { id?: unknown; kind?: unknown };
+  return typeof o.id === "string" && (o.kind === "imperative" || o.kind === "declarative");
+}
+
+/** Sanitize a flow id into a safe `.bpmn` filename (mirrors the host generator). */
+export function bpmnFilename(id: string): string {
+  return `${id.replace(/[^A-Za-z0-9._-]/g, "-")}.bpmn`;
+}
+
+/** The directory derived models are written to: the dir of the first `models.processes`
+ * glob if the manifest declares one, else the `processes/` default. */
+export function processesOutDir(manifest: ModelsManifest): string {
+  for (const pat of manifest.models?.processes ?? []) {
+    const star = pat.indexOf("*");
+    const slash = star === -1 ? pat.lastIndexOf("/") : pat.lastIndexOf("/", star);
+    if (slash > 0) return pat.slice(0, slash);
+  }
+  return PROCESSES_DIR;
+}
+
+/** Insert the provenance marker as an XML comment right after the `<?xml … ?>` prolog. */
+function withProvenance(xml: string): string {
+  const comment = `<!-- ${MODEL_PROVENANCE} -->`;
+  const m = xml.match(/^\uFEFF?\s*<\?xml[^>]*\?>/);
+  if (m) return `${m[0]}\n${comment}\n${xml.slice(m[0].length).replace(/^\r?\n/, "")}`;
+  return `${comment}\n${xml}`;
+}
+
+export interface ModelError {
+  path: string;
+  message: string;
+}
+
+export interface DerivedModels {
+  /** `processes/<id>.bpmn` artifacts (path + provenance-stamped content). */
+  artifacts: DerivedArtifact[];
+  /** The same models, in-memory, for feeding the type-contract derivers (worker I/O, meta, messages). */
+  models: ModelSource[];
+  /** Derived flow ids (used for the provenance-scoped stale sweep). */
+  ids: string[];
+  /** Per-flow `{ id, kind, xml }` for the non-writing preview (`urban derive --stdout`). */
+  list: DerivedModelInfo[];
+  /** The output directory the artifacts were written into. */
+  outDir: string;
+  /** True once we attempted derivation (loader present AND at least one workflow file matched). */
+  attempted: boolean;
+  /** True if any workflow module failed to import/derive — suppresses the destructive sweep. */
+  incomplete: boolean;
+  /** Per-file derivation errors (empty on full success). */
+  errors: ModelError[];
+}
+
+export interface DerivedModelInfo {
+  id: string;
+  kind: Workflow["kind"];
+  xml: string;
+}
+
+function emptyDerived(outDir: string): DerivedModels {
+  return {
+    artifacts: [],
+    models: [],
+    ids: [],
+    list: [],
+    outDir,
+    attempted: false,
+    incomplete: false,
+    errors: [],
+  };
+}
+
+function messageOf(e: unknown): string {
+  return e instanceof Error ? e.message : String(e);
+}
+
+/** Append an actionable hint when a `.ts` import fails because the runtime can't strip types. */
+function importHint(rel: string, e: unknown): string {
+  const base = messageOf(e);
+  const code = (e as { code?: string })?.code ?? "";
+  const looksLikeNoTsLoader =
+    rel.endsWith(".ts") &&
+    (code === "ERR_UNKNOWN_FILE_EXTENSION" || /Unknown file extension "\.ts"/.test(base));
+  if (!looksLikeNoTsLoader) return base;
+  return (
+    `${base}\n    ↳ importing TypeScript workflows needs a runtime that strips types: ` +
+    "Node ≥22.18 (default) or `node --experimental-strip-types`, or run under Deno."
+  );
+}
+
+/**
+ * Derive executable BPMN models from an app's code-first `workflows/*.ts`.
+ *
+ * Returns everything in-memory (artifacts + `ModelSource`s + ids). The caller decides whether
+ * to write the `.bpmn` to disk (`urban gen` / `urban derive`) or keep them in memory to feed
+ * the type-contract derivers only (`urban gen --no-models`) or preview them (`urban derive
+ * --stdout`). Never throws on a bad workflow: a failing module is recorded in `errors`,
+ * `incomplete` is set, and the sweep is suppressed so a partial failure can't delete good models.
+ */
+export async function deriveModels(
+  root: string,
+  io: GenIO,
+  manifest: ModelsManifest,
+): Promise<DerivedModels> {
+  const outDir = processesOutDir(manifest);
+  const importModule = io.importModule;
+  if (!importModule) return emptyDerived(outDir);
+
+  const patterns = manifest.models?.workflows ?? DEFAULT_WORKFLOW_PATTERNS;
+  const files: string[] = [];
+  for (const pat of patterns) {
+    for (const rel of await expandPattern(root, io, pat)) files.push(rel);
+  }
+  if (files.length === 0) return emptyDerived(outDir);
+
+  const out: DerivedModels = { ...emptyDerived(outDir), attempted: true };
+  // id → { source file, workflow ref } — distinguishes a genuine re-export (same
+  // object under two export names) from a true collision (two distinct flows, one id).
+  const byId = new Map<string, { rel: string; ref: unknown }>();
+
+  for (const rel of files.sort()) {
+    let mod: Record<string, unknown>;
+    try {
+      mod = await importModule(joinPath(root, rel));
+    } catch (e) {
+      out.incomplete = true;
+      out.errors.push({ path: rel, message: importHint(rel, e) });
+      continue;
+    }
+    for (const value of Object.values(mod)) {
+      if (!isWorkflow(value)) continue;
+      const id = value.id;
+      const prior = byId.get(id);
+      if (prior) {
+        if (prior.ref === value && prior.rel === rel) continue; // genuine intra-module re-export
+        out.incomplete = true;
+        const where = prior.rel === rel ? "also defined in the same module" : `also defined in ${prior.rel}`;
+        out.errors.push({ path: rel, message: `duplicate flow id "${id}" (${where})` });
+        continue;
+      }
+      byId.set(id, { rel, ref: value });
+      try {
+        const semantic = await toDeployableBpmn(value);
+        const xml = withProvenance(semantic);
+        const path = `${outDir}/${bpmnFilename(id)}`;
+        out.artifacts.push({ path, content: xml });
+        out.models.push({ path, xml });
+        out.list.push({ id, kind: value.kind, xml });
+        out.ids.push(id);
+      } catch (e) {
+        out.incomplete = true;
+        out.errors.push({ path: rel, message: `deriving "${id}": ${messageOf(e)}` });
+      }
+    }
+  }
+  return out;
+}