@exellix/graph-engine 7.8.2 → 8.0.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 8.0.0
+
+### Breaking
+
+- **`executeGraph({ plan, runtime })` only** — removed `ExecuteGraphInput.model`. Hosts compile with `compileExellixExecutablePlan` or `@x12i/graphenix-plan-compiler` before invoke.
+- **`ExecuteGraphResult.graphAudit` → `planAudit`** (`{ planHash, source }`).
+- Execute-time model case selection and `assertCanonicalGraphDocument` removed from the run path; frozen `plan.nodePlans` / `plan.finalizerPlans` drive model config and invoke contracts.
+
+### 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`.
+- **`buildAuthoringStudioGraphExecutionRequest`** re-export from `@x12i/graphenix-execute-envelope`.
+
+See [`BREAKING-CHANGES.md`](BREAKING-CHANGES.md) §8.0.0.
+
+## 7.8.3
+
+### Breaking
+
+- **Studio graph execute envelope:** `graphDefaultModel` removed with **no legacy reader**. Request-level model defaults duplicated `graph.modelConfig` and were never applied by graph-engine. Hosts (graphs-studio) must persist defaults on **`graph.modelConfig` only** and stop sending `graphDefaultModel`.
+- **Validation:** `assertCanonicalStudioGraphExecuteRequest` and `buildGraphExecutionRequestFromStudioExecute` reject the removed key (`NON_CANONICAL_STUDIO_GRAPH_EXECUTE_REQUEST`).
+
+### Added
+
+- **Documentation:** [`formats-documentations/graph-format-boundaries.md`](formats-documentations/graph-format-boundaries.md) — four-layer model (graph / runtime / studio envelope / studio DB), field mapping from playground payloads, and explicit list of what is not on `GraphModelObject`.
+
 ## 7.8.2
 
 ### Fixed

package/README.md

@@ -4,7 +4,7 @@ A minimal, focused SDK for executing graphs in the exellix ecosystem.
 
 ## What this package does and does not
 
-**In scope — what this package does:** On each **`createExellixGraphRuntime(...).executeGraph({ model, runtime })`** invocation, it runs **exactly one graph run** (validate model → plan → nodes → finalizer) until that run **completes or fails**, then returns the result. There is **no** batching, queueing, or multi-job orchestration inside this package — each call is one logical run. You supply the static **`model: GraphModelObject`**, planner (`GraphEngineFactory`), tasks client, and dynamic **`runtime: GraphRuntimeObject`** with the mandatory host `jobId`, `job` envelope, active `input`, memory, variables, and per-run options. The engine generates a fresh **`taskId`** (UUID) per invocation and sends it on **every** `runTask` request together with **`jobId`**. That is the **entire** product role of graph-engine.
+**In scope — what this package does:** On each **`createExellixGraphRuntime(...).executeGraph({ plan, runtime })`** invocation, it runs **exactly one graph run** (validate plan → schedule waves → nodes → finalizer) until that run **completes or fails**, then returns the result. There is **no** batching, queueing, or multi-job orchestration inside this package — each call is one logical run. You supply a compiled v2 **`plan: ExecutableGraphPlanV2`** (from `@x12i/graphenix-plan-compiler` or {@link compileExellixExecutablePlan}), planner (`GraphEngineFactory`), tasks client, and dynamic **`runtime: GraphRuntimeObject`** with the mandatory host `jobId`, `job` envelope, active `input`, memory, variables, and per-run options. The engine generates a fresh **`taskId`** (UUID) per invocation and sends it on **every** `runTask` request together with **`jobId`**. That is the **entire** product role of graph-engine.
 
 **Out of scope — what this package does not do:** It does **not** schedule work, own **execution matrices**, manage **claims** or **rows**, persist **job** lifecycle, implement **retry/requeue policy**, or **track** runs across tenants or sessions. Optional helpers and docs for matrix *hosts* only help **build arguments** for the same single-run API; they do **not** move orchestration into this package. Integrations (e.g. Activix graph-run events) emit data **for that call** when you wire an `eventEmitter` — they do not make graph-engine a workflow or matrix service.
 
@@ -12,8 +12,8 @@ A minimal, focused SDK for executing graphs in the exellix ecosystem.
 
 `exellix-graph-engine` does exactly this loop:
 
-1. **Validate graph model:** The caller supplies **`model: GraphModelObject`** directly in the execution request. The effective correlation **`graphId`** on the result and in telemetry is **`model.id`**.
-2. `plan = graphenix.plan(...)`
+1. **Validate executable plan:** The caller supplies **`plan: ExecutableGraphPlanV2`** (compiled upstream). The effective correlation **`graphId`** on the result and in telemetry is **`plan.source.graphId`**.
+2. `executeGraph({ plan, runtime })`
 3. For each runnable node:
    - Map node → `skillKey` (strict rules)
    - If `skillKey` is a **local skill** (`scoped-data-reader`, `deterministic-rule`, `scoped-answer-writer`, `scoped-answer-assembler`), run it in-process (no `ai-tasks` call); otherwise call `ai-tasks.runTask(...)`
@@ -97,7 +97,7 @@ Lower-level helpers (`validateRunTaskConfig`, `validateRunTaskInvoke`, `analyzeE
 ## Quick Start
 
 ```typescript
-import { createExellixGraphRuntime } from '@exellix/graph-engine';
+import { compileExellixExecutablePlan, createExellixGraphRuntime } from '@exellix/graph-engine';
 
 const runtime = createExellixGraphRuntime({
   graphLoader: myGraphLoader,
@@ -121,15 +121,18 @@ const graphModel = {
   // …
 };
 
+const graphRuntime = {
+  jobId: 'job-123',
+  job: { agentId: 'agent-1', input: {} },
+  input: { question: 'Analyze this record' },
+};
+
+const plan = compileExellixExecutablePlan(graphModel, graphRuntime);
+
 // Host correlation id (required). Engine sets `job.id` / `job.jobId` from it and generates `result.taskId`.
 const result = await runtime.executeGraph({
-  model: graphModel,
-  runtime: {
-    jobId: 'job-123',
-    job: { agentId: 'agent-1', input: {} },
-    input: { question: 'Analyze this record' },
-    // no modelConfig or aliasConfig on runtime (removed in 7.7)
-  },
+  plan,
+  runtime: graphRuntime,
 });
 
 // Canonical business output + per-run ids:
@@ -138,11 +141,11 @@ console.log(result.finalOutput, result.jobId, result.taskId);
 
 ## Public API
 
-### `runtime.executeGraph({ model, runtime })`
+### `runtime.executeGraph({ plan, runtime })`
 
 Execute a complete graph through the **single canonical client API**: `createExellixGraphRuntime(...)`. The runtime owns local-skill interception, conditional edge filtering, optional `eventEmitter`, optional `debugMode`, and produces one `ExecuteGraphResult` shape.
 
-Every call requires a static **`model: GraphModelObject`** and a dynamic **`runtime: GraphRuntimeObject`**. `runtime.jobId` is mandatory and non-empty. The engine also generates a **`taskId`** (UUID) per invocation. Together they form the **identity** forwarded to **`@exellix/ai-tasks`** (`runTask({ jobId, taskId, … })`), graph/node **`eventEmitter`** payloads, structured **`runLog`**, and Activix **`runContext`** / record metadata.
+Every call requires a compiled v2 **`plan: ExecutableGraphPlanV2`** and a dynamic **`runtime: GraphRuntimeObject`**. Hosts compile authoring graphs with `@x12i/graphenix-plan-compiler` (or {@link compileExellixExecutablePlan} for legacy exellix `GraphModelObject`) before invoke. `runtime.jobId` is mandatory and non-empty. The engine also generates a **`taskId`** (UUID) per invocation. Together they form the **identity** forwarded to **`@exellix/ai-tasks`** (`runTask({ jobId, taskId, … })`), graph/node **`eventEmitter`** payloads, structured **`runLog`**, and Activix **`runContext`** / record metadata.
 
 ```typescript
 import { createExellixGraphRuntime } from '@exellix/graph-engine';

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

@@ -0,0 +1,8 @@
+import type { CompileExecutablePlanV2Options, ExecutableGraphPlanV2 } from '@x12i/graphenix-executable-contracts';
+import type { Graph, GraphModelObject } from '../types/refs.js';
+import type { GraphRuntimeObject } from '../runtime/ExellixGraphRuntime.js';
+export type CompileExellixExecutablePlanOptions = CompileExecutablePlanV2Options;
+/**
+ * Host/test helper: exellix graph model + runtime → validated v2 executable plan.
+ */
+export declare function compileExellixExecutablePlan(model: Graph | GraphModelObject, runtime: GraphRuntimeObject, options?: CompileExellixExecutablePlanOptions): ExecutableGraphPlanV2;

package/dist/src/adapters/compileExellixExecutablePlan.js

@@ -0,0 +1,18 @@
+import { compileExecutablePlanV2 } from '@x12i/graphenix-plan-compiler';
+import { validateExecutablePlan } from '@x12i/graphenix-plan-format';
+import { migrateExellixGraphModelToAuthoring } from './migrateExellixGraphModelToAuthoring.js';
+import { patchFinalizerPlansOnExecutablePlan } from './patchFinalizerPlans.js';
+/**
+ * Host/test helper: exellix graph model + runtime → validated v2 executable plan.
+ */
+export function compileExellixExecutablePlan(model, runtime, options) {
+    const authoring = migrateExellixGraphModelToAuthoring(model);
+    const compiled = compileExecutablePlanV2(authoring, runtime, options);
+    const plan = patchFinalizerPlansOnExecutablePlan(compiled, runtime);
+    const validation = validateExecutablePlan(plan);
+    if (!validation.valid) {
+        const summary = validation.errors.map((e) => `${e.path}: ${e.message}`).join('; ');
+        throw new Error(`compileExellixExecutablePlan: invalid plan: ${summary}`);
+    }
+    return plan;
+}

package/dist/src/adapters/migrateExellixGraphModelToAuthoring.d.ts

@@ -0,0 +1,6 @@
+import { type AuthoringGraphDocument } from '@x12i/graphenix-executable-contracts';
+import type { Graph, GraphModelObject } from '../types/refs.js';
+/**
+ * Converts exellix {@link GraphModelObject} to graphenix {@link AuthoringGraphDocument} for plan compilation.
+ */
+export declare function migrateExellixGraphModelToAuthoring(model: Graph | GraphModelObject): AuthoringGraphDocument;

package/dist/src/adapters/migrateExellixGraphModelToAuthoring.js

@@ -0,0 +1,273 @@
+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';
+import { EXELLIX_STRUCTURED_DATA_FILTERS_V1 } from '../types/refs.js';
+import { DEFAULT_GRAPH_AI_MODEL_PROFILE_CONFIG } from '../runtime/graphAiModelConfig.js';
+import { migrateLegacyGraphResponse } from '../runtime/graphResponseMigration.js';
+function isPlainRecord(v) {
+    return v != null && typeof v === 'object' && !Array.isArray(v);
+}
+function aliasToProfileChoice(value) {
+    const trimmed = value.trim();
+    if (trimmed.includes('/'))
+        return { kind: 'profileChoice', key: trimmed };
+    const shortcuts = {
+        cheap: 'cheap/default',
+        balanced: 'vol/default',
+        deep: 'deep/openai_deep',
+        pro: 'pro/default',
+    };
+    const key = shortcuts[trimmed] ?? `${trimmed}/default`;
+    return { kind: 'profileChoice', key };
+}
+function exellixModelConfigToExecutable(modelConfig) {
+    if (!modelConfig?.cases?.length)
+        return undefined;
+    const cases = modelConfig.cases.map((c, index) => {
+        const mc = c.modelConfig;
+        const modelConfigOut = {};
+        if (mc.preActionModel != null && String(mc.preActionModel).trim() !== '') {
+            modelConfigOut.preActionModel = aliasToProfileChoice(String(mc.preActionModel));
+        }
+        if (mc.skillModel != null && String(mc.skillModel).trim() !== '') {
+            modelConfigOut.skillModel = aliasToProfileChoice(String(mc.skillModel));
+        }
+        if (mc.postActionModel != null && String(mc.postActionModel).trim() !== '') {
+            modelConfigOut.postActionModel = aliasToProfileChoice(String(mc.postActionModel));
+        }
+        return {
+            id: c.when == null ? 'default' : `case-${index}`,
+            ...(c.when != null ? { when: c.when } : {}),
+            modelConfig: modelConfigOut,
+        };
+    });
+    const hasPartialCase = cases.some((c) => !c.modelConfig.preActionModel ||
+        !c.modelConfig.skillModel ||
+        !c.modelConfig.postActionModel);
+    return {
+        version: 'graph-model-config/v1',
+        cases,
+        ...(hasPartialCase ? { inherit: true } : {}),
+    };
+}
+const DEFAULT_EXECUTABLE_FALLBACK_POLICY = {
+    enabled: true,
+    allowedTriggers: [
+        'nodeSlotMissing',
+        'nodeModelUnavailable',
+        'nodeModelUnsupported',
+        'nodeProviderNotConfigured',
+        'nodeModelRateLimited',
+        'nodeModelTransientFailure',
+    ],
+    maxAttemptsPerSlot: 1,
+};
+function defaultExecutableModelConfig() {
+    const mc = DEFAULT_GRAPH_AI_MODEL_PROFILE_CONFIG;
+    return {
+        version: 'graph-model-config/v1',
+        cases: [
+            {
+                id: 'default',
+                modelConfig: {
+                    preActionModel: aliasToProfileChoice(mc.preActionModel),
+                    skillModel: aliasToProfileChoice(mc.skillModel),
+                    postActionModel: aliasToProfileChoice(mc.postActionModel),
+                },
+            },
+        ],
+        fallbackPolicy: DEFAULT_EXECUTABLE_FALLBACK_POLICY,
+    };
+}
+function isStructuredExellixDataFilters(value) {
+    return (isPlainRecord(value) &&
+        value.version === EXELLIX_STRUCTURED_DATA_FILTERS_V1 &&
+        isPlainRecord(value.when));
+}
+function exellixGraphEntryToAuthoring(graphEntry) {
+    if (!isPlainRecord(graphEntry))
+        return graphEntry;
+    const next = structuredClone(graphEntry);
+    const dataFilters = next.dataFilters;
+    if (isStructuredExellixDataFilters(dataFilters)) {
+        next.dataFilters = [dataFilters.when];
+    }
+    return next;
+}
+/** Authoring validation requires jsonConditions as an array; exellix uses a CaseCondition object. */
+function exellixConditionsToAuthoring(conditions) {
+    if (Array.isArray(conditions)) {
+        return { runWhen: conditions };
+    }
+    const runWhenEntry = {};
+    if (conditions.jsonConditions != null) {
+        runWhenEntry.jsonConditions = structuredClone(conditions.jsonConditions);
+    }
+    if (conditions.jsConditionFunction != null) {
+        runWhenEntry.jsConditionFunction = structuredClone(conditions.jsConditionFunction);
+    }
+    if (conditions.aiCondition != null) {
+        runWhenEntry.aiCondition = structuredClone(conditions.aiCondition);
+    }
+    const out = {};
+    if (Object.keys(runWhenEntry).length > 0) {
+        out.runWhen = [runWhenEntry];
+    }
+    if (conditions.dataFilters != null) {
+        out.dataFilters = structuredClone(conditions.dataFilters);
+    }
+    if (conditions.narratives != null) {
+        out.narratives = structuredClone(conditions.narratives);
+    }
+    return out;
+}
+function defaultPorts(nodeId) {
+    return {
+        in: `in:${nodeId}`,
+        out: `out:${nodeId}`,
+    };
+}
+function exellixTaskNodeToExecutable(node) {
+    const ports = defaultPorts(String(node.id));
+    const params = {
+        profile: TASK_NODE_PROFILE,
+        nodeType: 'task',
+        skillKey: node.skillKey,
+    };
+    if (node.taskConfiguration != null)
+        params.taskConfiguration = structuredClone(node.taskConfiguration);
+    if (node.taskVariable != null)
+        params.taskVariable = structuredClone(node.taskVariable);
+    if (node.inputsConfig != null)
+        params.inputsConfig = structuredClone(node.inputsConfig);
+    if (node.executionMapping != null)
+        params.executionMapping = structuredClone(node.executionMapping);
+    if (node.conditions != null)
+        params.conditions = exellixConditionsToAuthoring(node.conditions);
+    if (Array.isArray(node.taskKnowledge)) {
+        params.taskKnowledge = exellixKnowledgeRefsToAuthoring(node.taskKnowledge);
+    }
+    if (node.variables != null)
+        params.variables = structuredClone(node.variables);
+    if (node.metadata != null)
+        params.metadata = structuredClone(node.metadata);
+    if (node.executionPipeline != null)
+        params.executionPipeline = structuredClone(node.executionPipeline);
+    if (node.jobContextMapping != null)
+        params.jobContextMapping = structuredClone(node.jobContextMapping);
+    if (node.scope != null)
+        params.scope = structuredClone(node.scope);
+    if (node.smartInput != null)
+        params.smartInput = exellixSmartInputToAuthoring(node.smartInput);
+    if (node.outputValidation != null)
+        params.outputValidation = structuredClone(node.outputValidation);
+    const nodeModelConfig = node.taskConfiguration?.modelConfig;
+    if (nodeModelConfig != null) {
+        const converted = exellixModelConfigToExecutable(nodeModelConfig);
+        if (converted) {
+            params.taskConfiguration = {
+                ...(isPlainRecord(params.taskConfiguration) ? params.taskConfiguration : {}),
+                modelConfig: converted,
+            };
+        }
+    }
+    return {
+        id: String(node.id),
+        kind: TASK_NODE_KIND,
+        inputs: [{ id: ports.in, direction: 'input', type: 'builtin:object', required: false }],
+        outputs: [{ id: ports.out, direction: 'output', type: 'builtin:object' }],
+        parameters: params,
+    };
+}
+function exellixSmartInputToAuthoring(smartInput) {
+    if (!isPlainRecord(smartInput))
+        return structuredClone(smartInput);
+    const next = structuredClone(smartInput);
+    if (Array.isArray(next.paths)) {
+        next.paths = next.paths.map((entry) => typeof entry === 'string' ? { path: entry } : entry);
+    }
+    return next;
+}
+function exellixKnowledgeRefsToAuthoring(refs) {
+    return refs.map((ref) => ({ id: ref }));
+}
+function exellixFinalizerToExecutable(node) {
+    const n = node;
+    const ports = defaultPorts(String(node.id));
+    return {
+        id: String(node.id),
+        kind: FINALIZER_NODE_KIND,
+        inputs: [{ id: ports.in, direction: 'input', type: 'builtin:object', required: false }],
+        outputs: [{ id: ports.out, direction: 'output', type: 'builtin:object' }],
+        parameters: {
+            profile: FINALIZER_NODE_PROFILE,
+            nodeType: 'finalizer',
+            finalizerType: n.finalizerType,
+            config: isPlainRecord(n.config) ? structuredClone(n.config) : {},
+            ...(n.inputs != null ? { inputs: structuredClone(n.inputs) } : {}),
+            ...(n.outputMapping != null ? { outputMapping: structuredClone(n.outputMapping) } : {}),
+        },
+    };
+}
+/**
+ * Converts exellix {@link GraphModelObject} to graphenix {@link AuthoringGraphDocument} for plan compilation.
+ */
+export function migrateExellixGraphModelToAuthoring(model) {
+    const legacyMigrated = migrateLegacyGraphResponse(structuredClone(model));
+    const source = legacyMigrated.graph;
+    const executableModelConfig = exellixModelConfigToExecutable(source.modelConfig) ?? defaultExecutableModelConfig();
+    const metadata = isPlainRecord(source.metadata) ? structuredClone(source.metadata) : {};
+    const extensions = isPlainRecord(metadata.extensions) ? { ...metadata.extensions } : {};
+    extensions[EXECUTABLE_PROFILE_NAMESPACE] = {
+        ...(isPlainRecord(extensions[EXECUTABLE_PROFILE_NAMESPACE])
+            ? extensions[EXECUTABLE_PROFILE_NAMESPACE]
+            : {}),
+        profileVersion: EXECUTABLE_PROFILE_VERSION,
+        modelConfig: executableModelConfig,
+    };
+    metadata.extensions = extensions;
+    if (metadata.graphEntry != null) {
+        metadata.graphEntry = exellixGraphEntryToAuthoring(metadata.graphEntry);
+    }
+    if (Array.isArray(source.jobKnowledge)) {
+        metadata.jobKnowledge = exellixKnowledgeRefsToAuthoring(source.jobKnowledge);
+    }
+    const nodes = (source.nodes ?? []).map((node) => {
+        const type = node.type ?? 'task';
+        if (type === 'finalizer')
+            return exellixFinalizerToExecutable(node);
+        return exellixTaskNodeToExecutable(node);
+    });
+    const portByNode = new Map();
+    for (const n of nodes)
+        portByNode.set(n.id, defaultPorts(n.id));
+    const edges = (source.edges ?? []).map((e, index) => {
+        const fromPorts = portByNode.get(e.from) ?? defaultPorts(e.from);
+        const toPorts = portByNode.get(e.to) ?? defaultPorts(e.to);
+        return {
+            id: `edge:${index}:${e.from}->${e.to}`,
+            from: { nodeId: e.from, portId: fromPorts.out },
+            to: { nodeId: e.to, portId: toPorts.in },
+            ...(e.when != null ? { when: e.when } : {}),
+        };
+    });
+    const graphResponse = isPlainRecord(source.response)
+        ? { shape: source.response.shape, ...source.response }
+        : undefined;
+    return {
+        formatVersion: GRAPHENIX_FORMAT_VERSION,
+        id: String(source.id),
+        revision: typeof source.version === 'string' ? source.version : '1.0.0',
+        name: typeof metadata.name === 'string' ? metadata.name : String(source.id),
+        graph: {
+            nodes,
+            edges,
+            inputs: [],
+            outputs: [],
+            metadata: {
+                ...metadata,
+                ...(graphResponse ? { graphResponse } : {}),
+                graphEntry: metadata.graphEntry,
+            },
+        },
+    };
+}

package/dist/src/adapters/patchFinalizerPlans.d.ts

@@ -0,0 +1,7 @@
+import type { ExecutableGraphPlanV2 } from '@x12i/graphenix-executable-contracts';
+import type { GraphRuntimeObject } from '../runtime/ExellixGraphRuntime.js';
+/**
+ * `@x12i/graphenix-plan-compiler` v1.0.0 builds AI finalizer plans without resolved
+ * `finalizerModel` slots. Rebuild finalizer plans using published compiler helpers.
+ */
+export declare function patchFinalizerPlansOnExecutablePlan(plan: ExecutableGraphPlanV2, runtime: GraphRuntimeObject): ExecutableGraphPlanV2;

package/dist/src/adapters/patchFinalizerPlans.js

@@ -0,0 +1,63 @@
+import { getFinalizerNodeConfig, isExecutableFinalizerNode, } from '@x12i/graphenix-executable-contracts';
+import { buildFinalizerPlans, buildDeterministicCaseContext, resolveGraphModelConfig, } from '@x12i/graphenix-plan-compiler';
+const AI_FINALIZER_TYPES = new Set(['synthesize']);
+/**
+ * `@x12i/graphenix-plan-compiler` v1.0.0 builds AI finalizer plans without resolved
+ * `finalizerModel` slots. Rebuild finalizer plans using published compiler helpers.
+ */
+export function patchFinalizerPlansOnExecutablePlan(plan, runtime) {
+    if (plan.normalizedGraph.mode !== 'embedded')
+        return plan;
+    const normalized = plan.normalizedGraph.graph;
+    const aiFinalizers = normalized.graph.nodes.filter(isExecutableFinalizerNode).filter((node) => {
+        const config = getFinalizerNodeConfig(node);
+        return config != null && AI_FINALIZER_TYPES.has(String(config.finalizerType));
+    });
+    if (aiFinalizers.length === 0)
+        return plan;
+    const context = buildDeterministicCaseContext(normalized, runtime);
+    const graphResolution = resolveGraphModelConfig(normalized, context);
+    const triplet = graphResolution.triplet;
+    if (triplet.preActionModel == null && triplet.skillModel == null && triplet.postActionModel == null) {
+        return plan;
+    }
+    const slotMeta = {
+        source: 'graphDefault',
+        inherited: true,
+        graphCaseId: graphResolution.caseId,
+    };
+    const resolvedFinalizerSlots = {};
+    for (const node of aiFinalizers) {
+        const finalizerSelection = triplet.postActionModel ?? triplet.skillModel ?? triplet.preActionModel;
+        if (finalizerSelection == null)
+            continue;
+        resolvedFinalizerSlots[node.id] = {
+            selection: finalizerSelection,
+            ...slotMeta,
+        };
+    }
+    const finalizerPlans = buildFinalizerPlans(normalized, resolvedFinalizerSlots);
+    for (const node of aiFinalizers) {
+        const entry = finalizerPlans[node.id];
+        if (!entry)
+            continue;
+        entry.modelSlots = {
+            ...(triplet.preActionModel != null
+                ? { preActionModel: { selection: triplet.preActionModel, ...slotMeta } }
+                : {}),
+            ...(triplet.skillModel != null
+                ? { skillModel: { selection: triplet.skillModel, ...slotMeta } }
+                : {}),
+            ...(triplet.postActionModel != null
+                ? { postActionModel: { selection: triplet.postActionModel, ...slotMeta } }
+                : {}),
+            ...(entry.modelSlots?.finalizerModel != null
+                ? { finalizerModel: entry.modelSlots.finalizerModel }
+                : {}),
+        };
+    }
+    return {
+        ...plan,
+        finalizerPlans,
+    };
+}

package/dist/src/errors/exellixGraphErrorCodes.d.ts

@@ -13,6 +13,11 @@ export declare enum ExellixGraphErrorCode {
     INVALID_GRAPH = "INVALID_GRAPH",
     /** Graph JSON has forbidden top-level keys; document metadata must be under `metadata` only. */
     NON_CANONICAL_GRAPH_DOCUMENT = "NON_CANONICAL_GRAPH_DOCUMENT",
+    /**
+     * Graphs-studio execute envelope carries a removed or forbidden key (e.g. request-level `graphDefaultModel`).
+     * Model defaults belong on `graph.modelConfig` only.
+     */
+    NON_CANONICAL_STUDIO_GRAPH_EXECUTE_REQUEST = "NON_CANONICAL_STUDIO_GRAPH_EXECUTE_REQUEST",
     /** Runtime object carries forbidden model / llmCall overrides (graph document only since 7.7). */
     NON_CANONICAL_GRAPH_RUNTIME = "NON_CANONICAL_GRAPH_RUNTIME",
     /**

package/dist/src/errors/exellixGraphErrorCodes.js

@@ -14,6 +14,11 @@ export var ExellixGraphErrorCode;
     ExellixGraphErrorCode["INVALID_GRAPH"] = "INVALID_GRAPH";
     /** Graph JSON has forbidden top-level keys; document metadata must be under `metadata` only. */
     ExellixGraphErrorCode["NON_CANONICAL_GRAPH_DOCUMENT"] = "NON_CANONICAL_GRAPH_DOCUMENT";
+    /**
+     * Graphs-studio execute envelope carries a removed or forbidden key (e.g. request-level `graphDefaultModel`).
+     * Model defaults belong on `graph.modelConfig` only.
+     */
+    ExellixGraphErrorCode["NON_CANONICAL_STUDIO_GRAPH_EXECUTE_REQUEST"] = "NON_CANONICAL_STUDIO_GRAPH_EXECUTE_REQUEST";
     /** Runtime object carries forbidden model / llmCall overrides (graph document only since 7.7). */
     ExellixGraphErrorCode["NON_CANONICAL_GRAPH_RUNTIME"] = "NON_CANONICAL_GRAPH_RUNTIME";
     /**

package/dist/src/index.d.ts

@@ -9,8 +9,8 @@
  * 5. Repeat until done/fail
  *
  * Single canonical entry point: {@link createExellixGraphRuntime} returns
- * `{ executeGraph({ model, runtime }: GraphExecutionRequest) }`. The legacy functional `executeGraph`
- * and the `ExellixGraphClient` class were removed in 5.0.
+ * `{ executeGraph({ plan, runtime }: GraphExecutionRequest) }`. Hosts compile upstream via
+ * {@link compileExellixExecutablePlan} or `@x12i/graphenix-plan-compiler`.
  */
 export type { HostExecuteGraphRunOptions, MainReadinessPolicy, ExecutionStepOption, StepRetryPolicy, ActivixNodeActivityExellixConfig, SkillKeyResolutionOptions, RunTaskRequest as ExellixGraphRunTaskRequest, RunTaskResponse as ExellixGraphRunTaskResponse, } from './types/options.js';
 export type { AiTaskProfileMetadata, AiTaskProfileWebScoping, AiTaskProfileInputSynthesis, } from './types/aiTaskProfile.js';
@@ -83,11 +83,18 @@ export type { AssertCanonicalGraphDocumentOptions, CanonicalGraphDocumentValidat
 export { assertCanonicalGraphRuntimeObject } from './runtime/validateCanonicalGraphRuntime.js';
 export { GRAPH_ENTRY_STUDIO_ONLY_KEYS, GRAPH_METADATA_STUDIO_ONLY_KEYS, stripGraphModelStudioFields, primaryRuntimeInputFromStudioDocument, getGraphEntryStudioOnlyKeyViolations, getGraphMetadataStudioOnlyKeyViolations, getGraphEntryEmptyInputPathViolations, } from './runtime/graphModelStudioSeparation.js';
 export type { GraphStudioDocument } from './runtime/graphModelStudioSeparation.js';
+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 { 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';
 export { InMemoryGraphLoader, DepGraphEngineFactory } from '../testkit/index.js';

package/dist/src/index.js

@@ -9,8 +9,8 @@
  * 5. Repeat until done/fail
  *
  * Single canonical entry point: {@link createExellixGraphRuntime} returns
- * `{ executeGraph({ model, runtime }: GraphExecutionRequest) }`. The legacy functional `executeGraph`
- * and the `ExellixGraphClient` class were removed in 5.0.
+ * `{ executeGraph({ plan, runtime }: GraphExecutionRequest) }`. Hosts compile upstream via
+ * {@link compileExellixExecutablePlan} or `@x12i/graphenix-plan-compiler`.
  */
 export { mergeGraphDocumentModel, EXELLIX_GRAPH_MODEL_VARIABLE_KEY, EXELLIX_STRUCTURED_DATA_FILTERS_V1, } from './types/refs.js';
 export { getTaskConfiguration } from './types/taskNodeConfiguration.js';
@@ -61,11 +61,15 @@ export { buildExellixGraphRuntimeObjects, setRuntimeObjectsLastJobId, summarizeR
 export { assertCanonicalGraphDocument, assertCanonicalTaskNode, getCanonicalGraphDocumentViolations, CANONICAL_GRAPH_TOP_LEVEL_KEYS, } from './runtime/validateCanonicalGraphDocument.js';
 export { assertCanonicalGraphRuntimeObject } from './runtime/validateCanonicalGraphRuntime.js';
 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 { 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';
 // Graph loaders

package/dist/src/plan/aiModelSelectionWire.d.ts

@@ -0,0 +1,11 @@
+import type { AiModelSelection } from '@x12i/graphenix-executable-contracts';
+import type { ResolvedInvocationSnapshot } from '@x12i/graphenix-executable-contracts';
+/**
+ * Maps plan {@link AiModelSelection} to ai-tasks 8.4+ wire profile strings.
+ */
+export declare function aiModelSelectionToWireString(selection: AiModelSelection | undefined): string | undefined;
+export declare function resolvedSnapshotToWireString(snapshot: ResolvedInvocationSnapshot | undefined): string | undefined;
+export declare function unitModelWireString(args: {
+    modelSelection?: AiModelSelection;
+    resolvedInvocationSnapshot?: ResolvedInvocationSnapshot;
+}): string | undefined;

package/dist/src/plan/aiModelSelectionWire.js

@@ -0,0 +1,39 @@
+/**
+ * Maps plan {@link AiModelSelection} to ai-tasks 8.4+ wire profile strings.
+ */
+export function aiModelSelectionToWireString(selection) {
+    if (selection == null)
+        return undefined;
+    if (selection.kind === 'profileChoice')
+        return selection.key.trim();
+    if (selection.kind === 'profile') {
+        const profile = selection.profile.trim();
+        const choice = typeof selection.choice === 'string' ? selection.choice.trim() : '';
+        return choice ? `${profile}/${choice}` : profile;
+    }
+    if (selection.kind === 'model') {
+        const modelId = typeof selection.modelId === 'string'
+            ? selection.modelId
+            : typeof selection.model === 'string'
+                ? selection.model
+                : '';
+        return `${selection.provider}/${modelId}`.replace(/\/+/g, '/');
+    }
+    return undefined;
+}
+export function resolvedSnapshotToWireString(snapshot) {
+    if (snapshot == null)
+        return undefined;
+    if (snapshot.purpose === 'strictReplay' || snapshot.purpose === 'debugReplay') {
+        return `${snapshot.provider}/${snapshot.modelId}`;
+    }
+    if (snapshot.profileChoiceKey)
+        return snapshot.profileChoiceKey;
+    return undefined;
+}
+export function unitModelWireString(args) {
+    const fromSnapshot = resolvedSnapshotToWireString(args.resolvedInvocationSnapshot);
+    if (fromSnapshot)
+        return fromSnapshot;
+    return aiModelSelectionToWireString(args.modelSelection);
+}

package/dist/src/plan/applyNodePlanInvoke.d.ts

@@ -0,0 +1,10 @@
+import type { FinalizerExecutionPlan, NodeExecutionPlan } from '@x12i/graphenix-executable-contracts';
+import type { TaskNode } from '../types/refs.js';
+/** Merge frozen plan invoke contract onto exellix task node before execution. */
+export declare function applyNodePlanInvoke(node: TaskNode, nodePlan: NodeExecutionPlan): TaskNode;
+export declare function finalizerPlanForId(plan: {
+    finalizerPlans: Record<string, FinalizerExecutionPlan>;
+}, nodeId: string): FinalizerExecutionPlan | undefined;
+export declare function nodePlanForId(plan: {
+    nodePlans: Record<string, NodeExecutionPlan>;
+}, nodeId: string): NodeExecutionPlan | undefined;