muse-domain-concepts.md
markdown
| 1 | # Muse Domain Concepts & Terminology |
| 2 | |
| 3 | > Muse is domain-agnostic at the core. This document clarifies which terms |
| 4 | > are universal VCS primitives, which are cross-domain patterns, and which |
| 5 | > belong only to the MIDI plugin. |
| 6 | |
| 7 | --- |
| 8 | |
| 9 | ## Universal Terms (all domains, all plugins) |
| 10 | |
| 11 | These terms are part of the core Muse engine. Their definitions contain no |
| 12 | domain-specific meaning. |
| 13 | |
| 14 | | Term | Definition | |
| 15 | |---|---| |
| 16 | | **Commit** | A named snapshot in the DAG, with one or more parent commits | |
| 17 | | **Snapshot** | A serializable, content-addressed capture of current state | |
| 18 | | **Branch** | A named, divergent line of intent forked from a shared ancestor | |
| 19 | | **Merge** | Three-way reconciliation of two divergent state lines against a common base | |
| 20 | | **Merge base** | The lowest common ancestor commit of two branches | |
| 21 | | **Conflict** | A path that was modified on both sides of a merge without consensus | |
| 22 | | **Drift** | The delta between the last committed snapshot and the current live state | |
| 23 | | **Checkout** | Deterministic reconstruction of any historical state from the DAG | |
| 24 | | **Lineage** | The causal chain of commits from root to any HEAD | |
| 25 | | **Revert** | A new commit whose snapshot is identical to a prior commit's parent | |
| 26 | | **Cherry-pick** | Applying one commit's delta on top of a different HEAD | |
| 27 | | **Tag** | A named, human-readable reference attached to a specific commit | |
| 28 | | **Stash** | A temporary shelving of uncommitted live-state changes | |
| 29 | | **Reset** | Moving a branch pointer backward (soft: pointer only; hard: also restores working state) | |
| 30 | | **Delta** | The minimal set of additions, removals, and modifications between two snapshots | |
| 31 | | **Object** | A content-addressed binary blob, identified by its SHA-256 digest | |
| 32 | | **Working tree** | The live, uncommitted state the user is currently editing | |
| 33 | |
| 34 | --- |
| 35 | |
| 36 | ## The Term "Variation" |
| 37 | |
| 38 | **"Variation" is currently a midi-domain concept.** It is not part of the core |
| 39 | Muse engine in v0.1.1. This section explains its current meaning and how it might |
| 40 | generalize. |
| 41 | |
| 42 | ### Current meaning (MIDI domain) |
| 43 | |
| 44 | In the MIDI plugin context — specifically the Stori DAW integration — |
| 45 | a *Variation* is a **proposed change set awaiting human review** before being |
| 46 | committed. The lifecycle is: |
| 47 | |
| 48 | ``` |
| 49 | Propose → Stream → Review → Accept (commit) | Discard |
| 50 | ``` |
| 51 | |
| 52 | A Variation maps onto standard VCS concepts as: |
| 53 | |
| 54 | | Music (Stori) | Standard VCS | |
| 55 | |---|---| |
| 56 | | Variation | A staged diff | |
| 57 | | Phrase | A hunk (contiguous group of changes) | |
| 58 | | Accept Variation | `muse commit` | |
| 59 | | Discard Variation | Discard working-tree changes | |
| 60 | | Undo Variation | `muse revert` | |
| 61 | |
| 62 | The key distinction: a Variation is *auditioned before commit* — the human |
| 63 | listens to the proposed change before deciding to accept it. This is a |
| 64 | domain-specific UX pattern layered on top of VCS primitives, not a VCS |
| 65 | primitive itself. |
| 66 | |
| 67 | ### Does it generalize? |
| 68 | |
| 69 | The *propose → review → commit or discard* pattern is not music-specific. It |
| 70 | appears in many domains: |
| 71 | |
| 72 | | Domain | Equivalent of a Variation | |
| 73 | |---|---| |
| 74 | | Music | A proposed MIDI change set, auditioned before commit | |
| 75 | | Genomics | A proposed edit sequence, reviewed before applying to the canonical genome | |
| 76 | | Climate simulation | A proposed parameter change, evaluated against a baseline run | |
| 77 | | 3D spatial design | A proposed layout modification, previewed in the viewport | |
| 78 | | Code review | A pull request diff, reviewed before merging | |
| 79 | |
| 80 | The common pattern: **a domain-aware proposal that can be previewed in the |
| 81 | domain's native modality before being committed to the DAG.** |
| 82 | |
| 83 | Muse could adopt "Variation" as a first-class VCS primitive — a content- |
| 84 | addressed, reviewable proposal that lives between `snapshot()` and `commit()`. |
| 85 | This is reserved for a future version. For now, the concept belongs to each |
| 86 | domain's plugin and UX layer. |
| 87 | |
| 88 | --- |
| 89 | |
| 90 | ## Cross-Domain Term Mapping |
| 91 | |
| 92 | When building a new domain plugin, these midi-domain terms have natural |
| 93 | analogues: |
| 94 | |
| 95 | | Music term | Generic concept | Example (Genomics) | Example (Climate) | |
| 96 | |---|---|---|---| |
| 97 | | **Track** | A named dimension or channel of state | Gene sequence | Model parameter set | |
| 98 | | **Region** | A bounded segment within a track | CRISPR edit window | Grid cell range | |
| 99 | | **Phrase** | A grouped set of changes within a region | Edit block | Parameter sweep | |
| 100 | | **Section** | A high-level structural division | Chromosome arm | Simulation epoch | |
| 101 | | **Emotion** | A semantic label on a commit | Functional annotation | Confidence tier | |
| 102 | | **Tempo** | A rate or throughput metadata field | Replication rate | Timestep | |
| 103 | | **Key** | A tonal or structural anchor | Reference genome | Baseline run | |
| 104 | |
| 105 | These are metadata conventions for `commit --<field> <value>` and |
| 106 | `log --<field> <value>`. The core engine stores them in `CommitRecord.metadata` |
| 107 | as `dict[str, str]` — no music-specific meaning is enforced. |
| 108 | |
| 109 | --- |
| 110 | |
| 111 | ## What Is and Is Not Music-Specific |
| 112 | |
| 113 | ### MIDI-specific (stay in MIDI plugin only) |
| 114 | |
| 115 | - MIDI, notes, velocities, controller events (CC), pitch bends, aftertouch |
| 116 | - DAW (Digital Audio Workstation) integration |
| 117 | - Beat-based time (all time in the MIDI plugin is measured in beats, not seconds) |
| 118 | - Groove analysis, swing, harmonic analysis, chord maps |
| 119 | - The `muse groove-check`, `muse emotion-diff`, `muse harmony`, `muse dynamics` |
| 120 | commands |
| 121 | - `.museattributes` merge strategies keyed on track names and musical dimensions |
| 122 | (pitch_bend, notes, notes, track_structure, cc_volume) — though the file format |
| 123 | itself could generalize to any domain |
| 124 | |
| 125 | ### Potentially cross-domain (implemented for music, could generalize) |
| 126 | |
| 127 | - **Variation** — the propose-review-commit pattern (see above) |
| 128 | - **Section / Track / Region / Phrase** — structural metadata concepts |
| 129 | - **Emotion / Tempo / Key** — semantic commit labels (already stored generically |
| 130 | in `metadata`) |
| 131 | - **`.museattributes`** — per-path merge strategy overrides (format is generic; |
| 132 | content is currently music-specific) |
| 133 | |
| 134 | ### Definitely universal (core engine, all domains) |
| 135 | |
| 136 | Everything in the [Universal Terms](#universal-terms-all-domains-all-plugins) |
| 137 | table above. |
| 138 | |
| 139 | --- |
| 140 | |
| 141 | ## Guidance for New Domain Authors |
| 142 | |
| 143 | When documenting a new domain plugin, use the universal terms from this document |
| 144 | for shared concepts, and define your own domain vocabulary for concepts that have |
| 145 | no clean analogue. |
| 146 | |
| 147 | A good domain glossary entry answers: |
| 148 | 1. What is this concept in the domain's own language? |
| 149 | 2. Which Muse primitive does it map to? |
| 150 | 3. Is it a snapshot dimension, a metadata field, or a behavioral policy? |
| 151 | |
| 152 | For example, a genomics plugin might define: |
| 153 | |
| 154 | > **Edit Session** — analogous to a Muse *branch*. An edit session is a divergent |
| 155 | > line of CRISPR interventions forked from a reference genome commit. An edit |
| 156 | > session is committed when the intervention set is finalized for review. |
| 157 | |
| 158 | That glossary entry is domain-owned, not part of Muse core. The Muse core |
| 159 | only cares that it is a branch. |