refactor(src): group the root modules by domain and gate the tree's shape in CI

.github/labeler.yml

@@ -35,40 +35,39 @@
 'scope: api':
   - changed-files:
       - any-glob-to-any-file:
-          - 'src/http.rs'
-          - 'src/services.rs'
+          - 'src/api/**'
+          - 'src/app/**'
+          - 'src/http/**'
+          - 'src/services/**'
           - 'src/lib.rs'
 
 'scope: db':
   - changed-files:
       - any-glob-to-any-file:
-          - 'src/database.rs'
-          - 'src/catalog.rs'
+          - 'src/storage/**'
           - 'migrations-v2/**'
 
 'scope: auth':
   - changed-files:
       - any-glob-to-any-file:
-          - 'src/authentication.rs'
-          - 'src/oauth.rs'
-          - 'src/security.rs'
+          - 'src/auth/**'
 
 'scope: subsonic':
   - changed-files:
       - any-glob-to-any-file:
-          - 'src/subsonic.rs'
+          - 'src/subsonic/**'
           - 'docs/subsonic-compatibility.md'
 
 'scope: streaming':
   - changed-files:
       - any-glob-to-any-file:
-          - 'src/media.rs'
-          - 'src/stream_ticket.rs'
+          - 'src/media/**'
+          - 'src/auth/stream_ticket/**'
 
 'scope: scanner':
   - changed-files:
       - any-glob-to-any-file:
-          - 'src/scanner.rs'
+          - 'src/library/**'
 
 # ─────────────────────────────────────────────────────────────
 # Web fine scopes (inside webapp/src/).

.github/workflows/ci-rust.yml

@@ -12,6 +12,7 @@ on:
       - "Cargo.toml"
       - "Cargo.lock"
       - "build.rs"
+      - "scripts/check-rust-layout.sh"
       - "src/**"
       - "migrations-v2/**"
       - "tests/**"
@@ -24,6 +25,7 @@ on:
       - "Cargo.toml"
       - "Cargo.lock"
       - "build.rs"
+      - "scripts/check-rust-layout.sh"
       - "src/**"
       - "migrations-v2/**"
       - "tests/**"
@@ -79,6 +81,12 @@ jobs:
       - name: Install FFmpeg
         run: sudo apt-get update && sudo apt-get install -y --no-install-recommends ffmpeg
 
+      # The shape the restructuring gave the tree: no source file past 800
+      # lines, no test file past 1,000, no unit test inline in the code. The
+      # limits and the one allowed exception live in the script, with why.
+      - name: Rust layout
+        run: sh scripts/check-rust-layout.sh
+
       - name: cargo fmt
         run: cargo fmt --all --check
 
@@ -88,6 +96,14 @@ jobs:
       - name: cargo check
         run: cargo check --all-targets --all-features
 
+      # An intra-doc link that resolves nowhere is a warning rustdoc prints and
+      # nobody reads; here it fails the build, so a renamed item cannot leave
+      # its links behind.
+      - name: cargo doc
+        env:
+          RUSTDOCFLAGS: -D warnings
+        run: cargo doc --no-deps --all-features
+
       - name: cargo test
         run: cargo test --all-features
 

AGENTS.md

@@ -20,11 +20,14 @@ cargo test --all-features
 
 Tests are hermetic and use temporary SQLite databases. No PostgreSQL or Better Auth process is required.
 
+Unit tests live in `tests.rs` beside their module (`foo/mod.rs` declares `#[cfg(test)] mod tests;`), never inline. Integration targets are declared in `Cargo.toml`; a large one is a directory whose `main.rs` declares one file per subject. CI runs `sh scripts/check-rust-layout.sh`: no source file under `src/` past 800 lines, no `tests.rs` or file under `tests/` past 1,000, no inline `mod tests {`. It also runs `cargo doc --no-deps --all-features` with `RUSTDOCFLAGS="-D warnings"`.
+
 ## v2 conventions
 
 - `src/main.rs` only loads config, initializes state, dispatches CLI commands and serves the router. Testable runtime behaviour belongs behind library functions.
-- All environment access lives in `src/config.rs`.
-- SQL stays in `src/database.rs` or later repository modules. Handlers orchestrate HTTP only.
+- `src/` is filed by domain; only `main.rs` and `lib.rs` sit at its root. `app/` (boot, state, router), `cli/`, `config/`; the surfaces `api/` and `subsonic/` over the one domain `services/`; `auth/` (sessions, sign-in guard, OAuth, setup token, instance-key cryptography, stream tickets); `library/` (scanner, watcher, tags, PIDs, credit splitting, playlist files, lyrics parsing); `storage/` (database, catalogue, sync journal, collation, pre-migration copy); `remote/` (outbound client, enrichment, portraits, LRCLIB, podcast feeds, scrobblers); `http/` (security headers, public share, `/reference`, web client); `media/`; `quality/`. A new module goes under the parent whose domain it serves, never at the root.
+- All environment access lives in `src/config/`.
+- SQL stays in `src/storage/database/`, `src/storage/catalog/` or `src/services/`. Handlers orchestrate HTTP only.
 - SQLite connections enable WAL, foreign keys and `busy_timeout`. All mutations acquire the single process-wide writer gate; libraries may scan concurrently but never create independent SQLite writers.
 - Migrations under `migrations-v2/` are immutable once merged. Schema changes always add a new dated migration.
 - Tenant isolation is enforced in repository queries through account plus library membership, not only in handlers.