perf(offline): reuse coherent Argument base caches when already offline (#740)
Summary
Continues #740 after merged writer profiling #757. Once PRKS has confirmed it is offline, Argument acknowledged-base reads (sync revision-state and full Argument record) may reuse coherent existing offline-cache records instead of each making a ~1s known-failing network attempt.
Only those acknowledged-base reads opt into preferCacheWhenOffline. Every other entity read remains server-first. Original durable-queue persistence, acknowledged revision checks, conflict behavior, and offline return provenance are preserved.
Safety guards
- A cache hit is eligible only in confirmed
offline, never online/reconnecting; a miss uses the existing read-through implementation. - Both entity and Arguments-domain invalidation fences are checked before and after IndexedDB resolves, including races against failed cache deletions.
- A monotonic connectivity generation prevents a stale result from crossing offline → online → offline during a pending IndexedDB read, even when the final connectivity state looks identical.
- No unknown revision or base is fabricated; abort signals do not trigger the fast path.
- Deterministic Node selftests cover ordinary server-first reads, cache hit/miss, invalidated records, blocked domains, reconnection, and in-flight invalidation/round-trip transitions.
Same-runner A/B proof
One-off exact-ref Chromium A/B run #39140250984 succeeded, with one excluded warm-up per ref and three alternating measured trials per side.
| Profiled phase | Baseline median | Candidate median |
|---|---|---|
| Whole isolated test | 16.476 s | 12.412 s |
| Target offline Argument rename write | 1.875 s | 0.005 s |
| Response offline Argument rename write | 1.949 s | 0.005 s |
The 4.064 s (24.7%) median improvement refers to this profiled offline Argument test only; no full-suite speedup is claimed. A subsequent safety-only reconnect-generation guard was added, so final-head validation is still required.
The temporary A/B workflow has been removed from the final diff. The P2 review thread requesting its removal has been resolved. No permanent scheduled CI cost remains.
Acceptance
- Successful isolated same-runner baseline/candidate Chromium A/B.
- Remove temporary experiment workflow from PR.
- Resolve P2 cleanup review comment.
- Add coherent-cache and reconnect/invalidation race tests.
- Record evidence in #740.
- All exact-final-head full E2E, packaged E2E, tests, lint and security gates pass.
No merge without explicit maintainer approval.
Summary by cubic
Improves offline Argument ack-base reads by serving coherent cached data when the runtime is confirmed offline, avoiding ~2s of failed network read-through attempts.
- Adds an opt-in
preferCacheWhenOfflineoption on entity read-through, used only for the Argument acknowledged-base revision and record reads; the default remains server-first. - Guards the fast path with coherence checks before and after IndexedDB access: invalidated rows, blocked domains, and generation changes force the normal network path, and a monotonic connectivity token rejects cached results across offline → reconnect → offline cycles and when invalidation or reconnection races a pending cache read.
- The same-runner Chromium A/B benchmark confirmed a median test wall time drop of 16.476s → 12.412s (~24.7%) on the profiled offline test; the dedicated one-off workflow has been removed.