@openapi-flow/core 0.3.5 → 0.3.6

package/dist/public-api.d.ts

@@ -249,6 +249,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

@@ -187,6 +187,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/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/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.6",
   "license": "MIT",
   "description": "Engine-independent OpenAPI catalogs, operation contracts and typed request schemas",
   "keywords": [