@openapi-flow/core 0.1.0 → 0.3.0

package/dist/draft/edits/assembly/prepare-primary-workflow-draft-edit.js

@@ -0,0 +1,288 @@
+import { createHash } from 'node:crypto';
+import { retainRequestedApiInputsAfterEdits } from '../inputs/retain-requested-api-inputs-after-edits.js';
+import { workflowDraftEditResolutionSchema } from '../../../schemas/workflow-draft-edit-assembly-schema.js';
+import { workflowDraftApiCallSchema } from '../../../schemas/workflow-draft-schema.js';
+import { validateWorkflowDraftEditPlan } from '../validate-workflow-draft-edit-plan.js';
+import { applyDraftChange } from '../../changes/apply-draft-change.js';
+import { resolveWorkflowDraftApiMaterials } from '../../resolve-workflow-draft-api-materials.js';
+import { applyWorkflowDraftApiInputEdits } from '../values/apply-workflow-draft-api-input-edits.js';
+import { applyWorkflowDraftBindingEdits } from '../values/apply-workflow-draft-binding-edits.js';
+import { applyWorkflowDraftNativeParameterChanges } from '../native/apply-workflow-draft-native-parameter-changes.js';
+import { projectWorkflowDraftClarificationRequirements } from '../../requirements/project-workflow-draft-clarification-requirements.js';
+import { createWorkflowDraftEditCandidateContext } from '../../requirements/create-workflow-draft-edit-candidate-context.js';
+import { listRemovedWorkflowDraftRequirements } from '../../requirements/history/list-removed-workflow-draft-requirements.js';
+import { createWorkflowDraftCapabilityGap } from '../../gaps/create-workflow-draft-capability-gap.js';
+import { deriveWorkflowDraftNodeRemovalConnections } from '../connections/derive-workflow-draft-node-removal-connections.js';
+/** Primary data only; retained edges/references may still need explicitly supplied repairs. */
+export function preparePrimaryWorkflowDraftEdit(input, mode) {
+    validateWorkflowDraftEditPlan(input);
+    createWorkflowDraftEditCandidateContext(input);
+    const resolutions = workflowDraftEditResolutionSchema
+        .array()
+        .parse(input.resolutions);
+    const byStep = new Map();
+    for (const resolution of resolutions) {
+        if (!input.plan.steps.some((step) => step.id === resolution.stepId) ||
+            byStep.has(resolution.stepId))
+            throw new Error(`Draft edit resolutions require distinct known stepId: ${resolution.stepId}`);
+        byStep.set(resolution.stepId, resolution);
+    }
+    const content = structuredClone({
+        id: input.draft.id,
+        apiCalls: input.draft.apiCalls,
+        nativeNodes: input.draft.nativeNodes,
+        ...(input.draft.gapNodes === undefined
+            ? {}
+            : { gapNodes: input.draft.gapNodes }),
+        requirements: input.draft.requirements,
+        edges: input.draft.edges,
+    });
+    const changes = [];
+    const deferredRequirementIds = [];
+    const pendingResolutionStepIds = [];
+    function add(change) {
+        applyDraftChange(content, change);
+        changes.push(change);
+    }
+    function requireResolution(stepId) {
+        const resolution = byStep.get(stepId);
+        if (!resolution)
+            throw new Error(`Missing draft edit resolution for ${stepId}`);
+        byStep.delete(stepId);
+        return resolution;
+    }
+    const nodeRemovalConnections = deriveWorkflowDraftNodeRemovalConnections(input);
+    for (const connection of nodeRemovalConnections)
+        add({ kind: connection.kind, edge: connection.edge });
+    for (const requirement of projectWorkflowDraftClarificationRequirements(input)) {
+        if (content.requirements.some((existing) => existing.id === requirement.id))
+            throw new Error(`Clarification requirement ${requirement.id} already exists; use an explicit requirements revision`);
+        add({ kind: 'set-requirement', requirement });
+        if (requirement.state !== 'confirmed')
+            deferredRequirementIds.push(requirement.id);
+    }
+    // Node replacement establishes the actual contract before any partial edits.
+    const replacements = input.plan.steps.filter((step) => ['add-api-call', 'replace-api-operation', 'add-native-node'].includes(step.decision.kind));
+    const details = input.plan.steps.filter((step) => !replacements.includes(step));
+    for (const step of [...replacements, ...details]) {
+        const decision = step.decision;
+        if (decision.kind === 'report-capability-gap') {
+            if (step.newNodeId === undefined)
+                throw new Error(`Capability gap ${step.id} requires its allocated node identity`);
+            add({
+                kind: 'add-capability-gap',
+                node: createWorkflowDraftCapabilityGap({
+                    id: step.newNodeId,
+                    requestedBehavior: decision.instruction,
+                    finding: decision.finding,
+                    sourceMessageIds: [
+                        ...new Set(decision.sources.map((source) => source.messageId)),
+                    ],
+                    context: input.context,
+                }),
+            });
+            continue;
+        }
+        if (decision.kind === 'needs-clarification') {
+            if (decision.owner.kind === 'planning-step')
+                continue;
+            const id = 'edit-decision:' + createHash('sha256').update(step.id).digest('hex');
+            if (content.requirements.some((requirement) => requirement.id === id))
+                throw new Error(`Draft edit deferred requirement identity conflict: ${id}`);
+            add({
+                kind: 'set-requirement',
+                requirement: {
+                    id,
+                    text: decision.instruction,
+                    state: 'needs-clarification',
+                    scope: structuredClone(decision.owner.scope),
+                    sourceMessageIds: [
+                        ...new Set(decision.sources.map((source) => source.messageId)),
+                    ],
+                },
+            });
+            deferredRequirementIds.push(id);
+            continue;
+        }
+        if (decision.kind === 'remove-node') {
+            add({ kind: 'remove-node', nodeId: decision.nodeId });
+            continue;
+        }
+        if (decision.kind === 'remove-requirement') {
+            add({
+                kind: 'remove-requirement',
+                requirementId: decision.requirementId,
+                sourceMessageIds: [
+                    ...new Set(decision.sources.map((source) => source.messageId)),
+                ],
+            });
+            continue;
+        }
+        if (decision.kind === 'no-change' || decision.kind === 'revise-connections')
+            continue;
+        if (!byStep.has(step.id) && mode === 'staged') {
+            pendingResolutionStepIds.push(step.id);
+            continue;
+        }
+        if ('nodeId' in decision &&
+            replacements.some((replacement) => replacement.decision.kind === 'replace-api-operation' &&
+                replacement.decision.nodeId === decision.nodeId &&
+                pendingResolutionStepIds.includes(replacement.id)))
+            throw new Error(`Draft edit ${step.id} needs its pending operation replacement before detail results`);
+        const resolution = requireResolution(step.id);
+        const wrongKind = () => new Error(`Draft edit resolution ${step.id} (${resolution.kind}) does not implement ${decision.kind}`);
+        if (decision.kind === 'add-api-call' ||
+            decision.kind === 'replace-api-operation') {
+            if (resolution.kind !== 'api-call')
+                throw wrongKind();
+            const id = decision.kind === 'add-api-call' ? step.newNodeId : decision.nodeId;
+            if (id === undefined)
+                throw new Error(`Draft edit ${step.id} is missing its allocated instance identity`);
+            add({
+                kind: decision.kind === 'add-api-call' ? 'add-api-call' : 'update-api-call',
+                call: workflowDraftApiCallSchema.parse({
+                    id,
+                    operation: decision.operation,
+                    values: resolution.values,
+                    bindings: resolution.bindings,
+                    ...(resolution.requestedInputs === undefined
+                        ? {}
+                        : { requestedInputs: resolution.requestedInputs }),
+                    ...(resolution.requestMediaType === undefined
+                        ? {}
+                        : { requestMediaType: resolution.requestMediaType }),
+                }),
+            });
+        }
+        else if (decision.kind === 'add-native-node' ||
+            decision.kind === 'revise-native-node') {
+            const id = decision.kind === 'add-native-node' ? step.newNodeId : decision.nodeId;
+            if (id === undefined)
+                throw new Error(`Draft edit ${step.id} is missing its allocated instance identity`);
+            const previous = content.nativeNodes.find((node) => node.id === id);
+            const capability = decision.kind === 'add-native-node'
+                ? decision.capability
+                : previous.capability;
+            if (resolution.kind === 'native-runtime')
+                add({
+                    kind: decision.kind === 'add-native-node'
+                        ? 'add-native-node'
+                        : 'update-native-node',
+                    node: { id, capability, parameters: {}, runtimeParameters: true },
+                });
+            else if (decision.kind === 'add-native-node' &&
+                (resolution.kind === 'native-literal' ||
+                    resolution.kind === 'native-mixed'))
+                add({
+                    kind: 'add-native-node',
+                    node: {
+                        id,
+                        capability,
+                        parameters: resolution.parameters,
+                        ...(resolution.kind === 'native-mixed'
+                            ? { runtimeParameters: resolution.runtimeParameters }
+                            : {}),
+                    },
+                });
+            else if (decision.kind === 'revise-native-node' &&
+                resolution.kind === 'native-parameters')
+                add({
+                    kind: 'update-native-node',
+                    node: applyWorkflowDraftNativeParameterChanges({
+                        node: previous,
+                        capability: input.context.capabilities.find((entry) => entry.name === capability),
+                        edits: resolution.edits,
+                        source: `Draft native ${id}`,
+                    }),
+                });
+            else
+                throw wrongKind();
+        }
+        else if (decision.kind === 'revise-api-inputs' ||
+            decision.kind === 'revise-api-bindings') {
+            const call = content.apiCalls.find((call) => call.id === decision.nodeId);
+            const material = resolveWorkflowDraftApiMaterials({
+                content,
+                context: input.context,
+            }).find((material) => material.callId === call.id);
+            if (decision.kind === 'revise-api-inputs' &&
+                resolution.kind === 'api-inputs')
+                add({
+                    kind: 'update-api-call',
+                    call: {
+                        ...call,
+                        ...(call.requestedInputs === undefined
+                            ? {}
+                            : {
+                                requestedInputs: retainRequestedApiInputsAfterEdits(call.requestedInputs, resolution.edits),
+                            }),
+                        values: applyWorkflowDraftApiInputEdits(call.values, resolution.edits, {
+                            ...material,
+                            ...(resolution.requestMediaType === undefined
+                                ? {}
+                                : { requestMediaType: resolution.requestMediaType }),
+                        }),
+                        ...(resolution.requestMediaType === undefined
+                            ? {}
+                            : { requestMediaType: resolution.requestMediaType }),
+                    },
+                });
+            else if (decision.kind === 'revise-api-bindings' &&
+                resolution.kind === 'api-bindings')
+                add({
+                    kind: 'update-api-call',
+                    call: {
+                        ...call,
+                        values: applyWorkflowDraftApiInputEdits(call.values, resolution.valueEdits, material),
+                        bindings: applyWorkflowDraftBindingEdits(call.bindings, resolution.edits, `Draft API ${call.id}`),
+                    },
+                });
+            else
+                throw wrongKind();
+        }
+        else if (decision.kind === 'revise-requirement' ||
+            decision.kind === 'restore-requirement') {
+            if (resolution.kind !== 'requirement')
+                throw wrongKind();
+            const reference = decision.kind === 'restore-requirement'
+                ? listRemovedWorkflowDraftRequirements(input.draft)
+                : content.requirements;
+            const previous = reference.find((requirement) => requirement.id === decision.requirementId);
+            add({
+                kind: 'set-requirement',
+                requirement: {
+                    id: previous.id,
+                    ...(previous.origin === undefined ? {} : { origin: previous.origin }),
+                    text: resolution.text,
+                    state: resolution.state,
+                    scope: resolution.scope,
+                    sourceMessageIds: [
+                        ...new Set([
+                            ...decision.sources.map((source) => source.messageId),
+                            resolution.answerMessageId,
+                        ]),
+                    ],
+                },
+            });
+        }
+    }
+    if (byStep.size)
+        throw new Error(`Unexpected resolution for deterministic draft edit step: ${[...byStep.keys()].join(', ')}`);
+    return {
+        kind: 'unvalidated-edit-materials',
+        planId: input.plan.id,
+        baseRevision: input.plan.baseRevision,
+        content,
+        nodeRemovalConnections,
+        changes,
+        pendingRepairs: [],
+        deferredRequirementIds,
+        pendingResolutionStepIds,
+        pendingClarificationQuestionIds: input.context.clarification === undefined
+            ? []
+            : [
+                ...input.context.clarification.resolution.pendingQuestionIds,
+                ...input.context.clarification.resolution.deferredQuestionIds,
+            ],
+    };
+}

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

@@ -0,0 +1,4 @@
+import type { PrepareWorkflowDraftEditInput } from '../../../types/workflow-draft-edit-assembly.js';
+import type { PrimaryWorkflowDraftEdit, WorkflowDraftEditPreparationMode } from '../../../types/workflow-draft-edit-assembly-internal.js';
+/** Recompute repair authority after each explicit result; never trust client-edited material state. */
+export declare function resolvePreparedWorkflowDraftEdit(input: PrepareWorkflowDraftEditInput, mode: WorkflowDraftEditPreparationMode): PrimaryWorkflowDraftEdit;

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[];