@nanobpm/urban 0.25.0 → 0.26.0

package/dist/toolkit/derivers/shapes.js

@@ -0,0 +1,498 @@
+// Composed motion shapes: the fuse composition algebra (ADR 0040 §9/§10).
+//
+// A composed shape is a named, model-scoped declaration authored in the Modeller and carried in
+// the `.bpmn` as a `nano:shape` (see the Rust scan `envelope_scan.rs`). It composes existing fused
+// entities — DB tables, manifest `types`, and other shapes — via four ordered operations:
+//
+//   carry(ref)                 spread every field of `ref`
+//   project(ref, fields, via)  spread only the named fields of `ref`
+//   extend(name, type, ...)    add a process-authored field
+//   reference(name, ref, ...)  nest (or spread) another shape
+//
+// Resolution folds the ops, in author (XML) order, into a flat `DomainTypeDef`, so a composed
+// shape enters the same `DomainTypes` registry a manifest `type` does — every downstream consumer
+// (envelope pickers, `defineWorker`, `publishMessage`, FEEL scopes) types against
+// `DomainTypes["ApprovedOrder"]` with no new codegen path. Broken shapes are omitted (degrade to
+// untyped) and reported as diagnostics.
+//
+// Byte-faithful port of the console's `resolveShapes`/`emitDomainModelJson` (server
+// `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";
+/** 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`
+ * like any declared field; affinities with no keyword (BLOB/opaque) fall back to `json`. */
+export function columnToField(col) {
+    const ts = sqliteAffinityToTs(col.type);
+    const keyword = ts === "string" || ts === "number" || ts === "boolean" ? ts : "json";
+    const nullable = !(col.notNull || col.primaryKey);
+    return nullable ? { type: keyword, optional: true } : { type: keyword };
+}
+/** Build the leaf entity index the shape fold resolves references against: every datasource table
+ * (by raw wire name, and by `source.table` to disambiguate a name shared across sources) and every
+ * manifest `type` (by id). A raw table name shared across sources keeps the first
+ * (default-source-first) binding; the qualified `source.table` alias is always unambiguous.
+ *
+ * When a manifest `type` id collides with a bare table name, the **type wins** the unqualified id
+ * (it is the more first-class, `DomainTypes`-visible entity) and the collision is surfaced via
+ * `ambiguousIds` so resolution can warn; the table stays reachable through its `source.table`
+ * alias. `tableIds` records every id (bare + qualified) that resolves to a DB table, so a nominal
+ * reference (which the emitter can only express against `DomainTypes` keys) can be rejected. */
+function leafEntityIndex(sources, types) {
+    const index = new Map();
+    const tableIds = new Set();
+    for (const s of sources) {
+        for (const t of s.tables) {
+            const fields = {};
+            const fks = {};
+            for (const c of t.columns)
+                fields[c.name] = columnToField(c);
+            // Store FK targets as the unambiguous `source.table` id (FKs are intra-source) so `via`-path
+            // following resolves the intended table, never a same-named table in another source or a
+            // type-preferred bare id.
+            for (const fk of t.foreignKeys ?? [])
+                fks[fk.column] = `${s.source}.${fk.refTable}`;
+            const entity = { fields, fks };
+            index.set(`${s.source}.${t.name}`, entity);
+            tableIds.add(`${s.source}.${t.name}`);
+            if (!index.has(t.name)) {
+                index.set(t.name, entity);
+                tableIds.add(t.name);
+            }
+        }
+    }
+    const ambiguousIds = new Set();
+    for (const [id, def] of Object.entries(types)) {
+        // The manifest type wins an unqualified id that also names a table; the table remains
+        // reachable by its `source.table` alias.
+        if (tableIds.has(id))
+            ambiguousIds.add(id);
+        index.set(id, { fields: { ...def.fields } });
+    }
+    return { index, tableIds, ambiguousIds };
+}
+/** The shape ids a shape references (carry/project/reference targets, and an `extend` whose type
+ * names a shape) — the edges of the shape dependency graph. */
+function referencedShapeIds(shape, shapeIds) {
+    const refs = new Set();
+    for (const op of shape.ops) {
+        if (op.op === "carry" || op.op === "project" || op.op === "reference") {
+            if (shapeIds.has(op.ref))
+                refs.add(op.ref);
+        }
+        else if (op.op === "extend" && shapeIds.has(op.type)) {
+            refs.add(op.type);
+        }
+    }
+    return [...refs];
+}
+/** Structural equality of two domain field defs (`type` + normalized optional/list flags), so a
+ * differing property insertion order does not read as a conflict. */
+function sameFieldDef(a, b) {
+    return a.type === b.type && !!a.optional === !!b.optional && !!a.list === !!b.list;
+}
+/**
+ * Resolve the project's composed shapes into `DomainTypeDef`s and diagnostics (ADR 0040 §10).
+ * Leaves (DB tables, manifest types) fuse first; shapes resolve in dependency order so a shape can
+ * carry another shape regardless of declaration order. A shape in a reference cycle, or one that
+ * names an unresolvable id, is omitted (degrades to untyped) with an `error` diagnostic; a
+ * deliberate field shadow with a differing type resolves with a `field-conflict` warning.
+ */
+export function resolveShapes(shapes, types, sources = []) {
+    const diagnostics = [];
+    const resolved = {};
+    if (shapes.length === 0)
+        return { types: resolved, diagnostics };
+    const { index, tableIds, ambiguousIds } = leafEntityIndex(sources, types);
+    // A nominal reference (an `extend` type or a non-spread `reference`) must resolve to a
+    // `DomainTypes` key at emit time — a manifest type or a resolved shape id. DB tables are
+    // spread-only (their fields flatten via carry/project); nominally referencing one would degrade
+    // to `unknown` in the emitted `.d.ts`, so we reject.
+    const nominalIds = new Set(Object.keys(types));
+    // Duplicate shape ids are fuse-identity collisions: since resolution keys by id, a later
+    // declaration would silently shadow an earlier one. Report every id that appears more than once
+    // and omit all of its declarations from resolution.
+    const idCounts = new Map();
+    for (const s of shapes)
+        if (s.id)
+            idCounts.set(s.id, (idCounts.get(s.id) ?? 0) + 1);
+    const duplicated = new Set();
+    for (const [id, n] of idCounts) {
+        if (n > 1) {
+            duplicated.add(id);
+            diagnostics.push({
+                shape: id,
+                kind: "duplicate-id",
+                severity: "error",
+                message: `shape id "${id}" is declared ${n} times; ids are fuse identities and must be unique`,
+            });
+        }
+    }
+    const byId = new Map();
+    for (const s of shapes)
+        if (s.id && !duplicated.has(s.id))
+            byId.set(s.id, s);
+    const shapeIds = new Set(byId.keys());
+    // Cycle detection over the shape-only dependency graph (DFS three-colour). Every shape on a back
+    // edge is failed; the reported path aids the maker's fix.
+    const failed = new Set();
+    const colour = new Map(); // 0=unvisited 1=on-stack 2=done
+    const visit = (id, stack) => {
+        colour.set(id, 1);
+        stack.push(id);
+        for (const dep of referencedShapeIds(byId.get(id), shapeIds)) {
+            const c = colour.get(dep) ?? 0;
+            if (c === 1) {
+                const cycle = stack.slice(stack.indexOf(dep)).concat(dep);
+                for (const n of cycle) {
+                    if (!failed.has(n)) {
+                        failed.add(n);
+                        diagnostics.push({
+                            shape: n,
+                            kind: "reference-cycle",
+                            severity: "error",
+                            message: `shape "${n}" is part of a reference cycle: ${cycle.join(" → ")}`,
+                        });
+                    }
+                }
+            }
+            else if (c === 0) {
+                visit(dep, stack);
+            }
+        }
+        stack.pop();
+        colour.set(id, 2);
+    };
+    for (const id of byId.keys())
+        if ((colour.get(id) ?? 0) === 0)
+            visit(id, []);
+    // Topological resolution: resolve a shape only after its (non-failed) shape dependencies, adding
+    // each resolved shape to the index so later shapes see it.
+    const done = new Set();
+    const resolveOne = (shape) => {
+        if (done.has(shape.id) || failed.has(shape.id))
+            return;
+        // Resolve shape dependencies first (they may themselves be pending).
+        for (const dep of referencedShapeIds(shape, shapeIds)) {
+            const d = byId.get(dep);
+            if (d && !done.has(dep) && !failed.has(dep))
+                resolveOne(d);
+        }
+        const fields = {};
+        let broken = false;
+        const addField = (name, field) => {
+            const existing = fields[name];
+            if (existing && !sameFieldDef(existing, field)) {
+                diagnostics.push({
+                    shape: shape.id,
+                    kind: "field-conflict",
+                    severity: "warning",
+                    message: `field "${name}" is contributed twice with differing types; the later value wins (author-order fold)`,
+                });
+            }
+            fields[name] = field; // last (author-order) wins
+        };
+        const lookup = (ref) => index.get(ref);
+        const unresolved = (ref) => {
+            broken = true;
+            diagnostics.push({
+                shape: shape.id,
+                kind: "unresolved-reference",
+                severity: "error",
+                message: `shape "${shape.id}" references unknown entity "${ref}"`,
+            });
+        };
+        // A bare id that names both a manifest type and a table resolves to the type; warn so the
+        // (silent) precedence is visible and the maker can qualify.
+        const noteAmbiguity = (ref) => {
+            if (ambiguousIds.has(ref)) {
+                diagnostics.push({
+                    shape: shape.id,
+                    kind: "ambiguous-reference",
+                    severity: "warning",
+                    message: `"${ref}" names both a manifest type and a table; resolved to the type — qualify as "<source>.${ref}" to target the table`,
+                });
+            }
+        };
+        // Report a nominal reference (extend type / non-spread reference) that targets a DB table,
+        // which cannot be expressed as a `DomainTypes` ref (it would degrade to `unknown`); the maker
+        // should spread it instead (carry/project or spread=true).
+        const nominalTableRef = (kind, ref) => {
+            broken = true;
+            diagnostics.push({
+                shape: shape.id,
+                kind: "nominal-table-ref",
+                severity: "error",
+                message: `${kind} nominally references table "${ref}", which is not a DomainTypes entity; spread its fields (carry/project or reference spread="true") instead`,
+            });
+        };
+        for (const op of shape.ops) {
+            switch (op.op) {
+                case "carry": {
+                    const e = lookup(op.ref);
+                    if (!e) {
+                        unresolved(op.ref);
+                        break;
+                    }
+                    noteAmbiguity(op.ref);
+                    for (const [k, f] of Object.entries(e.fields))
+                        addField(k, f);
+                    break;
+                }
+                case "project": {
+                    const e = lookup(op.ref);
+                    if (!e) {
+                        unresolved(op.ref);
+                        break;
+                    }
+                    noteAmbiguity(op.ref);
+                    for (const fname of op.fields) {
+                        const f = e.fields[fname];
+                        if (!f) {
+                            broken = true;
+                            diagnostics.push({
+                                shape: shape.id,
+                                kind: "unknown-field",
+                                severity: "error",
+                                message: `projected field "${fname}" is not a field of "${op.ref}"`,
+                            });
+                            continue;
+                        }
+                        addField(fname, f);
+                    }
+                    if (op.via)
+                        validateVia(shape.id, op.via, index, diagnostics);
+                    break;
+                }
+                case "extend": {
+                    if (!isPrimitiveKeyword(op.type)) {
+                        if (nominalIds.has(op.type)) {
+                            // ok — a manifest type or an already-resolved shape id
+                        }
+                        else if (tableIds.has(op.type)) {
+                            nominalTableRef(`extend field "${op.name}"`, op.type);
+                            break;
+                        }
+                        else {
+                            broken = true;
+                            diagnostics.push({
+                                shape: shape.id,
+                                kind: "unresolved-reference",
+                                severity: "error",
+                                message: `extend field "${op.name}" has type "${op.type}", which is neither a scalar keyword nor a fused entity`,
+                            });
+                            break;
+                        }
+                    }
+                    const field = { type: op.type };
+                    if (op.optional)
+                        field.optional = true;
+                    if (op.list)
+                        field.list = true;
+                    addField(op.name, field);
+                    break;
+                }
+                case "reference": {
+                    const e = lookup(op.ref);
+                    if (!e) {
+                        unresolved(op.ref);
+                        break;
+                    }
+                    if (op.spread) {
+                        noteAmbiguity(op.ref);
+                        for (const [k, f] of Object.entries(e.fields))
+                            addField(k, f);
+                    }
+                    else if (!nominalIds.has(op.ref)) {
+                        // `e` exists but the id is not a DomainTypes key — it is a DB table.
+                        nominalTableRef(`reference "${op.name}"`, op.ref);
+                    }
+                    else {
+                        const field = { type: op.ref };
+                        if (op.list)
+                            field.list = true;
+                        addField(op.name, field);
+                    }
+                    break;
+                }
+            }
+        }
+        // same-id collision: the shape id shadows a leaf entity it does not source. The shape composes
+        // that entity when it references it under any id (bare or `source.table` alias) — since the
+        // index maps every alias to the same `FuseEntity` instance, compare by identity rather than by
+        // the bare id alone.
+        const collidingEntity = index.get(shape.id);
+        const composesColliding = collidingEntity !== undefined &&
+            shape.ops.some((o) => o.op !== "extend" && index.get(o.ref) === collidingEntity);
+        if (collidingEntity !== undefined && !composesColliding) {
+            diagnostics.push({
+                shape: shape.id,
+                kind: "same-id-collision",
+                severity: "error",
+                message: `shape id "${shape.id}" collides with an existing fused entity it does not compose`,
+            });
+            broken = true;
+        }
+        done.add(shape.id);
+        if (broken) {
+            failed.add(shape.id);
+            return;
+        }
+        const def = { name: shape.name, fields };
+        resolved[shape.id] = def;
+        // Later shapes may carry this one; expose its resolved fields to the index and mark it
+        // nominal-referenceable (it will be a `DomainTypes` key).
+        index.set(shape.id, { fields });
+        nominalIds.add(shape.id);
+    };
+    for (const s of shapes)
+        if (s.id && !duplicated.has(s.id))
+            resolveOne(s);
+    return { types: resolved, diagnostics };
+}
+/** Validate a `project via` FK path (`Entity.column[.column...]`): the leading entity must resolve
+ * and carry the named column (an FK column on a DB table, or any field on a manifest type/shape).
+ * Deeper hops are validated leniently — the FK target is followed when the leading entity is a DB
+ * table with that FK. */
+function validateVia(shape, via, index, diagnostics) {
+    const parts = via.split(".");
+    if (parts.length < 2) {
+        diagnostics.push({
+            shape,
+            kind: "unknown-field",
+            severity: "warning",
+            message: `via path "${via}" is not of the form Entity.column`,
+        });
+        return;
+    }
+    // Resolve the starting entity as the *longest* dotted prefix present in the index (so a qualified
+    // `source.table` start works, not just a bare id), leaving at least one trailing segment as a hop
+    // column. The remaining segments are hop columns.
+    let entity;
+    let start = 0;
+    for (let p = 1; p < parts.length; p++) {
+        const candidate = parts.slice(0, p).join(".");
+        const hit = index.get(candidate);
+        if (hit) {
+            entity = hit;
+            start = p;
+        }
+    }
+    if (!entity) {
+        diagnostics.push({
+            shape,
+            kind: "unknown-field",
+            severity: "warning",
+            message: `via path "${via}" starts at unknown entity "${parts.slice(0, -1).join(".")}"`,
+        });
+        return;
+    }
+    let cursor = entity;
+    for (let i = start; i < parts.length; i++) {
+        const col = parts[i];
+        const hasField = Object.prototype.hasOwnProperty.call(cursor.fields, col);
+        const fkTarget = cursor.fks?.[col];
+        if (!hasField && !fkTarget) {
+            diagnostics.push({
+                shape,
+                kind: "unknown-field",
+                severity: "warning",
+                message: `via path "${via}" hops through unknown column "${col}"`,
+            });
+            return;
+        }
+        // Follow the FK to the next entity when we can; otherwise stop (lenient).
+        const next = fkTarget ? index.get(fkTarget) : undefined;
+        if (!next)
+            return;
+        cursor = next;
+    }
+}
+// --- the structured fused domain model: domain.json (ADR 0040 §1, OQ1) -----------------------
+//
+// The computed fuse is persisted as a generated, git-ignored `nano-generated/domain.json` — a
+// fast-read structured index for the IDE/codegen so a reader need not re-scan every model +
+// datasource. It is a *cache*, never a source: the `domaintypes` op regenerates it write-through on
+// any source change, and an `inputsHash` over its own content lets a reader detect staleness
+// cheaply.
+/** The basename of the generated structured fuse cache (ADR 0040 §1). */
+export const DOMAIN_MODEL_JSON = "domain.json";
+/** FNV-1a (32-bit) hex of a string — a small, dependency-free content tag for the fuse cache's
+ * `inputsHash` (staleness detection, not security). */
+function fnv1aHex(s) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return (h >>> 0).toString(16).padStart(8, "0");
+}
+/** Convert a resolved field map to the ordered `domain.json` field list. */
+function fieldsJson(fields) {
+    return Object.entries(fields ?? {}).map(([name, f]) => {
+        const out = { name, type: f.type };
+        if (f.optional)
+            out.optional = true;
+        if (f.list)
+            out.list = true;
+        return out;
+    });
+}
+/**
+ * Emit `domain.json`: the structured Fused Domain Model (ADR 0040 §1). Assembles every fused
+ * entity — DB tables (`db:` provenance), manifest `types` (`manifest:`), and composed motion shapes
+ * (`model:<processId>`, or bare `model` for an unsaved editor shape with no process) — with its
+ * resolved fields, plus the model-level metadata and the shape diagnostics. An `inputsHash` —
+ * FNV-1a (hex) over the compact `JSON.stringify` of the model object with `inputsHash` omitted
+ * (property-insertion order, not the pretty-printed bytes) — tags the cache for staleness.
+ */
+export function emitDomainModelJson(input) {
+    const entities = [];
+    for (const s of input.sources) {
+        for (const t of s.tables) {
+            const fields = {};
+            for (const c of t.columns)
+                fields[c.name] = columnToField(c);
+            entities.push({
+                id: `${s.source}.${t.name}`,
+                kind: "table",
+                provenance: `db:${s.source}.${t.name}`,
+                fields: fieldsJson(fields),
+            });
+        }
+    }
+    for (const [id, def] of Object.entries(input.manifestTypes)) {
+        entities.push({
+            id,
+            kind: "type",
+            provenance: `manifest:${id}`,
+            ...(def.name ? { name: def.name } : {}),
+            fields: fieldsJson(def.fields),
+        });
+    }
+    for (const { decl, def } of input.shapes) {
+        entities.push({
+            id: decl.id,
+            kind: "shape",
+            provenance: decl.process ? `model:${decl.process}` : "model",
+            ...(def.name ?? decl.name ? { name: def.name ?? decl.name } : {}),
+            fields: fieldsJson(def.fields),
+        });
+    }
+    const meta = input.meta
+        .filter((m) => (m?.key ?? "").trim().length > 0)
+        .map((m) => ({ ...(m.process ? { process: m.process } : {}), key: m.key, value: m.value ?? "" }));
+    const model = {
+        $generated: "nanobpmn ADR 0040 §1 Fused Domain Model — do not edit; regenerated by the domaintypes op",
+        version: 1,
+        ...(input.default ? { default: input.default } : {}),
+        sources: input.sources.map((s) => s.source),
+        entities,
+        meta,
+        diagnostics: input.diagnostics,
+        inputsHash: "",
+    };
+    model.inputsHash = fnv1aHex(JSON.stringify({ ...model, inputsHash: undefined }));
+    return `${JSON.stringify(model, null, 2)}\n`;
+}

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

@@ -25,6 +25,9 @@ export interface WorkerIo {
 }
 /** Filename the console uses; kept identical so the artifact is a drop-in. */
 export declare const WORKER_BINDINGS_DTS = "worker-io.d.ts";
+/** The generated typed-`defineWorker` wrapper's basename — re-exports the worker SDK and overrides
+ * `defineWorker` with a taskType-keyed typed signature. */
+export declare const WORKER_BINDINGS_TS = "workers.ts";
 /** The domain type declarations `worker-io.d.ts` imports from (console: domain-rows.d.ts). */
 export declare const DOMAIN_DTS = "domain-rows.d.ts";
 /** Scan one BPMN document for service-task worker I/O. */
@@ -37,6 +40,10 @@ export interface WorkerBindingDecl {
     taskType?: string;
     inputType?: string;
     outputType?: string;
+    /** The `zeebe:header` keys declared on the task; reified into a typed `job.customHeaders` shape
+     * (known keys, `string` values — headers are strings on the wire). Empty/absent leaves
+     * `customHeaders` the untyped fallback. */
+    headerKeys?: string[];
 }
 /** Emit `worker-io.d.ts` from worker bindings + the set of declared domain type ids. */
 export declare function emitWorkerBindings(workers: WorkerBindingDecl[], declaredTypeIds: Iterable<string>): string;
@@ -50,3 +57,22 @@ export declare const workerIoDeriver: Deriver<{
     models: ModelSource[];
     declaredTypeIds: Iterable<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
+ * `derived` (clearing a stale manifest value when the model carries none); manifest entries the scan
+ * did not cover (e.g. a worker declared only for an `llm` binding, with no service task) are
+ * preserved. New `taskType`s seen only in the model are appended. A byte-faithful port of the
+ * console's `overlayDerivedWorkerIo` (server `data_cli.ts`).
+ */
+export declare function overlayDerivedWorkerIo(manifest: WorkerBindingDecl[], derived: WorkerBindingDecl[]): WorkerBindingDecl[];
+/**
+ * The static typed-`defineWorker` wrapper (`workers.ts`). It re-exports the whole worker SDK and
+ * overrides `defineWorker` with a signature that keys off the `type:` string literal: when a job
+ * type is present in the generated `WorkerInputs`/`WorkerOutputs` (ADR 0033 §3), the handler's
+ * `job.variables` and result are typed from the declared domain type; otherwise they fall back to
+ * `WorkerVars`. The body is a pass-through — the wire stays untyped JSON (ADR 0029 §3). This file
+ * never changes with the schema, so it is written verbatim (unlike the regenerated
+ * `worker-io.d.ts`). A byte-faithful port of the console's `emitWorkerBindingsRuntime`.
+ */
+export declare function emitWorkerBindingsRuntime(): string;

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

@@ -14,6 +14,9 @@ export function byModelPath(a, b) {
 }
 /** Filename the console uses; kept identical so the artifact is a drop-in. */
 export const WORKER_BINDINGS_DTS = "worker-io.d.ts";
+/** The generated typed-`defineWorker` wrapper's basename — re-exports the worker SDK and overrides
+ * `defineWorker` with a taskType-keyed typed signature. */
+export const WORKER_BINDINGS_TS = "workers.ts";
 /** The domain type declarations `worker-io.d.ts` imports from (console: domain-rows.d.ts). */
 export const DOMAIN_DTS = "domain-rows.d.ts";
 const ENVELOPE_IN = "io.nanobpm.dataEnvelope.in";
@@ -65,6 +68,22 @@ export function scanModelWorkers(xml) {
 export function typeRefFor(id, declared) {
     return id != null && declared.has(id) ? `DomainTypes[${JSON.stringify(id)}]` : undefined;
 }
+/** The TS type expression for a worker's declared custom-header keys: an object type mapping each
+ * declared key to `string` (Zeebe headers are strings on the wire) plus a `string` index signature
+ * so undeclared headers stay accessible with the same honest wire type. Returns `undefined` when no
+ * keys are declared (the caller omits the entry so the taskType falls back to `WorkerHdrs`). */
+function headerRefFor(keys) {
+    const clean = [
+        ...new Set((keys ?? [])
+            .filter((k) => typeof k === "string")
+            .map((k) => k.trim())
+            .filter((k) => k.length > 0)),
+    ];
+    if (clean.length === 0)
+        return undefined;
+    const fields = clean.map((k) => `${JSON.stringify(k)}: string`).join("; ");
+    return `{ ${fields}; [key: string]: string }`;
+}
 /** Emit `worker-io.d.ts` from worker bindings + the set of declared domain type ids. */
 export function emitWorkerBindings(workers, declaredTypeIds) {
     const declared = new Set(declaredTypeIds);
@@ -79,6 +98,7 @@ export function emitWorkerBindings(workers, declaredTypeIds) {
         : "string";
     const inputs = [];
     const outputs = [];
+    const headers = [];
     for (const w of workers) {
         if (typeof w?.taskType !== "string" || w.taskType.length === 0)
             continue;
@@ -88,6 +108,9 @@ export function emitWorkerBindings(workers, declaredTypeIds) {
         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};`);
     }
     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" +
@@ -105,7 +128,9 @@ export function emitWorkerBindings(workers, declaredTypeIds) {
     const outputsIface = outputs.length > 0
         ? `export interface WorkerOutputs {\n${outputs.join("\n")}\n}\n`
         : `export interface WorkerOutputs {}\n`;
-    const headersIface = `export interface WorkerHeaders {}\n`;
+    const headersIface = headers.length > 0
+        ? `export interface WorkerHeaders {\n${headers.join("\n")}\n}\n`
+        : `export interface WorkerHeaders {}\n`;
     return `${header}\n` +
         importTypes +
         `\n/** Untyped fallback for a job whose worker declares no input/output type. */\n` +
@@ -144,3 +169,78 @@ export const workerIoDeriver = {
     describe: "Derive worker-io.d.ts (task type + data-envelope in/out) from BPMN models.",
     derive: ({ models, declaredTypeIds }) => deriveWorkerBindings(models, declaredTypeIds),
 };
+/**
+ * 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
+ * `derived` (clearing a stale manifest value when the model carries none); manifest entries the scan
+ * did not cover (e.g. a worker declared only for an `llm` binding, with no service task) are
+ * preserved. New `taskType`s seen only in the model are appended. A byte-faithful port of the
+ * console's `overlayDerivedWorkerIo` (server `data_cli.ts`).
+ */
+export function overlayDerivedWorkerIo(manifest, derived) {
+    const byType = new Map();
+    for (const w of manifest) {
+        if (typeof w.taskType === "string")
+            byType.set(w.taskType, { ...w });
+    }
+    for (const d of derived) {
+        if (typeof d.taskType !== "string")
+            continue;
+        const existing = byType.get(d.taskType);
+        const merged = existing
+            ? { ...existing, taskType: d.taskType }
+            : { taskType: d.taskType };
+        if (d.inputType)
+            merged.inputType = d.inputType;
+        else
+            delete merged.inputType;
+        if (d.outputType)
+            merged.outputType = d.outputType;
+        else
+            delete merged.outputType;
+        // Header keys are authored on the model, so the derived set is authoritative: replace (not
+        // union) the manifest's, and clear when the model declares none.
+        if (d.headerKeys && d.headerKeys.length > 0)
+            merged.headerKeys = [...d.headerKeys];
+        else
+            delete merged.headerKeys;
+        byType.set(d.taskType, merged);
+    }
+    return [...byType.values()];
+}
+/**
+ * The static typed-`defineWorker` wrapper (`workers.ts`). It re-exports the whole worker SDK and
+ * overrides `defineWorker` with a signature that keys off the `type:` string literal: when a job
+ * type is present in the generated `WorkerInputs`/`WorkerOutputs` (ADR 0033 §3), the handler's
+ * `job.variables` and result are typed from the declared domain type; otherwise they fall back to
+ * `WorkerVars`. The body is a pass-through — the wire stays untyped JSON (ADR 0029 §3). This file
+ * never changes with the schema, so it is written verbatim (unlike the regenerated
+ * `worker-io.d.ts`). A byte-faithful port of the console's `emitWorkerBindingsRuntime`.
+ */
+export function emitWorkerBindingsRuntime() {
+    return "// AUTO-GENERATED by nanobpmn (ADR 0033 §3): the typed `defineWorker`.\n" +
+        "// Re-exports the worker SDK and overrides `defineWorker` with a taskType-keyed\n" +
+        "// typed signature (job.variables, job.customHeaders + result typed from the\n" +
+        "// worker's declared input/output/header contract). Erased to a pass-through at\n" +
+        "// runtime. Do not edit.\n" +
+        "// eslint-disable\n\n" +
+        `import { defineWorker as defineWorkerRaw } from "./worker-sdk.ts";\n` +
+        `import type { WorkerOptions } from "./worker-sdk.ts";\n` +
+        `import type { WorkerInputs, WorkerOutputs, WorkerHeaders, WorkerTaskType, WorkerVars, WorkerHdrs } from "./${WORKER_BINDINGS_DTS}";\n\n` +
+        `export * from "./worker-sdk.ts";\n\n` +
+        `type InFor<K extends WorkerTaskType> = K extends keyof WorkerInputs ? WorkerInputs[K] : WorkerVars;\n` +
+        `type OutFor<K extends WorkerTaskType> = K extends keyof WorkerOutputs ? WorkerOutputs[K] : WorkerVars;\n` +
+        `type HdrFor<K extends WorkerTaskType> = K extends keyof WorkerHeaders ? WorkerHeaders[K] : WorkerHdrs;\n\n` +
+        `/**\n` +
+        ` * Typed \`defineWorker\`: \`type\` is constrained to the model's declared job types\n` +
+        ` * (\`WorkerTaskType\`, ADR 0033 §3) so it autocompletes and rejects unknown jobs,\n` +
+        ` * and the handler's \`job.variables\`, \`job.customHeaders\` + result are typed from\n` +
+        ` * the worker's declared \`inputType\`/\`outputType\`/header keys. A declared job type\n` +
+        ` * with no declared type falls back to WorkerVars / WorkerHdrs.\n` +
+        ` */\n` +
+        `export function defineWorker<K extends WorkerTaskType>(\n` +
+        `  opts: { type: K } & WorkerOptions<InFor<K> & object, OutFor<K> & object, HdrFor<K> & object>,\n` +
+        `): void {\n` +
+        `  defineWorkerRaw(opts as unknown as WorkerOptions);\n` +
+        `}\n`;
+}