refactor(server): carve builtin-content seeding into lib/builtin_content.py (R3b) (#900)

lib/builtin_content.py (321 lines moved). server.py 2,418 -> 2,098.

The calibration/diagnostic sloppaks and the starter library: _copy_builtin_packs,
_write_builtin_pack, the two seed helpers, their source tables, and the seed marker.

━━━ THE ONE SIGNATURE CHANGE, AND WHY THE CARVE IS UNSAFE WITHOUT IT ━━━

server.py has:

    def _feedBack_server_root() -> Path:
        return Path(__file__).resolve().parent

That is correct IN server.py: the repo root in dev, resources/feedBack when bundled — the
tree that actually holds docs/ and data/.

Move that body into lib/ unchanged and it keeps working, silently, and returns lib/. There
is no docs/diagnostics under lib/, so every seed would find nothing, log "source missing"
at debug, and return. Nothing raises. Nothing fails. The starter library simply never
appears, and the calibration sloppak is never seeded — on a fresh install, in the field.

A verbatim move whose MEANING changed because __file__ did.

So this module cannot compute a root: `server_root` is a PARAMETER, and server.py — the
only place that legitimately knows where it lives — passes it in. The trap is now
structurally impossible rather than merely avoided. (_copy_builtin_packs already took the
root that way; the two seed helpers now do too.)

Everything else is byte-identical. CONFIG_DIR is read late as appstate.config_dir and the
DLC root through dlc_paths._get_dlc_dir — the same seam every router in lib/routers/ uses,
late-bound because tests monkeypatch it.

━━━ PYFLAKES FOUND THREE MISSING IMPORTS THE TESTS WOULD HAVE FOUND ONE AT A TIME ━━━

The moved code uses `secrets`, `stat` and `tempfile`; none was in my import block. Each is
a NameError on a live path. `python3 -m pyflakes` names all three in one shot — this is the
Python twin of the no-undef gate that guarded every frontend carve, and it should run on
every server.py slice from here.

It also flagged a PRE-EXISTING one I deliberately did not touch: server.py's
TuningProviderRegistry.get_merged() calls `logger.exception(...)` in an except handler and
there is no `logger` in the module (it is `log`). So a raising tuning provider takes down
the merged-tunings call for everyone, with a NameError naming the wrong problem. Filed as
issue #899 rather than smuggled into a carve whose whole value is being behaviour-neutral.

The constants lost their underscore prefix: they cross a module boundary now (the seed
tests read them), so `_BUILTIN_STARTER_SOURCES` was a lie.

pytest 2397, pyflakes 0, Codex 0. Guarded by the plugin_context contract test (#898).

Refs #48

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

tests/test_builtin_diagnostic_seed.py

@@ -7,6 +7,7 @@ import os
 import sys
 import time
 
+import builtin_content
 import pytest
 
 
@@ -23,13 +24,13 @@ def test_seed_creates_builtin_diagnostic_sloppak(tmp_path, server_mod):
     """First seed copies the bundled sloppak into diagnostics-builtin/."""
     dlc = tmp_path / "dlc"
     dlc.mkdir()
-    source = server_mod._feedBack_server_root() / server_mod._BUILTIN_DIAGNOSTIC_SOURCES[0][1]
+    source = server_mod._feedBack_server_root() / builtin_content.BUILTIN_DIAGNOSTIC_SOURCES[0][1]
     if not source.is_file():
         pytest.skip(f"source sloppak not present in checkout: {source}")
 
-    server_mod._seed_builtin_diagnostic_sloppaks(dlc)
+    builtin_content.seed_builtin_diagnostic_sloppaks(server_mod._feedBack_server_root(), dlc)
 
-    dest = dlc / server_mod._BUILTIN_DIAGNOSTIC_SUBDIR / server_mod._BUILTIN_DIAGNOSTIC_SOURCES[0][0]
+    dest = dlc / builtin_content.BUILTIN_DIAGNOSTIC_SUBDIR / builtin_content.BUILTIN_DIAGNOSTIC_SOURCES[0][0]
     assert dest.is_file()
     assert dest.stat().st_size == source.stat().st_size
 
@@ -38,16 +39,16 @@ def test_seed_is_idempotent_when_destination_exists(tmp_path, server_mod):
     """Second seed leaves an up-to-date destination unchanged."""
     dlc = tmp_path / "dlc"
     dlc.mkdir()
-    source = server_mod._feedBack_server_root() / server_mod._BUILTIN_DIAGNOSTIC_SOURCES[0][1]
+    source = server_mod._feedBack_server_root() / builtin_content.BUILTIN_DIAGNOSTIC_SOURCES[0][1]
     if not source.is_file():
         pytest.skip(f"source sloppak not present in checkout: {source}")
 
-    server_mod._seed_builtin_diagnostic_sloppaks(dlc)
-    dest = dlc / server_mod._BUILTIN_DIAGNOSTIC_SUBDIR / server_mod._BUILTIN_DIAGNOSTIC_SOURCES[0][0]
+    builtin_content.seed_builtin_diagnostic_sloppaks(server_mod._feedBack_server_root(), dlc)
+    dest = dlc / builtin_content.BUILTIN_DIAGNOSTIC_SUBDIR / builtin_content.BUILTIN_DIAGNOSTIC_SOURCES[0][0]
     first_mtime = dest.stat().st_mtime_ns
     first_size = dest.stat().st_size
 
-    server_mod._seed_builtin_diagnostic_sloppaks(dlc)
+    builtin_content.seed_builtin_diagnostic_sloppaks(server_mod._feedBack_server_root(), dlc)
 
     assert dest.stat().st_mtime_ns == first_mtime
     assert dest.stat().st_size == first_size
@@ -57,18 +58,18 @@ def test_seed_skips_when_destination_is_newer(tmp_path, server_mod):
     """An existing newer destination is not overwritten."""
     dlc = tmp_path / "dlc"
     dlc.mkdir()
-    source = server_mod._feedBack_server_root() / server_mod._BUILTIN_DIAGNOSTIC_SOURCES[0][1]
+    source = server_mod._feedBack_server_root() / builtin_content.BUILTIN_DIAGNOSTIC_SOURCES[0][1]
     if not source.is_file():
         pytest.skip(f"source sloppak not present in checkout: {source}")
-    dest_dir = dlc / server_mod._BUILTIN_DIAGNOSTIC_SUBDIR
+    dest_dir = dlc / builtin_content.BUILTIN_DIAGNOSTIC_SUBDIR
     dest_dir.mkdir(parents=True)
-    dest_name = server_mod._BUILTIN_DIAGNOSTIC_SOURCES[0][0]
+    dest_name = builtin_content.BUILTIN_DIAGNOSTIC_SOURCES[0][0]
     dest = dest_dir / dest_name
     dest.write_bytes(b"user-owned diagnostic copy")
     future = time.time() + 3600
     os.utime(dest, (future, future))
 
-    server_mod._seed_builtin_diagnostic_sloppaks(dlc)
+    builtin_content.seed_builtin_diagnostic_sloppaks(server_mod._feedBack_server_root(), dlc)
 
     assert dest.read_bytes() == b"user-owned diagnostic copy"
 
@@ -77,18 +78,18 @@ def test_seed_refuses_to_follow_symlink_destination(tmp_path, server_mod):
     """A symlink at the destination is skipped, not written through."""
     dlc = tmp_path / "dlc"
     dlc.mkdir()
-    source = server_mod._feedBack_server_root() / server_mod._BUILTIN_DIAGNOSTIC_SOURCES[0][1]
+    source = server_mod._feedBack_server_root() / builtin_content.BUILTIN_DIAGNOSTIC_SOURCES[0][1]
     if not source.is_file():
         pytest.skip(f"source sloppak not present in checkout: {source}")
 
     outside = tmp_path / "outside.txt"
     outside.write_bytes(b"do not overwrite me")
-    dest_dir = dlc / server_mod._BUILTIN_DIAGNOSTIC_SUBDIR
+    dest_dir = dlc / builtin_content.BUILTIN_DIAGNOSTIC_SUBDIR
     dest_dir.mkdir(parents=True)
-    dest = dest_dir / server_mod._BUILTIN_DIAGNOSTIC_SOURCES[0][0]
+    dest = dest_dir / builtin_content.BUILTIN_DIAGNOSTIC_SOURCES[0][0]
     dest.symlink_to(outside)
 
-    server_mod._seed_builtin_diagnostic_sloppaks(dlc)
+    builtin_content.seed_builtin_diagnostic_sloppaks(server_mod._feedBack_server_root(), dlc)
 
     # The symlink target must be untouched and the link left as-is.
     assert outside.read_bytes() == b"do not overwrite me"
@@ -101,11 +102,11 @@ def test_seed_refuses_symlinked_seed_directory(tmp_path, server_mod):
     dlc.mkdir()
     outside_dir = tmp_path / "outside_dir"
     outside_dir.mkdir()
-    (dlc / server_mod._BUILTIN_DIAGNOSTIC_SUBDIR).symlink_to(
+    (dlc / builtin_content.BUILTIN_DIAGNOSTIC_SUBDIR).symlink_to(
         outside_dir, target_is_directory=True
     )
 
-    server_mod._seed_builtin_diagnostic_sloppaks(dlc)
+    builtin_content.seed_builtin_diagnostic_sloppaks(server_mod._feedBack_server_root(), dlc)
 
     # Nothing was written through the directory symlink into the link target.
     assert list(outside_dir.iterdir()) == []
@@ -116,11 +117,11 @@ def test_seed_missing_source_does_not_crash(tmp_path, server_mod, monkeypatch):
     dlc = tmp_path / "dlc"
     dlc.mkdir()
     monkeypatch.setattr(
-        server_mod,
-        "_BUILTIN_DIAGNOSTIC_SOURCES",
+        builtin_content,
+        "BUILTIN_DIAGNOSTIC_SOURCES",
         [("missing.sloppak", "docs/diagnostics/does-not-exist.sloppak")],
     )
 
-    server_mod._seed_builtin_diagnostic_sloppaks(dlc)
+    builtin_content.seed_builtin_diagnostic_sloppaks(server_mod._feedBack_server_root(), dlc)
 
-    assert not (dlc / server_mod._BUILTIN_DIAGNOSTIC_SUBDIR / "missing.sloppak").exists()
+    assert not (dlc / builtin_content.BUILTIN_DIAGNOSTIC_SUBDIR / "missing.sloppak").exists()

tests/test_builtin_starter_seed.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import importlib
 import sys
 
+import builtin_content
 import pytest
 
 
@@ -21,15 +22,15 @@ def server_mod(tmp_path, monkeypatch, isolate_logging):
 def _source(server_mod):
     return (
         server_mod._feedBack_server_root()
-        / server_mod._BUILTIN_STARTER_SOURCES[0][1]
+        / builtin_content.BUILTIN_STARTER_SOURCES[0][1]
     )
 
 
 def _dest(server_mod, dlc):
     return (
         dlc
-        / server_mod._BUILTIN_STARTER_SUBDIR
-        / server_mod._BUILTIN_STARTER_SOURCES[0][0]
+        / builtin_content.BUILTIN_STARTER_SUBDIR
+        / builtin_content.BUILTIN_STARTER_SOURCES[0][0]
     )
 
 
@@ -41,12 +42,12 @@ def test_seed_creates_starter_content_and_marker(tmp_path, server_mod):
     if not source.is_file():
         pytest.skip(f"starter source not present in checkout: {source}")
 
-    server_mod._seed_builtin_starter_content(dlc)
+    builtin_content.seed_builtin_starter_content(server_mod._feedBack_server_root(), dlc)
 
     dest = _dest(server_mod, dlc)
     assert dest.is_file()
     assert dest.stat().st_size == source.stat().st_size
-    assert (server_mod.CONFIG_DIR / server_mod._STARTER_SEED_MARKER).is_file()
+    assert (server_mod.CONFIG_DIR / builtin_content.STARTER_SEED_MARKER).is_file()
 
 
 def test_seed_preserves_source_mtime(tmp_path, server_mod):
@@ -58,7 +59,7 @@ def test_seed_preserves_source_mtime(tmp_path, server_mod):
     if not source.is_file():
         pytest.skip(f"starter source not present in checkout: {source}")
 
-    server_mod._seed_builtin_starter_content(dlc)
+    builtin_content.seed_builtin_starter_content(server_mod._feedBack_server_root(), dlc)
 
     assert _dest(server_mod, dlc).stat().st_mtime_ns == source.stat().st_mtime_ns
 
@@ -78,7 +79,7 @@ def test_seed_runs_only_once_and_respects_deletion(tmp_path, server_mod):
     if not source.is_file():
         pytest.skip(f"starter source not present in checkout: {source}")
 
-    server_mod._seed_builtin_starter_content(dlc)
+    builtin_content.seed_builtin_starter_content(server_mod._feedBack_server_root(), dlc)
     dest = _dest(server_mod, dlc)
     assert dest.is_file()
 
@@ -86,7 +87,7 @@ def test_seed_runs_only_once_and_respects_deletion(tmp_path, server_mod):
     dest.unlink()
 
     # A subsequent launch must not re-seed it.
-    server_mod._seed_builtin_starter_content(dlc)
+    builtin_content.seed_builtin_starter_content(server_mod._feedBack_server_root(), dlc)
     assert not dest.exists()
 
 
@@ -98,15 +99,15 @@ def test_seed_deferred_until_dlc_configured(tmp_path, server_mod):
         pytest.skip(f"starter source not present in checkout: {source}")
 
     # dlc is None and DLC_DIR unset -> _get_dlc_dir() returns None.
-    server_mod._seed_builtin_starter_content(None)
-    assert not (server_mod.CONFIG_DIR / server_mod._STARTER_SEED_MARKER).exists()
+    builtin_content.seed_builtin_starter_content(server_mod._feedBack_server_root(), None)
+    assert not (server_mod.CONFIG_DIR / builtin_content.STARTER_SEED_MARKER).exists()
 
     # Now a DLC is configured: the deferred seed runs.
     dlc = tmp_path / "dlc"
     dlc.mkdir()
-    server_mod._seed_builtin_starter_content(dlc)
+    builtin_content.seed_builtin_starter_content(server_mod._feedBack_server_root(), dlc)
     assert _dest(server_mod, dlc).is_file()
-    assert (server_mod.CONFIG_DIR / server_mod._STARTER_SEED_MARKER).is_file()
+    assert (server_mod.CONFIG_DIR / builtin_content.STARTER_SEED_MARKER).is_file()
 
 
 def test_seed_refuses_symlinked_seed_directory(tmp_path, server_mod):
@@ -119,13 +120,13 @@ def test_seed_refuses_symlinked_seed_directory(tmp_path, server_mod):
 
     outside_dir = tmp_path / "outside"
     outside_dir.mkdir()
-    (dlc / server_mod._BUILTIN_STARTER_SUBDIR).symlink_to(outside_dir)
+    (dlc / builtin_content.BUILTIN_STARTER_SUBDIR).symlink_to(outside_dir)
 
-    server_mod._seed_builtin_starter_content(dlc)
+    builtin_content.seed_builtin_starter_content(server_mod._feedBack_server_root(), dlc)
 
     assert list(outside_dir.iterdir()) == []
     # An incomplete seed must NOT write the marker, so a later launch retries.
-    assert not (server_mod.CONFIG_DIR / server_mod._STARTER_SEED_MARKER).exists()
+    assert not (server_mod.CONFIG_DIR / builtin_content.STARTER_SEED_MARKER).exists()
 
 
 def test_seed_never_overwrites_an_existing_user_file(tmp_path, server_mod):
@@ -140,11 +141,11 @@ def test_seed_never_overwrites_an_existing_user_file(tmp_path, server_mod):
     dest.write_bytes(b"user's own edited pack")
     _os.utime(dest, (1_000_000, 1_000_000))  # far older than the bundled source
 
-    server_mod._seed_builtin_starter_content(dlc)
+    builtin_content.seed_builtin_starter_content(server_mod._feedBack_server_root(), dlc)
 
     assert dest.read_bytes() == b"user's own edited pack"  # untouched
     # counted as already-present, so the one-time seed considers itself done
-    assert (server_mod.CONFIG_DIR / server_mod._STARTER_SEED_MARKER).is_file()
+    assert (server_mod.CONFIG_DIR / builtin_content.STARTER_SEED_MARKER).is_file()
 
 
 def test_seed_does_not_mark_when_destination_is_a_directory(tmp_path, server_mod):
@@ -160,10 +161,10 @@ def test_seed_does_not_mark_when_destination_is_a_directory(tmp_path, server_mod
     bogus.parent.mkdir(parents=True, exist_ok=True)
     bogus.mkdir()  # user (or junk) placed a directory where the pack goes
 
-    server_mod._seed_builtin_starter_content(dlc)
+    builtin_content.seed_builtin_starter_content(server_mod._feedBack_server_root(), dlc)
 
     assert bogus.is_dir()  # untouched
-    assert not (server_mod.CONFIG_DIR / server_mod._STARTER_SEED_MARKER).exists()
+    assert not (server_mod.CONFIG_DIR / builtin_content.STARTER_SEED_MARKER).exists()
 
 
 def test_seed_does_not_mark_when_source_missing(tmp_path, server_mod, monkeypatch):
@@ -172,15 +173,15 @@ def test_seed_does_not_mark_when_source_missing(tmp_path, server_mod, monkeypatc
     dlc = tmp_path / "dlc"
     dlc.mkdir()
     monkeypatch.setattr(
-        server_mod,
-        "_BUILTIN_STARTER_SOURCES",
+        builtin_content,
+        "BUILTIN_STARTER_SOURCES",
         [("missing.feedpak", "content/starter/does-not-exist.feedpak")],
     )
 
-    server_mod._seed_builtin_starter_content(dlc)
+    builtin_content.seed_builtin_starter_content(server_mod._feedBack_server_root(), dlc)
 
-    assert not (dlc / server_mod._BUILTIN_STARTER_SUBDIR / "missing.feedpak").exists()
-    assert not (server_mod.CONFIG_DIR / server_mod._STARTER_SEED_MARKER).exists()
+    assert not (dlc / builtin_content.BUILTIN_STARTER_SUBDIR / "missing.feedpak").exists()
+    assert not (server_mod.CONFIG_DIR / builtin_content.STARTER_SEED_MARKER).exists()
 
 
 def test_every_starter_source_file_is_present(server_mod):
@@ -190,7 +191,7 @@ def test_every_starter_source_file_is_present(server_mod):
     the checkout is clean, so "on disk" == committed."""
     root = server_mod._feedBack_server_root()
     missing = [
-        rel for _, rel in server_mod._BUILTIN_STARTER_SOURCES
+        rel for _, rel in builtin_content.BUILTIN_STARTER_SOURCES
         if not (root / rel).is_file()
     ]
     assert not missing, f"listed starter sources missing on disk: {missing}"
@@ -199,18 +200,18 @@ def test_every_starter_source_file_is_present(server_mod):
 def test_seed_lands_every_listed_starter_pack(tmp_path, server_mod):
     """A real seed run copies every listed pack into starter/ and marks done."""
     root = server_mod._feedBack_server_root()
-    for _, rel in server_mod._BUILTIN_STARTER_SOURCES:
+    for _, rel in builtin_content.BUILTIN_STARTER_SOURCES:
         if not (root / rel).is_file():
             pytest.skip(f"starter source not present in checkout: {rel}")
 
     dlc = tmp_path / "dlc"
     dlc.mkdir()
-    server_mod._seed_builtin_starter_content(dlc)
+    builtin_content.seed_builtin_starter_content(server_mod._feedBack_server_root(), dlc)
 
-    for dest_name, _ in server_mod._BUILTIN_STARTER_SOURCES:
-        dest = dlc / server_mod._BUILTIN_STARTER_SUBDIR / dest_name
+    for dest_name, _ in builtin_content.BUILTIN_STARTER_SOURCES:
+        dest = dlc / builtin_content.BUILTIN_STARTER_SUBDIR / dest_name
         assert dest.is_file(), f"pack not seeded: {dest_name}"
-    assert (server_mod.CONFIG_DIR / server_mod._STARTER_SEED_MARKER).is_file()
+    assert (server_mod.CONFIG_DIR / builtin_content.STARTER_SEED_MARKER).is_file()
 
 
 def test_no_unlisted_starter_pack_on_disk(server_mod):
@@ -220,7 +221,7 @@ def test_no_unlisted_starter_pack_on_disk(server_mod):
     main before being wired up. In CI the checkout is clean, so this flags any
     stray/committed pack that isn't listed."""
     root = server_mod._feedBack_server_root()
-    listed = {rel for _, rel in server_mod._BUILTIN_STARTER_SOURCES}
+    listed = {rel for _, rel in builtin_content.BUILTIN_STARTER_SOURCES}
     if not listed:
         pytest.skip("no starter sources declared")
     content_dir = (root / next(iter(listed))).parent  # all sources share this dir

tests/test_progression_api.py

@@ -5,6 +5,7 @@ import importlib
 import json
 import sys
 
+import builtin_content
 import pytest
 from fastapi.testclient import TestClient
 
@@ -192,7 +193,7 @@ def test_low_accuracy_play_does_not_complete_gated_challenge(client):
 
 
 def test_diagnostic_at_100_completes_calibration(client, server):
-    diag = server._builtin_diagnostic_filename()
+    diag = builtin_content.builtin_diagnostic_filename()
     # A near-miss leaves calibration pending.
     _scored_play(client, filename=diag, accuracy=0.97, score=500)
     assert client.get("/api/progression").json()["onboarding"]["calibration_status"] == "pending"
@@ -207,7 +208,7 @@ def test_diagnostic_play_does_not_feed_challenges_or_quests(client, server):
     # The calibration run is a perfect guitar play — it must yield rank 1
     # EXACTLY, advancing neither the guitar path nor the daily song quest.
     client.post("/api/progression/paths", json={"add": ["guitar"]})
-    r = _scored_play(client, filename=server._builtin_diagnostic_filename(),
+    r = _scored_play(client, filename=builtin_content.builtin_diagnostic_filename(),
                      accuracy=1.0, score=500)
     summary = r.json()["progression"]
     assert summary["calibration_completed"] is True
@@ -228,7 +229,7 @@ def test_pathless_diagnostic_run_still_completes_calibration(client, server):
     run is an earned achievement and must count even before any path is
     selected (e.g. a pre-progression profile playing the diagnostic as a
     hardware test) — yielding a valid pathless rank-1 state."""
-    _scored_play(client, filename=server._builtin_diagnostic_filename(),
+    _scored_play(client, filename=builtin_content.builtin_diagnostic_filename(),
                  accuracy=1.0, score=500)
     data = client.get("/api/progression").json()
     assert data["onboarding"]["calibration_status"] == "completed"
@@ -240,7 +241,7 @@ def test_diagnostic_upgrades_skipped_without_rank_change(client, server):
     client.post("/api/progression/paths", json={"add": ["guitar"]})
     r = client.post("/api/progression/onboarding", json={"action": "skip"})
     assert r.json()["onboarding"]["calibration_status"] == "skipped"
-    _scored_play(client, filename=server._builtin_diagnostic_filename(), accuracy=1.0, score=500)
+    _scored_play(client, filename=builtin_content.builtin_diagnostic_filename(), accuracy=1.0, score=500)
     data = client.get("/api/progression").json()
     assert data["onboarding"]["calibration_status"] == "completed"
     assert data["mastery_rank"] == 1