# 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.