@nanobpm/urban 0.47.0 → 0.48.0

package/dist/runtime/core/modules/pages.js

@@ -786,6 +786,27 @@ function el(tag, attrs = {}, ...kids) {
 function interpParam(s) {
   return typeof s === "string" ? s.replace(/\{\{param\}\}/g, () => PARAM) : s;
 }
+
+// Interpolate {{field}} tokens in a column's per-cell template with values from
+// the row, coercing each to a string (null/undefined → ""). Like interpParam the
+// result is only ever set as DOM text (textContent via el()), so a substituted
+// row value cannot inject markup or attributes. A function replacement inserts
+// each value literally, so a "$"-bearing value can't be reinterpreted as a
+// replacement pattern. Unknown tokens (no such field) render empty rather than
+// throwing, matching interpParam. This is a dumb text formatter: no expressions,
+// arithmetic, or conditionals — just field splicing. Only the row's own
+// fields resolve (own-property gate, enumerable or not): an inherited
+// Object.prototype key (toString, constructor, …) counts as unknown and
+// renders "", so a token can't pick up prototype cruft instead of blank.
+function interpTemplate(tpl, row) {
+  return typeof tpl === "string"
+    ? tpl.replace(/\{\{([^{}]+)\}\}/g, (_m, name) => {
+        const key = name.trim();
+        const v = Object.prototype.hasOwnProperty.call(row, key) ? row[key] : null;
+        return v == null ? "" : String(v);
+      })
+    : tpl;
+}
 function renderText(node) {
   const v = node.props.variant;
   const cls = v === "heading" ? "pc-heading" : v === "sub" ? "pc-sub" : "pc-body";
@@ -950,8 +971,27 @@ function renderButton(node) {
 // host's own explorer view in place via the nano-navigate postMessage bridge
 // (a modified/middle click keeps the new-tab behavior). Shared by the top-level
 // grid and child grids.
+//
+// Cell TEXT (the 'text' local below): the visible string a cell renders. By
+// default it is the column's single 'field' value, but an optional
+// 'col.template' string wins: its {{field}} tokens are spliced from the row
+// (interpTemplate) into DOM text. A template lets one cell combine several
+// fields / add surrounding text (e.g. "{{current_wave}}/{{wave_count}}")
+// without denormalising a display column into the datasource. The template
+// drives the rendered text for the plain, linkField and link
+// (page/processExplorer) paths — a link's href still comes from its own
+// keyField/linkField, never the template. The 'badge' presence gate and its
+// tooltip stay keyed to the raw 'field' value (a badge shows a fixed glyph, not
+// the field text), so a template does not change badge behaviour. Sorting,
+// groupBy and orderBy also key off real fields, never the rendered template.
 function gridCell(col, row) {
-  const text = row[col.field] == null ? "" : String(row[col.field]);
+  // Raw single-field value: drives the badge presence gate + tooltip and any
+  // field-derived defaults. Kept separate from the (possibly templated) display
+  // text so a template never re-lights or blanks a badge.
+  const rawText = row[col.field] == null ? "" : String(row[col.field]);
+  // Visible text: a col.template (interpolated from the row) wins over the
+  // raw field value, else the field value is shown verbatim.
+  const text = typeof col.template === "string" ? interpTemplate(col.template, row) : rawText;
   // 1. badge — a compact status indicator. When the row's field value is
   //    non-empty (truthy after trimming) render a small circular badge (e.g. a
   //    red "1" dot flagging an incident) whose tooltip is the full field text;
@@ -963,14 +1003,14 @@ function gridCell(col, row) {
   //    field text is also mirrored into aria-label so assistive tech announces
   //    the incident/status text (the visible "1" glyph alone is not meaningful).
   if (col.badge) {
-    if (text.trim() === "") return el("td", {});
+    if (rawText.trim() === "") return el("td", {});
     const t = col.badge.tone;
     const tone = t === "warn" || t === "ok" || t === "info" ? t : "danger";
     const label = col.badge.label == null ? "1" : String(col.badge.label);
     return el(
       "td",
       {},
-      el("span", { class: "pc-badge pc-badge-" + tone, title: text, "aria-label": text }, label),
+      el("span", { class: "pc-badge pc-badge-" + tone, title: rawText, "aria-label": rawText }, label),
     );
   }
   if (col.linkField) {

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

@@ -35,6 +35,11 @@ export interface ShapeDecl {
     /** Model-level metadata (`nano:meta`), free-form key/value (ADR 0040 §5). */
     meta?: Record<string, string>;
 }
+/** Scan one BPMN document for its `nano:shape` declarations (ADR 0040 §9), in document order, each
+ * tagged with the enclosing process for provenance. A shape with no `id` is skipped; op children
+ * are folded in author (XML) order. This is the standalone-`urban-gen` port of the shape-parsing
+ * half of the console's `envelope_scan.rs`. */
+export declare function scanModelShapes(xml: string): ShapeDecl[];
 /** A scan/resolve-time problem with a shape, surfaced like the `workers[]` drift warning (never a
  * silent merge). A shape with any `error` diagnostic is omitted from the fuse; a `warning` (e.g. a
  * deliberate field shadow) still resolves. */

package/dist/toolkit/derivers/shapes.js

@@ -19,6 +19,96 @@
 // `domain_types.ts`), so the toolkit is the single source of truth for the IDE's shape fuse
 // (host dry-out nano-bpm#576).
 import { isPrimitiveKeyword, sqliteAffinityToTs, } from "./domain.js";
+// --- model scan (`nano:shape` XML → `ShapeDecl[]`) -------------------------------------------
+// The regex-based BPMN scan mirrors the Rust `envelope_scan.rs` shape parser (and the sibling
+// `meta.ts`/`worker-io.ts` scanners): the toolkit is the standalone `urban gen` path, so it must
+// lift model-authored shapes itself rather than receive them from the host reifier.
+/** Read a `name="…"` attribute off an element's opening tag (any namespace prefix on the name). */
+function shapeAttr(tag, name) {
+    const m = tag.match(new RegExp(`\\b${name}\\s*=\\s*"([^"]*)"`));
+    const v = m?.[1]?.trim();
+    return v != null && v.length > 0 ? v : undefined;
+}
+/** A boolean attribute is true only for the exact literal `"true"` (mirrors `bool_attr`). */
+function shapeBool(tag, name) {
+    const m = tag.match(new RegExp(`\\b${name}\\s*=\\s*"([^"]*)"`));
+    return m?.[1]?.trim() === "true";
+}
+/** Split a comma-delimited `fields="a, b"` list, trimming and dropping empties (`split_fields`). */
+function splitFields(raw) {
+    return (raw ?? "").split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+}
+/** The enclosing `bpmn:process` id (provenance for the `model:<processId>` tag), best-effort. */
+function processId(xml) {
+    const m = xml.match(/<[\w.-]*:?process\b[^>]*>/);
+    return m ? shapeAttr(m[0], "id") : undefined;
+}
+// One `nano:shape` element: capture its open-tag attrs (2) and inner body (3, empty when self-closing).
+const SHAPE_RE = /<([\w.-]*:)?shape\b([^>]*?)(?:\/>|>([\s\S]*?)<\/\1?shape\s*>)/g;
+// One composition op child (`nano:carry|project|extend|reference`): the local name (2) + its attrs (3).
+const SHAPE_OP_RE = /<([\w.-]*:)?(carry|project|extend|reference)\b([^>]*?)\/?>/g;
+/** Parse one composition-op element into a `ShapeOp`. An op missing a required attribute is dropped
+ * (returns `undefined`) so a malformed model degrades rather than emitting a spurious binding —
+ * mirrors `parse_shape_op` in `envelope_scan.rs`. */
+function parseShapeOp(local, attrs) {
+    const tag = `<x ${attrs}>`;
+    switch (local) {
+        case "carry": {
+            const ref = shapeAttr(tag, "ref");
+            return ref ? { op: "carry", ref } : undefined;
+        }
+        case "project": {
+            const ref = shapeAttr(tag, "ref");
+            if (!ref)
+                return undefined;
+            return { op: "project", ref, fields: splitFields(shapeAttr(tag, "fields")), via: shapeAttr(tag, "via") };
+        }
+        case "extend": {
+            const name = shapeAttr(tag, "name");
+            const type = shapeAttr(tag, "type");
+            if (!name || !type)
+                return undefined;
+            return { op: "extend", name, type, optional: shapeBool(tag, "optional"), list: shapeBool(tag, "list") };
+        }
+        case "reference": {
+            const name = shapeAttr(tag, "name");
+            const ref = shapeAttr(tag, "ref");
+            if (!name || !ref)
+                return undefined;
+            return { op: "reference", name, ref, spread: shapeBool(tag, "spread"), list: shapeBool(tag, "list") };
+        }
+        default:
+            return undefined;
+    }
+}
+/** Scan one BPMN document for its `nano:shape` declarations (ADR 0040 §9), in document order, each
+ * tagged with the enclosing process for provenance. A shape with no `id` is skipped; op children
+ * are folded in author (XML) order. This is the standalone-`urban-gen` port of the shape-parsing
+ * half of the console's `envelope_scan.rs`. */
+export function scanModelShapes(xml) {
+    const proc = processId(xml);
+    const out = [];
+    let sm;
+    SHAPE_RE.lastIndex = 0;
+    while ((sm = SHAPE_RE.exec(xml)) !== null) {
+        const open = `<x ${sm[2]}>`;
+        const id = shapeAttr(open, "id");
+        if (!id)
+            continue;
+        const name = shapeAttr(open, "name");
+        const body = sm[3] ?? "";
+        const ops = [];
+        let om;
+        SHAPE_OP_RE.lastIndex = 0;
+        while ((om = SHAPE_OP_RE.exec(body)) !== null) {
+            const op = parseShapeOp(om[2], om[3] ?? "");
+            if (op)
+                ops.push(op);
+        }
+        out.push({ id, name, process: proc, ops });
+    }
+    return out;
+}
 /** Map one datasource column to a domain field. A nullable column widens to `optional` (the
  * composed shape is a motion snapshot: an absent value reads as undefined, not SQL NULL). The
  * manifest keyword is inferred from the column's SQLite affinity so it flows through `fieldTsType`

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

@@ -1,4 +1,5 @@
 import type { DerivedArtifact, Deriver } from "../artifact.ts";
+import type { DomainTypeRegistry } from "./domain.ts";
 export interface ModelSource {
     /** Path (used only for diagnostics/ordering). */
     path: string;
@@ -57,6 +58,30 @@ export declare const workerIoDeriver: Deriver<{
     models: ModelSource[];
     declaredTypeIds: Iterable<string>;
 }>;
+/** A data-envelope conflict: one `taskType` bound to variants that disagree on a field's *type*. */
+export interface EnvelopeConflict {
+    taskType: string;
+    /** `"in"` (job.variables) or `"out"` (result). */
+    slot: "in" | "out";
+    field: string;
+    /** The distinct resolved type expressions seen for `field`, one per conflicting variant. */
+    types: string[];
+    /** The envelope ids that carry the conflicting field, in scan order. */
+    envelopes: string[];
+}
+/**
+ * Report data-envelope conflicts: a `taskType` serviced by more than one *distinct* envelope whose
+ * variants disagree on the resolved TYPE of a shared field. A single handler is keyed by `taskType`,
+ * so its input/output is the UNION of every variant (see `emitWorkerBindings`). A union is sound as
+ * long as a shared field means the same thing everywhere; differing presence or optionality is fine
+ * (that is the normal subset/superset relationship the union already narrows). But a field declared
+ * `string` in one variant and `number` in another is a genuine contract conflict the author must
+ * resolve (split the job type or unify the envelope) — this surfaces it instead of silently
+ * emitting `string | number`. Compatible variants (nwf's escalation subset) produce no diagnostic.
+ */
+export declare function detectEnvelopeConflicts(workers: WorkerBindingDecl[], types: DomainTypeRegistry): EnvelopeConflict[];
+/** Human-readable warning for one envelope conflict, for the gen warning stream. */
+export declare function formatEnvelopeConflict(c: EnvelopeConflict): string;
 /**
  * Overlay the model-derived worker-IO map onto the manifest `workers[]`. The model is authoritative
  * for the envelope (`inputType`/`outputType`), so every scanned `taskType` takes its I/O from

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

@@ -96,21 +96,48 @@ export function emitWorkerBindings(workers, declaredTypeIds) {
     const taskTypeUnion = taskTypes.length > 0
         ? taskTypes.map((t) => JSON.stringify(t)).join(" | ")
         : "string";
-    const inputs = [];
-    const outputs = [];
-    const headers = [];
+    // A `taskType` may be serviced by more than one model element (a worker reused across processes,
+    // or the same job on several boundaries), each declaring its own data envelope. The interface is
+    // keyed by `taskType`, so a single member must cover every caller. We UNION the distinct declared
+    // envelope ids: `DomainTypes["A"] | DomainTypes["B"]`. A union is exactly the right contract for a
+    // shared handler — it reads the safe common surface (a field is accessible only where it is
+    // present-and-compatibly-typed in *every* variant, so an optional/absent-in-one field is not
+    // guaranteed), which is the "required iff required in all callers" rule. A single variant collapses
+    // to a plain `DomainTypes["A"]`. Genuine field-type conflicts across variants are reported out of
+    // band (see `detectEnvelopeConflicts`), where the resolved field types are in hand.
+    const inIds = new Map();
+    const outIds = new Map();
+    const hdrKeys = new Map();
+    const pushDistinct = (m, key, val) => {
+        const list = m.get(key) ?? [];
+        if (!list.includes(val))
+            list.push(val);
+        m.set(key, list);
+    };
     for (const w of workers) {
         if (typeof w?.taskType !== "string" || w.taskType.length === 0)
             continue;
-        const inRef = typeRefFor(w.inputType, declared);
-        if (inRef)
-            inputs.push(`  ${propKey(w.taskType)}: ${inRef};`);
-        const outRef = typeRefFor(w.outputType, declared);
-        if (outRef)
-            outputs.push(`  ${propKey(w.taskType)}: ${outRef};`);
-        const hdrRef = headerRefFor(w.headerKeys);
+        if (w.inputType && declared.has(w.inputType))
+            pushDistinct(inIds, w.taskType, w.inputType);
+        if (w.outputType && declared.has(w.outputType))
+            pushDistinct(outIds, w.taskType, w.outputType);
+        for (const k of w.headerKeys ?? []) {
+            if (typeof k === "string" && k.trim().length > 0)
+                pushDistinct(hdrKeys, w.taskType, k.trim());
+        }
+    }
+    const unionRef = (ids) => ids.map((id) => typeRefFor(id, declared)).filter((r) => !!r).join(" | ");
+    const inputs = [...inIds.entries()]
+        .filter(([, ids]) => ids.length > 0)
+        .map(([t, ids]) => `  ${propKey(t)}: ${unionRef(ids)};`);
+    const outputs = [...outIds.entries()]
+        .filter(([, ids]) => ids.length > 0)
+        .map(([t, ids]) => `  ${propKey(t)}: ${unionRef(ids)};`);
+    const headers = [];
+    for (const [t, keys] of hdrKeys.entries()) {
+        const hdrRef = headerRefFor(keys);
         if (hdrRef)
-            headers.push(`  ${propKey(w.taskType)}: ${hdrRef};`);
+            headers.push(`  ${propKey(t)}: ${hdrRef};`);
     }
     const header = "// AUTO-GENERATED by nanobpmn from the App manifest (ADR 0033 §3).\n" +
         "// The bridge from the process model to the worker type system: each declared\n" +
@@ -169,6 +196,72 @@ export const workerIoDeriver = {
     describe: "Derive worker-io.d.ts (task type + data-envelope in/out) from BPMN models.",
     derive: ({ models, declaredTypeIds }) => deriveWorkerBindings(models, declaredTypeIds),
 };
+function fieldSig(f) {
+    return `${f.type}${f.list ? "[]" : ""}`;
+}
+/**
+ * Report data-envelope conflicts: a `taskType` serviced by more than one *distinct* envelope whose
+ * variants disagree on the resolved TYPE of a shared field. A single handler is keyed by `taskType`,
+ * so its input/output is the UNION of every variant (see `emitWorkerBindings`). A union is sound as
+ * long as a shared field means the same thing everywhere; differing presence or optionality is fine
+ * (that is the normal subset/superset relationship the union already narrows). But a field declared
+ * `string` in one variant and `number` in another is a genuine contract conflict the author must
+ * resolve (split the job type or unify the envelope) — this surfaces it instead of silently
+ * emitting `string | number`. Compatible variants (nwf's escalation subset) produce no diagnostic.
+ */
+export function detectEnvelopeConflicts(workers, types) {
+    const collect = (pick, slot) => {
+        const byType = new Map();
+        for (const w of workers) {
+            const id = pick(w);
+            if (typeof w?.taskType !== "string" || !w.taskType || !id || !Object.hasOwn(types, id))
+                continue;
+            const list = byType.get(w.taskType) ?? [];
+            if (!list.includes(id))
+                list.push(id);
+            byType.set(w.taskType, list);
+        }
+        const conflicts = [];
+        for (const [taskType, ids] of byType.entries()) {
+            if (ids.length < 2)
+                continue;
+            const fieldNames = new Set();
+            for (const id of ids)
+                for (const name of Object.keys(types[id].fields))
+                    fieldNames.add(name);
+            for (const field of fieldNames) {
+                const seen = new Map(); // signature -> envelope ids carrying it
+                for (const id of ids) {
+                    if (!Object.hasOwn(types[id].fields, field))
+                        continue; // absent in this variant — a presence difference, not a type conflict
+                    const f = types[id].fields[field];
+                    const sig = fieldSig(f);
+                    const carriers = seen.get(sig) ?? [];
+                    carriers.push(id);
+                    seen.set(sig, carriers);
+                }
+                if (seen.size > 1) {
+                    conflicts.push({
+                        taskType,
+                        slot,
+                        field,
+                        types: [...seen.keys()],
+                        envelopes: ids.filter((id) => Object.hasOwn(types[id].fields, field)),
+                    });
+                }
+            }
+        }
+        return conflicts;
+    };
+    return [...collect((w) => w.inputType, "in"), ...collect((w) => w.outputType, "out")];
+}
+/** Human-readable warning for one envelope conflict, for the gen warning stream. */
+export function formatEnvelopeConflict(c) {
+    return (`data-envelope conflict on worker "${c.taskType}" (${c.slot}): field "${c.field}" is ` +
+        `${c.types.join(" vs ")} across envelopes ${c.envelopes.map((e) => `"${e}"`).join(", ")}. ` +
+        `The taskType's ${c.slot === "in" ? "input" : "output"} is the union of its envelopes; a ` +
+        `field must have one type across all of them. Unify the envelope or split the job type.`);
+}
 /**
  * Overlay the model-derived worker-IO map onto the manifest `workers[]`. The model is authoritative
  * for the envelope (`inputType`/`outputType`), so every scanned `taskType` takes its I/O from

package/dist/toolkit/gen.js

@@ -4,10 +4,11 @@
 // pure; all IO is confined here behind a tiny FS port so the same code runs on Node and Deno.
 import { GENERATED_DIR, isAbsolutePath, RUNTIME_MATERIALIZED_ARTIFACTS, sortArtifacts } from "./artifact.js";
 import { deriveMigrations } from "./derivers/migrations.js";
-import { deriveDomain } from "./derivers/domain.js";
-import { deriveWorkerBindings } from "./derivers/worker-io.js";
+import { emitDomainModel, registryFromManifest, sourcesFromManifest } from "./derivers/domain.js";
+import { byModelPath, deriveWorkerBindings, detectEnvelopeConflicts, DOMAIN_DTS, formatEnvelopeConflict, scanModelWorkers } from "./derivers/worker-io.js";
 import { deriveMeta } from "./derivers/meta.js";
 import { deriveMessageBindings } from "./derivers/messages.js";
+import { resolveShapes, scanModelShapes } from "./derivers/shapes.js";
 import { deriveApi } from "./derivers/api.js";
 import { parseSpec, sharedRequestBodySchemas } from "../openapi/spec.js";
 import { deriveModels, MODEL_PROVENANCE } from "./models.js";
@@ -69,28 +70,60 @@ async function collectAll(opts) {
     const manifest = JSON.parse(await io.readText(manifestPath));
     const artifacts = [];
     const warnings = [];
-    // 1. types → migrations + domain row types (DomainTables spine + DomainTypes registry)
-    if (!opts.modelsOnly && manifest.types && Object.keys(manifest.types).length > 0) {
-        artifacts.push(...deriveMigrations(manifest));
-        artifacts.push(...deriveDomain(manifest));
-    }
-    // 2. code-first models → derive BPMN from `workflows/*.ts` (executes the app's TS). The derived
-    //    `.bpmn` are emitted only when `emitModels` (default), but always fed to the type-contract
-    //    derivers below so worker I/O works for a code-first app even on a `--no-models` run.
+    // 1. Resolve the app's models first (code-first `workflows/*.ts` → BPMN, plus authored on-disk
+    //    `.bpmn`): the fused domain model (below) lifts `nano:shape` envelopes *from* the models, so
+    //    they must be in hand before the domain + worker/message type-contracts are derived.
     const derived = await deriveModels(root, io, manifest);
+    //    The derived `.bpmn` are emitted only when `emitModels` (default), but always fed to the
+    //    type-contract derivers so worker I/O works for a code-first app even on a `--no-models` run.
     if (emitModels)
         artifacts.push(...derived.artifacts);
-    // 3. models (authored on-disk + derived) → worker I/O index + meta accessor + message map.
-    //    Drop any on-disk model whose path a derived model already covers, to avoid double-counting.
+    const derivedPaths = new Set(derived.artifacts.map((a) => a.path));
+    const diskModels = (await readModels(root, io, manifest)).filter((m) => !derivedPaths.has(m.path));
+    const models = [...diskModels, ...derived.models];
+    // 2. Fused domain model (ADR 0040): the `DomainTypes` registry is the union of the manifest
+    //    `types` registry and the model-authored `nano:shape` envelopes, resolved through the same
+    //    fuse the console reifier (`envelope_scan.rs`) uses. Without this the standalone `urban gen`
+    //    would honour only `manifest.types` and silently ignore every model-authored data envelope,
+    //    so worker/message I/O against those envelopes would fall back to the untyped `WorkerVars`.
+    const manifestRegistry = registryFromManifest(manifest);
+    const sources = sourcesFromManifest(manifest);
+    const shapeDecls = models.flatMap((m) => scanModelShapes(m.xml));
+    const shapeResolution = resolveShapes(shapeDecls, manifestRegistry, sources);
+    const fusedTypes = { ...manifestRegistry, ...shapeResolution.types };
+    for (const d of shapeResolution.diagnostics) {
+        warnings.push(`data-envelope shape "${d.shape}" (${d.kind}): ${d.message}`);
+    }
+    // 3. types → migrations (persisted `manifest.types` only — shapes are transient wire envelopes,
+    //    never tables) + the fused domain row types (`DomainTables` spine + `DomainTypes` registry).
+    if (!opts.modelsOnly && manifest.types && Object.keys(manifest.types).length > 0) {
+        artifacts.push(...deriveMigrations(manifest));
+    }
+    if (!opts.modelsOnly && Object.keys(fusedTypes).length > 0) {
+        artifacts.push({
+            path: `${GENERATED_DIR}/${DOMAIN_DTS}`,
+            content: emitDomainModel(sources, manifest.data?.default ?? "app", fusedTypes),
+        });
+    }
+    // 4. models (authored on-disk + derived) → worker I/O index + meta accessor + message map. The
+    //    declared type ids include the fused shapes, so an envelope ref to a model-authored shape
+    //    resolves to its `DomainTypes[...]` entry instead of degrading to the untyped fallback.
     if (!opts.modelsOnly) {
-        const derivedPaths = new Set(derived.artifacts.map((a) => a.path));
-        const diskModels = (await readModels(root, io, manifest)).filter((m) => !derivedPaths.has(m.path));
-        const models = [...diskModels, ...derived.models];
         if (models.length > 0) {
-            const declaredTypeIds = Object.keys(manifest.types ?? {});
+            const declaredTypeIds = Object.keys(fusedTypes);
             artifacts.push(...deriveWorkerBindings(models, declaredTypeIds));
             artifacts.push(...deriveMeta(models));
             artifacts.push(...deriveMessageBindings(models, declaredTypeIds));
+            // Surface genuine data-envelope conflicts: a taskType whose variants disagree on a field's
+            // TYPE. The emitted contract is the union of the variants (sound for a shared handler), so a
+            // type clash would silently widen to `A | B` — warn instead so the author unifies the envelope.
+            const scannedWorkers = [...models]
+                .sort(byModelPath)
+                .flatMap((m) => scanModelWorkers(m.xml))
+                .map((w) => ({ taskType: w.taskType, inputType: w.in, outputType: w.out }));
+            for (const c of detectEnvelopeConflicts(scannedWorkers, fusedTypes)) {
+                warnings.push(formatEnvelopeConflict(c));
+            }
         }
     }
     // 4. OpenAPI `api` binding → typed endpoint contracts (ADR 0058). Fail-closed: a declared spec

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.47.0",
+	"version": "0.48.0",
 	"description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
 	"license": "Apache-2.0",
 	"type": "module",

package/src/runtime/core/modules/pages.test.ts

@@ -337,12 +337,37 @@ test("renderer wires a column's badge to a tone-classed pill shown only when pre
   // (default danger), the label defaults to "1", and the full field text becomes
   // the tooltip.
   assert.match(js, /if\s*\(col\.badge\)/);
-  assert.match(js, /text\.trim\(\)\s*===\s*""/);
+  assert.match(js, /rawText\.trim\(\)\s*===\s*""/);
   assert.match(js, /t\s*===\s*"warn"\s*\|\|\s*t\s*===\s*"ok"\s*\|\|\s*t\s*===\s*"info"\s*\?\s*t\s*:\s*"danger"/);
   assert.match(js, /col\.badge\.label\s*==\s*null\s*\?\s*"1"/);
   assert.match(js, /class:\s*"pc-badge pc-badge-"\s*\+\s*tone/);
-  assert.match(js, /title:\s*text/);
-  assert.match(js, /"aria-label":\s*text/);
+  assert.match(js, /title:\s*rawText/);
+  assert.match(js, /"aria-label":\s*rawText/);
+});
+
+test("renderer interpolates a column's per-cell template into DOM text (#214)", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // A column declaring `template: "{{a}}/{{b}}"` renders one cell by splicing the
+  // named row fields into a string, coerced to text and set only as DOM text
+  // (never markup). Guard the whole shape so the primitive can't silently
+  // regress: interpTemplate exists, replaces {{field}} tokens via a function
+  // replacement (so a "$"-bearing value can't be reinterpreted as a replacement
+  // pattern), coerces null/undefined to "" (unknown tokens render blank, no
+  // throw), and gridCell prefers a string col.template over the raw field value
+  // for the visible text while the badge stays keyed to the raw field.
+  assert.match(js, /function interpTemplate\(tpl, row\)/);
+  assert.match(js, /replace\(\/\\\{\\\{\(\[\^\{\}\]\+\)\\\}\\\}\/g,/);
+  assert.match(js, /const key = name\.trim\(\);/);
+  // Unknown tokens (no such own field) render blank and, crucially, an inherited
+  // Object.prototype key (toString, constructor, …) counts as unknown rather than
+  // resolving to prototype cruft — guard the own-property gate explicitly.
+  assert.match(js, /Object\.prototype\.hasOwnProperty\.call\(row, key\) \? row\[key\] : null/);
+  assert.match(js, /return v == null \? "" : String\(v\);/);
+  // gridCell keeps the raw single-field value separate (drives the badge gate)
+  // and lets a string template win for the rendered text.
+  assert.match(js, /const rawText = row\[col\.field\] == null \? "" : String\(row\[col\.field\]\);/);
+  assert.match(js, /const text = typeof col\.template === "string" \? interpTemplate\(col\.template, row\) : rawText;/);
 });
 
 test("renderer wires a column's processExplorer link to the console explorer", async () => {

package/src/runtime/core/modules/pages.ts

@@ -838,6 +838,27 @@ function el(tag, attrs = {}, ...kids) {
 function interpParam(s) {
   return typeof s === "string" ? s.replace(/\{\{param\}\}/g, () => PARAM) : s;
 }
+
+// Interpolate {{field}} tokens in a column's per-cell template with values from
+// the row, coercing each to a string (null/undefined → ""). Like interpParam the
+// result is only ever set as DOM text (textContent via el()), so a substituted
+// row value cannot inject markup or attributes. A function replacement inserts
+// each value literally, so a "$"-bearing value can't be reinterpreted as a
+// replacement pattern. Unknown tokens (no such field) render empty rather than
+// throwing, matching interpParam. This is a dumb text formatter: no expressions,
+// arithmetic, or conditionals — just field splicing. Only the row's own
+// fields resolve (own-property gate, enumerable or not): an inherited
+// Object.prototype key (toString, constructor, …) counts as unknown and
+// renders "", so a token can't pick up prototype cruft instead of blank.
+function interpTemplate(tpl, row) {
+  return typeof tpl === "string"
+    ? tpl.replace(/\{\{([^{}]+)\}\}/g, (_m, name) => {
+        const key = name.trim();
+        const v = Object.prototype.hasOwnProperty.call(row, key) ? row[key] : null;
+        return v == null ? "" : String(v);
+      })
+    : tpl;
+}
 function renderText(node) {
   const v = node.props.variant;
   const cls = v === "heading" ? "pc-heading" : v === "sub" ? "pc-sub" : "pc-body";
@@ -1002,8 +1023,27 @@ function renderButton(node) {
 // host's own explorer view in place via the nano-navigate postMessage bridge
 // (a modified/middle click keeps the new-tab behavior). Shared by the top-level
 // grid and child grids.
+//
+// Cell TEXT (the 'text' local below): the visible string a cell renders. By
+// default it is the column's single 'field' value, but an optional
+// 'col.template' string wins: its {{field}} tokens are spliced from the row
+// (interpTemplate) into DOM text. A template lets one cell combine several
+// fields / add surrounding text (e.g. "{{current_wave}}/{{wave_count}}")
+// without denormalising a display column into the datasource. The template
+// drives the rendered text for the plain, linkField and link
+// (page/processExplorer) paths — a link's href still comes from its own
+// keyField/linkField, never the template. The 'badge' presence gate and its
+// tooltip stay keyed to the raw 'field' value (a badge shows a fixed glyph, not
+// the field text), so a template does not change badge behaviour. Sorting,
+// groupBy and orderBy also key off real fields, never the rendered template.
 function gridCell(col, row) {
-  const text = row[col.field] == null ? "" : String(row[col.field]);
+  // Raw single-field value: drives the badge presence gate + tooltip and any
+  // field-derived defaults. Kept separate from the (possibly templated) display
+  // text so a template never re-lights or blanks a badge.
+  const rawText = row[col.field] == null ? "" : String(row[col.field]);
+  // Visible text: a col.template (interpolated from the row) wins over the
+  // raw field value, else the field value is shown verbatim.
+  const text = typeof col.template === "string" ? interpTemplate(col.template, row) : rawText;
   // 1. badge — a compact status indicator. When the row's field value is
   //    non-empty (truthy after trimming) render a small circular badge (e.g. a
   //    red "1" dot flagging an incident) whose tooltip is the full field text;
@@ -1015,14 +1055,14 @@ function gridCell(col, row) {
   //    field text is also mirrored into aria-label so assistive tech announces
   //    the incident/status text (the visible "1" glyph alone is not meaningful).
   if (col.badge) {
-    if (text.trim() === "") return el("td", {});
+    if (rawText.trim() === "") return el("td", {});
     const t = col.badge.tone;
     const tone = t === "warn" || t === "ok" || t === "info" ? t : "danger";
     const label = col.badge.label == null ? "1" : String(col.badge.label);
     return el(
       "td",
       {},
-      el("span", { class: "pc-badge pc-badge-" + tone, title: text, "aria-label": text }, label),
+      el("span", { class: "pc-badge pc-badge-" + tone, title: rawText, "aria-label": rawText }, label),
     );
   }
   if (col.linkField) {

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

@@ -3,6 +3,7 @@ import assert from "node:assert/strict";
 import {
   emitDomainModelJson,
   resolveShapes,
+  scanModelShapes,
   type ShapeDecl,
 } from "./shapes.ts";
 import type { DomainTypeRegistry, SourceSchema } from "./domain.ts";
@@ -169,3 +170,68 @@ test("resolveShapes returns an empty resolution for no shapes", () => {
   assert.deepEqual(types, {});
   assert.deepEqual(diagnostics, []);
 });
+
+// --- scanModelShapes: the standalone-`urban gen` port of the `nano:shape` XML scan --------------
+
+const SHAPES_BPMN = `<?xml version="1.0"?>
+<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL"
+  xmlns:nano="http://nanobpm.io/schema/nano/1.0">
+  <bpmn:process id="p1">
+    <bpmn:extensionElements>
+      <nano:shapes>
+        <nano:shape id="ReviewIn" name="Review — input">
+          <nano:extend name="prUrl" type="string" />
+          <nano:extend name="round" type="integer" />
+          <nano:extend name="answer" type="string" optional="true" />
+        </nano:shape>
+        <nano:shape id="Composed">
+          <nano:carry ref="ReviewIn" />
+          <nano:project ref="Customer" fields="tier, region" via="Order.customerId" />
+          <nano:reference name="lines" ref="OrderLine" spread="false" list="true" />
+        </nano:shape>
+        <nano:shape name="no-id-dropped"><nano:carry ref="ReviewIn" /></nano:shape>
+      </nano:shapes>
+    </bpmn:extensionElements>
+  </bpmn:process>
+</bpmn:definitions>`;
+
+test("scanModelShapes lifts nano:shape declarations with ops in author order", () => {
+  const shapes = scanModelShapes(SHAPES_BPMN);
+  // The id-less shape is dropped; the two identified shapes survive, process-tagged.
+  assert.deepEqual(shapes.map((s) => s.id), ["ReviewIn", "Composed"]);
+  assert.equal(shapes[0].process, "p1");
+  assert.equal(shapes[0].name, "Review — input");
+  assert.deepEqual(shapes[0].ops, [
+    { op: "extend", name: "prUrl", type: "string", optional: false, list: false },
+    { op: "extend", name: "round", type: "integer", optional: false, list: false },
+    { op: "extend", name: "answer", type: "string", optional: true, list: false },
+  ]);
+  assert.deepEqual(shapes[1].ops, [
+    { op: "carry", ref: "ReviewIn" },
+    { op: "project", ref: "Customer", fields: ["tier", "region"], via: "Order.customerId" },
+    { op: "reference", name: "lines", ref: "OrderLine", spread: false, list: true },
+  ]);
+});
+
+test("scanModelShapes → resolveShapes round-trips an all-extend envelope into DomainTypes", () => {
+  const shapes = scanModelShapes(SHAPES_BPMN).filter((s) => s.id === "ReviewIn");
+  const { types, diagnostics } = resolveShapes(shapes, {}, []);
+  assert.deepEqual(diagnostics, []);
+  assert.deepEqual(types.ReviewIn.fields, {
+    prUrl: { type: "string" },
+    round: { type: "integer" },
+    answer: { type: "string", optional: true },
+  });
+});
+
+test("scanModelShapes drops an op missing a required attribute", () => {
+  const xml = `<bpmn:process id="p"><bpmn:extensionElements><nano:shapes>
+    <nano:shape id="S">
+      <nano:extend name="ok" type="string" />
+      <nano:extend name="noType" />
+      <nano:carry />
+    </nano:shape>
+  </nano:shapes></bpmn:extensionElements></bpmn:process>`;
+  const [s] = scanModelShapes(xml);
+  assert.deepEqual(s.ops, [{ op: "extend", name: "ok", type: "string", optional: false, list: false }]);
+});

package/src/toolkit/derivers/shapes.ts

@@ -50,6 +50,99 @@ export interface ShapeDecl {
   meta?: Record<string, string>;
 }
 
+// --- model scan (`nano:shape` XML → `ShapeDecl[]`) -------------------------------------------
+// The regex-based BPMN scan mirrors the Rust `envelope_scan.rs` shape parser (and the sibling
+// `meta.ts`/`worker-io.ts` scanners): the toolkit is the standalone `urban gen` path, so it must
+// lift model-authored shapes itself rather than receive them from the host reifier.
+
+/** Read a `name="…"` attribute off an element's opening tag (any namespace prefix on the name). */
+function shapeAttr(tag: string, name: string): string | undefined {
+  const m = tag.match(new RegExp(`\\b${name}\\s*=\\s*"([^"]*)"`));
+  const v = m?.[1]?.trim();
+  return v != null && v.length > 0 ? v : undefined;
+}
+
+/** A boolean attribute is true only for the exact literal `"true"` (mirrors `bool_attr`). */
+function shapeBool(tag: string, name: string): boolean {
+  const m = tag.match(new RegExp(`\\b${name}\\s*=\\s*"([^"]*)"`));
+  return m?.[1]?.trim() === "true";
+}
+
+/** Split a comma-delimited `fields="a, b"` list, trimming and dropping empties (`split_fields`). */
+function splitFields(raw: string | undefined): string[] {
+  return (raw ?? "").split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+}
+
+/** The enclosing `bpmn:process` id (provenance for the `model:<processId>` tag), best-effort. */
+function processId(xml: string): string | undefined {
+  const m = xml.match(/<[\w.-]*:?process\b[^>]*>/);
+  return m ? shapeAttr(m[0], "id") : undefined;
+}
+
+// One `nano:shape` element: capture its open-tag attrs (2) and inner body (3, empty when self-closing).
+const SHAPE_RE = /<([\w.-]*:)?shape\b([^>]*?)(?:\/>|>([\s\S]*?)<\/\1?shape\s*>)/g;
+// One composition op child (`nano:carry|project|extend|reference`): the local name (2) + its attrs (3).
+const SHAPE_OP_RE = /<([\w.-]*:)?(carry|project|extend|reference)\b([^>]*?)\/?>/g;
+
+/** Parse one composition-op element into a `ShapeOp`. An op missing a required attribute is dropped
+ * (returns `undefined`) so a malformed model degrades rather than emitting a spurious binding —
+ * mirrors `parse_shape_op` in `envelope_scan.rs`. */
+function parseShapeOp(local: string, attrs: string): ShapeOp | undefined {
+  const tag = `<x ${attrs}>`;
+  switch (local) {
+    case "carry": {
+      const ref = shapeAttr(tag, "ref");
+      return ref ? { op: "carry", ref } : undefined;
+    }
+    case "project": {
+      const ref = shapeAttr(tag, "ref");
+      if (!ref) return undefined;
+      return { op: "project", ref, fields: splitFields(shapeAttr(tag, "fields")), via: shapeAttr(tag, "via") };
+    }
+    case "extend": {
+      const name = shapeAttr(tag, "name");
+      const type = shapeAttr(tag, "type");
+      if (!name || !type) return undefined;
+      return { op: "extend", name, type, optional: shapeBool(tag, "optional"), list: shapeBool(tag, "list") };
+    }
+    case "reference": {
+      const name = shapeAttr(tag, "name");
+      const ref = shapeAttr(tag, "ref");
+      if (!name || !ref) return undefined;
+      return { op: "reference", name, ref, spread: shapeBool(tag, "spread"), list: shapeBool(tag, "list") };
+    }
+    default:
+      return undefined;
+  }
+}
+
+/** Scan one BPMN document for its `nano:shape` declarations (ADR 0040 §9), in document order, each
+ * tagged with the enclosing process for provenance. A shape with no `id` is skipped; op children
+ * are folded in author (XML) order. This is the standalone-`urban-gen` port of the shape-parsing
+ * half of the console's `envelope_scan.rs`. */
+export function scanModelShapes(xml: string): ShapeDecl[] {
+  const proc = processId(xml);
+  const out: ShapeDecl[] = [];
+  let sm: RegExpExecArray | null;
+  SHAPE_RE.lastIndex = 0;
+  while ((sm = SHAPE_RE.exec(xml)) !== null) {
+    const open = `<x ${sm[2]}>`;
+    const id = shapeAttr(open, "id");
+    if (!id) continue;
+    const name = shapeAttr(open, "name");
+    const body = sm[3] ?? "";
+    const ops: ShapeOp[] = [];
+    let om: RegExpExecArray | null;
+    SHAPE_OP_RE.lastIndex = 0;
+    while ((om = SHAPE_OP_RE.exec(body)) !== null) {
+      const op = parseShapeOp(om[2], om[3] ?? "");
+      if (op) ops.push(op);
+    }
+    out.push({ id, name, process: proc, ops });
+  }
+  return out;
+}
+
 /** A scan/resolve-time problem with a shape, surfaced like the `workers[]` drift warning (never a
  * silent merge). A shape with any `error` diagnostic is omitted from the fuse; a `warning` (e.g. a
  * deliberate field shadow) still resolves. */

package/src/toolkit/derivers/worker-io.test.ts

@@ -2,11 +2,14 @@ import { test } from "node:test";
 import assert from "node:assert/strict";
 import {
   deriveWorkerBindings,
+  detectEnvelopeConflicts,
   emitWorkerBindings,
+  formatEnvelopeConflict,
   scanModelWorkers,
   byModelPath,
   type WorkerIo,
 } from "./worker-io.ts";
+import type { DomainFieldDef, DomainTypeRegistry } from "./domain.ts";
 
 test("byModelPath is a spec-compliant comparator: returns 0 for equal paths", () => {
   assert.equal(byModelPath({ path: "a" }, { path: "a" }), 0);
@@ -72,6 +75,134 @@ test("emitWorkerBindings falls back to string union + no import when nothing is
   assert.match(out, /export interface WorkerInputs \{\}/);
 });
 
+test("emitWorkerBindings unions distinct envelopes bound to one taskType (shared handler)", () => {
+  // The same worker services two processes, each declaring its own envelope. Keyed by taskType,
+  // the member is the UNION — a shared handler reads only what every caller guarantees.
+  const out = emitWorkerBindings(
+    [
+      { taskType: "pr.persist-escalation", inputType: "PrPersistEscalationIn" },
+      { taskType: "pr.persist-escalation", inputType: "MergeEscalationIn" },
+    ],
+    ["PrPersistEscalationIn", "MergeEscalationIn"],
+  );
+  assert.match(
+    out,
+    /"pr.persist-escalation": DomainTypes\["PrPersistEscalationIn"\] \| DomainTypes\["MergeEscalationIn"\];/,
+  );
+});
+
+test("emitWorkerBindings collapses a repeated identical envelope to a single ref (no dup keys)", () => {
+  const out = emitWorkerBindings(
+    [
+      { taskType: "pr.persist-escalation", inputType: "EscalationIn" },
+      { taskType: "pr.persist-escalation", inputType: "EscalationIn" },
+      { taskType: "pr.persist-escalation", inputType: "EscalationIn" },
+    ],
+    ["EscalationIn"],
+  );
+  // Exactly one member, no union, and the interface still parses (no duplicate identifier).
+  assert.match(out, /export interface WorkerInputs \{\n {2}"pr.persist-escalation": DomainTypes\["EscalationIn"\];\n\}/);
+});
+
+test("detectEnvelopeConflicts stays silent for a compatible subset (nwf escalation shape)", () => {
+  const types: DomainTypeRegistry = {
+    PrPersistEscalationIn: {
+      fields: {
+        prKey: { type: "string" },
+        round: { type: "integer" },
+        recordRound: { type: "boolean", optional: true },
+      },
+    },
+    MergeEscalationIn: {
+      fields: { prKey: { type: "string" }, round: { type: "integer" } },
+    },
+  };
+  const conflicts = detectEnvelopeConflicts(
+    [
+      { taskType: "pr.persist-escalation", inputType: "PrPersistEscalationIn" },
+      { taskType: "pr.persist-escalation", inputType: "MergeEscalationIn" },
+    ],
+    types,
+  );
+  // A field present in one and absent in the other, or optional in one, is NOT a conflict.
+  assert.deepEqual(conflicts, []);
+});
+
+test("detectEnvelopeConflicts flags a genuine field-type clash across envelopes", () => {
+  const types: DomainTypeRegistry = {
+    A: { fields: { round: { type: "integer" } } },
+    B: { fields: { round: { type: "string" } } },
+  };
+  const conflicts = detectEnvelopeConflicts(
+    [
+      { taskType: "pr.review", inputType: "A" },
+      { taskType: "pr.review", inputType: "B" },
+    ],
+    types,
+  );
+  assert.equal(conflicts.length, 1);
+  assert.equal(conflicts[0].taskType, "pr.review");
+  assert.equal(conflicts[0].slot, "in");
+  assert.equal(conflicts[0].field, "round");
+  assert.deepEqual(conflicts[0].types.sort(), ["integer", "string"]);
+  assert.match(formatEnvelopeConflict(conflicts[0]), /field "round" is integer vs string/);
+});
+
+test("detectEnvelopeConflicts treats a list mismatch as a conflict", () => {
+  const types: DomainTypeRegistry = {
+    A: { fields: { tags: { type: "string" } } },
+    B: { fields: { tags: { type: "string", list: true } } },
+  };
+  const conflicts = detectEnvelopeConflicts(
+    [
+      { taskType: "t", outputType: "A" },
+      { taskType: "t", outputType: "B" },
+    ],
+    types,
+  );
+  assert.equal(conflicts.length, 1);
+  assert.equal(conflicts[0].slot, "out");
+  assert.deepEqual(conflicts[0].types.sort(), ["string", "string[]"]);
+});
+
+test("detectEnvelopeConflicts uses own-property checks for envelope ids (no prototype-chain false positives)", () => {
+  const types: DomainTypeRegistry = {
+    Real: { fields: { prKey: { type: "string" } } },
+  };
+  // An author-named envelope id that only exists on Object.prototype ("toString", "constructor")
+  // must be treated as undeclared and skipped — not read through the prototype chain, which would
+  // yield a non-registry value and (previously) crash on `.fields`.
+  const conflicts = detectEnvelopeConflicts(
+    [
+      { taskType: "t", inputType: "Real" },
+      { taskType: "t", inputType: "toString" },
+      { taskType: "t", inputType: "constructor" },
+    ],
+    types,
+  );
+  assert.deepEqual(conflicts, []);
+});
+
+test("detectEnvelopeConflicts uses own-property checks for field names (no prototype-chain false positives)", () => {
+  // Envelope A carries an own field literally named "toString"; B does not carry it at all.
+  // A prototype-chain read (`B.fields["toString"]`) would resolve to Object.prototype.toString and
+  // fabricate a spurious type conflict; an own-property check correctly sees it as a presence
+  // difference, which is not a conflict.
+  const aFields: Record<string, DomainFieldDef> = { toString: { type: "string" } };
+  const types: DomainTypeRegistry = {
+    A: { fields: aFields },
+    B: { fields: { prKey: { type: "string" } } },
+  };
+  const conflicts = detectEnvelopeConflicts(
+    [
+      { taskType: "t", inputType: "A" },
+      { taskType: "t", inputType: "B" },
+    ],
+    types,
+  );
+  assert.deepEqual(conflicts, []);
+});
+
 test("deriveWorkerBindings is deterministic and emits worker-io.d.ts", () => {
   const models = [{ path: "processes/orders.bpmn", xml: XML }];
   const a1 = deriveWorkerBindings(models, ["Payment", "Receipt"]);

package/src/toolkit/derivers/worker-io.ts

@@ -6,6 +6,7 @@
 
 import type { DerivedArtifact, Deriver } from "../artifact.ts";
 import { GENERATED_DIR } from "../artifact.ts";
+import type { DomainFieldDef, DomainTypeRegistry } from "./domain.ts";
 
 export interface ModelSource {
   /** Path (used only for diagnostics/ordering). */
@@ -137,17 +138,43 @@ export function emitWorkerBindings(
   const taskTypeUnion = taskTypes.length > 0
     ? taskTypes.map((t) => JSON.stringify(t)).join(" | ")
     : "string";
-  const inputs: string[] = [];
-  const outputs: string[] = [];
-  const headers: string[] = [];
+  // A `taskType` may be serviced by more than one model element (a worker reused across processes,
+  // or the same job on several boundaries), each declaring its own data envelope. The interface is
+  // keyed by `taskType`, so a single member must cover every caller. We UNION the distinct declared
+  // envelope ids: `DomainTypes["A"] | DomainTypes["B"]`. A union is exactly the right contract for a
+  // shared handler — it reads the safe common surface (a field is accessible only where it is
+  // present-and-compatibly-typed in *every* variant, so an optional/absent-in-one field is not
+  // guaranteed), which is the "required iff required in all callers" rule. A single variant collapses
+  // to a plain `DomainTypes["A"]`. Genuine field-type conflicts across variants are reported out of
+  // band (see `detectEnvelopeConflicts`), where the resolved field types are in hand.
+  const inIds = new Map<string, string[]>();
+  const outIds = new Map<string, string[]>();
+  const hdrKeys = new Map<string, string[]>();
+  const pushDistinct = (m: Map<string, string[]>, key: string, val: string) => {
+    const list = m.get(key) ?? [];
+    if (!list.includes(val)) list.push(val);
+    m.set(key, list);
+  };
   for (const w of workers) {
     if (typeof w?.taskType !== "string" || w.taskType.length === 0) continue;
-    const inRef = typeRefFor(w.inputType, declared);
-    if (inRef) inputs.push(`  ${propKey(w.taskType)}: ${inRef};`);
-    const outRef = typeRefFor(w.outputType, declared);
-    if (outRef) outputs.push(`  ${propKey(w.taskType)}: ${outRef};`);
-    const hdrRef = headerRefFor(w.headerKeys);
-    if (hdrRef) headers.push(`  ${propKey(w.taskType)}: ${hdrRef};`);
+    if (w.inputType && declared.has(w.inputType)) pushDistinct(inIds, w.taskType, w.inputType);
+    if (w.outputType && declared.has(w.outputType)) pushDistinct(outIds, w.taskType, w.outputType);
+    for (const k of w.headerKeys ?? []) {
+      if (typeof k === "string" && k.trim().length > 0) pushDistinct(hdrKeys, w.taskType, k.trim());
+    }
+  }
+  const unionRef = (ids: string[]): string =>
+    ids.map((id) => typeRefFor(id, declared)).filter((r): r is string => !!r).join(" | ");
+  const inputs = [...inIds.entries()]
+    .filter(([, ids]) => ids.length > 0)
+    .map(([t, ids]) => `  ${propKey(t)}: ${unionRef(ids)};`);
+  const outputs = [...outIds.entries()]
+    .filter(([, ids]) => ids.length > 0)
+    .map(([t, ids]) => `  ${propKey(t)}: ${unionRef(ids)};`);
+  const headers: string[] = [];
+  for (const [t, keys] of hdrKeys.entries()) {
+    const hdrRef = headerRefFor(keys);
+    if (hdrRef) headers.push(`  ${propKey(t)}: ${hdrRef};`);
   }
 
   const header =
@@ -217,6 +244,86 @@ export const workerIoDeriver: Deriver<{ models: ModelSource[]; declaredTypeIds:
   derive: ({ models, declaredTypeIds }) => deriveWorkerBindings(models, declaredTypeIds),
 };
 
+/** A data-envelope conflict: one `taskType` bound to variants that disagree on a field's *type*. */
+export interface EnvelopeConflict {
+  taskType: string;
+  /** `"in"` (job.variables) or `"out"` (result). */
+  slot: "in" | "out";
+  field: string;
+  /** The distinct resolved type expressions seen for `field`, one per conflicting variant. */
+  types: string[];
+  /** The envelope ids that carry the conflicting field, in scan order. */
+  envelopes: string[];
+}
+
+function fieldSig(f: DomainFieldDef): string {
+  return `${f.type}${f.list ? "[]" : ""}`;
+}
+
+/**
+ * Report data-envelope conflicts: a `taskType` serviced by more than one *distinct* envelope whose
+ * variants disagree on the resolved TYPE of a shared field. A single handler is keyed by `taskType`,
+ * so its input/output is the UNION of every variant (see `emitWorkerBindings`). A union is sound as
+ * long as a shared field means the same thing everywhere; differing presence or optionality is fine
+ * (that is the normal subset/superset relationship the union already narrows). But a field declared
+ * `string` in one variant and `number` in another is a genuine contract conflict the author must
+ * resolve (split the job type or unify the envelope) — this surfaces it instead of silently
+ * emitting `string | number`. Compatible variants (nwf's escalation subset) produce no diagnostic.
+ */
+export function detectEnvelopeConflicts(
+  workers: WorkerBindingDecl[],
+  types: DomainTypeRegistry,
+): EnvelopeConflict[] {
+  const collect = (pick: (w: WorkerBindingDecl) => string | undefined, slot: "in" | "out") => {
+    const byType = new Map<string, string[]>();
+    for (const w of workers) {
+      const id = pick(w);
+      if (typeof w?.taskType !== "string" || !w.taskType || !id || !Object.hasOwn(types, id)) continue;
+      const list = byType.get(w.taskType) ?? [];
+      if (!list.includes(id)) list.push(id);
+      byType.set(w.taskType, list);
+    }
+    const conflicts: EnvelopeConflict[] = [];
+    for (const [taskType, ids] of byType.entries()) {
+      if (ids.length < 2) continue;
+      const fieldNames = new Set<string>();
+      for (const id of ids) for (const name of Object.keys(types[id].fields)) fieldNames.add(name);
+      for (const field of fieldNames) {
+        const seen = new Map<string, string[]>(); // signature -> envelope ids carrying it
+        for (const id of ids) {
+          if (!Object.hasOwn(types[id].fields, field)) continue; // absent in this variant — a presence difference, not a type conflict
+          const f = types[id].fields[field];
+          const sig = fieldSig(f);
+          const carriers = seen.get(sig) ?? [];
+          carriers.push(id);
+          seen.set(sig, carriers);
+        }
+        if (seen.size > 1) {
+          conflicts.push({
+            taskType,
+            slot,
+            field,
+            types: [...seen.keys()],
+            envelopes: ids.filter((id) => Object.hasOwn(types[id].fields, field)),
+          });
+        }
+      }
+    }
+    return conflicts;
+  };
+  return [...collect((w) => w.inputType, "in"), ...collect((w) => w.outputType, "out")];
+}
+
+/** Human-readable warning for one envelope conflict, for the gen warning stream. */
+export function formatEnvelopeConflict(c: EnvelopeConflict): string {
+  return (
+    `data-envelope conflict on worker "${c.taskType}" (${c.slot}): field "${c.field}" is ` +
+    `${c.types.join(" vs ")} across envelopes ${c.envelopes.map((e) => `"${e}"`).join(", ")}. ` +
+    `The taskType's ${c.slot === "in" ? "input" : "output"} is the union of its envelopes; a ` +
+    `field must have one type across all of them. Unify the envelope or split the job type.`
+  );
+}
+
 /**
  * Overlay the model-derived worker-IO map onto the manifest `workers[]`. The model is authoritative
  * for the envelope (`inputType`/`outputType`), so every scanned `taskType` takes its I/O from

package/src/toolkit/gen.test.ts

@@ -289,3 +289,38 @@ test("runGen warns when a requestBody schema is shared across operations, but ne
   });
   assert.deepEqual((await runGen({ root: "/app", io: clean })).warnings, []);
 });
+
+test("gen fuses a model-authored nano:shape envelope into the worker-io contract", async () => {
+  // No manifest `types` at all: the envelope's shape lives ENTIRELY in the model as a `nano:shape`,
+  // linked to the worker by `io.nanobpm.dataEnvelope.in`. Before the shape fuse was wired into gen
+  // this produced an empty `WorkerInputs {}`; now it resolves to `DomainTypes["ReviewIn"]`.
+  const manifest = JSON.stringify({
+    id: "demo",
+    data: { default: "app" },
+    models: { processes: ["processes/p.bpmn"] },
+  });
+  const bpmn = `<bpmn:process id="p"
+    xmlns:bpmn="x" xmlns:zeebe="y" xmlns:nano="z">
+    <bpmn:extensionElements><nano:shapes>
+      <nano:shape id="ReviewIn" name="Review — input">
+        <nano:extend name="prUrl" type="string" />
+        <nano:extend name="round" type="integer" />
+      </nano:shape>
+    </nano:shapes></bpmn:extensionElements>
+    <bpmn:serviceTask id="T"><bpmn:extensionElements>
+      <zeebe:taskDefinition type="demo.review" />
+      <zeebe:properties>
+        <zeebe:property name="io.nanobpm.dataEnvelope.in" value="ReviewIn" />
+      </zeebe:properties>
+    </bpmn:extensionElements></bpmn:serviceTask>
+  </bpmn:process>`;
+  const io = memIO({ "/app/nano.app.json": manifest, "/app/processes/p.bpmn": bpmn });
+  const res = await runGen({ root: "/app", io });
+  const workerIo = res.artifacts.find((a) => a.path.endsWith("worker-io.d.ts"));
+  assert.ok(workerIo, "worker-io.d.ts is emitted");
+  assert.match(workerIo!.content, /"demo\.review": DomainTypes\["ReviewIn"\];/);
+  // The fused shape also lands in the domain registry the worker index imports from.
+  const domain = res.artifacts.find((a) => a.path.endsWith("domain-rows.d.ts"));
+  assert.ok(domain, "domain-rows.d.ts is emitted from the fused registry");
+  assert.match(domain!.content, /"ReviewIn":/);
+});

package/src/toolkit/gen.ts

@@ -6,10 +6,11 @@
 import type { DerivedArtifact } from "./artifact.ts";
 import { GENERATED_DIR, isAbsolutePath, RUNTIME_MATERIALIZED_ARTIFACTS, sortArtifacts } from "./artifact.ts";
 import { deriveMigrations, type ToolkitManifest } from "./derivers/migrations.ts";
-import { deriveDomain } from "./derivers/domain.ts";
-import { deriveWorkerBindings, type ModelSource } from "./derivers/worker-io.ts";
+import { emitDomainModel, registryFromManifest, sourcesFromManifest } from "./derivers/domain.ts";
+import { byModelPath, deriveWorkerBindings, detectEnvelopeConflicts, DOMAIN_DTS, formatEnvelopeConflict, type ModelSource, scanModelWorkers } from "./derivers/worker-io.ts";
 import { deriveMeta } from "./derivers/meta.ts";
 import { deriveMessageBindings } from "./derivers/messages.ts";
+import { resolveShapes, scanModelShapes } from "./derivers/shapes.ts";
 import { deriveApi } from "./derivers/api.ts";
 import { parseSpec, sharedRequestBodySchemas } from "../openapi/spec.ts";
 import { deriveModels, type DerivedModels, type ModelError, MODEL_PROVENANCE } from "./models.ts";
@@ -133,29 +134,62 @@ async function collectAll(opts: GenOptions): Promise<{ artifacts: DerivedArtifac
   const artifacts: DerivedArtifact[] = [];
   const warnings: string[] = [];
 
-  // 1. types → migrations + domain row types (DomainTables spine + DomainTypes registry)
+  // 1. Resolve the app's models first (code-first `workflows/*.ts` → BPMN, plus authored on-disk
+  //    `.bpmn`): the fused domain model (below) lifts `nano:shape` envelopes *from* the models, so
+  //    they must be in hand before the domain + worker/message type-contracts are derived.
+  const derived = await deriveModels(root, io, manifest);
+  //    The derived `.bpmn` are emitted only when `emitModels` (default), but always fed to the
+  //    type-contract derivers so worker I/O works for a code-first app even on a `--no-models` run.
+  if (emitModels) artifacts.push(...derived.artifacts);
+  const derivedPaths = new Set(derived.artifacts.map((a) => a.path));
+  const diskModels = (await readModels(root, io, manifest)).filter((m) => !derivedPaths.has(m.path));
+  const models = [...diskModels, ...derived.models];
+
+  // 2. Fused domain model (ADR 0040): the `DomainTypes` registry is the union of the manifest
+  //    `types` registry and the model-authored `nano:shape` envelopes, resolved through the same
+  //    fuse the console reifier (`envelope_scan.rs`) uses. Without this the standalone `urban gen`
+  //    would honour only `manifest.types` and silently ignore every model-authored data envelope,
+  //    so worker/message I/O against those envelopes would fall back to the untyped `WorkerVars`.
+  const manifestRegistry = registryFromManifest(manifest);
+  const sources = sourcesFromManifest(manifest);
+  const shapeDecls = models.flatMap((m) => scanModelShapes(m.xml));
+  const shapeResolution = resolveShapes(shapeDecls, manifestRegistry, sources);
+  const fusedTypes = { ...manifestRegistry, ...shapeResolution.types };
+  for (const d of shapeResolution.diagnostics) {
+    warnings.push(`data-envelope shape "${d.shape}" (${d.kind}): ${d.message}`);
+  }
+
+  // 3. types → migrations (persisted `manifest.types` only — shapes are transient wire envelopes,
+  //    never tables) + the fused domain row types (`DomainTables` spine + `DomainTypes` registry).
   if (!opts.modelsOnly && manifest.types && Object.keys(manifest.types).length > 0) {
     artifacts.push(...deriveMigrations(manifest));
-    artifacts.push(...deriveDomain(manifest));
+  }
+  if (!opts.modelsOnly && Object.keys(fusedTypes).length > 0) {
+    artifacts.push({
+      path: `${GENERATED_DIR}/${DOMAIN_DTS}`,
+      content: emitDomainModel(sources, manifest.data?.default ?? "app", fusedTypes),
+    });
   }
 
-  // 2. code-first models → derive BPMN from `workflows/*.ts` (executes the app's TS). The derived
-  //    `.bpmn` are emitted only when `emitModels` (default), but always fed to the type-contract
-  //    derivers below so worker I/O works for a code-first app even on a `--no-models` run.
-  const derived = await deriveModels(root, io, manifest);
-  if (emitModels) artifacts.push(...derived.artifacts);
-
-  // 3. models (authored on-disk + derived) → worker I/O index + meta accessor + message map.
-  //    Drop any on-disk model whose path a derived model already covers, to avoid double-counting.
+  // 4. models (authored on-disk + derived) → worker I/O index + meta accessor + message map. The
+  //    declared type ids include the fused shapes, so an envelope ref to a model-authored shape
+  //    resolves to its `DomainTypes[...]` entry instead of degrading to the untyped fallback.
   if (!opts.modelsOnly) {
-    const derivedPaths = new Set(derived.artifacts.map((a) => a.path));
-    const diskModels = (await readModels(root, io, manifest)).filter((m) => !derivedPaths.has(m.path));
-    const models = [...diskModels, ...derived.models];
     if (models.length > 0) {
-      const declaredTypeIds = Object.keys(manifest.types ?? {});
+      const declaredTypeIds = Object.keys(fusedTypes);
       artifacts.push(...deriveWorkerBindings(models, declaredTypeIds));
       artifacts.push(...deriveMeta(models));
       artifacts.push(...deriveMessageBindings(models, declaredTypeIds));
+      // Surface genuine data-envelope conflicts: a taskType whose variants disagree on a field's
+      // TYPE. The emitted contract is the union of the variants (sound for a shared handler), so a
+      // type clash would silently widen to `A | B` — warn instead so the author unifies the envelope.
+      const scannedWorkers = [...models]
+        .sort(byModelPath)
+        .flatMap((m) => scanModelWorkers(m.xml))
+        .map((w) => ({ taskType: w.taskType, inputType: w.in, outputType: w.out }));
+      for (const c of detectEnvelopeConflicts(scannedWorkers, fusedTypes)) {
+        warnings.push(formatEnvelopeConflict(c));
+      }
     }
   }