Fix flaky boxel-cli push --delete: guard #sourceCache against set-after-invalidate

[habdelra]

The boxel-cli push --delete integration test (removes remote-only files) fails intermittently in CI: after the delete-push returns 204 and the file is gone from disk, the test's immediate source GET for the removed file returns 200 instead of 404.

Root cause

The realm server's getSourceOrRedirect serves .gts / .json source from an in-memory #sourceCache. It reads the bytes from disk under an await (getFileWithFallbacks + materializeFileRef) and only then calls #sourceCache.set. If invalidateCache(path) fires inside that window it clears the slot synchronously — but the in-flight read's set re-populates it afterward with the now-stale bytes. #sourceCache had no guard against this, even though #transpiledModuleCache was already hardened against the identical set-after-invalidate race.

The failing run's realm-server log shows the exact interleave: the prior push's waitForIndex:false indexing job for the same file was still in flight (its source fetch had read the bytes) when the delete-push's DELETE landed. The DELETE removed the file and invalidated the cache, then the indexing fetch's set re-cached the just-deleted bytes — and the next source GET came back a 200 cache hit (dur=2ms) for a file already gone from disk.

Fix

Give #sourceCache the same per-path + global generation guard #transpiledModuleCache already uses:

• getSourceOrRedirect snapshots the source-cache generation before its first await and drops its set when the resolved path's generation moved during the read (keyed on the canonical path, so extensionless-alias requests are covered too).
• invalidateCache, the bypass-cache early invalidate, and the bulk clears bump the generation.
• Every dropped stale set is logged, so if the race ever recurs through a path the snapshot didn't cover, the next occurrence still leaves a signal.

The in-flight reader still serves the bytes it read at request time (consistent with its happens-before ordering); only the cache write is discarded.

Tests

A new deterministic module in module-cache-race-test.ts uses a test-only gate that parks a source read at the post-read / pre-set point and races concurrent work against it:

• invalidate during the read → next GET is a cache miss (set discarded)
• delete during the read → next GET is 404, not a stale 200 — the realm-server-level reproduction of the flake
• unrelated-path invalidate → the set survives (cache hit; per-path scoping intact)
• __testOnlyClearCaches during the read → cache miss (the global generation catches what the path counter alone would miss)

eslint + prettier clean and the type declarations build; the realm-server test shard exercises the new tests in CI.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR fixes an intermittent stale-read race in the realm server’s source-serving path by hardening Realm.#sourceCache against “set-after-invalidate” when a source read is in-flight during a concurrent invalidation (notably DELETE). The change mirrors the existing generation-guard strategy already used for #transpiledModuleCache, preventing deleted or outdated bytes from being re-cached and subsequently served as a fast cache hit.

Changes:

• Add per-path and global generation counters for #sourceCache, and drop cache writes when an invalidate/clear occurs during an in-flight read.
• Route all single-path and bulk source-cache invalidations through generation-bumping helpers.
• Add deterministic realm-server regression tests using a test-only gate to park a request between “read bytes” and “cache set”, reproducing the race without timing flakiness.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
packages/runtime-common/realm.ts	Adds generation guards + helper invalidation methods for #sourceCache, and a test-only delay hook to deterministically reproduce the race window.
packages/realm-server/tests/module-cache-race-test.ts	Adds a new test module that deterministically verifies #sourceCache does not re-populate with stale bytes after concurrent invalidate/delete/clear.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[github-actions]

Host Test Results

    1 files      1 suites   1h 52m 20s ⏱️
2 936 tests 2 921 ✅ 15 💤 0 ❌
2 955 runs  2 940 ✅ 15 💤 0 ❌

Results for commit eb7d9a5.

Realm Server Test Results

    1 files      1 suites   11m 46s ⏱️
1 563 tests 1 562 ✅ 1 💤 0 ❌
1 654 runs  1 653 ✅ 1 💤 0 ❌

Results for commit eb7d9a5.