@nanobpm/urban 0.17.0 → 0.17.1

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[];
+}>;

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