@openapi-flow/core 0.2.0 → 0.3.1

package/dist/schemas/workflow-planning-message-ids-schema.js

@@ -0,0 +1,5 @@
+import { z } from 'zod';
+import { planningEvidenceTextSchema } from './planning-evidence-schema.js';
+export const workflowPlanningMessageIdsSchema = z
+    .array(planningEvidenceTextSchema)
+    .refine((ids) => new Set(ids).size === ids.length, 'planningMessageIds must contain distinct actual message IDs');

package/dist/schemas/workflow-review-suggestion-evidence-schema.d.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+export declare const workflowReviewSuggestionEvidenceSchema: z.ZodUnion<readonly [z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"message">;
+    messageId: z.ZodString;
+    quote: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"oas">;
+    operation: z.ZodObject<{
+        documentId: z.ZodString;
+        snapshotId: z.ZodString;
+        operationRef: z.ZodString;
+    }, z.core.$strict>;
+    pointer: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"native">;
+    capability: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"entrypoint">;
+    entrypoint: z.ZodString;
+}, z.core.$strict>], "kind">, z.ZodObject<{
+    kind: z.ZodLiteral<"review-question">;
+    questionId: z.ZodString;
+}, z.core.$strict>]>;

package/dist/schemas/workflow-review-suggestion-evidence-schema.js

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+import { workflowPlanningEvidenceSchema } from './planning-evidence-schema.js';
+export const workflowReviewSuggestionEvidenceSchema = z.union([
+    workflowPlanningEvidenceSchema,
+    z.strictObject({
+        kind: z.literal('review-question'),
+        questionId: z.string().min(1),
+    }),
+]);

package/dist/schemas/workflow-review-suggestion-settings-schema.d.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+export declare const workflowReviewSuggestionLimitsSchema: z.ZodObject<{
+    maxSuggestions: z.ZodNumber;
+}, z.core.$strict>;
+export declare const workflowReviewSuggestionOptionsSchema: z.ZodObject<{
+    includeExplanations: z.ZodDefault<z.ZodBoolean>;
+    includeExtensions: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strict>;
+export declare const workflowReviewBoundarySchema: z.ZodObject<{
+    key: z.ZodString;
+    kind: z.ZodEnum<{
+        "requirements-clarification": "requirements-clarification";
+        "selection-review": "selection-review";
+        "planning-questions": "planning-questions";
+        "candidate-review": "candidate-review";
+    }>;
+    revision: z.ZodNumber;
+    questions: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strict>>;
+    data: z.ZodJSONSchema;
+}, z.core.$strict>;

package/dist/schemas/workflow-review-suggestion-settings-schema.js

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+export const workflowReviewSuggestionLimitsSchema = z.strictObject({
+    maxSuggestions: z.number().int().positive(),
+});
+export const workflowReviewSuggestionOptionsSchema = z.strictObject({
+    includeExplanations: z.boolean().default(true),
+    includeExtensions: z.boolean().default(true),
+});
+export const workflowReviewBoundarySchema = z.strictObject({
+    key: z.string().refine((value) => value.trim().length > 0),
+    kind: z.enum([
+        'requirements-clarification',
+        'selection-review',
+        'planning-questions',
+        'candidate-review',
+    ]),
+    revision: z.number().int().nonnegative(),
+    questions: z
+        .array(z.strictObject({
+        id: z.string().min(1),
+        message: z.string().refine((value) => value.trim().length > 0),
+    }))
+        .refine((questions) => new Set(questions.map((question) => question.id)).size ===
+        questions.length),
+    data: z.json(),
+});

package/dist/schemas/workflow-review-suggestions-record-schema.d.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+/** Structural gate before reconstructing every canonical suggestion from its original proposal. */
+export declare const workflowReviewSuggestionsRecordSchema: z.ZodObject<{
+    id: z.ZodString;
+    fingerprint: z.ZodString;
+    boundaryKey: z.ZodString;
+    target: z.ZodObject<{
+        questions: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            message: z.ZodString;
+        }, z.core.$strict>>;
+        kind: z.ZodEnum<{
+            "requirements-clarification": "requirements-clarification";
+            "selection-review": "selection-review";
+            "planning-questions": "planning-questions";
+            "candidate-review": "candidate-review";
+        }>;
+        revision: z.ZodNumber;
+        data: z.ZodJSONSchema;
+    }, z.core.$strict>;
+    limits: z.ZodObject<{
+        maxSuggestions: z.ZodNumber;
+    }, z.core.$strict>;
+    options: z.ZodObject<{
+        includeExplanations: z.ZodDefault<z.ZodBoolean>;
+        includeExtensions: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>;
+    suggestions: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$loose>>;
+}, z.core.$strict>;

package/dist/schemas/workflow-review-suggestions-record-schema.js

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+import { workflowReviewSuggestionLimitsSchema, workflowReviewSuggestionOptionsSchema, } from './workflow-review-suggestion-settings-schema.js';
+import { workflowReviewBoundarySchema } from './workflow-review-suggestion-settings-schema.js';
+/** Structural gate before reconstructing every canonical suggestion from its original proposal. */
+export const workflowReviewSuggestionsRecordSchema = z.strictObject({
+    id: z.string().min(1),
+    fingerprint: z.string().min(1),
+    boundaryKey: z.string().min(1),
+    target: workflowReviewBoundarySchema.omit({ key: true }),
+    limits: workflowReviewSuggestionLimitsSchema,
+    options: workflowReviewSuggestionOptionsSchema,
+    suggestions: z.array(z.object({ id: z.string().min(1) }).passthrough()),
+});

package/dist/types/api-argument-generation.d.ts

@@ -1,13 +1,17 @@
 import type { z } from 'zod';
-import type { ApiArgumentProposal } from './api-arguments.js';
+import type { ApiArgumentValues } from './api-arguments.js';
 import type { JsonObject } from './openapi.js';
 export type LiteralInputSchema = JsonObject | boolean;
 export interface LiteralInputProjection {
     schema: LiteralInputSchema;
     hasLiteralValues: boolean;
 }
+export type ApiArgumentProposalSchemaShape = {
+    values: z.ZodType<ApiArgumentValues>;
+};
 export interface ApiArgumentGenerationContract {
-    schema: z.ZodType<ApiArgumentProposal>;
+    schema: z.ZodObject<ApiArgumentProposalSchemaShape, z.core.$strict>;
+    valuesSchema: z.ZodType<ApiArgumentValues>;
     literalInputSchema: JsonObject;
     hasLiteralInputs: boolean;
 }

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

@@ -1,16 +1,17 @@
 import type { ApiOperationContract } from './api-operation.js';
+import type { ApiLiteralGenerationRecord } from './api-literal-generation.js';
 export type JsonValue = string | number | boolean | null | JsonValue[] | JsonValueObject;
 export interface JsonValueObject {
     [key: string]: JsonValue;
 }
-export interface ApiArgumentValues {
+export type ApiArgumentValues = {
     path?: JsonValueObject;
     query?: JsonValueObject;
     header?: JsonValueObject;
     cookie?: JsonValueObject;
     querystring?: JsonValueObject;
     body?: JsonValue;
-}
+};
 export interface OutputBinding {
     kind: 'node-output';
     targetPointer: string;
@@ -28,9 +29,12 @@ export interface ApiArgumentsSchemaInput {
 export type ApiRequestSchemaInput = Omit<ApiArgumentsSchemaInput, 'bindings'>;
 export interface ApiCallArguments extends ApiArgumentProposal {
     callId: string;
+    requestedInputs?: string[];
     bindings: OutputBinding[];
     unresolvedInputs: string[];
     requestMediaType?: string;
+    /** Optional immutable attribution of the original literal proposal, not final merged values. */
+    literalGeneration?: ApiLiteralGenerationRecord;
 }
 export interface ValidateApiArgumentsInput extends ApiArgumentsSchemaInput {
     values: ApiArgumentValues;

package/dist/types/api-binding-planning.d.ts

@@ -0,0 +1,47 @@
+import type { ApiOperationContract } from './api-operation.js';
+import type { ApiBindingMaterial, ApiBindingPlanProposal, PlannedApiBindings } from './api-bindings.js';
+import type { ApiResponsePointerCatalog } from './api-response-pointers.js';
+import type { NativeOutputContract } from './node-output.js';
+export interface ApiBindingPlanningInput {
+    scenario: string;
+    materials: ApiBindingMaterial[];
+    nativeOutputs?: NativeOutputContract[];
+}
+export interface ApiBindingPlanningMaterial extends Pick<ApiBindingMaterial, 'callId' | 'purpose' | 'requestMediaType'> {
+    operation: Pick<ApiOperationContract, 'key' | 'method' | 'path' | 'operation' | 'effective'>;
+    responsePointerCatalog: ApiResponsePointerCatalog[];
+}
+export interface ApiBindingPlanningContext {
+    scenario: string;
+    materials: ApiBindingPlanningMaterial[];
+    nativeOutputs?: NativeOutputContract[];
+}
+export interface ApiBindingPlanningDescription {
+    input: ApiBindingPlanningInput;
+    context: ApiBindingPlanningContext;
+}
+export interface ApiBindingCallReason {
+    callId: string;
+    reason: string;
+}
+export interface ExplainedApiBindingCall extends PlannedApiBindings {
+    reason: string;
+}
+export interface ApiBindingPlanningRecord {
+    kind: 'proposed-bindings';
+    calls: ExplainedApiBindingCall[];
+    /** The original gap description is its reason; do not generate a duplicate. */
+    gaps: ApiBindingPlanProposal['gaps'];
+    evidence: {
+        kind: 'supplied-binding-contracts';
+        context: ApiBindingPlanningContext;
+    };
+}
+export interface CreateApiBindingPlanningRecordInput extends ApiBindingPlanningInput {
+    plan: ApiBindingPlanProposal;
+    reasons: ApiBindingCallReason[];
+}
+export interface ValidateApiBindingPlanningRecordInput extends ApiBindingPlanningInput {
+    plan: ApiBindingPlanProposal;
+    record: ApiBindingPlanningRecord;
+}

package/dist/types/api-binding-planning.js

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

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

@@ -2,19 +2,24 @@ import type { ApiOperationContract } from './api-operation.js';
 import type { OutputBinding } from './api-arguments.js';
 import type { JsonObject } from './openapi.js';
 import type { NativeOutputContract } from './node-output.js';
+import type { ApiBindingPlanningRecord } from './api-binding-planning.js';
 export interface ApiBindingMaterial {
     callId: string;
     operation: ApiOperationContract;
+    purpose?: string;
     requestMediaType?: string;
 }
 export interface PlannedApiBindings {
     callId: string;
     bindings: OutputBinding[];
 }
-export interface ApiBindingPlan {
+export interface ApiBindingPlanProposal {
     calls: PlannedApiBindings[];
     gaps: ApiBindingGap[];
 }
+export interface ApiBindingPlan extends ApiBindingPlanProposal {
+    bindingPlanning?: ApiBindingPlanningRecord;
+}
 export interface ApiBindingGap {
     callId: string;
     targetPointer: string;
@@ -25,6 +30,12 @@ export interface ValidateApiBindingAssignmentsInput {
     materials: ApiBindingMaterial[];
     nativeOutputs?: NativeOutputContract[];
 }
+export interface ValidateApiBindingAssignmentInput {
+    callId: string;
+    binding: OutputBinding;
+    materials: ApiBindingMaterial[];
+    nativeOutputs?: NativeOutputContract[];
+}
 export interface ValidateApiBindingPlanInput {
     plan: ApiBindingPlan;
     materials: ApiBindingMaterial[];

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

@@ -1,4 +1,5 @@
 import type { OpenApiDocument, OperationCandidate } from './openapi.js';
+import type { ApiSelectionExplanation } from './api-selection-evidence.js';
 export interface ApiSource {
     id: string;
     spec: OpenApiDocument;
@@ -22,11 +23,13 @@ export interface ApiCatalog {
 export interface SelectedApiOperation {
     key: ApiOperationKey;
     purpose: string;
+    explanation?: ApiSelectionExplanation;
 }
 export interface ApiCapabilityGap {
     kind: 'missing_operation' | 'insufficient_contract';
     description: string;
     operation?: ApiOperationKey;
+    explanation?: ApiSelectionExplanation;
 }
 export interface ApiSelection {
     operations: SelectedApiOperation[];

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

@@ -0,0 +1,80 @@
+import type { ApiCatalog, ApiOperationKey, ApiOperationCandidate, ApiSelection } from './api-catalog.js';
+import type { ApiArgumentsSchemaInput, ApiArgumentValues, JsonValue, ValidateApiArgumentsInput } from './api-arguments.js';
+import type { JsonObject } from './openapi.js';
+import type { ApiSelectionExplanation } from './api-selection-evidence.js';
+export interface ConfirmedApiInput {
+    callId: string;
+    operation: ApiOperationKey;
+    targetPointer: string;
+    value: JsonValue;
+}
+export interface ApiArgumentGenerationInput extends ApiArgumentsSchemaInput {
+    callId?: string;
+    confirmedInputs?: ConfirmedApiInput[];
+}
+export interface ApplyConfirmedApiInputsInput extends ApiArgumentGenerationInput {
+    values: ApiArgumentValues;
+}
+export interface ApiInputRequirement {
+    kind: 'missing-input' | 'requested-input';
+    id: string;
+    callId: string;
+    operation: ApiOperationKey;
+    targetPointer: string;
+    schema: JsonObject | boolean;
+    openapiVersion: string;
+    operationSummary?: string;
+    parameterDescription?: string;
+    message: string;
+    /** Actual user-requested paths covered by this question, not additions to the OAS schema. */
+    requestedInputs?: string[];
+}
+export interface InspectApiArgumentRequirementsInput extends ValidateApiArgumentsInput {
+    callId: string;
+    requestedInputs?: string[];
+}
+export interface ApiArgumentRequirements {
+    status: 'ready' | 'needs-input';
+    requirements: ApiInputRequirement[];
+}
+export interface ApiInputAnswer {
+    requirementId: string;
+    value: JsonValue;
+}
+export interface ApiAnswerIssue {
+    requirementId: string;
+    message: string;
+}
+export interface ValidateApiInputAnswersInput {
+    requirements: ApiInputRequirement[];
+    answers: ApiInputAnswer[];
+    operations: ApiOperationKey[];
+}
+export type ApiInputAnswersResult = {
+    status: 'accepted';
+    confirmedInputs: ConfirmedApiInput[];
+} | {
+    status: 'invalid-answer';
+    issues: ApiAnswerIssue[];
+};
+export interface ApiOperationChoice {
+    kind: 'operation-choice';
+    id: string;
+    message: string;
+    purpose: string;
+    candidates: ApiOperationCandidate[];
+    explanation?: ApiSelectionExplanation;
+}
+export interface ApiSelectionAnalysis {
+    selection: ApiSelection;
+    questions: ApiOperationChoice[];
+}
+export interface ApiOperationAnswer {
+    questionId: string;
+    operation: ApiOperationKey;
+}
+export interface ResolveApiSelectionAnswersInput {
+    catalog: ApiCatalog;
+    analysis: ApiSelectionAnalysis;
+    answers: ApiOperationAnswer[];
+}

package/dist/types/api-clarification.js

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

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

@@ -0,0 +1,49 @@
+import type { ApiInputAnswer, ApiInputRequirement } from './api-clarification.js';
+export interface ApiInputAnswerContext {
+    reply: string;
+    requirements: ApiInputRequirement[];
+}
+export interface ApiInputAnswerSource {
+    requirementId: string;
+    sourceFormat: 'text' | 'json';
+    sourceText: string;
+}
+export interface ExplainedApiInputAnswerSource extends ApiInputAnswerSource {
+    reason: string;
+}
+export interface ApiInputAnswerSourceLocation {
+    offset: number;
+    length: number;
+}
+export interface LocatedApiInputAnswerSource extends ApiInputAnswerSource {
+    /** All exact, complete occurrences; offsets count JavaScript UTF-16 code units. */
+    occurrences: ApiInputAnswerSourceLocation[];
+}
+export interface ResolveApiInputAnswerSourcesInput extends ApiInputAnswerContext {
+    selections: ApiInputAnswerSource[];
+}
+export interface ResolvedApiInputAnswerSources {
+    answers: ApiInputAnswer[];
+    sources: LocatedApiInputAnswerSource[];
+    unansweredRequirementIds: string[];
+}
+export interface ApiInputAnswerExtractionDecision {
+    reason: string;
+    answers: ExplainedApiInputAnswerSource[];
+}
+export interface ApiInputAnswerExtractionRecord {
+    kind: 'model-extracted-api-input-answers';
+    decision: ApiInputAnswerExtractionDecision;
+    evidence: ApiInputAnswerContext;
+    verification: ResolvedApiInputAnswerSources;
+}
+export interface CreateApiInputAnswerExtractionRecordInput extends ApiInputAnswerContext {
+    decision: ApiInputAnswerExtractionDecision;
+}
+export interface ValidateApiInputAnswerExtractionRecordInput extends ApiInputAnswerContext {
+    record: ApiInputAnswerExtractionRecord;
+}
+export interface ApiInputAnswerAnalysis extends ResolvedApiInputAnswerSources {
+    status: 'extracted' | 'no-pending-inputs' | 'empty-reply';
+    extraction?: ApiInputAnswerExtractionRecord;
+}

package/dist/types/api-input-answer-extraction.js

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

package/dist/types/api-input-literal-source.d.ts

@@ -0,0 +1,17 @@
+import type { JsonValue } from './api-arguments.js';
+import type { ApiInputAnswerSourceLocation } from './api-input-answer-extraction.js';
+export interface ApiInputLiteralSource {
+    sourceFormat: 'text' | 'json';
+    sourceText: string;
+}
+export interface ReadApiInputLiteralSourceInput extends ApiInputLiteralSource {
+    text: string;
+    label: string;
+}
+export interface ReadApiInputLiteralSourceResult {
+    value: JsonValue;
+    occurrences: ApiInputAnswerSourceLocation[];
+}
+export interface VerifyApiInputLiteralSourceInput extends ReadApiInputLiteralSourceInput {
+    value: JsonValue;
+}

package/dist/types/api-input-literal-source.js

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

package/dist/types/api-input-source-selection.d.ts

@@ -0,0 +1,36 @@
+import type { ApiInputAnswerContext, ApiInputAnswerSourceLocation } from './api-input-answer-extraction.js';
+export interface ProtectedApiInputLiteral extends ApiInputAnswerSourceLocation {
+    quoted: boolean;
+}
+export interface ApiInputJsonSourceCandidate extends ApiInputAnswerSourceLocation {
+    id: string;
+    text: string;
+}
+export interface ApiInputTextSourceToken extends ApiInputAnswerSourceLocation {
+    id: string;
+    text: string;
+}
+export interface ApiInputTextSourceSegment {
+    id: string;
+    tokens: ApiInputTextSourceToken[];
+}
+export interface ApiInputSourceCatalog {
+    json: ApiInputJsonSourceCandidate[];
+    text: ApiInputTextSourceSegment[];
+}
+export interface ApiInputJsonSourceSelection {
+    kind: 'json';
+    candidateId: string;
+}
+export interface ApiInputTextSourceSelection {
+    kind: 'text';
+    startTokenId: string;
+    endTokenId: string;
+}
+export interface ApiInputAnswerSourceSelection {
+    requirementId: string;
+    source: ApiInputJsonSourceSelection | ApiInputTextSourceSelection;
+}
+export interface ResolveApiInputSourceSelectionsInput extends ApiInputAnswerContext {
+    selections: ApiInputAnswerSourceSelection[];
+}

package/dist/types/api-input-source-selection.js

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

package/dist/types/api-literal-generation.d.ts

@@ -0,0 +1,59 @@
+import type { ApiOperationKey } from './api-catalog.js';
+import type { ApiArgumentGenerationInput } from './api-clarification.js';
+import type { ApiArgumentGenerationContract } from './api-argument-generation.js';
+import type { ApiArgumentProposal, ApiArgumentValues } from './api-arguments.js';
+import type { JsonObject } from './openapi.js';
+import type { WorkflowDecisionExplanation } from './workflow-clarification.js';
+export interface ApiLiteralGenerationInput extends ApiArgumentGenerationInput {
+    callId: string;
+    scenario: string;
+    /** Supplied call-instance role; never inferred from its array position or API path. */
+    purpose?: string;
+}
+export interface ApiLiteralGenerationOperation {
+    key: ApiOperationKey;
+    method: string;
+    path: string;
+    summary?: string;
+    description?: string;
+}
+export interface ApiLiteralGenerationContext {
+    scenario: string;
+    purpose?: string;
+    operation: ApiLiteralGenerationOperation;
+    literalInputSchema: JsonObject;
+    requestMediaType?: string;
+}
+export interface ApiLiteralGenerationDescription {
+    input: ApiLiteralGenerationInput;
+    contract: ApiArgumentGenerationContract;
+    context: ApiLiteralGenerationContext;
+}
+export type ApiLiteralGenerationEvidence = {
+    kind: 'scenario';
+    text: string;
+    purpose?: string;
+} | {
+    kind: 'literal-input-contract';
+    operation: ApiLiteralGenerationOperation;
+    schema: JsonObject;
+    requestMediaType?: string;
+};
+export type ApiLiteralGenerationRecord = {
+    kind: 'not-needed';
+    callId: string;
+    operation: ApiOperationKey;
+} | {
+    kind: 'proposed-literals';
+    callId: string;
+    operation: ApiOperationKey;
+    proposedValues: ApiArgumentValues;
+    explanation: WorkflowDecisionExplanation<ApiLiteralGenerationEvidence>;
+};
+export interface CreateApiLiteralGenerationRecordInput extends ApiLiteralGenerationInput {
+    proposal?: ApiArgumentProposal;
+    reason?: string;
+}
+export interface ValidateApiLiteralGenerationRecordInput extends ApiLiteralGenerationInput {
+    record: ApiLiteralGenerationRecord;
+}

package/dist/types/api-literal-generation.js

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

package/dist/types/api-request-media-type-decision.d.ts

@@ -0,0 +1,71 @@
+import type { ApiOperationContract } from './api-operation.js';
+import type { ApiOperationKey } from './api-catalog.js';
+import type { JsonObject } from './openapi.js';
+import type { WorkflowDecisionExplanation } from './workflow-clarification.js';
+export interface ApiRequestMediaTypeContextInput {
+    operation: ApiOperationContract;
+    scenario: string;
+    purpose?: string;
+}
+export interface ApiRequestMediaTypeSource {
+    key: ApiOperationKey;
+    method: string;
+    path: string;
+    requestBody?: JsonObject;
+}
+export interface ApiRequestMediaTypeContext {
+    scenario: string;
+    purpose?: string;
+    operation: ApiRequestMediaTypeSource;
+    mediaTypes: string[];
+}
+export type ApiRequestMediaTypeEvidence = {
+    kind: 'scenario';
+    text: string;
+    purpose?: string;
+} | {
+    kind: 'oas-request-body';
+    operation: ApiOperationKey;
+    pointer: '/requestBody';
+    value: JsonObject;
+};
+/** The optional reason explains the assessment, not a code-owned default choice. */
+export interface ProposedApiRequestMediaTypeAssessment {
+    requestMediaType: string | null;
+    explanation?: {
+        reason: string;
+    };
+}
+export interface ApiRequestMediaTypeAssessment extends Omit<ProposedApiRequestMediaTypeAssessment, 'explanation'> {
+    explanation?: WorkflowDecisionExplanation<ApiRequestMediaTypeEvidence>;
+}
+export interface ApiRequestMediaTypeDecisionFields {
+    operation: ApiOperationKey;
+    declaredMediaTypes: string[];
+}
+export type ApiRequestMediaTypeDecision = ApiRequestMediaTypeDecisionFields & ({
+    kind: 'no-request-body';
+    requestMediaType?: never;
+} | {
+    kind: 'single-declared-format';
+    requestMediaType: string;
+} | {
+    kind: 'model-selection';
+    requestMediaType: string;
+    assessment: ApiRequestMediaTypeAssessment & {
+        requestMediaType: string;
+    };
+} | {
+    kind: 'documented-default';
+    requestMediaType: string;
+    policy: 'json-form-concrete-wildcard-code-point';
+    assessment: ApiRequestMediaTypeAssessment & {
+        requestMediaType: null;
+    };
+});
+export interface CreateApiRequestMediaTypeDecisionInput extends ApiRequestMediaTypeContextInput {
+    assessment?: ProposedApiRequestMediaTypeAssessment;
+}
+export interface ValidateApiRequestMediaTypeDecisionInput extends ApiRequestMediaTypeContextInput {
+    decision: ApiRequestMediaTypeDecision;
+}

package/dist/types/api-request-media-type-decision.js

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

package/dist/types/api-selection-evidence.d.ts

@@ -0,0 +1,29 @@
+import type { ApiOperationCandidate, ApiOperationKey } from './api-catalog.js';
+import type { WorkflowDecisionExplanation } from './workflow-clarification.js';
+/** Discovery metadata is not a resolved request/response/security contract. */
+export interface ApiSelectionContext {
+    scenario: string;
+    operations: ApiOperationCandidate[];
+}
+export type ApiSelectionEvidence = {
+    kind: 'scenario';
+    text: string;
+} | {
+    kind: 'discovery';
+    candidates: ApiOperationCandidate[];
+};
+export type ApiSelectionExplanation = WorkflowDecisionExplanation<ApiSelectionEvidence>;
+export type ApiSelectionExplanationBasis = {
+    kind: 'catalog';
+} | {
+    kind: 'candidates';
+    operations: ApiOperationKey[];
+};
+export interface CreateApiSelectionExplanationInput {
+    context: ApiSelectionContext;
+    basis: ApiSelectionExplanationBasis;
+    reason: string;
+}
+export interface ValidateApiSelectionExplanationInput extends Omit<CreateApiSelectionExplanationInput, 'reason'> {
+    explanation: ApiSelectionExplanation;
+}