Spell out the sync contract: browsing, filtering and sorting never touch the network,
only media bytes and images are on-demand, and a server-derived sort key has to land in a
local column at sync time rather than being requested lazily.
- resolve() no longer discards a stored seed when the bitmap cannot be decoded (it used to
return null, dropping the theme for pre-v12 rows); it falls back to the stored pair
- fold the busy flag into the seed cache value so eviction is atomic (a busy entry could be
evicted from the separate flag LRU while its seed stayed, silently disabling the scrim)
- the artist top bar samples heroBarColor at scroll 0 to match the static HeroGradient, and
drops the wrong scroll estimate and per-pixel recomposition
- rememberOverlaidNameBusy keys its state so the cached flag is read on key change, not only
the first composition; bottomBandBusy bails out on an empty bitmap
- SyncManager now uses a conflated request channel instead of tryLock, so a
request that arrives during a sync (e.g. add-source switching the active
server) is queued and runs afterwards against the then-active source
instead of being dropped.
- Paged loops count raw server rows, not accepted entities, so an empty-id
row on an otherwise full page no longer ends the scan early and prunes
the unseen tail.
- The cap now fails when the page just past it is non-empty, not only when
it is full, matching the bound the error message reports.
- fetchRank rethrows the cap instead of downgrading an over-cap album scan
to empty ranks.
- Docs: the mutex lives in SyncManager, and the prune still holds the
existing-id set.
A full page at the cap is not proof of truncation, so a library whose
size is an exact multiple of the page size failed for no reason. Each
paged loop now keeps going one page past the cap and only throws when
that page comes back non-empty; a library up to the cap syncs normally.
Add a boundary test for the exact-cap case.
Also note the accepted per-batch observer invalidation churn in the sync
code and the architecture doc.
adds docs/architecture.md (stack, layers, data model, sync, search, networking, testing, CI), docs/implementation-plan.md (phases and status), and AGENTS.md for agents and contributors
austinried