@x12i/memorix-format 3.0.3 → 3.0.4

package/docs/memorix-workflow-format.md

@@ -1,126 +1,126 @@
-# 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`).
-
-This is **not** inventory (snapshots), **not** AI analysis/decision, and **not**
-vendor audit telemetry. It stores human/product work state: assignee, status,
-append-only audit of UI mutations, and close-via tasks.
-
-Catalog `memorix-workflow-field-schemas` defines which scalar/enum fields may
-appear under `data` (beyond reserved `audit` / `tasks`).
-
-## Collection postfix
-
-| Descriptor content-type key | Postfix | Collection | Cardinality |
-|---|---|---|---|
-| `workflow` | `workflow` | `{objectType}-workflow` | `1:1` |
-
-Join key: same `recordId` as the subject entity’s canonical snapshot.
-
-## Canonical document
-
-```ts
-type MemorixWorkflowDocument = {
-  format: "memorix-workflow/1";
-  recordId: string;
-  objectType: string;
-  data: {
-    /** Catalog-driven properties (validated against field schema). */
-    [fieldKey: string]: unknown;
-    /** Format-reserved — API-managed only. */
-    audit: WorkflowAuditEntry[];
-    tasks: WorkflowTask[];
-  };
-  modifiedAt: string;
-  modifiedBy?: string;
-};
-
-type WorkflowAuditEntry = {
-  id: string;
-  at: string;
-  actor: string;
-  action: string;
-  field?: string;
-  previous?: unknown;
-  next?: unknown;
-};
-
-type WorkflowTask = {
-  id: string;
-  dk: string;
-  title: string;
-  via?: string;
-  status: "open" | "done" | "cancelled";
-  createdAt: string;
-  createdBy: string;
-  completedAt?: string;
-};
-```
-
-## Rules
-
-1. Custom fields under `data` **must** be declared in `memorix-workflow-field-schemas`
-   for that `objectType` (when `rejectUnknownFields` is true, default).
-2. `audit` and `tasks` are **never** writable via generic field PATCH — dedicated
-   API endpoints only.
-3. Enum values are stored as English **keys**; UI maps display labels.
-4. Do not put workflow state on snapshots, analysis, or decision documents.
-
-## Field schema catalog
-
-Catalog id: `memorix-workflow-field-schemas`
-
-One item per object type (natural id e.g. `items-workflow-fields`):
-
-```ts
-type WorkflowFieldSchemaItem = {
-  id: string;
-  objectType: string;
-  contentType: "workflow";
-  rejectUnknownFields: boolean;
-  fields: WorkflowFieldDef[];
-};
-
-type WorkflowFieldDef = {
-  key: string;
-  label: string;
-  description?: string;
-  valueType: "string" | "number" | "boolean" | "datetime" | "enum";
-  enumValues?: string[];
-  required?: boolean;
-  writable?: boolean;
-  defaultValue?: unknown;
-  list?: boolean;
-  item?: boolean;
-  section?: string;
-  order?: number;
-};
-```
-
-## API
-
-See `@x12i/memorix-workflow-api` — catalog-driven HTTP for schema list/get/upsert,
-overview aggregation, document list/get/ensure, field PATCH, audit list, and
-tasks CRUD. UI: `@x12i/memorix-workflow-ui`.
-
-List/overview notes:
-
-- `GET /api/workflow/schemas` — discover object types with field schemas
-- `GET /api/workflow/:objectType` — list existing workflow overlays (slim `list:true` projection)
-- `GET /api/workflow/overview` — totals and recent audit activity
-- `GET .../audit` and `GET .../tasks` are read-only (404 when the document is missing; they do not create)
+# 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`).
+
+This is **not** inventory (snapshots), **not** AI analysis/decision, and **not**
+vendor audit telemetry. It stores human/product work state: assignee, status,
+append-only audit of UI mutations, and close-via tasks.
+
+Catalog `memorix-workflow-field-schemas` defines which scalar/enum fields may
+appear under `data` (beyond reserved `audit` / `tasks`).
+
+## Collection postfix
+
+| Descriptor content-type key | Postfix | Collection | Cardinality |
+|---|---|---|---|
+| `workflow` | `workflow` | `{objectType}-workflow` | `1:1` |
+
+Join key: same `recordId` as the subject entity’s canonical snapshot.
+
+## Canonical document
+
+```ts
+type MemorixWorkflowDocument = {
+  format: "memorix-workflow/1";
+  recordId: string;
+  objectType: string;
+  data: {
+    /** Catalog-driven properties (validated against field schema). */
+    [fieldKey: string]: unknown;
+    /** Format-reserved — API-managed only. */
+    audit: WorkflowAuditEntry[];
+    tasks: WorkflowTask[];
+  };
+  modifiedAt: string;
+  modifiedBy?: string;
+};
+
+type WorkflowAuditEntry = {
+  id: string;
+  at: string;
+  actor: string;
+  action: string;
+  field?: string;
+  previous?: unknown;
+  next?: unknown;
+};
+
+type WorkflowTask = {
+  id: string;
+  dk: string;
+  title: string;
+  via?: string;
+  status: "open" | "done" | "cancelled";
+  createdAt: string;
+  createdBy: string;
+  completedAt?: string;
+};
+```
+
+## Rules
+
+1. Custom fields under `data` **must** be declared in `memorix-workflow-field-schemas`
+   for that `objectType` (when `rejectUnknownFields` is true, default).
+2. `audit` and `tasks` are **never** writable via generic field PATCH — dedicated
+   API endpoints only.
+3. Enum values are stored as English **keys**; UI maps display labels.
+4. Do not put workflow state on snapshots, analysis, or decision documents.
+
+## Field schema catalog
+
+Catalog id: `memorix-workflow-field-schemas`
+
+One item per object type (natural id e.g. `items-workflow-fields`):
+
+```ts
+type WorkflowFieldSchemaItem = {
+  id: string;
+  objectType: string;
+  contentType: "workflow";
+  rejectUnknownFields: boolean;
+  fields: WorkflowFieldDef[];
+};
+
+type WorkflowFieldDef = {
+  key: string;
+  label: string;
+  description?: string;
+  valueType: "string" | "number" | "boolean" | "datetime" | "enum";
+  enumValues?: string[];
+  required?: boolean;
+  writable?: boolean;
+  defaultValue?: unknown;
+  list?: boolean;
+  item?: boolean;
+  section?: string;
+  order?: number;
+};
+```
+
+## API
+
+See `@x12i/memorix-workflow-api` — catalog-driven HTTP for schema list/get/upsert,
+overview aggregation, document list/get/ensure, field PATCH, audit list, and
+tasks CRUD. UI: `@x12i/memorix-workflow-ui`.
+
+List/overview notes:
+
+- `GET /api/workflow/schemas` — discover object types with field schemas
+- `GET /api/workflow/:objectType` — list existing workflow overlays (slim `list:true` projection)
+- `GET /api/workflow/overview` — totals and recent audit activity
+- `GET .../audit` and `GET .../tasks` are read-only (404 when the document is missing; they do not create)

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

@@ -1,49 +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 `@x12i/memorix-relationship-store` (archived decision: `.tmp/housekeeping-2026-07-23/docs/re-factoring-and-opx-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.
+# 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 `@x12i/memorix-relationship-store` (archived decision: `.tmp/housekeeping-2026-07-23/docs/re-factoring-and-opx-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/invalid-record.json

@@ -1,11 +1,11 @@
-{
-  "recordId": "",
-  "concept": {
-    "name": "legacy-name-only"
-  },
-  "data": "not-an-object",
-  "identity": {
-    "version": "memorix-record.2.0"
-  },
-  "analytics": []
-}
+{
+  "recordId": "",
+  "concept": {
+    "name": "legacy-name-only"
+  },
+  "data": "not-an-object",
+  "identity": {
+    "version": "memorix-record.2.0"
+  },
+  "analytics": []
+}

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

@@ -1,31 +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": "opx-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"
-  }
-}
+{
+  "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": "opx-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/people-discovery.json

@@ -1,26 +1,26 @@
-{
-  "format": "memorix-record/2",
-  "recordId": "person-e-10",
-  "revision": 1,
-  "objectType": "people",
-  "contentType": "discovery",
-  "dataCategory": "entity",
-  "concept": {
-    "title": "Discovery for person-e-10",
-    "identifiers": {
-      "primary": {
-        "kind": "recordId",
-        "value": "person-e-10"
-      }
-    }
-  },
-  "data": {
-    "discoveryType": "role-cluster",
-    "cluster": "operations"
-  },
-  "_system": {
-    "state": "active",
-    "createdAt": "2026-01-15T16:00:00.000Z",
-    "modifiedAt": "2026-01-15T16:00:00.000Z"
-  }
-}
+{
+  "format": "memorix-record/2",
+  "recordId": "person-e-10",
+  "revision": 1,
+  "objectType": "people",
+  "contentType": "discovery",
+  "dataCategory": "entity",
+  "concept": {
+    "title": "Discovery for person-e-10",
+    "identifiers": {
+      "primary": {
+        "kind": "recordId",
+        "value": "person-e-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/people-snapshots-employee.json

@@ -1,27 +1,27 @@
-{
-  "format": "memorix-record/2",
-  "recordId": "person-e-10",
-  "revision": 1,
-  "objectType": "people",
-  "contentType": "snapshots",
-  "dataCategory": "entity",
-  "concept": {
-    "title": "Alex Rivera",
-    "identifiers": {
-      "primary": {
-        "kind": "employeeId",
-        "value": "E-10",
-        "issuer": "opx-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"
-  }
-}
+{
+  "format": "memorix-record/2",
+  "recordId": "person-e-10",
+  "revision": 1,
+  "objectType": "people",
+  "contentType": "snapshots",
+  "dataCategory": "entity",
+  "concept": {
+    "title": "Alex Rivera",
+    "identifiers": {
+      "primary": {
+        "kind": "employeeId",
+        "value": "E-10",
+        "issuer": "opx-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/playbooks-knowledge.json

@@ -1,27 +1,27 @@
-{
-  "format": "memorix-record/2",
-  "recordId": "pb-1",
-  "revision": 1,
-  "objectType": "playbooks",
-  "contentType": "snapshots",
-  "dataCategory": "knowledge",
-  "concept": {
-    "title": "Quarterly review checklist",
-    "identifiers": {
-      "primary": {
-        "kind": "playbookId",
-        "value": "PB-1",
-        "issuer": "opx-source"
-      }
-    }
-  },
-  "data": {
-    "body": "1. Collect metrics\n2. Draft summary\n3. Review with lead",
-    "contentHash": "hash-pb-1-v1"
-  },
-  "_system": {
-    "state": "active",
-    "createdAt": "2026-01-01T00:00:00.000Z",
-    "modifiedAt": "2026-01-01T00:00:00.000Z"
-  }
-}
+{
+  "format": "memorix-record/2",
+  "recordId": "pb-1",
+  "revision": 1,
+  "objectType": "playbooks",
+  "contentType": "snapshots",
+  "dataCategory": "knowledge",
+  "concept": {
+    "title": "Quarterly review checklist",
+    "identifiers": {
+      "primary": {
+        "kind": "playbookId",
+        "value": "PB-1",
+        "issuer": "opx-source"
+      }
+    }
+  },
+  "data": {
+    "body": "1. Collect metrics\n2. Draft summary\n3. Review with lead",
+    "contentHash": "hash-pb-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

@@ -1,26 +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"
-  }
-}
+{
+  "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"
+  }
+}