@x12i/memorix-docs 1.0.2 → 1.1.1

package/files/scenarios/stale-revision-conflict.md

@@ -0,0 +1,38 @@
+---
+id: "stale-revision-conflict"
+type: "scenario"
+title: "A write returns a stale-revision conflict"
+summary: "PATCH/PUT rejected because expected revision was stale."
+audiences: ["developers"]
+invariants: ["Conflict means the prior write did not apply"]
+---
+# A write returns a stale-revision conflict
+
+## Situation
+
+API returned a revision conflict; record unchanged.
+
+## Decision
+
+Reapply from current revision or escalate?
+
+## Signals
+
+- 409/conflict
+- expectedRevision mismatch
+
+## Paths
+
+### Reload and retry
+
+**When:** Intended change still valid against current meaning
+
+Safe recovery path.
+
+Guides: `reload-retry-conflict`
+
+### Escalate
+
+**When:** Current meaning changed in a conflicting way
+
+Guides: _none_

package/files/scenarios/traversal-direction.md

@@ -0,0 +1,30 @@
+---
+id: "traversal-direction"
+type: "scenario"
+title: "Relationship traversal direction and expansion"
+summary: "Choose forward/inverse and expanded/unexpanded handling."
+audiences: ["developers"]
+---
+# Relationship traversal direction and expansion
+
+## Situation
+
+Caller must traverse a relationship and pick direction/expansion.
+
+## Decision
+
+Which direction and expansion?
+
+## Paths
+
+### Forward
+
+**When:** Following the definition's forward semantics
+
+Guides: `define-traverse-relationship`
+
+### Inverse
+
+**When:** Need inbound links
+
+Guides: `define-traverse-relationship`

package/files/scenarios/unresolved-relationship.md

@@ -0,0 +1,31 @@
+---
+id: "unresolved-relationship"
+type: "scenario"
+title: "A relationship target is unresolved"
+summary: "Traversal returns an unresolved target marker."
+audiences: ["developers", "builders"]
+invariants: ["Do not hide unresolved targets"]
+---
+# A relationship target is unresolved
+
+## Situation
+
+Related record cannot be resolved under the active definition.
+
+## Decision
+
+Repair, wait, or preserve/escalate?
+
+## Paths
+
+### Repair target
+
+**When:** Target should exist and can be created/linked
+
+Guides: `diagnose-unresolved`, `define-traverse-relationship`
+
+### Preserve unresolved
+
+**When:** Unresolved is intentional
+
+Guides: `diagnose-unresolved`

package/files/tutorials/analysis-decision-lab.md

@@ -0,0 +1,18 @@
+---
+id: "analysis-decision-lab"
+type: "tutorial"
+title: "Move from records to analysis and a decision"
+summary: "Create analysis then a distinct decision on sample evidence."
+audiences: ["developers", "builders"]
+---
+# Move from records to analysis and a decision
+
+Create analysis then a distinct decision on sample evidence.
+
+## 1. Write analysis
+
+
+
+## 2. Write decision
+
+

package/files/tutorials/compare-views.md

@@ -0,0 +1,22 @@
+---
+id: "compare-views"
+type: "tutorial"
+title: "Compare raw, composed, and abstract views"
+summary: "See fidelity differences on the same subjects."
+audiences: ["developers", "builders"]
+---
+# Compare raw, composed, and abstract views
+
+See fidelity differences on the same subjects.
+
+## 1. Open raw
+
+
+
+## 2. Open composition
+
+
+
+## 3. Open People
+
+

package/files/tutorials/conflict-lab.md

@@ -0,0 +1,18 @@
+---
+id: "conflict-lab"
+type: "tutorial"
+title: "Recover from a stale revision conflict"
+summary: "Trigger and recover from a conflict using sample data."
+audiences: ["developers"]
+---
+# Recover from a stale revision conflict
+
+Trigger and recover from a conflict using sample data.
+
+## 1. Submit stale revision
+
+
+
+## 2. Reload and retry
+
+

package/files/tutorials/first-revision-safe-record.md

@@ -0,0 +1,18 @@
+---
+id: "first-revision-safe-record"
+type: "tutorial"
+title: "Read and write the first revision-safe record"
+summary: "Practice expected-revision writes on sample data."
+audiences: ["developers"]
+---
+# Read and write the first revision-safe record
+
+Practice expected-revision writes on sample data.
+
+## 1. Read record
+
+
+
+## 2. Write with expected revision
+
+

package/files/tutorials/install-pack-lab.md

@@ -0,0 +1,22 @@
+---
+id: "install-pack-lab"
+type: "tutorial"
+title: "Validate and explicitly install a metadata pack"
+summary: "Practice validation versus confirmation."
+audiences: ["builders"]
+---
+# Validate and explicitly install a metadata pack
+
+Practice validation versus confirmation.
+
+## 1. Validate
+
+
+
+## 2. Cancel once
+
+
+
+## 3. Confirm install
+
+

package/files/tutorials/relationships-lab.md

@@ -0,0 +1,18 @@
+---
+id: "relationships-lab"
+type: "tutorial"
+title: "Define, store, and traverse relationships"
+summary: "Hands-on relationship definition and traversal."
+audiences: ["developers"]
+---
+# Define, store, and traverse relationships
+
+Hands-on relationship definition and traversal.
+
+## 1. Review definition
+
+Use sample relationship definition.
+
+## 2. Traverse forward and inverse
+
+

package/files/tutorials/start-with-sample-data.md

@@ -0,0 +1,18 @@
+---
+id: "start-with-sample-data"
+type: "tutorial"
+title: "Start Memorix with the sample dataset"
+summary: "Load the synthetic dataset and confirm scope."
+audiences: ["developers", "builders"]
+---
+# Start Memorix with the sample dataset
+
+Load the synthetic dataset and confirm scope.
+
+## 1. Apply demo scope
+
+
+
+## 2. List sample subjects
+
+

package/files/ui/clients/memorix-studio.md

@@ -0,0 +1,9 @@
+---
+id: "memorix-studio"
+type: "ui-client"
+title: "Memorix Studio"
+summary: "Service-oriented UI for designing, operating, and exploring Memorix."
+---
+# Memorix Studio
+
+Service-oriented UI for designing, operating, and exploring Memorix.

package/files/use-cases/abstract-people-list.md

@@ -0,0 +1,237 @@
+# Multi-type abstract list (People)
+
+> **Use case id:** `abstract-people-list`
+> **Goal:** List across concrete types via abstracts and reverse-map writes.
+> **Audiences:** developers
+> **Tags:** abstracts, metadata, http
+
+## Reading path
+
+1. **Metadata, Agents, Abstracts & Mappings** (developers) → chapters: `5-abstracts-virtual-unions-only`, `7-views-writes-and-the-client-effective-metadata-pattern`
+1. **Runtime Data Client** (developers) → chapters: `7-abstract-reads`, `12-abstract-writes`
+
+## From: Metadata, Agents, Abstracts & Mappings — 5. Abstracts — virtual unions only
+
+Hard rule **#4:** abstracts are virtual projections — **no** abstract collections, **no** abstract `recordId`.
+
+![Abstracts & bindings](../screenshots/05-abstracts-bindings.png)
+
+### Why abstracts exist
+
+Callers often want “all people” without knowing whether a subject is an `employees` or `contractors` record. An abstract type (`People`) is a **union projection** over concrete bindings.
+
+```text
+People (abstract, virtual)
+  ├─ employees (concrete) — snapshots via mapping
+  └─ contractors (concrete) — snapshots via mapping
+```
+
+There is no `people` Mongo collection and no `recordId` namespace owned by the abstract.
+
+### Abstract type (ops)
+
+```json
+{
+  "id": "People",
+  "name": "People",
+  "meaning": "Employees and contractors who perform operational work",
+  "category": "entity",
+  "properties": [
+    { "id": "title", "valueType": "string", "required": true },
+    { "id": "role", "valueType": "string", "required": true },
+    { "id": "lens", "valueType": "string", "required": false }
+  ]
+}
+```
+
+### Binding (union)
+
+```json
+{
+  "id": "people-employees-contractors",
+  "abstractType": "People",
+  "concreteObjectTypes": ["employees", "contractors"],
+  "union": true,
+  "notes": "People = Employees ∪ Contractors. No abstract records exist.",
+  "members": [
+    {
+      "objectType": "employees",
+      "contentType": "snapshots",
+      "properties": [
+        {
+          "abstractProperty": "title",
+          "contentType": "snapshots",
+          "mappingId": "ops-people-abstract-employees"
+        }
+      ]
+    },
+    {
+      "objectType": "contractors",
+      "contentType": "snapshots",
+      "properties": [
+        {
+          "abstractProperty": "title",
+          "contentType": "snapshots",
+          "mappingId": "ops-people-abstract-contractors"
+        }
+      ]
+    }
+  ]
+}
+```
+
+Studio Explore can list the union:
+
+![People union](../screenshots/11-people-union.png)
+
+### Reads vs writes
+
+| Operation | API idea | Where it lands |
+|---|---|---|
+| List / get abstract | `listAbstract` / `getAbstract` (data plane) | Virtual projection over concrete stores |
+| Patch abstract | `patchAbstract` | Reverse mapping → **one** concrete writer patch |
+| Write concrete | ordinary data write | Concrete `objectType` + `contentType` |
+
+```mermaid
+flowchart LR
+  Abs[Abstract People] --> Emp[employees]
+  Abs --> Con[contractors]
+  Patch[patchAbstract] --> Map[reverse mapping]
+  Map --> Writer[concrete patch via memorix-data]
+```
+
+See also [diagrams/abstract-reverse-write.md](../diagrams/abstract-reverse-write.md).
+
+### Reverse patch rules
+
+1. The caller patches **abstract properties** (for example `title`).
+2. Metadata bindings + mappings choose **which concrete object type** and **which content paths** receive the write.
+3. Exactly **one** concrete writer target is selected for a given patch context (union members are not written in parallel as “abstract records”).
+4. The data plane still enforces ordinary revision / concurrency rules on the concrete content.
+5. If reverse mapping cannot resolve a unique writer, the patch fails — do not invent an abstract identity.
+
+### What abstracts are not
+
+- Not a second database
+- Not a place to store relationship payloads
+- Not a substitute for four-field relationship links
+- Not auto-created when you invent a nice name in a host app — they must be declared and installed
+
+---
+
+## From: Metadata, Agents, Abstracts & Mappings — 7. Views, writes, and the client effective-metadata pattern
+
+Integrators should not invent list columns or write forms in the host. Load effective metadata, then drive UI from descriptors.
+
+### Pattern
+
+```text
+1. Resolve effective metadata for (orgId, agentIds[])
+2. Read views / writes / objectTypes / abstracts / custom kinds
+3. Render UI columns and forms from those descriptors
+4. Address data only with concrete types (or abstract reverse-write)
+5. Never bypass the service with direct Mongo domain writes
+```
+
+Example client sketch:
+
+```ts
+const effective = await fetch("/api/metadata/effective", {
+  headers: {
+    "x-memorix-org-id": orgId, // g12ops…
+    "x-memorix-agent-ids": "ops",
+  },
+}).then((r) => r.json());
+
+const employeeSnapshotWrite = effective.writes.find(
+  (w) => w.id === "ops-employees-snapshots",
+);
+
+// Drive form identity / required fields from employeeSnapshotWrite
+// Then POST/PATCH via /api/data against objectType: "employees", contentType: "snapshots"
+```
+
+### Built-in views / writes vs custom kinds
+
+Prefer built-in `views` and `writes` when the need is first-class Memorix shape or Studio-compatible UI composition. Use **custom kinds** (next chapter) when another client owns a descriptor vocabulary the platform should only store and resolve.
+
+---
+
+## From: Runtime Data Client — 7. Abstract reads
+
+Abstracts are **virtual projections** over concrete records. There is no `People` collection and no abstract `recordId`.
+
+### Operations
+
+- **Get** one abstract projection by concrete identity under an abstract type.
+- **List** an abstract union (e.g. People = employees ∪ contractors).
+- Each hit retains concrete `recordId` + `objectType`.
+- Direct **pushdown** filters run when the service can map them; unsupported non-pushdown queries fail clearly.
+- Cross-collection pagination is deterministic when exposed — trust the cursor, do not reimplement merges.
+- Abstract binding/provenance appears where the API exposes it.
+
+### Ops example — list People
+
+```bash
+curl -sS \
+  -H "x-memorix-org-id: $ORG" \
+  -H "x-memorix-agent-ids: $AGENTS" \
+  "$BASE/api/data/abstract?abstractType=People&limit=50"
+```
+
+Alex may appear as `objectType: "employees"`. A contractor peer appears as `objectType: "contractors"`. Both are People in the UI; neither is stored under a People collection.
+
+### May / must-not
+
+- **You may** bind UI forms to abstract property names when bindings exist.
+- **You must not** construct abstract storage paths or invent abstract record ids.
+- **You must not** write “into People” except via supported abstract reverse-write (`patchAbstract`) that targets one concrete member.
+
+---
+
+## From: Runtime Data Client — 12. Abstract writes
+
+Supported flow: **`patchAbstract`** (name per OpenAPI / data plane).
+
+1. Abstract type (e.g. `People`)
+2. Concrete `recordId` (Alex)
+3. Expected **concrete** revision
+4. Abstract-shaped changes
+5. Binding resolution → generated concrete update plan
+6. **One** concrete mutation
+
+### Failures (fail closed)
+
+| Failure | Meaning |
+|---|---|
+| Concrete record not a union member | Alex’s type not in People |
+| Unknown abstract property | No binding |
+| Non-reversible binding | Cannot map write safely |
+| Multi-target binding | Would touch more than one concrete path |
+| Conflicting reverse paths | Ambiguous plan |
+| Stale concrete revision | Refetch and retry |
+| Invalid generated path | Plan rejected |
+
+Abstract writes **never** create abstract records. They only reverse-map onto concrete content.
+
+### Ops example — patch People.title
+
+```ts
+await patchAbstract({
+  abstractType: "People",
+  recordId: "employee-10", // Alex
+  expectedRevision: 4,
+  changes: [{ op: "set", path: "title", value: "Operations lead" }],
+});
+// → one concrete employees snapshot patch
+```
+
+---
+
+## Also see
+
+- **Data Access Patterns** (`04-data-access-patterns`) — Decision matrix — best / acceptable / forbidden access methods for real client tasks.
+
+---
+
+_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._

package/files/use-cases/ai-pipeline-fail-closed.md

@@ -0,0 +1,117 @@
+# AI pipeline steps fail closed
+
+> **Use case id:** `ai-pipeline-fail-closed`
+> **Goal:** Add AI steps without silent invention; keep validation and retries honest.
+> **Audiences:** developers
+> **Tags:** pipelines, ai
+
+## Reading path
+
+1. **Building Pipelines** (developers) → chapters: `8-ai-pipelines`, `11-errors-catalog`
+1. **Building Services** (developers) → chapters: `9-secrets-validation-reliability`
+
+## From: Building Pipelines — 8. AI pipelines
+
+AI is **optional service execution**, not core pipeline intelligence.
+
+1. Capture exact record revisions, composition, relationship-expanded context, prompt/template fingerprint, model/service binding evidence.
+2. Invoke AI service step.
+3. Store raw response artifact/hash.
+4. Parse and validate structured output.
+5. Persist only through canonical ports.
+6. Several model attempts may differ; **one** accepted mutation applies.
+7. Recorded-response testing for acceptance; air-gapped execution supported.
+8. Failure/skip/fallback is explicit policy — never silent fake success.
+9. Metadata proposal pipelines never install metadata directly.
+
+Deterministic fixtures only for platform acceptance — **no live AI required**.
+
+---
+
+## From: Building Pipelines — 11. Errors (catalog)
+
+| Code class | Layer | Retryable? | Safe action |
+|---|---|---|---|
+| Invalid definition / unknown step / cycle | Validate | No | Fix pack |
+| Missing dependency / invalid reference | Validate | No | Fix graph |
+| Missing service / port | Startup/run | No | Bind registry / ports |
+| Missing prod ledger/artifact store | Startup | No | Configure durable stores |
+| Invalid scope / input | Run | No | Fix caller |
+| Mapping / validation failure | Step | No | Fix mapping/data |
+| Identity conflict | Step | No | Resolve identity |
+| Stale revision | Write | No auto | Re-read; new revision |
+| Relationship discover/write failure | Step | Often partial | Retry relationship portion |
+| Memory / cursor failure | Step | Often yes | Fix source; resume cursor |
+| Artifact missing / wrong org | DataRef | No | Restore / fix scope |
+| Timeout / cancelled | Attempt | Policy | Retry or accept cancel |
+| Retry exhausted | Step | No | Manual intervene |
+| Partial batch | Run | Mixed | Retry failed items |
+| Invalid AI output | Step | Policy | Repair or fail |
+| External action uncertain/failed | Step | Keyed only | Inspect receipt |
+| Unsupported atomicity | Validate | No | Disable atomicBatch |
+| Schedule error | Scheduler | No | Fix cron/config |
+
+Sanitize all evidence — no secrets, no unrestricted payloads.
+
+---
+
+## From: Building Services — 9. Secrets, validation, reliability
+
+### Credential references
+
+Service metadata and Memory configs carry `credentialRef` only. Runtime resolves credentials outside Catalox and never places them in metadata, records, run evidence, artifacts, errors, logs, or client responses.
+
+```http
+POST /api/memory/pull
+x-memorix-org-id: g12ops7a3c
+x-memorix-agent-ids: ops
+Content-Type: application/json
+
+{
+  "sourceId": "ops-source",
+  "credentialRef": "secret://ops-source"
+}
+```
+
+### Validation
+
+Schema validation, maximum sizes, path safety, content types, artifact type/hash, scope validation, unknown fields, structured error codes.
+
+### Timeouts and cancellation
+
+Deadline propagation, cancellation signal, cleanup, remote cancellation limits, cancelled attempt status, and honest uncertainty when an external side effect may already have occurred.
+
+### Idempotency declaration
+
+For every service declare: supported?, key shape, duplicate behavior, result reuse, side-effect receipt handling.
+
+Recommended key material: `(orgId, pipelineId, stepId, subjectRecordId, inputRevision)` or an explicit business key for external actions.
+
+### Error catalog (codes to handle)
+
+| Code class | Retryable? | Operator action |
+|---|---|---|
+| Configuration / missing binding | No | Fix pack / registry; redeploy |
+| Invalid input / validation | No | Fix caller or mapping |
+| Dependency unavailable | Yes | Wait / retry; check health |
+| Timeout | Often yes | Inspect attempt; raise timeout or fix hang |
+| Retryable external failure | Yes | Automatic / manual retry |
+| Terminal external failure | No | Fix external system or disable step |
+| Partial batch | Mixed | Retry failed items only |
+| Invalid output | No | Fix service contract / parser |
+| Artifact error | Depends | Restore artifact store / wrong-org check |
+| Stale write after service | No auto | Re-read; new revision; retry write |
+| Ambiguous identity / insufficient evidence | No | Human resolution / richer input |
+| AI parse / validation failure | Policy | Repair policy or fail terminal |
+
+Sanitize all errors — no secrets, no unrestricted payloads.
+
+---
+
+## Also see
+
+- **Structural Intelligence** (`10-intelligence`) — Profile data, proposals with evidence, human install boundary.
+
+---
+
+_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._