@openapi-flow/core 0.1.0 → 0.3.0

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

@@ -0,0 +1,12 @@
+import { isDeepStrictEqual } from 'node:util';
+import { nativeNodePlanningRecordSchema } from '../../schemas/native-node-planning-record-schema.js';
+import { createNativeNodePlanningRecord } from './create-native-node-planning-record.js';
+export function validateNativeNodePlanningRecord(input) {
+    const record = nativeNodePlanningRecordSchema.parse(input.record);
+    const expected = createNativeNodePlanningRecord({
+        ...input,
+        ...(record.kind === 'model-plan' ? { assessment: record.assessment } : {}),
+    });
+    if (!isDeepStrictEqual(record, expected))
+        throw new Error('Native planning record differs from the original scenario, prepared instances, implementation contracts or actual proposal');
+}

package/dist/workflow/planning/validate-native-producer-dependency-graph.d.ts

@@ -0,0 +1,3 @@
+import type { NativeInstanceDependencyProposal } from '../../types/native-instance-dependencies.js';
+/** Selected roles must form a planning DAG. Existing external contracts do not become generated roles. */
+export declare function validateNativeProducerDependencyGraph(nodeIds: string[], proposal: NativeInstanceDependencyProposal): void;

package/dist/workflow/planning/validate-native-producer-dependency-graph.js

@@ -0,0 +1,19 @@
+/** Selected roles must form a planning DAG. Existing external contracts do not become generated roles. */
+export function validateNativeProducerDependencyGraph(nodeIds, proposal) {
+    const remaining = new Map(nodeIds.map((nodeId) => [
+        nodeId,
+        new Set(proposal.sourcesByNodeId[nodeId].sourceNodeIds.filter((id) => nodeIds.includes(id))),
+    ]));
+    while (remaining.size) {
+        const ready = [...remaining]
+            .filter(([, sources]) => sources.size === 0)
+            .map(([id]) => id);
+        if (!ready.length)
+            throw new Error('Native producer dependency cycle: ' + [...remaining.keys()].join(', '));
+        for (const id of ready)
+            remaining.delete(id);
+        for (const sources of remaining.values())
+            for (const id of ready)
+                sources.delete(id);
+    }
+}

package/dist/workflow/resolve-native-material-snapshot.d.ts

@@ -0,0 +1,3 @@
+import type { ResolveNativeMaterialSnapshotInput, NativeMaterialSnapshot } from '../types/native-material-snapshot.js';
+/** Resolve actual source contracts in dependency order; unresolved output is never replaced by an old schema. */
+export declare function resolveNativeMaterialSnapshot(input: ResolveNativeMaterialSnapshotInput): NativeMaterialSnapshot;

package/dist/workflow/resolve-native-material-snapshot.js

@@ -0,0 +1,200 @@
+import { isDeepStrictEqual } from 'node:util';
+import { inspectNativeReferenceStructure } from './inspect-native-reference-structure.js';
+import { createWorkflowNodeContracts } from './create-workflow-node-contracts.js';
+import { createNativeOutputContracts } from './create-native-output-contracts.js';
+import { validateNativeOutputContracts } from '../bindings/validate-native-output-contracts.js';
+import { validateNativeMaterialSources } from './validate-native-material-sources.js';
+import { describeNativeReferenceBindings } from './describe-native-reference-bindings.js';
+import { bindNativeMaterialContracts } from './bind-native-material-contracts.js';
+/** Resolve actual source contracts in dependency order; unresolved output is never replaced by an old schema. */
+export function resolveNativeMaterialSnapshot(input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input))
+        throw new Error('Native material snapshot input must be an object');
+    for (const field of [
+        'apiMaterials',
+        'nativeOutputs',
+        'nativeNodes',
+        'capabilities',
+        'deferredNodeIds',
+    ])
+        if (!Array.isArray(input[field]))
+            throw new Error(`Native material snapshot.${field} must be an explicit array`);
+    if (input.shouldDeferNode !== undefined &&
+        typeof input.shouldDeferNode !== 'function')
+        throw new Error('Native material snapshot.shouldDeferNode must be a function');
+    if (input.capabilities.some((capability) => typeof capability?.name !== 'string' || !capability.name.trim()))
+        throw new Error('Native material snapshot.capabilities must have non-empty names');
+    const registry = new Map(input.capabilities.map((capability) => [capability.name, capability]));
+    const ids = [
+        ...input.apiMaterials.map((source) => source.callId),
+        ...input.nativeNodes.map((node) => node.id),
+    ];
+    if (new Set(ids).size !== ids.length ||
+        ids.some((id) => typeof id !== 'string' || !id.trim()) ||
+        registry.size !== input.capabilities.length)
+        throw new Error('Native material snapshot requires unique actual node IDs and capability names');
+    if (new Set(input.deferredNodeIds).size !== input.deferredNodeIds.length ||
+        input.deferredNodeIds.some((id) => !input.nativeNodes.some((node) => node.id === id)))
+        throw new Error('Native material snapshot deferredNodeIds must name distinct actual native nodes');
+    validateNativeOutputContracts(input.nativeOutputs);
+    if (input.nativeOutputs.some((output) => ids.includes(output.nodeId)))
+        throw new Error('Native material snapshot external outputs cannot replace a current workflow node');
+    const references = new Map();
+    for (const node of input.nativeNodes) {
+        const capability = registry.get(node.capability);
+        if (!capability)
+            throw new Error(`Native material snapshot node ${node.id}: unknown capability ${node.capability}`);
+        if (capability.bindMaterialContracts &&
+            (!capability.referenceStructureSchema ||
+                !capability.parameterReferenceBindings))
+            throw new Error(`Native capability ${capability.name} requires explicit reference structure for material binding`);
+        if (capability.referenceStructureSchema)
+            references.set(node.id, inspectNativeReferenceStructure({ node, capability }).map((binding) => binding.reference));
+        else {
+            const [contract] = createWorkflowNodeContracts({
+                materials: [],
+                nativeNodes: [node],
+                capabilities: [capability],
+            });
+            references.set(node.id, [
+                ...contract.references,
+                ...Object.values(contract.inputReferences === undefined
+                    ? {}
+                    : contract.inputReferences).flat(),
+                ...(contract.rejoinsExclusiveOutputs === undefined
+                    ? []
+                    : [
+                        {
+                            source: 'exclusive-output',
+                            nodeId: contract.rejoinsExclusiveOutputs,
+                        },
+                    ]),
+            ]);
+        }
+    }
+    const remaining = [...input.nativeNodes];
+    for (const [nodeId, declared] of references)
+        for (const reference of declared) {
+            if (reference.source !== 'response' &&
+                input.apiMaterials.some((source) => source.callId === reference.nodeId))
+                throw new Error(`node ${nodeId}: expected declared native node ${reference.nodeId} for ${reference.source}; supplied source is an API`);
+            if (reference.source === 'response' &&
+                (input.nativeNodes.some((node) => node.id === reference.nodeId) ||
+                    input.nativeOutputs.some((output) => output.nodeId === reference.nodeId)))
+                throw new Error(`node ${nodeId}: expected supplied API callId ${reference.nodeId}, not a native source`);
+        }
+    const outputs = [];
+    const bindings = [];
+    const pending = [];
+    const sources = () => ({
+        apiMaterials: structuredClone(input.apiMaterials),
+        nativeOutputs: structuredClone([...input.nativeOutputs, ...outputs]),
+    });
+    function bind(definition) {
+        return bindNativeMaterialContracts(definition, sources());
+    }
+    let progressed = true;
+    while (remaining.length && progressed) {
+        progressed = false;
+        for (let index = 0; index < remaining.length;) {
+            const node = remaining[index];
+            if (input.deferredNodeIds.includes(node.id) ||
+                input.shouldDeferNode?.(node.id, structuredClone(outputs), bindings.map((binding) => binding.nodeId)) === true) {
+                pending.push({
+                    nodeId: node.id,
+                    capability: node.capability,
+                    kind: 'deferred-reference',
+                    sourceNodeIds: [
+                        ...new Set(references.get(node.id).map((reference) => reference.nodeId)),
+                    ],
+                });
+                remaining.splice(index, 1);
+                progressed = true;
+                continue;
+            }
+            const unresolved = references
+                .get(node.id)
+                .filter((reference) => reference.source === 'response'
+                ? !input.apiMaterials.some((source) => source.callId === reference.nodeId)
+                : reference.source === 'exclusive-output'
+                    ? !bindings.some((bound) => bound.nodeId === reference.nodeId)
+                    : ![...input.nativeOutputs, ...outputs].some((output) => output.nodeId === reference.nodeId));
+            if (unresolved.length) {
+                index++;
+                continue;
+            }
+            const capability = bind(registry.get(node.capability));
+            if (capability.parameterReferenceBindings)
+                describeNativeReferenceBindings({ node, capability });
+            const [contract] = createWorkflowNodeContracts({
+                materials: [],
+                nativeNodes: [node],
+                capabilities: [capability],
+            });
+            const actualReferences = [
+                ...contract.references,
+                ...Object.values(contract.inputReferences === undefined
+                    ? {}
+                    : contract.inputReferences).flat(),
+            ];
+            validateNativeMaterialSources(capability, actualReferences, sources());
+            outputs.push(...createNativeOutputContracts({
+                nativeNodes: [node],
+                capabilities: [capability],
+            }));
+            bindings.push({ nodeId: node.id, capability });
+            remaining.splice(index, 1);
+            progressed = true;
+        }
+    }
+    for (const node of remaining)
+        pending.push({
+            nodeId: node.id,
+            capability: node.capability,
+            kind: 'unavailable-source',
+            sourceNodeIds: [
+                ...new Set(references
+                    .get(node.id)
+                    .filter((reference) => reference.source === 'response'
+                    ? !input.apiMaterials.some((source) => source.callId === reference.nodeId)
+                    : reference.source === 'exclusive-output'
+                        ? !bindings.some((bound) => bound.nodeId === reference.nodeId)
+                        : ![...input.nativeOutputs, ...outputs].some((output) => output.nodeId === reference.nodeId))
+                    .map((reference) => reference.nodeId)),
+            ],
+        });
+    if (pending.length)
+        return { status: 'pending', bindings, outputs, pending };
+    const capabilities = [
+        ...new Set(input.nativeNodes.map((node) => node.capability)),
+    ].map((name) => bind(registry.get(name)));
+    const completedContracts = createWorkflowNodeContracts({
+        materials: [],
+        nativeNodes: input.nativeNodes,
+        capabilities,
+    });
+    for (const node of input.nativeNodes) {
+        const capability = capabilities.find((candidate) => candidate.name === node.capability);
+        const contract = completedContracts.find((candidate) => candidate.id === node.id);
+        validateNativeMaterialSources(capability, [
+            ...contract.references,
+            ...Object.values(contract.inputReferences === undefined
+                ? {}
+                : contract.inputReferences).flat(),
+        ], sources());
+    }
+    const completed = createNativeOutputContracts({
+        nativeNodes: input.nativeNodes,
+        capabilities,
+    });
+    for (const output of outputs)
+        if (!isDeepStrictEqual(output, completed.find((item) => item.nodeId === output.nodeId)))
+            throw new Error(`Native material binding ${output.nodeId} changes its output when unrelated contracts become available`);
+    return {
+        status: 'ready',
+        bindings,
+        outputs: completed,
+        pending,
+        capabilities,
+    };
+}

package/dist/workflow/resolve-native-structure-parameters.d.ts

@@ -0,0 +1,4 @@
+import type { JsonValueObject } from '../types/api-arguments.js';
+import type { PlannedNativeNode, WorkflowCapability } from '../types/workflow-plan.js';
+/** {} is a declared binding source, never a fabricated complete parameter value. */
+export declare function resolveNativeStructureParameters(planned: PlannedNativeNode, capability: WorkflowCapability): JsonValueObject;

package/dist/workflow/resolve-native-structure-parameters.js

@@ -0,0 +1,56 @@
+import { parseNativeNodeParameters } from './parse-native-node-parameters.js';
+import { nativeRuntimeParametersSchema, nativeParameterValuesSchema, } from '../schemas/native-runtime-input-slot-schema.js';
+import { hasPointer, pointerTokens, pointerValue, } from '../bindings/json-pointer.js';
+import { createNativeRuntimeParametersSchema } from '../schemas/create-native-runtime-parameters-schema.js';
+import { optionalRequestProperties } from '../schemas/operation-plan-schema.js';
+import { createOasValueValidator } from '../openapi/common/create-oas-value-validator.js';
+import { projectLiteralInputSchema } from '../schemas/project-literal-input-schema.js';
+/** {} is a declared binding source, never a fabricated complete parameter value. */
+export function resolveNativeStructureParameters(planned, capability) {
+    if (planned.runtimeParameters === undefined)
+        return parseNativeNodeParameters(planned, capability);
+    if (capability.supportsRuntimeParameters !== true)
+        throw new Error(`node ${planned.id}: capability ${capability.name} does not declare runtime-independent parameter structure`);
+    const parsed = nativeRuntimeParametersSchema.safeParse(planned.runtimeParameters);
+    if (!parsed.success)
+        throw new Error(`node ${planned.id}: runtime-independent parameters require true or explicit pointer selection`, { cause: parsed.error });
+    const ownership = parsed.data;
+    if (ownership !== true) {
+        nativeParameterValuesSchema.parse(planned.parameters);
+        const seen = [];
+        for (const pointer of ownership.pointers) {
+            const tokens = pointerTokens(pointer);
+            for (let length = 1; length < tokens.length; length++) {
+                const parent = '/' +
+                    tokens
+                        .slice(0, length)
+                        .map((token) => token.replaceAll('~', '~0').replaceAll('/', '~1'))
+                        .join('/');
+                if (!hasPointer(planned.parameters, parent))
+                    continue;
+                const value = pointerValue(planned.parameters, parent);
+                if (value === null || typeof value !== 'object')
+                    throw new Error(`node ${planned.id}: runtime parameter ${pointer} traverses literal non-container ${parent}`);
+            }
+            if (seen.some((other) => other === pointer ||
+                other.startsWith(pointer + '/') ||
+                pointer.startsWith(other + '/')))
+                throw new Error(`node ${planned.id}: runtime parameter pointers overlap at ${pointer}`);
+            if (hasPointer(planned.parameters, pointer))
+                throw new Error(`node ${planned.id}: runtime parameter ${pointer} also contains a literal value`);
+            seen.push(pointer);
+        }
+        const literalSchema = optionalRequestProperties(createNativeRuntimeParametersSchema(capability));
+        const schema = projectLiteralInputSchema(literalSchema, ownership.pointers.map(pointerTokens), `native partial parameters ${planned.id}`).schema;
+        const checked = createOasValueValidator(schema, 'draft-2020-12', `native partial parameters ${planned.id}`).validate(planned.parameters);
+        if (!checked.valid)
+            throw new Error(`node ${planned.id}: partial parameter literals violate their schema: ${checked.errors.map((error) => error.message).join('; ')}`);
+        return planned.parameters;
+    }
+    if (!planned.parameters ||
+        typeof planned.parameters !== 'object' ||
+        Array.isArray(planned.parameters) ||
+        Object.keys(planned.parameters).length !== 0)
+        throw new Error(`node ${planned.id}: runtime parameters must not also contain literal parameter values`);
+    return planned.parameters;
+}

package/dist/workflow/validate-exclusive-output-rejoin.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowPlanNodeContract, WorkflowRouteState } from '../types/workflow-plan.js';
+/** Each input represents a distinct alternative, with the same enclosing route set. */
+export declare function validateExclusiveOutputRejoin(current: WorkflowPlanNodeContract, source: WorkflowPlanNodeContract | undefined, inputs: WorkflowRouteState[][]): void;

package/dist/workflow/validate-exclusive-output-rejoin.js

@@ -0,0 +1,26 @@
+/** Each input represents a distinct alternative, with the same enclosing route set. */
+export function validateExclusiveOutputRejoin(current, source, inputs) {
+    if (!source?.exclusiveOutputPorts ||
+        current.waitsForAllInputs ||
+        inputs.length !== source.outputs.length)
+        throw new Error(`node ${current.id}: rejoin requires a declared exclusive producer and every output alternative`);
+    const ports = new Set();
+    let enclosing;
+    for (const routes of inputs) {
+        const alternatives = new Set(routes.map((route) => route.branches.get(source.id)));
+        const port = alternatives.values().next().value;
+        if (alternatives.size !== 1 ||
+            port === undefined ||
+            !source.outputs.includes(port) ||
+            ports.has(port))
+            throw new Error(`node ${current.id}: rejoin inputs must cover distinct outputs of ${source.id}`);
+        ports.add(port);
+        const contexts = routes
+            .map((route) => JSON.stringify([...route.branches].filter(([id]) => id !== source.id).sort()))
+            .sort();
+        if (enclosing !== undefined &&
+            JSON.stringify(contexts) !== JSON.stringify(enclosing))
+            throw new Error(`node ${current.id}: rejoin alternatives have unmatched enclosing routes`);
+        enclosing = contexts;
+    }
+}

package/dist/workflow/validate-native-api-response-references.d.ts

@@ -0,0 +1,2 @@
+import type { ValidateNativeApiResponseReferencesInput } from '../types/workflow-capability-planning.js';
+export declare function validateNativeApiResponseReferences({ nativeNodes, capabilities, apiCallIds, }: ValidateNativeApiResponseReferencesInput): void;

package/dist/workflow/validate-native-api-response-references.js

@@ -0,0 +1,26 @@
+import { assertApiCallIdentities } from './assert-api-call-identities.js';
+import { resolveNativeStructureParameters } from './resolve-native-structure-parameters.js';
+export function validateNativeApiResponseReferences({ nativeNodes, capabilities, apiCallIds, }) {
+    assertApiCallIdentities(apiCallIds);
+    const registry = new Map(capabilities.map((capability) => [capability.name, capability]));
+    if (registry.size !== capabilities.length)
+        throw new Error('planning.capabilities contains duplicate names');
+    const available = new Set(apiCallIds);
+    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 references = [
+            ...capability.responseReferences(parameters),
+            ...Object.values(capability.inputReferences
+                ? capability.inputReferences(parameters)
+                : {})
+                .flat()
+                .filter((reference) => reference.source === 'response'),
+        ];
+        for (const [index, reference] of references.entries())
+            if (!available.has(reference.nodeId))
+                throw new Error(`node ${native.id}: responseReferences[${index}].nodeId ${JSON.stringify(reference.nodeId)} is not a supplied API callId; available ${JSON.stringify(apiCallIds)}`);
+    }
+}

package/dist/workflow/validate-native-material-sources.d.ts

@@ -0,0 +1,4 @@
+import type { WorkflowCapability, WorkflowValueReference } from '../types/workflow-plan.js';
+import type { WorkflowNativeMaterialSources } from '../types/native-material-snapshot.js';
+/** Captured contracts must describe the actual referenced producer, not another material revision. */
+export declare function validateNativeMaterialSources(capability: WorkflowCapability, references: WorkflowValueReference[], sources: WorkflowNativeMaterialSources): void;

package/dist/workflow/validate-native-material-sources.js

@@ -0,0 +1,26 @@
+import { isDeepStrictEqual } from 'node:util';
+/** Captured contracts must describe the actual referenced producer, not another material revision. */
+export function validateNativeMaterialSources(capability, references, sources) {
+    if (capability.bindMaterialContracts && !capability.materialSources)
+        throw new Error(`Native capability ${capability.name}.bindMaterialContracts must declare its actual materialSources`);
+    if (!capability.materialSources)
+        return;
+    for (const reference of references) {
+        if (reference.source === 'response') {
+            const actual = sources.apiMaterials.find((source) => source.callId === reference.nodeId);
+            const captured = capability.materialSources.apiMaterials.find((source) => source.callId === reference.nodeId);
+            if (!actual ||
+                !captured ||
+                !isDeepStrictEqual(actual.operation, captured.operation))
+                throw new Error(`Native capability ${capability.name}: API source ${reference.nodeId} does not match the current material contract`);
+        }
+        else {
+            const actual = sources.nativeOutputs.find((source) => source.nodeId === reference.nodeId);
+            const captured = capability.materialSources.nativeOutputs.find((source) => source.nodeId === reference.nodeId);
+            if (!actual ||
+                !captured ||
+                !isDeepStrictEqual(actual.schema, captured.schema))
+                throw new Error(`Native capability ${capability.name}: native source ${reference.nodeId} does not match the current material contract`);
+        }
+    }
+}

package/dist/workflow/validate-native-reference-binding-locations.d.ts

@@ -0,0 +1,4 @@
+import type { JsonValueObject } from '../types/api-arguments.js';
+import type { WorkflowNativeReferenceBinding } from '../types/native-parameter-reference.js';
+/** Physical location validation is independent of whether the producer contract is ready. */
+export declare function validateNativeReferenceBindingLocations(nodeId: string, parameters: JsonValueObject, bindings: WorkflowNativeReferenceBinding[]): void;

package/dist/workflow/validate-native-reference-binding-locations.js

@@ -0,0 +1,35 @@
+import { nativeReferenceBindingSchema } from '../schemas/native-reference-binding-schema.js';
+import { pointerTokens, pointerValue } from '../bindings/json-pointer.js';
+/** Physical location validation is independent of whether the producer contract is ready. */
+export function validateNativeReferenceBindingLocations(nodeId, parameters, bindings) {
+    nativeReferenceBindingSchema.array().parse(bindings);
+    const signatures = new Set();
+    for (const binding of bindings) {
+        if (!pointerTokens(binding.nodeIdPointer).length ||
+            pointerValue(parameters, binding.nodeIdPointer) !==
+                binding.reference.nodeId)
+            throw new Error(`Native reference binding for ${nodeId} must locate its actual node ID value`);
+        if ('pointer' in binding.reference) {
+            try {
+                pointerTokens(binding.reference.pointer);
+            }
+            catch (cause) {
+                throw new Error(`node ${nodeId}: invalid ${binding.reference.source} JSON pointer ${binding.reference.pointer} in reference binding ${binding.nodeIdPointer}`, { cause });
+            }
+        }
+        if (binding.valuePointer !== undefined &&
+            (!pointerTokens(binding.valuePointer).length ||
+                !('pointer' in binding.reference) ||
+                pointerValue(parameters, binding.valuePointer) !==
+                    binding.reference.pointer))
+            throw new Error(`Native reference binding for ${nodeId} must locate its actual declared value pointer`);
+        const signature = JSON.stringify([
+            binding.nodeIdPointer,
+            binding.valuePointer,
+            binding.reference,
+        ]);
+        if (signatures.has(signature))
+            throw new Error(`Native reference bindings for ${nodeId} repeat an identical location`);
+        signatures.add(signature);
+    }
+}

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

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

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

@@ -0,0 +1,100 @@
+import { inspectApiArgumentRequirements } from '../arguments/clarification/inspect-api-argument-requirements.js';
+import { validateApiBindingAssignments } from '../bindings/validate-api-binding-assignments.js';
+import { validateApiBindingGaps } from '../bindings/validate-api-binding-gaps.js';
+import { createReviewableNodeContracts } from './create-reviewable-node-contracts.js';
+import { validateWorkflowTopology } from './validate-workflow-topology.js';
+import { createNativeOutputContracts } from './create-native-output-contracts.js';
+export function validateReviewableWorkflowGraphPlan(input) {
+    const { plan, materials } = input;
+    const gaps = new Map(plan.gaps.map((gap) => [gap.id, gap]));
+    if (gaps.size !== plan.gaps.length ||
+        plan.gaps.some((gap) => !gap.id.trim() ||
+            !gap.description.trim() ||
+            !['api-selection', 'api-bindings', 'workflow-graph'].includes(gap.stage)))
+        throw new Error('review gaps require unique IDs, stages and descriptions');
+    const ids = materials.map((item) => item.status === 'ready' ? item.arguments.callId : item.callId);
+    if (new Set(ids).size !== ids.length || ids.some((id) => !id.trim()))
+        throw new Error('review materials require unique non-empty callIds');
+    const blocked = new Map(plan.blockedCalls.map((item) => [item.callId, item.gapIds]));
+    if (blocked.size !== plan.blockedCalls.length)
+        throw new Error('review blockedCalls contains duplicate callIds');
+    for (const [callId, gapIds] of blocked) {
+        if (!ids.includes(callId) ||
+            !gapIds.length ||
+            new Set(gapIds).size !== gapIds.length ||
+            gapIds.some((id) => !gaps.has(id)))
+            throw new Error(`review blocked call ${callId} requires declared gap IDs`);
+    }
+    for (const item of materials) {
+        if (item.status === 'blocked') {
+            if (!item.gapIds.length ||
+                item.gapIds.some((id) => !blocked.get(item.callId)?.includes(id)))
+                throw new Error(`review plan omitted blocked requirement for ${item.callId}`);
+        }
+        else {
+            const args = item.arguments;
+            const result = inspectApiArgumentRequirements({
+                operation: item.operation,
+                callId: args.callId,
+                requestedInputs: args.requestedInputs,
+                values: args.values,
+                bindings: args.bindings,
+                requestMediaType: args.requestMediaType,
+            });
+            if (args.unresolvedInputs.length || result.status !== 'ready')
+                throw new Error(`review ready material ${args.callId} has unresolved request inputs`);
+        }
+    }
+    if (materials.length)
+        validateApiBindingAssignments({
+            nativeOutputs: createNativeOutputContracts({
+                nativeNodes: plan.nativeNodes,
+                capabilities: input.capabilities,
+            }),
+            materials: materials.map((item) => ({
+                callId: item.status === 'ready' ? item.arguments.callId : item.callId,
+                operation: item.operation,
+                requestMediaType: item.status === 'ready'
+                    ? item.arguments.requestMediaType
+                    : item.requestMediaType,
+            })),
+            calls: materials.map((item) => ({
+                callId: item.status === 'ready' ? item.arguments.callId : item.callId,
+                bindings: item.status === 'ready' ? item.arguments.bindings : item.bindings,
+            })),
+        });
+    for (const gap of plan.gaps) {
+        if (gap.stage !== 'api-bindings')
+            continue;
+        if (typeof gap.callId !== 'string' ||
+            typeof gap.targetPointer !== 'string' ||
+            !blocked.get(gap.callId)?.includes(gap.id))
+            throw new Error('api-bindings review gap requires its declared blocked callId and request targetPointer');
+        validateApiBindingGaps({
+            materials: materials.map((item) => ({
+                callId: item.status === 'ready' ? item.arguments.callId : item.callId,
+                operation: item.operation,
+                requestMediaType: item.status === 'ready'
+                    ? item.arguments.requestMediaType
+                    : item.requestMediaType,
+            })),
+            plan: {
+                calls: [],
+                gaps: [
+                    {
+                        callId: gap.callId,
+                        targetPointer: gap.targetPointer,
+                        description: gap.description,
+                    },
+                ],
+            },
+        });
+    }
+    const apiIds = new Set(ids.filter((id) => !blocked.has(id)));
+    validateWorkflowTopology({
+        contracts: createReviewableNodeContracts(input),
+        apiIds,
+        edges: plan.edges,
+        starts: plan.starts,
+    });
+}

package/dist/workflow/validate-workflow-edges.d.ts

@@ -0,0 +1,2 @@
+import type { ValidateWorkflowEdgesInput } from '../types/workflow-plan.js';
+export declare function validateWorkflowEdges({ contracts, edges, }: ValidateWorkflowEdgesInput): void;

package/dist/workflow/validate-workflow-edges.js

@@ -0,0 +1,19 @@
+export function validateWorkflowEdges({ contracts, edges, }) {
+    const nodes = new Map(contracts.map((item) => [item.id, item]));
+    if (nodes.size !== contracts.length ||
+        contracts.some((item) => !item.id.trim()))
+        throw new Error('plan node IDs must be unique and non-empty');
+    const edgeKeys = new Set();
+    for (const edge of edges) {
+        const from = nodes.get(edge.from);
+        const to = nodes.get(edge.to);
+        if (!from || !to)
+            throw new Error('plan edge references a missing node');
+        if (!from.outputs.includes(edge.output) || !to.inputs.includes(edge.input))
+            throw new Error(`plan edge ${edge.from} -> ${edge.to} has an unknown port`);
+        const key = JSON.stringify([edge.from, edge.output, edge.to, edge.input]);
+        if (edgeKeys.has(key))
+            throw new Error('plan has duplicate edges');
+        edgeKeys.add(key);
+    }
+}

package/dist/workflow/validate-workflow-graph-plan.d.ts

@@ -0,0 +1,3 @@
+import type { ValidateWorkflowGraphPlanInput } from '../types/workflow-plan.js';
+/** Reject invalid graph proposals; never repair or infer edges. */
+export declare function validateWorkflowGraphPlan({ plan, materials, capabilities, unresolvedNodes, }: ValidateWorkflowGraphPlanInput): void;

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

@@ -0,0 +1,53 @@
+import { validateApiBindingPlan } from '../bindings/validate-api-binding-plan.js';
+import { createWorkflowNodeContracts } from './create-workflow-node-contracts.js';
+import { validateWorkflowTopology } from './validate-workflow-topology.js';
+import { resolveNativeMaterialSnapshot } from './resolve-native-material-snapshot.js';
+import { NativeMaterialResolutionError } from './native-material-resolution-error.js';
+/** Reject invalid graph proposals; never repair or infer edges. */
+export function validateWorkflowGraphPlan({ plan, materials, capabilities, unresolvedNodes, }) {
+    const snapshot = resolveNativeMaterialSnapshot({
+        apiMaterials: materials.map((material) => ({
+            callId: material.arguments.callId,
+            operation: material.operation,
+            requestMediaType: material.arguments.requestMediaType,
+        })),
+        nativeOutputs: [],
+        deferredNodeIds: [],
+        nativeNodes: plan.nativeNodes,
+        capabilities,
+    });
+    if (snapshot.status !== 'ready')
+        throw new NativeMaterialResolutionError(snapshot.pending);
+    const nativeOutputs = snapshot.outputs;
+    if (materials.length)
+        validateApiBindingPlan({
+            nativeOutputs,
+            materials: materials.map((item) => ({
+                callId: item.arguments.callId,
+                operation: item.operation,
+                requestMediaType: item.arguments.requestMediaType,
+            })),
+            plan: {
+                calls: materials.map((item) => ({
+                    callId: item.arguments.callId,
+                    bindings: item.arguments.bindings,
+                })),
+                gaps: [],
+            },
+        });
+    const apiIds = new Set(materials.map((item) => item.arguments.callId));
+    if (apiIds.size !== materials.length)
+        throw new Error('materials requires unique API callIds');
+    const contracts = createWorkflowNodeContracts({
+        materials,
+        nativeNodes: plan.nativeNodes,
+        capabilities: snapshot.capabilities,
+        unresolvedNodes,
+    });
+    validateWorkflowTopology({
+        contracts,
+        apiIds,
+        edges: plan.edges,
+        starts: plan.starts,
+    });
+}

package/dist/workflow/validate-workflow-topology.d.ts

@@ -0,0 +1,2 @@
+import type { ValidateWorkflowTopologyInput } from '../types/workflow-plan.js';
+export declare function validateWorkflowTopology({ contracts, apiIds, edges, starts, }: ValidateWorkflowTopologyInput): void;