gabriel / musehub public
test_crdt.py python
427 lines 20.2 KB
Raw
sha256:e1629e5f328982dbf6e535d3f253993c78ff225dfee4ebb0e0a15fc1db69046b merge: rc25 — docs and docs-contract tests match Muse batch… Opus 5.5 minor ⚠ breaking 2 days ago
1 """DOC_CRDT — /muse/crdt contract (musehub#259, QA contract v2).
2
3 Every claim on the page was checked on 2026-11-08 against musehub ``dev`` 4aa7b9e8 and muse 0.2.1rc20 (muse ``dev``
4 5becda10) in a disposable sandbox (isolated HOME, no identity, no hub, no remotes). The method tables, wire formats and
5 lattice-law cards come from the classes in ``muse.core.crdts`` (``docs_crdt_data``); these tests re-derive each from the
6 code the page documents, so a change on either side fails here. Known product defects stay documented as contract plus
7 warning (#241 defect-preservation rule): each is pinned by a strict xfail that flips when its ticket is fixed, so the
8 warning on the page must be removed in the same change. gabriel/muse#125 (RGA) and gabriel/musehub#204 (CRDT merge
9 routing) were fixed in Muse batch 1; their tests now pin the fixed behaviour.
10
11 DOC_CRDT_01 (commands parse), _02 (anchors and section labels) and _03 (URL scheme) are the #242 checkers
12 (``test_doc_inf_cli.py``, ``test_doc_inf_registry.py``, ``test_doc_inf_scheme.py``). DOC_CRDT_04 is ``TestApiSurface`` and
13 ``TestExamples``; _05 is ``TestLawCards`` (V1); _06 is ``TestWording``; _07 is ``TestPluginAndSchema``. No database is used.
14 """
15
16 from __future__ import annotations
17
18 import ast
19 import html as html_lib
20 import importlib.util
21 import json
22 import re
23 from pathlib import Path
24
25 import muse
26 import pytest
27 from muse.core.crdts import RGA
28 from muse.domain import CRDTPlugin, CRDTSnapshotManifest, MuseDomainPlugin
29 from muse.core.schema import CRDTDimensionSpec
30 from muse.plugins.registry import registered_domains, resolve_plugin_by_domain, schema_for
31
32 from musehub.api.routes.musehub import docs_crdt_data as data
33 from musehub.api.routes.musehub.ui_docs import _PHASES
34 from tests.docs_contract import registry_check as rc
35
36 pytestmark = pytest.mark.no_db
37
38 PAGE = rc.phase_path("crdt")
39 MUSE_ISSUES = "https://staging.musehub.ai/gabriel/muse/issues/"
40 HUB_ISSUES = "https://staging.musehub.ai/gabriel/musehub/issues/"
41
42 _C_RGA = "125" # fixed: RGA join idempotent, unknown anchors rejected, no recursion limit
43 _H_MERGE_ROUTING = "204" # fixed: run_merge joins a CRDTPlugin that declares merge_mode "crdt"
44 _C_DOCS = "214" # CRDT docstring examples, `muse annotate` wording and runtime-unresolvable protocol annotations
45
46 _MUSE_PKG = Path(muse.__file__).resolve().parent
47
48
49 @pytest.fixture(scope="module")
50 def html(rendered: dict[str, str]) -> str:
51 return html_lib.unescape(rendered[PAGE])
52
53
54 @pytest.fixture(scope="module")
55 def text(html: str) -> str:
56 return " ".join(re.sub(r"<[^>]+>", "", html).split())
57
58
59 # ── DOC_CRDT_04: the API surface the page lists ─────────────────────────────
60
61
62 class TestApiSurface:
63 def test_listed_methods_are_exactly_the_public_methods(self) -> None:
64 for name, cls in data.CLASSES.items():
65 public = {n for n in dir(cls) if not n.startswith("_")}
66 assert public == set(data.PUBLIC_METHODS[name]), name
67
68 def test_every_method_and_signature_is_on_the_page(self, html: str) -> None:
69 for p in data.PRIMITIVES:
70 for m in p.methods:
71 assert f"<code>{m.name}</code></th><td><code>{m.signature}</code>" in html, (p.name, m.name)
72
73 def test_pinned_signatures(self) -> None:
74 sigs = {(p.name, m.name): m.signature for p in data.PRIMITIVES for m in p.methods}
75 assert sigs["ORSet", "add"] == "(element: str) -> tuple[ORSet, str]"
76 assert sigs["ORSet", "remove"] == "(element: str, observed_tokens: set[str]) -> ORSet"
77 assert sigs["RGA", "insert"] == "(after_id: str | None, value: str, *, element_id: str) -> RGA"
78 assert sigs["LWWRegister", "write"] == "(value: str, timestamp: float, author: str) -> LWWRegister"
79 assert sigs["GCounter", "increment"] == "(agent_id: str, by: int = 1) -> GCounter"
80 assert sigs["VectorClock", "merge"] == "(other: VectorClock) -> VectorClock"
81 assert sigs["AWMap", "set"] == "(key: str, value: str) -> AWMap"
82 assert sigs["VectorClock", "to_dict"] == "() -> dict[str, int]"
83 assert sigs["AWMap", "to_plain_dict"] == "() -> dict[str, str]"
84 assert not any("_CountMap" in v or "_StrMap" in v for v in sigs.values())
85
86 def test_module_file_names_exist_and_the_old_names_do_not(self, html: str) -> None:
87 for p in data.PRIMITIVES:
88 stem = p.module.removesuffix(".py")
89 assert importlib.util.find_spec(f"muse.core.crdts.{stem}") is not None, p.module
90 assert f"<code>{p.module}</code>" in html
91 for stale in ("vector_clock", "gcounter"):
92 assert importlib.util.find_spec(f"muse.core.crdts.{stale}") is None
93 assert f"{stale}.py" not in html
94
95 def test_the_join_method_is_merge_on_vector_clock_and_join_elsewhere(self) -> None:
96 for p in data.PRIMITIVES:
97 cls = data.CLASSES[p.name]
98 other = "join" if p.join_name == "merge" else "merge"
99 assert hasattr(cls, p.join_name) and not hasattr(cls, other), p.name
100 assert {p.name: p.join_name for p in data.PRIMITIVES} == {
101 "VectorClock": "merge",
102 "LWWRegister": "join",
103 "ORSet": "join",
104 "RGA": "join",
105 "AWMap": "join",
106 "GCounter": "join",
107 }
108
109 def test_there_are_no_module_level_merge_functions(self) -> None:
110 for p in data.PRIMITIVES:
111 module = importlib.import_module(f"muse.core.crdts.{p.module.removesuffix('.py')}")
112 assert not hasattr(module, "merge"), p.module
113
114 def test_wire_examples_round_trip_through_the_classes(self, html: str) -> None:
115 for p in data.PRIMITIVES:
116 cls = data.CLASSES[p.name]
117 wire = json.loads(p.wire)
118 assert cls.from_dict(wire).to_dict() == wire, p.name # type: ignore[attr-defined]
119 assert p.wire in html
120
121 def test_six_primitives_and_the_package_exports(self) -> None:
122 import muse.core.crdts as pkg
123
124 assert [p.name for p in data.PRIMITIVES] == list(data.CLASSES) == [
125 "VectorClock",
126 "LWWRegister",
127 "ORSet",
128 "RGA",
129 "AWMap",
130 "GCounter",
131 ]
132 assert all(name in pkg.__all__ for name in data.CLASSES)
133
134 def test_the_library_uses_only_the_standard_library(self) -> None:
135 import sys
136
137 allowed = set(sys.stdlib_module_names) | {"muse"}
138 for path in (_MUSE_PKG / "core" / "crdts").glob("*.py"):
139 for node in ast.walk(ast.parse(path.read_text(encoding="utf-8"))):
140 mods = [a.name for a in node.names] if isinstance(node, ast.Import) else [node.module or ""] if isinstance(node, ast.ImportFrom) else []
141 for mod in mods:
142 assert mod.split(".")[0] in allowed, (path.name, mod)
143
144
145 class TestExamples:
146 @pytest.mark.parametrize("name", list(data.EXAMPLES))
147 def test_example_runs_as_written(self, name: str) -> None:
148 exec(compile(data.EXAMPLES[name], f"<crdt example {name}>", "exec"), {}) # noqa: S102 - the page's own example
149
150 def test_every_example_is_on_the_page_verbatim(self, html: str) -> None:
151 for name, source in data.EXAMPLES.items():
152 assert source in html, name
153
154 def test_orset_remove_only_tombstones_tokens_the_replica_holds(self) -> None:
155 """The page says remove on a replica that never received the add changes nothing."""
156 from muse.core.crdts import ORSet
157
158 s1, tok = ORSet().add("x")
159 empty = ORSet().remove("x", {tok})
160 assert empty.to_dict() == {"entries": [], "tombstones": []}
161 assert "x" in s1.join(empty).elements()
162
163 def test_gcounter_rejects_non_positive_increments(self) -> None:
164 from muse.core.crdts import GCounter
165
166 for by in (0, -1):
167 with pytest.raises(ValueError):
168 GCounter().increment("a", by=by)
169
170 def test_awmap_values_are_strings_not_crdts(self) -> None:
171 from muse.core.crdts import AWMap
172
173 with pytest.raises(TypeError):
174 AWMap().set("k", {"nested": "crdt"}) # type: ignore[arg-type]
175
176 def test_awmap_concurrent_sets_resolve_by_the_greater_token(self) -> None:
177 from muse.core.crdts import AWMap
178
179 a = AWMap({("k", "va", "t1")})
180 b = AWMap({("k", "vb", "t2")})
181 assert a.join(b).get("k") == b.join(a).get("k") == "vb"
182
183 def test_lww_ties_break_on_author_then_value(self) -> None:
184 from muse.core.crdts import LWWRegister
185
186 r = LWWRegister("x", 5.0, "a").join(LWWRegister("y", 5.0, "b"))
187 assert r.read() == "y"
188 assert LWWRegister("x", 5.0, "a").join(LWWRegister("z", 5.0, "a")).read() == "z"
189
190
191 # ── DOC_CRDT_05: the lattice-law cards (V1) ─────────────────────────────────
192
193
194 class TestLawCards:
195 def test_one_card_per_primitive_in_order_with_the_three_laws(self, html: str) -> None:
196 assert re.findall(r'<li class="lawcard[^"]*" data-primitive="(\w+)"', html) == list(data.CLASSES)
197 assert re.findall(r'data-law="([a-z]+)"', html) == ["commutativity", "associativity", "idempotency"] * 6
198
199 def test_the_figure_is_a_labelled_docs_figure(self, html: str) -> None:
200 assert 'id="lattice-law-cards"' in html and 'aria-labelledby="lattice-law-cards-title"' in html
201
202 def test_card_results_are_recomputed_from_the_classes(self) -> None:
203 for card in data.LAW_CARDS:
204 a, b, c = (
205 data._FIXTURES[card.primitive][:3] if card.primitive != "RGA" else data._rga_fixture() # noqa: SLF001
206 )
207 j = card.join_name
208 expect = [
209 getattr(a, j)(b).equivalent(getattr(b, j)(a)),
210 getattr(getattr(a, j)(b), j)(c).equivalent(getattr(a, j)(getattr(b, j)(c))),
211 getattr(a, j)(a).equivalent(a),
212 ]
213 assert [row[4] for row in card.rows] == expect, card.primitive
214
215 def test_all_six_types_hold_all_three_laws_on_their_fixtures(self) -> None:
216 for card in data.LAW_CARDS:
217 assert all(row[4] for row in card.rows), card.primitive
218
219 def test_the_rga_card_shows_the_muse_125_reproduction_holding(self) -> None:
220 rga = next(c for c in data.LAW_CARDS if c.primitive == "RGA")
221 assert [(r[0], r[4]) for r in rga.rows] == [("Commutativity", True), ("Associativity", True), ("Idempotency", True)]
222 assert rga.rows[2][2:4] == ("[A, B, C, D]", "[A, B, C, D]") # a ⊕ a = a: join keeps the local order
223
224 def test_a_failing_law_is_stated_in_text_not_by_colour_alone(self, html: str) -> None:
225 failing = sum(not row[4] for card in data.LAW_CARDS for row in card.rows)
226 assert html.count("NOT equal: the law fails here") == html.count("lawcard__row--fails") == failing
227
228 def test_rga_status_says_property_tested_and_links_the_fix(self, html: str, text: str) -> None:
229 assert "RGA is property-tested" in text and f'{MUSE_ISSUES}{_C_RGA}"' in html
230 for stale in ("RGA convergence is not verified by this card", "Do not rely on RGA convergence", "RecursionError"):
231 assert stale not in text, stale
232
233 def test_the_awmap_card_note_says_what_get_reads(self, text: str) -> None:
234 from muse.core.crdts import AWMap
235
236 assert data.AWMAP_TEMPO_READS == "100" # t3 > t2 on the card's fixture
237 assert AWMap({("tempo", "x", "t2"), ("tempo", "y", "t3")}).get("tempo") == "y"
238 assert 'get("tempo") reads the one with the greater token: "100"' in text
239
240 def test_the_cards_are_an_illustration_not_a_proof(self, text: str) -> None:
241 assert "an illustration on one fixture each, not evidence for all inputs" in text
242 assert "tests, not proofs" in text
243
244
245 # gabriel/muse#125 (fixed in Muse batch 1): the three RGA defects, pinned to the fixed contract.
246 def _d1() -> RGA:
247 return (
248 RGA()
249 .insert(None, "A", element_id="1@a")
250 .insert("1@a", "B", element_id="3@a")
251 .insert("3@a", "C", element_id="4@a")
252 .insert("1@a", "D", element_id="2@a")
253 )
254
255
256 def test_rga_join_is_idempotent_on_a_locally_built_sequence() -> None:
257 r = _d1()
258 assert r.join(r).to_sequence() == r.to_sequence()
259
260
261 def test_rga_insert_rejects_an_unknown_anchor(text: str) -> None:
262 with pytest.raises(ValueError, match="unknown after_id"):
263 RGA().insert(None, "A", element_id="1@a").insert("missing@z", "X", element_id="2@a")
264 assert "raises ValueError" in text
265
266
267 def test_rga_join_handles_a_long_sequential_chain() -> None:
268 c, prev = RGA(), None
269 for i in range(1500):
270 eid = f"{i:06d}@a"
271 c = c.insert(prev, str(i), element_id=eid)
272 prev = eid
273 try:
274 c.join(c)
275 except RecursionError as exc: # pragma: no cover - the defect itself
276 raise AssertionError("RecursionError in RGA.join") from exc
277
278
279 def test_muse_merge_reaches_the_crdt_join() -> None:
280 """gabriel/musehub#204 (fixed): run_merge, the engine behind ``muse merge``, routes a CRDTPlugin that declares
281 merge_mode "crdt" to crdt_join_snapshots, and leaves every other plugin on the three-way path."""
282 from muse.core import merge_engine
283 from muse.plugins.scaffold.plugin import ScaffoldPlugin
284
285 calls: list[str] = []
286
287 class CrdtScaffold(ScaffoldPlugin):
288 def schema(self): # type: ignore[no-untyped-def]
289 return {**super().schema(), "merge_mode": "crdt"}
290
291 real = merge_engine.crdt_join_snapshots_from_snapshots
292
293 def spy(plugin, ours, theirs, domain): # type: ignore[no-untyped-def]
294 calls.append(domain)
295 return real(plugin, ours, theirs, domain)
296
297 base, ours, theirs = ({"f.txt": f"sha256:{c * 64}"} for c in "012")
298 merge_engine.crdt_join_snapshots_from_snapshots = spy # type: ignore[assignment]
299 try:
300 joined = merge_engine.run_merge(base, ours, theirs, merge_engine.STRATEGY_MAP["recursive"],
301 plugin=CrdtScaffold(), domain="scaffold")
302 merge_engine.run_merge(base, ours, theirs, merge_engine.STRATEGY_MAP["recursive"], plugin=ScaffoldPlugin(),
303 domain="scaffold")
304 finally:
305 merge_engine.crdt_join_snapshots_from_snapshots = real # type: ignore[assignment]
306 assert calls == ["scaffold"] # only the plugin that declares "crdt" is joined
307 assert merge_engine.uses_crdt_join(CrdtScaffold()) and not merge_engine.uses_crdt_join(ScaffoldPlugin())
308 assert joined.conflicts == [] and set(joined.applied_strategies.values()) == {"crdt-join"}
309
310
311 # ── DOC_CRDT_06: wording the audit corrected ────────────────────────────────
312
313
314 class TestWording:
315 def test_section_label_and_pager_come_from_the_registry(self, html: str) -> None:
316 nums = {slug: num for slug, num, _t, _d in _PHASES}
317 titles = {slug: t for slug, _n, t, _d in _PHASES}
318 assert f'<span class="devdocs-phase-num">PHASE {nums["crdt"]}</span>' in html
319 for slug in ("vision", "security"):
320 assert f"{nums[slug]} — {titles[slug]}" in html
321
322 def test_the_old_claims_are_gone(self, html: str, text: str) -> None:
323 for stale in (
324 "proven to",
325 "provably-correct",
326 "provably correct",
327 "merge(a: State, b: State)",
328 "Used in:",
329 "three-tier",
330 "merge_mode: three-way",
331 "per-key CRDT values",
332 "each value is itself a CRDT",
333 "State</code> TypedDict",
334 "Mist download counts",
335 "repo star counts",
336 "Harmony audit log",
337 "Replicated Growable Array; ordered sequences with position stability",
338 ):
339 assert stale not in html, stale
340 assert 'merge_mode: "three_way"' in html
341
342 def test_fixed_tickets_stay_linked_and_the_unsupported_designation_is_gone(self, html: str, text: str) -> None:
343 assert f'{MUSE_ISSUES}{_C_RGA}"' in html
344 assert f'{HUB_ISSUES}{_H_MERGE_ROUTING}"' in html
345 assert "Not available in Muse 0.2.1rc20" not in text and "is still merged three-way" not in text
346 assert "the engine does not call it today" not in text
347 assert "Not used by any shipped command or plugin" in text
348
349 def test_the_status_section_is_first_and_in_the_sidebar(self, html: str) -> None:
350 assert html.index('id="status"') < html.index('id="lattice-laws"')
351 assert 'href="#status"' in html and 'href="#schema-types"' in html
352
353 def test_every_primitive_section_and_anchor_exists(self, html: str) -> None:
354 for p in data.PRIMITIVES:
355 assert f'id="{p.anchor}"' in html and f'href="#{p.anchor}"' in html
356
357
358 class TestUsage:
359 """The page says what uses these types today. Re-derived from the engine source."""
360
361 def _importers(self) -> dict[str, set[str]]:
362 found: dict[str, set[str]] = {}
363 for path in _MUSE_PKG.rglob("*.py"):
364 rel = path.relative_to(_MUSE_PKG).as_posix()
365 if rel.startswith("core/crdts/"):
366 continue
367 for node in ast.walk(ast.parse(path.read_text(encoding="utf-8"))):
368 if isinstance(node, ast.ImportFrom) and (node.module or "").startswith("muse.core.crdts"):
369 found.setdefault(rel, set()).update(a.name for a in node.names)
370 if isinstance(node, ast.Import):
371 for a in node.names:
372 if a.name.startswith("muse.core.crdts"):
373 found.setdefault(rel, set()).add(a.name)
374 return found
375
376 def test_only_the_scaffold_template_imports_the_primitives(self) -> None:
377 assert self._importers() == {"plugins/scaffold/plugin.py": {"ORSet", "VectorClock"}}
378
379 def test_muse_annotate_does_not_use_the_classes_it_names(self) -> None:
380 src = (_MUSE_PKG / "cli" / "commands" / "annotate.py").read_text(encoding="utf-8")
381 assert "**ORSet** semantics" in src and "**GCounter** semantics" in src and "real CRDT semantics" in src
382 assert "muse.core.crdts" not in src
383
384 def test_the_annotate_lines_link_their_ticket(self, html: str) -> None:
385 assert html.count(f'{MUSE_ISSUES}{_C_DOCS}"') == 2 # ORSet and GCounter "Used today" lines
386
387 def test_midi_has_its_own_separate_rga(self) -> None:
388 src = (_MUSE_PKG / "plugins" / "midi" / "_crdt_notes.py").read_text(encoding="utf-8")
389 assert "class MidiRGA" in src and "muse.core.crdts" not in src
390
391
392 # ── DOC_CRDT_07: the plugin protocol and the schema types ───────────────────
393
394
395 class TestPluginAndSchema:
396 def test_crdt_plugin_extends_the_domain_plugin_and_has_four_methods(self) -> None:
397 assert MuseDomainPlugin in CRDTPlugin.__mro__
398 own = {n for n, v in vars(CRDTPlugin).items() if callable(v) and not n.startswith("_")}
399 assert own == {m.name for m in data.PLUGIN_METHODS} == {"crdt_schema", "join", "to_crdt_state", "from_crdt_state"}
400
401 def test_plugin_block_renders_the_protocol_signatures(self, html: str) -> None:
402 assert "class CRDTPlugin(MuseDomainPlugin, Protocol):" in html
403 assert "def crdt_schema(self) -> list[CRDTDimensionSpec]: ..." in html
404 assert "def join(self, a: CRDTSnapshotManifest, b: CRDTSnapshotManifest) -> CRDTSnapshotManifest: ..." in html
405
406 def test_primitive_values_and_field_lists_match_the_schema_types(self, html: str) -> None:
407 assert data.CRDT_PRIMITIVE_VALUES == ("lww_register", "or_set", "rga", "aw_map", "g_counter")
408 assert {f for f, _ in data.DIMENSION_SPEC_FIELDS} == set(CRDTDimensionSpec.__required_keys__)
409 assert {f for f, _ in data.MANIFEST_FIELDS} == set(CRDTSnapshotManifest.__required_keys__)
410 for v in data.CRDT_PRIMITIVE_VALUES:
411 assert f'<code>"{v}"</code>' in html
412
413 def test_no_registered_domain_declares_crdt_merge(self) -> None:
414 modes = {d: (schema_for(d) or {}).get("merge_mode") for d in registered_domains()}
415 assert modes and set(modes.values()) == {"three_way"}
416
417 def test_only_the_scaffold_template_implements_the_protocol(self) -> None:
418 names = registered_domains()
419 assert "scaffold" in names and len(names) >= 8
420 assert {d for d in names if isinstance(resolve_plugin_by_domain(d), CRDTPlugin)} == {"scaffold"}
421
422 def test_the_scaffold_template_implements_the_protocol_but_declares_three_way(self) -> None:
423 from muse.plugins.scaffold.plugin import ScaffoldPlugin
424
425 plugin = ScaffoldPlugin()
426 assert isinstance(plugin, CRDTPlugin)
427 assert plugin.schema()["merge_mode"] == "three_way"
File History 3 commits
sha256:e1629e5f328982dbf6e535d3f253993c78ff225dfee4ebb0e0a15fc1db69046b merge: rc25 — docs and docs-contract tests match Muse batch… Opus 5.5 minor ⚠ 2 days ago
sha256:af59de7b8c8e9eaa86759e00caf5ee286439cf1dfc7730b6fb144cb29dd4a09f docs(domains,crdt,landing): .museattributes in every domain… Opus 5.5 minor ⚠ 2 days ago
sha256:259e6968cab8c57d9cd790b248e033ceeab2d75a7bdb547e2e41ffb4316cd3cf docs(crdt): #259 CRDT Primitives QA contract v2 — correct /… Sonnet 5.5 minor ⚠ 8 days ago