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 --- .../meshbay-node/src/meshbay_node/media_cache.py | 36 ++++++++++++---------- 1 file changed, 19 insertions(+), 17 deletions(-) (limited to 'packages/meshbay-node/src/meshbay_node/media_cache.py') diff --git a/packages/meshbay-node/src/meshbay_node/media_cache.py b/packages/meshbay-node/src/meshbay_node/media_cache.py index 2898dea..9dfdf73 100644 --- a/packages/meshbay-node/src/meshbay_node/media_cache.py +++ b/packages/meshbay-node/src/meshbay_node/media_cache.py @@ -4,8 +4,8 @@ Videos and Music group apps. Node-wide (not per-group, `data_dir/media_cache.db`), same rationale as `tmdb_enabled`/`tmdb_api_token` (and `musicbrainz_enabled`, -docs/musicbay.md §6) living in `group_settings` under the `group_id=""` -sentinel (docs/mediacenter.md §5.5): the credential/budget is one +docs/MESHBAY_DESIGN.md §9.8) living in `group_settings` under the `group_id=""` +sentinel (docs/MESHBAY_DESIGN.md §9.7): the credential/budget is one operator's, and a thumbnail or cover image is the same bytes regardless of which group happens to share the file. The `file_mbid`/ `mbid_meta` tables below are the Music app's equivalent of `file_tmdb`/ @@ -13,7 +13,8 @@ regardless of which group happens to share the file. The `file_mbid`/ release's cover is cached under a synthetic `musicbrainz:{mbid}` file_id, the same trick `_fetch_and_cache_poster` uses for a TMDB poster_path). -Disposable and rebuildable, like the rest of the file index (§1, §2) — never +Disposable and rebuildable, like the rest of the file index +(docs/MESHBAY_DESIGN.md §6.5) — never a second identity for a file. Every row here is keyed off a value the node can already derive (a file's own blake3 id, or a TMDB id), so losing this database costs re-probing/re-fetching, not data. @@ -98,14 +99,14 @@ CREATE TABLE IF NOT EXISTS mbid_meta ( json TEXT NOT NULL, fetched_at REAL NOT NULL ); --- Photos app (docs/photos.md): the technical/EXIF fields enrich_photo.py --- reads alongside the thumbnail. Durable for the same reason `thumbs` is — --- without this, only the thumbnail bytes survived a restart, and every --- image was still fully re-decoded through Pillow just to re-derive --- width/height/taken_at/camera, which get_thumb_hash_by_file_id's own --- cache hit had already proven unnecessary. thumb_hash is not duplicated --- here — get_thumb_hash_by_file_id(file_id) already answers that, and a --- second copy would just be one more place for the two to drift. +-- Photos app (docs/MESHBAY_DESIGN.md §9.9): the technical/EXIF fields +-- enrich_photo.py reads alongside the thumbnail. Durable for the same reason +-- `thumbs` is — without this, only the thumbnail bytes survived a restart, and +-- every image was still fully re-decoded through Pillow just to re-derive +-- width/height/taken_at/camera, which get_thumb_hash_by_file_id's own cache +-- hit had already proven unnecessary. thumb_hash is not duplicated here — +-- get_thumb_hash_by_file_id(file_id) already answers that, and a second copy +-- would just be one more place for the two to drift. CREATE TABLE IF NOT EXISTS photo_meta ( file_id TEXT PRIMARY KEY, width INTEGER, @@ -116,10 +117,10 @@ CREATE TABLE IF NOT EXISTS photo_meta ( """ # TMDB overviews/ratings do drift; a file's own resolved tmdb_id does not -# need re-checking on this schedule, only the metadata blob (§5.4, V3). +# need re-checking on this schedule, only the metadata blob (V3). TMDB_META_TTL_SECS = 30 * 86400 -# Same default as TMDB (docs/musicbay.md §6) — MusicBrainz release data is +# Same default as TMDB (docs/MESHBAY_DESIGN.md §9.8) — MusicBrainz release data is # not expected to drift faster; revisit if that proves wrong in practice. MUSICBRAINZ_META_TTL_SECS = 30 * 86400 @@ -231,7 +232,7 @@ class MediaCache: Full per-file reset: forget the match *and* any manual override marker, so the next `media_meta_req` re-resolves from scratch with the current matcher. This is the explicit operator "re-match this - one" action (§10.1/V13) — deliberately stronger than + one" action (V13) — deliberately stronger than `clear_file_tmdb`, which spares an override. """ await self._db.execute("DELETE FROM file_tmdb WHERE file_id = ?", (file_id,)) @@ -282,9 +283,10 @@ class MediaCache: # ── tmdb id + season number -> season-level metadata json ──────────────── # # A show's own overview (tmdb_meta above) is one static field an operator - # found does not necessarily describe every season alike (mediacenter.md - # §5.4) — this is TMDB's per-season `overview`/`air_date`/`poster_path`, - # fetched and cached independently, on the same staleness schedule. + # found does not necessarily describe every season alike + # (docs/MESHBAY_DESIGN.md §9.7) — this is TMDB's per-season + # `overview`/`air_date`/`poster_path`, fetched and cached independently, + # on the same staleness schedule. async def get_season_meta(self, tmdb_id: str, season: int) -> dict | None: async with self._db.execute( -- cgit v1.2.3