Pin file-api as a runtime dep of file extracts (flaky test fix)

[habdelra]

Problem

prerendering-test.ts > prerender - non-mutating tests > runner behavior > file prerender returns extracted metadata intermittently fails on the assertion:

deps include base file-api module
  actual  : false
  expected: true

Most recent failure: https://github.com/cardstack/boxel/actions/runs/26289527361/job/77386270791

The file-extract pipeline only natively imports ${baseRealm.url}card-api (because baseFileRef.module resolves there — that's where the FileDef class actually lives). The public ${baseRealm.url}file-api URL — which is what the indexer keys on when invalidating file extracts — landed in deps only because matrix-service's fileAPIModule = importResource(() => '…/file-api') happened to call loader.import('file-api') synchronously inside the active withRuntimeDependencyTrackingContext window.

Whether that import landed inside the window was a microtask-scheduling race. It was reliable on a fresh page but flaky after a BrowserManager.restartBrowser() (e.g., from a preceding test like concurrent restart coalescing), where the matrix-service resource fires either too early (before the route starts the session) or too late (after extract() resolves).

Prior art

PR #4875 attempted to fix this by pinning the imports in RenderRoute.#buildModel, but that ran the imports for every render — card prerenders too — and was reverted because it introduced cross-test instability.

Solution

Pin loader.import('${baseRealm.url}file-api') only inside the file-extract route's withRuntimeDependencyTrackingContext. This makes the dep deterministic for file extracts and is invisible to the card-prerender path, so it can't reintroduce the destabilisation that closed #4875.

Adds a console.warn diagnostic that fires if file-api is still missing from the snapshot after the explicit import — insurance in case the tracker session is ever closed early or the URL is rewritten.

Files

• packages/host/app/routes/render/file-extract.ts

Test plan

• CI passes on this branch (specifically the Realm Server Tests shards)
• No card-prerender regressions in prerendering-test.ts (the broader test module)

[github-actions]

Preview deployments

• Host staging preview

• Host production preview

Host Test Results

    1 files      1 suites   1h 49m 50s ⏱️
2 724 tests 2 707 ✅ 15 💤 0 ❌ 2 🔥
2 743 runs  2 724 ✅ 15 💤 2 ❌ 2 🔥

Results for commit 2f6ca5b.

For more details on these errors, see this check.

Realm Server Test Results

    1 files      1 suites   10m 15s ⏱️
1 482 tests 1 482 ✅ 0 💤 0 ❌
1 573 runs  1 573 ✅ 0 💤 0 ❌

Results for commit 2f6ca5b.

[Copilot]

Pull request overview

This PR makes runtime dependency tracking for file extracts deterministic by explicitly importing the base realm file-api module within the file-extract route’s dependency-tracking context, addressing an intermittent prerender test failure where file-api sometimes failed to appear in the extracted deps.

Changes:

• Import ${baseRealm.url}file-api inside withRuntimeDependencyTrackingContext so it is always recorded as a runtime dependency for file extracts.
• Add a diagnostic console.warn if file-api is still missing from the merged dependency snapshot after the explicit import.

---

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

[habdelra]

Closing — moving the same fix into #4934 directly. The failure is deterministic on that branch (4/4 recent RS shard 1 runs failed on prerendering-test.ts > file prerender returns extracted metadata), not a transient flake, so it makes sense to land the fix in the same PR rather than as a standalone.