refactor(server): extract MetadataDB into lib/metadata_db.py (R3) (#830)

Move-only. The library metadata cache -- the `MetadataDB` class (4,018 lines)
plus the query helpers it owns (keyset paging cursors, the tuning grouping key,
smart-arrangement naming, tag normalisation, the startup DB-restore swap) --
moves out of server.py into a flat `lib/` module. Every moved block is
byte-identical to its server.py original; server.py is exactly origin/main
minus the six cut ranges, minus the now-dead `import contextlib`, plus the
import-back block and the constructor call site.

server.py: 14,037 -> 9,705 lines.

The one non-verbatim change is the seam that lets the class leave server.py:
`MetadataDB.__init__` now takes `config_dir` explicitly instead of reading the
module-level CONFIG_DIR, so `lib/metadata_db.py` does no IO at import
(Principle V). The `meta_db` singleton stays in server.py, so `server.meta_db`
(282 refs) and `server.app` (67 refs) resolve unchanged and no route moves.
None of the 114 `monkeypatch.setattr(server, ...)` targets moved.

Logging still goes through the `feedBack.server` logger, so log filters and
caplog assertions resolve to the same logger object.

`tests/test_settings_export_library_db.py` imports `_apply_pending_db_restore`
from metadata_db (the test moves with its subject); no other test changed.

Verified: pyflakes clean on the new module (zero undefined names, zero unused
imports) and no new undefined name in server.py; pytest 2341 passed;
node --test 1030 passed; eslint 0 errors; uvicorn boot smoke serves
/api/version, /api/library, and all three migrated plugins' src/ module graphs
(stems, studio, editor -> 200).

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+- **`MetadataDB` moved out of `server.py` into `lib/metadata_db.py` (R3, move-only).**
+  The library metadata cache — the `MetadataDB` class (4,018 lines) plus the query
+  helpers it owns (keyset paging cursors, the tuning grouping key, smart-arrangement
+  naming, tag normalisation, the startup DB-restore swap) — now lives in its own flat
+  `lib/` module. `server.py` drops from **14,037 → 9,705 lines** and keeps the
+  `meta_db` singleton, so `server.meta_db` and `server.app` resolve exactly as before
+  and every route is untouched. The only non-verbatim change is the seam that lets the
+  class leave `server.py`: `MetadataDB.__init__` now takes `config_dir` explicitly
+  (`meta_db = MetadataDB(CONFIG_DIR)`) instead of reading the module-level `CONFIG_DIR`,
+  which also means `lib/metadata_db.py` performs no IO at import (Principle V). Logging
+  still goes through the `feedBack.server` logger, so existing log filters and `caplog`
+  assertions resolve to the same logger object. `tests/test_settings_export_library_db.py`
+  now imports `_apply_pending_db_restore` from `metadata_db` (the test moved with its
+  subject); no other test changed. Every moved block is byte-identical to its
+  `server.py` original.
+
 ### Added
 - **Plugins can ship an ES-module `src/` tree (module-migration rails, R0).** The host gains three things so a plugin can move off a single global-scope `screen.js` IIFE onto native ES modules with **no build step**: (1) a new sandboxed `GET /api/plugins/{id}/src/{path}` route that serves a plugin's `src/` source subtree, containment-checked by the same `safe_join` guard as `assets/` (traversal/absolute/NUL → 404); (2) the live-edit cache contract — `Cache-Control: no-cache` + a weak mtime/size `ETag` + `If-None-Match`→`304` — applied to `src/`, `screen.js`, and `assets/` (previously `screen.js` sent no cache headers and `assets/` emitted an ETag but never revalidated), so an edited module reloads on refresh while unchanged ones `304`; and (3) `scriptType`/`minHost` passthrough from `plugin.json` to `/api/plugins`, with the loader injecting a plugin that declares `"scriptType":"module"` as `<script type="module">` (its screen.js becomes `import './src/main.js'`). A `<script type=module>` fires its load event only after its whole static-import graph evaluates, preserving the loader's completion-by-`onload` + `_loadingPluginId` contract. Classic plugins are unaffected; `minHost` is passthrough-only for now (enforcement deferred). Tests: `tests/test_plugin_src_route.py` (serve/media-type/traversal/304/no-stale-304/screen.js+assets conditional), `tests/js/plugin_loader_script_type.test.js` (guarded module injection).
 - **Module-migration governance & rails (R0).** Constitution amended to **v1.2.0**: Principle II now names native ES modules as a first-class, *build-free* extension mechanism (the `scriptType:"module"` load path, both plugins and — over time — core's `static/js/`), keeping the no-bundler/no-transpiler/source-served rule intact; Operating Constraints gains a "Module load contract" clause (a `<script type=module>` load event awaits the whole static-import graph, so completion-by-`onload` is preserved; per-visit re-init comes from the `screen:changed` event, not screen.js re-execution). Mirrored into `CLAUDE.md`. New `docs/plugin-modules.md` (the migration playbook — layering, import-time purity, `import.meta.url` assets, the ETag live-edit loop) and `docs/size-exemptions.md` (the signed 1,500-line size-norm register; Byron signs core/bundled rows, Christian the authored virtuoso row). Adds a **maintainer/CI-only** ESLint gate (`eslint.config.js` + a `lint` CI job): `max-lines` warns at 1,500 as a non-blocking ratchet (ceilings for exempt files mirror the register), and `import-x/no-unresolved` + `import-x/no-cycle` hard-error on ES-module graphs — dormant until module code lands, never on the serve/Docker path.

docs/size-exemptions.md

@@ -54,8 +54,11 @@ without a *signed* exemption" is unenforceable.
 
 ## Planned, NOT exempt (owned by split plans — listed so nothing falls between states)
 
-core `static/app.js` (11,821) · `static/highway.js` (4,154, whole file) · `server.py`
-(13,948) · `static/v3/songs.js` (4,134) · `static/capabilities/audio-session.js`
+core `static/app.js` (11,852) · `static/highway.js` (4,168, whole file) · `server.py`
+(9,705 — was 14,037; ratcheted by the R3 `MetadataDB` extraction) ·
+`lib/metadata_db.py` (4,373 — new in R3; the `MetadataDB` class alone is 4,018 lines
+and is a monolith in its own right, to be split per-table once the router train
+lands) · `static/v3/songs.js` (4,134) · `static/capabilities/audio-session.js`
 (2,974) · `plugins/highway_3d/screen.js` (15,656) · `plugins/keys_highway_3d/screen.js`
 (3,780) · `plugins/drum_highway_3d/screen.js` (3,597) — and every monolith with a PR
 train in the refactor plan. Test files (e.g. `tests/test_plugins.py`) are out of scope

lib/scan_worker.py

@@ -3,7 +3,7 @@
 This module is deliberately kept apart from ``server.py`` so that
 ``ProcessPoolExecutor`` workers can import and unpickle ``_scan_one``
 without dragging in ``server.py``'s import-time side effects
-(``configure_logging()``, ``meta_db = MetadataDB()`` opening/migrating
+(``configure_logging()``, ``meta_db = MetadataDB(CONFIG_DIR)`` opening/migrating
 SQLite, and ``register_plugin_api(app)`` registering routes).
 
 The background scan spawns its pool with the ``spawn`` start method (see

tests/test_settings_api.py

@@ -50,7 +50,7 @@ def client(tmp_path, monkeypatch):
     # Point CONFIG_DIR at a per-test temp path BEFORE server's
     # import-time side effects run. server.py reads CONFIG_DIR from the
     # environment at module load (line 35) and immediately constructs
-    # `meta_db = MetadataDB()` at module level, which calls
+    # `meta_db = MetadataDB(CONFIG_DIR)` at module level, which calls
     # CONFIG_DIR.mkdir(...) and opens a sqlite file — a plain
     # post-import monkeypatch on server.CONFIG_DIR wouldn't catch those
     # side effects, and the real user config dir would get written to.

tests/test_settings_export_library_db.py

@@ -22,6 +22,11 @@ from pathlib import Path
 import pytest
 from fastapi.testclient import TestClient
 
+# The startup DB swap lives with the DB layer it guards, not with server.py.
+# metadata_db reads no environment at import, so a plain module import is safe
+# alongside the env-patched `server_mod` fixture below.
+from metadata_db import _apply_pending_db_restore
+
 
 @pytest.fixture()
 def server_mod(tmp_path, monkeypatch):
@@ -219,7 +224,7 @@ def test_apply_pending_db_restore_swaps_and_clears_sidecars(server_mod, tmp_path
     (tmp_path / "web_library.db-shm").write_bytes(b"OLD-SHM")
     (tmp_path / "web_library.db.restore").write_bytes(new_db)
 
-    server_mod._apply_pending_db_restore(tmp_path)
+    _apply_pending_db_restore(tmp_path)
 
     assert main.read_bytes() == new_db                  # swapped in
     assert not (tmp_path / "web_library.db.restore").exists()
@@ -234,7 +239,7 @@ def test_apply_pending_db_restore_discards_corrupt_keeps_live(server_mod, tmp_pa
     main.write_bytes(b"LIVE-GOOD-DB")
     (tmp_path / "web_library.db.restore").write_bytes(b"SQLite format 3\x00" + b"\xff" * 64)
 
-    server_mod._apply_pending_db_restore(tmp_path)
+    _apply_pending_db_restore(tmp_path)
 
     assert main.read_bytes() == b"LIVE-GOOD-DB"          # live DB preserved
     assert not (tmp_path / "web_library.db.restore").exists()  # bad restore dropped
@@ -242,7 +247,7 @@ def test_apply_pending_db_restore_discards_corrupt_keeps_live(server_mod, tmp_pa
 
 def test_apply_pending_db_restore_noop_without_staging(server_mod, tmp_path):
     (tmp_path / "web_library.db").write_bytes(b"LIVE")
-    server_mod._apply_pending_db_restore(tmp_path)        # nothing staged
+    _apply_pending_db_restore(tmp_path)        # nothing staged
     assert (tmp_path / "web_library.db").read_bytes() == b"LIVE"
 
 
@@ -266,7 +271,7 @@ def test_full_db_backup_restore_round_trip(client, server_mod, tmp_path):
     # Simulate a restart: close the live conn, apply the staged restore,
     # reopen — the song is back.
     server_mod.meta_db.conn.close()
-    server_mod._apply_pending_db_restore(tmp_path)
+    _apply_pending_db_restore(tmp_path)
     conn = sqlite3.connect(str(tmp_path / "web_library.db"))
     try:
         rows = conn.execute(