[matt2e]

Stack

This stack splits #1697, the frozen draft umbrella at 34fc40668, into three layers. Each PR is based on the one before and merges in order. #2408's tree equals #1697's, and #1697 closes when #2408 merges.

1. fix(unread): keep the viewer's threads in the Inbox under busier channels #2401 (PR 1, inbox-1-channel-windows): reads each channel on its own and remembers your threads, so busier channels no longer push a thread out of the Inbox. ← this PR
2. feat(unread): restore the Inbox's evidence from a device record on launch #2407 (PR 2, inbox-2-device-record): saves the Inbox's evidence on the device and restores it on launch.
3. perf(unread): catch the Inbox up from a saved mark instead of re-reading every repair #2408 (PR 3, inbox-3-catch-up): catches up from a saved mark instead of re-reading everything on every repair.

Before and after

Main c3c46c503, this PR's base, is on the left and this PR 47e9a8031 on the right. Both run the web app in Chromium on a fresh device against one local fixture relay with the same made-up team. The box at each pane's bottom right shows the time since the pane loaded, its relay queries and the bytes downloaded.

Diego's reply in your thread appears on the right only

Busy channels push Diego's unread reply in your quiet #rollout-team thread out of main's newest-500 read. This PR reads each channel and your threads, so the row and the channel's thread dot appear at launch and again after a reload.

pr2401-s1.mp4

One #incident-review row for one thread, not three

Main never looks up the root of a read reply, and this thread's root is older than main's read, so three read @mentions in it show as three rows. This PR fetches the root and groups them under one row; opening the thread shows the same thread on both sides.

pr2401-s2.mp4

#design-ops shows as unread on the right only

A post from nine hours ago, with no @mention, in a channel you last read three days ago is older than main's read reaches. This PR reads the channel itself and marks it unread; main shows the post only when you open the channel.

pr2401-s3.mp4

A reply in a three-week-old thread appears on the right only

Lena answers, without an @mention, in a 21-day-old #platform-arch thread you replied in. This PR pages back through your own messages, finds the thread and reads it; main never sees the reply.

pr2401-s4.mp4

One failed read: a notice on the right, an error and a lost row on the left

Here the busy channels are lighter, so main's read reaches Diego's reply, and both builds show it when every read answers. Then the relay fails that read: main shows “Relay request failed (500)” and loses the row, while this PR keeps it from its other reads and shows “Some recent activity could not be checked.” with Refresh.

pr2401-s8.mp4

Problem

A thread you had replied in vanished from the Inbox (reported in #buzz-team). Main builds the Inbox from one sample per 128 joined channels: their newest 500 messages, and since #1860 only what is newer than that batch's last read. On a busy roster the sample reaches back only a few hours. Once busier channels push a thread out of it, nothing brings it back. A read reply whose root has aged out then shows up as a loose row of its own.

What this PR contains

This is PR 1 of three. It contains the per-channel windows and the viewer's remembered threads. It does not restore evidence from the device and does not catch up from a mark: every repair (launch, reconnect, the 15-minute backstop, and recovery while a repair is owed) reads in full.

• Each channel on its own. Each joined channel is read since its read mark (or the last week, when never read), up to 100 recent events. On a large roster the windows shrink so the pass fits the 4,096-event budget. The newest 500 events of each 128 channels are read too, so a repair holds everything main's sample holds.
• The viewer's threads. Unread remembers up to 1,000 threads the viewer took part in, per relay and viewer: replies, mentions, answers and follows. A device's first repair learns the older ones by walking back through the viewer's own messages. The 50 most recently read or written in are read whole on every repair. The rest are read only for replies since the newest one the viewer wrote or read. The record is kept in IndexedDB buzz-unread-v1, in its meta store. Its events store is created empty, for PR 2.
• Budget. When the budget is full, the busiest channel's oldest ordinary evidence goes first. A channel left with none is unknown, not zero. Roots fetched only to group replies are structure, not evidence. They are bounded at 1,024, and the roots of remembered threads go last.
• Failures. A response too large for the reader or the native host is split and read in parts. A read dropped after its retry shows "Some recent activity could not be checked." with Refresh, instead of counting zero. The repair stays owed, so the next minute's recovery check repairs again.
• inbox() folds each channel's own evidence, and the edits and deletions on it, rather than every retained event.

#1860's per-batch incremental marks go: per-channel windows replace the batches they bounded. Its 14 tests are retired; see the coverage map below.

Details and limits: docs/inbox.md and docs/unread.md.

Commits

1. b64d85cf0 Snapshot. Its production tree equals 4d3639704's, the layer-1 tip of fix(unread): keep participated threads in the Inbox and persist its evidence across launches #1697 before its device record and catch-up. Tests are 4d3639704's. This commit is red on its own and was committed with --no-verify.
2. 9f220aa62 applies fix(unread): keep participated threads in the Inbox and persist its evidence across launches #1697's test trim (34fc40668) by name to those tests.
3. Forward-ports from fix(unread): keep participated threads in the Inbox and persist its evidence across launches #1697's later commits:
   • a5b5ee48a: fold per channel (5a5225718). Its unread-fold.test.ts comes from 34fc40668, so it also carries that file's 30-day read floor and perf(unread): reuse folded rows until the evidence index changes #2366 cached-fold reorder.
   • 031332b5a: keep unread owed after a pass that drops a read (dd306db07). It adds the test "a pass that drops a window chunk leaves unread owed…", shown failing before owing = unchecked.
   • 5211b06fe: storage under the record's final names (buzz-unread-v1, meta and events, IDB version 1).
   • 711d93cb7: request shapes named.
   • 9b346befd: keepRoot, with the cache order and exact bound (9815e47a0, de2d02efb, da8ed62cc).
   • c0b98bb58: tests read past main's 30-day read floor, count a repair's channel read, and fail only the timeline's page read (367b38c45, 11f22a6f4).
   • 47e9a8031: retire fix(relay): resume live routes from the last connection and spread restart reconnects #1860's tests.

keepRoot. The test "a remembered thread's root the repair fetches by ID, in a channel the viewer never read, groups its read mention and never counts" fails on the layer-1 tree without keepRoot (observedCount 1, expected 0). So keepRoot came into this PR, with the cache order and exact bound.

Cost against main

These are the plan's figures. None was re-measured on this branch. Each was taken at the commits named, and every one of those builds predates #2252 (45caf7fd2), when every minute tick repaired. None is this branch's tree. The branch-side probes ran on #1697 before its rebase (5cc123c61 or 1c428329f), which holds the windows, remembered threads and walk, but not the roster sample or this PR's forward-ports.

	main	this PR	measured at
Full repair (launch, reconnect, 15-minute backstop, owed recovery)	1 request, ~0.5 MB, 1 filter	~6 requests, ~2.6 MB, ~2.3k events, ~230 filters	main: live probe at 7d275a808 (510 KB, 500 events). This PR: derived. 1c428329f's live per-tick reads (5 requests, ~2.1 MB, ~1.8k events) plus an estimated ~0.5 MB roster sample. 229 filters in a replay of 1c428329f's requests.
Relay DB time per launch	~12 ms	~280 ms (~23×)	Local replay, not the live relay: requests rebuilt from 848288b67 and 1c428329f against the block/buzz relay at 24a370606 on a seeded Postgres 18.6. The repair read alone is ~77×.
Idle relay bytes per hour (4 backstops)	~2 MB	~10.5 MB	Arithmetic, 4 × the full-repair row; not measured.
Warm launch	1.82 s ensure() to first inbox()	~3.2 s; 7 /query, 1,571 events, 1.77 MB, plus the ~0.5 MB sample; first row +0.8 s, caption +1.7 s	main: live probe at 848288b67. This PR: live probe at 5cc123c61, without the sample. Deltas: headless Chromium, live relay, 7d275a808 vs 1c428329f, medians of 5.
Fresh device (once)	—	~8.6 s; 12 /query, ~3k events, 3.1 MB; caption +7.9 s	~8.6 s: live probe at 5cc123c61. Caption: 7d275a808 vs 1c428329f, as above.
inbox() CPU	5.6 ms	~10 ms (31 ms without the per-channel fold)	main: live recompute at 67e404917 (~530 events). This PR: Vitest micro-benchmark on 2,000 events across 80 channels, 5a5225718 vs its parent f4770e830. The two use different fixtures, so they do not compare directly.

A minute tick still reads nothing unless a repair is owed, as on main since #2252. Each full repair costs about 5× main's bytes, by the derived 2.6 ÷ 0.5 MB. Main's figure is for a busy roster, where #1860's marks drop at the limit; at 67e404917, which has #1860, main's repair read 481 KB. On quiet rosters main reads less, so this PR's relative cost is higher there. There is no kill switch. PR 3 brings the backstop and reconnect down to one delta.

#1860 coverage map

e8b13d4 (#1860) made main's evidence read incremental per 128-channel batch: a batch that came back short was next read from 960 s before the newest row it returned. This PR reads each channel's window on its own and keeps no mark, so its 14 tests in unread-startup.test.ts, and their helpers, tested behaviour the branch does not have. All 400 lines go (47e9a8031); they match 1d8c52742's deletion line for line. For each removed test, here is the test covering the equivalent behaviour, or the exception:

Removed test	Layer-1 coverage, or exception
a repair after a complete observation reads only near the newest event it returned	Exception: there is no mark, so no repair reads less than its windows. The cost is in the table above. PR 3's catch-up replaces it.
a batch that returned nothing is read unbounded again	Exception, nothing to port: every repair reads unbounded.
a future-dated event cannot move the next repair past the present	Exception, nothing to port: there is no mark for an event to move. PR 3 ports the clamp with its mark.
a repair never reads from before the newest event it already returned	Exception, nothing to port, as above.
regaining access reads the batch unbounded, not from the old mark	unread-startup "observes a channel again when the viewer regains access to it" stays. In "late chunk cannot publish or dispatch another after %s" (revoke), the abandoned read starts over against the current membership.
an explicit refresh re-observes unbounded	unread-startup "explicit refresh bypasses optional profiles for both markers and evidence" stays; its trace shows the refresh's full repair.
clearing the cache re-observes unbounded	Exception: there is no mark to forget, so the repair after a clear reads in full, as every repair does. unread-startup "late chunk cannot publish or dispatch another after %s" (clear) and "a lookup in flight during a cache clear cannot restore its result" keep the clear boundary.
capacity overflow discards the mark with the evidence it described	Exception: the branch never clears evidence on overflow. It evicts the busiest channel's oldest ordinary evidence, and a channel left with none is unknown, not zero. Covered by unread-repair "a full budget evicts the busiest channel's oldest ordinary evidence, never a quiet channel's only message or the viewer's thread" and unread-startup "a full budget evicts the oldest evidence and the observation still completes".
a read cut off at its limit installs no bound, so a freed slot still shows an older unread message	Every channel has its own window, so a busy channel cannot crowd out a quiet one's message. Covered by unread-repair "a first run with a large roster sizes each window so the pass fits the budget, and a quiet channel's mention survives" and unread-startup "a full channel window does not starve later channels, and a dropped request leaves its channels unknown until explicit refresh".
a bounded read that comes back at its limit drops the bound for the next read	Exception, nothing to port: no read is bounded by a mark.
a bounded repair answered after a live overflow restores no mark and keeps the overflow error	Exception, as for the overflow above: there is no overflow error, reset or mark.
an explicit refresh during a bounded repair waits for it, then reads in full	Exception: a refresh during a repair joins it (repair() returns the running pass), as on main before e8b13d4, and that pass already reads in full. No layer-1 test pins the join for refresh; "concurrent ensure callers share the active marker/evidence work" pins it for ensure.
a refresh asked while a repair's answer is being accepted still reads in full	Exception, as above.
renaming a channel does not move the batches, so they keep their bounds	Exception, nothing to port: windows are per channel ID and carry no bound.

FOUNDATION

src/features/relay/session.ts is FOUNDATION. This PR adds one import and one line to it, storage: browserUnreadStorage(readScope). Matt Toohey approved this before the change.

Checks

All of these were run on 47e9a8031, on a loaded machine (load average 9–16):

• git diff 4d3639704 HEAD -- src tests. On the branch's files, the snapshot equals 4d3639704, so everything past it is the trim and the seven forward-ports above. The other 37 files that differ were changed only by main, between 4d3639704's base cbc71c85a and c3c46c503.
• bin/pnpm typecheck: clean.
• biome check --error-on-warnings on the 33 changed code files: clean.
• git diff --check c3c46c503 HEAD: clean.
• Vitest on src/features/relay, src/bundled/inbox, src/features/notifications, src/features/messages and src/features/communities: 273 files passed and 1 skipped; 6,136 tests passed and 4 skipped.
• Playwright --no-deps on sidebar-unread, message-navigation, scroll, navigation-thread-history, inbox, inbox-edit, thread-unread and channel-lifecycle, one engine after the other: Chromium 76 passed (2.7 min) and WebKit 76 passed (3.1 min), with no timeouts or retries.
• 031332b5a's new test fails before owing = unchecked and passes after it. The keepRoot test fails on the layer-1 tree without keepRoot.

Browser cases: none were added or removed. Four journeys' request assertions are adapted to per-channel windows and the authored walk: sidebar-unread, scroll, message-navigation and navigation-thread-history.

Not verified: the native host (its 16 MiB split, and the dev broker's validFilters), a live relay, the live probe and just scan. Nothing was exercised in the running app, and there has been no human test, so this stays a draft.

🤖 Generated with Claude Code

[kalvinnchau]

🤖 One maintainability finding; no functional or security blocker established.

[kalvinnchau]

🤖 Three test-quality findings: the modeled relay rejects valid split reads, a startup mock hides assertion failures, and admission cases miss the rule they intend to exercise. No production defect established.

[kalvinnchau]

🤖 [P3] Accept reduced authored-page limits in the modeled relay

At tests/browser/policy-relay.mjs:465–469, the model still requires exactly 100 for the viewer's authored page and 500 for its continuation. The adjacent window fix now accepts split limits, but unread.ts:2003–2025 halves any lone filter and :2297–2302 preserves reduced continuation limits. An authored response exceeding 8 MiB can therefore produce valid limit-50 or limit-250 reads that the fixture rejects with 500.

This is a statically identified test-model mismatch, not a demonstrated production defect or a reproduced failure in current browser journeys. Accept 1..100 and 1..500 respectively when the authored filter is alone, and cover these cases beside the new lone-window integration test.