README.md
markdown
| 1 | # Muse Documentation |
| 2 | |
| 3 | > **Version:** v0.1.2 · [Project README](../README.md) · [Source](../muse/) |
| 4 | |
| 5 | This directory contains the complete documentation for Muse — a domain-agnostic version control system for multidimensional state. |
| 6 | |
| 7 | --- |
| 8 | |
| 9 | ## Quick Navigation |
| 10 | |
| 11 | | I want to… | Start here | |
| 12 | |-------------|-----------| |
| 13 | | Understand the full architecture | [Architecture Reference](architecture/muse-vcs.md) | |
| 14 | | Browse the CLI command tiers | [CLI Tiers Reference](reference/cli-tiers.md) | |
| 15 | | Build a new domain plugin | [Plugin Authoring Guide](guide/plugin-authoring-guide.md) | |
| 16 | | Learn CRDT semantics | [CRDT Reference](guide/crdt-reference.md) | |
| 17 | | See an end-to-end walkthrough | [E2E Demo](architecture/muse-e2e-demo.md) | |
| 18 | | Read the protocol spec | [Plugin Protocol](protocol/muse-protocol.md) | |
| 19 | | Understand domain concepts | [Domain Concepts](protocol/muse-domain-concepts.md) | |
| 20 | | Look up a named type | [Type Contracts](reference/type-contracts.md) | |
| 21 | | Configure merge strategies | [`.museattributes` Reference](reference/muse-attributes.md) | |
| 22 | | Exclude files from snapshots | [`.museignore` Reference](reference/museignore.md) | |
| 23 | | Watch the demo narration | [Demo Script](demo/demo-script.md) | |
| 24 | |
| 25 | --- |
| 26 | |
| 27 | ## Directory Map |
| 28 | |
| 29 | ``` |
| 30 | docs/ |
| 31 | ├── README.md ← you are here |
| 32 | │ |
| 33 | ├── architecture/ |
| 34 | │ ├── muse-vcs.md — full technical design: protocol stack, storage, |
| 35 | │ │ diff algorithms, OT merge, CRDT semantics, |
| 36 | │ │ config system, and CLI command map |
| 37 | │ └── muse-e2e-demo.md — step-by-step lifecycle: init → commit → branch |
| 38 | │ → merge conflict → resolve → tag |
| 39 | │ |
| 40 | ├── guide/ |
| 41 | │ ├── plugin-authoring-guide.md — complete walkthrough for writing a new domain |
| 42 | │ │ plugin, from core protocol through OT merge |
| 43 | │ │ and CRDT convergent merge |
| 44 | │ └── crdt-reference.md — CRDT primer: lattice laws, all six primitives |
| 45 | │ (VectorClock, LWWRegister, ORSet, RGA, AWMap, |
| 46 | │ GCounter), composition patterns, when to use CRDTs |
| 47 | │ |
| 48 | ├── protocol/ |
| 49 | │ ├── muse-protocol.md — language-agnostic MuseDomainPlugin spec: six |
| 50 | │ │ required methods, StructuredMergePlugin and |
| 51 | │ │ CRDTPlugin optional extensions, invariants |
| 52 | │ ├── muse-domain-concepts.md — universal vocabulary: what "state", "delta", |
| 53 | │ │ "dimension", "drift", and "merge" mean across |
| 54 | │ │ music, genomics, simulation, and beyond |
| 55 | │ └── muse-variation-spec.md — variation semantics for the MIDI domain |
| 56 | │ |
| 57 | ├── reference/ |
| 58 | │ ├── cli-tiers.md — three-tier CLI architecture: Tier 1 plumbing |
| 59 | │ │ (JSON, pipeable), Tier 2 porcelain (core VCS), |
| 60 | │ │ Tier 3 semantic (midi/code/coord namespaces) |
| 61 | │ ├── type-contracts.md — single source of truth for every named type: |
| 62 | │ │ TypedDicts, dataclasses, Protocols, Enums, |
| 63 | │ │ and TypeAliases with Mermaid diagrams |
| 64 | │ ├── muse-attributes.md — .museattributes TOML format reference: |
| 65 | │ │ [meta] domain, [[rules]] syntax, all five |
| 66 | │ │ strategies, multi-domain usage, examples |
| 67 | │ └── museignore.md — .museignore format: glob patterns, negation, |
| 68 | │ dotfile exclusion rules |
| 69 | │ |
| 70 | └── demo/ |
| 71 | └── demo-script.md — narration script for the video demo covering |
| 72 | all nine acts: core VCS through CRDT semantics |
| 73 | and the live domain dashboard |
| 74 | ``` |
| 75 | |
| 76 | --- |
| 77 | |
| 78 | ## Architecture at a Glance |
| 79 | |
| 80 | Muse separates the **VCS engine** (domain-agnostic) from **domain plugins** (domain-specific). The engine never changes when a new domain is added — only a new plugin is registered. |
| 81 | |
| 82 | ``` |
| 83 | ┌─────────────────────────────────────────────┐ |
| 84 | │ muse CLI │ |
| 85 | │ Tier 1: plumbing · Tier 2: porcelain │ |
| 86 | │ Tier 3: midi / code / coord domains │ |
| 87 | └──────────────────────┬──────────────────────┘ |
| 88 | │ |
| 89 | ┌──────────────────────▼──────────────────────┐ |
| 90 | │ Muse Core Engine │ |
| 91 | │ DAG · object store · branching · merging │ |
| 92 | │ content-addressed blobs · lineage walking │ |
| 93 | └──────┬────────────────────────────┬─────────┘ |
| 94 | │ │ |
| 95 | ┌──────▼──────┐ ┌──────▼──────┐ |
| 96 | │MuseDomainPlugin│ │MuseDomainPlugin│ |
| 97 | │ (music) │ │ (your domain) │ |
| 98 | │ 6 methods │ │ 6 methods │ |
| 99 | └──────────────┘ └───────────────┘ |
| 100 | ``` |
| 101 | |
| 102 | The six required methods: |
| 103 | |
| 104 | | Method | What it does | |
| 105 | |--------|-------------| |
| 106 | | `snapshot()` | Capture live state → content-addressed dict | |
| 107 | | `diff()` | Compute typed delta between two snapshots | |
| 108 | | `merge()` | Three-way reconciliation against a common ancestor | |
| 109 | | `drift()` | Compare committed state against live working tree | |
| 110 | | `apply()` | Apply a delta to reconstruct historical state | |
| 111 | | `schema()` | Declare data structure → drives diff algorithm selection | |
| 112 | |
| 113 | Two optional protocol extensions enable richer merge semantics: |
| 114 | |
| 115 | | Extension | Adds | Effect | |
| 116 | |-----------|------|--------| |
| 117 | | `StructuredMergePlugin` | `merge_ops()` | Operation-level OT merge — minimal real conflicts | |
| 118 | | `CRDTPlugin` | `join()` + 3 helpers | Convergent merge — `join` always succeeds, no conflict state | |
| 119 | |
| 120 | --- |
| 121 | |
| 122 | ## Adding a New Domain |
| 123 | |
| 124 | 1. Copy `muse/plugins/scaffold/` → `muse/plugins/<your_domain>/` |
| 125 | 2. Rename `ScaffoldPlugin` → `<YourDomain>Plugin` |
| 126 | 3. Replace every `raise NotImplementedError(...)` with real implementation |
| 127 | 4. Register in `muse/plugins/registry.py` |
| 128 | 5. Run `muse init --domain <your_domain>` in a project directory |
| 129 | |
| 130 | All Tier 2 core VCS commands work immediately for the new domain. Tier 3 semantic commands live in the new `muse/<domain> …` sub-namespace. See the [Plugin Authoring Guide](guide/plugin-authoring-guide.md) for the full walkthrough. |
| 131 | |
| 132 | --- |
| 133 | |
| 134 | ## Config Files Generated by `muse init` |
| 135 | |
| 136 | | File | Location | Purpose | |
| 137 | |------|----------|---------| |
| 138 | | `repo.json` | `.muse/repo.json` | Immutable identity: repo UUID, schema version, domain | |
| 139 | | `config.toml` | `.muse/config.toml` | Mutable: `[user]`, `[auth]`, `[remotes]`, `[domain]` | |
| 140 | | `HEAD` | `.muse/HEAD` | Current branch ref | |
| 141 | | `.museattributes` | repo root | TOML merge strategy overrides (`[[rules]]`) | |
| 142 | | `.museignore` | repo root | Glob patterns to exclude from snapshots | |
| 143 | |
| 144 | --- |
| 145 | |
| 146 | ## Testing Standards |
| 147 | |
| 148 | Every public function has a unit test. Integration tests wire real components. E2E tests invoke the CLI via `typer.testing.CliRunner`. |
| 149 | |
| 150 | ```bash |
| 151 | # Run all tests |
| 152 | pytest tests/ -v |
| 153 | |
| 154 | # Type-check |
| 155 | mypy muse/ |
| 156 | |
| 157 | # Zero-Any audit |
| 158 | python tools/typing_audit.py --dirs muse/ tests/ --max-any 0 |
| 159 | ``` |
| 160 | |
| 161 | All three gates must be green before any PR merges. |