[mozzius]

Fixes APP-3158. Stacked on #11942.

What it does

• Restores. Home Following reports whether it showed its saved snapshot, fetched instead, or failed to load. It also says whether the snapshot was valid, missing or rejected and why, how old its newest posts were, its size and its page count.
  • restored means the view shows the exact page the read restored, so it's also right after switching back to an account.
  • Two of the reasons, "expired" and "appVersion", mean TanStack threw away the whole saved cache: it has a 24 h maxAge and resets on every app version (APP-3397).
  • What a read found is held per query client, not in a module-level variable.
• Checks. Each check for new posts reports what started it (focus, return, hop or interval) and how long it's been since the last successful check. What it did comes from the prepend's own check: staged, notStaged, nothing, skipped, joined, found or failed.
• Prepends. Each fetch of newer posts above the reader reports what started it, whether it staged them, how many posts came back, and whether there were more than fit (a gap). If it wrote nothing, it says why:
  • nothing was newer;
  • the waiting page was already full;
  • a refresh won;
  • or the reader reached the posts first.
• Refreshes and gaps report whether they wrote, failed, or gave way to newer data. Settles also report how many pages they dropped.
• Low volume. Interval checks and quick hops can repeat every minute or more often. So they and their prepends are sampled at 10% of app sessions (all of them in internal builds), and each event carries its sampleRate.
• Gated and private. Only Home Following on iOS and Android with Following v2 on reports anything. Every payload is built field by field, so no feed content, cursors or account data can slip in through a spread. A test checks this across every event. The change to the shared persister only passes the query client and the settings it already used.

Known issues

• No events yet for Discover/For You batches (milestone F) or for the list losing the reader's place.
• A snapshot that couldn't be saved shows up as "missing" on the next cold start, without a reason.
• A failed check makes the next focus check's clock fall back to the top page's age (APP-3396).
• Following's own restore prepend still decides "restored" by when the process started. So switching back to an account in the same session restores its snapshot without a restore prepend or pill. That's a follow-up.

Test plan

• pnpm test src/features/followingV2 src/lib/appState (296 tests), pnpm typecheck, pnpm lint.
• Unit tests:
  • the snapshot rules;
  • what a read reports, once per read and per query client;
  • restore classification, including a restore within the same process;
  • sampling: a session outside the sample, one inside it with sampleRate 0.1, and reporting disabled.
• Through the renderHome harness, which now runs PostFeed's real wiring:
  • interval checks that stage, and ones that only peek;
  • full pages, and a full page kept;
  • a failed check;
  • a prepend that's dropped;
  • a refresh winning;
  • a cold start reporting restored, with its restore prepend and a joined focus check;
  • no content, cursors or DIDs in any payload;
  • settle outcomes.
• Device:
  • one followingV2:restore per cold start;
  • check, prepend and refresh events in the debug metrics log;
  • nothing with the flag off or on web.

🤖 Generated with Claude Code

[linear-code]

APP-3158

[github-actions]

Size	Old size	New size	Diff
Uncompressed	9.76 MB	9.77 MB	+5.83 KB (0.06%)
Gzip	2.86 MB	2.86 MB	+1.98 KB (0.07%)

---

[github-actions]

The OTA deployment for this PR was successful! You may now apply it by either scanning the QR code or opening the deep link below in your browser:

bluesky://intent/apply-ota?channel=pull-request-11957&releaseVersion=1.138.0&iosBuildNumber=2263&androidBuildNumber=1704