@nanobpm/urban 0.46.0 → 0.48.0

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