@exellix/graph-engine 7.7.5 → 7.7.8

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 7.7.8
+
+### Added (CR-11 execute-time model routing)
+
+- **`mergeGraphAiModelConfig`**, **`PartialGraphAiModelConfig`**, **`isPartialGraphAiModelConfig`** — job-default + per-task partial override merge at execute time (`task[slot] ?? graph[slot] ?? engine default`).
+- **`assertCanonicalGraphDocument(..., { mode: 'execute' })`** — accepts partial task `taskConfiguration.modelConfig` and `profile/choice` slot encoding (`cheap/default`, `cyber/deep_forensics`); **`persist`** mode (default) unchanged for save/inspection paths.
+- **`executeGraph`** uses execute-mode validation so hosts can POST authored graph JSON without pre-merging model slots or stripping `/`.
+
+### Changed
+
+- **`looksLikeConcreteModelId`** — only provider-prefixed ids are concrete; `profile/choice` strings are valid graph aliases.
+- **`inspectGraphModelSelection`** — reports merged effective routing when task overrides are partial.
+
+### Migration (hosts / graphs-studio)
+
+- Remove execute-time `skipCanonicalAssert`, host-side job→node model merge, and slot `/` stripping once on **7.7.8+** (see CR-11 / CR-9).
+
 ## 7.7.3
 
 ### Changed

package/dist/src/index.d.ts

@@ -15,7 +15,7 @@
 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';
 export type { ExecutionStrategyInvocation, ExecutionStrategyPhase, ExecutionStrategyWrapperKey, SmartInputConfig, TaskStrategyItemData, XynthesizedDestinationScope, XynthesizedMemory, XynthesizedOutputConfig, } from './types/aiTasksDerivedTypes.js';
-export type { Graph, GraphModelObject, GraphAiModelConfig, GraphModelAliasConfig, GraphRuntimeNodeConfig, TaskNodeRuntimeObject, GraphDocumentMetadata, GraphEntryContract, GraphEntryExecutionInputSpec, GraphEntryInputKind, GraphEntryInputSpecBase, GraphEntryInputSpec, GraphEntryValueInputKind, GraphEntryValueInputSpec, GraphResponseDefinition, GraphResponseMissingBehavior, GraphResponseSelector, GraphResponseShape, GraphResponseContract, GraphResponseMapping, GraphResponseMappingMissingBehavior, GraphResponseMappingSelector, GraphResponseMappingTarget, GraphExecutionDefaults, GraphExecutionMode, GraphOutputMode, GraphFlowOutline, GraphCoreObjective, GraphNodesResponses, GraphNode, TaskNode, TaskNodeConditions, TaskNodeConditionWhen, TaskNodeJsonCondition, TaskNodeJsConditionFunction, TaskNodeAiCondition, TaskNodeConditionParameters, ModelConfigSelection, ModelConfigCase, TaskNodePureMetadata, TaskNodeExecutionPipelineStep, TaskOutputValidation, FinalizerNode, FinalizerInputBinding, OutputSchema, AggregateFinalizerConfig, BundleFinalizerConfig, SelectFinalizerConfig, SynthesizeFinalizerConfig, UtilityExecutionPolicy, Job, CatalogPlanningKind, CatalogRequestStatus, CatalogBinding, ScopedQuestionCatalogRequestEntry, DiscoveryDefinitionCatalogRequestEntry, DiscoveryDefinitionCatalogRequest, DiscoveryDefinitionPlanningFields, CatalogRequestEntry, StructuredDataFiltersV1, ConditionsDataFilters, } from './types/refs.js';
+export type { Graph, GraphModelObject, GraphAiModelConfig, PartialGraphAiModelConfig, GraphModelAliasConfig, GraphRuntimeNodeConfig, TaskNodeRuntimeObject, GraphDocumentMetadata, GraphEntryContract, GraphEntryExecutionInputSpec, GraphEntryInputKind, GraphEntryInputSpecBase, GraphEntryInputSpec, GraphEntryValueInputKind, GraphEntryValueInputSpec, GraphResponseDefinition, GraphResponseMissingBehavior, GraphResponseSelector, GraphResponseShape, GraphResponseContract, GraphResponseMapping, GraphResponseMappingMissingBehavior, GraphResponseMappingSelector, GraphResponseMappingTarget, GraphExecutionDefaults, GraphExecutionMode, GraphOutputMode, GraphFlowOutline, GraphCoreObjective, GraphNodesResponses, GraphNode, TaskNode, TaskNodeConditions, TaskNodeConditionWhen, TaskNodeJsonCondition, TaskNodeJsConditionFunction, TaskNodeAiCondition, TaskNodeConditionParameters, ModelConfigSelection, ModelConfigCase, TaskNodePureMetadata, TaskNodeExecutionPipelineStep, TaskOutputValidation, FinalizerNode, FinalizerInputBinding, OutputSchema, AggregateFinalizerConfig, BundleFinalizerConfig, SelectFinalizerConfig, SynthesizeFinalizerConfig, UtilityExecutionPolicy, Job, CatalogPlanningKind, CatalogRequestStatus, CatalogBinding, ScopedQuestionCatalogRequestEntry, DiscoveryDefinitionCatalogRequestEntry, DiscoveryDefinitionCatalogRequest, DiscoveryDefinitionPlanningFields, CatalogRequestEntry, StructuredDataFiltersV1, ConditionsDataFilters, } from './types/refs.js';
 export { mergeGraphDocumentModel, EXELLIX_GRAPH_MODEL_VARIABLE_KEY, EXELLIX_STRUCTURED_DATA_FILTERS_V1, } from './types/refs.js';
 export type { TaskNodeTaskConfiguration, TaskNodeScopedDataReaderPackSlot, } from './types/taskNodeConfiguration.js';
 export { getTaskConfiguration } from './types/taskNodeConfiguration.js';
@@ -39,7 +39,7 @@ 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, resolveGraphAiModelConfig, toRunTaskModelConfig, DEFAULT_GRAPH_AI_MODEL_IDS, DEFAULT_GRAPH_AI_MODEL_PROFILE_CONFIG, } from './runtime/resolveModelConfigForNode.js';
+export { resolveModelConfigForNode, resolveGraphAiModelConfig, toRunTaskModelConfig, mergeGraphAiModelConfig, DEFAULT_GRAPH_AI_MODEL_IDS, DEFAULT_GRAPH_AI_MODEL_PROFILE_CONFIG, } from './runtime/resolveModelConfigForNode.js';
 export { looksLikeConcreteModelId, isGraphAiProfileName, assertGraphAiProfileNameString, type RunTaskModelConfigWire, type EngineModelPhase, } from './runtime/graphAiModelConfig.js';
 /** @deprecated Use {@link resolveGraphAiModelConfig}. */
 export { resolveGraphAiModelConfig as resolveGraphAiModelConfigAliases } from './runtime/graphAiModelConfig.js';
@@ -47,7 +47,7 @@ export { resolveGraphAiModelConfig as resolveGraphAiModelConfigAliases } from '.
 export { isGraphAiProfileName as isModelAliasString } from './runtime/graphAiModelConfig.js';
 /** @deprecated Use {@link assertGraphAiProfileNameString}. */
 export { assertGraphAiProfileNameString as assertGraphModelAliasString } from './runtime/graphAiModelConfig.js';
-export { isGraphAiModelConfig, isModelConfigSelection, isEmptyConditionWhen, conditionWhenSignature, countDefaultModelConfigCases, } from './runtime/modelConfigSelection.js';
+export { isGraphAiModelConfig, isPartialGraphAiModelConfig, 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';
 export { mirrorStructuredInputOntoExecutionMemory, } from './runtime/materializeStructuredRunTaskInput.js';
@@ -79,6 +79,7 @@ export { buildExellixGraphRuntimeObjects, setRuntimeObjectsLastJobId, summarizeR
 export type { ActivixQueryableClient, LogxerQueryableClient, LogxerLogLine, PackageRuntimeObjects, RuntimeObjects, BuildExellixGraphRuntimeObjectsInput, RuntimeObjectsObservabilitySummary, } from './runtime/runtimeObjects.js';
 export type { GetJobLogsInput, GetJobLogsResult, QueryableLogLine } from '@x12i/logxer';
 export { assertCanonicalGraphDocument, assertCanonicalTaskNode, getCanonicalGraphDocumentViolations, CANONICAL_GRAPH_TOP_LEVEL_KEYS, } from './runtime/validateCanonicalGraphDocument.js';
+export type { AssertCanonicalGraphDocumentOptions, CanonicalGraphDocumentValidationMode, } 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 type { GraphStudioDocument } from './runtime/graphModelStudioSeparation.js';

package/dist/src/index.js

@@ -29,7 +29,7 @@ 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, resolveGraphAiModelConfig, toRunTaskModelConfig, DEFAULT_GRAPH_AI_MODEL_IDS, DEFAULT_GRAPH_AI_MODEL_PROFILE_CONFIG, } from './runtime/resolveModelConfigForNode.js';
+export { resolveModelConfigForNode, resolveGraphAiModelConfig, toRunTaskModelConfig, mergeGraphAiModelConfig, DEFAULT_GRAPH_AI_MODEL_IDS, DEFAULT_GRAPH_AI_MODEL_PROFILE_CONFIG, } from './runtime/resolveModelConfigForNode.js';
 export { looksLikeConcreteModelId, isGraphAiProfileName, assertGraphAiProfileNameString, } from './runtime/graphAiModelConfig.js';
 /** @deprecated Use {@link resolveGraphAiModelConfig}. */
 export { resolveGraphAiModelConfig as resolveGraphAiModelConfigAliases } from './runtime/graphAiModelConfig.js';
@@ -37,7 +37,7 @@ export { resolveGraphAiModelConfig as resolveGraphAiModelConfigAliases } from '.
 export { isGraphAiProfileName as isModelAliasString } from './runtime/graphAiModelConfig.js';
 /** @deprecated Use {@link assertGraphAiProfileNameString}. */
 export { assertGraphAiProfileNameString as assertGraphModelAliasString } from './runtime/graphAiModelConfig.js';
-export { isGraphAiModelConfig, isModelConfigSelection, isEmptyConditionWhen, conditionWhenSignature, countDefaultModelConfigCases, } from './runtime/modelConfigSelection.js';
+export { isGraphAiModelConfig, isPartialGraphAiModelConfig, 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';
 export { mirrorStructuredInputOntoExecutionMemory, } from './runtime/materializeStructuredRunTaskInput.js';

package/dist/src/inspection/graphModelSelection.js

@@ -1,16 +1,17 @@
-import { isEmptyConditionWhen, isModelConfigSelection } from '../runtime/modelConfigSelection.js';
-import { DEFAULT_GRAPH_AI_MODEL_PROFILE_CONFIG } from '../runtime/graphAiModelConfig.js';
+import { isEmptyConditionWhen, isModelConfigSelection, isPartialGraphAiModelConfig } from '../runtime/modelConfigSelection.js';
+import { DEFAULT_GRAPH_AI_MODEL_PROFILE_CONFIG, mergeGraphAiModelConfig } from '../runtime/graphAiModelConfig.js';
 function asArrayNodes(graph) {
     return Array.isArray(graph.nodes) ? graph.nodes : Object.values(graph.nodes ?? {});
 }
-/** Returns the no-`when` default case profiles from a selection, if present and valid. */
+/** Returns the no-`when` default case partial profiles from a selection, if present. */
 function defaultCaseProfiles(selection) {
     if (!isModelConfigSelection(selection))
         return undefined;
     const sel = selection;
     for (const c of sel.cases ?? []) {
-        if (isEmptyConditionWhen(c.when))
+        if (isEmptyConditionWhen(c.when) && isPartialGraphAiModelConfig(c.modelConfig)) {
             return c.modelConfig;
+        }
     }
     return undefined;
 }
@@ -36,7 +37,10 @@ function finalizerUsesModel(node) {
  * provider id resolution happens inside `@exellix/ai-tasks`.
  */
 export function inspectGraphModelSelection(graph) {
-    const graphDefaultProfiles = defaultCaseProfiles(graph.modelConfig);
+    const graphDefaultPartial = defaultCaseProfiles(graph.modelConfig);
+    const graphDefaultProfiles = graphDefaultPartial
+        ? mergeGraphAiModelConfig(DEFAULT_GRAPH_AI_MODEL_PROFILE_CONFIG, graphDefaultPartial)
+        : undefined;
     const nodes = [];
     const aliases = new Set();
     const addAliases = (cfg) => {
@@ -76,15 +80,12 @@ export function inspectGraphModelSelection(graph) {
         const taskNode = raw;
         const nodeSelection = taskNode.taskConfiguration?.modelConfig;
         const nodeDefault = defaultCaseProfiles(nodeSelection);
+        const graphPartial = graphDefaultPartial;
         let profiles;
         let source;
-        if (nodeDefault) {
-            profiles = nodeDefault;
-            source = 'node';
-        }
-        else if (graphDefaultProfiles) {
-            profiles = graphDefaultProfiles;
-            source = 'graph';
+        if (nodeDefault != null || graphPartial != null) {
+            profiles = mergeGraphAiModelConfig(DEFAULT_GRAPH_AI_MODEL_PROFILE_CONFIG, graphPartial, nodeDefault);
+            source = nodeDefault != null ? 'node' : 'graph';
         }
         else {
             profiles = DEFAULT_GRAPH_AI_MODEL_PROFILE_CONFIG;

package/dist/src/runtime/ExellixGraphRuntime.js

@@ -1175,7 +1175,7 @@ export function createExellixGraphRuntime(opts) {
         return runWithAiTasksStackLogging(merged.logging, () => runGraphWithLogContext({ jobId, taskId: graphTaskId, graphId: resolvedGraphId, runId: graphTaskId }, async () => {
             bindGraphEngineRunLogxer(runLogxer);
             try {
-                assertCanonicalGraphDocument(graph, { jobId, graphId: resolvedGraphId });
+                assertCanonicalGraphDocument(graph, { jobId, graphId: resolvedGraphId }, { mode: 'execute' });
                 assertCanonicalGraphRuntimeObject(runtime, { jobId, graphId: resolvedGraphId });
                 let runxClient = opts.runx;
                 if (graphNeedsRunxClient(graph)) {

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

@@ -1,4 +1,4 @@
-import type { GraphAiModelConfig } from '../types/refs.js';
+import type { GraphAiModelConfig, PartialGraphAiModelConfig } from '../types/refs.js';
 /** Wire shape for `@exellix/ai-tasks` `RunTaskRequest.modelConfig` (8.4+). */
 export type RunTaskModelConfigWire = {
     preActionModel: string;
@@ -38,3 +38,8 @@ export type EngineModelPhase = 'pre' | 'main' | 'post';
  * Values are profile alias names from the graph document; ai-tasks resolves and routes slots per phase.
  */
 export declare function toRunTaskModelConfig(config: GraphAiModelConfig): RunTaskModelConfigWire;
+/**
+ * Merges layered partial configs left-to-right; later layers override earlier slots.
+ * Missing slots after all layers fall back to {@link DEFAULT_GRAPH_AI_MODEL_PROFILE_CONFIG}.
+ */
+export declare function mergeGraphAiModelConfig(...layers: Array<PartialGraphAiModelConfig | undefined>): GraphAiModelConfig;

package/dist/src/runtime/graphAiModelConfig.js

@@ -37,8 +37,6 @@ export function looksLikeConcreteModelId(value) {
     const trimmed = value.trim();
     if (trimmed === '')
         return false;
-    if (trimmed.includes('/'))
-        return true;
     const lower = trimmed.toLowerCase();
     return CONCRETE_MODEL_PREFIXES.some((p) => lower.startsWith(p));
 }
@@ -55,7 +53,7 @@ export function isGraphAiProfileName(value) {
 }
 export function assertGraphAiProfileNameString(value, path, context) {
     if (!isGraphAiProfileName(value)) {
-        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_MODEL_CONFIG, `${path} must be an AI profile alias (non-empty string without "/" or provider prefixes); got ${JSON.stringify(value)}`, context);
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_MODEL_CONFIG, `${path} must be an AI profile alias, profile/choice key, or shortcut (not a concrete provider model id); got ${JSON.stringify(value)}`, context);
     }
 }
 function normalizeModelSlot(slot, context) {
@@ -89,3 +87,26 @@ export function toRunTaskModelConfig(config) {
         postActionModel: config.postActionModel,
     };
 }
+/**
+ * Merges layered partial configs left-to-right; later layers override earlier slots.
+ * Missing slots after all layers fall back to {@link DEFAULT_GRAPH_AI_MODEL_PROFILE_CONFIG}.
+ */
+export function mergeGraphAiModelConfig(...layers) {
+    const merged = {};
+    for (const layer of layers) {
+        if (layer == null)
+            continue;
+        if (layer.preActionModel != null)
+            merged.preActionModel = layer.preActionModel.trim();
+        if (layer.skillModel != null)
+            merged.skillModel = layer.skillModel.trim();
+        if (layer.postActionModel != null)
+            merged.postActionModel = layer.postActionModel.trim();
+    }
+    const base = DEFAULT_GRAPH_AI_MODEL_PROFILE_CONFIG;
+    return {
+        preActionModel: merged.preActionModel ?? base.preActionModel,
+        skillModel: merged.skillModel ?? base.skillModel,
+        postActionModel: merged.postActionModel ?? base.postActionModel,
+    };
+}

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

@@ -1,4 +1,6 @@
-import type { GraphAiModelConfig, ModelConfigCase, ModelConfigSelection, TaskNodeConditionWhen } from '../types/refs.js';
+import type { GraphAiModelConfig, ModelConfigCase, ModelConfigSelection, PartialGraphAiModelConfig, TaskNodeConditionWhen } from '../types/refs.js';
+/** True when `value` is a non-empty subset of the three-phase model slots (partial or complete). */
+export declare function isPartialGraphAiModelConfig(value: unknown): value is PartialGraphAiModelConfig;
 export declare function isGraphAiModelConfig(value: unknown): value is GraphAiModelConfig;
 export declare function isEmptyConditionWhen(when: TaskNodeConditionWhen | undefined): boolean;
 export declare function isModelConfigSelection(value: unknown): value is ModelConfigSelection;

package/dist/src/runtime/modelConfigSelection.js

@@ -1,18 +1,23 @@
-export function isGraphAiModelConfig(value) {
+const MODEL_CONFIG_SLOT_KEYS = ['preActionModel', 'skillModel', 'postActionModel'];
+/** True when `value` is a non-empty subset of the three-phase model slots (partial or complete). */
+export function isPartialGraphAiModelConfig(value) {
     if (value == null || typeof value !== 'object' || Array.isArray(value))
         return false;
     const o = value;
     const keys = Object.keys(o);
-    return (keys.length === 3 &&
-        keys.includes('preActionModel') &&
-        keys.includes('skillModel') &&
-        keys.includes('postActionModel') &&
-        typeof o.preActionModel === 'string' &&
-        o.preActionModel.trim() !== '' &&
-        typeof o.skillModel === 'string' &&
-        o.skillModel.trim() !== '' &&
-        typeof o.postActionModel === 'string' &&
-        o.postActionModel.trim() !== '');
+    if (keys.length === 0 || keys.length > MODEL_CONFIG_SLOT_KEYS.length)
+        return false;
+    if (!keys.every((k) => MODEL_CONFIG_SLOT_KEYS.includes(k)))
+        return false;
+    return keys.every((k) => typeof o[k] === 'string' && o[k].trim() !== '');
+}
+export function isGraphAiModelConfig(value) {
+    if (!isPartialGraphAiModelConfig(value))
+        return false;
+    const o = value;
+    return (o.preActionModel != null &&
+        o.skillModel != null &&
+        o.postActionModel != null);
 }
 export function isEmptyConditionWhen(when) {
     if (when == null)

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

@@ -14,8 +14,9 @@ export type ResolveModelConfigForNodeArgs = {
 };
 /**
  * Resolves effective model config for a task node from the graph document only.
- * Precedence: `node.taskConfiguration.modelConfig` → `graph.modelConfig` → engine default profiles.
+ * Merges `node.taskConfiguration.modelConfig` (partial override) over `graph.modelConfig` (job default),
+ * then engine defaults for any remaining slots.
  */
 export declare function resolveModelConfigForNode(args: ResolveModelConfigForNodeArgs): Promise<GraphAiModelConfig>;
 export { conditionWhenSignature, isEmptyConditionWhen };
-export { resolveGraphAiModelConfig, toRunTaskModelConfig, DEFAULT_GRAPH_AI_MODEL_IDS, DEFAULT_GRAPH_AI_MODEL_PROFILE_CONFIG, } from './graphAiModelConfig.js';
+export { resolveGraphAiModelConfig, toRunTaskModelConfig, mergeGraphAiModelConfig, DEFAULT_GRAPH_AI_MODEL_IDS, DEFAULT_GRAPH_AI_MODEL_PROFILE_CONFIG, } from './graphAiModelConfig.js';

package/dist/src/runtime/resolveModelConfigForNode.js

@@ -1,6 +1,6 @@
-import { conditionWhenSignature, isEmptyConditionWhen, isGraphAiModelConfig, isModelConfigSelection, } from './modelConfigSelection.js';
+import { conditionWhenSignature, isEmptyConditionWhen, isModelConfigSelection, isPartialGraphAiModelConfig, } from './modelConfigSelection.js';
 import { evaluateConditionWhen } from './taskNodeConditionsEvaluation.js';
-import { DEFAULT_GRAPH_AI_MODEL_PROFILE_CONFIG, } from './graphAiModelConfig.js';
+import { DEFAULT_GRAPH_AI_MODEL_PROFILE_CONFIG, mergeGraphAiModelConfig, resolveGraphAiModelConfig, } from './graphAiModelConfig.js';
 async function selectFromCases(selection, ctx, executionInput, runx) {
     const cases = selection.cases;
     if (!Array.isArray(cases) || cases.length === 0)
@@ -16,17 +16,17 @@ async function selectFromCases(selection, ctx, executionInput, runx) {
         const ev = await evaluateConditionWhen(c.when, ctx, executionInput, { runx });
         if (ev.error)
             continue;
-        if (ev.ok && isGraphAiModelConfig(c.modelConfig)) {
+        if (ev.ok && isPartialGraphAiModelConfig(c.modelConfig)) {
             return c.modelConfig;
         }
     }
-    if (defaultCase != null && isGraphAiModelConfig(defaultCase.modelConfig)) {
+    if (defaultCase != null && isPartialGraphAiModelConfig(defaultCase.modelConfig)) {
         return defaultCase.modelConfig;
     }
     return undefined;
 }
 async function resolveTier(value, ctx, executionInput, runx) {
-    if (isGraphAiModelConfig(value))
+    if (isPartialGraphAiModelConfig(value))
         return value;
     if (isModelConfigSelection(value)) {
         return selectFromCases(value, ctx, executionInput, runx);
@@ -35,17 +35,18 @@ async function resolveTier(value, ctx, executionInput, runx) {
 }
 /**
  * Resolves effective model config for a task node from the graph document only.
- * Precedence: `node.taskConfiguration.modelConfig` → `graph.modelConfig` → engine default profiles.
+ * Merges `node.taskConfiguration.modelConfig` (partial override) over `graph.modelConfig` (job default),
+ * then engine defaults for any remaining slots.
  */
 export async function resolveModelConfigForNode(args) {
-    const tiers = [args.nodeModelConfig, args.graphModelConfig];
-    for (const tier of tiers) {
-        const selected = await resolveTier(tier, args.conditionCtx, args.executionInput, args.runx);
-        if (selected != null) {
-            return selected;
-        }
-    }
-    return DEFAULT_GRAPH_AI_MODEL_PROFILE_CONFIG;
+    const graphPartial = await resolveTier(args.graphModelConfig, args.conditionCtx, args.executionInput, args.runx);
+    const nodePartial = await resolveTier(args.nodeModelConfig, args.conditionCtx, args.executionInput, args.runx);
+    const merged = mergeGraphAiModelConfig(DEFAULT_GRAPH_AI_MODEL_PROFILE_CONFIG, graphPartial, nodePartial);
+    return resolveGraphAiModelConfig(merged, {
+        graphId: args.graphId,
+        nodeId: args.nodeId,
+        jobId: args.jobId,
+    });
 }
 export { conditionWhenSignature, isEmptyConditionWhen };
-export { resolveGraphAiModelConfig, toRunTaskModelConfig, DEFAULT_GRAPH_AI_MODEL_IDS, DEFAULT_GRAPH_AI_MODEL_PROFILE_CONFIG, } from './graphAiModelConfig.js';
+export { resolveGraphAiModelConfig, toRunTaskModelConfig, mergeGraphAiModelConfig, DEFAULT_GRAPH_AI_MODEL_IDS, DEFAULT_GRAPH_AI_MODEL_PROFILE_CONFIG, } from './graphAiModelConfig.js';

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

@@ -5,12 +5,17 @@ export declare const CANONICAL_GRAPH_TOP_LEVEL_KEYS: readonly ["id", "version",
  * Returns top-level keys on `graph` that are not part of the canonical executable document contract.
  */
 export declare function getCanonicalGraphDocumentViolations(graph: unknown): string[];
+export type CanonicalGraphDocumentValidationMode = 'persist' | 'execute';
+export type AssertCanonicalGraphDocumentOptions = {
+    /** `execute` accepts partial task overrides and profile/choice slot encoding; `persist` stays strict. */
+    mode?: CanonicalGraphDocumentValidationMode;
+};
 /** Single-node validation. Throws `NON_CANONICAL_TASK_NODE` on the first canonical violation. */
 export declare function assertCanonicalTaskNode(node: unknown, context?: {
     jobId?: string;
     graphId?: string;
     nodeIndex?: number;
-}): void;
+}, options?: AssertCanonicalGraphDocumentOptions): void;
 /**
  * Throws {@link ExellixGraphError} when the value is not a canonical graph document
  * (forbidden top-level keys, record-keyed `nodes`, root `outputConstraints`, or any
@@ -22,4 +27,4 @@ export declare function assertCanonicalTaskNode(node: unknown, context?: {
 export declare function assertCanonicalGraphDocument(graph: Graph, context?: {
     jobId?: string;
     graphId?: string;
-}): void;
+}, options?: AssertCanonicalGraphDocumentOptions): void;

package/dist/src/runtime/validateCanonicalGraphDocument.js

@@ -3,7 +3,7 @@ import { ExellixGraphError } from '../errors/ExellixGraphError.js';
 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 { conditionWhenSignature, countDefaultModelConfigCases, isEmptyConditionWhen, isGraphAiModelConfig, isModelConfigSelection, isPartialGraphAiModelConfig, } from './modelConfigSelection.js';
 import { assertGraphAiProfileNameString } from './graphAiModelConfig.js';
 import { assertCanonicalGraphDocumentMetadata } from './graphModelStudioSeparation.js';
 /** Top-level keys permitted on a canonical exellix-graph executable graph JSON document. */
@@ -273,13 +273,20 @@ function assertOptionalTaskNodeConditions(value, nodeId, context) {
     assertTaskNodeJsCondition(value.jsConditionFunction, `Task node "${nodeId}": conditions.jsConditionFunction`, ctx);
     assertTaskNodeAiCondition(value.aiCondition, `Task node "${nodeId}": conditions.aiCondition`, ctx);
 }
-function assertModelConfigSelection(value, path, context) {
+function assertModelConfigSlotIfPresent(slot, slotPath, context) {
+    if (slot === undefined)
+        return;
+    assertGraphAiProfileNameString(slot, slotPath, context);
+}
+function assertModelConfigSelection(value, path, context, options) {
     if (value === undefined)
         return;
+    const mode = options?.mode ?? 'persist';
+    const allowPartial = mode === 'execute';
     const code = context?.nodeId
         ? ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE
         : ExellixGraphErrorCode.NON_CANONICAL_GRAPH_DOCUMENT;
-    if (isGraphAiModelConfig(value)) {
+    if (isGraphAiModelConfig(value) || (allowPartial && isPartialGraphAiModelConfig(value))) {
         throw new ExellixGraphError(code, `${path}: flat modelConfig was removed. Use { cases: [{ modelConfig: { preActionModel, skillModel, postActionModel } }] } (one case with no \`when\` for a single default).`, context);
     }
     if (!isModelConfigSelection(value)) {
@@ -297,12 +304,24 @@ function assertModelConfigSelection(value, path, context) {
         if (!isPlainObject(c)) {
             throw new ExellixGraphError(code, `${casePath} must be a plain object.`, context);
         }
-        if (!isGraphAiModelConfig(c.modelConfig)) {
-            throw new ExellixGraphError(code, `${casePath}.modelConfig must be { preActionModel: string, skillModel: string, postActionModel: string } with non-empty AI profile names.`, context);
+        const mc = c.modelConfig;
+        const mcValid = allowPartial ? isPartialGraphAiModelConfig(mc) : isGraphAiModelConfig(mc);
+        if (!mcValid) {
+            throw new ExellixGraphError(code, allowPartial
+                ? `${casePath}.modelConfig must include at least one of { preActionModel, skillModel, postActionModel } with non-empty alias or profile/choice values.`
+                : `${casePath}.modelConfig must be { preActionModel: string, skillModel: string, postActionModel: string } with non-empty AI profile names.`, context);
+        }
+        const partial = mc;
+        if (!allowPartial) {
+            assertGraphAiProfileNameString(partial.preActionModel, `${casePath}.modelConfig.preActionModel`, context);
+            assertGraphAiProfileNameString(partial.skillModel, `${casePath}.modelConfig.skillModel`, context);
+            assertGraphAiProfileNameString(partial.postActionModel, `${casePath}.modelConfig.postActionModel`, context);
+        }
+        else {
+            assertModelConfigSlotIfPresent(partial.preActionModel, `${casePath}.modelConfig.preActionModel`, context);
+            assertModelConfigSlotIfPresent(partial.skillModel, `${casePath}.modelConfig.skillModel`, context);
+            assertModelConfigSlotIfPresent(partial.postActionModel, `${casePath}.modelConfig.postActionModel`, context);
         }
-        assertGraphAiProfileNameString(c.modelConfig.preActionModel, `${casePath}.modelConfig.preActionModel`, context);
-        assertGraphAiProfileNameString(c.modelConfig.skillModel, `${casePath}.modelConfig.skillModel`, context);
-        assertGraphAiProfileNameString(c.modelConfig.postActionModel, `${casePath}.modelConfig.postActionModel`, context);
         if (isEmptyConditionWhen(c.when)) {
             continue;
         }
@@ -424,7 +443,7 @@ function isTaskShape(node) {
     return true;
 }
 /** Single-node validation. Throws `NON_CANONICAL_TASK_NODE` on the first canonical violation. */
-export function assertCanonicalTaskNode(node, context) {
+export function assertCanonicalTaskNode(node, context, options) {
     if (!isPlainObject(node)) {
         throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE, `Graph node at index ${context?.nodeIndex ?? '?'} is not a plain object.`, { jobId: context?.jobId, graphId: context?.graphId });
     }
@@ -479,7 +498,7 @@ export function assertCanonicalTaskNode(node, context) {
         jobId: context?.jobId,
         graphId: context?.graphId,
         nodeId: String(node.id),
-    });
+    }, options);
     assertContextualKnowledgeScope(taskNode.scope, String(node.id), {
         jobId: context?.jobId,
         graphId: context?.graphId,
@@ -548,7 +567,7 @@ export function assertCanonicalTaskNode(node, context) {
  * `variables`, required `response`, and `metadata`); runtime fields belong under the execution
  * request `runtime` object.
  */
-export function assertCanonicalGraphDocument(graph, context) {
+export function assertCanonicalGraphDocument(graph, context, options) {
     const violations = getCanonicalGraphDocumentViolations(graph);
     if (violations.length > 0) {
         const graphId = context?.graphId ??
@@ -583,7 +602,7 @@ export function assertCanonicalGraphDocument(graph, context) {
     assertModelConfigSelection(graph.modelConfig, 'graph.modelConfig', {
         jobId: context?.jobId,
         graphId: resolvedGraphId,
-    });
+    }, options);
     const metadata = isPlainObject(graph.metadata)
         ? graph.metadata
         : undefined;
@@ -613,7 +632,7 @@ export function assertCanonicalGraphDocument(graph, context) {
     // Per-node canonical checks.
     const nodes = graph.nodes;
     for (let i = 0; i < nodes.length; i++) {
-        assertCanonicalTaskNode(nodes[i], { jobId: context?.jobId, graphId: resolvedGraphId, nodeIndex: i });
+        assertCanonicalTaskNode(nodes[i], { jobId: context?.jobId, graphId: resolvedGraphId, nodeIndex: i }, options);
     }
     if (!Object.prototype.hasOwnProperty.call(graph, 'response')) {
         throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_GRAPH_DOCUMENT, `Graph "${String(resolvedGraphId ?? '?')}" must declare root graph.response. Final response shaping must not live under metadata.graphResponse.responseMapping or finalizer output selection.`, { jobId: context?.jobId, graphId: resolvedGraphId });

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

@@ -21,6 +21,12 @@ export type GraphAiModelConfig = {
     skillModel: string;
     postActionModel: string;
 };
+/** Authoring / execute ingress: one or more phase slots; omitted slots inherit at runtime. */
+export type PartialGraphAiModelConfig = {
+    preActionModel?: string;
+    skillModel?: string;
+    postActionModel?: string;
+};
 /**
  * @deprecated Legacy alias map — no longer required for execute. Hosts may omit `runtime.aliasConfig`.
  */
@@ -347,7 +353,7 @@ export type TaskNodeConditions = {
 };
 export type ModelConfigCase = {
     when?: TaskNodeConditionWhen;
-    modelConfig: GraphAiModelConfig;
+    modelConfig: PartialGraphAiModelConfig;
 };
 /** Canonical authoring shape for graph and taskConfiguration model selection. */
 export type ModelConfigSelection = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exellix/graph-engine",
-  "version": "7.7.5",
+  "version": "7.7.8",
   "type": "module",
   "description": "Graph executor SDK",
   "main": "dist/src/index.js",
@@ -64,7 +64,7 @@
     "@x12i/memorix-retrieval": "1.11.2",
     "@x12i/memorix-writer": "1.0.0",
     "@x12i/rendrix": "4.3.0",
-    "@x12i/runx": "1.3.0"
+    "@x12i/runx": "1.3.2"
   },
   "devDependencies": {
     "@types/node": "25.9.1",