@exellix/exellix-matrix-read

Read-only execution-matrix data tier — programmatic and HTTP access to entity+graph job history, status counts, and execution output. Independent of @exellix/exellix-jobs (the worker).

Use this when Studio, BFF, or analytics need answers like:

• For entity type X and graph Y, how many matrix rows are processed / failed / waiting?
• What jobId, timestamps, and inference ran for each graph slot?
• Memorix entity statistics joined with matrix rows for one namespace.

Boundaries

| Package | Role | |---------|------| | @exellix/exellix-matrix-read | Read tier + optional read HTTP | | @exellix/exellix-jobs | Claim, execute, operator control (pause, PATCH) | | @exellix/exellix-runtime | Row shapes, orchestration, low-level read helpers | | @x12i/xmemory-store | Matrix + Memorix persistence factories |

No mongodb / @x12i/xronox-store in this package’s dependencies.

Programmatic API

import { openMatrixReadTier } from '@exellix/exellix-matrix-read';

const tier = await openMatrixReadTier({
  mongoUri: process.env.MONGO_URI,
});

// Counts by slot status for one graph (optional inputGroupByPath for per-entity buckets)
const dashboard = await tier.graphDashboard({
  matrixCatalogId: 'my-matrix',
  graphId: 'my-graph',
  inputGroupByPath: 'entityKind',
});

// Per-row graph slots: status, jobId, inference
const overview = await tier.multiGraphOverview({ matrixCatalogId: 'my-matrix' });

// waiting / in-progress / processed / failed / skipped
const join = await tier.sourceJoinView({
  matrixCatalogId: 'my-matrix',
  graphId: 'my-graph',
});

await tier.close();

Entity facet (Memorix + matrix)

Pass memorixTier from @x12i/xmemory-store (createXmemoryDataTier) when opening the tier, or set MATRIX_READ_MEMORIX_ENABLED=true for read:serve.

const tier = await openMatrixReadTier({
  mongoUri: process.env.MONGO_URI,
  memorixTier: createXmemoryDataTier(),
});

const facet = await tier.entityFacet({
  entityType: 'widget',
  namespace: 'tenant-a',
  matrixCatalogId: 'my-matrix',
  graphId: 'my-graph',
});

Read HTTP server

MONGO_URI=... npm run read:serve

Default port 8090, prefix /v1.

| Method | Path | Purpose | |--------|------|---------| | GET | /health | Liveness | | GET | /matrices/:catalogId/graphs/:graphId/dashboard | Status counts (+ optional inputGroupByPath) | | GET | /matrices/:catalogId/graphs/:graphId/navigator | Paginated rows + histogram | | GET | /matrices/:catalogId/graphs/:graphId/join-view | Pipeline buckets | | GET | /matrices/:catalogId/overview | Multi-graph slot view per row | | GET | /entities/:entityType/facet?namespace= | Memorix + matrix facet |

Relation to the worker

Both packages open the same matrix persistence (operational + config DBs). The worker writes rows while claiming; this package reads them. Deploy separately: worker replicas for execution, read tier for dashboards (can scale read replicas independently).