@openapi-flow/n8n 0.2.0 → 0.3.1

package/README.md

@@ -1,6 +1,34 @@
 # @openapi-flow/n8n
 
-Deterministic OpenAPI request-node creation and explicit n8n DAG assembly with the official workflow SDK. Unreleased `0.2.0` source; this package is not yet published.
+Zod `^4.6.5` is a required host peer for the public configuration schemas. It is not an independently pinned runtime dependency. The n8n SDK's internal Zod 3 remains separately owned; this does not pass a Zod 4 instance into an API requiring Zod 3.
+
+Version **0.3.1**, with matching `@openapi-flow/core@0.3.1`. Known limitation: Ajv 8.20.0 ignores a declared `properties.__proto__`. Generated validation can reject valid data or omit that property's constraints; do not rely on it for contracts using that key. The previously accepted limitation and original failing regression remain unchanged. No field substitution or schema compatibility transform is included. See the [release record](https://github.com/carefreelife98/openapi-flow/blob/main/docs/releases/0.3.1.md).
+
+`compileN8nWorkflowTemplate` supports canonical `gapNodes`. It preserves
+internal control edges, reuses Korean warning regions and stop-on-execution
+surrogates, and leaves Start detached. Full Core topology validation remains in
+place; the strict compiler still rejects unresolved plans. See the
+[gap contract](../../docs/workflow-draft-conversation-host.md#explicit-capability-gaps).
+
+templates retain API `requestedInputs` metadata and report requested
+optional values in their slots and Korean guide. Preflight and the final request
+materializer check presence separately from the unchanged OAS, including missing
+optional descendants of a response-bound object. Strict HTTP node creation also
+rejects missing requested literals. See [requested inputs](../../docs/workflow-draft-api-binding-questions.md#값이-미정인-선택-입력의-요청-추적).
+
+`resolveN8nNativePlanningFeatures` separates selectable implementation definitions from material readiness. Four source-dependent families can be selected before producers exist, then bind the original contracts through existing snapshots and SDK compilation. No guessed source schema or runtime name is used. See [planning and host integration](../../docs/native-feature-planning.md).
+
+material-dependent array/collection/item-join compilation rebinds current data contracts and resolves runtime names from actual SDK producer exits. `createN8nNativeOutputSources` requires actual `apiResponseContracts` for referenced APIs; partial subsets can declare external native outputs explicitly. Template requests accept `itemMode: 'linked'` for ancestry-preserving item streams. No old-contract/name fallback is used; custom compiler extensions must retain a coherent material binder. See [material snapshots and runtime proof](../../docs/native-material-snapshots.md).
+
+templates accept whole-object or explicit field-pointer runtime parameters for `createJsonOutputCapability` and StopAndError. A central editable input map, per-slot checks, full combined-object preflight and immediate native guards preserve original literals, schemas and revision. The compiler still uses official SDK Set/StopAndError nodes; structural settings are not guessed at execution time. Slots and the Korean guide identify where actual values belong. Staged planning/editing contracts are available, but older combined host factories do not automatically acquire them. See the [supported scope and checks](../../docs/native-runtime-inputs.md). These additions are not in npm 0.2.0.
+
+Standalone strict, reviewable and finite-batch compilation also accepts explicit `nativeInputs: { revision, inputValues? }`. A runtime-owned plan requires that configuration; there is no invented revision or template draft. Results with slots include `nativeInputTemplate` with original schemas, readiness, edit locations and a Korean guide. Missing actual values remain absent and fail at preflight before external calls. Review gaps retain internal wiring and warning regions with Start detached. Omission on literal-only plans preserves their existing result shape. See the [standalone compiler protocol](../../docs/native-runtime-inputs.md#standalone-compiler-input-protocol).
+
+`describeN8nManualTrigger()` exposes the compiler-owned start contract for requirement planning. Its description and actual SDK trigger creation share one module, so hosts can declare the existing start separately from selectable native instances. It is explicit planning metadata, not a registry default, deployment check or extra trigger node.
+
+`resolveN8nNativeFeatures` and `N8nNativeFeature` expose one registry for eleven existing feature families. Omission inventories every family with explicit `ready`/`requires-context` status; an explicit enum list is strict and `[]` selects none. Ready capabilities retain the existing schemas, source declarations and SDK compilers. Material-dependent families require actual OAS/native contracts, not invented placeholders. The published four-feature factory keeps its original selection. See the [registration and extension contract](../../docs/native-feature-registry.md).
+
+Deterministic OpenAPI request-node creation and explicit n8n DAG assembly with the official workflow SDK. Version `0.3.1` depends on matching core `0.3.1`.
 
 ## Installed declaration dependencies
 

package/dist/nodes/inputs/compile-template-input-validators.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowRuntimeInputSlot } from '@openapi-flow/core';
+/** Preserve every original $id and local $ref by compiling slot roots separately. */
+export declare function compileTemplateInputValidators(slots: WorkflowRuntimeInputSlot[]): string;

package/dist/nodes/inputs/compile-template-input-validators.js

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+import { createWorkflowRuntimeInputsSchema } from '@openapi-flow/core';
+import { createWorkflowInputValueMapSchema } from '../../schemas/workflow-input-value-map-schema.js';
+import { javascriptJsonLiteral } from '../../utils/javascript-json-literal.js';
+import { compileStandaloneValidator } from '../common/validation/compile-standalone-validator.js';
+/** Preserve every original $id and local $ref by compiling slot roots separately. */
+export function compileTemplateInputValidators(slots) {
+    const contract = createWorkflowRuntimeInputsSchema(slots);
+    const envelope = compileStandaloneValidator({
+        schema: z.toJSONSchema(createWorkflowInputValueMapSchema(Object.keys(contract.shape)), { io: 'input' }),
+        globalName: 'OpenApiFlowInputsValidator',
+    });
+    const values = Object.entries(contract.shape).map(([id, schema], index) => {
+        const name = `OpenApiFlowInputSlotValidator${index}`;
+        const validator = compileStandaloneValidator({
+            schema: z.toJSONSchema(schema, { io: 'input' }),
+            globalName: name,
+        });
+        const slot = slots.find((entry) => entry.id === id);
+        const presence = slot.kind === 'api-request-input' && slot.requestedInputs !== undefined
+            ? `\n{const missing=OpenApiFlowRequestRuntime.listMissingRequestedApiInputs({source:${javascriptJsonLiteral('Runtime input ' + id)},rootPointer:${javascriptJsonLiteral(slot.targetPointer)},value:payload.values[${javascriptJsonLiteral(id)}],requestedInputs:${javascriptJsonLiteral(slot.requestedInputs)}});if(missing.length)throw new Error('Workflow input omits scenario-requested inputs: '+missing.join(', '));}`
+            : '';
+        return `${validator}\nif(!${name}(payload.values[${javascriptJsonLiteral(id)}]))throw new Error('Workflow inputs do not match declared slots: '+${javascriptJsonLiteral(id)}+': '+JSON.stringify(${name}.errors));${presence}`;
+    });
+    return `${envelope}\nif(!OpenApiFlowInputsValidator(payload.values))throw new Error('Workflow inputs do not match declared slots: '+JSON.stringify(OpenApiFlowInputsValidator.errors));\n${values.join('\n')}`;
+}

package/dist/nodes/inputs/create-template-input-nodes.d.ts

@@ -0,0 +1,4 @@
+import type { CreateTemplateInputNodesInput } from '../../types/workflow-template.js';
+import type { N8nNodeFragment } from '../../types/node-fragment.js';
+/** Compile immutable contracts; the user edits only the separate actual-value map. */
+export declare function createTemplateInputNodes(input: CreateTemplateInputNodesInput): N8nNodeFragment[];

package/dist/nodes/inputs/create-template-input-nodes.js

@@ -0,0 +1,61 @@
+import { readFileSync } from 'node:fs';
+import { node } from '@n8n/workflow-sdk';
+import { javascriptJsonLiteral } from '../../utils/javascript-json-literal.js';
+import { compileTemplateInputValidators } from './compile-template-input-validators.js';
+import { compileRequestValidator } from '../request/bindings/compile-request-validator.js';
+import { compileStandaloneValidator } from '../common/validation/compile-standalone-validator.js';
+import { createNativeFragment } from '../native/common/create-native-fragment.js';
+import { TEMPLATE_INPUT_ID, TEMPLATE_INPUT_NAME, TEMPLATE_PREFLIGHT_ID, TEMPLATE_PREFLIGHT_NAME, } from '../../workflow/templates/workflow-template-identities.js';
+/** Compile immutable contracts; the user edits only the separate actual-value map. */
+export function createTemplateInputNodes(input) {
+    const validators = compileTemplateInputValidators(input.slots);
+    const setup = node({
+        type: 'n8n-nodes-base.code',
+        version: 2,
+        config: {
+            id: TEMPLATE_INPUT_ID,
+            name: TEMPLATE_INPUT_NAME,
+            position: [220, 0],
+            notes: '실제 값은 inputValues 객체에 슬롯 ID를 키로 추가하세요. 미입력 키는 생략하세요. 타입·스키마·revision은 바꾸지 마세요. 인증 비밀값은 n8n credential에 설정하세요.',
+            notesInFlow: true,
+            parameters: {
+                mode: 'runOnceForAllItems',
+                jsCode: `// 실제 값만 입력하세요. 미입력 값에 임시 값을 넣지 마세요.\nconst inputValues=${javascriptJsonLiteral(input.inputValues)};\nreturn [{json:{revision:${input.revision},values:inputValues}}];`,
+            },
+        },
+    });
+    const runtime = readFileSync(new URL('../request/runtime/request-runtime.bundle.js', import.meta.url), 'utf8');
+    const nativeRuntime = readFileSync(new URL('../native/inputs/native-input-runtime.bundle.js', import.meta.url), 'utf8');
+    // A request without runtime response dependencies can be checked completely
+    // before any branch performs an external call. Dependent requests are checked
+    // again by their materializers after the actual producers have executed.
+    const earlyChecks = input.requests
+        .filter((request) => !request.arguments.bindings.length)
+        .map((request, index) => {
+        const name = `OpenApiFlowInitialRequestValidator${index}`;
+        return `${compileRequestValidator(request, name)}\nOpenApiFlowRequestRuntime.materializeHttpRequest(${javascriptJsonLiteral(request)},Object.create(null),${name},payload.values);`;
+    });
+    const nativeChecks = input.nativeParameters.map((material, index) => {
+        const name = `OpenApiFlowInitialNativeValidator${index}`;
+        return `${compileStandaloneValidator({ schema: material.schema, globalName: name })}\n{const parameters=OpenApiFlowNativeInputRuntime.materializeNativeRuntimeParameters(${javascriptJsonLiteral(material)},payload.values);if(!${name}(parameters))throw new Error('Native runtime input violates complete original schema for '+${javascriptJsonLiteral(material.nodeId)}+': '+JSON.stringify(${name}.errors));}`;
+    });
+    const preflight = node({
+        type: 'n8n-nodes-base.code',
+        version: 2,
+        config: {
+            id: TEMPLATE_PREFLIGHT_ID,
+            name: TEMPLATE_PREFLIGHT_NAME,
+            position: [440, 0],
+            notes: '모든 초기 입력을 외부 호출 전에 검사합니다. 선행 응답을 사용하는 요청은 해당 응답을 합친 후 전송 직전에 전체 OAS를 다시 검사합니다. 부분 실행·pinning으로 검사를 건너뛰지 마세요.',
+            notesInFlow: true,
+            parameters: {
+                mode: 'runOnceForAllItems',
+                jsCode: `${runtime}\n${nativeRuntime}\nconst items=$input.all();if(items.length!==1)throw new Error('Workflow input setup requires exactly one JSON item');const payload=items[0].json;if(!payload||payload.revision!==${input.revision})throw new Error('Missing or stale workflow input revision');\n${validators}\n${nativeChecks.join('\n')}\n${earlyChecks.join('\n')}\nreturn [{json:payload,pairedItem:{item:0}}];`,
+            },
+        },
+    });
+    return [
+        createNativeFragment(setup, ['main'], ['main']),
+        createNativeFragment(preflight, ['main'], ['main']),
+    ];
+}

package/dist/nodes/native/arrays/create-bound-native-array-capability.d.ts

@@ -0,0 +1,4 @@
+import type { N8nNativeCapability } from '../../../types/native-capability.js';
+import type { BoundNativeArrayCapabilityInput } from '../../../types/native-material-binding.js';
+/** Data-contract binding is independent of runtime SDK producer names. */
+export declare function createBoundNativeArrayCapability(input: BoundNativeArrayCapabilityInput): N8nNativeCapability;

package/dist/nodes/native/arrays/create-bound-native-array-capability.js

@@ -0,0 +1,81 @@
+import { defineMaterialBoundCapability } from '../common/define-material-bound-capability.js';
+import { createNativeArrayItemSchema, validateNativeOutputContracts, } from '@openapi-flow/core';
+import { createNativeArrayParametersSchema } from '../../../schemas/native-array-schema.js';
+import { nativeArrayDefinition } from './native-array-definition.js';
+import { createArrayNodeFragment } from './create-array-node-fragment.js';
+import { resolveNativeRuntimeSource } from '../common/resolve-native-runtime-source.js';
+/** Data-contract binding is independent of runtime SDK producer names. */
+export function createBoundNativeArrayCapability(input) {
+    if (input.itemMode !== undefined && input.itemMode !== 'linked')
+        throw new Error('native array capability: itemMode must be linked or omitted');
+    validateNativeOutputContracts(input.sources);
+    if (!input.sources.length)
+        throw new Error('native array capability requires source contracts');
+    const contracts = input.sources.map(({ nodeId, schema }) => ({
+        nodeId,
+        schema,
+    }));
+    const sources = new Map(contracts.map((source) => [source.nodeId, source]));
+    const parametersSchema = createNativeArrayParametersSchema([
+        ...sources.keys(),
+    ]);
+    function source(parameters) {
+        const output = sources.get(parameters.sourceNodeId);
+        if (!output)
+            throw new Error(`native array: unknown sourceNodeId ${parameters.sourceNodeId}`);
+        createNativeArrayItemSchema(output, parameters.pointer);
+        return output;
+    }
+    return defineMaterialBoundCapability({
+        ...nativeArrayDefinition,
+        parametersSchema,
+        materialSources: {
+            apiMaterials: [],
+            nativeOutputs: structuredClone(contracts),
+        },
+        bindMaterialContracts: (contracts) => createBoundNativeArrayCapability({
+            sources: contracts.nativeOutputs,
+            itemMode: input.itemMode,
+            runtime: { kind: 'compiled' },
+        }),
+        responseReferences: () => [],
+        nodeOutputReferences: (values) => {
+            const parameters = parametersSchema.parse(values);
+            source(parameters);
+            return [
+                {
+                    source: 'node-output',
+                    nodeId: parameters.sourceNodeId,
+                    pointer: parameters.pointer,
+                },
+            ];
+        },
+        outputSchema: (values) => {
+            const parameters = parametersSchema.parse(values);
+            return {
+                type: 'object',
+                properties: {
+                    item: createNativeArrayItemSchema(source(parameters), parameters.pointer),
+                },
+                required: ['item'],
+                additionalProperties: false,
+            };
+        },
+        compile: ({ planned, position, nativeOutputSources }) => {
+            const parameters = parametersSchema.parse(planned.parameters);
+            const runtime = resolveNativeRuntimeSource({
+                binding: input.runtime,
+                contract: source(parameters),
+                compiledSources: nativeOutputSources,
+                consumerId: planned.id,
+            });
+            return createArrayNodeFragment({
+                planned,
+                position,
+                source: { ...runtime, kind: 'native-json' },
+                parameters,
+                linked: input.itemMode === 'linked',
+            });
+        },
+    });
+}

package/dist/nodes/native/arrays/create-native-array-capability.d.ts

@@ -1,3 +1,4 @@
 import type { N8nNativeCapability } from '../../../types/native-capability.js';
 import type { CreateNativeArrayCapabilityInput } from '../../../types/native-array.js';
+/** Existing explicitly named sources remain an immutable binding. New revisions bind contracts separately. */
 export declare function createNativeArrayCapability(input: CreateNativeArrayCapabilityInput): N8nNativeCapability;

package/dist/nodes/native/arrays/create-native-array-capability.js

@@ -1,64 +1,12 @@
-import { createNativeArrayItemSchema, validateNativeOutputContracts, } from '@openapi-flow/core';
-import { createNativeArrayParametersSchema } from '../../../schemas/native-array-schema.js';
-import { createArrayNodeFragment } from './create-array-node-fragment.js';
+import { createBoundNativeArrayCapability } from './create-bound-native-array-capability.js';
+/** Existing explicitly named sources remain an immutable binding. New revisions bind contracts separately. */
 export function createNativeArrayCapability(input) {
-    if (input.itemMode !== undefined && input.itemMode !== 'linked')
-        throw new Error('native array capability: itemMode must be linked or omitted');
-    validateNativeOutputContracts(input.sources);
     if (!input.sources.length ||
         input.sources.some((source) => typeof source.nodeName !== 'string' || !source.nodeName.trim()))
         throw new Error('native array capability requires sources with compiled names');
-    const sources = new Map(input.sources.map((source) => [source.nodeId, source]));
-    const parametersSchema = createNativeArrayParametersSchema([
-        ...sources.keys(),
-    ]);
-    function source(parameters) {
-        const output = sources.get(parameters.sourceNodeId);
-        if (!output)
-            throw new Error(`native array: unknown sourceNodeId ${parameters.sourceNodeId}`);
-        createNativeArrayItemSchema(output, parameters.pointer);
-        return { ...output, kind: 'native-json' };
-    }
-    return {
-        name: 'split-native-output-array',
-        description: 'Split a supplied native JSON output array into {item: unchangedElement} using official n8n Split Out. Validate the full native output schema first. Linked mode preserves parent ancestry across nested splits. Empty arrays emit no child items; never convert, flatten or fabricate values.',
-        parametersSchema,
-        inputPorts: () => ['main'],
-        outputPorts: () => ['main'],
-        responseReferences: () => [],
-        nodeOutputReferences: (values) => {
-            const parameters = parametersSchema.parse(values);
-            source(parameters);
-            return [
-                {
-                    source: 'node-output',
-                    nodeId: parameters.sourceNodeId,
-                    pointer: parameters.pointer,
-                },
-            ];
-        },
-        waitsForAllInputs: false,
-        exclusiveOutputPorts: false,
-        outputSchema: (values) => {
-            const parameters = parametersSchema.parse(values);
-            return {
-                type: 'object',
-                properties: {
-                    item: createNativeArrayItemSchema(source(parameters), parameters.pointer),
-                },
-                required: ['item'],
-                additionalProperties: false,
-            };
-        },
-        compile: ({ planned, position }) => {
-            const parameters = parametersSchema.parse(planned.parameters);
-            return createArrayNodeFragment({
-                planned,
-                position,
-                source: source(parameters),
-                parameters,
-                linked: input.itemMode === 'linked',
-            });
-        },
-    };
+    return createBoundNativeArrayCapability({
+        sources: input.sources,
+        itemMode: input.itemMode,
+        runtime: { kind: 'provided', sources: input.sources },
+    });
 }

package/dist/nodes/native/arrays/native-array-definition.d.ts

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

package/dist/nodes/native/arrays/native-array-definition.js

@@ -0,0 +1,27 @@
+import { nativeArrayParametersSchema } from '../../../schemas/native-array-schema.js';
+export const nativeArrayDefinition = {
+    name: 'split-native-output-array',
+    materialRequirements: [{ field: 'nativeOutputs', minimumItems: 1 }],
+    description: 'Split a supplied native JSON output array into {item: unchangedElement} using official n8n Split Out. Validate the full native output schema first. Linked mode preserves parent ancestry across nested splits. Empty arrays emit no child items; never convert, flatten or fabricate values.',
+    parametersSchema: nativeArrayParametersSchema,
+    parameterReferenceSources: ['node-output'],
+    inputPorts: () => ['main'],
+    outputPorts: () => ['main'],
+    referenceStructureSchema: nativeArrayParametersSchema,
+    parameterReferenceBindings: (values) => {
+        const parameters = nativeArrayParametersSchema.parse(values);
+        return [
+            {
+                nodeIdPointer: '/sourceNodeId',
+                valuePointer: '/pointer',
+                reference: {
+                    source: 'node-output',
+                    nodeId: parameters.sourceNodeId,
+                    pointer: parameters.pointer,
+                },
+            },
+        ];
+    },
+    waitsForAllInputs: false,
+    exclusiveOutputPorts: false,
+};

package/dist/nodes/native/common/create-material-planning-capability.d.ts

@@ -0,0 +1,4 @@
+import type { N8nNativeCapability } from '../../../types/native-capability.js';
+import type { NativeMaterialFeatureDefinition } from '../../../types/native-material-binding.js';
+/** A stable implementation definition, not a ready output contract or executable node. */
+export declare function createMaterialPlanningCapability(definition: NativeMaterialFeatureDefinition, bind: NonNullable<N8nNativeCapability['bindMaterialContracts']>): N8nNativeCapability;

package/dist/nodes/native/common/create-material-planning-capability.js

@@ -0,0 +1,14 @@
+import { defineMaterialBoundCapability } from './define-material-bound-capability.js';
+/** A stable implementation definition, not a ready output contract or executable node. */
+export function createMaterialPlanningCapability(definition, bind) {
+    function requireBinding() {
+        throw new Error(`Native feature ${definition.name} requires actual material contract binding before value references, output or compilation`);
+    }
+    return defineMaterialBoundCapability({
+        ...definition,
+        bindMaterialContracts: bind,
+        responseReferences: requireBinding,
+        outputSchema: requireBinding,
+        compile: requireBinding,
+    });
+}

package/dist/nodes/native/common/define-material-bound-capability.d.ts

@@ -0,0 +1,4 @@
+import type { MaterialBindableN8nCapability } from '../../../types/native-material-binding.js';
+import type { N8nNativeCapability } from '../../../types/native-capability.js';
+/** A material binder cannot silently discard a caller's different implementation or source receipt. */
+export declare function defineMaterialBoundCapability(definition: MaterialBindableN8nCapability): N8nNativeCapability;

package/dist/nodes/native/common/define-material-bound-capability.js

@@ -0,0 +1,33 @@
+import { isDeepStrictEqual } from 'node:util';
+/** A material binder cannot silently discard a caller's different implementation or source receipt. */
+export function defineMaterialBoundCapability(definition) {
+    if (definition.materialRequirements !== undefined)
+        definition.materialRequirements = structuredClone(definition.materialRequirements);
+    const requirements = structuredClone(definition.materialRequirements);
+    if (definition.parameterReferenceSources !== undefined)
+        definition.parameterReferenceSources = structuredClone(definition.parameterReferenceSources);
+    const referenceSources = structuredClone(definition.parameterReferenceSources);
+    const bind = definition.bindMaterialContracts;
+    const fields = new Map(Object.entries(definition).filter(([key]) => key !== 'bindMaterialContracts' && key !== 'materialSources'));
+    const receipts = structuredClone(definition.materialSources);
+    definition.bindMaterialContracts = function (sources) {
+        const changed = [...fields]
+            .filter(([key, value]) => Reflect.get(this, key) !== value)
+            .map(([key]) => key);
+        const extra = Object.keys(this).filter((key) => key !== 'bindMaterialContracts' &&
+            key !== 'materialSources' &&
+            !fields.has(key));
+        if (!isDeepStrictEqual(this.materialSources, receipts))
+            changed.push('materialSources');
+        if (!isDeepStrictEqual(this.parameterReferenceSources, referenceSources) &&
+            !changed.includes('parameterReferenceSources'))
+            changed.push('parameterReferenceSources');
+        if (!isDeepStrictEqual(this.materialRequirements, requirements) &&
+            !changed.includes('materialRequirements'))
+            changed.push('materialRequirements');
+        if (changed.length || extra.length)
+            throw new Error(`Native material definition ${definition.name} changed ${[...changed, ...extra].join(', ')} without a coherent bindMaterialContracts implementation`);
+        return bind.call(this, sources);
+    };
+    return definition;
+}

package/dist/nodes/native/common/resolve-native-runtime-source.d.ts

@@ -0,0 +1,3 @@
+import type { ResolveNativeRuntimeSourceInput } from '../../../types/native-material-binding.js';
+import type { N8nNativeOutputSource } from '../../../types/output-binding-source.js';
+export declare function resolveNativeRuntimeSource(input: ResolveNativeRuntimeSourceInput): N8nNativeOutputSource;

package/dist/nodes/native/common/resolve-native-runtime-source.js

@@ -0,0 +1,15 @@
+import { isDeepStrictEqual } from 'node:util';
+export function resolveNativeRuntimeSource(input) {
+    if (input.binding.kind === 'compiled' &&
+        !Array.isArray(input.compiledSources))
+        throw new Error(`Native ${input.consumerId}: compile.nativeOutputSources is required for the current material revision`);
+    const sources = input.binding.kind === 'provided'
+        ? input.binding.sources
+        : input.compiledSources;
+    const matches = sources.filter((source) => source.nodeId === input.contract.nodeId);
+    if (matches.length !== 1 ||
+        !matches[0].nodeName?.trim() ||
+        !isDeepStrictEqual(matches[0].schema, input.contract.schema))
+        throw new Error(`Native ${input.consumerId}: source ${input.contract.nodeId} requires exactly one matching actual compiled name/schema`);
+    return matches[0];
+}

package/dist/nodes/native/common/response-reference-bindings.d.ts

@@ -0,0 +1,4 @@
+import type { WorkflowNativeReferenceBinding } from '@openapi-flow/core';
+import type { NativeCheck } from '../../../types/native-capability.js';
+/** The comparison implementation owns these operand locations. */
+export declare function responseReferenceBindings(checks: NativeCheck[], prefix: string): WorkflowNativeReferenceBinding[];

package/dist/nodes/native/common/response-reference-bindings.js

@@ -0,0 +1,15 @@
+/** The comparison implementation owns these operand locations. */
+export function responseReferenceBindings(checks, prefix) {
+    return checks.flatMap((check, index) => ['left', 'right'].flatMap((side) => {
+        const operand = check[side];
+        return operand.source === 'response'
+            ? [
+                {
+                    nodeIdPointer: `${prefix}/${index}/${side}/nodeId`,
+                    valuePointer: `${prefix}/${index}/${side}/pointer`,
+                    reference: { ...operand },
+                },
+            ]
+            : [];
+    }));
+}

package/dist/nodes/native/create-exclusive-branch-merge-capability.js

@@ -7,6 +7,16 @@ export function createExclusiveBranchMergeCapability() {
         name: 'rejoin-exclusive-branches',
         description: 'Rejoin both alternative paths of one supplied IF instance using official Merge append. input1 and input2 each cover a distinct true/false path. Preserves existing items and ancestry; never creates an empty completion item. Both paths must return, including a skip path when no business call is required.',
         parametersSchema: exclusiveBranchMergeParametersSchema,
+        parameterReferenceSources: ['exclusive-output'],
+        parameterReferenceBindings: (parameters) => [
+            {
+                nodeIdPointer: '/sourceNodeId',
+                reference: {
+                    source: 'exclusive-output',
+                    nodeId: exclusiveBranchMergeParametersSchema.parse(parameters).sourceNodeId,
+                },
+            },
+        ],
         inputPorts: () => ['input1', 'input2'],
         outputPorts: () => ['main'],
         responseReferences: () => [],

package/dist/nodes/native/create-json-output-capability.js

@@ -3,21 +3,28 @@ import { z } from 'zod';
 import { parseNativeNodeParameters } from '@openapi-flow/core';
 import { javascriptJsonLiteral } from '../../utils/javascript-json-literal.js';
 import { createNativeFragment } from './common/create-native-fragment.js';
+import { prependNativeParameterGuard } from './inputs/prepend-native-parameter-guard.js';
 /** Explicit typed literals through Edit Fields JSON mode; no casts or mapping expressions. */
 export function createJsonOutputCapability(input) {
     if (!input.name.trim() || !input.description.trim())
         throw new Error('JSON output capability requires name and description');
     const capability = {
         ...input,
+        supportsRuntimeParameters: true,
         inputPorts: () => ['main'],
         outputPorts: () => ['main'],
         responseReferences: () => [],
+        parameterReferenceSources: [],
+        parameterReferenceBindings: () => [],
         waitsForAllInputs: false,
         exclusiveOutputPorts: false,
         outputSchema: () => z.toJSONSchema(input.parametersSchema, { io: 'output' }),
-        compile: ({ planned, position }) => {
-            const parameters = parseNativeNodeParameters(planned, capability);
-            return createNativeFragment(node({
+        compile: (source) => {
+            const { planned, position } = source;
+            const jsonOutput = planned.runtimeParameters !== undefined
+                ? '={{ JSON.stringify($json) }}'
+                : `={{ ${javascriptJsonLiteral(parseNativeNodeParameters(planned, capability))} }}`;
+            const fragment = createNativeFragment(node({
                 type: 'n8n-nodes-base.set',
                 version: 3.4,
                 config: {
@@ -26,12 +33,15 @@ export function createJsonOutputCapability(input) {
                     position,
                     parameters: {
                         mode: 'raw',
-                        jsonOutput: `={{ ${javascriptJsonLiteral(parameters)} }}`,
+                        jsonOutput,
                         includeOtherFields: false,
                         options: { dotNotation: false },
                     },
                 },
             }), ['main'], ['main']);
+            return planned.runtimeParameters !== undefined
+                ? prependNativeParameterGuard({ input: source, capability, fragment })
+                : fragment;
         },
     };
     return capability;

package/dist/nodes/native/create-native-capabilities.js

@@ -1,14 +1,15 @@
-import { createIfCapability } from './if-capability.js';
-import { createMergeAppendCapability } from './merge-append-capability.js';
-import { createResponseAssertionCapability } from './response-assertion-capability.js';
-import { createStopAndErrorCapability } from './stop-and-error-capability.js';
+import { resolveN8nNativeFeatures } from './registry/resolve-n8n-native-features.js';
+import { validateNativeFeatureContext } from './registry/validate-native-feature-context.js';
+import { N8nNativeFeature } from '../../types/native-feature-registry.js';
 export function createN8nNativeCapabilities(input = {}) {
-    if (input.itemMode !== undefined && input.itemMode !== 'linked')
-        throw new Error('native itemMode must be linked or omitted');
-    return [
-        createIfCapability(input),
-        createMergeAppendCapability(),
-        createResponseAssertionCapability(input),
-        createStopAndErrorCapability(),
-    ];
+    validateNativeFeatureContext(input);
+    return resolveN8nNativeFeatures({
+        ...input,
+        features: [
+            N8nNativeFeature.If,
+            N8nNativeFeature.MergeAppend,
+            N8nNativeFeature.AssertResponses,
+            N8nNativeFeature.StopAndError,
+        ],
+    }).capabilities;
 }

package/dist/nodes/native/create-pass-through-capability.js

@@ -7,9 +7,11 @@ export function createPassThroughCapability() {
         name: 'pass-through',
         description: 'n8n No Operation: forward all input items unchanged with their original links. Main input/output, no configuration or new data. Can provide a common entry before a fan-out. This does not merge branches, collect results or replace a missing API.',
         parametersSchema: passThroughParametersSchema,
+        parameterReferenceSources: [],
         inputPorts: () => ['main'],
         outputPorts: () => ['main'],
         responseReferences: () => [],
+        parameterReferenceBindings: () => [],
         waitsForAllInputs: false,
         exclusiveOutputPorts: false,
         compile: ({ planned, position }) => {

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

@@ -1,6 +1,8 @@
+import { defineMaterialBoundCapability } from './common/define-material-bound-capability.js';
 import { createResponseArrayItemSchema } from '@openapi-flow/core';
 import { createResponseArrayParametersSchema } from '../../schemas/response-array-schema.js';
 import { createArrayNodeFragment } from './arrays/create-array-node-fragment.js';
+import { responseArrayDefinition } from './response-array-definition.js';
 export function createResponseArrayCapability(input) {
     if (input.itemMode !== undefined && input.itemMode !== 'linked')
         throw new Error('response array capability: itemMode must be linked or omitted');
@@ -20,12 +22,17 @@ export function createResponseArrayCapability(input) {
         createResponseArrayItemSchema(material.operation, parameters.pointer);
         return material;
     }
-    return {
-        name: 'split-api-response-array',
-        description: 'Split a declared OAS response array into one unchanged JSON item per element using n8n Split Out. Output is {item: element}. Downstream bound requests must use linked item mode. An empty array creates no downstream items.',
+    return defineMaterialBoundCapability({
+        ...responseArrayDefinition,
         parametersSchema,
-        inputPorts: () => ['main'],
-        outputPorts: () => ['main'],
+        materialSources: {
+            apiMaterials: structuredClone(input.materials),
+            nativeOutputs: [],
+        },
+        bindMaterialContracts: (sources) => createResponseArrayCapability({
+            materials: sources.apiMaterials,
+            itemMode: input.itemMode,
+        }),
         responseReferences: (values) => {
             const parameters = parametersSchema.parse(values);
             source(parameters);
@@ -37,8 +44,6 @@ export function createResponseArrayCapability(input) {
                 },
             ];
         },
-        waitsForAllInputs: false,
-        exclusiveOutputPorts: false,
         outputSchema: (values) => {
             const parameters = parametersSchema.parse(values);
             return {
@@ -69,5 +74,5 @@ export function createResponseArrayCapability(input) {
                 },
             });
         },
-    };
+    });
 }