@volter/browser-wali 0.1.166 → 0.1.168

package/dist/filesystem-host-session.js

@@ -0,0 +1,951 @@
+import { releaseWaliSharedBuffers, markWaliSharedBufferWritten } from "./shared-buffer-pool.js";
+import { lowerTreeOf } from "./shared-file-layer.js";
+import { openPackReader } from "@volter/browser-runtime/browser-pack-store.js";
+import { SnapshotWaliFileSystem } from "./snapshot-filesystem.js";
+import { WaliSharedPipeHost } from "./shared-pipes.js";
+import { WaliDescriptionRegistry, WaliProcessDescriptorTable } from "./descriptors.js";
+import { WaliFileDescriptorTable } from "./filesystem.js";
+import { applyProcessFilesystemPatch, createProcessFilesystemPatch } from "./process-bridge.js";
+import { BrowserFileLockClient } from "@volter/browser-runtime/browser-file-locks.js";
+import { BrowserFileCoherenceClient } from "@volter/browser-runtime/browser-file-coherence.js";
+import { WaliCoherentFileLockClient } from "./coherent-file-locks.js";
+import { encodeBase64, decodeBase64 } from "@volter/browser-runtime/browser-base64.js";
+import { currentEntry } from "@volter/browser-runtime/browser-process-filesystem.js";
+import { FILESYSTEM_SNAPSHOT_CHUNK_BYTES, FilesystemOperation, } from "./filesystem-protocol.js";
+import { openLayerStores } from "./layer-stores.js";
+/** Process-tree filesystem state, multiplexed in the kernel worker or held locally. */
+export function createWaliFilesystemHost() {
+    let retired = false;
+    const cleanup = new Set();
+    let filesystem = new SnapshotWaliFileSystem();
+    let store;
+    let descriptors;
+    let sharedPipes;
+    let rootMemory;
+    const processes = new Map();
+    let nextProcess = 1;
+    let finalizeUpdates;
+    let prepareSpawn;
+    let importPeerPatch;
+    const encoder = new TextEncoder();
+    const decoder = new TextDecoder();
+    /**
+     * ON THE PROGRAM'S MAIN THREAD (ADR-0046). The host answers the main thread's
+     * own requests as calls and every other channel's when the main thread enters
+     * the host (`pumpHost`); its event loop does not run while the program does,
+     * so what it did on messages and timers it does there too: the page's imports
+     * arrive in a shared mailbox, and the program's changes go to the page when
+     * it blocks (before its output, too: `prepareSpawn`). Not on a timer: a file
+     * being written is published whole, and publishing every few milliseconds
+     * copied a `.blend` Blender was still writing again and again (2026-09-27:
+     * a 2 MB save went from 11 ms to 27-38).
+     */
+    let inThread = false;
+    /** Rung by every request on a channel, and by the page when it fills the mailbox: [0] counts the rings. */
+    let doorbell;
+    let doorbellSeen = 0;
+    /** Every channel attached, for the main thread to answer. */
+    const channels = new Set();
+    /** Requests a blocking lock left unanswered, asked again at every pump. */
+    const deferred = new Set();
+    /** [0] 1 when an import waits, [1] its length; its JSON after 8 bytes. Growable. */
+    let mailbox;
+    let publishUpdates;
+    let unpublishedSince = 0;
+    let pumping = false;
+    /** Set when the program starts: the port's imports were taken until then, the mailbox's after (ADR-0046). */
+    let portClosed = false;
+    let portTaken = 0;
+    let closePort;
+    /** The program's private trees, whose changes are not published (`privateRoots`). */
+    let privateRoots = [];
+    /** Set once the program's last changes have gone to the page: an import after that is the page's own. */
+    let hostFinalized = false;
+    const RETRY = Symbol("retry");
+    /** The program is about to run: the port is read no longer, and the page is told which import it took last. */
+    function closeHostPort() { closePort?.(); }
+    /** The host's run is over: nothing of it is held for the next (review of c96148c). */
+    function resetHost() {
+        retired = true;
+        for (const close of cleanup)
+            close();
+        cleanup.clear();
+        for (const id of [...processes.keys()])
+            releaseProcess(id);
+        descriptors?.descriptors.exit();
+        for (const entry of channels) {
+            entry.state.closed = true;
+            entry.port.onmessage = null;
+            entry.port.close();
+        }
+        store?.close();
+        store = undefined;
+        filesystem.setMutationHandler(() => { });
+        portClosed = false;
+        portTaken = 0;
+        closePort = undefined;
+        inThread = false;
+        doorbell = undefined;
+        channels.clear();
+        deferred.clear();
+        mailbox = undefined;
+        publishUpdates = undefined;
+        publishError = undefined;
+        unpublishedSince = 0;
+        hostFinalized = false;
+        filesystem = new SnapshotWaliFileSystem();
+        descriptors = undefined;
+        processes.clear();
+        rootMemory = undefined;
+        sharedPipes = undefined;
+        prepareSpawn = undefined;
+        finalizeUpdates = undefined;
+        importPeerPatch = () => { throw new Error("The WALI filesystem owner has ended."); };
+    }
+    /** The host runs on the calling realm's main thread from here on (ADR-0046); call before `initializeHost`. */
+    function hostInThread(bell) {
+        inThread = true;
+        doorbell = new Int32Array(bell);
+        doorbellSeen = Atomics.load(doorbell, 0);
+    }
+    /** The host's tree and descriptors for a run, in whichever realm runs it. */
+    async function initializeHost(data) {
+        const event = { data };
+        retired = false;
+        if (data.fileLocks)
+            cleanup.add(() => data.fileLocks.channel.port.close());
+        if (data.fileCoherence)
+            cleanup.add(() => data.fileCoherence.port.close());
+        channels.clear();
+        deferred.clear();
+        publishUpdates = undefined;
+        publishError = undefined;
+        mailbox = undefined;
+        unpublishedSince = 0;
+        hostFinalized = false;
+        portClosed = false;
+        portTaken = 0;
+        closePort = undefined;
+        privateRoots = (data.privateRoots ?? []).map(normalizeRoot);
+        {
+            finalizeUpdates = undefined;
+            prepareSpawn = undefined;
+            // Layers whose bytes are a store the host installed (ADR-0048), opened before the tree is made.
+            const layerStores = await openLayerStores(data.layers);
+            if (data.store) {
+                // The tree is read from the project's store, one file as the program opens it.
+                store = await openPackReader({ navigator: globalThis.navigator }, data.store.projectId);
+                if (!store)
+                    throw new Error("The project's store is not there to read.");
+                filesystem = SnapshotWaliFileSystem.fromStore(lowerTreeOf(store, data.layers, layerStores), data.snapshot);
+            }
+            else if (data.layers) {
+                filesystem = SnapshotWaliFileSystem.fromStore(lowerTreeOf(undefined, data.layers, layerStores), data.snapshot);
+            }
+            else {
+                filesystem = SnapshotWaliFileSystem.fromSnapshot(data.snapshot);
+            }
+            importPeerPatch = (patch, base) => applyProcessFilesystemPatch(filesystem, patch, base);
+            const lockClient = event.data.fileLocks
+                ? new BrowserFileLockClient(event.data.fileLocks.channel) : undefined;
+            sharedPipes = data.sharedPipes;
+            rootMemory = data.memory;
+            descriptors = new WaliFileDescriptorTable({
+                initializeStdio: true,
+                ...(sharedPipes ? { descriptors: new WaliProcessDescriptorTable(new WaliDescriptionRegistry(sharedPipes.descriptions), sharedPipes.table), descriptorState: sharedPipes } : {}),
+                filesystem,
+                ...(data.filesystemPolicy ? { filesystemPolicy: data.filesystemPolicy } : {}),
+                cwd: event.data.cwd,
+                stdin: new Uint8Array(),
+                executablePath: event.data.executablePath,
+                memory: () => event.data.memory,
+                emit: () => -9n,
+                descriptorMaximum: 19_999,
+                pid: event.data.pid,
+                // A declined offer is said once, where a worker's console goes (the page's devtools, a Node host's stderr).
+                ...(privateRoots.length ? { privateRoots, privateTreeAdoptable: () => processes.size === 0, onDiagnostic: (text) => console.warn(text) } : {}),
+                ...(lockClient && event.data.fileLocks ? {
+                    fileLocks: event.data.fileCoherence
+                        ? new WaliCoherentFileLockClient(lockClient, new BrowserFileCoherenceClient(event.data.fileCoherence), filesystem)
+                        : lockClient,
+                    lockOwner: event.data.fileLocks.owner,
+                } : {}),
+            });
+            if (event.data.updatePort) {
+                let updateTimer;
+                const updatePort = event.data.updatePort;
+                cleanup.add(() => {
+                    if (updateTimer !== undefined)
+                        clearTimeout(updateTimer);
+                    updatePort.onmessage = null;
+                    updatePort.close();
+                });
+                updatePort.start();
+                const locallyChangedPaths = new Set();
+                /**
+                 * THE PATHS THAT CHANGED, never a diff of two whole trees.
+                 *
+                 * This flush used to snapshot the entire filesystem twice and diff it,
+                 * to publish the two small files a directory-channel round trip writes.
+                 * The cost was proportional to everything the guest had EVER written,
+                 * so it grew with the session: measured 2026-09-19 against Blender's
+                 * real staged tree, 1.3 ms on a fresh session and ~1,500 ms forty-one
+                 * calls in, three times per host round trip. That WAS the WALI channel
+                 * floor. `takeChangedPaths()` states the same fact in the size of the
+                 * change instead of the size of the history.
+                 */
+                const flushUpdates = () => {
+                    if (updateTimer)
+                        clearTimeout(updateTimer);
+                    updateTimer = undefined;
+                    const paths = filesystem.takeChangedPaths();
+                    // A program's private trees are never the page's (privateRoots).
+                    if (privateRoots.length > 0)
+                        for (const path of paths)
+                            if (privateRoots.some((root) => underRoot(path, root)))
+                                paths.delete(path);
+                    if (paths.size === 0)
+                        return;
+                    for (const path of paths)
+                        locallyChangedPaths.add(path);
+                    const files = [];
+                    const removed = [];
+                    for (const path of paths) {
+                        // Raw bytes, transferred: base64 of every written file was most of
+                        // what publishing cost, on the program's own thread (ADR-0046).
+                        const entry = filesystem.writtenEntry(path, true);
+                        if (entry)
+                            files.push(entry);
+                        else
+                            removed.push(path);
+                    }
+                    if (files.length > 0 || removed.length > 0) {
+                        updatePort.postMessage({ type: "filesystem", patch: { files, removed } }, files.flatMap((entry) => entry.bytes ? [entry.bytes.buffer] : []));
+                        unacknowledged = true;
+                    }
+                };
+                // Patches posted since the page last acknowledged a checkpoint. With
+                // none, the page has committed every write and a checkpoint proves
+                // nothing, so the call returns at once: a process's output asks this
+                // before each write (`WaliSharedFileDescriptorHost`), not only a spawn.
+                let unacknowledged = false;
+                prepareSpawn = () => {
+                    flushUpdates();
+                    if (!unacknowledged)
+                        return;
+                    // Spawn and output use other MessagePorts. Acknowledgement on the
+                    // ordered update channel proves the page committed these writes first.
+                    const control = new Int32Array(new SharedArrayBuffer(4));
+                    updatePort.postMessage({ type: "checkpoint", control: control.buffer });
+                    Atomics.wait(control, 0, 0, 30_000);
+                    if (Atomics.load(control, 0) !== 1)
+                        throw new Error("WALI filesystem spawn checkpoint failed.");
+                    unacknowledged = false;
+                };
+                let importing = false;
+                let finalized = false;
+                finalizeUpdates = () => {
+                    if (finalized)
+                        return;
+                    flushUpdates();
+                    unpublishedSince = 0;
+                    finalized = true;
+                    hostFinalized = true;
+                    // All guest mutations precede this marker on the same channel.
+                    // Imports arriving after the cutoff remain the host's own state.
+                    updatePort.postMessage({ type: "finalized" });
+                };
+                importPeerPatch = (patch, base) => {
+                    if (finalized)
+                        throw new Error("The WALI filesystem is finalized.");
+                    // Child waits and page imports use the same atomic peer path. Replaying
+                    // them as per-file writes changes timestamps and echoes peer changes.
+                    flushUpdates();
+                    importing = true;
+                    try {
+                        // Opening the shared store can observe a newer file than the page's
+                        // snapshot. That cached state is not a competing guest write. For
+                        // untouched paths the host update is authoritative; paths changed
+                        // by the guest retain the supplied base and its conflict checks.
+                        let expected = base;
+                        if (base) {
+                            const entries = new Map(base.files.map(entry => [entry.path, entry]));
+                            for (const path of [...patch.files.map(entry => entry.path), ...patch.removed]) {
+                                if (locallyChangedPaths.has(path))
+                                    continue;
+                                const entry = currentEntry(filesystem, path);
+                                if (entry)
+                                    entries.set(path, entry);
+                                else
+                                    entries.delete(path);
+                            }
+                            expected = { files: [...entries.values()] };
+                        }
+                        applyProcessFilesystemPatch(filesystem, patch, expected);
+                        // THE PEER'S OWN CHANGES ARE NOT NEWS TO THE PEER. Applying the
+                        // patch marked every path in it; draining without publishing is
+                        // what stops this channel echoing the page's writes back at it.
+                        filesystem.takeChangedPaths();
+                        updatePort.postMessage({ type: "imported", patch });
+                    }
+                    finally {
+                        importing = false;
+                    }
+                };
+                if (inThread) {
+                    publishUpdates = flushUpdates;
+                    closePort = () => { portClosed = true; updatePort.postMessage({ type: "port-closed", taken: portTaken }); };
+                    // Growable: the page grows it to fit an import (the lib types predate growable SharedArrayBuffers).
+                    const buffer = new SharedArrayBuffer(1 << 20, { maxByteLength: 1 << 30 });
+                    mailbox = { control: new Int32Array(buffer, 0, 2), buffer };
+                    updatePort.postMessage({ type: "mailbox", buffer, doorbell: doorbell.buffer });
+                    publishError = (error) => updatePort.postMessage({ type: "import-error", message: error instanceof Error ? error.message : String(error) });
+                }
+                updatePort.onmessage = (event) => {
+                    if (event.data.type !== "import" || finalized || portClosed)
+                        return;
+                    portTaken = event.data.sequence ?? portTaken;
+                    try {
+                        importPeerPatch(event.data.patch, event.data.base);
+                    }
+                    catch (error) {
+                        updatePort.postMessage({ type: "import-error", message: error instanceof Error ? error.message : String(error) });
+                    }
+                };
+                // ONE TASK, NOT A WINDOW. `takeChangedPaths` made a flush cost the size
+                // of the change rather than the size of the session's history, so this
+                // wait stopped being a batching window and became pure answer latency:
+                // it was 100 ms, and `print(1)` through the editor's door measured
+                // 230 ms against the standalone skew's 51.
+                //
+                // IT WAS NOT SAFE TO DROP UNTIL THE CHANNEL HAD ONE WRITER, and that is
+                // why this is a comment and not a bare zero. At one-task cadence the
+                // directory channel used to die on `assertPatchBase` -- "write conflict
+                // at /work/.vgai-session/out/<n>.done" -- because the page's poll loop
+                // unlinked four files in the GUEST's own directory after every answer
+                // and `pending.filesystemBase` does not carry those deletions until the
+                // guest acknowledges an import that may be queued behind another. The
+                // 100 ms only made that window almost always empty (call 1 of 10
+                // survived at 0 ms). The fix was the protocol's, not this line's: the
+                // session owns `out/` and `ask/`, the page owns `in/` and `reply/`, and
+                // no path is named by patches from both sides, so the window has
+                // nothing left to lose. `setTimeout(_, 0)` still coalesces everything a
+                // single guest syscall batch mutates.
+                filesystem.setMutationHandler(() => {
+                    if (importing || finalized)
+                        return;
+                    if (inThread) {
+                        if (unpublishedSince === 0)
+                            unpublishedSince = performance.now();
+                        return;
+                    }
+                    updateTimer ??= setTimeout(flushUpdates, 0);
+                });
+            }
+        }
+    }
+    function attachChannel(channel) {
+        const control = new Int32Array(channel.control);
+        const payload = new Uint8Array(channel.payload);
+        const state = { process: channel.process ?? 0,
+            ...(channel.bufferLease ? { bufferLease: channel.bufferLease } : {}) };
+        const entry = { control, payload, state, port: channel.port };
+        const retireChannel = () => {
+            channel.releasePort?.close();
+            releaseWaliSharedBuffers(channel.bufferLease);
+        };
+        cleanup.add(retireChannel);
+        channels.add(entry);
+        if (channel.releasePort) {
+            const port = channel.releasePort;
+            port.onmessage = () => {
+                releaseProcess(state.process);
+                cleanup.delete(retireChannel);
+                port.postMessage(true);
+                port.close();
+                releaseWaliSharedBuffers(channel.bufferLease);
+            };
+            port.start();
+        }
+        if (channel.descriptorLimits) {
+            const table = state.process === 0 ? rootDescriptors()?.descriptors : processes.get(state.process).descriptors.descriptors;
+            table?.attachDescriptorLimits(channel.descriptorLimits);
+        }
+        if (state.process !== 0 && channel.sharedPipes) {
+            const table = processes.get(state.process).descriptors.descriptors;
+            table.attachSharedEntries(channel.sharedPipes.table, channel.bufferLease);
+        }
+        channel.port.onmessage = (event) => {
+            if (!channels.has(entry))
+                return;
+            if (typeof event.data !== "number" && "kind" in event.data) {
+                attachChannel({ ...event.data, process: event.data.process ?? state.process });
+                return;
+            }
+            if (typeof event.data !== "number") {
+                const process = processes.get(state.process);
+                if (!process)
+                    throw new Error("Unknown inherited descriptor table");
+                process.memory = event.data.memory;
+                return;
+            }
+            void dispatch(control, payload, state, event.data);
+        };
+        channel.port.start();
+        return entry;
+    }
+    /** Close ownership, including descriptor caches that capture the process. */
+    function releaseProcess(id) {
+        const process = processes.get(id);
+        try {
+            process?.descriptors.descriptors.exit();
+        }
+        finally {
+            // A copied table's memory getter closes over this object. Deleting only
+            // the map entry left the child memory alive through ChannelState.handlers.
+            if (process)
+                delete process.memory;
+            processes.delete(id);
+            for (const entry of channels) {
+                if (entry.state.process !== id)
+                    continue;
+                entry.state.closed = true;
+                delete entry.state.handlers;
+                delete entry.state.direct;
+                deferred.delete(entry);
+                channels.delete(entry);
+                entry.port.onmessage = null;
+                entry.port.close();
+            }
+        }
+    }
+    async function dispatch(control, payload, state, requestId) {
+        if (retired || state.closed || Atomics.load(control, 0) !== requestId)
+            return;
+        let result = -38;
+        let output = new Uint8Array();
+        // CloseProcess retires this channel synchronously, but its caller still
+        // needs this final answer before the producer/reap release handshake.
+        let replyingToClose = false;
+        try {
+            const operation = Atomics.load(control, 1);
+            replyingToClose = operation === FilesystemOperation.CloseProcess;
+            if (operation === FilesystemOperation.SyscallBinary) {
+                const pending = binarySyscall(payload, state);
+                if (pending === RETRY)
+                    return;
+                // Converted before the answer is claimed: a throw after the claim would leave the caller waiting.
+                const value = BigInt(pending instanceof Promise ? await pending : pending);
+                // As below: a stale completion never writes over a later request.
+                if (retired || (state.closed && !replyingToClose) || Atomics.compareExchange(control, 0, requestId, -requestId) !== requestId)
+                    return;
+                markWaliSharedBufferWritten(state.bufferLease, 1, 8);
+                (state.view ??= new DataView(payload.buffer, payload.byteOffset, payload.byteLength)).setBigInt64(0, value, true);
+                Atomics.store(control, 2, 0);
+                Atomics.store(control, 4, 8);
+                Atomics.store(control, 0, requestId + 1);
+                Atomics.notify(control, 0);
+                return;
+            }
+            const mapped = mappingOperation(operation, payload, state);
+            if (mapped) {
+                if (mapped.output.byteLength > payload.byteLength)
+                    throw Object.assign(new Error("EMSGSIZE"), { code: "EMSGSIZE" });
+                if (retired || (state.closed && !replyingToClose) || Atomics.compareExchange(control, 0, requestId, -requestId) !== requestId)
+                    return;
+                markWaliSharedBufferWritten(state.bufferLease, 1, mapped.output.byteLength);
+                payload.set(mapped.output);
+                Atomics.store(control, 2, mapped.result);
+                Atomics.store(control, 4, mapped.output.byteLength);
+                Atomics.store(control, 0, requestId + 1);
+                Atomics.notify(control, 0);
+                return;
+            }
+            const inputLength = Atomics.load(control, 3);
+            const input = inputLength > 0
+                ? JSON.parse(decoder.decode(payload.slice(0, inputLength)))
+                : {};
+            const pending = operate(operation, input, state);
+            if (pending === RETRY)
+                return;
+            const response = pending instanceof Promise ? await pending : pending;
+            output = response === undefined ? new Uint8Array() : encoder.encode(JSON.stringify(response));
+            result = 0;
+        }
+        catch (error) {
+            result = negativeErrno(error);
+        }
+        if (output.byteLength > payload.byteLength) {
+            result = -90;
+            output = new Uint8Array();
+        }
+        // A timed-out caller may already have cancelled this generation and begun a
+        // later request. Never let a stale completion overwrite its response.
+        if (retired || (state.closed && !replyingToClose) || Atomics.compareExchange(control, 0, requestId, -requestId) !== requestId)
+            return;
+        if (output.byteLength > 0) {
+            markWaliSharedBufferWritten(state.bufferLease, 1, output.byteLength);
+            payload.set(output);
+        }
+        Atomics.store(control, 2, result);
+        Atomics.store(control, 4, output.byteLength);
+        Atomics.store(control, 0, requestId + 1);
+        Atomics.notify(control, 0);
+    }
+    function rootDescriptors() { return descriptors; }
+    function operate(operation, input, state) {
+        const descriptors = state.process === 0 ? rootDescriptors() : processes.get(state.process)?.descriptors;
+        if (operation === FilesystemOperation.GetCwd)
+            return descriptors?.currentWorkingDirectory();
+        if (operation === FilesystemOperation.CopyForExec || operation === FilesystemOperation.CopyForFork) {
+            if (!descriptors)
+                throw new Error("Missing parent descriptor table");
+            const process = {
+                descriptors: descriptors[operation === FilesystemOperation.CopyForFork ? "copyForFork" : "copyForExec"](() => {
+                    if (!process.memory)
+                        throw new Error("Child memory is not attached");
+                    return process.memory;
+                }, Array.isArray(input.stdio) ? input.stdio.map(requiredNumber) : undefined),
+            };
+            const id = nextProcess++;
+            processes.set(id, process);
+            // The child's cwd and umask are the parent's at the copy; they ride this
+            // answer rather than round trips of their own on every fork.
+            return { process: id, cwd: descriptors.currentWorkingDirectory(), umask: descriptors.creationMask() };
+        }
+        if (operation === FilesystemOperation.CloseProcess) {
+            if (state.process !== 0)
+                releaseProcess(state.process);
+            else
+                descriptors?.descriptors.exit();
+            return;
+        }
+        const path = () => requiredString(input.path);
+        if (operation === FilesystemOperation.PrepareSpawn) {
+            prepareSpawn?.();
+            return;
+        }
+        if (operation === FilesystemOperation.ImportPeerPatch) {
+            importPeerPatch(input.patch);
+            return;
+        }
+        if (operation === FilesystemOperation.Exists)
+            return filesystem.existsSync(path());
+        if (operation === FilesystemOperation.Stat || operation === FilesystemOperation.Lstat) {
+            const stat = operation === FilesystemOperation.Lstat ? filesystem.lstatSync(path()) : filesystem.statSync(path());
+            return {
+                file: stat.isFile(), directory: stat.isDirectory(), symbolicLink: stat.isSymbolicLink?.(),
+                size: stat.size, mode: stat.mode,
+                mtimeMs: stat.mtimeMs, atimeMs: stat.atimeMs, ctimeMs: stat.ctimeMs, nlink: stat.nlink,
+                uid: stat.uid, gid: stat.gid, dev: stat.dev, ino: stat.ino, rdev: stat.rdev,
+                blksize: stat.blksize, blocks: stat.blocks,
+            };
+        }
+        if (operation === FilesystemOperation.ReadFile)
+            return { content: encodeBase64(filesystem.readFileSync(path())) };
+        if (operation === FilesystemOperation.WriteFile) {
+            filesystem.writeFileSync(path(), decodeBase64(requiredString(input.content)));
+            return;
+        }
+        if (operation === FilesystemOperation.ReadRange) {
+            const offset = requiredNumber(input.offset);
+            const length = requiredNumber(input.length);
+            const bytes = filesystem.readRangeSync
+                ? filesystem.readRangeSync(path(), offset, length)
+                : filesystem.readFileSync(path()).subarray(offset, offset + length);
+            return { content: encodeBase64(bytes) };
+        }
+        if (operation === FilesystemOperation.WriteRange) {
+            const offset = requiredNumber(input.offset);
+            const bytes = decodeBase64(requiredString(input.content));
+            if (filesystem.writeRangeSync)
+                filesystem.writeRangeSync(path(), offset, bytes);
+            else {
+                const current = filesystem.existsSync(path()) ? filesystem.readFileSync(path()) : new Uint8Array();
+                const next = new Uint8Array(Math.max(current.byteLength, offset + bytes.byteLength));
+                next.set(current);
+                next.set(bytes, offset);
+                filesystem.writeFileSync(path(), next);
+            }
+            return;
+        }
+        if (operation === FilesystemOperation.Mkdir) {
+            filesystem.mkdirSync(path(), { recursive: input.recursive === true });
+            return;
+        }
+        if (operation === FilesystemOperation.Readdir)
+            return filesystem.readdirSync(path());
+        if (operation === FilesystemOperation.Unlink) {
+            filesystem.unlinkSync(path());
+            return;
+        }
+        if (operation === FilesystemOperation.Rmdir) {
+            filesystem.rmdirSync(path());
+            return;
+        }
+        if (operation === FilesystemOperation.Rename) {
+            filesystem.renameSync(requiredString(input.from), requiredString(input.to));
+            return;
+        }
+        if (operation === FilesystemOperation.Snapshot)
+            return filesystem.toSnapshot();
+        if (operation === FilesystemOperation.SnapshotSize || operation === FilesystemOperation.FinalSnapshotSize) {
+            if (operation === FilesystemOperation.FinalSnapshotSize)
+                finalizeUpdates?.();
+            state.snapshot = encoder.encode(JSON.stringify(filesystem.toSnapshot()));
+            return { length: state.snapshot.byteLength };
+        }
+        if (operation === FilesystemOperation.SnapshotChunk) {
+            const offset = requiredNumber(input.offset);
+            const length = requiredNumber(input.length);
+            if (!state.snapshot || offset < 0 || length < 0 || length > FILESYSTEM_SNAPSHOT_CHUNK_BYTES
+                || offset + length > state.snapshot.byteLength) {
+                throw Object.assign(new Error("EINVAL"), { code: "EINVAL" });
+            }
+            const content = encodeBase64(state.snapshot.subarray(offset, offset + length));
+            if (offset + length === state.snapshot.byteLength)
+                delete state.snapshot;
+            return { content };
+        }
+        if (operation === FilesystemOperation.ReplaceSnapshot) {
+            filesystem.replaceSnapshot(input.snapshot);
+            return;
+        }
+        if (operation === FilesystemOperation.ReplaceSnapshotStart || operation === FilesystemOperation.ImportPeerPatchStart) {
+            const length = requiredNumber(input.length);
+            if (length <= 0 || length > 256 * 1024 * 1024) {
+                throw Object.assign(new Error("EINVAL"), { code: "EINVAL" });
+            }
+            state.replacement = { bytes: new Uint8Array(length), offset: 0, peerPatch: operation === FilesystemOperation.ImportPeerPatchStart };
+            return;
+        }
+        if (operation === FilesystemOperation.ReplaceSnapshotChunk || operation === FilesystemOperation.ImportPeerPatchChunk) {
+            const offset = requiredNumber(input.offset);
+            const chunk = decodeBase64(requiredString(input.content));
+            const replacement = state.replacement;
+            if (!replacement || replacement.peerPatch !== (operation === FilesystemOperation.ImportPeerPatchChunk)
+                || offset !== replacement.offset || chunk.byteLength > FILESYSTEM_SNAPSHOT_CHUNK_BYTES
+                || offset + chunk.byteLength > replacement.bytes.byteLength) {
+                throw Object.assign(new Error("EINVAL"), { code: "EINVAL" });
+            }
+            replacement.bytes.set(chunk, offset);
+            replacement.offset += chunk.byteLength;
+            if (replacement.offset === replacement.bytes.byteLength) {
+                delete state.replacement;
+                const value = JSON.parse(decoder.decode(replacement.bytes));
+                if (replacement.peerPatch)
+                    importPeerPatch(value);
+                else
+                    filesystem.replaceSnapshot(value);
+            }
+            return;
+        }
+        if (operation === FilesystemOperation.Syscall) {
+            if (!descriptors)
+                throw Object.assign(new Error("EIO"), { code: "EIO" });
+            const name = requiredString(input.name);
+            const handler = syscallHandlers(state, descriptors)[name];
+            if (!handler)
+                throw Object.assign(new Error("ENOSYS"), { code: "ENOSYS" });
+            const args = Array.isArray(input.args) ? input.args.map((value) => BigInt(requiredString(value))) : [];
+            const result = invokeSyscall(name, handler, args);
+            if (result === RETRY)
+                return RETRY;
+            return result instanceof Promise ? result.then((value) => ({ result: String(value) })) : { result: String(result) };
+        }
+        if (operation === FilesystemOperation.ReadForMapping) {
+            if (!descriptors)
+                throw Object.assign(new Error("EIO"), { code: "EIO" });
+            const value = descriptors.readForMapping(requiredNumber(input.fd), requiredNumber(input.offset), requiredNumber(input.length));
+            return value ? { content: encodeBase64(value) } : {};
+        }
+        if (operation === FilesystemOperation.MappingPath) {
+            if (!descriptors)
+                throw Object.assign(new Error("EIO"), { code: "EIO" });
+            const value = descriptors.mappingPath(requiredNumber(input.fd));
+            return value ? { path: value } : {};
+        }
+        if (operation === FilesystemOperation.WriteForMapping) {
+            if (!descriptors)
+                throw Object.assign(new Error("EIO"), { code: "EIO" });
+            return { written: descriptors.writeForMapping(requiredString(input.path), requiredNumber(input.offset), decodeBase64(requiredString(input.content))) };
+        }
+        throw Object.assign(new Error("ENOSYS"), { code: "ENOSYS" });
+    }
+    /** The channel's syscall handlers, made once for its process's descriptor table (see `ChannelState.handlers`). */
+    function syscallHandlers(state, descriptors) {
+        const table = descriptors.descriptors;
+        const held = state.handlers;
+        if (held && held.table === descriptors && held.entries === table.sharedEntries.buffer)
+            return held.imports;
+        const pipeHost = sharedPipes && new WaliSharedPipeHost(() => {
+            const memory = state.process === 0 ? rootMemory : processes.get(state.process)?.memory;
+            if (!memory)
+                throw new Error("The WALI filesystem process has no memory.");
+            return memory;
+        }, { ...sharedPipes, table: table.sharedEntries.buffer }, table);
+        const imports = pipeHost ? pipeHost.imports(descriptors.imports()) : descriptors.imports();
+        state.handlers = { table: descriptors, entries: table.sharedEntries.buffer, imports };
+        return imports;
+    }
+    /** A `SyscallBinary` request's result (see its layout in `filesystem-protocol.ts`). */
+    function binarySyscall(payload, state) {
+        const descriptors = state.process === 0 ? rootDescriptors() : processes.get(state.process)?.descriptors;
+        if (!descriptors)
+            throw Object.assign(new Error("EIO"), { code: "EIO" });
+        const view = state.view ??= new DataView(payload.buffer, payload.byteOffset, payload.byteLength);
+        const count = payload[0];
+        const name = decoder.decode(payload.slice(8 + count * 8, 8 + count * 8 + payload[1]));
+        const args = [];
+        for (let index = 0; index < count; index += 1)
+            args.push(view.getBigInt64(8 + index * 8, true));
+        const handler = syscallHandlers(state, descriptors)[name];
+        if (!handler)
+            throw Object.assign(new Error("ENOSYS"), { code: "ENOSYS" });
+        return invokeSyscall(name, handler, args);
+    }
+    /** Synchronous, except a blocking advisory lock, which is retried without blocking this worker. */
+    function invokeSyscall(name, handler, args) {
+        let nonblockingArgs;
+        if (name === "SYS_flock") {
+            const operation = Number(args[1] ?? 0);
+            if ((operation & 4) === 0 && (operation & 8) === 0) {
+                nonblockingArgs = [...args];
+                nonblockingArgs[1] = BigInt(operation | 4);
+            }
+        }
+        else if (name === "SYS_fcntl") {
+            const command = Number(args[1] ?? 0);
+            if (command === 7 || command === 38) {
+                nonblockingArgs = [...args];
+                nonblockingArgs[1] = BigInt(command === 7 ? 6 : 37);
+            }
+        }
+        if (!nonblockingArgs)
+            return handler(...args) ?? 0;
+        if (inThread) {
+            // On the main thread a lock that would block is not waited for here: its
+            // holder may be the main thread itself. The request stays unanswered and
+            // is asked again at the next pump.
+            const result = handler(...nonblockingArgs) ?? 0;
+            return BigInt(result) === -11n ? RETRY : result;
+        }
+        return blockingLock(handler, nonblockingArgs);
+    }
+    async function blockingLock(handler, nonblockingArgs) {
+        for (;;) {
+            if (retired)
+                return -9;
+            const result = handler(...nonblockingArgs) ?? 0;
+            if (BigInt(result) !== -11n)
+                return result;
+            // A blocking advisory lock must not block this worker: it owns the shared
+            // descriptor table for every pthread, including the holder that must
+            // write and unlock the file. Yield between nonblocking attempts so those
+            // syscalls can make progress on their own per-thread RPC channels.
+            await new Promise((resolve) => setTimeout(resolve, 5));
+        }
+    }
+    function requiredString(value) {
+        if (typeof value !== "string")
+            throw Object.assign(new Error("EINVAL"), { code: "EINVAL" });
+        return value;
+    }
+    function requiredNumber(value) {
+        if (typeof value !== "number" || !Number.isSafeInteger(value))
+            throw Object.assign(new Error("EINVAL"), { code: "EINVAL" });
+        return value;
+    }
+    function negativeErrno(error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const name = typeof error === "object" && error !== null && "code" in error ? String(error.code)
+            : /\b(E[A-Z]+)\b/u.exec(message)?.[1] ?? "EIO";
+        return -({ ENOENT: 2, EBADF: 9, EACCES: 13, EEXIST: 17, ENOTDIR: 20, EISDIR: 21,
+            EINVAL: 22, EMFILE: 24, ENOSPC: 28, ESPIPE: 29, ERANGE: 34, ENOSYS: 38,
+            ENOTEMPTY: 39, EMSGSIZE: 90 }[name] ?? 5);
+    }
+    /**
+     * One channel's waiting request, answered now on this thread (ADR-0046). A
+     * request whose blocking lock is held is left waiting and asked again later.
+     * Answers exactly as `dispatch` does.
+     */
+    function serveNow(entry) {
+        const { control, payload, state } = entry;
+        const requestId = Atomics.load(control, 0);
+        if (requestId <= 0 || (requestId & 1) === 0)
+            return false;
+        let result = -38;
+        let output = new Uint8Array();
+        let binary;
+        let mapped;
+        try {
+            const operation = Atomics.load(control, 1);
+            if (operation === FilesystemOperation.SyscallBinary) {
+                const value = binarySyscall(payload, state);
+                if (value === RETRY) {
+                    deferred.add(entry);
+                    return false;
+                }
+                if (value instanceof Promise)
+                    throw new Error("EIO: an asynchronous syscall on the main thread");
+                binary = BigInt(value);
+            }
+            else if ((mapped = mappingOperation(operation, payload, state)) !== undefined) {
+                output = mapped.output;
+            }
+            else {
+                const inputLength = Atomics.load(control, 3);
+                const input = inputLength > 0 ? JSON.parse(decoder.decode(payload.slice(0, inputLength))) : {};
+                const response = operate(operation, input, state);
+                if (response === RETRY) {
+                    deferred.add(entry);
+                    return false;
+                }
+                if (response instanceof Promise)
+                    throw new Error("EIO: an asynchronous operation on the main thread");
+                output = response === undefined ? new Uint8Array() : encoder.encode(JSON.stringify(response));
+            }
+            result = mapped?.result ?? 0;
+        }
+        catch (error) {
+            result = negativeErrno(error);
+            binary = undefined;
+        }
+        deferred.delete(entry);
+        if (output.byteLength > payload.byteLength) {
+            result = -90;
+            output = new Uint8Array();
+        }
+        if (Atomics.compareExchange(control, 0, requestId, -requestId) !== requestId)
+            return true;
+        if (binary !== undefined) {
+            markWaliSharedBufferWritten(state.bufferLease, 1, 8);
+            (state.view ??= new DataView(payload.buffer, payload.byteOffset, payload.byteLength)).setBigInt64(0, binary, true);
+            output = new Uint8Array(8);
+        }
+        else if (output.byteLength > 0) {
+            markWaliSharedBufferWritten(state.bufferLease, 1, output.byteLength);
+            payload.set(output);
+        }
+        Atomics.store(control, 2, result);
+        Atomics.store(control, 4, binary !== undefined ? 8 : output.byteLength);
+        Atomics.store(control, 0, requestId + 1);
+        Atomics.notify(control, 0);
+        return true;
+    }
+    /** Whether a pump has anything to do: a ring or a deferred lock. */
+    function hostWaiting() {
+        if (!inThread)
+            return false;
+        return Atomics.load(doorbell, 0) !== doorbellSeen || deferred.size > 0;
+    }
+    /**
+     * What the main thread owes while it is in the host (ADR-0046): the page's
+     * import, every other channel's waiting request, and, when it is about to
+     * block or has not published for a while, its changes to the page.
+     */
+    function pumpHost(blocking = false) {
+        if (!inThread || pumping)
+            return;
+        pumping = true;
+        try {
+            doorbellSeen = Atomics.load(doorbell, 0);
+            if (mailbox && !hostFinalized && Atomics.load(mailbox.control, 0) === 1) {
+                // Never thrown out of a pump: every wait of this thread pumps, and one
+                // that swallowed the error would spin (review of 31309ca).
+                try {
+                    const length = Atomics.load(mailbox.control, 1);
+                    const message = JSON.parse(decoder.decode(new Uint8Array(mailbox.buffer, 8, length).slice()));
+                    Atomics.store(mailbox.control, 0, 0);
+                    if (message.type === "import")
+                        importPeerPatch(message.patch, message.base);
+                }
+                catch (error) {
+                    Atomics.store(mailbox.control, 0, 0);
+                    publishError?.(error);
+                }
+            }
+            for (const entry of channels)
+                serveNow(entry);
+            if (publishUpdates && unpublishedSince !== 0 && blocking) {
+                unpublishedSince = 0;
+                publishUpdates();
+            }
+        }
+        finally {
+            pumping = false;
+        }
+    }
+    let publishError;
+    /** A raw mapping operation (`ReadForMappingBinary`, `WriteForMappingBinary`): its result and the bytes it answers. */
+    function mappingOperation(operation, payload, state) {
+        if (operation !== FilesystemOperation.ReadForMappingBinary && operation !== FilesystemOperation.WriteForMappingBinary)
+            return undefined;
+        const descriptors = state.process === 0 ? rootDescriptors() : processes.get(state.process)?.descriptors;
+        if (!descriptors)
+            throw Object.assign(new Error("EIO"), { code: "EIO" });
+        const view = state.view ??= new DataView(payload.buffer, payload.byteOffset, payload.byteLength);
+        if (operation === FilesystemOperation.ReadForMappingBinary) {
+            const length = Math.min(view.getInt32(16, true), payload.byteLength);
+            const value = descriptors.readForMapping(view.getInt32(0, true), view.getFloat64(8, true), length);
+            return value ? { result: 0, output: value } : { result: 1, output: new Uint8Array() };
+        }
+        const pathLength = view.getUint32(8, true);
+        const valueLength = view.getUint32(12, true);
+        const path = decoder.decode(payload.slice(16, 16 + pathLength));
+        const written = descriptors.writeForMapping(path, view.getFloat64(0, true), payload.slice(16 + pathLength, 16 + pathLength + valueLength));
+        return { result: 0, output: new Uint8Array([written ? 1 : 0]) };
+    }
+    /** A root as a path, as runtime.ts makes it: absolute, no empty component, no trailing slash; "/" itself kept. */
+    function normalizeRoot(root) { return `/${root.split("/").filter(Boolean).join("/")}`; }
+    /** Whether `path` is `root` or lies below it. */
+    function underRoot(path, root) {
+        return root === "/" || path === root || path.startsWith(`${root}/`);
+    }
+    /**
+     * A syscall on the main thread's own channel, called (ADR-0046): the same
+     * handlers `SyscallBinary` reaches, with no payload encoded and decoded
+     * between the caller and them. Undefined while a held lock defers it.
+     */
+    function syscallNow(entry, name, args) {
+        try {
+            const state = entry.state;
+            const table = state.process === 0 ? rootDescriptors() : processes.get(state.process)?.descriptors;
+            if (!table)
+                throw Object.assign(new Error("EIO"), { code: "EIO" });
+            const handler = syscallHandlers(state, table)[name];
+            if (!handler)
+                throw Object.assign(new Error("ENOSYS"), { code: "ENOSYS" });
+            const result = invokeSyscall(name, handler, args);
+            if (result === RETRY)
+                return undefined;
+            if (result instanceof Promise)
+                throw new Error("EIO: an asynchronous syscall on the main thread");
+            return BigInt(result);
+        }
+        catch (error) {
+            // As a channel answers a throw: its errno, which the caller throws as it would the answer's.
+            return { failed: negativeErrno(error) };
+        }
+    }
+    /** The main thread's own channel's handlers, and the errno a throw from one answers (ADR-0046). */
+    function handlersNow(entry) {
+        const state = entry.state;
+        const table = state.process === 0 ? rootDescriptors() : processes.get(state.process)?.descriptors;
+        if (!table)
+            throw Object.assign(new Error("EIO"), { code: "EIO" });
+        // THE FILE TABLE'S OWN HANDLERS, made once per table: the caller is the
+        // main thread's router, which the runtime's pipe layer reaches only with a
+        // descriptor it found is not a pipe, so the host's pipe layer around these
+        // (`syscallHandlers`, for the other threads' requests) would ask again; and
+        // a new result object per call was the rest (2026-09-28).
+        const held = state.direct;
+        if (held && held.table === table)
+            return held.handlers;
+        const handlers = { imports: table.imports(), errno: negativeErrno, owns: (fd) => table.ownsFile(fd) };
+        state.direct = { table, handlers };
+        return handlers;
+    }
+    return { closeHostPort, resetHost, hostInThread, initializeHost, attachChannel, serveNow, hostWaiting, pumpHost, underRoot, syscallNow, handlersNow };
+}
+//# sourceMappingURL=filesystem-host-session.js.map