@openapi-flow/core 0.2.0 → 0.3.0

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

package/dist/draft/edits/describe-workflow-draft-selected-nodes.js

@@ -0,0 +1,67 @@
+import { validateWorkflowDraftEditPlan } from './validate-workflow-draft-edit-plan.js';
+import { resolveWorkflowDraftApiResponseSources } from './references/resolve-workflow-draft-api-response-sources.js';
+/** Final selected identities exist before values; removed nodes never remain scope candidates. */
+export function describeWorkflowDraftSelectedNodes(input) {
+    validateWorkflowDraftEditPlan(input);
+    const removed = new Set(input.plan.steps.flatMap((step) => step.decision.kind === 'remove-node' ? [step.decision.nodeId] : []));
+    const content = {
+        ...input.draft,
+        apiCalls: input.draft.apiCalls.filter((call) => !removed.has(call.id)),
+    };
+    const apis = resolveWorkflowDraftApiResponseSources({
+        content,
+        context: input.context,
+        plan: input.plan,
+        pendingResolutionStepIds: input.plan.steps.map((step) => step.id),
+    });
+    const nodes = apis.map((source) => ({
+        id: source.nodeId,
+        kind: 'api',
+        operation: source.operation,
+        ...(source.preparation.status === 'request-pending'
+            ? { instruction: source.preparation.instruction }
+            : {}),
+    }));
+    for (const node of input.draft.nativeNodes.filter((node) => !removed.has(node.id))) {
+        const step = input.plan.steps.find((step) => 'nodeId' in step.decision && step.decision.nodeId === node.id);
+        nodes.push({
+            id: node.id,
+            kind: 'native',
+            capability: node.capability,
+            ...(step === undefined ? {} : { instruction: step.decision.instruction }),
+        });
+    }
+    for (const step of input.plan.steps)
+        if (step.decision.kind === 'add-native-node') {
+            if (!step.newNodeId)
+                throw new Error(`Selected native ${step.id} requires its allocated identity`);
+            nodes.push({
+                id: step.newNodeId,
+                kind: 'native',
+                capability: step.decision.capability,
+                instruction: step.decision.instruction,
+            });
+        }
+    for (const gap of input.draft.gapNodes === undefined
+        ? []
+        : input.draft.gapNodes)
+        if (!removed.has(gap.id))
+            nodes.push({
+                id: gap.id,
+                kind: 'capability-gap',
+                instruction: gap.requestedBehavior,
+            });
+    for (const step of input.plan.steps)
+        if (step.decision.kind === 'report-capability-gap') {
+            if (!step.newNodeId)
+                throw new Error(`Selected capability gap ${step.id} requires its allocated identity`);
+            nodes.push({
+                id: step.newNodeId,
+                kind: 'capability-gap',
+                instruction: step.decision.instruction,
+            });
+        }
+    if (new Set(nodes.map((node) => node.id)).size !== nodes.length)
+        throw new Error('Selected nodes require distinct actual identities');
+    return nodes;
+}

package/dist/draft/edits/inputs/create-workflow-draft-api-input-edit-contract.d.ts

@@ -0,0 +1,3 @@
+import type { CreateWorkflowDraftApiInputEditContractInput, WorkflowDraftApiInputEditContract } from '../../../types/workflow-draft-api-input-edit.js';
+/** Bind selected fields to original contracts. A proposed schema is never trusted. */
+export declare function createWorkflowDraftApiInputEditContract(input: CreateWorkflowDraftApiInputEditContractInput): WorkflowDraftApiInputEditContract;

package/dist/draft/edits/inputs/create-workflow-draft-api-input-edit-contract.js

@@ -0,0 +1,68 @@
+import { createHash } from 'node:crypto';
+import { describeWorkflowDraftApiInputEdit } from './describe-workflow-draft-api-input-edit.js';
+import { createWorkflowDraftApiInputEditProposalSchema } from '../../../schemas/workflow-draft-api-input-edit-proposal-schema.js';
+import { validateWorkflowPlanningEvidence } from '../../../planning/evidence/validate-workflow-planning-evidence.js';
+import { hasPointer, pointerTokens } from '../../../bindings/json-pointer.js';
+import { schemasAtPointer } from '../../../bindings/schema-at-pointer.js';
+import { createSchemaResourceContext } from '../../../bindings/resources/create-schema-resource-context.js';
+import { retainRequestedApiInputsAfterEdits } from './retain-requested-api-inputs-after-edits.js';
+/** Bind selected fields to original contracts. A proposed schema is never trusted. */
+export function createWorkflowDraftApiInputEditContract(input) {
+    const described = describeWorkflowDraftApiInputEdit(input);
+    const proposal = createWorkflowDraftApiInputEditProposalSchema(input.requestMessageIds, described.includeExplanations).parse(input.proposal);
+    const resources = createSchemaResourceContext(described.requestSchema);
+    const seen = [];
+    const targets = proposal.targets.map((target, index) => {
+        const tokens = pointerTokens(target.pointer);
+        if (!tokens.length ||
+            seen.some((pointer) => pointer === target.pointer ||
+                pointer.startsWith(target.pointer + '/') ||
+                target.pointer.startsWith(pointer + '/')))
+            throw new Error(`API input edit has duplicate or overlapping targets at ${target.pointer}`);
+        seen.push(target.pointer);
+        if (described.call.bindings.some((binding) => binding.targetPointer === target.pointer ||
+            binding.targetPointer.startsWith(target.pointer + '/') ||
+            target.pointer.startsWith(binding.targetPointer + '/')))
+            throw new Error(`API input edit ${target.pointer} overlaps binding ownership; use a binding edit instead`);
+        validateWorkflowPlanningEvidence({
+            context: { messages: described.messages },
+            evidence: target.sources,
+        });
+        if (target.explanation)
+            validateWorkflowPlanningEvidence({
+                context: { messages: described.messages },
+                evidence: target.explanation.evidence,
+            });
+        if (target.kind === 'remove' &&
+            !hasPointer(described.call.values, target.pointer) &&
+            (described.call.requestedInputs === undefined ||
+                retainRequestedApiInputsAfterEdits(described.call.requestedInputs, [
+                    { kind: 'remove', pointer: target.pointer },
+                ]).length === described.call.requestedInputs.length))
+            throw new Error(`API input edit cannot remove absent value ${target.pointer}`);
+        const schema = target.kind === 'set'
+            ? schemasAtPointer(resources.root, target.pointer, resources)[0]
+            : undefined;
+        if (target.kind === 'set' && schema === undefined)
+            throw new Error(`API input edit target ${target.pointer} is not permitted by its OAS`);
+        const fields = { ...target, id: `value-${index + 1}` };
+        return target.kind === 'remove'
+            ? { ...fields, kind: 'remove' }
+            : { ...fields, kind: 'set', schema: schema };
+    });
+    const fields = {
+        planId: input.plan.id,
+        stepId: input.stepId,
+        nodeId: described.call.id,
+        schemaResource: resources.root,
+        targets,
+        ...(described.call.requestMediaType === undefined
+            ? {}
+            : { requestMediaType: described.call.requestMediaType }),
+    };
+    return {
+        id: 'api-input-edit:' +
+            createHash('sha256').update(JSON.stringify(fields)).digest('hex'),
+        ...fields,
+    };
+}

package/dist/draft/edits/inputs/describe-workflow-draft-api-input-edit.d.ts

@@ -0,0 +1,2 @@
+import type { WorkflowDraftApiInputEditDescription, WorkflowDraftApiInputEditInput } from '../../../types/workflow-draft-api-input-edit.js';
+export declare function describeWorkflowDraftApiInputEdit(input: WorkflowDraftApiInputEditInput): WorkflowDraftApiInputEditDescription;

package/dist/draft/edits/inputs/describe-workflow-draft-api-input-edit.js

@@ -0,0 +1,36 @@
+import { validateWorkflowDraftEditPlan } from '../validate-workflow-draft-edit-plan.js';
+import { createApiRequestSchema } from '../../../schemas/create-api-request-schema.js';
+import { resolveWorkflowDraftApiMaterials } from '../../resolve-workflow-draft-api-materials.js';
+import { resolveWorkflowPlanningMessages } from '../../../planning/evidence/resolve-workflow-planning-messages.js';
+export function describeWorkflowDraftApiInputEdit(input) {
+    validateWorkflowDraftEditPlan(input);
+    const step = input.plan.steps.find((step) => step.id === input.stepId);
+    if (!step || step.decision.kind !== 'revise-api-inputs')
+        throw new Error('API input edit stepId must identify a revise-api-inputs decision');
+    const nodeId = step.decision.nodeId;
+    if (input.plan.steps.some((other) => other.decision.kind === 'replace-api-operation' &&
+        other.decision.nodeId === nodeId))
+        throw new Error('API input edit must use a draft after its operation replacement is resolved');
+    const original = input.draft.apiCalls.find((call) => call.id === nodeId);
+    const material = resolveWorkflowDraftApiMaterials({
+        content: input.draft,
+        context: input.context,
+    }).find((item) => item.callId === original.id);
+    const call = structuredClone({
+        ...original,
+        ...(input.requestMediaType === undefined
+            ? {}
+            : { requestMediaType: input.requestMediaType }),
+    });
+    return {
+        stepId: step.id,
+        instruction: step.decision.instruction,
+        call,
+        requestSchema: createApiRequestSchema({
+            operation: material.operation,
+            requestMediaType: call.requestMediaType,
+        }),
+        messages: structuredClone(resolveWorkflowPlanningMessages(input.context).filter((message) => input.requestMessageIds.includes(message.id))),
+        includeExplanations: input.plan.options.includeExplanations,
+    };
+}

package/dist/draft/edits/inputs/resolve-workflow-draft-api-input-edits.d.ts

@@ -0,0 +1,3 @@
+import type { ResolveWorkflowDraftApiInputEditsInput, WorkflowDraftApiInputEditResult } from '../../../types/workflow-draft-api-input-edit.js';
+/** Exact-source validation is deterministic; it is not semantic entailment proof. */
+export declare function resolveWorkflowDraftApiInputEdits(input: ResolveWorkflowDraftApiInputEditsInput): WorkflowDraftApiInputEditResult;

package/dist/draft/edits/inputs/resolve-workflow-draft-api-input-edits.js

@@ -0,0 +1,75 @@
+import { createWorkflowDraftApiInputEditValuesSchema } from '../../../schemas/create-workflow-draft-api-input-edit-values-schema.js';
+import { describeWorkflowDraftApiInputEdit } from './describe-workflow-draft-api-input-edit.js';
+import { validateWorkflowPlanningEvidence } from '../../../planning/evidence/validate-workflow-planning-evidence.js';
+import { applyWorkflowDraftApiInputEdits } from '../values/apply-workflow-draft-api-input-edits.js';
+import { resolveWorkflowDraftApiMaterials } from '../../resolve-workflow-draft-api-materials.js';
+import { validateApiArguments } from '../../../arguments/validate-api-arguments.js';
+import { orderWorkflowDraftValueEdits } from '../values/order-workflow-draft-value-edits.js';
+import { verifyApiInputLiteralSource } from '../../../arguments/sources/verify-api-input-literal-source.js';
+/** Exact-source validation is deterministic; it is not semantic entailment proof. */
+export function resolveWorkflowDraftApiInputEdits(input) {
+    const output = createWorkflowDraftApiInputEditValuesSchema(input).parse(input.output);
+    const described = describeWorkflowDraftApiInputEdit(input);
+    const sets = [];
+    const removals = [];
+    const pendingTargets = [];
+    for (const target of input.contract.targets) {
+        if (target.kind === 'remove') {
+            removals.push({ kind: 'remove', pointer: target.pointer });
+            continue;
+        }
+        const answer = output.values[target.id];
+        if (answer.explanation)
+            validateWorkflowPlanningEvidence({
+                context: { messages: described.messages },
+                evidence: answer.explanation.evidence,
+            });
+        if (answer.status === 'needs-input') {
+            pendingTargets.push(structuredClone(target));
+            continue;
+        }
+        const message = described.messages.find((message) => message.id === answer.source.messageId);
+        if (!message)
+            throw new Error(`API input edit ${target.pointer} value source is absent from the current request`);
+        verifyApiInputLiteralSource({
+            ...answer.source,
+            text: message.text,
+            value: answer.value,
+            label: `API input edit ${target.pointer}`,
+        });
+        sets.push({ kind: 'set', pointer: target.pointer, value: answer.value });
+    }
+    if (pendingTargets.length)
+        return {
+            status: 'needs-input',
+            contractId: input.contract.id,
+            values: output,
+            pendingTargets,
+        };
+    // Targets address the original value. Set before deletion; remove higher array
+    // indices first so one deletion does not retarget another original index.
+    const edits = orderWorkflowDraftValueEdits([...sets, ...removals]);
+    const material = resolveWorkflowDraftApiMaterials({
+        content: input.draft,
+        context: input.context,
+    }).find((item) => item.callId === described.call.id);
+    const selected = {
+        ...material,
+        requestMediaType: described.call.requestMediaType,
+    };
+    const values = applyWorkflowDraftApiInputEdits(described.call.values, edits, selected);
+    validateApiArguments({ ...selected, values });
+    return {
+        status: 'ready',
+        contractId: input.contract.id,
+        values: output,
+        resolution: {
+            stepId: input.stepId,
+            kind: 'api-inputs',
+            edits,
+            ...(input.contract.requestMediaType === undefined
+                ? {}
+                : { requestMediaType: input.contract.requestMediaType }),
+        },
+    };
+}

package/dist/draft/edits/inputs/retain-requested-api-inputs-after-edits.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowDraftValueEdit } from '../../../types/workflow-draft-edit-assembly.js';
+/** An explicit removal withdraws only that input intent and its descendants. */
+export declare function retainRequestedApiInputsAfterEdits(requestedInputs: string[], edits: WorkflowDraftValueEdit[]): string[];

package/dist/draft/edits/inputs/retain-requested-api-inputs-after-edits.js

@@ -0,0 +1,7 @@
+/** An explicit removal withdraws only that input intent and its descendants. */
+export function retainRequestedApiInputsAfterEdits(requestedInputs, edits) {
+    return requestedInputs.filter((pointer) => !edits.some((edit) => edit.kind === 'remove' &&
+        (edit.pointer === '' ||
+            pointer === edit.pointer ||
+            pointer.startsWith(edit.pointer + '/'))));
+}

package/dist/draft/edits/inputs/validate-workflow-draft-api-input-edit-contract.d.ts

@@ -0,0 +1,2 @@
+import type { WorkflowDraftApiInputEditContractInput } from '../../../types/workflow-draft-api-input-edit.js';
+export declare function validateWorkflowDraftApiInputEditContract(input: WorkflowDraftApiInputEditContractInput): void;

package/dist/draft/edits/inputs/validate-workflow-draft-api-input-edit-contract.js

@@ -0,0 +1,23 @@
+import { isDeepStrictEqual } from 'node:util';
+import { createWorkflowDraftApiInputEditContract } from './create-workflow-draft-api-input-edit-contract.js';
+import { workflowDraftApiInputEditContractSchema } from '../../../schemas/workflow-draft-api-input-edit-contract-schema.js';
+export function validateWorkflowDraftApiInputEditContract(input) {
+    const envelope = workflowDraftApiInputEditContractSchema.safeParse(input.contract);
+    if (!envelope.success)
+        throw new Error('API input edit contract has invalid metadata or target fields', { cause: envelope.error });
+    const expected = createWorkflowDraftApiInputEditContract({
+        ...input,
+        proposal: {
+            targets: input.contract.targets.map((target) => ({
+                kind: target.kind,
+                pointer: target.pointer,
+                sources: target.sources,
+                ...(target.explanation === undefined
+                    ? {}
+                    : { explanation: target.explanation }),
+            })),
+        },
+    });
+    if (!isDeepStrictEqual(expected, input.contract))
+        throw new Error('API input edit contract is stale or has modified identities, fields or schemas');
+}

package/dist/draft/edits/native/additions/describe-workflow-draft-native-node-addition-readiness.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowDraftNativeNodeAdditionInput, WorkflowDraftNativeNodeAdditionReadiness } from '../../../../types/workflow-draft-native-node-addition.js';
+/** Availability is not a valid parameter choice, graph edge or execution result. No model call. */
+export declare function describeWorkflowDraftNativeNodeAdditionReadiness(input: WorkflowDraftNativeNodeAdditionInput): WorkflowDraftNativeNodeAdditionReadiness;

package/dist/draft/edits/native/additions/describe-workflow-draft-native-node-addition-readiness.js

@@ -0,0 +1,14 @@
+import { resolveNativeNodeAdditionMaterials } from './resolve-native-node-addition-materials.js';
+/** Availability is not a valid parameter choice, graph edge or execution result. No model call. */
+export function describeWorkflowDraftNativeNodeAdditionReadiness(input) {
+    const { nodeId, definition, missingContext, pendingSourceNodeIds, sourceDependencies, } = resolveNativeNodeAdditionMaterials(input);
+    return {
+        status: missingContext.length || pendingSourceNodeIds.length
+            ? 'requires-context'
+            : 'ready',
+        nodeId,
+        capability: definition.name,
+        missingContext,
+        ...(sourceDependencies === undefined ? {} : { pendingSourceNodeIds }),
+    };
+}

package/dist/draft/edits/native/additions/describe-workflow-draft-native-node-addition.d.ts

@@ -0,0 +1,2 @@
+import type { WorkflowDraftNativeNodeAdditionInput, WorkflowDraftNativeNodeAdditionDescription } from '../../../../types/workflow-draft-native-node-addition.js';
+export declare function describeWorkflowDraftNativeNodeAddition(input: WorkflowDraftNativeNodeAdditionInput): WorkflowDraftNativeNodeAdditionDescription;