@openapi-flow/core 0.1.0 → 0.3.0

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', '/querystring'].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;
+}

package/dist/bindings/resources/create-schema-resource-context.d.ts

@@ -0,0 +1,4 @@
+import type { BindingSchema } from '../../types/api-bindings.js';
+import type { SchemaResourceContext } from '../../types/schema-resource.js';
+/** Keep original resources; projected values reference their original locations. */
+export declare function createSchemaResourceContext(schema: BindingSchema): SchemaResourceContext;

package/dist/bindings/resources/create-schema-resource-context.js

@@ -0,0 +1,234 @@
+import { createHash } from 'node:crypto';
+import { Ajv2020 } from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import uri from 'fast-uri';
+import { isObject } from '../../utils/is-object.js';
+import { cloneSchemaResource } from './clone-schema-resource.js';
+import { jsonValuesEqual } from '../../utils/json-values-equal.js';
+/** Keep original resources; projected values reference their original locations. */
+export function createSchemaResourceContext(schema) {
+    if (typeof schema === 'boolean')
+        return {
+            root: schema,
+            reference: (value) => value,
+            resolve: (value) => value,
+            bundle: (value) => value,
+            bundleStaticProjections: (projections) => ({
+                projections,
+                definitions: {},
+            }),
+        };
+    const document = cloneSchemaResource(schema);
+    if (typeof document === 'boolean')
+        throw new Error('Native schema resource must be an object');
+    // JSON Schema permits an implementation-assigned initial retrieval URI.
+    if (document.$id !== undefined && typeof document.$id !== 'string')
+        throw new Error('Native schema.$id must be a URI-reference string');
+    const retrievalUri = `https://openapi-flow.invalid/schema/${createHash('sha256').update(JSON.stringify(document)).digest('hex')}`;
+    const rootUri = typeof document.$id === 'string'
+        ? uri.resolve(retrievalUri, document.$id)
+        : retrievalUri;
+    const root = { ...document, $id: rootUri };
+    const locations = new WeakMap();
+    function index(current, pointer, baseUri) {
+        if (typeof current === 'boolean')
+            return;
+        const base = typeof current.$id === 'string'
+            ? uri.resolve(baseUri, current.$id)
+            : baseUri;
+        locations.set(current, {
+            reference: uri.resolve(rootUri, '#' + pointer.split('/').map(encodeURIComponent).join('/')),
+            baseUri: base,
+        });
+        function child(value, suffix) {
+            if (typeof value === 'boolean' || isObject(value))
+                index(value, pointer + suffix, base);
+        }
+        // Traverse schema-valued keywords, not const/enum/default/example data.
+        for (const key of [
+            '$defs',
+            'definitions',
+            'properties',
+            'patternProperties',
+            'dependentSchemas',
+            'dependencies',
+        ]) {
+            const children = current[key];
+            if (!isObject(children))
+                continue;
+            for (const [name, value] of Object.entries(children))
+                child(value, '/' + key + '/' + name.replaceAll('~', '~0').replaceAll('/', '~1'));
+        }
+        for (const key of [
+            'items',
+            'contains',
+            'additionalProperties',
+            'unevaluatedProperties',
+            'unevaluatedItems',
+            'propertyNames',
+            'not',
+            'if',
+            'then',
+            'else',
+        ])
+            child(current[key], '/' + key);
+        for (const key of ['allOf', 'anyOf', 'oneOf', 'prefixItems']) {
+            const children = current[key];
+            if (Array.isArray(children))
+                children.forEach((value, position) => child(value, '/' + key + '/' + position));
+        }
+    }
+    index(root, '', rootUri);
+    const ajv = new Ajv2020({ strict: false, discriminator: true });
+    addFormats.default(ajv);
+    ajv.addSchema(root);
+    // Resolve/validate on the host. No remote fetch and no runtime schema compiler.
+    ajv.getSchema(rootUri);
+    function resolveReference(current) {
+        if (typeof current === 'boolean' || typeof current.$ref !== 'string')
+            return current;
+        const location = locations.get(current);
+        // Generated projection references are already absolute; original references use lexical scope.
+        const reference = location
+            ? uri.resolve(location.baseUri, current.$ref)
+            : current.$ref;
+        const target = ajv.getSchema(reference);
+        if (!target)
+            throw new Error(`Unresolved native schema reference ${reference}`);
+        const value = target.schema;
+        if (typeof value !== 'boolean' && !isObject(value))
+            throw new Error(`Native schema reference ${reference} does not identify a schema`);
+        return value;
+    }
+    function declaredType(current, visited = new Set()) {
+        if (typeof current === 'boolean' || visited.has(current))
+            return undefined;
+        if (typeof current.type === 'string')
+            return current.type;
+        if (Array.isArray(current.type) &&
+            current.type.every((type) => typeof type === 'string'))
+            return current.type;
+        visited.add(current);
+        return typeof current.$ref === 'string'
+            ? declaredType(resolveReference(current), visited)
+            : undefined;
+    }
+    function bundleStaticProjections(projections) {
+        const definitions = {};
+        const names = new WeakMap();
+        function rewrite(current) {
+            if (typeof current === 'boolean')
+                return current;
+            if (current.$dynamicRef !== undefined ||
+                current.$dynamicAnchor !== undefined ||
+                current.$recursiveRef !== undefined ||
+                current.$recursiveAnchor !== undefined)
+                throw new Error('Static schema relocation cannot change dynamic or recursive schema scope; an explicit dialect-aware bundle is required');
+            const result = cloneSchemaResource(current);
+            if (typeof result === 'boolean')
+                throw new Error('Expected a schema object');
+            // Resolution annotations are replaced by canonical locations, not validation rules.
+            delete result.$id;
+            delete result.$anchor;
+            delete result.$defs;
+            delete result.definitions;
+            // Only schema-valued positions are visited: const/enum/default/example data stay verbatim.
+            for (const key of [
+                'properties',
+                'patternProperties',
+                'dependentSchemas',
+                'dependencies',
+            ]) {
+                const children = current[key];
+                if (isObject(children))
+                    result[key] = Object.fromEntries(Object.entries(children).map(([name, child]) => [
+                        name,
+                        typeof child === 'boolean' || isObject(child)
+                            ? rewrite(child)
+                            : child,
+                    ]));
+            }
+            for (const key of [
+                'items',
+                'contains',
+                'additionalProperties',
+                'unevaluatedProperties',
+                'unevaluatedItems',
+                'propertyNames',
+                'not',
+                'if',
+                'then',
+                'else',
+            ]) {
+                const child = current[key];
+                if (typeof child === 'boolean' || isObject(child))
+                    result[key] = rewrite(child);
+            }
+            for (const key of ['allOf', 'anyOf', 'oneOf', 'prefixItems']) {
+                const children = current[key];
+                if (Array.isArray(children))
+                    result[key] = children.map((child) => typeof child === 'boolean' || isObject(child)
+                        ? rewrite(child)
+                        : child);
+            }
+            if (typeof current.$ref === 'string') {
+                const target = resolveReference(current);
+                if (typeof target === 'boolean') {
+                    delete result.$ref;
+                    if (!target)
+                        result.allOf = [
+                            false,
+                            ...(Array.isArray(result.allOf) ? result.allOf : []),
+                        ];
+                }
+                else {
+                    const location = locations.get(target);
+                    if (!location)
+                        throw new Error('Local schema reference target has no original resource location');
+                    let name = names.get(target);
+                    if (name === undefined) {
+                        name =
+                            'schema-' +
+                                createHash('sha256').update(location.reference).digest('hex');
+                        names.set(target, name);
+                        definitions[name] = rewrite(target);
+                    }
+                    result.$ref = '#/$defs/' + name;
+                    // Projection-owned type metadata repeats the referenced declaration exactly.
+                    // Original schema siblings are assertions and must never be discarded.
+                    if (!locations.has(current) &&
+                        Object.keys(current).every((key) => key === '$ref' || key === 'type') &&
+                        current.type !== undefined &&
+                        jsonValuesEqual(current.type, declaredType(target)))
+                        delete result.type;
+                }
+            }
+            return result;
+        }
+        const relocated = Object.fromEntries(Object.entries(projections).map(([name, projection]) => [
+            name,
+            rewrite(projection),
+        ]));
+        return { projections: relocated, definitions };
+    }
+    return {
+        root,
+        reference: (current) => {
+            if (typeof current === 'boolean')
+                return current;
+            const location = locations.get(current);
+            if (!location)
+                throw new Error('Schema projection requires an original resource location');
+            const type = declaredType(current);
+            return {
+                $ref: location.reference,
+                ...(type === undefined ? {} : { type }),
+            };
+        },
+        resolve: resolveReference,
+        bundleStaticProjections,
+        bundle: (projection) => typeof projection === 'boolean'
+            ? { $defs: { resource: root }, allOf: [projection] }
+            : { ...projection, $defs: { resource: root } },
+    };
+}

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

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

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

@@ -0,0 +1,21 @@
+import { isObject } from '../utils/is-object.js';
+import { schemasAtPointer } from './schema-at-pointer.js';
+import { normalizeOasValueSchema } from '../openapi/common/normalize-oas-value-schema.js';
+export function responseBindingSchemas(operation, pointer) {
+    return Object.values(operation.operation.responses ?? {}).flatMap((response) => {
+        if (!isObject(response) || !isObject(response.content))
+            return [];
+        return Object.values(response.content).flatMap((media) => {
+            if (!isObject(media))
+                return [];
+            const schema = media.schema;
+            return typeof schema === 'boolean' || isObject(schema)
+                ? schemasAtPointer(normalizeOasValueSchema(schema, operation.openapiVersion.startsWith('3.0.')
+                    ? 'openapi-3.0'
+                    : 'draft-2020-12'), pointer)
+                : pointer === ''
+                    ? [true]
+                    : [];
+        });
+    });
+}

package/dist/bindings/schema-allows-container.d.ts

@@ -0,0 +1,3 @@
+import type { BindingSchema, RequestContainerKind } from '../types/api-bindings.js';
+/** Necessary type conditions only; full schema satisfiability is a runtime check. */
+export declare function schemaAllowsContainer(schema: BindingSchema, kind: RequestContainerKind): boolean;

package/dist/bindings/schema-allows-container.js

@@ -0,0 +1,20 @@
+import { isObject } from '../utils/is-object.js';
+/** Necessary type conditions only; full schema satisfiability is a runtime check. */
+export function schemaAllowsContainer(schema, kind) {
+    if (typeof schema === 'boolean')
+        return schema;
+    if (schema.type !== undefined) {
+        const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+        if (!types.includes(kind))
+            return false;
+    }
+    for (const key of ['allOf', 'anyOf', 'oneOf']) {
+        if (!Array.isArray(schema[key]))
+            continue;
+        const branches = schema[key].map((child) => (typeof child === 'boolean' || isObject(child)) &&
+            schemaAllowsContainer(child, kind));
+        if (key === 'allOf' ? !branches.every(Boolean) : !branches.some(Boolean))
+            return false;
+    }
+    return true;
+}

package/dist/bindings/schema-at-pointer.d.ts

@@ -0,0 +1,4 @@
+import type { BindingSchema } from '../types/api-bindings.js';
+import type { SchemaResourceContext } from '../types/schema-resource.js';
+/** Resolve declared object fields, array items and composition alternatives. */
+export declare function schemasAtPointer(schema: BindingSchema, pointer: string, resources?: SchemaResourceContext): BindingSchema[];

package/dist/bindings/schema-at-pointer.js

@@ -0,0 +1,89 @@
+import { pointerTokens } from './json-pointer.js';
+import { isObject } from '../utils/is-object.js';
+import { intersectBindingSchemas, unionBindingSchemas, } from './combine-binding-schemas.js';
+import { schemaAllowsContainer } from './schema-allows-container.js';
+/** Resolve declared object fields, array items and composition alternatives. */
+export function schemasAtPointer(schema, pointer, resources) {
+    const active = new Map();
+    function visit(current, tokens, inheritedKinds = ['object', 'array']) {
+        if (typeof current === 'boolean')
+            return current;
+        if (!tokens.length)
+            return resources ? resources.reference(current) : current;
+        if (resources && typeof current.$ref === 'string') {
+            const key = JSON.stringify([tokens, inheritedKinds]);
+            const pending = active.get(current) ?? new Set();
+            if (pending.has(key))
+                throw new Error(`Native pointer projection has a non-progressing reference cycle at ${pointer}`);
+            pending.add(key);
+            active.set(current, pending);
+            const siblings = { ...current };
+            delete siblings.$ref;
+            try {
+                return intersectBindingSchemas([
+                    visit(resources.resolve(current), tokens, inheritedKinds),
+                    visit(siblings, tokens, inheritedKinds),
+                ]);
+            }
+            finally {
+                pending.delete(key);
+            }
+        }
+        const [token, ...rest] = tokens;
+        const kinds = inheritedKinds.filter((kind) => schemaAllowsContainer(current, kind));
+        const containers = [];
+        if (kinds.includes('object')) {
+            const children = [];
+            if (isObject(current.properties) &&
+                Object.hasOwn(current.properties, token)) {
+                const child = current.properties[token];
+                if (typeof child === 'boolean' || isObject(child))
+                    children.push(visit(child, rest));
+            }
+            if (isObject(current.patternProperties))
+                for (const [pattern, child] of Object.entries(current.patternProperties))
+                    if (new RegExp(pattern).test(token) &&
+                        (typeof child === 'boolean' || isObject(child)))
+                        children.push(visit(child, rest));
+            if (!children.length) {
+                // JSON Schema leaves unspecified additionalProperties open.
+                const child = current.additionalProperties;
+                children.push(child === undefined
+                    ? true
+                    : typeof child === 'boolean' || isObject(child)
+                        ? visit(child, rest)
+                        : false);
+            }
+            containers.push(intersectBindingSchemas(children));
+        }
+        if (kinds.includes('array') && /^(0|[1-9][0-9]*)$/.test(token)) {
+            const index = Number(token);
+            const prefix = Array.isArray(current.prefixItems)
+                ? current.prefixItems
+                : [];
+            const child = index < prefix.length ? prefix[index] : current.items;
+            containers.push(typeof current.maxItems === 'number' && index >= current.maxItems
+                ? false
+                : child === undefined
+                    ? true
+                    : typeof child === 'boolean' || isObject(child)
+                        ? visit(child, rest)
+                        : false);
+        }
+        const constraints = [unionBindingSchemas(containers)];
+        for (const key of ['allOf', 'anyOf', 'oneOf']) {
+            if (!Array.isArray(current[key]))
+                continue;
+            const children = current[key].map((child) => typeof child === 'boolean' || isObject(child)
+                ? visit(child, tokens, kinds)
+                : false);
+            // Parent oneOf branches can share child values once their discriminators disappear.
+            constraints.push(key === 'allOf'
+                ? intersectBindingSchemas(children)
+                : unionBindingSchemas(children));
+        }
+        return intersectBindingSchemas(constraints);
+    }
+    const projected = visit(schema, pointerTokens(pointer));
+    return projected === false ? [] : [projected];
+}

package/dist/bindings/validate-api-binding-assignment.d.ts

@@ -0,0 +1,3 @@
+import type { ValidateApiBindingAssignmentInput } from '../types/api-bindings.js';
+/** Validate an actual assignment without fabricating empty bindings for unrelated calls. */
+export declare function validateApiBindingAssignment(input: ValidateApiBindingAssignmentInput): void;

package/dist/bindings/validate-api-binding-assignment.js

@@ -0,0 +1,9 @@
+import { createApiBindingSourceRegistry } from './create-api-binding-source-registry.js';
+import { validateRegisteredApiBinding } from './validate-registered-api-binding.js';
+/** Validate an actual assignment without fabricating empty bindings for unrelated calls. */
+export function validateApiBindingAssignment(input) {
+    validateRegisteredApiBinding({
+        ...input,
+        registry: createApiBindingSourceRegistry(input),
+    });
+}

package/dist/bindings/validate-api-binding-assignments.d.ts

@@ -0,0 +1,2 @@
+import type { ValidateApiBindingAssignmentsInput } from '../types/api-bindings.js';
+export declare function validateApiBindingAssignments({ calls, materials, nativeOutputs, }: ValidateApiBindingAssignmentsInput): void;

package/dist/bindings/validate-api-binding-assignments.js

@@ -0,0 +1,34 @@
+import { createApiBindingSourceRegistry } from './create-api-binding-source-registry.js';
+import { validateRegisteredApiBinding } from './validate-registered-api-binding.js';
+export function validateApiBindingAssignments({ calls, materials, nativeOutputs = [], }) {
+    const registry = createApiBindingSourceRegistry({ materials, nativeOutputs });
+    const byId = registry.api;
+    if (calls.length !== materials.length ||
+        new Set(calls.map((call) => call.callId)).size !== materials.length)
+        throw new Error('binding plan must name every material callId exactly once');
+    const dependencies = new Map();
+    for (const call of calls) {
+        const target = byId.get(call.callId);
+        if (!target)
+            throw new Error(`bindings: unknown target callId ${call.callId}`);
+        const pointers = [];
+        dependencies.set(call.callId, []);
+        for (const binding of call.bindings) {
+            validateRegisteredApiBinding({ callId: call.callId, binding, registry });
+            if (pointers.some((pointer) => pointer === binding.targetPointer ||
+                pointer.startsWith(binding.targetPointer + '/') ||
+                binding.targetPointer.startsWith(pointer + '/')))
+                throw new Error(`bindings overlap at ${call.callId}${binding.targetPointer}`);
+            pointers.push(binding.targetPointer);
+            dependencies.get(call.callId).push(binding.sourceNodeId);
+        }
+    }
+    const pending = new Set(byId.keys());
+    while (pending.size) {
+        const ready = [...pending].filter((id) => dependencies.get(id).every((source) => !pending.has(source)));
+        if (!ready.length)
+            throw new Error('binding dependencies have a cycle');
+        for (const id of ready)
+            pending.delete(id);
+    }
+}

package/dist/bindings/validate-api-binding-gaps.d.ts

@@ -0,0 +1,2 @@
+import type { ValidateApiBindingPlanInput } from '../types/api-bindings.js';
+export declare function validateApiBindingGaps({ plan, materials, }: ValidateApiBindingPlanInput): void;

package/dist/bindings/validate-api-binding-gaps.js

@@ -0,0 +1,10 @@
+import { requestBindingSchemas } from './request-binding-schema.js';
+export function validateApiBindingGaps({ plan, materials, }) {
+    for (const gap of plan.gaps) {
+        const material = materials.find((item) => item.callId === gap.callId);
+        if (!material || !gap.description.trim())
+            throw new Error('binding gap requires a declared callId and description');
+        if (!requestBindingSchemas(material, gap.targetPointer).length)
+            throw new Error(`binding gap ${gap.callId}${gap.targetPointer} is not declared by the request OAS`);
+    }
+}

package/dist/bindings/validate-api-binding-plan.d.ts

@@ -0,0 +1,3 @@
+import type { ValidateApiBindingPlanInput } from '../types/api-bindings.js';
+/** Check identities/contracts without guessing edges or substituting values. */
+export declare function validateApiBindingPlan({ plan, materials, nativeOutputs, }: ValidateApiBindingPlanInput): void;

package/dist/bindings/validate-api-binding-plan.js

@@ -0,0 +1,11 @@
+import { validateApiBindingAssignments } from './validate-api-binding-assignments.js';
+/** Check identities/contracts without guessing edges or substituting values. */
+export function validateApiBindingPlan({ plan, materials, nativeOutputs, }) {
+    if (plan.gaps.length)
+        throw new Error(`API bindings need review: ${JSON.stringify(plan.gaps)}`);
+    validateApiBindingAssignments({
+        calls: plan.calls,
+        materials,
+        nativeOutputs,
+    });
+}

package/dist/bindings/validate-native-output-contracts.d.ts

@@ -0,0 +1,3 @@
+import type { NativeOutputContract } from '../types/node-output.js';
+/** Validate the declaration boundary; the adapter compiles the JSON Schemas. */
+export declare function validateNativeOutputContracts(outputs: NativeOutputContract[]): void;

package/dist/bindings/validate-native-output-contracts.js

@@ -0,0 +1,16 @@
+import { isObject } from '../utils/is-object.js';
+/** Validate the declaration boundary; the adapter compiles the JSON Schemas. */
+export function validateNativeOutputContracts(outputs) {
+    if (!Array.isArray(outputs))
+        throw new Error('nativeOutputs must be an array');
+    const ids = new Set();
+    for (const output of outputs) {
+        if (!output || typeof output.nodeId !== 'string' || !output.nodeId.trim())
+            throw new Error('nativeOutputs.nodeId must be a non-empty string');
+        if (ids.has(output.nodeId))
+            throw new Error('native outputs require unique node IDs');
+        ids.add(output.nodeId);
+        if (typeof output.schema !== 'boolean' && !isObject(output.schema))
+            throw new Error(`nativeOutputs[${output.nodeId}].schema must be a JSON Schema object or boolean`);
+    }
+}

package/dist/bindings/validate-registered-api-binding.d.ts

@@ -0,0 +1,3 @@
+import type { ValidateRegisteredApiBindingInput } from '../types/binding-validation-internal.js';
+/** One declared source-to-input contract, not a whole graph/readiness assertion. */
+export declare function validateRegisteredApiBinding({ callId, binding, registry, }: ValidateRegisteredApiBindingInput): void;

package/dist/bindings/validate-registered-api-binding.js

@@ -0,0 +1,52 @@
+import { pointerTokens } from './json-pointer.js';
+import { requestBindingSchemas } from './request-binding-schema.js';
+import { responseBindingSchemas } from './response-binding-schema.js';
+import { nativeBindingSchemas } from './native-binding-schema.js';
+function declaredTypes(schemas) {
+    const types = new Set();
+    for (const schema of schemas) {
+        if (typeof schema === 'boolean' || schema.type === undefined)
+            return new Set();
+        for (const type of Array.isArray(schema.type) ? schema.type : [schema.type])
+            if (typeof type === 'string')
+                types.add(type);
+        if (schema.nullable === true)
+            types.add('null');
+    }
+    return types;
+}
+/** One declared source-to-input contract, not a whole graph/readiness assertion. */
+export function validateRegisteredApiBinding({ callId, binding, registry, }) {
+    const target = registry.api.get(callId);
+    if (!target)
+        throw new Error(`bindings: unknown target callId ${callId}`);
+    if (!binding || binding.kind !== 'node-output')
+        throw new Error('bindings.kind must be node-output');
+    if (typeof binding.targetPointer !== 'string' ||
+        typeof binding.sourcePointer !== 'string')
+        throw new Error('bindings.targetPointer and sourcePointer must be JSON Pointer strings');
+    if (typeof binding.sourceNodeId !== 'string' || !binding.sourceNodeId.trim())
+        throw new Error('bindings.sourceNodeId must be a non-empty string');
+    pointerTokens(binding.targetPointer);
+    pointerTokens(binding.sourcePointer);
+    const source = registry.api.get(binding.sourceNodeId);
+    const native = registry.native.get(binding.sourceNodeId);
+    if (!source && !native)
+        throw new Error(`bindings: unknown sourceNodeId ${binding.sourceNodeId}`);
+    if (binding.sourceNodeId === callId)
+        throw new Error(`bindings: self-reference ${callId}`);
+    const targets = requestBindingSchemas(target, binding.targetPointer);
+    const sources = native
+        ? nativeBindingSchemas(native, binding.sourcePointer)
+        : responseBindingSchemas(source.operation, binding.sourcePointer);
+    if (!targets.length)
+        throw new Error(`bindings: ${callId}${binding.targetPointer} is not declared by the request OAS`);
+    if (!sources.length)
+        throw new Error(`bindings: ${binding.sourceNodeId}${binding.sourcePointer} is not declared by the ${native ? 'native output contract' : 'response OAS'}`);
+    const from = declaredTypes(sources);
+    const to = declaredTypes(targets);
+    if (from.size &&
+        to.size &&
+        ![...from].some((type) => to.has(type) || (type === 'integer' && to.has('number'))))
+        throw new Error(`bindings: incompatible OAS types ${binding.sourceNodeId}${binding.sourcePointer} -> ${callId}${binding.targetPointer}`);
+}