@x12i/memorix-retrieval 1.22.0 → 1.23.0

package/docs/MEMORIX-DATABASE-CONVENTIONS.md

@@ -209,57 +209,45 @@ All peers should implement the same precedence so local, CI, and production beha
 
 ## Document shape
 
-### Memorix 2.0 record (entity / event / knowledge)
+### Clean Memorix record (entity / event / knowledge)
 
-All Memorix records use the grouped envelope introduced in Memorix 2.0. Version string: `memorix-record.2.0`.
+All Memorix records use the **clean envelope** format. See [`docs/memorix-format.md`](../../docs/memorix-format.md) for the full specification.
+
+The root holds only `_id`, `recordId`, `concept`, the five data buckets, and `_system`. There is no `identity` block, root `lifecycle`, `sourceFacts`, or `concept.name`.
 
 ```json
 {
   "_id": "<ObjectId>",
-  "identity": {
-    "recordId": "<stable logical id>",
-    "target": "entity | event | knowledge",
-    "targetId": "<target-specific id>",
-    "objectType": "<object type>",
-    "contentType": "<snapshots | core | scoped | inferences | ...>",
-    "version": "memorix-record.2.0"
-  },
-  "lifecycle": {
-    "createdAt": "<ISO-8601>",
-    "modifiedAt": "<ISO-8601>",
-    "capturedAt": "<ISO-8601 optional>",
-    "status": "active"
-  },
+  "recordId": "<stable logical id>",
   "concept": {
-    "kind": "<readable kind>",
-    "name": "<primary readable label>",
-    "title": "<optional>"
+    "identifier": { "kind": "<idKind>", "<idKind>": "<value>" },
+    "title": "<human-readable display name>"
   },
   "data": { "... domain fields ..." },
-  "associatedData": { "... snapshot-only related context ..." },
-  "analytics": { "... snapshot-only numeric rollups ..." },
-  "insights": { "... snapshot-only interpretations ..." },
-  "sourceFacts": { "schemaVersion": "sourceFacts.v1", "values": {} },
+  "associatedData": { "... related entity references ..." },
+  "analytics": { "... rollups and counts ..." },
+  "enrichment": { "... external feed values ..." },
+  "insights": { "... AI-generated judgments ..." },
   "_system": {
-    "memorix": {},
-    "provenance": {},
-    "processing": {},
-    "narratives": {}
+    "provenance": { "... source lineage ..." },
+    "lifecycle": [{ "process": "enriched", "processedAt": "<ISO-8601>" }],
+    "_graphRuns": { "<graphId>": { "... graph-run stamp ..." } },
+    "_jobTypeRuns": { "<jobTypeId>": { "... job-type stamp ..." } }
   }
 }
 ```
 
-| Block | Required | Notes |
-|-------|----------|-------|
-| `identity` | Yes | Use `identity.recordId` and `identity.targetId` — not root `entityId` / `eventId` / `recordId` |
-| `lifecycle` | Recommended | Timestamps and record status |
-| `concept` | Snapshots | Readable core label |
-| `data` | Yes | Domain payload; all content types |
-| `associatedData` / `analytics` / `insights` | Snapshots only | Full materialized view blocks |
-| `sourceFacts` | Optional | Raw/opaque source values |
-| `_system` | Recommended | Memorix-managed metadata, provenance, processing |
+| Field / block | Required | Notes |
+|---------------|----------|-------|
+| `recordId` | Yes | Stable logical record id at root — not nested under `identity` |
+| `concept` | Yes | `identifier` (discriminated by `kind`) + `title`; no `concept.name` |
+| `data` | Yes | Domain payload |
+| `associatedData` / `analytics` / `enrichment` / `insights` | Optional | Each value lives in exactly one bucket (five-bucket rule) |
+| `_system` | Recommended | Provenance, lifecycle events, `_graphRuns`, `_jobTypeRuns` |
+
+`objectType` is implied by collection name. `target` (`entity` / `event` / `knowledge`) is implied by database name.
 
-Legacy root fields (`entityId`, `eventId`, `recordId`, `displayName`, `snapshotId`, `_memorix`, root `idField`, etc.) **must not** be written. Provenance belongs under `_system.provenance`.
+**Legacy fields** (`identity`, root `lifecycle`, `sourceFacts`, `concept.name`, flat `entityId` / `eventId`, root `_graphRuns`, etc.) **must not be written**. Provenance belongs under `_system.provenance`.
 
 ### Provenance (under `_system.provenance`)
 
@@ -313,7 +301,7 @@ Tools that enrich Memorix from source data (e.g. `@x12i/memorix-completion`) use
     "collection": "vulnerabilities-information"
   },
   "match": {
-    "targetPath": "entityId",
+    "targetPath": "recordId",
     "sourcePath": "vulnerabilityId"
   },
   "writeRoot": "data",
@@ -330,7 +318,7 @@ Tools that enrich Memorix from source data (e.g. `@x12i/memorix-completion`) use
 | `targetSelector.sourceCollection` | Must match record's source lineage |
 | `source.databaseName` | Source DB; use `{{ENV.*}}` for env-driven deploys |
 | `source.collection` | Source collection to read from |
-| `match.targetPath` | Path on Memorix record (usually `entityId` or `eventId`) |
+| `match.targetPath` | Path on the Memorix record — `recordId`, `concept.identifier.<kind>`, or legacy aliases `entityId` / `eventId` (resolved to `recordId`) |
 | `match.sourcePath` | Path on source document |
 | `writeRoot` | Always `"data"` — never overwrite envelope fields via completion |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/memorix-retrieval",
-  "version": "1.22.0",
+  "version": "1.23.0",
   "description": "Read-side runtime data tier for Memorix: inventory, lists, items, slices, graph, and health",
   "type": "module",
   "main": "./dist/index.js",
@@ -38,7 +38,7 @@
     "@x12i/helpers": "^2.0.0",
     "@x12i/logxer": "^5.1.0",
     "@x12i/memorix-agents": "^1.2.1",
-    "@x12i/memorix-descriptors": "^1.17.0",
+    "@x12i/memorix-descriptors": "^1.19.0",
     "@x12i/xronox": "^3.9.0"
   },
   "devDependencies": {