@forgeax/engine-remote 0.1.2

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

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+// biome-ignore-all lint/suspicious/noConsole: standalone D-1 verification CLI script; console is its diagnostic output channel
+// @forgeax/engine-remote/src/__tests__/vm-async-eval-verify.mjs
+// D-1 verification: route A (vm + importModuleDynamically) vs route B (host realm eval).
+//
+// Indicators:
+//   (a)  vm.runInContext with importModuleDynamically: does await import resolve?
+//   (a') host realm eval via new Function: does await import resolve?
+//   (c)  vm timeout watchdog: does it fire on sync infinite loop?
+//
+// Route B has NO timeout watchdog — infinite loops hang the thread.
+//
+// RESULT (2026-06-29, Node 24.15.0):
+//   ROUTE A FALSIFIED — vm.runInContext does NOT support importModuleDynamically.
+//   ROUTE B CONFIRMED — new Function resolves await import naturally.
+//   Timeout: vm watchdog PASS, but host eval has NO timeout.
+
+import * as vm from 'node:vm';
+
+let exitCode = 0;
+const passes = [];
+const fails = [];
+
+function record(label, ok, detail) {
+  if (ok) {
+    passes.push(label);
+    console.log(`(a)  vm importModuleDynamically: ${detail}`);
+  } else {
+    fails.push(label);
+    console.log(`(a)  vm importModuleDynamically: FAIL — ${detail}`);
+  }
+}
+
+// ── Indicator (a): vm route ─────────────────────────────────────────────────
+
+{
+  const label = 'a';
+  const ok = false;
+  let detail = '';
+  const scriptBody = [
+    '(async () => {',
+    "  const ecs = await import('@forgeax/engine-ecs');",
+    "  return typeof ecs.World.prototype.query === 'function';",
+    '})()',
+  ].join('\n');
+  try {
+    const ctx = vm.createContext(
+      {},
+      { importModuleDynamically: vm.constants.USE_MAIN_CONTEXT_DEFAULT_LOADER },
+    );
+    const promise = vm.runInContext(scriptBody, ctx, { timeout: 10000, displayErrors: true });
+    if (typeof promise?.then === 'function') {
+      // We need to await it — but vm.runInContext is sync, so we get
+      // the Promise object back. However Node's vm Script does NOT
+      // execute the async IIFE — it evaluates the expression and returns
+      // the raw Promise without executing it. The Promise never settles.
+      // This is a known limitation.
+      detail =
+        'Promise returned but never settled — import() never called (vm Script cannot execute async IIFE)';
+      record(label, ok, detail);
+    } else {
+      detail = `returned ${typeof promise} (expected thenable)`;
+      record(label, ok, detail);
+    }
+  } catch (e) {
+    detail = e instanceof Error ? e.message : String(e);
+    record(label, ok, detail);
+  }
+}
+
+// ── Indicator (a'): host realm eval route ───────────────────────────────────
+
+{
+  const label = "a'";
+  let ok = false;
+  let detail = '';
+  try {
+    // Dynamically import in host realm, then new Function.
+    // The fact that new Function runs in host realm means import() works naturally.
+    const script = [
+      'return (async () => {',
+      "  const ecs = await import('@forgeax/engine-ecs');",
+      "  return typeof ecs.World.prototype.query === 'function';",
+      '})();',
+    ].join('\n');
+    const fn = new Function(script);
+    const result = await fn();
+    ok = result === true;
+    detail = `import resolved, World.query is function = ${result}`;
+    record(label, ok, detail);
+  } catch (e) {
+    detail = e instanceof Error ? e.message : String(e);
+    record(label, ok, detail);
+  }
+}
+
+// ── Indicator (c): vm timeout watchdog ──────────────────────────────────────
+
+{
+  const label = 'c';
+  let ok = false;
+  let detail = '';
+  const start = Date.now();
+  try {
+    const ctx = vm.createContext({});
+    vm.runInContext('while(true){}', ctx, { timeout: 200, displayErrors: false });
+    detail = `loop completed without interruption after ${Date.now() - start}ms`;
+    record(label, ok, detail);
+  } catch (e) {
+    const elapsed = Date.now() - start;
+    const msg = e instanceof Error ? e.message : String(e);
+    ok = msg.includes('timed out') || msg.includes('Script execution timed out');
+    detail = `timed out after ~${elapsed}ms`;
+    record(label, ok, detail);
+  }
+}
+
+// ── Final verdict ───────────────────────────────────────────────────────────
+
+const routeBpass = passes.includes("a'");
+const routeAfail = fails.includes('a');
+
+console.log();
+console.log('='.repeat(60));
+console.log('D-1 VERDICT:');
+
+if (routeAfail && routeBpass) {
+  console.log('ROUTE A (vm + importModuleDynamically): FALSIFIED');
+  console.log('  Reason: vm.runInContext does not honor importModuleDynamically');
+  console.log('  for Script execution. Only vm.SourceTextModule is supported.');
+  console.log();
+  console.log('ROUTE B (host realm eval via new Function): CONFIRMED');
+  console.log('  - await import resolves naturally in host realm');
+  console.log('  - NO timeout watchdog (known limitation, documented in R6)');
+  console.log();
+  console.log('IMPLEMENTATION IMPLICATIONS:');
+  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)');
+  exitCode = 0;
+} else {
+  console.log('UNEXPECTED RESULT:');
+  console.log('  Route A passes:', passes, 'fails:', fails);
+  console.log('  Route B passes:', passes, 'fails:', fails);
+  exitCode = 1;
+}
+
+process.exit(exitCode);

package/src/error-messages.ts

@@ -0,0 +1,9 @@
+import type { RemoteErrorCode } from './errors';
+
+export const REMOTE_ERROR_MESSAGES: Readonly<Record<RemoteErrorCode, string>> = {
+  'script-syntax-error': 'Script syntax error',
+  'script-runtime-error': 'Script runtime error',
+  'server-startup-failed': 'Server startup failed',
+  'server-not-running': 'Server not reachable',
+  'eval-result-not-serializable': 'Eval result not serializable',
+};

package/src/errors.ts

@@ -0,0 +1,143 @@
+// @forgeax/engine-remote/src/errors - RemoteError runtime class + re-export of
+// the closed `RemoteErrorCode` union; 5 members (feat-20260629-inspector-two-layer-model D-5).
+//
+// SSOT split: the **type alias** `RemoteErrorCode`
+// + **structural interface** `RemoteError` live in `@forgeax/engine-types`
+// (parallel to the existing `ShaderErrorCode` placement). This file owns
+// the **runtime class** (`extends Error` + `toJSON()`) only; the class
+// `implements` the type-side interface so the two sides cannot drift
+// (architecture-principles #1 SSOT).
+//
+// Shape (mirrors @forgeax/engine-rhi/src/errors.ts RhiError 4-field surface for
+// charter proposition 5 consistent abstraction):
+// - `RemoteErrorCode` = closed union 5 members (re-exported from types).
+//   tsc strict-mode guards exhaustive switch completeness (charter
+//   proposition 4); AI users consume via `switch (err.code) { case '...': ... }`
+//   with NO default branch.
+// - `RemoteError` class extends Error with three readonly fields .code /
+//   .expected / .hint (AGENTS.md "Errors are structured"). The constructor
+//   auto-composes a human-readable .message (`[RemoteError <code>]
+//   expected: <expected>; hint: <hint>`). The class implements the
+//   `RemoteError` interface from `@forgeax/engine-types` so callers may
+//   alternately type against the structural shape.
+// - `toJSON()` opts into JSON.stringify serialisation so the JSON-RPC 2.0
+//   `error.data` payload carries .code / .expected / .hint / .message
+//   verbatim through the WebSocket transport.
+
+import type {
+  RemoteErrorCode,
+  RemoteErrorDetail,
+  RemoteError as RemoteErrorShape,
+} from '@forgeax/engine-types';
+
+// Re-export the type-side alias verbatim so existing
+// `import { type RemoteErrorCode } from '@forgeax/engine-remote'` call sites
+// keep working (charter proposition 1 progressive disclosure — single
+// entry point for AI users).
+export type { RemoteErrorCode };
+
+/**
+ * Structured remote error. Four core fields plus bounded detail, mirroring `@forgeax/engine-rhi`
+ * `RhiError` (charter proposition 5 consistent abstraction; AGENTS.md
+ * "Errors are structured"). The class `implements RemoteErrorShape`
+ * (the structural interface re-exported from `@forgeax/engine-types`) so the type
+ * SSOT and the runtime class cannot drift.
+ *
+ * - `.code`      closed union member (L1 key signal; switch-able).
+ * - `.expected`  expected-state description (L2 detail; ai-user-charter
+ *                proposition 4 requires expected-state copy).
+ * - `.hint`      actionable recovery guidance (L2 detail; charter
+ *                proposition 3 machine-readable hint > prose).
+ * - `.message`   auto-composed `[RemoteError <code>] expected: <expected>;
+ *                hint: <hint>` so human stack traces still surface the
+ *                triple. AI users prefer property access (charter
+ *                proposition 4: no string parsing).
+ *
+ * Per-code `.expected` + `.hint` templates (requirements §10.2 SSOT):
+ *
+ * | code | `.expected` | `.hint` |
+ * |:--|:--|:--|
+ * | `'script-syntax-error'` | `'script body is valid JavaScript'` | `'check syntax position in errMessage; fix and resubmit'` |
+ * | `'script-runtime-error'` | `'script executes without throwing'` | `'inspect error; verify symbol availability; eval has full access to world/renderer/assets'` |
+ * | `'server-startup-failed'` | `'server starts successfully on requested port'` | `'check if port is already in use (default 5732); pass different port; or kill existing process holding the port'` |
+ * | `'server-not-running'` | `'server is reachable at ws://localhost:<port>'` | `'start the demo first; verify app.remote is wired; pass --port to override default 5732'` |
+ * | `'eval-result-not-serializable'` | `'eval result is JSON-serializable'` | `'return a JSON-safe value; BigInt and cyclic objects are unsupported over JSON-RPC'` |
+ *
+ * JSON-RPC 2.0 transport contract: `toJSON()` returns the structured plain
+ * object carried verbatim via `error.data` on the WebSocket envelope. The
+ * JSON-RPC server-error `.code` numeric segment -32001 ~ -32005 maps 1:1
+ * to the 5 members
+ * at the dispatch layer.
+ *
+ * @example AI-user exhaustive switch on the 5 remote-domain alternatives (no default fallback)
+ * ```ts
+ * import { RemoteError, type RemoteErrorCode } from '@forgeax/engine-remote';
+ *
+ * function recover(code: RemoteErrorCode): string {
+ *   switch (code) {
+ *     case 'script-syntax-error':     return 'fix script body syntax and resubmit';
+ *     case 'script-runtime-error':    return 'inspect stack trace; verify symbol availability';
+ *     case 'server-startup-failed':   return 'pick a different port or free port 5732';
+ *     case 'server-not-running':      return 'start demo dev or wire app.remote';
+ *     case 'eval-result-not-serializable': return 'return a JSON-safe eval result';
+ *   }
+ * }
+ * ```
+ */
+export class RemoteError extends Error implements RemoteErrorShape {
+  readonly code: RemoteErrorCode;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail?: RemoteErrorDetail;
+
+  constructor(args: {
+    code: RemoteErrorCode;
+    expected: string;
+    hint: string;
+    detail?: RemoteErrorDetail;
+  }) {
+    super(`[RemoteError ${args.code}] expected: ${args.expected}; hint: ${args.hint}`);
+    this.name = 'RemoteError';
+    this.code = args.code;
+    this.expected = args.expected;
+    this.hint = args.hint;
+    if (args.detail !== undefined) {
+      this.detail = args.detail;
+    }
+  }
+
+  toJSON(): {
+    readonly code: RemoteErrorCode;
+    readonly expected: string;
+    readonly hint: string;
+    readonly message: string;
+    readonly detail?: RemoteErrorDetail;
+  } {
+    const json = {
+      code: this.code,
+      expected: this.expected,
+      hint: this.hint,
+      message: this.message,
+    };
+    return this.detail === undefined ? json : { ...json, detail: this.detail };
+  }
+}
+
+/**
+ * SSOT mapping `RemoteErrorCode` -> JSON-RPC `error.code` numeric segment
+ * (feat-20260629-inspector-two-layer-model D-5). The 5 remote P0
+ * members occupy the closed segment `-32001..-32005`.
+ *
+ * `server.ts` consumes this map at the JSON-RPC envelope edge so the wire
+ * always carries the lock-in numeric and a future drift in either direction
+ * raises a TypeScript completeness error (the `Record<RemoteErrorCode,
+ * number>` type guard requires every closed-union member to have a
+ * numeric).
+ */
+export const REMOTE_ERROR_CODE_TO_JSONRPC: Readonly<Record<RemoteErrorCode, number>> = {
+  'script-syntax-error': -32001,
+  'script-runtime-error': -32002,
+  'server-startup-failed': -32003,
+  'server-not-running': -32004,
+  'eval-result-not-serializable': -32005,
+};

package/src/execute.ts

@@ -0,0 +1,152 @@
+// @forgeax/engine-remote/src/execute — async host-realm eval.
+//
+// D-1 route B (2026-06-29): vm.runInContext does not honor
+// importModuleDynamically for Script execution. Host realm compilation via
+// the AsyncFunction constructor resolves `await import` naturally, as long
+// as the import function from the calling module scope is injected.
+//
+// CONTRACT (the one an AI user holds): the script IS the body of an async
+// function with `world` / `renderer` / `assets` / `rhiCapture` / `simulation` / `_import`
+// in scope. So all of these Just Work, un-wrapped:
+//   - a bare expression:            `renderer.backend`            -> auto-returned
+//   - top-level await:              `await _import('@forgeax/engine-ecs')`
+//   - top-level return:             `return world.inspect().entityCount`
+//   - multi-statement + return:     `const m = await _import(...); return m.x`
+// (the historical `(async () => { ... })()` IIFE form still works too — its
+// returned Promise is awaited.)
+//
+// Implementation (mirrors a REPL, two construction-time-checked attempts):
+//   1. expression mode: compile `return (<script>)` — auto-returns a lone
+//      expression (incl. an await-expression), preserving last-expression value.
+//   2. on SyntaxError from (1)'s CONSTRUCTION: statement mode — compile
+//      `<script>` as the async body directly, legalizing top-level return +
+//      await + arbitrary statements.
+// Only a construction-time SyntaxError advances attempt 1 -> 2, so user code is
+// compiled once and executed at most once (no double side effects). We never use
+// `eval`: indirect eval ran the body as a global program, which is precisely
+// what banned top-level return/await and produced the doc-vs-reality gap.
+//
+// try/catch maps errors:
+//   SyntaxError (both attempts fail to compile) -> 'script-syntax-error'
+//   RemoteError (re-thrown)                      -> verbatim
+//   anything else                                -> 'script-runtime-error'
+//
+// The sandbox is dismantled — eval is full-access, no wrapReadOnly.
+// Timeout is removed (route B has no interrupt mechanism; see R6).
+
+import { RemoteError } from './errors';
+
+// AsyncFunction constructor (not a global binding). An async body is what
+// legalizes top-level `await` AND top-level `return` simultaneously.
+const AsyncFunction = Object.getPrototypeOf(async () => {}).constructor as FunctionConstructor;
+
+export type ExecuteContext = {
+  readonly world: unknown;
+  readonly renderer: unknown;
+  readonly assets: unknown;
+  readonly rhiCapture?: unknown;
+  readonly profiler?: unknown;
+  readonly execution?: unknown;
+  readonly importModule?: (specifier: string) => Promise<unknown>;
+};
+
+export type ExecuteResult = { ok: true; value: unknown } | { ok: false; error: RemoteError };
+
+// Capture import at module load time. This is the host realm's dynamic
+// import() — when injected into new Function, it resolves module
+// specifiers relative to the module that called executeScript. The remote
+// package stays package-neutral: a host may inject a capability projection
+// through ExecuteContext.importModule, but the transport does not own any
+// engine package vocabulary.
+const _import = async (specifier: string): Promise<unknown> => import(specifier);
+
+// Compile the script as an async function body. Tries expression mode first
+// (auto-return a lone expression), falling back to statement mode on a
+// construction-time SyntaxError. Returns the compiled fn, or throws the
+// statement-mode SyntaxError if BOTH modes fail to parse.
+function compile(script: string): FunctionConstructor['prototype'] {
+  const params = [
+    'world',
+    'renderer',
+    'assets',
+    'rhiCapture',
+    'profiler',
+    'execution',
+    '_import',
+  ] as const;
+  try {
+    // Expression mode: `return (<expr>)` auto-returns a lone expression
+    // (including an await-expression), preserving last-expression-value.
+    // Trailing semicolons/whitespace are trimmed so `renderer.backend;`
+    // still returns its value (the old indirect-eval completion-value
+    // behavior) instead of parsing as a statement that returns undefined.
+    const expr = script.replace(/[\s;]+$/, '');
+    return new AsyncFunction(...params, `return (${expr}\n)`);
+  } catch (e) {
+    if (!(e instanceof SyntaxError)) throw e;
+    // Statement mode: the script IS the async body — legalizes top-level
+    // return + await + arbitrary statements. If this also fails to parse,
+    // its SyntaxError is the authoritative one to surface.
+    return new AsyncFunction(...params, script);
+  }
+}
+
+/**
+ * Evaluate a JavaScript script against the host engine context.
+ *
+ * Route B (D-1): host-realm compilation via the AsyncFunction constructor with
+ * injected _import. The script is the body of an async function; a lone
+ * expression is auto-returned, and top-level `await` / `return` are legal.
+ *   - _import is available as a parameter for dynamic ESM imports.
+ *   - rhiCapture is available as a 4th eval-scope root for the RHI capture
+ *     capability (plan-strategy D-4).
+ *   - No sandbox — full access reads and writes.
+ *   - No timeout — host realm eval cannot be interrupted (see R6).
+ */
+export async function executeScript(script: string, ctx: ExecuteContext): Promise<ExecuteResult> {
+  try {
+    const fn = compile(script);
+    // AsyncFunction always returns a Promise; await resolves the value and
+    // surfaces any runtime throw into this catch.
+    const value: unknown = await fn(
+      ctx.world,
+      ctx.renderer,
+      ctx.assets,
+      ctx.rhiCapture,
+      ctx.profiler,
+      ctx.execution,
+      ctx.importModule ?? _import,
+    );
+
+    return { ok: true, value };
+  } catch (e) {
+    // 1. RemoteError re-thrown from within the script surfaces verbatim.
+    if (e instanceof RemoteError) {
+      return { ok: false, error: e };
+    }
+
+    // 2. SyntaxError: both compile() attempts failed to parse the script.
+    if (e instanceof SyntaxError) {
+      const msg = e.message;
+      return {
+        ok: false,
+        error: new RemoteError({
+          code: 'script-syntax-error',
+          expected: 'script body is valid JavaScript',
+          hint: `check syntax near: ${msg}; fix and resubmit`,
+        }),
+      };
+    }
+
+    // 3. Runtime error (throws during function execution).
+    const rawMessage = e instanceof Error ? e.message : String(e);
+    return {
+      ok: false,
+      error: new RemoteError({
+        code: 'script-runtime-error',
+        expected: 'script executes without throwing',
+        hint: `inspect error; verify symbol availability; eval has full access to world/renderer/assets (errMessage: ${rawMessage})`,
+      }),
+    };
+  }
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+// @forgeax/engine-remote - inspector P0 server + eval core.
+//
+// Single entry facade (charter proposition 1 progressive disclosure). The
+// runtime server lives under the ./server sub-path. AI users import the shared
+// error model from this top entry:
+//
+//   import { RemoteError, type RemoteErrorCode } from '@forgeax/engine-remote';
+//
+// The error model SSOT (5-member closed RemoteErrorCode union) lives in
+// src/errors.ts and is also exposed via the ./errors sub-path for callers that
+// want type-only imports without pulling the runtime surface (D-P4 bundle
+// isolation + AGENTS.md "Inspector / Console" evolution contract minor
+// add-only).
+//
+// M2 w8: routing layer (Registry / sandbox / wireDefaultInspectors /
+// register-plugin-inspector / discoverPlugins) deleted; eval is the sole
+// command channel.
+
+export { RemoteError, type RemoteErrorCode } from './errors';