@openapi-flow/core 0.1.0 → 0.3.0

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

@@ -0,0 +1,108 @@
+import { createReviewableNodeContracts } from '../create-reviewable-node-contracts.js';
+import { createNativeOutputContracts } from '../create-native-output-contracts.js';
+import { validateWorkflowEdges } from '../validate-workflow-edges.js';
+import { inspectApiArgumentRequirements } from '../../arguments/clarification/inspect-api-argument-requirements.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,
+    });
+    for (const material of materials) {
+        if (material.status !== 'ready')
+            continue;
+        const args = material.arguments;
+        const validation = inspectApiArgumentRequirements({
+            operation: material.operation,
+            ...args,
+        });
+        if (args.unresolvedInputs.length || validation.status !== 'ready')
+            throw new Error(`materials[${args.callId}] has unresolved OAS request inputs or scenario-requested inputs`);
+    }
+    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 };
+}

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.d.ts

@@ -0,0 +1,3 @@
+import type { CreateNativeOutputContractsInput, NativeOutputContract } from '../types/node-output.js';
+/** Derive contracts from actual capabilities/parameters, never model guesses. */
+export declare function createNativeOutputContracts({ nativeNodes, capabilities, }: CreateNativeOutputContractsInput): NativeOutputContract[];

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

@@ -0,0 +1,23 @@
+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, }) {
+    const registry = new Map(capabilities.map((item) => [item.name, item]));
+    if (registry.size !== capabilities.length)
+        throw new Error('capabilities contains duplicate names');
+    const ids = new Set();
+    const outputs = nativeNodes.flatMap((planned) => {
+        if (!planned.id.trim() || ids.has(planned.id))
+            throw new Error('native nodes require unique non-empty IDs');
+        ids.add(planned.id);
+        const capability = registry.get(planned.capability);
+        if (!capability)
+            throw new Error(`node ${planned.id}: unknown capability ${planned.capability}`);
+        const parameters = resolveNativeStructureParameters(planned, capability);
+        return capability.outputSchema
+            ? [{ nodeId: planned.id, schema: capability.outputSchema(parameters) }]
+            : [];
+    });
+    validateNativeOutputContracts(outputs);
+    return outputs;
+}

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.d.ts

@@ -0,0 +1,3 @@
+import type { ValidateReviewableWorkflowGraphPlanInput } from '../types/reviewable-workflow.js';
+import type { WorkflowPlanNodeContract } from '../types/workflow-plan.js';
+export declare function createReviewableNodeContracts({ plan, materials, capabilities, }: ValidateReviewableWorkflowGraphPlanInput): WorkflowPlanNodeContract[];

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

@@ -0,0 +1,28 @@
+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');
+    const contracts = createWorkflowNodeContracts({
+        materials: ready,
+        nativeNodes: plan.nativeNodes,
+        capabilities,
+    });
+    for (const contract of contracts)
+        if (blocked.has(contract.id)) {
+            contract.dependencyNodeIds = contract.references.map((reference) => reference.nodeId);
+            contract.references = [];
+        }
+    for (const material of materials.filter((item) => item.status === 'blocked'))
+        contracts.push({
+            id: material.callId,
+            inputs: ['main'],
+            outputs: ['main'],
+            references: [],
+            dependencyNodeIds: material.bindings.map((binding) => binding.sourceNodeId),
+            waitsForAllInputs: false,
+            exclusiveOutputPorts: false,
+        });
+    contracts.push(...createUnresolvedNodeContracts(plan.gaps));
+    return contracts;
+}

package/dist/workflow/create-reviewable-workflow-graph-plan.d.ts

@@ -0,0 +1,2 @@
+import type { CreateReviewableWorkflowGraphPlanInput, ReviewableWorkflowGraphPlan } from '../types/reviewable-workflow.js';
+export declare function createReviewableWorkflowGraphPlan(input: CreateReviewableWorkflowGraphPlanInput): ReviewableWorkflowGraphPlan;

package/dist/workflow/create-reviewable-workflow-graph-plan.js

@@ -0,0 +1,29 @@
+import { createReviewableNodeContracts } from './create-reviewable-node-contracts.js';
+import { validateReviewableWorkflowGraphPlan } from './validate-reviewable-workflow-graph-plan.js';
+export function createReviewableWorkflowGraphPlan(input) {
+    const { proposal, materials } = input;
+    const plan = {
+        nativeNodes: proposal.nativeNodes,
+        edges: proposal.edges,
+        gaps: [
+            ...input.gaps,
+            ...proposal.additionalGaps.map((gap) => ({
+                ...gap,
+                stage: 'workflow-graph',
+            })),
+        ],
+        blockedCalls: [
+            ...materials
+                .filter((item) => item.status === 'blocked')
+                .map((item) => ({ callId: item.callId, gapIds: item.gapIds })),
+            ...proposal.blockedCalls,
+        ],
+        starts: [],
+    };
+    const incoming = new Set(plan.edges.map((edge) => edge.to));
+    plan.starts = createReviewableNodeContracts({ ...input, plan })
+        .filter((item) => !incoming.has(item.id))
+        .map((item) => item.id);
+    validateReviewableWorkflowGraphPlan({ ...input, plan });
+    return plan;
+}

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-graph-plan.d.ts

@@ -0,0 +1,2 @@
+import type { CreateWorkflowGraphPlanInput, WorkflowGraphPlan } from '../types/workflow-plan.js';
+export declare function createWorkflowGraphPlan(input: CreateWorkflowGraphPlanInput): WorkflowGraphPlan;

package/dist/workflow/create-workflow-graph-plan.js

@@ -0,0 +1,17 @@
+import { validateWorkflowGraphPlan } from './validate-workflow-graph-plan.js';
+export function createWorkflowGraphPlan(input) {
+    const incomingIds = new Set(input.proposal.edges.map((edge) => edge.to));
+    const nodeIds = [
+        ...input.materials.map((item) => item.arguments.callId),
+        ...input.proposal.nativeNodes.map((item) => item.id),
+    ];
+    const plan = {
+        ...input.proposal,
+        starts: input.proposal.gaps.length
+            ? []
+            : nodeIds.filter((id) => !incomingIds.has(id)),
+    };
+    if (!plan.gaps.length)
+        validateWorkflowGraphPlan({ ...input, plan });
+    return plan;
+}

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

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

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

@@ -0,0 +1,68 @@
+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');
+    const contracts = materials.map((item) => ({
+        id: item.arguments.callId,
+        inputs: ['main'],
+        outputs: ['main'],
+        references: item.arguments.bindings.map((binding) => ({
+            source: materials.some((source) => source.arguments.callId === binding.sourceNodeId)
+                ? 'response'
+                : 'node-output',
+            nodeId: binding.sourceNodeId,
+            pointer: binding.sourcePointer,
+        })),
+        dependencyNodeIds: [],
+        waitsForAllInputs: false,
+        exclusiveOutputPorts: false,
+    }));
+    for (const native of nativeNodes) {
+        const capability = registry.get(native.capability);
+        if (!capability)
+            throw new Error(`node ${native.id}: unknown capability ${native.capability}`);
+        const parameters = resolveNativeStructureParameters(native, capability);
+        const contract = {
+            id: native.id,
+            inputs: capability.inputPorts(parameters),
+            outputs: capability.outputPorts(parameters),
+            references: [
+                ...capability.responseReferences(parameters),
+                ...(capability.nodeOutputReferences
+                    ? capability.nodeOutputReferences(parameters)
+                    : []),
+            ],
+            ...(capability.inputReferences
+                ? { inputReferences: capability.inputReferences(parameters) }
+                : {}),
+            dependencyNodeIds: [],
+            waitsForAllInputs: capability.waitsForAllInputs,
+            exclusiveOutputPorts: capability.exclusiveOutputPorts,
+            ...(capability.rejoinsExclusiveOutputs
+                ? {
+                    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/create-workflow-planning-capabilities.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowCapability } from '../types/workflow-plan.js';
+import type { WorkflowCapabilityPlanningInput } from '../types/workflow-capability-planning.js';
+export declare function createWorkflowPlanningCapabilities({ capabilities, apiCallIds, }: WorkflowCapabilityPlanningInput): WorkflowCapability[];

package/dist/workflow/create-workflow-planning-capabilities.js

@@ -0,0 +1,20 @@
+import { assertApiCallIdentities } from './assert-api-call-identities.js';
+export function createWorkflowPlanningCapabilities({ capabilities, apiCallIds, }) {
+    assertApiCallIdentities(apiCallIds);
+    if (!Array.isArray(capabilities))
+        throw new Error('planning.capabilities must be an array');
+    if (new Set(capabilities.map((item) => item.name)).size !== capabilities.length)
+        throw new Error('planning.capabilities contains duplicate names');
+    return capabilities.map((capability) => {
+        if (capability.createPlanningParametersSchema === undefined)
+            return capability;
+        if (typeof capability.createPlanningParametersSchema !== 'function')
+            throw new Error(`planning.capabilities[${capability.name}].createPlanningParametersSchema must be a function`);
+        const parametersSchema = capability.createPlanningParametersSchema({
+            apiCallIds: [...apiCallIds],
+        });
+        if (!parametersSchema || typeof parametersSchema.safeParse !== 'function')
+            throw new Error(`planning.capabilities[${capability.name}].createPlanningParametersSchema must return a Zod schema`);
+        return { ...capability, parametersSchema };
+    });
+}

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;