@x12i/memorix-format 2.2.2 → 2.3.2

package/docs/memorix-format.md

@@ -1,55 +1,50 @@
 # Memorix Record Format
 
-> **Package split:** Core envelope → [`@x12i/memorix-base-format`](https://www.npmjs.com/package/@x12i/memorix-base-format).  
-> Product open buckets / associations → this package (`@x12i/memorix-format`).  
-> Requirements: [memorix-format-requirements.md](./memorix-format-requirements.md).  
-> Migrate legacy records: `npx memorix-format migrate ./records/`.
+> **Canonical SoT for new work:** [memorix-record/2](./memorix-record-v2.md) (`validateMemorixRecordV2`).  
+> **Present envelope (migration source):** documented below — still enforced by default in writer/pipeline until `MEMORIX_RECORD_FORMAT=v2`.  
+> Core present envelope helpers: [`@x12i/memorix-base-format`](https://www.npmjs.com/package/@x12i/memorix-base-format) (temporary; folding into this package).  
+> Requirements: [memorix-format-requirements.md](./memorix-format-requirements.md).
 
 ## Purpose
 
 A Memorix record is a structured memory object: a stable envelope around domain payload, with clear separation between business data, derived analytics, external enrichment, AI insights, and cross-entity references.
 
-**Present envelope:** `recordId`, `concept` (`title` + `_extIdentifier`), `data`, optional open buckets (`analytics`, `enrichment`, `insights`, `associated*`, …), and `_…` machine roots (`_system.state`, `_system.lifecycle`, …). Open-bucket **names** are not closed — base does not reserve product names.
+**Prefer `memorix-record/2` for all new platform paths.** Present envelope remains for reading/migrating existing data.
 
 ---
 
-## Record envelope
+## Present envelope (migration source)
 
 ```ts
-type MemorixRecord = {
-  _id?: string;              // MongoDB document id (storage only)
-  recordId: string;          // join plumbing across content types (same subject)
+type MemorixRecordPresent = {
+  _id?: string;
+  recordId: string;
   concept: {
     _extIdentifier: { kind: string; key: string; [kindValue: string]: string };
     title: string;
-    // other human/LLM-readable fields allowed
   };
-  data: JsonObject;           // required — native facts
-
+  data: JsonObject;
   analytics?: JsonObject;
   enrichment?: JsonObject;
   insights?: JsonObject;
-  // associated…?: JsonObject[];
-
+  // associated…?: JsonObject[];  // copied payloads — removed in V2
   _system?: {
     state?: "active" | "archived" | "superseded";
     lifecycle?: Array<{ process: string; processedAt: string }>;
-    // …
   };
 };
 ```
 
-Associated properties use the reserved `associated` prefix. **Legacy** short names (`associatedData`, …) may still appear. Prefer `associated<ObjectType><ContentType>` — see [association-format.md](./association-format.md).
-
-Human/LLM readers SHOULD omit root `_…` and `concept._extIdentifier` by default; keep `recordId` for joins.
+Migrate legacy → present: `npx memorix-format migrate`.  
+Migrate present → V2: `npx memorix-format migrate-to-v2 --object-type=… --content-type=… --data-category=…`.
 
-### Migrate tooling (not format law)
+Associated properties use the reserved `associated` prefix on **present** records only. See [association-format.md](./association-format.md). V2 rejects copied association roots.
 
-Use `memorix-format migrate` to convert older envelopes (`identity`, root `lifecycle`, `concept.identifier`, root `_graphRuns`, …) into the present shape. Do not encode past roots in envelope meta.
+Human/LLM readers SHOULD omit root `_…` and `concept._extIdentifier` by default; keep `recordId` for joins.
 
 ---
 
-## Data And Associated Buckets
+## Data And Associated Buckets (present)
 
 Every piece of business data lives in **exactly one** of these buckets (plus the envelope fields above):
 
@@ -58,173 +53,16 @@ Every piece of business data lives in **exactly one** of these buckets (plus the
 | **`data`** | Native facts about the subject itself |
 | **`analytics`** | Numeric rollups computed from other records |
 | **`enrichment`** | External / prior-system values as received |
-| **`insights`** | Judgments, scores, recommendations |
-| **`associatedData`** | Linked snapshot/data content copied from associated records' `data` payloads |
-| **`associatedDiscovery`** | Linked discovery content copied from associated records' `data` payloads |
-| **`associatedAnalysis`** | Linked analysis content copied from associated records' `data` payloads |
-| **`associatedSiblings`** | Self-association: other snapshot `data` payloads sharing the same join key; each item includes linked `recordId`. Default cap: 99 items. |
-| **`associatedChildren`** | Parent-to-child association: child `data` payloads whose join key matches the parent; each item includes linked `recordId`. Default cap: 99 items. |
-
-Do not duplicate a value across buckets. When reshaping legacy records, promote `sourceFacts` values into the correct bucket rather than wrapping them.
-
-Associated properties are always arrays and are omitted when no linked data was resolved. Do not write empty arrays, and do not switch between object and array shape. Custom associated content uses the same root-level pattern: `associatedCompliance`, `associatedBusinessContext`, and so on.
-
-**Ranked top associations** use `associatedTop<ObjectType><ContentType>` (e.g. `associatedTopItemsAnalysis`). Candidates are sorted by the linked object type’s `importanceIndicator` (or rule `rankBy`) and capped (default 5). See [association-format.md](./association-format.md).
-
-**Enrichment associations** use `associated<ObjectType>Enrichment` (e.g. `associatedItemGroupsEnrichment`). They copy the linked snapshot’s root `enrichment` bucket as a flat object array — not a separate `*-enrichment` content collection. See [association-format.md](./association-format.md).
-
-Associated items contain the linked record's `data` payload (or `enrichment` / `concept` / root property for the specialized forms). Legacy associations may also include inline `recordId` and `contentType`; v2 associations store traceability in optional item-level `_system.association` metadata. Do not wrap associated items with redundant envelope keys; failure and diagnostic details belong in `<objectType>-failed` collections instead.
-
-**Associated property metadata:** Consumers should prefer Memorix associated-property metadata when available (`@x12i/memorix-associator`). Associated snapshot properties are exposed through managed descriptors plus discovery. Until metadata is available, or when reading older/custom records, fall back to the prefix rule: root-level fields on snapshots whose names start with `associated`. The well-known names `associatedData`, `associatedDiscovery`, and `associatedAnalysis` are conventions only — the complete set comes from metadata plus the `associated*` fallback rule.
-
-When a field can naturally have more than one value, processing contracts use array shape even if the current record has only one value. Join-key recipes (which paths and shapes) are defined on **entity descriptors** for each Catalox object type — not in this format package.
-
----
-
-## Concept
-
-```ts
-type MemorixConcept = {
-  _extIdentifier: {
-    kind: string;
-    /** Primary value — property name matches `kind`. */
-    [kind: string]: string;
-    /**
-     * Deterministic join key: `kind` first, then the kind-named value,
-     * then any other scalar fields in sorted key order, joined by `:`.
-     */
-    key: string;
-  };
-  title: string;
-};
-```
-
-`_extIdentifier` is a discriminated object: `kind` names the id type, and a same-named property holds the value. `key` is required. How `kind` / title are derived for an object type is defined on the **entity descriptor**, not here.
-
-```json
-"concept": {
-  "_extIdentifier": {
-    "kind": "sku",
-    "sku": "SKU-100",
-    "key": "sku:SKU-100"
-  },
-  "title": "Blue widget"
-}
-```
-
-`concept.name` is not used. `concept.identifier` / `identifierKey` are legacy — migrate to `_extIdentifier` / `key`. `title` is the human-readable display name; it may differ from the identifier value.
-
-### Identifier `kind` (illustrative — not format law)
-
-| Object type (abstract) | `kind` | Example |
-|---|---|---|
-| Items | `sku` | `{"kind":"sku","sku":"SKU-100","key":"sku:SKU-100"}` |
-| Groups | `groupCode` | `{"kind":"groupCode","groupCode":"G-42","key":"groupCode:G-42"}` |
-| Locations | `locationCode` | `{"kind":"locationCode","locationCode":"WH-A","key":"locationCode:WH-A"}` |
-| Documents | `docId` | `{"kind":"docId","docId":"DOC-9","key":"docId:DOC-9"}` |
-
-Domain packs (Catalox) may use different `kind` values; those recipes live on descriptors.
-
----
-
-## `_system`
-
-System metadata — provenance, processing history, graph-run stamps — never belongs in `data` or the other business buckets.
-
-```ts
-type MemorixLifecycleEvent = { process: string; processedAt: string };
-
-type MemorixSystemBlock = {
-  state?: "active" | "archived" | "superseded";
-  lifecycle?: MemorixLifecycleEvent[];
-  _graphRuns?: Record<string, GraphRunEntry>;
-  _jobTypeRuns?: Record<string, GraphRunEntry>;
-  provenance?: JsonObject;
-  // other system keys as needed (memorix, scoping, …)
-};
-```
-
-### Lifecycle
-
-Root-level `lifecycle` is gone. Processing events live at `_system.lifecycle`:
-
-```json
-"lifecycle": [
-  { "process": "enriched", "processedAt": "2026-04-05T08:01:15.511Z" }
-]
-```
-
-- Each entry is `{ process, processedAt }`.
-- When `createdAt`, `modifiedAt`, and `capturedAt` are identical (the common snapshot case), emit a single `"enriched"` event rather than three duplicate timestamps.
-- Distinct events (e.g. a future re-enrichment) append as additional array entries.
-- Omit `lifecycle` entirely when no timestamp is known — do not emit an empty array.
-- `_system.state` is the present-tense lifecycle state enum (`active` \| `archived` \| `superseded`).
-
-`_system.provenance.enrichedAt` (when present) is separate provenance metadata about a prior enrichment step, not a substitute for `lifecycle`.
-
-### Graph and job-type runs
-
-`_graphRuns` and `_jobTypeRuns` are stored under `_system`, keyed by graph id and sanitized job-type id respectively. Each entry tracks execution status, timestamps, and result metadata. These fields are written by Memorix writer during graph execution and are not part of the domain payload.
-
-Dot-path references: `_system._graphRuns.<graphId>`, `_system._jobTypeRuns.<jobTypeId>`.
-
----
-
-## Complete example
-
-Abstract item snapshot showing envelope fields and open buckets:
-
-```json
-{
-  "recordId": "rec-item-1",
-  "concept": {
-    "_extIdentifier": {
-      "kind": "sku",
-      "sku": "SKU-100",
-      "key": "sku:SKU-100"
-    },
-    "title": "Blue widget"
-  },
-  "data": {
-    "sku": "SKU-100",
-    "color": "blue",
-    "family": "widgets"
-  },
-  "associatedData": [
-    { "locationCode": "WH-A", "qty": 12 },
-    { "locationCode": "WH-B", "qty": 3 }
-  ],
-  "analytics": {
-    "linkedLocations": { "total": 2 }
-  },
-  "enrichment": {
-    "catalogScore": 0.91,
-    "sourceSystem": "erp-feed"
-  },
-  "insights": {
-    "priority": { "level": "high", "confidence": 0.9 }
-  },
-  "_system": {
-    "state": "active",
-    "provenance": {
-      "source": {
-        "database": "example-db",
-        "collection": "items-rawdata"
-      }
-    },
-    "lifecycle": [
-      { "process": "enriched", "processedAt": "2026-04-05T08:01:15.511Z" }
-    ]
-  }
-}
-```
+| **`insights`** | AI / judgment outputs |
+| **`associated*`** | Copied related payloads (present only; removed in V2) |
 
-Not every record populates every bucket. Non-snapshot content types usually keep substance in `.data` only (SCOPE).
+On **memorix-record/2**, snapshot buckets are optional and **omitted when empty**. Root `associated*` may hold **lightweight refs** only (Option A — still format-valid). **Authoritative relationship storage (Gate G4)** is centralized per-category collections (Candidate C); see `docs/re-factoring-and-ops-agent/RELATIONSHIP-STORAGE-DECISION.md`.
 
 ---
 
-## Migration notes
+## Further reading
 
-- Prefer **`npx memorix-format migrate`** for transforms (dry-run → `--out` → validate). Live Mongo apply is a separate ops step.
-- Historical reshape scripts under `scripts/` are not the recommended path.
-- Thin envelope helpers may still be re-exported from `@x12i/memorix-descriptors`; **format packages are the SOT**.
+- [memorix-record-v2.md](./memorix-record-v2.md) — Gate G2 contract
+- [association-format.md](./association-format.md) — present association naming
+- [memorix-workflow-format.md](./memorix-workflow-format.md) — workflow as sibling content
+- Golden V2 examples: `examples/v2/`

package/docs/memorix-record-v2.md

@@ -0,0 +1,101 @@
+# memorix-record/2
+
+**Status:** Gate G2 contract — preferred source of truth for new platform work.  
+**Package:** `@x12i/memorix-format` (`validateMemorixRecordV2`, `migratePresentToV2`, CLI `validate-v2` / `migrate-to-v2`).
+
+Present-tense envelope docs remain in [memorix-format.md](./memorix-format.md) for migration only.  
+Migration semantics: [migrate-present-to-v2.md](./migrate-present-to-v2.md).
+
+## Envelope
+
+```ts
+type MemorixRecordV2 = {
+  format: "memorix-record/2";
+  recordId: string;
+  revision: number; // starts at 1; increments every successful mutation
+  objectType: string;
+  contentType: string;
+  dataCategory: "entity" | "event" | "knowledge";
+  concept: {
+    title: string;
+    identifiers: {
+      primary: { kind: string; value: string; issuer?: string; normalizedValue?: string };
+      alternates?: Array<...>; // omit when empty
+    };
+  };
+  data: Record<string, unknown>;
+  analytics?: Record<string, unknown>;   // snapshots (and knowledge) only; omit when unused
+  enrichment?: Record<string, unknown>;
+  insights?: Record<string, unknown>;
+  // Option A — lightweight relationship refs remain FORMAT-VALID (G2).
+  // Gate G4 selected authoritative storage = central per-category collections (Candidate C).
+  // associatedPeople?: Array<{
+  //   relationshipDefinitionId: string; // required
+  //   recordId: string;                 // required
+  //   relationshipId?: string;          // optional — deterministically derivable
+  // }>;
+  _system: {
+    state: "active" | "archived" | "superseded";
+    createdAt: string;
+    modifiedAt: string;
+    observedAt?: string;
+    lifecycle?: Array<{ process: string; processedAt: string }>; // omit when empty
+    provenance?: Record<string, unknown>;
+  };
+};
+```
+
+## Locked decisions (Gate G2)
+
+1. **Empty optional snapshot buckets are omitted** — never emit `{}`.
+2. **Workflow is a sibling content record** (`contentType: "workflow"`), not a separate document system.
+3. **Composition** = same `recordId` across content types; not a relationship.
+4. **`_graphRuns` / `_jobTypeRuns` stay off the subject** — operational run ledger owns run history.
+5. **V2 rejects copied related-record payloads.** Root `associated*` may hold **lightweight relationship refs** only: required `relationshipDefinitionId` + `recordId`; optional `relationshipId` (derivable). Without `relationshipDefinitionId` the item is not a relationship. **Option A** (direct-record lightweight `associated*` roots) remains **format-valid** for validation and migration compatibility.
+6. **Authoritative physical relationship storage is Gate G4 Candidate C** — org-prefixed per-category `relationships` collections (`entity` / `event` / `knowledge`). Option A lightweight roots and sibling `relationships` content are **not** the selected authoritative storage model; see `docs/re-factoring-and-ops-agent/RELATIONSHIP-STORAGE-DECISION.md`.
+7. **Present format remains the writer/pipeline default** until cutover (`MEMORIX_RECORD_FORMAT=v2`). All **new** refactor packages and the `ops` harness use V2 exclusively. The env switch is transitional (`DEL-FORMAT-PRESENT-SOT`).
+
+## Revision vs lifecycle
+
+| Rule | Behavior |
+|---|---|
+| Revision | Increments on every successful mutation |
+| Lifecycle | Appended only for meaningful process/state events |
+| Independence | Revision may change with no lifecycle entry |
+| Concurrency | Stale `expectedRevision` is rejected (`checkExpectedRevision`) |
+
+Helpers: `applySuccessfulMutation`, `nextRevision`, `checkExpectedRevision`.
+
+## Discriminators
+
+- Pure structural V2 validation does not invent discriminator values.
+- Content-type **profiles** (from metadata) may declare `path`, `required`, `defaultValue`, `allowedValues`.
+- Missing + profile default → warning `V2-DISCRIMINATOR-DEFAULT` (writers apply default).
+- Missing + required + no default → error `V2-DISCRIMINATOR`.
+
+## Examples
+
+See [`examples/v2/`](../examples/v2/) — includes lifecycle, lightweight refs, analysis/decision/discovery, workflow sibling, relationships-candidate sibling.
+
+## Migrate
+
+```bash
+npx memorix-format migrate-to-v2 ./present.json \
+  --object-type=work-items \
+  --content-type=snapshots \
+  --data-category=entity \
+  --issuer=ops-source
+```
+
+Output includes `v2`, `extractedRelationships`, and `warnings`.
+
+## Writer cutover flag
+
+```bash
+MEMORIX_RECORD_FORMAT=v2   # writer uses validateMemorixRecordV2
+# default: present (legacy paths only)
+```
+
+## Folding `@x12i/memorix-base-format`
+
+Present base validation still depends on `@x12i/memorix-base-format`. That package becomes a temporary re-export after consumers move to `@x12i/memorix-format` / V2, then is deleted (Phase 0 deletion ledger).

package/docs/memorix-workflow-format.md

@@ -1,7 +1,19 @@
-# Memorix Workflow Format (`memorix-workflow/1`)
+# Memorix Workflow Format
 
 ## Purpose
 
+**Gate G2:** Workflow is a **sibling content record** on `memorix-record/2` with
+`contentType: "workflow"` and the same `recordId` as the subject — not a separate
+document system. See [memorix-record-v2.md](./memorix-record-v2.md) and
+`examples/v2/work-items-workflow.json`.
+
+Legacy product shape (`memorix-workflow/1`) below remains for migration until
+workflow-api cutover.
+
+---
+
+## Legacy: `memorix-workflow/1`
+
 Versioned JSON for **product workflow state** attached to a subject object via the
 content type `workflow` (collection `{objectType}-workflow`).
 

package/docs/migrate-present-to-v2.md

@@ -0,0 +1,49 @@
+# memorix-record/2 — present → V2 migration semantics
+
+## Result shape
+
+`migratePresentToV2` returns:
+
+```ts
+{
+  ok: boolean;
+  v2: MemorixRecordV2;           // clean V2; no copied associated payloads
+  extractedRelationships: [...]; // out-of-band; NOT persisted (Gate G4)
+  warnings: string[];
+}
+```
+
+## Associated* handling
+
+| Input | V2 record | extractedRelationships |
+|---|---|---|
+| Item with `recordId` (+ copied fields) | `associated*` removed from V2 | status `mapped` or `pending-metadata-resolution`; `droppedPayloadKeys` lists copied fields |
+| Item without target `recordId` | removed | `quarantined-missing-recordId` |
+| Non-array associated* | removed | warning; skipped |
+
+Copied payload is never written onto V2. Resolvable links are never silently discarded.
+
+Optional `associatedPropertyMap: { associatedPeople: "people-assigned-to-work-items" }` supplies `relationshipDefinitionId` when known.
+
+## Timestamps / identifiers
+
+| Situation | Behavior |
+|---|---|
+| `createdAt` missing | default `now`; warning |
+| `modifiedAt` missing | default to `createdAt`/`now`; warning |
+| kind-named value missing | fall back to `value` / key tail / `recordId`; warning |
+| Multiple old identifiers | primary from `_extIdentifier` only; extras not auto-alternates (warning path for future) |
+| Unrecognized roots | dropped with warning |
+| Subject `_graphRuns` etc. | dropped with warning (ops ledger owns run history) |
+
+## Success vs failure
+
+- Migration **succeeds with warnings** when a V2 envelope is produced (`ok: true`) even if relationships are pending/quarantined.
+- Callers should still run `validateMemorixRecordV2(result.v2)`.
+- Migration does not throw on missing association targets; it quarantines.
+
+## Gate G4 boundary
+
+**Authoritative physical relationship storage (Gate G4):** centralized org-prefixed per-category `relationships` collections (Candidate C). See `docs/re-factoring-and-ops-agent/RELATIONSHIP-STORAGE-DECISION.md`.
+
+`migratePresentToV2` still extracts relationship candidates **out-of-band** and does not persist them onto the V2 record. Option A root `associated*` lightweight refs remain **format-valid** but are **not** the selected authoritative storage model.

package/examples/v2/activity-events-snapshots.json

@@ -0,0 +1,31 @@
+{
+  "format": "memorix-record/2",
+  "recordId": "ae-500",
+  "revision": 1,
+  "objectType": "activity-events",
+  "contentType": "snapshots",
+  "dataCategory": "event",
+  "concept": {
+    "title": "status-note on WI-100",
+    "identifiers": {
+      "primary": {
+        "kind": "activityEventId",
+        "value": "AE-500",
+        "issuer": "ops-source"
+      }
+    }
+  },
+  "data": {
+    "workItemId": "WI-100",
+    "actorId": "E-10",
+    "type": "status-note",
+    "message": "Draft outline complete",
+    "occurredAt": "2026-01-15T14:00:00.000Z"
+  },
+  "_system": {
+    "state": "active",
+    "createdAt": "2026-01-15T14:00:00.000Z",
+    "modifiedAt": "2026-01-15T14:00:00.000Z",
+    "observedAt": "2026-01-15T14:00:00.000Z"
+  }
+}

package/examples/v2/employees-discovery.json

@@ -0,0 +1,26 @@
+{
+  "format": "memorix-record/2",
+  "recordId": "employee-10",
+  "revision": 1,
+  "objectType": "employees",
+  "contentType": "discovery",
+  "dataCategory": "entity",
+  "concept": {
+    "title": "Discovery for employee-10",
+    "identifiers": {
+      "primary": {
+        "kind": "recordId",
+        "value": "employee-10"
+      }
+    }
+  },
+  "data": {
+    "discoveryType": "role-cluster",
+    "cluster": "operations"
+  },
+  "_system": {
+    "state": "active",
+    "createdAt": "2026-01-15T16:00:00.000Z",
+    "modifiedAt": "2026-01-15T16:00:00.000Z"
+  }
+}

package/examples/v2/employees-snapshots.json

@@ -0,0 +1,27 @@
+{
+  "format": "memorix-record/2",
+  "recordId": "employee-10",
+  "revision": 1,
+  "objectType": "employees",
+  "contentType": "snapshots",
+  "dataCategory": "entity",
+  "concept": {
+    "title": "Alex Rivera",
+    "identifiers": {
+      "primary": {
+        "kind": "employeeId",
+        "value": "E-10",
+        "issuer": "ops-source"
+      }
+    }
+  },
+  "data": {
+    "role": "operations-lead",
+    "email": "alex@fieldstone.example"
+  },
+  "_system": {
+    "state": "active",
+    "createdAt": "2026-01-10T10:00:00.000Z",
+    "modifiedAt": "2026-01-10T10:00:00.000Z"
+  }
+}

package/examples/v2/procedures-knowledge.json

@@ -0,0 +1,27 @@
+{
+  "format": "memorix-record/2",
+  "recordId": "proc-1",
+  "revision": 1,
+  "objectType": "procedures",
+  "contentType": "snapshots",
+  "dataCategory": "knowledge",
+  "concept": {
+    "title": "Quarterly review checklist",
+    "identifiers": {
+      "primary": {
+        "kind": "procedureId",
+        "value": "PROC-1",
+        "issuer": "ops-source"
+      }
+    }
+  },
+  "data": {
+    "body": "1. Collect metrics\n2. Draft summary\n3. Review with lead",
+    "contentHash": "hash-proc-1-v1"
+  },
+  "_system": {
+    "state": "active",
+    "createdAt": "2026-01-01T00:00:00.000Z",
+    "modifiedAt": "2026-01-01T00:00:00.000Z"
+  }
+}

package/examples/v2/work-items-analysis.json

@@ -0,0 +1,26 @@
+{
+  "format": "memorix-record/2",
+  "recordId": "wi-100",
+  "revision": 1,
+  "objectType": "work-items",
+  "contentType": "analysis",
+  "dataCategory": "entity",
+  "concept": {
+    "title": "Analysis for wi-100",
+    "identifiers": {
+      "primary": {
+        "kind": "recordId",
+        "value": "wi-100"
+      }
+    }
+  },
+  "data": {
+    "analysisType": "delivery-risk",
+    "risk": "low"
+  },
+  "_system": {
+    "state": "active",
+    "createdAt": "2026-01-15T13:00:00.000Z",
+    "modifiedAt": "2026-01-15T13:00:00.000Z"
+  }
+}

package/examples/v2/work-items-context.json

@@ -0,0 +1,32 @@
+{
+  "format": "memorix-record/2",
+  "recordId": "wi-100",
+  "revision": 1,
+  "objectType": "work-items",
+  "contentType": "context",
+  "dataCategory": "entity",
+  "concept": {
+    "title": "Context for wi-100",
+    "identifiers": {
+      "primary": {
+        "kind": "recordId",
+        "value": "wi-100"
+      }
+    }
+  },
+  "data": {
+    "workItemId": "WI-100",
+    "notes": "Current blockers: waiting on finance figures",
+    "temporary": true
+  },
+  "_system": {
+    "state": "active",
+    "createdAt": "2026-01-15T15:00:00.000Z",
+    "modifiedAt": "2026-01-15T15:00:00.000Z",
+    "provenance": {
+      "mode": "context",
+      "sourceId": "ops-source",
+      "ttlPolicy": "work-scoped"
+    }
+  }
+}

package/examples/v2/work-items-decisions.json

@@ -0,0 +1,26 @@
+{
+  "format": "memorix-record/2",
+  "recordId": "wi-100",
+  "revision": 1,
+  "objectType": "work-items",
+  "contentType": "decisions",
+  "dataCategory": "entity",
+  "concept": {
+    "title": "Decision for wi-100",
+    "identifiers": {
+      "primary": {
+        "kind": "recordId",
+        "value": "wi-100"
+      }
+    }
+  },
+  "data": {
+    "decisionType": "priority",
+    "decision": "keep-current-priority"
+  },
+  "_system": {
+    "state": "active",
+    "createdAt": "2026-01-15T13:30:00.000Z",
+    "modifiedAt": "2026-01-15T13:30:00.000Z"
+  }
+}