@x12i/memorix-descriptors 1.4.0 → 1.4.1

package/README.md

@@ -35,6 +35,32 @@ npm install @x12i/xronox
 
 Peer dependencies: `@x12i/catalox` ≥5, `@x12i/memorix-retrieval` ≥1.6, `@x12i/xronox` ≥3.9 (optional).
 
+Install the retrieval peer from the **npm registry** in CI and monorepos — do not use `file:../memorix-retrieval` in `devDependencies` (causes TypeScript circular build errors with the main `"."` export).
+
+---
+
+## Package exports
+
+The main entry re-exports the full write-side surface (mutations, seeds, reconcile, CLI helpers).
+
+**Retrieval-safe subpaths** (module graph never imports `@x12i/memorix-retrieval`) — for `@x12i/memorix-retrieval` and other read-side consumers:
+
+| Subpath | Symbols | Use |
+|---------|---------|-----|
+| `@x12i/memorix-descriptors/types` | `MemorixSliceDescriptor`, `MemorixTarget`, `MemorixInventoryPolicy`, … | Type-only imports |
+| `@x12i/memorix-descriptors/catalog` | `defaultIdFieldForTarget`, `MEMORIX_INVENTORY_POLICIES_CATALOG`, … | Catalog ids |
+| `@x12i/memorix-descriptors/collections/parse` | `parseMemorixCollectionName` | Last-dash collection naming |
+| `@x12i/memorix-descriptors/validation/slice-shape` | `isMemorixSliceDescriptor`, `validateMemorixSliceDescriptorShape` | Slice shape validation |
+| `@x12i/memorix-descriptors/validation/inventory-policy` | `DEFAULT_INVENTORY_POLICY`, `isCollectionIgnored`, … | Inventory ignore policy |
+
+```typescript
+import type { MemorixSliceDescriptor } from "@x12i/memorix-descriptors/types";
+import { defaultIdFieldForTarget } from "@x12i/memorix-descriptors/catalog";
+import { parseMemorixCollectionName } from "@x12i/memorix-descriptors/collections/parse";
+```
+
+Write-side / CLI / Metadata Studio hosts should import from `"."` or use `MemorixDescriptorAdmin`.
+
 ---
 
 ## Bootstrap
@@ -71,6 +97,20 @@ const admin = await createMemorixDescriptorAdminFromEnv();
 // Uses MONGO_URI + Xronox when set (for reconcile / ensureCollection)
 ```
 
+### Control plane (retrieval + descriptors)
+
+For Explorer-like hosts that need both read and write stacks with shared `catalox`, `xronox`, and `appId`:
+
+```typescript
+import { createMemorixControlPlaneFromEnv } from "@x12i/memorix-descriptors";
+
+const { retrieval, descriptors } = await createMemorixControlPlaneFromEnv();
+// retrieval.client  — MemorixRetrievalClient (buildMemorixUnifiedInventory, fetchList, …)
+// descriptors       — MemorixDescriptorAdmin (mutations, reconcile, applyReconcileDraft)
+```
+
+Uses `createMemorixRetrievalStackFromEnv` from `@x12i/memorix-retrieval` internally.
+
 ---
 
 ## Memorix targets
@@ -214,6 +254,37 @@ Content types live under `entityDescriptor.contentTypes` (each resolves to a Mon
 
 ---
 
+### Slice descriptors
+
+Slice descriptors are list-catalog items with `kind: "slice"` (inventory-driven list views).
+
+| Method | Description |
+|--------|-------------|
+| `createSliceDescriptor(input)` | Validate shape + snapshot refs; write to list catalog |
+| `updateSliceDescriptor(sliceId, patch)` | |
+| `removeSliceDescriptor(sliceId)` | |
+| `validateSliceDescriptor(sliceId)` | Shape + entity/field/content-type checks |
+| `previewSliceDescriptor(sliceId)` | Dry-run preview payload |
+
+Also exported: `validateMemorixSliceDescriptorShape`, `validateSliceDescriptorAgainstSnapshot`, `buildSlicePreview` (main entry and `./validation/slice-shape` for shape-only helpers).
+
+---
+
+### Inventory policy
+
+Ignored collections are stored in Catalox catalog `memorix-inventory-policies` (item id `default`).
+
+| Method | Description |
+|--------|-------------|
+| `getInventoryPolicy()` | Load current policy |
+| `updateInventoryPolicy(patch)` | Replace `ignoredCollections` |
+| `ignoreCollection(input)` | Append ignored entry |
+| `unignoreCollection(input)` | Remove ignored entry |
+
+Also exported from `./validation/inventory-policy`: `DEFAULT_INVENTORY_POLICY`, `validateMemorixInventoryPolicy`, `isCollectionIgnored`, `ignoredCollectionKey`.
+
+---
+
 ### Relations
 
 Relations live on the **source** entity descriptor under `relations`.
@@ -267,19 +338,90 @@ Uses `mergeSeedItemScopeIntoUpsertData` from `@x12i/memorix-retrieval` for apply
 
 ### Mongo reconciliation
 
+Uses **`buildMemorixUnifiedInventory`** from `@x12i/memorix-retrieval` (same shape as the Inventory UI). Legacy `buildMemorixCollectionInventory` is no longer used.
+
+```typescript
+const result = await admin.reconcileDescriptorsWithMongo({
+  inventory: unifiedFromRetrieval, // optional — pass what Inventory already loaded
+  inventoryOptions: { sourceLens: "catalox-first", includeExactCounts: true },
+  allowCreateCollection: true,       // create missing Mongo collections (native driver)
+  autoRegisterOrphans: true,         // apply register-entity drafts for parseable orphans
+  skipMongo: true,                   // suggestions only, no Mongo side effects
+});
+```
+
+**Returns:**
+
+```typescript
+{
+  inventory: MemorixUnifiedInventory;
+  issues: MemorixInventoryIssue[];   // same as inventory.issues
+  suggestions: ReconcileSuggestion[];
+  applied: Array<{ kind: string; detail: string }>;
+}
+```
+
+**Suggestion kinds** (aligned with unified inventory issues):
+
+| Kind | Typical issue | Action |
+|------|---------------|--------|
+| `ensure-collection` | `missing-collection` | Create Mongo collection for declared content type |
+| `empty-declared-collection` | `empty-declared-collection` | Informational |
+| `create-descriptor-for-orphan` | `orphan-collection`, `object-missing` | Register new entity descriptor |
+| `add-content-type-for-orphan` | `content-type-missing` | Add content type to existing entity |
+| `fix-collection-binding` | `collection-mismatch` | Patch content type `collection` binding |
+| `ignore-collection` | `unparseable-collection` | Add to inventory ignore policy |
+| `unparseable-collection` | `unparseable-collection` | Informational / manual review |
+
+Requires `MONGO_URI` and Xronox when building inventory internally (via `createMemorixDescriptorAdminFromEnv` or `createMemorixControlPlaneFromEnv`).
+
+---
+
+### Reconcile drafts & apply
+
+Draft builders produce a **`ReconcileDescriptorDraft`** (`suggestedAction` + `draft` payload + `warnings`). Metadata Studio flow: **build draft → dry-run preview → apply**.
+
+| Builder | `suggestedAction` |
+|---------|-------------------|
+| `buildDescriptorDraftFromOrphanCollection(input)` | `registerEntityDescriptor` |
+| `buildAddContentTypeDraftFromCollection(input, snapshot?)` | `addContentType` |
+| `buildFixCollectionBindingDraft(input, snapshot?, env?)` | `updateContentType` |
+| `buildIgnoreCollectionDraft(input)` | `ignoreCollection` |
+
 | Method | Description |
 |--------|-------------|
-| `reconcileDescriptorsWithMongo()` | Uses `buildMemorixCollectionInventory` from retrieval |
+| `buildReconcileDraftForSuggestion(suggestion, snapshot?, env?)` | Map a `ReconcileSuggestion` to a draft (uses builders above) |
+| `applyReconcileDraft(ctx, draft, options?)` | Low-level apply (also `admin.applyReconcileDraft(draft, options?)`) |
 
-Returns `inventory` + `suggestions`:
+Supported apply actions: `registerEntityDescriptor`, `addContentType`, `updateContentType`, `ignoreCollection`. `manualReview` drafts return `MANUAL_REVIEW_REQUIRED`.
 
-- `ensure-collection` — declared in descriptors, missing in Mongo  
-- `empty-declared-collection` — declared but zero documents  
-- `create-descriptor-for-orphan` — Mongo collection with no descriptor  
+```typescript
+const { suggestions } = await admin.reconcileDescriptorsWithMongo({ skipMongo: true });
+const snapshot = await admin.loadSnapshot();
+const draft = buildReconcileDraftForSuggestion(suggestions[0]!, snapshot);
+const preview = await admin.applyReconcileDraft(draft!, { dryRun: true });
+const applied = await admin.applyReconcileDraft(draft!, { dryRun: false });
+```
+
+Also on admin (with snapshot-aware validation): `buildDescriptorDraftFromOrphanCollection`, `buildAddContentTypeDraftFromCollection`, `buildFixCollectionBindingDraft`, `buildIgnoreCollectionDraft`.
+
+---
 
-Descriptors in Catalox remain schema truth; orphans are **suggestions** only (`autoRegisterOrphans` not implemented).
+### Typed mutation dispatcher (optional)
 
-Requires `MONGO_URI` and Xronox when calling `createMemorixDescriptorAdminFromEnv`.
+Single entry for hosts that route mutation requests by operation name (Explorer `POST /metadata/mutations`, CLI, CI):
+
+```typescript
+import { executeDescriptorMutation } from "@x12i/memorix-descriptors";
+
+const result = await executeDescriptorMutation(admin, {
+  operation: "addContentType",
+  input: { entityName: "assets", contentType: { key: "enrichment", postfix: "enrichment", collection: "assets-enrichment" } },
+  options: { dryRun: true },
+});
+```
+
+Dispatches to `MemorixDescriptorAdmin` methods including `applyReconcileDraft`. Unknown operations return `UNKNOWN_OPERATION`.
 
 ---
 
@@ -290,7 +432,7 @@ Binary: `memorix-descriptors` (after `npm run build`).
 | Command | Status |
 |---------|--------|
 | `validate` | ✅ |
-| `reconcile` | ✅ (needs Xronox / `MONGO_URI`) |
+| `reconcile` | ✅ (needs Xronox / `MONGO_URI`; JSON includes `inventory`, `issues`, `suggestions`, `applied`) |
 | `graph [--format mermaid]` | ✅ |
 | `entity register --file <json> [--dry-run]` | ✅ |
 | `content-type add <entity> <key> --postfix <p> [--dry-run]` | ✅ |
@@ -301,16 +443,17 @@ Binary: `memorix-descriptors` (after `npm run build`).
 | `seed export <dir>` | ✅ |
 | `seed import <dir> [--dry-run]` | ✅ |
 
-**Library-only today** (use `MemorixDescriptorAdmin` directly): entity update/remove, property CRUD, content-type update/remove, list/item create/remove, relation CRUD, mapping update/remove, `ensureCollection`, etc.
-
 ```bash
 npx memorix-descriptors validate
+npx memorix-descriptors reconcile --allow-create-collection --auto-register-orphans
 npx memorix-descriptors graph --format mermaid
 npx memorix-descriptors entity register --file ./new-entity.json --dry-run
 npx memorix-descriptors seed export ./catalox-seeds/inputs
 npx memorix-descriptors seed import ./catalox-seeds/inputs --dry-run
 ```
 
+**Library-only today** (use `MemorixDescriptorAdmin` directly): entity update/remove, property CRUD, content-type update/remove, list/item/slice create/remove, relation CRUD, mapping update/remove, inventory policy, `ensureCollection`, reconcile draft builders, `applyReconcileDraft`, `executeDescriptorMutation`, etc.
+
 ---
 
 ## Explorer / host integration
@@ -318,27 +461,38 @@ npx memorix-descriptors seed import ./catalox-seeds/inputs --dry-run
 | UI surface | API |
 |------------|-----|
 | Entity graph canvas | `getDescriptorGraph`, `reconcileDescriptorsWithMongo` |
+| Inventory / Metadata Studio reconcile | `buildMemorixUnifiedInventory` (retrieval) + `reconcileDescriptorsWithMongo`, `buildReconcileDraftForSuggestion`, `applyReconcileDraft` |
 | Add entity wizard | `registerEntityDescriptor` |
 | Column / field editor | `addProperty`, `updateListDescriptor` |
 | Detail layout editor | `updateItemDescriptor` |
+| Slice editor | `createSliceDescriptor`, `validateSliceDescriptor`, `previewSliceDescriptor` |
 | Collection health | `reconcileDescriptorsWithMongo` |
+| Ignore collection | `ignoreCollection`, `buildIgnoreCollectionDraft` |
 | Mapping editor | `registerMapping` |
 | Knowledge tab | Filter entities where `target === "knowledge"` |
+| Generic mutation HTTP | `executeDescriptorMutation` (optional) |
 
-Hosts should **read** via `@x12i/memorix-retrieval` and **write** only through this package.
+Hosts should **read** via `@x12i/memorix-retrieval` and **write** only through this package. Pass pre-built `MemorixUnifiedInventory` into reconcile when the Inventory UI already loaded it.
 
 ---
 
 ## Validation utilities (exported)
 
+### Main entry (`"."`)
+
 Re-exported / extended validators (aligned with retrieval rules, plus `knowledge` target):
 
 - `validateMemorixEntityDescriptor`, `validateMemorixListDescriptor`, `validateMemorixEntityListDescriptor`, `validateMemorixItemDescriptor`
+- `validateMemorixSliceDescriptorShape`, `validateSliceDescriptorAgainstSnapshot`, `buildSlicePreview`, `isMemorixSliceDescriptor`
+- `validateMemorixInventoryPolicy`, `validateIgnoredCollectionEntry`, `isCollectionIgnored`, `DEFAULT_INVENTORY_POLICY`
 - `validatePropertyDescriptor`, `assertListFieldsHumanReadable`
 - `defaultListDescriptorId`, `defaultItemDescriptorId`, `singularizeEntityName`, `isKebabCase`
+- `parseMemorixCollectionName`, `defaultIdFieldForTarget`
 - `DescriptorValidationError`
 
----
+### Retrieval-safe subpaths
+
+See [Package exports](#package-exports). Subpath entry modules do not import `@x12i/memorix-retrieval` (avoids TS5055 cycles when retrieval depends on descriptors).
 
 ## Environment variables
 
@@ -352,6 +506,7 @@ See [`.env.example`](.env.example).
 | `MONGO_URI` | Xronox for reconcile / `ensureCollection` |
 | `MEMORIX_ENTITIES_DB`, `MEMORIX_EVENTS_DB`, `MEMORIX_KNOWLEDGE_DB` | DB names |
 | `MEMORIX_*_COLLECTION_<ENTITY>` | Per-entity collection overrides |
+| `MEMORIX_ENSURE_DESCRIPTOR_CATALOGS=1` | Auto-create descriptor catalogs on `createMemorixDescriptorAdminFromEnv` / control plane bootstrap |
 | `FIRESTORE_LIVE_TESTS=1` | Enable live integration tests |
 
 ---
@@ -364,7 +519,9 @@ npm run test:live # integration tests (reads .env, needs FIRESTORE_LIVE_TESTS=1)
 npm run test:all  # both
 ```
 
-Live tests: Firestore connectivity, validate deployed graph, load smoke entity (`MEMORIX_SMOKE_ENTITY`, default `assets`), catalog listing, graph, collection resolve, dry-run `addProperty`. Reconcile live test requires `MONGO_URI`.
+Live tests: Firestore connectivity, validate deployed graph, load smoke entity (`MEMORIX_SMOKE_ENTITY`, default `assets`), catalog listing, graph, collection resolve, dry-run `addProperty`. Reconcile live test requires `MONGO_URI` and asserts `MemorixUnifiedInventory` shape (`rows`, `issues`, `generatedAt`).
+
+CI (`validate-descriptor-seeds` workflow) runs `npm ci`, installs `@x12i/memorix-retrieval` from npm for the peer dependency, then `npm run build`.
 
 ---
 
@@ -374,19 +531,23 @@ Live tests: Firestore connectivity, validate deployed graph, load smoke entity (
 
 | Area | Coverage |
 |------|----------|
-| Bootstrap | `createMemorixDescriptorAdmin`, `createMemorixDescriptorAdminFromEnv` |
+| Bootstrap | `createMemorixDescriptorAdmin`, `createMemorixDescriptorAdminFromEnv`, `createMemorixControlPlaneFromEnv` |
+| Package exports | Retrieval-safe subpaths (`/types`, `/catalog`, `/collections/parse`, `/validation/slice-shape`, `/validation/inventory-policy`) |
 | Entity lifecycle | Register (atomic list+item), update, soft/hard remove |
 | Content types | Add, update, remove with referential guards |
 | Collections | Resolve, ensure (inventory), rename **plan** |
 | Properties | Add, update, remove with list/item cascade |
 | List / item descriptors | Full CRUD + set default list/item |
+| Slice descriptors | CRUD, validate, preview |
+| Inventory policy | Ignore / unignore collections in Catalox |
 | Relations | Add, update, remove with list/item cascade |
 | Mappings | CRUD + cross-validation (`memorix-completion-mappings`) |
 | Integrity engine | Full-graph validation, dangling refs, forbidden patterns |
 | Descriptor graph | Build + Mermaid export |
 | Seeds | Export/import/manifest; compatible with retrieval inputs layout |
-| Reconcile | Inventory + suggestions; `autoRegisterOrphans`, `allowCreateCollection` (native Mongo `createCollection`) |
-| Dry-run | All mutations |
+| Reconcile | Unified inventory + issues + extended suggestions; `applyReconcileDraft`; `autoRegisterOrphans`, `allowCreateCollection` |
+| Mutation dispatcher | `executeDescriptorMutation` (optional) |
+| Dry-run | All mutations + reconcile apply |
 | Targets | `entity`, `event`, `knowledge` in types and entity validation |
 | Transactions | `executeCataloxWrites` — compensating rollback on mid-batch Catalox failure; `rollbackPlan` on success |
 | Audit | JSONL via `MEMORIX_DESCRIPTORS_AUDIT_LOG` or per-mutation `reason` |
@@ -427,15 +588,15 @@ Live tests: Firestore connectivity, validate deployed graph, load smoke entity (
 |-------|--------|--------|
 | **1** | Bootstrap, validation, entity/content/property CRUD, seeds, dry-run | ✅ Done |
 | **2** | List/item/relation CRUD, cascades, graph | ✅ Done |
-| **3** | Mappings catalog, Mongo reconcile | ✅ Done |
-| **4** | Knowledge target across ecosystem | ✅ Descriptors + retrieval inventory/graph |
-| **5** | Rename/migrate, audit, rollback, CLI parity, CI seeds | ✅ Done (impact-report CLI optional) |
+| **3** | Mappings catalog, Mongo reconcile (unified inventory) | ✅ Done |
+| **4** | Knowledge target, slice descriptors, inventory policy, subpath exports | ✅ Done |
+| **5** | Rename/migrate, audit, rollback, CLI parity, CI seeds, reconcile apply | ✅ Done (impact-report CLI optional) |
 
 ---
 
 ## Related packages
 
-- **@x12i/memorix-retrieval** — read/composition layer (discover, fetchList, fetchItem, collection inventory)
+- **@x12i/memorix-retrieval** — read/composition layer (discover, fetchList, fetchItem, **`buildMemorixUnifiedInventory`**)
 - **@x12i/catalox** — descriptor storage and native catalog APIs
 - **@x12i/memorix-completion** — Memorix payload document writes (not descriptors)
 - **@x12i/xronox** — optional Mongo inventory for reconcile and `ensureCollection`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/memorix-descriptors",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "Manage Memorix entity, list, and item descriptors in Catalox",
   "type": "module",
   "main": "./dist/index.js",