@x12i/memorix-format 2.2.3 → 2.3.2

package/dist/v2/validate.js

@@ -0,0 +1,225 @@
+import { MEMORIX_RECORD_FORMAT_V2, } from "./types.js";
+import { DATA_CATEGORIES, RECORD_STATES, V2_FIXED_ROOTS, V2_SNAPSHOT_BUCKETS, resolveContentProfile, } from "./profiles.js";
+function issue(path, code, message, severity = "error") {
+    return { path, code, message, severity };
+}
+function isPlainObject(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+function isNonEmptyObject(v) {
+    return isPlainObject(v) && Object.keys(v).length > 0;
+}
+function readPath(obj, path) {
+    const parts = path.split(".");
+    let cur = obj;
+    for (const p of parts) {
+        if (!isPlainObject(cur))
+            return undefined;
+        cur = cur[p];
+    }
+    return cur;
+}
+/**
+ * Validate a memorix-record/2 document.
+ * Empty optional snapshot buckets must be omitted (not `{}`).
+ */
+export function validateMemorixRecordV2(input, options = {}) {
+    const issues = [];
+    if (!isPlainObject(input)) {
+        return {
+            ok: false,
+            issues: [issue("", "V2-TYPE", "Record must be a plain object")],
+        };
+    }
+    const rejectUnknown = options.rejectUnknownRoots !== false;
+    const profile = resolveContentProfile(options.contentType ?? (typeof input.contentType === "string" ? input.contentType : undefined), options.profile);
+    const allowed = new Set([
+        ...V2_FIXED_ROOTS,
+        ...(profile.allowSnapshotBuckets ? V2_SNAPSHOT_BUCKETS : []),
+        ...(profile.allowedExtraRoots ?? []),
+    ]);
+    /**
+     * Option A (Gate G2): root `associated*` may hold lightweight relationship
+     * references only. Copied target payloads are rejected.
+     * Gate G4 selected authoritative storage = central per-category collections
+     * (Candidate C). Option A roots remain format-valid but are not authoritative storage.
+     */
+    const LIGHTWEIGHT_REF_KEYS = new Set([
+        "recordId",
+        "relationshipId",
+        "relationshipDefinitionId",
+    ]);
+    for (const key of Object.keys(input)) {
+        if (key.startsWith("associated")) {
+            const value = input[key];
+            if (value === undefined)
+                continue;
+            if (!Array.isArray(value)) {
+                issues.push(issue(key, "V2-ASSOC-TYPE", `${key} must be an array of lightweight relationship refs`));
+                continue;
+            }
+            if (value.length === 0) {
+                issues.push(issue(key, "V2-ASSOC-EMPTY", `${key} must be omitted when empty`));
+                continue;
+            }
+            for (let i = 0; i < value.length; i++) {
+                const item = value[i];
+                const path = `${key}[${i}]`;
+                if (!isPlainObject(item)) {
+                    issues.push(issue(path, "V2-ASSOC-ITEM", `${path} must be a plain object`));
+                    continue;
+                }
+                if (typeof item.recordId !== "string" || !item.recordId.trim()) {
+                    issues.push(issue(`${path}.recordId`, "V2-ASSOC-RECORD-ID", `${path}.recordId is required`));
+                }
+                if (typeof item.relationshipDefinitionId !== "string" ||
+                    !item.relationshipDefinitionId.trim()) {
+                    issues.push(issue(`${path}.relationshipDefinitionId`, "V2-ASSOC-DEF-ID", `${path}.relationshipDefinitionId is required — without it this is a record reference, not a relationship`));
+                }
+                for (const k of Object.keys(item)) {
+                    if (!LIGHTWEIGHT_REF_KEYS.has(k)) {
+                        issues.push(issue(`${path}.${k}`, "V2-ASSOC-COPIED", `${path} may only contain relationshipDefinitionId, recordId, and optional relationshipId — copied related payload rejected (Gate G2). Option A lightweight roots remain format-valid; authoritative storage is G4 Candidate C (central per-category collections).`));
+                    }
+                }
+                if (item.relationshipId !== undefined &&
+                    (typeof item.relationshipId !== "string" || !String(item.relationshipId).trim())) {
+                    issues.push(issue(`${path}.relationshipId`, "V2-ASSOC-REF", `${path}.relationshipId must be a non-empty string when present (optional only because it is deterministically derivable)`));
+                }
+            }
+            continue;
+        }
+        if (rejectUnknown && !allowed.has(key) && !key.startsWith("_")) {
+            issues.push(issue(key, "V2-ROOT", `Unknown root '${key}' is not allowed for contentType '${profile.contentType}'`));
+        }
+        if (key.startsWith("_") && key !== "_system" && key !== "_id") {
+            issues.push(issue(key, "V2-SYSTEM-ROOT", `Only _system and _id machine roots are allowed; found '${key}'`));
+        }
+    }
+    if (input.format !== MEMORIX_RECORD_FORMAT_V2) {
+        issues.push(issue("format", "V2-FORMAT", `format must be "${MEMORIX_RECORD_FORMAT_V2}"`));
+    }
+    if (typeof input.recordId !== "string" || !input.recordId.trim()) {
+        issues.push(issue("recordId", "V2-RECORD-ID", "recordId must be a non-empty string"));
+    }
+    if (typeof input.revision !== "number" || !Number.isInteger(input.revision) || input.revision < 1) {
+        issues.push(issue("revision", "V2-REVISION", "revision must be an integer >= 1"));
+    }
+    if (typeof input.objectType !== "string" || !input.objectType.trim()) {
+        issues.push(issue("objectType", "V2-OBJECT-TYPE", "objectType must be a non-empty string"));
+    }
+    else if (options.objectType && input.objectType !== options.objectType) {
+        issues.push(issue("objectType", "V2-OBJECT-TYPE-MISMATCH", `objectType '${input.objectType}' does not match expected '${options.objectType}'`));
+    }
+    if (typeof input.contentType !== "string" || !input.contentType.trim()) {
+        issues.push(issue("contentType", "V2-CONTENT-TYPE", "contentType must be a non-empty string"));
+    }
+    else if (options.contentType && input.contentType !== options.contentType) {
+        issues.push(issue("contentType", "V2-CONTENT-TYPE-MISMATCH", `contentType '${input.contentType}' does not match expected '${options.contentType}'`));
+    }
+    if (typeof input.dataCategory !== "string" ||
+        !DATA_CATEGORIES.includes(input.dataCategory)) {
+        issues.push(issue("dataCategory", "V2-DATA-CATEGORY", `dataCategory must be one of ${DATA_CATEGORIES.join(", ")}`));
+    }
+    if (!isPlainObject(input.concept)) {
+        issues.push(issue("concept", "V2-CONCEPT", "concept must be a plain object"));
+    }
+    else {
+        if (typeof input.concept.title !== "string" || !input.concept.title.trim()) {
+            issues.push(issue("concept.title", "V2-CONCEPT-TITLE", "concept.title must be a non-empty string"));
+        }
+        const identifiers = input.concept.identifiers;
+        if (!isPlainObject(identifiers)) {
+            issues.push(issue("concept.identifiers", "V2-IDENTIFIERS", "concept.identifiers is required"));
+        }
+        else {
+            const primary = identifiers.primary;
+            if (!isPlainObject(primary)) {
+                issues.push(issue("concept.identifiers.primary", "V2-PRIMARY", "primary identifier is required"));
+            }
+            else {
+                if (typeof primary.kind !== "string" || !primary.kind.trim()) {
+                    issues.push(issue("concept.identifiers.primary.kind", "V2-PRIMARY-KIND", "kind is required"));
+                }
+                if (typeof primary.value !== "string" || !primary.value.trim()) {
+                    issues.push(issue("concept.identifiers.primary.value", "V2-PRIMARY-VALUE", "value is required"));
+                }
+            }
+            if (identifiers.alternates !== undefined) {
+                if (!Array.isArray(identifiers.alternates)) {
+                    issues.push(issue("concept.identifiers.alternates", "V2-ALTERNATES", "alternates must be an array"));
+                }
+                else if (identifiers.alternates.length === 0) {
+                    issues.push(issue("concept.identifiers.alternates", "V2-ALTERNATES-EMPTY", "alternates must be omitted when empty"));
+                }
+            }
+        }
+    }
+    if (!isPlainObject(input.data)) {
+        issues.push(issue("data", "V2-DATA", "data must be a plain object"));
+    }
+    for (const bucket of V2_SNAPSHOT_BUCKETS) {
+        if (input[bucket] === undefined)
+            continue;
+        if (!profile.allowSnapshotBuckets) {
+            issues.push(issue(bucket, "V2-SCOPE-BUCKET", `${bucket} is only allowed on snapshot-like content types (got '${profile.contentType}')`));
+        }
+        else if (!isNonEmptyObject(input[bucket])) {
+            issues.push(issue(bucket, "V2-EMPTY-BUCKET", `${bucket} must be omitted when empty (do not emit {})`));
+        }
+    }
+    if (!isPlainObject(input._system)) {
+        issues.push(issue("_system", "V2-SYSTEM", "_system is required"));
+    }
+    else {
+        const sys = input._system;
+        if (typeof sys.state !== "string" ||
+            !RECORD_STATES.includes(sys.state)) {
+            issues.push(issue("_system.state", "V2-STATE", `state must be one of ${RECORD_STATES.join(", ")}`));
+        }
+        for (const ts of ["createdAt", "modifiedAt"]) {
+            if (typeof sys[ts] !== "string" || !sys[ts].trim()) {
+                issues.push(issue(`_system.${ts}`, "V2-TIMESTAMP", `${ts} must be a non-empty string`));
+            }
+        }
+        if (sys.lifecycle !== undefined) {
+            if (!Array.isArray(sys.lifecycle)) {
+                issues.push(issue("_system.lifecycle", "V2-LIFECYCLE", "lifecycle must be an array"));
+            }
+            else if (sys.lifecycle.length === 0) {
+                issues.push(issue("_system.lifecycle", "V2-LIFECYCLE-EMPTY", "lifecycle must be omitted when empty"));
+            }
+        }
+        if (sys.provenance !== undefined && !isNonEmptyObject(sys.provenance)) {
+            issues.push(issue("_system.provenance", "V2-PROVENANCE-EMPTY", "provenance must be omitted when empty"));
+        }
+    }
+    if (options.enforceDiscriminator !== false && profile.discriminator && isPlainObject(input)) {
+        const disc = profile.discriminator;
+        const value = readPath(input, disc.path);
+        if (value === undefined || value === null || value === "") {
+            if (disc.defaultValue !== undefined) {
+                // Metadata-defined default exists: structural validation passes; writers may apply default.
+                issues.push(issue(disc.path, "V2-DISCRIMINATOR-DEFAULT", `${disc.path} missing; content-type profile default '${disc.defaultValue}' applies at write time`, "warning"));
+            }
+            else if (disc.required) {
+                issues.push(issue(disc.path, "V2-DISCRIMINATOR", `Required discriminator ${disc.path} is missing and no default is configured`));
+            }
+        }
+        else if (typeof value !== "string") {
+            issues.push(issue(disc.path, "V2-DISCRIMINATOR-TYPE", `${disc.path} must be a string`));
+        }
+        else if (disc.allowedValues && !disc.allowedValues.includes(value)) {
+            issues.push(issue(disc.path, "V2-DISCRIMINATOR-VALUE", `${disc.path}='${value}' is not in allowedValues`));
+        }
+    }
+    const ok = !issues.some((i) => i.severity === "error");
+    return {
+        ok,
+        issues,
+        record: ok ? input : undefined,
+    };
+}
+export function validateMemorixRecordsV2(inputs, options = {}) {
+    return inputs.map((input) => validateMemorixRecordV2(input, options));
+}
+//# sourceMappingURL=validate.js.map

package/dist/v2/validate.js.map

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

package/docs/association-format.md

@@ -38,6 +38,9 @@ Object-type segments come from Catalox descriptors — not from this format pack
 ## Payload rules
 
 - Associated properties are **arrays of plain objects** (linked payloads), never full envelopes.
+- On **memorix-record/2**, root `associated*` may hold **lightweight refs only** (Option A — format-valid): `relationshipDefinitionId` + `recordId`, optional `relationshipId`. Copied related business payload is rejected.
+- **Authoritative relationship storage (Gate G4)** is centralized per-category collections (Candidate C), not Option A roots or sibling `relationships` content. See `docs/re-factoring-and-ops-agent/RELATIONSHIP-STORAGE-DECISION.md`.
+
 - **Omit** the property when empty — never write `[]`.
 - Prefer traceability in optional item-level `_system.association` (v2) rather than wrapping envelopes.
 

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`).