@nanobpm/urban 0.46.0 → 0.48.0

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 () => {
@@ -502,6 +527,48 @@ test("the renderer honours boolean (checkbox) actionForm fields", async () => {
   assert.match(js, /input\.checked = input\.defaultChecked;/);
 });
 
+test("the renderer enforces required actionForm fields client-side, blocking submit with an inline hint", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // A field declared `required: true` is tracked in a Set and given an inline
+  // error node; the label carries a danger-toned "*" marker before submit.
+  assert.match(js, /required\.add\(f\.key\)/);
+  assert.match(js, /reqMark = \(f\) =>/);
+  assert.match(js, /class: "pc-req"/);
+  // The input is marked aria-required, and a clear-on-edit handler wipes the hint
+  // the moment the user starts fixing the field (input for text/number, change for
+  // a checkbox).
+  assert.match(js, /input\.setAttribute\("aria-required", "true"\)/);
+  assert.match(js, /wireField\(f, input, ferr, "input"\)/);
+  assert.match(js, /wireField\(f, input, ferr, "change"\)/);
+  // Submit is GATED: an empty required text/number or an unchecked required
+  // checkbox is "missing"; the first offender is focused and the submit RETURNS
+  // early (never round-trips to the server).
+  assert.match(js, /input\.checked !== true/);
+  assert.match(js, /!Number\.isFinite\(Number\(val\)\)/);
+  assert.match(js, /if \(firstInvalid\)/);
+  assert.match(js, /Please fill in the required fields\./);
+  assert.match(js, /firstInvalid\.focus\(\)/);
+  assert.match(js, /input\.classList\.add\("pc-invalid"\)/);
+  // Editing a required field after a blocked submit clears the summary banner too,
+  // so "Please fill in the required fields." never lingers stale while correcting.
+  assert.match(js, /msg\.textContent = "";\s*\n\s*msg\.className = "pc-msg";/);
+  // A per-field custom message (`requiredMessage`) overrides the default "Required".
+  assert.match(js, /reqMsg\.get\(k\) \|\| "Required"/);
+  assert.match(js, /f\.requiredMessage/);
+});
+
+test("the shell styles required-field markers and inline field errors", async () => {
+  const res = await dispatch("GET", "/");
+  const html = res.body ?? "";
+  // The "*" required marker and the inline per-field error both resolve through
+  // the shared danger token, and an empty error node collapses (no reserved gap).
+  assert.match(html, /\.pc-req \{ color:var\(--nano-danger\)/);
+  assert.match(html, /\.pc-field-err \{ font-size:.75rem; color:var\(--nano-danger\)/);
+  assert.match(html, /\.pc-field-err:empty \{ display:none; \}/);
+  assert.match(html, /input\.pc-invalid/);
+});
+
 test("renderer makes collapsible nodes persist their state across sessions", async () => {
   // A node with `collapsible` gets a clickable header that hides/shows the card
   // body, and the collapsed state is written to localStorage keyed by the home

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

@@ -533,6 +533,10 @@ body { margin:0; font:15px/1.5 system-ui,sans-serif; padding:2rem; max-width:64r
 .pc-msg { font-size:.85rem; margin-top:.5rem; min-height:1.2em; }
 .pc-msg.err { color:var(--nano-danger); }
 .pc-msg.ok { color:var(--nano-ok); }
+.pc-req { color:var(--nano-danger); font-weight:600; }
+.pc-field-err { font-size:.75rem; color:var(--nano-danger); margin:.1rem 0 0; }
+.pc-field-err:empty { display:none; }
+.pc-field input.pc-invalid, .pc-field-check input.pc-invalid { border-color:var(--nano-danger); outline-color:var(--nano-danger); }
 table.pc-grid { width:100%; border-collapse:collapse; font-size:.9rem; table-layout:fixed; }
 /* table-layout:fixed divides the available width across columns and wraps text
    within each, so a grid with several long free-text columns (e.g. the epic
@@ -834,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";
@@ -998,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;
@@ -1011,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) {
@@ -1083,9 +1127,38 @@ function renderActionForm(node) {
   // pollute Object.prototype or shadow inherited props (prototype-pollution class).
   const inputs = new Map();
   const fieldTypes = new Map();
+  // Client-side required-field validation state: the set of required keys, each
+  // field's custom message, and its inline error node (populated on a blocked
+  // submit, cleared as soon as the user edits the field).
+  const required = new Set();
+  const reqMsg = new Map();
+  const errs = new Map();
+  // A required field's label carries a danger-toned "*" so the requirement is
+  // visible BEFORE submit; spread into el(...) — an empty array adds no child.
+  const reqMark = (f) => (f.required === true ? [el("span", { class: "pc-req", title: "Required" }, " *")] : []);
+  // Register a field's inline error node and, when required, mark the input
+  // (aria-required) and wire a clear-on-edit handler so a hint disappears the
+  // moment the user starts fixing it. Editing a required field also clears the
+  // blocked-submit summary ("Please fill in the required fields.") so it never
+  // lingers as a stale/misleading banner while the user is correcting input.
+  const wireField = (f, input, ferr, evt) => {
+    errs.set(f.key, ferr);
+    if (f.required !== true) return;
+    required.add(f.key);
+    if (typeof f.requiredMessage === "string" && f.requiredMessage !== "") reqMsg.set(f.key, f.requiredMessage);
+    input.setAttribute("aria-required", "true");
+    input.addEventListener(evt, () => {
+      input.classList.remove("pc-invalid");
+      input.removeAttribute("aria-invalid");
+      ferr.textContent = "";
+      msg.textContent = "";
+      msg.className = "pc-msg";
+    });
+  };
   for (const f of p.fields || []) {
     const kind = f.type === "checkbox" ? "checkbox" : (f.type === "number" ? "number" : "text");
     fieldTypes.set(f.key, kind);
+    const ferr = el("p", { class: "pc-field-err" });
     if (kind === "checkbox") {
       // A boolean field renders a real checkbox; its default checked state comes
       // from default/checked on the field (unset -> unchecked). We record that on
@@ -1096,9 +1169,10 @@ function renderActionForm(node) {
       input.defaultChecked = checked;
       input.checked = checked;
       inputs.set(f.key, input);
+      wireField(f, input, ferr, "change");
       // Input-first, wrapped in the label so the whole row is a click target.
       card.append(
-        el("div", { class: "pc-field pc-field-check" }, el("label", {}, input, " " + (f.label || f.key))),
+        el("div", { class: "pc-field pc-field-check" }, el("label", {}, input, " " + (f.label || f.key), ...reqMark(f)), ferr),
       );
       continue;
     }
@@ -1111,11 +1185,43 @@ function renderActionForm(node) {
     }
     const input = el("input", attrs);
     inputs.set(f.key, input);
-    card.append(el("div", { class: "pc-field" }, el("label", {}, f.label || f.key), input));
+    wireField(f, input, ferr, "input");
+    card.append(el("div", { class: "pc-field" }, el("label", {}, f.label || f.key, ...reqMark(f)), input, ferr));
   }
   const msg = el("p", { class: "pc-msg" });
   const btn = el("button", { class: "pc-btn" }, p.submitLabel || "Submit");
   btn.addEventListener("click", async () => {
+    // Required-field gate: block the submit and surface an inline hint on each
+    // empty required field (a text/number left blank, a required checkbox left
+    // unchecked), focusing the first offender — so a missing value never
+    // round-trips to the server only to bounce back as a generic error.
+    let firstInvalid = null;
+    for (const [k, input] of inputs) {
+      const ferr = errs.get(k);
+      if (ferr) ferr.textContent = "";
+      input.classList.remove("pc-invalid");
+      input.removeAttribute("aria-invalid");
+      if (!required.has(k)) continue;
+      const type = fieldTypes.get(k);
+      const val = String(input.value).trim();
+      const missing = type === "checkbox"
+        ? input.checked !== true
+        : type === "number"
+          ? (val === "" || !Number.isFinite(Number(val)))
+          : val === "";
+      if (missing) {
+        if (ferr) ferr.textContent = reqMsg.get(k) || "Required";
+        input.classList.add("pc-invalid");
+        input.setAttribute("aria-invalid", "true");
+        if (!firstInvalid) firstInvalid = input;
+      }
+    }
+    if (firstInvalid) {
+      msg.className = "pc-msg err";
+      msg.textContent = "Please fill in the required fields.";
+      firstInvalid.focus();
+      return;
+    }
     const variables = Object.create(null);
     for (const [k, input] of inputs) {
       if (fieldTypes.get(k) === "checkbox") {

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"]);