@openapi-flow/core 0.1.0 → 0.2.0

package/README.md

@@ -1,11 +1,33 @@
 # @openapi-flow/core
 
-An importable Node.js library for turning a natural-language scenario and an OpenAPI document into a reviewable n8n workflow. It does not provide a server, connect to an n8n instance, or execute workflows.
+Engine-independent OpenAPI catalog, full operation contract lookup, OAS-derived Zod request schemas and argument validation. This is unreleased `0.2.0` source; published `0.1.0` has a different API.
 
-```sh
-npm install @openapi-flow/core @langchain/core @langchain/openai
+`createWorkflowPlanningCapabilities({ capabilities, apiCallIds })` specializes only capabilities that explicitly provide `createPlanningParametersSchema(context)`. Existing runtime schemas and capability objects are not mutated; custom definitions without the hook retain their schema. `validateNativeApiResponseReferences({ nativeNodes, capabilities, apiCallIds })` checks the API identities declared by each implementation's `responseReferences` and per-port `inputReferences`. It does not inspect arbitrary JSON field names, validate native-output identities as API IDs, infer a missing producer or repair a reference. These functions establish early planning boundaries; execution order and response contract validation remain separate.
+
+`createApiArgumentGenerationContract({ operation, bindings, requestMediaType })` is the shared literal-generation boundary. It returns the Zod `schema`, its matching `literalInputSchema` JSON Schema, and `hasLiteralInputs`. Bound paths have no original value definition and are forbidden (including through open additional properties); unbound OAS-approved fields stay available. Fully bound closed nested objects have no remaining literal decision. Open objects can still accept additional scenario values, so binding every named property does not close that OAS contract. The original operation and complete runtime request schema remain unchanged.
+
+Dynamic OAS assertions are no longer round-tripped through experimental `z.fromJSONSchema`. `createOasValueSchema` uses Zod's public refinement and metadata APIs: Scalar's JSON Schema validator checks the preserved assertions, and Zod exports those same assertions to LangChain. Type-less constraints, enum siblings and simultaneous compositions are not replaced by inferred types or weaker schemas. OAS 3.0 `nullable` and boolean exclusive bounds are explicitly translated to Draft 2020-12 syntax; formats, annotations and enum/example data are retained. Each embedded schema has a resource ID so fragment references keep their original scope. These IDs are schema identifiers, not inferred API input values. `validateApiArguments` and the complete `createApiRequestSchema` use the same dialect conversion; the latter retains required fields for the n8n standalone validator. Uncompileable selected schemas fail with their source before a model call. Provider-specific schema support is still an external boundary, not a reason to trim the OAS contract.
+
+See [Zod's JSON Schema and metadata APIs](https://zod.dev/json-schema#metadata) and the [OAS 3.0 Schema Object](https://spec.openapis.org/oas/v3.0.4.html#schema-object) for the conversion boundary and nullable semantics. This does not claim exhaustive support for every schema dialect or provider.
+
+```ts
+import {
+  createApiCatalog,
+  listApiOperations,
+  resolveApiOperations,
+} from '@openapi-flow/core';
 ```
 
-The host supplies an OpenAPI JSON object, a LangChain chat model, and a trusted API origin. See the [usage and current limitations](https://github.com/carefreelife98/openapi-flow#current-api) before generating workflows. `generateWorkflow` sends operation metadata to the host-supplied model. Review the resulting plan and workflow before importing it into n8n.
+The host supplies `{ id, spec }` documents. Catalog creation requires neither deployment credentials nor a per-path effect policy. The selected full OAS contract remains available before any engine-specific conversion. Operation keys carry document ID, snapshot hash and OAS JSON Pointer; changed documents fail lookup.
+
+`createApiArgumentsSchema` preserves OAS request types and excludes bound fields from model proposals. `validateApiArguments` checks literal constraints and returns missing-input pointers. `validateApiBindingPlan` checks response-to-request identities, pointers, known incompatible types and cycles. `materializeApiArguments(values, bindings, responses, material)` copies actual values without coercion or defaults; the OAS material determines missing container kinds. `createApiRequestSchema` supplies the complete final request schema for runtime validation. The `/runtime` entrypoint contains execution-only materialization and serializers without catalog/document intake. Core does not call an LLM, import LangChain/n8n, execute APIs or provide a server. The `/internal` export is an unstable adapter boundary. See the [workspace guide](https://github.com/carefreelife98/openapi-flow#independent-stages).
+
+`listApiResponsePointers(operation)` describes finite response-body declarations grouped by the original response key and media type. Each `declaredPointers` entry has an exact RFC 6901 body pointer, its `schemaLocation`, and the type/description actually declared by the schema. Empty pointer means the entire response body. Composition and conditional branch locations stay distinct; enum/example/default data are not traversed as schemas. OAS 3.0 nullable syntax is normalized without changing the operation.
+
+`dynamicLocations` identifies dictionaries, pattern keys, homogeneous array items, unexpanded references, recursive schema boundaries and unconstrained values. It never invents a dictionary key or a sample item index. A tuple's explicitly declared positions can be listed, but their runtime existence is not guaranteed. This catalog is advisory, not an exhaustive schema projection, a whitelist, a schema satisfiability proof or a promise that optional/conditional fields exist. The full OAS and existing binding/runtime validators remain authoritative; missing response values still fail without substitution.
+
+`WorkflowGraphPlan` describes native capability settings, named-port edges, starts and unmet requirements. `validateWorkflowGraphPlan` uses host-supplied capability contracts to check graph identity/ports/cycles, exclusive-branch join compatibility and API response availability on every incoming route. It does not prove scenario coverage or exhaustively validate response pointer types against every OAS schema dialect; missing fields fail in the runtime compiler. This contract is engine-independent and does not import an n8n node registry.
+
+Our code is MIT-licensed. Core has no n8n SDK dependency. Dependency licenses remain separate; see [third-party notices](./THIRD_PARTY_NOTICES.md).
 
-This package's own code is MIT-licensed. Its `@n8n/workflow-sdk` dependency is separately licensed under [n8n's Sustainable Use License](https://docs.n8n.io/n8n-community-license/), which places conditions on use and redistribution. The MIT license for this package does not change those conditions. See [third-party notices](./THIRD_PARTY_NOTICES.md).
+`ReviewableWorkflowApiMaterial` discriminates ready calls with real arguments from blocked calls with OAS identity, declared bindings and causal gap IDs, but no fabricated arguments. `createReviewableWorkflowGraphPlan` adds explicitly identified gaps and blocked calls to the proposed DAG, derives its actual roots, and invokes `validateReviewableWorkflowGraphPlan`. Topology and binding-contract validation are never skipped because of gaps. Blocked/gap nodes have ports but no available API response. `validateApiBindingAssignments` checks assignments independently of execution readiness; `validateApiBindingGaps` requires every reported gap to identify a known call and an OAS-declared request pointer. The strict `validateApiBindingPlan` still rejects all gaps. These contracts do not imply that review workflows may be executed.

package/THIRD_PARTY_NOTICES.md

@@ -1,5 +1,5 @@
 # Third-party notices
 
-`@openapi-flow/core` depends on `@n8n/workflow-sdk`, which is licensed separately under n8n's [Sustainable Use License](https://github.com/n8n-io/n8n/blob/master/LICENSE.md). Its terms restrict use and redistribution; check them for your intended use. This package does not bundle the SDK's source code.
+The unreleased `@openapi-flow/core@0.2.0` source depends on Scalar OpenAPI/JSON Schema libraries, Zod, Ajv, ajv-formats and fast-uri. Ajv's public schema registry and fast-uri preserve JSON Schema reference scope during native contract projection. It does not depend on `@n8n/workflow-sdk` or LangChain. This dependency boundary differs from the previously published `0.1.0` package.
 
 Other dependencies retain their own licenses. The MIT license in this package applies to openapi-flow's code only.

package/dist/arguments/list-api-request-media-types.d.ts

@@ -0,0 +1,2 @@
+import type { ApiOperationContract } from '../types/api-operation.js';
+export declare function listApiRequestMediaTypes(operation: ApiOperationContract): string[];

package/dist/arguments/list-api-request-media-types.js

@@ -0,0 +1,8 @@
+import { object } from '../openapi/common/parse-spec-utils.js';
+export function listApiRequestMediaTypes(operation) {
+    if (operation.operation.requestBody === undefined)
+        return [];
+    const source = `${operation.key.operationRef}.requestBody`;
+    const body = object(operation.operation.requestBody, source);
+    return Object.keys(object(body.content, `${source}.content`));
+}

package/dist/arguments/request-contract.d.ts

@@ -0,0 +1,4 @@
+import type { ApiOperationContract } from '../types/api-operation.js';
+import type { JsonObject } from '../types/openapi.js';
+export declare function bodyMediaSchema(operation: ApiOperationContract, mediaType?: string): JsonObject | boolean | undefined;
+export declare function parameterSchema(parameter: JsonObject, source: string): JsonObject | boolean;

package/dist/arguments/request-contract.js

@@ -0,0 +1,38 @@
+import { object } from '../openapi/common/parse-spec-utils.js';
+export function bodyMediaSchema(operation, mediaType) {
+    if (operation.operation.requestBody === undefined) {
+        if (mediaType !== undefined)
+            throw new Error(`${operation.key.operationRef} has no requestBody for ${mediaType}`);
+        return undefined;
+    }
+    const body = object(operation.operation.requestBody, `${operation.key.operationRef}.requestBody`);
+    const content = object(body.content, `${operation.key.operationRef}.requestBody.content`);
+    const names = Object.keys(content);
+    const selected = mediaType === undefined && names.length === 1 ? names[0] : mediaType;
+    if (selected === undefined)
+        throw new Error(`${operation.key.operationRef}.requestMediaType must explicitly select one of ${names.join(', ')}`);
+    if (!Object.hasOwn(content, selected))
+        throw new Error(`${operation.key.operationRef}.requestBody.content has no ${selected}`);
+    const media = object(content[selected], `${operation.key.operationRef}.requestBody.content.${selected}`);
+    if (media.schema === undefined)
+        return true;
+    return typeof media.schema === 'boolean'
+        ? media.schema
+        : object(media.schema, `${selected}.schema`);
+}
+export function parameterSchema(parameter, source) {
+    if (parameter.schema !== undefined)
+        return typeof parameter.schema === 'boolean'
+            ? parameter.schema
+            : object(parameter.schema, `${source}.schema`);
+    const content = object(parameter.content, `${source}.content`);
+    const names = Object.keys(content);
+    if (names.length !== 1)
+        throw new Error(`${source}.content must have one media type`);
+    const media = object(content[names[0]], `${source}.content.${names[0]}`);
+    return media.schema === undefined
+        ? true
+        : typeof media.schema === 'boolean'
+            ? media.schema
+            : object(media.schema, `${source}.schema`);
+}

package/dist/arguments/request-media-type-priority.d.ts

@@ -0,0 +1,2 @@
+/** Product preference, not an OpenAPI restriction or transport support check. */
+export declare function requestMediaTypePriority(mediaType: string): number;

package/dist/arguments/request-media-type-priority.js

@@ -0,0 +1,8 @@
+/** Product preference, not an OpenAPI restriction or transport support check. */
+export function requestMediaTypePriority(mediaType) {
+    if (mediaType === 'application/json')
+        return 0;
+    if (mediaType === 'application/x-www-form-urlencoded')
+        return 1;
+    return mediaType.includes('*') ? 3 : 2;
+}

package/dist/arguments/select-default-api-request-media-type.d.ts

@@ -0,0 +1,3 @@
+import type { ApiOperationContract } from '../types/api-operation.js';
+/** Select only an OAS-declared key; never synthesize a request media type. */
+export declare function selectDefaultApiRequestMediaType(operation: ApiOperationContract): string | undefined;

package/dist/arguments/select-default-api-request-media-type.js

@@ -0,0 +1,17 @@
+import { listApiRequestMediaTypes } from './list-api-request-media-types.js';
+import { requestMediaTypePriority } from './request-media-type-priority.js';
+/** Select only an OAS-declared key; never synthesize a request media type. */
+export function selectDefaultApiRequestMediaType(operation) {
+    if (operation.operation.requestBody === undefined)
+        return undefined;
+    const mediaTypes = listApiRequestMediaTypes(operation);
+    const [selected] = mediaTypes.sort((left, right) => {
+        const priority = requestMediaTypePriority(left) - requestMediaTypePriority(right);
+        if (priority !== 0)
+            return priority;
+        return left < right ? -1 : left > right ? 1 : 0;
+    });
+    if (selected === undefined)
+        throw new Error(`${operation.key.operationRef}.requestBody.content has no request media type`);
+    return selected;
+}

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/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-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/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[];

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

@@ -0,0 +1,23 @@
+import { pointerTokens } from './json-pointer.js';
+import { schemasAtPointer } from './schema-at-pointer.js';
+import { bodyMediaSchema, parameterSchema, } from '../arguments/request-contract.js';
+export function requestBindingSchemas(material, pointer) {
+    const [location, name, ...children] = pointerTokens(pointer);
+    if (location === 'body') {
+        const schema = bodyMediaSchema(material.operation, material.requestMediaType);
+        return schema === undefined
+            ? []
+            : schemasAtPointer(schema, pointer.slice(5));
+    }
+    const parameter = material.operation.effective.parameters.find((item) => item.in === location && item.name === name);
+    if (!parameter)
+        return [];
+    const schema = parameterSchema(parameter, pointer);
+    const childPointer = children.length
+        ? '/' +
+            children
+                .map((token) => token.replaceAll('~', '~0').replaceAll('/', '~1'))
+                .join('/')
+        : '';
+    return schemasAtPointer(schema, childPointer);
+}

package/dist/bindings/request-container-kind.d.ts

@@ -0,0 +1,3 @@
+import type { ApiBindingMaterial, RequestContainerKind } from '../types/api-bindings.js';
+/** Container identity comes from the OAS, never from a numeric property name. */
+export declare function requestContainerKind(material: ApiBindingMaterial, pointer: string): RequestContainerKind;

package/dist/bindings/request-container-kind.js

@@ -0,0 +1,17 @@
+import { requestBindingSchemas } from './request-binding-schema.js';
+import { schemaAllowsContainer } from './schema-allows-container.js';
+/** Container identity comes from the OAS, never from a numeric property name. */
+export function requestContainerKind(material, pointer) {
+    if (['/path', '/query', '/header', '/cookie'].includes(pointer))
+        return 'object';
+    const kinds = new Set();
+    for (const schema of requestBindingSchemas(material, pointer)) {
+        if (schemaAllowsContainer(schema, 'object'))
+            kinds.add('object');
+        if (schemaAllowsContainer(schema, 'array'))
+            kinds.add('array');
+    }
+    if (kinds.size !== 1)
+        throw new Error(`Request ${material.callId}${pointer} needs an explicit literal container: OAS does not determine object versus array`);
+    return kinds.has('array') ? 'array' : 'object';
+}

package/dist/bindings/resources/clone-schema-resource.d.ts

@@ -0,0 +1,3 @@
+import type { BindingSchema } from '../../types/api-bindings.js';
+/** JSON has locations, not shared JavaScript object identity or object cycles. */
+export declare function cloneSchemaResource(schema: BindingSchema): BindingSchema;

package/dist/bindings/resources/clone-schema-resource.js

@@ -0,0 +1,38 @@
+/** JSON has locations, not shared JavaScript object identity or object cycles. */
+export function cloneSchemaResource(schema) {
+    const active = new Set();
+    function copy(value, path) {
+        if (value === null ||
+            typeof value === 'string' ||
+            typeof value === 'boolean')
+            return value;
+        if (typeof value === 'number' && Number.isFinite(value))
+            return value;
+        if (typeof value !== 'object' || value === null)
+            throw new Error(`Native schema${path} must contain JSON values`);
+        if (active.has(value))
+            throw new Error(`Native schema${path} has a JavaScript object cycle; use a schema reference`);
+        if (!Array.isArray(value) &&
+            Object.getPrototypeOf(value) !== Object.prototype &&
+            Object.getPrototypeOf(value) !== null)
+            throw new Error(`Native schema${path} must contain JSON objects`);
+        active.add(value);
+        try {
+            return Array.isArray(value)
+                ? Array.from(value, (child, index) => copy(child, `${path}/${index}`))
+                : Object.fromEntries(Object.entries(value).map(([key, child]) => [
+                    key,
+                    copy(child, `${path}/${key}`),
+                ]));
+        }
+        finally {
+            active.delete(value);
+        }
+    }
+    const result = copy(schema, '');
+    if (typeof result === 'boolean')
+        return result;
+    if (result === null || typeof result !== 'object' || Array.isArray(result))
+        throw new Error('Native schema resource must be a JSON object or boolean');
+    return result;
+}