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 --- .../src/meshbay_node/transport/webrtc_server.py | 72 ++++++++++++---------- 1 file changed, 38 insertions(+), 34 deletions(-) (limited to 'packages/meshbay-node/src/meshbay_node/transport') diff --git a/packages/meshbay-node/src/meshbay_node/transport/webrtc_server.py b/packages/meshbay-node/src/meshbay_node/transport/webrtc_server.py index 3bb0df7..4540f2f 100644 --- a/packages/meshbay-node/src/meshbay_node/transport/webrtc_server.py +++ b/packages/meshbay-node/src/meshbay_node/transport/webrtc_server.py @@ -174,7 +174,8 @@ USER_BLOB_ACCOUNT_MAX = 8 * 1024 * 1024 _USER_BLOB_KIND_RE = re.compile( r"^(playlists|playlist:[A-Za-z0-9_-]{1,64})$") -# Chat link-preview results, kept in memory only (draft-v6 §2.7: the node +# Chat link-preview results, kept in memory only (docs/MESHBAY_DESIGN.md §6.5: +# the node # produces enrichment on demand and keeps nothing durable — the asking device # caches). Bounded and time-limited so a busy group cannot grow it without end # and a page that changed its card is picked up within the hour. @@ -998,7 +999,7 @@ class WebRTCPeerSession: self._ctx.get("daemon_state", {}).get("tmdb_token_customized", False)), "tmdb_language": str( self._ctx.get("daemon_state", {}).get("tmdb_language") or ""), - # Music app (docs/musicbay.md §6) — same shape as the TMDB + # Music app (docs/MESHBAY_DESIGN.md §9.8) — same shape as the TMDB # fields above. No language field: MusicBrainz search doesn't # take one the way TMDB does. "musicbrainz_enabled": bool(self._group_ctx().get("musicbrainz_enabled", True)), @@ -1174,7 +1175,7 @@ class WebRTCPeerSession: } # The recovery-wrapped copy (MNP 0.14) rides along when present, so a # client holding the recovery key can re-wrap it under a new - # passphrase — docs/auth-confirm.md §4.5. + # passphrase — docs/MESHBAY_DESIGN.md §3.6. if kp.get("bundle_enc_recovery"): resp["bundle_enc_recovery"] = kp["bundle_enc_recovery"] self._send(resp) @@ -1558,7 +1559,7 @@ class WebRTCPeerSession: # A person may hold several devices on one node. The authority admitting a # new one is a key the node already pinned — never the hub, which has stored # no user keys since 2026-08-14 and therefore cannot countersign anything. - # See docs/desktop-client-v1.md §4. + # See docs/MESHBAY_DESIGN.md §3.3. async def _do_device_request(self, msg: dict) -> None: """ @@ -1719,7 +1720,7 @@ class WebRTCPeerSession: # # This is what lets another member check for themselves that this device # belongs to an account whose earlier device they have already pinned, - # instead of taking the node's word (Tier 2, desktop-client-v1.md §4.8). + # instead of taking the node's word (Tier 2, docs/MESHBAY_DESIGN.md §3.3). await roster.pin_identity( user_id=self._user_id, username=self._username or "", pk_ed25519=pk_ed_b64, pk_x25519=pk_x_b64, via="device", @@ -1746,7 +1747,7 @@ class WebRTCPeerSession: What is checked, in order: the key is a live device *of this account* in the node's own roster (never a token claim — that is - `per-node-identity-v1.md`'s rule), the timestamp is fresh, and the + `docs/MESHBAY_DESIGN.md` §3.2's rule), the timestamp is fresh, and the signature verifies over a transcript naming this node, this group and this connection's nonce. A key that is merely well-formed proves nothing. @@ -1964,7 +1965,7 @@ class WebRTCPeerSession: Admission policy for a group, read from the node's own configuration. Never from the hub: a hub that could declare a group open would be handed - the key to it (§3.4 of docs/invite-pairing-v1.md). + the key to it (docs/MESHBAY_DESIGN.md §3.4). """ gctx = (self._ctx.get("groups") or {}).get(group_id) or {} return gctx.get("join_policy", "invite") @@ -2290,9 +2291,9 @@ class WebRTCPeerSession: # include "video" or "music" — both can make outbound third-party # network calls (TMDB, MusicBrainz) once enabled, so an operator opts a # group in explicitly rather than getting it for free - # (docs/mediacenter.md §5.6, docs/musicbay.md §4.4). - # `helloworld` is the reference implementation (docs/refactor-groups.md - # §4.1), hidden client-side behind `?dev=1`. It is here because the + # (docs/MESHBAY_DESIGN.md §9.7, §9.8). + # `helloworld` is the reference implementation (docs/MESHBAY_DESIGN.md + # §9.4), hidden client-side behind `?dev=1`. It is here because the # allow-list is server-side enforcement — a client that names an app this # node does not know is refused — and an app the node refused could not # demonstrate anything. This entry and the client's registry line are the @@ -2363,7 +2364,7 @@ class WebRTCPeerSession: per-group concern (see _do_tmdb_enabled for the per-group on/off switch). Signed like the rest: this changes outbound third-party network traffic the node did not have before the Videos app - (docs/mediacenter.md §5.5, §8) — an unsigned change would let any + (docs/MESHBAY_DESIGN.md §9.7, §6.5) — an unsigned change would let any member alter egress the operator never agreed to. """ token = msg.get("token") @@ -2746,7 +2747,7 @@ class WebRTCPeerSession: def _do_musicbrainz_enabled(self, msg: dict) -> None: """ Whether MusicBrainz lookups run for this group at all. Per-group - from the start (docs/musicbay.md §3.2/§6) — signed like + from the start (docs/MESHBAY_DESIGN.md §9.8) — signed like tmdb_enabled: it decides whether this group's members' Music tab ever makes outbound MusicBrainz traffic. """ @@ -3813,13 +3814,13 @@ class WebRTCPeerSession: self, thumb_hash: str, chunk_index: int, gek: bytes | None, ) -> dict | None: """ - docs/mediacenter.md §5.3: a thumbnail is served through the same + docs/MESHBAY_DESIGN.md §6.5: a thumbnail is served through the same chunked file_req path as a real file, resolved against the media cache instead of the index when the id doesn't match a file. Sliced by `chunk_index` like a real file's chunks, not just handed back whole: a thumbnail/poster/cover never approached CHUNK_SIZE so this used to be equivalent to "only chunk 0 exists", but an audio - transcode result (docs/musicbay.md, the WMA/Musepack exception) is + transcode result (docs/MESHBAY_DESIGN.md §9.8, the WMA/Musepack exception) is cached in the same media_cache blob store and can be several MB — genuinely multi-chunk, same as a file read straight off disk. """ @@ -3939,7 +3940,7 @@ class WebRTCPeerSession: async def _fetch_and_cache_poster(media_cache, tmdb_client, poster_path: str | None) -> str | None: """ Downloads a TMDB poster/backdrop once, caches it under its own - blake3 like a video thumbnail (docs/mediacenter.md §5.4), and + blake3 like a video thumbnail (docs/MESHBAY_DESIGN.md §9.7), and returns the hash a client then fetches via the normal file_req/ chunk path (§5.3) — no client ever contacts image.tmdb.org directly. @@ -3988,7 +3989,7 @@ class WebRTCPeerSession: async def _do_audio_transcode_request(self, msg: dict) -> None: """ - docs/musicbay.md's one exception to "no node-side transcode pool": + docs/MESHBAY_DESIGN.md §9.8's one exception to "no node-side transcode pool": WMA and Musepack tag/cover fine (enrich_audio.py) but decode in no mainstream browser's