@nanobpm/urban 0.47.0 → 0.49.0

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/fsio.ts

@@ -25,6 +25,14 @@ export function createNodeGenIO(): GenIO {
         return [];
       }
     },
+    async listSubdirs(path: string): Promise<string[]> {
+      try {
+        const entries = await readdir(path, { withFileTypes: true });
+        return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+      } catch {
+        return [];
+      }
+    },
     async exists(path: string): Promise<boolean> {
       try {
         await stat(path);

package/src/toolkit/gen.test.ts

@@ -1,6 +1,6 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { runGen, collectArtifacts, type GenIO } from "./gen.ts";
+import { runGen, collectArtifacts, readModels, type GenIO } from "./gen.ts";
 import { defineFlow, envelope } from "@nanobpm/workflow";
 import { MODEL_PROVENANCE } from "./models.ts";
 
@@ -29,6 +29,18 @@ function memIO(
       }
       return [...names];
     },
+    async listSubdirs(p) {
+      const prefix = p.replace(/\/+$/, "") + "/";
+      const names = new Set<string>();
+      for (const f of Object.keys(files)) {
+        if (f.startsWith(prefix)) {
+          const rest = f.slice(prefix.length);
+          const slash = rest.indexOf("/");
+          if (slash > 0) names.add(rest.slice(0, slash));
+        }
+      }
+      return [...names];
+    },
     async exists(p) {
       return p in files;
     },
@@ -181,11 +193,11 @@ function codeFirstIO() {
   );
 }
 
-test("runGen derives processes/<id>.bpmn from workflows/*.ts and feeds worker-io off it", async () => {
+test("runGen derives resources/processes/<id>.bpmn from workflows/*.ts and feeds worker-io off it", async () => {
   const io = codeFirstIO();
   const res = await runGen({ root: "/cf", io });
-  const bpmn = io.files["/cf/processes/greet.bpmn"];
-  assert.ok(bpmn, "expected a derived processes/greet.bpmn");
+  const bpmn = io.files["/cf/resources/processes/greet.bpmn"];
+  assert.ok(bpmn, "expected a derived resources/processes/greet.bpmn");
   assert.ok(bpmn.includes(MODEL_PROVENANCE), "derived .bpmn must be provenance-stamped");
   assert.ok(bpmn.includes('type="greet:hello"'), "derived .bpmn carries the task type");
   // worker-io is derived FROM the in-memory model, not from any on-disk file.
@@ -197,7 +209,7 @@ test("runGen derives processes/<id>.bpmn from workflows/*.ts and feeds worker-io
 test("gen --no-models derives in-memory for worker-io but writes no .bpmn", async () => {
   const io = codeFirstIO();
   const res = await runGen({ root: "/cf", io, emitModels: false });
-  assert.equal(io.files["/cf/processes/greet.bpmn"], undefined, "must not write .bpmn");
+  assert.equal(io.files["/cf/resources/processes/greet.bpmn"], undefined, "must not write .bpmn");
   // still derives the model in-memory so worker-io is populated.
   assert.ok(io.files["/cf/nano-generated/worker-io.d.ts"].includes("greet:hello"));
   assert.equal(res.incomplete, false);
@@ -206,17 +218,17 @@ test("gen --no-models derives in-memory for worker-io but writes no .bpmn", asyn
 test("the provenance sweep removes a stale derived .bpmn no longer backed by a workflow", async () => {
   const io = codeFirstIO();
   // a leftover derived model from a since-deleted flow, provenance-stamped.
-  io.files["/cf/processes/stale.bpmn"] = `<?xml version="1.0"?>\n${MODEL_PROVENANCE}\n<bpmn:x/>`;
+  io.files["/cf/resources/processes/stale.bpmn"] = `<?xml version="1.0"?>\n${MODEL_PROVENANCE}\n<bpmn:x/>`;
   await runGen({ root: "/cf", io });
-  assert.ok(io.files["/cf/processes/greet.bpmn"], "keeps the live derived model");
-  assert.equal(io.files["/cf/processes/stale.bpmn"], undefined, "sweeps the stale derived model");
+  assert.ok(io.files["/cf/resources/processes/greet.bpmn"], "keeps the live derived model");
+  assert.equal(io.files["/cf/resources/processes/stale.bpmn"], undefined, "sweeps the stale derived model");
 });
 
 test("the sweep never touches an authored (un-stamped) .bpmn", async () => {
   const io = codeFirstIO();
-  io.files["/cf/processes/authored.bpmn"] = `<?xml version="1.0"?>\n<bpmn:authored/>`;
+  io.files["/cf/resources/processes/authored.bpmn"] = `<?xml version="1.0"?>\n<bpmn:authored/>`;
   await runGen({ root: "/cf", io });
-  assert.ok(io.files["/cf/processes/authored.bpmn"], "authored .bpmn must survive the sweep");
+  assert.ok(io.files["/cf/resources/processes/authored.bpmn"], "authored .bpmn must survive the sweep");
 });
 
 test("collectArtifacts trims api.spec whitespace so gen matches the runtime (no gen/runtime drift)", async () => {
@@ -289,3 +301,62 @@ 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":/);
+});
+
+// Guards the gen/runtime drift class: gen's readModels must key the `resources/` convention off the
+// *absence* of the whole `models` block (mirroring the runtime deploy, ADR 0062), NOT off a missing
+// `models.processes`. A `models` block present for other overrides (e.g. forms) must suppress the
+// convention scan, so gen never derives process models the runtime deploy would never deploy.
+test("readModels: a models block without processes suppresses the resources/ convention (no gen/runtime drift)", async () => {
+  const io = memIO({
+    "/app/resources/a.bpmn": "<bpmn:definitions/>",
+    "/app/resources/sub/b.bpmn": "<bpmn:definitions/>",
+  });
+  // No models block at all → convention scans resources/ (shallow, one level deep).
+  const byConvention = await readModels("/app", io, {});
+  assert.deepEqual(
+    byConvention.map((m) => m.path).sort(),
+    ["resources/a.bpmn", "resources/sub/b.bpmn"],
+    "with no models block, gen discovers under resources/ by convention",
+  );
+  // A declared models block (even one that resolves to zero process files) is an explicit override:
+  // the convention scan must be skipped entirely, matching runtime deployModels.
+  const withEmptyModels = await readModels("/app", io, { models: {} });
+  assert.deepEqual(withEmptyModels, [], "a declared models block suppresses the resources/ convention");
+  const withOnlyProcesses = await readModels("/app", io, { models: { processes: [] } });
+  assert.deepEqual(withOnlyProcesses, [], "an explicitly empty models.processes yields no models, not a convention fallback");
+});