@openapi-flow/core 0.1.0 → 0.3.0

package/dist/requirements/clarification/create-workflow-clarification-round.js

@@ -0,0 +1,71 @@
+import { createHash } from 'node:crypto';
+import { createWorkflowRequirementsProposalSchema } from '../../schemas/create-workflow-requirements-proposal-schema.js';
+import { workflowPlanningEvidenceSchema } from '../../schemas/planning-evidence-schema.js';
+import { clarificationQuestionLimitsSchema } from '../../schemas/workflow-clarification-settings-schema.js';
+import { workflowPlanningContextFingerprintFromDescription } from '../../planning/evidence/workflow-planning-context-fingerprint.js';
+import { describeWorkflowPlanningContext } from '../../planning/evidence/describe-workflow-planning-context.js';
+import { validateDescribedWorkflowPlanningEvidence } from '../../planning/evidence/validate-workflow-planning-evidence.js';
+import { resolveWorkflowClarificationOptions } from '../configuration/resolve-workflow-clarification-options.js';
+/** The model proposes meaning; code validates sources and owns every identity. */
+export function createWorkflowClarificationRound(input) {
+    const limits = clarificationQuestionLimitsSchema.parse(input.limits);
+    const options = resolveWorkflowClarificationOptions(input.options);
+    const context = describeWorkflowPlanningContext(input.context);
+    const contextFingerprint = workflowPlanningContextFingerprintFromDescription(context);
+    const proposal = createWorkflowRequirementsProposalSchema(limits, options, workflowPlanningEvidenceSchema).parse(input.proposal);
+    const described = [
+        ...proposal.statements,
+        ...proposal.categories,
+        ...proposal.categories.flatMap((category) => category.questions),
+        ...proposal.categories.flatMap((category) => category.questions.flatMap((question) => question.answer.kind === 'text' ? [] : question.answer.choices)),
+        ...(proposal.suggestions ?? []),
+    ];
+    for (const statement of proposal.statements)
+        validateDescribedWorkflowPlanningEvidence(context, statement.sources);
+    for (const item of described)
+        if (item.explanation)
+            validateDescribedWorkflowPlanningEvidence(context, item.explanation.evidence);
+    const id = 'clarification:' +
+        createHash('sha256')
+            .update(JSON.stringify([contextFingerprint, limits, options, proposal]))
+            .digest('hex');
+    return {
+        id,
+        contextFingerprint,
+        sourceMessages: structuredClone(context.messages),
+        limits,
+        options,
+        statements: proposal.statements.map((statement, index) => ({
+            ...statement,
+            id: `${id}:statement:${index + 1}`,
+        })),
+        categories: proposal.categories.map((category, categoryIndex) => ({
+            ...category,
+            id: `${id}:category:${categoryIndex + 1}`,
+            questions: category.questions.map((question, questionIndex) => {
+                const questionId = `${id}:question:${categoryIndex + 1}:${questionIndex + 1}`;
+                return {
+                    ...question,
+                    id: questionId,
+                    answer: question.answer.kind === 'text'
+                        ? question.answer
+                        : {
+                            ...question.answer,
+                            choices: question.answer.choices.map((choice, choiceIndex) => ({
+                                ...choice,
+                                id: `${questionId}:choice:${choiceIndex + 1}`,
+                            })),
+                        },
+                };
+            }),
+        })),
+        ...(proposal.suggestions === undefined
+            ? {}
+            : {
+                suggestions: proposal.suggestions.map((suggestion, index) => ({
+                    ...suggestion,
+                    id: `${id}:suggestion:${index + 1}`,
+                })),
+            }),
+    };
+}

package/dist/requirements/clarification/describe-workflow-draft-clarification.d.ts

@@ -0,0 +1,4 @@
+import type { WorkflowPlanningContext } from '../../types/planning-evidence.js';
+import type { WorkflowDraftClarificationDescription } from '../../types/workflow-draft-clarification.js';
+/** Validate against current declarations and original source messages, never client-edited facts or receipt text. */
+export declare function describeWorkflowDraftClarification(context: WorkflowPlanningContext): WorkflowDraftClarificationDescription | undefined;

package/dist/requirements/clarification/describe-workflow-draft-clarification.js

@@ -0,0 +1,45 @@
+import { isDeepStrictEqual } from 'node:util';
+import { prepareWorkflowDraftClarification } from './prepare-workflow-draft-clarification.js';
+/** Validate against current declarations and original source messages, never client-edited facts or receipt text. */
+export function describeWorkflowDraftClarification(context) {
+    const supplied = context.clarification;
+    if (supplied === undefined)
+        return undefined;
+    if (!supplied ||
+        !supplied.round ||
+        !supplied.resolution ||
+        !Array.isArray(supplied.answerMessages) ||
+        !Array.isArray(supplied.confirmedAnswerMessageIds))
+        throw new Error('planning context.clarification requires round, resolution, answerMessages and confirmedAnswerMessageIds');
+    for (const message of supplied.round.sourceMessages)
+        if (!context.messages.some((current) => isDeepStrictEqual(current, message)))
+            throw new Error(`Draft clarification source message ${message.id} is missing or changed`);
+    const originalContext = {
+        messages: supplied.round.sourceMessages,
+        operations: context.operations,
+        capabilities: context.capabilities,
+        ...(context.entrypoint === undefined
+            ? {}
+            : { entrypoint: context.entrypoint }),
+    };
+    const derived = prepareWorkflowDraftClarification({
+        context: originalContext,
+        round: supplied.round,
+        resolution: supplied.resolution,
+    });
+    if (!isDeepStrictEqual(derived, supplied))
+        throw new Error('Draft clarification data differs from its original validated round and replies');
+    for (const message of derived.answerMessages)
+        if (!context.messages.some((current) => isDeepStrictEqual(current, message)))
+            throw new Error(`Draft clarification reply evidence ${message.id} is missing or changed`);
+    const questions = supplied.round.categories.flatMap((category) => category.questions);
+    return {
+        roundId: supplied.round.id,
+        facts: structuredClone(derived.resolution.facts),
+        pendingQuestions: structuredClone(questions.filter((question) => derived.resolution.pendingQuestionIds.includes(question.id))),
+        deferredQuestions: structuredClone(questions.filter((question) => derived.resolution.deferredQuestionIds.includes(question.id))),
+        requirementsPrompt: derived.resolution.requirementsPrompt,
+        answerMessageIds: derived.answerMessages.map((message) => message.id),
+        confirmedAnswerMessageIds: [...derived.confirmedAnswerMessageIds],
+    };
+}

package/dist/requirements/clarification/format-workflow-requirements-prompt.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowRequirementsPromptInput } from '../../types/workflow-clarification.js';
+/** A readable projection of structured facts, never a second source of truth. */
+export declare function formatWorkflowRequirementsPrompt(input: WorkflowRequirementsPromptInput): string;

package/dist/requirements/clarification/format-workflow-requirements-prompt.js

@@ -0,0 +1,21 @@
+/** A readable projection of structured facts, never a second source of truth. */
+export function formatWorkflowRequirementsPrompt(input) {
+    return [
+        '사용자 원문',
+        ...input.sourceMessages.map((message) => `- [${message.id}] ${message.text}`),
+        '확인된 요구사항',
+        ...input.facts.map((fact) => `- ${fact.text}`),
+        ...(input.pendingQuestions.length
+            ? [
+                '미답변 질문',
+                ...input.pendingQuestions.map((question) => `- ${question.message}`),
+            ]
+            : []),
+        ...(input.deferredQuestions.length
+            ? [
+                '보류한 질문',
+                ...input.deferredQuestions.map((question) => `- ${question.message}`),
+            ]
+            : []),
+    ].join('\n');
+}

package/dist/requirements/clarification/prepare-workflow-draft-clarification.d.ts

@@ -0,0 +1,3 @@
+import type { PrepareWorkflowDraftClarificationInput, WorkflowDraftClarification } from '../../types/workflow-draft-clarification.js';
+/** Re-derive facts and reply evidence from the original round. No summary text is promoted to a user's answer. */
+export declare function prepareWorkflowDraftClarification(input: PrepareWorkflowDraftClarificationInput): WorkflowDraftClarification;

package/dist/requirements/clarification/prepare-workflow-draft-clarification.js

@@ -0,0 +1,42 @@
+import { createHash } from 'node:crypto';
+import { isDeepStrictEqual } from 'node:util';
+import { resolveWorkflowClarificationReplies } from './resolve-workflow-clarification-replies.js';
+/** Re-derive facts and reply evidence from the original round. No summary text is promoted to a user's answer. */
+export function prepareWorkflowDraftClarification(input) {
+    if (input.context.clarification !== undefined)
+        throw new Error('prepareWorkflowDraftClarification.context must be the original question context, not a nested clarified context');
+    const resolution = resolveWorkflowClarificationReplies({
+        round: input.round,
+        context: input.context,
+        replies: input.resolution.replies,
+    });
+    if (!isDeepStrictEqual(resolution, input.resolution))
+        throw new Error('Draft clarification resolution has modified facts, replies, provenance or readiness');
+    const questions = input.round.categories.flatMap((category) => category.questions);
+    const answerMessages = resolution.replies.map((reply) => {
+        const question = questions.find((item) => item.id === reply.questionId);
+        const fact = resolution.facts.find((item) => item.sources.some((source) => source.kind === 'clarification-answer' &&
+            source.questionId === reply.questionId));
+        const text = JSON.stringify({
+            kind: 'clarification-reply-evidence',
+            roundId: input.round.id,
+            questionId: question.id,
+            question: question.message,
+            reply,
+            ...(fact === undefined ? {} : { confirmedFact: fact }),
+        });
+        return {
+            id: 'clarification-reply:' +
+                createHash('sha256').update(text).digest('hex'),
+            text,
+        };
+    });
+    return {
+        round: structuredClone(input.round),
+        resolution,
+        answerMessages,
+        confirmedAnswerMessageIds: answerMessages
+            .filter((_message, index) => resolution.replies[index].kind !== 'defer')
+            .map((message) => message.id),
+    };
+}

package/dist/requirements/clarification/proposal-from-clarification-round.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowClarificationRound, WorkflowRequirementsProposal } from '../../types/workflow-clarification.js';
+/** Remove only the code-owned identities; strict proposal parsing follows. */
+export declare function proposalFromClarificationRound(round: WorkflowClarificationRound): WorkflowRequirementsProposal;

package/dist/requirements/clarification/proposal-from-clarification-round.js

@@ -0,0 +1,28 @@
+function withoutIdentity(part) {
+    const result = { ...part };
+    Reflect.deleteProperty(result, 'id');
+    return result;
+}
+/** Remove only the code-owned identities; strict proposal parsing follows. */
+export function proposalFromClarificationRound(round) {
+    return {
+        statements: round.statements.map(withoutIdentity),
+        categories: round.categories.map((category) => ({
+            ...withoutIdentity(category),
+            questions: category.questions.map((question) => ({
+                ...withoutIdentity(question),
+                answer: question.answer.kind === 'text'
+                    ? question.answer
+                    : {
+                        ...question.answer,
+                        choices: question.answer.choices.map(withoutIdentity),
+                    },
+            })),
+        })),
+        ...(round.suggestions === undefined
+            ? {}
+            : {
+                suggestions: round.suggestions.map(withoutIdentity),
+            }),
+    };
+}

package/dist/requirements/clarification/resolve-workflow-clarification-replies.d.ts

@@ -0,0 +1,3 @@
+import type { ResolveWorkflowClarificationRepliesInput, WorkflowClarificationResolution } from '../../types/workflow-clarification.js';
+/** Retain confirmed answers across partial replies; stale/modified state fails. */
+export declare function resolveWorkflowClarificationReplies(input: ResolveWorkflowClarificationRepliesInput): WorkflowClarificationResolution;

package/dist/requirements/clarification/resolve-workflow-clarification-replies.js

@@ -0,0 +1,31 @@
+import { isDeepStrictEqual } from 'node:util';
+import { workflowClarificationRepliesSchema } from '../../schemas/workflow-clarification-reply-schema.js';
+import { buildWorkflowClarificationResolution } from './build-workflow-clarification-resolution.js';
+import { validateWorkflowClarificationRound } from './validate-workflow-clarification-round.js';
+/** Retain confirmed answers across partial replies; stale/modified state fails. */
+export function resolveWorkflowClarificationReplies(input) {
+    validateWorkflowClarificationRound(input);
+    const replies = workflowClarificationRepliesSchema.parse(input.replies);
+    if (input.previous !== undefined) {
+        if (input.previous.roundId !== input.round.id ||
+            input.previous.contextFingerprint !== input.round.contextFingerprint)
+            throw new Error('Previous clarification resolution belongs to a different round or planning context');
+        const expected = buildWorkflowClarificationResolution({
+            round: input.round,
+            replies: input.previous.replies,
+        });
+        if (!isDeepStrictEqual(expected, input.previous))
+            throw new Error('Previous clarification resolution has modified facts, answers or readiness');
+    }
+    const combined = new Map(input.previous?.replies.map((reply) => [reply.questionId, reply]));
+    for (const reply of replies) {
+        const previous = combined.get(reply.questionId);
+        if (previous && previous.kind !== 'defer')
+            throw new Error(`Clarification question ${reply.questionId} is already answered; start an explicit requirements revision to change it`);
+        combined.set(reply.questionId, reply);
+    }
+    return buildWorkflowClarificationResolution({
+        round: input.round,
+        replies: [...combined.values()],
+    });
+}

package/dist/requirements/clarification/revisions/describe-workflow-clarification-answer-revision.d.ts

@@ -0,0 +1,4 @@
+import type { WorkflowPlanningContext } from '../../../types/planning-evidence.js';
+import type { WorkflowClarificationAnswerRevisionDescription } from '../../../types/workflow-clarification-answer-revision.js';
+/** Describe only already-confirmed questions. Pending answers use the ordinary reply boundary. */
+export declare function describeWorkflowClarificationAnswerRevision(context: WorkflowPlanningContext): WorkflowClarificationAnswerRevisionDescription;

package/dist/requirements/clarification/revisions/describe-workflow-clarification-answer-revision.js

@@ -0,0 +1,18 @@
+import { createHash } from 'node:crypto';
+import { describeWorkflowPlanningContext } from '../../../planning/evidence/describe-workflow-planning-context.js';
+/** Describe only already-confirmed questions. Pending answers use the ordinary reply boundary. */
+export function describeWorkflowClarificationAnswerRevision(context) {
+    const description = describeWorkflowPlanningContext(context);
+    const clarification = context.clarification;
+    if (!clarification)
+        throw new Error('Clarification answer revision requires context.clarification');
+    const replies = clarification.resolution.replies.filter((reply) => reply.kind !== 'defer');
+    return {
+        fingerprint: createHash('sha256')
+            .update(JSON.stringify([description, clarification]))
+            .digest('hex'),
+        roundId: clarification.round.id,
+        questions: structuredClone(clarification.round.categories.flatMap((category) => category.questions.filter((question) => replies.some((reply) => reply.questionId === question.id)))),
+        replies: structuredClone(replies),
+    };
+}

package/dist/requirements/clarification/revisions/revise-workflow-clarification-answers.d.ts

@@ -0,0 +1,3 @@
+import type { ReviseWorkflowClarificationAnswersInput, WorkflowClarificationAnswerRevisionResult } from '../../../types/workflow-clarification-answer-revision.js';
+/** Explicit, atomic answer replacement/reopening. No model call, guessed choice or in-place mutation. */
+export declare function reviseWorkflowClarificationAnswers(input: ReviseWorkflowClarificationAnswersInput): WorkflowClarificationAnswerRevisionResult;

package/dist/requirements/clarification/revisions/revise-workflow-clarification-answers.js

@@ -0,0 +1,91 @@
+import { createHash } from 'node:crypto';
+import { isDeepStrictEqual } from 'node:util';
+import { workflowClarificationAnswerChangesSchema } from '../../../schemas/workflow-clarification-answer-revision-schema.js';
+import { planningEvidenceTextSchema } from '../../../schemas/planning-evidence-schema.js';
+import { describeWorkflowClarificationAnswerRevision } from './describe-workflow-clarification-answer-revision.js';
+import { resolveWorkflowClarificationReplies } from '../resolve-workflow-clarification-replies.js';
+import { prepareWorkflowDraftClarification } from '../prepare-workflow-draft-clarification.js';
+/** Explicit, atomic answer replacement/reopening. No model call, guessed choice or in-place mutation. */
+export function reviseWorkflowClarificationAnswers(input) {
+    const description = describeWorkflowClarificationAnswerRevision(input.context);
+    if (input.fingerprint !== description.fingerprint)
+        throw new Error('Stale clarification answer revision fingerprint');
+    const messageId = planningEvidenceTextSchema.parse(input.messageId);
+    if (input.context.messages.some((message) => message.id === messageId))
+        throw new Error(`Clarification revision message ID already exists: ${messageId}`);
+    const changes = workflowClarificationAnswerChangesSchema.parse(input.changes);
+    const before = structuredClone(input.context.clarification);
+    const replies = new Map(before.resolution.replies.map((reply) => [reply.questionId, reply]));
+    for (const change of changes) {
+        const questionId = change.kind === 'replace-answer'
+            ? change.reply.questionId
+            : change.questionId;
+        if (!description.replies.some((reply) => reply.questionId === questionId))
+            throw new Error(`Clarification revision requires a currently confirmed answer: ${questionId}`);
+        if (change.kind === 'reopen-question')
+            replies.delete(questionId);
+        else {
+            if (isDeepStrictEqual(replies.get(questionId), change.reply))
+                throw new Error(`Clarification answer change is a no-op: ${questionId}`);
+            replies.set(questionId, change.reply);
+        }
+    }
+    const originalContext = {
+        messages: before.round.sourceMessages,
+        ...(input.context.operations === undefined
+            ? {}
+            : { operations: input.context.operations }),
+        ...(input.context.capabilities === undefined
+            ? {}
+            : { capabilities: input.context.capabilities }),
+        ...(input.context.entrypoint === undefined
+            ? {}
+            : { entrypoint: input.context.entrypoint }),
+    };
+    const after = prepareWorkflowDraftClarification({
+        context: originalContext,
+        round: before.round,
+        resolution: resolveWorkflowClarificationReplies({
+            context: originalContext,
+            round: before.round,
+            replies: [...replies.values()],
+        }),
+    });
+    const supersededAnswerMessageIds = before.answerMessages
+        .filter((message) => !after.answerMessages.some((next) => next.id === message.id))
+        .map((message) => message.id);
+    const message = {
+        id: messageId,
+        text: JSON.stringify({
+            kind: 'explicit-clarification-answer-revision',
+            roundId: before.round.id,
+            fingerprint: description.fingerprint,
+            changes,
+        }),
+    };
+    const body = {
+        fingerprint: description.fingerprint,
+        message,
+        changes,
+        before,
+        after,
+        supersededAnswerMessageIds,
+    };
+    const revision = {
+        id: 'clarification-answer-revision:' +
+            createHash('sha256').update(JSON.stringify(body)).digest('hex'),
+        ...body,
+    };
+    const activeMessages = input.context.messages
+        .filter((item) => !supersededAnswerMessageIds.includes(item.id))
+        .map((item) => ({ ...item }));
+    activeMessages.push(message);
+    for (const receipt of after.answerMessages) {
+        const existing = activeMessages.find((item) => item.id === receipt.id);
+        if (existing && !isDeepStrictEqual(existing, receipt))
+            throw new Error(`Clarification answer evidence conflicts with message ${receipt.id}`);
+        if (!existing)
+            activeMessages.push(structuredClone(receipt));
+    }
+    return { revision, activeMessages };
+}

package/dist/requirements/clarification/revisions/validate-workflow-clarification-answer-revision.d.ts

@@ -0,0 +1,3 @@
+import type { ValidateWorkflowClarificationAnswerRevisionInput } from '../../../types/workflow-clarification-answer-revision.js';
+/** Reconstruct against the trusted pre-change context, not a receipt's claimed original state. */
+export declare function validateWorkflowClarificationAnswerRevision(input: ValidateWorkflowClarificationAnswerRevisionInput): void;

package/dist/requirements/clarification/revisions/validate-workflow-clarification-answer-revision.js

@@ -0,0 +1,15 @@
+import { isDeepStrictEqual } from 'node:util';
+import { reviseWorkflowClarificationAnswers } from './revise-workflow-clarification-answers.js';
+/** Reconstruct against the trusted pre-change context, not a receipt's claimed original state. */
+export function validateWorkflowClarificationAnswerRevision(input) {
+    if (!input.revision || !input.revision.message)
+        throw new Error('Clarification answer revision requires its original receipt');
+    const result = reviseWorkflowClarificationAnswers({
+        context: input.context,
+        fingerprint: input.revision.fingerprint,
+        messageId: input.revision.message.id,
+        changes: input.revision.changes,
+    });
+    if (!isDeepStrictEqual(result.revision, input.revision))
+        throw new Error('Clarification answer revision has modified lineage, facts or evidence');
+}

package/dist/requirements/clarification/validate-workflow-clarification-round.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowClarificationRoundInput } from '../../types/workflow-clarification.js';
+/** Host-owned question data must match the current sources and original shape. */
+export declare function validateWorkflowClarificationRound(input: WorkflowClarificationRoundInput): void;

package/dist/requirements/clarification/validate-workflow-clarification-round.js

@@ -0,0 +1,24 @@
+import { isDeepStrictEqual } from 'node:util';
+import { workflowPlanningContextFingerprint } from '../../planning/evidence/workflow-planning-context-fingerprint.js';
+import { createWorkflowClarificationRound } from './create-workflow-clarification-round.js';
+import { proposalFromClarificationRound } from './proposal-from-clarification-round.js';
+/** Host-owned question data must match the current sources and original shape. */
+export function validateWorkflowClarificationRound(input) {
+    const fingerprint = workflowPlanningContextFingerprint(input.context);
+    if (!input.round || input.round.contextFingerprint !== fingerprint)
+        throw new Error('Clarification round is missing or stale for planning context');
+    let expected;
+    try {
+        expected = createWorkflowClarificationRound({
+            context: input.context,
+            limits: input.round.limits,
+            options: input.round.options,
+            proposal: proposalFromClarificationRound(input.round),
+        });
+    }
+    catch (cause) {
+        throw new Error('Invalid clarification round: questions, sources or settings do not match the contract', { cause });
+    }
+    if (!isDeepStrictEqual(expected, input.round))
+        throw new Error('Clarification round has modified identities, fields or settings');
+}

package/dist/requirements/configuration/read-clarification-question-limits.d.ts

@@ -0,0 +1,3 @@
+import type { ClarificationQuestionLimits } from '../../types/workflow-clarification.js';
+/** Read once at the host boundary; no process.env access or silent defaults. */
+export declare function readClarificationQuestionLimits(environment: Record<string, string | undefined>): ClarificationQuestionLimits;

package/dist/requirements/configuration/read-clarification-question-limits.js

@@ -0,0 +1,18 @@
+import { clarificationQuestionLimitsSchema } from '../../schemas/workflow-clarification-settings-schema.js';
+/** Read once at the host boundary; no process.env access or silent defaults. */
+export function readClarificationQuestionLimits(environment) {
+    function read(name) {
+        const value = environment[name];
+        if (typeof value !== 'string' ||
+            !/^[1-9][0-9]*$/.test(value) ||
+            !Number.isSafeInteger(Number(value)))
+            throw new Error(`${name} must be an explicitly configured positive safe integer`);
+        return Number(value);
+    }
+    return clarificationQuestionLimitsSchema.parse({
+        maxCategories: read('OPENAPI_FLOW_CLARIFY_MAX_CATEGORIES'),
+        maxQuestionsPerCategory: read('OPENAPI_FLOW_CLARIFY_MAX_QUESTIONS_PER_CATEGORY'),
+        maxChoicesPerQuestion: read('OPENAPI_FLOW_CLARIFY_MAX_CHOICES_PER_QUESTION'),
+        maxQuestionsPerRound: read('OPENAPI_FLOW_CLARIFY_MAX_QUESTIONS_PER_ROUND'),
+    });
+}

package/dist/requirements/configuration/resolve-workflow-clarification-options.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowClarificationOptions, ResolvedWorkflowClarificationOptions } from '../../types/workflow-clarification.js';
+/** Product-approved optional feature defaults, not recovery of required data. */
+export declare function resolveWorkflowClarificationOptions(input?: WorkflowClarificationOptions): ResolvedWorkflowClarificationOptions;

package/dist/requirements/configuration/resolve-workflow-clarification-options.js

@@ -0,0 +1,13 @@
+import { workflowClarificationOptionsSchema } from '../../schemas/workflow-clarification-settings-schema.js';
+/** Product-approved optional feature defaults, not recovery of required data. */
+export function resolveWorkflowClarificationOptions(input = {}) {
+    const options = workflowClarificationOptionsSchema.parse(input);
+    return {
+        includeExplanations: options.includeExplanations === undefined
+            ? true
+            : options.includeExplanations,
+        includeSuggestions: options.includeSuggestions === undefined
+            ? true
+            : options.includeSuggestions,
+    };
+}

package/dist/review/suggestions/adopt-workflow-review-suggestion.d.ts

@@ -0,0 +1,3 @@
+import type { AdoptWorkflowReviewSuggestionInput, WorkflowReviewSuggestionAdoption } from '../../types/workflow-review-suggestions.js';
+/** The caller must authenticate the human action. This receipt authorizes no implicit graph edit. */
+export declare function adoptWorkflowReviewSuggestion(input: AdoptWorkflowReviewSuggestionInput): WorkflowReviewSuggestionAdoption;

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

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+import { validateWorkflowReviewSuggestions } from './validate-workflow-review-suggestions.js';
+/** The caller must authenticate the human action. This receipt authorizes no implicit graph edit. */
+export function adoptWorkflowReviewSuggestion(input) {
+    validateWorkflowReviewSuggestions(input);
+    const messageId = z
+        .string()
+        .refine((id) => id.trim().length > 0)
+        .parse(input.messageId);
+    if (input.context.messages.some((message) => message.id === messageId))
+        throw new Error(`Review suggestion adoption message id already exists: ${messageId}`);
+    const suggestion = input.review.suggestions.find((item) => item.id === input.suggestionId);
+    if (!suggestion)
+        throw new Error(`Review suggestion adoption references unknown suggestion ${input.suggestionId}`);
+    return {
+        reviewId: input.review.id,
+        suggestionId: suggestion.id,
+        boundaryKey: input.review.boundaryKey,
+        suggestion: structuredClone(suggestion),
+        message: {
+            id: messageId,
+            text: JSON.stringify({
+                kind: 'user-adopted-workflow-review-suggestion',
+                reviewId: input.review.id,
+                suggestionId: suggestion.id,
+                boundaryKey: input.review.boundaryKey,
+                intent: suggestion.kind,
+                ...(suggestion.kind === 'answer-question'
+                    ? { questionIds: suggestion.questionIds }
+                    : {}),
+                adoptedText: suggestion.text,
+            }),
+        },
+    };
+}

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

@@ -0,0 +1,2 @@
+import type { CreateWorkflowReviewSuggestionsInput, WorkflowReviewSuggestions } from '../../types/workflow-review-suggestions.js';
+export declare function createWorkflowReviewSuggestions(input: CreateWorkflowReviewSuggestionsInput): WorkflowReviewSuggestions;

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

@@ -0,0 +1,51 @@
+import { createHash } from 'node:crypto';
+import { isDeepStrictEqual } from 'node:util';
+import { describeWorkflowReviewSuggestions } from './describe-workflow-review-suggestions.js';
+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';
+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) {
+        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');
+        for (const source of suggestion.sources) {
+            if (source.kind === 'review-question') {
+                if (!description.boundary.questions.some((question) => question.id === source.questionId))
+                    throw new Error(`Review suggestion cites unknown current question ${source.questionId}`);
+            }
+            else
+                validateDescribedWorkflowPlanningEvidence(description.context, [
+                    source,
+                ]);
+        }
+        if (suggestion.kind === 'answer-question' &&
+            suggestion.questionIds.some((id) => !suggestion.sources.some((source) => source.kind === 'review-question' && source.questionId === id)))
+            throw new Error('An answer suggestion must cite every actual question it proposes to answer');
+    }
+    const id = 'workflow-review:' +
+        createHash('sha256')
+            .update(JSON.stringify([description.fingerprint, proposal]))
+            .digest('hex');
+    return {
+        id,
+        fingerprint: description.fingerprint,
+        boundaryKey: description.boundary.key,
+        target: {
+            kind: description.boundary.kind,
+            revision: description.boundary.revision,
+            questions: structuredClone(description.boundary.questions),
+            data: structuredClone(description.boundary.data),
+        },
+        limits: description.limits,
+        options: description.options,
+        suggestions: proposal.suggestions.map((suggestion, index) => ({
+            ...suggestion,
+            id: `${id}:suggestion:${index + 1}`,
+        })),
+    };
+}

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

@@ -0,0 +1,2 @@
+import type { WorkflowReviewSuggestionsInput, WorkflowReviewSuggestionsDescription } from '../../types/workflow-review-suggestions.js';
+export declare function describeWorkflowReviewSuggestions(input: WorkflowReviewSuggestionsInput): WorkflowReviewSuggestionsDescription;

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

@@ -0,0 +1,16 @@
+import { createHash } from 'node:crypto';
+import { workflowReviewBoundarySchema, workflowReviewSuggestionLimitsSchema, workflowReviewSuggestionOptionsSchema, } from '../../schemas/workflow-review-suggestion-settings-schema.js';
+import { describeWorkflowPlanningContext } from '../../planning/evidence/describe-workflow-planning-context.js';
+export function describeWorkflowReviewSuggestions(input) {
+    const context = describeWorkflowPlanningContext(input.context);
+    const boundary = workflowReviewBoundarySchema.parse(input.boundary);
+    const limits = workflowReviewSuggestionLimitsSchema.parse(input.limits);
+    const options = workflowReviewSuggestionOptionsSchema.parse(input.options === undefined ? {} : input.options);
+    const described = { context, boundary, limits, options };
+    return {
+        ...described,
+        fingerprint: createHash('sha256')
+            .update(JSON.stringify(described))
+            .digest('hex'),
+    };
+}

package/dist/review/suggestions/read-workflow-review-suggestion-limits.d.ts

@@ -0,0 +1,2 @@
+import type { WorkflowReviewSuggestionEnvironment, WorkflowReviewSuggestionLimits } from '../../types/workflow-review-suggestions.js';
+export declare function readWorkflowReviewSuggestionLimits(environment: WorkflowReviewSuggestionEnvironment): WorkflowReviewSuggestionLimits;

package/dist/review/suggestions/read-workflow-review-suggestion-limits.js

@@ -0,0 +1,10 @@
+import { workflowReviewSuggestionLimitsSchema } from '../../schemas/workflow-review-suggestion-settings-schema.js';
+export function readWorkflowReviewSuggestionLimits(environment) {
+    const name = 'OPENAPI_FLOW_REVIEW_MAX_SUGGESTIONS';
+    const value = environment[name];
+    if (typeof value !== 'string' || !/^[1-9]\d*$/.test(value))
+        throw new Error(`${name} must explicitly provide a positive integer`);
+    return workflowReviewSuggestionLimitsSchema.parse({
+        maxSuggestions: Number(value),
+    });
+}

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

@@ -0,0 +1,2 @@
+import type { WorkflowReviewSuggestionsValidationInput } from '../../types/workflow-review-suggestions.js';
+export declare function validateWorkflowReviewSuggestions(input: WorkflowReviewSuggestionsValidationInput): void;