@openapi-flow/core 0.1.0 → 0.3.0

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

@@ -0,0 +1,3 @@
+import type { ApproveWorkflowDraftInput, WorkflowDraft } from '../types/workflow-draft.js';
+/** Host approval is an explicit revision-checked action, not a model field. */
+export declare function approveWorkflowDraft(input: ApproveWorkflowDraftInput): WorkflowDraft;

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

@@ -0,0 +1,32 @@
+import { randomUUID } from 'node:crypto';
+import { inspectDraftReadiness } from './inspect-draft-readiness.js';
+import { draftRevisionSchema } from '../schemas/workflow-draft-schema.js';
+import { validateWorkflowDraft } from './validate-workflow-draft.js';
+/** Host approval is an explicit revision-checked action, not a model field. */
+export function approveWorkflowDraft(input) {
+    const readiness = inspectDraftReadiness(input);
+    draftRevisionSchema.parse(input.expectedRevision);
+    if (input.expectedRevision !== input.draft.revision)
+        throw new Error(`Stale approval revision: expected ${input.draft.revision}, received ${input.expectedRevision}`);
+    if (!Array.isArray(input.nodeIds) ||
+        !input.nodeIds.length ||
+        new Set(input.nodeIds).size !== input.nodeIds.length)
+        throw new Error('Draft approval requires distinct nodeIds');
+    for (const id of input.nodeIds) {
+        const node = readiness.nodes.find((node) => node.nodeId === id);
+        if (!node || node.planningStatus !== 'ready')
+            throw new Error(`Cannot approve unknown or decision-blocked node ${id}`);
+    }
+    if (input.draft.revision === Number.MAX_SAFE_INTEGER)
+        throw new Error('Draft revision cannot exceed Number.MAX_SAFE_INTEGER');
+    const draft = structuredClone(input.draft);
+    draft.revision++;
+    draft.approvals.push({
+        id: randomUUID(),
+        revision: draft.revision,
+        nodeIds: [...input.nodeIds],
+        invalidatedNodeIds: [],
+    });
+    validateWorkflowDraft({ draft, context: input.context });
+    return draft;
+}

package/dist/draft/changes/apply-draft-change-set.d.ts

@@ -0,0 +1,3 @@
+import type { ApplyDraftChangeSetInput, ApplyDraftChangeSetResult } from '../../types/workflow-draft-changes.js';
+/** Commit one validated candidate; any error leaves the source draft unchanged. */
+export declare function applyDraftChangeSet(input: ApplyDraftChangeSetInput): ApplyDraftChangeSetResult;

package/dist/draft/changes/apply-draft-change-set.js

@@ -0,0 +1,75 @@
+import { draftChangeSetSchema } from '../../schemas/draft-change-set-schema.js';
+import { validateWorkflowDraft } from '../validate-workflow-draft.js';
+import { applyDraftChange } from './apply-draft-change.js';
+import { analyzeDraftChangeImpact } from '../impact/analyze-draft-change-impact.js';
+import { isDeepStrictEqual } from 'node:util';
+import { appendWorkflowDraftRequirementHistory } from '../requirements/history/append-workflow-draft-requirement-history.js';
+/** Commit one validated candidate; any error leaves the source draft unchanged. */
+export function applyDraftChangeSet(input) {
+    validateWorkflowDraft(input);
+    const changeSet = draftChangeSetSchema.parse(input.changeSet);
+    if (changeSet.baseRevision !== input.draft.revision)
+        throw new Error(`Stale draft revision: expected ${input.draft.revision}, received ${changeSet.baseRevision}`);
+    if (input.draft.revision === Number.MAX_SAFE_INTEGER)
+        throw new Error('Draft revision cannot exceed Number.MAX_SAFE_INTEGER');
+    const content = structuredClone({
+        id: input.draft.id,
+        requirements: input.draft.requirements,
+        apiCalls: input.draft.apiCalls,
+        nativeNodes: input.draft.nativeNodes,
+        ...(input.draft.gapNodes === undefined
+            ? {}
+            : { gapNodes: input.draft.gapNodes }),
+        edges: input.draft.edges,
+    });
+    const requirementHistory = structuredClone(input.draft.requirementHistory);
+    for (const change of changeSet.changes) {
+        if (change.kind === 'set-requirement' ||
+            change.kind === 'remove-requirement') {
+            const requirementId = change.kind === 'set-requirement'
+                ? change.requirement.id
+                : change.requirementId;
+            const before = content.requirements.find((item) => item.id === requirementId);
+            applyDraftChange(content, change);
+            const after = content.requirements.find((item) => item.id === requirementId);
+            if (!isDeepStrictEqual(before, after))
+                requirementHistory.push(appendWorkflowDraftRequirementHistory({
+                    draftId: input.draft.id,
+                    revision: input.draft.revision + 1,
+                    history: requirementHistory,
+                    before,
+                    after,
+                    sourceMessageIds: change.kind === 'set-requirement'
+                        ? change.requirement.sourceMessageIds
+                        : change.sourceMessageIds,
+                    messages: input.context.messages,
+                }));
+        }
+        else
+            applyDraftChange(content, change);
+    }
+    const impact = analyzeDraftChangeImpact({
+        before: input.draft,
+        after: content,
+        context: input.context,
+    });
+    if (!impact.affectedNodeIds.length && !impact.changedRequirementIds.length)
+        throw new Error('Draft change set does not change any requirement, node or connection');
+    const affected = new Set(impact.affectedNodeIds);
+    const draft = {
+        ...content,
+        revision: input.draft.revision + 1,
+        requirementHistory,
+        approvals: input.draft.approvals.map((approval) => ({
+            ...structuredClone(approval),
+            invalidatedNodeIds: [
+                ...new Set([
+                    ...approval.invalidatedNodeIds,
+                    ...approval.nodeIds.filter((id) => affected.has(id)),
+                ]),
+            ],
+        })),
+    };
+    validateWorkflowDraft({ draft, context: input.context });
+    return { draft, impact };
+}

package/dist/draft/changes/apply-draft-change.d.ts

@@ -0,0 +1,4 @@
+import type { WorkflowDraftContent } from '../../types/workflow-draft.js';
+import type { WorkflowDraftChange } from '../../types/workflow-draft-changes.js';
+/** Mutate only an isolated candidate; callers validate the complete transaction. */
+export declare function applyDraftChange(content: WorkflowDraftContent, change: WorkflowDraftChange): void;

package/dist/draft/changes/apply-draft-change.js

@@ -0,0 +1,77 @@
+import { draftEdgeKey } from './draft-edge-key.js';
+/** Mutate only an isolated candidate; callers validate the complete transaction. */
+export function applyDraftChange(content, change) {
+    switch (change.kind) {
+        case 'add-capability-gap':
+            assertNewId(content, change.node.id);
+            if (content.gapNodes === undefined)
+                content.gapNodes = [];
+            content.gapNodes.push(structuredClone(change.node));
+            break;
+        case 'add-api-call':
+            assertNewId(content, change.call.id);
+            content.apiCalls.push(structuredClone(change.call));
+            break;
+        case 'update-api-call': {
+            const index = content.apiCalls.findIndex((call) => call.id === change.call.id);
+            if (index < 0)
+                throw new Error(`Cannot update unknown API call ${change.call.id}`);
+            content.apiCalls[index] = structuredClone(change.call);
+            break;
+        }
+        case 'add-native-node':
+            assertNewId(content, change.node.id);
+            content.nativeNodes.push(structuredClone(change.node));
+            break;
+        case 'update-native-node': {
+            const index = content.nativeNodes.findIndex((node) => node.id === change.node.id);
+            if (index < 0)
+                throw new Error(`Cannot update unknown native node ${change.node.id}`);
+            content.nativeNodes[index] = structuredClone(change.node);
+            break;
+        }
+        case 'remove-node': {
+            if (!content.apiCalls.some((call) => call.id === change.nodeId) &&
+                !content.nativeNodes.some((node) => node.id === change.nodeId) &&
+                !content.gapNodes?.some((node) => node.id === change.nodeId))
+                throw new Error(`Cannot remove unknown draft node ${change.nodeId}`);
+            content.apiCalls = content.apiCalls.filter((call) => call.id !== change.nodeId);
+            content.nativeNodes = content.nativeNodes.filter((node) => node.id !== change.nodeId);
+            if (content.gapNodes !== undefined)
+                content.gapNodes = content.gapNodes.filter((node) => node.id !== change.nodeId);
+            break;
+        }
+        case 'add-edge':
+            content.edges.push(structuredClone(change.edge));
+            break;
+        case 'remove-edge': {
+            const key = draftEdgeKey(change.edge);
+            const index = content.edges.findIndex((edge) => draftEdgeKey(edge) === key);
+            if (index < 0)
+                throw new Error('Cannot remove an undeclared draft edge');
+            content.edges.splice(index, 1);
+            break;
+        }
+        case 'set-requirement': {
+            const index = content.requirements.findIndex((item) => item.id === change.requirement.id);
+            if (index < 0)
+                content.requirements.push(structuredClone(change.requirement));
+            else
+                content.requirements[index] = structuredClone(change.requirement);
+            break;
+        }
+        case 'remove-requirement': {
+            const index = content.requirements.findIndex((item) => item.id === change.requirementId);
+            if (index < 0)
+                throw new Error(`Cannot remove unknown requirement ${change.requirementId}`);
+            content.requirements.splice(index, 1);
+            break;
+        }
+    }
+}
+function assertNewId(content, id) {
+    if (content.apiCalls.some((call) => call.id === id) ||
+        content.nativeNodes.some((node) => node.id === id) ||
+        content.gapNodes?.some((node) => node.id === id))
+        throw new Error(`Draft node ${id} already exists; use an explicit update`);
+}

package/dist/draft/changes/draft-edge-key.d.ts

@@ -0,0 +1,2 @@
+import type { WorkflowPlanEdge } from '../../types/workflow-plan.js';
+export declare function draftEdgeKey(edge: WorkflowPlanEdge): string;

package/dist/draft/changes/draft-edge-key.js

@@ -0,0 +1,3 @@
+export function draftEdgeKey(edge) {
+    return JSON.stringify([edge.from, edge.output, edge.to, edge.input]);
+}

package/dist/draft/contracts/resolve-workflow-draft-node-contracts.d.ts

@@ -0,0 +1,4 @@
+import type { WorkflowDraftInput } from '../../types/workflow-draft.js';
+import type { WorkflowPlanNodeContract } from '../../types/workflow-plan.js';
+/** Actual implementation/OAS contracts for an already validated canonical draft. */
+export declare function resolveWorkflowDraftNodeContracts(input: WorkflowDraftInput): WorkflowPlanNodeContract[];

package/dist/draft/contracts/resolve-workflow-draft-node-contracts.js

@@ -0,0 +1,38 @@
+import { resolveWorkflowDraftMaterials } from '../resolve-workflow-draft-materials.js';
+import { resolveWorkflowDraftNativeSnapshot } from '../resolve-workflow-draft-native-snapshot.js';
+import { createWorkflowNodeContracts } from '../../workflow/create-workflow-node-contracts.js';
+import { NativeMaterialResolutionError } from '../../workflow/native-material-resolution-error.js';
+/** Actual implementation/OAS contracts for an already validated canonical draft. */
+export function resolveWorkflowDraftNodeContracts(input) {
+    const { materials, slots } = resolveWorkflowDraftMaterials(input);
+    const snapshot = resolveWorkflowDraftNativeSnapshot({
+        content: input.draft,
+        context: input.context,
+        deferredNodeIds: [],
+        unavailableApiNodeIds: [],
+    });
+    if (snapshot.status !== 'ready')
+        throw new NativeMaterialResolutionError(snapshot.pending);
+    return createWorkflowNodeContracts({
+        unresolvedNodes: input.draft.gapNodes,
+        materials: materials.map((material) => ({
+            operation: material.operation,
+            arguments: {
+                callId: material.callId,
+                values: material.values,
+                bindings: material.bindings,
+                ...(material.requestMediaType === undefined
+                    ? {}
+                    : { requestMediaType: material.requestMediaType }),
+                ...(material.requestedInputs === undefined
+                    ? {}
+                    : { requestedInputs: material.requestedInputs }),
+                unresolvedInputs: slots
+                    .filter((slot) => slot.callId === material.callId)
+                    .map((slot) => slot.targetPointer),
+            },
+        })),
+        nativeNodes: input.draft.nativeNodes,
+        capabilities: snapshot.capabilities,
+    });
+}

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

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

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

@@ -0,0 +1,24 @@
+import { workflowDraftContentSchema } from '../schemas/workflow-draft-schema.js';
+import { validateWorkflowDraft } from './validate-workflow-draft.js';
+import { appendWorkflowDraftRequirementHistory } from './requirements/history/append-workflow-draft-requirement-history.js';
+export function createWorkflowDraft(input) {
+    if (!input.context || !Array.isArray(input.context.messages))
+        throw new Error('draft context.messages must be an explicit array');
+    const draft = {
+        ...workflowDraftContentSchema.parse(input.content),
+        revision: 0,
+        approvals: [],
+        requirementHistory: [],
+    };
+    for (const requirement of draft.requirements)
+        draft.requirementHistory.push(appendWorkflowDraftRequirementHistory({
+            draftId: draft.id,
+            revision: 0,
+            history: draft.requirementHistory,
+            after: requirement,
+            sourceMessageIds: requirement.sourceMessageIds,
+            messages: input.context.messages,
+        }));
+    validateWorkflowDraft({ draft, context: input.context });
+    return structuredClone(draft);
+}

package/dist/draft/edits/api/create-workflow-draft-api-binding-questions.d.ts

@@ -0,0 +1,5 @@
+import type { WorkflowDraftApiCallBindingsDescription, WorkflowDraftApiCallBindingProposal, ProposedWorkflowDraftApiCallMapping } from '../../../types/workflow-draft-api-call-planning.js';
+import type { WorkflowDraftApiCallPlanningQuestion } from '../../../types/workflow-draft-api-binding-clarification.js';
+import type { ResolvedWorkflowDraftSourceEvidence } from '../../../types/workflow-draft-source-evidence.js';
+/** The model selects unresolved inputs, never question wording, other operation contracts or UI identities. */
+export declare function createWorkflowDraftApiBindingQuestions(description: WorkflowDraftApiCallBindingsDescription, proposal: WorkflowDraftApiCallBindingProposal, mappings: ProposedWorkflowDraftApiCallMapping[], evidence: ResolvedWorkflowDraftSourceEvidence): WorkflowDraftApiCallPlanningQuestion[];

package/dist/draft/edits/api/create-workflow-draft-api-binding-questions.js

@@ -0,0 +1,65 @@
+import { createHash } from 'node:crypto';
+import { requestBindingSchemas } from '../../../bindings/request-binding-schema.js';
+import { validateWorkflowDraftApiCallMappings } from './validate-workflow-draft-api-call-mappings.js';
+/** The model selects unresolved inputs, never question wording, other operation contracts or UI identities. */
+export function createWorkflowDraftApiBindingQuestions(description, proposal, mappings, evidence) {
+    if (proposal.decision.status !== 'needs-clarification')
+        throw new Error('Binding questions require the original unresolved proposal');
+    const targets = mappings.map((mapping) => mapping.targetPointer);
+    return proposal.decision.questions.map((question) => {
+        const pointer = question.targetPointer;
+        if (description.inputIntent !== undefined &&
+            !description.inputIntent.targets.includes(pointer))
+            throw new Error(`API binding question ${pointer} is outside the selected input intent`);
+        if (targets.some((target) => target === pointer ||
+            target.startsWith(pointer + '/') ||
+            pointer.startsWith(target + '/')))
+            throw new Error(`Binding question overlaps an already assigned or unresolved input: ${pointer}`);
+        targets.push(pointer);
+        const targetSchemas = requestBindingSchemas({
+            callId: description.nodeId,
+            operation: description.operation,
+            requestMediaType: description.requestMediaType,
+        }, pointer);
+        if (!targetSchemas.length)
+            throw new Error(`Binding question ${pointer} is not declared by selected API ${description.operation.method} ${description.operation.path}`);
+        const id = 'api-call-binding-question:' +
+            createHash('sha256')
+                .update(JSON.stringify([description.fingerprint, proposal, question]))
+                .digest('hex');
+        const candidates = question.kind === 'choose-source' ? question.candidates : [];
+        if (new Set(candidates.map((candidate) => JSON.stringify(candidate))).size !==
+            candidates.length)
+            throw new Error('Binding question repeats an identical source alternative');
+        const choices = candidates.map((candidate) => {
+            validateWorkflowDraftApiCallMappings(description, [
+                { targetPointer: pointer, ...candidate },
+            ]);
+            const source = description.sources.values.find((source) => source.nodeId === candidate.sourceNodeId);
+            const label = source.kind === 'api'
+                ? `${source.operation.method} ${source.operation.path} 응답`
+                : `${source.node.capability} 출력`;
+            return {
+                id: 'api-binding-choice:' +
+                    createHash('sha256')
+                        .update(JSON.stringify([id, candidate]))
+                        .digest('hex'),
+                label: `${label} ${candidate.sourcePointer === '' ? '(전체 값)' : candidate.sourcePointer}`,
+                ...candidate,
+            };
+        });
+        return {
+            id,
+            nodeId: description.nodeId,
+            operation: structuredClone(description.operation.key),
+            method: description.operation.method,
+            path: description.operation.path,
+            kind: question.kind,
+            targetPointer: pointer,
+            targetSchemas: structuredClone(targetSchemas),
+            message: `${description.operation.method} ${description.operation.path}의 ${pointer} 입력에 ${question.kind === 'choose-source' ? '연결할 선행 응답을 선택해 주세요.' : '선행 응답을 연결할지, 직접 입력값을 사용할지 선택해 주세요.'}`,
+            choices,
+            ...evidence,
+        };
+    });
+}

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

@@ -0,0 +1,4 @@
+import type { WorkflowDraftApiCallPlanningInput } from '../../../types/workflow-draft-api-call-planning.js';
+import type { WorkflowDraftApiBindingIntentDescription } from '../../../types/workflow-draft-api-binding-intent.js';
+/** Intent belongs to the selected request and messages, not changing producer readiness. */
+export declare function describeWorkflowDraftApiBindingIntent(input: WorkflowDraftApiCallPlanningInput): WorkflowDraftApiBindingIntentDescription;

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

@@ -0,0 +1,32 @@
+import { createHash } from 'node:crypto';
+import { describeWorkflowDraftApiCallPlanning } from './describe-workflow-draft-api-call-planning.js';
+/** Intent belongs to the selected request and messages, not changing producer readiness. */
+export function describeWorkflowDraftApiBindingIntent(input) {
+    const description = describeWorkflowDraftApiCallPlanning(input);
+    const fields = {
+        instruction: description.instruction,
+        operation: description.operation,
+        requestSchema: description.requestSchema,
+        ...(description.requestMediaType === undefined
+            ? {}
+            : { requestMediaType: description.requestMediaType }),
+        messages: description.messages,
+        backgroundMessages: description.backgroundMessages,
+        includeExplanations: description.includeExplanations,
+        hasRequestInputs: description.hasRequestInputs,
+        hasPotentialPredecessors: description.hasOtherSelectedNodes ||
+            description.sources.values.length > 0,
+        sources: { values: [], exclusiveOutputs: [] },
+    };
+    return {
+        ...fields,
+        fingerprint: createHash('sha256')
+            .update(JSON.stringify({
+            planId: input.plan.id,
+            stepId: input.stepId,
+            nodeId: description.nodeId,
+            ...fields,
+        }))
+            .digest('hex'),
+    };
+}

package/dist/draft/edits/api/describe-workflow-draft-api-call-arguments.d.ts

@@ -0,0 +1,2 @@
+import type { WorkflowDraftApiCallArgumentsInput, WorkflowDraftApiCallArgumentsDescription } from '../../../types/workflow-draft-api-call-planning.js';
+export declare function describeWorkflowDraftApiCallArguments(input: WorkflowDraftApiCallArgumentsInput): WorkflowDraftApiCallArgumentsDescription;

package/dist/draft/edits/api/describe-workflow-draft-api-call-arguments.js

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+import { resolveApiCallArgumentsContext } from './resolve-api-call-arguments-context.js';
+export function describeWorkflowDraftApiCallArguments(input) {
+    const { description, contract, fingerprint } = resolveApiCallArgumentsContext(input);
+    return {
+        ...description,
+        fingerprint,
+        // Source pointers and this schema share the values root, not a metadata wrapper.
+        literalInputSchema: z.toJSONSchema(contract.valuesSchema),
+        hasLiteralInputs: contract.hasLiteralInputs,
+    };
+}

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

@@ -0,0 +1,3 @@
+import type { WorkflowDraftApiCallBindingsInput, WorkflowDraftApiCallBindingsDescription } from '../../../types/workflow-draft-api-call-planning.js';
+/** A supplied intent is authority only after re-derivation from its original proposal. */
+export declare function describeWorkflowDraftApiCallBindings(input: WorkflowDraftApiCallBindingsInput): WorkflowDraftApiCallBindingsDescription;

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

@@ -0,0 +1,36 @@
+import { createHash } from 'node:crypto';
+import { describeWorkflowDraftApiCallPlanning } from './describe-workflow-draft-api-call-planning.js';
+import { resolveWorkflowDraftApiBindingIntent } from './resolve-workflow-draft-api-binding-intent.js';
+import { jsonValuesEqual } from '../../../utils/json-values-equal.js';
+import { requestBindingSchemas } from '../../../bindings/request-binding-schema.js';
+/** A supplied intent is authority only after re-derivation from its original proposal. */
+export function describeWorkflowDraftApiCallBindings(input) {
+    const description = describeWorkflowDraftApiCallPlanning(input);
+    if (input.inputIntent === undefined)
+        return description;
+    const inputIntent = resolveWorkflowDraftApiBindingIntent({
+        ...input,
+        fingerprint: input.inputIntent.fingerprint,
+        proposal: input.inputIntent.proposal,
+    });
+    if (!jsonValuesEqual(inputIntent, input.inputIntent))
+        throw new Error('API binding inputIntent differs from its original validated proposal');
+    return {
+        ...description,
+        fingerprint: createHash('sha256')
+            .update(JSON.stringify({
+            planning: description.fingerprint,
+            inputIntent,
+        }))
+            .digest('hex'),
+        inputIntent,
+        bindingTargets: inputIntent.targets.map((targetPointer) => ({
+            targetPointer,
+            schemas: requestBindingSchemas({
+                callId: description.nodeId,
+                operation: description.operation,
+                requestMediaType: description.requestMediaType,
+            }, targetPointer),
+        })),
+    };
+}

package/dist/draft/edits/api/describe-workflow-draft-api-call-planning.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowDraftApiCallPlanningInput, WorkflowDraftApiCallPlanningDescription } from '../../../types/workflow-draft-api-call-planning.js';
+/** Selected original OAS only. An unresolved replacement never advertises its previous output. */
+export declare function describeWorkflowDraftApiCallPlanning(input: WorkflowDraftApiCallPlanningInput): WorkflowDraftApiCallPlanningDescription;

package/dist/draft/edits/api/describe-workflow-draft-api-call-planning.js

@@ -0,0 +1,73 @@
+import { createHash } from 'node:crypto';
+import { resolveWorkflowPlanningMessages } from '../../../planning/evidence/resolve-workflow-planning-messages.js';
+import { stageWorkflowDraftEdit } from '../stage-workflow-draft-edit.js';
+import { apiOperationKeyEquals } from '../../../openapi/catalog/api-operation-key-equals.js';
+import { listApiRequestMediaTypes } from '../../../arguments/media/list-api-request-media-types.js';
+import { createApiRequestSchema } from '../../../schemas/create-api-request-schema.js';
+import { describeWorkflowDraftReferenceSources } from '../references/describe-workflow-draft-reference-sources.js';
+import { listApiRequestInputRoots } from '../../../arguments/list-api-request-input-roots.js';
+/** Selected original OAS only. An unresolved replacement never advertises its previous output. */
+export function describeWorkflowDraftApiCallPlanning(input) {
+    const stage = stageWorkflowDraftEdit(input);
+    const step = input.plan.steps.find((step) => step.id === input.stepId);
+    if (!step ||
+        (step.decision.kind !== 'add-api-call' &&
+            step.decision.kind !== 'replace-api-operation'))
+        throw new Error('API call planning stepId must identify an add-api-call or replace-api-operation decision');
+    if (!stage.pendingResolutionStepIds.includes(step.id))
+        throw new Error('API call planning already has an explicit result; remove it before replanning');
+    const nodeId = step.decision.kind === 'add-api-call'
+        ? step.newNodeId
+        : step.decision.nodeId;
+    if (typeof nodeId !== 'string' || !nodeId.trim())
+        throw new Error('API call planning requires its code-allocated or existing instance identity');
+    if (stage.content.requirements.some((item) => item.state !== 'confirmed' &&
+        (item.scope.kind === 'workflow' || item.scope.nodeIds.includes(nodeId))))
+        throw new Error(`API call planning ${nodeId} is blocked by an unresolved requirement`);
+    const selectedOperation = step.decision.operation;
+    const matches = input.context.operations.filter((operation) => apiOperationKeyEquals(operation.key, selectedOperation));
+    if (matches.length !== 1)
+        throw new Error(`API call planning ${nodeId} requires exactly one selected original OAS contract and snapshot`);
+    const operation = structuredClone(matches[0]);
+    const mediaTypes = listApiRequestMediaTypes(operation);
+    const requestMediaType = input.requestMediaType === undefined && mediaTypes.length === 1
+        ? mediaTypes[0]
+        : input.requestMediaType;
+    // The existing OAS boundary rejects absent multi-media choices and unsupported supplied media.
+    const requestSchema = createApiRequestSchema({ operation, requestMediaType });
+    const sources = describeWorkflowDraftReferenceSources({
+        stage,
+        context: input.context,
+        excludedNodeIds: [nodeId],
+    });
+    const previousCall = step.decision.kind === 'replace-api-operation'
+        ? structuredClone(input.draft.apiCalls.find((call) => call.id === nodeId))
+        : undefined;
+    const fields = {
+        stage,
+        kind: step.decision.kind,
+        nodeId,
+        operation,
+        ...(previousCall === undefined ? {} : { previousCall }),
+        instruction: step.decision.instruction,
+        ...(requestMediaType === undefined ? {} : { requestMediaType }),
+        requestSchema,
+        requestInputRoots: listApiRequestInputRoots(requestSchema),
+        hasRequestInputs: Object.keys(requestSchema.properties).length > 0,
+        hasOtherSelectedNodes: [
+            ...stage.content.apiCalls.map((call) => call.id),
+            ...stage.content.nativeNodes.map((node) => node.id),
+            ...input.plan.steps.flatMap((selected) => selected.newNodeId === undefined ? [] : [selected.newNodeId]),
+        ].some((id) => id !== nodeId),
+        sources,
+        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,
+    };
+    return {
+        fingerprint: createHash('sha256')
+            .update(JSON.stringify(fields))
+            .digest('hex'),
+        ...fields,
+    };
+}

package/dist/draft/edits/api/resolve-api-call-arguments-context.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowDraftApiCallArgumentsInput } from '../../../types/workflow-draft-api-call-planning.js';
+import type { WorkflowDraftApiCallArgumentsContext } from '../../../types/workflow-draft-api-call-planning-internal.js';
+export declare function resolveApiCallArgumentsContext(input: WorkflowDraftApiCallArgumentsInput): WorkflowDraftApiCallArgumentsContext;

package/dist/draft/edits/api/resolve-api-call-arguments-context.js

@@ -0,0 +1,46 @@
+import { createHash } from 'node:crypto';
+import { describeWorkflowDraftApiCallPlanning } from './describe-workflow-draft-api-call-planning.js';
+import { resolveWorkflowDraftApiCallBindings } from './resolve-workflow-draft-api-call-bindings.js';
+import { createApiArgumentGenerationContract } from '../../../schemas/create-api-argument-generation-contract.js';
+import { jsonValuesEqual } from '../../../utils/json-values-equal.js';
+export function resolveApiCallArgumentsContext(input) {
+    if (input.allowRuntimeInputs !== undefined &&
+        typeof input.allowRuntimeInputs !== 'boolean')
+        throw new Error('API call arguments allowRuntimeInputs must be a boolean');
+    if (input.trackRequestedInputs !== undefined &&
+        typeof input.trackRequestedInputs !== 'boolean')
+        throw new Error('API call arguments trackRequestedInputs must be a boolean');
+    if (!input.bindingPlan || input.bindingPlan.status !== 'ready')
+        throw new Error('API call arguments require a ready bindingPlan');
+    const description = describeWorkflowDraftApiCallPlanning(input);
+    const bindingPlan = resolveWorkflowDraftApiCallBindings({
+        ...input,
+        fingerprint: input.bindingPlan.fingerprint,
+        proposal: input.bindingPlan.proposal,
+        ...(input.bindingPlan.inputIntent === undefined
+            ? {}
+            : { inputIntent: input.bindingPlan.inputIntent }),
+        ...(input.bindingPlan.answers === undefined
+            ? {}
+            : { answers: input.bindingPlan.answers }),
+    });
+    if (!jsonValuesEqual(bindingPlan, input.bindingPlan))
+        throw new Error('API call arguments bindingPlan must match its actual validated proposal and current contracts');
+    const contract = createApiArgumentGenerationContract({
+        callId: description.nodeId,
+        operation: description.operation,
+        requestMediaType: description.requestMediaType,
+        bindings: input.bindingPlan.bindings,
+        confirmedInputs: input.confirmedInputs,
+    });
+    const fingerprint = createHash('sha256')
+        .update(JSON.stringify({
+        description,
+        bindingPlan,
+        confirmedInputs: input.confirmedInputs,
+        allowRuntimeInputs: input.allowRuntimeInputs === true,
+        trackRequestedInputs: input.trackRequestedInputs === true,
+    }))
+        .digest('hex');
+    return { description, contract, fingerprint };
+}

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

@@ -0,0 +1,2 @@
+import type { ResolveWorkflowDraftApiBindingIntentInput, WorkflowDraftApiBindingIntent } from '../../../types/workflow-draft-api-binding-intent.js';
+export declare function resolveWorkflowDraftApiBindingIntent(input: ResolveWorkflowDraftApiBindingIntentInput): WorkflowDraftApiBindingIntent;

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

@@ -0,0 +1,37 @@
+import { describeWorkflowDraftApiBindingIntent } from './describe-workflow-draft-api-binding-intent.js';
+import { createWorkflowDraftApiBindingIntentSchema } from '../../../schemas/workflow-draft-api-binding-intent-schema.js';
+import { requestBindingSchemas } from '../../../bindings/request-binding-schema.js';
+import { resolveWorkflowDraftSourceEvidence } from '../references/resolve-workflow-draft-source-evidence.js';
+import { jsonValuesEqual } from '../../../utils/json-values-equal.js';
+export function resolveWorkflowDraftApiBindingIntent(input) {
+    const description = describeWorkflowDraftApiBindingIntent(input);
+    if (input.fingerprint !== description.fingerprint)
+        throw new Error('API binding intent fingerprint is stale or describes a different request, operation or media contract');
+    const proposal = createWorkflowDraftApiBindingIntentSchema(input).parse(input.proposal);
+    if (!jsonValuesEqual(proposal, input.proposal))
+        throw new Error('API binding intent must validate without defaults, coercion or transformation');
+    const targets = [];
+    for (const pointer of proposal.targets) {
+        if (targets.some((target) => target === pointer ||
+            target.startsWith(pointer + '/') ||
+            pointer.startsWith(target + '/')))
+            throw new Error(`API binding intent repeats or overlaps a target: ${pointer}`);
+        if (!requestBindingSchemas({
+            callId: input.stepId,
+            operation: description.operation,
+            requestMediaType: input.requestMediaType,
+        }, pointer).length)
+            throw new Error(`API binding intent target ${pointer} is not permitted by the selected OAS request`);
+        targets.push(pointer);
+    }
+    return {
+        fingerprint: description.fingerprint,
+        proposal,
+        targets,
+        ...resolveWorkflowDraftSourceEvidence({
+            description,
+            decision: proposal,
+            capabilities: [],
+        }),
+    };
+}

package/dist/draft/edits/api/resolve-workflow-draft-api-call-arguments.d.ts

@@ -0,0 +1,3 @@
+import type { ResolveWorkflowDraftApiCallArgumentsInput, WorkflowDraftApiCallArgumentsResult } from '../../../types/workflow-draft-api-call-planning.js';
+/** Resolve one actual request; partial values become typed questions/slots, never dummy data. */
+export declare function resolveWorkflowDraftApiCallArguments(input: ResolveWorkflowDraftApiCallArgumentsInput): WorkflowDraftApiCallArgumentsResult;