@openapi-flow/n8n 0.0.0-stage → 0.3.0

package/dist/utils/bundled-license-banner.js

@@ -0,0 +1,32 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+/** Preserve bundled dependencies' license notices in generated workflow code. */
+export function bundledLicenseBanner(metadata, generatedFrom) {
+    const packages = new Set(generatedFrom);
+    const notices = [];
+    for (const input of Object.keys(metadata.inputs)) {
+        if (input === '<stdin>')
+            continue;
+        let directory = dirname(resolve(input));
+        while (!existsSync(join(directory, 'package.json'))) {
+            const parent = dirname(directory);
+            if (parent === directory)
+                throw new Error(`Bundled input ${input} has no owning package`);
+            directory = parent;
+        }
+        packages.add(directory);
+    }
+    for (const directory of packages) {
+        const file = ['LICENSE', 'LICENSE.md', 'LICENSE.txt']
+            .map((name) => join(directory, name))
+            .find(existsSync);
+        if (!file)
+            throw new Error(`Bundled package ${directory} has no license notice`);
+        notices.push(readFileSync(file, 'utf8'));
+    }
+    return notices.length
+        ? '/*! Bundled dependency licenses\n' +
+            notices.join('\n\n').replaceAll('*/', '* /') +
+            '\n*/\n'
+        : '';
+}

package/dist/utils/javascript-json-literal.d.ts

@@ -0,0 +1,2 @@
+/** Encode data as a JS string, avoiding n8n's delimiter scan even inside strings. */
+export declare function javascriptJsonLiteral(value: unknown): string;

package/dist/utils/javascript-json-literal.js

@@ -0,0 +1,10 @@
+/** Encode data as a JS string, avoiding n8n's delimiter scan even inside strings. */
+export function javascriptJsonLiteral(value) {
+    const json = JSON.stringify(value);
+    if (json === undefined)
+        throw new Error('Runtime data must be JSON-serializable');
+    const literal = JSON.stringify(json)
+        .replaceAll('{', '\\u007b')
+        .replaceAll('}', '\\u007d');
+    return `JSON.parse(${literal})`;
+}

package/dist/utils/json-values-equal.cjs

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/** JSON Schema equality is structural; JavaScript prototypes are not JSON data. */
+function jsonValuesEqual(left, right) {
+    if (left === right)
+        return true;
+    if (left === null ||
+        right === null ||
+        typeof left !== 'object' ||
+        typeof right !== 'object')
+        return false;
+    if (Array.isArray(left) !== Array.isArray(right))
+        return false;
+    if (Array.isArray(left) &&
+        Array.isArray(right) &&
+        left.length !== right.length)
+        return false;
+    const keys = Object.keys(left);
+    return (keys.length === Object.keys(right).length &&
+        keys.every((key) => Object.hasOwn(right, key) &&
+            jsonValuesEqual(Reflect.get(left, key), Reflect.get(right, key))));
+}
+// Ajv standalone requires a CommonJS module's plain default field.
+module.exports = { default: jsonValuesEqual };

package/dist/utils/json-values-equal.d.cts

@@ -0,0 +1 @@
+export {};

package/dist/workflow/assemble-n8n-workflow.d.ts

@@ -0,0 +1,2 @@
+import type { AssembleN8nWorkflowInput, N8nCompileResult } from '../types/workflow-compilation.js';
+export declare function assembleN8nWorkflow(input: AssembleN8nWorkflowInput): N8nCompileResult;

package/dist/workflow/assemble-n8n-workflow.js

@@ -0,0 +1,11 @@
+import { buildN8nWorkflow } from './build-n8n-workflow.js';
+export function assembleN8nWorkflow(input) {
+    return {
+        status: 'complete',
+        workflow: buildN8nWorkflow({
+            ...input,
+            triggerConnections: 'connected',
+            annotations: [],
+        }),
+    };
+}

package/dist/workflow/batch/compile-batched-n8n-workflow.d.ts

@@ -0,0 +1,3 @@
+import type { CompileBatchedN8nWorkflowInput } from '../../types/batch-execution.js';
+import type { N8nCompileResult } from '../../types/workflow-compilation.js';
+export declare function compileBatchedN8nWorkflow(input: CompileBatchedN8nWorkflowInput): N8nCompileResult;

package/dist/workflow/batch/compile-batched-n8n-workflow.js

@@ -0,0 +1,36 @@
+import { batchExecutionScopesSchema } from '../../schemas/batch-execution-schema.js';
+import { compileValidatedWorkflowFragments } from '../compile-validated-workflow-fragments.js';
+import { buildN8nWorkflow } from '../build-n8n-workflow.js';
+import { prepareNativeRuntimeInputs, assembleNativeRuntimeInputs, } from '../inputs/compile-native-runtime-inputs.js';
+export function compileBatchedN8nWorkflow(input) {
+    const batchScopes = batchExecutionScopesSchema.parse(input.batchScopes);
+    const nativeInputs = prepareNativeRuntimeInputs({
+        nativeInputs: input.nativeInputs,
+        nativeNodes: input.plan.nativeNodes,
+        capabilities: input.capabilities,
+        apiMaterials: input.materials.map((item) => ({
+            callId: item.arguments.callId,
+            operation: item.operation,
+            requestMediaType: item.arguments.requestMediaType,
+        })),
+        nativeOutputs: [],
+    });
+    const graph = {
+        id: input.id,
+        name: input.name,
+        nodes: compileValidatedWorkflowFragments(nativeInputs === undefined
+            ? input
+            : { ...input, capabilities: nativeInputs.capabilities }),
+        edges: input.plan.edges,
+        starts: input.plan.starts,
+        triggerConnections: 'connected',
+        annotations: [],
+        batchScopes,
+    };
+    const result = nativeInputs === undefined
+        ? { workflow: buildN8nWorkflow(graph) }
+        : assembleNativeRuntimeInputs({ ...graph, nativeInputs });
+    const workflow = result.workflow;
+    workflow.settings = { ...workflow.settings, executionOrder: 'v1' };
+    return { status: 'complete', ...result };
+}

package/dist/workflow/batch/create-batch-execution-scopes.d.ts

@@ -0,0 +1,3 @@
+import type { CreateBatchExecutionScopesInput, CompiledN8nBatchExecutionScope } from '../../types/batch-execution.js';
+/** Lower explicitly bounded, cardinality-preserving paths; never allow arbitrary cycles. */
+export declare function createBatchExecutionScopes(input: CreateBatchExecutionScopesInput): CompiledN8nBatchExecutionScope[];

package/dist/workflow/batch/create-batch-execution-scopes.js

@@ -0,0 +1,59 @@
+import { node } from '@n8n/workflow-sdk';
+import { batchExecutionScopesSchema } from '../../schemas/batch-execution-schema.js';
+import { validateBatchItemFlow } from './validate-batch-item-flow.js';
+/** Lower explicitly bounded, cardinality-preserving paths; never allow arbitrary cycles. */
+export function createBatchExecutionScopes(input) {
+    const scopes = batchExecutionScopesSchema.parse(input.batchScopes);
+    const fragments = new Map(input.nodes.map((fragment) => [fragment.nodeId, fragment]));
+    const owners = new Set();
+    const ids = new Set();
+    return scopes.map((scope) => {
+        const members = new Set(scope.nodeIds);
+        if (ids.has(scope.id) ||
+            members.size !== scope.nodeIds.length ||
+            !members.has(scope.entryNodeId) ||
+            !members.has(scope.exitNodeId))
+            throw new Error(`batch ${scope.id}: duplicate scope/member identity or missing entry/exit member`);
+        ids.add(scope.id);
+        for (const id of members) {
+            const fragment = fragments.get(id);
+            if (!fragment || owners.has(id))
+                throw new Error(`batch ${scope.id}: missing or overlapping member ${id}`);
+            owners.add(id);
+            const incoming = input.edges.filter((edge) => edge.to === id);
+            const outgoing = input.edges.filter((edge) => edge.from === id);
+            if (incoming.some((edge) => !members.has(edge.from) && id !== scope.entryNodeId) ||
+                outgoing.some((edge) => !members.has(edge.to) && id !== scope.exitNodeId))
+                throw new Error(`batch ${scope.id}: member ${id} crosses the entry/exit boundary`);
+            if (id !== scope.entryNodeId && input.starts.includes(id))
+                throw new Error(`batch ${scope.id}: only its entry may be a workflow start`);
+        }
+        validateBatchItemFlow({
+            scope,
+            fragments,
+            edges: input.edges,
+            otherBatchNodeIds: new Set(scopes
+                .filter((other) => other.id !== scope.id)
+                .flatMap((other) => other.nodeIds)),
+        });
+        const entry = fragments.get(scope.entryNodeId);
+        const position = entry.entry.config.position;
+        if (!Array.isArray(position) ||
+            position.length !== 2 ||
+            position.some((coordinate) => typeof coordinate !== 'number' || !Number.isFinite(coordinate)))
+            throw new Error(`batch ${scope.id}: entry ${scope.entryNodeId} requires config.position with two finite coordinates`);
+        return {
+            scope,
+            controller: node({
+                type: 'n8n-nodes-base.splitInBatches',
+                version: 3,
+                config: {
+                    id: scope.id,
+                    name: scope.id,
+                    position: [position[0] - 220, position[1]],
+                    parameters: { batchSize: scope.batchSize, options: { reset: false } },
+                },
+            }),
+        };
+    });
+}

package/dist/workflow/batch/validate-batch-exclusive-rejoin.d.ts

@@ -0,0 +1,3 @@
+import type { ValidateBatchItemFlowInput } from '../../types/batch-execution.js';
+/** Verify complete one-to-one paths, rather than interpreting item values or IDs. */
+export declare function validateBatchExclusiveRejoin(input: ValidateBatchItemFlowInput, nodeId: string): void;

package/dist/workflow/batch/validate-batch-exclusive-rejoin.js

@@ -0,0 +1,49 @@
+/** Verify complete one-to-one paths, rather than interpreting item values or IDs. */
+export function validateBatchExclusiveRejoin(input, nodeId) {
+    const { scope, fragments, edges } = input;
+    const sourceId = fragments.get(nodeId).rejoinsExclusiveOutputs;
+    const source = fragments.get(sourceId);
+    const target = fragments.get(nodeId);
+    const incoming = edges.filter((edge) => edge.to === nodeId);
+    if (!scope.nodeIds.includes(sourceId) ||
+        !source?.partitionsInputItems ||
+        target.preservesInputItems ||
+        target.joinsInputItemsByAncestry ||
+        Object.keys(target.outputPorts).join() !== 'main' ||
+        target.inputEndpoints ||
+        incoming.length !== Object.keys(target.inputPorts).length)
+        throw new Error(`batch ${scope.id}: rejoin ${nodeId} requires a complete partition in the same scope`);
+    const covered = new Set();
+    for (const port of Object.keys(target.inputPorts)) {
+        const paths = incoming.filter((edge) => edge.input === port);
+        if (paths.length !== 1)
+            throw new Error(`batch ${scope.id}: rejoin ${nodeId} requires exactly one path per input`);
+        let edge = paths[0];
+        const visited = new Set();
+        while (edge.from !== sourceId) {
+            const step = fragments.get(edge.from);
+            const predecessors = edges.filter((item) => item.to === edge.from);
+            if (!scope.nodeIds.includes(edge.from) ||
+                visited.has(edge.from) ||
+                !step ||
+                step.preservesInputItems !== true ||
+                step.joinsInputItemsByAncestry ||
+                step.partitionsInputItems ||
+                step.rejoinsExclusiveOutputs ||
+                step.inputEndpoints ||
+                Object.keys(step.inputPorts).join() !== 'main' ||
+                Object.keys(step.outputPorts).join() !== 'main' ||
+                predecessors.length !== 1 ||
+                edges.filter((item) => item.from === edge.from).length !== 1)
+                throw new Error(`batch ${scope.id}: rejoin ${nodeId} requires item-preserving paths from ${sourceId}`);
+            visited.add(edge.from);
+            edge = predecessors[0];
+        }
+        if (!Object.hasOwn(source.outputPorts, edge.output) ||
+            covered.has(edge.output))
+            throw new Error(`batch ${scope.id}: rejoin ${nodeId} repeats or omits an alternative of ${sourceId}`);
+        covered.add(edge.output);
+    }
+    if (covered.size !== Object.keys(source.outputPorts).length)
+        throw new Error(`batch ${scope.id}: rejoin ${nodeId} must return every alternative of ${sourceId}`);
+}

package/dist/workflow/batch/validate-batch-item-flow.d.ts

@@ -0,0 +1,3 @@
+import type { ValidateBatchItemFlowInput } from '../../types/batch-execution.js';
+/** Prove one result per entry item through declared preservation and ancestry joins. */
+export declare function validateBatchItemFlow({ scope, fragments, edges, otherBatchNodeIds, }: ValidateBatchItemFlowInput): void;

package/dist/workflow/batch/validate-batch-item-flow.js

@@ -0,0 +1,98 @@
+import { validateBatchExclusiveRejoin } from './validate-batch-exclusive-rejoin.js';
+/** Prove one result per entry item through declared preservation and ancestry joins. */
+export function validateBatchItemFlow({ scope, fragments, edges, otherBatchNodeIds, }) {
+    const members = new Set(scope.nodeIds);
+    const incoming = (id) => edges.filter((edge) => edge.to === id);
+    const outgoing = (id) => edges.filter((edge) => edge.from === id);
+    const upstream = incoming(scope.entryNodeId).filter((edge) => !members.has(edge.from));
+    if (upstream.length > 1)
+        throw new Error(`batch ${scope.id}: entry requires one upstream stream`);
+    const entryAncestors = new Set();
+    let preceding = upstream.map((edge) => edge.from);
+    while (preceding.length) {
+        const id = preceding.pop();
+        if (otherBatchNodeIds.has(id))
+            break;
+        if (entryAncestors.has(id))
+            throw new Error(`batch ${scope.id}: upstream item flow has a cycle`);
+        entryAncestors.add(id);
+        const fragment = fragments.get(id);
+        const sources = incoming(id);
+        if (fragment.preservesInputItems === true &&
+            !fragment.joinsInputItemsByAncestry &&
+            Object.keys(fragment.inputPorts).join() === 'main' &&
+            Object.keys(fragment.outputPorts).join() === 'main' &&
+            !fragment.inputEndpoints &&
+            sources.length === 1)
+            preceding = [sources[0].from];
+    }
+    const ancestors = new Map();
+    const pending = [...members];
+    while (pending.length) {
+        const index = pending.findIndex((id) => incoming(id)
+            .filter((edge) => members.has(edge.from))
+            .every((edge) => ancestors.has(edge.from)));
+        if (index === -1)
+            throw new Error(`batch ${scope.id}: item flow has a cycle`);
+        const id = pending.splice(index, 1)[0];
+        const fragment = fragments.get(id);
+        const innerIncoming = incoming(id).filter((edge) => members.has(edge.from));
+        const innerOutgoing = outgoing(id).filter((edge) => members.has(edge.to));
+        if ((id === scope.entryNodeId
+            ? innerIncoming.length !== 0
+            : innerIncoming.length === 0) ||
+            (id === scope.exitNodeId
+                ? innerOutgoing.length !== 0
+                : innerOutgoing.length === 0))
+            throw new Error(`batch ${scope.id}: every member must lie between its entry and exit`);
+        const join = fragment.joinsInputItemsByAncestry;
+        const rejoin = fragment.rejoinsExclusiveOutputs;
+        const partition = fragment.partitionsInputItems;
+        if (partition &&
+            (fragment.preservesInputItems ||
+                join ||
+                rejoin ||
+                Object.keys(fragment.inputPorts).join() !== 'main' ||
+                fragment.inputEndpoints ||
+                Object.keys(fragment.outputPorts).length < 2 ||
+                Object.keys(fragment.outputPorts).some((port) => innerOutgoing.filter((edge) => edge.output === port).length !== 1)))
+            throw new Error(`batch ${scope.id}: item-preserving main path contract requires every partition output of ${id} to return exactly once`);
+        if ((!partition && Object.keys(fragment.outputPorts).join() !== 'main') ||
+            (!join &&
+                !partition &&
+                !rejoin &&
+                (fragment.preservesInputItems !== true ||
+                    Object.keys(fragment.inputPorts).join() !== 'main' ||
+                    fragment.inputEndpoints)) ||
+            (join && fragment.preservesInputItems === true))
+            throw new Error(`batch ${scope.id}: member ${id} requires an item-preserving main path contract or an explicit ancestry join`);
+        let inherited;
+        if (rejoin) {
+            validateBatchExclusiveRejoin({ scope, fragments, edges, otherBatchNodeIds }, id);
+            const branches = innerIncoming.map((edge) => ancestors.get(edge.from));
+            inherited = new Set([...branches[0]].filter((ancestor) => branches.every((branch) => branch.has(ancestor))));
+        }
+        else if (join) {
+            const ports = Object.keys(fragment.inputPorts);
+            if (id === scope.entryNodeId ||
+                ports.length < 2 ||
+                ports.some((port) => innerIncoming.filter((edge) => edge.input === port).length !== 1) ||
+                innerIncoming.length !== ports.length)
+                throw new Error(`batch ${scope.id}: join ${id} requires exactly one branch per declared input`);
+            const branchAncestors = innerIncoming.map((edge) => ancestors.get(edge.from));
+            if (!fragment.bindingSources?.some((source) => source.kind === 'native-json' && source.nodeId === join.scopeNodeId) ||
+                branchAncestors.some((branch) => !branch.has(join.scopeNodeId)))
+                throw new Error(`batch ${scope.id}: join ${id} scope ${join.scopeNodeId} must identify each entry item on every branch`);
+            inherited = new Set([...branchAncestors[0]].filter((ancestor) => branchAncestors.every((branch) => branch.has(ancestor))));
+        }
+        else {
+            if (id !== scope.entryNodeId && innerIncoming.length !== 1)
+                throw new Error(`batch ${scope.id}: member ${id} requires one incoming item stream; use an explicit ancestry join for branches`);
+            inherited =
+                id === scope.entryNodeId
+                    ? entryAncestors
+                    : ancestors.get(innerIncoming[0].from);
+        }
+        ancestors.set(id, new Set([...inherited, id]));
+    }
+}

package/dist/workflow/build-n8n-workflow.d.ts

@@ -0,0 +1,2 @@
+import type { BuildN8nWorkflowInput, N8nWorkflowJSON } from '../types/workflow-compilation.js';
+export declare function buildN8nWorkflow({ id, name, nodes, edges, starts, triggerConnections, annotations, batchScopes, }: BuildN8nWorkflowInput): N8nWorkflowJSON;

package/dist/workflow/build-n8n-workflow.js

@@ -0,0 +1,140 @@
+import { workflow, validateWorkflow } from '@n8n/workflow-sdk';
+import { createN8nManualTrigger } from './entrypoint/manual-trigger.js';
+import { validateNodeFragments } from './validate-node-fragments.js';
+import { createBatchExecutionScopes } from './batch/create-batch-execution-scopes.js';
+export function buildN8nWorkflow({ id, name, nodes, edges, starts, triggerConnections, annotations, batchScopes, }) {
+    if (!['connected', 'detached'].includes(triggerConnections))
+        throw new Error('triggerConnections must be connected or detached');
+    if (!Array.isArray(annotations) ||
+        annotations.some((item) => item.type !== 'n8n-nodes-base.stickyNote'))
+        throw new Error('workflow annotations must be Sticky Notes');
+    if (typeof id !== 'string' ||
+        !id.trim() ||
+        typeof name !== 'string' ||
+        !name.trim())
+        throw new Error('workflow.id and workflow.name must be non-empty');
+    if (!Array.isArray(nodes) ||
+        nodes.length === 0 ||
+        !Array.isArray(edges) ||
+        !Array.isArray(starts) ||
+        starts.length === 0)
+        throw new Error('workflow requires nodes, edges and explicit starts');
+    if (nodes.some((fragment) => fragment.nodes.some((item) => 'isTrigger' in item && item.isTrigger === true)))
+        throw new Error('workflow fragments must not introduce an additional trigger');
+    const byId = new Map(nodes.map((fragment) => [fragment.nodeId, fragment]));
+    if (byId.size !== nodes.length ||
+        nodes.some((fragment) => !fragment.nodeId.trim()))
+        throw new Error('workflow nodes require unique non-empty nodeId');
+    const batches = batchScopes === undefined
+        ? []
+        : createBatchExecutionScopes({
+            id,
+            name,
+            nodes,
+            edges,
+            starts,
+            batchScopes,
+        });
+    const sdkNodes = [
+        ...nodes.flatMap((fragment) => fragment.nodes),
+        ...annotations,
+        ...batches.map((batch) => batch.controller),
+    ];
+    const sdkIds = sdkNodes.map((node) => node.id);
+    const sdkNames = sdkNodes.map((node) => node.name);
+    if (new Set(sdkIds).size !== sdkIds.length ||
+        new Set(sdkNames).size !== sdkNames.length ||
+        sdkNames.includes('Start') ||
+        sdkIds.includes('openapi-flow-start'))
+        throw new Error('workflow SDK node IDs and names must be unique and not use the Start trigger identity');
+    validateNodeFragments(nodes);
+    if (starts.some((id) => {
+        const fragment = byId.get(id);
+        return (fragment?.inputEndpoints &&
+            new Set(Object.values(fragment.inputEndpoints).map((endpoint) => endpoint.nodeId)).size > 1);
+    }))
+        throw new Error('workflow starts cannot bypass independent fragment input endpoints');
+    const successors = new Map(nodes.map((fragment) => [fragment.nodeId, []]));
+    const inbound = new Map(nodes.map((fragment) => [fragment.nodeId, 0]));
+    const edgeIds = new Set();
+    for (const edge of edges) {
+        const source = byId.get(edge.from);
+        const target = byId.get(edge.to);
+        if (!source || !target)
+            throw new Error(`edge ${edge.from} -> ${edge.to} references a missing node`);
+        if (!Object.hasOwn(source.outputPorts, edge.output) ||
+            !Object.hasOwn(target.inputPorts, edge.input))
+            throw new Error(`edge ${edge.from} -> ${edge.to} references an undeclared port`);
+        const key = JSON.stringify(edge);
+        if (edgeIds.has(key))
+            throw new Error(`duplicate edge ${edge.from} -> ${edge.to}`);
+        edgeIds.add(key);
+        successors.get(edge.from).push(edge.to);
+        inbound.set(edge.to, inbound.get(edge.to) + 1);
+    }
+    const roots = [...inbound]
+        .filter(([, count]) => count === 0)
+        .map(([nodeId]) => nodeId);
+    if (new Set(starts).size !== starts.length ||
+        starts.some((nodeId) => !roots.includes(nodeId)) ||
+        roots.some((nodeId) => !starts.includes(nodeId)))
+        throw new Error('workflow.starts must identify every root exactly once');
+    const pending = [...roots];
+    let visited = 0;
+    while (pending.length) {
+        const current = pending.shift();
+        visited++;
+        for (const next of successors.get(current)) {
+            const count = inbound.get(next) - 1;
+            inbound.set(next, count);
+            if (count === 0)
+                pending.push(next);
+        }
+    }
+    if (visited !== nodes.length)
+        throw new Error('workflow DAG has a cycle');
+    const start = createN8nManualTrigger();
+    let built = workflow(id, name).add(start);
+    for (const fragment of nodes)
+        for (const node of fragment.nodes)
+            built = built.add(node);
+    for (const batch of batches) {
+        built = built.add(batch.controller);
+        built = built.connect(batch.controller, 1, byId.get(batch.scope.entryNodeId).entry, byId.get(batch.scope.entryNodeId).inputPorts.main);
+        built = built.connect(byId.get(batch.scope.exitNodeId).exit, byId.get(batch.scope.exitNodeId).outputPorts.main, batch.controller, 0);
+    }
+    for (const fragment of nodes)
+        for (const edge of fragment.internalEdges ?? [])
+            built = built.connect(fragment.nodes.find((item) => item.id === edge.from), edge.output, fragment.nodes.find((item) => item.id === edge.to), edge.input);
+    if (triggerConnections === 'connected')
+        for (const nodeId of starts)
+            built = built.connect(start, 0, batches.find((batch) => batch.scope.entryNodeId === nodeId)
+                ?.controller ?? byId.get(nodeId).entry, 0);
+    for (const note of annotations)
+        built = built.add(note);
+    for (const edge of edges) {
+        const source = byId.get(edge.from);
+        const target = byId.get(edge.to);
+        const endpoint = target.inputEndpoints?.[edge.input];
+        const sourceBatch = batches.find((batch) => batch.scope.exitNodeId === edge.from &&
+            !batch.scope.nodeIds.includes(edge.to));
+        const targetBatch = batches.find((batch) => batch.scope.entryNodeId === edge.to &&
+            !batch.scope.nodeIds.includes(edge.from));
+        built = built.connect(sourceBatch ? sourceBatch.controller : source.exit, sourceBatch ? 0 : source.outputPorts[edge.output], targetBatch
+            ? targetBatch.controller
+            : endpoint
+                ? target.nodes.find((node) => node.id === endpoint.nodeId)
+                : target.entry, targetBatch
+            ? 0
+            : endpoint
+                ? endpoint.input
+                : target.inputPorts[edge.input]);
+    }
+    const checked = validateWorkflow(built);
+    if (!checked.valid)
+        throw new Error(`n8n SDK validation failed: ${checked.errors.map((error) => error.message).join('; ')}`);
+    const result = built.toJSON();
+    if (triggerConnections === 'detached')
+        result.active = false;
+    return result;
+}

package/dist/workflow/compile-native-material-fragments.d.ts

@@ -0,0 +1,3 @@
+import type { CompileNativeMaterialFragmentsInput, CompiledNativeMaterialFragments } from '../types/native-material-binding.js';
+/** Compile dependency names from actual SDK exits; graph execution order is still owned by explicit edges. */
+export declare function compileNativeMaterialFragments(input: CompileNativeMaterialFragmentsInput): CompiledNativeMaterialFragments;

package/dist/workflow/compile-native-material-fragments.js

@@ -0,0 +1,76 @@
+/** Compile dependency names from actual SDK exits; graph execution order is still owned by explicit edges. */
+export function compileNativeMaterialFragments(input) {
+    const registry = new Map(input.materials.capabilities.map((capability) => [
+        capability.name,
+        capability,
+    ]));
+    const selected = new Set(input.nodeIds);
+    if (selected.size !== input.nodeIds.length ||
+        input.nodeIds.some((id) => !input.nativeNodes.some((node) => node.id === id)))
+        throw new Error('Native compilation requires distinct actual selected nodeIds');
+    const pending = input.nativeNodes.filter((node) => selected.has(node.id));
+    const sources = [...input.externalNativeOutputSources];
+    const fragments = new Map();
+    const apiResponseContracts = Object.fromEntries(input.apiMaterials.map((material) => [material.callId, material.operation]));
+    let progressed = true;
+    while (pending.length && progressed) {
+        progressed = false;
+        for (let index = 0; index < pending.length;) {
+            const node = pending[index];
+            const capability = registry.get(node.capability);
+            if (!capability)
+                throw new Error(`Missing current native compiler ${node.capability}`);
+            const references = [
+                ...(capability.nodeOutputReferences
+                    ? capability.nodeOutputReferences(node.parameters)
+                    : []),
+                ...Object.values(capability.inputReferences
+                    ? capability.inputReferences(node.parameters)
+                    : {})
+                    .flat()
+                    .filter((reference) => reference.source === 'node-output'),
+            ];
+            if (references.some((reference) => !sources.some((source) => source.nodeId === reference.nodeId))) {
+                index++;
+                continue;
+            }
+            const compiled = capability.compile({
+                planned: node,
+                apiNodeNames: input.apiNodeNames,
+                apiResponseContracts,
+                singletonApiResponseIds: input.singletonApiResponseIds,
+                nativeOutputSources: sources,
+                position: [
+                    600 +
+                        input.nativeNodes.findIndex((planned) => planned.id === node.id) *
+                            250,
+                    300,
+                ],
+            });
+            if (compiled.nodeId !== node.id ||
+                !compiled.exit.name.trim() ||
+                JSON.stringify(Object.keys(compiled.inputPorts)) !==
+                    JSON.stringify(capability.inputPorts(node.parameters)) ||
+                JSON.stringify(Object.keys(compiled.outputPorts)) !==
+                    JSON.stringify(capability.outputPorts(node.parameters)))
+                throw new Error(`Native compiler ${node.capability} violated declared node identity/ports`);
+            if (compiled.rejoinsExclusiveOutputs !==
+                capability.rejoinsExclusiveOutputs?.(node.parameters))
+                throw new Error(`Native compiler ${node.capability} violated declared rejoinsExclusiveOutputs`);
+            fragments.set(node.id, compiled);
+            const output = input.materials.outputs.find((output) => output.nodeId === node.id);
+            if (output)
+                sources.push({ ...output, nodeName: compiled.exit.name });
+            pending.splice(index, 1);
+            progressed = true;
+        }
+    }
+    if (pending.length)
+        throw new Error(`Native compilation is missing actual producer exits for ${pending.map((node) => node.id).join(', ')}`);
+    return {
+        fragments: input.nativeNodes
+            .filter((node) => selected.has(node.id))
+            .map((node) => fragments.get(node.id)),
+        outputSources: sources.filter((source) => selected.has(source.nodeId)),
+    };
+}

package/dist/workflow/compile-native-workflow-nodes.d.ts

@@ -0,0 +1,3 @@
+import type { CompileNativeWorkflowNodesInput } from '../types/native-capability.js';
+import type { N8nNodeFragment } from '../types/node-fragment.js';
+export declare function compileNativeWorkflowNodes(input: CompileNativeWorkflowNodesInput): N8nNodeFragment[];

package/dist/workflow/compile-native-workflow-nodes.js

@@ -0,0 +1,25 @@
+import { resolveN8nNativeMaterials } from './resolve-n8n-native-materials.js';
+import { compileNativeMaterialFragments } from './compile-native-material-fragments.js';
+import { findSingletonApiResponses } from './find-singleton-api-responses.js';
+export function compileNativeWorkflowNodes(input) {
+    const apiMaterials = input.materials.map((item) => ({
+        callId: item.arguments.callId,
+        operation: item.operation,
+        requestMediaType: item.arguments.requestMediaType,
+    }));
+    const materials = resolveN8nNativeMaterials({
+        apiMaterials,
+        nativeOutputs: [],
+        nativeNodes: input.plan.nativeNodes,
+        capabilities: input.capabilities,
+    });
+    return compileNativeMaterialFragments({
+        nativeNodes: input.plan.nativeNodes,
+        materials,
+        apiMaterials,
+        apiNodeNames: Object.fromEntries(input.apiNodes.map((item) => [item.nodeId, item.exit.name])),
+        singletonApiResponseIds: findSingletonApiResponses(input),
+        externalNativeOutputSources: [],
+        nodeIds: input.plan.nativeNodes.map((node) => node.id),
+    }).fragments;
+}

package/dist/workflow/compile-planned-n8n-workflow.d.ts

@@ -0,0 +1,3 @@
+import type { CompilePlannedN8nWorkflowInput } from '../types/native-capability.js';
+import type { N8nCompileResult } from '../types/workflow-compilation.js';
+export declare function compilePlannedN8nWorkflow(input: CompilePlannedN8nWorkflowInput): N8nCompileResult;