@openapi-flow/core 0.1.0 → 0.3.0

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

@@ -0,0 +1,67 @@
+import { createHash } from 'node:crypto';
+import { describeWorkflowDraftEditContext } from '../edits/describe-workflow-draft-edit-context.js';
+import { validateWorkflowDraftEditPlan } from '../edits/validate-workflow-draft-edit-plan.js';
+import { describeWorkflowDraftSelectedNodes } from '../edits/describe-workflow-draft-selected-nodes.js';
+/** Facts and question states are code-owned; the remaining choice is their actual semantic scope. */
+export function describeWorkflowDraftClarificationScopes(input) {
+    validateWorkflowDraftEditPlan(input);
+    const described = describeWorkflowDraftEditContext(input);
+    const active = input.context.clarification;
+    const clarification = described.planning.clarification;
+    const requirements = [];
+    if (active && clarification && input.plan.status !== 'no-change') {
+        for (const fact of clarification.facts) {
+            const sourceMessageIds = [
+                ...new Set(fact.sources.map((source) => {
+                    if (source.kind === 'message')
+                        return source.messageId;
+                    const index = active.resolution.replies.findIndex((reply) => reply.questionId === source.questionId);
+                    if (index < 0 || !active.answerMessages[index])
+                        throw new Error(`Clarified fact ${fact.id} requires its original reply evidence`);
+                    return active.answerMessages[index].id;
+                })),
+            ];
+            requirements.push({
+                id: `requirement:${fact.id}`,
+                text: fact.text,
+                state: 'confirmed',
+                sourceMessageIds,
+                origin: {
+                    kind: 'clarification-fact',
+                    roundId: clarification.roundId,
+                    sourceId: fact.id,
+                },
+            });
+        }
+        for (const question of [
+            ...clarification.pendingQuestions,
+            ...clarification.deferredQuestions,
+        ])
+            requirements.push({
+                id: `requirement:${question.id}`,
+                text: question.message,
+                state: active.resolution.deferredQuestionIds.includes(question.id)
+                    ? 'deferred'
+                    : 'needs-clarification',
+                sourceMessageIds: active.round.sourceMessages.map((message) => message.id),
+                origin: {
+                    kind: 'clarification-question',
+                    roundId: clarification.roundId,
+                    sourceId: question.id,
+                },
+            });
+    }
+    const nodes = describeWorkflowDraftSelectedNodes(input);
+    const fields = {
+        requirements,
+        nodes,
+        messages: described.planning.messages.filter((message) => described.requestMessageIds.includes(message.id)),
+        includeExplanations: input.plan.options.includeExplanations,
+    };
+    return {
+        fingerprint: createHash('sha256')
+            .update(JSON.stringify([input.plan.id, described.contextFingerprint, fields]))
+            .digest('hex'),
+        ...fields,
+    };
+}

package/dist/draft/requirements/describe-workflow-draft-requirement-edit.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowDraftRequirementEditInput, WorkflowDraftRequirementEditDescription } from '../../types/workflow-draft-requirement-edit.js';
+/** Typed human answers choose a real final identity, without requiring its executable material. */
+export declare function describeWorkflowDraftRequirementEdit(input: WorkflowDraftRequirementEditInput): WorkflowDraftRequirementEditDescription;

package/dist/draft/requirements/describe-workflow-draft-requirement-edit.js

@@ -0,0 +1,26 @@
+import { describeWorkflowDraftSelectedNodes } from '../edits/describe-workflow-draft-selected-nodes.js';
+import { listRemovedWorkflowDraftRequirements } from './history/list-removed-workflow-draft-requirements.js';
+/** Typed human answers choose a real final identity, without requiring its executable material. */
+export function describeWorkflowDraftRequirementEdit(input) {
+    const nodes = describeWorkflowDraftSelectedNodes(input);
+    const step = input.plan.steps.find((entry) => entry.id === input.stepId);
+    if (!step ||
+        (step.decision.kind !== 'revise-requirement' &&
+            step.decision.kind !== 'restore-requirement'))
+        throw new Error(`Requirement edit ${input.stepId} must name a selected revise-requirement or restore-requirement step`);
+    const requirementId = step.decision.requirementId;
+    const candidates = step.decision.kind === 'restore-requirement'
+        ? listRemovedWorkflowDraftRequirements(input.draft)
+        : input.draft.requirements;
+    const requirement = candidates.find((entry) => entry.id === requirementId);
+    if (!requirement)
+        throw new Error(`Requirement edit ${input.stepId} has no original requirement ${requirementId}`);
+    return {
+        action: step.decision.kind === 'restore-requirement' ? 'restore' : 'revise',
+        planId: input.plan.id,
+        baseRevision: input.plan.baseRevision,
+        stepId: step.id,
+        requirement: structuredClone(requirement),
+        nodes,
+    };
+}

package/dist/draft/requirements/history/append-workflow-draft-requirement-history.d.ts

@@ -0,0 +1,3 @@
+import type { AppendWorkflowDraftRequirementHistoryInput, WorkflowDraftRequirementHistoryEntry } from '../../../types/workflow-draft-requirement-history.js';
+/** Snapshots, source quotes and predecessor identity are code-owned, not model fields. */
+export declare function appendWorkflowDraftRequirementHistory(input: AppendWorkflowDraftRequirementHistoryInput): WorkflowDraftRequirementHistoryEntry;

package/dist/draft/requirements/history/append-workflow-draft-requirement-history.js

@@ -0,0 +1,61 @@
+import { createHash } from 'node:crypto';
+import { isDeepStrictEqual } from 'node:util';
+/** Snapshots, source quotes and predecessor identity are code-owned, not model fields. */
+export function appendWorkflowDraftRequirementHistory(input) {
+    const requirement = input.after === undefined ? input.before : input.after;
+    if (!requirement ||
+        (input.before && input.after && input.before.id !== input.after.id))
+        throw new Error('Requirement history needs an actual unchanged requirement identity');
+    if (input.before &&
+        input.after &&
+        isDeepStrictEqual(input.before, input.after))
+        throw new Error(`Requirement history cannot record a no-op: ${requirement.id}`);
+    if (input.after &&
+        !isDeepStrictEqual(input.sourceMessageIds, input.after.sourceMessageIds))
+        throw new Error(`Requirement history ${requirement.id} must preserve the current requirement sourceMessageIds`);
+    if (!Array.isArray(input.sourceMessageIds) ||
+        !input.sourceMessageIds.length ||
+        new Set(input.sourceMessageIds).size !== input.sourceMessageIds.length)
+        throw new Error('Requirement history needs distinct explicit sourceMessageIds');
+    if (!Array.isArray(input.messages))
+        throw new Error('Requirement history requires context.messages');
+    const evidence = input.sourceMessageIds.map((id) => {
+        const message = input.messages.find((entry) => entry.id === id);
+        if (!message)
+            throw new Error(`Requirement history ${requirement.id} references unknown source message ${id}`);
+        return {
+            kind: 'message',
+            messageId: message.id,
+            quote: message.text,
+        };
+    });
+    const previous = input.history.findLast((entry) => entry.requirementId === requirement.id);
+    const change = input.before === undefined
+        ? {
+            kind: previous === undefined
+                ? 'created'
+                : 'restored',
+            after: structuredClone(input.after),
+        }
+        : input.after === undefined
+            ? { kind: 'removed', before: structuredClone(input.before) }
+            : {
+                kind: 'revised',
+                before: structuredClone(input.before),
+                after: structuredClone(input.after),
+            };
+    const fields = {
+        revision: input.revision,
+        requirementId: requirement.id,
+        ...(previous === undefined ? {} : { previousEntryId: previous.id }),
+        evidence,
+        ...change,
+    };
+    return {
+        id: 'requirement-history:' +
+            createHash('sha256')
+                .update(JSON.stringify([input.draftId, fields]))
+                .digest('hex'),
+        ...fields,
+    };
+}

package/dist/draft/requirements/history/describe-workflow-draft-requirement-history.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowDraftInput } from '../../../types/workflow-draft.js';
+import type { WorkflowDraftRequirementHistoryDescription } from '../../../types/workflow-draft-requirement-history.js';
+export declare function describeWorkflowDraftRequirementHistory(input: WorkflowDraftInput): WorkflowDraftRequirementHistoryDescription;

package/dist/draft/requirements/history/describe-workflow-draft-requirement-history.js

@@ -0,0 +1,22 @@
+import { validateWorkflowDraft } from '../../validate-workflow-draft.js';
+export function describeWorkflowDraftRequirementHistory(input) {
+    validateWorkflowDraft(input);
+    const heads = new Map(input.draft.requirementHistory.map((entry) => [entry.requirementId, entry]));
+    return {
+        draftId: input.draft.id,
+        revision: input.draft.revision,
+        entries: structuredClone(input.draft.requirementHistory),
+        current: [...heads.values()]
+            .filter((entry) => entry.kind !== 'removed')
+            .map((entry) => ({
+            requirementId: entry.requirementId,
+            entryId: entry.id,
+        })),
+        removed: [...heads.values()]
+            .filter((entry) => entry.kind === 'removed')
+            .map((entry) => ({
+            requirementId: entry.requirementId,
+            entryId: entry.id,
+        })),
+    };
+}

package/dist/draft/requirements/history/list-removed-workflow-draft-requirements.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowDraft, WorkflowDraftRequirement } from '../../../types/workflow-draft.js';
+/** Called only after canonical validation; the latest history head owns removal state. */
+export declare function listRemovedWorkflowDraftRequirements(draft: WorkflowDraft): WorkflowDraftRequirement[];

package/dist/draft/requirements/history/list-removed-workflow-draft-requirements.js

@@ -0,0 +1,5 @@
+/** Called only after canonical validation; the latest history head owns removal state. */
+export function listRemovedWorkflowDraftRequirements(draft) {
+    const heads = new Map(draft.requirementHistory.map((entry) => [entry.requirementId, entry]));
+    return [...heads.values()].flatMap((entry) => entry.kind === 'removed' ? [structuredClone(entry.before)] : []);
+}

package/dist/draft/requirements/history/validate-workflow-draft-requirement-history.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowDraftInput } from '../../../types/workflow-draft.js';
+/** Validate the chain and its current projection. Hashes are consistency checks, not authentication. */
+export declare function validateWorkflowDraftRequirementHistory(input: WorkflowDraftInput): void;

package/dist/draft/requirements/history/validate-workflow-draft-requirement-history.js

@@ -0,0 +1,35 @@
+import { isDeepStrictEqual } from 'node:util';
+import { appendWorkflowDraftRequirementHistory } from './append-workflow-draft-requirement-history.js';
+/** Validate the chain and its current projection. Hashes are consistency checks, not authentication. */
+export function validateWorkflowDraftRequirementHistory(input) {
+    const active = new Map();
+    const seen = [];
+    let revision = 0;
+    for (const entry of input.draft.requirementHistory) {
+        if (entry.revision < revision || entry.revision > input.draft.revision)
+            throw new Error(`Requirement history ${entry.requirementId} has an invalid revision`);
+        revision = entry.revision;
+        const after = 'after' in entry ? entry.after : undefined;
+        if (after && after.id !== entry.requirementId)
+            throw new Error('Requirement history snapshot has a different requirementId');
+        const actual = appendWorkflowDraftRequirementHistory({
+            draftId: input.draft.id,
+            revision: entry.revision,
+            history: seen,
+            before: active.get(entry.requirementId),
+            after,
+            sourceMessageIds: entry.evidence.map((item) => item.messageId),
+            messages: input.context.messages,
+        });
+        if (!isDeepStrictEqual(actual, entry))
+            throw new Error(`Requirement history ${entry.requirementId} has changed snapshots, sources, ordering or identity`);
+        if (after)
+            active.set(entry.requirementId, after);
+        else
+            active.delete(entry.requirementId);
+        seen.push(entry);
+    }
+    if (active.size !== input.draft.requirements.length ||
+        input.draft.requirements.some((requirement) => !isDeepStrictEqual(active.get(requirement.id), requirement)))
+        throw new Error('Requirement history does not match the current draft requirements');
+}

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

@@ -0,0 +1,4 @@
+import type { PrepareWorkflowDraftEditInput } from '../../types/workflow-draft-edit-assembly.js';
+import type { WorkflowDraftRequirement } from '../../types/workflow-draft.js';
+/** The receipt is not authority: re-derive exact facts, provenance, states and selected-instance scopes. */
+export declare function projectWorkflowDraftClarificationRequirements(input: PrepareWorkflowDraftEditInput): WorkflowDraftRequirement[];

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

@@ -0,0 +1,24 @@
+import { isDeepStrictEqual } from 'node:util';
+import { describeWorkflowDraftClarificationScopes } from './describe-workflow-draft-clarification-scopes.js';
+import { resolveWorkflowDraftClarificationScopes } from './resolve-workflow-draft-clarification-scopes.js';
+/** The receipt is not authority: re-derive exact facts, provenance, states and selected-instance scopes. */
+export function projectWorkflowDraftClarificationRequirements(input) {
+    if (input.context.clarification === undefined) {
+        if (input.clarificationScopes !== undefined)
+            throw new Error('Clarification scope receipt requires its original context.clarification');
+        return [];
+    }
+    if (input.clarificationScopes === undefined) {
+        if (describeWorkflowDraftClarificationScopes(input).requirements.length)
+            throw new Error('Active clarified facts/questions require an explicit clarificationScopes result before material planning');
+        return [];
+    }
+    const actual = resolveWorkflowDraftClarificationScopes({
+        ...input,
+        fingerprint: input.clarificationScopes.fingerprint,
+        proposal: input.clarificationScopes.proposal,
+    });
+    if (!isDeepStrictEqual(actual, input.clarificationScopes))
+        throw new Error('Clarification scope receipt has modified requirements, states or provenance');
+    return actual.requirements;
+}

package/dist/draft/requirements/resolve-workflow-draft-clarification-scopes.d.ts

@@ -0,0 +1,2 @@
+import type { ResolveWorkflowDraftClarificationScopesInput, ResolvedWorkflowDraftClarificationScopes } from '../../types/workflow-draft-clarification.js';
+export declare function resolveWorkflowDraftClarificationScopes(input: ResolveWorkflowDraftClarificationScopesInput): ResolvedWorkflowDraftClarificationScopes;

package/dist/draft/requirements/resolve-workflow-draft-clarification-scopes.js

@@ -0,0 +1,31 @@
+import { isDeepStrictEqual } from 'node:util';
+import { describeWorkflowDraftClarificationScopes } from './describe-workflow-draft-clarification-scopes.js';
+import { createWorkflowDraftClarificationScopeSchema } from '../../schemas/create-workflow-draft-clarification-scope-schema.js';
+import { validateWorkflowPlanningEvidence } from '../../planning/evidence/validate-workflow-planning-evidence.js';
+export function resolveWorkflowDraftClarificationScopes(input) {
+    const description = describeWorkflowDraftClarificationScopes(input);
+    if (input.fingerprint !== description.fingerprint)
+        throw new Error('Clarification scope fingerprint is stale or describes a different plan, reply or original contract');
+    const proposal = createWorkflowDraftClarificationScopeSchema(input).parse(input.proposal);
+    if (!isDeepStrictEqual(proposal, input.proposal))
+        throw new Error('Clarification scopes must validate without defaults, coercion or output repair');
+    for (const decision of Object.values(proposal.scopes))
+        if (decision.explanation)
+            validateWorkflowPlanningEvidence({
+                context: { messages: description.messages },
+                evidence: decision.explanation.evidence,
+            });
+    return {
+        fingerprint: description.fingerprint,
+        proposal,
+        requirements: description.requirements.flatMap((requirement) => {
+            const scope = proposal.scopes[requirement.id].scope;
+            return scope.kind === 'unselected-work'
+                ? []
+                : [{ ...requirement, scope: structuredClone(scope) }];
+        }),
+        unselectedQuestionIds: description.requirements.flatMap((requirement) => proposal.scopes[requirement.id].scope.kind === 'unselected-work'
+            ? [requirement.origin.sourceId]
+            : []),
+    };
+}

package/dist/draft/resolve-workflow-draft-api-materials.d.ts

@@ -0,0 +1,4 @@
+import type { ResolveWorkflowDraftApiMaterialsInput } from '../types/workflow-draft.js';
+import type { DeferredApiInputMaterial } from '../types/deferred-api-inputs.js';
+/** Resolve content without fabricating canonical revision/approval metadata. */
+export declare function resolveWorkflowDraftApiMaterials(input: ResolveWorkflowDraftApiMaterialsInput): DeferredApiInputMaterial[];

package/dist/draft/resolve-workflow-draft-api-materials.js

@@ -0,0 +1,21 @@
+import { apiOperationKeyEquals } from '../openapi/catalog/api-operation-key-equals.js';
+/** Resolve content without fabricating canonical revision/approval metadata. */
+export function resolveWorkflowDraftApiMaterials(input) {
+    return input.content.apiCalls.map((call) => {
+        const matches = input.context.operations.filter((operation) => apiOperationKeyEquals(operation.key, call.operation));
+        if (matches.length !== 1)
+            throw new Error(`Draft API ${call.id} requires exactly one original OAS contract for its operation and snapshot`);
+        return {
+            operation: matches[0],
+            callId: call.id,
+            values: call.values,
+            bindings: call.bindings,
+            ...(call.requestedInputs === undefined
+                ? {}
+                : { requestedInputs: call.requestedInputs }),
+            ...(call.requestMediaType === undefined
+                ? {}
+                : { requestMediaType: call.requestMediaType }),
+        };
+    });
+}

package/dist/draft/resolve-workflow-draft-materials.d.ts

@@ -0,0 +1,2 @@
+import type { WorkflowDraftInput, WorkflowDraftMaterials } from '../types/workflow-draft.js';
+export declare function resolveWorkflowDraftMaterials(input: WorkflowDraftInput): WorkflowDraftMaterials;

package/dist/draft/resolve-workflow-draft-materials.js

@@ -0,0 +1,29 @@
+import { resolveWorkflowDraftApiMaterials } from './resolve-workflow-draft-api-materials.js';
+import { collectDeferredApiInputSlots } from '../inputs/collect-deferred-api-input-slots.js';
+import { collectNativeRuntimeInputSlots } from '../inputs/native/collect-native-runtime-input-slots.js';
+import { resolveWorkflowDraftNativeSnapshot } from './resolve-workflow-draft-native-snapshot.js';
+import { NativeMaterialResolutionError } from '../workflow/native-material-resolution-error.js';
+export function resolveWorkflowDraftMaterials(input) {
+    if (!input.context || !Array.isArray(input.context.operations))
+        throw new Error('draft context.operations must be an array');
+    const materials = resolveWorkflowDraftApiMaterials({
+        content: input.draft,
+        context: input.context,
+    });
+    const snapshot = resolveWorkflowDraftNativeSnapshot({
+        content: input.draft,
+        context: input.context,
+        deferredNodeIds: [],
+        unavailableApiNodeIds: [],
+    });
+    if (snapshot.status !== 'ready')
+        throw new NativeMaterialResolutionError(snapshot.pending);
+    return {
+        materials,
+        slots: collectDeferredApiInputSlots({ materials }),
+        nativeSlots: collectNativeRuntimeInputSlots({
+            nativeNodes: input.draft.nativeNodes,
+            capabilities: snapshot.capabilities,
+        }),
+    };
+}

package/dist/draft/resolve-workflow-draft-native-snapshot.d.ts

@@ -0,0 +1,3 @@
+import type { ResolveWorkflowDraftNativeSnapshotInput } from '../types/workflow-draft-native-materials.js';
+import type { NativeMaterialSnapshot } from '../types/native-material-snapshot.js';
+export declare function resolveWorkflowDraftNativeSnapshot(input: ResolveWorkflowDraftNativeSnapshotInput): NativeMaterialSnapshot;

package/dist/draft/resolve-workflow-draft-native-snapshot.js

@@ -0,0 +1,18 @@
+import { resolveWorkflowDraftApiMaterials } from './resolve-workflow-draft-api-materials.js';
+import { resolveNativeMaterialSnapshot } from '../workflow/resolve-native-material-snapshot.js';
+export function resolveWorkflowDraftNativeSnapshot(input) {
+    const materials = resolveWorkflowDraftApiMaterials({
+        content: input.content,
+        context: input.context,
+    });
+    return resolveNativeMaterialSnapshot({
+        apiMaterials: materials.filter((material) => !input.unavailableApiNodeIds.includes(material.callId)),
+        nativeOutputs: [],
+        nativeNodes: input.content.nativeNodes,
+        capabilities: input.context.capabilities,
+        deferredNodeIds: input.deferredNodeIds,
+        ...(input.shouldDeferNode === undefined
+            ? {}
+            : { shouldDeferNode: input.shouldDeferNode }),
+    });
+}

package/dist/draft/validate-workflow-draft.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowDraftInput } from '../types/workflow-draft.js';
+/** A canonical draft retains valid structure even while values/decisions await input. */
+export declare function validateWorkflowDraft(input: WorkflowDraftInput): void;

package/dist/draft/validate-workflow-draft.js

@@ -0,0 +1,96 @@
+import { workflowDraftSchema } from '../schemas/workflow-draft-schema.js';
+import { resolveWorkflowDraftMaterials } from './resolve-workflow-draft-materials.js';
+import { validateWorkflowGraphPlan } from '../workflow/validate-workflow-graph-plan.js';
+import { validateWorkflowDraftRequirementHistory } from './requirements/history/validate-workflow-draft-requirement-history.js';
+import { workflowPlanningMessageIdsSchema } from '../schemas/workflow-planning-message-ids-schema.js';
+import { inspectWorkflowDraftCapabilityGap } from './gaps/inspect-workflow-draft-capability-gap.js';
+/** A canonical draft retains valid structure even while values/decisions await input. */
+export function validateWorkflowDraft(input) {
+    const draft = workflowDraftSchema.parse(input.draft);
+    if (!input.context ||
+        !Array.isArray(input.context.operations) ||
+        !Array.isArray(input.context.messages) ||
+        !Array.isArray(input.context.capabilities))
+        throw new Error('draft context.operations, context.messages and context.capabilities must be arrays');
+    const { materials, slots } = resolveWorkflowDraftMaterials({
+        ...input,
+        draft,
+    });
+    const capabilityNames = input.context.capabilities.map((capability) => capability.name);
+    if (new Set(capabilityNames).size !== capabilityNames.length ||
+        capabilityNames.some((name) => typeof name !== 'string' || !name.trim()))
+        throw new Error('draft context.capabilities requires distinct non-empty names');
+    const ids = [
+        ...draft.apiCalls.map((call) => call.id),
+        ...draft.nativeNodes.map((node) => node.id),
+        ...(draft.gapNodes === undefined
+            ? []
+            : draft.gapNodes.map((node) => node.id)),
+    ];
+    const known = new Set(ids);
+    for (const gap of draft.gapNodes === undefined ? [] : draft.gapNodes)
+        inspectWorkflowDraftCapabilityGap({ gap, context: input.context });
+    if (known.size !== ids.length)
+        throw new Error('Draft node IDs must be unique across API and native instances, including unresolved gaps');
+    const messageIds = new Set(input.context.messages.map((message) => message.id));
+    if (messageIds.size !== input.context.messages.length ||
+        input.context.messages.some((message) => !message.id?.trim() || typeof message.text !== 'string'))
+        throw new Error('draft context.messages requires distinct non-empty IDs and text');
+    if (new Set(draft.requirements.map((item) => item.id)).size !==
+        draft.requirements.length)
+        throw new Error('Draft requirements require distinct IDs');
+    if (input.context.planningMessageIds !== undefined &&
+        workflowPlanningMessageIdsSchema
+            .parse(input.context.planningMessageIds)
+            .some((id) => !messageIds.has(id)))
+        throw new Error('draft context.planningMessageIds references an unknown message');
+    for (const requirement of draft.requirements) {
+        if (requirement.sourceMessageIds.some((id) => !messageIds.has(id)))
+            throw new Error(`Requirement ${requirement.id} references an unknown source message`);
+        if (requirement.scope.kind === 'nodes' &&
+            requirement.scope.nodeIds.some((id) => !known.has(id)))
+            throw new Error(`Requirement ${requirement.id} references an unknown node`);
+    }
+    validateWorkflowDraftRequirementHistory({ draft, context: input.context });
+    if (new Set(draft.approvals.map((item) => item.id)).size !==
+        draft.approvals.length)
+        throw new Error('Draft approval IDs must be distinct');
+    for (const approval of draft.approvals) {
+        if (approval.revision > draft.revision ||
+            approval.invalidatedNodeIds.some((id) => !approval.nodeIds.includes(id)) ||
+            approval.nodeIds.some((id) => !known.has(id) && !approval.invalidatedNodeIds.includes(id)))
+            throw new Error(`Draft approval ${approval.id} has invalid revision or scope`);
+    }
+    if (!ids.length) {
+        if (draft.edges.length)
+            throw new Error('An empty draft cannot contain edges');
+        return;
+    }
+    validateWorkflowGraphPlan({
+        unresolvedNodes: draft.gapNodes,
+        capabilities: input.context.capabilities,
+        materials: materials.map((material) => ({
+            operation: material.operation,
+            arguments: {
+                callId: material.callId,
+                values: material.values,
+                bindings: material.bindings,
+                ...(material.requestedInputs === undefined
+                    ? {}
+                    : { requestedInputs: material.requestedInputs }),
+                unresolvedInputs: slots
+                    .filter((slot) => slot.callId === material.callId)
+                    .map((slot) => slot.targetPointer),
+                ...(material.requestMediaType !== undefined
+                    ? { requestMediaType: material.requestMediaType }
+                    : {}),
+            },
+        })),
+        plan: {
+            nativeNodes: draft.nativeNodes,
+            edges: draft.edges,
+            starts: ids.filter((id) => !draft.edges.some((edge) => edge.to === id)),
+            gaps: [],
+        },
+    });
+}

package/dist/inputs/collect-deferred-api-input-slots.d.ts

@@ -0,0 +1,3 @@
+import type { CollectDeferredApiInputSlotsInput, DeferredApiInputSlot } from '../types/deferred-api-inputs.js';
+/** Derive slots from the original OAS and current literal/binding ownership. */
+export declare function collectDeferredApiInputSlots(input: CollectDeferredApiInputSlotsInput): DeferredApiInputSlot[];

package/dist/inputs/collect-deferred-api-input-slots.js

@@ -0,0 +1,35 @@
+import { inspectApiArgumentRequirements } from '../arguments/clarification/inspect-api-argument-requirements.js';
+import { apiOperationKeySchema } from '../schemas/api-operation-key-schema.js';
+/** Derive slots from the original OAS and current literal/binding ownership. */
+export function collectDeferredApiInputSlots(input) {
+    if (!Array.isArray(input.materials))
+        throw new Error('collectDeferredApiInputSlots.materials must be an array');
+    const ids = new Set();
+    return input.materials.flatMap((material) => {
+        if (typeof material.callId !== 'string' ||
+            !material.callId.trim() ||
+            ids.has(material.callId))
+            throw new Error('Input materials require distinct non-empty callIds');
+        ids.add(material.callId);
+        apiOperationKeySchema.parse(material.operation.key);
+        return inspectApiArgumentRequirements(material).requirements.map((requirement) => ({
+            kind: 'api-request-input',
+            state: 'deferred',
+            id: `input:${requirement.id}`,
+            callId: requirement.callId,
+            operation: requirement.operation,
+            targetPointer: requirement.targetPointer,
+            ...(requirement.requestedInputs === undefined
+                ? {}
+                : { requestedInputs: requirement.requestedInputs }),
+            schema: requirement.schema,
+            openapiVersion: requirement.openapiVersion,
+            ...(requirement.operationSummary !== undefined
+                ? { operationSummary: requirement.operationSummary }
+                : {}),
+            ...(requirement.parameterDescription !== undefined
+                ? { parameterDescription: requirement.parameterDescription }
+                : {}),
+        }));
+    });
+}

package/dist/inputs/deferred-api-input-error.d.ts

@@ -0,0 +1,5 @@
+import type { DeferredApiInputIssue } from '../types/deferred-api-inputs.js';
+export declare class DeferredApiInputError extends Error {
+    readonly issues: DeferredApiInputIssue[];
+    constructor(issues: DeferredApiInputIssue[]);
+}

package/dist/inputs/deferred-api-input-error.js

@@ -0,0 +1,8 @@
+export class DeferredApiInputError extends Error {
+    issues;
+    constructor(issues) {
+        super(issues.map((issue) => issue.message).join('; '));
+        this.name = 'DeferredApiInputError';
+        this.issues = structuredClone(issues);
+    }
+}

package/dist/inputs/inspect-deferred-api-inputs.d.ts

@@ -0,0 +1,3 @@
+import type { DeferredApiInputInspection, InspectDeferredApiInputsInput } from '../types/deferred-api-inputs.js';
+/** Missing values are explicit state; malformed supplied values are never repaired. */
+export declare function inspectDeferredApiInputs(input: InspectDeferredApiInputsInput): DeferredApiInputInspection;