Muse Documentation

Version: v0.1.3 · Project README · Source

This directory contains the complete documentation for Muse — a domain-agnostic version control system for multidimensional state.

I want to…	Start here
Understand the full architecture	Architecture Reference
Authenticate with MuseHub	Auth Reference
Connect a repo to a hub	Hub Reference
Understand the security model	Security Architecture
Push, fetch, or clone a repo	Remotes Reference
Browse the CLI command tiers	CLI Tiers Reference
See all MIDI semantic commands	MIDI Domain Reference
See all Code semantic commands	Code Domain Reference
Build a new domain plugin	Plugin Authoring Guide
Learn CRDT semantics	CRDT Reference
See an end-to-end walkthrough	E2E Demo
Read the protocol spec	Plugin Protocol
Understand domain concepts	Domain Concepts
Look up a named type	Type Contracts
Configure merge strategies	`.museattributes` Reference
Exclude files from snapshots	`.museignore` Reference
Undo accidental resets	Reflog Reference
Remove unused blobs	GC Reference
Export a versioned archive	Archive Reference
Hunt regressions automatically	Bisect Reference
Attribute text file lines	Blame Reference
Work on multiple branches at once	Worktree Reference
Compose multiple Muse repos	Workspace Reference
Watch the demo narration	Demo Script

Directory Map

docs/
├── README.md                     ← you are here
│
├── architecture/
│   ├── muse-vcs.md               — full technical design: protocol stack, storage,
│   │                               diff algorithms, OT merge, CRDT semantics,
│   │                               config system, and CLI command map
│   └── muse-e2e-demo.md          — step-by-step lifecycle: init → commit → branch
│                                   → merge conflict → resolve → tag
│
├── guide/
│   ├── plugin-authoring-guide.md — complete walkthrough for writing a new domain
│   │                               plugin, from core protocol through OT merge
│   │                               and CRDT convergent merge
│   └── crdt-reference.md         — CRDT primer: lattice laws, all six primitives
│                                   (VectorClock, LWWRegister, ORSet, RGA, AWMap,
│                                   GCounter), composition patterns, when to use CRDTs
│
├── protocol/
│   ├── muse-protocol.md          — language-agnostic MuseDomainPlugin spec: six
│   │                               required methods, StructuredMergePlugin and
│   │                               CRDTPlugin optional extensions, invariants
│   ├── muse-domain-concepts.md   — universal vocabulary: what "state", "delta",
│   │                               "dimension", "drift", and "merge" mean across
│   │                               music, genomics, simulation, and beyond
│   └── muse-variation-spec.md    — variation semantics for the MIDI domain
│
├── reference/
│   ├── auth.md                   — muse auth register/whoami/logout: identity lifecycle,
│   │                               ~/.muse/identity.toml format, env vars, flows
│   ├── hub.md                    — muse hub connect/status/disconnect/ping: hub fabric,
│   │                               hub vs remote distinction, HTTPS enforcement
│   ├── remotes.md                — muse push/fetch/clone/pull/remote: transport arch,
│   │                               PackBundle wire format, tracking branches
│   ├── security.md               — security architecture: validation trust model,
│   │                               path containment, ANSI injection, XML safety,
│   │                               transport hardening, identity store guarantees
│   ├── cli-tiers.md              — three-tier CLI architecture: Tier 1 plumbing
│   │                               (JSON, pipeable), Tier 2 porcelain (core VCS),
│   │                               Tier 3 semantic (midi/code/coord namespaces)
│   ├── midi-domain.md            — MIDI domain complete reference: all 31 semantic
│   │                               porcelain commands, flags, JSON schemas, types
│   ├── code-domain.md            — Code domain complete reference: all semantic
│   │                               porcelain commands, symbol identity model, types
│   ├── type-contracts.md         — single source of truth for every named type:
│   │                               TypedDicts, dataclasses, Protocols, Enums,
│   │                               and TypeAliases with Mermaid diagrams
│   ├── muse-attributes.md        — .museattributes TOML format reference:
│   │                               [meta] domain, [[rules]] syntax, all five
│   │                               strategies, multi-domain usage, examples
│   ├── museignore.md             — .museignore format: glob patterns, negation,
│   │                               dotfile exclusion rules
│   ├── reflog.md                 — muse reflog: HEAD/branch movement history,
│   │                               undo safety net, per-ref journals
│   ├── gc.md                     — muse gc: reachability walk, dry-run, stats,
│   │                               when and why to run garbage collection
│   ├── archive.md                — muse archive: tar.gz/zip export, --prefix,
│   │                               --ref, distribution without history
│   ├── bisect.md                 — muse bisect: binary regression search,
│   │                               start/bad/good/skip/run/log/reset, agent-safe
│   ├── blame.md                  — muse blame: line-level text attribution,
│   │                               porcelain JSON output, attribution algorithm
│   ├── worktree.md               — muse worktree: parallel branch checkouts,
│   │                               shared object store, agent-per-branch pattern
│   └── workspace.md              — muse workspace: multi-repo composition,
│                                   manifest, sync, coordinator/worker patterns
│
└── demo/
    ├── midi-demo.md              — MIDI domain demo walkthrough: all 31 semantic
    │                               porcelain commands with CLI output examples
    ├── demo-code.md              — Code domain demo walkthrough
    └── demo-script.md            — narration script for the video demo

Architecture at a Glance

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.

┌─────────────────────────────────────────────┐
│                  muse CLI                   │
│  Tier 1: plumbing  ·  Tier 2: porcelain    │
│  Tier 3: midi / code / coord domains        │
└──────────────────────┬──────────────────────┘
                       │
┌──────────────────────▼──────────────────────┐
│              Muse Core Engine               │
│  DAG · object store · branching · merging   │
│  content-addressed blobs · lineage walking  │
└──────┬────────────────────────────┬─────────┘
       │                            │
┌──────▼──────┐              ┌──────▼──────┐
│MuseDomainPlugin│          │MuseDomainPlugin│
│   (music)    │            │  (your domain) │
│  6 methods   │            │   6 methods    │
└──────────────┘            └───────────────┘

The six required methods:

Method	What it does
`snapshot()`	Capture live state → content-addressed dict
`diff()`	Compute typed delta between two snapshots
`merge()`	Three-way reconciliation against a common ancestor
`drift()`	Compare committed state against live working tree
`apply()`	Apply a delta to reconstruct historical state
`schema()`	Declare data structure → drives diff algorithm selection

Two optional protocol extensions enable richer merge semantics:

Extension	Adds	Effect
`StructuredMergePlugin`	`merge_ops()`	Operation-level OT merge — minimal real conflicts
`CRDTPlugin`	`join()` + 3 helpers	Convergent merge — `join` always succeeds, no conflict state

Adding a New Domain

Copy muse/plugins/scaffold/ → muse/plugins/<your_domain>/
Rename ScaffoldPlugin → <YourDomain>Plugin
Replace every raise NotImplementedError(...) with real implementation
Register in muse/plugins/registry.py
Run muse init --domain <your_domain> in a project directory

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 for the full walkthrough.

Config Files Generated by `muse init`

File	Location	Purpose
`repo.json`	`.muse/repo.json`	Immutable identity: repo UUID, schema version, domain
`config.toml`	`.muse/config.toml`	Mutable: `[user]`, `[auth]`, `[remotes]`, `[domain]`
`HEAD`	`.muse/HEAD`	Current branch ref
`.museattributes`	repo root	TOML merge strategy overrides (`[[rules]]`)
`.museignore`	repo root	Glob patterns to exclude from snapshots

Testing Standards

Every public function has a unit test. Integration tests wire real components. E2E tests invoke the CLI via typer.testing.CliRunner.

# Run all tests
pytest tests/ -v

# Type-check
mypy muse/

# Zero-Any audit
python tools/typing_audit.py --dirs muse/ tests/ --max-any 0

All three gates must be green before any proposal merges.

File History 3 commits

sha256:660fcac1df3ab28f61862e961890bd2ca8b754fa0242079d93ca1e25037ec8a6 chore(tests): add docstring to tests/__init__.py so rc14 tr… Human 26 days ago

sha256:d8316ffae901be06347e16ab55be11868eb519dd16ade3e8aa16a99e662f7e62 baseline: rc14 re-baseline after rc3 store corruption recovery Human patch 26 days ago

sha256:1c4b3e3a9a1f300774c3ee662b572a698d5fd405bf765a71e6011a2e9c3eaaaa feat: Muse — version control for the agent era Human 100 days ago