Stop flaky atomic instance batch depending on unindexed modules

[habdelra]

What was flaky

atomic-endpoints-test.ts > ... > writes > can write multiple instances that depend on each other intermittently fails in CI with a 500 and FilterRefersToNonexistentTypeError for the Place type (failing run).

Root cause

The test does two separate /_atomic writes: first place.gts + country.gts (modules), then Country/Place instances that adopt from them.

/_atomic returns once writes are durable, not indexed, and _batchWriteUnlocked run with waitForIndex: false deliberately skips waiting for a prior write's pending index (so consecutive atomic writes stay responsive). So the second batch's fileSerialization can look up the Place definition while the first batch's modules are still indexing. That on-demand definition lookup then races the in-flight module index: the generation bump discards the prerender result and the lookup returns undefined, so the whole batch rolls back with a 500. Under CI load the module index lags into that window; locally it usually wins, so it only flakes in CI.

The existing module-before-instance ordering handles modules and instances within a single batch. This test splits them across two batches, so that path never applies.

Fix

The first batch is setup for the second, so it posts with ?waitForIndex=true. The modules are indexed before the instance batch runs, which removes the race. This is the documented way for a caller writing modules and then dependent instances across separate batches to stay correct.

Diagnostics kept alongside the fix

So a recurrence is debuggable without a rerun:

• The atomic 500 handler now logs e.cause. FilterRefersToNonexistentTypeError carries the actionable detail (which module/definition was missing, or that a concurrent invalidation discarded the lookup) in its cause, not its message.
• The instance-batch assertion prints the response body on a non-201.

[Copilot]

Pull request overview

This PR addresses a CI flake in the realm-server atomic write tests caused by issuing two separate /_atomic batches where the second batch depends on modules from the first before those modules are indexed. It also improves server-side diagnostics so future atomic-batch 500s preserve the most actionable underlying error detail.

Changes:

• Make the module-setup /_atomic request in atomic-endpoints-test.ts opt into waitForIndex=true so the subsequent instance batch can’t race module indexing.
• Improve atomic-write 500 logging to include e.cause (message + stack when it’s an Error) so root causes like FilterRefersToNonexistentTypeError aren’t swallowed.
• Enhance the test assertion to print the response body when the instance batch doesn’t return 201.

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	Logs e.cause details when an atomic write fails, improving debuggability of intermittent 500s.
packages/realm-server/tests/atomic-endpoints-test.ts	Uses /_atomic?waitForIndex=true for module setup and prints response body on failure to eliminate and diagnose the flaky race.

---

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

[github-actions]

Host Test Results

    1 files      1 suites   2h 47m 9s ⏱️
3 433 tests 3 418 ✅ 15 💤 0 ❌
3 452 runs  3 437 ✅ 15 💤 0 ❌

Results for commit da84d4f.

Realm Server Test Results

    1 files      1 suites   12m 17s ⏱️
1 765 tests 1 765 ✅ 0 💤 0 ❌
1 844 runs  1 844 ✅ 0 💤 0 ❌

Results for commit da84d4f.