@openapi-flow/core 0.2.0 → 0.3.0

package/dist/draft/edits/assembly/resolve-prepared-workflow-draft-edit.js

@@ -0,0 +1,38 @@
+import { workflowDraftEditRepairSchema } from '../../../schemas/workflow-draft-edit-assembly-schema.js';
+import { applyDraftChange } from '../../changes/apply-draft-change.js';
+import { preparePrimaryWorkflowDraftEdit } from './prepare-primary-workflow-draft-edit.js';
+import { inspectWorkflowDraftEditRepairs } from './inspect-workflow-draft-edit-repairs.js';
+import { resolveWorkflowDraftEditRepair } from './resolve-workflow-draft-edit-repair.js';
+/** Recompute repair authority after each explicit result; never trust client-edited material state. */
+export function resolvePreparedWorkflowDraftEdit(input, mode) {
+    const prepared = preparePrimaryWorkflowDraftEdit(input, mode);
+    const repairs = workflowDraftEditRepairSchema
+        .array()
+        .optional()
+        .parse(input.repairs);
+    const pending = [...(repairs === undefined ? [] : repairs)];
+    if (new Set(pending.map((repair) => repair.taskId)).size !== pending.length)
+        throw new Error('Draft edit repairs require distinct taskId values');
+    const acknowledgedTaskIds = new Set();
+    const inspect = () => inspectWorkflowDraftEditRepairs({
+        before: input.draft,
+        content: prepared.content,
+        context: input.context,
+        plan: input.plan,
+        acknowledgedTaskIds,
+        pendingResolutionStepIds: prepared.pendingResolutionStepIds,
+    });
+    while (pending.length) {
+        const tasks = inspect();
+        const index = pending.findIndex((repair) => tasks.some((task) => task.id === repair.taskId));
+        if (index < 0)
+            throw new Error(`Draft edit repair task is unknown or stale: ${pending.map((repair) => repair.taskId).join(', ')}`);
+        const [repair] = pending.splice(index, 1);
+        const task = tasks.find((task) => task.id === repair.taskId);
+        const change = resolveWorkflowDraftEditRepair(prepared.content, task, repair);
+        applyDraftChange(prepared.content, change);
+        prepared.changes.push(change);
+        acknowledgedTaskIds.add(task.id);
+    }
+    return { ...prepared, pendingRepairs: inspect() };
+}

package/dist/draft/edits/assembly/resolve-workflow-draft-edit-repair.d.ts

@@ -0,0 +1,4 @@
+import type { WorkflowDraftEditRepair, WorkflowDraftEditRepairTask } from '../../../types/workflow-draft-edit-assembly.js';
+import type { WorkflowDraftContent } from '../../../types/workflow-draft.js';
+import type { WorkflowDraftChange } from '../../../types/workflow-draft-changes.js';
+export declare function resolveWorkflowDraftEditRepair(content: WorkflowDraftContent, task: WorkflowDraftEditRepairTask, repair: WorkflowDraftEditRepair): WorkflowDraftChange;

package/dist/draft/edits/assembly/resolve-workflow-draft-edit-repair.js

@@ -0,0 +1,37 @@
+import { workflowDraftNativeNodeSchema } from '../../../schemas/workflow-draft-schema.js';
+import { applyWorkflowDraftBindingEdits } from '../values/apply-workflow-draft-binding-edits.js';
+import { applyWorkflowDraftValueEdits } from '../values/apply-workflow-draft-value-edits.js';
+export function resolveWorkflowDraftEditRepair(content, task, repair) {
+    if (task.kind !== repair.kind)
+        throw new Error(`Draft repair ${task.id} must resolve ${task.kind}, not ${repair.kind}`);
+    if (repair.kind === 'api-bindings') {
+        for (const edit of repair.edits) {
+            const pointer = edit.kind === 'set' ? edit.binding.targetPointer : edit.targetPointer;
+            if (!task.targetPointers.includes(pointer))
+                throw new Error(`Draft repair ${task.id} cannot alter unrelated API binding target ${pointer}`);
+        }
+        const call = content.apiCalls.find((call) => call.id === task.nodeId);
+        return {
+            kind: 'update-api-call',
+            call: {
+                ...call,
+                bindings: applyWorkflowDraftBindingEdits(call.bindings, repair.edits, `Draft repair ${task.nodeId}`),
+            },
+        };
+    }
+    const node = content.nativeNodes.find((node) => node.id === task.nodeId);
+    if (task.targetPointers.length &&
+        repair.edits.some((edit) => !task.targetPointers.includes(edit.pointer)))
+        throw new Error(`Draft repair ${task.id} cannot alter unrelated native parameter locations`);
+    return {
+        kind: 'update-native-node',
+        node: workflowDraftNativeNodeSchema.parse({
+            ...node,
+            parameters: applyWorkflowDraftValueEdits({
+                value: node.parameters,
+                edits: repair.edits,
+                source: `Draft repair ${task.nodeId}`,
+            }),
+        }),
+    };
+}

package/dist/draft/edits/bindings/describe-workflow-draft-api-binding-edit.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowDraftApiBindingEditInput, WorkflowDraftApiBindingEditDescription } from '../../../types/workflow-draft-api-binding-edit.js';
+/** Describe actual staged sources, never old contracts for unresolved replacements. */
+export declare function describeWorkflowDraftApiBindingEdit(input: WorkflowDraftApiBindingEditInput): WorkflowDraftApiBindingEditDescription;

package/dist/draft/edits/bindings/describe-workflow-draft-api-binding-edit.js

@@ -0,0 +1,84 @@
+import { createHash } from 'node:crypto';
+import { resolveWorkflowPlanningMessages } from '../../../planning/evidence/resolve-workflow-planning-messages.js';
+import { stageWorkflowDraftEdit } from '../stage-workflow-draft-edit.js';
+import { resolveWorkflowDraftApiMaterials } from '../../resolve-workflow-draft-api-materials.js';
+import { describeWorkflowDraftReferenceSources } from '../references/describe-workflow-draft-reference-sources.js';
+import { createApiRequestSchema } from '../../../schemas/create-api-request-schema.js';
+import { workflowDraftApiBindingEditScopeSchema } from '../../../schemas/workflow-draft-api-binding-edit-scope-schema.js';
+/** Describe actual staged sources, never old contracts for unresolved replacements. */
+export function describeWorkflowDraftApiBindingEdit(input) {
+    const scope = workflowDraftApiBindingEditScopeSchema.parse(input.scope);
+    const stage = stageWorkflowDraftEdit(input);
+    let nodeId;
+    let instruction;
+    let requiredTargetPointers;
+    if (scope.kind === 'step') {
+        const step = input.plan.steps.find((step) => step.id === scope.stepId);
+        if (!step || step.decision.kind !== 'revise-api-bindings')
+            throw new Error('Binding edit scope.stepId must identify a revise-api-bindings decision');
+        if (!stage.pendingResolutionStepIds.includes(step.id))
+            throw new Error('Binding edit step already has a supplied result; remove that result explicitly before replanning');
+        nodeId = step.decision.nodeId;
+        instruction = step.decision.instruction;
+        requiredTargetPointers = [];
+    }
+    else {
+        const task = stage.pendingRepairs.find((task) => task.id === scope.taskId);
+        if (!task || task.kind !== 'api-bindings')
+            throw new Error('Binding edit scope.taskId must identify a current API binding repair');
+        nodeId = task.nodeId;
+        requiredTargetPointers = [...task.targetPointers];
+        if (!requiredTargetPointers.length)
+            throw new Error('API binding repair must declare affected target pointers');
+        instruction = input.plan.steps
+            .map((step) => step.decision.instruction)
+            .join('\n');
+    }
+    if (stage.blockedSourceNodeIds.includes(nodeId))
+        throw new Error(`Binding target ${nodeId} is blocked by an unresolved contract or requirement`);
+    const call = stage.content.apiCalls.find((call) => call.id === nodeId);
+    if (!call)
+        throw new Error(`Binding edit target ${nodeId} has no staged API instance`);
+    const materials = resolveWorkflowDraftApiMaterials({
+        content: stage.content,
+        context: input.context,
+    });
+    const material = materials.find((material) => material.callId === nodeId);
+    const requirementsFor = (id) => structuredClone(stage.content.requirements.filter((requirement) => requirement.scope.kind === 'workflow' ||
+        requirement.scope.nodeIds.includes(id)));
+    const sources = describeWorkflowDraftReferenceSources({
+        stage,
+        context: input.context,
+        excludedNodeIds: [nodeId],
+    });
+    const sourceCandidates = sources.values.map((source) => source.kind === 'api'
+        ? { ...source, requirements: requirementsFor(source.nodeId) }
+        : {
+            kind: 'native',
+            nodeId: source.nodeId,
+            schema: source.schema,
+            requirements: requirementsFor(source.nodeId),
+        });
+    if (new Set(sourceCandidates.map((source) => source.nodeId)).size !==
+        sourceCandidates.length)
+        throw new Error('Binding edit source candidates must have distinct actual node IDs');
+    const fields = {
+        stage,
+        scope,
+        instruction,
+        call: structuredClone(call),
+        operation: structuredClone(material.operation),
+        requestSchema: createApiRequestSchema(material),
+        sourceCandidates,
+        requiredTargetPointers,
+        messages: structuredClone(resolveWorkflowPlanningMessages(input.context).filter((message) => input.requestMessageIds.includes(message.id))),
+        includeExplanations: input.plan.options.includeExplanations,
+        backgroundMessages: structuredClone(resolveWorkflowPlanningMessages(input.context).filter((message) => !input.requestMessageIds.includes(message.id))),
+    };
+    return {
+        fingerprint: createHash('sha256')
+            .update(JSON.stringify(fields))
+            .digest('hex'),
+        ...fields,
+    };
+}

package/dist/draft/edits/bindings/resolve-workflow-draft-api-binding-edit.d.ts

@@ -0,0 +1,3 @@
+import type { ResolveWorkflowDraftApiBindingEditInput, WorkflowDraftApiBindingEditResult } from '../../../types/workflow-draft-api-binding-edit.js';
+/** Resolve one actual target's mappings. Whole-graph validation remains atomic assembly's job. */
+export declare function resolveWorkflowDraftApiBindingEdit(input: ResolveWorkflowDraftApiBindingEditInput): WorkflowDraftApiBindingEditResult;

package/dist/draft/edits/bindings/resolve-workflow-draft-api-binding-edit.js

@@ -0,0 +1,152 @@
+import { createHash } from 'node:crypto';
+import { describeWorkflowDraftApiBindingEdit } from './describe-workflow-draft-api-binding-edit.js';
+import { createWorkflowDraftApiBindingEditProposalSchema } from '../../../schemas/workflow-draft-api-binding-edit-schema.js';
+import { validateWorkflowPlanningEvidence } from '../../../planning/evidence/validate-workflow-planning-evidence.js';
+import { resolveWorkflowDraftApiMaterials } from '../../resolve-workflow-draft-api-materials.js';
+import { pointerTokens, hasPointer } from '../../../bindings/json-pointer.js';
+import { requestBindingSchemas } from '../../../bindings/request-binding-schema.js';
+import { applyWorkflowDraftBindingEdits } from '../values/apply-workflow-draft-binding-edits.js';
+import { applyWorkflowDraftApiInputEdits } from '../values/apply-workflow-draft-api-input-edits.js';
+import { validateApiArguments } from '../../../arguments/validate-api-arguments.js';
+import { validateApiBindingAssignment } from '../../../bindings/validate-api-binding-assignment.js';
+/** Resolve one actual target's mappings. Whole-graph validation remains atomic assembly's job. */
+export function resolveWorkflowDraftApiBindingEdit(input) {
+    const described = describeWorkflowDraftApiBindingEdit(input);
+    if (input.fingerprint !== described.fingerprint)
+        throw new Error('Binding edit fingerprint is missing, stale or describes different staged materials');
+    const proposal = createWorkflowDraftApiBindingEditProposalSchema(described).parse(input.proposal);
+    const material = resolveWorkflowDraftApiMaterials({
+        content: described.stage.content,
+        context: input.context,
+    }).find((item) => item.callId === described.call.id);
+    const edits = [];
+    const valueEdits = [];
+    const questions = [];
+    const targets = [];
+    for (const decision of proposal.decisions) {
+        pointerTokens(decision.targetPointer);
+        if (!requestBindingSchemas(material, decision.targetPointer).length)
+            throw new Error(`Binding edit target ${decision.targetPointer} is not declared by its actual request OAS`);
+        if (targets.some((pointer) => pointer === decision.targetPointer ||
+            pointer.startsWith(decision.targetPointer + '/') ||
+            decision.targetPointer.startsWith(pointer + '/')))
+            throw new Error(`Binding edit has duplicate or overlapping decisions at ${decision.targetPointer}`);
+        targets.push(decision.targetPointer);
+        validateWorkflowPlanningEvidence({
+            context: { messages: described.messages },
+            evidence: decision.sources,
+        });
+        if (decision.explanation)
+            validateWorkflowPlanningEvidence({
+                context: { messages: described.messages },
+                evidence: decision.explanation.evidence,
+            });
+        const existing = described.call.bindings.find((binding) => binding.targetPointer === decision.targetPointer);
+        if (decision.kind === 'needs-clarification') {
+            questions.push({
+                id: 'binding-question:' +
+                    createHash('sha256')
+                        .update(JSON.stringify([described.fingerprint, decision]))
+                        .digest('hex'),
+                nodeId: described.call.id,
+                targetPointer: decision.targetPointer,
+                message: decision.message,
+                sources: decision.sources,
+                ...(decision.explanation === undefined
+                    ? {}
+                    : { explanation: decision.explanation }),
+            });
+        }
+        else if (decision.kind === 'unbind' || decision.kind === 'keep') {
+            if (!existing)
+                throw new Error(`Binding edit ${decision.kind} requires an existing binding at ${decision.targetPointer}`);
+            if (decision.kind === 'unbind')
+                edits.push({ kind: 'remove', targetPointer: decision.targetPointer });
+        }
+        else {
+            const literal = hasPointer(described.call.values, decision.targetPointer);
+            if (decision.kind === 'replace-literal-with-binding') {
+                if (!literal)
+                    throw new Error(`Binding edit replacement has no actual literal at ${decision.targetPointer}`);
+                valueEdits.push({ kind: 'remove', pointer: decision.targetPointer });
+            }
+            else if (literal)
+                throw new Error(`Binding edit ${decision.targetPointer} requires an explicit replace-literal-with-binding decision`);
+            edits.push({
+                kind: 'set',
+                binding: {
+                    kind: 'node-output',
+                    targetPointer: decision.targetPointer,
+                    sourceNodeId: decision.sourceNodeId,
+                    sourcePointer: decision.sourcePointer,
+                },
+            });
+        }
+    }
+    if (described.scope.kind === 'repair' &&
+        (targets.length !== described.requiredTargetPointers.length ||
+            described.requiredTargetPointers.some((pointer) => !targets.includes(pointer))))
+        throw new Error('Binding repair must explicitly decide every affected target exactly once');
+    const materials = [
+        material,
+        ...described.sourceCandidates
+            .filter((candidate) => candidate.kind === 'api')
+            .map((candidate) => ({
+            callId: candidate.nodeId,
+            operation: candidate.operation,
+        })),
+    ];
+    const nativeOutputs = described.sourceCandidates
+        .filter((candidate) => candidate.kind === 'native')
+        .map((candidate) => ({
+        nodeId: candidate.nodeId,
+        schema: candidate.schema,
+    }));
+    for (const edit of edits)
+        if (edit.kind === 'set')
+            validateApiBindingAssignment({
+                callId: described.call.id,
+                binding: edit.binding,
+                materials,
+                nativeOutputs,
+            });
+    for (const decision of proposal.decisions)
+        if (decision.kind === 'keep')
+            validateApiBindingAssignment({
+                callId: described.call.id,
+                binding: described.call.bindings.find((binding) => binding.targetPointer === decision.targetPointer),
+                materials,
+                nativeOutputs,
+            });
+    const fields = { fingerprint: described.fingerprint, proposal };
+    if (questions.length)
+        return { status: 'needs-clarification', ...fields, questions };
+    const bindings = applyWorkflowDraftBindingEdits(described.call.bindings, edits, `Binding edit ${described.call.id}`);
+    const values = applyWorkflowDraftApiInputEdits(described.call.values, valueEdits, material);
+    validateApiArguments({ ...material, values, bindings });
+    for (const binding of bindings)
+        validateApiBindingAssignment({
+            callId: described.call.id,
+            binding,
+            materials,
+            nativeOutputs,
+        });
+    if (described.scope.kind === 'step')
+        return {
+            status: 'ready',
+            kind: 'step',
+            ...fields,
+            resolution: {
+                stepId: described.scope.stepId,
+                kind: 'api-bindings',
+                edits,
+                valueEdits,
+            },
+        };
+    return {
+        status: 'ready',
+        kind: 'repair',
+        ...fields,
+        repair: { taskId: described.scope.taskId, kind: 'api-bindings', edits },
+    };
+}

package/dist/draft/edits/clarification/describe-workflow-draft-clarification-ownership.d.ts

@@ -0,0 +1,3 @@
+import type { DescribeWorkflowDraftClarificationOwnershipInput, WorkflowDraftClarificationOwnership } from '../../../types/workflow-draft-clarification-ownership.js';
+/** Retain every declared concern and code-resolve its stage owner; this is not an answer or readiness claim. */
+export declare function describeWorkflowDraftClarificationOwnership(input: DescribeWorkflowDraftClarificationOwnershipInput): WorkflowDraftClarificationOwnership[];

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;