@x12i/memorix-format 2.2.3 → 2.3.2

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@x12i/memorix-format",
-  "version": "2.2.3",
-  "description": "Memorix product format on @x12i/memorix-base-format: open buckets, associations, SCOPE, migrate CLI.",
+  "version": "2.3.2",
+  "description": "Memorix format: present envelope + memorix-record/2 (Gate G2 SoT), validators, migrate CLIs.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -24,6 +24,10 @@
     "./types": {
       "types": "./dist/types.d.ts",
       "import": "./dist/types.js"
+    },
+    "./v2": {
+      "types": "./dist/v2/index.d.ts",
+      "import": "./dist/v2/index.js"
     }
   },
   "files": [
@@ -67,6 +71,7 @@
   "keywords": [
     "memorix",
     "format",
+    "memorix-record/2",
     "validator",
     "profile",
     "exellix"