@exellix/graph-engine 7.8.1 → 8.0.0

package/dist/src/runtime/ExellixGraphRuntime.js

@@ -1,3 +1,10 @@
+import { createExecutionTrace, appendExecutionEvent, validateExecutionTrace } from "@x12i/graphenix-trace-format";
+import { preparePlanExecuteEntry, computePlanAudit } from "../plan/planExecuteEntry.js";
+import { embeddedGraphToExellixGraph } from "../plan/embeddedGraphToExellixGraph.js";
+import { graphAiModelConfigFromFinalizerPlan, graphAiModelConfigFromNodePlan } from "../plan/planModelConfig.js";
+import { executionPipelineFromNodePlan } from "../plan/planExecutionPipeline.js";
+import { applyNodePlanInvoke, finalizerPlanForId, nodePlanForId } from "../plan/applyNodePlanInvoke.js";
+import { evaluateDeferredNodeGate, evaluateDeferredEdgeGate, nodeDeferredGate, hasPlanConditionalEdges, evaluatePlanEntryGates, planNeedsRunx, } from "../plan/planDeferredGates.js";
 import { mergeExecutionObject, copyExecutionContextFields, } from "./memory.js";
 import { buildAiTasksRunTaskRequest, extractRunTaskStrategyOverrides, resolveJobTypeId, } from "./buildAiTasksRunTaskRequest.js";
 import { runTaskResponseSucceeded } from "./runTaskResponse.js";
@@ -16,11 +23,9 @@ import { resolveNarrixForTaskNode } from "./resolveNarrixForTaskNode.js";
 import { assertFinalizerRequiredReadsResolvable, validateGraphFinalizer, } from "./finalizers/validateFinalizer.js";
 import { executeDeterministicFinalizer, executeSynthesizeFinalizer } from "./finalizers/executeFinalizer.js";
 import { createFinalizerError } from "./finalizers/errors.js";
-import { assertCanonicalGraphDocument } from "./validateCanonicalGraphDocument.js";
 import { assertCanonicalGraphRuntimeObject } from "./validateCanonicalGraphRuntime.js";
 import { applyGraphResponseDefinition } from "./graphResponseMapping.js";
 import { migrateLegacyGraphResponse } from "./graphResponseMigration.js";
-import { computeGraphDocumentContentSha256 } from "./graphDocumentFingerprint.js";
 import { buildAiTasksObservabilityRecord } from "./aiTasksObservability.js";
 import { buildMainLlmCallForRunTask, buildRunTaskIdentityEnvelope, shouldForwardRunTaskTraceMode, } from "./runTaskAugments.js";
 import { buildRunLog, extractLogxerCorrelationFromMetadata, extractTaskRunLogFromMetadata, resolveRunLogLimits, } from "./buildRunLog.js";
@@ -33,9 +38,6 @@ import { buildPredicateEvalContextForNode, mirrorTaskVariablesOnExecution, readE
 import { mergeExellixGraphRuntimeInvocation } from "./mergeExellixGraphRuntimeInvocation.js";
 import { resolveStepRetryPolicy, runRunTaskWithRetry } from "./stepRetry.js";
 import { isLocalSkillKey, runScopedDataReader, runDeterministicRule, runScopedAnswerWriter, runScopedAnswerAssembler, } from "./localSkills/index.js";
-import { evaluateGraphPredicate } from "./predicates.js";
-import { evaluateStructuredDataFilters } from "./dataFiltersEvaluation.js";
-import { evaluateTaskNodeConditions } from "./taskNodeConditionsEvaluation.js";
 import { resolveModelConfigForNode } from "./resolveModelConfigForNode.js";
 import { toRunTaskModelConfig } from "./graphAiModelConfig.js";
 import { isGraphAiModelConfig } from "./modelConfigSelection.js";
@@ -963,8 +965,10 @@ export function createExellixGraphRuntime(opts) {
             const resMeta = res.metadata ?? res.meta;
             const taskRunLog = [...retryOutcome.syntheticRunLog, ...extractTaskRunLogFromMetadata(resMeta)];
             const logxerCorrelationId = extractLogxerCorrelationFromMetadata(resMeta);
-            const err = new Error(`TASK_RUN_FAILED: ${skillKey}`);
-            err.code = res.error?.code ?? "TASK_RUN_FAILED";
+            const taskErrorMessage = res.error?.message ?? "Task run failed";
+            const taskErrorCode = res.error?.code ?? "TASK_RUN_FAILED";
+            const err = new Error(taskErrorMessage);
+            err.code = taskErrorCode;
             err.skillKey = skillKey;
             err.diagnostics = res.diagnostics;
             err.nodeId = input.node?.id;
@@ -1153,36 +1157,45 @@ export function createExellixGraphRuntime(opts) {
         };
     }
     async function executeGraph(input) {
-        const { model: suppliedGraph, runtime } = input;
-        const { graph } = migrateLegacyGraphResponse(suppliedGraph);
+        const { plan: suppliedPlan, runtime } = input;
+        const { plan } = preparePlanExecuteEntry(suppliedPlan, runtime);
+        const materialized = embeddedGraphToExellixGraph(plan);
+        const graph = migrateLegacyGraphResponse(materialized).graph;
         const merged = mergeExellixGraphRuntimeInvocation(runtime, opts);
-        const failFast = merged.failFast;
+        const scheduling = plan.schedulingPolicy;
+        const plannerMode = scheduling?.mode ?? runtime.mode;
+        const plannerGoalNodeId = scheduling?.goalNodeId ?? runtime.goalNodeId;
+        const failFast = scheduling?.failFast ?? merged.failFast;
         const debugMode = runtime.debugMode === true;
         const eventEmitter = runtime.eventEmitter ?? opts.eventEmitter;
         const jobId = assertHostJobId(runtime.jobId);
         const graphTaskId = newGraphRunTaskId();
         const job = { ...(runtime.job ?? {}), id: jobId, jobId };
-        if (runtime.mode === "backward" && !runtime.goalNodeId) {
+        if (plannerMode === "backward" && !plannerGoalNodeId) {
             const err = new Error(`BACKWARD_GOAL_REQUIRED: mode=backward requires goalNodeId`);
             err.code = "BACKWARD_GOAL_REQUIRED";
             throw err;
         }
-        const resolvedGraphIdRaw = graph?.id;
-        if (resolvedGraphIdRaw == null || resolvedGraphIdRaw === '') {
-            throw new Error('GRAPH_ID_REQUIRED: execution request model must include a non-empty id');
-        }
-        const resolvedGraphId = String(resolvedGraphIdRaw);
+        const resolvedGraphId = String(plan.source.graphId);
         const runLogxer = createGraphEngineLogxer({ logging: merged.logging });
+        const executionTrace = createExecutionTrace(plan, runtime);
+        appendExecutionEvent(executionTrace, {
+            id: `evt:${graphTaskId}:graph.started`,
+            ts: new Date().toISOString(),
+            level: "info",
+            type: "graph.started",
+            message: "Graph execution started.",
+        });
+        const planAudit = computePlanAudit(plan);
         return runWithAiTasksStackLogging(merged.logging, () => runGraphWithLogContext({ jobId, taskId: graphTaskId, graphId: resolvedGraphId, runId: graphTaskId }, async () => {
             bindGraphEngineRunLogxer(runLogxer);
             try {
-                assertCanonicalGraphDocument(graph, { jobId, graphId: resolvedGraphId }, { mode: 'execute' });
                 assertCanonicalGraphRuntimeObject(runtime, { jobId, graphId: resolvedGraphId });
                 let runxClient = opts.runx;
-                if (graphNeedsRunxClient(graph)) {
+                if (planNeedsRunx(plan)) {
                     if (!runxClient) {
                         if (!opts.runxCreateOptions) {
-                            const err = new Error("RUNX_REQUIRED: graph uses jsConditionFunction, aiCondition, or conditional modelConfig cases that require runx. Pass runx or runxCreateOptions on createExellixGraphRuntime.");
+                            const err = new Error("RUNX_REQUIRED: executable plan deferred gates require runx. Pass runx or runxCreateOptions on createExellixGraphRuntime.");
                             err.code = "RUNX_REQUIRED";
                             throw err;
                         }
@@ -1196,10 +1209,6 @@ export function createExellixGraphRuntime(opts) {
                         await runxClient.reload();
                     }
                 }
-                const graphAudit = {
-                    source: 'model',
-                    contentSha256: computeGraphDocumentContentSha256(suppliedGraph),
-                };
                 const graphDocumentModel = mergeGraphDocumentModel(graph);
                 const graphExecution = graphDocumentModel.graphExecution;
                 const nodeResponseKeys = resolveNodeResponseKeys(graphExecution);
@@ -1213,8 +1222,8 @@ export function createExellixGraphRuntime(opts) {
                 const { finalizer } = validateGraphFinalizer(graph);
                 const engine = opts.engineFactory.create({
                     graph,
-                    mode: runtime.mode,
-                    goalNodeId: runtime.goalNodeId,
+                    mode: plannerMode,
+                    goalNodeId: plannerGoalNodeId,
                     dimension: runtime.dimension,
                     initialState: runtime.initialState,
                     initialVariables: runtime.initialVariables,
@@ -1224,19 +1233,15 @@ export function createExellixGraphRuntime(opts) {
                 const errors = [];
                 const finalizerNodeId = String(finalizer.id);
                 const jobCorrelation = job?.jobType != null ? { jobType: job.jobType } : undefined;
-                // Pre-compute incoming-edge map for conditional-edge filtering of plan.nextNodes.
-                const rawEdges = Array.isArray(graph.edges) ? graph.edges : [];
-                const hasConditionalEdges = rawEdges.some((e) => e && typeof e === "object" && e.when != null);
+                const hasConditionalEdges = hasPlanConditionalEdges(plan);
                 const incomingByTo = new Map();
                 if (hasConditionalEdges) {
-                    for (const e of rawEdges) {
-                        if (!e || typeof e !== "object")
-                            continue;
-                        const to = e.to;
+                    for (const edgeRef of plan.topology.edges) {
+                        const to = edgeRef.to.nodeId;
                         if (typeof to !== "string" || to.length === 0)
                             continue;
                         const list = incomingByTo.get(to) ?? [];
-                        list.push(e);
+                        list.push(edgeRef);
                         incomingByTo.set(to, list);
                     }
                 }
@@ -1395,50 +1400,67 @@ export function createExellixGraphRuntime(opts) {
                         ? currentExecution.input
                         : {};
                 }
-                const graphEntryForGate = graphDocumentModel.graphEntry;
-                if (graphEntryForGate?.dataFilters !== undefined) {
-                    const entryEv = evaluateStructuredDataFilters(graphEntryForGate.dataFilters, recordForStructuredDataFilters());
-                    if (entryEv.status === "unsupported_shape" ||
-                        (entryEv.status === "evaluated" && !entryEv.ok)) {
-                        const err = new Error("GRAPH_ENTRY_DATA_FILTERS_REJECTED: metadata.graphEntry.dataFilters (structured) did not accept runtime.executionMemory.input");
-                        err.code = ExellixGraphErrorCode.GRAPH_ENTRY_DATA_FILTERS_REJECTED;
-                        logGraphEngineErrorCode(ExellixGraphErrorCode.GRAPH_ENTRY_DATA_FILTERS_REJECTED, err.message, {
-                            graphId: resolvedGraphId,
-                            jobId,
-                            taskId: graphTaskId,
-                            error: err,
-                        });
-                        const finalOutput = buildFinalOutputFromGraphResponse();
-                        const result = {
-                            jobId,
-                            taskId: graphTaskId,
-                            graphId: resolvedGraphId,
-                            status: "failed",
-                            outputsByNodeId,
-                            stepsResponses,
-                            engineSnapshot: engine.snapshot(),
-                            ...(finalOutput !== undefined ? { finalOutput } : {}),
-                            errors: [...errors, { error: err }],
-                            graphAudit,
-                            ...finalizeGraphPayload("failed"),
-                        };
-                        const debug = buildDebugTrace();
-                        if (debug)
-                            result.debug = debug;
-                        if (eventEmitter) {
-                            eventEmitter.emit(createGraphFailEvent(jobId, resolvedGraphId, graphTaskId, err, {
-                                finalMemory: { jobMemory: currentJobMemory, taskMemory: currentTaskMemory, execution: currentExecution, outputsMemory: currentOutputsMemory },
-                                ...(jobCorrelation ?? {}),
-                            }));
-                        }
-                        return result;
+                const entryGateEv = await evaluatePlanEntryGates(plan.deferredGates.entryGates, recordForStructuredDataFilters(), {
+                    executionMemory: currentExecution,
+                    jobMemory: currentJobMemory,
+                    taskMemory: currentTaskMemory,
+                    job,
+                }, runxClient);
+                if (!entryGateEv.ok) {
+                    const err = new Error("GRAPH_ENTRY_DATA_FILTERS_REJECTED: plan entry gates rejected runtime.executionMemory.input");
+                    err.code = ExellixGraphErrorCode.GRAPH_ENTRY_DATA_FILTERS_REJECTED;
+                    logGraphEngineErrorCode(ExellixGraphErrorCode.GRAPH_ENTRY_DATA_FILTERS_REJECTED, err.message, {
+                        graphId: resolvedGraphId,
+                        jobId,
+                        taskId: graphTaskId,
+                        error: err,
+                    });
+                    const finalOutput = buildFinalOutputFromGraphResponse();
+                    appendExecutionEvent(executionTrace, {
+                        id: `evt:${graphTaskId}:graph.failed`,
+                        ts: new Date().toISOString(),
+                        level: "error",
+                        type: "graph.failed",
+                        message: err.message,
+                    });
+                    const result = {
+                        jobId,
+                        taskId: graphTaskId,
+                        graphId: resolvedGraphId,
+                        status: "failed",
+                        outputsByNodeId,
+                        stepsResponses,
+                        engineSnapshot: engine.snapshot(),
+                        ...(finalOutput !== undefined ? { finalOutput } : {}),
+                        errors: [...errors, { error: err }],
+                        planAudit,
+                        trace: executionTrace,
+                        ...finalizeGraphPayload("failed"),
+                    };
+                    const debug = buildDebugTrace();
+                    if (debug)
+                        result.debug = debug;
+                    if (eventEmitter) {
+                        eventEmitter.emit(createGraphFailEvent(jobId, resolvedGraphId, graphTaskId, err, {
+                            finalMemory: { jobMemory: currentJobMemory, taskMemory: currentTaskMemory, execution: currentExecution, outputsMemory: currentOutputsMemory },
+                            ...(jobCorrelation ?? {}),
+                        }));
                     }
+                    return result;
                 }
                 while (true) {
-                    const plan = engine.plan();
-                    if (plan.status === "completed") {
+                    const wavePlan = engine.plan();
+                    if (wavePlan.status === "completed") {
                         const graphStatus = errors.length ? "failed" : "completed";
                         const finalOutput = buildFinalOutputFromGraphResponse();
+                        appendExecutionEvent(executionTrace, {
+                            id: `evt:${graphTaskId}:graph.${graphStatus}`,
+                            ts: new Date().toISOString(),
+                            level: graphStatus === "completed" ? "info" : "error",
+                            type: graphStatus === "completed" ? "graph.completed" : "graph.failed",
+                            message: `Graph execution ${graphStatus}.`,
+                        });
+                        validateExecutionTrace(executionTrace, plan);
                         const result = {
                             jobId,
                             taskId: graphTaskId,
@@ -1450,7 +1472,8 @@ export function createExellixGraphRuntime(opts) {
                             ...(finalOutput !== undefined ? { finalOutput } : {}),
                             ...(errors.length === 0 ? { finalizerNodeId, finalizerType: finalizer.finalizerType } : {}),
                             errors: errors.length ? errors : undefined,
-                            graphAudit,
+                            planAudit,
+                            trace: executionTrace,
                             ...finalizeGraphPayload(graphStatus),
                         };
                         const debug = buildDebugTrace();
@@ -1474,8 +1497,8 @@ export function createExellixGraphRuntime(opts) {
                         }
                         return result;
                     }
-                    if (plan.status !== "continue") {
-                        const err = new Error(`GRAPH_BLOCKED: status=${plan.status}`);
+                    if (wavePlan.status !== "continue") {
+                        const err = new Error(`GRAPH_BLOCKED: status=${wavePlan.status}`);
                         err.code = "GRAPH_BLOCKED";
                         const finalOutput = buildFinalOutputFromGraphResponse();
                         const result = {
@@ -1488,7 +1511,8 @@ export function createExellixGraphRuntime(opts) {
                             engineSnapshot: engine.snapshot(),
                             ...(finalOutput !== undefined ? { finalOutput } : {}),
                             errors: [...errors, { error: err }],
-                            graphAudit,
+                            planAudit,
+                            trace: executionTrace,
                             ...finalizeGraphPayload("failed"),
                         };
                         const debug = buildDebugTrace();
@@ -1502,7 +1526,7 @@ export function createExellixGraphRuntime(opts) {
                         }
                         return result;
                     }
-                    let runnableNodes = plan.nextNodes ?? [];
+                    let runnableNodes = wavePlan.nextNodes ?? [];
                     // Conditional edge filtering: a node with incoming edges that are *all* conditional must
                     // have at least one incoming edge whose `when` evaluates true to be runnable this round.
                     // Roots and nodes with at least one unconditional incoming edge always pass through.
@@ -1519,7 +1543,7 @@ export function createExellixGraphRuntime(opts) {
                             const incoming = incomingByTo.get(id) ?? [];
                             if (incoming.length === 0)
                                 return true;
-                            const hasUnconditional = incoming.some((e) => e?.when == null);
+                            const hasUnconditional = incoming.some((e) => !e?.hasDeferredGate);
                             if (hasUnconditional)
                                 return true;
                             const planningContext = buildPredicateEvalContextForNode({
@@ -1529,7 +1553,10 @@ export function createExellixGraphRuntime(opts) {
                                 node: n,
                                 runtimeTaskVariables: runtime.taskVariables,
                             });
-                            return incoming.some((e) => evaluateGraphPredicate(e.when, planningContext));
+                            return incoming.some((edgeRef) => {
+                                const gate = plan.deferredGates.edgeGates[edgeRef.edgeId];
+                                return evaluateDeferredEdgeGate(gate, planningContext);
+                            });
                         });
                     }
                     const dataFiltersRecord = recordForStructuredDataFilters();
@@ -1553,7 +1580,7 @@ export function createExellixGraphRuntime(opts) {
                             node: n,
                             runtimeTaskVariables: runtime.taskVariables,
                         });
-                        const condEv = await evaluateTaskNodeConditions(n.conditions, { ...conditionCtxBase, ...nodePredicateCtx }, dataFiltersRecord, { runx: runxClient });
+                        const condEv = await evaluateDeferredNodeGate(nodeDeferredGate(plan, String(n.id)), { ...conditionCtxBase, ...nodePredicateCtx }, dataFiltersRecord, runxClient);
                         if (!condEv.ok) {
                             skippedByConditions.push({
                                 node: n,
@@ -1603,27 +1630,32 @@ export function createExellixGraphRuntime(opts) {
                                 context: { model: graph, runtime, graphId: resolvedGraphId, jobId, taskId: graphTaskId, node: node },
                             });
                             const nodeTaskMemory = isPlainRecord(currentTaskMemory) ? { ...currentTaskMemory } : currentTaskMemory;
-                            const effectiveModelConfig = await resolveModelConfigForNode({
-                                nodeModelConfig: node.taskConfiguration?.modelConfig,
-                                graphModelConfig: graph.modelConfig,
-                                conditionCtx: buildPredicateEvalContextForNode({
-                                    executionMemory: currentExecution,
-                                    jobMemory: currentJobMemory,
-                                    taskMemory: currentTaskMemory,
-                                    node: node,
-                                    runtimeTaskVariables: runtime.taskVariables,
-                                }),
-                                executionInput: dataFiltersRecord,
-                                runx: runxClient,
-                                graphId: resolvedGraphId,
-                                nodeId: typeof node.id === "string" ? node.id : String(node.id),
-                                jobId,
+                            const nodeIdStr = String(node.id);
+                            appendExecutionEvent(executionTrace, {
+                                id: `evt:${graphTaskId}:node.started:${nodeIdStr}`,
+                                ts: new Date().toISOString(),
+                                level: "info",
+                                type: "node.started",
+                                nodeId: nodeIdStr,
                             });
+                            const nodePlanEntryResolved = nodePlanForId(plan, nodeIdStr);
+                            const finalizerPlanEntryResolved = node.type === "finalizer"
+                                ? finalizerPlanForId(plan, nodeIdStr)
+                                : undefined;
+                            const taskNodeForExecute = nodePlanEntryResolved && node.type !== "finalizer"
+                                ? applyNodePlanInvoke(node, nodePlanEntryResolved)
+                                : node;
+                            const effectiveModelConfig = finalizerPlanEntryResolved != null
+                                ? graphAiModelConfigFromFinalizerPlan(finalizerPlanEntryResolved)
+                                : nodePlanEntryResolved && node.type !== "finalizer"
+                                    ? graphAiModelConfigFromNodePlan(nodePlanEntryResolved)
+                                    : undefined;
+                            const nodeExecutionPipeline = nodePlanEntryResolved != null ? executionPipelineFromNodePlan(nodePlanEntryResolved) : undefined;
                             const r = await executeNode({
                                 graphId: resolvedGraphId,
                                 graph,
                                 graphRunTaskId: graphTaskId,
-                                node,
+                                node: taskNodeForExecute,
                                 job,
                                 jobMemory: currentJobMemory,
                                 taskMemory: nodeTaskMemory,
@@ -1637,7 +1669,7 @@ export function createExellixGraphRuntime(opts) {
                                 runTaskIdentity: merged.runTaskIdentity,
                                 runTaskExecutionMode: merged.runTaskExecutionMode,
                                 runTaskDiagnostics: merged.runTaskDiagnostics,
-                                graphExecutionPipeline: merged.executionPipeline,
+                                graphExecutionPipeline: nodeExecutionPipeline ?? merged.executionPipeline,
                                 skillKeyResolution: merged.skillKeyResolution,
                                 nodeTimeoutMs: merged.nodeTimeoutMs,
                                 clearSynthesizedContextPerNode: merged.clearSynthesizedContextPerNode,
@@ -1649,6 +1681,13 @@ export function createExellixGraphRuntime(opts) {
                             outputsByNodeId[r.nodeId] = r.output;
                             appendStepResponse(node, r.output);
                             engine.commit({ nodeId: r.nodeId, output: r.output });
+                            appendExecutionEvent(executionTrace, {
+                                id: `evt:${graphTaskId}:node.completed:${nodeIdStr}`,
+                                ts: new Date().toISOString(),
+                                level: "info",
+                                type: "node.completed",
+                                nodeId: nodeIdStr,
+                            });
                             const trl = r.taskRunLog;
                             if (trl?.length)
                                 taskRunLogBuffer.push(...trl);
@@ -1720,7 +1759,8 @@ export function createExellixGraphRuntime(opts) {
                             engineSnapshot: engine.snapshot(),
                             ...(finalOutput !== undefined ? { finalOutput } : {}),
                             errors,
-                            graphAudit,
+                            planAudit,
+                            trace: executionTrace,
                             ...finalizeGraphPayload("failed"),
                         };
                         const debug = buildDebugTrace();

package/dist/src/runtime/executionMatrixHost.js

@@ -5,6 +5,7 @@
  * a `{ model, runtime }` request with per-graph `GraphEntryContract` + seeded
  * `runtime.executionMemory` objects built here.
  */
+import { compileExellixExecutablePlan } from '../adapters/compileExellixExecutablePlan.js';
 import { mergeGraphDocumentModel } from '../types/refs.js';
 import { createExellixGraphRuntime } from './ExellixGraphRuntime.js';
 import { selectByPath, writeByPath } from './pathExpr.js';
@@ -76,7 +77,7 @@ export function buildExecutionSeedFromGraphEntry(graphEntry, sources = {}) {
 /** Builds the canonical graph-engine execution request for matrix-style hosts. */
 export function buildGraphExecutionRequest(input) {
     return {
-        model: input.model,
+        plan: compileExellixExecutablePlan(input.model, input.runtime),
         runtime: input.runtime,
     };
 }

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

@@ -0,0 +1,51 @@
+import type { Graph } from '../types/refs.js';
+import type { ExecuteGraphInput, GraphRuntimeObject } 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.
+ */
+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;
+};
+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;
+    graphId?: string;
+}): asserts request is StudioGraphExecuteRequest;
+export type BuildGraphExecutionRequestFromStudioExecuteOptions = {
+    agentId?: string;
+    jobTypeId?: string;
+};
+/**
+ * Maps a validated studio execute envelope to {@link ExecuteGraphInput}.
+ * Does not read or merge removed request-level model defaults — graph.modelConfig is authoritative.
+ */
+export declare function buildGraphExecutionRequestFromStudioExecute(request: StudioGraphExecuteRequest, options?: BuildGraphExecutionRequestFromStudioExecuteOptions): ExecuteGraphInput;

package/dist/src/runtime/studioGraphExecuteRequest.js

@@ -0,0 +1,78 @@
+import { compileExellixExecutablePlan } from '../adapters/compileExellixExecutablePlan.js';
+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.
+ */
+export const STUDIO_GRAPH_EXECUTE_REMOVED_KEYS = ['graphDefaultModel'];
+function isPlainObject(v) {
+    return v != null && typeof v === 'object' && !Array.isArray(v);
+}
+export function getStudioGraphExecuteRemovedKeyViolations(request) {
+    if (!isPlainObject(request))
+        return [];
+    return STUDIO_GRAPH_EXECUTE_REMOVED_KEYS.filter((key) => Object.prototype.hasOwnProperty.call(request, key));
+}
+/**
+ * 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 });
+    }
+    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 });
+    }
+}
+/**
+ * Maps a validated studio execute envelope to {@link ExecuteGraphInput}.
+ * Does not read or merge removed request-level model defaults — graph.modelConfig is authoritative.
+ */
+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,
+    };
+}

package/dist/testkit/buildExecuteGraphInput.d.ts

@@ -0,0 +1,4 @@
+import type { Graph, GraphModelObject } from '../src/types/refs.js';
+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;

package/dist/testkit/buildExecuteGraphInput.js

@@ -0,0 +1,8 @@
+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) {
+    return {
+        plan: compileExellixExecutablePlan(model, runtime),
+        runtime,
+    };
+}

package/dist/testkit/index.d.ts

@@ -2,4 +2,5 @@ export { InMemoryGraphLoader } from './inMemoryGraphLoader.js';
 export { DepGraphEngineFactory } from './depGraphEngineFactory.js';
 export { RealTasksClient } from './RealTasksClient.js';
 export { createTestExellixGraphRuntime } from './testModelAliasRuntime.js';
+export { buildExecuteGraphInput } from './buildExecuteGraphInput.js';
 export { tryLoadExellixAiTasksRuntimeSubtree, loadExellixGraphRuntimeObjects, } from './exellixRuntimeObjects.js';

package/dist/testkit/index.js

@@ -2,4 +2,5 @@ export { InMemoryGraphLoader } from './inMemoryGraphLoader.js';
 export { DepGraphEngineFactory } from './depGraphEngineFactory.js';
 export { RealTasksClient } from './RealTasksClient.js';
 export { createTestExellixGraphRuntime } from './testModelAliasRuntime.js';
+export { buildExecuteGraphInput } from './buildExecuteGraphInput.js';
 export { tryLoadExellixAiTasksRuntimeSubtree, loadExellixGraphRuntimeObjects, } from './exellixRuntimeObjects.js';

package/dist/testkit/testModelAliasRuntime.js

@@ -9,12 +9,12 @@ export function createTestExellixGraphRuntime(opts) {
         const base = input.runtime ?? {};
         const jobId = typeof base.jobId === 'string' && base.jobId.trim() !== ''
             ? base.jobId
-            : `job-${input.model.id ?? 'graph'}`;
+            : `job-${input.plan.source.graphId}`;
         const job = base.job != null && typeof base.job === 'object'
             ? base.job
             : { agentId: 'test-agent', jobType: 'unit-test' };
         return executeGraph({
-            ...input,
+            plan: input.plan,
             runtime: { ...base, jobId, job },
         });
     };