@x12i/memorix-docs 1.0.2 → 1.1.0

package/files/diagrams/metadata-lifecycle.md

@@ -0,0 +1,40 @@
+---
+id: "metadata-lifecycle"
+type: "diagram"
+title: "Metadata lifecycle"
+summary: "Pack → validate → explicit install → effective resolution → runtime; proposals stay off the auto path."
+why: "Separates proposal, approval, installation, and use."
+diagramType: "flow"
+---
+# Metadata lifecycle
+
+Pack → validate → explicit install → effective resolution → runtime; proposals stay off the auto path.
+
+## Why
+
+Separates proposal, approval, installation, and use.
+
+## How to read
+
+Follow the solid path; proposals branch and never auto-join install.
+
+## Text alternative
+
+A metadata pack is validated, then explicitly installed, resolved into the effective model, and consumed at runtime. Intelligence proposals require a separate explicit install path and never auto-install.
+
+## Nodes
+
+- **Pack** (`pack`)
+- **Validate** (`validate`)
+- **Explicit install** (`install`)
+- **Effective** (`effective`)
+- **Runtime** (`runtime`)
+- **Intelligence proposal** (`proposal`)
+
+## Edges
+
+- pack → validate (check)
+- validate → install (confirm)
+- install → effective (resolve)
+- effective → runtime (use)
+- proposal → validate (review only)

package/files/diagrams/people-union-diagram.md

@@ -0,0 +1,36 @@
+---
+id: "people-union-diagram"
+type: "diagram"
+title: "People abstract union"
+summary: "Employees and contractors bind into the People abstract projection."
+why: "Shows virtual union without stored merged rows."
+diagramType: "relationship-map"
+---
+# People abstract union
+
+Employees and contractors bind into the People abstract projection.
+
+## Why
+
+Shows virtual union without stored merged rows.
+
+## How to read
+
+Concrete types feed bindings into People.
+
+## Text alternative
+
+Employees and contractors are bound into the People abstract. Combined reads return concrete members under the People projection.
+
+## Nodes
+
+- **employees** (`employees`)
+- **contractors** (`contractors`)
+- **Bindings** (`bindings`)
+- **People** (`people`)
+
+## Edges
+
+- employees → bindings
+- contractors → bindings
+- bindings → people (project)

package/files/diagrams/record-content-model.md

@@ -0,0 +1,43 @@
+---
+id: "record-content-model"
+type: "diagram"
+title: "Record and content model"
+summary: "Record identity relates to object type, content type, category, raw, snapshots, and composition."
+why: "Keeps identity and payload axes distinct."
+diagramType: "entity-relationship"
+---
+# Record and content model
+
+Record identity relates to object type, content type, category, raw, snapshots, and composition.
+
+## Why
+
+Keeps identity and payload axes distinct.
+
+## How to read
+
+Center on the record; spokes are model axes and views.
+
+## Text alternative
+
+A record identity has an object type, content type, and data category. Raw content and snapshots are content instances that can be composed for the same subject.
+
+## Nodes
+
+- **Record identity** (`record`)
+- **Object type** (`object`)
+- **Content type** (`content`)
+- **Data category** (`category`)
+- **Raw** (`raw`)
+- **Snapshot** (`snap`)
+- **Composition** (`compose`)
+
+## Edges
+
+- record → object
+- record → content
+- record → category
+- record → raw
+- record → snap
+- raw → compose
+- snap → compose

package/files/diagrams/relationship-traversal.md

@@ -0,0 +1,40 @@
+---
+id: "relationship-traversal"
+type: "diagram"
+title: "Relationship definition to traversal"
+summary: "Definition versus stored reference; forward/inverse; resolved versus unresolved."
+why: "Prevents treating definitions as edges."
+diagramType: "flow"
+---
+# Relationship definition to traversal
+
+Definition versus stored reference; forward/inverse; resolved versus unresolved.
+
+## Why
+
+Prevents treating definitions as edges.
+
+## How to read
+
+Definition enables references; traversal yields resolved or unresolved targets.
+
+## Text alternative
+
+A relationship definition enables stored references. Traversal may go forward or inverse and can return resolved or unresolved targets.
+
+## Nodes
+
+- **Definition** (`def`)
+- **Stored ref** (`ref`)
+- **Forward** (`fwd`)
+- **Inverse** (`inv`)
+- **Resolved** (`resolved`)
+- **Unresolved** (`unresolved`)
+
+## Edges
+
+- def → ref
+- ref → fwd
+- ref → inv
+- fwd → resolved
+- fwd → unresolved

package/files/diagrams/revision-safe-write.md

@@ -0,0 +1,39 @@
+---
+id: "revision-safe-write"
+type: "diagram"
+title: "Revision-safe write flow"
+summary: "Load, write with expected revision, success or conflict with reload/retry."
+why: "Makes stale-write recovery explicit."
+diagramType: "state"
+---
+# Revision-safe write flow
+
+Load, write with expected revision, success or conflict with reload/retry.
+
+## Why
+
+Makes stale-write recovery explicit.
+
+## How to read
+
+Conflict path returns to reload; success updates revision.
+
+## Text alternative
+
+Load a record and its revision. Write with that expected revision. On success the revision advances. On conflict, reload and retry or escalate; the record was not changed by the failed write.
+
+## Nodes
+
+- **Load** (`load`)
+- **Write + expected rev** (`write`)
+- **Success** (`ok`)
+- **Conflict** (`conflict`)
+- **Reload/retry** (`reload`)
+
+## Edges
+
+- load → write
+- write → ok (match)
+- write → conflict (stale)
+- conflict → reload
+- reload → write

package/files/examples/analysis-decision-records.md

@@ -0,0 +1,11 @@
+---
+id: "analysis-decision-records"
+type: "example"
+title: "Analysis and decision records"
+summary: "Keep analysis and decision content types distinct."
+---
+# Analysis and decision records
+
+Keep analysis and decision content types distinct.
+
+

package/files/examples/memorix-record-envelope.md

@@ -0,0 +1,11 @@
+---
+id: "memorix-record-envelope"
+type: "example"
+title: "memorix-record/2 envelope"
+summary: "Show identity, revision, and content envelope fields."
+---
+# memorix-record/2 envelope
+
+Show identity, revision, and content envelope fields.
+
+Envelope metadata is distinct from product payload.

package/files/examples/metadata-pack-install.md

@@ -0,0 +1,11 @@
+---
+id: "metadata-pack-install"
+type: "example"
+title: "Metadata-pack validation and explicit installation"
+summary: "Evidence that validate ≠ install."
+---
+# Metadata-pack validation and explicit installation
+
+Evidence that validate ≠ install.
+
+

package/files/examples/people-abstract-query.md

@@ -0,0 +1,11 @@
+---
+id: "people-abstract-query"
+type: "example"
+title: "People abstract query/result"
+summary: "Demonstrate union projection."
+---
+# People abstract query/result
+
+Demonstrate union projection.
+
+

package/files/examples/raw-vs-composed.md

@@ -0,0 +1,11 @@
+---
+id: "raw-vs-composed"
+type: "example"
+title: "Raw versus composed subject responses"
+summary: "Compare fidelity of raw and composition."
+---
+# Raw versus composed subject responses
+
+Compare fidelity of raw and composition.
+
+

package/files/examples/relationship-def-and-ref.md

@@ -0,0 +1,11 @@
+---
+id: "relationship-def-and-ref"
+type: "example"
+title: "Relationship definition and stored reference"
+summary: "Contrast metadata definition with stored ref."
+---
+# Relationship definition and stored reference
+
+Contrast metadata definition with stored ref.
+
+

package/files/examples/revision-conflict-response.md

@@ -0,0 +1,11 @@
+---
+id: "revision-conflict-response"
+type: "example"
+title: "Revision conflict response and retry"
+summary: "Show conflict payload and retry input."
+---
+# Revision conflict response and retry
+
+Show conflict payload and retry input.
+
+

package/files/examples/revision-safe-write.md

@@ -0,0 +1,11 @@
+---
+id: "revision-safe-write"
+type: "example"
+title: "Revision-safe write"
+summary: "Write with expected revision."
+---
+# Revision-safe write
+
+Write with expected revision.
+
+

package/files/examples/traversal-resolved-unresolved.md

@@ -0,0 +1,11 @@
+---
+id: "traversal-resolved-unresolved"
+type: "example"
+title: "Forward/inverse traversal with resolved and unresolved targets"
+summary: "Show both target states."
+---
+# Forward/inverse traversal with resolved and unresolved targets
+
+Show both target states.
+
+

package/files/glossary/abstract.md

@@ -0,0 +1,9 @@
+---
+id: "abstract"
+type: "glossary-term"
+title: "Abstract"
+summary: "Virtual projected union over concrete types via bindings."
+---
+# Abstract
+
+Virtual projected union over concrete types via bindings.

package/files/glossary/agent.md

@@ -0,0 +1,9 @@
+---
+id: "agent"
+type: "glossary-term"
+title: "Agent"
+summary: "An inheritance and configuration unit inside an organization."
+---
+# Agent
+
+An inheritance and configuration unit inside an organization.

package/files/glossary/analysis.md

@@ -0,0 +1,9 @@
+---
+id: "analysis"
+type: "glossary-term"
+title: "Analysis"
+summary: "Evaluated evidence content distinct from a decision."
+---
+# Analysis
+
+Evaluated evidence content distinct from a decision.

package/files/glossary/binding.md

@@ -0,0 +1,9 @@
+---
+id: "binding"
+type: "glossary-term"
+title: "Binding"
+summary: "Maps concrete members into an abstract."
+---
+# Binding
+
+Maps concrete members into an abstract.

package/files/glossary/composition.md

@@ -0,0 +1,9 @@
+---
+id: "composition"
+type: "glossary-term"
+title: "Composition"
+summary: "Explicit same-subject aggregation of content instances."
+---
+# Composition
+
+Explicit same-subject aggregation of content instances.

package/files/glossary/content-type.md

@@ -0,0 +1,9 @@
+---
+id: "content-type"
+type: "glossary-term"
+title: "Content type"
+summary: "Shape of a content instance on a subject."
+---
+# Content type
+
+Shape of a content instance on a subject.

package/files/glossary/data-category.md

@@ -0,0 +1,9 @@
+---
+id: "data-category"
+type: "glossary-term"
+title: "Data category"
+summary: "Category axis distinct from object and content type."
+---
+# Data category
+
+Category axis distinct from object and content type.

package/files/glossary/decision.md

@@ -0,0 +1,9 @@
+---
+id: "decision"
+type: "glossary-term"
+title: "Decision"
+summary: "Committed choice recorded separately from analysis."
+---
+# Decision
+
+Committed choice recorded separately from analysis.

package/files/glossary/effective-metadata.md

@@ -0,0 +1,9 @@
+---
+id: "effective-metadata"
+type: "glossary-term"
+title: "Effective metadata"
+summary: "Resolved definitions after inheritance and installation."
+---
+# Effective metadata
+
+Resolved definitions after inheritance and installation.

package/files/glossary/intelligence-proposal.md

@@ -0,0 +1,9 @@
+---
+id: "intelligence-proposal"
+type: "glossary-term"
+title: "Intelligence proposal"
+summary: "Suggested change that never auto-installs."
+---
+# Intelligence proposal
+
+Suggested change that never auto-installs.

package/files/glossary/mapping.md

@@ -0,0 +1,9 @@
+---
+id: "mapping"
+type: "glossary-term"
+title: "Mapping"
+summary: "Declared transform from source shape to Memory content."
+---
+# Mapping
+
+Declared transform from source shape to Memory content.

package/files/glossary/memory.md

@@ -0,0 +1,9 @@
+---
+id: "memory"
+type: "glossary-term"
+title: "Memory"
+summary: "Durable store of Memorix records."
+---
+# Memory
+
+Durable store of Memorix records.

package/files/glossary/object-type.md

@@ -0,0 +1,9 @@
+---
+id: "object-type"
+type: "glossary-term"
+title: "Object type"
+summary: "Identity kind for a record subject."
+---
+# Object type
+
+Identity kind for a record subject.

package/files/glossary/relationship-definition.md

@@ -0,0 +1,9 @@
+---
+id: "relationship-definition"
+type: "glossary-term"
+title: "Relationship definition"
+summary: "Metadata describing an allowed relationship kind."
+---
+# Relationship definition
+
+Metadata describing an allowed relationship kind.

package/files/glossary/relationship-reference.md

@@ -0,0 +1,9 @@
+---
+id: "relationship-reference"
+type: "glossary-term"
+title: "Relationship reference"
+summary: "Stored link instance on a record."
+---
+# Relationship reference
+
+Stored link instance on a record.

package/files/glossary/revision.md

@@ -0,0 +1,9 @@
+---
+id: "revision"
+type: "glossary-term"
+title: "Revision"
+summary: "Optimistic concurrency token on a record."
+---
+# Revision
+
+Optimistic concurrency token on a record.

package/files/glossary/scope.md

@@ -0,0 +1,9 @@
+---
+id: "scope"
+type: "glossary-term"
+title: "Scope"
+summary: "Selected organization and agent context for reads and writes."
+---
+# Scope
+
+Selected organization and agent context for reads and writes.

package/files/glossary/source.md

@@ -0,0 +1,9 @@
+---
+id: "source"
+type: "glossary-term"
+title: "Source"
+summary: "Origin that feeds content into Memory."
+---
+# Source
+
+Origin that feeds content into Memory.

package/files/glossary/traversal.md

@@ -0,0 +1,9 @@
+---
+id: "traversal"
+type: "glossary-term"
+title: "Traversal"
+summary: "Forward or inverse walk of relationship references."
+---
+# Traversal
+
+Forward or inverse walk of relationship references.

package/files/guides/apply-scope.md

@@ -0,0 +1,40 @@
+---
+id: "apply-scope"
+type: "guide"
+title: "Select and apply organization/agent scope"
+summary: "Set the workspace scope before reading or writing."
+why: "Wrong scope violates isolation."
+audiences: ["builders", "developers"]
+related: ["org-agent-scope"]
+invariants: ["Do not mutate another organization's data"]
+confirmationRequired: false
+---
+# Select and apply organization/agent scope
+
+Set the workspace scope before reading or writing.
+
+## Why this path
+
+Wrong scope violates isolation.
+
+## Use this when
+
+- Entering Studio or an API session
+
+## Do not use this when
+
+- You already confirmed the active scope matches the task
+
+## Invariants
+
+- Do not mutate another organization's data
+
+## Steps
+
+1. **Choose organization** — Org selected
+2. **Choose agent** — Agent selected
+3. **Apply scope** — UI/API uses that scope
+
+## Verification
+
+- Subsequent reads show the expected workspace

package/files/guides/choose-access-method.md

@@ -0,0 +1,24 @@
+---
+id: "choose-access-method"
+type: "guide"
+title: "Choose raw, composed, or abstract access"
+summary: "Pick the fidelity that matches the caller goal."
+why: "Wrong view wastes work or loses detail."
+audiences: ["developers"]
+related: ["raw-records", "composition", "people-union"]
+---
+# Choose raw, composed, or abstract access
+
+Pick the fidelity that matches the caller goal.
+
+## Why this path
+
+Wrong view wastes work or loses detail.
+
+## Steps
+
+1. **Match goal to raw vs composition vs abstract** — Access method chosen
+
+## Verification
+
+- Response shape matches the chosen view

package/files/guides/compose-subject-ui.md

@@ -0,0 +1,24 @@
+---
+id: "compose-subject-ui"
+type: "guide"
+title: "Compose same-subject content for a UI"
+summary: "Load composition for a subject the UI will render."
+why: "UIs need the bag of content instances, not only raw."
+audiences: ["developers", "builders"]
+related: ["composition"]
+---
+# Compose same-subject content for a UI
+
+Load composition for a subject the UI will render.
+
+## Why this path
+
+UIs need the bag of content instances, not only raw.
+
+## Steps
+
+1. **Request same-subject composition** — Composed payload
+
+## Verification
+
+- Expected content types present

package/files/guides/define-traverse-relationship.md

@@ -0,0 +1,26 @@
+---
+id: "define-traverse-relationship"
+type: "guide"
+title: "Define and traverse a relationship"
+summary: "Author a definition, store a reference, traverse forward/inverse."
+why: "Traversal is only predictable with explicit definitions."
+audiences: ["developers"]
+related: ["relationship-definitions", "traversal"]
+---
+# Define and traverse a relationship
+
+Author a definition, store a reference, traverse forward/inverse.
+
+## Why this path
+
+Traversal is only predictable with explicit definitions.
+
+## Steps
+
+1. **Author relationship definition** — Definition installed
+2. **Store relationship reference** — Ref on record
+3. **Traverse with chosen direction** — Targets returned
+
+## Verification
+
+- Forward and inverse match the definition

package/files/guides/diagnose-unresolved.md

@@ -0,0 +1,24 @@
+---
+id: "diagnose-unresolved"
+type: "guide"
+title: "Diagnose an unresolved relationship target"
+summary: "Distinguish intentional unresolved from broken targets."
+why: "Unresolved is retained as a first-class state."
+audiences: ["developers", "builders"]
+related: ["resolved-unresolved"]
+---
+# Diagnose an unresolved relationship target
+
+Distinguish intentional unresolved from broken targets.
+
+## Why this path
+
+Unresolved is retained as a first-class state.
+
+## Steps
+
+1. **Inspect unresolved marker and definition** — Cause classified
+
+## Verification
+
+- Chosen repair/wait/escalate path documented