@nanobpm/urban 0.17.0 → 0.18.0

package/dist/toolkit/derivers/meta.js

@@ -0,0 +1,106 @@
+// Deriver: BPMN models → `meta.ts`, the typed model-metadata accessor (`@nanobpm/meta`,
+// ADR 0040 §5). Scans each process for `nano:meta` key/value siblings of the `nano:shapes`
+// container and folds them into a single app-wide record. It emits the SAME `meta.ts` the
+// console generates (a faithful port of `foldMeta`/`emitMeta` in the server's domain_types.ts),
+// so the toolkit is a drop-in for the IDE's codegen (ADR 0053).
+import { GENERATED_DIR } from "../artifact.js";
+import { byModelPath } from "./worker-io.js";
+/** Basename the console uses for the generated accessor; kept identical (drop-in). */
+export const META_TS = "meta.ts";
+function attr(tag, name) {
+    const m = tag.match(new RegExp(`\\b${name}\\s*=\\s*"([^"]*)"`));
+    return m ? m[1] : undefined;
+}
+function processId(xml) {
+    const m = xml.match(/<[\w.-]*:?process\b[^>]*>/);
+    return m ? attr(m[0], "id") : undefined;
+}
+// A `nano:shape` carrier (`<...:shape>…</...:shape>`, and self-closing) — meta is only
+// recognised *outside* a shape carrier (its op children, e.g. `extend`, are a different
+// vocabulary), so strip carriers before matching `nano:meta` (mirrors envelope_scan.rs).
+const SHAPE_BLOCK_RE = /<([\w.-]*:)?shape\b[^>]*(?:\/>|>[\s\S]*?<\/\1?shape\s*>)/g;
+// A `nano:meta` element (any namespace prefix; matches the Rust local-name scan).
+const META_RE = /<([\w.-]*:)?meta\b([^>]*?)\/?>/g;
+/** Scan one BPMN document for model-level `nano:meta` key/value entries, in document
+ * order, tagged with the enclosing process. A meta with no `key` attribute is ignored;
+ * a missing `value` folds to the empty string (matches envelope_scan.rs). */
+export function scanModelMeta(xml) {
+    const proc = processId(xml);
+    const withoutShapes = xml.replace(SHAPE_BLOCK_RE, "");
+    const out = [];
+    let m;
+    while ((m = META_RE.exec(withoutShapes)) !== null) {
+        const key = attr(`<x ${m[2]}>`, "key");
+        if (key == null)
+            continue;
+        out.push({ process: proc, key, value: attr(`<x ${m[2]}>`, "value") ?? "" });
+    }
+    return out;
+}
+// --- Faithful port of the console's foldMeta/emitMeta (domain_types.ts) so the emitted
+//     meta.ts is byte-compatible with the IDE's own codegen. ---
+function isIdent(name) {
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name);
+}
+/** Fold the scanned model-level metadata into a single key→value record. When two models
+ * declare the same key the last (scan order) wins. Empty keys are ignored. The accumulator
+ * is a **null-prototype** dict so user-authored keys (including `__proto__`) round-trip
+ * deterministically as own data properties. */
+export function foldMeta(metas) {
+    const out = Object.create(null);
+    for (const m of metas) {
+        const key = (m?.key ?? "").trim();
+        if (!key)
+            continue;
+        out[key] = m.value ?? "";
+    }
+    return out;
+}
+/** Emit `meta.ts`: the typed model-metadata accessor (`@nanobpm/meta`, ADR 0040 §5).
+ * `AppMeta` keys the declared metadata as string-literal properties; `appMeta` is the
+ * concrete null-prototype record; the overloaded `meta()` returns the typed value for a
+ * known key and `string | undefined` for a dynamic one. Strip-safe (ADR 0036). */
+export function emitMeta(metas) {
+    const folded = foldMeta(metas);
+    const keys = Object.keys(folded);
+    const propKey = (k) => (isIdent(k) ? k : JSON.stringify(k));
+    const header = "// AUTO-GENERATED by nanobpmn from the process model (ADR 0040 §5): the typed\n" +
+        "// model-metadata accessor. Each `nano:meta` key/value the models declare becomes\n" +
+        "// a checked `AppMeta` property, so `meta(key)` is typed and app-wide queryable\n" +
+        "// without a second store. Do not edit — regenerated from the model.\n" +
+        "// eslint-disable\n\n";
+    const iface = keys.length > 0
+        ? `export interface AppMeta {\n${keys.map((k) => `  ${propKey(k)}: string;`).join("\n")}\n}\n`
+        : `export interface AppMeta {}\n`;
+    const constDecl = keys.length > 0
+        ? `export const appMeta: AppMeta = (() => {\n` +
+            `  const m: Record<string, string> = Object.create(null);\n` +
+            keys.map((k) => `  m[${JSON.stringify(k)}] = ${JSON.stringify(folded[k])};`).join("\n") +
+            `\n  return m as AppMeta;\n})();\n`
+        : `export const appMeta: AppMeta = Object.create(null) as AppMeta;\n`;
+    const accessor = `\n/** Read a model-level metadata value. A declared key is typed; a dynamic key\n` +
+        ` * returns \`string | undefined\`. */\n` +
+        `export function meta<K extends keyof AppMeta>(key: K): AppMeta[K];\n` +
+        `export function meta(key: string): string | undefined;\n` +
+        `export function meta(key: string): string | undefined {\n` +
+        `  return (appMeta as Record<string, string>)[key];\n` +
+        `}\n`;
+    return `${header}/** Every model-level metadata key the App's models declare (ADR 0040 §5). */\n` +
+        iface + "\n" + constDecl + accessor;
+}
+/**
+ * Derive `nano-generated/meta.ts` from BPMN models. Deterministic: models are scanned in
+ * path order, then their `nano:meta` entries folded (last write wins) into the accessor.
+ */
+export function deriveMeta(models) {
+    const metas = [];
+    for (const model of [...models].sort(byModelPath)) {
+        metas.push(...scanModelMeta(model.xml));
+    }
+    return [{ path: `${GENERATED_DIR}/${META_TS}`, content: emitMeta(metas) }];
+}
+export const metaDeriver = {
+    id: "model->meta",
+    describe: "Derive meta.ts (the typed @nanobpm/meta accessor) from BPMN nano:meta entries.",
+    derive: ({ models }) => deriveMeta(models),
+};

package/dist/toolkit/derivers/migrations.d.ts

@@ -2,6 +2,8 @@ import type { DerivedArtifact, Deriver } from "../artifact.ts";
 export interface ToolkitField {
     type?: string;
     optional?: boolean;
+    /** Marks a repeated field: the domain row-type projects it as `T[]` in the `DomainTypes` registry. */
+    list?: boolean;
 }
 export interface ToolkitType {
     table?: string;
@@ -20,7 +22,38 @@ export interface ToolkitManifest {
 /** Map a domain field type to a SQLite column type. Unknown types fall back to TEXT. */
 export declare function sqlType(t: string | undefined): string;
 export declare function assertSqlIdent(kind: string, name: string): string;
-/** Build the CREATE TABLE statement for one type. */
+/** Double-quote an identifier for DDL. `assertSqlIdent` already rejects non-identifier
+ * chars (the injection guard), but quoting is what makes valid-but-reserved words
+ * (`order`, `group`, `select`, …) legal SQL — no reserved-word denylist to maintain.
+ * Embedded double quotes are doubled per the SQL standard (defensive; can't occur here). */
+export declare function quoteSqlIdent(name: string): string;
+/** A column in a manifest type's canonical table schema. `sqlType` is the SQLite
+ * declared type (the affinity source for both the CREATE TABLE and the row types). */
+export interface DerivedColumn {
+    name: string;
+    sqlType: string;
+    notNull: boolean;
+    primaryKey: boolean;
+}
+/** The canonical table schema for one manifest type. */
+export interface DerivedTable {
+    table: string;
+    columns: DerivedColumn[];
+}
+/**
+ * Derive the canonical table schema for one manifest type: an implicit
+ * autoincrement `id` primary key plus one column per declared field. This is the
+ * single source of truth both the SQL migration (`createTableSql`) and the domain
+ * row-types (`domain.ts`) derive from, so the schema can never drift between them.
+ */
+export declare function tableSchemaForType(typeName: string, def: ToolkitType): DerivedTable;
+/** Group manifest types by their datasource, preserving declaration order within each
+ * source. Shared by the migrations and domain derivers so both partition and order
+ * sources identically (a single source of truth for the source spine). */
+export declare function groupTypesBySource(manifest: ToolkitManifest): Map<string, Array<[string, ToolkitType]>>;
+/** Build the CREATE TABLE statement for one type, from its canonical schema. Table and
+ * column identifiers are quoted so valid-but-reserved names (`order`, `group`, …) emit
+ * legal SQL. */
 export declare function createTableSql(typeName: string, def: ToolkitType): string;
 export declare function deriveMigrations(manifest: ToolkitManifest): DerivedArtifact[];
 export declare const migrationsDeriver: Deriver<ToolkitManifest>;

package/dist/toolkit/derivers/migrations.js

@@ -31,25 +31,40 @@ export function assertSqlIdent(kind, name) {
     }
     return name;
 }
-/** Build the CREATE TABLE statement for one type. */
-export function createTableSql(typeName, def) {
+/** Double-quote an identifier for DDL. `assertSqlIdent` already rejects non-identifier
+ * chars (the injection guard), but quoting is what makes valid-but-reserved words
+ * (`order`, `group`, `select`, …) legal SQL — no reserved-word denylist to maintain.
+ * Embedded double quotes are doubled per the SQL standard (defensive; can't occur here). */
+export function quoteSqlIdent(name) {
+    return `"${name.replace(/"/g, '""')}"`;
+}
+/**
+ * Derive the canonical table schema for one manifest type: an implicit
+ * autoincrement `id` primary key plus one column per declared field. This is the
+ * single source of truth both the SQL migration (`createTableSql`) and the domain
+ * row-types (`domain.ts`) derive from, so the schema can never drift between them.
+ */
+export function tableSchemaForType(typeName, def) {
     const table = assertSqlIdent("table name", def.table ?? typeName);
-    const cols = ["  id INTEGER PRIMARY KEY AUTOINCREMENT"];
+    const columns = [
+        { name: "id", sqlType: "INTEGER", notNull: false, primaryKey: true },
+    ];
     const fields = def.fields ?? {};
     for (const [name, f] of Object.entries(fields)) {
         assertSqlIdent("field name", name);
         if (name === "id") {
             throw new Error(`type "${typeName}": field "id" is reserved (the table's implicit primary key)`);
         }
-        const notNull = f.optional ? "" : " NOT NULL";
-        cols.push(`  ${name} ${sqlType(f.type)}${notNull}`);
+        columns.push({ name, sqlType: sqlType(f.type), notNull: !f.optional, primaryKey: false });
     }
-    return `CREATE TABLE IF NOT EXISTS ${table} (\n${cols.join(",\n")}\n);`;
+    return { table, columns };
 }
-export function deriveMigrations(manifest) {
+/** Group manifest types by their datasource, preserving declaration order within each
+ * source. Shared by the migrations and domain derivers so both partition and order
+ * sources identically (a single source of truth for the source spine). */
+export function groupTypesBySource(manifest) {
     const types = manifest.types ?? {};
     const defaultSource = manifest.data?.default ?? "app";
-    // Group types by their datasource.
     const bySource = new Map();
     for (const [name, def] of Object.entries(types)) {
         const src = def.source ?? defaultSource;
@@ -57,6 +72,20 @@ export function deriveMigrations(manifest) {
         list.push([name, def]);
         bySource.set(src, list);
     }
+    return bySource;
+}
+/** Build the CREATE TABLE statement for one type, from its canonical schema. Table and
+ * column identifiers are quoted so valid-but-reserved names (`order`, `group`, …) emit
+ * legal SQL. */
+export function createTableSql(typeName, def) {
+    const { table, columns } = tableSchemaForType(typeName, def);
+    const cols = columns.map((c) => c.primaryKey
+        ? `  ${quoteSqlIdent(c.name)} ${c.sqlType} PRIMARY KEY AUTOINCREMENT`
+        : `  ${quoteSqlIdent(c.name)} ${c.sqlType}${c.notNull ? " NOT NULL" : ""}`);
+    return `CREATE TABLE IF NOT EXISTS ${quoteSqlIdent(table)} (\n${cols.join(",\n")}\n);`;
+}
+export function deriveMigrations(manifest) {
+    const bySource = groupTypesBySource(manifest);
     const artifacts = [];
     for (const [src, list] of bySource) {
         const header = `-- Derived from manifest \`types\` by @nanobpm/urban (urban gen). Do not edit.\n` +

package/dist/toolkit/derivers/worker-io.d.ts

@@ -4,6 +4,16 @@ export interface ModelSource {
     path: string;
     xml: string;
 }
+/** Deterministic comparator for ordering `ModelSource` lists by path. Returns 0 on equal
+ * paths so it satisfies the JS sort contract (a comparator that reports both `a>b` and
+ * `b>a` can reorder equal elements unpredictably) — keeping the derivers' cross-model
+ * fold order stable even if a manifest pattern yields duplicate paths. Shared by every
+ * model-scanning deriver so there is one canonical ordering. */
+export declare function byModelPath(a: {
+    path: string;
+}, b: {
+    path: string;
+}): number;
 export interface WorkerIo {
     taskType: string;
     elementId?: string;
@@ -19,6 +29,10 @@ export declare const WORKER_BINDINGS_DTS = "worker-io.d.ts";
 export declare const DOMAIN_DTS = "domain-rows.d.ts";
 /** Scan one BPMN document for service-task worker I/O. */
 export declare function scanModelWorkers(xml: string): WorkerIo[];
+/** A `DomainTypes[...]` ref for a declared type id (else undefined). The one canonical
+ * ref helper shared by the worker- and message-IO emitters (matches the console's single
+ * `typeRefFor` in domain_types.ts), so both stay identical to the host codegen. */
+export declare function typeRefFor(id: string | undefined, declared: Set<string>): string | undefined;
 export interface WorkerBindingDecl {
     taskType?: string;
     inputType?: string;

package/dist/toolkit/derivers/worker-io.js

@@ -4,6 +4,14 @@
 // `worker-io.d.ts` the console generates (a faithful port of `emitWorkerBindings` in the
 // server's domain_types.ts), so the toolkit is a drop-in for the IDE's codegen (ADR 0053).
 import { GENERATED_DIR } from "../artifact.js";
+/** Deterministic comparator for ordering `ModelSource` lists by path. Returns 0 on equal
+ * paths so it satisfies the JS sort contract (a comparator that reports both `a>b` and
+ * `b>a` can reorder equal elements unpredictably) — keeping the derivers' cross-model
+ * fold order stable even if a manifest pattern yields duplicate paths. Shared by every
+ * model-scanning deriver so there is one canonical ordering. */
+export function byModelPath(a, b) {
+    return a.path < b.path ? -1 : a.path > b.path ? 1 : 0;
+}
 /** Filename the console uses; kept identical so the artifact is a drop-in. */
 export const WORKER_BINDINGS_DTS = "worker-io.d.ts";
 /** The domain type declarations `worker-io.d.ts` imports from (console: domain-rows.d.ts). */
@@ -51,7 +59,10 @@ export function scanModelWorkers(xml) {
 }
 // --- Faithful port of the console's emitWorkerBindings (domain_types.ts) so the emitted
 //     worker-io.d.ts is byte-compatible with the IDE's own codegen. ---
-function typeRefFor(id, declared) {
+/** A `DomainTypes[...]` ref for a declared type id (else undefined). The one canonical
+ * ref helper shared by the worker- and message-IO emitters (matches the console's single
+ * `typeRefFor` in domain_types.ts), so both stay identical to the host codegen. */
+export function typeRefFor(id, declared) {
     return id != null && declared.has(id) ? `DomainTypes[${JSON.stringify(id)}]` : undefined;
 }
 /** Emit `worker-io.d.ts` from worker bindings + the set of declared domain type ids. */
@@ -120,7 +131,7 @@ export function emitWorkerBindings(workers, declaredTypeIds) {
  */
 export function deriveWorkerBindings(models, declaredTypeIds = []) {
     const workers = [];
-    for (const model of [...models].sort((a, b) => (a.path < b.path ? -1 : 1))) {
+    for (const model of [...models].sort(byModelPath)) {
         for (const w of scanModelWorkers(model.xml)) {
             workers.push({ taskType: w.taskType, inputType: w.in, outputType: w.out });
         }

package/dist/toolkit/fsio.js

@@ -1,7 +1,16 @@
 // 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";
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
 export function createNodeGenIO() {
     return {
         async readText(path) {
@@ -31,5 +40,25 @@ export function createNodeGenIO() {
                 return false;
             }
         },
+        async remove(path) {
+            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) {
+            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(__rewriteRelativeImportExtension(href));
+        },
     };
 }

package/dist/toolkit/gen.d.ts

@@ -1,5 +1,6 @@
 import type { DerivedArtifact } from "./artifact.ts";
 import { type ModelSource } from "./derivers/worker-io.ts";
+import { type DerivedModels, type ModelError } from "./models.ts";
 /** Minimal filesystem port. Node/Deno impls live in `fsio.ts`. */
 export interface GenIO {
     readText(path: string): Promise<string>;
@@ -7,19 +8,43 @@ 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[];
 }
 declare function join(root: string, rel: string): string;
 declare function dirOf(p: string): string;
+/** Resolve a `dir/*.ext` (or literal) manifest pattern to file paths relative to root. */
+export declare function expandPattern(root: string, io: GenIO, pattern: string): Promise<string[]>;
 /** Read + resolve the app's process models from the manifest's `models.processes` patterns. */
 export declare function readModels(root: string, io: GenIO, manifest: {
     models?: {
@@ -33,3 +58,6 @@ export declare function runGen(opts: GenOptions & {
     check?: boolean;
 }): Promise<GenResult>;
 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 declare function previewModels(opts: GenOptions): Promise<DerivedModels>;

package/dist/toolkit/gen.js

@@ -4,7 +4,11 @@
 // pure; all IO is confined here behind a tiny FS port so the same code runs on Node and Deno.
 import { sortArtifacts } from "./artifact.js";
 import { deriveMigrations } from "./derivers/migrations.js";
+import { deriveDomain } from "./derivers/domain.js";
 import { deriveWorkerBindings } from "./derivers/worker-io.js";
+import { deriveMeta } from "./derivers/meta.js";
+import { deriveMessageBindings } from "./derivers/messages.js";
+import { deriveModels, MODEL_PROVENANCE } from "./models.js";
 function join(root, rel) {
     // Trim either separator so callers may pass Windows-style paths; GenIO
     // implementations accept forward slashes on all platforms.
@@ -15,7 +19,7 @@ function dirOf(p) {
     return i <= 0 ? "." : p.slice(0, i);
 }
 /** Resolve a `dir/*.ext` (or literal) manifest pattern to file paths relative to root. */
-async function expandPattern(root, io, pattern) {
+export async function expandPattern(root, io, pattern) {
     const star = pattern.indexOf("*");
     if (star === -1) {
         return (await io.exists(join(root, pattern))) ? [pattern] : [];
@@ -43,26 +47,47 @@ export async function readModels(root, io, manifest) {
 }
 /** Collect all artifacts a run would produce, without touching disk beyond reads. */
 export async function collectArtifacts(opts) {
+    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) {
     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));
     const artifacts = [];
-    // 1. types → migrations
-    if (manifest.types && Object.keys(manifest.types).length > 0) {
+    // 1. types → migrations + domain row types (DomainTables spine + DomainTypes registry)
+    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
-    const models = await readModels(root, io, manifest);
-    if (models.length > 0) {
-        const declaredTypeIds = Object.keys(manifest.types ?? {});
-        artifacts.push(...deriveWorkerBindings(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) {
-    const artifacts = await collectArtifacts(opts);
+    const { artifacts, derived } = await collectAll(opts);
     const { root, io } = opts;
+    const emitModels = opts.emitModels ?? true;
     const drift = [];
     for (const a of artifacts) {
         const abs = join(root, a.path);
@@ -75,6 +100,30 @@ export async function runGen(opts) {
             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) {
+    const { root, io } = opts;
+    const manifestPath = join(root, opts.manifestFile ?? "nano.app.json");
+    const manifest = JSON.parse(await io.readText(manifestPath));
+    return deriveModels(root, io, manifest);
+}

package/dist/toolkit/index.d.ts

@@ -1,16 +1,30 @@
 export type { DerivedArtifact, Deriver } from "./artifact.ts";
 export { GENERATED_DIR, sortArtifacts } from "./artifact.ts";
-export { deriveMigrations, migrationsDeriver, sqlType, createTableSql, } from "./derivers/migrations.ts";
-export type { ToolkitManifest, ToolkitType, ToolkitField } from "./derivers/migrations.ts";
+export { deriveMigrations, migrationsDeriver, sqlType, createTableSql, tableSchemaForType, groupTypesBySource, } from "./derivers/migrations.ts";
+export type { ToolkitManifest, ToolkitType, ToolkitField, DerivedColumn, DerivedTable, } from "./derivers/migrations.ts";
+export { deriveDomain, emitDomain, emitDomainModel, emitDomainDts, emitDomainDtsForSources, emitDomainTypeRegistry, domainDeriver, sourcesFromManifest, registryFromManifest, sqliteAffinityToTs, interfaceName, } from "./derivers/domain.ts";
+export type { SourceSchema, DomainFieldDef, DomainTypeDef, DomainTypeRegistry, } from "./derivers/domain.ts";
 export { deriveWorkerBindings, emitWorkerBindings, workerIoDeriver, scanModelWorkers, WORKER_BINDINGS_DTS, DOMAIN_DTS, } from "./derivers/worker-io.ts";
 export type { ModelSource, WorkerIo, WorkerBindingDecl } from "./derivers/worker-io.ts";
-export declare const DERIVERS: readonly [import("./artifact.ts").Deriver<import("./derivers/migrations.ts").ToolkitManifest>, import("./artifact.ts").Deriver<{
+export { byModelPath, typeRefFor } from "./derivers/worker-io.ts";
+export { deriveMeta, emitMeta, foldMeta, metaDeriver, scanModelMeta, META_TS, } from "./derivers/meta.ts";
+export type { MetaDecl } from "./derivers/meta.ts";
+export { deriveMessageBindings, emitMessageBindings, messagesDeriver, scanModelMessages, MESSAGE_BINDINGS_DTS, } from "./derivers/messages.ts";
+export type { MessageIo, MessageBindingDecl } from "./derivers/messages.ts";
+export declare const DERIVERS: readonly [import("./artifact.ts").Deriver<import("./derivers/migrations.ts").ToolkitManifest>, import("./artifact.ts").Deriver<import("./derivers/migrations.ts").ToolkitManifest>, import("./artifact.ts").Deriver<{
+    models: import("./derivers/worker-io.ts").ModelSource[];
+    declaredTypeIds: Iterable<string>;
+}>, import("./artifact.ts").Deriver<{
+    models: import("./derivers/worker-io.ts").ModelSource[];
+}>, import("./artifact.ts").Deriver<{
     models: import("./derivers/worker-io.ts").ModelSource[];
     declaredTypeIds: Iterable<string>;
 }>];
-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";
+export { deriveModels, isWorkflow, bpmnFilename, processesOutDir, DEFAULT_WORKFLOW_PATTERNS, PROCESSES_DIR, MODEL_PROVENANCE, } from "./models.ts";
+export type { DerivedModels, DerivedModelInfo, ModelError, ModelsManifest } from "./models.ts";
 export { planWorkerScaffold, renderWorkerStub, slugifyTaskType, } from "./scaffold/workers.ts";
 export type { ScaffoldWorker, SkippedWorker, SkipReason, StubManifestEntry, WorkerScaffoldPlan, WorkerStubPlan, } from "./scaffold/workers.ts";
 export { scaffoldWorkers } from "./scaffold.ts";

package/dist/toolkit/index.js

@@ -4,15 +4,24 @@
 // (ADR 0054) — the toolkit derives migrations and worker I/O from the model.
 export { GENERATED_DIR, sortArtifacts } from "./artifact.js";
 // Derivers
-export { deriveMigrations, migrationsDeriver, sqlType, createTableSql, } from "./derivers/migrations.js";
+export { deriveMigrations, migrationsDeriver, sqlType, createTableSql, tableSchemaForType, groupTypesBySource, } from "./derivers/migrations.js";
+export { deriveDomain, emitDomain, emitDomainModel, emitDomainDts, emitDomainDtsForSources, emitDomainTypeRegistry, domainDeriver, sourcesFromManifest, registryFromManifest, sqliteAffinityToTs, interfaceName, } from "./derivers/domain.js";
 export { deriveWorkerBindings, emitWorkerBindings, workerIoDeriver, scanModelWorkers, WORKER_BINDINGS_DTS, DOMAIN_DTS, } from "./derivers/worker-io.js";
+export { byModelPath, typeRefFor } from "./derivers/worker-io.js";
+export { deriveMeta, emitMeta, foldMeta, metaDeriver, scanModelMeta, META_TS, } from "./derivers/meta.js";
+export { deriveMessageBindings, emitMessageBindings, messagesDeriver, scanModelMessages, MESSAGE_BINDINGS_DTS, } from "./derivers/messages.js";
 // The registry of all derivers (for discovery / IDE migration).
 import { migrationsDeriver } from "./derivers/migrations.js";
+import { domainDeriver } from "./derivers/domain.js";
 import { workerIoDeriver } from "./derivers/worker-io.js";
-export const DERIVERS = [migrationsDeriver, workerIoDeriver];
+import { metaDeriver } from "./derivers/meta.js";
+import { messagesDeriver } from "./derivers/messages.js";
+export const DERIVERS = [migrationsDeriver, domainDeriver, workerIoDeriver, metaDeriver, messagesDeriver];
 // Gen orchestrator + IO
-export { collectArtifacts, runGen, joinPath, readModels } from "./gen.js";
+export { collectArtifacts, runGen, joinPath, readModels, expandPattern, previewModels } from "./gen.js";
 export { createNodeGenIO } from "./fsio.js";
+// Code-first model derivation (workflows/*.ts → BPMN)
+export { deriveModels, isWorkflow, bpmnFilename, processesOutDir, DEFAULT_WORKFLOW_PATTERNS, PROCESSES_DIR, MODEL_PROVENANCE, } from "./models.js";
 // Worker-stub scaffolder (ADR 0056): write-once handler stubs from the model.
 export { planWorkerScaffold, renderWorkerStub, slugifyTaskType, } from "./scaffold/workers.js";
 export { scaffoldWorkers } from "./scaffold.js";

package/dist/toolkit/models.d.ts

@@ -0,0 +1,63 @@
+import type { Workflow } from "@nanobpm/workflow";
+import type { DerivedArtifact } from "./artifact.ts";
+import type { GenIO } 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 declare const DEFAULT_WORKFLOW_PATTERNS: string[];
+/** 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 declare 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 declare const MODEL_PROVENANCE = "Generated by @nanobpm/urban from workflows/*.ts \u2014 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 declare function isWorkflow(v: unknown): v is Workflow;
+/** Sanitize a flow id into a safe `.bpmn` filename (mirrors the host generator). */
+export declare function bpmnFilename(id: string): string;
+/** 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 declare function processesOutDir(manifest: ModelsManifest): string;
+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;
+}
+/**
+ * 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 declare function deriveModels(root: string, io: GenIO, manifest: ModelsManifest): Promise<DerivedModels>;