CS-11030: cross-process transpile coalesce via module_transpile_cache

[lukemelia]

Summary

• New module_transpile_cache table (UNLOGGED, RAM-backed, like the modules definition cache). Keyed on (realm_url, canonical_path). Columns: nullable body/headers/dependency_keys (so tombstones can sit in the row without bytes), generation BIGINT NOT NULL DEFAULT 0, created_at.
• Lifts Realm.#moduleCache from purely in-memory L1 to L1+L2. L1 stays in-process for hot-path latency; L2 is the cross-process shared layer.
• OCC writes. The writer captures the row's generation at the L2 read step (or 0 if absent), transpiles, then UPSERTs with that captured value via ON CONFLICT DO UPDATE WHERE existing.generation <= EXCLUDED.generation. An invalidate that lands during the transpile bumps the row past the captured value, so the writer's UPSERT is rejected by the WHERE clause and a stale transpile started before the invalidate cannot resurrect the row.
• Tombstone-and-bump on invalidate. #deleteTranspileCacheRow UPSERTs body=NULL, generation = generation+1 rather than physically DELETEing. Physical DELETE would let a slow in-flight writer's INSERT succeed (no conflict, no row to compare against) and resurrect the stale bytes. Bulk wipe (#deleteAllTranspileCacheRows from __testOnlyClearCaches) likewise UPDATEs all rows to tombstones with bumped gen.
• Read path: L1 miss → in-flight dedup (CS-11029) → L2 read → coordinator winner/loser → babel → L2 OCC-protected persist.
• Coordinator: reuses the existing ModuleCacheCoordinator (CS-10953) and MODULE_CACHE_POPULATED_CHANNEL. The coalesce key prefix (transpile|... vs the CachingDefinitionLookup shape) keeps the two flows separate; waiters dispatch off the bounded int64 hash, so crosstalk is a benign hash miss.
• Invalidation: every CS-11028 invalidation site (writeMany, delete/deleteAll, file-watcher callback, handleExecutableInvalidations cascade, full-index clear, public invalidateCache) now fire-and-forget tombstones the matching L2 row alongside the in-memory drop. Every peer's listener runs the same tombstone-and-bump on its own copy → self-healing on transient pg blips and idempotent on the bump.
• main.ts passes the existing moduleCacheCoordinator as transpileCoordinator to every Realm it constructs.

The CS-11028 generation guard protects the in-memory L1 write; the new DB-resident generation column protects the L2 write. Together they close both layers of the invalidate-during-transpile race.

Linear: https://linear.app/cardstack/issue/CS-11030

Test plan

• CI passes the Realm.#moduleCache L2 module_transpile_cache (DB-backed) module:
  • fresh transpile populates module_transpile_cache
  • L2 row serves a subsequent reader after L1 wipe (no re-transpile)
  • invalidateCache tombstones the L2 row and bumps generation
  • in-flight transpile that completes after invalidate cannot resurrect the L2 row (direct OCC guard exercise)
• Existing CS-11028 + CS-11029 race/dedup tests still pass.
• Existing CS-10953 ModuleCacheCoordinator tests still pass — the coordinator is unchanged; we just route a second flow through it.
• Module-cache regression tests in realm-endpoints-test.ts still pass (etag, 304, content-type).

Follow-ups (NOT in this PR)

• Two-instance integration test mirroring module-cache-coordination-test.ts for the transpile flow (gated babel + advisory-lock contention → exactly one transpile across both instances).
• Bulk-wipe edge case: #deleteAllTranspileCacheRows bumps existing rows but doesn't tombstone paths that didn't yet have a row, so an in-flight writer for one of those paths could still resurrect. Narrow, only reachable from __testOnlyClearCaches.
• Periodic tombstone GC if the table grows materially (UNLOGGED, but still bounded only by total path cardinality).
• Carry dependency_keys through the L2 write so cross-process load skips the extractModuleDependencyKeys recomputation in fallbackHandle.

🤖 Generated with Claude Code

[github-actions]

Preview deployments

• Host staging preview

• Host production preview

Host Test Results

    1 files      1 suites   2h 3m 48s ⏱️
2 658 tests 2 643 ✅ 15 💤 0 ❌
2 677 runs  2 662 ✅ 15 💤 0 ❌

Results for commit 66ead90.

Realm Server Test Results

    1 files  ±0      1 suites  ±0   11m 8s ⏱️ - 2m 37s
1 334 tests +7  1 334 ✅ +8  0 💤 ±0  0 ❌  - 1 
1 413 runs  +7  1 413 ✅ +8  0 💤 ±0  0 ❌  - 1 

Results for commit 66ead90. ± Comparison against earlier commit 62a2c38.