Resolve cross-realm file links instead of erroring

[lukemelia]

Problem

A card that links to a file in another realm — e.g. an image referenced via linksTo(FileDef) whose file lives in a different realm than the card — fails to load with an HTTP 500. This commonly happens with cards instantiated from the catalog: the card moves into the user's workspace but its image link still points at the file in the catalog realm.

RealmIndexQueryEngine.loadLinks partitions each relationship into in-realm cards, in-realm file-meta, and cross-realm targets. The in-realm path already resolves both cards and files, but the cross-realm path (fetchCrossRealmLinks) assumed every target was a card:

if (!isSingleCardDocument(json)) {
  throw new Error(`instance ${url} is not a card document. it is: ...`);
}

When the remote realm returned a file-meta document for the linked file, the throw fired and the request 500'd, dropping the card into an error state.

Fix

fetchCrossRealmLinks now accepts file-meta documents as well, mirroring the in-realm path. Its return type widens to CardResource | FileMetaResource (the downstream Step-4 consumer already accepts that union), and it only throws on a genuinely unrecognized payload.

Test

Added a regression test (card-endpoints-test.ts → cross-realm file links): a provider realm hosts a file, a consumer realm has a card linking to it cross-realm, and a GET asserts HTTP 200 with the file-meta resource present in included[]. Verified it fails with the original 500 symptom when the fix is reverted, and passes with it.

Resolves CS-11344.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Fixes a runtime failure when loadLinks resolves cross-realm relationships whose targets are files (JSON:API file-meta documents) rather than cards. This aligns the cross-realm resolution path with the existing in-realm behavior so catalog-hosted assets (like images/markdown files) linked from workspace cards no longer trigger HTTP 500s.

Changes:

• Broadened fetchCrossRealmLinks to accept both SingleCardDocument and SingleFileMetaDocument, returning CardResource | FileMetaResource instead of assuming every cross-realm target is a card.
• Updated the loadLinks cross-realm map typing to match the widened return type.
• Added a regression test ensuring a card with a cross-realm linksTo(FileDef) relationship is served successfully and includes the file-meta resource in included[].

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
packages/runtime-common/realm-index-query-engine.ts	Accepts cross-realm file-meta payloads in fetchCrossRealmLinks and widens related types to prevent 500s on valid file links.
packages/realm-server/tests/card-endpoints-test.ts	Adds a regression test covering cross-realm file link resolution and asserting HTTP 200 + file-meta included resource.

---

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

[github-actions]

Host Test Results

    1 files      1 suites   1h 51m 17s ⏱️
2 931 tests 2 916 ✅ 15 💤 0 ❌
2 950 runs  2 935 ✅ 15 💤 0 ❌

Results for commit dbf9ba7.

Realm Server Test Results

    1 files  ±0      1 suites  ±0   10m 13s ⏱️ -26s
1 550 tests ±0  1 549 ✅ ±0  1 💤 ±0  0 ❌ ±0 
1 641 runs  ±0  1 640 ✅ ±0  1 💤 ±0  0 ❌ ±0 

Results for commit dbf9ba7. ± Comparison against earlier commit 525a8e4.