Muse Domain Concepts & Terminology
Muse is domain-agnostic at the core. This document clarifies which terms are universal VCS primitives, which are cross-domain patterns, and which belong only to the MIDI plugin.
Universal Terms (all domains, all plugins)
These terms are part of the core Muse engine. Their definitions contain no domain-specific meaning.
| Term | Definition |
|---|---|
| Commit | A named snapshot in the DAG, with one or more parent commits |
| Snapshot | A serializable, content-addressed capture of current state |
| Branch | A named, divergent line of intent forked from a shared ancestor |
| Merge | Three-way reconciliation of two divergent state lines against a common base |
| Merge base | The lowest common ancestor commit of two branches |
| Conflict | A path that was modified on both sides of a merge without consensus |
| Drift | The delta between the last committed snapshot and the current live state |
| Checkout | Deterministic reconstruction of any historical state from the DAG |
| Lineage | The causal chain of commits from root to any HEAD |
| Revert | A new commit whose snapshot is identical to a prior commit's parent |
| Cherry-pick | Applying one commit's delta on top of a different HEAD |
| Tag | A named, human-readable reference attached to a specific commit |
| Stash | A temporary shelving of uncommitted live-state changes |
| Reset | Moving a branch pointer backward (soft: pointer only; hard: also restores working state) |
| Delta | The minimal set of additions, removals, and modifications between two snapshots |
| Object | A content-addressed binary blob, identified by its SHA-256 digest |
| Working tree | The live, uncommitted state the user is currently editing |
The Term "Variation"
"Variation" is currently a midi-domain concept. It is not part of the core Muse engine in v0.1.2. This section explains its current meaning and how it might generalize.
Current meaning (MIDI domain)
In the MIDI plugin context — specifically the Stori DAW integration — a Variation is a proposed change set awaiting human review before being committed. The lifecycle is:
Propose → Stream → Review → Accept (commit) | Discard
A Variation maps onto standard VCS concepts as:
| Music (Stori) | Standard VCS |
|---|---|
| Variation | A staged diff |
| Phrase | A hunk (contiguous group of changes) |
| Accept Variation | muse commit |
| Discard Variation | Discard working-tree changes |
| Undo Variation | muse revert |
The key distinction: a Variation is auditioned before commit — the human listens to the proposed change before deciding to accept it. This is a domain-specific UX pattern layered on top of VCS primitives, not a VCS primitive itself.
Does it generalize?
The propose → review → commit or discard pattern is not music-specific. It appears in many domains:
| Domain | Equivalent of a Variation |
|---|---|
| Music | A proposed MIDI change set, auditioned before commit |
| Genomics | A proposed edit sequence, reviewed before applying to the canonical genome |
| Climate simulation | A proposed parameter change, evaluated against a baseline run |
| 3D spatial design | A proposed layout modification, previewed in the viewport |
| Code review | A proposal diff, reviewed before merging |
The common pattern: a domain-aware proposal that can be previewed in the domain's native modality before being committed to the DAG.
Muse could adopt "Variation" as a first-class VCS primitive — a content-
addressed, reviewable proposal that lives between snapshot() and commit().
This is reserved for a future version. For now, the concept belongs to each
domain's plugin and UX layer.
Cross-Domain Term Mapping
When building a new domain plugin, these midi-domain terms have natural analogues:
| Music term | Generic concept | Example (Genomics) | Example (Climate) |
|---|---|---|---|
| Track | A named dimension or channel of state | Gene sequence | Model parameter set |
| Region | A bounded segment within a track | CRISPR edit window | Grid cell range |
| Phrase | A grouped set of changes within a region | Edit block | Parameter sweep |
| Section | A high-level structural division | Chromosome arm | Simulation epoch |
| Emotion | A semantic label on a commit | Functional annotation | Confidence tier |
| Tempo | A rate or throughput metadata field | Replication rate | Timestep |
| Key | A tonal or structural anchor | Reference genome | Baseline run |
These are metadata conventions for commit --<field> <value> and
log --<field> <value>. The core engine stores them in CommitRecord.metadata
as dict[str, str] — no music-specific meaning is enforced.
What Is and Is Not Music-Specific
MIDI-specific (stay in MIDI plugin only)
- MIDI, notes, velocities, controller events (CC), pitch bends, aftertouch
- DAW (Digital Audio Workstation) integration
- Beat-based time (all time in the MIDI plugin is measured in beats, not seconds)
- Groove analysis, swing, harmonic analysis, chord maps
- The
muse midi groove-check,muse midi emotion-diff,muse midi harmony,muse dynamicscommands .museattributesmerge strategies keyed on track names and musical dimensions (pitch_bend, notes, notes, track_structure, cc_volume) — though the file format itself could generalize to any domain
Potentially cross-domain (implemented for music, could generalize)
- Variation — the propose-review-commit pattern (see above)
- Section / Track / Region / Phrase — structural metadata concepts
- Emotion / Tempo / Key — semantic commit labels (already stored generically
in
metadata) .museattributes— per-path merge strategy overrides (format is generic; content is currently music-specific)
Definitely universal (core engine, all domains)
Everything in the Universal Terms table above.
Guidance for New Domain Authors
When documenting a new domain plugin, use the universal terms from this document for shared concepts, and define your own domain vocabulary for concepts that have no clean analogue.
A good domain glossary entry answers:
- What is this concept in the domain's own language?
- Which Muse primitive does it map to?
- Is it a snapshot dimension, a metadata field, or a behavioral policy?
For example, a genomics plugin might define:
Edit Session — analogous to a Muse branch. An edit session is a divergent line of CRISPR interventions forked from a reference genome commit. An edit session is committed when the intervention set is finalized for review.
That glossary entry is domain-owned, not part of Muse core. The Muse core only cares that it is a branch.