first commit

docs/devtools/tooling/sandbox/src/isolate-engine/isolate-engine.md

@@ -0,0 +1,78 @@
+# IsolateEngine
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`IsolateEngine` implements the `SandboxEngine` contract over a structural `IsolateFactory` interface that mirrors the `isolated-vm` package's API. This keeps `isolated-vm` an optional peer dependency: consumers who want its stronger isolation guarantees wire their own factory backed by `new ivm.Isolate(...)`, consumers who don't pay no install cost. Tests use a hand-written fake factory that satisfies the same structural contract.
+
+`isolated-vm` provides genuine V8 isolate separation — a separate heap, separate intrinsics, hard memory + timeout limits enforced inside V8 itself. When a consumer needs stronger isolation than `vm-engine` offers but cannot afford the per-call cost of `worker-engine` or `spawn-engine`, `IsolateEngine` plus a real `isolated-vm` factory is the right pick.
+
+## Features
+
+- Structural `IsolateFactory` / `IsolateInstance` / `IsolateContext` /
+  `IsolateReference` / `IsolateScript` interfaces.
+- `executeSync` companion for pool callers.
+- Captured console via injected `__log`/`__warn`/`__error` proxies.
+- Module + context-variable injection.
+- Heap stats via `getHeapStatisticsSync` (returns null after destroy).
+- `reset` disposes + re-creates the underlying isolate.
+
+## Usage: Basic
+
+```ts
+import ivm from "isolated-vm";
+import { IsolateEngine } from "@suaveplan/sandbox/isolate-engine";
+
+const engine = new IsolateEngine({
+    timeout: 5000,
+    maxOutputSize: 1024,
+    memoryLimit: 32 * 1024 * 1024,
+    factory: {
+        createIsolate: (memLimit) =>
+            new ivm.Isolate({ memoryLimit: memLimit / (1024 * 1024) }),
+    },
+});
+```
+
+## Usage: Advanced
+
+Provide a custom factory backed by a test double for deterministic unit
+tests:
+
+```ts
+import { IsolateEngine } from "@suaveplan/sandbox/isolate-engine";
+
+const engine = new IsolateEngine({
+    timeout: 5000,
+    maxOutputSize: 1024,
+    memoryLimit: 32 * 1024 * 1024,
+    factory: {
+        createIsolate: () => myDeterministicIsolate,
+    },
+});
+```
+
+## API Reference
+
+- `IsolateFactory` — `createIsolate(memoryLimit): IsolateInstance`.
+- `IsolateInstance` — `createContextSync`, `compileScriptSync`,
+  `getHeapStatisticsSync`, `dispose`.
+- `IsolateContext` — `global: IsolateReference`, `release`.
+- `IsolateReference` — `setSync`, `getSync`.
+- `IsolateScript` — `runSync(context, { timeout? })`.
+- `new IsolateEngine(options: IsolateEngineOptions)`.
+- `execute`, `executeSync`, `registerModule`, `unregisterModule`,
+  `getHeapStatistics`, `reset`, `destroy`.
+
+## Implementation Notes
+
+The console proxy is set up by injecting three reference functions
+(`__log`/`__warn`/`__error`) into the isolate's global, then prepending a
+`const console = { log: ..., warn: ..., error: ... }` to the compiled script.
+The real `isolated-vm` API serialises across the realm boundary with
+`ExternalCopy` and `Reference`; the structural type intentionally does not
+prescribe that machinery because consumer adapters may wrap arguments
+differently depending on their isolation needs.