feat(runner): throw errors instead of returning empty document on link cycles (#1925)

Changed link resolution behavior to throw errors when detecting cycles or
hitting iteration limits, rather than silently returning an empty document
with a `did:null:null` space.

Changes:
- Modified `resolveLink()` to throw when cycle detected or iteration limit reached
- Removed `createEmptyResolvedFullLink()` helper that created the empty document
- Updated all related tests to expect thrown errors instead of undefined values
- Changed logger severity from warn to error for these conditions
- Enhanced cycle detection error message to include the seen path for debugging

This makes link resolution errors more explicit and easier to debug, rather
than silently failing with an empty document that might be missed.

Author: seefeldb

packages/runner/src/link-resolution.ts

@@ -70,15 +70,17 @@ export function resolveLink(
 
   while (true) {
     if (iteration++ > MAX_PATH_RESOLUTION_LENGTH) {
-      logger.warn(`Link resolution iteration limit reached`);
-      return createEmptyResolvedFullLink(link); // = return link to empty document
+      logger.error(`Link resolution iteration limit reached`);
+      throw new Error(`Link resolution iteration limit reached`);
     }
 
     // Detect cycles.
     const key = JSON.stringify([link.space, link.id, link.path]);
     if (seen.has(key)) {
-      logger.warn(`Link cycle detected ${key}`);
-      return createEmptyResolvedFullLink(link); // = return link to empty document
+      logger.error(`Link cycle detected ${key} [${JSON.stringify([...seen])}]`);
+      throw new Error(
+        `Link cycle detected at ${key} [${JSON.stringify([...seen])}]`,
+      );
     }
     seen.add(key);
 
@@ -258,15 +260,3 @@ export function readMaybeLink(
     return undefined;
   }
 }
-
-function createEmptyResolvedFullLink(
-  link: NormalizedFullLink,
-): ResolvedFullLink {
-  return {
-    ...link,
-    id: "data:application/json,{}",
-    path: [],
-    type: "application/json",
-    space: "did:null:null",
-  } satisfies NormalizedFullLink as unknown as ResolvedFullLink;
-}

packages/runner/test/link-resolution.test.ts

@@ -1005,8 +1005,7 @@ describe("link-resolution", () => {
 
       // When we resolve a circular reference, it should return undefined
       // (the empty document resolves to undefined)
-      const value = cellA.get();
-      expect(value).toBeUndefined();
+      expect(() => cellA.get()).toThrow();
 
       // Case 2: Mutual references A -> B -> A
       const cellB = runtime.getCell<any>(
@@ -1024,8 +1023,8 @@ describe("link-resolution", () => {
       cellB.setRaw(linkToA);
 
       // Both should resolve to undefined
-      expect(cellA.get()).toBeUndefined();
-      expect(cellB.get()).toBeUndefined();
+      expect(() => cellA.get()).toThrow();
+      expect(() => cellB.get()).toThrow();
     });
 
     it("detects cycle when resolving link to its own subpath", async () => {
@@ -1056,15 +1055,10 @@ describe("link-resolution", () => {
       });
 
       try {
-        const resolved = await Promise.race([
-          resolutionPromise,
-          timeoutPromise,
-        ]);
-
-        // This creates: A -> A/foo -> A/foo/foo -> A/foo/foo/foo -> ...
-        // The iteration limit should catch this and return the empty document
-        expect(resolved.id).toBe("data:application/json,{}");
-        expect(resolved.space).toBe("did:null:null");
+        await expect(Promise.race([resolutionPromise, timeoutPromise])).rejects
+          .toThrow(
+            "Link resolution iteration limit reached",
+          );
       } finally {
         // Clean up the timeout if it was set
         if (timeoutId !== undefined) {
@@ -1095,8 +1089,7 @@ describe("link-resolution", () => {
       cellA.setRaw({ x: linkToBy });
       cellB.setRaw({ y: linkToAx });
 
-      const value = cellA.key("x").get();
-      expect(value).toBeUndefined();
+      expect(() => cellA.key("x").get()).toThrow();
     });
 
     it("shows data URI when resolving cyclic links", () => {
@@ -1114,13 +1107,13 @@ describe("link-resolution", () => {
 
       // When we resolve this link at a low level, it should return the empty document
       // with a data: URI indicating the cycle was detected
-      const resolved = resolveLink(
-        tx,
-        cellA.getAsNormalizedFullLink(),
-        "value",
-      );
-      expect(resolved.id).toBe("data:application/json,{}");
-      expect(resolved.space).toBe("did:null:null");
+      expect(() =>
+        resolveLink(
+          tx,
+          cellA.getAsNormalizedFullLink(),
+          "value",
+        )
+      ).toThrow();
     });
 
     it("allows non-cyclic references to the same cell", () => {