@openapi-flow/n8n 0.2.0 → 0.3.1

package/dist/nodes/native/create-response-collection-capability.js

@@ -1,7 +1,9 @@
+import { defineMaterialBoundCapability } from './common/define-material-bound-capability.js';
 import { node } from '@n8n/workflow-sdk';
 import { readFileSync } from 'node:fs';
 import { createResponseValueSchema } from '@openapi-flow/core';
 import { createResponseCollectionParametersSchema } from '../../schemas/response-collection-schema.js';
+import { responseCollectionDefinition } from './response-collection-definition.js';
 import { createOutputReaderCode } from '../request/bindings/create-output-reader-code.js';
 import { javascriptJsonLiteral } from '../../utils/javascript-json-literal.js';
 export function createResponseCollectionCapability(input) {
@@ -20,12 +22,14 @@ export function createResponseCollectionCapability(input) {
         createResponseValueSchema(material.operation, parameters.pointer);
         return material;
     }
-    return {
-        name: 'collect-api-responses',
-        description: 'Collect unchanged item-linked API response values from one incoming stream into {items: values} using n8n Aggregate. Validates each full OAS response first. Preserves null, nested arrays, duplicates and received order. Not a branch join. Empty streams do not trigger this node or create an artificial result.',
+    return defineMaterialBoundCapability({
+        ...responseCollectionDefinition,
         parametersSchema,
-        inputPorts: () => ['main'],
-        outputPorts: () => ['main'],
+        materialSources: {
+            apiMaterials: structuredClone(input.materials),
+            nativeOutputs: [],
+        },
+        bindMaterialContracts: (sources) => createResponseCollectionCapability({ materials: sources.apiMaterials }),
         responseReferences: (values) => {
             const parameters = parametersSchema.parse(values);
             source(parameters);
@@ -37,8 +41,6 @@ export function createResponseCollectionCapability(input) {
                 },
             ];
         },
-        waitsForAllInputs: false,
-        exclusiveOutputPorts: false,
         outputSchema: (values) => {
             const parameters = parametersSchema.parse(values);
             return {
@@ -128,5 +130,5 @@ export function createResponseCollectionCapability(input) {
                 ],
             };
         },
-    };
+    });
 }

package/dist/nodes/native/if-capability.js

@@ -3,6 +3,7 @@ import { ifParametersSchema } from '../../schemas/native-capability-schemas.js';
 import { createIfPlanningParametersSchema } from '../../schemas/create-native-comparison-planning-schema.js';
 import { createNativeFragment } from './common/create-native-fragment.js';
 import { responseReferences } from './common/response-references.js';
+import { responseReferenceBindings } from './common/response-reference-bindings.js';
 import { conditionExpression } from './response-check-code.js';
 import { createResponseCheckReader } from './response-checks/create-response-check-reader.js';
 import { createResponseCheckGuard } from './response-checks/create-response-check-guard.js';
@@ -11,19 +12,22 @@ export function createIfCapability(input = {}) {
         name: 'if',
         description: 'n8n IF: main input; true and false OUTPUT PORTS are mutually exclusive. Multiple edges from the SAME port all execute (fan-out) and can be joined. Type-strict declarative conditions.',
         parametersSchema: ifParametersSchema,
+        parameterReferenceSources: ['response'],
         createPlanningParametersSchema: createIfPlanningParametersSchema,
         inputPorts: () => ['main'],
         outputPorts: () => ['true', 'false'],
         responseReferences: (parameters) => responseReferences(ifParametersSchema.parse(parameters).conditions),
+        parameterReferenceBindings: (parameters) => responseReferenceBindings(ifParametersSchema.parse(parameters).conditions, '/conditions'),
         waitsForAllInputs: false,
         exclusiveOutputPorts: true,
-        compile: ({ planned, apiNodeNames, apiResponseContracts, position }) => {
+        compile: ({ planned, apiNodeNames, apiResponseContracts, singletonApiResponseIds, position, }) => {
             const parameters = ifParametersSchema.parse(planned.parameters);
             const reader = createResponseCheckReader({
                 nodeId: planned.id,
                 checks: parameters.conditions,
                 apiNodeNames,
                 apiResponseContracts,
+                singletonApiResponseIds,
                 linked: input.itemMode === 'linked',
             });
             const fragment = createNativeFragment(node({
@@ -43,7 +47,7 @@ export function createIfCapability(input = {}) {
                             },
                             conditions: parameters.conditions.map((check, index) => ({
                                 id: `${planned.id}-${index}`,
-                                leftValue: conditionExpression(check, apiNodeNames, input.itemMode === 'linked'),
+                                leftValue: conditionExpression(check, apiNodeNames, input.itemMode === 'linked', singletonApiResponseIds),
                                 rightValue: true,
                                 operator: { type: 'boolean', operation: 'equals' },
                             })),

package/dist/nodes/native/inputs/native-input-runtime.bundle.js

@@ -0,0 +1,24 @@
+/*! MIT License
+
+Copyright (c) 2026 carefreelife98
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+ */
+var OpenApiFlowNativeInputRuntime;
+(()=>{function f(e){if(e==="")return[];if(!e.startsWith("/")||/~(?![01])/u.test(e))throw new Error(`Invalid JSON Pointer: ${e}`);return e.slice(1).split("/").map(i=>i.replaceAll("~1","/").replaceAll("~0","~"))}function l(e){if(Array.isArray(e))return e.map(l);if(e===null||typeof e!="object")return e;let i=Object.create(null);for(let[c,r]of Object.entries(e))i[c]=l(r);return i}function y(e){let i=f(e.pointer);if(!i.length)throw new Error(`${e.source} must identify a JSON field`);let c=l(e.values),r=c;for(let[o,t]of i.entries()){if(Array.isArray(r)&&(!/^(0|[1-9][0-9]*)$/.test(t)||Number(t)>r.length))throw new Error(`${e.source} ${e.pointer} requires an explicit complete array prefix`);if(o===i.length-1){if(Object.hasOwn(r,t))throw new Error(`${e.source} conflicts with existing value at ${e.pointer}`);Reflect.set(r,t,l(e.value))}else{if(!Object.hasOwn(r,t)){let a="/"+i.slice(0,o+1).map(s=>s.replaceAll("~","~0").replaceAll("/","~1")).join("/");Reflect.set(r,t,e.containerKind(a)==="array"?[]:Object.create(null))}let n=Reflect.get(r,t);if(n===null||typeof n!="object")throw new Error(`${e.source} traverses non-container ${e.pointer}`);r=n}}return JSON.parse(JSON.stringify(c))}function d(e,i){let c=l(e.parameters),r=[...e.inputs].sort((o,t)=>{let n=f(o.targetPointer),a=f(t.targetPointer);for(let s=0;s<Math.min(n.length,a.length);s++)if(n[s]!==a[s])return/^(0|[1-9][0-9]*)$/.test(n[s])&&/^(0|[1-9][0-9]*)$/.test(a[s])?Number(n[s])-Number(a[s]):n[s].localeCompare(a[s]);return n.length-a.length});for(let o of r){if(!Object.hasOwn(i,o.id))throw new Error(`Missing native runtime input ${o.id} for ${e.nodeId}${o.targetPointer}`);let t=i[o.id];if(o.targetPointer===""){if(r.length!==1||Object.keys(c).length||t===null||typeof t!="object"||Array.isArray(t))throw new Error(`Native runtime input ${e.nodeId} must be an exclusive JSON parameter object`);c=l(t)}else c=y({values:c,pointer:o.targetPointer,value:t,source:`Native runtime input ${e.nodeId}`,containerKind(n){if(!Object.hasOwn(o.containerKinds,n))throw new Error(`Native runtime input ${e.nodeId} has no declared container at ${n}`);return o.containerKinds[n]}})}return c}OpenApiFlowNativeInputRuntime={materializeNativeRuntimeParameters:d};})();

package/dist/nodes/native/inputs/prepend-native-parameter-guard.d.ts

@@ -0,0 +1,4 @@
+import type { PrependNativeParameterGuardInput } from '../../../types/native-runtime-parameters.js';
+import type { N8nNodeFragment } from '../../../types/node-fragment.js';
+/** Validate the unchanged declared parameter object again immediately before the native node. */
+export declare function prependNativeParameterGuard({ input, capability, fragment, }: PrependNativeParameterGuardInput): N8nNodeFragment;

package/dist/nodes/native/inputs/prepend-native-parameter-guard.js

@@ -0,0 +1,52 @@
+import { node } from '@n8n/workflow-sdk';
+import { readFileSync } from 'node:fs';
+import { isDeepStrictEqual } from 'node:util';
+import { createNativeRuntimeParameterMaterializations } from '@openapi-flow/core';
+import { compileStandaloneValidator } from '../../common/validation/compile-standalone-validator.js';
+import { javascriptJsonLiteral } from '../../../utils/javascript-json-literal.js';
+/** Validate the unchanged declared parameter object again immediately before the native node. */
+export function prependNativeParameterGuard({ input, capability, fragment, }) {
+    const configuration = input.runtimeInput;
+    if (!configuration ||
+        typeof configuration.inputNodeName !== 'string' ||
+        !configuration.inputNodeName.trim() ||
+        !Number.isSafeInteger(configuration.revision) ||
+        configuration.revision < 0)
+        throw new Error(`node ${input.planned.id}: runtime parameters require an explicit template input source and revision`);
+    const [materialization] = createNativeRuntimeParameterMaterializations({
+        nativeNodes: [input.planned],
+        capabilities: [capability],
+    });
+    if (!materialization ||
+        !isDeepStrictEqual(materialization, configuration.materialization))
+        throw new Error(`node ${input.planned.id}: runtime parameter slot differs from its original capability contract`);
+    const validator = compileStandaloneValidator({
+        schema: materialization.schema,
+        globalName: 'OpenApiFlowNativeParametersValidator',
+    });
+    const runtime = readFileSync(new URL('./native-input-runtime.bundle.js', import.meta.url), 'utf8');
+    const read = `const configurations=$(${javascriptJsonLiteral(configuration.inputNodeName)}).all();if(configurations.length!==1)throw new Error('Native runtime input requires exactly one configuration item');const payload=configurations[0].json;if(!payload||payload.revision!==${configuration.revision})throw new Error('Missing or stale native input revision');if(!payload.values||typeof payload.values!=='object')throw new Error('Missing native runtime input values');const parameters=OpenApiFlowNativeInputRuntime.materializeNativeRuntimeParameters(${javascriptJsonLiteral(materialization)},payload.values);if(!OpenApiFlowNativeParametersValidator(parameters))throw new Error('Native runtime input violates original schema for '+${javascriptJsonLiteral(materialization.nodeId)}+': '+JSON.stringify(OpenApiFlowNativeParametersValidator.errors));`;
+    const guard = node({
+        type: 'n8n-nodes-base.code',
+        version: 2,
+        config: {
+            id: `${input.planned.id}-parameters`,
+            name: `Parameters ${input.planned.id}`,
+            position: [input.position[0] - 220, input.position[1]],
+            parameters: {
+                mode: 'runOnceForAllItems',
+                language: 'javaScript',
+                jsCode: `${runtime}\n${validator}\n${read}\nreturn $input.all().map((_,index)=>({json:parameters,pairedItem:{item:index}}));`,
+            },
+        },
+    });
+    return {
+        ...fragment,
+        entry: guard,
+        nodes: [guard, ...fragment.nodes],
+        internalEdges: [
+            { from: guard.id, output: 0, to: fragment.entry.id, input: 0 },
+            ...(fragment.internalEdges === undefined ? [] : fragment.internalEdges),
+        ],
+    };
+}

package/dist/nodes/native/item-join/create-bound-item-join-capability.d.ts

@@ -0,0 +1,3 @@
+import type { N8nNativeCapability } from '../../../types/native-capability.js';
+import type { BoundItemJoinCapabilityInput } from '../../../types/native-material-binding.js';
+export declare function createBoundItemJoinCapability({ materials, scopes, runtime: sourceBinding, }: BoundItemJoinCapabilityInput): N8nNativeCapability;

package/dist/nodes/native/item-join/create-bound-item-join-capability.js

@@ -0,0 +1,169 @@
+import { defineMaterialBoundCapability } from '../common/define-material-bound-capability.js';
+import { node } from '@n8n/workflow-sdk';
+import { readFileSync } from 'node:fs';
+import { createResponseValueSchema, validateNativeOutputContracts, } from '@openapi-flow/core';
+import { resolveNativeRuntimeSource } from '../common/resolve-native-runtime-source.js';
+import { createItemJoinParametersSchema } from '../../../schemas/item-join-schema.js';
+import { itemJoinDefinition } from './item-join-definition.js';
+import { javascriptJsonLiteral } from '../../../utils/javascript-json-literal.js';
+import { createItemJoinReaderCode } from './create-item-join-reader-code.js';
+export function createBoundItemJoinCapability({ materials, scopes, runtime: sourceBinding, }) {
+    const apis = new Map(materials.map((material) => [material.callId, material]));
+    validateNativeOutputContracts(scopes);
+    const scopeContracts = scopes.map(({ nodeId, schema }) => ({
+        nodeId,
+        schema,
+    }));
+    const scopeById = new Map(scopeContracts.map((scope) => [scope.nodeId, scope]));
+    if (apis.size !== materials.length ||
+        materials.some((material) => !material.callId.trim()))
+        throw new Error('item join materials require unique non-empty callIds');
+    if (scopeById.size !== scopes.length ||
+        scopes.some((scope) => !scope.nodeId.trim()))
+        throw new Error('item join scopes require unique non-empty contract identities');
+    const parametersSchema = createItemJoinParametersSchema([...scopeById.keys()], [...apis.keys()]);
+    return defineMaterialBoundCapability({
+        ...itemJoinDefinition,
+        parametersSchema,
+        materialSources: {
+            apiMaterials: structuredClone(materials),
+            nativeOutputs: structuredClone(scopeContracts),
+        },
+        bindMaterialContracts: (sources) => createBoundItemJoinCapability({
+            materials: sources.apiMaterials,
+            scopes: sources.nativeOutputs,
+            runtime: { kind: 'compiled' },
+        }),
+        responseReferences: (values) => parametersSchema.parse(values).sourceCallIds.map((nodeId) => ({
+            source: 'response',
+            nodeId,
+            pointer: '',
+        })),
+        nodeOutputReferences: (values) => [
+            {
+                source: 'node-output',
+                nodeId: parametersSchema.parse(values).scopeNodeId,
+                pointer: '',
+            },
+        ],
+        inputReferences: (values) => {
+            const parameters = parametersSchema.parse(values);
+            return Object.fromEntries(parameters.sourceCallIds.map((nodeId, i) => [
+                `input${i + 1}`,
+                [
+                    { source: 'response', nodeId, pointer: '' },
+                    {
+                        source: 'node-output',
+                        nodeId: parameters.scopeNodeId,
+                        pointer: '',
+                    },
+                ],
+            ]));
+        },
+        outputSchema: (values) => {
+            const parameters = parametersSchema.parse(values);
+            return {
+                type: 'object',
+                required: ['responses'],
+                additionalProperties: false,
+                properties: {
+                    responses: {
+                        type: 'object',
+                        additionalProperties: false,
+                        required: parameters.sourceCallIds,
+                        properties: Object.fromEntries(parameters.sourceCallIds.map((id) => [
+                            id,
+                            createResponseValueSchema(apis.get(id).operation, ''),
+                        ])),
+                    },
+                },
+            };
+        },
+        compile: ({ planned, position, apiNodeNames, nativeOutputSources }) => {
+            const parameters = parametersSchema.parse(planned.parameters);
+            const scope = resolveNativeRuntimeSource({
+                binding: sourceBinding,
+                contract: scopeById.get(parameters.scopeNodeId),
+                compiledSources: nativeOutputSources,
+                consumerId: planned.id,
+            });
+            const bindingSources = [
+                { ...scope, kind: 'native-json' },
+                ...parameters.sourceCallIds.map((id) => {
+                    if (!Object.hasOwn(apiNodeNames, id) || !apiNodeNames[id].trim())
+                        throw new Error(`item join apiNodeNames is missing ${id}`);
+                    return {
+                        kind: 'api-response',
+                        nodeId: id,
+                        nodeName: apiNodeNames[id],
+                        operation: apis.get(id).operation,
+                    };
+                }),
+            ];
+            const readers = parameters.sourceCallIds.map((id, index) => node({
+                type: 'n8n-nodes-base.code',
+                version: 2,
+                config: {
+                    id: `${planned.id}-read-${index}`,
+                    name: `Read branch ${index + 1} ${planned.id}`,
+                    position: [position[0], position[1] + index * 180],
+                    parameters: {
+                        mode: 'runOnceForAllItems',
+                        jsCode: createItemJoinReaderCode({
+                            scope,
+                            sourceCallId: id,
+                            sources: [bindingSources[0], bindingSources[index + 1]],
+                        }),
+                    },
+                },
+            }));
+            const merge = node({
+                type: 'n8n-nodes-base.merge',
+                version: 3.2,
+                config: {
+                    id: `${planned.id}-wait`,
+                    name: `Wait branches ${planned.id}`,
+                    position: [position[0] + 220, position[1]],
+                    parameters: { mode: 'append', numberInputs: readers.length },
+                },
+            });
+            const runtime = readFileSync(new URL('./runtime/item-join-runtime.bundle.js', import.meta.url), 'utf8');
+            const joined = node({
+                type: 'n8n-nodes-base.code',
+                version: 2,
+                config: {
+                    id: planned.id,
+                    name: planned.id,
+                    position: [position[0] + 440, position[1]],
+                    parameters: {
+                        mode: 'runOnceForAllItems',
+                        jsCode: `${runtime}\nreturn OpenApiFlowItemJoinRuntime.joinApiItems({items:$input.all(),sourceCallIds:${javascriptJsonLiteral(parameters.sourceCallIds)}});`,
+                    },
+                },
+            });
+            return {
+                nodeId: planned.id,
+                joinsInputItemsByAncestry: { scopeNodeId: parameters.scopeNodeId },
+                nodes: [...readers, merge, joined],
+                entry: readers[0],
+                exit: joined,
+                inputPorts: Object.fromEntries(itemJoinDefinition.inputPorts(parameters).map((port) => [port, 0])),
+                inputEndpoints: Object.fromEntries(readers.map((reader, i) => [
+                    `input${i + 1}`,
+                    { nodeId: reader.id, input: 0 },
+                ])),
+                outputPorts: { main: 0 },
+                bindingSources,
+                internalEdges: [
+                    ...readers.map((reader, index) => ({
+                        from: reader.id,
+                        output: 0,
+                        to: merge.id,
+                        input: index,
+                    })),
+                    { from: merge.id, output: 0, to: joined.id, input: 0 },
+                ],
+            };
+        },
+    });
+}

package/dist/nodes/native/item-join/create-item-join-capability.d.ts

@@ -1,3 +1,4 @@
 import type { N8nNativeCapability } from '../../../types/native-capability.js';
 import type { CreateItemJoinCapabilityInput } from '../../../types/item-join.js';
-export declare function createItemJoinCapability({ materials, scopes, }: CreateItemJoinCapabilityInput): N8nNativeCapability;
+/** Preserve explicitly supplied original runtime names; later revisions bind contracts and SDK names separately. */
+export declare function createItemJoinCapability(input: CreateItemJoinCapabilityInput): N8nNativeCapability;

package/dist/nodes/native/item-join/create-item-join-capability.js

@@ -1,153 +1,10 @@
-import { node } from '@n8n/workflow-sdk';
-import { readFileSync } from 'node:fs';
-import { createResponseValueSchema } from '@openapi-flow/core';
-import { createItemJoinParametersSchema } from '../../../schemas/item-join-schema.js';
-import { javascriptJsonLiteral } from '../../../utils/javascript-json-literal.js';
-import { createItemJoinReaderCode } from './create-item-join-reader-code.js';
-export function createItemJoinCapability({ materials, scopes, }) {
-    const apis = new Map(materials.map((material) => [material.callId, material]));
-    const scopeById = new Map(scopes.map((scope) => [scope.nodeId, scope]));
-    if (apis.size !== materials.length ||
-        materials.some((material) => !material.callId.trim()))
-        throw new Error('item join materials require unique non-empty callIds');
-    if (scopeById.size !== scopes.length ||
-        scopes.some((scope) => !scope.nodeId.trim() || !scope.nodeName.trim()))
+import { createBoundItemJoinCapability } from './create-bound-item-join-capability.js';
+/** Preserve explicitly supplied original runtime names; later revisions bind contracts and SDK names separately. */
+export function createItemJoinCapability(input) {
+    if (input.scopes.some((scope) => typeof scope.nodeName !== 'string' || !scope.nodeName.trim()))
         throw new Error('item join scopes require unique non-empty identities and compiled names');
-    const parametersSchema = createItemJoinParametersSchema([...scopeById.keys()], [...apis.keys()]);
-    const ports = (count) => Array.from({ length: count }, (_, i) => `input${i + 1}`);
-    return {
-        name: 'join-api-items',
-        description: 'Join API branches by their shared native scope item ancestry. Each participating item requires exactly one full OAS-valid response per API. Different orders and duplicate JSON values are safe. Missing/duplicate branch responses fail; no business-ID matching, index zip, Cartesian product or value conversion. Output {responses: {callId: unchangedBody}}.',
-        parametersSchema,
-        inputPorts: (values) => ports(parametersSchema.parse(values).sourceCallIds.length),
-        outputPorts: () => ['main'],
-        responseReferences: (values) => parametersSchema.parse(values).sourceCallIds.map((nodeId) => ({
-            source: 'response',
-            nodeId,
-            pointer: '',
-        })),
-        nodeOutputReferences: (values) => [
-            {
-                source: 'node-output',
-                nodeId: parametersSchema.parse(values).scopeNodeId,
-                pointer: '',
-            },
-        ],
-        inputReferences: (values) => {
-            const parameters = parametersSchema.parse(values);
-            return Object.fromEntries(parameters.sourceCallIds.map((nodeId, i) => [
-                `input${i + 1}`,
-                [
-                    { source: 'response', nodeId, pointer: '' },
-                    {
-                        source: 'node-output',
-                        nodeId: parameters.scopeNodeId,
-                        pointer: '',
-                    },
-                ],
-            ]));
-        },
-        waitsForAllInputs: true,
-        exclusiveOutputPorts: false,
-        outputSchema: (values) => {
-            const parameters = parametersSchema.parse(values);
-            return {
-                type: 'object',
-                required: ['responses'],
-                additionalProperties: false,
-                properties: {
-                    responses: {
-                        type: 'object',
-                        additionalProperties: false,
-                        required: parameters.sourceCallIds,
-                        properties: Object.fromEntries(parameters.sourceCallIds.map((id) => [
-                            id,
-                            createResponseValueSchema(apis.get(id).operation, ''),
-                        ])),
-                    },
-                },
-            };
-        },
-        compile: ({ planned, position, apiNodeNames }) => {
-            const parameters = parametersSchema.parse(planned.parameters);
-            const scope = scopeById.get(parameters.scopeNodeId);
-            const bindingSources = [
-                { ...scope, kind: 'native-json' },
-                ...parameters.sourceCallIds.map((id) => {
-                    if (!Object.hasOwn(apiNodeNames, id) || !apiNodeNames[id].trim())
-                        throw new Error(`item join apiNodeNames is missing ${id}`);
-                    return {
-                        kind: 'api-response',
-                        nodeId: id,
-                        nodeName: apiNodeNames[id],
-                        operation: apis.get(id).operation,
-                    };
-                }),
-            ];
-            const readers = parameters.sourceCallIds.map((id, index) => node({
-                type: 'n8n-nodes-base.code',
-                version: 2,
-                config: {
-                    id: `${planned.id}-read-${index}`,
-                    name: `Read branch ${index + 1} ${planned.id}`,
-                    position: [position[0], position[1] + index * 180],
-                    parameters: {
-                        mode: 'runOnceForAllItems',
-                        jsCode: createItemJoinReaderCode({
-                            scope,
-                            sourceCallId: id,
-                            sources: [bindingSources[0], bindingSources[index + 1]],
-                        }),
-                    },
-                },
-            }));
-            const merge = node({
-                type: 'n8n-nodes-base.merge',
-                version: 3.2,
-                config: {
-                    id: `${planned.id}-wait`,
-                    name: `Wait branches ${planned.id}`,
-                    position: [position[0] + 220, position[1]],
-                    parameters: { mode: 'append', numberInputs: readers.length },
-                },
-            });
-            const runtime = readFileSync(new URL('./runtime/item-join-runtime.bundle.js', import.meta.url), 'utf8');
-            const joined = node({
-                type: 'n8n-nodes-base.code',
-                version: 2,
-                config: {
-                    id: planned.id,
-                    name: planned.id,
-                    position: [position[0] + 440, position[1]],
-                    parameters: {
-                        mode: 'runOnceForAllItems',
-                        jsCode: `${runtime}\nreturn OpenApiFlowItemJoinRuntime.joinApiItems({items:$input.all(),sourceCallIds:${javascriptJsonLiteral(parameters.sourceCallIds)}});`,
-                    },
-                },
-            });
-            return {
-                nodeId: planned.id,
-                joinsInputItemsByAncestry: { scopeNodeId: parameters.scopeNodeId },
-                nodes: [...readers, merge, joined],
-                entry: readers[0],
-                exit: joined,
-                inputPorts: Object.fromEntries(ports(readers.length).map((port) => [port, 0])),
-                inputEndpoints: Object.fromEntries(readers.map((reader, i) => [
-                    `input${i + 1}`,
-                    { nodeId: reader.id, input: 0 },
-                ])),
-                outputPorts: { main: 0 },
-                bindingSources,
-                internalEdges: [
-                    ...readers.map((reader, index) => ({
-                        from: reader.id,
-                        output: 0,
-                        to: merge.id,
-                        input: index,
-                    })),
-                    { from: merge.id, output: 0, to: joined.id, input: 0 },
-                ],
-            };
-        },
-    };
+    return createBoundItemJoinCapability({
+        ...input,
+        runtime: { kind: 'provided', sources: input.scopes },
+    });
 }

package/dist/nodes/native/item-join/item-join-definition.d.ts

@@ -0,0 +1,2 @@
+import type { NativeMaterialFeatureDefinition } from '../../../types/native-material-binding.js';
+export declare const itemJoinDefinition: NativeMaterialFeatureDefinition;

package/dist/nodes/native/item-join/item-join-definition.js

@@ -0,0 +1,33 @@
+import { itemJoinParametersSchema } from '../../../schemas/item-join-schema.js';
+export const itemJoinDefinition = {
+    name: 'join-api-items',
+    materialRequirements: [
+        { field: 'apiMaterials', minimumItems: 2 },
+        { field: 'nativeOutputs', minimumItems: 1 },
+    ],
+    description: 'Join API branches by their shared native scope item ancestry. Each participating item requires exactly one full OAS-valid response per API. Different orders and duplicate JSON values are safe. Missing/duplicate branch responses fail; no business-ID matching, index zip, Cartesian product or value conversion. Output {responses: {callId: unchangedBody}}.',
+    parametersSchema: itemJoinParametersSchema,
+    parameterReferenceSources: ['response', 'node-output'],
+    inputPorts: (values) => Array.from({ length: itemJoinParametersSchema.parse(values).sourceCallIds.length }, (_, index) => `input${index + 1}`),
+    outputPorts: () => ['main'],
+    referenceStructureSchema: itemJoinParametersSchema,
+    parameterReferenceBindings: (values) => {
+        const parameters = itemJoinParametersSchema.parse(values);
+        return [
+            ...parameters.sourceCallIds.map((nodeId, index) => ({
+                nodeIdPointer: `/sourceCallIds/${index}`,
+                reference: { source: 'response', nodeId, pointer: '' },
+            })),
+            {
+                nodeIdPointer: '/scopeNodeId',
+                reference: {
+                    source: 'node-output',
+                    nodeId: parameters.scopeNodeId,
+                    pointer: '',
+                },
+            },
+        ];
+    },
+    waitsForAllInputs: true,
+    exclusiveOutputPorts: false,
+};

package/dist/nodes/native/merge-append-capability.js

@@ -6,9 +6,11 @@ export function createMergeAppendCapability() {
         name: 'merge-append',
         description: 'n8n Merge append: input1..inputN; main output. Waits for all independent incoming branches.',
         parametersSchema: mergeParametersSchema,
+        parameterReferenceSources: [],
         inputPorts: (parameters) => Array.from({ length: mergeParametersSchema.parse(parameters).numberInputs }, (_, index) => `input${index + 1}`),
         outputPorts: () => ['main'],
         responseReferences: () => [],
+        parameterReferenceBindings: () => [],
         waitsForAllInputs: true,
         exclusiveOutputPorts: false,
         compile: ({ planned, position }) => {

package/dist/nodes/native/registry/native-feature-definitions.d.ts

@@ -0,0 +1,4 @@
+import { N8nNativeFeature } from '../../../types/native-feature-registry.js';
+import type { N8nNativeFeatureDefinition } from '../../../types/native-feature-registry.js';
+/** Material prerequisites belong to their actual factories, not model prompts. */
+export declare const nativeFeatureDefinitions: Record<N8nNativeFeature, N8nNativeFeatureDefinition>;