test: prove the kernel against the emu-atlas machine vectors (#1542)

Adds the [emu-atlas](https://github.com/danielcopper/emu-atlas)
conformance tier, mirroring the gavel pattern: the 16 machine vectors
from release v0.1.0 are vendored byte-identical under
`tests/atlas_vectors/`, and every vector is driven through this plugin's
own kernel — the fixture file tree is materialized into `tmp_path` and
`RetroDeckPathsAdapter` + `RetroArchConfigAdapter` + `domain/save_path`
must reproduce the placements the published contract expects.

The overlap between the two codebases is partial, so an explicit
per-vector allowlist declares the check level: 8 vectors run end-to-end
(RetroDECK flavors — the saves root is this plugin's own source), 7
check the shared retroarch.cfg interpretation (standalone/native saves
roots the plugin does not model; `<content_dir>` ⇔ sort-by-content,
`<core>` ⇔ sort-by-core, ContentDir ⇔ next-to-ROMs), 1 has no plugin
equivalent (nothing-installed — the plugin always resolves fallback
paths). A collection-time guard fails the run if an upstream vector
appears or disappears without an allowlist decision — no silent skips.

Docs: sibling subsections next to the gavel tier in
`docs/contributing/development.md` and `CLAUDE.md`.

Author: danielcopper

CLAUDE.md

@@ -377,6 +377,20 @@ kernels: **ladder** against `domain/sync_action.resolve_upload_conflict`, **deci
 kernel pass** — updating means deliberately re-copying the JSON and bumping the commit reference in that folder's
 `README.md`.
 
+### emu-atlas conformance vectors — vendored contract tier
+
+The same self-conformance pattern proves the plugin's save-path kernel agrees with
+[emu-atlas](https://github.com/danielcopper/emu-atlas), the config-aware emulator-knowledge library extracted from this
+plugin, where the two overlap. Its `machines` vector family (16 fixture machines in, detected installations + save
+placements out) runs against the real adapters (`RetroDeckPathsAdapter` + `RetroArchConfigAdapter`) and domain functions
+(`resolve_save_dir` / `compute_local_save_target`) in `tests/test_atlas_machine_vectors.py`. The overlap is partial by
+design — the plugin has no standalone-RetroArch saves-root concept (its saves base always comes from RetroDECK paths) —
+so every vector carries an explicit `_CHECK_LEVELS` entry: `full` (end-to-end dir + filename), `layout-only` (only the
+`retroarch.cfg` interpretation — sort flags or the `ContentDir` classification), or `n/a` (no overlap). No vector is
+silently skipped: a new upstream vector without an allowlist entry fails at collection. Vectors are vendored verbatim
+under `tests/atlas_vectors/machines/` at a pinned upstream release tag; **never edit a vector to make the kernel pass**
+— updating means re-copying the JSON and bumping the tag in that folder's `README.md`.
+
 ### Frontend component tests — `@decky/api` event harness
 
 `src/test-utils/decky-api-mock.ts` exposes an in-memory event bus that `addEventListener` / `removeEventListener` route

docs/contributing/development.md

@@ -124,6 +124,39 @@ python -m pytest tests/domain/test_sync_action_gavel_vectors.py tests/domain/tes
 Updating the vectors means deliberately re-copying the JSON from the matching upstream `vectors/<family>/` directory and
 bumping the commit reference in `tests/domain/gavel_vectors/README.md`; never edit a vector to match the kernel.
 
+### emu-atlas conformance vectors
+
+The config-aware emulator knowledge — where a RetroArch / RetroDECK install keeps its saves — is likewise published as a
+standalone library, [emu-atlas](https://github.com/danielcopper/emu-atlas), extracted from this plugin. Its `machines`
+vector family (16 fixture machines in, detected installations + save placements out) runs against the plugin's own
+save-path kernel in `tests/test_atlas_machine_vectors.py`, so the two can't silently drift. Each vector materializes a
+`{path: content}` file tree under a `tmp_path` fake home, then drives the real adapters (`RetroDeckPathsAdapter` +
+`RetroArchConfigAdapter`) and the domain save-path functions (`resolve_save_dir` / `compute_local_save_target`).
+
+The overlap is partial, so every vector carries an explicit check level (an `_CHECK_LEVELS` allowlist entry that also
+records _why_):
+
+- **`full`** — end-to-end placement. The plugin derives the saves root the same way atlas does (from `retrodeck.json`,
+  or the `~/retrodeck` fallback), so the final directory + filename strings are compared. Covers the RetroDECK-flavor
+  `InSaveDir` cases and the RetroDECK-first coexistence case.
+- **`layout-only`** — only the `retroarch.cfg` interpretation overlaps. The plugin has no standalone-RetroArch
+  saves-root concept (its saves base always comes from RetroDECK paths), so a vector whose placement hangs off a
+  standalone `savefile_directory` is checked on the `SaveLayout` the plugin derives from the same cfg text — the sort
+  flags for an `InSaveDir` placement, or the `ContentDir` (next-to-ROM) classification.
+- **`n/a`** — no overlap (the plugin has no installation-enumeration surface, so atlas's "nothing detected" outcome has
+  no plugin equivalent). The check only guards that the vector stays in its non-checkable shape.
+
+No vector is silently skipped: a new upstream vector without an allowlist entry (or a stale entry for a removed one)
+fails at collection. The vectors are vendored verbatim under `tests/atlas_vectors/machines/` at a pinned upstream
+release tag — no submodule, no network in CI. Run it like any other test:
+
+```bash
+python -m pytest tests/test_atlas_machine_vectors.py -q
+```
+
+Updating means deliberately re-copying the JSON from upstream `vectors/machines/` and bumping the release tag in
+`tests/atlas_vectors/README.md`; never edit a vector to match the kernel.
+
 Every backend feature or callable where testing makes sense should have unit tests covering:
 
 - **Happy path** — normal successful operation

tests/atlas_vectors/README.md

@@ -0,0 +1,20 @@
+# emu-atlas conformance vectors — vendored
+
+These JSON files are vendored verbatim from [danielcopper/emu-atlas](https://github.com/danielcopper/emu-atlas)
+`vectors/machines/`, at release tag `v0.1.0`. The layout mirrors upstream — one subdirectory per vector family:
+
+- `machines/` — fixture machines in, detected installations + save placements out, run by
+  `tests/test_atlas_machine_vectors.py`.
+  - `named-cases.json` — the 16 curated machine vectors (each carries a `rationale`).
+
+emu-atlas is the config-aware emulator-knowledge library extracted from this plugin; its machine vectors are the
+normative contract for where RetroArch/RetroDECK installs keep saves, and the save-placement expectations are
+oracle-derived from this repo's `domain/save_path.resolve_save_dir` / `compute_local_save_target`. The test proves the
+plugin's own kernel still agrees with the published contract where the two overlap.
+
+## Updating
+
+There is no submodule and no network access in CI — a vector change must surface as a reviewable diff in this repo.
+Updating means deliberately re-copying the files from the matching upstream `vectors/<family>/` directory and bumping
+the release tag above. Do not reformat the copied files; they must stay byte-for-byte identical to upstream. Never edit
+a vector to make the kernel pass — a genuine divergence is a finding to triage, not a vector to rewrite.