1.38.0 • Published 11h agoCLI

@x12i/memorix-descriptors

Licence

—

Version

1.38.0

Deps

Size

1.5 MB

Vulns

Weekly

Summary Dependency Versions

@x12i/memorix-descriptors

Write-side control plane for Memorix entity, list, and item descriptors — plus content types, collections, relations, and completion mappings — stored in Catalox and consumed by @x12i/memorix-retrieval.

Role in the ecosystem

Hosts (Explorer Admin, CI, CLI, internal tools)
        │
        ▼
@x12i/memorix-descriptors   ← validate, mutate, seed, reconcile (this package)
        │
        ├─ write ──► @x12i/catalox (descriptor catalogs)
        │
        └─ read / inventory ──► @x12i/memorix-retrieval (+ optional @x12i/xronox)

Concern	Package
Load descriptors, compose lists/items, graph, runtime reads	`@x12i/memorix-retrieval`
Create/update/delete descriptors and mappings in Catalox	`@x12i/memorix-descriptors`
Write Memorix payload documents to Mongo	`@x12i/memorix-completion`

Canonical contracts: docs/MEMORIX-CATALOX-CONTRACTS.md, docs/MEMORIX-DATABASE-CONVENTIONS.md. Object types vs storage targets (naming cleanup): docs/MEMORIX-OBJECT-TYPES-AND-TARGETS.md.

Install

npm install @x12i/memorix-descriptors @x12i/catalox
# Optional, for Mongo inventory / reconcile:
npm install @x12i/xronox

Optional peer: @x12i/xronox ≥3.9 for Mongo inventory / reconcile. This package does not depend on @x12i/memorix-retrieval.

Package exports

The main entry re-exports the full write-side surface (mutations, seeds, reconcile, CLI helpers).

Retrieval-safe subpaths — for @x12i/memorix-retrieval and other read-side consumers that must not import the main "." entry (avoids TS5055 cycles):

Subpath	Symbols	Use
`@x12i/memorix-descriptors/types`	`MemorixSliceDescriptor`, `MemorixTarget`, `GraphRunEntry`, `MemorixRecordRef`, `PersistencyTarget`, …	Type-only imports
`@x12i/memorix-descriptors/catalog`	`defaultIdFieldForTarget`, `resolveEntityIdentityField`, `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

import type { MemorixSliceDescriptor } from "@x12i/memorix-descriptors/types";
import { defaultIdFieldForTarget, resolveEntityIdentityField } from "@x12i/memorix-descriptors/catalog";
import { resolveContentTypeCardinality } from "@x12i/memorix-descriptors";
import { parseMemorixCollectionName } from "@x12i/memorix-descriptors/collections/parse";

Write-side / CLI / Metadata Studio hosts should import from "." or use MemorixDescriptorAdmin.

Bootstrap

From a bound Catalox client

import { bindCataloxContext } from "@x12i/catalox";
import {
  createMemorixCataloxFromEnv,
  createMemorixDescriptorAdmin,
  resolveMemorixAppId,
} from "@x12i/memorix-descriptors";

const { catalox } = await createMemorixCataloxFromEnv();
const bound = bindCataloxContext(catalox, {
  appId: resolveMemorixAppId(), // CATALOX_APP_ID → MEMORIX_APP_ID → "memorix"
  actor: { type: "service", id: "memorix-descriptors" },
  superAdmin: true,
});

const admin = createMemorixDescriptorAdmin({
  catalox: bound,
  processEnv: process.env,
});

From environment

import { createMemorixDescriptorAdminFromEnv } from "@x12i/memorix-descriptors";

const admin = await createMemorixDescriptorAdminFromEnv();
// Uses MONGO_URI + MEMORIX_CATALOX_DB (default memorix-catalox) for Catalox metadata
// 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:

import { createMemorixControlPlaneFromEnv } from "@x12i/memorix-descriptors";

const { retrieval, descriptors } = await createMemorixControlPlaneFromEnv();
// retrieval.client  — MemorixRetrievalClient (buildMemorixUnifiedInventory, fetchList, …)
// descriptors       — MemorixDescriptorAdmin (mutations, reconcile, applyReconcileDraft)

Uses shared Catalox + optional Xronox from env — no @x12i/memorix-retrieval import. The retrieval key exposes a compatible { appId, cataloxBound, catalox, client } stack for inventory/reconcile wiring; client is a UnifiedInventoryContext for buildMemorixUnifiedInventory.

Catalog object types and storage targets

Memorix overloads the word entity. Use this split:

Concept	Examples	Where
Catalog object type	`assets`, `vulnerabilities`, `variabilities-groups`	Catalox `memorix-entity-descriptors` (field `entityName` today)
Storage target	`entity`, `event`, `knowledge`	Descriptor field `target` → Mongo DB

Target	Default DB	Identity field	Typical object types
`entity`	`memorix-entities`	`entityId`	`assets`, `variabilities-groups`
`event`	`memorix-events`	`eventId`	`vulnerabilities` (findings / timeline)
`knowledge`	`memorix-knowledge`	`knowledgeId`	`knowledge-playbooks`, `content-documents`

Not the same: Mongo DB memorix-entities, legacy Catalox catalog memorix-entities, and catalog memorix-entity-descriptors are three different things. Full glossary and rename roadmap: docs/MEMORIX-OBJECT-TYPES-AND-TARGETS.md.

This package accepts target: "knowledge" on object type descriptors and mappings. Canonical specs include content-documents (snapshots, extractions, chunks). Corpus conventions: memorix-corpus/README.md.

Catalox catalogs

Do not introduce parallel catalog ids (per contracts).

Catalog id	Descriptor type	Managed by
`memorix-entity-descriptors`	Object type descriptor (legacy catalog id)
`lists`	List descriptor (entity + workspace)
`memorix-item-descriptors`	Item descriptor
`memorix-completion-mappings`	Completion source → target maps	(optional catalog; missing catalog is treated as empty)

App id: memorix (override via CATALOX_APP_ID / MEMORIX_APP_ID).

`MemorixDescriptorAdmin` API

All mutating methods accept DescriptorMutationOptions and return DescriptorMutationResult<T>.

Mutation options

Option	Description
`dryRun`	Validate + build projected graph; no Catalox write
`skipMongo`	Skip collection inventory / ensure steps
`scope`	Catalox seed scope (`domains`, `agents`) merged into item data
`allowCreateCollection`	When `true` and Xronox is configured, report `create-required` for missing collections (does not move data)
`cascade`	Property/relation removal updates list/item field sets (default `true`)
`force`	Hard delete / ignore default list-item guards
`mode`	`soft` \| `hard` for `removeEntityDescriptor`
`reason`	Reserved for audit trail (not persisted yet)
`expectedVersion`	Reserved for optimistic concurrency (not enforced yet)

Mutation result

{
  ok: boolean;           // false if validation/integrity errors on the projected graph
  dryRun: boolean;
  data?: T;
  warnings: string[];
  errors: Array<{ code: string; message: string; path?: string }>;
  cataloxWrites: Array<{ catalogId; itemId; action: "create"|"update"|"delete" }>;
  mongoActions?: Array<{ action; database; collection }>;
  integrity: DescriptorIntegrityReport;
  rollbackPlan?: CataloxWriteAction[];  // reserved — not populated on failed writes yet
}

Every mutation validates against a projected full descriptor graph (in-memory) before writing.

Integrity & graph

Method	Description
`validateMemorixDescriptors()`	Load all catalogs + run referential integrity
`getDescriptorGraph()`	Nodes/edges: entities, lists, items, mappings, relations
`getDescriptorGraphMermaid()`	Mermaid diagram string
`loadSnapshot()`	Raw `DescriptorSnapshot` from Catalox

Integrity checks include: default list/item ids exist; list fields ⊆ entity properties with humanReadable: true; item fields human-readable; content types on properties/lists/items; relation targets; mapping targetCollection / entityType; forbidden process.env in descriptor JSON; dangling relation references.

Also exported: validateDescriptorSnapshot, buildDescriptorGraph, descriptorGraphToMermaid.

Entity descriptors

Method	Description
`registerEntityDescriptor(input)`	Create entity + default `{entity}-main-list` + `{entity}-detail-item` (atomic logical transaction)
`updateEntityDescriptor(entityName, patch)`	Patch defaults, identity, content types, etc. Cannot rename `entityName` / `id`
`removeEntityDescriptor(entityName, options?)`	`soft` (default): deprecated flags; `hard`: delete entity + all list/item for that type, scrub inbound relations / inventory-policy refs / mappings / write descriptors

registerEntityDescriptor input: entityName, target, collectionPrefix, canonicalContentType, optional identity, initialProperties, scope.

Content types & collections

Content types live under entityDescriptor.contentTypes (each resolves to a Mongo collection).

Entity-level join key (identityField): Primary FK linking all content-type collections of an object type. When omitted, defaults to the storage-target id field (entityId, eventId, or knowledgeId). Set explicitly for non-standard keys (e.g. subnetId on subnets). Resolve at runtime with resolveEntityIdentityField(entity).

Content-type cardinality (cardinality): 1:1 = one document per identity; 1:n = many per identity. When omitted: core / snapshots postfixes → 1:1; others → 1:n. Resolve with resolveContentTypeCardinality(ct, contentTypeKey).

Method	Description
`addContentType(entityName, input)`	Add key; at most one `isCanonical: true`
`updateContentType(entityName, key, patch)`	Patch postfix, collection, canonical flag, etc.
`removeContentType(entityName, key)`	Fails if referenced by properties, lists, items, relations, or sole canonical
`resolveCollection(entityName, contentTypeKey)`	Same resolution order as retrieval (explicit → env → `{prefix}-{postfix}`)
`ensureCollection(entityName, contentTypeKey)`	Inventory via Xronox `listCollections`
`planCollectionRename(entityName, contentTypeKey, newName)`	Migration plan only (no data move)

Properties

Method	Description
`addProperty(entityName, key, property, options?)`	Validates `source.contentType`; optional `addToDefaultList` / `addToDefaultItem`
`updateProperty(entityName, key, patch)`	Merge patch
`removeProperty(entityName, key, options?)`	Cascades out of list `fields[]` and item `sections[].fields[]` unless `cascade: false`; fails if used in relation join paths

List descriptors

Method	Description
`createListDescriptor(input)`	Entity list (`kind` omitted or `"entity"`) or workspace list (`kind: "workspace"`)
`updateListDescriptor(id, patch)`
`removeListDescriptor(id)`	Blocked if still entity default unless `force`
`setEntityDefaultList(entityName, listDescriptorId)`	Wire `defaultListDescriptorId` with referential checks
`addListExtension(listId, extension)`	Add multi-collection join
`removeListExtension(listId, contentType)`
`addListAnalyticsField(listId, field)`	Add computed analytics column
`removeListAnalyticsField(listId, field)`
`setListSort(listId, sort[])`	Set compound `defaultSort`

Also dispatchable via executeDescriptorMutation / memorix-catalox-api POST /metadata/mutations.

Item descriptors

Method	Description
`createItemDescriptor(input)`
`updateItemDescriptor(id, patch)`
`removeItemDescriptor(id)`	Blocked if still entity default unless `force`
`setEntityDefaultItem(entityName, itemDescriptorId)`

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.

Method	Description
`addRelation(sourceEntity, relationKey, descriptor)`	Validates target entity + content types
`updateRelation(sourceEntity, relationKey, patch)`
`removeRelation(sourceEntity, relationKey, options?)`	Cascades `includeRelations` on list/item unless `cascade: false`

RelationInput: targetEntity, type, source/target { contentType, path }, optional defaultMode, defaultArrayProperty, targetFields.

Completion mappings

Method	Description
`registerMapping(input)`	Cross-validates `entityType`, `target`, `targetCollection`, field paths
`updateMapping(id, patch)`
`removeMapping(id)`

Shape: MemorixCompletionMapping (see src/types/index.ts and MEMORIX-DATABASE-CONVENTIONS.md).

Seed import / export

Compatible with the standard Memorix catalox-seeds/inputs/ layout (also used by @x12i/memorix-retrieval):

catalox-seeds/inputs/
  entity-descriptors/*.json
  list-descriptors/*.json
  item-descriptors/*.json
  mapping-descriptors/*.json   # optional
  scope.json
  manifest.json                # written on export

Method	Description
`buildDescriptorSeedManifest(scope?)`	Build manifest from current Catalox snapshot
`exportDescriptorSeedInputs(dir, scope?)`	Write inputs layout to disk
`importDescriptorSeedInputs(dir, { dryRun?, scope? })`	Validate + upsert
`applyDescriptorSeedManifest(manifest, { dryRun?, force? })`	Upsert manifest items (scope merged into data)

Uses local mergeSeedItemScopeIntoUpsertData for apply shape.

Mongo reconciliation

Uses buildMemorixUnifiedInventory implemented in this package (same shape as retrieval's Inventory UI). Legacy buildMemorixCollectionInventory is no longer used. Hosts may pass pre-built inventory from @x12i/memorix-retrieval or build via admin.reconcileDescriptorsWithMongo().

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:

{
  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
`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?)`)

Supported apply actions: registerEntityDescriptor, addContentType, updateContentType, ignoreCollection. manualReview drafts return MANUAL_REVIEW_REQUIRED.

Authored narratives catalog (`narratives`)

Optional map on each object-type descriptor, keyed by narrative slug. Each entry uses MemorixNarrativeDefinition:

Field	Type	Description
`kind`	`having-signal` \| `association-common-property`	Required classification
`label`	`string`	Optional display label
`description`	`string`	Optional UI description
`sourceRef`	`string`	Association source (e.g. `assetVulnerabilities`)
`targetEntity`	`string`	Target object type (e.g. `vulnerabilities`)
`property`	`string`	For `association-common-property` — matched property
`value`	`string`	For `association-common-property` — matched value

Persist via updateEntityDescriptor(entity, { narratives }) or seed JSON under entity-descriptors/*.json. Validated by validateNarrativesCatalog / validateNarrativeDefinition. Survives the v2 Catalox round-trip and appears on loadSnapshot().entityDescriptors[<entity>].narratives.

Per-record narrative instances (addedAt, detectedBy, etc.) remain on Mongo documents at narratives.<key> — they are not part of this catalog.

Root envelope property catalog (`rootPropertyCatalog`)

Pipeline-computed catalog of root/envelope keys (outside data) per content type. Distinct from declarative rootProperties (managed snapshot buckets like possiblePaths on subnets).

Each MemorixContentTypeRootProperties entry includes contentType, properties[] (key, valueTypes, presentCount, totalCount, optional internal), computedAt, and fullScan.

Method	Description
`computeRootPropertyCatalog(objectType, options?)`	Full-scan Mongo collections per content type; persist on descriptor. Options: `ttlMs` (default 24h), `contentTypes[]`, `force`

Also exported: scanRootPropertyCatalogForDescriptor, mergeRootPropertyStatsFromDocs, DEFAULT_ROOT_PROPERTY_CATALOG_TTL_MS.

const result = await admin.computeRootPropertyCatalog("assets", { force: true });
// result.rootPropertyCatalog — persisted when not skipped by TTL

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.

Typed mutation dispatcher (optional)

Single entry for hosts that route mutation requests by operation name (Explorer POST /metadata/mutations, CLI, CI):

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.

CLI

Binary: memorix-descriptors (after npm run build).

Command	Status
`validate`
`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]`
`list create --file <json> [--dry-run]`
`list update <id> --file <json> [--dry-run]`
`list add-extension <id> --file <json>`
`list remove-extension <id> <contentType>`
`list add-analytics <id> --file <json>`
`list remove-analytics <id> <field>`
`list set-sort <id> --file <json>`
`item update <id> --file <json> [--dry-run]`
`mapping register --file <json> [--dry-run]`
`seed export <dir>`
`seed import <dir> [--dry-run]`

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

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. 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
validateNarrativesCatalog, validateNarrativeDefinition, validateRootPropertyCatalog
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. Subpath entry modules avoid importing the main "." write-side graph.

Environment variables

See .env.example.

Variable	Purpose
`MONGO_URI`	Mongo cluster for payload data (Xronox) and Catalox metadata
`MEMORIX_CATALOX_DB`	Catalox metadata database (default `memorix-catalox`)
`CATALOX_APP_ID` / `MEMORIX_APP_ID`	App namespace (default `memorix`)
`MEMORIX_ENTITIES_DB`, `MEMORIX_EVENTS_DB`, `MEMORIX_KNOWLEDGE_DB`	Payload DB names
`MEMORIX_*_COLLECTION_<ENTITY>`	Per-entity collection overrides
`MEMORIX_ENSURE_DESCRIPTOR_CATALOGS=1`	Auto-create descriptor catalogs on `createMemorixDescriptorAdminFromEnv` / control plane bootstrap
`MONGO_LIVE_TESTS=1` or `MEMORIX_CATALOX_LIVE_TESTS=1`	Enable live integration tests

Tests

npm test          # unit tests only (no Mongo)
npm run test:live # integration tests (reads .env, needs MONGO_LIVE_TESTS=1)
npm run test:all  # both

Live tests: Mongo/Catalox 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 and npm run build with no retrieval dependency.

Gap analysis (spec vs implementation)

Implemented

Area	Coverage
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	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`
Concurrency	`expectedVersion` optimistic check on Catalox updates
Rename	`renameEntityDescriptor(from, to)` with optional deprecated source
Catalog bootstrap	`ensureMemorixDescriptorCatalogs` on `createMemorixDescriptorAdminFromEnv`
CLI	Full CRUD for entity, content-type, property, list, item, relation, mapping + reconcile flags
CI seeds	`npm run validate:seeds` + GitHub workflow
Tests	Unit + live Catalox suite

Partial

Item	Notes
Mutation `ok` vs `graphValid`	`ok` = Catalox write succeeded; `graphValid` = projected snapshot passes integrity (legacy graphs may differ)
`ensureCollection` via Xronox	Still inventory-only when using Xronox adapter; reconcile/create uses native `mongodb` driver
Completion mappings catalog	Gracefully empty if catalog not seeded in Catalox yet
Retrieval seed npm scripts	Still owned by `@x12i/memorix-retrieval`; this package provides equivalent CLI `seed` commands
Impact report command	Use `validateMemorixDescriptors` + dry-run `removeEntityDescriptor`

Not implemented yet

Item	Notes
Standalone `impact-report` CLI subcommand	Compose validation + dry-run helpers manually today

Explicit non-goals (v1)

Writing Memorix payload documents (stays in @x12i/memorix-completion)
Replacing Catalox storage or building Explorer UI
Runtime list/item composition (stays in @x12i/memorix-retrieval)

Implementation status by phase

Phase	Focus	Status
1	Bootstrap, validation, entity/content/property CRUD, seeds, dry-run	Done
2	List/item/relation CRUD, cascades, graph	Done
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)

@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