fix: Fix launch-subcluster RPC result type for JSON compatibility

Use nullable() instead of optional() for bootstrapResult field, and
define a JSON-compatible LaunchSubclusterRpcResult type that uses null
instead of undefined for JSON serialization.

Also update tests to match the new behavior.

Co-Authored-By: Claude Opus 4.5 <[email protected]>

Author: rekmarks

packages/kernel-browser-runtime/src/kernel-worker/captp/kernel-facade.test.ts

@@ -1,18 +1,37 @@
-import type { ClusterConfig, Kernel, KRef, VatId } from '@metamask/ocap-kernel';
+import type {
+  ClusterConfig,
+  Kernel,
+  KernelStatus,
+  KRef,
+  VatId,
+} from '@metamask/ocap-kernel';
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 
 import { makeKernelFacade } from './kernel-facade.ts';
 import type { KernelFacade } from './kernel-facade.ts';
 
+const makeClusterConfig = (): ClusterConfig => ({
+  bootstrap: 'v1',
+  vats: {
+    v1: {
+      bundleSpec: 'test-source',
+    },
+  },
+});
+
 describe('makeKernelFacade', () => {
   let mockKernel: Kernel;
   let facade: KernelFacade;
 
   beforeEach(() => {
     mockKernel = {
       launchSubcluster: vi.fn().mockResolvedValue({
-        body: '#{"status":"ok"}',
-        slots: [],
+        subclusterId: 'sc1',
+        bootstrapRootKref: 'ko1',
+        bootstrapResult: {
+          body: '#{"result":"ok"}',
+          slots: [],
+        },
       }),
       terminateSubcluster: vi.fn().mockResolvedValue(undefined),
       queueMessage: vi.fn().mockResolvedValue({
@@ -22,12 +41,9 @@ describe('makeKernelFacade', () => {
       getStatus: vi.fn().mockResolvedValue({
         vats: [],
         subclusters: [],
-        remoteComms: false,
-      }),
-      pingVat: vi.fn().mockResolvedValue({
-        pingVatResult: 'pong',
-        roundTripMs: 10,
+        remoteComms: { isInitialized: false },
       }),
+      pingVat: vi.fn().mockResolvedValue('pong'),
     } as unknown as Kernel;
 
     facade = makeKernelFacade(mockKernel);
@@ -42,94 +58,41 @@ describe('makeKernelFacade', () => {
 
   describe('launchSubcluster', () => {
     it('delegates to kernel with correct arguments', async () => {
-      const config: ClusterConfig = {
-        name: 'test-cluster',
-        vats: [
-          {
-            name: 'test-vat',
-            bundleSpec: { type: 'literal', source: 'test' },
-          },
-        ],
-      };
+      const config = makeClusterConfig();
 
       await facade.launchSubcluster(config);
 
       expect(mockKernel.launchSubcluster).toHaveBeenCalledWith(config);
       expect(mockKernel.launchSubcluster).toHaveBeenCalledTimes(1);
     });
 
-    it('returns result from kernel with parsed subclusterId and wrapped kref', async () => {
+    it('returns result with subclusterId and rootKref from kernel', async () => {
       const kernelResult = {
-        body: '#{"subclusterId":"s1"}',
-        slots: ['ko1'],
+        subclusterId: 's1',
+        bootstrapRootKref: 'ko1',
+        bootstrapResult: { body: '#null', slots: [] },
       };
       vi.mocked(mockKernel.launchSubcluster).mockResolvedValueOnce(
         kernelResult,
       );
 
-      const config: ClusterConfig = {
-        name: 'test-cluster',
-        vats: [],
-      };
+      const config = makeClusterConfig();
 
       const result = await facade.launchSubcluster(config);
 
-      // The facade should parse the CapData and return a LaunchResult
       expect(result).toStrictEqual({
         subclusterId: 's1',
-        rootKref: { kref: 'ko1' },
-        rootKrefString: 'ko1',
+        rootKref: 'ko1',
       });
     });
 
     it('propagates errors from kernel', async () => {
       const error = new Error('Launch failed');
       vi.mocked(mockKernel.launchSubcluster).mockRejectedValueOnce(error);
 
-      const config: ClusterConfig = {
-        name: 'test-cluster',
-        vats: [],
-      };
-
-      await expect(facade.launchSubcluster(config)).rejects.toThrow(error);
-    });
-
-    it('throws when kernel returns no capData', async () => {
-      vi.mocked(mockKernel.launchSubcluster).mockResolvedValueOnce(
-        undefined as unknown as ReturnType<Kernel['launchSubcluster']>,
-      );
-
-      const config = makeClusterConfig();
-
-      await expect(facade.launchSubcluster(config)).rejects.toThrow(
-        'launchSubcluster: expected capData with root kref',
-      );
-    });
-
-    it('throws when capData body has no subclusterId', async () => {
-      vi.mocked(mockKernel.launchSubcluster).mockResolvedValueOnce({
-        body: '#{}',
-        slots: ['ko1'],
-      });
-
-      const config = makeClusterConfig();
-
-      await expect(facade.launchSubcluster(config)).rejects.toThrow(
-        'launchSubcluster: expected subclusterId in body',
-      );
-    });
-
-    it('throws when capData slots is empty', async () => {
-      vi.mocked(mockKernel.launchSubcluster).mockResolvedValueOnce({
-        body: '#{"subclusterId":"sc1"}',
-        slots: [],
-      });
-
       const config = makeClusterConfig();
 
-      await expect(facade.launchSubcluster(config)).rejects.toThrow(
-        'launchSubcluster: expected root kref in slots',
-      );
+      await expect(facade.launchSubcluster(config)).rejects.toThrow(error);
     });
   });
 
@@ -194,10 +157,10 @@ describe('makeKernelFacade', () => {
     });
 
     it('returns status from kernel', async () => {
-      const expectedStatus = {
-        vats: [{ id: 'v1', name: 'test-vat' }],
+      const expectedStatus: KernelStatus = {
+        vats: [{ id: 'v1' as VatId, name: 'test-vat' }],
         subclusters: [],
-        remoteComms: true,
+        remoteComms: { isInitialized: true },
       };
       vi.mocked(mockKernel.getStatus).mockResolvedValueOnce(expectedStatus);
 
@@ -215,7 +178,7 @@ describe('makeKernelFacade', () => {
 
   describe('pingVat', () => {
     it('delegates to kernel with correct vatId', async () => {
-      const vatId: VatId = 'v1';
+      const vatId: VatId = 'v1' as VatId;
 
       await facade.pingVat(vatId);
 
@@ -224,18 +187,25 @@ describe('makeKernelFacade', () => {
     });
 
     it('returns result from kernel', async () => {
-      const expectedResult = { pingVatResult: 'pong', roundTripMs: 5 };
+      const expectedResult = 'pong';
       vi.mocked(mockKernel.pingVat).mockResolvedValueOnce(expectedResult);
 
-      const result = await facade.pingVat('v1');
-      expect(result).toStrictEqual(expectedResult);
+      const result = await facade.pingVat('v1' as VatId);
+      expect(result).toBe(expectedResult);
     });
 
     it('propagates errors from kernel', async () => {
       const error = new Error('Ping vat failed');
       vi.mocked(mockKernel.pingVat).mockRejectedValueOnce(error);
 
-      await expect(facade.pingVat('v1')).rejects.toThrow(error);
+      await expect(facade.pingVat('v1' as VatId)).rejects.toThrow(error);
+    });
+  });
+
+  describe('getVatRoot', () => {
+    it('returns wrapped kref', async () => {
+      const result = await facade.getVatRoot('ko123');
+      expect(result).toStrictEqual({ kref: 'ko123' });
     });
   });
 });

packages/kernel-browser-runtime/src/rpc-handlers/launch-subcluster.test.ts

@@ -44,6 +44,32 @@ describe('launchSubclusterHandler', () => {
       { kernel: mockKernel },
       params,
     );
-    expect(result).toBe(mockResult);
+    expect(result).toStrictEqual(mockResult);
+  });
+
+  it('converts undefined bootstrapResult to null for JSON compatibility', async () => {
+    const mockResult = {
+      subclusterId: 's1',
+      bootstrapRootKref: 'ko1',
+      bootstrapResult: undefined,
+    };
+    const mockKernel = {
+      launchSubcluster: vi.fn().mockResolvedValue(mockResult),
+    };
+    const params = {
+      config: {
+        bootstrap: 'test-bootstrap',
+        vats: {},
+      },
+    };
+    const result = await launchSubclusterHandler.implementation(
+      { kernel: mockKernel },
+      params,
+    );
+    expect(result).toStrictEqual({
+      subclusterId: 's1',
+      bootstrapRootKref: 'ko1',
+      bootstrapResult: null,
+    });
   });
 });

packages/kernel-browser-runtime/src/rpc-handlers/launch-subcluster.ts

@@ -1,31 +1,38 @@
+import type { CapData } from '@endo/marshal';
 import type { MethodSpec, Handler } from '@metamask/kernel-rpc-methods';
-import type {
-  Kernel,
-  ClusterConfig,
-  SubclusterLaunchResult,
-} from '@metamask/ocap-kernel';
+import type { Kernel, ClusterConfig, KRef } from '@metamask/ocap-kernel';
 import { ClusterConfigStruct, CapDataStruct } from '@metamask/ocap-kernel';
 import {
   object,
   string,
-  optional,
+  nullable,
   type as structType,
 } from '@metamask/superstruct';
 
-const SubclusterLaunchResultStruct = structType({
+/**
+ * JSON-compatible version of SubclusterLaunchResult for RPC.
+ * Uses null instead of undefined for JSON serialization.
+ */
+type LaunchSubclusterRpcResult = {
+  subclusterId: string;
+  bootstrapRootKref: string;
+  bootstrapResult: CapData<KRef> | null;
+};
+
+const LaunchSubclusterRpcResultStruct = structType({
   subclusterId: string(),
   bootstrapRootKref: string(),
-  bootstrapResult: optional(CapDataStruct),
+  bootstrapResult: nullable(CapDataStruct),
 });
 
 export const launchSubclusterSpec: MethodSpec<
   'launchSubcluster',
   { config: ClusterConfig },
-  Promise<SubclusterLaunchResult>
+  Promise<LaunchSubclusterRpcResult>
 > = {
   method: 'launchSubcluster',
   params: object({ config: ClusterConfigStruct }),
-  result: SubclusterLaunchResultStruct,
+  result: LaunchSubclusterRpcResultStruct,
 };
 
 export type LaunchSubclusterHooks = {
@@ -35,15 +42,21 @@ export type LaunchSubclusterHooks = {
 export const launchSubclusterHandler: Handler<
   'launchSubcluster',
   { config: ClusterConfig },
-  Promise<SubclusterLaunchResult>,
+  Promise<LaunchSubclusterRpcResult>,
   LaunchSubclusterHooks
 > = {
   ...launchSubclusterSpec,
   hooks: { kernel: true },
   implementation: async (
     { kernel }: LaunchSubclusterHooks,
     params: { config: ClusterConfig },
-  ): Promise<SubclusterLaunchResult> => {
-    return kernel.launchSubcluster(params.config);
+  ): Promise<LaunchSubclusterRpcResult> => {
+    const result = await kernel.launchSubcluster(params.config);
+    // Convert undefined to null for JSON compatibility
+    return {
+      subclusterId: result.subclusterId,
+      bootstrapRootKref: result.bootstrapRootKref,
+      bootstrapResult: result.bootstrapResult ?? null,
+    };
   },
 };