@openapi-flow/core 0.1.0 → 0.3.0

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;

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

@@ -0,0 +1,4 @@
+import { resolveNativeNodeAdditionContext } from './resolve-native-node-addition-context.js';
+export function describeWorkflowDraftNativeNodeAddition(input) {
+    return resolveNativeNodeAdditionContext(input).description;
+}

package/dist/draft/edits/native/additions/resolve-native-node-addition-context.d.ts

@@ -0,0 +1,4 @@
+import type { WorkflowDraftNativeNodeAdditionInput } from '../../../../types/workflow-draft-native-node-addition.js';
+import type { WorkflowDraftNativeNodeAdditionContext } from '../../../../types/workflow-draft-native-node-addition-internal.js';
+/** Only one already-selected addition: identities and implementation contracts are code-owned. */
+export declare function resolveNativeNodeAdditionContext(input: WorkflowDraftNativeNodeAdditionInput): WorkflowDraftNativeNodeAdditionContext;

package/dist/draft/edits/native/additions/resolve-native-node-addition-context.js

@@ -0,0 +1,58 @@
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+import { resolveNativeNodeAdditionMaterials } from './resolve-native-node-addition-materials.js';
+import { nativeMaterialSourcesFromDraftReferences } from '../../references/native-material-sources-from-draft-references.js';
+import { bindNativeMaterialContracts } from '../../../../workflow/bind-native-material-contracts.js';
+import { createWorkflowPlanningCapabilities } from '../../../../workflow/create-workflow-planning-capabilities.js';
+import { hasFixedEmptyNativeParameters } from '../../../../workflow/planning/has-fixed-empty-native-parameters.js';
+import { resolveWorkflowPlanningMessages } from '../../../../planning/evidence/resolve-workflow-planning-messages.js';
+/** Only one already-selected addition: identities and implementation contracts are code-owned. */
+export function resolveNativeNodeAdditionContext(input) {
+    const { stage, nodeId, definition, sources, instruction, missingContext, pendingSourceNodeIds, sourceDependencies, plannedNativeRoles, } = resolveNativeNodeAdditionMaterials(input);
+    if (missingContext.length || pendingSourceNodeIds.length)
+        throw new Error(`Native node addition ${nodeId} [${definition.name}] requires ${missingContext.map((entry) => `${entry.field} (at least ${entry.minimumItems}, available ${entry.availableItems})`).join(', ')}${pendingSourceNodeIds.length ? '; pending selected producers: ' + pendingSourceNodeIds.join(', ') : ''}`);
+    const capability = bindNativeMaterialContracts(definition, nativeMaterialSourcesFromDraftReferences(sources));
+    const [planning] = createWorkflowPlanningCapabilities({
+        capabilities: [capability],
+        apiCallIds: sources.values
+            .filter((source) => source.kind === 'api')
+            .map((source) => source.nodeId),
+    });
+    const parametersSchema = JSON.parse(JSON.stringify(z.toJSONSchema(planning.parametersSchema, {
+        io: 'input',
+        target: 'draft-2020-12',
+        reused: 'inline',
+        cycles: 'ref',
+    })));
+    const fields = {
+        stage,
+        nodeId,
+        capability: {
+            name: capability.name,
+            description: capability.description,
+            supportsRuntimeParameters: capability.supportsRuntimeParameters === true,
+        },
+        instruction,
+        parametersSchema,
+        parameterMode: hasFixedEmptyNativeParameters(parametersSchema, capability)
+            ? 'fixed-empty'
+            : 'values',
+        sources,
+        ...(sourceDependencies === undefined ? {} : { sourceDependencies }),
+        ...(plannedNativeRoles === undefined ? {} : { plannedNativeRoles }),
+        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,
+        allowRuntimeParameters: input.allowRuntimeParameters === true,
+    };
+    return {
+        capability,
+        parametersSchema: planning.parametersSchema,
+        description: {
+            fingerprint: createHash('sha256')
+                .update(JSON.stringify(fields))
+                .digest('hex'),
+            ...fields,
+        },
+    };
+}

package/dist/draft/edits/native/additions/resolve-native-node-addition-materials.d.ts

@@ -0,0 +1,4 @@
+import type { WorkflowDraftNativeNodeAdditionInput } from '../../../../types/workflow-draft-native-node-addition.js';
+import type { WorkflowDraftNativeAdditionMaterials } from '../../../../types/workflow-draft-native-node-addition-internal.js';
+/** Validate the selected unfinished instance before deciding whether its original sources exist. */
+export declare function resolveNativeNodeAdditionMaterials(input: WorkflowDraftNativeNodeAdditionInput): WorkflowDraftNativeAdditionMaterials;

package/dist/draft/edits/native/additions/resolve-native-node-addition-materials.js

@@ -0,0 +1,78 @@
+import { nativeMaterialRequirementsSchema } from '../../../../schemas/native-material-requirements-schema.js';
+import { stageWorkflowDraftEdit } from '../../stage-workflow-draft-edit.js';
+import { describeWorkflowDraftReferenceSources } from '../../references/describe-workflow-draft-reference-sources.js';
+import { nativeMaterialSourcesFromDraftReferences } from '../../references/native-material-sources-from-draft-references.js';
+import { validateWorkflowDraftNativeDependencies } from './resolve-workflow-draft-native-dependencies.js';
+/** Validate the selected unfinished instance before deciding whether its original sources exist. */
+export function resolveNativeNodeAdditionMaterials(input) {
+    if (input.allowRuntimeParameters !== undefined &&
+        typeof input.allowRuntimeParameters !== 'boolean')
+        throw new Error('Native node addition allowRuntimeParameters must be a boolean');
+    const stage = stageWorkflowDraftEdit(input);
+    const step = input.plan.steps.find((step) => step.id === input.stepId);
+    if (!step || step.decision.kind !== 'add-native-node')
+        throw new Error('Native node addition stepId must identify an add-native-node decision');
+    if (!stage.pendingResolutionStepIds.includes(step.id))
+        throw new Error('Native node addition already has an explicit result; remove it before replanning');
+    if (typeof step.newNodeId !== 'string' || !step.newNodeId.trim())
+        throw new Error('Native node addition requires its code-allocated newNodeId');
+    const nodeId = step.newNodeId;
+    if (stage.content.requirements.some((requirement) => requirement.state !== 'confirmed' &&
+        (requirement.scope.kind === 'workflow' ||
+            requirement.scope.nodeIds.includes(nodeId))))
+        throw new Error(`Native node addition ${nodeId} is blocked by an unresolved requirement`);
+    const capabilityName = step.decision.capability;
+    const definition = input.context.capabilities.find((capability) => capability.name === capabilityName);
+    if (!definition)
+        throw new Error(`Native node addition requires registered capability ${capabilityName}`);
+    const dependencies = input.producerDependencies === undefined
+        ? undefined
+        : validateWorkflowDraftNativeDependencies({
+            ...input,
+            producerDependencies: input.producerDependencies,
+        });
+    const sourceIds = dependencies?.proposal.sourcesByNodeId[nodeId].sourceNodeIds;
+    const available = describeWorkflowDraftReferenceSources({
+        stage,
+        context: input.context,
+        excludedNodeIds: [nodeId],
+    });
+    const sources = {
+        values: available.values.filter((source) => sourceIds === undefined || sourceIds.includes(source.nodeId)),
+        exclusiveOutputs: available.exclusiveOutputs.filter((source) => sourceIds === undefined || sourceIds.includes(source.nodeId)),
+    };
+    const pendingSourceNodeIds = sourceIds === undefined
+        ? []
+        : sourceIds.filter((id) => !sources.values.some((source) => source.nodeId === id) &&
+            !sources.exclusiveOutputs.some((source) => source.nodeId === id));
+    const materials = nativeMaterialSourcesFromDraftReferences(sources);
+    const requirements = definition.materialRequirements === undefined
+        ? []
+        : nativeMaterialRequirementsSchema.parse(definition.materialRequirements);
+    const missingContext = requirements.flatMap((requirement) => materials[requirement.field].length < requirement.minimumItems
+        ? [
+            {
+                ...requirement,
+                availableItems: materials[requirement.field].length,
+            },
+        ]
+        : []);
+    return {
+        stage,
+        nodeId,
+        definition,
+        sources,
+        instruction: step.decision.instruction,
+        missingContext,
+        pendingSourceNodeIds,
+        ...(dependencies === undefined
+            ? {}
+            : {
+                sourceDependencies: {
+                    planId: dependencies.id,
+                    sourceNodeIds: [...sourceIds],
+                },
+                plannedNativeRoles: structuredClone(dependencies.context.roles),
+            }),
+    };
+}

package/dist/draft/edits/native/additions/resolve-workflow-draft-native-dependencies.d.ts

@@ -0,0 +1,7 @@
+import type { WorkflowDraftNativeDependenciesInput, WorkflowDraftNativeDependencyContext, WorkflowDraftNativeDependencies, ResolveWorkflowDraftNativeDependenciesInput, ValidateWorkflowDraftNativeDependenciesInput, ValidateWorkflowDraftNativeDependencyResolutionsInput } from '../../../../types/workflow-draft-native-dependencies.js';
+/** Reconstruct the original semantic plan before any value generation. Progress never rebases this receipt. */
+export declare function describeWorkflowDraftNativeDependencies(input: WorkflowDraftNativeDependenciesInput): WorkflowDraftNativeDependencyContext;
+export declare function resolveWorkflowDraftNativeDependencies(input: ResolveWorkflowDraftNativeDependenciesInput): WorkflowDraftNativeDependencies;
+export declare function validateWorkflowDraftNativeDependencies(input: ValidateWorkflowDraftNativeDependenciesInput): WorkflowDraftNativeDependencies;
+/** Revalidate actual completed additions before final connection planning/adoption, not just the model wrapper. */
+export declare function validateWorkflowDraftNativeDependencyResolutions(input: ValidateWorkflowDraftNativeDependencyResolutionsInput): void;

package/dist/draft/edits/native/additions/resolve-workflow-draft-native-dependencies.js

@@ -0,0 +1,137 @@
+import { createHash } from 'node:crypto';
+import { stageWorkflowDraftEdit } from '../../stage-workflow-draft-edit.js';
+import { describeWorkflowDraftReferenceSources } from '../../references/describe-workflow-draft-reference-sources.js';
+import { resolveWorkflowPlanningMessages } from '../../../../planning/evidence/resolve-workflow-planning-messages.js';
+import { createWorkflowDraftNativeDependenciesSchema } from '../../../../schemas/workflow-draft-native-dependencies-schema.js';
+import { validateNativeProducerDependencyGraph } from '../../../../workflow/planning/validate-native-producer-dependency-graph.js';
+import { validateNativeNodeProducerReferences } from '../../../../workflow/planning/resolve-native-configuration-materials.js';
+import { nativeMaterialSourcesFromDraftReferences } from '../../references/native-material-sources-from-draft-references.js';
+import { bindNativeMaterialContracts } from '../../../../workflow/bind-native-material-contracts.js';
+import { jsonValuesEqual } from '../../../../utils/json-values-equal.js';
+import { requireNativeParameterReferenceSources, describePendingNativeProducer, selectNativeParameterProducers, } from '../../../../workflow/planning/select-native-parameter-producers.js';
+/** Reconstruct the original semantic plan before any value generation. Progress never rebases this receipt. */
+export function describeWorkflowDraftNativeDependencies(input) {
+    const stage = stageWorkflowDraftEdit({
+        ...input,
+        resolutions: [],
+        repairs: [],
+    });
+    const sources = describeWorkflowDraftReferenceSources({
+        stage,
+        context: input.context,
+        excludedNodeIds: [],
+    });
+    const roles = [];
+    const pendingNativeSources = [];
+    for (const step of input.plan.steps) {
+        const decision = step.decision;
+        if (decision.kind !== 'add-native-node' &&
+            decision.kind !== 'revise-native-node')
+            continue;
+        const nodeId = decision.kind === 'add-native-node' ? step.newNodeId : decision.nodeId;
+        const capability = decision.kind === 'add-native-node'
+            ? decision.capability
+            : input.draft.nativeNodes.find((node) => node.id === decision.nodeId)
+                .capability;
+        if (typeof nodeId !== 'string' || !nodeId.trim())
+            throw new Error(`Draft native dependency step ${step.id} requires its original allocated node ID`);
+        const definition = input.context.capabilities.find((entry) => entry.name === capability);
+        if (!definition)
+            throw new Error(`Draft native dependency ${nodeId} requires registered capability ${capability}`);
+        const role = {
+            nodeId,
+            stepId: step.id,
+            capability,
+            description: definition.description,
+            instruction: decision.instruction,
+            parameterReferenceSources: requireNativeParameterReferenceSources(definition),
+        };
+        if (decision.kind === 'add-native-node')
+            roles.push(role);
+        else
+            pendingNativeSources.push(role);
+    }
+    const candidates = [
+        ...stage.apiResponseSources.map((source) => ({
+            nodeId: source.nodeId,
+            referenceSources: ['response'],
+        })),
+        ...sources.values.map((source) => ({
+            nodeId: source.nodeId,
+            referenceSources: [
+                source.kind === 'api' ? 'response' : 'node-output',
+            ],
+        })),
+        ...sources.exclusiveOutputs.map((source) => ({
+            nodeId: source.nodeId,
+            referenceSources: ['exclusive-output'],
+        })),
+        ...[...pendingNativeSources, ...roles].map((role) => describePendingNativeProducer(role.nodeId, input.context.capabilities.find((entry) => entry.name === role.capability))),
+    ];
+    const messages = resolveWorkflowPlanningMessages(input.context);
+    return structuredClone({
+        plan: input.plan,
+        sources,
+        roles,
+        pendingNativeSources,
+        sourceCandidatesByNodeId: Object.fromEntries(roles.map((role) => [
+            role.nodeId,
+            selectNativeParameterProducers({
+                nodeId: role.nodeId,
+                capability: input.context.capabilities.find((entry) => entry.name === role.capability),
+                producers: candidates,
+            }),
+        ])),
+        messages: messages.filter((message) => input.requestMessageIds.includes(message.id)),
+        backgroundMessages: messages.filter((message) => !input.requestMessageIds.includes(message.id)),
+        includeExplanations: input.plan.options.includeExplanations,
+    });
+}
+export function resolveWorkflowDraftNativeDependencies(input) {
+    const context = describeWorkflowDraftNativeDependencies(input);
+    const proposal = createWorkflowDraftNativeDependenciesSchema(input).parse(input.proposal);
+    if (!jsonValuesEqual(proposal, input.proposal))
+        throw new Error('Draft native producer choices cannot be coerced, defaulted or transformed');
+    validateNativeProducerDependencyGraph(context.roles.map((role) => role.nodeId), proposal);
+    const fields = { context, proposal };
+    return {
+        id: 'draft-native-dependencies:' +
+            createHash('sha256').update(JSON.stringify(fields)).digest('hex'),
+        ...structuredClone(fields),
+    };
+}
+export function validateWorkflowDraftNativeDependencies(input) {
+    if (!input.producerDependencies?.proposal)
+        throw new Error('Draft native dependencies require their original proposal');
+    const expected = resolveWorkflowDraftNativeDependencies({
+        ...input,
+        proposal: input.producerDependencies.proposal,
+    });
+    if (!jsonValuesEqual(expected, input.producerDependencies))
+        throw new Error('Draft native dependency choices are stale or their original plan/source contracts changed');
+    return expected;
+}
+/** Revalidate actual completed additions before final connection planning/adoption, not just the model wrapper. */
+export function validateWorkflowDraftNativeDependencyResolutions(input) {
+    const dependencies = validateWorkflowDraftNativeDependencies(input);
+    const stage = stageWorkflowDraftEdit(input);
+    for (const role of dependencies.context.roles) {
+        if (stage.pendingResolutionStepIds.includes(role.stepId))
+            throw new Error(`Draft native dependency ${role.nodeId} has no completed addition resolution`);
+        const node = stage.content.nativeNodes.find((entry) => entry.id === role.nodeId);
+        if (!node)
+            throw new Error(`Draft native dependency ${role.nodeId} has no actual staged node`);
+        const ids = dependencies.proposal.sourcesByNodeId[role.nodeId].sourceNodeIds;
+        const available = describeWorkflowDraftReferenceSources({
+            stage,
+            context: input.context,
+            excludedNodeIds: [role.nodeId],
+        });
+        const sources = {
+            values: available.values.filter((source) => ids.includes(source.nodeId)),
+            exclusiveOutputs: available.exclusiveOutputs.filter((source) => ids.includes(source.nodeId)),
+        };
+        const capability = bindNativeMaterialContracts(input.context.capabilities.find((entry) => entry.name === role.capability), nativeMaterialSourcesFromDraftReferences(sources));
+        validateNativeNodeProducerReferences(node, capability, ids);
+    }
+}

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

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