@exellix/exellix-jobs

Execution-matrix worker package: supervised runMatrixContinuously loops, operator HTTP (/health, /metrics, graph PATCH), and Prometheus metrics — wired to @exellix/exellix-runtime ≥ 3.1 and matrix persistence via createExellixMatrixDataTier (legacy xronox-factory fallback optional).

Normative behavior is specified in docs/specs.md. docs/execution-matrix-worker-service.md is a short historical pointer. HTTP routes are cataloged in docs/openapi.yaml. Local issues (404 PATCH paths, tombstoned graphs, idle worker, …): docs/troubleshooting.md.

Graph execution input (record placement)

Peer contract for where the work-unit record goes on executeGraph and matrix runs: ../exellix-runtime/docs/graph-execution-record-placement.md.

This worker does not call executeGraph itself. It passes your host executeGraph into @exellix/exellix-runtime, which builds { model, runtime } and sets runtime.input = record.input at claim time.

| Phase | Where the record lives | |-------|-------------------------| | Materialize | ExecutionMatrixRuntimeRecord.input — flat field names (subnetId, question, …), not input.raw | | Execute | runtime.input on the graph-engine request (same blob as row input) |

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).

Constraints

• No direct mongodb or @x12i/xronox-store dependency in this package’s package.json or source imports.
• Matrix collections are xronox-shaped handles from createExellixMatrixDataTier on @exellix/exellix-runtime, or via openExellixMatrixPersistence() / openExellixMatrixPersistenceFromRuntimeFactories() as a bridge.

Programmatic API

import { createExellixMatrixDataTier } from '@exellix/exellix-runtime';
import {
  createMatrixWorker,
  startMatrixWorkerHttp,
  loadJobsEnv,
} from '@exellix/exellix-jobs';

const env = loadJobsEnv();
const tier = await createExellixMatrixDataTier({
  mongoUri: process.env.MONGO_URI,
  executionDb: env.executionDb,
  configDb: env.configDb,
});
const persistence = {
  rows: tier.rows,
  failures: tier.failures,
  snapshots: tier.snapshots,
  matrices: tier.matrices,
  graphs: tier.graphs,
  close: () => tier.close(),
  ...(tier.probe ? { probe: tier.probe } : {}),
};

const worker = await createMatrixWorker({
  persistence,
  matrixWorkerId: env.matrixWorkerId,
  executeGraph: graphRuntime.executeGraph.bind(graphRuntime),
  resolveGraphModel: async ({ graphId }) => { /* … */ },
  sourceResolver,
  graphSchedulabilityRequireConfig: env.graphSchedulabilityStrict,
  maxConcurrentClaims: env.maxConcurrentClaims,
});

const ac = new AbortController();
void worker.startSupervised(ac.signal);
await startMatrixWorkerHttp({ worker, env: loadJobsEnv() });

CLI

exellix-jobs serve loads an application bootstrap module so graph-engine wiring stays in the host:

• Set EXELLIX_JOBS_HOST_BOOTSTRAP to an absolute path of an ESM file whose default export is an async function returning { workerOptions } (see CreateMatrixWorkerOptions).
• See examples/host-bootstrap.mjs for createExellixMatrixDataTier + env wiring; set EXELLIX_JOBS_GRAPH_ENGINE_BOOTSTRAP for executeGraph / resolveGraphModel.

npm run jobs:serve

Operator routes use suffix paths — e.g. PATCH /v1/graphs/{graphId}/operational, not PATCH /v1/graphs/{graphId}. See docs/troubleshooting.md.

Optional: install @x12i/env next to this package for .env loading via dynamic import in the CLI.

Environment

See docs/specs.md §12. Implemented keys include:

| Variable | Purpose | |----------|---------| | PORT | HTTP listen port | | JOBS_HTTP_PREFIX | Route prefix (default /v1) | | MATRIX_WORKER_ID | Identity in /health and /workers/status | | execution_db / config_db | Persistence DB names | | EXELLIX_JOBS_MAX_CONCURRENT_CLAIMS | Global parallelism | | EXELLIX_JOBS_GRAPH_SCHEDULABILITY_STRICT | Schedulability flag | | EXELLIX_JOBS_HTTP_ENABLED | Start HTTP server | | EXELLIX_JOBS_API_KEY | Mutating HTTP routes | | EXELLIX_JOBS_ACTIVIX_SCHEDULER_PROBE | Activix lane on dependency probe |

HA note

Multiple replicas claiming the same matrix without coordination can double-execute; see docs/specs.md §15.

Read tier (entity + graph history)

Job counts, slot status, and execution output for dashboards live in @exellix/exellix-matrix-read (sibling package) — not in this worker. Use it from BFF/Studio; keep this package for claim/execute only.