From 20a824118c09af15d6c338db4c9480ffe5cbcdb6 Mon Sep 17 00:00:00 2001 From: Christophe Besson Date: Sat, 19 Sep 2026 02:12:47 +0200 Subject: docs: cite MESHBAY_DESIGN.md and a section instead of the merged notes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The per-feature design notes were merged into docs/MESHBAY_DESIGN.md and deleted from the tree on 2026-09-11, but ~230 comments across the three packages still named them — usually written `docs/musicbay.md §3.2`, as though the file were still in docs/. A reader had to know §16 existed to resolve any of them. They now name the section directly. Every mapping comes from §16, the concordance, which already records where each old section landed: musicbay -> §9.8, mediacenter -> §9.7 for the Videos app and §6.5 where the subject is derived data, photos -> §9.9, auth-confirm -> §3.6, refactoring-search -> §9.11, invite-pairing-v1 -> §3.4, per-node-identity-v1 -> §3.2, captcha -> §7.7, chat-sender-keys -> §4.5, apps/refactor-groups -> §9.1–§9.4, desktop-client-v1 per section. Bare citations of the same documents (`draft-v6 §2.11`, `§4.8`, `§3.4`) are retargeted too: those collide with real section numbers in the design document, so leaving them would have been worse than the named form. Four cases the concordance does not cover, each decided rather than guessed: Sub-item references into documents that no longer exist — mediacenter's `§3.3 row 4`, `§3.4b/c`, `apps.md §3b` — name rows and sub-items §9.7 and §9.2 do not reproduce. The module-level citation stays; the sub-item pointer is dropped. The V-findings keep their labels but lose the dead `§10.1/` prefix. §13.8 lists V1–V13 as per-application open items, which is not what the labels mean in these comments, so pointing them at §13.8 would have been a false citation. `apps.md §5`'s virtualization requirement has no counterpart anywhere in the design document. The requirement is stated in the comment itself, so the citation is dropped rather than aimed at a section that does not say it. Comments that attributed a *sentence* to an old note — musicbay's "several thousand files" example, its "what got measured" note, its measured ~11%/~26% cover-art figures, the "original no root, whole shared tree" call — state the fact without attribution now. §9.8 does not contain those sentences and citing it for them would have been wrong. CLAUDE.md's "a reference to a document that no longer exists" row now says the concordance is for git history and out-of-tree material; the code cites sections directly. Verified: 2851 passed, 4 skipped. The 12 errors in the run are the Firefox leg of test_sticky_header.py's browser harness, which is broken at the browser level on this machine — headless Firefox (snap) dies with `[GFX1-]: RenderCompositorSWGL failed mapping default framebuffer`, renders nothing, and the probe exits `{"error": "no measurement"}` after its full 90s wait. Chrome runs the same 12 assertions in 3.2s and passes. Nothing here can affect it: every changed line in style.css is inside a comment. Also checked: ast.parse on every changed .py, `node --check` on every changed .js, the /* */ balance in style.css, and that no changed line exceeds the width its file already used. Co-Authored-By: Claude Opus 5 --- packages/meshbay-hub/tests/test_desktop_shell.py | 11 ++++++----- packages/meshbay-hub/tests/test_downloads.py | 6 +++--- .../tests/test_helloworld_proves_the_plugin_claim.py | 2 +- packages/meshbay-hub/tests/test_hook_ordering.py | 2 +- packages/meshbay-hub/tests/test_password_change.py | 2 +- packages/meshbay-hub/tests/test_password_reset.py | 2 +- packages/meshbay-hub/tests/test_recovery_email.py | 2 +- packages/meshbay-hub/tests/test_recovery_key.py | 2 +- packages/meshbay-hub/tests/test_rewrap_fanout.py | 2 +- packages/meshbay-hub/tests/test_search_files_unmerged.py | 4 ++-- packages/meshbay-hub/tests/test_search_media_merge.py | 2 +- packages/meshbay-hub/tests/test_search_source_merge.py | 2 +- packages/meshbay-hub/tests/test_sticky_band_ring.py | 7 ++++--- packages/meshbay-hub/tests/test_transport_contracts.py | 2 +- packages/meshbay-hub/tests/test_zip_size_limit.py | 2 +- 15 files changed, 26 insertions(+), 24 deletions(-) (limited to 'packages/meshbay-hub/tests') diff --git a/packages/meshbay-hub/tests/test_desktop_shell.py b/packages/meshbay-hub/tests/test_desktop_shell.py index 5862ac3..fcf6c4d 100644 --- a/packages/meshbay-hub/tests/test_desktop_shell.py +++ b/packages/meshbay-hub/tests/test_desktop_shell.py @@ -8,8 +8,8 @@ the design depends on are present in the source, and it fails if one is removed — which is the same treatment `test_downloads.py` gives the three browser-specific save paths, for the same reason. -Every assertion here corresponds to a sentence in `docs/desktop-client-v1.md` -§3. Weak evidence, and the only evidence available without a packaged build; a +Every assertion here corresponds to a sentence in `docs/MESHBAY_DESIGN.md` +§8.2. Weak evidence, and the only evidence available without a packaged build; a person with an installed client is what confirms the rest. """ @@ -370,9 +370,10 @@ def test_plain_http_is_refused_except_to_loopback(): def test_the_interface_is_copied_not_forked(): """ - §2.7: the hub's static directory is the single source. A silent fork is the - only real way to end up maintaining the interface twice, so the copy is - generated and the generated tree is not committed. + docs/MESHBAY_DESIGN.md §8.3: the hub's static directory is the single + source. A silent fork is the only real way to end up maintaining the + interface twice, so the copy is generated and the generated tree is not + committed. """ sync = (CLIENT / "scripts" / "sync-ui.js").read_text(encoding="utf-8") assert "meshbay-hub" in sync and "static" in sync diff --git a/packages/meshbay-hub/tests/test_downloads.py b/packages/meshbay-hub/tests/test_downloads.py index afb85d6..395053b 100644 --- a/packages/meshbay-hub/tests/test_downloads.py +++ b/packages/meshbay-hub/tests/test_downloads.py @@ -146,9 +146,9 @@ def test_a_length_is_only_promised_when_it_is_known(tmp_path): assert "if (entry.size > 0)" in src # The zip-directory download started in files-app.js (group-page refactor) - # and was lifted into file-utils.js's downloadDirectory (docs/photos.md - # §3) so photos-app.js's own "zip this album" button calls the same - # implementation rather than a second one. + # and was lifted into file-utils.js's downloadDirectory + # (docs/MESHBAY_DESIGN.md §9.9) so photos-app.js's own "zip this album" + # button calls the same implementation rather than a second one. # Anchored on the call, not on how its result is bound: the assignment # became a bare `target = ...` inside a try when _openDownloadTarget gained # the ability to refuse an oversized download (test_memory_ceiling.py). diff --git a/packages/meshbay-hub/tests/test_helloworld_proves_the_plugin_claim.py b/packages/meshbay-hub/tests/test_helloworld_proves_the_plugin_claim.py index a1baf92..451b57b 100644 --- a/packages/meshbay-hub/tests/test_helloworld_proves_the_plugin_claim.py +++ b/packages/meshbay-hub/tests/test_helloworld_proves_the_plugin_claim.py @@ -1,7 +1,7 @@ """ The reference application, and what it is for. -`docs/refactor-groups.md` claims that adding an application costs a registry +`docs/MESHBAY_DESIGN.md` §9.4 claims that adding an application costs a registry entry and the app's own files — no op, no MNP message, no route, no edit to the pages that render it. Every other test of that claim reads source for the *absence* of app names, which proves nobody wrote a special case for Videos. It diff --git a/packages/meshbay-hub/tests/test_hook_ordering.py b/packages/meshbay-hub/tests/test_hook_ordering.py index 78561b6..3c82bb0 100644 --- a/packages/meshbay-hub/tests/test_hook_ordering.py +++ b/packages/meshbay-hub/tests/test_hook_ordering.py @@ -37,7 +37,7 @@ STATIC_FILES = [ "video-player.js", "video-app.js", "music-app.js", "music-player.js", "photos-app.js", "pager.js", "group-settings.js", - # The per-app settings architecture (docs/refactor-groups.md §3). Reached + # The per-app settings architecture (docs/MESHBAY_DESIGN.md §9.4). Reached # through the apps.js registry rather than imported by name, so a file # left out of this list is one nothing checks — the failure is silent. "settings-ui.js", "folder-tree.js", diff --git a/packages/meshbay-hub/tests/test_password_change.py b/packages/meshbay-hub/tests/test_password_change.py index 4d2f303..b2fe586 100644 --- a/packages/meshbay-hub/tests/test_password_change.py +++ b/packages/meshbay-hub/tests/test_password_change.py @@ -1,5 +1,5 @@ """ -Passphrase change — Flow A of docs/auth-confirm.md. +Passphrase change — Flow A of docs/MESHBAY_DESIGN.md §3.6. The hub's part is small: re-prove the current passphrase, swap the auth_key verifier, invalidate every other session, keep the caller's. The re-wrapping of diff --git a/packages/meshbay-hub/tests/test_password_reset.py b/packages/meshbay-hub/tests/test_password_reset.py index 1273315..823807c 100644 --- a/packages/meshbay-hub/tests/test_password_reset.py +++ b/packages/meshbay-hub/tests/test_password_reset.py @@ -1,5 +1,5 @@ """ -Passphrase reset by e-mail code — Flow B of docs/auth-confirm.md §4.2. +Passphrase reset by e-mail code — Flow B of docs/MESHBAY_DESIGN.md §3.6. The hub's part re-opens sign-in only: it swaps the auth_key verifier, kills every session, and drops every registered device key so a stored one cannot diff --git a/packages/meshbay-hub/tests/test_recovery_email.py b/packages/meshbay-hub/tests/test_recovery_email.py index 07880d0..96dde5d 100644 --- a/packages/meshbay-hub/tests/test_recovery_email.py +++ b/packages/meshbay-hub/tests/test_recovery_email.py @@ -1,5 +1,5 @@ """ -The recovery key in the registration e-mail (docs/auth-confirm.md §4.4). +The recovery key in the registration e-mail (docs/MESHBAY_DESIGN.md §3.6). When the client sends `recovery_key`, the hub appends it to the verification e-mail and stores it nowhere. When it does not, the e-mail carries only the diff --git a/packages/meshbay-hub/tests/test_recovery_key.py b/packages/meshbay-hub/tests/test_recovery_key.py index 378758a..54415f6 100644 --- a/packages/meshbay-hub/tests/test_recovery_key.py +++ b/packages/meshbay-hub/tests/test_recovery_key.py @@ -1,5 +1,5 @@ """ -The account recovery key (docs/auth-confirm.md §4.3). +The account recovery key (docs/MESHBAY_DESIGN.md §3.6). `generateRecoveryKey` / `deriveRecoveryKey` in keyderive.js are run here under node against the real WebCrypto, rather than reimplemented: the mnemonic has to diff --git a/packages/meshbay-hub/tests/test_rewrap_fanout.py b/packages/meshbay-hub/tests/test_rewrap_fanout.py index 03d24dc..54ef67a 100644 --- a/packages/meshbay-hub/tests/test_rewrap_fanout.py +++ b/packages/meshbay-hub/tests/test_rewrap_fanout.py @@ -1,6 +1,6 @@ """ `MeshBayTransport.rewrapAllNodes` — the passphrase-change / recovery fan-out -(docs/auth-confirm.md §3.2, §4.5). +(docs/MESHBAY_DESIGN.md §3.6). The real function is run under node with its two boundaries stubbed: the hub HTTP calls and the per-node `MeshBayTransport` handshake. What is exercised is diff --git a/packages/meshbay-hub/tests/test_search_files_unmerged.py b/packages/meshbay-hub/tests/test_search_files_unmerged.py index 6956dde..b84b25d 100644 --- a/packages/meshbay-hub/tests/test_search_files_unmerged.py +++ b/packages/meshbay-hub/tests/test_search_files_unmerged.py @@ -19,7 +19,7 @@ merge. Weak evidence, and the only kind available for the SPA — but the failur it guards against is a one-line edit, which is exactly what a source-reading test catches well. -See docs/refactoring-search.md §6.1. +See docs/MESHBAY_DESIGN.md §9.11. """ import re @@ -54,7 +54,7 @@ def test_the_files_list_is_not_merged(): "fileEntries now goes through the source merge. The Files explorer " "shows one folder per group and a member navigates into it; merging " "two groups' copies of a file would remove it from one of those " - "folders. See docs/refactoring-search.md §6.1") + "folders. See docs/MESHBAY_DESIGN.md §9.11") @pytest.mark.parametrize("name", ["videoEntries", "musicEntries", "photoEntries"]) diff --git a/packages/meshbay-hub/tests/test_search_media_merge.py b/packages/meshbay-hub/tests/test_search_media_merge.py index 65f85aa..3464902 100644 --- a/packages/meshbay-hub/tests/test_search_media_merge.py +++ b/packages/meshbay-hub/tests/test_search_media_merge.py @@ -23,7 +23,7 @@ with it — so what this counts is what the grid renders. `t()` is stubbed to return its key: `groupMusicEntries` uses it for the two placeholder album names, and a string is not what is under test here. -See docs/refactoring-search.md. +See docs/MESHBAY_DESIGN.md §9.11. """ import json diff --git a/packages/meshbay-hub/tests/test_search_source_merge.py b/packages/meshbay-hub/tests/test_search_source_merge.py index cadf095..b471891 100644 --- a/packages/meshbay-hub/tests/test_search_source_merge.py +++ b/packages/meshbay-hub/tests/test_search_source_merge.py @@ -20,7 +20,7 @@ it has no imports precisely so that it can be, and a copy of the picking rule in a test would keep agreeing with the original right up until one of them changed. -See docs/refactoring-search.md. +See docs/MESHBAY_DESIGN.md §9.11. """ import json diff --git a/packages/meshbay-hub/tests/test_sticky_band_ring.py b/packages/meshbay-hub/tests/test_sticky_band_ring.py index 2d57822..e5ef860 100644 --- a/packages/meshbay-hub/tests/test_sticky_band_ring.py +++ b/packages/meshbay-hub/tests/test_sticky_band_ring.py @@ -28,9 +28,10 @@ before `test_sticky_header.py` measured it. Read out of the stylesheet rather than measured in a browser, deliberately. A browser shows the 4px at one width, in one of the states that happen to put something above a band; what has to hold is which bands are in which of two -lists, and that is a fact about the source. `docs/apps.md` sends the author of -a new application here to make its toolbar pin, and this is what says whether -the toolbar they add needs the gap — it does not, and it must not have it. +lists, and that is a fact about the source. `docs/MESHBAY_DESIGN.md` §9.2 sends +the author of a new application here to make its toolbar pin, and this is what +says whether the toolbar they add needs the gap — it does not, and it must not +have it. """ import re diff --git a/packages/meshbay-hub/tests/test_transport_contracts.py b/packages/meshbay-hub/tests/test_transport_contracts.py index 9c3a88b..3c2b0b6 100644 --- a/packages/meshbay-hub/tests/test_transport_contracts.py +++ b/packages/meshbay-hub/tests/test_transport_contracts.py @@ -141,7 +141,7 @@ def test_the_view_only_follows_new_messages_when_already_at_the_bottom(chat): def test_every_authorize_admin_op_call_is_registered_in_admin_op_types(transport): """ - Found live (docs/photos.md's photo_roots): `setPhotoRoots` called + Found live (docs/MESHBAY_DESIGN.md §9.9's photo_roots): `setPhotoRoots` called `_authorizeAdminOp(msg, 'photo_roots', ...)` like every other admin op, but `photo_roots` was never added to `ADMIN_OP_TYPES` — so its initial request was never keyed `admin:photo_roots`, the node's `admin_challenge` diff --git a/packages/meshbay-hub/tests/test_zip_size_limit.py b/packages/meshbay-hub/tests/test_zip_size_limit.py index 9471b8a..26c5552 100644 --- a/packages/meshbay-hub/tests/test_zip_size_limit.py +++ b/packages/meshbay-hub/tests/test_zip_size_limit.py @@ -3,7 +3,7 @@ The arbitrary ceiling on a directory zip. `downloadDirectory` is the one implementation behind every "download this folder as a zip" button — Files' single folder, Files' multi-folder selection, -and the Photos album button (docs/photos.md §3) — so the limit is checked +and the Photos album button (docs/MESHBAY_DESIGN.md §9.9) — so the limit is checked once, there, and holds for all of them. Three things are worth pinning. That an oversized folder is refused *before* -- cgit v1.2.3