@x12i/memorix-retrieval 1.5.1 → 1.6.2

package/docs/XRONOX-DATA-TIER-REQUIREMENTS.md

@@ -2,13 +2,14 @@
 
 **Audience:** `@x12i/xronox` maintainers  
 **Consumer:** `@x12i/memorix-retrieval` (v1.5+) and hosts (Memorix Explorer, APIs, tools)  
-**Status:** Draft — retrieval has migrated to Xronox as the default data tier; several gaps are shimmed in `memorix-retrieval` until Xronox ships native support.
+**Status:** Active — open FRs in [`docs/fr/`](./fr/README.md). **No Mongo workarounds in production paths.**
 
 Related docs:
 
 - [DATA-TIER-CONTRACT.md](./DATA-TIER-CONTRACT.md) — public retrieval API
 - [MEMORIX-DATABASE-CONVENTIONS.md](./MEMORIX-DATABASE-CONVENTIONS.md) — Mongo layout and env vars
 - [MEMORIX-CATALOX-CONTRACTS.md](./MEMORIX-CATALOX-CONTRACTS.md) — descriptor metadata (Catalox, not Xronox)
+- **[Feature requests for `@x12i/xronox`](./fr/README.md)** — implement here first; retrieval waits
 
 ---
 
@@ -22,7 +23,7 @@ Memorix separates **metadata** from **payload**:
 | Payload | **Xronox** | Routed Mongo reads/counts by role + collection |
 | Composition | **memorix-retrieval** | Join descriptors + Xronox I/O → list/item rows |
 
-Hosts must **not** connect to Mongo directly. Retrieval’s default bootstrap is:
+Hosts must **not** connect to Mongo directly in production. Retrieval’s default bootstrap is:
 
 ```ts
 createMemorixRetrievalFromEnv({ catalox })
@@ -30,7 +31,7 @@ createMemorixRetrievalFromEnv({ catalox })
   → createMemorixXronoxAdapter(createXronox())
 ```
 
-All list/item/workspace reads and counts should flow through Xronox routing — same pattern as `@x12i/memorix-writer` and other x12i data-tier peers.
+All list/item/workspace reads and counts flow through Xronox routing.
 
 ---
 
@@ -45,391 +46,87 @@ Every Memorix Mongo read uses this Xronox routing shape:
   dataType: "metadata",
   sourceType: "database",
   subSourceType: "mongo",
-  role: "<xronox-role>",      // see §3
-  source: "<collection-name>", // e.g. assets-snapshots, vulnerabilities-snapshots
+  role: "<xronox-role>",
+  source: "<collection-name>",
   query?: Record<string, unknown>,
   project?: string[],
   sort?: string | string[] | Record<string, 1 | -1>,
   limit?: number,
-  skip?: number,              // ⚠️ passed by retrieval; not implemented in Xronox 3.7 — see §4.2
+  skip?: number,
 }
 ```
 
-Collection names and queries come from **Catalox entity descriptors** (not hardcoded in retrieval). Xronox resolves **which Mongo database** to use from `role`.
-
 ### 2.2 Role mapping (Memorix target → Xronox role)
 
-Entity descriptors declare `target`:
-
 | Entity descriptor `target` | Memorix database (logical) | Default Xronox `role` (3.8+) |
 |--------------------------|----------------------------|------------------------------|
 | `"entity"` (default) | `memorix-entities` | `memorix_entities` |
 | `"event"` | `memorix-events` | `memorix_events` |
 
-Legacy aliases still work in Xronox: `operational` / `logs`. Prefer `memorix_entities` / `memorix_events` — they map to `memory.entities` / `memory.events` with defaults `memorix-entities` / `memorix-events`.
-
-Override per client: `createMemorixRetrieval({ xronoxRoles: { entity: "…", event: "…" } })`.
-
 Constants in retrieval: `DEFAULT_MEMORIX_XRONOX_ROLES` (`src/data/memorix-read.ts`).
 
-### 2.3 Bootstrap (zero-config)
-
-Retrieval initializes Xronox as:
-
-```ts
-await xronox.init({
-  engine: "nxMongo",
-  zeroConfig: true,
-  lazyInit: true,
-  envFile: false, // host already loaded .env
-});
-```
-
-**Required env (minimum):**
-
-| Variable | Purpose |
-|----------|---------|
-| `MONGO_URI` | Cluster connection (aliases: `MONGO_URL`, `XRONOX_MONGO_URI`) |
-
-**Required for correct entity/event split (recommended explicit):**
-
-| Xronox role | Env (Xronox role resolution) | Should resolve to (Memorix convention) |
-|-------------|------------------------------|----------------------------------------|
-| `operational` | `MONGO_OPERATIONAL_DB` (+ fallbacks) | `memorix-entities` or `MEMORIX_ENTITIES_DB` |
-| `logs` | `MONGO_LOGS_DB` (+ fallbacks) | `memorix-events` or `MEMORIX_EVENTS_DB` |
-
-> **Gap:** Memorix documents `MEMORIX_ENTITIES_DB` / `MEMORIX_EVENTS_DB`; Xronox zero-config defaults to `MONGO_DB` / role vars. Deployments must align both naming schemes until Xronox ships a Memorix preset (§4.6).
-
-### 2.4 Operations retrieval performs via Xronox
-
-| Operation | Retrieval API | Xronox usage | Frequency |
-|-----------|---------------|--------------|-----------|
-| Paginated list driver read | `fetchMemorixList` | `read` / `readArray` | High |
-| Extension batch fetch | `fetchMemorixList` | `read` / `readArray` by id `$in` | High |
-| Item detail fetch | `fetchMemorixItem` | `read` / `readArray` | Medium |
-| List total (`includeTotal`) | `fetchMemorixList` | **count** (shimmed today) | Medium |
-| Entity graph counts | `buildMemorixEntityGraph` | **count** per content type | Medium |
-| Raw explorer reads | `listMemorixEntityContentTypeDocuments` | `read` + **count** | Medium |
-| Scoped workspace (legacy) | `listScopedWorkspaceDocuments` | `read` + **count** | Low |
-| Health check | `getMemorixRetrievalHealth` | `selfTest({ testConnectivity: true })` | Low |
-
-Retrieval does **not** write to Mongo via Xronox (writes are `@x12i/memorix-writer` / completion pipelines).
-
----
-
-## 3. What works in Xronox 3.7.3 (used today)
-
-| Capability | Xronox API | Memorix usage |
-|------------|------------|---------------|
-| Routed Mongo read | `read` / `readArray` | All document fetches |
-| Single document | `readOne` | Not used yet; candidate for `getMemorixEntityContentTypeDocument` |
-| Connectivity check | `selfTest({ testConnectivity })` | Health endpoint |
-| Zero-config init | `init({ engine: "nxMongo", zeroConfig: true })` | Default bootstrap |
-| Role-based DB routing | `role` on `ReadParams` | Entity vs event databases |
-| Collection as `source` | `source: string` | Descriptor-resolved collection name |
-| Mongo filter query | `query` | List filters + searchText |
-| Field projection | `project: string[]` | List field composition |
-| Sort (string form) | `sort: string \| string[]` | List sort (adapter converts `{ path: 1 \| -1 }`) |
-| Limit | `limit` | Pagination page size |
-
----
-
-## 4. Gaps — what we need from Xronox
-
-Priority: **P0** = blocks correct production behavior; **P1** = performance/ergonomics; **P2** = nice-to-have.
-
-### 4.1 P0 — Native `countDocuments` (routed)
-
-**Problem:** Xronox 3.7 has no public count API. Retrieval shims counts by loading all matching `_id` values through `readArray`:
-
-```ts
-// memorix-retrieval/src/client/xronox-adapter.ts (interim)
-countDocuments(params) {
-  const rows = await readArray({ ...params, project: ["_id"], limit: undefined });
-  return rows.length;
-}
-```
-
-This breaks down on large collections (assets, vulnerabilities) when hosts use `includeTotal: true` or graph counts.
-
-**Request:** Add to `Xronox` interface:
-
-```ts
-countDocuments(params: CountParams): Promise<number>;
-
-type CountParams = RoutingKey & {
-  subSourceType: "mongo";
-  source: string;
-  role?: string;
-  query?: Record<string, unknown>;
-  /** Optional — default false. When true, use estimatedDocumentCount (no filter). */
-  estimated?: boolean;
-};
-```
-
-**Semantics:**
-
-- Same binding resolution as `read` (role → connection → db → collection).
-- Uses Mongo `countDocuments(query)` — **not** a full collection scan.
-- Must respect `query` identically to `read`.
-- Return type: `number` (throws on routing/connection errors, same as read).
-
-**Acceptance:**
-
-- `countDocuments` with filter matches Mongo shell `countDocuments` on the resolved collection.
-- Works for both `role: operational` and `role: logs` in a two-DB Memorix deployment.
-- Documented in Xronox README + `.env.example`.
-
----
-
-### 4.2 P0 — `skip` (offset pagination)
-
-**Problem:** Retrieval passes `skip` on every paginated list read (`page.offset`). Xronox `ReadParams` and `nxMongoEngine.readMongo` **do not forward `skip`** to the driver (verified in `@x12i/xronox@3.7.3`). Offset pagination silently returns wrong pages when using the Xronox data tier.
-
-**Request:** Add to `ReadParams`:
-
-```ts
-skip?: number;
-```
-
-**Engine behavior:** Pass through to Mongo cursor `.skip(skip).limit(limit)`.
-
-**Acceptance:**
-
-- `readArray({ ..., query, sort, skip: 50, limit: 25 })` returns items 51–75.
-- Matches retrieval `fetchMemorixList` pagination tests against direct Mongo.
-
----
-
-### 4.3 P1 — `sort` as Mongo object
-
-**Problem:** Retrieval builds sort as `Record<string, 1 | -1>` (Mongo native). Xronox `ReadParams.sort` is typed as `string | string[]` only. Retrieval converts in an adapter:
-
-```ts
-{ "data.ip_address": 1 } → ["data.ip_address"]
-{ "data.priorityScore": -1 } → ["-data.priorityScore"]
-```
-
-**Request:** Extend `ReadParams.sort`:
-
-```ts
-sort?: string | string[] | Record<string, 1 | -1>;
-```
-
-**Acceptance:** Nested field paths (e.g. `data.xdr.host_name`) sort correctly.
-
----
-
-### 4.4 P1 — Typed errors for routing failures
-
-**Problem:** Hosts need to distinguish misconfiguration from empty results.
-
-**Request:** Stable error codes (or `ErrorCodes` enum) for:
-
-| Code | When |
-|------|------|
-| `ROUTING_NOT_FOUND` | No binding for role + subSourceType |
-| `CONNECTION_NOT_FOUND` | Binding references missing connection alias |
-| `DATABASE_NOT_RESOLVED` | Role/env missing DB name |
-| `COLLECTION_NOT_FOUND` | Optional — collection absent (may be empty vs error) |
+### 2.3 Operations retrieval performs via Xronox
 
-Retrieval maps these to `MemorixRetrievalError` where appropriate.
+| Operation | Retrieval API | Xronox usage | Blocked? |
+|-----------|---------------|--------------|----------|
+| Paginated list | `fetchMemorixList` | `read` / `readArray` | — |
+| List total | `fetchMemorixList` | `countDocuments` | — |
+| Entity graph counts | `buildMemorixEntityGraph` | `countDocuments` per content type | — |
+| **Collection inventory scan** | `buildMemorixCollectionInventory` | **`listCollections` + `countDocuments`** | — (3.9.0+) |
+| Raw explorer reads | `listMemorixEntityContentTypeDocuments` | `read` + `countDocuments` | — |
+| Health | `getMemorixRetrievalHealth` | `selfTest` | Partial — [FR](./fr/xronox-fr-per-role-selftest.md) |
 
 ---
 
-### 4.5 P1 — `readOne` alignment for identity fetch
+## 3. Shipped in Xronox (retrieval uses today)
 
-**Problem:** `getMemorixEntityContentTypeDocument` uses `read` + `limit: 1`. Xronox already exposes `readOne`.
-
-**Request:** Document `readOne` for `{ filter, role, source, project }` as the preferred single-doc path. Ensure `readOne` supports the same routing key as `read`.
-
-**Optional retrieval change after Xronox confirms:** switch item/single-doc paths to `readOne`.
-
----
-
-### 4.6 P1 — Memorix deployment preset (env + zero-config)
-
-**Problem:** Two parallel env naming schemes:
-
-- Memorix: `MEMORIX_ENTITIES_DB`, `MEMORIX_EVENTS_DB`
-- Xronox: `MONGO_OPERATIONAL_DB`, `MONGO_LOGS_DB`
-
-**Request (choose one or both):**
-
-**Option A — Env aliases in Xronox role resolution:**
-
-```
-MONGO_OPERATIONAL_DB ← fallback MEMORIX_ENTITIES_DB
-MONGO_LOGS_DB        ← fallback MEMORIX_EVENTS_DB
-```
-
-**Option B — Zero-config preset:**
-
-```ts
-await xronox.init({ engine: "nxMongo", preset: "memorix" });
-```
-
-Preset behavior:
-
-- `operational` → `MEMORIX_ENTITIES_DB` ?? `memorix-entities`
-- `logs` → `MEMORIX_EVENTS_DB` ?? `memorix-events`
-- Single `MONGO_URI` cluster
-
-**Acceptance:** Memorix smoke script works with only `MONGO_URI` + `MEMORIX_*_DB` set (no duplicate Xronox-specific DB vars).
+| Capability | Xronox API | Since |
+|------------|------------|-------|
+| Routed read | `read` / `readArray` | 3.8+ |
+| Routed count | `countDocuments` (incl. `estimated: true`) | 3.8+ |
+| Offset pagination | `skip` + `limit` | 3.8+ |
+| Object sort | `sort: Record<string, 1 \| -1>` | 3.8+ |
+| Role-based DB routing | `role` on params | 3.8+ |
+| Database collection listing | `listCollections({ role, source: "_db" })` | **3.9+** |
+| Connectivity | `selfTest({ testConnectivity })` | 3.8+ |
 
 ---
 
-### 4.7 P2 — `createXronoxFromEnv` helper
+## 4. Open — implement in Xronox (see FRs)
 
-**Problem:** Every host duplicates:
+| Priority | FR | Blocks |
+|----------|-----|--------|
+| P1 | [Memorix env preset](./fr/xronox-fr-memorix-env-preset.md) | `MEMORIX_*_DB`-only zero-config |
+| P2 | [Per-role selfTest](./fr/xronox-fr-per-role-selftest.md) | Health detail for both DBs |
 
-```ts
-const xronox = createXronox();
-await xronox.init({ engine: "nxMongo", zeroConfig: true, lazyInit: true, envFile: false });
-```
+~~P0 listCollections~~ — **shipped 3.9.0**. See [FR](./fr/xronox-fr-list-collections.md).
 
-**Request:** Export from `@x12i/xronox`:
-
-```ts
-createXronoxFromEnv(options?: {
-  preset?: "default" | "memorix";
-  envFile?: string | false;
-  engine?: EngineMode;
-}): Promise<Xronox>;
-```
-
-Retrieval would replace `createMemorixXronoxFromEnv` with a thin wrapper or re-export.
+**Do not** implement these in retrieval with `connectMemorixMongo` or other driver bypasses.
 
 ---
 
-### 4.8 P2 — Per-role `selfTest` detail
-
-**Problem:** Health check runs one `selfTest`. Memorix needs both entity and event DBs reachable.
+## 5. Retrieval policy (no workarounds)
 
-**Request:** Extend `SelfTestResult`:
-
-```ts
-{
-  passed: boolean;
-  roles?: Array<{
-    role: string;
-    db: string;
-    ok: boolean;
-    latencyMs?: number;
-    error?: string;
-  }>;
-}
-```
-
-Optional init flag: `selfTestRoles: ["operational", "logs"]`.
+| Rule | Detail |
+|------|--------|
+| Production I/O | Xronox only |
+| `buildMemorixCollectionInventory` | Uses Xronox `listCollections` + `countDocuments` (requires `@x12i/xronox` ≥ 3.9.0) |
+| Tests | Mock `xronox.listCollections` / inject test `mongo` only in unit tests — not production bootstrap |
+| Explorer host shims | Delete `memorix-explorer/server/collection-inventory.ts` after bumping to retrieval 1.6.1+ |
 
 ---
 
-### 4.9 P2 — Streaming reads for large scans
-
-**Problem:** Cross-entity workspace merge (v1) may fetch many rows per entity. `read` returning `AsyncIterable` exists but `readArray` materializes everything.
-
-**Request:** Document streaming pattern; ensure `countDocuments` never materializes rows. Optional `readStream` alias for clarity.
-
----
-
-## 5. Proposed Xronox surface (summary)
-
-```ts
-interface Xronox {
-  // Existing
-  read(params: ReadParams): Promise<unknown[] | AsyncIterable<unknown>>;
-  readArray(params: ReadParams): Promise<unknown[]>;
-  readOne(params: ReadOneParams): Promise<unknown | null>;
-  selfTest(options?: { testConnectivity?: boolean }): Promise<SelfTestResult>;
-  init(opts: XronoxInitOptions): Promise<void>;
-  close(): Promise<void>;
-
-  // NEW — P0
-  countDocuments(params: CountParams): Promise<number>;
-}
-
-interface ReadParams extends RoutingKey {
-  query?: Record<string, unknown>;
-  project?: string[];
-  sort?: string | string[] | Record<string, 1 | -1>;  // P1
-  limit?: number;
-  skip?: number;                                       // P0
-}
-```
-
----
-
-## 6. Consumer adapter (retrieval side)
-
-Until Xronox ships §4.1–§4.3, retrieval keeps `createMemorixXronoxAdapter` (`src/client/xronox-adapter.ts`):
-
-| Xronox gap | Retrieval shim |
-|------------|----------------|
-| No `countDocuments` | `_id` projection + `readArray` length |
-| No `Record` sort | Convert to `string[]` before `read` |
-| No `skip` | **None** — pagination may be wrong until Xronox fix |
-
-When Xronox releases native APIs, retrieval will:
-
-1. Delegate `countDocuments` directly (remove shim).
-2. Pass `skip` / object `sort` through without conversion.
-3. Drop direct Mongo escape hatch from default path (keep for tests only).
-
----
-
-## 7. Test matrix (acceptance for Xronox PR)
-
-Run against a fixture with:
-
-- DB `memorix-entities`, collection `assets-snapshots`, role `operational`
-- DB `memorix-events`, collection `vulnerabilities-snapshots`, role `logs`
-
-| # | Test | Expected |
-|---|------|----------|
-| 1 | `readArray` with `limit: 10, skip: 0` vs `skip: 10` | Disjoint pages, stable sort |
-| 2 | `countDocuments` with `{}` vs `readArray` length on small set | Equal |
-| 3 | `countDocuments` with filter vs Mongo shell | Equal |
-| 4 | `countDocuments` on 100k+ docs | Completes in O(1) network vs full scan |
-| 5 | Wrong `role` | Typed routing error |
-| 6 | `selfTest` with both roles configured | Both DBs reported |
-
-Retrieval integration test (downstream): `npm run smoke:retrieval -- --workspace-list` with `includeTotal: true`.
-
----
-
-## 8. Version alignment
+## 6. Version alignment
 
 | Package | Current | Notes |
 |---------|---------|-------|
-| `@x12i/memorix-retrieval` | 1.5.x | Default data tier = Xronox |
-| `@x12i/xronox` | ^3.8.0 | Peer dependency; pin after count/skip land |
-
-**Suggested Xronox release:** minor bump (e.g. 3.8.0) with `countDocuments` + `skip` — no breaking changes to existing `read` callers.
-
----
-
-## 9. Out of scope for Xronox
-
-These stay in **Catalox** / **memorix-retrieval**, not Xronox:
-
-- Entity discovery, list columns, field paths, filters allowlist
-- Row composition, multi-match, relations, content objects
-- Cross-entity workspace merge logic
-- Catalox seed / descriptor validation
-
-Xronox should remain a **database routing + I/O layer**, not Memorix-aware.
+| `@x12i/memorix-retrieval` | 1.6.1 | Inventory via Xronox `listCollections` |
+| `@x12i/xronox` | ^3.9.0 | `listCollections` required for inventory |
 
 ---
 
-## 10. References in this repo
+## 7. Out of scope for Xronox
 
-| File | Purpose |
-|------|---------|
-| `src/data/memorix-read.ts` | Read routing + role resolution |
-| `src/data/memorix-count.ts` | Count entry point |
-| `src/client/xronox-adapter.ts` | Interim shims |
-| `src/client/create-xronox-from-env.ts` | Bootstrap |
-| `src/client/xronox-like.ts` | Minimal interface retrieval expects |
+Entity discovery, list columns, row composition, Catalox seed, orphan name parsing — stay in Catalox / memorix-retrieval.
 
-**Tracking:** When implementing in `@x12i/xronox`, link PR to this doc and update §3 / §4 status tables.
+Xronox remains a **database routing + I/O layer**, not Memorix-aware.

package/docs/fr/README.md

@@ -0,0 +1,15 @@
+# Feature requests — `@x12i/xronox` (Memorix data tier)
+
+**Audience:** `@x12i/xronox` maintainers  
+**Consumer:** `@x12i/memorix-retrieval`, Memorix Explorer, APIs, tools  
+**Policy:** Retrieval and hosts **must not** bypass Xronox with direct Mongo for production paths. Open FRs block retrieval features until Xronox ships the generic API.
+
+| FR | Status | Blocks |
+|----|--------|--------|
+| [xronox-fr-list-collections.md](./xronox-fr-list-collections.md) | **Shipped** (`@x12i/xronox` 3.9.0) | — |
+| [xronox-fr-memorix-env-preset.md](./xronox-fr-memorix-env-preset.md) | **Open** | Zero-config with `MEMORIX_*_DB` only |
+| [xronox-fr-per-role-selftest.md](./xronox-fr-per-role-selftest.md) | **Open** | Health reporting both entity + event DBs |
+
+**Already in Xronox 3.8+ (no FR):** `countDocuments`, `skip`, `sort` as Mongo object, `countDocuments({ estimated: true })`.
+
+See also: [XRONOX-DATA-TIER-REQUIREMENTS.md](../XRONOX-DATA-TIER-REQUIREMENTS.md) (integration index).

package/docs/fr/xronox-fr-list-collections.md

@@ -0,0 +1,196 @@
+# Feature request — routed `listCollections` (`@x12i/xronox`)
+
+**Date:** 2026-05-22  
+**Status:** **Shipped** — `@x12i/xronox@3.9.0`  
+**Consumer:** `@x12i/memorix-retrieval@1.6.1+`
+
+---
+
+## Summary
+
+Memorix **collection inventory** lists all Mongo collections in **both** Memorix databases (`memorix-entities`, `memorix-events`) using the same **role → database** routing as `read` and `countDocuments`. Implemented in Xronox 3.9.0; retrieval uses it with **no direct Mongo bypass**.
+
+---
+
+## Why this belongs in Xronox (not retrieval)
+
+| Concern | Host/retrieval bypass problem |
+|---------|-------------------------------|
+| Role routing | Must use same `role` → DB resolution as reads (`memorix_entities`, `memorix_events`) |
+| Multi-DB | Inventory scans **both** databases; routing must stay in Xronox |
+| Contract | [DATA-TIER-CONTRACT.md](../DATA-TIER-CONTRACT.md): production I/O through Xronox only |
+| Reuse | Any x12i app with role-based Mongo needs collection discovery, not only Memorix |
+
+---
+
+## Product requirement
+
+Expose a routed API that returns collection names (and optional types) for the **database resolved from `role`**, without targeting a single collection in `source`.
+
+Orphan scan flow (retrieval consumer):
+
+1. `listCollections({ role: "memorix_entities" })` → all non-system collections in entity DB  
+2. `listCollections({ role: "memorix_events" })` → all non-system collections in event DB  
+3. For each collection not in Catalox descriptor map: `countDocuments({ role, source: collectionName, estimated: true })` (already in Xronox 3.8+)
+
+Declared slot counts continue to use descriptor-routed `countDocuments` via `countMemorixEntityContentTypeDocuments` (retrieval).
+
+---
+
+## Proposed API
+
+```ts
+listCollections(params: ListCollectionsParams): Promise<ListCollectionsResult>;
+
+export interface ListedCollection {
+  name: string;
+  type?: string; // "collection" | "view" | ...
+}
+
+export interface ListCollectionsResult {
+  /** Resolved database name after role + tenancy (same as countDocuments/read) */
+  database: string;
+  collections: ListedCollection[];
+}
+
+export interface ListCollectionsParams extends RoutingKey {
+  subSourceType: "mongo";
+  /**
+   * Binding match token only — not a collection name.
+   * Zero-config bindings with no `match` accept any source (e.g. `"_db"`).
+   */
+  source: string;
+  role?: string;
+  /** Forwarded to Mongo db.listCollections({ filter }) */
+  filter?: Record<string, unknown>;
+  /** Default true — omit names starting with `system.` */
+  excludeSystem?: boolean;
+  /** Default true — use driver nameOnly for lighter responses */
+  nameOnly?: boolean;
+}
+```
+
+Add to `Xronox` interface and `Engine` (nxMongo engine only; xronoxCore may omit like `countDocuments`).
+
+---
+
+## Algorithm (normative)
+
+1. `resolveBinding(config, params)` — **same as `countDocuments` and `read`**.
+2. Resolve `connection` → `SimpleMongoHelper`.
+3. Resolve `db` from binding + `params.role` (role overrides binding default db).
+4. `sanitizeDatabaseName(db)` — same as existing count path.
+5. `mongoDb.listCollections(filter, { nameOnly })`.
+6. If `excludeSystem !== false`, filter out `system.*` names.
+7. Return `{ database: db, collections }`.
+
+**Do not** use `params.source` as a collection name. `source` exists only for binding selection.
+
+---
+
+## Example calls (Memorix)
+
+```ts
+// Entity store
+const entityDb = await xronox.listCollections({
+  dataType: "metadata",
+  sourceType: "database",
+  subSourceType: "mongo",
+  source: "_db",
+  role: "memorix_entities",
+});
+
+// Event store
+const eventDb = await xronox.listCollections({
+  dataType: "metadata",
+  sourceType: "database",
+  subSourceType: "mongo",
+  source: "_db",
+  role: "memorix_events",
+});
+
+// Orphan count (existing API)
+const count = await xronox.countDocuments({
+  dataType: "metadata",
+  sourceType: "database",
+  subSourceType: "mongo",
+  role: "memorix_entities",
+  source: "orphan-entity-records",
+  estimated: true,
+});
+```
+
+---
+
+## Implementation guidance (`@x12i/xronox`)
+
+| Layer | Change |
+|-------|--------|
+| `src/types.ts` | `ListCollectionsParams`, `ListCollectionsResult`, `ListedCollection`; extend `Xronox` |
+| `src/engines/interface.ts` | `listCollections?(params, resolved)` |
+| `src/engines/nxMongoEngine.ts` | Implement via `getDatabase` / `listCollections` (same helper lookup as `countDocuments`) |
+| `src/index.ts` | `XronoxImpl.listCollections` → `resolveBinding` → engine |
+| `README.md` | Document next to `countDocuments` example |
+| Tests | Routing unit test (no Mongo); optional integration test with fixture DB |
+
+Mirror error codes from count path: `CONNECTION_NOT_FOUND`, `DATABASE_NOT_RESOLVED`, `ROUTING_NOT_FOUND`.
+
+---
+
+## Retrieval integration (after Xronox ships)
+
+| Step | Action |
+|------|--------|
+| 1 | Bump `@x12i/xronox` minimum (e.g. `^3.9.0`) |
+| 2 | Extend `XronoxLike` + adapter to delegate `listCollections` |
+| 3 | `buildMemorixCollectionInventory` calls Xronox only — **throws** if `listCollections` missing |
+| 4 | Delete Explorer host shim `server/collection-inventory.ts` |
+| 5 | `npm run smoke:retrieval -- --inventory` |
+
+**No Mongo fallback in retrieval.** Tests may inject a mock `xronox` with `listCollections`; production requires real Xronox.
+
+---
+
+## Acceptance criteria
+
+### Xronox
+
+- [ ] `listCollections({ role: "memorix_entities" })` returns collections from `MEMORIX_ENTITIES_DB` / role map default
+- [ ] `listCollections({ role: "memorix_events" })` returns collections from events DB
+- [ ] `excludeSystem: true` (default) omits `system.*`
+- [ ] `database` in result matches DB used for `countDocuments` on same role + collection
+- [ ] Wrong/missing role → typed routing error (not empty list)
+- [ ] nxMongo engine only; clear error on xronoxCore
+
+### Retrieval (downstream)
+
+- [ ] `buildMemorixCollectionInventory` completes without `connectMemorixMongo`
+- [ ] Inventory `summary.byTarget` matches entries filtered by `target`
+- [ ] Vitest mocks `xronox.listCollections` only (no Mongo client for scan)
+
+---
+
+## Non-goals
+
+| Item | Reason |
+|------|--------|
+| Catalox orphan → descriptor seeding | Ops / Catalox tooling |
+| Memorix-specific parsing in Xronox | Stays in retrieval (`parseOrphanCollection`) |
+| List documents across all collections | Use inventory + per-collection `read` |
+
+---
+
+## Version
+
+| Package | Minimum after FR |
+|---------|------------------|
+| `@x12i/xronox` | `3.9.0` (proposed minor) |
+| `@x12i/memorix-retrieval` | Requires published Xronox with this FR |
+
+---
+
+## References
+
+- Retrieval inventory: `src/explorer/collection-inventory.ts`
+- Role constants: `src/data/memorix-read.ts` (`DEFAULT_MEMORIX_XRONOX_ROLES`)
+- Explorer shim (delete after ship): `memorix-explorer/server/collection-inventory.ts`