feat(node): add audio_root, gate Music enrichment on it like video_root

musicbay.md's original call — Music needs no root, tag reads are cheap so
just cover the whole shared tree — didn't hold up against a real messy
library: everything under every shared folder got mixed together with no
way to scope Music down to an actual music collection. This adds an
audio_root setting, symmetric to video_root in every respect: signed
operator op (audio_root/audio_root_ack, MNP bumped to 0.10), validated
against a real directory in the group's own roots before a signature is
even asked for, gates tag/cover enrichment exactly like video_root gates
ffprobe/TMDB (nothing runs until it's set, only files under it once it
is), and a set/change fires a one-off sweep of whatever the folder already
contains.

The old trigger — sweep everything the instant "music" joins enabled_apps
— is gone along with the root-less design it belonged to; setting
audio_root is now the trigger, mirroring set_video_root's
enrich_video_root_fn exactly.

Test coverage mirrors the video_root suite: policy (refuse before a
signature round trip, accept/store correctly) and the enrichment gate
itself (nothing without a root, only files under it, sweep on set).

2 files changed, 293 insertions, 0 deletions

diff --git a/packages/meshbay-node/tests/test_audio_root_gates_enrichment.py b/packages/meshbay-node/tests/test_audio_root_gates_enrichment.py
new file mode 100644
index 0000000..f088f5e
--- /dev/null
+++ b/packages/meshbay-node/tests/test_audio_root_gates_enrichment.py
@@ -0,0 +1,156 @@
+"""
+Music-app enrichment (tag/cover extraction, docs/musicbay.md §2.1/§6) only
+ever runs for a group that has an audio_root configured, and only for files
+under it — see daemon.py's _enrich_new_audio_entries. Same reasoning as
+Videos' video_root gate (test_video_root_gates_enrichment.py), added later:
+musicbay.md's original "no root, whole shared tree" call turned out wrong
+against a real messy library, where everything under every shared folder
+got mixed together with no way to scope Music down to just the actual
+music library.
+
+Setting or changing the root (ops.set_audio_root) fires a one-off sweep
+(_enrich_audio_root_now) of whatever it already contains — same shape as
+_enrich_video_root_now.
+"""
+
+import asyncio
+import os
+
+import pytest
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+from meshbay_common.crypto import generate_gek
+from meshbay_node import ops
+from meshbay_node.config import Config, HubConfig, NodeConfig, GroupConfig, KeystoreConfig
+from meshbay_node.daemon import NodeDaemon
+from meshbay_node.indexer import DirectoryIndexer
+from meshbay_node.indexer.enrich_audio import AudioEnricher
+from meshbay_node.media_cache import MediaCache
+from meshbay_node.roster import Roster
+
+from conftest import one_root
+
+pytestmark = pytest.mark.asyncio
+
+# Above indexer.py's MIN_AUDIO_SIZE_BYTES gate — otherwise these fixture
+# files would never even be indexed at all, regardless of audio_root.
+_AUDIO_BYTES = os.urandom(60 * 1024)
+
+
+def _free_port() -> int:
+    import socket
+    with socket.socket() as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+async def _make_daemon(tmp_path, shared, group_id):
+    config = Config(
+        hub=HubConfig(url="http://localhost:9999", username="testuser"),
+        node=NodeConfig(quic_port=_free_port(), ui_port=_free_port()),
+        groups=[GroupConfig(
+            id=group_id, name="test-group", shared_dir=str(shared),
+            visibility="private", quic_port=29015,
+        )],
+        keystore=KeystoreConfig(path=tmp_path / "keystore.enc"),
+        data_dir=tmp_path / "data",
+    )
+    daemon = NodeDaemon(config)
+    daemon._broadcast_coalesce_secs = 0.01
+    daemon._media_cache = MediaCache(db_path=tmp_path / "media_cache.db")
+    await daemon._media_cache.open()
+    daemon._audio_enricher = AudioEnricher(daemon._media_cache)
+    daemon._roster = Roster(db_path=tmp_path / "roster.db")
+    await daemon._roster.open()
+    return daemon
+
+
+async def _teardown(daemon):
+    await daemon._media_cache.close()
+    await daemon._roster.close()
+
+
+async def test_no_audio_root_means_no_enrichment_at_all(tmp_path):
+    group_id = "a" * 32
+    shared = tmp_path / "shared"
+    shared.mkdir()
+    (shared / "track.mp3").write_bytes(_AUDIO_BYTES)
+
+    daemon = await _make_daemon(tmp_path, shared, group_id)
+    try:
+        indexer = DirectoryIndexer(
+            roots=one_root(shared), group_id=group_id,
+            sk_node=Ed25519PrivateKey.generate(), gek=generate_gek())
+        await indexer.initial_scan()
+        await daemon._on_index_change(indexer)
+        await asyncio.sleep(0.05)
+
+        assert not daemon._enriched_attempted, (
+            "a group with no audio_root configured must not enrich anything, "
+            "not even fall back to the whole index")
+    finally:
+        await _teardown(daemon)
+
+
+async def test_only_entries_under_the_configured_root_are_enriched(tmp_path):
+    group_id = "a" * 32
+    shared = tmp_path / "shared"
+    shared.mkdir()
+    (shared / "Music").mkdir()
+    (shared / "Music" / "in-root.mp3").write_bytes(_AUDIO_BYTES)
+    (shared / "outside.mp3").write_bytes(os.urandom(60 * 1024))
+
+    daemon = await _make_daemon(tmp_path, shared, group_id)
+    try:
+        await daemon._roster.set_audio_root(group_id, "shared/Music", set_by="op")
+        indexer = DirectoryIndexer(
+            roots=one_root(shared), group_id=group_id,
+            sk_node=Ed25519PrivateKey.generate(), gek=generate_gek())
+        await indexer.initial_scan()
+        await daemon._on_index_change(indexer)
+        await asyncio.sleep(0.05)
+
+        by_name = {e.name: e for e in indexer.index.entries}
+        assert by_name["in-root.mp3"].id in daemon._enriched_attempted
+        assert by_name["outside.mp3"].id not in daemon._enriched_attempted, (
+            "a file outside the configured audio_root must never be enriched")
+    finally:
+        await _teardown(daemon)
+
+
+async def test_setting_the_audio_root_sweeps_what_it_already_contains(tmp_path):
+    group_id = "a" * 32
+    shared = tmp_path / "shared"
+    shared.mkdir()
+    (shared / "Music").mkdir()
+    (shared / "Music" / "already-there.mp3").write_bytes(_AUDIO_BYTES)
+
+    daemon = await _make_daemon(tmp_path, shared, group_id)
+    try:
+        indexer = DirectoryIndexer(
+            roots=one_root(shared), group_id=group_id,
+            sk_node=Ed25519PrivateKey.generate(), gek=generate_gek())
+        await indexer.initial_scan()
+        daemon._state["indexers"][group_id] = indexer
+
+        # Broadcast once with nothing configured — nothing should be scheduled.
+        await daemon._on_index_change(indexer)
+        await asyncio.sleep(0.05)
+        assert not daemon._enriched_attempted
+
+        # Now the operator points audio_root at the folder that already held
+        # this file all along.
+        state = {
+            "roster": daemon._roster,
+            "groups_ctx": {group_id: {}},
+            "enrich_audio_root_fn": daemon._enrich_audio_root_now,
+        }
+        await ops.set_audio_root(state, group_id, "shared/Music")
+        await asyncio.sleep(0.05)  # let the fire-and-forget sweep actually run
+
+        entry = next(iter(indexer.index.entries))
+        assert entry.id in daemon._enriched_attempted, (
+            "a file already sitting in the newly-chosen root must be picked "
+            "up by the sweep, not wait for some unrelated future change")
+    finally:
+        await _teardown(daemon)
diff --git a/packages/meshbay-node/tests/test_audio_root_policy.py b/packages/meshbay-node/tests/test_audio_root_policy.py
new file mode 100644
index 0000000..73bbe1f
--- /dev/null
+++ b/packages/meshbay-node/tests/test_audio_root_policy.py
@@ -0,0 +1,137 @@
+"""
+Which folder (possibly a subfolder of a shared root) is the Music app's
+entry point for a group. Same shape as test_video_root_policy.py — a
+signed operator instruction, per-group, stored via roster.py's
+group_settings table, added later once a real messy library showed
+musicbay.md's original "no root, whole shared tree" call was wrong.
+"""
+
+from pathlib import Path
+
+import pytest
+
+from meshbay_common.adminop import OP_AUDIO_ROOT
+from meshbay_node.indexer.group_index import GroupIndex
+from meshbay_node.roster import Roster
+from meshbay_node.transport.webrtc_server import WebRTCPeerSession
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+from conftest import one_root
+
+pytestmark = pytest.mark.asyncio
+
+
+def _session(tmp_path: Path, user_id: str, *, operator: str | None = None) -> WebRTCPeerSession:
+    shared_root = tmp_path / "shared"
+    shared_root.mkdir(exist_ok=True)
+    (shared_root / "Music").mkdir()
+    (shared_root / "Podcasts").mkdir()
+    index = GroupIndex(group_id="g" * 32, sk_node=Ed25519PrivateKey.generate())
+    ctx = {
+        "roots": one_root(shared_root),
+        "index": index,
+        "sk_node": index.sk_node,
+        "node_user_id": operator,
+    }
+    session = WebRTCPeerSession.__new__(WebRTCPeerSession)
+    session._ctx = ctx
+    session._group_id = None
+    session._user_id = user_id
+    session._pk_user = ""
+    session.sent = []
+    session._send = session.sent.append
+    session._audit = lambda *a, **k: None
+    return session
+
+
+# ── Refused before a challenge is even issued ───────────────────────────────
+
+async def test_missing_path_is_refused(tmp_path):
+    session = _session(tmp_path, "op", operator="op")
+    session._has_admin_authority = lambda: True
+    issued = []
+    session._issue_admin_challenge = lambda op, subject: issued.append((op, subject))
+
+    session._do_audio_root({})
+
+    assert not issued
+    assert [m for m in session.sent if m.get("type") == "error"]
+
+
+async def test_a_nonexistent_folder_is_refused(tmp_path):
+    session = _session(tmp_path, "op", operator="op")
+    session._has_admin_authority = lambda: True
+    issued = []
+    session._issue_admin_challenge = lambda op, subject: issued.append((op, subject))
+
+    session._do_audio_root({"path": "shared/Nonexistent"})
+
+    assert not issued, "a mistyped path must be refused before a signature round trip"
+    assert [m for m in session.sent if m.get("type") == "error"]
+
+
+async def test_path_traversal_is_refused(tmp_path):
+    session = _session(tmp_path, "op", operator="op")
+    session._has_admin_authority = lambda: True
+    issued = []
+    session._issue_admin_challenge = lambda op, subject: issued.append((op, subject))
+
+    session._do_audio_root({"path": "../../etc"})
+
+    assert not issued
+    assert [m for m in session.sent if m.get("type") == "error"]
+
+
+async def test_a_request_with_nobody_to_authorize_it_is_refused(tmp_path):
+    session = _session(tmp_path, "member-1", operator="the-operator")
+    session._has_admin_authority = lambda: False
+
+    session._do_audio_root({"path": "shared/Music"})
+
+    assert [m for m in session.sent if m.get("type") == "error"]
+
+
+# ── Accepted cases ───────────────────────────────────────────────────────────
+
+async def test_an_empty_path_is_always_accepted(tmp_path):
+    """Empty means 'unset' — Music shows nothing yet, always valid to clear."""
+    session = _session(tmp_path, "op", operator="op")
+    session._has_admin_authority = lambda: True
+    issued = []
+    session._issue_admin_challenge = lambda op, subject: issued.append((op, subject))
+
+    session._do_audio_root({"path": ""})
+
+    assert issued == [(OP_AUDIO_ROOT, "")]
+
+
+async def test_a_real_subfolder_is_accepted_and_signed(tmp_path):
+    session = _session(tmp_path, "op", operator="op")
+    session._has_admin_authority = lambda: True
+    issued = []
+    session._issue_admin_challenge = lambda op, subject: issued.append((op, subject))
+
+    session._do_audio_root({"path": "shared/Music"})
+
+    assert issued == [(OP_AUDIO_ROOT, "shared/Music")]
+
+
+# ── Where it is stored ──────────────────────────────────────────────────────
+
+async def test_the_setting_lives_on_the_node_and_survives_a_restart(tmp_path):
+    roster = Roster(db_path=tmp_path / "roster.db")
+    await roster.open()
+    try:
+        assert await roster.audio_root("g1") == "", "absent must mean unset"
+        await roster.set_audio_root("g1", "shared/Music", set_by="op")
+        assert await roster.audio_root("g1") == "shared/Music"
+    finally:
+        await roster.close()
+
+    reopened = Roster(db_path=tmp_path / "roster.db")
+    await reopened.open()
+    try:
+        assert await reopened.audio_root("g1") == "shared/Music"
+        assert await reopened.audio_root("g2") == "", "one group's setting must not answer for another"
+    finally:
+        await reopened.close()