@exellix/graph-engine 6.0.2 → 7.0.1

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 7.0.0
+
+### Breaking
+
+- **Model profile aliases only on graph JSON:** `modelConfig` / `taskConfiguration.modelConfig` values must be profile alias names (`strong`, `weak`, `default`, …), not provider model ids. `assertCanonicalGraphDocument` throws `NON_CANONICAL_MODEL_CONFIG` for provider-like strings.
+- **Required `runtime.aliasConfig`:** Every `executeGraph` must supply a non-empty alias → concrete model map covering all aliases used by the graph (including `default`). Missing map or keys throws `MODEL_ALIAS_CONFIG_REQUIRED` / `MODEL_ALIAS_UNRESOLVED`.
+- **No alias pass-through:** Resolved concrete models are sent on `RunTaskRequest.modelConfig` only after strict alias resolution.
+- **Exports:** `collectModelAliasesUsedInGraph`, `assertRuntimeAliasConfigCoversGraph`, `DEFAULT_MODEL_ALIAS`, testkit `createTestExellixGraphRuntime` / `buildTestAliasConfig`.
+
 ## 5.16.0
 
 ### Breaking

package/README.md

@@ -33,6 +33,7 @@ A minimal, focused SDK for executing graphs in the exellix ecosystem.
 | Layer 01 / 08 graph entry & response contracts | [`.docs/graph-io-visibility.md`](.docs/graph-io-visibility.md) |
 | Graph entry `dataFilters` v1 / public evaluator | [`.docs/data-filters-evaluation.md`](.docs/data-filters-evaluation.md) |
 | Task-node `conditions` + conditional `modelConfig.cases` (runx) | [`.docs/task-node-conditions-evaluation.md`](.docs/task-node-conditions-evaluation.md) |
+| **Model profile aliases** (7.x: graph = profile names, runtime = concrete models) | [`BREAKING-CHANGES.md`](BREAKING-CHANGES.md) §7.0.0, [`.docs/ai-tasks-model-profile-aliases-7x.md`](.docs/ai-tasks-model-profile-aliases-7x.md) (ai-tasks), [`.docs/fr-model-alias-descriptors.md`](.docs/fr-model-alias-descriptors.md) (upstream FRs) |
 | Platform vs implementation (no domain operators in schema) | [`.docs/platform-generic-vs-implementation.md`](.docs/platform-generic-vs-implementation.md) |
 | Bundled graph examples & bundle README | [`graphs/README.md`](graphs/README.md) |
 
@@ -112,10 +113,14 @@ const result = await runtime.executeGraph({
     jobId: 'job-123',
     job: { agentId: 'agent-1', input: {} },
     input: { question: 'Analyze this record' },
-    modelConfig: { xynthesisModel: 'xynth-default', skillModel: 'skill-default' },
+    // 7.x: graph modelConfig values are profile aliases; concrete models bind here (required).
+    modelConfig: {
+      cases: [{ modelConfig: { xynthesisModel: 'weak', skillModel: 'strong' } }],
+    },
     aliasConfig: {
-      'xynth-default': 'openrouter/xynthesis-default',
-      'skill-default': 'openrouter/skill-default',
+      strong: 'anthropic/claude-sonnet-4',
+      weak: 'google/gemini-2.5-flash',
+      default: 'google/gemini-2.5-flash',
     },
   },
 });
@@ -164,10 +169,14 @@ interface GraphRuntimeObject {
   taskMemory?: any;
   executionMemory?: any;
   variables?: Record<string, any>;
-  modelConfig?: { xynthesisModel: string; skillModel: string };
-  aliasConfig?: Record<string, string>;
+  /** Run-level model profile override (`cases`); values are alias names, not provider ids. */
+  modelConfig?: { cases: Array<{ when?: unknown; modelConfig: { xynthesisModel: string; skillModel: string } }> };
+  /** Required (7.x): profile alias → concrete provider model id for this execution. */
+  aliasConfig: Record<string, string>;
   nodes?: Record<string, {
+    /** Per-node profile override (alias names). */
     modelConfig?: { xynthesisModel: string; skillModel: string };
+    /** Per-node alias bindings (overlay `aliasConfig`). */
     aliasConfig?: Record<string, string>;
   }>;
   mode?: 'forward' | 'backward' | 'hybrid';
@@ -266,7 +275,11 @@ Graph-engine builds a canonical `RunTaskRequest` for every outbound task call it
 - **Canonical task payload:** **`input`** object only (merged execution slice + **materialized** `node.inputs`). Root-level **`question`**, **`raw`**, **`jobInput`**, duplicate **`inputs`**, and legacy **`executionType`** are **not** sent on the request object.
 - **Graph telemetry:** `graphId`, **`nodeId`**, **`coreSkillId`** (node id), `masterSkillId`, `masterSkillActivityId`, `jobId`, `taskId`, optional `identity`.
 
-To build `RunTaskRequest` without fallback defaults, the execution request must provide both sides of the contract: `model.id`, `node.id`, `node.skillKey`, explicit `node.taskConfiguration.taskTypeId` (even when it matches `skillKey`), `node.taskConfiguration.executionStrategies` (use `[]` for plain MAIN), `runtime.jobId`, `runtime.job.agentId`, `runtime.job.jobTypeId` or `runtime.job.jobType`, active input/memory, and any model/LLM/diagnostic options needed by the task. Model selection uses the exact shape `{ xynthesisModel, skillModel }` from `runtime.nodes[nodeId].modelConfig`, `node.taskConfiguration.modelConfig`, `runtime.modelConfig`, or `model.modelConfig`; aliases are runtime-only and resolve through `runtime.aliasConfig` plus `runtime.nodes[nodeId].aliasConfig`. The resolved model config is forwarded to MAIN, engine PRE/POST utility calls, and `synthesize` finalizer calls. Graph-engine still derives correlation fields such as `graphId`, `nodeId`, `coreSkillId`, `masterSkillId`, `taskId`, and `masterSkillActivityId` from those authored values.
+To build `RunTaskRequest` without fallback defaults, the execution request must provide both sides of the contract: `model.id`, `node.id`, `node.skillKey`, explicit `node.taskConfiguration.taskTypeId` (even when it matches `skillKey`), `node.taskConfiguration.executionStrategies` (use `[]` for plain MAIN), `runtime.jobId`, `runtime.job.agentId`, `runtime.job.jobTypeId` or `runtime.job.jobType`, active input/memory, and any model/LLM/diagnostic options needed by the task.
+
+**Model profiles (7.x):** Graph and node `modelConfig` carry **profile alias names** only (`strong`, `weak`, `default`, …) — never provider model ids in graph JSON. **`runtime.aliasConfig` is required** and maps every alias used by the run (including `default` when fallback applies) to concrete provider models. Selection order: `runtime.nodes[nodeId].modelConfig` → `node.taskConfiguration.modelConfig` → `runtime.modelConfig` → `model.modelConfig` → implicit `{ default, default }`; then strict resolution through `runtime.aliasConfig` plus `runtime.nodes[nodeId].aliasConfig`. The **resolved** `{ xynthesisModel, skillModel }` is forwarded to MAIN, engine PRE/POST utility calls, and `synthesize` finalizer calls. Snapshot `aliasConfig` on execution records for reproducibility. See [`BREAKING-CHANGES.md`](BREAKING-CHANGES.md) §7.0.0.
+
+Graph-engine still derives correlation fields such as `graphId`, `nodeId`, `coreSkillId`, `masterSkillId`, `taskId`, and `masterSkillActivityId` from those authored values.
 
 #### Mandatory `executionStrategies` (breaking vs pre–v7 authoring)
 

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

@@ -27,5 +27,11 @@ export declare enum ExellixGraphErrorCode {
      */
     GRAPH_ENTRY_DATA_FILTERS_REJECTED = "GRAPH_ENTRY_DATA_FILTERS_REJECTED",
     /** MAIN readiness guard rejected empty execution input or synthesis context before runTask. */
-    MAIN_READINESS_FAILED = "MAIN_READINESS_FAILED"
+    MAIN_READINESS_FAILED = "MAIN_READINESS_FAILED",
+    /** `executeGraph` called without a non-empty `runtime.aliasConfig`. */
+    MODEL_ALIAS_CONFIG_REQUIRED = "MODEL_ALIAS_CONFIG_REQUIRED",
+    /** Selected model alias has no concrete model in the merged runtime alias map. */
+    MODEL_ALIAS_UNRESOLVED = "MODEL_ALIAS_UNRESOLVED",
+    /** Graph JSON `modelConfig` contains a provider model id instead of an alias name. */
+    NON_CANONICAL_MODEL_CONFIG = "NON_CANONICAL_MODEL_CONFIG"
 }

package/dist/src/errors/exellixGraphErrorCodes.js

@@ -29,4 +29,10 @@ export var ExellixGraphErrorCode;
     ExellixGraphErrorCode["GRAPH_ENTRY_DATA_FILTERS_REJECTED"] = "GRAPH_ENTRY_DATA_FILTERS_REJECTED";
     /** MAIN readiness guard rejected empty execution input or synthesis context before runTask. */
     ExellixGraphErrorCode["MAIN_READINESS_FAILED"] = "MAIN_READINESS_FAILED";
+    /** `executeGraph` called without a non-empty `runtime.aliasConfig`. */
+    ExellixGraphErrorCode["MODEL_ALIAS_CONFIG_REQUIRED"] = "MODEL_ALIAS_CONFIG_REQUIRED";
+    /** Selected model alias has no concrete model in the merged runtime alias map. */
+    ExellixGraphErrorCode["MODEL_ALIAS_UNRESOLVED"] = "MODEL_ALIAS_UNRESOLVED";
+    /** Graph JSON `modelConfig` contains a provider model id instead of an alias name. */
+    ExellixGraphErrorCode["NON_CANONICAL_MODEL_CONFIG"] = "NON_CANONICAL_MODEL_CONFIG";
 })(ExellixGraphErrorCode || (ExellixGraphErrorCode = {}));

package/dist/src/index.d.ts

@@ -38,7 +38,8 @@ export type { PathSegment } from './runtime/pathExpr.js';
 export { evaluateStructuredDataFilters, evaluateDataFilterPredicate, getStructuredDataFilterPathViolations, isStructuredDataFiltersV1, } from './runtime/dataFiltersEvaluation.js';
 export { evaluateTaskNodeConditions, evaluateConditionWhen, applyConditionNegate, } from './runtime/taskNodeConditionsEvaluation.js';
 export type { TaskNodeConditionsEvalDeps, TaskNodeConditionsEvalResult, TaskNodeConditionEvalContext, } from './runtime/taskNodeConditionsEvaluation.js';
-export { resolveModelConfigForNode, resolveGraphAiModelConfigAliases, } from './runtime/resolveModelConfigForNode.js';
+export { resolveModelConfigForNode, resolveGraphAiModelConfigAliases, mergeAliasConfigs, } from './runtime/resolveModelConfigForNode.js';
+export { DEFAULT_MODEL_ALIAS, DEFAULT_GRAPH_AI_MODEL_ALIAS_CONFIG, isModelAliasString, looksLikeConcreteModelId, assertGraphModelAliasString, collectModelAliasesUsedInGraph, assertRuntimeAliasConfigPresent, assertRuntimeAliasConfigCoversGraph, } from './runtime/modelAliasContract.js';
 export { isGraphAiModelConfig, isModelConfigSelection, isEmptyConditionWhen, conditionWhenSignature, countDefaultModelConfigCases, } from './runtime/modelConfigSelection.js';
 export { GRAPH_ENGINE_MEMORY_PATH_ROOTS, splitGraphEngineMemoryPath, isAllowedGraphEngineMemoryPath, graphEngineMemoryPathValidationMessage, } from './runtime/graphEngineMemoryPaths.js';
 export { buildRunTaskMainInput, extractCallerInputsBag, buildGraphEngineMemoryResolutionRoot, buildGraphEngineMemoryResolutionRootFromWorkingMemory, resolveGraphEngineMemoryPathValue, } from './runtime/resolveGraphEngineMemoryPaths.js';

package/dist/src/index.js

@@ -28,7 +28,8 @@ export { mergeMemory } from './runtime/memory.js';
 export { selectByPath, writeByPath, parsePath } from './runtime/pathExpr.js';
 export { evaluateStructuredDataFilters, evaluateDataFilterPredicate, getStructuredDataFilterPathViolations, isStructuredDataFiltersV1, } from './runtime/dataFiltersEvaluation.js';
 export { evaluateTaskNodeConditions, evaluateConditionWhen, applyConditionNegate, } from './runtime/taskNodeConditionsEvaluation.js';
-export { resolveModelConfigForNode, resolveGraphAiModelConfigAliases, } from './runtime/resolveModelConfigForNode.js';
+export { resolveModelConfigForNode, resolveGraphAiModelConfigAliases, mergeAliasConfigs, } from './runtime/resolveModelConfigForNode.js';
+export { DEFAULT_MODEL_ALIAS, DEFAULT_GRAPH_AI_MODEL_ALIAS_CONFIG, isModelAliasString, looksLikeConcreteModelId, assertGraphModelAliasString, collectModelAliasesUsedInGraph, assertRuntimeAliasConfigPresent, assertRuntimeAliasConfigCoversGraph, } from './runtime/modelAliasContract.js';
 export { isGraphAiModelConfig, isModelConfigSelection, isEmptyConditionWhen, conditionWhenSignature, countDefaultModelConfigCases, } from './runtime/modelConfigSelection.js';
 export { GRAPH_ENGINE_MEMORY_PATH_ROOTS, splitGraphEngineMemoryPath, isAllowedGraphEngineMemoryPath, graphEngineMemoryPathValidationMessage, } from './runtime/graphEngineMemoryPaths.js';
 export { buildRunTaskMainInput, extractCallerInputsBag, buildGraphEngineMemoryResolutionRoot, buildGraphEngineMemoryResolutionRootFromWorkingMemory, resolveGraphEngineMemoryPathValue, } from './runtime/resolveGraphEngineMemoryPaths.js';

package/dist/src/runtime/ExellixGraphRuntime.js

@@ -34,6 +34,7 @@ import { evaluateGraphPredicate } from "./predicates.js";
 import { evaluateStructuredDataFilters } from "./dataFiltersEvaluation.js";
 import { evaluateTaskNodeConditions } from "./taskNodeConditionsEvaluation.js";
 import { resolveModelConfigForNode } from "./resolveModelConfigForNode.js";
+import { assertRuntimeAliasConfigCoversGraph } from "./modelAliasContract.js";
 import { createRunx } from "@x12i/runx";
 import { selectByPath } from "./pathExpr.js";
 import { createGraphStartEvent, createGraphCompleteEvent, createGraphFailEvent, createNodeStartEvent, createNodeCompleteEvent, createNodeFailEvent, } from "./events.js";
@@ -186,19 +187,6 @@ function readRuntimeNodeConfig(nodes, nodeId) {
     const candidate = nodes[nodeId];
     return isPlainRecord(candidate) ? candidate : undefined;
 }
-function mergeAliasConfigs(rootAliases, nodeAliases) {
-    const aliases = {};
-    for (const source of [rootAliases, nodeAliases]) {
-        if (!isPlainRecord(source))
-            continue;
-        for (const [alias, model] of Object.entries(source)) {
-            if (alias.trim() !== "" && typeof model === "string" && model.trim() !== "") {
-                aliases[alias] = model;
-            }
-        }
-    }
-    return Object.keys(aliases).length > 0 ? aliases : undefined;
-}
 function taskNodeNeedsRunxClient(conditions) {
     return conditions?.jsConditionFunction != null || conditions?.aiCondition != null;
 }
@@ -1164,6 +1152,7 @@ export function createExellixGraphRuntime(opts) {
         }
         const resolvedGraphId = String(resolvedGraphIdRaw);
         assertCanonicalGraphDocument(graph, { jobId, graphId: resolvedGraphId });
+        assertRuntimeAliasConfigCoversGraph(graph, merged.aliasConfig, { modelConfig: merged.modelConfig, nodes: merged.nodes }, { jobId, graphId: resolvedGraphId });
         let runxClient = opts.runx;
         if (graphNeedsRunxClient(graph, merged.modelConfig)) {
             if (!runxClient) {
@@ -1590,6 +1579,9 @@ export function createExellixGraphRuntime(opts) {
                         }),
                         executionInput: dataFiltersRecord,
                         runx: runxClient,
+                        graphId: resolvedGraphId,
+                        nodeId: typeof node.id === "string" ? node.id : String(node.id),
+                        jobId,
                     });
                     const r = await executeNode({
                         graphId: resolvedGraphId,

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

@@ -0,0 +1,46 @@
+import type { Graph, GraphAiModelConfig, GraphModelAliasConfig, ModelConfigSelection } from '../types/refs.js';
+/** Fallback alias pair when no modelConfig tier resolves. */
+export declare const DEFAULT_MODEL_ALIAS = "default";
+export declare const DEFAULT_GRAPH_AI_MODEL_ALIAS_CONFIG: GraphAiModelConfig;
+/**
+ * True when a string is a valid graph-authored model alias (not a provider model id).
+ */
+export declare function isModelAliasString(value: unknown): value is string;
+/** True when a value looks like a concrete provider model id (forbidden in graph JSON). */
+export declare function looksLikeConcreteModelId(value: string): boolean;
+export declare function assertGraphModelAliasString(value: unknown, path: string, context?: {
+    jobId?: string;
+    graphId?: string;
+    nodeId?: string;
+}): asserts value is string;
+export declare function mergeAliasConfigs(root?: GraphModelAliasConfig, node?: GraphModelAliasConfig): GraphModelAliasConfig;
+/**
+ * Collects every alias name referenced by graph + optional runtime overrides (before resolution).
+ * Always includes `default` because resolution may fall back to it.
+ */
+export declare function collectModelAliasesUsedInGraph(graph: Pick<Graph, 'modelConfig' | 'nodes'>, runtime?: {
+    modelConfig?: ModelConfigSelection;
+    nodes?: Record<string, {
+        modelConfig?: GraphAiModelConfig;
+        aliasConfig?: GraphModelAliasConfig;
+    }>;
+}): Set<string>;
+export declare function assertRuntimeAliasConfigPresent(aliasConfig: GraphModelAliasConfig | undefined, context?: {
+    jobId?: string;
+    graphId?: string;
+}): asserts aliasConfig is GraphModelAliasConfig;
+/**
+ * Ensures merged runtime alias map covers every alias used by the graph (+ runtime overrides).
+ */
+export declare function assertRuntimeAliasConfigCoversGraph(graph: Pick<Graph, 'id' | 'modelConfig' | 'nodes'>, aliasConfig: GraphModelAliasConfig | undefined, runtime?: Parameters<typeof collectModelAliasesUsedInGraph>[1], context?: {
+    jobId?: string;
+    graphId?: string;
+}): void;
+/**
+ * Resolves alias-only {@link GraphAiModelConfig} to concrete provider model ids via runtime map.
+ */
+export declare function resolveGraphAiModelConfigAliases(modelConfig: GraphAiModelConfig | undefined, aliasConfig: GraphModelAliasConfig | undefined, context?: {
+    jobId?: string;
+    graphId?: string;
+    nodeId?: string;
+}): GraphAiModelConfig | undefined;

package/dist/src/runtime/modelAliasContract.js

@@ -0,0 +1,129 @@
+import { ExellixGraphError } from '../errors/ExellixGraphError.js';
+import { ExellixGraphErrorCode } from '../errors/exellixGraphErrorCodes.js';
+import { isGraphAiModelConfig, isModelConfigSelection } from './modelConfigSelection.js';
+/** Fallback alias pair when no modelConfig tier resolves. */
+export const DEFAULT_MODEL_ALIAS = 'default';
+export const DEFAULT_GRAPH_AI_MODEL_ALIAS_CONFIG = {
+    xynthesisModel: DEFAULT_MODEL_ALIAS,
+    skillModel: DEFAULT_MODEL_ALIAS,
+};
+const CONCRETE_MODEL_PREFIXES = ['openrouter/', 'anthropic/', 'openai/', 'google/', 'x-ai/', 'meta-llama/'];
+/**
+ * True when a string is a valid graph-authored model alias (not a provider model id).
+ */
+export function isModelAliasString(value) {
+    if (typeof value !== 'string')
+        return false;
+    const trimmed = value.trim();
+    if (trimmed === '')
+        return false;
+    return !looksLikeConcreteModelId(trimmed);
+}
+/** True when a value looks like a concrete provider model id (forbidden in graph JSON). */
+export function looksLikeConcreteModelId(value) {
+    const trimmed = value.trim();
+    if (trimmed.includes('/'))
+        return true;
+    const lower = trimmed.toLowerCase();
+    return CONCRETE_MODEL_PREFIXES.some((p) => lower.startsWith(p));
+}
+export function assertGraphModelAliasString(value, path, context) {
+    if (!isModelAliasString(value)) {
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_MODEL_CONFIG, `${path} must be a model alias name (non-empty string without "/" or provider prefixes); got ${JSON.stringify(value)}`, context);
+    }
+}
+export function mergeAliasConfigs(root, node) {
+    const aliases = {};
+    for (const source of [root, node]) {
+        if (source == null || typeof source !== 'object' || Array.isArray(source))
+            continue;
+        for (const [alias, model] of Object.entries(source)) {
+            if (alias.trim() !== '' && typeof model === 'string' && model.trim() !== '') {
+                aliases[alias] = model;
+            }
+        }
+    }
+    return aliases;
+}
+function collectAliasesFromGraphAiModelConfig(config, out) {
+    if (!isGraphAiModelConfig(config))
+        return;
+    out.add(config.xynthesisModel.trim());
+    out.add(config.skillModel.trim());
+}
+function collectAliasesFromModelConfigSelection(selection, out) {
+    if (!isModelConfigSelection(selection))
+        return;
+    for (const c of selection.cases) {
+        collectAliasesFromGraphAiModelConfig(c.modelConfig, out);
+    }
+}
+/**
+ * Collects every alias name referenced by graph + optional runtime overrides (before resolution).
+ * Always includes `default` because resolution may fall back to it.
+ */
+export function collectModelAliasesUsedInGraph(graph, runtime) {
+    const out = new Set([DEFAULT_MODEL_ALIAS]);
+    collectAliasesFromModelConfigSelection(graph.modelConfig, out);
+    for (const node of graph.nodes ?? []) {
+        const tn = node;
+        if (tn.type === 'finalizer')
+            continue;
+        collectAliasesFromModelConfigSelection(tn.taskConfiguration?.modelConfig, out);
+    }
+    if (runtime != null) {
+        collectAliasesFromModelConfigSelection(runtime.modelConfig, out);
+        if (runtime.nodes != null && typeof runtime.nodes === 'object') {
+            for (const nodeRuntime of Object.values(runtime.nodes)) {
+                if (nodeRuntime == null || typeof nodeRuntime !== 'object')
+                    continue;
+                collectAliasesFromGraphAiModelConfig(nodeRuntime.modelConfig, out);
+            }
+        }
+    }
+    return out;
+}
+export function assertRuntimeAliasConfigPresent(aliasConfig, context) {
+    if (aliasConfig == null ||
+        typeof aliasConfig !== 'object' ||
+        Array.isArray(aliasConfig) ||
+        Object.keys(aliasConfig).length === 0) {
+        throw new ExellixGraphError(ExellixGraphErrorCode.MODEL_ALIAS_CONFIG_REQUIRED, 'runtime.aliasConfig is required and must be a non-empty map of alias name → concrete model id', context);
+    }
+}
+/**
+ * Ensures merged runtime alias map covers every alias used by the graph (+ runtime overrides).
+ */
+export function assertRuntimeAliasConfigCoversGraph(graph, aliasConfig, runtime, context) {
+    assertRuntimeAliasConfigPresent(aliasConfig, context);
+    const needed = collectModelAliasesUsedInGraph(graph, runtime);
+    const missing = [];
+    for (const alias of needed) {
+        const concrete = aliasConfig[alias];
+        if (typeof concrete !== 'string' || concrete.trim() === '') {
+            missing.push(alias);
+        }
+    }
+    if (missing.length > 0) {
+        throw new ExellixGraphError(ExellixGraphErrorCode.MODEL_ALIAS_UNRESOLVED, `runtime.aliasConfig is missing concrete models for alias(es): ${missing.join(', ')}`, { ...context, graphId: context?.graphId ?? graph.id, missingAliases: missing });
+    }
+}
+function resolveModelAliasStrict(alias, aliasConfig, context) {
+    const concrete = aliasConfig[alias];
+    if (typeof concrete !== 'string' || concrete.trim() === '') {
+        throw new ExellixGraphError(ExellixGraphErrorCode.MODEL_ALIAS_UNRESOLVED, `Unresolved model alias "${alias}" — add it to runtime.aliasConfig (and runtime.nodes[nodeId].aliasConfig when scoped per node)`, { ...context, alias });
+    }
+    return concrete.trim();
+}
+/**
+ * Resolves alias-only {@link GraphAiModelConfig} to concrete provider model ids via runtime map.
+ */
+export function resolveGraphAiModelConfigAliases(modelConfig, aliasConfig, context) {
+    if (!isGraphAiModelConfig(modelConfig))
+        return undefined;
+    assertRuntimeAliasConfigPresent(aliasConfig, context);
+    return {
+        xynthesisModel: resolveModelAliasStrict(modelConfig.xynthesisModel, aliasConfig, context),
+        skillModel: resolveModelAliasStrict(modelConfig.skillModel, aliasConfig, context),
+    };
+}

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

@@ -11,10 +11,14 @@ export type ResolveModelConfigForNodeArgs = {
     conditionCtx: TaskNodeConditionEvalContext;
     executionInput: Record<string, unknown>;
     runx?: RunxClient;
+    graphId?: string;
+    nodeId?: string;
+    jobId?: string;
 };
-export declare function resolveGraphAiModelConfigAliases(modelConfig: GraphAiModelConfig | undefined, aliasConfig: GraphModelAliasConfig | undefined): GraphAiModelConfig | undefined;
 /**
- * Resolves effective model config for a task node (precedence + conditional cases + aliases).
+ * Resolves effective model config for a task node (precedence + conditional cases + strict alias resolution).
+ * Returns concrete provider model ids for `RunTaskRequest.modelConfig`.
  */
-export declare function resolveModelConfigForNode(args: ResolveModelConfigForNodeArgs): Promise<GraphAiModelConfig | undefined>;
+export declare function resolveModelConfigForNode(args: ResolveModelConfigForNodeArgs): Promise<GraphAiModelConfig>;
 export { conditionWhenSignature, isEmptyConditionWhen };
+export { resolveGraphAiModelConfigAliases, mergeAliasConfigs } from './modelAliasContract.js';

package/dist/src/runtime/resolveModelConfigForNode.js

@@ -1,21 +1,6 @@
 import { conditionWhenSignature, isEmptyConditionWhen, isGraphAiModelConfig, isModelConfigSelection, } from './modelConfigSelection.js';
 import { evaluateConditionWhen } from './taskNodeConditionsEvaluation.js';
-function resolveModelAlias(modelOrAlias, aliases) {
-    return aliases?.[modelOrAlias] ?? modelOrAlias;
-}
-function mergeAliasConfigs(root, node) {
-    if (root == null && node == null)
-        return undefined;
-    return { ...(root ?? {}), ...(node ?? {}) };
-}
-export function resolveGraphAiModelConfigAliases(modelConfig, aliasConfig) {
-    if (!isGraphAiModelConfig(modelConfig))
-        return undefined;
-    return {
-        xynthesisModel: resolveModelAlias(modelConfig.xynthesisModel, aliasConfig),
-        skillModel: resolveModelAlias(modelConfig.skillModel, aliasConfig),
-    };
-}
+import { DEFAULT_GRAPH_AI_MODEL_ALIAS_CONFIG, mergeAliasConfigs, resolveGraphAiModelConfigAliases, } from './modelAliasContract.js';
 async function selectFromCases(selection, ctx, executionInput, runx) {
     const cases = selection.cases;
     if (!Array.isArray(cases) || cases.length === 0)
@@ -49,21 +34,24 @@ async function resolveTier(value, ctx, executionInput, runx) {
     return undefined;
 }
 /**
- * Resolves effective model config for a task node (precedence + conditional cases + aliases).
+ * Resolves effective model config for a task node (precedence + conditional cases + strict alias resolution).
+ * Returns concrete provider model ids for `RunTaskRequest.modelConfig`.
  */
 export async function resolveModelConfigForNode(args) {
     const aliasConfig = mergeAliasConfigs(args.runtimeAliasConfig, args.runtimeNodeConfig?.aliasConfig);
+    const resolveCtx = { graphId: args.graphId, nodeId: args.nodeId, jobId: args.jobId };
     const staticHost = args.runtimeNodeConfig?.modelConfig;
     if (isGraphAiModelConfig(staticHost)) {
-        return resolveGraphAiModelConfigAliases(staticHost, aliasConfig);
+        return resolveGraphAiModelConfigAliases(staticHost, aliasConfig, resolveCtx);
     }
     const tiers = [args.nodeModelConfig, args.runtimeModelConfig, args.graphModelConfig];
     for (const tier of tiers) {
         const selected = await resolveTier(tier, args.conditionCtx, args.executionInput, args.runx);
         if (selected != null) {
-            return resolveGraphAiModelConfigAliases(selected, aliasConfig);
+            return resolveGraphAiModelConfigAliases(selected, aliasConfig, resolveCtx);
         }
     }
-    return undefined;
+    return resolveGraphAiModelConfigAliases(DEFAULT_GRAPH_AI_MODEL_ALIAS_CONFIG, aliasConfig, resolveCtx);
 }
 export { conditionWhenSignature, isEmptyConditionWhen };
+export { resolveGraphAiModelConfigAliases, mergeAliasConfigs } from './modelAliasContract.js';

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

@@ -5,7 +5,7 @@
 import type { Catalox } from '@x12i/catalox';
 import type { RunTaskRequest } from '@exellix/ai-tasks';
 import { type AnalyzeRunTaskRequestOptions, type AnalyzeRunTaskRequestResult, type RunTaskInvokeValidationResult, type RunTaskValidationResult, type ValidateRunTaskInvokeParams } from '@exellix/ai-tasks';
-import type { GraphAiModelConfig, Job, TaskNode } from '../types/refs.js';
+import type { GraphAiModelConfig, GraphModelAliasConfig, Job, TaskNode } from '../types/refs.js';
 import type { ExecutionStepOption, RunTaskDiagnostics, SkillKeyResolutionOptions } from '../types/options.js';
 export type TaskNodeRunTaskPreflightSkipReason = 'local_skill' | 'finalizer';
 export type BuildTaskNodeRunTaskRequestResult = {
@@ -30,7 +30,10 @@ export type BuildTaskNodeRunTaskRequestArgs = {
     graphRunTaskId?: string;
     /** Host job id on `job.jobId` / `job.id`; defaults from `job` when omitted. */
     runTaskJobId?: string;
+    /** Alias-only selection; resolved via `aliasConfig` before building the request. */
     modelConfig?: GraphAiModelConfig;
+    /** Required when resolving `modelConfig` aliases for preflight (mirrors `runtime.aliasConfig`). */
+    aliasConfig?: GraphModelAliasConfig;
     llmCall?: Record<string, unknown>;
     /** Runtime default merged with per-node `taskConfiguration.llmCall`. */
     runtimeLlmCall?: Record<string, unknown>;

package/dist/src/runtime/taskNodeRunTaskPreflight.js

@@ -1,4 +1,5 @@
 import { analyzeRunTaskRequest, validateRunTaskConfig, validateRunTaskInvoke, } from '@exellix/ai-tasks';
+import { resolveGraphAiModelConfigAliases } from './modelAliasContract.js';
 import { resolveTaskKey } from './resolveTaskKey.js';
 import { isLocalSkillKey } from './localSkills/index.js';
 import { buildAiTasksRunTaskRequest, extractRunTaskStrategyOverrides, } from './buildAiTasksRunTaskRequest.js';
@@ -121,6 +122,13 @@ export function buildTaskNodeRunTaskRequest(args) {
     });
     const metaStrats = node.taskConfiguration?.executionStrategies;
     const ov = node.taskConfiguration?.aiTasksOutputValidation;
+    const resolvedModelConfig = args.modelConfig != null && args.aliasConfig != null
+        ? resolveGraphAiModelConfigAliases(args.modelConfig, args.aliasConfig, {
+            graphId: args.graphId,
+            nodeId: String(node.id),
+            jobId: lifecycleJobId,
+        })
+        : args.modelConfig;
     const request = buildAiTasksRunTaskRequest({
         skillKey,
         job: args.job,
@@ -145,7 +153,7 @@ export function buildTaskNodeRunTaskRequest(args) {
             ? ov
             : undefined,
         diagnostics: args.runTaskDiagnostics,
-        modelConfig: args.modelConfig ?? undefined,
+        modelConfig: resolvedModelConfig ?? undefined,
         llmCall: effectiveLlmCall,
         identity: buildRunTaskIdentityEnvelope({
             base: args.runTaskIdentity,

package/dist/src/runtime/validateCanonicalGraphDocument.js

@@ -4,6 +4,7 @@ import { ExellixGraphErrorCode } from '../errors/exellixGraphErrorCodes.js';
 import { EXELLIX_VIRTUAL_BOUNDARY_NODE_METADATA_KEY } from '../inspection/types.js';
 import { getStructuredDataFilterPathViolations } from './dataFiltersEvaluation.js';
 import { conditionWhenSignature, countDefaultModelConfigCases, isEmptyConditionWhen, isGraphAiModelConfig, isModelConfigSelection, } from './modelConfigSelection.js';
+import { assertGraphModelAliasString } from './modelAliasContract.js';
 /** Top-level keys permitted on a canonical exellix-graph executable graph JSON document. */
 export const CANONICAL_GRAPH_TOP_LEVEL_KEYS = [
     'id',
@@ -296,8 +297,10 @@ function assertModelConfigSelection(value, path, context) {
             throw new ExellixGraphError(code, `${casePath} must be a plain object.`, context);
         }
         if (!isGraphAiModelConfig(c.modelConfig)) {
-            throw new ExellixGraphError(code, `${casePath}.modelConfig must be { xynthesisModel: string, skillModel: string } with non-empty values.`, context);
+            throw new ExellixGraphError(code, `${casePath}.modelConfig must be { xynthesisModel: string, skillModel: string } with non-empty alias values.`, context);
         }
+        assertGraphModelAliasString(c.modelConfig.xynthesisModel, `${casePath}.modelConfig.xynthesisModel`, context);
+        assertGraphModelAliasString(c.modelConfig.skillModel, `${casePath}.modelConfig.skillModel`, context);
         if (isEmptyConditionWhen(c.when)) {
             continue;
         }
@@ -318,8 +321,10 @@ function assertOptionalRuntimeFlatModelConfig(value, path, context) {
     if (value === undefined)
         return;
     if (!isGraphAiModelConfig(value)) {
-        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE, `${path} must be exactly { xynthesisModel: string, skillModel: string } (runtime host override does not use cases).`, context);
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE, `${path} must be exactly { xynthesisModel: string, skillModel: string } alias names (runtime host override does not use cases).`, context);
     }
+    assertGraphModelAliasString(value.xynthesisModel, `${path}.xynthesisModel`, context);
+    assertGraphModelAliasString(value.skillModel, `${path}.skillModel`, context);
 }
 function assertContextualKnowledgeScope(scope, nodeId, context) {
     if (scope === undefined)

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

@@ -13,14 +13,14 @@ export type TaskNodeExecutionPipelineStep = {
  * Type references for graph execution
  */
 /**
- * Explicit AI model selection carried by graph model/runtime contracts.
- * Values may be concrete model ids or runtime aliases resolved before `runTask`.
+ * Alias-only AI model slot selection on graph model / node `modelConfig`.
+ * Concrete provider model ids are supplied only via {@link GraphModelAliasConfig} at execution.
  */
 export type GraphAiModelConfig = {
     xynthesisModel: string;
     skillModel: string;
 };
-/** Runtime alias map used to resolve GraphAiModelConfig values before dispatch. */
+/** Runtime map: alias name → concrete provider model id (required on every `executeGraph`). */
 export type GraphModelAliasConfig = Record<string, string>;
 /** Runtime overrides for a single task node, stored at GraphRuntimeObject.nodes[nodeId]. */
 export type TaskNodeRuntimeObject = {

package/dist/testkit/index.d.ts

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

package/dist/testkit/index.js

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

package/dist/testkit/testModelAliasRuntime.d.ts

@@ -0,0 +1,14 @@
+import type { Graph } from '../src/types/refs.js';
+import { createExellixGraphRuntime, type GraphRuntimeObject } from '../src/runtime/ExellixGraphRuntime.js';
+/** Maps every alias used by a graph (plus `default`) to `openrouter/<alias>` for unit tests. */
+export declare function buildTestAliasConfig(graph: Pick<Graph, 'modelConfig' | 'nodes'>, runtimePartial?: Pick<GraphRuntimeObject, 'modelConfig' | 'nodes'> & {
+    aliasConfig?: Record<string, string>;
+}): Record<string, string>;
+/** Merges test alias bindings into a runtime object (required for executeGraph in 7.x). */
+export declare function withTestAliasRuntime(graph: Pick<Graph, 'id' | 'modelConfig' | 'nodes'>, runtime: Partial<GraphRuntimeObject> & Pick<GraphRuntimeObject, 'jobId' | 'job'>): GraphRuntimeObject;
+type CreateOpts = Parameters<typeof createExellixGraphRuntime>[0];
+/**
+ * Testkit runtime that auto-injects `runtime.aliasConfig` on every `executeGraph` call.
+ */
+export declare function createTestExellixGraphRuntime(opts: CreateOpts): ReturnType<typeof createExellixGraphRuntime>;
+export {};

package/dist/testkit/testModelAliasRuntime.js

@@ -0,0 +1,40 @@
+import { createExellixGraphRuntime, } from '../src/runtime/ExellixGraphRuntime.js';
+import { collectModelAliasesUsedInGraph } from '../src/runtime/modelAliasContract.js';
+/** Maps every alias used by a graph (plus `default`) to `openrouter/<alias>` for unit tests. */
+export function buildTestAliasConfig(graph, runtimePartial) {
+    const needed = collectModelAliasesUsedInGraph(graph, runtimePartial);
+    const map = {};
+    for (const alias of needed) {
+        map[alias] = `openrouter/${alias}`;
+    }
+    return { ...map, ...(runtimePartial?.aliasConfig ?? {}) };
+}
+/** Merges test alias bindings into a runtime object (required for executeGraph in 7.x). */
+export function withTestAliasRuntime(graph, runtime) {
+    const aliasConfig = buildTestAliasConfig(graph, runtime);
+    return {
+        ...runtime,
+        aliasConfig,
+    };
+}
+/**
+ * Testkit runtime that auto-injects `runtime.aliasConfig` on every `executeGraph` call.
+ */
+export function createTestExellixGraphRuntime(opts) {
+    const runtime = createExellixGraphRuntime(opts);
+    const executeGraph = runtime.executeGraph.bind(runtime);
+    runtime.executeGraph = async (input) => {
+        const base = input.runtime ?? {};
+        const jobId = typeof base.jobId === 'string' && base.jobId.trim() !== ''
+            ? base.jobId
+            : `job-${input.model.id ?? 'graph'}`;
+        const job = base.job != null && typeof base.job === 'object'
+            ? base.job
+            : { agentId: 'test-agent', jobType: 'unit-test' };
+        return executeGraph({
+            ...input,
+            runtime: withTestAliasRuntime(input.model, { ...base, jobId, job }),
+        });
+    };
+    return runtime;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exellix/graph-engine",
-  "version": "6.0.2",
+  "version": "7.0.1",
   "type": "module",
   "description": "Graph executor SDK",
   "main": "dist/src/index.js",
@@ -25,7 +25,8 @@
   "scripts": {
     "prebuild": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true, maxRetries: 10, retryDelay: 100 })\"",
     "build": "tsc",
-    "test": "npm run build && npm run check:no-legacy && tsx --test --test-force-exit tests/graph-engine.test.ts tests/passthrough-parity.test.ts tests/task-node-run-task-preflight.test.ts tests/reports-fixtures-pre-synthesis.test.ts",
+    "test": "npm run build && npm run check:no-legacy && node --test --test-force-exit tests/model-alias-contract.test.ts tests/reports-fixtures-pre-synthesis.test.ts tests/passthrough-parity.test.ts",
+    "test:full": "npm run build && npm run check:no-legacy && tsx --test --test-force-exit tests/graph-engine.test.ts tests/passthrough-parity.test.ts tests/task-node-run-task-preflight.test.ts tests/reports-fixtures-pre-synthesis.test.ts tests/model-alias-contract.test.ts",
     "run:pre-synthesis": "npm run build && node --env-file=.env scripts/run-pre-synthesis-graph.mjs",
     "check:no-legacy": "node scripts/check-no-legacy.mjs",
     "lint": "eslint src testkit --ext .ts",
@@ -48,7 +49,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@exellix/ai-tasks": "^7.8.2",
+    "@exellix/ai-tasks": "^8.0.0",
     "@x12i/activix": "^7.1.0",
     "@x12i/catalox": "^5.1.1",
     "@x12i/env": "^4.0.1",