docs/reference/type-contracts.md · cgcardona/muse

| `dimension_reports` | `dict[str, dict[str, str]]` | `{}` | Path → per-dimension winner map; only populated for MIDI files that went through dimension-level merge (e.g. `{"keys/piano.mid": {"notes": "left", "harmonic": "right"}}`) |

180

181

**Property:**

182

183

| Name | Returns | Description |

184

|------|---------|-------------|

185

| `is_clean` | `bool` | `True` when `conflicts` is empty |

#### `DriftReport`

`@dataclass` — Gap between committed state and current live state. Produced by

190

`MuseDomainPlugin.drift()` and consumed by `muse status`.

191

192

193

|-------|------|---------|-------------|

194

195

| `summary` | `str` | `""` | Human-readable description (e.g. `"2 added, 1 modified"`) |

196

197

198

### MuseDomainPlugin Protocol

199

200

`@runtime_checkable Protocol` — The six interfaces a domain plugin must

201

implement. Runtime-checkable so that `assert isinstance(plugin, MuseDomainPlugin)`

202

works as a module-load sanity check.

203

204

| Method | Signature | Description |

205

|--------|-----------|-------------|

206

| `snapshot` | `(live_state: LiveState) -> StateSnapshot` | Capture current state as a content-addressed dict; must honour `.museignore` |

207

208

| `merge` | `(base, left, right: StateSnapshot, *, repo_root: pathlib.Path \| None = None) -> MergeResult` | Three-way merge; when `repo_root` is provided, load `.museattributes` and perform dimension-level merge for supported formats |

209

| `drift` | `(committed: StateSnapshot, live: LiveState) -> DriftReport` | Compare committed state vs current live state |

210

| `apply` | `(delta: StateDelta, live_state: LiveState) -> LiveState` | Apply a delta to produce a new live state |

211

| `schema` | `() -> DomainSchema` | Declare the structural shape of the domain's data (drives diff algorithm selection) |

212

213

The music plugin (`muse.plugins.music.plugin`) is the reference implementation.

214

Every other domain — scientific simulation, genomics, 3D spatial design,

215

spacetime — implements these six methods and registers itself as a plugin.

216

217

### Optional Protocol Extensions

218

219

#### `StructuredMergePlugin`

220

221

`@runtime_checkable Protocol` — Extends `MuseDomainPlugin` with operation-level

222

OT merge. When both branches produce `StructuredDelta`s, the merge engine detects

223

`isinstance(plugin, StructuredMergePlugin)` and calls `merge_ops()` instead of

224

`merge()`.

225

226

| Method | Signature | Description |

227

|--------|-----------|-------------|

228

| `merge_ops` | `(base, ours_snap, theirs_snap, ours_ops, theirs_ops, *, repo_root) -> MergeResult` | Operation-level three-way merge using OT commutativity rules |

#### `CRDTPlugin`

`@runtime_checkable Protocol` — Extends `MuseDomainPlugin` with convergent merge.

233

`join` always succeeds — no conflict state ever exists.

234

235

| Method | Signature | Description |

236

|--------|-----------|-------------|

237

| `join` | `(a: CRDTSnapshotManifest, b: CRDTSnapshotManifest) -> CRDTSnapshotManifest` | Convergent join satisfying commutativity, associativity, idempotency |

238

| `crdt_schema` | `() -> list[CRDTDimensionSpec]` | Per-dimension CRDT primitive specification |

239

| `to_crdt_state` | `(snapshot: StateSnapshot) -> CRDTSnapshotManifest` | Convert a snapshot into CRDT state |

240

| `from_crdt_state` | `(crdt: CRDTSnapshotManifest) -> StateSnapshot` | Convert CRDT state back to a plain snapshot |

### CRDT Types

#### `CRDTSnapshotManifest`

245

246

`TypedDict` — Extended snapshot format for CRDT-mode plugins. Wraps the plain

247

snapshot manifest with a vector clock and serialised CRDT state.

248

249

| Field | Type | Description |

250

|-------|------|-------------|

251

| `schema_version` | `int` | Always `1` |

252

| `domain` | `str` | Plugin domain name |

253

| `files` | `dict[str, str]` | POSIX path → SHA-256 object digest (same as `SnapshotManifest`) |

254

| `vclock` | `dict[str, int]` | Vector clock: agent ID → logical clock value |

255

| `crdt_state` | `dict[str, str]` | Dimension name → serialised CRDT primitive state (JSON-encoded) |

256

257

#### `CRDTDimensionSpec`

258

259

`TypedDict` — Declares which CRDT primitive a dimension uses.

260

261

| Field | Type | Description |

262

|-------|------|-------------|

263

| `name` | `str` | Dimension name (must match a `DimensionSpec.name` in the plugin's `DomainSchema`) |

264

| `crdt_type` | `str` | One of: `"lww_register"`, `"or_set"`, `"rga"`, `"aw_map"`, `"g_counter"`, `"vector_clock"` |

---

## Domain Schema Types

269

270

**Path:** `muse/core/schema.py`

271

272

The `DomainSchema` family of TypedDicts allow a plugin to declare its data

273

structure. The core engine uses this to select diff algorithms per-dimension

274

and to drive informed conflict reporting during OT merge.

#### `ElementSchema`

`TypedDict` — The schema for a single element kind (a top-level data entity).

279

280

| Field | Type | Description |

281

|-------|------|-------------|

282

| `name` | `str` | Element kind name (e.g. `"note"`, `"track"`, `"gene_edit"`) |

283

| `kind` | `str` | Container kind: `"sequence"`, `"set"`, `"map"`, or `"scalar"` |

#### `DimensionSpec`

`TypedDict` — Schema for a single orthogonal dimension within the domain.

288

289

| Field | Type | Description |

290

|-------|------|-------------|

291

| `name` | `str` | Dimension name (e.g. `"melodic"`, `"harmonic"`) |

292

| `description` | `str` | Human-readable description for this dimension |

293

| `diff_algorithm` | `str` | Algorithm to use: `"myers_lcs"`, `"tree_edit"`, `"numerical"`, or `"set_ops"` |

294

295

#### `CRDTDimensionSpec`

296

297

`TypedDict` — Schema for a dimension using CRDT convergent merge semantics.

298

See [CRDT Types](#crdt-types) above for the `crdt_type` values.

#### `MapSchema`

`TypedDict` — Schema for a map-kind element's value type.

303

304

| Field | Type | Description |

305

|-------|------|-------------|

306

| `value_schema` | `ElementSchema` | Schema of the map's values |

#### `DomainSchema`

`TypedDict` — The top-level schema declaration returned by `MuseDomainPlugin.schema()`.

311

312

| Field | Type | Description |

313

|-------|------|-------------|

314

| `domain` | `str` | Plugin domain name |

315

| `schema_version` | `int` | Always `1` |

316

| `description` | `str` | Human-readable domain description |

317

| `merge_mode` | `str` | `"three_way"` (OT merge) or `"crdt"` (convergent join) |

318

| `elements` | `list[ElementSchema]` | Top-level element kind declarations |

---

## OT Merge Types

**Path:** `muse/core/op_transform.py`

326

327

Operational Transformation types for the `StructuredMergePlugin` extension.

328

329

#### `MergeOpsResult`

330

331

`@dataclass` — Result of `merge_op_lists()`. Carries auto-merged ops and any

332

unresolvable conflicts as pairs.

333

334

| Field | Type | Description |

335

|-------|------|-------------|

336

| `merged_ops` | `list[DomainOp]` | Operations that were auto-merged (commuting ops from both branches) |

337

| `conflict_ops` | `list[tuple[DomainOp, DomainOp]]` | Pairs of non-commuting operations: `(our_op, their_op)` |

338

339

**Lattice contract:** `merged_ops` contains every auto-merged op exactly once;

340

`conflict_ops` contains every unresolvable pair exactly once.

---

## Store Types

**Path:** `muse/core/store.py`

347

348

All commit and snapshot metadata is stored as JSON files under `.muse/`.

349

Wire-format `TypedDict`s are the JSON-serialisable shapes used in `to_dict()`

350

and `from_dict()`. In-memory `dataclass`es are the rich representations used

351

in business logic throughout the CLI commands.

352

353

### Wire-Format TypedDicts

354

355

These types appear at the boundary between Python objects and JSON on disk.

356

`json.loads()` returns an untyped result; `from_dict()` methods consume it and

357

return typed dataclasses. `to_dict()` methods produce these TypedDicts for

`json.dumps()`.

#### `CommitDict`

`TypedDict` — JSON-serialisable representation of a commit record. All datetime

363

values are ISO-8601 strings; callers convert to `datetime` inside `from_dict()`.

364

365

| Field | Type | Description |

366

|-------|------|-------------|

367

| `commit_id` | `str` | SHA-256 hex digest of the commit's canonical inputs |

368

| `repo_id` | `str` | UUID identifying the repository |

369

| `branch` | `str` | Branch name at time of commit |

370

| `snapshot_id` | `str` | SHA-256 hex digest of the attached snapshot |

371

| `message` | `str` | Commit message |

372

| `committed_at` | `str` | ISO-8601 UTC timestamp |

373

374

375

| `author` | `str` | Author name string |

376

| `metadata` | `dict[str, str]` | Extensible string→string metadata bag |

#### `SnapshotDict`

`TypedDict` — JSON-serialisable representation of a snapshot record.

381

382

| Field | Type | Description |

383

|-------|------|-------------|

384

| `snapshot_id` | `str` | SHA-256 hex digest of the manifest |

385

| `manifest` | `dict[str, str]` | POSIX path → SHA-256 object digest |

386

| `created_at` | `str` | ISO-8601 UTC timestamp |

#### `TagDict`

`TypedDict` — JSON-serialisable representation of a semantic tag.

391

392

| Field | Type | Description |

393

|-------|------|-------------|

394

| `tag_id` | `str` | UUID identifying the tag |

395

| `repo_id` | `str` | UUID identifying the repository |

396

| `commit_id` | `str` | SHA-256 commit ID this tag points to |

397

| `tag` | `str` | Tag name string (e.g. `"v1.0"`) |

398

| `created_at` | `str` | ISO-8601 UTC timestamp |

399

400

#### `RemoteCommitPayload`

401

402

`TypedDict (total=False)` — Wire format received from a remote during push/pull.

403

All fields are optional because the remote payload may omit fields unknown to

404

older protocol versions. Callers validate required fields before constructing

405

a `CommitRecord`.

406

407

| Field | Type | Description |

408

|-------|------|-------------|

409

| `commit_id` | `str` | Commit identifier |

410

| `repo_id` | `str` | Repository UUID |

411

| `branch` | `str` | Branch name |

412

| `snapshot_id` | `str` | Snapshot identifier |

413

| `message` | `str` | Commit message |

414

| `committed_at` | `str` | ISO-8601 timestamp |

415

416

417

| `author` | `str` | Author name |

418

| `metadata` | `dict[str, str]` | Metadata bag |

419

| `manifest` | `dict[str, str]` | Inline snapshot manifest (remote optimisation) |

420

421

### In-Memory Dataclasses

422

423

These rich types are constructed from wire-format TypedDicts after loading from

424

disk. They carry typed `datetime` values and are used throughout CLI command

implementations.

#### `CommitRecord`

`@dataclass` — In-memory representation of a commit.

430

431

432

|-------|------|---------|-------------|

| `author` | `str` | `""` | Author name |

442

| `metadata` | `dict[str, str]` | `{}` | Extensible string→string metadata |

**Methods:**

| Method | Returns | Description |

447

|--------|---------|-------------|

448

| `to_dict()` | `CommitDict` | Serialise to JSON-ready TypedDict |

449

| `from_dict(d: CommitDict)` | `CommitRecord` | Deserialise from JSON-loaded TypedDict |

450

451

#### `SnapshotRecord`

452

453

`@dataclass` — In-memory representation of a content-addressed snapshot.

454

455

456

|-------|------|---------|-------------|

**Methods:** `to_dict() -> SnapshotDict`, `from_dict(d: SnapshotDict) -> SnapshotRecord`

#### `TagRecord`

`@dataclass` — In-memory representation of a semantic tag.

466

467

468

|-------|------|---------|-------------|

| `tag` | `str` | required | Tag name |

473

474

475

**Methods:** `to_dict() -> TagDict`, `from_dict(d: TagDict) -> TagRecord`

---

## Merge Engine Types

480

481

**Path:** `muse/core/merge_engine.py`

482

483

#### `MergeStatePayload`

484

485

`TypedDict (total=False)` — JSON-serialisable form of an in-progress merge

486

state. Written to `.muse/MERGE_STATE.json` when a merge has unresolved

487

conflicts. All fields are optional in the TypedDict because `other_branch` is

488

only set when the merge has a named second branch.

489

490

| Field | Type | Description |

491

|-------|------|-------------|

492

| `base_commit` | `str` | Common ancestor commit ID |

493

| `ours_commit` | `str` | Current branch HEAD at merge start |

494

| `theirs_commit` | `str` | Incoming branch HEAD at merge start |

495

| `conflict_paths` | `list[str]` | POSIX paths with unresolved conflicts |

496

| `other_branch` | `str` | Name of the branch being merged in (optional) |

#### `MergeState`

`@dataclass (frozen=True)` — Loaded in-memory representation of

501

`MERGE_STATE.json`. Immutable so it can be passed around without accidental

mutation.

|-------|------|---------|-------------|

---

## Attributes Types

**Path:** `muse/core/attributes.py`

517

518

Parse and resolve `.museattributes` TOML merge-strategy rules. The parser

519

produces a typed `AttributeRule` list; `resolve_strategy` does first-match

520

lookup with `fnmatch` path patterns and dimension name matching.

521

522

#### `VALID_STRATEGIES`

523

524

`frozenset[str]` — The set of legal strategy strings:

525

`{"ours", "theirs", "union", "auto", "manual"}`.

526

527

#### `AttributesMeta`

528

529

`TypedDict (total=False)` — The `[meta]` section of `.museattributes`.

530

531

| Field | Type | Description |

532

|-------|------|-------------|

533

| `domain` | `str` | Domain name this file targets (optional — validated against `.muse/repo.json` when present) |

534

535

#### `AttributesRuleDict`

536

537

`TypedDict` — A single `[[rules]]` entry as parsed from TOML.

538

539

| Field | Type | Description |

540

|-------|------|-------------|

541

| `path` | `str` | `fnmatch` glob matched against workspace-relative POSIX paths |

542

| `dimension` | `str` | Domain axis name (e.g. `"melodic"`) or `"*"` to match all |

543

| `strategy` | `str` | One of the `VALID_STRATEGIES` strings |

544

545

#### `MuseAttributesFile`

546

547

`TypedDict (total=False)` — The complete `MuseAttributesFile` structure after TOML parsing.

548

549

| Field | Type | Description |

550

|-------|------|-------------|

551

| `meta` | `AttributesMeta` | Optional `[meta]` section |

552

| `rules` | `list[AttributesRuleDict]` | Ordered `[[rules]]` array |

#### `AttributeRule`

`@dataclass (frozen=True)` — A single resolved rule from `.museattributes`.

557

558

| Field | Type | Description |

559

|-------|------|-------------|

560

| `path_pattern` | `str` | `fnmatch` glob matched against workspace-relative POSIX paths |

561

| `dimension` | `str` | Domain axis name (e.g. `"melodic"`, `"harmonic"`) or `"*"` to match all |

562

| `strategy` | `str` | One of the `VALID_STRATEGIES` strings |

563

| `source_index` | `int` | 0-based index of the rule in the `[[rules]]` array; defaults to `0` |

564

565

**Public functions:**

566

567

- `load_attributes(root: pathlib.Path, *, domain: str | None = None) -> list[AttributeRule]` —

568

reads `.museattributes` TOML, validates domain if provided, returns rules in

569

file order; raises `ValueError` for parse errors, missing fields, or invalid strategy.

570

- `read_attributes_meta(root: pathlib.Path) -> AttributesMeta` —

571

returns the `[meta]` section only; returns `{}` if file is absent or unparseable.

572

- `resolve_strategy(rules: list[AttributeRule], path: str, dimension: str = "*") -> str` —

573

first-match lookup; returns `"auto"` when no rule matches.

---

## MIDI Dimension Merge Types

578

579

**Path:** `muse/plugins/music/midi_merge.py`

580

581

The multidimensional merge engine for the music domain. MIDI events are

582

bucketed into four orthogonal dimension slices; each slice has a content hash

583

for fast change detection. A three-way merge resolves each dimension

584

independently using `.museattributes` strategies, then reconstructs a valid

585

MIDI file from the winning slices.

#### Constants

| Name | Type | Value / Description |

590

|------|------|---------------------|

591

| `INTERNAL_DIMS` | `list[str]` | `["notes", "harmonic", "dynamic", "structural"]` — the four internal dimension bucket names |

592

| `DIM_ALIAS` | `dict[str, str]` | Maps user-facing names to internal buckets: `"melodic" → "notes"`, `"rhythmic" → "notes"`, `"harmonic" → "harmonic"`, `"dynamic" → "dynamic"`, `"structural" → "structural"` |

#### `_MsgVal`

`TypeAlias = int | str | list[int]` — The set of value types that can appear

597

in the serialised form of a MIDI message field. Used by `_msg_to_dict` to

598

avoid `dict[str, object]`.

599

600

#### `DimensionSlice`

601

602

`@dataclass` — All MIDI events belonging to one dimension of a parsed file.

603

604

605

|-------|------|---------|-------------|

606

607

608

| `content_hash` | `str` | `""` | SHA-256 digest of the canonical JSON serialisation; computed in `__post_init__` when not provided |

609

610

#### `MidiDimensions`

611

612

`@dataclass` — All four dimension slices extracted from one MIDI file, plus

613

file-level metadata.

614

615

| Field | Type | Description |

616

|-------|------|-------------|

617

| `ticks_per_beat` | `int` | MIDI timing resolution (pulses per quarter note) from the source file |

618

| `file_type` | `int` | MIDI file type (0 = single-track, 1 = multi-track synchronous) |

619

| `slices` | `dict[str, DimensionSlice]` | Internal dimension name → slice |

**Method:**

| Name | Signature | Description |

624

|------|-----------|-------------|

625

| `get` | `(user_dim: str) -> DimensionSlice` | Resolve a user-facing alias (`"melodic"`, `"rhythmic"`) or internal name to the correct slice |

626

627

**Public functions:**

628

629

| Function | Signature | Description |

630

|----------|-----------|-------------|

631

| `extract_dimensions` | `(midi_bytes: bytes) -> MidiDimensions` | Parse MIDI bytes and bucket events by dimension |

632

| `dimension_conflict_detail` | `(base, left, right: MidiDimensions) -> dict[str, str]` | Per-dimension change report: `"unchanged"`, `"left_only"`, `"right_only"`, or `"both"` |

633

| `merge_midi_dimensions` | `(base_bytes, left_bytes, right_bytes: bytes, attrs_rules: list[AttributeRule], path: str) -> tuple[bytes, dict[str, str]] \| None` | Three-way dimension merge; returns `(merged_bytes, dimension_report)` or `None` on unresolvable conflict |

---

## Configuration Types

638

639

**Path:** `muse/cli/config.py`

640

641

The structured view of `.muse/config.toml`. Loading from TOML uses `isinstance`

642

narrowing from `tomllib`'s untyped output — no `Any` annotation is ever written

643

in source. All mutation functions read the current config, modify the specific

644

section, and write back.

#### `AuthEntry`

`TypedDict (total=False)` — `[auth]` section in `.muse/config.toml`.

649

650

| Field | Type | Description |

651

|-------|------|-------------|

652

| `token` | `str` | Bearer token for Muse Hub authentication. **Never logged.** |

#### `RemoteEntry`

`TypedDict (total=False)` — `[remotes.<name>]` section in `.muse/config.toml`.

657

658

| Field | Type | Description |

659

|-------|------|-------------|

660

| `url` | `str` | Remote Hub URL (e.g. `"https://hub.example.com/repos/my-repo"`) |

661

| `branch` | `str` | Upstream branch tracked by this remote (set by `--set-upstream`) |

#### `MuseConfig`

`TypedDict (total=False)` — Structured view of the entire `.muse/config.toml`

666

file. All sections are optional; an empty dict is a valid `MuseConfig`.

667

668

| Field | Type | Description |

669

|-------|------|-------------|

670

| `auth` | `AuthEntry` | Authentication credentials section |

671

| `remotes` | `dict[str, RemoteEntry]` | Named remote sections |

672

| `domain` | `dict[str, str]` | Domain-specific key/value pairs; keys are domain-defined (e.g. `ticks_per_beat` for music, `reference_assembly` for genomics). The core engine ignores this section; only the active plugin reads it. |

#### `RemoteConfig`

`TypedDict` — Public-facing remote descriptor returned by `list_remotes()`.

677

A lightweight projection of `RemoteEntry` that always has both required fields.

678

679

| Field | Type | Description |

680

|-------|------|-------------|

681

| `name` | `str` | Remote name (e.g. `"origin"`) |

682

| `url` | `str` | Remote URL |

---

## MIDI / MusicXML Import Types

687

688

**Path:** `muse/cli/midi_parser.py`

689

690

Types used by `muse import` to parse Standard MIDI Files and MusicXML documents

691

into Muse's internal note representation.

#### `MidiMeta`

`TypedDict` — Format-specific metadata for Standard MIDI Files (`.mid`, `.midi`).

696

697

| Field | Type | Description |

698

|-------|------|-------------|

699

| `num_tracks` | `int` | Number of MIDI tracks in the file |

#### `MusicXMLMeta`

`TypedDict` — Format-specific metadata for MusicXML files (`.xml`, `.musicxml`).

704

705

| Field | Type | Description |

706

|-------|------|-------------|

707

| `num_parts` | `int` | Number of parts (instruments) in the score |

708

| `part_names` | `list[str]` | Display names of each part |

#### `RawMeta`

`TypeAlias = MidiMeta | MusicXMLMeta` — Discriminated union of all

713

format-specific metadata shapes. The `MuseImportData.raw_meta` field carries

714

one of these two named types depending on the source file's format.

#### `NoteEvent`

`@dataclass` — A single sounding note extracted from an imported file.

719

720

| Field | Type | Description |

721

|-------|------|-------------|

722

| `pitch` | `int` | MIDI pitch number (0–127) |

723

| `velocity` | `int` | MIDI velocity (0–127; 0 = note-off) |

724

| `start_tick` | `int` | Onset tick relative to file start |

725

| `duration_ticks` | `int` | Note length in MIDI ticks |

726

| `channel` | `int` | MIDI channel (0–15) |

727

| `channel_name` | `str` | Track/part name for this channel |

728

729

#### `MuseImportData`

730

731

`@dataclass` — All data extracted from a single imported music file. The

732

complete parsed result returned by `parse_file()`.

733

734

| Field | Type | Description |

735

|-------|------|-------------|

736

| `source_path` | `pathlib.Path` | Absolute path to the source file |

737

| `format` | `str` | `"midi"` or `"musicxml"` |

738

| `ticks_per_beat` | `int` | MIDI timing resolution (pulses per quarter note) |

739

| `tempo_bpm` | `float` | Tempo in beats per minute |

740

| `notes` | `list[NoteEvent]` | All sounding notes, in onset order |

741

| `tracks` | `list[str]` | Track/part names present in the file |

742

| `raw_meta` | `RawMeta` | Format-specific metadata (`MidiMeta` or `MusicXMLMeta`) |

---

## Stash Types

**Path:** `muse/cli/commands/stash.py`

#### `StashEntry`

`TypedDict` — A single entry in the stash stack, persisted to

753

`.muse/stash.json` as one element of a JSON array.

754

755

| Field | Type | Description |

756

|-------|------|-------------|

757

| `snapshot_id` | `str` | SHA-256 content digest of the stashed snapshot |

758

| `manifest` | `dict[str, str]` | POSIX path → SHA-256 object digest of stashed files |

759

| `branch` | `str` | Branch name that was active when the stash was saved |

760

| `stashed_at` | `str` | ISO-8601 UTC timestamp of the stash operation |

---

## Error Hierarchy

**Path:** `muse/core/errors.py`

#### `ExitCode`

`IntEnum` — Standardised CLI exit codes. Used throughout the CLI commands via

771

`raise typer.Exit(code=ExitCode.USER_ERROR)`.

772

773

| Value | Integer | Meaning |

774

|-------|---------|---------|

775

| `SUCCESS` | `0` | Command completed successfully |

776

| `USER_ERROR` | `1` | Bad arguments or invalid user input |

777

| `REPO_NOT_FOUND` | `2` | Not inside a Muse repository |

778

| `INTERNAL_ERROR` | `3` | Unexpected internal failure |

#### `MuseCLIError`

`Exception` — Base exception for all Muse CLI errors. Carries an exit code

783

so that top-level handlers can produce the correct process exit.

784

785

| Field | Type | Description |

786

|-------|------|-------------|

787

| `exit_code` | `ExitCode` | Exit code to use when this exception terminates the process |

788

789

#### `RepoNotFoundError`

790

791

`MuseCLIError` — Raised by `find_repo_root()` callers when a command is invoked

792

outside a Muse repository. Default message: `"Not a Muse repository. Run muse init."` Default exit code: `ExitCode.REPO_NOT_FOUND`.

793

794

**Alias:** `MuseNotARepoError = RepoNotFoundError`

---

## Entity Hierarchy

```

Muse VCS

│

├── Domain Protocol (muse/domain.py)

804

│ │

805

│ ├── Snapshot and Delta

806

│ │ ├── SnapshotManifest — TypedDict: {files: dict[str,str], domain: str}

807

│ │ └── DeltaManifest — TypedDict: {domain, added, removed, modified}

808

│ │

809

│ ├── Type Aliases

810

│ │ ├── LiveState — SnapshotManifest | pathlib.Path

811

│ │ ├── StateSnapshot — SnapshotManifest

812

│ │ └── StateDelta — DeltaManifest

813

│ │

814

│ ├── Result Types

815

│ │ ├── MergeResult — dataclass: merged + conflicts + applied_strategies + dimension_reports

816

│ │ └── DriftReport — dataclass: has_drift + summary + delta

817

│ │

818

│ └── MuseDomainPlugin — Protocol (runtime_checkable): 6 methods

819

│ merge() accepts repo_root kwarg for attribute-aware merge

820

│

821

├── Store (muse/core/store.py)

822

│ │

823

│ ├── Wire-Format TypedDicts

824

│ │ ├── CommitDict — TypedDict: all commit fields (str timestamps)

825

│ │ ├── SnapshotDict — TypedDict: snapshot_id + manifest + created_at

826

│ │ ├── TagDict — TypedDict: tag identity fields

827

│ │ └── RemoteCommitPayload — TypedDict (total=False): wire format + manifest

828

│ │

829

│ └── In-Memory Dataclasses

830

│ ├── CommitRecord — dataclass: typed datetime, to_dict/from_dict

831

│ ├── SnapshotRecord — dataclass: manifest + datetime

832

│ └── TagRecord — dataclass: tag metadata + datetime

833

│

834

├── Merge Engine (muse/core/merge_engine.py)

835

│ ├── MergeStatePayload — TypedDict (total=False): MERGE_STATE.json shape

836

│ └── MergeState — dataclass (frozen): loaded in-memory merge state

837

│

838

├── Attributes (muse/core/attributes.py)

839

│ ├── VALID_STRATEGIES — frozenset[str]: {ours, theirs, union, auto, manual}

840

│ ├── AttributesMeta — TypedDict (total=False): [meta] section (domain: str)

841

│ ├── AttributesRuleDict — TypedDict: [[rules]] entry (path, dimension, strategy)

842

│ ├── MuseAttributesFile — TypedDict (total=False): full parsed file structure

843

│ └── AttributeRule — dataclass (frozen): path_pattern + dimension + strategy + source_index

844

│

845

├── MIDI Dimension Merge (muse/plugins/music/midi_merge.py)

846

│ ├── INTERNAL_DIMS — list[str]: [notes, harmonic, dynamic, structural]

847

│ ├── DIM_ALIAS — dict[str, str]: user-facing names → internal buckets

848

│ ├── _MsgVal — TypeAlias: int | str | list[int]

849

│ ├── DimensionSlice — dataclass: name + events list + content_hash

850

│ └── MidiDimensions — dataclass: ticks_per_beat + file_type + slices dict

851

│

852

├── Configuration (muse/cli/config.py)

853

│ ├── AuthEntry — TypedDict (total=False): [auth] section

854

│ ├── RemoteEntry — TypedDict (total=False): [remotes.<name>] section

855

│ ├── MuseConfig — TypedDict (total=False): full config.toml shape (auth + remotes + domain)

856

│ └── RemoteConfig — TypedDict: public remote descriptor

857

│

858

├── MIDI / MusicXML Import (muse/cli/midi_parser.py)

859

│ ├── MidiMeta — TypedDict: num_tracks

860

│ ├── MusicXMLMeta — TypedDict: num_parts + part_names

861

│ ├── RawMeta — TypeAlias: MidiMeta | MusicXMLMeta

862

│ ├── NoteEvent — dataclass: pitch, velocity, timing, channel

863

│ └── MuseImportData — dataclass: full parsed file result

864

│

865

├── Stash (muse/cli/commands/stash.py)

866

│ └── StashEntry — TypedDict: snapshot_id + manifest + branch + stashed_at

867

│

868

└── Errors (muse/core/errors.py)

869

├── ExitCode — IntEnum: SUCCESS=0 USER_ERROR=1 REPO_NOT_FOUND=2 INTERNAL_ERROR=3

870

├── MuseCLIError — Exception base: carries ExitCode

871

├── RepoNotFoundError — MuseCLIError: default exit REPO_NOT_FOUND

872

└── MuseNotARepoError — alias for RepoNotFoundError

```

---

## Entity Graphs (Mermaid)

878

879

Arrow conventions:

880

- `*--` composition (owns, lifecycle-coupled)

881

- `-->` association (references)

882

- `..>` dependency (uses)

883

- `..>` with label: produces / implements

---

### Diagram 1 — Domain Protocol and Plugin Contract

888

889

The `MuseDomainPlugin` protocol and the types that flow through its six methods. `MusicPlugin` is the reference implementation that proves the abstraction.

```mermaid

classDiagram

class SnapshotManifest {

894

<<TypedDict>>

895

+files : dict~str, str~

896

+domain : str

897

}

898

class DeltaManifest {

<<TypedDict>>

+domain : str

+added : list~str~

+removed : list~str~

+modified : list~str~

}

class MergeResult {

<<dataclass>>

+merged : StateSnapshot

908

+conflicts : list~str~

909

+applied_strategies : dict~str, str~

910

+dimension_reports : dict~str, dict~str, str~~

+is_clean : bool

}

class DriftReport {

<<dataclass>>

+has_drift : bool

+summary : str

+delta : StateDelta

}

class MuseDomainPlugin {

920

<<Protocol runtime_checkable>>

921

+snapshot(live_state: LiveState) StateSnapshot

922

+diff(base, target: StateSnapshot) StateDelta

923

+merge(base, left, right, *, repo_root) MergeResult

924

+drift(committed: StateSnapshot, live: LiveState) DriftReport

925

+apply(delta: StateDelta, live_state: LiveState) LiveState

926

}

927

class MusicPlugin {

928

<<reference implementation>>

929

+snapshot(live_state) StateSnapshot

930

+diff(base, target) StateDelta

931

+merge(base, left, right, *, repo_root) MergeResult

932

+drift(committed, live) DriftReport

933

+apply(delta, live_state) LiveState

934

}

935

936

MuseDomainPlugin ..> SnapshotManifest : StateSnapshot alias

937

MuseDomainPlugin ..> DeltaManifest : StateDelta alias

938

MuseDomainPlugin --> MergeResult : merge() returns

939

MuseDomainPlugin --> DriftReport : drift() returns

940

MusicPlugin ..|> MuseDomainPlugin : implements

941

MergeResult --> SnapshotManifest : merged

942

DriftReport --> DeltaManifest : delta

```

---

### Diagram 2 — Store Wire-Format TypedDicts and Dataclasses

948

949

The two-layer design: wire-format TypedDicts for JSON serialisation, rich

950

dataclasses for in-memory logic. Every `from_dict` consumes the TypedDict

951

shape produced by `json.loads()`; every `to_dict` produces it for

`json.dumps()`.

```mermaid

classDiagram

class CommitDict {

<<TypedDict wire format>>

+commit_id : str

+repo_id : str

+branch : str

+snapshot_id : str

+message : str

+committed_at : str

+parent_commit_id : str | None

965

+parent2_commit_id : str | None

966

+author : str

967

+metadata : dict~str, str~

968

}

969

class SnapshotDict {

970

<<TypedDict wire format>>

971

+snapshot_id : str

972

+manifest : dict~str, str~

+created_at : str

}

class TagDict {

<<TypedDict wire format>>

+tag_id : str

+repo_id : str

+commit_id : str

+tag : str

+created_at : str

}

class RemoteCommitPayload {

984

<<TypedDict total=False>>

+commit_id : str

+repo_id : str

+branch : str

+snapshot_id : str

+message : str

+committed_at : str

+parent_commit_id : str | None

992

+parent2_commit_id : str | None

993

+author : str

994

+metadata : dict~str, str~

995

+manifest : dict~str, str~

}

class CommitRecord {

<<dataclass>>

+commit_id : str

+repo_id : str

+branch : str

+snapshot_id : str

+message : str

+committed_at : datetime

1005

+parent_commit_id : str | None

1006

+parent2_commit_id : str | None

1007

+author : str

1008

+metadata : dict~str, str~

1009

+to_dict() CommitDict

1010

+from_dict(d: CommitDict) CommitRecord

1011

}

1012

class SnapshotRecord {

1013

<<dataclass>>

1014

+snapshot_id : str

1015

+manifest : dict~str, str~

1016

+created_at : datetime

1017

+to_dict() SnapshotDict

1018

+from_dict(d: SnapshotDict) SnapshotRecord

}

class TagRecord {

<<dataclass>>

+tag_id : str

+repo_id : str

+commit_id : str

+tag : str

+created_at : datetime

1027

+to_dict() TagDict

1028

+from_dict(d: TagDict) TagRecord

1029

}

1030

1031

CommitRecord ..> CommitDict : to_dict produces

1032

CommitDict ..> CommitRecord : from_dict produces

1033

SnapshotRecord ..> SnapshotDict : to_dict produces

1034

SnapshotDict ..> SnapshotRecord : from_dict produces

1035

TagRecord ..> TagDict : to_dict produces

1036

TagDict ..> TagRecord : from_dict produces

1037

RemoteCommitPayload ..> CommitDict : store_pulled_commit builds

1038

CommitRecord --> SnapshotRecord : snapshot_id reference

1039

CommitRecord --> TagRecord : commit_id reference (via TagRecord)

```

---

### Diagram 3 — Merge Engine State

1045

1046

The in-progress merge state written to disk on conflict and loaded on

1047

continuation. `MergeStatePayload` is the JSON shape; `MergeState` is the

1048

loaded, immutable in-memory form.

```mermaid

classDiagram

class MergeStatePayload {

1053

<<TypedDict total=False>>

+base_commit : str

+ours_commit : str

+theirs_commit : str

+conflict_paths : list~str~

+other_branch : str

}

class MergeState {

<<dataclass frozen>>

+conflict_paths : list~str~

1063

+base_commit : str | None

1064

+ours_commit : str | None

1065

+theirs_commit : str | None

1066

+other_branch : str | None

}

class CommitRecord {

<<dataclass>>

+commit_id : str

+branch : str

+parent_commit_id : str | None

1073

}

1074

1075

MergeStatePayload ..> MergeState : read_merge_state() produces

1076

MergeState ..> MergeStatePayload : write_merge_state() serialises

1077

MergeState --> CommitRecord : base_commit, ours_commit, theirs_commit

```

---

### Diagram 4 — Configuration Type Hierarchy

1083

1084

The structured config.toml types. `MuseConfig` is the root; mutation functions

1085

read, modify a specific section, and write back. `isinstance` narrowing converts

1086

`tomllib`'s untyped output to the typed structure at the load boundary.

```mermaid

classDiagram

class MuseConfig {

<<TypedDict total=False>>

1092

+auth : AuthEntry

1093

+remotes : dict~str, RemoteEntry~

1094

}

1095

class AuthEntry {

1096

<<TypedDict total=False>>

+token : str

}

class RemoteEntry {

<<TypedDict total=False>>

+url : str

+branch : str

}

class RemoteConfig {

<<TypedDict public API>>

+name : str

+url : str

}

MuseConfig *-- AuthEntry : auth

1111

MuseConfig *-- RemoteEntry : remotes (by name)

1112

RemoteEntry ..> RemoteConfig : list_remotes() projects to

```

---

### Diagram 5 — MIDI / MusicXML Import Types

1118

1119

The parser output types for `muse import`. `RawMeta` is a discriminated union

1120

of two named shapes; no dict with mixed value types is exposed.

```mermaid

classDiagram

class MidiMeta {

<<TypedDict>>

+num_tracks : int

}

class MusicXMLMeta {

<<TypedDict>>

+num_parts : int

+part_names : list~str~

}

class NoteEvent {

<<dataclass>>

+pitch : int

+velocity : int

+start_tick : int

+duration_ticks : int

+channel : int

+channel_name : str

}

class MuseImportData {

<<dataclass>>

+source_path : Path

+format : str

+ticks_per_beat : int

1147

+tempo_bpm : float

1148

+notes : list~NoteEvent~

+tracks : list~str~

+raw_meta : RawMeta

}

class RawMeta {

<<TypeAlias>>

MidiMeta | MusicXMLMeta

1155

}

1156

1157

MuseImportData *-- NoteEvent : notes

1158

MuseImportData --> RawMeta : raw_meta

1159

RawMeta ..> MidiMeta : MIDI files

1160

RawMeta ..> MusicXMLMeta : MusicXML files

```

---

### Diagram 6 — Error Hierarchy

1166

1167

Exit codes, base exception, and concrete error types. Every CLI command raises

1168

a typed exception or calls `raise typer.Exit(code=ExitCode.X)`.

```mermaid

classDiagram

class ExitCode {

<<IntEnum>>

SUCCESS = 0

USER_ERROR = 1

REPO_NOT_FOUND = 2

INTERNAL_ERROR = 3

}

class MuseCLIError {

<<Exception>>

+exit_code : ExitCode

1182

}

1183

class RepoNotFoundError {

1184

<<MuseCLIError>>

1185

default exit_code = REPO_NOT_FOUND

1186

default message = Not a Muse repository

1187

}

1188

1189

MuseCLIError --> ExitCode : exit_code

1190

RepoNotFoundError --|> MuseCLIError

```

---

### Diagram 7 — Stash Stack

1196

1197

The stash is a JSON array of `StashEntry` TypedDicts persisted to

1198

`.muse/stash.json`. Push prepends; pop removes index 0.

```mermaid

classDiagram

class StashEntry {

<<TypedDict>>

+snapshot_id : str

+manifest : dict~str, str~

+branch : str

+stashed_at : str

}

class SnapshotRecord {

1210

<<dataclass>>

1211

+snapshot_id : str

1212

+manifest : dict~str, str~

1213

}

1214

1215

StashEntry ..> SnapshotRecord : snapshot_id + manifest mirror

```

---

### Diagram 8 — Full Entity Overview

1221

1222

All named entities grouped by layer, showing the dependency flow from the

1223

domain protocol down through the store, CLI, and plugin layers.

```mermaid

classDiagram

class MuseDomainPlugin {

1228

<<Protocol>>

1229

snapshot / diff / merge / drift / apply / schema

1230

}

1231

class SnapshotManifest {

1232

<<TypedDict>>

1233

files: dict~str,str~ · domain: str

1234

}

1235

class DeltaManifest {

1236

<<TypedDict>>

1237

domain · added · removed · modified

}

class MergeResult {

<<dataclass>>

merged · conflicts · applied_strategies · dimension_reports

}

class DriftReport {

<<dataclass>>

has_drift · summary · delta

}

class CommitRecord {

<<dataclass>>

commit_id · branch · snapshot_id · metadata

1250

}

1251

class SnapshotRecord {

1252

<<dataclass>>

1253

snapshot_id · manifest: dict~str,str~

}

class TagRecord {

<<dataclass>>

tag_id · commit_id · tag

}

class CommitDict {

<<TypedDict wire>>

all str fields · committed_at: str

}

class SnapshotDict {

<<TypedDict wire>>

snapshot_id · manifest · created_at

}

class TagDict {

<<TypedDict wire>>

tag_id · repo_id · commit_id · tag

1270

}

1271

class RemoteCommitPayload {

1272

<<TypedDict total=False>>

1273

wire format + manifest

}

class MergeState {

<<dataclass frozen>>

conflict_paths · base/ours/theirs commits

1278

}

1279

class MergeStatePayload {

1280

<<TypedDict total=False>>

1281

MERGE_STATE.json shape

1282

}

1283

class MuseConfig {

1284

<<TypedDict total=False>>

auth · remotes

}

class AuthEntry {

<<TypedDict total=False>>

token: str

}

class RemoteEntry {

<<TypedDict total=False>>

url · branch

}

class RemoteConfig {

<<TypedDict>>

name · url

}

class StashEntry {

<<TypedDict>>

snapshot_id · manifest · branch · stashed_at

1302

}

1303

class MuseImportData {

1304

<<dataclass>>

1305

notes · tracks · raw_meta

}

class NoteEvent {

<<dataclass>>

pitch · velocity · timing · channel

}

class MidiMeta {

<<TypedDict>>

num_tracks: int

}

class MusicXMLMeta {

<<TypedDict>>

num_parts · part_names

1318

}

1319

class AttributeRule {

1320

<<dataclass frozen>>

1321

path_pattern · dimension · strategy

1322

}

1323

class DimensionSlice {

1324

<<dataclass>>

1325

name · events · content_hash

1326

}

1327

class MidiDimensions {

1328

<<dataclass>>

1329

ticks_per_beat · slices: dict~str, DimensionSlice~

}

class ExitCode {

<<IntEnum>>

SUCCESS=0 · USER_ERROR=1 · REPO_NOT_FOUND=2 · INTERNAL_ERROR=3

}

class MuseCLIError {

<<Exception>>

exit_code: ExitCode

}

class RepoNotFoundError {

<<MuseCLIError>>

}

MuseDomainPlugin ..> SnapshotManifest : StateSnapshot

1344

MuseDomainPlugin ..> DeltaManifest : StateDelta

1345

MuseDomainPlugin --> MergeResult : merge() returns

1346

MuseDomainPlugin --> DriftReport : drift() returns

1347

MergeResult --> SnapshotManifest : merged

1348

DriftReport --> DeltaManifest : delta

1349

1350

CommitRecord ..> CommitDict : to_dict / from_dict

1351

SnapshotRecord ..> SnapshotDict : to_dict / from_dict

1352

TagRecord ..> TagDict : to_dict / from_dict

1353

RemoteCommitPayload ..> CommitDict : store_pulled_commit

1354

CommitRecord --> SnapshotRecord : snapshot_id

1355

MergeState ..> MergeStatePayload : serialise / deserialise

1356

1357

MuseConfig *-- AuthEntry : auth

1358

MuseConfig *-- RemoteEntry : remotes

1359

RemoteEntry ..> RemoteConfig : list_remotes()

1360

1361

StashEntry ..> SnapshotRecord : snapshot_id

1362

MuseImportData *-- NoteEvent : notes

1363

MuseImportData --> MidiMeta : raw_meta (MIDI)

1364

MuseImportData --> MusicXMLMeta : raw_meta (XML)

1365

1366

AttributeRule ..> MergeResult : applied_strategies reflects

1367

MidiDimensions *-- DimensionSlice : slices

1368

MidiDimensions ..> MergeResult : dimension_reports reflects

1369

1370

RepoNotFoundError --|> MuseCLIError

1371

MuseCLIError --> ExitCode : exit_code

```

---

### Diagram 9 — Attributes and MIDI Dimension Merge

1377

1378

The attribute rule pipeline and how it flows into the multidimensional MIDI

1379

merge engine. `AttributeRule` objects are produced by `load_attributes()` and

1380

consumed by both `MusicPlugin.merge()` and `merge_midi_dimensions()`.

1381

`DimensionSlice` is the core bucket type; `MidiDimensions` groups the four

slices for one file.

```mermaid

classDiagram

class AttributeRule {

<<dataclass frozen>>

+path_pattern : str

+dimension : str

+strategy : str

+source_index : int

}

class DimensionSlice {

1394

<<dataclass>>

1395

+name : str

1396

+events : list~tuple~int, Message~~

1397

+content_hash : str

1398

}

1399

class MidiDimensions {

1400

<<dataclass>>

1401

+ticks_per_beat : int

1402

+file_type : int

1403

+slices : dict~str, DimensionSlice~

1404

+get(user_dim: str) DimensionSlice

}

class MergeResult {

<<dataclass>>

+merged : StateSnapshot

1409

+conflicts : list~str~

1410

+applied_strategies : dict~str, str~

1411

+dimension_reports : dict~str, dict~str, str~~

+is_clean : bool

}

class MusicPlugin {

<<MuseDomainPlugin>>

+merge(base, left, right, *, repo_root) MergeResult

1417

}

1418

1419

MusicPlugin ..> AttributeRule : load_attributes()

1420

MusicPlugin ..> MidiDimensions : extract_dimensions()

1421

MusicPlugin --> MergeResult : returns

1422

MergeResult --> AttributeRule : applied_strategies reflects rules used

1423

MidiDimensions *-- DimensionSlice : slices (4 buckets)

1424

AttributeRule ..> DimensionSlice : resolve_strategy selects winner

1425

```