@openapi-flow/core 0.1.0 → 0.3.0

package/dist/draft/edits/clarification/describe-workflow-draft-clarification-ownership.js

@@ -0,0 +1,69 @@
+import { validateWorkflowDraftEditPlan } from '../validate-workflow-draft-edit-plan.js';
+import { resolveWorkflowDraftClarificationOwnerIndex } from './resolve-workflow-draft-clarification-owner-index.js';
+import { workflowDraftClarificationPlanningStageSchema } from '../../../schemas/workflow-draft-clarification-planning-stage-schema.js';
+/** Retain every declared concern and code-resolve its stage owner; this is not an answer or readiness claim. */
+export function describeWorkflowDraftClarificationOwnership(input) {
+    validateWorkflowDraftEditPlan(input);
+    const stage = workflowDraftClarificationPlanningStageSchema
+        .optional()
+        .safeParse(input.stage);
+    if (!stage.success)
+        throw new Error('Clarification ownership stage is invalid', {
+            cause: stage.error,
+        });
+    if (input.stepId !== undefined &&
+        !input.plan.steps.some((step) => step.id === input.stepId))
+        throw new Error(`Clarification ownership stepId ${input.stepId} must name an actual plan step`);
+    const decisions = input.plan.steps.map((step) => step.decision);
+    const ownership = [];
+    input.plan.steps.forEach((step, index) => {
+        const decision = step.decision;
+        if (decision.kind !== 'needs-clarification')
+            return;
+        const targetIndex = resolveWorkflowDraftClarificationOwnerIndex({
+            decisions,
+            sourceIndex: index,
+        });
+        if (targetIndex === undefined) {
+            if (decision.owner.kind !== 'semantic')
+                throw new Error('A semantic clarification requires its explicit scope');
+            if (input.stage === undefined &&
+                (input.stepId === undefined || input.stepId === step.id))
+                ownership.push({
+                    sourceStepId: step.id,
+                    owner: structuredClone(decision.owner),
+                    instruction: decision.instruction,
+                    sources: structuredClone(decision.sources),
+                    ...(decision.explanation === undefined
+                        ? {}
+                        : { explanation: structuredClone(decision.explanation) }),
+                });
+            return;
+        }
+        const target = input.plan.steps[targetIndex];
+        if (decision.owner.kind !== 'planning-step')
+            throw new Error('An owned clarification requires its explicit planning stage');
+        if (input.stage !== undefined && input.stage !== decision.owner.stage)
+            return;
+        if (input.stepId !== undefined &&
+            input.stepId !== target.id &&
+            input.stepId !== step.id)
+            return;
+        const nodeId = 'nodeId' in target.decision ? target.decision.nodeId : target.newNodeId;
+        ownership.push({
+            sourceStepId: step.id,
+            owner: {
+                kind: 'planning-step',
+                stepId: target.id,
+                ...(nodeId === undefined ? {} : { nodeId }),
+                stage: decision.owner.stage,
+            },
+            instruction: decision.instruction,
+            sources: structuredClone(decision.sources),
+            ...(decision.explanation === undefined
+                ? {}
+                : { explanation: structuredClone(decision.explanation) }),
+        });
+    });
+    return ownership;
+}

package/dist/draft/edits/clarification/resolve-workflow-draft-clarification-owner-index.d.ts

@@ -0,0 +1,3 @@
+import type { ResolveWorkflowDraftClarificationOwnerIndexInput } from '../../../types/workflow-draft-clarification-ownership.js';
+/** Owner references address explicit decisions, never inferred text, material names or guessed IDs. */
+export declare function resolveWorkflowDraftClarificationOwnerIndex(input: ResolveWorkflowDraftClarificationOwnerIndexInput): number | undefined;

package/dist/draft/edits/clarification/resolve-workflow-draft-clarification-owner-index.js

@@ -0,0 +1,21 @@
+import { workflowDraftClarificationStages } from './workflow-draft-clarification-stages.js';
+/** Owner references address explicit decisions, never inferred text, material names or guessed IDs. */
+export function resolveWorkflowDraftClarificationOwnerIndex(input) {
+    const source = input.decisions[input.sourceIndex];
+    if (!source || source.kind !== 'needs-clarification')
+        throw new Error(`Clarification source ${input.sourceIndex} must name a needs-clarification decision`);
+    if (source.owner.kind === 'semantic')
+        return undefined;
+    const index = source.owner.decisionIndex;
+    const target = input.decisions[index];
+    if (!Number.isSafeInteger(index) || index < 0 || !target)
+        throw new Error(`Clarification owner decisionIndex ${index} must name an existing decision`);
+    if (index === input.sourceIndex ||
+        target.kind === 'needs-clarification' ||
+        target.kind === 'no-change' ||
+        target.kind === 'remove-requirement')
+        throw new Error(`Clarification owner decisionIndex ${index} must name an actual value, requirement or connection planning decision`);
+    if (!workflowDraftClarificationStages(target).includes(source.owner.stage))
+        throw new Error(`Clarification owner decisionIndex ${index} has no ${source.owner.stage} planning stage`);
+    return index;
+}

package/dist/draft/edits/clarification/workflow-draft-clarification-stages.d.ts

@@ -0,0 +1,4 @@
+import type { WorkflowDraftEditDecision } from '../../../types/workflow-draft-edit.js';
+import type { WorkflowDraftClarificationPlanningStage } from '../../../types/workflow-draft-clarification-ownership.js';
+/** Direct owner stages only. Consumer repairs are separate code-derived tasks, not the producer's input owner. */
+export declare function workflowDraftClarificationStages(decision: WorkflowDraftEditDecision): WorkflowDraftClarificationPlanningStage[];

package/dist/draft/edits/clarification/workflow-draft-clarification-stages.js

@@ -0,0 +1,26 @@
+/** Direct owner stages only. Consumer repairs are separate code-derived tasks, not the producer's input owner. */
+export function workflowDraftClarificationStages(decision) {
+    switch (decision.kind) {
+        case 'add-api-call':
+        case 'replace-api-operation':
+            return ['api-bindings', 'api-arguments', 'connections'];
+        case 'add-native-node':
+        case 'revise-native-node':
+            return ['native-parameters', 'connections'];
+        case 'revise-api-inputs':
+            return ['api-arguments'];
+        case 'revise-api-bindings':
+            return ['api-bindings', 'connections'];
+        case 'revise-requirement':
+        case 'restore-requirement':
+            return ['requirements'];
+        case 'revise-connections':
+        case 'remove-node':
+        case 'report-capability-gap':
+            return ['connections'];
+        case 'needs-clarification':
+        case 'no-change':
+        case 'remove-requirement':
+            return [];
+    }
+}

package/dist/draft/edits/connections/derive-workflow-draft-node-removal-connections.d.ts

@@ -0,0 +1,4 @@
+import type { ValidateWorkflowDraftEditPlanInput } from '../../../types/workflow-draft-edit.js';
+import type { WorkflowDraftEditConnectionChange } from '../../../types/workflow-draft-edit-assembly.js';
+/** A validated explicit removal owns all incident edges, never replacement routes or other nodes. */
+export declare function deriveWorkflowDraftNodeRemovalConnections(input: ValidateWorkflowDraftEditPlanInput): WorkflowDraftEditConnectionChange[];

package/dist/draft/edits/connections/derive-workflow-draft-node-removal-connections.js

@@ -0,0 +1,14 @@
+/** A validated explicit removal owns all incident edges, never replacement routes or other nodes. */
+export function deriveWorkflowDraftNodeRemovalConnections(input) {
+    const removals = input.plan.steps.filter((step) => step.decision.kind === 'remove-node');
+    return input.draft.edges.flatMap((edge) => {
+        const stepIds = removals
+            .filter((step) => step.decision.kind === 'remove-node' &&
+            (step.decision.nodeId === edge.from ||
+                step.decision.nodeId === edge.to))
+            .map((step) => step.id);
+        return stepIds.length
+            ? [{ kind: 'remove-edge', stepIds, edge: structuredClone(edge) }]
+            : [];
+    });
+}

package/dist/draft/edits/connections/describe-workflow-draft-connection-edit.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowDraftConnectionEditInput, WorkflowDraftConnectionEditDescription } from '../../../types/workflow-draft-connection-edit.js';
+/** The final connection stage needs actual ports/references, not unfinished old contracts. */
+export declare function describeWorkflowDraftConnectionEdit(input: WorkflowDraftConnectionEditInput): WorkflowDraftConnectionEditDescription;

package/dist/draft/edits/connections/describe-workflow-draft-connection-edit.js

@@ -0,0 +1,139 @@
+import { createHash } from 'node:crypto';
+import { stageWorkflowDraftEdit } from '../stage-workflow-draft-edit.js';
+import { resolveWorkflowDraftApiMaterials } from '../../resolve-workflow-draft-api-materials.js';
+import { collectDeferredApiInputSlots } from '../../../inputs/collect-deferred-api-input-slots.js';
+import { createWorkflowNodeContracts } from '../../../workflow/create-workflow-node-contracts.js';
+import { draftEdgeKey } from '../../changes/draft-edge-key.js';
+import { resolveWorkflowDraftNativeSnapshot } from '../../resolve-workflow-draft-native-snapshot.js';
+import { NativeMaterialResolutionError } from '../../../workflow/native-material-resolution-error.js';
+import { resolveWorkflowPlanningMessages } from '../../../planning/evidence/resolve-workflow-planning-messages.js';
+/** The final connection stage needs actual ports/references, not unfinished old contracts. */
+export function describeWorkflowDraftConnectionEdit(input) {
+    const stage = stageWorkflowDraftEdit(input);
+    const steps = structuredClone(input.plan.steps.filter((step) => step.stages.includes('connections')));
+    const fields = {
+        stage,
+        steps,
+        messages: structuredClone(resolveWorkflowPlanningMessages(input.context).filter((message) => input.requestMessageIds.includes(message.id))),
+        backgroundMessages: structuredClone(resolveWorkflowPlanningMessages(input.context).filter((message) => !input.requestMessageIds.includes(message.id))),
+        includeExplanations: input.plan.options.includeExplanations,
+    };
+    const fingerprint = createHash('sha256')
+        .update(JSON.stringify(fields))
+        .digest('hex');
+    if (!steps.length)
+        return { status: 'not-required', fingerprint, ...fields };
+    if (stage.pendingResolutionStepIds.length ||
+        stage.pendingRepairs.length ||
+        stage.blockedSourceNodeIds.length ||
+        stage.deferredRequirementIds.length ||
+        stage.pendingClarificationQuestionIds.length)
+        return { status: 'waiting-for-materials', fingerprint, ...fields };
+    const materials = resolveWorkflowDraftApiMaterials({
+        content: stage.content,
+        context: input.context,
+    });
+    const slots = collectDeferredApiInputSlots({ materials });
+    const snapshot = resolveWorkflowDraftNativeSnapshot({
+        content: stage.content,
+        context: input.context,
+        deferredNodeIds: [],
+        unavailableApiNodeIds: [],
+    });
+    if (snapshot.status !== 'ready')
+        throw new NativeMaterialResolutionError(snapshot.pending);
+    const contracts = createWorkflowNodeContracts({
+        unresolvedNodes: stage.content.gapNodes,
+        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 }),
+            },
+        })),
+        nativeNodes: stage.content.nativeNodes,
+        capabilities: snapshot.capabilities,
+    });
+    const affectedNodeIds = [
+        ...new Set(steps.flatMap((step) => {
+            const decision = step.decision;
+            if (decision.kind === 'revise-connections')
+                return decision.nodeIds;
+            if (decision.kind === 'remove-node')
+                return [
+                    decision.nodeId,
+                    ...input.draft.edges.flatMap((edge) => edge.from === decision.nodeId
+                        ? [edge.to]
+                        : edge.to === decision.nodeId
+                            ? [edge.from]
+                            : []),
+                ];
+            if ('nodeId' in decision)
+                return [decision.nodeId];
+            if (step.newNodeId !== undefined)
+                return [step.newNodeId];
+            throw new Error(`Connection step ${step.id} has no actual node scope`);
+        })),
+    ];
+    const existingEdges = stage.content.edges.map((edge) => ({
+        id: 'edge:' + createHash('sha256').update(draftEdgeKey(edge)).digest('hex'),
+        edge: structuredClone(edge),
+        editable: affectedNodeIds.includes(edge.from) || affectedNodeIds.includes(edge.to),
+    }));
+    const apiInstances = materials.map((material) => ({
+        nodeId: material.callId,
+        method: material.operation.method,
+        path: material.operation.path,
+        ...(material.operation.operation.summary === undefined
+            ? {}
+            : { summary: material.operation.operation.summary }),
+        values: structuredClone(material.values),
+        bindings: structuredClone(material.bindings),
+    }));
+    const ready = {
+        ...fields,
+        contracts,
+        apiInstances,
+        affectedNodeIds,
+        existingEdges,
+    };
+    if (!steps.some((step) => step.decision.kind === 'revise-connections') &&
+        contracts.length === 1 &&
+        existingEdges.length === 0 &&
+        contracts[0].inputs.length === 1 &&
+        contracts[0].inputs[0] === 'main' &&
+        !contracts[0].waitsForAllInputs &&
+        contracts[0].dependencyNodeIds.length === 0 &&
+        contracts[0].references.length === 0 &&
+        Object.values(contracts[0].inputReferences ?? {}).flat().length === 0) {
+        const structuralProof = {
+            kind: 'single-node-dag',
+            nodeId: contracts[0].id,
+        };
+        return {
+            ...fields,
+            status: 'not-required',
+            structuralProof,
+            fingerprint: createHash('sha256')
+                .update(JSON.stringify({ ...ready, structuralProof }))
+                .digest('hex'),
+        };
+    }
+    return {
+        status: 'ready',
+        fingerprint: createHash('sha256')
+            .update(JSON.stringify(ready))
+            .digest('hex'),
+        ...ready,
+    };
+}

package/dist/draft/edits/connections/resolve-workflow-draft-connection-edit.d.ts

@@ -0,0 +1,3 @@
+import type { ResolveWorkflowDraftConnectionEditInput, WorkflowDraftConnectionEditResult } from '../../../types/workflow-draft-connection-edit.js';
+/** Preserve retained edges; only a complete validated candidate is returned as ready. */
+export declare function resolveWorkflowDraftConnectionEdit(input: ResolveWorkflowDraftConnectionEditInput): WorkflowDraftConnectionEditResult;

package/dist/draft/edits/connections/resolve-workflow-draft-connection-edit.js

@@ -0,0 +1,82 @@
+import { createHash } from 'node:crypto';
+import { describeWorkflowDraftConnectionEdit } from './describe-workflow-draft-connection-edit.js';
+import { createWorkflowDraftConnectionEditProposalSchema } from '../../../schemas/workflow-draft-connection-edit-schema.js';
+import { validateWorkflowPlanningEvidence } from '../../../planning/evidence/validate-workflow-planning-evidence.js';
+import { draftEdgeKey } from '../../changes/draft-edge-key.js';
+import { validateWorkflowEdges } from '../../../workflow/validate-workflow-edges.js';
+import { assembleWorkflowDraftEdit } from '../assemble-workflow-draft-edit.js';
+/** Preserve retained edges; only a complete validated candidate is returned as ready. */
+export function resolveWorkflowDraftConnectionEdit(input) {
+    const described = describeWorkflowDraftConnectionEdit(input);
+    if (input.fingerprint !== described.fingerprint)
+        throw new Error('Connection edit fingerprint is missing, stale or describes different staged materials');
+    if (described.status !== 'ready')
+        throw new Error(`Connection edit cannot resolve while ${described.status}`);
+    const proposal = createWorkflowDraftConnectionEditProposalSchema(described).parse(input.proposal);
+    const connections = [];
+    const questions = [];
+    const keys = new Set();
+    if (proposal.decisions.some((decision) => decision.kind === 'keep-connections') &&
+        proposal.decisions.length !== 1)
+        throw new Error('keep-connections must be the only connection decision');
+    for (const decision of proposal.decisions) {
+        validateWorkflowPlanningEvidence({
+            context: { messages: described.messages },
+            evidence: decision.sources,
+        });
+        if (decision.explanation)
+            validateWorkflowPlanningEvidence({
+                context: { messages: described.messages },
+                evidence: decision.explanation.evidence,
+            });
+        if (decision.kind === 'needs-clarification') {
+            questions.push({
+                id: 'connection-question:' +
+                    createHash('sha256')
+                        .update(JSON.stringify([described.fingerprint, decision]))
+                        .digest('hex'),
+                message: decision.message,
+                sources: decision.sources,
+                ...(decision.explanation === undefined
+                    ? {}
+                    : { explanation: decision.explanation }),
+            });
+            continue;
+        }
+        if (decision.kind === 'keep-connections')
+            continue;
+        const edge = decision.kind === 'remove'
+            ? described.existingEdges.find((item) => item.id === decision.edgeId)
+                .edge
+            : {
+                from: decision.source.nodeId,
+                output: decision.source.port,
+                to: decision.target.nodeId,
+                input: decision.target.port,
+            };
+        const key = draftEdgeKey(edge);
+        if (keys.has(key))
+            throw new Error('Connection edit contains duplicate or cancelling changes for the same edge');
+        keys.add(key);
+        if (!described.affectedNodeIds.includes(edge.from) &&
+            !described.affectedNodeIds.includes(edge.to))
+            throw new Error('Connection change is outside every connection-planning node scope');
+        if (decision.kind === 'add') {
+            validateWorkflowEdges({ contracts: described.contracts, edges: [edge] });
+            if (edge.from === edge.to)
+                throw new Error('Connection edit cannot add a self-cycle');
+            if (described.existingEdges.some((item) => draftEdgeKey(item.edge) === key))
+                throw new Error('Connection edit cannot add an existing edge');
+        }
+        connections.push({
+            kind: decision.kind === 'add' ? 'add-edge' : 'remove-edge',
+            stepIds: described.steps.map((step) => step.id),
+            edge: structuredClone(edge),
+        });
+    }
+    const fields = { fingerprint: described.fingerprint, proposal };
+    if (questions.length)
+        return { status: 'needs-clarification', ...fields, questions };
+    const candidate = assembleWorkflowDraftEdit({ ...input, connections });
+    return { status: 'ready', ...fields, connections, candidate };
+}

package/dist/draft/edits/connections/resolve-workflow-draft-terminal-removal.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowDraftTerminalRemovalInput, WorkflowDraftTerminalRemovalResult } from '../../../types/workflow-draft-terminal-removal.js';
+/** Deleting only a terminal subgraph needs incident-edge removal, never invented reconnection. */
+export declare function resolveWorkflowDraftTerminalRemoval(input: WorkflowDraftTerminalRemovalInput): WorkflowDraftTerminalRemovalResult;

package/dist/draft/edits/connections/resolve-workflow-draft-terminal-removal.js

@@ -0,0 +1,34 @@
+import { createHash } from 'node:crypto';
+import { stageWorkflowDraftEdit } from '../stage-workflow-draft-edit.js';
+import { assembleWorkflowDraftEdit } from '../assemble-workflow-draft-edit.js';
+/** Deleting only a terminal subgraph needs incident-edge removal, never invented reconnection. */
+export function resolveWorkflowDraftTerminalRemoval(input) {
+    const stage = stageWorkflowDraftEdit(input);
+    if (!input.plan.steps.length ||
+        input.plan.steps.some((step) => step.decision.kind !== 'remove-node'))
+        return { status: 'not-applicable' };
+    const removedNodeIds = input.plan.steps.flatMap((step) => step.decision.kind === 'remove-node' ? [step.decision.nodeId] : []);
+    if (stage.pendingResolutionStepIds.length ||
+        stage.pendingRepairs.length ||
+        stage.blockedSourceNodeIds.length ||
+        stage.pendingClarificationQuestionIds.length ||
+        stage.deferredRequirementIds.length ||
+        input.draft.edges.some((edge) => removedNodeIds.includes(edge.from) && !removedNodeIds.includes(edge.to)))
+        return { status: 'not-applicable' };
+    const connections = stage.nodeRemovalConnections;
+    const fields = {
+        kind: 'terminal-node-removal',
+        removedNodeIds,
+        connections,
+        candidate: assembleWorkflowDraftEdit(input),
+    };
+    return {
+        status: 'ready',
+        result: {
+            fingerprint: createHash('sha256')
+                .update(JSON.stringify([input.plan, stage.fingerprint, fields]))
+                .digest('hex'),
+            ...fields,
+        },
+    };
+}

package/dist/draft/edits/create-workflow-draft-edit-plan.d.ts

@@ -0,0 +1,3 @@
+import type { CreateWorkflowDraftEditPlanInput, WorkflowDraftEditPlan } from '../../types/workflow-draft-edit.js';
+/** Bounded semantic plan only. Actual values/edges must pass their own stages and atomic change validation. */
+export declare function createWorkflowDraftEditPlan(input: CreateWorkflowDraftEditPlanInput): WorkflowDraftEditPlan;

package/dist/draft/edits/create-workflow-draft-edit-plan.js

@@ -0,0 +1,140 @@
+import { createHash } from 'node:crypto';
+import { apiOperationKeySchema } from '../../schemas/api-operation-key-schema.js';
+import { workflowMessageEvidenceSchema, workflowPlanningEvidenceSchema, } from '../../schemas/planning-evidence-schema.js';
+import { resolveWorkflowDraftEditOptions } from './resolve-workflow-draft-edit-options.js';
+import { createWorkflowDraftEditProposalSchema } from '../../schemas/create-workflow-draft-edit-proposal-schema.js';
+import { describeWorkflowDraftEditContext } from './describe-workflow-draft-edit-context.js';
+import { validateDescribedWorkflowPlanningEvidence } from '../../planning/evidence/validate-workflow-planning-evidence.js';
+import { apiOperationKeyEquals } from '../../openapi/catalog/api-operation-key-equals.js';
+import { workflowDraftEditStages } from './workflow-draft-edit-stages.js';
+import { resolveWorkflowDraftClarificationOwnerIndex } from './clarification/resolve-workflow-draft-clarification-owner-index.js';
+/** Bounded semantic plan only. Actual values/edges must pass their own stages and atomic change validation. */
+export function createWorkflowDraftEditPlan(input) {
+    const described = describeWorkflowDraftEditContext(input);
+    const options = resolveWorkflowDraftEditOptions(input.options);
+    const proposal = createWorkflowDraftEditProposalSchema(options, {
+        ...(described.planning.operations.length
+            ? { operationSchema: apiOperationKeySchema }
+            : {}),
+        apiNodeIds: described.draft.apiCalls.map((call) => call.id),
+        nativeNodeIds: described.draft.nativeNodes.map((node) => node.id),
+        gapNodeIds: described.draft.gapNodes?.map((node) => node.id),
+        capabilityNames: described.planning.capabilities.map((capability) => capability.name),
+        requirementIds: described.draft.requirements.map((requirement) => requirement.id),
+        removedRequirementIds: described.removedRequirements.map((requirement) => requirement.id),
+        messageSchema: workflowMessageEvidenceSchema,
+        evidenceSchema: workflowPlanningEvidenceSchema,
+    }).parse(input.proposal);
+    const signatures = new Set();
+    const requirementDecisions = new Set();
+    const removals = new Set(proposal.decisions
+        .filter((decision) => decision.kind === 'remove-node')
+        .map((decision) => decision.nodeId));
+    for (const [index, decision] of proposal.decisions.entries()) {
+        if (decision.kind === 'needs-clarification')
+            resolveWorkflowDraftClarificationOwnerIndex({
+                decisions: proposal.decisions,
+                sourceIndex: index,
+            });
+        if (decision.kind === 'revise-requirement' ||
+            decision.kind === 'remove-requirement' ||
+            decision.kind === 'restore-requirement') {
+            if (requirementDecisions.has(decision.requirementId))
+                throw new Error(`Draft edit repeats or conflicts on requirement ${decision.requirementId}`);
+            requirementDecisions.add(decision.requirementId);
+        }
+        validateDescribedWorkflowPlanningEvidence(described.planning, decision.sources);
+        if (decision.sources.some((source) => !described.requestMessageIds.includes(source.messageId)))
+            throw new Error('Draft edit sources must cite the current requestMessageIds');
+        if (decision.explanation)
+            validateDescribedWorkflowPlanningEvidence(described.planning, decision.explanation.evidence);
+        if ('operation' in decision &&
+            !described.planning.operations.some((operation) => apiOperationKeyEquals(operation.key, decision.operation)))
+            throw new Error('Draft edit references an unavailable or stale operation');
+        if (decision.kind === 'replace-api-operation') {
+            const previous = described.draft.apiCalls.find((call) => call.id === decision.nodeId);
+            if (apiOperationKeyEquals(previous.operation, decision.operation))
+                throw new Error('Replacing an API operation requires a different supplied operation');
+        }
+        if (decision.kind === 'report-capability-gap' &&
+            decision.finding.kind === 'api-contract-gap') {
+            const operation = decision.finding.operation;
+            if (!described.planning.operations.some((candidate) => apiOperationKeyEquals(candidate.key, operation)))
+                throw new Error('Capability gap references an unavailable or stale OAS operation');
+        }
+        if ('nodeId' in decision &&
+            decision.kind !== 'remove-node' &&
+            removals.has(decision.nodeId))
+            throw new Error(`Draft edit both removes and revises ${decision.nodeId}`);
+        if (decision.kind === 'revise-connections' &&
+            new Set(decision.nodeIds).size !== decision.nodeIds.length)
+            throw new Error('Draft edit connection scope requires distinct node IDs');
+        if (decision.kind === 'needs-clarification' &&
+            decision.owner.kind === 'semantic' &&
+            decision.owner.scope.kind === 'nodes' &&
+            new Set(decision.owner.scope.nodeIds).size !==
+                decision.owner.scope.nodeIds.length)
+            throw new Error('Draft edit clarification scope requires distinct node IDs');
+        const signature = JSON.stringify(decision);
+        if (signatures.has(signature))
+            throw new Error('Draft edit repeats an identical decision; distinct new instances require distinct roles');
+        signatures.add(signature);
+    }
+    if (proposal.decisions.some((decision) => decision.kind === 'no-change') &&
+        (described.planning.clarification?.pendingQuestions.length ||
+            described.planning.clarification?.deferredQuestions.length))
+        throw new Error('A no-change edit cannot discard unresolved original clarification questions');
+    const id = 'draft-edit:' +
+        createHash('sha256')
+            .update(JSON.stringify([
+            described.draftFingerprint,
+            described.contextFingerprint,
+            described.nodeContractsFingerprint,
+            described.requestMessageIds,
+            options,
+            proposal,
+        ]))
+            .digest('hex');
+    const known = new Set([
+        ...described.draft.apiCalls,
+        ...described.draft.nativeNodes,
+        ...(described.draft.gapNodes === undefined
+            ? []
+            : described.draft.gapNodes),
+    ].map((node) => node.id));
+    const steps = proposal.decisions.map((decision, index) => {
+        const stepId = `${id}:step:${index + 1}`;
+        const newNodeId = decision.kind === 'add-api-call' ||
+            decision.kind === 'add-native-node' ||
+            decision.kind === 'report-capability-gap'
+            ? 'node-' + createHash('sha256').update(stepId).digest('hex')
+            : undefined;
+        if (newNodeId !== undefined && known.has(newNodeId))
+            throw new Error('Allocated draft edit instance ID conflicts with an existing node');
+        if (newNodeId !== undefined)
+            known.add(newNodeId);
+        return {
+            id: stepId,
+            decision,
+            ...(newNodeId === undefined ? {} : { newNodeId }),
+            stages: workflowDraftEditStages(decision),
+        };
+    });
+    return {
+        id,
+        draftId: described.draft.id,
+        baseRevision: described.draft.revision,
+        draftFingerprint: described.draftFingerprint,
+        contextFingerprint: described.contextFingerprint,
+        nodeContractsFingerprint: described.nodeContractsFingerprint,
+        requestMessageIds: described.requestMessageIds,
+        options,
+        status: proposal.decisions.some((decision) => decision.kind === 'needs-clarification' &&
+            decision.owner.kind === 'semantic')
+            ? 'needs-clarification'
+            : proposal.decisions.every((decision) => decision.kind === 'no-change')
+                ? 'no-change'
+                : 'ready-for-planning',
+        steps,
+    };
+}

package/dist/draft/edits/describe-workflow-draft-edit-context.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowDraftEditInput, WorkflowDraftEditContextDescription } from '../../types/workflow-draft-edit.js';
+/** Snapshot authority before model invocation; no model-owned versions or identities. */
+export declare function describeWorkflowDraftEditContext(input: WorkflowDraftEditInput): WorkflowDraftEditContextDescription;

package/dist/draft/edits/describe-workflow-draft-edit-context.js

@@ -0,0 +1,31 @@
+import { createHash } from 'node:crypto';
+import { validateWorkflowDraft } from '../validate-workflow-draft.js';
+import { describeWorkflowPlanningContext } from '../../planning/evidence/describe-workflow-planning-context.js';
+import { workflowPlanningContextFingerprintFromDescription } from '../../planning/evidence/workflow-planning-context-fingerprint.js';
+import { workflowDraftEditRequestIdsSchema } from '../../schemas/workflow-draft-edit-options-schema.js';
+import { listRemovedWorkflowDraftRequirements } from '../requirements/history/list-removed-workflow-draft-requirements.js';
+import { resolveWorkflowDraftNodeContracts } from '../contracts/resolve-workflow-draft-node-contracts.js';
+/** Snapshot authority before model invocation; no model-owned versions or identities. */
+export function describeWorkflowDraftEditContext(input) {
+    validateWorkflowDraft(input);
+    const requestMessageIds = workflowDraftEditRequestIdsSchema.parse(input.requestMessageIds);
+    const planning = describeWorkflowPlanningContext(input.context);
+    if (requestMessageIds.some((id) => !planning.messages.some((message) => message.id === id)))
+        throw new Error('draft edit requestMessageIds references an unknown source message');
+    const draft = structuredClone(input.draft);
+    const nodeContracts = structuredClone(resolveWorkflowDraftNodeContracts(input));
+    return {
+        draft,
+        nodeContracts,
+        nodeContractsFingerprint: createHash('sha256')
+            .update(JSON.stringify(nodeContracts))
+            .digest('hex'),
+        removedRequirements: listRemovedWorkflowDraftRequirements(draft),
+        planning,
+        requestMessageIds,
+        draftFingerprint: createHash('sha256')
+            .update(JSON.stringify(draft))
+            .digest('hex'),
+        contextFingerprint: workflowPlanningContextFingerprintFromDescription(planning),
+    };
+}

package/dist/draft/edits/describe-workflow-draft-selected-nodes.d.ts

@@ -0,0 +1,4 @@
+import type { ValidateWorkflowDraftEditPlanInput } from '../../types/workflow-draft-edit.js';
+import type { WorkflowDraftSelectedNode } from '../../types/workflow-draft-selected-nodes.js';
+/** Final selected identities exist before values; removed nodes never remain scope candidates. */
+export declare function describeWorkflowDraftSelectedNodes(input: ValidateWorkflowDraftEditPlanInput): WorkflowDraftSelectedNode[];