feat(library): count linked editions once in pile and stats

All game counts read the counted_user_game view, which keeps only the
most advanced edition of a linked set (older edition wins a tie). Add
the hideDuplicates filter to the library query.

readme.md

@@ -53,7 +53,9 @@ To Be Played is split into three repositories:
   and moods; moon trips (Apollo 11, 195.3 h), longest day, share under one hour; finished games per year (from the
   status history); games and playtime per platform (`PLATFORMS`: Steam games as "Steam", manual games by platform, trimmed and ignoring case, the most used spelling is the label); the Pile of Shame trend (90 days of `backlog_snapshot`, plus "this month: added / done", where the
   first sync of a Steam account is no "added", see `user_steam_sync.history_since`). Every number counts only listed games (still owned, not hidden: the view
-  `listed_user_game`, V24).
+  `listed_user_game`, V24). A linked set (see "Editions of one game") counts once: its most advanced edition (status, then
+  playtime, then the older `first_seen_at`; `counted_user_game`, V28), so the set is on the pile only when every owned edition is `BACKLOG`. Playtime
+  sums, most played, genres, moods and platforms still use every listed game.
 - **Status history**: a database trigger logs every status change of a library game in `user_game_status_change`
   (old and new status, time, whether the user chose it), whatever code path made it. It starts with V14; older
   changes are not known.
@@ -80,7 +82,7 @@ To Be Played is split into three repositories:
 - **Time to beat**: story, extras and completionist hours from the IGDB API. Optional: without credentials the
   feature is off and the rest works.
 - **Public profile data**: totals, status counts, games in progress and finished games with rating, perfect games
-  and average completion. Readable only
+  and average completion (the numbers count a linked set once; the lists keep every edition). Readable only
   with a profile ticket issued by Auth. Never returns notes, priority or the Steam ID. `stats` holds only the stat
   groups the user shares (the ticket's `profileStats` claim, derived in Auth from the profile tiles); none by
   default. A section the user
@@ -131,7 +133,7 @@ ArchUnit role rules (`RoleAnnotationRules`) and `src/test/resources/contract/aut
 | `GET` | `/api/rewards/wallet` (balance, catalog, owned, equipped, last 50 ledger rows with the game name) | JWT |
 | `POST` | `/api/rewards/purchases` (`{item}`; `200` wallet, `409 ALREADY_OWNED` / `NOT_ENOUGH_POINTS`) | JWT |
 | `PUT` | `/api/rewards/equipped/{slot}` (`{item}`, null = take off; `200` wallet, `409 NOT_OWNED`, `400 WRONG_SLOT`) | JWT |
-| `GET` | `/api/library/games`, `/api/library/games/{appid}` | JWT |
+| `GET` | `/api/library/games` (`hideDuplicates=true` leaves out the lesser editions of a linked set), `/api/library/games/{appid}` | JWT |
 | `PATCH` | `/api/library/games/{appid}/backlog` (only the sent fields; `null` clears one) | JWT |
 | `PUT`, `DELETE` | `/api/library/games/{appid}/corrections/{field}` (`{value}`; `name`, `image`, `speedrun`, `moods`, `endless`, `genres`; `204`, `400 INVALID_CORRECTION`) | JWT, AUDITOR |
 | `POST` | `/api/library/games/{appid}/merge` (`{otherAppid}`; `200 {appid}` = the key that stays, `400 SAME_GAME` / `STEAM_GAMES`, `404 GAME_NOT_FOUND`) | JWT, AUDITOR |
@@ -204,7 +206,7 @@ flowchart LR
     Igdb -->|"OAuth token"| Twitch["Twitch"]
     Speedrun --> SpeedrunApi["speedrun.com API"]
     LibRepo --> Db[("PostgreSQL tbp_core")]
-    Stats -->|"listed_user_game, game_mood, user_game_status_change, deleted_user, blocked_user"| Db
+    Stats -->|"listed_user_game, counted_user_game, game_mood, user_game_status_change, deleted_user, blocked_user"| Db
     Auth -->|"service token<br/>/internal/accounts"| Account
     Account -->|"per-user rows, deleted_user, blocked_user, user_seen_at"| Db
 ```
@@ -220,12 +222,14 @@ flowchart LR
 | `speedrun_adapter` | speedrun.com client: game search by name, verified runs |
 
 **One shared schema.** All modules use one database `tbp_core`, and some read or write another module's tables in
-SQL, which ArchUnit cannot see: `stats` reads `listed_user_game`, `steam_game`, `game_mood`, `user_game_status_change`, `deleted_user` and `blocked_user`; `account`
+SQL, which ArchUnit cannot see: `stats` reads `listed_user_game`, `counted_user_game`, `steam_game`, `game_mood`, `user_game_status_change`, `deleted_user` and `blocked_user`; `account`
 deletes the per-user rows of the library tables (`AccountCleanupRepository`; a new library table with `user_id` goes
 into its list) and writes `user_seen_at` and `last_synced_at` of `user_steam_sync` (`AccountStateRepository`); `library`
 reads `deleted_user` and `blocked_user`. A module that moves to its own service takes these reads along as calls.
 The listed rule ("still owned, not hidden") is `UserGameRepository.LISTED` for JPQL and the view
-`listed_user_game` for native SQL; V24 says what a migration of `user_game` must do with the view.
+`listed_user_game` for native SQL; V24 says what a migration of `user_game` must do with the view. The numbers that
+count games once per linked set read `counted_user_game` (V28), built on `listed_user_game`: a migration that changes
+a column of `user_game` drops this view first, then `listed_user_game`.
 
 Inside a module: `api` (controllers, DTOs), `service` (business logic), `domain` (JPA entities) and `repo`
 (repositories). `src/test/java/core_service/architecture/ArchitectureTest.java` checks these rules on every build:
@@ -348,6 +352,9 @@ IGDB id; remakes (8) keep their own id. `null` when IGDB does not know the game.
   read; a row in any state keeps the pair out for good. An unlink dismisses the pairs of that key with the former
   members. `game_link_request` holds who asked for a pair (the queue shows only the count). A user asks for a pair of
   two games of their own library; at most 20 open requests per user (a per-user advisory lock makes the cap hold for parallel calls), a dismissed pair answers `409 PAIR_DISMISSED`.
+- Pile, stats, snapshots and the dashboard count a set once (`counted_user_game`, see "Stats"); the library
+  filter `hideDuplicates=true` hides the lesser editions. Pile Points are unchanged: `STARTED` and `FINISHED` stay per row,
+  and the `MONTH` bonus reads `backlog_snapshot`, which counts a set once.
 - The game detail has `linked` and `editions` (the user's other listed games of the set); a game row has `editions`
   (size of the set in the user's library, `null` below 2).