test(arch): architecture fitness tests (ArchUnitNET) — encode the layering laws once /design rules them

[genwave-radio]

🏛️ What

Add an architecture fitness-test layer (NetArchTest.Rules / maintained fork / ArchUnitNET — evaluate at adoption time) that turns our architectural rules into red tests, extending the existing structural-pin culture (Story278 route sweeps, disclosure contracts, zero-diff gates) down to the generic layer the csproj graph can't see.

🎯 Why

• The build loop is agents-under-review — every rule converted from reviewer judgment into a red test makes builders self-correcting and reviews cheaper (same reasoning as the house mutation-test standard).
• docs/ARCHITECTURE.md is internal-only; an arch-test project is the shipped, executable subset of the architecture — the one form that can't drift (see the 2026-08-07 /document pass for how much prose had).
• For GenWave Business: edition boundaries ("Business assemblies depend on Core, never on demo/spectator internals") are exactly the silently-eroding kind of rule fitness tests hold forever — and "here's the test that fails if the layering breaks" is the answer an auditor wants.

📏 Candidate starter rules (encode rulings, not habits — see dependency below)

1. GenWave.Core stays framework-free (no ASP.NET/Npgsql/Dapper types) — CLAUDE.md law
2. Npgsql/Dapper types appear only inside the repository layer (GenWave.MediaLibrary.Station)
3. HttpClient construction only at designated client seams (CatalogProxyService etc.) — SSRF surface control
4. DTO/record immutability conventions in Core.Abstractions
5. Namespace discipline inside Host (Api / Theming / middleware boundaries)

Rules that restate a csproj reference are dead weight — only encode what the compiler can't see. Domain-specific pins (routes, disclosure) stay bespoke; this is the generic layer beneath them.

⛓️ Dependency

Blocked on a /design session ruling the architecture laws first ("once we decide on them" — Dean, 2026-08-07). Compile-time alternatives (NsDepCop / custom Roslyn analyzers) fit the -warnaserror culture but cost more to author; xUnit fitness tests are the idiomatic entry point given the existing spec culture.

(From a 2026-08-07 discussion; full rationale in the conversation that created projects #3–#9.)

[genwave-radio]

📋 The /design session this issue depends on now has a full agenda (2026-08-07, from the August architecture analysis + accumulated flags):

1. The architecture law set this issue encodes (layering, framework-free Core, repository-layer-only Npgsql, HttpClient seams, DTO immutability)
2. arch: Host graduation rule — subsystems leave Host before Business touches them (ladder: Theming → Catalog → Requests → Stats) #399 — the Host graduation rule + ladder (its enforcement rule lands here as a fitness test)
3. docs+arch: seam-placement criterion — Abstractions vs Core/Abstractions, ten shipped lines in CONTRIBUTING #400 — the Abstractions vs Core/Abstractions placement criterion (ditto; P1.5: Move IStationSettingsStore to Core.Abstractions #11 is the worked example)
4. security: engine control channel — unix socket over shared volume replaces the telnet TCP port (design-first) #403 — the engine control channel socket contract (option b ruled; design ratifies the shape)
5. Carried flags: F99 'the deleted default' (contested — designed, never built, Pi/piper-only work leans against it) and the OFL re-subset of the five original vendored faces (+ where a pack's subset-command provenance lives)

Related but independently schedulable: #401 (MusicSelectionPolicy — opens project #3's cycle), #402 (generated SEAMS.md — no ruling needed, just build it).

[genwave-radio]

I think https://github.com/TNG/ArchUnitNET is the way to go, looks much more up-to-date and maintained.

[genwave-radio]

✅ Ruled at /design 2026-08-07 — this issue is unblocked. All six laws are in (SPEC F105.1; ARCHITECTURE 'Architecture governance' holds the table + rationale): framework-free inner projects, Postgres confinement (+composition-root exemption), HttpClient seams, Abstractions hygiene, Host namespace tripwire (the #399 list), seam mechanics (#400's encodable half). Mechanics ruled: new tests/GenWave.Architecture.Tests project, library evaluated at adoption (ArchUnitNET preferred), pre-existing violations fixed-if-trivial else a named, dated exemption baseline failing on NEW (F105.2). Laws also go front-and-center in CONTRIBUTING.md (F105.3). Ready for /plan.