@nanobpm/urban 0.47.0 → 0.49.0

package/dist/runtime/core/runtime.js

@@ -2,7 +2,7 @@
 // materializes the app by mounting each module. Hosts (CLI/IDE/console/bare process) call
 // this the same way; a host may mount a subset via `mount` flags (e.g. the console mounts
 // its own surfaces but reuses deploy + workers + datasource).
-import { loadManifest } from "./manifest.js";
+import { loadManifest, resolveBindMode, bindModeToHost } from "./manifest.js";
 import { validateManifest } from "./validate.js";
 import { makeRouter } from "./router.js";
 import { deployModels } from "./modules/deploy.js";
@@ -48,7 +48,7 @@ export async function createUrbanApp(opts) {
         security: opts.mount?.security ?? true,
         instanceTracking: opts.mount?.instanceTracking ?? true,
     };
-    const ctx = { manifest, host, engine, root, templates: opts.templates };
+    const ctx = { manifest, host, engine, root };
     // One app-level structured logger over the host sink, shared by the entrypoint (exposed as
     // `app.log`) and the per-invocation `AppApi.log` (workers/route delegates `child()` it with their
     // correlation context).
@@ -65,6 +65,12 @@ export async function createUrbanApp(opts) {
     let started = false;
     let httpPort;
     const port = resolvePort(opts.port, host.env("PORT"));
+    // Which interface the HTTP server binds to (issue #235). Secure by default: loopback unless
+    // the manifest's `network.bind` (or the `URBAN_BIND` env override) opts into all interfaces.
+    // Derive the host address from the already-resolved mode so the two can never diverge (and we
+    // consult the env exactly once) — a second `resolveBindHost` call would re-read the override.
+    const bindMode = resolveBindMode(manifest, (n) => host.env(n));
+    const bindHost = bindModeToHost(bindMode);
     // Release every mounted resource and reset internal state so a subsequent
     // start() begins clean. Used by stop() and by start()'s failure path.
     const teardown = async () => {
@@ -181,9 +187,26 @@ export async function createUrbanApp(opts) {
                             body: JSON.stringify({ ok: true, app: manifest.id }),
                         }),
                     });
-                    server = await host.serveHttp(port, makeRouter(routes));
+                    server = await host.serveHttp(port, makeRouter(routes), bindHost);
                     httpPort = server.port;
-                    host.log("info", "urban app serving surfaces/triggers", { port: httpPort, routes: routes.length });
+                    host.log("info", "urban app serving surfaces/triggers", {
+                        port: httpPort,
+                        routes: routes.length,
+                        bind: bindMode,
+                        bindHost,
+                    });
+                    // Binding to all interfaces exposes the app (and its token-gated capability
+                    // hooks) on the LAN. That is the explicit opt-in this setting exists for, but a
+                    // non-loopback bind must not serve any LOCAL-mode "well-known localhost token"
+                    // credential (issue #235) — consumers that mint one (e.g. the agentic channel's
+                    // LOCAL mode) must gate it on a loopback bind. Surface the exposure so it is never
+                    // silent.
+                    if (bindMode === "all") {
+                        host.log("warn", "urban app bound to all interfaces — reachable off-box on the LAN", {
+                            port: httpPort,
+                            bindHost,
+                        });
+                    }
                     // ADR 0057 boot handshake: under a supervising host (the nano-bpm
                     // Studio sets NANOBPMN_APP_HANDSHAKE), announce the port we actually
                     // bound on a machine-readable stdout control line so the host can

package/dist/runtime/core/validate.js

@@ -9,6 +9,7 @@
 // silently — the whole point of consuming the package rather than vendoring a copy.
 import schema from "@nanobpm/nano-app-schema/schema" with { type: "json" };
 import { isRecord } from "./guards.js";
+import { BIND_MODES, NETWORK_KEYS, isBindMode, isConfiguredStatusSelector } from "./manifest.js";
 export class ManifestValidationError extends Error {
     issues;
     constructor(issues) {
@@ -32,6 +33,13 @@ export function collectManifestIssues(m) {
             issues.push({ path: req, message: "required by nano-app.schema.json" });
     }
     const allowed = new Set(Object.keys(S.properties ?? {}));
+    // `network` (issue #235) is threaded as a runtime-side setting until
+    // @nanobpm/nano-app-schema ships the field in its JSON Schema; allow it here so the
+    // envelope check doesn't reject it. Remove this once the schema owns `network` (it
+    // then flows from `S.properties` like every other block). The matching local type
+    // (NetworkConfig) lives in manifest.ts — mirrored like the `api` binding (ADR 0058),
+    // never via a `declare module` augmentation (CI bans augmenting the schema type).
+    allowed.add("network");
     if (S.additionalProperties === false) {
         for (const k of Object.keys(obj)) {
             if (!allowed.has(k)) {
@@ -39,6 +47,28 @@ export function collectManifestIssues(m) {
             }
         }
     }
+    if ("network" in obj) {
+        const network = isRecord(obj.network) ? obj.network : undefined;
+        if (!network) {
+            issues.push({ path: "network", message: "must be an object" });
+        }
+        else {
+            if ("bind" in network && !isBindMode(network.bind)) {
+                issues.push({
+                    path: "network.bind",
+                    message: `must be one of: ${BIND_MODES.map((mode) => `"${mode}"`).join(", ")}`,
+                });
+            }
+            // `network` is mirrored runtime-side until the schema owns it, so this is its only
+            // validation surface: mirror the schema's `additionalProperties: false` intent and
+            // reject unknown keys so typos (e.g. `binn`) fail loudly instead of silently no-op'ing.
+            for (const k of Object.keys(network)) {
+                if (!NETWORK_KEYS.some((known) => known === k)) {
+                    issues.push({ path: `network.${k}`, message: "unknown key (network additionalProperties: false)" });
+                }
+            }
+        }
+    }
     if ("schemaVersion" in obj && obj.schemaVersion !== 1) {
         issues.push({ path: "schemaVersion", message: "must be 1" });
     }
@@ -153,12 +183,46 @@ export function collectManifestIssues(m) {
                     message: "missing onTerminated.set patch (a non-empty column → value map)",
                 });
             }
-            if (Array.isArray(b?.activeStatuses) && (typeof b?.statusField !== "string" || b.statusField.length === 0)) {
+            // `activeStatuses` (fail-closed allow-list) and `terminalStatuses` (fail-open exclusion) are
+            // both consumed as arrays of status strings. A malformed value — a bare string, or an array
+            // holding a non-string/empty entry — would misbehave at runtime (`new Set("abandoned")`
+            // becomes a set of characters; `activeStatuses.map(...)` crashes), so reject any non-`unset`
+            // shape that isn't a non-empty array of non-empty strings. An empty array is treated as
+            // "unset" (the runtime's `isConfiguredStatusSelector` gate does the same), so it is allowed.
+            for (const sel of ["activeStatuses", "terminalStatuses"]) {
+                const v = b?.[sel];
+                const malformed = v !== undefined &&
+                    (!Array.isArray(v) || v.some((s) => typeof s !== "string" || s.length === 0));
+                if (malformed) {
+                    issues.push({
+                        path: `instanceTracking[${i}].${sel}`,
+                        message: `${sel} must be an array of non-empty strings`,
+                    });
+                }
+            }
+            if (isConfiguredStatusSelector(b?.activeStatuses) && (typeof b?.statusField !== "string" || b.statusField.length === 0)) {
                 issues.push({
                     path: `instanceTracking[${i}].activeStatuses`,
                     message: "activeStatuses requires statusField",
                 });
             }
+            // `terminalStatuses` is the fail-open exclusion selector (poll every row NOT in one of
+            // these). Like `activeStatuses` it reads `statusField`, so it too requires one; and the two
+            // selectors are mutually exclusive — declaring both is ambiguous, so reject it.
+            if (isConfiguredStatusSelector(b?.terminalStatuses) && (typeof b?.statusField !== "string" || b.statusField.length === 0)) {
+                issues.push({
+                    path: `instanceTracking[${i}].terminalStatuses`,
+                    message: "terminalStatuses requires statusField",
+                });
+            }
+            // Mutual exclusion is gated on the same "configured" predicate the runtime uses, so an empty
+            // array (which the runtime treats as unset) does not spuriously trip the both-declared error.
+            if (isConfiguredStatusSelector(b?.activeStatuses) && isConfiguredStatusSelector(b?.terminalStatuses)) {
+                issues.push({
+                    path: `instanceTracking[${i}].terminalStatuses`,
+                    message: "activeStatuses and terminalStatuses are mutually exclusive; declare only one",
+                });
+            }
             // `pollMs`, when set, schedules a self-rescheduling timer; a non-number/NaN/non-positive
             // value would become a 0-delay hot loop at runtime, so reject it at author time.
             if (b?.pollMs !== undefined && (typeof b.pollMs !== "number" || !Number.isFinite(b.pollMs) || b.pollMs <= 0)) {

package/dist/runtime/engine/nanosdk.d.ts

@@ -1,4 +1,4 @@
-import type { EngineClient, JobHandler, ProcessInstanceSnapshot, ProcessInstanceState, WorkerSubscription } from "../core/host.ts";
+import type { EngineClient, FormSchema, JobHandler, ProcessInstanceSnapshot, ProcessInstanceState, UserTaskSummary, WorkerSubscription } from "../core/host.ts";
 import type { EngineSdkClient } from "./sdk.ts";
 /** Coerce an engine response's process-instance key to a non-empty string, or
  * throw — a missing key means a malformed/partial response, not a real instance. */
@@ -81,6 +81,9 @@ export interface NanoSdkClient {
         userTaskKey: string;
         variables?: Record<string, unknown>;
     }, options?: unknown): Promise<unknown>;
+    getFormByKey(input: {
+        formKey: string;
+    }, consistency?: unknown, options?: unknown): Promise<Record<string, unknown>>;
     searchProcessInstances(input: {
         filter?: Record<string, unknown>;
         page?: Record<string, unknown>;
@@ -137,11 +140,11 @@ export declare class SdkEngineClient implements EngineClient {
         processInstanceKey?: string;
         assignee?: string;
         candidateGroup?: string;
-    }): Promise<{
-        userTaskKey: string;
-        elementId?: string;
-        variables?: Record<string, unknown>;
-    }[]>;
+    }): Promise<UserTaskSummary[]>;
+    getForm(input: {
+        formKey?: string;
+        formId?: string;
+    }): Promise<FormSchema | null>;
     completeUserTask(userTaskKey: string, variables?: Record<string, unknown>): Promise<void>;
     searchProcessInstances(filter?: {
         processInstanceKeys?: string[];

package/dist/runtime/engine/nanosdk.js

@@ -18,7 +18,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
-import { isBpmnError } from "../core/host.js";
+import { isBpmnError, presentFormIdentifier } from "../core/host.js";
 import { isRecord } from "../core/guards.js";
 /** Coerce an engine response's process-instance key to a non-empty string, or
  * throw — a missing key means a malformed/partial response, not a real instance. */
@@ -109,13 +109,77 @@ export class SdkEngineClient {
                 this.log("warn", "skipping user task with no key in engine response");
                 return [];
             }
+            // The engine resolves a `formId="X"` linkage to the latest deployed form's key at
+            // task creation, so `formKey` (not a form id) is the linkage it reports on the task.
+            const formKey = it.formKey != null && it.formKey !== "" ? String(it.formKey) : undefined;
+            const externalFormReference = typeof it.externalFormReference === "string" && it.externalFormReference !== ""
+                ? it.externalFormReference
+                : undefined;
             return [{
                     userTaskKey: String(userTaskKey),
                     elementId: typeof it.elementId === "string" ? it.elementId : undefined,
                     variables: isRecord(it.variables) ? it.variables : undefined,
+                    ...(formKey ? { formKey } : {}),
+                    ...(externalFormReference ? { externalFormReference } : {}),
                 }];
         });
     }
+    async getForm(input) {
+        // The engine addresses deployed forms by key (`GET /forms/{formKey}`). A user task's
+        // `formKey` is the engine's resolution of its `formId` linkage to the latest deployed
+        // form, so callers pass that key. `formId` is accepted as a fallback identifier for
+        // engines that address a form by its id; either way the engine returns the current
+        // form or 404s (→ null) when there is no such form.
+        //
+        // This is the single gate that resolves which identifier addresses the form: an
+        // empty/whitespace identifier is treated as *absent* (via `presentFormIdentifier`, the
+        // shared presence rule) so a blank `formKey` (e.g. a `?formKey=` query param) falls
+        // through to a valid `formId` instead of being taken as a present-but-unresolvable key
+        // that short-circuits to null.
+        const key = presentFormIdentifier(input.formKey) ?? presentFormIdentifier(input.formId);
+        if (key == null)
+            return null;
+        let body;
+        try {
+            body = await this.client.getFormByKey({ formKey: key }, { consistency: { waitUpToMs: 0 } });
+        }
+        catch (err) {
+            this.log("warn", "getForm: engine form fetch failed", {
+                key,
+                formKey: input.formKey,
+                formId: input.formId,
+                err: err instanceof Error ? err.message : String(err),
+            });
+            return null;
+        }
+        if (!isRecord(body))
+            return null;
+        const rawSchema = body.schema;
+        // The engine serializes the form-js schema as a JSON string; parse it to the object
+        // the surface renders. Tolerate an already-parsed object (an in-memory/embedded engine).
+        let schema;
+        if (typeof rawSchema === "string") {
+            try {
+                const parsed = JSON.parse(rawSchema);
+                if (isRecord(parsed))
+                    schema = parsed;
+            }
+            catch {
+                this.log("warn", "getForm: form schema is not valid JSON", { key, formKey: input.formKey, formId: input.formId });
+            }
+        }
+        else if (isRecord(rawSchema)) {
+            schema = rawSchema;
+        }
+        if (!schema)
+            return null;
+        return {
+            schema,
+            ...(body.formKey != null && body.formKey !== "" ? { formKey: String(body.formKey) } : {}),
+            ...(typeof body.formId === "string" && body.formId !== "" ? { formId: body.formId } : {}),
+            ...(typeof body.version === "number" ? { version: body.version } : {}),
+        };
+    }
     async completeUserTask(userTaskKey, variables) {
         await this.client.completeUserTask({ userTaskKey, variables: variables ?? {} });
     }

package/dist/runtime/index.d.ts

@@ -1,7 +1,7 @@
 export { createUrbanApp } from "./core/runtime.ts";
 export type { CreateUrbanAppOptions, MountFlags, UrbanApp, } from "./core/runtime.ts";
-export { expandEnv, expandEnvString, loadManifest, parseManifest, workerJobType, } from "./core/manifest.ts";
-export type { ActionDecl, AppManifest, ChatSurface, DataSource, DomainField, DomainType, LlmBinding, PagesSurface, Surfaces, TaskInboxSurface, Trigger, Worker, } from "./core/manifest.ts";
+export { bindModeToHost, expandEnv, expandEnvString, isBindMode, loadManifest, parseManifest, resolveBindHost, resolveBindMode, workerJobType, ALL_INTERFACES_HOST, BIND_ENV_VAR, LOOPBACK_HOST, } from "./core/manifest.ts";
+export type { ActionDecl, AppManifest, BindMode, ChatSurface, DataSource, DomainField, DomainType, LlmBinding, NetworkConfig, PagesSurface, Surfaces, TaskInboxSurface, Trigger, Worker, } from "./core/manifest.ts";
 export { collectManifestIssues, ManifestValidationError, validateManifest, } from "./core/validate.ts";
 export type { ValidationIssue } from "./core/validate.ts";
 export type { EngineClient, EngineJob, HostContext, HttpHandler, HttpRequest, HttpResponse, HttpServer, JobHandler, SqliteDb, WatchHandle, WorkerSubscription, } from "./core/host.ts";
@@ -30,9 +30,7 @@ export { resolveHandler, sdkDecisionEvaluator } from "./core/modules/workers.ts"
 export { buildMessages, callLlm, resolveProvider, runLlmJob, } from "./core/modules/llm.ts";
 export type { ChatMessage, DecisionEvaluator, EnvLookup, LlmRuntime, LlmVars, ProviderConfig, } from "./core/modules/llm.ts";
 export { evalCorrelation } from "./core/modules/triggers.ts";
-export { deployModels } from "./core/modules/deploy.ts";
-export { applyTemplates, resolveTemplates } from "./core/modules/templates.ts";
-export type { TemplateApplication, TemplateSource } from "./core/modules/templates.ts";
+export { deployModels, RESOURCES_DIR } from "./core/modules/deploy.ts";
 export { defaultScheduler, MAX_TIMER_DELAY_MS } from "./core/modules/scheduler.ts";
 export type { SchedulerDeps } from "./core/modules/scheduler.ts";
 export { createNodeHost } from "./adapters/node.ts";

package/dist/runtime/index.js

@@ -2,7 +2,7 @@
 // Core runtime
 export { createUrbanApp } from "./core/runtime.js";
 // Manifest
-export { expandEnv, expandEnvString, loadManifest, parseManifest, workerJobType, } from "./core/manifest.js";
+export { bindModeToHost, expandEnv, expandEnvString, isBindMode, loadManifest, parseManifest, resolveBindHost, resolveBindMode, workerJobType, ALL_INTERFACES_HOST, BIND_ENV_VAR, LOOPBACK_HOST, } from "./core/manifest.js";
 // Validation
 export { collectManifestIssues, ManifestValidationError, validateManifest, } from "./core/validate.js";
 // Structured logging surface (see core/logger.ts): the shape of `AppApi.log`, plus `createLogger`
@@ -24,9 +24,8 @@ export { defineOperation, mountApi, resolveOperationHandler, NotImplemented } fr
 export { resolveHandler, sdkDecisionEvaluator } from "./core/modules/workers.js";
 export { buildMessages, callLlm, resolveProvider, runLlmJob, } from "./core/modules/llm.js";
 export { evalCorrelation } from "./core/modules/triggers.js";
-// Model deploy + `{{name}}` template substitution
-export { deployModels } from "./core/modules/deploy.js";
-export { applyTemplates, resolveTemplates } from "./core/modules/templates.js";
+// Model deploy (deploy-by-convention under `resources/`, ADR 0062)
+export { deployModels, RESOURCES_DIR } from "./core/modules/deploy.js";
 export { defaultScheduler, MAX_TIMER_DELAY_MS } from "./core/modules/scheduler.js";
 // Adapters + engine + run entrypoint
 export { createNodeHost } from "./adapters/node.js";

package/dist/runtime/run.js

@@ -27,7 +27,6 @@ export async function runFromEnv(opts = {}) {
         manifestPath: opts.manifestPath,
         port: opts.port,
         mount: opts.mount,
-        templates: opts.templates,
     });
     await app.start();
     if (opts.handleSignals !== false)

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

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