@openapi-flow/core 0.3.4 → 0.3.6

package/README.md

@@ -2,7 +2,7 @@
 
 Zod `^4.6.5` is a required peer, shared with the host rather than installed as a separately pinned runtime copy. Development tests use 4.6.5; the strict installed-consumer check also uses the host's 4.6.7. This preserves the public schema type boundary without casts or dependency overrides.
 
-Version **0.3.4**. Canonical draft, clarification and runtime-input APIs described below are included in this release. Ajv 8.20.0 does not correctly validate a declared `properties.__proto__`; generated validation may reject valid data or omit that property's constraints. This previously accepted limitation remains unchanged, without renaming data or skipping its failing regression. See the [release record](https://github.com/carefreelife98/openapi-flow/blob/main/docs/releases/0.3.4.md).
+Version **0.3.5**. Canonical draft, clarification and runtime-input APIs described below are included in this release source. Original-choice follow-ups now derive their display and typed reply in Core. Ajv 8.20.0 does not correctly validate a declared `properties.__proto__`; generated validation may reject valid data or omit that property's constraints. This previously accepted limitation remains unchanged, without renaming data or skipping its failing regression. See the [release record](https://github.com/carefreelife98/openapi-flow/blob/main/docs/releases/0.3.5.md) for publication and host status.
 
 Native and fixed-material connection planning accept the optional, existing `WorkflowEntryPointContract` as `entrypoint`. Core validates and snapshots this owner-provided start alongside the other inputs; it does not infer one when absent, add a selectable trigger or let model output modify it.
 

package/dist/public-api.d.ts

@@ -249,10 +249,17 @@ export { createResponseValueSchema } from './openapi/response/create-response-va
 export { listApiResponsePointers } from './openapi/response/list-api-response-pointers.js';
 export type * from './types/api-response-pointers.js';
 export type * from './types/workflow-review-suggestions.js';
+export type * from './types/workflow-review-feedback.js';
+export { workflowReviewFeedbackSchema, createWorkflowReviewFeedbackSchema, } from './schemas/workflow-review-feedback-schema.js';
+export { createWorkflowReviewFeedback } from './review/feedback/create-workflow-review-feedback.js';
+export { isWorkflowReviewFeedback } from './review/feedback/is-workflow-review-feedback.js';
 export { describeWorkflowReviewSuggestions } from './review/suggestions/describe-workflow-review-suggestions.js';
 export { createWorkflowReviewSuggestions } from './review/suggestions/create-workflow-review-suggestions.js';
+export { createWorkflowReviewChoiceSuggestion } from './review/suggestions/create-workflow-review-choice-suggestion.js';
 export { validateWorkflowReviewSuggestions } from './review/suggestions/validate-workflow-review-suggestions.js';
 export { adoptWorkflowReviewSuggestion } from './review/suggestions/adopt-workflow-review-suggestion.js';
 export { readWorkflowReviewSuggestionLimits } from './review/suggestions/read-workflow-review-suggestion-limits.js';
 export { createWorkflowReviewSuggestionsProposalSchema } from './schemas/create-workflow-review-suggestions-proposal-schema.js';
+export { createWorkflowReviewSuggestionFieldsSchema } from './schemas/workflow-review-suggestion-fields-schema.js';
+export { createWorkflowReviewChoiceSuggestionSchema } from './schemas/workflow-review-choice-suggestion-schema.js';
 export { workflowReviewSuggestionLimitsSchema, workflowReviewSuggestionOptionsSchema, } from './schemas/workflow-review-suggestion-settings-schema.js';

package/dist/public-api.js

@@ -187,10 +187,16 @@ export { createResponseArrayItemSchema } from './openapi/response/create-respons
 export { createNativeArrayItemSchema } from './bindings/create-native-array-item-schema.js';
 export { createResponseValueSchema } from './openapi/response/create-response-value-schema.js';
 export { listApiResponsePointers } from './openapi/response/list-api-response-pointers.js';
+export { workflowReviewFeedbackSchema, createWorkflowReviewFeedbackSchema, } from './schemas/workflow-review-feedback-schema.js';
+export { createWorkflowReviewFeedback } from './review/feedback/create-workflow-review-feedback.js';
+export { isWorkflowReviewFeedback } from './review/feedback/is-workflow-review-feedback.js';
 export { describeWorkflowReviewSuggestions } from './review/suggestions/describe-workflow-review-suggestions.js';
 export { createWorkflowReviewSuggestions } from './review/suggestions/create-workflow-review-suggestions.js';
+export { createWorkflowReviewChoiceSuggestion } from './review/suggestions/create-workflow-review-choice-suggestion.js';
 export { validateWorkflowReviewSuggestions } from './review/suggestions/validate-workflow-review-suggestions.js';
 export { adoptWorkflowReviewSuggestion } from './review/suggestions/adopt-workflow-review-suggestion.js';
 export { readWorkflowReviewSuggestionLimits } from './review/suggestions/read-workflow-review-suggestion-limits.js';
 export { createWorkflowReviewSuggestionsProposalSchema } from './schemas/create-workflow-review-suggestions-proposal-schema.js';
+export { createWorkflowReviewSuggestionFieldsSchema } from './schemas/workflow-review-suggestion-fields-schema.js';
+export { createWorkflowReviewChoiceSuggestionSchema } from './schemas/workflow-review-choice-suggestion-schema.js';
 export { workflowReviewSuggestionLimitsSchema, workflowReviewSuggestionOptionsSchema, } from './schemas/workflow-review-suggestion-settings-schema.js';

package/dist/requirements/clarification/build-workflow-clarification-resolution.js

@@ -20,7 +20,8 @@ export function buildWorkflowClarificationResolution(input) {
             continue;
         if (reply.kind === 'defer')
             continue;
-        if (reply.kind !== question.answer.kind)
+        // Offered controls constrain choice IDs, not an explicitly authored human text answer.
+        if (reply.kind !== 'text' && reply.kind !== question.answer.kind)
             throw new Error(`Clarification reply ${reply.questionId} must use ${question.answer.kind}`);
         let answerText;
         if (reply.kind === 'text')

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

@@ -0,0 +1,3 @@
+import type { CreateWorkflowReviewFeedbackInput, WorkflowReviewFeedbackReceipt } from '../../types/workflow-review-feedback.js';
+/** Validate explicit human intent and retain its source, without choosing or approving anything. */
+export declare function createWorkflowReviewFeedback(input: CreateWorkflowReviewFeedbackInput): WorkflowReviewFeedbackReceipt;

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

@@ -0,0 +1,21 @@
+import { createWorkflowReviewFeedbackSchema } from '../../schemas/workflow-review-feedback-schema.js';
+import { planningEvidenceTextSchema } from '../../schemas/planning-evidence-schema.js';
+/** Validate explicit human intent and retain its source, without choosing or approving anything. */
+export function createWorkflowReviewFeedback(input) {
+    const feedback = createWorkflowReviewFeedbackSchema(input.boundary).parse(input.feedback);
+    const messageId = planningEvidenceTextSchema.parse(input.messageId);
+    const question = feedback.scope.kind === 'question'
+        ? input.boundary.questions.find((entry) => feedback.scope.kind === 'question' &&
+            entry.id === feedback.scope.questionId)
+        : undefined;
+    if (feedback.scope.kind === 'question' && question === undefined)
+        throw new Error(`Review feedback is missing original question ${feedback.scope.questionId}`);
+    return {
+        boundaryKey: feedback.boundaryKey,
+        boundaryKind: input.boundary.kind,
+        expectedRevision: feedback.expectedRevision,
+        scope: structuredClone(feedback.scope),
+        ...(question === undefined ? {} : { question: structuredClone(question) }),
+        message: { id: messageId, text: feedback.text },
+    };
+}

package/dist/review/feedback/is-workflow-review-feedback.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowReviewFeedback } from '../../types/workflow-review-feedback.js';
+/** Structural dispatch only. Acceptance still requires the exact current boundary schema. */
+export declare function isWorkflowReviewFeedback(value: unknown): value is WorkflowReviewFeedback;

package/dist/review/feedback/is-workflow-review-feedback.js

@@ -0,0 +1,5 @@
+import { workflowReviewFeedbackSchema } from '../../schemas/workflow-review-feedback-schema.js';
+/** Structural dispatch only. Acceptance still requires the exact current boundary schema. */
+export function isWorkflowReviewFeedback(value) {
+    return workflowReviewFeedbackSchema.safeParse(value).success;
+}

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

@@ -28,6 +28,10 @@ export function adoptWorkflowReviewSuggestion(input) {
                 ...(suggestion.kind === 'answer-question'
                     ? { questionIds: suggestion.questionIds }
                     : {}),
+                ...(suggestion.kind === 'answer-question' &&
+                    suggestion.choiceReply !== undefined
+                    ? { choiceReply: suggestion.choiceReply }
+                    : {}),
                 adoptedText: suggestion.text,
             }),
         },

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

@@ -0,0 +1,3 @@
+import type { CreateWorkflowReviewChoiceSuggestionInput, ProposedWorkflowReviewSuggestion } from '../../types/workflow-review-suggestions.js';
+/** Derive display and a typed reply from the same original contract. This does not submit or adopt the reply. */
+export declare function createWorkflowReviewChoiceSuggestion(input: CreateWorkflowReviewChoiceSuggestionInput): ProposedWorkflowReviewSuggestion;

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

@@ -0,0 +1,39 @@
+import { describeWorkflowReviewSuggestions } from './describe-workflow-review-suggestions.js';
+import { createWorkflowReviewChoiceSuggestionSchema } from '../../schemas/workflow-review-choice-suggestion-schema.js';
+/** Derive display and a typed reply from the same original contract. This does not submit or adopt the reply. */
+export function createWorkflowReviewChoiceSuggestion(input) {
+    const description = describeWorkflowReviewSuggestions(input);
+    const question = description.boundary.questions.find((item) => item.id === input.proposal.questionId);
+    if (question === undefined || question.answer === undefined)
+        throw new Error('Review choice proposal references a missing current choice contract');
+    const answer = question.answer;
+    const proposal = createWorkflowReviewChoiceSuggestionSchema(question, description.options.includeExplanations).parse(input.proposal);
+    const labels = proposal.choiceIds.map((id) => {
+        const choice = answer.choices.find((item) => item.id === id);
+        if (choice === undefined)
+            throw new Error('Review choice proposal references an unknown original choice');
+        return choice.label;
+    });
+    let choiceReply;
+    if (answer.kind === 'single-choice') {
+        const choiceId = proposal.choiceIds[0];
+        if (choiceId === undefined)
+            throw new Error('Review single-choice proposal has no choiceId');
+        choiceReply = { kind: 'single-choice', questionId: question.id, choiceId };
+    }
+    else {
+        choiceReply = {
+            kind: 'multiple-choice',
+            questionId: question.id,
+            choiceIds: [...proposal.choiceIds],
+        };
+    }
+    return {
+        kind: 'answer-question',
+        questionIds: [question.id],
+        text: `${question.message}\n선택: ${labels.join(', ')}`,
+        choiceReply,
+        sources: [{ kind: 'review-question', questionId: question.id }],
+        ...(proposal.reason === undefined ? {} : { reason: proposal.reason }),
+    };
+}

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

@@ -4,12 +4,36 @@ import { describeWorkflowReviewSuggestions } from './describe-workflow-review-su
 import { createWorkflowReviewSuggestionsProposalSchema } from '../../schemas/create-workflow-review-suggestions-proposal-schema.js';
 import { workflowReviewSuggestionEvidenceSchema } from '../../schemas/workflow-review-suggestion-evidence-schema.js';
 import { validateDescribedWorkflowPlanningEvidence } from '../../planning/evidence/validate-workflow-planning-evidence.js';
+import { createWorkflowReviewChoiceSuggestion } from './create-workflow-review-choice-suggestion.js';
 export function createWorkflowReviewSuggestions(input) {
     const description = describeWorkflowReviewSuggestions(input);
     const proposal = createWorkflowReviewSuggestionsProposalSchema(description, workflowReviewSuggestionEvidenceSchema).parse(input.proposal);
     if (!isDeepStrictEqual(proposal, input.proposal))
         throw new Error('Review suggestions must validate without defaults, coercion or transformation');
     for (const suggestion of proposal.suggestions) {
+        if (suggestion.kind === 'answer-question') {
+            if (suggestion.choiceReply !== undefined) {
+                const reply = suggestion.choiceReply;
+                const expected = createWorkflowReviewChoiceSuggestion({
+                    ...input,
+                    proposal: {
+                        kind: 'answer-choice',
+                        questionId: reply.questionId,
+                        choiceIds: reply.kind === 'single-choice'
+                            ? [reply.choiceId]
+                            : reply.choiceIds,
+                        ...(suggestion.reason === undefined
+                            ? {}
+                            : { reason: suggestion.reason }),
+                    },
+                });
+                if (!isDeepStrictEqual(suggestion, expected))
+                    throw new Error('Typed review choice suggestion must keep its original derived text, reply and question sources');
+            }
+            else if (suggestion.questionIds.some((id) => description.boundary.questions.find((question) => question.id === id)?.answer !== undefined)) {
+                throw new Error('Choice-backed review questions require a typed choiceReply');
+            }
+        }
         const keys = suggestion.sources.map((source) => JSON.stringify(source));
         if (new Set(keys).size !== keys.length)
             throw new Error('Review suggestion evidence must not repeat identical sources');

package/dist/schemas/create-workflow-review-suggestions-proposal-schema.js

@@ -1,25 +1,13 @@
 import { z } from 'zod';
 import { workflowReviewBoundarySchema, workflowReviewSuggestionLimitsSchema, workflowReviewSuggestionOptionsSchema, } from './workflow-review-suggestion-settings-schema.js';
+import { createWorkflowReviewSuggestionFieldsSchema } from './workflow-review-suggestion-fields-schema.js';
+import { workflowReviewChoiceReplySchema } from './workflow-review-choice-suggestion-schema.js';
 /** Only user-facing proposed messages and actual source choices are model-owned. */
 export function createWorkflowReviewSuggestionsProposalSchema(description, evidenceSchema) {
     workflowReviewBoundarySchema.parse(description.boundary);
     workflowReviewSuggestionLimitsSchema.parse(description.limits);
     workflowReviewSuggestionOptionsSchema.parse(description.options);
-    const fields = {
-        text: z
-            .string()
-            .refine((text) => text.trim().length > 0)
-            .describe("A concrete optional message in the user's language. Not a confirmed instruction, a workflow, a value default or a credential. Do not expose internal candidate IDs or bookkeeping references here; use structured sources. Do not present unapproved review assumptions as existing user intent."),
-        sources: z.array(evidenceSchema).min(1),
-        ...(description.options.includeExplanations
-            ? {
-                reason: z
-                    .string()
-                    .min(1)
-                    .describe("Concise relevance in the user's language, not private chain-of-thought. Distinguish actual message evidence from unapproved review material; do not claim the user requested a candidate's assumptions. Keep internal candidate IDs and source bookkeeping in structured sources only."),
-            }
-            : {}),
-    };
+    const fields = createWorkflowReviewSuggestionFieldsSchema(description.options, evidenceSchema).shape;
     const choices = [
         z.strictObject({ kind: z.literal('change-request'), ...fields }),
     ];
@@ -32,6 +20,7 @@ export function createWorkflowReviewSuggestionsProposalSchema(description, evide
                 .array(z.enum(description.boundary.questions.map((question) => question.id)))
                 .min(1)
                 .refine((ids) => new Set(ids).size === ids.length),
+            choiceReply: workflowReviewChoiceReplySchema.optional(),
             ...fields,
         }));
     const suggestion = z.union(choices);

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

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+import type { WorkflowReviewQuestion, ProposedWorkflowReviewChoiceSuggestion } from '../types/workflow-review-suggestions.js';
+export declare const workflowReviewChoiceReplySchema: z.ZodUnion<readonly [z.ZodObject<{
+    kind: z.ZodLiteral<"single-choice">;
+    questionId: z.ZodString;
+    choiceId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"multiple-choice">;
+    questionId: z.ZodString;
+    choiceIds: z.ZodArray<z.ZodString>;
+}, z.core.$strict>]>;
+/** One current question, bounded original choices; the model cannot generate its sentence or sources. */
+export declare function createWorkflowReviewChoiceSuggestionSchema(question: WorkflowReviewQuestion, includeExplanations: boolean): z.ZodType<ProposedWorkflowReviewChoiceSuggestion>;

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

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+import { workflowClarificationReplySchema } from './workflow-clarification-reply-schema.js';
+import { workflowReviewQuestionSchema } from './workflow-review-suggestion-settings-schema.js';
+import { workflowReviewSuggestionReasonSchema } from './workflow-review-suggestion-fields-schema.js';
+export const workflowReviewChoiceReplySchema = z.union([
+    workflowClarificationReplySchema.options[0],
+    workflowClarificationReplySchema.options[1],
+]);
+/** One current question, bounded original choices; the model cannot generate its sentence or sources. */
+export function createWorkflowReviewChoiceSuggestionSchema(question, includeExplanations) {
+    const original = workflowReviewQuestionSchema.parse(question);
+    z.boolean().parse(includeExplanations);
+    if (original.answer === undefined)
+        throw new Error('Review choice suggestions require an original choice answer contract');
+    const ids = original.answer.choices.map((choice) => choice.id);
+    const base = z.strictObject({
+        kind: z.literal('answer-choice'),
+        questionId: z
+            .literal(original.id)
+            .describe('The exact supplied current question ID, not a new question.'),
+        choiceIds: z
+            .array(z.enum(ids))
+            .min(1)
+            .max(original.answer.kind === 'single-choice' ? 1 : ids.length)
+            .refine((choices) => new Set(choices).size === choices.length)
+            .describe('Select distinct IDs from this original question. Propose an optional answer; do not submit it, invent a choice, rewrite its label or infer an API binding.'),
+    });
+    return includeExplanations
+        ? base.extend({ reason: workflowReviewSuggestionReasonSchema })
+        : base;
+}

package/dist/schemas/workflow-review-feedback-schema.d.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+import type { WorkflowReviewBoundary } from '../types/workflow-review-suggestions.js';
+export declare const workflowReviewFeedbackSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"review-feedback">;
+    boundaryKey: z.ZodString;
+    expectedRevision: z.ZodNumber;
+    scope: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"review">;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"question">;
+        questionId: z.ZodString;
+    }, z.core.$strict>], "kind">;
+    text: z.ZodString;
+}, z.core.$strict>;
+/** Derive exact review/question identities from the caller's current source-owned boundary. */
+export declare function createWorkflowReviewFeedbackSchema(input: WorkflowReviewBoundary): z.ZodObject<{
+    kind: z.ZodLiteral<"review-feedback">;
+    text: z.ZodString;
+    boundaryKey: z.ZodLiteral<string>;
+    expectedRevision: z.ZodLiteral<number>;
+    scope: z.ZodObject<{
+        kind: z.ZodLiteral<"review">;
+    }, z.core.$strict> | z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"review">;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"question">;
+        questionId: z.ZodEnum<{
+            [x: string]: string;
+        }>;
+    }, z.core.$strict>], "kind">;
+}, z.core.$strict>;

package/dist/schemas/workflow-review-feedback-schema.js

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+import { planningEvidenceTextSchema } from './planning-evidence-schema.js';
+import { workflowReviewBoundarySchema } from './workflow-review-suggestion-settings-schema.js';
+export const workflowReviewFeedbackSchema = z.strictObject({
+    kind: z.literal('review-feedback'),
+    boundaryKey: planningEvidenceTextSchema,
+    expectedRevision: z.number().int().nonnegative(),
+    scope: z.discriminatedUnion('kind', [
+        z.strictObject({ kind: z.literal('review') }),
+        z.strictObject({
+            kind: z.literal('question'),
+            questionId: planningEvidenceTextSchema,
+        }),
+    ]),
+    text: planningEvidenceTextSchema,
+});
+/** Derive exact review/question identities from the caller's current source-owned boundary. */
+export function createWorkflowReviewFeedbackSchema(input) {
+    const boundary = workflowReviewBoundarySchema.parse(input);
+    const reviewScope = z.strictObject({ kind: z.literal('review') });
+    const scope = boundary.questions.length === 0
+        ? reviewScope
+        : z.discriminatedUnion('kind', [
+            reviewScope,
+            z.strictObject({
+                kind: z.literal('question'),
+                questionId: z.enum(boundary.questions.map((question) => question.id)),
+            }),
+        ]);
+    return workflowReviewFeedbackSchema.extend({
+        boundaryKey: z.literal(boundary.key),
+        expectedRevision: z.literal(boundary.revision),
+        scope,
+    });
+}

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

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+import type { ResolvedWorkflowReviewSuggestionOptions } from '../types/workflow-review-suggestions.js';
+export declare const workflowReviewSuggestionReasonSchema: z.ZodString;
+export declare function createWorkflowReviewSuggestionFieldsSchema<Evidence>(options: ResolvedWorkflowReviewSuggestionOptions, evidenceSchema: z.ZodType<Evidence>): z.ZodObject<{
+    reason?: z.ZodString | undefined;
+    text: z.ZodString;
+    sources: z.ZodArray<z.ZodType<Evidence, unknown, z.core.$ZodTypeInternals<Evidence, unknown>>>;
+}, z.core.$strict>;

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

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+export const workflowReviewSuggestionReasonSchema = z
+    .string()
+    .min(1)
+    .describe("Concise relevance in the user's language, not private chain-of-thought. Distinguish actual message evidence from unapproved review material; do not claim the user requested a candidate's assumptions. Keep internal candidate IDs and source bookkeeping in structured sources only.");
+export function createWorkflowReviewSuggestionFieldsSchema(options, evidenceSchema) {
+    return z.strictObject({
+        text: z
+            .string()
+            .refine((text) => text.trim().length > 0)
+            .describe("A concrete optional message in the user's language. Not a confirmed instruction, a workflow, a value default or a credential. Do not expose internal candidate IDs or bookkeeping references here; use structured sources. Do not present unapproved review assumptions as existing user intent."),
+        sources: z.array(evidenceSchema).min(1),
+        ...(options.includeExplanations
+            ? { reason: workflowReviewSuggestionReasonSchema }
+            : {}),
+    });
+}

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

@@ -6,6 +6,20 @@ export declare const workflowReviewSuggestionOptionsSchema: z.ZodObject<{
     includeExplanations: z.ZodDefault<z.ZodBoolean>;
     includeExtensions: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strict>;
+export declare const workflowReviewQuestionSchema: z.ZodObject<{
+    id: z.ZodString;
+    message: z.ZodString;
+    answer: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodEnum<{
+            "single-choice": "single-choice";
+            "multiple-choice": "multiple-choice";
+        }>;
+        choices: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
 export declare const workflowReviewBoundarySchema: z.ZodObject<{
     key: z.ZodString;
     kind: z.ZodEnum<{
@@ -18,6 +32,16 @@ export declare const workflowReviewBoundarySchema: z.ZodObject<{
     questions: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         message: z.ZodString;
+        answer: z.ZodOptional<z.ZodObject<{
+            kind: z.ZodEnum<{
+                "single-choice": "single-choice";
+                "multiple-choice": "multiple-choice";
+            }>;
+            choices: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                label: z.ZodString;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
     }, z.core.$strict>>;
     data: z.ZodJSONSchema;
 }, z.core.$strict>;

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

@@ -6,6 +6,22 @@ export const workflowReviewSuggestionOptionsSchema = z.strictObject({
     includeExplanations: z.boolean().default(true),
     includeExtensions: z.boolean().default(true),
 });
+export const workflowReviewQuestionSchema = z.strictObject({
+    id: z.string().min(1),
+    message: z.string().refine((value) => value.trim().length > 0),
+    answer: z
+        .strictObject({
+        kind: z.enum(['single-choice', 'multiple-choice']),
+        choices: z
+            .array(z.strictObject({
+            id: z.string().min(1),
+            label: z.string().refine((value) => value.trim().length > 0),
+        }))
+            .min(1)
+            .refine((choices) => new Set(choices.map((choice) => choice.id)).size === choices.length),
+    })
+        .optional(),
+});
 export const workflowReviewBoundarySchema = z.strictObject({
     key: z.string().refine((value) => value.trim().length > 0),
     kind: z.enum([
@@ -16,10 +32,7 @@ export const workflowReviewBoundarySchema = z.strictObject({
     ]),
     revision: z.number().int().nonnegative(),
     questions: z
-        .array(z.strictObject({
-        id: z.string().min(1),
-        message: z.string().refine((value) => value.trim().length > 0),
-    }))
+        .array(workflowReviewQuestionSchema)
         .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

@@ -8,6 +8,16 @@ export declare const workflowReviewSuggestionsRecordSchema: z.ZodObject<{
         questions: z.ZodArray<z.ZodObject<{
             id: z.ZodString;
             message: z.ZodString;
+            answer: z.ZodOptional<z.ZodObject<{
+                kind: z.ZodEnum<{
+                    "single-choice": "single-choice";
+                    "multiple-choice": "multiple-choice";
+                }>;
+                choices: z.ZodArray<z.ZodObject<{
+                    id: z.ZodString;
+                    label: z.ZodString;
+                }, z.core.$strict>>;
+            }, z.core.$strict>>;
         }, z.core.$strict>>;
         kind: z.ZodEnum<{
             "requirements-clarification": "requirements-clarification";

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

@@ -103,7 +103,9 @@ export type WorkflowClarificationReply = {
     kind: 'multiple-choice';
     questionId: string;
     choiceIds: string[];
-} | {
+}
+/** Explicit human text may answer any question; it is never converted to a choice ID. */
+ | {
     kind: 'text';
     questionId: string;
     text: string;

package/dist/types/workflow-review-feedback.d.ts

@@ -0,0 +1,30 @@
+import type { WorkflowReviewBoundary, WorkflowReviewQuestion } from './workflow-review-suggestions.js';
+import type { WorkflowSourceMessage } from './workflow-draft.js';
+export type WorkflowReviewFeedbackScope = {
+    kind: 'review';
+} | {
+    kind: 'question';
+    questionId: WorkflowReviewQuestion['id'];
+};
+/** Human-authored feedback is never a choice, a literal API value, or an approval. */
+export interface WorkflowReviewFeedback {
+    kind: 'review-feedback';
+    boundaryKey: WorkflowReviewBoundary['key'];
+    expectedRevision: WorkflowReviewBoundary['revision'];
+    scope: WorkflowReviewFeedbackScope;
+    text: string;
+}
+export interface CreateWorkflowReviewFeedbackInput {
+    boundary: WorkflowReviewBoundary;
+    feedback: WorkflowReviewFeedback;
+    messageId: WorkflowSourceMessage['id'];
+}
+/** The host decides which planning stage to revisit. This receipt applies no graph edit. */
+export interface WorkflowReviewFeedbackReceipt {
+    boundaryKey: WorkflowReviewBoundary['key'];
+    boundaryKind: WorkflowReviewBoundary['kind'];
+    expectedRevision: WorkflowReviewBoundary['revision'];
+    scope: WorkflowReviewFeedbackScope;
+    question?: WorkflowReviewQuestion;
+    message: WorkflowSourceMessage;
+}

package/dist/types/workflow-review-feedback.js

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

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

@@ -1,9 +1,20 @@
 import type { JsonValue } from './api-arguments.js';
 import type { WorkflowPlanningContext, WorkflowPlanningContextDescription, WorkflowPlanningEvidence } from './planning-evidence.js';
 import type { WorkflowSourceMessage } from './workflow-draft.js';
+import type { WorkflowClarificationAnswer, WorkflowClarificationChoice, WorkflowClarificationReply } from './workflow-clarification.js';
+export type WorkflowReviewChoice = Pick<WorkflowClarificationChoice, 'id' | 'label'>;
+export interface WorkflowReviewChoiceAnswer {
+    kind: Exclude<WorkflowClarificationAnswer['kind'], 'text'>;
+    choices: WorkflowReviewChoice[];
+}
+export type WorkflowReviewChoiceReply = Extract<WorkflowClarificationReply, {
+    kind: 'single-choice' | 'multiple-choice';
+}>;
 export interface WorkflowReviewQuestion {
     id: string;
     message: string;
+    /** Exact original choices supplied by the host. Omission does not infer a choice contract. */
+    answer?: WorkflowReviewChoiceAnswer;
 }
 /** The host owns this read-only review projection, not an executable plan or a new OAS contract. */
 export interface WorkflowReviewBoundary {
@@ -37,6 +48,8 @@ export type ProposedWorkflowReviewSuggestion<Evidence = WorkflowReviewSuggestion
 } & ({
     kind: 'answer-question';
     questionIds: string[];
+    /** Code-validated original choice, never inferred by parsing the display text. */
+    choiceReply?: WorkflowReviewChoiceReply;
 } | {
     kind: 'change-request' | 'extend-workflow';
 });
@@ -72,6 +85,16 @@ export interface WorkflowReviewSuggestions {
 export interface CreateWorkflowReviewSuggestionsInput extends WorkflowReviewSuggestionsInput {
     proposal: WorkflowReviewSuggestionsProposal;
 }
+/** A wire proposal chooses declared identities, not the derived sentence, sources or human receipt. */
+export interface ProposedWorkflowReviewChoiceSuggestion {
+    kind: 'answer-choice';
+    questionId: string;
+    choiceIds: string[];
+    reason?: string;
+}
+export interface CreateWorkflowReviewChoiceSuggestionInput extends WorkflowReviewSuggestionsInput {
+    proposal: ProposedWorkflowReviewChoiceSuggestion;
+}
 export interface WorkflowReviewSuggestionsValidationInput extends WorkflowReviewSuggestionsInput {
     review: WorkflowReviewSuggestions;
 }

package/package.json

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