test(deflake): deterministic BookRegistry write-seams + ~57 wall-clock-wait conversions (#1331)

* [swarm_ad0b4c65] swarm scaffold: wall-clock-wait elimination plan + manifest

Architect triage of the ~675-wait-token population: collapses to 12 new
XCTest-gated Task-join seams across 16 contracts in 3 waves. Correctness
over volume — no bounded wait replaced by an unbounded await.

**Scope:** swarm scaffolding only (plan + manifest); per-module contracts,
implementer diffs, and integration land in subsequent commits on this branch.
**Not done:** the 16 per-module contract bodies + any code — pending user GO.

* [swarm_ad0b4c65] wave-1 infra contracts: S1/S2 registry, S3 network, S4/S11 download

**Scope:** the 3 critical-path wave-1 seam contracts only (prod-only, no test
files). Wave-2/3 contracts authored after wave-1 seams land (so they cite real
signatures).
**Not done:** wave-2/3 module contracts + all call-site conversions.

* [swarm_ad0b4c65] wave-1 infra seams: S1/S2 registry, S3 network, S4/S11 download

Adds deterministic, XCTest-gated Task-join / barrier-drain seams so Wave-2 test
conversions can await fire-and-forget async work instead of wall-clock polling.
BUILD SUCCEEDED on the Palace target (iPhone 16 Pro sim).

- S1 BookRegistryStore._awaitPendingWritesForTesting — trailing-barrier drain
  (concurrent-queue .barrier ⇒ always drains; no handle await).
- S2 TPPBookRegistry._awaitPendingWritesForTesting — forwards to S1 + one main hop;
  skips the intrinsic switch-back debounce.
- S3 TPPNetworkExecutor/Responder._awaitInFlightForTesting — grow-until-stable
  join over the completion Tasks fired off the URLSession delegate queue;
  terminal synchronous completion + watchdog deliberately not retained.
- S4 MyBooksDownloadCenter._awaitDownloadDispatchForTesting — grow-until-stable
  join over all 14 fire-and-forget Task spawns (retention gated by XCTest).
- S11 DownloadProgressPublisher throttle interval made injectable (prod default
  0.5s unchanged; RELEASE byte-identical).

All retention arrays populated ONLY under _isRunningUnderXCTest; RELEASE spawns
identical work and never reads/populates them. Every seam is BOUNDED — a barrier
that always drains or a retained Task that completes; no bare never-resuming
await, no added sleep/poll/Date/Timer; NSLock never held across a suspension.

**Scope:** wave-1 production seams only (6 files); no test files change here.
**Not done:** wave-2/3 module contracts + the ~550-620 call-site conversions
that consume these seams; those land in subsequent commits after per-contract
CI verification.

* [swarm_ad0b4c65] wave-2 conversion playbook (seam catalog + bounded-await rule + bucket protocol)

**Scope:** the shared wave-2 playbook only.
**Not done:** the 12 module conversions.

* [swarm_ad0b4c65] wave-2: land validated S1/S2 conversions; drop S3/S4/S11 (no/broken consumers)

Wave-2 fanned 12 module agents over the full PalaceTests suite to convert
wall-clock/deadline-poll waits to the wave-1 seams. Honest outcome: the
"~675 sites" premise was a mismeasure — most waits are already-converted (prior
#1319 sweep) or legitimate KEEP (bounded by a direct synchronous injected-mock
callback, the correct pattern). Real net-new conversions concentrate in the
registry seams.

LANDED (verified green — 161 tests, 0 failures on iPhone 16 Pro sim):
- S1 BookRegistryStore._awaitPendingWritesForTesting + S2 TPPBookRegistry (kept
  from the wave-1 commit) — ~51 real consumers across Book + BookRegistry.
- Converted: Book (BookRegistryStoreTests, BookRegistrySyncTests),
  BookRegistry (7 files), BookStateManagement (BookCellModelStateTests) — all
  wait(for:)/waitForExpectations on registry fire-and-forget writes → the S1/S2
  barrier-drain seams; async-context DispatchGroup waits use `await fulfillment`.
- Accounts (AccountsManagerTests, AccountsManagerStateMachineWiringTests) —
  6 conversions using EXISTING primitives (drainMainQueue / awaitCondition),
  no production seam; deleted a global().asyncAfter settle-pad + a Thread.sleep poll.

DROPPED (this commit reverts the wave-1 seams that didn't earn their place):
- S3 TPPNetworkExecutor/Responder._awaitInFlightForTesting — 1 consumer, and that
  conversion FAILED (testSessionInvalidationCallsPendingCompletionsWithCancelError:
  seam join returned without the cancellation completion). Marginal + broken → out.
- S4 MyBooksDownloadCenter + S11 DownloadProgressPublisher — 0 consumers
  (MyBooks tests use synchronous mocks per "never hit real singletons"). Unused
  test-only production surface is a blast-radius liability → out.

The 8 other modules correctly produced 0 conversions (already-done / legit KEEP /
UNMAPPED-needs-unbuilt-seam). UNMAPPED clusters flagged for a possible targeted
Wave 3: HoldsViewModel debounce (15), OfflineQueueService (12), AudiobookLoader
(5), BookmarkManager.waitForBarrier (~20), SignInLogic main-hops (46, mostly
drainMainQueueAsync-able). Full per-module transcripts under transcripts/.

**Scope:** S1/S2 registry seams + ~57 verified test-only conversions; drop
S3/S4/S11.
**Not done:** Wave-3 targeted seams (Holds/OfflineQueue) — deferred, pending a
decision they're worth the production surface. The remaining raw wait-token count
is intentional (legitimate KEEP), not a silent cap.

---------

Co-authored-by: t <t@t.io>

Author: mauricecarrier7

.forgeos/swarms/swarm_ad0b4c65/.swarm_id

@@ -0,0 +1 @@
+swarm_ad0b4c65

.forgeos/swarms/swarm_ad0b4c65/CONVERSION_PLAYBOOK.md

@@ -0,0 +1,65 @@
+# Wave-2 Conversion Playbook — swarm_ad0b4c65
+
+Every Wave-2 module implementer follows THIS. Your job: convert the wall-clock /
+deadline-poll waits in YOUR test directory to deterministic seam-joins, DELETE
+the always-bad ones, and LEAVE the legitimate ones. Test files only — you do NOT
+edit production (the seams already exist, see catalog).
+
+## THE ONE INVIOLABLE RULE
+**Never introduce an unbounded `await`.** A bounded `wait(for:[e], timeout: 5)`
+replaced by `await handle.value` on a handle that may never resume is a
+REGRESSION worse than the flake. Every `await` you write in a converted test MUST
+target one of the enumerated seams below (each bounded by a barrier drain or a
+grow-until-stable Task join), OR a `withCheckedContinuation` you resume from a
+real callback. If a wait does NOT map to an enumerated seam, do NOT invent one —
+leave it as-is and record it in your transcript's `UNMAPPED` list for the
+orchestrator. When in doubt, KEEP + flag; never guess.
+
+## Seam catalog (Wave-1, already in the tree at this branch)
+| Seam | Await from a test as | Bounded because |
+|---|---|---|
+| `BookRegistryStore._awaitPendingWritesForTesting()` | `await store._awaitPendingWritesForTesting()` | trailing barrier on a concurrent queue always drains |
+| `TPPBookRegistry._awaitPendingWritesForTesting()` | `await registry._awaitPendingWritesForTesting()` | forwards to S1 + one main hop |
+| `TPPNetworkExecutor._awaitInFlightForTesting()` | `await executor._awaitInFlightForTesting()` | grow-until-stable join over completion Tasks |
+| `MyBooksDownloadCenter._awaitDownloadDispatchForTesting()` | `await center._awaitDownloadDispatchForTesting()` | grow-until-stable join over all spawned Tasks |
+| `DownloadProgressReporter(throttleInterval:)` | construct with `throttleInterval: 0` in tests | removes the 0.5s throttle deterministically |
+| **Pre-existing** (already used elsewhere — mirror those call sites): `AccountsManager._awaitAllCrawlTasksForTesting`, `CatalogRepository._awaitAllBackgroundRefreshesForTesting`, `TokenRefreshInterceptor._awaitAuthDispatchForTesting`, `CatalogViewModel._awaitLoadForTesting`, `CatalogSearchViewModel._awaitInFlightWorkForTesting`, `AudiobookBookmarkBusinessLogic._awaitPositionWriteForTesting`, `NowPlayingCoordinator._awaitPendingUpdateForTesting`, `AppHealthViewModel.awaitLoadForTesting` | | |
+
+The `drainMainQueue` / `drainMainQueueAsync` / `awaitCondition(Async)` helpers in
+`PalaceTests/XCTestCase+drainMainQueue.swift` are BOUNDED PRIMITIVES — you MAY
+use `await drainMainQueueAsync()` to flush a single main-hop after a seam join.
+Do NOT edit that file (OFF-LIMITS to every module).
+
+## Bucket protocol — for each wait occurrence in your test dir
+1. **CONVERT** — a `wait(for:)`/`waitForExpectations`/`fulfillment(of:)`/
+   `awaitCondition` that is waiting on fire-and-forget async whose owning
+   production class has a seam in the catalog → replace the expectation+wait with
+   `await <seam>()` then assert synchronously. Remove the now-dead
+   `XCTestExpectation` and its `.fulfill()`. Make the test method `async` if not
+   already.
+   - If the class is `@MainActor`, the test is already on the main actor;
+     `await seam()` is fine.
+   - After the join, state is settled — assert directly, no re-poll.
+2. **DELETE** — `Thread.sleep`, `usleep`, `asyncAfter { …fulfill() }` used purely
+   as a settle delay, `Task.sleep`-as-delay, hand-rolled `while Date() < deadline`.
+   Remove and assert deterministically (usually a seam join replaces the intent).
+3. **KEEP** (leave byte-for-byte, list in transcript `KEPT`):
+   - Expectations fulfilled by a DIRECT synchronous injected callback (no async hop, no CPU race).
+   - Negative "nothing fired" assertions with a short deliberate window (`timeout: 0.3` asserting ABSENCE) — these are intrinsically time-based.
+   - Mock schedulers / injected-clock/delay simulations (the mock's contract).
+   - Any wait on a 3rd-party completion (audiobook toolkit / LCP / Adobe DRM) with no production seam → KEEP or bridge with an IN-TEST `withCheckedContinuation` resumed from the completion (no production change).
+4. **UNMAPPED** (record, do NOT convert): a fire-and-forget wait whose class has NO
+   catalog seam. Leave as-is; list it so the orchestrator can decide (maybe a
+   Wave-3 seam). Do NOT invent an unbounded await.
+
+## Verification (paste in your transcript before reporting done)
+- `grep -c 'wait(for:\|waitForExpectations\|fulfillment(of:' <each changed file>` — report the before→after count; the remainder must equal your KEPT+UNMAPPED count (never a silent drop).
+- `grep -nE 'Thread.sleep|usleep|asyncAfter.*fulfill|while.*Date\(\).*<' <your test dir>` → empty (all DELETEd).
+- **Bounded-await proof:** for every `await …ForTesting()` / continuation you added, cite which catalog seam it targets. NO bare `await someTask.value` on a raw handle.
+- Do NOT edit production `Palace/**` or `PalaceTests/XCTestCase+drainMainQueue.swift` or any other module's test dir.
+
+## Output
+Do NOT commit/push. Leave converted files in your worktree. Write your transcript
+to the orchestrator path given in your dispatch prompt with: files changed,
+per-file before→after wait counts, the CONVERT/DELETE/KEPT/UNMAPPED tallies, and
+the bounded-await citations.

.forgeos/swarms/swarm_ad0b4c65/contracts/BookRegistryInfra.md

@@ -0,0 +1,80 @@
+# Contract — BookRegistryInfra (Wave 1, risk: critical_path)
+
+## Goal
+Add two deterministic test-join seams so tests never wall-clock-wait on the
+registry's barrier-queue writes or its main-thread broadcast hops. **Prod-only —
+no test files change in this contract.** Highest fan-in (Book, BookRegistry,
+MyBooks, Holds, BookStateManagement, Sync, Bookmarks depend on these).
+
+## Files in scope (edit ONLY these)
+- `Palace/Book/Models/BookRegistryStore.swift`
+- `Palace/Book/Models/TPPBookRegistry.swift`
+
+## OFF-LIMITS
+- Every `PalaceTests/**` file (Wave 2 converts call sites, not this contract).
+- Any other `Palace/**` file. If you find you need to touch one, STOP and report.
+
+## Seams to add
+
+### S1 — `BookRegistryStore._awaitPendingWritesForTesting() async`
+The store serializes mutations on a barrier queue (see `performBarrier(...)`,
+~line 193). A trailing barrier is bounded by construction: a FIFO barrier block
+runs only after every previously-enqueued `addBook`/`removeBook`/`updateBook`
+block (and its `onComplete`) has finished. Enqueue one and await it:
+```swift
+/// Test-only: await all writes enqueued before this call. Bounded — a FIFO
+/// barrier block runs only after every prior mutation block has completed.
+/// No XCTest gate needed: this spawns NO retained state, it only drains the
+/// existing queue (production never calls it).
+func _awaitPendingWritesForTesting() async {
+    await withCheckedContinuation { cont in
+        performBarrier { cont.resume() }
+    }
+}
+```
+- If `performBarrier`'s real name/signature differs, adapt to the actual barrier
+  primitive — the REQUIREMENT is "enqueue a trailing block on the same serial/
+  barrier queue and resume the continuation from it." Do NOT add a sleep/poll.
+- Keep it `internal` (reachable via `@testable import Palace`), documented test-only.
+
+### S2 — `TPPBookRegistry._awaitPendingWritesForTesting() async`
+Forwards to S1, then drains the registry's own `DispatchQueue.main.async`
+state-broadcast hops (the notification/`@Published` re-broadcasts, ~lines
+617/633/648/661/682) by awaiting one main-queue hop:
+```swift
+/// Test-only: await the store's pending writes (S1) THEN one main-queue hop so
+/// the registry's state broadcasts have been delivered. Deliberately does NOT
+/// await the intrinsic account switch-back debounce (asyncAfter ~line 160) —
+/// that is a UX timer, not fire-and-forget work; tests asserting switch-back
+/// drive it explicitly.
+func _awaitPendingWritesForTesting() async {
+    await store._awaitPendingWritesForTesting()   // adapt to the actual store accessor
+    await withCheckedContinuation { cont in
+        DispatchQueue.main.async { cont.resume() }
+    }
+}
+```
+- Adapt `store.` to however `TPPBookRegistry` references its `BookRegistryStore`.
+- If the registry is an `@objc`/singleton with no direct store handle in a
+  testable scope, expose the minimal internal accessor needed (document it
+  test-only) rather than reaching through `.shared`.
+
+## Verification criteria (grep-able; paste evidence)
+1. Both seams exist and compile:
+   `grep -n '_awaitPendingWritesForTesting' Palace/Book/Models/BookRegistryStore.swift Palace/Book/Models/TPPBookRegistry.swift` → 2 defs.
+2. **No unbounded await introduced:** each seam's `await` targets either a
+   `withCheckedContinuation` resumed from a barrier/main hop, or S1. `grep -n
+   'await' <files>` — every await is one of those two shapes; NO bare
+   `await someHandle.value` on a handle that may never resume.
+3. **No new clock:** `grep -nE 'sleep|asyncAfter|Date\(\)|Timer' ` on the ADDED
+   lines returns nothing (the added seams introduce no delay).
+4. Build the app target compiles (CI-gated; if you can build locally, paste the
+   tail; otherwise state "CI-gated build" honestly).
+5. Seams are `internal`/test-documented, not `public`: `grep -n 'public func _await' <files>` → empty.
+
+## Notes for the implementer
+- Mirror the canonical existing seams for tone/placement: `AccountsManager
+  ._awaitAllCrawlTasksForTesting`, `TokenRefreshInterceptor._awaitAuthDispatchForTesting`.
+- This contract adds NO tests (it's infra). Wave-2 contracts consume these seams.
+- Do NOT commit; leave staged for the integrator. Write your transcript to
+  `.forgeos/swarms/swarm_ad0b4c65/transcripts/BookRegistryInfra.md`.

.forgeos/swarms/swarm_ad0b4c65/contracts/DownloadCenterInfra.md

@@ -0,0 +1,55 @@
+# Contract — DownloadCenterInfra (Wave 1, risk: critical_path)
+
+## Goal
+Add a deterministic download-dispatch join seam (S4) and make the progress
+throttle injectable (S11) so tests never wall-clock-wait on
+`MyBooksDownloadCenter`'s fire-and-forget `Task {}`s or the +0.5s progress
+throttle. **Prod-only — no test files change here.** Fan-in: MyBooks, Book.
+
+## Files in scope (edit ONLY these)
+- `Palace/MyBooks/MyBooksDownloadCenter.swift`
+- `Palace/MyBooks/DownloadProgressPublisher.swift`
+
+## OFF-LIMITS
+- Every `PalaceTests/**` file. Any other `Palace/**` — STOP and report if needed.
+
+## Seams to add
+
+### S4 — `MyBooksDownloadCenter._awaitDownloadDispatchForTesting() async`
+The class already retains one handle (`lastNetworkLossFailureTask`, ~line 217)
+and spawns many fire-and-forget `Task {}` (~lines 1197/1228/1290/1371/1419).
+Generalize to an XCTest-gated `[Task<Void, Never>]` + grow-until-stable join,
+identical in shape to S3 / `_awaitAuthDispatchForTesting`:
+- Add the canonical gate `_isRunningUnderXCTest`.
+- At each fire-and-forget `Task { … }` spawn site, when under XCTest, append the
+  `Task` handle to a lock-guarded array (synchronous snapshot; NSLock never held
+  across `await`).
+- `func _awaitDownloadDispatchForTesting() async` drains the array in a
+  re-snapshotting loop until empty. Bounded because each retained `Task` is the
+  actual dispatched unit and completes.
+- RELEASE spawns the identical `Task`s and never populates/reads the array.
+
+### S11 — injectable throttle in `DownloadProgressPublisher`
+The publisher broadcasts via `asyncAfter(+0.5s)` (an intrinsic throttle, NOT a
+flake — do NOT delete it). Make the interval injectable so tests set it to 0:
+- Add a stored `throttleInterval: TimeInterval` (or inject a scheduler),
+  defaulting to the current 0.5s in the production initializer so behavior is
+  byte-identical in RELEASE.
+- Replace the hard-coded `0.5` in the `asyncAfter` with the stored interval.
+- Do NOT remove the throttle; only make its interval configurable.
+
+## Verification criteria (paste evidence)
+1. `grep -n '_awaitDownloadDispatchForTesting\|_isRunningUnderXCTest' Palace/MyBooks/MyBooksDownloadCenter.swift`.
+2. **XCTest gate proven:** each handle append is guarded by `_isRunningUnderXCTest`.
+3. **Bounded join:** grow-until-stable over retained `Task.value`; no bare
+   never-resuming `await`, no `sleep`/poll on added lines.
+4. **Throttle preserved, not deleted:** `grep -n 'throttleInterval\|asyncAfter' Palace/MyBooks/DownloadProgressPublisher.swift` shows the asyncAfter still present, now driven by the injectable interval; the production default is still 0.5s (`grep` the initializer default).
+5. **No RELEASE timing change:** the default initializer path is unchanged; the array is only populated under XCTest.
+6. Build compiles (CI-gated; state honestly if unavailable).
+
+## Notes
+- Canonical reference: `TokenRefreshInterceptor.spawnAuthDispatch` +
+  `_awaitAuthDispatchForTesting`. This is critical-path (borrow/download) — a
+  broken seam corrupts download completion under CI. Be conservative.
+- No tests here. Transcript →
+  `.forgeos/swarms/swarm_ad0b4c65/transcripts/DownloadCenterInfra.md`. Do NOT commit.

.forgeos/swarms/swarm_ad0b4c65/contracts/NetworkInfra.md

@@ -0,0 +1,68 @@
+# Contract — NetworkInfra (Wave 1, risk: critical_path)
+
+## Goal
+Add a deterministic test-join seam so tests never wall-clock-wait on
+`TPPNetworkExecutor`/`TPPNetworkResponder` completions that fire off the URLSession
+`delegateQueue`. **Prod-only — no test files change here.** Fan-in: Network,
+MyBooks downloads, Book, SignInLogic token refresh.
+
+## Files in scope (edit ONLY these)
+- `Palace/Network/TPPNetworkExecutor.swift`
+- `Palace/Network/TPPNetworkResponder.swift`
+
+## OFF-LIMITS
+- Every `PalaceTests/**` file. Any other `Palace/**` file — STOP and report if needed.
+
+## Seam to add
+
+### S3 — `TPPNetworkExecutor._awaitInFlightForTesting() async`
+The responder dispatches completion handlers off the session `delegateQueue`
+(fire-and-forget relative to the caller). Extend the existing test-seam infra on
+this class (`claimTokenRefreshSlotForTesting`/`currentTokenRefreshGenerationForTesting`,
+~lines 280-283) with an XCTest-gated retained-handle join, mirroring
+`TokenRefreshInterceptor._awaitAuthDispatchForTesting` (grow-until-stable loop):
+- Add, guarded by the canonical gate:
+  ```swift
+  private static let _isRunningUnderXCTest =
+      ProcessInfo.processInfo.environment["XCTestConfigurationFilePath"] != nil
+  ```
+- Where the responder/executor spawns each completion-dispatch `Task {}` (or
+  `delegateQueue.async {}`), when `_isRunningUnderXCTest`, ALSO retain the unit
+  of work as a `Task<Void, Never>` handle appended to an internal, lock-guarded
+  `[Task<Void, Never>]`. Snapshot the array **synchronously** under an `NSLock`
+  (NSLock across a suspension is a Swift 6 error), then `await` the handles in
+  the caller, re-snapshotting until the set stops growing (mirror
+  `_awaitAuthDispatchForTesting`, lines ~526-575 of TokenRefreshInterceptor).
+  ```swift
+  func _awaitInFlightForTesting() async {
+      while true {
+          let handles: [Task<Void, Never>] = { lock.lock(); defer { lock.unlock() }; let s = pendingTestTasks; pendingTestTasks.removeAll(); return s }()
+          if handles.isEmpty { break }
+          for h in handles { await h.value }
+      }
+  }
+  ```
+- If completions currently run via `delegateQueue.async` (not a `Task`), wrap the
+  work so a retained `Task` awaits the same completion, OR bridge the queue hop
+  via `await withCheckedContinuation { c in delegateQueue.async { …; c.resume() } }`.
+  The REQUIREMENT: the seam resolves exactly when all in-flight completions have
+  run. Do NOT change production timing when NOT under XCTest — RELEASE must spawn
+  the identical work and never populate/read the array.
+
+## Verification criteria (paste evidence)
+1. `grep -n '_awaitInFlightForTesting\|_isRunningUnderXCTest\|pendingTestTasks' Palace/Network/TPPNetworkExecutor.swift Palace/Network/TPPNetworkResponder.swift`.
+2. **XCTest gate proven:** every retain of a handle is inside an
+   `if …_isRunningUnderXCTest` (or equivalent) guard — grep shows the guard
+   wraps the append. RELEASE never appends.
+3. **Bounded join:** the seam awaits retained `Task.value` handles in a
+   grow-until-stable loop; NO bare `await` on a handle that could never resume,
+   NO `sleep`/`Date()`/poll on the added lines.
+4. **NSLock not held across `await`:** the snapshot is a synchronous closure;
+   grep the seam to confirm no `lock()` spans an `await`.
+5. Build compiles (CI-gated; state honestly if local build unavailable).
+
+## Notes
+- Canonical reference to copy: `Palace/MyBooks/TokenRefreshInterceptor.swift`
+  `spawnAuthDispatch` (retain site) + `_awaitAuthDispatchForTesting` (join).
+- No tests in this contract. Transcript →
+  `.forgeos/swarms/swarm_ad0b4c65/transcripts/NetworkInfra.md`. Do NOT commit.