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

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

594

595

```mermaid

596

classDiagram

597

class SnapshotManifest {

598

<<TypedDict>>

599

+files : dict~str, str~

600

+domain : str

601

}

602

class DeltaManifest {

<<TypedDict>>

+domain : str

+added : list~str~

+removed : list~str~

+modified : list~str~

}

class MergeResult {

<<dataclass>>

+merged : StateSnapshot

612

+conflicts : list~str~

+is_clean : bool

}

class DriftReport {

<<dataclass>>

+has_drift : bool

+summary : str

+delta : StateDelta

}

class MuseDomainPlugin {

622

<<Protocol runtime_checkable>>

623

+snapshot(live_state: LiveState) StateSnapshot

624

+diff(base, target: StateSnapshot) StateDelta

625

+merge(base, left, right: StateSnapshot) MergeResult

626

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

627

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

628

}

629

class MusicPlugin {

630

<<reference implementation>>

631

+snapshot(live_state) StateSnapshot

632

+diff(base, target) StateDelta

633

+merge(base, left, right) MergeResult

634

+drift(committed, live) DriftReport

635

+apply(delta, live_state) LiveState

636

}

637

638

MuseDomainPlugin ..> SnapshotManifest : StateSnapshot alias

639

MuseDomainPlugin ..> DeltaManifest : StateDelta alias

640

MuseDomainPlugin --> MergeResult : merge() returns

641

MuseDomainPlugin --> DriftReport : drift() returns

642

MusicPlugin ..|> MuseDomainPlugin : implements

643

MergeResult --> SnapshotManifest : merged

644

DriftReport --> DeltaManifest : delta

```

---

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

650

651

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

652

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

653

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

667

+parent2_commit_id : str | None

668

+author : str

669

+metadata : dict~str, str~

670

}

671

class SnapshotDict {

672

<<TypedDict wire format>>

673

+snapshot_id : str

674

+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 {

686

<<TypedDict total=False>>

+commit_id : str

+repo_id : str

+branch : str

+snapshot_id : str

+message : str

+committed_at : str

+parent_commit_id : str | None

694

+parent2_commit_id : str | None

695

+author : str

696

+metadata : dict~str, str~

697

+manifest : dict~str, str~

}

class CommitRecord {

<<dataclass>>

+commit_id : str

+repo_id : str

+branch : str

+snapshot_id : str

+message : str

+committed_at : datetime

707

+parent_commit_id : str | None

708

+parent2_commit_id : str | None

709

+author : str

710

+metadata : dict~str, str~

711

+to_dict() CommitDict

712

+from_dict(d: CommitDict) CommitRecord

713

}

714

class SnapshotRecord {

715

<<dataclass>>

716

+snapshot_id : str

717

+manifest : dict~str, str~

718

+created_at : datetime

719

+to_dict() SnapshotDict

720

+from_dict(d: SnapshotDict) SnapshotRecord

}

class TagRecord {

<<dataclass>>

+tag_id : str

+repo_id : str

+commit_id : str

+tag : str

+created_at : datetime

729

+to_dict() TagDict

730

+from_dict(d: TagDict) TagRecord

731

}

732

733

CommitRecord ..> CommitDict : to_dict produces

734

CommitDict ..> CommitRecord : from_dict produces

735

SnapshotRecord ..> SnapshotDict : to_dict produces

736

SnapshotDict ..> SnapshotRecord : from_dict produces

737

TagRecord ..> TagDict : to_dict produces

738

TagDict ..> TagRecord : from_dict produces

739

RemoteCommitPayload ..> CommitDict : store_pulled_commit builds

740

CommitRecord --> SnapshotRecord : snapshot_id reference

741

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

```

---

### Diagram 3 — Merge Engine State

747

748

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

749

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

750

loaded, immutable in-memory form.

```mermaid

classDiagram

class MergeStatePayload {

755

<<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~

765

+base_commit : str | None

766

+ours_commit : str | None

767

+theirs_commit : str | None

768

+other_branch : str | None

}

class CommitRecord {

<<dataclass>>

+commit_id : str

+branch : str

+parent_commit_id : str | None

775

}

776

777

MergeStatePayload ..> MergeState : read_merge_state() produces

778

MergeState ..> MergeStatePayload : write_merge_state() serialises

779

MergeState --> CommitRecord : base_commit, ours_commit, theirs_commit

```

---

### Diagram 4 — Configuration Type Hierarchy

785

786

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

787

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

788

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

```mermaid

classDiagram

class MuseConfig {

<<TypedDict total=False>>

794

+auth : AuthEntry

795

+remotes : dict~str, RemoteEntry~

796

}

797

class AuthEntry {

798

<<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

813

MuseConfig *-- RemoteEntry : remotes (by name)

814

RemoteEntry ..> RemoteConfig : list_remotes() projects to

```

---

### Diagram 5 — MIDI / MusicXML Import Types

820

821

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

822

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

849

+tempo_bpm : float

850

+notes : list~NoteEvent~

+tracks : list~str~

+raw_meta : RawMeta

}

class RawMeta {

<<TypeAlias>>

MidiMeta | MusicXMLMeta

857

}

858

859

MuseImportData *-- NoteEvent : notes

860

MuseImportData --> RawMeta : raw_meta

861

RawMeta ..> MidiMeta : MIDI files

862

RawMeta ..> MusicXMLMeta : MusicXML files

```

---

### Diagram 6 — Error Hierarchy

868

869

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

870

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

884

}

885

class RepoNotFoundError {

886

<<MuseCLIError>>

887

default exit_code = REPO_NOT_FOUND

888

default message = Not a Muse repository

889

}

890

891

MuseCLIError --> ExitCode : exit_code

892

RepoNotFoundError --|> MuseCLIError

```

---

### Diagram 7 — Stash Stack

898

899

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

900

`.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 {

912

<<dataclass>>

913

+snapshot_id : str

914

+manifest : dict~str, str~

915

}

916

917

StashEntry ..> SnapshotRecord : snapshot_id + manifest mirror

```

---

### Diagram 8 — Full Entity Overview

923

924

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

925

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

```mermaid

classDiagram

class MuseDomainPlugin {

930

<<Protocol>>

931

snapshot / diff / merge / drift / apply

932

}

933

class SnapshotManifest {

934

<<TypedDict>>

935

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

936

}

937

class DeltaManifest {

938

<<TypedDict>>

939

domain · added · removed · modified

}

class MergeResult {

<<dataclass>>

merged: StateSnapshot · conflicts: list~str~

}

class DriftReport {

<<dataclass>>

has_drift · summary · delta

}

class CommitRecord {

<<dataclass>>

commit_id · branch · snapshot_id · metadata

952

}

953

class SnapshotRecord {

954

<<dataclass>>

955

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

972

}

973

class RemoteCommitPayload {

974

<<TypedDict total=False>>

975

wire format + manifest

}

class MergeState {

<<dataclass frozen>>

conflict_paths · base/ours/theirs commits

980

}

981

class MergeStatePayload {

982

<<TypedDict total=False>>

983

MERGE_STATE.json shape

984

}

985

class MuseConfig {

986

<<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

1004

}

1005

class MuseImportData {

1006

<<dataclass>>

1007

notes · tracks · raw_meta

}

class NoteEvent {

<<dataclass>>

pitch · velocity · timing · channel

}

class MidiMeta {

<<TypedDict>>

num_tracks: int

}

class MusicXMLMeta {

<<TypedDict>>

num_parts · part_names

}

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

1034

MuseDomainPlugin ..> DeltaManifest : StateDelta

1035

MuseDomainPlugin --> MergeResult : merge() returns

1036

MuseDomainPlugin --> DriftReport : drift() returns

1037

MergeResult --> SnapshotManifest : merged

1038

DriftReport --> DeltaManifest : delta

1039

1040

CommitRecord ..> CommitDict : to_dict / from_dict

1041

SnapshotRecord ..> SnapshotDict : to_dict / from_dict

1042

TagRecord ..> TagDict : to_dict / from_dict

1043

RemoteCommitPayload ..> CommitDict : store_pulled_commit

1044

CommitRecord --> SnapshotRecord : snapshot_id

1045

MergeState ..> MergeStatePayload : serialise / deserialise

1046

1047

MuseConfig *-- AuthEntry : auth

1048

MuseConfig *-- RemoteEntry : remotes

1049

RemoteEntry ..> RemoteConfig : list_remotes()

1050

1051

StashEntry ..> SnapshotRecord : snapshot_id

1052

MuseImportData *-- NoteEvent : notes

1053

MuseImportData --> MidiMeta : raw_meta (MIDI)

1054

MuseImportData --> MusicXMLMeta : raw_meta (XML)

1055

1056

RepoNotFoundError --|> MuseCLIError

1057

MuseCLIError --> ExitCode : exit_code

1058

```