@sequenceholdings/studio-cli 0.1.9

package/dist/process/build.js

@@ -0,0 +1,368 @@
+/**
+ * Bundle builder. Produces the canonical `bundle_hash` for a process
+ * source tree.
+ */
+import { execSync } from 'node:child_process';
+import { finalizeBundleIdentity, forEachSerializedNode, } from '@sequenceholdings/lattice/bundle';
+import { parseDurationMs, serializeRetryConfig, } from '@sequenceholdings/lattice/define';
+export async function buildBundleFromProcesses(defs, options) {
+    if (defs.length === 0) {
+        throw new Error('no lattice process definitions found in configured roots');
+    }
+    const processes = defs.map((d) => serializeProcess({ process: d.process }));
+    const localProcessIds = new Set(processes.map((p) => p.id));
+    if (options?.resolveProcessPin) {
+        await resolveSubprocessPinsInProcesses(processes, async (processId, version) => {
+            // Child processes co-located in this bundle are pinned by
+            // finalizeBundleIdentity to this bundle's own version/hash.
+            if (!version && localProcessIds.has(processId))
+                return null;
+            return options.resolveProcessPin(processId, version);
+        });
+    }
+    // Manifest, hash, version, and co-located subprocess pins are all derived in
+    // the SDK so a CLI-built bundle is byte-identical to a server-applied one.
+    return finalizeBundleIdentity({ processes, metadata: collectGitMetadata() });
+}
+async function resolveSubprocessPinsInProcesses(processes, resolve) {
+    const pins = [];
+    for (const proc of processes) {
+        forEachSerializedNode(proc.nodes, (node) => {
+            if (node.kind !== 'subprocess')
+                return;
+            pins.push(pinSubprocessNode(proc.id, node, resolve, { allowUnresolved: true }));
+        });
+    }
+    await Promise.all(pins);
+}
+async function pinSubprocessNode(processId, node, resolve, options) {
+    const meta = node.metadata;
+    const spec = meta.subprocess;
+    if (!spec?.process_id) {
+        throw new Error(`process "${processId}": subprocess node "${node.id}" is missing subprocess metadata`);
+    }
+    if (spec.bundle_hash && spec.version)
+        return;
+    const resolved = await resolve(spec.process_id, spec.version);
+    if (!resolved) {
+        if (options?.allowUnresolved)
+            return;
+        throw new Error(`process "${processId}": subprocess node "${node.id}" references unknown process ` +
+            `"${spec.process_id}"${spec.version ? ` version "${spec.version}"` : ''}`);
+    }
+    meta.subprocess = {
+        ...spec,
+        version: resolved.version,
+        bundle_hash: resolved.bundleHash,
+    };
+}
+function serializeProcess(input) {
+    const nodes = input.process.nodes.map((node) => serializeNode(node));
+    return {
+        id: input.process.id,
+        name: input.process.name,
+        description: input.process.description ?? null,
+        entity_spec: { type: input.process.entity.type },
+        start_node_id: input.process.start_node_id,
+        nodes,
+        ...(input.process.recommendations && input.process.recommendations.length > 0
+            ? { recommendations: input.process.recommendations }
+            : {}),
+        ...(input.process.tags && input.process.tags.length > 0
+            ? { tags: input.process.tags }
+            : {}),
+        ...(input.process.max_iterations !== undefined
+            ? { max_iterations: input.process.max_iterations }
+            : {}),
+        ...(input.process.max_revisits !== undefined
+            ? { max_revisits: input.process.max_revisits }
+            : {}),
+        ...(input.process.max_concurrent_runs !== undefined
+            ? { max_concurrent_runs: input.process.max_concurrent_runs }
+            : {}),
+        ...(input.process.supervisor_retry !== undefined
+            ? { supervisor_retry: serializeRetryConfig(input.process.supervisor_retry) }
+            : {}),
+        ...(input.process.run_as !== undefined
+            ? { run_as: { email: input.process.run_as.email } }
+            : {}),
+    };
+}
+/**
+ * Serialize one node definition to its bundle form. Extracted so parallel
+ * sub-nodes round-trip through the exact same path as top-level nodes —
+ * including nested parallel blocks (recursion lands back here via
+ * `serializeNodeMetadata`'s `parallel` case).
+ */
+function serializeNode(node) {
+    const metadata = serializeNodeMetadata(node);
+    // Node-execution middleware (e.g. retry) — author-declared on the node
+    // definition, serialized verbatim into metadata.middleware. Resolved at
+    // runtime against the server-side node-middleware registry; the bundle
+    // registration step validates the referenced ids + kind-eligibility.
+    const middleware = 'middleware' in node ? node.middleware : undefined;
+    if (Array.isArray(middleware) && middleware.length > 0) {
+        metadata.middleware = middleware.map((m) => ({
+            id: m.id,
+            ...(m.config !== undefined ? { config: m.config } : {}),
+        }));
+    }
+    return {
+        id: node.id,
+        kind: node.kind,
+        title: node.title,
+        description: node.description ?? null,
+        outgoing_edges: node.outgoing_edges.map((e) => ({ id: e.id, to: e.to })),
+        metadata,
+    };
+}
+function serializeNodeMetadata(node) {
+    switch (node.kind) {
+        case 'automation': {
+            // Automation nodes carry a native registry id instead of inline source —
+            // their code lives in the Atlas image and is never serialized here.
+            const native = node;
+            const meta = {
+                registered_function_id: native.registered_function_id,
+                execution: 'native',
+            };
+            if (native.config)
+                meta.config = native.config;
+            if (native.limits)
+                meta.limits = native.limits;
+            if (native.bindings)
+                meta.bindings = native.bindings;
+            const nativeInputMapper = native.input;
+            if (typeof nativeInputMapper === 'function') {
+                meta.input_mapper_source = nativeInputMapper.toString();
+            }
+            return meta;
+        }
+        case 'agent': {
+            const agent = node;
+            const meta = {
+                agent_id: agent.agent.id,
+            };
+            if (agent.timeout !== undefined)
+                meta.timeout = agent.timeout;
+            if (agent.workflowId !== undefined)
+                meta.workflow_id = agent.workflowId;
+            if (agent.on_reset_edge_id)
+                meta.on_reset_edge_id = agent.on_reset_edge_id;
+            if (agent.bindings)
+                meta.bindings = agent.bindings;
+            const inputMapper = agent.input;
+            if (typeof inputMapper === 'function') {
+                meta.input_mapper_source = inputMapper.toString();
+            }
+            return meta;
+        }
+        case 'human': {
+            const human = node;
+            const meta = {
+                metadata: human.metadata ?? {},
+                timeout: human.timeout ?? '7d',
+            };
+            if (human.on_timeout_edge_id)
+                meta.on_timeout_edge_id = human.on_timeout_edge_id;
+            if (human.completeLabel)
+                meta.complete_label = human.completeLabel;
+            if (human.hideTimeoutEdgeFromAdvance)
+                meta.hide_timeout_edge_from_advance = true;
+            // advance_allowed is either a static ACL object or a `(ctx) => ACL`
+            // mapper resolved per-step at entry (the per-branch fan-out assignment
+            // hook). Serialize the function form as source like the other mappers.
+            if (typeof human.advance_allowed === 'function') {
+                meta.advance_allowed_mapper_source = human.advance_allowed.toString();
+            }
+            else if (human.advance_allowed) {
+                meta.advance_allowed = human.advance_allowed;
+            }
+            if (human.assignable_to)
+                meta.assignable_to = human.assignable_to;
+            // Email notification: normalize the boolean / template-fn / config forms
+            // into metadata. Presence of `email_notification` = enabled; template fns
+            // are serialized to source like the other mappers.
+            const email = human.emailNotification;
+            if (email === true) {
+                meta.email_notification = true;
+            }
+            else if (typeof email === 'function') {
+                meta.email_notification = true;
+                meta.email_notification_template_source = email.toString();
+            }
+            else if (email && typeof email === 'object') {
+                meta.email_notification = true;
+                if (typeof email.template === 'function') {
+                    meta.email_notification_template_source = email.template.toString();
+                }
+                if (email.timezone)
+                    meta.email_notification_timezone = email.timezone;
+                if (email.reminders && email.reminders.length > 0) {
+                    meta.email_notification_reminders = email.reminders.map((r) => ({
+                        ...(r.before !== undefined ? { before: r.before } : {}),
+                        ...(r.after !== undefined ? { after: r.after } : {}),
+                        ...(typeof r.template === 'function'
+                            ? { template_source: r.template.toString() }
+                            : {}),
+                    }));
+                }
+                // Deploy-env allowlist (plain data, no sandboxed fn). Copied so the
+                // serialized bundle never aliases the author's readonly array. The
+                // worker interprets it against its own APP_ENV at dispatch time.
+                if (email.enabledEnvironments && email.enabledEnvironments.length > 0) {
+                    meta.email_notification_enabled_environments = [...email.enabledEnvironments];
+                }
+            }
+            // dueDate `(ctx) => Date`, computed per-run; serialize as source.
+            if (typeof human.dueDate === 'function') {
+                meta.due_date_source = human.dueDate.toString();
+            }
+            if (human.bindings)
+                meta.bindings = human.bindings;
+            if (Array.isArray(human.artifact_refs)) {
+                meta.artifact_refs = human.artifact_refs;
+            }
+            else if (typeof human.artifact_refs === 'function') {
+                meta.artifact_refs_mapper_source = human.artifact_refs.toString();
+            }
+            // First-class comment-chain opt-in — packed alongside artifact_refs (NOT
+            // inside the author `metadata` bag), so it serializes as its own node
+            // field that the inbox/process-activity reads at `node.metadata.comments`.
+            if (human.comments)
+                meta.comments = human.comments;
+            const humanInputMapper = human.input;
+            if (typeof humanInputMapper === 'function') {
+                meta.input_mapper_source = humanInputMapper.toString();
+            }
+            return meta;
+        }
+        case 'subprocess': {
+            const subprocess = node;
+            const toSource = (fn) => fn.toString();
+            const smeta = {
+                process_id: subprocess.process,
+                version: subprocess.version ?? '',
+                bundle_hash: '',
+                on_child_error: subprocess.on_child_error,
+                output_mapper_source: toSource(subprocess.output),
+                ...(subprocess.supervisor_retry !== undefined
+                    ? { supervisor_retry: serializeRetryConfig(subprocess.supervisor_retry) }
+                    : {}),
+            };
+            const meta = { subprocess: smeta };
+            if (typeof subprocess.input === 'function') {
+                meta.input_mapper_source = toSource(subprocess.input);
+            }
+            if (subprocess.bindings)
+                meta.bindings = subprocess.bindings;
+            return meta;
+        }
+        case 'parallel': {
+            const parallel = node;
+            const toSource = (fn) => fn.toString();
+            const pmeta = {
+                mode: parallel.branches ? 'static' : 'dynamic',
+                on_branch_error: parallel.on_branch_error,
+                join_source: toSource(parallel.join),
+            };
+            if (parallel.max_concurrency !== undefined) {
+                pmeta.max_concurrency = parallel.max_concurrency;
+            }
+            if (parallel.supervisor_retry !== undefined) {
+                pmeta.supervisor_retry = serializeRetryConfig(parallel.supervisor_retry);
+            }
+            if (parallel.branches) {
+                pmeta.branches = parallel.branches.map((b) => ({
+                    branch_id: b.branch_id,
+                    node: serializeNode(b.node),
+                }));
+            }
+            else {
+                pmeta.fan_out_source = toSource(parallel.fan_out);
+                if (parallel.max_fanout !== undefined)
+                    pmeta.max_fanout = parallel.max_fanout;
+                pmeta.branch = serializeNode(parallel.branch);
+            }
+            const meta = { parallel: pmeta };
+            // The parallel node's `input` mapper produces the optional rerun
+            // directive. It must live at TOP-LEVEL `input_mapper_source` — the same
+            // slot every other node kind uses — so the orchestrator's runInputMapper
+            // executes it and the runner reads the directive from its payload input.
+            // (Nesting it under `parallel` left it unread, disabling selective
+            // re-run + epoch invalidation entirely.)
+            if (typeof parallel.input === 'function') {
+                meta.input_mapper_source = toSource(parallel.input);
+            }
+            if (parallel.bindings)
+                meta.bindings = parallel.bindings;
+            return meta;
+        }
+        case 'delay': {
+            const delay = node;
+            // Pre-parse to ms so the runtime never re-implements the grammar. The
+            // string is kept for display; `duration_ms` is the authoritative wait.
+            const ms = parseDurationMs(delay.duration);
+            if (ms === null) {
+                throw new Error(`delay node "${delay.id}": invalid duration "${delay.duration}"`);
+            }
+            return { duration: delay.duration, duration_ms: ms };
+        }
+        case 'managed_function': {
+            const mf = node;
+            const meta = {
+                function_id: mf.function,
+            };
+            if (mf.version)
+                meta.version = mf.version;
+            if (mf.limits)
+                meta.limits = mf.limits;
+            if (mf.bindings)
+                meta.bindings = mf.bindings;
+            // NOTE: `middleware` (e.g. withRetry) is serialized generically for every
+            // node kind in `serializeNode` above — don't duplicate it here.
+            const inputMapper = mf.input;
+            if (typeof inputMapper === 'function') {
+                meta.input_mapper_source = inputMapper.toString();
+            }
+            return meta;
+        }
+        default:
+            return {};
+    }
+}
+function collectGitMetadata() {
+    const get = (cmd) => {
+        try {
+            return execSync(cmd, { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+        }
+        catch {
+            return null;
+        }
+    };
+    return {
+        created_at: new Date().toISOString(),
+        created_by: process.env['USER'] ?? null,
+        git_commit: get('git rev-parse HEAD'),
+        git_branch: get('git rev-parse --abbrev-ref HEAD'),
+        git_dirty: get('git status --porcelain') !== '',
+    };
+}
+export function summarizeBundle(bundle) {
+    return {
+        name: bundle.manifest.bundle.name,
+        version: bundle.version,
+        bundle_hash: bundle.bundle_hash,
+        source_hash: bundle.source_hash,
+        created_at: bundle.metadata.created_at,
+        created_by: bundle.metadata.created_by,
+        git_commit: bundle.metadata.git_commit,
+        git_branch: bundle.metadata.git_branch,
+        git_dirty: bundle.metadata.git_dirty,
+        processes: bundle.processes.map((p) => ({
+            id: p.id,
+            nodes: p.nodes.length,
+            edges: p.nodes.reduce((acc, n) => acc + n.outgoing_edges.length, 0),
+        })),
+    };
+}

package/dist/process/codegen.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Bundle → source codegen. Regenerates the author-facing `process.ts` (and
+ * `recommendations.ts`) for a stored {@link SerializedProcess} so a process
+ * published from the UI can be pulled back into a local tree.
+ *
+ * Fidelity notes (the bundle is a compiled artifact, not the original source):
+ *   - Mapper bodies are the build-time `Function.toString()` strings — valid and
+ *     runnable, but type annotations were stripped at serialize time.
+ *   - Automation bodies live in the Atlas image; only the registry id is
+ *     emitted (`function: '<id>'`).
+ *   - Co-located subprocess pins (version / bundle_hash) are dropped — they are
+ *     re-resolved on the next `apply`. An EXTERNAL subprocess (not bundled here)
+ *     keeps its explicit `version` pin so the rebuild resolves the same target.
+ *   - `recommendations` are an opaque passthrough — emitted verbatim.
+ */
+import type { LatticeBundle, SerializedProcess } from '@sequenceholdings/lattice/bundle';
+/** Files to write for one process, keyed by basename. */
+export declare function generateProcessFiles(process: SerializedProcess, bundle: LatticeBundle): Record<string, string>;

package/dist/process/codegen.js

@@ -0,0 +1,270 @@
+/**
+ * Bundle → source codegen. Regenerates the author-facing `process.ts` (and
+ * `recommendations.ts`) for a stored {@link SerializedProcess} so a process
+ * published from the UI can be pulled back into a local tree.
+ *
+ * Fidelity notes (the bundle is a compiled artifact, not the original source):
+ *   - Mapper bodies are the build-time `Function.toString()` strings — valid and
+ *     runnable, but type annotations were stripped at serialize time.
+ *   - Automation bodies live in the Atlas image; only the registry id is
+ *     emitted (`function: '<id>'`).
+ *   - Co-located subprocess pins (version / bundle_hash) are dropped — they are
+ *     re-resolved on the next `apply`. An EXTERNAL subprocess (not bundled here)
+ *     keeps its explicit `version` pin so the rebuild resolves the same target.
+ *   - `recommendations` are an opaque passthrough — emitted verbatim.
+ */
+/** ECMAScript reserved words (+ a few literals) that can't be bare identifiers. */
+const RESERVED = new Set([
+    'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger',
+    'default', 'delete', 'do', 'else', 'enum', 'export', 'extends', 'false',
+    'finally', 'for', 'function', 'if', 'import', 'in', 'instanceof', 'new',
+    'null', 'return', 'super', 'switch', 'this', 'throw', 'true', 'try',
+    'typeof', 'var', 'void', 'while', 'with', 'yield', 'let', 'static',
+    'implements', 'interface', 'package', 'private', 'protected', 'public',
+    'await', 'async',
+]);
+/** Files to write for one process, keyed by basename. */
+export function generateProcessFiles(process, bundle) {
+    const ctx = {
+        used: new Set(['defineProcess']),
+        colocated: new Set((bundle.processes ?? []).map((p) => p.id)),
+    };
+    const names = buildConstNames(process.nodes);
+    const consts = process.nodes.map((node) => {
+        const name = names.get(node.id);
+        return { name, code: `const ${name} = ${emitNode(node, ctx)}` };
+    });
+    const hasRecs = Array.isArray(process.recommendations) && process.recommendations.length > 0;
+    const imports = `import {\n${[...ctx.used].sort().map((n) => `  ${n},`).join('\n')}\n} from '@sequenceholdings/lattice'`;
+    const recImport = hasRecs ? `\nimport { recommendations } from './recommendations.js'` : '';
+    const entityType = process.entity_spec?.type ?? 'application';
+    const procFields = [
+        `  id: ${lit(process.id)},`,
+        `  name: ${lit(process.name)},`,
+        process.description != null ? `  description: ${lit(process.description)},` : null,
+        `  entity: { type: ${lit(entityType)} },`,
+        `  start_node_id: ${lit(process.start_node_id)},`,
+        process.max_iterations !== undefined ? `  max_iterations: ${process.max_iterations},` : null,
+        process.max_revisits !== undefined ? `  max_revisits: ${process.max_revisits},` : null,
+        process.max_concurrent_runs !== undefined
+            ? `  max_concurrent_runs: ${process.max_concurrent_runs},`
+            : null,
+        process.supervisor_retry !== undefined ? `  supervisor_retry: ${pretty(process.supervisor_retry, 1)},` : null,
+        process.run_as !== undefined ? `  run_as: { email: ${lit(process.run_as.email)} },` : null,
+        Array.isArray(process.tags) && process.tags.length > 0
+            ? `  tags: ${pretty(process.tags, 1)},`
+            : null,
+        `  nodes: [${consts.map((c) => c.name).join(', ')}],`,
+        hasRecs ? '  recommendations,' : null,
+    ]
+        .filter((l) => l !== null)
+        .join('\n');
+    const processTs = `${imports}${recImport}\n\n` +
+        `${consts.map((c) => c.code).join('\n\n')}\n\n` +
+        `export default defineProcess({\n${procFields}\n})\n`;
+    const files = { 'process.ts': processTs };
+    if (hasRecs) {
+        files['recommendations.ts'] =
+            `// Pulled from bundle ${bundle.version} — opaque passthrough.\n` +
+                `export const recommendations = ${pretty(process.recommendations, 0)}\n`;
+    }
+    return files;
+}
+function emitNode(node, ctx) {
+    const edges = emitEdges(node.outgoing_edges);
+    const head = [
+        `  id: ${lit(node.id)},`,
+        `  title: ${lit(node.title)},`,
+        node.description != null ? `  description: ${lit(node.description)},` : null,
+    ];
+    const m = node.metadata;
+    const tail = `  outgoing_edges: ${edges},`;
+    switch (node.kind) {
+        case 'agent': {
+            ctx.used.add('defineAgentNode');
+            return call('defineAgentNode', [
+                ...head,
+                `  agent: { id: ${lit(String(m.agent_id))} },`,
+                m.workflow_id != null ? `  workflowId: ${lit(String(m.workflow_id))},` : null,
+                m.on_reset_edge_id != null ? `  on_reset_edge_id: ${lit(String(m.on_reset_edge_id))},` : null,
+                m.timeout !== undefined ? `  timeout: ${value(m.timeout)},` : null,
+                bindings(m.bindings),
+                middleware(m.middleware),
+                mapper('input', m.input_mapper_source),
+                tail,
+            ]);
+        }
+        case 'human': {
+            ctx.used.add('defineHumanNode');
+            const metaObj = m.metadata;
+            return call('defineHumanNode', [
+                ...head,
+                metaObj && Object.keys(metaObj).length > 0 ? `  metadata: ${pretty(metaObj, 1)},` : null,
+                m.complete_label != null ? `  completeLabel: ${lit(String(m.complete_label))},` : null,
+                m.timeout !== undefined ? `  timeout: ${value(m.timeout)},` : null,
+                m.on_timeout_edge_id != null ? `  on_timeout_edge_id: ${lit(String(m.on_timeout_edge_id))},` : null,
+                m.hide_timeout_edge_from_advance === true ? `  hideTimeoutEdgeFromAdvance: true,` : null,
+                m.advance_allowed !== undefined ? `  advance_allowed: ${value(m.advance_allowed)},` : null,
+                m.assignable_to !== undefined ? `  assignable_to: ${pretty(m.assignable_to, 1)},` : null,
+                bindings(m.bindings),
+                Array.isArray(m.artifact_refs) ? `  artifact_refs: ${pretty(m.artifact_refs, 1)},` : null,
+                mapper('artifact_refs', m.artifact_refs_mapper_source),
+                m.comments !== undefined ? `  comments: ${pretty(m.comments, 1)},` : null,
+                mapper('input', m.input_mapper_source),
+                tail,
+            ]);
+        }
+        case 'automation': {
+            if (m.registered_function_id == null) {
+                throw new Error(`codegen: automation node "${node.id}" has no registered_function_id — ` +
+                    `sandboxed automation nodes are no longer supported`);
+            }
+            ctx.used.add('defineNativeAutomationNode');
+            return call('defineNativeAutomationNode', [
+                ...head,
+                `  function: ${lit(String(m.registered_function_id))},`,
+                m.config !== undefined ? `  config: ${pretty(m.config, 1)},` : null,
+                m.limits !== undefined ? `  limits: ${pretty(m.limits, 1)},` : null,
+                bindings(m.bindings),
+                middleware(m.middleware),
+                mapper('input', m.input_mapper_source),
+                tail,
+            ]);
+        }
+        case 'subprocess': {
+            ctx.used.add('defineSubprocessNode');
+            const sub = m.subprocess;
+            return call('defineSubprocessNode', [
+                ...head,
+                `  process: ${lit(sub.process_id)},`,
+                // Colocated pins re-resolve on rebuild; keep an external target's pin.
+                ctx.colocated.has(sub.process_id) ? null : `  version: ${lit(sub.version)},`,
+                `  on_child_error: ${lit(sub.on_child_error)},`,
+                sub.supervisor_retry !== undefined ? `  supervisor_retry: ${pretty(sub.supervisor_retry, 1)},` : null,
+                bindings(m.bindings),
+                mapper('input', m.input_mapper_source),
+                `  output: ${sub.output_mapper_source},`,
+                tail,
+            ]);
+        }
+        case 'parallel': {
+            ctx.used.add('defineParallelNode');
+            const par = m.parallel;
+            const branchFields = [];
+            if (par.mode === 'static' && par.branches) {
+                branchFields.push(`  branches: [\n${par.branches
+                    .map((b) => `    { branch_id: ${lit(b.branch_id)}, node: ${emitNode(b.node, ctx)} },`)
+                    .join('\n')}\n  ],`);
+            }
+            else {
+                if (par.fan_out_source)
+                    branchFields.push(`  fan_out: ${par.fan_out_source},`);
+                if (par.max_fanout !== undefined)
+                    branchFields.push(`  max_fanout: ${par.max_fanout},`);
+                if (par.branch)
+                    branchFields.push(`  branch: ${emitNode(par.branch, ctx)},`);
+            }
+            return call('defineParallelNode', [
+                ...head,
+                ...branchFields,
+                par.max_concurrency !== undefined ? `  max_concurrency: ${par.max_concurrency},` : null,
+                par.supervisor_retry !== undefined ? `  supervisor_retry: ${pretty(par.supervisor_retry, 1)},` : null,
+                bindings(m.bindings),
+                `  on_branch_error: ${lit(par.on_branch_error)},`,
+                `  join: ${par.join_source},`,
+                mapper('input', m.input_mapper_source),
+                tail,
+            ]);
+        }
+        case 'delay': {
+            ctx.used.add('defineDelayNode');
+            return call('defineDelayNode', [...head, `  duration: ${lit(String(m.duration))},`, tail]);
+        }
+        case 'managed_function': {
+            ctx.used.add('defineManagedFunctionNode');
+            const fields = [
+                ...head,
+                `  function: ${lit(String(m.function_id))},`,
+                m.version ? `  version: ${lit(String(m.version))},` : null,
+                m.limits !== undefined ? `  limits: ${pretty(m.limits, 1)},` : null,
+                bindings(m.bindings),
+                middleware(m.middleware),
+                mapper('input', m.input_mapper_source),
+                tail,
+            ];
+            return call('defineManagedFunctionNode', fields);
+        }
+        default:
+            throw new Error(`codegen: unsupported node kind "${node.kind}" (node "${node.id}")`);
+    }
+}
+function call(fn, fields) {
+    return `${fn}({\n${fields.filter((f) => f !== null).join('\n')}\n})`;
+}
+function emitEdges(edges) {
+    if (edges.length === 0)
+        return '[] as const';
+    const items = edges.map((e) => `{ id: ${lit(e.id)}, to: ${lit(e.to)} }`).join(', ');
+    return `[${items}] as const`;
+}
+/** A mapper field whose value is a serialized `Function.toString()` string. */
+function mapper(field, source) {
+    if (typeof source !== 'string' || source.length === 0)
+        return null;
+    return `  ${field}: ${source},`;
+}
+/** A safely-escaped TS string literal. */
+function lit(value) {
+    return JSON.stringify(value);
+}
+/** A primitive value as TS source (string → quoted; number/boolean → as-is). */
+function value(v) {
+    return typeof v === 'string' ? lit(v) : String(v);
+}
+/** A plain JSON value as an indented TS object/array literal. `depth` is the
+ *  indent level of the line the value starts on. */
+function pretty(v, depth) {
+    const json = JSON.stringify(v, null, 2);
+    if (!json.includes('\n'))
+        return json;
+    const pad = '  '.repeat(depth);
+    return json
+        .split('\n')
+        .map((line, i) => (i === 0 ? line : pad + line))
+        .join('\n');
+}
+/** An optional `bindings: [...]` field (descriptive node→lineage links). */
+function bindings(v) {
+    if (!Array.isArray(v) || v.length === 0)
+        return null;
+    return `  bindings: ${pretty(v, 1)},`;
+}
+/** An optional `middleware: [...]` field (node-execution middleware refs). */
+function middleware(v) {
+    if (!Array.isArray(v) || v.length === 0)
+        return null;
+    return `  middleware: ${pretty(v, 1)},`;
+}
+/** A node id → a valid, readable JS const identifier (camelCase, never a
+ *  reserved word, always starting with a letter/underscore). */
+function constName(id) {
+    const safe = id.replace(/[^A-Za-z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+    const camel = safe.replace(/_([a-z0-9])/g, (_, c) => c.toUpperCase());
+    return /^[A-Za-z_]/.test(camel) && !RESERVED.has(camel) ? camel : `n_${camel}`;
+}
+/** Assign each node a collision-free const name in node order: derive a safe
+ *  base via {@link constName}, then suffix `_2`, `_3`, … on any clash so two
+ *  ids that camelCase to the same identifier stay distinct. */
+function buildConstNames(nodes) {
+    const names = new Map();
+    const used = new Set();
+    for (const node of nodes) {
+        const base = constName(node.id);
+        let name = base;
+        for (let i = 2; used.has(name); i++)
+            name = `${base}_${i}`;
+        used.add(name);
+        names.set(node.id, name);
+    }
+    return names;
+}