@x12i/memorix-format 2.2.3 → 2.3.3

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"
+  }
+}

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

@@ -0,0 +1,37 @@
+{
+  "format": "memorix-record/2",
+  "recordId": "wi-100",
+  "revision": 1,
+  "objectType": "work-items",
+  "contentType": "raw",
+  "dataCategory": "entity",
+  "concept": {
+    "title": "Prepare quarterly operations review",
+    "identifiers": {
+      "primary": {
+        "kind": "workItemId",
+        "value": "WI-100",
+        "issuer": "ops-source"
+      }
+    }
+  },
+  "data": {
+    "id": "WI-100",
+    "title": "Prepare quarterly operations review",
+    "status": "in-progress",
+    "priority": "normal",
+    "assigneeId": "E-10",
+    "procedureIds": ["PROC-1"],
+    "dependsOnIds": ["WI-90"],
+    "updatedAt": "2026-01-15T12:00:00.000Z"
+  },
+  "_system": {
+    "state": "active",
+    "createdAt": "2026-01-15T12:00:00.000Z",
+    "modifiedAt": "2026-01-15T12:00:00.000Z",
+    "provenance": {
+      "sourceId": "ops-source",
+      "endpoint": "/work-items"
+    }
+  }
+}

package/examples/v2/work-items-relationships-candidate.json

@@ -0,0 +1,38 @@
+{
+  "format": "memorix-record/2",
+  "recordId": "wi-100",
+  "revision": 2,
+  "objectType": "work-items",
+  "contentType": "relationships",
+  "dataCategory": "entity",
+  "concept": {
+    "title": "Relationships for wi-100",
+    "identifiers": {
+      "primary": {
+        "kind": "recordId",
+        "value": "wi-100"
+      }
+    }
+  },
+  "data": {
+    "associatedPeople": [
+      {
+        "relationshipId": "rel-people-assigned-employee-10-wi-100",
+        "relationshipDefinitionId": "people-assigned-to-work-items",
+        "recordId": "employee-10"
+      }
+    ],
+    "usedProcedures": [
+      {
+        "relationshipId": "rel-wi-use-proc-wi-100-proc-1",
+        "relationshipDefinitionId": "work-items-use-procedures",
+        "recordId": "proc-1"
+      }
+    ]
+  },
+  "_system": {
+    "state": "active",
+    "createdAt": "2026-01-15T12:00:00.000Z",
+    "modifiedAt": "2026-01-15T12:30:00.000Z"
+  }
+}

package/examples/v2/work-items-snapshots-lifecycle.json

@@ -0,0 +1,31 @@
+{
+  "format": "memorix-record/2",
+  "recordId": "wi-100",
+  "revision": 5,
+  "objectType": "work-items",
+  "contentType": "snapshots",
+  "dataCategory": "entity",
+  "concept": {
+    "title": "Prepare quarterly operations review",
+    "identifiers": {
+      "primary": {
+        "kind": "workItemId",
+        "value": "WI-100",
+        "issuer": "ops-source"
+      }
+    }
+  },
+  "data": {
+    "status": "done",
+    "priority": "normal"
+  },
+  "_system": {
+    "state": "active",
+    "createdAt": "2026-01-10T10:00:00.000Z",
+    "modifiedAt": "2026-01-20T09:00:00.000Z",
+    "lifecycle": [
+      { "process": "created", "processedAt": "2026-01-10T10:00:00.000Z" },
+      { "process": "completed", "processedAt": "2026-01-20T09:00:00.000Z" }
+    ]
+  }
+}

package/examples/v2/work-items-snapshots-lightweight-refs.json

@@ -0,0 +1,34 @@
+{
+  "format": "memorix-record/2",
+  "recordId": "wi-100",
+  "revision": 2,
+  "objectType": "work-items",
+  "contentType": "snapshots",
+  "dataCategory": "entity",
+  "concept": {
+    "title": "Prepare quarterly operations review",
+    "identifiers": {
+      "primary": {
+        "kind": "workItemId",
+        "value": "WI-100",
+        "issuer": "ops-source"
+      }
+    }
+  },
+  "data": {
+    "status": "in-progress",
+    "priority": "normal"
+  },
+  "associatedPeople": [
+    {
+      "relationshipDefinitionId": "people-assigned-to-work-items",
+      "recordId": "employee-10",
+      "relationshipId": "rel-people-assigned-employee-10-wi-100"
+    }
+  ],
+  "_system": {
+    "state": "active",
+    "createdAt": "2026-01-10T10:00:00.000Z",
+    "modifiedAt": "2026-01-15T12:30:00.000Z"
+  }
+}

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

@@ -0,0 +1,28 @@
+{
+  "format": "memorix-record/2",
+  "recordId": "wi-100",
+  "revision": 3,
+  "objectType": "work-items",
+  "contentType": "snapshots",
+  "dataCategory": "entity",
+  "concept": {
+    "title": "Prepare quarterly operations review",
+    "identifiers": {
+      "primary": {
+        "kind": "workItemId",
+        "value": "WI-100",
+        "issuer": "ops-source"
+      }
+    }
+  },
+  "data": {
+    "status": "in-progress",
+    "priority": "normal"
+  },
+  "_system": {
+    "state": "active",
+    "createdAt": "2026-01-10T10:00:00.000Z",
+    "modifiedAt": "2026-01-15T12:00:00.000Z",
+    "observedAt": "2026-01-15T12:00:00.000Z"
+  }
+}

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

@@ -0,0 +1,28 @@
+{
+  "format": "memorix-record/2",
+  "recordId": "wi-100",
+  "revision": 4,
+  "objectType": "work-items",
+  "contentType": "workflow",
+  "dataCategory": "entity",
+  "concept": {
+    "title": "Workflow for wi-100",
+    "identifiers": {
+      "primary": {
+        "kind": "recordId",
+        "value": "wi-100"
+      }
+    }
+  },
+  "data": {
+    "status": "in-progress",
+    "assigneeRecordId": "employee-10",
+    "tasks": [],
+    "audit": []
+  },
+  "_system": {
+    "state": "active",
+    "createdAt": "2026-01-10T10:00:00.000Z",
+    "modifiedAt": "2026-01-15T14:00:00.000Z"
+  }
+}