@x12i/memorix-retrieval 1.2.0 → 1.4.0

package/dist/tests/seed-check.test.js

@@ -0,0 +1,47 @@
+import { describe, expect, it, vi } from "vitest";
+import { createMemorixRetrieval } from "../client/create-client.js";
+import { checkMemorixRetrievalSeedNeeds } from "../seeds/check-needs-seed.js";
+import { MEMORIX_ENTITY_DESCRIPTORS_CATALOG } from "../descriptors/catalog-ids.js";
+describe("checkMemorixRetrievalSeedNeeds", () => {
+    it("reports missing catalog items", async () => {
+        const client = createMemorixRetrieval({
+            catalox: {
+                getCatalogItem: vi.fn(),
+                listCatalogItems: vi.fn(async (_ctx, catalogId) => {
+                    if (catalogId === MEMORIX_ENTITY_DESCRIPTORS_CATALOG) {
+                        return { items: [{ id: "assets", data: {} }], hasMore: false };
+                    }
+                    return { items: [], hasMore: false };
+                }),
+            },
+        });
+        const result = await checkMemorixRetrievalSeedNeeds(client, {
+            expected: [
+                {
+                    catalogId: MEMORIX_ENTITY_DESCRIPTORS_CATALOG,
+                    itemIds: ["assets", "vulnerabilities"],
+                },
+            ],
+        });
+        expect(result.needed).toBe(true);
+        expect(result.catalogs[0]?.missingItemIds).toEqual(["vulnerabilities"]);
+    });
+    it("reports ok when all expected items exist", async () => {
+        const client = createMemorixRetrieval({
+            catalox: {
+                getCatalogItem: vi.fn(),
+                listCatalogItems: vi.fn(async () => ({
+                    items: [{ id: "assets", data: {} }],
+                    hasMore: false,
+                })),
+            },
+        });
+        const result = await checkMemorixRetrievalSeedNeeds(client, {
+            expected: [
+                { catalogId: MEMORIX_ENTITY_DESCRIPTORS_CATALOG, itemIds: ["assets"] },
+            ],
+        });
+        expect(result.needed).toBe(false);
+    });
+});
+//# sourceMappingURL=seed-check.test.js.map

package/dist/tests/seed-check.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed-check.test.js","sourceRoot":"","sources":["../../src/tests/seed-check.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAClD,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,EAAE,8BAA8B,EAAE,MAAM,8BAA8B,CAAC;AAC9E,OAAO,EAAE,kCAAkC,EAAE,MAAM,+BAA+B,CAAC;AAEnF,QAAQ,CAAC,gCAAgC,EAAE,GAAG,EAAE;IAC9C,EAAE,CAAC,+BAA+B,EAAE,KAAK,IAAI,EAAE;QAC7C,MAAM,MAAM,GAAG,sBAAsB,CAAC;YACpC,OAAO,EAAE;gBACP,cAAc,EAAE,EAAE,CAAC,EAAE,EAAE;gBACvB,gBAAgB,EAAE,EAAE,CAAC,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE;oBAChD,IAAI,SAAS,KAAK,kCAAkC,EAAE,CAAC;wBACrD,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;oBACjE,CAAC;oBACD,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;gBACvC,CAAC,CAAC;aACH;SACF,CAAC,CAAC;QAEH,MAAM,MAAM,GAAG,MAAM,8BAA8B,CAAC,MAAM,EAAE;YAC1D,QAAQ,EAAE;gBACR;oBACE,SAAS,EAAE,kCAAkC;oBAC7C,OAAO,EAAE,CAAC,QAAQ,EAAE,iBAAiB,CAAC;iBACvC;aACF;SACF,CAAC,CAAC;QAEH,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC,OAAO,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC;IAC1E,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0CAA0C,EAAE,KAAK,IAAI,EAAE;QACxD,MAAM,MAAM,GAAG,sBAAsB,CAAC;YACpC,OAAO,EAAE;gBACP,cAAc,EAAE,EAAE,CAAC,EAAE,EAAE;gBACvB,gBAAgB,EAAE,EAAE,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;oBACnC,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;oBACnC,OAAO,EAAE,KAAK;iBACf,CAAC,CAAC;aACJ;SACF,CAAC,CAAC;QAEH,MAAM,MAAM,GAAG,MAAM,8BAA8B,CAAC,MAAM,EAAE;YAC1D,QAAQ,EAAE;gBACR,EAAE,SAAS,EAAE,kCAAkC,EAAE,OAAO,EAAE,CAAC,QAAQ,CAAC,EAAE;aACvE;SACF,CAAC,CAAC;QAEH,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/tests/seed-manifest.test.d.ts

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

package/dist/tests/seed-manifest.test.d.ts.map

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

package/dist/tests/seed-manifest.test.js

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "vitest";
+import { buildMemorixRetrievalSeedManifest } from "../seeds/build-manifest.js";
+import { MEMORIX_ENTITY_DESCRIPTORS_CATALOG, MEMORIX_LIST_DESCRIPTORS_CATALOG, } from "../descriptors/catalog-ids.js";
+import { mergeSeedItemScopeIntoUpsertData, prepareMemorixRetrievalSeedManifestForCataloxApply, } from "../seeds/merge-for-apply.js";
+import { listExpectedMemorixRetrievalSeedItemIds, MEMORIX_RETRIEVAL_SEED_CATALOGS, } from "../seeds/default-seed-spec.js";
+import { buildMemorixRetrievalSeedManifestFromInputs } from "../seeds/paths.js";
+describe("buildMemorixRetrievalSeedManifest", () => {
+    it("builds preset from input json", async () => {
+        const manifest = await buildMemorixRetrievalSeedManifest({
+            scope: { domains: ["network"], agents: ["neo"] },
+            readJson: async (path) => {
+                const base = path.split("/").pop()?.replace(/\.json$/i, "") ?? path;
+                if (path.startsWith("entity-descriptors/")) {
+                    return { id: base, entityName: base };
+                }
+                if (path.startsWith("list-descriptors/")) {
+                    return { id: base, entity: "assets", title: base };
+                }
+                if (path.startsWith("item-descriptors/")) {
+                    return { id: base, entity: "assets", title: base };
+                }
+                throw new Error(`unexpected ${path}`);
+            },
+        });
+        expect(manifest.presetVersion).toBe(1);
+        expect(manifest.items).toHaveLength(MEMORIX_RETRIEVAL_SEED_CATALOGS.flatMap((c) => c.inputFiles).length);
+        const assetsEntity = manifest.items.find((i) => i.catalogId === MEMORIX_ENTITY_DESCRIPTORS_CATALOG && i.data.id === "assets");
+        expect(assetsEntity).toMatchObject({
+            scope: { domains: ["network"], agents: ["neo"] },
+            data: { id: "assets", entityName: "assets", target: "entity" },
+        });
+        expect(manifest.items.some((i) => i.catalogId === MEMORIX_LIST_DESCRIPTORS_CATALOG)).toBe(true);
+    });
+    it("builds full manifest from shipped catalox-seeds/inputs", async () => {
+        const manifest = await buildMemorixRetrievalSeedManifestFromInputs();
+        expect(manifest.items).toHaveLength(10);
+        expect(manifest.items.every((i) => i.scope.domains.length > 0)).toBe(true);
+    });
+});
+describe("seed merge for apply", () => {
+    it("merges scope into upsert data", () => {
+        expect(mergeSeedItemScopeIntoUpsertData({ id: "assets" }, {
+            domains: ["network"],
+            agents: ["neo"],
+        })).toEqual({
+            id: "assets",
+            scope: { domains: ["network"], agents: ["neo"] },
+        });
+    });
+    it("prepares manifest items for catalox apply", () => {
+        const prepared = prepareMemorixRetrievalSeedManifestForCataloxApply({
+            presetVersion: 1,
+            id: "x",
+            name: "x",
+            description: "x",
+            catalogs: [],
+            descriptors: [],
+            bindings: [],
+            items: [
+                {
+                    catalogId: MEMORIX_ENTITY_DESCRIPTORS_CATALOG,
+                    scope: { domains: ["network"], agents: ["neo"] },
+                    data: { id: "assets" },
+                },
+            ],
+        });
+        expect(prepared.items[0]?.data.scope).toEqual({
+            domains: ["network"],
+            agents: ["neo"],
+        });
+    });
+});
+describe("listExpectedMemorixRetrievalSeedItemIds", () => {
+    it("lists all shipped catalog item ids", () => {
+        const expected = listExpectedMemorixRetrievalSeedItemIds();
+        expect(expected.find((c) => c.catalogId.includes("entity"))?.itemIds).toContain("assets");
+        expect(expected.flatMap((c) => c.itemIds)).toHaveLength(10);
+    });
+});
+//# sourceMappingURL=seed-manifest.test.js.map

package/dist/tests/seed-manifest.test.js.map

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

package/docs/DATA-TIER-CONTRACT.md

@@ -0,0 +1,138 @@
+# Memorix data tier contract
+
+**Reference only** — indexes the public API of `@x12i/memorix-retrieval`. It does not define new runtime behavior; see implementation in `src/index.ts`.
+
+Public API surface for **`@x12i/memorix-retrieval`**. Host apps (Explorer, APIs, tools) should call these exports only — not ad hoc Mongo or env-based entity discovery.
+
+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)
+
+---
+
+## Bootstrap
+
+| Export | Purpose |
+|--------|---------|
+| `createMemorixRetrieval(options)` | Build client with Catalox (+ lazy Mongo from `MONGO_URI`) |
+| `createMemorixRetrievalFromEnv(options)` | Same, connects Mongo up front |
+| `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.
+
+---
+
+## Descriptor-driven reads (primary)
+
+| Export | Purpose |
+|--------|---------|
+| `fetchMemorixList(client, request)` | Paginated list by list descriptor id |
+| `fetchMemorixItem(client, request)` | Record detail by item descriptor id |
+| `fetchMemorixListForEntity(client, { entityName, ... })` | List using entity `defaultListDescriptorId` |
+| `fetchMemorixItemForEntity(client, { entityName, entityId \| eventId, ... })` | Item using entity `defaultItemDescriptorId` |
+
+List requests support `filters`, `searchText`, `sort`, `page`, `includeExtensions`.
+
+List descriptor `filters` with `operator` + `value` are **always applied**; request filters merge on top (same property: request wins).
+
+---
+
+## Discovery and defaults
+
+| Export | Purpose |
+|--------|---------|
+| `discoverMemorixEntities(client)` | List entity descriptors from Catalox (`source: "catalox" \| "none"`) |
+| `loadMemorixEntityDescriptorByName(client, entityName)` | Load full entity descriptor by `entityName` |
+| `loadMemorixEntityDescriptor` / `loadMemorixListDescriptor` / `loadMemorixItemDescriptor` | Load by catalog item id |
+| `resolveDefaultListDescriptorForEntity` / `resolveDefaultItemDescriptorForEntity` | Resolve Option A defaults |
+| `entityDescriptorConnections(entity)` | Relation edges from entity descriptor |
+
+**Forbidden:** env entity lists (`MEMORIX_ENTITY_NAMES`, etc.). Discovery is Catalox-only.
+
+---
+
+## Explorer / graph (optional)
+
+| Export | Purpose |
+|--------|---------|
+| `buildMemorixEntityGraph(client, options?)` | Discovery + counts + relation graph |
+| `buildMemorixEntitySlices(client, entityName)` | Per–content-type counts for drill-down |
+| `getMemorixRetrievalHealth(client)` | Mongo ping + discovery sample |
+| `countMemorixEntityContentTypeDocuments` | Count by entity + content type (descriptor-resolved collection) |
+| `listMemorixEntityContentTypeDocuments` | Paginated raw documents (descriptor-resolved) |
+| `getMemorixEntityContentTypeDocument` | Single document by record id |
+| `listScopedWorkspaceEntityTypes` / `listScopedWorkspaceDocuments` / `countScopedWorkspaceDocuments` | Namespace-scoped cross-entity reads |
+| `resolveScopedWorkspaceNamespace` / `resolveScopedNamespaceFieldPaths` | Scoped workspace env helpers |
+
+Raw reads resolve **entity name + content type** to Mongo via descriptors — they do not accept arbitrary collection names.
+
+---
+
+## Content objects
+
+| Export | Purpose |
+|--------|---------|
+| `fetchMemorixContentObject(client, ...)` | Fetch full content from GCS/S3 via host-injected `contentReaders` |
+| `resolveMemorixContentObject` / `shapeContentForList` / `shapeContentForItem` | Content object parsing and shaping |
+
+---
+
+## Catalox seed helpers (library)
+
+Build/apply logic for default descriptors lives in **`src/seeds/`** and is exported for scripts and host tooling. Runtime retrieval does not seed Catalox automatically.
+
+| Export | Purpose |
+|--------|---------|
+| `buildMemorixRetrievalSeedManifest` | Build preset manifest from `readJson` + scope |
+| `buildMemorixRetrievalSeedManifestFromInputs` | Build from `catalox-seeds/inputs/` on disk |
+| `checkMemorixRetrievalSeedNeeds` | Compare expected vs present catalog item ids |
+| `prepareMemorixRetrievalSeedManifestForCataloxApply` | Merge `scope` into item `data` for Catalox upsert |
+| `listExpectedMemorixRetrievalSeedItemIds` | Expected ids per catalog (10 items shipped) |
+| `MEMORIX_RETRIEVAL_SEED_CATALOGS` | Catalog spec (ids, input files, native fields) |
+
+Scripts (not imported by hosts at runtime):
+
+| Script | Purpose |
+|--------|---------|
+| `scripts/build-seed-manifest.mjs` | Write `catalox-seeds/memorix-retrieval-descriptors.manifest.json` |
+| `scripts/apply-seed-manifest.mjs` | Apply manifest to Catalox |
+| `scripts/ensure-catalox-seed.mjs` | Check + apply only when items missing (`--dry-run`, `--force`, `--build`) |
+
+---
+
+## Advanced / escape hatches
+
+| Export | Purpose |
+|--------|---------|
+| `memorixRead` | Low-level read with entity context (Mongo default; optional Xronox) |
+| `readMemorixCollection` / `countMemorixCollection` / `connectMemorixMongo` | Direct Mongo helpers |
+| `resolveMemorixCollectionName` / `resolveMemorixDbNameForEntity` | Resolution utilities |
+| Env helpers: `resolveMemorixDbName`, `resolveMongoUri`, `targetCollectionEnvKey` | Advanced overrides |
+
+Pass `xronox` to `createMemorixRetrieval` only when injecting a pre-configured Xronox client.
+
+---
+
+## Catalog constants
+
+| Export | Value |
+|--------|-------|
+| `MEMORIX_APP_ID` | `memorix` |
+| `MEMORIX_ENTITY_DESCRIPTORS_CATALOG` | `memorix-entity-descriptors` |
+| `MEMORIX_LIST_DESCRIPTORS_CATALOG` | `memorix-list-descriptors` |
+| `MEMORIX_ITEM_DESCRIPTORS_CATALOG` | `memorix-item-descriptors` |
+
+---
+
+## Host rules
+
+1. **Entity existence** — from `discoverMemorixEntities` only.
+2. **List columns / detail layout** — from list/item descriptors only.
+3. **Mongo targeting** — from entity descriptor `target` + content types; override via env only when documented as advanced.
+4. **No credentials in descriptors** — inject storage clients via `contentReaders`.
+
+Types: `MemorixEntityDescriptor`, `MemorixListDescriptor`, `MemorixItemDescriptor`, `MemorixRetrievalClient`, `FetchMemorixListRequest`, `FetchMemorixItemRequest`, `MemorixRetrievalIssue`.

package/docs/EXPLORER-HOST-APIS.md

@@ -1,6 +1,8 @@
-# Explorer host APIs (v1.2)
+# Explorer host APIs
 
-Optional exports for host applications such as **memorix-explorer** that need graph/count/list operations without going through list/item descriptors.
+Optional exports from **`@x12i/memorix-retrieval`** for host applications such as **memorix-explorer** that need graph, count, or namespace-scoped reads in addition to descriptor-driven list/item APIs.
+
+Full export list: [DATA-TIER-CONTRACT.md](./DATA-TIER-CONTRACT.md).
 
 ## Stack bootstrap
 
@@ -12,22 +14,22 @@ const { client, cataloxBound, appId } = await createMemorixRetrievalStackFromEnv
 });
 ```
 
-Uses `createCataloxFromEnv` + `createCataloxAdapterFromBound` + `createMemorixRetrievalFromEnv` in one call.
+Uses `createCataloxFromEnv` + `createCataloxAdapterFromBound` + `createMemorixRetrievalFromEnv` in one call. App id resolves from option → `CATALOX_APP_ID` → `MEMORIX_APP_ID` → `memorix`.
 
 ## Entity discovery
 
-- `discoverMemorixEntities(client)` — lists `memorix-entity-descriptors` via Catalox, or `MEMORIX_ENTITY_NAMES` env override.
+- `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.
 
 ## Raw collection reads (Explorer compatibility)
 
+Descriptor-resolved reads by **entity name + content type** (not arbitrary collection names):
+
 - `countMemorixEntityContentTypeDocuments`
 - `listMemorixEntityContentTypeDocuments`
 - `getMemorixEntityContentTypeDocument`
 
-Resolve collection names and DB targets from entity descriptors.
-
 ## Scoped workspace
 
 - `listScopedWorkspaceEntityTypes` / `listScopedWorkspaceDocuments` / `countScopedWorkspaceDocuments`