@openapi-flow/core 0.1.0 → 0.3.0

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

@@ -0,0 +1,114 @@
+import type { ApiOperationContract } from './api-operation.js';
+import type { ReviewableWorkflowApiMaterial, WorkflowReviewGap, ReviewableWorkflowGraphPlan, BlockedWorkflowCall, ReadyWorkflowApiMaterial, BlockedWorkflowApiMaterial } from './reviewable-workflow.js';
+import type { WorkflowCapability, PlannedNativeNode, WorkflowPlanEdge, WorkflowPlanGap, WorkflowGraphPlan, WorkflowPlanNodeContract } from './workflow-plan.js';
+import type { PreparedNativeNodeMaterial } from './native-node-planning.js';
+import type { NativeOutputContract } from './node-output.js';
+import type { BindingSchema } from './api-bindings.js';
+import type { ExplainedWorkflowConnection, ExplainedWorkflowBlockedCall } from './workflow-connection-planning.js';
+import type { WorkflowPlanningSourceEvidence } from './workflow-planning-materials.js';
+export type WorkflowGraphPlanningMode = 'executable' | 'reviewable';
+export interface WorkflowGraphPlanningInput {
+    mode: WorkflowGraphPlanningMode;
+    scenario: string;
+    materials: ReviewableWorkflowApiMaterial[];
+    capabilities: WorkflowCapability[];
+    gaps: WorkflowReviewGap[];
+    preparedNativeNodes?: PlannedNativeNode[];
+}
+export interface WorkflowGraphPlanningSnapshot extends WorkflowGraphPlanningInput {
+    preparedNativeNodes: PlannedNativeNode[];
+}
+export type WorkflowGraphOperationMaterial = Pick<ApiOperationContract, 'key' | 'method' | 'path'> & {
+    operation: Partial<Pick<ApiOperationContract['operation'], 'summary' | 'description' | 'tags' | 'responses'>>;
+};
+export type WorkflowGraphApiMaterial = (Omit<ReadyWorkflowApiMaterial, 'operation'> | Omit<BlockedWorkflowApiMaterial, 'operation'>) & {
+    operation: WorkflowGraphOperationMaterial;
+    inputPorts: string[];
+    outputPorts: string[];
+};
+export interface WorkflowGraphGapMaterial extends WorkflowReviewGap {
+    inputPorts: string[];
+    outputPorts: string[];
+}
+export interface WorkflowGraphCapabilityMaterial {
+    name: string;
+    description: string;
+    parametersSchema: BindingSchema;
+    waitsForAllInputs: boolean;
+    exclusiveOutputPorts: boolean;
+}
+export interface WorkflowGraphPlanningContext {
+    scenario: string;
+    materials: WorkflowGraphApiMaterial[];
+    preparedNativeNodes: PreparedNativeNodeMaterial[];
+    nativeOutputs: NativeOutputContract[];
+    capabilities: WorkflowGraphCapabilityMaterial[];
+    gaps?: WorkflowGraphGapMaterial[];
+}
+export interface WorkflowGraphPlanningDescription {
+    input: WorkflowGraphPlanningSnapshot;
+    context: WorkflowGraphPlanningContext;
+    sources: WorkflowPlanningSourceEvidence;
+    planningCapabilities: WorkflowCapability[];
+}
+export interface ExecutableWorkflowGraphPlanningProposal {
+    mode: 'executable';
+    additionalNativeNodes: PlannedNativeNode[];
+    edges: WorkflowPlanEdge[];
+    gaps: WorkflowPlanGap[];
+}
+export interface ReviewableWorkflowGraphPlanningProposal {
+    mode: 'reviewable';
+    additionalNativeNodes: PlannedNativeNode[];
+    edges: WorkflowPlanEdge[];
+    additionalGaps: Pick<WorkflowReviewGap, 'id' | 'description'>[];
+    blockedCalls: BlockedWorkflowCall[];
+}
+export type WorkflowGraphPlanningProposal = ExecutableWorkflowGraphPlanningProposal | ReviewableWorkflowGraphPlanningProposal;
+export interface WorkflowGraphPlanningNodeReason {
+    nodeId: string;
+    reason: string;
+}
+export interface WorkflowGraphPlanningAssessment {
+    reason: string;
+    nodes: WorkflowGraphPlanningNodeReason[];
+    edges: ExplainedWorkflowConnection[];
+    blockedCalls: ExplainedWorkflowBlockedCall[];
+}
+export type WorkflowGraphPlanningVerification = {
+    status: 'needs-review';
+} | {
+    status: 'validated';
+    contracts: WorkflowPlanNodeContract[];
+    outputs: NativeOutputContract[];
+};
+export type ExecutableWorkflowGraphPlanningResult = Pick<WorkflowGraphPlan, 'nativeNodes' | 'edges' | 'gaps' | 'starts'>;
+export type ReviewableWorkflowGraphPlanningResult = Pick<ReviewableWorkflowGraphPlan, 'nativeNodes' | 'edges' | 'gaps' | 'blockedCalls' | 'starts'>;
+export interface WorkflowGraphPlanningRecordFields {
+    proposal: WorkflowGraphPlanningProposal;
+    assessment: WorkflowGraphPlanningAssessment;
+    evidence: {
+        kind: 'supplied-graph-materials';
+        context: WorkflowGraphPlanningContext;
+        sources: WorkflowPlanningSourceEvidence;
+    };
+    verification: WorkflowGraphPlanningVerification;
+}
+export type WorkflowGraphPlanningRecord = WorkflowGraphPlanningRecordFields & ({
+    kind: 'executable';
+    plan: ExecutableWorkflowGraphPlanningResult;
+} | {
+    kind: 'reviewable';
+    plan: ReviewableWorkflowGraphPlanningResult;
+});
+export interface CreateWorkflowGraphPlanningResultInput extends WorkflowGraphPlanningInput {
+    proposal: WorkflowGraphPlanningProposal;
+}
+export interface CreateWorkflowGraphPlanningRecordInput extends CreateWorkflowGraphPlanningResultInput {
+    plan: WorkflowGraphPlan | ReviewableWorkflowGraphPlan;
+    assessment: WorkflowGraphPlanningAssessment;
+}
+export interface ValidateWorkflowGraphPlanningRecordInput extends WorkflowGraphPlanningInput {
+    plan: WorkflowGraphPlan | ReviewableWorkflowGraphPlan;
+    record: WorkflowGraphPlanningRecord;
+}

package/dist/types/workflow-graph-planning.js

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

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

@@ -0,0 +1,132 @@
+import type { z } from 'zod';
+import type { ApiOperationContract } from './api-operation.js';
+import type { ApiCallArguments, JsonValueObject } from './api-arguments.js';
+import type { BindingSchema } from './api-bindings.js';
+import type { WorkflowCapabilityPlanningContext } from './workflow-capability-planning.js';
+import type { WorkflowNativeReferenceBinding, WorkflowNativeParameterReference } from './native-parameter-reference.js';
+import type { WorkflowGraphPlanningRecord } from './workflow-graph-planning.js';
+import type { WorkflowUnresolvedNode } from './workflow-draft-capability-gap.js';
+import type { WorkflowNativeMaterialSources, WorkflowNativeMaterialRequirement } from './native-material-snapshot.js';
+export interface WorkflowApiMaterial {
+    operation: ApiOperationContract;
+    arguments: ApiCallArguments;
+    purpose?: string;
+}
+export interface WorkflowResponseReference {
+    source: 'response';
+    nodeId: string;
+    /** RFC 6901 pointer into the API response body, not n8n's envelope. */
+    pointer: string;
+}
+export interface WorkflowNodeOutputReference {
+    source: 'node-output';
+    nodeId: string;
+    /** RFC 6901 pointer into the declared native JSON item. */
+    pointer: string;
+}
+export type WorkflowValueReference = WorkflowResponseReference | WorkflowNodeOutputReference;
+export interface WorkflowCapability {
+    name: string;
+    description: string;
+    parametersSchema: z.ZodType<JsonValueObject>;
+    /** Supported parameter-reference kinds, not execution predecessors. Required by producer-choice planning; [] declares no references. */
+    parameterReferenceSources?: WorkflowNativeParameterReference['source'][];
+    /** Opt-in: ports, references and output schema do not depend on parameter values. */
+    supportsRuntimeParameters?: true;
+    /** Optional generation contract specialized by the capability, never by field-name guessing. */
+    createPlanningParametersSchema?: (context: WorkflowCapabilityPlanningContext) => z.ZodType<JsonValueObject>;
+    inputPorts: (parameters: JsonValueObject) => string[];
+    outputPorts: (parameters: JsonValueObject) => string[];
+    responseReferences: (parameters: JsonValueObject) => WorkflowResponseReference[];
+    /** Native provenance required by this implementation, never inferred from values. */
+    nodeOutputReferences?: (parameters: JsonValueObject) => WorkflowNodeOutputReference[];
+    /** Locations of actual API/native/control references in this implementation's parameters. */
+    parameterReferenceBindings?: (parameters: JsonValueObject) => WorkflowNativeReferenceBinding[];
+    /** Explicit structural contract for inspecting unresolved references, never execution readiness. */
+    referenceStructureSchema?: z.ZodType<JsonValueObject>;
+    /** Captured source receipts and an explicit pure binding step for a new material revision. */
+    materialSources?: WorkflowNativeMaterialSources;
+    /** Declared constructor prerequisites, not inferred workflow dependencies or execution order. */
+    materialRequirements?: WorkflowNativeMaterialRequirement[];
+    bindMaterialContracts?: (sources: WorkflowNativeMaterialSources) => WorkflowCapability;
+    /** Dependencies required on a specific incoming port, before a join combines routes. */
+    inputReferences?: (parameters: JsonValueObject) => Record<string, WorkflowValueReference[]>;
+    waitsForAllInputs: boolean;
+    exclusiveOutputPorts: boolean;
+    /** Rejoin alternatives from this declared exclusive producer, not independent branches. */
+    rejoinsExclusiveOutputs?: (parameters: JsonValueObject) => string;
+    /** Explicit native JSON output contract; absent means no bindable output. */
+    outputSchema?: (parameters: JsonValueObject) => BindingSchema;
+}
+export interface NativeRuntimeParameterSelection {
+    pointers: string[];
+}
+export interface PlannedNativeNode {
+    id: string;
+    capability: string;
+    parameters: JsonValueObject;
+    /** Explicit runtime ownership of the whole parameter object; parameters must be {}. */
+    runtimeParameters?: true | NativeRuntimeParameterSelection;
+}
+export interface WorkflowPlanEdge {
+    from: string;
+    output: string;
+    to: string;
+    input: string;
+}
+export interface WorkflowPlanGap {
+    description: string;
+}
+export interface WorkflowGraphProposal {
+    nativeNodes: PlannedNativeNode[];
+    edges: WorkflowPlanEdge[];
+    gaps: WorkflowPlanGap[];
+}
+export interface WorkflowGraphPlan extends WorkflowGraphProposal {
+    starts: string[];
+    /** Optional original combined native/connection decision, not executable node data. */
+    graphPlanning?: WorkflowGraphPlanningRecord;
+}
+export interface CreateWorkflowGraphPlanInput {
+    proposal: WorkflowGraphProposal;
+    materials: WorkflowApiMaterial[];
+    capabilities: WorkflowCapability[];
+}
+export interface ValidateWorkflowGraphPlanInput {
+    /** Structural unresolved roles; strict compilers do not supply these. */
+    unresolvedNodes?: WorkflowUnresolvedNode[];
+    plan: WorkflowGraphPlan;
+    materials: WorkflowApiMaterial[];
+    capabilities: WorkflowCapability[];
+}
+export interface WorkflowRouteState {
+    branches: Map<string, string>;
+    completed: Set<string>;
+}
+export interface WorkflowPlanNodeContract {
+    id: string;
+    inputs: string[];
+    outputs: string[];
+    references: WorkflowValueReference[];
+    inputReferences?: Record<string, WorkflowValueReference[]>;
+    dependencyNodeIds: string[];
+    waitsForAllInputs: boolean;
+    exclusiveOutputPorts: boolean;
+    rejoinsExclusiveOutputs?: string;
+}
+export interface WorkflowNodeContractsInput {
+    unresolvedNodes?: WorkflowUnresolvedNode[];
+    materials: WorkflowApiMaterial[];
+    nativeNodes: PlannedNativeNode[];
+    capabilities: WorkflowCapability[];
+}
+export interface ValidateWorkflowTopologyInput {
+    contracts: WorkflowPlanNodeContract[];
+    apiIds: Set<string>;
+    edges: WorkflowPlanEdge[];
+    starts: string[];
+}
+export interface ValidateWorkflowEdgesInput {
+    contracts: WorkflowPlanNodeContract[];
+    edges: WorkflowPlanEdge[];
+}

package/dist/types/workflow-plan.js

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

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

@@ -0,0 +1,29 @@
+import type { ApiBindingMaterial } from './api-bindings.js';
+import type { WorkflowCapability, PlannedNativeNode } from './workflow-plan.js';
+import type { ReviewableWorkflowApiMaterial } from './reviewable-workflow.js';
+import type { NativeOutputContract } from './node-output.js';
+import type { NativePlanningCapabilityMaterial } from './native-node-planning.js';
+export interface WorkflowPlanningMaterialInput {
+    scenario: string;
+    capabilities?: WorkflowCapability[];
+    apiMaterials?: ApiBindingMaterial[];
+    preparedNativeNodes?: PlannedNativeNode[];
+}
+export type WorkflowPlanningMaterialSnapshot = Required<Omit<WorkflowPlanningMaterialInput, 'scenario'>>;
+export interface WorkflowPlanningDataInput {
+    scenario: string;
+    materials: ReviewableWorkflowApiMaterial[];
+    capabilities?: WorkflowCapability[];
+    preparedNativeNodes?: PlannedNativeNode[];
+}
+export interface WorkflowPlanningDataSnapshot {
+    materials: ReviewableWorkflowApiMaterial[];
+    capabilities: WorkflowCapability[];
+    preparedNativeNodes: PlannedNativeNode[];
+}
+export interface WorkflowPlanningSourceEvidence {
+    /** Original supplied API contracts/values, not an extra model-generated contract. */
+    materials: ReviewableWorkflowApiMaterial[];
+    nativeOutputs: NativeOutputContract[];
+    capabilities: NativePlanningCapabilityMaterial[];
+}

package/dist/types/workflow-planning-materials.js

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

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

@@ -0,0 +1,89 @@
+import type { JsonValue } from './api-arguments.js';
+import type { WorkflowPlanningContext, WorkflowPlanningContextDescription, WorkflowPlanningEvidence } from './planning-evidence.js';
+import type { WorkflowSourceMessage } from './workflow-draft.js';
+export interface WorkflowReviewQuestion {
+    id: string;
+    message: string;
+}
+/** The host owns this read-only review projection, not an executable plan or a new OAS contract. */
+export interface WorkflowReviewBoundary {
+    key: string;
+    kind: 'requirements-clarification' | 'selection-review' | 'planning-questions' | 'candidate-review';
+    revision: number;
+    questions: WorkflowReviewQuestion[];
+    data: JsonValue;
+}
+export interface WorkflowReviewSuggestionLimits {
+    maxSuggestions: number;
+}
+export type WorkflowReviewSuggestionEnvironment = Record<string, string | undefined>;
+export interface WorkflowReviewSuggestionOptions {
+    includeExplanations?: boolean;
+    includeExtensions?: boolean;
+}
+export interface ResolvedWorkflowReviewSuggestionOptions {
+    includeExplanations: boolean;
+    includeExtensions: boolean;
+}
+export interface WorkflowReviewQuestionEvidence {
+    kind: 'review-question';
+    questionId: string;
+}
+export type WorkflowReviewSuggestionEvidence = WorkflowPlanningEvidence | WorkflowReviewQuestionEvidence;
+export type ProposedWorkflowReviewSuggestion<Evidence = WorkflowReviewSuggestionEvidence> = {
+    text: string;
+    sources: Evidence[];
+    reason?: string;
+} & ({
+    kind: 'answer-question';
+    questionIds: string[];
+} | {
+    kind: 'change-request' | 'extend-workflow';
+});
+export interface WorkflowReviewSuggestionsProposal<Evidence = WorkflowReviewSuggestionEvidence> {
+    suggestions: ProposedWorkflowReviewSuggestion<Evidence>[];
+}
+export type WorkflowReviewSuggestion = ProposedWorkflowReviewSuggestion & {
+    id: string;
+};
+export interface WorkflowReviewSuggestionsInput {
+    context: WorkflowPlanningContext;
+    boundary: WorkflowReviewBoundary;
+    limits: WorkflowReviewSuggestionLimits;
+    options?: WorkflowReviewSuggestionOptions;
+}
+export interface WorkflowReviewSuggestionsDescription {
+    fingerprint: string;
+    context: WorkflowPlanningContextDescription;
+    boundary: WorkflowReviewBoundary;
+    limits: WorkflowReviewSuggestionLimits;
+    options: ResolvedWorkflowReviewSuggestionOptions;
+}
+export interface WorkflowReviewSuggestions {
+    id: string;
+    fingerprint: string;
+    boundaryKey: string;
+    /** Immutable read-only review target, so historical question sources remain inspectable after a revision. */
+    target: Omit<WorkflowReviewBoundary, 'key'>;
+    limits: WorkflowReviewSuggestionLimits;
+    options: ResolvedWorkflowReviewSuggestionOptions;
+    suggestions: WorkflowReviewSuggestion[];
+}
+export interface CreateWorkflowReviewSuggestionsInput extends WorkflowReviewSuggestionsInput {
+    proposal: WorkflowReviewSuggestionsProposal;
+}
+export interface WorkflowReviewSuggestionsValidationInput extends WorkflowReviewSuggestionsInput {
+    review: WorkflowReviewSuggestions;
+}
+export interface AdoptWorkflowReviewSuggestionInput extends WorkflowReviewSuggestionsValidationInput {
+    suggestionId: string;
+    messageId: string;
+}
+/** An explicit adoption receipt. It is not the original human's prose and does not apply an edit. */
+export interface WorkflowReviewSuggestionAdoption {
+    reviewId: string;
+    suggestionId: string;
+    boundaryKey: string;
+    suggestion: WorkflowReviewSuggestion;
+    message: WorkflowSourceMessage;
+}

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

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

package/dist/utils/clone-json-value.d.ts

@@ -0,0 +1,3 @@
+import type { JsonValue } from '../types/api-arguments.js';
+/** JSON-only structural copy; object keys cannot invoke prototype setters. */
+export declare function cloneJsonValue(value: JsonValue): JsonValue;

package/dist/utils/clone-json-value.js

@@ -0,0 +1,11 @@
+/** JSON-only structural copy; object keys cannot invoke prototype setters. */
+export function cloneJsonValue(value) {
+    if (Array.isArray(value))
+        return value.map(cloneJsonValue);
+    if (value === null || typeof value !== 'object')
+        return value;
+    const result = Object.create(null);
+    for (const [key, child] of Object.entries(value))
+        result[key] = cloneJsonValue(child);
+    return result;
+}

package/dist/utils/is-object.d.ts

@@ -0,0 +1,2 @@
+import type { JsonObject } from '../types/openapi.js';
+export declare function isObject(value: unknown): value is JsonObject;

package/dist/utils/is-object.js

@@ -0,0 +1,3 @@
+export function isObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

package/dist/utils/json-values-equal.d.ts

@@ -0,0 +1,2 @@
+/** Compare JSON values without normalizing their types or object key order. */
+export declare function jsonValuesEqual(left: unknown, right: unknown): boolean;

package/dist/utils/json-values-equal.js

@@ -0,0 +1,16 @@
+/** Compare JSON values without normalizing their types or object key order. */
+export function jsonValuesEqual(left, right) {
+    if (left === right)
+        return true;
+    if (Array.isArray(left) || Array.isArray(right))
+        return (Array.isArray(left) &&
+            Array.isArray(right) &&
+            left.length === right.length &&
+            left.every((value, index) => jsonValuesEqual(value, right[index])));
+    if (!left || !right || typeof left !== 'object' || typeof right !== 'object')
+        return false;
+    const keys = Object.keys(left);
+    return (keys.length === Object.keys(right).length &&
+        keys.every((key) => Object.hasOwn(right, key) &&
+            jsonValuesEqual(Reflect.get(left, key), Reflect.get(right, key))));
+}

package/dist/workflow/assert-api-call-identities.d.ts

@@ -0,0 +1 @@
+export declare function assertApiCallIdentities(apiCallIds: string[]): void;

package/dist/workflow/assert-api-call-identities.js

@@ -0,0 +1,6 @@
+export function assertApiCallIdentities(apiCallIds) {
+    if (!Array.isArray(apiCallIds) ||
+        apiCallIds.some((id) => typeof id !== 'string' || !id.trim()) ||
+        new Set(apiCallIds).size !== apiCallIds.length)
+        throw new Error('planning.apiCallIds must contain unique non-empty call IDs');
+}

package/dist/workflow/bind-native-material-contracts.d.ts

@@ -0,0 +1,4 @@
+import type { WorkflowCapability } from '../types/workflow-plan.js';
+import type { WorkflowNativeMaterialSources } from '../types/native-material-snapshot.js';
+/** Static implementations retain their definition; material-dependent implementations receive actual contracts. */
+export declare function bindNativeMaterialContracts(definition: WorkflowCapability, sources: WorkflowNativeMaterialSources): WorkflowCapability;

package/dist/workflow/bind-native-material-contracts.js

@@ -0,0 +1,16 @@
+import { jsonValuesEqual } from '../utils/json-values-equal.js';
+/** Static implementations retain their definition; material-dependent implementations receive actual contracts. */
+export function bindNativeMaterialContracts(definition, sources) {
+    if (!definition.bindMaterialContracts)
+        return definition;
+    const bound = definition.bindMaterialContracts(structuredClone(sources));
+    if (!bound ||
+        bound.name !== definition.name ||
+        typeof bound.parametersSchema?.parse !== 'function')
+        throw new Error(`Native material binding ${definition.name} must retain its capability identity and parameter contract`);
+    if (!bound.materialSources)
+        throw new Error(`Native material binding ${definition.name} must declare its actual materialSources`);
+    if (!jsonValuesEqual(bound.parameterReferenceSources, definition.parameterReferenceSources))
+        throw new Error(`Native material binding ${definition.name} must retain its declared parameterReferenceSources`);
+    return bound;
+}

package/dist/workflow/connections/create-workflow-connection-plan.d.ts

@@ -0,0 +1,3 @@
+import type { CreateWorkflowConnectionPlanInput } from '../../types/workflow-connection-planning.js';
+import type { ReviewableWorkflowGraphPlan } from '../../types/reviewable-workflow.js';
+export declare function createWorkflowConnectionPlan(input: CreateWorkflowConnectionPlanInput): ReviewableWorkflowGraphPlan;

package/dist/workflow/connections/create-workflow-connection-plan.js

@@ -0,0 +1,15 @@
+import { workflowConnectionProposalSchema } from '../../schemas/workflow-connection-planning-schema.js';
+import { describeWorkflowConnectionPlanning } from './describe-workflow-connection-planning.js';
+import { createReviewableWorkflowGraphPlan } from '../create-reviewable-workflow-graph-plan.js';
+export function createWorkflowConnectionPlan(input) {
+    const { input: snapshot } = describeWorkflowConnectionPlanning(input);
+    const proposal = workflowConnectionProposalSchema.parse(input.proposal);
+    return createReviewableWorkflowGraphPlan({
+        ...snapshot,
+        proposal: {
+            ...proposal,
+            nativeNodes: structuredClone(snapshot.nativeNodes),
+            edges: [...structuredClone(snapshot.edges), ...proposal.edges],
+        },
+    });
+}

package/dist/workflow/connections/create-workflow-connection-planning-record.d.ts

@@ -0,0 +1,2 @@
+import type { CreateWorkflowConnectionPlanningRecordInput, WorkflowConnectionPlanningRecord } from '../../types/workflow-connection-planning.js';
+export declare function createWorkflowConnectionPlanningRecord(input: CreateWorkflowConnectionPlanningRecordInput): WorkflowConnectionPlanningRecord;

package/dist/workflow/connections/create-workflow-connection-planning-record.js

@@ -0,0 +1,32 @@
+import { isDeepStrictEqual } from 'node:util';
+import { workflowConnectionDecisionSchema, workflowConnectionPlanningResultSchema, workflowConnectionPlanningRecordSchema, } from '../../schemas/workflow-connection-planning-schema.js';
+import { describeWorkflowConnectionPlanning } from './describe-workflow-connection-planning.js';
+import { projectWorkflowConnectionDecision } from './project-workflow-connection-decision.js';
+import { createWorkflowConnectionPlan } from './create-workflow-connection-plan.js';
+import { createReviewableNodeContracts } from '../create-reviewable-node-contracts.js';
+export function createWorkflowConnectionPlanningRecord(input) {
+    const { input: snapshot, context, sources, } = describeWorkflowConnectionPlanning(input);
+    const decision = workflowConnectionDecisionSchema.parse(input.decision);
+    const plan = workflowConnectionPlanningResultSchema.parse({
+        nativeNodes: input.plan.nativeNodes,
+        edges: input.plan.edges,
+        gaps: input.plan.gaps,
+        blockedCalls: input.plan.blockedCalls,
+        starts: input.plan.starts,
+    });
+    const expected = createWorkflowConnectionPlan({
+        ...snapshot,
+        proposal: projectWorkflowConnectionDecision(decision),
+    });
+    if (!isDeepStrictEqual(plan, expected))
+        throw new Error('connection planning result differs from its original fixed materials or explained proposal');
+    return workflowConnectionPlanningRecordSchema.parse({
+        kind: 'proposed-connections',
+        decision,
+        plan: structuredClone(plan),
+        evidence: { kind: 'supplied-connection-materials', context, sources },
+        verification: {
+            contracts: structuredClone(createReviewableNodeContracts({ ...snapshot, plan })),
+        },
+    });
+}

package/dist/workflow/connections/describe-workflow-connection-planning.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowConnectionPlanningInput, WorkflowConnectionPlanningDescription } from '../../types/workflow-connection-planning.js';
+/** Capture declared data before awaiting the model; never clone opaque callbacks or forward audit metadata. */
+export declare function describeWorkflowConnectionPlanning(input: WorkflowConnectionPlanningInput): WorkflowConnectionPlanningDescription;

package/dist/workflow/connections/describe-workflow-connection-planning.js

@@ -0,0 +1,81 @@
+import { workflowConnectionIdentitySchema } from '../../schemas/workflow-connection-planning-schema.js';
+import { workflowDraftEdgeSchema } from '../../schemas/workflow-draft-schema.js';
+import { captureWorkflowPlanningData } from '../planning/capture-workflow-planning-data.js';
+import { workflowReviewGapSchema } from '../../schemas/workflow-planning-material-schema.js';
+import { createPreparedNativeNodeMaterials } from '../planning/create-prepared-native-node-materials.js';
+import { createNativeOutputContracts } from '../create-native-output-contracts.js';
+import { createNativePlanningCapabilityMaterial } from '../planning/create-native-planning-capability-material.js';
+import { prepareWorkflowConnectionMaterials } from './prepare-workflow-connection-materials.js';
+/** Capture declared data before awaiting the model; never clone opaque callbacks or forward audit metadata. */
+export function describeWorkflowConnectionPlanning(input) {
+    const { scenario } = workflowConnectionIdentitySchema.parse({
+        scenario: input.scenario,
+    });
+    for (const field of [
+        'materials',
+        'capabilities',
+        'nativeNodes',
+        'gaps',
+        'edges',
+    ])
+        if (input[field] !== undefined && !Array.isArray(input[field]))
+            throw new Error(`connection planning ${field} must be an array`);
+    const supplied = input.materials === undefined ? [] : input.materials;
+    const captured = captureWorkflowPlanningData({
+        scenario,
+        capabilities: input.capabilities,
+        preparedNativeNodes: input.nativeNodes,
+        materials: supplied,
+    });
+    const materials = captured.materials;
+    const prepared = prepareWorkflowConnectionMaterials({
+        materials,
+        capabilities: captured.capabilities,
+        nativeNodes: captured.preparedNativeNodes,
+        gaps: structuredClone((input.gaps === undefined ? [] : input.gaps).map((gap) => workflowReviewGapSchema.parse(gap))),
+        edges: structuredClone((input.edges === undefined ? [] : input.edges).map((edge) => workflowDraftEdgeSchema.parse(edge))),
+    });
+    const context = {
+        scenario,
+        nodes: structuredClone(prepared.contracts),
+        ...(prepared.nativeNodes.length
+            ? {
+                nativeNodes: structuredClone(createPreparedNativeNodeMaterials(prepared.nativeNodes, prepared.capabilities)),
+                nativeParameterReadiness: prepared.nativeNodes.map((node) => ({
+                    nodeId: node.id,
+                    planTimeStatus: 'validated',
+                    executionInputPointers: node.runtimeParameters === undefined
+                        ? []
+                        : node.runtimeParameters === true
+                            ? ['']
+                            : [...node.runtimeParameters.pointers],
+                })),
+            }
+            : {}),
+        edges: structuredClone(prepared.edges),
+        gaps: structuredClone(prepared.gaps),
+        readyCallIds: materials.flatMap((material) => material.status === 'ready' ? [material.arguments.callId] : []),
+        apiRoles: materials.flatMap((material) => material.purpose === undefined
+            ? []
+            : [
+                {
+                    callId: material.status === 'ready'
+                        ? material.arguments.callId
+                        : material.callId,
+                    purpose: material.purpose,
+                },
+            ]),
+    };
+    return {
+        input: { ...prepared, scenario },
+        context,
+        sources: structuredClone({
+            materials,
+            nativeOutputs: createNativeOutputContracts({
+                nativeNodes: prepared.nativeNodes,
+                capabilities: prepared.capabilities,
+            }),
+            capabilities: prepared.capabilities.map((capability) => createNativePlanningCapabilityMaterial(capability, false)),
+        }),
+    };
+}

package/dist/workflow/connections/prepare-workflow-connection-materials.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowConnectionMaterialInput, WorkflowConnectionMaterials } from '../../types/workflow-connection-planning.js';
+/** Validate immutable supplied data before paying for any orchestration model call. */
+export declare function prepareWorkflowConnectionMaterials(input: WorkflowConnectionMaterialInput): WorkflowConnectionMaterials;