@openapi-flow/core 0.3.10 → 0.3.12

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-argument-enum.d.ts

@@ -0,0 +1,23 @@
+import type { ApiLiteralGenerationInput } from './api-literal-generation.js';
+import type { ApiArgumentValues, ApiArgumentProposal } from './api-arguments.js';
+import type { ApiInputAnswerAnalysis, ValidateApiInputAnswerAnalysisInput } from './api-input-answer-extraction.js';
+import type { ApiLiteralProposalSource } from './api-input-literal-source.js';
+import type { ApiInputRequirement } from './api-clarification.js';
+export interface ApiArgumentEnumRequirementsInput extends ApiArgumentEnumContextInput {
+    requirements: ApiInputRequirement[];
+    values: ApiArgumentValues;
+}
+export interface ApiArgumentEnumContextInput extends ApiLiteralGenerationInput {
+    /** Original literal proposal, before confirmed inputs or semantic OAS values are merged. */
+    proposal: ApiArgumentProposal;
+    literalSources: ApiLiteralProposalSource[];
+    requestedInputs?: string[];
+}
+export interface ResolveApiArgumentEnumInterpretationInput extends ApiArgumentEnumContextInput {
+    analysis: ApiInputAnswerAnalysis;
+}
+export interface ApiArgumentEnumResolution {
+    values: ApiArgumentValues;
+    unresolvedInputs: string[];
+    interpretation: ValidateApiInputAnswerAnalysisInput;
+}

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

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

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

@@ -1,5 +1,7 @@
 import type { ApiOperationContract } from './api-operation.js';
 import type { ApiLiteralGenerationRecord } from './api-literal-generation.js';
+import type { ValidateApiInputAnswerAnalysisInput } from './api-input-answer-extraction.js';
+import type { VerifiedApiLiteralProposalSource } from './api-input-literal-source.js';
 export type JsonValue = string | number | boolean | null | JsonValue[] | JsonValueObject;
 export interface JsonValueObject {
     [key: string]: JsonValue;
@@ -35,6 +37,10 @@ export interface ApiCallArguments extends ApiArgumentProposal {
     requestMediaType?: string;
     /** Optional immutable attribution of the original literal proposal, not final merged values. */
     literalGeneration?: ApiLiteralGenerationRecord;
+    /** Opt-in interpretation of unresolved OAS enum inputs; never verbatim literal attribution. */
+    enumInterpretation?: ValidateApiInputAnswerAnalysisInput;
+    /** Code-verified coverage of the original literal proposal, excluding copied OAS values. */
+    literalSources?: VerifiedApiLiteralProposalSource[];
 }
 export interface ValidateApiArgumentsInput extends ApiArgumentsSchemaInput {
     values: ApiArgumentValues;

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,12 @@
 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[];
+    /** Caller-supplied call role, separate from the quoted answer/value source. */
+    purpose?: string;
+    /** Allow semantic selection of original OAS enum values, never arbitrary generation. */
+    selectOasEnums?: boolean;
 }
 export interface ApiInputAnswerSource {
     requirementId: string;
@@ -30,12 +35,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 +49,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/api-input-literal-source.d.ts

@@ -1,5 +1,20 @@
 import type { JsonValue } from './api-arguments.js';
 import type { ApiInputAnswerSourceLocation } from './api-input-answer-extraction.js';
+import type { ApiArgumentValues } from './api-arguments.js';
+import type { WorkflowSourceMessage } from './workflow-draft.js';
+export interface ApiLiteralProposalSource extends ApiInputLiteralSource {
+    targetPointer: string;
+    messageId: string;
+}
+export interface VerifiedApiLiteralProposalSource extends ApiLiteralProposalSource {
+    occurrences: ApiInputAnswerSourceLocation[];
+}
+export interface ResolveApiLiteralProposalSourcesInput {
+    callId: string;
+    values: ApiArgumentValues;
+    sources: ApiLiteralProposalSource[];
+    messages: WorkflowSourceMessage[];
+}
 export interface ApiInputLiteralSource {
     sourceFormat: 'text' | 'json';
     sourceText: string;

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/dist/types/workflow-draft-api-literal-sources.d.ts

@@ -1,13 +1,7 @@
-import type { ApiInputLiteralSource } from './api-input-literal-source.js';
-import type { ApiInputAnswerSourceLocation } from './api-input-answer-extraction.js';
+import type { ApiLiteralProposalSource, VerifiedApiLiteralProposalSource } from './api-input-literal-source.js';
 import type { WorkflowDraftApiCallPlanningDescription, WorkflowDraftApiCallArgumentsProposal } from './workflow-draft-api-call-planning.js';
-export interface WorkflowDraftApiLiteralSource extends ApiInputLiteralSource {
-    targetPointer: string;
-    messageId: string;
-}
-export interface VerifiedWorkflowDraftApiLiteralSource extends WorkflowDraftApiLiteralSource {
-    occurrences: ApiInputAnswerSourceLocation[];
-}
+export type WorkflowDraftApiLiteralSource = ApiLiteralProposalSource;
+export type VerifiedWorkflowDraftApiLiteralSource = VerifiedApiLiteralProposalSource;
 export interface ResolveWorkflowDraftApiLiteralSourcesInput {
     description: WorkflowDraftApiCallPlanningDescription;
     proposal: WorkflowDraftApiCallArgumentsProposal;

package/package.json

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