@exellix/exellix-matrix-persister 1.0.1

package/.env.example

@@ -0,0 +1,3 @@
+# ============================================
+# nx-mongo Configuration
+# ============================================

package/README.md

@@ -0,0 +1,109 @@
+# @exellix/exellix-matrix-persister
+
+Mongo-backed **factory** for Exellix execution-matrix persistence: operational collections (rows, failures, snapshots) plus matrix and graph config collections. Host apps import **`createExellixMatrixDataTier`** instead of wiring **`mongodb`** or **`@x12i/xronox-store`** themselves.
+
+Domain behavior (claims, materialization, filters) stays in **`@exellix/exellix-runtime`**. This package is the supported **wiring** surface for workers and read tiers.
+
+## Install
+
+```bash
+npm install @exellix/exellix-matrix-persister @exellix/exellix-runtime
+```
+
+`@exellix/exellix-runtime` is a **peer** dependency (install it next to this package).
+
+### Private registry (GitHub Packages)
+
+If `@exellix/*` is published to GitHub npm, set a token and `.npmrc` (do **not** commit tokens):
+
+```ini
+@exellix:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}
+```
+
+Export `NODE_AUTH_TOKEN` (PAT with `read:packages`) before `npm install`.
+
+## Usage
+
+```ts
+import { createExellixMatrixDataTier } from '@exellix/exellix-matrix-persister';
+
+const tier = await createExellixMatrixDataTier({
+  mongoUri: process.env.MONGO_URI,
+  executionDb: 'exellix-runtime',
+  configDb: 'exellix',
+});
+
+await tier.init?.();
+
+// Pass into createMatrixWorker / openMatrixReadTier / createExecutionMatrixRuntime
+const { rows, failures, snapshots, matrices, graphs } = tier;
+
+await tier.close();
+```
+
+### Returned shape
+
+| Field        | Role |
+|-------------|------|
+| `rows`      | Execution matrix rows |
+| `failures`  | Failure records |
+| `snapshots` | Snapshot side-channel |
+| `matrices`  | Matrix configs (`exellix_matrix_configs`) |
+| `graphs`    | Graph configs (`exellix_graph_configs`) |
+| `init?`     | Optional warm-up (no-op after factory; safe to call) |
+| `close`     | Closes stores and any Mongo driver pass-through |
+| `probe?`    | `{ executionStore, configStore, executionMongoUri, configMongoUri }` for dependency health checks |
+
+Collection names and indexes follow **`@exellix/exellix-runtime`** (`src/execution-matrix/collections.ts`).
+
+## Environment
+
+| Variable        | Default           | Used by |
+|----------------|-------------------|---------|
+| `MONGO_URI`    | _(required)_      | Connection string |
+| `execution_db` | `exellix-runtime` | Rows, failures, snapshots |
+| `config_db`    | `exellix`         | Matrix + graph configs |
+
+Options passed to `createExellixMatrixDataTier({ ... })` override env for that call.
+
+## Consumers
+
+**`@exellix/exellix-jobs`** and **`@exellix/exellix-matrix-read`** try this package first for `createExellixMatrixDataTier`, then **`@x12i/xmemory-store`** if the factory is re-exported there later. Installing **`@exellix/exellix-matrix-persister`** is enough for `openExellixMatrixPersistenceFromXmemoryStore` / `openMatrixPersistenceFromXmemoryStore` to succeed without host glue.
+
+## API surface
+
+- **`createExellixMatrixDataTier(options?)`** — main factory
+- **`resolveExellixMatrixDataTierOptions(overrides?, env?)`** — merge options + `process.env` (throws if `mongoUri` missing)
+- **`loadMatrixDataTierFactory()`** — resolves the factory from this package or `@x12i/xmemory-store` (for advanced dynamic wiring)
+
+Types are exported from the package entry (`CreateExellixMatrixDataTierOptions`, `ExellixMatrixDataTier`, etc.).
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+### Live tests (real Mongo)
+
+1. Copy **`.env.example`** → **`.env`** and set `MONGO_URI` (and optional `execution_db` / `config_db`).
+2. Run:
+
+```bash
+npm run test:live
+```
+
+The default **`npm test`** suite skips live tests when `MONGO_URI` is unset. Vitest is configured with **`MODE=debug`** so importing `@exellix/exellix-runtime` in tests does not fail on `@x12i/funcx` mode checks.
+
+More detail: [docs/integration.md](./docs/integration.md). For a minimal env template, see [`.env.example`](./.env.example).
+
+## Specification
+
+Normative persistence contract: **`createExellixMatrixDataTier`** in **`@exellix/exellix-runtime`** — see [client-integration.md](https://github.com/exellix/exellix-runtime/blob/main/docs/client-integration.md).
+
+## License
+
+UNLICENSED (internal Exellix package unless published otherwise).

package/dist/collection-names.d.ts

@@ -0,0 +1,7 @@
+/** Mongo collection names — mirror `@exellix/exellix-runtime` execution-matrix constants. */
+export declare const EXECUTION_MATRIX_ROWS_COLLECTION: "exellix_execution_matrix_rows";
+export declare const EXECUTION_MATRIX_FAILURES_COLLECTION: "exellix_execution_matrix_failures";
+export declare const EXECUTION_MATRIX_SNAPSHOTS_COLLECTION: "exellix_execution_matrix_snapshots";
+export declare const EXELLIX_MATRIX_CONFIGS_COLLECTION: "exellix_matrix_configs";
+export declare const EXELLIX_GRAPH_CONFIGS_COLLECTION: "exellix_graph_configs";
+//# sourceMappingURL=collection-names.d.ts.map

package/dist/collection-names.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection-names.d.ts","sourceRoot":"","sources":["../src/collection-names.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,eAAO,MAAM,gCAAgC,EAAG,+BAAwC,CAAC;AACzF,eAAO,MAAM,oCAAoC,EAAG,mCAA4C,CAAC;AACjG,eAAO,MAAM,qCAAqC,EAAG,oCAA6C,CAAC;AACnG,eAAO,MAAM,iCAAiC,EAAG,wBAAiC,CAAC;AACnF,eAAO,MAAM,gCAAgC,EAAG,uBAAgC,CAAC"}

package/dist/collection-names.js

@@ -0,0 +1,7 @@
+/** Mongo collection names — mirror `@exellix/exellix-runtime` execution-matrix constants. */
+export const EXECUTION_MATRIX_ROWS_COLLECTION = 'exellix_execution_matrix_rows';
+export const EXECUTION_MATRIX_FAILURES_COLLECTION = 'exellix_execution_matrix_failures';
+export const EXECUTION_MATRIX_SNAPSHOTS_COLLECTION = 'exellix_execution_matrix_snapshots';
+export const EXELLIX_MATRIX_CONFIGS_COLLECTION = 'exellix_matrix_configs';
+export const EXELLIX_GRAPH_CONFIGS_COLLECTION = 'exellix_graph_configs';
+//# sourceMappingURL=collection-names.js.map

package/dist/collection-names.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection-names.js","sourceRoot":"","sources":["../src/collection-names.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,MAAM,CAAC,MAAM,gCAAgC,GAAG,+BAAwC,CAAC;AACzF,MAAM,CAAC,MAAM,oCAAoC,GAAG,mCAA4C,CAAC;AACjG,MAAM,CAAC,MAAM,qCAAqC,GAAG,oCAA6C,CAAC;AACnG,MAAM,CAAC,MAAM,iCAAiC,GAAG,wBAAiC,CAAC;AACnF,MAAM,CAAC,MAAM,gCAAgC,GAAG,uBAAgC,CAAC"}

package/dist/create-exellix-matrix-data-tier.d.ts

@@ -0,0 +1,10 @@
+import type { CreateExellixMatrixDataTierOptions, ExellixMatrixDataTier } from './types.js';
+/**
+ * Opens Mongo-backed persistence for Exellix execution-matrix operational data and config collections.
+ * Host applications import this factory instead of `mongodb` or `@x12i/xronox-store`.
+ *
+ * Databases (defaults): `exellix-runtime` (rows, failures, snapshots), `exellix` (matrix_configs, graph_configs).
+ * Indexes follow `@exellix/exellix-runtime` `src/execution-matrix/collections.ts`.
+ */
+export declare function createExellixMatrixDataTier(options?: CreateExellixMatrixDataTierOptions): Promise<ExellixMatrixDataTier>;
+//# sourceMappingURL=create-exellix-matrix-data-tier.d.ts.map

package/dist/create-exellix-matrix-data-tier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-exellix-matrix-data-tier.d.ts","sourceRoot":"","sources":["../src/create-exellix-matrix-data-tier.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,kCAAkC,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAE5F;;;;;;GAMG;AACH,wBAAsB,2BAA2B,CAC/C,OAAO,GAAE,kCAAuC,GAC/C,OAAO,CAAC,qBAAqB,CAAC,CA0DhC"}

package/dist/create-exellix-matrix-data-tier.js

@@ -0,0 +1,64 @@
+import { createExellixConfigStoreFromXronox, createExecutionMatrixRuntimeFromXronox, } from '@exellix/exellix-runtime/internal/xronox-matrix';
+import { EXECUTION_MATRIX_FAILURES_COLLECTION, EXECUTION_MATRIX_ROWS_COLLECTION, EXECUTION_MATRIX_SNAPSHOTS_COLLECTION, EXELLIX_GRAPH_CONFIGS_COLLECTION, EXELLIX_MATRIX_CONFIGS_COLLECTION, } from './collection-names.js';
+import { resolveExellixMatrixDataTierOptions } from './resolve-options.js';
+/**
+ * Opens Mongo-backed persistence for Exellix execution-matrix operational data and config collections.
+ * Host applications import this factory instead of `mongodb` or `@x12i/xronox-store`.
+ *
+ * Databases (defaults): `exellix-runtime` (rows, failures, snapshots), `exellix` (matrix_configs, graph_configs).
+ * Indexes follow `@exellix/exellix-runtime` `src/execution-matrix/collections.ts`.
+ */
+export async function createExellixMatrixDataTier(options = {}) {
+    const resolved = resolveExellixMatrixDataTierOptions(options);
+    const passThrough = resolved.mongoDriverPassThrough !== false;
+    const exec = await createExecutionMatrixRuntimeFromXronox({
+        mongoUri: resolved.mongoUri,
+        mongoDb: resolved.executionDb,
+        mongoRole: resolved.executionMongoRole,
+        mongoDriverPassThrough: passThrough,
+        serializeClaims: resolved.serializeClaims ?? true,
+    });
+    const cfg = await createExellixConfigStoreFromXronox({
+        mongoUri: resolved.mongoUri,
+        mongoDb: resolved.configDb,
+        mongoRole: resolved.configMongoRole,
+        mongoDriverPassThrough: passThrough,
+    });
+    const rows = exec.store.collection(EXECUTION_MATRIX_ROWS_COLLECTION);
+    const failures = exec.store.collection(EXECUTION_MATRIX_FAILURES_COLLECTION);
+    const snapshots = exec.store.collection(EXECUTION_MATRIX_SNAPSHOTS_COLLECTION);
+    const matrices = cfg.store.collection(EXELLIX_MATRIX_CONFIGS_COLLECTION);
+    const graphs = cfg.store.collection(EXELLIX_GRAPH_CONFIGS_COLLECTION);
+    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);
+    };
+    const probe = {
+        executionStore: exec.store,
+        configStore: cfg.store,
+        executionMongoUri: resolved.mongoUri,
+        configMongoUri: resolved.mongoUri,
+    };
+    return {
+        rows,
+        failures,
+        snapshots,
+        matrices,
+        graphs,
+        init: async () => undefined,
+        close,
+        executionStore: exec.store,
+        configStore: cfg.store,
+        executionMongoUri: resolved.mongoUri,
+        configMongoUri: resolved.mongoUri,
+        probe,
+    };
+}
+//# sourceMappingURL=create-exellix-matrix-data-tier.js.map

package/dist/create-exellix-matrix-data-tier.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { createExellixMatrixDataTier } from './create-exellix-matrix-data-tier.js';
+export { loadMatrixDataTierFactory, type MatrixDataTierFactory } from './load-matrix-data-tier-factory.js';
+export { resolveExellixMatrixDataTierOptions } from './resolve-options.js';
+export type { CreateExellixMatrixDataTierOptions, ExellixMatrixDataTier, ExellixMatrixDataTierProbe, ExellixMatrixPersistenceCollection, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,2BAA2B,EAAE,MAAM,sCAAsC,CAAC;AACnF,OAAO,EAAE,yBAAyB,EAAE,KAAK,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAC3G,OAAO,EAAE,mCAAmC,EAAE,MAAM,sBAAsB,CAAC;AAC3E,YAAY,EACV,kCAAkC,EAClC,qBAAqB,EACrB,0BAA0B,EAC1B,kCAAkC,GACnC,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { createExellixMatrixDataTier } from './create-exellix-matrix-data-tier.js';
+export { loadMatrixDataTierFactory } from './load-matrix-data-tier-factory.js';
+export { resolveExellixMatrixDataTierOptions } from './resolve-options.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,2BAA2B,EAAE,MAAM,sCAAsC,CAAC;AACnF,OAAO,EAAE,yBAAyB,EAA8B,MAAM,oCAAoC,CAAC;AAC3G,OAAO,EAAE,mCAAmC,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/load-matrix-data-tier-factory.d.ts

@@ -0,0 +1,6 @@
+export type MatrixDataTierFactory = (options: Record<string, unknown>) => Promise<unknown>;
+/**
+ * Resolves `createExellixMatrixDataTier` from this package or, when upstream re-exports it, `@x12i/xmemory-store`.
+ */
+export declare function loadMatrixDataTierFactory(): Promise<MatrixDataTierFactory>;
+//# sourceMappingURL=load-matrix-data-tier-factory.d.ts.map

package/dist/load-matrix-data-tier-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-matrix-data-tier-factory.d.ts","sourceRoot":"","sources":["../src/load-matrix-data-tier-factory.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,qBAAqB,GAAG,CAClC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC7B,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtB;;GAEG;AACH,wBAAsB,yBAAyB,IAAI,OAAO,CAAC,qBAAqB,CAAC,CAoBhF"}

package/dist/load-matrix-data-tier-factory.js

@@ -0,0 +1,24 @@
+const FACTORY = 'createExellixMatrixDataTier';
+const FACTORY_PACKAGES = ['@exellix/exellix-matrix-persister', '@x12i/xmemory-store'];
+/**
+ * Resolves `createExellixMatrixDataTier` from this package or, when upstream re-exports it, `@x12i/xmemory-store`.
+ */
+export async function loadMatrixDataTierFactory() {
+    const errors = [];
+    for (const pkg of FACTORY_PACKAGES) {
+        try {
+            const mod = (await import(pkg));
+            const factory = mod[FACTORY];
+            if (typeof factory === 'function') {
+                return factory;
+            }
+            errors.push(`${pkg}: "${FACTORY}" is not exported`);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            errors.push(`${pkg}: ${message}`);
+        }
+    }
+    throw new Error(`createExellixMatrixDataTier is not available. Tried:\n${errors.map((e) => `  - ${e}`).join('\n')}`);
+}
+//# sourceMappingURL=load-matrix-data-tier-factory.js.map

package/dist/load-matrix-data-tier-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-matrix-data-tier-factory.js","sourceRoot":"","sources":["../src/load-matrix-data-tier-factory.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,GAAG,6BAA6B,CAAC;AAE9C,MAAM,gBAAgB,GAAG,CAAC,mCAAmC,EAAE,qBAAqB,CAAU,CAAC;AAM/F;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB;IAC7C,MAAM,MAAM,GAAa,EAAE,CAAC;IAE5B,KAAK,MAAM,GAAG,IAAI,gBAAgB,EAAE,CAAC;QACnC,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,CAAC,MAAM,MAAM,CAAC,GAAG,CAAC,CAA4B,CAAC;YAC3D,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC;YAC7B,IAAI,OAAO,OAAO,KAAK,UAAU,EAAE,CAAC;gBAClC,OAAO,OAAgC,CAAC;YAC1C,CAAC;YACD,MAAM,CAAC,IAAI,CAAC,GAAG,GAAG,MAAM,OAAO,mBAAmB,CAAC,CAAC;QACtD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACjE,MAAM,CAAC,IAAI,CAAC,GAAG,GAAG,KAAK,OAAO,EAAE,CAAC,CAAC;QACpC,CAAC;IACH,CAAC;IAED,MAAM,IAAI,KAAK,CACb,yDAAyD,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACpG,CAAC;AACJ,CAAC"}

package/dist/resolve-options.d.ts

@@ -0,0 +1,11 @@
+import type { CreateExellixMatrixDataTierOptions } from './types.js';
+export type ResolvedExellixMatrixDataTierOptions = CreateExellixMatrixDataTierOptions & {
+    mongoUri: string;
+    executionDb: string;
+    configDb: string;
+};
+/**
+ * Merges caller options with `MONGO_URI`, `execution_db`, and `config_db` (ERC / jobs convention).
+ */
+export declare function resolveExellixMatrixDataTierOptions(overrides?: CreateExellixMatrixDataTierOptions, env?: NodeJS.ProcessEnv): ResolvedExellixMatrixDataTierOptions;
+//# sourceMappingURL=resolve-options.d.ts.map

package/dist/resolve-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-options.d.ts","sourceRoot":"","sources":["../src/resolve-options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kCAAkC,EAAE,MAAM,YAAY,CAAC;AAKrE,MAAM,MAAM,oCAAoC,GAAG,kCAAkC,GAAG;IACtF,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;GAEG;AACH,wBAAgB,mCAAmC,CACjD,SAAS,GAAE,kCAAuC,EAClD,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,oCAAoC,CAatC"}

package/dist/resolve-options.js

@@ -0,0 +1,18 @@
+const DEFAULT_EXECUTION_DB = 'exellix-runtime';
+const DEFAULT_CONFIG_DB = 'exellix';
+/**
+ * Merges caller options with `MONGO_URI`, `execution_db`, and `config_db` (ERC / jobs convention).
+ */
+export function resolveExellixMatrixDataTierOptions(overrides = {}, env = process.env) {
+    const mongoUri = (overrides.mongoUri ?? env.MONGO_URI?.trim() ?? '').trim();
+    if (!mongoUri) {
+        throw new Error('createExellixMatrixDataTier: mongoUri missing — set MONGO_URI or pass options.mongoUri');
+    }
+    return {
+        ...overrides,
+        mongoUri,
+        executionDb: overrides.executionDb ?? (env.execution_db?.trim() || DEFAULT_EXECUTION_DB),
+        configDb: overrides.configDb ?? (env.config_db?.trim() || DEFAULT_CONFIG_DB),
+    };
+}
+//# sourceMappingURL=resolve-options.js.map

package/dist/resolve-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-options.js","sourceRoot":"","sources":["../src/resolve-options.ts"],"names":[],"mappings":"AAEA,MAAM,oBAAoB,GAAG,iBAAiB,CAAC;AAC/C,MAAM,iBAAiB,GAAG,SAAS,CAAC;AAQpC;;GAEG;AACH,MAAM,UAAU,mCAAmC,CACjD,YAAgD,EAAE,EAClD,MAAyB,OAAO,CAAC,GAAG;IAEpC,MAAM,QAAQ,GAAG,CAAC,SAAS,CAAC,QAAQ,IAAI,GAAG,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC5E,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CACb,wFAAwF,CACzF,CAAC;IACJ,CAAC;IACD,OAAO;QACL,GAAG,SAAS;QACZ,QAAQ;QACR,WAAW,EAAE,SAAS,CAAC,WAAW,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,IAAI,EAAE,IAAI,oBAAoB,CAAC;QACxF,QAAQ,EAAE,SAAS,CAAC,QAAQ,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,iBAAiB,CAAC;KAC7E,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,45 @@
+import type { createExecutionMatrixRuntime } from '@exellix/exellix-runtime';
+import type { createExecutionMatrixRuntimeFromXronox, createExellixConfigStoreFromXronox } from '@exellix/exellix-runtime/internal/xronox-matrix';
+/** xronox-shaped collection handle expected by `@exellix/exellix-runtime` factories. */
+export type ExellixMatrixPersistenceCollection = Parameters<typeof createExecutionMatrixRuntime>[0];
+type ExecutionMatrixXronoxBundle = Awaited<ReturnType<typeof createExecutionMatrixRuntimeFromXronox>>;
+type ConfigXronoxBundle = Awaited<ReturnType<typeof createExellixConfigStoreFromXronox>>;
+export type CreateExellixMatrixDataTierOptions = {
+    mongoUri?: string;
+    executionDb?: string;
+    configDb?: string;
+    executionMongoRole?: string;
+    configMongoRole?: string;
+    /**
+     * When `false`, skips native `mongodb` pass-through hooks on the underlying xronox store
+     * (legacy behavior). Default `true`.
+     */
+    mongoDriverPassThrough?: boolean;
+    /** Passed through to {@link createExecutionMatrixRuntime} (default `true` for workers). */
+    serializeClaims?: boolean;
+    [key: string]: unknown;
+};
+export type ExellixMatrixDataTierProbe = {
+    executionStore: ExecutionMatrixXronoxBundle['store'];
+    configStore: ConfigXronoxBundle['store'];
+    executionMongoUri: string;
+    configMongoUri: string;
+};
+export type ExellixMatrixDataTier = {
+    rows: ExellixMatrixPersistenceCollection;
+    failures: ExellixMatrixPersistenceCollection;
+    snapshots: ExellixMatrixPersistenceCollection;
+    matrices: ExellixMatrixPersistenceCollection;
+    graphs: ExellixMatrixPersistenceCollection;
+    /** Optional warm-up (stores are initialized during factory creation; this is a no-op by default). */
+    init?: () => Promise<void>;
+    close: () => Promise<void>;
+    /** Optional handles for dependency health probes (`/health?probe=dependencies`). */
+    executionStore?: ExecutionMatrixXronoxBundle['store'];
+    configStore?: ConfigXronoxBundle['store'];
+    executionMongoUri?: string;
+    configMongoUri?: string;
+    probe?: ExellixMatrixDataTierProbe;
+};
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,0BAA0B,CAAC;AAC7E,OAAO,KAAK,EACV,sCAAsC,EACtC,kCAAkC,EACnC,MAAM,iDAAiD,CAAC;AAEzD,wFAAwF;AACxF,MAAM,MAAM,kCAAkC,GAAG,UAAU,CAAC,OAAO,4BAA4B,CAAC,CAAC,CAAC,CAAC,CAAC;AAEpG,KAAK,2BAA2B,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,sCAAsC,CAAC,CAAC,CAAC;AACtG,KAAK,kBAAkB,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,kCAAkC,CAAC,CAAC,CAAC;AAEzF,MAAM,MAAM,kCAAkC,GAAG;IAC/C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,2FAA2F;IAC3F,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG;IACvC,cAAc,EAAE,2BAA2B,CAAC,OAAO,CAAC,CAAC;IACrD,WAAW,EAAE,kBAAkB,CAAC,OAAO,CAAC,CAAC;IACzC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,IAAI,EAAE,kCAAkC,CAAC;IACzC,QAAQ,EAAE,kCAAkC,CAAC;IAC7C,SAAS,EAAE,kCAAkC,CAAC;IAC9C,QAAQ,EAAE,kCAAkC,CAAC;IAC7C,MAAM,EAAE,kCAAkC,CAAC;IAC3C,qGAAqG;IACrG,IAAI,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,oFAAoF;IACpF,cAAc,CAAC,EAAE,2BAA2B,CAAC,OAAO,CAAC,CAAC;IACtD,WAAW,CAAC,EAAE,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC1C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,KAAK,CAAC,EAAE,0BAA0B,CAAC;CACpC,CAAC"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/docs/integration.md

@@ -0,0 +1,47 @@
+# Integration
+
+## Install
+
+```bash
+npm install @exellix/exellix-matrix-persister @exellix/exellix-runtime
+```
+
+## Factory
+
+```ts
+import { createExellixMatrixDataTier } from '@exellix/exellix-matrix-persister';
+
+const tier = await createExellixMatrixDataTier({
+  mongoUri: process.env.MONGO_URI,
+  executionDb: 'exellix-runtime',
+  configDb: 'exellix',
+});
+
+await tier.init?.();
+// tier.rows | failures | snapshots | matrices | graphs → createMatrixWorker / openMatrixReadTier
+await tier.close();
+```
+
+## Environment
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `MONGO_URI` | _(required)_ | Mongo connection string |
+| `execution_db` | `exellix-runtime` | Rows, failures, snapshots |
+| `config_db` | `exellix` | Matrix and graph config |
+
+## `@exellix/exellix-jobs` / `@exellix/exellix-matrix-read`
+
+Add a peer or dependency on `@exellix/exellix-matrix-persister`. Consumer packages resolve `createExellixMatrixDataTier` from this package first, then from `@x12i/xmemory-store` when re-exported upstream.
+
+## Live test
+
+```bash
+MONGO_URI="mongodb://localhost:27017" npm run test:live
+```
+
+Skips automatically when `MONGO_URI` is unset.
+
+## Normative FR
+
+See `@exellix/exellix-runtime` [exellix-matrix-mongo-persistence-fr.md](https://github.com/exellix/exellix-runtime/blob/main/docs/platform-requests/requests/exellix-matrix-mongo-persistence-fr.md).

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@exellix/exellix-matrix-persister",
+  "version": "1.0.1",
+  "description": "Mongo persistence factory for Exellix execution-matrix rows, failures, snapshots, and matrix/graph config (hides mongodb/xronox from hosts).",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md",
+    ".env.example"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "node -e \"import('node:fs').then(fs=>fs.promises.rm('dist',{recursive:true,force:true}))\"",
+    "prepack": "npm run build",
+    "test": "vitest run",
+    "test:live": "vitest run test/create-exellix-matrix-data-tier.live.spec.ts",
+    "test:watch": "vitest"
+  },
+  "peerDependencies": {
+    "@exellix/exellix-runtime": "^5.1.8"
+  },
+  "devDependencies": {
+    "@exellix/exellix-runtime": "^5.1.8",
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2",
+    "vitest": "^3.0.0"
+  },
+  "keywords": [
+    "exellix",
+    "execution-matrix",
+    "mongodb",
+    "persistence"
+  ],
+  "license": "exellix-license"
+}