@secure-exec/core 0.1.1-rc.3 → 0.2.0-rc.2

package/dist/kernel/kernel.js

@@ -0,0 +1,1393 @@
+/**
+ * Kernel implementation.
+ *
+ * The kernel is the OS. It owns VFS, FD table, process table, device layer,
+ * pipe manager, command registry, and permissions. Runtimes are execution
+ * engines that make "syscalls" to the kernel.
+ */
+import { createDeviceLayer } from "./device-layer.js";
+import { createProcLayer } from "./proc-layer.js";
+import { FDTableManager } from "./fd-table.js";
+import { ProcessTable } from "./process-table.js";
+import { PipeManager } from "./pipe-manager.js";
+import { PtyManager } from "./pty.js";
+import { FileLockManager } from "./file-lock.js";
+import { CommandRegistry } from "./command-registry.js";
+import { wrapFileSystem, checkChildProcess } from "./permissions.js";
+import { UserManager } from "./user.js";
+import { SocketTable } from "./socket-table.js";
+import { TimerTable } from "./timer-table.js";
+import { InodeTable } from "./inode-table.js";
+import { InMemoryFileSystem } from "../shared/in-memory-fs.js";
+import { FILETYPE_REGULAR_FILE, SEEK_SET, SEEK_CUR, SEEK_END, O_APPEND, O_CREAT, O_EXCL, O_TRUNC, SIGTERM, SIGPIPE, SIGWINCH, F_DUPFD, F_GETFD, F_SETFD, F_GETFL, F_DUPFD_CLOEXEC, FD_CLOEXEC, KernelError, } from "./types.js";
+export function createKernel(options) {
+    return new KernelImpl(options);
+}
+class KernelImpl {
+    vfs;
+    rawInMemoryFs;
+    fdTableManager = new FDTableManager();
+    processTable = new ProcessTable();
+    pipeManager = new PipeManager();
+    ptyManager = new PtyManager((pgid, signal, excludeLeaders) => {
+        try {
+            if (excludeLeaders) {
+                return this.processTable.killGroupExcludeLeaders(pgid, signal);
+            }
+            this.processTable.kill(-pgid, signal);
+        }
+        catch { /* no-op if pgid gone */ }
+        return 0;
+    });
+    fileLockManager = new FileLockManager();
+    commandRegistry = new CommandRegistry();
+    socketTable;
+    timerTable;
+    inodeTable;
+    userManager;
+    drivers = [];
+    driverPids = new Map();
+    permissions;
+    maxProcesses;
+    env;
+    cwd;
+    disposed = false;
+    pendingBinEntries = [];
+    posixDirsReady;
+    constructor(options) {
+        this.inodeTable = new InodeTable();
+        if (options.filesystem instanceof InMemoryFileSystem) {
+            options.filesystem.setInodeTable(this.inodeTable);
+            this.rawInMemoryFs = options.filesystem;
+        }
+        // Apply pseudo-filesystems before permissions so dynamic entries are
+        // subject to the same policy as regular files.
+        let fs = createDeviceLayer(options.filesystem);
+        fs = createProcLayer(fs, {
+            processTable: this.processTable,
+            fdTableManager: this.fdTableManager,
+            hostname: options.env?.HOSTNAME,
+        });
+        // Apply permission wrapping
+        if (options.permissions) {
+            fs = wrapFileSystem(fs, options.permissions);
+        }
+        this.vfs = fs;
+        this.permissions = options.permissions;
+        this.maxProcesses = options.maxProcesses;
+        this.env = { ...options.env };
+        this.cwd = options.cwd ?? "/home/user";
+        this.userManager = new UserManager();
+        this.socketTable = new SocketTable({
+            vfs: this.vfs,
+            networkCheck: options.permissions?.network,
+            hostAdapter: options.hostNetworkAdapter,
+            getSignalState: (pid) => this.processTable.getSignalState(pid),
+            processExists: (pid) => this.processTable.get(pid) !== undefined,
+        });
+        this.timerTable = new TimerTable();
+        // Clean up FD table and sockets when a process exits
+        this.processTable.onProcessExit = (pid) => {
+            this.cleanupProcessFDs(pid);
+            this.socketTable.closeAllForProcess(pid);
+            this.timerTable.clearAllForProcess(pid);
+        };
+        // Clean up driver PID ownership when zombie is reaped
+        this.processTable.onProcessReap = (pid) => {
+            const entry = this.processTable.get(pid);
+            if (entry)
+                this.driverPids.get(entry.driver)?.delete(pid);
+        };
+        // Deliver SIGPIPE default action: terminate writer with 128+SIGPIPE
+        this.pipeManager.onBrokenPipe = (pid) => {
+            try {
+                this.processTable.kill(pid, SIGPIPE);
+            }
+            catch {
+                // Process may already be exited
+            }
+        };
+        // Create standard POSIX directory hierarchy so all programs see /tmp,
+        // /usr, /etc, etc. — matching a real Linux root filesystem layout.
+        this.posixDirsReady = this.initPosixDirs();
+    }
+    async initPosixDirs() {
+        const dirs = [
+            "/tmp",
+            "/bin",
+            "/lib",
+            "/sbin",
+            "/boot",
+            "/etc",
+            "/root",
+            "/run",
+            "/srv",
+            "/sys",
+            "/proc",
+            "/opt",
+            "/mnt",
+            "/media",
+            "/home",
+            "/usr",
+            "/usr/bin",
+            "/usr/games",
+            "/usr/include",
+            "/usr/lib",
+            "/usr/libexec",
+            "/usr/man",
+            "/usr/sbin",
+            "/usr/share",
+            "/usr/share/man",
+            "/var",
+            "/var/cache",
+            "/var/empty",
+            "/var/lib",
+            "/var/lock",
+            "/var/log",
+            "/var/run",
+            "/var/spool",
+            "/var/tmp",
+        ];
+        for (const dir of dirs) {
+            try {
+                await this.vfs.mkdir(dir, { recursive: true });
+            }
+            catch {
+                // Directory may already exist
+            }
+        }
+        // Standard utility that many scripts expect
+        try {
+            await this.vfs.writeFile("/usr/bin/env", new Uint8Array(1));
+        }
+        catch {
+            // File may already exist
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Kernel public API
+    // -----------------------------------------------------------------------
+    async mount(driver) {
+        this.assertNotDisposed();
+        await this.posixDirsReady;
+        // Track PIDs owned by this driver
+        if (!this.driverPids.has(driver.name)) {
+            this.driverPids.set(driver.name, new Set());
+        }
+        // Initialize the driver with a scoped kernel interface
+        await driver.init(this.createKernelInterface(driver.name));
+        // Register commands
+        this.commandRegistry.register(driver);
+        this.drivers.push(driver);
+        // Populate /bin stubs for shell PATH lookup
+        await this.commandRegistry.populateBin(this.vfs);
+    }
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        // Terminate all running processes
+        await this.processTable.terminateAll();
+        // Clean up all sockets
+        this.socketTable.disposeAll();
+        this.timerTable.disposeAll();
+        // Dispose all drivers (reverse mount order)
+        for (let i = this.drivers.length - 1; i >= 0; i--) {
+            try {
+                await this.drivers[i].dispose();
+            }
+            catch {
+                // Best effort cleanup
+            }
+        }
+        this.drivers.length = 0;
+    }
+    /**
+     * Flush pending /bin stub entries created by on-demand command discovery.
+     * Ensures VFS is consistent before shell PATH lookups.
+     */
+    async flushPendingBinEntries() {
+        if (this.pendingBinEntries.length > 0) {
+            await Promise.all(this.pendingBinEntries);
+            this.pendingBinEntries.length = 0;
+        }
+    }
+    async exec(command, options) {
+        this.assertNotDisposed();
+        // Flush pending /bin stubs before shell PATH lookup
+        await this.flushPendingBinEntries();
+        // Route through shell
+        const shell = this.commandRegistry.resolve("sh");
+        if (!shell) {
+            throw new Error("No shell available. Mount a WasmVM runtime to enable exec().");
+        }
+        const proc = this.spawnInternal("sh", ["-c", command], options);
+        // Write stdin if provided
+        if (options?.stdin) {
+            const data = typeof options.stdin === "string"
+                ? new TextEncoder().encode(options.stdin)
+                : options.stdin;
+            proc.writeStdin(data);
+            proc.closeStdin();
+        }
+        // Collect output
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        proc.onStdout = (data) => {
+            stdoutChunks.push(data);
+            options?.onStdout?.(data);
+        };
+        proc.onStderr = (data) => {
+            stderrChunks.push(data);
+            options?.onStderr?.(data);
+        };
+        // Wait with optional timeout
+        let exitCode;
+        if (options?.timeout) {
+            let timer;
+            try {
+                exitCode = await Promise.race([
+                    proc.wait().then((code) => {
+                        clearTimeout(timer);
+                        return code;
+                    }),
+                    new Promise((_, reject) => {
+                        timer = setTimeout(() => {
+                            // Kill process and detach output callbacks
+                            proc.onStdout = null;
+                            proc.onStderr = null;
+                            proc.kill(SIGTERM);
+                            reject(new KernelError("ETIMEDOUT", "exec timeout"));
+                        }, options.timeout);
+                    }),
+                ]);
+            }
+            catch (err) {
+                clearTimeout(timer);
+                throw err;
+            }
+        }
+        else {
+            exitCode = await proc.wait();
+        }
+        return {
+            exitCode,
+            stdout: concatUint8(stdoutChunks),
+            stderr: concatUint8(stderrChunks),
+        };
+    }
+    spawn(command, args, options) {
+        this.assertNotDisposed();
+        return this.spawnManaged(command, args, options);
+    }
+    openShell(options) {
+        this.assertNotDisposed();
+        const command = options?.command ?? "sh";
+        const args = options?.args ?? [];
+        // Allocate a controller PID with an FD table to hold the PTY master
+        const controllerPid = this.processTable.allocatePid();
+        const controllerTable = this.fdTableManager.create(controllerPid);
+        // Create PTY pair in the controller's FD table
+        const { masterFd, slaveFd } = this.ptyManager.createPtyFDs(controllerTable);
+        const masterDescId = controllerTable.get(masterFd).description.id;
+        // Spawn shell with PTY slave as stdin/stdout/stderr
+        const proc = this.spawnInternal(command, args, {
+            env: options?.env,
+            cwd: options?.cwd,
+            stdinFd: slaveFd,
+            stdoutFd: slaveFd,
+            stderrFd: slaveFd,
+        }, controllerPid);
+        // Shell becomes its own process group leader, set as PTY foreground
+        this.processTable.setpgid(proc.pid, proc.pid);
+        this.ptyManager.setForegroundPgid(masterDescId, proc.pid);
+        this.ptyManager.setSessionLeader(masterDescId, proc.pid);
+        // Close controller's copy of slave FD (child inherited its own copy via fork).
+        // Without this, slave refCount stays >0 after shell exits, preventing EOF on master.
+        const slaveEntry = controllerTable.get(slaveFd);
+        const slaveDescId = slaveEntry.description.id;
+        controllerTable.close(slaveFd);
+        if (slaveEntry.description.refCount <= 0) {
+            this.ptyManager.close(slaveDescId);
+        }
+        // Start read pump: master reads → onData callback
+        // Use object wrapper so TypeScript doesn't narrow to null in the async closure
+        const pump = { onData: null, exited: false };
+        const pumpPromise = (async () => {
+            try {
+                while (!pump.exited) {
+                    const data = await this.ptyManager.read(masterDescId, 4096);
+                    if (!data || data.length === 0)
+                        break;
+                    try {
+                        pump.onData?.(data);
+                    }
+                    catch (cbErr) {
+                        // Propagate callback errors — don't silently swallow
+                        console.error("openShell readPump: onData callback error:", cbErr);
+                    }
+                }
+            }
+            catch (err) {
+                // Master closed or PTY gone — expected when shell exits
+                if (pump.exited)
+                    return;
+                console.error("openShell readPump: PTY read error:", err);
+            }
+        })();
+        // wait() resolves after both shell exit AND pump drain
+        const waitPromise = proc.wait().then(async (exitCode) => {
+            pump.exited = true;
+            // Wait for pump to finish delivering remaining data
+            await pumpPromise;
+            // Clean up controller PID's FD table (incl. PTY master)
+            this.cleanupProcessFDs(controllerPid);
+            return exitCode;
+        });
+        return {
+            pid: proc.pid,
+            write: (data) => {
+                const bytes = typeof data === "string"
+                    ? new TextEncoder().encode(data)
+                    : data;
+                this.ptyManager.write(masterDescId, bytes);
+            },
+            get onData() { return pump.onData; },
+            set onData(fn) { pump.onData = fn; },
+            resize: (_cols, _rows) => {
+                const fgPgid = this.ptyManager.getForegroundPgid(masterDescId);
+                if (fgPgid > 0) {
+                    try {
+                        this.processTable.kill(-fgPgid, SIGWINCH);
+                    }
+                    catch { /* pgid may be gone */ }
+                }
+            },
+            kill: (signal) => {
+                proc.kill(signal ?? SIGTERM);
+            },
+            wait: () => waitPromise,
+        };
+    }
+    async connectTerminal(options) {
+        this.assertNotDisposed();
+        const stdin = process.stdin;
+        const stdout = process.stdout;
+        const isTTY = stdin.isTTY;
+        let onStdinData;
+        let onResize;
+        try {
+            const shell = this.openShell(options);
+            // Set raw mode so keypresses pass through directly
+            if (isTTY)
+                stdin.setRawMode(true);
+            // Forward stdin to shell
+            onStdinData = (data) => shell.write(data);
+            stdin.on("data", onStdinData);
+            stdin.resume();
+            // Forward shell output to stdout or custom handler
+            const outputHandler = options?.onData
+                ?? ((data) => { stdout.write(data); });
+            shell.onData = outputHandler;
+            // PTY resize forwarding is currently unsafe for Wasm shell sessions:
+            // an early resize can terminate the shell before the first prompt.
+            // Keep interactive stdin/stdout working and leave resize disabled
+            // until the PTY/SIGWINCH path is fixed end-to-end.
+            onResize = undefined;
+            return await shell.wait();
+        }
+        finally {
+            // Restore terminal — guard each cleanup since setup may have partially completed
+            if (onStdinData)
+                stdin.removeListener("data", onStdinData);
+            stdin.pause();
+            if (isTTY)
+                stdin.setRawMode(false);
+            if (onResize && stdout.isTTY)
+                stdout.removeListener("resize", onResize);
+        }
+    }
+    // Filesystem convenience wrappers
+    readFile(path) { return this.vfs.readFile(path); }
+    writeFile(path, content) { return this.vfs.writeFile(path, content); }
+    mkdir(path) { return this.vfs.mkdir(path); }
+    readdir(path) { return this.vfs.readDir(path); }
+    stat(path) { return this.vfs.stat(path); }
+    exists(path) { return this.vfs.exists(path); }
+    // Introspection
+    get commands() {
+        return this.commandRegistry.list();
+    }
+    get processes() {
+        return this.processTable.listProcesses();
+    }
+    get zombieTimerCount() {
+        return this.processTable.zombieTimerCount;
+    }
+    // -----------------------------------------------------------------------
+    // Internal spawn
+    // -----------------------------------------------------------------------
+    spawnInternal(command, args, options, callerPid) {
+        let driver = this.commandRegistry.resolve(command);
+        // On-demand discovery: ask mounted drivers to resolve unknown commands
+        if (!driver) {
+            const basename = command.includes("/")
+                ? command.split("/").pop()
+                : command;
+            if (basename) {
+                for (const d of this.drivers) {
+                    if (d.tryResolve?.(basename)) {
+                        this.commandRegistry.registerCommand(basename, d);
+                        // Store pending promise so exec() can flush before shell PATH lookup
+                        const p = this.commandRegistry.populateBinEntry(this.vfs, basename);
+                        this.pendingBinEntries.push(p);
+                        p.then(() => {
+                            const idx = this.pendingBinEntries.indexOf(p);
+                            if (idx >= 0)
+                                this.pendingBinEntries.splice(idx, 1);
+                        });
+                        driver = d;
+                        break;
+                    }
+                }
+            }
+        }
+        if (!driver) {
+            throw new KernelError("ENOENT", `command not found: ${command}`);
+        }
+        // Check childProcess permission
+        checkChildProcess(this.permissions, command, args, options?.cwd);
+        // Enforce maxProcesses budget
+        if (this.maxProcesses !== undefined && this.processTable.runningCount() >= this.maxProcesses) {
+            throw new KernelError("EAGAIN", "maximum process limit reached");
+        }
+        // Allocate PID atomically
+        const pid = this.processTable.allocatePid();
+        // Register PID ownership before driver.spawn() so the driver can use it
+        this.driverPids.get(driver.name)?.add(pid);
+        // Cross-runtime spawn: parent driver must also track child PID so
+        // it can waitpid/kill/interact with the child process
+        if (callerPid !== undefined) {
+            for (const [name, pids] of this.driverPids) {
+                if (name !== driver.name && pids.has(callerPid)) {
+                    pids.add(pid);
+                    break;
+                }
+            }
+        }
+        // Create FD table — wire pipe FDs when overrides are provided
+        const table = this.createChildFDTable(pid, options, callerPid);
+        // Check which stdio channels are piped (data flows through kernel, not callbacks)
+        const stdoutPiped = this.isStdioPiped(table, 1);
+        const stderrPiped = this.isStdioPiped(table, 2);
+        // Buffer stdout/stderr — wired before spawn so nothing is lost
+        const stdoutBuf = [];
+        const stderrBuf = [];
+        // Resolve output callbacks: when a child inherits non-piped stdio from
+        // a parent, forward output to the parent's DriverProcess callbacks so
+        // cross-runtime child output reaches the top-level collector.
+        // When piped, wire a callback that forwards through the pipe/PTY so
+        // drivers that emit output via callbacks (Node) reach the PTY/pipe.
+        let stdoutCb;
+        let stderrCb;
+        if (stdoutPiped) {
+            stdoutCb = this.createPipedOutputCallback(table, 1, pid);
+        }
+        else {
+            if (options?.onStdout) {
+                stdoutCb = options.onStdout;
+            }
+            else if (callerPid !== undefined) {
+                const parent = this.processTable.get(callerPid);
+                if (parent?.driverProcess.onStdout) {
+                    stdoutCb = parent.driverProcess.onStdout;
+                }
+            }
+            if (!stdoutCb)
+                stdoutCb = (data) => stdoutBuf.push(data);
+        }
+        if (stderrPiped) {
+            stderrCb = this.createPipedOutputCallback(table, 2, pid);
+        }
+        else {
+            if (options?.onStderr) {
+                stderrCb = options.onStderr;
+            }
+            else if (callerPid !== undefined) {
+                const parent = this.processTable.get(callerPid);
+                if (parent?.driverProcess.onStderr) {
+                    stderrCb = parent.driverProcess.onStderr;
+                }
+            }
+            if (!stderrCb)
+                stderrCb = (data) => stderrBuf.push(data);
+        }
+        // Inherit env from parent process if spawned by another process, else use kernel defaults
+        const parentEntry = callerPid ? this.processTable.get(callerPid) : undefined;
+        const baseEnv = parentEntry?.env ?? this.env;
+        // Detect PTY slave on stdio FDs
+        const stdinIsTTY = this.isFdPtySlave(table, 0);
+        const stdoutIsTTY = this.isFdPtySlave(table, 1);
+        const stderrIsTTY = this.isFdPtySlave(table, 2);
+        // Build process context with pre-wired callbacks
+        const ctx = {
+            pid,
+            ppid: callerPid ?? 0,
+            env: { ...baseEnv, ...options?.env },
+            cwd: options?.cwd ?? this.cwd,
+            fds: { stdin: 0, stdout: 1, stderr: 2 },
+            stdinIsTTY,
+            stdoutIsTTY,
+            stderrIsTTY,
+            onStdout: stdoutCb,
+            onStderr: stderrCb,
+        };
+        // Spawn via driver
+        const driverProcess = driver.spawn(command, args, ctx);
+        // Capture data emitted via DriverProcess callbacks after spawn returns.
+        if (!stdoutPiped) {
+            driverProcess.onStdout = stdoutCb ?? ((data) => stdoutBuf.push(data));
+        }
+        if (!stderrPiped) {
+            driverProcess.onStderr = stderrCb ?? ((data) => stderrBuf.push(data));
+        }
+        // Register in process table
+        const entry = this.processTable.register(pid, driver.name, command, args, ctx, driverProcess);
+        return {
+            pid: entry.pid,
+            driverProcess,
+            wait: () => driverProcess.wait(),
+            writeStdin: (data) => driverProcess.writeStdin(data),
+            closeStdin: () => driverProcess.closeStdin(),
+            kill: (signal) => driverProcess.kill(signal ?? 15),
+            get onStdout() { return driverProcess.onStdout; },
+            set onStdout(fn) {
+                driverProcess.onStdout = fn;
+                // Replay buffered data
+                if (fn)
+                    for (const chunk of stdoutBuf)
+                        fn(chunk);
+                stdoutBuf.length = 0;
+            },
+            get onStderr() { return driverProcess.onStderr; },
+            set onStderr(fn) {
+                driverProcess.onStderr = fn;
+                if (fn)
+                    for (const chunk of stderrBuf)
+                        fn(chunk);
+                stderrBuf.length = 0;
+            },
+        };
+    }
+    spawnManaged(command, args, options, callerPid) {
+        const internal = this.spawnInternal(command, args, options, callerPid);
+        let exitCode = null;
+        // Note: options.onStdout/onStderr are already wired through ctx.onStdout
+        // by spawnInternal. Do NOT also set them on driverProcess.onStdout here —
+        // the driver calls both ctx.onStdout and proc.onStdout per message, so
+        // setting both to the same callback would double-deliver output.
+        internal.driverProcess.wait().then((code) => {
+            exitCode = code;
+        });
+        return {
+            pid: internal.pid,
+            writeStdin: (data) => {
+                const bytes = typeof data === "string"
+                    ? new TextEncoder().encode(data)
+                    : data;
+                internal.writeStdin(bytes);
+            },
+            closeStdin: () => internal.closeStdin(),
+            kill: (signal) => this.processTable.kill(internal.pid, signal ?? 15),
+            wait: () => internal.driverProcess.wait(),
+            get exitCode() { return exitCode; },
+        };
+    }
+    // -----------------------------------------------------------------------
+    // Kernel interface (exposed to drivers)
+    // -----------------------------------------------------------------------
+    createKernelInterface(driverName) {
+        // Validate that the calling driver owns the target PID
+        const assertOwns = (pid) => {
+            if (this.driverPids.get(driverName)?.has(pid))
+                return;
+            // Check if any driver owns this PID — if not, the PID doesn't exist
+            for (const pids of this.driverPids.values()) {
+                if (pids.has(pid)) {
+                    throw new KernelError("EPERM", `driver "${driverName}" does not own PID ${pid}`);
+                }
+            }
+            throw new KernelError("ESRCH", `no such process ${pid}`);
+        };
+        const kernelInterface = {
+            vfs: this.vfs,
+            // FD operations
+            fdOpen: (pid, path, flags, mode) => {
+                assertOwns(pid);
+                // /dev/fd/N → dup(N): equivalent to open() on the underlying FD
+                if (path.startsWith("/dev/fd/")) {
+                    const raw = path.slice(8);
+                    const n = parseInt(raw, 10);
+                    if (isNaN(n) || n < 0 || String(n) !== raw)
+                        throw new KernelError("EBADF", `bad file descriptor: ${path}`);
+                    const table = this.getTable(pid);
+                    const entry = table.get(n);
+                    if (!entry)
+                        throw new KernelError("EBADF", `bad file descriptor ${n}`);
+                    return table.dup(n);
+                }
+                const created = (flags & (O_CREAT | O_EXCL | O_TRUNC)) !== 0
+                    ? this.prepareOpenSync(path, flags)
+                    : false;
+                const table = this.getTable(pid);
+                const filetype = FILETYPE_REGULAR_FILE;
+                const fd = table.open(path, flags, filetype);
+                const fdEntry = table.get(fd);
+                if (fdEntry) {
+                    this.trackDescriptionInode(fdEntry.description);
+                }
+                // Stash the effective mode for the first write that materializes a new file.
+                if (created && (flags & O_CREAT)) {
+                    const entry = this.processTable.get(pid);
+                    const umask = entry?.umask ?? 0o022;
+                    const requestedMode = mode ?? 0o666;
+                    if (fdEntry) {
+                        fdEntry.description.creationMode = requestedMode & ~umask;
+                    }
+                }
+                return fd;
+            },
+            fdRead: async (pid, fd, length) => {
+                assertOwns(pid);
+                const table = this.getTable(pid);
+                const entry = table.get(fd);
+                if (!entry)
+                    throw new KernelError("EBADF", `bad file descriptor ${fd}`);
+                // Pipe reads route through PipeManager
+                if (this.pipeManager.isPipe(entry.description.id)) {
+                    const data = await this.pipeManager.read(entry.description.id, length);
+                    return data ?? new Uint8Array(0);
+                }
+                // PTY reads route through PtyManager
+                if (this.ptyManager.isPty(entry.description.id)) {
+                    const data = await this.ptyManager.read(entry.description.id, length);
+                    return data ?? new Uint8Array(0);
+                }
+                // Positional read from VFS — avoids loading entire file
+                const cursor = Number(entry.description.cursor);
+                const slice = await this.preadDescription(entry.description, cursor, length);
+                entry.description.cursor += BigInt(slice.length);
+                return slice;
+            },
+            fdWrite: (pid, fd, data) => {
+                assertOwns(pid);
+                const table = this.getTable(pid);
+                const entry = table.get(fd);
+                if (!entry)
+                    throw new KernelError("EBADF", `bad file descriptor ${fd}`);
+                if (this.pipeManager.isPipe(entry.description.id)) {
+                    return this.pipeManager.write(entry.description.id, data, pid);
+                }
+                if (this.ptyManager.isPty(entry.description.id)) {
+                    return this.ptyManager.write(entry.description.id, data);
+                }
+                // Write to VFS at cursor position (async — returns Promise)
+                return this.vfsWrite(entry, data);
+            },
+            fdClose: (pid, fd) => {
+                assertOwns(pid);
+                const table = this.getTable(pid);
+                const entry = table.get(fd);
+                if (!entry)
+                    return;
+                const descId = entry.description.id;
+                const isPipe = this.pipeManager.isPipe(descId);
+                const isPty = this.ptyManager.isPty(descId);
+                // Close FD first (decrements refCount on shared FileDescription)
+                table.close(fd);
+                // Only signal pipe/pty/lock closure when last reference is dropped
+                if (entry.description.refCount <= 0) {
+                    this.releaseDescriptionInode(entry.description);
+                    if (isPipe)
+                        this.pipeManager.close(descId);
+                    if (isPty)
+                        this.ptyManager.close(descId);
+                    this.fileLockManager.releaseByDescription(descId);
+                }
+            },
+            fdSeek: async (pid, fd, offset, whence) => {
+                assertOwns(pid);
+                const table = this.getTable(pid);
+                const entry = table.get(fd);
+                if (!entry)
+                    throw new KernelError("EBADF", `bad file descriptor ${fd}`);
+                // Pipes and PTYs are not seekable
+                if (this.pipeManager.isPipe(entry.description.id) || this.ptyManager.isPty(entry.description.id)) {
+                    throw new KernelError("ESPIPE", "illegal seek");
+                }
+                let newCursor;
+                switch (whence) {
+                    case SEEK_SET:
+                        newCursor = offset;
+                        break;
+                    case SEEK_CUR:
+                        newCursor = entry.description.cursor + offset;
+                        break;
+                    case SEEK_END: {
+                        newCursor = BigInt(await this.getDescriptionSize(entry.description)) + offset;
+                        break;
+                    }
+                    default:
+                        throw new KernelError("EINVAL", `invalid whence ${whence}`);
+                }
+                if (newCursor < 0n)
+                    throw new KernelError("EINVAL", "negative seek position");
+                entry.description.cursor = newCursor;
+                return newCursor;
+            },
+            fdPread: async (pid, fd, length, offset) => {
+                assertOwns(pid);
+                const table = this.getTable(pid);
+                const entry = table.get(fd);
+                if (!entry)
+                    throw new KernelError("EBADF", `bad file descriptor ${fd}`);
+                // Pipes and PTYs are not seekable
+                if (this.pipeManager.isPipe(entry.description.id) || this.ptyManager.isPty(entry.description.id)) {
+                    throw new KernelError("ESPIPE", "illegal seek");
+                }
+                // Read from VFS at given offset without moving cursor
+                return this.preadDescription(entry.description, Number(offset), length);
+            },
+            fdPwrite: async (pid, fd, data, offset) => {
+                assertOwns(pid);
+                const table = this.getTable(pid);
+                const entry = table.get(fd);
+                if (!entry)
+                    throw new KernelError("EBADF", `bad file descriptor ${fd}`);
+                // Pipes and PTYs are not seekable
+                if (this.pipeManager.isPipe(entry.description.id) || this.ptyManager.isPty(entry.description.id)) {
+                    throw new KernelError("ESPIPE", "illegal seek");
+                }
+                // Write at offset without moving cursor.
+                const content = await this.readDescriptionFile(entry.description);
+                const pos = Number(offset);
+                const endPos = pos + data.length;
+                const newContent = new Uint8Array(Math.max(content.length, endPos));
+                newContent.set(content);
+                newContent.set(data, pos);
+                await this.writeDescriptionFile(entry.description, newContent);
+                return data.length;
+            },
+            fdDup: (pid, fd) => {
+                assertOwns(pid);
+                return this.getTable(pid).dup(fd);
+            },
+            fdDup2: (pid, oldFd, newFd) => {
+                assertOwns(pid);
+                const table = this.getTable(pid);
+                const targetEntry = table.get(newFd);
+                const targetDesc = targetEntry?.description;
+                const targetDescId = targetDesc?.id;
+                table.dup2(oldFd, newFd);
+                if (targetDesc && targetDesc.refCount <= 0) {
+                    this.releaseDescriptionInode(targetDesc);
+                    if (targetDescId !== undefined) {
+                        if (this.pipeManager.isPipe(targetDescId))
+                            this.pipeManager.close(targetDescId);
+                        if (this.ptyManager.isPty(targetDescId))
+                            this.ptyManager.close(targetDescId);
+                        this.fileLockManager.releaseByDescription(targetDescId);
+                    }
+                }
+            },
+            fdDupMin: (pid, fd, minFd) => {
+                assertOwns(pid);
+                return this.getTable(pid).dupMinFd(fd, minFd);
+            },
+            fdStat: (pid, fd) => {
+                assertOwns(pid);
+                return this.getTable(pid).stat(fd);
+            },
+            fdPoll: (pid, fd) => {
+                try {
+                    const table = this.getTable(pid);
+                    const entry = table.get(fd);
+                    if (!entry)
+                        return { readable: false, writable: false, hangup: false, invalid: true };
+                    const descId = entry.description.id;
+                    if (this.pipeManager.isPipe(descId)) {
+                        const ps = this.pipeManager.pollState(descId);
+                        return ps ? { ...ps, invalid: false } : { readable: false, writable: false, hangup: false, invalid: true };
+                    }
+                    // Regular files are always readable/writable
+                    return { readable: true, writable: true, hangup: false, invalid: false };
+                }
+                catch {
+                    return { readable: false, writable: false, hangup: false, invalid: true };
+                }
+            },
+            fdPollWait: async (pid, fd, timeoutMs) => {
+                assertOwns(pid);
+                const table = this.getTable(pid);
+                const entry = table.get(fd);
+                if (!entry)
+                    throw new KernelError("EBADF", `bad file descriptor ${fd}`);
+                const descId = entry.description.id;
+                if (this.pipeManager.isPipe(descId)) {
+                    await this.pipeManager.waitForPoll(descId, timeoutMs);
+                }
+            },
+            fdSetCloexec: (pid, fd, value) => {
+                assertOwns(pid);
+                const table = this.getTable(pid);
+                const entry = table.get(fd);
+                if (!entry)
+                    throw new KernelError("EBADF", `bad file descriptor ${fd}`);
+                entry.cloexec = value;
+            },
+            fdGetCloexec: (pid, fd) => {
+                assertOwns(pid);
+                const table = this.getTable(pid);
+                const entry = table.get(fd);
+                if (!entry)
+                    throw new KernelError("EBADF", `bad file descriptor ${fd}`);
+                return entry.cloexec;
+            },
+            fcntl: (pid, fd, cmd, arg) => {
+                assertOwns(pid);
+                const table = this.getTable(pid);
+                const entry = table.get(fd);
+                if (!entry)
+                    throw new KernelError("EBADF", `bad file descriptor ${fd}`);
+                switch (cmd) {
+                    case F_DUPFD:
+                        return table.dupMinFd(fd, arg ?? 0);
+                    case F_DUPFD_CLOEXEC: {
+                        const newFd = table.dupMinFd(fd, arg ?? 0);
+                        table.get(newFd).cloexec = true;
+                        return newFd;
+                    }
+                    case F_GETFD:
+                        return entry.cloexec ? FD_CLOEXEC : 0;
+                    case F_SETFD:
+                        entry.cloexec = ((arg ?? 0) & FD_CLOEXEC) !== 0;
+                        return 0;
+                    case F_GETFL:
+                        return entry.description.flags;
+                    default:
+                        throw new KernelError("EINVAL", `unsupported fcntl command ${cmd}`);
+                }
+            },
+            // Advisory file locking
+            flock: async (pid, fd, operation) => {
+                assertOwns(pid);
+                const table = this.getTable(pid);
+                const entry = table.get(fd);
+                if (!entry)
+                    throw new KernelError("EBADF", `bad file descriptor ${fd}`);
+                await this.fileLockManager.flock(entry.description.path, entry.description.id, operation);
+            },
+            // Process operations
+            spawn: (command, args, ctx) => {
+                if (ctx.ppid)
+                    assertOwns(ctx.ppid);
+                return this.spawnManaged(command, args, {
+                    env: ctx.env,
+                    cwd: ctx.cwd,
+                    onStdout: ctx.onStdout,
+                    onStderr: ctx.onStderr,
+                    stdinFd: ctx.stdinFd,
+                    stdoutFd: ctx.stdoutFd,
+                    stderrFd: ctx.stderrFd,
+                }, ctx.ppid);
+            },
+            waitpid: (pid, options) => {
+                try {
+                    assertOwns(pid);
+                }
+                catch (e) {
+                    return Promise.reject(e);
+                }
+                return this.processTable.waitpid(pid, options);
+            },
+            kill: (pid, signal) => {
+                // Negative PID = process group kill, handled by kernel directly
+                if (pid >= 0)
+                    assertOwns(pid);
+                this.processTable.kill(pid, signal);
+            },
+            getpid: (pid) => {
+                assertOwns(pid);
+                return pid;
+            },
+            getppid: (pid) => {
+                assertOwns(pid);
+                return this.processTable.getppid(pid);
+            },
+            // Process group / session
+            setpgid: (pid, pgid) => {
+                assertOwns(pid);
+                this.processTable.setpgid(pid, pgid);
+            },
+            getpgid: (pid) => {
+                assertOwns(pid);
+                return this.processTable.getpgid(pid);
+            },
+            setsid: (pid) => {
+                assertOwns(pid);
+                return this.processTable.setsid(pid);
+            },
+            getsid: (pid) => {
+                assertOwns(pid);
+                return this.processTable.getsid(pid);
+            },
+            // Pipe operations
+            pipe: (pid) => {
+                assertOwns(pid);
+                const table = this.getTable(pid);
+                return this.pipeManager.createPipeFDs(table);
+            },
+            // PTY operations
+            openpty: (pid) => {
+                assertOwns(pid);
+                const table = this.getTable(pid);
+                return this.ptyManager.createPtyFDs(table);
+            },
+            isatty: (pid, fd) => {
+                assertOwns(pid);
+                const table = this.getTable(pid);
+                const entry = table.get(fd);
+                if (!entry)
+                    return false;
+                return this.ptyManager.isSlave(entry.description.id);
+            },
+            ptySetDiscipline: (pid, fd, config) => {
+                assertOwns(pid);
+                const table = this.getTable(pid);
+                const entry = table.get(fd);
+                if (!entry)
+                    throw new KernelError("EBADF", `bad file descriptor ${fd}`);
+                this.ptyManager.setDiscipline(entry.description.id, config);
+            },
+            ptySetForegroundPgid: (pid, fd, pgid) => {
+                assertOwns(pid);
+                const table = this.getTable(pid);
+                const entry = table.get(fd);
+                if (!entry)
+                    throw new KernelError("EBADF", `bad file descriptor ${fd}`);
+                this.ptyManager.setForegroundPgid(entry.description.id, pgid);
+            },
+            // Termios operations
+            tcgetattr: (pid, fd) => {
+                assertOwns(pid);
+                const table = this.getTable(pid);
+                const entry = table.get(fd);
+                if (!entry)
+                    throw new KernelError("EBADF", `bad file descriptor ${fd}`);
+                return this.ptyManager.getTermios(entry.description.id);
+            },
+            tcsetattr: (pid, fd, termios) => {
+                assertOwns(pid);
+                const table = this.getTable(pid);
+                const entry = table.get(fd);
+                if (!entry)
+                    throw new KernelError("EBADF", `bad file descriptor ${fd}`);
+                this.ptyManager.setTermios(entry.description.id, termios);
+            },
+            tcsetpgrp: (pid, fd, pgid) => {
+                assertOwns(pid);
+                const table = this.getTable(pid);
+                const entry = table.get(fd);
+                if (!entry)
+                    throw new KernelError("EBADF", `bad file descriptor ${fd}`);
+                // Validate target PGID refers to an existing process group
+                if (!this.processTable.hasProcessGroup(pgid)) {
+                    throw new KernelError("ESRCH", `no such process group ${pgid}`);
+                }
+                this.ptyManager.setForegroundPgid(entry.description.id, pgid);
+            },
+            tcgetpgrp: (pid, fd) => {
+                assertOwns(pid);
+                const table = this.getTable(pid);
+                const entry = table.get(fd);
+                if (!entry)
+                    throw new KernelError("EBADF", `bad file descriptor ${fd}`);
+                return this.ptyManager.getForegroundPgid(entry.description.id);
+            },
+            // /dev/fd operations
+            devFdReadDir: (pid) => {
+                assertOwns(pid);
+                const table = this.fdTableManager.get(pid);
+                if (!table)
+                    return [];
+                const fds = [];
+                for (const entry of table)
+                    fds.push(entry.fd);
+                return fds.sort((a, b) => a - b).map(String);
+            },
+            devFdStat: async (pid, fd) => {
+                assertOwns(pid);
+                const table = this.getTable(pid);
+                const entry = table.get(fd);
+                if (!entry)
+                    throw new KernelError("EBADF", `bad file descriptor ${fd}`);
+                // Pipe/PTY FDs return a synthetic character device stat
+                if (this.pipeManager.isPipe(entry.description.id) || this.ptyManager.isPty(entry.description.id)) {
+                    const now = Date.now();
+                    return {
+                        mode: 0o666,
+                        size: 0,
+                        isDirectory: false,
+                        isSymbolicLink: false,
+                        atimeMs: now,
+                        mtimeMs: now,
+                        ctimeMs: now,
+                        birthtimeMs: now,
+                        ino: entry.description.id,
+                        nlink: 1,
+                        uid: 0,
+                        gid: 0,
+                    };
+                }
+                // Regular file — stat the underlying path
+                return this.statDescription(entry.description);
+            },
+            // Environment
+            getenv: (pid) => {
+                assertOwns(pid);
+                const entry = this.processTable.get(pid);
+                return entry?.env ?? { ...this.env };
+            },
+            setenv: (pid, key, value) => {
+                assertOwns(pid);
+                const entry = this.processTable.get(pid);
+                if (!entry)
+                    throw new KernelError("ESRCH", `no such process ${pid}`);
+                entry.env[key] = value;
+            },
+            unsetenv: (pid, key) => {
+                assertOwns(pid);
+                const entry = this.processTable.get(pid);
+                if (!entry)
+                    throw new KernelError("ESRCH", `no such process ${pid}`);
+                delete entry.env[key];
+            },
+            getcwd: (pid) => {
+                assertOwns(pid);
+                const entry = this.processTable.get(pid);
+                return entry?.cwd ?? this.cwd;
+            },
+            // Working directory
+            chdir: async (pid, path) => {
+                assertOwns(pid);
+                const entry = this.processTable.get(pid);
+                if (!entry)
+                    throw new KernelError("ESRCH", `no such process ${pid}`);
+                // Validate path exists and is a directory
+                let st;
+                try {
+                    st = await this.vfs.stat(path);
+                }
+                catch {
+                    throw new KernelError("ENOENT", `no such file or directory: ${path}`);
+                }
+                if (!st.isDirectory) {
+                    throw new KernelError("ENOTDIR", `not a directory: ${path}`);
+                }
+                entry.cwd = path;
+            },
+            // Alarm (SIGALRM)
+            alarm: (pid, seconds) => {
+                assertOwns(pid);
+                return this.processTable.alarm(pid, seconds);
+            },
+            // File mode creation mask
+            umask: (pid, newMask) => {
+                assertOwns(pid);
+                const entry = this.processTable.get(pid);
+                if (!entry)
+                    throw new KernelError("ESRCH", `no such process ${pid}`);
+                const old = entry.umask;
+                if (newMask !== undefined) {
+                    entry.umask = newMask & 0o777;
+                }
+                return old;
+            },
+            // Directory creation with umask
+            mkdir: async (pid, path, mode) => {
+                assertOwns(pid);
+                const entry = this.processTable.get(pid);
+                const umask = entry?.umask ?? 0o022;
+                const requestedMode = mode ?? 0o777;
+                const effectiveMode = requestedMode & ~umask;
+                await this.vfs.mkdir(path);
+                await this.vfs.chmod(path, effectiveMode);
+            },
+            // Socket table (shared across runtimes)
+            socketTable: this.socketTable,
+            timerTable: this.timerTable,
+            // Process table (shared across runtimes)
+            processTable: this.processTable,
+        };
+        return kernelInterface;
+    }
+    /**
+     * Create FD table for a child process via fork + optional FD overrides.
+     *
+     * When callerPid exists, forks the parent's FD table so the child inherits
+     * all open FDs (shared cursors via refcounted FileDescription). Then applies
+     * stdinFd/stdoutFd/stderrFd overrides on top of the forked table.
+     */
+    createChildFDTable(childPid, options, callerPid) {
+        // Fork parent's FD table if parent exists
+        if (callerPid && this.fdTableManager.get(callerPid)) {
+            const table = this.fdTableManager.fork(callerPid, childPid);
+            // Apply FD overrides on top of the forked table
+            const hasFdOverrides = options?.stdinFd !== undefined ||
+                options?.stdoutFd !== undefined ||
+                options?.stderrFd !== undefined;
+            if (hasFdOverrides) {
+                const callerTable = this.fdTableManager.get(callerPid);
+                this.applyStdioOverride(table, callerTable, 0, options.stdinFd);
+                this.applyStdioOverride(table, callerTable, 1, options.stdoutFd);
+                this.applyStdioOverride(table, callerTable, 2, options.stderrFd);
+            }
+            // Close inherited pipe FDs above stdio that share a pipe with an
+            // overridden stdio FD — prevents pipe deadlocks (close-on-exec for
+            // counterpart pipe ends only, so tests that intentionally inherit pipe
+            // FDs without overrides are not affected).
+            if (hasFdOverrides) {
+                const overridePipeIds = new Set();
+                for (const fd of [0, 1, 2]) {
+                    const e = table.get(fd);
+                    if (e && this.pipeManager.isPipe(e.description.id)) {
+                        const pipeId = this.pipeManager.pipeIdFor(e.description.id);
+                        if (pipeId !== undefined)
+                            overridePipeIds.add(pipeId);
+                    }
+                }
+                if (overridePipeIds.size > 0) {
+                    const toClose = [];
+                    for (const entry of table) {
+                        if (entry.fd > 2 && this.pipeManager.isPipe(entry.description.id)) {
+                            const pid2 = this.pipeManager.pipeIdFor(entry.description.id);
+                            if (pid2 !== undefined && overridePipeIds.has(pid2)) {
+                                toClose.push(entry.fd);
+                            }
+                        }
+                    }
+                    for (const fd of toClose) {
+                        table.close(fd);
+                    }
+                }
+            }
+            return table;
+        }
+        return this.fdTableManager.create(childPid);
+    }
+    /** Close inherited stdio FD and install an override from the caller's table. */
+    applyStdioOverride(childTable, callerTable, targetFd, overrideFd) {
+        if (overrideFd === undefined)
+            return;
+        if (overrideFd === 0xFFFFFFFF)
+            return; // /dev/null sentinel — keep inherited
+        const entry = callerTable.get(overrideFd);
+        if (!entry)
+            return;
+        // Close the inherited FD and install the override
+        const existing = childTable.get(targetFd);
+        childTable.close(targetFd);
+        if (existing && existing.description.refCount <= 0) {
+            this.releaseDescriptionInode(existing.description);
+            const descId = existing.description.id;
+            if (this.pipeManager.isPipe(descId))
+                this.pipeManager.close(descId);
+            if (this.ptyManager.isPty(descId))
+                this.ptyManager.close(descId);
+            this.fileLockManager.releaseByDescription(descId);
+        }
+        childTable.openWith(entry.description, entry.filetype, targetFd);
+    }
+    /** Check if a stdio FD (0/1/2) in a process's table is a pipe or PTY. */
+    isStdioPiped(table, fd) {
+        const entry = table.get(fd);
+        if (!entry)
+            return false;
+        return this.pipeManager.isPipe(entry.description.id) || this.ptyManager.isPty(entry.description.id);
+    }
+    /** Check if an FD in the given table refers to a PTY slave (terminal). */
+    isFdPtySlave(table, fd) {
+        const entry = table.get(fd);
+        if (!entry)
+            return false;
+        return this.ptyManager.isSlave(entry.description.id);
+    }
+    /**
+     * Create a callback that forwards data through a piped stdio FD.
+     * Needed for drivers (like Node) that emit output via callbacks rather
+     * than kernel FD writes (like WasmVM does via WASI fd_write).
+     */
+    createPipedOutputCallback(table, fd, pid) {
+        const entry = table.get(fd);
+        if (!entry)
+            return undefined;
+        const descId = entry.description.id;
+        if (this.pipeManager.isPipe(descId)) {
+            return (data) => {
+                try {
+                    this.pipeManager.write(descId, data, pid);
+                }
+                catch { /* pipe closed */ }
+            };
+        }
+        if (this.ptyManager.isPty(descId)) {
+            return (data) => {
+                try {
+                    this.ptyManager.write(descId, data);
+                }
+                catch { /* pty closed */ }
+            };
+        }
+        return undefined;
+    }
+    /** Clean up all FDs for a process, closing pipe/PTY ends when last reference drops. */
+    cleanupProcessFDs(pid) {
+        const table = this.fdTableManager.get(pid);
+        if (!table)
+            return;
+        // Collect descriptions before closing so we can check refCounts after.
+        const descriptions = new Map();
+        const managedDescs = [];
+        for (const entry of table) {
+            descriptions.set(entry.description.id, entry.description);
+            const descId = entry.description.id;
+            if (this.pipeManager.isPipe(descId)) {
+                managedDescs.push({ id: descId, description: entry.description, type: "pipe" });
+            }
+            else if (this.ptyManager.isPty(descId)) {
+                managedDescs.push({ id: descId, description: entry.description, type: "pty" });
+            }
+            else if (this.fileLockManager.hasLock(descId)) {
+                managedDescs.push({ id: descId, description: entry.description, type: "lock" });
+            }
+        }
+        // Close all FDs and remove the table
+        this.fdTableManager.remove(pid);
+        // Release inode-backed file data after the last shared reference closes.
+        for (const description of descriptions.values()) {
+            if (description.refCount <= 0) {
+                this.releaseDescriptionInode(description);
+            }
+        }
+        // Signal closure for managed descriptions whose last reference was dropped.
+        for (const { id, description, type } of managedDescs) {
+            if (description.refCount <= 0) {
+                if (type === "pipe")
+                    this.pipeManager.close(id);
+                else if (type === "pty")
+                    this.ptyManager.close(id);
+                else if (type === "lock")
+                    this.fileLockManager.releaseByDescription(id);
+            }
+        }
+    }
+    async vfsWrite(entry, data) {
+        let content;
+        try {
+            content = await this.readDescriptionFile(entry.description);
+        }
+        catch {
+            content = new Uint8Array(0);
+        }
+        // O_APPEND: every write seeks to end of file first (POSIX)
+        const cursor = (entry.description.flags & O_APPEND)
+            ? content.length
+            : Number(entry.description.cursor);
+        const endPos = cursor + data.length;
+        const newContent = new Uint8Array(Math.max(content.length, endPos));
+        newContent.set(content);
+        newContent.set(data, cursor);
+        await this.writeDescriptionFile(entry.description, newContent);
+        // Apply creation mode once the descriptor's newly created file is materialized.
+        if (entry.description.creationMode !== undefined) {
+            await this.vfs.chmod(entry.description.path, entry.description.creationMode);
+            entry.description.creationMode = undefined;
+        }
+        entry.description.cursor = BigInt(endPos);
+        return data.length;
+    }
+    trackDescriptionInode(description) {
+        if (!this.rawInMemoryFs || description.inode !== undefined)
+            return;
+        const ino = this.rawInMemoryFs.getInodeForPath(description.path);
+        if (ino === null)
+            return;
+        description.inode = ino;
+        this.inodeTable.incrementOpenRefs(ino);
+    }
+    releaseDescriptionInode(description) {
+        if (description.inode === undefined)
+            return;
+        this.inodeTable.decrementOpenRefs(description.inode);
+        if (this.inodeTable.shouldDelete(description.inode)) {
+            this.rawInMemoryFs?.deleteInodeData(description.inode);
+            this.inodeTable.delete(description.inode);
+        }
+        description.inode = undefined;
+    }
+    async readDescriptionFile(description) {
+        if (description.inode !== undefined && this.rawInMemoryFs) {
+            return this.rawInMemoryFs.readFileByInode(description.inode);
+        }
+        return this.vfs.readFile(description.path);
+    }
+    async writeDescriptionFile(description, content) {
+        if (description.inode !== undefined && this.rawInMemoryFs) {
+            this.rawInMemoryFs.writeFileByInode(description.inode, content);
+            return;
+        }
+        await this.vfs.writeFile(description.path, content);
+        this.trackDescriptionInode(description);
+    }
+    prepareOpenSync(path, flags) {
+        const syncVfs = this.vfs;
+        return syncVfs.prepareOpenSync?.(path, flags) ?? false;
+    }
+    async preadDescription(description, offset, length) {
+        if (description.inode !== undefined && this.rawInMemoryFs) {
+            return this.rawInMemoryFs.preadByInode(description.inode, offset, length);
+        }
+        return this.vfs.pread(description.path, offset, length);
+    }
+    async getDescriptionSize(description) {
+        return (await this.statDescription(description)).size;
+    }
+    async statDescription(description) {
+        if (description.inode !== undefined && this.rawInMemoryFs) {
+            return this.rawInMemoryFs.statByInode(description.inode);
+        }
+        return this.vfs.stat(description.path);
+    }
+    getTable(pid) {
+        const table = this.fdTableManager.get(pid);
+        if (!table)
+            throw new KernelError("ESRCH", `no FD table for PID ${pid}`);
+        return table;
+    }
+    assertNotDisposed() {
+        if (this.disposed)
+            throw new Error("Kernel is disposed");
+    }
+}
+function concatUint8(chunks) {
+    if (chunks.length === 0)
+        return "";
+    const total = chunks.reduce((sum, c) => sum + c.length, 0);
+    const buf = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        buf.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return new TextDecoder().decode(buf);
+}