@openapi-flow/core 0.2.0 → 0.3.0

package/dist/arguments/generation/create-api-literal-generation-record.js

@@ -0,0 +1,45 @@
+import { planningEvidenceTextSchema } from '../../schemas/planning-evidence-schema.js';
+import { describeApiLiteralGeneration } from './describe-api-literal-generation.js';
+/** Only literal proposals are attributed here; confirmed inputs and bindings remain code-owned. */
+export function createApiLiteralGenerationRecord(input) {
+    const { input: snapshot, contract, context, } = describeApiLiteralGeneration(input);
+    if (!contract.hasLiteralInputs) {
+        if (input.proposal !== undefined || input.reason !== undefined)
+            throw new Error('Literal generation proposal and reason must be absent when no literal inputs remain');
+        return {
+            kind: 'not-needed',
+            callId: snapshot.callId,
+            operation: structuredClone(snapshot.operation.key),
+        };
+    }
+    if (input.proposal === undefined)
+        throw new Error('Literal generation proposal is required when literal inputs remain');
+    const proposal = contract.schema.parse(input.proposal);
+    const reason = planningEvidenceTextSchema.parse(input.reason);
+    return {
+        kind: 'proposed-literals',
+        callId: snapshot.callId,
+        operation: structuredClone(snapshot.operation.key),
+        proposedValues: structuredClone(proposal.values),
+        explanation: {
+            reason,
+            evidence: [
+                {
+                    kind: 'scenario',
+                    text: context.scenario,
+                    ...(context.purpose === undefined
+                        ? {}
+                        : { purpose: context.purpose }),
+                },
+                {
+                    kind: 'literal-input-contract',
+                    operation: context.operation,
+                    schema: context.literalInputSchema,
+                    ...(context.requestMediaType === undefined
+                        ? {}
+                        : { requestMediaType: context.requestMediaType }),
+                },
+            ],
+        },
+    };
+}

package/dist/arguments/generation/describe-api-literal-generation.d.ts

@@ -0,0 +1,3 @@
+import type { ApiLiteralGenerationInput, ApiLiteralGenerationDescription } from '../../types/api-literal-generation.js';
+/** Snapshot only declared data fields, never the caller's model or unrelated stage metadata. */
+export declare function describeApiLiteralGeneration(input: ApiLiteralGenerationInput): ApiLiteralGenerationDescription;

package/dist/arguments/generation/describe-api-literal-generation.js

@@ -0,0 +1,50 @@
+import { apiLiteralGenerationContextSchema, apiLiteralGenerationIdentitySchema, } from '../../schemas/api-literal-generation-schema.js';
+import { createApiArgumentGenerationContract } from '../../schemas/create-api-argument-generation-contract.js';
+import { apiOperationKeySchema } from '../../schemas/api-operation-key-schema.js';
+/** Snapshot only declared data fields, never the caller's model or unrelated stage metadata. */
+export function describeApiLiteralGeneration(input) {
+    const { callId, scenario, purpose } = apiLiteralGenerationIdentitySchema.parse({
+        callId: input.callId,
+        scenario: input.scenario,
+        purpose: input.purpose,
+    });
+    if (!input.operation ||
+        !apiOperationKeySchema.safeParse(input.operation.key).success)
+        throw new Error('literal generation operation.key is missing or invalid');
+    if (!Array.isArray(input.bindings))
+        throw new Error('arguments.bindings must be an array');
+    const snapshot = {
+        callId,
+        scenario,
+        operation: structuredClone(input.operation),
+        bindings: structuredClone(input.bindings),
+        ...(purpose === undefined ? {} : { purpose }),
+        ...(input.requestMediaType === undefined
+            ? {}
+            : { requestMediaType: input.requestMediaType }),
+        ...(input.confirmedInputs === undefined
+            ? {}
+            : { confirmedInputs: structuredClone(input.confirmedInputs) }),
+    };
+    const contract = createApiArgumentGenerationContract(snapshot);
+    const context = apiLiteralGenerationContextSchema.parse({
+        scenario,
+        ...(snapshot.purpose === undefined ? {} : { purpose: snapshot.purpose }),
+        operation: {
+            key: snapshot.operation.key,
+            method: snapshot.operation.method,
+            path: snapshot.operation.path,
+            ...(snapshot.operation.operation.summary === undefined
+                ? {}
+                : { summary: snapshot.operation.operation.summary }),
+            ...(snapshot.operation.operation.description === undefined
+                ? {}
+                : { description: snapshot.operation.operation.description }),
+        },
+        literalInputSchema: contract.literalInputSchema,
+        ...(snapshot.requestMediaType === undefined
+            ? {}
+            : { requestMediaType: snapshot.requestMediaType }),
+    });
+    return { input: snapshot, contract, context: structuredClone(context) };
+}

package/dist/arguments/generation/validate-api-literal-generation-record.d.ts

@@ -0,0 +1,3 @@
+import type { ValidateApiLiteralGenerationRecordInput } from '../../types/api-literal-generation.js';
+/** Use the original generation snapshot, not later confirmed-input state. */
+export declare function validateApiLiteralGenerationRecord(input: ValidateApiLiteralGenerationRecordInput): void;

package/dist/arguments/generation/validate-api-literal-generation-record.js

@@ -0,0 +1,20 @@
+import { isDeepStrictEqual } from 'node:util';
+import { createApiLiteralGenerationRecordSchema } from '../../schemas/api-literal-generation-schema.js';
+import { describeApiLiteralGeneration } from './describe-api-literal-generation.js';
+import { createApiLiteralGenerationRecord } from './create-api-literal-generation-record.js';
+/** Use the original generation snapshot, not later confirmed-input state. */
+export function validateApiLiteralGenerationRecord(input) {
+    const { input: snapshot, contract } = describeApiLiteralGeneration(input);
+    const record = createApiLiteralGenerationRecordSchema(contract.valuesSchema).parse(input.record);
+    const expected = createApiLiteralGenerationRecord({
+        ...snapshot,
+        ...(record.kind === 'not-needed'
+            ? {}
+            : {
+                proposal: { values: record.proposedValues },
+                reason: record.explanation.reason,
+            }),
+    });
+    if (!isDeepStrictEqual(record, expected))
+        throw new Error('Literal generation record differs from its original scenario, role, OAS projection or input ownership');
+}

package/dist/arguments/list-api-request-input-roots.d.ts

@@ -0,0 +1,3 @@
+import type { JsonObject } from '../types/openapi.js';
+/** Roots of the existing full request schema; dynamic descendants remain legal and are checked against the original OAS. */
+export declare function listApiRequestInputRoots(schema: JsonObject): string[];

package/dist/arguments/list-api-request-input-roots.js

@@ -0,0 +1,9 @@
+import { object } from '../openapi/common/parse-spec-utils.js';
+/** Roots of the existing full request schema; dynamic descendants remain legal and are checked against the original OAS. */
+export function listApiRequestInputRoots(schema) {
+    return Object.entries(object(schema.properties, 'requestSchema.properties')).flatMap(([location, schema]) => {
+        if (location === 'body')
+            return ['/body'];
+        return Object.keys(object(object(schema, `requestSchema.${location}`).properties, `requestSchema.${location}.properties`)).map((name) => `/${location}/${name.replaceAll('~', '~0').replaceAll('/', '~1')}`);
+    });
+}

package/dist/arguments/media/create-api-request-media-type-decision.d.ts

@@ -0,0 +1,3 @@
+import type { ApiRequestMediaTypeDecision, CreateApiRequestMediaTypeDecisionInput } from '../../types/api-request-media-type-decision.js';
+/** Resolves a declared choice or the approved explicit-null default, never invalid output. */
+export declare function createApiRequestMediaTypeDecision(input: CreateApiRequestMediaTypeDecisionInput): ApiRequestMediaTypeDecision;

package/dist/arguments/media/create-api-request-media-type-decision.js

@@ -0,0 +1,73 @@
+import { apiRequestMediaTypeAssessmentProposalSchema } from '../../schemas/api-request-media-type-decision-schema.js';
+import { describeApiRequestMediaTypeContext } from './describe-api-request-media-type-context.js';
+import { selectDefaultApiRequestMediaType } from './select-default-api-request-media-type.js';
+import { object } from '../../openapi/common/parse-spec-utils.js';
+/** Resolves a declared choice or the approved explicit-null default, never invalid output. */
+export function createApiRequestMediaTypeDecision(input) {
+    const context = describeApiRequestMediaTypeContext(input);
+    const fields = {
+        operation: context.operation.key,
+        declaredMediaTypes: context.mediaTypes,
+    };
+    if (context.mediaTypes.length < 2) {
+        if (input.assessment !== undefined)
+            throw new Error('Request media assessment must be absent when code owns the zero/one-format decision');
+        return context.operation.requestBody === undefined
+            ? { ...fields, kind: 'no-request-body' }
+            : {
+                ...fields,
+                kind: 'single-declared-format',
+                requestMediaType: context.mediaTypes[0],
+            };
+    }
+    if (input.assessment === undefined)
+        throw new Error(`${context.operation.key.operationRef} requires an explicit request media assessment for multiple formats`);
+    const assessment = apiRequestMediaTypeAssessmentProposalSchema.parse(input.assessment);
+    const requestBody = object(context.operation.requestBody, `${context.operation.key.operationRef}.requestBody`);
+    if (assessment.requestMediaType !== null &&
+        !context.mediaTypes.includes(assessment.requestMediaType))
+        throw new Error(`${context.operation.key.operationRef} assessment.requestMediaType is not a declared requestBody.content key`);
+    const explanation = assessment.explanation === undefined
+        ? {}
+        : {
+            explanation: {
+                reason: assessment.explanation.reason,
+                evidence: [
+                    {
+                        kind: 'scenario',
+                        text: context.scenario,
+                        ...(context.purpose === undefined
+                            ? {}
+                            : { purpose: context.purpose }),
+                    },
+                    {
+                        kind: 'oas-request-body',
+                        operation: structuredClone(context.operation.key),
+                        pointer: '/requestBody',
+                        value: requestBody,
+                    },
+                ],
+            },
+        };
+    if (assessment.requestMediaType === null) {
+        const selected = selectDefaultApiRequestMediaType(input.operation);
+        if (selected === undefined)
+            throw new Error('Declared request body did not produce a default media type');
+        return {
+            ...fields,
+            kind: 'documented-default',
+            requestMediaType: selected,
+            policy: 'json-form-concrete-wildcard-code-point',
+            assessment: { requestMediaType: null, ...explanation },
+        };
+    }
+    return {
+        ...fields,
+        kind: 'model-selection',
+        requestMediaType: assessment.requestMediaType,
+        assessment: {
+            requestMediaType: assessment.requestMediaType,
+            ...explanation,
+        },
+    };
+}

package/dist/arguments/media/describe-api-request-media-type-context.d.ts

@@ -0,0 +1,3 @@
+import type { ApiRequestMediaTypeContext, ApiRequestMediaTypeContextInput } from '../../types/api-request-media-type-decision.js';
+/** A copy of exactly the selected contract material supplied to the format model. */
+export declare function describeApiRequestMediaTypeContext(input: ApiRequestMediaTypeContextInput): ApiRequestMediaTypeContext;

package/dist/arguments/media/describe-api-request-media-type-context.js

@@ -0,0 +1,28 @@
+import { apiRequestMediaTypeContextSchema } from '../../schemas/api-request-media-type-decision-schema.js';
+import { listApiRequestMediaTypes } from './list-api-request-media-types.js';
+import { object } from '../../openapi/common/parse-spec-utils.js';
+/** A copy of exactly the selected contract material supplied to the format model. */
+export function describeApiRequestMediaTypeContext(input) {
+    const operation = input.operation;
+    const mediaTypes = listApiRequestMediaTypes(operation);
+    const requestBody = operation.operation.requestBody;
+    const context = apiRequestMediaTypeContextSchema.parse({
+        scenario: input.scenario,
+        ...(input.purpose === undefined ? {} : { purpose: input.purpose }),
+        operation: {
+            key: operation.key,
+            method: operation.method,
+            path: operation.path,
+            ...(requestBody === undefined
+                ? {}
+                : {
+                    requestBody: object(requestBody, `${operation.key.operationRef}.requestBody`),
+                }),
+        },
+        mediaTypes,
+    });
+    if (requestBody !== undefined && mediaTypes.length === 0)
+        throw new Error(`${operation.key.operationRef}.requestBody.content has no request media type`);
+    // Arbitrary nested OAS schema data must be copied too, not retained through z.unknown().
+    return structuredClone(context);
+}

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

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

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

@@ -1,4 +1,4 @@
-import { object } from '../openapi/common/parse-spec-utils.js';
+import { object } from '../../openapi/common/parse-spec-utils.js';
 export function listApiRequestMediaTypes(operation) {
     if (operation.operation.requestBody === undefined)
         return [];

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

@@ -1,3 +1,3 @@
-import type { ApiOperationContract } from '../types/api-operation.js';
+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/media/validate-api-request-media-type-decision.d.ts

@@ -0,0 +1,3 @@
+import type { ValidateApiRequestMediaTypeDecisionInput } from '../../types/api-request-media-type-decision.js';
+/** Verify recorded origin, declared choice/default policy and exact original sources. */
+export declare function validateApiRequestMediaTypeDecision(input: ValidateApiRequestMediaTypeDecisionInput): void;

package/dist/arguments/media/validate-api-request-media-type-decision.js

@@ -0,0 +1,28 @@
+import { isDeepStrictEqual } from 'node:util';
+import { apiRequestMediaTypeDecisionSchema } from '../../schemas/api-request-media-type-decision-schema.js';
+import { createApiRequestMediaTypeDecision } from './create-api-request-media-type-decision.js';
+/** Verify recorded origin, declared choice/default policy and exact original sources. */
+export function validateApiRequestMediaTypeDecision(input) {
+    const decision = apiRequestMediaTypeDecisionSchema.parse(input.decision);
+    const expected = createApiRequestMediaTypeDecision({
+        operation: input.operation,
+        scenario: input.scenario,
+        ...(input.purpose === undefined ? {} : { purpose: input.purpose }),
+        ...('assessment' in decision
+            ? {
+                assessment: {
+                    requestMediaType: decision.assessment.requestMediaType,
+                    ...(decision.assessment.explanation === undefined
+                        ? {}
+                        : {
+                            explanation: {
+                                reason: decision.assessment.explanation.reason,
+                            },
+                        }),
+                },
+            }
+            : {}),
+    });
+    if (!isDeepStrictEqual(decision, expected))
+        throw new Error('Request media decision differs from the original OAS, scenario, assessment or documented default policy');
+}

package/dist/arguments/sources/describe-api-input-sources.d.ts

@@ -0,0 +1,3 @@
+import type { ApiInputSourceCatalog } from '../../types/api-input-source-selection.js';
+/** Enumerate original literal spans and unquoted boundaries, never proposed values. */
+export declare function describeApiInputSources(reply: string): ApiInputSourceCatalog;

package/dist/arguments/sources/describe-api-input-sources.js

@@ -0,0 +1,83 @@
+import { parseTree } from 'jsonc-parser';
+import { scanProtectedApiInputLiterals } from './scan-protected-api-input-literals.js';
+/** Enumerate original literal spans and unquoted boundaries, never proposed values. */
+export function describeApiInputSources(reply) {
+    if (typeof reply !== 'string')
+        throw new Error('API input sources require reply to be a string');
+    const protectedLiterals = scanProtectedApiInputLiterals(reply);
+    const literals = new Map(protectedLiterals.map((literal) => [literal.offset, literal]));
+    const candidates = [...protectedLiterals];
+    const stack = [];
+    const catalog = { json: [], text: [] };
+    let textTokens = [];
+    const flushText = () => {
+        if (textTokens.length)
+            catalog.text.push({
+                id: `text:${textTokens[0].offset}`,
+                tokens: textTokens,
+            });
+        textTokens = [];
+    };
+    for (let offset = 0; offset < reply.length;) {
+        const literal = literals.get(offset);
+        if (literal?.quoted) {
+            flushText();
+            offset += literal.length;
+            continue;
+        }
+        const character = String.fromCodePoint(reply.codePointAt(offset));
+        const length = literal?.length ?? character.length;
+        if (!literal && (character === '{' || character === '['))
+            stack.push({ offset, length: 1 });
+        if (!literal && (character === '}' || character === ']')) {
+            const start = stack.pop();
+            if (start !== undefined &&
+                ((reply[start.offset] === '{' && character === '}') ||
+                    (reply[start.offset] === '[' && character === ']')))
+                candidates.push({
+                    offset: start.offset,
+                    length: offset + 1 - start.offset,
+                });
+            else
+                stack.length = 0;
+        }
+        textTokens.push({
+            id: `text:${offset}:${length}`,
+            text: reply.slice(offset, offset + length),
+            offset,
+            length,
+        });
+        offset += length;
+    }
+    flushText();
+    for (const candidate of candidates.sort((a, b) => a.offset - b.offset || b.length - a.length)) {
+        const text = reply.slice(candidate.offset, candidate.offset + candidate.length);
+        // A malformed numeric run or quoted token is protected, not a valid JSON
+        // choice. Absence is not repaired into a smaller literal or a different type.
+        const errors = [];
+        const parsed = parseTree(text, errors, {
+            allowTrailingComma: false,
+            disallowComments: true,
+        });
+        if (!parsed || errors.length)
+            continue;
+        const pending = [parsed];
+        let finite = true;
+        while (pending.length) {
+            const node = pending.pop();
+            if (node.type === 'number' && !Number.isFinite(node.value))
+                finite = false;
+            if (node.children)
+                pending.push(...node.children);
+        }
+        if (!finite)
+            continue;
+        catalog.json.push({
+            id: `json:${candidate.offset}:${candidate.length}`,
+            text,
+            offset: candidate.offset,
+            length: candidate.length,
+        });
+    }
+    return catalog;
+}

package/dist/arguments/sources/locate-complete-api-input-source.d.ts

@@ -0,0 +1,3 @@
+import type { ApiInputAnswerSourceLocation } from '../../types/api-input-answer-extraction.js';
+/** The scanner checks token boundaries only. It never parses or repairs a value. */
+export declare function locateCompleteApiInputSource(reply: string, sourceText: string): ApiInputAnswerSourceLocation[];

package/dist/arguments/sources/locate-complete-api-input-source.js

@@ -0,0 +1,17 @@
+import { scanProtectedApiInputLiterals } from './scan-protected-api-input-literals.js';
+/** The scanner checks token boundaries only. It never parses or repairs a value. */
+export function locateCompleteApiInputSource(reply, sourceText) {
+    const literals = scanProtectedApiInputLiterals(reply);
+    const occurrences = [];
+    for (let offset = reply.indexOf(sourceText); offset !== -1; offset = reply.indexOf(sourceText, offset + 1)) {
+        const end = offset + sourceText.length;
+        if (literals.every((literal) => {
+            const literalEnd = literal.offset + literal.length;
+            return (end <= literal.offset ||
+                offset >= literalEnd ||
+                (offset <= literal.offset && end >= literalEnd));
+        }))
+            occurrences.push({ offset, length: sourceText.length });
+    }
+    return occurrences;
+}

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

@@ -0,0 +1,3 @@
+import type { ReadApiInputLiteralSourceInput, ReadApiInputLiteralSourceResult } from '../../types/api-input-literal-source.js';
+/** Exact source occurrence and literal parsing, never semantic conversion or repair. */
+export declare function readApiInputLiteralSource(input: ReadApiInputLiteralSourceInput): ReadApiInputLiteralSourceResult;

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

@@ -0,0 +1,20 @@
+import { locateCompleteApiInputSource } from './locate-complete-api-input-source.js';
+/** Exact source occurrence and literal parsing, never semantic conversion or repair. */
+export function readApiInputLiteralSource(input) {
+    const occurrences = locateCompleteApiInputSource(input.text, input.sourceText);
+    if (!occurrences.length)
+        throw new Error(`${input.label} sourceText is absent or is not a complete literal in the user reply`);
+    if (input.sourceFormat === 'text')
+        return { value: input.sourceText, occurrences };
+    try {
+        const value = JSON.parse(input.sourceText, (_key, part) => {
+            if (typeof part === 'number' && !Number.isFinite(part))
+                throw new Error('JSON number is outside the finite JavaScript number range');
+            return part;
+        });
+        return { value, occurrences };
+    }
+    catch (cause) {
+        throw new Error(`${input.label} sourceText is not a complete JSON literal`, { cause });
+    }
+}

package/dist/arguments/sources/scan-protected-api-input-literals.d.ts

@@ -0,0 +1,3 @@
+import type { ProtectedApiInputLiteral } from '../../types/api-input-source-selection.js';
+/** Lexical protection is independent of whether the complete token is valid JSON. */
+export declare function scanProtectedApiInputLiterals(reply: string): ProtectedApiInputLiteral[];

package/dist/arguments/sources/scan-protected-api-input-literals.js

@@ -0,0 +1,37 @@
+import { createScanner } from 'jsonc-parser';
+/** Lexical protection is independent of whether the complete token is valid JSON. */
+export function scanProtectedApiInputLiterals(reply) {
+    const scanner = createScanner(reply);
+    const literals = [];
+    while (scanner.getPosition() < reply.length) {
+        scanner.scan();
+        const offset = scanner.getTokenOffset();
+        const length = scanner.getTokenLength();
+        const token = reply.slice(offset, offset + length);
+        // Protect complete number-like runs, including malformed JSON forms, so a
+        // selected substring cannot silently drop a sign, leading zero or exponent.
+        // A decimal point needs following digits; a prose full stop is not numeric.
+        // Only token spans change here. The original selected text is parsed later.
+        const numeric = /^[+-]?(?:\d+(?:\.\d+)?|\.\d+)(?:[eE][+-]?\d*)?/u.exec(reply.slice(offset));
+        if (numeric) {
+            literals.push({ offset, length: numeric[0].length, quoted: false });
+            scanner.setPosition(offset + numeric[0].length);
+            continue;
+        }
+        // jsonc-parser treats a keyword followed by prose punctuation as one unknown
+        // token. Preserve the JSON keyword boundary without matching ASCII names
+        // such as falsehood or null_value.
+        const keyword = /^(?:true|false|null)(?![A-Za-z0-9_$])/u.exec(reply.slice(offset));
+        if (keyword) {
+            literals.push({ offset, length: keyword[0].length, quoted: false });
+            scanner.setPosition(offset + keyword[0].length);
+            continue;
+        }
+        if (token.startsWith('"') ||
+            token === 'true' ||
+            token === 'false' ||
+            token === 'null')
+            literals.push({ offset, length, quoted: token.startsWith('"') });
+    }
+    return literals;
+}

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