@exellix/exellix-runtime 3.5.1

package/dist/execution-matrix/xmemory-entity-collections.js

@@ -0,0 +1,120 @@
+/**
+ * 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 { compactCatalogFilter, } from '@x12i/catalox';
+import { DEFAULT_XMEMORY_ENTITY_COLLECTIONS_CATALOG_ID } from './constants.js';
+/** Env: overrides default registry catalog id when non-empty after trim. */
+export const EXELLIX_XMEMORY_ENTITY_COLLECTIONS_CATALOG_ID_ENV = 'EXELLIX_XMEMORY_ENTITY_COLLECTIONS_CATALOG_ID';
+export function resolveXmemoryEntityCollectionsRuntimeConfig(overrides) {
+    const envRaw = typeof process !== 'undefined'
+        ? process.env?.[EXELLIX_XMEMORY_ENTITY_COLLECTIONS_CATALOG_ID_ENV]
+        : undefined;
+    const envId = typeof envRaw === 'string' ? envRaw.trim() : '';
+    return {
+        entityCollectionsCatalogId: overrides?.entityCollectionsCatalogId ??
+            (envId.length > 0 ? envId : DEFAULT_XMEMORY_ENTITY_COLLECTIONS_CATALOG_ID),
+    };
+}
+function normalizeCatalogQueryOptions(query) {
+    if (!query)
+        return undefined;
+    const compacted = compactCatalogFilter(query.filter);
+    const next = { ...query };
+    if (query.filter !== undefined) {
+        next.filter = Object.keys(compacted).length > 0 ? compacted : undefined;
+    }
+    return next;
+}
+/** Read Catalox backing catalog id from a registry catalog item (`data.*`). */
+export function resolveEntitiesCatalogIdFromRegistryItem(item) {
+    const data = item.data;
+    if (!data || typeof data !== 'object')
+        return undefined;
+    const rec = data;
+    for (const key of ['entitiesCatalogId', 'entityCatalogId', 'itemsCatalogId']) {
+        const v = rec[key];
+        if (typeof v === 'string' && v.trim())
+            return v.trim();
+    }
+    return undefined;
+}
+/** Read xronox logical collection ref from a registry catalog item (`data.*`). */
+export function resolveRecordCollectionRefFromRegistryItem(item) {
+    const data = item.data;
+    if (!data || typeof data !== 'object')
+        return undefined;
+    const rec = data;
+    for (const key of ['recordCollectionRef', 'xronoxCollectionRef', 'collectionRef']) {
+        const v = rec[key];
+        if (typeof v === 'string' && v.trim())
+            return v.trim();
+    }
+    return undefined;
+}
+async function loadRegistryItem(catalox, context, registryItemId, resolvedConfig) {
+    const got = await catalox.getCatalogItem(context, resolvedConfig.entityCollectionsCatalogId, registryItemId);
+    if (got.outcome === 'not_found') {
+        throw new Error(`listXmemoryEntityCollection*: registry item '${registryItemId}' not found in catalog '${resolvedConfig.entityCollectionsCatalogId}'`);
+    }
+    if (got.outcome === 'mapping_blocked') {
+        throw new Error(`listXmemoryEntityCollection*: registry item '${registryItemId}' mapping_blocked in catalog '${resolvedConfig.entityCollectionsCatalogId}'`);
+    }
+    return got.item;
+}
+/**
+ * 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 async function listXmemoryEntityCollectionRegistryItems(catalox, context, query, config) {
+    const resolved = resolveXmemoryEntityCollectionsRuntimeConfig(config);
+    return catalox.listCatalogItems(context, resolved.entityCollectionsCatalogId, normalizeCatalogQueryOptions(query));
+}
+/**
+ * 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 async function listXmemoryEntityCollectionCatalogEntities(catalox, context, input, config) {
+    const resolvedConfig = resolveXmemoryEntityCollectionsRuntimeConfig(config);
+    let catalogId = input.entitiesCatalogId?.trim();
+    if (!catalogId && input.registryItemId) {
+        const item = await loadRegistryItem(catalox, context, input.registryItemId, resolvedConfig);
+        catalogId = resolveEntitiesCatalogIdFromRegistryItem(item);
+    }
+    if (!catalogId) {
+        throw new Error('listXmemoryEntityCollectionCatalogEntities: provide entitiesCatalogId or a registry item whose data includes entitiesCatalogId (or entityCatalogId / itemsCatalogId)');
+    }
+    return catalox.listCatalogItems(context, catalogId, normalizeCatalogQueryOptions(input.query));
+}
+/**
+ * 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 async function listXmemoryEntityCollectionDocuments(catalox, context, input, deps, config) {
+    const resolvedConfig = resolveXmemoryEntityCollectionsRuntimeConfig(config);
+    const item = await loadRegistryItem(catalox, context, input.registryItemId, resolvedConfig);
+    const ref = resolveRecordCollectionRefFromRegistryItem(item);
+    if (!ref) {
+        throw new Error(`listXmemoryEntityCollectionDocuments: registry item '${input.registryItemId}' missing recordCollectionRef (or xronoxCollectionRef / collectionRef) in data`);
+    }
+    const coll = deps.resolveCollection(ref);
+    const filter = input.filter ?? {};
+    const readOpts = {
+        limit: input.limit,
+        sort: input.sort,
+        mergeCache: input.mergeCache ?? true,
+    };
+    const rowsP = coll.readMany(filter, readOpts);
+    const totalP = input.includeTotal ? coll.countMatching(filter) : Promise.resolve(undefined);
+    const [rows, total] = await Promise.all([rowsP, totalP]);
+    return total !== undefined ? { rows, total } : { rows };
+}
+//# sourceMappingURL=xmemory-entity-collections.js.map

package/dist/execution-matrix/xmemory-entity-collections.js.map

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

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=xmemory-entity-collections.spec.d.ts.map

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

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

package/dist/execution-matrix/xmemory-entity-collections.spec.js

@@ -0,0 +1,112 @@
+import { describe, expect, it, vi } from 'vitest';
+import { MemoryMatrixCollection } from './memory-store.js';
+import { EXELLIX_XMEMORY_ENTITY_COLLECTIONS_CATALOG_ID_ENV, listXmemoryEntityCollectionCatalogEntities, listXmemoryEntityCollectionDocuments, listXmemoryEntityCollectionRegistryItems, resolveEntitiesCatalogIdFromRegistryItem, resolveRecordCollectionRefFromRegistryItem, resolveXmemoryEntityCollectionsRuntimeConfig, } from './xmemory-entity-collections.js';
+import { DEFAULT_XMEMORY_ENTITY_COLLECTIONS_CATALOG_ID } from './constants.js';
+const ctx = { appId: 'app_test' };
+describe('resolveXmemoryEntityCollectionsRuntimeConfig', () => {
+    it('defaults to package constant', () => {
+        const prev = process.env[EXELLIX_XMEMORY_ENTITY_COLLECTIONS_CATALOG_ID_ENV];
+        delete process.env[EXELLIX_XMEMORY_ENTITY_COLLECTIONS_CATALOG_ID_ENV];
+        expect(resolveXmemoryEntityCollectionsRuntimeConfig().entityCollectionsCatalogId).toBe(DEFAULT_XMEMORY_ENTITY_COLLECTIONS_CATALOG_ID);
+        if (prev !== undefined)
+            process.env[EXELLIX_XMEMORY_ENTITY_COLLECTIONS_CATALOG_ID_ENV] = prev;
+    });
+    it('respects overrides over env', () => {
+        process.env[EXELLIX_XMEMORY_ENTITY_COLLECTIONS_CATALOG_ID_ENV] = 'from-env';
+        expect(resolveXmemoryEntityCollectionsRuntimeConfig({ entityCollectionsCatalogId: 'override' })
+            .entityCollectionsCatalogId).toBe('override');
+        delete process.env[EXELLIX_XMEMORY_ENTITY_COLLECTIONS_CATALOG_ID_ENV];
+    });
+});
+describe('registry item data helpers', () => {
+    const base = (data) => ({
+        itemId: 'reg1',
+        catalogId: DEFAULT_XMEMORY_ENTITY_COLLECTIONS_CATALOG_ID,
+        sourceMode: 'native',
+        data,
+        metadata: {},
+    });
+    it('resolveEntitiesCatalogIdFromRegistryItem picks known keys', () => {
+        expect(resolveEntitiesCatalogIdFromRegistryItem(base({ entitiesCatalogId: '  cats  ' }))).toBe('cats');
+        expect(resolveEntitiesCatalogIdFromRegistryItem(base({ entityCatalogId: 'e' }))).toBe('e');
+        expect(resolveEntitiesCatalogIdFromRegistryItem(base({ itemsCatalogId: 'i' }))).toBe('i');
+        expect(resolveEntitiesCatalogIdFromRegistryItem(base({}))).toBeUndefined();
+    });
+    it('resolveRecordCollectionRefFromRegistryItem picks known keys', () => {
+        expect(resolveRecordCollectionRefFromRegistryItem(base({ recordCollectionRef: ' r ' }))).toBe('r');
+        expect(resolveRecordCollectionRefFromRegistryItem(base({ xronoxCollectionRef: 'x' }))).toBe('x');
+        expect(resolveRecordCollectionRefFromRegistryItem(base({ collectionRef: 'c' }))).toBe('c');
+    });
+});
+describe('listXmemoryEntityCollectionRegistryItems', () => {
+    it('lists against resolved catalog id', async () => {
+        const listCatalogItems = vi.fn().mockResolvedValue({
+            listOutcome: 'ok',
+            items: [],
+        });
+        const catalox = { listCatalogItems };
+        await listXmemoryEntityCollectionRegistryItems(catalox, ctx, { limit: 5 }, {
+            entityCollectionsCatalogId: 'my-registry',
+        });
+        expect(listCatalogItems).toHaveBeenCalledWith(ctx, 'my-registry', { limit: 5 });
+    });
+});
+describe('listXmemoryEntityCollectionCatalogEntities', () => {
+    it('uses entitiesCatalogId override without getCatalogItem', async () => {
+        const listCatalogItems = vi.fn().mockResolvedValue({ listOutcome: 'ok', items: [{ itemId: 'a' }] });
+        const getCatalogItem = vi.fn();
+        const catalox = { listCatalogItems, getCatalogItem };
+        const res = await listXmemoryEntityCollectionCatalogEntities(catalox, ctx, { entitiesCatalogId: 'entities', query: { filter: { x: '' }, limit: 10 } });
+        expect(getCatalogItem).not.toHaveBeenCalled();
+        expect(listCatalogItems).toHaveBeenCalledWith(ctx, 'entities', { filter: undefined, limit: 10 });
+        expect(res.items).toHaveLength(1);
+    });
+    it('loads registry item then lists entities catalog', async () => {
+        const item = {
+            itemId: 'r1',
+            catalogId: DEFAULT_XMEMORY_ENTITY_COLLECTIONS_CATALOG_ID,
+            sourceMode: 'native',
+            data: { entitiesCatalogId: 'pet-catalog' },
+            metadata: {},
+        };
+        const getCatalogItem = vi.fn().mockResolvedValue({ outcome: 'found', item });
+        const listCatalogItems = vi.fn().mockResolvedValue({ listOutcome: 'ok', items: [] });
+        const catalox = { getCatalogItem, listCatalogItems };
+        await listXmemoryEntityCollectionCatalogEntities(catalox, ctx, { registryItemId: 'r1' });
+        expect(getCatalogItem).toHaveBeenCalledWith(ctx, DEFAULT_XMEMORY_ENTITY_COLLECTIONS_CATALOG_ID, 'r1');
+        expect(listCatalogItems).toHaveBeenCalledWith(ctx, 'pet-catalog', undefined);
+    });
+});
+describe('listXmemoryEntityCollectionDocuments', () => {
+    it('reads xronox collection via resolveCollection', async () => {
+        const item = {
+            itemId: 'r2',
+            catalogId: DEFAULT_XMEMORY_ENTITY_COLLECTIONS_CATALOG_ID,
+            sourceMode: 'native',
+            data: { recordCollectionRef: 'things' },
+            metadata: {},
+        };
+        const getCatalogItem = vi.fn().mockResolvedValue({ outcome: 'found', item });
+        const catalox = { getCatalogItem };
+        const mem = new MemoryMatrixCollection('_id');
+        await mem.insert({ _id: '1', kind: 'dog' });
+        const res = await listXmemoryEntityCollectionDocuments(catalox, ctx, { registryItemId: 'r2', filter: {}, limit: 10 }, {
+            resolveCollection: (ref) => {
+                expect(ref).toBe('things');
+                return mem.asCollection();
+            },
+        });
+        expect(res.rows).toHaveLength(1);
+        expect(res.total).toBeUndefined();
+        const mockColl = {
+            readMany: vi.fn().mockResolvedValue([{ _id: '1' }]),
+            countMatching: vi.fn().mockResolvedValue(42),
+        };
+        const withTotal = await listXmemoryEntityCollectionDocuments(catalox, ctx, { registryItemId: 'r2', filter: { a: 1 }, includeTotal: true }, {
+            resolveCollection: () => mockColl,
+        });
+        expect(withTotal.total).toBe(42);
+        expect(mockColl.countMatching).toHaveBeenCalledWith({ a: 1 });
+    });
+});
+//# sourceMappingURL=xmemory-entity-collections.spec.js.map

package/dist/execution-matrix/xmemory-entity-collections.spec.js.map

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

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

@@ -0,0 +1,172 @@
+/**
+ * Read helpers for the XMemory **operational** Mongo tier (`tier.env.opDb`, typically **`xmemory-op`**
+ * — align with deployment **`XMEMORY_OP_DB`** and `@x12i/xmemory-store` tier defaults).
+ *
+ * `@x12i/xmemory-store` registers {@link tier.opStore} with **scoped views** (`tier.env.viewsCollection`,
+ * default `scoped_views`). Use {@link listXmemoryOpScopedViews} for xronox-shaped reads (visibility / cache merge)
+ * and {@link listXmemoryOpScopedViewsPaged} when you need **`skip` / offset** paging via the tier
+ * {@link XmemoryMongoClient}.
+ *
+ * **Scoped data / snapshots** live in the same op DB but are **not** first-class xronox collections on the tier
+ * adapter — reads use {@link tier.mongoClient} (`findMany` / `countMany`), typically with **`fallbackMongoClient`**
+ * wired at tier creation. Collection names come from {@link MemorixRuntimeTier.env} (`scopedDataCollection` default
+ * **`x-scoped-data`**, `snapshotsCollection` default **`x-snapshots`**), overridable via **`SCOPED_DATA_COLLECTION`**
+ * / **`SNAPSHOTS_COLLECTION`** (see {@link resolveMemorixRuntimeTierEnv}).
+ */
+import type { XmemoryDataTier } from './memorix-runtime-tier.js';
+import type { XronoxCollection } from '@x12i/xronox-store';
+export { COLLECTION_DEFAULTS, DEFAULT_SCOPED_DATA_COLLECTION, DEFAULT_SNAPSHOTS_COLLECTION, FIND_MANY_DEFAULT_LIMIT_WITH_SKIP, FIND_MANY_MAX_SKIP, FIND_MANY_MAX_WINDOW, } from './memorix-runtime-tier.js';
+/** xronox collection handle for scoped view rows on {@link XmemoryDataTier.opStore}. */
+export declare function getXmemoryOpScopedViewsCollection(tier: XmemoryDataTier): XronoxCollection<Record<string, unknown>>;
+/** xronox collection handle for **things** on {@link XmemoryDataTier.corpusStore} (`tier.env.thingsCollection`). */
+export declare function getXmemoryTierThingsCollection(tier: XmemoryDataTier): XronoxCollection<Record<string, unknown>>;
+/**
+ * Recommended **`groupByPaths.scoped_data`** for {@link getXmemoryTierStatistics} so entity-type buckets align with
+ * {@link buildXScopedDataEntityTypeFilter} (camelCase and snake_case documents).
+ */
+export declare const RECOMMENDED_TIER_STATS_SCOPED_DATA_GROUP_PATHS: readonly ["$entityType", "$entity_type"];
+export type ListXmemoryTierThingsOptions = {
+    filter?: Record<string, unknown>;
+    limit?: number;
+    sort?: Record<string, 1 | -1>;
+    mergeCache?: boolean;
+    includeHidden?: boolean;
+};
+/**
+ * List thing documents via xronox {@link XronoxCollection.readMany} on the corpus store.
+ * No `skip` — use {@link listXmemoryTierThingsPaged} for offset paging.
+ */
+export declare function listXmemoryTierThings(tier: XmemoryDataTier, options?: ListXmemoryTierThingsOptions): Promise<Record<string, unknown>[]>;
+export declare function countXmemoryTierThings(tier: XmemoryDataTier, filter?: Record<string, unknown>, includeHidden?: boolean): Promise<number>;
+/**
+ * Paged things read via {@link XmemoryMongoClient.findMany} on **`thingsDb`** / **`thingsCollection`**.
+ */
+export declare function listXmemoryTierThingsPaged(tier: XmemoryDataTier, query?: ListXmemoryOpPagedQuery): Promise<Record<string, unknown>[]>;
+export declare function countXmemoryTierThingsMongo(tier: XmemoryDataTier, filter?: Record<string, unknown>): Promise<number>;
+export type FetchAllXmemoryTierThingsOptions = {
+    filter?: Record<string, unknown>;
+    pageSize?: number;
+    maxRows?: number;
+};
+/**
+ * Walk things with repeated paged reads until empty or limits hit.
+ */
+export declare function fetchAllXmemoryTierThings(tier: XmemoryDataTier, options?: FetchAllXmemoryTierThingsOptions): Promise<Record<string, unknown>[]>;
+export type ListXmemoryOpScopedViewsOptions = {
+    filter?: Record<string, unknown>;
+    limit?: number;
+    sort?: Record<string, 1 | -1>;
+    mergeCache?: boolean;
+    includeHidden?: boolean;
+};
+/**
+ * List scoped view documents via xronox {@link XronoxCollection.readMany} (same path as scoper tier wiring).
+ * Does **not** support `skip`; use {@link listXmemoryOpScopedViewsPaged} for offset paging.
+ */
+export declare function listXmemoryOpScopedViews(tier: XmemoryDataTier, options?: ListXmemoryOpScopedViewsOptions): Promise<Record<string, unknown>[]>;
+/** Match semantics align with {@link listXmemoryOpScopedViews} / xronox visibility rules on scoped views. */
+export declare function countXmemoryOpScopedViews(tier: XmemoryDataTier, filter?: Record<string, unknown>, includeHidden?: boolean): Promise<number>;
+export type ListXmemoryOpPagedQuery = {
+    filter?: Record<string, unknown>;
+    limit?: number;
+    skip?: number;
+    projection?: Record<string, 0 | 1>;
+};
+/**
+ * Paged read using {@link XmemoryMongoClient.findMany} — supports **`skip`** for walking large corpora.
+ * Prefer {@link listXmemoryOpScopedViews} when you only need the first `limit` rows and want cache-merged reads.
+ */
+export declare function listXmemoryOpScopedViewsPaged(tier: XmemoryDataTier, query?: ListXmemoryOpPagedQuery): Promise<Record<string, unknown>[]>;
+/**
+ * Document count for scoped views using {@link XmemoryMongoClient.countMany} when present; otherwise falls back
+ * to {@link countXmemoryOpScopedViews} (xronox path).
+ */
+export declare function countXmemoryOpScopedViewsMongo(tier: XmemoryDataTier, filter?: Record<string, unknown>): Promise<number>;
+export type FetchAllXmemoryOpScopedViewsOptions = {
+    filter?: Record<string, unknown>;
+    /** Page size for each {@link listXmemoryOpScopedViewsPaged} call. */
+    pageSize?: number;
+    /** Hard cap on rows returned (defaults to {@link FIND_MANY_MAX_WINDOW}). */
+    maxRows?: number;
+};
+/**
+ * Walk scoped views with repeated paged reads until a batch is empty or limits hit.
+ * Intended for exports / batch jobs — prefer bounded filters in production.
+ */
+export declare function fetchAllXmemoryOpScopedViews(tier: XmemoryDataTier, options?: FetchAllXmemoryOpScopedViewsOptions): Promise<Record<string, unknown>[]>;
+/**
+ * Count documents in any collection under {@link XmemoryDataTier.env.opDb}.
+ * Uses xronox {@link XronoxCollection.countMatching} when `collectionName` is the scoped-views collection.
+ */
+export declare function countXmemoryOpCollectionDocuments(tier: XmemoryDataTier, collectionName: string, filter?: Record<string, unknown>, includeHidden?: boolean): Promise<number>;
+/**
+ * List documents from any collection in `tier.env.opDb` via {@link XmemoryMongoClient.findMany} (`skip` / `limit` / `projection`).
+ */
+export declare function listXmemoryOpCollectionDocumentsPaged(tier: XmemoryDataTier, collectionName: string, query?: ListXmemoryOpPagedQuery): Promise<Record<string, unknown>[]>;
+export type FetchAllXmemoryOpCollectionOptions = FetchAllXmemoryOpScopedViewsOptions;
+/**
+ * Same as {@link fetchAllXmemoryOpScopedViews} but for an arbitrary collection name in the op database.
+ */
+export declare function fetchAllXmemoryOpCollectionDocuments(tier: XmemoryDataTier, collectionName: string, options?: FetchAllXmemoryOpCollectionOptions): Promise<Record<string, unknown>[]>;
+/** Resolved scoped-data collection on the op DB ({@link XmemoryDataTier.env.scopedDataCollection}). */
+export declare function getXmemoryTierScopedDataCollectionName(tier: XmemoryDataTier): string;
+/** Resolved Memorix snapshots collection on the op DB ({@link XmemoryDataTier.env.snapshotsCollection}). */
+export declare function getXmemoryTierSnapshotsCollectionName(tier: XmemoryDataTier): string;
+/**
+ * {@link countXmemoryOpCollectionDocuments} for {@link XmemoryDataTier.env.scopedDataCollection}.
+ */
+export declare function countXmemoryTierScopedDataDocuments(tier: XmemoryDataTier, filter?: Record<string, unknown>, includeHidden?: boolean): Promise<number>;
+/**
+ * {@link listXmemoryOpCollectionDocumentsPaged} for {@link XmemoryDataTier.env.scopedDataCollection}.
+ */
+export declare function listXmemoryTierScopedDataPaged(tier: XmemoryDataTier, query?: ListXmemoryOpPagedQuery): Promise<Record<string, unknown>[]>;
+/**
+ * {@link fetchAllXmemoryOpCollectionDocuments} for {@link XmemoryDataTier.env.scopedDataCollection}.
+ */
+export declare function fetchAllXmemoryTierScopedDataDocuments(tier: XmemoryDataTier, options?: FetchAllXmemoryOpCollectionOptions): Promise<Record<string, unknown>[]>;
+/**
+ * {@link countXmemoryOpCollectionDocuments} for {@link XmemoryDataTier.env.snapshotsCollection}.
+ */
+export declare function countXmemoryTierSnapshotDocuments(tier: XmemoryDataTier, filter?: Record<string, unknown>, includeHidden?: boolean): Promise<number>;
+/**
+ * {@link listXmemoryOpCollectionDocumentsPaged} for {@link XmemoryDataTier.env.snapshotsCollection}.
+ */
+export declare function listXmemoryTierSnapshotsPaged(tier: XmemoryDataTier, query?: ListXmemoryOpPagedQuery): Promise<Record<string, unknown>[]>;
+/**
+ * {@link fetchAllXmemoryOpCollectionDocuments} for {@link XmemoryDataTier.env.snapshotsCollection}.
+ */
+export declare function fetchAllXmemoryTierSnapshotDocuments(tier: XmemoryDataTier, options?: FetchAllXmemoryOpCollectionOptions): Promise<Record<string, unknown>[]>;
+/**
+ * Thin delegate for {@link XmemoryDataTier.runMongoAggregate} — native aggregation on **`mapsDb`**, **`thingsDb`**, or **`opDb`**.
+ */
+export declare function runXmemoryTierMongoAggregate(tier: XmemoryDataTier, params: {
+    database: string;
+    collection: string;
+    pipeline: Record<string, unknown>[];
+}): Promise<unknown[]>;
+/**
+ * Canonical Mongo filter for Memorix **scoped data** (`tier.env.scopedDataCollection`, default **`x-scoped-data`**;
+ * legacy deployments often use **`x_scoped_data`** via **`SCOPED_DATA_COLLECTION`**) keyed by entity discriminator.
+ * Matches either camelCase or snake_case field names used across pipelines.
+ *
+ * Pair with {@link countXmemoryTierScopedDataDocuments}, {@link countXmemoryOpCollectionDocuments}, {@link runXmemoryTierMongoAggregate},
+ * or your host’s direct Mongo count — keep **`database`** aligned with {@link XmemoryDataTier.env.opDb}. When the tier path fails,
+ * **surface** errors instead of silently falling back (hosts such as Graphs Studio should not swallow {@link countXmemoryOpCollectionDocuments}
+ * failures — it throws if `mongoClient.countMany` is missing for non–views collections).
+ */
+export declare function buildXScopedDataEntityTypeFilter(catalogId: string): Record<string, unknown>;
+/**
+ * Mongo filter for Memorix **scoped views** (`tier.env.viewsCollection`) by entity / thing type.
+ * Aligns with default {@link getXmemoryTierStatistics} paths for **`scoped_views`** (`aboutThingType`, nested metadata).
+ */
+export declare function buildXScopedViewEntityTypeFilter(entityType: string): Record<string, unknown>;
+/**
+ * Mongo filter for Memorix **x-snapshots** (`tier.env.snapshotsCollection`) by embedded snapshot entity type.
+ * Aligns with default tier statistics path `$_snapshot.entityType`; includes snake_case variant when present on docs.
+ */
+export declare function buildXMemorixSnapshotEntityTypeFilter(entityType: string): Record<string, unknown>;
+/**
+ * Mongo filter for **things** matching tier statistics default buckets (`thingType` / header layout).
+ */
+export declare function buildXThingEntityTypeFilter(entityType: string): Record<string, unknown>;
+//# sourceMappingURL=xmemory-op-tier.d.ts.map

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

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