@openapi-flow/langchain 0.2.0 → 0.3.1

package/dist/types/workflow-draft-api-input-edit.js

@@ -0,0 +1 @@
+export {};

package/dist/types/workflow-draft-clarification.d.ts

@@ -0,0 +1,9 @@
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import type { WorkflowDraftClarificationScopeInput } from '@openapi-flow/core';
+export interface PlanWorkflowDraftClarificationScopesInput extends WorkflowDraftClarificationScopeInput {
+    model: BaseChatModel;
+}
+export interface WorkflowDraftClarificationScopePlanningFailure {
+    stage: 'scope-schema' | 'scope-resolution';
+    output: unknown;
+}

package/dist/types/workflow-draft-clarification.js

@@ -0,0 +1 @@
+export {};

package/dist/types/workflow-draft-connection-edit.d.ts

@@ -0,0 +1,9 @@
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import type { WorkflowDraftConnectionEditInput } from '@openapi-flow/core';
+export interface PlanWorkflowDraftConnectionEditInput extends WorkflowDraftConnectionEditInput {
+    model: BaseChatModel;
+}
+export interface WorkflowDraftConnectionEditPlanningFailure {
+    stage: 'proposal-schema' | 'proposal-validation';
+    output: unknown;
+}

package/dist/types/workflow-draft-connection-edit.js

@@ -0,0 +1 @@
+export {};

package/dist/types/workflow-draft-edit.d.ts

@@ -0,0 +1,16 @@
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import type { WorkflowDraftEditInput, WorkflowDraftEditOptions, WorkflowDraftEditProposal, ApiOperationContract } from '@openapi-flow/core';
+import type { ProposedWorkflowPlanningEvidence } from './workflow-clarification.js';
+export interface AnalyzeWorkflowDraftEditInput extends WorkflowDraftEditInput {
+    options?: WorkflowDraftEditOptions;
+    model: BaseChatModel;
+}
+export type WorkflowDraftEditModelOutput = WorkflowDraftEditProposal<string, ProposedWorkflowPlanningEvidence>;
+export interface WorkflowDraftEditOperationCandidate {
+    candidateId: string;
+    operation: ApiOperationContract;
+}
+export interface WorkflowDraftEditPlanningFailure {
+    stage: 'proposal-schema' | 'proposal-validation';
+    proposal: unknown;
+}

package/dist/types/workflow-draft-edit.js

@@ -0,0 +1 @@
+export {};

package/dist/types/workflow-draft-native-node-addition.d.ts

@@ -0,0 +1,18 @@
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import type { WorkflowDraftNativeNodeAdditionInput, WorkflowDraftNativeDependenciesInput } from '@openapi-flow/core';
+export interface PlanWorkflowDraftNativeDependenciesInput extends WorkflowDraftNativeDependenciesInput {
+    /** Required only when the original plan offers a producer choice. */
+    model?: BaseChatModel;
+}
+export interface GenerateWorkflowDraftNativeNodeAdditionInput extends WorkflowDraftNativeNodeAdditionInput {
+    /** Not required when the implementation proves the sole valid setting is {}. */
+    model?: BaseChatModel;
+}
+export interface SelectWorkflowDraftNativeNodeParameterOwnershipInput extends WorkflowDraftNativeNodeAdditionInput {
+    /** No model is needed when policy or the implementation permits only literals. */
+    model?: BaseChatModel;
+}
+export interface WorkflowDraftNativeNodeAdditionPlanningFailure {
+    stage: 'proposal-schema' | 'node-validation' | 'ownership' | 'producer-dependencies';
+    output: unknown;
+}

package/dist/types/workflow-draft-native-node-addition.js

@@ -0,0 +1 @@
+export {};

package/dist/types/workflow-draft-native-parameter-edit.d.ts

@@ -0,0 +1,13 @@
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import type { WorkflowDraftNativeParameterEditInput, WorkflowDraftNativeParameterEditContractInput } from '@openapi-flow/core';
+export interface SelectWorkflowDraftNativeParameterEditTargetsInput extends WorkflowDraftNativeParameterEditInput {
+    model: BaseChatModel;
+}
+export interface GenerateWorkflowDraftNativeParameterEditsInput extends WorkflowDraftNativeParameterEditContractInput {
+    /** Required only when selected set targets contain actual values to generate. */
+    model?: BaseChatModel;
+}
+export interface WorkflowDraftNativeParameterEditPlanningFailure {
+    stage: 'targets' | 'values';
+    output: unknown;
+}

package/dist/types/workflow-draft-native-parameter-edit.js

@@ -0,0 +1 @@
+export {};

package/dist/types/workflow-draft-native-reference-repair.d.ts

@@ -0,0 +1,9 @@
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import type { WorkflowDraftNativeReferenceRepairInput } from '@openapi-flow/core';
+export interface PlanWorkflowDraftNativeReferenceRepairInput extends WorkflowDraftNativeReferenceRepairInput {
+    model: BaseChatModel;
+}
+export interface WorkflowDraftNativeReferenceRepairPlanningFailure {
+    stage: 'proposal-schema' | 'proposal-validation';
+    output: unknown;
+}

package/dist/types/workflow-draft-native-reference-repair.js

@@ -0,0 +1 @@
+export {};

package/dist/types/workflow-message-evidence-selection.d.ts

@@ -0,0 +1,6 @@
+import type { WorkflowMessageEvidence } from '@openapi-flow/core';
+/** Model input contains identities; the parsed result contains code-owned exact source text. */
+export type WorkflowMessageEvidenceSelection = Pick<WorkflowMessageEvidence, 'kind' | 'messageId'>;
+export type WorkflowMessageSelectionOutput<Output> = Output extends WorkflowMessageEvidence ? WorkflowMessageEvidenceSelection : Output extends Array<infer Item> ? WorkflowMessageSelectionOutput<Item>[] : Output extends object ? {
+    [Key in keyof Output]: WorkflowMessageSelectionOutput<Output[Key]>;
+} : Output;

package/dist/types/workflow-message-evidence-selection.js

@@ -0,0 +1 @@
+export {};

package/dist/types/workflow-orchestration.d.ts

@@ -1,23 +1,21 @@
 import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
-import type { ReviewableWorkflowApiMaterial, PlannedNativeNode, WorkflowCapability, WorkflowPlanEdge, WorkflowReviewGap, WorkflowPlanNodeContract } from '@openapi-flow/core';
-export interface PlanWorkflowConnectionsInput {
-    scenario: string;
+import type { PlannedNativeNode, WorkflowConnectionPlanningInput, WorkflowConnectionDecision, WorkflowConnectionProposal, ExplainedWorkflowBlockedCall, ExplainedWorkflowConnection } from '@openapi-flow/core';
+import type { ReviewableWorkflowGraphOutput } from './reviewable-workflow-planning.js';
+export interface PlanWorkflowConnectionsInput extends WorkflowConnectionPlanningInput {
     model: BaseChatModel;
-    materials?: ReviewableWorkflowApiMaterial[];
-    capabilities?: WorkflowCapability[];
-    nativeNodes?: PlannedNativeNode[];
-    gaps?: WorkflowReviewGap[];
-    edges?: WorkflowPlanEdge[];
+    includeExplanations?: boolean;
 }
 export interface OrchestrateWorkflowInput extends Omit<PlanWorkflowConnectionsInput, 'nativeNodes'> {
     workflowId: string;
     preparedNativeNodes?: PlannedNativeNode[];
 }
-export interface WorkflowConnectionMaterials {
-    materials: ReviewableWorkflowApiMaterial[];
-    capabilities: WorkflowCapability[];
-    nativeNodes: PlannedNativeNode[];
-    gaps: WorkflowReviewGap[];
-    edges: WorkflowPlanEdge[];
-    contracts: WorkflowPlanNodeContract[];
+export interface WorkflowConnectionModelDecision extends ReviewableWorkflowGraphOutput {
+    reason: string;
+    edges: ExplainedWorkflowConnection[];
+    blockedCalls?: ExplainedWorkflowBlockedCall[];
+}
+export type WorkflowConnectionPlanningOutput = ReviewableWorkflowGraphOutput | WorkflowConnectionModelDecision;
+export interface ResolvedWorkflowConnectionOutput {
+    proposal: WorkflowConnectionProposal;
+    decision?: WorkflowConnectionDecision;
 }

package/dist/types/workflow-planning.d.ts

@@ -1,23 +1,35 @@
 import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
-import type { WorkflowApiMaterial, WorkflowCapability, WorkflowGraphProposal, PlannedNativeNode } from '@openapi-flow/core';
+import type { WorkflowApiMaterial, WorkflowCapability, WorkflowGraphProposal, PlannedNativeNode, ExplainedWorkflowConnection, WorkflowGraphPlanningProposal, WorkflowGraphPlanningAssessment } from '@openapi-flow/core';
 export interface PlanWorkflowGraphInput {
     scenario: string;
     model: BaseChatModel;
     materials: WorkflowApiMaterial[];
     capabilities: WorkflowCapability[];
     preparedNativeNodes?: PlannedNativeNode[];
+    includeExplanations?: boolean;
 }
-export interface PreparedNativeNodeMaterial extends PlannedNativeNode {
-    inputPorts: string[];
-    outputPorts: string[];
-}
+export type { PreparedNativeNodeMaterial } from '@openapi-flow/core';
 export type WorkflowGraphOutput = Omit<WorkflowGraphProposal, 'nativeNodes'> & {
-    additionalNativeNodes: PlannedNativeNode[];
+    additionalNativeNodes?: PlannedNativeNode[];
 };
+export interface ExplainedGraphNativeNode extends PlannedNativeNode {
+    reason: string;
+}
+export interface ExplainedWorkflowGraphOutput extends WorkflowGraphOutput {
+    reason: string;
+    additionalNativeNodes?: ExplainedGraphNativeNode[];
+    edges: ExplainedWorkflowConnection[];
+}
+export type WorkflowGraphModelOutput = WorkflowGraphOutput | ExplainedWorkflowGraphOutput;
+export interface ResolvedWorkflowGraphOutput {
+    proposal: WorkflowGraphPlanningProposal;
+    assessment?: WorkflowGraphPlanningAssessment;
+}
+export type WorkflowGraphExplanationMode = 'none' | 'connections' | 'graph';
 export type WorkflowGraphPlanningFailure = {
     stage: 'proposal-schema';
     output: unknown;
 } | {
     stage: 'graph-validation';
-    output: WorkflowGraphOutput;
+    output: WorkflowGraphModelOutput;
 };

package/dist/types/workflow-review-suggestions.d.ts

@@ -0,0 +1,12 @@
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import type { WorkflowReviewSuggestionsInput, WorkflowReviewSuggestionsProposal, WorkflowReviewQuestionEvidence } from '@openapi-flow/core';
+import type { ProposedWorkflowPlanningEvidence } from './workflow-clarification.js';
+export interface SuggestWorkflowReviewFollowUpsInput extends WorkflowReviewSuggestionsInput {
+    model: BaseChatModel;
+}
+export type ProposedWorkflowReviewSuggestionEvidence = ProposedWorkflowPlanningEvidence | WorkflowReviewQuestionEvidence;
+export type WorkflowReviewSuggestionsModelOutput = WorkflowReviewSuggestionsProposal<ProposedWorkflowReviewSuggestionEvidence>;
+export interface WorkflowReviewSuggestionPlanningFailure {
+    stage: 'proposal-schema' | 'source-validation';
+    output: unknown;
+}

package/dist/types/workflow-review-suggestions.js

@@ -0,0 +1 @@
+export {};

package/dist/workflow/generate-native-node-parameters.d.ts

@@ -0,0 +1,4 @@
+import type { NativeNodeParameterResult } from '@openapi-flow/core';
+import type { GenerateNativeNodeParametersInput } from '../types/native-node-planning.js';
+/** Zero or one value call for one selected instance; no hidden ownership or connection planning. */
+export declare function generateNativeNodeParameters(input: GenerateNativeNodeParametersInput): Promise<NativeNodeParameterResult>;

package/dist/workflow/generate-native-node-parameters.js

@@ -0,0 +1,87 @@
+import { HumanMessage, SystemMessage } from '@langchain/core/messages';
+import { createNativeNodeParametersSchema, describeNativeNodeConfiguration, resolveNativeNodeParameters, } from '@openapi-flow/core';
+import { serializeStructuredOutputSchema } from '../schemas/serialize-structured-output-schema.js';
+import { nativeNodeParametersPrompt } from '../prompts/native-node-planning-prompt.js';
+import { NativeNodePlanningError } from './native-node-planning-error.js';
+/** Zero or one value call for one selected instance; no hidden ownership or connection planning. */
+export async function generateNativeNodeParameters(input) {
+    if (input.model !== undefined &&
+        (!input.model || typeof input.model.withStructuredOutput !== 'function'))
+        throw new Error('generateNativeNodeParameters.model must support structured output when supplied');
+    const description = describeNativeNodeConfiguration(input);
+    if (!description.instance.hasLiteralParameters)
+        return resolveNativeNodeParameters({
+            ...input,
+            fingerprint: description.fingerprint,
+            proposal: {
+                decision: {
+                    status: 'provided',
+                    parameters: {},
+                    ...(input.includeExplanations
+                        ? {
+                            reason: 'The validated ownership contract leaves no literal parameter choice.',
+                        }
+                        : {}),
+                },
+            },
+        });
+    if (!input.model || typeof input.model.withStructuredOutput !== 'function')
+        throw new Error('generateNativeNodeParameters.model must support structured output for remaining values');
+    const schema = createNativeNodeParametersSchema(input);
+    const capability = description.context.capabilities.find((entry) => entry.name === description.instance.capability);
+    if (!capability)
+        throw new Error('Native parameter generation has no selected capability material');
+    const output = await input.model
+        .withStructuredOutput(serializeStructuredOutputSchema(schema, 'draft-2020-12'), {
+        name: 'generate_native_node_parameters',
+        method: 'jsonSchema',
+        strict: true,
+    })
+        .invoke([
+        new SystemMessage(nativeNodeParametersPrompt),
+        new HumanMessage(JSON.stringify({
+            scenario: description.context.scenario,
+            purpose: description.instance.purpose,
+            target: {
+                id: description.instance.id,
+                capability: {
+                    name: capability.name,
+                    description: capability.description,
+                },
+            },
+            parametersSchema: description.instance.literalParametersSchema,
+            runtimeParameters: description.instance.runtimeParameters,
+            apiMaterials: description.context.apiMaterials,
+            preparedNativeNodes: description.context.preparedNativeNodes,
+            configuredNodes: description.configuredNodes,
+            outputs: description.outputs,
+            ...(description.sourceDependencies === undefined
+                ? {}
+                : { sourceDependencies: description.sourceDependencies }),
+            ...(description.replies === undefined
+                ? {}
+                : { replies: description.replies }),
+        })),
+    ]);
+    try {
+        // Validate output separately so callers can distinguish a malformed reply from stale source material.
+        schema.parse(output);
+    }
+    catch (cause) {
+        if (!(cause instanceof Error))
+            throw cause;
+        throw new NativeNodePlanningError({ stage: 'parameter-schema', output }, cause);
+    }
+    try {
+        return resolveNativeNodeParameters({
+            ...input,
+            fingerprint: description.fingerprint,
+            proposal: output,
+        });
+    }
+    catch (cause) {
+        if (!(cause instanceof Error))
+            throw cause;
+        throw new NativeNodePlanningError({ stage: 'parameter-validation', output }, cause);
+    }
+}

package/dist/workflow/orchestrate-workflow.js

@@ -1,7 +1,7 @@
 import { planNativeNodes } from './plan-native-nodes.js';
 import { planWorkflowConnections } from './plan-workflow-connections.js';
-import { assembleNativeNodeMaterials } from './assemble-native-node-materials.js';
-import { prepareWorkflowConnectionMaterials } from './prepare-workflow-connection-materials.js';
+import { assembleNativeNodeMaterials } from '@openapi-flow/core';
+import { prepareWorkflowConnectionMaterials } from '@openapi-flow/core';
 /** Optional material groups mean absence, never an implicit capability registry. */
 export async function orchestrateWorkflow(input) {
     if (!input.workflowId?.trim())

package/dist/workflow/plan-native-instance-dependencies.d.ts

@@ -0,0 +1,4 @@
+import type { NativeInstanceDependencyPlan } from '@openapi-flow/core';
+import type { PlanNativeInstanceDependenciesInput } from '../types/native-node-planning.js';
+/** Zero or one producer-choice call; no parameters, output contracts or runtime DAG edges. */
+export declare function planNativeInstanceDependencies(input: PlanNativeInstanceDependenciesInput): Promise<NativeInstanceDependencyPlan>;

package/dist/workflow/plan-native-instance-dependencies.js

@@ -0,0 +1,45 @@
+import { HumanMessage, SystemMessage } from '@langchain/core/messages';
+import { isDeepStrictEqual } from 'node:util';
+import { describeNativeInstanceDependencies, createNativeInstanceDependenciesSchema, resolveNativeInstanceDependencies, } from '@openapi-flow/core';
+import { nativeInstanceDependenciesPrompt } from '../prompts/native-instance-dependencies-prompt.js';
+import { serializeStructuredOutputSchema } from '../schemas/serialize-structured-output-schema.js';
+import { NativeNodePlanningError } from './native-node-planning-error.js';
+/** Zero or one producer-choice call; no parameters, output contracts or runtime DAG edges. */
+export async function planNativeInstanceDependencies(input) {
+    if (input.model !== undefined &&
+        (!input.model || typeof input.model.withStructuredOutput !== 'function'))
+        throw new Error('planNativeInstanceDependencies.model must support structured output when supplied');
+    const context = describeNativeInstanceDependencies(input);
+    const explanations = input.includeExplanations;
+    if (Object.values(context.sourceCandidatesByNodeId).every((ids) => ids.length === 0))
+        return resolveNativeInstanceDependencies({
+            ...input,
+            proposal: {
+                sourcesByNodeId: Object.fromEntries(context.instances.map((node) => [node.id, { sourceNodeIds: [] }])),
+            },
+        });
+    if (!input.model || typeof input.model.withStructuredOutput !== 'function')
+        throw new Error('planNativeInstanceDependencies.model must support structured output for producer choices');
+    const schema = createNativeInstanceDependenciesSchema(input);
+    const output = await input.model
+        .withStructuredOutput(serializeStructuredOutputSchema(schema, 'draft-2020-12'), {
+        name: 'plan_native_instance_dependencies',
+        method: 'jsonSchema',
+        strict: true,
+    })
+        .invoke([
+        new SystemMessage(nativeInstanceDependenciesPrompt),
+        new HumanMessage(JSON.stringify(context)),
+    ]);
+    try {
+        if (!isDeepStrictEqual(describeNativeInstanceDependencies(input), context) ||
+            explanations !== input.includeExplanations)
+            throw new Error('Native dependency source contracts changed during planning; no automatic rebase');
+        return resolveNativeInstanceDependencies({ ...input, proposal: output });
+    }
+    catch (cause) {
+        if (!(cause instanceof Error))
+            throw cause;
+        throw new NativeNodePlanningError({ stage: 'dependency-plan', output }, cause);
+    }
+}

package/dist/workflow/plan-native-nodes.js

@@ -1,70 +1,64 @@
 import { HumanMessage, SystemMessage } from '@langchain/core/messages';
 import { isDeepStrictEqual } from 'node:util';
-import { z } from 'zod';
-import { createNativeOutputContracts, createWorkflowPlanningCapabilities, validateNativeApiResponseReferences, } from '@openapi-flow/core';
-import { createNativeNodePlanSchema } from '../schemas/native-node-plan-schema.js';
+import { describeNativeNodePlanning, createNativeNodePlan, createNativeNodePlanningRecord, } from '@openapi-flow/core';
+import { createNativeNodePlanningContract } from '../schemas/native-node-planning-contract.js';
+import { nativeNodeExplanationOptionsSchema } from '../schemas/native-node-explanation-schema.js';
 import { nativeNodePlanningPrompt } from '../prompts/native-node-planning-prompt.js';
 import { assertSelectionInput } from '../legacy/planning/select-operation.js';
 import { parseStructuredOutput } from '../legacy/planning/parse-structured-output.js';
-import { createPreparedNativeNodeMaterials } from './create-prepared-native-node-materials.js';
-import { assembleNativeNodeMaterials } from './assemble-native-node-materials.js';
+import { resolveNativeNodePlanningOutput } from './resolve-native-node-planning-output.js';
+import { serializeStructuredOutputSchema } from '../schemas/serialize-structured-output-schema.js';
 import { NativeNodePlanningError } from './native-node-planning-error.js';
 export async function planNativeNodes(input) {
-    assertSelectionInput(input.scenario, input.model);
     if (!input.planId?.trim())
         throw new Error('planNativeNodes.planId is required');
-    const capabilities = input.capabilities ?? [];
-    const apiMaterials = input.apiMaterials ?? [];
-    const prepared = input.preparedNativeNodes ?? [];
-    createNativeOutputContracts({ nativeNodes: prepared, capabilities });
-    const apiIds = apiMaterials.map((material) => material.callId);
-    const existingIds = [...apiIds, ...prepared.map((node) => node.id)];
-    if (existingIds.some((id) => !id.trim()) ||
-        new Set(existingIds).size !== existingIds.length)
-        throw new Error('native planning materials require unique non-empty IDs');
-    validateNativeApiResponseReferences({
-        nativeNodes: prepared,
-        capabilities,
-        apiCallIds: apiIds,
+    if (input.model !== undefined &&
+        (!input.model || typeof input.model.withStructuredOutput !== 'function'))
+        throw new Error('planNativeNodes.model must support structured output when supplied');
+    const options = nativeNodeExplanationOptionsSchema.parse({
+        includeExplanations: input.includeExplanations,
     });
+    const { input: snapshot, context, planningCapabilities, } = describeNativeNodePlanning(input);
     // No registered choice means no native-selection model call, not an inferred registry.
-    if (!capabilities.length)
-        return { nativeNodes: [], gaps: [] };
-    const planningCapabilities = createWorkflowPlanningCapabilities({
-        capabilities,
-        apiCallIds: apiIds,
-    });
-    const schema = createNativeNodePlanSchema(planningCapabilities);
-    const output = await input.model
-        .withStructuredOutput(z.toJSONSchema(schema), {
+    if (!snapshot.capabilities.length) {
+        const plan = createNativeNodePlan({
+            ...snapshot,
+            proposal: { nativeNodes: [], gaps: [] },
+        });
+        return {
+            ...plan,
+            ...(options.includeExplanations === true
+                ? {
+                    nativePlanning: createNativeNodePlanningRecord({
+                        ...snapshot,
+                        plan,
+                    }),
+                }
+                : {}),
+        };
+    }
+    const model = input.model;
+    if (!model)
+        throw new Error('planNativeNodes.model is required when supplied capabilities need a planning decision');
+    assertSelectionInput(snapshot.scenario, model);
+    const contract = createNativeNodePlanningContract(planningCapabilities, snapshot.allowRuntimeParameters === true, options.includeExplanations === true);
+    if (!isDeepStrictEqual(contract.capabilities, context.capabilities))
+        throw new Error('native planning schema differs from its supplied capability material');
+    const { schema } = contract;
+    const output = await model
+        .withStructuredOutput(serializeStructuredOutputSchema(schema, 'draft-2020-12'), {
         name: 'plan_native_nodes',
         method: 'functionCalling',
         strict: true,
     })
         .invoke([
         new SystemMessage(nativeNodePlanningPrompt),
-        new HumanMessage(JSON.stringify({
-            scenario: input.scenario,
-            apiMaterials: apiMaterials.map(({ callId, operation }) => ({
-                callId,
-                key: operation.key,
-                method: operation.method,
-                path: operation.path,
-                operation: operation.operation,
-                effective: operation.effective,
-            })),
-            preparedNativeNodes: createPreparedNativeNodeMaterials(prepared, capabilities),
-            capabilities: planningCapabilities.map((capability) => ({
-                name: capability.name,
-                description: capability.description,
-                parametersSchema: z.toJSONSchema(capability.parametersSchema),
-            })),
-        })),
+        new HumanMessage(JSON.stringify(context)),
     ]);
-    let proposal;
+    let parsed;
     try {
-        proposal = parseStructuredOutput(schema, output, 'model native node plan');
-        if (!isDeepStrictEqual(proposal, output))
+        parsed = parseStructuredOutput(schema, output, 'model native node plan');
+        if (!isDeepStrictEqual(parsed, output))
             throw new Error('native model schema must validate without defaults, coercion or transformation');
     }
     catch (error) {
@@ -72,28 +66,31 @@ export async function planNativeNodes(input) {
             throw error;
         throw new NativeNodePlanningError({ stage: 'proposal-schema', output }, error);
     }
+    const { proposal, assessment } = resolveNativeNodePlanningOutput(parsed);
     try {
-        const nodes = assembleNativeNodeMaterials(prepared, proposal.nativeNodes);
-        if (proposal.nativeNodes.some((node) => apiIds.includes(node.id)))
-            throw new Error('native node plan contains an API callId');
-        createNativeOutputContracts({ nativeNodes: nodes, capabilities });
-        validateNativeApiResponseReferences({
-            nativeNodes: nodes,
-            capabilities,
-            apiCallIds: apiIds,
-        });
-        const gaps = proposal.gaps.map((gap, index) => ({
-            id: `${input.planId}-gap-${index + 1}`,
-            stage: 'workflow-graph',
-            description: gap.description,
-        }));
-        if (gaps.some((gap) => [...existingIds, ...nodes.map((node) => node.id)].includes(gap.id)))
-            throw new Error('native planning gap ID collides with a declared node');
-        return { nativeNodes: proposal.nativeNodes, gaps };
+        if (!isDeepStrictEqual(describeNativeNodePlanning(snapshot).context, context))
+            throw new Error('native planning source contracts changed during the model invocation');
+        const plan = createNativeNodePlan({ ...snapshot, proposal });
+        return {
+            ...plan,
+            ...(options.includeExplanations === true
+                ? {
+                    nativePlanning: createNativeNodePlanningRecord({
+                        ...snapshot,
+                        plan,
+                        assessment,
+                    }),
+                }
+                : {}),
+        };
     }
     catch (error) {
         if (!(error instanceof Error))
             throw error;
-        throw new NativeNodePlanningError({ stage: 'node-validation', output: proposal }, error);
+        throw new NativeNodePlanningError({
+            stage: 'node-validation',
+            output: proposal,
+            sourceOutput: parsed,
+        }, error);
     }
 }