feat(domain): save sync v2 domain logic (#183) (#189)

Add four pure domain modules for save sync v2:

- save_sync: unified sync action logic with v4.7 device sync
  awareness (is_current) and v4.6 fallback
- save_path: RetroArch save directory layout resolution
  (sort_by_content, sort_by_core)
- emulator_tag: RomM emulator tag construction from core names
- save_extensions: per-platform save file extension configuration

60 new tests, all pure functions with no I/O.

Author: danielcopper

py_modules/domain/emulator_tag.py

@@ -0,0 +1,66 @@
+"""Emulator tag construction for RomM save uploads.
+
+The emulator tag determines the server-side folder path for saves:
+saves/{system}/{rom_id}/{emulator}/
+
+Format: retroarch-{core} where core is the libretro core name
+without the _libretro suffix, lowercased.
+
+No I/O, no service/adapter/lib imports. Pure functions only.
+"""
+
+from __future__ import annotations
+
+_LIBRETRO_SUFFIX = "_libretro"
+_FALLBACK = "retroarch"
+
+
+def build_emulator_tag(core_so: str | None) -> str:
+    """Build a RomM emulator tag from a RetroArch core .so name.
+
+    Parameters
+    ----------
+    core_so:
+        The libretro core name as found in ES-DE config, e.g. "mgba_libretro",
+        "snes9x_libretro", "swanstation_libretro".
+        May be None if core resolution failed.
+
+    Returns
+    -------
+    str
+        Emulator tag string, e.g. "retroarch-mgba", "retroarch-snes9x".
+        Returns "retroarch" as fallback when core_so is None or empty.
+
+    Rules:
+    - Strip "_libretro" suffix
+    - Lowercase
+    - Prepend "retroarch-"
+    - Fallback to "retroarch" if core_so is None/empty
+    """
+    if not core_so:
+        return _FALLBACK
+    core = core_so.lower()
+    if core.endswith(_LIBRETRO_SUFFIX):
+        core = core[: -len(_LIBRETRO_SUFFIX)]
+    return f"retroarch-{core}"
+
+
+def detect_core_change(stored_core: str | None, active_core: str | None) -> bool:
+    """Detect if the active RetroArch core has changed since last sync.
+
+    Parameters
+    ----------
+    stored_core:
+        The core_so name recorded at last sync, or None if never synced.
+    active_core:
+        The currently active core_so name, or None if unresolved.
+
+    Returns
+    -------
+    bool
+        True if the cores differ and both are non-None (actual change).
+        False if either is None (can't determine) or they match.
+    """
+    if stored_core is None or active_core is None:
+        return False
+    return stored_core != active_core

py_modules/domain/save_extensions.py

@@ -0,0 +1,60 @@
+"""Per-platform save file extension configuration.
+
+Provides the list of save file extensions to look for when syncing saves.
+The default covers RetroArch's standard .srm and .rtc extensions.
+Platform-specific overrides can expand or replace this list.
+
+Extension expansion (adding .sav, .mcr, .mcd, etc.) is tracked in #186.
+
+No I/O, no service/adapter/lib imports. Pure functions only.
+"""
+
+from __future__ import annotations
+
+_DEFAULT_EXTENSIONS: tuple[str, ...] = (".srm", ".rtc")
+
+# Platform-specific overrides. Keys are RomM platform slugs.
+# Values completely replace the default list for that platform.
+# Populated incrementally as gameplay tests confirm actual extensions.
+_PLATFORM_OVERRIDES: dict[str, tuple[str, ...]] = {
+    # Example (to be filled in #186):
+    # "n64": (".srm", ".rtc", ".eep", ".sra", ".fla", ".mpk"),
+}
+
+
+def get_save_extensions(platform_slug: str | None = None) -> tuple[str, ...]:
+    """Return the save file extensions to search for a given platform.
+
+    Parameters
+    ----------
+    platform_slug:
+        RomM platform slug (e.g. "gba", "n64", "psx").
+        If None or not in overrides, returns the default extensions.
+
+    Returns
+    -------
+    tuple[str, ...]
+        Tuple of file extensions including the leading dot (e.g. (".srm", ".rtc")).
+    """
+    if platform_slug is not None and platform_slug in _PLATFORM_OVERRIDES:
+        return _PLATFORM_OVERRIDES[platform_slug]
+    return _DEFAULT_EXTENSIONS
+
+
+def get_all_known_extensions() -> tuple[str, ...]:
+    """Return all unique extensions across defaults and all platform overrides.
+
+    Useful for broad file discovery or migration tooling.
+    """
+    seen: set[str] = set()
+    result: list[str] = []
+    for ext in _DEFAULT_EXTENSIONS:
+        if ext not in seen:
+            seen.add(ext)
+            result.append(ext)
+    for exts in _PLATFORM_OVERRIDES.values():
+        for ext in exts:
+            if ext not in seen:
+                seen.add(ext)
+                result.append(ext)
+    return tuple(result)

py_modules/domain/save_path.py

@@ -0,0 +1,83 @@
+"""Save file path resolution for RetroArch save directory layouts.
+
+Handles the various save directory structures created by RetroArch's
+sort_savefiles_by_content_enable and sort_savefiles_enable settings.
+
+No I/O, no service/adapter/lib imports. Pure functions only.
+"""
+
+from __future__ import annotations
+
+import os
+
+
+def resolve_save_dir(
+    rom_path: str,
+    saves_base: str,
+    system: str,
+    *,
+    sort_by_content: bool = True,
+    sort_by_core: bool = False,
+    core_name: str | None = None,
+) -> str:
+    """Resolve the save directory for a ROM.
+
+    Parameters
+    ----------
+    rom_path:
+        Relative ROM file path as stored in RomM (e.g. "gba/Game.gba" or
+        "psx/Game (USA)/Game.m3u").
+    saves_base:
+        Absolute path to the RetroArch saves root directory.
+    system:
+        Platform/system slug (e.g. "gba", "psx"). Used as fallback subdir.
+    sort_by_content:
+        If True, save subdir = last folder component of rom_path.
+        RetroDECK default: True.
+    sort_by_core:
+        If True, adds a core name subfolder inside the content dir.
+        RetroDECK default: False. Requires core_name.
+    core_name:
+        RetroArch core name (e.g. "mgba_libretro"). Required when sort_by_core=True.
+
+    Returns
+    -------
+    str
+        Absolute path to the directory where save files should be found/placed.
+    """
+    parts: list[str] = [saves_base]
+
+    if sort_by_content:
+        # Last folder component of the rom_path (i.e. the directory containing the ROM file)
+        rom_dir = os.path.dirname(rom_path)
+        content_dir = os.path.basename(rom_dir) if rom_dir else system
+        parts.append(content_dir)
+
+    if sort_by_core and core_name:
+        parts.append(core_name)
+
+    return os.path.join(*parts)
+
+
+def resolve_save_filename(rom_path: str, ext: str = ".srm") -> str:
+    """Derive the save filename from a ROM path.
+
+    Takes the ROM's basename, strips extension, appends save extension.
+    E.g. "gba/Pokemon.gba" -> "Pokemon.srm"
+    """
+    basename = os.path.basename(rom_path)
+    name, _ = os.path.splitext(basename)
+    return name + ext
+
+
+def detect_path_change(stored_path: str | None, resolved_path: str) -> bool:
+    """Detect if the save path has changed since last sync.
+
+    Useful for warning users when RetroArch settings change (e.g.
+    sort_by_content toggled) which would move where saves are expected.
+
+    Returns True if paths differ (or stored_path is None -- first sync).
+    """
+    if stored_path is None:
+        return True
+    return stored_path != resolved_path

py_modules/domain/save_sync.py

@@ -0,0 +1,85 @@
+"""Unified sync-action logic for save sync v2.
+
+Extends the existing conflict detection (save_conflicts.py) with
+RomM v4.7 device sync awareness (is_current flag from device_syncs).
+
+No I/O, no service/adapter/lib imports. Pure functions only.
+"""
+
+from __future__ import annotations
+
+from domain.save_conflicts import check_server_changes_fast, determine_action
+
+
+def check_server_changed_v47(device_sync_info: dict | None) -> bool | None:
+    """Check server change using v4.7 device_syncs info.
+
+    Parameters
+    ----------
+    device_sync_info:
+        A single device sync record from the server's device_syncs array,
+        or None if not available (v4.6 / no device registered).
+
+    Returns
+    -------
+    bool | None
+        True if server changed (is_current == False),
+        False if server unchanged (is_current == True),
+        None if indeterminate (no device_sync_info provided, or is_current is
+        absent/None).
+    """
+    if device_sync_info is None:
+        return None
+    is_current = device_sync_info.get("is_current")
+    if is_current is None:
+        return None
+    return not is_current
+
+
+def determine_sync_action(
+    local_changed: bool,
+    server_save: dict | None,
+    device_sync_info: dict | None = None,
+    file_state: dict | None = None,
+) -> str:
+    """Determine the sync action combining local and server change detection.
+
+    Parameters
+    ----------
+    local_changed:
+        Whether the local file has changed since last sync (caller computes this).
+    server_save:
+        Server save metadata dict, or None if no server save exists.
+    device_sync_info:
+        v4.7 device sync record (has "is_current" key), or None for v4.6 fallback.
+    file_state:
+        Per-file sync state dict (used for v4.6 fallback via check_server_changes_fast).
+        Only needed when device_sync_info is None.
+
+    Returns
+    -------
+    str
+        One of "skip", "upload", "download", "conflict", "initial_upload",
+        "initial_download".
+    """
+    # No server save at all
+    if server_save is None:
+        return "initial_upload" if local_changed else "skip"
+
+    # Server save exists — determine whether server has changed
+    server_changed: bool
+
+    # Priority 1: v4.7 device_sync_info
+    v47_result = check_server_changed_v47(device_sync_info)
+    if v47_result is not None:
+        server_changed = v47_result
+    else:
+        # Priority 2: v4.6 fast-path using file_state
+        if file_state is not None:
+            v46_result = check_server_changes_fast(file_state, server_save)
+            server_changed = v46_result if v46_result is not None else True
+        else:
+            # Priority 3: no info at all — safe default: assume server changed
+            server_changed = True
+
+    return determine_action(local_changed, server_changed)

tests/test_emulator_tag.py

@@ -0,0 +1,57 @@
+"""Unit tests for domain.emulator_tag — pure emulator tag construction functions."""
+
+from __future__ import annotations
+
+from domain.emulator_tag import build_emulator_tag, detect_core_change
+
+# ---------------------------------------------------------------------------
+# TestBuildEmulatorTag
+# ---------------------------------------------------------------------------
+
+
+class TestBuildEmulatorTag:
+    def test_normal_core_strips_libretro_suffix(self):
+        assert build_emulator_tag("mgba_libretro") == "retroarch-mgba"
+
+    def test_core_with_digits_strips_libretro_suffix(self):
+        assert build_emulator_tag("snes9x_libretro") == "retroarch-snes9x"
+
+    def test_swanstation_core(self):
+        assert build_emulator_tag("swanstation_libretro") == "retroarch-swanstation"
+
+    def test_none_input_returns_fallback(self):
+        assert build_emulator_tag(None) == "retroarch"
+
+    def test_empty_string_returns_fallback(self):
+        assert build_emulator_tag("") == "retroarch"
+
+    def test_core_without_libretro_suffix_passes_through(self):
+        # Shouldn't happen in practice but must not crash
+        assert build_emulator_tag("mgba") == "retroarch-mgba"
+
+    def test_uppercase_core_is_lowercased(self):
+        assert build_emulator_tag("MGBA_libretro") == "retroarch-mgba"
+
+
+# ---------------------------------------------------------------------------
+# TestDetectCoreChange
+# ---------------------------------------------------------------------------
+
+
+class TestDetectCoreChange:
+    def test_same_core_returns_false(self):
+        assert detect_core_change("mgba_libretro", "mgba_libretro") is False
+
+    def test_different_cores_returns_true(self):
+        assert detect_core_change("mgba_libretro", "snes9x_libretro") is True
+
+    def test_stored_none_returns_false(self):
+        # First sync — no prior core recorded, can't determine change
+        assert detect_core_change(None, "mgba_libretro") is False
+
+    def test_active_none_returns_false(self):
+        # Core unresolved — can't determine change
+        assert detect_core_change("mgba_libretro", None) is False
+
+    def test_both_none_returns_false(self):
+        assert detect_core_change(None, None) is False