[arun279]

Problem

Trakt allows 500 GETs per user per 5 minutes (https://developer.trakt.tv/docs/rate-limiting), and the Trakt fake in packages/core/test/trakt-fake/ enforces it. The heavy-library replay in packages/core/test/harness/scenario-budget.test.tsx measured:

Scenario	GETs	429s
Sign-in and first sync	794	2
Cold launch, cache older than an hour	701	5
Warm launch, fresh cache	569	4

Each 429 pauses every read for Trakt's Retry-After, which is how large libraries ended up with multi-minute stalls. On top of that, the first sync read every watchlist-shows page twice, hidden/dropped three times and last_activities twice, and two screens asking for the browse rails while Trakt was slow cost 6 GETs instead of 4.

Root causes

1. Season trees read for shows with nothing new. lastAiredKey in packages/core/src/data/trakt/library.ts took a show's last aired episode from the last episode the user watched whenever the show was past the 60-show progress budget. For a show with episodes still to watch, that frontier is behind the real one. reconcileRecentlyAired (domain/recently-aired.ts) then counted calendar episodes Trakt had already counted, needsNextEpisode flagged the show, and useLibrarySnapshot read its season tree through loadShowSeasons: two GETs per show (/shows/:id/seasons and /shows/:id/progress/watched with specials). In the heavy library that was 282 shows, so 564 GETs on every launch.
2. The warm launch re-read every tree. createQueryCachePolicy in runtime/query-cache.ts persisted only a library show's art, never its season tree. A launch with a fresh persisted cache and unchanged activities still read all the trees again.
3. Hidden and dropped read three times. loadCalendar in app/create-runtime.ts read both lists for each of the two calendar windows, on top of the library's own read in read-budget.ts. Stopping a show in the app also invalidated both calendars, which read them again.
4. Watchlist shows read twice. useWatchlistAdd mounted a watchlist query, key ["watchlist", "shows"], over the same /sync/watchlist/shows URL the library reads under ["library"]. The keys differ, so TanStack Query could not dedupe them.
5. last_activities read twice. The second read was the 60-second interval poll firing while every read waited out a 429 pause. It goes away with the 429s.
6. Browse rails cost 6. TraktClient.get joined identical GETs only once a request had been sent. Pooled reads (pooled-endpoints.ts) first wait for one of six slots in withReadRateRetry. The second screen's reads still queued for a slot found the first ones finished and sent their own.
7. The 429s. The tree fan-out plus queue art came to about 690 reads in one burst. The six-slot pool limits how many reads run at once, not how many are sent per window.

Fixes

• Aired frontier. Without a progress read, a show's aired frontier is now the last watched episode only if nothing is left to watch, and null otherwise. The reconcile already leaves a null frontier alone. Caught-up shows keep their frontier, so a new season of a finished show is still found and placed. Only those shows get a season tree now.
• Season trees. A library show's season tree is persisted while a screen uses it: Up Next placing a card, or an open detail screen. A tree from a detail visit drops out of the persisted cache once the screen closes. Trees keep their one-hour content stale time.
• Watched state from other devices. A change to watched history, progress or hidden shows in last_activities now invalidates every show's progress, season tree and episode queries (data/query-invalidation.ts). Each of these merges the user's per-episode watched state, so a tree kept across launches can no longer show an episode watched on another device as unwatched. Only the trees on screen are read again.
• Calendar filtering.
  • The calendar read returns only episodes. The Calendar tab, Up Next's coming-up list, reminders and the recently-aired reconcile filter by the library's hidden flags.
  • useCalendarFocus owns the played and hidden sets. The Calendar stays on its loading plates until the library answers, whatever the "every watchlist episode" setting is. If the library read fails, the Calendar shows every row unfiltered, as it already did for played shows.
  • Stopping a show no longer invalidates the calendars. A show stopped on another device now leaves the calendar when the library reloads, not when the calendar cache next expires.
• Watchlist. Search's watchlist membership for shows comes from the library, which holds every watchlisted show. The watchlist query, its runtime loader (loadMovieWatchlistIds) and Search's add and remove paths now handle movies only, because the movie library loads only with the Library tab's Movies segment.
• Read sharing. Identical pooled reads share one promise from the moment they are asked for. This replaces the client's in-flight map.
• Cache buster. The persisted cache buster is bumped, since the calendar data lost its hidden ids.

Behaviour changes to know about

• Backlog shows past the progress budget. Before, a show past the 60-show budget that still had episodes to watch got a season tree, and so an Up Next card, only if one of its episodes happened to air in the last 33 days. Now every such show is treated the same: it keeps Trakt's bulk counts, counts toward Library's episodes left, and stays out of Up Next until it is among the 60 most recently watched. The same goes for a rewatch past the budget: a new season of a show the user is partway through rewatching is not placed from the calendar. A show the user had caught up on is still placed when a new episode airs.
• Episodes outside the library. An episode watchlisted on its own, for a show that is not otherwise in the library, cannot be filtered by the library's hidden flags. Trakt's calendar lists it, and the Calendar shows it even if that show is hidden or dropped.
• Search before the library loads. Search shows "Add" for a watchlisted show until the library loads. Adding it again is harmless: Trakt's watchlist add is idempotent.
• A remote watch costs more reads. After an activity change to watched history, the season trees on screen are read again. In the heavy replay, "mark, undo, then the next poll" goes from 89 to 169 GETs, because the poll after the user's own mark refetches Up Next's 40 placed trees, two reads each. There are still no 429s. The planned delta reload after the app's own writes, already in the known-over table, is where that poll should get cheaper.

After

Scenario	GETs before	GETs after	429s before	429s after
Sign-in and first sync	794	276	2	0
Cold launch, cache older than an hour	701	187	5	0
Warm launch, fresh cache	569	5	4	0

Warm launch, fresh cache and unchanged activities, per path:

Path	Before	After
/sync/last_activities	1	1
/shows/:id/progress/watched	282	0
/shows/:id/seasons	282	0
/shows/trending, /shows/popular, /movies/trending, /movies/popular	1 each	1 each

The four rails are the Search tab's own read when it mounts, and do not depend on the activities diff. They go away with the planned change that loads the Search tab's data on first focus, which the known-over table already lists.

What the first sync still reads: 60 progress reads for the most recently watched backlog shows (the policy budget), 40 season trees (80 GETs) for caught-up shows that have a new episode, 100 show reads for queue row art, and 36 list pages. The known-over table names the planned changes that cover the art and the trees.

Tests

• scenario-budget.test.tsx:
  • For both library sizes:
    • no read in any scenario is refused by the rate limit;
    • no scenario that writes nothing fetches the same URL twice;
    • the warm launch reads exactly the five paths above.
  • Two loadBrowse calls made while the rails are held cost 4 requests, and a later call costs 4 more.
  • Heavy library: backlog shows past the budget that had an episode air lately stay out of Up Next, and Library counts their episodes left from Trakt's bulk numbers.
  • A season tree kept across launches: open a show so its tree is persisted, write a play for it straight to the fake as another device would, relaunch warm. The tree is read once more and shows the episode watched.
• pooled-endpoints.test.ts:
  • different arguments are not shared;
  • a failure reaches every caller of a shared read;
  • the next call after a failure reads afresh.
• trakt-library.test.ts: a backlog show without a progress read has no aired frontier.
• query-cache.test.ts: a library show's season tree is persisted only while a screen observes it, and an unseen show's tree never is.
• query-invalidation.test.ts: the watched and hidden activity changes route to the show trees.
• library-snapshot.test.tsx: a show hidden in the library is left out of the recently-aired reconcile.
• calendar-read.test.ts: a dropped show is filtered by the library's flag.
• watchlist-add.test.tsx: a failed remove restores the library, the movie library and the movie watchlist.
• Native calendar.test.tsx:
  • a hidden show is left off;
  • the Calendar holds until the library answers, including with "every watchlist episode" on;
  • a failed library read shows every row.
• Native up-next.test.tsx: a hidden show is left off Up Next's coming-up list.
• hide-show.test.tsx: stopping a show does not invalidate the calendars.

Every new or changed assertion was checked by reverting the change it covers and confirming that the test fails.

Size

• Product code: +131, -116 (net +15).
• Tests: +403, -151 (net +252).

Coverage-Rationale: useCalendarFocus (lines 20-35) is exercised through the native Jest suite, which the core coverage report does not include: calendar.test.tsx covers played versus watchlist-only shows, stopped and dropped shows left off, the hold until the library answers (with "Every watchlist episode" off and on), and unfiltered rows when the library cannot be read; settings.test.tsx covers the switch revealing an episode.

[github-actions]

Pull request footprint

measurement	base to head
Product code lines in core/src, native/src, native/app, and native/modules	+6
Test lines in test, packages/*/{test,__tests__,e2e}, and .maestro	+224
CI and tooling lines in .github and scripts	+0
Product comment lines identified by a comment prefix	+6

JavaScript bundle at head	size
Expo ios bundle	5624 kB
Expo android bundle	5662 kB