@openapi-flow/core 0.3.9 → 0.3.11

package/dist/draft/edits/inputs/resolve-workflow-draft-api-input-edits.js

@@ -6,6 +6,8 @@ import { applyWorkflowDraftApiInputEdits } from '../values/apply-workflow-draft-
 import { validateApiArguments } from '../../../arguments/validate-api-arguments.js';
 import { orderWorkflowDraftValueEdits } from '../values/order-workflow-draft-value-edits.js';
 import { verifyApiInputLiteralSource } from '../../../arguments/sources/verify-api-input-literal-source.js';
+import { describeWorkflowDraftApiInputEditEnumChoices } from './describe-workflow-draft-api-input-edit-enum-choices.js';
+import { verifyWorkflowDraftApiEnumSelection } from '../enum/verify-workflow-draft-api-enum-selection.js';
 /** Exact-source validation is deterministic; it is not semantic entailment proof. */
 export function resolveWorkflowDraftApiInputEdits(input) {
     const output = createWorkflowDraftApiInputEditValuesSchema(input).parse(input.output);
@@ -19,12 +21,28 @@ export function resolveWorkflowDraftApiInputEdits(input) {
     const sets = [];
     const removals = [];
     const pendingTargets = [];
+    const enumSelections = [];
+    const { candidates } = describeWorkflowDraftApiInputEditEnumChoices(input);
     for (const target of input.contract.targets) {
         if (target.kind === 'remove') {
             removals.push({ kind: 'remove', pointer: target.pointer });
             continue;
         }
         const answer = output.values[target.id];
+        if (answer.status === 'oas-enum') {
+            const selection = verifyWorkflowDraftApiEnumSelection({
+                selection: answer.selection,
+                candidates: candidates.filter((candidate) => candidate.targetPointer === target.pointer),
+                messages: described.messages,
+            });
+            sets.push({
+                kind: 'set',
+                pointer: target.pointer,
+                value: structuredClone(selection.value),
+            });
+            enumSelections.push(selection);
+            continue;
+        }
         if (answer.explanation)
             validateWorkflowPlanningEvidence({
                 context: { messages: described.messages },
@@ -60,6 +78,7 @@ export function resolveWorkflowDraftApiInputEdits(input) {
             values: output,
             pendingTargets,
             ...human,
+            ...(enumSelections.length ? { enumSelections } : {}),
         };
     // Targets address the original value. Set before deletion; remove higher array
     // indices first so one deletion does not retarget another original index.
@@ -80,6 +99,7 @@ export function resolveWorkflowDraftApiInputEdits(input) {
         contractId: input.contract.id,
         values: output,
         ...human,
+        ...(enumSelections.length ? { enumSelections } : {}),
         resolution: {
             stepId: input.stepId,
             kind: 'api-inputs',

package/dist/openapi/common/create-oas-value-validation-cache.d.ts

@@ -0,0 +1,3 @@
+import type { OasValueValidationCache, OasValueValidationCacheOptions } from '../../types/oas-value-validation.js';
+/** Cache compilation only; every supplied value still runs the original validator. */
+export declare function createOasValueValidationCache(options: OasValueValidationCacheOptions): OasValueValidationCache;

package/dist/openapi/common/create-oas-value-validation-cache.js

@@ -0,0 +1,46 @@
+import { Buffer } from 'node:buffer';
+import { isDeepStrictEqual } from 'node:util';
+/** Cache compilation only; every supplied value still runs the original validator. */
+export function createOasValueValidationCache(options) {
+    for (const name of ['maximumEntries', 'maximumRetainedSchemaBytes'])
+        if (!Number.isSafeInteger(options[name]) || options[name] <= 0)
+            throw new Error(`OAS validator cache.${name} must be a positive safe integer`);
+    const { maximumEntries, maximumRetainedSchemaBytes } = options;
+    const entries = new Map();
+    let retainedSchemaBytes = 0;
+    return {
+        getOrCreate: (schema, dialect, compile) => {
+            const key = JSON.stringify([dialect, schema]);
+            const existing = entries.get(key);
+            // Serialization alone is not identity: undefined and non-JSON values can collide.
+            if (existing !== undefined &&
+                isDeepStrictEqual(existing.schema, schema)) {
+                entries.delete(key);
+                entries.set(key, existing);
+                return existing.validate;
+            }
+            // Neither returned schemas nor caller-owned objects can mutate the compiled resource.
+            const snapshot = structuredClone(schema);
+            const validate = compile(snapshot);
+            const bytes = Buffer.byteLength(key);
+            // Large schemas remain supported; only their optional retention is bounded.
+            if (bytes > maximumRetainedSchemaBytes)
+                return validate;
+            if (existing !== undefined) {
+                entries.delete(key);
+                retainedSchemaBytes -= existing.bytes;
+            }
+            while (entries.size >= maximumEntries ||
+                retainedSchemaBytes + bytes > maximumRetainedSchemaBytes) {
+                const oldest = entries.entries().next();
+                if (oldest.done)
+                    throw new Error('OAS validator cache retained-size invariant is invalid');
+                entries.delete(oldest.value[0]);
+                retainedSchemaBytes -= oldest.value[1].bytes;
+            }
+            entries.set(key, { schema: snapshot, validate, bytes });
+            retainedSchemaBytes += bytes;
+            return validate;
+        },
+    };
+}

package/dist/openapi/common/create-oas-value-validator.js

@@ -2,6 +2,12 @@ import { createHash } from 'node:crypto';
 import { createValidator } from '@scalar/json-schema-validator';
 import { normalizeOasValueSchema } from './normalize-oas-value-schema.js';
 import { isObject } from '../../utils/is-object.js';
+import { createOasValueValidationCache } from './create-oas-value-validation-cache.js';
+// Internal retention budgets, not limits on accepted OAS contracts or request values.
+const compiledValidators = createOasValueValidationCache({
+    maximumEntries: 64,
+    maximumRetainedSchemaBytes: 1024 * 1024,
+});
 export function createOasValueValidator(input, dialect, source) {
     if (typeof input !== 'boolean' && !isObject(input))
         throw new Error(`${source} must be an OAS schema object or boolean`);
@@ -24,7 +30,11 @@ export function createOasValueValidator(input, dialect, source) {
     };
     let validate;
     try {
-        validate = createValidator(schema);
+        validate = compiledValidators.getOrCreate(schema, dialect, (snapshot) => {
+            const compiled = createValidator(snapshot);
+            // Scalar parses string documents as YAML; encode actual string values first.
+            return (value) => compiled(typeof value === 'string' ? JSON.stringify(value) : value);
+        });
     }
     catch (error) {
         throw new Error(`${source} cannot compile its OAS value schema`, {
@@ -33,7 +43,6 @@ export function createOasValueValidator(input, dialect, source) {
     }
     return {
         schema,
-        // Scalar parses string documents as YAML; encode actual string values first.
-        validate: (value) => validate(typeof value === 'string' ? JSON.stringify(value) : value),
+        validate,
     };
 }

package/dist/public-api.d.ts

@@ -32,8 +32,14 @@ export { resolveApiInputSourceSelections } from './arguments/clarification/extra
 export { createApiInputSourceSelectionSchema } from './schemas/api-input-source-selection-schema.js';
 export { captureApiInputAnswerContext } from './arguments/clarification/extraction/capture-api-input-answer-context.js';
 export { resolveApiInputAnswerSources } from './arguments/clarification/extraction/resolve-api-input-answer-sources.js';
+export { resolveApiInputAnswerInterpretations } from './arguments/clarification/extraction/resolve-api-input-answer-interpretations.js';
+export { describeApiInputEnumAnswerChoices } from './arguments/enum/describe-api-input-enum-answer-choices.js';
+export type * from './types/api-input-enum-answers.js';
 export { createApiInputAnswerExtractionRecord } from './arguments/clarification/extraction/create-api-input-answer-extraction-record.js';
 export { validateApiInputAnswerExtractionRecord } from './arguments/clarification/extraction/validate-api-input-answer-extraction-record.js';
+export { validateApiInputAnswerAnalysis } from './arguments/clarification/extraction/validate-api-input-answer-analysis.js';
+export { describeWorkflowDraftApiInputEditAnswerRequirements } from './draft/edits/inputs/describe-workflow-draft-api-input-edit-answer-requirements.js';
+export { resolveWorkflowDraftApiInputEditReply } from './draft/edits/inputs/resolve-workflow-draft-api-input-edit-reply.js';
 export { applyConfirmedApiInputs } from './arguments/clarification/apply-confirmed-api-inputs.js';
 export { inspectApiArgumentRequirements } from './arguments/clarification/inspect-api-argument-requirements.js';
 export { validateApiInputAnswers } from './arguments/clarification/validate-api-input-answers.js';
@@ -166,6 +172,11 @@ export type * from './types/workflow-draft-native-dependencies.js';
 export { createWorkflowDraftNativeDependenciesSchema } from './schemas/workflow-draft-native-dependencies-schema.js';
 export { describeWorkflowDraftNativeDependencies, resolveWorkflowDraftNativeDependencies, validateWorkflowDraftNativeDependencies, validateWorkflowDraftNativeDependencyResolutions, } from './draft/edits/native/additions/resolve-workflow-draft-native-dependencies.js';
 export type * from './types/workflow-draft-api-call-planning.js';
+export type * from './types/workflow-draft-api-enum-selection.js';
+export type { ApiInputEnumCandidate } from './types/api-input-enum.js';
+export { describeWorkflowDraftApiEnumChoices } from './draft/edits/api/describe-workflow-draft-api-enum-choices.js';
+export { createWorkflowDraftApiEnumSelectionSchema } from './schemas/workflow-draft-api-enum-selection-schema.js';
+export { describeWorkflowDraftApiInputEditEnumChoices } from './draft/edits/inputs/describe-workflow-draft-api-input-edit-enum-choices.js';
 export type * from './types/workflow-draft-api-binding-intent.js';
 export { describeWorkflowDraftApiBindingIntent } from './draft/edits/api/describe-workflow-draft-api-binding-intent.js';
 export { createWorkflowDraftApiBindingIntentSchema } from './schemas/workflow-draft-api-binding-intent-schema.js';

package/dist/public-api.js

@@ -22,8 +22,13 @@ export { resolveApiInputSourceSelections } from './arguments/clarification/extra
 export { createApiInputSourceSelectionSchema } from './schemas/api-input-source-selection-schema.js';
 export { captureApiInputAnswerContext } from './arguments/clarification/extraction/capture-api-input-answer-context.js';
 export { resolveApiInputAnswerSources } from './arguments/clarification/extraction/resolve-api-input-answer-sources.js';
+export { resolveApiInputAnswerInterpretations } from './arguments/clarification/extraction/resolve-api-input-answer-interpretations.js';
+export { describeApiInputEnumAnswerChoices } from './arguments/enum/describe-api-input-enum-answer-choices.js';
 export { createApiInputAnswerExtractionRecord } from './arguments/clarification/extraction/create-api-input-answer-extraction-record.js';
 export { validateApiInputAnswerExtractionRecord } from './arguments/clarification/extraction/validate-api-input-answer-extraction-record.js';
+export { validateApiInputAnswerAnalysis } from './arguments/clarification/extraction/validate-api-input-answer-analysis.js';
+export { describeWorkflowDraftApiInputEditAnswerRequirements } from './draft/edits/inputs/describe-workflow-draft-api-input-edit-answer-requirements.js';
+export { resolveWorkflowDraftApiInputEditReply } from './draft/edits/inputs/resolve-workflow-draft-api-input-edit-reply.js';
 export { applyConfirmedApiInputs } from './arguments/clarification/apply-confirmed-api-inputs.js';
 export { inspectApiArgumentRequirements } from './arguments/clarification/inspect-api-argument-requirements.js';
 export { validateApiInputAnswers } from './arguments/clarification/validate-api-input-answers.js';
@@ -124,6 +129,9 @@ export { resolveWorkflowDraftNativeNodeParameterOwnership, validateWorkflowDraft
 export { resolveWorkflowDraftNativeNodeAddition } from './draft/edits/native/additions/resolve-workflow-draft-native-node-addition.js';
 export { createWorkflowDraftNativeDependenciesSchema } from './schemas/workflow-draft-native-dependencies-schema.js';
 export { describeWorkflowDraftNativeDependencies, resolveWorkflowDraftNativeDependencies, validateWorkflowDraftNativeDependencies, validateWorkflowDraftNativeDependencyResolutions, } from './draft/edits/native/additions/resolve-workflow-draft-native-dependencies.js';
+export { describeWorkflowDraftApiEnumChoices } from './draft/edits/api/describe-workflow-draft-api-enum-choices.js';
+export { createWorkflowDraftApiEnumSelectionSchema } from './schemas/workflow-draft-api-enum-selection-schema.js';
+export { describeWorkflowDraftApiInputEditEnumChoices } from './draft/edits/inputs/describe-workflow-draft-api-input-edit-enum-choices.js';
 export { describeWorkflowDraftApiBindingIntent } from './draft/edits/api/describe-workflow-draft-api-binding-intent.js';
 export { createWorkflowDraftApiBindingIntentSchema } from './schemas/workflow-draft-api-binding-intent-schema.js';
 export { resolveWorkflowDraftApiBindingIntent } from './draft/edits/api/resolve-workflow-draft-api-binding-intent.js';

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

@@ -15,6 +15,7 @@ export declare const apiInputRequirementSchema: z.ZodObject<{
     targetPointer: z.ZodString;
     schema: z.ZodUnion<readonly [z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodJSONSchema>]>;
     openapiVersion: z.ZodString;
+    schemaDialect: z.ZodOptional<z.ZodLiteral<"draft-2020-12">>;
     operationSummary: z.ZodOptional<z.ZodString>;
     parameterDescription: z.ZodOptional<z.ZodString>;
     message: z.ZodString;
@@ -37,10 +38,12 @@ export declare const apiInputAnswerContextSchema: z.ZodObject<{
         targetPointer: z.ZodString;
         schema: z.ZodUnion<readonly [z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodJSONSchema>]>;
         openapiVersion: z.ZodString;
+        schemaDialect: z.ZodOptional<z.ZodLiteral<"draft-2020-12">>;
         operationSummary: z.ZodOptional<z.ZodString>;
         parameterDescription: z.ZodOptional<z.ZodString>;
         message: z.ZodString;
     }, z.core.$strict>>;
+    selectOasEnums: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 export declare const apiInputAnswerSourceSchema: z.ZodObject<{
     sourceFormat: z.ZodEnum<{
@@ -69,4 +72,16 @@ export declare const apiInputAnswerExtractionDecisionSchema: z.ZodObject<{
         requirementId: z.ZodString;
         reason: z.ZodString;
     }, z.core.$strict>>;
+    enumSelections: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        requirementId: z.ZodString;
+        candidateId: z.ZodString;
+        intent: z.ZodObject<{
+            sourceFormat: z.ZodEnum<{
+                text: "text";
+                json: "json";
+            }>;
+            sourceText: z.ZodString;
+        }, z.core.$strict>;
+        reason: z.ZodString;
+    }, z.core.$strict>>>;
 }, z.core.$strict>;

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

@@ -2,6 +2,7 @@ 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';
+import { apiInputEnumAnswerSelectionsSchema } from './api-input-enum-answer-selection-schema.js';
 export const apiInputRequirementSchema = z.strictObject({
     kind: z.enum(['missing-input', 'requested-input']),
     requestedInputs: requestedApiInputsSchema.optional(),
@@ -11,6 +12,7 @@ export const apiInputRequirementSchema = z.strictObject({
     targetPointer: z.string().min(1),
     schema: z.union([z.boolean(), z.record(z.string(), z.json())]),
     openapiVersion: z.string().min(1),
+    schemaDialect: z.literal('draft-2020-12').optional(),
     operationSummary: z.string().optional(),
     parameterDescription: z.string().optional(),
     message: z.string().min(1),
@@ -18,6 +20,7 @@ export const apiInputRequirementSchema = z.strictObject({
 export const apiInputAnswerContextSchema = z.strictObject({
     reply: z.string(),
     requirements: z.array(apiInputRequirementSchema),
+    selectOasEnums: z.boolean().optional(),
 });
 export const apiInputAnswerSourceSchema = apiInputLiteralSourceSchema.extend({
     requirementId: z.string().min(1),
@@ -26,4 +29,5 @@ 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) })),
+    enumSelections: apiInputEnumAnswerSelectionsSchema.optional(),
 });

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

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+export declare const apiInputEnumAnswerSelectionSchema: z.ZodObject<{
+    requirementId: z.ZodString;
+    candidateId: z.ZodString;
+    intent: z.ZodObject<{
+        sourceFormat: z.ZodEnum<{
+            text: "text";
+            json: "json";
+        }>;
+        sourceText: z.ZodString;
+    }, z.core.$strict>;
+    reason: z.ZodString;
+}, z.core.$strict>;
+export declare const apiInputEnumAnswerSelectionsSchema: z.ZodArray<z.ZodObject<{
+    requirementId: z.ZodString;
+    candidateId: z.ZodString;
+    intent: z.ZodObject<{
+        sourceFormat: z.ZodEnum<{
+            text: "text";
+            json: "json";
+        }>;
+        sourceText: z.ZodString;
+    }, z.core.$strict>;
+    reason: z.ZodString;
+}, z.core.$strict>>;

package/dist/schemas/api-input-enum-answer-selection-schema.js

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+import { apiInputLiteralSourceSchema } from './api-input-literal-source-schema.js';
+export const apiInputEnumAnswerSelectionSchema = z.strictObject({
+    requirementId: z.string().min(1),
+    candidateId: z.string().min(1),
+    intent: apiInputLiteralSourceSchema,
+    reason: z
+        .string()
+        .refine((value) => value.trim().length > 0, 'An enum choice requires a reason'),
+});
+export const apiInputEnumAnswerSelectionsSchema = z.array(apiInputEnumAnswerSelectionSchema);

package/dist/schemas/create-workflow-draft-api-input-edit-values-schema.js

@@ -1,12 +1,13 @@
 import { z } from 'zod';
-import { validateWorkflowDraftApiInputEditContract } from '../draft/edits/inputs/validate-workflow-draft-api-input-edit-contract.js';
 import { createWorkflowDraftEditMessageFields } from './workflow-draft-edit-message-fields.js';
 import { createWorkflowDraftApiInputEditTargetValueSchema } from './create-workflow-draft-api-input-edit-target-value-schema.js';
 import { createSchemaResourceContext } from '../bindings/resources/create-schema-resource-context.js';
 import { apiInputLiteralSourceSchema } from './api-input-literal-source-schema.js';
+import { describeWorkflowDraftApiInputEditEnumChoices } from '../draft/edits/inputs/describe-workflow-draft-api-input-edit-enum-choices.js';
+import { createWorkflowDraftApiEnumChoiceSchema } from './workflow-draft-api-enum-choice-schema.js';
 /** Only selected set-values are model-owned; per-field OAS assertions stay intact. */
 export function createWorkflowDraftApiInputEditValuesSchema(input, messageSchema) {
-    validateWorkflowDraftApiInputEditContract(input);
+    const { candidates } = describeWorkflowDraftApiInputEditEnumChoices(input);
     const evidence = createWorkflowDraftEditMessageFields(input.requestMessageIds, input.plan.options.includeExplanations, messageSchema);
     const resources = createSchemaResourceContext(input.contract.schemaResource);
     const wire = resources.bundleStaticProjections(Object.fromEntries(input.contract.targets
@@ -31,6 +32,14 @@ export function createWorkflowDraftApiInputEditValuesSchema(input, messageSchema
                     status: z.literal('needs-input'),
                     ...evidence.fields,
                 }),
+                ...(candidates.some((candidate) => candidate.targetPointer === target.pointer)
+                    ? [
+                        z.strictObject({
+                            status: z.literal('oas-enum'),
+                            selection: createWorkflowDraftApiEnumChoiceSchema(candidates.filter((candidate) => candidate.targetPointer === target.pointer), input.requestMessageIds),
+                        }),
+                    ]
+                    : []),
             ]),
         ]))),
     })

package/dist/schemas/workflow-draft-api-enum-choice-schema.d.ts

@@ -0,0 +1,5 @@
+import { z } from 'zod';
+import type { WorkflowDraftApiEnumSelection } from '../types/workflow-draft-api-enum-selection.js';
+import type { ApiInputEnumCandidate } from '../types/api-input-enum.js';
+/** No generated value or schema field exists in a semantic enum choice. */
+export declare function createWorkflowDraftApiEnumChoiceSchema(candidates: ApiInputEnumCandidate[], messageIds: string[]): z.ZodType<WorkflowDraftApiEnumSelection>;

package/dist/schemas/workflow-draft-api-enum-choice-schema.js

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+/** No generated value or schema field exists in a semantic enum choice. */
+export function createWorkflowDraftApiEnumChoiceSchema(candidates, messageIds) {
+    if (!messageIds.length)
+        throw new Error('API enum choice requires original human message IDs');
+    if (!candidates.length)
+        return z.never();
+    return z.strictObject({
+        candidateId: z
+            .enum(candidates.map((candidate) => candidate.id))
+            .describe('Choose an offered original-OAS enum candidate ID. Code copies its original value; never generate a request value.'),
+        messageId: z
+            .enum(messageIds)
+            .describe('Actual supplied human message expressing this enum intent, not an OAS quotation.'),
+        sourceText: z
+            .string()
+            .min(1)
+            .describe('Exact original human text expressing the intended meaning; it need not contain the enum literal.'),
+        reason: z
+            .string()
+            .min(1)
+            .refine((value) => value.trim().length > 0)
+            .describe('Brief user-facing reason why this OAS choice matches the cited request. Not private chain-of-thought.'),
+    });
+}

package/dist/schemas/workflow-draft-api-enum-selection-schema.d.ts

@@ -0,0 +1,4 @@
+import { z } from 'zod';
+import type { WorkflowDraftApiEnumChoicesInput, WorkflowDraftApiEnumSelectionProposal } from '../types/workflow-draft-api-enum-selection.js';
+/** The model selects IDs and explains intent; there is deliberately no value field. */
+export declare function createWorkflowDraftApiEnumSelectionSchema(input: WorkflowDraftApiEnumChoicesInput): z.ZodType<WorkflowDraftApiEnumSelectionProposal>;

package/dist/schemas/workflow-draft-api-enum-selection-schema.js

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+import { describeWorkflowDraftApiEnumChoices } from '../draft/edits/api/describe-workflow-draft-api-enum-choices.js';
+import { createWorkflowDraftApiEnumChoiceSchema } from './workflow-draft-api-enum-choice-schema.js';
+/** The model selects IDs and explains intent; there is deliberately no value field. */
+export function createWorkflowDraftApiEnumSelectionSchema(input) {
+    const { candidates } = describeWorkflowDraftApiEnumChoices(input);
+    if (!candidates.length)
+        return z.strictObject({ selections: z.array(z.never()).max(0) });
+    return z.strictObject({
+        selections: z
+            .array(createWorkflowDraftApiEnumChoiceSchema(candidates, input.context.messages.map((message) => message.id)))
+            .describe('Select only when the human request identifies the meaning. Empty means no supported interpretation; keep the existing input question. Never select a default just because it exists.'),
+    });
+}

package/dist/schemas/workflow-draft-api-input-edit-proposal-schema.js

@@ -6,7 +6,9 @@ export function createWorkflowDraftApiInputEditProposalSchema(messageIds, includ
     return z.strictObject({
         targets: z
             .array(z.strictObject({
-            kind: z.enum(['set', 'remove']),
+            kind: z
+                .enum(['set', 'remove'])
+                .describe('set replaces a requested field, even when its new value is unknown and must be asked later. remove requires explicit withdrawal/deletion; asking which replacement to use is not removal.'),
             pointer: z
                 .string()
                 .min(1)

package/dist/types/api-clarification.d.ts

@@ -23,6 +23,8 @@ export interface ApiInputRequirement {
     targetPointer: string;
     schema: JsonObject | boolean;
     openapiVersion: string;
+    /** Present only when schema is an already-normalized OAS projection. Omission means raw source-version rules. */
+    schemaDialect?: 'draft-2020-12';
     operationSummary?: string;
     parameterDescription?: string;
     message: string;

package/dist/types/api-input-answer-extraction.d.ts

@@ -1,7 +1,10 @@
 import type { ApiInputAnswer, ApiInputRequirement } from './api-clarification.js';
+import type { ApiInputEnumAnswerSelection, ResolvedApiInputAnswerInterpretations } from './api-input-enum-answers.js';
 export interface ApiInputAnswerContext {
     reply: string;
     requirements: ApiInputRequirement[];
+    /** Allow semantic selection of original OAS enum values, never arbitrary generation. */
+    selectOasEnums?: boolean;
 }
 export interface ApiInputAnswerSource {
     requirementId: string;
@@ -30,12 +33,13 @@ export interface ResolvedApiInputAnswerSources {
 export interface ApiInputAnswerExtractionDecision {
     reason: string;
     answers: ExplainedApiInputAnswerSource[];
+    enumSelections?: ApiInputEnumAnswerSelection[];
 }
 export interface ApiInputAnswerExtractionRecord {
     kind: 'model-extracted-api-input-answers';
     decision: ApiInputAnswerExtractionDecision;
     evidence: ApiInputAnswerContext;
-    verification: ResolvedApiInputAnswerSources;
+    verification: ResolvedApiInputAnswerInterpretations;
 }
 export interface CreateApiInputAnswerExtractionRecordInput extends ApiInputAnswerContext {
     decision: ApiInputAnswerExtractionDecision;
@@ -43,7 +47,10 @@ export interface CreateApiInputAnswerExtractionRecordInput extends ApiInputAnswe
 export interface ValidateApiInputAnswerExtractionRecordInput extends ApiInputAnswerContext {
     record: ApiInputAnswerExtractionRecord;
 }
-export interface ApiInputAnswerAnalysis extends ResolvedApiInputAnswerSources {
+export interface ApiInputAnswerAnalysis extends ResolvedApiInputAnswerInterpretations {
     status: 'extracted' | 'no-pending-inputs' | 'empty-reply';
     extraction?: ApiInputAnswerExtractionRecord;
 }
+export interface ValidateApiInputAnswerAnalysisInput extends ApiInputAnswerContext {
+    analysis: ApiInputAnswerAnalysis;
+}

package/dist/types/api-input-enum-answers.d.ts

@@ -0,0 +1,25 @@
+import type { ApiInputAnswerContext, ApiInputAnswerSource, ApiInputAnswerSourceLocation, ResolvedApiInputAnswerSources } from './api-input-answer-extraction.js';
+import type { ApiInputEnumCandidate } from './api-input-enum.js';
+import type { ApiInputLiteralSource } from './api-input-literal-source.js';
+export interface ApiInputEnumAnswerChoice {
+    requirementId: string;
+    candidates: ApiInputEnumCandidate[];
+}
+/** Intent is a human quotation, not the value copied from the OAS. */
+export interface ApiInputEnumAnswerSelection {
+    requirementId: string;
+    candidateId: string;
+    intent: ApiInputLiteralSource;
+    reason: string;
+}
+export interface VerifiedApiInputEnumAnswerSelection extends ApiInputEnumAnswerSelection {
+    candidate: ApiInputEnumCandidate;
+    occurrences: ApiInputAnswerSourceLocation[];
+}
+export interface ResolveApiInputAnswerInterpretationsInput extends ApiInputAnswerContext {
+    selections: ApiInputAnswerSource[];
+    enumSelections?: ApiInputEnumAnswerSelection[];
+}
+export interface ResolvedApiInputAnswerInterpretations extends ResolvedApiInputAnswerSources {
+    enumSelections?: VerifiedApiInputEnumAnswerSelection[];
+}

package/dist/types/api-input-enum-answers.js

@@ -0,0 +1 @@
+export {};

package/dist/types/api-input-enum.d.ts

@@ -0,0 +1,26 @@
+import type { ApiOperationKey } from './api-catalog.js';
+import type { JsonValue } from './api-arguments.js';
+import type { ApiBindingMaterial, BindingSchema } from './api-bindings.js';
+import type { ApiInputRequirement } from './api-clarification.js';
+import type { SchemaResourceContext } from './schema-resource.js';
+export interface ApiInputEnumCandidate {
+    id: string;
+    callId: string;
+    operation: ApiOperationKey;
+    targetPointer: string;
+    /** Location in the original target schema, never a human quotation. */
+    schemaPointer: string;
+    value: JsonValue;
+}
+export type ApiInputEnumSource = (ApiBindingMaterial & {
+    kind: 'operation';
+    targetPointer: string;
+}) | {
+    kind: 'requirement';
+    requirement: ApiInputRequirement;
+};
+export interface ApiInputEnumCandidatesInput {
+    source: ApiInputEnumSource;
+    schemas: BindingSchema[];
+    resources: SchemaResourceContext;
+}

package/dist/types/api-input-enum.js

@@ -0,0 +1 @@
+export {};

package/dist/types/oas-value-validation.d.ts

@@ -1,8 +1,21 @@
 import type { createValidator } from '@scalar/json-schema-validator';
 import type { JsonObject } from './openapi.js';
+import type { SchemaDialect } from './schema-dialect.js';
 export type OasValueSchema = JsonObject | boolean;
 export type OasValueValidation = ReturnType<typeof createValidator>;
 export interface OasValueValidator {
     schema: JsonObject;
     validate: OasValueValidation;
 }
+export interface OasValueValidationCacheOptions {
+    maximumEntries: number;
+    maximumRetainedSchemaBytes: number;
+}
+export interface OasValueValidationCacheEntry {
+    schema: JsonObject;
+    validate: OasValueValidation;
+    bytes: number;
+}
+export interface OasValueValidationCache {
+    getOrCreate(schema: JsonObject, dialect: SchemaDialect, compile: (schema: JsonObject) => OasValueValidation): OasValueValidation;
+}

package/dist/types/workflow-draft-api-call-planning.d.ts

@@ -9,6 +9,7 @@ import type { ProposedWorkflowDraftSourceEvidence, ResolvedWorkflowDraftSourceEv
 import type { ProposedWorkflowDraftApiBindingQuestion, WorkflowDraftApiBindingAnswer, WorkflowDraftApiCallPlanningQuestion } from './workflow-draft-api-binding-clarification.js';
 import type { WorkflowDraftApiBindingIntent } from './workflow-draft-api-binding-intent.js';
 import type { BindingSchema } from './api-bindings.js';
+import type { WorkflowDraftApiEnumSelection, VerifiedWorkflowDraftApiEnumSelection } from './workflow-draft-api-enum-selection.js';
 /** One operation already selected by an add-api-call or replace-api-operation decision. */
 export interface WorkflowDraftApiCallPlanningInput extends PrepareWorkflowDraftEditInput {
     stepId: string;
@@ -108,11 +109,14 @@ export interface WorkflowDraftApiCallArgumentsDescription extends WorkflowDraftA
 export interface ResolveWorkflowDraftApiCallArgumentsInput extends WorkflowDraftApiCallArgumentsInput {
     fingerprint: string;
     proposal: WorkflowDraftApiCallArgumentsProposal;
+    /** Semantic OAS choices, never raw user literal provenance or confirmed user answers. */
+    enumSelections?: WorkflowDraftApiEnumSelection[];
 }
 export interface WorkflowDraftApiCallArgumentsResultFields extends ResolvedWorkflowDraftSourceEvidence {
     fingerprint: string;
     proposal: WorkflowDraftApiCallArgumentsProposal;
     literalSources: VerifiedWorkflowDraftApiLiteralSource[];
+    enumSelections?: VerifiedWorkflowDraftApiEnumSelection[];
     arguments: ApiCallArguments;
     requirements: ApiInputRequirement[];
 }

package/dist/types/workflow-draft-api-enum-selection.d.ts

@@ -0,0 +1,39 @@
+import type { ApiInputAnswerSourceLocation } from './api-input-answer-extraction.js';
+import type { JsonObject } from './openapi.js';
+import type { ApiArgumentValues } from './api-arguments.js';
+import type { ApiInputEnumCandidate } from './api-input-enum.js';
+import type { WorkflowSourceMessage } from './workflow-draft.js';
+import type { WorkflowDraftApiCallArgumentsInput, WorkflowDraftApiCallArgumentsProposal } from './workflow-draft-api-call-planning.js';
+export interface WorkflowDraftApiEnumSelection {
+    candidateId: string;
+    messageId: string;
+    sourceText: string;
+    reason: string;
+}
+export interface VerifiedWorkflowDraftApiEnumSelection extends ApiInputEnumCandidate, WorkflowDraftApiEnumSelection {
+    occurrences: ApiInputAnswerSourceLocation[];
+}
+export interface WorkflowDraftApiEnumChoicesInput extends WorkflowDraftApiCallArgumentsInput {
+    proposal: WorkflowDraftApiCallArgumentsProposal;
+}
+export interface WorkflowDraftApiEnumChoicesDescription {
+    candidates: ApiInputEnumCandidate[];
+    targets: WorkflowDraftApiEnumTarget[];
+}
+export interface WorkflowDraftApiEnumTarget {
+    targetPointer: string;
+    schema: JsonObject | boolean;
+    description?: string;
+}
+export interface WorkflowDraftApiEnumResolution {
+    values: ApiArgumentValues;
+    selections: VerifiedWorkflowDraftApiEnumSelection[];
+}
+export interface WorkflowDraftApiEnumSelectionProposal {
+    selections: WorkflowDraftApiEnumSelection[];
+}
+export interface VerifyWorkflowDraftApiEnumSelectionInput {
+    selection: WorkflowDraftApiEnumSelection;
+    candidates: ApiInputEnumCandidate[];
+    messages: WorkflowSourceMessage[];
+}

package/dist/types/workflow-draft-api-enum-selection.js

@@ -0,0 +1 @@
+export {};