fix(sync): union same-named collections instead of overwriting in finalize (#1533)

Two enabled collections sharing a display name overwrote each other's member set in the name-keyed finalize accumulator, so the single by-name Steam collection reflected only the last-synced one. Reachable on a single-user server (RomM has no cross-table name constraint, so a user and a smart/franchise collection can share a name) and wider on shared servers (list endpoints return own + public). The accumulator is re-keyed to a collision-free (collection_kind, collection_id) identity carrying the name, and the reporter unions same-named collections' resolved appIds when building the by-name Steam map — the frontend contract is byte-for-byte unchanged. No owner filter (a QAM own/all toggle is tracked as #1532). Side benefit: the #742 stamp now records each collection's own membership.

Closes #1503

Author: danielcopper

docs/architecture/backend-architecture.md

@@ -500,6 +500,20 @@ sibling row holding `shortcut_app_id` is the group's **active version**.
   to its group's bound sibling's appId — so collecting or favouriting any version puts the game's single shortcut in the
   collection.
 
+**Same-named collections union into one Steam collection (#1503).** RomM enforces name uniqueness only per-table and
+per-`(name, user_id)`, so two enabled collections can share a display name — a user collection and a smart/franchise
+collection, or (multi-user) another account's public collection the list endpoints return. Steam's collection namespace
+is **by-name** (`RomM: [<name>] (host)`), so both must resolve to the one Steam collection. The finalize accumulator
+(`_state.py` `pending_collection_memberships`) is therefore keyed by a collision-free `(collection_kind, collection_id)`
+identity — the same identity the #742 completion stamp uses — with the display name carried in the
+`CollectionMembership` value; the real-sync and preview write paths share one key builder so they cannot drift. The
+reporter (`_resolve_collection_memberships`) then groups the accumulator's entries by name and **unions** their resolved
+appId sets (order-preserving, de-duplicated across collections; each collection's own resolution already dedups within),
+emitting the unchanged by-name `romm_collection_app_ids: {name → [appId]}` contract — a single-collection name unions a
+set of one and is byte-for-byte the pre-#1503 output. The plugin **unions rather than owner-filters** here: RomM
+deliberately exposes public collections across accounts, so syncing them unfiltered is the established behaviour (an
+own/all QAM toggle is a separate concern).
+
 **Incremental skip — the per-platform completion stamp is the sole authority.** A platform unit skips only when its
 `PlatformSyncState` stamp exists
 ([ADR-0023](https://github.com/danielcopper/decky-romm-sync/blob/main/docs/adr/0023-chunked-per-unit-apply.md)); the

docs/user-guide/syncing-your-library.md

@@ -229,6 +229,11 @@ collections, or use the paired **Enable All** / **Disable All** buttons to bulk-
 **Show collection games in platform groups** toggle controls whether games pulled in via a collection also get added to
 their platform's Steam group.
 
+If two enabled collections share the same name — for example a personal collection and a smart or franchise collection
+called the same thing, or (on a shared server) another account's public collection — they **merge into a single Steam
+collection** carrying the combined set of games. RomM allows collections to share a name, but Steam identifies a
+collection by its name, so the plugin unions their members rather than dropping one.
+
 ## Artwork
 
 Each synced game gets up to five types of artwork:

py_modules/domain/sync_diff.py

@@ -270,16 +270,21 @@ def select_stale_removals(
 
 
 def compute_collection_diff(
-    collection_memberships: dict[str, list[int]],
+    current_collection_names: set[str],
     last_synced_collections: list[str],
 ) -> dict[str, Any]:
     """Diff enabled collections (by name) against the last-synced set.
 
-    Returns ``{"has_changes": bool, "added": [...], "removed": [...]}``.
-    ``has_changes`` is True if there are any added/removed collections, or
-    if there are any current collections at all (covers first-sync case).
+    ``current_collection_names`` is the set of DISTINCT display names present in
+    this run's collection accumulator — a name counts as present iff at least one
+    collection carries it, so two same-named collections (RomM permits them across
+    kinds/users, #1503) collapse to one entry, matching the by-name Steam
+    collection they merge into. Returns
+    ``{"has_changes": bool, "added": [...], "removed": [...]}``; ``has_changes`` is
+    True if there are any added/removed collections, or if there are any current
+    collections at all (covers first-sync case).
     """
-    current = set(collection_memberships.keys())
+    current = current_collection_names
     previous = set(last_synced_collections)
     added = sorted(current - previous)
     removed = sorted(previous - current)

py_modules/services/library/_state.py

@@ -42,6 +42,24 @@ def _default_progress() -> dict[str, Any]:
     }
 
 
+@dataclass(frozen=True)
+class CollectionMembership:
+    """One enabled collection's full member rom_ids, tagged with its display name.
+
+    The value type of :attr:`LibrarySyncStateBox.pending_collection_memberships`,
+    whose key is a collision-free ``(collection_kind, collection_id)`` identity so
+    two collections that merely SHARE a display name never overwrite each other's
+    members in the finalize accumulator. The name rides here in the value because
+    Steam's collection namespace is by-name: the reporter groups same-named
+    memberships and UNIONs their resolved appIds into the one
+    ``RomM: [<name>] (host)`` Steam collection (RomM permits same-named collections
+    across kinds/users, so the plugin merges rather than owner-filters, #1503).
+    """
+
+    name: str
+    rom_ids: list[int]
+
+
 @dataclass(frozen=True)
 class AbandonedChunk:
     """A heartbeat-timed-out apply chunk, stashed for a late-ack commit.
@@ -98,7 +116,13 @@ class LibrarySyncStateBox:
     # abandon window so a late ack still stamps the confirmed values.
     pending_cover_sources: dict[int, str] = field(default_factory=dict)
     pending_delta: PreviewDelta | None = None
-    pending_collection_memberships: dict[str, list[int]] = field(default_factory=dict)
+    # Per-run collection-membership accumulator, keyed by a collision-free
+    # ``(collection_kind, collection_id)`` identity (never the display name), so
+    # two collections that share a name each keep their own members. The name
+    # travels in the :class:`CollectionMembership` value; the reporter unions
+    # same-named memberships when it builds the by-name Steam-collection map
+    # (#1503).
+    pending_collection_memberships: dict[tuple[str, str], CollectionMembership] = field(default_factory=dict)
     pending_platform_rom_ids: set[int] | None = None
     # Per-unit pipeline coordination. ``unit_complete_event`` is set by
     # :meth:`SyncReporter.report_unit_results` when the frontend acks the

py_modules/services/library/reporter.py

@@ -37,7 +37,7 @@
     from domain.collection_sync_state import CollectionSyncState
     from domain.platform_sync_state import PlatformSyncState
     from domain.sync_run import SyncRun
-    from services.library._state import LibrarySyncStateBox
+    from services.library._state import CollectionMembership, LibrarySyncStateBox
     from services.protocols import (
         ArtworkManager,
         Clock,
@@ -117,7 +117,7 @@ def _build_collection_app_ids(
         self,
         uow: UnitOfWork,
         pending_platform_rom_ids: set[int] | None,
-        pending_collection_memberships: dict[str, list[int]],
+        pending_collection_memberships: dict[tuple[str, str], CollectionMembership],
         platform_names: dict[str, str],
     ) -> tuple[dict[str, list[int]], dict[str, list[int]]]:
         """Build platform_app_ids and romm_collection_app_ids from ``uow.roms``.
@@ -128,14 +128,17 @@ def _build_collection_app_ids(
         resolved from *platform_names* (the work-queue), falling back to
         the slug when absent.
 
-        RomM collections keep the per-run membership accumulator and resolve
-        each member ``rom_id`` to a Steam appId with a **sibling-group
-        fallback** (ADR-0021): a bound member uses its own binding; an unbound
-        member maps to its group's bound sibling's appId, so favouriting /
-        collecting ANY version of a game puts the game's single shortcut into
-        the Steam collection. Per-collection appIds are de-duplicated — several
-        siblings of one group collapse onto the one shortcut. The platform loop
-        still excludes rows whose ``shortcut_app_id`` is ``None``.
+        RomM collections keep the per-run membership accumulator (keyed by a
+        collision-free ``(collection_kind, collection_id)`` identity, name in the
+        value) and resolve each member ``rom_id`` to a Steam appId with a
+        **sibling-group fallback** (ADR-0021): a bound member uses its own
+        binding; an unbound member maps to its group's bound sibling's appId, so
+        favouriting / collecting ANY version of a game puts the game's single
+        shortcut into the Steam collection. Per-collection appIds are
+        de-duplicated — several siblings of one group collapse onto the one
+        shortcut — and same-named collections UNION into the one by-name Steam
+        collection (#1503). The platform loop still excludes rows whose
+        ``shortcut_app_id`` is ``None``.
         """
         platform_app_ids, group_bound_app_id = self._scan_bound_rows(uow, pending_platform_rom_ids, platform_names)
         romm_collection_app_ids = self._resolve_collection_memberships(
@@ -179,27 +182,33 @@ def _note_group_binding(group_bound: dict[str, tuple[int, int]], rom: Rom) -> No
     def _resolve_collection_memberships(
         self,
         uow: UnitOfWork,
-        pending_collection_memberships: dict[str, list[int]],
+        pending_collection_memberships: dict[tuple[str, str], CollectionMembership],
         group_bound_app_id: dict[str, int],
     ) -> dict[str, list[int]]:
-        """Resolve each collection's member rom_ids to de-duplicated appIds.
-
-        A bound member uses its own binding; an unbound member falls back to
-        its sibling group's bound appId (ADR-0021). Collections that resolve
-        to no appId are omitted.
+        """Resolve each collection's member rom_ids to de-duplicated appIds, UNION by name.
+
+        A bound member uses its own binding; an unbound member falls back to its
+        sibling group's bound appId (ADR-0021). Steam's collection namespace is
+        by-name, so same-named RomM collections (permitted across kinds/users,
+        #1503) merge into one entry: their resolved appIds are UNIONed,
+        order-preserving and de-duplicated ACROSS collections (each collection's
+        own resolution already dedups within). The accumulator is keyed by a
+        collision-free identity, so a same-named pair never overwrote either
+        member set upstream. Names that resolve to no appId are omitted; the
+        common single-collection case unions a set of one and is byte-for-byte
+        identical to the pre-#1503 output.
         """
         romm_collection_app_ids: dict[str, list[int]] = {}
-        for coll_name, rom_ids in pending_collection_memberships.items():
-            seen: set[int] = set()
-            app_ids: list[int] = []
-            for rid in rom_ids:
+        seen_by_name: dict[str, set[int]] = {}
+        for membership in pending_collection_memberships.values():
+            app_ids = romm_collection_app_ids.setdefault(membership.name, [])
+            seen = seen_by_name.setdefault(membership.name, set())
+            for rid in membership.rom_ids:
                 app_id = self._member_app_id(uow, rid, group_bound_app_id)
                 if app_id is not None and app_id not in seen:
                     seen.add(app_id)
                     app_ids.append(app_id)
-            if app_ids:
-                romm_collection_app_ids[coll_name] = app_ids
-        return romm_collection_app_ids
+        return {name: app_ids for name, app_ids in romm_collection_app_ids.items() if app_ids}
 
     @staticmethod
     def _member_app_id(uow: UnitOfWork, rid: int, group_bound_app_id: dict[str, int]) -> int | None:
@@ -217,7 +226,7 @@ def _member_app_id(uow: UnitOfWork, rid: int, group_bound_app_id: dict[str, int]
 
     def _finalize_per_unit_run_io(
         self,
-        pending_collection_memberships: dict[str, list[int]],
+        pending_collection_memberships: dict[tuple[str, str], CollectionMembership],
         pending_platform_rom_ids: set[int] | None,
         platform_names: dict[str, str],
         stale_rom_ids: list[int] | None = None,
@@ -263,7 +272,7 @@ def _finalize_per_unit_run_io(
 
     async def finalize_per_unit_run(
         self,
-        pending_collection_memberships: dict[str, list[int]],
+        pending_collection_memberships: dict[tuple[str, str], CollectionMembership],
         pending_platform_rom_ids: set[int] | None,
         platform_names: dict[str, str] | None = None,
         stale_rom_ids: list[int] | None = None,

py_modules/services/library/service.py

@@ -18,7 +18,7 @@
 from typing import TYPE_CHECKING, Any
 
 from lib.late_binding import LateBinding
-from services.library._state import LibrarySyncStateBox
+from services.library._state import CollectionMembership, LibrarySyncStateBox
 from services.library.fetcher import LibraryFetcher, LibraryFetcherConfig
 from services.library.reporter import SyncReporter, SyncReporterConfig
 from services.library.sync_orchestrator import SyncOrchestrator, SyncOrchestratorConfig
@@ -228,11 +228,11 @@ def _pending_delta(self, value: PreviewDelta | None) -> None:
         self._box.pending_delta = value
 
     @property
-    def _pending_collection_memberships(self) -> dict[str, list[int]]:
+    def _pending_collection_memberships(self) -> dict[tuple[str, str], CollectionMembership]:
         return self._box.pending_collection_memberships
 
     @_pending_collection_memberships.setter
-    def _pending_collection_memberships(self, value: dict[str, list[int]]) -> None:
+    def _pending_collection_memberships(self, value: dict[tuple[str, str], CollectionMembership]) -> None:
         self._box.pending_collection_memberships = value
 
     @property