[ldt1996]

⊙ Problem

When allowStaleWhileRevalidate serves an expired record, every read also queued its own background refresh behind the running one. If the source kept failing, each queued refresh called it again and logged a warning: one source call and one warning per read. 300 stale reads of a record whose source fails after 150 ms made 300 calls and 300 warnings over 45 seconds.

💡 Solution

• A stale read starts a refresh only if no other request holds that record's fetch. Otherwise it returns the stale record.
• The read after a failed refresh starts a new one.
• allowStaleWhileRevalidate now runs before the refresh starts.
• Reads that cannot be served stale still wait for the fetch.
• Stacked on Release a source fetch's record lock only from the fetch that took it #4366, whose 10-second hold limit frees a record whose refresh never settles; this PR's base is that branch until it merges.

🤔 Skip, or queue one retry?

A stale read that finds the record busy skips the refresh, so after a failed refresh the record stays stale until the next read. Queueing one retry per record would refresh sooner, at the cost of a waiting request per record. Switching later touches only the stale path.

⚖️ Alternatives

The planning review found a better approach than the one first proposed, a hasLock pre-check: take the lock atomically with a callback-free tryLock, and refresh only on success. This PR adopts it.

Framing-Verdict: better-alternative-exists

• Check hasLock, then lock inside the fetch — two threads can both see the record free and both refresh.
• Back off after a failed refresh — a freshness policy; a separate design.

🔧 Changes

• resources/Table.ts: the stale path takes the record lock with a callback-free tryLock and hands it to getFromSource through a new lockHeld parameter, which skips the fetch's own tryLock. A busy record returns stale at once. A tryLock that throws is logged, and the read serves stale. getFromSource releases a handed-over lock if anything before the fetch owns it throws, from reading the context to issuing the version.
• docs/reference/resources/resource-api.md: a v5.4.1 paragraph on the single refresh and the earlier hook call.

Product and architecture tour

Product and architecture tour

One refresh per expired record

What does a read of an expired record do when stale serving is allowed?

Before	After
Every stale read returned the stale record and queued its own refresh behind the running one; after a failure, each queued refresh called the source again.	A stale read refreshes only if it can take the record lock at once; otherwise it returns the stale record and does nothing more.

A stale read, step by step

1. Ask the hook — allowStaleWhileRevalidate decides whether this read may be served stale.
2. Try the lock — a callback-free tryLock, so a busy record registers no waiter.
3. Busy: return stale — another request's fetch owns the record; nothing is queued.
4. Free: refresh in the background — the read hands the held lock to getFromSource and returns the stale record.
5. Release — the fetch releases the lock at commit, or when its hold ends if the source never settles.

A read that may not be served stale still waits for the fetch, as before.
Record locks are per database on RocksDB, so a fetch of the same id in another table of the database also makes a stale read skip; that keying is tracked separately.

✅ Verification

• Fails on main, in unitTests/resources/staleRefreshOncePerKey.test.js: reads queue a refresh each; the query path makes 2 calls, expected 1; a record another thread holds is refreshed anyway.
• 8 of 8 pass on RocksDB and LMDB, including a worker thread holding the record lock and a refresh that never settles. Without the setup-throw release, its test fails. The full unit suites fail only tests that also fail on main on the same machine; one record-lock test that failed in this branch's RocksDB run is flaky on main too (2 of 10 runs alone fail there, 0 of 10 here).
• 4 threads, 300 stale reads, refresh failing after 150 ms: main made 300 source calls and logged 300 warnings over 45.8 s; this branch made 1 call and logged 1 warning in 0.2 s. All reads were answered from stale within 4 ms on both.
• Performance: fresh hits do no new work. A stale read adds one tryLock, and a busy record skips the refresh setup.
• PR QA: skipped @ 8414d3c — Dispatch is not available in this session.

Test cases

• Concurrent stale reads start one refresh; after it fails, no read had queued its own, and the next read refreshes.
• A successful refresh replaces the record.
• A read that may not be served stale still waits for the refresh.
• Concurrent queries over a stale row start one refresh.
• A tryLock that throws is logged, and the read serves stale.
• A context that throws once the lock is held releases it; the next read refreshes.
• A refresh whose source never settles keeps the record busy only until its hold limit; the next read refreshes again.
• A worker thread holding the record lock: the read serves stale and queues nothing; after the release, a read refreshes.

_{🤖 Generated by Claude Opus 5.5 (Claude Code); posted via @ldt1996.}

Release target: v5.4 — main is the 5.4 line; fixes stale-while-revalidate behavior that shipped in 5.4.0

Related PRs: #2155 overlaps (its drain may assume getFromSource takes the fill lock), #2918 overlaps (a lock handed in by a stale read skips the acquisition it orders), 5 others independent
Complexity: complicated

Deferred findings

• 78defa8349fe2006 minor correctness — resources/Table.ts — Database-wide bare-id fill lock makes a stale read skip its refresh when another table fills the same id — NOT FILED
• 6aef72546c35fcc8 nit correctness — resources/Table.ts — Background refresh .then mutates the leading stale read's context after it returned — NOT FILED
• 210a587193a7fbb1 nit maintainability — resources/Table.ts — New comments in the lock-tenure prerequisite (Table.ts:461, :14338, sourceFillLockTenure.test.js) — NOT FILED

_{Review-Coverage: authored=claude; ran=codex,gemini,gemini-carbon; late=gemini-carbon:adjudicated; adjudicated=domain; blocked=cursor-composer(not-installed); declined=cursor-grok,muse; rounds=8; full=3 @ 8414d3c}

_{Review-Attention: deep ~35m (critical: Table.ts; decisions: stale-busy-skip, waiters-never-unlock, fixed-10s-tenure, do-less-alternative, release-target-unclear; raised: degraded review) @ 8414d3c}

[kriszyp]

_{🤖 Reviewed with Muse Wonder 1.0 · adjudicated by Codex}

[kriszyp]

[nit] Possible LMDB-only failure in the foreign-lock test remains disputed