@earendil-works/djs 0.0.0-stage → 0.1.0

package/dist/sandbox.js

@@ -0,0 +1,1958 @@
+// The Sandbox API: loads djs-wasm (docs/host.md) and runs code in a djs VM. Values go in
+// through the wire format (wire.ts) and come out through direct heap reads (reader.ts).
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { IN_PLACE_MIN, encode, stringInPlace } from "./wire.js";
+import { trapText } from "./trap.js";
+import { Opaque, readValue } from "./reader.js";
+import { provideBase, rememberBase } from "./base.js";
+import { scriptFor as dumpRuntimeFor } from "./dump-runtime.js";
+import { envVar } from "./env.js";
+/** Why a sandbox operation failed. `value` is the thrown VM value (kind "threw"). */
+export class SandboxError extends Error {
+    kind;
+    value;
+    constructor(kind, message, value) {
+        super(message);
+        this.name = "SandboxError";
+        this.kind = kind;
+        this.value = value;
+    }
+}
+const STATUS_DONE = 0;
+const STATUS_THREW = 1;
+const STATUS_OUT_OF_FUEL = 2;
+const STATUS_HOST_CALL = 3;
+const STATUS_IDLE = 4;
+const STATUS_HOST_OUT_OF_MEMORY = 5;
+const ABI_VERSION = 5;
+/** `vm_new_with`'s flag: frozen builtins (D2304). */
+const VM_FROZEN_BUILTINS = 1;
+const CONSOLE_METHODS = ["log", "info", "warn", "error"];
+/**
+ * A plain dump's host hooks (D2832, D2890): the global object `$djs` with `resume(id,
+ * name, args, state)` and `seed(lo, hi)`, defined while the dump's Script runs. Their
+ * function ids are outside the host functions' (ids are places in `fnNames`).
+ */
+const PLAIN_HOOKS = "$djs";
+const HOOK_RESUME = 0x7fff_fff0;
+const HOOK_SEED = 0x7fff_fff1;
+const HOOK_SOURCE = 0x7fff_fff2;
+const HOOK_HOST = 0x7fff_fff3;
+/** An identity `ns.member` of two identifiers: member `member` of the namespace `ns` (D2632). */
+const NAMESPACE_MEMBER = /^([A-Za-z_$][\w$]*)\.([A-Za-z_$][\w$]*)$/;
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+/**
+ * The codemode bodies the sandboxes of this process ran, by name, newest first: what a
+ * dump's `$djs.source(name, hash)` refers to (D2882). A sandbox in another process gets
+ * them from the `sources` option. A few per name are kept.
+ */
+const ranScripts = new Map();
+const SCRIPTS_KEPT = 16;
+/**
+ * The hash of `$djs.source(name, hash, params)` (D2882, `vm::script_hash`): FNV-1a 64 of
+ * the UTF-8 of the parameter names (`,`-joined), the compile option bits in decimal and
+ * the source, `\0`-separated, folded to 32 bits (D2839), as 8 hex digits.
+ */
+export function scriptHash(source, params, bits) {
+    let h = 0xcbf29ce484222325n;
+    const step = (bytes) => {
+        for (const b of bytes)
+            h = BigInt.asUintN(64, (h ^ BigInt(b)) * 0x100000001b3n);
+    };
+    step(textEncoder.encode(params));
+    step(new Uint8Array([0]));
+    step(textEncoder.encode(String(bits)));
+    step(new Uint8Array([0]));
+    step(textEncoder.encode(source));
+    return BigInt.asUintN(32, h ^ (h >> 32n)).toString(16).padStart(8, "0");
+}
+function rememberScript(name, code) {
+    const list = (ranScripts.get(name) ?? []).filter((c) => c !== code);
+    list.unshift(code);
+    if (list.length > SCRIPTS_KEPT)
+        list.length = SCRIPTS_KEPT;
+    ranScripts.set(name, list);
+}
+/** A plain dump (D2830): `"djs-dump";`, and whether its text is TypeScript. */
+export function plainDump(text) {
+    const m = /^\s*"djs-dump( typescript)?";/.exec(text);
+    return m ? { typescript: m[1] !== undefined } : undefined;
+}
+/** The modules being compiled or compiled, by location. */
+const modules = new Map();
+/** The compiled ones, for the synchronous constructor. */
+const compiled = new Map();
+/**
+ * The dump module's sandboxes, one per module and memory limit in the process (D2802):
+ * every sandbox with that `dumpModule` moves its image into the same instance and VM for
+ * a dump or a load, which runs no host function (the loader refuses host calls), so the
+ * VM is the only state they share, and it is replaced each time.
+ */
+const dumpers = new WeakMap();
+/**
+ * The default location of djs-wasm: `$DJS_WASM`, else, running from the repository's
+ * sources (js/src/*.ts), the `wasm` profile build. The package's entry points have their
+ * own defaults (`Sandbox.defaultModule`), the modules shipped in the package (D3106).
+ */
+export function defaultWasmPath() {
+    const env = envVar("DJS_WASM");
+    if (env !== undefined)
+        return env;
+    // Not `new URL("…", import.meta.url)` literally: bundlers take that for an asset of the
+    // package, and the built package has no repository around it.
+    const here = import.meta.url;
+    if (here.endsWith(".ts"))
+        return new URL("../../target/wasm32-unknown-unknown/wasm/djs_wasm.wasm", here);
+    throw new SandboxError("misuse", "no default djs-wasm module: pass a location or set $DJS_WASM");
+}
+/**
+ * Compiles djs-wasm once per location and caches the `WebAssembly.Module` (ARCH: the
+ * module is compiled once; every sandbox gets its own instance). A `file:` URL, or a
+ * string that is no URL in node, Bun or Deno, is read from the file system; anything else
+ * is fetched (in a browser, a relative string is relative to the page).
+ */
+export function loadModule(location = defaultWasmPath()) {
+    const key = String(location);
+    let m = modules.get(key);
+    if (m === undefined) {
+        m = (async () => {
+            let bytes;
+            if (isFile(location)) {
+                // Not a literal specifier, so the package type-checks without node's types, and
+                // bundlers for the browser leave it alone.
+                const fsModule = "node:fs/promises";
+                const fs = (await import(__rewriteRelativeImportExtension(/* @vite-ignore */ /* webpackIgnore: true */ fsModule)));
+                bytes = await fs.readFile(typeof location === "string" && /^file:/i.test(location) ? new URL(location) : location);
+            }
+            else {
+                const r = await fetch(location);
+                if (!r.ok)
+                    throw new SandboxError("misuse", `cannot fetch djs-wasm from ${key}: HTTP ${r.status}`);
+                bytes = new Uint8Array(await r.arrayBuffer());
+            }
+            return WebAssembly.compile(bytes);
+        })();
+        modules.set(key, m);
+        m.then((mod) => compiled.set(key, mod), () => modules.delete(key));
+    }
+    return m;
+}
+/** Whether `loadModule` reads `location` from the file system (else it fetches it). */
+function isFile(location) {
+    // A scheme of two letters or more: `C:\x` is a path.
+    const url = typeof location === "string" ? /^([a-z][a-z0-9+.-]+):/i.exec(location)?.[1] : location.protocol.slice(0, -1);
+    if (url !== undefined)
+        return url.toLowerCase() === "file";
+    const g = globalThis;
+    return g.process?.versions?.node !== undefined || g.Deno !== undefined || g.Bun !== undefined;
+}
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+/**
+ * A run the host drives itself (docs/host.md "Host-driven runs"; the part 0179
+ * needs of 0175): `Sandbox.begin` runs a body to its first idle point, the host settles
+ * the open async calls in any order and advances it, and while it is idle it can be
+ * dumped (`dump()`) and continued elsewhere (`Sandbox.resume`). The async host functions
+ * are never called by the run: `calls` lists them and the host answers, so that a call
+ * can outlive the process that issued it. Sync host functions are called as in `run`.
+ */
+export class Run {
+    /** "idle": waiting on `calls`; "done": `value` is the result; "threw": `error`. */
+    state = "idle";
+    value = undefined;
+    error = undefined;
+    #core;
+    /** Made by `Sandbox.begin` and `Sandbox.resume`. */
+    constructor(core) {
+        this.#core = core;
+    }
+    /** The async host calls waiting for a result, oldest first. */
+    get calls() {
+        return [...this.#core.open.values()];
+    }
+    /**
+     * Delivers the result of open call `id`. The VM applies it at the next `advance`, after
+     * the results settled before it (D1670).
+     */
+    settle(id, s) {
+        this.#core.settle(id, s);
+    }
+    /**
+     * Runs to the next idle point (or the end): applies the settled results, and calls the
+     * sync host functions the script calls meanwhile (awaiting them if they return
+     * promises). New async calls show up in `calls`.
+     */
+    async advance() {
+        if (this.state !== "idle")
+            throw new SandboxError("misuse", `the run is ${this.state}`);
+        this.end(await this.#core.advance());
+    }
+    /**
+     * The waiting run as a dump (a plain Script, D2830; docs/plain-js-dumps.md): its
+     * suspended activations, open calls and data as JavaScript, for `loadRun` in another
+     * sandbox or process. Only while idle, and only with `frozenBuiltins` (D2836). `states` are the host's states of open calls, by id (JSON
+     * data, D2770): the dump writes each with its call, and the load gives it back
+     * (`OpenCall.state`).
+     */
+    dump(states = {}) {
+        if (this.state !== "idle")
+            throw new SandboxError("misuse", `the run is ${this.state}: only an idle run can be dumped`);
+        return this.#core.dump(Object.entries(states).map(([id, v]) => [Number(id), stateJson(Number(id), v)]));
+    }
+    /** Records how a step ended. */
+    end(e) {
+        this.state = e.state;
+        if (e.state === "done")
+            this.value = e.value;
+        if (e.state === "threw")
+            this.error = e.error;
+    }
+}
+/**
+ * A run the sandbox drives (D2771): `Sandbox.start` begins one, `Sandbox.resume`
+ * continues one from a dump. It calls the async host functions as the script calls them
+ * and passes their results back, like `runAsync`; `result` is the outcome. While it waits
+ * on host calls it can be suspended (`suspend()`): the sandbox writes it as a dump, with
+ * each open call's state from its function's `save` hook, and stops. `Sandbox.resume`
+ * continues the dump in a new sandbox, any time later and in any process: each open call
+ * is continued by its function's `resume` hook (or made again, or rejected).
+ */
+export class Task {
+    /** The sandbox the task runs in (dispose it when done). */
+    sandbox;
+    /**
+     * The run's result. Rejects with a SandboxError: `threw` for an exception, `suspended`
+     * when the task was suspended into a dump (this rejection counts as handled).
+     */
+    result;
+    #calls;
+    #request;
+    /** Made by `Sandbox.start` and `Sandbox.resume`. */
+    constructor(sandbox, result, calls, request) {
+        this.sandbox = sandbox;
+        this.result = result;
+        this.#calls = calls;
+        this.#request = request;
+    }
+    /** The async host calls the task waits for, oldest first. */
+    get calls() {
+        return [...this.#calls.values()].map((c) => c.call);
+    }
+    /**
+     * Suspends the task at its next idle point (no script work left, only host calls to
+     * wait for): calls `save` for every open call, dumps the run with those states and
+     * stops. The open calls' signals are aborted and their results ignored; `result`
+     * rejects with kind `suspended`. Resolves to the dump (a Script, for
+     * `Sandbox.resume`). Rejects, and the task goes on, when the run cannot be dumped (or a
+     * `save` throws); rejects when the run ends first.
+     */
+    suspend() {
+        return new Promise((resolve, reject) => this.#request({ stop: true, resolve, reject }));
+    }
+    /** `suspend` without stopping: a dump at the next idle point, and the task goes on. */
+    checkpoint() {
+        return new Promise((resolve, reject) => this.#request({ stop: false, resolve, reject }));
+    }
+}
+/** `drive`'s value at an idle point of a host-driven run. */
+const IDLE = Symbol("idle");
+export class Sandbox {
+    x;
+    module;
+    /** The VM; replaced when the dump module's sandbox takes another image (`takeImage`). */
+    vm;
+    opts;
+    /** Host function names by id - 1. */
+    fnNames = [];
+    fns = new Map();
+    /** Async host functions with hooks (D2771), by id. */
+    hooks = new Map();
+    atomCache = [];
+    rejections = [];
+    cons;
+    dead = null;
+    /** Deterministic mode: the VM's clock, moved only by async results (never backwards). */
+    clock;
+    /** The journal of the current run, being recorded or replayed (D1730). */
+    journal = null;
+    /** The first hook a dump's load could not serve (D3001). */
+    hookError = undefined;
+    /** Namespace objects this sandbox made for dotted function names (`tools`), as handles. */
+    namespaces = new Map();
+    /** The host function objects by id, as handles: one per identity (D2970). */
+    fnHandles = new Map();
+    fnAsync = new Map();
+    /** The globals the sandbox bound to host functions and namespaces (a dump's host globals). */
+    globalNames = new Set();
+    /** The host-driven run in progress (`begin`, `resume`), until it ends. */
+    active = null;
+    /** The task in progress (`start`, `resume`): ends it when the sandbox is disposed. */
+    cancelTask = null;
+    /**
+     * Where `create` and the constructor find the module when `opts.module` is not given:
+     * here `defaultWasmPath()`; each entry point of the package overrides it with its own
+     * module (D3106).
+     */
+    static defaultModule() {
+        return defaultWasmPath();
+    }
+    /** A new sandbox; loads (and caches) the default module unless `opts.module` is given. */
+    static async create(opts = {}) {
+        return new this({ ...opts, module: opts.module ?? (await loadModule(this.defaultModule())) });
+    }
+    /**
+     * Continues a task from its dump (`Task.suspend()`, or a host-driven `Run.dump()`) in
+     * a new sandbox made from `opts` (the same host functions, by name, as the one that
+     * dumped): `(await Sandbox.resume(dump, opts)).result`. See `resume`. A dump is code:
+     * resume only dumps you trust.
+     */
+    static async resume(dump, opts = {}) {
+        const sandbox = await this.create(opts);
+        try {
+            return sandbox.resume(dump);
+        }
+        catch (e) {
+            sandbox.dispose();
+            throw e;
+        }
+    }
+    /**
+     * Loads a dumped run into this sandbox (a fresh one) and drives it (D2771): each open
+     * call is continued by its function's `resume` hook with the state it was dumped with,
+     * made again (`call`) when the function has no `resume`, and rejected when it is a
+     * plain function (the sandbox cannot know whether calling it again is safe).
+     */
+    resume(dump) {
+        const { calls, result } = this.loadRunDump(dump);
+        return this.task(this.startRun(calls, result), calls);
+    }
+    /**
+     * Loads a dumped run into this sandbox (a fresh one) for the host to drive: the run is
+     * idle, waiting on the same open calls with the same ids (`run.calls`, with their
+     * states); the host settles them, issues them again or rejects them. No hooks run.
+     */
+    loadRun(dump) {
+        const { calls, result } = this.loadRunDump(dump);
+        return this.startRun(calls, result).run;
+    }
+    /** Loads a dump that holds a run: its open calls and the run's result promise. */
+    loadRunDump(dump) {
+        const { calls, handles } = this.loadDump(dump);
+        const result = handles.get("run") ?? 0;
+        this.guard(() => {
+            for (const [name, h] of handles)
+                if (name !== "run")
+                    this.x.vm_handle_free(this.vm, h);
+        });
+        if (result === 0)
+            throw new SandboxError("misuse", "the dump holds no run (no handle named run)");
+        return { calls, result };
+    }
+    /**
+     * A new sandbox (its own wasm instance and VM), synchronously: needs a compiled module,
+     * `opts.module` or one `loadModule()` has finished loading. (`raw`: internal, a VM image
+     * of this process moving to the dump module, D2635.)
+     */
+    constructor(opts = {}, raw) {
+        let module = opts.module;
+        if (module === undefined) {
+            try {
+                module = compiled.get(String(new.target.defaultModule()));
+            }
+            catch {
+                // No default location: the error below.
+            }
+        }
+        if (module === undefined) {
+            throw new SandboxError("misuse", "no compiled module: pass opts.module or await loadModule() first");
+        }
+        const x = new WebAssembly.Instance(module, {}).exports;
+        if (x.djs_abi_version() !== ABI_VERSION) {
+            throw new SandboxError("misuse", `djs-wasm ABI ${x.djs_abi_version()}, expected ${ABI_VERSION}`);
+        }
+        let vm;
+        let restoredFns = [];
+        if (raw === undefined) {
+            // The module's base, decoded once by its first instance, not by each (D2252), and
+            // kept for later instances before `vm_new` takes this instance's bytes as its arena
+            // (D2060).
+            provideBase(module, x);
+            rememberBase(module, x);
+            if (opts.frozenBuiltins) {
+                if (!x.vm_new_with)
+                    throw new SandboxError("misuse", "the djs-wasm module has no frozenBuiltins (vm_new_with)");
+                vm = x.vm_new_with(opts.memoryLimit ?? 0, 0, VM_FROZEN_BUILTINS);
+            }
+            else
+                vm = x.vm_new(opts.memoryLimit ?? 0);
+            if (vm === 0)
+                throw new SandboxError("memory", "memory limit too small for the realm");
+        }
+        else {
+            const image = raw.image;
+            restoredFns = raw.functions;
+            if (opts.deterministic)
+                this.clock = raw.clock ?? opts.deterministic.startedAt;
+            for (const [ns, h] of raw.namespaces)
+                this.namespaces.set(ns, h);
+            for (const [id, h] of raw.fnHandles)
+                this.fnHandles.set(id, h);
+            for (const g of raw.globals)
+                this.globalNames.add(g);
+            // May grow memory: take the buffer afterwards. The image's buffer becomes the arena,
+            // so it is staged with the arena's capacity (D1942).
+            const limit = opts.memoryLimit ?? 0;
+            const at = x.djs_image_staging ? x.djs_image_staging(image.length, limit) : x.djs_staging(image.length);
+            new Uint8Array(x.memory.buffer).set(image, at);
+            vm = x.vm_from_bytes(image.length, opts.memoryLimit ?? 0);
+            if (vm === 0)
+                throw new SandboxError("misuse", outText(x));
+        }
+        this.x = x;
+        this.module = module;
+        this.vm = vm;
+        this.opts = opts;
+        const cons = opts.console ?? globalThis.console;
+        this.cons = cons;
+        const builtins = {};
+        for (const m of CONSOLE_METHODS)
+            builtins[`console.${m}`] = (...a) => cons[m](...a);
+        if (raw !== undefined) {
+            // The VM already has its host functions; bind the ids to the given implementations.
+            restoredFns.forEach((name, i) => {
+                const a = name === "debugger" && opts.debugger !== undefined ? opts.debugger : opts.asyncFunctions?.[name];
+                const f = builtins[name] ?? opts.functions?.[name] ?? (typeof a === "object" ? a.call : a);
+                if (f === undefined)
+                    throw new SandboxError("misuse", `the image needs host function ${name}`);
+                this.fnNames.push(name);
+                this.fns.set(i + 1, f);
+                if (typeof a === "object")
+                    this.hooks.set(i + 1, a);
+            });
+        }
+        else {
+            // `console` is a namespace like `tools` (a host root of dumps, D2971).
+            for (const m of CONSOLE_METHODS)
+                this.addFunction(`console.${m}`, builtins[`console.${m}`], false);
+            for (const [name, f] of Object.entries(opts.functions ?? {}))
+                this.addFunction(name, f, false);
+            for (const [name, f] of Object.entries(opts.asyncFunctions ?? {}))
+                this.addFunction(name, f, true);
+            if (opts.debugger !== undefined) {
+                if (!x.vm_dump)
+                    throw new SandboxError("misuse", "the debugger option needs a djs-wasm module with the dumper (the `dump` feature)");
+                this.addFunction("debugger", opts.debugger, true);
+            }
+            const globals = { ...(opts.globals ?? this.defaultGlobals()) };
+            if (opts.debugger !== undefined)
+                globals.debugger = "debugger";
+            for (const [name, identity] of Object.entries(globals))
+                this.bindGlobal(name, identity);
+            // What a new VM starts with; an image keeps its own (D1680).
+            const det = opts.deterministic;
+            const [lo, hi] = det ? seedWords(det.seed) : opts.randomSeed !== undefined ? seedWords(opts.randomSeed) : entropy();
+            x.vm_set_random_seed(vm, lo, hi);
+            const weak = opts.weakRefs ?? (det ? "strong" : "collected");
+            if (this.guard(() => x.vm_set_weak_refs(vm, WEAK_REF_MODES[weak])) !== 0) {
+                throw new SandboxError("misuse", `bad weakRefs mode ${String(weak)}`);
+            }
+            if (det) {
+                this.clock = det.startedAt;
+                x.vm_set_now(vm, det.startedAt);
+                x.vm_set_time_zone_offset(vm, 0);
+            }
+        }
+    }
+    /**
+     * Defines a host function with identity `name` and binds it as a global by the written
+     * rule (`SandboxOptions.globals`): `tools.read` as member `read` of the global namespace
+     * `tools`, an identifier as the global of that name, anything else nowhere.
+     */
+    defineFunction(name, f) {
+        this.addFunction(name, f, false);
+        this.bindDefault(name);
+    }
+    /** Defines an async host function (see `SandboxOptions.asyncFunctions`), bound as `defineFunction` does. */
+    defineAsyncFunction(name, f) {
+        this.addFunction(name, f, true);
+        this.bindDefault(name);
+    }
+    /** Makes host function `name` and, for `ns.member`, adds it to the namespace `ns`. */
+    addFunction(name, f, async) {
+        this.guard(() => {
+            const h = this.hostFunction(name, f, async);
+            const m = NAMESPACE_MEMBER.exec(name);
+            if (m)
+                this.defineOn(this.namespace(m[1]), m[2], h);
+        });
+    }
+    /** The namespace object `ns`, made on first use (D2632); bound nowhere by itself. */
+    namespace(ns) {
+        let o = this.namespaces.get(ns);
+        if (o === undefined) {
+            o = this.check(this.x.vm_new_object(this.vm), "memory");
+            this.namespaces.set(ns, o);
+        }
+        return o;
+    }
+    /** The written rule: the globals the sandbox binds without `SandboxOptions.globals`. */
+    defaultGlobals() {
+        const globals = {};
+        for (const name of this.fnNames) {
+            const m = NAMESPACE_MEMBER.exec(name);
+            if (m)
+                globals[m[1]] = m[1];
+            else if (IDENTIFIER.test(name))
+                globals[name] = name;
+        }
+        return globals;
+    }
+    bindDefault(name) {
+        const m = NAMESPACE_MEMBER.exec(name);
+        if (m)
+            this.bindGlobal(m[1], m[1]);
+        else if (IDENTIFIER.test(name))
+            this.bindGlobal(name, name);
+    }
+    /** The object of a namespace or host function by identity (D2970), as a handle the sandbox owns. */
+    hostValue(identity) {
+        return this.namespaces.get(identity) ?? this.fnHandles.get(this.fnNames.indexOf(identity) + 1);
+    }
+    bindGlobal(name, identity) {
+        const h = this.hostValue(identity);
+        if (h === undefined)
+            throw new SandboxError("misuse", `global ${name}: no host function or namespace ${identity}`);
+        this.guard(() => {
+            const g = this.x.vm_global(this.vm);
+            this.defineOn(g, name, h);
+            this.x.vm_handle_free(this.vm, g);
+        });
+        this.globalNames.add(name);
+    }
+    /** Defines a global variable holding a copy of `value` (sent through the wire format). */
+    setGlobal(name, value) {
+        this.guard(() => {
+            const h = this.toHandle(value);
+            const g = this.x.vm_global(this.vm);
+            this.defineOn(g, name, h);
+            this.x.vm_handle_free(this.vm, g);
+            if (h !== 0)
+                this.x.vm_handle_free(this.vm, h);
+        });
+    }
+    /**
+     * Runs `code` as a codemode function body (`return` gives the result) with the
+     * `params` as its parameters (sent through the wire format). `console` is a global. Host
+     * functions must return synchronously; use `runAsync` for ones that return promises. A
+     * promise as the result is unwrapped (fulfilled: its value; rejected: thrown).
+     */
+    run(code, params = {}, opts = {}) {
+        this.beginJournal(code, params, opts);
+        this.enter(code, params);
+        try {
+            // In sync mode the loop never yields: a promise from a host function is an error.
+            return this.auto(false).next().value;
+        }
+        catch (e) {
+            this.abandon(e);
+            throw e;
+        }
+        finally {
+            this.endRun();
+            this.journal = null;
+        }
+    }
+    /**
+     * Starts `code` as a codemode function body (as `run`) and runs it to its first idle
+     * point or its end, for the host to drive (`Run`): async host functions are not called
+     * but listed in `run.calls`. Sync host functions must return synchronously here (as in
+     * `run`); `advance` awaits them. A compile error throws; an exception in the script is
+     * `run.state === "threw"`. One run at a time: the sandbox runs nothing else until it
+     * ends.
+     */
+    begin(code, params = {}, opts = {}) {
+        this.beginJournal(code, params, opts);
+        this.enter(code, params, false, opts.filename);
+        const core = this.startRun([], 0);
+        try {
+            core.run.end(this.step(core, false).next().value);
+        }
+        catch (e) {
+            this.endRun();
+            this.abandon(e);
+            throw e;
+        }
+        if (core.run.state !== "idle")
+            this.endRun();
+        return core.run;
+    }
+    /**
+     * Starts `code` as a codemode function body (as `runAsync`) in a task the sandbox
+     * drives (D2771): it calls the async host functions as the script calls them, and
+     * `task.result` is the outcome. Unlike `runAsync`, the task can be suspended into a
+     * dump while it waits (`task.suspend()`) and continued later (`Sandbox.resume`). The
+     * first step runs now: a compile error throws. One task or run at a time.
+     */
+    start(code, params = {}, opts = {}) {
+        this.beginJournal(code, params, opts);
+        this.enter(code, params, false, opts.filename);
+        return this.task(this.startRun([], 0), []);
+    }
+    /**
+     * Drives `core` as a task: continues the `loaded` calls of a resumed run through their
+     * hooks, calls new async host functions as the script calls them, delivers results at
+     * the next slice, and serves `suspend`/`checkpoint` at idle points.
+     */
+    task(core, loaded) {
+        const calls = new Map();
+        const finished = [];
+        const requests = [];
+        let ended = false;
+        let wake = null;
+        const poke = () => {
+            const w = wake;
+            wake = null;
+            w?.();
+        };
+        const done = (id, ok, value) => {
+            if (ended || !calls.has(id))
+                return;
+            finished.push({ id, ok, value });
+            poke();
+        };
+        // Starts (or, after a load, continues) a call; its outcome arrives through `done`.
+        const begin = (open, loaded) => {
+            const fnId = this.fnNames.indexOf(open.fn) + 1;
+            const live = newCall(open.id, open.fn, open.args, open.state);
+            calls.set(open.id, live);
+            let r;
+            try {
+                const hooks = this.hooks.get(fnId);
+                if (!loaded)
+                    r = this.invoke(fnId, open.args, live.call);
+                else if (hooks === undefined) {
+                    throw new Error(`${open.fn}: the call was open when the run was dumped, and the host function has no hooks to continue it`);
+                }
+                else if (hooks.resume)
+                    r = hooks.resume(open.state, live.call);
+                else
+                    r = this.invoke(fnId, open.args, live.call);
+            }
+            catch (e) {
+                done(open.id, false, e);
+                return;
+            }
+            if (r instanceof Promise)
+                r.then((v) => done(open.id, true, v), (e) => done(open.id, false, e));
+            else
+                done(open.id, true, r);
+        };
+        core.onCall = (call) => begin(call, false);
+        core.beforeSlice = () => {
+            for (const { id, ok, value } of finished.splice(0)) {
+                calls.delete(id);
+                core.deliver(id, ok, value);
+            }
+        };
+        const stopWaiting = () => {
+            ended = true;
+            this.cancelTask = null;
+            for (const c of calls.values())
+                c.abort.abort();
+            for (const r of requests.splice(0))
+                r.reject(new SandboxError("misuse", "the task ended before an idle point"));
+        };
+        let settle;
+        const result = new Promise((resolve, reject) => (settle = { resolve, reject }));
+        const stop = (e) => {
+            if (ended)
+                return;
+            stopWaiting();
+            if (this.active === core)
+                this.endRun();
+            if (e.kind === "suspended")
+                result.catch(() => { });
+            settle.reject(e);
+            poke();
+        };
+        this.cancelTask = () => stop(new SandboxError("misuse", "the sandbox was disposed"));
+        // The dump at an idle point: each open call's state, from `save` or `call.state`.
+        const dump = () => {
+            const states = [];
+            for (const { call } of calls.values()) {
+                const save = this.hooks.get(this.fnNames.indexOf(call.fn) + 1)?.save;
+                const state = save ? save(call) : call.state;
+                if (state !== undefined)
+                    states.push([call.id, stateJson(call.id, state)]);
+            }
+            return this.dumpRun(core, states);
+        };
+        const loop = async () => {
+            for (;;) {
+                const end = await core.advance();
+                if (ended)
+                    return;
+                if (end.state !== "idle") {
+                    stopWaiting();
+                    if (end.state === "done")
+                        settle.resolve(end.value);
+                    else
+                        settle.reject(end.error);
+                    return;
+                }
+                // Idle: deliver what came in meanwhile, serve dump requests, or wait.
+                while (finished.length === 0 && !ended) {
+                    const asked = requests.splice(0);
+                    if (asked.length > 0) {
+                        let text;
+                        try {
+                            text = dump();
+                        }
+                        catch (e) {
+                            for (const r of asked)
+                                r.reject(e);
+                            continue;
+                        }
+                        for (const r of asked)
+                            r.resolve(text);
+                        if (asked.some((r) => r.stop)) {
+                            stop(new SandboxError("suspended", "the task was suspended into a dump"));
+                            return;
+                        }
+                        continue;
+                    }
+                    if (calls.size === 0) {
+                        // Nothing to wait for (as in `runAsync`): the run is over without a result.
+                        stopWaiting();
+                        this.endRun();
+                        settle.resolve(undefined);
+                        return;
+                    }
+                    await new Promise((w) => (wake = w));
+                }
+                if (ended)
+                    return;
+            }
+        };
+        for (const c of loaded)
+            begin(c, true);
+        const task = new Task(this, result, calls, (r) => {
+            if (ended)
+                r.reject(new SandboxError("misuse", "the task has ended"));
+            else {
+                requests.push(r);
+                poke();
+            }
+        });
+        loop().catch((e) => {
+            if (ended)
+                return;
+            stopWaiting();
+            settle.reject(e);
+        });
+        return task;
+    }
+    /** Makes a run, waiting on `calls`, with its result promise `result` (0: the entry call's). */
+    startRun(calls, result) {
+        const core = {
+            open: new Map(calls.map((c) => [c.id, c])),
+            result,
+            used: 0,
+            run: undefined,
+            advance: async () => {
+                try {
+                    const it = this.step(core, true);
+                    let r = it.next();
+                    while (!r.done)
+                        r = it.next(await r.value);
+                    const end = r.value;
+                    if (end.state !== "idle")
+                        this.endRun();
+                    return end;
+                }
+                catch (e) {
+                    this.endRun();
+                    this.abandon(e);
+                    throw e;
+                }
+            },
+            settle: (id, s) => {
+                if (this.active !== core)
+                    throw new SandboxError("misuse", "the run has ended");
+                if (!core.open.has(id))
+                    throw new SandboxError("misuse", `no open call ${id}`);
+                core.deliver(id, s.ok, s.value);
+            },
+            deliver: (id, ok, value, at) => {
+                const call = core.open.get(id);
+                core.open.delete(id);
+                const now = this.complete(id, ok, value, true, at);
+                const j = this.journal;
+                if (j)
+                    j.delivered++;
+                if (j?.mode === "record" && call) {
+                    j.push({ type: "async", callId: id, fn: call.fn, args: call.args, ok, value: errorJson(ok, value), now: now });
+                }
+            },
+            dump: (states) => {
+                if (this.active !== core)
+                    throw new SandboxError("misuse", "the run has ended");
+                return this.dumpRun(core, states);
+            },
+        };
+        core.run = new Run(core);
+        this.active = core;
+        return core;
+    }
+    /** One step of a host-driven run: `drive` until idle (recording a check) or the end. */
+    *step(core, async) {
+        try {
+            const r = yield* this.drive(async, core);
+            if (r !== IDLE)
+                return { state: "done", value: r };
+            this.recordCheck();
+            return { state: "idle" };
+        }
+        catch (e) {
+            if (e instanceof SandboxError && e.kind === "threw")
+                return { state: "threw", error: e };
+            throw e;
+        }
+    }
+    /**
+     * The run loop of `run`, `runAsync` and `replay`, on top of the host-driven run (`drive`
+     * to each idle point): calls the async host functions as soon as the script calls them
+     * (or, replaying, takes their results from the journal), passes their results back
+     * before the next fuel slice, and at an idle point waits for the next one. Yields a
+     * promise when the host must wait (only when `async`), returns the result.
+     */
+    *auto(async) {
+        const j = this.journal;
+        // Async host calls being served, and those that finished but are not passed back yet.
+        const inflight = new Map();
+        const finished = [];
+        const core = this.startRun([], 0);
+        core.beforeSlice = () => {
+            for (const { callId, ok, value } of finished.splice(0)) {
+                inflight.delete(callId);
+                core.deliver(callId, ok, value);
+            }
+        };
+        core.onCall = (call, fnId) => {
+            // Replay: the result comes from the journal, at an idle point.
+            if (j?.mode === "replay")
+                return;
+            const callId = call.id;
+            let p;
+            try {
+                const r = this.invoke(fnId, call.args);
+                if (!(r instanceof Promise)) {
+                    finished.push({ callId, ok: true, value: r });
+                    return;
+                }
+                if (!async)
+                    throw new TypeError(`host function ${call.fn} returned a promise; use runAsync`);
+                p = r;
+            }
+            catch (e) {
+                finished.push({ callId, ok: false, value: e });
+                return;
+            }
+            inflight.set(callId, p.then((value) => void finished.push({ callId, ok: true, value }), (value) => void finished.push({ callId, ok: false, value })));
+        };
+        for (;;) {
+            const r = yield* this.drive(async, core);
+            if (r !== IDLE)
+                return r;
+            if (j?.mode === "record")
+                this.recordCheck();
+            else if (j && core.open.size > 0) {
+                // Replay: the checks recorded at this point, then the next result.
+                j.checkIdle(this.canonicalHash());
+                const e = j.take("async");
+                const call = core.open.get(e.callId);
+                j.expect(call !== undefined, () => `result ${j.delivered + 1} is for call ${e.callId}, which the script has not made`);
+                j.expectCall(e.fn, e.args, call.fn, call.args);
+                core.deliver(e.callId, e.ok, e.ok ? e.value : errorFromJson(e.value), e.now);
+                continue;
+            }
+            if (finished.length > 0)
+                continue;
+            if (inflight.size === 0)
+                return undefined; // nothing was called
+            // Only async host calls are left: wait for one of them.
+            yield Promise.race(inflight.values());
+        }
+    }
+    /** Records a `check` entry at an idle point, when recording. */
+    recordCheck() {
+        const j = this.journal;
+        if (j?.mode === "record")
+            j.push({ type: "check", delivered: j.delivered, issued: j.issued, hash: this.canonicalHash() });
+    }
+    /** The run has ended: frees its result handle; the sandbox can run again. */
+    endRun() {
+        const a = this.active;
+        this.active = null;
+        this.journal = null;
+        if (a !== null && a.result !== 0 && this.dead === null) {
+            this.x.vm_handle_free(this.vm, a.result);
+            a.result = 0;
+        }
+    }
+    /**
+     * `Run.dump()`: the waiting run as a dump, its result promise named "run" (handle
+     * 0: the entry call's outcome, which takes no handle, so a dump leaves the heap as it
+     * was and a journal's later checks still replay).
+     */
+    dumpRun(core, states = []) {
+        return this.dumpText([], [["run", core.result]], states);
+    }
+    /**
+     * The VM's global bindings (or the ones in `names`) as JavaScript that recreates them
+     * when `load`ed into another sandbox, also of a later djs (docs/functions-as-code.md):
+     * functions as their source text, closures and data as code, builtins by name. The
+     * host's functions and `console` are not written: the loading sandbox provides them
+     * under the same names. Needs `frozenBuiltins` (D2836). Throws a "misuse" error listing
+     * every value that cannot be written, by its path (a weak collection, a Proxy, ...).
+     */
+    dump(names = []) {
+        return this.dumpText(names, [], []);
+    }
+    /**
+     * `vm_dump`. staging: the globals the host defines and the names to dump (comma
+     * separated, a line each), then this sandbox's host function names (tab separated, id
+     * order: an open call or a host function held as a value is written by name), then
+     * the values to name for the host (`handle:name`, tab separated), then the host roots
+     * (the namespace objects, `handle:name`, written as `$djs.host(name)`, D2971), then the open calls'
+     * states (`id:bytes`, tab separated) followed by their JSON texts (D2770).
+     */
+    dumpText(names, handles, states) {
+        // Dumps need frozen builtins (D2836): the VM's mode, which a restored sandbox keeps
+        // from its image.
+        if (this.x.vm_frozen_builtins?.(this.vm) !== 1) {
+            throw new SandboxError("misuse", "cannot dump: dumps need frozen builtins (SandboxOptions.frozenBuiltins, D2836)");
+        }
+        const refs = !this.opts.inlineSources;
+        return this.viaDumper((sb) => sb.dumpHere(names, handles, states, refs));
+    }
+    /**
+     * Runs `f` on a sandbox with the dumper: this one, or (with `opts.dumpModule`, D2635)
+     * a transient sandbox in the dump module made from this VM's image. The image travels
+     * as is, so a dump leaves this VM untouched (D2633).
+     */
+    viaDumper(f) {
+        const dm = this.opts.dumpModule;
+        if (dm === undefined)
+            return f(this);
+        this.alive();
+        const raw = (sb) => ({
+            image: sb.arena().slice(),
+            functions: [...sb.fnNames],
+            clock: sb.clock,
+            namespaces: [...sb.namespaces],
+            fnHandles: [...sb.fnHandles],
+            globals: [...sb.globalNames],
+        });
+        // One dump-module sandbox per module and memory limit, kept between dumps (D2701,
+        // D2802): an instance costs a base, and its VM keeps what the dumper derives from the
+        // base on the first dump.
+        const limit = this.opts.memoryLimit ?? 0;
+        let byLimit = dumpers.get(dm);
+        if (byLimit === undefined)
+            dumpers.set(dm, (byLimit = new Map()));
+        let d = byLimit.get(limit);
+        if (d === undefined || d.dead !== null) {
+            d = new Sandbox({ ...this.opts, module: dm, dumpModule: undefined }, raw(this));
+            byLimit.set(limit, d);
+        }
+        else
+            d.takeImage(raw(this));
+        return f(d);
+    }
+    /** The dump module's sandbox: takes the main sandbox's image into the same VM. */
+    takeImage(raw) {
+        const x = this.x;
+        this.fnNames.splice(0, this.fnNames.length, ...raw.functions);
+        this.namespaces.clear();
+        for (const [ns, h] of raw.namespaces)
+            this.namespaces.set(ns, h);
+        this.fnHandles.clear();
+        for (const [id, h] of raw.fnHandles)
+            this.fnHandles.set(id, h);
+        this.globalNames.clear();
+        for (const g of raw.globals)
+            this.globalNames.add(g);
+        if (!x.vm_replace_image) {
+            this.replaceVm(raw);
+            return;
+        }
+        this.guard(() => {
+            const limit = this.opts.memoryLimit ?? 0;
+            const at = x.djs_image_staging ? x.djs_image_staging(raw.image.length, limit) : x.djs_staging(raw.image.length);
+            new Uint8Array(x.memory.buffer).set(raw.image, at);
+            if (x.vm_replace_image(this.vm, raw.image.length) !== 0) {
+                throw new SandboxError("misuse", `the image does not load in the dump module: ${outText(x)}`);
+            }
+        });
+        this.clock = raw.clock;
+        this.atomCache.length = 0;
+    }
+    /** Replaces this sandbox's VM with an image (from the dump module). */
+    replaceVm(raw) {
+        const x = this.x;
+        this.guard(() => {
+            x.vm_free(this.vm);
+            const limit = this.opts.memoryLimit ?? 0;
+            const at = x.djs_image_staging ? x.djs_image_staging(raw.image.length, limit) : x.djs_staging(raw.image.length);
+            new Uint8Array(x.memory.buffer).set(raw.image, at);
+            const vm = x.vm_from_bytes(raw.image.length, limit);
+            if (vm === 0) {
+                this.dead = `lost its VM: ${outText(x)}`;
+                throw new SandboxError("misuse", `the dump module's image does not load here: ${outText(x)}`);
+            }
+            this.vm = vm;
+        });
+        this.clock = raw.clock;
+        this.atomCache.length = 0;
+    }
+    /**
+     * A plain dump's `$djs.source(name, hash, params)` (D2882): the codemode body `name`
+     * compiled again as this sandbox runs bodies, the one whose hash is the dump's (the
+     * `sources` option's code first, then the scripts this process ran, newest first).
+     */
+    serveSource(callId, args) {
+        const x = this.x;
+        const vm = this.vm;
+        const [name, hash, params] = args;
+        const fail = (why) => this.failHook(callId, new Error(`source: ${why}`));
+        if (typeof name !== "string" || typeof hash !== "string")
+            return void fail("not a name and a hash");
+        const candidates = [];
+        const given = this.opts.sources?.(name);
+        if (given !== undefined)
+            candidates.push(given);
+        for (const code of ranScripts.get(name) ?? [])
+            if (code !== given)
+                candidates.push(code);
+        if (candidates.length === 0) {
+            return void fail(`the dump continues the script ${JSON.stringify(name)}, which this host does not have (pass the sandbox option \`sources\`, or dump with \`inlineSources\`)`);
+        }
+        const o = this.opts;
+        const goal = 1 | (o.typescript ? 2 : 0) | (o.experimentalDecorators || o.emitDecoratorMetadata ? 4 : 0) | (o.emitDecoratorMetadata ? 8 : 0) | (o.debugger ? 16 : 0);
+        // The script's compile options as the dump's hash counts them (`CompileOptions::bits`).
+        const bits = 1 | (goal & 2 ? 4 : 0) | (goal & 12 ? 8 : 0) | (goal & 8 ? 16 : 0) | (goal & 16 ? 64 : 0);
+        const ps = typeof params === "string" ? params : "";
+        const code = candidates.find((c) => scriptHash(c, ps, bits) === hash);
+        if (code === undefined)
+            return void fail(`the host's script ${JSON.stringify(name)} is not the one the dump refers to (another text, parameters or options)`);
+        const n = textEncoder.encode(name);
+        const head = textEncoder.encode(ps.split(",").filter((p) => p !== "").join("\n"));
+        const src = textEncoder.encode(code);
+        const all = new Uint8Array(n.length + head.length + src.length);
+        all.set(n);
+        all.set(head, n.length);
+        all.set(src, n.length + head.length);
+        const f = this.guard(() => {
+            this.stage(all);
+            return x.vm_compile_file(vm, goal, n.length, head.length, src.length);
+        });
+        if (f === 0)
+            return void fail(outText(x));
+        this.guard(() => {
+            x.vm_resolve_host_call(vm, callId, 1, f);
+            x.vm_handle_free(vm, f);
+        });
+    }
+    /**
+     * A plain dump's `$djs.host(name)` (D2971): the object this sandbox made for host
+     * function `name` (its identity) or for the namespace `name` (`tools`, `console`).
+     */
+    serveHost(callId, args) {
+        const [name] = args;
+        const h = typeof name === "string" ? this.hostValue(name) : undefined;
+        if (h === undefined)
+            return void this.failHook(callId, new Error(`host: unknown host value ${String(name)}`));
+        this.guard(() => this.x.vm_resolve_host_call(this.vm, callId, 1, h));
+    }
+    /**
+     * A hook that cannot be served: its call throws, and the load fails once the Script ran
+     * (a hook the dump calls inside a continuation, D3001, throws into its activation, not
+     * the Script).
+     */
+    failHook(callId, e) {
+        this.hookError ??= e;
+        this.complete(callId, false, e, false);
+    }
+    /** `vm_dump` in this sandbox's own module. */
+    dumpHere(names, handles, states, sourceRefs = true) {
+        const x = this.x;
+        x.vm_set_dump_source_refs?.(this.vm, sourceRefs ? 1 : 0);
+        if (!x.vm_dump)
+            throw new SandboxError("misuse", "the djs-wasm module has no dump (vm_dump): build it with the `dump` feature, or pass `dumpModule`");
+        const host = this.globalNames;
+        const text = [
+            [...host].join(","),
+            names.join(","),
+            this.fnNames.join("\t"),
+            handles.map(([name, h]) => `${h}:${name}`).join("\t"),
+            [...this.namespaces].map(([name, h]) => `${h}:${name}`).join("\t"),
+            states.map(([id, json]) => `${id}:${textEncoder.encode(json).length}`).join("\t"),
+            states.map(([, json]) => json).join(""),
+        ].join("\n");
+        const r = this.guard(() => x.vm_dump(this.vm, this.stageText(text)));
+        if (r !== 0)
+            throw new SandboxError("misuse", `cannot dump:\n${outText(x)}`);
+        return outText(x);
+    }
+    /**
+     * Loads a dump (the text of `dump()`): runs it as a Script (D2890), so its bindings
+     * become globals of this sandbox. A dump is code: load only dumps you trust, into a
+     * fresh sandbox. Not recorded in a journal. Returns the open host calls the dump
+     * recreated (its open calls name this sandbox's host functions); `Sandbox.resume`
+     * continues a dumped run. The dumper is not needed.
+     */
+    load(dump) {
+        const { calls, handles } = this.loadDump(dump);
+        this.guard(() => {
+            for (const h of handles.values())
+                this.x.vm_handle_free(this.vm, h);
+        });
+        return { calls };
+    }
+    /** Loads a dump: the open calls it recreated and the handles it named (the caller frees them). */
+    loadDump(dump) {
+        if (this.active !== null)
+            throw new SandboxError("misuse", "a run is in progress");
+        const plain = plainDump(dump);
+        if (!plain)
+            throw new SandboxError("misuse", 'cannot load the dump: not a djs dump (no "djs-dump"; header)');
+        return this.loadPlain(dump, plain.typescript);
+    }
+    /**
+     * Loads a plain dump (D2830): runs it as a Script with the hooks in `$djs` (D2890), to
+     * its first stop that is not a sync host call (idle, or done); the hooks are served only
+     * meanwhile. Then the sandbox deletes `$djs` and the dump's `$dump` (D2916).
+     * `$djs.resume(id, name, args, state)` opens the dump's call `id` of host function
+     * `name` again under its id (`vm_open_call`): one of the calls returned, with its state;
+     * `$djs.seed(lo, hi, next)` sets `Math.random`'s state and, once the dump has loaded,
+     * the id of the next call (D2897). Other sync host functions are called
+     * (they must return synchronously); async calls the Script makes are new calls, which
+     * the run that follows reports. The Script's completion value, when a promise, is the
+     * handle "run". The dumper is not needed: a plain dump is code.
+     */
+    loadPlain(dump, typescript) {
+        const x = this.x;
+        const vm = this.vm;
+        if (!x.vm_open_call || !x.vm_dump_runtime) {
+            throw new SandboxError("misuse", "the djs-wasm module cannot load plain dumps (no vm_open_call or vm_dump_runtime): rebuild it");
+        }
+        const dumpRuntime = x.vm_dump_runtime;
+        const calls = [];
+        this.guard(() => {
+            // `$djs`: the dump runtime's helpers the dump names (D2903, 0215) with the hooks added.
+            const hooks = this.check(dumpRuntime(vm, this.stageText(dumpRuntimeFor(dump))), "memory");
+            for (const [name, id] of [["resume", HOOK_RESUME], ["seed", HOOK_SEED], ["source", HOOK_SOURCE], ["host", HOOK_HOST]]) {
+                const f = this.check(x.vm_new_host_function(vm, id, this.stageText(name)), "memory");
+                this.defineOn(hooks, name, f);
+                x.vm_handle_free(vm, f);
+            }
+            const g = x.vm_global(vm);
+            this.defineOn(g, PLAIN_HOOKS, hooks);
+            x.vm_handle_free(vm, g);
+            x.vm_handle_free(vm, hooks);
+        });
+        let st = STATUS_DONE;
+        this.hookError = undefined;
+        // `$djs.seed`'s next call id: the counter goes on from the dumped VM's (D2897).
+        let next;
+        this.enter(dump, {}, true, "dump.js", typescript);
+        const slice = this.opts.fuelSlice ?? 1_000_000;
+        const maxFuel = this.opts.maxFuel ?? Infinity;
+        let used = 0;
+        for (;;) {
+            st = this.guard(() => {
+                this.setClock();
+                return x.vm_run(vm, slice);
+            });
+            used += x.vm_fuel_used ? x.vm_fuel_used(vm) : st === STATUS_OUT_OF_FUEL ? slice : 0;
+            if (used >= maxFuel) {
+                this.guard(() => x.vm_abort(vm));
+                throw new SandboxError("fuel", `out of fuel after ${used} units while loading the dump`);
+            }
+            if (st === STATUS_OUT_OF_FUEL)
+                continue;
+            if (st !== STATUS_HOST_CALL)
+                break;
+            const { callId, fnId, args } = this.guard(() => this.readCall(x.vm_host_call(vm)));
+            if (fnId === HOOK_RESUME) {
+                const [id, name, callArgs, state] = args;
+                const f = typeof name === "string" ? this.fnNames.indexOf(name) + 1 : 0;
+                if (f === 0) {
+                    this.failHook(callId, new Error(`resume: unknown host function ${String(name)}`));
+                    continue;
+                }
+                if (this.guard(() => x.vm_open_call(vm, callId, f)) !== 0) {
+                    // (Out of memory may come after the parked call returned: then this is a no-op.)
+                    this.complete(callId, false, new Error(outText(x)), false);
+                    continue;
+                }
+                const call = { id: id, fn: name, args: Array.isArray(callArgs) ? callArgs : [] };
+                if (state !== undefined)
+                    call.state = state;
+                calls.push(call);
+                continue;
+            }
+            if (fnId === HOOK_SOURCE) {
+                this.serveSource(callId, args);
+                continue;
+            }
+            if (fnId === HOOK_HOST) {
+                this.serveHost(callId, args);
+                continue;
+            }
+            let ok = true;
+            let result;
+            if (fnId === HOOK_SEED) {
+                // `$djs.seed(lo, hi[, next])`, or `$djs.seed(next)` (D2837).
+                const [lo, hi, n] = args;
+                if (hi === undefined && typeof lo === "number")
+                    next = lo;
+                else if (typeof lo === "number" && typeof hi === "number") {
+                    // (A state that ran, which the next dump writes again: `vm_restore_math_random`.)
+                    this.guard(() => (x.vm_restore_math_random ?? x.vm_set_math_random_seed)(vm, lo >>> 0, hi >>> 0));
+                    if (typeof n === "number")
+                        next = n;
+                }
+                else
+                    [ok, result] = [false, new TypeError("seed: not two int32 halves")];
+            }
+            else {
+                try {
+                    result = this.invoke(fnId, args);
+                    if (result instanceof Promise)
+                        throw new TypeError(`host function ${this.fnNames[fnId - 1]} returned a promise while a dump loads`);
+                }
+                catch (e) {
+                    if (e instanceof SandboxError && e.kind === "trap")
+                        throw e;
+                    [ok, result] = [false, e];
+                }
+            }
+            this.complete(callId, ok, result, false);
+        }
+        // (Without `next`: one past the highest reopened call, D2837.)
+        if (x.vm_set_next_call_id) {
+            const last = Math.max(0, ...calls.map((c) => c.id));
+            this.guard(() => x.vm_set_next_call_id(vm, Math.max(next ?? 0, last + 1)));
+        }
+        // Set by hooks that ran meanwhile, which the narrowing of `this.hookError` cannot see.
+        const hookError = this.hookError;
+        this.hookError = undefined;
+        return this.guard(() => {
+            if (st === STATUS_THREW || st === STATUS_HOST_OUT_OF_MEMORY) {
+                const h = x.vm_result(vm);
+                const why = st === STATUS_THREW ? `the dump threw: ${this.display(h)}` : "out of host memory";
+                x.vm_handle_free(vm, h);
+                throw new SandboxError("misuse", `cannot load the dump: ${why}`);
+            }
+            if (hookError !== undefined)
+                throw new SandboxError("misuse", `cannot load the dump: ${hookError.message}`);
+            // The completion value: vm_result once done, else (idle) the entry call's outcome.
+            const h = st === STATUS_DONE ? x.vm_result(vm) : x.vm_outcome(vm);
+            const handles = new Map();
+            const ps = h === 0 ? 0 : x.vm_promise_state(vm, h);
+            if (ps >= 2)
+                x.vm_handle_free(vm, outWords(x, 1)[0]);
+            if (ps !== 0)
+                handles.set("run", h);
+            else if (h !== 0)
+                x.vm_handle_free(vm, h);
+            // The load is over: the host deletes the dump's globals (D2916), by running JS (the
+            // module has no delete of its own).
+            const drop = textEncoder.encode("delete globalThis.$djs; delete globalThis.$dump");
+            this.stage(drop);
+            const f = x.vm_compile_file(vm, 0, 0, 0, drop.length);
+            if (f !== 0) {
+                this.stage(new Uint8Array(0));
+                if (x.vm_call(vm, f, 0, 0) === 0)
+                    x.vm_run(vm, slice);
+                x.vm_handle_free(vm, f);
+            }
+            return { calls, handles };
+        });
+    }
+    /**
+     * Like `run`, but awaits host functions that return promises: a sync one keeps the VM
+     * parked meanwhile, async ones run concurrently while the script goes on.
+     */
+    async runAsync(code, params = {}, opts = {}) {
+        this.beginJournal(code, params, opts);
+        this.enter(code, params);
+        try {
+            const it = this.auto(true);
+            let r = it.next();
+            while (!r.done)
+                r = it.next(await r.value);
+            return r.value;
+        }
+        catch (e) {
+            this.abandon(e);
+            throw e;
+        }
+        finally {
+            this.endRun();
+            this.journal = null;
+        }
+    }
+    /**
+     * Replays a recorded run (D1730): runs the journal's code and parameters, answers every
+     * host call from the journal instead of calling the host functions (console output
+     * still goes to the console), delivers the async results in the recorded order with
+     * their clocks, and checks the calls the script makes and the canonical hashes at the
+     * start, at every recorded idle point and at the end. The sandbox must be deterministic
+     * and in the state the recording one was in (a fresh one created the same way, given the
+     * same runs before); the fuel slice may differ.
+     * Returns the run's result; a mismatch is a `diverged` SandboxError.
+     */
+    async replay(journal) {
+        const head = journal[0];
+        if (head?.type !== "run")
+            throw new SandboxError("misuse", "a journal starts with a run entry");
+        if (this.opts.deterministic === undefined)
+            throw new SandboxError("misuse", "replay needs a deterministic sandbox");
+        const j = new Journal("replay", journal);
+        j.expect(head.engine === this.buildHash(), () => `engine ${this.buildHash()}, the journal was made by ${head.engine}`);
+        j.expect(head.hash === this.canonicalHash(), () => "the sandbox's state before the run differs from the recording's");
+        j.next = 1;
+        this.enter(head.code, head.params);
+        this.journal = j;
+        try {
+            const it = this.auto(true);
+            let r = it.next();
+            while (!r.done)
+                r = it.next(await r.value);
+            return r.value;
+        }
+        catch (e) {
+            this.abandon(e);
+            throw e;
+        }
+        finally {
+            this.endRun();
+            this.journal = null;
+        }
+    }
+    /** The VM's canonical hash (D1730) as 16 hex digits: its state, independent of collections. */
+    canonicalHash() {
+        return this.guard(() => {
+            if (this.x.vm_canonical_hash(this.vm) !== 0)
+                throw new SandboxError("memory", "no memory for the canonical hash");
+            const [lo, hi] = outWords(this.x, 2);
+            return hi.toString(16).padStart(8, "0") + lo.toString(16).padStart(8, "0");
+        });
+    }
+    buildHash() {
+        return (this.x.djs_build_hash() >>> 0).toString(16).padStart(8, "0");
+    }
+    /** Starts recording a run into `opts.journal`, if given. */
+    beginJournal(code, params, opts) {
+        if (this.active !== null)
+            throw new SandboxError("misuse", "a run is in progress");
+        this.journal = null;
+        if (opts.journal === undefined)
+            return;
+        if (this.opts.deterministic === undefined)
+            throw new SandboxError("misuse", "recording needs a deterministic sandbox");
+        opts.journal.push({ type: "run", engine: this.buildHash(), code, params, hash: this.canonicalHash() });
+        this.journal = new Journal("record", opts.journal);
+    }
+    /**
+     * After a failed run: drops the VM's call if it is still in one (out of fuel, or a host
+     * side error escaped the loop), so the next run starts clean. Not after a trap: the
+     * instance is gone then.
+     */
+    abandon(e) {
+        if (this.dead === null && !(e instanceof SandboxError && e.kind === "trap")) {
+            this.guard(() => this.x.vm_abort(this.vm));
+        }
+    }
+    /**
+     * The VM's arena: a view into wasm memory, valid until the next call into the sandbox
+     * (the arena may move when it grows). For inspecting the heap with `LAYOUT` (the docs'
+     * live examples walk it cell by cell).
+     */
+    heapView() {
+        this.alive();
+        return this.arena();
+    }
+    /**
+     * Where the run waits on open host call `id` (D3054): the `await` (or `yield`) of the
+     * innermost suspended activation waiting on the call, directly or through promise
+     * combinators. `file` is the name the code was compiled as: the run's `filename` for
+     * the code it started with, the dump loader's name (`dump.js`) for code a dump carried
+     * (a run continued from a dump runs the dump's text). Undefined when the call is not
+     * open or nothing waits on it at a known position, and in modules without the dumper
+     * (the `dump` feature), where it is not built.
+     */
+    callSite(id) {
+        this.alive();
+        const x = this.x;
+        if (!x.vm_call_site)
+            return undefined;
+        const n = this.guard(() => x.vm_call_site(this.vm, id));
+        if (n === 0)
+            return undefined;
+        const m = /^(\d+):(\d+):(.*)$/s.exec(outText(x));
+        return m ? { file: m[3], line: Number(m[1]), column: Number(m[2]) } : undefined;
+    }
+    /** Collects garbage now. False if the heap could not reserve the to-space. */
+    collect() {
+        return this.guard(() => this.x.vm_collect(this.vm) === 0);
+    }
+    /** The arena's current size in bytes. */
+    get heapSize() {
+        this.alive();
+        return this.x.vm_arena_len(this.vm);
+    }
+    /** Releases the VM. The sandbox cannot be used afterwards. A task in progress ends (`misuse`). */
+    dispose() {
+        this.cancelTask?.();
+        this.active = null;
+        if (this.dead === null) {
+            this.x.vm_free(this.vm);
+            this.dead = "disposed";
+        }
+    }
+    /** Panics inside the module on purpose (tests the trap path). */
+    debugTrap() {
+        this.guard(() => this.x.djs_debug_panic());
+    }
+    // ---- internals ---------------------------------------------------------------------
+    alive() {
+        if (this.dead !== null)
+            throw new SandboxError("misuse", `sandbox is unusable: ${this.dead}`);
+    }
+    /** Runs `f` and turns a wasm trap into a SandboxError; the sandbox is dead afterwards. */
+    guard(f) {
+        this.alive();
+        try {
+            return f();
+        }
+        catch (e) {
+            if (e instanceof WebAssembly.RuntimeError) {
+                const msg = trapText(this.x, e);
+                this.dead = `trapped (${msg})`;
+                throw new SandboxError("trap", `djs-wasm trapped: ${msg}`);
+            }
+            throw e;
+        }
+    }
+    check(h, kind) {
+        if (h === 0)
+            throw new SandboxError(kind, outText(this.x) || "out of memory");
+        return h;
+    }
+    /** Copies bytes into the staging buffer. */
+    stage(bytes) {
+        const at = this.x.djs_staging(bytes.length);
+        new Uint8Array(this.x.memory.buffer).set(bytes, at);
+    }
+    stageText(s) {
+        const b = textEncoder.encode(s);
+        this.stage(b);
+        return b.length;
+    }
+    hostFunction(name, f, async = false) {
+        let id = this.fnNames.indexOf(name) + 1;
+        if (id === 0) {
+            this.fnNames.push(name);
+            id = this.fnNames.length;
+        }
+        if (typeof f === "function") {
+            this.fns.set(id, f);
+            this.hooks.delete(id);
+        }
+        else {
+            if (!async || typeof f?.call !== "function")
+                throw new SandboxError("misuse", `host function ${name}: not a function or { call, save, resume }`);
+            this.fns.set(id, f.call);
+            this.hooks.set(id, f);
+        }
+        // One function object per identity (D2970): a dump's `$djs.host(name)` gets the one
+        // the sandbox bound. A redefinition makes a new one only if its kind changes.
+        const old = this.fnHandles.get(id);
+        if (old !== undefined && this.fnAsync.get(id) === async)
+            return old;
+        const shortName = name.slice(name.lastIndexOf(".") + 1);
+        const len = this.stageText(shortName);
+        const h = this.check(async ? this.x.vm_new_async_host_function(this.vm, id, len) : this.x.vm_new_host_function(this.vm, id, len), "memory");
+        if (old !== undefined)
+            this.x.vm_handle_free(this.vm, old);
+        this.fnHandles.set(id, h);
+        this.fnAsync.set(id, async);
+        return h;
+    }
+    defineOn(obj, name, value) {
+        if (this.x.vm_define(this.vm, obj, this.stageText(name), value) !== 0) {
+            throw new SandboxError("memory", `cannot define ${name}`);
+        }
+    }
+    /** A handle for a host value (0 for undefined). */
+    toHandle(v) {
+        if (v === undefined)
+            return 0;
+        const bytes = encode(v);
+        if (typeof v === "string" && v.length >= IN_PLACE_MIN) {
+            const h = stringInPlace(this.x, this.vm, v, bytes);
+            if (h !== 0)
+                return h;
+        }
+        this.stage(bytes);
+        return this.check(this.x.vm_decode_wire(this.vm, bytes.length), "memory");
+    }
+    arena() {
+        const x = this.x;
+        return new Uint8Array(x.memory.buffer, x.vm_arena_ptr(this.vm), x.vm_arena_len(this.vm));
+    }
+    read(lo, hi) {
+        return readValue(this.arena(), [lo, hi], { atomCache: this.atomCache });
+    }
+    readHandle(h) {
+        this.x.vm_handle_bits(this.vm, h);
+        const w = outWords(this.x, 2);
+        return this.read(w[0], w[1]);
+    }
+    display(h) {
+        const n = this.x.vm_display(this.vm, h);
+        return textDecoder.decode(new Uint8Array(this.x.memory.buffer, this.x.djs_out_ptr(), n));
+    }
+    /** Compiles `code` and starts the call; returns nothing (the VM holds the call). */
+    enter(code, params, script = false, filename, typescript = false) {
+        if (this.active !== null)
+            throw new SandboxError("misuse", "a run is in progress");
+        this.guard(() => {
+            const x = this.x;
+            const vm = this.vm;
+            // A body's parameters: the run's data, then the sandbox's bindings (D2972), whose
+            // objects the sandbox owns.
+            const bound = script ? [] : Object.entries(this.opts.bindings ?? {});
+            const boundHandles = bound.map(([p, identity]) => {
+                if (Object.hasOwn(params, p))
+                    throw new SandboxError("misuse", `parameter ${p} is both a run parameter and a binding`);
+                const h = this.hostValue(identity);
+                if (h === undefined)
+                    throw new SandboxError("misuse", `binding ${p}: no host function or namespace ${identity}`);
+                return h;
+            });
+            const names = [...Object.keys(params), ...bound.map(([p]) => p)];
+            const handles = Object.values(params).map((v) => this.toHandle(v));
+            const name = textEncoder.encode(filename ?? "");
+            const head = textEncoder.encode(names.join("\n"));
+            const src = textEncoder.encode(code);
+            const all = new Uint8Array(name.length + head.length + src.length);
+            all.set(name);
+            all.set(head, name.length);
+            all.set(src, name.length + head.length);
+            this.stage(all);
+            const o = this.opts;
+            const goal = (o.debugger ? 16 : 0) |
+                (script
+                    ? typescript ? 2 : 0
+                    : 1 |
+                        (o.typescript ? 2 : 0) |
+                        (o.experimentalDecorators || o.emitDecoratorMetadata ? 4 : 0) |
+                        (o.emitDecoratorMetadata ? 8 : 0));
+            const f = x.vm_compile_file(vm, goal, name.length, head.length, src.length);
+            if (f !== 0 && !script)
+                rememberScript(filename || "sandbox.js", code);
+            if (f === 0) {
+                const msg = outText(x);
+                for (const h of handles)
+                    if (h !== 0)
+                        x.vm_handle_free(vm, h);
+                throw new SandboxError(msg.startsWith("SyntaxError") ? "syntax" : "memory", msg);
+            }
+            const argv = [...handles, ...boundHandles];
+            const args = new Uint8Array(4 * argv.length);
+            const dv = new DataView(args.buffer);
+            argv.forEach((h, i) => dv.setUint32(4 * i, h, true));
+            this.stage(args);
+            const r = x.vm_call(vm, f, 0, argv.length);
+            x.vm_handle_free(vm, f);
+            for (const h of handles)
+                if (h !== 0)
+                    x.vm_handle_free(vm, h);
+            if (r !== 0)
+                throw new SandboxError("misuse", "a call is already in progress");
+        });
+    }
+    /**
+     * The run loop to the next idle point or the end, as a generator: yields a promise when
+     * the host must wait for a sync host function (only when `async`), returns the result,
+     * or `IDLE` when only async host calls are left (they are in `run.open`).
+     */
+    *drive(async, run) {
+        const x = this.x;
+        const vm = this.vm;
+        const slice = this.opts.fuelSlice ?? 1_000_000;
+        const maxFuel = this.opts.maxFuel ?? Infinity;
+        const j = this.journal;
+        for (;;) {
+            run.beforeSlice?.();
+            const st = this.guard(() => {
+                this.setClock();
+                return x.vm_run(vm, slice);
+            });
+            // Counted across sync host calls too, which end a slice early (D2653, D2702).
+            run.used += x.vm_fuel_used ? x.vm_fuel_used(vm) : st === STATUS_OUT_OF_FUEL ? slice : 0;
+            for (const callId of this.newHostCalls()) {
+                const { fnId, args } = this.callInfo(callId);
+                const call = { id: callId, fn: this.fnNames[fnId - 1], args };
+                run.open.set(callId, call);
+                if (j)
+                    j.issued++;
+                run.onCall?.(call, fnId);
+            }
+            if (st === STATUS_DONE || st === STATUS_THREW) {
+                const outcome = this.guard(() => {
+                    let h = x.vm_result(vm);
+                    if (run.result !== 0) {
+                        // A resumed run's result promise: its entry call was the dump's Script.
+                        x.vm_handle_free(vm, h);
+                        h = run.result;
+                        run.result = 0;
+                    }
+                    let threw = st === STATUS_THREW;
+                    // A promise result (an async body): its outcome.
+                    const ps = x.vm_promise_state(vm, h);
+                    if (ps === 1) {
+                        x.vm_handle_free(vm, h);
+                        throw new SandboxError("threw", "the result is a promise that never settles");
+                    }
+                    if (ps >= 2) {
+                        const r = outWords(x, 1)[0];
+                        x.vm_handle_free(vm, h);
+                        h = r;
+                        threw = ps === 3;
+                    }
+                    const value = this.readHandle(h);
+                    const message = threw ? this.display(h) : "";
+                    x.vm_handle_free(vm, h);
+                    return { value, message, threw };
+                });
+                const { value, message, threw } = outcome;
+                if (j) {
+                    const end = { type: "end", ok: !threw, value: threw ? message : value };
+                    j.finish(end, this.canonicalHash());
+                }
+                if (threw)
+                    throw new SandboxError("threw", message, value);
+                this.checkRejections();
+                return value;
+            }
+            if (st === STATUS_OUT_OF_FUEL) {
+                if (run.used >= maxFuel) {
+                    // `run` abandons the call (vm_abort), so the sandbox stays usable.
+                    throw new SandboxError("fuel", `out of fuel after ${run.used} units`);
+                }
+                continue;
+            }
+            if (st === STATUS_HOST_OUT_OF_MEMORY) {
+                // The host (wasm memory) could not back the heap below its cap: not a script
+                // error. The VM abandoned the call and is usable again (D1690).
+                throw new SandboxError("memory", "out of host memory");
+            }
+            if (st === STATUS_IDLE) {
+                this.checkRejections();
+                return IDLE;
+            }
+            if (st !== STATUS_HOST_CALL)
+                return undefined;
+            if (run.used >= maxFuel)
+                throw new SandboxError("fuel", `out of fuel after ${run.used} units`);
+            const { callId, fnId, args } = this.guard(() => {
+                const argc = x.vm_host_call(vm);
+                return this.readCall(argc);
+            });
+            let ok = true;
+            let result;
+            const fn = this.fnNames[fnId - 1];
+            const journaled = j !== null && !fn?.startsWith("console.");
+            try {
+                if (journaled && j.mode === "replay") {
+                    j.issued++;
+                    const e = j.take("sync");
+                    j.expectCall(e.fn, e.args, fn, args);
+                    if (!e.ok)
+                        throw errorFromJson(e.value);
+                    result = e.value;
+                }
+                else {
+                    result = this.invoke(fnId, args);
+                    if (result instanceof Promise) {
+                        if (!async)
+                            throw new TypeError(`host function ${fn} returned a promise; use runAsync`);
+                        result = yield result;
+                    }
+                }
+            }
+            catch (e) {
+                if (e instanceof SandboxError && (e.kind === "trap" || e.kind === "diverged"))
+                    throw e;
+                ok = false;
+                result = e;
+            }
+            if (journaled && j.mode === "record") {
+                j.issued++;
+                j.push({ type: "sync", fn, args, ok, value: errorJson(ok, result) });
+            }
+            this.complete(callId, ok, result, false);
+        }
+    }
+    /**
+     * The unhandled rejections collected so far (`unhandledRejections: "collect"`), as host
+     * values; forgets them.
+     */
+    takeUnhandledRejections() {
+        return this.rejections.splice(0);
+    }
+    /** Reports the VM's unhandled rejections per `opts.unhandledRejections` (D1423). */
+    checkRejections() {
+        const reasons = this.guard(() => {
+            const x = this.x;
+            const n = x.vm_take_unhandled_rejections(this.vm);
+            const handles = outWords(x, n);
+            return handles.map((h) => {
+                const value = this.readHandle(h);
+                const message = this.display(h);
+                x.vm_handle_free(this.vm, h);
+                return { value, message };
+            });
+        });
+        if (reasons.length === 0)
+            return;
+        const mode = this.opts.unhandledRejections ?? "warn";
+        if (mode === "throw") {
+            const first = reasons[0];
+            throw new SandboxError("threw", `Possibly unhandled promise rejection: ${first.message}`, first.value);
+        }
+        for (const r of reasons) {
+            if (mode === "collect")
+                this.rejections.push(r.value);
+            else
+                this.cons.warn("Possibly unhandled promise rejection:", r.message);
+        }
+    }
+    /**
+     * Passes the host clock and time zone to the VM (before every slice). Not in
+     * deterministic mode: there the clock moves only with async results (`complete`).
+     */
+    setClock() {
+        if (this.clock !== undefined)
+            return;
+        const { now, timeZoneOffset } = this.opts;
+        const ms = typeof now === "number" ? now : (now ?? Date.now)();
+        this.x.vm_set_now(this.vm, ms);
+        this.x.vm_set_time_zone_offset(this.vm, timeZoneOffset ?? -new Date(ms).getTimezoneOffset());
+    }
+    /** Calls host function `fnId` with arguments read from the VM; `call` is `this` for hooks. */
+    invoke(fnId, args, call) {
+        const f = this.fns.get(fnId);
+        if (f === undefined)
+            throw new TypeError(`unknown host function ${fnId}`);
+        if (this.hooks.has(fnId))
+            return f.apply(call ?? newCall(fnId, this.fnNames[fnId - 1], args).call, args);
+        const isConsole = this.fnNames[fnId - 1]?.startsWith("console.");
+        return f(...(isConsole ? args.map(consoleArg) : args));
+    }
+    /** The async host calls made since the last check (`vm_new_host_calls`). */
+    newHostCalls() {
+        return this.guard(() => {
+            const n = this.x.vm_new_host_calls(this.vm);
+            return outWords(this.x, n);
+        });
+    }
+    /** The function and arguments of pending host call `callId`. */
+    callInfo(callId) {
+        return this.guard(() => this.readCall(this.x.vm_host_call_info(this.vm, callId)));
+    }
+    /** Reads `[call_id, fn_id, this, args...]` from the out buffer. */
+    readCall(argc) {
+        const x = this.x;
+        const w = outWords(x, 4 + 2 * argc);
+        const args = [];
+        for (let i = 0; i < argc; i++)
+            args.push(this.read(w[4 + 2 * i], w[5 + 2 * i]));
+        return { callId: w[0], fnId: w[1], args };
+    }
+    /**
+     * Passes a host call's outcome back: a value (through the wire format), or an error
+     * thrown at the call (sync) or rejecting its promise (async), as an Error of the same
+     * kind with the host error's message. A value the wire format cannot carry becomes
+     * such an error too.
+     */
+    complete(callId, ok, value, async, at) {
+        const x = this.x;
+        const vm = this.vm;
+        let h = 0;
+        if (ok) {
+            try {
+                h = this.guard(() => this.toHandle(value));
+            }
+            catch (e) {
+                if (e instanceof SandboxError && e.kind === "trap")
+                    throw e;
+                ok = false;
+                value = e;
+            }
+        }
+        if (!ok) {
+            const e = value;
+            h = this.guard(() => {
+                const msg = this.stageText(e instanceof Error ? e.message : String(e));
+                const kind = e instanceof TypeError ? 1 : e instanceof RangeError ? 2 : 0;
+                return this.check(x.vm_new_error(vm, kind, msg), "memory");
+            });
+        }
+        return this.guard(() => {
+            let clock;
+            if (async && this.clock !== undefined) {
+                // Deterministic mode: the result's time (a replay's: the recorded one), applied
+                // when the VM takes the result (D1670).
+                const { now } = this.opts;
+                this.clock = at ?? Math.max(this.clock, typeof now === "number" ? now : (now ?? Date.now)());
+                clock = this.clock;
+                x.vm_resolve_host_call_at(vm, callId, ok ? 1 : 0, h, this.clock);
+            }
+            else {
+                x.vm_resolve_host_call(vm, callId, ok ? 1 : 0, h);
+            }
+            if (h !== 0)
+                x.vm_handle_free(vm, h);
+            return clock;
+        });
+    }
+}
+const WEAK_REF_MODES = { collected: 0, strong: 1, absent: 2 };
+/** A call's hook view (`this` of `call`, the argument of `save` and `resume`) and its abort. */
+function newCall(id, fn, args, state) {
+    const abort = new AbortController();
+    return { call: { id, fn, args, startedAt: Date.now(), state, signal: abort.signal }, abort };
+}
+/** A call's state as the JSON text a dump carries (D2770). */
+function stateJson(id, state) {
+    let json;
+    try {
+        json = JSON.stringify(state);
+    }
+    catch (e) {
+        throw new SandboxError("misuse", `the state of call ${id} is not JSON data: ${String(e)}`);
+    }
+    if (json === undefined)
+        throw new SandboxError("misuse", `the state of call ${id} is not JSON data`);
+    return json;
+}
+/** The journal of a run being recorded or replayed (D1730). */
+class Journal {
+    /** Replay: the index of the next entry. */
+    next = 0;
+    /** Async results delivered, non-console host calls made. */
+    delivered = 0;
+    issued = 0;
+    mode;
+    entries;
+    constructor(mode, entries) {
+        this.mode = mode;
+        this.entries = entries;
+    }
+    push(e) {
+        this.entries.push(e);
+    }
+    expect(ok, why) {
+        if (!ok)
+            throw new SandboxError("diverged", `replay diverged: ${why()}`);
+    }
+    /** Replay: takes the next entry, which must be of `type`. */
+    take(type) {
+        const e = this.entries[this.next];
+        this.expect(e?.type === type, () => `the script needs ${type === "sync" ? "a host call" : "a result"} here, the journal has ${e ? `a ${e.type} entry` : "nothing more"} (entry ${this.next})`);
+        this.next++;
+        return e;
+    }
+    expectCall(fn, args, gotFn, gotArgs) {
+        this.expect(fn === gotFn && sameValue(args, gotArgs), () => `the script called ${gotFn}(${stable(gotArgs)}), the recording ${fn}(${stable(args)})`);
+    }
+    /** Replay at an idle point: the recorded checks for this many delivered results. */
+    checkIdle(hash) {
+        for (let e = this.entries[this.next]; e?.type === "check"; e = this.entries[this.next]) {
+            this.expect(e.delivered === this.delivered, () => `the recording was idle after ${e.delivered} results, the replay after ${this.delivered}`);
+            this.expect(e.issued === this.issued, () => `${this.issued} host calls made, the recording made ${e.issued} (after ${e.delivered} results)`);
+            this.expect(e.hash === hash, () => `the state after ${e.delivered} results differs`);
+            this.next++;
+        }
+    }
+    /** At the end: records or checks the `end` entry. */
+    finish(end, hash) {
+        const full = { ...end, delivered: this.delivered, issued: this.issued, hash };
+        if (this.mode === "record") {
+            this.push(full);
+            return;
+        }
+        while (this.entries[this.next]?.type === "check")
+            this.next++;
+        const e = this.take("end");
+        this.expect(e.ok === full.ok && sameValue(e.value, full.value), () => `the run ended ${full.ok ? "with" : "throwing"} ${stable(full.value)}, the recording ${e.ok ? "with" : "throwing"} ${stable(e.value)}`);
+        this.expect(e.issued === full.issued && e.delivered === full.delivered, () => "a different number of host calls or results");
+        this.expect(e.hash === full.hash, () => "the final state differs");
+    }
+}
+/** A host value as a journal records it: errors as `{ name, message }`. */
+function errorJson(ok, v) {
+    if (ok)
+        return v;
+    return v instanceof Error ? { name: v.name, message: v.message } : { name: "Error", message: String(v) };
+}
+/** The host error a journal entry stands for, of the same kind. */
+function errorFromJson(v) {
+    const { name, message } = (v ?? {});
+    const E = name === "TypeError" ? TypeError : name === "RangeError" ? RangeError : Error;
+    return new E(message ?? "");
+}
+/** A stable text form of a host value, for comparing and messages. */
+function stable(v) {
+    return JSON.stringify(v, (_k, x) => typeof x === "bigint" ? `${x}n` : x === undefined ? "<undefined>" : x instanceof Uint8Array ? Array.from(x) : x) ?? "<undefined>";
+}
+function sameValue(a, b) {
+    return stable(a) === stable(b);
+}
+/** A 64-bit seed as the two u32 words `vm_set_random_seed` takes. */
+function seedWords(seed) {
+    const s = BigInt.asUintN(64, BigInt(seed));
+    return [Number(s & 0xffffffffn), Number(s >> 32n)];
+}
+/** A seed from the host's entropy (never 0, which would mean the VM's fixed default). */
+function entropy() {
+    const words = new Uint32Array(2);
+    globalThis.crypto.getRandomValues(words);
+    return [words[0], words[1] | 1];
+}
+/** Console arguments: values without a host form are shown by their class. */
+function consoleArg(a) {
+    return a instanceof Opaque ? `[${a.className ?? a.type}]` : a;
+}
+/** The first `n` u32 (LE) words of the out buffer, which need not be aligned. */
+function outWords(x, n) {
+    const dv = new DataView(x.memory.buffer, x.djs_out_ptr(), 4 * n);
+    return Array.from({ length: n }, (_, i) => dv.getUint32(4 * i, true));
+}
+function outText(x) {
+    return textDecoder.decode(new Uint8Array(x.memory.buffer, x.djs_out_ptr(), x.djs_out_len()));
+}