@exellix/graph-engine 7.7.8 → 7.8.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 7.7.9
+
+### Changed
+
+- **Documentation:** Align README, [`.docs/exellix-graph-engine-format.md`](.docs/exellix-graph-engine-format.md), format docs, and [`.docs/ai-tasks-model-profile-aliases-7x.md`](.docs/ai-tasks-model-profile-aliases-7x.md) with ai-tasks **8.6.8** / funcx **4.4.4**: three-slot `modelConfig`, graph-only selection (7.7+), partial task overrides (7.7.8+), studio preflight via `@exellix/graph-composer`, funcx-for-runx vs xynthesis-for-execution-strategies.
+
+### Dependencies
+
+- **`@exellix/ai-tasks`:** ^8.6.8
+- **`@x12i/funcx`:** 4.4.4
+
 ## 7.7.8
 
 ### Added (CR-11 execute-time model routing)
@@ -212,7 +223,7 @@
 ### Changed
 
 - **Dual memory roots `input` and `inputs`:** Both are allowlisted for `smartInput.paths` and `inputSynthesis.sources`; paths are no longer rewritten to `input.*` at validation or runtime. Optional migration via `mapInputsMemoryPathToInputRoot` / `mapSmartInputPathsInputsToInput`.
-- **`runTask` wire:** Forwards `inputs` (caller bag) alongside coalesced `input` when present. See [CR-input-and-inputs-dual-root.md](.docs/CR-input-and-inputs-dual-root.md) for downstream `@exellix/ai-tasks` and graphs-studio work.
+- **`runTask` wire:** Forwards `inputs` (caller bag) alongside coalesced `input` when present.
 
 ## 5.4.0
 

package/README.md

@@ -27,22 +27,21 @@ A minimal, focused SDK for executing graphs in the exellix ecosystem.
 | Topic | Document |
 |--------|----------|
 | **Object contracts** (model × runtime + per-call resolution view) | Index: [`formats-documentations/README.md`](formats-documentations/README.md) — [`graph-model`](formats-documentations/graph-model-object-format.md), [`graph-runtime`](formats-documentations/graph-runtime-object-format.md), [`task-node-model`](formats-documentations/task-node-model-object-format.md), [`task-node-runtime`](formats-documentations/task-node-runtime-object-format.md), [`ExellixRuntimeObject`](formats-documentations/exellix-runtime-object-format.md) |
-| **Ecosystem acceptance** (ai-tasks, studio, matrix parity) | [`.docs/ecosystem-acceptance-criteria.md`](.docs/ecosystem-acceptance-criteria.md) |
 | **Executable graph JSON** (top-level shape, task/finalizer nodes, edges, variables, `metadata.graphExecution`, canonical root enforcement, execution memory, local skills, Narrix / web scope (**forwarded `narrix` → `runTask`**), **graph JSON vs outbound `runTask`**) | **[`.docs/exellix-graph-engine-format.md`](.docs/exellix-graph-engine-format.md)** — start here for authors and schema tooling |
 | Task node bridge (shell, `metadata`, `executionPipeline`, `aiTaskProfile` → Narrix web merge, composer alignment) | [`.docs/task-node-exellix-graph-engine-and-graph-composer.md`](.docs/task-node-exellix-graph-engine-and-graph-composer.md) |
 | 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) |
+| **Model profile aliases** (7.x+: graph = aliases / `profile/choice`; ai-tasks resolves per phase) | [`BREAKING-CHANGES.md`](BREAKING-CHANGES.md) §7.6 / §7.7, [`.docs/ai-tasks-model-profile-aliases-7x.md`](.docs/ai-tasks-model-profile-aliases-7x.md) |
 | Platform vs implementation (no domain operators in schema) | [`.docs/platform-generic-vs-implementation.md`](.docs/platform-generic-vs-implementation.md) |
 | Activix records, `runContext`, collection tracking (`@x12i/activix` 8.4+) | [`.docs/activix-records.md`](.docs/activix-records.md) |
 | Bundled graph examples & bundle README | [`graphs/README.md`](graphs/README.md) |
 
-The **`runTask`** wire contract (identity, canonical **`input`**, optional extra ai-tasks PRE/POST utility calls vs `executionPipeline`) is summarized later under **Run identity** and **`runTask` request contract**, and expanded in the graph format doc’s [**Graph JSON vs outbound `runTask`**](.docs/exellix-graph-engine-format.md#graph-json-vs-outbound-runtask) section. Graph-engine integrates with **`@exellix/ai-tasks`** at the semver range declared in **`package.json`** (currently **`^7.6.4`**); use your **lockfile** as the tested line. Variable buckets align with ai-tasks **≥ 7.6.2** (two-scope passthrough). There is **no** minimum graph-engine ↔ ai-tasks matrix published inside ai-tasks — follow dependency semver and upstream **`CHANGELOG.md`**. Graph-engine does **not** import or invoke the Xynthesis SDK directly.
+The **`runTask`** wire contract (identity, canonical **`input`**, optional extra ai-tasks PRE/POST utility calls vs `executionPipeline`) is summarized later under **Run identity** and **`runTask` request contract**, and expanded in the graph format doc’s [**Graph JSON vs outbound `runTask`**](.docs/exellix-graph-engine-format.md#graph-json-vs-outbound-runtask) section. Graph-engine integrates with **`@exellix/ai-tasks`** at the semver range declared in **`package.json`** (currently **`^8.6.8`**); use your **lockfile** as the tested line. Variable buckets align with ai-tasks **≥ 7.6.2** (two-scope passthrough). There is **no** minimum graph-engine ↔ ai-tasks matrix published inside ai-tasks — follow dependency semver and upstream **`CHANGELOG.md`**. Graph-engine does **not** import **`@exellix/xynthesis`** directly; **`@x12i/funcx`** is used only for optional **runx** (conditional edges / `modelConfig.cases`), not for ai-tasks execution strategies (those run via xynthesis inside ai-tasks **8.5+**).
 
 ### Canonical executable graph document (strict boundary)
 
-An executable graph model object may have **only** these **top-level** keys: `id`, `version`, `modelConfig`, `jobKnowledge`, `nodes`, `edges`, `variables`, `response`, `metadata`. The required root **`response`** is the single executable final response contract used to build `ExecuteGraphResult.finalOutput`. Document-model and authoring fields (`name`, `description`, `exellixContractTarget`, `graphExecution`, `graphEntry`, `catalogRequests`, and similar) belong **under `metadata`** only. Node-scoped `taskKnowledge` belongs under each task node, not at the model root. Runtime state (`input`, `jobMemory`, `taskMemory`, `executionMemory`, `outputsMemory`, `aliasConfig`, runtime node overrides) belongs under the execution request’s **`runtime`** object and is rejected on the model.
+An executable graph model object may have **only** these **top-level** keys: `id`, `version`, `modelConfig`, `jobKnowledge`, `nodes`, `edges`, `variables`, `response`, `metadata`. The required root **`response`** is the single executable final response contract used to build `ExecuteGraphResult.finalOutput`. Document-model and authoring fields (`name`, `description`, `exellixContractTarget`, `graphExecution`, `graphEntry`, `catalogRequests`, and similar) belong **under `metadata`** only. Node-scoped `taskKnowledge` belongs under each task node, not at the model root. Runtime state (`input`, `jobMemory`, `taskMemory`, `executionMemory`, `outputsMemory`, per-run options) belongs under the execution request’s **`runtime`** object and is rejected on the model. **`runtime.modelConfig`**, **`runtime.aliasConfig`**, and **`runtime.nodes[id].modelConfig`** were removed in **7.7** — model profiles belong on the graph document only.
 
 `metadata.graphExecution` can document graph execution defaults and labels, including `mode: 'forward' | 'backward' | 'hybrid'`, optional `goalNodeId`, optional `dimension`, `outputMode: 'mappedAggregation' | 'lastExitNode'`, `coreObjective`, optional `nodesResponses`, and metadata-only `flowOutline: 'linearSequence' | 'convergingParallelFlow'`. Planner mode still comes from `executeGraph({ model, runtime }).runtime.mode`; `outputMode` does not decide the returned `finalOutput`.
 
@@ -54,7 +53,7 @@ Enforcement: `executeGraph`, `createExellixGraphRuntime().executeGraph`, `execut
 npm install @exellix/graph-engine
 ```
 
-**Upstream tasks SDK:** This package depends on **`@exellix/ai-tasks` ^7.4.0** (see **`package.json`**). Graph-engine emits **`RunTaskRequest`** shapes that match the v7 closed schema (mandatory **`executionStrategies`**, **`xynthesized`**, optional **`smartInput`**, no legacy root mirrors). Pin compatible versions in your app lockfile. Optional CI improvement: fail or warn when the resolved ai-tasks major/minor drifts outside an allowlist (not enforced in-repo today).
+**Upstream tasks SDK:** This package depends on **`@exellix/ai-tasks` ^8.6.8** and **`@x12i/funcx` 4.4.4** (see **`package.json`**). Graph-engine emits **`RunTaskRequest`** shapes that match the ai-tasks **8.x** closed schema (mandatory **`executionStrategies`**, three-slot **`modelConfig`**, **`xynthesized`**, optional **`smartInput`**, no legacy root mirrors). Pin compatible versions in your app lockfile. Optional CI improvement: fail or warn when the resolved ai-tasks major/minor drifts outside an allowlist (not enforced in-repo today).
 
 ### Execution matrix hosts (`@exellix/exellix-runtime`) — documentation only for the engine
 
@@ -83,7 +82,7 @@ For Firebase Admin, `createCataloxFromEnv`, `listAiSkillsCatalogItems`, and rela
 
 ### Task-node preflight (validation & analysis, no `runTask`)
 
-Graph-engine exposes the **`@exellix/ai-tasks` ≥ 7.6** preflight surface so studios and matrix hosts can validate a node **before** execution without a second dependency:
+Graph-engine exposes the **`@exellix/ai-tasks`** preflight surface so studios and matrix hosts can validate a node **before** execution without a second dependency on ai-tasks:
 
 | Export | Purpose |
 |--------|---------|
@@ -91,7 +90,7 @@ Graph-engine exposes the **`@exellix/ai-tasks` ≥ 7.6** preflight surface so st
 | **`validateTaskNodeRunTaskConfig`** | Static config checks (`agentId`, pipeline, `smartInput`, `llmCall`, …). |
 | **`validateTaskNodeRunTaskInvoke`** | Config + payload path resolution + optional template/smart-input render checks. |
 
-Lower-level helpers (`validateRunTaskConfig`, `validateRunTaskInvoke`, `analyzeExpectedRunTaskInput`, Rendrix `listTokens` / `analyzeTemplateResolution`, …) are **re-exported** from the package root when you already have a `RunTaskRequest`. Catalox-backed skill invoke packet analysis was removed from `@exellix/ai-tasks` — use studio / skills-manager preflight (`@x12i/funcx` analyze-gateway-invoke-request) instead.
+Lower-level helpers (`validateRunTaskConfig`, `validateRunTaskInvoke`, `analyzeExpectedRunTaskInput`, Rendrix `listTokens` / `analyzeTemplateResolution`, …) are **re-exported** from the package root when you already have a `RunTaskRequest`. Catalox-backed skill invoke packet analysis was removed from `@exellix/ai-tasks` **8.6** — use **`@exellix/graph-composer`** for studio / skills-manager invoke preflight (see `@exellix/ai-tasks` `documenations/studio-skill-invoke-preflight.md`).
 
 **Testing safety:** Default `npm test` uses **mocked** Catalox in catalog validation tests and does not open Firestore. Do **not** point `FIRESTORE_LIVE_TESTS` / integration flags at a **production** Firebase project; Catalox’s own docs recommend a dedicated test project for live integration runs.
 
@@ -106,6 +105,22 @@ const runtime = createExellixGraphRuntime({
   tasksClient: myTasksClient,     // TasksClientLike — responses may use `ok` or `success` (both accepted)
 });
 
+// graphModel carries static modelConfig (profile aliases on the graph document — not on runtime).
+const graphModel = {
+  id: 'my-graph',
+  modelConfig: {
+    cases: [{
+      modelConfig: {
+        preActionModel: 'cheap',
+        skillModel: 'balanced',
+        postActionModel: 'cheap',
+      },
+    }],
+  },
+  nodes: [/* … */],
+  // …
+};
+
 // Host correlation id (required). Engine sets `job.id` / `job.jobId` from it and generates `result.taskId`.
 const result = await runtime.executeGraph({
   model: graphModel,
@@ -113,15 +128,7 @@ const result = await runtime.executeGraph({
     jobId: 'job-123',
     job: { agentId: 'agent-1', input: {} },
     input: { question: 'Analyze this record' },
-    // 7.x: graph modelConfig values are profile aliases; concrete models bind here (required).
-    modelConfig: {
-      cases: [{ modelConfig: { xynthesisModel: 'weak', skillModel: 'strong' } }],
-    },
-    aliasConfig: {
-      strong: 'anthropic/claude-sonnet-4',
-      weak: 'google/gemini-2.5-flash',
-      default: 'google/gemini-2.5-flash',
-    },
+    // no modelConfig or aliasConfig on runtime (removed in 7.7)
   },
 });
 
@@ -144,9 +151,9 @@ const runtime = createExellixGraphRuntime({
   graphLoader,
   engineFactory,
   tasksClient,
-  modelConfig,            // optional explicit fallback: { xynthesisModel, skillModel }
   eventEmitter,           // optional graph/node lifecycle events
   playgroundReporter,     // optional
+  runxCreateOptions,      // optional — lazy runx + funcx when graph needs conditional modelConfig / conditions
   // …stepRetryPolicy, runLogMode, concurrency, runTaskDiagnostics, etc.
 });
 
@@ -161,6 +168,9 @@ interface GraphExecutionRequest {
 // Task-node model:   TaskNode
 // Task-node runtime: TaskNodeRuntimeObject at runtime.nodes[nodeId]
 
+// Task-node runtime: TaskNodeRuntimeObject at runtime.nodes[nodeId] — extensible bag;
+// modelConfig / aliasConfig on runtime.nodes were removed in 7.7.
+
 interface GraphRuntimeObject {
   jobId: string;                 // required: host correlation id
   job: any;                      // host envelope: agentId, input, jobType, …
@@ -169,21 +179,13 @@ interface GraphRuntimeObject {
   taskMemory?: any;
   executionMemory?: any;
   variables?: Record<string, any>;
-  /** 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>;
-  }>;
+  /** Per-node runtime bag (must not carry modelConfig or aliasConfig since 7.7). */
+  nodes?: Record<string, Record<string, unknown>>;
   mode?: 'forward' | 'backward' | 'hybrid';
   goalNodeId?: string;           // required when mode === 'backward'
   debugMode?: boolean;           // include per-node trace on result.debug
   failFast?: boolean;            // default: false
-  // …llmCall, stepRetryPolicy, runLogMode, runtimeObjects, runTaskDiagnostics, etc.
+  // …stepRetryPolicy, runLogMode, runtimeObjects, runTaskDiagnostics, etc.
 }
 ```
 
@@ -265,7 +267,7 @@ const markdown = playgroundReporter.getMarkdown();
 
 **Standalone node debugging:** The runtime also exposes **`runtime.executeNode(...)`** for single-node test runs. Provide `node`, `job`, optional `graph` / `execution`, and (when continuing an existing run) `graphRunTaskId` from the parent `ExecuteGraphResult.taskId` so `runTask` and Activix stay aligned.
 
-### `runTask` request contract (`@exellix/ai-tasks` v7.x)
+### `runTask` request contract (`@exellix/ai-tasks` 8.x)
 
 Graph-engine builds a canonical `RunTaskRequest` for every outbound task call it owns: MAIN task-node invokes, engine PRE/POST utility invokes, and `synthesize` finalizer invokes. MAIN request assembly lives in [`src/runtime/buildAiTasksRunTaskRequest.ts`](src/runtime/buildAiTasksRunTaskRequest.ts); all paths follow **`RUNTASK_REQUEST.md`** in `@exellix/ai-tasks`. Types align with **`RunTaskRequest`** / **`ExellixGraphRunTaskRequest`** exported from this package.
 
@@ -277,7 +279,7 @@ Graph-engine builds a canonical `RunTaskRequest` for every outbound task call it
 
 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.
+**Model profiles (7.x+):** Graph and node `modelConfig` carry **profile alias names** only (`cheap`, `balanced`, `deep`, or `profile/choice` keys like `cheap/default`, `cyber/deep_forensics`) — never provider model ids in graph JSON. **Since 7.7**, model selection is **graph-document only**: merge `node.taskConfiguration.modelConfig` (partial override per slot) over `model.modelConfig`, then engine defaults (`cheap` / `balanced` / `cheap`). Graph-engine forwards the three-slot triplet `{ preActionModel, skillModel, postActionModel }` on every outbound `runTask`; **`@exellix/ai-tasks`** resolves aliases via `@x12i/ai-profiles`. **7.7.8+** execute-mode validation accepts partial per-task overrides and `profile/choice` encoding without host-side pre-merge. See [`BREAKING-CHANGES.md`](BREAKING-CHANGES.md) §7.6 / §7.7 / §7.7.8.
 
 Graph-engine still derives correlation fields such as `graphId`, `nodeId`, `coreSkillId`, `masterSkillId`, `taskId`, and `masterSkillActivityId` from those authored values.
 
@@ -286,7 +288,7 @@ Graph-engine still derives correlation fields such as `graphId`, `nodeId`, `core
 - Every MAIN (and engine PRE/POST utility) **`runTask`** includes **`executionStrategies`**: an array of **`ExecutionStrategyInvocation`** objects (semantics defined by **`@exellix/ai-tasks`** / `RUNTASK_REQUEST.md`).
 - **Plain MAIN** (no wrappers): graph-engine sends **`executionStrategies: []`**.
 - Optional task-node authoring: **`taskConfiguration.executionStrategies`** — when present and non-empty, it overrides the default **`[]`** for that node’s MAIN call.
-- Optional catalog metadata: **`taskConfiguration.executionStrategyCatalogItems`** is forwarded to `ai-tasks`; `ai-tasks` still validates the runtime invocation shape and consumes only safe catalog fields such as wrapper default function ids.
+- Optional catalog metadata: **`taskConfiguration.executionStrategyCatalogItems`** is forwarded to `ai-tasks`; planner/optimizer rows use **`runtimeKind: "xynthesis-action"`** in ai-tasks **8.5+** (not funcx). `ai-tasks` still validates the runtime invocation shape and consumes only safe catalog fields such as wrapper default sidekick actions.
 - **Removed in 5.0:** `metadata.executionStrategyKey` typing and code branches. Configure planners/optimizers through **`executionStrategies`** per ai-tasks (see upstream docs / Catalox task-strategy catalogs).
 
 #### `xynthesized` and internal `execution.xynthesized`
@@ -480,7 +482,6 @@ const result = await runtime.executeGraph({
     jobId: 'job-123',
     job: { agentId: 'agent-1', jobType: 'analysis' },
     input: entryInput,
-    aliasConfig: { /* … */ },
     runtimeObjects: buildExellixGraphRuntimeObjects({ graphActivixClient: activixClient }),
   },
 });
@@ -919,7 +920,7 @@ Bundled **graph definitions** (JSON DAGs) live in [`graphs/`](graphs/). **[graph
 
 To execute a graph, supply a `graphLoader` that resolves `graphId` to JSON, build a `job` with the input shape your graph expects (often `execution.input` with `raw` and optional `metadata`), and call `executeGraph`. Further integration notes may live under [.docs/](.docs/).
 
-**`taskConfiguration.aiTasksOutputValidation`** on task nodes is forwarded as **`outputValidation`** on the `runTask` request (**`@exellix/ai-tasks` v7+**). Root **`outputConstraints`** is not part of the closed schema.
+**`taskConfiguration.aiTasksOutputValidation`** on task nodes is forwarded as **`outputValidation`** on the `runTask` request (**`@exellix/ai-tasks` 8.x**). Root **`outputConstraints`** is not part of the closed schema.
 
 ## Runtime observability (`runtimeObjects`)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exellix/graph-engine",
-  "version": "7.7.8",
+  "version": "7.8.0",
   "type": "module",
   "description": "Graph executor SDK",
   "main": "dist/src/index.js",
@@ -52,11 +52,11 @@
     "access": "public"
   },
   "dependencies": {
-    "@exellix/ai-tasks": "^8.6.2",
+    "@exellix/ai-tasks": "^8.6.8",
     "@x12i/activix": "8.5.0",
     "@x12i/catalox": "5.1.3",
     "@x12i/env": "4.0.1",
-    "@x12i/funcx": "4.4.0",
+    "@x12i/funcx": "4.4.4",
     "@x12i/graphenix": "2.5.0",
     "@x12i/graphenix-format": "2.0.0",
     "@x12i/logxer": "^4.6.0",