@openapi-flow/core 0.1.0 → 0.3.0

package/dist/arguments/clarification/validate-api-input-answers.js

@@ -0,0 +1,65 @@
+import { apiInputAnswersSchema } from '../../schemas/confirmed-api-input-schema.js';
+import { apiOperationKeyEquals } from '../../openapi/catalog/api-operation-key-equals.js';
+import { createOasValueValidator } from '../../openapi/common/create-oas-value-validator.js';
+import { listMissingRequestedApiInputs } from './list-missing-requested-api-inputs.js';
+export function validateApiInputAnswers(input) {
+    if (!Array.isArray(input.requirements) || !Array.isArray(input.operations))
+        throw new Error('validateApiInputAnswers.requirements and operations must be arrays');
+    const parsed = apiInputAnswersSchema.safeParse(input.answers);
+    if (!parsed.success)
+        return {
+            status: 'invalid-answer',
+            issues: parsed.error.issues.map((issue) => ({
+                requirementId: '',
+                message: issue.message,
+            })),
+        };
+    const issues = [];
+    const confirmedInputs = [];
+    const seen = new Set();
+    for (const answer of parsed.data) {
+        const requirement = input.requirements.find((item) => item.id === answer.requirementId);
+        if (!requirement || seen.has(answer.requirementId)) {
+            issues.push({
+                requirementId: answer.requirementId,
+                message: 'Unknown or duplicate requirementId',
+            });
+            continue;
+        }
+        seen.add(answer.requirementId);
+        if (!input.operations.some((operation) => apiOperationKeyEquals(operation, requirement.operation)))
+            throw new Error(`Input requirement ${requirement.id} belongs to a stale OAS snapshot`);
+        const checked = createOasValueValidator(requirement.schema, requirement.openapiVersion.startsWith('3.0.')
+            ? 'openapi-3.0'
+            : 'draft-2020-12', `answer ${requirement.targetPointer}`).validate(answer.value);
+        if (!checked.valid) {
+            issues.push({
+                requirementId: requirement.id,
+                message: checked.errors.map((error) => error.message).join('; '),
+            });
+            continue;
+        }
+        const missing = listMissingRequestedApiInputs({
+            source: `Answer ${requirement.id}`,
+            rootPointer: requirement.targetPointer,
+            value: answer.value,
+            requestedInputs: requirement.requestedInputs,
+        });
+        if (missing.length) {
+            issues.push({
+                requirementId: requirement.id,
+                message: `Answer omits scenario-requested inputs: ${missing.join(', ')}`,
+            });
+            continue;
+        }
+        confirmedInputs.push({
+            callId: requirement.callId,
+            operation: structuredClone(requirement.operation),
+            targetPointer: requirement.targetPointer,
+            value: structuredClone(answer.value),
+        });
+    }
+    return issues.length
+        ? { status: 'invalid-answer', issues }
+        : { status: 'accepted', confirmedInputs };
+}

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

@@ -0,0 +1,3 @@
+import type { CreateApiLiteralGenerationRecordInput, ApiLiteralGenerationRecord } from '../../types/api-literal-generation.js';
+/** Only literal proposals are attributed here; confirmed inputs and bindings remain code-owned. */
+export declare function createApiLiteralGenerationRecord(input: CreateApiLiteralGenerationRecordInput): ApiLiteralGenerationRecord;

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/media/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/media/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/media/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/media/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/media/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/media/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/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/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/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;
+}