@earendil-works/djs 0.0.1 → 0.1.0

package/dist/sandbox.d.ts

@@ -0,0 +1,756 @@
+/** A host function callable from the sandbox. Arguments and the result are host values. */
+export type HostFunction = (...args: unknown[]) => unknown;
+/**
+ * An async host call as an `AsyncHostFunction`'s hooks see it (D2771): what the script
+ * called, and the host's state of the call, which a dump keeps.
+ */
+export interface HostCall<S = unknown> {
+    /** The VM's call id; a dump keeps it. */
+    readonly id: number;
+    /** The host function's name, as given in `asyncFunctions`. */
+    readonly fn: string;
+    readonly args: unknown[];
+    /** When this sandbox started (or, after a load, resumed) the call: ms, the host's `Date.now()`. */
+    readonly startedAt: number;
+    /**
+     * The host's state of the call: JSON data that a dump writes with the call (as
+     * `save`'s default) and a load gives back to `resume`. Set it at any time; a resumed
+     * call starts with the state it was dumped with.
+     */
+    state: S | undefined;
+    /**
+     * Aborted when this sandbox stops waiting for the call: the task was suspended into a
+     * dump (the call continues from there) or the sandbox was disposed.
+     */
+    readonly signal: AbortSignal;
+}
+/**
+ * An async host function with hooks for continuation dumps (D2771): a task the sandbox
+ * drives (`start`, `Sandbox.resume`) can be suspended while calls of it are open, and
+ * continued from the dump in another sandbox or process. `S` is the type of the calls'
+ * state.
+ */
+export interface AsyncHostFunction<S = unknown> {
+    /** Starts the call: its result, or a promise of it. `this` is the call. */
+    call(this: HostCall<S>, ...args: unknown[]): unknown;
+    /** The call's state when a dump is taken: JSON data. Default: `call.state`. */
+    save?(call: HostCall<S>): S | undefined;
+    /**
+     * Continues the call after a load, from the `state` it was dumped with: its result, or
+     * a promise of it. Without `resume` the call is made again (`call`); a plain function
+     * (no hooks) is not continued: its call rejects.
+     */
+    resume?(state: S, call: HostCall<S>): unknown;
+}
+export interface ConsoleLike {
+    log(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}
+export interface SandboxOptions {
+    /** The compiled djs-wasm module; default: `loadModule()`. */
+    module?: WebAssembly.Module;
+    /**
+     * The dump module (`djs-dump.wasm`: djs-wasm with the `dump` feature) for a `module`
+     * without the dumper (packaging B, D2635): `dump`, `Run.dump` and a task's `suspend`
+     * and `checkpoint` copy the VM's image to an instance of it. Not needed when `module`
+     * has the dumper itself, nor for loading (`load`, `loadRun`, `Sandbox.resume`): a dump
+     * is a Script.
+     */
+    dumpModule?: WebAssembly.Module;
+    /** Heap cap in bytes; default: the engine's (4 GiB). */
+    memoryLimit?: number;
+    /** Fuel per `vm_run` call: how often the host gets control back. Default 1,000,000. */
+    fuelSlice?: number;
+    /**
+     * Fuel budget of one `run`, after which it fails with "out of fuel" (the call is
+     * abandoned; the sandbox stays usable). Default: none.
+     */
+    maxFuel?: number;
+    /**
+     * Host functions, by identity (D2970): any string (`tools.read`, `@sdk/our-stuff#myTool`),
+     * which calls, journals and dumps name the function by. A call parks the VM until the
+     * function returns. An identity `ns.member` of two identifiers makes the function member
+     * `member` of the namespace object `ns`, which the sandbox makes for its first member.
+     * Where scripts find functions and namespaces is `globals` and `bindings`.
+     */
+    functions?: Record<string, HostFunction>;
+    /**
+     * Async host functions, by identity (D1374): a call returns a promise in the VM at
+     * once and the script goes on, so several calls can be outstanding (`Promise.all`
+     * over tools). The function may return a value or a promise. Identities as in `functions`.
+     * An `AsyncHostFunction` (`{ call, save, resume }`) adds the hooks that let a task
+     * suspended into a dump continue its open calls after a load.
+     */
+    asyncFunctions?: Record<string, HostFunction | AsyncHostFunction>;
+    /**
+     * The global bindings of host functions and namespaces: global name -> identity of a
+     * function or namespace (`{ tools: "tools", console: "console", myTool:
+     * "@sdk/our-stuff#myTool" }`, D2972). Without it, the one written rule: `console`, every
+     * namespace and every function whose identity is an identifier are globals of their
+     * own names (`tools.read` makes the global `tools`).
+     */
+    globals?: Record<string, string>;
+    /**
+     * The bindings every codemode body gets as parameters, after the run's `params`:
+     * parameter name -> identity of a function or namespace (`{ myTool:
+     * "@sdk/our-stuff#myTool", tools: "tools" }`, D2972). A stand-in for imports: a script
+     * that calls `myTool("x")` finds it there. Default: none.
+     */
+    bindings?: Record<string, string>;
+    /** Receives `console.*` calls from the sandbox; default: the host's `console`. */
+    console?: ConsoleLike;
+    /**
+     * The clock `Date.now()` and `new Date()` see, in ms since the epoch (the VM reads no
+     * clock itself, D1383): a fixed time (replays) or a function; default `Date.now`.
+     * Set before every fuel slice.
+     */
+    now?: number | (() => number);
+    /**
+     * The VM's local time zone, in minutes east of UTC (fixed, no DST); default: the
+     * host's current offset. Set before every fuel slice.
+     */
+    timeZoneOffset?: number;
+    /**
+     * Promises rejected with no handler once the VM's job queue ran empty (as qjs reports
+     * them, D1423; a rejected result promise does not count): `"warn"` (default) passes
+     * each reason (its display form, `TypeError: x`) to `console.warn`,
+     * `"throw"` fails the run with a `threw` SandboxError, `"collect"` keeps them for
+     * `takeUnhandledRejections()`.
+     */
+    unhandledRejections?: "warn" | "throw" | "collect";
+    /**
+     * Parse the code as TypeScript (types are erased, enums and namespaces run; 0048).
+     * Default false.
+     */
+    typescript?: boolean;
+    /**
+     * The 64-bit seed of `Math.random` for a new sandbox (a restored one continues its
+     * sequence). Default: from `crypto.getRandomValues`. Ignored with `deterministic`.
+     */
+    randomSeed?: number | bigint;
+    /**
+     * What `WeakRef` and `FinalizationRegistry` do (D1680): `"collected"` (weak, as the
+     * spec intends), `"strong"` (targets never die and cleanup callbacks never run, so no
+     * collection is observable) or `"absent"` (the globals are deleted). Default
+     * `"collected"`, with `deterministic` `"strong"`.
+     */
+    weakRefs?: "collected" | "strong" | "absent";
+    /**
+     * Frozen builtins (D2304): the builtin objects (prototypes, constructors, `Math`, ...)
+     * behave as frozen: writes to them fail (a TypeError in strict code), their properties
+     * read as non-writable and non-configurable, and `Object.isFrozen` is true. Assigning
+     * over an inherited builtin property (`obj.toString = f`, `this.name = ...` in an Error
+     * subclass) defines an own property instead of failing, as after SES's lockdown.
+     * `globalThis` stays ordinary. Default false (the spec's behavior); a restored sandbox
+     * keeps the mode it was created with.
+     */
+    frozenBuiltins?: boolean;
+    /**
+     * The scripts a loaded dump may refer to (D2834, D2882): a dump names the codemode body
+     * it continues by `$djs.source(name, hash)` instead of carrying its text a second time,
+     * and loading it needs that script again. The scripts this sandbox ran are known; for a
+     * dump from another process, return the code the script `name` (`BeginOptions.filename`,
+     * default `"sandbox.js"`) had. A script that is not the one the dump refers to (another
+     * text, parameters or options) is refused.
+     */
+    sources?: (name: string) => string | undefined;
+    /**
+     * Dumps write the codemode body's text instead of `$djs.source(name, hash)`: a dump
+     * that loads without the script (larger). Default false.
+     */
+    inlineSources?: boolean;
+    /**
+     * Run deterministically (D1680): with the same code, parameters and results in the same
+     * order, a run does the same thing every time. `Math.random` is seeded from `seed`, the
+     * time zone is UTC, weak references are strong (unless `weakRefs` says otherwise), and
+     * the clock starts at `startedAt` and moves only when an async host function's result
+     * is delivered: to `now` at that moment (never backwards). Sync host functions and
+     * fuel slices do not move it. A fixed `now` makes the clock fully reproducible.
+     */
+    deterministic?: {
+        startedAt: number;
+        seed: number | bigint;
+    };
+    /**
+     * With `typescript`: TypeScript's legacy `experimentalDecorators` (tsc's decorator
+     * semantics and parameter decorators) instead of the standard decorators (0065).
+     * Default false.
+     */
+    experimentalDecorators?: boolean;
+    /**
+     * With `typescript`: `emitDecoratorMetadata` (`design:type` and friends through
+     * `Reflect.metadata`); implies `experimentalDecorators`. Default false.
+     */
+    emitDecoratorMetadata?: boolean;
+    /**
+     * Makes `debugger;` a pause (D3050): in an async function, the statement awaits a call
+     * of this function, bound as the global `debugger` with the identity `"debugger"`. While
+     * it is open, the run is idle at the statement and can be dumped there (a task's
+     * `suspend`, `Run.dump`); a dump writes the pause as any open call, and a sandbox with
+     * this option that loads it pauses again at the next `debugger;`. Outside async
+     * functions the statement does nothing, as without the option. Needs a `module` with the
+     * dumper (the dump module), since a dump compiles the script again with the same options.
+     */
+    debugger?: HostFunction | AsyncHostFunction;
+}
+export type SandboxErrorKind = "threw" | "syntax" | "fuel" | "trap" | "memory" | "misuse" | "diverged" | "suspended";
+/**
+ * One entry of a run's journal (D1730, docs/host.md "Journals"): everything a
+ * deterministic run took from outside, in order, plus checks. Values are host values
+ * (JSON-serializable when the host's values are); a host error is `{ name, message }`.
+ * - `run`: the start: the engine build, the code, the parameters and the canonical hash
+ *   of the VM before the run.
+ * - `sync`: a sync host function's call and outcome (console output is not journaled).
+ * - `async`: an async host function's result, in delivery order, with the clock it
+ *   carried.
+ * - `check`: the VM was idle (quiescent) after `delivered` results, with `issued` host
+ *   calls made and this canonical hash.
+ * - `end`: the outcome (`ok` false: the error's display text), with the final counts and
+ *   hash.
+ */
+export type JournalEntry = {
+    type: "run";
+    engine: string;
+    code: string;
+    params: Record<string, unknown>;
+    hash: string;
+} | {
+    type: "sync";
+    fn: string;
+    args: unknown[];
+    ok: boolean;
+    value: unknown;
+} | {
+    type: "async";
+    callId: number;
+    fn: string;
+    args: unknown[];
+    ok: boolean;
+    value: unknown;
+    now: number;
+} | {
+    type: "check";
+    delivered: number;
+    issued: number;
+    hash: string;
+} | {
+    type: "end";
+    ok: boolean;
+    value: unknown;
+    delivered: number;
+    issued: number;
+    hash: string;
+};
+/** Options of one run. */
+/** A source position (`Sandbox.callSite`): the script's name, line and column from 1. */
+export interface CallSite {
+    file: string;
+    line: number;
+    column: number;
+}
+export interface RunOptions {
+    /** Record the run (deterministic sandboxes only): entries are appended to this array. */
+    journal?: JournalEntry[];
+}
+/** An async host call the script made that has no result yet (`Run.calls`). */
+export interface OpenCall {
+    /** The VM's call id: `settle` takes it, and a dump keeps it. */
+    id: number;
+    /** The host function's name, as given in `asyncFunctions` (`sleep`, `tools.read`). */
+    fn: string;
+    args: unknown[];
+    /** A loaded call's state, as dumped (D2770); absent when the dump has none. */
+    state?: unknown;
+}
+/** A host call's outcome for `Run.settle`: a value, or (`ok` false) an error to reject with. */
+export interface Settlement {
+    ok: boolean;
+    value: unknown;
+}
+/** What `Sandbox.load` recreated: the open host calls of a dump (0171, D2890). */
+export interface LoadedDump {
+    calls: OpenCall[];
+}
+/**
+ * Options of `Sandbox.begin`. A `journal` records the run while it stays in this sandbox:
+ * the sync calls, every `settle` in order and a check at every idle point; `replay` runs
+ * it like a `runAsync` journal.
+ */
+export interface BeginOptions extends RunOptions {
+    /**
+     * The script's name, as stack traces show it (`sleep.js:4:13`); default `sandbox.js`.
+     */
+    filename?: string;
+}
+/** Why a sandbox operation failed. `value` is the thrown VM value (kind "threw"). */
+export declare class SandboxError extends Error {
+    readonly kind: SandboxErrorKind;
+    readonly value?: unknown;
+    constructor(kind: SandboxErrorKind, message: string, value?: unknown);
+}
+/**
+ * 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 declare function scriptHash(source: string, params: string, bits: number): string;
+/** A plain dump (D2830): `"djs-dump";`, and whether its text is TypeScript. */
+export declare function plainDump(text: string): {
+    typescript: boolean;
+} | undefined;
+/**
+ * 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 declare function defaultWasmPath(): string | URL;
+/**
+ * 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 declare function loadModule(location?: string | URL): Promise<WebAssembly.Module>;
+/** What a run in progress needs from its sandbox. */
+interface RunCore {
+    /** The open async calls, oldest first, until their results are delivered. */
+    open: Map<number, OpenCall>;
+    /**
+     * A resumed run's result promise, the handle its dump named `run` (freed at the end);
+     * 0 for a run this sandbox started, whose result is the entry call's outcome.
+     */
+    result: number;
+    /** Fuel used so far: `maxFuel` is per run, across all its steps. */
+    used: number;
+    /** A new async call (`runAsync`: call the host function now). */
+    onCall?(call: OpenCall, fnId: number): void;
+    /** Before every fuel slice (`runAsync`: pass back the results that came in). */
+    beforeSlice?(): void;
+    advance(): Promise<RunEnd>;
+    settle(id: number, s: Settlement): void;
+    /** Passes a result back; `at`: a replayed result's clock. */
+    deliver(id: number, ok: boolean, value: unknown, at?: number): void;
+    /** `states`: the host's state of open calls, by id, as JSON text (D2770). */
+    dump(states?: [number, string][]): string;
+}
+type RunEnd = {
+    state: "idle";
+} | {
+    state: "done";
+    value: unknown;
+} | {
+    state: "threw";
+    error: SandboxError;
+};
+/**
+ * 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 declare class Run {
+    #private;
+    /** "idle": waiting on `calls`; "done": `value` is the result; "threw": `error`. */
+    state: "idle" | "done" | "threw";
+    value: unknown;
+    error: SandboxError | undefined;
+    /** Made by `Sandbox.begin` and `Sandbox.resume`. */
+    constructor(core: RunCore);
+    /** The async host calls waiting for a result, oldest first. */
+    get calls(): OpenCall[];
+    /**
+     * Delivers the result of open call `id`. The VM applies it at the next `advance`, after
+     * the results settled before it (D1670).
+     */
+    settle(id: number, s: Settlement): void;
+    /**
+     * 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`.
+     */
+    advance(): Promise<void>;
+    /**
+     * 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?: Record<number, unknown>): string;
+    /** Records how a step ended. */
+    end(e: RunEnd): void;
+}
+/** A call a task waits for: the hooks' view of it, and how to stop waiting. */
+interface LiveCall {
+    call: HostCall;
+    abort: AbortController;
+}
+/** A dump a task was asked for: `suspend` (the task stops) or `checkpoint`. */
+interface DumpRequest {
+    stop: boolean;
+    resolve(text: string): void;
+    reject(e: unknown): void;
+}
+/**
+ * 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 declare class Task {
+    #private;
+    /** The sandbox the task runs in (dispose it when done). */
+    readonly sandbox: 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).
+     */
+    readonly result: Promise<unknown>;
+    /** Made by `Sandbox.start` and `Sandbox.resume`. */
+    constructor(sandbox: Sandbox, result: Promise<unknown>, calls: Map<number, LiveCall>, request: (r: DumpRequest) => void);
+    /** The async host calls the task waits for, oldest first. */
+    get calls(): HostCall[];
+    /**
+     * 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(): Promise<string>;
+    /** `suspend` without stopping: a dump at the next idle point, and the task goes on. */
+    checkpoint(): Promise<string>;
+}
+/**
+ * A VM image moving between the main module and the dump module (packaging B, D2635):
+ * the arena as is, with what the sandbox keeps beside it.
+ */
+interface RawImage {
+    image: Uint8Array;
+    functions: string[];
+    clock?: number;
+    namespaces: [string, number][];
+    fnHandles: [number, number][];
+    globals: string[];
+}
+export declare class Sandbox {
+    private readonly x;
+    private readonly module;
+    /** The VM; replaced when the dump module's sandbox takes another image (`takeImage`). */
+    private vm;
+    private readonly opts;
+    /** Host function names by id - 1. */
+    private readonly fnNames;
+    private readonly fns;
+    /** Async host functions with hooks (D2771), by id. */
+    private readonly hooks;
+    private readonly atomCache;
+    private readonly rejections;
+    private readonly cons;
+    private dead;
+    /** Deterministic mode: the VM's clock, moved only by async results (never backwards). */
+    private clock;
+    /** The journal of the current run, being recorded or replayed (D1730). */
+    private journal;
+    /** The first hook a dump's load could not serve (D3001). */
+    private hookError;
+    /** Namespace objects this sandbox made for dotted function names (`tools`), as handles. */
+    private readonly namespaces;
+    /** The host function objects by id, as handles: one per identity (D2970). */
+    private readonly fnHandles;
+    private readonly fnAsync;
+    /** The globals the sandbox bound to host functions and namespaces (a dump's host globals). */
+    private readonly globalNames;
+    /** The host-driven run in progress (`begin`, `resume`), until it ends. */
+    private active;
+    /** The task in progress (`start`, `resume`): ends it when the sandbox is disposed. */
+    private cancelTask;
+    /**
+     * 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(): string | URL;
+    /** A new sandbox; loads (and caches) the default module unless `opts.module` is given. */
+    static create(opts?: SandboxOptions): Promise<Sandbox>;
+    /**
+     * 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 resume(dump: string, opts?: SandboxOptions): Promise<Task>;
+    /**
+     * 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: string): Task;
+    /**
+     * 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: string): Run;
+    /** Loads a dump that holds a run: its open calls and the run's result promise. */
+    private loadRunDump;
+    /**
+     * 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?: SandboxOptions, raw?: RawImage);
+    /**
+     * 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: string, f: HostFunction): void;
+    /** Defines an async host function (see `SandboxOptions.asyncFunctions`), bound as `defineFunction` does. */
+    defineAsyncFunction(name: string, f: HostFunction | AsyncHostFunction): void;
+    /** Makes host function `name` and, for `ns.member`, adds it to the namespace `ns`. */
+    private addFunction;
+    /** The namespace object `ns`, made on first use (D2632); bound nowhere by itself. */
+    private namespace;
+    /** The written rule: the globals the sandbox binds without `SandboxOptions.globals`. */
+    private defaultGlobals;
+    private bindDefault;
+    /** The object of a namespace or host function by identity (D2970), as a handle the sandbox owns. */
+    private hostValue;
+    private bindGlobal;
+    /** Defines a global variable holding a copy of `value` (sent through the wire format). */
+    setGlobal(name: string, value: unknown): void;
+    /**
+     * 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: string, params?: Record<string, unknown>, opts?: RunOptions): unknown;
+    /**
+     * 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: string, params?: Record<string, unknown>, opts?: BeginOptions): 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: string, params?: Record<string, unknown>, opts?: BeginOptions): Task;
+    /**
+     * 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.
+     */
+    private task;
+    /** Makes a run, waiting on `calls`, with its result promise `result` (0: the entry call's). */
+    private startRun;
+    /** One step of a host-driven run: `drive` until idle (recording a check) or the end. */
+    private step;
+    /**
+     * 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.
+     */
+    private auto;
+    /** Records a `check` entry at an idle point, when recording. */
+    private recordCheck;
+    /** The run has ended: frees its result handle; the sandbox can run again. */
+    private endRun;
+    /**
+     * `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).
+     */
+    private dumpRun;
+    /**
+     * 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?: string[]): string;
+    /**
+     * `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).
+     */
+    private dumpText;
+    /**
+     * 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).
+     */
+    private viaDumper;
+    /** The dump module's sandbox: takes the main sandbox's image into the same VM. */
+    private takeImage;
+    /** Replaces this sandbox's VM with an image (from the dump module). */
+    private replaceVm;
+    /**
+     * 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).
+     */
+    private serveSource;
+    /**
+     * 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`).
+     */
+    private serveHost;
+    /**
+     * 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).
+     */
+    private failHook;
+    /** `vm_dump` in this sandbox's own module. */
+    private dumpHere;
+    /**
+     * 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: string): LoadedDump;
+    /** Loads a dump: the open calls it recreated and the handles it named (the caller frees them). */
+    private loadDump;
+    /**
+     * 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.
+     */
+    private loadPlain;
+    /**
+     * 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.
+     */
+    runAsync(code: string, params?: Record<string, unknown>, opts?: RunOptions): Promise<unknown>;
+    /**
+     * 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.
+     */
+    replay(journal: JournalEntry[]): Promise<unknown>;
+    /** The VM's canonical hash (D1730) as 16 hex digits: its state, independent of collections. */
+    canonicalHash(): string;
+    private buildHash;
+    /** Starts recording a run into `opts.journal`, if given. */
+    private beginJournal;
+    /**
+     * 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.
+     */
+    private abandon;
+    /**
+     * 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(): Uint8Array;
+    /**
+     * 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: number): CallSite | undefined;
+    /** Collects garbage now. False if the heap could not reserve the to-space. */
+    collect(): boolean;
+    /** The arena's current size in bytes. */
+    get heapSize(): number;
+    /** Releases the VM. The sandbox cannot be used afterwards. A task in progress ends (`misuse`). */
+    dispose(): void;
+    /** Panics inside the module on purpose (tests the trap path). */
+    debugTrap(): void;
+    private alive;
+    /** Runs `f` and turns a wasm trap into a SandboxError; the sandbox is dead afterwards. */
+    private guard;
+    private check;
+    /** Copies bytes into the staging buffer. */
+    private stage;
+    private stageText;
+    private hostFunction;
+    private defineOn;
+    /** A handle for a host value (0 for undefined). */
+    private toHandle;
+    private arena;
+    private read;
+    private readHandle;
+    private display;
+    /** Compiles `code` and starts the call; returns nothing (the VM holds the call). */
+    private enter;
+    /**
+     * 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`).
+     */
+    private drive;
+    /**
+     * The unhandled rejections collected so far (`unhandledRejections: "collect"`), as host
+     * values; forgets them.
+     */
+    takeUnhandledRejections(): unknown[];
+    /** Reports the VM's unhandled rejections per `opts.unhandledRejections` (D1423). */
+    private checkRejections;
+    /**
+     * 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`).
+     */
+    private setClock;
+    /** Calls host function `fnId` with arguments read from the VM; `call` is `this` for hooks. */
+    private invoke;
+    /** The async host calls made since the last check (`vm_new_host_calls`). */
+    private newHostCalls;
+    /** The function and arguments of pending host call `callId`. */
+    private callInfo;
+    /** Reads `[call_id, fn_id, this, args...]` from the out buffer. */
+    private readCall;
+    /**
+     * 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.
+     */
+    private complete;
+}
+export {};