@nanobpm/urban 0.17.0 → 0.18.0

package/dist/cli.js

@@ -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
@@ -11,7 +12,7 @@
 //               --port <n>, -h/--help, -v/--version.
 import { collectManifestIssues, installSignalHandlers, loadManifest, runDev, runFromEnv, selectHost, } from "./runtime/index.js";
 import { scaffold, slugify } from "create-urban-app";
-import { createNodeGenIO, runGen, scaffoldWorkers } from "./toolkit/index.js";
+import { createNodeGenIO, previewModels, runGen, scaffoldWorkers } from "./toolkit/index.js";
 import { pathToFileURL } from "node:url";
 import { readFileSync } from "node:fs";
 // Read the package version from package.json (one hop up from both src/cli.ts and the
@@ -27,7 +28,7 @@ function readVersion() {
 }
 const VERSION = readVersion();
 function parse(argv) {
-    const f = { root: ".", manifest: "nano.app.json", check: false, write: false, deno: false, help: false, version: false, _: [] };
+    const f = { root: ".", manifest: "nano.app.json", check: false, write: false, deno: false, models: true, stdout: false, help: false, version: false, _: [] };
     const need = (i, flag) => {
         const v = argv[i];
         if (v === undefined || v.startsWith("-"))
@@ -46,6 +47,12 @@ function parse(argv) {
             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") {
@@ -81,7 +88,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
@@ -113,7 +123,13 @@ async function cmdCheck(f) {
 }
 async function cmdGen(f) {
     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)`);
@@ -129,6 +145,52 @@ async function cmdGen(f) {
         console.log(`  • ${a.path}`);
     return 0;
 }
+async function cmdDerive(f) {
+    // `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) {
     const io = createNodeGenIO();
     const run = await scaffoldWorkers({ root: f.root, io, manifestFile: f.manifest, write: f.write });
@@ -232,6 +294,8 @@ export async function main(argv) {
             return cmdCheck(f);
         case "gen":
             return cmdGen(f);
+        case "derive":
+            return cmdDerive(f);
         case "stubs":
             return cmdStubs(f);
         case "run":

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

@@ -0,0 +1,69 @@
+import type { DerivedArtifact, Deriver } from "../artifact.ts";
+import type { ColumnMeta, TableMeta } from "../../runtime/core/modules/gateway.ts";
+import { type ToolkitManifest } from "./migrations.ts";
+export type { ColumnMeta, TableMeta };
+/** One datasource's tables, paired with its manifest alias. */
+export interface SourceSchema {
+    source: string;
+    tables: TableMeta[];
+}
+/**
+ * Map a SQLite declared column type to a TypeScript field type. SQLite is dynamically typed but
+ * assigns each column a *type affinity* from its declared name, so we apply the affinity rules
+ * (https://sqlite.org/datatype3.html §3.1) with two maker-friendly overrides: `BOOLEAN` →
+ * `boolean` and date/time types → `string` (ISO text), matching how Urban surfaces them.
+ */
+export declare function sqliteAffinityToTs(declaredType: string): string;
+/** PascalCase a table name into an interface name, sanitised to an identifier. */
+export declare function interfaceName(table: string): string;
+/**
+ * Emit the full `domain-rows.d.ts` from a datasource's tables: one `interface` per table plus a
+ * `DomainTables` lookup keyed by the *raw* table name, so callers write `DomainTables["customers"]`.
+ */
+export declare function emitDomainDts(tables: TableMeta[]): string;
+/**
+ * Emit `domain-rows.d.ts` for an App that declares *multiple* datasources: one `interface` per
+ * (source, table), a `DomainSources` map keyed by alias then wire table name, and a `DomainTables`
+ * alias to the default source. When there is one source (or none) this is byte-identical to
+ * `emitDomainDts` so the common case stays stable.
+ */
+export declare function emitDomainDtsForSources(sources: SourceSchema[], defaultSource?: string): string;
+/** One field of a declared domain type in the manifest `types` registry. */
+export interface DomainFieldDef {
+    /** A primitive keyword or the id of another registry type (nominal ref). */
+    type: string;
+    optional?: boolean;
+    list?: boolean;
+}
+/** A declared (transient) domain record type from the manifest `types` block. */
+export interface DomainTypeDef {
+    name?: string;
+    match?: string;
+    table?: string;
+    fields: Record<string, DomainFieldDef>;
+}
+/** The manifest `types` registry: type id → declared record type. */
+export type DomainTypeRegistry = Record<string, DomainTypeDef>;
+/**
+ * Emit the `DomainTypes` block for the manifest `types` registry: an inline map keyed by type id.
+ * Returns `""` when the registry is empty, so the table spine stays byte-identical when no types
+ * are declared. `optional` widens the key with `?`.
+ */
+export declare function emitDomainTypeRegistry(types: DomainTypeRegistry): string;
+/**
+ * Compose the full `domain-rows.d.ts`: the datasource table spine (every source, ADR 0029 §6)
+ * followed by the manifest `types` registry (§4.2).
+ */
+export declare function emitDomainModel(sources: SourceSchema[], defaultSource: string | undefined, types: DomainTypeRegistry): string;
+/** The datasource table spine derived from the manifest types, grouped by source (same grouping
+ * and order as the SQL migration). */
+export declare function sourcesFromManifest(manifest: ToolkitManifest): SourceSchema[];
+/** The `DomainTypes` registry derived from the manifest types (declared fields only — the
+ * persisted `id` belongs to the table row, not the logical type). */
+export declare function registryFromManifest(manifest: ToolkitManifest): DomainTypeRegistry;
+/** Emit the `domain-rows.d.ts` content for an app manifest. */
+export declare function emitDomain(manifest: ToolkitManifest): string;
+/** Derive `nano-generated/domain-rows.d.ts` from the manifest types. Empty when the app declares
+ * no types (no tables, no registry, and nothing references `DomainTypes`). */
+export declare function deriveDomain(manifest: ToolkitManifest): DerivedArtifact[];
+export declare const domainDeriver: Deriver<ToolkitManifest>;

package/dist/toolkit/derivers/domain.js

@@ -0,0 +1,243 @@
+// Deriver: manifest `types` → `domain-rows.d.ts`, the domain row-type contract (ADR 0029 §4.1/§6,
+// ADR 0053). Two blocks compose into one generated `.d.ts`:
+//   • the **table spine** — one `interface` per persisted table plus a `DomainTables` lookup
+//     keyed by wire name, so a worker types `DomainTables["greetings"]`; and
+//   • the **`DomainTypes` registry** — the declared (transient) manifest types keyed by id, so
+//     envelope/worker/message refs resolve to `DomainTypes["<id>"]` (see `typeRefFor`).
+//
+// Byte-faithful port of the console's `emitDomainModel`/`emitDomainDts…`/`emitDomainTypeRegistry`
+// (server `domain_types.ts`), so the toolkit is a drop-in for the IDE's codegen. The emitters are
+// pure; the table spine is derived from the manifest (code-first, ADR 0054) via the *same*
+// canonical `tableSchemaForType` the SQL migration uses — one schema truth, no drift surface.
+import { GENERATED_DIR } from "../artifact.js";
+import { DOMAIN_DTS } from "./worker-io.js";
+import { groupTypesBySource, tableSchemaForType, } from "./migrations.js";
+// --- table spine emitters (port of domain_types.ts) ------------------------------------------
+/**
+ * Map a SQLite declared column type to a TypeScript field type. SQLite is dynamically typed but
+ * assigns each column a *type affinity* from its declared name, so we apply the affinity rules
+ * (https://sqlite.org/datatype3.html §3.1) with two maker-friendly overrides: `BOOLEAN` →
+ * `boolean` and date/time types → `string` (ISO text), matching how Urban surfaces them.
+ */
+export function sqliteAffinityToTs(declaredType) {
+    const t = declaredType.toUpperCase();
+    if (t.length === 0)
+        return "unknown"; // NONE affinity — opaque
+    if (t.includes("BOOL"))
+        return "boolean";
+    if (t.includes("DATE") || t.includes("TIME"))
+        return "string";
+    if (t.includes("INT"))
+        return "number";
+    if (t.includes("CHAR") || t.includes("CLOB") || t.includes("TEXT"))
+        return "string";
+    if (t.includes("BLOB"))
+        return "Uint8Array";
+    if (t.includes("REAL") || t.includes("FLOA") || t.includes("DOUB"))
+        return "number";
+    return "number"; // NUMERIC affinity
+}
+/** A TS identifier is safe to use bare as a property name / type name. */
+function isIdent(name) {
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name);
+}
+/** PascalCase a table name into an interface name, sanitised to an identifier. */
+export function interfaceName(table) {
+    const pascal = table
+        .replace(/[^A-Za-z0-9]+/g, " ")
+        .trim()
+        .split(/\s+/)
+        .map((w) => (w ? w[0].toUpperCase() + w.slice(1) : ""))
+        .join("");
+    const safe = pascal.replace(/[^A-Za-z0-9_$]/g, "");
+    return /^[A-Za-z_$]/.test(safe) ? safe : `T_${safe}`;
+}
+/** The TS field type for a column: nullable columns widen with `| null`. */
+function fieldType(col) {
+    const base = sqliteAffinityToTs(col.type);
+    // A NOT NULL column (or the INTEGER PRIMARY KEY rowid alias) is never null.
+    return col.notNull || col.primaryKey ? base : `${base} | null`;
+}
+/** One `export interface` block for a table under an explicit interface name. */
+function tableInterfaceNamed(name, t) {
+    const fields = t.columns
+        .map((c) => {
+        const key = isIdent(c.name) ? c.name : JSON.stringify(c.name);
+        const pk = c.primaryKey ? " (primary key)" : "";
+        return `  /** ${c.type || "?"}${pk} */\n  ${key}: ${fieldType(c)};`;
+    })
+        .join("\n");
+    return `export interface ${name} {\n${fields}\n}`;
+}
+/** One `export interface` block for a table (name derived from the table). */
+function tableInterface(t) {
+    return tableInterfaceNamed(interfaceName(t.name), t);
+}
+/**
+ * Emit the full `domain-rows.d.ts` from a datasource's tables: one `interface` per table plus a
+ * `DomainTables` lookup keyed by the *raw* table name, so callers write `DomainTables["customers"]`.
+ */
+export function emitDomainDts(tables) {
+    const header = "// AUTO-GENERATED by nanobpmn from the datasource schema (ADR 0029 §4.1).\n" +
+        "// Do not edit — regenerated from the live tables. Erased at `deno compile`.\n" +
+        "// eslint-disable\n";
+    if (tables.length === 0) {
+        return `${header}\nexport interface DomainTables {}\n`;
+    }
+    const interfaces = tables.map(tableInterface).join("\n\n");
+    const map = tables
+        .map((t) => `  ${JSON.stringify(t.name)}: ${interfaceName(t.name)};`)
+        .join("\n");
+    return `${header}\n${interfaces}\n\n/** Every table keyed by its wire name — index it for a row type. */\nexport interface DomainTables {\n${map}\n}\n`;
+}
+/**
+ * The interface name for a table in a multi-source union: the source alias is PascalCased and
+ * prefixed to the table's interface name so tables that share a name across datasources get
+ * distinct, collision-free interfaces (`AppCustomers`, `AnalyticsCustomers`).
+ */
+function prefixedInterfaceName(source, table) {
+    return `${interfaceName(source)}${interfaceName(table)}`;
+}
+/**
+ * Emit `domain-rows.d.ts` for an App that declares *multiple* datasources: one `interface` per
+ * (source, table), a `DomainSources` map keyed by alias then wire table name, and a `DomainTables`
+ * alias to the default source. When there is one source (or none) this is byte-identical to
+ * `emitDomainDts` so the common case stays stable.
+ */
+export function emitDomainDtsForSources(sources, defaultSource) {
+    if (sources.length <= 1) {
+        return emitDomainDts(sources[0]?.tables ?? []);
+    }
+    const header = "// AUTO-GENERATED by nanobpmn from the datasource schemas (ADR 0029 §4.1/§6).\n" +
+        "// Do not edit — regenerated from the live tables. Erased at `deno compile`.\n" +
+        "// eslint-disable\n";
+    const interfaces = sources
+        .flatMap((s) => s.tables.map((t) => tableInterfaceNamed(prefixedInterfaceName(s.source, t.name), t)))
+        .join("\n\n");
+    const sourceMap = sources
+        .map((s) => {
+        if (s.tables.length === 0)
+            return `  ${JSON.stringify(s.source)}: {};`;
+        const tableMap = s.tables
+            .map((t) => `    ${JSON.stringify(t.name)}: ${prefixedInterfaceName(s.source, t.name)};`)
+            .join("\n");
+        return `  ${JSON.stringify(s.source)}: {\n${tableMap}\n  };`;
+    })
+        .join("\n");
+    const def = defaultSource && sources.some((s) => s.source === defaultSource)
+        ? defaultSource
+        : sources[0].source;
+    return `${header}\n${interfaces}\n\n` +
+        `/** Every datasource keyed by alias, then table by wire name. */\n` +
+        `export interface DomainSources {\n${sourceMap}\n}\n\n` +
+        `/** The default datasource's tables — index by wire name. */\n` +
+        `export type DomainTables = DomainSources[${JSON.stringify(def)}];\n`;
+}
+/** Manifest primitive field keywords → TS types (ADR 0029 §4.2 / schema). */
+const PRIMITIVE_TS = {
+    string: "string",
+    number: "number",
+    integer: "number",
+    boolean: "boolean",
+    date: "string",
+    datetime: "string",
+    json: "unknown",
+};
+/**
+ * The TS type for a registry field. A primitive keyword maps directly (and takes precedence over
+ * an identically named type, per the schema); anything else is a nominal reference to another
+ * registry type, emitted as an indexed access into `DomainTypes`. An unresolved reference degrades
+ * to `unknown`. `list` wraps the base type in `[]`.
+ */
+function fieldTsType(field, ids) {
+    const base = PRIMITIVE_TS[field.type] ??
+        (ids.has(field.type) ? `DomainTypes[${JSON.stringify(field.type)}]` : "unknown");
+    return field.list ? `${base}[]` : base;
+}
+/**
+ * Emit the `DomainTypes` block for the manifest `types` registry: an inline map keyed by type id.
+ * Returns `""` when the registry is empty, so the table spine stays byte-identical when no types
+ * are declared. `optional` widens the key with `?`.
+ */
+export function emitDomainTypeRegistry(types) {
+    const ids = new Set(Object.keys(types));
+    if (ids.size === 0)
+        return "";
+    const entries = Object.entries(types)
+        .map(([id, def]) => {
+        const fields = Object.entries(def.fields ?? {})
+            .map(([fname, field]) => {
+            const key = isIdent(fname) ? fname : JSON.stringify(fname);
+            const opt = field.optional ? "?" : "";
+            return `    ${key}${opt}: ${fieldTsType(field, ids)};`;
+        })
+            .join("\n");
+        const body = fields.length > 0 ? `{\n${fields}\n  }` : "{}";
+        return `  ${JSON.stringify(id)}: ${body};`;
+    })
+        .join("\n");
+    return `/** Declared (transient) domain types from the manifest \`types\` registry (ADR 0029 §4.2), keyed by id. */\nexport interface DomainTypes {\n${entries}\n}\n`;
+}
+/**
+ * Compose the full `domain-rows.d.ts`: the datasource table spine (every source, ADR 0029 §6)
+ * followed by the manifest `types` registry (§4.2).
+ */
+export function emitDomainModel(sources, defaultSource, types) {
+    const spine = emitDomainDtsForSources(sources, defaultSource);
+    const registry = emitDomainTypeRegistry(types);
+    return registry ? `${spine}\n${registry}` : spine;
+}
+// --- manifest bridge (code-first, ADR 0054) --------------------------------------------------
+/** Project one manifest type's canonical schema into a `TableMeta` for the row-type spine. Reuses
+ * the *same* `tableSchemaForType` the SQL migration uses, so the row types can't drift from the DB. */
+function tableMetaFromType(typeName, def) {
+    const { table, columns } = tableSchemaForType(typeName, def);
+    return {
+        name: table,
+        columns: columns.map((c) => ({
+            name: c.name,
+            type: c.sqlType,
+            notNull: c.notNull,
+            primaryKey: c.primaryKey,
+        })),
+        indexes: [],
+        foreignKeys: [],
+    };
+}
+/** The datasource table spine derived from the manifest types, grouped by source (same grouping
+ * and order as the SQL migration). */
+export function sourcesFromManifest(manifest) {
+    return [...groupTypesBySource(manifest)].map(([source, list]) => ({
+        source,
+        tables: list.map(([name, def]) => tableMetaFromType(name, def)),
+    }));
+}
+/** The `DomainTypes` registry derived from the manifest types (declared fields only — the
+ * persisted `id` belongs to the table row, not the logical type). */
+export function registryFromManifest(manifest) {
+    const out = {};
+    for (const [id, def] of Object.entries(manifest.types ?? {})) {
+        const fields = {};
+        for (const [fname, f] of Object.entries(def.fields ?? {})) {
+            fields[fname] = { type: f.type ?? "string", optional: f.optional, list: f.list };
+        }
+        out[id] = { table: def.table, fields };
+    }
+    return out;
+}
+/** Emit the `domain-rows.d.ts` content for an app manifest. */
+export function emitDomain(manifest) {
+    return emitDomainModel(sourcesFromManifest(manifest), manifest.data?.default ?? "app", registryFromManifest(manifest));
+}
+/** Derive `nano-generated/domain-rows.d.ts` from the manifest types. Empty when the app declares
+ * no types (no tables, no registry, and nothing references `DomainTypes`). */
+export function deriveDomain(manifest) {
+    if (!manifest.types || Object.keys(manifest.types).length === 0)
+        return [];
+    return [{ path: `${GENERATED_DIR}/${DOMAIN_DTS}`, content: emitDomain(manifest) }];
+}
+export const domainDeriver = {
+    id: "types->domain",
+    describe: "Derive domain row types (DomainTables spine + DomainTypes registry) from manifest types.",
+    derive: deriveDomain,
+};

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

@@ -0,0 +1,36 @@
+import type { DerivedArtifact, Deriver } from "../artifact.ts";
+import { type ModelSource } from "./worker-io.ts";
+/** Filename the console uses for the derived message-payload map; kept identical (drop-in). */
+export declare const MESSAGE_BINDINGS_DTS = "message-io.d.ts";
+/** One message-IO entry scanned from a model: a `bpmn:message` name plus the envelope
+ * type refs it carries. `inputType` is the received payload (what a `publishMessage`
+ * caller sends); `outputType` is reserved. Mirrors the Rust `MessageIo`. */
+export interface MessageIo {
+    messageName: string;
+    inputType?: string;
+    outputType?: string;
+}
+/** The binding shape the emitter reads. Identical to a scanned `MessageIo`, so it is an
+ * alias — one canonical shape, no second declaration to drift (the console keeps the two
+ * apart only because its scan output is Rust and its emitter input is TS). */
+export type MessageBindingDecl = MessageIo;
+/** Scan one BPMN document for `bpmn:message` envelopes. Handles both a self-closing
+ * `<bpmn:message name=.. />` (name only — completes the `MessageName` union) and an open
+ * message whose body carries the `io.nanobpm.dataEnvelope.in/out` `zeebe:property`. */
+export declare function scanModelMessages(xml: string): MessageIo[];
+/** Emit `message-io.d.ts` from message bindings + the set of declared domain type ids.
+ * Each named message joins the `MessageName` union; a message whose envelope names a
+ * declared type also maps to it in `MessagePayloads` (else falls back to `MessageVars`). */
+export declare function emitMessageBindings(messages: MessageBindingDecl[], declaredTypeIds: Iterable<string>): string;
+/**
+ * Derive `nano-generated/message-io.d.ts` from BPMN models. Messages are aggregated the way
+ * the console's Rust scan does (a `BTreeMap` keyed by name): deduped by name, sorted by name,
+ * with the envelope type refs merged first-wins across models — so the derived output matches
+ * the host's `derivedMessages` for the same models. `declaredTypeIds` is the manifest `types`
+ * key set; a message only gets a typed payload when its envelope names a declared type.
+ */
+export declare function deriveMessageBindings(models: ModelSource[], declaredTypeIds?: Iterable<string>): DerivedArtifact[];
+export declare const messagesDeriver: Deriver<{
+    models: ModelSource[];
+    declaredTypeIds: Iterable<string>;
+}>;

package/dist/toolkit/derivers/messages.js

@@ -0,0 +1,134 @@
+// Deriver: BPMN models → `message-io.d.ts`, the message-payload type map (ADR 0040 slice 2).
+// Scans each process for `bpmn:message` envelopes and maps each message name to its declared
+// payload type. It emits the SAME `message-io.d.ts` the console generates (a faithful port of
+// `emitMessageBindings` in the server's domain_types.ts), so the toolkit is a drop-in for the
+// IDE's codegen (ADR 0053). The static typed-`publishMessage` wrapper (`messages.ts`) never
+// changes with the model, so — like the worker SDK — it is a package/runtime concern, not a
+// derived artifact; only the model-derived `message-io.d.ts` is emitted here.
+import { GENERATED_DIR } from "../artifact.js";
+import { byModelPath, DOMAIN_DTS, typeRefFor } from "./worker-io.js";
+/** Filename the console uses for the derived message-payload map; kept identical (drop-in). */
+export const MESSAGE_BINDINGS_DTS = "message-io.d.ts";
+const ENVELOPE_IN = "io.nanobpm.dataEnvelope.in";
+const ENVELOPE_OUT = "io.nanobpm.dataEnvelope.out";
+function attr(tag, name) {
+    const m = tag.match(new RegExp(`\\b${name}\\s*=\\s*"([^"]*)"`));
+    return m ? m[1] : undefined;
+}
+/** An envelope ref is trimmed; an empty/whitespace value contributes nothing (mirrors the
+ * Rust `envelope_ref`). A message name, by contrast, is a correlation identity matched
+ * verbatim by the engine, so it is NOT trimmed — only an absent/empty name is dropped. */
+function envelopeRef(value) {
+    const v = value?.trim();
+    return v ? v : undefined;
+}
+/** Scan one BPMN document for `bpmn:message` envelopes. Handles both a self-closing
+ * `<bpmn:message name=.. />` (name only — completes the `MessageName` union) and an open
+ * message whose body carries the `io.nanobpm.dataEnvelope.in/out` `zeebe:property`. */
+export function scanModelMessages(xml) {
+    const out = [];
+    const blockRe = /<bpmn:message\b([^>]*?)(?:\/>|>([\s\S]*?)<\/bpmn:message>)/g;
+    let m;
+    while ((m = blockRe.exec(xml)) !== null) {
+        const name = attr(`<x ${m[1]}>`, "name");
+        if (name == null || name.length === 0)
+            continue;
+        const io = { messageName: name };
+        const body = m[2] ?? "";
+        const propRe = /<zeebe:property\b[^>]*>/g;
+        let p;
+        while ((p = propRe.exec(body)) !== null) {
+            const pname = attr(p[0], "name");
+            if (pname === ENVELOPE_IN)
+                io.inputType = envelopeRef(attr(p[0], "value"));
+            else if (pname === ENVELOPE_OUT)
+                io.outputType = envelopeRef(attr(p[0], "value"));
+        }
+        out.push(io);
+    }
+    return out;
+}
+// --- Faithful port of the console's emitMessageBindings (domain_types.ts) so the emitted
+//     message-io.d.ts is byte-compatible with the IDE's own codegen. ---
+/** Emit `message-io.d.ts` from message bindings + the set of declared domain type ids.
+ * Each named message joins the `MessageName` union; a message whose envelope names a
+ * declared type also maps to it in `MessagePayloads` (else falls back to `MessageVars`). */
+export function emitMessageBindings(messages, declaredTypeIds) {
+    const declared = new Set(declaredTypeIds);
+    const propKey = (m) => JSON.stringify(m);
+    const names = [
+        ...new Set(messages
+            .map((m) => m?.messageName)
+            .filter((n) => typeof n === "string" && n.length > 0)),
+    ];
+    const nameUnion = names.length > 0
+        ? names.map((n) => JSON.stringify(n)).join(" | ")
+        : "string";
+    const payloads = [];
+    for (const m of messages) {
+        if (typeof m?.messageName !== "string" || m.messageName.length === 0)
+            continue;
+        const ref = typeRefFor(m.inputType, declared);
+        if (ref)
+            payloads.push(`  ${propKey(m.messageName)}: ${ref};`);
+    }
+    const header = "// AUTO-GENERATED by nanobpmn from the process model (ADR 0040 slice 2).\n" +
+        "// The bridge from a `bpmn:message`'s data envelope to the message type system:\n" +
+        "// each named message maps to the TS type of its payload, so the typed\n" +
+        "// `publishMessage` types a call by its message name. Do not edit — regenerated\n" +
+        "// from the model. Erased to plain JS at compile.\n" +
+        "// eslint-disable\n";
+    const needsRegistry = payloads.length > 0;
+    const importTypes = needsRegistry
+        ? `import type { DomainTypes } from "./${DOMAIN_DTS}";\n`
+        : "";
+    const payloadsIface = payloads.length > 0
+        ? `export interface MessagePayloads {\n${payloads.join("\n")}\n}\n`
+        : `export interface MessagePayloads {}\n`;
+    return `${header}\n` +
+        importTypes +
+        `\n/** Untyped fallback payload for a message that declares no envelope type. */\n` +
+        `export type MessageVars = Record<string, unknown>;\n\n` +
+        `/** Every declared message \`name\` (ADR 0040 slice 2): the model-derived set the\n` +
+        ` * typed \`publishMessage\` accepts, so \`name\` autocompletes and rejects unknown messages. */\n` +
+        `export type MessageName = ${nameUnion};\n\n` +
+        `/** Payload (\`variables\`) per declared message, keyed by \`name\`. */\n` +
+        payloadsIface;
+}
+/**
+ * Derive `nano-generated/message-io.d.ts` from BPMN models. Messages are aggregated the way
+ * the console's Rust scan does (a `BTreeMap` keyed by name): deduped by name, sorted by name,
+ * with the envelope type refs merged first-wins across models — so the derived output matches
+ * the host's `derivedMessages` for the same models. `declaredTypeIds` is the manifest `types`
+ * key set; a message only gets a typed payload when its envelope names a declared type.
+ */
+export function deriveMessageBindings(models, declaredTypeIds = []) {
+    const byName = new Map();
+    for (const model of [...models].sort(byModelPath)) {
+        for (const msg of scanModelMessages(model.xml)) {
+            const existing = byName.get(msg.messageName);
+            if (!existing) {
+                byName.set(msg.messageName, {
+                    messageName: msg.messageName,
+                    inputType: msg.inputType,
+                    outputType: msg.outputType,
+                });
+            }
+            else {
+                // First-wins merge of the envelope refs (mirrors the Rust `fill`).
+                if (existing.inputType == null)
+                    existing.inputType = msg.inputType;
+                if (existing.outputType == null)
+                    existing.outputType = msg.outputType;
+            }
+        }
+    }
+    const messages = [...byName.values()].sort((a, b) => a.messageName < b.messageName ? -1 : a.messageName > b.messageName ? 1 : 0);
+    const content = emitMessageBindings(messages, declaredTypeIds);
+    return [{ path: `${GENERATED_DIR}/${MESSAGE_BINDINGS_DTS}`, content }];
+}
+export const messagesDeriver = {
+    id: "model->message-io",
+    describe: "Derive message-io.d.ts (bpmn:message name + envelope payload) from BPMN models.",
+    derive: ({ models, declaredTypeIds }) => deriveMessageBindings(models, declaredTypeIds),
+};

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

@@ -0,0 +1,34 @@
+import type { DerivedArtifact, Deriver } from "../artifact.ts";
+import { type ModelSource } from "./worker-io.ts";
+/** Basename the console uses for the generated accessor; kept identical (drop-in). */
+export declare const META_TS = "meta.ts";
+/** One model-level metadata entry (`nano:meta`), tagged with its defining process for
+ * the `model:<processId>` provenance (ADR 0040 §5). `process` is carried for the fuse;
+ * the emitted `meta.ts` folds on key/value only. */
+export interface MetaDecl {
+    process?: string;
+    key: string;
+    value: string;
+}
+/** 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 declare function scanModelMeta(xml: string): MetaDecl[];
+/** 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 declare function foldMeta(metas: MetaDecl[]): Record<string, string>;
+/** 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 declare function emitMeta(metas: MetaDecl[]): string;
+/**
+ * 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 declare function deriveMeta(models: ModelSource[]): DerivedArtifact[];
+export declare const metaDeriver: Deriver<{
+    models: ModelSource[];
+}>;