@openapi-flow/core 0.3.5 → 0.3.7

package/dist/openapi/selection/resolve-api-operation-choice-answer.d.ts

@@ -0,0 +1,4 @@
+import type { ResolveApiOperationChoiceAnswerInput } from '../../types/api-clarification.js';
+import type { SelectedApiOperation } from '../../types/api-catalog.js';
+/** Resolve only the explicitly declared choice mode; prose never determines cardinality. */
+export declare function resolveApiOperationChoiceAnswer(input: ResolveApiOperationChoiceAnswerInput): SelectedApiOperation[];

package/dist/openapi/selection/resolve-api-operation-choice-answer.js

@@ -0,0 +1,38 @@
+import { apiOperationAnswersSchema } from '../../schemas/api-operation-answers-schema.js';
+import { validateApiSelectionQuestion } from './validate-api-selection-question.js';
+import { apiOperationKeyEquals } from '../catalog/api-operation-key-equals.js';
+/** Resolve only the explicitly declared choice mode; prose never determines cardinality. */
+export function resolveApiOperationChoiceAnswer(input) {
+    const { question } = input;
+    validateApiSelectionQuestion(question);
+    const answer = apiOperationAnswersSchema.element.parse(input.answer);
+    if (answer.questionId !== question.id)
+        throw new Error(`Operation answer questionId does not match ${question.id}`);
+    let keys;
+    if (question.kind === 'operation-choice') {
+        if (!('operation' in answer))
+            throw new Error(`Operation question ${question.id} requires one operation`);
+        keys = [answer.operation];
+    }
+    else if (question.kind === 'operation-multiple-choice') {
+        if (!('operations' in answer))
+            throw new Error(`Operation question ${question.id} requires an operations array`);
+        keys = answer.operations;
+        if (keys.length < question.minSelections ||
+            keys.length > question.maxSelections)
+            throw new Error(`Operation question ${question.id} requires ${question.minSelections}..${question.maxSelections} selections`);
+    }
+    else {
+        throw new Error('Operation question has no supported source-owned choice kind');
+    }
+    const seen = [];
+    return keys.map((key) => {
+        if (seen.some((previous) => apiOperationKeyEquals(previous, key)))
+            throw new Error(`Operation answer ${question.id} contains a duplicate selection`);
+        const candidate = question.candidates.find((item) => apiOperationKeyEquals(item.key, key));
+        if (!candidate)
+            throw new Error(`Operation answer ${question.id} does not match a current offered candidate`);
+        seen.push(key);
+        return { key: structuredClone(candidate.key), purpose: question.purpose };
+    });
+}

package/dist/openapi/selection/resolve-api-selection-answers.js

@@ -1,5 +1,5 @@
 import { apiOperationAnswersSchema } from '../../schemas/api-operation-answers-schema.js';
-import { apiOperationKeyEquals } from '../catalog/api-operation-key-equals.js';
+import { resolveApiOperationChoiceAnswer } from './resolve-api-operation-choice-answer.js';
 import { resolveApiOperations } from '../resolve-api-operations.js';
 export async function resolveApiSelectionAnswers(input) {
     const answers = apiOperationAnswersSchema.parse(input.answers);
@@ -13,13 +13,7 @@ export async function resolveApiSelectionAnswers(input) {
         const question = input.analysis.questions.find((item) => item.id === answer.questionId);
         if (!question || answered.has(answer.questionId))
             throw new Error(`Unknown or duplicate operation question ${answer.questionId}`);
-        const candidate = question.candidates.find((item) => apiOperationKeyEquals(item.key, answer.operation));
-        if (!candidate)
-            throw new Error(`Operation answer ${answer.questionId} does not match a current offered candidate`);
-        operations.push({
-            key: structuredClone(candidate.key),
-            purpose: question.purpose,
-        });
+        operations.push(...resolveApiOperationChoiceAnswer({ question, answer }));
         answered.add(question.id);
     }
     return {

package/dist/openapi/selection/validate-api-selection-question.d.ts

@@ -0,0 +1,2 @@
+import type { ApiSelectionQuestion } from '../../types/api-clarification.js';
+export declare function validateApiSelectionQuestion(question: ApiSelectionQuestion): void;

package/dist/openapi/selection/validate-api-selection-question.js

@@ -0,0 +1,13 @@
+import { apiOperationChoiceBoundsSchema } from '../../schemas/api-operation-choice-bounds-schema.js';
+export function validateApiSelectionQuestion(question) {
+    if (question.kind === 'operation-choice')
+        return;
+    if (question.kind !== 'operation-multiple-choice')
+        throw new Error('Operation question has no supported source-owned choice kind');
+    const bounds = apiOperationChoiceBoundsSchema.parse({
+        minSelections: question.minSelections,
+        maxSelections: question.maxSelections,
+    });
+    if (bounds.maxSelections > question.candidates.length)
+        throw new Error(`Operation question ${question.id} maxSelections exceeds offered candidates`);
+}

package/dist/public-api.d.ts

@@ -39,6 +39,8 @@ export { inspectApiArgumentRequirements } from './arguments/clarification/inspec
 export { validateApiInputAnswers } from './arguments/clarification/validate-api-input-answers.js';
 export { createApiInputAnswersSchema } from './schemas/create-api-input-answers-schema.js';
 export { resolveApiSelectionAnswers } from './openapi/selection/resolve-api-selection-answers.js';
+export { resolveApiOperationChoiceAnswer } from './openapi/selection/resolve-api-operation-choice-answer.js';
+export { validateApiSelectionQuestion } from './openapi/selection/validate-api-selection-question.js';
 export type * from './types/deferred-api-inputs.js';
 export { collectDeferredApiInputSlots } from './inputs/collect-deferred-api-input-slots.js';
 export { createDeferredApiInputsSchema } from './schemas/create-deferred-api-inputs-schema.js';
@@ -249,6 +251,10 @@ 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';

package/dist/public-api.js

@@ -29,6 +29,8 @@ export { inspectApiArgumentRequirements } from './arguments/clarification/inspec
 export { validateApiInputAnswers } from './arguments/clarification/validate-api-input-answers.js';
 export { createApiInputAnswersSchema } from './schemas/create-api-input-answers-schema.js';
 export { resolveApiSelectionAnswers } from './openapi/selection/resolve-api-selection-answers.js';
+export { resolveApiOperationChoiceAnswer } from './openapi/selection/resolve-api-operation-choice-answer.js';
+export { validateApiSelectionQuestion } from './openapi/selection/validate-api-selection-question.js';
 export { collectDeferredApiInputSlots } from './inputs/collect-deferred-api-input-slots.js';
 export { createDeferredApiInputsSchema } from './schemas/create-deferred-api-inputs-schema.js';
 export { inspectDeferredApiInputs } from './inputs/inspect-deferred-api-inputs.js';
@@ -187,6 +189,9 @@ 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';

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/schemas/api-operation-answers-schema.d.ts

@@ -1,9 +1,16 @@
 import { z } from 'zod';
-export declare const apiOperationAnswersSchema: z.ZodArray<z.ZodObject<{
+export declare const apiOperationAnswersSchema: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
     questionId: z.ZodString;
     operation: z.ZodObject<{
         documentId: z.ZodString;
         snapshotId: z.ZodString;
         operationRef: z.ZodString;
     }, z.core.$strict>;
-}, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    questionId: z.ZodString;
+    operations: z.ZodArray<z.ZodObject<{
+        documentId: z.ZodString;
+        snapshotId: z.ZodString;
+        operationRef: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>]>>;

package/dist/schemas/api-operation-answers-schema.js

@@ -1,8 +1,14 @@
 import { z } from 'zod';
 import { apiOperationKeySchema } from './api-operation-key-schema.js';
 export const apiOperationAnswersSchema = z
-    .array(z.strictObject({
-    questionId: z.string().min(1),
-    operation: apiOperationKeySchema,
-}))
+    .array(z.union([
+    z.strictObject({
+        questionId: z.string().min(1),
+        operation: apiOperationKeySchema,
+    }),
+    z.strictObject({
+        questionId: z.string().min(1),
+        operations: z.array(apiOperationKeySchema),
+    }),
+]))
     .min(1);

package/dist/schemas/api-operation-choice-bounds-schema.d.ts

@@ -0,0 +1,5 @@
+import { z } from 'zod';
+export declare const apiOperationChoiceBoundsSchema: z.ZodObject<{
+    minSelections: z.ZodNumber;
+    maxSelections: z.ZodNumber;
+}, z.core.$strict>;

package/dist/schemas/api-operation-choice-bounds-schema.js

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+export const apiOperationChoiceBoundsSchema = z
+    .strictObject({
+    minSelections: z.number().int().nonnegative().safe(),
+    maxSelections: z.number().int().nonnegative().safe(),
+})
+    .refine((bounds) => bounds.minSelections <= bounds.maxSelections, {
+    message: 'minSelections must not exceed maxSelections',
+});

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-suggestions-record-schema.d.ts

@@ -5,6 +5,12 @@ export declare const workflowReviewSuggestionsRecordSchema: z.ZodObject<{
     fingerprint: z.ZodString;
     boundaryKey: z.ZodString;
     target: z.ZodObject<{
+        kind: z.ZodEnum<{
+            "requirements-clarification": "requirements-clarification";
+            "selection-review": "selection-review";
+            "planning-questions": "planning-questions";
+            "candidate-review": "candidate-review";
+        }>;
         questions: z.ZodArray<z.ZodObject<{
             id: z.ZodString;
             message: z.ZodString;
@@ -19,12 +25,6 @@ export declare const workflowReviewSuggestionsRecordSchema: z.ZodObject<{
                 }, z.core.$strict>>;
             }, z.core.$strict>>;
         }, 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>;

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

@@ -65,16 +65,30 @@ export interface ApiOperationChoice {
     candidates: ApiOperationCandidate[];
     explanation?: ApiSelectionExplanation;
 }
+export interface ApiOperationMultipleChoice extends Omit<ApiOperationChoice, 'kind'> {
+    kind: 'operation-multiple-choice';
+    minSelections: number;
+    maxSelections: number;
+}
+export type ApiSelectionQuestion = ApiOperationChoice | ApiOperationMultipleChoice;
 export interface ApiSelectionAnalysis {
     selection: ApiSelection;
-    questions: ApiOperationChoice[];
+    questions: ApiSelectionQuestion[];
 }
 export interface ApiOperationAnswer {
     questionId: string;
     operation: ApiOperationKey;
 }
+export interface ApiOperationMultipleAnswer extends Omit<ApiOperationAnswer, 'operation'> {
+    operations: ApiOperationKey[];
+}
+export type ApiSelectionAnswer = ApiOperationAnswer | ApiOperationMultipleAnswer;
+export interface ResolveApiOperationChoiceAnswerInput {
+    question: ApiSelectionQuestion;
+    answer: ApiSelectionAnswer;
+}
 export interface ResolveApiSelectionAnswersInput {
     catalog: ApiCatalog;
     analysis: ApiSelectionAnalysis;
-    answers: ApiOperationAnswer[];
+    answers: ApiSelectionAnswer[];
 }

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/package.json

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