@openapi-flow/core 0.3.10 → 0.3.11

package/dist/arguments/clarification/api-input-requirement-dialect.d.ts

@@ -0,0 +1,4 @@
+import type { ApiInputRequirement } from '../../types/api-clarification.js';
+import type { SchemaDialect } from '../../types/schema-dialect.js';
+/** A compiled projection declares its actual dialect; the source OAS version remains unchanged. */
+export declare function apiInputRequirementDialect(requirement: ApiInputRequirement): SchemaDialect;

package/dist/arguments/clarification/api-input-requirement-dialect.js

@@ -0,0 +1,8 @@
+/** A compiled projection declares its actual dialect; the source OAS version remains unchanged. */
+export function apiInputRequirementDialect(requirement) {
+    if (requirement.schemaDialect === 'draft-2020-12')
+        return 'draft-2020-12';
+    return requirement.openapiVersion.startsWith('3.0.')
+        ? 'openapi-3.0'
+        : 'draft-2020-12';
+}

package/dist/arguments/clarification/extraction/capture-api-input-answer-context.js

@@ -1,5 +1,6 @@
 import { apiInputAnswerContextSchema } from '../../../schemas/api-input-answer-extraction-schema.js';
 import { createOasValueValidator } from '../../../openapi/common/create-oas-value-validator.js';
+import { apiInputRequirementDialect } from '../api-input-requirement-dialect.js';
 /** Capture supplied pending contracts before any asynchronous model work. */
 export function captureApiInputAnswerContext(input) {
     apiInputAnswerContextSchema.parse(input);
@@ -9,9 +10,7 @@ export function captureApiInputAnswerContext(input) {
         if (ids.has(requirement.id))
             throw new Error(`Duplicate API input requirementId: ${requirement.id}`);
         ids.add(requirement.id);
-        createOasValueValidator(requirement.schema, requirement.openapiVersion.startsWith('3.0.')
-            ? 'openapi-3.0'
-            : 'draft-2020-12', `API input requirement ${requirement.id} ${requirement.targetPointer}`);
+        createOasValueValidator(requirement.schema, apiInputRequirementDialect(requirement), `API input requirement ${requirement.id} ${requirement.targetPointer}`);
     }
     return snapshot;
 }

package/dist/arguments/clarification/extraction/create-api-input-answer-extraction-record.js

@@ -1,19 +1,25 @@
 import { apiInputAnswerExtractionDecisionSchema } from '../../../schemas/api-input-answer-extraction-schema.js';
 import { captureApiInputAnswerContext } from './capture-api-input-answer-context.js';
-import { resolveApiInputAnswerSources } from './resolve-api-input-answer-sources.js';
+import { resolveApiInputAnswerInterpretations } from './resolve-api-input-answer-interpretations.js';
 export function createApiInputAnswerExtractionRecord(input) {
     const evidence = captureApiInputAnswerContext({
         reply: input.reply,
         requirements: input.requirements,
+        ...(input.selectOasEnums === undefined
+            ? {}
+            : { selectOasEnums: input.selectOasEnums }),
     });
     const decision = structuredClone(apiInputAnswerExtractionDecisionSchema.parse(input.decision));
-    const verification = resolveApiInputAnswerSources({
+    const verification = resolveApiInputAnswerInterpretations({
         ...evidence,
         selections: decision.answers.map((source) => ({
             requirementId: source.requirementId,
             sourceFormat: source.sourceFormat,
             sourceText: source.sourceText,
         })),
+        ...(decision.enumSelections === undefined
+            ? {}
+            : { enumSelections: decision.enumSelections }),
     });
     return {
         kind: 'model-extracted-api-input-answers',

package/dist/arguments/clarification/extraction/resolve-api-input-answer-interpretations.d.ts

@@ -0,0 +1,3 @@
+import type { ResolveApiInputAnswerInterpretationsInput, ResolvedApiInputAnswerInterpretations } from '../../../types/api-input-enum-answers.js';
+/** Literal values and semantic intent have different sources and must never be conflated. */
+export declare function resolveApiInputAnswerInterpretations(input: ResolveApiInputAnswerInterpretationsInput): ResolvedApiInputAnswerInterpretations;

package/dist/arguments/clarification/extraction/resolve-api-input-answer-interpretations.js

@@ -0,0 +1,51 @@
+import { apiInputEnumAnswerSelectionsSchema } from '../../../schemas/api-input-enum-answer-selection-schema.js';
+import { captureApiInputAnswerContext } from './capture-api-input-answer-context.js';
+import { resolveApiInputAnswerSources } from './resolve-api-input-answer-sources.js';
+import { describeApiInputEnumAnswerChoices } from '../../enum/describe-api-input-enum-answer-choices.js';
+import { readApiInputLiteralSource } from '../../sources/read-api-input-literal-source.js';
+/** Literal values and semantic intent have different sources and must never be conflated. */
+export function resolveApiInputAnswerInterpretations(input) {
+    const context = captureApiInputAnswerContext({
+        reply: input.reply,
+        requirements: input.requirements,
+        ...(input.selectOasEnums === undefined
+            ? {}
+            : { selectOasEnums: input.selectOasEnums }),
+    });
+    const result = resolveApiInputAnswerSources({
+        reply: context.reply,
+        requirements: context.requirements,
+        selections: input.selections,
+    });
+    if (input.enumSelections === undefined)
+        return result;
+    const selections = apiInputEnumAnswerSelectionsSchema.parse(input.enumSelections);
+    if (context.selectOasEnums !== true)
+        throw new Error('API enum answer selection requires selectOasEnums: true in the original context');
+    const choices = describeApiInputEnumAnswerChoices(context);
+    const answered = new Set(result.answers.map((answer) => answer.requirementId));
+    result.enumSelections = selections.map((selection) => {
+        if (answered.has(selection.requirementId))
+            throw new Error(`Duplicate requirementId: ${selection.requirementId}`);
+        const candidate = choices
+            .find((choice) => choice.requirementId === selection.requirementId)
+            ?.candidates.find((item) => item.id === selection.candidateId);
+        if (!candidate)
+            throw new Error(`API enum answer ${selection.requirementId} has an unknown or stale OAS candidate: ${selection.candidateId}`);
+        const { occurrences } = readApiInputLiteralSource({
+            ...selection.intent,
+            text: context.reply,
+            label: `Enum answer intent ${selection.requirementId}`,
+        });
+        answered.add(selection.requirementId);
+        result.answers.push({
+            requirementId: selection.requirementId,
+            value: structuredClone(candidate.value),
+        });
+        return { ...selection, candidate: structuredClone(candidate), occurrences };
+    });
+    result.unansweredRequirementIds = context.requirements
+        .filter((item) => !answered.has(item.id))
+        .map((item) => item.id);
+    return result;
+}

package/dist/arguments/clarification/extraction/resolve-api-input-answer-sources.js

@@ -2,6 +2,7 @@ import { apiInputAnswerSourcesSchema } from '../../../schemas/api-input-answer-e
 import { captureApiInputAnswerContext } from './capture-api-input-answer-context.js';
 import { readApiInputLiteralSource } from '../../sources/read-api-input-literal-source.js';
 import { createOasValueValidator } from '../../../openapi/common/create-oas-value-validator.js';
+import { apiInputRequirementDialect } from '../api-input-requirement-dialect.js';
 /** Model-selected source text is the only value source, never a model-generated value. */
 export function resolveApiInputAnswerSources(input) {
     const context = captureApiInputAnswerContext({
@@ -24,9 +25,7 @@ export function resolveApiInputAnswerSources(input) {
             text: context.reply,
             label: `Answer ${requirement.id}`,
         });
-        const checked = createOasValueValidator(requirement.schema, requirement.openapiVersion.startsWith('3.0.')
-            ? 'openapi-3.0'
-            : 'draft-2020-12', `answer ${requirement.targetPointer}`).validate(value);
+        const checked = createOasValueValidator(requirement.schema, apiInputRequirementDialect(requirement), `answer ${requirement.targetPointer}`).validate(value);
         if (!checked.valid)
             throw new Error(`Answer ${requirement.id} violates its supplied OAS schema: ${checked.errors.map((error) => error.message).join('; ')}`);
         answered.add(requirement.id);

package/dist/arguments/clarification/extraction/validate-api-input-answer-analysis.d.ts

@@ -0,0 +1,3 @@
+import type { ValidateApiInputAnswerAnalysisInput } from '../../../types/api-input-answer-extraction.js';
+/** Replay model choices against independently supplied original questions and reply. */
+export declare function validateApiInputAnswerAnalysis(input: ValidateApiInputAnswerAnalysisInput): void;

package/dist/arguments/clarification/extraction/validate-api-input-answer-analysis.js

@@ -0,0 +1,55 @@
+import { isDeepStrictEqual } from 'node:util';
+import { resolveApiInputAnswerInterpretations } from './resolve-api-input-answer-interpretations.js';
+import { validateApiInputAnswerExtractionRecord } from './validate-api-input-answer-extraction-record.js';
+/** Replay model choices against independently supplied original questions and reply. */
+export function validateApiInputAnswerAnalysis(input) {
+    const context = {
+        reply: input.reply,
+        requirements: input.requirements,
+        ...(input.selectOasEnums === undefined
+            ? {}
+            : { selectOasEnums: input.selectOasEnums }),
+    };
+    const { analysis } = input;
+    if (!Array.isArray(analysis.sources))
+        throw new Error('API input answer analysis.sources must be an array');
+    const resolved = resolveApiInputAnswerInterpretations({
+        ...context,
+        selections: analysis.sources.map((source) => ({
+            requirementId: source.requirementId,
+            sourceFormat: source.sourceFormat,
+            sourceText: source.sourceText,
+        })),
+        ...(analysis.enumSelections === undefined
+            ? {}
+            : {
+                enumSelections: analysis.enumSelections.map((selection) => ({
+                    requirementId: selection.requirementId,
+                    candidateId: selection.candidateId,
+                    intent: selection.intent,
+                    reason: selection.reason,
+                })),
+            }),
+    });
+    if (analysis.extraction !== undefined) {
+        validateApiInputAnswerExtractionRecord({
+            ...context,
+            record: analysis.extraction,
+        });
+        if (!isDeepStrictEqual(analysis.extraction.verification, resolved))
+            throw new Error('API input explanation differs from its code-resolved answer selection');
+    }
+    const status = !input.requirements.length
+        ? 'no-pending-inputs'
+        : input.reply === ''
+            ? 'empty-reply'
+            : 'extracted';
+    if (!isDeepStrictEqual(analysis, {
+        status,
+        ...resolved,
+        ...(analysis.extraction === undefined
+            ? {}
+            : { extraction: analysis.extraction }),
+    }))
+        throw new Error('API input analysis differs from its original reply, contracts or code-resolved values');
+}

package/dist/arguments/clarification/extraction/validate-api-input-answer-extraction-record.js

@@ -5,6 +5,9 @@ export function validateApiInputAnswerExtractionRecord(input) {
     const expected = createApiInputAnswerExtractionRecord({
         reply: input.reply,
         requirements: input.requirements,
+        ...(input.selectOasEnums === undefined
+            ? {}
+            : { selectOasEnums: input.selectOasEnums }),
         decision: input.record.decision,
     });
     if (!isDeepStrictEqual(expected, input.record))

package/dist/arguments/enum/describe-api-input-enum-answer-choices.d.ts

@@ -0,0 +1,4 @@
+import type { ApiInputAnswerContext } from '../../types/api-input-answer-extraction.js';
+import type { ApiInputEnumAnswerChoice } from '../../types/api-input-enum-answers.js';
+/** Pending question contracts are the only value authority; defaults/examples are not candidates. */
+export declare function describeApiInputEnumAnswerChoices(input: ApiInputAnswerContext): ApiInputEnumAnswerChoice[];

package/dist/arguments/enum/describe-api-input-enum-answer-choices.js

@@ -0,0 +1,23 @@
+import { captureApiInputAnswerContext } from '../clarification/extraction/capture-api-input-answer-context.js';
+import { createOasValueValidator } from '../../openapi/common/create-oas-value-validator.js';
+import { createSchemaResourceContext } from '../../bindings/resources/create-schema-resource-context.js';
+import { listApiInputEnumCandidates } from './list-api-input-enum-candidates.js';
+import { apiInputRequirementDialect } from '../clarification/api-input-requirement-dialect.js';
+/** Pending question contracts are the only value authority; defaults/examples are not candidates. */
+export function describeApiInputEnumAnswerChoices(input) {
+    const context = captureApiInputAnswerContext(input);
+    if (context.selectOasEnums !== true)
+        return [];
+    return context.requirements.flatMap((requirement) => {
+        const normalized = createOasValueValidator(requirement.schema, apiInputRequirementDialect(requirement), `API enum answer ${requirement.id}`).schema;
+        const resources = createSchemaResourceContext(normalized);
+        const candidates = listApiInputEnumCandidates({
+            source: { kind: 'requirement', requirement },
+            schemas: [resources.reference(resources.root)],
+            resources,
+        });
+        return candidates.length
+            ? [{ requirementId: requirement.id, candidates }]
+            : [];
+    });
+}

package/dist/arguments/enum/list-api-input-enum-candidates.d.ts

@@ -0,0 +1,3 @@
+import type { ApiInputEnumCandidatesInput, ApiInputEnumCandidate } from '../../types/api-input-enum.js';
+/** Enumerate declared values only. A source resource retains references and all sibling assertions. */
+export declare function listApiInputEnumCandidates(input: ApiInputEnumCandidatesInput): ApiInputEnumCandidate[];

package/dist/arguments/enum/list-api-input-enum-candidates.js

@@ -0,0 +1,73 @@
+import { createHash } from 'node:crypto';
+import { createOasValueValidator } from '../../openapi/common/create-oas-value-validator.js';
+/** Enumerate declared values only. A source resource retains references and all sibling assertions. */
+export function listApiInputEnumCandidates(input) {
+    const material = input.source.kind === 'operation' ? input.source : input.source.requirement;
+    const operation = input.source.kind === 'operation'
+        ? input.source.operation.key
+        : input.source.requirement.operation;
+    if (!input.schemas.length)
+        throw new Error(`API enum ${material.callId}${material.targetPointer} has no original OAS target schema`);
+    const schema = input.schemas.length === 1 ? input.schemas[0] : { anyOf: input.schemas };
+    const validator = createOasValueValidator(input.resources.bundle(schema), 'draft-2020-12', `API enum ${material.callId}${material.targetPointer}`);
+    const identity = input.source.kind === 'operation'
+        ? JSON.stringify([
+            input.source.callId,
+            input.source.operation,
+            input.source.requestMediaType,
+            input.source.targetPointer,
+        ])
+        : JSON.stringify(['requirement', input.source.requirement]);
+    const candidates = [];
+    const active = new Set();
+    function visit(current, pointer) {
+        if (typeof current === 'boolean' || active.has(current))
+            return;
+        active.add(current);
+        try {
+            if (Array.isArray(current.enum))
+                current.enum.forEach((value, index) => {
+                    if (!validator.validate(value).valid)
+                        return;
+                    const schemaPointer = `${pointer}/enum/${index}`;
+                    candidates.push({
+                        id: createHash('sha256')
+                            .update(identity)
+                            .update(JSON.stringify([schemaPointer, value]))
+                            .digest('hex'),
+                        callId: material.callId,
+                        operation: structuredClone(operation),
+                        targetPointer: material.targetPointer,
+                        schemaPointer,
+                        value: structuredClone(value),
+                    });
+                });
+            if (typeof current.$ref === 'string') {
+                const resolved = input.resources.resolve(current);
+                if (typeof resolved !== 'boolean') {
+                    const reference = input.resources.reference(resolved);
+                    if (typeof reference === 'boolean' ||
+                        typeof reference.$ref !== 'string')
+                        throw new Error(`API enum ${material.callId}${material.targetPointer} has no original schema reference`);
+                    visit(resolved, decodeURIComponent(new URL(reference.$ref).hash.slice(1)));
+                }
+            }
+            for (const key of ['allOf', 'anyOf', 'oneOf']) {
+                const children = current[key];
+                if (Array.isArray(children))
+                    children.forEach((child, index) => {
+                        if (typeof child === 'boolean' ||
+                            (child !== null &&
+                                typeof child === 'object' &&
+                                !Array.isArray(child)))
+                            visit(child, `${pointer}/${key}/${index}`);
+                    });
+            }
+        }
+        finally {
+            active.delete(current);
+        }
+    }
+    input.schemas.forEach((item, index) => visit(item, `/${index}`));
+    return candidates.filter((candidate, index) => candidates.findIndex((item) => item.id === candidate.id) === index);
+}

package/dist/draft/edits/api/describe-workflow-draft-api-enum-choices.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowDraftApiEnumChoicesInput, WorkflowDraftApiEnumChoicesDescription } from '../../../types/workflow-draft-api-enum-selection.js';
+/** Only unresolved original-OAS inputs. Defaults/examples never become choices. */
+export declare function describeWorkflowDraftApiEnumChoices(input: WorkflowDraftApiEnumChoicesInput): WorkflowDraftApiEnumChoicesDescription;

package/dist/draft/edits/api/describe-workflow-draft-api-enum-choices.js

@@ -0,0 +1,70 @@
+import { resolveApiCallArgumentsContext } from './resolve-api-call-arguments-context.js';
+import { applyConfirmedApiInputs } from '../../../arguments/clarification/apply-confirmed-api-inputs.js';
+import { inspectApiArgumentRequirements } from '../../../arguments/clarification/inspect-api-argument-requirements.js';
+import { schemasAtPointer } from '../../../bindings/schema-at-pointer.js';
+import { hasPointer } from '../../../bindings/json-pointer.js';
+import { createSchemaResourceContext } from '../../../bindings/resources/create-schema-resource-context.js';
+import { listApiInputEnumCandidates } from '../../../arguments/enum/list-api-input-enum-candidates.js';
+/** Only unresolved original-OAS inputs. Defaults/examples never become choices. */
+export function describeWorkflowDraftApiEnumChoices(input) {
+    const { description, contract } = resolveApiCallArgumentsContext(input);
+    const values = applyConfirmedApiInputs({
+        callId: description.nodeId,
+        operation: description.operation,
+        requestMediaType: description.requestMediaType,
+        bindings: input.bindingPlan.bindings,
+        confirmedInputs: input.confirmedInputs,
+        values: contract.valuesSchema.parse(input.proposal.values),
+    });
+    const inspected = inspectApiArgumentRequirements({
+        callId: description.nodeId,
+        operation: description.operation,
+        requestMediaType: description.requestMediaType,
+        bindings: input.bindingPlan.bindings,
+        values,
+        requestedInputs: input.proposal.requestedInputs,
+    });
+    const targets = new Set(inspected.requirements.flatMap((requirement) => [
+        requirement.targetPointer,
+        ...(requirement.requestedInputs ?? []),
+    ]));
+    const candidates = [];
+    const choiceTargets = [];
+    const resources = createSchemaResourceContext(description.requestSchema);
+    for (const targetPointer of targets) {
+        if (hasPointer(values, targetPointer) ||
+            input.bindingPlan.bindings.some((binding) => overlaps(binding.targetPointer, targetPointer)) ||
+            (input.confirmedInputs ?? []).some((item) => overlaps(item.targetPointer, targetPointer)))
+            continue;
+        const schemas = schemasAtPointer(resources.root, targetPointer, resources);
+        const selected = listApiInputEnumCandidates({
+            source: {
+                kind: 'operation',
+                callId: description.nodeId,
+                operation: description.operation,
+                requestMediaType: description.requestMediaType,
+                targetPointer,
+            },
+            schemas,
+            resources,
+        });
+        if (selected.length) {
+            candidates.push(...selected);
+            const requirement = inspected.requirements.find((item) => item.targetPointer === targetPointer ||
+                item.requestedInputs?.includes(targetPointer));
+            choiceTargets.push({
+                targetPointer,
+                schema: resources.bundle(schemas.length === 1 ? schemas[0] : { anyOf: schemas }),
+                ...(requirement?.parameterDescription === undefined
+                    ? {}
+                    : { description: requirement.parameterDescription }),
+            });
+        }
+    }
+    return { candidates, targets: choiceTargets };
+}
+function overlaps(left, right) {
+    return (left === right ||
+        left.startsWith(right + '/') ||
+        right.startsWith(left + '/'));
+}

package/dist/draft/edits/api/resolve-workflow-draft-api-call-arguments.js

@@ -5,6 +5,7 @@ import { inspectApiArgumentRequirements } from '../../../arguments/clarification
 import { resolveWorkflowDraftSourceEvidence } from '../references/resolve-workflow-draft-source-evidence.js';
 import { jsonValuesEqual } from '../../../utils/json-values-equal.js';
 import { resolveWorkflowDraftApiLiteralSources } from './resolve-workflow-draft-api-literal-sources.js';
+import { resolveWorkflowDraftApiEnumSelections } from './resolve-workflow-draft-api-enum-selections.js';
 /** Resolve one actual request; partial values become typed questions/slots, never dummy data. */
 export function resolveWorkflowDraftApiCallArguments(input) {
     const { description, fingerprint } = resolveApiCallArgumentsContext(input);
@@ -13,13 +14,18 @@ export function resolveWorkflowDraftApiCallArguments(input) {
     const proposal = createWorkflowDraftApiCallArgumentsSchema(input).parse(input.proposal);
     if (!jsonValuesEqual(proposal, input.proposal))
         throw new Error('API call arguments must validate without defaults, coercion or transformation');
+    const literalSources = resolveWorkflowDraftApiLiteralSources({
+        description,
+        proposal,
+    });
+    const enums = resolveWorkflowDraftApiEnumSelections({ ...input, proposal });
     const values = applyConfirmedApiInputs({
         callId: description.nodeId,
         operation: description.operation,
         requestMediaType: description.requestMediaType,
         bindings: input.bindingPlan.bindings,
         confirmedInputs: input.confirmedInputs,
-        values: proposal.values,
+        values: enums.values,
     });
     const inspected = inspectApiArgumentRequirements({
         callId: description.nodeId,
@@ -32,10 +38,8 @@ export function resolveWorkflowDraftApiCallArguments(input) {
     const fields = {
         fingerprint,
         proposal,
-        literalSources: resolveWorkflowDraftApiLiteralSources({
-            description,
-            proposal,
-        }),
+        literalSources,
+        ...(enums.selections.length ? { enumSelections: enums.selections } : {}),
         ...resolveWorkflowDraftSourceEvidence({
             description,
             decision: proposal,

package/dist/draft/edits/api/resolve-workflow-draft-api-enum-selections.d.ts

@@ -0,0 +1,4 @@
+import type { ResolveWorkflowDraftApiCallArgumentsInput } from '../../../types/workflow-draft-api-call-planning.js';
+import type { WorkflowDraftApiEnumResolution } from '../../../types/workflow-draft-api-enum-selection.js';
+/** Copy from the current OAS, never from model-supplied values or same-name fields. */
+export declare function resolveWorkflowDraftApiEnumSelections(input: ResolveWorkflowDraftApiCallArgumentsInput): WorkflowDraftApiEnumResolution;

package/dist/draft/edits/api/resolve-workflow-draft-api-enum-selections.js

@@ -0,0 +1,38 @@
+import { describeWorkflowDraftApiEnumChoices } from './describe-workflow-draft-api-enum-choices.js';
+import { createWorkflowDraftApiEnumSelectionSchema } from '../../../schemas/workflow-draft-api-enum-selection-schema.js';
+import { assignApiInputValue } from '../../../arguments/clarification/assign-api-input-value.js';
+import { resolveApiCallArgumentsContext } from './resolve-api-call-arguments-context.js';
+import { verifyWorkflowDraftApiEnumSelection } from '../enum/verify-workflow-draft-api-enum-selection.js';
+/** Copy from the current OAS, never from model-supplied values or same-name fields. */
+export function resolveWorkflowDraftApiEnumSelections(input) {
+    const values = structuredClone(input.proposal.values);
+    const verified = [];
+    if (input.enumSelections === undefined)
+        return { values, selections: verified };
+    const { candidates } = describeWorkflowDraftApiEnumChoices(input);
+    const proposal = createWorkflowDraftApiEnumSelectionSchema(input).parse({
+        selections: input.enumSelections,
+    });
+    const { description } = resolveApiCallArgumentsContext(input);
+    for (const selection of proposal.selections) {
+        const candidate = candidates.find((item) => item.id === selection.candidateId);
+        if (!candidate)
+            throw new Error(`API enum selection ${selection.candidateId} is absent from the current OAS choices`);
+        if (verified.some((item) => item.targetPointer === candidate.targetPointer ||
+            item.targetPointer.startsWith(candidate.targetPointer + '/') ||
+            candidate.targetPointer.startsWith(item.targetPointer + '/')))
+            throw new Error(`API enum selections overlap at ${candidate.targetPointer}`);
+        const receipt = verifyWorkflowDraftApiEnumSelection({
+            selection,
+            candidates,
+            messages: [...description.messages, ...description.backgroundMessages],
+        });
+        assignApiInputValue(values, candidate.targetPointer, structuredClone(candidate.value), {
+            operation: description.operation,
+            requestMediaType: description.requestMediaType,
+            callId: description.nodeId,
+        });
+        verified.push(receipt);
+    }
+    return { values, selections: verified };
+}

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

@@ -0,0 +1,3 @@
+import type { VerifyWorkflowDraftApiEnumSelectionInput, VerifiedWorkflowDraftApiEnumSelection } from '../../../types/workflow-draft-api-enum-selection.js';
+/** Human intent is a separate receipt; the selected request value comes only from the OAS. */
+export declare function verifyWorkflowDraftApiEnumSelection(input: VerifyWorkflowDraftApiEnumSelectionInput): VerifiedWorkflowDraftApiEnumSelection;

package/dist/draft/edits/enum/verify-workflow-draft-api-enum-selection.js

@@ -0,0 +1,23 @@
+import { createWorkflowDraftApiEnumChoiceSchema } from '../../../schemas/workflow-draft-api-enum-choice-schema.js';
+import { readApiInputLiteralSource } from '../../../arguments/sources/read-api-input-literal-source.js';
+/** Human intent is a separate receipt; the selected request value comes only from the OAS. */
+export function verifyWorkflowDraftApiEnumSelection(input) {
+    const selection = createWorkflowDraftApiEnumChoiceSchema(input.candidates, input.messages.map((message) => message.id)).parse(input.selection);
+    const candidate = input.candidates.find((item) => item.id === selection.candidateId);
+    if (!candidate)
+        throw new Error(`API enum selection ${selection.candidateId} is absent from the current OAS choices`);
+    const message = input.messages.find((item) => item.id === selection.messageId);
+    if (!message)
+        throw new Error(`API enum selection cites unavailable message ${selection.messageId}`);
+    const source = readApiInputLiteralSource({
+        sourceFormat: 'text',
+        sourceText: selection.sourceText,
+        text: message.text,
+        label: `API enum ${candidate.targetPointer}`,
+    });
+    return {
+        ...structuredClone(candidate),
+        ...selection,
+        occurrences: source.occurrences,
+    };
+}

package/dist/draft/edits/inputs/describe-workflow-draft-api-input-edit-answer-requirements.d.ts

@@ -0,0 +1,4 @@
+import type { ResolveWorkflowDraftApiInputEditsInput } from '../../../types/workflow-draft-api-input-edit.js';
+import type { ApiInputRequirement } from '../../../types/api-clarification.js';
+/** Questions for actual pending set-targets, retaining references and declaring the compiled dialect. */
+export declare function describeWorkflowDraftApiInputEditAnswerRequirements(input: ResolveWorkflowDraftApiInputEditsInput): ApiInputRequirement[];

package/dist/draft/edits/inputs/describe-workflow-draft-api-input-edit-answer-requirements.js

@@ -0,0 +1,30 @@
+import { describeWorkflowDraftApiInputEdit } from './describe-workflow-draft-api-input-edit.js';
+import { resolveWorkflowDraftApiInputEdits } from './resolve-workflow-draft-api-input-edits.js';
+import { createSchemaResourceContext } from '../../../bindings/resources/create-schema-resource-context.js';
+/** Questions for actual pending set-targets, retaining references and declaring the compiled dialect. */
+export function describeWorkflowDraftApiInputEditAnswerRequirements(input) {
+    const result = resolveWorkflowDraftApiInputEdits(input);
+    if (result.status === 'ready')
+        return [];
+    const described = describeWorkflowDraftApiInputEdit(input);
+    const resources = createSchemaResourceContext(input.contract.schemaResource);
+    return result.pendingTargets.map((target) => {
+        if (target.kind !== 'set')
+            throw new Error(`Pending API edit ${input.contract.id}:${target.id} is not a set-target`);
+        return {
+            kind: 'requested-input',
+            id: `${input.contract.id}:${target.id}`,
+            callId: described.call.id,
+            operation: structuredClone(described.operation.key),
+            targetPointer: target.pointer,
+            schema: resources.bundle(target.schema),
+            openapiVersion: described.operation.openapiVersion,
+            schemaDialect: 'draft-2020-12',
+            requestedInputs: [target.pointer],
+            ...(typeof described.operation.operation.summary === 'string'
+                ? { operationSummary: described.operation.operation.summary }
+                : {}),
+            message: `Provide the new explicitly requested value at ${target.pointer}. The existing value is not an answer to this edit.`,
+        };
+    });
+}

package/dist/draft/edits/inputs/describe-workflow-draft-api-input-edit-enum-choices.d.ts

@@ -0,0 +1,4 @@
+import type { WorkflowDraftApiInputEditContractInput } from '../../../types/workflow-draft-api-input-edit.js';
+import type { WorkflowDraftApiEnumChoicesDescription } from '../../../types/workflow-draft-api-enum-selection.js';
+/** Only previously validated set-targets; never advertise remove targets, bindings or unrelated fields. */
+export declare function describeWorkflowDraftApiInputEditEnumChoices(input: WorkflowDraftApiInputEditContractInput): WorkflowDraftApiEnumChoicesDescription;

package/dist/draft/edits/inputs/describe-workflow-draft-api-input-edit-enum-choices.js

@@ -0,0 +1,42 @@
+import { validateWorkflowDraftApiInputEditContract } from './validate-workflow-draft-api-input-edit-contract.js';
+import { describeWorkflowDraftApiInputEdit } from './describe-workflow-draft-api-input-edit.js';
+import { createSchemaResourceContext } from '../../../bindings/resources/create-schema-resource-context.js';
+import { listApiInputEnumCandidates } from '../../../arguments/enum/list-api-input-enum-candidates.js';
+/** Only previously validated set-targets; never advertise remove targets, bindings or unrelated fields. */
+export function describeWorkflowDraftApiInputEditEnumChoices(input) {
+    validateWorkflowDraftApiInputEditContract(input);
+    if (input.selectOasEnums !== undefined &&
+        typeof input.selectOasEnums !== 'boolean')
+        throw new Error('API input edit selectOasEnums must be a boolean');
+    const result = {
+        candidates: [],
+        targets: [],
+    };
+    if (input.selectOasEnums !== true)
+        return result;
+    const description = describeWorkflowDraftApiInputEdit(input);
+    const resources = createSchemaResourceContext(input.contract.schemaResource);
+    for (const target of input.contract.targets) {
+        if (target.kind !== 'set')
+            continue;
+        const candidates = listApiInputEnumCandidates({
+            source: {
+                kind: 'operation',
+                callId: description.call.id,
+                operation: description.operation,
+                requestMediaType: description.call.requestMediaType,
+                targetPointer: target.pointer,
+            },
+            schemas: [target.schema],
+            resources,
+        });
+        if (candidates.length) {
+            result.candidates.push(...candidates);
+            result.targets.push({
+                targetPointer: target.pointer,
+                schema: resources.bundle(target.schema),
+            });
+        }
+    }
+    return result;
+}

package/dist/draft/edits/inputs/resolve-workflow-draft-api-input-edit-reply.d.ts

@@ -0,0 +1,3 @@
+import type { ResolveWorkflowDraftApiInputEditReplyInput, WorkflowDraftApiInputEditAnswers } from '../../../types/workflow-draft-api-input-edit.js';
+/** Interpretations become validated answer values, never a replacement model proposal. */
+export declare function resolveWorkflowDraftApiInputEditReply(input: ResolveWorkflowDraftApiInputEditReplyInput): WorkflowDraftApiInputEditAnswers;

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

@@ -0,0 +1,24 @@
+import { describeWorkflowDraftApiInputEditAnswerRequirements } from './describe-workflow-draft-api-input-edit-answer-requirements.js';
+import { validateApiInputAnswerAnalysis } from '../../../arguments/clarification/extraction/validate-api-input-answer-analysis.js';
+import { createWorkflowDraftApiInputEditAnswersSchema } from '../../../schemas/create-workflow-draft-api-input-edit-answers-schema.js';
+/** Interpretations become validated answer values, never a replacement model proposal. */
+export function resolveWorkflowDraftApiInputEditReply(input) {
+    const requirements = describeWorkflowDraftApiInputEditAnswerRequirements(input);
+    validateApiInputAnswerAnalysis({
+        reply: input.reply,
+        requirements,
+        ...(input.selectOasEnums === undefined
+            ? {}
+            : { selectOasEnums: input.selectOasEnums }),
+        analysis: input.analysis,
+    });
+    return createWorkflowDraftApiInputEditAnswersSchema(input).parse({
+        contractId: input.contract.id,
+        answers: input.analysis.answers.map((answer) => {
+            const target = input.contract.targets.find((target) => `${input.contract.id}:${target.id}` === answer.requirementId);
+            if (!target)
+                throw new Error(`API edit reply references an unavailable target ${answer.requirementId}`);
+            return { targetId: target.id, value: structuredClone(answer.value) };
+        }),
+    });
+}

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

package/dist/types/workflow-draft-api-input-edit.d.ts

@@ -9,6 +9,8 @@ import type { ApiOperationContract } from './api-operation.js';
 import type { WorkflowDraftApiCall, WorkflowSourceMessage } from './workflow-draft.js';
 import type { JsonObject } from './openapi.js';
 import type { ApiInputLiteralSource } from './api-input-literal-source.js';
+import type { ApiInputAnswerAnalysis } from './api-input-answer-extraction.js';
+import type { WorkflowDraftApiEnumSelection, VerifiedWorkflowDraftApiEnumSelection } from './workflow-draft-api-enum-selection.js';
 import type { workflowDraftApiInputEditAnswerSchema, workflowDraftApiInputEditAnswersSchema } from '../schemas/workflow-draft-api-input-edit-answers-schema.js';
 export interface WorkflowDraftApiInputEditMaterial extends ApiBindingMaterial {
     requestedInputs?: string[];
@@ -63,6 +65,8 @@ export interface WorkflowDraftApiInputEditContract {
 }
 export interface WorkflowDraftApiInputEditContractInput extends WorkflowDraftApiInputEditInput {
     contract: WorkflowDraftApiInputEditContract;
+    /** Enable ID-only interpretation of declared OAS enum choices, with separate provenance. */
+    selectOasEnums?: boolean;
 }
 export interface WorkflowDraftApiInputEditValueSource extends ApiInputLiteralSource {
     messageId: string;
@@ -73,6 +77,9 @@ export type WorkflowDraftApiInputEditValue = ({
     source: WorkflowDraftApiInputEditValueSource;
 } | {
     status: 'needs-input';
+} | {
+    status: 'oas-enum';
+    selection: WorkflowDraftApiEnumSelection;
 }) & {
     explanation?: WorkflowDecisionExplanation<WorkflowMessageEvidence>;
 };
@@ -85,9 +92,13 @@ export interface WorkflowDraftApiInputEditAnswerSchemaInput extends WorkflowDraf
     output: WorkflowDraftApiInputEditValues;
 }
 export interface ResolveWorkflowDraftApiInputEditsInput extends WorkflowDraftApiInputEditAnswerSchemaInput {
-    /** Explicit user answers to pending targets, separate from the unchanged model output. */
+    /** Validated user answer values, separate from the unchanged model output. Retain natural-answer analysis independently. */
     confirmedAnswers?: WorkflowDraftApiInputEditAnswers;
 }
+export interface ResolveWorkflowDraftApiInputEditReplyInput extends ResolveWorkflowDraftApiInputEditsInput {
+    reply: string;
+    analysis: ApiInputAnswerAnalysis;
+}
 export type WorkflowDraftApiInputEditResult = ({
     status: 'ready';
     contractId: string;
@@ -101,8 +112,10 @@ export type WorkflowDraftApiInputEditResult = ({
     values: WorkflowDraftApiInputEditValues;
     pendingTargets: WorkflowDraftApiInputEditTarget[];
 }) & {
-    /** Present only when the caller supplied an explicit typed reply. */
+    /** Present when validated user answer values were supplied; natural provenance belongs to the separate answer analysis. */
     confirmedAnswers?: WorkflowDraftApiInputEditAnswers;
+    /** Original OAS values and human intent, not user-provided literal attribution. */
+    enumSelections?: VerifiedWorkflowDraftApiEnumSelection[];
 };
 export type WorkflowDraftApiInputEditValuesSchema = z.ZodType<WorkflowDraftApiInputEditValues>;
 export type WorkflowDraftApiInputEditAnswersSchema = z.ZodType<WorkflowDraftApiInputEditAnswers>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openapi-flow/core",
-  "version": "0.3.10",
+  "version": "0.3.11",
   "license": "MIT",
   "description": "Engine-independent OpenAPI catalogs, operation contracts and typed request schemas",
   "keywords": [