fix(version-picker): disable versions missing from RomM (#1575)

## What this is

PR 3 of #1570. Retained local ROM rows no longer masquerade as live,
selectable versions after RomM drops their ids. Availability is
recomputed whenever the Game Page lazily loads the version list; it is
never persisted.

## What changed

- The bound ROM detail request establishes whether the active id is
still available and supplies RomM's direct sibling view.
- Local members absent from that direct view are confirmed concurrently
through exact-id, single-attempt `get_rom` probes. If the bound id
itself returns 404, every other local member is probed individually.
- Only `RommNotFoundError` marks a version `vanished`; every non-404
failure fails open.
- Vanished rows remain visible with their local state, but are dimmed,
labelled `No longer available on RomM`, disabled, and excluded from
Default ranking.
- `vanished` remains separate from `switchable`, preserving
sibling-group membership semantics.
- A bound 404 returns `bound_vanished: true` without reporting RomM
offline or updating the global connection state.
- `SavesTab` excludes vanished versions from its stranded-save advice
while continuing to inspect live inactive installs.
- The deferred artwork cleanup now reports a missing/falsy ROM as
`not_found` instead of `server_unreachable`; artwork remains data-only
and is not used as liveness evidence.

The version-switch commit guard and deletion/purge behavior remain in
PRs 4 and 5.

## Safety

Liveness probes use the existing three-second `request_once` path on the
executor fan-out, so they neither retry nor block the event loop. Direct
sibling presence is a positive server statement; absence alone never
proves disappearance because sibling groups can be transitive.

A restored database or visibility change can make the same id available
again. The next list load recomputes the result and removes `vanished`
automatically.

## Docs

Updated the backend and Steam-shortcut architecture pages plus the
managing-games and save-sync user guides. Frozen ADR history remains
unchanged.

## Verification

`mise run gate` passed on the final code state:

- 6334 backend tests
- 2244 frontend tests
- Ruff and basedpyright clean
- TypeScript, ESLint, Prettier, Deno, build, size limit, import
contracts, and repository invariant checks passed

The subsequent documentation wording correction passed focused Markdown
formatting, link, whitespace, backend, frontend, and 404-classification
checks. Final review found no remaining issues.

## On-device verification

Open a Game Page whose shortcut is bound to a RomM id that was removed
while a replacement version remains in the local sibling group. The page
should render without waiting for liveness probes; the removed version
should remain visible but disabled, the live replacement should remain
selectable, and RomM must not be reported offline.

Closes part of #1570.

Author: danielcopper

docs/architecture/backend-architecture.md

@@ -127,6 +127,21 @@ the rest are single modules. A service over ~700 LOC is the decomposition signal
 | `connection.py`           | ConnectionService — connection test + RomM minimum-version gate + Client API Token lifecycle (mint/establish via credentials, validate/store a user-pasted token, or exchange a short-lived pairing code for a token — the latter two for OIDC accounts; host-bound to the minting origin; see [ConnectionService notes](#connectionservice-notes))                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `protocols/`              | Protocol interfaces grouped by concern (see [Protocol Interfaces](#protocol-interfaces))                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 
+#### Version-list liveness
+
+`VersionSwitchService.get_version_list` separates retained local membership from current RomM availability. On each lazy
+Game Page load, the bound detail request proves the bound id live and supplies the direct sibling ids; only non-bound
+local members absent from that direct sibling view are exact-id probed through `RommRomReader.get_rom_once`, the
+adapter's single-attempt short-timeout `request_once` path, concurrently on the existing executor fan-out. Only
+`RommNotFoundError` produces `vanished: true`. All other probe failures and malformed/falsy responses fail open. No
+result is persisted.
+
+The response carries `vanished` on every version and `bound_vanished` even when `multi_version` is false. Retained
+vanished rows remain in the payload and keep the independently-computed `switchable` membership verdict, but are
+excluded from default ranking. A bound-id 404 is a successful entity verdict (`bound_vanished: true`,
+`server_query_failed: false`), not a global reachability signal. Artwork and save reads do not contribute availability
+evidence; `fetch_cover_base64` remains a nullable data callable.
+
 #### LibraryService decomposition (`services/library/`)
 
 The library sync subsystem is a façade over three sub-services that coordinate through a shared `LibrarySyncStateBox`:

docs/architecture/steam-non-steam-shortcuts.md

@@ -125,6 +125,32 @@ Two guards keep a re-import from wiping a freshly-bound shortcut (`#1036`):
   the run just re-bound onto the new `rom_id` is never emitted for removal. The `get_by_app_id` reverse lookup orders
   `rom_id DESC LIMIT 1` so it resolves the live (newest) binding for any pre-migration edge state.
 
+### Retained-row availability in the version picker
+
+ADR-0007 keeps a `roms` row after RomM stops returning that id because the row can anchor local-only saves, playtime,
+and an installed ROM. Retention does not imply that RomM still offers the row as a playable version. The Game Page's
+lazy `get_version_list` load therefore recomputes availability every time; there is no liveness column, migration,
+cache, or persisted verdict.
+
+The existing detail request for the bound id supplies its own answer and RomM's current direct `sibling_roms` view. The
+bound id and every local id positively present in that view are live. A local group member absent from the direct view
+is only a suspect because RomM sibling membership can be transitive, so each suspect is checked by an exact-id
+`get_rom_once` request. These checks fan out concurrently on the worker executor and use the short timeout with no
+retry, keeping them off the event loop and out of the initial Game Page render.
+
+Only a typed `RommNotFoundError` from an exact id marks that entry `vanished`. A successful response is live; timeout,
+transport, authentication, server errors, and malformed or empty data all fail open and leave it available. If the bound
+detail itself 404s, `bound_vanished` is true, `server_query_failed` stays false, and every other local member is checked
+individually. That entity-specific 404 is not fed into the global connection store; a genuine explicit
+server-unreachable result still is. Cover and save endpoints are not liveness authorities.
+
+Vanished rows stay visible with their active and downloaded markers, but are disabled and excluded before the existing
+default-resolution kernel runs. `vanished` does not change `switchable` or
+`domain.sibling_group.target_in_sibling_group`: availability and sibling membership remain separate verdicts. This lets
+a shortcut still bound to a vanished id show the retained context while the user selects a live alternative. The Saves
+tab likewise skips positively vanished inactive installs before checking local drift, then continues through later live
+candidates.
+
 ## Sync-start reconcile of Steam-UI-deleted shortcuts
 
 A user can delete a RomM shortcut through **Steam's own UI** (remove from library), which the plugin never observes. The

docs/user-guide/managing-games.md

@@ -54,6 +54,16 @@ a not-yet-synced version whose match conflicts, are both shown (so you know they
 either would move the shortcut onto a different game. To make one selectable, fix its metadata match in RomM so it
 agrees with this game's, then re-sync.
 
+A retained local version that RomM has positively confirmed it no longer has is also shown dimmed and disabled, with the
+separate label _"No longer available on RomM"_. Its **active** and **Downloaded** markers remain visible so it is clear
+what the shortcut and local files still refer to, but it never receives the **Default** badge. If the shortcut is still
+active on that unavailable id, choose any live alternative in the same list to recover the game.
+
+This availability check is fresh each time the version list loads and is not saved in the plugin database. Only a 404
+for that exact ROM id establishes that it is gone. Timeouts, sign-in/permission errors, server errors, and malformed
+responses fail open: the plugin does not disable a version merely because it could not get a trustworthy answer. A
+ROM-specific 404 also does not make the rest of the plugin report that RomM is offline.
+
 Selecting a different version **rebinds** the game to it: the Download button now fetches that version, the panel's
 title and Region/Languages rows update to reflect it, and its cover refreshes to the new version. The Steam shortcut
 keeps its name, its place in your collections, and its playtime — all tied to the shortcut, which never changes. A
@@ -71,7 +81,8 @@ switch. What happens depends on whether the version you're leaving is downloaded
   drops the sync option and offers only **Switch anyway** and **Cancel**, explaining why.
 
 When you leave a downloaded version with unsynced saves behind, the **Saves** tab shows a reminder banner ("switch back
-to sync them") so those saves aren't forgotten.
+to sync them") so those saves aren't forgotten. It does not recommend switching back to a version positively confirmed
+as no longer available on RomM; it skips that retained row and continues checking any later live versions.
 
 While a download of the game is running, switching is blocked with a short message — cancel the running download first.
 

docs/user-guide/save-sync.md

@@ -40,6 +40,11 @@ plugin warns you before you leave such a version and shows a reminder banner on
 forgotten (see [Managing Games → Versions](managing-games.md#versions)). Nothing is lost — the saves just don't sync
 while their version is inactive.
 
+The reminder never tells you to switch back to a retained version that the current version-list check positively
+confirmed is [no longer available on RomM](managing-games.md#the-switch-version-control). Such a row may still keep its
+local files and saves, but it cannot be selected; the Saves tab skips it and continues looking for drift on later live
+inactive versions.
+
 ## Important: Use Your Own RomM Account
 
 Save files in RomM are tied to the authenticated user account. If multiple people share the same RomM account, their

py_modules/adapters/romm/http.py

@@ -348,10 +348,9 @@ def request_once(self, path: str, *, timeout: int):
         """GET a JSON resource in a SINGLE attempt with a SHORT *timeout*.
 
         Deliberately bypasses :meth:`with_retry` and the 30s urlopen timeout used
-        by :meth:`request`. The launch-gate reachability probe needs a fast
-        offline verdict (~3s, one shot) instead of waiting through 3 retry
-        attempts and up to ~90s of accumulated remote timeouts. The real sync
-        paths keep the retrying :meth:`request`.
+        by :meth:`request`. Point probes need a fast verdict (~3s, one shot)
+        instead of waiting through 3 retry attempts and up to ~90s of accumulated
+        remote timeouts. The real sync paths keep the retrying :meth:`request`.
         """
         return self._build_get(path, timeout=timeout)()
 

py_modules/adapters/romm/romm_api.py

@@ -101,9 +101,8 @@ def get_version(self) -> str | None:
 
     # ── Server / Auth ─────────────────────────────────────────────────
 
-    # Fast-fail reachability probe: a single ~3s attempt, no retry. Keeps the
-    # launch gate's "offline" verdict snappy instead of waiting through the
-    # retrying heartbeat (3 attempts + up to ~90s of accumulated timeouts).
+    # Fast-fail point probes: a single ~3s attempt, no retry. Keeps verdicts
+    # snappy instead of waiting through 3 attempts and accumulated timeouts.
     _PROBE_TIMEOUT_SECONDS = 3
 
     def heartbeat(self) -> dict[str, Any]:
@@ -130,6 +129,10 @@ def get_current_user(self) -> dict[str, Any]:
     def get_rom(self, rom_id: int) -> dict[str, Any]:
         return self._client.request(f"/api/roms/{rom_id}")
 
+    def get_rom_once(self, rom_id: int) -> dict[str, Any]:
+        """Single-attempt, short-timeout exact-ROM read for liveness probes."""
+        return self._client.request_once(f"/api/roms/{rom_id}", timeout=self._PROBE_TIMEOUT_SECONDS)
+
     def list_roms(self, platform_id: int, limit: int = LIST_PAGE_SIZE, offset: int = 0) -> dict[str, Any]:
         return self._client.request(
             f"/api/roms?platform_ids={platform_id}&limit={limit}&offset={offset}{_LIST_AGGREGATIONS_DISABLED}"

py_modules/services/artwork.py

@@ -835,7 +835,7 @@ async def refresh_cover(self, rom_id: int) -> dict[str, Any]:
         if not rom:
             return {
                 "success": False,
-                "reason": ErrorCode.SERVER_UNREACHABLE.value,
+                "reason": ErrorCode.NOT_FOUND.value,
                 "message": "Could not fetch ROM from server",
             }
 

py_modules/services/protocols/transport.py

@@ -145,6 +145,10 @@ def get_rom(self, rom_id: int) -> dict[str, Any]:
         """
         ...
 
+    def get_rom_once(self, rom_id: int) -> dict[str, Any]:
+        """Fetch a single ROM by ID once with the short probe timeout."""
+        ...
+
     def list_roms(self, platform_id: int, limit: int = LIST_PAGE_SIZE, offset: int = 0) -> dict[str, Any]:
         """List ROMs for a platform with pagination.