Classify 507 Insufficient Storage, and stop the four places that swallowed it

[jvsena42]

Closes #91 (code); the measurement pass and the upstream ask are left open — see below.

The homeserver enforces a per-user storage quota and answers 507 Insufficient Storage on any write over it. Loopky had no classifier for it, no copy for it, and the four places most likely to hit it all swallowed the failure.

What changed

1. It has a name now. isQuotaExceeded() + ErrorReason.StorageFull, with copy on both platforms that names the two remedies that actually work — delete a deck, or buy more room — instead of "please try again", which is the one action that cannot possibly succeed.

Two details worth reviewing:

• The classifier runs ahead of isRateLimited/isNetworkFailure. Nothing they match collides with the 507 body today, but "quota" is the word a future bandwidth limit will also reach for, and reading a full disk as "the server is busy" retries against it forever.
• It matches 507 as a status code, not a substring. Every failure message carries a pubky:// URL and ids are random alphanumerics, so a bare "507" in msg would send someone off to delete decks over a missing record. There is a test for exactly that.
• withWriteRetry now returns on a quota error before the rate-limit branch can claim it. It already didn't retry 507 in practice; this makes that a property of the code rather than of the wording the homeserver happens to use.

2. Study progress no longer dies silently. This was the worst of the four and silent by construction: flushAsync logged the failure and dropped it, the reviews went back into an in-memory dirty set, every retry hit the same 507, and the whole set died with the process. A user could study a full session, watch the counters move, restart, and find the progress gone having seen nothing go wrong.

Both halves are needed — surfacing an error about work already lost is not much better than silence:

• PendingReviewStore mirrors the unflushed buffer to SharedPreferences/NSUserDefaults, written on every grade rather than only on the failure path, since the window it closes is the process dying. Restored before anything reads the cache, sent immediately on recovery, cleared by the first flush that succeeds. It records each review's chunk rather than recomputing it, because a restore that guessed differently would file the review into the wrong record.
• SrsRepository.flushFailures surfaces it, replayed so the study screen still learns about a flush that failed as the screen was going away. The synchronous path was swallowing too — the automatic every-20 flush comes back through review(), and onGrade logged and dropped it.
• The screen shows a banner, not an error state. The session is still worth finishing, so blanking the card someone is mid-way through would cost more than the warning is worth.

3. The background jobs stop instead of backing off. Result.failure(), not Result.retry() — WorkManager's exponential backoff against a permanent condition never converges. DeckMediaSweeper also ends the pass on the first 507 rather than trying every remaining blob, banking its progress first. This compounds: re-hosting is a quota consumer, so the mechanism that fills the quota was the one retrying against it. And compaction can't dig you out either — a merge writes the landing chunk before emptying the source, so it temporarily grows usage.

4. Publish no longer ships a deck missing the user's images. resolveDraftImage/resolveCoverImage degraded a failed upload to null and carried on, producing a deck that looked successfully published and was quietly missing the images picked during triage. They now throw and the publish aborts. Anything already uploaded is swept by hand, because media goes up before the #49 marker manifest and delete has no manifest to walk — which matters most in exactly this case, since a full disk is a poor moment to leak blobs. state.error is now a PublishError rather than a raw err.message putting FFI diagnostic text on screen.

Found by driving it on a device

Two things the tests passed straight through:

• Recovered reviews were restored but never sent. A flush needs either a closing study screen or 20 more grades, so someone who studied offline and never opened another session kept a journal that was recoverable but never recovered.
• An outage was being reported as a session expiry. Offline, the FFI reports "Failed to import session: … HTTP transport error", which contains both "session" and "import" — so isSessionExpired matched it. The new banner rendered "Sign in with Pubky Ring again" to a user whose only problem was airplane mode, and requiresReauth would have signed them out over a dropped connection. Pre-existing; the banner is just what made it visible.

Verified on device (emulator, real homeserver): journal written live on each grade and cleared by a successful flush; 24 reviews graded offline survived a force-stop, were restored on relaunch, and reached the homeserver once the network was back; the banner renders over a live session without ending it.

Deliberately not done

• §5.4, measure how close 1GB is. Needs a realistic Anki import with audio published against a test homeserver and an admin-API read of storage_used — it cannot be answered from the client. What is known is written down in Architecture.md §8.5 so the next person doesn't guess: audio is uploaded uncompressed, dedupe is per-deck not per-user, and a clone re-hosts its own copy. Until there is a number, no copy should promise a deck count.
• §5.5, ask upstream for a usage endpoint. Not a code change. Recorded in §8.5 as the thing that would turn this from an error state into a progress bar — without it Loopky cannot warn anyone in advance, so all of this is necessarily reactive.
• The §6 asides (bandwidth quota, the 100MB body cap) are recorded in §8.5 as open, not investigated.

🤖 Generated with Claude Code