@exellix/exellix-jobs 4.1.8 → 4.1.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +1 -1
  2. package/docs/specs.md +9 -7
  3. package/examples/host-bootstrap.mjs +3 -1
  4. package/package.json +4 -3
package/README.md CHANGED
@@ -15,7 +15,7 @@ This worker **does not** call `executeGraph` itself. It passes your host `execut
15
15
  | Materialize | `ExecutionMatrixRuntimeRecord.input` — flat field names (`subnetId`, `question`, …), not `input.raw` |
16
16
  | Execute | `runtime.input` on the graph-engine request (same blob as row `input`) |
17
17
 
18
- **Host responsibilities:** supply **`sourceResolver`** / **`inputRows`** so materialized row `input` uses **flat keys** matching `metadata.graphEntry.inputs` (requires **`@exellix/graph-engine` ≥ 5.16**). Wrap production executors with **`createMatrixExecuteGraphAdapter`** from runtime when adding `modelConfig` defaults (see [`examples/host-bootstrap.mjs`](./examples/host-bootstrap.mjs)).
18
+ **Host responsibilities:** supply **`sourceResolver`** / **`inputRows`** so materialized row `input` uses **flat keys** matching `metadata.graphEntry.inputs` (requires **`@exellix/graph-engine` ≥ 5.16**). Wrap production executors with **`createMatrixExecuteGraphAdapter`** from runtime for stable defaults (run knobs only — model profiles belong on graph JSON, not runtime overrides). See [`examples/host-bootstrap.mjs`](./examples/host-bootstrap.mjs).
19
19
 
20
20
  ## Constraints
21
21
 
package/docs/specs.md CHANGED
@@ -1,11 +1,13 @@
1
- # `@exellix/exellix-jobs` — detailed specification (draft)
1
+ # `@exellix/exellix-jobs` — detailed specification
2
2
 
3
- **Status:** specification only — package **does not exist** yet.
4
- **Audience:** implementers of the new worker package and maintainers of **`@exellix/exellix-runtime`**, **`@exellix/graph-engine`**, **`@x12i/catalox`**.
5
- **Supersedes as normative worker doc:** the narrative in [`docs/execution-matrix-worker-service.md`](../execution-matrix-worker-service.md) once this package ships (that file should become a short pointer).
3
+ **Status:** implemented — see package README and [`docs/openapi.yaml`](./openapi.yaml).
4
+ **Audience:** implementers of the worker package and maintainers of **`@exellix/exellix-runtime`**, **`@exellix/graph-engine`**, **`@x12i/catalox`**.
5
+ **Supersedes as normative worker doc:** the narrative in [`docs/execution-matrix-worker-service.md`](../execution-matrix-worker-service.md) (historical pointer).
6
6
 
7
7
  **Hard rule:** **`@exellix/exellix-jobs`** must **not** import **`mongodb`** or **`@x12i/xronox-store`**. All matrix **data** access goes through **`createExellixMatrixDataTier`** on **`@exellix/exellix-runtime` ≥ 3.1**. **Metadata** (catalog listing, optional graph JSON from Catalox) uses **`@x12i/catalox`** where applicable.
8
8
 
9
+ **Graph model contract (7.x+):** AI profiles are graph-document only — `{ preActionModel, skillModel, postActionModel }` on `model.modelConfig` and optional partial `taskConfiguration.modelConfig`. No `runtime.modelConfig`, `runtime.aliasConfig`, or `runtime.nodes[id].modelConfig`. AI task nodes require explicit `executionStrategies: []` for plain MAIN. OpenRouter keys are env-only (`OPENROUTER_API_KEY`).
10
+
9
11
  ---
10
12
 
11
13
  ## 1. Package identity
@@ -72,7 +74,7 @@
72
74
  | Package | Semver policy | Usage |
73
75
  |---------|----------------|--------|
74
76
  | **`@exellix/exellix-runtime`** | **`^3.1.0`** | `createExellixMatrixDataTier`, `ExecutionMatrixRuntime`, `createExecutionMatrixRuntime`, `ExellixConfigStore`, `createExellixConfigStore`, `runMatrixCycle`, `runMatrixContinuously`, `processMatrixGraphBatch`, `processNextMatrixClaim`, `createExecutionMatrixClaimPauseController`, `buildExellixRuntimeRealLivenessPayload`, `runExellixRuntimeConnectivityProbe`, types from `contracts` |
75
- | **`@exellix/graph-engine`** | **≥ 5.16** (via runtime) | **`executeGraph`** — host supplies executor; record on **`runtime.input`** only (see §6.1) |
77
+ | **`@exellix/graph-engine`** | **≥ 7.7** (via runtime) | **`executeGraph`** — host supplies executor; record on **`runtime.input`** only; graph JSON model profiles (see §6.1) |
76
78
  | **`@x12i/catalox`** | Optional | Only if **`resolveGraphModel`** loads graph JSON from Firestore catalogs |
77
79
  | **`@x12i/env`** | Optional | `initConfig` for `.env` in dev |
78
80
 
@@ -109,8 +111,8 @@ Worker-specific rules:
109
111
  1. **`@exellix/exellix-jobs` never constructs `ExecuteGraphInput`** — it imports `runMatrixCycle` / `processMatrixGraphBatch` from **`@exellix/exellix-runtime`** and wraps the host `executeGraph` only for concurrency and metrics ([`wrap-execute-graph.ts`](../src/worker/wrap-execute-graph.ts)).
110
112
  2. **Materialize** — runtime persists the work-unit on **`ExecutionMatrixRuntimeRecord.input`**. The host must ensure **`sourceResolver`** / **`inputRows`** produce **flat** field names aligned with graph `graphEntry.inputs` (e.g. `subnetId`, `question` on the row object — not nested `raw` wrappers).
111
113
  3. **Execute** — orchestrator **`executeMatrixGraphForClaim`** sets **`runtime.input = record.input`**, seeds **`executionMemory`** via `buildExecutionSeedFromGraphEntry`, then calls **`executeGraph({ model, runtime })`**.
112
- 4. **Host `executeGraph`** — must accept `{ model, runtime }` only; use **`createMatrixExecuteGraphAdapter`** when layering defaults without overriding orchestrator-owned `jobId` / `job` / `input` / `executionMemory`.
113
- 5. **Dependencies** — **`@exellix/graph-engine` ≥ 5.16** (no implicit `job.raw` → `execution.input.raw` promotion). Align versions with **`@exellix/exellix-runtime`**.
114
+ 4. **Host `executeGraph`** — must accept `{ model, runtime }` only; use **`createMatrixExecuteGraphAdapter`** when layering run defaults without overriding orchestrator-owned `jobId` / `job` / `input` / `executionMemory`. Do not inject model profiles via runtime — set `model.modelConfig` / `taskConfiguration.modelConfig` on graph JSON.
115
+ 5. **Dependencies** — **`@exellix/graph-engine` ≥ 7.7** (no runtime model routing; no implicit `job.raw` → `execution.input.raw` promotion). Align versions with **`@exellix/exellix-runtime`**.
114
116
 
115
117
  ---
116
118
 
package/examples/host-bootstrap.mjs CHANGED
@@ -57,8 +57,10 @@ export default async function bootstrap() {
57
57
  };
58
58
  const graph = await loadGraphEngineBootstrap();
59
59
  // Production: wrap graph.executeGraph with createMatrixExecuteGraphAdapter from
60
- // @exellix/exellix-runtime (see docs/execution-matrix-runtime.md) so modelConfig defaults
60
+ // @exellix/exellix-runtime (see docs/execution-matrix-runtime.md) so run-level defaults
61
61
  // merge under orchestrator-owned jobId / job / input / executionMemory.
62
+ // Model profiles (preActionModel, skillModel, postActionModel) belong on graph JSON only —
63
+ // not runtime.modelConfig, runtime.aliasConfig, or executeOverrides model fields (7.7+).
62
64
  return {
63
65
  workerOptions: {
64
66
  persistence,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@exellix/exellix-jobs",
3
- "version": "4.1.8",
3
+ "version": "4.1.9",
4
4
  "description": "Execution-matrix worker: claims, run-loop, operator HTTP, and Prometheus metrics (XMemory-backed persistence).",
5
5
  "type": "module",
6
6
  "engines": {
@@ -47,8 +47,9 @@
47
47
  }
48
48
  },
49
49
  "dependencies": {
50
- "@exellix/ai-tasks": "^8.6.8",
51
- "@exellix/exellix-runtime": "^4.4.0",
50
+ "@exellix/ai-tasks": "^8.8.0",
51
+ "@exellix/exellix-runtime": "^4.4.2",
52
+ "@x12i/activix": "^8.6.0",
52
53
  "@x12i/logxer": "^4.6.0",
53
54
  "fastify": "^5.8.5",
54
55
  "p-limit": "^7.3.0",