Every read first checks the local cache before ever touching the network — the
core of local-first / offline-first mobile architecture:
age = now - insertedAt
age <= TTL → cache HIT (instant)
TTL < age <= TTL+stale → STALE HIT (instant, + background refresh)
age > TTL+stale (or miss) → BLOCKS on network fetch
- TTL — how long a cached entry counts as fresh.
- Stale grace window — with stale-while-revalidate ON, a just-expired
entry is still served instantly while a refresh happens in the background; OFF means
it behaves like an ordinary miss the instant TTL passes.
- Cache slots — capacity; a full cache evicts the least-recently-used entry.
- Network latency — round-trip time a blocking fetch takes on a miss or a full expiry.
- Offline — a cache miss can no longer reach the network at all and is blocked,
while hits and stale hits keep working from local data exactly as before.
This models the read path only — TTL, staleness and hit rate — distinct
from write-queue ordering or cross-device merge sync, which are different mobile-offline mechanics.