@nanobpm/urban 0.17.0 → 0.18.0

package/src/toolkit/derivers/domain.ts

@@ -0,0 +1,317 @@
+// 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 type { DerivedArtifact, Deriver } from "../artifact.ts";
+import { GENERATED_DIR } from "../artifact.ts";
+import { DOMAIN_DTS } from "./worker-io.ts";
+import type { ColumnMeta, TableMeta } from "../../runtime/core/modules/gateway.ts";
+import {
+  groupTypesBySource,
+  tableSchemaForType,
+  type ToolkitManifest,
+  type ToolkitType,
+} from "./migrations.ts";
+
+// The introspected-schema types (`ColumnMeta`/`TableMeta`) are the runtime gateway's canonical
+// definitions — the single source of truth the driver introspection, the page runtime, and this
+// domain projection all share (no parallel schema shape). Re-exported for convenience.
+export type { ColumnMeta, TableMeta };
+
+/** One datasource's tables, paired with its manifest alias. */
+export interface SourceSchema {
+  source: string;
+  tables: TableMeta[];
+}
+
+// --- 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: string): string {
+  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: string): boolean {
+  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: string): string {
+  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: ColumnMeta): string {
+  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: string, t: TableMeta): string {
+  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: TableMeta): string {
+  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: TableMeta[]): string {
+  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: string, table: string): string {
+  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: SourceSchema[],
+  defaultSource?: string,
+): string {
+  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 `types` registry (ADR 0029 §4.2) -----------------------------------------------
+
+/** 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>;
+
+/** Manifest primitive field keywords → TS types (ADR 0029 §4.2 / schema). */
+const PRIMITIVE_TS: Record<string, string> = {
+  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: DomainFieldDef, ids: Set<string>): string {
+  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: DomainTypeRegistry): string {
+  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: SourceSchema[],
+  defaultSource: string | undefined,
+  types: DomainTypeRegistry,
+): string {
+  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: string, def: ToolkitType): TableMeta {
+  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: ToolkitManifest): SourceSchema[] {
+  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: ToolkitManifest): DomainTypeRegistry {
+  const out: DomainTypeRegistry = {};
+  for (const [id, def] of Object.entries(manifest.types ?? {})) {
+    const fields: Record<string, DomainFieldDef> = {};
+    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: ToolkitManifest): string {
+  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: ToolkitManifest): DerivedArtifact[] {
+  if (!manifest.types || Object.keys(manifest.types).length === 0) return [];
+  return [{ path: `${GENERATED_DIR}/${DOMAIN_DTS}`, content: emitDomain(manifest) }];
+}
+
+export const domainDeriver: Deriver<ToolkitManifest> = {
+  id: "types->domain",
+  describe: "Derive domain row types (DomainTables spine + DomainTypes registry) from manifest types.",
+  derive: deriveDomain,
+};

package/src/toolkit/derivers/messages.test.ts

@@ -0,0 +1,174 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  deriveMessageBindings,
+  emitMessageBindings,
+  scanModelMessages,
+  type MessageIo,
+} from "./messages.ts";
+
+// Goldens captured byte-for-byte from the console's canonical `emitMessageBindings`
+// (server/src/console/domain_types.ts) so this port is provably a drop-in (ADR 0053).
+const GOLD_EMPTY =
+  "// 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" +
+  "\n" +
+  "\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 = string;\n" +
+  "\n" +
+  "/** Payload (`variables`) per declared message, keyed by `name`. */\n" +
+  "export interface MessagePayloads {}\n";
+
+const GOLD_NAMESONLY =
+  "// 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" +
+  "\n" +
+  "\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 = \"OrderPlaced\" | \"OrderShipped\";\n" +
+  "\n" +
+  "/** Payload (`variables`) per declared message, keyed by `name`. */\n" +
+  "export interface MessagePayloads {}\n";
+
+const GOLD_TYPED =
+  "// 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" +
+  "\n" +
+  "import type { DomainTypes } from \"./domain-rows.d.ts\";\n" +
+  "\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 = \"OrderPlaced\";\n" +
+  "\n" +
+  "/** Payload (`variables`) per declared message, keyed by `name`. */\n" +
+  "export interface MessagePayloads {\n" +
+  "  \"OrderPlaced\": DomainTypes[\"Order\"];\n" +
+  "}\n";
+
+const GOLD_MIXED =
+  "// 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" +
+  "\n" +
+  "import type { DomainTypes } from \"./domain-rows.d.ts\";\n" +
+  "\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 = \"OrderPlaced\" | \"Ping\";\n" +
+  "\n" +
+  "/** Payload (`variables`) per declared message, keyed by `name`. */\n" +
+  "export interface MessagePayloads {\n" +
+  "  \"OrderPlaced\": DomainTypes[\"Order\"];\n" +
+  "}\n";
+
+test("emitMessageBindings: no messages → string union + empty payloads (matches console)", () => {
+  assert.equal(emitMessageBindings([], []), GOLD_EMPTY);
+});
+
+test("emitMessageBindings: names-only → finite union, no import (matches console)", () => {
+  const out = emitMessageBindings(
+    [{ messageName: "OrderPlaced" }, { messageName: "OrderShipped" }],
+    [],
+  );
+  assert.equal(out, GOLD_NAMESONLY);
+});
+
+test("emitMessageBindings: a declared envelope maps to DomainTypes (matches console)", () => {
+  const out = emitMessageBindings([{ messageName: "OrderPlaced", inputType: "Order" }], ["Order"]);
+  assert.equal(out, GOLD_TYPED);
+});
+
+test("emitMessageBindings: an undeclared envelope type is omitted from payloads (matches console)", () => {
+  const out = emitMessageBindings(
+    [
+      { messageName: "OrderPlaced", inputType: "Order" },
+      { messageName: "Ping", inputType: "NotDeclared" },
+    ],
+    ["Order", "Receipt"],
+  );
+  assert.equal(out, GOLD_MIXED);
+});
+
+const XML = `<?xml version="1.0"?>
+<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL"
+                  xmlns:zeebe="http://camunda.org/schema/zeebe/1.0">
+  <bpmn:message id="M1" name="OrderPlaced">
+    <bpmn:extensionElements>
+      <zeebe:properties>
+        <zeebe:property name="io.nanobpm.dataEnvelope.in" value="Order" />
+      </zeebe:properties>
+    </bpmn:extensionElements>
+  </bpmn:message>
+  <bpmn:message id="M2" name="Ping" />
+</bpmn:definitions>`;
+
+test("scanModelMessages extracts message name + envelope; a self-closing message is name-only", () => {
+  const m = scanModelMessages(XML);
+  const placed = m.find((x) => x.messageName === "OrderPlaced") as MessageIo;
+  assert.ok(placed);
+  assert.equal(placed.inputType, "Order");
+  const ping = m.find((x) => x.messageName === "Ping") as MessageIo;
+  assert.ok(ping);
+  assert.equal(ping.inputType, undefined);
+});
+
+test("scanModelMessages drops a message with an empty/absent name", () => {
+  assert.deepEqual(scanModelMessages(`<bpmn:message name="" />`), []);
+  assert.deepEqual(scanModelMessages(`<bpmn:message id="x" />`), []);
+});
+
+test("deriveMessageBindings is deterministic and emits message-io.d.ts", () => {
+  const models = [{ path: "processes/orders.bpmn", xml: XML }];
+  const a1 = deriveMessageBindings(models, ["Order"]);
+  const a2 = deriveMessageBindings(models, ["Order"]);
+  assert.deepEqual(a1, a2);
+  assert.equal(a1[0].path, "nano-generated/message-io.d.ts");
+  assert.match(a1[0].content, /"OrderPlaced": DomainTypes\["Order"\]/);
+});
+
+test("deriveMessageBindings sorts by name and merges envelopes first-wins across models", () => {
+  // Same message declared in two models: the first (path order) carries the envelope,
+  // the later re-declaration (no envelope) must not clear it (mirrors the Rust fill).
+  const a = `<bpmn:message name="Zebra" />`;
+  const b1 = `<bpmn:message name="Alpha"><zeebe:property name="io.nanobpm.dataEnvelope.in" value="Order" /></bpmn:message>`;
+  const b2 = `<bpmn:message name="Alpha" />`;
+  const models = [
+    { path: "processes/2-second.bpmn", xml: b2 },
+    { path: "processes/1-first.bpmn", xml: b1 + a },
+  ];
+  const content = deriveMessageBindings(models, ["Order"])[0].content;
+  // Sorted by name: Alpha before Zebra.
+  assert.match(content, /export type MessageName = "Alpha" \| "Zebra";/);
+  // First-wins: Alpha keeps its Order envelope despite the later name-only re-declaration.
+  assert.match(content, /"Alpha": DomainTypes\["Order"\]/);
+});

package/src/toolkit/derivers/messages.ts

@@ -0,0 +1,166 @@
+// 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 type { DerivedArtifact, Deriver } from "../artifact.ts";
+import { GENERATED_DIR } from "../artifact.ts";
+import { byModelPath, DOMAIN_DTS, typeRefFor, type ModelSource } from "./worker-io.ts";
+
+/** 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";
+
+/** 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;
+
+function attr(tag: string, name: string): string | undefined {
+  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: string | undefined): string | undefined {
+  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: string): MessageIo[] {
+  const out: MessageIo[] = [];
+  const blockRe = /<bpmn:message\b([^>]*?)(?:\/>|>([\s\S]*?)<\/bpmn:message>)/g;
+  let m: RegExpExecArray | null;
+  while ((m = blockRe.exec(xml)) !== null) {
+    const name = attr(`<x ${m[1]}>`, "name");
+    if (name == null || name.length === 0) continue;
+    const io: MessageIo = { messageName: name };
+    const body = m[2] ?? "";
+    const propRe = /<zeebe:property\b[^>]*>/g;
+    let p: RegExpExecArray | null;
+    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: MessageBindingDecl[],
+  declaredTypeIds: Iterable<string>,
+): string {
+  const declared = new Set(declaredTypeIds);
+  const propKey = (m: string) => JSON.stringify(m);
+  const names = [
+    ...new Set(
+      messages
+        .map((m) => m?.messageName)
+        .filter((n): n is string => typeof n === "string" && n.length > 0),
+    ),
+  ];
+  const nameUnion = names.length > 0
+    ? names.map((n) => JSON.stringify(n)).join(" | ")
+    : "string";
+  const payloads: string[] = [];
+  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: ModelSource[],
+  declaredTypeIds: Iterable<string> = [],
+): DerivedArtifact[] {
+  const byName = new Map<string, MessageBindingDecl>();
+  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: Deriver<{ models: ModelSource[]; declaredTypeIds: Iterable<string> }> = {
+  id: "model->message-io",
+  describe: "Derive message-io.d.ts (bpmn:message name + envelope payload) from BPMN models.",
+  derive: ({ models, declaredTypeIds }) => deriveMessageBindings(models, declaredTypeIds),
+};