test_vision.py
python
sha256:e1629e5f328982dbf6e535d3f253993c78ff225dfee4ebb0e0a15fc1db69046b
merge: rc25 — docs and docs-contract tests match Muse batch…
Opus 5.5
minor
⚠ breaking
2 days ago
| 1 | """DOC_VIS — /muse/vision contract (musehub#258, QA contract v2). |
| 2 | |
| 3 | Every claim on the page was checked on 2026-11-08 against musehub ``dev`` d6608a13 and muse 0.2.1rc20 in a disposable |
| 4 | sandbox (isolated HOME, no identity, no hub, no remotes; Git only inside throwaway repositories on the #241 B terms). |
| 5 | The MIDI dimension grid (V2) and the list of domains registered by default are computed from the engine code |
| 6 | (``docs_vision_data``); these tests re-derive each from the code the page documents, so a change on either side fails |
| 7 | here. Known product defects stay documented as contract plus warning (#241 defect-preservation rule): each is pinned by |
| 8 | a strict xfail that flips when its ticket is fixed, so the warning on the page must be removed in the same change |
| 9 | (muse#212 and muse#147 were fixed in Muse batch 1; their tests now pin the fixed behaviour). |
| 10 | |
| 11 | DOC_VIS_01 (commands parse), _02 (anchors) and _03 (URL scheme) are the #242 checkers (test_doc_inf_cli.py, |
| 12 | test_doc_inf_registry.py, test_doc_inf_scheme.py). DOC_VIS_04 is ``TestDimensionGrid`` / ``TestDomains``; _05 is |
| 13 | ``TestPhaseLabels``; _06 is ``TestWording``. No database is used. |
| 14 | """ |
| 15 | |
| 16 | from __future__ import annotations |
| 17 | |
| 18 | import html as html_lib |
| 19 | import inspect |
| 20 | import io |
| 21 | import os |
| 22 | import re |
| 23 | import subprocess |
| 24 | import sys |
| 25 | from pathlib import Path |
| 26 | from typing import Any |
| 27 | |
| 28 | import mido |
| 29 | import pytest |
| 30 | from muse.core.object_store import read_object, write_object |
| 31 | from muse.core.types import blob_id |
| 32 | from muse.domain import MuseDomainPlugin |
| 33 | from muse.plugins.midi import midi_merge |
| 34 | from muse.plugins.midi.plugin import MidiPlugin |
| 35 | |
| 36 | from musehub.api.routes.musehub import docs_vision_data as data |
| 37 | from musehub.api.routes.musehub.ui_docs import _PHASES |
| 38 | from tests.docs_contract import cli_check as cc |
| 39 | from tests.docs_contract import registry_check as rc |
| 40 | |
| 41 | pytestmark = pytest.mark.no_db |
| 42 | |
| 43 | PAGE = rc.phase_path("vision") |
| 44 | MUSE_ISSUES = "https://staging.musehub.ai/gabriel/muse/issues/" |
| 45 | HUB_ISSUES = "https://staging.musehub.ai/gabriel/musehub/issues/" |
| 46 | |
| 47 | _H_MIDI_DELTA = "203" # MIDI structured_delta falls back to a file-level ReplaceOp |
| 48 | _C_INDEPENDENCE = "173" # code independence merge corrupts touching edits |
| 49 | _C_SIGN_DEFAULT = "136" # signing default is an open product decision |
| 50 | |
| 51 | |
| 52 | @pytest.fixture(scope="module") |
| 53 | def html(rendered: dict[str, str]) -> str: |
| 54 | return html_lib.unescape(rendered[PAGE]) |
| 55 | |
| 56 | |
| 57 | @pytest.fixture(scope="module") |
| 58 | def text(html: str) -> str: |
| 59 | return " ".join(re.sub(r"<[^>]+>", "", html).split()) |
| 60 | |
| 61 | |
| 62 | def _engine_env() -> dict[str, str]: |
| 63 | """A child environment that imports the same engine as this process and has the MIDI switch OFF.""" |
| 64 | env = {k: v for k, v in os.environ.items() if k != "MUSE_ENABLE_MIDI"} |
| 65 | env["PYTHONPATH"] = os.pathsep.join(p for p in sys.path if p) |
| 66 | return env |
| 67 | |
| 68 | |
| 69 | # ── DOC_VIS_04: the MIDI dimension grid (V2) ──────────────────────────────── |
| 70 | |
| 71 | |
| 72 | class TestDimensionGrid: |
| 73 | def test_counts_are_the_engine_counts(self) -> None: |
| 74 | assert data.DIM_COUNT == len(midi_merge.INTERNAL_DIMS) == 21 |
| 75 | assert data.INDEPENDENT_COUNT == 18 |
| 76 | assert set(data.NON_INDEPENDENT_NAMES) == set(midi_merge.NON_INDEPENDENT_DIMS) == { |
| 77 | "tempo_map", |
| 78 | "time_signatures", |
| 79 | "track_structure", |
| 80 | } |
| 81 | |
| 82 | def test_every_dimension_has_a_description_and_no_extra(self) -> None: |
| 83 | assert set(data._HOLDS) == set(midi_merge.INTERNAL_DIMS) # noqa: SLF001 - the table under test |
| 84 | assert all(d.holds for d in data.MIDI_DIMS) |
| 85 | |
| 86 | def test_grid_renders_every_dimension_once_in_engine_order(self, html: str) -> None: |
| 87 | assert re.findall(r'<li class="vdim__cell[^"]*" data-dim="([a-z_]+)"', html) == midi_merge.INTERNAL_DIMS |
| 88 | |
| 89 | def test_exactly_the_non_independent_dimensions_are_marked(self, html: str) -> None: |
| 90 | marked = re.findall(r'<li class="vdim__cell vdim__cell--blocking" data-dim="([a-z_]+)"', html) |
| 91 | assert set(marked) == set(midi_merge.NON_INDEPENDENT_DIMS) |
| 92 | |
| 93 | def test_marking_is_also_in_text_not_colour_alone(self, html: str) -> None: |
| 94 | assert html.count("non-independent: blocks the rest") == len(midi_merge.NON_INDEPENDENT_DIMS) |
| 95 | |
| 96 | def test_aliases_shown_resolve_to_their_dimension(self, html: str) -> None: |
| 97 | for dim, shown in re.findall( |
| 98 | r'data-dim="([a-z_]+)">.*?(?:<span class="vdim__alias">\.museattributes: ([^<]+)</span>)?\s*<span class="vdim__kind"', |
| 99 | html, |
| 100 | flags=re.S, |
| 101 | ): |
| 102 | for alias in filter(None, (a.strip() for a in shown.split(","))): |
| 103 | assert midi_merge.DIM_ALIAS[alias] == dim |
| 104 | |
| 105 | def test_prose_states_the_real_counts_and_the_real_non_independent_three(self, text: str) -> None: |
| 106 | assert "composition of 21 named dimensions" in text |
| 107 | assert "18 of them are independent" in text |
| 108 | assert "tempo_map, time_signatures and track_structure" in text |
| 109 | assert "21 independent" not in text |
| 110 | assert "onset position" not in text |
| 111 | |
| 112 | def test_hand_written_names_that_are_not_dimensions_are_gone(self, html: str) -> None: |
| 113 | for gone in ("beat-ref", "bar-ref", "time-sig", "poly-aftertouch", "position", "cc-sustain"): |
| 114 | assert f">{gone}<" not in html # the old hand-written tags, matched as whole tag texts |
| 115 | assert "vision-dim-tag" not in html |
| 116 | |
| 117 | |
| 118 | # ── DOC_VIS_04: the domains section ───────────────────────────────────────── |
| 119 | |
| 120 | |
| 121 | class TestDomains: |
| 122 | def test_default_domains_are_what_the_engine_registers_and_midi_is_opt_in(self) -> None: |
| 123 | probe = "from muse.plugins.registry import registered_domains as r; print(','.join(r()))" |
| 124 | off = subprocess.run([sys.executable, "-P", "-c", probe], env=_engine_env(), capture_output=True, text=True, check=True) |
| 125 | on = subprocess.run( |
| 126 | [sys.executable, "-P", "-c", probe], env={**_engine_env(), "MUSE_ENABLE_MIDI": "1"}, capture_output=True, text=True, check=True |
| 127 | ) |
| 128 | assert tuple(off.stdout.strip().split(",")) == data.DEFAULT_DOMAINS |
| 129 | assert "midi" not in data.DEFAULT_DOMAINS |
| 130 | assert set(on.stdout.strip().split(",")) == set(data.DEFAULT_DOMAINS) | {"midi"} |
| 131 | |
| 132 | def test_every_default_domain_has_a_role_line_and_no_extra(self) -> None: |
| 133 | assert set(data._ROLE) == set(data.DEFAULT_DOMAINS) # noqa: SLF001 - the table under test |
| 134 | |
| 135 | def test_cards_cover_the_defaults_plus_midi(self, html: str) -> None: |
| 136 | assert set(re.findall(r'data-domain="([a-z]+)"', html)) == set(data.DEFAULT_DOMAINS) | {"midi"} |
| 137 | |
| 138 | def test_page_states_the_default_count(self, text: str) -> None: |
| 139 | assert f"registers {data.DEFAULT_DOMAIN_COUNT} domains by default" in text |
| 140 | |
| 141 | def test_old_claims_are_gone(self, text: str) -> None: |
| 142 | assert "Two are live today" not in text |
| 143 | assert "MIDI / Audio" not in text |
| 144 | assert "Every version control system before Muse" not in text |
| 145 | |
| 146 | def test_planned_domains_say_they_are_not_implemented(self, html: str) -> None: |
| 147 | for name in ("Genomics", "3D Design", "Scientific Simulation"): |
| 148 | before = html.split(f'vision-domain-card-name">{name}<', 1)[0] |
| 149 | assert "Planned · not implemented" in before[-160:] # the status line of that same card |
| 150 | assert html.count("Planned · not implemented") == 3 |
| 151 | assert not {"genomics", "3d", "simulation"} & set(data.DEFAULT_DOMAINS) |
| 152 | |
| 153 | def test_midi_transform_commands_the_page_calls_disabled_are_not_commands(self) -> None: |
| 154 | subs = _top_level_commands(cc.capture_parser()) |
| 155 | assert not {"quantize", "humanize", "invert", "retrograde", "midi"} & subs |
| 156 | |
| 157 | def test_code_card_commands_exist(self) -> None: |
| 158 | parser = cc.capture_parser() |
| 159 | code = _subparsers(_subparsers(parser)["code"]) |
| 160 | assert {"impact", "dead", "coverage", "symbols"} <= set(code) |
| 161 | |
| 162 | |
| 163 | # ── DOC_VIS_05: section numbers follow the registry ───────────────────────── |
| 164 | |
| 165 | |
| 166 | class TestPhaseLabels: |
| 167 | @pytest.mark.parametrize("slug", ["coordination", "harmony", "mcp", "domains"]) |
| 168 | def test_in_prose_phase_numbers_match_the_registry(self, slug: str, html: str) -> None: |
| 169 | num = next(p[1] for p in _PHASES if p[0] == slug) |
| 170 | found = re.findall(rf'href="/muse/{slug}">Phase (\d\d)', html) |
| 171 | assert found and set(found) == {num} |
| 172 | |
| 173 | def test_pager_labels_match_the_registry(self, html: str) -> None: |
| 174 | nums = {p[0]: p[1] for p in _PHASES} |
| 175 | assert f'{nums["mists"]} — Mist Domain' in html |
| 176 | assert f'{nums["crdt"]} — CRDT Primitives' in html |
| 177 | |
| 178 | |
| 179 | # ── DOC_VIS_06: wording that was checked against behaviour ────────────────── |
| 180 | |
| 181 | |
| 182 | class TestWording: |
| 183 | def test_git_sample_is_gits_real_output(self, html: str) -> None: |
| 184 | assert "Binary files a/before.mid and b/after.mid differ" in html |
| 185 | assert "Binary files before.mid and after.mid differ" not in html |
| 186 | |
| 187 | def test_muse_sample_is_the_note_level_old_new_form(self, html: str) -> None: |
| 188 | pane = html.split("vision-compare-pane--muse", 1)[1].split("</div>\n </div>\n </div>", 1)[0] |
| 189 | assert len(re.findall(r'<span class="tok-add">\+ ', pane)) == 3 |
| 190 | assert len(re.findall(r'<span class="tok-del">- ', pane)) == 3 |
| 191 | assert "bar 2" not in pane and "beat 1.00" not in pane |
| 192 | |
| 193 | def test_provenance_is_described_as_opt_in(self, text: str) -> None: |
| 194 | assert "Every commit carries" not in text |
| 195 | assert "None of the three is applied automatically" in text |
| 196 | parser = cc.capture_parser() |
| 197 | commit = _subparsers(parser)["commit"] |
| 198 | flags = {o for a in commit._actions for o in a.option_strings} # noqa: SLF001 |
| 199 | assert {"--agent-id", "--model-id", "--sign"} <= flags |
| 200 | |
| 201 | def test_speed_and_deadlock_claims_are_not_made(self, text: str) -> None: |
| 202 | for gone in ("hundreds of times per session", "it is a deadlock", "machine speed", "without human intervention on the happy path"): |
| 203 | assert gone not in text |
| 204 | assert "No benchmark backs a speed claim yet" in text |
| 205 | |
| 206 | def test_mcp_claim_is_narrowed(self, text: str) -> None: |
| 207 | assert "exposes all of this" not in text |
| 208 | assert "it has no Harmony tools" in text |
| 209 | |
| 210 | def test_protocol_block_matches_the_engine_protocol(self, html: str) -> None: |
| 211 | block = html.split("Domain plugin interface", 1)[1].split("</pre>", 1)[0] |
| 212 | names = re.findall(r'<span class="tok-fn">(\w+)</span>', block) |
| 213 | public = [n for n in vars(MuseDomainPlugin) if not n.startswith("_") and callable(getattr(MuseDomainPlugin, n))] |
| 214 | assert names == ["snapshot", "diff", "merge", "drift", "apply", "schema"] |
| 215 | assert sorted(names) == sorted(public) |
| 216 | for method in ("diff", "merge"): |
| 217 | param = inspect.signature(getattr(MuseDomainPlugin, method)).parameters["repo_root"] |
| 218 | assert param.kind is inspect.Parameter.KEYWORD_ONLY |
| 219 | assert block.count("repo_root") == 2 |
| 220 | |
| 221 | def test_alice_and_bob_dimensions_are_real_dimensions(self) -> None: |
| 222 | assert {"cc_sustain", "notes"} <= set(midi_merge.INTERNAL_DIMS) |
| 223 | assert midi_merge.DIM_ALIAS["sustain"] == "cc_sustain" |
| 224 | |
| 225 | def test_known_defects_link_their_tickets(self, html: str) -> None: |
| 226 | for n in (_C_INDEPENDENCE, _C_SIGN_DEFAULT): |
| 227 | assert f"{MUSE_ISSUES}{n}" in html |
| 228 | assert f"{HUB_ISSUES}{_H_MIDI_DELTA}" in html |
| 229 | |
| 230 | |
| 231 | # ── The engine's dimension merge does what the page promises ──────────────── |
| 232 | |
| 233 | |
| 234 | def _mid(tempo: int = 500_000, cc: int = 0, v1: int = 80, v2: int = 80) -> bytes: |
| 235 | """Smallest MIDI fixture: tempo, one CC64 and two notes (bar 1).""" |
| 236 | m = mido.MidiFile(ticks_per_beat=480) |
| 237 | t = mido.MidiTrack() |
| 238 | m.tracks.append(t) |
| 239 | t.append(mido.MetaMessage("set_tempo", tempo=tempo, time=0)) |
| 240 | t.append(mido.Message("control_change", control=64, value=cc, time=0)) |
| 241 | t.append(mido.Message("note_on", note=60, velocity=v1, time=0)) |
| 242 | t.append(mido.Message("note_off", note=60, velocity=0, time=240)) |
| 243 | t.append(mido.Message("note_on", note=62, velocity=v2, time=0)) |
| 244 | t.append(mido.Message("note_off", note=62, velocity=0, time=240)) |
| 245 | t.append(mido.MetaMessage("end_of_track", time=0)) |
| 246 | buf = io.BytesIO() |
| 247 | m.save(file=buf) |
| 248 | return buf.getvalue() |
| 249 | |
| 250 | |
| 251 | def _events(data_: bytes) -> list[tuple[str, int | None]]: |
| 252 | out: list[tuple[str, int | None]] = [] |
| 253 | for msg in mido.MidiFile(file=io.BytesIO(data_)).tracks[0]: |
| 254 | out.append((msg.type, getattr(msg, "value", None) if msg.type == "control_change" else getattr(msg, "velocity", None))) |
| 255 | return out |
| 256 | |
| 257 | |
| 258 | def test_dimension_merge_library_keeps_every_dimension_for_the_alice_bob_shape() -> None: |
| 259 | merged = midi_merge.merge_midi_dimensions(_mid(), _mid(cc=127), _mid(v1=100), [], "song.mid") |
| 260 | assert merged is not None |
| 261 | ev = _events(merged[0]) |
| 262 | assert ("control_change", 127) in ev and ("note_on", 100) in ev |
| 263 | assert "set_tempo" in {t for t, _ in ev} |
| 264 | assert merged[1]["cc_sustain"] == "left" and merged[1]["notes"] == "right" |
| 265 | |
| 266 | |
| 267 | def test_dimension_merge_library_blocks_on_a_bilateral_tempo_change() -> None: |
| 268 | assert midi_merge.merge_midi_dimensions(_mid(), _mid(tempo=400_000), _mid(tempo=600_000), [], "song.mid") is None |
| 269 | |
| 270 | |
| 271 | def test_dimension_merge_library_conflicts_on_the_same_controller_changed_two_ways() -> None: |
| 272 | assert midi_merge.merge_midi_dimensions(_mid(), _mid(cc=100), _mid(cc=127), [], "song.mid") is None |
| 273 | |
| 274 | |
| 275 | # ── The merge path (MidiPlugin.merge_ops) does what the page says (muse#212, fixed) ─ |
| 276 | |
| 277 | |
| 278 | def _merge_ops(tmp_path: Path, left: bytes, right: bytes) -> tuple[list[tuple[str, int | None]], list[str]]: |
| 279 | """Run the path ``muse merge`` takes for the MIDI domain (MidiPlugin.merge_ops) on base/left/right bytes.""" |
| 280 | (tmp_path / ".muse").mkdir() |
| 281 | plugin = MidiPlugin() |
| 282 | |
| 283 | def snap(raw: bytes) -> Any: |
| 284 | oid = blob_id(raw) |
| 285 | write_object(tmp_path, oid, raw) |
| 286 | return {"files": {"song.mid": oid}, "domain": "midi"} |
| 287 | |
| 288 | base_s, left_s, right_s = snap(_mid()), snap(left), snap(right) |
| 289 | left_ops = plugin.diff(base_s, left_s, repo_root=tmp_path)["ops"] |
| 290 | right_ops = plugin.diff(base_s, right_s, repo_root=tmp_path)["ops"] |
| 291 | result = plugin.merge_ops(base_s, left_s, right_s, left_ops, right_ops, repo_root=tmp_path) |
| 292 | merged = result.merged["files"].get("song.mid") |
| 293 | return (_events(read_object(tmp_path, merged) or b"") if merged else []), list(result.conflicts) |
| 294 | |
| 295 | |
| 296 | def test_midi_merge_keeps_both_sides_and_the_untouched_dimensions(tmp_path: Path) -> None: |
| 297 | events, conflicts = _merge_ops(tmp_path, _mid(cc=127), _mid(v1=100)) |
| 298 | assert conflicts == [] |
| 299 | assert ("control_change", 127) in events and ("note_on", 100) in events |
| 300 | assert any(t == "set_tempo" for t, _ in events) |
| 301 | |
| 302 | |
| 303 | def test_midi_merge_blocks_on_a_bilateral_tempo_change(tmp_path: Path) -> None: |
| 304 | _, conflicts = _merge_ops(tmp_path, _mid(tempo=400_000), _mid(tempo=600_000)) |
| 305 | assert conflicts != [] |
| 306 | |
| 307 | |
| 308 | def test_midi_merge_conflicts_on_the_same_controller_changed_two_ways(tmp_path: Path) -> None: |
| 309 | _, conflicts = _merge_ops(tmp_path, _mid(cc=100), _mid(cc=127)) |
| 310 | assert conflicts != [] |
| 311 | |
| 312 | |
| 313 | def test_midi_merge_conflicts_on_the_same_note_edited_on_both_sides(tmp_path: Path) -> None: |
| 314 | _, conflicts = _merge_ops(tmp_path, _mid(v1=100), _mid(v1=110)) |
| 315 | assert conflicts != [] |
| 316 | |
| 317 | |
| 318 | def test_the_page_describes_the_dimension_merge_on_the_merge_path(text: str) -> None: |
| 319 | assert "merges it dimension by dimension" in text and "is on the merge path" in text |
| 320 | for case in ("a tempo change on both branches", "one controller changed two ways", "the same note edited on both sides", |
| 321 | "reported as a conflict too, never merged with a loss"): |
| 322 | assert case in text, case |
| 323 | for stale in ("does not yet merge", "does not hold yet", "is meant to merge them", "Intended result"): |
| 324 | assert stale not in text, stale |
| 325 | |
| 326 | |
| 327 | def _top_level_commands(parser: Any) -> set[str]: |
| 328 | return set(_subparsers(parser)) |
| 329 | |
| 330 | |
| 331 | def _subparsers(parser: Any) -> dict[str, Any]: |
| 332 | import argparse |
| 333 | |
| 334 | for action in parser._actions: # noqa: SLF001 |
| 335 | if isinstance(action, argparse._SubParsersAction): # noqa: SLF001 |
| 336 | return dict(action.choices) |
| 337 | return {} |
| 338 | |
| 339 | |
| 340 | def test_init_refuses_a_domain_that_is_not_registered(tmp_path: Path, text: str) -> None: |
| 341 | """muse#147 (fixed): without MUSE_ENABLE_MIDI=1, init --domain midi refuses, as the page says.""" |
| 342 | code = "import sys; from muse.cli.app import main; sys.argv = ['muse', 'init', '--domain', 'midi']; sys.exit(main())" |
| 343 | env = {**_engine_env(), "HOME": str(tmp_path), "XDG_CONFIG_HOME": str(tmp_path / ".config")} |
| 344 | work = tmp_path / "repo" |
| 345 | work.mkdir() |
| 346 | proc = subprocess.run([sys.executable, "-P", "-c", code], cwd=work, env=env, capture_output=True, text=True, timeout=60) |
| 347 | assert proc.returncode != 0 |
File History
7 commits
sha256:e1629e5f328982dbf6e535d3f253993c78ff225dfee4ebb0e0a15fc1db69046b
merge: rc25 — docs and docs-contract tests match Muse batch…
Opus 5.5
minor
⚠
2 days ago
sha256:26fa336482c7e8eb47ce0b130ea8c4bc94769cf56746fea14ef72fc3bfcc3bd5
docs(vision): MIDI dimension merge is on the merge path (mu…
Opus 5.5
patch
2 days ago
sha256:dbbf615be725b5889e300e2fe88a603841d6f3c315236e35a5426796bfcdcb65
docs(vision,foundations,domains): init refuses an unregiste…
Opus 5.5
patch
2 days ago
sha256:4ceebb0463025887a217b2c74e9c588f440187292b03e908398d0e3933b2190e
docs(vision): the MIDI merge callout describes today's fail…
Opus 5.5
patch
2 days ago
sha256:369f691c7aaec3ca84a864ad1d099d5409045ddc12d185a922b3c84b9e2a1bad
merge: 100% passing, parallelized MuseHub test suite (task/…
Sonnet 5.5
patch
3 days ago
sha256:8166b51ae53275831023a7ce334228b3ccc8237b55d68a35172389db9ff46ad5
test: 100% passing MuseHub suite, parallelized (xdist, one …
Sonnet 5.5
patch
3 days ago
sha256:4aa7b9e8b5efaedeca95e1d384878c61282a9ad77bd32077fc6dc326d9da1e7d
docs(vision): #258 Vision QA contract v2 — correct /muse/vi…
Sonnet 5.5
minor
⚠
8 days ago