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-node/src/meshbay_node/roster.py | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'packages/meshbay-node/src/meshbay_node/roster.py') diff --git a/packages/meshbay-node/src/meshbay_node/roster.py b/packages/meshbay-node/src/meshbay_node/roster.py index b0ca78b..064ab93 100644 --- a/packages/meshbay-node/src/meshbay_node/roster.py +++ b/packages/meshbay-node/src/meshbay_node/roster.py @@ -16,7 +16,7 @@ Three tables: only in the operator's hands and the invitee's. The code is what binds a public key to an account without asking the hub -(finding H3). See `docs/invite-pairing-v1.md`. +(finding H3). See `docs/MESHBAY_DESIGN.md` §3.4. """ from __future__ import annotations @@ -63,7 +63,7 @@ DEFAULT_DEVICE_REQUEST_TTL = 3600 _SCHEMA = """\ -- One row per DEVICE, not per person. A browser and a desktop client are two -- keys belonging to one account, and `user_id` alone as the key made the second --- silently overwrite the first (INSERT OR REPLACE). See docs/desktop-client-v1.md §4. +-- silently overwrite the first (INSERT OR REPLACE). See docs/MESHBAY_DESIGN.md §3.3. CREATE TABLE IF NOT EXISTS identities ( user_id TEXT NOT NULL, username TEXT NOT NULL, @@ -81,7 +81,7 @@ CREATE TABLE IF NOT EXISTS identities ( -- transcript binds `nonce_node` — the approving connection's handshake -- nonce — so even a stored signature is unverifiable without it. -- - -- This is what Tier 2 needs (docs/desktop-client-v1.md §4.8): relayed with + -- This is what Tier 2 needs (docs/MESHBAY_DESIGN.md §3.3): relayed with -- the roster, it lets a member verify for themselves that a second device -- belongs to an account whose first device they have already pinned, -- instead of taking the node's word. Verified and discarded until @@ -407,7 +407,7 @@ class Roster: Every live device of every active member of one group, with the evidence that admitted it. - For Tier 2 (`docs/desktop-client-v1.md` §4.8), and therefore + For Tier 2 (`docs/MESHBAY_DESIGN.md` §3.3), and therefore **member-visible** — unlike `list_identities`, which answers the operator. Two consequences of that, and both are the price of the feature rather than oversights: @@ -750,10 +750,10 @@ class Roster: return apps # The TMDB credential and query language are one operator's budget, not a - # per-group concern (docs/mediacenter.md §5.5) — stored under the + # per-group concern (docs/MESHBAY_DESIGN.md §9.7) — stored under the # group_id="" sentinel, the same precedent as `roster.get_member("", - # user_id)` authorizing the operator node-wide (desktop-client-v1.md - # §6.3). Unset means "the shipped default token, TMDB's own default + # user_id)` authorizing the operator node-wide (docs/MESHBAY_DESIGN.md + # §6.1). Unset means "the shipped default token, TMDB's own default # language" — the same "absent means the old behaviour" discipline # enabled_apps already follows. # @@ -791,7 +791,7 @@ class Roster: # Which folder(s) inside the group's shared roots each application uses as # its entry point. One storage shape for every app, keyed by the app's own # name, so adding an application needs no change here at all — that is the - # whole point of the plugin architecture (docs/refactor-groups.md §1.6). + # whole point of the plugin architecture (docs/MESHBAY_DESIGN.md §9.3). # # Always a JSON list, even for an app that only ever wants one directory. # Two shapes for one idea is how `video_root` (scalar) and `photo_roots` -- cgit v1.2.3