@exellix/exellix-runtime 3.5.1

package/dist/catalox-inventory/catalox-xmemory-entity-count-report.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Read-only report: **entity type keys** from Catalox native catalog(s) and/or **scoped-data tier discovery**;
+ * `@x12i/xmemory-store` supplies namespace-scoped counts (same predicates as {@link getXmemoryTierStatistics}).
+ */
+import type { Catalox, CataloxContext, UnifiedCatalogItem } from '@x12i/catalox';
+import type { XmemoryDataTier, XmemoryMongoClient } from '../execution-matrix/memorix-runtime-tier.js';
+import { MongoClient } from 'mongodb';
+import { type ExecutionMatrixRuntime } from '../execution-matrix/runtime-store.js';
+/** `entityCatalogId` / row **`catalogId`** when types come from tier statistics, not a Catalox catalog. */
+export declare const SCOPED_DATA_TIER_ENTITY_DISCOVERY_CATALOG_ID: "__scoped_data_tier__";
+/**
+ * Default **`groupByPaths.scoped_data`** for tier discovery — broader than **`DEFAULT_ENTITY_TYPE_PATHS.scoped_data`**
+ * so rows that only store the discriminator under **`data.*`** / **`metadata.*`** still bucket into real type keys.
+ */
+export declare const DEFAULT_ENTITY_DISCOVERY_SCOPED_DATA_GROUP_PATHS: readonly ["$entityType", "$entity_type", "$data.entityType", "$data.entity_type", "$metadata.entityType", "$metadata.entity_type"];
+/** `$match` fragment: any of the common scoped-data locations equals **`entityTypeKey`**. */
+export declare function buildExtendedScopedDataEntityTypeFilter(entityTypeKey: string): Record<string, unknown>;
+export type ScopedDataTierEntityTypeDiscovery = {
+    keys: string[];
+    scopedDataMatchedTotal: number;
+    /** Doc count in the **`__missing__`** bucket for {@link ScopedDataTierEntityTypeDiscovery.groupByPathsUsed}. */
+    missingBucketDocCount: number;
+    groupByPathsUsed: readonly string[];
+};
+export type TierDiscoveryDiagnostics = ScopedDataTierEntityTypeDiscovery & {
+    /** When **`keys`** is empty but **`scopedDataMatchedTotal`** is not. */
+    emptyKeysHint?: string;
+};
+export type CollectScopedDataEntityTypeDiscoveryOptions = {
+    signal?: AbortSignal;
+    /** Override **`groupByPaths.scoped_data`** (Mongo aggregation field paths, usually with **`$`** prefix). */
+    groupByPathsScopedData?: readonly string[];
+};
+/** Normalize one or many catalog ids: trim, drop empties, preserve first-seen order. */
+export declare function normalizeEntityReportCatalogIds(catalogIds: string | readonly string[]): string[];
+/**
+ * Resolves the xmemory **entity type key** for a Catalox native row (used as `entityTypeKey` in tier match).
+ * Order: explicit `data.*` fields, then **`itemId`** (common when each row is one entity slug).
+ */
+export declare function entityTypeKeyFromCatalogItem(item: UnifiedCatalogItem): string | undefined;
+export type CataloxXmemoryEntitySurfaceCounts = {
+    scopedData: number;
+    things: number;
+    scopedViews: number;
+    snapshots: number;
+};
+/** Execution matrix slice for one entity type (rows match {@link buildMatrixRowEntityTypeExtraFilter}; snapshots use `entityType`). */
+export type CataloxXmemoryEntityMatrixSlice = {
+    matrixCatalogId: string;
+    matrixRunId?: string;
+    rows: number;
+    snapshots: number;
+    error?: string;
+};
+export type CataloxXmemoryEntityCountRow = {
+    catalogId: string;
+    itemId: string;
+    entityTypeKey: string;
+    counts: CataloxXmemoryEntitySurfaceCounts;
+    /** Present when {@link RunCataloxXmemoryEntityCountReportOptions.matrix} was passed. */
+    matrix?: CataloxXmemoryEntityMatrixSlice;
+    error?: string;
+};
+export type CataloxXmemoryEntityCountReport = {
+    kind: 'catalox-xmemory-entity-counts';
+    generatedAt: string;
+    namespace: string;
+    /** Comma-separated when multiple catalogs; {@link SCOPED_DATA_TIER_ENTITY_DISCOVERY_CATALOG_ID} for tier discovery. */
+    entityCatalogId: string;
+    context: CataloxContext;
+    mongo: {
+        opDb: string;
+        thingsDb: string;
+        scopedDataCollection: string;
+        viewsCollection: string;
+        snapshotsCollection: string;
+    };
+    catalogList: {
+        outcome: string;
+        error?: string;
+        itemCount: number;
+    };
+    /** Set when matrix counts were requested (see {@link RunCataloxXmemoryEntityCountReportOptions.matrix}). */
+    executionMatrix?: {
+        matrixCatalogId: string;
+        matrixRunId?: string;
+        mongoDb?: string;
+    };
+    /** Present for {@link runScopedDataEntityTypeDiscoveryReport} when tier statistics were used to list types. */
+    tierDiscoveryDiagnostics?: TierDiscoveryDiagnostics;
+    entities: CataloxXmemoryEntityCountRow[];
+};
+/**
+ * Parse a comma-separated list of Mongo field paths for **`groupByPaths.scoped_data`**.
+ * Paths without a leading **`$`** get **`$`** prefixed (e.g. **`data.entityType`** → **`$data.entityType`**).
+ */
+export declare function parseTierDiscoveryGroupPathsCsv(raw: string | undefined): readonly string[] | undefined;
+/**
+ * Paginates **`getXmemoryTierStatistics`** (`scoped_data` only) with configurable **`groupByPaths`**
+ * until all distinct **`typeKey`** values are collected for **`namespace`**.
+ */
+export declare function collectScopedDataEntityTypeDiscovery(tier: XmemoryDataTier, namespace: string, options?: CollectScopedDataEntityTypeDiscoveryOptions): Promise<ScopedDataTierEntityTypeDiscovery>;
+/** @returns Distinct type keys only — use {@link collectScopedDataEntityTypeDiscovery} for diagnostics. */
+export declare function collectScopedDataEntityTypeKeys(tier: XmemoryDataTier, namespace: string, signal?: AbortSignal): Promise<string[]>;
+export type RunCataloxXmemoryEntityCountReportOptions = {
+    context?: Partial<CataloxContext>;
+    pageSize?: number;
+    /**
+     * When set, each entity row includes **execution matrix** row + snapshot counts for that
+     * **`entityTypeKey`** (aligned with {@link fetchMemorixMatrixEntityFacet} / materialized `input.entityType`).
+     */
+    matrix?: {
+        runtime: ExecutionMatrixRuntime;
+        matrixCatalogId: string;
+        matrixRunId?: string;
+        /** Echoed on {@link CataloxXmemoryEntityCountReport.executionMatrix} for operators. */
+        mongoDb?: string;
+    };
+    signal?: AbortSignal;
+    /** Override **`groupByPaths.scoped_data`** for {@link runScopedDataEntityTypeDiscoveryReport} / {@link collectScopedDataEntityTypeDiscovery}. */
+    discoveryGroupByPathsScopedData?: readonly string[];
+    /**
+     * **`extended`**: scoped_data document counts use {@link buildExtendedScopedDataEntityTypeFilter} (nested + top-level).
+     * {@link runScopedDataEntityTypeDiscoveryReport} always uses **`extended`** for scoped_data counts.
+     */
+    scopedDataEntityMatch?: 'default' | 'extended';
+};
+/**
+ * Discovers **entity type keys** from scoped-data tier statistics for **`namespace`**, then emits the same
+ * per-type surface counts (and optional matrix slice) as {@link runCataloxXmemoryEntityCountReport}.
+ * Does **not** call Catalox.
+ */
+export declare function runScopedDataEntityTypeDiscoveryReport(tier: XmemoryDataTier, namespace: string, options?: RunCataloxXmemoryEntityCountReportOptions): Promise<CataloxXmemoryEntityCountReport>;
+/**
+ * Lists native items across **`catalogIds`**, derives {@link entityTypeKeyFromCatalogItem} per row, then counts
+ * Mongo tier documents per surface for **`namespace`**, and optional **execution matrix** row / snapshot counts.
+ *
+ * **`groupByPaths.scoped_data`** for tier statistics should use the same paths as
+ * **`RECOMMENDED_TIER_STATS_SCOPED_DATA_GROUP_PATHS`** in **`xmemory-op-tier.ts`** so catalog keys align with scoped-data buckets.
+ */
+export declare function runCataloxXmemoryEntityCountReport(catalox: Catalox, tier: XmemoryDataTier, catalogIds: string | readonly string[], namespace: string, options?: RunCataloxXmemoryEntityCountReportOptions): Promise<CataloxXmemoryEntityCountReport>;
+export declare function formatCataloxXmemoryEntityCountMarkdown(report: CataloxXmemoryEntityCountReport): string;
+/** Minimal {@link XmemoryMongoClient} so tier `countMany` reaches op DB collections not registered on opStore. */
+export declare function driverBackedMongoClientForXmemoryCli(driver: MongoClient): XmemoryMongoClient;
+//# sourceMappingURL=catalox-xmemory-entity-count-report.d.ts.map

package/dist/catalox-inventory/catalox-xmemory-entity-count-report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalox-xmemory-entity-count-report.d.ts","sourceRoot":"","sources":["../../src/catalox-inventory/catalox-xmemory-entity-count-report.ts"],"names":[],"mappings":"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"}

package/dist/catalox-inventory/catalox-xmemory-entity-count-report.js

@@ -0,0 +1,477 @@
+import { buildTierFetchMatch, countScopedDataDocuments, ENTITY_TYPES_LIMIT_MAX, getMemorixTierStatistics, TIER_STATS_MISSING_TYPE, } from '../execution-matrix/memorix-tier-statistics.js';
+import { buildMatrixRowEntityTypeExtraFilter } from '../execution-matrix/memorix-entity-type-helpers.js';
+import { buildMatrixRowReadFilter } from '../execution-matrix/runtime-store.js';
+import { countXmemoryOpCollectionDocuments } from '../execution-matrix/xmemory-op-tier.js';
+const DEFAULT_PAGE = 200;
+/** `entityCatalogId` / row **`catalogId`** when types come from tier statistics, not a Catalox catalog. */
+export const SCOPED_DATA_TIER_ENTITY_DISCOVERY_CATALOG_ID = '__scoped_data_tier__';
+/**
+ * Default **`groupByPaths.scoped_data`** for tier discovery — broader than **`DEFAULT_ENTITY_TYPE_PATHS.scoped_data`**
+ * so rows that only store the discriminator under **`data.*`** / **`metadata.*`** still bucket into real type keys.
+ */
+export const DEFAULT_ENTITY_DISCOVERY_SCOPED_DATA_GROUP_PATHS = [
+    '$entityType',
+    '$entity_type',
+    '$data.entityType',
+    '$data.entity_type',
+    '$metadata.entityType',
+    '$metadata.entity_type',
+];
+/** `$match` fragment: any of the common scoped-data locations equals **`entityTypeKey`**. */
+export function buildExtendedScopedDataEntityTypeFilter(entityTypeKey) {
+    return {
+        $or: [
+            { entityType: entityTypeKey },
+            { entity_type: entityTypeKey },
+            { 'data.entityType': entityTypeKey },
+            { 'data.entity_type': entityTypeKey },
+            { 'metadata.entityType': entityTypeKey },
+            { 'metadata.entity_type': entityTypeKey },
+        ],
+    };
+}
+function readDataString(data, key) {
+    if (!data || typeof data !== 'object' || Array.isArray(data))
+        return undefined;
+    const v = data[key];
+    return typeof v === 'string' && v.trim() ? v.trim() : undefined;
+}
+/** Normalize one or many catalog ids: trim, drop empties, preserve first-seen order. */
+export function normalizeEntityReportCatalogIds(catalogIds) {
+    const raw = typeof catalogIds === 'string' ? [catalogIds] : [...catalogIds];
+    const out = [];
+    const seen = new Set();
+    for (const r of raw) {
+        const t = String(r ?? '').trim();
+        if (!t || seen.has(t))
+            continue;
+        seen.add(t);
+        out.push(t);
+    }
+    return out;
+}
+/**
+ * Resolves the xmemory **entity type key** for a Catalox native row (used as `entityTypeKey` in tier match).
+ * Order: explicit `data.*` fields, then **`itemId`** (common when each row is one entity slug).
+ */
+export function entityTypeKeyFromCatalogItem(item) {
+    const d = item.data;
+    return (readDataString(d, 'entityType') ??
+        readDataString(d, 'typeKey') ??
+        readDataString(d, 'memorixEntityType') ??
+        readDataString(d, 'memorixEntityName') ??
+        readDataString(d, 'thingType') ??
+        readDataString(d, 'xmemoryEntityType') ??
+        (typeof item.itemId === 'string' && item.itemId.trim() ? item.itemId.trim() : undefined));
+}
+async function countSurfacesForEntityType(tier, namespace, entityTypeKey, scopedDataMatch = 'default') {
+    const scopedScope = scopedDataMatch === 'extended'
+        ? { namespace, extraMatch: buildExtendedScopedDataEntityTypeFilter(entityTypeKey) }
+        : { namespace, entityTypeKey };
+    const facetScope = { namespace, entityTypeKey };
+    const thingsCol = tier.corpusStore.collection(tier.env.thingsCollection);
+    const viewsCol = tier.opStore.collection(tier.env.viewsCollection);
+    const [scopedData, things, scopedViews, snapshots] = await Promise.all([
+        countScopedDataDocuments(tier, scopedScope, {}),
+        thingsCol.countMatching(buildTierFetchMatch(facetScope, 'things')),
+        viewsCol.countMatching(buildTierFetchMatch(facetScope, 'scoped_views')),
+        countXmemoryOpCollectionDocuments(tier, tier.env.snapshotsCollection, buildTierFetchMatch(facetScope, 'snapshots')),
+    ]);
+    return { scopedData, things, scopedViews, snapshots };
+}
+async function countMatrixForEntityType(runtime, matrixCatalogId, matrixRunId, entityTypeKey) {
+    const rowFilter = buildMatrixRowReadFilter(matrixCatalogId, matrixRunId, undefined, undefined, buildMatrixRowEntityTypeExtraFilter(entityTypeKey));
+    const [rows, snapshots] = await Promise.all([
+        runtime.countRowsMatching(rowFilter),
+        runtime.countSnapshots({ matrixCatalogId, matrixRunId, entityType: entityTypeKey }),
+    ]);
+    return { rows, snapshots };
+}
+/**
+ * Parse a comma-separated list of Mongo field paths for **`groupByPaths.scoped_data`**.
+ * Paths without a leading **`$`** get **`$`** prefixed (e.g. **`data.entityType`** → **`$data.entityType`**).
+ */
+export function parseTierDiscoveryGroupPathsCsv(raw) {
+    if (!raw?.trim())
+        return undefined;
+    return raw
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .map((p) => (p.startsWith('$') ? p : `$${p}`));
+}
+/**
+ * Paginates **`getXmemoryTierStatistics`** (`scoped_data` only) with configurable **`groupByPaths`**
+ * until all distinct **`typeKey`** values are collected for **`namespace`**.
+ */
+export async function collectScopedDataEntityTypeDiscovery(tier, namespace, options) {
+    const paths = options?.groupByPathsScopedData && options.groupByPathsScopedData.length > 0
+        ? options.groupByPathsScopedData
+        : DEFAULT_ENTITY_DISCOVERY_SCOPED_DATA_GROUP_PATHS;
+    const keys = new Set();
+    let missingBucketDocCount = 0;
+    let scopedDataMatchedTotal = 0;
+    let skip = 0;
+    const limit = ENTITY_TYPES_LIMIT_MAX;
+    for (;;) {
+        const stats = await getMemorixTierStatistics(tier, {
+            namespace,
+            entityTypesSkip: skip,
+            entityTypesLimit: limit,
+            surfaces: ['scoped_data'],
+            groupByPaths: { scoped_data: [...paths] },
+            force: true,
+            signal: options?.signal,
+        });
+        const sec = stats.scopedData;
+        if (skip === 0)
+            scopedDataMatchedTotal = sec.matchedDocTotal;
+        for (const e of sec.entityTypes) {
+            const k = String(e.typeKey ?? '');
+            if (!k)
+                continue;
+            if (k === TIER_STATS_MISSING_TYPE) {
+                missingBucketDocCount = Math.max(missingBucketDocCount, e.docCount ?? 0);
+            }
+            else {
+                keys.add(k);
+            }
+        }
+        if (!sec.entityTypesHasMore)
+            break;
+        skip += limit;
+    }
+    return {
+        keys: [...keys].sort((a, b) => a.localeCompare(b)),
+        scopedDataMatchedTotal,
+        missingBucketDocCount,
+        groupByPathsUsed: paths,
+    };
+}
+/** @returns Distinct type keys only — use {@link collectScopedDataEntityTypeDiscovery} for diagnostics. */
+export async function collectScopedDataEntityTypeKeys(tier, namespace, signal) {
+    const d = await collectScopedDataEntityTypeDiscovery(tier, namespace, { signal });
+    return d.keys;
+}
+async function appendCountsForEntityTypeKey(entityTypeKey, catalogId, itemId, tier, namespace, matrixOpt, scopedDataMatch) {
+    try {
+        const counts = await countSurfacesForEntityType(tier, namespace, entityTypeKey, scopedDataMatch);
+        let matrixSlice;
+        if (matrixOpt !== undefined) {
+            try {
+                const { rows, snapshots } = await countMatrixForEntityType(matrixOpt.runtime, matrixOpt.matrixCatalogId, matrixOpt.matrixRunId, entityTypeKey);
+                matrixSlice = {
+                    matrixCatalogId: matrixOpt.matrixCatalogId,
+                    ...(matrixOpt.matrixRunId ? { matrixRunId: matrixOpt.matrixRunId } : {}),
+                    rows,
+                    snapshots,
+                };
+            }
+            catch (me) {
+                matrixSlice = {
+                    matrixCatalogId: matrixOpt.matrixCatalogId,
+                    ...(matrixOpt.matrixRunId ? { matrixRunId: matrixOpt.matrixRunId } : {}),
+                    rows: 0,
+                    snapshots: 0,
+                    error: me instanceof Error ? me.message : String(me),
+                };
+            }
+        }
+        return {
+            catalogId,
+            itemId,
+            entityTypeKey,
+            counts,
+            ...(matrixSlice !== undefined ? { matrix: matrixSlice } : {}),
+        };
+    }
+    catch (e) {
+        return {
+            catalogId,
+            itemId,
+            entityTypeKey,
+            counts: { scopedData: 0, things: 0, scopedViews: 0, snapshots: 0 },
+            error: e instanceof Error ? e.message : String(e),
+        };
+    }
+}
+/**
+ * Discovers **entity type keys** from scoped-data tier statistics for **`namespace`**, then emits the same
+ * per-type surface counts (and optional matrix slice) as {@link runCataloxXmemoryEntityCountReport}.
+ * Does **not** call Catalox.
+ */
+export async function runScopedDataEntityTypeDiscoveryReport(tier, namespace, options) {
+    const matrixOpt = options?.matrix;
+    const executionMatrixMeta = matrixOpt !== undefined
+        ? {
+            matrixCatalogId: matrixOpt.matrixCatalogId,
+            ...(matrixOpt.matrixRunId ? { matrixRunId: matrixOpt.matrixRunId } : {}),
+            ...(matrixOpt.mongoDb ? { mongoDb: matrixOpt.mongoDb } : {}),
+        }
+        : undefined;
+    const discoveryPaths = options?.discoveryGroupByPathsScopedData;
+    const disc = await collectScopedDataEntityTypeDiscovery(tier, namespace, {
+        signal: options?.signal,
+        ...(discoveryPaths?.length ? { groupByPathsScopedData: discoveryPaths } : {}),
+    });
+    let emptyKeysHint;
+    if (disc.keys.length === 0 && disc.scopedDataMatchedTotal === 0) {
+        emptyKeysHint =
+            'No scoped_data documents matched this namespace (verify namespace spelling, MONGO_URI, op DB, and SCOPED_DATA_COLLECTION / X_SCOPED_DATA_COLLECTION).';
+    }
+    else if (disc.keys.length === 0 && disc.missingBucketDocCount > 0) {
+        emptyKeysHint =
+            'Scoped_data rows exist for this namespace, but every document fell into the __missing__ bucket for the configured group paths — set --entity-discovery-group-paths or XMEMORY_ENTITY_DISCOVERY_GROUP_PATHS to match your document shape.';
+    }
+    else if (disc.keys.length === 0) {
+        emptyKeysHint =
+            'Scoped_data matched the namespace but no typed entity buckets were returned — inspect tier statistics vs document fields.';
+    }
+    const tierDiscoveryDiagnostics = {
+        ...disc,
+        ...(emptyKeysHint ? { emptyKeysHint } : {}),
+    };
+    const entities = [];
+    for (const entityTypeKey of disc.keys) {
+        entities.push(await appendCountsForEntityTypeKey(entityTypeKey, SCOPED_DATA_TIER_ENTITY_DISCOVERY_CATALOG_ID, entityTypeKey, tier, namespace, matrixOpt, 'extended'));
+    }
+    const env = tier.env;
+    return {
+        kind: 'catalox-xmemory-entity-counts',
+        generatedAt: new Date().toISOString(),
+        namespace,
+        entityCatalogId: SCOPED_DATA_TIER_ENTITY_DISCOVERY_CATALOG_ID,
+        context: {
+            superAdmin: true,
+            userId: 'exellix-runtime-scoped-data-entity-discovery',
+            actor: { type: 'system', id: '@exellix/exellix-runtime' },
+            ...options?.context,
+        },
+        mongo: {
+            opDb: env.opDb,
+            thingsDb: env.thingsDb,
+            scopedDataCollection: env.scopedDataCollection,
+            viewsCollection: env.viewsCollection,
+            snapshotsCollection: env.snapshotsCollection,
+        },
+        catalogList: {
+            outcome: 'scoped_data_tier_entity_types',
+            itemCount: disc.keys.length,
+        },
+        ...(executionMatrixMeta !== undefined ? { executionMatrix: executionMatrixMeta } : {}),
+        tierDiscoveryDiagnostics,
+        entities,
+    };
+}
+/**
+ * Lists native items across **`catalogIds`**, derives {@link entityTypeKeyFromCatalogItem} per row, then counts
+ * Mongo tier documents per surface for **`namespace`**, and optional **execution matrix** row / snapshot counts.
+ *
+ * **`groupByPaths.scoped_data`** for tier statistics should use the same paths as
+ * **`RECOMMENDED_TIER_STATS_SCOPED_DATA_GROUP_PATHS`** in **`xmemory-op-tier.ts`** so catalog keys align with scoped-data buckets.
+ */
+export async function runCataloxXmemoryEntityCountReport(catalox, tier, catalogIds, namespace, options) {
+    const ids = normalizeEntityReportCatalogIds(catalogIds);
+    if (ids.length === 0) {
+        throw new Error('runCataloxXmemoryEntityCountReport: at least one non-empty catalog id is required');
+    }
+    const ctx = {
+        superAdmin: true,
+        userId: 'exellix-runtime-catalox-xmemory-entity-counts',
+        actor: { type: 'system', id: '@exellix/exellix-runtime' },
+        ...options?.context,
+    };
+    const pageSize = Math.max(50, Math.min(options?.pageSize ?? DEFAULT_PAGE, 2000));
+    const matrixOpt = options?.matrix;
+    const executionMatrixMeta = matrixOpt !== undefined
+        ? {
+            matrixCatalogId: matrixOpt.matrixCatalogId,
+            ...(matrixOpt.matrixRunId ? { matrixRunId: matrixOpt.matrixRunId } : {}),
+            ...(matrixOpt.mongoDb ? { mongoDb: matrixOpt.mongoDb } : {}),
+        }
+        : undefined;
+    const rows = [];
+    let listOutcome = 'ok';
+    let listError;
+    outer: for (const catalogId of ids) {
+        let offset = 0;
+        for (;;) {
+            try {
+                const page = await catalox.listCatalogItems(ctx, catalogId, {
+                    limit: pageSize,
+                    offset,
+                    scope: { superAdmin: true },
+                });
+                if (page.listOutcome !== 'ok') {
+                    listOutcome = page.listOutcome;
+                    listError = `${catalogId}: ${page.issues?.map((i) => `${i.severity ?? ''}:${JSON.stringify(i)}`).join('; ') ?? 'list failed'}`;
+                    break outer;
+                }
+                for (const item of page.items)
+                    rows.push({ item, sourceCatalogId: catalogId });
+                if (page.items.length < pageSize)
+                    break;
+                offset += page.items.length;
+            }
+            catch (e) {
+                listError = `${catalogId}: ${e instanceof Error ? e.message : String(e)}`;
+                listOutcome = 'error';
+                break outer;
+            }
+        }
+    }
+    const entities = [];
+    for (const { item, sourceCatalogId } of rows) {
+        const entityTypeKey = entityTypeKeyFromCatalogItem(item);
+        if (!entityTypeKey) {
+            entities.push({
+                catalogId: sourceCatalogId,
+                itemId: item.itemId,
+                entityTypeKey: '',
+                counts: { scopedData: 0, things: 0, scopedViews: 0, snapshots: 0 },
+                error: 'no_entity_type_key (set data.entityType or similar, or use itemId as the type slug)',
+            });
+            continue;
+        }
+        entities.push(await appendCountsForEntityTypeKey(entityTypeKey, sourceCatalogId, item.itemId, tier, namespace, matrixOpt, options?.scopedDataEntityMatch ?? 'default'));
+    }
+    const env = tier.env;
+    return {
+        kind: 'catalox-xmemory-entity-counts',
+        generatedAt: new Date().toISOString(),
+        namespace,
+        entityCatalogId: ids.join(','),
+        context: ctx,
+        mongo: {
+            opDb: env.opDb,
+            thingsDb: env.thingsDb,
+            scopedDataCollection: env.scopedDataCollection,
+            viewsCollection: env.viewsCollection,
+            snapshotsCollection: env.snapshotsCollection,
+        },
+        catalogList: { outcome: listOutcome, ...(listError ? { error: listError } : {}), itemCount: rows.length },
+        ...(executionMatrixMeta !== undefined ? { executionMatrix: executionMatrixMeta } : {}),
+        entities,
+    };
+}
+export function formatCataloxXmemoryEntityCountMarkdown(report) {
+    const em = report.executionMatrix;
+    const isTierDiscovery = report.entityCatalogId === SCOPED_DATA_TIER_ENTITY_DISCOVERY_CATALOG_ID;
+    const title = isTierDiscovery
+        ? '# xmemory: scoped-data entity types → surface counts'
+        : '# Catalox → xmemory entity counts';
+    const catalogLabel = isTierDiscovery
+        ? `**Discovery:** scoped-data tier (\`${SCOPED_DATA_TIER_ENTITY_DISCOVERY_CATALOG_ID}\`)`
+        : `**Entity catalog(s):** \`${report.entityCatalogId}\``;
+    const lines = [
+        title,
+        '',
+        `- **Generated:** ${report.generatedAt}`,
+        `- **Namespace:** ${report.namespace}`,
+        `- ${catalogLabel}`,
+        `- **Catalog / discovery list:** ${report.catalogList.outcome} (${report.catalogList.itemCount} rows)`,
+        `- **Mongo:** opDb \`${report.mongo.opDb}\` · scopedData \`${report.mongo.scopedDataCollection}\` · views \`${report.mongo.viewsCollection}\` · snapshots \`${report.mongo.snapshotsCollection}\` · thingsDb \`${report.mongo.thingsDb}\``,
+        ...(isTierDiscovery
+            ? [
+                '',
+                `_Entity type keys come from \`getXmemoryTierStatistics\` (\`scoped_data\` only) with broader default \`groupByPaths.scoped_data\` than stock tier stats so nested \`data.*\` / \`metadata.*\` discriminators still bucket. Paginated at \`${ENTITY_TYPES_LIMIT_MAX}\` types per page. Per-row **scopedData** counts use \`buildExtendedScopedDataEntityTypeFilter\`; things / views / snapshots still match top-level \`entityTypeKey\`._`,
+            ]
+            : []),
+        ...(report.tierDiscoveryDiagnostics
+            ? [
+                '',
+                '### Tier discovery diagnostics',
+                '',
+                `- **scopedDataMatchedTotal:** ${report.tierDiscoveryDiagnostics.scopedDataMatchedTotal}`,
+                `- **missingBucketDocCount (\`__missing__\`):** ${report.tierDiscoveryDiagnostics.missingBucketDocCount}`,
+                `- **groupByPathsUsed:** ${report.tierDiscoveryDiagnostics.groupByPathsUsed.map((p) => `\`${p}\``).join(', ')}`,
+                ...(report.tierDiscoveryDiagnostics.emptyKeysHint
+                    ? ['', `_**Hint:** ${report.tierDiscoveryDiagnostics.emptyKeysHint}_`]
+                    : []),
+            ]
+            : []),
+        ...(em
+            ? [
+                '',
+                `### Execution matrix`,
+                '',
+                `- **matrixCatalogId:** \`${em.matrixCatalogId}\`${em.matrixRunId ? ` · **matrixRunId:** \`${em.matrixRunId}\`` : ''}${em.mongoDb ? ` · **DB:** \`${em.mongoDb}\`` : ''}`,
+            ]
+            : []),
+        '',
+        em
+            ? '| itemId | entityTypeKey | scopedData | things | scopedViews | snapshots | matrixRows | matrixSnapshots |'
+            : '| itemId | entityTypeKey | scopedData | things | scopedViews | snapshots |',
+        em
+            ? '|--------|---------------|------------:|------:|-------------:|----------:|-------------:|----------------:|'
+            : '|--------|---------------|------------:|------:|-------------:|----------:|',
+    ];
+    for (const r of report.entities) {
+        const c = r.counts;
+        const err = r.error ? ` ⚠ ${r.error}` : '';
+        const m = r.matrix;
+        const mErr = m?.error ? ` ⚠ ${m.error}` : '';
+        if (em) {
+            lines.push(`| ${r.itemId} | ${r.entityTypeKey || '—'} | ${c.scopedData} | ${c.things} | ${c.scopedViews} | ${c.snapshots} | ${m?.rows ?? '—'} | ${m?.snapshots ?? '—'} |${err}${mErr}`);
+        }
+        else {
+            lines.push(`| ${r.itemId} | ${r.entityTypeKey || '—'} | ${c.scopedData} | ${c.things} | ${c.scopedViews} | ${c.snapshots} |${err}`);
+        }
+    }
+    return lines.join('\n');
+}
+/** Minimal {@link XmemoryMongoClient} so tier `countMany` reaches op DB collections not registered on opStore. */
+export function driverBackedMongoClientForXmemoryCli(driver) {
+    return {
+        findById: async ({ database, collection, id, idField, projection }) => {
+            const field = idField ?? '_id';
+            return driver.db(database).collection(collection).findOne({ [field]: id }, {
+                projection,
+            });
+        },
+        findMany: async ({ database, collection, filter, projection, limit, skip }) => {
+            let cur = driver.db(database).collection(collection).find(filter ?? {}, { projection });
+            if (skip !== undefined)
+                cur = cur.skip(skip);
+            if (limit !== undefined)
+                cur = cur.limit(limit);
+            return cur.toArray();
+        },
+        countMany: async ({ database, collection, filter }) => {
+            return driver.db(database).collection(collection).countDocuments(filter ?? {});
+        },
+        upsertOne: async ({ database, collection, filter, set, setOnInsert }) => {
+            const col = driver.db(database).collection(collection);
+            const r = await col.updateOne(filter, { $set: set, ...(setOnInsert && Object.keys(setOnInsert).length > 0 ? { $setOnInsert: setOnInsert } : {}) }, { upsert: true });
+            return {
+                matchedCount: r.matchedCount,
+                modifiedCount: r.modifiedCount,
+                upsertedCount: r.upsertedCount ?? 0,
+            };
+        },
+        findOne: async ({ database, collection, filter, projection }) => {
+            return driver.db(database).collection(collection).findOne(filter ?? {}, { projection });
+        },
+        createIndex: async ({ database, collection, spec, options }) => {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            await driver.db(database).collection(collection).createIndex(spec, options);
+        },
+        updateOne: async ({ database, collection, filter, update, options }) => {
+            const r = await driver.db(database).collection(collection).updateOne(filter, update, options);
+            return {
+                matchedCount: r.matchedCount,
+                modifiedCount: r.modifiedCount,
+                upsertedCount: r.upsertedCount,
+            };
+        },
+        updateMany: async ({ database, collection, filter, update }) => {
+            const r = await driver.db(database).collection(collection).updateMany(filter, update);
+            return { matchedCount: r.matchedCount, modifiedCount: r.modifiedCount };
+        },
+        deleteOne: async ({ database, collection, filter }) => {
+            const r = await driver.db(database).collection(collection).deleteOne(filter);
+            return { deletedCount: r.deletedCount };
+        },
+    };
+}
+//# sourceMappingURL=catalox-xmemory-entity-count-report.js.map