@forgeax/engine-remote 0.1.4 → 0.1.6

package/src/__tests__/errors.unit.test.ts

@@ -1,5 +1,5 @@
 // w11: RemoteErrorCode completeness unit test (5-member closed union).
-// Verifies that the error-code family has exactly 5 members after
+// Verifies that the error-code family has exactly 4 members after
 // deleting inspector-write-denied + script-timeout in w7.
 
 import { describe, expect, it } from 'vitest';
@@ -39,7 +39,7 @@ describe('RemoteErrorCode closed union — 5-member completeness', () => {
 });
 
 describe('RemoteError construction + toJSON', () => {
-  it('constructs with the core structured fields', () => {
+  it('constructs with all 4 fields', () => {
     const err = new RemoteError({
       code: 'script-syntax-error',
       expected: 'valid JS',
@@ -51,7 +51,7 @@ describe('RemoteError construction + toJSON', () => {
     expect(err.message).toContain('[RemoteError script-syntax-error]');
   });
 
-  it('toJSON() returns the core plain object when detail is absent', () => {
+  it('toJSON() returns 4-field plain object', () => {
     const err = new RemoteError({
       code: 'server-not-running',
       expected: 'server reachable',
@@ -85,18 +85,4 @@ describe('RemoteError construction + toJSON', () => {
     expect(err.code).toBe('script-runtime-error');
     expect(err.expected).toBe('script executes');
   });
-
-  it('toJSON retains only the bounded result-shape detail', () => {
-    const err = new RemoteError({
-      code: 'eval-result-not-serializable',
-      expected: 'eval result is JSON-serializable',
-      hint: 'return a JSON-safe value',
-      detail: { code: 'eval-result-not-serializable', shape: 'cyclic-object' },
-    });
-    expect(err.toJSON()).toMatchObject({
-      code: 'eval-result-not-serializable',
-      detail: { code: 'eval-result-not-serializable', shape: 'cyclic-object' },
-    });
-    expect(JSON.stringify(err)).not.toContain('privateMarker');
-  });
 });

package/src/__tests__/execute.async.test.ts

@@ -18,7 +18,21 @@ import { executeScript } from '../execute';
 
 function makeMockWorld() {
   const state: unknown[] = [];
+  // Archetype shape retained for scripts that inspect the mock World internals:
+  // - columns: Map<compId, Map<fieldName, { length: number }>>
+  //   The Entity component (id=0) has field 'self' with Uint32Array length.
+  function mkArchetype(id: number) {
+    const selfField = new Map([['self', { length: 3 }]]);
+    const columns = new Map([[0, selfField]]);
+    return { id, componentIds: [0], columns };
+  }
   return {
+    _getGraph() {
+      return {
+        generation: 1,
+        archetypes: [mkArchetype(0), mkArchetype(1)],
+      };
+    },
     inspect(): { entityCount: number } {
       return { entityCount: state.length + 5 };
     },
@@ -41,17 +55,7 @@ const mockRenderer = {
     /* no-op */
   },
 };
-const mockAssets = {
-  load(guid: string, expectedKind: string) {
-    return Promise.resolve({ ok: true, value: { guid, kind: expectedKind } });
-  },
-  snapshot() {
-    return { scopeId: 'test-scope', generation: 1, entries: [] };
-  },
-  subscribe() {
-    return () => {};
-  },
-};
+const mockAssets = { HANDLE_CUBE: 1, HANDLE_TRIANGLE: 2 };
 
 function makeCtx() {
   return {
@@ -89,9 +93,9 @@ describe('executeScript async - read (w1)', () => {
     }
   });
 
-  it('reads the AssetRegistry snapshot', async () => {
+  it('reads asset handle constants', async () => {
     const ctx = makeCtx();
-    const result = await executeScript('assets.snapshot().generation', ctx);
+    const result = await executeScript('assets.HANDLE_CUBE', ctx);
     expect(result.ok).toBe(true);
     if (result.ok) {
       expect(result.value).toBe(1);

package/src/__tests__/server.unit.test.ts

@@ -8,7 +8,6 @@
 // source as ancestorTitles[0]. Top-level imports merged + deduped.
 
 import { createProfiler } from '@forgeax/engine-profiler';
-import { defaultConnect } from '@forgeax/engine-types/inspector-client';
 import { describe, expect, it } from 'vitest';
 import { WebSocket } from 'ws';
 import { RemoteError } from '../errors';
@@ -37,7 +36,6 @@ import { type ComponentIntrospectionDescriptor, type ConsoleHandle, startServer
         expected: string;
         hint: string;
         message?: string;
-        detail?: { code: string; shape: string };
       };
     };
     id: number | string | null;
@@ -68,22 +66,6 @@ import { type ComponentIntrospectionDescriptor, type ConsoleHandle, startServer
     });
   }
 
-  async function sendRaw(ws: WebSocket, raw: string): Promise<JsonRpcResponse> {
-    return new Promise<JsonRpcResponse>((resolve, reject) => {
-      const handler = (message: WebSocket.RawData): void => {
-        ws.off('message', handler);
-        try {
-          const parsed = JSON.parse(message.toString()) as JsonRpcResponse;
-          resolve(parsed);
-        } catch (e) {
-          reject(e);
-        }
-      };
-      ws.on('message', handler);
-      ws.send(raw);
-    });
-  }
-
   async function withServer(
     fn: (handle: ConsoleHandle) => Promise<void>,
     opts: {
@@ -92,7 +74,6 @@ import { type ComponentIntrospectionDescriptor, type ConsoleHandle, startServer
       renderer?: unknown;
       assets?: unknown;
       profiler?: unknown;
-      importModule?: (specifier: string) => Promise<unknown>;
     } = {},
   ): Promise<void> {
     const startResult = await startServer({
@@ -102,7 +83,6 @@ import { type ComponentIntrospectionDescriptor, type ConsoleHandle, startServer
       renderer: opts.renderer,
       assets: opts.assets,
       profiler: opts.profiler,
-      ...(opts.importModule === undefined ? {} : { importModule: opts.importModule }),
     });
     if (!startResult.ok) {
       throw startResult.error;
@@ -123,39 +103,9 @@ import { type ComponentIntrospectionDescriptor, type ConsoleHandle, startServer
         expect(typeof handle.close).toBe('function');
       });
     });
-
-    it('close is idempotent', async () => {
-      await withServer(async (handle) => {
-        await handle.close();
-        await handle.close();
-      });
-    });
   });
 
   describe('JSON-RPC envelope shape', () => {
-    it('uses the host import resolver without coupling remote to engine packages', async () => {
-      await withServer(
-        async (handle) => {
-          const ws = await connect(handle.port);
-          const resp = await send(ws, {
-            jsonrpc: '2.0',
-            method: 'eval',
-            params: {
-              script: "const module = await _import('virtual:host-module'); return module.value",
-            },
-            id: 11,
-          });
-          expect(resp.result).toBe('host-resolved');
-          expect(resp.error).toBeUndefined();
-          ws.close();
-        },
-        {
-          importModule: async (specifier) =>
-            specifier === 'virtual:host-module' ? { value: 'host-resolved' } : {},
-        },
-      );
-    });
-
     it('response carries jsonrpc + id and either result or error (mutually exclusive)', async () => {
       await withServer(async (handle) => {
         const ws = await connect(handle.port);
@@ -208,58 +158,6 @@ import { type ComponentIntrospectionDescriptor, type ConsoleHandle, startServer
         ws.close();
       });
     });
-
-    it('null envelope returns -32600 without root execution and preserves the connection', async () => {
-      let worldReads = 0;
-      const world = new Proxy(
-        {},
-        {
-          get(_target, property) {
-            worldReads += 1;
-            throw new Error(`unexpected world read: ${String(property)}`);
-          },
-        },
-      );
-
-      await withServer(
-        async (handle) => {
-          const ws = await connect(handle.port);
-          let closeCount = 0;
-          ws.on('close', () => {
-            closeCount += 1;
-          });
-
-          const invalid = await sendRaw(ws, 'null');
-          expect(invalid).toEqual({
-            jsonrpc: '2.0',
-            id: null,
-            error: { code: -32600, message: 'Invalid Request' },
-          });
-          expect(worldReads).toBe(0);
-
-          const introspect = await send(ws, { jsonrpc: '2.0', method: 'introspect', id: 1 });
-          expect(introspect.jsonrpc).toBe('2.0');
-          expect(introspect.id).toBe(1);
-          expect(introspect.result).toBeDefined();
-
-          const evaluated = await send(ws, {
-            jsonrpc: '2.0',
-            method: 'eval',
-            params: { script: 'return 7' },
-            id: 2,
-          });
-          expect(evaluated).toEqual({ jsonrpc: '2.0', id: 2, result: 7 });
-
-          const repeated = await sendRaw(ws, 'null');
-          expect(repeated).toEqual(invalid);
-          expect(worldReads).toBe(0);
-          expect(ws.readyState).toBe(ws.OPEN);
-          expect(closeCount).toBe(0);
-          ws.close();
-        },
-        { world },
-      );
-    });
   });
 
   describe('introspect() OpenRPC L2 subset', () => {
@@ -497,14 +395,18 @@ import { type ComponentIntrospectionDescriptor, type ConsoleHandle, startServer
     });
 
     it('renderer read returns real field value', async () => {
-      const stubRenderer = { backend: 'webgpu', isReady: true };
+      const stubRenderer = {
+        backend: 'webgpu',
+        isReady: true,
+        inspect: () => ({ capabilities: { backendKind: 'webgpu' } }),
+      };
       await withServer(
         async (handle) => {
           const ws = await connect(handle.port);
           const resp = await send(ws, {
             jsonrpc: '2.0',
             method: 'eval',
-            params: { script: 'renderer.backend' },
+            params: { script: 'renderer.inspect().capabilities.backendKind' },
             id: 21,
           });
           expect(resp.result).toBe('webgpu');
@@ -545,157 +447,6 @@ import { type ComponentIntrospectionDescriptor, type ConsoleHandle, startServer
       });
     });
 
-    it('successful non-JSON results return a structured error and preserve the socket', async () => {
-      const world = {
-        count: 0,
-        bump() {
-          this.count += 1;
-        },
-        inspect() {
-          return { count: this.count, stable: true };
-        },
-      };
-      const renderer = {
-        inspect() {
-          return { renderer: 'stable' };
-        },
-      };
-      await withServer(
-        async (handle) => {
-          const ws = await connect(handle.port);
-          const cyclic = await send(ws, {
-            jsonrpc: '2.0',
-            method: 'eval',
-            params: {
-              script:
-                "world.bump(); const value = { privateMarker: 'must-not-cross-wire' }; value.self = value; return value;",
-            },
-            id: 'cyclic-result',
-          });
-          expect(cyclic).toMatchObject({
-            jsonrpc: '2.0',
-            id: 'cyclic-result',
-            error: {
-              code: -32005,
-              message: 'Eval result not serializable',
-              data: {
-                code: 'eval-result-not-serializable',
-                expected: 'eval result is JSON-serializable',
-                hint: 'return a JSON-safe value; BigInt and cyclic objects are unsupported over JSON-RPC',
-                detail: {
-                  code: 'eval-result-not-serializable',
-                  shape: 'cyclic-object',
-                },
-              },
-            },
-          });
-          expect(JSON.stringify(cyclic)).not.toContain('privateMarker');
-
-          const afterCyclic = await send(ws, {
-            jsonrpc: '2.0',
-            method: 'eval',
-            params: { script: 'world.inspect()' },
-            id: 'after-cyclic',
-          });
-          expect(afterCyclic).toEqual({
-            jsonrpc: '2.0',
-            id: 'after-cyclic',
-            result: { count: 1, stable: true },
-          });
-
-          let notificationReceived = false;
-          const notificationHandler = () => {
-            notificationReceived = true;
-          };
-          ws.on('message', notificationHandler);
-          ws.send(
-            JSON.stringify({
-              jsonrpc: '2.0',
-              method: 'eval',
-              params: { script: 'world.bump(); return 7' },
-            }),
-          );
-          await new Promise((resolve) => setTimeout(resolve, 50));
-          ws.off('message', notificationHandler);
-          expect(notificationReceived).toBe(false);
-
-          const afterNotification = await send(ws, {
-            jsonrpc: '2.0',
-            method: 'eval',
-            params: { script: 'renderer.inspect()' },
-            id: 'after-notification',
-          });
-          expect(afterNotification.result).toEqual({ renderer: 'stable' });
-
-          const bigint = await send(ws, {
-            jsonrpc: '2.0',
-            method: 'eval',
-            params: { script: 'world.bump(); return 1n' },
-            id: 'bigint-result',
-          });
-          expect(bigint).toMatchObject({
-            jsonrpc: '2.0',
-            id: 'bigint-result',
-            error: {
-              code: -32005,
-              message: 'Eval result not serializable',
-              data: {
-                code: 'eval-result-not-serializable',
-                detail: { code: 'eval-result-not-serializable', shape: 'bigint' },
-              },
-            },
-          });
-
-          const afterBigInt = await send(ws, {
-            jsonrpc: '2.0',
-            method: 'eval',
-            params: { script: 'world.inspect()' },
-            id: 'after-bigint',
-          });
-          expect(afterBigInt).toEqual({
-            jsonrpc: '2.0',
-            id: 'after-bigint',
-            result: { count: 3, stable: true },
-          });
-          ws.close();
-        },
-        { world, renderer },
-      );
-    });
-
-    it('shared inspector client preserves structured serialization errors and recovers', async () => {
-      const world = {
-        count: 0,
-        bump() {
-          this.count += 1;
-        },
-        inspect() {
-          return { count: this.count, stable: true };
-        },
-      };
-      await withServer(
-        async (handle) => {
-          const connected = await defaultConnect(`ws://127.0.0.1:${handle.port}/inspector`);
-          expect(connected.ok).toBe(true);
-          if (!connected.ok) return;
-          const client = connected.value;
-          await expect(
-            client.eval(
-              "world.bump(); const value = { secret: 'hidden' }; value.self = value; return value",
-            ),
-          ).rejects.toMatchObject({
-            code: 'eval-result-not-serializable',
-            expected: 'eval result is JSON-serializable',
-            detail: { code: 'eval-result-not-serializable', shape: 'cyclic-object' },
-          });
-          await expect(client.eval('world.inspect()')).resolves.toEqual({ count: 1, stable: true });
-          await client.dispose();
-          await client.dispose();
-        },
-        { world },
-      );
-    });
-
     it('JSON-RPC error envelopes preserve exact human messages', async () => {
       await withServer(async (handle) => {
         const ws = await connect(handle.port);
@@ -771,10 +522,10 @@ import { type ComponentIntrospectionDescriptor, type ConsoleHandle, startServer
       );
     });
 
-    it('assets.load() succeeds (full-access, no sandbox)', async () => {
+    it('assets.register() succeeds (full-access, no sandbox)', async () => {
       const stubAssets = {
-        load(guid: string, kind: string): Promise<unknown> {
-          return Promise.resolve({ ok: true, value: { guid, kind } });
+        register(_a: unknown): number {
+          return 42;
         },
       };
       await withServer(
@@ -783,10 +534,10 @@ import { type ComponentIntrospectionDescriptor, type ConsoleHandle, startServer
           const resp = await send(ws, {
             jsonrpc: '2.0',
             method: 'eval',
-            params: { script: 'await assets.load("asset-guid", "mesh")' },
+            params: { script: 'assets.register({ kind: "mesh" })' },
             id: 51,
           });
-          expect(resp.result).toEqual({ ok: true, value: { guid: 'asset-guid', kind: 'mesh' } });
+          expect(resp.result).toBe(42);
           ws.close();
         },
         { world: {}, assets: stubAssets },
@@ -800,13 +551,19 @@ import { type ComponentIntrospectionDescriptor, type ConsoleHandle, startServer
           const resp = await send(ws, {
             jsonrpc: '2.0',
             method: 'eval',
-            params: { script: 'renderer.backend' },
+            params: { script: 'renderer.inspect().capabilities.backendKind' },
             id: 52,
           });
           expect(resp.result).toBe('webgpu');
           ws.close();
         },
-        { world: {}, renderer: { backend: 'webgpu' } },
+        {
+          world: {},
+          renderer: {
+            backend: 'webgpu',
+            inspect: () => ({ capabilities: { backendKind: 'webgpu' } }),
+          },
+        },
       );
     });
   });

package/src/__tests__/simulation-inspect.integration.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest';
+
+import { buildIntrospectDoc } from '../introspect';
+import { startServer } from '../server';
+
+describe('remote simulation inspection projection', () => {
+  it('projects the existing simulation read root without adding remote actions', () => {
+    const doc = buildIntrospectDoc('127.0.0.1', 5732, {
+      world: {},
+      renderer: {},
+      assets: {},
+      simulation: {
+        inspect: () => ({
+          formatVersion: 1,
+          recordOwner: '@forgeax/engine-ecs',
+          schemaOwner: '@forgeax/engine-ecs',
+          participants: [],
+          trace: { recordTick: 0, sampleCount: 0 },
+          report: { verdict: 'match', entries: [] },
+        }),
+      },
+    }) as {
+      roots: Record<string, { type: string; description: string }>;
+      methods: readonly { name: string }[];
+    };
+
+    expect(doc.roots.simulation).toMatchObject({
+      available: true,
+      type: 'SimulationInspection',
+    });
+    expect(doc.methods.map((method) => method.name)).toEqual(['eval', 'introspect']);
+  });
+
+  it('keeps simulation inspection on the existing eval transport', async () => {
+    const started = await startServer({
+      port: 0,
+      host: '127.0.0.1',
+      world: {},
+      simulation: {
+        inspect: () => ({
+          formatVersion: 1,
+          recordOwner: '@forgeax/engine-ecs',
+          schemaOwner: '@forgeax/engine-ecs',
+          participants: [],
+          trace: { recordTick: 0, sampleCount: 0 },
+          report: { verdict: 'match', entries: [] },
+        }),
+      },
+    });
+    expect(started.ok).toBe(true);
+    if (!started.ok) return;
+    try {
+      const { defaultConnect } = await import('@forgeax/engine-types/inspector-client');
+      const connected = await defaultConnect(`ws://127.0.0.1:${started.value.port}/inspector`);
+      expect(connected.ok).toBe(true);
+      if (!connected.ok) return;
+      const value = await connected.value.eval('simulation.inspect()');
+      expect(value).toMatchObject({
+        formatVersion: 1,
+        recordOwner: '@forgeax/engine-ecs',
+      });
+      await connected.value.dispose();
+    } finally {
+      await started.value.close();
+    }
+  });
+});

package/src/__tests__/vm-async-eval-verify.mjs

@@ -137,7 +137,7 @@ if (routeAfail && routeBpass) {
   console.log('  - w5: implement executeScript via new Function');
   console.log('  - w5: remove scriptTimeoutMs & timeout logic (dead)');
   console.log('  - w7: delete script-timeout from RemoteErrorCode');
-  console.log('  - Final error set: 5 members (no script-timeout)');
+  console.log('  - Final error set: 4 members (no script-timeout)');
   exitCode = 0;
 } else {
   console.log('UNEXPECTED RESULT:');