README.md
markdown
| 1 | # Muse Documentation |
| 2 | |
| 3 | > **Version:** v0.1.3 · [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 | | Authenticate with MuseHub | [Auth Reference](reference/auth.md) | |
| 15 | | Connect a repo to a hub | [Hub Reference](reference/hub.md) | |
| 16 | | Understand the security model | [Security Architecture](reference/security.md) | |
| 17 | | Push, fetch, or clone a repo | [Remotes Reference](reference/remotes.md) | |
| 18 | | Browse the CLI command tiers | [CLI Tiers Reference](reference/cli-tiers.md) | |
| 19 | | See all MIDI semantic commands | [MIDI Domain Reference](reference/midi-domain.md) | |
| 20 | | See all Code semantic commands | [Code Domain Reference](reference/code-domain.md) | |
| 21 | | Build a new domain plugin | [Plugin Authoring Guide](guide/plugin-authoring-guide.md) | |
| 22 | | Learn CRDT semantics | [CRDT Reference](guide/crdt-reference.md) | |
| 23 | | See an end-to-end walkthrough | [E2E Demo](architecture/muse-e2e-demo.md) | |
| 24 | | Read the protocol spec | [Plugin Protocol](protocol/muse-protocol.md) | |
| 25 | | Understand domain concepts | [Domain Concepts](protocol/muse-domain-concepts.md) | |
| 26 | | Look up a named type | [Type Contracts](reference/type-contracts.md) | |
| 27 | | Configure merge strategies | [`.museattributes` Reference](reference/muse-attributes.md) | |
| 28 | | Exclude files from snapshots | [`.museignore` Reference](reference/museignore.md) | |
| 29 | | Undo accidental resets | [Reflog Reference](reference/reflog.md) | |
| 30 | | Remove unused blobs | [GC Reference](reference/gc.md) | |
| 31 | | Export a versioned archive | [Archive Reference](reference/archive.md) | |
| 32 | | Hunt regressions automatically | [Bisect Reference](reference/bisect.md) | |
| 33 | | Attribute text file lines | [Blame Reference](reference/blame.md) | |
| 34 | | Work on multiple branches at once | [Worktree Reference](reference/worktree.md) | |
| 35 | | Compose multiple Muse repos | [Workspace Reference](reference/workspace.md) | |
| 36 | | Watch the demo narration | [Demo Script](demo/demo-script.md) | |
| 37 | |
| 38 | --- |
| 39 | |
| 40 | ## Directory Map |
| 41 | |
| 42 | ``` |
| 43 | docs/ |
| 44 | ├── README.md ← you are here |
| 45 | │ |
| 46 | ├── architecture/ |
| 47 | │ ├── muse-vcs.md — full technical design: protocol stack, storage, |
| 48 | │ │ diff algorithms, OT merge, CRDT semantics, |
| 49 | │ │ config system, and CLI command map |
| 50 | │ └── muse-e2e-demo.md — step-by-step lifecycle: init → commit → branch |
| 51 | │ → merge conflict → resolve → tag |
| 52 | │ |
| 53 | ├── guide/ |
| 54 | │ ├── plugin-authoring-guide.md — complete walkthrough for writing a new domain |
| 55 | │ │ plugin, from core protocol through OT merge |
| 56 | │ │ and CRDT convergent merge |
| 57 | │ └── crdt-reference.md — CRDT primer: lattice laws, all six primitives |
| 58 | │ (VectorClock, LWWRegister, ORSet, RGA, AWMap, |
| 59 | │ GCounter), composition patterns, when to use CRDTs |
| 60 | │ |
| 61 | ├── protocol/ |
| 62 | │ ├── muse-protocol.md — language-agnostic MuseDomainPlugin spec: six |
| 63 | │ │ required methods, StructuredMergePlugin and |
| 64 | │ │ CRDTPlugin optional extensions, invariants |
| 65 | │ ├── muse-domain-concepts.md — universal vocabulary: what "state", "delta", |
| 66 | │ │ "dimension", "drift", and "merge" mean across |
| 67 | │ │ music, genomics, simulation, and beyond |
| 68 | │ └── muse-variation-spec.md — variation semantics for the MIDI domain |
| 69 | │ |
| 70 | ├── reference/ |
| 71 | │ ├── auth.md — muse auth login/whoami/logout: identity lifecycle, |
| 72 | │ │ ~/.muse/identity.toml format, env vars, flows |
| 73 | │ ├── hub.md — muse hub connect/status/disconnect/ping: hub fabric, |
| 74 | │ │ hub vs remote distinction, HTTPS enforcement |
| 75 | │ ├── remotes.md — muse push/fetch/clone/pull/remote: transport arch, |
| 76 | │ │ PackBundle wire format, tracking branches |
| 77 | │ ├── security.md — security architecture: validation trust model, |
| 78 | │ │ path containment, ANSI injection, XML safety, |
| 79 | │ │ transport hardening, identity store guarantees |
| 80 | │ ├── cli-tiers.md — three-tier CLI architecture: Tier 1 plumbing |
| 81 | │ │ (JSON, pipeable), Tier 2 porcelain (core VCS), |
| 82 | │ │ Tier 3 semantic (midi/code/coord namespaces) |
| 83 | │ ├── midi-domain.md — MIDI domain complete reference: all 31 semantic |
| 84 | │ │ porcelain commands, flags, JSON schemas, types |
| 85 | │ ├── code-domain.md — Code domain complete reference: all semantic |
| 86 | │ │ porcelain commands, symbol identity model, types |
| 87 | │ ├── type-contracts.md — single source of truth for every named type: |
| 88 | │ │ TypedDicts, dataclasses, Protocols, Enums, |
| 89 | │ │ and TypeAliases with Mermaid diagrams |
| 90 | │ ├── muse-attributes.md — .museattributes TOML format reference: |
| 91 | │ │ [meta] domain, [[rules]] syntax, all five |
| 92 | │ │ strategies, multi-domain usage, examples |
| 93 | │ ├── museignore.md — .museignore format: glob patterns, negation, |
| 94 | │ │ dotfile exclusion rules |
| 95 | │ ├── reflog.md — muse reflog: HEAD/branch movement history, |
| 96 | │ │ undo safety net, per-ref journals |
| 97 | │ ├── gc.md — muse gc: reachability walk, dry-run, stats, |
| 98 | │ │ when and why to run garbage collection |
| 99 | │ ├── archive.md — muse archive: tar.gz/zip export, --prefix, |
| 100 | │ │ --ref, distribution without history |
| 101 | │ ├── bisect.md — muse bisect: binary regression search, |
| 102 | │ │ start/bad/good/skip/run/log/reset, agent-safe |
| 103 | │ ├── blame.md — muse blame: line-level text attribution, |
| 104 | │ │ porcelain JSON output, attribution algorithm |
| 105 | │ ├── worktree.md — muse worktree: parallel branch checkouts, |
| 106 | │ │ shared object store, agent-per-branch pattern |
| 107 | │ └── workspace.md — muse workspace: multi-repo composition, |
| 108 | │ manifest, sync, coordinator/worker patterns |
| 109 | │ |
| 110 | └── demo/ |
| 111 | ├── midi-demo.md — MIDI domain demo walkthrough: all 31 semantic |
| 112 | │ porcelain commands with CLI output examples |
| 113 | ├── demo-code.md — Code domain demo walkthrough |
| 114 | └── demo-script.md — narration script for the video demo |
| 115 | ``` |
| 116 | |
| 117 | --- |
| 118 | |
| 119 | ## Architecture at a Glance |
| 120 | |
| 121 | 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. |
| 122 | |
| 123 | ``` |
| 124 | ┌─────────────────────────────────────────────┐ |
| 125 | │ muse CLI │ |
| 126 | │ Tier 1: plumbing · Tier 2: porcelain │ |
| 127 | │ Tier 3: midi / code / coord domains │ |
| 128 | └──────────────────────┬──────────────────────┘ |
| 129 | │ |
| 130 | ┌──────────────────────▼──────────────────────┐ |
| 131 | │ Muse Core Engine │ |
| 132 | │ DAG · object store · branching · merging │ |
| 133 | │ content-addressed blobs · lineage walking │ |
| 134 | └──────┬────────────────────────────┬─────────┘ |
| 135 | │ │ |
| 136 | ┌──────▼──────┐ ┌──────▼──────┐ |
| 137 | │MuseDomainPlugin│ │MuseDomainPlugin│ |
| 138 | │ (music) │ │ (your domain) │ |
| 139 | │ 6 methods │ │ 6 methods │ |
| 140 | └──────────────┘ └───────────────┘ |
| 141 | ``` |
| 142 | |
| 143 | The six required methods: |
| 144 | |
| 145 | | Method | What it does | |
| 146 | |--------|-------------| |
| 147 | | `snapshot()` | Capture live state → content-addressed dict | |
| 148 | | `diff()` | Compute typed delta between two snapshots | |
| 149 | | `merge()` | Three-way reconciliation against a common ancestor | |
| 150 | | `drift()` | Compare committed state against live working tree | |
| 151 | | `apply()` | Apply a delta to reconstruct historical state | |
| 152 | | `schema()` | Declare data structure → drives diff algorithm selection | |
| 153 | |
| 154 | Two optional protocol extensions enable richer merge semantics: |
| 155 | |
| 156 | | Extension | Adds | Effect | |
| 157 | |-----------|------|--------| |
| 158 | | `StructuredMergePlugin` | `merge_ops()` | Operation-level OT merge — minimal real conflicts | |
| 159 | | `CRDTPlugin` | `join()` + 3 helpers | Convergent merge — `join` always succeeds, no conflict state | |
| 160 | |
| 161 | --- |
| 162 | |
| 163 | ## Adding a New Domain |
| 164 | |
| 165 | 1. Copy `muse/plugins/scaffold/` → `muse/plugins/<your_domain>/` |
| 166 | 2. Rename `ScaffoldPlugin` → `<YourDomain>Plugin` |
| 167 | 3. Replace every `raise NotImplementedError(...)` with real implementation |
| 168 | 4. Register in `muse/plugins/registry.py` |
| 169 | 5. Run `muse init --domain <your_domain>` in a project directory |
| 170 | |
| 171 | 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. |
| 172 | |
| 173 | --- |
| 174 | |
| 175 | ## Config Files Generated by `muse init` |
| 176 | |
| 177 | | File | Location | Purpose | |
| 178 | |------|----------|---------| |
| 179 | | `repo.json` | `.muse/repo.json` | Immutable identity: repo UUID, schema version, domain | |
| 180 | | `config.toml` | `.muse/config.toml` | Mutable: `[user]`, `[auth]`, `[remotes]`, `[domain]` | |
| 181 | | `HEAD` | `.muse/HEAD` | Current branch ref | |
| 182 | | `.museattributes` | repo root | TOML merge strategy overrides (`[[rules]]`) | |
| 183 | | `.museignore` | repo root | Glob patterns to exclude from snapshots | |
| 184 | |
| 185 | --- |
| 186 | |
| 187 | ## Testing Standards |
| 188 | |
| 189 | Every public function has a unit test. Integration tests wire real components. E2E tests invoke the CLI via `typer.testing.CliRunner`. |
| 190 | |
| 191 | ```bash |
| 192 | # Run all tests |
| 193 | pytest tests/ -v |
| 194 | |
| 195 | # Type-check |
| 196 | mypy muse/ |
| 197 | |
| 198 | # Zero-Any audit |
| 199 | python tools/typing_audit.py --dirs muse/ tests/ --max-any 0 |
| 200 | ``` |
| 201 | |
| 202 | All three gates must be green before any PR merges. |