@x12i/memorix-descriptors 1.4.2 → 1.5.0

package/docs/MEMORIX-CATALOX-CATALOG-MAP.md

@@ -0,0 +1,589 @@
+# Memorix Catalox catalog map
+
+**Purpose:** Single reference for every Memorix `catalogId` stored in Catalox under app `memorix`, including catalog metadata, item schemas, shipped items, cross-links, and the **why** behind each choice.
+
+**Terminology:** Catalog **object types** (`assets`, `vulnerabilities`, …) vs storage **targets** (`entity`, `event`, `knowledge`) vs overloaded “entity” names are defined in **[MEMORIX-OBJECT-TYPES-AND-TARGETS.md](./MEMORIX-OBJECT-TYPES-AND-TARGETS.md)**. Read that first if “entities vs objects” is unclear.
+
+**Sources (2026-05-23):**
+
+| Source | What it represents |
+|--------|-------------------|
+| `@x12i/memorix-descriptors` | Canonical catalog ids, `ensureCatalog` metadata, write/read paths, integrity rules |
+| `@x12i/memorix-retrieval` → `catalox-seeds/inputs/` | Shipped descriptor JSON (expected Catalox contents after seed apply) |
+| `docs/MEMORIX-CATALOX-CONTRACTS.md`, `docs/MEMORIX-DATABASE-CONVENTIONS.md` | Cross-package contracts |
+| **Live Firebase** (project `x12i-493313`, app `memorix`) | Catalog registry + item counts via `@x12i/catalox` (`listCatalogs`, `listCatalogItems`) |
+
+Reconcile local exports with production:
+
+```bash
+npx memorix-descriptors seed export ./catalox-seeds/inputs
+# or: admin.loadSnapshot() / validateMemorixDescriptors()
+```
+
+---
+
+## 1. Namespace
+
+| Field | Value | Why |
+|-------|-------|-----|
+| **App id** | `memorix` | Single namespace for all Memorix metadata catalogs so retrieval, Explorer, and descriptors share one discovery surface. |
+| **Override** | `CATALOX_APP_ID` → `MEMORIX_APP_ID` | Allows non-default deployments without forking catalog ids. |
+| **Rule** | Do not invent parallel catalog names | Fragmented truth breaks discovery (`discoverMemorixEntities` lists one catalog only) and seed apply. |
+
+**Package-managed catalogs:** **5** (`memorix-descriptors` ensures these). Retrieval’s public contract documents the **first three** descriptor catalogs.
+
+**Production Firebase (this deployment):** **7** Memorix-related native catalogs with item rows, plus legacy catalogs still present in Firestore (see §2.1).
+
+### 1.1 Firestore physical layout (what you see in Firebase console)
+
+Catalox stores **native catalog items** in top-level Firestore collections named:
+
+```text
+catalogData-{catalogId}-items/{itemId}
+```
+
+The Firebase console often shows the **suffix** with a leading `-`, e.g. `-memorix-entity-descriptors-items` is the tail of **`catalogData-memorix-entity-descriptors-items`**.
+
+| Console suffix (your screenshot) | Full Firestore collection | `catalogId` |
+|----------------------------------|---------------------------|-------------|
+| `-memorix-entity-descriptors-items` | `catalogData-memorix-entity-descriptors-items` | `memorix-entity-descriptors` |
+| `-memorix-list-descriptors-items` | `catalogData-memorix-list-descriptors-items` | `memorix-list-descriptors` |
+| `-memorix-item-descriptors-items` | `catalogData-memorix-item-descriptors-items` | `memorix-item-descriptors` |
+| `-memorix-entities-items` | `catalogData-memorix-entities-items` | `memorix-entities` (legacy — see §12) |
+| `-memorix-entity_content_types-items` | `catalogData-memorix_entity_content_types-items` | `memorix_entity_content_types` (legacy — underscore in id) |
+
+**Not the same as Mongo:** Mongo database `memorix-entities` is the **storage target `entity`** database (payload). Catalox catalog `memorix-entities` holds **legacy inferred schema samples** — unrelated catalog id. Catalog **`memorix-entity-descriptors`** registers **object types** for all targets (`entity`, `event`, `knowledge`), not only the entity tier. See [MEMORIX-OBJECT-TYPES-AND-TARGETS.md](./MEMORIX-OBJECT-TYPES-AND-TARGETS.md).
+
+Other Catalox roots in the same project (not in your screenshot): `apps`, `catalogs`, `catalogBindings`, `catalogDescriptors`, legacy `catalogData/{catalogId}/items` subcollections (pre-migration). See `@x12i/catalox` README → `docs/firestore-data-model.md`.
+
+```text
+                    appId: memorix
+                           │
+    ┌──────────────────────┼──────────────────────┐
+    │                      │                      │
+    ▼                      ▼                      ▼
+ memorix-entity-      memorix-list-         memorix-item-
+ descriptors          descriptors           descriptors
+    │                      │                      │
+    │    default-list / default-item edges       │
+    └──────────────────────┴──────────────────────┘
+                           │
+              ┌────────────┴────────────┐
+              ▼                         ▼
+   memorix-completion-mappings   memorix-inventory-policies
+   (optional, runtime CRUD)      (single item: default)
+```
+
+---
+
+## 2. Catalog index
+
+### 2.1 Live Firebase inventory (app `memorix`, 2026-05-23)
+
+| `catalogId` | Firestore items collection | Items (live) | Status | Primary consumer |
+|-------------|------------------------------|--------------|--------|------------------|
+| `memorix-entity-descriptors` | `catalogData-memorix-entity-descriptors-items` | **3** | **Current** — retrieval discovery | `@x12i/memorix-retrieval`, `@x12i/memorix-descriptors` |
+| `memorix-list-descriptors` | `catalogData-memorix-list-descriptors-items` | **5** | **Current** | Retrieval lists / workspace; descriptor slices |
+| `memorix-item-descriptors` | `catalogData-memorix-item-descriptors-items` | **3** | **Current** | Retrieval detail views |
+| `memorix-completion-mappings` | `catalogData-memorix-completion-mappings-items` | ? (list blocked) | Registered; `listCatalogItems` → adapter error | `@x12i/memorix-completion` when wired |
+| `memorix-inventory-policies` | `catalogData-memorix-inventory-policies-items` | **0** (catalog not registered) | Not deployed yet | `memorix-descriptors` reconcile |
+| `memorix-entities` | `catalogData-memorix-entities-items` | **9** | **Legacy** — schema inference | Old Explorer / `catalog-memorix-entities` tooling |
+| `memorix_entity_content_types` | `catalogData-memorix_entity_content_types-items` | **15** | **Legacy** — xmemory content types | `@x12i/xmemory-store` era; superseded by `contentTypes` on entity descriptors |
+| `knowledge` | `catalogData-knowledge-items` | **3** | **Active** (parallel track) | Memorix knowledge / skills (not entity descriptors) |
+
+**Live item ids (descriptor catalogs — match seeds):**
+
+| Catalog | Item ids |
+|---------|----------|
+| `memorix-entity-descriptors` | `assets`, `variabilities-groups`, `vulnerabilities` |
+| `memorix-list-descriptors` | `assets-main-list`, `critical-vulnerabilities-list`, `memorix-workspace-records-list`, `variabilities-groups-main-list`, `vulnerabilities-main-list` |
+| `memorix-item-descriptors` | `asset-detail-item`, `variabilities-group-detail-item`, `vulnerability-detail-item` |
+
+### 2.2 Package-managed catalog index (`memorix-descriptors`)
+
+| # | `catalogId` | Group | `catalogType` | `sourceMode` | Item id field | Title field | In Firebase today |
+|---|-------------|-------|---------------|--------------|---------------|-------------|-------------------|
+| 1 | `memorix-entity-descriptors` | Descriptor | `memorix` | `native` | `id` | `entityName` | Yes (3 items) |
+| 2 | `memorix-list-descriptors` | Descriptor | `memorix` | `native` | `id` | `title` | Yes (5 items) |
+| 3 | `memorix-item-descriptors` | Descriptor | `memorix` | `native` | `id` | `title` | Yes (3 items) |
+| 4 | `memorix-completion-mappings` | Control plane | `generic`* | `native` | `id` | `name` | Catalog exists; list adapter error |
+| 5 | `memorix-inventory-policies` | System | `memorix` | `native` | `id` | `id` | Not registered |
+
+\*Live registry shows `catalogType: "generic"` for completion mappings; seeds use `memorix`. Harmless for reads if items exist; align type on next `ensureCatalog` if desired.
+
+**Why native + memorix type:** Catalox stores JSON documents as first-class items (not external DB mirrors). The `memorix` catalog type signals Memorix-specific validation and seed presets (`memorix-retrieval-descriptors`).
+
+---
+
+## 3. Shared item envelope
+
+Every catalog item upserted through seeds or mutations follows:
+
+```json
+{
+  "id": "<same as Catalox itemId>",
+  "...descriptor or policy fields...",
+  "scope": {
+    "domains": ["network", "vulnerabilities"],
+    "agents": ["neo"]
+  }
+}
+```
+
+| Aspect | Detail | Why |
+|--------|--------|-----|
+| **`id` in body** | Must match Catalox `itemId` | Stable joins for `getCatalogItem`, integrity graph, and seed round-trip. |
+| **`scope`** | `domains[]`, `agents[]` | Filters which deployment/agent sees seeded descriptors; **not** a Mongo namespace. Workspace lists may use `scopeFilter: "inherit-seed-scope"` as a Catalox hint. |
+| **Seed apply** | Scope merged into upsert `data` | Catalox seed CLI upserts `row.data` only; merge avoids losing scope until native top-level scope exists. |
+| **Shipped scope** | `network`, `vulnerabilities` × agent `neo` | Matches Neo/network vulnerability product slice. |
+
+---
+
+## 4. Catalog: `memorix-entity-descriptors` (object type descriptors)
+
+> **Naming debt:** Catalog id and type name `MemorixEntityDescriptor` predate **event** and **knowledge** targets. Each item is a **catalog object type** descriptor (field `entityName`), not “an entity” in the Mongo `memorix-entities` sense. Proposed rename: `memorix-object-type-descriptors` — [roadmap](./MEMORIX-OBJECT-TYPES-AND-TARGETS.md#7-rename-roadmap-recommended--not-yet-applied-in-code).
+
+### 4.1 Catalog metadata (Catalox)
+
+| Property | Value |
+|----------|-------|
+| **Display name** | Memorix entity descriptors (display name is legacy) |
+| **`catalogType`** | `memorix` |
+| **`sourceMode`** | `native` |
+| **`native.itemIdField`** | `id` |
+| **`native.titleField`** | `entityName` |
+| **Queryable fields** | `id`, `entityName`, `target` |
+| **Descriptor capabilities** | list, get, create, edit, delete, import, export, validate, viewReferences (no sync) |
+| **Ensured by** | `ensureMemorixDescriptorCatalogs()` |
+
+### 4.2 Why this catalog exists
+
+**Object type descriptors** (this catalog) are the **root of truth** for which domain types exist in Memorix:
+
+- **Discovery:** `discoverMemorixEntities` lists this catalog only — returns **catalog object types** (field `entityName`); no env fallback (`MEMORIX_ENTITY_NAMES` is forbidden).
+- **Mongo routing:** per-item `target` selects storage tier → `memorix-entities` | `memorix-events` | `memorix-knowledge`.
+- **Schema:** Properties, content types, relations, and default list/item ids per object type.
+- **Graph:** Relations are declared here; retrieval resolves joins at read time using Mongo paths, not Catalox edges.
+
+### 4.3 Item schema (`MemorixEntityDescriptor`)
+
+| Field | Required | Purpose |
+|-------|----------|---------|
+| `id` | yes | Catalog item id (usually equals `entityName`) |
+| `entityName` | yes | **Catalog object type** id (kebab-case); rename candidate: `objectType` |
+| `defaultListDescriptorId` | yes | Pointer into `memorix-list-descriptors` |
+| `defaultItemDescriptorId` | yes | Pointer into `memorix-item-descriptors` |
+| `target` | no (default `entity`) | `entity` \| `event` \| `knowledge` → database role |
+| `collectionPrefix` | yes | `{prefix}-{postfix}` heuristic when `collection` omitted |
+| `identity` | yes | `allowedIdFields`, `requiredExactlyOne`, `defaultIdField` |
+| `defaults` | yes | Canonical content type, `dataRoot`, effective-date paths |
+| `contentTypes` | yes | Named slices → Mongo collections |
+| `properties` | yes | Field dictionary (paths, types, list/item flags) |
+| `relations` | no | Cross-entity joins (Mongo path matching) |
+| `contentDefaults` | no | Content-object storage defaults |
+
+**Property rules:** List views only expose properties with `humanReadable: true`. Paths are dot paths from the Mongo document root (e.g. `data.assetIp`).
+
+### 4.4 Shipped items (seed)
+
+| Item id | `entityName` | `target` | Mongo DB | Canonical collection | Default list | Default item | Why this entity |
+|---------|--------------|----------|----------|----------------------|--------------|--------------|-----------------|
+| `assets` | `assets` | `entity` | `memorix-entities` | `assets-snapshots` | `assets-main-list` | `asset-detail-item` | XDR/network **assets** — stable inventory hosts; hub for vulnerability counts and `assetVulnerabilities` relation. |
+| `vulnerabilities` | `vulnerabilities` | `event` | `memorix-events` | `vulnerabilities-snapshots` | `vulnerabilities-main-list` | `vulnerability-detail-item` | Vulnerability **findings** as events (timeline/detections), enriched fields (`data.enrichment.*`), MITRE/network context. |
+| `variabilities-groups` | `variabilities-groups` | `entity` | `memorix-entities` | `variabilities-groups-snapshots` | `variabilities-groups-main-list` | `variabilities-group-detail-item` | Plugin-level **groups** aggregating many vulnerabilities; supports group ↔ vuln relation. |
+
+**Target injection at seed build:** `MEMORIX_RETRIEVAL_ENTITY_TARGETS` in `memorix-descriptors` sets `target` when building manifests from retrieval seed files (assets/variabilities-groups → `entity`, vulnerabilities → `event`).
+
+### 4.5 Shipped relations (why)
+
+| Source entity | Relation key | Type | Target | Join (summary) | Why |
+|---------------|--------------|------|--------|----------------|-----|
+| `assets` | `assetVulnerabilities` | `oneToMany` | `vulnerabilities` | `data.ip_address` ↔ `data.assetIp` | Asset detail/list can show related vulns without storing edges in Mongo. |
+| `vulnerabilities` | `affectedAsset` | `manyToOne` | `assets` | `data.assetIp` ↔ `data.ip_address` | Vuln detail enriches with host/XDR context from asset snapshots. |
+| `vulnerabilities` | `vulnerabilityGroup` | `manyToOne` | `variabilities-groups` | `data.pluginId` ↔ `data.plugin_id` | Links finding to plugin-level group metadata. |
+| `variabilities-groups` | `groupVulnerabilities` | `oneToMany` | `vulnerabilities` | `data.plugin_id` ↔ `data.pluginId` | Group detail lists member vulnerabilities. |
+
+### 4.6 Property counts (shipped)
+
+| Entity | Properties | Relations |
+|--------|------------|-----------|
+| `assets` | 17 | 1 |
+| `vulnerabilities` | 27 | 2 |
+| `variabilities-groups` | 18 | 1 |
+
+---
+
+## 5. Catalog: `memorix-list-descriptors`
+
+### 5.1 Catalog metadata (Catalox)
+
+| Property | Value |
+|----------|-------|
+| **Display name** | Memorix list descriptors |
+| **`catalogType`** | `memorix` |
+| **`sourceMode`** | `native` |
+| **`native.itemIdField`** | `id` |
+| **`native.titleField`** | `title` |
+| **Queryable fields** | `id`, `entity`, `title` |
+
+### 5.2 Why this catalog exists
+
+List descriptors define **how** retrieval (and Explorer) query Mongo and shape tabular rows:
+
+- Pagination driver (`leadingContentType`), default filters, sort allowlists.
+- Column sets (`fields[]` → entity property keys).
+- Optional extensions and `includeRelations` for list rows.
+- **Workspace** and **slice** variants also live here (`kind: "workspace"` \| `"slice"`).
+
+Without this catalog, hosts would query collections by name and invent columns — forbidden by contract.
+
+### 5.3 Item kinds (discriminated union)
+
+| `kind` | When | Key fields | Why separate |
+|--------|------|------------|--------------|
+| *(omit / `"entity"`)* | Per-entity table | `entity`, `leadingContentType`, `fields[]`, `pagination` | Standard entity list API (`fetchMemorixList`). |
+| `"workspace"` | Cross-entity Records view | `fields[]`, optional `entities`, `listDescriptorByEntity` | Explorer workspace merges multiple entity lists in memory (v1). |
+| `"slice"` | Filtered sub-view (admin) | `entityName`, `contentType`, `filter`, `sort` | Operational slices (e.g. critical subset) without new entities; written by `createSliceDescriptor`. |
+
+### 5.4 Shipped items (seed)
+
+| Item id | Kind | Entity | Title | Leading CT | Notable filters / sort | Why |
+|---------|------|--------|-------|------------|------------------------|-----|
+| `assets-main-list` | entity | `assets` | Assets | `snapshots` | Sort default: `ipAddress` asc | Primary asset inventory for Neo network view. |
+| `vulnerabilities-main-list` | entity | `vulnerabilities` | Vulnerabilities | `snapshots` | Sort: `priorityScore` desc | Full vuln table with enrichment columns. |
+| `critical-vulnerabilities-list` | entity | `vulnerabilities` | Critical Vulnerabilities | `snapshots` | Default filter `severityLevel >= 4` | Focused view for high-severity triage without separate entity. |
+| `variabilities-groups-main-list` | entity | `variabilities-groups` | Vulnerability Groups | `snapshots` | Sort: `priorityScore` desc | Group-centric prioritization. |
+| `memorix-workspace-records-list` | workspace | — | Workspace records | — | Sort: `lastUpdated` desc | Explorer **Records** when no entity filter; merges per-entity default lists. |
+
+**Workspace column hints:** `entityName`, `recordTitle`, `recordId`, `source`, `lastUpdated`, `status` — synthetic/host-composed row fields, not all entity properties.
+
+---
+
+## 6. Catalog: `memorix-item-descriptors`
+
+### 6.1 Catalog metadata (Catalox)
+
+| Property | Value |
+|----------|-------|
+| **Display name** | Memorix item descriptors |
+| **`catalogType`** | `memorix` |
+| **`sourceMode`** | `native` |
+| **`native.itemIdField`** | `id` |
+| **`native.titleField`** | `title` |
+| **Queryable fields** | `id`, `entity`, `title` |
+
+### 6.2 Why this catalog exists
+
+Item descriptors define **record detail** composition:
+
+- Which content types to load per identity (`entityId` / `eventId`).
+- `multiMatch` strategy when several Mongo docs share identity (`last` by `capturedAt` default).
+- UI sections (`sections[].fields[]` → property keys).
+- `includeRelations` for embedded related data on detail pages.
+
+### 6.3 Item schema (summary)
+
+| Field | Required | Purpose |
+|-------|----------|---------|
+| `id`, `entity`, `title` | yes | Identity and label |
+| `identity.idField` | yes | `entityId` or `eventId` for fetch |
+| `contentTypes[]` | yes | Per-type `required`, `multiMatch` |
+| `sections[]` | yes | Grouped field layout |
+| `includeRelations` | no | Relation keys from entity descriptor |
+| `content` | no | Full content-object fetch policy |
+
+### 6.4 Shipped items (seed)
+
+| Item id | Entity | `identity.idField` | Sections (ids) | Relations included | Why |
+|---------|--------|-------------------|----------------|-------------------|-----|
+| `asset-detail-item` | `assets` | `entityId` | summary, vulnerabilitySummary, impact, xdr | `assetVulnerabilities` (array, limit 100) | Asset drill-down with vuln rollups and XDR raw block. |
+| `vulnerability-detail-item` | `vulnerabilities` | `entityId` | summary, asset, risk, threatIntelligence, networkAndMitre | `affectedAsset`, `vulnerabilityGroup` | Single-finding analysis with asset + group context. |
+| `variabilities-group-detail-item` | `variabilities-groups` | `entityId` | summary, affectedEntities, risk, threatIntelligence | `groupVulnerabilities` (array, limit 200) | Group drill-down with member vuln list. |
+
+**Note:** Shipped vuln item uses `entityId` even though entity `target` is `event` — identity block allows both fields on entity descriptor; item fetch uses declared `idField`.
+
+---
+
+## 7. Catalog: `memorix-completion-mappings`
+
+### 7.1 Catalog metadata (Catalox)
+
+| Property | Value |
+|----------|-------|
+| **Display name** | Memorix completion mappings |
+| **`catalogType`** | `memorix` |
+| **`sourceMode`** | `native` |
+| **`native.itemIdField`** | `id` |
+| **`native.titleField`** | `name` |
+| **Ensured by** | `ensureMemorixDescriptorCatalogs()` |
+| **Read behavior** | If catalog missing or adapter error → **empty** (no throw) | Lets retrieval/descriptors run before mappings are seeded. |
+
+### 7.2 Why this catalog exists
+
+Completion pipelines enrich Memorix **Mongo `data`** from **source databases**. Storing mappings in Catalox (instead of repo-only JSON) gives:
+
+- One control plane with entity descriptors (`entityType`, `targetCollection` validated against entity `contentTypes`).
+- Runtime CRUD via `registerMapping` / `updateMapping` / `removeMapping`.
+- Rename safety: `renameEntityDescriptor` updates `entityType` on affected mappings.
+
+**Not in retrieval seeds:** `@x12i/memorix-retrieval` ships zero mapping files; mappings are deployment-specific.
+
+### 7.3 Item schema (`MemorixCompletionMapping`)
+
+| Field | Purpose | Why |
+|-------|---------|-----|
+| `id` | Stable mapping id | Catalog item key |
+| `name` | Human label | Catalox title field |
+| `entityType` | Must match an entity descriptor id / name | Ties mapping to schema and collections |
+| `target` | `entity` \| `event` \| `knowledge` | Selects Memorix DB |
+| `targetCollection` | Explicit Mongo collection | Must exist on entity `contentTypes` |
+| `targetSelector` | `{ sourceCollection, idField }` | Provenance / join lineage on Memorix records |
+| `source` | `{ databaseName, collection }` | Where to read enrichment from (often `{{ENV.*}}`) |
+| `match` | `{ targetPath, sourcePath }` | Document join (e.g. `entityId` ↔ `vulnerabilityId`) |
+| `writeRoot` | Always `"data"` | Never overwrite envelope fields |
+| `fields[]` | `{ sourcePath, targetPath }` | Field-level copy rules |
+| `onlyFillMissing` / `overwriteExisting` | Write mode | Default: fill missing only |
+
+See `docs/MEMORIX-DATABASE-CONVENTIONS.md` § Completion mapping conventions for example JSON.
+
+### 7.4 Shipped items
+
+**None** in `memorix-retrieval` catalox-seeds. Expected count in fresh deploy: **0** until operators register mappings.
+
+---
+
+## 8. Catalog: `memorix-inventory-policies`
+
+### 8.1 Catalog metadata (Catalox)
+
+| Property | Value |
+|----------|-------|
+| **Display name** | Memorix inventory policies |
+| **`catalogType`** | `memorix` |
+| **`sourceMode`** | `native` |
+| **`native.itemIdField`** | `id` |
+| **`native.titleField`** | `id` |
+| **Fixed item id** | `default` (`MEMORIX_INVENTORY_POLICY_ITEM_ID`) | Single policy document per app |
+
+### 8.2 Why this catalog exists
+
+Unified inventory compares **Mongo collections** to **descriptor-declared** collections. Operators need to suppress noise (legacy DBs, external collections, pending mappings) without deleting data:
+
+- `ignoreCollection` / `unignoreCollection` append/remove entries.
+- Reconcile marks ignored rows separately from true orphans.
+
+**Why not in retrieval contract:** Read-only data tier does not manage inventory policy; `memorix-descriptors` owns it.
+
+### 8.3 Item schema (`MemorixInventoryPolicy`)
+
+```json
+{
+  "id": "default",
+  "ignoredCollections": [
+    {
+      "target": "entity",
+      "collectionName": "some-legacy-col",
+      "reason": "legacy",
+      "databaseName": "optional-override",
+      "note": "optional",
+      "createdAt": "ISO-8601",
+      "createdBy": "operator"
+    }
+  ]
+}
+```
+
+| `reason` enum | Typical use |
+|---------------|-------------|
+| `legacy` | Old collections not yet mapped |
+| `external` | Non-Memorix data in shared cluster |
+| `reserved` | Planned future mapping |
+| `temporary` | Migration in progress |
+| `not-memorix` | Unrelated database artifact |
+| `pending-mapping` | Known gap, mapping coming |
+| `other` | Catch-all |
+
+### 8.4 Shipped items
+
+**None** required. Absent catalog/item → empty policy (`ignoredCollections: []`).
+
+---
+
+## 9. Cross-catalog reference graph
+
+### 9.1 Default wiring (Option A)
+
+```text
+assets ──default-list──► assets-main-list
+      └──default-item──► asset-detail-item
+
+vulnerabilities ──default-list──► vulnerabilities-main-list
+                └──default-item──► vulnerability-detail-item
+                └──alt list──────► critical-vulnerabilities-list
+
+variabilities-groups ──default-list──► variabilities-groups-main-list
+                     └──default-item──► variabilities-group-detail-item
+
+(workspace) memorix-workspace-records-list ──► all discovered entities' default lists
+```
+
+### 9.2 Integrity edges checked by `memorix-descriptors`
+
+| Edge kind | From | To | Why validated |
+|-----------|------|-----|---------------|
+| `default-list` | entity id | list id | `fetchMemorixListForEntity` must resolve |
+| `default-item` | entity id | item id | `fetchMemorixItemForEntity` must resolve |
+| `entity-list` | list id | entity name | List fields ⊆ entity properties |
+| `entity-item` | item id | entity name | Item fields human-readable on entity |
+| `relation:*` | entity | target entity | Graph tools and `includeRelations` |
+| `mapping-entity` | mapping id | `entityType` | Completion target must exist |
+
+### 9.3 Mermaid (shipped seed)
+
+```mermaid
+graph TD
+  assets["entity:assets"]
+  vulns["entity:vulnerabilities"]
+  groups["entity:variabilities-groups"]
+  assets_list["list:Assets"]
+  vulns_list["list:Vulnerabilities"]
+  crit_list["list:Critical Vulnerabilities"]
+  groups_list["list:Vulnerability Groups"]
+  workspace["list:Workspace records"]
+  asset_item["item:Asset Detail"]
+  vuln_item["item:Vulnerability Detail"]
+  group_item["item:Vulnerability Group Detail"]
+
+  assets -->|default-list| assets_list
+  assets -->|default-item| asset_item
+  vulns -->|default-list| vulns_list
+  vulns -->|default-item| vuln_item
+  groups -->|default-list| groups_list
+  groups -->|default-item| group_item
+  assets -->|relation:assetVulnerabilities| vulns
+  vulns -->|relation:affectedAsset| assets
+  vulns -->|relation:vulnerabilityGroup| groups
+  groups -->|relation:groupVulnerabilities| vulns
+  assets_list -->|entity-list| assets
+  vulns_list -->|entity-list| vulns
+  crit_list -->|entity-list| vulns
+  groups_list -->|entity-list| groups
+  asset_item -->|entity-item| assets
+  vuln_item -->|entity-item| vulns
+  group_item -->|entity-item| groups
+```
+
+---
+
+## 10. Who reads / writes what
+
+| Component | `entity` | `list` | `item` | `completion-mappings` | `inventory-policies` |
+|-----------|----------|--------|--------|----------------------|----------------------|
+| `@x12i/memorix-retrieval` | Read | Read | Read | — | — |
+| `@x12i/memorix-descriptors` | R/W | R/W | R/W | R/W | R/W |
+| `@x12i/memorix-completion` | — | — | — | Read (when wired) | — |
+| `@x12i/memorix-explorer` | Via retrieval | Via retrieval | Via retrieval | — | — |
+| Seed CLI (`memorix-retrieval`) | Apply | Apply | Apply | — | — |
+| Seed export/import (`memorix-descriptors`) | Apply | Apply | Apply | Apply | Apply |
+
+---
+
+## 11. Seed preset metadata
+
+| Field | Value |
+|-------|-------|
+| **Preset id** | `memorix-retrieval-descriptors` |
+| **Preset version** | `1` |
+| **Binding** | `{ appId: "memorix", catalogId, access: { canRead: true, canWrite: true } }` |
+| **Input root** | `catalox-seeds/inputs/` (sibling `memorix-retrieval` or local copy) |
+
+**Expected item counts after retrieval seed apply:**
+
+| Catalog | Items |
+|---------|-------|
+| `memorix-entity-descriptors` | 3 |
+| `memorix-list-descriptors` | 5 |
+| `memorix-item-descriptors` | 3 |
+| **Total descriptor items** | **11** |
+
+---
+
+## 12. Legacy & parallel Firebase catalogs (not retrieval seeds)
+
+These appear in Firestore alongside the three descriptor catalogs. **`@x12i/memorix-retrieval` does not read them** for discovery or list/item APIs.
+
+### 12.1 `memorix-entities` (legacy schema inference)
+
+| Aspect | Detail |
+|--------|--------|
+| **Firestore** | `catalogData-memorix-entities-items` |
+| **Why it existed** | Pre-descriptor pipeline: sample Mongo collections and publish inferred field catalogs for Explorer / catalog tooling (`scripts/catalog-memorix-entities.ts`, `schemaVersion: memorix.entity-descriptor.v1`). |
+| **Item shape** | `entityName`, `displayName`, `documentCount`, `collectionFamilies[]`, `dataDescriptors[]` (inferred paths/types), `sourceCollections[]` — **not** `MemorixEntityDescriptor`. |
+| **Live items (9)** | `any`, `assets`, `subnets`, `topology-cidr-graphs`, `topology-subnets`, `topology-vrs`, `topology-zones`, `vulnerabilities`, `vulnerability-groups` |
+| **Why keep in Firebase** | Historical UI and inventory that still point at this catalog; safe to deprecate once nothing lists it. |
+| **Why not use for new work** | Contracts forbid env/collection discovery bypass; retrieval uses `memorix-entity-descriptors` only. Relations belong on entity descriptors, not rows here (see retrieval `EXPLORER-HOST-APIS.md`). |
+
+**Example (`assets` item):** ~42k Mongo docs sampled; families `assets-snapshots`, `assets-scoped`; 67 inferred `dataDescriptors` — parallel to but **not** the same JSON as `memorix-entity-descriptors/assets`.
+
+**Naming trap:** Mongo DB **`memorix-entities`** ≠ Catalox catalog **`memorix-entities`**.
+
+### 12.2 `memorix_entity_content_types` (legacy content-type registry)
+
+| Aspect | Detail |
+|--------|--------|
+| **Firestore** | `catalogData-memorix_entity_content_types-items` (underscore in `catalogId`) |
+| **Why it existed** | `@x12i/xmemory-store` registered suffix/content-type metadata (`sourcePackage`, `suffix`, `editorSlot`, …) before content types lived under each **entity descriptor** `contentTypes` block. |
+| **Live items (15)** | `analytics`, `event_trigger`, `foresights`, `inference`, `inferences`, `narratives`, `raw`, `scoped`, `scoped_data`, `scoped_views`, `scoping_questions`, `snapshots`, `things`, `web`, `web-scoped` |
+| **Why deprecated** | `MEMORIX-CATALOX-CONTRACTS.md` explicitly says: do not introduce `memorix_entity_content_types` for new work — use entity descriptor `contentTypes`. |
+| **Console label** | May show as `-memorix-entity_content_types-items` (mixed hyphen/underscore from `catalogData-` + `memorix_entity_content_types`). |
+
+### 12.3 `knowledge` (Memorix knowledge / skills)
+
+| Aspect | Detail |
+|--------|--------|
+| **Firestore** | `catalogData-knowledge-items` |
+| **`catalogType`** | `memorix` |
+| **Why** | Curated knowledge artifacts (skills, playbooks) with `knowledgeId` — separate from entity/event **payload** descriptors. |
+| **Live items (3)** | `skill-asset-context-analysis`, `skill-asset-exposure-analysis`, `skill-subnet-routed-reachability` |
+| **Shape** | `knowledgeId`, `kind`, `title`, `content`, `status`, `metadata` |
+| **Retrieval** | `target: "knowledge"` on entity descriptors is a coordinated extension; this catalog is not the same as the three descriptor catalogs. |
+
+---
+
+## 13. Operational notes
+
+| Topic | Behavior |
+|-------|----------|
+| **Catalog ensure** | `MEMORIX_ENSURE_DESCRIPTOR_CATALOGS=1` on admin bootstrap calls `ensureMemorixDescriptorCatalogs`. |
+| **Version checks** | `expectedVersion` on mutations reserved; Catalox optimistic version via `assertExpectedCatalogItemVersion`. |
+| **Completion catalog** | Registered in Firebase; `listCatalogItems` may return adapter error — `memorix-descriptors` treats missing/adapter failure as empty when loading snapshot. |
+| **Inventory policies** | Not in Firebase yet; `ignoreCollection` will create catalog + `default` item on first write. |
+| **Slices** | Stored as list descriptors with `kind: "slice"`; same catalog id. |
+| **Knowledge target** | Accepted on entity descriptors and mappings; full ecosystem support is coordinated across packages (see README). |
+| **Contract drift** | `MEMORIX-CATALOX-CONTRACTS.md` lists three descriptor catalogs; this map adds completion + inventory + documents **legacy** Firebase catalogs. |
+
+---
+
+## 14. Quick lookup — catalogId → why (one line)
+
+| `catalogId` | Why it exists |
+|-------------|---------------|
+| `memorix-entity-descriptors` | Defines **what** entities exist, how they map to Mongo, and how they relate. **Use this for retrieval.** |
+| `memorix-list-descriptors` | Defines **how** to list and filter records in tables and workspace views. |
+| `memorix-item-descriptors` | Defines **how** to compose record detail pages and related data. |
+| `memorix-completion-mappings` | Defines **how** source DB rows enrich Memorix `data` without bypassing schema. |
+| `memorix-inventory-policies` | Defines **which** Mongo collections to exclude from orphan/reconcile noise. |
+| `memorix-entities` | **Legacy** — Mongo schema inference / catalog explorer; not descriptor-driven retrieval. |
+| `memorix_entity_content_types` | **Legacy** — global content-type suffix registry (xmemory-store era). |
+| `knowledge` | Memorix **knowledge/skills** documents (`knowledgeId`), not list/item descriptors. |
+
+---
+
+## 15. Related documents
+
+- [MEMORIX-OBJECT-TYPES-AND-TARGETS.md](./MEMORIX-OBJECT-TYPES-AND-TARGETS.md) — **Object types vs targets vs “entity” overload** (read this for naming cleanup)
+- [MEMORIX-CATALOX-CONTRACTS.md](./MEMORIX-CATALOX-CONTRACTS.md) — Descriptor JSON formats and retrieval behavior
+- [MEMORIX-DATABASE-CONVENTIONS.md](./MEMORIX-DATABASE-CONVENTIONS.md) — Mongo databases, envelopes, completion mapping fields
+- [../README.md](../README.md) — `MemorixDescriptorAdmin` API and CLI
+
+**Code anchors:** `src/catalog/ids.ts`, `src/catalog/ensure-catalogs.ts`, `src/seeds/default-seed-spec.ts`, `src/catalox/client.ts` (`CATALOG_BY_KIND`).

package/docs/MEMORIX-CATALOX-CONTRACTS.md

@@ -2,10 +2,13 @@
 
 **Canonical sync document** for all Memorix data packages and Memorix-consuming UIs (Explorer, completion pipelines, ingestion, graph tools).
 
+**Terminology:** **Catalog object types** (e.g. `assets`, `vulnerabilities`) are declared in `memorix-entity-descriptors`. **Storage targets** (`entity`, `event`, `knowledge`) select Mongo databases — not the same as “entity” in the catalog id. Full glossary and rename plan: **[MEMORIX-OBJECT-TYPES-AND-TARGETS.md](./MEMORIX-OBJECT-TYPES-AND-TARGETS.md)**.
 
 | Document | Scope |
 |----------|--------|
 | **This file** | Catalox catalogs, descriptor JSON formats, expected Mongo shape, cross-component behavior |
+| [MEMORIX-OBJECT-TYPES-AND-TARGETS.md](./MEMORIX-OBJECT-TYPES-AND-TARGETS.md) | Object types vs targets; “entity” disambiguation; rename roadmap |
+| [MEMORIX-CATALOX-CATALOG-MAP.md](./MEMORIX-CATALOX-CATALOG-MAP.md) | Per–catalog-id map (Firestore + live inventory) |
 | [MEMORIX-DATABASE-CONVENTIONS.md](./MEMORIX-DATABASE-CONVENTIONS.md) | Database names, collection naming, env vars, record envelope |
 | [DATA-TIER-CONTRACT.md](./DATA-TIER-CONTRACT.md) | What host apps may call (retrieval APIs only) |
 
@@ -67,15 +70,17 @@ If this document and a package disagree, **update both together**.
 
 All Memorix descriptor catalogs live under this app. Peers must use the same `appId` unless a deployment explicitly namespaces apps. `createMemorixRetrieval`, `createMemorixRetrievalFromEnv`, and `createMemorixRetrievalStackFromEnv` resolve the app id via `resolveMemorixAppId()`.
 
-### 2.2 Catalog ids (only these three)
+### 2.2 Catalog ids (descriptor trio + control-plane catalogs)
 
 | Catalog id | Item id field | Title field | Purpose |
 |------------|---------------|-------------|---------|
-| `memorix-entity-descriptors` | `id` | `entityName` | Entity schema: properties, content types, relations, default list/item |
-| `memorix-list-descriptors` | `id` | `title` | Tabular list views |
-| `memorix-item-descriptors` | `id` | `title` | Record detail layout |
+| `memorix-entity-descriptors` | `id` | `entityName` | **Object type** schema: properties, content types, relations, `target`, default list/item (catalog id is legacy — holds event/knowledge types too) |
+| `memorix-list-descriptors` | `id` | `title` | Tabular list views (per object type or workspace) |
+| `memorix-item-descriptors` | `id` | `title` | Record detail layout (per object type) |
 
-Catalogs use **`sourceMode: "native"`** and **`catalogType: "memorix"`** in seed manifests. Do not introduce parallel catalog names (e.g. `memorix_entity_content_types`) for new work.
+`@x12i/memorix-descriptors` also uses `memorix-completion-mappings` and `memorix-inventory-policies` (see [MEMORIX-CATALOX-CATALOG-MAP.md](./MEMORIX-CATALOX-CATALOG-MAP.md)).
+
+Catalogs use **`sourceMode: "native"`** and **`catalogType: "memorix"`** in seed manifests. Do not introduce parallel catalog names (e.g. `memorix_entity_content_types`, legacy `memorix-entities` inference catalog) for new work.
 
 ### 2.3 Item shape in Catalox
 
@@ -116,14 +121,17 @@ If the catalog is empty or Catalox is unreachable, discovery returns `source: "n
 
 Types below mirror `MemorixEntityDescriptor`, `MemorixListDescriptor`, and `MemorixItemDescriptor` in `@x12i/memorix-retrieval`.
 
-### 3.1 Entity descriptor (`memorix-entity-descriptors`)
+### 3.1 Object type descriptor (`memorix-entity-descriptors`)
+
+> TypeScript: `MemorixEntityDescriptor`. Field **`entityName`** = **catalog object type** id (not “only for target entity”). See [MEMORIX-OBJECT-TYPES-AND-TARGETS.md](./MEMORIX-OBJECT-TYPES-AND-TARGETS.md).
 
 **Required top-level fields:**
 
 | Field | Type | Rules |
 |-------|------|-------|
-| `id` | string | Stable catalog item id; usually equals `entityName` |
-| `entityName` | string | Kebab-case domain id (`vulnerabilities`, `variabilities-groups`, `assets`) |
+| `id` | string | Stable catalog item id; usually equals `entityName` (object type) |
+| `entityName` | string | Kebab-case **object type** id (`vulnerabilities`, `variabilities-groups`, `assets`) |
+| `target` | `"entity"` \| `"event"` \| `"knowledge"` | **Storage target** — which Memorix Mongo DB role (default `"entity"`) |
 | `defaultListDescriptorId` | string | **Option A** — id in `memorix-list-descriptors` |
 | `defaultItemDescriptorId` | string | **Option A** — id in `memorix-item-descriptors` |
 | `collectionPrefix` | string | Used with content-type `postfix` when `collection` is omitted |
@@ -136,9 +144,8 @@ Types below mirror `MemorixEntityDescriptor`, `MemorixListDescriptor`, and `Memo
 
 | Field | Type | Default |
 |-------|------|---------|
-| `target` | `"entity"` \| `"event"` | `"entity"` — selects `memorix-entities` vs `memorix-events` |
 | `contentDefaults` | object | Default content-object storage/format |
-| `relations` | object | Cross-entity joins declared on this entity |
+| `relations` | object | Cross–object-type joins (relation `targetEntity` is another object type name) |
 
 **Identity block:**