@openapi-flow/core 0.2.0 → 0.3.0

package/dist/requirements/clarification/revisions/revise-workflow-clarification-answers.js

@@ -0,0 +1,91 @@
+import { createHash } from 'node:crypto';
+import { isDeepStrictEqual } from 'node:util';
+import { workflowClarificationAnswerChangesSchema } from '../../../schemas/workflow-clarification-answer-revision-schema.js';
+import { planningEvidenceTextSchema } from '../../../schemas/planning-evidence-schema.js';
+import { describeWorkflowClarificationAnswerRevision } from './describe-workflow-clarification-answer-revision.js';
+import { resolveWorkflowClarificationReplies } from '../resolve-workflow-clarification-replies.js';
+import { prepareWorkflowDraftClarification } from '../prepare-workflow-draft-clarification.js';
+/** Explicit, atomic answer replacement/reopening. No model call, guessed choice or in-place mutation. */
+export function reviseWorkflowClarificationAnswers(input) {
+    const description = describeWorkflowClarificationAnswerRevision(input.context);
+    if (input.fingerprint !== description.fingerprint)
+        throw new Error('Stale clarification answer revision fingerprint');
+    const messageId = planningEvidenceTextSchema.parse(input.messageId);
+    if (input.context.messages.some((message) => message.id === messageId))
+        throw new Error(`Clarification revision message ID already exists: ${messageId}`);
+    const changes = workflowClarificationAnswerChangesSchema.parse(input.changes);
+    const before = structuredClone(input.context.clarification);
+    const replies = new Map(before.resolution.replies.map((reply) => [reply.questionId, reply]));
+    for (const change of changes) {
+        const questionId = change.kind === 'replace-answer'
+            ? change.reply.questionId
+            : change.questionId;
+        if (!description.replies.some((reply) => reply.questionId === questionId))
+            throw new Error(`Clarification revision requires a currently confirmed answer: ${questionId}`);
+        if (change.kind === 'reopen-question')
+            replies.delete(questionId);
+        else {
+            if (isDeepStrictEqual(replies.get(questionId), change.reply))
+                throw new Error(`Clarification answer change is a no-op: ${questionId}`);
+            replies.set(questionId, change.reply);
+        }
+    }
+    const originalContext = {
+        messages: before.round.sourceMessages,
+        ...(input.context.operations === undefined
+            ? {}
+            : { operations: input.context.operations }),
+        ...(input.context.capabilities === undefined
+            ? {}
+            : { capabilities: input.context.capabilities }),
+        ...(input.context.entrypoint === undefined
+            ? {}
+            : { entrypoint: input.context.entrypoint }),
+    };
+    const after = prepareWorkflowDraftClarification({
+        context: originalContext,
+        round: before.round,
+        resolution: resolveWorkflowClarificationReplies({
+            context: originalContext,
+            round: before.round,
+            replies: [...replies.values()],
+        }),
+    });
+    const supersededAnswerMessageIds = before.answerMessages
+        .filter((message) => !after.answerMessages.some((next) => next.id === message.id))
+        .map((message) => message.id);
+    const message = {
+        id: messageId,
+        text: JSON.stringify({
+            kind: 'explicit-clarification-answer-revision',
+            roundId: before.round.id,
+            fingerprint: description.fingerprint,
+            changes,
+        }),
+    };
+    const body = {
+        fingerprint: description.fingerprint,
+        message,
+        changes,
+        before,
+        after,
+        supersededAnswerMessageIds,
+    };
+    const revision = {
+        id: 'clarification-answer-revision:' +
+            createHash('sha256').update(JSON.stringify(body)).digest('hex'),
+        ...body,
+    };
+    const activeMessages = input.context.messages
+        .filter((item) => !supersededAnswerMessageIds.includes(item.id))
+        .map((item) => ({ ...item }));
+    activeMessages.push(message);
+    for (const receipt of after.answerMessages) {
+        const existing = activeMessages.find((item) => item.id === receipt.id);
+        if (existing && !isDeepStrictEqual(existing, receipt))
+            throw new Error(`Clarification answer evidence conflicts with message ${receipt.id}`);
+        if (!existing)
+            activeMessages.push(structuredClone(receipt));
+    }
+    return { revision, activeMessages };
+}

package/dist/requirements/clarification/revisions/validate-workflow-clarification-answer-revision.d.ts

@@ -0,0 +1,3 @@
+import type { ValidateWorkflowClarificationAnswerRevisionInput } from '../../../types/workflow-clarification-answer-revision.js';
+/** Reconstruct against the trusted pre-change context, not a receipt's claimed original state. */
+export declare function validateWorkflowClarificationAnswerRevision(input: ValidateWorkflowClarificationAnswerRevisionInput): void;

package/dist/requirements/clarification/revisions/validate-workflow-clarification-answer-revision.js

@@ -0,0 +1,15 @@
+import { isDeepStrictEqual } from 'node:util';
+import { reviseWorkflowClarificationAnswers } from './revise-workflow-clarification-answers.js';
+/** Reconstruct against the trusted pre-change context, not a receipt's claimed original state. */
+export function validateWorkflowClarificationAnswerRevision(input) {
+    if (!input.revision || !input.revision.message)
+        throw new Error('Clarification answer revision requires its original receipt');
+    const result = reviseWorkflowClarificationAnswers({
+        context: input.context,
+        fingerprint: input.revision.fingerprint,
+        messageId: input.revision.message.id,
+        changes: input.revision.changes,
+    });
+    if (!isDeepStrictEqual(result.revision, input.revision))
+        throw new Error('Clarification answer revision has modified lineage, facts or evidence');
+}

package/dist/requirements/clarification/validate-workflow-clarification-round.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowClarificationRoundInput } from '../../types/workflow-clarification.js';
+/** Host-owned question data must match the current sources and original shape. */
+export declare function validateWorkflowClarificationRound(input: WorkflowClarificationRoundInput): void;

package/dist/requirements/clarification/validate-workflow-clarification-round.js

@@ -0,0 +1,24 @@
+import { isDeepStrictEqual } from 'node:util';
+import { workflowPlanningContextFingerprint } from '../../planning/evidence/workflow-planning-context-fingerprint.js';
+import { createWorkflowClarificationRound } from './create-workflow-clarification-round.js';
+import { proposalFromClarificationRound } from './proposal-from-clarification-round.js';
+/** Host-owned question data must match the current sources and original shape. */
+export function validateWorkflowClarificationRound(input) {
+    const fingerprint = workflowPlanningContextFingerprint(input.context);
+    if (!input.round || input.round.contextFingerprint !== fingerprint)
+        throw new Error('Clarification round is missing or stale for planning context');
+    let expected;
+    try {
+        expected = createWorkflowClarificationRound({
+            context: input.context,
+            limits: input.round.limits,
+            options: input.round.options,
+            proposal: proposalFromClarificationRound(input.round),
+        });
+    }
+    catch (cause) {
+        throw new Error('Invalid clarification round: questions, sources or settings do not match the contract', { cause });
+    }
+    if (!isDeepStrictEqual(expected, input.round))
+        throw new Error('Clarification round has modified identities, fields or settings');
+}

package/dist/requirements/configuration/read-clarification-question-limits.d.ts

@@ -0,0 +1,3 @@
+import type { ClarificationQuestionLimits } from '../../types/workflow-clarification.js';
+/** Read once at the host boundary; no process.env access or silent defaults. */
+export declare function readClarificationQuestionLimits(environment: Record<string, string | undefined>): ClarificationQuestionLimits;

package/dist/requirements/configuration/read-clarification-question-limits.js

@@ -0,0 +1,18 @@
+import { clarificationQuestionLimitsSchema } from '../../schemas/workflow-clarification-settings-schema.js';
+/** Read once at the host boundary; no process.env access or silent defaults. */
+export function readClarificationQuestionLimits(environment) {
+    function read(name) {
+        const value = environment[name];
+        if (typeof value !== 'string' ||
+            !/^[1-9][0-9]*$/.test(value) ||
+            !Number.isSafeInteger(Number(value)))
+            throw new Error(`${name} must be an explicitly configured positive safe integer`);
+        return Number(value);
+    }
+    return clarificationQuestionLimitsSchema.parse({
+        maxCategories: read('OPENAPI_FLOW_CLARIFY_MAX_CATEGORIES'),
+        maxQuestionsPerCategory: read('OPENAPI_FLOW_CLARIFY_MAX_QUESTIONS_PER_CATEGORY'),
+        maxChoicesPerQuestion: read('OPENAPI_FLOW_CLARIFY_MAX_CHOICES_PER_QUESTION'),
+        maxQuestionsPerRound: read('OPENAPI_FLOW_CLARIFY_MAX_QUESTIONS_PER_ROUND'),
+    });
+}

package/dist/requirements/configuration/resolve-workflow-clarification-options.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowClarificationOptions, ResolvedWorkflowClarificationOptions } from '../../types/workflow-clarification.js';
+/** Product-approved optional feature defaults, not recovery of required data. */
+export declare function resolveWorkflowClarificationOptions(input?: WorkflowClarificationOptions): ResolvedWorkflowClarificationOptions;

package/dist/requirements/configuration/resolve-workflow-clarification-options.js

@@ -0,0 +1,13 @@
+import { workflowClarificationOptionsSchema } from '../../schemas/workflow-clarification-settings-schema.js';
+/** Product-approved optional feature defaults, not recovery of required data. */
+export function resolveWorkflowClarificationOptions(input = {}) {
+    const options = workflowClarificationOptionsSchema.parse(input);
+    return {
+        includeExplanations: options.includeExplanations === undefined
+            ? true
+            : options.includeExplanations,
+        includeSuggestions: options.includeSuggestions === undefined
+            ? true
+            : options.includeSuggestions,
+    };
+}

package/dist/review/suggestions/adopt-workflow-review-suggestion.d.ts

@@ -0,0 +1,3 @@
+import type { AdoptWorkflowReviewSuggestionInput, WorkflowReviewSuggestionAdoption } from '../../types/workflow-review-suggestions.js';
+/** The caller must authenticate the human action. This receipt authorizes no implicit graph edit. */
+export declare function adoptWorkflowReviewSuggestion(input: AdoptWorkflowReviewSuggestionInput): WorkflowReviewSuggestionAdoption;

package/dist/review/suggestions/adopt-workflow-review-suggestion.js

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+import { validateWorkflowReviewSuggestions } from './validate-workflow-review-suggestions.js';
+/** The caller must authenticate the human action. This receipt authorizes no implicit graph edit. */
+export function adoptWorkflowReviewSuggestion(input) {
+    validateWorkflowReviewSuggestions(input);
+    const messageId = z
+        .string()
+        .refine((id) => id.trim().length > 0)
+        .parse(input.messageId);
+    if (input.context.messages.some((message) => message.id === messageId))
+        throw new Error(`Review suggestion adoption message id already exists: ${messageId}`);
+    const suggestion = input.review.suggestions.find((item) => item.id === input.suggestionId);
+    if (!suggestion)
+        throw new Error(`Review suggestion adoption references unknown suggestion ${input.suggestionId}`);
+    return {
+        reviewId: input.review.id,
+        suggestionId: suggestion.id,
+        boundaryKey: input.review.boundaryKey,
+        suggestion: structuredClone(suggestion),
+        message: {
+            id: messageId,
+            text: JSON.stringify({
+                kind: 'user-adopted-workflow-review-suggestion',
+                reviewId: input.review.id,
+                suggestionId: suggestion.id,
+                boundaryKey: input.review.boundaryKey,
+                intent: suggestion.kind,
+                ...(suggestion.kind === 'answer-question'
+                    ? { questionIds: suggestion.questionIds }
+                    : {}),
+                adoptedText: suggestion.text,
+            }),
+        },
+    };
+}

package/dist/review/suggestions/create-workflow-review-suggestions.d.ts

@@ -0,0 +1,2 @@
+import type { CreateWorkflowReviewSuggestionsInput, WorkflowReviewSuggestions } from '../../types/workflow-review-suggestions.js';
+export declare function createWorkflowReviewSuggestions(input: CreateWorkflowReviewSuggestionsInput): WorkflowReviewSuggestions;

package/dist/review/suggestions/create-workflow-review-suggestions.js

@@ -0,0 +1,51 @@
+import { createHash } from 'node:crypto';
+import { isDeepStrictEqual } from 'node:util';
+import { describeWorkflowReviewSuggestions } from './describe-workflow-review-suggestions.js';
+import { createWorkflowReviewSuggestionsProposalSchema } from '../../schemas/create-workflow-review-suggestions-proposal-schema.js';
+import { workflowReviewSuggestionEvidenceSchema } from '../../schemas/workflow-review-suggestion-evidence-schema.js';
+import { validateDescribedWorkflowPlanningEvidence } from '../../planning/evidence/validate-workflow-planning-evidence.js';
+export function createWorkflowReviewSuggestions(input) {
+    const description = describeWorkflowReviewSuggestions(input);
+    const proposal = createWorkflowReviewSuggestionsProposalSchema(description, workflowReviewSuggestionEvidenceSchema).parse(input.proposal);
+    if (!isDeepStrictEqual(proposal, input.proposal))
+        throw new Error('Review suggestions must validate without defaults, coercion or transformation');
+    for (const suggestion of proposal.suggestions) {
+        const keys = suggestion.sources.map((source) => JSON.stringify(source));
+        if (new Set(keys).size !== keys.length)
+            throw new Error('Review suggestion evidence must not repeat identical sources');
+        for (const source of suggestion.sources) {
+            if (source.kind === 'review-question') {
+                if (!description.boundary.questions.some((question) => question.id === source.questionId))
+                    throw new Error(`Review suggestion cites unknown current question ${source.questionId}`);
+            }
+            else
+                validateDescribedWorkflowPlanningEvidence(description.context, [
+                    source,
+                ]);
+        }
+        if (suggestion.kind === 'answer-question' &&
+            suggestion.questionIds.some((id) => !suggestion.sources.some((source) => source.kind === 'review-question' && source.questionId === id)))
+            throw new Error('An answer suggestion must cite every actual question it proposes to answer');
+    }
+    const id = 'workflow-review:' +
+        createHash('sha256')
+            .update(JSON.stringify([description.fingerprint, proposal]))
+            .digest('hex');
+    return {
+        id,
+        fingerprint: description.fingerprint,
+        boundaryKey: description.boundary.key,
+        target: {
+            kind: description.boundary.kind,
+            revision: description.boundary.revision,
+            questions: structuredClone(description.boundary.questions),
+            data: structuredClone(description.boundary.data),
+        },
+        limits: description.limits,
+        options: description.options,
+        suggestions: proposal.suggestions.map((suggestion, index) => ({
+            ...suggestion,
+            id: `${id}:suggestion:${index + 1}`,
+        })),
+    };
+}

package/dist/review/suggestions/describe-workflow-review-suggestions.d.ts

@@ -0,0 +1,2 @@
+import type { WorkflowReviewSuggestionsInput, WorkflowReviewSuggestionsDescription } from '../../types/workflow-review-suggestions.js';
+export declare function describeWorkflowReviewSuggestions(input: WorkflowReviewSuggestionsInput): WorkflowReviewSuggestionsDescription;

package/dist/review/suggestions/describe-workflow-review-suggestions.js

@@ -0,0 +1,16 @@
+import { createHash } from 'node:crypto';
+import { workflowReviewBoundarySchema, workflowReviewSuggestionLimitsSchema, workflowReviewSuggestionOptionsSchema, } from '../../schemas/workflow-review-suggestion-settings-schema.js';
+import { describeWorkflowPlanningContext } from '../../planning/evidence/describe-workflow-planning-context.js';
+export function describeWorkflowReviewSuggestions(input) {
+    const context = describeWorkflowPlanningContext(input.context);
+    const boundary = workflowReviewBoundarySchema.parse(input.boundary);
+    const limits = workflowReviewSuggestionLimitsSchema.parse(input.limits);
+    const options = workflowReviewSuggestionOptionsSchema.parse(input.options === undefined ? {} : input.options);
+    const described = { context, boundary, limits, options };
+    return {
+        ...described,
+        fingerprint: createHash('sha256')
+            .update(JSON.stringify(described))
+            .digest('hex'),
+    };
+}

package/dist/review/suggestions/read-workflow-review-suggestion-limits.d.ts

@@ -0,0 +1,2 @@
+import type { WorkflowReviewSuggestionEnvironment, WorkflowReviewSuggestionLimits } from '../../types/workflow-review-suggestions.js';
+export declare function readWorkflowReviewSuggestionLimits(environment: WorkflowReviewSuggestionEnvironment): WorkflowReviewSuggestionLimits;

package/dist/review/suggestions/read-workflow-review-suggestion-limits.js

@@ -0,0 +1,10 @@
+import { workflowReviewSuggestionLimitsSchema } from '../../schemas/workflow-review-suggestion-settings-schema.js';
+export function readWorkflowReviewSuggestionLimits(environment) {
+    const name = 'OPENAPI_FLOW_REVIEW_MAX_SUGGESTIONS';
+    const value = environment[name];
+    if (typeof value !== 'string' || !/^[1-9]\d*$/.test(value))
+        throw new Error(`${name} must explicitly provide a positive integer`);
+    return workflowReviewSuggestionLimitsSchema.parse({
+        maxSuggestions: Number(value),
+    });
+}

package/dist/review/suggestions/validate-workflow-review-suggestions.d.ts

@@ -0,0 +1,2 @@
+import type { WorkflowReviewSuggestionsValidationInput } from '../../types/workflow-review-suggestions.js';
+export declare function validateWorkflowReviewSuggestions(input: WorkflowReviewSuggestionsValidationInput): void;

package/dist/review/suggestions/validate-workflow-review-suggestions.js

@@ -0,0 +1,20 @@
+import { isDeepStrictEqual } from 'node:util';
+import { createWorkflowReviewSuggestions } from './create-workflow-review-suggestions.js';
+import { workflowReviewSuggestionsRecordSchema } from '../../schemas/workflow-review-suggestions-record-schema.js';
+export function validateWorkflowReviewSuggestions(input) {
+    if (!input.review || !Array.isArray(input.review.suggestions))
+        throw new Error('Review suggestions require an original host-owned review record');
+    workflowReviewSuggestionsRecordSchema.parse(input.review);
+    const expected = createWorkflowReviewSuggestions({
+        ...input,
+        proposal: {
+            suggestions: input.review.suggestions.map(({ id, ...suggestion }) => {
+                if (!id.trim())
+                    throw new Error('Review suggestion id must be non-empty');
+                return suggestion;
+            }),
+        },
+    });
+    if (!isDeepStrictEqual(expected, input.review))
+        throw new Error('Review suggestions are stale or have modified identities, text, sources or settings');
+}

package/dist/runtime-api.d.ts

@@ -4,3 +4,6 @@ export { serializeFormBody } from './openapi/request/serialize-form-body.js';
 export { UnsupportedOperationError } from './openapi/common/unsupported-operation-error.js';
 export { apiResponseValidationValue } from './openapi/response/api-response-validation-value.js';
 export { pointerValue } from './bindings/json-pointer.js';
+export { listMissingRequestedApiInputs } from './arguments/clarification/list-missing-requested-api-inputs.js';
+export { assignRequestInputValue } from './bindings/assign-request-input-value.js';
+export { materializeNativeRuntimeParameters } from './inputs/native/materialize-native-runtime-parameters.js';

package/dist/runtime-api.js

@@ -5,3 +5,6 @@ export { serializeFormBody } from './openapi/request/serialize-form-body.js';
 export { UnsupportedOperationError } from './openapi/common/unsupported-operation-error.js';
 export { apiResponseValidationValue } from './openapi/response/api-response-validation-value.js';
 export { pointerValue } from './bindings/json-pointer.js';
+export { listMissingRequestedApiInputs } from './arguments/clarification/list-missing-requested-api-inputs.js';
+export { assignRequestInputValue } from './bindings/assign-request-input-value.js';
+export { materializeNativeRuntimeParameters } from './inputs/native/materialize-native-runtime-parameters.js';

package/dist/schemas/api-binding-planning-schema.d.ts

@@ -0,0 +1,67 @@
+import { z } from 'zod';
+import type { ApiBindingPlanningMaterial } from '../types/api-binding-planning.js';
+import type { NativeOutputContract } from '../types/node-output.js';
+import type { ApiParameterObject, ApiServerObject } from '../types/api-operation.js';
+export declare const apiBindingPlanningIdentitySchema: z.ZodObject<{
+    scenario: z.ZodString;
+}, z.core.$strict>;
+/** Validate the resolved-contract container, not a second implementation of OpenAPI validation. */
+export declare const apiBindingPlanningOperationSchema: z.ZodObject<{
+    key: z.ZodObject<{
+        documentId: z.ZodString;
+        snapshotId: z.ZodString;
+        operationRef: z.ZodString;
+    }, z.core.$strict>;
+    openapiVersion: z.ZodString;
+    source: z.ZodLiteral<"paths">;
+    method: z.ZodString;
+    path: z.ZodString;
+    operation: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    pathItem: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    effective: z.ZodObject<{
+        parameters: z.ZodArray<z.ZodCustom<ApiParameterObject, ApiParameterObject>>;
+        security: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+        securitySchemes: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        servers: z.ZodOptional<z.ZodArray<z.ZodCustom<ApiServerObject, ApiServerObject>>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const apiBindingMaterialRoleSchema: z.ZodObject<{
+    purpose: z.ZodOptional<z.ZodString>;
+    requestMediaType: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const apiBindingCallReasonsSchema: z.ZodArray<z.ZodObject<{
+    callId: z.ZodString;
+    reason: z.ZodString;
+}, z.core.$strict>>;
+/** Nested OAS and native data are compared to a newly derived exact source snapshot. */
+export declare const apiBindingPlanningContextSchema: z.ZodObject<{
+    scenario: z.ZodString;
+    materials: z.ZodArray<z.ZodCustom<ApiBindingPlanningMaterial, ApiBindingPlanningMaterial>>;
+    nativeOutputs: z.ZodOptional<z.ZodArray<z.ZodCustom<NativeOutputContract, NativeOutputContract>>>;
+}, z.core.$strict>;
+export declare const apiBindingPlanningRecordSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"proposed-bindings">;
+    calls: z.ZodArray<z.ZodObject<{
+        callId: z.ZodString;
+        bindings: z.ZodArray<z.ZodObject<{
+            kind: z.ZodLiteral<"node-output">;
+            targetPointer: z.ZodString;
+            sourceNodeId: z.ZodString;
+            sourcePointer: z.ZodString;
+        }, z.core.$strict>>;
+        reason: z.ZodString;
+    }, z.core.$strict>>;
+    gaps: z.ZodArray<z.ZodObject<{
+        callId: z.ZodString;
+        targetPointer: z.ZodString;
+        description: z.ZodString;
+    }, z.core.$strict>>;
+    evidence: z.ZodObject<{
+        kind: z.ZodLiteral<"supplied-binding-contracts">;
+        context: z.ZodObject<{
+            scenario: z.ZodString;
+            materials: z.ZodArray<z.ZodCustom<ApiBindingPlanningMaterial, ApiBindingPlanningMaterial>>;
+            nativeOutputs: z.ZodOptional<z.ZodArray<z.ZodCustom<NativeOutputContract, NativeOutputContract>>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+}, z.core.$strict>;

package/dist/schemas/api-binding-planning-schema.js

@@ -0,0 +1,58 @@
+import { z } from 'zod';
+import { apiOperationKeySchema } from './api-operation-key-schema.js';
+import { planningEvidenceTextSchema } from './planning-evidence-schema.js';
+export const apiBindingPlanningIdentitySchema = z.strictObject({
+    scenario: planningEvidenceTextSchema,
+});
+/** Validate the resolved-contract container, not a second implementation of OpenAPI validation. */
+export const apiBindingPlanningOperationSchema = z.object({
+    key: apiOperationKeySchema,
+    openapiVersion: planningEvidenceTextSchema,
+    source: z.literal('paths'),
+    method: planningEvidenceTextSchema,
+    path: z.string(),
+    operation: z.record(z.string(), z.unknown()),
+    pathItem: z.record(z.string(), z.unknown()),
+    effective: z.object({
+        parameters: z.array(z.custom()),
+        security: z.array(z.record(z.string(), z.array(z.string()))),
+        securitySchemes: z.record(z.string(), z.unknown()),
+        servers: z.array(z.custom()).optional(),
+    }),
+});
+export const apiBindingMaterialRoleSchema = z.strictObject({
+    purpose: planningEvidenceTextSchema.optional(),
+    requestMediaType: planningEvidenceTextSchema.optional(),
+});
+export const apiBindingCallReasonsSchema = z.array(z.strictObject({
+    callId: planningEvidenceTextSchema,
+    reason: planningEvidenceTextSchema,
+}));
+/** Nested OAS and native data are compared to a newly derived exact source snapshot. */
+export const apiBindingPlanningContextSchema = z.strictObject({
+    scenario: planningEvidenceTextSchema,
+    materials: z.array(z.custom()),
+    nativeOutputs: z.array(z.custom()).optional(),
+});
+export const apiBindingPlanningRecordSchema = z.strictObject({
+    kind: z.literal('proposed-bindings'),
+    calls: z.array(z.strictObject({
+        callId: planningEvidenceTextSchema,
+        bindings: z.array(z.strictObject({
+            kind: z.literal('node-output'),
+            targetPointer: z.string().min(1),
+            sourceNodeId: planningEvidenceTextSchema,
+            sourcePointer: z.string(),
+        })),
+        reason: planningEvidenceTextSchema,
+    })),
+    gaps: z.array(z.strictObject({
+        callId: planningEvidenceTextSchema,
+        targetPointer: z.string().min(1),
+        description: planningEvidenceTextSchema,
+    })),
+    evidence: z.strictObject({
+        kind: z.literal('supplied-binding-contracts'),
+        context: apiBindingPlanningContextSchema,
+    }),
+});

package/dist/schemas/api-input-answer-extraction-schema.d.ts

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+export declare const apiInputRequirementSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        "missing-input": "missing-input";
+        "requested-input": "requested-input";
+    }>;
+    requestedInputs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    id: z.ZodString;
+    callId: z.ZodString;
+    operation: z.ZodObject<{
+        documentId: z.ZodString;
+        snapshotId: z.ZodString;
+        operationRef: z.ZodString;
+    }, z.core.$strict>;
+    targetPointer: z.ZodString;
+    schema: z.ZodUnion<readonly [z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodJSONSchema>]>;
+    openapiVersion: z.ZodString;
+    operationSummary: z.ZodOptional<z.ZodString>;
+    parameterDescription: z.ZodOptional<z.ZodString>;
+    message: z.ZodString;
+}, z.core.$strict>;
+export declare const apiInputAnswerContextSchema: z.ZodObject<{
+    reply: z.ZodString;
+    requirements: z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            "missing-input": "missing-input";
+            "requested-input": "requested-input";
+        }>;
+        requestedInputs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        id: z.ZodString;
+        callId: z.ZodString;
+        operation: z.ZodObject<{
+            documentId: z.ZodString;
+            snapshotId: z.ZodString;
+            operationRef: z.ZodString;
+        }, z.core.$strict>;
+        targetPointer: z.ZodString;
+        schema: z.ZodUnion<readonly [z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodJSONSchema>]>;
+        openapiVersion: z.ZodString;
+        operationSummary: z.ZodOptional<z.ZodString>;
+        parameterDescription: z.ZodOptional<z.ZodString>;
+        message: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const apiInputAnswerSourceSchema: z.ZodObject<{
+    sourceFormat: z.ZodEnum<{
+        text: "text";
+        json: "json";
+    }>;
+    sourceText: z.ZodString;
+    requirementId: z.ZodString;
+}, z.core.$strict>;
+export declare const apiInputAnswerSourcesSchema: z.ZodArray<z.ZodObject<{
+    sourceFormat: z.ZodEnum<{
+        text: "text";
+        json: "json";
+    }>;
+    sourceText: z.ZodString;
+    requirementId: z.ZodString;
+}, z.core.$strict>>;
+export declare const apiInputAnswerExtractionDecisionSchema: z.ZodObject<{
+    reason: z.ZodString;
+    answers: z.ZodArray<z.ZodObject<{
+        sourceFormat: z.ZodEnum<{
+            text: "text";
+            json: "json";
+        }>;
+        sourceText: z.ZodString;
+        requirementId: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;

package/dist/schemas/api-input-answer-extraction-schema.js

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import { apiOperationKeySchema } from './api-operation-key-schema.js';
+import { apiInputLiteralSourceSchema } from './api-input-literal-source-schema.js';
+import { requestedApiInputsSchema } from './requested-api-inputs-schema.js';
+export const apiInputRequirementSchema = z.strictObject({
+    kind: z.enum(['missing-input', 'requested-input']),
+    requestedInputs: requestedApiInputsSchema.optional(),
+    id: z.string().min(1),
+    callId: z.string().min(1),
+    operation: apiOperationKeySchema,
+    targetPointer: z.string().min(1),
+    schema: z.union([z.boolean(), z.record(z.string(), z.json())]),
+    openapiVersion: z.string().min(1),
+    operationSummary: z.string().optional(),
+    parameterDescription: z.string().optional(),
+    message: z.string().min(1),
+});
+export const apiInputAnswerContextSchema = z.strictObject({
+    reply: z.string(),
+    requirements: z.array(apiInputRequirementSchema),
+});
+export const apiInputAnswerSourceSchema = apiInputLiteralSourceSchema.extend({
+    requirementId: z.string().min(1),
+});
+export const apiInputAnswerSourcesSchema = z.array(apiInputAnswerSourceSchema);
+export const apiInputAnswerExtractionDecisionSchema = z.strictObject({
+    reason: z.string().min(1),
+    answers: z.array(apiInputAnswerSourceSchema.extend({ reason: z.string().min(1) })),
+});

package/dist/schemas/api-input-literal-source-schema.d.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+export declare const apiInputLiteralSourceSchema: z.ZodObject<{
+    sourceFormat: z.ZodEnum<{
+        text: "text";
+        json: "json";
+    }>;
+    sourceText: z.ZodString;
+}, z.core.$strict>;

package/dist/schemas/api-input-literal-source-schema.js

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+export const apiInputLiteralSourceSchema = z.strictObject({
+    sourceFormat: z
+        .enum(['text', 'json'])
+        .describe('Use json for a quoted JSON string and include both original quotes in sourceText; json also parses explicit numbers, booleans, null, objects and arrays. Use text only for an unquoted verbatim string. Never use text for a quoted token unless the quote characters themselves are part of the requested string value. No coercion or quote repair.'),
+    sourceText: z
+        .string()
+        .min(1)
+        .describe('Exact complete substring from the selected original user message. For a quoted JSON string preserve its original quotes and escapes and use sourceFormat json. Never add/remove quotes, invent text or use a schema default.'),
+});

package/dist/schemas/api-input-source-selection-schema.d.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+import type { ApiInputSourceCatalog, ApiInputJsonSourceSelection, ApiInputTextSourceSelection } from '../types/api-input-source-selection.js';
+export declare const apiInputSourceSelectionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"json">;
+    candidateId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"text">;
+    startTokenId: z.ZodString;
+    endTokenId: z.ZodString;
+}, z.core.$strict>], "kind">;
+export declare const apiInputAnswerSelectionsSchema: z.ZodArray<z.ZodObject<{
+    requirementId: z.ZodString;
+    source: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"json">;
+        candidateId: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"text">;
+        startTokenId: z.ZodString;
+        endTokenId: z.ZodString;
+    }, z.core.$strict>], "kind">;
+}, z.core.$strict>>;
+/** Only code-owned IDs can be selected; strings and values are input-only. */
+export declare function createApiInputSourceSelectionSchema(catalog: ApiInputSourceCatalog): z.ZodUnion<z.ZodType<ApiInputJsonSourceSelection | ApiInputTextSourceSelection, unknown, z.core.$ZodTypeInternals<ApiInputJsonSourceSelection | ApiInputTextSourceSelection, unknown>>[]>;