@x12i/memorix-writer 1.0.0 → 1.1.0

package/docs/GRAPH-RUNS.md

@@ -0,0 +1,93 @@
+# Graph-run tracking (`_graphRuns`) — MRX-FRS-001
+
+Record-level visibility for graph execution over Memorix entity and event records.
+
+## Overview
+
+The reserved system field `_graphRuns` is stored **top-level on the Mongo payload document**, outside domain `data`. It is keyed by `graphId` and holds the **latest state only** per `(record, graphId)`.
+
+Domain `writeMemorixRecord` operations **must not** accept `_graphRuns` in user input. Only the graph-run writer APIs below may mutate it.
+
+Shared types live in `@x12i/memorix-descriptors/types`.
+
+## Writer APIs (`@x12i/memorix-writer`)
+
+```typescript
+import {
+  markGraphRunStarted,
+  markGraphRunFailed,
+  writeGraphRunResult,
+  clearGraphRun,
+  ensureGraphRunIndexes,
+} from "@x12i/memorix-writer";
+```
+
+### `markGraphRunStarted(ref, graphId, opts)`
+
+Sets `_graphRuns.<graphId>` to `{ status: "in_progress", startedAt, lastJobRunId, attempts, graphVersion? }` using a per-key dot-path `$set`.
+
+**Idempotency:** If already `in_progress` with the same `lastJobRunId`, no-op (safe on lease-sweep re-claim). A different `lastJobRunId` overwrites the stamp.
+
+### `markGraphRunFailed(ref, graphId, opts)`
+
+Sets terminal `failed` status with `error` and `completedAt`. Call only when `job_runs` has exhausted `maxAttempts`.
+
+### `writeGraphRunResult(ref, graphId, opts)` — combined success path
+
+1. Upserts the graph result document to the persistency target collection (`<entityName>-<contentType>`).
+2. Stamps the source record `_graphRuns.<graphId>` = `done` + result pointer + `completedAt`.
+
+**Atomicity (best-effort compensation):** No Mongo transactions. Result is written first; if stamping fails, the result document is rolled back (restored to prior state or deleted). A hard crash between steps can leave a stray result doc — reconcile via jobs / optional sweep (FRS-001-F).
+
+### `clearGraphRun(ref, graphId)`
+
+`$unset` on `_graphRuns.<graphId>` so the record re-qualifies for `graphRunNotDone` planning queries.
+
+### `ensureGraphRunIndexes(client, ref, graphId)`
+
+Opt-in helper creating recommended compound indexes on the source collection:
+
+- `{ "_graphRuns.<graphId>.status": 1, <idField>: 1 }`
+- `{ "_graphRuns.<graphId>.completedAt": 1 }`
+
+## Retrieval filters (`@x12i/memorix-retrieval`)
+
+```typescript
+await fetchMemorixListForEntity(client, {
+  entityName: "assets",
+  contentType: "scoped", // via list descriptor driver content type
+  graphRunFilter: { graphRunNotDone: { graphId: "graph-qcrbz6t" } },
+  page: { limit: 100, offset: 0 },
+});
+```
+
+Supported facets (via `compileGraphRunFilter` / `graphRunFilter` on list requests):
+
+| Facet | Use case |
+|-------|----------|
+| `graphRunStatus` | Filter by `in_progress` / `done` / `failed` |
+| `graphRunNotDone` | Planning — absent or status ≠ `done` |
+| `graphRunCompletedBefore` | Stale results |
+| `graphRunFailed` | Retry candidates |
+| `graphRunStaleVersion` | Graph version invalidation |
+
+Read exposure:
+
+- **List:** `includeGraphRuns: true` adds `_graphRuns` to row projection (default off).
+- **Item:** `includeGraphRuns` defaults to **true**; response includes top-level `_graphRuns` when present.
+
+## Error codes
+
+| Code | When |
+|------|------|
+| `RECORD_NOT_FOUND` | Source record missing |
+| `DESCRIPTOR_MISSING` | Result collection write failed |
+| `GRAPH_RUN_STAMP_FAILED` | Stamp failed after compensation attempt |
+| `SYSTEM_FIELD_NOT_WRITABLE` | `_graphRuns` passed to `writeMemorixRecord` |
+
+Log correlation shape: `{ jobRunId, graphId, recordRef, operation }`.
+
+## References
+
+- MRX-FRS-001 change request (Exellix consumer: EXLX-CRS-001)
+- [MEMORIX-DATABASE-CONVENTIONS](https://github.com/x12i/memorix-retrieval/blob/main/docs/MEMORIX-DATABASE-CONVENTIONS.md)

package/docs/gap-analysis.md

@@ -0,0 +1,18 @@
+# @x12i/memorix-writer — gap analysis
+
+## Status: v1.0 core path complete
+
+| Area | Status |
+|------|--------|
+| Descriptor-driven writes (add/upsert/patch/replace) | Done |
+| Content upload + pointers | Done |
+| Wired to `@x12i/memorix-descriptors/catalog` | Done |
+| Knowledge target | Done |
+| Write descriptor CRUD | Owned by `@x12i/memorix-descriptors` |
+| CLI | Not planned (library-only) |
+| Live integration tests | Optional via host env |
+
+## Non-goals
+
+- Descriptor admin (use `@x12i/memorix-descriptors`)
+- List/item layout (use `@x12i/memorix-retrieval`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/memorix-writer",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Descriptor-driven write layer for Memorix entity/event records and content objects",
   "type": "module",
   "main": "./dist/index.js",
@@ -27,11 +27,8 @@
   },
   "dependencies": {
     "@x12i/catalox": "^5.1.1",
-    "@x12i/env": "^4.0.1",
-    "@x12i/helpers": "^1.7.0",
-    "@x12i/memorix-descriptors": "^1.6.0",
-    "@x12i/memorix-retrieval": "^1.10.0",
-    "@x12i/xronox": "^3.9.0",
+    "@x12i/memorix-descriptors": "^1.7.0",
+    "@x12i/memorix-retrieval": "^1.12.0",
     "mongodb": "^6.21.0"
   },
   "devDependencies": {