@daugasauron/dolly 0.0.0-stage → 0.1.4-rc.0

package/host/runtime/runtime.mjs

@@ -0,0 +1,209 @@
+import { DollyProcessSupervisor } from "../../src/process-supervisor.mjs";
+import { createLeaseBridge } from "./lease-bridge.mjs";
+import { instantiateKernelPlugin } from "../../src/kernel-plugin.mjs";
+import { DOLLY_ERRNO as E } from "./abi.mjs";
+import { DOLLY_TERMINAL_WORD_RESULT_SEQUENCE, DOLLY_TERMINAL_WORD_RESULT_STATUS, DOLLY_TERMINAL_WORD_FOREGROUND_PID,
+  DOLLY_TERMINAL_WORD_FOREGROUND_INTERRUPTIBLE, DOLLY_TERMINAL_WORD_INTERRUPT_SEQUENCE,
+  DOLLY_TERMINAL_WORD_INTERRUPT_TARGET_PID } from "./abi.mjs";
+
+export function check() {
+  if (!globalThis.crossOriginIsolated) return "cross-origin isolation is required";
+  try { new WebAssembly.Memory({ initial: 1n, maximum: 1n, shared: true, address: "i64" }); }
+  catch { return "shared WebAssembly memory64 is unavailable"; }
+  return null;
+}
+
+// Bootstrap text only feeds the page's 1 MiB log; a longer write is refused.
+const maxBootstrapMessage = 1024 * 1024;
+// What crypto.getRandomValues fills in one call.
+const maxEntropy = 65536;
+
+// The terminal mailbox (abi/dolly-supervisor-0.wat), the Worker's end: the
+// foreground command, shell results and the page's interrupt request, with or
+// without a display.
+class TerminalMailbox {
+  static resultSequence = DOLLY_TERMINAL_WORD_RESULT_SEQUENCE;
+  static resultStatus = DOLLY_TERMINAL_WORD_RESULT_STATUS;
+  static foregroundPid = DOLLY_TERMINAL_WORD_FOREGROUND_PID;
+  static foregroundInterruptible = DOLLY_TERMINAL_WORD_FOREGROUND_INTERRUPTIBLE;
+  static interruptSequence = DOLLY_TERMINAL_WORD_INTERRUPT_SEQUENCE;
+  static interruptTargetPid = DOLLY_TERMINAL_WORD_INTERRUPT_TARGET_PID;
+
+  constructor(buffer, address) {
+    if (!(buffer instanceof SharedArrayBuffer) || !Number.isSafeInteger(address) ||
+        address <= 0 || address % 4 !== 0 || address > buffer.byteLength - 24) {
+      throw new Error("Dolly supplied an invalid terminal mailbox");
+    }
+    this.words = new Int32Array(buffer, address, 6);
+  }
+
+  currentResultSequence() {
+    return Atomics.load(this.words, TerminalMailbox.resultSequence);
+  }
+
+  async waitForResult(sequence) {
+    while (Atomics.load(this.words, TerminalMailbox.resultSequence) === sequence) {
+      const waiting = Atomics.waitAsync(this.words, TerminalMailbox.resultSequence, sequence);
+      if (waiting.async) await waiting.value;
+    }
+    return Atomics.load(this.words, TerminalMailbox.resultStatus);
+  }
+
+  foregroundPid() {
+    return Atomics.load(this.words, TerminalMailbox.foregroundPid);
+  }
+
+  // The terminal's interrupt character (termios VINTR) while it signals, or 0.
+  foregroundInterruptKey() {
+    return Atomics.load(this.words, TerminalMailbox.foregroundInterruptible);
+  }
+
+  foregroundInterruptible() {
+    return this.foregroundInterruptKey() !== 0;
+  }
+
+  // The interrupt key, or a caller with none to give: Wasm interrupts the
+  // foreground command read here only if it still owns the terminal. False
+  // (ISIG clear, or another key) lets the key reach it as input.
+  interruptForeground(key) {
+    const pid = this.foregroundPid();
+    if (pid <= 0 || !this.foregroundInterruptible() || (key !== undefined && key !== this.foregroundInterruptKey())) return false;
+    Atomics.store(this.words, TerminalMailbox.interruptTargetPid, pid);
+    Atomics.add(this.words, TerminalMailbox.interruptSequence, 1);
+    return true;
+  }
+}
+
+// The page's terminal: the foreground program and its interrupt key as the
+// Worker last reported them; the shell's results and interrupts, asked of the
+// Worker, which decides on what it holds then.
+export function browser({ ask }) {
+  let foreground = { pid: 0, interrupt: 0 };
+  const terminal = {
+    foregroundPid: () => foreground.pid,
+    foregroundInterruptKey: () => foreground.interrupt,
+    foregroundInterruptible: () => foreground.interrupt !== 0,
+    currentResultSequence: () => ask({ type: "terminal-result-sequence" }),
+    waitForResult: sequence => ask({ type: "terminal-result", sequence }),
+    interruptForeground: key => ask({ type: "terminal-interrupt", key }),
+  };
+  return {
+    terminal,
+    page: { terminal, get foregroundPid() { return foreground.pid; } },
+    messages: { "terminal-foreground"({ pid, interrupt }) { foreground = { pid, interrupt }; } },
+  };
+}
+
+export function worker({ send, runtimeBase, abi, service }) {
+  const memory = new WebAssembly.Memory({ initial: 1024n, maximum: 131072n, shared: true, address: "i64" });
+  // The kernel's memory grows in a Worker of its own (grower.mjs) while this
+  // one waits. Chrome counts a shared memory as external memory of the isolate
+  // that grows it; past twice its heap limit it then collects between every
+  // message of this one, and every system call takes fifteen times as long.
+  const growth = new BigInt64Array(new SharedArrayBuffer(16)), growthWord = new Int32Array(growth.buffer);
+  const grower = new Worker(new URL("./grower.mjs", import.meta.url), { type: "module", name: "dolly-memory" });
+  const growing = new Promise((resolve, reject) => {
+    grower.onmessage = resolve;
+    grower.onerror = event => reject(new Error(event.message || "the kernel memory Worker failed"));
+  });
+  grower.postMessage({ memory, control: growth.buffer });
+  let supervisor, threadProvider, terminal, reported = "";
+  // The foreground program, sent to the page when it changes.
+  function reportForeground() {
+    if (!terminal) return;
+    const foreground = { pid: terminal.foregroundPid(), interrupt: terminal.foregroundInterruptKey() };
+    const text = JSON.stringify(foreground);
+    if (text === reported) return;
+    reported = text;
+    send({ type: "terminal-foreground", ...foreground });
+  }
+  // Modules served inside the process Worker of the executables that record
+  // them, by requirement: the bundle (a Blob) that Worker imports and the
+  // configuration its serve() receives.
+  const processModules = new Map();
+  // The bytes a kernel import names, or null: inside kernel memory, at most `limit`.
+  const span = (address, length, limit) => {
+    const [start, size] = [address, length].map(Number);
+    return start >= 0 && size >= 0 && size <= limit && start <= memory.buffer.byteLength - size
+      ? new Uint8Array(memory.buffer, start, size) : null;
+  };
+  return {
+    memory,
+    // Before the kernel runs: it must not ask for memory before the Worker that grows it waits.
+    growing,
+    get terminal() { return terminal; },
+    reportForeground,
+    service: reportForeground,
+    messages: {
+      "terminal-result-sequence": () => terminal.currentResultSequence(),
+      "terminal-result": ({ sequence }) => terminal.waitForResult(sequence),
+      "terminal-interrupt": ({ key }) => terminal.interruptForeground(key),
+    },
+    bindings: {
+      "env.memory": memory,
+      "env.dolly_bootstrap_write_bytes": (address, length) => {
+        const bytes = span(address, length, maxBootstrapMessage);
+        if (!bytes) return -E.EINVAL;
+        send({ type: "bootstrap-bytes", bytes: bytes.slice() });
+        return 0;
+      },
+      "env.dolly_clock_realtime": () => Date.now(),
+      "env.dolly_clock_monotonic": () => performance.now(),
+      "env.dolly_memory_grow": pages => {
+        growth[1] = pages;
+        Atomics.store(growthWord, 0, 1);
+        Atomics.notify(growthWord, 0);
+        // A notify can be the grower's for the last growth, whose wait found
+        // it done already: this one is done when the word says so.
+        while (Atomics.load(growthWord, 0) === 1) Atomics.wait(growthWord, 0, 1);
+        const old = growth[1];
+        // This thread learns of the growth by an interrupt, which a wait that
+        // found it done already does not take: take it before the kernel
+        // touches the new pages, as a loop does at each turn.
+        if (old >= 0n) while (BigInt(memory.buffer.byteLength) < (old + pages) * 65536n);
+        return old;
+      },
+      // Web Crypto rejects views of shared memory: fill a private buffer, then copy.
+      "env.dolly_entropy": (address, length) => {
+        const bytes = span(address, length, maxEntropy);
+        if (!bytes) return -E.EINVAL;
+        bytes.set(crypto.getRandomValues(new Uint8Array(bytes.length)));
+        return 0;
+      },
+    },
+    // Both follow their modules, which nena@0 may enable or disable while the
+    // supervisor runs: undefined takes the provider or the module away.
+    setThreadProvider(provider) {
+      threadProvider = provider;
+      if (provider) { if (supervisor) supervisor.threadHost = provider; }
+      else supervisor?.withdrawThreads();
+    },
+    serveInProcess(requirement, module) {
+      if (module) processModules.set(requirement, module); else processModules.delete(requirement);
+    },
+    async supervisor(kernel) {
+      return supervisor ??= await DollyProcessSupervisor.create(kernel, memory, runtimeBase, abi, service, threadProvider, processModules);
+    },
+    start({ kernel }) {
+      terminal = new TerminalMailbox(memory.buffer, Number(kernel.dolly_terminal_mailbox_address()));
+      reportForeground();
+    },
+    serviceDeferred() { supervisor?.serviceDeferred(); },
+    // Services deferred work each time the page notifies words[index], a
+    // module's mailbox word, until the returned function is called.
+    serviceOnNotify(words, index) {
+      let stopped = false;
+      const wait = () => void Promise.resolve(Atomics.waitAsync(words, index, Atomics.load(words, index)).value)
+        .then(() => { if (stopped) return; supervisor?.serviceDeferred(); wait(); });
+      wait();
+      return () => { stopped = true; };
+    },
+    // A resident library linked into the kernel (--dolly-kernel-plugin), such as the display's.
+    kernelPlugin(bytes, kernel) { return instantiateKernelPlugin(bytes, kernel, memory); },
+    // The Worker side of a device a module leases per process (src/device-lease.c).
+    leaseBridge(lease, mailbox, send) {
+      return createLeaseBridge(lease, memory, mailbox, send, () => supervisor?.serviceDeferred());
+    },
+    dispose() { supervisor?.dispose(); grower.terminate(); },
+  };
+}

package/host/snapshot/abi.mjs

@@ -0,0 +1,16 @@
+// Generated from host/snapshot/dolly-snapshot-0.wat, include/dolly/process.h.
+export const DOLLY_SESSION_HEADER_SIZE = 64;
+export const DOLLY_SESSION_NAME_CAPACITY = 128;
+export const DOLLY_SESSION_TRANSFER_CAPACITY = 1048576;
+export const DOLLY_SESSION_WORD_REQUEST_SEQUENCE = 0;
+export const DOLLY_SESSION_WORD_COMPLETED_SEQUENCE = 1;
+export const DOLLY_SESSION_WORD_STATUS = 2;
+export const DOLLY_SESSION_WORD_NAME_LENGTH = 3;
+export const DOLLY_SESSION_WORD_CHUNK_SEQUENCE = 4;
+export const DOLLY_SESSION_WORD_CHUNK_CONSUMED_SEQUENCE = 5;
+export const DOLLY_SESSION_WORD_CHUNK_LENGTH = 6;
+export const DOLLY_SESSION_WORD_CHUNK_EOF = 7;
+export const DOLLY_SESSION_WORD_TOTAL_SIZE_LOW = 8;
+export const DOLLY_SESSION_WORD_TOTAL_SIZE_HIGH = 9;
+export const DOLLY_SESSION_WORD_CANCELLED_SEQUENCE = 10;
+export const DOLLY_ERRNO = Object.freeze({ E2BIG: 1, EACCES: 2, EADDRINUSE: 3, EADDRNOTAVAIL: 4, EAFNOSUPPORT: 5, EAGAIN: 6, EALREADY: 7, EBADF: 8, EBADMSG: 9, EBUSY: 10, ECANCELED: 11, ECHILD: 12, ECONNABORTED: 13, ECONNREFUSED: 14, ECONNRESET: 15, EDEADLK: 16, EDESTADDRREQ: 17, EDOM: 18, EDQUOT: 19, EEXIST: 20, EFAULT: 21, EFBIG: 22, EHOSTUNREACH: 23, EIDRM: 24, EILSEQ: 25, EINPROGRESS: 26, EINTR: 27, EINVAL: 28, EIO: 29, EISCONN: 30, EISDIR: 31, ELOOP: 32, EMFILE: 33, EMLINK: 34, EMSGSIZE: 35, EMULTIHOP: 36, ENAMETOOLONG: 37, ENETDOWN: 38, ENETRESET: 39, ENETUNREACH: 40, ENFILE: 41, ENOBUFS: 42, ENODEV: 43, ENOENT: 44, ENOEXEC: 45, ENOLCK: 46, ENOLINK: 47, ENOMEM: 48, ENOMSG: 49, ENOPROTOOPT: 50, ENOSPC: 51, ENOSYS: 52, ENOTCONN: 53, ENOTDIR: 54, ENOTEMPTY: 55, ENOTRECOVERABLE: 56, ENOTSOCK: 57, ENOTTY: 59, ENXIO: 60, EOVERFLOW: 61, EOWNERDEAD: 62, EPERM: 63, EPIPE: 64, EPROTO: 65, EPROTONOSUPPORT: 66, EPROTOTYPE: 67, ERANGE: 68, EROFS: 69, ESPIPE: 70, ESRCH: 71, ESTALE: 72, ETIMEDOUT: 73, ETXTBSY: 74, EXDEV: 75, ENODATA: 116, ENOTSUP: 138 });

package/host/snapshot/module.json

@@ -0,0 +1,15 @@
+{
+  "name": "snapshot",
+  "version": 0,
+  "gives": "save the session in this browser and restore it",
+  "fixed": "its baseline is the image as loaded",
+  "dependencies": ["runtime@0"],
+  "phase": "image",
+  "imports": [],
+  "host": "snapshot.mjs",
+  "contracts": ["dolly-snapshot-0.wat"],
+  "process": [],
+  "headers": [],
+  "kernel": ["kernel.c"],
+  "client": []
+}

package/host/snapshot/snapshot.mjs

@@ -0,0 +1,138 @@
+import { SessionTransport } from "./transport.mjs";
+import { mountSessionSave } from "./ui.mjs";
+import { DOLLY_BUILD_ID } from "../../dist/dolly-build-id.mjs";
+import { DOLLY_IMAGE_BUILD_ID } from "../../dist/dolly-image-build-id.mjs";
+import { DOLLY_IMAGES } from "../../src/images.mjs";
+import { DOLLY_SESSION_FORMAT_VERSION, decodeSessionSnapshot, loadStoredSession, sessionCompatible,
+  sessionLoadUrl, validSessionName, DOLLY_SESSION_MAX_BYTES } from "../../src/session-store.mjs";
+
+// A session route (/session/?name=NAME) boots the saved session's image and
+// restores its delta; with recover=1 it unpacks the files into a fresh system
+// image instead.
+export async function boot(route) {
+  if (!route.loadSession) return undefined;
+  if (route.mode !== "snapshot") throw new Error("invalid Dolly route configuration");
+  const query = new URL(location.href).searchParams;
+  const name = query.get("name"), recovering = query.get("recover") === "1";
+  if (!validSessionName(name)) throw new Error("The Dolly session URL has an invalid name. Open /sessions to see saved sessions.");
+  const record = await loadStoredSession(name);
+  if (record === null) throw new Error(`Session '${name}' was not found in this browser. Open /sessions to see saved sessions.`);
+  if (record.name !== name) throw new Error("Stored session name does not match its key");
+  let image = record.image;
+  if (recovering) {
+    if (record.formatVersion !== DOLLY_SESSION_FORMAT_VERSION) throw new Error("This save uses an unsupported recovery format");
+    if (!DOLLY_IMAGES.some(definition => definition.image === "system")) throw new Error("File recovery needs the system image in this distribution");
+    image = "system";
+  } else if (!sessionCompatible(record, DOLLY_IMAGES, DOLLY_BUILD_ID, DOLLY_IMAGE_BUILD_ID)) {
+    throw new Error("This save belongs to an older runtime or image recipe. It has not been deleted or overwritten. Open /sessions to see saved sessions.");
+  }
+  const bytes = await decodeSessionSnapshot(record);
+  record.bytes.transfer(0);
+  record.bytes = undefined;
+  return { image, label: `${recovering ? "RECOVER FILES FROM" : "RESTORE SESSION"} ${name}`,
+    custom: image === "custom" ? record.customImage : undefined, configuration: { bytes, name, recovering } };
+}
+
+// The page's capture: the Worker reads the session's chunks out of the mailbox
+// and hands each one to onChunk here, waiting until it is consumed.
+function sessionCapture({ send, ask }) {
+  let consume = null;
+  return {
+    async capture(name, { signal, onChunk }) {
+      signal?.throwIfAborted();
+      if (consume) throw new Error("A Dolly session save is already active");
+      const cancel = () => send({ type: "snapshot-cancel" });
+      consume = onChunk;
+      signal?.addEventListener("abort", cancel, { once: true });
+      try { return await ask({ type: "snapshot-capture", name }); }
+      finally {
+        consume = null;
+        signal?.removeEventListener("abort", cancel);
+      }
+    },
+    chunk: ({ bytes }) => consume?.(bytes),
+  };
+}
+
+export function browser(page) {
+  const { bytes, name, recovering } = page.configuration, capture = sessionCapture(page);
+  const session = mountSessionSave(page, () => capture, name === undefined ? null : { name, recovering });
+  return {
+    configuration: bytes === undefined ? {} : { bytes, ...(recovering ? { recover: name } : {}) },
+    transfers: bytes ? [bytes] : [],
+    page: { get sessionName() { return session.name; }, saveSession: session.save },
+    claimsKey: session.claimsKey,
+    entryStarted: session.entryStarted,
+    // An ended image leaves the session this tab saved or restored to open again.
+    ended: () => session.name && page.site ? [{ text: `Open saved session ${session.name}`,
+      href: sessionLoadUrl(session.name, page.site).href }] : [],
+    messages: { "snapshot-chunk": capture.chunk },
+    dispose() { session.abort(); },
+  };
+}
+
+export function worker({ get, ask, configuration: { bytes, recover } }) {
+  let kernel, transport, cancelled;
+  if (bytes !== undefined && (!(bytes instanceof ArrayBuffer) || bytes.byteLength < 16 ||
+      bytes.byteLength > DOLLY_SESSION_MAX_BYTES)) throw new Error("invalid Dolly session snapshot");
+  if (recover !== undefined && (!validSessionName(recover) || bytes === undefined)) {
+    throw new Error("invalid Dolly file recovery request");
+  }
+  function restore(kernel) {
+    const memory = get("runtime").memory;
+    const address = Number(kernel.dolly_session_restore_address(BigInt(bytes.byteLength)));
+    if (!Number.isSafeInteger(address) || address <= 0 || address > memory.buffer.byteLength - bytes.byteLength) {
+      throw new Error("invalid session restore memory range");
+    }
+    new Uint8Array(memory.buffer, address, bytes.byteLength).set(new Uint8Array(bytes));
+    if (kernel.dolly_session_restore(BigInt(bytes.byteLength)) !== 0) {
+      throw new Error("Dolly session filesystem restore failed; the saved copy is unchanged");
+    }
+  }
+  async function recoverFiles({ supervisor, stage, files }) {
+    const path = "/tmp/dolly-session-recovery.delta", destination = `/workspace/recovered-${recover}`;
+    stage(`recovering saved files into ${destination}...`);
+    files.write(path, new Uint8Array(bytes));
+    try {
+      const program = "/usr/bin/session-recover";
+      if ((await supervisor.spawn([program, path, destination])).status !== 0) {
+        throw new Error("File recovery failed; the original saved session is unchanged");
+      }
+    } finally { files.remove(path); }
+  }
+  return {
+    async imageRestored(context) {
+      const { kernel, image, stage } = context;
+      if (kernel.dolly_session_base_capture() !== 0) throw new Error("Dolly could not index the session baseline");
+      if (bytes === undefined) return;
+      if (recover !== undefined) {
+        if (image !== "system") throw new Error("invalid Dolly file recovery request");
+        await recoverFiles(context);
+      } else {
+        stage("restoring named session filesystem...");
+        restore(kernel);
+        stage("named session filesystem restored");
+      }
+      bytes.transfer(0);
+      bytes = undefined;
+    },
+    service() { kernel?.dolly_session_service(); },
+    messages: {
+      "snapshot-capture"({ name }) {
+        const controller = cancelled = new AbortController();
+        return transport.capture(name, { signal: controller.signal,
+          onChunk: chunk => ask({ type: "snapshot-chunk", bytes: chunk }, [chunk.buffer]) });
+      },
+      "snapshot-cancel"() { cancelled?.abort(); },
+    },
+    start({ kernel: exports, memory }) {
+      kernel = exports;
+      // The kernel serves the mailbox on a request, after each consumed chunk
+      // and on cancellation, in a task of its own.
+      transport = new SessionTransport(memory.buffer, Number(kernel.dolly_session_mailbox_address()),
+        Number(kernel.dolly_session_name_address()), Number(kernel.dolly_session_transfer_address()),
+        () => setTimeout(() => kernel?.dolly_session_service()));
+    },
+    dispose() { transport?.close(); },
+  };
+}

package/host/snapshot/transport.mjs

@@ -0,0 +1,132 @@
+import { DOLLY_SESSION_MAX_BYTES, validSessionName } from "../../src/session-store.mjs";
+import { DOLLY_ERRNO } from "./abi.mjs";
+import * as A from "./abi.mjs";
+
+// The mailbox words as dolly-snapshot-0.wat names them, the Worker's end. No
+// filesystem paths cross here. wake asks the kernel to serve the mailbox: on a
+// request, after each consumed chunk and on cancellation; the kernel never
+// waits for the page.
+export class SessionTransport {
+  static requestSequence = A.DOLLY_SESSION_WORD_REQUEST_SEQUENCE;
+  static completedSequence = A.DOLLY_SESSION_WORD_COMPLETED_SEQUENCE;
+  static status = A.DOLLY_SESSION_WORD_STATUS;
+  static nameLength = A.DOLLY_SESSION_WORD_NAME_LENGTH;
+  static chunkSequence = A.DOLLY_SESSION_WORD_CHUNK_SEQUENCE;
+  static chunkConsumedSequence = A.DOLLY_SESSION_WORD_CHUNK_CONSUMED_SEQUENCE;
+  static chunkLength = A.DOLLY_SESSION_WORD_CHUNK_LENGTH;
+  static chunkEof = A.DOLLY_SESSION_WORD_CHUNK_EOF;
+  static totalSizeLow = A.DOLLY_SESSION_WORD_TOTAL_SIZE_LOW;
+  static totalSizeHigh = A.DOLLY_SESSION_WORD_TOTAL_SIZE_HIGH;
+  static cancelledSequence = A.DOLLY_SESSION_WORD_CANCELLED_SEQUENCE;
+
+  constructor(buffer, address, nameAddress, transferAddress, wake) {
+    const range = (start, size) => Number.isSafeInteger(start) && start > 0 && start <= buffer.byteLength - size;
+    if (!(buffer instanceof SharedArrayBuffer) || !range(address, A.DOLLY_SESSION_HEADER_SIZE) || address % 4 ||
+        !range(nameAddress, A.DOLLY_SESSION_NAME_CAPACITY) || !range(transferAddress, A.DOLLY_SESSION_TRANSFER_CAPACITY)) {
+      throw new Error("Dolly supplied an invalid session mailbox");
+    }
+    this.bytes = new Uint8Array(buffer);
+    this.words = new Int32Array(buffer, address, A.DOLLY_SESSION_HEADER_SIZE / 4);
+    this.nameAddress = nameAddress;
+    this.nameCapacity = A.DOLLY_SESSION_NAME_CAPACITY;
+    this.transferAddress = transferAddress;
+    this.transferCapacity = A.DOLLY_SESSION_TRANSFER_CAPACITY;
+    this.wake = wake;
+    this.closed = false;
+    this.cancel = null;
+  }
+
+  async capture(name, { signal, timeoutMilliseconds = 30000, onChunk } = {}) {
+    if (!validSessionName(name)) throw new TypeError("invalid Dolly session name");
+    if (onChunk !== undefined && typeof onChunk !== "function") throw new TypeError("invalid session consumer");
+    signal?.throwIfAborted();
+    if (this.closed) throw new Error("Snapshot provider closed");
+    const words = this.words;
+    const published = Atomics.load(words, SessionTransport.requestSequence);
+    if (published !== Atomics.load(words, SessionTransport.completedSequence)) {
+      throw new Error("A Dolly session save is already active");
+    }
+    const requested = (published + 1) | 0;
+    let chunkSequence = Atomics.load(words, SessionTransport.chunkSequence);
+    let deadline = performance.now() + timeoutMilliseconds;
+    const wait = async (index, ready) => {
+      for (;;) {
+        signal?.throwIfAborted();
+        if (this.closed) throw new Error("Snapshot provider closed");
+        // Compare and wait on the SAME observation: a publication between
+        // these operations makes waitAsync return not-equal, never a lost wake.
+        const observed = Atomics.load(words, index);
+        if (ready(observed)) return observed;
+        if (performance.now() >= deadline) throw new Error("Session save timed out; try again");
+        if (index === SessionTransport.chunkSequence &&
+            Atomics.load(words, SessionTransport.completedSequence) === requested) {
+          throw new Error("Dolly stopped the session transfer before it completed");
+        }
+        const waiting = Atomics.waitAsync(words, index, observed, 1000);
+        if (waiting.async) await waiting.value;
+      }
+    };
+    const cancel = () => {
+      Atomics.store(words, SessionTransport.cancelledSequence, requested);
+      // Wake this capture's own waits, and the kernel.
+      Atomics.notify(words, SessionTransport.chunkSequence);
+      Atomics.notify(words, SessionTransport.completedSequence);
+      this.wake();
+    };
+    this.cancel = cancel;
+    signal?.addEventListener("abort", cancel, { once: true });
+    let complete = false;
+    try {
+      const nameBytes = new TextEncoder().encode(name);
+      this.bytes.fill(0, this.nameAddress, this.nameAddress + this.nameCapacity);
+      this.bytes.set(nameBytes, this.nameAddress);
+      Atomics.store(words, SessionTransport.nameLength, nameBytes.length);
+      Atomics.store(words, SessionTransport.requestSequence, requested);
+      this.wake();
+      let snapshot;
+      let offset = 0;
+      let declaredTotal;
+      for (;;) {
+        const chunk = await wait(SessionTransport.chunkSequence, (value) => value !== chunkSequence);
+        if (chunk !== ((chunkSequence + 1) | 0)) throw new Error("Dolly session chunk sequence skipped");
+        const length = Atomics.load(words, SessionTransport.chunkLength) >>> 0;
+        const eof = Atomics.load(words, SessionTransport.chunkEof);
+        const total = (Atomics.load(words, SessionTransport.totalSizeHigh) >>> 0) * 2 ** 32 +
+          (Atomics.load(words, SessionTransport.totalSizeLow) >>> 0);
+        if (!Number.isSafeInteger(total) || total > DOLLY_SESSION_MAX_BYTES ||
+            (total !== 0 && total < 16) || (declaredTotal !== undefined && declaredTotal !== total) ||
+            length > this.transferCapacity || length > total - offset ||
+            (eof !== 0 && eof !== 1) || (!eof && length === 0)) {
+          throw new Error("Dolly published an invalid session chunk");
+        }
+        if (declaredTotal === undefined) {
+          declaredTotal = total;
+          if (!onChunk) snapshot = new Uint8Array(total);
+        }
+        const bytes = this.bytes.subarray(this.transferAddress, this.transferAddress + length);
+        if (onChunk) await onChunk(bytes.slice());
+        else snapshot.set(bytes, offset);
+        offset += length;
+        Atomics.store(words, SessionTransport.chunkConsumedSequence, chunk);
+        this.wake();
+        chunkSequence = chunk;
+        deadline = performance.now() + timeoutMilliseconds;
+        if (eof) break;
+      }
+      await wait(SessionTransport.completedSequence, (value) => value === requested);
+      const status = Atomics.load(words, SessionTransport.status);
+      if (status === -DOLLY_ERRNO.EFBIG) {
+        throw new Error(`Dolly session exceeds its ${DOLLY_SESSION_MAX_BYTES / 1024 / 1024} MiB limit; remove files or installed packages and save again`);
+      }
+      if (status !== 0) throw new Error(`Dolly session capture failed with status ${status}`);
+      if (offset < 16 || offset !== declaredTotal) throw new Error("Dolly session snapshot was incomplete");
+      complete = true;
+      return onChunk ? offset : snapshot.buffer;
+    } finally {
+      if (!complete) cancel();
+      signal?.removeEventListener("abort", cancel);
+      this.cancel = null;
+    }
+  }
+  close() { this.closed = true; this.cancel?.(); }
+}