@openapi-flow/core 0.1.0 → 0.2.0

package/dist/types/security.d.ts

@@ -0,0 +1,17 @@
+import type { ApiSecurityRequirement } from './api-operation.js';
+import type { JsonObject } from './openapi.js';
+export interface ResolveOpenApiSecurityInput {
+    operationRef: string;
+    security: ApiSecurityRequirement[];
+    securitySchemes: JsonObject;
+    requirementIndex?: number;
+}
+export interface ResolvedSecurityScheme {
+    name: string;
+    scopes: string[];
+    definition: JsonObject;
+}
+export interface ResolvedOpenApiSecurity {
+    requirementIndex: number;
+    schemes: ResolvedSecurityScheme[];
+}

package/dist/types/security.js

@@ -0,0 +1 @@
+export {};

package/dist/types/workflow-capability-planning.d.ts

@@ -0,0 +1,10 @@
+import type { WorkflowCapability, PlannedNativeNode } from './workflow-plan.js';
+export interface WorkflowCapabilityPlanningContext {
+    apiCallIds: string[];
+}
+export interface WorkflowCapabilityPlanningInput extends WorkflowCapabilityPlanningContext {
+    capabilities: WorkflowCapability[];
+}
+export interface ValidateNativeApiResponseReferencesInput extends WorkflowCapabilityPlanningInput {
+    nativeNodes: PlannedNativeNode[];
+}

package/dist/types/workflow-capability-planning.js

@@ -0,0 +1 @@
+export {};

package/dist/types/workflow-plan.d.ts

@@ -0,0 +1,104 @@
+import type { z } from 'zod';
+import type { ApiOperationContract } from './api-operation.js';
+import type { ApiCallArguments, JsonValueObject } from './api-arguments.js';
+import type { BindingSchema } from './api-bindings.js';
+import type { WorkflowCapabilityPlanningContext } from './workflow-capability-planning.js';
+export interface WorkflowApiMaterial {
+    operation: ApiOperationContract;
+    arguments: ApiCallArguments;
+}
+export interface WorkflowResponseReference {
+    source: 'response';
+    nodeId: string;
+    /** RFC 6901 pointer into the API response body, not n8n's envelope. */
+    pointer: string;
+}
+export interface WorkflowNodeOutputReference {
+    source: 'node-output';
+    nodeId: string;
+    /** RFC 6901 pointer into the declared native JSON item. */
+    pointer: string;
+}
+export type WorkflowValueReference = WorkflowResponseReference | WorkflowNodeOutputReference;
+export interface WorkflowCapability {
+    name: string;
+    description: string;
+    parametersSchema: z.ZodType<JsonValueObject>;
+    /** Optional generation contract specialized by the capability, never by field-name guessing. */
+    createPlanningParametersSchema?: (context: WorkflowCapabilityPlanningContext) => z.ZodType<JsonValueObject>;
+    inputPorts: (parameters: JsonValueObject) => string[];
+    outputPorts: (parameters: JsonValueObject) => string[];
+    responseReferences: (parameters: JsonValueObject) => WorkflowResponseReference[];
+    /** Native provenance required by this implementation, never inferred from values. */
+    nodeOutputReferences?: (parameters: JsonValueObject) => WorkflowNodeOutputReference[];
+    /** Dependencies required on a specific incoming port, before a join combines routes. */
+    inputReferences?: (parameters: JsonValueObject) => Record<string, WorkflowValueReference[]>;
+    waitsForAllInputs: boolean;
+    exclusiveOutputPorts: boolean;
+    /** Rejoin alternatives from this declared exclusive producer, not independent branches. */
+    rejoinsExclusiveOutputs?: (parameters: JsonValueObject) => string;
+    /** Explicit native JSON output contract; absent means no bindable output. */
+    outputSchema?: (parameters: JsonValueObject) => BindingSchema;
+}
+export interface PlannedNativeNode {
+    id: string;
+    capability: string;
+    parameters: JsonValueObject;
+}
+export interface WorkflowPlanEdge {
+    from: string;
+    output: string;
+    to: string;
+    input: string;
+}
+export interface WorkflowPlanGap {
+    description: string;
+}
+export interface WorkflowGraphProposal {
+    nativeNodes: PlannedNativeNode[];
+    edges: WorkflowPlanEdge[];
+    gaps: WorkflowPlanGap[];
+}
+export interface WorkflowGraphPlan extends WorkflowGraphProposal {
+    starts: string[];
+}
+export interface CreateWorkflowGraphPlanInput {
+    proposal: WorkflowGraphProposal;
+    materials: WorkflowApiMaterial[];
+    capabilities: WorkflowCapability[];
+}
+export interface ValidateWorkflowGraphPlanInput {
+    plan: WorkflowGraphPlan;
+    materials: WorkflowApiMaterial[];
+    capabilities: WorkflowCapability[];
+}
+export interface WorkflowRouteState {
+    branches: Map<string, string>;
+    completed: Set<string>;
+}
+export interface WorkflowPlanNodeContract {
+    id: string;
+    inputs: string[];
+    outputs: string[];
+    references: WorkflowValueReference[];
+    inputReferences?: Record<string, WorkflowValueReference[]>;
+    dependencyNodeIds: string[];
+    waitsForAllInputs: boolean;
+    exclusiveOutputPorts: boolean;
+    rejoinsExclusiveOutputs?: string;
+}
+export interface WorkflowNodeContractsInput {
+    materials: WorkflowApiMaterial[];
+    nativeNodes: PlannedNativeNode[];
+    capabilities: WorkflowCapability[];
+}
+export interface ValidateWorkflowTopologyInput {
+    contracts: WorkflowPlanNodeContract[];
+    apiIds: Set<string>;
+    edges: WorkflowPlanEdge[];
+    starts: string[];
+}
+export interface ValidateWorkflowEdgesInput {
+    contracts: WorkflowPlanNodeContract[];
+    edges: WorkflowPlanEdge[];
+}

package/dist/types/workflow-plan.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/is-object.d.ts

@@ -0,0 +1,2 @@
+import type { JsonObject } from '../types/openapi.js';
+export declare function isObject(value: unknown): value is JsonObject;

package/dist/utils/is-object.js

@@ -0,0 +1,3 @@
+export function isObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

package/dist/utils/json-values-equal.d.ts

@@ -0,0 +1,2 @@
+/** Compare JSON values without normalizing their types or object key order. */
+export declare function jsonValuesEqual(left: unknown, right: unknown): boolean;

package/dist/utils/json-values-equal.js

@@ -0,0 +1,16 @@
+/** Compare JSON values without normalizing their types or object key order. */
+export function jsonValuesEqual(left, right) {
+    if (left === right)
+        return true;
+    if (Array.isArray(left) || Array.isArray(right))
+        return (Array.isArray(left) &&
+            Array.isArray(right) &&
+            left.length === right.length &&
+            left.every((value, index) => jsonValuesEqual(value, right[index])));
+    if (!left || !right || typeof left !== 'object' || typeof right !== 'object')
+        return false;
+    const keys = Object.keys(left);
+    return (keys.length === Object.keys(right).length &&
+        keys.every((key) => Object.hasOwn(right, key) &&
+            jsonValuesEqual(Reflect.get(left, key), Reflect.get(right, key))));
+}

package/dist/workflow/assert-api-call-identities.d.ts

@@ -0,0 +1 @@
+export declare function assertApiCallIdentities(apiCallIds: string[]): void;

package/dist/workflow/assert-api-call-identities.js

@@ -0,0 +1,6 @@
+export function assertApiCallIdentities(apiCallIds) {
+    if (!Array.isArray(apiCallIds) ||
+        apiCallIds.some((id) => typeof id !== 'string' || !id.trim()) ||
+        new Set(apiCallIds).size !== apiCallIds.length)
+        throw new Error('planning.apiCallIds must contain unique non-empty call IDs');
+}

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 { parseNativeNodeParameters } from './parse-native-node-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 = parseNativeNodeParameters(planned, capability);
+        return capability.outputSchema
+            ? [{ nodeId: planned.id, schema: capability.outputSchema(parameters) }]
+            : [];
+    });
+    validateNativeOutputContracts(outputs);
+    return outputs;
+}

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,36 @@
+import { createWorkflowNodeContracts } from './create-workflow-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,
+        });
+    for (const gap of plan.gaps)
+        contracts.push({
+            id: gap.id,
+            inputs: ['main'],
+            outputs: ['main'],
+            references: [],
+            dependencyNodeIds: [],
+            waitsForAllInputs: false,
+            exclusiveOutputPorts: false,
+        });
+    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-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, }: WorkflowNodeContractsInput): WorkflowPlanNodeContract[];

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

@@ -0,0 +1,50 @@
+import { parseNativeNodeParameters } from './parse-native-node-parameters.js';
+export function createWorkflowNodeContracts({ materials, 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 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 = parseNativeNodeParameters(native, capability);
+        contracts.push({
+            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),
+                }
+                : {}),
+        });
+    }
+    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/parse-native-node-parameters.d.ts

@@ -0,0 +1,3 @@
+import type { JsonValueObject } from '../types/api-arguments.js';
+import type { PlannedNativeNode, WorkflowCapability } from '../types/workflow-plan.js';
+export declare function parseNativeNodeParameters(planned: PlannedNativeNode, capability: WorkflowCapability): JsonValueObject;

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

@@ -0,0 +1,7 @@
+import { jsonValuesEqual } from '../utils/json-values-equal.js';
+export function parseNativeNodeParameters(planned, capability) {
+    const parameters = capability.parametersSchema.parse(planned.parameters);
+    if (!jsonValuesEqual(parameters, planned.parameters))
+        throw new Error(`node ${planned.id}: parameter schema must validate without defaults, coercion or transformation`);
+    return 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 { parseNativeNodeParameters } from './parse-native-node-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 = parseNativeNodeParameters(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-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,98 @@
+import { validateApiArguments } from '../arguments/validate-api-arguments.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 = validateApiArguments({
+                operation: item.operation,
+                values: args.values,
+                bindings: args.bindings,
+                requestMediaType: args.requestMediaType,
+            });
+            if (args.unresolvedInputs.length || !result.valid)
+                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, }: ValidateWorkflowGraphPlanInput): void;