@openapi-flow/core 0.2.0 → 0.3.0

package/dist/workflow/graphs/describe-workflow-graph-planning.js

@@ -0,0 +1,101 @@
+import { workflowGraphPlanningIdentitySchema } from '../../schemas/workflow-graph-planning-schema.js';
+import { workflowReviewGapSchema } from '../../schemas/workflow-planning-material-schema.js';
+import { captureWorkflowPlanningData } from '../planning/capture-workflow-planning-data.js';
+import { createPreparedNativeNodeMaterials } from '../planning/create-prepared-native-node-materials.js';
+import { createNativePlanningCapabilityMaterial } from '../planning/create-native-planning-capability-material.js';
+import { createNativeOutputContracts } from '../create-native-output-contracts.js';
+import { createWorkflowPlanningCapabilities } from '../create-workflow-planning-capabilities.js';
+import { inspectApiArgumentRequirements } from '../../arguments/clarification/inspect-api-argument-requirements.js';
+export function describeWorkflowGraphPlanning(input) {
+    const identity = workflowGraphPlanningIdentitySchema.parse({
+        mode: input.mode,
+        scenario: input.scenario,
+    });
+    if (!Array.isArray(input.capabilities))
+        throw new Error('graph planning capabilities must be an array');
+    if (!Array.isArray(input.gaps))
+        throw new Error('graph planning gaps must be an array');
+    const captured = captureWorkflowPlanningData(input);
+    const gaps = structuredClone(input.gaps.map((gap) => workflowReviewGapSchema.parse(gap)));
+    if (identity.mode === 'executable' &&
+        (gaps.length ||
+            captured.materials.some((material) => material.status !== 'ready')))
+        throw new Error('executable graph planning accepts only ready API materials and no supplied review gaps');
+    for (const material of captured.materials) {
+        if (material.status !== 'ready')
+            continue;
+        const args = material.arguments;
+        if (args.unresolvedInputs.length ||
+            inspectApiArgumentRequirements({ operation: material.operation, ...args })
+                .status !== 'ready')
+            throw new Error(`graph planning materials[${args.callId}] has unresolved OAS request inputs or scenario-requested inputs`);
+    }
+    const apiIds = captured.materials.map((material) => material.status === 'ready' ? material.arguments.callId : material.callId);
+    const planningCapabilities = createWorkflowPlanningCapabilities({
+        capabilities: captured.capabilities,
+        apiCallIds: apiIds,
+    });
+    const nativeOutputs = createNativeOutputContracts({
+        nativeNodes: captured.preparedNativeNodes,
+        capabilities: captured.capabilities,
+    });
+    return {
+        input: { ...identity, ...captured, gaps },
+        planningCapabilities,
+        context: {
+            scenario: identity.scenario,
+            preparedNativeNodes: structuredClone(createPreparedNativeNodeMaterials(captured.preparedNativeNodes, captured.capabilities)),
+            nativeOutputs: structuredClone(nativeOutputs),
+            // Request values are already generated. Avoid duplicating the resolved
+            // response schemas through both operation and pathItem in this stage.
+            materials: captured.materials.map(({ operation, ...material }) => ({
+                ...structuredClone(material),
+                operation: structuredClone({
+                    key: operation.key,
+                    method: operation.method,
+                    path: operation.path,
+                    operation: {
+                        ...(operation.operation.summary === undefined
+                            ? {}
+                            : { summary: operation.operation.summary }),
+                        ...(operation.operation.description === undefined
+                            ? {}
+                            : { description: operation.operation.description }),
+                        ...(operation.operation.tags === undefined
+                            ? {}
+                            : { tags: operation.operation.tags }),
+                        ...(operation.operation.responses === undefined
+                            ? {}
+                            : { responses: operation.operation.responses }),
+                    },
+                }),
+                inputPorts: ['main'],
+                outputPorts: ['main'],
+            })),
+            ...(identity.mode === 'reviewable'
+                ? {
+                    gaps: gaps.map((gap) => ({
+                        ...structuredClone(gap),
+                        inputPorts: ['main'],
+                        outputPorts: ['main'],
+                    })),
+                }
+                : {}),
+            capabilities: planningCapabilities.map((capability) => {
+                const material = createNativePlanningCapabilityMaterial(capability, false);
+                return {
+                    name: material.name,
+                    description: material.description,
+                    parametersSchema: material.parametersSchema,
+                    waitsForAllInputs: capability.waitsForAllInputs,
+                    exclusiveOutputPorts: capability.exclusiveOutputPorts,
+                };
+            }),
+        },
+        sources: structuredClone({
+            materials: captured.materials,
+            nativeOutputs,
+            capabilities: captured.capabilities.map((capability) => createNativePlanningCapabilityMaterial(capability, false)),
+        }),
+    };
+}

package/dist/workflow/graphs/validate-workflow-graph-planning-record.d.ts

@@ -0,0 +1,2 @@
+import type { ValidateWorkflowGraphPlanningRecordInput } from '../../types/workflow-graph-planning.js';
+export declare function validateWorkflowGraphPlanningRecord(input: ValidateWorkflowGraphPlanningRecordInput): void;

package/dist/workflow/graphs/validate-workflow-graph-planning-record.js

@@ -0,0 +1,13 @@
+import { isDeepStrictEqual } from 'node:util';
+import { workflowGraphPlanningRecordSchema } from '../../schemas/workflow-graph-planning-schema.js';
+import { createWorkflowGraphPlanningRecord } from './create-workflow-graph-planning-record.js';
+export function validateWorkflowGraphPlanningRecord(input) {
+    const record = workflowGraphPlanningRecordSchema.parse(input.record);
+    const expected = createWorkflowGraphPlanningRecord({
+        ...input,
+        proposal: record.proposal,
+        assessment: record.assessment,
+    });
+    if (!isDeepStrictEqual(record, expected))
+        throw new Error('graph planning record differs from its original scenario, supplied materials, proposal, plan or verification');
+}

package/dist/workflow/inspect-native-reference-structure.d.ts

@@ -0,0 +1,3 @@
+import type { DescribeNativeReferenceBindingsInput, WorkflowNativeReferenceBinding } from '../types/native-parameter-reference.js';
+/** Inspect literal reference locations while their source snapshot may be unresolved. Not a material contract. */
+export declare function inspectNativeReferenceStructure(input: DescribeNativeReferenceBindingsInput): WorkflowNativeReferenceBinding[];

package/dist/workflow/inspect-native-reference-structure.js

@@ -0,0 +1,19 @@
+import { jsonValuesEqual } from '../utils/json-values-equal.js';
+import { validateNativeReferenceBindingLocations } from './validate-native-reference-binding-locations.js';
+/** Inspect literal reference locations while their source snapshot may be unresolved. Not a material contract. */
+export function inspectNativeReferenceStructure(input) {
+    const { node, capability } = input;
+    if (node.capability !== capability.name)
+        throw new Error(`node ${node.id}: reference structure capability ${capability.name} does not match ${node.capability}`);
+    if (!capability.referenceStructureSchema ||
+        typeof capability.parameterReferenceBindings !== 'function')
+        throw new Error(`Native capability ${capability.name} requires referenceStructureSchema and parameterReferenceBindings for unresolved reference inspection`);
+    if (node.runtimeParameters !== undefined)
+        throw new Error(`node ${node.id}: unresolved reference inspection requires literal structural parameters, not runtime ownership`);
+    const parameters = capability.referenceStructureSchema.parse(node.parameters);
+    if (!jsonValuesEqual(parameters, node.parameters))
+        throw new Error(`node ${node.id}: reference structure schema must validate without defaults, coercion or transformation`);
+    const bindings = capability.parameterReferenceBindings(parameters);
+    validateNativeReferenceBindingLocations(node.id, parameters, bindings);
+    return structuredClone(bindings);
+}

package/dist/workflow/native-material-resolution-error.d.ts

@@ -0,0 +1,5 @@
+import type { PendingNativeMaterialNode } from '../types/native-material-snapshot.js';
+export declare class NativeMaterialResolutionError extends Error {
+    readonly pending: PendingNativeMaterialNode[];
+    constructor(pending: PendingNativeMaterialNode[]);
+}

package/dist/workflow/native-material-resolution-error.js

@@ -0,0 +1,8 @@
+export class NativeMaterialResolutionError extends Error {
+    pending;
+    constructor(pending) {
+        super(`Native material contracts are not resolved: ${pending.map((node) => `${node.nodeId} [${node.capability}] (${node.kind}: ${node.sourceNodeIds.join(', ')})`).join('; ')}`);
+        this.name = 'NativeMaterialResolutionError';
+        this.pending = structuredClone(pending);
+    }
+}

package/dist/workflow/parse-native-node-parameters.js

@@ -1,5 +1,7 @@
 import { jsonValuesEqual } from '../utils/json-values-equal.js';
 export function parseNativeNodeParameters(planned, capability) {
+    if (planned.runtimeParameters !== undefined)
+        throw new Error(`node ${planned.id}: runtime parameters require explicit input materialization or a workflow template compiler`);
     const parameters = capability.parametersSchema.parse(planned.parameters);
     if (!jsonValuesEqual(parameters, planned.parameters))
         throw new Error(`node ${planned.id}: parameter schema must validate without defaults, coercion or transformation`);

package/dist/workflow/planning/assemble-native-node-materials.d.ts

@@ -0,0 +1,3 @@
+import type { PlannedNativeNode } from '../../types/workflow-plan.js';
+/** Prepared values belong to the host; model output contains only additions. */
+export declare function assembleNativeNodeMaterials(prepared: PlannedNativeNode[], additional: PlannedNativeNode[]): PlannedNativeNode[];

package/dist/workflow/planning/assemble-native-node-materials.js

@@ -0,0 +1,8 @@
+/** Prepared values belong to the host; model output contains only additions. */
+export function assembleNativeNodeMaterials(prepared, additional) {
+    const preparedIds = new Set(prepared.map((node) => node.id));
+    for (const node of additional)
+        if (preparedIds.has(node.id))
+            throw new Error(`additionalNativeNodes[${node.id}] duplicates preparedNativeNodes; return only new nodes, not existing materials`);
+    return [...prepared, ...additional];
+}

package/dist/workflow/planning/capture-native-planning-capability.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowCapability } from '../../types/workflow-plan.js';
+/** Capture the declared protocol, including prototype methods, without cloning opaque schema/closure state. */
+export declare function captureNativePlanningCapability(capability: WorkflowCapability): WorkflowCapability;

package/dist/workflow/planning/capture-native-planning-capability.js

@@ -0,0 +1,79 @@
+import { createNativePlanningCapabilityMaterial } from './create-native-planning-capability-material.js';
+/** Capture the declared protocol, including prototype methods, without cloning opaque schema/closure state. */
+export function captureNativePlanningCapability(capability) {
+    if (!capability || typeof capability !== 'object')
+        throw new Error('native planning capabilities must contain implementation objects');
+    createNativePlanningCapabilityMaterial(capability, false);
+    for (const field of [
+        'createPlanningParametersSchema',
+        'nodeOutputReferences',
+        'parameterReferenceBindings',
+        'bindMaterialContracts',
+        'inputReferences',
+        'rejoinsExclusiveOutputs',
+        'outputSchema',
+    ])
+        if (capability[field] !== undefined &&
+            typeof capability[field] !== 'function')
+            throw new Error(`native planning capability ${capability.name}.${field} must be a function`);
+    return {
+        name: capability.name,
+        description: capability.description,
+        parametersSchema: capability.parametersSchema,
+        ...(capability.parameterReferenceSources === undefined
+            ? {}
+            : {
+                parameterReferenceSources: structuredClone(capability.parameterReferenceSources),
+            }),
+        inputPorts: capability.inputPorts.bind(capability),
+        outputPorts: capability.outputPorts.bind(capability),
+        responseReferences: capability.responseReferences.bind(capability),
+        waitsForAllInputs: capability.waitsForAllInputs,
+        exclusiveOutputPorts: capability.exclusiveOutputPorts,
+        ...(capability.supportsRuntimeParameters === undefined
+            ? {}
+            : { supportsRuntimeParameters: capability.supportsRuntimeParameters }),
+        ...(capability.createPlanningParametersSchema === undefined
+            ? {}
+            : {
+                createPlanningParametersSchema: capability.createPlanningParametersSchema.bind(capability),
+            }),
+        ...(capability.nodeOutputReferences === undefined
+            ? {}
+            : {
+                nodeOutputReferences: capability.nodeOutputReferences.bind(capability),
+            }),
+        ...(capability.parameterReferenceBindings === undefined
+            ? {}
+            : {
+                parameterReferenceBindings: capability.parameterReferenceBindings.bind(capability),
+            }),
+        ...(capability.referenceStructureSchema === undefined
+            ? {}
+            : { referenceStructureSchema: capability.referenceStructureSchema }),
+        ...(capability.materialSources === undefined
+            ? {}
+            : { materialSources: structuredClone(capability.materialSources) }),
+        ...(capability.materialRequirements === undefined
+            ? {}
+            : {
+                materialRequirements: structuredClone(capability.materialRequirements),
+            }),
+        ...(capability.bindMaterialContracts === undefined
+            ? {}
+            : {
+                bindMaterialContracts: capability.bindMaterialContracts.bind(capability),
+            }),
+        ...(capability.inputReferences === undefined
+            ? {}
+            : { inputReferences: capability.inputReferences.bind(capability) }),
+        ...(capability.rejoinsExclusiveOutputs === undefined
+            ? {}
+            : {
+                rejoinsExclusiveOutputs: capability.rejoinsExclusiveOutputs.bind(capability),
+            }),
+        ...(capability.outputSchema === undefined
+            ? {}
+            : { outputSchema: capability.outputSchema.bind(capability) }),
+    };
+}

package/dist/workflow/planning/capture-workflow-planning-data.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowPlanningDataInput, WorkflowPlanningDataSnapshot } from '../../types/workflow-planning-materials.js';
+/** Capture only declared source data, without requiring not-yet-generated native producers. */
+export declare function captureWorkflowPlanningData(input: WorkflowPlanningDataInput): WorkflowPlanningDataSnapshot;

package/dist/workflow/planning/capture-workflow-planning-data.js

@@ -0,0 +1,66 @@
+import { workflowMaterialArgumentSchema, workflowBlockedCallSchema, } from '../../schemas/workflow-planning-material-schema.js';
+import { captureWorkflowPlanningMaterials } from './capture-workflow-planning-materials.js';
+/** Capture only declared source data, without requiring not-yet-generated native producers. */
+export function captureWorkflowPlanningData(input) {
+    if (!Array.isArray(input.materials))
+        throw new Error('workflow planning materials must be an array');
+    for (const material of input.materials)
+        if (!material || !['ready', 'blocked'].includes(material.status))
+            throw new Error('workflow planning materials require ready or blocked status');
+    const captured = captureWorkflowPlanningMaterials({
+        scenario: input.scenario,
+        capabilities: input.capabilities,
+        preparedNativeNodes: input.preparedNativeNodes,
+        apiMaterials: input.materials.map((material) => ({
+            callId: material.status === 'ready'
+                ? material.arguments?.callId
+                : material.callId,
+            operation: material.operation,
+            purpose: material.purpose,
+            requestMediaType: material.status === 'ready'
+                ? material.arguments?.requestMediaType
+                : material.requestMediaType,
+        })),
+    });
+    const materials = input.materials.map((material, index) => {
+        const { operation, purpose, requestMediaType } = captured.apiMaterials[index];
+        const common = {
+            operation,
+            ...(purpose === undefined ? {} : { purpose }),
+        };
+        if (material.status === 'ready') {
+            const args = material.arguments;
+            return {
+                status: 'ready',
+                ...common,
+                arguments: structuredClone(workflowMaterialArgumentSchema.parse({
+                    callId: args.callId,
+                    values: args.values,
+                    bindings: args.bindings,
+                    ...(args.requestedInputs === undefined
+                        ? {}
+                        : { requestedInputs: args.requestedInputs }),
+                    unresolvedInputs: args.unresolvedInputs,
+                    ...(args.requestMediaType === undefined
+                        ? {}
+                        : { requestMediaType: args.requestMediaType }),
+                })),
+            };
+        }
+        return {
+            status: 'blocked',
+            ...common,
+            ...workflowBlockedCallSchema.parse({
+                callId: captured.apiMaterials[index].callId,
+                gapIds: structuredClone(material.gapIds),
+            }),
+            bindings: structuredClone(workflowMaterialArgumentSchema.shape.bindings.parse(material.bindings)),
+            ...(requestMediaType === undefined ? {} : { requestMediaType }),
+        };
+    });
+    return {
+        materials,
+        capabilities: captured.capabilities,
+        preparedNativeNodes: captured.preparedNativeNodes,
+    };
+}

package/dist/workflow/planning/capture-workflow-planning-materials.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowPlanningMaterialInput, WorkflowPlanningMaterialSnapshot } from '../../types/workflow-planning-materials.js';
+/** Capture the shared supplied-material protocol, without creating a fictitious planning identity. */
+export declare function captureWorkflowPlanningMaterials(input: WorkflowPlanningMaterialInput): WorkflowPlanningMaterialSnapshot;

package/dist/workflow/planning/capture-workflow-planning-materials.js

@@ -0,0 +1,53 @@
+import { isDeepStrictEqual } from 'node:util';
+import { workflowDraftNativeNodeSchema } from '../../schemas/workflow-draft-schema.js';
+import { describeApiBindingPlanning } from '../../bindings/planning/describe-api-binding-planning.js';
+import { validateNativeApiResponseReferences } from '../validate-native-api-response-references.js';
+import { captureNativePlanningCapability } from './capture-native-planning-capability.js';
+import { resolveNativePlanningMaterials } from './resolve-native-planning-materials.js';
+/** Capture the shared supplied-material protocol, without creating a fictitious planning identity. */
+export function captureWorkflowPlanningMaterials(input) {
+    const suppliedCapabilities = input.capabilities === undefined ? [] : input.capabilities;
+    if (!Array.isArray(suppliedCapabilities))
+        throw new Error('native planning capabilities must be an array');
+    const capabilities = suppliedCapabilities.map(captureNativePlanningCapability);
+    const suppliedApis = input.apiMaterials === undefined ? [] : input.apiMaterials;
+    if (!Array.isArray(suppliedApis))
+        throw new Error('native planning apiMaterials must be an array');
+    const apiMaterials = suppliedApis.length
+        ? describeApiBindingPlanning({
+            scenario: input.scenario,
+            materials: suppliedApis,
+        }).input.materials
+        : [];
+    const suppliedPrepared = input.preparedNativeNodes === undefined ? [] : input.preparedNativeNodes;
+    if (!Array.isArray(suppliedPrepared))
+        throw new Error('native planning preparedNativeNodes must be an array');
+    const preparedNativeNodes = suppliedPrepared.map((node) => {
+        const parsed = workflowDraftNativeNodeSchema.parse(node);
+        if (!isDeepStrictEqual(parsed, node))
+            throw new Error('prepared native node schema must preserve original values');
+        return {
+            id: parsed.id,
+            capability: parsed.capability,
+            parameters: structuredClone(parsed.parameters),
+            ...(parsed.runtimeParameters === undefined
+                ? {}
+                : { runtimeParameters: parsed.runtimeParameters }),
+        };
+    });
+    const resolved = resolveNativePlanningMaterials({
+        nativeNodes: preparedNativeNodes,
+        capabilities,
+        apiMaterials,
+        nativeOutputs: [],
+    });
+    const apiIds = apiMaterials.map((material) => material.callId), ids = [...apiIds, ...preparedNativeNodes.map((node) => node.id)];
+    if (new Set(ids).size !== ids.length)
+        throw new Error('native planning materials require unique non-empty IDs');
+    validateNativeApiResponseReferences({
+        nativeNodes: preparedNativeNodes,
+        capabilities: resolved.capabilities,
+        apiCallIds: apiIds,
+    });
+    return { capabilities, apiMaterials, preparedNativeNodes };
+}

package/dist/workflow/planning/create-native-node-plan.d.ts

@@ -0,0 +1,3 @@
+import type { CreateNativeNodePlanInput, NativePlanningResult } from '../../types/native-node-planning.js';
+/** Opaque symbolic IDs come from the proposal; original contracts and review gap IDs are code-owned. */
+export declare function createNativeNodePlan(input: CreateNativeNodePlanInput): NativePlanningResult;

package/dist/workflow/planning/create-native-node-plan.js

@@ -0,0 +1,54 @@
+import { nativePlanningProposalSchema } from '../../schemas/native-node-planning-record-schema.js';
+import { describeNativeNodePlanning } from './describe-native-node-planning.js';
+import { assembleNativeNodeMaterials } from './assemble-native-node-materials.js';
+import { createNativeOutputContracts } from '../create-native-output-contracts.js';
+import { validateNativeApiResponseReferences } from '../validate-native-api-response-references.js';
+import { resolveNativeStructureParameters } from '../resolve-native-structure-parameters.js';
+import { resolveNativePlanningMaterials } from './resolve-native-planning-materials.js';
+import { createWorkflowPlanningCapabilities } from '../create-workflow-planning-capabilities.js';
+/** Opaque symbolic IDs come from the proposal; original contracts and review gap IDs are code-owned. */
+export function createNativeNodePlan(input) {
+    const { input: snapshot } = describeNativeNodePlanning(input);
+    const proposal = nativePlanningProposalSchema.parse(input.proposal);
+    const prepared = snapshot.preparedNativeNodes, apis = snapshot.apiMaterials;
+    if (!snapshot.capabilities.length &&
+        (proposal.nativeNodes.length || proposal.gaps.length))
+        throw new Error('native planning without capabilities cannot attribute a model proposal');
+    const apiIds = apis.map((material) => material.callId);
+    const nodes = assembleNativeNodeMaterials(prepared, proposal.nativeNodes);
+    if (proposal.nativeNodes.some((node) => apiIds.includes(node.id)))
+        throw new Error('native node plan contains an API callId');
+    const { capabilities } = resolveNativePlanningMaterials({
+        nativeNodes: nodes,
+        capabilities: snapshot.capabilities,
+        apiMaterials: apis,
+        nativeOutputs: [],
+    });
+    const planningCapabilities = createWorkflowPlanningCapabilities({
+        capabilities,
+        apiCallIds: apiIds,
+    });
+    for (const node of proposal.nativeNodes) {
+        const capability = planningCapabilities.find((candidate) => candidate.name === node.capability);
+        if (!capability)
+            throw new Error(`node ${node.id}: unknown capability ${node.capability}`);
+        if (node.runtimeParameters !== undefined &&
+            snapshot.allowRuntimeParameters !== true)
+            throw new Error(`node ${node.id}: native planning runtime parameters were not enabled`);
+        resolveNativeStructureParameters(node, capability);
+    }
+    createNativeOutputContracts({ nativeNodes: nodes, capabilities });
+    validateNativeApiResponseReferences({
+        nativeNodes: nodes,
+        capabilities,
+        apiCallIds: apiIds,
+    });
+    const gaps = proposal.gaps.map((gap, index) => ({
+        id: `${snapshot.planId}-gap-${index + 1}`,
+        stage: 'workflow-graph',
+        description: gap.description,
+    }));
+    if (gaps.some((gap) => [...apiIds, ...nodes.map((node) => node.id)].includes(gap.id)))
+        throw new Error('native planning gap ID collides with a declared node');
+    return { nativeNodes: structuredClone(proposal.nativeNodes), gaps };
+}

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

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

package/dist/workflow/planning/create-native-node-planning-record.js

@@ -0,0 +1,69 @@
+import { isDeepStrictEqual } from 'node:util';
+import { nativePlanningResultSchema, nativePlanningAssessmentSchema, nativeNodePlanningRecordSchema, } from '../../schemas/native-node-planning-record-schema.js';
+import { describeNativeNodePlanning } from './describe-native-node-planning.js';
+import { createNativeNodePlan } from './create-native-node-plan.js';
+import { assembleNativeNodeMaterials } from './assemble-native-node-materials.js';
+import { createWorkflowNodeContracts } from '../create-workflow-node-contracts.js';
+import { resolveNativePlanningMaterials } from './resolve-native-planning-materials.js';
+export function createNativeNodePlanningRecord(input) {
+    const { input: snapshot, context } = describeNativeNodePlanning(input);
+    const plan = nativePlanningResultSchema.parse({
+        nativeNodes: input.plan.nativeNodes,
+        gaps: input.plan.gaps,
+    });
+    const expected = createNativeNodePlan({
+        ...snapshot,
+        proposal: {
+            nativeNodes: plan.nativeNodes,
+            gaps: plan.gaps.map(({ description }) => ({ description })),
+        },
+    });
+    if (!isDeepStrictEqual(plan, expected))
+        throw new Error('native planning result differs from its original proposal or code-derived gap identities');
+    const allNodes = assembleNativeNodeMaterials(snapshot.preparedNativeNodes, plan.nativeNodes);
+    const { capabilities, outputs } = resolveNativePlanningMaterials({
+        nativeNodes: allNodes,
+        capabilities: snapshot.capabilities,
+        apiMaterials: snapshot.apiMaterials,
+        nativeOutputs: [],
+    });
+    const fields = {
+        planId: snapshot.planId,
+        plan: structuredClone(plan),
+        evidence: { kind: 'native-planning-context', context },
+        verification: structuredClone({
+            contracts: createWorkflowNodeContracts({
+                materials: [],
+                nativeNodes: allNodes,
+                capabilities,
+            }),
+            outputs,
+        }),
+    };
+    if (!snapshot.capabilities.length) {
+        if (input.assessment !== undefined)
+            throw new Error('native planning without capabilities must not include a model assessment');
+        return nativeNodePlanningRecordSchema.parse({
+            ...fields,
+            kind: 'no-capabilities',
+        });
+    }
+    const assessment = nativePlanningAssessmentSchema.parse(input.assessment);
+    if (assessment.kind === 'no-additions') {
+        if (plan.nativeNodes.length)
+            throw new Error('native no-additions assessment cannot contain new native nodes');
+    }
+    else {
+        const ids = new Set(assessment.nodes.map((node) => node.nodeId));
+        if (!plan.nativeNodes.length ||
+            ids.size !== assessment.nodes.length ||
+            ids.size !== plan.nativeNodes.length ||
+            plan.nativeNodes.some((node) => !ids.has(node.id)))
+            throw new Error('native planning reasons must name every new node ID exactly once');
+    }
+    return nativeNodePlanningRecordSchema.parse({
+        ...fields,
+        kind: 'model-plan',
+        assessment,
+    });
+}

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

@@ -0,0 +1,4 @@
+import type { WorkflowCapability } from '../../types/workflow-plan.js';
+import type { NativePlanningCapabilityMaterial } from '../../types/native-node-planning.js';
+/** Serializable generation contract only; executable implementations remain host supplied. */
+export declare function createNativePlanningCapabilityMaterial(capability: WorkflowCapability, allowRuntimeParameters: boolean, allowFieldOwnership?: boolean): NativePlanningCapabilityMaterial;

package/dist/workflow/planning/create-native-planning-capability-material.js

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+import { nativeMaterialRequirementsSchema } from '../../schemas/native-material-requirements-schema.js';
+import { nativeParameterReferenceSourcesSchema } from '../../schemas/native-parameter-reference-sources-schema.js';
+/** Serializable generation contract only; executable implementations remain host supplied. */
+export function createNativePlanningCapabilityMaterial(capability, allowRuntimeParameters, allowFieldOwnership = false) {
+    if (typeof capability.name !== 'string' || !capability.name.trim())
+        throw new Error('native planning capability.name must be non-empty');
+    if (typeof capability.description !== 'string')
+        throw new Error(`native planning capability ${capability.name}.description must be a string`);
+    if (!capability.parametersSchema ||
+        typeof capability.parametersSchema.safeParse !== 'function')
+        throw new Error(`native planning capability ${capability.name}.parametersSchema must be a Zod schema`);
+    for (const field of [
+        'inputPorts',
+        'outputPorts',
+        'responseReferences',
+    ])
+        if (typeof capability[field] !== 'function')
+            throw new Error(`native planning capability ${capability.name}.${field} must be a function`);
+    for (const field of ['waitsForAllInputs', 'exclusiveOutputPorts'])
+        if (typeof capability[field] !== 'boolean')
+            throw new Error(`native planning capability ${capability.name}.${field} must be a boolean`);
+    return {
+        name: capability.name,
+        description: capability.description,
+        parametersSchema: z.toJSONSchema(capability.parametersSchema),
+        ...(capability.parameterReferenceSources === undefined
+            ? {}
+            : {
+                parameterReferenceSources: nativeParameterReferenceSourcesSchema.parse(capability.parameterReferenceSources),
+            }),
+        ...(capability.materialRequirements === undefined
+            ? {}
+            : {
+                materialRequirements: nativeMaterialRequirementsSchema.parse(capability.materialRequirements),
+            }),
+        ...(capability.materialSources === undefined
+            ? {}
+            : { materialSources: structuredClone(capability.materialSources) }),
+        parameterSources: allowRuntimeParameters && capability.supportsRuntimeParameters === true
+            ? allowFieldOwnership
+                ? ['literal', 'workflow-input', 'workflow-fields']
+                : ['literal', 'workflow-input']
+            : ['literal'],
+    };
+}

package/dist/workflow/planning/create-prepared-native-node-materials.d.ts

@@ -0,0 +1,4 @@
+import type { PlannedNativeNode, WorkflowCapability } from '../../types/workflow-plan.js';
+import type { PreparedNativeNodeMaterial } from '../../types/native-node-planning.js';
+/** Expose existing implementation-owned ports, not descriptions for the model to guess. */
+export declare function createPreparedNativeNodeMaterials(nodes: PlannedNativeNode[], capabilities: WorkflowCapability[]): PreparedNativeNodeMaterial[];

package/dist/workflow/planning/create-prepared-native-node-materials.js

@@ -0,0 +1,15 @@
+import { resolveNativeStructureParameters } from '../resolve-native-structure-parameters.js';
+/** Expose existing implementation-owned ports, not descriptions for the model to guess. */
+export function createPreparedNativeNodeMaterials(nodes, capabilities) {
+    return nodes.map((planned) => {
+        const capability = capabilities.find((item) => item.name === planned.capability);
+        if (!capability)
+            throw new Error(`prepared node ${planned.id}: unknown capability ${planned.capability}`);
+        const parameters = resolveNativeStructureParameters(planned, capability);
+        return {
+            ...planned,
+            inputPorts: capability.inputPorts(parameters),
+            outputPorts: capability.outputPorts(parameters),
+        };
+    });
+}

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

@@ -0,0 +1,4 @@
+import type { NativeNodeConfigurationInput, NativeNodeConfigurationDescription, ResolveNativeNodeParametersInput, NativeNodeParameterResult } from '../../types/native-node-planning.js';
+export declare function describeNativeNodeConfiguration(input: NativeNodeConfigurationInput): NativeNodeConfigurationDescription;
+/** Build one actual instance, never adopt a graph or turn an unfinished role into a source contract. */
+export declare function resolveNativeNodeParameters(input: ResolveNativeNodeParametersInput): NativeNodeParameterResult;