@exellix/exellix-jobs 1.6.1

package/dist/metrics.js

@@ -0,0 +1,57 @@
+import { Counter, Histogram, Registry } from 'prom-client';
+export function createJobsMetrics(registry = new Registry()) {
+    const matrixClaimsStartedTotal = new Counter({
+        name: 'matrix_claims_started_total',
+        help: 'Matrix claims started (before executeGraph).',
+        labelNames: ['graph_id', 'matrix_catalog_id'],
+        registers: [registry],
+    });
+    const matrixClaimsCompletedTotal = new Counter({
+        name: 'matrix_claims_completed_total',
+        help: 'Matrix claims completed with graph-engine terminal status.',
+        labelNames: ['graph_id', 'status'],
+        registers: [registry],
+    });
+    const matrixClaimsFailedTotal = new Counter({
+        name: 'matrix_claims_failed_total',
+        help: 'Matrix claims failed (executor throw or failure path).',
+        labelNames: ['graph_id'],
+        registers: [registry],
+    });
+    const matrixRowsMaterializedTotal = new Counter({
+        name: 'matrix_rows_materialized_total',
+        help: 'Runtime rows inserted by matrix materializer.',
+        labelNames: ['matrix_catalog_id'],
+        registers: [registry],
+    });
+    const matrixWorkerIdleSecondsTotal = new Counter({
+        name: 'matrix_worker_idle_seconds_total',
+        help: 'Approximate idle time in empty-pass cycles (seconds).',
+        labelNames: ['matrix_catalog_id'],
+        registers: [registry],
+    });
+    const matrixWorkerCyclesTotal = new Counter({
+        name: 'matrix_worker_cycles_total',
+        help: 'Completed runMatrixCycle invocations.',
+        labelNames: ['matrix_catalog_id', 'empty'],
+        registers: [registry],
+    });
+    const executeGraphDurationSeconds = new Histogram({
+        name: 'matrix_execute_graph_duration_seconds',
+        help: 'executeGraph wall time (seconds).',
+        labelNames: ['graph_id'],
+        buckets: [0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 15, 60, 300],
+        registers: [registry],
+    });
+    return {
+        registry,
+        matrixClaimsStartedTotal,
+        matrixClaimsCompletedTotal,
+        matrixClaimsFailedTotal,
+        matrixRowsMaterializedTotal,
+        matrixWorkerIdleSecondsTotal,
+        matrixWorkerCyclesTotal,
+        executeGraphDurationSeconds,
+    };
+}
+//# sourceMappingURL=metrics.js.map

package/dist/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../src/metrics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAa3D,MAAM,UAAU,iBAAiB,CAAC,QAAQ,GAAG,IAAI,QAAQ,EAAE;IACzD,MAAM,wBAAwB,GAAG,IAAI,OAAO,CAAC;QAC3C,IAAI,EAAE,6BAA6B;QACnC,IAAI,EAAE,8CAA8C;QACpD,UAAU,EAAE,CAAC,UAAU,EAAE,mBAAmB,CAAC;QAC7C,SAAS,EAAE,CAAC,QAAQ,CAAC;KACtB,CAAC,CAAC;IACH,MAAM,0BAA0B,GAAG,IAAI,OAAO,CAAC;QAC7C,IAAI,EAAE,+BAA+B;QACrC,IAAI,EAAE,4DAA4D;QAClE,UAAU,EAAE,CAAC,UAAU,EAAE,QAAQ,CAAC;QAClC,SAAS,EAAE,CAAC,QAAQ,CAAC;KACtB,CAAC,CAAC;IACH,MAAM,uBAAuB,GAAG,IAAI,OAAO,CAAC;QAC1C,IAAI,EAAE,4BAA4B;QAClC,IAAI,EAAE,wDAAwD;QAC9D,UAAU,EAAE,CAAC,UAAU,CAAC;QACxB,SAAS,EAAE,CAAC,QAAQ,CAAC;KACtB,CAAC,CAAC;IACH,MAAM,2BAA2B,GAAG,IAAI,OAAO,CAAC;QAC9C,IAAI,EAAE,gCAAgC;QACtC,IAAI,EAAE,+CAA+C;QACrD,UAAU,EAAE,CAAC,mBAAmB,CAAC;QACjC,SAAS,EAAE,CAAC,QAAQ,CAAC;KACtB,CAAC,CAAC;IACH,MAAM,4BAA4B,GAAG,IAAI,OAAO,CAAC;QAC/C,IAAI,EAAE,kCAAkC;QACxC,IAAI,EAAE,uDAAuD;QAC7D,UAAU,EAAE,CAAC,mBAAmB,CAAC;QACjC,SAAS,EAAE,CAAC,QAAQ,CAAC;KACtB,CAAC,CAAC;IACH,MAAM,uBAAuB,GAAG,IAAI,OAAO,CAAC;QAC1C,IAAI,EAAE,4BAA4B;QAClC,IAAI,EAAE,uCAAuC;QAC7C,UAAU,EAAE,CAAC,mBAAmB,EAAE,OAAO,CAAC;QAC1C,SAAS,EAAE,CAAC,QAAQ,CAAC;KACtB,CAAC,CAAC;IACH,MAAM,2BAA2B,GAAG,IAAI,SAAS,CAAC;QAChD,IAAI,EAAE,uCAAuC;QAC7C,IAAI,EAAE,mCAAmC;QACzC,UAAU,EAAE,CAAC,UAAU,CAAC;QACxB,OAAO,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,CAAC;QACvD,SAAS,EAAE,CAAC,QAAQ,CAAC;KACtB,CAAC,CAAC;IACH,OAAO;QACL,QAAQ;QACR,wBAAwB;QACxB,0BAA0B;QAC1B,uBAAuB;QACvB,2BAA2B;QAC3B,4BAA4B;QAC5B,uBAAuB;QACvB,2BAA2B;KAC5B,CAAC;AACJ,CAAC"}

package/dist/open-matrix-persistence.d.ts

@@ -0,0 +1,7 @@
+import type { ExellixMatrixPersistenceHandles, OpenExellixMatrixPersistenceOptions } from './collections.js';
+/**
+ * Preferred persistence opener: {@link createExellixMatrixDataTier} from `@exellix/exellix-runtime` (≥ 3.1),
+ * otherwise legacy runtime xronox factories when {@link OpenExellixMatrixPersistenceOptions.fallbackToRuntimeFactories} is enabled.
+ */
+export declare function openExellixMatrixPersistence(options?: OpenExellixMatrixPersistenceOptions): Promise<ExellixMatrixPersistenceHandles>;
+//# sourceMappingURL=open-matrix-persistence.d.ts.map

package/dist/open-matrix-persistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"open-matrix-persistence.d.ts","sourceRoot":"","sources":["../src/open-matrix-persistence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,+BAA+B,EAAE,mCAAmC,EAAE,MAAM,kBAAkB,CAAC;AAa7G;;;GAGG;AACH,wBAAsB,4BAA4B,CAChD,OAAO,GAAE,mCAAwC,GAChD,OAAO,CAAC,+BAA+B,CAAC,CAe1C"}

package/dist/open-matrix-persistence.js

@@ -0,0 +1,29 @@
+import { resolveMatrixPersistenceOptionsFromEnv } from './persistence-env.js';
+import { openExellixMatrixPersistenceFromRuntimeFactories } from './runtime-matrix-tier.js';
+import { openExellixMatrixPersistenceFromXmemoryStore } from './xmemory-matrix-tier.js';
+function isMatrixDataTierFactoryUnavailable(err) {
+    return (err instanceof Error &&
+        err.message.includes('createExellixMatrixDataTier') &&
+        (err.message.includes('not exported') || err.message.includes('not available')));
+}
+/**
+ * Preferred persistence opener: {@link createExellixMatrixDataTier} from `@exellix/exellix-runtime` (≥ 3.1),
+ * otherwise legacy runtime xronox factories when {@link OpenExellixMatrixPersistenceOptions.fallbackToRuntimeFactories} is enabled.
+ */
+export async function openExellixMatrixPersistence(options = {}) {
+    const resolved = resolveMatrixPersistenceOptionsFromEnv(options);
+    const fallback = resolved.fallbackToRuntimeFactories !== false;
+    try {
+        return await openExellixMatrixPersistenceFromXmemoryStore(resolved);
+    }
+    catch (err) {
+        if (!fallback) {
+            throw err;
+        }
+        if (!isMatrixDataTierFactoryUnavailable(err)) {
+            throw err;
+        }
+        return openExellixMatrixPersistenceFromRuntimeFactories(resolved);
+    }
+}
+//# sourceMappingURL=open-matrix-persistence.js.map

package/dist/open-matrix-persistence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"open-matrix-persistence.js","sourceRoot":"","sources":["../src/open-matrix-persistence.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,sCAAsC,EAAE,MAAM,sBAAsB,CAAC;AAC9E,OAAO,EAAE,gDAAgD,EAAE,MAAM,0BAA0B,CAAC;AAC5F,OAAO,EAAE,4CAA4C,EAAE,MAAM,0BAA0B,CAAC;AAExF,SAAS,kCAAkC,CAAC,GAAY;IACtD,OAAO,CACL,GAAG,YAAY,KAAK;QACpB,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,6BAA6B,CAAC;QACnD,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC,CAChF,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAChD,UAA+C,EAAE;IAEjD,MAAM,QAAQ,GAAG,sCAAsC,CAAC,OAAO,CAAC,CAAC;IACjE,MAAM,QAAQ,GAAG,QAAQ,CAAC,0BAA0B,KAAK,KAAK,CAAC;IAE/D,IAAI,CAAC;QACH,OAAO,MAAM,4CAA4C,CAAC,QAAQ,CAAC,CAAC;IACtE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,GAAG,CAAC;QACZ,CAAC;QACD,IAAI,CAAC,kCAAkC,CAAC,GAAG,CAAC,EAAE,CAAC;YAC7C,MAAM,GAAG,CAAC;QACZ,CAAC;QACD,OAAO,gDAAgD,CAAC,QAAQ,CAAC,CAAC;IACpE,CAAC;AACH,CAAC"}

package/dist/persistence-env.d.ts

@@ -0,0 +1,7 @@
+import type { OpenExellixMatrixPersistenceOptions } from './collections.js';
+import { type JobsEnv } from './env.js';
+/**
+ * Merges {@link loadJobsEnv} database names (and optional caller overrides) into persistence opener options.
+ */
+export declare function resolveMatrixPersistenceOptionsFromEnv(overrides?: OpenExellixMatrixPersistenceOptions, env?: JobsEnv): OpenExellixMatrixPersistenceOptions;
+//# sourceMappingURL=persistence-env.d.ts.map

package/dist/persistence-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence-env.d.ts","sourceRoot":"","sources":["../src/persistence-env.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mCAAmC,EAAE,MAAM,kBAAkB,CAAC;AAC5E,OAAO,EAAe,KAAK,OAAO,EAAE,MAAM,UAAU,CAAC;AAErD;;GAEG;AACH,wBAAgB,sCAAsC,CACpD,SAAS,GAAE,mCAAwC,EACnD,GAAG,GAAE,OAAuB,GAC3B,mCAAmC,CAQrC"}

package/dist/persistence-env.js

@@ -0,0 +1,14 @@
+import { loadJobsEnv } from './env.js';
+/**
+ * Merges {@link loadJobsEnv} database names (and optional caller overrides) into persistence opener options.
+ */
+export function resolveMatrixPersistenceOptionsFromEnv(overrides = {}, env = loadJobsEnv()) {
+    const mongoUri = overrides.mongoUri ?? (process.env.MONGO_URI?.trim() || undefined);
+    return {
+        ...overrides,
+        ...(mongoUri !== undefined ? { mongoUri } : {}),
+        executionDb: overrides.executionDb ?? env.executionDb,
+        configDb: overrides.configDb ?? env.configDb,
+    };
+}
+//# sourceMappingURL=persistence-env.js.map

package/dist/persistence-env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence-env.js","sourceRoot":"","sources":["../src/persistence-env.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAgB,MAAM,UAAU,CAAC;AAErD;;GAEG;AACH,MAAM,UAAU,sCAAsC,CACpD,YAAiD,EAAE,EACnD,MAAe,WAAW,EAAE;IAE5B,MAAM,QAAQ,GAAG,SAAS,CAAC,QAAQ,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,SAAS,CAAC,CAAC;IACpF,OAAO;QACL,GAAG,SAAS;QACZ,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,WAAW,EAAE,SAAS,CAAC,WAAW,IAAI,GAAG,CAAC,WAAW;QACrD,QAAQ,EAAE,SAAS,CAAC,QAAQ,IAAI,GAAG,CAAC,QAAQ;KAC7C,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,8 @@
+import type { ExellixMatrixPersistenceHandles, OpenExellixMatrixPersistenceOptions } from './collections.js';
+/**
+ * Opens matrix persistence via legacy `@exellix/exellix-runtime` xronox factories when
+ * {@link createExellixMatrixDataTier} is unavailable. Prefer {@link openExellixMatrixPersistenceFromXmemoryStore}.
+ * No direct `@x12i/xronox-store` import in jobs.
+ */
+export declare function openExellixMatrixPersistenceFromRuntimeFactories(options?: OpenExellixMatrixPersistenceOptions): Promise<ExellixMatrixPersistenceHandles>;
+//# sourceMappingURL=runtime-matrix-tier.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-matrix-tier.d.ts","sourceRoot":"","sources":["../src/runtime-matrix-tier.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,+BAA+B,EAAE,mCAAmC,EAAE,MAAM,kBAAkB,CAAC;AAK7G;;;;GAIG;AACH,wBAAsB,gDAAgD,CACpE,OAAO,GAAE,mCAAwC,GAChD,OAAO,CAAC,+BAA+B,CAAC,CAmE1C"}

package/dist/runtime-matrix-tier.js

@@ -0,0 +1,57 @@
+import { resolveMatrixPersistenceOptionsFromEnv } from './persistence-env.js';
+/**
+ * Opens matrix persistence via legacy `@exellix/exellix-runtime` xronox factories when
+ * {@link createExellixMatrixDataTier} is unavailable. Prefer {@link openExellixMatrixPersistenceFromXmemoryStore}.
+ * No direct `@x12i/xronox-store` import in jobs.
+ */
+export async function openExellixMatrixPersistenceFromRuntimeFactories(options = {}) {
+    const resolved = resolveMatrixPersistenceOptionsFromEnv(options);
+    const mongoUri = resolved.mongoUri ?? process.env.MONGO_URI?.trim();
+    if (!mongoUri) {
+        throw new Error('@exellix/exellix-jobs: MONGO_URI is required to open matrix persistence via runtime factories.');
+    }
+    const runtime = (await import('@exellix/exellix-runtime'));
+    const xronox = (await import('@exellix/exellix-runtime/internal/xronox-matrix'));
+    const { createExecutionMatrixRuntimeFromXronox, createExellixConfigStoreFromXronox, } = xronox;
+    const { executionMatrixRowsCollectionDef, executionMatrixFailuresCollectionDef, executionMatrixSnapshotsCollectionDef, exellixMatrixConfigsCollectionDef, exellixGraphConfigsCollectionDef, } = runtime;
+    const exec = await createExecutionMatrixRuntimeFromXronox({
+        mongoUri,
+        mongoDb: resolved.executionDb,
+        serializeClaims: true,
+    });
+    const cfg = await createExellixConfigStoreFromXronox({
+        mongoUri,
+        mongoDb: resolved.configDb,
+    });
+    const rows = exec.store.collection(executionMatrixRowsCollectionDef().name);
+    const failures = exec.store.collection(executionMatrixFailuresCollectionDef().name);
+    const snapshots = exec.store.collection(executionMatrixSnapshotsCollectionDef().name);
+    const matrices = cfg.store.collection(exellixMatrixConfigsCollectionDef().name);
+    const graphs = cfg.store.collection(exellixGraphConfigsCollectionDef().name);
+    let closed = false;
+    const close = async () => {
+        if (closed) {
+            return;
+        }
+        closed = true;
+        await exec.store.close().catch(() => undefined);
+        await cfg.store.close().catch(() => undefined);
+        await exec.closeMongoDriverPassThrough?.().catch(() => undefined);
+        await cfg.closeMongoDriverPassThrough?.().catch(() => undefined);
+    };
+    return {
+        rows,
+        failures,
+        snapshots,
+        matrices,
+        graphs,
+        close,
+        probe: {
+            executionStore: exec.store,
+            configStore: cfg.store,
+            executionMongoUri: mongoUri,
+            configMongoUri: mongoUri,
+        },
+    };
+}
+//# sourceMappingURL=runtime-matrix-tier.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-matrix-tier.js","sourceRoot":"","sources":["../src/runtime-matrix-tier.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,sCAAsC,EAAE,MAAM,sBAAsB,CAAC;AAI9E;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,gDAAgD,CACpE,UAA+C,EAAE;IAEjD,MAAM,QAAQ,GAAG,sCAAsC,CAAC,OAAO,CAAC,CAAC;IACjE,MAAM,QAAQ,GAAG,QAAQ,CAAC,QAAQ,IAAI,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,EAAE,CAAC;IACpE,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CACb,gGAAgG,CACjG,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,CAAC,MAAM,MAAM,CAAC,0BAA0B,CAAC,CAA8C,CAAC;IACxG,MAAM,MAAM,GAAG,CAAC,MAAM,MAAM,CAC1B,iDAAiD,CAClD,CAA+B,CAAC;IACjC,MAAM,EACJ,sCAAsC,EACtC,kCAAkC,GACnC,GAAG,MAAM,CAAC;IACX,MAAM,EACJ,gCAAgC,EAChC,oCAAoC,EACpC,qCAAqC,EACrC,iCAAiC,EACjC,gCAAgC,GACjC,GAAG,OAAO,CAAC;IAEZ,MAAM,IAAI,GAAG,MAAM,sCAAsC,CAAC;QACxD,QAAQ;QACR,OAAO,EAAE,QAAQ,CAAC,WAAW;QAC7B,eAAe,EAAE,IAAI;KACtB,CAAC,CAAC;IACH,MAAM,GAAG,GAAG,MAAM,kCAAkC,CAAC;QACnD,QAAQ;QACR,OAAO,EAAE,QAAQ,CAAC,QAAQ;KAC3B,CAAC,CAAC;IAEH,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,gCAAgC,EAAE,CAAC,IAAI,CAAC,CAAC;IAC5E,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,oCAAoC,EAAE,CAAC,IAAI,CAAC,CAAC;IACpF,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,qCAAqC,EAAE,CAAC,IAAI,CAAC,CAAC;IACtF,MAAM,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,iCAAiC,EAAE,CAAC,IAAI,CAAC,CAAC;IAChF,MAAM,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,gCAAgC,EAAE,CAAC,IAAI,CAAC,CAAC;IAE7E,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,MAAM,KAAK,GAAG,KAAK,IAAmB,EAAE;QACtC,IAAI,MAAM,EAAE,CAAC;YACX,OAAO;QACT,CAAC;QACD,MAAM,GAAG,IAAI,CAAC;QACd,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAChD,MAAM,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC/C,MAAM,IAAI,CAAC,2BAA2B,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAClE,MAAM,GAAG,CAAC,2BAA2B,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IACnE,CAAC,CAAC;IAEF,OAAO;QACL,IAAI;QACJ,QAAQ;QACR,SAAS;QACT,QAAQ;QACR,MAAM;QACN,KAAK;QACL,KAAK,EAAE;YACL,cAAc,EAAE,IAAI,CAAC,KAAK;YAC1B,WAAW,EAAE,GAAG,CAAC,KAAK;YACtB,iBAAiB,EAAE,QAAQ;YAC3B,cAAc,EAAE,QAAQ;SACzB;KACF,CAAC;AACJ,CAAC"}

package/dist/worker/continuous-loop.d.ts

@@ -0,0 +1,22 @@
+import { type ConfigDrivenDispatchDeps, type RunMatrixContinuouslyByCatalogIdOptions } from '@exellix/exellix-runtime';
+import type { JobsMetrics } from '../metrics.js';
+import type { MatrixCycleState } from './cycle-state.js';
+export type RunMatrixContinuouslyByCatalogIdWithMetricsOptions = RunMatrixContinuouslyByCatalogIdOptions & {
+    onCycleComplete?: (info: {
+        matrixCatalogId: string;
+        matrixItemId: string;
+        matrixRunId?: string;
+        emptyPass: boolean;
+        cyclesRun: number;
+    }) => void;
+    cycleState?: MatrixCycleState;
+};
+/**
+ * Same behavior as {@link runMatrixContinuouslyByCatalogId} from `@exellix/exellix-runtime`, plus Prometheus
+ * counters for cycles, materialized rows, and idle sleep seconds on empty passes.
+ */
+export declare function runMatrixContinuouslyByCatalogIdWithMetrics(deps: ConfigDrivenDispatchDeps, opts: RunMatrixContinuouslyByCatalogIdWithMetricsOptions, metrics?: JobsMetrics): Promise<{
+    cyclesRun: number;
+    reason: 'aborted' | 'maxCycles' | 'event-source';
+}>;
+//# sourceMappingURL=continuous-loop.d.ts.map

package/dist/worker/continuous-loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"continuous-loop.d.ts","sourceRoot":"","sources":["../../src/worker/continuous-loop.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,wBAAwB,EAC7B,KAAK,uCAAuC,EAC7C,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD,MAAM,MAAM,kDAAkD,GAAG,uCAAuC,GAAG;IACzG,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE;QACvB,eAAe,EAAE,MAAM,CAAC;QACxB,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,SAAS,EAAE,OAAO,CAAC;QACnB,SAAS,EAAE,MAAM,CAAC;KACnB,KAAK,IAAI,CAAC;IACX,UAAU,CAAC,EAAE,gBAAgB,CAAC;CAC/B,CAAC;AAEF;;;GAGG;AACH,wBAAsB,2CAA2C,CAC/D,IAAI,EAAE,wBAAwB,EAC9B,IAAI,EAAE,kDAAkD,EACxD,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,cAAc,CAAA;CAAE,CAAC,CAsElF"}

package/dist/worker/continuous-loop.js

@@ -0,0 +1,73 @@
+import { resolveMatrixExecutionConfig, resolvePollWhenEmptySeconds, runMatrixCycle, shouldLoopDriveMatrix, sleepWithAbort, } from '@exellix/exellix-runtime';
+/**
+ * Same behavior as {@link runMatrixContinuouslyByCatalogId} from `@exellix/exellix-runtime`, plus Prometheus
+ * counters for cycles, materialized rows, and idle sleep seconds on empty passes.
+ */
+export async function runMatrixContinuouslyByCatalogIdWithMetrics(deps, opts, metrics) {
+    const refresh = opts.refreshConfigPerCycle ?? true;
+    let { effective, graphRecords } = await resolveMatrixExecutionConfig(deps.configStore, opts.matrixCatalogId);
+    if (!shouldLoopDriveMatrix(effective.payload)) {
+        return { cyclesRun: 0, reason: 'event-source' };
+    }
+    const maxCycles = opts.maxCycles ?? Number.POSITIVE_INFINITY;
+    let cyclesRun = 0;
+    const matrixCatalogId = opts.matrixCatalogId;
+    while (!opts.signal.aborted) {
+        if (cyclesRun >= maxCycles) {
+            return { cyclesRun, reason: 'maxCycles' };
+        }
+        if (refresh && cyclesRun > 0) {
+            ({ effective, graphRecords } = await resolveMatrixExecutionConfig(deps.configStore, opts.matrixCatalogId));
+            if (!shouldLoopDriveMatrix(effective.payload)) {
+                return { cyclesRun, reason: 'event-source' };
+            }
+        }
+        const cycleOpts = {
+            matrixCatalogId: opts.matrixCatalogId,
+            matrixItemId: opts.matrixItemId,
+            ...(opts.matrixRunId !== undefined ? { matrixRunId: opts.matrixRunId } : {}),
+            payload: effective.payload,
+            graphRecords,
+            ...(opts.inputRows ? { inputRows: opts.inputRows } : {}),
+            ...(opts.snapshot ? { snapshot: opts.snapshot } : {}),
+            ...(opts.jobId !== undefined ? { jobId: opts.jobId } : {}),
+            ...(opts.debugMode !== undefined ? { debugMode: opts.debugMode } : {}),
+            ...(opts.executeOverrides ? { executeOverrides: opts.executeOverrides } : {}),
+        };
+        const cycle = await runMatrixCycle(deps, cycleOpts);
+        cyclesRun += 1;
+        opts.onCycleComplete?.({
+            matrixCatalogId: opts.matrixCatalogId,
+            matrixItemId: opts.matrixItemId,
+            ...(opts.matrixRunId !== undefined ? { matrixRunId: opts.matrixRunId } : {}),
+            emptyPass: cycle.emptyPass,
+            cyclesRun,
+        });
+        opts.cycleState?.recordCycle({
+            matrixCatalogId: opts.matrixCatalogId,
+            matrixItemId: opts.matrixItemId,
+            ...(opts.matrixRunId !== undefined ? { matrixRunId: opts.matrixRunId } : {}),
+            emptyPass: cycle.emptyPass,
+            cyclesRun,
+        });
+        metrics?.matrixWorkerCyclesTotal.inc({
+            matrix_catalog_id: matrixCatalogId,
+            empty: String(cycle.emptyPass),
+        });
+        if (cycle.materialized > 0) {
+            metrics?.matrixRowsMaterializedTotal.inc({ matrix_catalog_id: matrixCatalogId }, cycle.materialized);
+        }
+        if (opts.signal.aborted) {
+            break;
+        }
+        if (cycle.emptyPass) {
+            const sleepSeconds = opts.pollWhenEmptySecondsOverride ?? resolvePollWhenEmptySeconds(effective.payload.dataSource);
+            if (sleepSeconds > 0) {
+                metrics?.matrixWorkerIdleSecondsTotal.inc({ matrix_catalog_id: matrixCatalogId }, sleepSeconds);
+                await sleepWithAbort(sleepSeconds * 1000, opts.signal);
+            }
+        }
+    }
+    return { cyclesRun, reason: 'aborted' };
+}
+//# sourceMappingURL=continuous-loop.js.map

package/dist/worker/continuous-loop.js.map

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

package/dist/worker/cycle-state.d.ts

@@ -0,0 +1,22 @@
+export type CycleLoopSnapshot = {
+    matrixCatalogId: string;
+    matrixItemId: string;
+    matrixRunId?: string;
+    lastCycleAt: string;
+    lastCycleEmpty: boolean;
+    cyclesRun: number;
+};
+export declare class MatrixCycleState {
+    private readonly loops;
+    recordCycle(info: {
+        matrixCatalogId: string;
+        matrixItemId: string;
+        matrixRunId?: string;
+        emptyPass: boolean;
+        cyclesRun: number;
+    }): void;
+    snapshot(filter?: {
+        matrixCatalogId?: string;
+    }): CycleLoopSnapshot[];
+}
+//# sourceMappingURL=cycle-state.d.ts.map

package/dist/worker/cycle-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cycle-state.d.ts","sourceRoot":"","sources":["../../src/worker/cycle-state.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,iBAAiB,GAAG;IAC9B,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,OAAO,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAMF,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAwC;IAE9D,WAAW,CAAC,IAAI,EAAE;QAChB,eAAe,EAAE,MAAM,CAAC;QACxB,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,SAAS,EAAE,OAAO,CAAC;QACnB,SAAS,EAAE,MAAM,CAAC;KACnB,GAAG,IAAI;IAYR,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,iBAAiB,EAAE;CAOrE"}

package/dist/worker/cycle-state.js

@@ -0,0 +1,25 @@
+function loopKey(matrixCatalogId, matrixItemId, matrixRunId) {
+    return `${matrixCatalogId}\0${matrixItemId}\0${matrixRunId ?? ''}`;
+}
+export class MatrixCycleState {
+    loops = new Map();
+    recordCycle(info) {
+        const key = loopKey(info.matrixCatalogId, info.matrixItemId, info.matrixRunId);
+        this.loops.set(key, {
+            matrixCatalogId: info.matrixCatalogId,
+            matrixItemId: info.matrixItemId,
+            ...(info.matrixRunId !== undefined ? { matrixRunId: info.matrixRunId } : {}),
+            lastCycleAt: new Date().toISOString(),
+            lastCycleEmpty: info.emptyPass,
+            cyclesRun: info.cyclesRun,
+        });
+    }
+    snapshot(filter) {
+        const rows = [...this.loops.values()];
+        if (!filter?.matrixCatalogId) {
+            return rows;
+        }
+        return rows.filter((r) => r.matrixCatalogId === filter.matrixCatalogId);
+    }
+}
+//# sourceMappingURL=cycle-state.js.map

package/dist/worker/cycle-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cycle-state.js","sourceRoot":"","sources":["../../src/worker/cycle-state.ts"],"names":[],"mappings":"AASA,SAAS,OAAO,CAAC,eAAuB,EAAE,YAAoB,EAAE,WAAoB;IAClF,OAAO,GAAG,eAAe,KAAK,YAAY,KAAK,WAAW,IAAI,EAAE,EAAE,CAAC;AACrE,CAAC;AAED,MAAM,OAAO,gBAAgB;IACV,KAAK,GAAG,IAAI,GAAG,EAA6B,CAAC;IAE9D,WAAW,CAAC,IAMX;QACC,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,eAAe,EAAE,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;QAC/E,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE;YAClB,eAAe,EAAE,IAAI,CAAC,eAAe;YACrC,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,GAAG,CAAC,IAAI,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC5E,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACrC,cAAc,EAAE,IAAI,CAAC,SAAS;YAC9B,SAAS,EAAE,IAAI,CAAC,SAAS;SAC1B,CAAC,CAAC;IACL,CAAC;IAED,QAAQ,CAAC,MAAqC;QAC5C,MAAM,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;QACtC,IAAI,CAAC,MAAM,EAAE,eAAe,EAAE,CAAC;YAC7B,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,eAAe,KAAK,MAAM,CAAC,eAAe,CAAC,CAAC;IAC1E,CAAC;CACF"}

package/dist/worker/discovery.d.ts

@@ -0,0 +1,32 @@
+import { type ExellixConfigStore, type GraphConfigRecord, type GraphOperationalState, type GraphPublicationStatus } from '@exellix/exellix-runtime';
+export declare function graphIsSchedulableCandidate(g: GraphConfigRecord): boolean;
+export type MatrixAssignment = {
+    matrixCatalogId: string;
+    /** Catalog item identity for run-loop; defaults to `matrixCatalogId` when not supplied elsewhere. */
+    matrixItemId: string;
+    matrixRunId?: string;
+    /** Graph ids from the matrix payload that are schedulable candidates. */
+    graphIds: string[];
+};
+/**
+ * Implements `docs/specs.md` §7: discover matrices whose payload references any Published/Ready|Running graph.
+ */
+export declare function discoverMatrixAssignments(configStore: ExellixConfigStore, opts?: {
+    matrixPageSize?: number;
+    graphListLimit?: number;
+}): Promise<MatrixAssignment[]>;
+export type GraphSummaryRow = {
+    graphId: string;
+    publicationStatus: GraphPublicationStatus;
+    operationalState: GraphOperationalState;
+    version: number;
+    matrixCatalogIds: string[];
+};
+/**
+ * Lists graphs with derived `matrixCatalogIds` (best-effort; walks matrix configs).
+ */
+export declare function listGraphSummaries(configStore: ExellixConfigStore, opts?: {
+    matrixPageSize?: number;
+    graphListLimit?: number;
+}): Promise<GraphSummaryRow[]>;
+//# sourceMappingURL=discovery.d.ts.map

package/dist/worker/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../src/worker/discovery.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAE5B,MAAM,0BAA0B,CAAC;AAElC,wBAAgB,2BAA2B,CAAC,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAOzE;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,eAAe,EAAE,MAAM,CAAC;IACxB,qGAAqG;IACrG,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AAEF;;GAEG;AACH,wBAAsB,yBAAyB,CAC7C,WAAW,EAAE,kBAAkB,EAC/B,IAAI,CAAC,EAAE;IAAE,cAAc,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,GAC1D,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAkD7B;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,iBAAiB,EAAE,sBAAsB,CAAC;IAC1C,gBAAgB,EAAE,qBAAqB,CAAC;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B,CAAC;AAEF;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,kBAAkB,EAC/B,IAAI,CAAC,EAAE;IAAE,cAAc,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,GAC1D,OAAO,CAAC,eAAe,EAAE,CAAC,CAqC5B"}

package/dist/worker/discovery.js

@@ -0,0 +1,104 @@
+import { assertGraphSchedulable, resolveGraphConfigOperationalView, } from '@exellix/exellix-runtime';
+export function graphIsSchedulableCandidate(g) {
+    try {
+        assertGraphSchedulable(g);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Implements `docs/specs.md` §7: discover matrices whose payload references any Published/Ready|Running graph.
+ */
+export async function discoverMatrixAssignments(configStore, opts) {
+    const graphPageSize = opts?.graphListLimit ?? 500;
+    const matrixPageSize = opts?.matrixPageSize ?? 200;
+    const schedulableGraphIds = new Set();
+    let gSkip = 0;
+    for (;;) {
+        const graphs = await configStore.graphs.list({ limit: graphPageSize, skip: gSkip });
+        for (const g of graphs) {
+            if (graphIsSchedulableCandidate(g)) {
+                schedulableGraphIds.add(g.graphId);
+            }
+        }
+        if (graphs.length < graphPageSize) {
+            break;
+        }
+        gSkip += graphs.length;
+    }
+    const byMatrix = new Map();
+    let mSkip = 0;
+    for (;;) {
+        const matrices = await configStore.matrices.list({ limit: matrixPageSize, skip: mSkip });
+        if (matrices.length === 0) {
+            break;
+        }
+        for (const m of matrices) {
+            const graphsInMatrix = m.payload.graphs ?? [];
+            const schedulableInMatrix = graphsInMatrix.filter((id) => schedulableGraphIds.has(id));
+            if (schedulableInMatrix.length > 0) {
+                const matrixCatalogId = m.matrixCatalogId;
+                const existing = byMatrix.get(matrixCatalogId);
+                if (!existing) {
+                    byMatrix.set(matrixCatalogId, {
+                        matrixCatalogId,
+                        matrixItemId: matrixCatalogId,
+                        graphIds: [...schedulableInMatrix],
+                    });
+                }
+                else {
+                    const merged = new Set([...existing.graphIds, ...schedulableInMatrix]);
+                    existing.graphIds = [...merged];
+                }
+            }
+        }
+        if (matrices.length < matrixPageSize) {
+            break;
+        }
+        mSkip += matrices.length;
+    }
+    return [...byMatrix.values()];
+}
+/**
+ * Lists graphs with derived `matrixCatalogIds` (best-effort; walks matrix configs).
+ */
+export async function listGraphSummaries(configStore, opts) {
+    const matrixPageSize = opts?.matrixPageSize ?? 200;
+    const graphToMatrices = new Map();
+    let mSkip = 0;
+    for (;;) {
+        const matrices = await configStore.matrices.list({ limit: matrixPageSize, skip: mSkip });
+        if (matrices.length === 0) {
+            break;
+        }
+        for (const m of matrices) {
+            for (const gid of m.payload.graphs ?? []) {
+                let set = graphToMatrices.get(gid);
+                if (!set) {
+                    set = new Set();
+                    graphToMatrices.set(gid, set);
+                }
+                set.add(m.matrixCatalogId);
+            }
+        }
+        if (matrices.length < matrixPageSize) {
+            break;
+        }
+        mSkip += matrices.length;
+    }
+    const limit = opts?.graphListLimit ?? 2000;
+    const graphs = await configStore.graphs.list({ limit, skip: 0 });
+    return graphs.map((g) => {
+        const eff = resolveGraphConfigOperationalView(g);
+        return {
+            graphId: g.graphId,
+            publicationStatus: eff.publicationStatus,
+            operationalState: eff.operationalState,
+            version: g.version,
+            matrixCatalogIds: [...(graphToMatrices.get(g.graphId) ?? [])].sort(),
+        };
+    });
+}
+//# sourceMappingURL=discovery.js.map

package/dist/worker/discovery.js.map

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

package/dist/worker/matrix-worker.d.ts

@@ -0,0 +1,57 @@
+import { createExecutionMatrixClaimPauseController, type ConfigDrivenDispatchDeps, type ExellixRuntimeConnectivityProbeOptions, type ExecutionMatrixRuntime, type ExellixConfigStore, type MatrixGraphExecutor, type MatrixGraphModelResolver, type MatrixSourceResolver } from '@exellix/exellix-runtime';
+import type { ExellixMatrixPersistenceHandles } from '../collections.js';
+import type { JobsMetrics } from '../metrics.js';
+import { type CycleLoopSnapshot } from './cycle-state.js';
+import { type MatrixAssignment } from './discovery.js';
+export type { MatrixAssignment } from './discovery.js';
+export type CreateMatrixWorkerOptions = {
+    persistence: ExellixMatrixPersistenceHandles;
+    executeGraph: MatrixGraphExecutor;
+    resolveGraphModel?: MatrixGraphModelResolver;
+    sourceResolver?: MatrixSourceResolver;
+    matrixActivix?: ConfigDrivenDispatchDeps['matrixActivix'];
+    matrixLogxer?: ConfigDrivenDispatchDeps['matrixLogxer'];
+    executeOverrides?: ConfigDrivenDispatchDeps['executeOverrides'];
+    runtimeScope?: ConfigDrivenDispatchDeps['runtimeScope'];
+    runtimeObjects?: ConfigDrivenDispatchDeps['runtimeObjects'];
+    maxConcurrentClaims?: number;
+    perGraphConcurrency?: Record<string, number>;
+    /** Maps to {@link ProcessMatrixClaimDeps.graphSchedulabilityRequireConfig}. */
+    graphSchedulabilityRequireConfig?: boolean;
+    /** Operator identity (`MATRIX_WORKER_ID`) surfaced in health and `/workers/status`. */
+    matrixWorkerId?: string;
+    metrics?: JobsMetrics;
+};
+export type MatrixWorkerStatus = {
+    matrixWorkerId?: string;
+    assignedMatrixCatalogIds: string[];
+    /** Spec §10.4 alias — graph ids from assigned matrices. */
+    assignedGraphIds: string[];
+    activeJobsByGraphId: Record<string, number>;
+    /** Spec §10.4 alias for {@link activeJobsByGraphId}. */
+    activeJobs: Record<string, number>;
+    maxConcurrency: number;
+    paused: boolean;
+    loops: CycleLoopSnapshot[];
+};
+export type MatrixWorker = {
+    readonly runtime: ExecutionMatrixRuntime;
+    readonly configStore: ExellixConfigStore;
+    readonly metrics: JobsMetrics;
+    readonly pauseController: ReturnType<typeof createExecutionMatrixClaimPauseController>;
+    readonly connectivityProbe?: ExellixRuntimeConnectivityProbeOptions;
+    getStatus: (filter?: {
+        matrixCatalogId?: string;
+    }) => MatrixWorkerStatus;
+    /**
+     * Starts one continuous loop per matrix assignment. When `assignments` is omitted, runs catalog discovery
+     * (`docs/specs.md` §7).
+     */
+    startSupervised: (signal: AbortSignal, opts?: {
+        assignments?: MatrixAssignment[];
+    }) => Promise<void>;
+    close: () => Promise<void>;
+};
+export declare function createMatrixWorker(options: CreateMatrixWorkerOptions): Promise<MatrixWorker>;
+export { discoverMatrixAssignments, listGraphSummaries } from './discovery.js';
+//# sourceMappingURL=matrix-worker.d.ts.map

package/dist/worker/matrix-worker.d.ts.map

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