@x12i/memorix-retrieval 1.5.0 → 1.6.2

package/dist/tests/package-json.test.js

@@ -0,0 +1,14 @@
+import { describe, expect, it } from "vitest";
+import pkg from "../../package.json" with { type: "json" };
+describe("package.json sanity", () => {
+    it("does not list @x12i/memorix-retrieval as its own dependency", () => {
+        const deps = pkg.dependencies;
+        const devDeps = pkg.devDependencies;
+        const peerDeps = pkg
+            .peerDependencies;
+        expect(deps?.["@x12i/memorix-retrieval"]).toBeUndefined();
+        expect(devDeps?.["@x12i/memorix-retrieval"]).toBeUndefined();
+        expect(peerDeps?.["@x12i/memorix-retrieval"]).toBeUndefined();
+    });
+});
+//# sourceMappingURL=package-json.test.js.map

package/dist/tests/package-json.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-json.test.js","sourceRoot":"","sources":["../../src/tests/package-json.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,GAAG,MAAM,oBAAoB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AAE3D,QAAQ,CAAC,qBAAqB,EAAE,GAAG,EAAE;IACnC,EAAE,CAAC,6DAA6D,EAAE,GAAG,EAAE;QACrE,MAAM,IAAI,GAAG,GAAG,CAAC,YAAkD,CAAC;QACpE,MAAM,OAAO,GAAG,GAAG,CAAC,eAAqD,CAAC;QAC1E,MAAM,QAAQ,GAAI,GAAqD;aACpE,gBAAgB,CAAC;QAEpB,MAAM,CAAC,IAAI,EAAE,CAAC,yBAAyB,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC;QAC1D,MAAM,CAAC,OAAO,EAAE,CAAC,yBAAyB,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC;QAC7D,MAAM,CAAC,QAAQ,EAAE,CAAC,yBAAyB,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC;IAChE,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/docs/DATA-TIER-CONTRACT.md

@@ -9,6 +9,8 @@ See also:
 - [MEMORIX-CATALOX-CONTRACTS.md](./MEMORIX-CATALOX-CONTRACTS.md) — descriptor catalogs and JSON formats
 - [MEMORIX-DATABASE-CONVENTIONS.md](./MEMORIX-DATABASE-CONVENTIONS.md) — Mongo layout and env vars
 - [EXPLORER-HOST-APIS.md](./EXPLORER-HOST-APIS.md) — graph, raw reads, scoped workspace (Explorer-oriented)
+- [XRONOX-DATA-TIER-REQUIREMENTS.md](./XRONOX-DATA-TIER-REQUIREMENTS.md) — what `@x12i/xronox` must provide as Memorix data tier
+- [fr/README.md](./fr/README.md) — **open feature requests for `@x12i/xronox`** (implement there first)
 
 ---
 
@@ -16,13 +18,16 @@ See also:
 
 | Export | Purpose |
 |--------|---------|
-| `createMemorixRetrieval(options)` | Build client with Catalox (+ lazy Mongo from `MONGO_URI`) |
-| `createMemorixRetrievalFromEnv(options)` | Same, connects Mongo up front |
+| `createMemorixRetrieval(options)` | Build client with Catalox + optional Xronox data tier |
+| `createMemorixRetrievalFromEnv(options)` | Catalox + Xronox from env (default for hosts) |
+| `createMemorixXronoxFromEnv(options?)` | Xronox zero-config bootstrap only |
 | `createMemorixRetrievalStackFromEnv(options?)` | Catalox from env + adapter + retrieval client (recommended for hosts) |
 | `createCataloxAdapterFromBound(bound)` | Wrap a bound Catalox client for descriptor loads |
 | `resolveMemorixAppId(options?, processEnv?)` | Resolve app id: option → `CATALOX_APP_ID` → `MEMORIX_APP_ID` → `memorix` |
 
-**Required env (simple mode):** `MONGO_URI`. Catalox credentials per `@x12i/catalox` when using the stack helper.
+**Required env (default stack):** `MONGO_URI` (used by Xronox zero-config). Catalox credentials per `@x12i/catalox` when using the stack helper.
+
+Data reads and counts go through **Xronox** (`role: memorix_entities` for entity descriptors, `role: memorix_events` for event descriptors). Direct Mongo is an advanced test-only escape hatch.
 
 ---
 
@@ -62,8 +67,10 @@ List descriptor `filters` with `operator` + `value` are **always applied**; requ
 
 | Export | Purpose |
 |--------|---------|
-| `buildMemorixEntityGraph(client, options?)` | Discovery + counts + relation graph |
-| `buildMemorixEntitySlices(client, entityName)` | Per–content-type counts for drill-down |
+| `buildMemorixEntityGraph(client, options?)` | Discovery + counts + relation graph (per–content-type metadata, both DBs) |
+| `buildMemorixEntitySlices(client, entityName)` | Per–content-type counts for drill-down (includes zero counts) |
+| `buildMemorixCollectionInventory(client, options?)` | Reconcile Catalox-declared collections with Mongo in both databases via Xronox `listCollections` (≥ 3.9.0) |
+| `orphanNodesFromInventory(entries)` | Group inventory orphans for entity graph canvas |
 | `getMemorixRetrievalHealth(client)` | Mongo ping + discovery sample |
 | `countMemorixEntityContentTypeDocuments` | Count by entity + content type (descriptor-resolved collection) |
 | `listMemorixEntityContentTypeDocuments` | Paginated raw documents (descriptor-resolved) |
@@ -111,12 +118,13 @@ Scripts (not imported by hosts at runtime):
 
 | Export | Purpose |
 |--------|---------|
-| `memorixRead` | Low-level read with entity context (Mongo default; optional Xronox) |
-| `readMemorixCollection` / `countMemorixCollection` / `connectMemorixMongo` | Direct Mongo helpers |
+| `memorixRead` | Routed read via Xronox (entity context + collection + role) |
+| `memorixCount` | Routed count via Xronox (`countDocuments` on adapter) |
+| `readMemorixCollection` / `countMemorixCollection` / `connectMemorixMongo` | **Test-only** — not used by production inventory or list/item paths |
 | `resolveMemorixCollectionName` / `resolveMemorixDbNameForEntity` | Resolution utilities |
 | Env helpers: `resolveMemorixDbName`, `resolveMongoUri`, `targetCollectionEnvKey` | Advanced overrides |
 
-Pass `xronox` to `createMemorixRetrieval` only when injecting a pre-configured Xronox client.
+Pass `mongo` to `createMemorixRetrieval` only for tests or legacy hosts. Production hosts should use `createMemorixRetrievalFromEnv` / `createMemorixRetrievalStackFromEnv` (Xronox data tier).
 
 ---
 

package/docs/EXPLORER-HOST-APIS.md

@@ -19,8 +19,22 @@ Uses `createCataloxFromEnv` + `createCataloxAdapterFromBound` + `createMemorixRe
 ## Entity discovery
 
 - `discoverMemorixEntities(client)` — lists `memorix-entity-descriptors` via Catalox only (`source: "catalox" | "none"`). No env entity list fallback.
-- `buildMemorixEntityGraph(client)` — discovery + per–content-type counts + **relations from entity descriptors**.
-- `buildMemorixEntitySlices(client, entityName)` — slice counts for canvas drill-down.
+- `buildMemorixEntityGraph(client)` — discovery + per–content-type counts + **relations from entity descriptors**. Each entity includes `target`, `memorixDatabase`, and `contentTypes[]` (collection, database, count, status). `discovery.memorixDatabases` names both entity and event stores.
+- `buildMemorixEntitySlices(client, entityName)` — slice counts for canvas drill-down; includes **all** declared content types (zero counts use `status: "empty"`).
+- `buildMemorixCollectionInventory(client, options?)` — bidirectional Mongo ↔ Catalox inventory across both databases (`matched`, `empty`, `orphan`, `unresolved`). Options: `includeExactCounts`, `scopedNamespace`.
+- `orphanNodesFromInventory(entries)` — group orphan inventory rows into graph nodes for Explorer entities canvas.
+
+## Collection inventory
+
+Requires `@x12i/xronox` ≥ 3.9.0 (`listCollections`).
+
+- Declared counts: `countMemorixEntityContentTypeDocuments` (Xronox)
+- DB scan: `xronox.listCollections({ role })` for `memorix_entities` and `memorix_events`
+- Orphan counts: `xronox.countDocuments({ estimated: true })`
+
+Smoke: `npm run smoke:retrieval -- --inventory`
+
+Response: `entries`, `summary.byTarget`, `discovery`.
 
 ## Raw collection reads (Explorer compatibility)
 

package/docs/MEMORIX-CATALOX-CONTRACTS.md

@@ -481,12 +481,16 @@ When `discovery.source` is `"none"`, returns empty rows with a hint — no env e
 5. Resolve `includeRelations` and optional full content fetches.
 6. Return `{ identity, sections, relations?, issues? }`.
 
-### 5.6 Entity graph (Explorer)
+### 5.6 Entity graph and collection inventory (Explorer)
 
-`buildMemorixEntityGraph` uses discovery + entity descriptors only:
+Retrieval exports (see [EXPLORER-HOST-APIS.md](./EXPLORER-HOST-APIS.md)):
 
-- Per entity: label, counts, content-type labels, **`relations` → connections**, default list/item ids.
-- `discovery.source` is `"catalox"` or `"none"` — never `"env"`.
+- `buildMemorixEntityGraph` — discovery + entity descriptors; per entity: label, counts, **`contentTypes[]`**, **`relations` → connections**, default list/item ids, `target`, `memorixDatabase`.
+- `buildMemorixEntitySlices` — all declared content types including zero counts.
+- `buildMemorixCollectionInventory` — reconcile declared collections with Mongo in both databases.
+- `orphanNodesFromInventory` — orphan groups for entities canvas.
+
+`discovery.source` is `"catalox"` or `"none"` — never `"env"`. `discovery.memorixDatabases` names both entity and event stores.
 
 ---
 

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

@@ -0,0 +1,132 @@
+# Xronox data tier requirements — `@x12i/memorix-retrieval`
+
+**Audience:** `@x12i/xronox` maintainers  
+**Consumer:** `@x12i/memorix-retrieval` (v1.5+) and hosts (Memorix Explorer, APIs, tools)  
+**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
+
+---
+
+## 1. Why Xronox is the Memorix data tier
+
+Memorix separates **metadata** from **payload**:
+
+| Layer | Package | Owns |
+|-------|---------|------|
+| Metadata | **Catalox** | Entity/list/item descriptors, discovery, column layout |
+| 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 in production. Retrieval’s default bootstrap is:
+
+```ts
+createMemorixRetrievalFromEnv({ catalox })
+  → createMemorixXronoxFromEnv()
+  → createMemorixXronoxAdapter(createXronox())
+```
+
+All list/item/workspace reads and counts flow through Xronox routing.
+
+---
+
+## 2. Integration contract (today)
+
+### 2.1 Read routing key
+
+Every Memorix Mongo read uses this Xronox routing shape:
+
+```ts
+{
+  dataType: "metadata",
+  sourceType: "database",
+  subSourceType: "mongo",
+  role: "<xronox-role>",
+  source: "<collection-name>",
+  query?: Record<string, unknown>,
+  project?: string[],
+  sort?: string | string[] | Record<string, 1 | -1>,
+  limit?: number,
+  skip?: number,
+}
+```
+
+### 2.2 Role mapping (Memorix target → Xronox role)
+
+| Entity descriptor `target` | Memorix database (logical) | Default Xronox `role` (3.8+) |
+|--------------------------|----------------------------|------------------------------|
+| `"entity"` (default) | `memorix-entities` | `memorix_entities` |
+| `"event"` | `memorix-events` | `memorix_events` |
+
+Constants in retrieval: `DEFAULT_MEMORIX_XRONOX_ROLES` (`src/data/memorix-read.ts`).
+
+### 2.3 Operations retrieval performs via Xronox
+
+| 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) |
+
+---
+
+## 3. Shipped in Xronox (retrieval uses today)
+
+| 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. Open — implement in Xronox (see FRs)
+
+| 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 |
+
+~~P0 listCollections~~ — **shipped 3.9.0**. See [FR](./fr/xronox-fr-list-collections.md).
+
+**Do not** implement these in retrieval with `connectMemorixMongo` or other driver bypasses.
+
+---
+
+## 5. Retrieval policy (no workarounds)
+
+| 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+ |
+
+---
+
+## 6. Version alignment
+
+| Package | Current | Notes |
+|---------|---------|-------|
+| `@x12i/memorix-retrieval` | 1.6.1 | Inventory via Xronox `listCollections` |
+| `@x12i/xronox` | ^3.9.0 | `listCollections` required for inventory |
+
+---
+
+## 7. Out of scope for Xronox
+
+Entity discovery, list columns, row composition, Catalox seed, orphan name parsing — stay in Catalox / memorix-retrieval.
+
+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`

package/docs/fr/xronox-fr-memorix-env-preset.md

@@ -0,0 +1,69 @@
+# Feature request — Memorix deployment preset / env aliases (`@x12i/xronox`)
+
+**Date:** 2026-05-22  
+**Status:** **Open**  
+**Requested by:** `@x12i/memorix-retrieval`, Memorix Explorer smoke scripts  
+**Target package:** `@x12i/xronox`  
+**Priority:** P1 (ergonomics — not blocking inventory if roles + DB vars are set explicitly)
+
+---
+
+## Summary
+
+Memorix documents **`MEMORIX_ENTITIES_DB`** and **`MEMORIX_EVENTS_DB`**. Xronox zero-config resolves databases via **`MONGO_OPERATIONAL_DB`**, **`MONGO_LOGS_DB`**, and role maps (`memorix_entities`, `memorix_events`). Deployments must duplicate env vars today.
+
+This FR aligns Xronox zero-config with Memorix conventions so smoke and Explorer work with **`MONGO_URI` + `MEMORIX_*_DB` only**.
+
+---
+
+## Product requirement
+
+When resolving Mongo database names for roles:
+
+| Xronox role | Memorix target | Fallback chain should include |
+|-------------|----------------|------------------------------|
+| `memorix_entities` / `memory.entities` / `operational` | `entity` | `MEMORIX_ENTITIES_DB` → `memorix-entities` |
+| `memorix_events` / `memory.events` / `logs` | `event` | `MEMORIX_EVENTS_DB` → `memorix-events` |
+
+---
+
+## Proposed options (pick one or both)
+
+### Option A — Env aliases in role resolution
+
+In `resolveDatabaseNameFromRole` / `MONGO_ROLE_MAP` fallback chains:
+
+```
+memorix_entities.database ← MEMORIX_ENTITIES_DB ← MONGO_OPERATIONAL_DB ← MONGO_DB
+memorix_events.database   ← MEMORIX_EVENTS_DB   ← MONGO_LOGS_DB       ← MONGO_DB
+```
+
+### Option B — Zero-config preset
+
+```ts
+await xronox.init({ engine: "nxMongo", preset: "memorix", zeroConfig: true });
+```
+
+Preset registers role map defaults and env aliases above. Document in Xronox README + `.env.example`.
+
+---
+
+## Acceptance criteria
+
+- [ ] `npm run smoke:retrieval` in memorix-retrieval succeeds with only `MONGO_URI`, `MEMORIX_ENTITIES_DB`, `MEMORIX_EVENTS_DB`, Catalox creds
+- [ ] No requirement to set `MONGO_OPERATIONAL_DB` / `MONGO_LOGS_DB` for Memorix deployments
+- [ ] Existing non-Memorix zero-config behavior unchanged when preset not used
+
+---
+
+## Retrieval integration (after ship)
+
+- Optionally simplify `createMemorixXronoxFromEnv` to pass `preset: "memorix"`.
+- Update [MEMORIX-DATABASE-CONVENTIONS.md](../MEMORIX-DATABASE-CONVENTIONS.md) with single env table.
+
+---
+
+## Non-goals
+
+- Catalox or descriptor env (stays in `@x12i/catalox`)
+- Changing Memorix collection naming (retrieval + Catalox)

package/docs/fr/xronox-fr-per-role-selftest.md

@@ -0,0 +1,60 @@
+# Feature request — per-role `selfTest` detail (`@x12i/xronox`)
+
+**Date:** 2026-05-22  
+**Status:** **Open**  
+**Requested by:** `@x12i/memorix-retrieval` (`getMemorixRetrievalHealth`)  
+**Target package:** `@x12i/xronox`  
+**Priority:** P2 (health UX — not blocking lists or inventory)
+
+---
+
+## Summary
+
+Memorix runs **two** Mongo databases (entity + event). Health checks should report connectivity **per role**, not a single anonymous ping. Retrieval already passes `selfTestRoles: ["memorix_entities", "memorix_events"]` to the adapter when Xronox supports it.
+
+---
+
+## Product requirement
+
+Extend `selfTest` result so hosts can show which Memorix store failed:
+
+```ts
+type SelfTestResult = {
+  passed: boolean;
+  roles?: Array<{
+    role: string;
+    db: string;
+    ok: boolean;
+    latencyMs?: number;
+    error?: string;
+  }>;
+};
+```
+
+```ts
+await xronox.selfTest({
+  testConnectivity: true,
+  selfTestRoles: ["memorix_entities", "memorix_events"],
+});
+```
+
+---
+
+## Acceptance criteria
+
+- [ ] Each role resolves DB name and attempts connectivity (e.g. listCollections or count on a lightweight op)
+- [ ] `passed: false` if any requested role fails
+- [ ] Works with Memorix env vars when [memorix-env-preset FR](./xronox-fr-memorix-env-preset.md) is also applied (or explicit DB vars)
+
+---
+
+## Retrieval integration (after ship)
+
+- `getMemorixRetrievalHealth` surfaces per-role results in response (optional field)
+- Remove direct Mongo ping fallback from health when Xronox reports both roles
+
+---
+
+## Non-goals
+
+- Descriptor / Catalox health (retrieval discovers Catalox separately)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/memorix-retrieval",
-  "version": "1.5.0",
+  "version": "1.6.2",
   "description": "Descriptor-driven Memorix retrieval layer for lists, items, and content objects",
   "type": "module",
   "main": "./dist/index.js",
@@ -30,18 +30,9 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@x12i/catalox": "^4.1.2",
+    "@x12i/catalox": "^5.0.0",
     "@x12i/helpers": "^1.7.0",
-    "@x12i/memorix-retrieval": "^1.4.0",
-    "mongodb": "^6.21.0"
-  },
-  "peerDependencies": {
-    "@x12i/xronox": ">=3.7.0"
-  },
-  "peerDependenciesMeta": {
-    "@x12i/xronox": {
-      "optional": true
-    }
+    "@x12i/xronox": "^3.9.0"
   },
   "devDependencies": {
     "@types/node": "^20.14.0",