@openapi-flow/core 0.1.0 → 0.3.0

package/dist/arguments/sources/verify-api-input-literal-source.d.ts

@@ -0,0 +1,3 @@
+import type { VerifyApiInputLiteralSourceInput, ReadApiInputLiteralSourceResult } from '../../types/api-input-literal-source.js';
+/** A source token must be complete and equal the proposed JSON value, without conversion. */
+export declare function verifyApiInputLiteralSource(input: VerifyApiInputLiteralSourceInput): ReadApiInputLiteralSourceResult;

package/dist/arguments/sources/verify-api-input-literal-source.js

@@ -0,0 +1,9 @@
+import { readApiInputLiteralSource } from './read-api-input-literal-source.js';
+import { jsonValuesEqual } from '../../utils/json-values-equal.js';
+/** A source token must be complete and equal the proposed JSON value, without conversion. */
+export function verifyApiInputLiteralSource(input) {
+    const parsed = readApiInputLiteralSource(input);
+    if (!jsonValuesEqual(parsed.value, input.value))
+        throw new Error(`${input.label} does not equal its exact user source without conversion`);
+    return parsed;
+}

package/dist/arguments/validate-api-arguments.d.ts

@@ -0,0 +1,2 @@
+import type { ApiArgumentValidation, ValidateApiArgumentsInput } from '../types/api-arguments.js';
+export declare function validateApiArguments({ operation, values, bindings, requestMediaType, }: ValidateApiArgumentsInput): ApiArgumentValidation;

package/dist/arguments/validate-api-arguments.js

@@ -0,0 +1,140 @@
+import { hasPointer, pointerTokens, pointerValue, } from '../bindings/json-pointer.js';
+import { checkOasValue } from '../openapi/common/check-oas-value.js';
+import { object } from '../openapi/common/parse-spec-utils.js';
+import { optionalRequestProperties } from '../schemas/operation-plan-schema.js';
+import { projectLiteralInputSchema } from '../schemas/project-literal-input-schema.js';
+import { bodyMediaSchema, parameterSchema } from './request-contract.js';
+function requiredPointers(schema, value, pointer, missing, bound) {
+    if (bound.includes(pointer) || typeof schema === 'boolean')
+        return;
+    if (Array.isArray(schema.allOf))
+        for (const item of schema.allOf)
+            requiredPointers(object(item, `${pointer}.allOf`), value, pointer, missing, bound);
+    if (Array.isArray(schema.required))
+        for (const name of schema.required) {
+            const child = `${pointer}/${String(name).replaceAll('~', '~0').replaceAll('/', '~1')}`;
+            if ((value === null ||
+                typeof value !== 'object' ||
+                !Object.hasOwn(value, String(name))) &&
+                !bound.includes(child))
+                if (!bound.some((target) => target.startsWith(child + '/')))
+                    missing.push(child);
+        }
+    if ((value === undefined ||
+        (value !== null && typeof value === 'object' && !Array.isArray(value))) &&
+        schema.properties !== undefined) {
+        for (const [name, child] of Object.entries(object(schema.properties, `${pointer}.properties`))) {
+            const childPointer = `${pointer}/${name.replaceAll('~', '~0').replaceAll('/', '~1')}`;
+            const suppliedChild = value !== undefined && Object.hasOwn(value, name);
+            if (!suppliedChild &&
+                !bound.some((target) => target.startsWith(childPointer + '/')))
+                continue;
+            requiredPointers(typeof child === 'boolean'
+                ? child
+                : object(child, `${pointer}.${name}`), suppliedChild ? Reflect.get(value, name) : undefined, childPointer, missing, bound);
+        }
+    }
+    if (Array.isArray(value) &&
+        schema.items !== undefined &&
+        !Array.isArray(schema.items))
+        for (const [index, item] of value.entries()) {
+            requiredPointers(typeof schema.items === 'boolean'
+                ? schema.items
+                : object(schema.items, `${pointer}.items`), item, `${pointer}/${index}`, missing, bound);
+        }
+}
+export function validateApiArguments({ operation, values, bindings, requestMediaType, }) {
+    if (!Array.isArray(bindings))
+        throw new Error('arguments.bindings must be an array');
+    const supplied = object(values, 'arguments.values');
+    const dialect = operation.openapiVersion.startsWith('3.0.')
+        ? 'openapi-3.0'
+        : 'draft-2020-12';
+    const allowed = new Set(operation.effective.parameters.map((parameter) => parameter.in));
+    if (operation.operation.requestBody !== undefined)
+        allowed.add('body');
+    for (const group of Object.keys(supplied))
+        if (!allowed.has(group))
+            throw new Error(`arguments.values.${group} is not declared by ${operation.key.operationRef}`);
+    const targets = [];
+    for (const binding of bindings) {
+        if (binding.kind !== 'node-output' ||
+            typeof binding.sourceNodeId !== 'string' ||
+            !binding.sourceNodeId.trim())
+            throw new Error('bindings require kind and non-empty sourceNodeId');
+        const tokens = pointerTokens(binding.targetPointer);
+        pointerTokens(binding.sourcePointer);
+        if (tokens.length === 0)
+            throw new Error('bindings.targetPointer must identify a request field');
+        if (targets.some((target) => target === binding.targetPointer ||
+            target.startsWith(binding.targetPointer + '/') ||
+            binding.targetPointer.startsWith(target + '/')))
+            throw new Error(`bindings overlap at ${binding.targetPointer}`);
+        if (hasPointer(values, binding.targetPointer))
+            throw new Error(`arguments supply both a literal and binding at ${binding.targetPointer}`);
+        if (tokens[0] !== 'body' &&
+            !operation.effective.parameters.some((parameter) => parameter.in === tokens[0] && parameter.name === tokens[1]))
+            throw new Error(`binding ${binding.targetPointer} is not declared by ${operation.key.operationRef}`);
+        if (tokens[0] === 'body' && operation.operation.requestBody === undefined)
+            throw new Error(`${operation.key.operationRef} has no body for ${binding.targetPointer}`);
+        targets.push(binding.targetPointer);
+    }
+    const missing = [];
+    for (const raw of operation.effective.parameters) {
+        const parameter = object(raw, `${operation.key.operationRef}.parameters`);
+        if (parameter.in === 'header' &&
+            ['accept', 'content-type', 'authorization'].includes(String(parameter.name).toLowerCase()))
+            continue;
+        const location = String(parameter.in);
+        const name = String(parameter.name);
+        const group = supplied[location];
+        if (group !== undefined) {
+            for (const key of Object.keys(object(group, `arguments.values.${location}`)))
+                if (!operation.effective.parameters.some((item) => item.in === location && item.name === key))
+                    throw new Error(`arguments.values.${location}.${key} is not declared by ${operation.key.operationRef}`);
+        }
+        const pointer = `/${location}/${name.replaceAll('~', '~0').replaceAll('/', '~1')}`;
+        const value = pointerValue(values, pointer);
+        const schema = parameterSchema(parameter, pointer);
+        if (value === undefined) {
+            if (targets.some((target) => target.startsWith(pointer + '/')))
+                requiredPointers(schema, undefined, pointer, missing, targets);
+            else if (parameter.required === true && !targets.includes(pointer))
+                missing.push(pointer);
+            continue;
+        }
+        requiredPointers(schema, value, pointer, missing, targets);
+        checkOasValue(value, targets.some((item) => item.startsWith(pointer + '/')) ||
+            missing.some((item) => item.startsWith(pointer + '/'))
+            ? projectLiteralInputSchema(optionalRequestProperties(schema), bindings
+                .filter((entry) => entry.targetPointer.startsWith(pointer + '/'))
+                .map((entry) => pointerTokens(entry.targetPointer).slice(2)), pointer).schema
+            : schema, dialect, pointer);
+    }
+    const bodySchema = bodyMediaSchema(operation, requestMediaType);
+    if (bodySchema !== undefined) {
+        const requestBody = object(operation.operation.requestBody, `${operation.key.operationRef}.requestBody`);
+        if (values.body === undefined &&
+            requestBody.required === true &&
+            !targets.some((pointer) => pointer === '/body' || pointer.startsWith('/body/')))
+            missing.push('/body');
+        if (values.body !== undefined ||
+            targets.some((pointer) => pointer.startsWith('/body/'))) {
+            requiredPointers(bodySchema, values.body, '/body', missing, targets);
+        }
+        if (values.body !== undefined) {
+            const incomplete = targets.some((pointer) => pointer.startsWith('/body/')) ||
+                missing.some((pointer) => pointer.startsWith('/body/'));
+            checkOasValue(values.body, incomplete
+                ? projectLiteralInputSchema(optionalRequestProperties(bodySchema), bindings
+                    .filter((entry) => entry.targetPointer.startsWith('/body/'))
+                    .map((entry) => pointerTokens(entry.targetPointer).slice(1)), '/body').schema
+                : bodySchema, dialect, '/body');
+        }
+    }
+    return {
+        valid: missing.length === 0,
+        missingInputs: [...new Set(missing)],
+        requiresRuntimeValidation: bindings.length > 0,
+    };
+}

package/dist/bindings/assign-json-input-value.d.ts

@@ -0,0 +1,4 @@
+import type { JsonValueObject } from '../types/api-arguments.js';
+import type { AssignJsonInputValueInput } from '../types/json-input-assignment.js';
+/** Schema-owned containers and own-property assignment; never overwrite or fill sparse arrays. */
+export declare function assignJsonInputValue(input: AssignJsonInputValueInput): JsonValueObject;

package/dist/bindings/assign-json-input-value.js

@@ -0,0 +1,35 @@
+import { cloneJsonValue } from '../utils/clone-json-value.js';
+import { pointerTokens } from './json-pointer.js';
+/** Schema-owned containers and own-property assignment; never overwrite or fill sparse arrays. */
+export function assignJsonInputValue(input) {
+    const tokens = pointerTokens(input.pointer);
+    if (!tokens.length)
+        throw new Error(`${input.source} must identify a JSON field`);
+    const result = cloneJsonValue(input.values);
+    let container = result;
+    for (const [index, token] of tokens.entries()) {
+        if (Array.isArray(container) &&
+            (!/^(0|[1-9][0-9]*)$/.test(token) || Number(token) > container.length))
+            throw new Error(`${input.source} ${input.pointer} requires an explicit complete array prefix`);
+        if (index === tokens.length - 1) {
+            if (Object.hasOwn(container, token))
+                throw new Error(`${input.source} conflicts with existing value at ${input.pointer}`);
+            Reflect.set(container, token, cloneJsonValue(input.value));
+        }
+        else {
+            if (!Object.hasOwn(container, token)) {
+                const parent = '/' +
+                    tokens
+                        .slice(0, index + 1)
+                        .map((part) => part.replaceAll('~', '~0').replaceAll('/', '~1'))
+                        .join('/');
+                Reflect.set(container, token, input.containerKind(parent) === 'array' ? [] : Object.create(null));
+            }
+            const child = Reflect.get(container, token);
+            if (child === null || typeof child !== 'object')
+                throw new Error(`${input.source} traverses non-container ${input.pointer}`);
+            container = child;
+        }
+    }
+    return JSON.parse(JSON.stringify(result));
+}

package/dist/bindings/assign-request-input-value.d.ts

@@ -0,0 +1,4 @@
+import type { ApiArgumentValues, JsonValue } from '../types/api-arguments.js';
+import type { ApiBindingMaterial } from '../types/api-bindings.js';
+/** Pure assignment into JSON dictionaries, with OAS-owned container identity. */
+export declare function assignRequestInputValue(values: ApiArgumentValues, pointer: string, value: JsonValue, material: ApiBindingMaterial): ApiArgumentValues;

package/dist/bindings/assign-request-input-value.js

@@ -0,0 +1,39 @@
+import { pointerTokens } from './json-pointer.js';
+import { requestContainerKind } from './request-container-kind.js';
+import { cloneJsonValue } from '../utils/clone-json-value.js';
+/** Pure assignment into JSON dictionaries, with OAS-owned container identity. */
+export function assignRequestInputValue(values, pointer, value, material) {
+    const tokens = pointerTokens(pointer);
+    if (!tokens.length ||
+        !['path', 'query', 'header', 'cookie', 'querystring', 'body'].includes(tokens[0]))
+        throw new Error('confirmed input must identify a request field');
+    const result = cloneJsonValue(JSON.parse(JSON.stringify(values)));
+    let container = result;
+    for (const [index, token] of tokens.entries()) {
+        if (Array.isArray(container) &&
+            (!/^(0|[1-9][0-9]*)$/.test(token) || Number(token) > container.length))
+            throw new Error(`confirmed input ${pointer} requires an explicit complete array prefix`);
+        if (index === tokens.length - 1) {
+            if (Object.hasOwn(container, token))
+                throw new Error(`Request value conflicts with confirmed input ${pointer}`);
+            Reflect.set(container, token, cloneJsonValue(value));
+        }
+        else {
+            if (!Object.hasOwn(container, token)) {
+                const parent = '/' +
+                    tokens
+                        .slice(0, index + 1)
+                        .map((part) => part.replaceAll('~', '~0').replaceAll('/', '~1'))
+                        .join('/');
+                Reflect.set(container, token, requestContainerKind(material, parent) === 'array'
+                    ? []
+                    : Object.create(null));
+            }
+            const child = Reflect.get(container, token);
+            if (child === null || typeof child !== 'object')
+                throw new Error(`confirmed input traverses non-container ${pointer}`);
+            container = child;
+        }
+    }
+    return JSON.parse(JSON.stringify(result));
+}

package/dist/bindings/combine-binding-schemas.d.ts

@@ -0,0 +1,4 @@
+import type { BindingSchema } from '../types/api-bindings.js';
+/** Boolean identities belong to the schema algebra, not to runtime data defaults. */
+export declare function intersectBindingSchemas(schemas: BindingSchema[]): BindingSchema;
+export declare function unionBindingSchemas(schemas: BindingSchema[]): BindingSchema;

package/dist/bindings/combine-binding-schemas.js

@@ -0,0 +1,17 @@
+/** Boolean identities belong to the schema algebra, not to runtime data defaults. */
+export function intersectBindingSchemas(schemas) {
+    if (schemas.includes(false))
+        return false;
+    const assertions = schemas.filter((schema) => schema !== true);
+    if (!assertions.length)
+        return true;
+    return assertions.length === 1 ? assertions[0] : { allOf: assertions };
+}
+export function unionBindingSchemas(schemas) {
+    if (schemas.includes(true))
+        return true;
+    const alternatives = schemas.filter((schema) => schema !== false);
+    if (!alternatives.length)
+        return false;
+    return alternatives.length === 1 ? alternatives[0] : { anyOf: alternatives };
+}

package/dist/bindings/create-api-binding-source-registry.d.ts

@@ -0,0 +1,3 @@
+import type { ValidateApiBindingAssignmentInput } from '../types/api-bindings.js';
+import type { ApiBindingSourceRegistry } from '../types/binding-validation-internal.js';
+export declare function createApiBindingSourceRegistry(input: Pick<ValidateApiBindingAssignmentInput, 'materials' | 'nativeOutputs'>): ApiBindingSourceRegistry;

package/dist/bindings/create-api-binding-source-registry.js

@@ -0,0 +1,18 @@
+import { validateNativeOutputContracts } from './validate-native-output-contracts.js';
+export function createApiBindingSourceRegistry(input) {
+    if (!Array.isArray(input.materials))
+        throw new Error('binding materials must be an array');
+    if (!input.materials.length ||
+        input.materials.some((item) => !item || typeof item.callId !== 'string' || !item.callId.trim()))
+        throw new Error('binding materials require unique non-empty callIds');
+    const api = new Map(input.materials.map((material) => [material.callId, material]));
+    if (api.size !== input.materials.length)
+        throw new Error('binding materials require unique non-empty callIds');
+    const outputs = input.nativeOutputs === undefined ? [] : input.nativeOutputs;
+    validateNativeOutputContracts(outputs);
+    const native = new Map(outputs.map((item) => [item.nodeId, item]));
+    for (const output of outputs)
+        if (api.has(output.nodeId))
+            throw new Error(`native output ${output.nodeId} duplicates an API callId`);
+    return { api, native };
+}

package/dist/bindings/create-native-array-item-schema.d.ts

@@ -0,0 +1,4 @@
+import type { BindingSchema } from '../types/api-bindings.js';
+import type { NativeOutputContract } from '../types/node-output.js';
+/** Native JSON roots are not HTTP envelopes or OAS response definitions. */
+export declare function createNativeArrayItemSchema(output: NativeOutputContract, pointer: string): BindingSchema;

package/dist/bindings/create-native-array-item-schema.js

@@ -0,0 +1,16 @@
+import { validateNativeOutputContracts } from './validate-native-output-contracts.js';
+import { schemasAtPointer } from './schema-at-pointer.js';
+import { projectArrayItemSchema } from './project-array-item-schema.js';
+import { createSchemaResourceContext } from './resources/create-schema-resource-context.js';
+/** Native JSON roots are not HTTP envelopes or OAS response definitions. */
+export function createNativeArrayItemSchema(output, pointer) {
+    validateNativeOutputContracts([output]);
+    const resources = createSchemaResourceContext(output.schema);
+    const items = schemasAtPointer(resources.root, pointer, resources).flatMap((schema) => {
+        const projection = projectArrayItemSchema(schema, resources);
+        return projection.allowsArray ? [projection.schema] : [];
+    });
+    if (!items.length)
+        throw new Error(`native output ${output.nodeId}${pointer} has no declared array`);
+    return resources.bundle({ anyOf: items });
+}

package/dist/bindings/json-pointer.d.ts

@@ -0,0 +1,3 @@
+export declare function pointerTokens(pointer: string): string[];
+export declare function pointerValue(value: unknown, pointer: string): unknown;
+export declare function hasPointer(value: unknown, pointer: string): boolean;

package/dist/bindings/json-pointer.js

@@ -0,0 +1,24 @@
+export function pointerTokens(pointer) {
+    if (pointer === '')
+        return [];
+    if (!pointer.startsWith('/') || /~(?![01])/u.test(pointer))
+        throw new Error(`Invalid JSON Pointer: ${pointer}`);
+    return pointer
+        .slice(1)
+        .split('/')
+        .map((part) => part.replaceAll('~1', '/').replaceAll('~0', '~'));
+}
+export function pointerValue(value, pointer) {
+    let result = value;
+    for (const token of pointerTokens(pointer)) {
+        if (result === null ||
+            typeof result !== 'object' ||
+            !Object.hasOwn(result, token))
+            return undefined;
+        result = Reflect.get(result, token);
+    }
+    return result;
+}
+export function hasPointer(value, pointer) {
+    return pointerValue(value, pointer) !== undefined;
+}

package/dist/bindings/materialize-api-arguments.d.ts

@@ -0,0 +1,4 @@
+import type { ApiArgumentValues, JsonValue, OutputBinding } from '../types/api-arguments.js';
+import type { ApiBindingMaterial } from '../types/api-bindings.js';
+/** Copy response values without coercion, defaults or missing-value recovery. */
+export declare function materializeApiArguments(values: ApiArgumentValues, bindings: OutputBinding[], responses: Record<string, JsonValue>, material: ApiBindingMaterial): ApiArgumentValues;

package/dist/bindings/materialize-api-arguments.js

@@ -0,0 +1,54 @@
+import { pointerTokens, pointerValue } from './json-pointer.js';
+import { requestContainerKind } from './request-container-kind.js';
+/** Copy response values without coercion, defaults or missing-value recovery. */
+export function materializeApiArguments(values, bindings, responses, material) {
+    function copy(value) {
+        if (Array.isArray(value))
+            return value.map(copy);
+        if (value === null || typeof value !== 'object')
+            return value;
+        const result = Object.create(null);
+        for (const [key, child] of Object.entries(value))
+            result[key] = copy(child);
+        return result;
+    }
+    const result = copy(JSON.parse(JSON.stringify(values)));
+    for (const binding of bindings) {
+        if (!Object.hasOwn(responses, binding.sourceNodeId))
+            throw new Error(`Missing response node ${binding.sourceNodeId}`);
+        const value = pointerValue(responses[binding.sourceNodeId], binding.sourcePointer);
+        if (value === undefined)
+            throw new Error(`Missing response pointer ${binding.sourceNodeId}${binding.sourcePointer}`);
+        const tokens = pointerTokens(binding.targetPointer);
+        if (!tokens.length)
+            throw new Error('binding target must identify a request field');
+        let container = result;
+        for (const [index, token] of tokens.entries()) {
+            if (index === tokens.length - 1) {
+                if (Object.hasOwn(container, token))
+                    throw new Error(`Literal conflicts with binding ${binding.targetPointer}`);
+                if (Array.isArray(container) && !/^(0|[1-9][0-9]*)$/.test(token))
+                    throw new Error(`Binding array index is invalid ${binding.targetPointer}`);
+                Reflect.set(container, token, copy(value));
+            }
+            else {
+                if (!Object.hasOwn(container, token)) {
+                    const pointer = '/' +
+                        tokens
+                            .slice(0, index + 1)
+                            .map((part) => part.replaceAll('~', '~0').replaceAll('/', '~1'))
+                            .join('/');
+                    const next = requestContainerKind(material, pointer) === 'array'
+                        ? []
+                        : Object.create(null);
+                    Reflect.set(container, token, next);
+                }
+                const child = Reflect.get(container, token);
+                if (!child || typeof child !== 'object')
+                    throw new Error(`Binding traverses non-container ${binding.targetPointer}`);
+                container = child;
+            }
+        }
+    }
+    return JSON.parse(JSON.stringify(result));
+}

package/dist/bindings/native-binding-schema.d.ts

@@ -0,0 +1,3 @@
+import type { BindingSchema } from '../types/api-bindings.js';
+import type { NativeOutputContract } from '../types/node-output.js';
+export declare function nativeBindingSchemas(output: NativeOutputContract, pointer: string): BindingSchema[];

package/dist/bindings/native-binding-schema.js

@@ -0,0 +1,6 @@
+import { createSchemaResourceContext } from './resources/create-schema-resource-context.js';
+import { schemasAtPointer } from './schema-at-pointer.js';
+export function nativeBindingSchemas(output, pointer) {
+    const resources = createSchemaResourceContext(output.schema);
+    return schemasAtPointer(resources.root, pointer, resources).map(resources.bundle);
+}

package/dist/bindings/planning/create-api-binding-planning-record.d.ts

@@ -0,0 +1,3 @@
+import type { ApiBindingPlanningRecord, CreateApiBindingPlanningRecordInput } from '../../types/api-binding-planning.js';
+/** Reasons belong to exact call decisions; gap descriptions already state their reasons. */
+export declare function createApiBindingPlanningRecord(input: CreateApiBindingPlanningRecordInput): ApiBindingPlanningRecord;

package/dist/bindings/planning/create-api-binding-planning-record.js

@@ -0,0 +1,26 @@
+import { apiBindingCallReasonsSchema, apiBindingPlanningRecordSchema, } from '../../schemas/api-binding-planning-schema.js';
+import { describeApiBindingPlanning } from './describe-api-binding-planning.js';
+import { validateApiBindingAssignments } from '../validate-api-binding-assignments.js';
+import { validateApiBindingGaps } from '../validate-api-binding-gaps.js';
+/** Reasons belong to exact call decisions; gap descriptions already state their reasons. */
+export function createApiBindingPlanningRecord(input) {
+    const { input: snapshot, context } = describeApiBindingPlanning(input);
+    validateApiBindingAssignments({ ...snapshot, calls: input.plan.calls });
+    validateApiBindingGaps({ ...snapshot, plan: input.plan });
+    const reasons = apiBindingCallReasonsSchema.parse(input.reasons);
+    const byId = new Map(reasons.map((item) => [item.callId, item.reason]));
+    if (reasons.length !== input.plan.calls.length ||
+        byId.size !== reasons.length ||
+        input.plan.calls.some((call) => !byId.has(call.callId)))
+        throw new Error('binding planning reasons must name every planned callId exactly once');
+    return apiBindingPlanningRecordSchema.parse({
+        kind: 'proposed-bindings',
+        calls: input.plan.calls.map((call) => ({
+            callId: call.callId,
+            bindings: structuredClone(call.bindings),
+            reason: byId.get(call.callId),
+        })),
+        gaps: structuredClone(input.plan.gaps),
+        evidence: { kind: 'supplied-binding-contracts', context },
+    });
+}

package/dist/bindings/planning/describe-api-binding-planning.d.ts

@@ -0,0 +1,3 @@
+import type { ApiBindingPlanningDescription, ApiBindingPlanningInput } from '../../types/api-binding-planning.js';
+/** Snapshot only declared source data before an asynchronous model invocation. */
+export declare function describeApiBindingPlanning(input: ApiBindingPlanningInput): ApiBindingPlanningDescription;

package/dist/bindings/planning/describe-api-binding-planning.js

@@ -0,0 +1,59 @@
+import { apiBindingPlanningIdentitySchema, apiBindingMaterialRoleSchema, apiBindingPlanningOperationSchema, } from '../../schemas/api-binding-planning-schema.js';
+import { createApiBindingSourceRegistry } from '../create-api-binding-source-registry.js';
+import { listApiResponsePointers } from '../../openapi/response/list-api-response-pointers.js';
+/** Snapshot only declared source data before an asynchronous model invocation. */
+export function describeApiBindingPlanning(input) {
+    const { scenario } = apiBindingPlanningIdentitySchema.parse({
+        scenario: input.scenario,
+    });
+    createApiBindingSourceRegistry(input);
+    const materials = input.materials.map((material) => {
+        const parsedOperation = apiBindingPlanningOperationSchema.safeParse(material.operation);
+        if (!parsedOperation.success)
+            throw new Error(`binding material ${material.callId}.operation is invalid: ${parsedOperation.error.message}`);
+        const options = apiBindingMaterialRoleSchema.parse({
+            purpose: material.purpose,
+            requestMediaType: material.requestMediaType,
+        });
+        return {
+            callId: material.callId,
+            operation: structuredClone(material.operation),
+            ...(options.purpose === undefined ? {} : { purpose: options.purpose }),
+            ...(options.requestMediaType === undefined
+                ? {}
+                : { requestMediaType: options.requestMediaType }),
+        };
+    });
+    const snapshot = {
+        scenario,
+        materials,
+        ...(input.nativeOutputs === undefined
+            ? {}
+            : {
+                nativeOutputs: input.nativeOutputs.map((output) => ({
+                    nodeId: output.nodeId,
+                    schema: structuredClone(output.schema),
+                })),
+            }),
+    };
+    return {
+        input: snapshot,
+        context: {
+            scenario,
+            ...(snapshot.nativeOutputs === undefined
+                ? {}
+                : { nativeOutputs: structuredClone(snapshot.nativeOutputs) }),
+            materials: materials.map(({ operation, ...material }) => ({
+                ...material,
+                operation: structuredClone({
+                    key: operation.key,
+                    method: operation.method,
+                    path: operation.path,
+                    operation: operation.operation,
+                    effective: operation.effective,
+                }),
+                responsePointerCatalog: listApiResponsePointers(operation),
+            })),
+        },
+    };
+}

package/dist/bindings/planning/validate-api-binding-planning-record.d.ts

@@ -0,0 +1,3 @@
+import type { ValidateApiBindingPlanningRecordInput } from '../../types/api-binding-planning.js';
+/** Recheck against the original planning input and actual proposed plan, not later revisions. */
+export declare function validateApiBindingPlanningRecord(input: ValidateApiBindingPlanningRecordInput): void;

package/dist/bindings/planning/validate-api-binding-planning-record.js

@@ -0,0 +1,13 @@
+import { isDeepStrictEqual } from 'node:util';
+import { apiBindingPlanningRecordSchema } from '../../schemas/api-binding-planning-schema.js';
+import { createApiBindingPlanningRecord } from './create-api-binding-planning-record.js';
+/** Recheck against the original planning input and actual proposed plan, not later revisions. */
+export function validateApiBindingPlanningRecord(input) {
+    const record = apiBindingPlanningRecordSchema.parse(input.record);
+    const expected = createApiBindingPlanningRecord({
+        ...input,
+        reasons: record.calls.map(({ callId, reason }) => ({ callId, reason })),
+    });
+    if (!isDeepStrictEqual(record, expected))
+        throw new Error('Binding planning record differs from its original scenario, roles, contracts, native sources or proposed plan');
+}

package/dist/bindings/project-array-item-schema.d.ts

@@ -0,0 +1,5 @@
+import type { BindingSchema } from '../types/api-bindings.js';
+import type { ArrayItemProjection } from '../types/array-projection.js';
+import type { SchemaResourceContext } from '../types/schema-resource.js';
+/** Necessary item candidates; the original container remains the validation authority. */
+export declare function projectArrayItemSchema(schema: BindingSchema, resources?: SchemaResourceContext, active?: Set<BindingSchema>): ArrayItemProjection;

package/dist/bindings/project-array-item-schema.js

@@ -0,0 +1,67 @@
+import { isObject } from '../utils/is-object.js';
+import { intersectBindingSchemas, unionBindingSchemas, } from './combine-binding-schemas.js';
+/** Necessary item candidates; the original container remains the validation authority. */
+export function projectArrayItemSchema(schema, resources, active = new Set()) {
+    if (typeof schema === 'boolean')
+        return { allowsArray: schema, schema };
+    if (resources && typeof schema.$ref === 'string') {
+        if (active.has(schema))
+            throw new Error('Native array projection has a non-progressing reference cycle');
+        active.add(schema);
+        const siblings = { ...schema };
+        delete siblings.$ref;
+        try {
+            const target = projectArrayItemSchema(resources.resolve(schema), resources, active);
+            const sibling = projectArrayItemSchema(siblings, resources, active);
+            const allowsArray = target.allowsArray && sibling.allowsArray;
+            return {
+                allowsArray,
+                schema: allowsArray
+                    ? intersectBindingSchemas([target.schema, sibling.schema])
+                    : false,
+            };
+        }
+        finally {
+            active.delete(schema);
+        }
+    }
+    const types = schema.type === undefined
+        ? undefined
+        : Array.isArray(schema.type)
+            ? schema.type
+            : [schema.type];
+    let allowsArray = !types || types.includes('array');
+    const items = [];
+    if (Array.isArray(schema.prefixItems))
+        for (const child of schema.prefixItems)
+            if (typeof child === 'boolean' || isObject(child))
+                items.push(resources ? resources.reference(child) : child);
+    if (schema.items === undefined)
+        items.push(true);
+    else if (typeof schema.items === 'boolean' || isObject(schema.items))
+        items.push(resources ? resources.reference(schema.items) : schema.items);
+    const constraints = [
+        schema.maxItems === 0 ? false : unionBindingSchemas(items),
+    ];
+    for (const key of ['allOf', 'anyOf', 'oneOf']) {
+        if (!Array.isArray(schema[key]))
+            continue;
+        const branches = schema[key].flatMap((child) => typeof child === 'boolean' || isObject(child)
+            ? [projectArrayItemSchema(child, resources, active)]
+            : []);
+        if (key === 'allOf') {
+            allowsArray &&= branches.every((branch) => branch.allowsArray);
+            constraints.push(intersectBindingSchemas(branches.map((branch) => branch.schema)));
+        }
+        else {
+            allowsArray &&= branches.some((branch) => branch.allowsArray);
+            constraints.push(unionBindingSchemas(branches
+                .filter((branch) => branch.allowsArray)
+                .map((branch) => branch.schema)));
+        }
+    }
+    return {
+        allowsArray,
+        schema: allowsArray ? intersectBindingSchemas(constraints) : false,
+    };
+}

package/dist/bindings/request-binding-schema.d.ts

@@ -0,0 +1,2 @@
+import type { ApiBindingMaterial, BindingSchema } from '../types/api-bindings.js';
+export declare function requestBindingSchemas(material: ApiBindingMaterial, pointer: string): BindingSchema[];