@exellix/graph-engine 8.0.0 → 8.1.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 8.1.0
+
+### Breaking
+
+- **`compileExellixExecutablePlan` input is `AuthoringGraphDocument` only** — removed `migrateLegacyGraphModelObjectToGraphenixExecutable` re-export and all legacy migration hooks. Compile = `validateAuthoringGraph` → `compileExecutablePlanV2` → `validateExecutablePlanV2`.
+- **`buildGraphExecutionRequest` (matrix host)** now takes `{ doc: AuthoringGraphDocument, runtime }` instead of `{ model: GraphModelObject, runtime }`.
+- Studio execute adapter delegates to `@x12i/graphenix-execute-envelope` ^1.1.0 (authoring graph on the wire).
+
+### Changed
+
+- Dependency floor: `@x12i/graphenix-*` ^1.1.0 for authoring-format, plan-compiler, executable-contracts, execute-envelope, plan-format.
+
+## 8.0.2
+
+### Changed
+
+- **No legacy compile fixups:** removed `preprocessLegacy` / `migrateLegacyGraphResponse`. `compileExellixExecutablePlan` runs `assertCanonicalGraphDocument` first; graphs must declare root `response` (fix in studio/CI, not at compile).
+
+## 8.0.1
+
+### Changed
+
+- **Zero local compile workarounds:** removed local migration/finalizer patches; `compileExellixExecutablePlan` uses `@x12i/graphenix-authoring-format` ≥1.0.2 and `@x12i/graphenix-plan-compiler` ≥1.0.1 only.
+- Re-export `migrateLegacyGraphModelObjectToGraphenixExecutable` from authoring-format (upstream name; no exellix alias).
+- **Docs / layout:** compile helper lives under `src/compile/`; execute path no longer runs response migration (compile-only).
+
 ## 8.0.0
 
 ### Breaking
@@ -11,7 +37,7 @@
 ### Added
 
 - **`@x12i/graphenix-*` integration:** plan validation, deferred gates, trace events (`ExecuteGraphResult.trace`), and exports for `ExecutableGraphPlanV2`.
-- **`compileExellixExecutablePlan`**, **`migrateExellixGraphModelToAuthoring`** — host compile helpers for legacy exellix `GraphModelObject`.
+- **`compileExellixExecutablePlan`**, **`migrateLegacyGraphModelObjectToGraphenixExecutable`** (re-export from `@x12i/graphenix-authoring-format`) — host compile helpers for legacy exellix `GraphModelObject`.
 - **`buildAuthoringStudioGraphExecutionRequest`** re-export from `@x12i/graphenix-execute-envelope`.
 
 See [`BREAKING-CHANGES.md`](BREAKING-CHANGES.md) §8.0.0.

package/README.md

@@ -43,7 +43,7 @@ The **`runTask`** wire contract (identity, canonical **`input`**, optional extra
 
 An executable graph model object may have **only** these **top-level** keys: `id`, `version`, `modelConfig`, `jobKnowledge`, `nodes`, `edges`, `variables`, `response`, `metadata`. The required root **`response`** is the single executable final response contract used to build `ExecuteGraphResult.finalOutput`. Document-model and authoring fields (`name`, `description`, `exellixContractTarget`, `graphExecution`, `graphEntry`, `catalogRequests`, and similar) belong **under `metadata`** only. Node-scoped `taskKnowledge` belongs under each task node, not at the model root. Runtime state (`input`, `jobMemory`, `taskMemory`, `executionMemory`, `outputsMemory`, per-run options) belongs under the execution request’s **`runtime`** object and is rejected on the model. **`runtime.modelConfig`**, **`runtime.aliasConfig`**, and **`runtime.nodes[id].modelConfig`** were removed in **7.7** — model profiles belong on the graph document only.
 
-`metadata.graphExecution` can document graph execution defaults and labels, including `mode: 'forward' | 'backward' | 'hybrid'`, optional `goalNodeId`, optional `dimension`, `outputMode: 'mappedAggregation' | 'lastExitNode'`, `coreObjective`, optional `nodesResponses`, and metadata-only `flowOutline: 'linearSequence' | 'convergingParallelFlow'`. Planner mode still comes from `executeGraph({ model, runtime }).runtime.mode`; `outputMode` does not decide the returned `finalOutput`.
+`metadata.graphExecution` can document graph execution defaults and labels, including `mode: 'forward' | 'backward' | 'hybrid'`, optional `goalNodeId`, optional `dimension`, `outputMode: 'mappedAggregation' | 'lastExitNode'`, `coreObjective`, optional `nodesResponses`, and metadata-only `flowOutline: 'linearSequence' | 'convergingParallelFlow'`. Planner mode comes from `plan.schedulingPolicy.mode` or `runtime.mode`; `outputMode` does not decide the returned `finalOutput`.
 
 Enforcement: `executeGraph`, `createExellixGraphRuntime().executeGraph`, `executeNode` when a graph is passed in context, `inspectGraph`, `inspectGraphContracts`, `validateCatalogPlanning`, and Catalox graph validators call this check. Failures throw `ExellixGraphError` with code `NON_CANONICAL_GRAPH_DOCUMENT`. For CI or custom loaders, call **`assertCanonicalGraphDocument`** (exported from the package root) on parsed JSON before execution. **`loadGraph`** returns whatever the loader parsed; validation runs when you execute or inspect, not necessarily on load.
 
@@ -57,7 +57,7 @@ npm install @exellix/graph-engine
 
 ### Execution matrix hosts (`@exellix/exellix-runtime`) — documentation only for the engine
 
-Matrix **claim**, **rows**, and **retry policy** live outside this package. If your host wires **matrix → graph run**, see [.docs/execution-matrix-handoff.md](.docs/execution-matrix-handoff.md) for how **you** should inject `runtime.executeGraph`, resolve **`metadata.graphEntry` per model**, seed **`runtime.executionMemory`**, and pass **`runtime.jobId`** (see [Run identity](#run-identity-host-jobid-and-engine-taskid) below). Helpers such as **`buildMatrixJobForGraphRun`** align **`id`** and **`job.jobId`** on the `job` object so you can call **`runtime.executeGraph({ model, runtime: { jobId: job.jobId, job, … } })`**. Those exports are **optional helpers for callers**; they do **not** expand graph-engine’s role beyond **executing the single run** when invoked.
+Matrix **claim**, **rows**, and **retry policy** live outside this package. If your host wires **matrix → graph run**, see [.docs/execution-matrix-handoff.md](.docs/execution-matrix-handoff.md) for how **you** should inject `runtime.executeGraph`, compile **`GraphModelObject` → plan**, resolve **`metadata.graphEntry` per model**, seed **`runtime.executionMemory`**, and pass **`runtime.jobId`**. Helpers such as **`buildMatrixJobForGraphRun`** align **`id`** and **`job.jobId`** on the `job` object so you can call **`runtime.executeGraph({ plan, runtime: { jobId: job.jobId, job, … } })`**. Those exports are **optional helpers for callers**; they do **not** expand graph-engine’s role beyond **executing the single run** when invoked.
 
 ### Configuration (`.env`)
 
@@ -213,10 +213,11 @@ interface ExecuteGraphResult {
   runLogOmittedCount?: number;
   logxerCorrelationId?: string;
   debug?: { nodes: NodeTraceEntry[] }; // populated only when debugMode: true
-  graphAudit?: {
-    source: 'model';
-    contentSha256: string; // stable JSON + SHA-256 of supplied model (audit / matrix persistence)
+  planAudit?: {
+    planHash: string;
+    source: string;
   };
+  trace?: unknown;
 }
 ```
 
@@ -237,13 +238,11 @@ const runtime = createExellixGraphRuntime({
   playgroundReporter,
 });
 
+const plan = compileExellixExecutablePlan(graphModel, graphRuntime);
+
 await runtime.executeGraph({
-  model,
-  runtime: {
-    jobId: 'job-123',
-    job,
-    input,
-  },
+  plan,
+  runtime: graphRuntime,
 });
 
 // Inspect full node request/response payloads in memory.
@@ -367,7 +366,7 @@ Example:
 }
 ```
 
-`metadata.graphExecution.outputMode`, finalizer output, and legacy `metadata.graphResponse.responseMapping` are not final-output selectors for new graphs. Migrate legacy response mappings by copying `missing` and `shape` to root `response` and dropping `version`, `target`, `primaryResponsePaths`, `debugResponsePaths`, `notableExecutionPaths`, and `mappingPreset`.
+`metadata.graphExecution.outputMode`, finalizer output, and `metadata.graphResponse.responseMapping` are not final-output selectors. Graphs must declare root `graph.response` at persist time; graph-engine does not hoist or migrate legacy response sidecars at compile.
 
 `coreObjective` is resolved once from graph/run context, not from each node response. Supported `sourcePath` roots are `input.*`, `execution.*`, `variables.*` / `jobVariables.*`, `taskVariables.*`, `jobMemory.*`, `taskMemory.*`, and `job.*`.
 

package/dist/src/compile/authoringDocumentHelpers.d.ts

@@ -0,0 +1,9 @@
+import type { AuthoringGraphDocument } from '@x12i/graphenix-executable-contracts';
+import type { GraphEntryContract } from '../types/refs.js';
+/**
+ * Reads Layer 01 contract from a Graphenix 2.x {@link AuthoringGraphDocument}
+ * (`graph.metadata.graphEntry`). Host catalog loaders return this shape from studio.
+ */
+export declare function resolveGraphEntryFromAuthoringDocument(doc: AuthoringGraphDocument): GraphEntryContract | undefined;
+/** Canonical id on an authoring document (matrix claim `graphId` must match this). */
+export declare function authoringDocumentGraphId(doc: AuthoringGraphDocument): string;

package/dist/src/compile/authoringDocumentHelpers.js

@@ -0,0 +1,18 @@
+function isPlainRecord(v) {
+    return v != null && typeof v === 'object' && !Array.isArray(v);
+}
+/**
+ * Reads Layer 01 contract from a Graphenix 2.x {@link AuthoringGraphDocument}
+ * (`graph.metadata.graphEntry`). Host catalog loaders return this shape from studio.
+ */
+export function resolveGraphEntryFromAuthoringDocument(doc) {
+    const meta = doc.graph?.metadata;
+    if (!isPlainRecord(meta))
+        return undefined;
+    const graphEntry = meta.graphEntry;
+    return isPlainRecord(graphEntry) ? graphEntry : undefined;
+}
+/** Canonical id on an authoring document (matrix claim `graphId` must match this). */
+export function authoringDocumentGraphId(doc) {
+    return doc.id;
+}

package/dist/src/compile/compileExellixExecutablePlan.d.ts

@@ -0,0 +1,8 @@
+import type { AuthoringGraphDocument, CompileExecutablePlanV2Options, ExecutableGraphPlanV2 } from '@x12i/graphenix-executable-contracts';
+import type { GraphRuntimeObject } from '../runtime/ExellixGraphRuntime.js';
+export type CompileExellixExecutablePlanOptions = CompileExecutablePlanV2Options;
+/**
+ * Host/test helper: canonical {@link AuthoringGraphDocument} + runtime → validated v2 executable plan.
+ * No legacy migration — graphs must already be Graphenix 2.x authoring shape.
+ */
+export declare function compileExellixExecutablePlan(doc: AuthoringGraphDocument, runtime: GraphRuntimeObject, options?: CompileExellixExecutablePlanOptions): ExecutableGraphPlanV2;

package/dist/src/compile/compileExellixExecutablePlan.js

@@ -0,0 +1,75 @@
+import { validateAuthoringGraph } from '@x12i/graphenix-authoring-format';
+import { compileExecutablePlanV2 } from '@x12i/graphenix-plan-compiler';
+import { validateExecutablePlanV2 } from '@x12i/graphenix-plan-format';
+import { resolveGraphEntryFromAuthoringDocument } from './authoringDocumentHelpers.js';
+import { EXELLIX_STRUCTURED_DATA_FILTERS_V1 } from '../types/refs.js';
+function patchEntryGatesFromGraphEntryDataFilters(plan, doc) {
+    const graphEntry = resolveGraphEntryFromAuthoringDocument(doc);
+    const dataFilters = graphEntry?.dataFilters;
+    if (dataFilters == null ||
+        typeof dataFilters !== 'object' ||
+        Array.isArray(dataFilters) ||
+        dataFilters.version !== EXELLIX_STRUCTURED_DATA_FILTERS_V1) {
+        return plan;
+    }
+    const when = dataFilters.when;
+    if (when == null || typeof when !== 'object')
+        return plan;
+    const next = structuredClone(plan);
+    const entryGates = [...(next.deferredGates.entryGates ?? [])];
+    entryGates.push({
+        gateId: 'graph-entry:structured-data-filters',
+        condition: { condition: when, parameters: {} },
+        sourcePath: 'metadata.graphEntry.dataFilters',
+    });
+    next.deferredGates = { ...next.deferredGates, entryGates };
+    return next;
+}
+function patchInvokeContractReadPathsForExecutionMemory(plan) {
+    const allowedRoots = new Set([
+        'executionMemory',
+        'input',
+        'inputs',
+        'jobMemory',
+        'taskMemory',
+        'smartInput',
+        'xynthesized',
+        'runtime',
+        'response',
+    ]);
+    const next = structuredClone(plan);
+    for (const nodePlan of Object.values(next.nodePlans ?? {})) {
+        if (!nodePlan?.executionUnits)
+            continue;
+        for (const unit of nodePlan.executionUnits) {
+            const contract = unit.invokeContract;
+            if (!contract || !Array.isArray(contract.reads))
+                continue;
+            contract.reads = contract.reads.map((readPath) => {
+                if (typeof readPath !== 'string')
+                    return readPath;
+                const root = readPath.split('.')[0];
+                return allowedRoots.has(root) ? readPath : `executionMemory.${readPath}`;
+            });
+        }
+    }
+    return next;
+}
+/**
+ * Host/test helper: canonical {@link AuthoringGraphDocument} + runtime → validated v2 executable plan.
+ * No legacy migration — graphs must already be Graphenix 2.x authoring shape.
+ */
+export function compileExellixExecutablePlan(doc, runtime, options) {
+    const authoringValidation = validateAuthoringGraph(doc);
+    if (!authoringValidation.valid) {
+        const summary = authoringValidation.errors.map((e) => `${e.path}: ${e.message}`).join('; ');
+        throw new Error(`compileExellixExecutablePlan: invalid authoring graph: ${summary}`);
+    }
+    const plan = patchInvokeContractReadPathsForExecutionMemory(patchEntryGatesFromGraphEntryDataFilters(compileExecutablePlanV2(doc, runtime, options), doc));
+    const planValidation = validateExecutablePlanV2(plan);
+    if (!planValidation.valid) {
+        const summary = planValidation.errors.map((e) => `${e.path}: ${e.message}`).join('; ');
+        throw new Error(`compileExellixExecutablePlan: invalid plan: ${summary}`);
+    }
+    return plan;
+}

package/dist/src/index.d.ts

@@ -62,7 +62,7 @@ export { collectAiTasksNodeExtensionIssues, assertAiTasksNodeExtensionsValid, }
 export type { AiTasksNodeExtensionIssue } from './inspection/validateAiTasksNodeExtensions.js';
 export type { EvaluateStructuredDataFiltersResult, EvaluateStructuredDataFiltersOptions, } from './runtime/dataFiltersEvaluation.js';
 /** Execution-matrix host: resolve graph entry, seed execution, stable job ids, runtime binder. */
-export { resolveGraphEntryFromGraph, createResolveGraphEntryFromLoader, buildExecutionSeedFromGraphEntry, validateExecutionSeedPaths, buildStableMatrixJobId, buildMatrixJobForGraphRun, buildGraphExecutionRequest, isExecuteGraphResultFailed, createMatrixHostGraphExecutor, } from './runtime/executionMatrixHost.js';
+export { resolveGraphEntryFromGraph, resolveGraphEntryFromAuthoringDocument, authoringDocumentGraphId, createResolveGraphEntryFromLoader, buildExecutionSeedFromGraphEntry, validateExecutionSeedPaths, buildStableMatrixJobId, buildMatrixJobForGraphRun, buildGraphExecutionRequest, isExecuteGraphResultFailed, createMatrixHostGraphExecutor, } from './runtime/executionMatrixHost.js';
 export type { BuildExecutionSeedSources, BuildExecutionSeedResult } from './runtime/executionMatrixHost.js';
 export { assertHostJobId, newGraphRunTaskId } from './runtime/graphRunIdentity.js';
 export { buildAiTasksRunTaskRequest, extractRunTaskMetadataPassthrough, extractRunTaskStrategyOverrides, resolveJobTypeId, resolveTaskTypeId, } from './runtime/buildAiTasksRunTaskRequest.js';
@@ -86,14 +86,12 @@ export type { GraphStudioDocument } from './runtime/graphModelStudioSeparation.j
 export { STUDIO_GRAPH_EXECUTE_REMOVED_KEYS, getStudioGraphExecuteRemovedKeyViolations, assertCanonicalStudioGraphExecuteRequest, buildGraphExecutionRequestFromStudioExecute, } from './runtime/studioGraphExecuteRequest.js';
 export type { StudioGraphExecuteRemovedKey, StudioGraphExecuteRequest, BuildGraphExecutionRequestFromStudioExecuteOptions, } from './runtime/studioGraphExecuteRequest.js';
 export { computeGraphDocumentContentSha256, stableStringifyGraphDocument, } from './runtime/graphDocumentFingerprint.js';
-export { migrateLegacyGraphResponse, migrateLegacyGraphResponseDefinition, } from './runtime/graphResponseMigration.js';
-export type { MigrateGraphResponseResult } from './runtime/graphResponseMigration.js';
 export { applyAiTaskProfileWebScopingToNarrix, mapAiTaskProfileQuestionsToWebScopeQuestions, } from './runtime/applyAiTaskProfileWebScopingToNarrix.js';
 export { createExellixGraphRuntime } from './runtime/ExellixGraphRuntime.js';
 export type { ExecutableGraphPlanV2, NodeExecutionPlan, ExecutionUnitPlanV2, } from '@x12i/graphenix-executable-contracts';
-export { compileExellixExecutablePlan } from './adapters/compileExellixExecutablePlan.js';
-export type { CompileExellixExecutablePlanOptions } from './adapters/compileExellixExecutablePlan.js';
-export { migrateExellixGraphModelToAuthoring } from './adapters/migrateExellixGraphModelToAuthoring.js';
+export type { AuthoringGraphDocument } from '@x12i/graphenix-executable-contracts';
+export { compileExellixExecutablePlan } from './compile/compileExellixExecutablePlan.js';
+export type { CompileExellixExecutablePlanOptions } from './compile/compileExellixExecutablePlan.js';
 export { buildGraphExecutionRequestFromStudioExecute as buildAuthoringStudioGraphExecutionRequest } from '@x12i/graphenix-execute-envelope';
 export type { RunTaskRequest, RunTaskResponse, TasksClientLike, GraphLoader as RuntimeGraphLoader, ExecuteGraphInput, GraphExecutionRequest, GraphRuntimeObject, GraphKnowledgeResolver, GraphKnowledgeResolverContext, ExecuteGraphResult, ExellixGraphRuntimeOptions, } from './runtime/ExellixGraphRuntime.js';
 export type { PlanStatus, GraphPlan, GraphEngine, GraphEngineFactory, } from './runtime/GraphEngine.js';

package/dist/src/index.js

@@ -48,7 +48,7 @@ export { resolveCanonicalModelUsed } from './runtime/canonicalModelUsed.js';
 export { buildAiTasksObservabilityRecord } from './runtime/aiTasksObservability.js';
 export { collectAiTasksNodeExtensionIssues, assertAiTasksNodeExtensionsValid, } from './inspection/validateAiTasksNodeExtensions.js';
 /** Execution-matrix host: resolve graph entry, seed execution, stable job ids, runtime binder. */
-export { resolveGraphEntryFromGraph, createResolveGraphEntryFromLoader, buildExecutionSeedFromGraphEntry, validateExecutionSeedPaths, buildStableMatrixJobId, buildMatrixJobForGraphRun, buildGraphExecutionRequest, isExecuteGraphResultFailed, createMatrixHostGraphExecutor, } from './runtime/executionMatrixHost.js';
+export { resolveGraphEntryFromGraph, resolveGraphEntryFromAuthoringDocument, authoringDocumentGraphId, createResolveGraphEntryFromLoader, buildExecutionSeedFromGraphEntry, validateExecutionSeedPaths, buildStableMatrixJobId, buildMatrixJobForGraphRun, buildGraphExecutionRequest, isExecuteGraphResultFailed, createMatrixHostGraphExecutor, } from './runtime/executionMatrixHost.js';
 export { assertHostJobId, newGraphRunTaskId } from './runtime/graphRunIdentity.js';
 export { buildAiTasksRunTaskRequest, extractRunTaskMetadataPassthrough, extractRunTaskStrategyOverrides, resolveJobTypeId, resolveTaskTypeId, } from './runtime/buildAiTasksRunTaskRequest.js';
 export { buildTaskNodeJobContext } from './runtime/buildTaskNodeJobContext.js';
@@ -63,12 +63,10 @@ export { assertCanonicalGraphRuntimeObject } from './runtime/validateCanonicalGr
 export { GRAPH_ENTRY_STUDIO_ONLY_KEYS, GRAPH_METADATA_STUDIO_ONLY_KEYS, stripGraphModelStudioFields, primaryRuntimeInputFromStudioDocument, getGraphEntryStudioOnlyKeyViolations, getGraphMetadataStudioOnlyKeyViolations, getGraphEntryEmptyInputPathViolations, } from './runtime/graphModelStudioSeparation.js';
 export { STUDIO_GRAPH_EXECUTE_REMOVED_KEYS, getStudioGraphExecuteRemovedKeyViolations, assertCanonicalStudioGraphExecuteRequest, buildGraphExecutionRequestFromStudioExecute, } from './runtime/studioGraphExecuteRequest.js';
 export { computeGraphDocumentContentSha256, stableStringifyGraphDocument, } from './runtime/graphDocumentFingerprint.js';
-export { migrateLegacyGraphResponse, migrateLegacyGraphResponseDefinition, } from './runtime/graphResponseMigration.js';
 export { applyAiTaskProfileWebScopingToNarrix, mapAiTaskProfileQuestionsToWebScopeQuestions, } from './runtime/applyAiTaskProfileWebScopingToNarrix.js';
 // New runtime with injection seam
 export { createExellixGraphRuntime } from './runtime/ExellixGraphRuntime.js';
-export { compileExellixExecutablePlan } from './adapters/compileExellixExecutablePlan.js';
-export { migrateExellixGraphModelToAuthoring } from './adapters/migrateExellixGraphModelToAuthoring.js';
+export { compileExellixExecutablePlan } from './compile/compileExellixExecutablePlan.js';
 export { buildGraphExecutionRequestFromStudioExecute as buildAuthoringStudioGraphExecutionRequest } from '@x12i/graphenix-execute-envelope';
 // Testkit (in-memory loader, dep engine, recording client — sample NARRIX tasks: `@exellix/graph-engine/testkit`)
 export { InMemoryGraphLoader, DepGraphEngineFactory } from '../testkit/index.js';

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

@@ -1,6 +1,5 @@
 import type { GraphEngineFactory } from "./GraphEngine.js";
-import type { ExecutionStep } from "@exellix/ai-tasks";
-import type { ExecutableGraphPlanV2, GraphExecutionTrace } from "@x12i/graphenix-executable-contracts";
+import type { ExecutableGraphPlanV2, FinalizerExecutionPlan, GraphExecutionTrace, NodeExecutionPlan } from "@x12i/graphenix-executable-contracts";
 import type { Graph, GraphModelObject, GraphNode, GraphAiModelConfig, TaskNodeRuntimeObject } from "../types/refs.js";
 import type { RunLogEntry } from "../types/runLog.js";
 import type { RunTaskDiagnostics } from "../types/options.js";
@@ -10,38 +9,7 @@ import type { CreateRunxOptions, RunxClient } from "@x12i/runx";
 import { type EventEmitter } from "./events.js";
 import type { NodeTraceEntry } from "../types/results.js";
 import type { ExecuteGraphStepResponse } from "../types/results.js";
-export type RunTaskRequest = {
-    skillKey: string;
-    /** Execution pipeline (pre → main → post). When omitted, defaults to [{ phase: "main", type: "direct" }]. */
-    executionPipeline?: ExecutionStep[];
-    /** When true, task receives synthesized/context in prompt (e.g. for synthesized-context PRE step). */
-    includeContextInPrompt?: boolean;
-    input?: any;
-    variables?: Record<string, any>;
-    jobMemory?: any;
-    taskMemory?: any;
-    executionMemory?: any;
-    prevNodeId?: string;
-    jobId?: string;
-    taskId?: string;
-    agentId?: string;
-    skillId?: string;
-    masterSkillId?: string;
-    masterSkillActivityId?: string;
-    jobContext?: any;
-    modelConfig?: GraphAiModelConfig;
-    outputValidation?: {
-        schema: Record<string, unknown>;
-        mode?: "fail" | "warn";
-        validateWhenMissing?: boolean;
-    };
-    diagnostics?: RunTaskDiagnostics;
-    llmCall?: Record<string, unknown>;
-    identity?: Record<string, unknown>;
-    executionMode?: "default" | "trace";
-    taskKind?: "decision" | "utility" | "content";
-    autoValidateDecisionOutput?: boolean;
-};
+export type RunTaskRequest = import("@exellix/ai-tasks").RunTaskRequest;
 export type RunTaskResponse = {
     ok: boolean;
     rawContent?: string;
@@ -203,8 +171,14 @@ export declare function createExellixGraphRuntime(opts: ExellixGraphRuntimeOptio
         /** Per-node task-scope overrides → `executionMemory.taskVariables`. */
         taskVariables?: Record<string, unknown>;
         prevNodeId?: string;
-        /** Resolved graph model profiles; omitted when {@link graph} is supplied (resolved from the model document). */
+        /** Resolved model profiles from frozen plan slots; required when {@link nodePlan} is omitted. */
         modelConfig?: GraphAiModelConfig;
+        /** Frozen per-node plan from {@link compileExecutablePlanV2}; drives executionUnits on the executeGraph path. */
+        nodePlan?: NodeExecutionPlan;
+        /** Frozen finalizer plan slice when executing a synthesize finalizer utility invoke. */
+        finalizerPlan?: FinalizerExecutionPlan;
+        /** Graphenix v2 trace handle forwarded to ai-tasks node executor. */
+        executionTrace?: GraphExecutionTrace;
         /** Same UUID for every `runTask` in this `executeGraph` invocation; omitted → new UUID per direct `executeNode` call. */
         graphRunTaskId?: string;
         runTaskIdentity?: Record<string, unknown>;
@@ -214,7 +188,7 @@ export declare function createExellixGraphRuntime(opts: ExellixGraphRuntimeOptio
         jobKnowledgePatch?: Record<string, unknown>;
         /** Resolved per-node taskKnowledge, applied only to outbound RunTaskRequest.taskMemory. */
         taskKnowledgePatch?: Record<string, unknown>;
-        /** Graph-run default pipeline; node / `execution.executionPipeline` override per executeNode rules. */
+        /** @deprecated ai-tasks ≥ 9 executes {@link nodePlan.executionUnits}; graph-engine does not forward a pipeline. */
         graphExecutionPipeline?: ExecutionStepOption[];
         skillKeyResolution?: SkillKeyResolutionOptions;
         nodeTimeoutMs?: number;
@@ -256,6 +230,6 @@ export declare function createExellixGraphRuntime(opts: ExellixGraphRuntimeOptio
         };
         execution: any;
         outputsMemory: Record<string, unknown>;
-        request: RunTaskRequest;
+        request: import("@exellix/ai-tasks").RunTaskRequest;
     }>;
 };