@exellix/graph-engine 8.0.0 → 8.1.0

package/dist/src/runtime/studioGraphExecuteRequest.d.ts

@@ -1,40 +1,15 @@
-import type { Graph } from '../types/refs.js';
-import type { ExecuteGraphInput, GraphRuntimeObject } from './ExellixGraphRuntime.js';
+import type { ExecuteGraphInput } from './ExellixGraphRuntime.js';
 /**
  * Removed from the graphs-studio execute envelope (7.8.3+). No reader, no fallback.
- * Default model selection belongs on {@link Graph}.modelConfig only.
+ * Default model selection belongs on authoring graph executable profile only.
  */
 export declare const STUDIO_GRAPH_EXECUTE_REMOVED_KEYS: readonly ["graphDefaultModel"];
 export type StudioGraphExecuteRemovedKey = (typeof STUDIO_GRAPH_EXECUTE_REMOVED_KEYS)[number];
-/**
- * Graphs-studio / playground graph execute envelope before host adaptation to
- * {@link ExecuteGraphInput}. Credential and simulate-only fields are host concerns;
- * graph-engine validates shape and forbidden keys only.
- */
-export type StudioGraphExecuteRequest = {
-    mode: 'graph';
-    graph: Graph;
-    jobId: string;
-    runtime: Pick<GraphRuntimeObject, 'input' | 'inputs' | 'jobMemory' | 'taskMemory' | 'executionMemory' | 'outputsMemory' | 'variables' | 'jobVariables' | 'taskVariables' | 'nodes'>;
-    studioId?: string;
-    executionMode?: string;
-    runLogMode?: GraphRuntimeObject['runLogMode'];
-    maxRunLogEntries?: number;
-    maxRunLogDataJsonChars?: number;
-    graphExecution?: {
-        mode?: GraphRuntimeObject['mode'];
-        goalNodeId?: string;
-        dimension?: string;
-    };
-    runTaskDiagnostics?: GraphRuntimeObject['runTaskDiagnostics'];
-    exampleIndex?: number;
-    validateGraphEntrySeed?: boolean;
-    openrouterApiKey?: string;
-};
+/** @deprecated Prefer {@link AuthoringGraphDocument} from `@x12i/graphenix-executable-contracts`. */
+export type StudioGraphExecuteRequest = import('@x12i/graphenix-executable-contracts').StudioGraphExecuteRequest;
 export declare function getStudioGraphExecuteRemovedKeyViolations(request: unknown): StudioGraphExecuteRemovedKey[];
 /**
  * Rejects removed studio execute keys (notably `graphDefaultModel`).
- * Hosts must persist model defaults on `graph.modelConfig` and stop sending request-level mirrors.
  */
 export declare function assertCanonicalStudioGraphExecuteRequest(request: unknown, context?: {
     jobId?: string;
@@ -46,6 +21,6 @@ export type BuildGraphExecutionRequestFromStudioExecuteOptions = {
 };
 /**
  * Maps a validated studio execute envelope to {@link ExecuteGraphInput}.
- * Does not read or merge removed request-level model defaults — graph.modelConfig is authoritative.
+ * Delegates validate + compile to `@x12i/graphenix-execute-envelope`.
  */
 export declare function buildGraphExecutionRequestFromStudioExecute(request: StudioGraphExecuteRequest, options?: BuildGraphExecutionRequestFromStudioExecuteOptions): ExecuteGraphInput;

package/dist/src/runtime/studioGraphExecuteRequest.js

@@ -1,9 +1,9 @@
-import { compileExellixExecutablePlan } from '../adapters/compileExellixExecutablePlan.js';
+import { buildGraphExecutionRequestFromStudioExecute as buildAuthoringRequest } from '@x12i/graphenix-execute-envelope';
 import { ExellixGraphError } from '../errors/ExellixGraphError.js';
 import { ExellixGraphErrorCode } from '../errors/exellixGraphErrorCodes.js';
 /**
  * Removed from the graphs-studio execute envelope (7.8.3+). No reader, no fallback.
- * Default model selection belongs on {@link Graph}.modelConfig only.
+ * Default model selection belongs on authoring graph executable profile only.
  */
 export const STUDIO_GRAPH_EXECUTE_REMOVED_KEYS = ['graphDefaultModel'];
 function isPlainObject(v) {
@@ -16,63 +16,27 @@ export function getStudioGraphExecuteRemovedKeyViolations(request) {
 }
 /**
  * Rejects removed studio execute keys (notably `graphDefaultModel`).
- * Hosts must persist model defaults on `graph.modelConfig` and stop sending request-level mirrors.
  */
 export function assertCanonicalStudioGraphExecuteRequest(request, context) {
     const removed = getStudioGraphExecuteRemovedKeyViolations(request);
     if (removed.length > 0) {
-        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_STUDIO_GRAPH_EXECUTE_REQUEST, `Studio graph execute request must not include removed field(s): ${removed.join(', ')}. Model defaults belong on graph.modelConfig only; request-level graphDefaultModel was removed with no legacy fallback.`, { ...context, removedKeys: removed });
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_STUDIO_GRAPH_EXECUTE_REQUEST, `Studio graph execute request must not include removed field(s): ${removed.join(', ')}. Model defaults belong on the authoring graph executable profile only; request-level graphDefaultModel was removed with no legacy fallback.`, { ...context, removedKeys: removed });
     }
-    if (!isPlainObject(request)) {
-        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_STUDIO_GRAPH_EXECUTE_REQUEST, 'Studio graph execute request must be a plain object.', context);
-    }
-    if (request.mode !== 'graph') {
-        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_STUDIO_GRAPH_EXECUTE_REQUEST, 'Studio graph execute request mode must be "graph".', context);
-    }
-    const jobId = typeof request.jobId === 'string' ? request.jobId.trim() : '';
-    if (!jobId) {
-        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_STUDIO_GRAPH_EXECUTE_REQUEST, 'Studio graph execute request requires a non-empty jobId.', context);
-    }
-    if (!isPlainObject(request.graph)) {
-        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_STUDIO_GRAPH_EXECUTE_REQUEST, 'Studio graph execute request requires graph (GraphModelObject).', { ...context, jobId });
-    }
-    if (!isPlainObject(request.runtime)) {
-        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_STUDIO_GRAPH_EXECUTE_REQUEST, 'Studio graph execute request requires runtime.', { ...context, jobId });
+    if (!isPlainObject(request) || request.mode !== 'graph' || typeof request.jobId !== 'string') {
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_STUDIO_GRAPH_EXECUTE_REQUEST, 'Studio graph execute request requires mode graph and jobId.', context);
     }
 }
 /**
  * Maps a validated studio execute envelope to {@link ExecuteGraphInput}.
- * Does not read or merge removed request-level model defaults — graph.modelConfig is authoritative.
+ * Delegates validate + compile to `@x12i/graphenix-execute-envelope`.
  */
 export function buildGraphExecutionRequestFromStudioExecute(request, options) {
-    assertCanonicalStudioGraphExecuteRequest(request);
-    const jobId = request.jobId.trim();
-    const graphId = request.graph != null && typeof request.graph === 'object' && typeof request.graph.id === 'string'
-        ? request.graph.id
-        : undefined;
-    const runtime = {
-        jobId,
-        job: {
-            id: jobId,
-            jobId,
-            agentId: options?.agentId ?? 'standalone-agent',
-            jobTypeId: options?.jobTypeId ?? 'exellix-graph-job',
-        },
-        ...request.runtime,
-        ...(request.graphExecution?.mode != null ? { mode: request.graphExecution.mode } : {}),
-        ...(request.graphExecution?.goalNodeId != null
-            ? { goalNodeId: request.graphExecution.goalNodeId }
-            : {}),
-        ...(request.graphExecution?.dimension != null ? { dimension: request.graphExecution.dimension } : {}),
-        ...(request.runLogMode != null ? { runLogMode: request.runLogMode } : {}),
-        ...(request.maxRunLogEntries != null ? { maxRunLogEntries: request.maxRunLogEntries } : {}),
-        ...(request.maxRunLogDataJsonChars != null
-            ? { maxRunLogDataJsonChars: request.maxRunLogDataJsonChars }
-            : {}),
-        ...(request.runTaskDiagnostics != null ? { runTaskDiagnostics: request.runTaskDiagnostics } : {}),
-    };
-    return {
-        plan: compileExellixExecutablePlan(request.graph, runtime),
-        runtime,
-    };
+    assertCanonicalStudioGraphExecuteRequest(request, {
+        jobId: request.jobId,
+        graphId: request.graph?.id,
+    });
+    return buildAuthoringRequest(request, {
+        agentId: options?.agentId,
+        jobTypeId: options?.jobTypeId,
+    });
 }

package/dist/src/runtime/taskNodeRunTaskPreflight.d.ts

@@ -1,11 +1,12 @@
 /**
  * Graph-level preflight for `@exellix/ai-tasks` validation and analysis on task nodes.
- * Builds the same outbound {@link RunTaskRequest} as `executeNode` (without PRE strategy phases or `runTask`).
+ * Builds the same outbound {@link RunTaskRequest} as `executeNode` (without `runTask`).
  */
 import type { RunTaskRequest } from '@exellix/ai-tasks';
 import { type RunTaskInvokeValidationResult, type RunTaskValidationResult, type ValidateRunTaskInvokeParams } from '@exellix/ai-tasks';
+import type { NodeExecutionPlan } from '@x12i/graphenix-executable-contracts';
 import type { GraphAiModelConfig, Job, TaskNode } from '../types/refs.js';
-import type { ExecutionStepOption, RunTaskDiagnostics, SkillKeyResolutionOptions } from '../types/options.js';
+import type { RunTaskDiagnostics, SkillKeyResolutionOptions } from '../types/options.js';
 export type TaskNodeRunTaskPreflightSkipReason = 'local_skill' | 'finalizer';
 export type BuildTaskNodeRunTaskRequestResult = {
     runnable: true;
@@ -29,20 +30,21 @@ export type BuildTaskNodeRunTaskRequestArgs = {
     graphRunTaskId?: string;
     /** Host job id on `job.jobId` / `job.id`; defaults from `job` when omitted. */
     runTaskJobId?: string;
-    /** Resolved graph model profiles (required for runnable MAIN). */
+    /** Frozen per-node plan from compile; when omitted a minimal plan is synthesized and patched from modelConfig. */
+    nodePlan?: NodeExecutionPlan;
+    /** Resolved graph model profiles (required for runnable MAIN when nodePlan is omitted). */
     modelConfig: GraphAiModelConfig;
     runTaskIdentity?: Record<string, unknown>;
     runTaskExecutionMode?: 'default' | 'trace';
     runTaskDiagnostics?: RunTaskDiagnostics;
     jobKnowledgePatch?: Record<string, unknown>;
     taskKnowledgePatch?: Record<string, unknown>;
-    graphExecutionPipeline?: ExecutionStepOption[];
     skillKeyResolution?: SkillKeyResolutionOptions;
     clearSynthesizedContextPerNode?: boolean;
 };
 /**
  * Materialize the outbound `RunTaskRequest` graph-engine would send for a task node
- * (mirrors `executeNode` request assembly; does not run PRE strategy phases or `runTask`).
+ * (mirrors `executeNode` request assembly; does not invoke `runTask`).
  */
 export declare function buildTaskNodeRunTaskRequest(args: BuildTaskNodeRunTaskRequestArgs): Promise<BuildTaskNodeRunTaskRequestResult>;
 export type ValidateTaskNodeRunTaskConfigArgs = BuildTaskNodeRunTaskRequestArgs;

package/dist/src/runtime/taskNodeRunTaskPreflight.js

@@ -3,7 +3,6 @@ import { toRunTaskModelConfig } from './graphAiModelConfig.js';
 import { resolveTaskKey } from './resolveTaskKey.js';
 import { isLocalSkillKey } from './localSkills/index.js';
 import { buildAiTasksRunTaskRequest, extractRunTaskStrategyOverrides, } from './buildAiTasksRunTaskRequest.js';
-import { resolveExecutionPipelineForTaskNode } from './resolveExecutionPipelineForTaskNode.js';
 import { resolveTaskNodeInputsForRunTask } from './resolveTaskNodeInputs.js';
 import { assertAiTasksNodeExtensionsValid } from '../inspection/validateAiTasksNodeExtensions.js';
 import { buildRunTaskMainInput, extractCallerInputsBag } from './resolveGraphEngineMemoryPaths.js';
@@ -11,10 +10,10 @@ import { mirrorStructuredInputOntoExecutionMemory, } from './materializeStructur
 import { xynthesizedOutboundForNode } from './graphRunExecutionSeed.js';
 import { buildTaskNodeJobContext } from './buildTaskNodeJobContext.js';
 import { resolveNarrixForTaskNode } from './resolveNarrixForTaskNode.js';
-import { normalizeSynthesizedContextConfig } from './synthesizedContextPipeline.js';
-import { buildMainLlmCallForRunTask, buildRunTaskIdentityEnvelope, shouldForwardRunTaskTraceMode, } from './runTaskAugments.js';
+import { buildRunTaskIdentityEnvelope, shouldForwardRunTaskTraceMode, } from './runTaskAugments.js';
 import { mirrorTaskVariablesOnExecution, readExecutionVariableBuckets, } from './executionVariableBuckets.js';
 import { newGraphRunTaskId } from './graphRunIdentity.js';
+import { patchNodePlanMainModelFromWire, resolveRunTaskNodePlan } from './runTaskNodePlan.js';
 function isPlainRecord(v) {
     return v != null && typeof v === 'object' && !Array.isArray(v);
 }
@@ -33,7 +32,7 @@ function mergeKnowledgePatchIntoRunTaskMemory(memory, patch) {
 }
 /**
  * Materialize the outbound `RunTaskRequest` graph-engine would send for a task node
- * (mirrors `executeNode` request assembly; does not run PRE strategy phases or `runTask`).
+ * (mirrors `executeNode` request assembly; does not invoke `runTask`).
  */
 export async function buildTaskNodeRunTaskRequest(args) {
     const node = args.node;
@@ -59,23 +58,22 @@ export async function buildTaskNodeRunTaskRequest(args) {
         node: node,
         runtimeTaskVariables: args.taskVariables,
     });
-    const executionPipeline = resolveExecutionPipelineForTaskNode({
-        node,
-        optionsExecutionPipeline: args.graphExecutionPipeline,
-        executionExecutionPipeline: execution.executionPipeline,
+    const wireModelConfig = toRunTaskModelConfig(args.modelConfig);
+    let runTaskNodePlan = resolveRunTaskNodePlan({
+        nodePlan: args.nodePlan,
+        skillKey,
+        nodeId: String(node.id),
     });
-    const hasSynthesizedContextPreStep = Array.isArray(executionPipeline) &&
-        executionPipeline.some((s) => s.phase === 'pre' && s.type === 'synthesized-context');
-    const preStepConfig = hasSynthesizedContextPreStep && Array.isArray(executionPipeline)
-        ? normalizeSynthesizedContextConfig(executionPipeline.find((s) => s.phase === 'pre' && s.type === 'synthesized-context')?.config)
-        : undefined;
-    const includeContextInPrompt = hasSynthesizedContextPreStep && preStepConfig?.autoEnableContext !== true;
-    const variableBuckets = readExecutionVariableBuckets(execution);
-    const jobVariables = variableBuckets.jobVariables;
+    if (!args.nodePlan) {
+        runTaskNodePlan = patchNodePlanMainModelFromWire(runTaskNodePlan, wireModelConfig);
+    }
+    const hasSynthesizedContextPreStep = runTaskNodePlan.executionUnits.some((u) => u.unitKind === 'externalPreUtility' || u.unitKind === 'pipelinePhase');
     const hasExistingSynthesizedContext = execution.synthesizedContext != null;
     const clearSynthForTask = args.clearSynthesizedContextPerNode === true &&
         hasSynthesizedContextPreStep &&
         hasExistingSynthesizedContext;
+    const variableBuckets = readExecutionVariableBuckets(execution);
+    const jobVariables = variableBuckets.jobVariables;
     const nodeBindings = resolveTaskNodeInputsForRunTask({ node, execution });
     const jobContext = buildTaskNodeJobContext({
         node,
@@ -115,12 +113,21 @@ export async function buildTaskNodeRunTaskRequest(args) {
     mirrorStructuredInputOntoExecutionMemory(executionForTask, taskInput);
     const runTaskJobMemory = mergeKnowledgePatchIntoRunTaskMemory(args.jobMemory, args.jobKnowledgePatch);
     const runTaskTaskMemory = mergeKnowledgePatchIntoRunTaskMemory(args.taskMemory, args.taskKnowledgePatch);
-    const wireModelConfig = toRunTaskModelConfig(args.modelConfig);
-    const effectiveLlmCall = buildMainLlmCallForRunTask(wireModelConfig, node.taskConfiguration?.llmCall);
     const forwardRunTaskTrace = shouldForwardRunTaskTraceMode({
         runTaskExecutionMode: args.runTaskExecutionMode,
     });
-    const metaStrats = node.taskConfiguration?.executionStrategies;
+    const metaStrats = runTaskNodePlan.invokeContract?.pipeline &&
+        typeof runTaskNodePlan.invokeContract.pipeline === 'object' &&
+        Array.isArray(runTaskNodePlan.invokeContract.pipeline.executionStrategies)
+        ? runTaskNodePlan.invokeContract.pipeline
+            .executionStrategies
+        : node.taskConfiguration?.executionStrategies;
+    const outputValidationFromPlan = runTaskNodePlan.invokeContract?.validation &&
+        typeof runTaskNodePlan.invokeContract.validation === 'object' &&
+        'aiTasksOutputValidation' in runTaskNodePlan.invokeContract.validation
+        ? runTaskNodePlan.invokeContract.validation
+            .aiTasksOutputValidation
+        : undefined;
     const ov = node.taskConfiguration?.aiTasksOutputValidation;
     const request = buildAiTasksRunTaskRequest({
         skillKey,
@@ -138,16 +145,13 @@ export async function buildTaskNodeRunTaskRequest(args) {
         executionMemory: executionForTask,
         jobContext,
         prevNodeId: args.prevNodeId,
-        executionPipeline: executionPipeline,
-        includeContextInPrompt: includeContextInPrompt === true ? true : undefined,
         narrix: narrix ?? undefined,
         ...extractRunTaskStrategyOverrides(node.taskConfiguration),
-        outputValidation: ov != null && typeof ov === 'object' && !Array.isArray(ov) && 'schema' in ov
-            ? ov
-            : undefined,
+        outputValidation: outputValidationFromPlan ??
+            (ov != null && typeof ov === 'object' && !Array.isArray(ov) && 'schema' in ov
+                ? ov
+                : undefined),
         diagnostics: args.runTaskDiagnostics,
-        modelConfig: wireModelConfig,
-        llmCall: effectiveLlmCall,
         identity: buildRunTaskIdentityEnvelope({
             base: args.runTaskIdentity,
             nodeMeta: node.taskConfiguration,
@@ -162,6 +166,7 @@ export async function buildTaskNodeRunTaskRequest(args) {
         executionStrategies: Array.isArray(metaStrats) ? metaStrats : [],
         xynthesized: xynthesizedOutboundForNode(execution, String(node.id)),
         smartInput: node.smartInput,
+        nodePlan: runTaskNodePlan,
     });
     return { runnable: true, skillKey, request };
 }

package/dist/src/types/refs.d.ts

@@ -680,7 +680,7 @@ export interface GraphDocumentMetadata {
     graphResponse?: GraphResponseContract;
     /**
      * Graph execution defaults and labels.
-     * Planner mode is still selected by `executeGraph({ model, runtime }).runtime.mode` and defaults to `forward`;
+     * Planner mode is still selected by `executeGraph({ plan, runtime }).runtime.mode` (or plan.schedulingPolicy) and defaults to `forward`;
      * output labels in this block shape `stepsResponses`, not `ExecuteGraphResult.finalOutput`.
      */
     graphExecution?: GraphExecutionDefaults;

package/dist/testkit/authoringGraphFixtures.d.ts

@@ -0,0 +1,8 @@
+import type { AuthoringGraphDocument } from '@x12i/graphenix-executable-contracts';
+/** Single ai-task + select finalizer — mirrors legacy flat `buildAiTaskGraph` tests. */
+export declare function buildAiTaskAuthoringGraph(graphId: string): AuthoringGraphDocument;
+/** deterministic-rule local skill + select finalizer. */
+export declare function buildLocalSkillAuthoringGraph(graphId: string): AuthoringGraphDocument;
+/** Fan-in Q&A graph used by graph.response mapping tests. */
+export declare function buildGraphResponseMappingAuthoringGraph(graphId: string): AuthoringGraphDocument;
+export declare function withAuthoringGraphModelConfig(doc: AuthoringGraphDocument, modelConfig: Record<string, unknown>): AuthoringGraphDocument;

package/dist/testkit/authoringGraphFixtures.js

@@ -0,0 +1,249 @@
+import { GRAPHENIX_FORMAT_VERSION } from '@x12i/graphenix-core';
+import { EXECUTABLE_PROFILE_NAMESPACE, EXECUTABLE_PROFILE_VERSION, FINALIZER_NODE_KIND, FINALIZER_NODE_PROFILE, TASK_NODE_KIND, TASK_NODE_PROFILE, } from '@x12i/graphenix-executable-contracts';
+function defaultExecutableModelConfig() {
+    return {
+        version: 'graph-model-config/v1',
+        cases: [
+            {
+                id: 'default',
+                modelConfig: {
+                    preActionModel: { kind: 'profileChoice', key: 'cheap/default' },
+                    skillModel: { kind: 'profileChoice', key: 'pro/default' },
+                    postActionModel: { kind: 'profileChoice', key: 'cheap/default' },
+                },
+            },
+        ],
+        fallbackPolicy: {
+            enabled: true,
+            allowedTriggers: [
+                'nodeSlotMissing',
+                'nodeModelUnavailable',
+                'nodeModelUnsupported',
+                'nodeProviderNotConfigured',
+                'nodeModelRateLimited',
+                'nodeModelTransientFailure',
+            ],
+            maxAttemptsPerSlot: 1,
+        },
+    };
+}
+function authoringShell(graphId, nodes, edges, graphResponseShape, extra) {
+    const taskNodes = nodes.filter((n) => n.kind === TASK_NODE_KIND);
+    const finalizer = nodes.find((n) => n.kind === FINALIZER_NODE_KIND);
+    return {
+        formatVersion: GRAPHENIX_FORMAT_VERSION,
+        id: graphId.startsWith('graph:') ? graphId : `graph:${graphId}`,
+        revision: '1.0.0',
+        name: graphId,
+        graph: {
+            nodes,
+            edges,
+            inputs: taskNodes.map((node) => ({
+                id: `graph-input:${node.id}`,
+                name: 'Input Record',
+                type: 'builtin:object',
+                target: { nodeId: node.id, portId: 'in:record' },
+                contract: { semanticKind: 'record', required: true, schema: { type: 'object' } },
+            })),
+            outputs: finalizer
+                ? [
+                    {
+                        id: 'graph-output:final',
+                        name: 'Final Output',
+                        type: 'builtin:object',
+                        source: { nodeId: finalizer.id, portId: 'out:final' },
+                        contract: { semanticKind: 'final-output', required: true, schema: { type: 'object' } },
+                    },
+                ]
+                : [],
+            metadata: {
+                graphResponse: { shape: graphResponseShape },
+                extensions: {
+                    [EXECUTABLE_PROFILE_NAMESPACE]: {
+                        profileVersion: EXECUTABLE_PROFILE_VERSION,
+                        modelConfig: defaultExecutableModelConfig(),
+                    },
+                },
+                ...extra,
+            },
+        },
+        types: [],
+    };
+}
+/** Single ai-task + select finalizer — mirrors legacy flat `buildAiTaskGraph` tests. */
+export function buildAiTaskAuthoringGraph(graphId) {
+    const taskId = 'ask-1';
+    const finalId = 'final';
+    const taskNode = {
+        id: taskId,
+        kind: TASK_NODE_KIND,
+        inputs: [{ id: 'in:record', direction: 'input', type: 'builtin:object', required: true }],
+        outputs: [{ id: 'out:answer', direction: 'output', type: 'builtin:object' }],
+        parameters: {
+            profile: TASK_NODE_PROFILE,
+            nodeType: 'task',
+            skillKey: 'professional-answer',
+            executionMapping: {
+                path: 'answers.ask1',
+                mode: 'replace',
+                map: { answer: 'output.answer' },
+            },
+            taskConfiguration: { executionStrategies: [] },
+        },
+    };
+    const finalizerNode = {
+        id: finalId,
+        kind: FINALIZER_NODE_KIND,
+        inputs: [{ id: 'in:answer', direction: 'input', type: 'builtin:object', required: true }],
+        outputs: [{ id: 'out:final', direction: 'output', type: 'builtin:object' }],
+        parameters: {
+            profile: FINALIZER_NODE_PROFILE,
+            nodeType: 'finalizer',
+            finalizerType: 'select',
+            inputs: {
+                answer: { type: 'executionMemoryPath', path: 'answers.ask1.answer' },
+            },
+            config: {
+                strategy: 'select',
+                selector: { type: 'firstPresent', order: ['answer'] },
+            },
+            outputMapping: {
+                path: 'answers.ask1',
+                mode: 'replace',
+                map: { answer: 'output.parsed' },
+            },
+        },
+    };
+    return authoringShell(graphId, [taskNode, finalizerNode], [{ id: 'edge:ask-final', from: { nodeId: taskId, portId: 'out:answer' }, to: { nodeId: finalId, portId: 'in:answer' } }], { answer: { type: 'outputsMemoryPath', path: 'answers.ask1.answer' } });
+}
+/** deterministic-rule local skill + select finalizer. */
+export function buildLocalSkillAuthoringGraph(graphId) {
+    const taskId = 'rule-1';
+    const finalId = 'final';
+    const taskNode = {
+        id: taskId,
+        kind: TASK_NODE_KIND,
+        inputs: [{ id: 'in:record', direction: 'input', type: 'builtin:object', required: true }],
+        outputs: [{ id: 'out:answer', direction: 'output', type: 'builtin:object' }],
+        parameters: {
+            profile: TASK_NODE_PROFILE,
+            nodeType: 'task',
+            skillKey: 'deterministic-rule',
+            taskConfiguration: {
+                rules: [{ id: 'always', condition: { all: [] }, output: { decision: 'go' } }],
+                firstMatchWins: true,
+            },
+            executionMapping: {
+                path: 'rule',
+                mode: 'replace',
+                map: { decision: 'output.output.decision' },
+            },
+        },
+    };
+    const finalizerNode = {
+        id: finalId,
+        kind: FINALIZER_NODE_KIND,
+        inputs: [{ id: 'in:answer', direction: 'input', type: 'builtin:object', required: true }],
+        outputs: [{ id: 'out:final', direction: 'output', type: 'builtin:object' }],
+        parameters: {
+            profile: FINALIZER_NODE_PROFILE,
+            nodeType: 'finalizer',
+            finalizerType: 'select',
+            inputs: {
+                decision: { type: 'executionMemoryPath', path: 'rule.decision' },
+            },
+            config: {
+                strategy: 'select',
+                selector: { type: 'firstPresent', order: ['decision'] },
+            },
+            outputMapping: {
+                path: 'rule',
+                mode: 'replace',
+                map: { decision: 'output.parsed' },
+            },
+        },
+    };
+    return authoringShell(graphId, [taskNode, finalizerNode], [{ id: 'edge:rule-final', from: { nodeId: taskId, portId: 'out:answer' }, to: { nodeId: finalId, portId: 'in:answer' } }], { decision: { type: 'outputsMemoryPath', path: 'rule.decision' } });
+}
+/** Fan-in Q&A graph used by graph.response mapping tests. */
+export function buildGraphResponseMappingAuthoringGraph(graphId) {
+    const q1 = 'q1';
+    const q2 = 'q2';
+    const finalId = 'final';
+    const makeTask = (id, path, question) => ({
+        id,
+        kind: TASK_NODE_KIND,
+        inputs: [{ id: 'in:record', direction: 'input', type: 'builtin:object', required: true }],
+        outputs: [{ id: 'out:answer', direction: 'output', type: 'builtin:object' }],
+        parameters: {
+            profile: TASK_NODE_PROFILE,
+            nodeType: 'task',
+            skillKey: 'professional-answer',
+            taskVariable: { question },
+            executionMapping: {
+                path: `answers.${path}`,
+                mode: 'replace',
+                map: { shortAnswer: 'output.parsed.shortAnswer' },
+            },
+            taskConfiguration: { executionStrategies: [] },
+        },
+    });
+    const finalizerNode = {
+        id: finalId,
+        kind: FINALIZER_NODE_KIND,
+        inputs: [
+            { id: 'in:q1', direction: 'input', type: 'builtin:object', required: true },
+            { id: 'in:q2', direction: 'input', type: 'builtin:object', required: true },
+        ],
+        outputs: [{ id: 'out:final', direction: 'output', type: 'builtin:object' }],
+        parameters: {
+            profile: FINALIZER_NODE_PROFILE,
+            nodeType: 'finalizer',
+            finalizerType: 'aggregate',
+            config: {
+                sections: [
+                    { sourceNodeId: q1, sourcePortId: 'out:answer', executionMemoryPath: 'answers.q1' },
+                    { sourceNodeId: q2, sourcePortId: 'out:answer', executionMemoryPath: 'answers.q2' },
+                ],
+            },
+        },
+    };
+    const doc = authoringShell(graphId, [makeTask(q1, 'q1', 'Q1?'), makeTask(q2, 'q2', 'Q2?'), finalizerNode], [
+        { id: 'edge:q1-final', from: { nodeId: q1, portId: 'out:answer' }, to: { nodeId: finalId, portId: 'in:q1' } },
+        { id: 'edge:q2-final', from: { nodeId: q2, portId: 'out:answer' }, to: { nodeId: finalId, portId: 'in:q2' } },
+    ], {
+        answers: {
+            type: 'firstPresent',
+            sources: [
+                {
+                    answer: {
+                        type: 'object',
+                        properties: {
+                            shortAnswer: { type: 'outputsMemoryPath', path: 'answers.q1.shortAnswer' },
+                        },
+                    },
+                },
+                {
+                    answer: {
+                        type: 'object',
+                        properties: {
+                            shortAnswer: { type: 'outputsMemoryPath', path: 'answers.q2.shortAnswer' },
+                        },
+                    },
+                },
+            ],
+        },
+    });
+    return doc;
+}
+export function withAuthoringGraphModelConfig(doc, modelConfig) {
+    const next = structuredClone(doc);
+    const metadata = next.graph.metadata;
+    if (!metadata?.extensions)
+        return next;
+    const profile = metadata.extensions[EXECUTABLE_PROFILE_NAMESPACE];
+    if (profile && typeof profile === 'object') {
+        Object.assign(profile, { modelConfig });
+    }
+    return next;
+}

package/dist/testkit/buildExecuteGraphInput.d.ts

@@ -1,4 +1,4 @@
-import type { Graph, GraphModelObject } from '../src/types/refs.js';
+import type { AuthoringGraphDocument } from '@x12i/graphenix-executable-contracts';
 import type { ExecuteGraphInput, GraphRuntimeObject } from '../src/runtime/ExellixGraphRuntime.js';
-/** Builds `{ plan, runtime }` for tests and hosts that still author exellix GraphModelObject JSON. */
-export declare function buildExecuteGraphInput(model: Graph | GraphModelObject, runtime: GraphRuntimeObject): ExecuteGraphInput;
+/** Builds `{ plan, runtime }` for tests and hosts with a Graphenix 2.x {@link AuthoringGraphDocument}. */
+export declare function buildExecuteGraphInput(doc: AuthoringGraphDocument | Record<string, unknown>, runtime: GraphRuntimeObject): ExecuteGraphInput;

package/dist/testkit/buildExecuteGraphInput.js

@@ -1,8 +1,12 @@
-import { compileExellixExecutablePlan } from '../src/adapters/compileExellixExecutablePlan.js';
-/** Builds `{ plan, runtime }` for tests and hosts that still author exellix GraphModelObject JSON. */
-export function buildExecuteGraphInput(model, runtime) {
+import { compileExellixExecutablePlan } from '../src/compile/compileExellixExecutablePlan.js';
+import { flatTestGraphToAuthoringDocument, isAuthoringGraphDocument } from './flatGraphToAuthoring.js';
+function normalizeAuthoringDocument(input) {
+    return isAuthoringGraphDocument(input) ? input : flatTestGraphToAuthoringDocument(input);
+}
+/** Builds `{ plan, runtime }` for tests and hosts with a Graphenix 2.x {@link AuthoringGraphDocument}. */
+export function buildExecuteGraphInput(doc, runtime) {
     return {
-        plan: compileExellixExecutablePlan(model, runtime),
+        plan: compileExellixExecutablePlan(normalizeAuthoringDocument(doc), runtime),
         runtime,
     };
 }

package/dist/testkit/flatGraphToAuthoring.d.ts

@@ -0,0 +1,29 @@
+import type { AuthoringGraphDocument } from '@x12i/graphenix-executable-contracts';
+export declare function isAuthoringGraphDocument(v: unknown): v is AuthoringGraphDocument;
+export declare function defaultExecutableModelConfig(): {
+    version: "graph-model-config/v1";
+    cases: {
+        id: string;
+        modelConfig: {
+            preActionModel: {
+                kind: "profileChoice";
+                key: string;
+            };
+            skillModel: {
+                kind: "profileChoice";
+                key: string;
+            };
+            postActionModel: {
+                kind: "profileChoice";
+                key: string;
+            };
+        };
+    }[];
+    fallbackPolicy: {
+        enabled: boolean;
+        allowedTriggers: readonly ["nodeSlotMissing", "nodeModelUnavailable", "nodeModelUnsupported", "nodeProviderNotConfigured", "nodeModelRateLimited", "nodeModelTransientFailure"];
+        maxAttemptsPerSlot: number;
+    };
+};
+/** Converts legacy flat exellix test graphs into Graphenix 2.x {@link AuthoringGraphDocument}. */
+export declare function flatTestGraphToAuthoringDocument(flat: Record<string, unknown>): AuthoringGraphDocument;