CS-11119: cross-replica clearInFlightSearch via realm_index_updated NOTIFY

[lukemelia]

Summary

Phase 1 of CS-11115 added #inFlightSearch on RealmIndexQueryEngine (a Map<string, Promise<LinkableCollectionDocument>>) to dedupe concurrent same-key searchCards calls per replica. Local clears are wired to every same-replica index-update event (Realm.update's onInvalidation + Realm.fullReindex after await completed). The cross-replica gap: when a peer's worker commits a swap to the shared boxel_index, this replica's #inFlightSearch keeps coalescing post-update callers into pre-update pending promises until each self-resolves — bounded window, typically <1 s but 5–10 s for piranha-class deep populateQueryFields walks.

This PR closes the window with a new per-realm post-update NOTIFY channel, and folds the existing #cachedRealmInfo invalidation that already cohabited the same lifecycle point into the same umbrella.

What's in

• REALM_INDEX_UPDATED_CHANNEL = 'realm_index_updated' (constant in runtime-common/realm.ts), payload = realm URL.
• notifyRealmIndexUpdated(dbAdapter, realmURL) free function, parallel in shape to CS-11156's notifyAllFileChanges. Same best-effort semantics — a missed NOTIFY is a bounded staleness window, not data corruption.
• Realm.clearRealmIndexCaches() new public method that drops every read-side cache deriving from the realm's index — currently #inFlightSearch + #cachedRealmInfo. For the listener; mirrors Realm.invalidateCache as a public NOTIFY-receiver entry point.
• Realm.clearRealmIndexCachesAndBroadcast() that bundles local clear + cross-replica NOTIFY in one call. Same shape as clearLocalSourceCachesAndBroadcast from CS-11156.
• Three index-update sites updated in realm.ts (sync Realm.update onInvalidation, deferred-enqueue onInvalidation, Realm.fullReindex post-completed) now call clearRealmIndexCachesAndBroadcast() instead of reaching into the private query engine. The redundant sibling invalidateCachedRealmInfo() at the fullReindex completion path is dropped — now covered by the umbrella.
• RealmIndexUpdatedListener in packages/realm-server/lib/, parallel in shape to RealmFileChangesListener. On NOTIFY, looks up the mounted realm and calls clearRealmIndexCaches(). Wired into main.ts startup + shutDown alongside the file-changes listener.

Umbrella scope

clearRealmIndexCaches covers the read-side caches that go stale when boxel_index moves:

• #inFlightSearch — the searchCards coalesce map (CS-11115 Phase 1). Was the original audit target.
• #cachedRealmInfo + its ETag hash — derived from indexed metadata and realm_registry rows. A from-scratch reindex pass that re-parses /realm.json invalidates it; was already paired with the in-flight clear at the fullReindex completion site. Folding into the umbrella picks up free cross-replica invalidation on peer replicas, closing a small parallel gap.

The other invalidateCachedRealmInfo() callsites (pre-fullIndex setup, the /realm.json route handler, publish/unpublish cross-realm metadata effects) stay direct — they aren't index-update events.

Naming

The channel is named "updated" rather than "swapped": "swap" is internal jargon for the boxel_index_working → boxel_index atomic moment, while "updated" matches the dominant public terminology (Realm.update(), RealmIndexUpdater) and the past-participle pattern of sibling channels (jobs_finished, module_cache_invalidated). The methods use "realm index caches" as the umbrella term mirroring CS-11156's "source caches" framing.

Why a new channel, not an existing one

Channel	Why not
realm_file_changes	Fires at file-WRITE time (before indexing). At that moment the shared boxel_index hasn't been updated yet — clearing #inFlightSearch then would make new callers re-do the same search against unchanged DB state. Wrong layer + wrong time.
jobs_finished	Payload-less, fires for every worker job system-wide. Forcing every replica to scan every mounted realm's #inFlightSearch on every job completion is a sledgehammer.
realm_index_updated (new)	Per-realm payload, fires only at index-update commit. ~Once per indexing batch per realm. Targeted.

Composition with CS-11156

CS-11156 keeps its realm_file_changes:* wildcard for byte-cache invalidation at publish/unpublish/delete (write-event triggered). This PR adds the orthogonal update-event channel. The two together close cross-replica staleness across both byte caches and the read-side index caches.

Tests

packages/realm-server/tests/realm-index-updated-listener-test.ts — 6 new tests, all pass locally:

• 4 dispatch (handleNotification to mounted realm, dropping unmounted, undefined/empty payload guards)
• 2 LISTEN end-to-end through a real PgAdapter.subscribe round-trip (mounted realm clears; unmounted realm is dropped)

Test plan

• New realm-index-updated-listener-test.ts (6/6 pass locally)
• tsc on runtime-common + realm-server — clean
• Prettier clean on touched files
• CI realm-server suite

Linear

CS-11119.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds a new Postgres NOTIFY channel realm_index_updated so that when one replica's worker commits an index swap to the shared boxel_index, peer replicas drop their RealmIndexQueryEngine#inFlightSearch (and #cachedRealmInfo) caches. This closes a small cross-replica staleness window where post-update callers on a peer would coalesce into pre-update pending search promises.

Changes:

• Add REALM_INDEX_UPDATED_CHANNEL constant + notifyRealmIndexUpdated() helper and new Realm.clearRealmIndexCaches() / clearRealmIndexCachesAndBroadcast() methods; route the three local post-update sites (sync/deferred Realm.update onInvalidation and Realm.fullReindex) through the umbrella.
• New RealmIndexUpdatedListener in packages/realm-server/lib/, parallel in shape to RealmFileChangesListener, wired into main.ts startup and shutdown.
• Add realm-index-updated-listener-test.ts (4 dispatch + 2 LISTEN end-to-end tests) and register it in the test index.

Reviewed changes

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

Show a summary per file

File	Description
packages/runtime-common/realm.ts	Define new NOTIFY channel + helper; add clearRealmIndexCaches/...AndBroadcast; route the three post-update sites through the umbrella and drop the redundant invalidateCachedRealmInfo at fullReindex completion.
packages/realm-server/lib/realm-index-updated-listener.ts	New listener subscribing to realm_index_updated, dispatching to realm.clearRealmIndexCaches() for mounted realms.
packages/realm-server/main.ts	Instantiate RealmIndexUpdatedListener at startup and include it in shutdown sequence.
packages/realm-server/tests/realm-index-updated-listener-test.ts	Unit + LISTEN end-to-end tests for dispatch, unmounted-realm drop, and empty/undefined payload guards.
packages/realm-server/tests/index.ts	Register the new test module in the runner.

---

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

[github-actions]

Host Test Results

    1 files  ±    0      1 suites  ±0   1h 45m 42s ⏱️ - 1h 42m 22s
2 661 tests ±    0  2 646 ✅ ±    0  15 💤 ± 0  0 ❌ ±0 
2 680 runs   - 2 586  2 665 ✅  - 2 571  15 💤  - 15  0 ❌ ±0 

Results for commit 8328ba5. ± Comparison against earlier commit 9359cff.

Realm Server Test Results

    1 files  ±0      1 suites  ±0   7m 51s ⏱️ -9s
1 405 tests +5  1 405 ✅ +5  0 💤 ±0  0 ❌ ±0 
1 492 runs  +5  1 492 ✅ +5  0 💤 ±0  0 ❌ ±0 

Results for commit 8328ba5. ± Comparison against earlier commit 9359cff.