Thread VN through serializers/code-ref.ts and delete the no-VN branch

`codeRefAdjustments` carried a no-VN branch reachable from the
`deserializeAbsolute` path because the framework field-deserialize
machinery called it without opts. Now `deserializeAbsolute` accepts
the framework's store parameter and threads `store.virtualNetwork`
into `codeRefAdjustments`, so the no-VN branch in the inner
`resolve` helper is unreachable from any framework-driven path.

Tighten `codeRefAdjustments` to require `opts.virtualNetwork` and
drop the no-VN URL-join fallback. `serialize` also tightens its
opts.virtualNetwork to required; the early-out when opts is missing
preserves the public surface for direct callers that pass no opts.

`deserializeAbsolute` has an early-out when no store is supplied —
only direct test callers reach that path, and they get a passthrough.

The code-ref-test.ts unit test that exercised the `serialize` no-VN
path is updated to pass an empty `new VirtualNetwork()`; the assertion
is unchanged because the URL-form base+ref still resolves the same
way through VN.

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

Author: backspace

packages/host/tests/unit/code-ref-test.ts

@@ -6,6 +6,7 @@ import { module, test } from 'qunit';
 
 import type { Loader, LooseCardResource } from '@cardstack/runtime-common';
 import {
+  VirtualNetwork,
   baseRealm,
   loadCardDef,
   rri,
@@ -194,6 +195,7 @@ module('code-ref', function (hooks) {
     let doc = { data: { id: base.href } };
     let serialized = CodeRefSerializer.serialize(ref, doc, undefined, {
       relativeTo: base,
+      virtualNetwork: new VirtualNetwork(),
     }) as any;
     assert.strictEqual(
       serialized.module,

packages/runtime-common/serializers/code-ref.ts

@@ -1,6 +1,7 @@
 import type {
   BaseDefConstructor,
   BaseInstanceType,
+  CardStore,
 } from 'https://cardstack.com/base/card-api';
 import {
   type ResolvedCodeRef,
@@ -31,17 +32,20 @@ export function serialize(
     trimExecutableExtension?: true;
     maybeRelativeReference?: (reference: string) => string;
     allowRelative?: true;
-    virtualNetwork?: VirtualNetwork;
+    virtualNetwork: VirtualNetwork;
   },
 ): ResolvedCodeRef | {} {
-  let vn = opts?.virtualNetwork;
+  if (!opts) {
+    return { ...codeRef };
+  }
+  let vn = opts.virtualNetwork;
   let baseURL: URL | undefined;
-  if (opts?.relativeTo instanceof URL) {
+  if (opts.relativeTo instanceof URL) {
     baseURL = opts.relativeTo;
-  } else if (typeof opts?.relativeTo === 'string') {
-    baseURL = vn ? vn.toURL(opts.relativeTo) : undefined;
+  } else if (typeof opts.relativeTo === 'string') {
+    baseURL = vn.toURL(opts.relativeTo);
   } else if (doc?.data?.id && typeof doc.data.id === 'string') {
-    baseURL = vn ? vn.toURL(doc.data.id) : undefined;
+    baseURL = vn.toURL(doc.data.id);
   }
   return {
     ...codeRef,
@@ -65,21 +69,33 @@ export async function deserializeAbsolute<T extends BaseDefConstructor>(
   this: T,
   codeRef: ResolvedCodeRef | {},
   relativeTo: RealmResourceIdentifier | URL | undefined,
+  _doc?: unknown,
+  store?: CardStore,
 ): Promise<BaseInstanceType<T>> {
+  if (!store) {
+    // Reached only by direct test callers that bypass the framework
+    // protocol; the framework's field-deserialize path always supplies
+    // a store. Without a VN we can't resolve prefix-form refs or
+    // round-trip URL-form refs through registered mappings, so leave
+    // the codeRef untouched.
+    return { ...codeRef } as BaseInstanceType<T>;
+  }
   return {
     ...codeRef,
-    ...codeRefAdjustments(codeRef, relativeTo),
+    ...codeRefAdjustments(codeRef, relativeTo, {
+      virtualNetwork: store.virtualNetwork,
+    }),
   } as BaseInstanceType<T>;
 }
 
 function codeRefAdjustments(
   codeRef: any,
-  relativeTo?: RealmResourceIdentifier | URL,
-  opts?: Omit<SerializeOpts, 'virtualNetwork'> & {
+  relativeTo: RealmResourceIdentifier | URL | undefined,
+  opts: Omit<SerializeOpts, 'virtualNetwork'> & {
     trimExecutableExtension?: true;
     maybeRelativeReference?: (reference: string) => string;
     allowRelative?: true;
-    virtualNetwork?: VirtualNetwork;
+    virtualNetwork: VirtualNetwork;
   },
 ) {
   if (!codeRef) {
@@ -88,35 +104,18 @@ function codeRefAdjustments(
   if (!isResolvedCodeRef(codeRef)) {
     return {};
   }
-  // The `deserializeAbsolute` field-deserialize path reaches this without
-  // opts (no VN, no `allowRelative`, no `maybeRelativeReference`). For
-  // URL-like refs we can still do a plain URL-join against `relativeTo`
-  // and apply `trimExecutableExtension`. Bare specifiers (e.g.
-  // `@cardstack/boxel-host/…`) throw — `resolve` is wrapped in try/catch
-  // below, so the original ref stays intact for the loader's importMap
-  // shim.
-  let vn = opts?.virtualNetwork;
-  let resolve = (ref: string) => {
-    if (vn) {
-      return resolveModuleHref(ref, relativeTo, vn);
-    }
-    if (!isUrlLike(ref)) {
-      throw new Error(
-        `Cannot resolve bare package specifier "${ref}" — no matching prefix mapping registered`,
-      );
-    }
-    return new URL(ref, relativeTo).href;
-  };
+  let vn = opts.virtualNetwork;
+  let resolve = (ref: string) => resolveModuleHref(ref, relativeTo, vn);
   if (!isUrlLike(codeRef.module)) {
     // Try resolving via registered prefix mappings (e.g., @cardstack/catalog/)
     try {
       let resolved = resolve(codeRef.module);
       if (resolved !== codeRef.module) {
         let module: string = resolved;
-        if (opts?.trimExecutableExtension) {
+        if (opts.trimExecutableExtension) {
           module = trimExecutableExtension(rri(module));
         }
-        if (opts?.allowRelative && opts?.maybeRelativeReference) {
+        if (opts.allowRelative && opts.maybeRelativeReference) {
           module = opts.maybeRelativeReference(module);
         }
         return { module };
@@ -128,10 +127,10 @@ function codeRefAdjustments(
   }
   if (relativeTo) {
     let module: string = resolve(codeRef.module);
-    if (opts?.trimExecutableExtension) {
+    if (opts.trimExecutableExtension) {
       module = trimExecutableExtension(rri(module));
     }
-    if (opts?.allowRelative && opts?.maybeRelativeReference) {
+    if (opts.allowRelative && opts.maybeRelativeReference) {
       module = opts.maybeRelativeReference(module);
     }
     return { module };