gabriel / musehub public
test_foundations.py python
296 lines 14.0 KB
Raw
sha256:16d33f5988942b0ea6160933bdd2ac8e5c97aa4a0816c1d4be03abdfc73da2f4 docs: follow Muse 0.2.2rc8 — fixed defects leave the pages Opus 5.5 minor ⚠ breaking 1 day ago
1 """DOC_FND — /muse/foundations contract (musehub#245, QA contract v2).
2
3 Every claim below was checked against muse 0.2.1rc20 (muse ``dev`` 5becda10) in a disposable
4 sandbox on 2026-11-07: IDs were recomputed from stored bytes, the stored records were read
5 back, and the documented commands were run. The figures' data is computed by muse's own
6 functions (``ui_docs._FND_*``); these tests re-derive it from the formulas the page documents,
7 so a change to either the engine or the page fails here. Known product defects stay documented
8 as contract plus warning (#241 defect-preservation rule): the tests pin both halves. Rendering
9 is the shared in-process fixture (no database).
10 """
11
12 from __future__ import annotations
13
14 import base64
15 import dataclasses
16 import hashlib
17 import re
18 import typing
19
20 import pytest
21
22 from musehub.api.routes.musehub import ui_docs
23 from tests.docs_contract import registry_check as rc
24
25 PAGE = rc.phase_path("foundations")
26 MUSE_ISSUES = "https://staging.musehub.ai/gabriel/muse/issues/"
27 MUSEHUB_ISSUES = "https://staging.musehub.ai/gabriel/musehub/issues/"
28
29 # Product tickets the page's known-defect warnings link to (filed under #245, assigned to gabriel).
30 _T_EXCLUSION_POLICY = 154 # [force_track] inert in code repos; check-ignore layers; dot-directories
31 _T_PATTERN_SEMANTICS = 145 # unanchored dir/ matches at the root only; * crosses /
32 _T_ADD_AFTER_RM_CACHED = 146
33 _T_INIT_UNKNOWN_DOMAIN = 147
34 _T_FETCH_FSYNC = 148
35 _T_BRANCH_INTENT_BUS = 151
36
37
38 @pytest.fixture(scope="module")
39 def html(rendered: dict[str, str]) -> str:
40 return rendered[PAGE].replace("'", "'").replace(""", '"').replace(""", '"')
41
42
43 def _section(html: str, anchor: str) -> str:
44 """From ``id="<anchor>"`` to the next subsection or section, whitespace-collapsed."""
45 rest = html.split(f'id="{anchor}"', 1)[1]
46 end = min(i for i in (rest.find('class="devdocs-subsection-title"'), rest.find("</section>")) if i >= 0)
47 return " ".join(rest[:end].split())
48
49
50 def _text(fragment: str) -> str:
51 return re.sub(r"<[^>]+>", "", fragment).replace("&lt;", "<").replace("&gt;", ">").replace("&amp;", "&")
52
53
54 def _code_after(html: str, anchor: str, label: str = "") -> str:
55 """Text of the first ``<pre>`` after ``anchor`` (and after ``label``, when given)."""
56 rest = html.split(f'id="{anchor}"', 1)[1]
57 if label:
58 rest = rest.split(label, 1)[1]
59 return _text(rest.split("<pre>", 1)[1].split("</pre>", 1)[0])
60
61
62 # ── DOC_FND_04: the documented ID formulas reproduce muse's IDs (V1, V3) ─────
63
64
65 def _sha(data: bytes) -> str:
66 return "sha256:" + hashlib.sha256(data).hexdigest()
67
68
69 def _doc_blob(data: bytes) -> str:
70 return _sha(f"blob {len(data)}\0".encode() + data)
71
72
73 def _doc_snapshot(manifest: dict[str, str], directories: list[str]) -> str:
74 parts = sorted(f"{p}\0{oid.split(':', 1)[1]}" for p, oid in manifest.items())
75 parts += [f"dir\0{d}" for d in sorted(directories)]
76 canon = "\0".join(parts).encode()
77 return _sha(f"snapshot {len(canon)}\0".encode() + canon)
78
79
80 def _doc_commit(parents: list[str], snapshot: str, message: str, at: str, author: str, signer: str) -> str:
81 fields = ["\0".join(sorted(p.split(":", 1)[1] for p in parents)), snapshot.split(":", 1)[1], message, at, author, signer]
82 canon = "\0".join(fields).encode()
83 return _sha(f"commit {len(canon)}\0".encode() + canon)
84
85
86 def test_figure_ids_follow_the_documented_formulas() -> None:
87 cards = {c.kind: c for c in ui_docs._FND_ID_CARDS}
88 blobs = {p: _doc_blob(b) for p, b in ui_docs._FND_FILES.items()}
89 assert cards["blob"].result == blobs["README.md"]
90 snapshot = _doc_snapshot(blobs, ui_docs._FND_DIRS)
91 assert cards["snapshot"].result == snapshot
92 commit = _doc_commit([], snapshot, ui_docs._FND_MESSAGE, ui_docs._FND_AT, ui_docs._FND_AUTHOR, ui_docs._FND_SIGNER)
93 assert cards["commit"].result == commit
94 agent, model = ui_docs._FND_AGENT
95 payload = "muse-provenance-v2\n" + "\0".join([commit, ui_docs._FND_AUTHOR, agent, model, "", "", ui_docs._FND_AT])
96 assert cards["signature"].result == hashlib.sha256(payload.encode()).hexdigest()
97
98
99 def test_a_blob_id_is_the_sha256_of_its_object_file() -> None:
100 data = ui_docs._FND_FILES["README.md"]
101 stored = f"blob {len(data)}\0".encode() + data # the on-disk object file
102 assert _sha(stored) == ui_docs._FND_ID_CARDS[0].result
103 assert _sha(data) != ui_docs._FND_ID_CARDS[0].result, "not the SHA-256 of the raw bytes"
104
105
106 def test_figure_signer_key_is_the_public_key_of_the_documented_seed() -> None:
107 from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
108 from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat
109
110 raw = Ed25519PrivateKey.from_private_bytes(bytes(range(32))).public_key().public_bytes(Encoding.Raw, PublicFormat.Raw)
111 assert ui_docs._FND_SIGNER == "ed25519:" + base64.urlsafe_b64encode(raw).rstrip(b"=").decode()
112
113
114 def test_one_changed_byte_changes_every_id_above_it() -> None:
115 rows = {name: (before, after) for name, before, after in ui_docs._FND_PROPAGATION}
116 assert rows["src/app.py blob"][0] == rows["src/app.py blob"][1]
117 for name in ("README.md blob", "snapshot", "commit"):
118 assert rows[name][0] != rows[name][1], name
119
120
121 def test_dag_ids_follow_the_documented_formulas_and_share_blobs() -> None:
122 by_label = {c.label: c for c in ui_docs._FND_DAG}
123 assert by_label["A"].commit_id == ui_docs._FND_ID_CARDS[2].result, "A is the V1 commit"
124 assert by_label["M"].parents == ["B", "C"] and by_label["B"].parents == by_label["C"].parents == ["A"]
125 for c in ui_docs._FND_DAG:
126 parents = [by_label[p].commit_id for p in c.parents]
127 snap = _doc_snapshot(c.manifest, ui_docs._FND_DIRS)
128 at = {"A": "09:00", "B": "09:10", "C": "09:20", "M": "09:30"}[c.label]
129 assert c.commit_id == _doc_commit(parents, snap, c.message, f"2026-11-07T{at}:00+00:00", ui_docs._FND_AUTHOR, ui_docs._FND_SIGNER)
130 app = {c.manifest["src/app.py"] for c in ui_docs._FND_DAG}
131 assert len(app) == 1, "an unchanged file keeps one blob across every snapshot"
132 # M keeps dev's README.md (B) and adds task's new file (C).
133 assert by_label["M"].manifest == {**by_label["C"].manifest, **by_label["B"].manifest}
134
135
136 def test_page_states_the_formulas_the_figures_use(html: str) -> None:
137 formulas = _code_after(html, "object-store", "muse.core.ids")
138 for part in ('"blob <size>\\0" + data', '"snapshot <size>\\0"', '"dir\\0<directory>"', '"commit <size>\\0"', "signer_public_key"):
139 assert part in formulas, part
140
141
142 @pytest.mark.parametrize("figure", ["id-derivation", "object-graph-figure"])
143 def test_figures_render_as_accessible_static_figures(html: str, figure: str) -> None:
144 fig = html.split(f'id="{figure}"', 1)[1].split("</figure>", 1)[0]
145 assert f'aria-labelledby="{figure}-title"' in html and f'id="{figure}-title"' in fig
146 assert "<figcaption" in fig and "<script" not in fig and "<svg" not in fig
147 for table in re.findall(r"<table.*?</table>", fig, re.S):
148 named = "<caption>" in table or re.search(r'aria-labelledby="([\w-]+)"', table)
149 assert named and 'scope="col"' in table
150 if "<caption>" not in table:
151 assert f'id="{named.group(1)}"' in fig, "the table's label is in the figure"
152 for region in re.findall(r'<div class="dagfig__scroll"[^>]*>', fig):
153 assert 'tabindex="0"' in region and 'role="region"' in region and "aria-labelledby=" in region
154
155
156 def test_figures_show_the_computed_ids(html: str) -> None:
157 for card in ui_docs._FND_ID_CARDS[:3]:
158 assert ui_docs._short(card.result) in html
159 for c in ui_docs._FND_DAG:
160 assert ui_docs._short(c.commit_id) in html
161 assert html.count('class="idfig__card') == len(ui_docs._FND_ID_CARDS)
162
163
164 # ── DOC_FND_05: documented shapes equal muse's own types ─────────────────────
165
166
167 def _keys(block: str) -> list[str]:
168 return re.findall(r'"(\w+)"\s*:', block)
169
170
171 def test_status_json_keys_are_the_status_schema(html: str) -> None:
172 from muse.cli.commands.status import _StatusJson
173
174 assert set(_keys(_code_after(html, "cli-json-shape"))) == set(typing.get_type_hints(_StatusJson))
175
176
177 def test_branch_json_keys_are_the_branch_entry_schema(html: str) -> None:
178 from muse.cli.commands.branch import _BranchEntryJson, _CreatedByJson
179
180 keys = set(_keys(_code_after(html, "resumable-branches", "muse branch --json")))
181 nested = set(typing.get_type_hints(_CreatedByJson))
182 assert keys - nested == set(typing.get_type_hints(_BranchEntryJson)) and nested <= keys
183
184
185 def test_commit_record_fields_are_the_dataclass_fields_in_order(html: str) -> None:
186 from muse.core.commits import CommitRecord
187
188 documented = re.findall(r"^\s{4}(\w+):", _code_after(html, "commit-record", "CommitRecord"), re.M)
189 assert documented == [f.name for f in dataclasses.fields(CommitRecord)]
190
191
192 def test_stored_commit_record_lists_exactly_the_dataclass_fields(html: str) -> None:
193 from muse.core.commits import CommitRecord
194
195 stored = _code_after(html, "stored-records", 'devdocs-code-block--output')
196 assert _keys(stored) == [f.name for f in dataclasses.fields(CommitRecord)]
197
198
199 def test_never_tracked_directories_are_the_engine_list(html: str) -> None:
200 from muse.core.snapshot import _ALWAYS_PRUNE_DIRS
201
202 para = html.split("Some directories are never tracked", 1)[1].split("says:", 1)[1].split("</p>", 1)[0]
203 assert set(re.findall(r"<code>([^<]+)</code>", para)) == set(_ALWAYS_PRUNE_DIRS)
204
205
206 # ── DOC_FND_06: corrected claims stay corrected ──────────────────────────────
207
208
209 @pytest.mark.parametrize("stale", [
210 "serialized with <strong>msgpack</strong>", # storage is JSON behind a typed header (muse#12)
211 "3–6×", # unsupported benchmark
212 "msgpack.unpackb", # the decode recipe fails on a stored record
213 "/data/repos", # the hub keeps no per-repo directory
214 "POST /{owner}/{slug}/push<", # no such route
215 "branches/{name}/repair", # no such route; repair is POST …/repair-object|snapshot|commit
216 "WireMPack", # unused server model
217 "≥32 chars", # IDs are exactly sha256:<64-hex>
218 "zero, one, or two parent", # N-way merges exist (muse#105)
219 "format_version", # not a CommitRecord field
220 '"repo_id": "sha256:0000genesis', # not a CommitRecord field (muse#9)
221 "claude-sonnet-4-6", # dated example model ID
222 "midi|identity", # init --domain list: midi is not generally available
223 "SHA-256 of raw bytes", # blob IDs hash a typed header
224 "preimage attack", # replacing an object needs a second-preimage attack
225 "no index file", # .muse/code/stage.json is the staging index
226 "└── agent.md", # agent rules are .museagent.md at the repo root (muse#78)
227 "Muse automatically blocks certain file types", # replaced by the owner-approved wording above
228 ])
229 def test_corrected_claims_stay_corrected(html: str, stale: str) -> None:
230 if stale == "preimage attack":
231 assert "second-preimage attack" in html and "a SHA-256 preimage attack" not in html
232 return
233 assert stale not in html
234
235
236 def test_tag_and_label_examples_use_the_current_commands(html: str) -> None:
237 cli = _section(html, "cli-basics")
238 assert re.search(r"muse tag add v\d+\.\d+\.\d+", cli) and "muse label add" in cli
239 assert 'muse tag add "label"' not in cli
240
241
242 def test_branch_lifecycle_creates_dev_and_signs_the_merge(html: str) -> None:
243 lifecycle = _code_after(html, "branch-dag", "branch lifecycle")
244 assert lifecycle.index("muse branch dev") < lifecycle.index("muse checkout dev")
245 merge = lifecycle.split("muse merge", 1)[1].split("muse branch -d", 1)[0]
246 assert "--agent-id" in merge and "--model-id" in merge and "--sign" in merge
247
248
249 def test_every_subsection_link_has_its_target(html: str) -> None:
250 for frag in set(re.findall(r'href="#([\w-]+)"', html)):
251 assert f'id="{frag}"' in html, frag
252
253
254 # ── DOC_FND_07: known product defects stay documented as contract + warning ─
255
256
257 def _warning_links(html: str, anchor: str, issue: int, base: str = MUSE_ISSUES) -> bool:
258 return f'href="{base}{issue}"' in _section(html, anchor)
259
260
261 def test_exclusion_contract_is_kept_and_its_defect_is_linked(html: str) -> None:
262 force = _section(html, "museignore-force-track")
263 # Owner-approved wording (gabriel, 2026-11-07): the default exclusions are stated, with review guidance.
264 assert "Muse provides default exclusions for certain file types" in force
265 assert "not a substitute for reviewing the contents of a commit" in force
266 assert "verify what will be committed before sharing a repository" in force
267 assert "Known defect in muse 0.2.1rc20" in force and _warning_links(html, "museignore-force-track", _T_EXCLUSION_POLICY)
268 assert _warning_links(html, "cli-basics", _T_EXCLUSION_POLICY), "code add . skips dot-directories"
269
270
271 def test_pattern_semantics_contract_is_kept_and_its_defects_are_linked(html: str) -> None:
272 patterns = _section(html, "museignore-patterns")
273 assert "Any directory named" in patterns and "excludes <code>/</code>" in patterns
274 assert "mirroring gitignore semantics" in patterns
275 assert "Known defects in muse 0.2.1rc20" in patterns and _warning_links(html, "museignore-patterns", _T_PATTERN_SEMANTICS)
276
277
278 @pytest.mark.parametrize(("anchor", "issue", "base"), [
279 ("object-graph", _T_FETCH_FSYNC, MUSE_ISSUES), # durability caveat in the object-store callout
280 ("resumable-branches", _T_BRANCH_INTENT_BUS, MUSE_ISSUES),
281 ("cli-basics", _T_ADD_AFTER_RM_CACHED, MUSE_ISSUES),
282 ("cli-basics", _T_INIT_UNKNOWN_DOMAIN, MUSE_ISSUES),
283 ("push-flow", 171, MUSEHUB_ISSUES), # pushed_at is never updated
284 ])
285 def test_known_defects_link_their_tickets(html: str, anchor: str, issue: int, base: str) -> None:
286 assert _warning_links(html, anchor, issue, base)
287
288
289 def test_resumable_metadata_keeps_its_documented_purpose(html: str) -> None:
290 resumable = _section(html, "resumable-branches")
291 assert "orchestrators can assign" in resumable and "Not yet implemented in muse 0.2.1rc20" in resumable
292
293
294 def test_fsync_contract_is_kept_with_its_caveat(html: str) -> None:
295 graph = _section(html, "object-graph")
296 assert "mkstemp → write → fsync → os.replace" in graph and "Known defect in muse 0.2.1rc20" in graph
File History 7 commits
sha256:16d33f5988942b0ea6160933bdd2ac8e5c97aa4a0816c1d4be03abdfc73da2f4 docs: follow Muse 0.2.2rc8 — fixed defects leave the pages Opus 5.5 minor ⚠ 1 day ago
sha256:4f1496efd3bb9b1e764c31d3d9ae8218a550c06f78e351b15fe58409e4223282 fix(releases,wire): the rc channel is accepted like Muse's … Opus 5.5 minor ⚠ 1 day ago
sha256:e1629e5f328982dbf6e535d3f253993c78ff225dfee4ebb0e0a15fc1db69046b merge: rc25 — docs and docs-contract tests match Muse batch… Opus 5.5 minor ⚠ 2 days ago
sha256:dbbf615be725b5889e300e2fe88a603841d6f3c315236e35a5426796bfcdcb65 docs(vision,foundations,domains): init refuses an unregiste… 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:0d8df91e78d3fa8d14d82f9b35de2f6991462e104025f8f1d80174f55cd18fb6 docs(foundations): QA contract v2 — verified object model, … Opus 5.5 minor ⚠ 9 days ago