@x12i/memorix-retrieval 1.6.4 → 1.8.0

package/docs/MEMORIX-CATALOX-CONTRACTS.md

@@ -136,7 +136,7 @@ Types below mirror `MemorixEntityDescriptor`, `MemorixListDescriptor`, and `Memo
 
 | Field | Type | Default |
 |-------|------|---------|
-| `target` | `"entity"` \| `"event"` | `"entity"` — selects `memorix-entities` vs `memorix-events` |
+| `target` | `"entity"` \| `"event"` \| `"knowledge"` | `"entity"` — selects memorix-entities / memorix-events / memorix-knowledge |
 | `contentDefaults` | object | Default content-object storage/format |
 | `relations` | object | Cross-entity joins declared on this entity |
 
@@ -144,7 +144,7 @@ Types below mirror `MemorixEntityDescriptor`, `MemorixListDescriptor`, and `Memo
 
 ```json
 {
-  "allowedIdFields": ["entityId", "eventId"],
+  "allowedIdFields": ["entityId", "eventId", "knowledgeId"],
   "requiredExactlyOne": true,
   "defaultIdField": "entityId"
 }
@@ -210,6 +210,7 @@ List descriptors are a **discriminated union** by `kind`:
 | Kind | When | Key fields |
 |------|------|------------|
 | *(omit or `"entity"`)* | Per-entity tabular list | `entity`, `leadingContentType`, `fields[]` |
+| `"slice"` | Saved Explorer view / executable slice | Same as entity list + optional `group`, `contentType`, `itemDescriptorId` |
 | `"workspace"` | Cross-entity workspace merge | `fields[]` (column hints), optional `entities`, `listDescriptorByEntity` |
 
 #### 3.2.1 Entity list (`kind` omitted or `"entity"`)
@@ -386,6 +387,7 @@ Documents in Memorix target databases follow [MEMORIX-DATABASE-CONVENTIONS](./ME
   "recordId": "<optional>",
   "entityId": "<for entity-targeted records>",
   "eventId": "<for event-targeted records>",
+  "knowledgeId": "<for knowledge-targeted records>",
   "capturedAt": "<ISO-8601>",
   "data": { "... domain fields referenced by descriptor paths ..." }
 }
@@ -395,7 +397,7 @@ Documents in Memorix target databases follow [MEMORIX-DATABASE-CONVENTIONS](./ME
 
 - Domain payload lives under **`data`** (or content-type-specific `dataRoot`, almost always `data`).
 - Descriptor `source.path` values are **dot paths from the document root** (e.g. `data.assetIp`, not `assetIp` alone).
-- Identity for list pagination and item fetch: **`entityId`** or **`eventId`** as declared on the item descriptor.
+- Identity for list pagination and item fetch: **`entityId`**, **`eventId`**, or **`knowledgeId`** as declared on the item descriptor.
 - Legacy `snapshotId` may be read as `recordId` fallback; do not write it in new code.
 
 ### 4.2 Shipped entity ↔ database mapping

package/docs/MEMORIX-DATABASE-CONVENTIONS.md

@@ -85,7 +85,18 @@ Resolution order matters: **first non-empty value wins**.
 | 4 | `MEMORIX_DB` *(legacy fallback)* |
 | 5 | **Default:** `memorix-events` |
 
-> **Peer rule:** Prefer `MEMORIX_ENTITIES_DB` and `MEMORIX_EVENTS_DB`. Treat `MEMORIX_DB` as a legacy single-database override only.
+#### Knowledge database (`memorix-knowledge`)
+
+| Priority | Variable |
+|----------|----------|
+| 1 | `MEMORIX_KNOWLEDGE_DB` |
+| 2 | `MEMORIX_DB_KNOWLEDGE` |
+| 3 | `memorix_knowledge_db` |
+| 4 | **Default:** `memorix-knowledge` |
+
+Identity field: `knowledgeId`.
+
+> **Peer rule:** Prefer `MEMORIX_ENTITIES_DB`, `MEMORIX_EVENTS_DB`, and `MEMORIX_KNOWLEDGE_DB`. Treat `MEMORIX_DB` as a legacy single-database override only.
 
 #### Neo / non-default deployments
 
@@ -120,6 +131,17 @@ Normalize `entityType` by replacing `-` with `_` and uppercasing.
 |--------|-----------------|----------------------------------------|
 | `entity` | `MEMORIX_ENTITIES_COLLECTION_<ENTITY_TYPE>` | `MEMORIX_ENTITIES_COLLECTION_VULNERABILITY` |
 | `event` | `MEMORIX_EVENTS_COLLECTION_<ENTITY_TYPE>` | `MEMORIX_EVENTS_COLLECTION_VULNERABILITY` |
+| `knowledge` | `MEMORIX_KNOWLEDGE_COLLECTION_<ENTITY_TYPE>` | `MEMORIX_KNOWLEDGE_COLLECTION_PLAYBOOK` |
+
+### Content-type collection naming (retrieval / Explorer)
+
+When content types do not set an explicit `collection`, retrieval uses:
+
+```
+<objectName>-<contentType>
+```
+
+The **last dash** separates object name from content type (object names may contain dashes). See `parseMemorixCollectionName` in `@x12i/memorix-retrieval`.
 
 ## Collection naming
 
@@ -315,7 +337,7 @@ MEMORIX_EVENTS_COLLECTION_VULNERABILITY=vulnerability-events
 When building a new service or tool that touches Memorix:
 
 - [ ] Connect with `MONGO_URI` / `MONGO_CONNECTION_STRING`
-- [ ] Select database via `target`: `entity` → `memorix-entities`, `event` → `memorix-events`
+- [ ] Select database via `target`: `entity` → `memorix-entities`, `event` → `memorix-events`, `knowledge` → `memorix-knowledge`
 - [ ] Respect env precedence documented above
 - [ ] Use recommended collection names or set explicit env overrides
 - [ ] Store domain payload under `data`

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@x12i/memorix-retrieval",
-  "version": "1.6.4",
-  "description": "Descriptor-driven Memorix retrieval layer for lists, items, and content objects",
+  "version": "1.8.0",
+  "description": "Read-side runtime data tier for Memorix: inventory, lists, items, slices, graph, and health",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -24,6 +24,7 @@
     "catalox:seed:memorix-retrieval:apply": "npm run build && node scripts/apply-seed-manifest.mjs",
     "catalox:seed:ensure": "npm run build && node scripts/ensure-catalox-seed.mjs",
     "mongo:check-collections": "node scripts/check-mongo-collections.mjs",
+    "mongo:inventory": "npm run build && node scripts/mongo-inventory.mjs",
     "smoke:retrieval": "npm run build && node scripts/smoke-retrieval.mjs"
   },
   "engines": {
@@ -32,6 +33,7 @@
   "dependencies": {
     "@x12i/catalox": "^5.0.0",
     "@x12i/helpers": "^1.7.0",
+    "@x12i/memorix-descriptors": "^1.3.0",
     "@x12i/xronox": "^3.9.0"
   },
   "devDependencies": {

package/dist/data/xronox-read.d.ts

@@ -1,13 +0,0 @@
-import type { MemorixRetrievalClient } from "../client/types.js";
-import type { XronoxReadParams } from "../client/xronox-like.js";
-import type { MemorixEntityDescriptor } from "../descriptors/descriptor-types.js";
-import type { MemorixTarget } from "../mongo/types.js";
-/** Default Xronox role names for Memorix entity/event databases (see README). */
-export declare const DEFAULT_MEMORIX_XRONOX_ROLES: Record<MemorixTarget, string>;
-export declare function resolveMemorixXronoxRole(entity: MemorixEntityDescriptor, client: MemorixRetrievalClient): string;
-export declare function memorixXronoxRead(client: MemorixRetrievalClient, params: Omit<XronoxReadParams, "dataType" | "sourceType" | "subSourceType"> & {
-    source: string;
-    entity: MemorixEntityDescriptor;
-    role?: string;
-}): Promise<Record<string, unknown>[]>;
-//# sourceMappingURL=xronox-read.d.ts.map

package/dist/data/xronox-read.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"xronox-read.d.ts","sourceRoot":"","sources":["../../src/data/xronox-read.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,oCAAoC,CAAC;AAElF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD,iFAAiF;AACjF,eAAO,MAAM,4BAA4B,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,CAGtE,CAAC;AAEF,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,uBAAuB,EAC/B,MAAM,EAAE,sBAAsB,GAC7B,MAAM,CAGR;AAED,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,sBAAsB,EAC9B,MAAM,EAAE,IAAI,CAAC,gBAAgB,EAAE,UAAU,GAAG,YAAY,GAAG,eAAe,CAAC,GAAG;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,uBAAuB,CAAC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GACA,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAyBpC"}

package/dist/data/xronox-read.js

@@ -1,34 +0,0 @@
-import { resolveEntityTarget } from "../mongo/resolve-db.js";
-/** Default Xronox role names for Memorix entity/event databases (see README). */
-export const DEFAULT_MEMORIX_XRONOX_ROLES = {
-    entity: "operational",
-    event: "logs",
-};
-export function resolveMemorixXronoxRole(entity, client) {
-    const target = resolveEntityTarget(entity);
-    return client.xronoxRoles?.[target] ?? DEFAULT_MEMORIX_XRONOX_ROLES[target];
-}
-export async function memorixXronoxRead(client, params) {
-    const { entity, role: roleOverride, ...readParams } = params;
-    const fullParams = {
-        dataType: "metadata",
-        sourceType: "database",
-        subSourceType: "mongo",
-        role: roleOverride ?? resolveMemorixXronoxRole(entity, client),
-        ...readParams,
-    };
-    if (client.xronox.readArray) {
-        const rows = await client.xronox.readArray(fullParams);
-        return rows.map((r) => r);
-    }
-    const result = await client.xronox.read(fullParams);
-    if (Array.isArray(result)) {
-        return result.map((r) => r);
-    }
-    const rows = [];
-    for await (const row of result) {
-        rows.push(row);
-    }
-    return rows;
-}
-//# sourceMappingURL=xronox-read.js.map

package/dist/data/xronox-read.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"xronox-read.js","sourceRoot":"","sources":["../../src/data/xronox-read.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAG7D,iFAAiF;AACjF,MAAM,CAAC,MAAM,4BAA4B,GAAkC;IACzE,MAAM,EAAE,aAAa;IACrB,KAAK,EAAE,MAAM;CACd,CAAC;AAEF,MAAM,UAAU,wBAAwB,CACtC,MAA+B,EAC/B,MAA8B;IAE9B,MAAM,MAAM,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC3C,OAAO,MAAM,CAAC,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,4BAA4B,CAAC,MAAM,CAAC,CAAC;AAC9E,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,MAA8B,EAC9B,MAIC;IAED,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,GAAG,UAAU,EAAE,GAAG,MAAM,CAAC;IAE7D,MAAM,UAAU,GAAqB;QACnC,QAAQ,EAAE,UAAU;QACpB,UAAU,EAAE,UAAU;QACtB,aAAa,EAAE,OAAO;QACtB,IAAI,EAAE,YAAY,IAAI,wBAAwB,CAAC,MAAM,EAAE,MAAM,CAAC;QAC9D,GAAG,UAAU;KACd,CAAC;IAEF,IAAI,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;QAC5B,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;QACvD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAA4B,CAAC,CAAC;IACvD,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACpD,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1B,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAA4B,CAAC,CAAC;IACzD,CAAC;IACD,MAAM,IAAI,GAA8B,EAAE,CAAC;IAC3C,IAAI,KAAK,EAAE,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC;QAC/B,IAAI,CAAC,IAAI,CAAC,GAA8B,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}