@x12i/memorix-retrieval 1.8.2 → 1.9.2

package/dist/tests/source-provenance.test.js

@@ -0,0 +1,94 @@
+import { describe, expect, it } from "vitest";
+import { isLegacyCatalogId, legacyCatalogSourceRef, mongoPayloadSourceRef, runtimeProjectionSourceRef, } from "../runtime/source-provenance.js";
+import { parseMemorixCollectionName } from "../data/collection-parser.js";
+import { resolveMemorixRecordIdentity } from "../data/record-identity.js";
+import { resolveMemorixTargetBindings } from "../runtime/target-bindings.js";
+import { createMemorixRetrieval } from "../client/create-client.js";
+describe("source provenance", () => {
+    it("creates runtime projection source refs", () => {
+        const source = runtimeProjectionSourceRef("buildMemorixUnifiedInventory", {
+            appId: "memorix",
+            sourceLens: "db-first",
+        });
+        expect(source.sourceClass).toBe("runtime-projection");
+        expect(source.canonicalStatus).toBe("derived");
+        expect(source.generatedBy).toBe("buildMemorixUnifiedInventory");
+        expect(source.generatedAt).toBeTruthy();
+    });
+    it("marks legacy catalogs as not used", () => {
+        expect(isLegacyCatalogId("memorix-entities")).toBe(true);
+        expect(isLegacyCatalogId("memorix-entity-descriptors")).toBe(false);
+        const source = legacyCatalogSourceRef("memorix-entities", "memorix");
+        expect(source.sourceClass).toBe("legacy-catalog-not-used");
+        expect(source.trustWarning).toContain("does not use");
+    });
+    it("creates mongo payload source refs with target and collection", () => {
+        const source = mongoPayloadSourceRef("entity", "memorix-entities", "assets-snapshots", {
+            objectType: "assets",
+            contentType: "snapshots",
+        });
+        expect(source.target).toBe("entity");
+        expect(source.databaseName).toBe("memorix-entities");
+        expect(source.collectionName).toBe("assets-snapshots");
+        expect(source.sourceClass).toBe("mongo-payload");
+    });
+});
+describe("parseMemorixCollectionName", () => {
+    it("uses last-dash rule and exposes objectType alias", () => {
+        const parsed = parseMemorixCollectionName("topology-cidr-graphs-snapshots");
+        expect(parsed.ok).toBe(true);
+        if (parsed.ok) {
+            expect(parsed.objectType).toBe("topology-cidr-graphs");
+            expect(parsed.objectName).toBe("topology-cidr-graphs");
+            expect(parsed.contentType).toBe("snapshots");
+            expect(parsed.parseRule).toBe("last-dash");
+        }
+    });
+});
+describe("resolveMemorixRecordIdentity", () => {
+    it("prefers recordId before target default", () => {
+        const identity = resolveMemorixRecordIdentity("knowledge", {
+            recordId: "k1",
+            knowledgeId: "k2",
+        });
+        expect(identity.recordId).toBe("k1");
+        expect(identity.source).toBe("recordId");
+    });
+    it("uses knowledgeId as target default", () => {
+        const identity = resolveMemorixRecordIdentity("knowledge", { knowledgeId: "k1" });
+        expect(identity.recordId).toBe("k1");
+        expect(identity.identityField).toBe("knowledgeId");
+        expect(identity.source).toBe("target-default");
+    });
+});
+describe("resolveMemorixTargetBindings", () => {
+    it("returns not-configured for missing knowledge DB env", async () => {
+        const client = createMemorixRetrieval({
+            appId: "memorix",
+            catalox: { getCatalogItem: async () => ({ outcome: "not_found" }) },
+            processEnv: {
+                MEMORIX_ENTITIES_DB: "memorix-entities",
+                MEMORIX_EVENTS_DB: "memorix-events",
+            },
+        });
+        const bindings = await resolveMemorixTargetBindings(client);
+        expect(bindings.knowledge.configured).toBe(false);
+        expect(bindings.knowledge.status).toBe("not-configured");
+        expect(bindings.knowledge.warnings.some((w) => w.code === "TARGET_DB_NOT_CONFIGURED")).toBe(true);
+    });
+    it("marks shared physical database across targets", async () => {
+        const client = createMemorixRetrieval({
+            appId: "memorix",
+            catalox: { getCatalogItem: async () => ({ outcome: "not_found" }) },
+            processEnv: {
+                MEMORIX_ENTITIES_DB: "memorix",
+                MEMORIX_EVENTS_DB: "memorix",
+                MEMORIX_KNOWLEDGE_DB: "memorix",
+            },
+        });
+        const bindings = await resolveMemorixTargetBindings(client);
+        expect(bindings.entity.databaseName).toBe("memorix");
+        expect(bindings.event.sharedPhysicalDatabaseWith).toEqual(["entity", "knowledge"]);
+    });
+});
+//# sourceMappingURL=source-provenance.test.js.map

package/dist/tests/source-provenance.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-provenance.test.js","sourceRoot":"","sources":["../../src/tests/source-provenance.test.ts"],"names":[],"mappings":"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"}

package/dist/tests/unified-inventory.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=unified-inventory.test.d.ts.map

package/dist/tests/unified-inventory.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unified-inventory.test.d.ts","sourceRoot":"","sources":["../../src/tests/unified-inventory.test.ts"],"names":[],"mappings":""}

package/dist/tests/unified-inventory.test.js

@@ -0,0 +1,122 @@
+import { describe, expect, it, vi } from "vitest";
+import { createMemorixRetrieval } from "../client/create-client.js";
+import { MEMORIX_ENTITY_DESCRIPTORS_CATALOG } from "../descriptors/catalog-ids.js";
+import { buildMemorixUnifiedInventory } from "../explorer/unified-inventory.js";
+import { assetsEntity, vulnerabilitiesEntity } from "./fixtures.js";
+function mockInventoryCatalox() {
+    const entityItems = [
+        { id: "assets", data: assetsEntity, title: "Assets" },
+        { id: "vulnerabilities", data: vulnerabilitiesEntity, title: "Vulnerabilities" },
+    ];
+    return {
+        getCatalogItem: vi.fn(async (_ctx, catalogId, itemId) => {
+            const map = {
+                assets: assetsEntity,
+                vulnerabilities: vulnerabilitiesEntity,
+            };
+            if (catalogId === MEMORIX_ENTITY_DESCRIPTORS_CATALOG && map[itemId]) {
+                return { outcome: "found", item: { data: map[itemId] } };
+            }
+            return { outcome: "not_found" };
+        }),
+        listCatalogItems: vi.fn(async () => ({
+            items: entityItems,
+            hasMore: false,
+        })),
+    };
+}
+function mockInventoryXronox() {
+    const entityCollections = ["assets-snapshots", "orphan-bucket"];
+    const eventCollections = ["vulnerabilities-snapshots"];
+    const counts = {
+        "assets-snapshots": 5,
+        "orphan-bucket": 2,
+        "vulnerabilities-snapshots": 3,
+    };
+    return {
+        listCollections: vi.fn(async (params) => {
+            if (params.role === "memorix_events") {
+                return { database: "memorix-events", collections: eventCollections.map((name) => ({ name })) };
+            }
+            return { database: "memorix-entities", collections: entityCollections.map((name) => ({ name })) };
+        }),
+        countDocuments: vi.fn(async (params) => counts[params.source] ?? 0),
+        read: vi.fn(async () => [
+            { entityId: "sample-1", name: "Sample One" },
+            { entityId: "sample-2", name: "Sample Two" },
+        ]),
+    };
+}
+function createInventoryClient(processEnv) {
+    return createMemorixRetrieval({
+        appId: "memorix",
+        catalox: mockInventoryCatalox(),
+        xronox: mockInventoryXronox(),
+        processEnv: {
+            MEMORIX_ENTITIES_DB: "memorix-entities",
+            MEMORIX_EVENTS_DB: "memorix-events",
+            ...processEnv,
+        },
+    });
+}
+describe("buildMemorixUnifiedInventory", () => {
+    it("db_first_toggle_returns_db_first_inventory_not_same_graph", async () => {
+        const client = createInventoryClient();
+        const inventory = await buildMemorixUnifiedInventory(client, {
+            sourceLens: "db-first",
+            targets: ["entity", "event"],
+        });
+        expect(inventory.source.sourceClass).toBe("runtime-projection");
+        expect(inventory.sourceLens).toBe("db-first");
+        expect(inventory.rows.length).toBeGreaterThan(0);
+        expect(inventory.rows.some((row) => row.sources.some((s) => s.sourceClass === "mongo-payload"))).toBe(true);
+        const sorted = [...inventory.rows];
+        sorted.sort((a, b) => {
+            const target = a.target.localeCompare(b.target);
+            if (target !== 0)
+                return target;
+            const db = (a.databaseName ?? "").localeCompare(b.databaseName ?? "");
+            if (db !== 0)
+                return db;
+            return (a.collectionName ?? "").localeCompare(b.collectionName ?? "");
+        });
+        expect(inventory.rows.map((r) => r.rowId)).toEqual(sorted.map((r) => r.rowId));
+    });
+    it("target_filter_events_excludes_entity_rows", async () => {
+        const client = createInventoryClient();
+        const inventory = await buildMemorixUnifiedInventory(client, {
+            sourceLens: "db-first",
+            targets: ["event"],
+        });
+        expect(inventory.rows.every((row) => row.target === "event")).toBe(true);
+        expect(inventory.rows.some((row) => row.target === "entity")).toBe(false);
+    });
+    it("knowledge_empty_is_not_fatal", async () => {
+        const client = createInventoryClient();
+        const inventory = await buildMemorixUnifiedInventory(client, {
+            targets: ["entity", "event", "knowledge"],
+        });
+        expect(inventory.targetBindings.knowledge.status).toMatch(/not-configured|empty|connected/);
+        const knowledgeIssues = inventory.issues.filter((issue) => issue.target === "knowledge");
+        expect(knowledgeIssues.every((issue) => issue.severity !== "error")).toBe(true);
+        expect(inventory.warnings.some((w) => w.code === "TARGET_DB_NOT_CONFIGURED")).toBe(true);
+    });
+    it("includes source refs on every row", async () => {
+        const client = createInventoryClient();
+        const inventory = await buildMemorixUnifiedInventory(client);
+        for (const row of inventory.rows) {
+            expect(row.source.sourceClass).toBeTruthy();
+            expect(row.source.generatedAt).toBeTruthy();
+            expect(row.objectType ?? row.objectName).toBeDefined();
+        }
+    });
+    it("attach samples when includeSamples is true", async () => {
+        const client = createInventoryClient();
+        const inventory = await buildMemorixUnifiedInventory(client, {
+            includeSamples: true,
+        });
+        const withData = inventory.rows.filter((row) => (row.counts.exact ?? row.counts.estimated ?? 0) > 0 && row.collectionName);
+        expect(withData.some((row) => (row.samples?.length ?? 0) > 0)).toBe(true);
+    });
+});
+//# sourceMappingURL=unified-inventory.test.js.map

package/dist/tests/unified-inventory.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unified-inventory.test.js","sourceRoot":"","sources":["../../src/tests/unified-inventory.test.ts"],"names":[],"mappings":"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"}

package/docs/DATA-TIER-CONTRACT.md

@@ -44,6 +44,23 @@ Data reads and counts go through **Xronox** (`role: memorix_entities` / `memorix
 
 ---
 
+## Source-aware runtime provenance
+
+Retrieval is the source-aware read engine for Explorer. Every inventory row, health response, raw read, and list result can carry `MemorixRuntimeSourceRef` metadata.
+
+| Export | Purpose |
+|--------|---------|
+| `MemorixRuntimeSourceRef` | Primary runtime provenance type (`sourceClass`, `canonicalStatus`, catalog/Mongo fields) |
+| `RuntimeSourceAware<T>` | Wrapper `{ data, source, sources? }` |
+| `MemorixTargetDbBinding` | Per-target DB status (`connected`, `empty`, `not-configured`, shared physical DB) |
+| `resolveMemorixTargetBindings(client, options?)` | Resolve entity/event/knowledge bindings with warnings |
+| `getSourceAwareMemorixRetrievalHealth(client, options?)` | Full source-aware health (Catalox catalogs, targets, inventory summary) |
+| `legacyCatalogSourceRef` / `isLegacyCatalogId` | Guardrails for legacy catalogs not used in descriptor-driven reads |
+
+List/item responses include optional `source`, `sources`, `descriptorRefs`, `target`, `databaseName`, and `collectionNames` (default: source refs enabled).
+
+---
+
 ## Descriptor-driven reads (primary)
 
 | Export | Purpose |
@@ -94,11 +111,12 @@ List descriptor `filters` with `operator` + `value` are **always applied**; requ
 
 | Export | Purpose |
 |--------|---------|
-| `buildMemorixEntityGraph(client, options?)` | Discovery + counts + relation graph + optional inventory overlay (`nodes`, `inventory`) |
+| `buildMemorixEntityGraph(client, options?)` | Discovery + counts + relation graph + optional `runtimeGraph` (source-aware nodes/edges), `nodes`, `inventory` |
 | `buildMemorixEntitySlices(client, entityName)` | Per–content-type counts for drill-down (includes zero counts) |
 | `buildMemorixCollectionInventory(client, options?)` | Legacy inventory (prefer `buildMemorixUnifiedInventory`) |
 | `orphanNodesFromInventory(entries)` | Group inventory orphans for entity graph canvas |
-| `getMemorixRetrievalHealth(client, options?)` | Catalox + Mongo per-target + descriptor counts + optional inventory summary |
+| `getMemorixRetrievalHealth(client, options?)` | Legacy health shape (wraps source-aware health) |
+| `getSourceAwareMemorixRetrievalHealth(client, options?)` | Source-aware Catalox + Mongo + inventory health |
 | `countMemorixEntityContentTypeDocuments` | Count by entity + content type (descriptor-resolved collection) |
 | `listMemorixEntityContentTypeDocuments` | Paginated raw documents (descriptor-resolved) |
 | `getMemorixEntityContentTypeDocument` | Single document by record id |

package/docs/EXPLORER-HOST-APIS.md

@@ -19,12 +19,13 @@ 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, options?)` — discovery + per–content-type counts + relations. Options: `sourceLens`, `targets`, `includeInventory`, `includeOrphans`, `includeCounts`, `includeSlices`. Returns optional `nodes[]` and `inventory`.
-- `buildMemorixUnifiedInventory(client, options?)` — **preferred** inventory API for Explorer Inventory workspace. Options: `sourceLens` (`catalox-first` \| `db-first`), `targets`, `includeExactCounts`.
+- `buildMemorixEntityGraph(client, options?)` — discovery + per–content-type counts + relations. Options: `sourceLens`, `targets`, `includeInventory`, `includeOrphans`, `includeCounts`, `includeSlices`, `includeSourceRefs`. Returns legacy `entities[]`, optional `nodes[]`, `inventory`, and **`runtimeGraph`** (`MemorixRuntimeGraph` with source refs on every node/edge).
+- `buildMemorixUnifiedInventory(client, options?)` — **preferred** inventory API for Explorer Inventory workspace. Options: `sourceLens` (`catalox-first` \| `db-first`), `targets`, `includeExactCounts`, `includeSamples`.
 - `parseMemorixCollectionName(name)` — last-dash parser for DB-first mode.
 - `fetchMemorixRawCollectionRecords` / `fetchMemorixCollectionRecords` — open records from inventory rows.
-- `fetchMemorixSlices` / `fetchMemorixSliceRecords` — slice descriptor execution.
-- `getMemorixRetrievalHealth(client, { includeInventory })` — operational status for Explorer top bar.
+- `fetchMemorixSlices` / `fetchMemorixSliceRecords` — slice descriptor execution with optional relation expansion per row.
+- `getMemorixRetrievalHealth(client, { includeInventory })` — legacy operational status for Explorer top bar.
+- `getSourceAwareMemorixRetrievalHealth(client, { includeInventory: true })` — source-aware health with target bindings and inventory summary.
 - `buildMemorixCollectionInventory(client, options?)` — legacy inventory (still supported).
 
 ## Collection inventory
@@ -112,7 +113,22 @@ Supports `page`, `includeTotal`, `searchText`, and global `sort` (v1: in-memory
 
 ## Health
 
-- `getMemorixRetrievalHealth(client)` — Mongo ping + discovery sample.
+- `getMemorixRetrievalHealth(client, { includeInventory })` — legacy health shape.
+- `getSourceAwareMemorixRetrievalHealth(client, { includeInventory: true })` — Catalox catalog status, per-target DB bindings (entity/event/knowledge), optional inventory summary, all with `MemorixRuntimeSourceRef`.
+
+## Source provenance (Explorer Source Card)
+
+Every major retrieval result exposes runtime provenance:
+
+| API | Primary `source.sourceClass` |
+|-----|------------------------------|
+| `buildMemorixUnifiedInventory` | `runtime-projection` |
+| `buildMemorixEntityGraph` → `runtimeGraph` | `runtime-projection` |
+| `fetchMemorixList` / `fetchMemorixItem` | `descriptor-backed-runtime-view` |
+| `fetchMemorixRawCollectionRecords` | `raw-db-inspection` |
+| `getSourceAwareMemorixRetrievalHealth` | `runtime-projection` |
+
+Inventory rows include `source`, `sources[]`, `objectType`, `mappingStatus`, and optional `samples` when `includeSamples: true`.
 
 ## Catalox cleanliness
 

package/docs/MEMORIX-CATALOX-CONTRACTS.md

@@ -77,7 +77,19 @@ All Memorix descriptor catalogs live under this app. Peers must use the same `ap
 
 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.
 
-### 2.3 Item shape in Catalox
+### 2.4 Legacy catalogs (not used by retrieval)
+
+Retrieval **does not** treat these as canonical descriptor sources for read-time composition:
+
+| Catalog id | Status |
+|------------|--------|
+| `memorix-entities` | Legacy schema inference — not descriptor-driven retrieval |
+| `memorix_entity_content_types` | Superseded by `contentTypes` on object type descriptors |
+| `knowledge` | Knowledge/skills artifacts — not object type descriptors for `target: knowledge` |
+
+If exposed in debug/source-inspector mode, mark with `sourceClass: "legacy-catalog-not-used"`. Normal list/item/inventory APIs load **`memorix-entity-descriptors`**, **`memorix-list-descriptors`**, and **`memorix-item-descriptors`** only.
+
+### 2.5 Item shape in Catalox
 
 Each catalog item is stored as:
 
@@ -97,7 +109,7 @@ Each catalog item is stored as:
 - Descriptor payload lives in the item **`data`** body when read via Catalox APIs.
 - **Seed apply note:** the Catalox seed CLI upserts `row.data` only, so `scripts/apply-seed-manifest.mjs` merges `scope` into the upsert `data` object. Hosts may see `scope` inside `data` until Catalox stores top-level scope natively; retrieval ignores unknown fields when validating descriptors.
 
-### 2.4 Expected Catalox client behavior
+### 2.6 Expected Catalox client behavior
 
 Peers that integrate with Catalox must support:
 

package/docs/MEMORIX-DATABASE-CONVENTIONS.md

@@ -10,7 +10,7 @@ Memorix uses **three logical database roles**:
 |------|---------|------------------------|
 | **Entities** | Canonical entity records (vulnerabilities, assets, groups, …) | `memorix-entities` |
 | **Events** | Event records derived from or linked to entities | `memorix-events` |
-| **Source** | Upstream operational / enrichment data used to extend Memorix records | *(environment-specific)* |
+| **Knowledge** | Knowledge-tier object payloads when configured | `memorix-knowledge` |
 
 All three may live on the **same MongoDB cluster** (single `MONGO_URI`). They are separated by **database name**, not by connection string.
 
@@ -46,10 +46,15 @@ Packages resolve `memorix-entities`, `memorix-events`, collection names, and ent
 
 Every Memorix record belongs to exactly one **target**:
 
-| Target | Database | Typical use |
-|--------|----------|-------------|
-| `entity` | `memorix-entities` | Stable domain objects (vulnerability, asset, group, …) |
-| `event` | `memorix-events` | Occurrences, detections, or timeline entries |
+| Target | Database | Typical use | Identity field |
+|--------|----------|-------------|----------------|
+| `entity` | `memorix-entities` | Stable domain objects (vulnerability, asset, group, …) | `entityId` |
+| `event` | `memorix-events` | Occurrences, detections, or timeline entries | `eventId` |
+| `knowledge` | `memorix-knowledge` | Knowledge-tier objects when configured | `knowledgeId` |
+
+Multiple logical targets may share one physical database (e.g. `MEMORIX_ENTITIES_DB=memorix`, `MEMORIX_EVENTS_DB=memorix`, `MEMORIX_KNOWLEDGE_DB=memorix`). Retrieval returns separate logical bindings and marks `sharedPhysicalDatabaseWith`.
+
+An empty or unconfigured knowledge target is **non-fatal** — inventory and health return `status: "not-configured"` or `"empty"` with informational warnings.
 
 Tools must declare which target they read or write. Do not mix entity and event documents in the same collection.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/memorix-retrieval",
-  "version": "1.8.2",
+  "version": "1.9.2",
   "description": "Read-side runtime data tier for Memorix: inventory, lists, items, slices, graph, and health",
   "type": "module",
   "main": "./dist/index.js",
@@ -33,7 +33,7 @@
   "dependencies": {
     "@x12i/catalox": "^5.0.0",
     "@x12i/helpers": "^1.7.0",
-    "@x12i/memorix-descriptors": "^1.4.2",
+    "@x12i/memorix-descriptors": "^1.5.0",
     "@x12i/xronox": "^3.9.0"
   },
   "devDependencies": {