diff --git a/.github/workflows/docker-build.yml b/.github/workflows/docker-build.yml
index a7c8ca6..3033ea6 100644
--- a/.github/workflows/docker-build.yml
+++ b/.github/workflows/docker-build.yml
@@ -101,4 +101,4 @@ jobs:
           push-to-registry: true
       - name: Deploy to Portainer
         if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-        run: curl -X POST https://portainer.nickthesick.com/api/stacks/webhooks/b45c66e3-986c-4c08-b302-123ce48fe8b8
+        run: curl -X POST ${{ secrets.PORTAINER_WEBHOOK_URL }}
diff --git a/AGENTS.md b/AGENTS.md
index 3bdeb5a..5c13526 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -41,17 +41,19 @@ Browser ──> Bun.serve() ──> Hono app ──> Server-rendered JSX pages
                 │                              └── Worker threads (see below)
                 └── static files (public/)
 
-Worker threads (src/workers/, bundled to .output/server/workers/):
-  ingester-worker     — Jetstream firehose ingest
-  og-render-worker    — OG image generation (React + takumi)
-  open-observe-worker — pino log shipping to OpenObserve
-  import-worker       — CSV import processing
+Worker threads (bundled to .output/server/workers/):
+  ingester-worker     — Jetstream firehose ingest          (src/workers/)
+  og-render-worker    — OG image generation (React+takumi) (src/workers/)
+  open-observe-worker — pino log shipping to OpenObserve   (src/workers/)
+  import-worker       — CSV import processing              (src/workers/)
+  parse-worker        — ebook metadata parse + cover raster (single-shot, src/workers/)
+  waf-solver-worker   — AWS WAF challenge solve            (src/scrapers/waf/)
 ```
 
 **Key patterns:**
 
 - Server components (`src/pages/`) render full HTML. Only 6 islands are hydrated client-side (`src/client/`). Most interactivity is CSS-only (peer/checked selectors) or inline `<Script>` vanilla JS.
-- **Production is multi-process**: `server/cluster.ts` spawns `WEB_CONCURRENCY` (default 4) workers sharing port 8080 via SO_REUSEPORT. Worker 0 is the **primary** (`isPrimaryWorker`): only it runs migrations, VACUUM, the Jetstream ingester, and the enrichment drain.
+- **Production is multi-process**: `server/cluster.ts` spawns `WEB_CONCURRENCY` workers sharing port 8080 via SO_REUSEPORT — the code defaults to 4, but the deployed container sets **3** (verified on the host), which is the number every memory ceiling in this document is derived from. Worker 0 is the **primary** (`isPrimaryWorker`): only it runs migrations, VACUUM, the Jetstream ingester, and the enrichment drain.
 - **Enrichment is queued, never inline**: routes call `enqueueEnrichment`/`enqueueEnrichmentBatch` (`src/utils/enrichQueue.ts`). The primary worker drains it every 5s at concurrency 3, with exponential backoff. `enrichBookWithDetailedData` holds its own semaphore (4) + 45s deadline. That drain interval × concurrency is also the **only** rate limit on requests to Goodreads — 36 fetches/min, healthy or not. Don't add a second one.
 - **`enrich_queue.attempts` counts answers from Goodreads, not failures.** A run reports `enrich_retry` in the wide-event bag: `retry` spends an attempt, `defer` costs nothing and re-queues on a decaying schedule, `dead` tombstones the book immediately. Anything the app decided on its own — a WAF challenge, a timeout, a transport error — is a `defer`. Getting this wrong is expensive: when refusals counted as attempts, one 6h window wrote off 2,854 books for 7 days apiece **without sending a single request on their behalf** (98% of everything the queue gave up on). The bound on defers is `MAX_QUEUE_AGE_MS` (7d from `enqueuedAt`, which survives re-enqueue), not the attempt counter.
 - **Author lookups use `hive_book_author` join** (mig 020), not `LIKE`. This is exact identity, not text search.
@@ -147,7 +149,17 @@ Two traps this encodes, both of which caused real bugs:
 
 - `/healthcheck` → JSON status + git sha
 - `/metrics` → Prometheus
-- `/admin/*` → `src/routes/admin.ts` (gated by `EXPORT_SHARED_SECRET`)
+- `/admin/*` → `src/routes/admin.ts` (gated by `EXPORT_SHARED_SECRET`).
+  `GET /admin/backfill-catalog/progress` reads **through the KV**, not just this
+  process's memory: the backfill runs for hours on the primary worker while the
+  request lands on any of the three, so an in-memory-only answer reported `idle`
+  for a live job and lost the outcome of a finished one. A _stored_ `running`
+  can only mean the process died mid-run (a live run answers from memory), so it
+  is reported as `interrupted`.
+  **Persist the object, never `JSON.stringify` of it.** unstorage runs `destr`
+  over whatever a driver returns, so a stored JSON string reads back as an
+  object and any `JSON.parse` of it throws — which silently discarded every
+  stored run. Same idiom as `enqueuePdsWrite`.
 - `/debug/*` → `src/routes/debug.ts` (gated by `EXPORT_SHARED_SECRET`)
 - `/import` (POST `/goodreads`, `/storygraph`) → `src/routes/import.ts` — CSV import handler
 
@@ -221,7 +233,7 @@ User book lists ("shelves"). Uses **popfeed** lexicons (`social.popfeed.feed.lis
 Personal library: ebook uploads, e-reader credentials, sync documents. All auth-required.
 
 - GET `/` → `src/pages/library.tsx`
-- POST `/upload` → multipart upload (validates format, computes KOReader partial MD5, parses metadata, auto-links matching `sync_document`). Content-negotiated: JSON for mobile, 302 for browser. Size checked before `arrayBuffer()`.
+- POST `/upload` → multipart upload. A **thin adapter** over `uploadPersonalBook` (`src/utils/uploadPersonalBook.ts`) — the same core the XRPC procedure calls. Content-negotiated: JSON for mobile, `302 /library?error=<code>` for browsers (a plain `<form>` can't read a JSON error body, so the reason round-trips as a code `LibraryPage` renders as an alert). **No `bodyLimit()` middleware** — see the upload-core section for why it was the worst memory path in the codebase.
 - GET `/covers/:hash` → cover image; GET `/books/:hash/download` → file download (shares `streamPersonalBook` with OPDS)
 - GET `/shelves` → JSON shelf list with counts
 - GET `/sync/password`, POST `/sync/rotate` → KOSync password (duplicated from settings)
@@ -260,6 +272,66 @@ Auth: `x-auth-user` (handle) + `x-auth-key` (md5 of HMAC-derived password). Prog
 - PUT `/syncs/progress` → push progress; GET `/syncs/progress/:document` → pull progress
 - GET `/syncs/documents` → list all synced documents
 
+**A KOSync `document` id is not necessarily a content hash.** KOReader's
+checksum method is a user setting: `BINARY` (the default) is
+`koreaderPartialMD5` over the file, but `FILENAME` is plain `md5(basename)`, and
+users switch to it precisely because their files are _not_ byte-identical across
+devices. Matching only `documentHash = personal_book.contentHash` therefore
+never fired for any of them. `SAME_BOOK_FILE` (`src/utils/syncMatching.ts`) is
+the one predicate for "same book" — content hash, filename hash, or normalized
+filename — and it is used as a **correlated subquery, never a join**, because a
+document can match several files (and vice versa) and a join fans that out into
+duplicate rows that also break `getPersonalLibrary`'s pagination.
+
+Separately, the payload may carry `metadata: { filename, title, authors }`
+(KOReader PR #15306, merged 2026-04-29 — its "Send document metadata" toggle
+**defaults off**, so most KOReader users still send none of it; CrossPoint sends
+it). Two non-obvious things about that object, each of which silently matches
+nothing if you assume otherwise:
+
+- **`authors` is newline-separated**, not comma- or tab-separated. It is
+  `doc_props.authors`, one of the three props KOReader's metadata editor opens
+  with `allow_newline = true`. (Three separators are in play across the app:
+  newline from KOReader, **comma** in `personal_book.authors` from `parseBook`,
+  tab in `hive_book.authors`.)
+- **`title` may itself be a filename.** It is `doc_props.display_title`, defined
+  as `props.title or splitFileNameType(filepath)` — so any document with no
+  embedded title sends the filename stem, dashes and all. `matchSyncDocument`
+  runs the client's `title` through the filename parser for that reason.
+
+**The routes call `matchSyncDocumentForUser`, not `matchSyncDocument`.** With
+both KOReader defaults in force — BINARY checksum, `send_metadata` off, which is
+most users — the entire request identifies the book as one partial-MD5 hash and
+nothing else, so matching the _payload_ is hopeless no matter how good the tiers
+get. But that hash is `personal_book.contentHash`: if the user uploaded the
+file, we already parsed real title/author metadata out of the ebook at upload
+time and may already have resolved it to a book.
+`matchSyncDocumentForUser` finds the file first, inherits its `hiveId`, else
+matches on the file's own metadata, and writes the result back onto the file
+(plus `user_book.owned`). `uploadPersonalBook` already pushes a link the other
+way when the document exists first; this covers the opposite ordering.
+
+`matchSyncDocument` itself runs three tiers, and the invariant across all of
+them is that **a wrong link is worse than no link**: it writes progress onto a
+book the user isn't reading and mirrors it to their PDS, while a miss just
+leaves the document for them to link by hand.
+
+1. Exact `hive_book.id` hash of the client's title+author.
+2. Exact id hash of title/author pairs parsed out of the filename. Both
+   orderings of an `A - B` split are tried; that is safe _because_ it resolves
+   against the catalogue, so a wrong guess hashes to an id that does not exist.
+3. Fuzzy. Candidates come from `hive_book_fts`, searched by **author** as well
+   as by title — FTS matches phrases, so a title search alone can never reach
+   "The Hitchhiker's Guide" from "Hitchhikers Guide", whereas an author's name
+   is spelled the same either way and their books can then be compared in JS.
+   Acceptance is `titlesEquivalent` (equal content-word sets, gated **both**
+   ways — one-way containment would accept "Dune" as "Dune Messiah") plus an
+   agreeing author. With no author signal anywhere, only a title that names
+   exactly one book is accepted.
+
+Do not gate any of this on title/author being present — that gate is what made a
+filename-only client unmatchable in the first place.
+
 ### Shared route helpers
 
 `src/routes/lib.ts` — `cacheControl`, `searchBooks`, `ensureBookIdentifiersCurrent`, `refetchBooks`, `refetchBuzzes`, `refetchLists`, `syncFollowsIfNeeded`.
@@ -337,7 +409,8 @@ larger than the JPEG. Size the WebP to ~2x the CSS slot, not to the source's int
 - `apple-touch-icon.png`, `favicon*.png`, `favicon.ico` — fixed-format platform requirements.
 - `reading.png` — only used by `README.md` / `app/README.md`, never served.
 
-The other 16 `public/screenshots/*.png` (~6.6 MB) are referenced nowhere in the codebase; they
+The other 13 `public/screenshots/*.png` (5.6 MB — the directory holds 16, three of which are the
+`<img>` fallbacks above) are referenced nowhere in the codebase; they
 look like App Store listing assets (light/dark and `-16` variants), so they are kept as-is.
 
 ### Shared Page Components (`src/pages/components/`)
@@ -382,7 +455,7 @@ Client hooks/utils: `useSearchBooks.ts`, `useDebounce.ts`, `icons.tsx`, `debounc
 
 ### Database (`src/db.ts`)
 
-SQLite via Kysely. Schema + all migrations (001–021) in one file. `createDb` sets WAL/perf PRAGMAs. `mmap_size` defaults to 0 (see `DB_MMAP_SIZE` in `src/env.ts`). Kysely talks to `bun:sqlite` through `src/bun-sqlite-kysely.ts`, which rewrites `begin` to `BEGIN IMMEDIATE` (deferred transactions fail with `SQLITE_BUSY_SNAPSHOT` across cluster processes).
+SQLite via Kysely. Schema + all migrations (001–023) in one file. `createDb` sets WAL/perf PRAGMAs. `mmap_size` defaults to 0 (see `DB_MMAP_SIZE` in `src/env.ts`). Kysely talks to `bun:sqlite` through `src/bun-sqlite-kysely.ts`, which rewrites `begin` to `BEGIN IMMEDIATE` (deferred transactions fail with `SQLITE_BUSY_SNAPSHOT` across cluster processes).
 
 | Table                 | Purpose                   | Key columns                                                                                                                                                                                              |
 | --------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -396,11 +469,11 @@ SQLite via Kysely. Schema + all migrations (001–021) in one file. `createDb` s
 | `user_follows`        | Cached follow graph       | userDid, followsDid, followedAt, syncedAt, **isActive**                                                                                                                                                  |
 | `book_list`           | User-created book lists   | **uri (PK, AT URI)**, userDid, name, description, ordered, tags, createdAt                                                                                                                               |
 | `book_list_item`      | Items in a book list      | **uri (PK, AT URI)**, userDid, **listUri**, hiveId, position                                                                                                                                             |
-| `sync_document`       | E-reader sync progress    | id (PK), userDid, provider, documentHash (UNIQUE per user+provider), hiveId (nullable), filename, title, authors, progressData (JSON)                                                                    |
+| `sync_document`       | E-reader sync progress    | id (PK), userDid, provider, documentHash (UNIQUE per user+provider), hiveId (nullable), filename, **filenameKey**, title, authors, progressData (JSON)                                                   |
 | `enrich_queue`        | Pending Goodreads enrich  | **hiveId (PK — the dedupe)**, **enqueuedAt** (age ceiling; survives re-enqueue), attempts, nextAttemptAt, claimedAt, lastError                                                                           |
-| `personal_book`       | Uploaded ebook files      | contentHash (PK), userDid, filename, title, authors, format, hiveId (nullable), fileSize                                                                                                                 |
+| `personal_book`       | Uploaded ebook files      | id (PK, autoincrement), UNIQUE (userDid, contentHash), filename, **filenameHash**, **filenameKey**, title, authors, format, hiveId (nullable), **sizeBytes**                                             |
 | `personal_shelf`      | User's personal shelves   | id (PK, autoincrement), userDid, name, description                                                                                                                                                       |
-| `personal_shelf_item` | Books in personal shelves | shelfId, contentHash (PK pair)                                                                                                                                                                           |
+| `personal_shelf_item` | Books in personal shelves | shelfId, **personalBookId** (UNIQUE pair) — the row id, not the content hash                                                                                                                             |
 
 Notes: `book_list*` are keyed by AT URI, not numeric ids. `NO_HIVE_MATCH` sentinel (`bk_none`) on `sync_document.hiveId` means the user dismissed the match — read paths must surface as `{ hiveId: null, dismissed: true }`. `enqueueEnrichmentBatch` filters books with recent `enrichAttempts`/`enrichFailedAt` internally (7d cooldown).
 
@@ -436,33 +509,162 @@ SQLite-backed unstorage. Mounts: `search:` (in-memory LRU), `profile:`, `identit
 
 ### Key Utilities (`src/utils/`)
 
-| File                  | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `getBook.ts`          | Book record CRUD against user's PDS                                                                                                                                                                                                                                                                                                                                                                                           |
-| `getProfile.ts`       | Profile fetching from Bluesky                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `getFollows.ts`       | Follow graph sync                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `enrichBookData.ts`   | Goodreads enrichment (semaphore-bounded, 45s deadline)                                                                                                                                                                                                                                                                                                                                                                        |
-| `enrichQueue.ts`      | `enrich_queue` producer + primary-worker drain, and the `retry`/`defer`/`dead` accounting. The `exhausted` gauge/heartbeat counts `hive_book.enrichFailedAt` inside the cooldown, **not** queue rows at MAX_ATTEMPTS — those are deleted as they exhaust, so that read was always 0. `deferred` counts books parked on something that isn't their fault; it replaced `circuit_open` as the signal that fetching is in trouble |
-| `semaphore.ts`        | Async concurrency limiter + `withTimeout`                                                                                                                                                                                                                                                                                                                                                                                     |
-| `circuitBreaker.ts`   | Three-state breaker — **`auth/restore-guard.ts` only.** Right when refusing is cheaper for a waiting user than failing; wrong for scraping, where the queue can defer instead. See the note under Scrapers                                                                                                                                                                                                                    |
-| `bookIdentifiers.ts`  | ISBN/ID normalization + persistence                                                                                                                                                                                                                                                                                                                                                                                           |
-| `bookProgress.ts`     | BookProgress serialization                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `readThroughCache.ts` | KV read-through with TTL                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `csv.ts`              | Goodreads/StoryGraph CSV parsers                                                                                                                                                                                                                                                                                                                                                                                              |
-| `lists.ts`            | Book list (shelf) CRUD against PDS                                                                                                                                                                                                                                                                                                                                                                                            |
-| `readingStats.ts`     | Reading stats aggregation by year                                                                                                                                                                                                                                                                                                                                                                                             |
-| `imageProxy.ts`       | imgproxy signing + proxy helper                                                                                                                                                                                                                                                                                                                                                                                               |
-| `personalLibrary.ts`  | Personal library paths, `streamPersonalBook`                                                                                                                                                                                                                                                                                                                                                                                  |
-| `bookMetadata/`       | Ebook metadata parsing (epub, mobi, fb2, cbz, cover extraction, KOReader hash)                                                                                                                                                                                                                                                                                                                                                |
-| `bookMeta.ts`         | Book metadata utilities                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `syncMatching.ts`     | KOReader document → BookHive book matching; `NO_HIVE_MATCH` sentinel                                                                                                                                                                                                                                                                                                                                                          |
-| `syncBridge.ts`       | Bridge e-reader progress → user_book + queue PDS write                                                                                                                                                                                                                                                                                                                                                                        |
-| `ftsQuery.ts`         | FTS5 MATCH expression builder                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `importBook.ts`       | Import a single book record                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `authorMatching.ts`   | Author name matching                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `manifest.ts`         | Vite manifest → asset URLs                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `xml.ts`              | XML utilities                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| Other                 | `getLanguages.ts`, `catalogBookService.ts`, `deleteAccount.ts`, `dbExport.ts`, `generateInitialsAvatar.ts`, `htmlToText.ts`, `batchTransform.ts`, `lazy.ts`, `hiveBookGenres.ts`, `ensureBookCataloged.ts`, `uploadImageBlob.ts`                                                                                                                                                                                              |
+| File                    | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `getBook.ts`            | Book record CRUD against user's PDS                                                                                                                                                                                                                                                                                                                                                                                           |
+| `getProfile.ts`         | Profile fetching from Bluesky                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `getFollows.ts`         | Follow graph sync                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `enrichBookData.ts`     | Goodreads enrichment (semaphore-bounded, 45s deadline)                                                                                                                                                                                                                                                                                                                                                                        |
+| `enrichQueue.ts`        | `enrich_queue` producer + primary-worker drain, and the `retry`/`defer`/`dead` accounting. The `exhausted` gauge/heartbeat counts `hive_book.enrichFailedAt` inside the cooldown, **not** queue rows at MAX_ATTEMPTS — those are deleted as they exhaust, so that read was always 0. `deferred` counts books parked on something that isn't their fault; it replaced `circuit_open` as the signal that fetching is in trouble |
+| `semaphore.ts`          | Async concurrency limiter + `withTimeout`                                                                                                                                                                                                                                                                                                                                                                                     |
+| `circuitBreaker.ts`     | Three-state breaker — **`auth/restore-guard.ts` only.** Right when refusing is cheaper for a waiting user than failing; wrong for scraping, where the queue can defer instead. See the note under Scrapers                                                                                                                                                                                                                    |
+| `bookIdentifiers.ts`    | ISBN/ID normalization + persistence                                                                                                                                                                                                                                                                                                                                                                                           |
+| `bookProgress.ts`       | BookProgress serialization                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `readThroughCache.ts`   | KV read-through with TTL                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `csv.ts`                | Goodreads/StoryGraph CSV parsers                                                                                                                                                                                                                                                                                                                                                                                              |
+| `lists.ts`              | Book list (shelf) CRUD against PDS                                                                                                                                                                                                                                                                                                                                                                                            |
+| `readingStats.ts`       | Reading stats aggregation by year                                                                                                                                                                                                                                                                                                                                                                                             |
+| `imageProxy.ts`         | imgproxy signing + proxy helper                                                                                                                                                                                                                                                                                                                                                                                               |
+| `personalLibrary.ts`    | Personal library paths, `streamPersonalBook`, `getStorageUsage`/`getStorageQuota`                                                                                                                                                                                                                                                                                                                                             |
+| `uploadPersonalBook.ts` | **The one** "put this ebook in this user's library". Both `POST /library/upload` and the XRPC procedure are thin adapters over it — see below                                                                                                                                                                                                                                                                                 |
+| `bookMetadata/`         | Ebook metadata parsing (epub, mobi, fb2, cbz, cover extraction, KOReader hash)                                                                                                                                                                                                                                                                                                                                                |
+| `bookMeta.ts`           | Book metadata utilities                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `syncMatching.ts`       | KOReader document → BookHive book matching (3 tiers, see below); `NO_HIVE_MATCH` sentinel; `SAME_BOOK_FILE`                                                                                                                                                                                                                                                                                                                   |
+| `filenameMatching.ts`   | Filename-derived identity: `koreaderFilenameHash`, `filenameKey`, `filenameBookCandidates`, `titlesEquivalent`, `authorsMatch`                                                                                                                                                                                                                                                                                                |
+| `bookMatching.ts`       | Fuzzy title scoring primitives (`similarityScore`, `contentWords`, `contentWordsMatch`), ported from MIT-licensed shelfcheck                                                                                                                                                                                                                                                                                                  |
+| `syncBridge.ts`         | Bridge e-reader progress → user_book + queue PDS write                                                                                                                                                                                                                                                                                                                                                                        |
+| `ftsQuery.ts`           | FTS5 MATCH expression builder                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `importBook.ts`         | Import a single book record                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `authorMatching.ts`     | Author name matching                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `manifest.ts`           | Vite manifest → asset URLs                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `xml.ts`                | XML utilities                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| Other                   | `getLanguages.ts`, `catalogBookService.ts`, `deleteAccount.ts`, `dbExport.ts`, `generateInitialsAvatar.ts`, `htmlToText.ts`, `batchTransform.ts`, `lazy.ts`, `hiveBookGenres.ts`, `ensureBookCataloged.ts`, `uploadImageBlob.ts`                                                                                                                                                                                              |
+
+### The upload core (`src/utils/uploadPersonalBook.ts`)
+
+**There is exactly one upload implementation. Do not add a second.** There used
+to be two — the live multipart route and a `processBookUpload` in the XRPC
+router whose own doc comment claimed to be the shared core — and they drifted in
+four ways (cover validation, sync matching, `sync_document.hiveId` writeback,
+empty-string handling) before anyone noticed. Both routes are now thin adapters.
+
+**The step order is the design, not an accident**, and each step is where it is
+for a measured reason:
+
+1. Reject on the _declared_ size and against the quota — before a byte is read.
+2. `writeCapped` streams the body to `{libraryDir}/.tmp/*.part`, capping as it
+   goes. The memory bound is the sink's **1 MB `highWaterMark`** — awaiting each
+   write is the backpressure signal, so a 100 MB body costs 1 MB of buffer
+   rather than 100 MB. This is what replaced `bodyLimit()`, which only
+   short-circuits on `Content-Length`: given a chunked body it drained the whole
+   stream into an array and rebuilt the Request, so a compliant 100 MB chunked
+   upload was buffered there **and again** by `formData()`.
+3. `detectFormat` off a **4 KB head** (it reads ≤512 bytes, plus 60–68 for MOBI).
+4. `koreaderPartialMD5File` reads **twelve 1 KB windows** — the hash never needed
+   the whole file; the buffer was incidental to how the old path worked.
+5. **Duplicate check before the parse**, so a re-upload allocates nothing.
+   `src/routes/library.test.ts` leans on this ordering to exercise the duplicate
+   path without touching the library directory.
+6. `parseBook` + `prepareCover` in a **single-shot Worker** (`parseBookInWorker`,
+   `src/workers/parse-client.ts` → `parse-worker.ts`), gated by `parseSemaphore`.
+   These are the only whole-file, CPU-bound steps — `parseBook` holds the full
+   buffer (fflate reads a ZIP's central directory from the end of one contiguous
+   array) and `prepareCover` rasterizes synchronously — so running them inline
+   stalled the request process's event loop; a Worker per upload moves both off
+   it. The file is read inside the Worker from the temp path, so nothing large
+   crosses the thread boundary. `UPLOAD_PARSE_CONCURRENCY` (2) still bounds
+   concurrency — now the number of **live Workers**, hence the native memory
+   across them — and it is **per process**: at the deployed `WEB_CONCURRENCY=3`
+   the ceiling is `2 × 3 × 100 MB ≈ 630 MB`, against a previously _unbounded_
+   ~200–400 MB per in-flight upload. The Worker is terminated on every path
+   (reply, error, or the 60s deadline); the semaphore sheds excess as `busy`
+   (503) rather than spawning Workers without limit.
+7. Cover gated on `prepareCover`, always (rasterizes SVG, then validates). `coverPath IS NOT NULL` is the only
+   signal driving `coverUrl` on the web library, the OPDS feed and the XRPC book
+   view, so an unvalidated cover is a dead URL and a blank box in all three.
+8. **The quota `SUM` is evaluated inside the INSERT's `WHERE`.** SQLite
+   serialises writers, so this is exact — two concurrent uploads cannot both
+   observe the pre-insert total. A per-process mutex would not have worked:
+   production is three independent processes against one file. The statement
+   also carries `ON CONFLICT (userDid, contentHash) DO NOTHING`, so two uploads
+   of the same file racing past the duplicate check report `duplicate` instead
+   of raising a UNIQUE violation; the two zero-row outcomes are told apart by
+   re-reading the row.
+9. `rename` into place — same filesystem, zero bytes copied. The row commits
+   _before_ the bytes move, which beats writing 100 MB and then discovering a
+   problem.
+
+Sync-doc linking is **exact first, fuzzy only on a miss**. The XRPC path used to
+run `matchSyncDocument` first, which let a title/author guess beat a byte-exact
+`documentHash` — wrong, and it paid for up to four FTS queries on the common
+path. Newly-linked documents also get their **already-recorded progress
+bridged**, which is why the core takes `kv`.
+
+Errors are a **discriminated result, never a throw** — `processBookUpload` threw
+`XRPCError` from a util, so a Hono route had to catch an HTTP-shaped exception
+and translate it back. Each adapter owns its own status codes; the XRPC mapping
+is `uploadErrorFor` in the router, the HTTP one is the `switch` in
+`src/routes/library.tsx`.
+
+**Storage quota** is `SUM(personal_book.sizeBytes)` per user, derived rather than
+counted: the quota itself bounds the row count (~700 rows at 2 GB over a ~3 MB
+median epub), `idx_personal_book_user_size` (migration 023) makes it index-only,
+and a derived total cannot drift. A counter would need a backfill, decrements in
+both delete paths and a repair job — and `removeBookDir` is best-effort, so a
+failed `rm` after a row delete would under-report forever while the disk filled.
+**The quota counts book bytes only; stored covers are extra.** Measured on
+production they add **~12%** on top (13.4 MiB of covers against 110.4 MiB of
+books), so a user at a 2 GB quota occupies closer to 2.25 GB of disk — size the
+volume accordingly rather than assuming the quota is the ceiling.
+Over-quota is **413** (not 507, which proxies retry as a server fault; not 403,
+which reads as auth) with `{error, code, usedBytes, quotaBytes}` — the iOS app
+renders `payload.error` verbatim for any non-2xx, so already-installed builds
+show the message with no update shipped.
+
+**Cover extraction is two-pass** (`bookMetadata/epub.ts`, `cbz.ts`). fflate's
+`UnzipFileFilter` returning `false` still walks the central directory, so pass 1
+indexes every image's name and `originalSize` for free and pass 2 inflates
+exactly the chosen one, gated on `MAX_COVER_BYTES`. Both parsers used to inflate
+_every_ image in the archive to keep one — a 100 MB CBZ decompressed ~100 MB of
+pages to keep page 1.
+
+**An SVG cover is a composition, not a wrapper — it must be rasterized.**
+`prepareCover` (`bookMetadata/cover.ts`) is the one gate between "the parser
+found something" and "we store a cover", and it renders SVG through
+`@resvg/resvg-js` before validating. Standard Ebooks — one of the largest
+sources of public-domain EPUBs — ships every cover as an SVG holding the artwork
+in an `<image>` element _plus_ the title and author as ~40 vector `<path>`s over
+a translucent band. Both shortcuts lose half the cover, and both were tried:
+pulling the embedded base64 raster back out drops the lettering, and rendering
+with `@takumi-rs` (already a dependency, so tempting) drops the artwork — it
+ignores the embedded `<image>` entirely.
+
+Three things hold this together:
+
+- **Dimension checks use `image-meta`, not `Bun.Image`.** Bun's pipeline rejects
+  SVG as an "unrecognised format", which is what made every Standard Ebooks
+  upload land with no cover at all. The two agree exactly on every raster
+  format; `image-meta` just knows more of them, and parses headers only.
+- **The output is JPEG, never SVG.** OPDS clients and e-readers can't be relied
+  on to render vector covers, and an SVG served from our own origin is
+  script-capable where a JPEG is inert (there is no CSP anywhere in this app).
+  Rasterizing at `SVG_RASTER_WIDTH` (700 — the largest a cover is ever displayed
+  is ~300 CSS px) then encoding to JPEG turns a 1.1 MB `resvg` PNG into ~77 KB.
+- **`@resvg/resvg-js*` is in `traceDeps`** (`vite.config.ts`) alongside
+  `@takumi-rs/core*`. Native NAPI bindings never appear in the Rolldown graph,
+  and a missing one here does **not** crash — `prepareCover` catches and returns
+  null — so an untraced build silently uploads every Standard Ebooks book with
+  no cover, which is exactly the bug it was added to fix.
+
+Rasterizing runs inside the parse Worker (step 6), next to the ZIP parse and
+under the same `parseSemaphore`, so `UPLOAD_PARSE_CONCURRENCY` bounds all of an
+upload's native memory rather than just the file buffer. `resvg` renders
+synchronously (~0.5s at width 700, ~2.4s at 1400 — the cost scales with the
+square of the width, which is the other reason 700 is the cap); running it on
+the Worker rather than the request thread is why that synchronous cost no longer
+stalls the event loop. `@resvg/resvg-js` is bundled into the standalone Worker
+by `bun build` (its `.node` binding is emitted alongside `parse-worker.js`), the
+same way the OG worker ships takumi's.
 
 ## Types & Constants
 
@@ -478,7 +680,7 @@ SQLite-backed unstorage. Mounts: `search:` (in-memory LRU), `profile:`, `identit
 | `src/bsky/bookLookup.ts`  | Book identifier lookup + transformation                          |
 | `src/bsky/lexicon/`       | Generated types + validators from lexicon schemas                |
 | `src/xrpc/router.ts`      | All `/xrpc/*` methods                                            |
-| `lexicons/*.json`         | AT Protocol lexicon definitions (~27 files)                      |
+| `lexicons/*.json`         | AT Protocol lexicon definitions (44 files)                       |
 | `lex.config.ts`           | Lexicon codegen config (`bun run lexgen`)                        |
 
 **Records**: Books `buzz.bookhive.book`, buzzes `buzz.bookhive.buzz`, lists `social.popfeed.feed.list`/`.listItem`, follows `app.bsky.graph.follow`.
@@ -487,10 +689,53 @@ SQLite-backed unstorage. Mounts: `search:` (in-memory LRU), `profile:`, `identit
 
 **XRPC list procedures**: `createList`, `updateList`, `deleteList`, `addToList`, `removeFromList`, `reorderList`.
 
-**XRPC personal library queries**: `getPersonalLibrary`, `getPersonalBook`, `getSyncProgress`, `listSyncDocuments`.
+**XRPC personal library queries**: `getPersonalLibrary` (params `limit`/`cursor`/`shelfId`/`q`/`sort`; output carries `storage`), `getPersonalBook`, `getPersonalBookFile`, `getPersonalBookCover`, `listPersonalShelves`, `getSyncProgress`, `listSyncDocuments`.
+
+**Every `getPersonalLibrary` sort ends on `personal_book.id`.** None of the
+leading keys are unique: titles and authors collide routinely (a series, an
+omnibus, the same book in two formats), and `createdAt` — millisecond-precision
+ISO — collides when two uploads commit in the same millisecond. SQLite may order
+ties differently between two `LIMIT`/`OFFSET` queries, so without a unique final
+key a book appears on two consecutive pages while another never appears at all.
+Same reasoning applies to any new sort added here.
 
 **XRPC personal library procedures**: `uploadPersonalBook`, `deletePersonalBook`, `linkPersonalBook`, `unlinkPersonalBook`, `putSyncProgress`, `createPersonalShelf`, `updatePersonalShelf`, `deletePersonalShelf`, `addToPersonalShelf`, `removeFromPersonalShelf`.
 
+**The personal library is fully reachable over XRPC, not just over `/opds`.** Parity map:
+
+| OPDS route                          | XRPC method                                        |
+| ----------------------------------- | -------------------------------------------------- |
+| `GET /opds` (root nav + counts)     | `listPersonalShelves` — the root call, one request |
+| `GET /opds/all`                     | `getPersonalLibrary`                               |
+| `GET /opds/shelves/:id`             | `getPersonalLibrary?shelfId=`                      |
+| `GET /opds/search/results`          | `getPersonalLibrary?q=&sort=title` (same SQL)      |
+| `GET /opds/books/:hash/download`    | `getPersonalBookFile`                              |
+| `GET /opds/books/:hash/cover`       | `getPersonalBookCover`                             |
+| `GET /opds/search` (OpenSearch doc) | n/a — an XRPC client reads the lexicon instead     |
+
+**Two methods declare non-JSON bodies**, which is what makes upload and download work at all:
+
+- `uploadPersonalBook` — `input.encoding` is an explicit ebook MIME list **plus
+  `application/octet-stream`**, and the filename is a required **query param**
+  (it replaced an `x-file-name` header that defaulted to `"unknown"`). Two
+  things to know before touching this: `@atcute/lex-cli` emits **no MIME
+  validator at all** when the encoding is exactly `*/*` (which is what the old
+  lexicon said), and `constructMimeValidator` is **exact-match** — `image/*` in
+  an encoding list is a literal, not a wildcard, so every type must be
+  enumerated. `octet-stream` is in the list deliberately: the iOS app sends
+  `type: mime || "application/octet-stream"`, mobile document pickers report it
+  for `.epub`, and `curl --data-binary` sends form-urlencoded. The declared
+  type is client-asserted and worthless as a control — **`detectFormat`
+  checking magic bytes against the filename's extension is the real gate**, and
+  `filename` is required because `.epub`/`.cbz`/`.fb2.zip` are all zip
+  containers that nothing else can tell apart.
+- `getPersonalBookFile` / `getPersonalBookCover` — blob outputs, so the handler
+  returns a bare `Response` and owns every header (the `json()` helper is only
+  typed for lex outputs, and the router sets no Content-Type for you). Both are
+  in `ETAG_EXCLUDED_PREFIXES` and skipped by `compress()` in `src/app.ts`, by
+  **exact NSID path** rather than a `/xrpc/` prefix — the prefix would cost the
+  other ~35 JSON methods their 304s.
+
 ## Scrapers (`src/scrapers/`)
 
 | File               | Purpose                                        |
@@ -545,6 +790,65 @@ currently fails from the production host but not from a residential IP.
 
 **Key constraint**: `guardedRestore` wraps every OAuth restore in a 5s timeout + circuit breaker keyed by the authorization-server host. `getSessionAgent` only destroys sessions on terminal credential errors, never on timeouts.
 
+### XRPC auth (`src/xrpc/auth.ts`)
+
+`/xrpc/*` accepts **two** credentials, resolved by `resolveXrpcAuth`:
+
+- the `sid` iron-session cookie (web + iOS, unchanged);
+- an **atproto inter-service auth JWT** as `Authorization: Bearer <token>`
+  ([spec](https://atproto.com/specs/xrpc#inter-service-authentication-jwt)) —
+  the client calls `com.atproto.server.getServiceAuth` on its own PDS with
+  `aud` and `lxm`, and we verify with `ServiceJwtVerifier` from
+  `@atcute/xrpc-server/auth`. This is what makes the personal library usable
+  from a script or an e-reader rather than only from a browser session.
+
+Bearer wins when both are present. A method declares what it needs with
+`auth: "identity" | "pdsWrite"` on its registration, and the wrapper in
+`createXrpcRouter` **derives the `lxm` from the schema's own NSID**, so a
+method's route and its token binding cannot drift apart. Handlers then read
+`getAuth()` / `requireAgent()` instead of repeating a `getSessionAgent()`
+preamble.
+
+- `identity` — we only need the DID. Every personal-library and sync method:
+  none of them touch the agent for anything but `.did` (progress bridging
+  writes `user_book` and queues a deferred PDS write via `sync_pending:`).
+- `pdsWrite` — writes a record to the user's repo, so it needs a live OAuth
+  session. **Service auth can never satisfy this** — it proves key control, not
+  that we hold a grant. Only the six book-list procedures.
+
+Three things that are load-bearing and easy to get wrong:
+
+- **`acceptAudiences` is exact string `Array.includes`.** A bare DID does _not_
+  match a `DID#fragment` audience, so both spellings are listed. The fragment
+  is there in advance of a PLC operation adding a `#bookhive_appview` service
+  entry; the live DID document has only `#atproto_pds`, so **PDS proxying via
+  `atproto-proxy` cannot work today** and clients must mint a token and POST to
+  us directly.
+- **`SERVICE_AUTH_MAX_AGE_SECONDS` is 3600, not atcute's 300** (a constant in
+  `src/context.ts`). A PDS mints up to an hour when `lxm` is set and most SDKs
+  don't expose `exp`, so the stricter default rejects ordinary tokens as
+  `JwtTooOld`. The token's own `exp` is still enforced separately.
+- **There is no prior-relationship gate.** A valid service token from _any_ DID
+  on the network is accepted — we deliberately do not require that the DID has
+  signed in to BookHive before. BookHive signup is open, so such a gate bought
+  little, and the **per-user storage quota** (`PERSONAL_LIBRARY_QUOTA_BYTES`) is
+  the real backstop on what a caller can consume. `pdsWrite` methods are still
+  refused (service auth proves key control, not an OAuth grant), so the exposure
+  is bounded to the identity/personal-library surface.
+
+`lexicons/auth.json` carries the `rpc` permission that lets a client mint these
+tokens at all; **`GRANULAR_SCOPES` in `src/auth/client.ts` must move with it**
+(it is the `USE_PERMISSION_SETS = false` fallback, and granting in only one
+place silently drops it for whichever path is live). Note that adding `rpc`
+permissions means **existing users must re-consent** before their PDS will
+issue tokens for these methods.
+
+There is **no replay protection**: a token is already scoped to one `lxm` and
+one audience, and within its short `SERVICE_AUTH_MAX_AGE_SECONDS` window a reused
+one authenticates the same DID it always did. Service auth is also **always on**
+— there is no kill-switch env var; the cookie path is unaffected by it either
+way.
+
 ## Middleware (`src/middleware/`)
 
 Applied globally in `src/app.ts`. Key middleware:
@@ -615,16 +919,59 @@ Keep selected/current states tinted and leave the solid fill to real actions.
 | `bun run lint`      | Same as typecheck (oxlint/oxfmt via vp, **not** tsc)         |
 | `bun run format`    | `vp fmt`                                                     |
 | `bun run lexgen`    | Regenerate AT Protocol XRPC types from lexicons              |
-| `bun run seed:db`   | Seed/initialize the DB (`src/initialize.ts`)                 |
 
-**Build pipeline**: Vite+ wrapping Vite 8 + Rolldown + Nitro (preset `bun`). Production builds use custom entry `server/entry.bun.mjs` (adds `reusePort: true`). Docker CMD is `server/cluster.ts` under `tini` init. The `standaloneBundles()` Vite plugin builds 4 worker entry points into `.output/server/workers/`. TypeScript type checking via **tsgo** (TS 6.x); linting via **oxlint**, formatting via **oxfmt**, both through the `vp` CLI. Path alias `@` → `./src`. Runtime requires `bun >= 1.3.14`. Pre-commit hook runs `vp staged` → `vp check --fix`.
+**Build pipeline**: Vite+ wrapping Vite 8 + Rolldown + Nitro (preset `bun`). Production builds use custom entry `server/entry.bun.mjs` (adds `reusePort: true`). Docker CMD is `server/cluster.ts` under `tini` init. The `standaloneBundles()` Vite plugin builds 6 worker entry points into `.output/server/workers/` — the five under `src/workers/` (including the single-shot `parse-worker.ts`) plus `src/scrapers/waf/solver-worker.ts`. TypeScript type checking via **tsgo** (TS 6.x); linting via **oxlint**, formatting via **oxfmt**, both through the `vp` CLI. **Do not use `@/…` in `src/` or `server/`.** `vite.config.ts` maps `@` → `./src`, but the root `tsconfig.json` has no matching `paths`, so tsgo cannot resolve it and the import fails typecheck while bundling fine. Nothing in `src/`/`server/` uses it today; the alias that _is_ live is `app/`'s own `@/*` → `app/*`, declared in `app/tsconfig.json`. Runtime requires `bun >= 1.3.14`. Pre-commit hook runs `vp staged` → `vp check --fix`.
 
 Notable deps: hono, kysely, zod 4, iron-session, unstorage + ocache, `@atcute/*`, `@takumi-rs/image-response` + React 19 (OG only), pino, `@hono/prometheus`, `@opentelemetry/*`, basecoat-css, envalid.
 
+**`bunfig.toml` preloads `src/test/env-setup.ts`, and that is load-bearing.**
+envalid freezes `env` at import, so `DB_PATH`/`LIBRARY_DIR` can only be set
+before the import graph loads. Without it `DB_PATH` falls back to `":memory:"`,
+`getLibraryDir()` resolves to **`./library` inside the checkout**, and any test
+exercising an upload writes ebooks into the working tree.
+
+Related trap, since it cost real debugging time: **`mock.module("../env", …)` is
+process-wide and permanent.** Returning a bare object from it replaces `env` for
+every module loaded afterwards in the same run, so every field the mock doesn't
+name reads back as `undefined`. `src/auth/session.test.ts` and
+`token-refresh.test.ts` spread the real env for exactly this reason — the
+failure shows up in an unrelated file that passes in isolation.
+
 ## iOS App (`app/`)
 
 Separate Expo/React Native workspace — see `app/ARCHITECTURE.md`. Consumes personal-library and KOSync surfaces (XRPC `*PersonalBook`/`*PersonalShelf` methods, REST `/library/*`, `/settings/sync/*`, `POST /library/upload`).
 
+**The app renders `payload.error` verbatim for any non-2xx upload response**, which is why the quota rejection is a 413 carrying human prose rather than a bare code — already-installed builds show the right message with nothing shipped. It reads `storage` off `getPersonalLibrary` for its own meter and pre-flight check, so **anything that changes the quota's wire shape needs an app release**, unlike the message text. `app/utils/personalLibrary.ts` `formatBytes` is a deliberate byte-for-byte copy of the server's; if they diverge, the 413 alert and the meter under it disagree about how full the library is.
+
+## Third-party clients (service auth)
+
+What to tell someone who wants to script against the personal library:
+
+```http
+# 1. Mint a token on YOUR OWN PDS, bound to one method and one audience.
+#    exp should be short; one token per call is what Bluesky's own PDS does.
+GET  https://<your-pds>/xrpc/com.atproto.server.getServiceAuth
+       ?aud=did:plc:enu2j5xjlqsjaylv3du4myh4
+       &lxm=buzz.bookhive.uploadPersonalBook
+       &exp=<now + 60>
+  -> { "token": "..." }
+
+# 2. Call BookHive directly with it. `filename` is a required query param and
+#    the body is the raw file — no multipart wrapper.
+POST https://bookhive.buzz/xrpc/buzz.bookhive.uploadPersonalBook?filename=Dune.epub
+  Authorization: Bearer <token>
+  Content-Type: application/epub+zip
+  <raw bytes>
+```
+
+Notes worth passing on: `lxm` is **required** (atcute's parser rejects a token
+without it); the audience must match one of `acceptAudiences` **exactly**;
+`atproto-proxy` will not work until the DID document gains an AppView service
+entry. There is no requirement that the account have used BookHive before — any
+valid token is accepted, bounded by the per-user storage quota. The OAuth client
+must have been granted the `rpc:buzz.bookhive.*` scopes, which means **existing
+users need to re-consent** before their PDS will issue these tokens.
+
 ## Workers, Logging & Observability
 
 | Path                                 | Purpose                                                 |
diff --git a/app/ARCHITECTURE.md b/app/ARCHITECTURE.md
index d044539..1711cae 100644
--- a/app/ARCHITECTURE.md
+++ b/app/ARCHITECTURE.md
@@ -56,9 +56,34 @@ an `ActionSheet` (match/unmatch, shelves, delete) — there is no in-app reader,
 Native stream the file off disk and drive a determinate progress bar from
 `XMLHttpRequest.upload.onprogress`.
 
+**Storage quota.** Every `getPersonalLibrary` page carries a `storage`
+`{usedBytes, quotaBytes}`, so `StorageMeter` stays current off the queries the
+screen already runs — there is no separate usage request and nothing extra to
+invalidate. Three guards hang off it, in increasing order of how much they cost
+the user to hit:
+
+- The upload button dims and explains itself when the library is full, rather
+  than being `disabled` — a dead control in a header answers no questions.
+- A picked file larger than the remaining quota is refused before a byte goes
+  over the wire. This is a _hint_, not the rule: `storage` is as old as the last
+  fetch, and the server evaluates the quota inside the INSERT.
+- A 413 that gets through arrives as an `UploadError` with
+  `code: "QuotaExceeded"`, whose message is the server's own prose (rendered
+  verbatim) and which triggers a library refetch, because a rejection means the
+  meter was showing room that wasn't there.
+
+`quotaBytes <= 0` means the deployment has quotas switched off, and so does an
+older server that sends no `storage` at all; both must read as "no ceiling",
+never as "full", or every upload on such a server would be blocked client-side.
+
 **`/sync`** shows a connection-status card (derived from whether any documents
 have synced), the KOSync server URL, OPDS catalog URL, username and derived
-password with reveal/copy/reset, and the six KOReader setup steps.
+password with reveal/copy/reset, and the seven KOReader setup steps. One of those
+steps is load-bearing rather than cosmetic: KOReader's "Send document metadata"
+toggle defaults to **off**, and with it off a sync request identifies the book by
+a single partial-MD5 hash, so a book the user never uploaded here has nothing to
+match against. The web setup instructions say the same thing — keep the two lists
+in step.
 
 Sync documents are surfaced in three places by state: `hasFile` → folded into
 the grid card that shares its content hash; unmatched → triage strip; matched or
@@ -91,6 +116,7 @@ dismissed → "Also tracking".
 | Hook                                                       | Purpose                                        |
 | ---------------------------------------------------------- | ---------------------------------------------- |
 | `usePersonalLibrary(shelfId?)`                             | Infinite query of uploaded books (24/page)     |
+| `storageFromLibrary(data)`                                 | Storage usage out of a library result (helper) |
 | `usePersonalShelves()`                                     | Shelves with book counts                       |
 | `useSyncDocuments()`                                       | Synced e-reader documents                      |
 | `useSyncPassword()` / `useRotateSyncPassword()`            | Derived KOSync/OPDS password, and rotating it  |
@@ -102,7 +128,9 @@ dismissed → "Also tracking".
 | `useLinkSyncDocument()` / `useDismissSyncDocument()`       | Match a document, or mark it "not on BookHive" |
 | `useRenameSyncDocument()` / `useDeleteSyncDocument()`      | Rename / forget a document (both optimistic)   |
 
-Exported types: `PersonalBook`, `PersonalShelf`, `SyncDoc`.
+Exported types: `PersonalBook`, `PersonalShelf`, `PersonalStorage`, `SyncDoc`, and
+`UploadError` (a real class — it carries the server's `code`, so a caller can
+tell a quota rejection from a dropped connection and act on it).
 
 ### Context Providers
 
@@ -184,6 +212,7 @@ Exported types: `PersonalBook`, `PersonalShelf`, `SyncDoc`.
 | `DeleteConfirmationModal` | Delete confirmation dialog      |
 | `DatePickerModal`         | Date picker for reading dates   |
 | `PersonalBookCard`        | Grid card for an uploaded file  |
+| `StorageMeter`            | Library storage used vs. quota  |
 | `BookSearchModal`         | Catalog picker for matching     |
 
 ### Layout & Navigation
diff --git a/app/app/(tabs)/library/index.tsx b/app/app/(tabs)/library/index.tsx
index 98ac841..3eddb64 100644
--- a/app/app/(tabs)/library/index.tsx
+++ b/app/app/(tabs)/library/index.tsx
@@ -22,6 +22,7 @@ import { BookSearchModal } from "@/components/BookSearchModal";
 import { PersonalBookCard } from "@/components/PersonalBookCard";
 import { ProgressBar } from "@/components/ProgressBar";
 import { QueryErrorHandler } from "@/components/QueryErrorHandler";
+import { StorageMeter } from "@/components/StorageMeter";
 import { TextPromptModal } from "@/components/TextPromptModal";
 import { ThemedText } from "@/components/ThemedText";
 import { ThemedView } from "@/components/ThemedView";
@@ -44,13 +45,19 @@ import {
   useUnlinkPersonalBook,
   useUpdatePersonalShelf,
   useUploadPersonalBook,
+  storageFromLibrary,
   type PersonalBook,
   type PersonalShelf,
   type SyncDoc,
 } from "@/hooks/useBookhiveQuery";
 import { useColorScheme } from "@/hooks/useColorScheme";
 import { useThemeColor } from "@/hooks/useThemeColor";
-import { formatAuthors, progressFraction } from "@/utils/personalLibrary";
+import {
+  formatAuthors,
+  formatBytes,
+  formatFileSize,
+  progressFraction,
+} from "@/utils/personalLibrary";
 import type { HiveBook } from "../../../../src/types";
 
 /** Mirrors the formats the upload route accepts (`ACCEPTED_EXTENSIONS`). */
@@ -123,6 +130,14 @@ export default function LibraryScreen() {
   const shelves = shelvesQuery.data ?? [];
   const documents = documentsQuery.data ?? [];
 
+  // Storage rides along on every library page, so this is current as of the
+  // last fetch without a request of its own. `quotaBytes <= 0` means the
+  // deployment has the quota switched off — treat that as "no ceiling", never
+  // as "full", or the upload button would lock out every user on such a server.
+  const storage = storageFromLibrary(allBooksQuery.data);
+  const hasQuota = storage != null && storage.quotaBytes > 0;
+  const isLibraryFull = hasQuota && storage.usedBytes >= storage.quotaBytes;
+
   // A document whose content hash matches an upload is already on screen as a
   // grid card, so the sync sections only cover documents with no file.
   const looseDocuments = useMemo(() => documents.filter((doc) => !doc.hasFile), [documents]);
@@ -148,6 +163,17 @@ export default function LibraryScreen() {
   // ── Upload ──
 
   const handleUpload = useCallback(async () => {
+    // Refuse before opening the picker rather than disabling the button: a
+    // greyed-out icon in a header explains nothing, and "why can't I upload"
+    // is exactly the question the message answers.
+    if (storage && storage.quotaBytes > 0 && storage.usedBytes >= storage.quotaBytes) {
+      Alert.alert(
+        "Library full",
+        `You've used ${formatBytes(storage.usedBytes)} of your ${formatBytes(storage.quotaBytes)}. Delete a book to free up space.`,
+      );
+      return;
+    }
+
     const picked = await DocumentPicker.getDocumentAsync({
       // iOS reports no useful MIME type for most ebook formats, so accept
       // everything and check the extension ourselves — a clear message beats a
@@ -170,6 +196,21 @@ export default function LibraryScreen() {
       return;
     }
 
+    // The server is still the authority — this copy of `storage` is as old as
+    // the last library fetch, and the quota is evaluated inside the INSERT. But
+    // pushing 80 MB over a cellular connection to be told there was never room
+    // for it is the failure worth spending two lines to avoid.
+    if (storage && storage.quotaBytes > 0 && asset.size != null) {
+      const free = Math.max(0, storage.quotaBytes - storage.usedBytes);
+      if (asset.size > free) {
+        Alert.alert(
+          "Not enough space",
+          `“${asset.name}” is ${formatBytes(asset.size)}, but only ${formatBytes(free)} of your ${formatBytes(storage.quotaBytes)} is free. Delete a book to make room.`,
+        );
+        return;
+      }
+    }
+
     setUploadName(asset.name);
     setUploadProgress(0);
     upload.mutate(
@@ -195,7 +236,7 @@ export default function LibraryScreen() {
         },
       },
     );
-  }, [upload]);
+  }, [upload, storage]);
 
   // ── Book actions ──
 
@@ -206,7 +247,9 @@ export default function LibraryScreen() {
       // it loses its file and reappears in the sync sections. Say so.
       Alert.alert(
         "Delete this file?",
-        `“${book.title}” will be removed from your library and your OPDS catalog.` +
+        `“${book.title}” will be removed from your library and your OPDS catalog` +
+          (book.sizeBytes ? `, freeing ${formatFileSize(book.sizeBytes)}` : "") +
+          "." +
           (book.progress
             ? " Your e-reader progress is kept and moves down to “Also tracking”."
             : "") +
@@ -612,6 +655,8 @@ export default function LibraryScreen() {
 
   const renderHeader = () => (
     <View>
+      <StorageMeter storage={storage} />
+
       {renderShelfTabs()}
 
       {needsTriage.length > 0 ? (
@@ -771,12 +816,19 @@ export default function LibraryScreen() {
             onPress={handleUpload}
             disabled={upload.isPending}
             hitSlop={8}
-            accessibilityLabel="Upload a book"
+            accessibilityLabel={isLibraryFull ? "Upload a book — library full" : "Upload a book"}
+            // Dimmed, not disabled: pressing it explains that the library is
+            // full, which a dead control can't.
+            style={isLibraryFull ? styles.uploadFull : undefined}
           >
             {upload.isPending ? (
               <ActivityIndicator size="small" color={colors.primary} />
             ) : (
-              <Ionicons name="add-circle" size={28} color={colors.primary} />
+              <Ionicons
+                name="add-circle"
+                size={28}
+                color={isLibraryFull ? colors.tertiaryText : colors.primary}
+              />
             )}
           </Pressable>
         }
@@ -905,6 +957,9 @@ export default function LibraryScreen() {
                     }`
                   : null,
                 bookSheet.hiveId ? "Linked to BookHive" : "Not linked",
+                // Worth the space now that there is a quota: "which of these do
+                // I delete to make room" is unanswerable without it.
+                formatFileSize(bookSheet.sizeBytes),
               ]
                 .filter(Boolean)
                 .join(" · ")
@@ -1026,6 +1081,9 @@ const styles = StyleSheet.create({
     alignItems: "center",
     justifyContent: "center",
   },
+  uploadFull: {
+    opacity: 0.6,
+  },
   uploadStrip: {
     marginHorizontal: 16,
     marginBottom: 8,
diff --git a/app/app/(tabs)/sync/index.tsx b/app/app/(tabs)/sync/index.tsx
index 790fb2d..cc9b70e 100644
--- a/app/app/(tabs)/sync/index.tsx
+++ b/app/app/(tabs)/sync/index.tsx
@@ -19,11 +19,19 @@ import { useRotateSyncPassword, useSyncDocuments, useSyncPassword } from "@/hook
 import { useColorScheme } from "@/hooks/useColorScheme";
 import { useThemeColor } from "@/hooks/useThemeColor";
 
+/**
+ * The metadata step is not cosmetic. KOReader's "Send document metadata" toggle
+ * defaults to off, and with it off a sync request identifies the book by one
+ * partial-MD5 hash and nothing else — so for a file the user never uploaded
+ * here, there is nothing to match a catalog entry against. Turning it on is the
+ * difference between progress landing on the right book and landing nowhere.
+ */
 const SETUP_STEPS = [
   "Open a book on your KOReader device.",
   "Go to Settings → Progress sync → Custom sync server.",
   "Enter the sync server URL above.",
   "Choose Login and enter the username and password above.",
+  "Turn on “Send document metadata” in the same menu — it’s off by default, and it’s what lets BookHive match books you haven’t uploaded here.",
   "Tap “Push progress from this device now” to test it.",
   "For your uploads, add the OPDS catalog URL in KOReader’s OPDS browser with the same login.",
 ];
diff --git a/app/components/StorageMeter.tsx b/app/components/StorageMeter.tsx
new file mode 100644
index 0000000..6bd30ba
--- /dev/null
+++ b/app/components/StorageMeter.tsx
@@ -0,0 +1,70 @@
+import React from "react";
+import { StyleSheet, View } from "react-native";
+
+import { ProgressBar } from "@/components/ProgressBar";
+import { ThemedText } from "@/components/ThemedText";
+import { Colors } from "@/constants/Colors";
+import type { PersonalStorage } from "@/hooks/useBookhiveQuery";
+import { useColorScheme } from "@/hooks/useColorScheme";
+import { formatBytes } from "@/utils/personalLibrary";
+
+/** Fill ratio past which the bar turns amber to warn before the upload fails. */
+const WARN_AT = 0.9;
+
+type StorageMeterProps = {
+  storage: PersonalStorage | null;
+};
+
+/**
+ * Library storage used against the quota — the app's counterpart to the web
+ * `StorageMeter` in `src/client/components/LibraryManager.tsx`.
+ *
+ * Renders nothing without a quota. `quotaBytes <= 0` is how a deployment turns
+ * the quota off, and a meter with no ceiling is noise; an older server that
+ * doesn't send `storage` at all lands in the same branch, which is what keeps
+ * this screen working against one.
+ */
+export function StorageMeter({ storage }: StorageMeterProps) {
+  const colorScheme = useColorScheme();
+  const colors = Colors[colorScheme ?? "light"];
+
+  if (!storage || storage.quotaBytes <= 0) return null;
+
+  const ratio = Math.min(1, storage.usedBytes / storage.quotaBytes);
+  const isFull = storage.usedBytes >= storage.quotaBytes;
+  const barColor = ratio >= WARN_AT ? colors.warning : colors.primary;
+
+  return (
+    <View style={styles.container}>
+      <View style={styles.header}>
+        <ThemedText type="caption" style={{ color: colors.secondaryText }}>
+          {formatBytes(storage.usedBytes)} of {formatBytes(storage.quotaBytes)} used
+        </ThemedText>
+        {isFull ? (
+          <ThemedText type="caption" style={{ color: colors.warning }}>
+            Library full
+          </ThemedText>
+        ) : null}
+      </View>
+      <ProgressBar
+        value={ratio}
+        height={4}
+        color={barColor}
+        trackColor={colors.inactiveBackground}
+      />
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    paddingHorizontal: 16,
+    paddingBottom: 12,
+    gap: 6,
+  },
+  header: {
+    flexDirection: "row",
+    alignItems: "center",
+    justifyContent: "space-between",
+  },
+});
diff --git a/app/hooks/useBookhiveQuery.ts b/app/hooks/useBookhiveQuery.ts
index e13ce00..4d02cab 100644
--- a/app/hooks/useBookhiveQuery.ts
+++ b/app/hooks/useBookhiveQuery.ts
@@ -732,7 +732,19 @@ export type PersonalBook = {
   mime: string;
   sizeBytes: number;
   coverUrl?: string;
+  /**
+   * Whether a cover was extracted from the uploaded file (as opposed to
+   * `coverUrl` pointing at the public catalog image proxy). The app fetches
+   * either form through `personalCoverSource`, which attaches the session
+   * cookie for the local one; this is here because a service-auth client can't
+   * use the local URL at all and has to go through `getPersonalBookCover`.
+   */
+  hasLocalCover?: boolean;
   hiveId?: string;
+  /** Original uploaded file name — what the user sees on their e-reader. */
+  filename?: string;
+  /** Synopsis from the linked catalog entry. Absent until the book is linked. */
+  description?: string;
   createdAt: string;
   updatedAt: string;
   /** Percentage arrives as a decimal string ("0.42") straight from KOSync. */
@@ -740,6 +752,17 @@ export type PersonalBook = {
   shelfIds?: number[];
 };
 
+/**
+ * Per-user storage usage against the quota, returned on every
+ * `getPersonalLibrary` page rather than by a method of its own — the library
+ * screen already refetches that after each mutation, so the meter stays honest
+ * with no extra round-trip and no separate invalidation to keep in sync.
+ */
+export type PersonalStorage = {
+  usedBytes: number;
+  quotaBytes: number;
+};
+
 /** A user-defined shelf grouping personal library books. */
 export type PersonalShelf = {
   id: number;
@@ -783,6 +806,7 @@ export const usePersonalLibrary = (shelfId?: number) => {
         books: PersonalBook[];
         total?: number;
         cursor?: string;
+        storage?: PersonalStorage;
       }>(url);
     },
     getNextPageParam: (lastPage) => lastPage.cursor ?? undefined,
@@ -791,6 +815,21 @@ export const usePersonalLibrary = (shelfId?: number) => {
   });
 };
 
+/**
+ * Storage usage out of a `usePersonalLibrary` result.
+ *
+ * Reads the **last** page, not the first: every page carries a fresh `storage`,
+ * and on a refetch React Query replays the pages in order, so the last one is
+ * the most recently observed. Falling back to the first page covers the
+ * single-page case and a paginated result whose tail hasn't loaded yet.
+ */
+export function storageFromLibrary(
+  data: { pages: { storage?: PersonalStorage }[] } | undefined,
+): PersonalStorage | null {
+  if (!data?.pages.length) return null;
+  return data.pages[data.pages.length - 1]?.storage ?? data.pages[0]?.storage ?? null;
+}
+
 export const usePersonalShelves = () => {
   return useQuery({
     queryKey: ["personalShelves"] as const,
@@ -844,6 +883,34 @@ export const useRotateSyncPassword = () => {
   });
 };
 
+/**
+ * An upload the server refused for a reason it named.
+ *
+ * `code` is the server's closed set of upload failure codes (`TooLarge`,
+ * `QuotaExceeded`, `UnsupportedFormat`, `AlreadyExists`, `EmptyFile`, `NoFile`,
+ * `Busy`). `message` is the server's own prose, which is what the UI shows — the
+ * code is for deciding what to do *besides* showing it, like refreshing the
+ * storage meter after a quota rejection.
+ */
+export class UploadError extends Error {
+  readonly code?: string;
+  readonly status: number;
+  readonly usedBytes?: number;
+  readonly quotaBytes?: number;
+
+  constructor(
+    message: string,
+    init: { code?: string; status: number; usedBytes?: number; quotaBytes?: number },
+  ) {
+    super(message);
+    this.name = "UploadError";
+    this.code = init.code;
+    this.status = init.status;
+    this.usedBytes = init.usedBytes;
+    this.quotaBytes = init.quotaBytes;
+  }
+}
+
 /**
  * Multipart upload with real progress. Goes through XMLHttpRequest rather than
  * the shared fetch wrapper for two reasons: React Native streams a
@@ -894,11 +961,17 @@ function uploadBookFile({
         return;
       }
       reject(
-        new Error(
+        new UploadError(
           payload?.error ||
             (xhr.status === 401
               ? "Your session expired. Sign in again to upload."
               : `Upload failed (${xhr.status})`),
+          {
+            code: payload?.code,
+            status: xhr.status,
+            usedBytes: payload?.usedBytes,
+            quotaBytes: payload?.quotaBytes,
+          },
         ),
       );
     };
@@ -924,6 +997,18 @@ export const useUploadPersonalBook = () => {
       void queryClient.invalidateQueries({ queryKey: ["syncDocuments"] });
       void queryClient.invalidateQueries({ queryKey: ["profile"] });
     },
+    onError: (error) => {
+      // A rejection on these two codes means our copy of the library disagrees
+      // with the server's: the quota bar is showing room that isn't there, or
+      // the grid is missing a book that already exists. Both are worth a
+      // refetch — the user's next action depends on seeing the real state.
+      if (
+        error instanceof UploadError &&
+        (error.code === "QuotaExceeded" || error.code === "AlreadyExists")
+      ) {
+        void queryClient.invalidateQueries({ queryKey: ["personalLibrary"] });
+      }
+    },
     retry: false,
   });
 };
diff --git a/app/utils/personalLibrary.ts b/app/utils/personalLibrary.ts
index 4358d76..88bfdb9 100644
--- a/app/utils/personalLibrary.ts
+++ b/app/utils/personalLibrary.ts
@@ -28,6 +28,21 @@ export function personalCoverSource(
   };
 }
 
+/**
+ * Human-readable byte count at quota scale, e.g. "1.2 GB".
+ *
+ * Deliberately a byte-for-byte port of `formatBytes` in `src/routes/library.tsx`
+ * and `src/client/components/LibraryManager.tsx`: the server bakes this exact
+ * rendering into the 413 body it sends when an upload busts the quota, and the
+ * app shows that message verbatim. If the two round differently, the alert and
+ * the meter directly under it disagree about how full the library is.
+ */
+export function formatBytes(bytes: number): string {
+  if (bytes >= 1024 ** 3) return `${(bytes / 1024 ** 3).toFixed(1)} GB`;
+  if (bytes >= 1024 ** 2) return `${Math.round(bytes / 1024 ** 2)} MB`;
+  return `${Math.round(bytes / 1024)} KB`;
+}
+
 /** Human-readable file size, e.g. "2.4 MB". */
 export function formatFileSize(bytes: number): string {
   if (!bytes || bytes < 0) return "";
@@ -38,7 +53,17 @@ export function formatFileSize(bytes: number): string {
   return `${mb < 10 ? mb.toFixed(1) : Math.round(mb)} MB`;
 }
 
-/** Authors are stored tab-separated throughout BookHive. */
+/**
+ * Render a stored author string as a comma list.
+ *
+ * `personal_book.authors` is not consistently tab-separated, despite what the
+ * lexicon description says: `parseBook` joins the ebook's own creators with
+ * `", "`, while `linkPersonalBook` overwrites the column with `hive_book.authors`,
+ * which is tab-separated. Splitting on tab handles the linked case and leaves the
+ * parsed case alone — it is already a comma list. Do **not** also split on comma
+ * to "fix" the parsed case: EPUB `dc:creator` is frequently "Last, First", and
+ * that would turn one author into two.
+ */
 export function formatAuthors(authors: string | null | undefined): string {
   return (authors ?? "").split("\t").filter(Boolean).join(", ");
 }
diff --git a/bun.lock b/bun.lock
index 6ca5ec0..6ab9b6f 100644
--- a/bun.lock
+++ b/bun.lock
@@ -7,10 +7,12 @@
       "dependencies": {
         "@atcute/password-session": "1.0.1",
         "@atcute/xrpc-server": "2.0.1",
+        "@resvg/resvg-js": "2.6.2",
         "@takumi-rs/image-response": "2.0.2",
         "@voidzero-dev/vite-plus-core": "0.2.2",
         "basecoat-css": "0.3.11",
         "fflate": "0.8.3",
+        "image-meta": "0.2.2",
         "ocache": "0.1.5",
         "pino": "10.3.1",
         "react": "19.2.7",
@@ -21,6 +23,7 @@
         "@atcute/atproto": "4.0.3",
         "@atcute/bluesky": "4.0.13",
         "@atcute/client": "5.1.1",
+        "@atcute/crypto": "2.4.2",
         "@atcute/identity-resolver": "2.0.1",
         "@atcute/identity-resolver-node": "2.0.1",
         "@atcute/jetstream": "2.0.1",
@@ -874,6 +877,32 @@
 
     "@react-native/virtualized-lists": ["@react-native/virtualized-lists@0.85.3", "", { "dependencies": { "invariant": "^2.2.4", "nullthrows": "^1.1.1" }, "peerDependencies": { "@types/react": "^19.2.0", "react": "*", "react-native": "0.85.3" }, "optionalPeers": ["@types/react"] }, "sha512-dsCjI//OIPEUJMyNHp4l7zNLVjCx7bcaRUceOCkU+IB17hkbtbGWvi7HjGFSzy7FJGmS/MOlcfpb72xXiy1Oig=="],
 
+    "@resvg/resvg-js": ["@resvg/resvg-js@2.6.2", "", { "optionalDependencies": { "@resvg/resvg-js-android-arm-eabi": "2.6.2", "@resvg/resvg-js-android-arm64": "2.6.2", "@resvg/resvg-js-darwin-arm64": "2.6.2", "@resvg/resvg-js-darwin-x64": "2.6.2", "@resvg/resvg-js-linux-arm-gnueabihf": "2.6.2", "@resvg/resvg-js-linux-arm64-gnu": "2.6.2", "@resvg/resvg-js-linux-arm64-musl": "2.6.2", "@resvg/resvg-js-linux-x64-gnu": "2.6.2", "@resvg/resvg-js-linux-x64-musl": "2.6.2", "@resvg/resvg-js-win32-arm64-msvc": "2.6.2", "@resvg/resvg-js-win32-ia32-msvc": "2.6.2", "@resvg/resvg-js-win32-x64-msvc": "2.6.2" } }, "sha512-xBaJish5OeGmniDj9cW5PRa/PtmuVU3ziqrbr5xJj901ZDN4TosrVaNZpEiLZAxdfnhAe7uQ7QFWfjPe9d9K2Q=="],
+
+    "@resvg/resvg-js-android-arm-eabi": ["@resvg/resvg-js-android-arm-eabi@2.6.2", "", { "os": "android", "cpu": "arm" }, "sha512-FrJibrAk6v29eabIPgcTUMPXiEz8ssrAk7TXxsiZzww9UTQ1Z5KAbFJs+Z0Ez+VZTYgnE5IQJqBcoSiMebtPHA=="],
+
+    "@resvg/resvg-js-android-arm64": ["@resvg/resvg-js-android-arm64@2.6.2", "", { "os": "android", "cpu": "arm64" }, "sha512-VcOKezEhm2VqzXpcIJoITuvUS/fcjIw5NA/w3tjzWyzmvoCdd+QXIqy3FBGulWdClvp4g+IfUemigrkLThSjAQ=="],
+
+    "@resvg/resvg-js-darwin-arm64": ["@resvg/resvg-js-darwin-arm64@2.6.2", "", { "os": "darwin", "cpu": "arm64" }, "sha512-nmok2LnAd6nLUKI16aEB9ydMC6Lidiiq2m1nEBDR1LaaP7FGs4AJ90qDraxX+CWlVuRlvNjyYJTNv8qFjtL9+A=="],
+
+    "@resvg/resvg-js-darwin-x64": ["@resvg/resvg-js-darwin-x64@2.6.2", "", { "os": "darwin", "cpu": "x64" }, "sha512-GInyZLjgWDfsVT6+SHxQVRwNzV0AuA1uqGsOAW+0th56J7Nh6bHHKXHBWzUrihxMetcFDmQMAX1tZ1fZDYSRsw=="],
+
+    "@resvg/resvg-js-linux-arm-gnueabihf": ["@resvg/resvg-js-linux-arm-gnueabihf@2.6.2", "", { "os": "linux", "cpu": "arm" }, "sha512-YIV3u/R9zJbpqTTNwTZM5/ocWetDKGsro0SWp70eGEM9eV2MerWyBRZnQIgzU3YBnSBQ1RcxRZvY/UxwESfZIw=="],
+
+    "@resvg/resvg-js-linux-arm64-gnu": ["@resvg/resvg-js-linux-arm64-gnu@2.6.2", "", { "os": "linux", "cpu": "arm64" }, "sha512-zc2BlJSim7YR4FZDQ8OUoJg5holYzdiYMeobb9pJuGDidGL9KZUv7SbiD4E8oZogtYY42UZEap7dqkkYuA91pg=="],
+
+    "@resvg/resvg-js-linux-arm64-musl": ["@resvg/resvg-js-linux-arm64-musl@2.6.2", "", { "os": "linux", "cpu": "arm64" }, "sha512-3h3dLPWNgSsD4lQBJPb4f+kvdOSJHa5PjTYVsWHxLUzH4IFTJUAnmuWpw4KqyQ3NA5QCyhw4TWgxk3jRkQxEKg=="],
+
+    "@resvg/resvg-js-linux-x64-gnu": ["@resvg/resvg-js-linux-x64-gnu@2.6.2", "", { "os": "linux", "cpu": "x64" }, "sha512-IVUe+ckIerA7xMZ50duAZzwf1U7khQe2E0QpUxu5MBJNao5RqC0zwV/Zm965vw6D3gGFUl7j4m+oJjubBVoftw=="],
+
+    "@resvg/resvg-js-linux-x64-musl": ["@resvg/resvg-js-linux-x64-musl@2.6.2", "", { "os": "linux", "cpu": "x64" }, "sha512-UOf83vqTzoYQO9SZ0fPl2ZIFtNIz/Rr/y+7X8XRX1ZnBYsQ/tTb+cj9TE+KHOdmlTFBxhYzVkP2lRByCzqi4jQ=="],
+
+    "@resvg/resvg-js-win32-arm64-msvc": ["@resvg/resvg-js-win32-arm64-msvc@2.6.2", "", { "os": "win32", "cpu": "arm64" }, "sha512-7C/RSgCa+7vqZ7qAbItfiaAWhyRSoD4l4BQAbVDqRRsRgY+S+hgS3in0Rxr7IorKUpGE69X48q6/nOAuTJQxeQ=="],
+
+    "@resvg/resvg-js-win32-ia32-msvc": ["@resvg/resvg-js-win32-ia32-msvc@2.6.2", "", { "os": "win32", "cpu": "ia32" }, "sha512-har4aPAlvjnLcil40AC77YDIk6loMawuJwFINEM7n0pZviwMkMvjb2W5ZirsNOZY4aDbo5tLx0wNMREp5Brk+w=="],
+
+    "@resvg/resvg-js-win32-x64-msvc": ["@resvg/resvg-js-win32-x64-msvc@2.6.2", "", { "os": "win32", "cpu": "x64" }, "sha512-ZXtYhtUr5SSaBrUDq7DiyjOFJqBVL/dOBN7N/qmi/pO0IgiWW/f/ue3nbvu9joWE5aAKDoIzy/CxsY0suwGosQ=="],
+
     "@rolldown/binding-android-arm64": ["@rolldown/binding-android-arm64@1.1.1", "", { "os": "android", "cpu": "arm64" }, "sha512-BLf9Wak/gfwVb7NQTQW4wBgL3oAfPy7ArEkhwV543OVw/uY6B47z5xYsqPSZ9PDOorvURPinws6ThaFuNgGLgA=="],
 
     "@rolldown/binding-darwin-arm64": ["@rolldown/binding-darwin-arm64@1.1.1", "", { "os": "darwin", "cpu": "arm64" }, "sha512-rRZRPy/Ynb+Mxu0O6tfPldHeDgAn0sRij+IOUy6sFdUlv3hArGW/DloE3GfAxtqpOJuRNgF74Nr5gM4xBeU2jQ=="],
@@ -1638,6 +1667,8 @@
 
     "ignore": ["ignore@5.3.2", "", {}, "sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g=="],
 
+    "image-meta": ["image-meta@0.2.2", "", {}, "sha512-3MOLanc3sb3LNGWQl1RlQlNWURE5g32aUphrDyFeCsxBTk08iE3VNe4CwsUZ0Qs1X+EfX0+r29Sxdpza4B+yRA=="],
+
     "image-size": ["image-size@1.2.1", "", { "dependencies": { "queue": "6.0.2" }, "bin": { "image-size": "bin/image-size.js" } }, "sha512-rH+46sQJ2dlwfjfhCyNx5thzrv+dtmBIhPHk0zgRUukHzZ/kRueTJXoYYsclBaKcSMBWuGbOFXtioLpzTb5euw=="],
 
     "import-fresh": ["import-fresh@2.0.0", "", { "dependencies": { "caller-path": "^2.0.0", "resolve-from": "^3.0.0" } }, "sha512-eZ5H8rcgYazHbKC3PG4ClHNykCSxtAhxSSEM+2mb+7evD2CKF5V7c0dNum7AdpDh0ZdICwZY9sRSn8f+KH96sg=="],
diff --git a/bunfig.toml b/bunfig.toml
index c9408fd..c8cc8a5 100644
--- a/bunfig.toml
+++ b/bunfig.toml
@@ -4,3 +4,9 @@
 # directories explicitly (`bun test src server`) so app/'s React Native suites,
 # which use the jest preset rather than bun's runner, stay out of the way.
 root = "."
+
+# Runs before src/env.ts is imported, which is the only moment DB_PATH and
+# LIBRARY_DIR can still be set — envalid freezes `env` at import. Without it
+# getLibraryDir() resolves to ./library inside the checkout and upload tests
+# write ebooks into the repo. See src/test/env-setup.ts.
+preload = ["./src/test/env-setup.ts"]
diff --git a/lexicons/auth.json b/lexicons/auth.json
index 63a40f3..10d1f62 100644
--- a/lexicons/auth.json
+++ b/lexicons/auth.json
@@ -5,7 +5,7 @@
     "main": {
       "type": "permission-set",
       "title": "Full BookHive Functionality",
-      "detail": "Track books, write reviews and comments, and manage reading lists",
+      "detail": "Track books, write reviews and comments, manage reading lists, and use your personal ebook library from other apps",
       "permissions": [
         {
           "type": "permission",
@@ -18,6 +18,30 @@
           "resource": "repo",
           "collection": ["buzz.bookhive.buzz"],
           "action": ["create", "update", "delete"]
+        },
+        {
+          "type": "permission",
+          "resource": "rpc",
+          "aud": "*",
+          "lxm": [
+            "buzz.bookhive.getPersonalLibrary",
+            "buzz.bookhive.getPersonalBook",
+            "buzz.bookhive.getPersonalBookFile",
+            "buzz.bookhive.getPersonalBookCover",
+            "buzz.bookhive.listPersonalShelves",
+            "buzz.bookhive.uploadPersonalBook",
+            "buzz.bookhive.deletePersonalBook",
+            "buzz.bookhive.linkPersonalBook",
+            "buzz.bookhive.unlinkPersonalBook",
+            "buzz.bookhive.createPersonalShelf",
+            "buzz.bookhive.updatePersonalShelf",
+            "buzz.bookhive.deletePersonalShelf",
+            "buzz.bookhive.addToPersonalShelf",
+            "buzz.bookhive.removeFromPersonalShelf",
+            "buzz.bookhive.getSyncProgress",
+            "buzz.bookhive.putSyncProgress",
+            "buzz.bookhive.listSyncDocuments"
+          ]
         }
       ]
     }
diff --git a/lexicons/getPersonalBookCover.json b/lexicons/getPersonalBookCover.json
new file mode 100644
index 0000000..7e2c873
--- /dev/null
+++ b/lexicons/getPersonalBookCover.json
@@ -0,0 +1,36 @@
+{
+  "lexicon": 1,
+  "id": "buzz.bookhive.getPersonalBookCover",
+  "defs": {
+    "main": {
+      "type": "query",
+      "description": "Cover image for a book in the authenticated user's personal library. Serves the cover extracted from the uploaded file when there is one; otherwise, if the book is linked to a BookHive catalog entry, responds 302 to the public image proxy for that entry. The XRPC equivalent of GET /opds/books/{hash}/cover.",
+      "parameters": {
+        "type": "params",
+        "required": ["contentHash"],
+        "properties": {
+          "contentHash": {
+            "type": "string",
+            "description": "Content hash identifying the book"
+          },
+          "width": {
+            "type": "integer",
+            "description": "Requested width in pixels for the catalog-cover redirect. Ignored for locally stored covers, which are served at the size they were extracted at.",
+            "minimum": 32,
+            "maximum": 1024,
+            "default": 300
+          }
+        }
+      },
+      "output": {
+        "encoding": "image/jpeg,image/png,image/gif,image/webp"
+      },
+      "errors": [
+        {
+          "name": "NotFound",
+          "description": "No such book, or the book has neither a stored cover nor a linked catalog entry"
+        }
+      ]
+    }
+  }
+}
diff --git a/lexicons/getPersonalBookFile.json b/lexicons/getPersonalBookFile.json
new file mode 100644
index 0000000..d2a6f70
--- /dev/null
+++ b/lexicons/getPersonalBookFile.json
@@ -0,0 +1,29 @@
+{
+  "lexicon": 1,
+  "id": "buzz.bookhive.getPersonalBookFile",
+  "defs": {
+    "main": {
+      "type": "query",
+      "description": "Download the raw ebook file for a book in the authenticated user's personal library. Responds with the stored bytes, a strong ETag equal to the content hash, and a `Content-Disposition: attachment` filename. Honours `If-None-Match` with a 304, so an e-reader syncing on a schedule does not re-download every book. The XRPC equivalent of GET /opds/books/{hash}/download.",
+      "parameters": {
+        "type": "params",
+        "required": ["contentHash"],
+        "properties": {
+          "contentHash": {
+            "type": "string",
+            "description": "Content hash identifying the book, as returned by getPersonalLibrary"
+          }
+        }
+      },
+      "output": {
+        "encoding": "application/epub+zip,application/x-mobipocket-ebook,application/x-fictionbook+xml,application/vnd.comicbook+zip,application/octet-stream"
+      },
+      "errors": [
+        {
+          "name": "NotFound",
+          "description": "No such book in the caller's library, or its file is missing from disk"
+        }
+      ]
+    }
+  }
+}
diff --git a/lexicons/getPersonalLibrary.json b/lexicons/getPersonalLibrary.json
index a97eeae..bea0b96 100644
--- a/lexicons/getPersonalLibrary.json
+++ b/lexicons/getPersonalLibrary.json
@@ -22,6 +22,18 @@
           "shelfId": {
             "type": "integer",
             "description": "Filter by personal shelf ID"
+          },
+          "q": {
+            "type": "string",
+            "description": "Case-insensitive substring match against title or authors. Mirrors the OPDS search feed.",
+            "minLength": 1,
+            "maxLength": 256
+          },
+          "sort": {
+            "type": "string",
+            "description": "Result ordering. `recent` is newest-added first (the default, matching the library page and the OPDS /all feed); `title` and `author` are ascending alphabetical, matching the OPDS search results feed. Not switched implicitly when `q` is set — pass it explicitly.",
+            "knownValues": ["recent", "title", "author"],
+            "default": "recent"
           }
         }
       },
@@ -45,11 +57,32 @@
             "cursor": {
               "type": "string",
               "description": "Pagination cursor for the next page"
+            },
+            "storage": {
+              "type": "ref",
+              "ref": "#storageView",
+              "description": "This user's storage usage against their quota"
             }
           }
         }
       }
     },
+    "storageView": {
+      "type": "object",
+      "required": ["usedBytes", "quotaBytes"],
+      "properties": {
+        "usedBytes": {
+          "type": "integer",
+          "description": "Total bytes currently stored for this user",
+          "minimum": 0
+        },
+        "quotaBytes": {
+          "type": "integer",
+          "description": "Total bytes this user is allowed to store",
+          "minimum": 0
+        }
+      }
+    },
     "personalBookView": {
       "type": "object",
       "required": ["contentHash", "title", "format", "mime", "sizeBytes", "createdAt", "updatedAt"],
@@ -88,7 +121,19 @@
         },
         "coverUrl": {
           "type": "string",
-          "description": "URL of the book cover image"
+          "description": "URL of the book cover image. When it points at the public catalog image proxy it needs no authentication; the `/library/covers/...` form is session-authenticated, so a client using service auth should use `hasLocalCover` and getPersonalBookCover instead."
+        },
+        "hasLocalCover": {
+          "type": "boolean",
+          "description": "Whether a cover extracted from the uploaded file is stored. Fetch it with getPersonalBookCover, which works under any supported authentication."
+        },
+        "filename": {
+          "type": "string",
+          "description": "Original uploaded file name. A sync client needs this to correlate the book with what is on the device."
+        },
+        "description": {
+          "type": "string",
+          "description": "Synopsis from the linked BookHive catalog entry. Deliberately unbounded: this is scraped catalog copy, not user input, and 125 of the 367k descriptions in production already exceed 5000 bytes (longest 10386). A maxLength here would be a contract the data violates, and enforcing it would mean truncating a synopsis mid-sentence."
         },
         "createdAt": {
           "type": "string",
diff --git a/lexicons/listPersonalShelves.json b/lexicons/listPersonalShelves.json
new file mode 100644
index 0000000..7f8880a
--- /dev/null
+++ b/lexicons/listPersonalShelves.json
@@ -0,0 +1,36 @@
+{
+  "lexicon": 1,
+  "id": "buzz.bookhive.listPersonalShelves",
+  "defs": {
+    "main": {
+      "type": "query",
+      "description": "List the authenticated user's personal shelves with per-shelf book counts, plus library-wide totals and storage usage. This is the root call for a catalog client: it carries everything the OPDS root navigation feed renders, in one request. Unpaginated — `personal_shelf` is unique on (userDid, name) and these lists are small.",
+      "output": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "required": ["shelves", "totalBooks"],
+          "properties": {
+            "shelves": {
+              "type": "array",
+              "items": {
+                "type": "ref",
+                "ref": "buzz.bookhive.createPersonalShelf#personalShelfView"
+              }
+            },
+            "totalBooks": {
+              "type": "integer",
+              "description": "Books in the library across all shelves and unshelved",
+              "minimum": 0
+            },
+            "storage": {
+              "type": "ref",
+              "ref": "buzz.bookhive.getPersonalLibrary#storageView",
+              "description": "This user's storage usage against their quota"
+            }
+          }
+        }
+      }
+    }
+  }
+}
diff --git a/lexicons/uploadPersonalBook.json b/lexicons/uploadPersonalBook.json
index 6739876..44bbf9f 100644
--- a/lexicons/uploadPersonalBook.json
+++ b/lexicons/uploadPersonalBook.json
@@ -4,23 +4,67 @@
   "defs": {
     "main": {
       "type": "procedure",
-      "description": "Upload an ebook file to the personal library. Accepts EPUB, PDF, MOBI, FB2, CBZ.",
+      "description": "Upload an ebook file to the authenticated user's personal library. Accepts EPUB, MOBI/AZW/AZW3, FB2 (including .fb2.zip) and CBZ. The declared Content-Type is advisory only: the format is determined from the file's magic bytes checked against the `filename` extension, and a file that matches neither is rejected. `application/octet-stream` is accepted because mobile document pickers and plain curl uploads routinely send it.",
+      "parameters": {
+        "type": "params",
+        "required": ["filename"],
+        "properties": {
+          "filename": {
+            "type": "string",
+            "description": "Original file name including extension. Required: the extension is the only thing distinguishing the zip-container formats (.epub / .cbz / .fb2.zip) from each other, and it is the key used to match e-reader sync documents to this file.",
+            "minLength": 1,
+            "maxLength": 512
+          }
+        }
+      },
       "input": {
-        "encoding": "*/*"
+        "encoding": "application/epub+zip,application/x-mobipocket-ebook,application/vnd.amazon.ebook,application/vnd.amazon.mobi8-ebook,application/x-fictionbook+xml,application/vnd.comicbook+zip,application/x-cbz,application/zip,application/octet-stream"
       },
       "output": {
         "encoding": "application/json",
         "schema": {
           "type": "object",
-          "required": ["book"],
+          "required": ["book", "storageUsedBytes", "storageQuotaBytes"],
           "properties": {
             "book": {
               "type": "ref",
               "ref": "buzz.bookhive.getPersonalLibrary#personalBookView"
+            },
+            "storageUsedBytes": {
+              "type": "integer",
+              "description": "Total bytes stored for this user after the upload",
+              "minimum": 0
+            },
+            "storageQuotaBytes": {
+              "type": "integer",
+              "description": "Total bytes this user is allowed to store",
+              "minimum": 0
             }
           }
         }
-      }
+      },
+      "errors": [
+        {
+          "name": "UnsupportedFormat",
+          "description": "The bytes are not a recognised ebook, or do not match the filename's extension"
+        },
+        {
+          "name": "AlreadyExists",
+          "description": "A book with this content hash is already in the library"
+        },
+        {
+          "name": "TooLarge",
+          "description": "The file exceeds the per-file size limit"
+        },
+        {
+          "name": "QuotaExceeded",
+          "description": "The upload would take the library over its total storage quota"
+        },
+        {
+          "name": "Busy",
+          "description": "Too many uploads are being processed; retry shortly"
+        }
+      ]
     }
   }
 }
diff --git a/package.json b/package.json
index 54d637a..3fdcde1 100644
--- a/package.json
+++ b/package.json
@@ -28,10 +28,12 @@
   "dependencies": {
     "@atcute/password-session": "1.0.1",
     "@atcute/xrpc-server": "2.0.1",
+    "@resvg/resvg-js": "2.6.2",
     "@takumi-rs/image-response": "2.0.2",
     "@voidzero-dev/vite-plus-core": "0.2.2",
     "basecoat-css": "0.3.11",
     "fflate": "0.8.3",
+    "image-meta": "0.2.2",
     "ocache": "0.1.5",
     "pino": "10.3.1",
     "react": "19.2.7",
@@ -42,6 +44,7 @@
     "@atcute/atproto": "4.0.3",
     "@atcute/bluesky": "4.0.13",
     "@atcute/client": "5.1.1",
+    "@atcute/crypto": "2.4.2",
     "@atcute/identity-resolver": "2.0.1",
     "@atcute/identity-resolver-node": "2.0.1",
     "@atcute/jetstream": "2.0.1",
diff --git a/src/app.ts b/src/app.ts
index 0a02bfe..ab2ef0e 100644
--- a/src/app.ts
+++ b/src/app.ts
@@ -30,6 +30,20 @@ export function createApp({ startTime: serverStartTime, deps }: CreateAppOptions
 
   app.use(timing({ autoEnd: false }));
 
+  /**
+   * Routes that stream a stored ebook file. Kept out of both `compress()` and
+   * `etag()` — see the notes at each call site.
+   */
+  const BOOK_DOWNLOAD_PREFIXES = [
+    "/library/books/",
+    "/opds/books/",
+    "/xrpc/buzz.bookhive.getPersonalBookFile",
+  ];
+  const isBookDownloadPath = (path: string) =>
+    BOOK_DOWNLOAD_PREFIXES.some(
+      (prefix) => path === prefix || path.startsWith(prefix.endsWith("/") ? prefix : `${prefix}/`),
+    );
+
   if (env.isDevelopment) {
     app.use(prettyJSON());
   }
@@ -65,7 +79,16 @@ export function createApp({ startTime: serverStartTime, deps }: CreateAppOptions
     await next();
     endTime(c, "compress");
   });
-  app.use(compress());
+  const compressMiddleware = compress();
+  app.use("*", async (c, next) => {
+    // Ebook downloads are already-compressed containers (EPUB and CBZ are ZIP,
+    // MOBI is its own packing), so gzipping them burns CPU for ~nothing. The
+    // one that would actually match hono's compressible-type regex is FB2 —
+    // `application/x-fictionbook+xml` hits the `+xml` branch — and compressing
+    // it drops the Content-Length a client is driving a progress bar from.
+    if (isBookDownloadPath(c.req.path)) return next();
+    return compressMiddleware(c, next);
+  });
 
   app.use(jsxRenderer());
 
@@ -122,7 +145,18 @@ export function createApp({ startTime: serverStartTime, deps }: CreateAppOptions
   // completes and no byte is ever flushed. That failure is severe and would
   // look like "import is broken" rather than "etag is misconfigured", so it is
   // worth being order-independent about.
-  const ETAG_EXCLUDED_PREFIXES = ["/library/books/", "/opds/books/", "/import"];
+  // The two binary XRPC methods are listed by exact NSID, deliberately not as
+  // a `/xrpc/` prefix — that would cost the ~35 JSON methods their 304s. Both
+  // set their own ETag, and hono's etag() skips a response that already has
+  // one, so this is belt-and-braces: if a future edit drops that header the
+  // buffering regression above would otherwise come back silently.
+  const ETAG_EXCLUDED_PREFIXES = [
+    "/library/books/",
+    "/opds/books/",
+    "/import",
+    "/xrpc/buzz.bookhive.getPersonalBookFile",
+    "/xrpc/buzz.bookhive.getPersonalBookCover",
+  ];
   const isEtagExcluded = (path: string) =>
     ETAG_EXCLUDED_PREFIXES.some(
       (prefix) =>
diff --git a/src/auth/client.ts b/src/auth/client.ts
index 81ae465..e3fc654 100644
--- a/src/auth/client.ts
+++ b/src/auth/client.ts
@@ -13,8 +13,40 @@ export type LockFunction = <T>(key: string, cb: () => Promise<T>) => Promise<T>;
 // When false, uses the granular per-resource scopes (works on all current PDS instances).
 const USE_PERMISSION_SETS = true;
 
+/**
+ * The `rpc:buzz.bookhive.*` entries are what allow a client to mint an atproto
+ * service-auth token for our own XRPC methods via
+ * `com.atproto.server.getServiceAuth` — without them the user's PDS refuses.
+ * They must stay in lockstep with the `rpc` permission in `lexicons/auth.json`:
+ * this constant is the fallback used when `USE_PERMISSION_SETS` is false, and
+ * granting the permission in only one of the two places silently drops it for
+ * whichever path is live.
+ */
+const PERSONAL_LIBRARY_RPC_SCOPES = [
+  "getPersonalLibrary",
+  "getPersonalBook",
+  "getPersonalBookFile",
+  "getPersonalBookCover",
+  "listPersonalShelves",
+  "uploadPersonalBook",
+  "deletePersonalBook",
+  "linkPersonalBook",
+  "unlinkPersonalBook",
+  "createPersonalShelf",
+  "updatePersonalShelf",
+  "deletePersonalShelf",
+  "addToPersonalShelf",
+  "removeFromPersonalShelf",
+  "getSyncProgress",
+  "putSyncProgress",
+  "listSyncDocuments",
+]
+  .map((method) => `rpc:buzz.bookhive.${method}?aud=*`)
+  .join(" ");
+
 const GRANULAR_SCOPES =
-  "atproto blob:*/* repo:buzz.bookhive.book?action=create&action=update&action=delete repo:buzz.bookhive.buzz?action=create&action=update&action=delete repo:app.bsky.graph.follow?action=create&action=delete repo:social.popfeed.feed.list?action=create&action=update&action=delete repo:social.popfeed.feed.listItem?action=create&action=update&action=delete rpc:app.bsky.graph.getFollows?aud=* rpc:app.bsky.actor.getProfile?aud=* rpc:app.bsky.actor.getProfiles?aud=*";
+  "atproto blob:*/* repo:buzz.bookhive.book?action=create&action=update&action=delete repo:buzz.bookhive.buzz?action=create&action=update&action=delete repo:app.bsky.graph.follow?action=create&action=delete repo:social.popfeed.feed.list?action=create&action=update&action=delete repo:social.popfeed.feed.listItem?action=create&action=update&action=delete rpc:app.bsky.graph.getFollows?aud=* rpc:app.bsky.actor.getProfile?aud=* rpc:app.bsky.actor.getProfiles?aud=* " +
+  PERSONAL_LIBRARY_RPC_SCOPES;
 
 // Permission set can only cover buzz.bookhive.* namespace (spec namespace authority rule).
 // blob, app.bsky.*, and social.popfeed.* must remain as granular scopes.
diff --git a/src/auth/session.test.ts b/src/auth/session.test.ts
index 34b28be..0eeab58 100644
--- a/src/auth/session.test.ts
+++ b/src/auth/session.test.ts
@@ -1,5 +1,6 @@
 import { describe, it, expect, mock } from "bun:test";
 import { getIronSession } from "iron-session";
+import { env as realEnv } from "../env";
 
 // Mock iron-session
 const mockGetIronSession = mock();
@@ -7,11 +8,16 @@ void mock.module("iron-session", () => ({
   getIronSession: mockGetIronSession,
 }));
 
-// Mock environment
+// Override one field of the environment, keeping the rest.
+//
+// `mock.module` is process-wide and permanent, so returning a bare object here
+// replaces `env` for *every* module loaded afterwards in the same `bun test`
+// run — every other field reads back as undefined. That is a landmine for any
+// module that reads env lazily inside a request (`getLibraryDir()` reading
+// `DB_PATH`, for one): the owning test passes in isolation and an unrelated
+// file fails in the full suite. Spread the real env so only COOKIE_SECRET moves.
 void mock.module("../env", () => ({
-  env: {
-    COOKIE_SECRET: "test-secret-key-for-testing-purposes-only",
-  },
+  env: { ...realEnv, COOKIE_SECRET: "test-secret-key-for-testing-purposes-only" },
 }));
 
 describe("Auth Session TTL Logic", () => {
diff --git a/src/auth/token-refresh.test.ts b/src/auth/token-refresh.test.ts
index 286799a..5e9d407 100644
--- a/src/auth/token-refresh.test.ts
+++ b/src/auth/token-refresh.test.ts
@@ -1,4 +1,5 @@
 import { describe, it, expect, mock, beforeEach } from "bun:test";
+import { env as realEnv } from "../env";
 
 // Mock the OAuth client and session
 const mockOAuthSession = {
@@ -16,11 +17,11 @@ const mockSession = {
   destroy: mock(),
 };
 
-// Mock environment
+// Override one field of the environment, keeping the rest — see the same note
+// in session.test.ts. `mock.module` is process-wide, so a bare object here
+// blanks every other env field for the remainder of the run.
 void mock.module("../env", () => ({
-  env: {
-    COOKIE_SECRET: "test-secret-key-for-testing-purposes-only",
-  },
+  env: { ...realEnv, COOKIE_SECRET: "test-secret-key-for-testing-purposes-only" },
 }));
 
 describe("Token Refresh Logic", () => {
diff --git a/src/bsky/id-resolver.ts b/src/bsky/id-resolver.ts
index 319f925..f47f77b 100644
--- a/src/bsky/id-resolver.ts
+++ b/src/bsky/id-resolver.ts
@@ -1,6 +1,6 @@
 import type { Storage } from "unstorage";
 import type { ActorIdentifier } from "@atcute/lexicons/syntax";
-import type { ActorResolver } from "@atcute/identity-resolver";
+import type { ActorResolver, DidDocumentResolver } from "@atcute/identity-resolver";
 import {
   CompositeDidDocumentResolver,
   CompositeHandleResolver,
@@ -13,6 +13,26 @@ import { NodeDnsHandleResolver } from "@atcute/identity-resolver-node";
 
 import { readThroughCache } from "../utils/readThroughCache";
 
+let sharedDidDocumentResolver: DidDocumentResolver | undefined;
+
+/**
+ * The process-wide DID document resolver.
+ *
+ * Memoised rather than constructed per caller so the OAuth client, the handle
+ * resolvers and the service-auth JWT verifier all share one instance — and
+ * therefore one DID-document cache. The verifier re-resolves with
+ * `noCache: true` when a signature fails, to recover from key rotation;
+ * `CompositeDidDocumentResolver` forwards that through, so sharing is safe.
+ */
+export function getDidDocumentResolver(): DidDocumentResolver {
+  return (sharedDidDocumentResolver ??= new CompositeDidDocumentResolver({
+    methods: {
+      plc: new PlcDidDocumentResolver(),
+      web: new WebDidDocumentResolver(),
+    },
+  }));
+}
+
 /** Create ActorResolver for OAuth (handle/DID resolution). */
 export function createActorResolver(): ActorResolver {
   const handleResolver = new CompositeHandleResolver({
@@ -21,15 +41,9 @@ export function createActorResolver(): ActorResolver {
       http: new WellKnownHandleResolver(),
     },
   });
-  const didDocumentResolver = new CompositeDidDocumentResolver({
-    methods: {
-      plc: new PlcDidDocumentResolver(),
-      web: new WebDidDocumentResolver(),
-    },
-  });
   return new LocalActorResolver({
     handleResolver,
-    didDocumentResolver,
+    didDocumentResolver: getDidDocumentResolver(),
   });
 }
 
diff --git a/src/bsky/lexicon/generated/index.ts b/src/bsky/lexicon/generated/index.ts
index 98b0c2a..b64392a 100644
--- a/src/bsky/lexicon/generated/index.ts
+++ b/src/bsky/lexicon/generated/index.ts
@@ -17,6 +17,8 @@ export * as BuzzBookhiveGetFeed from "./types/buzz/bookhive/getFeed.js";
 export * as BuzzBookhiveGetLanguages from "./types/buzz/bookhive/getLanguages.js";
 export * as BuzzBookhiveGetList from "./types/buzz/bookhive/getList.js";
 export * as BuzzBookhiveGetPersonalBook from "./types/buzz/bookhive/getPersonalBook.js";
+export * as BuzzBookhiveGetPersonalBookCover from "./types/buzz/bookhive/getPersonalBookCover.js";
+export * as BuzzBookhiveGetPersonalBookFile from "./types/buzz/bookhive/getPersonalBookFile.js";
 export * as BuzzBookhiveGetPersonalLibrary from "./types/buzz/bookhive/getPersonalLibrary.js";
 export * as BuzzBookhiveGetProfile from "./types/buzz/bookhive/getProfile.js";
 export * as BuzzBookhiveGetReadingStats from "./types/buzz/bookhive/getReadingStats.js";
@@ -25,6 +27,7 @@ export * as BuzzBookhiveGetUserLists from "./types/buzz/bookhive/getUserLists.js
 export * as BuzzBookhiveHiveBook from "./types/buzz/bookhive/hiveBook.js";
 export * as BuzzBookhiveLinkPersonalBook from "./types/buzz/bookhive/linkPersonalBook.js";
 export * as BuzzBookhiveListGenres from "./types/buzz/bookhive/listGenres.js";
+export * as BuzzBookhiveListPersonalShelves from "./types/buzz/bookhive/listPersonalShelves.js";
 export * as BuzzBookhiveListSyncDocuments from "./types/buzz/bookhive/listSyncDocuments.js";
 export * as BuzzBookhivePutSyncProgress from "./types/buzz/bookhive/putSyncProgress.js";
 export * as BuzzBookhiveRemoveFromList from "./types/buzz/bookhive/removeFromList.js";
diff --git a/src/bsky/lexicon/generated/types/buzz/bookhive/getPersonalBookCover.ts b/src/bsky/lexicon/generated/types/buzz/bookhive/getPersonalBookCover.ts
new file mode 100644
index 0000000..a143009
--- /dev/null
+++ b/src/bsky/lexicon/generated/types/buzz/bookhive/getPersonalBookCover.ts
@@ -0,0 +1,40 @@
+import type {} from "@atcute/lexicons";
+import * as v from "@atcute/lexicons/validations";
+import type {} from "@atcute/lexicons/ambient";
+
+const _mainSchema = /*#__PURE__*/ v.query("buzz.bookhive.getPersonalBookCover", {
+  params: /*#__PURE__*/ v.object({
+    /**
+     * Content hash identifying the book
+     */
+    contentHash: /*#__PURE__*/ v.string(),
+    /**
+     * Requested width in pixels for the catalog-cover redirect. Ignored for locally stored covers, which are served at the size they were extracted at.
+     * @minimum 32
+     * @maximum 1024
+     * @default 300
+     */
+    width: /*#__PURE__*/ v.optional(
+      /*#__PURE__*/ v.constrain(/*#__PURE__*/ v.integer(), [
+        /*#__PURE__*/ v.integerRange(32, 1024),
+      ]),
+      300,
+    ),
+  }),
+  output: {
+    type: "blob",
+    encoding: ["image/jpeg", "image/png", "image/gif", "image/webp"],
+  },
+});
+type main$schematype = typeof _mainSchema;
+
+export interface mainSchema extends main$schematype {}
+export const mainSchema = _mainSchema as mainSchema;
+
+export interface $params extends v.InferInput<mainSchema["params"]> {}
+export type $output = v.InferXRPCBodyInput<mainSchema["output"]>;
+declare module "@atcute/lexicons/ambient" {
+  interface XRPCQueries {
+    "buzz.bookhive.getPersonalBookCover": mainSchema;
+  }
+}
diff --git a/src/bsky/lexicon/generated/types/buzz/bookhive/getPersonalBookFile.ts b/src/bsky/lexicon/generated/types/buzz/bookhive/getPersonalBookFile.ts
new file mode 100644
index 0000000..e6fd33c
--- /dev/null
+++ b/src/bsky/lexicon/generated/types/buzz/bookhive/getPersonalBookFile.ts
@@ -0,0 +1,34 @@
+import type {} from "@atcute/lexicons";
+import * as v from "@atcute/lexicons/validations";
+import type {} from "@atcute/lexicons/ambient";
+
+const _mainSchema = /*#__PURE__*/ v.query("buzz.bookhive.getPersonalBookFile", {
+  params: /*#__PURE__*/ v.object({
+    /**
+     * Content hash identifying the book, as returned by getPersonalLibrary
+     */
+    contentHash: /*#__PURE__*/ v.string(),
+  }),
+  output: {
+    type: "blob",
+    encoding: [
+      "application/epub+zip",
+      "application/x-mobipocket-ebook",
+      "application/x-fictionbook+xml",
+      "application/vnd.comicbook+zip",
+      "application/octet-stream",
+    ],
+  },
+});
+type main$schematype = typeof _mainSchema;
+
+export interface mainSchema extends main$schematype {}
+export const mainSchema = _mainSchema as mainSchema;
+
+export interface $params extends v.InferInput<mainSchema["params"]> {}
+export type $output = v.InferXRPCBodyInput<mainSchema["output"]>;
+declare module "@atcute/lexicons/ambient" {
+  interface XRPCQueries {
+    "buzz.bookhive.getPersonalBookFile": mainSchema;
+  }
+}
diff --git a/src/bsky/lexicon/generated/types/buzz/bookhive/getPersonalLibrary.ts b/src/bsky/lexicon/generated/types/buzz/bookhive/getPersonalLibrary.ts
index 4937b5c..9157b9c 100644
--- a/src/bsky/lexicon/generated/types/buzz/bookhive/getPersonalLibrary.ts
+++ b/src/bsky/lexicon/generated/types/buzz/bookhive/getPersonalLibrary.ts
@@ -18,10 +18,26 @@ const _mainSchema = /*#__PURE__*/ v.query("buzz.bookhive.getPersonalLibrary", {
       /*#__PURE__*/ v.constrain(/*#__PURE__*/ v.integer(), [/*#__PURE__*/ v.integerRange(1, 100)]),
       24,
     ),
+    /**
+     * Case-insensitive substring match against title or authors. Mirrors the OPDS search feed.
+     * @minLength 1
+     * @maxLength 256
+     */
+    q: /*#__PURE__*/ v.optional(
+      /*#__PURE__*/ v.constrain(/*#__PURE__*/ v.string(), [/*#__PURE__*/ v.stringLength(1, 256)]),
+    ),
     /**
      * Filter by personal shelf ID
      */
     shelfId: /*#__PURE__*/ v.optional(/*#__PURE__*/ v.integer()),
+    /**
+     * Result ordering. `recent` is newest-added first (the default, matching the library page and the OPDS /all feed); `title` and `author` are ascending alphabetical, matching the OPDS search results feed. Not switched implicitly when `q` is set — pass it explicitly.
+     * @default "recent"
+     */
+    sort: /*#__PURE__*/ v.optional(
+      /*#__PURE__*/ v.string<"author" | "recent" | "title" | (string & {})>(),
+      "recent",
+    ),
   }),
   output: {
     type: "lex",
@@ -33,6 +49,12 @@ const _mainSchema = /*#__PURE__*/ v.query("buzz.bookhive.getPersonalLibrary", {
        * Pagination cursor for the next page
        */
       cursor: /*#__PURE__*/ v.optional(/*#__PURE__*/ v.string()),
+      /**
+       * This user's storage usage against their quota
+       */
+      get storage() {
+        return /*#__PURE__*/ v.optional(storageViewSchema);
+      },
       /**
        * Total number of books matching the query, across all pages
        */
@@ -53,17 +75,29 @@ const _personalBookViewSchema = /*#__PURE__*/ v.object({
    */
   contentHash: /*#__PURE__*/ v.string(),
   /**
-   * URL of the book cover image
+   * URL of the book cover image. When it points at the public catalog image proxy it needs no authentication; the `/library/covers/...` form is session-authenticated, so a client using service auth should use `hasLocalCover` and getPersonalBookCover instead.
    */
   coverUrl: /*#__PURE__*/ v.optional(/*#__PURE__*/ v.string()),
   /**
    * When the book was added to the library
    */
   createdAt: /*#__PURE__*/ v.datetimeString(),
+  /**
+   * Synopsis from the linked BookHive catalog entry. Deliberately unbounded: this is scraped catalog copy, not user input, and 125 of the 367k descriptions in production already exceed 5000 bytes (longest 10386). A maxLength here would be a contract the data violates, and enforcing it would mean truncating a synopsis mid-sentence.
+   */
+  description: /*#__PURE__*/ v.optional(/*#__PURE__*/ v.string()),
+  /**
+   * Original uploaded file name. A sync client needs this to correlate the book with what is on the device.
+   */
+  filename: /*#__PURE__*/ v.optional(/*#__PURE__*/ v.string()),
   /**
    * File format (e.g. epub, pdf, mobi, fb2, cbz)
    */
   format: /*#__PURE__*/ v.string(),
+  /**
+   * Whether a cover extracted from the uploaded file is stored. Fetch it with getPersonalBookCover, which works under any supported authentication.
+   */
+  hasLocalCover: /*#__PURE__*/ v.optional(/*#__PURE__*/ v.boolean()),
   /**
    * Linked BookHive catalog entry ID
    */
@@ -99,6 +133,21 @@ const _personalBookViewSchema = /*#__PURE__*/ v.object({
    */
   updatedAt: /*#__PURE__*/ v.datetimeString(),
 });
+const _storageViewSchema = /*#__PURE__*/ v.object({
+  $type: /*#__PURE__*/ v.optional(
+    /*#__PURE__*/ v.literal("buzz.bookhive.getPersonalLibrary#storageView"),
+  ),
+  /**
+   * Total bytes this user is allowed to store
+   * @minimum 0
+   */
+  quotaBytes: /*#__PURE__*/ v.integer(),
+  /**
+   * Total bytes currently stored for this user
+   * @minimum 0
+   */
+  usedBytes: /*#__PURE__*/ v.integer(),
+});
 const _syncProgressViewSchema = /*#__PURE__*/ v.object({
   $type: /*#__PURE__*/ v.optional(
     /*#__PURE__*/ v.literal("buzz.bookhive.getPersonalLibrary#syncProgressView"),
@@ -118,19 +167,25 @@ const _syncProgressViewSchema = /*#__PURE__*/ v.object({
 });
 type main$schematype = typeof _mainSchema;
 type personalBookView$schematype = typeof _personalBookViewSchema;
+type storageView$schematype = typeof _storageViewSchema;
 type syncProgressView$schematype = typeof _syncProgressViewSchema;
 
 export interface mainSchema extends main$schematype {}
 
 export interface personalBookViewSchema extends personalBookView$schematype {}
 
+export interface storageViewSchema extends storageView$schematype {}
+
 export interface syncProgressViewSchema extends syncProgressView$schematype {}
 export const mainSchema = _mainSchema as mainSchema;
 export const personalBookViewSchema = _personalBookViewSchema as personalBookViewSchema;
+export const storageViewSchema = _storageViewSchema as storageViewSchema;
 export const syncProgressViewSchema = _syncProgressViewSchema as syncProgressViewSchema;
 
 export interface PersonalBookView extends v.InferInput<typeof personalBookViewSchema> {}
 
+export interface StorageView extends v.InferInput<typeof storageViewSchema> {}
+
 export interface SyncProgressView extends v.InferInput<typeof syncProgressViewSchema> {}
 
 export interface $params extends v.InferInput<mainSchema["params"]> {}
diff --git a/src/bsky/lexicon/generated/types/buzz/bookhive/listPersonalShelves.ts b/src/bsky/lexicon/generated/types/buzz/bookhive/listPersonalShelves.ts
new file mode 100644
index 0000000..ff35e1c
--- /dev/null
+++ b/src/bsky/lexicon/generated/types/buzz/bookhive/listPersonalShelves.ts
@@ -0,0 +1,41 @@
+import type {} from "@atcute/lexicons";
+import * as v from "@atcute/lexicons/validations";
+import type {} from "@atcute/lexicons/ambient";
+import * as BuzzBookhiveCreatePersonalShelf from "./createPersonalShelf.js";
+import * as BuzzBookhiveGetPersonalLibrary from "./getPersonalLibrary.js";
+
+const _mainSchema = /*#__PURE__*/ v.query("buzz.bookhive.listPersonalShelves", {
+  params: null,
+  output: {
+    type: "lex",
+    schema: /*#__PURE__*/ v.object({
+      get shelves() {
+        return /*#__PURE__*/ v.array(BuzzBookhiveCreatePersonalShelf.personalShelfViewSchema);
+      },
+      /**
+       * This user's storage usage against their quota
+       */
+      get storage() {
+        return /*#__PURE__*/ v.optional(BuzzBookhiveGetPersonalLibrary.storageViewSchema);
+      },
+      /**
+       * Books in the library across all shelves and unshelved
+       * @minimum 0
+       */
+      totalBooks: /*#__PURE__*/ v.integer(),
+    }),
+  },
+});
+type main$schematype = typeof _mainSchema;
+
+export interface mainSchema extends main$schematype {}
+export const mainSchema = _mainSchema as mainSchema;
+
+export interface $params {}
+
+export interface $output extends v.InferXRPCBodyInput<mainSchema["output"]> {}
+declare module "@atcute/lexicons/ambient" {
+  interface XRPCQueries {
+    "buzz.bookhive.listPersonalShelves": mainSchema;
+  }
+}
diff --git a/src/bsky/lexicon/generated/types/buzz/bookhive/uploadPersonalBook.ts b/src/bsky/lexicon/generated/types/buzz/bookhive/uploadPersonalBook.ts
index f3cc1e1..aa517d4 100644
--- a/src/bsky/lexicon/generated/types/buzz/bookhive/uploadPersonalBook.ts
+++ b/src/bsky/lexicon/generated/types/buzz/bookhive/uploadPersonalBook.ts
@@ -4,14 +4,46 @@ import type {} from "@atcute/lexicons/ambient";
 import * as BuzzBookhiveGetPersonalLibrary from "./getPersonalLibrary.js";
 
 const _mainSchema = /*#__PURE__*/ v.procedure("buzz.bookhive.uploadPersonalBook", {
-  params: null,
-  input: { type: "blob" },
+  params: /*#__PURE__*/ v.object({
+    /**
+     * Original file name including extension. Required: the extension is the only thing distinguishing the zip-container formats (.epub / .cbz / .fb2.zip) from each other, and it is the key used to match e-reader sync documents to this file.
+     * @minLength 1
+     * @maxLength 512
+     */
+    filename: /*#__PURE__*/ v.constrain(/*#__PURE__*/ v.string(), [
+      /*#__PURE__*/ v.stringLength(1, 512),
+    ]),
+  }),
+  input: {
+    type: "blob",
+    encoding: [
+      "application/epub+zip",
+      "application/x-mobipocket-ebook",
+      "application/vnd.amazon.ebook",
+      "application/vnd.amazon.mobi8-ebook",
+      "application/x-fictionbook+xml",
+      "application/vnd.comicbook+zip",
+      "application/x-cbz",
+      "application/zip",
+      "application/octet-stream",
+    ],
+  },
   output: {
     type: "lex",
     schema: /*#__PURE__*/ v.object({
       get book() {
         return BuzzBookhiveGetPersonalLibrary.personalBookViewSchema;
       },
+      /**
+       * Total bytes this user is allowed to store
+       * @minimum 0
+       */
+      storageQuotaBytes: /*#__PURE__*/ v.integer(),
+      /**
+       * Total bytes stored for this user after the upload
+       * @minimum 0
+       */
+      storageUsedBytes: /*#__PURE__*/ v.integer(),
     }),
   },
 });
@@ -20,7 +52,7 @@ type main$schematype = typeof _mainSchema;
 export interface mainSchema extends main$schematype {}
 export const mainSchema = _mainSchema as mainSchema;
 
-export interface $params {}
+export interface $params extends v.InferInput<mainSchema["params"]> {}
 export type $input = v.InferXRPCBodyInput<mainSchema["input"]>;
 
 export interface $output extends v.InferXRPCBodyInput<mainSchema["output"]> {}
diff --git a/src/client/components/LibraryManager.tsx b/src/client/components/LibraryManager.tsx
index e97ae04..96a39ff 100644
--- a/src/client/components/LibraryManager.tsx
+++ b/src/client/components/LibraryManager.tsx
@@ -37,6 +37,47 @@ const getJson = (url: string): Promise<Response> => fetch(url, { cache: "no-stor
  * triaged above the grid, or parked in "Also tracking" below it once the user
  * has linked or dismissed them.
  */
+function formatBytes(bytes: number): string {
+  if (bytes >= 1024 ** 3) return `${(bytes / 1024 ** 3).toFixed(1)} GB`;
+  if (bytes >= 1024 ** 2) return `${Math.round(bytes / 1024 ** 2)} MB`;
+  return `${Math.round(bytes / 1024)} KB`;
+}
+
+const StorageMeter: FC<{ storage: { usedBytes: number; quotaBytes: number } | null }> = ({
+  storage,
+}) => {
+  if (!storage || storage.quotaBytes <= 0) return null;
+  const ratio = Math.min(1, storage.usedBytes / storage.quotaBytes);
+  const pct = Math.round(ratio * 100);
+  const full = ratio >= 1;
+  const barColor = full ? "bg-destructive" : ratio >= 0.8 ? "bg-amber-500" : "bg-primary";
+
+  return (
+    <div class="mt-4 flex flex-col gap-1.5 text-xs text-muted-foreground">
+      <div class="flex items-center justify-between">
+        <span>
+          {formatBytes(storage.usedBytes)} of {formatBytes(storage.quotaBytes)} used
+        </span>
+        <span>{pct}%</span>
+      </div>
+      <span
+        class="h-2 w-full overflow-hidden rounded-full bg-muted"
+        role="progressbar"
+        aria-valuenow={pct}
+        aria-valuemin={0}
+        aria-valuemax={100}
+        aria-label="Library storage used"
+      >
+        <span
+          class={`block h-full rounded-full transition-all ${barColor}`}
+          style={`width: ${Math.max(pct, 1)}%`}
+        />
+      </span>
+      {full && <span class="text-destructive">Library full — delete a book to upload more.</span>}
+    </div>
+  );
+};
+
 export const LibraryManager: FC = () => {
   const [books, setBooks] = useState<PersonalBook[] | null>(null);
   const [cursor, setCursor] = useState<string | undefined>(undefined);
@@ -48,6 +89,7 @@ export const LibraryManager: FC = () => {
   const [shelves, setShelves] = useState<Shelf[]>([]);
   const [shelvesLoaded, setShelvesLoaded] = useState(false);
   const [totalBooks, setTotalBooks] = useState(0);
+  const [storage, setStorage] = useState<{ usedBytes: number; quotaBytes: number } | null>(null);
 
   const [activeShelfId, setActiveShelfId] = useState<number | null>(null);
   const [linkTarget, setLinkTarget] = useState<LinkTarget | null>(null);
@@ -72,11 +114,21 @@ export const LibraryManager: FC = () => {
         if (!r.ok) throw new Error("Failed");
         return r.json();
       })
-      .then((d: { books: PersonalBook[]; total?: number; cursor?: string }) => {
-        setBooks(d.books);
-        setCursor(d.cursor);
-        if (shelfId === null) setTotalBooks(d.total ?? d.books.length);
-      })
+      .then(
+        (d: {
+          books: PersonalBook[];
+          total?: number;
+          cursor?: string;
+          storage?: { usedBytes: number; quotaBytes: number };
+        }) => {
+          setBooks(d.books);
+          setCursor(d.cursor);
+          if (shelfId === null) setTotalBooks(d.total ?? d.books.length);
+          // Rides along on the list every client already refetches after each
+          // mutation, so the usage bar stays current with no extra request.
+          if (d.storage) setStorage(d.storage);
+        },
+      )
       .catch(() => setError(true))
       .finally(() => setRefreshing(false));
   }, []);
@@ -169,6 +221,11 @@ export const LibraryManager: FC = () => {
     try {
       const res = await postJson("/xrpc/buzz.bookhive.deletePersonalBook", { contentHash });
       if (!res.ok) throw new Error("Failed");
+      // Refetch rather than subtract the deleted size locally: `storage` is the
+      // server's `SUM(sizeBytes)`, and the list response carries it for free.
+      // Without this the usage bar keeps showing the freed space as used, and a
+      // user who deletes a book to get under quota still can't upload.
+      fetchBooks(activeShelfId);
       // The file is gone but its sync document may live on, so it can reappear
       // in the triage/tracking sections.
       fetchDocs();
@@ -393,6 +450,8 @@ export const LibraryManager: FC = () => {
         />
       )}
 
+      <StorageMeter storage={storage} />
+
       {error && (
         <p class="mt-6 text-sm text-muted-foreground">
           Could not load your library. Try reloading the page.
diff --git a/src/context.ts b/src/context.ts
index 041afac..8994b1f 100644
--- a/src/context.ts
+++ b/src/context.ts
@@ -27,8 +27,13 @@ import {
   createBidirectionalResolverAtcute,
   createCachingBaseIdResolver,
   createCachingBidirectionalResolver,
+  getDidDocumentResolver,
 } from "./bsky/id-resolver";
 import type { BidirectionalResolver } from "./bsky/id-resolver";
+import { ServiceJwtVerifier } from "@atcute/xrpc-server/auth";
+import type { AtprotoAudience } from "@atcute/lexicons/syntax";
+import { BOOKHIVE_DID } from "./constants";
+import { sweepStaleUploads } from "./utils/uploadPersonalBook";
 import type { Database } from "./db";
 import { createDb, migrateToLatest } from "./db";
 import { env } from "./env";
@@ -72,6 +77,8 @@ export type AppContext = {
   getProfile: () => Promise<ProfileViewDetailed | null>;
   /** Service account agent for @bookhive.buzz ATProto writes. Null if env vars not set. */
   serviceAccountAgent: SessionClient | null;
+  /** Verifies atproto service-auth JWTs on /xrpc/*. Null when disabled. */
+  serviceJwtVerifier: ServiceJwtVerifier | null;
   /** Add fields to the one wide event logged per request (observability). */
   addWideEventContext: AddWideEventContext;
 };
@@ -117,6 +124,8 @@ export type AppDeps = {
   ingester: Ingester;
   resolver: BidirectionalResolver;
   serviceAccountAgent: SessionClient | null;
+  /** Verifies atproto service-auth JWTs on /xrpc/*. Null when disabled. */
+  serviceJwtVerifier: ServiceJwtVerifier | null;
   /** Stops the primary worker's enrichment drain loop; no-op elsewhere. */
   stopEnrichmentDrain: () => void;
 };
@@ -304,6 +313,33 @@ export async function createAppDeps(): Promise<AppDeps> {
   // scrape per search result (the 2026-08-01 OOM).
   const stopEnrichmentDrain = isPrimaryWorker ? startEnrichmentDrain({ db, logger }) : () => {};
 
+  // Accepts atproto inter-service auth on /xrpc/*, which is what lets a client
+  // that is not a browser (a script, an e-reader, another app) use the personal
+  // library. Always on; the cookie path is unaffected either way. No replay
+  // store — a token is already scoped to one lxm and one audience, so within its
+  // short lifetime "authed is authed".
+  const serviceJwtVerifier: ServiceJwtVerifier = new ServiceJwtVerifier({
+    // atcute compares these with exact string equality, so a bare DID does
+    // *not* match a `#fragment` audience — both spellings have to be listed.
+    // The fragment form is here in advance of a PLC operation adding a
+    // `#bookhive_appview` service entry to the DID document; once that lands,
+    // clients that switch to PDS proxying keep working with no server change.
+    acceptAudiences: serviceAuthAudiences(),
+    resolver: getDidDocumentResolver(),
+    maxAge: SERVICE_AUTH_MAX_AGE_SECONDS,
+  });
+
+  if (isPrimaryWorker) {
+    // Clear `.part` files left by a process that died between an upload's write
+    // and its rename. Nothing else removes them, and each is up to 100 MB.
+    void sweepStaleUploads().then(
+      (removed) => {
+        if (removed > 0) logger.info({ removed }, "swept stale upload temp files");
+      },
+      (err: unknown) => logger.warn({ err }, "stale upload sweep failed"),
+    );
+  }
+
   return {
     db,
     kv,
@@ -313,10 +349,32 @@ export async function createAppDeps(): Promise<AppDeps> {
     ingester,
     resolver,
     serviceAccountAgent,
+    serviceJwtVerifier,
     stopEnrichmentDrain,
   };
 }
 
+/**
+ * Maximum accepted service-JWT lifetime window, in seconds. atcute defaults to
+ * 300, but a PDS mints up to 3600 when `lxm` is set and most client SDKs don't
+ * expose `exp`, so those tokens would be refused as JwtTooOld. The token's own
+ * `exp` is still enforced separately, so widening this only accepts tokens the
+ * issuing PDS already considered valid.
+ */
+const SERVICE_AUTH_MAX_AGE_SECONDS = 3600;
+
+/**
+ * The `aud` values this deployment answers for. Overridable so a staging
+ * deployment can run under its own DID without a code change.
+ */
+function serviceAuthAudiences(): (Did | AtprotoAudience)[] {
+  const override = env.XRPC_SERVICE_AUTH_AUDIENCES.split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+  if (override.length > 0) return override as (Did | AtprotoAudience)[];
+  return [BOOKHIVE_DID, `${BOOKHIVE_DID}#bookhive_appview`] as (Did | AtprotoAudience)[];
+}
+
 /** Optional timing callbacks for server-timing breakdown (session_iron, session_restore, session_save). */
 export type SessionTiming = {
   start: (name: string) => void;
diff --git a/src/db.ts b/src/db.ts
index 33c2683..6d00483 100644
--- a/src/db.ts
+++ b/src/db.ts
@@ -20,6 +20,7 @@ import type {
   UserFollow,
 } from "./types";
 import { deriveBookIdentifiers } from "./utils/bookIdentifiers.js";
+import { filenameKey, koreaderFilenameHash } from "./utils/filenameMatching.js";
 
 // Types
 export type DatabaseSchema = {
@@ -908,6 +909,103 @@ migrations["021"] = {
   },
 };
 
+migrations["022"] = {
+  async up(db: Kysely<unknown>) {
+    // Filename-derived identity for e-reader documents. See
+    // src/utils/filenameMatching.ts for what each value is and why the first is
+    // exact while the second is not:
+    //
+    // - `filenameHash` is md5(basename) — literally the `document` id a KOSync
+    //   client sends when its checksum method is FILENAME instead of BINARY.
+    //   Without it, every user on that setting has a library where no uploaded
+    //   file ever lines up with its synced progress, because the id they send
+    //   is not a content hash at all.
+    // - `filenameKey` is a normalized, extension-less name, so a file survives
+    //   the calibre conversion (.epub -> .azw3) that broke the content hash in
+    //   the first place — which is the reason those users switched.
+    await db.schema.alterTable("personal_book").addColumn("filenameHash", "text").execute();
+    await db.schema.alterTable("personal_book").addColumn("filenameKey", "text").execute();
+    await db.schema.alterTable("sync_document").addColumn("filenameKey", "text").execute();
+
+    await sql`CREATE INDEX idx_personal_book_user_filename_hash ON personal_book(userDid, filenameHash)`.execute(
+      db,
+    );
+    await sql`CREATE INDEX idx_personal_book_user_filename_key ON personal_book(userDid, filenameKey)`.execute(
+      db,
+    );
+    await sql`CREATE INDEX idx_sync_document_user_filename_key ON sync_document(userDid, filenameKey)`.execute(
+      db,
+    );
+
+    // Backfill in JS: SQLite has no md5, and the normalization is Unicode-aware.
+    // Both tables hold one row per user per book, so this is small.
+    //
+    // These call the live helpers on purpose — see the header of
+    // `utils/filenameMatching.ts`. Changing their output requires a *new*
+    // migration that recomputes both columns; pinning a frozen copy here would
+    // only guarantee that a fresh install disagrees with the running app.
+    const books = (
+      await sql<{
+        id: number;
+        filename: string | null;
+      }>`SELECT id, filename FROM personal_book`.execute(db)
+    ).rows;
+    for (const row of books) {
+      const hash = koreaderFilenameHash(row.filename);
+      const key = filenameKey(row.filename);
+      if (!hash && !key) continue;
+      await sql`UPDATE personal_book SET filenameHash = ${hash}, filenameKey = ${key} WHERE id = ${row.id}`.execute(
+        db,
+      );
+    }
+
+    const docs = (
+      await sql<{
+        id: number;
+        filename: string | null;
+      }>`SELECT id, filename FROM sync_document WHERE filename IS NOT NULL`.execute(db)
+    ).rows;
+    for (const row of docs) {
+      const key = filenameKey(row.filename);
+      if (!key) continue;
+      await sql`UPDATE sync_document SET filenameKey = ${key} WHERE id = ${row.id}`.execute(db);
+    }
+  },
+  async down(db: Kysely<unknown>) {
+    await sql`DROP INDEX IF EXISTS idx_sync_document_user_filename_key`.execute(db);
+    await sql`DROP INDEX IF EXISTS idx_personal_book_user_filename_key`.execute(db);
+    await sql`DROP INDEX IF EXISTS idx_personal_book_user_filename_hash`.execute(db);
+    await db.schema.alterTable("sync_document").dropColumn("filenameKey").execute();
+    await db.schema.alterTable("personal_book").dropColumn("filenameKey").execute();
+    await db.schema.alterTable("personal_book").dropColumn("filenameHash").execute();
+  },
+};
+
+migrations["023"] = {
+  async up(db: Kysely<unknown>) {
+    // Covering index for the storage quota. The quota is enforced as
+    // `SUM(sizeBytes) WHERE userDid = ?` evaluated inside the upload INSERT, and
+    // the existing `idx_personal_book_user` only covers `userDid` — SQLite would
+    // walk it and then fetch every row from the table to read `sizeBytes`. With
+    // the size in the index the SUM is an index-only range scan.
+    await sql`CREATE INDEX idx_personal_book_user_size ON personal_book(userDid, sizeBytes)`.execute(
+      db,
+    );
+
+    // `parseBook` returns `authors: ""` (not null) on every fallback path, and
+    // the web upload route stored that verbatim while the XRPC one normalised
+    // it. The two are indistinguishable to JS truthiness and completely
+    // different to SQL — `WHERE authors IS NULL` silently misses every row the
+    // web route wrote. Normalise the existing rows once here; the shared upload
+    // core writes NULL from now on.
+    await sql`UPDATE personal_book SET authors = NULL WHERE authors = ''`.execute(db);
+    await sql`UPDATE personal_book SET language = NULL WHERE language = ''`.execute(db);
+  },
+  async down(db: Kysely<unknown>) {
+    await sql`DROP INDEX IF EXISTS idx_personal_book_user_size`.execute(db);
+  },
+};
+
 // APIs
 
 export const createDb = (location: string): { db: Database; sqlite: DatabaseSync } => {
diff --git a/src/env.ts b/src/env.ts
index a4351c7..c746d26 100644
--- a/src/env.ts
+++ b/src/env.ts
@@ -78,4 +78,20 @@ export const env = cleanEnv(process.env, {
     default: "",
     desc: "Hex-encoded imgproxy signing salt (IMGPROXY_SALT). Empty uses unsafe URLs (dev only).",
   }),
+  XRPC_SERVICE_AUTH_AUDIENCES: str({
+    default: "",
+    desc: "Comma-separated `aud` values this deployment answers for. Empty uses BOOKHIVE_DID plus its #bookhive_appview fragment. Matching is exact string equality — a bare DID does not match a fragment audience.",
+  }),
+  LIBRARY_DIR: str({
+    default: "",
+    desc: "Root directory for personal-library files. Empty derives it from dirname(DB_PATH)/library. Set explicitly to put the library on a different volume from the DB — and by the test preload, so tests can never write ebooks into the repo.",
+  }),
+  PERSONAL_LIBRARY_QUOTA_BYTES: num({
+    default: 2 * 1024 * 1024 * 1024,
+    desc: "Total bytes of personal-library files one user may store. Enforced as SUM(personal_book.sizeBytes) evaluated *inside* the INSERT, so two concurrent uploads can't both observe the pre-insert total. The per-file ceiling (MAX_PERSONAL_BOOK_BYTES, 100 MB) applies on top. Excludes stored cover images, which are <1% of the total.",
+  }),
+  UPLOAD_PARSE_CONCURRENCY: num({
+    default: 2,
+    desc: "Per-process cap on concurrent ebook metadata parses. The parse is the only step that holds the whole file (<=100 MB) in native memory, so this is the memory bound on uploads — and it is per-process: with WEB_CONCURRENCY=4 the cluster-wide ceiling is this x 4 x 100 MB. See src/utils/uploadPersonalBook.ts.",
+  }),
 });
diff --git a/src/pages/library.test.tsx b/src/pages/library.test.tsx
index e159586..1a208ce 100644
--- a/src/pages/library.test.tsx
+++ b/src/pages/library.test.tsx
@@ -55,6 +55,45 @@ describe("LibraryPage", () => {
     });
   });
 
+  describe("upload error alert", () => {
+    it("renders the reason a plain form post failed, in both layouts", async () => {
+      // A <form> post can't read a JSON error body, so the browser path
+      // redirects with a code. Before this it landed on a page showing raw
+      // JSON as text.
+      for (const bookCount of [0, 3]) {
+        const html = await render(
+          <LibraryPage
+            handle="alice.bsky.social"
+            bookCount={bookCount}
+            syncDocCount={0}
+            uploadError="QuotaExceeded"
+          />,
+        );
+        expect(html).toContain("Your library is full");
+        expect(html).toContain('role="alert"');
+      }
+    });
+
+    it("falls back to a generic message for an unknown code", async () => {
+      const html = await render(
+        <LibraryPage
+          handle="alice.bsky.social"
+          bookCount={3}
+          syncDocCount={0}
+          uploadError="SomethingNew"
+        />,
+      );
+      expect(html).toContain("didn&#39;t work");
+    });
+
+    it("renders no alert when there is no error", async () => {
+      const html = await render(
+        <LibraryPage handle="alice.bsky.social" bookCount={3} syncDocCount={0} />,
+      );
+      expect(html).not.toContain('role="alert"');
+    });
+  });
+
   it("uses the populated layout when only synced documents exist", async () => {
     // Progress can arrive from an e-reader before anything is uploaded; that
     // still needs the manager so the user can triage those documents.
diff --git a/src/pages/library.tsx b/src/pages/library.tsx
index f4ec60c..1d37dc7 100644
--- a/src/pages/library.tsx
+++ b/src/pages/library.tsx
@@ -296,11 +296,38 @@ const LibraryDialog: FC<{
   </dialog>
 );
 
+/**
+ * What a failed upload said, for the codes `POST /library/upload` redirects
+ * with. A plain `<form>` post can't read a JSON error body, so the browser path
+ * round-trips a code and renders it here — it used to land on a page showing
+ * raw JSON as text.
+ */
+const UPLOAD_ERRORS: Record<string, string> = {
+  TooLarge: "That file is larger than the 100 MB limit.",
+  QuotaExceeded: "Your library is full. Delete a book to free up space, then try again.",
+  UnsupportedFormat: "That file isn't a supported ebook. Try EPUB, MOBI, AZW3, FB2 or CBZ.",
+  AlreadyExists: "That book is already in your library.",
+  EmptyFile: "That file is empty.",
+  NoFile: "No file was selected.",
+  Busy: "The server is busy right now — try that upload again in a moment.",
+};
+
+const UploadError: FC<{ code: string }> = ({ code }) => (
+  <div
+    role="alert"
+    class="rounded-lg border border-destructive/40 bg-destructive/10 px-4 py-3 text-sm text-foreground"
+  >
+    {UPLOAD_ERRORS[code] ?? "That upload didn't work. Please try again."}
+  </div>
+);
+
 export const LibraryPage: FC<{
   handle: string;
   bookCount: number;
   syncDocCount: number;
-}> = ({ handle, bookCount, syncDocCount }) => {
+  /** `?error=` code from a failed upload redirect, if any. */
+  uploadError?: string | undefined;
+}> = ({ handle, bookCount, syncDocCount, uploadError }) => {
   // Nothing uploaded and nothing synced: there's no library to manage yet, so
   // explain the feature and put setup right on the page instead of behind
   // buttons the user has no reason to press.
@@ -335,6 +362,11 @@ export const LibraryPage: FC<{
             <p class="text-muted-foreground mt-1 mb-4 text-sm">
               Supported formats: EPUB, MOBI, AZW3, FB2, CBZ.
             </p>
+            {uploadError ? (
+              <div class="mb-4">
+                <UploadError code={uploadError} />
+              </div>
+            ) : null}
             <UploadZone />
           </div>
         </div>
@@ -366,6 +398,12 @@ export const LibraryPage: FC<{
         </div>
       </div>
 
+      {uploadError ? (
+        <div class="mt-4">
+          <UploadError code={uploadError} />
+        </div>
+      ) : null}
+
       <LibraryDialog
         id="ereader-dialog"
         title="Connect your e-reader"
diff --git a/src/routes/admin.ts b/src/routes/admin.ts
index 24e033d..d567d68 100644
--- a/src/routes/admin.ts
+++ b/src/routes/admin.ts
@@ -44,7 +44,7 @@ const admin = new Hono<AppEnv>()
     ctx.addWideEventContext({ backfill_catalog: "started" });
     return c.json({ message: "Backfill started" }, 202);
   })
-  .get("/backfill-catalog/progress", (c) => {
+  .get("/backfill-catalog/progress", async (c) => {
     const authorization = c.req.header("authorization");
     if (
       !env.EXPORT_SHARED_SECRET ||
@@ -56,7 +56,10 @@ const admin = new Hono<AppEnv>()
       return c.json({ message: "Not Found" }, 404);
     }
 
-    return c.json(getBackfillProgress());
+    // Reads through to the KV, so this answers usefully even when the request
+    // lands on a worker that never ran the backfill, or after a restart.
+    const ctx = c.get("ctx");
+    return c.json(await getBackfillProgress(ctx.kv));
   })
   .get("/export", async (c) => {
     const ctx = c.get("ctx");
diff --git a/src/routes/library.test.ts b/src/routes/library.test.ts
index ede9c4d..b153045 100644
--- a/src/routes/library.test.ts
+++ b/src/routes/library.test.ts
@@ -9,6 +9,7 @@ import { migrateToLatest, type DatabaseSchema, type Database } from "../db";
 import type { HiveId } from "../types";
 import { koreaderPartialMD5 } from "../utils/bookMetadata/index";
 import { NO_HIVE_MATCH } from "../utils/syncMatching";
+import { filenameKey, koreaderFilenameHash } from "../utils/filenameMatching";
 import libraryRouter from "./library";
 
 type TestApp = Hono<AppEnv>;
@@ -56,8 +57,10 @@ async function seedSyncDocument(
     title?: string | null;
     percentage?: number;
     userDid?: string;
+    filename?: string;
   },
 ) {
+  const filename = opts.filename ?? "book.epub";
   await db
     .insertInto("sync_document")
     .values({
@@ -65,7 +68,8 @@ async function seedSyncDocument(
       provider: "kosync",
       documentHash: opts.documentHash,
       hiveId: opts.hiveId ?? null,
-      filename: "book.epub",
+      filename,
+      filenameKey: filenameKey(filename),
       title: opts.title ?? "A Synced Book",
       authors: "An Author",
       progressData: JSON.stringify({
@@ -81,14 +85,21 @@ async function seedSyncDocument(
     .execute();
 }
 
-async function seedPersonalBook(db: Database, contentHash: string, filePath: string) {
+async function seedPersonalBook(
+  db: Database,
+  contentHash: string,
+  filePath: string,
+  filename = "book.epub",
+) {
   await db
     .insertInto("personal_book")
     .values({
       userDid: DID,
       contentHash,
       hiveId: null,
-      filename: "book.epub",
+      filename,
+      filenameHash: koreaderFilenameHash(filename),
+      filenameKey: filenameKey(filename),
       title: "An Uploaded Book",
       authors: "An Author",
       language: "en",
@@ -149,6 +160,55 @@ describe("GET /library/sync/documents", () => {
     expect(doc?.hasFile).toBe(true);
   });
 
+  it("reports hasFile=true for a client using the FILENAME checksum method", async () => {
+    // KOSync's other checksum mode sends md5(basename) as the document id, so
+    // it never equals our content hash. Matching only on content hash left
+    // every one of these users' uploads looking unsynced.
+    const filename = "The Dispossessed.epub";
+    await seedSyncDocument(db, { documentHash: koreaderFilenameHash(filename)!, filename });
+    await seedPersonalBook(db, "some-content-hash", "/tmp/nonexistent.epub", filename);
+
+    const [doc] = await getDocuments(app);
+    expect(doc?.hasFile).toBe(true);
+  });
+
+  it("reports hasFile=true when conversion changed the bytes and the extension", async () => {
+    // Neither hash can line up: the device holds an .azw3 calibre made from the
+    // .epub we hold. The readable filename is the only thing left.
+    await seedSyncDocument(db, {
+      documentHash: "hash-from-the-converted-copy",
+      filename: "Dune - Frank Herbert.azw3",
+    });
+    await seedPersonalBook(db, "hash-of-original", "/tmp/x.epub", "dune_-_frank_herbert.epub");
+
+    const [doc] = await getDocuments(app);
+    expect(doc?.hasFile).toBe(true);
+  });
+
+  it("lists a document once even when several uploads match it", async () => {
+    // EXISTS rather than a join: a join emits one row per match.
+    const filename = "Dune.epub";
+    await seedSyncDocument(db, { documentHash: koreaderFilenameHash(filename)!, filename });
+    await seedPersonalBook(db, "hash-a", "/tmp/a.epub", filename);
+    await seedPersonalBook(db, "hash-b", "/tmp/b.epub", "Dune.azw3");
+
+    const docs = await getDocuments(app);
+    expect(docs).toHaveLength(1);
+    expect(docs[0]?.hasFile).toBe(true);
+  });
+
+  it("does not match a file with no filename key to a document with none", async () => {
+    // Both keys null; `NULL = NULL` is not true, which is what stops every
+    // metadata-less document matching every metadata-less upload.
+    await seedSyncDocument(db, { documentHash: "hash-orphan" });
+    await db.updateTable("sync_document").set({ filenameKey: null }).execute();
+    await seedPersonalBook(db, "other-hash", "/tmp/nonexistent.epub");
+    await db.updateTable("personal_book").set({ filenameKey: null, filenameHash: null }).execute();
+
+    const [doc] = await getDocuments(app);
+    expect(doc?.hasFile).toBe(false);
+  });
+
   it("does not match another user's uploaded file", async () => {
     await seedSyncDocument(db, { documentHash: "hash-shared" });
     await seedPersonalBook(db, "hash-shared", "/tmp/nonexistent.epub");
@@ -456,7 +516,9 @@ describe("POST /library/upload", () => {
     db = await createTestDb();
     app = createApp(db);
     // Seed the row the uploader will collide with, keyed by the same hash the
-    // upload computes, so neither request reaches the filesystem.
+    // upload computes, so neither request reaches the library directory. This
+    // relies on the shared core running its duplicate check before the parse
+    // and before the rename — keep that ordering.
     await seedPersonalBook(db, koreaderPartialMD5(new TextEncoder().encode(FB2)), "/tmp/dupe.fb2");
   });
 
@@ -466,10 +528,12 @@ describe("POST /library/upload", () => {
     expect((await res.json()) as { error: string }).toHaveProperty("error");
   });
 
-  it("still redirects the browser back to the library", async () => {
+  it("redirects the browser back to the library with the reason", async () => {
+    // A plain <form> post used to get raw JSON rendered as a text page. Every
+    // failure now round-trips a code the library page can render as an alert.
     const res = await uploadRequest(app, { json: false });
     expect(res.status).toBe(302);
-    expect(res.headers.get("location")).toBe("/library");
+    expect(res.headers.get("location")).toBe("/library?error=AlreadyExists");
   });
 
   it("401s without a session", async () => {
diff --git a/src/routes/library.tsx b/src/routes/library.tsx
index 2e8de02..610c62a 100644
--- a/src/routes/library.tsx
+++ b/src/routes/library.tsx
@@ -1,6 +1,6 @@
 import { zValidator } from "@hono/zod-validator";
 import { Hono } from "hono";
-import { bodyLimit } from "hono/body-limit";
+import type { ContentfulStatusCode } from "hono/utils/http-status";
 import { z } from "zod";
 
 import type { AppEnv } from "../context";
@@ -9,204 +9,159 @@ import { currentSyncPassword, rotateSyncToken } from "../middleware/sync-auth";
 import { bridgeProgressToUserBook } from "../utils/syncBridge";
 import { updateBookRecord } from "../utils/getBook";
 import { READING } from "../constants";
-import {
-  detectFormat,
-  parseBook,
-  koreaderPartialMD5,
-  isUsableCover,
-} from "../utils/bookMetadata/index";
-import {
-  ensureDir,
-  personalBookDir,
-  bookFilePath,
-  coverFilePath,
-  streamPersonalBook,
-  MAX_PERSONAL_BOOK_BYTES,
-} from "../utils/personalLibrary";
-import { NO_HIVE_MATCH } from "../utils/syncMatching";
+import { streamPersonalBook, MAX_PERSONAL_BOOK_BYTES } from "../utils/personalLibrary";
+import { uploadPersonalBook } from "../utils/uploadPersonalBook";
+import { NO_HIVE_MATCH, SAME_BOOK_FILE } from "../utils/syncMatching";
 import type { HiveId, SyncProgressData } from "../types";
 
 const MAX_FILE_SIZE = MAX_PERSONAL_BOOK_BYTES;
 
-const app = new Hono<AppEnv>()
-  .get("/", async (c) => {
-    const agent = await c.get("ctx").getSessionAgent();
-    if (!agent) return c.redirect("/login");
-    const profile = await c.get("ctx").getProfile();
-    const handle = profile?.handle ?? agent.did;
-    const { db } = c.get("ctx");
+/**
+ * Headroom for multipart part headers and boundaries when checking the request's
+ * total `Content-Length` against the per-file limit. Generous on purpose — this
+ * is a cheap early reject, and the core enforces the real cap on the file itself.
+ */
+const MULTIPART_SLACK = 64 * 1024;
+
+/** Human-readable byte count for user-facing quota messages. */
+function formatBytes(bytes: number): string {
+  if (bytes >= 1024 ** 3) return `${(bytes / 1024 ** 3).toFixed(1)} GB`;
+  if (bytes >= 1024 ** 2) return `${Math.round(bytes / 1024 ** 2)} MB`;
+  return `${Math.round(bytes / 1024)} KB`;
+}
+
+/**
+ * The `?error=` codes the upload adapter redirects a browser back with. Closed
+ * set rather than a free string: it is the one input on this page that comes
+ * from the URL, and anything outside the list is someone hand-crafting a link
+ * to put an error banner on another user's library.
+ */
+const UPLOAD_ERROR_CODES = [
+  "TooLarge",
+  "QuotaExceeded",
+  "UnsupportedFormat",
+  "AlreadyExists",
+  "EmptyFile",
+  "NoFile",
+  "Busy",
+] as const;
 
-    // Drives the empty-vs-populated layout: with nothing uploaded and nothing
-    // synced there is no library to manage, so the page explains itself and
-    // puts setup inline instead of behind modals.
-    const [books, documents] = await Promise.all([
-      db
-        .selectFrom("personal_book")
-        .select((eb) => eb.fn.countAll<number>().as("total"))
-        .where("userDid", "=", agent.did)
-        .executeTakeFirstOrThrow(),
-      db
-        .selectFrom("sync_document")
-        .select((eb) => eb.fn.countAll<number>().as("total"))
-        .where("userDid", "=", agent.did)
-        .executeTakeFirstOrThrow(),
-    ]);
-
-    return c.render(
-      <LibraryPage
-        handle={handle}
-        bookCount={Number(books.total)}
-        syncDocCount={Number(documents.total)}
-      />,
-      { title: "Personal Library" },
-    );
-  })
-  .post(
-    "/upload",
-    // Rejects on Content-Length, and aborts the stream once the cap is passed
-    // when there is none. This has to run *before* the handler because
-    // `c.req.formData()` materialises the entire multipart body in native
-    // memory — the `file.size` check below cannot fire until after that has
-    // already happened, so on its own it bounds what we store, not what we
-    // allocate.
-    bodyLimit({
-      maxSize: MAX_FILE_SIZE,
-      onError: (c) => c.json({ error: "File exceeds 100 MB limit" }, 413),
-    }),
+const app = new Hono<AppEnv>()
+  .get(
+    "/",
+    // `.catch` rather than a hard 400: an unrecognised code means a stale or
+    // hand-edited link, and dropping the banner is a better answer than
+    // refusing to render the user's library.
+    zValidator(
+      "query",
+      z.object({ error: z.enum(UPLOAD_ERROR_CODES).optional().catch(undefined) }),
+    ),
     async (c) => {
       const agent = await c.get("ctx").getSessionAgent();
-      if (!agent) return c.json({ error: "Unauthorized" }, 401);
-
-      // The browser posts a plain <form> and wants to land back on the library;
-      // the mobile app posts the same multipart body but needs the created record
-      // (and a real status on duplicates) rather than a redirect to HTML.
-      const wantsJson = c.req.header("accept")?.includes("application/json") ?? false;
-
-      const formData = await c.req.formData();
-      const file = formData.get("file");
-      if (!file || !(file instanceof File)) {
-        return c.json({ error: "No file provided" }, 400);
-      }
-
-      // Check the declared size *before* materialising the file. The check used
-      // to run after `arrayBuffer()`, so rejecting an oversized upload still cost
-      // a full copy of it in native memory first.
-      if (file.size > MAX_FILE_SIZE) {
-        return c.json({ error: "File exceeds 100 MB limit" }, 413);
-      }
-
-      const bytes = new Uint8Array(await file.arrayBuffer());
-      if (bytes.length > MAX_FILE_SIZE) {
-        return c.json({ error: "File exceeds 100 MB limit" }, 413);
-      }
-
-      const formatInfo = detectFormat(bytes, file.name);
-      if (formatInfo.format === "unknown") {
-        return c.json({ error: "Unsupported file format" }, 400);
-      }
-
-      const contentHash = koreaderPartialMD5(bytes);
-
+      if (!agent) return c.redirect("/login");
+      const profile = await c.get("ctx").getProfile();
+      const handle = profile?.handle ?? agent.did;
       const { db } = c.get("ctx");
 
-      // Check for duplicate
-      const existing = await db
-        .selectFrom("personal_book")
-        .select("id")
-        .where("userDid", "=", agent.did)
-        .where("contentHash", "=", contentHash)
-        .executeTakeFirst();
-      if (existing) {
-        if (wantsJson) {
-          return c.json({ error: "This book is already in your library" }, 409);
-        }
-        return c.redirect("/library");
-      }
-
-      const metadata = parseBook(bytes, file.name);
-
-      await ensureDir(personalBookDir(agent.did, contentHash));
-
-      const filePath = bookFilePath(agent.did, contentHash, formatInfo.ext);
-      await Bun.write(filePath, bytes);
-
-      let coverPath: string | null = null;
-      let coverMime: string | null = null;
-      if (metadata.cover && (await isUsableCover(metadata.cover.bytes))) {
-        const cp = coverFilePath(agent.did, contentHash, metadata.cover.ext);
-        await Bun.write(cp, metadata.cover.bytes);
-        coverPath = cp;
-        coverMime = metadata.cover.mime;
-      }
-
-      // Try to match an existing sync_document (contentHash is the KOReader partial MD5)
-      let matchedHiveId: HiveId | null = null;
-      const syncDoc = await db
-        .selectFrom("sync_document")
-        .select(["hiveId"])
-        .where("userDid", "=", agent.did)
-        .where("documentHash", "=", contentHash)
-        .executeTakeFirst();
-      if (syncDoc?.hiveId) {
-        matchedHiveId = syncDoc.hiveId;
-      }
-
-      const now = new Date().toISOString();
-      await db
-        .insertInto("personal_book")
-        .values({
-          userDid: agent.did,
-          contentHash,
-          hiveId: matchedHiveId,
-          filename: file.name,
-          title: metadata.title,
-          authors: metadata.authors,
-          language: metadata.language || null,
-          format: formatInfo.format,
-          mime: formatInfo.mime,
-          filePath,
-          coverPath,
-          coverMime,
-          sizeBytes: bytes.length,
-          createdAt: now,
-          updatedAt: now,
-        })
-        .execute();
-
-      // Mark the book as owned if auto-linked and user has it in their library
-      if (matchedHiveId) {
-        await db
-          .updateTable("user_book")
-          .set({ owned: 1 })
+      // Drives the empty-vs-populated layout: with nothing uploaded and nothing
+      // synced there is no library to manage, so the page explains itself and
+      // puts setup inline instead of behind modals.
+      const [books, documents] = await Promise.all([
+        db
+          .selectFrom("personal_book")
+          .select((eb) => eb.fn.countAll<number>().as("total"))
+          .where("userDid", "=", agent.did)
+          .executeTakeFirstOrThrow(),
+        db
+          .selectFrom("sync_document")
+          .select((eb) => eb.fn.countAll<number>().as("total"))
           .where("userDid", "=", agent.did)
-          .where("hiveId", "=", matchedHiveId)
-          .where("owned", "=", 0)
-          .execute();
-      }
-
-      if (wantsJson) {
-        // Same shape as getPersonalLibrary#personalBookView so clients have one
-        // book type for both the list and the upload response.
-        return c.json({
-          book: {
-            contentHash,
-            title: metadata.title,
-            authors: metadata.authors || undefined,
-            language: metadata.language || undefined,
-            format: formatInfo.format,
-            mime: formatInfo.mime,
-            sizeBytes: bytes.length,
-            createdAt: now,
-            updatedAt: now,
-            hiveId: matchedHiveId ?? undefined,
-            coverUrl: coverPath ? `/library/covers/${contentHash}` : undefined,
-          },
-        });
-      }
-
-      return c.redirect("/library");
+          .executeTakeFirstOrThrow(),
+      ]);
+
+      return c.render(
+        <LibraryPage
+          handle={handle}
+          bookCount={Number(books.total)}
+          syncDocCount={Number(documents.total)}
+          uploadError={c.req.valid("query").error}
+        />,
+        { title: "Personal Library" },
+      );
     },
-  );
+  )
+  // Thin adapter over `uploadPersonalBook` — the same core the XRPC procedure
+  // calls. Everything here is transport: content negotiation and the mapping
+  // from the core's discriminated result to a status code.
+  //
+  // Note there is no `bodyLimit()` middleware any more. It only short-circuits
+  // on `Content-Length`; given a chunked body it drains the whole stream into
+  // an array and rebuilds the Request, so a compliant 100 MB chunked upload was
+  // buffered there *and again* by `formData()`. The core caps while streaming
+  // to disk, which bounds every path at one chunk.
+  .post("/upload", async (c) => {
+    const agent = await c.get("ctx").getSessionAgent();
+    if (!agent) return c.json({ error: "Unauthorized" }, 401);
+
+    // The browser posts a plain <form> and wants to land back on the library;
+    // the mobile app posts the same multipart body but needs the created record
+    // (and a real status on duplicates) rather than a redirect to HTML.
+    const wantsJson = c.req.header("accept")?.includes("application/json") ?? false;
+    const fail = (status: ContentfulStatusCode, code: string, error: string, extra = {}) =>
+      wantsJson
+        ? c.json({ error, code, ...extra }, status)
+        : c.redirect(`/library?error=${encodeURIComponent(code)}`);
+
+    // The early reject `bodyLimit` used to give. `formData()` below still
+    // materialises the File in native memory — Bun/hono expose no incremental
+    // multipart API — so refusing an obviously oversized body before parsing it
+    // is worth the two lines. MULTIPART_SLACK covers the part headers.
+    const declaredTotal = Number(c.req.header("content-length"));
+    if (Number.isFinite(declaredTotal) && declaredTotal > MAX_FILE_SIZE + MULTIPART_SLACK) {
+      return fail(413, "TooLarge", "File exceeds 100 MB limit");
+    }
+
+    const formData = await c.req.formData();
+    const file = formData.get("file");
+    if (!file || !(file instanceof File)) {
+      return fail(400, "NoFile", "No file provided");
+    }
+
+    const { db, kv } = c.get("ctx");
+    const result = await uploadPersonalBook({
+      db,
+      kv,
+      userDid: agent.did,
+      filename: file.name,
+      source: { kind: "stream", body: file.stream(), declaredLength: file.size },
+    });
+
+    if (result.ok) {
+      // Same shape as getPersonalLibrary#personalBookView so clients have one
+      // book type for both the list and the upload response.
+      return wantsJson ? c.json({ book: result.book }) : c.redirect("/library");
+    }
+
+    switch (result.reason) {
+      case "too-large":
+        return fail(413, "TooLarge", "File exceeds 100 MB limit");
+      case "quota-exceeded":
+        return fail(
+          413,
+          "QuotaExceeded",
+          `Library full — ${formatBytes(result.usedBytes)} of ${formatBytes(result.quotaBytes)} used. Delete a book to free space.`,
+          { usedBytes: result.usedBytes, quotaBytes: result.quotaBytes },
+        );
+      case "unsupported-format":
+        return fail(400, "UnsupportedFormat", "Unsupported file format");
+      case "duplicate":
+        return fail(409, "AlreadyExists", "This book is already in your library");
+      case "empty":
+        return fail(400, "EmptyFile", "The file is empty");
+      case "busy":
+        return fail(503, "Busy", "Server is busy — try again in a moment");
+    }
+  });
 
 // Serve cover images for personal library books
 app.get("/covers/:hash", async (c) => {
@@ -316,13 +271,6 @@ app.get("/sync/documents", async (c) => {
   const rows = await db
     .selectFrom("sync_document")
     .leftJoin("hive_book", "hive_book.id", "sync_document.hiveId")
-    // A document whose hash matches an uploaded file is the same book: the
-    // library grid renders it, so the sync sections must not claim it too.
-    .leftJoin("personal_book", (join) =>
-      join
-        .onRef("personal_book.contentHash", "=", "sync_document.documentHash")
-        .onRef("personal_book.userDid", "=", "sync_document.userDid"),
-    )
     .select([
       "sync_document.documentHash as document",
       "sync_document.title as title",
@@ -332,8 +280,22 @@ app.get("/sync/documents", async (c) => {
       "sync_document.updatedAt as updatedAt",
       "sync_document.hiveId as hiveId",
       "hive_book.title as bookTitle",
-      "personal_book.id as personalBookId",
     ])
+    // A document we hold the file for is the same book: the library grid
+    // renders it, so the sync sections must not claim it too. An EXISTS rather
+    // than a join because more than one upload can match one document (see
+    // SAME_BOOK_FILE) and a join would list the document once per match.
+    .select((eb) =>
+      eb
+        .exists(
+          eb
+            .selectFrom("personal_book")
+            .select("personal_book.id")
+            .whereRef("personal_book.userDid", "=", "sync_document.userDid")
+            .where(SAME_BOOK_FILE),
+        )
+        .as("hasFile"),
+    )
     .where("sync_document.userDid", "=", agent.did)
     .orderBy("sync_document.updatedAt", "desc")
     .execute();
@@ -362,7 +324,7 @@ app.get("/sync/documents", async (c) => {
       hiveId: dismissed ? null : row.hiveId,
       bookTitle: dismissed ? null : row.bookTitle,
       dismissed,
-      hasFile: row.personalBookId != null,
+      hasFile: Boolean(row.hasFile),
     };
   });
 
diff --git a/src/routes/opds.test.ts b/src/routes/opds.test.ts
index 35737c9..6a147e0 100644
--- a/src/routes/opds.test.ts
+++ b/src/routes/opds.test.ts
@@ -309,4 +309,41 @@ describe("OPDS 2.0 content negotiation", () => {
     expect(res.status).toBe(401);
     expect(res.headers.get("www-authenticate")).toContain("Basic");
   });
+
+  describe("cover caching", () => {
+    // This route sits under `/opds/books/`, which is excluded from hono's
+    // etag() middleware, so if it doesn't set a validator itself it cannot ever
+    // answer a conditional request. It didn't: production served 43 cover
+    // fetches in 48h and never once returned a 304, while a catalogue browse
+    // re-requests every cover on the page.
+    const coverPath = "/tmp/bookhive-opds-cover-test.jpg";
+
+    beforeEach(async () => {
+      await Bun.write(coverPath, "not-really-a-jpeg-but-bytes-are-bytes");
+      await seedBook(db, { contentHash: "hash-a", coverPath });
+    });
+
+    it("serves the cover with a strong ETag", async () => {
+      const res = await app.request("/opds/books/hash-a/cover", {
+        headers: { authorization: auth },
+      });
+      expect(res.status).toBe(200);
+      expect(res.headers.get("etag")).toBe('"hash-a-cover"');
+    });
+
+    it("answers a matching If-None-Match with 304 and no body", async () => {
+      const res = await app.request("/opds/books/hash-a/cover", {
+        headers: { authorization: auth, "if-none-match": '"hash-a-cover"' },
+      });
+      expect(res.status).toBe(304);
+      expect(await res.text()).toBe("");
+    });
+
+    it("still serves the bytes when the validator does not match", async () => {
+      const res = await app.request("/opds/books/hash-a/cover", {
+        headers: { authorization: auth, "if-none-match": '"something-else"' },
+      });
+      expect(res.status).toBe(200);
+    });
+  });
 });
diff --git a/src/routes/opds.ts b/src/routes/opds.ts
index bdfe4cf..2cab338 100644
--- a/src/routes/opds.ts
+++ b/src/routes/opds.ts
@@ -2,7 +2,7 @@ import { Hono, type Context } from "hono";
 import type { AppEnv } from "../context";
 import { opdsAuthMiddleware } from "../middleware/opds-auth";
 import { escapeXml } from "../utils/xml";
-import { OPDS_PAGE_SIZE, streamPersonalBook } from "../utils/personalLibrary";
+import { etagMatches, OPDS_PAGE_SIZE, streamPersonalBook } from "../utils/personalLibrary";
 import type { Selectable } from "kysely";
 import type { PersonalBookRow } from "../types";
 
@@ -19,7 +19,20 @@ const THUMBNAIL_REL = "http://opds-spec.org/image/thumbnail";
 
 type OpdsEnv = AppEnv & { Variables: { opdsUserDid: string } };
 
-type BookForEntry = Selectable<PersonalBookRow> & {
+// Only the columns an entry actually renders, so adding one to `personal_book`
+// (filename matching, say) does not oblige every feed query to select it.
+type BookForEntry = Pick<
+  Selectable<PersonalBookRow>,
+  | "contentHash"
+  | "hiveId"
+  | "title"
+  | "authors"
+  | "language"
+  | "mime"
+  | "coverPath"
+  | "coverMime"
+  | "updatedAt"
+> & {
   hiveBookCover?: string | null;
   hiveBookDescription?: string | null;
 };
@@ -555,10 +568,22 @@ app.get("/books/:hash/cover", async (c) => {
   if (book.coverPath) {
     const file = Bun.file(book.coverPath);
     if (await file.exists()) {
-      return c.body(file.stream(), 200, {
+      // This route is under `/opds/books/`, which is in ETAG_EXCLUDED_PREFIXES,
+      // so hono's etag() never sees it — without an ETag set here the response
+      // carries no validator at all and a 304 is impossible. Production bore
+      // that out: 43 cover fetches over 48h, none of them conditional, while
+      // the catalogue root was hit 431 times. The hash is immutable content, so
+      // the validator is free.
+      const etag = `"${hash}-cover"`;
+      const headers = {
         "Content-Type": book.coverMime || "image/jpeg",
         "Cache-Control": "private, max-age=86400",
-      });
+        ETag: etag,
+      };
+      if (etagMatches(c.req.header("if-none-match"), etag)) {
+        return c.body(null, 304, headers);
+      }
+      return c.body(file.stream(), 200, headers);
     }
   }
 
diff --git a/src/routes/sync/kosync.test.ts b/src/routes/sync/kosync.test.ts
new file mode 100644
index 0000000..a0411de
--- /dev/null
+++ b/src/routes/sync/kosync.test.ts
@@ -0,0 +1,283 @@
+/**
+ * End-to-end cover for the bug PR #204 reported: an ebook uploaded *before* the
+ * first KOSync push left `sync_document.hiveId` null forever, so reading
+ * progress never reached the user's public book.
+ *
+ * The upload's writeback couldn't help — the document didn't exist yet — and the
+ * KOSync handler only auto-matched on title/author, which a default-configured
+ * KOReader never sends. `matchSyncDocumentForUser` closes it from the other
+ * side: the document hash *is* the uploaded file's content hash, so the file's
+ * own metadata (and any book already linked to it) resolves the document.
+ *
+ * These tests drive the real route, so they fail if either half regresses.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { Database as DatabaseSync } from "bun:sqlite";
+import { Hono } from "hono";
+import { Kysely, SqliteDialect } from "kysely";
+import { createStorage } from "unstorage";
+import memoryDriver from "unstorage/drivers/memory";
+import { rm } from "node:fs/promises";
+import path from "node:path";
+import type { Storage } from "unstorage";
+
+import { wrapBunSqliteForKysely } from "../../bun-sqlite-kysely";
+import type { AppContext, AppEnv } from "../../context";
+import { migrateToLatest, type DatabaseSchema, type Database } from "../../db";
+import type { HiveId } from "../../types";
+import { currentSyncPassword } from "../../middleware/sync-auth";
+import { getHiveId } from "../../scrapers/getHiveId";
+import { koreaderPartialMD5 } from "../../utils/bookMetadata/index";
+import { makeEpub } from "../../utils/bookMetadata/testFixtures";
+import { personalBookDir } from "../../utils/personalLibrary";
+import { uploadPersonalBook } from "../../utils/uploadPersonalBook";
+import { NO_HIVE_MATCH } from "../../utils/syncMatching";
+import kosyncRouter from "./kosync";
+
+const DID = "did:plc:testuser";
+const HANDLE = "alice.bsky.social";
+
+let db: Database;
+let kv: Storage;
+
+async function createTestDb(): Promise<Database> {
+  const sqlite = new DatabaseSync(":memory:");
+  sqlite.exec("PRAGMA journal_mode = WAL");
+  const database = new Kysely<DatabaseSchema>({
+    dialect: new SqliteDialect({ database: wrapBunSqliteForKysely(sqlite) }),
+  });
+  await migrateToLatest(database, sqlite);
+  return database;
+}
+
+function createApp(): Hono<AppEnv> {
+  const app = new Hono<AppEnv>();
+  app.use("*", async (c, next) => {
+    c.set("ctx", {
+      db,
+      kv,
+      baseIdResolver: {
+        handle: { resolve: async (h: string) => (h === HANDLE ? DID : null) },
+      },
+      addWideEventContext: () => {},
+    } as unknown as AppContext);
+    await next();
+  });
+  app.route("/kosync", kosyncRouter);
+  return app;
+}
+
+/** KOSync sends md5 of the derived password, not the password itself. */
+async function authHeaders(): Promise<Record<string, string>> {
+  const password = await currentSyncPassword(kv, DID);
+  return {
+    "x-auth-user": HANDLE,
+    "x-auth-key": new Bun.CryptoHasher("md5").update(password).digest("hex"),
+    "content-type": "application/json",
+  };
+}
+
+/** Push progress the way a default-configured KOReader does: hash and nothing else. */
+async function pushProgress(
+  app: Hono<AppEnv>,
+  document: string,
+  percentage: number,
+  metadata?: { filename?: string; title?: string; authors?: string },
+) {
+  return app.request("/kosync/syncs/progress", {
+    method: "PUT",
+    headers: await authHeaders(),
+    body: JSON.stringify({
+      document,
+      progress: "/body/DocFragment[3]",
+      percentage,
+      device: "kindle",
+      device_id: "dev-1",
+      ...(metadata ? { metadata } : {}),
+    }),
+  });
+}
+
+async function seedHiveBook(title: string, authors: string): Promise<HiveId> {
+  const id = getHiveId({ title, authors });
+  await db
+    .insertInto("hive_book")
+    .values({
+      id,
+      title,
+      rawTitle: title,
+      authors,
+      source: "goodreads",
+      thumbnail: "",
+      createdAt: "2026-08-01T00:00:00.000Z",
+      updatedAt: "2026-08-01T00:00:00.000Z",
+    } as never)
+    .execute();
+  return id;
+}
+
+async function seedUserBook(hiveId: HiveId): Promise<void> {
+  await db
+    .insertInto("user_book")
+    .values({
+      uri: `at://${DID}/buzz.bookhive.book/${hiveId}`,
+      cid: "cid",
+      userDid: DID,
+      hiveId,
+      title: "t",
+      authors: "a",
+      status: "buzz.bookhive.defs#reading",
+      owned: 0,
+      createdAt: "2026-08-01T00:00:00.000Z",
+      indexedAt: "2026-08-01T00:00:00.000Z",
+    })
+    .execute();
+}
+
+beforeEach(async () => {
+  db = await createTestDb();
+  kv = createStorage({ driver: memoryDriver() });
+});
+
+afterEach(async () => {
+  await rm(path.dirname(personalBookDir(DID, "x")), { recursive: true, force: true }).catch(
+    () => {},
+  );
+});
+
+describe("PUT /kosync/syncs/progress — upload first, then sync", () => {
+  it("bridges progress to the public book for a client sending only a hash", async () => {
+    // This is the reported bug, in order: the file is uploaded, the catalogue
+    // book exists, and only then does the device push — with no metadata at all.
+    const hiveId = await seedHiveBook("Dune", "Frank Herbert");
+    await seedUserBook(hiveId);
+
+    const bytes = makeEpub({ title: "Dune", authors: ["Frank Herbert"] });
+    const upload = await uploadPersonalBook({
+      db,
+      kv,
+      userDid: DID,
+      filename: "Dune.epub",
+      source: {
+        kind: "stream",
+        body: new Blob([bytes as BlobPart]).stream(),
+        declaredLength: bytes.length,
+      },
+    });
+    expect(upload.ok).toBe(true);
+
+    const res = await pushProgress(createApp(), koreaderPartialMD5(bytes), 0.42);
+    expect(res.status).toBe(200);
+
+    const doc = await db.selectFrom("sync_document").select("hiveId").executeTakeFirstOrThrow();
+    expect(doc.hiveId).toBe(hiveId);
+
+    const userBook = await db
+      .selectFrom("user_book")
+      .select(["bookProgress", "owned"])
+      .executeTakeFirstOrThrow();
+    expect(JSON.parse(userBook.bookProgress!).percent).toBe(42);
+    expect(userBook.owned).toBe(1);
+  });
+
+  it("still bridges when the upload had already resolved the book itself", async () => {
+    // The file carries the link; the document inherits it rather than
+    // re-deriving it from metadata the client never sent.
+    const hiveId = await seedHiveBook("Neuromancer", "William Gibson");
+    await seedUserBook(hiveId);
+
+    const bytes = makeEpub({ title: "Neuromancer", authors: ["William Gibson"] });
+    await uploadPersonalBook({
+      db,
+      kv,
+      userDid: DID,
+      filename: "Neuromancer.epub",
+      source: {
+        kind: "stream",
+        body: new Blob([bytes as BlobPart]).stream(),
+        declaredLength: bytes.length,
+      },
+    });
+    const file = await db.selectFrom("personal_book").select("hiveId").executeTakeFirstOrThrow();
+    expect(file.hiveId).toBe(hiveId);
+
+    await pushProgress(createApp(), koreaderPartialMD5(bytes), 0.9);
+
+    const userBook = await db
+      .selectFrom("user_book")
+      .select("bookProgress")
+      .executeTakeFirstOrThrow();
+    expect(JSON.parse(userBook.bookProgress!).percent).toBe(90);
+  });
+
+  it("does not overwrite a link the user set by hand", async () => {
+    const theirs = await seedHiveBook("Dune", "Frank Herbert");
+    const manual = "bk_manualchoice" as HiveId;
+    const bytes = makeEpub({ title: "Dune", authors: ["Frank Herbert"] });
+
+    await db
+      .insertInto("sync_document")
+      .values({
+        userDid: DID,
+        provider: "kosync",
+        documentHash: koreaderPartialMD5(bytes),
+        hiveId: manual,
+        progressData: "{}",
+        createdAt: "2026-08-01T00:00:00.000Z",
+        updatedAt: "2026-08-01T00:00:00.000Z",
+      })
+      .execute();
+
+    await pushProgress(createApp(), koreaderPartialMD5(bytes), 0.5);
+
+    const doc = await db.selectFrom("sync_document").select("hiveId").executeTakeFirstOrThrow();
+    expect(doc.hiveId).toBe(manual);
+    expect(doc.hiveId).not.toBe(theirs);
+  });
+
+  it("respects a dismissed document and never bridges onto the sentinel", async () => {
+    const hiveId = await seedHiveBook("Dune", "Frank Herbert");
+    await seedUserBook(hiveId);
+    const bytes = makeEpub({ title: "Dune", authors: ["Frank Herbert"] });
+
+    await db
+      .insertInto("sync_document")
+      .values({
+        userDid: DID,
+        provider: "kosync",
+        documentHash: koreaderPartialMD5(bytes),
+        hiveId: NO_HIVE_MATCH,
+        progressData: "{}",
+        createdAt: "2026-08-01T00:00:00.000Z",
+        updatedAt: "2026-08-01T00:00:00.000Z",
+      })
+      .execute();
+
+    const res = await pushProgress(createApp(), koreaderPartialMD5(bytes), 0.5);
+    expect(res.status).toBe(200);
+
+    const doc = await db.selectFrom("sync_document").select("hiveId").executeTakeFirstOrThrow();
+    expect(doc.hiveId).toBe(NO_HIVE_MATCH);
+    const userBook = await db
+      .selectFrom("user_book")
+      .select("bookProgress")
+      .executeTakeFirstOrThrow();
+    expect(userBook.bookProgress).toBeNull();
+  });
+
+  it("401s without valid sync credentials", async () => {
+    const res = await createApp().request("/kosync/syncs/progress", {
+      method: "PUT",
+      headers: { "x-auth-user": HANDLE, "x-auth-key": "wrong", "content-type": "application/json" },
+      body: JSON.stringify({
+        document: "d",
+        progress: "p",
+        percentage: 0.1,
+        device: "k",
+        device_id: "1",
+      }),
+    });
+    expect(res.status).toBe(401);
+  });
+});
diff --git a/src/routes/sync/kosync.ts b/src/routes/sync/kosync.ts
index 1075b10..73b8c87 100644
--- a/src/routes/sync/kosync.ts
+++ b/src/routes/sync/kosync.ts
@@ -1,7 +1,8 @@
 import { Hono } from "hono";
 import type { AppEnv } from "../../context";
 import { syncAuthMiddleware } from "../../middleware/sync-auth";
-import { matchSyncDocument } from "../../utils/syncMatching";
+import { matchSyncDocumentForUser } from "../../utils/syncMatching";
+import { filenameKey } from "../../utils/filenameMatching";
 import { bridgeProgressToUserBook } from "../../utils/syncBridge";
 import type { HiveId, SyncProgressData } from "../../types";
 
@@ -75,7 +76,7 @@ app.put("/syncs/progress", syncAuthMiddleware, async (c) => {
       .set({
         progressData: JSON.stringify(progressData),
         updatedAt: now,
-        ...(filename != null ? { filename } : {}),
+        ...(filename != null ? { filename, filenameKey: filenameKey(filename) } : {}),
         ...(title != null ? { title } : {}),
         ...(authors != null ? { authors } : {}),
       })
@@ -90,6 +91,7 @@ app.put("/syncs/progress", syncAuthMiddleware, async (c) => {
         documentHash: document,
         hiveId: null,
         filename,
+        filenameKey: filenameKey(filename),
         title,
         authors,
         progressData: JSON.stringify(progressData),
@@ -101,8 +103,17 @@ app.put("/syncs/progress", syncAuthMiddleware, async (c) => {
 
   let hiveId = existing?.hiveId ?? null;
 
-  if (!hiveId && (title || authors)) {
-    hiveId = await matchSyncDocument(db, { title, authors, filename });
+  // Unconditional: a default-configured KOReader sends no metadata at all, and
+  // `matchSyncDocumentForUser` resolves those from the uploaded file the
+  // document hash points at. Gating this on the client having sent something is
+  // what kept both that case and the filename-only case unmatchable.
+  if (!hiveId) {
+    hiveId = await matchSyncDocumentForUser(db, userDid, {
+      documentHash: document,
+      title,
+      authors,
+      filename,
+    });
     if (hiveId) {
       await db
         .updateTable("sync_document")
@@ -110,6 +121,12 @@ app.put("/syncs/progress", syncAuthMiddleware, async (c) => {
         .where("userDid", "=", userDid)
         .where("provider", "=", "kosync")
         .where("documentHash", "=", document)
+        // Only fill a genuinely empty link. `hiveId` was read at the top of the
+        // handler and the match takes a few queries, so a concurrent request —
+        // or the user linking by hand in another tab — can land in between;
+        // production runs three worker processes, so this is not theoretical.
+        // It also can't clobber the NO_HIVE_MATCH dismissal sentinel.
+        .where("hiveId", "is", null)
         .execute();
     }
   }
diff --git a/src/test/env-setup.ts b/src/test/env-setup.ts
new file mode 100644
index 0000000..4725d47
--- /dev/null
+++ b/src/test/env-setup.ts
@@ -0,0 +1,22 @@
+/**
+ * Bun test preload — runs before any test file's imports, and therefore before
+ * `src/env.ts` is evaluated.
+ *
+ * This is load-bearing rather than cosmetic. `env` is frozen by envalid at
+ * import time, so a test can neither assign to it nor usefully mutate
+ * `process.env` afterwards (ESM imports hoist). Without this file `DB_PATH`
+ * falls back to its `devDefault` of `":memory:"`, which makes
+ * `getLibraryDir()` resolve to `path.dirname(":memory:") + "/library"` —
+ * i.e. `./library` **inside the repo working tree**. The first test that
+ * actually exercises an upload would write ebooks into the checkout.
+ *
+ * Both paths are set with `??=` so an explicit env var (CI, a targeted debug
+ * run) still wins.
+ */
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+const root = path.join(tmpdir(), "bookhive-test", String(process.pid));
+
+process.env["DB_PATH"] ??= path.join(root, "db.sqlite");
+process.env["LIBRARY_DIR"] ??= path.join(root, "library");
diff --git a/src/types.ts b/src/types.ts
index e3c7649..6a21588 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -283,6 +283,10 @@ export type PersonalBookRow = {
   contentHash: string;
   hiveId: HiveId | null;
   filename: string;
+  /** md5 of the basename — the id a FILENAME-checksum KOSync client sends. */
+  filenameHash: string | null;
+  /** Normalized, extension-less basename; survives format conversion. */
+  filenameKey: string | null;
   title: string;
   authors: string | null;
   language: string | null;
@@ -319,6 +323,8 @@ export type SyncDocumentRow = {
   documentHash: string;
   hiveId: HiveId | null;
   filename: string | null;
+  /** Normalized `filename`; see src/utils/filenameMatching.ts. */
+  filenameKey: string | null;
   title: string | null;
   authors: string | null;
   progressData: string;
diff --git a/src/utils/bookMatching.ts b/src/utils/bookMatching.ts
new file mode 100644
index 0000000..3af41ac
--- /dev/null
+++ b/src/utils/bookMatching.ts
@@ -0,0 +1,94 @@
+/**
+ * Fuzzy title/author scoring primitives, shared by anything that has to decide
+ * whether two differently-written strings name the same book.
+ *
+ * Ported from the MIT-licensed shelfcheck project
+ * (`nowells/libby-reading-list` — `app/lib/libby.ts` and `app/lib/dedupe.ts`)
+ * with light adaptation for BookHive (tab-separated authors, HiveId).
+ *
+ * These normalize on the ASCII range: `normalizeForMatch` drops any character
+ * outside `[a-z0-9\s]` rather than folding it, so callers with non-Latin input
+ * must fold diacritics themselves first (`src/utils/filenameMatching.ts` does)
+ * and must not treat an empty word list as agreement.
+ */
+
+const STOP_WORDS = new Set([
+  "a",
+  "an",
+  "the",
+  "and",
+  "or",
+  "of",
+  "in",
+  "on",
+  "at",
+  "to",
+  "for",
+  "is",
+  "it",
+  "by",
+  "as",
+  "be",
+  "no",
+  "not",
+  "but",
+  "from",
+  "with",
+]);
+
+/**
+ * Lowercase, strip non-alphanumerics, collapse whitespace.
+ *
+ * Note that punctuation is *deleted*, not replaced with a space, which is the
+ * point: "hitchhiker's" and "hitchhikers" collapse onto the same word instead
+ * of differing by a stray "s" token.
+ */
+export function normalizeForMatch(input: string): string {
+  return input
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/** Significant words in `s` after stop-word removal. */
+export function contentWords(s: string): string[] {
+  return normalizeForMatch(s)
+    .split(" ")
+    .filter((w) => w.length > 0 && !STOP_WORDS.has(w));
+}
+
+/**
+ * Sørensen–Dice on whitespace-separated words after normalization.
+ * Returns 1 for an exact normalized match.
+ */
+export function similarityScore(a: string, b: string): number {
+  const na = normalizeForMatch(a);
+  const nb = normalizeForMatch(b);
+  if (na === nb) return 1;
+
+  const wordsA = na.split(" ").filter(Boolean);
+  const wordsB = nb.split(" ").filter(Boolean);
+  if (wordsA.length === 0 || wordsB.length === 0) return 0;
+
+  const setB = new Set(wordsB);
+  const intersection = wordsA.filter((w) => setB.has(w));
+  return (2 * intersection.length) / (wordsA.length + wordsB.length);
+}
+
+/**
+ * All-content-words gate: every significant word in `searchTitle` must
+ * appear in `candidateTitle`. Keeps "Children of Time" from accepting
+ * "Children of Ruin", which would otherwise share a high Dice score from
+ * the series stem.
+ *
+ * Containment is one-directional, so it accepts a candidate that adds words —
+ * "Dune" passes against "Dune Messiah". Anywhere a superset is the *wrong*
+ * book, gate on it in both directions.
+ */
+export function contentWordsMatch(searchTitle: string, candidateTitle: string): boolean {
+  const searchContent = contentWords(searchTitle);
+  if (searchContent.length === 0) return true;
+  const candidateContent = new Set(contentWords(candidateTitle));
+  return searchContent.every((w) => candidateContent.has(w));
+}
diff --git a/src/utils/bookMetadata/bookMetadata.test.ts b/src/utils/bookMetadata/bookMetadata.test.ts
index 2c40cac..49d811a 100644
--- a/src/utils/bookMetadata/bookMetadata.test.ts
+++ b/src/utils/bookMetadata/bookMetadata.test.ts
@@ -1,6 +1,15 @@
 import { describe, expect, test } from "bun:test";
 import { zipSync, strToU8 } from "fflate";
-import { koreaderPartialMD5, parseBook, detectFormat, isUsableCover } from ".";
+import { imageMeta } from "image-meta";
+import {
+  koreaderPartialMD5,
+  parseBook,
+  detectFormat,
+  isUsableCover,
+  prepareCover,
+  MIN_COVER_DIMENSION,
+} from ".";
+import { makeSvgCover, PNG_32 } from "./testFixtures";
 
 // 1x1 red PNG (a degenerate placeholder cover).
 const RED_PNG = Uint8Array.from(
@@ -131,12 +140,83 @@ describe("detectFormat", () => {
 describe("isUsableCover", () => {
   test("accepts a real, adequately-sized image", async () => {
     const bigPng = await new Bun.Image(RED_PNG).resize(32, 48).png().bytes();
-    expect(await isUsableCover(bigPng)).toBe(true);
+    expect(isUsableCover(bigPng)).toBe(true);
   });
 
-  test("rejects a 1x1 placeholder and empty input", async () => {
-    expect(await isUsableCover(RED_PNG)).toBe(false);
-    expect(await isUsableCover(new Uint8Array())).toBe(false);
-    expect(await isUsableCover(undefined)).toBe(false);
+  test("rejects a 1x1 placeholder and empty input", () => {
+    expect(isUsableCover(RED_PNG)).toBe(false);
+    expect(isUsableCover(new Uint8Array())).toBe(false);
+    expect(isUsableCover(undefined)).toBe(false);
+  });
+
+  test("rejects bytes that are not an image at all", () => {
+    expect(isUsableCover(strToU8("definitely not an image"))).toBe(false);
+  });
+});
+
+// -----------------------------------------------------------------------------
+// prepareCover — the gate between "the parser found something" and "we store a
+// cover". Rasterizes SVG, because an SVG cover is a composition, not a wrapper.
+// -----------------------------------------------------------------------------
+
+describe("prepareCover", () => {
+  test("passes a raster cover through untouched", async () => {
+    const out = await prepareCover({ bytes: PNG_32, mime: "image/png", ext: "png" });
+    expect(out?.ext).toBe("png");
+    expect(out?.bytes).toBe(PNG_32);
+  });
+
+  test("rasterizes an SVG cover to a JPEG", async () => {
+    const out = await prepareCover({ bytes: makeSvgCover(), mime: "image/svg+xml", ext: "svg" });
+    expect(out).not.toBeNull();
+    // JPEG, not SVG: OPDS clients and e-readers can't be relied on to render
+    // vector covers, and nothing should ever write an SVG to the library.
+    expect(out!.ext).toBe("jpg");
+    expect(out!.mime).toBe("image/jpeg");
+    const meta = imageMeta(out!.bytes);
+    expect(meta.type).toBe("jpg");
+    expect(meta.width).toBeGreaterThanOrEqual(MIN_COVER_DIMENSION);
+  });
+
+  test("renders BOTH svg layers — the artwork and the lettering over it", async () => {
+    // The whole reason this rasterizes instead of unwrapping the embedded
+    // <image>. Rendering is deterministic, so comparing the full cover against
+    // each single-layer version pins down the two real failure modes:
+    //   - equal to the paths-only render  => the artwork was dropped
+    //     (what @takumi-rs does: it ignores the embedded <image> entirely)
+    //   - equal to the image-only render  => the lettering was dropped
+    //     (what pulling the base64 raster back out of the SVG does)
+    const render = async (layers: "both" | "image" | "paths") =>
+      (await prepareCover({
+        bytes: makeSvgCover({ layers }),
+        mime: "image/svg+xml",
+        ext: "svg",
+      }))!.bytes;
+
+    const [both, imageOnly, pathsOnly] = await Promise.all([
+      render("both"),
+      render("image"),
+      render("paths"),
+    ]);
+
+    expect(Buffer.compare(both, pathsOnly)).not.toBe(0);
+    expect(Buffer.compare(both, imageOnly)).not.toBe(0);
+    // Sanity: the two degenerate renders differ from each other too, so the
+    // assertions above can't both pass on a renderer that emits a constant.
+    expect(Buffer.compare(imageOnly, pathsOnly)).not.toBe(0);
+  });
+
+  test("returns null for an unrenderable SVG rather than throwing", async () => {
+    const out = await prepareCover({
+      bytes: strToU8("<svg><this is not valid"),
+      mime: "image/svg+xml",
+      ext: "svg",
+    });
+    expect(out).toBeNull();
+  });
+
+  test("returns null for a cover below the minimum dimension", async () => {
+    expect(await prepareCover({ bytes: RED_PNG, mime: "image/png", ext: "png" })).toBeNull();
+    expect(await prepareCover(undefined)).toBeNull();
   });
 });
diff --git a/src/utils/bookMetadata/cbz.ts b/src/utils/bookMetadata/cbz.ts
index 5309aaf..c695b84 100644
--- a/src/utils/bookMetadata/cbz.ts
+++ b/src/utils/bookMetadata/cbz.ts
@@ -4,6 +4,7 @@
 import { unzipSync } from "fflate";
 import type { BookCover, BookMetadata } from "./types";
 import { extOf, mimeForExt } from "./shared";
+import { MAX_COVER_BYTES } from "./cover";
 
 const IMAGE_EXTS = new Set(["jpg", "jpeg", "png", "gif", "bmp", "webp", "avif"]);
 
@@ -16,20 +17,34 @@ const collator = new Intl.Collator(undefined, { numeric: true });
 export function parseCbz(bytes: Uint8Array, fallbackTitle: string): BookMetadata {
   const fallback: BookMetadata = { title: fallbackTitle, authors: "" };
   try {
-    const files = unzipSync(bytes, {
-      filter: (f) => IMAGE_EXTS.has(extOf(f.name)),
+    // Pass 1: index every page without inflating one. This used to decompress
+    // the entire comic — every page — in order to keep page 1. Returning
+    // `false` still walks the central directory, so the names (and sizes) are
+    // free; a 100 MB CBZ no longer inflates ~100 MB of pages it discards.
+    const pages: { name: string; originalSize: number }[] = [];
+    unzipSync(bytes, {
+      filter: (f) => {
+        if (IMAGE_EXTS.has(extOf(f.name))) {
+          pages.push({ name: f.name, originalSize: f.originalSize });
+        }
+        return false;
+      },
     });
-    const names = Object.keys(files).sort((a, b) => collator.compare(a, b));
-    if (names.length === 0) return fallback;
+    if (pages.length === 0) return fallback;
 
-    const first = names[0];
-    if (!first) return fallback;
-    const ext = extOf(first) === "jpeg" ? "jpg" : extOf(first);
-    const cover: BookCover = {
-      bytes: files[first]!,
-      mime: mimeForExt(ext),
-      ext,
-    };
+    pages.sort((a, b) => collator.compare(a.name, b.name));
+    const first = pages[0]!;
+    if (first.originalSize > MAX_COVER_BYTES) return fallback;
+
+    // Pass 2: inflate exactly the first page.
+    const data = unzipSync(bytes, { filter: (f) => f.name === first.name })[first.name];
+    // `originalSize` above is the archive's own claim; re-check the bytes we
+    // actually got, since a crafted zip can understate it and covers are
+    // written outside the storage quota.
+    if (!data || data.length === 0 || data.length > MAX_COVER_BYTES) return fallback;
+
+    const ext = extOf(first.name) === "jpeg" ? "jpg" : extOf(first.name);
+    const cover: BookCover = { bytes: data, mime: mimeForExt(ext), ext };
     return { title: fallbackTitle, authors: "", cover };
   } catch {
     return fallback;
diff --git a/src/utils/bookMetadata/cover.ts b/src/utils/bookMetadata/cover.ts
index 7707d9f..12902ca 100644
--- a/src/utils/bookMetadata/cover.ts
+++ b/src/utils/bookMetadata/cover.ts
@@ -1,23 +1,109 @@
-// Cover validation.
+// Cover validation and normalization.
 //
 // A book can advertise a cover that is missing, undecodable (garbage bytes), or
 // nonsensical (e.g. a 1x1 transparent placeholder). Any of those render as a
 // blank box in the library grid, so we validate the extracted cover before
 // storing it and fall back to a generated placeholder when it doesn't hold up.
 
+import { imageMeta } from "image-meta";
+import { Resvg } from "@resvg/resvg-js";
+import type { BookCover } from "./types";
+import { mimeForExt } from "./shared";
+
 /** Minimum width/height (px) for a cover to be considered "real". */
 export const MIN_COVER_DIMENSION = 16;
 
 /**
- * Decode the cover header with Bun's native image pipeline and confirm it is a
- * real, sensibly-sized image. Never throws — returns false on any failure.
+ * Largest cover we will decompress out of an archive. The ZIP central
+ * directory tells us the decompressed size before we inflate anything, so this
+ * is checked ahead of the work rather than after it — a book advertising a
+ * 200 MB image as its cover simply doesn't get one.
+ */
+export const MAX_COVER_BYTES = 8 * 1024 * 1024;
+
+/**
+ * Width we rasterize an SVG cover to. The largest a cover is ever displayed is
+ * ~300 CSS px (the book detail page), so 700 covers a 2x screen with room to
+ * spare. It is also the memory and latency bound on the raster: `resvg` renders
+ * synchronously into an RGBA buffer, so the cost is `width x height x 4` and
+ * scales with the square of this number — 700 measured ~0.5s against ~2.4s at
+ * 1400, for an output no one can tell apart.
+ */
+const SVG_RASTER_WIDTH = 700;
+
+/** Quality for the JPEG we transcode a rasterized SVG to. */
+const SVG_JPEG_QUALITY = 82;
+
+function looksLikeSvg(bytes: Uint8Array): boolean {
+  // Sniff rather than trust the extension: `mimeForExt` is driven by the name
+  // inside the archive, and the manifest can lie. Only the first bytes matter —
+  // an XML declaration and/or a comment may precede the root element.
+  const head = new TextDecoder("utf-8", { fatal: false }).decode(bytes.subarray(0, 1024));
+  return /<svg[\s>]/i.test(head);
+}
+
+/**
+ * Turn an SVG cover into a raster one, or return null if it can't be rendered.
+ *
+ * This exists because **an SVG cover is not a wrapper around an image** — it is
+ * a composition. Standard Ebooks, which is one of the largest sources of
+ * public-domain EPUBs, ships every cover as an SVG holding the artwork in an
+ * `<image>` element *plus* the title and author as ~40 vector `<path>`s over a
+ * translucent band. Pulling the embedded raster back out (which is tempting,
+ * and was tried) silently drops the title and author; rendering only the vector
+ * layer (which is what `@takumi-rs` does — it ignores the embedded `<image>`)
+ * drops the artwork. Only a real SVG renderer produces the actual cover.
+ *
+ * The output is JPEG rather than WebP deliberately: these covers are served to
+ * OPDS clients and e-readers whose format support is unreliable and unknowable,
+ * and JPEG is the one format all of them read. It costs ~2x the bytes of WebP
+ * (75 KB vs 33 KB on a measured Standard Ebooks cover) against a PNG straight
+ * out of `resvg` that would have been 1.1 MB.
  */
-export async function isUsableCover(bytes: Uint8Array | undefined | null): Promise<boolean> {
+async function rasterizeSvgCover(bytes: Uint8Array): Promise<BookCover | null> {
+  try {
+    // `resvg` renders synchronously on this thread. The work is bounded by
+    // MAX_COVER_BYTES on the way in and SVG_RASTER_WIDTH on the way out, and it
+    // runs inside the upload core's parse semaphore, so at most
+    // UPLOAD_PARSE_CONCURRENCY of these can be in flight per process.
+    const png = new Resvg(Buffer.from(bytes), {
+      fitTo: { mode: "width", value: SVG_RASTER_WIDTH },
+      // A cover with transparency would otherwise flatten to black once we
+      // encode to JPEG, which has no alpha channel.
+      background: "white",
+      // Don't rescan the host font database on every instance — resvg-js does
+      // that per-`Resvg` and it is slow. These covers carry their text as
+      // outlined vector `<path>`s (Standard Ebooks), so no fonts are needed; an
+      // SVG that relied on live `<text>` would supply them via `fontFiles` here.
+      font: { loadSystemFonts: false },
+    })
+      .render()
+      .asPng();
+
+    const jpeg = await new Bun.Image(png).jpeg({ quality: SVG_JPEG_QUALITY }).bytes();
+    if (!jpeg || jpeg.length === 0) return null;
+    return { bytes: jpeg, mime: mimeForExt("jpg"), ext: "jpg" };
+  } catch {
+    // A malformed or unrenderable SVG is a missing cover, not a failed upload.
+    return null;
+  }
+}
+
+/**
+ * Confirm the bytes are a real, sensibly-sized image.
+ *
+ * Uses `image-meta` (header parse, no pixel decode) rather than Bun's native
+ * image pipeline, which rejects SVG outright as an "unrecognised format" — that
+ * is what made every Standard Ebooks upload land with no cover at all. The two
+ * agree exactly on every raster format; `image-meta` just knows more of them.
+ */
+export function isUsableCover(bytes: Uint8Array | undefined | null): boolean {
   if (!bytes || bytes.length === 0) return false;
   try {
-    // metadata() reads the header only (no full pixel decode).
-    const { width, height } = await new Bun.Image(bytes).metadata();
+    const { width, height } = imageMeta(bytes);
     return (
+      typeof width === "number" &&
+      typeof height === "number" &&
       Number.isFinite(width) &&
       Number.isFinite(height) &&
       width >= MIN_COVER_DIMENSION &&
@@ -27,3 +113,20 @@ export async function isUsableCover(bytes: Uint8Array | undefined | null): Promi
     return false;
   }
 }
+
+/**
+ * The one gate between "the parser found something" and "we store a cover":
+ * rasterizes SVG, then validates whatever we ended up with. Returns null when
+ * there is no cover worth keeping.
+ *
+ * `coverPath IS NOT NULL` is the only signal driving `coverUrl` on the web
+ * library, the OPDS feed and the XRPC book view, so anything that gets past
+ * here has to actually render in all three.
+ */
+export async function prepareCover(cover: BookCover | null | undefined): Promise<BookCover | null> {
+  if (!cover?.bytes || cover.bytes.length === 0) return null;
+
+  const resolved = looksLikeSvg(cover.bytes) ? await rasterizeSvgCover(cover.bytes) : cover;
+  if (!resolved) return null;
+  return isUsableCover(resolved.bytes) ? resolved : null;
+}
diff --git a/src/utils/bookMetadata/epub.ts b/src/utils/bookMetadata/epub.ts
index 510f6f6..72f2728 100644
--- a/src/utils/bookMetadata/epub.ts
+++ b/src/utils/bookMetadata/epub.ts
@@ -1,6 +1,12 @@
 import { unzipSync, strFromU8 } from "fflate";
 import type { BookCover, BookMetadata } from "./types";
 import { attr, decodeXmlEntities, mimeForExt } from "./shared";
+import { MAX_COVER_BYTES } from "./cover";
+
+const IMAGE_NAME_RE = /\.(?:jpg|jpeg|png|gif|webp|svg)$/i;
+
+/** One archive entry we know about but have deliberately not inflated yet. */
+type ImageEntry = { name: string; originalSize: number };
 
 /** Extract inner text of the first matching <dc:tag> (or <tag>) element. */
 function firstDcValue(xml: string, tag: string): string | undefined {
@@ -45,22 +51,25 @@ function resolveHref(opfPath: string, href: string): string {
 export function parseEpub(bytes: Uint8Array, fallbackTitle: string): BookMetadata {
   const fallback: BookMetadata = { title: fallbackTitle, authors: "" };
 
+  // Pass 1: inflate ONLY container.xml and the .opf, while noting the name and
+  // size of every image without inflating any of them.
+  //
+  // This used to decompress every image in the archive in order to keep one.
+  // Returning `false` from the filter still walks the central directory — the
+  // entry's name and `originalSize` are available for free — so an index costs
+  // nothing and the ~100 MB of pages in a large CBZ-style EPUB is never
+  // materialised. See the second pass below for the one entry we do inflate.
+  const images: ImageEntry[] = [];
   let files: Record<string, Uint8Array>;
   try {
-    // Only decompress the small files we actually need plus any image (cover).
     files = unzipSync(bytes, {
       filter(file) {
         const n = file.name.toLowerCase();
-        return (
-          n === "meta-inf/container.xml" ||
-          n.endsWith(".opf") ||
-          n.endsWith(".jpg") ||
-          n.endsWith(".jpeg") ||
-          n.endsWith(".png") ||
-          n.endsWith(".gif") ||
-          n.endsWith(".webp") ||
-          n.endsWith(".svg")
-        );
+        if (IMAGE_NAME_RE.test(n)) {
+          images.push({ name: file.name, originalSize: file.originalSize });
+          return false;
+        }
+        return n === "meta-inf/container.xml" || n.endsWith(".opf");
       },
     });
   } catch {
@@ -101,27 +110,47 @@ export function parseEpub(bytes: Uint8Array, fallbackTitle: string): BookMetadat
   const language = firstDcValue(opf, "language");
   const identifier = firstDcValue(opf, "identifier");
 
-  // 3. Locate the cover image.
-  const cover = findCover(opf, opfPath, byLowerName);
+  // 3. Locate the cover image, then inflate exactly that one entry.
+  const imagesByLowerName = new Map<string, ImageEntry>();
+  for (const image of images) imagesByLowerName.set(image.name.toLowerCase(), image);
+  const cover = inflateCover(bytes, findCoverEntry(opf, opfPath, imagesByLowerName));
 
   return { title, authors, language, identifier, cover };
 }
 
-function findCover(
+/**
+ * Pass 2: decompress the single chosen image. Guarded on `originalSize` so a
+ * book advertising a 200 MB "cover" can't inflate unbounded — nothing we do
+ * with a cover needs more than MAX_COVER_BYTES.
+ */
+function inflateCover(bytes: Uint8Array, entry: ImageEntry | undefined): BookCover | undefined {
+  if (!entry || entry.originalSize > MAX_COVER_BYTES) return undefined;
+  let data: Uint8Array | undefined;
+  try {
+    data = unzipSync(bytes, { filter: (f) => f.name === entry.name })[entry.name];
+  } catch {
+    return undefined;
+  }
+  // `originalSize` above is the archive's own claim about the entry. Check the
+  // bytes we actually got as well: a crafted zip can understate it, and covers
+  // are written outside the storage quota, so an unchecked one is a way to put
+  // arbitrarily many bytes on our disk for free.
+  if (!data || data.length === 0 || data.length > MAX_COVER_BYTES) return undefined;
+  const ext = (entry.name.split(".").pop() || "").toLowerCase();
+  const normExt = ext === "jpeg" ? "jpg" : ext;
+  return { bytes: data, mime: mimeForExt(normExt), ext: normExt };
+}
+
+function findCoverEntry(
   opf: string,
   opfPath: string,
-  byLowerName: Map<string, { name: string; data: Uint8Array }>,
-): BookCover | undefined {
+  byLowerName: Map<string, ImageEntry>,
+): ImageEntry | undefined {
   const itemTags = opf.match(/<item\b[^>]*>/gi) ?? [];
 
-  const findByHref = (href?: string): BookCover | undefined => {
+  const findByHref = (href?: string): ImageEntry | undefined => {
     if (!href) return undefined;
-    const resolved = resolveHref(opfPath, href).toLowerCase();
-    const entry = byLowerName.get(resolved);
-    if (!entry) return undefined;
-    const ext = (entry.name.split(".").pop() || "").toLowerCase();
-    const normExt = ext === "jpeg" ? "jpg" : ext;
-    return { bytes: entry.data, mime: mimeForExt(normExt), ext: normExt };
+    return byLowerName.get(resolveHref(opfPath, href).toLowerCase());
   };
 
   // EPUB3: item with properties="cover-image".
diff --git a/src/utils/bookMetadata/hash.ts b/src/utils/bookMetadata/hash.ts
index a27ccb8..84b29f7 100644
--- a/src/utils/bookMetadata/hash.ts
+++ b/src/utils/bookMetadata/hash.ts
@@ -29,3 +29,29 @@ export function koreaderPartialMD5(bytes: Uint8Array): string {
   }
   return hasher.digest("hex");
 }
+
+/**
+ * The same hash, read straight off a file instead of a buffer.
+ *
+ * The algorithm only ever touches twelve 1 KB windows, so it never needed the
+ * whole file resident — the buffer was incidental to how the upload path used
+ * to work. Reading the slices costs at most 12 KB regardless of file size,
+ * which is what lets an upload be hashed (and rejected as a duplicate) before
+ * anything is materialised.
+ *
+ * Must stay byte-for-byte equivalent to `koreaderPartialMD5`: the resulting
+ * hash is what lines an uploaded file up with the `document` id a KOReader
+ * device sends. `bookMetadata.test.ts` pins the two together.
+ */
+export async function koreaderPartialMD5File(file: Blob, size: number): Promise<string> {
+  const step = 1024;
+  const window = 1024;
+  const hasher = new Bun.CryptoHasher("md5");
+  for (let i = -1; i <= 10; i++) {
+    const offset = (step << ((2 * i) & 0x1f)) >>> 0; // i === -1 -> 0
+    if (offset >= size) break;
+    const end = Math.min(offset + window, size);
+    hasher.update(new Uint8Array(await file.slice(offset, end).arrayBuffer()));
+  }
+  return hasher.digest("hex");
+}
diff --git a/src/utils/bookMetadata/index.ts b/src/utils/bookMetadata/index.ts
index ae7798b..e187a35 100644
--- a/src/utils/bookMetadata/index.ts
+++ b/src/utils/bookMetadata/index.ts
@@ -96,10 +96,21 @@ export function detectFormat(bytes: Uint8Array, filename: string): FormatInfo {
   return unknown(ext);
 }
 
-/** Parse metadata for any supported format. Never throws. */
-export function parseBook(bytes: Uint8Array, filename: string): BookMetadata {
+/**
+ * Parse metadata for any supported format. Never throws.
+ *
+ * `formatInfo` is optional purely to save re-deriving it: the upload path
+ * already ran `detectFormat` against a 4 KB head to decide whether to accept
+ * the file at all, and re-running it here would be the only reason that call
+ * needed the full buffer.
+ */
+export function parseBook(
+  bytes: Uint8Array,
+  filename: string,
+  formatInfo?: FormatInfo,
+): BookMetadata {
   const fallbackTitle = filename.replace(/\.[^.]+$/, "");
-  const { format } = detectFormat(bytes, filename);
+  const { format } = formatInfo ?? detectFormat(bytes, filename);
   switch (format) {
     case "epub":
       return parseEpub(bytes, fallbackTitle);
@@ -114,8 +125,8 @@ export function parseBook(bytes: Uint8Array, filename: string): BookMetadata {
   }
 }
 
-export { koreaderPartialMD5 } from "./hash";
+export { koreaderPartialMD5, koreaderPartialMD5File } from "./hash";
 export { looksLikeZip } from "./shared";
 export { parseEpub } from "./epub";
-export { isUsableCover, MIN_COVER_DIMENSION } from "./cover";
+export { isUsableCover, prepareCover, MAX_COVER_BYTES, MIN_COVER_DIMENSION } from "./cover";
 export type { BookCover, BookMetadata, EpubCover, EpubMetadata } from "./types";
diff --git a/src/utils/bookMetadata/testFixtures.ts b/src/utils/bookMetadata/testFixtures.ts
new file mode 100644
index 0000000..c8a3643
--- /dev/null
+++ b/src/utils/bookMetadata/testFixtures.ts
@@ -0,0 +1,225 @@
+/**
+ * Synthetic ebook fixtures for tests.
+ *
+ * Built with fflate's `zipSync` rather than checked in as binaries so the
+ * contents are readable in the diff and a test can vary one thing (a 1x1 cover,
+ * an oversized page) without a new blob appearing in the repo.
+ */
+
+import { zipSync, strToU8 } from "fflate";
+import { deflateSync } from "node:zlib";
+
+/**
+ * A real 32x32 PNG. Has to decode for `isUsableCover` — which reads the header
+ * with Bun's image pipeline — so it can't be arbitrary bytes.
+ */
+export const PNG_32 = makeSolidPng();
+
+/**
+ * An **opaque** 32x32 PNG in a solid colour. `PNG_32` is all-zero RGBA, i.e.
+ * fully transparent — fine as "a real image" for the dimension gate, useless as
+ * artwork in a fixture that has to be visually distinguishable from the
+ * background it is composited over.
+ */
+export const PNG_32_OPAQUE = makeSolidPng([220, 20, 20, 255]);
+
+/** A 32x32 8-bit RGBA PNG filled with `rgba` (default: transparent). */
+function makeSolidPng(rgba: [number, number, number, number] = [0, 0, 0, 0]): Uint8Array {
+  // 32x32, 8-bit RGBA, single IDAT; one filter byte per scanline.
+  const raw = new Uint8Array(32 * (32 * 4 + 1));
+  for (let y = 0; y < 32; y++) {
+    const rowStart = y * (32 * 4 + 1);
+    raw[rowStart] = 0; // filter: none
+    for (let x = 0; x < 32; x++) {
+      const px = rowStart + 1 + x * 4;
+      raw[px] = rgba[0]!;
+      raw[px + 1] = rgba[1]!;
+      raw[px + 2] = rgba[2]!;
+      raw[px + 3] = rgba[3]!;
+    }
+  }
+  // `node:zlib`, not `Bun.deflateSync`: the latter emits a *raw* deflate stream
+  // (0x63 0x60...) while PNG's IDAT must hold a zlib one (0x78 ...). Bun's own
+  // image decoder accepts the raw form, so this fixture looked fine for a long
+  // time — but a strict decoder (resvg) silently renders nothing, which turns
+  // an SVG-compositing test into a false pass.
+  const idat = deflateSync(raw);
+  const chunks: Uint8Array[] = [];
+  const be32 = (n: number) =>
+    new Uint8Array([(n >>> 24) & 255, (n >>> 16) & 255, (n >>> 8) & 255, n & 255]);
+  const crcTable = (() => {
+    const t = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+      let c = n;
+      for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+      t[n] = c >>> 0;
+    }
+    return t;
+  })();
+  const crc = (bytes: Uint8Array) => {
+    let c = 0xffffffff;
+    for (const b of bytes) c = crcTable[(c ^ b) & 0xff]! ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+  };
+  const chunk = (type: string, data: Uint8Array) => {
+    const typeBytes = new TextEncoder().encode(type);
+    const body = new Uint8Array(typeBytes.length + data.length);
+    body.set(typeBytes);
+    body.set(data, typeBytes.length);
+    chunks.push(be32(data.length), body, be32(crc(body)));
+  };
+  const ihdr = new Uint8Array(13);
+  ihdr.set(be32(32), 0);
+  ihdr.set(be32(32), 4);
+  ihdr[8] = 8; // bit depth
+  ihdr[9] = 6; // RGBA
+  chunk("IHDR", ihdr);
+  chunk("IDAT", idat);
+  chunk("IEND", new Uint8Array(0));
+
+  const signature = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+  const total = signature.length + chunks.reduce((n, c) => n + c.length, 0);
+  const out = new Uint8Array(total);
+  out.set(signature);
+  let offset = signature.length;
+  for (const c of chunks) {
+    out.set(c, offset);
+    offset += c.length;
+  }
+  return out;
+}
+
+/** A 1x1 PNG — decodes fine, but below MIN_COVER_DIMENSION so it must be rejected. */
+export const PNG_1 = new Uint8Array([
+  0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00, 0x00, 0x0d, 0x49, 0x48, 0x44, 0x52,
+  0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01, 0x08, 0x06, 0x00, 0x00, 0x00, 0x1f, 0x15, 0xc4,
+  0x89, 0x00, 0x00, 0x00, 0x0a, 0x49, 0x44, 0x41, 0x54, 0x78, 0x9c, 0x63, 0x00, 0x01, 0x00, 0x00,
+  0x05, 0x00, 0x01, 0x0d, 0x0a, 0x2d, 0xb4, 0x00, 0x00, 0x00, 0x00, 0x49, 0x45, 0x4e, 0x44, 0xae,
+  0x42, 0x60, 0x82,
+]);
+
+/**
+ * An SVG cover shaped like the ones Standard Ebooks ships: raster artwork in an
+ * `<image>` element with the title typeset over it as vector `<path>`s.
+ *
+ * Both layers matter, and the two ways of getting this wrong drop one each —
+ * extracting the embedded raster loses the lettering, rendering only the vector
+ * layer loses the artwork. `layers` builds the two degenerate versions so a
+ * test can assert the real render matches neither.
+ */
+export function makeSvgCover(
+  options: { width?: number; height?: number; layers?: "both" | "image" | "paths" } = {},
+): Uint8Array {
+  const { width = 200, height = 300, layers = "both" } = options;
+  // PNG_32 rather than something smaller: resvg declines to render very tiny
+  // embedded rasters (a 2x2 silently produced a blank layer), which would make
+  // this fixture assert the opposite of what it means to.
+  const artwork =
+    layers === "paths"
+      ? ""
+      : `<image height="${height}" width="${width}" x="0" y="0" ` +
+        `xlink:href="data:image/png;base64,${Buffer.from(PNG_32_OPAQUE).toString("base64")}"/>`;
+  // The "title band" — the layer that unwrapping the <image> would lose.
+  const lettering =
+    layers === "image"
+      ? ""
+      : `<path d="M 0,${height - 40} ${width},${height - 40} ${width},${height} 0,${height} Z"/>`;
+
+  return strToU8(
+    `<?xml version="1.0" encoding="utf-8"?>` +
+      `<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" ` +
+      `version="1.1" viewBox="0 0 ${width} ${height}">` +
+      `<title>The cover for the test edition</title>` +
+      `<style type="text/css">path{fill: #00f;}</style>` +
+      artwork +
+      lettering +
+      `</svg>`,
+  );
+}
+
+export type EpubFixtureOptions = {
+  title?: string;
+  authors?: string[];
+  language?: string;
+  /** Cover image bytes; omit for a book with no cover at all. */
+  cover?: Uint8Array | undefined;
+  /**
+   * Name the cover is stored under inside the archive, and the media-type
+   * declared for it in the OPF manifest. Defaults to a PNG; pass
+   * `{ coverName: "cover.svg", coverMediaType: "image/svg+xml" }` with
+   * `makeSvgCover()` to build a Standard-Ebooks-shaped book.
+   */
+  coverName?: string;
+  coverMediaType?: string;
+  /** Extra padding, to push the file past a size threshold. */
+  padBytes?: number;
+};
+
+/** A minimal but genuinely valid EPUB: mimetype, container.xml, OPF, cover. */
+export function makeEpub(options: EpubFixtureOptions = {}): Uint8Array {
+  const {
+    title = "The Test Book",
+    authors = ["A Test Author"],
+    language = "en",
+    cover = PNG_32,
+    coverName = "cover.png",
+    coverMediaType = "image/png",
+    padBytes = 0,
+  } = options;
+
+  const manifest = cover
+    ? `<item id="cover" href="images/${coverName}" media-type="${coverMediaType}" properties="cover-image"/>`
+    : "";
+  const opf =
+    `<?xml version="1.0" encoding="UTF-8"?>` +
+    `<package xmlns="http://www.idpf.org/2007/opf" version="3.0">` +
+    `<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">` +
+    `<dc:title>${title}</dc:title>` +
+    authors.map((a) => `<dc:creator>${a}</dc:creator>`).join("") +
+    `<dc:language>${language}</dc:language>` +
+    `</metadata><manifest>${manifest}</manifest></package>`;
+
+  const files: Record<string, Uint8Array> = {
+    mimetype: strToU8("application/epub+zip"),
+    "META-INF/container.xml": strToU8(
+      `<?xml version="1.0"?><container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container">` +
+        `<rootfiles><rootfile full-path="OEBPS/content.opf" media-type="application/oebps-package+xml"/></rootfiles></container>`,
+    ),
+    "OEBPS/content.opf": strToU8(opf),
+  };
+  if (cover) files[`OEBPS/images/${coverName}`] = cover;
+  if (padBytes > 0) {
+    // Random so it doesn't deflate to nothing — the point of padding is size.
+    const pad = new Uint8Array(padBytes);
+    crypto.getRandomValues(pad);
+    files["OEBPS/pad.bin"] = pad;
+  }
+  return zipSync(files);
+}
+
+/**
+ * A CBZ whose pages sort such that page 1 is small and page 2 is large — so a
+ * test can assert the cover extractor took the first page without inflating
+ * the rest.
+ */
+export function makeCbz(pageCount = 20, bigPageBytes = 200_000): Uint8Array {
+  const files: Record<string, Uint8Array> = { "001.png": PNG_32 };
+  for (let i = 2; i <= pageCount; i++) {
+    const big = new Uint8Array(bigPageBytes);
+    big.set(PNG_32);
+    files[`${String(i).padStart(3, "0")}.png`] = big;
+  }
+  return zipSync(files);
+}
+
+/** The smallest thing `detectFormat` accepts with no zip container. */
+export function makeFb2(title = "FB2 Book", author = "FB2 Author"): Uint8Array {
+  return strToU8(
+    `<?xml version="1.0" encoding="UTF-8"?>` +
+      `<FictionBook xmlns="http://www.gribuser.ru/xml/fictionbook/2.0">` +
+      `<description><title-info>` +
+      `<book-title>${title}</book-title>` +
+      `<author><first-name>${author.split(" ")[0]}</first-name><last-name>${author.split(" ").slice(1).join(" ")}</last-name></author>` +
+      `</title-info></description><body/></FictionBook>`,
+  );
+}
diff --git a/src/utils/catalogBookService.test.ts b/src/utils/catalogBookService.test.ts
new file mode 100644
index 0000000..e1381fe
--- /dev/null
+++ b/src/utils/catalogBookService.test.ts
@@ -0,0 +1,83 @@
+/**
+ * Backfill progress persistence.
+ *
+ * `backfillCatalogBooks` runs for hours on the primary worker, but
+ * `/admin/backfill-catalog/progress` is answered by whichever of the three
+ * cluster workers the request lands on — and by a fresh process after any
+ * restart. Without the KV mirror those requests reported `idle` for a job that
+ * was running, or lost the outcome of one that had finished.
+ */
+
+import { describe, it, expect, beforeEach } from "bun:test";
+import { createStorage } from "unstorage";
+import memoryDriver from "unstorage/drivers/memory";
+import type { Storage } from "unstorage";
+
+import { getBackfillProgress, type BackfillProgress } from "./catalogBookService";
+
+const KEY = "backfill:catalog_progress";
+
+let kv: Storage;
+
+beforeEach(() => {
+  kv = createStorage({ driver: memoryDriver() });
+});
+
+function stored(overrides: Partial<BackfillProgress>): BackfillProgress {
+  return {
+    status: "running",
+    startedAt: "2026-08-01T00:00:00.000Z",
+    completedAt: null,
+    written: 120,
+    batches: 5,
+    totalPending: 900,
+    lastBatchAt: "2026-08-01T00:20:00.000Z",
+    error: null,
+    ...overrides,
+  };
+}
+
+describe("getBackfillProgress", () => {
+  it("reports idle when nothing has ever run", async () => {
+    expect((await getBackfillProgress(kv)).status).toBe("idle");
+  });
+
+  it("still answers without a KV, for callers that have none", async () => {
+    expect((await getBackfillProgress()).status).toBe("idle");
+  });
+
+  it("reads a completed run back out of the KV", async () => {
+    await kv.setItem(KEY, stored({ status: "completed", completedAt: "2026-08-01T01:00:00.000Z" }));
+    const progress = await getBackfillProgress(kv);
+    expect(progress.status).toBe("completed");
+    expect(progress.written).toBe(120);
+    expect(progress.batches).toBe(5);
+  });
+
+  it("reports a stored 'running' as interrupted", async () => {
+    // A genuinely live run answers from this process's memory, so a *stored*
+    // "running" can only mean the process died mid-run. Leaving it as "running"
+    // would show a job that never finishes and never fails.
+    await kv.setItem(KEY, stored({ status: "running" }));
+    const progress = await getBackfillProgress(kv);
+    expect(progress.status).toBe("interrupted");
+    expect(progress.completedAt).toBe("2026-08-01T00:20:00.000Z");
+    expect(progress.error).toContain("restarted");
+  });
+
+  it("falls back to idle rather than throwing on an unusable entry", async () => {
+    await kv.setItem(KEY, "{not json");
+    expect((await getBackfillProgress(kv)).status).toBe("idle");
+  });
+
+  it("survives the JSON round trip unstorage actually performs", async () => {
+    // The trap this pins: unstorage runs `destr` over what a driver returns, so
+    // persisting `JSON.stringify(progress)` reads back as an object and any
+    // `JSON.parse` of it throws — which silently discarded every stored run.
+    // Store the object; let unstorage handle serialization.
+    await kv.setItem(KEY, stored({ status: "completed" }));
+    const raw = await kv.getItem(KEY);
+    expect(typeof raw).toBe("object");
+    expect((await getBackfillProgress(kv)).status).toBe("completed");
+  });
+});
diff --git a/src/utils/catalogBookService.ts b/src/utils/catalogBookService.ts
index a37e549..47ad128 100644
--- a/src/utils/catalogBookService.ts
+++ b/src/utils/catalogBookService.ts
@@ -2,6 +2,7 @@ import { Client } from "@atcute/client";
 import { PasswordSession } from "@atcute/password-session";
 import type { ActorIdentifier } from "@atcute/lexicons/syntax";
 import type { Logger } from "pino";
+import type { Storage } from "unstorage";
 import type { SessionClient } from "../auth/client";
 import type { AppContext } from "../context";
 import { createActorResolver } from "../bsky/id-resolver";
@@ -39,6 +40,8 @@ export async function createServiceAccountAgent(
 
 type CatalogCtx = Pick<AppContext, "db"> & {
   serviceAccountAgent: AppContext["serviceAccountAgent"] | undefined;
+  /** Optional: when present, backfill progress is persisted across restarts. */
+  kv?: Storage;
   logger?: Logger;
 };
 
@@ -234,7 +237,7 @@ class RateLimitError extends Error {
 }
 
 export interface BackfillProgress {
-  status: "idle" | "running" | "completed" | "failed";
+  status: "idle" | "running" | "completed" | "failed" | "interrupted";
   startedAt: string | null;
   completedAt: string | null;
   written: number;
@@ -244,6 +247,8 @@ export interface BackfillProgress {
   error: string | null;
 }
 
+const BACKFILL_KV_KEY = "backfill:catalog_progress";
+
 let backfillProgress: BackfillProgress = {
   status: "idle",
   startedAt: null,
@@ -255,8 +260,48 @@ let backfillProgress: BackfillProgress = {
   error: null,
 };
 
-export function getBackfillProgress(): BackfillProgress {
-  return { ...backfillProgress };
+/**
+ * Mirror the in-memory progress into the KV so it survives a restart. Fire and
+ * forget: this is observability for an admin endpoint, and failing to record it
+ * must never interrupt the backfill itself.
+ *
+ * Stores the object, not `JSON.stringify` of it. unstorage runs `destr` over
+ * whatever a driver returns, so a stored JSON *string* reads back as an object
+ * — round-tripping it through `JSON.parse` then throws, and the persisted
+ * progress is silently discarded. Same idiom as `enqueuePdsWrite`.
+ */
+function persistProgress(kv: Storage | undefined) {
+  if (!kv) return;
+  // A snapshot, not the mutable module-level object: the backfill keeps
+  // mutating it while this write is in flight, and handing a driver a live
+  // reference makes what actually lands depend on when it serialises.
+  void kv.setItem(BACKFILL_KV_KEY, { ...backfillProgress }).catch(() => {});
+}
+
+/**
+ * Progress of the catalog backfill. Reads the in-memory value while a run is
+ * live in *this* process, and otherwise falls back to the KV — which is what
+ * makes the answer meaningful after a restart, and across the other cluster
+ * workers that never ran the backfill.
+ *
+ * A stored "running" status necessarily means the process died mid-run (a live
+ * run would have answered from memory), so it is reported as `interrupted`
+ * rather than left looking active forever.
+ */
+export async function getBackfillProgress(kv?: Storage): Promise<BackfillProgress> {
+  if (backfillProgress.status !== "idle") return { ...backfillProgress };
+  if (!kv) return { ...backfillProgress };
+  const stored = await kv.getItem<BackfillProgress>(BACKFILL_KV_KEY);
+  if (!stored || typeof stored !== "object" || typeof stored.status !== "string") {
+    return { ...backfillProgress };
+  }
+  const parsed = { ...stored };
+  if (parsed.status === "running") {
+    parsed.status = "interrupted";
+    parsed.completedAt = parsed.lastBatchAt;
+    parsed.error = "Process restarted while backfill was running";
+  }
+  return parsed;
 }
 
 /**
@@ -306,6 +351,7 @@ export async function backfillCatalogBooks(
     lastBatchAt: null,
     error: null,
   };
+  persistProgress(ctx.kv);
 
   try {
     while (true) {
@@ -345,18 +391,21 @@ export async function backfillCatalogBooks(
       backfillProgress.written = written;
       backfillProgress.batches = batches;
       backfillProgress.lastBatchAt = new Date().toISOString();
+      persistProgress(ctx.kv);
 
       await new Promise((r) => setTimeout(r, BATCH_DELAY_MS));
     }
 
     backfillProgress.status = "completed";
     backfillProgress.completedAt = new Date().toISOString();
+    persistProgress(ctx.kv);
     wideEvent["outcome"] = "success";
     return { written, batches };
   } catch (err) {
     backfillProgress.status = "failed";
     backfillProgress.completedAt = new Date().toISOString();
     backfillProgress.error = err instanceof Error ? err.message : String(err);
+    persistProgress(ctx.kv);
     wideEvent["outcome"] = "error";
     wideEvent["error"] =
       err instanceof Error ? { message: err.message, type: err.name } : String(err);
diff --git a/src/utils/filenameMatching.test.ts b/src/utils/filenameMatching.test.ts
new file mode 100644
index 0000000..1c801c6
--- /dev/null
+++ b/src/utils/filenameMatching.test.ts
@@ -0,0 +1,176 @@
+import { describe, it, expect } from "bun:test";
+
+import {
+  authorsMatch,
+  filenameBasename,
+  filenameBookCandidates,
+  filenameKey,
+  koreaderFilenameHash,
+  normalizeAuthor,
+  normalizeTitle,
+  titlesEquivalent,
+} from "./filenameMatching";
+
+describe("koreaderFilenameHash", () => {
+  it("is md5 of the basename, matching KOSync's FILENAME checksum method", () => {
+    // KOReader: `md5(file_name)` where file_name is util.splitFilePathName's
+    // second return — the basename, extension included. This is the id such a
+    // client sends as `document`, so the value has to be byte-exact.
+    const expected = new Bun.CryptoHasher("md5").update("Dune.epub", "utf8").digest("hex");
+    expect(koreaderFilenameHash("Dune.epub")).toBe(expected);
+    expect(koreaderFilenameHash("/mnt/onboard/books/Dune.epub")).toBe(expected);
+    expect(koreaderFilenameHash("D:\\books\\Dune.epub")).toBe(expected);
+  });
+
+  it("returns null rather than hashing nothing", () => {
+    expect(koreaderFilenameHash(null)).toBeNull();
+    expect(koreaderFilenameHash("")).toBeNull();
+    expect(koreaderFilenameHash("   ")).toBeNull();
+  });
+});
+
+describe("filenameBasename", () => {
+  it("handles both separators", () => {
+    expect(filenameBasename("/a/b/c.epub")).toBe("c.epub");
+    expect(filenameBasename("a\\b\\c.epub")).toBe("c.epub");
+    expect(filenameBasename("c.epub")).toBe("c.epub");
+  });
+});
+
+describe("filenameKey", () => {
+  it("survives the format conversion that broke the content hash", () => {
+    // The whole reason users switch off binary checksums: calibre re-encodes
+    // the file, so the bytes (and the extension) differ but the book does not.
+    expect(filenameKey("Dune - Frank Herbert.epub")).toBe(filenameKey("dune_-_frank_herbert.azw3"));
+  });
+
+  it("ignores release noise and copy markers", () => {
+    expect(filenameKey("Dune (z-lib.org) [Retail].epub")).toBe("dune");
+    expect(filenameKey("Dune (1).epub")).toBe("dune");
+  });
+
+  it("keeps a dot-number that is part of the title", () => {
+    // A generic `\.\w+$` strip would turn this into "foundation vol".
+    expect(filenameKey("Foundation Vol.2.epub")).toBe("foundation vol 2");
+  });
+
+  it("folds diacritics so the same book from two sources agrees", () => {
+    expect(filenameKey("Les Misérables.epub")).toBe(filenameKey("Les Miserables.mobi"));
+  });
+
+  it("returns null when nothing indexable survives", () => {
+    // Must not be "", or every metadata-less document would match every other.
+    expect(filenameKey(null)).toBeNull();
+    expect(filenameKey("---.epub")).toBeNull();
+  });
+});
+
+describe("filenameBookCandidates", () => {
+  const pairs = (filename: string) =>
+    filenameBookCandidates(filename).map((c) => [c.title, c.authors]);
+
+  it("emits both orderings of an A - B split", () => {
+    // Nothing in the string says which convention this is, and the caller
+    // resolves the ambiguity against the catalogue.
+    expect(pairs("Ursula K. Le Guin - The Dispossessed.epub")).toContainEqual([
+      "The Dispossessed",
+      "Ursula K. Le Guin",
+    ]);
+    expect(pairs("The Dispossessed - Ursula K. Le Guin.epub")).toContainEqual([
+      "The Dispossessed",
+      "Ursula K. Le Guin",
+    ]);
+  });
+
+  it("reads a trailing parenthetical as the author", () => {
+    expect(pairs("The Dispossessed (Ursula K. Le Guin).epub")).toContainEqual([
+      "The Dispossessed",
+      "Ursula K. Le Guin",
+    ]);
+  });
+
+  it("drops a leading series index", () => {
+    expect(pairs("01 - The Fellowship of the Ring - J.R.R. Tolkien.epub")).toContainEqual([
+      "The Fellowship of the Ring",
+      "J.R.R. Tolkien",
+    ]);
+  });
+
+  it("still offers a title for a bare filename", () => {
+    expect(pairs("The Dispossessed.epub")).toEqual([["The Dispossessed", null]]);
+  });
+
+  it("reads underscores as spaces", () => {
+    expect(pairs("Frank_Herbert_-_Dune.epub")).toContainEqual(["Dune", "Frank Herbert"]);
+  });
+
+  it("declines a two-character title, which is an index or a stray token", () => {
+    expect(filenameBookCandidates("a.epub")).toEqual([]);
+    expect(filenameBookCandidates("")).toEqual([]);
+    expect(filenameBookCandidates(null)).toEqual([]);
+  });
+});
+
+describe("normalizeTitle", () => {
+  it("drops a trailing series or edition tail", () => {
+    expect(normalizeTitle("Dune (Dune Chronicles #1)")).toBe("dune");
+    expect(normalizeTitle("Emma [Illustrated]")).toBe("emma");
+  });
+
+  it("folds case, punctuation and diacritics", () => {
+    expect(normalizeTitle("The Hitchhiker's Guide")).toBe("the hitchhiker s guide");
+    expect(normalizeTitle("Les Misérables")).toBe("les miserables");
+  });
+});
+
+describe("titlesEquivalent", () => {
+  it("ignores punctuation, stop words and word order", () => {
+    expect(
+      titlesEquivalent("Hitchhikers Guide to the Galaxy", "The Hitchhiker's Guide to the Galaxy"),
+    ).toBe(true);
+    expect(titlesEquivalent("Hobbit", "The Hobbit")).toBe(true);
+  });
+
+  it("rejects a title that merely contains the other", () => {
+    // The reason the word gate runs both ways: this is a real, different book
+    // by the same author, so no downstream check would catch it.
+    expect(titlesEquivalent("Dune", "Dune Messiah")).toBe(false);
+    expect(titlesEquivalent("Children of Time", "Children of Ruin")).toBe(false);
+  });
+
+  it("does not call two unmatched non-Latin titles equivalent", () => {
+    // Both sides normalize to no ASCII content words; that is absence of
+    // evidence, not agreement.
+    expect(titlesEquivalent("戦争と平和", "白鯨")).toBe(false);
+    expect(titlesEquivalent("戦争と平和", "戦争と平和")).toBe(true);
+  });
+});
+
+describe("normalizeAuthor", () => {
+  it("un-inverts a Last, First name", () => {
+    expect(normalizeAuthor("Le Guin, Ursula K.")).toBe("ursula k le guin");
+  });
+});
+
+describe("authorsMatch", () => {
+  it("matches across punctuation and inversion", () => {
+    expect(authorsMatch("J.R.R. Tolkien", "J R R Tolkien")).toBe(true);
+    expect(authorsMatch("Tolkien, J.R.R.", "J.R.R. Tolkien")).toBe(true);
+  });
+
+  it("matches initials against the spelled-out name", () => {
+    expect(authorsMatch("J.R.R. Tolkien", "John Ronald Reuel Tolkien")).toBe(true);
+  });
+
+  it("does not accept a shared surname alone", () => {
+    // The reason the first-initial check exists: a surname on its own would
+    // link a book to the wrong member of a writing family.
+    expect(authorsMatch("Jane Tolkien", "John Tolkien")).toBe(false);
+    expect(authorsMatch("Tolkien", "John Tolkien")).toBe(false);
+  });
+
+  it("rejects unrelated names", () => {
+    expect(authorsMatch("Frank Herbert", "Ursula K. Le Guin")).toBe(false);
+    expect(authorsMatch("", "Frank Herbert")).toBe(false);
+  });
+});
diff --git a/src/utils/filenameMatching.ts b/src/utils/filenameMatching.ts
new file mode 100644
index 0000000..aa9dbc4
--- /dev/null
+++ b/src/utils/filenameMatching.ts
@@ -0,0 +1,329 @@
+/**
+ * Filename-derived identity for e-reader documents.
+ *
+ * KOSync clients identify a document one of two ways (KOReader's
+ * `CHECKSUM_METHOD`, plugins/kosync.koplugin/main.lua):
+ *
+ * - `BINARY` (0, the default) — `md5` over 1 KiB samples of the file itself.
+ *   That is `koreaderPartialMD5` in `bookMetadata/hash.ts`, and it is what
+ *   `personal_book.contentHash` stores, which is why an uploaded file lines up
+ *   with its synced progress by hash alone.
+ * - `FILENAME` (1) — plain `md5(basename)`, nothing to do with the bytes.
+ *   Users switch to it precisely *because* their files are not byte-identical
+ *   across devices (calibre conversion, image downscaling), so for those users
+ *   the content hash can never match. `koreaderFilenameHash` reproduces it.
+ *
+ * Separately, KOReader's `send_metadata` option (and CrossPoint, which sends it
+ * unconditionally) puts the human-readable filename in the progress payload. A
+ * filename is often the *only* usable signal we get: plenty of documents arrive
+ * with no title/author metadata at all, and "Ursula K. Le Guin - The
+ * Dispossessed.epub" identifies a book perfectly well.
+ *
+ * Three derived values, used in that order of confidence:
+ *
+ * | value                   | matches                                    | fuzzy? |
+ * | ----------------------- | ------------------------------------------ | ------ |
+ * | `koreaderFilenameHash`  | a FILENAME-mode `sync_document.documentHash` | no    |
+ * | `filenameKey`           | another file's normalized name              | a bit |
+ * | `filenameBookCandidates`| a `hive_book` title/author                  | yes   |
+ *
+ * **`filenameKey` and `koreaderFilenameHash` are persisted**, in
+ * `personal_book.filenameHash`/`.filenameKey` and `sync_document.filenameKey`
+ * (migration 022 backfilled them by calling these functions). They are a stored
+ * index of a pure function, so changing either one silently splits the data:
+ * rows written before the change keep the old normalization while new writes
+ * use the new one, and `SAME_BOOK_FILE` then compares values that were never
+ * computed the same way.
+ *
+ * Any change to their output therefore needs a follow-up migration that
+ * recomputes both columns for every row. Freezing a copy inside migration 022
+ * would *not* fix this and would make it worse — a fresh install would then
+ * backfill old-normalized values into a database the app writes new-normalized
+ * values to.
+ */
+
+import { contentWords } from "./bookMatching";
+
+/**
+ * Extensions stripped before comparing two filenames. Deliberately a closed
+ * list rather than a `\.\w+$` regex: a generic strip mangles titles that end in
+ * a dot-number ("Foundation Vol.2", "Hitchhiker's 1.5"), and the whole point of
+ * the key is that two names for the same book collapse onto it.
+ *
+ * Conversion changes the extension — the .epub on the desktop is the .azw3 on
+ * the Kindle — so stripping it is what makes the key survive a calibre round
+ * trip at all.
+ */
+const EBOOK_EXTENSIONS = new Set([
+  "epub",
+  "kepub",
+  "mobi",
+  "azw",
+  "azw3",
+  "azw4",
+  "prc",
+  "pdb",
+  "fb2",
+  "cbz",
+  "cbr",
+  "cb7",
+  "pdf",
+  "djvu",
+  "djv",
+  "txt",
+  "rtf",
+  "doc",
+  "docx",
+  "html",
+  "htm",
+  "xhtml",
+  "chm",
+  "lit",
+  "opf",
+  "zip",
+  "gz",
+]);
+
+/** Parenthesised groups that are release noise, not part of the title. */
+const JUNK_PAREN =
+  /^(z-?lib(rary)?(\.org)?|libgen|anna'?s? archive|retail|repack|v\d+(\.\d+)*|\d+|epub|mobi|azw3?|pdf|scan|ocr|copy|dup(licate)?|final|fixed)$/i;
+
+const SEPARATORS = /\s+[-–—_]\s+/;
+
+export type FilenameCandidate = {
+  title: string;
+  /** null when the filename yielded no author signal at all. */
+  authors: string | null;
+};
+
+/** Last path segment, tolerating both separators (KOReader runs on Windows too). */
+export function filenameBasename(path: string): string {
+  const cut = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
+  return cut === -1 ? path : path.slice(cut + 1);
+}
+
+/**
+ * `md5` of the basename — byte-for-byte what a KOSync client in FILENAME
+ * checksum mode sends as its `document` id. Matching this against
+ * `sync_document.documentHash` is exact, not fuzzy: it is the same protocol
+ * identifier, just computed on our side.
+ */
+export function koreaderFilenameHash(filename: string | null | undefined): string | null {
+  if (!filename) return null;
+  const name = filenameBasename(filename).trim();
+  if (!name) return null;
+  return new Bun.CryptoHasher("md5").update(name, "utf8").digest("hex");
+}
+
+/** Strip a known ebook extension (including the `.fb2.zip` double form). */
+function stripExtension(name: string): string {
+  let out = name;
+  for (let i = 0; i < 2; i++) {
+    const dot = out.lastIndexOf(".");
+    if (dot <= 0) break;
+    const ext = out.slice(dot + 1).toLowerCase();
+    if (!EBOOK_EXTENSIONS.has(ext)) break;
+    out = out.slice(0, dot);
+  }
+  return out;
+}
+
+/**
+ * Everything both the key and the candidate parser want: basename, no
+ * extension, no `[...]` groups, no release-noise `(...)` groups, underscores
+ * read as spaces, whitespace collapsed.
+ */
+function cleanFilename(filename: string): string {
+  let name = stripExtension(filenameBasename(filename));
+  name = name.replace(/\[[^\]]*\]/g, " ");
+  name = name.replace(/\(([^)]*)\)/g, (whole, inner: string) =>
+    JUNK_PAREN.test(inner.trim()) ? " " : whole,
+  );
+  name = name.replace(/_/g, " ");
+  return name.replace(/\s+/g, " ").trim();
+}
+
+/**
+ * Comparison key for "are these two files the same book". Folds case,
+ * punctuation and the extension away, so `Dune - Frank Herbert.epub` and
+ * `dune_-_frank_herbert.azw3` land on `dune frank herbert`.
+ *
+ * Returns null when nothing indexable survives, which callers must treat as
+ * "no key" rather than as a value to match on — otherwise every metadata-less
+ * document would match every other one.
+ */
+export function filenameKey(filename: string | null | undefined): string | null {
+  if (!filename) return null;
+  const key = cleanFilename(filename)
+    .normalize("NFKD")
+    .replace(/\p{M}+/gu, "")
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}]+/gu, " ")
+    .trim();
+  return key || null;
+}
+
+/** Diacritics folded away, so the ASCII-only helpers in `bookMatching` behave. */
+function foldDiacritics(input: string): string {
+  return input.normalize("NFKD").replace(/\p{M}+/gu, "");
+}
+
+/** Diacritics folded, series/edition tail dropped, punctuation still intact. */
+function titleBody(title: string): string {
+  // Tails: "Dune (Dune Chronicles #1)", "Emma [Illustrated]".
+  return foldDiacritics(title)
+    .toLowerCase()
+    .replace(/[([][^)\]]*[)\]]\s*$/g, "")
+    .trim();
+}
+
+/** Normalized form used to compare a filename-derived title to a `hive_book` one. */
+export function normalizeTitle(title: string): string {
+  return titleBody(title)
+    .replace(/[^\p{L}\p{N}]+/gu, " ")
+    .trim();
+}
+
+/**
+ * Whether two titles name the same book.
+ *
+ * Equal normalized strings, or the same set of significant words in any order
+ * — which buys tolerance for punctuation ("Hitchhiker's" / "Hitchhikers"),
+ * stop words ("The Hobbit" / "Hobbit") and ordering, all of which vary between
+ * a filename and a Goodreads title without changing the book.
+ *
+ * The word gate runs in **both** directions, unlike `contentWordsMatch`'s
+ * one-way containment. One-way is right for a CSV import, where the row has
+ * other identifiers to fall back on; here it would accept "Dune" against "Dune
+ * Messiah" — a real, different book, by the same author, so the author check
+ * downstream would wave it through and write the user's progress onto it.
+ */
+export function titlesEquivalent(a: string, b: string): boolean {
+  const na = normalizeTitle(a);
+  const nb = normalizeTitle(b);
+  if (!na || !nb) return false;
+  if (na === nb) return true;
+
+  // From the punctuated body, not from `na`/`nb`: `normalizeTitle` turns
+  // punctuation into a space, which splits "hitchhiker's" into two words, while
+  // `contentWords` deletes it and yields the one word "hitchhikers".
+  const wa = contentWords(titleBody(a));
+  const wb = contentWords(titleBody(b));
+  // Empty on both sides means neither title survived ASCII normalization (a
+  // CJK or Cyrillic title, or one made entirely of stop words). That is not
+  // agreement — fall back to the string equality already tested above.
+  if (wa.length === 0 || wb.length === 0) return false;
+  if (wa.length !== wb.length) return false;
+  const sortedA = [...wa].sort();
+  const sortedB = [...wb].sort();
+  return sortedA.every((w, i) => w === sortedB[i]);
+}
+
+/** Normalized form of a single personal name, with `Last, First` un-inverted. */
+export function normalizeAuthor(author: string): string {
+  let name = author.trim();
+  const comma = name.indexOf(",");
+  if (comma > 0 && !name.slice(comma + 1).includes(",")) {
+    name = `${name.slice(comma + 1).trim()} ${name.slice(0, comma).trim()}`;
+  }
+  return name
+    .normalize("NFKD")
+    .replace(/\p{M}+/gu, "")
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}]+/gu, " ")
+    .trim();
+}
+
+/**
+ * Whether two author strings plausibly name the same person.
+ *
+ * Deliberately not a similarity score: each rule below is one concrete way the
+ * same author is written differently across a filename and Goodreads, and
+ * anything else is a miss. Initials are the interesting case — "J R R Tolkien"
+ * and "John Ronald Reuel Tolkien" agree on a surname and a first initial only.
+ * Comparing initials is therefore allowed, but only when one side actually *is*
+ * an initial: two spelled-out first names must be equal, or "Jane Tolkien" and
+ * "John Tolkien" would be the same person.
+ */
+export function authorsMatch(a: string, b: string): boolean {
+  const x = normalizeAuthor(a);
+  const y = normalizeAuthor(b);
+  if (!x || !y) return false;
+  if (x === y) return true;
+
+  const xs = x.split(" ");
+  const ys = y.split(" ");
+  const xSurname = xs[xs.length - 1];
+  const ySurname = ys[ys.length - 1];
+  if (!xSurname || !ySurname || xSurname !== ySurname) return false;
+  // Single-token names ("Homer", "Plato") are already covered by equality; a
+  // surname-only match against a full name is too weak to accept.
+  if (xs.length === 1 || ys.length === 1) return false;
+
+  const xFirst = xs[0]!;
+  const yFirst = ys[0]!;
+  if (xFirst === yFirst) return true;
+  if (xFirst.length > 1 && yFirst.length > 1) return false;
+  return xFirst[0] === yFirst[0];
+}
+
+function pushCandidate(out: FilenameCandidate[], title: string, authors: string | null): void {
+  const t = title.trim().replace(/^[-–—\s]+|[-–—\s]+$/g, "");
+  const a = authors?.trim().replace(/^[-–—\s]+|[-–—\s]+$/g, "") || null;
+  // A "title" of one or two characters is a series index or a stray token, not
+  // something worth hashing against the whole catalogue.
+  if (t.length < 3) return;
+  if (a !== null && a.length < 2) return;
+  if (out.some((c) => c.title === t && c.authors === a)) return;
+  out.push({ title: t, authors: a });
+}
+
+/**
+ * Title/author guesses for a filename, most confident first.
+ *
+ * Both orderings of an `A - B` split are emitted, because both conventions are
+ * in the wild (calibre writes `Title - Author`, most torrents write `Author -
+ * Title`) and nothing in the string says which one this is. That is safe to do
+ * blindly *because* the caller resolves them against the catalogue: `hive_book.id`
+ * is a hash of title+author, so a wrong ordering simply hashes to an id that
+ * does not exist. Guessing costs a lookup, never a wrong link.
+ */
+export function filenameBookCandidates(filename: string | null | undefined): FilenameCandidate[] {
+  if (!filename) return [];
+  const cleaned = cleanFilename(filename);
+  if (!cleaned) return [];
+
+  const out: FilenameCandidate[] = [];
+
+  // "The Dispossessed (Ursula K. Le Guin)" — a trailing parenthetical that
+  // survived the junk filter is nearly always the author.
+  const trailingParen = cleaned.match(/^(.*?)\s*\(([^)]+)\)\s*$/);
+  const body = trailingParen ? trailingParen[1]!.trim() : cleaned;
+  if (trailingParen) pushCandidate(out, body, trailingParen[2]!);
+
+  // Leading series index: "01 - The Fellowship of the Ring - J.R.R. Tolkien".
+  let parts = body
+    .split(SEPARATORS)
+    .map((p) => p.trim())
+    .filter(Boolean);
+  if (parts.length > 1 && /^\d{1,3}\.?$/.test(parts[0]!)) parts = parts.slice(1);
+
+  if (parts.length === 2) {
+    pushCandidate(out, parts[0]!, parts[1]!);
+    pushCandidate(out, parts[1]!, parts[0]!);
+  } else if (parts.length > 2) {
+    const head = parts[0]!;
+    const tail = parts[parts.length - 1]!;
+    const middle = parts.slice(1).join(" - ");
+    const front = parts.slice(0, -1).join(" - ");
+    // Either end can be the author; the rest is the title.
+    pushCandidate(out, middle, head);
+    pushCandidate(out, front, tail);
+  }
+
+  // Whole name as a title, with whatever author signal we found. Last resort,
+  // but it is the only candidate for a bare "The Dispossessed.epub".
+  pushCandidate(out, parts.join(" - "), null);
+
+  return out;
+}
diff --git a/src/utils/imageProxy.ts b/src/utils/imageProxy.ts
index 3c58e6e..92a5ff2 100644
--- a/src/utils/imageProxy.ts
+++ b/src/utils/imageProxy.ts
@@ -12,9 +12,10 @@
 import { env } from "../env";
 
 /** Remote hosts we are willing to proxy. */
-// images.isbndb.com: the ISBNdb scraper was deleted, but rows written
-// while it was active still carry those cover URLs — without it we reject our
-// own data as a forbidden source.
+// images.isbndb.com: `src/scrapers/isbndb.ts` still exists but is no longer
+// wired into `findBookDetails`, and rows written while it was active still
+// carry those cover URLs — without it we reject our own data as a forbidden
+// source.
 export const ALLOWED_IMAGE_HOSTS = new Set([
   "i.gr-assets.com",
   "cdn.bsky.app",
diff --git a/src/utils/personalLibrary.ts b/src/utils/personalLibrary.ts
index d447c75..2773443 100644
--- a/src/utils/personalLibrary.ts
+++ b/src/utils/personalLibrary.ts
@@ -8,16 +8,30 @@ import type { Database } from "../db";
 export const OPDS_PAGE_SIZE = 24;
 
 /**
- * Largest accepted ebook upload. Every upload path materialises the whole file
- * as a `Uint8Array` (the KOReader partial MD5 and the format parsers both need
- * random access), so this is a direct per-request ceiling on native memory —
- * enforce it against the *declared* size before reading the body.
+ * Largest accepted ebook upload. The body itself streams to disk, but the
+ * format parsers need the whole file in one contiguous buffer (fflate reads a
+ * ZIP's central directory from the end), so this remains the per-request
+ * ceiling on native memory for the parse step. Enforce it against the
+ * *declared* size first, then again while streaming.
  */
 export const MAX_PERSONAL_BOOK_BYTES = 100 * 1024 * 1024;
 
-/** Root directory for all personal library files, adjacent to the DB. */
+/**
+ * Root directory for all personal library files. `LIBRARY_DIR` wins when set,
+ * so the library can live on a different volume from the DB; otherwise it sits
+ * adjacent to the DB as it always has.
+ */
 export function getLibraryDir(): string {
-  return path.join(path.dirname(env.DB_PATH), "library");
+  return env.LIBRARY_DIR || path.join(path.dirname(env.DB_PATH), "library");
+}
+
+/**
+ * Scratch directory for in-flight uploads. Deliberately under the library root
+ * so the finished file can be `rename`d into place rather than copied — that
+ * only holds within one filesystem.
+ */
+export function getLibraryTmpDir(): string {
+  return path.join(getLibraryDir(), ".tmp");
 }
 
 /** Directory for a specific book: `{libraryDir}/{did}/{contentHash}/` */
@@ -50,6 +64,29 @@ export async function removeUserDir(did: string): Promise<void> {
   await rm(path.join(getLibraryDir(), did), { recursive: true, force: true });
 }
 
+/** Total bytes one user may store across their personal library. */
+export function getStorageQuota(): number {
+  return env.PERSONAL_LIBRARY_QUOTA_BYTES;
+}
+
+/**
+ * Bytes this user currently stores. Derived with a `SUM`, never a maintained
+ * counter: the quota itself bounds the row count (2 GB over a ~3 MB median
+ * epub is ~700 rows), `idx_personal_book_user_size` makes it an index-only
+ * scan, and a derived total cannot drift. A counter would need a backfill,
+ * decrements in both delete paths, and a repair job — and `removeBookDir` is
+ * best-effort, so a failed `rm` after a row delete would leave the counter
+ * under-reporting forever while the disk quietly filled.
+ */
+export async function getStorageUsage(db: Database, userDid: string): Promise<number> {
+  const row = await db
+    .selectFrom("personal_book")
+    .select((eb) => eb.fn.coalesce(eb.fn.sum<number>("sizeBytes"), eb.lit(0)).as("used"))
+    .where("userDid", "=", userDid)
+    .executeTakeFirst();
+  return Number(row?.used ?? 0);
+}
+
 export type PersonalBookDownload =
   | { notModified: true; headers: Record<string, string> }
   | { notModified: false; stream: ReadableStream; headers: Record<string, string> };
@@ -59,7 +96,7 @@ export type PersonalBookDownload =
  * and `*` forms, and tolerates the `W/` prefix a client may echo back — the
  * validator is a content hash, so a weak match is still the same bytes.
  */
-function etagMatches(ifNoneMatch: string | null | undefined, etag: string): boolean {
+export function etagMatches(ifNoneMatch: string | null | undefined, etag: string): boolean {
   if (!ifNoneMatch) return false;
   const normalize = (raw: string) => raw.trim().replace(/^W\//, "");
   return ifNoneMatch
diff --git a/src/utils/syncMatching.test.ts b/src/utils/syncMatching.test.ts
new file mode 100644
index 0000000..c17602e
--- /dev/null
+++ b/src/utils/syncMatching.test.ts
@@ -0,0 +1,351 @@
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { Database as DatabaseSync } from "bun:sqlite";
+import { Kysely, SqliteDialect } from "kysely";
+
+import { wrapBunSqliteForKysely } from "../bun-sqlite-kysely";
+import { migrateToLatest, type Database, type DatabaseSchema } from "../db";
+import { getHiveId } from "../scrapers/getHiveId";
+import type { HiveId } from "../types";
+import { filenameKey, koreaderFilenameHash } from "./filenameMatching";
+import { matchSyncDocument, matchSyncDocumentForUser } from "./syncMatching";
+
+const DID = "did:plc:testuser";
+
+/** Hand-built like the other DB suites; `createDb` reads a mocked `env`. */
+async function createTestDb(): Promise<Database> {
+  const sqlite = new DatabaseSync(":memory:");
+  sqlite.exec("PRAGMA journal_mode = WAL");
+  const db = new Kysely<DatabaseSchema>({
+    dialect: new SqliteDialect({ database: wrapBunSqliteForKysely(sqlite) }),
+  });
+  await migrateToLatest(db, sqlite);
+  return db;
+}
+
+describe("matchSyncDocument", () => {
+  let db: Database;
+
+  const insert = async (title: string, authors: string, ratingsCount = 0): Promise<HiveId> => {
+    const id = getHiveId({ title, authors });
+    await db
+      .insertInto("hive_book")
+      .values({
+        id: id as never,
+        title,
+        rawTitle: title,
+        authors,
+        ratingsCount,
+        source: "goodreads",
+        thumbnail: "",
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+      } as never)
+      .execute();
+    return id;
+  };
+
+  beforeEach(async () => {
+    db = await createTestDb();
+  });
+
+  afterEach(async () => {
+    await db.destroy();
+  });
+
+  describe("tier 1 — exact hash of the client's metadata", () => {
+    it("matches title + authors", async () => {
+      const id = await insert("The Dispossessed", "Ursula K. Le Guin");
+      expect(
+        await matchSyncDocument(db, { title: "The Dispossessed", authors: "Ursula K. Le Guin" }),
+      ).toBe(id);
+    });
+
+    it("returns null when nothing identifies the document", async () => {
+      await insert("The Dispossessed", "Ursula K. Le Guin");
+      expect(await matchSyncDocument(db, {})).toBeNull();
+    });
+
+    it("splits newline-separated authors, which is how KOReader sends them", async () => {
+      // `metadata.authors` is `doc_props.authors`, one of the props KOReader
+      // edits with `allow_newline = true`. Treated as one name it matches
+      // nobody.
+      const id = await insert("Good Omens", "Terry Pratchett", 900);
+      expect(
+        await matchSyncDocument(db, {
+          title: "Good Omens",
+          authors: "Neil Gaiman\nTerry Pratchett",
+          filename: "Good Omens.epub",
+        }),
+      ).toBe(id);
+    });
+  });
+
+  describe("tier 2 — exact hash of filename-derived pairs", () => {
+    it("matches a document that carries only a filename", async () => {
+      // The case this whole path exists for: KOSync metadata is optional, and
+      // a client that sends just the filename used to be unmatchable.
+      const id = await insert("The Dispossessed", "Ursula K. Le Guin");
+      expect(
+        await matchSyncDocument(db, {
+          filename: "Ursula K. Le Guin - The Dispossessed.epub",
+        }),
+      ).toBe(id);
+    });
+
+    it("matches regardless of which side of the dash the author is on", async () => {
+      const id = await insert("The Dispossessed", "Ursula K. Le Guin");
+      expect(
+        await matchSyncDocument(db, { filename: "The Dispossessed - Ursula K. Le Guin.epub" }),
+      ).toBe(id);
+    });
+
+    it("crosses a client title with a filename author", async () => {
+      const id = await insert("Dune", "Frank Herbert");
+      expect(
+        await matchSyncDocument(db, { title: "Dune", filename: "Frank Herbert - Dune.epub" }),
+      ).toBe(id);
+    });
+
+    it("parses the client's title, which KOReader derives from the filename", async () => {
+      // `display_title` is `props.title or splitFileNameType(filepath)`, so a
+      // document with no embedded title sends the filename stem as its title.
+      const id = await insert("The Dispossessed", "Ursula K. Le Guin");
+      expect(await matchSyncDocument(db, { title: "Ursula K. Le Guin - The Dispossessed" })).toBe(
+        id,
+      );
+    });
+
+    it("prefers the client's own metadata over a filename guess", async () => {
+      const real = await insert("Dune", "Frank Herbert");
+      await insert("Dune", "Someone Else");
+      expect(
+        await matchSyncDocument(db, {
+          title: "Dune",
+          authors: "Frank Herbert",
+          filename: "Someone Else - Dune.epub",
+        }),
+      ).toBe(real);
+    });
+  });
+
+  describe("tier 3 — fuzzy, filename only", () => {
+    it("matches a title the id hash could not, when the author agrees", async () => {
+      // The filename title is exact but the author is written differently, so
+      // the title+author hash misses entirely.
+      const id = await insert("The Dispossessed", "Ursula K. Le Guin", 100);
+      expect(
+        await matchSyncDocument(db, { filename: "Le Guin, Ursula - The Dispossessed.epub" }),
+      ).toBe(id);
+    });
+
+    it("accepts an unambiguous title with no author anywhere", async () => {
+      const id = await insert("The Dispossessed", "Ursula K. Le Guin", 100);
+      expect(await matchSyncDocument(db, { filename: "The Dispossessed.epub" })).toBe(id);
+    });
+
+    it("refuses to pick between books that share a title", async () => {
+      // Ranking is by popularity, which says nothing about which one this is.
+      await insert("Dune", "Frank Herbert", 900);
+      await insert("Dune", "A Different Author", 5);
+      expect(await matchSyncDocument(db, { filename: "Dune.epub" })).toBeNull();
+    });
+
+    it("refuses a title match whose author disagrees", async () => {
+      await insert("Dune", "Frank Herbert", 900);
+      expect(await matchSyncDocument(db, { filename: "Ursula K. Le Guin - Dune.epub" })).toBeNull();
+    });
+
+    it("does not match a book that merely ranks first for the filename", async () => {
+      await insert("The Girl with the Dragon Tattoo", "Stieg Larsson", 100);
+      expect(await matchSyncDocument(db, { filename: "The Girl.epub" })).toBeNull();
+    });
+
+    it("tolerates punctuation and stop-word differences in the title", async () => {
+      const id = await insert("The Hitchhiker's Guide to the Galaxy", "Douglas Adams", 900);
+      expect(
+        await matchSyncDocument(db, {
+          filename: "Douglas Adams - Hitchhikers Guide to the Galaxy.epub",
+        }),
+      ).toBe(id);
+    });
+
+    it("does not accept a sequel that merely contains the title", async () => {
+      // "Dune" is a content-word subset of "Dune Messiah" and the author agrees,
+      // so one-directional containment would link the user's progress to the
+      // wrong book. A different book by the same author is the easiest way to
+      // get this wrong and the hardest for the user to notice.
+      await insert("Dune Messiah", "Frank Herbert", 900);
+      expect(await matchSyncDocument(db, { filename: "Frank Herbert - Dune.epub" })).toBeNull();
+    });
+
+    it("ignores a series tail on the catalogue title", async () => {
+      const id = await insert("Dune (Dune Chronicles #1)", "Frank Herbert", 900);
+      expect(await matchSyncDocument(db, { filename: "Frank Herbert - Dune.epub" })).toBe(id);
+    });
+  });
+});
+
+describe("matchSyncDocumentForUser", () => {
+  let db: Database;
+
+  const insert = async (title: string, authors: string, ratingsCount = 0): Promise<HiveId> => {
+    const id = getHiveId({ title, authors });
+    await db
+      .insertInto("hive_book")
+      .values({
+        id: id as never,
+        title,
+        rawTitle: title,
+        authors,
+        ratingsCount,
+        source: "goodreads",
+        thumbnail: "",
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+      } as never)
+      .execute();
+    return id;
+  };
+
+  const upload = async (opts: {
+    contentHash: string;
+    filename: string;
+    title: string;
+    authors?: string | null;
+    hiveId?: HiveId | null;
+  }) => {
+    const now = new Date().toISOString();
+    await db
+      .insertInto("personal_book")
+      .values({
+        userDid: DID,
+        contentHash: opts.contentHash,
+        hiveId: opts.hiveId ?? null,
+        filename: opts.filename,
+        filenameHash: koreaderFilenameHash(opts.filename),
+        filenameKey: filenameKey(opts.filename),
+        title: opts.title,
+        authors: opts.authors ?? null,
+        language: null,
+        format: "epub",
+        mime: "application/epub+zip",
+        filePath: "/tmp/x.epub",
+        coverPath: null,
+        coverMime: null,
+        sizeBytes: 1,
+        createdAt: now,
+        updatedAt: now,
+      })
+      .execute();
+  };
+
+  beforeEach(async () => {
+    db = await createTestDb();
+  });
+
+  afterEach(async () => {
+    await db.destroy();
+  });
+
+  it("matches a default-configured client, which sends only a content hash", async () => {
+    // KOReader defaults: checksum_method BINARY, send_metadata off. The whole
+    // request identifies the book as one partial-MD5 and nothing else, so
+    // matching the payload alone can never work — but that hash is the
+    // contentHash of a file whose metadata we parsed at upload time.
+    const id = await insert("The Dispossessed", "Ursula K. Le Guin");
+    await upload({
+      contentHash: "partial-md5",
+      filename: "book.epub",
+      title: "The Dispossessed",
+      authors: "Ursula K. Le Guin",
+    });
+
+    expect(await matchSyncDocument(db, { title: null, authors: null, filename: null })).toBeNull();
+    expect(await matchSyncDocumentForUser(db, DID, { documentHash: "partial-md5" })).toBe(id);
+  });
+
+  it("inherits a link the user already established on the file", async () => {
+    const id = await insert("Dune", "Frank Herbert");
+    await upload({
+      contentHash: "partial-md5",
+      filename: "book.epub",
+      title: "Something Unmatchable",
+      hiveId: id,
+    });
+
+    expect(await matchSyncDocumentForUser(db, DID, { documentHash: "partial-md5" })).toBe(id);
+  });
+
+  it("writes the resolved book back onto the file and marks it owned", async () => {
+    const id = await insert("The Dispossessed", "Ursula K. Le Guin");
+    await upload({
+      contentHash: "partial-md5",
+      filename: "book.epub",
+      title: "The Dispossessed",
+      authors: "Ursula K. Le Guin",
+    });
+    const now = new Date().toISOString();
+    await db
+      .insertInto("user_book")
+      .values({
+        uri: "at://x/1",
+        cid: "c",
+        userDid: DID,
+        createdAt: now,
+        indexedAt: now,
+        hiveId: id,
+        title: "The Dispossessed",
+        authors: "Ursula K. Le Guin",
+        owned: 0,
+      } as never)
+      .execute();
+
+    await matchSyncDocumentForUser(db, DID, { documentHash: "partial-md5" });
+
+    const file = await db.selectFrom("personal_book").select("hiveId").executeTakeFirstOrThrow();
+    expect(file.hiveId).toBe(id);
+    const book = await db.selectFrom("user_book").select("owned").executeTakeFirstOrThrow();
+    expect(book.owned).toBe(1);
+  });
+
+  it("splits comma-separated authors, which is how uploads store them", async () => {
+    // `parseBook` joins epub dc:creator values with ", ".
+    const id = await insert("Good Omens", "Terry Pratchett", 900);
+    await upload({
+      contentHash: "partial-md5",
+      filename: "Good Omens.epub",
+      title: "Good Omens",
+      authors: "Neil Gaiman, Terry Pratchett",
+    });
+
+    expect(await matchSyncDocumentForUser(db, DID, { documentHash: "partial-md5" })).toBe(id);
+  });
+
+  it("still un-inverts a single Last, First author", async () => {
+    // The same comma that separates two authors also inverts one name, so both
+    // readings are tried rather than guessed between.
+    const id = await insert("The Dispossessed", "Ursula K. Le Guin", 900);
+    await upload({
+      contentHash: "partial-md5",
+      filename: "x.epub",
+      title: "The Dispossessed",
+      authors: "Le Guin, Ursula K.",
+    });
+
+    expect(await matchSyncDocumentForUser(db, DID, { documentHash: "partial-md5" })).toBe(id);
+  });
+
+  it("does not reach another user's uploads", async () => {
+    await insert("The Dispossessed", "Ursula K. Le Guin");
+    await upload({
+      contentHash: "partial-md5",
+      filename: "book.epub",
+      title: "The Dispossessed",
+      authors: "Ursula K. Le Guin",
+    });
+
+    expect(
+      await matchSyncDocumentForUser(db, "did:plc:someoneelse", { documentHash: "partial-md5" }),
+    ).toBeNull();
+  });
+});
diff --git a/src/utils/syncMatching.ts b/src/utils/syncMatching.ts
index 7f6a582..c14b78b 100644
--- a/src/utils/syncMatching.ts
+++ b/src/utils/syncMatching.ts
@@ -1,6 +1,19 @@
+import { sql } from "kysely";
 import type { Database } from "../db";
 import type { HiveId } from "../types";
 import { getHiveId } from "../scrapers/getHiveId";
+import { parseAuthors } from "./authorMatching";
+import { ftsMatchQuery } from "./ftsQuery";
+import {
+  authorsMatch,
+  filenameBookCandidates,
+  filenameKey,
+  normalizeAuthor,
+  normalizeTitle,
+  titlesEquivalent,
+  type FilenameCandidate,
+} from "./filenameMatching";
+import { similarityScore } from "./bookMatching";
 
 /**
  * Sentinel written to `sync_document.hiveId` when the user asserts a synced
@@ -14,27 +27,364 @@ import { getHiveId } from "../scrapers/getHiveId";
  */
 export const NO_HIVE_MATCH = "bk_none" as HiveId;
 
+/**
+ * Cap on how much filename guessing one progress push is allowed to pay for.
+ * This runs on every push for a document that has not matched yet, so an
+ * unmatchable document re-pays it every few minutes, per device.
+ */
+const MAX_FTS_QUERIES = 4;
+const FTS_LIMIT = 50;
+
+/**
+ * "This synced document and this uploaded file are the same book."
+ *
+ * Three ways that can be true, and a KOSync client only ever gives us one of
+ * them, so all three have to be tried:
+ *
+ * 1. `contentHash = documentHash` — the client is in BINARY checksum mode and
+ *    the file we hold is byte-identical to the one on the device. The original
+ *    (and only) rule.
+ * 2. `filenameHash = documentHash` — the client is in FILENAME mode, so what it
+ *    calls a document id is md5 of the basename. Nothing about the bytes is
+ *    involved and rule 1 can never fire for these users.
+ * 3. `filenameKey = filenameKey` — neither hash lines up, but the client sent a
+ *    readable filename that normalizes to the same thing as ours. This is the
+ *    calibre-conversion case: same book, different bytes *and* a different
+ *    extension.
+ *
+ * Written as raw SQL because both directions of the relationship need it, as a
+ * correlated subquery rather than a join — a document can match more than one
+ * file and vice versa, and a join would fan those out into duplicate rows in
+ * the library grid and break its pagination.
+ *
+ * Both `filenameKey` columns are nullable and `NULL = NULL` is not true in SQL,
+ * so a document with no filename cannot match a file with no key.
+ */
+export const SAME_BOOK_FILE = sql<boolean>`(
+  personal_book.contentHash = sync_document.documentHash
+  OR personal_book.filenameHash = sync_document.documentHash
+  OR personal_book.filenameKey = sync_document.filenameKey
+)`;
+
+type FtsRow = { id: HiveId; title: string; authors: string | null; ratingsCount: number | null };
+
+/**
+ * Split an author *signal* into individual names. Three sources reach this and
+ * each separates authors differently:
+ *
+ * - KOReader's `metadata.authors` is **newline**-separated (`doc_props.authors`
+ *   is one of the three props its metadata editor opens with
+ *   `allow_newline = true`).
+ * - `personal_book.authors` is **comma**-separated (`parseBook` joins epub
+ *   `dc:creator` values with ", ").
+ * - `hive_book.authors` is tab-separated, but that side goes through
+ *   `parseAuthors`, not here.
+ *
+ * The comma is ambiguous — it also inverts a single name ("Le Guin, Ursula") —
+ * so rather than guess, the whole string is emitted *alongside* the split
+ * parts and both interpretations are tried. That is safe because signals are
+ * only ever used as corroborating evidence: one that matches nothing simply
+ * fails to confirm, it cannot select a book on its own.
+ */
+function splitAuthorSignal(value: string | null | undefined): string[] {
+  if (!value) return [];
+  const parts = value
+    .split(/[\r\n\t;&]|\band\b/i)
+    .map((a) => a.trim())
+    .filter(Boolean);
+  const withCommaSplits = parts.flatMap((part) =>
+    part.includes(",") ? [part, ...part.split(",").map((a) => a.trim())] : [part],
+  );
+  return dedupe(withCommaSplits.filter(Boolean));
+}
+
+function dedupe(values: string[]): string[] {
+  return [...new Set(values)];
+}
+
+/** Merge candidate lists, keeping the first (most confident) of each pair. */
+function dedupeCandidates(candidates: FilenameCandidate[]): FilenameCandidate[] {
+  const seen = new Set<string>();
+  return candidates.filter((c) => {
+    const key = `${c.title}\0${c.authors ?? ""}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+/**
+ * Resolve a synced e-reader document to a `hive_book`.
+ *
+ * Three tiers, strongest first. The rule that governs all of them is that a
+ * wrong link is worse than no link — it writes someone's reading progress onto
+ * a book they aren't reading, and (via `bridgeProgressToUserBook`) mirrors that
+ * to their PDS. A miss just leaves the document unlinked for the user to
+ * connect by hand, and the progress itself is stored either way, so e-reader
+ * sync is unaffected.
+ *
+ * 1. **Exact id hash of the supplied metadata.** `hive_book.id` is a hash of
+ *    the lowercased title + author, so a hit is an exact identity, not a
+ *    search.
+ * 2. **Exact id hash of title/author pairs parsed out of the filename**,
+ *    including pairs that cross client metadata with a filename-derived author.
+ *    Still exact: a wrong guess hashes to an id that does not exist.
+ * 3. **FTS on the filename-derived title**, accepted only when the normalized
+ *    title is *equal* (not merely ranked first) and the author agrees. With no
+ *    author signal at all, only an unambiguous single-book title is accepted.
+ *
+ * Tiers 2 and 3 exist because the filename is frequently the only thing we get.
+ * KOSync's own metadata is optional (KOReader's `send_metadata` defaults off;
+ * CrossPoint sends it) and plenty of documents carry no embedded title or
+ * author at all — but "Ursula K. Le Guin - The Dispossessed.epub" names a book
+ * perfectly well.
+ *
+ * This takes only what the client sent. Prefer `matchSyncDocumentForUser`,
+ * which also brings the user's own uploaded files to bear — it is the only
+ * thing that helps a default-configured client, which sends no metadata at all.
+ */
 export async function matchSyncDocument(
   db: Database,
   metadata: { title?: string | null; authors?: string | null; filename?: string | null },
 ): Promise<HiveId | null> {
-  const { title, authors } = metadata;
-  if (!title) return null;
-
-  const authorStr = authors || "Unknown";
-
-  // Exact match only: the derived HiveId is a hash of the normalized
-  // title + author. A confident hit auto-bridges to the user's book; anything
-  // else is left unlinked for the user to connect manually, so we never write
-  // progress to the wrong book. The sync_document row (and its progress) is
-  // stored regardless, so e-reader sync itself is unaffected by a miss.
-  const candidateId = getHiveId({ title, authors: authorStr });
-  const exact = await db
-    .selectFrom("hive_book")
-    .select("id")
-    .where("id", "=", candidateId)
-    .executeTakeFirst();
-  if (exact) return exact.id;
+  const { title, authors, filename } = metadata;
+
+  // The client's `title` may itself be a filename. KOReader sends
+  // `doc_props.display_title`, which is `props.title or
+  // splitFileNameType(filepath)` — for any document with no embedded title (a
+  // conversion, most scanned PDFs, plenty of epubs) that is literally the
+  // filename minus its extension, dashes and all. So parse it the same way.
+  const candidates = dedupeCandidates([
+    ...filenameBookCandidates(filename),
+    ...filenameBookCandidates(title),
+  ]);
+  if (!title && candidates.length === 0) return null;
+
+  // ── Tiers 1 + 2: exact id hashes, most confident first ──
+  const ids: HiveId[] = [];
+  const considerId = (t: string, a: string) => {
+    const id = getHiveId({ title: t, authors: a });
+    if (!ids.includes(id)) ids.push(id);
+  };
+
+  if (title) considerId(title, authors || "Unknown");
+  for (const c of candidates) {
+    if (c.authors) considerId(c.title, c.authors);
+    if (authors) considerId(c.title, authors);
+  }
+  // The client named the book but not the author; the filename may have one.
+  if (title) {
+    for (const c of candidates) {
+      if (c.authors) considerId(title, c.authors);
+    }
+  }
+
+  if (ids.length > 0) {
+    const found = await db.selectFrom("hive_book").select("id").where("id", "in", ids).execute();
+    if (found.length > 0) {
+      const hit = new Set(found.map((r) => r.id));
+      // Resolve in the order the ids were generated, so client metadata beats a
+      // filename guess and a two-sided guess beats a one-sided one.
+      const best = ids.find((id) => hit.has(id));
+      if (best) return best;
+    }
+  }
+
+  // ── Tier 3: fuzzy, on the filename only ──
+  const authorSignals = dedupe([
+    ...splitAuthorSignal(authors),
+    ...candidates.flatMap((c) => splitAuthorSignal(c.authors)),
+  ]);
+
+  // Candidate pool. `hive_book_fts` matches phrases, so searching it for the
+  // title only finds books whose title tokenizes the same way — "Hitchhikers
+  // Guide" never reaches "The Hitchhiker's Guide". Searching for the *author*
+  // instead sidesteps that: an author's name is spelled the same either way,
+  // and their handful of books can then be compared on title in JS, where the
+  // comparison can be as forgiving as it needs to be. The title search stays
+  // as the only option when the filename yields no author at all.
+  const authorQueries: string[] = [];
+  for (const signal of authorSignals) {
+    const q = ftsMatchQuery(normalizeAuthor(signal));
+    if (q) authorQueries.push(q);
+  }
+  const titleQueries: string[] = [];
+  const seenTitles = new Set<string>();
+  for (const candidate of candidates) {
+    const want = normalizeTitle(candidate.title);
+    if (!want || seenTitles.has(want)) continue;
+    seenTitles.add(want);
+    const q = ftsMatchQuery(candidate.title);
+    if (q) titleQueries.push(q);
+  }
+
+  // Author queries lead — they are the ones that can reach a title we'd never
+  // tokenize our way to. But they must not consume the whole budget: an `A - B`
+  // filename contributes an author signal for *both* orderings, so four junk
+  // signals could crowd the title query out entirely and leave the pool empty
+  // when the title alone would have found the book. One slot is always held
+  // back for the first title query.
+  const deduped = dedupe([...authorQueries, ...titleQueries]);
+  const firstTitle = deduped.find((q) => titleQueries.includes(q));
+  let queries = deduped.slice(0, MAX_FTS_QUERIES);
+  if (firstTitle && !queries.includes(firstTitle)) {
+    queries = [...queries.slice(0, MAX_FTS_QUERIES - 1), firstTitle];
+  }
+
+  const pool = new Map<HiveId, FtsRow>();
+  for (const match of queries) {
+    const rows = (
+      await sql<FtsRow>`
+        SELECT b.id, b.title, b.authors, b.ratingsCount
+        FROM hive_book_fts f
+        JOIN hive_book b ON b.rowid = f.rowid
+        WHERE hive_book_fts MATCH ${match}
+        ORDER BY b.ratingsCount DESC, b.rating DESC
+        LIMIT ${FTS_LIMIT}
+      `.execute(db)
+    ).rows;
+    for (const row of rows) if (!pool.has(row.id)) pool.set(row.id, row);
+  }
+  if (pool.size === 0) return null;
+
+  const books = [...pool.values()].sort((a, b) => (b.ratingsCount ?? 0) - (a.ratingsCount ?? 0));
+
+  for (const candidate of candidates) {
+    // Ranking is by popularity, which says nothing about whether the top hit is
+    // *this* book. Only titles that name the same book are eligible.
+    const eligible = books.filter((r) => titlesEquivalent(candidate.title, r.title));
+    if (eligible.length === 0) continue;
+
+    if (authorSignals.length > 0) {
+      const byAuthor = eligible.filter((r) =>
+        parseAuthors(r.authors || "").some((bookAuthor) =>
+          authorSignals.some((signal) => authorsMatch(bookAuthor, signal)),
+        ),
+      );
+      // Several editions can agree on both; prefer the closest title, then the
+      // popularity order the query already applied.
+      const hit = byAuthor.reduce<FtsRow | null>(
+        (best, r) =>
+          best === null ||
+          similarityScore(candidate.title, r.title) > similarityScore(candidate.title, best.title)
+            ? r
+            : best,
+        null,
+      );
+      if (hit) return hit.id;
+      // The title matched but no author did: this is a different book with the
+      // same name. Fall through to the next candidate rather than to the
+      // no-author rule below, which would accept it.
+      continue;
+    }
+
+    // No author anywhere. Accept only a title that names exactly one book in
+    // the catalogue — otherwise we would be picking the most popular of several
+    // unrelated books that happen to share a title.
+    const distinct = new Set(eligible.map((r) => r.id));
+    if (distinct.size === 1) return eligible[0]!.id;
+  }
 
   return null;
 }
+
+/**
+ * Resolve a synced document to a book using everything we hold for this user,
+ * not just what the client sent.
+ *
+ * This is the entry point the KOSync routes use, and it exists for the
+ * **default** KOReader configuration, which is the majority: `checksum_method`
+ * is BINARY and `send_metadata` is off, so the entire request identifies the
+ * book as one partial-MD5 hash and nothing else. `matchSyncDocument` has
+ * nothing to work with — no title, no author, no filename — and returns null
+ * every time, forever, no matter how good its tiers get.
+ *
+ * But that hash *is* `personal_book.contentHash`. If the user has uploaded the
+ * file, we already parsed real title/author metadata out of the ebook itself at
+ * upload time, and may already have resolved it to a book. So: find the file
+ * first, inherit its book if it has one, and otherwise match on the file's
+ * metadata. The upload path already pushes a link the other way when the
+ * document exists first (`uploadPersonalBook` step 9); this closes the opposite
+ * ordering, where the file is uploaded before the e-reader ever syncs it.
+ */
+export async function matchSyncDocumentForUser(
+  db: Database,
+  userDid: string,
+  doc: {
+    documentHash: string;
+    filename?: string | null;
+    title?: string | null;
+    authors?: string | null;
+  },
+): Promise<HiveId | null> {
+  const docFilenameKey = filenameKey(doc.filename);
+  const file = await db
+    .selectFrom("personal_book")
+    .select(["id", "hiveId", "title", "authors", "filename"])
+    .where("userDid", "=", userDid)
+    .where((eb) =>
+      eb.or([
+        eb("contentHash", "=", doc.documentHash),
+        eb("filenameHash", "=", doc.documentHash),
+        ...(docFilenameKey ? [eb("filenameKey", "=", docFilenameKey)] : []),
+      ]),
+    )
+    // A byte-identical file is a stronger claim than a same-name one.
+    .orderBy(sql`CASE WHEN contentHash = ${doc.documentHash} THEN 0 ELSE 1 END`, "asc")
+    .executeTakeFirst();
+
+  if (file?.hiveId && file.hiveId !== NO_HIVE_MATCH) return file.hiveId;
+
+  let hiveId = await matchSyncDocument(db, doc);
+  if (!hiveId && file) {
+    // The ebook's own metadata, parsed from the file at upload time. Usually
+    // better than anything a filename can offer, and for a default-configured
+    // client it is the only thing there is.
+    hiveId = await matchSyncDocument(db, {
+      title: file.title,
+      authors: file.authors,
+      filename: file.filename,
+    });
+  }
+
+  if (hiveId && file && !file.hiveId) {
+    // Keep the file and the document agreeing, and mirror the upload path's
+    // "you own a copy" flag. The `hiveId is null` guard is enforced in the
+    // statement, not just by the `!file.hiveId` read above: two sync pushes for
+    // the same file can race between the SELECT and this UPDATE, and the loser
+    // would otherwise overwrite a link the winner just established.
+    const updated = await db
+      .updateTable("personal_book")
+      .set({ hiveId })
+      .where("id", "=", file.id)
+      .where("hiveId", "is", null)
+      .executeTakeFirst();
+
+    // Lost the race: another request (or a manual link in another tab) linked
+    // this file first, possibly to a *different* book. Adopt whatever it
+    // persisted instead of our own guess, so the file, the ownership flag and
+    // the returned id can't disagree — a wrong link is worse than no link.
+    if (!updated.numUpdatedRows) {
+      const current = await db
+        .selectFrom("personal_book")
+        .select("hiveId")
+        .where("id", "=", file.id)
+        .executeTakeFirst();
+      // Always take the persisted value, never the stale local guess: adopt a
+      // real link, but clear to null when the winner dismissed the match
+      // (NO_HIVE_MATCH) or the row vanished — so the ownership update below
+      // matches nothing and we return "no match" rather than a wrong link.
+      hiveId = current?.hiveId && current.hiveId !== NO_HIVE_MATCH ? current.hiveId : null;
+    }
+
+    await db
+      .updateTable("user_book")
+      .set({ owned: 1 })
+      .where("userDid", "=", userDid)
+      .where("hiveId", "=", hiveId)
+      .where("owned", "=", 0)
+      .execute();
+  }
+
+  return hiveId;
+}
diff --git a/src/utils/uploadPersonalBook.test.ts b/src/utils/uploadPersonalBook.test.ts
new file mode 100644
index 0000000..0b7bd02
--- /dev/null
+++ b/src/utils/uploadPersonalBook.test.ts
@@ -0,0 +1,646 @@
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { Database as DatabaseSync } from "bun:sqlite";
+import { Kysely, SqliteDialect } from "kysely";
+import { createStorage } from "unstorage";
+import memoryDriver from "unstorage/drivers/memory";
+import { readdir, rm } from "node:fs/promises";
+import path from "node:path";
+import type { Storage } from "unstorage";
+
+import { wrapBunSqliteForKysely } from "../bun-sqlite-kysely";
+import { migrateToLatest, type DatabaseSchema, type Database } from "../db";
+import type { HiveId } from "../types";
+import { imageMeta } from "image-meta";
+import { koreaderPartialMD5, MIN_COVER_DIMENSION } from "./bookMetadata/index";
+import { makeCbz, makeEpub, makeFb2, makeSvgCover, PNG_1 } from "./bookMetadata/testFixtures";
+import { filenameKey, koreaderFilenameHash } from "./filenameMatching";
+import { getHiveId } from "../scrapers/getHiveId";
+import { NO_HIVE_MATCH } from "./syncMatching";
+import {
+  bookFilePath,
+  coverFilePath,
+  ensureDir,
+  getLibraryTmpDir,
+  getStorageQuota,
+  getStorageUsage,
+  personalBookDir,
+  MAX_PERSONAL_BOOK_BYTES,
+} from "./personalLibrary";
+import { uploadPersonalBook, type UploadPersonalBookResult } from "./uploadPersonalBook";
+
+const DID = "did:plc:testuser";
+const OTHER_DID = "did:plc:someoneelse";
+const HIVE_A = "bk_aaaaaaaa" as HiveId;
+
+let db: Database;
+let kv: Storage;
+
+async function createTestDb(): Promise<Database> {
+  const sqlite = new DatabaseSync(":memory:");
+  sqlite.exec("PRAGMA journal_mode = WAL");
+  const database = new Kysely<DatabaseSchema>({
+    dialect: new SqliteDialect({ database: wrapBunSqliteForKysely(sqlite) }),
+  });
+  await migrateToLatest(database, sqlite);
+  return database;
+}
+
+/** Upload from a buffer, through the same stream path a real request uses. */
+function upload(
+  bytes: Uint8Array,
+  filename: string,
+  opts: { userDid?: string; declaredLength?: number | undefined; chunked?: boolean } = {},
+): Promise<UploadPersonalBookResult> {
+  const userDid = opts.userDid ?? DID;
+  const body = new ReadableStream<Uint8Array>({
+    start(controller) {
+      // Two chunks, so the streaming path is genuinely exercised rather than
+      // degenerating into a single write.
+      const mid = Math.floor(bytes.length / 2);
+      controller.enqueue(bytes.subarray(0, mid));
+      controller.enqueue(bytes.subarray(mid));
+      controller.close();
+    },
+  });
+  return uploadPersonalBook({
+    db,
+    kv,
+    userDid,
+    filename,
+    // `chunked` models a request with no Content-Length.
+    source: {
+      kind: "stream",
+      body,
+      declaredLength: opts.chunked ? undefined : (opts.declaredLength ?? bytes.length),
+    },
+  });
+}
+
+async function seedSyncDocument(opts: {
+  documentHash: string;
+  hiveId?: HiveId | null;
+  filename?: string | null;
+  title?: string | null;
+  authors?: string | null;
+  percentage?: number;
+  userDid?: string;
+}): Promise<void> {
+  await db
+    .insertInto("sync_document")
+    .values({
+      userDid: opts.userDid ?? DID,
+      provider: "kosync",
+      documentHash: opts.documentHash,
+      hiveId: opts.hiveId ?? null,
+      filename: opts.filename ?? null,
+      filenameKey: filenameKey(opts.filename ?? null),
+      title: opts.title ?? null,
+      authors: opts.authors ?? null,
+      progressData: JSON.stringify({
+        progress: "1",
+        percentage: opts.percentage ?? 0.5,
+        device: "kindle",
+        device_id: "d1",
+        timestamp: 1,
+      }),
+      createdAt: "2026-08-01T00:00:00.000Z",
+      updatedAt: "2026-08-01T00:00:00.000Z",
+    })
+    .execute();
+}
+
+/**
+ * Seed a catalog book. Returns its id, which is derived from title+author —
+ * `matchSyncDocument`'s strongest tier recomputes exactly that hash and looks
+ * it up, so a fuzzy-match test only works with the real derived id.
+ */
+async function seedHiveBook(title: string, authors: string): Promise<HiveId> {
+  const id = getHiveId({ title, authors });
+  await db
+    .insertInto("hive_book")
+    .values({
+      id,
+      title,
+      rawTitle: title,
+      authors,
+      source: "goodreads",
+      thumbnail: "",
+      createdAt: "2026-08-01T00:00:00.000Z",
+      updatedAt: "2026-08-01T00:00:00.000Z",
+    } as never)
+    .execute();
+  return id;
+}
+
+async function seedUserBook(hiveId: HiveId, owned = 0, userDid = DID): Promise<void> {
+  await db
+    .insertInto("user_book")
+    .values({
+      uri: `at://${userDid}/buzz.bookhive.book/${hiveId}`,
+      cid: "cid",
+      userDid,
+      hiveId,
+      title: "t",
+      authors: "a",
+      status: "buzz.bookhive.defs#reading",
+      owned,
+      createdAt: "2026-08-01T00:00:00.000Z",
+      indexedAt: "2026-08-01T00:00:00.000Z",
+    })
+    .execute();
+}
+
+/** Seed a row directly, for quota arithmetic that shouldn't touch the disk. */
+async function seedPersonalBook(contentHash: string, sizeBytes: number, userDid = DID) {
+  await db
+    .insertInto("personal_book")
+    .values({
+      userDid,
+      contentHash,
+      filename: `${contentHash}.epub`,
+      title: "Seeded",
+      format: "epub",
+      mime: "application/epub+zip",
+      filePath: `/tmp/${contentHash}.epub`,
+      sizeBytes,
+      createdAt: "2026-08-01T00:00:00.000Z",
+      updatedAt: "2026-08-01T00:00:00.000Z",
+    })
+    .execute();
+}
+
+async function tmpEntries(): Promise<string[]> {
+  try {
+    return (await readdir(getLibraryTmpDir())).filter((n) => n.endsWith(".part"));
+  } catch {
+    return [];
+  }
+}
+
+beforeEach(async () => {
+  db = await createTestDb();
+  kv = createStorage({ driver: memoryDriver() });
+  // The preload points LIBRARY_DIR at a per-pid tmp root; make sure it exists
+  // and is empty so leftover files can't make an assertion pass.
+  await ensureDir(getLibraryTmpDir());
+  await rm(personalBookDir(DID, ""), { recursive: true, force: true }).catch(() => {});
+});
+
+afterEach(async () => {
+  for (const did of [DID, OTHER_DID]) {
+    await rm(path.dirname(personalBookDir(did, "x")), { recursive: true, force: true }).catch(
+      () => {},
+    );
+  }
+  for (const name of await tmpEntries()) {
+    await rm(path.join(getLibraryTmpDir(), name), { force: true });
+  }
+});
+
+describe("uploadPersonalBook — happy path", () => {
+  it("writes the file and cover to disk and persists every column", async () => {
+    const bytes = makeEpub({ title: "Dune", authors: ["Frank Herbert"], language: "en" });
+    const result = await upload(bytes, "Dune.epub");
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    expect(result.book.title).toBe("Dune");
+    expect(result.book.authors).toBe("Frank Herbert");
+    expect(result.book.language).toBe("en");
+    expect(result.book.format).toBe("epub");
+    expect(result.book.mime).toBe("application/epub+zip");
+    expect(result.book.sizeBytes).toBe(bytes.length);
+    expect(result.book.coverUrl).toBe(`/library/covers/${result.book.contentHash}`);
+
+    const hash = result.book.contentHash;
+    const stored = Bun.file(bookFilePath(DID, hash, "epub"));
+    expect(await stored.exists()).toBe(true);
+    expect(stored.size).toBe(bytes.length);
+
+    const cover = Bun.file(coverFilePath(DID, hash, "png"));
+    expect(await cover.exists()).toBe(true);
+
+    const row = await db
+      .selectFrom("personal_book")
+      .selectAll()
+      .where("userDid", "=", DID)
+      .executeTakeFirstOrThrow();
+    expect(row.title).toBe("Dune");
+    expect(row.authors).toBe("Frank Herbert");
+    expect(row.language).toBe("en");
+    expect(row.sizeBytes).toBe(bytes.length);
+    expect(row.filename).toBe("Dune.epub");
+    expect(row.filenameHash).toBe(koreaderFilenameHash("Dune.epub"));
+    expect(row.filenameKey).toBe(filenameKey("Dune.epub"));
+    expect(row.coverMime).toBe("image/png");
+    expect(row.coverPath).toBe(coverFilePath(DID, hash, "png"));
+  });
+
+  it("computes the same content hash streaming as in memory", async () => {
+    // The KOReader-compat invariant: this hash is what lines an uploaded file
+    // up with the `document` id a device sends. If the streamed and in-memory
+    // implementations ever diverge, every FILENAME/BINARY match silently stops.
+    for (const [bytes, name] of [
+      [makeEpub(), "a.epub"],
+      [makeFb2(), "b.fb2"],
+      [makeEpub({ padBytes: 70_000 }), "c.epub"],
+    ] as const) {
+      const result = await upload(bytes, name);
+      expect(result.ok).toBe(true);
+      if (result.ok) expect(result.book.contentHash).toBe(koreaderPartialMD5(bytes));
+      await db.deleteFrom("personal_book").execute();
+    }
+  });
+
+  it("leaves no temp file behind", async () => {
+    await upload(makeEpub(), "x.epub");
+    expect(await tmpEntries()).toEqual([]);
+  });
+
+  it("reports storage usage after the upload", async () => {
+    const bytes = makeEpub();
+    const result = await upload(bytes, "x.epub");
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.storageUsedBytes).toBe(bytes.length);
+    expect(result.storageQuotaBytes).toBe(getStorageQuota());
+  });
+});
+
+describe("uploadPersonalBook — cover handling", () => {
+  it("stores no cover when the extracted image is too small to be real", async () => {
+    const result = await upload(makeEpub({ cover: PNG_1 }), "tiny.epub");
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    expect(result.book.coverUrl).toBeUndefined();
+    const row = await db
+      .selectFrom("personal_book")
+      .select(["coverPath", "coverMime"])
+      .executeTakeFirstOrThrow();
+    expect(row.coverPath).toBeNull();
+    expect(row.coverMime).toBeNull();
+
+    // And nothing was written for it.
+    const dir = await readdir(personalBookDir(DID, result.book.contentHash));
+    expect(dir.some((n) => n.startsWith("cover."))).toBe(false);
+  });
+
+  it("takes the first page of a CBZ as the cover", async () => {
+    const result = await upload(makeCbz(), "comic.cbz");
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.book.format).toBe("cbz");
+    expect(await Bun.file(coverFilePath(DID, result.book.contentHash, "png")).exists()).toBe(true);
+  });
+
+  it("rasterizes an SVG cover, the shape every Standard Ebooks book ships", async () => {
+    // Before this, `isUsableCover` asked Bun's image pipeline to decode the SVG,
+    // it answered "unrecognised format", and the entire Standard Ebooks corpus
+    // uploaded with no cover at all.
+    const result = await upload(
+      makeEpub({
+        cover: makeSvgCover(),
+        coverName: "cover.svg",
+        coverMediaType: "image/svg+xml",
+      }),
+      "standard-ebooks.epub",
+    );
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    // Stored as a raster, never as SVG: OPDS clients and e-readers can't be
+    // relied on to render vector covers, and an SVG served from our own origin
+    // would be script-capable where a JPEG is inert.
+    const row = await db
+      .selectFrom("personal_book")
+      .select(["coverPath", "coverMime"])
+      .executeTakeFirstOrThrow();
+    expect(row.coverMime).toBe("image/jpeg");
+    expect(row.coverPath).toBe(coverFilePath(DID, result.book.contentHash, "jpg"));
+    expect(result.book.coverUrl).toBe(`/library/covers/${result.book.contentHash}`);
+
+    const onDisk = new Uint8Array(await Bun.file(row.coverPath!).arrayBuffer());
+    const meta = imageMeta(onDisk);
+    expect(meta.type).toBe("jpg");
+    expect(meta.width).toBeGreaterThanOrEqual(MIN_COVER_DIMENSION);
+    expect(meta.height).toBeGreaterThanOrEqual(MIN_COVER_DIMENSION);
+  });
+});
+
+describe("uploadPersonalBook — empty metadata normalisation", () => {
+  it("stores NULL rather than empty string for missing authors and language", async () => {
+    // A CBZ carries no metadata at all, so parseBook returns authors: "".
+    const result = await upload(makeCbz(2, 100), "Nameless.cbz");
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    expect(result.book.authors).toBeUndefined();
+    expect(result.book.language).toBeUndefined();
+
+    const row = await db
+      .selectFrom("personal_book")
+      .select(["authors", "language"])
+      .executeTakeFirstOrThrow();
+    expect(row.authors).toBeNull();
+    expect(row.language).toBeNull();
+
+    // The point of NULL over "": this predicate has to find the row.
+    const missing = await db
+      .selectFrom("personal_book")
+      .select("id")
+      .where("authors", "is", null)
+      .execute();
+    expect(missing).toHaveLength(1);
+  });
+});
+
+describe("uploadPersonalBook — sync document linking", () => {
+  it("links via an exact content hash", async () => {
+    const bytes = makeEpub();
+    await seedSyncDocument({ documentHash: koreaderPartialMD5(bytes), hiveId: HIVE_A });
+
+    const result = await upload(bytes, "x.epub");
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.book.hiveId).toBe(HIVE_A);
+  });
+
+  it("links via the filename hash a FILENAME-mode client sends", async () => {
+    await seedSyncDocument({
+      documentHash: koreaderFilenameHash("Dune.epub")!,
+      hiveId: HIVE_A,
+    });
+
+    const result = await upload(makeEpub(), "Dune.epub");
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.book.hiveId).toBe(HIVE_A);
+  });
+
+  it("links via the normalised filename key across a format conversion", async () => {
+    await seedSyncDocument({
+      documentHash: "unrelated-hash",
+      hiveId: HIVE_A,
+      filename: "Dune.azw3",
+    });
+
+    const result = await upload(makeEpub(), "Dune.epub");
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.book.hiveId).toBe(HIVE_A);
+  });
+
+  it("prefers a byte-exact document over a fuzzy title match", async () => {
+    // The regression this pins: the XRPC path used to run the fuzzy matcher
+    // first, so a title guess could beat an exact documentHash. Both links are
+    // available here and the exact one has to win.
+    const bytes = makeEpub({ title: "Dune", authors: ["Frank Herbert"] });
+    const fuzzyId = await seedHiveBook("Dune", "Frank Herbert");
+    await seedSyncDocument({ documentHash: koreaderPartialMD5(bytes), hiveId: HIVE_A });
+
+    const result = await upload(bytes, "Dune.epub");
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.book.hiveId).toBe(HIVE_A);
+      expect(result.book.hiveId).not.toBe(fuzzyId);
+    }
+  });
+
+  it("falls back to fuzzy matching when no document matches", async () => {
+    const hiveId = await seedHiveBook("Dune", "Frank Herbert");
+    const result = await upload(
+      makeEpub({ title: "Dune", authors: ["Frank Herbert"] }),
+      "Dune.epub",
+    );
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.book.hiveId).toBe(hiveId);
+  });
+
+  it("never adopts the dismissal sentinel", async () => {
+    const bytes = makeEpub({ title: "Untraceable Xyzzy", authors: ["Nobody At All"] });
+    await seedSyncDocument({
+      documentHash: koreaderPartialMD5(bytes),
+      hiveId: NO_HIVE_MATCH,
+    });
+
+    const result = await upload(bytes, "x.epub");
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.book.hiveId).toBeUndefined();
+  });
+
+  it("writes the link back onto an unmatched document and bridges its progress", async () => {
+    const bytes = makeEpub({ title: "Dune", authors: ["Frank Herbert"] });
+    const hiveId = await seedHiveBook("Dune", "Frank Herbert");
+    await seedUserBook(hiveId);
+    // A document the device has been pushing progress for that never matched.
+    await seedSyncDocument({
+      documentHash: koreaderPartialMD5(bytes),
+      hiveId: null,
+      percentage: 0.42,
+    });
+
+    const result = await upload(bytes, "Dune.epub");
+    expect(result.ok).toBe(true);
+
+    const doc = await db.selectFrom("sync_document").select("hiveId").executeTakeFirstOrThrow();
+    expect(doc.hiveId).toBe(hiveId);
+
+    // The percentage it had already recorded is now on the user's book, rather
+    // than sitting unused until the device next syncs.
+    const userBook = await db
+      .selectFrom("user_book")
+      .select(["bookProgress", "owned"])
+      .executeTakeFirstOrThrow();
+    expect(JSON.parse(userBook.bookProgress!).percent).toBe(42);
+    expect(userBook.owned).toBe(1);
+  });
+
+  it("does not clobber a document the user linked by hand", async () => {
+    const bytes = makeEpub({ title: "Dune", authors: ["Frank Herbert"] });
+    await seedHiveBook("Dune", "Frank Herbert");
+    await seedSyncDocument({ documentHash: koreaderPartialMD5(bytes), hiveId: HIVE_A });
+
+    await upload(bytes, "Dune.epub");
+    const doc = await db.selectFrom("sync_document").select("hiveId").executeTakeFirstOrThrow();
+    expect(doc.hiveId).toBe(HIVE_A);
+  });
+
+  it("flips owned only for the uploading user", async () => {
+    const bytes = makeEpub();
+    await seedSyncDocument({ documentHash: koreaderPartialMD5(bytes), hiveId: HIVE_A });
+    await seedUserBook(HIVE_A, 0, DID);
+    await seedUserBook(HIVE_A, 0, OTHER_DID);
+
+    await upload(bytes, "x.epub");
+
+    const mine = await db
+      .selectFrom("user_book")
+      .select("owned")
+      .where("userDid", "=", DID)
+      .executeTakeFirstOrThrow();
+    const theirs = await db
+      .selectFrom("user_book")
+      .select("owned")
+      .where("userDid", "=", OTHER_DID)
+      .executeTakeFirstOrThrow();
+    expect(mine.owned).toBe(1);
+    expect(theirs.owned).toBe(0);
+  });
+});
+
+describe("uploadPersonalBook — rejections", () => {
+  it("rejects an unsupported format and leaves nothing behind", async () => {
+    const result = await upload(new TextEncoder().encode("just some text"), "notes.txt");
+    expect(result).toEqual({ ok: false, reason: "unsupported-format", filename: "notes.txt" });
+    expect(await db.selectFrom("personal_book").selectAll().execute()).toHaveLength(0);
+    expect(await tmpEntries()).toEqual([]);
+  });
+
+  it("rejects an empty body", async () => {
+    const result = await upload(new Uint8Array(0), "empty.epub");
+    expect(result).toEqual({ ok: false, reason: "empty" });
+    expect(await tmpEntries()).toEqual([]);
+  });
+
+  it("rejects a file merely named .epub", async () => {
+    // detectFormat validates the extension's claim against the magic bytes —
+    // this is the real gate, not the declared Content-Type.
+    const result = await upload(new TextEncoder().encode("not a zip at all"), "fake.epub");
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toBe("unsupported-format");
+  });
+
+  it("rejects a duplicate without writing anything", async () => {
+    const bytes = makeEpub();
+    const first = await upload(bytes, "x.epub");
+    expect(first.ok).toBe(true);
+
+    const second = await upload(bytes, "x.epub");
+    expect(second.ok).toBe(false);
+    if (!second.ok) expect(second.reason).toBe("duplicate");
+
+    expect(await db.selectFrom("personal_book").selectAll().execute()).toHaveLength(1);
+    expect(await tmpEntries()).toEqual([]);
+  });
+
+  it("lets two users hold the same bytes independently", async () => {
+    // The duplicate check is scoped to (userDid, contentHash) — a cross-user
+    // hash collision is the normal case (the same book), not an error.
+    const bytes = makeEpub();
+    const mine = await upload(bytes, "x.epub", { userDid: DID });
+    const theirs = await upload(bytes, "x.epub", { userDid: OTHER_DID });
+
+    expect(mine.ok).toBe(true);
+    expect(theirs.ok).toBe(true);
+    expect(await db.selectFrom("personal_book").selectAll().execute()).toHaveLength(2);
+    if (mine.ok && theirs.ok) {
+      expect(await Bun.file(bookFilePath(DID, mine.book.contentHash, "epub")).exists()).toBe(true);
+      expect(
+        await Bun.file(bookFilePath(OTHER_DID, theirs.book.contentHash, "epub")).exists(),
+      ).toBe(true);
+    }
+  });
+
+  it("caps a chunked body with no declared length", async () => {
+    // The case hono's bodyLimit() buffered whole: no Content-Length, so the
+    // ceiling can only be enforced while streaming.
+    const oversized = new ReadableStream<Uint8Array>({
+      start(controller) {
+        const chunk = new Uint8Array(1024 * 1024);
+        for (let sent = 0; sent <= MAX_PERSONAL_BOOK_BYTES; sent += chunk.length) {
+          controller.enqueue(chunk);
+        }
+        controller.close();
+      },
+    });
+
+    const result = await uploadPersonalBook({
+      db,
+      kv,
+      userDid: DID,
+      filename: "huge.epub",
+      source: { kind: "stream", body: oversized, declaredLength: undefined },
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toBe("too-large");
+    expect(await tmpEntries()).toEqual([]);
+  }, 60_000);
+
+  it("caps an in-memory byte source too", async () => {
+    // The `bytes` branch of writeCapped is its own code path — the XRPC
+    // procedure can hand the core a buffer rather than a stream, and it must
+    // hit the same ceiling rather than writing the whole thing out first.
+    const oversized = new Uint8Array(MAX_PERSONAL_BOOK_BYTES + 1);
+
+    const result = await uploadPersonalBook({
+      db,
+      kv,
+      userDid: DID,
+      filename: "huge.epub",
+      source: { kind: "bytes", bytes: oversized },
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toBe("too-large");
+    expect(await db.selectFrom("personal_book").selectAll().execute()).toHaveLength(0);
+    expect(await tmpEntries()).toEqual([]);
+  }, 60_000);
+});
+
+describe("uploadPersonalBook — storage quota", () => {
+  it("refuses an upload that would cross the quota, before reading the body", async () => {
+    const bytes = makeEpub();
+    // One byte of headroom short of what this upload needs.
+    const used = getStorageQuota() - bytes.length + 1;
+    await seedPersonalBook("seeded", used);
+
+    const result = await upload(bytes, "x.epub");
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.reason).toBe("quota-exceeded");
+      if (result.reason === "quota-exceeded") {
+        expect(result.quotaBytes).toBe(getStorageQuota());
+        expect(result.usedBytes).toBe(used);
+      }
+    }
+    // Nothing stored, and the body was never drained to disk.
+    expect(await db.selectFrom("personal_book").selectAll().execute()).toHaveLength(1);
+    expect(await tmpEntries()).toEqual([]);
+  });
+
+  it("enforces the quota against the real size when none was declared", async () => {
+    const bytes = makeEpub();
+    await seedPersonalBook("seeded", getStorageQuota() - Math.floor(bytes.length / 2));
+
+    const result = await upload(bytes, "x.epub", { chunked: true });
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toBe("quota-exceeded");
+    expect(await db.selectFrom("personal_book").selectAll().execute()).toHaveLength(1);
+    expect(await tmpEntries()).toEqual([]);
+  });
+
+  it("allows an upload that lands exactly on the quota", async () => {
+    const bytes = makeEpub();
+    await seedPersonalBook("seeded", getStorageQuota() - bytes.length);
+
+    const result = await upload(bytes, "x.epub");
+    expect(result.ok).toBe(true);
+  });
+
+  it("does not count another user's books toward mine", async () => {
+    await seedPersonalBook("theirs", getStorageQuota(), OTHER_DID);
+    const result = await upload(makeEpub(), "x.epub");
+    expect(result.ok).toBe(true);
+    expect(await getStorageUsage(db, OTHER_DID)).toBe(getStorageQuota());
+  });
+
+  it("frees space when a book is deleted", async () => {
+    const bytes = makeEpub();
+    const first = await upload(bytes, "x.epub");
+    expect(first.ok).toBe(true);
+    expect(await getStorageUsage(db, DID)).toBe(bytes.length);
+
+    await db.deleteFrom("personal_book").where("userDid", "=", DID).execute();
+    expect(await getStorageUsage(db, DID)).toBe(0);
+  });
+});
diff --git a/src/utils/uploadPersonalBook.ts b/src/utils/uploadPersonalBook.ts
new file mode 100644
index 0000000..f82136d
--- /dev/null
+++ b/src/utils/uploadPersonalBook.ts
@@ -0,0 +1,589 @@
+/**
+ * The one implementation of "put this ebook in this user's library".
+ *
+ * There used to be two: `POST /library/upload` (live) and `processBookUpload`
+ * in the XRPC router (dead code that claimed in its own doc comment to be the
+ * shared core). They drifted — different cover validation, different sync
+ * matching, only one of them writing the link back onto `sync_document` — which
+ * is exactly the failure mode a "shared" helper nobody shares is supposed to
+ * prevent. Both routes are now thin adapters over this function.
+ *
+ * The ordering of the pipeline below is the design, not an accident. Two
+ * properties it exists to hold:
+ *
+ * - **Nothing large is resident unless we are actually going to keep it.** The
+ *   body streams to a temp file, bounded by the sink's 1 MB high-water mark
+ *   regardless of how big the upload is; format detection reads a 4 KB
+ *   head; the KOReader hash reads twelve 1 KB windows; the duplicate check
+ *   happens before the parse. A rejected upload — wrong format, too big, over
+ *   quota, already present — never allocates a copy of the file. Only
+ *   `parseBook` needs the whole thing, and that step is behind a semaphore.
+ * - **The row commits before the bytes move into place.** The quota is
+ *   evaluated inside the INSERT, so a rejected upload unlinks a temp file
+ *   rather than discovering the problem after writing 100 MB to its final home.
+ *
+ * Errors are a discriminated result, never a throw. `processBookUpload` threw
+ * `XRPCError` from a util, which meant a Hono route had to catch an HTTP-shaped
+ * exception and translate it back. Each adapter now owns its own status codes.
+ */
+
+import path from "node:path";
+import { rename, rm, readdir, stat } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { sql } from "kysely";
+import type { Storage } from "unstorage";
+
+import type { Database } from "../db";
+import type { HiveId } from "../types";
+import { env } from "../env";
+import { Semaphore, SemaphoreFullError, SemaphoreTimeoutError } from "./semaphore";
+import {
+  detectFormat,
+  koreaderPartialMD5File,
+  type BookCover,
+  type BookMetadata,
+  type FormatInfo,
+} from "./bookMetadata/index";
+import { parseBookInWorker } from "../workers/parse-client";
+import {
+  bookFilePath,
+  coverFilePath,
+  ensureDir,
+  getLibraryTmpDir,
+  getStorageQuota,
+  getStorageUsage,
+  personalBookDir,
+  MAX_PERSONAL_BOOK_BYTES,
+} from "./personalLibrary";
+import { matchSyncDocument, NO_HIVE_MATCH } from "./syncMatching";
+import { bridgeProgressToUserBook } from "./syncBridge";
+import { filenameKey, koreaderFilenameHash } from "./filenameMatching";
+import type { SyncProgressData } from "../types";
+
+/**
+ * Bytes needed for format detection. `detectFormat` reads at most the first 512
+ * bytes (the FictionBook sniff), the first 4 for the ZIP magic, and 60..68 for
+ * the MOBI magic — 4 KB is generous and keeps one read.
+ */
+const FORMAT_HEAD_BYTES = 4096;
+
+/**
+ * The parse is the only step holding a whole file (<=100 MB) in native memory,
+ * so this is the memory bound on uploads. It is **per process** — at the
+ * deployed `WEB_CONCURRENCY=3` the cluster-wide ceiling is `limit x 3 x 100 MB`,
+ * so 2 here means roughly 630 MB worst case rather than the previous unbounded
+ * ~300 MB *per in-flight upload*.
+ *
+ * `maxPending` sheds load instead of queueing waiters: each queued caller holds
+ * its closure — and therefore its temp file handle — alive, and a client that
+ * gets a fast 503 retries better than one that hangs.
+ */
+const parseSemaphore = new Semaphore(env.UPLOAD_PARSE_CONCURRENCY, {
+  label: "ebook-parse",
+  maxPending: 16,
+  acquireTimeoutMs: 30_000,
+});
+
+export type UploadSource =
+  | { kind: "stream"; body: ReadableStream<Uint8Array>; declaredLength?: number | undefined }
+  | { kind: "bytes"; bytes: Uint8Array };
+
+/** Exactly `buzz.bookhive.getPersonalLibrary#personalBookView`. */
+export type PersonalBookView = {
+  contentHash: string;
+  title: string;
+  authors?: string | undefined;
+  language?: string | undefined;
+  format: string;
+  mime: string;
+  sizeBytes: number;
+  createdAt: string;
+  updatedAt: string;
+  hiveId?: string | undefined;
+  coverUrl?: string | undefined;
+};
+
+export type UploadPersonalBookResult =
+  | { ok: true; book: PersonalBookView; storageUsedBytes: number; storageQuotaBytes: number }
+  | { ok: false; reason: "empty" }
+  | { ok: false; reason: "too-large"; limitBytes: number }
+  | { ok: false; reason: "unsupported-format"; filename: string }
+  | { ok: false; reason: "duplicate"; contentHash: string }
+  | {
+      ok: false;
+      reason: "quota-exceeded";
+      usedBytes: number;
+      quotaBytes: number;
+      fileBytes: number;
+    }
+  | { ok: false; reason: "busy" };
+
+/** Reasons in the order a caller is likely to want them, for exhaustive maps. */
+export type UploadFailureReason = Extract<UploadPersonalBookResult, { ok: false }>["reason"];
+
+class TooLargeError extends Error {}
+
+/**
+ * Stream a body to disk with a hard byte ceiling, holding at most one buffer's
+ * worth of it at a time.
+ *
+ * This is what replaces hono's `bodyLimit()` on the multipart route. That
+ * middleware only short-circuits on `Content-Length`; with a chunked body it
+ * drains the entire stream into an array and rebuilds the Request, so a
+ * compliant 100 MB chunked upload was buffered there *and again* by
+ * `formData()`. Capping while writing bounds every path identically.
+ */
+async function writeCapped(dest: string, source: UploadSource, cap: number): Promise<number> {
+  // `highWaterMark` is the real memory bound here: the sink buffers up to this
+  // much before flushing to disk, and awaiting each write is the backpressure
+  // signal. (Bun's FileSink returns a number synchronously today, but the type
+  // allows a Promise — awaiting handles both and costs nothing.)
+  const sink = Bun.file(dest).writer({ highWaterMark: 1024 * 1024 });
+  let written = 0;
+  try {
+    if (source.kind === "bytes") {
+      if (source.bytes.length > cap) throw new TooLargeError();
+      await sink.write(source.bytes);
+      written = source.bytes.length;
+    } else {
+      const reader = source.body.getReader();
+      try {
+        for (;;) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          written += value.length;
+          // Checked before the write, so nothing past the cap ever reaches disk.
+          if (written > cap) throw new TooLargeError();
+          await sink.write(value);
+        }
+      } finally {
+        await reader.cancel().catch(() => {});
+      }
+    }
+    await sink.end();
+  } catch (err) {
+    // Close the fd rather than leaking it; the caller unlinks the file.
+    try {
+      await sink.end();
+    } catch {
+      /* already ended */
+    }
+    throw err;
+  }
+  return written;
+}
+
+/**
+ * Insert the row only if it keeps the user under quota.
+ *
+ * The `SUM` is evaluated *inside* the statement rather than read first and
+ * compared in JS. SQLite serialises writers, so this is exact: two concurrent
+ * uploads cannot both observe the pre-insert total. A per-process mutex would
+ * not have worked anyway — production runs three independent processes against
+ * one file (`server/cluster.ts`).
+ *
+ * `ON CONFLICT DO NOTHING` covers the other way this statement can insert
+ * nothing: two uploads of the *same* file racing past the duplicate check,
+ * which would otherwise raise a UNIQUE violation on
+ * `idx_personal_book_user_hash` and surface as a 500 instead of the duplicate
+ * the caller asked about. The two zero-row cases are told apart by re-reading
+ * the row, so "duplicate" never gets reported as "quota exceeded".
+ */
+async function insertIfUnderQuota(
+  db: Database,
+  row: {
+    userDid: string;
+    contentHash: string;
+    hiveId: HiveId | null;
+    filename: string;
+    filenameHash: string | null;
+    filenameKey: string | null;
+    title: string;
+    authors: string | null;
+    language: string | null;
+    format: string;
+    mime: string;
+    filePath: string;
+    coverPath: string | null;
+    coverMime: string | null;
+    sizeBytes: number;
+    createdAt: string;
+    updatedAt: string;
+  },
+  quotaBytes: number,
+): Promise<"inserted" | "duplicate" | "over-quota"> {
+  const result = await sql<unknown>`
+    INSERT INTO personal_book
+      (userDid, contentHash, hiveId, filename, filenameHash, filenameKey, title, authors,
+       language, format, mime, filePath, coverPath, coverMime, sizeBytes, createdAt, updatedAt)
+    SELECT ${row.userDid}, ${row.contentHash}, ${row.hiveId}, ${row.filename},
+           ${row.filenameHash}, ${row.filenameKey}, ${row.title}, ${row.authors},
+           ${row.language}, ${row.format}, ${row.mime}, ${row.filePath},
+           ${row.coverPath}, ${row.coverMime}, ${row.sizeBytes}, ${row.createdAt},
+           ${row.updatedAt}
+    WHERE (
+      SELECT COALESCE(SUM(sizeBytes), 0) FROM personal_book WHERE userDid = ${row.userDid}
+    ) + ${row.sizeBytes} <= ${quotaBytes}
+    ON CONFLICT (userDid, contentHash) DO NOTHING
+  `.execute(db);
+  if ((result.numAffectedRows ?? 0n) > 0n) return "inserted";
+
+  const existing = await db
+    .selectFrom("personal_book")
+    .select("id")
+    .where("userDid", "=", row.userDid)
+    .where("contentHash", "=", row.contentHash)
+    .executeTakeFirst();
+  return existing ? "duplicate" : "over-quota";
+}
+
+/**
+ * Find an already-synced document that names the same book as this file, using
+ * every identity a KOSync client might have sent (see `SAME_BOOK_FILE`).
+ * Ordered so a byte-exact `documentHash` beats a filename-derived one, and
+ * skipping the dismissal sentinel, which is the user saying "not on BookHive".
+ */
+async function findExactSyncLink(
+  db: Database,
+  userDid: string,
+  contentHash: string,
+  uploadFilenameHash: string | null,
+  uploadFilenameKey: string | null,
+): Promise<HiveId | null> {
+  const doc = await db
+    .selectFrom("sync_document")
+    .select("hiveId")
+    .where("userDid", "=", userDid)
+    .where("hiveId", "is not", null)
+    .where("hiveId", "!=", NO_HIVE_MATCH)
+    .where((eb) =>
+      eb.or([
+        eb("documentHash", "=", contentHash),
+        ...(uploadFilenameHash ? [eb("documentHash", "=", uploadFilenameHash)] : []),
+        ...(uploadFilenameKey ? [eb("filenameKey", "=", uploadFilenameKey)] : []),
+      ]),
+    )
+    .orderBy(sql`CASE WHEN documentHash = ${contentHash} THEN 0 ELSE 1 END`, "asc")
+    .executeTakeFirst();
+  return doc?.hiveId ?? null;
+}
+
+/** KOReader stores its fraction as 0..1; anything else we treat as absent. */
+function progressPercentage(progressData: string | null | undefined): number | null {
+  if (!progressData) return null;
+  try {
+    const parsed = JSON.parse(progressData) as SyncProgressData;
+    const pct = Number(parsed.percentage);
+    return Number.isFinite(pct) ? pct : null;
+  } catch {
+    return null;
+  }
+}
+
+export type UploadPersonalBookInput = {
+  db: Database;
+  kv: Storage;
+  userDid: string;
+  filename: string;
+  source: UploadSource;
+};
+
+export async function uploadPersonalBook(
+  input: UploadPersonalBookInput,
+): Promise<UploadPersonalBookResult> {
+  const { db, kv, userDid, filename, source } = input;
+  const quotaBytes = getStorageQuota();
+  const declared =
+    source.kind === "stream" ? source.declaredLength : (source.bytes.length as number | undefined);
+
+  // ── 1. Reject on the declared size before reading a byte ──
+  // Advisory (a chunked body has no Content-Length, and the value is
+  // client-asserted either way), so it is an optimisation rather than the
+  // control — steps 2 and 8 are what actually enforce these two limits.
+  if (declared !== undefined && declared > MAX_PERSONAL_BOOK_BYTES) {
+    return { ok: false, reason: "too-large", limitBytes: MAX_PERSONAL_BOOK_BYTES };
+  }
+  if (declared !== undefined && declared > 0) {
+    const used = await getStorageUsage(db, userDid);
+    if (used + declared > quotaBytes) {
+      return {
+        ok: false,
+        reason: "quota-exceeded",
+        usedBytes: used,
+        quotaBytes,
+        fileBytes: declared,
+      };
+    }
+  }
+
+  // ── 2. Stream to a temp file on the same filesystem as the library ──
+  const tmpDir = getLibraryTmpDir();
+  await ensureDir(tmpDir);
+  const tmp = path.join(tmpDir, `${randomUUID()}.part`);
+
+  let size: number;
+  try {
+    size = await writeCapped(tmp, source, MAX_PERSONAL_BOOK_BYTES);
+  } catch (err) {
+    await rm(tmp, { force: true });
+    if (err instanceof TooLargeError) {
+      return { ok: false, reason: "too-large", limitBytes: MAX_PERSONAL_BOOK_BYTES };
+    }
+    throw err;
+  }
+
+  try {
+    if (size === 0) return { ok: false, reason: "empty" };
+
+    const file = Bun.file(tmp);
+
+    // ── 3. Format, from a 4 KB head ──
+    // The magic-byte check against the filename's extension is the real gate on
+    // what we accept; a declared Content-Type is client-asserted and worthless.
+    const head = new Uint8Array(await file.slice(0, FORMAT_HEAD_BYTES).arrayBuffer());
+    const formatInfo: FormatInfo = detectFormat(head, filename);
+    if (formatInfo.format === "unknown") {
+      return { ok: false, reason: "unsupported-format", filename };
+    }
+
+    // ── 4. Content hash, from twelve 1 KB windows ──
+    const contentHash = await koreaderPartialMD5File(file, size);
+
+    // ── 5. Duplicate check, BEFORE the parse ──
+    // Deliberately ahead of both the parse and the disk commit so a re-upload
+    // costs neither. `src/routes/library.test.ts` leans on this ordering to
+    // exercise the duplicate path without touching the library directory.
+    const duplicate = await db
+      .selectFrom("personal_book")
+      .select("id")
+      .where("userDid", "=", userDid)
+      .where("contentHash", "=", contentHash)
+      .executeTakeFirst();
+    if (duplicate) return { ok: false, reason: "duplicate", contentHash };
+
+    // ── 6+7. Parse and cover — the native-memory, CPU-bound steps ──
+    //
+    // Offloaded to a single-shot Worker (`parseBookInWorker`): `parseBook`
+    // (fflate `unzipSync`) and `prepareCover` (synchronous `resvg` raster) are
+    // the only whole-file, CPU-bound work in an upload, and running them inline
+    // would stall this process's event loop for the duration. The Worker reads
+    // the file from the temp path we just wrote, so nothing large crosses the
+    // thread boundary. The semaphore still bounds concurrency — now the number
+    // of live Workers, hence the native memory across them — and sheds load as
+    // `busy` rather than spawning an unbounded number of them.
+    //
+    // The cover gate is not optional: `coverPath IS NOT NULL` is the only signal
+    // driving `coverUrl` on the web library, the OPDS feed and the XRPC book
+    // view, so storing an unvalidated cover produces a dead URL and a blank box
+    // in all three.
+    let metadata: BookMetadata;
+    let cover: BookCover | undefined;
+    try {
+      ({ metadata, cover } = await parseSemaphore.run(() =>
+        parseBookInWorker(tmp, filename, formatInfo),
+      ));
+    } catch (err) {
+      if (err instanceof SemaphoreFullError || err instanceof SemaphoreTimeoutError) {
+        return { ok: false, reason: "busy" };
+      }
+      throw err;
+    }
+
+    // ── 8. Link, then insert under quota ──
+    const uploadFilenameHash = koreaderFilenameHash(filename);
+    const uploadFilenameKey = filenameKey(filename);
+
+    // Exact first, fuzzy only on a miss. The XRPC path used to run the fuzzy
+    // matcher first, which let a title/author guess beat a byte-exact
+    // documentHash match — strictly wrong, and it paid for up to four FTS
+    // queries on the common path where the exact lookup would have answered.
+    let hiveId = await findExactSyncLink(
+      db,
+      userDid,
+      contentHash,
+      uploadFilenameHash,
+      uploadFilenameKey,
+    );
+    if (!hiveId) {
+      hiveId = await matchSyncDocument(db, {
+        title: metadata.title,
+        authors: metadata.authors,
+        filename,
+      });
+    }
+
+    const now = new Date().toISOString();
+    const filePath = bookFilePath(userDid, contentHash, formatInfo.ext);
+    const coverPath = cover ? coverFilePath(userDid, contentHash, cover.ext) : null;
+
+    const inserted = await insertIfUnderQuota(
+      db,
+      {
+        userDid,
+        contentHash,
+        hiveId,
+        filename,
+        filenameHash: uploadFilenameHash,
+        filenameKey: uploadFilenameKey,
+        title: metadata.title,
+        // `parseBook` returns "" on every fallback. Normalise to NULL so
+        // `WHERE authors IS NULL` means what it looks like it means — the two
+        // are identical to JS truthiness and completely different to SQL.
+        authors: metadata.authors || null,
+        language: metadata.language || null,
+        format: formatInfo.format,
+        mime: formatInfo.mime,
+        filePath,
+        coverPath,
+        coverMime: cover?.mime ?? null,
+        sizeBytes: size,
+        createdAt: now,
+        updatedAt: now,
+      },
+      quotaBytes,
+    );
+    if (inserted === "duplicate") return { ok: false, reason: "duplicate", contentHash };
+    if (inserted === "over-quota") {
+      const used = await getStorageUsage(db, userDid);
+      return { ok: false, reason: "quota-exceeded", usedBytes: used, quotaBytes, fileBytes: size };
+    }
+
+    // ── 9. Commit the bytes: rename, not copy ──
+    await ensureDir(personalBookDir(userDid, contentHash));
+    try {
+      await rename(tmp, filePath);
+    } catch (err) {
+      // The row committed in step 8, before the bytes moved. A rename failure
+      // here would otherwise leave a personal_book row with no file behind it —
+      // a dead download and phantom quota usage. Roll the row back before
+      // rethrowing; the `finally` still unlinks the temp file.
+      await db
+        .deleteFrom("personal_book")
+        .where("userDid", "=", userDid)
+        .where("contentHash", "=", contentHash)
+        .execute();
+      throw err;
+    }
+
+    // The row is already committed, so a failed cover write must not fail the
+    // upload — the book itself is fine. But it must not leave `coverPath` set
+    // either: that column is the only signal driving `coverUrl` on the web
+    // library, the OPDS feed and the XRPC book view, so a path with no file
+    // behind it is a dead URL and a blank box in all three.
+    let coverStored = Boolean(cover && coverPath);
+    if (cover && coverPath) {
+      try {
+        await Bun.write(coverPath, cover.bytes);
+      } catch {
+        coverStored = false;
+        await db
+          .updateTable("personal_book")
+          .set({ coverPath: null, coverMime: null })
+          .where("userDid", "=", userDid)
+          .where("contentHash", "=", contentHash)
+          .execute();
+      }
+    }
+
+    // ── 10. Propagate the link outward ──
+    if (hiveId) {
+      // Any document the device has been pushing progress for that never
+      // matched now points at this book — so the next push bridges instead of
+      // being dropped.
+      const linked = await db
+        .selectFrom("sync_document")
+        .select(["id", "progressData"])
+        .where("userDid", "=", userDid)
+        .where("hiveId", "is", null)
+        .where((eb) =>
+          eb.or([
+            eb("documentHash", "=", contentHash),
+            ...(uploadFilenameHash ? [eb("documentHash", "=", uploadFilenameHash)] : []),
+            ...(uploadFilenameKey ? [eb("filenameKey", "=", uploadFilenameKey)] : []),
+          ]),
+        )
+        .execute();
+
+      if (linked.length > 0) {
+        await db
+          .updateTable("sync_document")
+          .set({ hiveId })
+          .where(
+            "id",
+            "in",
+            linked.map((d) => d.id),
+          )
+          .execute();
+
+        // The percentage those documents already recorded has been sitting
+        // unused; without this it stays that way until the device next syncs.
+        for (const doc of linked) {
+          const pct = progressPercentage(doc.progressData);
+          if (pct !== null) await bridgeProgressToUserBook(db, kv, userDid, hiveId, pct);
+        }
+      }
+
+      await db
+        .updateTable("user_book")
+        .set({ owned: 1 })
+        .where("userDid", "=", userDid)
+        .where("hiveId", "=", hiveId)
+        .where("owned", "=", 0)
+        .execute();
+    }
+
+    return {
+      ok: true,
+      book: {
+        contentHash,
+        title: metadata.title,
+        authors: metadata.authors || undefined,
+        language: metadata.language || undefined,
+        format: formatInfo.format,
+        mime: formatInfo.mime,
+        sizeBytes: size,
+        createdAt: now,
+        updatedAt: now,
+        hiveId: hiveId ?? undefined,
+        coverUrl: coverStored ? `/library/covers/${contentHash}` : undefined,
+      },
+      storageUsedBytes: await getStorageUsage(db, userDid),
+      storageQuotaBytes: quotaBytes,
+    };
+  } finally {
+    // No-op once the rename has happened; the safety net for every path that
+    // returns before it.
+    await rm(tmp, { force: true });
+  }
+}
+
+/**
+ * Delete `.part` files left behind by a process that died between the write and
+ * the rename. Runs on the primary worker at startup; an hour is well past any
+ * live upload (the parse semaphore times out at 30s).
+ */
+export async function sweepStaleUploads(maxAgeMs = 60 * 60 * 1000): Promise<number> {
+  const tmpDir = getLibraryTmpDir();
+  let names: string[];
+  try {
+    names = await readdir(tmpDir);
+  } catch {
+    return 0; // never uploaded anything on this host
+  }
+  const cutoff = Date.now() - maxAgeMs;
+  let removed = 0;
+  for (const name of names) {
+    if (!name.endsWith(".part")) continue;
+    const full = path.join(tmpDir, name);
+    try {
+      const info = await stat(full);
+      if (info.mtimeMs < cutoff) {
+        await rm(full, { force: true });
+        removed++;
+      }
+    } catch {
+      /* raced with another sweep or the upload itself */
+    }
+  }
+  return removed;
+}
diff --git a/src/workers/parse-client.ts b/src/workers/parse-client.ts
new file mode 100644
index 0000000..2c034be
--- /dev/null
+++ b/src/workers/parse-client.ts
@@ -0,0 +1,63 @@
+/// Main-thread side of the single-shot ebook parse Worker.
+
+import { randomUUID } from "node:crypto";
+import type { BookCover, BookMetadata, FormatInfo } from "../utils/bookMetadata/index";
+import type { ParseRequest, ParseResponse } from "./parse-messages";
+
+// When running the Nitro bundle (.output/server/index.mjs) load the pre-built
+// worker; in dev load the TS entry directly. Same idiom as every other worker.
+const isBundled = import.meta.url.includes(".output/");
+const WORKER_URL = isBundled
+  ? new URL("./workers/parse-worker.js", import.meta.url).href
+  : new URL("./parse-worker.ts", import.meta.url).href;
+
+/**
+ * Hard ceiling on one parse. Generous: a 100 MB unzip plus an SVG raster is well
+ * under this, and the upload's parse semaphore already limits how many run. A
+ * blown deadline terminates the Worker rather than hanging the request.
+ */
+const PARSE_TIMEOUT_MS = 60_000;
+
+export type ParsedBook = { metadata: BookMetadata; cover: BookCover | undefined };
+
+/**
+ * Parse an ebook in a throwaway Worker, reading it from `path` (already on
+ * disk). The Worker is terminated on every path — a fresh VM per upload is how
+ * the whole-file buffer is shed without a long-lived pool.
+ */
+export function parseBookInWorker(
+  path: string,
+  filename: string,
+  formatInfo: FormatInfo,
+): Promise<ParsedBook> {
+  const worker = new Worker(WORKER_URL);
+  const id = randomUUID();
+
+  return new Promise<ParsedBook>((resolve, reject) => {
+    let settled = false;
+    const finish = (fn: () => void) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      worker.terminate();
+      fn();
+    };
+
+    const timer = setTimeout(
+      () => finish(() => reject(new Error("ebook parse timed out"))),
+      PARSE_TIMEOUT_MS,
+    );
+
+    worker.onmessage = (event: MessageEvent<ParseResponse>) => {
+      const res = event.data;
+      if (res.id !== id) return; // ignore a stale reply from a worker we gave up on
+      if (res.ok) finish(() => resolve({ metadata: res.metadata, cover: res.cover }));
+      else finish(() => reject(new Error(res.error)));
+    };
+    worker.onerror = (error) => {
+      finish(() => reject(new Error(`parse worker error: ${error.message}`)));
+    };
+
+    worker.postMessage({ id, path, filename, formatInfo } satisfies ParseRequest);
+  });
+}
diff --git a/src/workers/parse-messages.ts b/src/workers/parse-messages.ts
new file mode 100644
index 0000000..7c966f8
--- /dev/null
+++ b/src/workers/parse-messages.ts
@@ -0,0 +1,18 @@
+/// Message contract between the upload path and the single-shot parse Worker
+/// (`parse-worker.ts` / `parse-client.ts`). Only a file path crosses in; the
+/// parsed metadata and the (already-rasterized, <=8 MB) cover cross back.
+
+import type { BookCover, BookMetadata, FormatInfo } from "../utils/bookMetadata/index";
+
+export type ParseRequest = {
+  id: string;
+  /** Absolute path to the on-disk upload; the Worker reads it with `Bun.file`. */
+  path: string;
+  filename: string;
+  /** Already derived from the file head on the main thread — no need to re-sniff. */
+  formatInfo: FormatInfo;
+};
+
+export type ParseResponse =
+  | { id: string; ok: true; metadata: BookMetadata; cover: BookCover | undefined }
+  | { id: string; ok: false; error: string };
diff --git a/src/workers/parse-worker.ts b/src/workers/parse-worker.ts
new file mode 100644
index 0000000..330ee7f
--- /dev/null
+++ b/src/workers/parse-worker.ts
@@ -0,0 +1,41 @@
+/// Ebook metadata parse — runs off the main thread as a single-shot Bun Worker.
+///
+/// `parseBook` (fflate `unzipSync`) and `prepareCover` (SVG rasterization via
+/// `resvg`, which renders synchronously) are the only CPU-bound, whole-file
+/// steps of an upload. Running them here keeps a 100 MB unzip or a synchronous
+/// raster from stalling the request process's event loop.
+///
+/// One Worker is spawned per upload and terminated by the caller on every path
+/// (`parseBookInWorker` in `parse-client.ts`); the upload's parse semaphore
+/// still bounds how many run at once, so at most UPLOAD_PARSE_CONCURRENCY of
+/// these exist per process. The file is read here from its path — the caller
+/// already streamed it to disk, so only a path crosses in.
+
+import { parseBook, prepareCover } from "../utils/bookMetadata/index";
+import type { ParseRequest, ParseResponse } from "./parse-messages";
+
+declare var self: Worker;
+
+self.onmessage = async (event: MessageEvent<ParseRequest>) => {
+  const { id, path, filename, formatInfo } = event.data;
+  try {
+    const bytes = new Uint8Array(await Bun.file(path).arrayBuffer());
+    const metadata = parseBook(bytes, filename, formatInfo);
+    const cover = (await prepareCover(metadata.cover)) ?? undefined;
+    // Drop the raw parsed cover: `prepareCover` already produced the one we
+    // keep, and shipping the un-rasterized original back would double the bytes
+    // crossing the boundary for nothing.
+    self.postMessage({
+      id,
+      ok: true,
+      metadata: { ...metadata, cover: undefined },
+      cover,
+    } satisfies ParseResponse);
+  } catch (error) {
+    self.postMessage({
+      id,
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    } satisfies ParseResponse);
+  }
+};
diff --git a/src/xrpc/auth.test.ts b/src/xrpc/auth.test.ts
new file mode 100644
index 0000000..07a43f6
--- /dev/null
+++ b/src/xrpc/auth.test.ts
@@ -0,0 +1,301 @@
+/**
+ * Service auth on /xrpc/*.
+ *
+ * The verifier is NOT stubbed — a stubbed one would test nothing, and the
+ * negative cases (wrong audience, wrong lxm, expired, tampered signature) are
+ * the entire point. Instead a real `ServiceJwtVerifier` runs against a real
+ * `createServiceJwt`-signed token, with a static one-method `DidDocumentResolver`
+ * standing in for the network. That exercises every check the production path
+ * runs, deterministically and offline.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { Database as DatabaseSync } from "bun:sqlite";
+import { Hono } from "hono";
+import { Kysely, SqliteDialect } from "kysely";
+import { createStorage } from "unstorage";
+import memoryDriver from "unstorage/drivers/memory";
+import { rm } from "node:fs/promises";
+import path from "node:path";
+import type { Storage } from "unstorage";
+import { P256PrivateKeyExportable } from "@atcute/crypto";
+import { ServiceJwtVerifier, createServiceJwt } from "@atcute/xrpc-server/auth";
+import type { Did, Nsid } from "@atcute/lexicons";
+
+import { wrapBunSqliteForKysely } from "../bun-sqlite-kysely";
+import type { AppContext, AppEnv } from "../context";
+import { migrateToLatest, type DatabaseSchema, type Database } from "../db";
+import { makeEpub } from "../utils/bookMetadata/testFixtures";
+import { personalBookDir } from "../utils/personalLibrary";
+import { createXrpcRouter, type XrpcContext } from "./router";
+
+const DID = "did:plc:testuser" as Did;
+const STRANGER = "did:plc:neverheardofthem" as Did;
+const SERVICE_DID = "did:plc:enu2j5xjlqsjaylv3du4myh4" as Did;
+
+let db: Database;
+let kv: Storage;
+let keypair: P256PrivateKeyExportable;
+let strangerKeypair: P256PrivateKeyExportable;
+
+async function createTestDb(): Promise<Database> {
+  const sqlite = new DatabaseSync(":memory:");
+  sqlite.exec("PRAGMA journal_mode = WAL");
+  const database = new Kysely<DatabaseSchema>({
+    dialect: new SqliteDialect({ database: wrapBunSqliteForKysely(sqlite) }),
+  });
+  await migrateToLatest(database, sqlite);
+  return database;
+}
+
+/** A DID document carrying the given key as its `#atproto` verification method. */
+async function didDocFor(did: Did, key: P256PrivateKeyExportable) {
+  return {
+    id: did,
+    verificationMethod: [
+      {
+        id: `${did}#atproto`,
+        type: "Multikey",
+        controller: did,
+        publicKeyMultibase: await key.exportPublicKey("multikey"),
+      },
+    ],
+  };
+}
+
+/** Resolves both test identities; the network is never touched. */
+async function staticResolver() {
+  const docs = new Map<string, unknown>([
+    [DID, await didDocFor(DID, keypair)],
+    [STRANGER, await didDocFor(STRANGER, strangerKeypair)],
+  ]);
+  return {
+    resolve: async (did: string) => {
+      const doc = docs.get(did);
+      if (!doc) throw new Error(`no did doc for ${did}`);
+      return doc;
+    },
+  };
+}
+
+async function createApp(opts: { audiences?: string[]; maxAge?: number; enabled?: boolean } = {}) {
+  const resolver = await staticResolver();
+  const verifier =
+    opts.enabled === false
+      ? null
+      : new ServiceJwtVerifier({
+          acceptAudiences: (opts.audiences ?? [SERVICE_DID]) as Did[],
+          resolver: resolver as never,
+          maxAge: opts.maxAge ?? 3600,
+        });
+
+  const app = new Hono<AppEnv>();
+  app.use("*", async (c, next) => {
+    c.set("ctx", {
+      db,
+      kv,
+      resolver: { resolveDidsToHandles: async () => ({}) },
+      // No cookie session: these tests are exclusively about the Bearer path.
+      getSessionAgent: async () => null,
+      baseIdResolver: { handle: { resolve: async () => undefined } },
+      addWideEventContext: () => {},
+      serviceJwtVerifier: verifier,
+    } as unknown as AppContext);
+    await next();
+  });
+  createXrpcRouter<XrpcContext>(
+    app as never,
+    {
+      searchBooks: async () => [],
+      ensureBookIdentifiersCurrent: async () => {},
+      getProfile: async () => null,
+    } as never,
+  );
+  return app;
+}
+
+function token(
+  opts: {
+    lxm?: string;
+    audience?: string;
+    issuer?: Did;
+    key?: P256PrivateKeyExportable;
+    expiresIn?: number;
+    issuedAt?: number;
+  } = {},
+) {
+  return createServiceJwt({
+    keypair: opts.key ?? keypair,
+    issuer: opts.issuer ?? DID,
+    audience: (opts.audience ?? SERVICE_DID) as Did,
+    lxm: (opts.lxm ?? "buzz.bookhive.listPersonalShelves") as Nsid,
+    ...(opts.expiresIn !== undefined ? { expiresIn: opts.expiresIn } : {}),
+    ...(opts.issuedAt !== undefined ? { issuedAt: opts.issuedAt } : {}),
+  });
+}
+
+beforeEach(async () => {
+  db = await createTestDb();
+  kv = createStorage({ driver: memoryDriver() });
+  keypair = await P256PrivateKeyExportable.createKeypair();
+  strangerKeypair = await P256PrivateKeyExportable.createKeypair();
+});
+
+afterEach(async () => {
+  await rm(path.dirname(personalBookDir(DID, "x")), { recursive: true, force: true }).catch(
+    () => {},
+  );
+});
+
+describe("service auth — the happy path", () => {
+  it("authenticates a query with a Bearer service token", async () => {
+    const app = await createApp();
+    const res = await app.request("/xrpc/buzz.bookhive.listPersonalShelves", {
+      headers: { authorization: `Bearer ${await token()}` },
+    });
+    expect(res.status).toBe(200);
+    expect((await res.json()) as { totalBooks: number }).toHaveProperty("totalBooks", 0);
+  });
+
+  it("authenticates an upload, the whole point of the feature", async () => {
+    const app = await createApp();
+    const bytes = makeEpub({ title: "Dune" });
+    const res = await app.request("/xrpc/buzz.bookhive.uploadPersonalBook?filename=Dune.epub", {
+      method: "POST",
+      body: bytes as BodyInit,
+      headers: {
+        authorization: `Bearer ${await token({ lxm: "buzz.bookhive.uploadPersonalBook" })}`,
+        "content-type": "application/epub+zip",
+        "content-length": String(bytes.length),
+      },
+    });
+    expect(res.status).toBe(200);
+
+    // And the row landed under the token's issuer, not some other DID.
+    const row = await db
+      .selectFrom("personal_book")
+      .select(["userDid", "title"])
+      .executeTakeFirstOrThrow();
+    expect(row.userDid).toBe(DID);
+    expect(row.title).toBe("Dune");
+  });
+
+  it("accepts the #fragment audience form as well as the bare DID", async () => {
+    // atcute compares audiences by exact string, so both spellings must be
+    // listed. This is what will keep clients working when the DID document
+    // gains a #bookhive_appview service entry.
+    const app = await createApp({ audiences: [SERVICE_DID, `${SERVICE_DID}#bookhive_appview`] });
+    const res = await app.request("/xrpc/buzz.bookhive.listPersonalShelves", {
+      headers: {
+        authorization: `Bearer ${await token({ audience: `${SERVICE_DID}#bookhive_appview` })}`,
+      },
+    });
+    expect(res.status).toBe(200);
+  });
+});
+
+describe("service auth — rejections", () => {
+  const cases: { name: string; make: () => Promise<string>; lxm?: string }[] = [
+    {
+      name: "a token minted for a different audience",
+      make: () => token({ audience: "did:web:someone-else.example" }),
+    },
+    {
+      name: "a token bound to a different method",
+      make: () => token({ lxm: "buzz.bookhive.getPersonalLibrary" }),
+    },
+    {
+      name: "an expired token",
+      make: () => token({ issuedAt: Math.floor(Date.now() / 1000) - 600, expiresIn: 60 }),
+    },
+    {
+      name: "a token signed by the wrong key",
+      // Issued as DID, but signed with the stranger's key — the DID document
+      // for DID carries a different public key, so the signature can't verify.
+      make: () => token({ key: strangerKeypair }),
+    },
+  ];
+
+  for (const c of cases) {
+    it(`401s ${c.name}`, async () => {
+      const app = await createApp();
+      const res = await app.request("/xrpc/buzz.bookhive.listPersonalShelves", {
+        headers: { authorization: `Bearer ${await c.make()}` },
+      });
+      expect(res.status).toBe(401);
+    });
+  }
+
+  it("401s a token whose signature does not cover its payload", async () => {
+    // Splice a *different* token's signature onto this one's header+payload.
+    // Deliberately not "flip the last base64url character": that char carries
+    // padding bits, so flipping it can decode to the identical signature bytes
+    // and the token still verifies — which made this test flaky.
+    const app = await createApp();
+    const [header, payload] = (await token()).split(".");
+    const [, , otherSig] = (await token({ key: strangerKeypair })).split(".");
+    const forged = `${header}.${payload}.${otherSig}`;
+
+    const res = await app.request("/xrpc/buzz.bookhive.listPersonalShelves", {
+      headers: { authorization: `Bearer ${forged}` },
+    });
+    expect(res.status).toBe(401);
+  });
+
+  it("401s a token older than the configured max-age window", async () => {
+    const app = await createApp({ maxAge: 300 });
+    const res = await app.request("/xrpc/buzz.bookhive.listPersonalShelves", {
+      headers: { authorization: `Bearer ${await token({ expiresIn: 3600 })}` },
+    });
+    expect(res.status).toBe(401);
+  });
+
+  it("accepts a valid token from any DID, including one that has never used BookHive", async () => {
+    // There is no prior-relationship gate: a valid token is sufficient, and the
+    // per-user storage quota is the backstop on what a caller can consume.
+    const app = await createApp();
+    const res = await app.request("/xrpc/buzz.bookhive.listPersonalShelves", {
+      headers: {
+        authorization: `Bearer ${await token({ issuer: STRANGER, key: strangerKeypair })}`,
+      },
+    });
+    expect(res.status).toBe(200);
+    expect((await res.json()) as { totalBooks: number }).toHaveProperty("totalBooks", 0);
+  });
+
+  it("401s garbage in the Authorization header", async () => {
+    const app = await createApp();
+    const res = await app.request("/xrpc/buzz.bookhive.listPersonalShelves", {
+      headers: { authorization: "Bearer not-a-jwt" },
+    });
+    expect(res.status).toBe(401);
+  });
+
+  it("401s when service auth is disabled", async () => {
+    const app = await createApp({ enabled: false });
+    const res = await app.request("/xrpc/buzz.bookhive.listPersonalShelves", {
+      headers: { authorization: `Bearer ${await token()}` },
+    });
+    expect(res.status).toBe(401);
+    expect(((await res.json()) as { message: string }).message).toContain("not enabled");
+  });
+});
+
+describe("service auth — what it deliberately cannot do", () => {
+  it("refuses a method that writes to the user's repo", async () => {
+    // `createList` puts a record in the caller's repository, which needs an
+    // OAuth grant. A service token proves key control, not that we hold one.
+    const app = await createApp();
+    const res = await app.request("/xrpc/buzz.bookhive.createList", {
+      method: "POST",
+      body: JSON.stringify({ name: "Sci-Fi" }),
+      headers: {
+        authorization: `Bearer ${await token({ lxm: "buzz.bookhive.createList" })}`,
+        "content-type": "application/json",
+      },
+    });
+    expect(res.status).toBe(401);
+    const message = ((await res.json()) as { message: string }).message;
+    expect(message).toContain("OAuth session");
+  });
+});
diff --git a/src/xrpc/auth.ts b/src/xrpc/auth.ts
new file mode 100644
index 0000000..5f9c156
--- /dev/null
+++ b/src/xrpc/auth.ts
@@ -0,0 +1,87 @@
+/**
+ * Authentication for `/xrpc/*`.
+ *
+ * Two credentials are accepted:
+ *
+ * - The `sid` iron-session cookie, which is what the web app and the iOS app
+ *   have always used.
+ * - An **atproto inter-service auth JWT** as `Authorization: Bearer <token>` —
+ *   https://atproto.com/specs/xrpc#inter-service-authentication-jwt. The client
+ *   asks its own PDS for a token via `com.atproto.server.getServiceAuth`,
+ *   bound to an audience (us) and an `lxm` (the one method it wants to call);
+ *   the PDS signs it with the account's repo signing key, and we verify it by
+ *   resolving the issuer's DID document. This is the canonical mechanism for a
+ *   third-party service exposing its own XRPC methods, and it is what makes the
+ *   personal library reachable from a script or an e-reader rather than only
+ *   from a browser session.
+ *
+ * The one thing service auth cannot do is write to the user's repo: it proves
+ * control of a signing key, not that we hold an OAuth grant for that account.
+ * `AuthMode` is how a method declares which it needs.
+ */
+
+import { AuthRequiredError } from "@atcute/xrpc-server";
+import type { ServiceJwtVerifier } from "@atcute/xrpc-server/auth";
+import type { Nsid } from "@atcute/lexicons";
+import type { SessionClient } from "../auth/client";
+
+/**
+ * What a method requires of its caller.
+ *
+ * `identity` — we only need to know *who* they are. Every personal-library and
+ *   sync method is in this class: none of them touch the session agent for
+ *   anything but `.did` (progress bridging writes `user_book` and queues a
+ *   deferred PDS write via `sync_pending:`, rather than writing inline).
+ * `pdsWrite` — the handler puts a record in the user's repository, which needs
+ *   a live OAuth session. Only the book-list procedures are in this class.
+ */
+export type AuthMode = "identity" | "pdsWrite";
+
+export type XrpcAuth =
+  | { did: string; method: "session"; agent: SessionClient }
+  | { did: string; method: "service"; agent: null };
+
+export type XrpcAuthContext = {
+  getSessionAgent: () => Promise<SessionClient | null>;
+  serviceJwtVerifier?: ServiceJwtVerifier | null;
+};
+
+export async function resolveXrpcAuth(
+  ctx: XrpcAuthContext,
+  request: Request,
+  opts: { lxm: Nsid; mode: AuthMode },
+): Promise<XrpcAuth> {
+  const authorization = request.headers.get("authorization");
+
+  // Bearer wins when both are somehow present: a browser never sends one and a
+  // programmatic client never has our cookie, so a request carrying both is
+  // stating its intent.
+  if (authorization !== null && /^bearer\s/i.test(authorization)) {
+    if (!ctx.serviceJwtVerifier) {
+      throw new AuthRequiredError({ message: "Service auth is not enabled on this server" });
+    }
+    if (opts.mode === "pdsWrite") {
+      throw new AuthRequiredError({
+        message:
+          `${opts.lxm} writes a record to your repository, which needs an OAuth session; ` +
+          `service auth cannot provide one. Sign in at bookhive.buzz to use this method.`,
+      });
+    }
+
+    // Throws AuthRequiredError (401, with a WWW-Authenticate: Bearer challenge)
+    // on every failure path: missing or malformed token, bad signature, wrong
+    // audience, wrong lxm, expired, outside the max-age window, or replayed.
+    //
+    // A valid token proves control of an atproto identity, nothing more — any
+    // DID on the network is accepted. The per-user storage quota is the backstop
+    // on what a caller can consume; BookHive signup is open, so gating this on a
+    // prior sign-in bought little and is deliberately not done.
+    const { issuer } = await ctx.serviceJwtVerifier.verifyRequest(request, { lxm: opts.lxm });
+
+    return { did: issuer, method: "service", agent: null };
+  }
+
+  const agent = await ctx.getSessionAgent();
+  if (!agent) throw new AuthRequiredError({ message: "Authentication required" });
+  return { did: agent.did, method: "session", agent };
+}
diff --git a/src/xrpc/personalLibrary.test.ts b/src/xrpc/personalLibrary.test.ts
new file mode 100644
index 0000000..a7c1320
--- /dev/null
+++ b/src/xrpc/personalLibrary.test.ts
@@ -0,0 +1,550 @@
+/**
+ * The first tests of `src/xrpc/router.ts`.
+ *
+ * Scoped to the personal-library methods rather than named `router.test.ts`:
+ * that file is 2000+ lines and 40 methods, and one suite per region stays
+ * reviewable (and signposts `src/xrpc/lists.test.ts` for whoever needs it next).
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { Database as DatabaseSync } from "bun:sqlite";
+import { Hono } from "hono";
+import { Kysely, SqliteDialect } from "kysely";
+import { createStorage } from "unstorage";
+import memoryDriver from "unstorage/drivers/memory";
+import { readdir, rm } from "node:fs/promises";
+import path from "node:path";
+import type { Storage } from "unstorage";
+
+import { wrapBunSqliteForKysely } from "../bun-sqlite-kysely";
+import type { AppContext, AppEnv } from "../context";
+import { migrateToLatest, type DatabaseSchema, type Database } from "../db";
+import { koreaderPartialMD5 } from "../utils/bookMetadata/index";
+import { makeEpub, makeFb2 } from "../utils/bookMetadata/testFixtures";
+import {
+  bookFilePath,
+  getLibraryTmpDir,
+  getStorageQuota,
+  personalBookDir,
+} from "../utils/personalLibrary";
+import { createXrpcRouter, type XrpcContext } from "./router";
+
+const DID = "did:plc:testuser";
+const OTHER_DID = "did:plc:someoneelse";
+
+type TestApp = Hono<AppEnv>;
+
+let db: Database;
+let kv: Storage;
+let wideEvent: Record<string, unknown>;
+
+async function createTestDb(): Promise<Database> {
+  const sqlite = new DatabaseSync(":memory:");
+  sqlite.exec("PRAGMA journal_mode = WAL");
+  const database = new Kysely<DatabaseSchema>({
+    dialect: new SqliteDialect({ database: wrapBunSqliteForKysely(sqlite) }),
+  });
+  await migrateToLatest(database, sqlite);
+  return database;
+}
+
+function createApp(did: string | null = DID): TestApp {
+  const app = new Hono<AppEnv>();
+  app.use("*", async (c, next) => {
+    c.set("ctx", {
+      db,
+      kv,
+      resolver: { resolveDidsToHandles: async () => ({}) },
+      getSessionAgent: async () => (did ? { did } : null),
+      baseIdResolver: { handle: { resolve: async () => undefined } },
+      addWideEventContext: (fields: Record<string, unknown>) => Object.assign(wideEvent, fields),
+    } as unknown as AppContext);
+    await next();
+  });
+  createXrpcRouter<XrpcContext>(
+    app as never,
+    {
+      searchBooks: async () => [],
+      ensureBookIdentifiersCurrent: async () => {},
+      getProfile: async () => null,
+    } as never,
+  );
+  return app;
+}
+
+/** POST an ebook as a raw body, the way a programmatic client would. */
+function uploadRequest(
+  app: TestApp,
+  bytes: Uint8Array,
+  filename: string,
+  init: { contentType?: string; contentLength?: boolean } = {},
+) {
+  const headers: Record<string, string> = {
+    "content-type": init.contentType ?? "application/epub+zip",
+  };
+  if (init.contentLength !== false) headers["content-length"] = String(bytes.length);
+  return app.request(
+    `/xrpc/buzz.bookhive.uploadPersonalBook?filename=${encodeURIComponent(filename)}`,
+    { method: "POST", body: bytes as BodyInit, headers },
+  );
+}
+
+async function tmpEntries(): Promise<string[]> {
+  try {
+    return (await readdir(getLibraryTmpDir())).filter((n) => n.endsWith(".part"));
+  } catch {
+    return [];
+  }
+}
+
+beforeEach(async () => {
+  db = await createTestDb();
+  kv = createStorage({ driver: memoryDriver() });
+  wideEvent = {};
+});
+
+afterEach(async () => {
+  for (const did of [DID, OTHER_DID]) {
+    await rm(path.dirname(personalBookDir(did, "x")), { recursive: true, force: true }).catch(
+      () => {},
+    );
+  }
+  for (const name of await tmpEntries()) {
+    await rm(path.join(getLibraryTmpDir(), name), { force: true });
+  }
+});
+
+describe("XRPC uploadPersonalBook", () => {
+  it("accepts a raw ebook body and stores it", async () => {
+    const app = createApp();
+    const bytes = makeEpub({ title: "Dune", authors: ["Frank Herbert"] });
+
+    const res = await uploadRequest(app, bytes, "Dune.epub");
+    expect(res.status).toBe(200);
+
+    const body = (await res.json()) as {
+      book: { contentHash: string; title: string; authors?: string; sizeBytes: number };
+      storageUsedBytes: number;
+      storageQuotaBytes: number;
+    };
+    expect(body.book.title).toBe("Dune");
+    expect(body.book.authors).toBe("Frank Herbert");
+    expect(body.book.sizeBytes).toBe(bytes.length);
+    expect(body.book.contentHash).toBe(koreaderPartialMD5(bytes));
+    expect(body.storageUsedBytes).toBe(bytes.length);
+    expect(body.storageQuotaBytes).toBe(getStorageQuota());
+
+    expect(await Bun.file(bookFilePath(DID, body.book.contentHash, "epub")).exists()).toBe(true);
+    expect(await tmpEntries()).toEqual([]);
+  });
+
+  it("accepts application/octet-stream, which is what real clients send", async () => {
+    // Mobile document pickers and `curl --data-binary` both report this; the
+    // lexicon's MIME list documents intent, but detectFormat is the real gate.
+    const res = await uploadRequest(createApp(), makeEpub(), "x.epub", {
+      contentType: "application/octet-stream",
+    });
+    expect(res.status).toBe(200);
+  });
+
+  it("rejects a content type outside the lexicon's list before the handler runs", async () => {
+    const res = await uploadRequest(createApp(), makeEpub(), "x.epub", {
+      contentType: "application/json",
+    });
+    expect(res.status).toBe(400);
+    expect(((await res.json()) as { error: string }).error).toBe("InvalidRequest");
+  });
+
+  it("requires the filename parameter", async () => {
+    const app = createApp();
+    const res = await app.request("/xrpc/buzz.bookhive.uploadPersonalBook", {
+      method: "POST",
+      body: makeEpub() as BodyInit,
+      headers: { "content-type": "application/epub+zip" },
+    });
+    expect(res.status).toBe(400);
+  });
+
+  it("uses the filename to tell zip containers apart", async () => {
+    // An EPUB and a CBZ are both zip archives; only the extension distinguishes
+    // them, which is why `filename` is required rather than a header.
+    const app = createApp();
+    const res = await uploadRequest(app, makeEpub(), "book.cbz", {
+      contentType: "application/vnd.comicbook+zip",
+    });
+    expect(res.status).toBe(200);
+    expect(((await res.json()) as { book: { format: string } }).book.format).toBe("cbz");
+  });
+
+  it("401s without a session", async () => {
+    const res = await uploadRequest(createApp(null), makeEpub(), "x.epub");
+    expect(res.status).toBe(401);
+  });
+
+  it("409s a duplicate", async () => {
+    const app = createApp();
+    const bytes = makeEpub();
+    expect((await uploadRequest(app, bytes, "x.epub")).status).toBe(200);
+
+    const res = await uploadRequest(app, bytes, "x.epub");
+    expect(res.status).toBe(409);
+    expect(((await res.json()) as { error: string }).error).toBe("AlreadyExists");
+  });
+
+  it("400s an unsupported format", async () => {
+    const res = await uploadRequest(
+      createApp(),
+      new TextEncoder().encode("plain text, not a book"),
+      "notes.epub",
+    );
+    expect(res.status).toBe(400);
+    expect(((await res.json()) as { error: string }).error).toBe("InvalidRequest");
+  });
+
+  it("413s when the upload would cross the storage quota", async () => {
+    const bytes = makeEpub();
+    await db
+      .insertInto("personal_book")
+      .values({
+        userDid: DID,
+        contentHash: "seeded",
+        filename: "seeded.epub",
+        title: "Seeded",
+        format: "epub",
+        mime: "application/epub+zip",
+        filePath: "/tmp/seeded.epub",
+        sizeBytes: getStorageQuota() - bytes.length + 1,
+        createdAt: "2026-08-01T00:00:00.000Z",
+        updatedAt: "2026-08-01T00:00:00.000Z",
+      })
+      .execute();
+
+    const res = await uploadRequest(createApp(), bytes, "x.epub");
+    expect(res.status).toBe(413);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toBe("QuotaExceeded");
+    expect(await tmpEntries()).toEqual([]);
+  });
+
+  it("records a deliberate 4xx on the wide event without a stack", async () => {
+    // The registration wrapper decides this from `status < 500`, and nothing
+    // covered it before.
+    await uploadRequest(createApp(), new TextEncoder().encode("nope"), "x.epub");
+    expect(wideEvent["xrpc_handler"]).toBe("threw");
+    const error = wideEvent["error"] as { message?: string; stack?: string } | undefined;
+    expect(error?.message).toBeTruthy();
+    expect(error?.stack).toBeUndefined();
+  });
+
+  it("keeps two users' identical uploads separate", async () => {
+    const bytes = makeFb2();
+    expect(
+      (
+        await uploadRequest(createApp(DID), bytes, "x.fb2", {
+          contentType: "application/x-fictionbook+xml",
+        })
+      ).status,
+    ).toBe(200);
+    expect(
+      (
+        await uploadRequest(createApp(OTHER_DID), bytes, "x.fb2", {
+          contentType: "application/x-fictionbook+xml",
+        })
+      ).status,
+    ).toBe(200);
+
+    const rows = await db.selectFrom("personal_book").select(["userDid"]).execute();
+    expect(rows.map((r) => r.userDid).sort()).toEqual([OTHER_DID, DID].sort());
+  });
+
+  it("streams a body with no content-length", async () => {
+    const res = await uploadRequest(createApp(), makeEpub(), "x.epub", { contentLength: false });
+    expect(res.status).toBe(200);
+  });
+});
+
+describe("XRPC getPersonalBookFile", () => {
+  it("serves the stored bytes with download headers", async () => {
+    const app = createApp();
+    const bytes = makeEpub();
+    const hash = (
+      (await (await uploadRequest(app, bytes, "Dune.epub")).json()) as {
+        book: { contentHash: string };
+      }
+    ).book.contentHash;
+
+    const res = await app.request(`/xrpc/buzz.bookhive.getPersonalBookFile?contentHash=${hash}`);
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toBe("application/epub+zip");
+    expect(res.headers.get("content-length")).toBe(String(bytes.length));
+    expect(res.headers.get("content-disposition")).toContain("Dune.epub");
+    expect(res.headers.get("etag")).toBe(`"${hash}"`);
+    expect(Array.from(new Uint8Array(await res.arrayBuffer()))).toEqual(Array.from(bytes));
+  });
+
+  it("answers If-None-Match with a 304 and no body", async () => {
+    // The reason this matters: without it an e-reader re-downloads every book
+    // on every scheduled sync.
+    const app = createApp();
+    const hash = (
+      (await (await uploadRequest(app, makeEpub(), "x.epub")).json()) as {
+        book: { contentHash: string };
+      }
+    ).book.contentHash;
+
+    const res = await app.request(`/xrpc/buzz.bookhive.getPersonalBookFile?contentHash=${hash}`, {
+      headers: { "if-none-match": `"${hash}"` },
+    });
+    expect(res.status).toBe(304);
+    expect(await res.text()).toBe("");
+  });
+
+  it("404s another user's book rather than 403", async () => {
+    const hash = (
+      (await (await uploadRequest(createApp(DID), makeEpub(), "x.epub")).json()) as {
+        book: { contentHash: string };
+      }
+    ).book.contentHash;
+
+    const res = await createApp(OTHER_DID).request(
+      `/xrpc/buzz.bookhive.getPersonalBookFile?contentHash=${hash}`,
+    );
+    // 404, not 403: a different status would confirm the book exists.
+    expect(res.status).toBe(404);
+  });
+
+  it("401s without a session", async () => {
+    const res = await createApp(null).request(
+      "/xrpc/buzz.bookhive.getPersonalBookFile?contentHash=whatever",
+    );
+    expect(res.status).toBe(401);
+  });
+});
+
+describe("XRPC getPersonalBookCover", () => {
+  it("serves the extracted cover", async () => {
+    const app = createApp();
+    const hash = (
+      (await (await uploadRequest(app, makeEpub(), "x.epub")).json()) as {
+        book: { contentHash: string };
+      }
+    ).book.contentHash;
+
+    const res = await app.request(`/xrpc/buzz.bookhive.getPersonalBookCover?contentHash=${hash}`);
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toBe("image/png");
+    expect(res.headers.get("etag")).toBe(`"${hash}-cover"`);
+  });
+
+  it("answers If-None-Match on the cover", async () => {
+    const app = createApp();
+    const hash = (
+      (await (await uploadRequest(app, makeEpub(), "x.epub")).json()) as {
+        book: { contentHash: string };
+      }
+    ).book.contentHash;
+
+    const res = await app.request(`/xrpc/buzz.bookhive.getPersonalBookCover?contentHash=${hash}`, {
+      headers: { "if-none-match": `"${hash}-cover"` },
+    });
+    expect(res.status).toBe(304);
+  });
+
+  it("404s a book with neither a stored cover nor a catalog entry", async () => {
+    const app = createApp();
+    // FB2 fixture carries no cover image.
+    const hash = (
+      (await (
+        await uploadRequest(app, makeFb2(), "x.fb2", {
+          contentType: "application/x-fictionbook+xml",
+        })
+      ).json()) as { book: { contentHash: string } }
+    ).book.contentHash;
+
+    const res = await app.request(`/xrpc/buzz.bookhive.getPersonalBookCover?contentHash=${hash}`);
+    expect(res.status).toBe(404);
+  });
+
+  it("redirects to the catalog image for a linked book with no stored cover", async () => {
+    // The branch that used to be built with `Response.redirect`, whose headers
+    // are immutable — the Cache-Control middleware setting a header on it threw
+    // a TypeError and turned the 302 into a 500.
+    const app = createApp();
+    const hash = (
+      (await (
+        await uploadRequest(app, makeFb2(), "x.fb2", {
+          contentType: "application/x-fictionbook+xml",
+        })
+      ).json()) as { book: { contentHash: string } }
+    ).book.contentHash;
+
+    // Link it to a catalog entry, leaving coverPath null.
+    await db
+      .updateTable("personal_book")
+      .set({ hiveId: "bk_catalog1" })
+      .where("contentHash", "=", hash)
+      .execute();
+
+    const res = await app.request(
+      `/xrpc/buzz.bookhive.getPersonalBookCover?contentHash=${hash}&width=200`,
+    );
+    expect(res.status).toBe(302);
+    expect(res.headers.get("location")).toContain("/images/books/bk_catalog1?w=200");
+
+    // The header guard is the actual regression: mutating it must not throw.
+    expect(() => res.headers.set("cache-control", "private, no-store")).not.toThrow();
+  });
+});
+
+describe("XRPC getPersonalLibrary — search, sort and storage", () => {
+  async function seedLibrary(app: TestApp) {
+    await uploadRequest(app, makeEpub({ title: "Dune", authors: ["Frank Herbert"] }), "Dune.epub");
+    await uploadRequest(
+      app,
+      makeEpub({ title: "Neuromancer", authors: ["William Gibson"] }),
+      "Neuromancer.epub",
+    );
+    await uploadRequest(
+      app,
+      makeEpub({ title: "Ancillary Justice", authors: ["Ann Leckie"] }),
+      "Ancillary.epub",
+    );
+  }
+
+  it("filters on title or author, matching the OPDS search feed", async () => {
+    const app = createApp();
+    await seedLibrary(app);
+
+    const byTitle = (await (
+      await app.request("/xrpc/buzz.bookhive.getPersonalLibrary?q=neuro")
+    ).json()) as { books: { title: string }[]; total: number };
+    expect(byTitle.books.map((b) => b.title)).toEqual(["Neuromancer"]);
+    expect(byTitle.total).toBe(1);
+
+    const byAuthor = (await (
+      await app.request("/xrpc/buzz.bookhive.getPersonalLibrary?q=Leckie")
+    ).json()) as { books: { title: string }[] };
+    expect(byAuthor.books.map((b) => b.title)).toEqual(["Ancillary Justice"]);
+  });
+
+  it("sorts by title and by author on request", async () => {
+    const app = createApp();
+    await seedLibrary(app);
+
+    const byTitle = (await (
+      await app.request("/xrpc/buzz.bookhive.getPersonalLibrary?sort=title")
+    ).json()) as { books: { title: string }[] };
+    expect(byTitle.books.map((b) => b.title)).toEqual(["Ancillary Justice", "Dune", "Neuromancer"]);
+
+    const byAuthor = (await (
+      await app.request("/xrpc/buzz.bookhive.getPersonalLibrary?sort=author")
+    ).json()) as { books: { authors?: string }[] };
+    expect(byAuthor.books.map((b) => b.authors)).toEqual([
+      "Ann Leckie",
+      "Frank Herbert",
+      "William Gibson",
+    ]);
+  });
+
+  it("defaults to newest first, and does not switch when q is set", async () => {
+    // Deterministic because every sort ends on `personal_book.id`: all three
+    // uploads land in the same whole second, so `createdAt DESC` alone leaves
+    // the order up to SQLite. Newest-first therefore means "highest id first",
+    // which is the last book seeded.
+    const app = createApp();
+    await seedLibrary(app);
+    const res = (await (await app.request("/xrpc/buzz.bookhive.getPersonalLibrary")).json()) as {
+      books: { title: string }[];
+    };
+    expect(res.books.map((b) => b.title)).toEqual(["Ancillary Justice", "Neuromancer", "Dune"]);
+
+    // OPDS switches to a title sort when searching; this deliberately does not.
+    // `q` narrows the set, it does not reorder it.
+    const searched = (await (
+      await app.request("/xrpc/buzz.bookhive.getPersonalLibrary?q=n")
+    ).json()) as { books: { title: string }[] };
+    expect(searched.books.map((b) => b.title)).toEqual([
+      "Ancillary Justice",
+      "Neuromancer",
+      "Dune",
+    ]);
+  });
+
+  it("reports storage usage and the extra view fields", async () => {
+    const app = createApp();
+    const bytes = makeEpub({ title: "Dune" });
+    await uploadRequest(app, bytes, "Dune.epub");
+
+    const res = (await (await app.request("/xrpc/buzz.bookhive.getPersonalLibrary")).json()) as {
+      books: { filename: string; hasLocalCover: boolean }[];
+      storage: { usedBytes: number; quotaBytes: number };
+    };
+    expect(res.storage).toEqual({ usedBytes: bytes.length, quotaBytes: getStorageQuota() });
+    expect(res.books[0]!.filename).toBe("Dune.epub");
+    expect(res.books[0]!.hasLocalCover).toBe(true);
+  });
+});
+
+describe("XRPC listPersonalShelves", () => {
+  it("returns shelves with counts plus library totals", async () => {
+    const app = createApp();
+    await uploadRequest(app, makeEpub({ title: "Dune" }), "Dune.epub");
+    const bookRow = await db.selectFrom("personal_book").select("id").executeTakeFirstOrThrow();
+
+    const shelf = await db
+      .insertInto("personal_shelf")
+      .values({
+        userDid: DID,
+        name: "Sci-Fi",
+        description: "space",
+        createdAt: "2026-08-01T00:00:00.000Z",
+        updatedAt: "2026-08-01T00:00:00.000Z",
+      })
+      .returning("id")
+      .executeTakeFirstOrThrow();
+    await db
+      .insertInto("personal_shelf_item")
+      .values({
+        shelfId: shelf.id,
+        personalBookId: bookRow.id,
+        createdAt: "2026-08-01T00:00:00.000Z",
+      })
+      .execute();
+
+    const res = (await (await app.request("/xrpc/buzz.bookhive.listPersonalShelves")).json()) as {
+      shelves: { id: number; name: string; description?: string; bookCount: number }[];
+      totalBooks: number;
+      storage: { usedBytes: number; quotaBytes: number };
+    };
+
+    expect(res.shelves).toHaveLength(1);
+    expect(res.shelves[0]!.name).toBe("Sci-Fi");
+    expect(res.shelves[0]!.description).toBe("space");
+    expect(res.shelves[0]!.bookCount).toBe(1);
+    expect(res.totalBooks).toBe(1);
+    expect(res.storage.quotaBytes).toBe(getStorageQuota());
+  });
+
+  it("does not show another user's shelves", async () => {
+    await db
+      .insertInto("personal_shelf")
+      .values({
+        userDid: OTHER_DID,
+        name: "Theirs",
+        createdAt: "2026-08-01T00:00:00.000Z",
+        updatedAt: "2026-08-01T00:00:00.000Z",
+      })
+      .execute();
+
+    const res = (await (
+      await createApp(DID).request("/xrpc/buzz.bookhive.listPersonalShelves")
+    ).json()) as { shelves: unknown[]; totalBooks: number };
+    expect(res.shelves).toHaveLength(0);
+    expect(res.totalBooks).toBe(0);
+  });
+
+  it("401s without a session", async () => {
+    const res = await createApp(null).request("/xrpc/buzz.bookhive.listPersonalShelves");
+    expect(res.status).toBe(401);
+  });
+});
diff --git a/src/xrpc/router.ts b/src/xrpc/router.ts
index a61b691..b78e291 100644
--- a/src/xrpc/router.ts
+++ b/src/xrpc/router.ts
@@ -31,6 +31,9 @@ import {
   BuzzBookhiveGetLanguages,
   BuzzBookhiveGetPersonalLibrary,
   BuzzBookhiveGetPersonalBook,
+  BuzzBookhiveGetPersonalBookFile,
+  BuzzBookhiveGetPersonalBookCover,
+  BuzzBookhiveListPersonalShelves,
   BuzzBookhiveUploadPersonalBook,
   BuzzBookhiveDeletePersonalBook,
   BuzzBookhiveLinkPersonalBook,
@@ -96,19 +99,62 @@ import type {
   ProfileViewDetailed,
   SyncProgressData,
 } from "../types";
-import { detectFormat, parseBook, koreaderPartialMD5 } from "../utils/bookMetadata/index";
 import {
-  bookFilePath,
-  coverFilePath,
-  ensureDir,
-  MAX_PERSONAL_BOOK_BYTES,
-  personalBookDir,
+  etagMatches,
+  getStorageQuota,
+  getStorageUsage,
   removeBookDir,
+  streamPersonalBook,
 } from "../utils/personalLibrary";
-import { matchSyncDocument, NO_HIVE_MATCH } from "../utils/syncMatching";
+import { uploadPersonalBook, type UploadPersonalBookResult } from "../utils/uploadPersonalBook";
+import { resolveXrpcAuth, type AuthMode, type XrpcAuth, type XrpcAuthContext } from "./auth";
+import type { Nsid } from "@atcute/lexicons";
+import type { ServiceJwtVerifier } from "@atcute/xrpc-server/auth";
+import { matchSyncDocumentForUser, NO_HIVE_MATCH, SAME_BOOK_FILE } from "../utils/syncMatching";
+import { filenameKey } from "../utils/filenameMatching";
 import { bridgeProgressToUserBook } from "../utils/syncBridge";
 import { truncateForLog } from "../middleware/wide-event";
 
+/**
+ * The one place the upload core's failure reasons become XRPC errors, so the
+ * XRPC and multipart adapters can't drift on what a given failure means. The
+ * matching HTTP mapping lives in `src/routes/library.tsx`.
+ */
+function uploadErrorFor(result: Extract<UploadPersonalBookResult, { ok: false }>): XRPCError {
+  switch (result.reason) {
+    case "too-large":
+      return new XRPCError({
+        status: 413,
+        error: "TooLarge",
+        message: `File exceeds ${result.limitBytes} bytes`,
+      });
+    case "quota-exceeded":
+      return new XRPCError({
+        status: 413,
+        error: "QuotaExceeded",
+        message: `Library full (${result.usedBytes} of ${result.quotaBytes} bytes used)`,
+      });
+    case "unsupported-format":
+      return new InvalidRequestError({
+        message: `Unsupported file format: ${result.filename}`,
+      });
+    case "duplicate":
+      return new XRPCError({
+        status: 409,
+        error: "AlreadyExists",
+        message: "This book already exists in your library",
+      });
+    case "empty":
+      return new InvalidRequestError({ message: "The file is empty" });
+    case "busy":
+      return new XRPCError({
+        status: 503,
+        error: "Busy",
+        message: "Server is busy — try again in a moment",
+      });
+  }
+}
+
 /**
  * Shape a `sync_document.progressData` blob into the lexicon's syncProgressView.
  * Returns undefined when the book has never been synced or the blob is unusable.
@@ -130,143 +176,6 @@ function syncProgressView(
   }
 }
 
-/**
- * Process a book upload: detect format, hash, extract metadata, write to disk,
- * insert DB row, and attempt auto-linking to a hive_book. Exported so it can be
- * called from both the XRPC handler and a regular Hono multipart form route.
- */
-export async function processBookUpload(
-  db: Database,
-  _kv: Storage,
-  userDid: string,
-  bytes: Uint8Array,
-  filename: string,
-): Promise<{
-  contentHash: string;
-  title: string;
-  authors?: string;
-  language?: string;
-  format: string;
-  mime: string;
-  sizeBytes: number;
-  createdAt: string;
-  updatedAt: string;
-  hiveId?: string;
-  coverUrl?: string;
-}> {
-  // 1. Detect format — reject unknown
-  const formatInfo = detectFormat(bytes, filename);
-  if (formatInfo.format === "unknown") {
-    throw new XRPCError({
-      status: 400,
-      error: "InvalidRequest",
-      message: `Unsupported file format: ${filename}`,
-    });
-  }
-
-  // 2. Compute content hash
-  const contentHash = koreaderPartialMD5(bytes);
-
-  // 3. Check for duplicate
-  const duplicate = await db
-    .selectFrom("personal_book")
-    .select(["id", "contentHash"])
-    .where("userDid", "=", userDid)
-    .where("contentHash", "=", contentHash)
-    .executeTakeFirst();
-
-  if (duplicate) {
-    throw new XRPCError({
-      status: 409,
-      error: "AlreadyExists",
-      message: "This book already exists in your library",
-    });
-  }
-
-  // 4. Parse metadata + cover
-  const metadata = parseBook(bytes, filename);
-
-  // 5. Write file to disk
-  const dir = personalBookDir(userDid, contentHash);
-  await ensureDir(dir);
-  const filePath = bookFilePath(userDid, contentHash, formatInfo.ext);
-  await Bun.write(filePath, bytes);
-
-  // 6. Write cover if extracted
-  let coverPath: string | null = null;
-  let coverMime: string | null = null;
-  if (metadata.cover) {
-    coverPath = coverFilePath(userDid, contentHash, metadata.cover.ext);
-    coverMime = metadata.cover.mime;
-    await Bun.write(coverPath, metadata.cover.bytes);
-  }
-
-  // 7. Insert into personal_book
-  const now = new Date().toISOString();
-
-  // 8. Auto-link: try to match to a hive_book
-  let hiveId = await matchSyncDocument(db, {
-    title: metadata.title,
-    authors: metadata.authors,
-    filename,
-  });
-
-  await db
-    .insertInto("personal_book")
-    .values({
-      userDid,
-      contentHash,
-      hiveId,
-      filename,
-      title: metadata.title,
-      authors: metadata.authors || null,
-      language: metadata.language ?? null,
-      format: formatInfo.format,
-      mime: formatInfo.mime,
-      filePath,
-      coverPath,
-      coverMime,
-      sizeBytes: bytes.length,
-      createdAt: now,
-      updatedAt: now,
-    })
-    .execute();
-
-  // 9. If contentHash matches a sync_document for this user, update its hiveId
-  if (hiveId) {
-    await db
-      .updateTable("sync_document")
-      .set({ hiveId })
-      .where("userDid", "=", userDid)
-      .where("documentHash", "=", contentHash)
-      .where("hiveId", "is", null)
-      .execute();
-
-    // Mark the book as owned if the user has it in their library
-    await db
-      .updateTable("user_book")
-      .set({ owned: 1 })
-      .where("userDid", "=", userDid)
-      .where("hiveId", "=", hiveId)
-      .where("owned", "=", 0)
-      .execute();
-  }
-
-  return {
-    contentHash,
-    title: metadata.title,
-    authors: metadata.authors || undefined,
-    language: metadata.language ?? undefined,
-    format: formatInfo.format,
-    mime: formatInfo.mime,
-    sizeBytes: bytes.length,
-    createdAt: now,
-    updatedAt: now,
-    hiveId: hiveId ?? undefined,
-    coverUrl: coverPath ? `/library/covers/${contentHash}` : undefined,
-  };
-}
-
 /** Minimal context shape required by XRPC handlers (avoids importing index). */
 export type XrpcContext = {
   db: Database;
@@ -279,6 +188,8 @@ export type XrpcContext = {
     handle: { resolve: (handle: string) => Promise<string | undefined> };
   };
   addWideEventContext: (context: Record<string, unknown>) => void;
+  /** Verifies atproto service-auth JWTs. Null when service auth is disabled. */
+  serviceJwtVerifier?: ServiceJwtVerifier | null;
 };
 
 export type XrpcDeps<E extends XrpcContext = XrpcContext> = {
@@ -298,27 +209,78 @@ function getCtx(): XrpcContext {
   return ctx;
 }
 
+/**
+ * Auth resolved for the in-flight handler, by the registration wrapper below.
+ * Same AsyncLocalStorage idiom as the context — atcute handlers only receive
+ * `{request, params, input, signal}`, so there is nowhere else to put it.
+ */
+const xrpcAuthStorage = new AsyncLocalStorage<XrpcAuth>();
+
+/** The authenticated caller. Only valid inside a handler registered with `auth`. */
+function getAuth(): XrpcAuth {
+  const auth = xrpcAuthStorage.getStore();
+  if (!auth) throw new Error("XRPC auth not resolved (method registered without `auth`)");
+  return auth;
+}
+
+/**
+ * The caller's OAuth session, for handlers that write to their repo. Non-null by
+ * construction — `auth: "pdsWrite"` refuses service auth before the handler runs
+ * — but narrowing the union keeps that guarantee in the types rather than in a
+ * comment.
+ */
+function requireAgent(): SessionClient {
+  const auth = getAuth();
+  if (auth.method !== "session") {
+    throw new AuthRequiredError({ message: "This method requires an OAuth session" });
+  }
+  return auth.agent;
+}
+
 export function createXrpcRouter<E extends XrpcContext, V extends { ctx: E } = { ctx: E }>(
   app: import("hono").Hono<{ Variables: V }>,
   deps: XrpcDeps<E>,
 ): void {
   const router = new XRPCRouter();
 
-  // XRPCRouter catches handler throws and turns them into a 500 Response, so
-  // Hono's error-capture middleware never sees them and the wide event logs an
-  // error-level line with no `error` field at all. Record the cause on the way
-  // past. Patching the two registration methods once beats annotating 40+
-  // handlers (and can't be forgotten by the next one added).
+  // Two things are patched onto every registration here rather than repeated in
+  // 40+ handlers (where the next one added would forget them):
+  //
+  // 1. **Error observability.** XRPCRouter catches handler throws and turns them
+  //    into a 500 Response, so Hono's error-capture middleware never sees them
+  //    and the wide event logs an error-level line with no `error` field at all.
+  //    Record the cause on the way past.
+  // 2. **Authentication**, when the registration carries an `auth` mode. The
+  //    `lxm` a service-auth token must be bound to is derived from the schema's
+  //    own NSID, which makes it structurally impossible for a method's route and
+  //    its token binding to disagree.
   for (const method of ["addQuery", "addProcedure"] as const) {
     const original = router[method].bind(router) as (schema: unknown, options: any) => unknown;
-    (router as any)[method] = (schema: unknown, options: any) => {
+    (router as any)[method] = (schema: any, options: any) => {
       const handler = options?.handler;
       if (typeof handler !== "function") return original(schema, options);
+
+      // A generated lexicon module carries `mainSchema`; `v.query`/`v.procedure`
+      // put the NSID on it. Same unwrap atcute does internally.
+      const nsid = ("mainSchema" in schema ? schema.mainSchema : schema).nsid as Nsid;
+      const mode: AuthMode | undefined = options.auth;
+      const { auth: _auth, ...rest } = options;
+
       return original(schema, {
-        ...options,
-        handler: async (input: unknown) => {
+        ...rest,
+        handler: async (input: any) => {
           try {
-            return await handler(input);
+            if (mode === undefined) return await handler(input);
+
+            const ctx = xrpcContextStorage.getStore();
+            const auth = await resolveXrpcAuth(ctx as XrpcAuthContext, input.request, {
+              lxm: nsid,
+              mode,
+            });
+            ctx?.addWideEventContext({ userDid: auth.did, xrpc_auth: auth.method });
+            // Auth failures land inside this try, so a 401 is recorded as the
+            // intentional control flow it is — same as a hand-thrown one.
+            return await xrpcAuthStorage.run(auth, () => handler(input));
           } catch (err) {
             // Deliberate 4xx (AuthRequiredError, InvalidRequest, …) are control
             // flow, not defects — record them without a stack.
@@ -1272,10 +1234,10 @@ export function createXrpcRouter<E extends XrpcContext, V extends { ctx: E } = {
   // ── List CRUD ──
 
   router.addProcedure(BuzzBookhiveCreateList, {
+    auth: "pdsWrite",
     async handler({ input: _input }) {
       const ctx = getCtx();
-      const agent = await ctx.getSessionAgent();
-      if (!agent) throw new AuthRequiredError({ message: "Authentication required" });
+      const agent = requireAgent();
       const input = _input as BuzzBookhiveCreateList.$input;
 
       const result = await createList({
@@ -1292,10 +1254,10 @@ export function createXrpcRouter<E extends XrpcContext, V extends { ctx: E } = {
   });
 
   router.addProcedure(BuzzBookhiveUpdateList, {
+    auth: "pdsWrite",
     async handler({ input: _input }) {
       const ctx = getCtx();
-      const agent = await ctx.getSessionAgent();
-      if (!agent) throw new AuthRequiredError({ message: "Authentication required" });
+      const agent = requireAgent();
       const input = _input as BuzzBookhiveUpdateList.$input;
 
       const result = await updateList({
@@ -1313,10 +1275,10 @@ export function createXrpcRouter<E extends XrpcContext, V extends { ctx: E } = {
   });
 
   router.addProcedure(BuzzBookhiveDeleteList, {
+    auth: "pdsWrite",
     async handler({ input: _input }) {
       const ctx = getCtx();
-      const agent = await ctx.getSessionAgent();
-      if (!agent) throw new AuthRequiredError({ message: "Authentication required" });
+      const agent = requireAgent();
       const input = _input as BuzzBookhiveDeleteList.$input;
 
       await deleteList({ agent, db: ctx.db, uri: input.uri });
@@ -1326,10 +1288,10 @@ export function createXrpcRouter<E extends XrpcContext, V extends { ctx: E } = {
   });
 
   router.addProcedure(BuzzBookhiveAddToList, {
+    auth: "pdsWrite",
     async handler({ input: _input }) {
       const ctx = getCtx();
-      const agent = await ctx.getSessionAgent();
-      if (!agent) throw new AuthRequiredError({ message: "Authentication required" });
+      const agent = requireAgent();
       const input = _input as BuzzBookhiveAddToList.$input;
 
       const result = await addBookToList({
@@ -1346,10 +1308,10 @@ export function createXrpcRouter<E extends XrpcContext, V extends { ctx: E } = {
   });
 
   router.addProcedure(BuzzBookhiveRemoveFromList, {
+    auth: "pdsWrite",
     async handler({ input: _input }) {
       const ctx = getCtx();
-      const agent = await ctx.getSessionAgent();
-      if (!agent) throw new AuthRequiredError({ message: "Authentication required" });
+      const agent = requireAgent();
       const input = _input as BuzzBookhiveRemoveFromList.$input;
 
       await removeBookFromList({ agent, db: ctx.db, itemUri: input.itemUri });
@@ -1359,10 +1321,10 @@ export function createXrpcRouter<E extends XrpcContext, V extends { ctx: E } = {
   });
 
   router.addProcedure(BuzzBookhiveReorderList, {
+    auth: "pdsWrite",
     async handler({ input: _input }) {
       const ctx = getCtx();
-      const agent = await ctx.getSessionAgent();
-      if (!agent) throw new AuthRequiredError({ message: "Authentication required" });
+      const agent = requireAgent();
       const input = _input as BuzzBookhiveReorderList.$input;
 
       await reorderListItems({
@@ -1457,27 +1419,17 @@ export function createXrpcRouter<E extends XrpcContext, V extends { ctx: E } = {
   // ── Personal Library CRUD ──
 
   router.addQuery(BuzzBookhiveGetPersonalLibrary, {
+    auth: "identity",
     async handler({ params: _params }) {
       const ctx = getCtx();
-      const agent = await ctx.getSessionAgent();
-      if (!agent) throw new AuthRequiredError({ message: "Authentication required" });
-      const userDid = agent.did;
+      const { did: userDid } = getAuth();
       const params = _params as BuzzBookhiveGetPersonalLibrary.$params;
-      const { limit = 24, shelfId } = params;
+      const { limit = 24, shelfId, q, sort = "recent" } = params;
       const offset = params.cursor ? parseInt(params.cursor, 10) : 0;
 
       let query = ctx.db
         .selectFrom("personal_book")
         .leftJoin("hive_book", "personal_book.hiveId", "hive_book.id")
-        // The KOReader partial MD5 is both `personal_book.contentHash` and
-        // `sync_document.documentHash`, so a synced file joins straight to its
-        // e-reader progress.
-        .leftJoin("sync_document", (join) =>
-          join
-            .onRef("sync_document.documentHash", "=", "personal_book.contentHash")
-            .on("sync_document.userDid", "=", userDid)
-            .on("sync_document.provider", "=", "kosync"),
-        )
         .select([
           "personal_book.id",
           "personal_book.contentHash",
@@ -1496,11 +1448,68 @@ export function createXrpcRouter<E extends XrpcContext, V extends { ctx: E } = {
           "personal_book.updatedAt",
           "hive_book.cover as hiveCover",
           "hive_book.thumbnail as hiveThumbnail",
-          "sync_document.progressData as progressData",
-          "sync_document.updatedAt as progressUpdatedAt",
+          "hive_book.description as hiveDescription",
         ])
-        .where("personal_book.userDid", "=", userDid)
-        .orderBy("personal_book.createdAt", "desc");
+        // E-reader progress for this file. Correlated subqueries rather than a
+        // join: a file can match more than one synced document (the same book
+        // read on a device in BINARY checksum mode and another in FILENAME
+        // mode is two rows — see SAME_BOOK_FILE), and a join would emit the
+        // book once per match and quietly corrupt this query's pagination.
+        // Most recent wins.
+        .select((eb) => [
+          eb
+            .selectFrom("sync_document")
+            .select("sync_document.progressData")
+            .where("sync_document.userDid", "=", userDid)
+            .where("sync_document.provider", "=", "kosync")
+            .where(SAME_BOOK_FILE)
+            .orderBy("sync_document.updatedAt", "desc")
+            .limit(1)
+            .as("progressData"),
+          eb
+            .selectFrom("sync_document")
+            .select("sync_document.updatedAt")
+            .where("sync_document.userDid", "=", userDid)
+            .where("sync_document.provider", "=", "kosync")
+            .where(SAME_BOOK_FILE)
+            .orderBy("sync_document.updatedAt", "desc")
+            .limit(1)
+            .as("progressUpdatedAt"),
+        ])
+        .where("personal_book.userDid", "=", userDid);
+
+      // Same predicate and ordering as the OPDS search feed, so "full parity"
+      // is a property of the SQL rather than a claim. SQLite's LIKE is
+      // case-insensitive for ASCII only; that is pre-existing OPDS behaviour
+      // and deliberately preserved rather than silently changed here.
+      if (q) {
+        query = query.where((eb) =>
+          eb.or([
+            eb("personal_book.title", "like", `%${q}%`),
+            eb("personal_book.authors", "like", `%${q}%`),
+          ]),
+        ) as typeof query;
+      }
+      // Every sort ends on `personal_book.id`. None of the leading keys are
+      // unique: titles and authors collide routinely (a series, an omnibus, the
+      // same book in two formats), and `createdAt` — millisecond-precision ISO
+      // — collides when two uploads commit in the same millisecond. SQLite is
+      // free to return ties in any order it likes between two LIMIT/OFFSET
+      // queries, so without a unique final key a book can appear on two
+      // consecutive pages while another never appears at all.
+      query =
+        sort === "title"
+          ? (query
+              .orderBy("personal_book.title", "asc")
+              .orderBy("personal_book.id", "asc") as typeof query)
+          : sort === "author"
+            ? (query
+                .orderBy("personal_book.authors", "asc")
+                .orderBy("personal_book.title", "asc")
+                .orderBy("personal_book.id", "asc") as typeof query)
+            : (query
+                .orderBy("personal_book.createdAt", "desc")
+                .orderBy("personal_book.id", "desc") as typeof query);
 
       if (shelfId !== undefined) {
         query = query
@@ -1518,6 +1527,14 @@ export function createXrpcRouter<E extends XrpcContext, V extends { ctx: E } = {
         .selectFrom("personal_book")
         .select((eb) => eb.fn.countAll<number>().as("total"))
         .where("personal_book.userDid", "=", userDid);
+      if (q) {
+        countQuery = countQuery.where((eb) =>
+          eb.or([
+            eb("personal_book.title", "like", `%${q}%`),
+            eb("personal_book.authors", "like", `%${q}%`),
+          ]),
+        ) as typeof countQuery;
+      }
       if (shelfId !== undefined) {
         countQuery = countQuery
           .innerJoin(
@@ -1528,12 +1545,16 @@ export function createXrpcRouter<E extends XrpcContext, V extends { ctx: E } = {
           .where("personal_shelf_item.shelfId", "=", shelfId) as typeof countQuery;
       }
 
-      const [rows, counted] = await Promise.all([
+      const [rows, counted, usedBytes] = await Promise.all([
         query
           .limit(limit + 1)
           .offset(offset)
           .execute(),
         countQuery.executeTakeFirstOrThrow(),
+        // Bundled here rather than exposed as its own method: every client
+        // already refetches this on mount and after each mutation, so a usage
+        // bar updates with no extra round-trip and no new invalidation wiring.
+        getStorageUsage(ctx.db, userDid),
       ]);
       const hasMore = rows.length > limit;
       const books = rows.slice(0, limit);
@@ -1570,6 +1591,8 @@ export function createXrpcRouter<E extends XrpcContext, V extends { ctx: E } = {
           format: b.format,
           mime: b.mime,
           sizeBytes: b.sizeBytes,
+          filename: b.filename,
+          description: b.hiveDescription ?? undefined,
           createdAt: b.createdAt,
           updatedAt: b.updatedAt,
           hiveId: b.hiveId ?? undefined,
@@ -1577,21 +1600,26 @@ export function createXrpcRouter<E extends XrpcContext, V extends { ctx: E } = {
             b.hiveCover ??
             b.hiveThumbnail ??
             (b.coverPath ? `/library/covers/${b.contentHash}` : undefined),
+          // `coverUrl`'s local form needs a session cookie, which a service-auth
+          // client does not have. This tells such a client to use
+          // getPersonalBookCover instead, without breaking `coverUrl` for the
+          // web and mobile clients that already read it.
+          hasLocalCover: Boolean(b.coverPath),
           progress: syncProgressView(b.progressData, b.progressUpdatedAt),
           shelfIds: shelfIdsByBook.get(b.id) ?? [],
         })),
         total: Number(counted.total),
         cursor: nextCursor,
+        storage: { usedBytes, quotaBytes: getStorageQuota() },
       });
     },
   });
 
   router.addQuery(BuzzBookhiveGetPersonalBook, {
+    auth: "identity",
     async handler({ params: _params }) {
       const ctx = getCtx();
-      const agent = await ctx.getSessionAgent();
-      if (!agent) throw new AuthRequiredError({ message: "Authentication required" });
-      const userDid = agent.did;
+      const { did: userDid } = getAuth();
       const { contentHash } = _params as BuzzBookhiveGetPersonalBook.$params;
 
       const book = await ctx.db
@@ -1641,44 +1669,183 @@ export function createXrpcRouter<E extends XrpcContext, V extends { ctx: E } = {
     },
   });
 
-  // TODO: The uploadPersonalBook XRPC handler uses blob input. If the XRPC
-  // server's binary handling proves problematic, the actual upload route may
-  // need to be a standard Hono multipart form handler at `/library/upload`
-  // instead. The core logic is exported as `processBookUpload` so it can be
-  // called from either location.
-  router.addProcedure(BuzzBookhiveUploadPersonalBook, {
-    async handler({ request }) {
+  // The XRPC equivalent of GET /opds/books/:hash/download.
+  //
+  // Returns a bare `Response` rather than `json(...)`: the lexicon declares a
+  // blob output, so the router passes whatever we return straight through and
+  // sets no headers of its own — this handler owns all of them.
+  router.addQuery(BuzzBookhiveGetPersonalBookFile, {
+    auth: "identity",
+    async handler({ request, params: _params }) {
       const ctx = getCtx();
-      const agent = await ctx.getSessionAgent();
-      if (!agent) throw new AuthRequiredError({ message: "Authentication required" });
-      const userDid = agent.did;
+      const { did: userDid } = getAuth();
+      const { contentHash } = _params as BuzzBookhiveGetPersonalBookFile.$params;
+
+      // `streamPersonalBook` answers the conditional request itself, before it
+      // opens the file. This route must not lean on hono's `etag()` for the
+      // 304: that middleware buffers a whole body through a digest, which is
+      // exactly what a 100 MB download must never do.
+      const download = await streamPersonalBook(
+        ctx.db,
+        userDid,
+        contentHash,
+        request.headers.get("if-none-match"),
+      );
+      // 404 rather than 403 for someone else's book — don't leak existence.
+      if (!download) {
+        throw new XRPCError({ status: 404, error: "NotFound", message: "Book not found" });
+      }
+      if (download.notModified) {
+        return new Response(null, { status: 304, headers: download.headers });
+      }
+      return new Response(download.stream, { status: 200, headers: download.headers });
+    },
+  });
 
-      // This path had no size limit at all, unlike POST /library/upload — an
-      // unbounded `arrayBuffer()` straight into native memory on an
-      // authenticated endpoint. Reject on the declared length first so an
-      // oversized body is never materialised.
-      const declared = Number(request.headers.get("content-length"));
-      if (Number.isFinite(declared) && declared > MAX_PERSONAL_BOOK_BYTES) {
-        throw new InvalidRequestError({ message: "File exceeds 100 MB limit" });
+  // The XRPC equivalent of GET /opds/books/:hash/cover.
+  router.addQuery(BuzzBookhiveGetPersonalBookCover, {
+    auth: "identity",
+    async handler({ request, params: _params }) {
+      const ctx = getCtx();
+      const { did: userDid } = getAuth();
+      const { contentHash, width = 300 } = _params as BuzzBookhiveGetPersonalBookCover.$params;
+
+      const book = await ctx.db
+        .selectFrom("personal_book")
+        .select(["coverPath", "coverMime", "hiveId"])
+        .where("userDid", "=", userDid)
+        .where("contentHash", "=", contentHash)
+        .executeTakeFirst();
+      if (!book) {
+        throw new XRPCError({ status: 404, error: "NotFound", message: "Book not found" });
       }
 
-      const bytes = new Uint8Array(await request.arrayBuffer());
-      if (bytes.length > MAX_PERSONAL_BOOK_BYTES) {
-        throw new InvalidRequestError({ message: "File exceeds 100 MB limit" });
+      if (book.coverPath) {
+        const file = Bun.file(book.coverPath);
+        if (await file.exists()) {
+          // Set our own ETag: hono's `etag()` only digests (and so buffers) a
+          // response that doesn't already carry one, and this gets conditional
+          // requests answered for free.
+          const etag = `"${contentHash}-cover"`;
+          if (etagMatches(request.headers.get("if-none-match"), etag)) {
+            return new Response(null, { status: 304, headers: { ETag: etag } });
+          }
+          return new Response(file.stream(), {
+            headers: {
+              "Content-Type": book.coverMime || "image/jpeg",
+              "Content-Length": String(file.size),
+              "Cache-Control": "private, max-age=86400",
+              ETag: etag,
+            },
+          });
+        }
       }
-      const filename = request.headers.get("x-file-name") ?? "unknown";
 
-      const result = await processBookUpload(ctx.db, ctx.kv, userDid, bytes, filename);
-      return json({ book: result });
+      // No extracted cover, but the book is linked to a catalog entry: hand the
+      // client the public image proxy. Absolute, so a non-browser client can
+      // follow it without knowing our origin, and public, so nothing leaks.
+      if (book.hiveId) {
+        // Built by hand rather than with `Response.redirect`, whose headers are
+        // *immutable*: the downstream `Cache-Control` middleware and the nitro
+        // response hook both set headers on the final Response, and doing that
+        // to an immutable guard throws a TypeError — turning a 302 into a 500.
+        return new Response(null, {
+          status: 302,
+          headers: {
+            Location: new URL(`/images/books/${book.hiveId}?w=${width}`, request.url).toString(),
+          },
+        });
+      }
+      throw new XRPCError({ status: 404, error: "NotFound", message: "No cover for this book" });
+    },
+  });
+
+  // The root call for a catalog client: everything GET /opds renders, in one
+  // request — shelves with their counts, the library total, and storage usage.
+  router.addQuery(BuzzBookhiveListPersonalShelves, {
+    auth: "identity",
+    async handler() {
+      const ctx = getCtx();
+      const { did: userDid } = getAuth();
+
+      const [shelves, counted, usedBytes] = await Promise.all([
+        ctx.db
+          .selectFrom("personal_shelf")
+          .leftJoin("personal_shelf_item", "personal_shelf.id", "personal_shelf_item.shelfId")
+          .select((eb) => [
+            "personal_shelf.id",
+            "personal_shelf.name",
+            "personal_shelf.description",
+            "personal_shelf.createdAt",
+            "personal_shelf.updatedAt",
+            eb.fn.count<number>("personal_shelf_item.personalBookId").as("bookCount"),
+          ])
+          .where("personal_shelf.userDid", "=", userDid)
+          .groupBy("personal_shelf.id")
+          .orderBy("personal_shelf.name", "asc")
+          .execute(),
+        ctx.db
+          .selectFrom("personal_book")
+          .select((eb) => eb.fn.countAll<number>().as("total"))
+          .where("userDid", "=", userDid)
+          .executeTakeFirstOrThrow(),
+        getStorageUsage(ctx.db, userDid),
+      ]);
+
+      return json({
+        shelves: shelves.map((s) => ({
+          id: s.id,
+          name: s.name,
+          description: s.description ?? undefined,
+          bookCount: Number(s.bookCount),
+          createdAt: s.createdAt,
+          updatedAt: s.updatedAt,
+        })),
+        totalBooks: Number(counted.total),
+        storage: { usedBytes, quotaBytes: getStorageQuota() },
+      });
+    },
+  });
+
+  // The blob-input twin of POST /library/upload. Both are thin adapters over
+  // `uploadPersonalBook`; the body streams straight to disk from here, so an
+  // oversized or malformed upload is never materialised in memory.
+  router.addProcedure(BuzzBookhiveUploadPersonalBook, {
+    auth: "identity",
+    async handler({ request, params: _params }) {
+      const ctx = getCtx();
+      const { did: userDid } = getAuth();
+      const { filename } = _params as BuzzBookhiveUploadPersonalBook.$params;
+
+      const declared = Number(request.headers.get("content-length"));
+      const result = await uploadPersonalBook({
+        db: ctx.db,
+        kv: ctx.kv,
+        userDid,
+        filename,
+        source: {
+          kind: "stream",
+          // The lexicon declares a blob input, so atcute leaves the body alone
+          // and types it as a stream for us.
+          body: request.body as ReadableStream<Uint8Array>,
+          declaredLength: Number.isFinite(declared) && declared > 0 ? declared : undefined,
+        },
+      });
+
+      if (!result.ok) throw uploadErrorFor(result);
+      return json({
+        book: result.book,
+        storageUsedBytes: result.storageUsedBytes,
+        storageQuotaBytes: result.storageQuotaBytes,
+      });
     },
   });
 
   router.addProcedure(BuzzBookhiveDeletePersonalBook, {
+    auth: "identity",
     async handler({ input: _input }) {
       const ctx = getCtx();
-      const agent = await ctx.getSessionAgent();
-      if (!agent) throw new AuthRequiredError({ message: "Authentication required" });
-      const userDid = agent.did;
+      const { did: userDid } = getAuth();
       const { contentHash } = _input as BuzzBookhiveDeletePersonalBook.$input;
 
       const book = await ctx.db
@@ -1704,18 +1871,26 @@ export function createXrpcRouter<E extends XrpcContext, V extends { ctx: E } = {
         .where("contentHash", "=", contentHash)
         .execute();
 
-      await removeBookDir(userDid, contentHash);
+      // Best-effort: the row is already gone, so the book is out of the library
+      // and out of the quota either way. Failing the request here would 500 an
+      // otherwise-successful delete and send the client into retrying a delete
+      // that now 404s.
+      await removeBookDir(userDid, contentHash).catch((err: unknown) => {
+        ctx.addWideEventContext({
+          personal_book_rm: "failed",
+          error: { message: err instanceof Error ? err.message : String(err) },
+        });
+      });
 
       return json({});
     },
   });
 
   router.addProcedure(BuzzBookhiveLinkPersonalBook, {
+    auth: "identity",
     async handler({ input: _input }) {
       const ctx = getCtx();
-      const agent = await ctx.getSessionAgent();
-      if (!agent) throw new AuthRequiredError({ message: "Authentication required" });
-      const userDid = agent.did;
+      const { did: userDid } = getAuth();
       const { contentHash, hiveId } = _input as BuzzBookhiveLinkPersonalBook.$input;
 
       const book = await ctx.db
@@ -1791,11 +1966,10 @@ export function createXrpcRouter<E extends XrpcContext, V extends { ctx: E } = {
   });
 
   router.addProcedure(BuzzBookhiveUnlinkPersonalBook, {
+    auth: "identity",
     async handler({ input: _input }) {
       const ctx = getCtx();
-      const agent = await ctx.getSessionAgent();
-      if (!agent) throw new AuthRequiredError({ message: "Authentication required" });
-      const userDid = agent.did;
+      const { did: userDid } = getAuth();
       const { contentHash } = _input as BuzzBookhiveUnlinkPersonalBook.$input;
 
       const book = await ctx.db
@@ -1846,11 +2020,10 @@ export function createXrpcRouter<E extends XrpcContext, V extends { ctx: E } = {
   // ── Personal Shelf Management ──
 
   router.addProcedure(BuzzBookhiveCreatePersonalShelf, {
+    auth: "identity",
     async handler({ input: _input }) {
       const ctx = getCtx();
-      const agent = await ctx.getSessionAgent();
-      if (!agent) throw new AuthRequiredError({ message: "Authentication required" });
-      const userDid = agent.did;
+      const { did: userDid } = getAuth();
       const { name, description } = _input as BuzzBookhiveCreatePersonalShelf.$input;
 
       const now = new Date().toISOString();
@@ -1880,11 +2053,10 @@ export function createXrpcRouter<E extends XrpcContext, V extends { ctx: E } = {
   });
 
   router.addProcedure(BuzzBookhiveUpdatePersonalShelf, {
+    auth: "identity",
     async handler({ input: _input }) {
       const ctx = getCtx();
-      const agent = await ctx.getSessionAgent();
-      if (!agent) throw new AuthRequiredError({ message: "Authentication required" });
-      const userDid = agent.did;
+      const { did: userDid } = getAuth();
       const { id, name, description } = _input as BuzzBookhiveUpdatePersonalShelf.$input;
 
       const existing = await ctx.db
@@ -1936,11 +2108,10 @@ export function createXrpcRouter<E extends XrpcContext, V extends { ctx: E } = {
   });
 
   router.addProcedure(BuzzBookhiveDeletePersonalShelf, {
+    auth: "identity",
     async handler({ input: _input }) {
       const ctx = getCtx();
-      const agent = await ctx.getSessionAgent();
-      if (!agent) throw new AuthRequiredError({ message: "Authentication required" });
-      const userDid = agent.did;
+      const { did: userDid } = getAuth();
       const { id } = _input as BuzzBookhiveDeletePersonalShelf.$input;
 
       const existing = await ctx.db
@@ -1966,11 +2137,10 @@ export function createXrpcRouter<E extends XrpcContext, V extends { ctx: E } = {
   });
 
   router.addProcedure(BuzzBookhiveAddToPersonalShelf, {
+    auth: "identity",
     async handler({ input: _input }) {
       const ctx = getCtx();
-      const agent = await ctx.getSessionAgent();
-      if (!agent) throw new AuthRequiredError({ message: "Authentication required" });
-      const userDid = agent.did;
+      const { did: userDid } = getAuth();
       const { shelfId, contentHash } = _input as BuzzBookhiveAddToPersonalShelf.$input;
 
       const shelf = await ctx.db
@@ -2007,11 +2177,10 @@ export function createXrpcRouter<E extends XrpcContext, V extends { ctx: E } = {
   });
 
   router.addProcedure(BuzzBookhiveRemoveFromPersonalShelf, {
+    auth: "identity",
     async handler({ input: _input }) {
       const ctx = getCtx();
-      const agent = await ctx.getSessionAgent();
-      if (!agent) throw new AuthRequiredError({ message: "Authentication required" });
-      const userDid = agent.did;
+      const { did: userDid } = getAuth();
       const { shelfId, contentHash } = _input as BuzzBookhiveRemoveFromPersonalShelf.$input;
 
       const shelf = await ctx.db
@@ -2049,11 +2218,10 @@ export function createXrpcRouter<E extends XrpcContext, V extends { ctx: E } = {
   // ── Sync Progress (XRPC mirrors of KOSync) ──
 
   router.addQuery(BuzzBookhiveGetSyncProgress, {
+    auth: "identity",
     async handler({ params: _params }) {
       const ctx = getCtx();
-      const agent = await ctx.getSessionAgent();
-      if (!agent) throw new AuthRequiredError({ message: "Authentication required" });
-      const userDid = agent.did;
+      const { did: userDid } = getAuth();
       const { contentHash } = _params as BuzzBookhiveGetSyncProgress.$params;
 
       const row = await ctx.db
@@ -2081,11 +2249,10 @@ export function createXrpcRouter<E extends XrpcContext, V extends { ctx: E } = {
   });
 
   router.addProcedure(BuzzBookhivePutSyncProgress, {
+    auth: "identity",
     async handler({ input: _input }) {
       const ctx = getCtx();
-      const agent = await ctx.getSessionAgent();
-      if (!agent) throw new AuthRequiredError({ message: "Authentication required" });
-      const userDid = agent.did;
+      const { did: userDid } = getAuth();
       const input = _input as BuzzBookhivePutSyncProgress.$input;
       const { document, progress, percentage: percentageStr, device, device_id, metadata } = input;
 
@@ -2126,7 +2293,7 @@ export function createXrpcRouter<E extends XrpcContext, V extends { ctx: E } = {
           .set({
             progressData: JSON.stringify(progressData),
             updatedAt: now,
-            ...(filename != null ? { filename } : {}),
+            ...(filename != null ? { filename, filenameKey: filenameKey(filename) } : {}),
             ...(title != null ? { title } : {}),
             ...(authors != null ? { authors } : {}),
           })
@@ -2141,6 +2308,7 @@ export function createXrpcRouter<E extends XrpcContext, V extends { ctx: E } = {
             documentHash: document,
             hiveId: null,
             filename,
+            filenameKey: filenameKey(filename),
             title,
             authors,
             progressData: JSON.stringify(progressData),
@@ -2152,8 +2320,15 @@ export function createXrpcRouter<E extends XrpcContext, V extends { ctx: E } = {
 
       let hiveId = existing?.hiveId ?? null;
 
-      if (!hiveId && (title || authors)) {
-        hiveId = await matchSyncDocument(ctx.db, { title, authors, filename });
+      // Unconditional, and resolved against the user's uploaded files — see the
+      // same call in src/routes/sync/kosync.ts.
+      if (!hiveId) {
+        hiveId = await matchSyncDocumentForUser(ctx.db, userDid, {
+          documentHash: document,
+          title,
+          authors,
+          filename,
+        });
         if (hiveId) {
           await ctx.db
             .updateTable("sync_document")
@@ -2161,6 +2336,9 @@ export function createXrpcRouter<E extends XrpcContext, V extends { ctx: E } = {
             .where("userDid", "=", userDid)
             .where("provider", "=", "kosync")
             .where("documentHash", "=", document)
+            // Fill only an empty link — see the same guard in
+            // src/routes/sync/kosync.ts for why.
+            .where("hiveId", "is", null)
             .execute();
         }
       }
@@ -2174,11 +2352,10 @@ export function createXrpcRouter<E extends XrpcContext, V extends { ctx: E } = {
   });
 
   router.addQuery(BuzzBookhiveListSyncDocuments, {
+    auth: "identity",
     async handler() {
       const ctx = getCtx();
-      const agent = await ctx.getSessionAgent();
-      if (!agent) throw new AuthRequiredError({ message: "Authentication required" });
-      const userDid = agent.did;
+      const { did: userDid } = getAuth();
 
       const rows = await ctx.db
         .selectFrom("sync_document")
diff --git a/vite.config.ts b/vite.config.ts
index 384c9e6..2d1a66f 100644
--- a/vite.config.ts
+++ b/vite.config.ts
@@ -46,6 +46,12 @@ function standaloneBundles(): Plugin {
       name: "waf-solver-worker.js",
       label: "WAF solver worker",
     },
+    {
+      entrypoint: "./src/workers/parse-worker.ts",
+      outdir: "./.output/server/workers",
+      name: "parse-worker.js",
+      label: "Ebook parse worker",
+    },
   ];
 
   return {
@@ -124,11 +130,18 @@ export default defineConfig(({ command }): any => ({
         "./server/plugins/request-tracing.ts",
         "./server/plugins/cache-headers.ts",
       ],
-      // The OG render worker loads @takumi-rs/core (native NAPI-RS bindings) at
-      // runtime in a worker thread, so it never appears in the Rolldown bundle
-      // graph. Explicitly trace it (full trace `*` to copy the platform-specific
-      // optional binding packages) into .output/server/node_modules/.
-      traceDeps: ["@takumi-rs/core*"],
+      // Native NAPI-RS bindings, which resolve their platform-specific `.node`
+      // at runtime and so never appear in the Rolldown bundle graph. The `*`
+      // suffix is a full trace, which is what copies the optional per-platform
+      // binding packages (…-linux-x64-musl for this Alpine image) into
+      // .output/server/node_modules/.
+      //
+      // - @takumi-rs/core: loaded by the OG render worker.
+      // - @resvg/resvg-js: rasterizes SVG book covers on the upload path.
+      //   Missing it does NOT crash — `prepareCover` catches and returns null —
+      //   so an untraced build silently uploads every Standard Ebooks book with
+      //   no cover, which is precisely the bug this was added to fix.
+      traceDeps: ["@takumi-rs/core*", "@resvg/resvg-js*"],
       // Longer cache lifetimes for static assets (fixes Lighthouse "cache lifetime" warnings).
       // Vite emits content-hashed files under /assets/* → safe to cache immutably for 1 year.
       //