gabriel / musehub public
docs_muse_vision.html html
411 lines 21.1 KB
Raw
sha256:9f5112c9a633a22e53a831c6d3af637093d0ceb914393749905187046f1c548a chore: renumber phases — merge is 05, shift harmony through… Sonnet 4.6 patch 7 days ago
1 {% extends "musehub/base.html" %}
2
3 {% block container_extra_class %} page-container{% endblock %}
4 {% block title %}Vision — Muse Developer Docs{% endblock %}
5 {% block page_json %}{"page":"docs-vision"}{% endblock %}
6
7 {% block content %}
8 <div class="devdocs">
9 <div class="devdocs-layout">
10
11 {# ── Sidebar nav ─────────────────────────────────────────────────────────── #}
12 <aside class="devdocs-sidebar">
13 <nav class="devdocs-nav" aria-label="Docs navigation">
14 <div class="devdocs-nav-group">
15 <div class="devdocs-nav-group-label">Sections</div>
16 {% for slug, num, title, desc in phases %}
17 <a class="devdocs-nav-link devdocs-nav-link--phase{% if slug == current %} devdocs-nav-link--active{% endif %}"
18 href="/muse/{{ slug }}">{{ num }} {{ title }}</a>
19 {% endfor %}
20 </div>
21
22 <div class="devdocs-nav-group">
23 <div class="devdocs-nav-group-label">On this page</div>
24 <a class="devdocs-nav-link devdocs-nav-link--sub" href="#why">Why Muse</a>
25 <a class="devdocs-nav-link devdocs-nav-link--sub" href="#binary-problem">The binary diff problem</a>
26 <a class="devdocs-nav-link devdocs-nav-link--sub" href="#auto-merge">Independent dimensions</a>
27 <a class="devdocs-nav-link devdocs-nav-link--sub" href="#midi-dims">MIDI: 21 dimensions</a>
28 <a class="devdocs-nav-link devdocs-nav-link--sub" href="#domain-agnostic">Domain agnosticism</a>
29 <a class="devdocs-nav-link devdocs-nav-link--sub" href="#ai-agents">AI agents</a>
30 <a class="devdocs-nav-link devdocs-nav-link--sub" href="#domains-live">Domains</a>
31 </div>
32 </nav>
33 </aside>
34
35 {# ── Content ─────────────────────────────────────────────────────────────── #}
36 <article class="devdocs-content">
37
38 <div class="devdocs-breadcrumb">
39 <a href="/muse">Developer Docs</a>
40 <span>›</span>
41 <span>Vision</span>
42 </div>
43
44 <div class="devdocs-phase-header">
45 <span class="devdocs-phase-num">PHASE 13</span>
46 <h1 class="devdocs-phase-title">Vision</h1>
47 <p class="devdocs-phase-desc">
48 Why Muse exists, what makes it fundamentally different from file-level
49 version control, and why semantic diffing is the only model that scales
50 to the AI-agent era.
51 </p>
52 </div>
53
54 {# ── Why Muse ─────────────────────────────────────────────────────────── #}
55 <section class="devdocs-section" id="why">
56 <h2 class="devdocs-section-title"><a href="#why">Why Muse</a></h2>
57
58 <div class="vision-pull">
59 <p class="vision-pull-quote">
60 <em>Git versions files.</em> Muse versions meaning.
61 </p>
62 <p class="vision-pull-sub">
63 The unit of history is not a byte sequence — it is a <em>thing</em> with
64 structure, semantics, and independently meaningful dimensions.
65 </p>
66 </div>
67
68 <p>
69 Every version control system before Muse treats repositories as bags of
70 files and changes as line-level byte diffs. That model works well for
71 source code where the file is the natural unit of meaning. It breaks
72 immediately the moment your data has richer structure: a MIDI arrangement
73 with 21 independent musical dimensions, a genome with overlapping
74 annotations, a 3D scene with material and mesh data on the same asset.
75 </p>
76
77 <p>
78 Muse asks a different question: <strong>what is the smallest independently
79 meaningful unit in this domain?</strong> For MIDI it is an individual note
80 event attribute. For code it is a symbol. For genomics it will be a
81 base-pair annotation. The answer determines the diff algebra, the merge
82 strategy, and the conflict surface — and Muse's domain plugin protocol
83 makes all three programmable in six methods.
84 </p>
85 </section>
86
87 {# ── Binary diff problem ──────────────────────────────────────────────── #}
88 <section class="devdocs-section" id="binary-problem">
89 <h2 class="devdocs-section-title"><a href="#binary-problem">The binary diff problem</a></h2>
90
91 <p>
92 Here is the same change — a velocity adjustment on three notes — as
93 seen by Git and by Muse:
94 </p>
95
96 <div class="vision-compare">
97 <div class="vision-compare-pane">
98 <div class="vision-compare-header">
99 <span class="vision-compare-label">Git</span>
100 <span class="vision-compare-badge vision-compare-badge--bad">binary</span>
101 </div>
102 <div class="vision-compare-body">
103 <span class="tok-del">Binary files before.mid and after.mid differ</span>
104 </div>
105 </div>
106 <div class="vision-compare-pane vision-compare-pane--muse">
107 <div class="vision-compare-header">
108 <span class="vision-compare-label">Muse</span>
109 <span class="vision-compare-badge vision-compare-badge--good">semantic</span>
110 </div>
111 <div class="vision-compare-body">
112 <span class="tok-dim">bar 2 beat 1.00</span>
113 <span class="tok-sym"> C4 </span><span class="tok-field">vel</span><span class="tok-arrow">=</span><span class="tok-del">80</span><span class="tok-arrow">→</span><span class="tok-add">100</span>
114 <span class="tok-dim">bar 2 beat 2.00</span>
115 <span class="tok-sym"> C4 </span><span class="tok-field">vel</span><span class="tok-arrow">=</span><span class="tok-del">64</span><span class="tok-arrow">→</span><span class="tok-add">80</span>
116 <span class="tok-dim">bar 2 beat 3.00</span>
117 <span class="tok-sym"> D4 </span><span class="tok-field">vel</span><span class="tok-arrow">=</span><span class="tok-del">72</span><span class="tok-arrow">→</span><span class="tok-add">90</span>
118 </div>
119 </div>
120 </div>
121
122 <p>
123 Git cannot tell you what changed inside a MIDI file. It hands you two
124 opaque blobs and says they differ. Muse knows that three notes in bar 2
125 had their velocity increased. It knows which notes, which attributes, and
126 by how much. It can display that diff to a human, replay it for conflict
127 resolution, and apply it surgically to a merge.
128 </p>
129
130 <p>
131 The same principle holds for any structured domain. A genome annotation
132 update is not "the file changed" — it is a specific base-pair range with
133 a specific annotation delta. A 3D scene change is not "the asset changed"
134 — it is a material property on a specific mesh node. Muse gives every
135 domain the language to say exactly what changed.
136 </p>
137 </section>
138
139 {# ── Independent dimensions ───────────────────────────────────────────── #}
140 <section class="devdocs-section" id="auto-merge">
141 <h2 class="devdocs-section-title"><a href="#auto-merge">Independent dimensions auto-merge</a></h2>
142
143 <p>
144 When two changes touch independent dimensions of the same object, there
145 is no conflict. Muse detects this and merges automatically — no human
146 intervention required.
147 </p>
148
149 <div class="vision-merge">
150 <div class="vision-merge-header">Live collaboration scenario — same bar, independent dimensions</div>
151 <div class="vision-merge-agents">
152 <div class="vision-merge-agent">
153 <div class="vision-merge-agent-name vision-merge-agent-name--alice">Alice</div>
154 <div class="vision-merge-agent-change">
155 <span class="tok-dim">bar 2</span>
156 <span class="tok-field">cc_sustain</span><span class="tok-arrow"> = </span><span class="tok-val">0 → 127</span>
157 <span class="tok-dim">at beat 1.00</span>
158 </div>
159 <div class="vision-merge-agent-label">Adding a sustain pedal down event</div>
160 </div>
161 <div class="vision-merge-agent">
162 <div class="vision-merge-agent-name vision-merge-agent-name--bob">Bob</div>
163 <div class="vision-merge-agent-change">
164 <span class="tok-dim">bar 2</span>
165 <span class="tok-field">C4.velocity</span><span class="tok-arrow"> = </span><span class="tok-val">80 → 100</span>
166 <span class="tok-dim">at beat 1.00</span>
167 </div>
168 <div class="vision-merge-agent-label">Increasing note velocity</div>
169 </div>
170 </div>
171 <div class="vision-merge-result">
172 <div class="vision-merge-result-icon">✓</div>
173 <span class="vision-merge-result-text">Auto-merged — cc_sustain (Alice) + C4.velocity (Bob)</span>
174 <span class="vision-merge-result-sub">zero conflicts · zero human input</span>
175 </div>
176 </div>
177
178 <p>
179 Alice modifies <code>cc_sustain</code> — MIDI continuous controller 64.
180 Bob modifies <code>C4.velocity</code> — the attack velocity of a note.
181 These are two different rows in the MIDI event model. They are
182 structurally independent. Muse merges them without any conflict, just as
183 two developers editing different functions in the same file merge cleanly
184 in Git.
185 </p>
186
187 <p>
188 The difference: Git's independence is at the <em>line</em> level.
189 Muse's independence is at the <em>semantic dimension</em> level — which
190 is what actually matters for the domain.
191 </p>
192 </section>
193
194 {# ── MIDI dimensions ──────────────────────────────────────────────────── #}
195 <section class="devdocs-section" id="midi-dims">
196 <h2 class="devdocs-section-title"><a href="#midi-dims">MIDI: 21 dimensions, 18 independent</a></h2>
197
198 <div class="vision-dims">
199 <div class="vision-dims-stat">
200 <span class="vision-dims-num">21</span>
201 <span class="vision-dims-label">total dims</span>
202 </div>
203 <div class="vision-dims-divider"></div>
204 <div class="vision-dims-stat">
205 <span class="vision-dims-num">18</span>
206 <span class="vision-dims-label">independent</span>
207 </div>
208 <div class="vision-dims-divider"></div>
209 <div class="vision-dims-grid">
210 <span class="vision-dim-tag vision-dim-tag--independent">pitch</span>
211 <span class="vision-dim-tag vision-dim-tag--independent">velocity</span>
212 <span class="vision-dim-tag vision-dim-tag vision-dim-tag--independent">duration</span>
213 <span class="vision-dim-tag vision-dim-tag--independent">channel</span>
214 <span class="vision-dim-tag vision-dim-tag--independent">tempo</span>
215 <span class="vision-dim-tag vision-dim-tag--independent">time-sig</span>
216 <span class="vision-dim-tag vision-dim-tag--independent">key-sig</span>
217 <span class="vision-dim-tag vision-dim-tag--independent">cc-sustain</span>
218 <span class="vision-dim-tag vision-dim-tag--independent">cc-mod</span>
219 <span class="vision-dim-tag vision-dim-tag--independent">cc-pan</span>
220 <span class="vision-dim-tag vision-dim-tag--independent">cc-volume</span>
221 <span class="vision-dim-tag vision-dim-tag--independent">pitch-bend</span>
222 <span class="vision-dim-tag vision-dim-tag--independent">program</span>
223 <span class="vision-dim-tag vision-dim-tag--independent">aftertouch</span>
224 <span class="vision-dim-tag vision-dim-tag--independent">poly-aftertouch</span>
225 <span class="vision-dim-tag vision-dim-tag--independent">sysex</span>
226 <span class="vision-dim-tag vision-dim-tag--independent">track-name</span>
227 <span class="vision-dim-tag vision-dim-tag--independent">lyrics</span>
228 <span class="vision-dim-tag">position</span>
229 <span class="vision-dim-tag">bar-ref</span>
230 <span class="vision-dim-tag">beat-ref</span>
231 </div>
232 </div>
233
234 <p>
235 A MIDI file is not a blob. It is a composition of 21 named dimensions.
236 18 of them are completely independent — changes on separate dimensions
237 never conflict. Only the 3 positional dimensions (onset position, bar
238 reference, beat reference) interact, because two events at the same
239 position on the same pitch create genuine ambiguity.
240 </p>
241
242 <p>
243 This is the mathematics of music: the sustain pedal and the note velocity
244 are as independent as two different variables in a program. They happen
245 to be encoded in the same binary file, but that encoding is an
246 implementation detail. Muse works on the semantics, not the encoding.
247 </p>
248 </section>
249
250 {# ── Domain agnosticism ───────────────────────────────────────────────── #}
251 <section class="devdocs-section" id="domain-agnostic">
252 <h2 class="devdocs-section-title"><a href="#domain-agnostic">Domain agnosticism</a></h2>
253
254 <p>
255 The domain plugin protocol is six methods. Implement them for any state
256 space and you get content-addressed history, branching, three-way merge,
257 time-travel, typed diffs, and semantic conflict resolution — for free.
258 </p>
259
260 <div class="devdocs-code-block">
261 <div class="devdocs-code-header">
262 <span class="devdocs-code-lang">Python</span>
263 <span class="devdocs-code-label">Domain plugin interface — six methods</span>
264 </div>
265 <pre><span class="tok-kw">class</span> <span class="tok-type">MuseDomainPlugin</span>:
266 <span class="tok-kw">def</span> <span class="tok-fn">snapshot</span>(self, live_state: <span class="tok-type">LiveState</span>) <span class="tok-kw">-></span> <span class="tok-type">StateSnapshot</span>: <span class="tok-cmt">...</span>
267 <span class="tok-kw">def</span> <span class="tok-fn">diff</span>(self, base: <span class="tok-type">StateSnapshot</span>, target: <span class="tok-type">StateSnapshot</span>) <span class="tok-kw">-></span> <span class="tok-type">StateDelta</span>: <span class="tok-cmt">...</span>
268 <span class="tok-kw">def</span> <span class="tok-fn">merge</span>(self, base: <span class="tok-type">StateSnapshot</span>, left: <span class="tok-type">StateSnapshot</span>, right: <span class="tok-type">StateSnapshot</span>) <span class="tok-kw">-></span> <span class="tok-type">MergeResult</span>: <span class="tok-cmt">...</span>
269 <span class="tok-kw">def</span> <span class="tok-fn">drift</span>(self, committed: <span class="tok-type">StateSnapshot</span>, live: <span class="tok-type">LiveState</span>) <span class="tok-kw">-></span> <span class="tok-type">DriftReport</span>: <span class="tok-cmt">...</span>
270 <span class="tok-kw">def</span> <span class="tok-fn">apply</span>(self, delta: <span class="tok-type">StateDelta</span>, live_state: <span class="tok-type">LiveState</span>) <span class="tok-kw">-></span> <span class="tok-type">LiveState</span>: <span class="tok-cmt">...</span>
271 <span class="tok-kw">def</span> <span class="tok-fn">schema</span>(self) <span class="tok-kw">-></span> <span class="tok-type">DomainSchema</span>: <span class="tok-cmt">...</span></pre>
272 </div>
273
274 <p>
275 The object store, snapshot model, commit DAG, branch refs, push/fetch
276 wire protocol, and all of Harmony's conflict resolution machinery are
277 completely domain-agnostic. They operate on
278 <code>sha256:&lt;id&gt;</code> blobs and typed delta lists. The domain
279 plugin tells Muse what the blobs mean.
280 </p>
281
282 <div class="devdocs-callout">
283 <svg class="devdocs-callout-icon" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5">
284 <circle cx="8" cy="8" r="6.5"/>
285 <path d="M8 5v4M8 11v.5"/>
286 </svg>
287 At the storage layer, a MIDI file and a Python file are identical — both
288 are bytes with a path. Domain semantics live in the content, not the
289 storage model. Muse is multi-domain but the object store, snapshot, and
290 commit model are identical for all domains.
291 </div>
292 </section>
293
294 {# ── AI agents ────────────────────────────────────────────────────────── #}
295 <section class="devdocs-section" id="ai-agents">
296 <h2 class="devdocs-section-title"><a href="#ai-agents">AI agents need this</a></h2>
297
298 <p>
299 Git was designed for human developers committing once or twice a day.
300 AI agents commit hundreds of times per session. They branch, merge, and
301 resolve conflicts in automated pipelines with no human in the loop.
302 </p>
303
304 <p>
305 At that scale, binary diffing breaks down entirely. When ten agents are
306 editing the same module simultaneously, "these two byte sequences differ"
307 is not a conflict resolution strategy — it is a deadlock. You need a
308 system that understands what changed, at what granularity, and why two
309 concurrent changes are or are not compatible.
310 </p>
311
312 <p>
313 Muse was built for exactly this model. Every commit carries cryptographic
314 agent provenance (<code>--agent-id</code>, <code>--model-id</code>,
315 <code>--sign</code>). The coordination system (<a href="/muse/coordination">Phase 06</a>)
316 provides work queues, reservations, and conflict forecasting. Harmony
317 (<a href="/muse/harmony">Phase 05</a>) learns from every resolved conflict
318 and auto-replays known resolutions. The MCP server
319 (<a href="/muse/mcp">Phase 07</a>) exposes all of this to any agent that
320 speaks Model Context Protocol.
321 </p>
322
323 <p>
324 The result: agents can commit at machine speed with full semantic
325 awareness of what they are changing, what might conflict, and how prior
326 conflicts were resolved — without human intervention on the happy path.
327 </p>
328 </section>
329
330 {# ── Domains ──────────────────────────────────────────────────────────── #}
331 <section class="devdocs-section" id="domains-live">
332 <h2 class="devdocs-section-title"><a href="#domains-live">Domains</a></h2>
333
334 <p>
335 Any state space with a programmable diff algebra becomes a first-class
336 Muse domain. Two are live today; more are on the roadmap.
337 </p>
338
339 <div class="vision-domain-grid">
340 <div class="vision-domain-card vision-domain-card--live">
341 <div class="vision-domain-card-status">Live</div>
342 <div class="vision-domain-card-name">Source Code</div>
343 <div class="vision-domain-card-desc">
344 Symbol-level diffs, AST-aware merge, blast-radius analysis,
345 dead-code detection, semantic coverage.
346 </div>
347 </div>
348
349 <div class="vision-domain-card vision-domain-card--live">
350 <div class="vision-domain-card-status">Live</div>
351 <div class="vision-domain-card-name">MIDI / Audio</div>
352 <div class="vision-domain-card-desc">
353 21-dimension event model, independent-dimension merge,
354 quantize, humanize, invert, retrograde, SysEx.
355 </div>
356 </div>
357
358 <div class="vision-domain-card vision-domain-card--soon">
359 <div class="vision-domain-card-status">Planned</div>
360 <div class="vision-domain-card-name">Genomics</div>
361 <div class="vision-domain-card-desc">
362 Base-pair addressed annotations, VCF/GFF diff algebra,
363 clinical-grade conflict escalation.
364 </div>
365 </div>
366
367 <div class="vision-domain-card vision-domain-card--soon">
368 <div class="vision-domain-card-status">Planned</div>
369 <div class="vision-domain-card-name">3D Design</div>
370 <div class="vision-domain-card-desc">
371 Node-addressed scene graph, mesh + material independence,
372 glTF/USD diff algebra.
373 </div>
374 </div>
375
376 <div class="vision-domain-card vision-domain-card--soon">
377 <div class="vision-domain-card-status">Planned</div>
378 <div class="vision-domain-card-name">Scientific Simulation</div>
379 <div class="vision-domain-card-desc">
380 Parameter-addressed config, reproducible run snapshots,
381 result provenance chains.
382 </div>
383 </div>
384
385 <div class="vision-domain-card vision-domain-card--soon">
386 <div class="vision-domain-card-status">Open</div>
387 <div class="vision-domain-card-name">Your Domain</div>
388 <div class="vision-domain-card-desc">
389 Six methods. Any state space.
390 See <a href="/muse/domains">Phase 03 — Domain Protocol</a>.
391 </div>
392 </div>
393 </div>
394 </section>
395
396 {# ── Phase nav ────────────────────────────────────────────────────────── #}
397 <nav class="devdocs-phase-nav" aria-label="Phase navigation">
398 <a class="devdocs-phase-nav-btn" href="/muse/mists">
399 <svg width="14" height="14" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="2"><path d="M10 12L6 8l4-4"/></svg>
400 12 — Mist Domain
401 </a>
402 <a class="devdocs-phase-nav-btn devdocs-phase-nav-btn--next" href="/muse/crdt">
403 14 — CRDT Primitives
404 <svg width="14" height="14" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="2"><path d="M6 12l4-4-4-4"/></svg>
405 </a>
406 </nav>
407
408 </article>
409 </div>
410 </div>
411 {% endblock %}
File History 1 commit
sha256:9f5112c9a633a22e53a831c6d3af637093d0ceb914393749905187046f1c548a chore: renumber phases — merge is 05, shift harmony through… Sonnet 4.6 patch 7 days ago