Make CardStore.virtualNetwork required

Tighten the CardStore interface so every implementation must expose a
VirtualNetwork. Implementations updated:

- gc-card-store.ts's CardStoreWithGarbageCollection already had it
- render-service.ts's CardStoreWithErrors gains a public getter that
  exposes its existing #virtualNetwork field
- field-configuration-test.gts's DeferredLinkStore test stub gains a
  `virtualNetwork: new VirtualNetwork()` field
- card-api.gts's FallbackCardStore.virtualNetwork getter throws when
  the active loader can't supply one (was `undefined` before); the
  loadCardDocument / loadFileMetaDocument methods that previously
  threw on missing VN drop their now-redundant runtime checks

virtualNetworkFor's external contract stays `VirtualNetwork | undefined`
— that's the documented out-of-scope item for CS-11374 (detached
instances, static parsers). It wraps the getStore(instance).virtualNetwork
access in try/catch so a FallbackCardStore-without-loader-VN reaches the
function as undefined the way callers already expect.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: backspace

packages/base/card-api.gts

@@ -469,10 +469,10 @@ export type GetSearchResourceFunc<T extends CardDef | FileDef = CardDef> = (
 
 export interface CardStore {
   // The VirtualNetwork that owns this store's realm mappings, used for
-  // prefix/RRI resolution during (de)serialization. Optional so test doubles
-  // don't need to implement it; resolution sites degrade — URL-form refs
-  // still URL-join, prefix-form refs pass through unchanged.
-  virtualNetwork?: VirtualNetwork;
+  // prefix/RRI resolution during (de)serialization. Required — every store
+  // implementation must supply one (production stores, test stubs, the
+  // FallbackCardStore).
+  virtualNetwork: VirtualNetwork;
   getCard(url: string): CardDef | undefined;
   getFileMeta(url: string): FileDef | undefined;
   setCard(url: string, instance: CardDef): void;
@@ -4653,12 +4653,17 @@ function getStore(instance: BaseDef): CardStore {
 }
 
 // The VirtualNetwork associated with an instance's store, for prefix/RRI
-// resolution outside this module. Returns undefined when the store can't
-// supply one — callers handle that by degrading to URL math or throwing.
+// resolution outside this module. Returns undefined when the instance is
+// detached (no store, no loader-attached VN) — callers handle that by
+// degrading to URL math or throwing.
 export function virtualNetworkFor(
   instance: BaseDef,
 ): VirtualNetwork | undefined {
-  return getStore(instance).virtualNetwork;
+  try {
+    return getStore(instance).virtualNetwork;
+  } catch {
+    return undefined;
+  }
 }
 
 // Resolve a (possibly prefix-form or relative) reference to an absolute URL
@@ -4712,8 +4717,14 @@ class FallbackCardStore implements CardStore {
   #inFlight: Set<Promise<unknown>> = new Set();
   #loadGeneration = 0; // mirrors host store tracking to detect new loads
 
-  get virtualNetwork(): VirtualNetwork | undefined {
-    return myLoader().getVirtualNetwork();
+  get virtualNetwork(): VirtualNetwork {
+    let vn = myLoader().getVirtualNetwork();
+    if (!vn) {
+      throw new Error(
+        `FallbackCardStore.virtualNetwork requires the active Loader to have a VirtualNetwork`,
+      );
+    }
+    return vn;
   }
 
   getCard(id: string) {
@@ -4774,13 +4785,7 @@ class FallbackCardStore implements CardStore {
     opts?: { dependencyTrackingContext?: RuntimeDependencyTrackingContext },
   ) {
     trackRuntimeInstanceDependency(url, opts?.dependencyTrackingContext);
-    let vn = this.virtualNetwork;
-    if (!vn) {
-      throw new Error(
-        `CardStore.loadCardDocument requires a Loader with a VirtualNetwork`,
-      );
-    }
-    let promise = loadCardDocument(fetch, url, vn);
+    let promise = loadCardDocument(fetch, url, this.virtualNetwork);
     this.trackLoad(promise);
     return await promise;
   }
@@ -4790,13 +4795,7 @@ class FallbackCardStore implements CardStore {
     opts?: { dependencyTrackingContext?: RuntimeDependencyTrackingContext },
   ) {
     trackRuntimeFileDependency(url, opts?.dependencyTrackingContext);
-    let vn = this.virtualNetwork;
-    if (!vn) {
-      throw new Error(
-        `CardStore.loadFileMetaDocument requires a Loader with a VirtualNetwork`,
-      );
-    }
-    let promise = loadFileMetaDocument(fetch, url, vn);
+    let promise = loadFileMetaDocument(fetch, url, this.virtualNetwork);
     this.trackLoad(promise);
     return await promise;
   }

packages/host/app/services/render-service.ts

@@ -68,6 +68,10 @@ export class CardStoreWithErrors implements CardStore {
     this.#virtualNetwork = virtualNetwork;
   }
 
+  get virtualNetwork(): VirtualNetwork {
+    return this.#virtualNetwork;
+  }
+
   getCard(id: string): CardDef | undefined {
     id = this.normalizeKey(id);
     return this.#cards.get(id);

packages/host/tests/integration/field-configuration-test.gts

@@ -4,7 +4,7 @@ import { settled } from '@ember/test-helpers';
 import { getService } from '@universal-ember/test-support';
 import { module, test } from 'qunit';
 
-import { baseRealm, Deferred } from '@cardstack/runtime-common';
+import { baseRealm, Deferred, VirtualNetwork } from '@cardstack/runtime-common';
 import type {
   SingleCardDocument,
   SingleFileMetaDocument,
@@ -44,6 +44,7 @@ import { setupRenderingTest } from '../helpers/setup';
 let loader: Loader;
 
 class DeferredLinkStore implements CardStore {
+  virtualNetwork: VirtualNetwork = new VirtualNetwork();
   private cardInstances = new Map<string, CardDefType>();
   private fileMetaInstances = new Map<string, FileDef>();
   private readyCardDocs = new Map<string, SingleCardDocument>();