[pkmetski]

Root cause

The elided-view (annotations) tab was fed entirely from the local Room DB, but the only code path that pulls peer annotation files from WebDAV/ABS into Room was AnnotationSyncController.syncOnOpen — gated on opening each individual book in the reader. On a fresh device (or after reconfiguring sync), all annotations exist on the sync backend but the tab showed nothing until every annotated book was opened.

Additionally, for ABS-only users, the AnnotationSyncTargetHolder seeds with sources = emptyList() before the init coroutine fires, causing the pull sweep to race startup and see a null target → immediate no-op.

Fix

AnnotationSyncController.pullAll(sourceId, namespace) — new method that:

• Calls AnnotationSyncTarget.enumerateDevices(namespace) (single PROPFIND, not one per book)
• Groups peer annotation files by itemId
• Merges each book's peer files via the existing AnnotationMergeOrchestrator.mergeFromListing LWW policy
• Holds per-book ReconcileLocks so the pull never interleaves with a concurrent live push
• Skips this device's own file (already in Room)

AnnotationPullSweep — new pull-only sweep class (companion to the push-only AnnotationSweep) that iterates all configured sources and calls pullAll for each.

AnnotationSyncTargetHolder.awaitFirstLoad() — CompletableDeferred that signals when the init coroutine's first source-driven build completes. The pull sweep awaits it before reading current(), eliminating the startup race.

Null→non-null watcher (Android + iOS) — re-runs the pull sweep whenever the holder transitions from null to non-null mid-session (e.g., source added or re-authed), so the tab populates without requiring a restart. Initial value prevNull=false prevents a duplicate sweep at startup.

Wired into the same app-lifecycle triggers as the push sweep:

• Android: runs on app start + on connectivity return via kickSweepsOnReconnect
• iOS: runs on app-active + reconnect via ForegroundSyncDriver.runAnnotationSweep

Battery impact

The null→non-null watcher is a StateFlow.collect — idle between user-driven source changes. No polling, no timers. enumerateDevices is a single PROPFIND; the ABS target caches GET /api/me for 3s to prevent N+1 calls.

Code review fixes applied

• buildTarget wrapped in try/finally so firstLoad.complete(Unit) always fires even if a factory throws (prevents awaitFirstLoad from deadlocking callers)
• prevNull initialised to false so startup null→non-null doesn't fire a second concurrent sweep alongside the explicit launch
• PullRecordingTarget.read() now scopes by itemId ("$itemId/$filename" key with fallback); multi-item test uses per-item scoped keys with distinct annotation IDs so item-routing bugs are detectable

Follow-up (not in this PR)

AnnotationSweep (push) still passes { holder.current() } as its target provider, which returns null for ABS-only users during the brief startup window before the init coroutine fires — pre-existing behaviour, tracked separately.

Performance

One PROPFIND per source (not per book) via enumerateDevices, then N reads for peer files. Runs in background (Android: applicationScope = Dispatchers.IO; iOS: Dispatchers.Default). The tab live-updates as Room rows land.

Tests

• AnnotationPullSweepTest — 8 scenarios in commonTest: unconfigured target no-op, no-peer no-op, peer annotations merged, multiple items (item-scoped fixture), own-device file skipped, multiple sources, no-namespace source skipped, enumerateDevices failure
• AnnotationSyncControllerLifecycleTest — 3 new pullAll tests: no-target no-op, peers merged + own skipped, multiple items
• AnnotationSyncTargetHolderTest (androidHostTest) — 5 new tests: awaitFirstLoad resolves, idempotent, observe() null initial, null→non-null, non-null→null
• AnnotationSyncTargetHolderStartupTest (commonTest) — 5 mirrored tests running on the iOS simulator via :core:data:iosSimulatorArm64Test

Simulator screenshot evidence

n/a — non-visual (data-layer/sync changes only)

🤖 Generated with Claude Code