@exellix/exellix-runtime 3.5.1

package/dist/execution-matrix/snapshot-runner.js

@@ -0,0 +1,111 @@
+/**
+ * Snapshot transform runner: executes the inline JS source declared on a `query-snapshot`
+ * data source under `node:vm` with a wall-clock timeout.
+ *
+ * **Sandbox is best-effort, NOT a security boundary.** `node:vm` shares the same V8 process and
+ * does not isolate prototype tampering or long synchronous loops perfectly. Hosts that expose this
+ * to untrusted authors must add their own process-level isolation. We intentionally do not pass
+ * `require`, `process`, network globals, or filesystem APIs into the sandbox.
+ */
+import { createHash, randomUUID } from 'node:crypto';
+import { Script, createContext } from 'node:vm';
+import { SNAPSHOT_TRANSFORM_TIMEOUT_HARD_CAP_MS, } from './contracts.js';
+const DEFAULT_TIMEOUT_MS = 1_000;
+export class SnapshotTransformError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'SnapshotTransformError';
+    }
+}
+/**
+ * Compile and execute `transform.source` in `node:vm`.
+ *
+ * Source contract: the script is wrapped in `(function(records, params){ ... })(records, params)` so
+ * authors can write either a `return ...` body or a top-level expression. The returned value is
+ * the snapshot payload.
+ */
+export function runSnapshotTransform(transform, inputs) {
+    if (!transform || transform.language !== 'js') {
+        throw new SnapshotTransformError('runSnapshotTransform: only language="js" is supported');
+    }
+    if (!transform.source || typeof transform.source !== 'string') {
+        throw new SnapshotTransformError('runSnapshotTransform: source is required');
+    }
+    const timeoutMs = Math.min(transform.timeoutMs ?? DEFAULT_TIMEOUT_MS, SNAPSHOT_TRANSFORM_TIMEOUT_HARD_CAP_MS);
+    const wrappedSource = `(function(records, params, snapshot){\n${transform.source}\n})(records, params, snapshot)`;
+    let script;
+    try {
+        script = new Script(wrappedSource, { filename: `snapshot-transform.${transform.version}.js` });
+    }
+    catch (err) {
+        throw new SnapshotTransformError('runSnapshotTransform: failed to compile transform source', err);
+    }
+    const sandboxState = { result: undefined };
+    const sandbox = createContext({
+        records: deepFreezeShallow(inputs.records),
+        params: inputs.params ? deepFreezeShallow(inputs.params) : {},
+        snapshot: {
+            set(value) {
+                sandboxState.result = value;
+            },
+        },
+        console: {
+            log: () => undefined,
+            info: () => undefined,
+            warn: () => undefined,
+            error: () => undefined,
+        },
+    });
+    let returned;
+    try {
+        returned = script.runInContext(sandbox, { timeout: timeoutMs, breakOnSigint: true });
+    }
+    catch (err) {
+        throw new SnapshotTransformError(`runSnapshotTransform: execution failed (timeoutMs=${timeoutMs}): ${err?.message ?? String(err)}`, err);
+    }
+    const payload = returned !== undefined ? returned : sandboxState.result;
+    return { payload, transformVersion: transform.version };
+}
+function deepFreezeShallow(v) {
+    if (v && typeof v === 'object') {
+        try {
+            Object.freeze(v);
+        }
+        catch {
+            // ignore
+        }
+    }
+    return v;
+}
+/**
+ * Stable hash over a (selection, sourceIds) pair, used to dedupe / correlate snapshots
+ * built from the same source query. SHA-256 hex truncated to 32 chars (sufficient for collision
+ * resistance within a single matrix's history).
+ */
+export function buildSourceQueryHash(selection, sourceIds) {
+    const canonical = JSON.stringify({
+        selection: selection ?? null,
+        sourceIds: sourceIds ? [...sourceIds].sort() : null,
+    });
+    return createHash('sha256').update(canonical).digest('hex').slice(0, 32);
+}
+/**
+ * Convenience: build a fully-formed {@link ExecutionMatrixSnapshotRecord} from transform output.
+ * Caller still needs to persist via `ExecutionMatrixRuntime.insertSnapshot`.
+ */
+export function buildSnapshotRecord(input) {
+    return {
+        snapshotId: `snap_${input.matrixCatalogId}_${randomUUID()}`,
+        matrixCatalogId: input.matrixCatalogId,
+        ...(input.matrixRunId ? { matrixRunId: input.matrixRunId } : {}),
+        ...(input.entityType !== undefined && input.entityType !== '' ? { entityType: input.entityType } : {}),
+        sourceQueryHash: buildSourceQueryHash(input.selection, input.sourceIds),
+        ...(input.sourceIds && input.sourceIds.length > 0 ? { sourceIds: [...input.sourceIds] } : {}),
+        transformVersion: input.transformResult.transformVersion,
+        payload: input.transformResult.payload,
+        createdAt: new Date().toISOString(),
+    };
+}
+//# sourceMappingURL=snapshot-runner.js.map

package/dist/execution-matrix/snapshot-runner.js.map

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

package/dist/execution-matrix/source-resolver-factories.d.ts

@@ -0,0 +1,31 @@
+import type { XronoxCollection } from '@x12i/xronox-store';
+import type { DataSource, EffectiveMatrixConfig } from './contracts.js';
+import type { MatrixSourceResolver } from './source-resolver.js';
+/** Default cap for {@link listSourceIds} when using factory-built resolvers (matches typical run-loop batching). */
+export declare const DEFAULT_MATRIX_SOURCE_LIST_CAP = 10000;
+export type ResolveMatrixRecordCollection = (collectionRef: string) => XronoxCollection<Record<string, unknown>>;
+export type MatrixSourceResolverFromRecordLikeOptions = {
+    resolveCollection: ResolveMatrixRecordCollection;
+    /** Document field used as stable source id (default `_id`). */
+    sourceIdField?: string;
+    /** Max documents scanned per {@link MatrixSourceResolver.listSourceIds} call. */
+    listCap?: number;
+};
+/**
+ * Builds a {@link MatrixSourceResolver} for **`record`** or **`query-snapshot`** data sources — the same
+ * shapes the run loop uses when listing upstream ids before fetch/transform.
+ *
+ * **Not supported here:** `event`, `storage` (hosts must supply a custom resolver). **`collectionRef`**
+ * is resolved through {@link ResolveMatrixRecordCollection} — wire it to your xronox store / Mongo mirror.
+ */
+export declare function createMatrixSourceResolverFromRecordLikeDataSource(dataSource: Extract<DataSource, {
+    kind: 'record' | 'query-snapshot';
+}>, options: MatrixSourceResolverFromRecordLikeOptions): MatrixSourceResolver;
+/**
+ * Same as {@link createMatrixSourceResolverFromRecordLikeDataSource} but reads `payload.dataSource`
+ * from an {@link EffectiveMatrixConfig}.
+ *
+ * @throws When `dataSource` is missing or kind is not `record` / `query-snapshot`.
+ */
+export declare function createMatrixSourceResolverFromEffectiveConfig(effective: EffectiveMatrixConfig, options: MatrixSourceResolverFromRecordLikeOptions): MatrixSourceResolver;
+//# sourceMappingURL=source-resolver-factories.d.ts.map

package/dist/execution-matrix/source-resolver-factories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-resolver-factories.d.ts","sourceRoot":"","sources":["../../src/execution-matrix/source-resolver-factories.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACxE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAEjE,oHAAoH;AACpH,eAAO,MAAM,8BAA8B,QAAS,CAAC;AAErD,MAAM,MAAM,6BAA6B,GAAG,CAC1C,aAAa,EAAE,MAAM,KAClB,gBAAgB,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAE/C,MAAM,MAAM,yCAAyC,GAAG;IACtD,iBAAiB,EAAE,6BAA6B,CAAC;IACjD,+DAA+D;IAC/D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAQF;;;;;;GAMG;AACH,wBAAgB,kDAAkD,CAChE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE;IAAE,IAAI,EAAE,QAAQ,GAAG,gBAAgB,CAAA;CAAE,CAAC,EACtE,OAAO,EAAE,yCAAyC,GACjD,oBAAoB,CAoCtB;AAED;;;;;GAKG;AACH,wBAAgB,6CAA6C,CAC3D,SAAS,EAAE,qBAAqB,EAChC,OAAO,EAAE,yCAAyC,GACjD,oBAAoB,CAWtB"}

package/dist/execution-matrix/source-resolver-factories.js

@@ -0,0 +1,71 @@
+/** Default cap for {@link listSourceIds} when using factory-built resolvers (matches typical run-loop batching). */
+export const DEFAULT_MATRIX_SOURCE_LIST_CAP = 10_000;
+function normalizeIdField(field, doc) {
+    const raw = doc[field];
+    if (raw === undefined || raw === null)
+        return '';
+    return String(raw);
+}
+/**
+ * Builds a {@link MatrixSourceResolver} for **`record`** or **`query-snapshot`** data sources — the same
+ * shapes the run loop uses when listing upstream ids before fetch/transform.
+ *
+ * **Not supported here:** `event`, `storage` (hosts must supply a custom resolver). **`collectionRef`**
+ * is resolved through {@link ResolveMatrixRecordCollection} — wire it to your xronox store / Mongo mirror.
+ */
+export function createMatrixSourceResolverFromRecordLikeDataSource(dataSource, options) {
+    const field = options.sourceIdField ?? '_id';
+    const cap = options.listCap ?? DEFAULT_MATRIX_SOURCE_LIST_CAP;
+    const selection = dataSource.selection;
+    return {
+        async listSourceIds(sel, _runtimeScope) {
+            const coll = options.resolveCollection(dataSource.collectionRef);
+            const filter = (sel ?? selection ?? {});
+            const docs = await coll.readMany(filter, { limit: cap, mergeCache: true });
+            const ids = [];
+            for (const d of docs) {
+                const id = normalizeIdField(field, d);
+                if (id.length > 0)
+                    ids.push(id);
+            }
+            return ids;
+        },
+        async fetchRecordsByIds(ids, _runtimeScope) {
+            if (ids.length === 0)
+                return [];
+            const coll = options.resolveCollection(dataSource.collectionRef);
+            const filter = { [field]: { $in: ids } };
+            const docs = await coll.readMany(filter, { limit: ids.length, mergeCache: true });
+            const byId = new Map();
+            for (const d of docs) {
+                const id = normalizeIdField(field, d);
+                if (id.length > 0)
+                    byId.set(id, d);
+            }
+            const out = [];
+            for (const id of ids) {
+                const row = byId.get(id);
+                if (row)
+                    out.push(row);
+            }
+            return out;
+        },
+    };
+}
+/**
+ * Same as {@link createMatrixSourceResolverFromRecordLikeDataSource} but reads `payload.dataSource`
+ * from an {@link EffectiveMatrixConfig}.
+ *
+ * @throws When `dataSource` is missing or kind is not `record` / `query-snapshot`.
+ */
+export function createMatrixSourceResolverFromEffectiveConfig(effective, options) {
+    const ds = effective.payload.dataSource;
+    if (!ds) {
+        throw new Error('createMatrixSourceResolverFromEffectiveConfig: payload.dataSource is required');
+    }
+    if (ds.kind === 'record' || ds.kind === 'query-snapshot') {
+        return createMatrixSourceResolverFromRecordLikeDataSource(ds, options);
+    }
+    throw new Error(`createMatrixSourceResolverFromEffectiveConfig: unsupported dataSource.kind '${ds.kind}' — provide a custom MatrixSourceResolver (storage/event sources are host-specific).`);
+}
+//# sourceMappingURL=source-resolver-factories.js.map

package/dist/execution-matrix/source-resolver-factories.js.map

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

package/dist/execution-matrix/source-resolver-factories.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=source-resolver-factories.spec.d.ts.map

package/dist/execution-matrix/source-resolver-factories.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-resolver-factories.spec.d.ts","sourceRoot":"","sources":["../../src/execution-matrix/source-resolver-factories.spec.ts"],"names":[],"mappings":""}

package/dist/execution-matrix/source-resolver-factories.spec.js

@@ -0,0 +1,127 @@
+import { describe, expect, it } from 'vitest';
+import { MATRIX_FAILURE_PK, MATRIX_ROW_PK } from './constants.js';
+import { MemoryMatrixCollection } from './memory-store.js';
+import { fetchSourceJoinView } from './navigator.js';
+import { createExecutionMatrixRuntime } from './runtime-store.js';
+import { createMatrixSourceResolverFromEffectiveConfig, createMatrixSourceResolverFromRecordLikeDataSource, } from './source-resolver-factories.js';
+import { materializeExecutionMatrixRuntimeRows } from './materializer.js';
+describe('createMatrixSourceResolverFromRecordLikeDataSource', () => {
+    it('drives waitingInSource for fetchSourceJoinView', async () => {
+        const widgets = new MemoryMatrixCollection('_id');
+        await widgets.insert({ _id: 'w1', name: 'a' });
+        await widgets.insert({ _id: 'w2', name: 'b' });
+        const rows = new MemoryMatrixCollection(MATRIX_ROW_PK);
+        const fails = new MemoryMatrixCollection(MATRIX_FAILURE_PK);
+        const rt = createExecutionMatrixRuntime(rows.asCollection(), fails.asCollection(), { serializeClaims: true });
+        const [row] = materializeExecutionMatrixRuntimeRows({
+            matrixCatalogId: 'cat',
+            matrixItemId: 'item',
+            matrixRunId: 'r1',
+            payload: { input: {}, graphs: ['G'] },
+            graphRecords: [{ graphId: 'G', mappedInput: [], execution: { priority: 1 } }],
+            inputRows: [{ sourceId: 'w1' }],
+        });
+        await rt.insertRuntimeRow(row);
+        const resolver = createMatrixSourceResolverFromRecordLikeDataSource({
+            kind: 'record',
+            collectionRef: 'widgets',
+            selection: {},
+        }, {
+            resolveCollection: (ref) => {
+                expect(ref).toBe('widgets');
+                return widgets.asCollection();
+            },
+            sourceIdField: '_id',
+        });
+        const view = await fetchSourceJoinView({ runtime: rt, sourceResolver: resolver }, { matrixCatalogId: 'cat', matrixRunId: 'r1', graphId: 'G' });
+        expect(view.waitingInSource).toEqual(['w2']);
+        expect(view.waitingInMatrix).toHaveLength(1);
+    });
+    it('createMatrixSourceResolverFromEffectiveConfig rejects unsupported kinds', () => {
+        const effective = {
+            matrixCatalogId: 'cat',
+            payload: {
+                input: {},
+                graphs: ['G'],
+                dataSource: { kind: 'event' },
+            },
+            executionMode: { mode: 'single-pass' },
+            pollWhenEmptySeconds: 0,
+            dataSourceKind: 'event',
+        };
+        expect(() => createMatrixSourceResolverFromEffectiveConfig(effective, {
+            resolveCollection: () => {
+                throw new Error('unused');
+            },
+        })).toThrow(/unsupported dataSource\.kind/);
+    });
+    it('createMatrixSourceResolverFromEffectiveConfig rejects missing dataSource', () => {
+        const effective = {
+            matrixCatalogId: 'cat',
+            payload: { input: {}, graphs: ['G'] },
+            executionMode: { mode: 'single-pass' },
+            pollWhenEmptySeconds: 0,
+            dataSourceKind: 'event',
+        };
+        expect(() => createMatrixSourceResolverFromEffectiveConfig(effective, {
+            resolveCollection: () => {
+                throw new Error('unused');
+            },
+        })).toThrow(/payload\.dataSource is required/);
+    });
+    it('createMatrixSourceResolverFromEffectiveConfig supports record kind', async () => {
+        const widgets = new MemoryMatrixCollection('_id');
+        await widgets.insert({ _id: 'a1', v: 1 });
+        await widgets.insert({ _id: 'a2', v: 2 });
+        const effective = {
+            matrixCatalogId: 'cat',
+            payload: {
+                input: {},
+                graphs: ['G'],
+                dataSource: { kind: 'record', collectionRef: 'widgets', selection: {} },
+            },
+            executionMode: { mode: 'single-pass' },
+            pollWhenEmptySeconds: 0,
+            dataSourceKind: 'record',
+        };
+        const resolver = createMatrixSourceResolverFromEffectiveConfig(effective, {
+            resolveCollection: () => widgets.asCollection(),
+        });
+        const ids = await resolver.listSourceIds({});
+        expect(ids).toEqual(['a1', 'a2']);
+    });
+    it('createMatrixSourceResolverFromEffectiveConfig supports query-snapshot kind', async () => {
+        const widgets = new MemoryMatrixCollection('_id');
+        await widgets.insert({ _id: 'a1', v: 1 });
+        const effective = {
+            matrixCatalogId: 'cat',
+            payload: {
+                input: {},
+                graphs: ['G'],
+                dataSource: {
+                    kind: 'query-snapshot',
+                    collectionRef: 'widgets',
+                    selection: {},
+                    transform: { language: 'js', source: 'return records;', version: 'v1' },
+                },
+            },
+            executionMode: { mode: 'single-pass' },
+            pollWhenEmptySeconds: 0,
+            dataSourceKind: 'query-snapshot',
+        };
+        const resolver = createMatrixSourceResolverFromEffectiveConfig(effective, {
+            resolveCollection: () => widgets.asCollection(),
+        });
+        const ids = await resolver.listSourceIds({});
+        expect(ids).toEqual(['a1']);
+    });
+    it('fetchRecordsByIds preserves caller id order', async () => {
+        const widgets = new MemoryMatrixCollection('_id');
+        await widgets.insert({ _id: 'z', name: 'z' });
+        await widgets.insert({ _id: 'a', name: 'a' });
+        const resolver = createMatrixSourceResolverFromRecordLikeDataSource({ kind: 'record', collectionRef: 'widgets', selection: {} }, { resolveCollection: () => widgets.asCollection(), sourceIdField: '_id' });
+        const rows = await resolver.fetchRecordsByIds(['a', 'z', 'missing']);
+        expect(rows.map((r) => r._id)).toEqual(['a', 'z']);
+    });
+});
+//# sourceMappingURL=source-resolver-factories.spec.js.map

package/dist/execution-matrix/source-resolver-factories.spec.js.map

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

package/dist/execution-matrix/source-resolver.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Host-implemented bridge between an upstream source (collection / bucket / queue) and the
+ * execution matrix. Used by the run loop and by `fetchSourceJoinView` to know which records
+ * exist in the source vs which are already represented by matrix rows.
+ *
+ * Implementations live in product hosts (xmemory, custom MongoDB queries, blob listing …);
+ * this package only declares the interface and convenience helpers.
+ */
+export interface MatrixSourceResolver {
+    /**
+     * Return the list of source ids matching `selection` (and any host-defined `runtimeScope`).
+     *
+     * Order should be deterministic per (selection, scope) pair so callers can compute stable
+     * diffs against matrix-side ids. Pagination, if needed, is the host's concern; resolvers
+     * may cap the response and expose their own paging surface elsewhere.
+     */
+    listSourceIds(selection: Record<string, unknown> | undefined, runtimeScope?: Record<string, unknown>): Promise<string[]>;
+    /**
+     * Hydrate the actual record bodies for a list of ids returned by {@link listSourceIds}.
+     *
+     * Implementations should preserve the input order on the response when possible to make
+     * downstream materialization deterministic.
+     */
+    fetchRecordsByIds(ids: string[], runtimeScope?: Record<string, unknown>): Promise<Array<Record<string, unknown>>>;
+}
+/**
+ * Compute set difference of source ids minus already-known matrix ids.
+ * Useful for the run loop's "what hasn't been materialized yet" question.
+ */
+export declare function diffSourceIdsAgainstMatrix(sourceIds: ReadonlyArray<string>, matrixSourceIds: ReadonlyArray<string>): string[];
+//# sourceMappingURL=source-resolver.d.ts.map

package/dist/execution-matrix/source-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-resolver.d.ts","sourceRoot":"","sources":["../../src/execution-matrix/source-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,oBAAoB;IACnC;;;;;;OAMG;IACH,aAAa,CACX,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC9C,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACrC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAErB;;;;;OAKG;IACH,iBAAiB,CACf,GAAG,EAAE,MAAM,EAAE,EACb,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACrC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;CAC5C;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,aAAa,CAAC,MAAM,CAAC,EAChC,eAAe,EAAE,aAAa,CAAC,MAAM,CAAC,GACrC,MAAM,EAAE,CASV"}

package/dist/execution-matrix/source-resolver.js

@@ -0,0 +1,26 @@
+/**
+ * Host-implemented bridge between an upstream source (collection / bucket / queue) and the
+ * execution matrix. Used by the run loop and by `fetchSourceJoinView` to know which records
+ * exist in the source vs which are already represented by matrix rows.
+ *
+ * Implementations live in product hosts (xmemory, custom MongoDB queries, blob listing …);
+ * this package only declares the interface and convenience helpers.
+ */
+/**
+ * Compute set difference of source ids minus already-known matrix ids.
+ * Useful for the run loop's "what hasn't been materialized yet" question.
+ */
+export function diffSourceIdsAgainstMatrix(sourceIds, matrixSourceIds) {
+    if (sourceIds.length === 0)
+        return [];
+    if (matrixSourceIds.length === 0)
+        return [...sourceIds];
+    const seen = new Set(matrixSourceIds);
+    const out = [];
+    for (const id of sourceIds) {
+        if (!seen.has(id))
+            out.push(id);
+    }
+    return out;
+}
+//# sourceMappingURL=source-resolver.js.map

package/dist/execution-matrix/source-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-resolver.js","sourceRoot":"","sources":["../../src/execution-matrix/source-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA2BH;;;GAGG;AACH,MAAM,UAAU,0BAA0B,CACxC,SAAgC,EAChC,eAAsC;IAEtC,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACtC,IAAI,eAAe,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,GAAG,SAAS,CAAC,CAAC;IACxD,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,eAAe,CAAC,CAAC;IACtC,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,MAAM,EAAE,IAAI,SAAS,EAAE,CAAC;QAC3B,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAClC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/execution-matrix/status.d.ts

@@ -0,0 +1,7 @@
+import type { ExecutionMatrixStatus } from './contracts.js';
+/**
+ * Normalize user or legacy status strings to canonical {@link ExecutionMatrixStatus}.
+ */
+export declare function normalizeExecutionMatrixStatus(raw: string): ExecutionMatrixStatus | null;
+export declare function assertExecutionMatrixStatus(raw: string): ExecutionMatrixStatus;
+//# sourceMappingURL=status.d.ts.map

package/dist/execution-matrix/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../src/execution-matrix/status.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAkB5D;;GAEG;AACH,wBAAgB,8BAA8B,CAAC,GAAG,EAAE,MAAM,GAAG,qBAAqB,GAAG,IAAI,CAMxF;AAED,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,GAAG,qBAAqB,CAM9E"}

package/dist/execution-matrix/status.js

@@ -0,0 +1,33 @@
+import { EXECUTION_MATRIX_STATUSES } from './contracts.js';
+const ALIASES = {
+    'not-strated': 'not-started',
+    'not_started': 'not-started',
+    notstarted: 'not-started',
+    pending: 'not-started',
+    queued: 'not-started',
+    running: 'in-progress',
+    inprogress: 'in-progress',
+    done: 'completed',
+    success: 'completed',
+    error: 'failed',
+    cancelled: 'skipped',
+    canceled: 'skipped',
+};
+/**
+ * Normalize user or legacy status strings to canonical {@link ExecutionMatrixStatus}.
+ */
+export function normalizeExecutionMatrixStatus(raw) {
+    const s = raw.trim().toLowerCase().replace(/\s+/g, '-');
+    if (EXECUTION_MATRIX_STATUSES.includes(s)) {
+        return s;
+    }
+    return ALIASES[s] ?? null;
+}
+export function assertExecutionMatrixStatus(raw) {
+    const n = normalizeExecutionMatrixStatus(raw);
+    if (!n) {
+        throw new Error(`Invalid execution matrix status: ${JSON.stringify(raw)}`);
+    }
+    return n;
+}
+//# sourceMappingURL=status.js.map

package/dist/execution-matrix/status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.js","sourceRoot":"","sources":["../../src/execution-matrix/status.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAE3D,MAAM,OAAO,GAA0C;IACrD,aAAa,EAAE,aAAa;IAC5B,aAAa,EAAE,aAAa;IAC5B,UAAU,EAAE,aAAa;IACzB,OAAO,EAAE,aAAa;IACtB,MAAM,EAAE,aAAa;IACrB,OAAO,EAAE,aAAa;IACtB,UAAU,EAAE,aAAa;IACzB,IAAI,EAAE,WAAW;IACjB,OAAO,EAAE,WAAW;IACpB,KAAK,EAAE,QAAQ;IACf,SAAS,EAAE,SAAS;IACpB,QAAQ,EAAE,SAAS;CACpB,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,8BAA8B,CAAC,GAAW;IACxD,MAAM,CAAC,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACxD,IAAK,yBAA+C,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;QACjE,OAAO,CAA0B,CAAC;IACpC,CAAC;IACD,OAAO,OAAO,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;AAC5B,CAAC;AAED,MAAM,UAAU,2BAA2B,CAAC,GAAW;IACrD,MAAM,CAAC,GAAG,8BAA8B,CAAC,GAAG,CAAC,CAAC;IAC9C,IAAI,CAAC,CAAC,EAAE,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,oCAAoC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC7E,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC"}

package/dist/execution-matrix/xmemory-entity-collections.d.ts

@@ -0,0 +1,69 @@
+/**
+ * XMemory entity-collection registry: Catalox catalog listing plus resolved entity queries.
+ *
+ * The **registry** is a normal Catalox catalog (default id {@link DEFAULT_XMEMORY_ENTITY_COLLECTIONS_CATALOG_ID})
+ * whose items describe where entity rows live. Each registry item’s `data` should include either:
+ * - `entitiesCatalogId` (or `entityCatalogId` / `itemsCatalogId`) — Catalox catalog to list via {@link Catalox.listCatalogItems}, or
+ * - `recordCollectionRef` (or `xronoxCollectionRef` / `collectionRef`) — logical collection ref for {@link XronoxCollection.readMany}.
+ */
+import { type Catalox, type CataloxContext, type CatalogId, type CatalogListResult, type CatalogQueryOptions, type ItemId, type UnifiedCatalogItem } from '@x12i/catalox';
+import type { XronoxCollection } from '@x12i/xronox-store';
+/** Env: overrides default registry catalog id when non-empty after trim. */
+export declare const EXELLIX_XMEMORY_ENTITY_COLLECTIONS_CATALOG_ID_ENV: "EXELLIX_XMEMORY_ENTITY_COLLECTIONS_CATALOG_ID";
+export type XmemoryEntityCollectionsRuntimeConfig = {
+    /** Catalox catalog whose items define entity collections (metadata / pointers to corpora). */
+    entityCollectionsCatalogId: CatalogId;
+};
+export declare function resolveXmemoryEntityCollectionsRuntimeConfig(overrides?: Partial<XmemoryEntityCollectionsRuntimeConfig>): XmemoryEntityCollectionsRuntimeConfig;
+/** Read Catalox backing catalog id from a registry catalog item (`data.*`). */
+export declare function resolveEntitiesCatalogIdFromRegistryItem(item: UnifiedCatalogItem): CatalogId | undefined;
+/** Read xronox logical collection ref from a registry catalog item (`data.*`). */
+export declare function resolveRecordCollectionRefFromRegistryItem(item: UnifiedCatalogItem): string | undefined;
+/**
+ * List registry items from the configured entity-collections catalog (default {@link DEFAULT_XMEMORY_ENTITY_COLLECTIONS_CATALOG_ID}).
+ * Forwards `query` to {@link Catalox.listCatalogItems} (`limit`, `offset`, `filter`, `sort`, `scope`).
+ */
+export declare function listXmemoryEntityCollectionRegistryItems(catalox: Catalox, context: CataloxContext, query?: CatalogQueryOptions, config?: Partial<XmemoryEntityCollectionsRuntimeConfig>): Promise<CatalogListResult>;
+export type ListXmemoryEntityCollectionCatalogEntitiesInput = {
+    /**
+     * Registry item id — loads `data.entitiesCatalogId` (or aliases) from the entity-collections catalog.
+     * Ignored when `entitiesCatalogId` is set.
+     */
+    registryItemId?: ItemId;
+    /** When set, lists this catalog directly (skips registry lookup). */
+    entitiesCatalogId?: CatalogId;
+    /** Passed through to {@link Catalox.listCatalogItems} after {@link compactCatalogFilter} on `filter`. */
+    query?: CatalogQueryOptions;
+};
+/**
+ * List entity rows exposed as a **Catalox catalog** (native or mapped).
+ *
+ * Resolve order: `entitiesCatalogId` override → registry item `data.entitiesCatalogId` / aliases.
+ * Throws if neither yields a catalog id.
+ */
+export declare function listXmemoryEntityCollectionCatalogEntities(catalox: Catalox, context: CataloxContext, input: ListXmemoryEntityCollectionCatalogEntitiesInput, config?: Partial<XmemoryEntityCollectionsRuntimeConfig>): Promise<CatalogListResult>;
+export type ListXmemoryEntityCollectionDocumentsInput = {
+    /** Registry item id — must carry `recordCollectionRef` (or aliases). */
+    registryItemId: ItemId;
+    /** Mongo-style filter for {@link XronoxCollection.readMany}. */
+    filter?: Record<string, unknown>;
+    limit?: number;
+    sort?: Record<string, 1 | -1>;
+    mergeCache?: boolean;
+    /** When true, runs {@link XronoxCollection.countMatching} with the same filter (extra round-trip). */
+    includeTotal?: boolean;
+};
+export type ListXmemoryEntityCollectionDocumentsDeps = {
+    resolveCollection: (collectionRef: string) => XronoxCollection<Record<string, unknown>>;
+};
+/**
+ * List raw documents for an entity collection backed by **xronox** (Mongo-shaped rows).
+ *
+ * Pagination: use `limit` + tight `filter`. Deep paging without skip is a known xronox read constraint;
+ * prefer Catalox-mapped catalogs for offset-style paging via {@link listXmemoryEntityCollectionCatalogEntities}.
+ */
+export declare function listXmemoryEntityCollectionDocuments(catalox: Catalox, context: CataloxContext, input: ListXmemoryEntityCollectionDocumentsInput, deps: ListXmemoryEntityCollectionDocumentsDeps, config?: Partial<XmemoryEntityCollectionsRuntimeConfig>): Promise<{
+    rows: Record<string, unknown>[];
+    total?: number;
+}>;
+//# sourceMappingURL=xmemory-entity-collections.d.ts.map

package/dist/execution-matrix/xmemory-entity-collections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xmemory-entity-collections.d.ts","sourceRoot":"","sources":["../../src/execution-matrix/xmemory-entity-collections.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAEL,KAAK,OAAO,EACZ,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,MAAM,EACX,KAAK,kBAAkB,EACxB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAG3D,4EAA4E;AAC5E,eAAO,MAAM,iDAAiD,EAC5D,+CAAwD,CAAC;AAE3D,MAAM,MAAM,qCAAqC,GAAG;IAClD,8FAA8F;IAC9F,0BAA0B,EAAE,SAAS,CAAC;CACvC,CAAC;AAEF,wBAAgB,4CAA4C,CAC1D,SAAS,CAAC,EAAE,OAAO,CAAC,qCAAqC,CAAC,GACzD,qCAAqC,CAWvC;AAYD,+EAA+E;AAC/E,wBAAgB,wCAAwC,CAAC,IAAI,EAAE,kBAAkB,GAAG,SAAS,GAAG,SAAS,CASxG;AAED,kFAAkF;AAClF,wBAAgB,0CAA0C,CAAC,IAAI,EAAE,kBAAkB,GAAG,MAAM,GAAG,SAAS,CASvG;AA0BD;;;GAGG;AACH,wBAAsB,wCAAwC,CAC5D,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,cAAc,EACvB,KAAK,CAAC,EAAE,mBAAmB,EAC3B,MAAM,CAAC,EAAE,OAAO,CAAC,qCAAqC,CAAC,GACtD,OAAO,CAAC,iBAAiB,CAAC,CAG5B;AAED,MAAM,MAAM,+CAA+C,GAAG;IAC5D;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,iBAAiB,CAAC,EAAE,SAAS,CAAC;IAC9B,yGAAyG;IACzG,KAAK,CAAC,EAAE,mBAAmB,CAAC;CAC7B,CAAC;AAEF;;;;;GAKG;AACH,wBAAsB,0CAA0C,CAC9D,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,+CAA+C,EACtD,MAAM,CAAC,EAAE,OAAO,CAAC,qCAAqC,CAAC,GACtD,OAAO,CAAC,iBAAiB,CAAC,CAgB5B;AAED,MAAM,MAAM,yCAAyC,GAAG;IACtD,wEAAwE;IACxE,cAAc,EAAE,MAAM,CAAC;IACvB,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAC9B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,sGAAsG;IACtG,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,wCAAwC,GAAG;IACrD,iBAAiB,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,gBAAgB,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACzF,CAAC;AAEF;;;;;GAKG;AACH,wBAAsB,oCAAoC,CACxD,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,yCAAyC,EAChD,IAAI,EAAE,wCAAwC,EAC9C,MAAM,CAAC,EAAE,OAAO,CAAC,qCAAqC,CAAC,GACtD,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAsB9D"}