@exellix/exellix-jobs 1.6.1

package/dist/worker/matrix-worker.js

@@ -0,0 +1,103 @@
+import { createExecutionMatrixClaimPauseController, createExecutionMatrixRuntime, createExellixConfigStore, } from '@exellix/exellix-runtime';
+import { createJobsMetrics } from '../metrics.js';
+import { MatrixCycleState } from './cycle-state.js';
+import { runMatrixContinuouslyByCatalogIdWithMetrics } from './continuous-loop.js';
+import { discoverMatrixAssignments } from './discovery.js';
+import { wrapMatrixGraphExecutor } from './wrap-execute-graph.js';
+export async function createMatrixWorker(options) {
+    await options.persistence.init?.();
+    const runtime = createExecutionMatrixRuntime(options.persistence.rows, options.persistence.failures, {
+        snapshots: options.persistence.snapshots,
+        serializeClaims: true,
+    });
+    const configStore = createExellixConfigStore({
+        matrices: options.persistence.matrices,
+        graphs: options.persistence.graphs,
+    });
+    const metrics = options.metrics ?? createJobsMetrics();
+    const pauseController = createExecutionMatrixClaimPauseController();
+    const cycleState = new MatrixCycleState();
+    const inFlight = new Map();
+    const maxConcurrentClaims = options.maxConcurrentClaims ?? 4;
+    let currentAssignments = [];
+    const executeGraph = wrapMatrixGraphExecutor({
+        inner: options.executeGraph,
+        maxConcurrentClaims,
+        perGraphConcurrency: options.perGraphConcurrency,
+        metrics,
+        onInFlightDelta: (graphId, delta) => {
+            const cur = inFlight.get(graphId) ?? 0;
+            const next = Math.max(0, cur + delta);
+            if (next === 0) {
+                inFlight.delete(graphId);
+            }
+            else {
+                inFlight.set(graphId, next);
+            }
+        },
+    });
+    const dispatchDeps = {
+        runtime,
+        configStore,
+        executeGraph,
+        resolveGraphModel: options.resolveGraphModel,
+        resolveGraphSchedulability: (graphId) => configStore.graphs.get(graphId),
+        graphSchedulabilityRequireConfig: options.graphSchedulabilityRequireConfig,
+        shouldClaimNext: () => pauseController.shouldClaimNext(),
+        sourceResolver: options.sourceResolver,
+        matrixActivix: options.matrixActivix,
+        matrixLogxer: options.matrixLogxer,
+        executeOverrides: options.executeOverrides,
+        runtimeScope: options.runtimeScope,
+        runtimeObjects: options.runtimeObjects,
+    };
+    const getStatus = (filter) => {
+        const activeJobsByGraphId = {};
+        for (const [gid, n] of inFlight) {
+            activeJobsByGraphId[gid] = n;
+        }
+        const assignments = filter?.matrixCatalogId
+            ? currentAssignments.filter((a) => a.matrixCatalogId === filter.matrixCatalogId)
+            : currentAssignments;
+        const catalogIds = assignments.map((a) => a.matrixCatalogId);
+        const graphIds = [...new Set(assignments.flatMap((a) => a.graphIds))].sort();
+        return {
+            ...(options.matrixWorkerId !== undefined ? { matrixWorkerId: options.matrixWorkerId } : {}),
+            assignedMatrixCatalogIds: catalogIds,
+            assignedGraphIds: graphIds,
+            activeJobsByGraphId,
+            activeJobs: { ...activeJobsByGraphId },
+            maxConcurrency: maxConcurrentClaims,
+            paused: pauseController.isPaused(),
+            loops: cycleState.snapshot(filter),
+        };
+    };
+    const startSupervised = async (signal, opts) => {
+        const assignments = opts && 'assignments' in opts && opts.assignments !== undefined
+            ? opts.assignments
+            : await discoverMatrixAssignments(configStore);
+        currentAssignments = assignments;
+        await Promise.all(assignments.map((a) => runMatrixContinuouslyByCatalogIdWithMetrics(dispatchDeps, {
+            matrixCatalogId: a.matrixCatalogId,
+            matrixItemId: a.matrixItemId,
+            matrixRunId: a.matrixRunId,
+            signal,
+            cycleState,
+        }, metrics)));
+    };
+    const close = async () => {
+        await options.persistence.close();
+    };
+    return {
+        runtime,
+        configStore,
+        metrics,
+        pauseController,
+        connectivityProbe: options.persistence.probe,
+        getStatus,
+        startSupervised,
+        close,
+    };
+}
+export { discoverMatrixAssignments, listGraphSummaries } from './discovery.js';
+//# sourceMappingURL=matrix-worker.js.map

package/dist/worker/matrix-worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"matrix-worker.js","sourceRoot":"","sources":["../../src/worker/matrix-worker.ts"],"names":[],"mappings":"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"}

package/dist/worker/wrap-execute-graph.d.ts

@@ -0,0 +1,14 @@
+import type { MatrixGraphExecutor } from '@exellix/exellix-runtime';
+import type { JobsMetrics } from '../metrics.js';
+export type WrapMatrixGraphExecutorOptions = {
+    inner: MatrixGraphExecutor;
+    maxConcurrentClaims: number;
+    perGraphConcurrency?: Record<string, number>;
+    metrics?: JobsMetrics;
+    onInFlightDelta?: (graphId: string, delta: 1 | -1) => void;
+};
+/**
+ * Global and optional per-graph concurrency around graph-engine execution, plus §11 counters/histogram.
+ */
+export declare function wrapMatrixGraphExecutor(opts: WrapMatrixGraphExecutorOptions): MatrixGraphExecutor;
+//# sourceMappingURL=wrap-execute-graph.d.ts.map

package/dist/worker/wrap-execute-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrap-execute-graph.d.ts","sourceRoot":"","sources":["../../src/worker/wrap-execute-graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAKjD,MAAM,MAAM,8BAA8B,GAAG;IAC3C,KAAK,EAAE,mBAAmB,CAAC;IAC3B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7C,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC;CAC5D,CAAC;AAkBF;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,8BAA8B,GAAG,mBAAmB,CA2CjG"}

package/dist/worker/wrap-execute-graph.js

@@ -0,0 +1,61 @@
+import pLimit from 'p-limit';
+function resolveGraphId(input) {
+    const job = input.runtime?.job;
+    const fromJob = job?.graphId ?? job?.graph_id;
+    if (typeof fromJob === 'string' && fromJob.length > 0) {
+        return fromJob;
+    }
+    const id = input.model?.id;
+    return typeof id === 'string' && id.length > 0 ? id : 'unknown';
+}
+function resolveMatrixCatalogId(input) {
+    const job = input.runtime?.job;
+    const raw = job?.matrixCatalogId ?? job?.matrix_catalog_id;
+    return typeof raw === 'string' && raw.length > 0 ? raw : 'unknown';
+}
+/**
+ * Global and optional per-graph concurrency around graph-engine execution, plus §11 counters/histogram.
+ */
+export function wrapMatrixGraphExecutor(opts) {
+    const globalLimit = pLimit(opts.maxConcurrentClaims);
+    const perGraphLimits = new Map();
+    const perGraphMax = opts.perGraphConcurrency ?? {};
+    const getPerGraphLimit = (graphId) => {
+        const cap = perGraphMax[graphId];
+        if (cap === undefined || cap < 1) {
+            return undefined;
+        }
+        let lim = perGraphLimits.get(graphId);
+        if (!lim) {
+            lim = pLimit(cap);
+            perGraphLimits.set(graphId, lim);
+        }
+        return lim;
+    };
+    return async (input) => {
+        const graphId = resolveGraphId(input);
+        const matrixCatalogId = resolveMatrixCatalogId(input);
+        const run = async () => {
+            const t0 = performance.now();
+            opts.metrics?.matrixClaimsStartedTotal.inc({ graph_id: graphId, matrix_catalog_id: matrixCatalogId });
+            opts.onInFlightDelta?.(graphId, 1);
+            try {
+                const result = await opts.inner(input);
+                opts.metrics?.matrixClaimsCompletedTotal.inc({ graph_id: graphId, status: result.status });
+                return result;
+            }
+            catch (err) {
+                opts.metrics?.matrixClaimsFailedTotal.inc({ graph_id: graphId });
+                throw err;
+            }
+            finally {
+                opts.onInFlightDelta?.(graphId, -1);
+                const secs = (performance.now() - t0) / 1000;
+                opts.metrics?.executeGraphDurationSeconds.observe({ graph_id: graphId }, secs);
+            }
+        };
+        const per = getPerGraphLimit(graphId);
+        return globalLimit(() => (per ? per(run) : run()));
+    };
+}
+//# sourceMappingURL=wrap-execute-graph.js.map

package/dist/worker/wrap-execute-graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrap-execute-graph.js","sourceRoot":"","sources":["../../src/worker/wrap-execute-graph.ts"],"names":[],"mappings":"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"}

package/dist/xmemory-matrix-tier.d.ts

@@ -0,0 +1,7 @@
+import type { ExellixMatrixPersistenceHandles, OpenExellixMatrixPersistenceOptions } from './collections.js';
+/**
+ * Resolves {@link createExellixMatrixDataTier} from `@exellix/exellix-runtime` (≥ 3.1)
+ * so `@exellix/exellix-jobs` stays free of direct `@x12i/xronox-store` imports (see `docs/specs.md` §5–§6).
+ */
+export declare function openExellixMatrixPersistenceFromXmemoryStore(options: OpenExellixMatrixPersistenceOptions): Promise<ExellixMatrixPersistenceHandles>;
+//# sourceMappingURL=xmemory-matrix-tier.d.ts.map

package/dist/xmemory-matrix-tier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xmemory-matrix-tier.d.ts","sourceRoot":"","sources":["../src/xmemory-matrix-tier.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,+BAA+B,EAE/B,mCAAmC,EACpC,MAAM,kBAAkB,CAAC;AA8C1B;;;GAGG;AACH,wBAAsB,4CAA4C,CAChE,OAAO,EAAE,mCAAmC,GAC3C,OAAO,CAAC,+BAA+B,CAAC,CAuB1C"}

package/dist/xmemory-matrix-tier.js

@@ -0,0 +1,65 @@
+const FACTORY = 'createExellixMatrixDataTier';
+const FACTORY_PACKAGE = '@exellix/exellix-runtime';
+async function loadMatrixDataTierFactory() {
+    try {
+        const mod = (await import(FACTORY_PACKAGE));
+        const factory = mod[FACTORY];
+        if (typeof factory === 'function') {
+            return factory;
+        }
+        throw new Error(`"${FACTORY}" is not exported`);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`@exellix/exellix-jobs: "${FACTORY}" is not available from ${FACTORY_PACKAGE} (peer ^3.1.0 required). ${message} ` +
+            'Wire persistence by passing pre-built handles to createMatrixWorker(), ' +
+            'or use openExellixMatrixPersistence() / openExellixMatrixPersistenceFromRuntimeFactories().');
+    }
+}
+function extractProbeHandles(tier) {
+    if (!tier || typeof tier !== 'object') {
+        return undefined;
+    }
+    const t = tier;
+    const probe = {};
+    if (t.executionStore !== undefined) {
+        probe.executionStore = t.executionStore;
+    }
+    if (t.configStore !== undefined) {
+        probe.configStore = t.configStore;
+    }
+    if (typeof t.executionMongoUri === 'string') {
+        probe.executionMongoUri = t.executionMongoUri;
+    }
+    if (typeof t.configMongoUri === 'string') {
+        probe.configMongoUri = t.configMongoUri;
+    }
+    return Object.keys(probe).length > 0 ? probe : undefined;
+}
+/**
+ * Resolves {@link createExellixMatrixDataTier} from `@exellix/exellix-runtime` (≥ 3.1)
+ * so `@exellix/exellix-jobs` stays free of direct `@x12i/xronox-store` imports (see `docs/specs.md` §5–§6).
+ */
+export async function openExellixMatrixPersistenceFromXmemoryStore(options) {
+    const factory = await loadMatrixDataTierFactory();
+    const tier = await factory(options);
+    const t = tier;
+    const { rows, failures, matrices, graphs, close } = t;
+    if (!rows || !failures || !matrices || !graphs || typeof close !== 'function') {
+        throw new Error(`@exellix/exellix-jobs: "${FACTORY}" returned an object missing rows, failures, matrices, graphs, or close().`);
+    }
+    if (t.init) {
+        await t.init();
+    }
+    const probe = extractProbeHandles(tier);
+    return {
+        rows,
+        failures,
+        snapshots: t.snapshots,
+        matrices,
+        graphs,
+        close: () => Promise.resolve(close.call(tier)),
+        ...(probe ? { probe } : {}),
+    };
+}
+//# sourceMappingURL=xmemory-matrix-tier.js.map

package/dist/xmemory-matrix-tier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"xmemory-matrix-tier.js","sourceRoot":"","sources":["../src/xmemory-matrix-tier.ts"],"names":[],"mappings":"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"}

package/docs/execution-matrix-worker-service.md

@@ -0,0 +1,8 @@
+# Execution matrix worker service (historical)
+
+This document is **historical**. Normative worker behavior lives in:
+
+- **[`docs/specs.md`](./specs.md)** — operator HTTP, metrics, concurrency, discovery (in this package)
+- **`@exellix/exellix-jobs` README** — programmatic API and CLI bootstrap
+
+Use **`exellix-jobs serve`** with **`EXELLIX_JOBS_HOST_BOOTSTRAP`** (see [`examples/host-bootstrap.mjs`](../examples/host-bootstrap.mjs)) instead of wiring a bespoke worker process in `@exellix/exellix-runtime`.

package/docs/openapi.yaml

@@ -0,0 +1,122 @@
+openapi: 3.0.3
+info:
+  title: Exellix Jobs Operator API
+  version: 1.0.0
+  description: |
+    Operator HTTP surface for `@exellix/exellix-jobs`. Base path is configurable via `JOBS_HTTP_PREFIX` (default `/v1`).
+servers:
+  - url: /v1
+paths:
+  /health:
+    get:
+      summary: Liveness or dependency readiness
+      parameters:
+        - in: query
+          name: probe
+          schema:
+            type: string
+            enum: [dependencies]
+          description: When `dependencies`, runs connectivity probe (Mongo / XMemory env / optional Activix).
+      responses:
+        '200':
+          description: Health payload
+  /graphs:
+    get:
+      summary: Graph summaries with matrix catalog references
+      responses:
+        '200':
+          description: Graph list
+  /workers/status:
+    get:
+      summary: Worker introspection
+      parameters:
+        - in: query
+          name: matrixCatalogId
+          schema:
+            type: string
+          description: Filter status to a single matrix catalog id.
+      responses:
+        '200':
+          description: Worker status including loop timestamps
+  /metrics:
+    get:
+      summary: Prometheus metrics
+      responses:
+        '200':
+          description: text/plain exposition format
+  /graphs/{graphId}/operational:
+    patch:
+      summary: Patch graph operational state
+      security:
+        - ApiKeyAuth: []
+      parameters:
+        - in: path
+          name: graphId
+          required: true
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [expectedVersion]
+              properties:
+                expectedVersion:
+                  type: integer
+                operationalState:
+                  type: string
+      responses:
+        '200':
+          description: Updated graph record
+        '401':
+          description: Unauthorized
+  /graphs/{graphId}/publication:
+    patch:
+      summary: Patch graph publication status
+      security:
+        - ApiKeyAuth: []
+      parameters:
+        - in: path
+          name: graphId
+          required: true
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [expectedVersion]
+              properties:
+                expectedVersion:
+                  type: integer
+                publicationStatus:
+                  type: string
+      responses:
+        '200':
+          description: Updated graph record
+  /workers/pause:
+    post:
+      summary: Pause new matrix claims (extension)
+      security:
+        - ApiKeyAuth: []
+      responses:
+        '200':
+          description: Paused
+  /workers/resume:
+    post:
+      summary: Resume matrix claims (extension)
+      security:
+        - ApiKeyAuth: []
+      responses:
+        '200':
+          description: Resumed
+components:
+  securitySchemes:
+    ApiKeyAuth:
+      type: apiKey
+      in: header
+      name: x-exellix-jobs-api-key