@x12i/memorix-format 3.0.3 → 3.0.4

package/docs/memorix-format-requirements.md

@@ -1,54 +1,54 @@
-# Memorix Format — Requirements (product layer)
-
-**Package:** `@x12i/memorix-format`  
-**Depends on:** `@x12i/memorix-base-format` (fixed skeleton — do not re-state ENV/ID/DATA/SYS here).
-
-This document covers **Memorix product** open-bucket conventions. Base envelope MUST be satisfied first (`TOOL-3`: layer checks on base).
-
----
-
-## Known open buckets (when present)
-
-**BUCKET-5.**
-
-| Bucket | MUST contain | MUST NOT contain |
-|---|---|---|
-| `analytics` | Numeric rollups | The underlying list of records |
-| `enrichment` | External / prior-system values as received | Interpreted judgments |
-| `insights` | Judgments, scores, recommendations | Anything a reader would mistake for a stored native fact |
-
-These names are **Memorix declarations**, not base-reserved keys. Base classifies them as open buckets.
-
----
-
-## Associated properties
-
-**ASSOC-1.** Keys matching Memorix association patterns (`associated…`, legacy short names, `associatedTop…`, `associated…Enrichment`, custom `associated` prefix).
-
-**ASSOC-2.** When present, MUST be an array.
-
-**ASSOC-3.** MUST be omitted when empty — never `[]`.
-
-**ASSOC-5.** Items MUST be plain objects (linked payloads), not full envelopes.
-
-**ASSOC-6.** Resolution MUST be snapshot-first (see association-format.md). Enforced by associator tooling, documented here.
-
----
-
-## Snapshot vs minimal (SCOPE)
-
-**SCOPE-1.** Full open-bucket set SHOULD appear primarily on snapshots.
-
-**SCOPE-2.** Non-snapshot content types MUST include `recordId` + `data`; SHOULD omit `analytics` / `insights` / most `associated*` unless opted in via ContentTypeMeta.
-
-**SCOPE-3.** Readers MUST treat missing optional buckets as N/A, not error.
-
----
-
-## Validator
-
-**TOOL-3.** `validateMemorixRecord` = `validateMemorixBaseRecord` + profile/ASSOC/SCOPE.
-
-**TOOL-4.** `migrateMemorixRecord` / CLI `migrate` transforms legacy/transitional envelopes to the present format and SHOULD validate the result.
-
-Built-in profiles: `snapshots`, `minimal` (`--profile=`).
+# Memorix Format — Requirements (product layer)
+
+**Package:** `@x12i/memorix-format`  
+**Depends on:** `@x12i/memorix-base-format` (fixed skeleton — do not re-state ENV/ID/DATA/SYS here).
+
+This document covers **Memorix product** open-bucket conventions. Base envelope MUST be satisfied first (`TOOL-3`: layer checks on base).
+
+---
+
+## Known open buckets (when present)
+
+**BUCKET-5.**
+
+| Bucket | MUST contain | MUST NOT contain |
+|---|---|---|
+| `analytics` | Numeric rollups | The underlying list of records |
+| `enrichment` | External / prior-system values as received | Interpreted judgments |
+| `insights` | Judgments, scores, recommendations | Anything a reader would mistake for a stored native fact |
+
+These names are **Memorix declarations**, not base-reserved keys. Base classifies them as open buckets.
+
+---
+
+## Associated properties
+
+**ASSOC-1.** Keys matching Memorix association patterns (`associated…`, legacy short names, `associatedTop…`, `associated…Enrichment`, custom `associated` prefix).
+
+**ASSOC-2.** When present, MUST be an array.
+
+**ASSOC-3.** MUST be omitted when empty — never `[]`.
+
+**ASSOC-5.** Items MUST be plain objects (linked payloads), not full envelopes.
+
+**ASSOC-6.** Resolution MUST be snapshot-first (see association-format.md). Enforced by associator tooling, documented here.
+
+---
+
+## Snapshot vs minimal (SCOPE)
+
+**SCOPE-1.** Full open-bucket set SHOULD appear primarily on snapshots.
+
+**SCOPE-2.** Non-snapshot content types MUST include `recordId` + `data`; SHOULD omit `analytics` / `insights` / most `associated*` unless opted in via ContentTypeMeta.
+
+**SCOPE-3.** Readers MUST treat missing optional buckets as N/A, not error.
+
+---
+
+## Validator
+
+**TOOL-3.** `validateMemorixRecord` = `validateMemorixBaseRecord` + profile/ASSOC/SCOPE.
+
+**TOOL-4.** `migrateMemorixRecord` / CLI `migrate` transforms legacy/transitional envelopes to the present format and SHOULD validate the result.
+
+Built-in profiles: `snapshots`, `minimal` (`--profile=`).

package/docs/memorix-format.md

@@ -1,68 +1,68 @@
-# Memorix Record Format
-
-> **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.
-
-**Prefer `memorix-record/2` for all new platform paths.** Present envelope remains for reading/migrating existing data.
-
----
-
-## Present envelope (migration source)
-
-```ts
-type MemorixRecordPresent = {
-  _id?: string;
-  recordId: string;
-  concept: {
-    _extIdentifier: { kind: string; key: string; [kindValue: string]: string };
-    title: string;
-  };
-  data: JsonObject;
-  analytics?: JsonObject;
-  enrichment?: JsonObject;
-  insights?: JsonObject;
-  // associated…?: JsonObject[];  // copied payloads — removed in V2
-  _system?: {
-    state?: "active" | "archived" | "superseded";
-    lifecycle?: Array<{ process: string; processedAt: string }>;
-  };
-};
-```
-
-Migrate legacy → present: `npx memorix-format migrate`.  
-Migrate present → V2: `npx memorix-format migrate-to-v2 --object-type=… --content-type=… --data-category=…`.
-
-Associated properties use the reserved `associated` prefix on **present** records only. See [association-format.md](./association-format.md). V2 rejects copied association roots.
-
-Human/LLM readers SHOULD omit root `_…` and `concept._extIdentifier` by default; keep `recordId` for joins.
-
----
-
-## Data And Associated Buckets (present)
-
-Every piece of business data lives in **exactly one** of these buckets (plus the envelope fields above):
-
-| Bucket | Contents |
-|---|---|
-| **`data`** | Native facts about the subject itself |
-| **`analytics`** | Numeric rollups computed from other records |
-| **`enrichment`** | External / prior-system values as received |
-| **`insights`** | AI / judgment outputs |
-| **`associated*`** | Copied related payloads (present only; removed in V2) |
-
-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 `@x12i/memorix-relationship-store` (archived: `.tmp/housekeeping-2026-07-23/docs/re-factoring-and-opx-agent/RELATIONSHIP-STORAGE-DECISION.md`).
-
----
-
-## Further reading
-
-- [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/`
+# Memorix Record Format
+
+> **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.
+
+**Prefer `memorix-record/2` for all new platform paths.** Present envelope remains for reading/migrating existing data.
+
+---
+
+## Present envelope (migration source)
+
+```ts
+type MemorixRecordPresent = {
+  _id?: string;
+  recordId: string;
+  concept: {
+    _extIdentifier: { kind: string; key: string; [kindValue: string]: string };
+    title: string;
+  };
+  data: JsonObject;
+  analytics?: JsonObject;
+  enrichment?: JsonObject;
+  insights?: JsonObject;
+  // associated…?: JsonObject[];  // copied payloads — removed in V2
+  _system?: {
+    state?: "active" | "archived" | "superseded";
+    lifecycle?: Array<{ process: string; processedAt: string }>;
+  };
+};
+```
+
+Migrate legacy → present: `npx memorix-format migrate`.  
+Migrate present → V2: `npx memorix-format migrate-to-v2 --object-type=… --content-type=… --data-category=…`.
+
+Associated properties use the reserved `associated` prefix on **present** records only. See [association-format.md](./association-format.md). V2 rejects copied association roots.
+
+Human/LLM readers SHOULD omit root `_…` and `concept._extIdentifier` by default; keep `recordId` for joins.
+
+---
+
+## Data And Associated Buckets (present)
+
+Every piece of business data lives in **exactly one** of these buckets (plus the envelope fields above):
+
+| Bucket | Contents |
+|---|---|
+| **`data`** | Native facts about the subject itself |
+| **`analytics`** | Numeric rollups computed from other records |
+| **`enrichment`** | External / prior-system values as received |
+| **`insights`** | AI / judgment outputs |
+| **`associated*`** | Copied related payloads (present only; removed in V2) |
+
+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 `@x12i/memorix-relationship-store` (archived: `.tmp/housekeeping-2026-07-23/docs/re-factoring-and-opx-agent/RELATIONSHIP-STORAGE-DECISION.md`).
+
+---
+
+## Further reading
+
+- [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

@@ -1,101 +1,102 @@
-# 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 `@x12i/memorix-relationship-store` / `@x12i/memorix-relationships` (decision note archived under `.tmp/housekeeping-2026-07-23/docs/re-factoring-and-opx-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 `opx` 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=opx-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).
+# 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 `@x12i/memorix-relationship-store` / `@x12i/memorix-relationships` (decision note archived under `.tmp/housekeeping-2026-07-23/docs/re-factoring-and-opx-agent/RELATIONSHIP-STORAGE-DECISION.md`).
+7. **Writers persist `memorix-record/2` exclusively.** The historical `MEMORIX_RECORD_FORMAT=v2` switch is obsolete and must not be documented as optional. Present-format docs remain for migration tooling only.
+
+## 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=opx-source
+```
+
+Output includes `v2`, `extractedRelationships`, and `warnings`.
+
+## Writer cutover flag
+
+Obsolete. Production writers always validate and persist `memorix-record/2`. Do not set `MEMORIX_RECORD_FORMAT`.
+
+## Subject identity
+
+See [the subject-model contract](../../docs/subject-model-contract.md). `recordId` is never Mongo `_id`. Source identifiers are adopted as `{issuer}/{kind}/{value}`.
+
+## 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).