@openapi-flow/core 0.2.0 → 0.3.1

package/dist/workflow/connections/describe-workflow-connection-planning.js

@@ -0,0 +1,85 @@
+import { workflowConnectionIdentitySchema } from '../../schemas/workflow-connection-planning-schema.js';
+import { workflowDraftEdgeSchema } from '../../schemas/workflow-draft-schema.js';
+import { captureWorkflowPlanningData } from '../planning/capture-workflow-planning-data.js';
+import { workflowReviewGapSchema } from '../../schemas/workflow-planning-material-schema.js';
+import { createPreparedNativeNodeMaterials } from '../planning/create-prepared-native-node-materials.js';
+import { createNativeOutputContracts } from '../create-native-output-contracts.js';
+import { createNativePlanningCapabilityMaterial } from '../planning/create-native-planning-capability-material.js';
+import { prepareWorkflowConnectionMaterials } from './prepare-workflow-connection-materials.js';
+/** Capture declared data before awaiting the model; never clone opaque callbacks or forward audit metadata. */
+export function describeWorkflowConnectionPlanning(input) {
+    const { scenario } = workflowConnectionIdentitySchema.parse({
+        scenario: input.scenario,
+    });
+    for (const field of [
+        'materials',
+        'capabilities',
+        'nativeNodes',
+        'gaps',
+        'edges',
+    ])
+        if (input[field] !== undefined && !Array.isArray(input[field]))
+            throw new Error(`connection planning ${field} must be an array`);
+    const supplied = input.materials === undefined ? [] : input.materials;
+    const captured = captureWorkflowPlanningData({
+        scenario,
+        capabilities: input.capabilities,
+        preparedNativeNodes: input.nativeNodes,
+        materials: supplied,
+    });
+    const materials = captured.materials;
+    const prepared = prepareWorkflowConnectionMaterials({
+        materials,
+        deferredApiInputIds: input.deferredApiInputIds,
+        capabilities: captured.capabilities,
+        nativeNodes: captured.preparedNativeNodes,
+        gaps: structuredClone((input.gaps === undefined ? [] : input.gaps).map((gap) => workflowReviewGapSchema.parse(gap))),
+        edges: structuredClone((input.edges === undefined ? [] : input.edges).map((edge) => workflowDraftEdgeSchema.parse(edge))),
+    });
+    const context = {
+        scenario,
+        nodes: structuredClone(prepared.contracts),
+        ...(prepared.nativeNodes.length
+            ? {
+                nativeNodes: structuredClone(createPreparedNativeNodeMaterials(prepared.nativeNodes, prepared.capabilities)),
+                nativeParameterReadiness: prepared.nativeNodes.map((node) => ({
+                    nodeId: node.id,
+                    planTimeStatus: 'validated',
+                    executionInputPointers: node.runtimeParameters === undefined
+                        ? []
+                        : node.runtimeParameters === true
+                            ? ['']
+                            : [...node.runtimeParameters.pointers],
+                })),
+            }
+            : {}),
+        edges: structuredClone(prepared.edges),
+        gaps: structuredClone(prepared.gaps),
+        readyCallIds: materials.flatMap((material) => material.status === 'ready' ? [material.arguments.callId] : []),
+        apiRoles: materials.flatMap((material) => material.purpose === undefined
+            ? []
+            : [
+                {
+                    callId: material.status === 'ready'
+                        ? material.arguments.callId
+                        : material.callId,
+                    purpose: material.purpose,
+                },
+            ]),
+        ...(prepared.deferredApiInputs === undefined
+            ? {}
+            : { deferredApiInputs: structuredClone(prepared.deferredApiInputs) }),
+    };
+    return {
+        input: { ...prepared, scenario },
+        context,
+        sources: structuredClone({
+            materials,
+            nativeOutputs: createNativeOutputContracts({
+                nativeNodes: prepared.nativeNodes,
+                capabilities: prepared.capabilities,
+            }),
+            capabilities: prepared.capabilities.map((capability) => createNativePlanningCapabilityMaterial(capability, false)),
+        }),
+    };
+}

package/dist/workflow/connections/prepare-workflow-connection-materials.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowConnectionMaterialInput, WorkflowConnectionMaterials } from '../../types/workflow-connection-planning.js';
+/** Validate immutable supplied data before paying for any orchestration model call. */
+export declare function prepareWorkflowConnectionMaterials(input: WorkflowConnectionMaterialInput): WorkflowConnectionMaterials;

package/dist/workflow/connections/prepare-workflow-connection-materials.js

@@ -0,0 +1,112 @@
+import { createReviewableNodeContracts } from '../create-reviewable-node-contracts.js';
+import { createNativeOutputContracts } from '../create-native-output-contracts.js';
+import { validateWorkflowEdges } from '../validate-workflow-edges.js';
+import { validateWorkflowApiInputReadiness } from '../validate-workflow-api-input-readiness.js';
+import { validateApiBindingAssignments } from '../../bindings/validate-api-binding-assignments.js';
+import { validateNativeApiResponseReferences } from '../validate-native-api-response-references.js';
+import { createNativeParameterGenerationContract } from '../../schemas/create-native-parameter-generation-contract.js';
+import { jsonValuesEqual } from '../../utils/json-values-equal.js';
+/** Validate immutable supplied data before paying for any orchestration model call. */
+export function prepareWorkflowConnectionMaterials(input) {
+    for (const field of [
+        'materials',
+        'capabilities',
+        'nativeNodes',
+        'gaps',
+        'edges',
+    ])
+        if (input[field] !== undefined && !Array.isArray(input[field]))
+            throw new Error(`connection materials ${field} must be an array`);
+    const materials = input.materials === undefined ? [] : input.materials;
+    const capabilities = input.capabilities === undefined ? [] : input.capabilities;
+    const nativeNodes = input.nativeNodes === undefined ? [] : input.nativeNodes;
+    const gaps = input.gaps === undefined ? [] : input.gaps;
+    const edges = input.edges === undefined ? [] : input.edges;
+    for (const material of materials) {
+        if (material.status !== 'blocked')
+            continue;
+        if (!Array.isArray(material.gapIds) ||
+            !material.gapIds.length ||
+            new Set(material.gapIds).size !== material.gapIds.length ||
+            material.gapIds.some((id) => !gaps.some((gap) => gap.id === id)))
+            throw new Error(`materials[${material.callId}].gapIds must name declared gaps exactly once`);
+    }
+    validateNativeApiResponseReferences({
+        nativeNodes,
+        capabilities,
+        apiCallIds: materials.map((material) => material.status === 'ready' ? material.arguments.callId : material.callId),
+    });
+    // Ownership inspection may accept unfinished literals while deriving a slot.
+    // Final connection materials may not: every non-runtime setting must be ready.
+    for (const node of nativeNodes) {
+        if (node.runtimeParameters === undefined || node.runtimeParameters === true)
+            continue;
+        const capability = capabilities.find((entry) => entry.name === node.capability);
+        if (!capability)
+            throw new Error(`connection native ${node.id}: missing capability ${node.capability}`);
+        const contract = createNativeParameterGenerationContract({
+            nodeId: node.id,
+            capability,
+            runtimeParameters: node.runtimeParameters,
+        });
+        const checked = contract.valuesSchema.safeParse(node.parameters);
+        if (!checked.success || !jsonValuesEqual(checked.data, node.parameters))
+            throw new Error(`connection native ${node.id}: unresolved or invalid plan-time parameter literals`, { cause: checked.success ? undefined : checked.error });
+    }
+    const nativeOutputs = createNativeOutputContracts({
+        nativeNodes,
+        capabilities,
+    });
+    const deferredApiInputs = validateWorkflowApiInputReadiness({
+        materials,
+        deferredApiInputIds: input.deferredApiInputIds,
+    });
+    if (materials.length)
+        validateApiBindingAssignments({
+            nativeOutputs,
+            materials: materials.map((material) => ({
+                operation: material.operation,
+                callId: material.status === 'ready'
+                    ? material.arguments.callId
+                    : material.callId,
+                requestMediaType: material.status === 'ready'
+                    ? material.arguments.requestMediaType
+                    : material.requestMediaType,
+            })),
+            calls: materials.map((material) => ({
+                callId: material.status === 'ready'
+                    ? material.arguments.callId
+                    : material.callId,
+                bindings: material.status === 'ready'
+                    ? material.arguments.bindings
+                    : material.bindings,
+            })),
+        });
+    const plan = {
+        nativeNodes,
+        gaps,
+        edges,
+        starts: [],
+        blockedCalls: materials.flatMap((material) => material.status === 'blocked'
+            ? [{ callId: material.callId, gapIds: material.gapIds }]
+            : []),
+    };
+    const contracts = createReviewableNodeContracts({
+        materials,
+        capabilities,
+        plan,
+    });
+    validateWorkflowEdges({ contracts, edges });
+    return {
+        materials,
+        capabilities,
+        nativeNodes,
+        gaps,
+        edges,
+        contracts,
+        ...(input.deferredApiInputIds === undefined
+            ? {}
+            : { deferredApiInputIds: [...input.deferredApiInputIds] }),
+        ...(deferredApiInputs.length ? { deferredApiInputs } : {}),
+    };
+}

package/dist/workflow/connections/project-workflow-connection-decision.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowConnectionDecision, WorkflowConnectionProposal } from '../../types/workflow-connection-planning.js';
+/** Project only validated execution decisions; reasons never become workflow data. */
+export declare function projectWorkflowConnectionDecision(input: WorkflowConnectionDecision): WorkflowConnectionProposal;

package/dist/workflow/connections/project-workflow-connection-decision.js

@@ -0,0 +1,18 @@
+import { workflowConnectionDecisionSchema } from '../../schemas/workflow-connection-planning-schema.js';
+/** Project only validated execution decisions; reasons never become workflow data. */
+export function projectWorkflowConnectionDecision(input) {
+    const decision = workflowConnectionDecisionSchema.parse(input);
+    return {
+        edges: decision.edges.map(({ from, output, to, input }) => ({
+            from,
+            output,
+            to,
+            input,
+        })),
+        blockedCalls: decision.blockedCalls.map(({ callId, gapIds }) => ({
+            callId,
+            gapIds: structuredClone(gapIds),
+        })),
+        additionalGaps: structuredClone(decision.additionalGaps),
+    };
+}

package/dist/workflow/connections/validate-workflow-connection-planning-record.d.ts

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

package/dist/workflow/connections/validate-workflow-connection-planning-record.js

@@ -0,0 +1,12 @@
+import { isDeepStrictEqual } from 'node:util';
+import { workflowConnectionPlanningRecordSchema } from '../../schemas/workflow-connection-planning-schema.js';
+import { createWorkflowConnectionPlanningRecord } from './create-workflow-connection-planning-record.js';
+export function validateWorkflowConnectionPlanningRecord(input) {
+    const record = workflowConnectionPlanningRecordSchema.parse(input.record);
+    const expected = createWorkflowConnectionPlanningRecord({
+        ...input,
+        decision: record.decision,
+    });
+    if (!isDeepStrictEqual(record, expected))
+        throw new Error('connection planning record differs from its original scenario, API/native sources, fixed edges, proposed plan or derived contracts');
+}

package/dist/workflow/create-native-output-contracts.js

@@ -1,4 +1,4 @@
-import { parseNativeNodeParameters } from './parse-native-node-parameters.js';
+import { resolveNativeStructureParameters } from './resolve-native-structure-parameters.js';
 import { validateNativeOutputContracts } from '../bindings/validate-native-output-contracts.js';
 /** Derive contracts from actual capabilities/parameters, never model guesses. */
 export function createNativeOutputContracts({ nativeNodes, capabilities, }) {
@@ -13,7 +13,7 @@ export function createNativeOutputContracts({ nativeNodes, capabilities, }) {
         const capability = registry.get(planned.capability);
         if (!capability)
             throw new Error(`node ${planned.id}: unknown capability ${planned.capability}`);
-        const parameters = parseNativeNodeParameters(planned, capability);
+        const parameters = resolveNativeStructureParameters(planned, capability);
         return capability.outputSchema
             ? [{ nodeId: planned.id, schema: capability.outputSchema(parameters) }]
             : [];

package/dist/workflow/create-native-structure-contracts.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowNodeContractsInput, WorkflowPlanNodeContract } from '../types/workflow-plan.js';
+/** Edit discovery reads explicit structure, not a not-yet-repaired source schema. Never final graph validation. */
+export declare function createNativeStructureContracts(input: WorkflowNodeContractsInput): WorkflowPlanNodeContract[];

package/dist/workflow/create-native-structure-contracts.js

@@ -0,0 +1,38 @@
+import { createWorkflowNodeContracts } from './create-workflow-node-contracts.js';
+import { inspectNativeReferenceStructure } from './inspect-native-reference-structure.js';
+/** Edit discovery reads explicit structure, not a not-yet-repaired source schema. Never final graph validation. */
+export function createNativeStructureContracts(input) {
+    const contracts = createWorkflowNodeContracts({ ...input, nativeNodes: [] });
+    for (const node of input.nativeNodes) {
+        const capability = input.capabilities.find((capability) => capability.name === node.capability);
+        if (!capability)
+            throw new Error(`Native structure node ${node.id}: unknown capability ${node.capability}`);
+        if (!capability.referenceStructureSchema) {
+            contracts.push(...createWorkflowNodeContracts({
+                materials: [],
+                nativeNodes: [node],
+                capabilities: [capability],
+            }));
+            continue;
+        }
+        const bindings = inspectNativeReferenceStructure({ node, capability });
+        const controls = bindings.filter((binding) => binding.reference.source === 'exclusive-output');
+        if (controls.length > 1)
+            throw new Error(`Native ${node.id} declares multiple exclusive rejoin producers`);
+        contracts.push({
+            id: node.id,
+            inputs: capability.inputPorts(node.parameters),
+            outputs: capability.outputPorts(node.parameters),
+            references: bindings.flatMap((binding) => binding.reference.source === 'exclusive-output'
+                ? []
+                : [binding.reference]),
+            dependencyNodeIds: [],
+            waitsForAllInputs: capability.waitsForAllInputs,
+            exclusiveOutputPorts: capability.exclusiveOutputPorts,
+            ...(controls.length
+                ? { rejoinsExclusiveOutputs: controls[0].reference.nodeId }
+                : {}),
+        });
+    }
+    return contracts;
+}

package/dist/workflow/create-reviewable-node-contracts.js

@@ -1,4 +1,5 @@
 import { createWorkflowNodeContracts } from './create-workflow-node-contracts.js';
+import { createUnresolvedNodeContracts } from './create-unresolved-node-contracts.js';
 export function createReviewableNodeContracts({ plan, materials, capabilities, }) {
     const blocked = new Set(plan.blockedCalls.map((item) => item.callId));
     const ready = materials.filter((item) => item.status === 'ready');
@@ -22,15 +23,6 @@ export function createReviewableNodeContracts({ plan, materials, capabilities, }
             waitsForAllInputs: false,
             exclusiveOutputPorts: false,
         });
-    for (const gap of plan.gaps)
-        contracts.push({
-            id: gap.id,
-            inputs: ['main'],
-            outputs: ['main'],
-            references: [],
-            dependencyNodeIds: [],
-            waitsForAllInputs: false,
-            exclusiveOutputPorts: false,
-        });
+    contracts.push(...createUnresolvedNodeContracts(plan.gaps));
     return contracts;
 }

package/dist/workflow/create-unresolved-node-contracts.d.ts

@@ -0,0 +1,4 @@
+import type { WorkflowUnresolvedNode } from '../types/workflow-draft-capability-gap.js';
+import type { WorkflowPlanNodeContract } from '../types/workflow-plan.js';
+/** Structural ports do not advertise a usable response/value contract. */
+export declare function createUnresolvedNodeContracts(nodes: WorkflowUnresolvedNode[]): WorkflowPlanNodeContract[];

package/dist/workflow/create-unresolved-node-contracts.js

@@ -0,0 +1,12 @@
+/** Structural ports do not advertise a usable response/value contract. */
+export function createUnresolvedNodeContracts(nodes) {
+    return nodes.map((node) => ({
+        id: node.id,
+        inputs: ['main'],
+        outputs: ['main'],
+        references: [],
+        dependencyNodeIds: [],
+        waitsForAllInputs: false,
+        exclusiveOutputPorts: false,
+    }));
+}

package/dist/workflow/create-workflow-node-contracts.d.ts

@@ -1,2 +1,2 @@
 import type { WorkflowNodeContractsInput, WorkflowPlanNodeContract } from '../types/workflow-plan.js';
-export declare function createWorkflowNodeContracts({ materials, nativeNodes, capabilities, }: WorkflowNodeContractsInput): WorkflowPlanNodeContract[];
+export declare function createWorkflowNodeContracts({ materials, nativeNodes, capabilities, unresolvedNodes, }: WorkflowNodeContractsInput): WorkflowPlanNodeContract[];

package/dist/workflow/create-workflow-node-contracts.js

@@ -1,5 +1,7 @@
-import { parseNativeNodeParameters } from './parse-native-node-parameters.js';
-export function createWorkflowNodeContracts({ materials, nativeNodes, capabilities, }) {
+import { resolveNativeStructureParameters } from './resolve-native-structure-parameters.js';
+import { requireNativeParameterReferenceSources } from './planning/select-native-parameter-producers.js';
+import { createUnresolvedNodeContracts } from './create-unresolved-node-contracts.js';
+export function createWorkflowNodeContracts({ materials, nativeNodes, capabilities, unresolvedNodes, }) {
     const registry = new Map(capabilities.map((item) => [item.name, item]));
     if (registry.size !== capabilities.length)
         throw new Error('capabilities contains duplicate names');
@@ -22,8 +24,8 @@ export function createWorkflowNodeContracts({ materials, nativeNodes, capabiliti
         const capability = registry.get(native.capability);
         if (!capability)
             throw new Error(`node ${native.id}: unknown capability ${native.capability}`);
-        const parameters = parseNativeNodeParameters(native, capability);
-        contracts.push({
+        const parameters = resolveNativeStructureParameters(native, capability);
+        const contract = {
             id: native.id,
             inputs: capability.inputPorts(parameters),
             outputs: capability.outputPorts(parameters),
@@ -44,7 +46,23 @@ export function createWorkflowNodeContracts({ materials, nativeNodes, capabiliti
                     rejoinsExclusiveOutputs: capability.rejoinsExclusiveOutputs(parameters),
                 }
                 : {}),
-        });
+        };
+        if (capability.parameterReferenceSources !== undefined) {
+            const supported = requireNativeParameterReferenceSources(capability);
+            const actual = [
+                ...contract.references,
+                ...Object.values(contract.inputReferences === undefined
+                    ? {}
+                    : contract.inputReferences).flat(),
+            ];
+            if (actual.some((reference) => !supported.includes(reference.source)) ||
+                (contract.rejoinsExclusiveOutputs !== undefined &&
+                    !supported.includes('exclusive-output')))
+                throw new Error(`Native capability ${capability.name}.parameterReferenceSources contradicts actual references for node ${native.id}`);
+        }
+        contracts.push(contract);
     }
+    if (unresolvedNodes !== undefined)
+        contracts.push(...createUnresolvedNodeContracts(unresolvedNodes));
     return contracts;
 }

package/dist/workflow/describe-native-reference-bindings.d.ts

@@ -0,0 +1,3 @@
+import type { DescribeNativeReferenceBindingsInput, WorkflowNativeReferenceBinding } from '../types/native-parameter-reference.js';
+/** Validate an implementation's declared locations against its actual reference declarations. */
+export declare function describeNativeReferenceBindings(input: DescribeNativeReferenceBindingsInput): WorkflowNativeReferenceBinding[];

package/dist/workflow/describe-native-reference-bindings.js

@@ -0,0 +1,37 @@
+import { isDeepStrictEqual } from 'node:util';
+import { resolveNativeStructureParameters } from './resolve-native-structure-parameters.js';
+import { validateNativeReferenceBindingLocations } from './validate-native-reference-binding-locations.js';
+/** Validate an implementation's declared locations against its actual reference declarations. */
+export function describeNativeReferenceBindings(input) {
+    if (typeof input.capability.parameterReferenceBindings !== 'function')
+        throw new Error(`Native capability ${input.capability.name} must declare parameterReferenceBindings for bounded consumer repair`);
+    const parameters = resolveNativeStructureParameters(input.node, input.capability);
+    const references = [
+        ...input.capability.responseReferences(parameters),
+        ...(input.capability.nodeOutputReferences
+            ? input.capability.nodeOutputReferences(parameters)
+            : []),
+        ...Object.values(input.capability.inputReferences
+            ? input.capability.inputReferences(parameters)
+            : {}).flat(),
+        ...(input.capability.rejoinsExclusiveOutputs
+            ? [
+                {
+                    source: 'exclusive-output',
+                    nodeId: input.capability.rejoinsExclusiveOutputs(parameters),
+                },
+            ]
+            : []),
+    ];
+    const bindings = input.capability.parameterReferenceBindings(parameters);
+    if (!Array.isArray(bindings))
+        throw new Error(`Native capability ${input.capability.name}.parameterReferenceBindings must return an array`);
+    validateNativeReferenceBindingLocations(input.node.id, parameters, bindings);
+    for (const binding of bindings) {
+        if (!references.some((reference) => isDeepStrictEqual(reference, binding.reference)))
+            throw new Error(`Native reference binding for ${input.node.id} is not an implementation-declared reference`);
+    }
+    if (references.some((reference) => !bindings.some((binding) => isDeepStrictEqual(binding.reference, reference))))
+        throw new Error(`Native capability ${input.capability.name}.parameterReferenceBindings omits a declared reference`);
+    return structuredClone(bindings);
+}

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

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

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

@@ -0,0 +1,51 @@
+import { isDeepStrictEqual } from 'node:util';
+import { workflowGraphPlanningProposalSchema, workflowGraphPlanningAssessmentSchema, executableGraphPlanningResultSchema, reviewableGraphPlanningResultSchema, workflowGraphPlanningRecordSchema, } from '../../schemas/workflow-graph-planning-schema.js';
+import { describeWorkflowGraphPlanning } from './describe-workflow-graph-planning.js';
+import { createWorkflowGraphPlanningResult } from './create-workflow-graph-planning-result.js';
+import { describeWorkflowGraphPlanningVerification } from './describe-workflow-graph-planning-verification.js';
+export function createWorkflowGraphPlanningRecord(input) {
+    const { input: snapshot, context, sources, } = describeWorkflowGraphPlanning(input);
+    const proposal = workflowGraphPlanningProposalSchema.parse(input.proposal);
+    const assessment = workflowGraphPlanningAssessmentSchema.parse(input.assessment);
+    const ids = assessment.nodes.map((node) => node.nodeId);
+    if (new Set(ids).size !== ids.length ||
+        ids.length !== proposal.additionalNativeNodes.length ||
+        proposal.additionalNativeNodes.some((node) => !ids.includes(node.id)))
+        throw new Error('graph reasons must name every additional native node exactly once');
+    const edges = assessment.edges.map(({ from, output, to, input }) => ({
+        from,
+        output,
+        to,
+        input,
+    }));
+    const blockedCalls = assessment.blockedCalls.map(({ callId, gapIds }) => ({
+        callId,
+        gapIds,
+    }));
+    if (!isDeepStrictEqual(edges, proposal.edges) ||
+        !isDeepStrictEqual(blockedCalls, proposal.mode === 'reviewable' ? proposal.blockedCalls : []))
+        throw new Error('graph reasons must match every proposed edge and newly blocked call exactly');
+    const fields = {
+        nativeNodes: input.plan.nativeNodes,
+        edges: input.plan.edges,
+        gaps: input.plan.gaps,
+        starts: input.plan.starts,
+    };
+    const plan = snapshot.mode === 'executable'
+        ? executableGraphPlanningResultSchema.parse(fields)
+        : reviewableGraphPlanningResultSchema.parse({
+            ...fields,
+            blockedCalls: 'blockedCalls' in input.plan ? input.plan.blockedCalls : undefined,
+        });
+    const expected = createWorkflowGraphPlanningResult({ ...snapshot, proposal });
+    if (!isDeepStrictEqual(plan, expected))
+        throw new Error('graph planning result differs from original prepared/API materials or proposed graph');
+    return workflowGraphPlanningRecordSchema.parse({
+        kind: snapshot.mode,
+        proposal,
+        assessment,
+        evidence: { kind: 'supplied-graph-materials', context, sources },
+        plan: structuredClone(plan),
+        verification: structuredClone(describeWorkflowGraphPlanningVerification(snapshot, expected)),
+    });
+}

package/dist/workflow/graphs/create-workflow-graph-planning-result.d.ts

@@ -0,0 +1,4 @@
+import type { CreateWorkflowGraphPlanningResultInput } from '../../types/workflow-graph-planning.js';
+import type { WorkflowGraphPlan } from '../../types/workflow-plan.js';
+import type { ReviewableWorkflowGraphPlan } from '../../types/reviewable-workflow.js';
+export declare function createWorkflowGraphPlanningResult(input: CreateWorkflowGraphPlanningResultInput): WorkflowGraphPlan | ReviewableWorkflowGraphPlan;

package/dist/workflow/graphs/create-workflow-graph-planning-result.js

@@ -0,0 +1,37 @@
+import { workflowGraphPlanningProposalSchema } from '../../schemas/workflow-graph-planning-schema.js';
+import { describeWorkflowGraphPlanning } from './describe-workflow-graph-planning.js';
+import { assembleNativeNodeMaterials } from '../planning/assemble-native-node-materials.js';
+import { createWorkflowGraphPlan } from '../create-workflow-graph-plan.js';
+import { createReviewableWorkflowGraphPlan } from '../create-reviewable-workflow-graph-plan.js';
+export function createWorkflowGraphPlanningResult(input) {
+    const { input: snapshot } = describeWorkflowGraphPlanning(input);
+    const proposal = workflowGraphPlanningProposalSchema.parse(input.proposal);
+    if (proposal.mode !== snapshot.mode)
+        throw new Error('graph proposal mode differs from its supplied planning mode');
+    const nativeNodes = assembleNativeNodeMaterials(snapshot.preparedNativeNodes, proposal.additionalNativeNodes);
+    if (proposal.mode === 'reviewable')
+        return createReviewableWorkflowGraphPlan({
+            ...snapshot,
+            proposal: {
+                nativeNodes,
+                edges: proposal.edges,
+                additionalGaps: proposal.additionalGaps,
+                blockedCalls: proposal.blockedCalls,
+            },
+        });
+    return createWorkflowGraphPlan({
+        capabilities: snapshot.capabilities,
+        materials: snapshot.materials.map((material) => {
+            if (material.status !== 'ready')
+                throw new Error('executable graph material must remain ready');
+            return {
+                operation: material.operation,
+                arguments: material.arguments,
+                ...(material.purpose === undefined
+                    ? {}
+                    : { purpose: material.purpose }),
+            };
+        }),
+        proposal: { nativeNodes, edges: proposal.edges, gaps: proposal.gaps },
+    });
+}

package/dist/workflow/graphs/describe-workflow-graph-planning-verification.d.ts

@@ -0,0 +1,5 @@
+import type { WorkflowGraphPlanningSnapshot, WorkflowGraphPlanningVerification } from '../../types/workflow-graph-planning.js';
+import type { WorkflowGraphPlan } from '../../types/workflow-plan.js';
+import type { ReviewableWorkflowGraphPlan } from '../../types/reviewable-workflow.js';
+/** Distinguish a legacy non-executable gap report from a fully validated graph. */
+export declare function describeWorkflowGraphPlanningVerification(snapshot: WorkflowGraphPlanningSnapshot, plan: WorkflowGraphPlan | ReviewableWorkflowGraphPlan): WorkflowGraphPlanningVerification;

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

@@ -0,0 +1,49 @@
+import { createWorkflowNodeContracts } from '../create-workflow-node-contracts.js';
+import { createReviewableNodeContracts } from '../create-reviewable-node-contracts.js';
+import { createNativeOutputContracts } from '../create-native-output-contracts.js';
+import { resolveNativeMaterialSnapshot } from '../resolve-native-material-snapshot.js';
+import { NativeMaterialResolutionError } from '../native-material-resolution-error.js';
+/** Distinguish a legacy non-executable gap report from a fully validated graph. */
+export function describeWorkflowGraphPlanningVerification(snapshot, plan) {
+    if (snapshot.mode === 'reviewable') {
+        if (!('blockedCalls' in plan))
+            throw new Error('reviewable graph verification requires blockedCalls');
+        return {
+            status: 'validated',
+            contracts: createReviewableNodeContracts({ ...snapshot, plan }),
+            outputs: createNativeOutputContracts({
+                nativeNodes: plan.nativeNodes,
+                capabilities: snapshot.capabilities,
+            }),
+        };
+    }
+    if (plan.gaps.length)
+        return { status: 'needs-review' };
+    const materials = snapshot.materials.map((material) => {
+        if (material.status !== 'ready')
+            throw new Error('executable graph verification requires ready materials');
+        return material;
+    });
+    const native = resolveNativeMaterialSnapshot({
+        apiMaterials: materials.map((material) => ({
+            callId: material.arguments.callId,
+            operation: material.operation,
+            requestMediaType: material.arguments.requestMediaType,
+        })),
+        nativeOutputs: [],
+        deferredNodeIds: [],
+        nativeNodes: plan.nativeNodes,
+        capabilities: snapshot.capabilities,
+    });
+    if (native.status !== 'ready')
+        throw new NativeMaterialResolutionError(native.pending);
+    return {
+        status: 'validated',
+        contracts: createWorkflowNodeContracts({
+            materials,
+            nativeNodes: plan.nativeNodes,
+            capabilities: native.capabilities,
+        }),
+        outputs: native.outputs,
+    };
+}

package/dist/workflow/graphs/describe-workflow-graph-planning.d.ts

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