@x12i/memorix-writer 1.8.1 → 1.9.0

package/README.md

@@ -75,15 +75,39 @@ Override defaults only when you need to:
 
 ## Collection resolution
 
-Writes target **`memorix-entities`**, **`memorix-events`**, or **`memorix-knowledge`** based on the write descriptor (`target.kind`, defaulting from `identity.idField`). Database names follow [Memorix Database Conventions](./docs/MEMORIX-DATABASE-CONVENTIONS.md) (`MEMORIX_ENTITIES_DB`, `MEMORIX_EVENTS_DB`, `MEMORIX_KNOWLEDGE_DB`, …).
+Writes target **`memorix-entities`**, **`memorix-events`**, or **`memorix-knowledge`** based on the write descriptor (`target.kind`, defaulting from the descriptor's `identity.idField` config). Database names follow [Memorix Database Conventions](./docs/MEMORIX-DATABASE-CONVENTIONS.md) (`MEMORIX_ENTITIES_DB`, `MEMORIX_EVENTS_DB`, `MEMORIX_KNOWLEDGE_DB`, …).
 
-Use exactly one identity per write:
+## Identity model
 
-| Target | Identity field |
-|--------|----------------|
-| `entity` | `entityId` |
-| `event` | `eventId` |
-| `knowledge` | `knowledgeId` |
+Every record this package writes uses the `memorix-record.2.0` envelope — a nested `identity` object, not flat top-level id fields:
+
+```json
+{
+  "identity": {
+    "recordId": "rec_...",
+    "target": "entity",
+    "targetId": "10.150.68.31",
+    "objectType": "assets",
+    "contentType": "analysis",
+    "version": "memorix-record.2.0"
+  },
+  "lifecycle": { "createdAt": "...", "modifiedAt": "...", "status": "active" },
+  "concept": { "kind": "assets", "name": "10.150.68.31" },
+  "data": { "...": "..." }
+}
+```
+
+`entityId` / `eventId` / `knowledgeId` are **request-time parameter names** on `writeMemorixRecord` — pass exactly one to say which target and which id value you're writing:
+
+| Target | Request field | Written to |
+|--------|----------------|------------|
+| `entity` | `entityId` | `identity.target: "entity"`, `identity.targetId` |
+| `event` | `eventId` | `identity.target: "event"`, `identity.targetId` |
+| `knowledge` | `knowledgeId` | `identity.target: "knowledge"`, `identity.targetId` |
+
+They are never stored as flat root fields, and there is no client-facing `idField` concept — clients read/write identity via the `identity` object (and, for narrative/search context, the `concept` object). This package will not add a flat-id or `idField` public API even on request, since it would break the `memorix-record.2.0` contract for every downstream consumer. See [MEMORIX-DATABASE-CONVENTIONS.md](./docs/MEMORIX-DATABASE-CONVENTIONS.md#document-shape) for the full shape and rationale.
+
+Internally, `@x12i/memorix-writer` tolerates **reading** older, pre-2.0 records that only have a flat `entityId`/`eventId` (see [docs/GRAPH-RUNS.md § Identity resolution](./docs/GRAPH-RUNS.md#identity-resolution-source-records)) so graph-run tracking keeps working during a tenant's migration window. That fallback is read-only, internal, and not exported — it does not change what gets written, and it is not something applications should rely on or target.
 
 Collection name resolution order:
 
@@ -150,7 +174,7 @@ Shipped write descriptors include `asset-analysis-write` (entity) and corpus hel
 |----|--------|
 | AC-1 | Generic descriptor-driven write |
 | AC-2 | Prefix/postfix collection resolution |
-| AC-3 | Identity: exactly one of `entityId` / `eventId` |
+| AC-3 | Identity: exactly one of `entityId` / `eventId` / `knowledgeId`, written to `identity.targetId` |
 | AC-4 | Default operation `add` |
 | AC-5 | Upsert only when allowed |
 | AC-6 | Patch only when allowed |

package/dist/writer/build-record.d.ts

@@ -2,7 +2,14 @@ import type { MemorixEntityDescriptor } from "../descriptors/entity-descriptor-t
 import type { MemorixWriteDescriptor } from "../descriptors/write-descriptor-types.js";
 import type { ResolvedIdentity } from "../data/identity.js";
 import type { MemorixWriterDefaults } from "../client/types.js";
-export declare const MEMORIX_RECORD_VERSION = "memorix-record.vnext";
+/**
+ * Canonical Memorix record envelope version. Must match the shared spec in
+ * `docs/memorix-format.md` and `@x12i/memorix-retrieval`'s
+ * `MEMORIX-DATABASE-CONVENTIONS.md`. Every record this package writes
+ * (domain writes and graph-run results) is stamped with this value —
+ * never a legacy/interim tag.
+ */
+export declare const MEMORIX_RECORD_VERSION = "memorix-record.2.0";
 export type MemorixWrittenRecordBase = {
     identity: {
         recordId: string;

package/dist/writer/build-record.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build-record.d.ts","sourceRoot":"","sources":["../../src/writer/build-record.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,2CAA2C,CAAC;AACzF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,0CAA0C,CAAC;AACvF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAGhE,eAAO,MAAM,sBAAsB,yBAAyB,CAAC;AAE7D,MAAM,MAAM,wBAAwB,GAAG;IACrC,QAAQ,EAAE;QACR,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,QAAQ,GAAG,OAAO,GAAG,WAAW,CAAC;QACzC,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,EAAE,MAAM,CAAC;QACpB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,SAAS,EAAE;QACT,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,MAAM,EAAE,QAAQ,CAAC;KAClB,CAAC;IACF,OAAO,EAAE;QACP,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC,CAAC;AAUF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAM3E;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAM1D;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEvF;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,eAAe,EAAE,sBAAsB,CAAC;IACxC,MAAM,EAAE,uBAAuB,CAAC;IAChC,QAAQ,EAAE,qBAAqB,CAAC;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAgD1B;AAED,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,IAAI,EAAE,MAAM,EACZ,IAAI,SAAgC,GACnC,IAAI,CAEN"}
+{"version":3,"file":"build-record.d.ts","sourceRoot":"","sources":["../../src/writer/build-record.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,2CAA2C,CAAC;AACzF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,0CAA0C,CAAC;AACvF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAGhE;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,uBAAuB,CAAC;AAE3D,MAAM,MAAM,wBAAwB,GAAG;IACrC,QAAQ,EAAE;QACR,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,QAAQ,GAAG,OAAO,GAAG,WAAW,CAAC;QACzC,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,EAAE,MAAM,CAAC;QACpB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,SAAS,EAAE;QACT,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,MAAM,EAAE,QAAQ,CAAC;KAClB,CAAC;IACF,OAAO,EAAE;QACP,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC,CAAC;AAUF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAM3E;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAM1D;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEvF;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,eAAe,EAAE,sBAAsB,CAAC;IACxC,MAAM,EAAE,uBAAuB,CAAC;IAChC,QAAQ,EAAE,qBAAqB,CAAC;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAgD1B;AAED,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,IAAI,EAAE,MAAM,EACZ,IAAI,SAAgC,GACnC,IAAI,CAEN"}

package/dist/writer/build-record.js

@@ -1,6 +1,13 @@
 import { randomUUID } from "node:crypto";
 import { deepSet } from "../utils/path.js";
-export const MEMORIX_RECORD_VERSION = "memorix-record.vnext";
+/**
+ * Canonical Memorix record envelope version. Must match the shared spec in
+ * `docs/memorix-format.md` and `@x12i/memorix-retrieval`'s
+ * `MEMORIX-DATABASE-CONVENTIONS.md`. Every record this package writes
+ * (domain writes and graph-run results) is stamped with this value —
+ * never a legacy/interim tag.
+ */
+export const MEMORIX_RECORD_VERSION = "memorix-record.2.0";
 function targetFromIdField(idField) {
     if (idField === "eventId")
         return "event";

package/dist/writer/build-record.js.map

@@ -1 +1 @@
-{"version":3,"file":"build-record.js","sourceRoot":"","sources":["../../src/writer/build-record.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"build-record.js","sourceRoot":"","sources":["../../src/writer/build-record.ts"],"names":[],"mappings":"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"}

package/docs/GRAPH-RUNS.md

@@ -54,10 +54,16 @@ Sets terminal `failed` status with `error` and `completedAt`. Call only when `jo
 
 ### `writeGraphRunResult(ref, graphId, opts)` — combined success path
 
-1. Writes the graph result document to the persistency target collection (`<entityName>-<contentType>`).
-   - **`recordIdSource: { generate: true }` (MRX-FRS-002):** always **inserts** a new record with a new `recordId`. Same-entity runs keep the source identity field (`entityId` / `eventId`); cross-entity runs allocate a new identity as well. Optional `link` applies an FK on the result document and verifies the relation descriptor on the result entity.
+1. Writes the graph result document to the persistency target collection (`<entityName>-<contentType>`) as a full `memorix-record.2.0` envelope (`identity` / `lifecycle` / `concept` / `data`) — never a legacy flat shape.
+   - **`recordIdSource: { generate: true }` (MRX-FRS-002):** always **inserts** a new record with a new `identity.recordId`. Same-entity runs keep the source's `identity.targetId`; cross-entity runs allocate a new `identity.targetId` as well. Optional `link` applies an FK on the result document and verifies the relation descriptor on the result entity.
    - **`recordIdSource: "same-as-input"` (deprecated):** upserts/replaces by source id (legacy 1.2.0 behavior).
-2. Stamps the source record `_graphRuns.<graphId>` = `done` + result pointer (using the **new** `recordId` when `generate: true`) + `completedAt`.
+2. Stamps the source record `_graphRuns.<graphId>` = `done` + result pointer (using the **new** `identity.recordId` when `generate: true`) + `completedAt`.
+
+### Identity resolution (source records)
+
+Source lookups are **tolerant**, in probe order: `identity.recordId` → `identity.targetId` → legacy flat `entityId`/`eventId` (pre-`memorix-record.2.0` tenants only) → `_id`. This lets `writeGraphRunResult`, `markGraphRunStarted`, and `markGraphRunFailed` find a record whether it was written under the current `memorix-record.2.0` envelope or an older flat schema, without the caller needing to know which.
+
+This is a **read-time compatibility shim only**. It exists so old data keeps working during migration; it is not part of the public API (no `idField` type or helper is exported from `@x12i/memorix-writer`) and it never changes what gets **written** — new/updated documents always use the nested `identity` object, per [MEMORIX-DATABASE-CONVENTIONS.md](./MEMORIX-DATABASE-CONVENTIONS.md).
 
 **Atomicity (Mongo transaction):** Result upsert and source stamp run inside a single Mongo transaction via `client.startSession().withTransaction()`. If either step fails, both are rolled back. **Requires a transaction-capable Mongo deployment** (replica set or sharded cluster). Standalone Mongo instances will fail at runtime when calling this API.
 
@@ -69,7 +75,7 @@ Sets terminal `failed` status with `error` and `completedAt`. Call only when `jo
 
 Opt-in helper creating recommended compound indexes on the source collection:
 
-- `{ "_graphRuns.<graphId>.status": 1, <idField>: 1 }`
+- `{ "_graphRuns.<graphId>.status": 1, "identity.recordId": 1 }`
 - `{ "_graphRuns.<graphId>.completedAt": 1 }`
 
 ## Retrieval filters (`@x12i/memorix-retrieval`)

package/docs/JOB-TYPE-RUNS.md

@@ -8,6 +8,8 @@ The reserved system field `_jobTypeRuns` is stored **top-level on the Mongo payl
 
 Domain `writeMemorixRecord` operations **must not** accept `_jobTypeRuns` in user input.
 
+Source-record lookups use the same tolerant identity resolution as `_graphRuns` — see [GRAPH-RUNS.md § Identity resolution](./GRAPH-RUNS.md#identity-resolution-source-records).
+
 Shared types and helpers live in `@x12i/memorix-descriptors/types`:
 
 - `JobTypeRunsField`, `GraphRunEntry`
@@ -45,7 +47,7 @@ When `jobTypeId` is provided, stamps both `_graphRuns.<graphId>` and `_jobTypeRu
 
 Opt-in compound indexes for reprocessing filters:
 
-- `{ "_jobTypeRuns.<key>.status": 1, <idField>: 1 }`
+- `{ "_jobTypeRuns.<key>.status": 1, "identity.recordId": 1 }`
 - `{ "_jobTypeRuns.<key>.completedAt": -1 }`
 - `{ "_jobTypeRuns.<key>.status": 1, "_jobTypeRuns.<key>.completedAt": -1 }` (reprocessing)
 

package/docs/MEMORIX-DATABASE-CONVENTIONS.md

@@ -2,6 +2,8 @@
 
 This document defines the shared MongoDB naming and layout conventions for Memorix. All services, pipelines, and tools in the x12i ecosystem should follow these rules so entity data, event data, and source enrichment stay consistent across peers.
 
+> This file is kept in sync with [`@x12i/memorix-retrieval`'s `MEMORIX-DATABASE-CONVENTIONS.md`](https://github.com/x12i/memorix-retrieval/blob/main/docs/MEMORIX-DATABASE-CONVENTIONS.md), which is the canonical copy. If the two disagree, treat the retrieval copy as authoritative and file a fix here.
+
 ## Overview
 
 Memorix uses **three logical database roles**:
@@ -10,7 +12,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 +48,17 @@ 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 target discriminator |
+|--------|----------|-------------|--------------------------------|
+| `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` |
+
+`entityId` / `eventId` / `knowledgeId` are **request-time parameter names** on write/lookup APIs (they tell the writer which target and identity value a call refers to). They are **not** stored as flat top-level Mongo fields — on disk the value lands in `identity.targetId` alongside `identity.target`. See [Document shape](#document-shape) below.
+
+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.
 
@@ -85,7 +94,27 @@ Resolution order matters: **first non-empty value wins**.
 | 4 | `MEMORIX_DB` *(legacy fallback)* |
 | 5 | **Default:** `memorix-events` |
 
-> **Peer rule:** Prefer `MEMORIX_ENTITIES_DB` and `MEMORIX_EVENTS_DB`. Treat `MEMORIX_DB` as a legacy single-database override only.
+#### Knowledge database (`memorix-knowledge`)
+
+| Priority | Variable |
+|----------|----------|
+| 1 | `MEMORIX_KNOWLEDGE_DB` |
+| 2 | `MEMORIX_DB_KNOWLEDGE` |
+| 3 | `memorix_knowledge_db` |
+| 4 | **Default:** `memorix-knowledge` |
+
+Identity target discriminator: `knowledgeId`.
+
+> **Peer rule:** Prefer `MEMORIX_ENTITIES_DB`, `MEMORIX_EVENTS_DB`, and `MEMORIX_KNOWLEDGE_DB`. Treat `MEMORIX_DB` as a legacy single-database override only.
+
+#### Neo / non-default deployments
+
+Some clusters store Memorix data under non-default database names (for example `memorix-neo-entities` / `memorix-neo-events` instead of `memorix-entities` / `memorix-events`). Set:
+
+```bash
+MEMORIX_ENTITIES_DB=memorix-neo-entities
+MEMORIX_EVENTS_DB=memorix-neo-events
+```
 
 ### Source databases
 
@@ -107,6 +136,7 @@ Normalize `entityType` by replacing `-` with `_` and uppercasing.
 |--------|-----------------|----------------------------------------|
 | `entity` | `MEMORIX_ENTITIES_COLLECTION_<ENTITY_TYPE>` | `MEMORIX_ENTITIES_COLLECTION_VULNERABILITY` |
 | `event` | `MEMORIX_EVENTS_COLLECTION_<ENTITY_TYPE>` | `MEMORIX_EVENTS_COLLECTION_VULNERABILITY` |
+| `knowledge` | `MEMORIX_KNOWLEDGE_COLLECTION_<ENTITY_TYPE>` | `MEMORIX_KNOWLEDGE_COLLECTION_PLAYBOOK` |
 
 ## Collection naming
 
@@ -117,7 +147,6 @@ Use **plural, kebab-case** collection names that describe the entity domain.
 | `entityType` | Recommended collection | Accepted fallbacks |
 |--------------|------------------------|--------------------|
 | `vulnerability` | `vulnerabilities` | `vulnerability` |
-| `variabilities-group` | `vulnerability-groups` | `vulnerabilities-groups`, `variabilities-groups` |
 | `assets` | `assets` | — |
 
 **Default heuristic** when nothing else is configured:
@@ -143,6 +172,8 @@ Use `<domain>-events` or `<domain>s-events`.
 <entityType>-events     → e.g. vulnerability-events
 ```
 
+For content-type slices (used by `@x12i/memorix-writer`), collections resolve as `{collectionPrefix}-{postfix}` (e.g. `assets` + `analysis` → `assets-analysis`). See the [memorix-writer README](../README.md#collection-resolution) for the full resolution order.
+
 ### Source collections
 
 Source collections typically use an **`-information`** suffix to distinguish them from Memorix canonical stores:
@@ -150,10 +181,9 @@ Source collections typically use an **`-information`** suffix to distinguish the
 | Source collection | Feeds entity type | Notes |
 |-------------------|-------------------|-------|
 | `vulnerabilities-information` | `vulnerability` | Raw / enriched vulnerability facts |
-| `vulnerability-groups-information` | `variabilities-group` | Group-level enrichment |
 | `assets-information` | `assets` | Asset metadata |
 
-**Peer rule:** Source collection names are referenced in `targetSelector.sourceCollection` on Memorix records and in completion mappings. Keep these strings stable — they are the join key for mapping selection.
+**Peer rule:** Source collection names are referenced in `targetSelector.sourceCollection` in completion mappings and in `_system.provenance.source.collection` on Memorix records. Keep these strings stable — they are the join key for mapping selection.
 
 ## Collection name resolution order
 
@@ -171,48 +201,69 @@ All peers should implement the same precedence so local, CI, and production beha
 
 ## Document shape
 
-### Memorix entity / event document
+### Memorix 2.0 record (entity / event / knowledge)
 
-Documents in `memorix-entities` and `memorix-events` share this layout:
+All Memorix records use the grouped envelope introduced in Memorix 2.0. Version string: `memorix-record.2.0`.
 
 ```json
 {
   "_id": "<ObjectId>",
-  "recordId": "<optional stable id>",
-  "entityId": "<for entity records>",
-  "eventId": "<for event records>",
-  "capturedAt": "<ISO-8601 timestamp>",
-  "data": {
-    "... domain fields ..."
+  "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"
+  },
+  "concept": {
+    "kind": "<readable kind>",
+    "name": "<primary readable label>",
+    "title": "<optional>"
+  },
+  "data": { "... domain fields ..." },
+  "associatedData": { "... snapshot-only related context ..." },
+  "analytics": { "... snapshot-only numeric rollups ..." },
+  "insights": { "... snapshot-only interpretations ..." },
+  "sourceFacts": { "schemaVersion": "sourceFacts.v1", "values": {} },
+  "_system": {
+    "memorix": {},
+    "provenance": {},
+    "processing": {},
+    "narratives": {}
   }
 }
 ```
 
-| Field | Entity | Event | Notes |
-|-------|--------|-------|-------|
-| `_id` | Required | Required | MongoDB primary key |
-| `recordId` | Recommended | Recommended | Logical id; falls back to `_id` string |
-| `entityId` | Required* | Optional | Join key for entity completion |
-| `eventId` | — | Required* | Join key for event completion |
-| `data` | Required | Required | Payload; completion writes here |
-| `modifiedAt` | Optional | Optional | Set by writers on update (ISO-8601) |
-
-\*Required for completion pipelines that match on these paths.
+| 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 |
 
-Legacy field `snapshotId` is still read as a fallback for `recordId` but **must not** be written by new code.
+**Legacy root fields (`entityId`, `eventId`, `recordId`, `displayName`, `snapshotId`, `_memorix`, root `idField`, etc.) must not be written by any package in this monorepo, no matter what a client requests.** `@x12i/memorix-writer` only reads them as a tolerant, read-only fallback when locating pre-2.0 records that predate this envelope (see [GRAPH-RUNS.md § Identity resolution](./GRAPH-RUNS.md#identity-resolution-source-records)); it never writes them and never exposes an `idField` concept in its public API.
 
-### Provenance (logical, not always stored)
-
-Completion and ingestion tools track provenance in memory using:
+### Provenance (under `_system.provenance`)
 
 | Field | Description |
 |-------|-------------|
-| `sourceCollection` | Which source collection this record was enriched from |
-| `sourceDatabase` | Source database name |
+| `source.collection` | Which source collection this record was enriched from |
+| `source.database` | Source database name |
+| `source.server` | Source server label (when applicable) |
 | `sourceId` | Id in the source system |
-| `idField` | Which id field was used when the record was created |
+| `snapshotRecordId` | Snapshot lineage id (snapshots only) |
 
-These align with `targetSelector` in completion mappings.
+These align with `targetSelector` in completion mappings (`targetSelector.sourceCollection` matches `provenance.source.collection`). Source id-field names belong in source lookup paths such as `match.sourcePath`, not in record provenance.
 
 ### Source document
 
@@ -226,7 +277,6 @@ Do **not** write completion results back to source collections unless a separate
 
 ```
 vulnerability
-variabilities-group
 assets
 ```
 
@@ -255,7 +305,7 @@ Tools that enrich Memorix from source data (e.g. `@x12i/memorix-completion`) use
     "collection": "vulnerabilities-information"
   },
   "match": {
-    "targetPath": "entityId",
+    "targetPath": "identity.targetId",
     "sourcePath": "vulnerabilityId"
   },
   "writeRoot": "data",
@@ -270,9 +320,10 @@ Tools that enrich Memorix from source data (e.g. `@x12i/memorix-completion`) use
 | `target` | `"entity"` or `"event"` — selects Memorix database |
 | `targetCollection` | Explicit Memorix collection (recommended) |
 | `targetSelector.sourceCollection` | Must match record's source lineage |
+| `targetSelector.idField` | Name of the **source** document's id field (source documents have no envelope) |
 | `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 — `identity.targetId` (never a root `entityId` / `eventId`) |
 | `match.sourcePath` | Path on source document |
 | `writeRoot` | Always `"data"` — never overwrite envelope fields via completion |
 
@@ -302,10 +353,10 @@ MEMORIX_EVENTS_COLLECTION_VULNERABILITY=vulnerability-events
 When building a new service or tool that touches Memorix:
 
 - [ ] Connect with `MONGO_URI` / `MONGO_CONNECTION_STRING`
-- [ ] Select database via `target`: `entity` → `memorix-entities`, `event` → `memorix-events`
+- [ ] Select database via `target`: `entity` → `memorix-entities`, `event` → `memorix-events`, `knowledge` → `memorix-knowledge`
 - [ ] Respect env precedence documented above
 - [ ] Use recommended collection names or set explicit env overrides
-- [ ] Store domain payload under `data`
+- [ ] Store domain payload under `data`, identity under `identity` — never write root `entityId` / `eventId` / `idField`
 - [ ] Read enrichment from source databases; write only to Memorix target databases
 - [ ] Use stable `sourceCollection` strings for mapping / provenance
 - [ ] Use kebab-case `entityType` values consistently
@@ -313,12 +364,15 @@ When building a new service or tool that touches Memorix:
 
 ## Reference implementation
 
-The canonical resolver logic lives in `@x12i/memorix-completion`:
+Shared env resolution is mirrored across peers:
 
 | Concern | Module |
 |---------|--------|
-| Database name from env | `src/mongo/env.ts` → `resolveMemorixDbName`, `resolveDefaultSourceDbName` |
-| Collection name resolution | `src/mongo/resolve-collection.ts` → `resolveTargetCollectionName` |
-| Record document shape | `src/types.ts` → `MemorixRecord`, `CompletionMapping` |
-
-If this document and the package disagree, **update this document and the package together** — they are intended to stay in sync.
+| Database name from env | `@x12i/memorix-completion` / `@x12i/memorix-retrieval` → `src/mongo/env.ts` → `resolveMemorixDbName`, `resolveDefaultSourceDbName` |
+| Completion collection resolution | `@x12i/memorix-completion` → `src/mongo/resolve-collection.ts` → `resolveTargetCollectionName` |
+| Retrieval collection resolution | `@x12i/memorix-retrieval` → `src/data/collection-name.ts` → `resolveMemorixCollectionName` (descriptor + env override + prefix/postfix heuristic) |
+| Write collection resolution | `@x12i/memorix-writer` → `src/graph-runs/resolve-record-collection.ts` (descriptor-driven; see package README) |
+| Tolerant identity lookup (read-only, backward-compat) | `@x12i/memorix-writer` → `src/data/record-lookup.ts` (internal — not exported) |
+| Record document shape | `@x12i/memorix-completion` → `src/types.ts` → `MemorixRecord`, `CompletionMapping` |
+
+If this document and a package disagree, **update this document and the package together** — they are intended to stay in sync.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/memorix-writer",
-  "version": "1.8.1",
+  "version": "1.9.0",
   "description": "Descriptor-driven write layer for Memorix entity/event records and content objects",
   "type": "module",
   "main": "./dist/index.js",