@openapi-flow/core 0.2.0 → 0.3.0

package/dist/workflow/planning/describe-native-node-configuration.js

@@ -0,0 +1,110 @@
+import { createHash } from 'node:crypto';
+import { createNativeNodePlan } from './create-native-node-plan.js';
+import { createPreparedNativeNodeMaterials } from './create-prepared-native-node-materials.js';
+import { createNativeNodeParametersSchema, nativeNodeConfigurationRepliesSchema, } from '../../schemas/native-instance-planning-schema.js';
+import { jsonValuesEqual } from '../../utils/json-values-equal.js';
+import { resolveNativeConfigurationMaterials, validateNativeNodeProducerReferences, } from './resolve-native-configuration-materials.js';
+export function describeNativeNodeConfiguration(input) {
+    const { selection, instance, configuredNodes, capabilities, outputs, sourceDependencies, } = resolveNativeConfigurationMaterials(input);
+    const allowed = sourceDependencies?.sourceNodeIds;
+    const fields = {
+        context: allowed === undefined
+            ? selection.context
+            : {
+                ...selection.context,
+                apiMaterials: selection.context.apiMaterials.filter((source) => allowed.includes(source.callId)),
+                preparedNativeNodes: selection.context.preparedNativeNodes.filter((node) => allowed.includes(node.id)),
+            },
+        instance,
+        configuredNodes: createPreparedNativeNodeMaterials(configuredNodes.filter((node) => allowed === undefined || allowed.includes(node.id)), capabilities),
+        outputs: outputs.filter((source) => allowed === undefined || allowed.includes(source.nodeId)),
+        ...(sourceDependencies === undefined ? {} : { sourceDependencies }),
+    };
+    const replies = input.replies === undefined
+        ? []
+        : nativeNodeConfigurationRepliesSchema.parse(input.replies);
+    if (input.replies !== undefined && !jsonValuesEqual(replies, input.replies))
+        throw new Error('Native configuration replies must preserve original text and question records');
+    if (replies.length && !instance.hasLiteralParameters)
+        throw new Error('Native configuration replies require a remaining literal parameter choice');
+    const accepted = [];
+    const fingerprint = () => createHash('sha256')
+        .update(JSON.stringify([
+        selection.id,
+        { ...fields, ...(accepted.length ? { replies: accepted } : {}) },
+    ]))
+        .digest('hex');
+    for (const [index, reply] of replies.entries()) {
+        if (reply.question.nodeId !== instance.id ||
+            reply.question.fingerprint !== fingerprint())
+            throw new Error(`Native configuration replies[${index}].question is stale, out of order or belongs to another instance/material revision`);
+        const proposal = createNativeNodeParametersSchema(input).parse(reply.question.proposal);
+        if (proposal.decision.status !== 'needs-clarification' ||
+            !jsonValuesEqual(proposal, reply.question.proposal) ||
+            reply.question.message !== proposal.decision.message ||
+            reply.question.id !==
+                nativeParameterQuestionIdentity(reply.question.fingerprint, instance.id, proposal))
+            throw new Error(`Native configuration replies[${index}].question differs from its original clarification proposal`);
+        accepted.push(structuredClone(reply));
+    }
+    return {
+        fingerprint: fingerprint(),
+        ...structuredClone(fields),
+        ...(accepted.length ? { replies: accepted } : {}),
+    };
+}
+/** Build one actual instance, never adopt a graph or turn an unfinished role into a source contract. */
+export function resolveNativeNodeParameters(input) {
+    const description = describeNativeNodeConfiguration(input);
+    if (input.fingerprint !== description.fingerprint)
+        throw new Error('Native parameter generation fingerprint is stale; no automatic rebase');
+    const proposal = createNativeNodeParametersSchema(input).parse(input.proposal);
+    if (!jsonValuesEqual(proposal, input.proposal))
+        throw new Error('Native parameters must validate without defaults, coercion or transformation');
+    if (proposal.decision.status === 'needs-clarification')
+        return {
+            status: 'needs-clarification',
+            id: nativeParameterQuestionIdentity(description.fingerprint, input.nodeId, proposal),
+            fingerprint: description.fingerprint,
+            nodeId: input.nodeId,
+            message: proposal.decision.message,
+            proposal,
+        };
+    const instance = description.instance;
+    const node = {
+        id: instance.id,
+        capability: instance.capability,
+        parameters: proposal.decision.parameters,
+        ...(instance.runtimeParameters === undefined
+            ? {}
+            : { runtimeParameters: instance.runtimeParameters }),
+    };
+    createNativeNodePlan({
+        ...input,
+        proposal: {
+            nativeNodes: [
+                ...(input.configuredNodes === undefined ? [] : input.configuredNodes),
+                node,
+            ],
+            gaps: [],
+        },
+    });
+    if (input.dependencies !== undefined) {
+        const materials = resolveNativeConfigurationMaterials(input);
+        if (!materials.sourceDependencies)
+            throw new Error('Native configuration is missing its validated producer choice');
+        validateNativeNodeProducerReferences(node, materials.capability, materials.sourceDependencies.sourceNodeIds);
+    }
+    return {
+        status: 'ready',
+        fingerprint: description.fingerprint,
+        node: structuredClone(node),
+        proposal: structuredClone(proposal),
+    };
+}
+function nativeParameterQuestionIdentity(fingerprint, nodeId, proposal) {
+    return ('native-question:' +
+        createHash('sha256')
+            .update(JSON.stringify({ fingerprint, nodeId, proposal }))
+            .digest('hex'));
+}

package/dist/workflow/planning/describe-native-node-planning.d.ts

@@ -0,0 +1,3 @@
+import type { NativeNodePlanningInput, NativeNodePlanningDescription } from '../../types/native-node-planning.js';
+/** Capture data and registry fields, not arbitrary JavaScript closure state or provider authenticity. */
+export declare function describeNativeNodePlanning(input: NativeNodePlanningInput): NativeNodePlanningDescription;

package/dist/workflow/planning/describe-native-node-planning.js

@@ -0,0 +1,51 @@
+import { nativeNodePlanningOptionsSchema } from '../../schemas/native-node-planning-record-schema.js';
+import { createWorkflowPlanningCapabilities } from '../create-workflow-planning-capabilities.js';
+import { createPreparedNativeNodeMaterials } from './create-prepared-native-node-materials.js';
+import { createNativePlanningCapabilityMaterial } from './create-native-planning-capability-material.js';
+import { captureWorkflowPlanningMaterials } from './capture-workflow-planning-materials.js';
+import { resolveNativePlanningMaterials } from './resolve-native-planning-materials.js';
+/** Capture data and registry fields, not arbitrary JavaScript closure state or provider authenticity. */
+export function describeNativeNodePlanning(input) {
+    const options = nativeNodePlanningOptionsSchema.parse({
+        planId: input.planId,
+        scenario: input.scenario,
+        allowRuntimeParameters: input.allowRuntimeParameters,
+    });
+    const { capabilities, apiMaterials, preparedNativeNodes: prepared, } = captureWorkflowPlanningMaterials(input);
+    const apiIds = apiMaterials.map((material) => material.callId);
+    const planningCapabilities = createWorkflowPlanningCapabilities({
+        capabilities,
+        apiCallIds: apiIds,
+    });
+    const snapshot = {
+        ...options,
+        capabilities,
+        apiMaterials,
+        preparedNativeNodes: prepared,
+    };
+    return {
+        input: snapshot,
+        planningCapabilities,
+        context: {
+            scenario: options.scenario,
+            apiMaterials: apiMaterials.map(({ callId, operation, purpose }) => ({
+                callId,
+                ...(purpose === undefined ? {} : { purpose }),
+                ...structuredClone({
+                    key: operation.key,
+                    method: operation.method,
+                    path: operation.path,
+                    operation: operation.operation,
+                    effective: operation.effective,
+                }),
+            })),
+            preparedNativeNodes: structuredClone(createPreparedNativeNodeMaterials(prepared, resolveNativePlanningMaterials({
+                nativeNodes: prepared,
+                capabilities,
+                apiMaterials,
+                nativeOutputs: [],
+            }).capabilities)),
+            capabilities: planningCapabilities.map((capability) => createNativePlanningCapabilityMaterial(capability, options.allowRuntimeParameters === true)),
+        },
+    };
+}

package/dist/workflow/planning/has-fixed-empty-native-parameters.d.ts

@@ -0,0 +1,4 @@
+import type { BindingSchema } from '../../types/api-bindings.js';
+import type { WorkflowCapability } from '../../types/workflow-plan.js';
+/** Prove the single value using the explicit closed empty object contract, then the full original validator. */
+export declare function hasFixedEmptyNativeParameters(schema: BindingSchema, capability: WorkflowCapability): boolean;

package/dist/workflow/planning/has-fixed-empty-native-parameters.js

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import { jsonValuesEqual } from '../../utils/json-values-equal.js';
+/** Prove the single value using the explicit closed empty object contract, then the full original validator. */
+export function hasFixedEmptyNativeParameters(schema, capability) {
+    if (!(capability.parametersSchema instanceof z.ZodObject) ||
+        Object.keys(capability.parametersSchema.shape).length)
+        return false;
+    if (typeof schema === 'boolean' ||
+        schema.type !== 'object' ||
+        schema.additionalProperties !== false ||
+        !schema.properties ||
+        typeof schema.properties !== 'object' ||
+        Array.isArray(schema.properties) ||
+        Object.keys(schema.properties).length)
+        return false;
+    if (schema.patternProperties !== undefined &&
+        (schema.patternProperties === null ||
+            typeof schema.patternProperties !== 'object' ||
+            Array.isArray(schema.patternProperties) ||
+            Object.keys(schema.patternProperties).length))
+        return false;
+    const checked = capability.parametersSchema.safeParse({});
+    return checked.success && jsonValuesEqual(checked.data, {});
+}

package/dist/workflow/planning/resolve-native-configuration-materials.d.ts

@@ -0,0 +1,8 @@
+import type { NativeNodeConfigurationInput, NativeNodeConfigurationReadiness, ResolvedNativeConfigurationMaterials } from '../../types/native-node-planning.js';
+import type { PlannedNativeNode, WorkflowCapability } from '../../types/workflow-plan.js';
+/** Actual implementation references must equal the prior choice; unused or substituted producers are not repairs. */
+export declare function validateNativeNodeProducerReferences(node: PlannedNativeNode, capability: WorkflowCapability, expected: string[]): void;
+/** Constructor prerequisites only, not proof that a requested pointer or dependency is available. */
+export declare function inspectNativeNodeConfigurationReadiness(input: NativeNodeConfigurationInput): NativeNodeConfigurationReadiness;
+/** Keep selection immutable; bind the value contract from actual completed sources separately. */
+export declare function resolveNativeConfigurationMaterials(input: NativeNodeConfigurationInput): ResolvedNativeConfigurationMaterials;

package/dist/workflow/planning/resolve-native-configuration-materials.js

@@ -0,0 +1,166 @@
+import { validateNativeInstanceSelection } from './resolve-native-instance-selection.js';
+import { describeNativeNodePlanning } from './describe-native-node-planning.js';
+import { resolveNativePlanningMaterials } from './resolve-native-planning-materials.js';
+import { createWorkflowPlanningCapabilities } from '../create-workflow-planning-capabilities.js';
+import { bindNativeMaterialContracts } from '../bind-native-material-contracts.js';
+import { nativeMaterialRequirementsSchema } from '../../schemas/native-material-requirements-schema.js';
+import { createNativeParameterGenerationContract } from '../../schemas/create-native-parameter-generation-contract.js';
+import { jsonValuesEqual } from '../../utils/json-values-equal.js';
+import { validateNativeInstanceDependencies } from './resolve-native-instance-dependencies.js';
+import { createWorkflowNodeContracts } from '../create-workflow-node-contracts.js';
+/** Actual implementation references must equal the prior choice; unused or substituted producers are not repairs. */
+export function validateNativeNodeProducerReferences(node, capability, expected) {
+    const [contract] = createWorkflowNodeContracts({
+        materials: [],
+        nativeNodes: [node],
+        capabilities: [capability],
+    });
+    const actual = [
+        ...new Set([
+            ...contract.references.map((reference) => reference.nodeId),
+            ...Object.values(contract.inputReferences === undefined ? {} : contract.inputReferences)
+                .flat()
+                .map((reference) => reference.nodeId),
+            ...(contract.rejoinsExclusiveOutputs === undefined
+                ? []
+                : [contract.rejoinsExclusiveOutputs]),
+        ]),
+    ].sort();
+    if (!jsonValuesEqual(actual, [...expected].sort()))
+        throw new Error(`Native instance ${node.id}: actual parameter references must exactly match its declared producer dependencies`);
+}
+/** Validate the original role receipt before resolving completed producer contracts. */
+function prepareNativeConfigurationMaterials(input) {
+    const selection = validateNativeInstanceSelection(input);
+    const instance = selection.instances.find((entry) => entry.id === input.nodeId);
+    if (!instance)
+        throw new Error(`Native instance ${input.nodeId} is not selected`);
+    const dependencies = input.dependencies === undefined
+        ? undefined
+        : validateNativeInstanceDependencies({
+            ...input,
+            dependencies: input.dependencies,
+        });
+    const configured = input.configuredNodes === undefined ? [] : input.configuredNodes;
+    if (!Array.isArray(configured))
+        throw new Error('native configuration configuredNodes must be an array');
+    const { input: snapshot } = describeNativeNodePlanning(input);
+    for (const node of configured) {
+        const selected = selection.instances.find((entry) => entry.id === node.id);
+        if (!selected ||
+            selected.id === input.nodeId ||
+            selected.capability !== node.capability ||
+            !jsonValuesEqual(selected.runtimeParameters, node.runtimeParameters))
+            throw new Error(`Configured native instance ${node.id} does not match a distinct selected role and owner`);
+    }
+    const materials = resolveNativePlanningMaterials({
+        apiMaterials: snapshot.apiMaterials,
+        nativeOutputs: [],
+        nativeNodes: [...snapshot.preparedNativeNodes, ...configured],
+        capabilities: snapshot.capabilities,
+    });
+    const planning = createWorkflowPlanningCapabilities({
+        capabilities: materials.capabilities,
+        apiCallIds: snapshot.apiMaterials.map((material) => material.callId),
+    });
+    for (const node of configured) {
+        const capability = planning.find((entry) => entry.name === node.capability);
+        if (!capability)
+            throw new Error(`Configured native instance ${node.id} has no supplied capability`);
+        const contract = createNativeParameterGenerationContract({
+            nodeId: node.id,
+            capability,
+            runtimeParameters: node.runtimeParameters,
+        });
+        const values = contract.valuesSchema.parse(node.parameters);
+        if (!jsonValuesEqual(values, node.parameters))
+            throw new Error(`Configured native instance ${node.id} cannot coerce or default literal parameters`);
+        if (dependencies !== undefined)
+            validateNativeNodeProducerReferences(node, capability, dependencies.proposal.sourcesByNodeId[node.id].sourceNodeIds);
+    }
+    const definition = snapshot.capabilities.find((entry) => entry.name === instance.capability);
+    if (!definition)
+        throw new Error(`Native instance ${input.nodeId} has no registered capability`);
+    return {
+        selection,
+        instance,
+        snapshot,
+        definition,
+        capabilities: materials.capabilities,
+        configuredNodes: structuredClone(configured),
+        outputs: materials.outputs,
+        ...(dependencies === undefined
+            ? {}
+            : {
+                sourceDependencies: {
+                    planId: dependencies.id,
+                    sourceNodeIds: [
+                        ...dependencies.proposal.sourcesByNodeId[instance.id]
+                            .sourceNodeIds,
+                    ],
+                },
+            }),
+    };
+}
+/** An explicit empty choice means no sources; it never falls back to all available producers. */
+function nativeConfigurationSources(materials) {
+    const allowed = materials.sourceDependencies?.sourceNodeIds;
+    return {
+        apiMaterials: materials.snapshot.apiMaterials.filter((source) => allowed === undefined || allowed.includes(source.callId)),
+        nativeOutputs: materials.outputs.filter((source) => allowed === undefined || allowed.includes(source.nodeId)),
+    };
+}
+function nativeConfigurationReadiness(materials) {
+    const { definition, snapshot, instance } = materials;
+    const requirements = definition.materialRequirements === undefined
+        ? []
+        : nativeMaterialRequirementsSchema.parse(definition.materialRequirements);
+    const sources = nativeConfigurationSources(materials);
+    const pending = materials.sourceDependencies?.sourceNodeIds.filter((id) => !snapshot.apiMaterials.some((source) => source.callId === id) &&
+        !snapshot.preparedNativeNodes.some((node) => node.id === id) &&
+        !materials.configuredNodes.some((node) => node.id === id));
+    const missingContext = requirements.flatMap((requirement) => sources[requirement.field].length < requirement.minimumItems
+        ? [{ ...requirement, availableItems: sources[requirement.field].length }]
+        : []);
+    return missingContext.length || (pending !== undefined && pending.length > 0)
+        ? {
+            status: 'awaiting-materials',
+            nodeId: instance.id,
+            capability: instance.capability,
+            missingContext,
+            ...(pending === undefined ? {} : { pendingSourceNodeIds: pending }),
+        }
+        : { status: 'ready', nodeId: instance.id };
+}
+/** Constructor prerequisites only, not proof that a requested pointer or dependency is available. */
+export function inspectNativeNodeConfigurationReadiness(input) {
+    return nativeConfigurationReadiness(prepareNativeConfigurationMaterials(input));
+}
+/** Keep selection immutable; bind the value contract from actual completed sources separately. */
+export function resolveNativeConfigurationMaterials(input) {
+    const materials = prepareNativeConfigurationMaterials(input);
+    const readiness = nativeConfigurationReadiness(materials);
+    if (readiness.status !== 'ready')
+        throw new Error(`Native configuration ${input.nodeId} [${readiness.capability}] requires ${readiness.missingContext.map((entry) => `${entry.field} (at least ${entry.minimumItems}, available ${entry.availableItems})`).join(', ')}${readiness.pendingSourceNodeIds?.length ? '; pending selected producers: ' + readiness.pendingSourceNodeIds.join(', ') : ''}`);
+    const sources = nativeConfigurationSources(materials);
+    const bound = bindNativeMaterialContracts(materials.definition, sources);
+    const [capability] = createWorkflowPlanningCapabilities({
+        capabilities: [bound],
+        apiCallIds: sources.apiMaterials.map((material) => material.callId),
+    });
+    const contract = createNativeParameterGenerationContract({
+        nodeId: materials.instance.id,
+        capability,
+        runtimeParameters: materials.instance.runtimeParameters,
+    });
+    return {
+        ...materials,
+        capability,
+        contract,
+        instance: {
+            ...materials.instance,
+            literalParametersSchema: contract.literalParametersSchema,
+            hasLiteralParameters: contract.hasLiteralParameters,
+        },
+    };
+}

package/dist/workflow/planning/resolve-native-instance-dependencies.d.ts

@@ -0,0 +1,7 @@
+import type { NativeSelectedPlanningInput } from '../../types/native-node-planning.js';
+import type { NativeInstanceDependencyContext, NativeInstanceDependencyPlan, ResolveNativeInstanceDependenciesInput, ValidateNativeInstanceDependenciesInput } from '../../types/native-instance-dependencies.js';
+/** Future role IDs are candidates, not evidence of ready output contracts. */
+export declare function describeNativeInstanceDependencies(input: NativeSelectedPlanningInput): NativeInstanceDependencyContext;
+/** Validate producer choice and its planning DAG, without generating parameters, outputs or execution edges. */
+export declare function resolveNativeInstanceDependencies(input: ResolveNativeInstanceDependenciesInput): NativeInstanceDependencyPlan;
+export declare function validateNativeInstanceDependencies(input: ValidateNativeInstanceDependenciesInput): NativeInstanceDependencyPlan;

package/dist/workflow/planning/resolve-native-instance-dependencies.js

@@ -0,0 +1,77 @@
+import { createHash } from 'node:crypto';
+import { validateNativeInstanceSelection } from './resolve-native-instance-selection.js';
+import { describeNativeNodePlanning } from './describe-native-node-planning.js';
+import { resolveNativePlanningMaterials } from './resolve-native-planning-materials.js';
+import { createNativeInstanceDependenciesSchema } from '../../schemas/native-instance-dependencies-schema.js';
+import { jsonValuesEqual } from '../../utils/json-values-equal.js';
+import { validateNativeProducerDependencyGraph } from './validate-native-producer-dependency-graph.js';
+import { describePendingNativeProducer, selectNativeParameterProducers, } from './select-native-parameter-producers.js';
+/** Future role IDs are candidates, not evidence of ready output contracts. */
+export function describeNativeInstanceDependencies(input) {
+    const selection = validateNativeInstanceSelection(input);
+    const { input: snapshot } = describeNativeNodePlanning(input);
+    const prepared = resolveNativePlanningMaterials({
+        nativeNodes: snapshot.preparedNativeNodes,
+        capabilities: snapshot.capabilities,
+        apiMaterials: snapshot.apiMaterials,
+        nativeOutputs: [],
+    });
+    const producers = [
+        ...snapshot.apiMaterials.map((source) => ({
+            nodeId: source.callId,
+            referenceSources: ['response'],
+        })),
+        ...snapshot.preparedNativeNodes.map((node) => {
+            const capability = snapshot.capabilities.find((entry) => entry.name === node.capability);
+            const producer = describePendingNativeProducer(node.id, capability);
+            return {
+                ...producer,
+                referenceSources: producer.referenceSources.filter((source) => source !== 'node-output' ||
+                    prepared.outputs.some((output) => output.nodeId === node.id)),
+            };
+        }),
+        ...selection.instances.map((node) => describePendingNativeProducer(node.id, snapshot.capabilities.find((entry) => entry.name === node.capability))),
+    ];
+    return structuredClone({
+        selectionId: selection.id,
+        scenario: selection.context.scenario,
+        instances: selection.instances,
+        capabilities: selection.context.capabilities,
+        apiMaterials: selection.context.apiMaterials,
+        preparedNativeNodes: selection.context.preparedNativeNodes,
+        preparedOutputs: prepared.outputs,
+        sourceCandidatesByNodeId: Object.fromEntries(selection.instances.map((node) => [
+            node.id,
+            selectNativeParameterProducers({
+                nodeId: node.id,
+                capability: snapshot.capabilities.find((entry) => entry.name === node.capability),
+                producers,
+            }),
+        ])),
+    });
+}
+/** Validate producer choice and its planning DAG, without generating parameters, outputs or execution edges. */
+export function resolveNativeInstanceDependencies(input) {
+    const context = describeNativeInstanceDependencies(input);
+    const proposal = createNativeInstanceDependenciesSchema(input).parse(input.proposal);
+    if (!jsonValuesEqual(proposal, input.proposal))
+        throw new Error('Native dependency choices cannot be coerced, defaulted or transformed');
+    validateNativeProducerDependencyGraph(context.instances.map((node) => node.id), proposal);
+    const fields = { selectionId: context.selectionId, context, proposal };
+    return {
+        id: 'native-dependencies:' +
+            createHash('sha256').update(JSON.stringify(fields)).digest('hex'),
+        ...structuredClone(fields),
+    };
+}
+export function validateNativeInstanceDependencies(input) {
+    if (!input.dependencies?.proposal)
+        throw new Error('Native dependencies require their original proposal');
+    const expected = resolveNativeInstanceDependencies({
+        ...input,
+        proposal: input.dependencies.proposal,
+    });
+    if (!jsonValuesEqual(expected, input.dependencies))
+        throw new Error('Native dependency plan is stale or its original choices/material context changed');
+    return expected;
+}

package/dist/workflow/planning/resolve-native-instance-selection.d.ts

@@ -0,0 +1,6 @@
+import type { NativeInstanceSelection, ResolveNativeInstanceSelectionInput, NativeInstanceSelectionInput, NativeInstanceSelectionDescription, NativeSelectedPlanningInput } from '../../types/native-node-planning.js';
+/** The same capability material owns both model context and field-ownership alternatives. */
+export declare function describeNativeInstanceSelection(input: NativeInstanceSelectionInput): NativeInstanceSelectionDescription;
+/** Select roles and ownership only; node identities and generation schemas are derived here. */
+export declare function resolveNativeInstanceSelection(input: ResolveNativeInstanceSelectionInput): NativeInstanceSelection;
+export declare function validateNativeInstanceSelection(input: NativeSelectedPlanningInput): NativeInstanceSelection;

package/dist/workflow/planning/resolve-native-instance-selection.js

@@ -0,0 +1,100 @@
+import { createHash } from 'node:crypto';
+import { createNativeInstanceSelectionSchema } from '../../schemas/native-instance-planning-schema.js';
+import { createNativeParameterGenerationContract } from '../../schemas/create-native-parameter-generation-contract.js';
+import { describeNativeNodePlanning } from './describe-native-node-planning.js';
+import { jsonValuesEqual } from '../../utils/json-values-equal.js';
+import { createNativePlanningCapabilityMaterial } from './create-native-planning-capability-material.js';
+/** The same capability material owns both model context and field-ownership alternatives. */
+export function describeNativeInstanceSelection(input) {
+    const description = describeNativeNodePlanning(input);
+    return {
+        ...description,
+        context: {
+            ...description.context,
+            parameterPlanning: {
+                stage: 'separate-value-generation',
+                missingPlanTimeValues: 'ask-in-value-stage',
+            },
+            capabilities: description.planningCapabilities.map((capability) => createNativePlanningCapabilityMaterial(capability, input.allowRuntimeParameters === true, true)),
+        },
+    };
+}
+/** Select roles and ownership only; node identities and generation schemas are derived here. */
+export function resolveNativeInstanceSelection(input) {
+    const { input: snapshot, context, planningCapabilities, } = describeNativeInstanceSelection(input);
+    const proposal = createNativeInstanceSelectionSchema(input).parse(input.proposal);
+    if (!jsonValuesEqual(proposal, input.proposal))
+        throw new Error('Native instance selection must preserve original model values');
+    const used = new Set([
+        ...snapshot.apiMaterials.map((entry) => entry.callId),
+        ...snapshot.preparedNativeNodes.map((entry) => entry.id),
+    ]);
+    const instances = proposal.instances.map((choice) => {
+        if (!choice.purpose.trim())
+            throw new Error('Native instance purpose must be non-empty');
+        const capability = planningCapabilities.find((entry) => entry.name === choice.capability);
+        if (!capability)
+            throw new Error(`Native instance capability ${choice.capability} is not supplied`);
+        const id = 'native-instance:' +
+            createHash('sha256')
+                .update(JSON.stringify([snapshot.planId, choice.capability, choice.purpose]))
+                .digest('hex');
+        if (used.has(id))
+            throw new Error(`Native instance role is repeated or its ID collides: ${choice.purpose}`);
+        used.add(id);
+        const runtimeParameters = choice.parameterSource === 'workflow-input'
+            ? true
+            : choice.parameterSource === 'workflow-fields'
+                ? { pointers: choice.pointers }
+                : undefined;
+        const contract = createNativeParameterGenerationContract({
+            nodeId: id,
+            capability,
+            runtimeParameters,
+        });
+        return {
+            id,
+            capability: choice.capability,
+            purpose: choice.purpose,
+            ...(choice.reason === undefined ? {} : { reason: choice.reason }),
+            literalParametersSchema: contract.literalParametersSchema,
+            hasLiteralParameters: contract.hasLiteralParameters,
+            ...(runtimeParameters === undefined ? {} : { runtimeParameters }),
+        };
+    });
+    const gaps = proposal.gaps.map((gap, index) => ({
+        id: `${snapshot.planId}-gap-${index + 1}`,
+        stage: 'workflow-graph',
+        description: gap.description,
+    }));
+    for (const gap of gaps)
+        if (used.has(gap.id))
+            throw new Error(`Native instance gap ID collides: ${gap.id}`);
+    const fields = {
+        proposal,
+        context,
+        includeExplanations: input.includeExplanations === true,
+        instances,
+        gaps,
+    };
+    return {
+        id: 'native-selection:' +
+            createHash('sha256')
+                .update(JSON.stringify([snapshot.planId, fields]))
+                .digest('hex'),
+        ...structuredClone(fields),
+    };
+}
+export function validateNativeInstanceSelection(input) {
+    if (!input.selection ||
+        typeof input.selection !== 'object' ||
+        !input.selection.proposal)
+        throw new Error('native configuration.selection requires its original proposal');
+    const selection = resolveNativeInstanceSelection({
+        ...input,
+        proposal: input.selection.proposal,
+    });
+    if (!jsonValuesEqual(selection, input.selection))
+        throw new Error('Native instance selection is stale or its derived contract was modified');
+    return selection;
+}

package/dist/workflow/planning/resolve-native-planning-materials.d.ts

@@ -0,0 +1,3 @@
+import type { ResolveNativePlanningMaterialsInput, ResolvedNativePlanningMaterials } from '../../types/native-node-planning.js';
+/** Resolve completed materials only; retain unused implementation definitions for later choices. */
+export declare function resolveNativePlanningMaterials(input: ResolveNativePlanningMaterialsInput): ResolvedNativePlanningMaterials;

package/dist/workflow/planning/resolve-native-planning-materials.js

@@ -0,0 +1,31 @@
+import { resolveNativeMaterialSnapshot } from '../resolve-native-material-snapshot.js';
+import { NativeMaterialResolutionError } from '../native-material-resolution-error.js';
+import { validateNativeApiResponseReferences } from '../validate-native-api-response-references.js';
+/** Resolve completed materials only; retain unused implementation definitions for later choices. */
+export function resolveNativePlanningMaterials(input) {
+    // Static references retain the existing named API diagnostic before dependency resolution.
+    // A source-bound definition is inspected by the material resolver, not executed unbound.
+    validateNativeApiResponseReferences({
+        nativeNodes: input.nativeNodes.filter((node) => input.capabilities.some((capability) => capability.name === node.capability &&
+            !capability.bindMaterialContracts)),
+        capabilities: input.capabilities,
+        apiCallIds: input.apiMaterials.map((material) => material.callId),
+    });
+    const result = resolveNativeMaterialSnapshot({
+        ...input,
+        deferredNodeIds: [],
+    });
+    if (result.status !== 'ready')
+        throw new NativeMaterialResolutionError(result.pending);
+    return {
+        outputs: result.outputs,
+        capabilities: input.capabilities.map((definition) => {
+            if (!input.nativeNodes.some((node) => node.capability === definition.name))
+                return definition;
+            const bound = result.capabilities.find((candidate) => candidate.name === definition.name);
+            if (!bound)
+                throw new Error('Native planning material binding is missing ' + definition.name);
+            return bound;
+        }),
+    };
+}

package/dist/workflow/planning/select-native-parameter-producers.d.ts

@@ -0,0 +1,8 @@
+import type { WorkflowCapability } from '../../types/workflow-plan.js';
+import type { WorkflowNativeParameterReference } from '../../types/native-parameter-reference.js';
+import type { NativeParameterProducerCandidate, SelectNativeParameterProducersInput } from '../../types/native-producer-eligibility.js';
+/** An explicit implementation protocol; absence never means all sources. */
+export declare function requireNativeParameterReferenceSources(capability: WorkflowCapability): WorkflowNativeParameterReference['source'][];
+/** Only potential output kinds are exposed here, not fabricated future schemas. */
+export declare function describePendingNativeProducer(nodeId: string, capability: WorkflowCapability): NativeParameterProducerCandidate;
+export declare function selectNativeParameterProducers(input: SelectNativeParameterProducersInput): string[];

package/dist/workflow/planning/select-native-parameter-producers.js

@@ -0,0 +1,26 @@
+import { nativeParameterReferenceSourcesSchema } from '../../schemas/native-parameter-reference-sources-schema.js';
+/** An explicit implementation protocol; absence never means all sources. */
+export function requireNativeParameterReferenceSources(capability) {
+    const checked = nativeParameterReferenceSourcesSchema.safeParse(capability.parameterReferenceSources);
+    if (!checked.success)
+        throw new Error(`Native capability ${capability.name}.parameterReferenceSources must explicitly declare distinct supported reference kinds for producer-choice planning`, { cause: checked.error });
+    return checked.data;
+}
+/** Only potential output kinds are exposed here, not fabricated future schemas. */
+export function describePendingNativeProducer(nodeId, capability) {
+    const referenceSources = [];
+    if (typeof capability.outputSchema === 'function')
+        referenceSources.push('node-output');
+    if (capability.exclusiveOutputPorts)
+        referenceSources.push('exclusive-output');
+    return { nodeId, referenceSources };
+}
+export function selectNativeParameterProducers(input) {
+    const allowed = requireNativeParameterReferenceSources(input.capability);
+    return [
+        ...new Set(input.producers
+            .filter((producer) => producer.nodeId !== input.nodeId &&
+            producer.referenceSources.some((source) => allowed.includes(source)))
+            .map((producer) => producer.nodeId)),
+    ];
+}

package/dist/workflow/planning/validate-native-node-planning-record.d.ts

@@ -0,0 +1,2 @@
+import type { ValidateNativeNodePlanningRecordInput } from '../../types/native-node-planning.js';
+export declare function validateNativeNodePlanningRecord(input: ValidateNativeNodePlanningRecordInput): void;