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

package/dist/kernel/kernel.js

@@ -5,8 +5,9 @@
  * 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 { createDeviceBackend } from "./device-backend.js";
+import { createProcBackend } from "./proc-backend.js";
+import { MountTable } from "./mount-table.js";
 import { FDTableManager } from "./fd-table.js";
 import { ProcessTable } from "./process-table.js";
 import { PipeManager } from "./pipe-manager.js";
@@ -17,33 +18,21 @@ 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";
+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, noopKernelLogger, } from "./types.js";
 export function createKernel(options) {
     return new KernelImpl(options);
 }
 class KernelImpl {
     vfs;
-    rawInMemoryFs;
+    mountTable;
     fdTableManager = new FDTableManager();
-    processTable = new ProcessTable();
+    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;
-    });
+    ptyManager;
     fileLockManager = new FileLockManager();
     commandRegistry = new CommandRegistry();
     socketTable;
     timerTable;
-    inodeTable;
     userManager;
     drivers = [];
     driverPids = new Map();
@@ -54,21 +43,38 @@ class KernelImpl {
     disposed = false;
     pendingBinEntries = [];
     posixDirsReady;
+    log;
     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, {
+        this.log = options.logger ?? noopKernelLogger;
+        this.processTable = new ProcessTable(this.log.child({ component: "process" }));
+        this.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;
+        }, this.log.child({ component: "pty" }));
+        // Build mount table: root FS → /dev → /proc → user mounts.
+        const mt = new MountTable(options.filesystem);
+        mt.mount("/dev", createDeviceBackend());
+        mt.mount("/proc", createProcBackend({
             processTable: this.processTable,
             fdTableManager: this.fdTableManager,
             hostname: options.env?.HOSTNAME,
-        });
-        // Apply permission wrapping
+            mountTable: mt,
+        }));
+        // Mount user-supplied filesystems
+        if (options.mounts) {
+            for (const m of options.mounts) {
+                mt.mount(m.path, m.fs, { readOnly: m.readOnly });
+            }
+        }
+        this.mountTable = mt;
+        // Apply permission wrapping on top of the mount table
+        let fs = mt;
         if (options.permissions) {
             fs = wrapFileSystem(fs, options.permissions);
         }
@@ -88,6 +94,7 @@ class KernelImpl {
         this.timerTable = new TimerTable();
         // Clean up FD table and sockets when a process exits
         this.processTable.onProcessExit = (pid) => {
+            this.log.debug({ pid }, "process exit cleanup");
             this.cleanupProcessFDs(pid);
             this.socketTable.closeAllForProcess(pid);
             this.timerTable.clearAllForProcess(pid);
@@ -112,6 +119,7 @@ class KernelImpl {
         this.posixDirsReady = this.initPosixDirs();
     }
     async initPosixDirs() {
+        // /dev and /proc are auto-created by MountTable mounts — don't create them here.
         const dirs = [
             "/tmp",
             "/bin",
@@ -123,7 +131,6 @@ class KernelImpl {
             "/run",
             "/srv",
             "/sys",
-            "/proc",
             "/opt",
             "/mnt",
             "/media",
@@ -170,6 +177,7 @@ class KernelImpl {
     async mount(driver) {
         this.assertNotDisposed();
         await this.posixDirsReady;
+        this.log.debug({ driver: driver.name, commands: driver.commands }, "mounting runtime driver");
         // Track PIDs owned by this driver
         if (!this.driverPids.has(driver.name)) {
             this.driverPids.set(driver.name, new Set());
@@ -181,11 +189,21 @@ class KernelImpl {
         this.drivers.push(driver);
         // Populate /bin stubs for shell PATH lookup
         await this.commandRegistry.populateBin(this.vfs);
+        this.log.info({ driver: driver.name, commands: driver.commands }, "runtime driver mounted");
+    }
+    mountFs(path, fs, options) {
+        this.assertNotDisposed();
+        this.mountTable.mount(path, fs, options);
+    }
+    unmountFs(path) {
+        this.assertNotDisposed();
+        this.mountTable.unmount(path);
     }
     async dispose() {
         if (this.disposed)
             return;
         this.disposed = true;
+        this.log.info({}, "kernel disposing");
         // Terminate all running processes
         await this.processTable.terminateAll();
         // Clean up all sockets
@@ -214,6 +232,7 @@ class KernelImpl {
     }
     async exec(command, options) {
         this.assertNotDisposed();
+        this.log.debug({ command, timeout: options?.timeout, cwd: options?.cwd }, "exec start");
         // Flush pending /bin stubs before shell PATH lookup
         await this.flushPendingBinEntries();
         // Route through shell
@@ -254,6 +273,7 @@ class KernelImpl {
                     new Promise((_, reject) => {
                         timer = setTimeout(() => {
                             // Kill process and detach output callbacks
+                            this.log.warn({ command, timeout: options.timeout }, "exec timeout, sending SIGTERM");
                             proc.onStdout = null;
                             proc.onStderr = null;
                             proc.kill(SIGTERM);
@@ -284,6 +304,7 @@ class KernelImpl {
         this.assertNotDisposed();
         const command = options?.command ?? "sh";
         const args = options?.args ?? [];
+        this.log.debug({ command, args, cols: options?.cols, rows: options?.rows, cwd: options?.cwd }, "openShell start");
         // Allocate a controller PID with an FD table to hold the PTY master
         const controllerPid = this.processTable.allocatePid();
         const controllerTable = this.fdTableManager.create(controllerPid);
@@ -291,8 +312,16 @@ class KernelImpl {
         const { masterFd, slaveFd } = this.ptyManager.createPtyFDs(controllerTable);
         const masterDescId = controllerTable.get(masterFd).description.id;
         // Spawn shell with PTY slave as stdin/stdout/stderr
+        // Propagate terminal dimensions as POSIX COLUMNS/LINES env vars
+        const cols = options?.cols;
+        const rows = options?.rows;
+        const dimEnv = {};
+        if (cols !== undefined)
+            dimEnv.COLUMNS = String(cols);
+        if (rows !== undefined)
+            dimEnv.LINES = String(rows);
         const proc = this.spawnInternal(command, args, {
-            env: options?.env,
+            env: { ...options?.env, ...dimEnv },
             cwd: options?.cwd,
             stdinFd: slaveFd,
             stdoutFd: slaveFd,
@@ -302,6 +331,7 @@ class KernelImpl {
         this.processTable.setpgid(proc.pid, proc.pid);
         this.ptyManager.setForegroundPgid(masterDescId, proc.pid);
         this.ptyManager.setSessionLeader(masterDescId, proc.pid);
+        this.log.debug({ shellPid: proc.pid, controllerPid, masterFd, masterDescId }, "openShell PTY attached");
         // 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);
@@ -356,6 +386,7 @@ class KernelImpl {
             set onData(fn) { pump.onData = fn; },
             resize: (_cols, _rows) => {
                 const fgPgid = this.ptyManager.getForegroundPgid(masterDescId);
+                this.log.trace({ shellPid: proc.pid, cols: _cols, rows: _rows, fgPgid }, "PTY resize");
                 if (fgPgid > 0) {
                     try {
                         this.processTable.kill(-fgPgid, SIGWINCH);
@@ -371,6 +402,7 @@ class KernelImpl {
     }
     async connectTerminal(options) {
         this.assertNotDisposed();
+        this.log.debug({ command: options?.command, cols: options?.cols, rows: options?.rows }, "connectTerminal start");
         const stdin = process.stdin;
         const stdout = process.stdout;
         const isTTY = stdin.isTTY;
@@ -389,11 +421,13 @@ class KernelImpl {
             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;
+            // Forward terminal resize → PTY SIGWINCH
+            if (stdout.isTTY) {
+                onResize = () => {
+                    shell.resize(stdout.columns, stdout.rows);
+                };
+                stdout.on("resize", onResize);
+            }
             return await shell.wait();
         }
         finally {
@@ -414,6 +448,9 @@ class KernelImpl {
     readdir(path) { return this.vfs.readDir(path); }
     stat(path) { return this.vfs.stat(path); }
     exists(path) { return this.vfs.exists(path); }
+    removeFile(path) { return this.vfs.removeFile(path); }
+    removeDir(path) { return this.vfs.removeDir(path); }
+    rename(oldPath, newPath) { return this.vfs.rename(oldPath, newPath); }
     // Introspection
     get commands() {
         return this.commandRegistry.list();
@@ -428,6 +465,7 @@ class KernelImpl {
     // Internal spawn
     // -----------------------------------------------------------------------
     spawnInternal(command, args, options, callerPid) {
+        this.log.debug({ command, args, callerPid, cwd: options?.cwd }, "spawn start");
         let driver = this.commandRegistry.resolve(command);
         // On-demand discovery: ask mounted drivers to resolve unknown commands
         if (!driver) {
@@ -453,12 +491,20 @@ class KernelImpl {
             }
         }
         if (!driver) {
+            this.log.warn({ command }, "command not found");
             throw new KernelError("ENOENT", `command not found: ${command}`);
         }
         // Check childProcess permission
-        checkChildProcess(this.permissions, command, args, options?.cwd);
+        try {
+            checkChildProcess(this.permissions, command, args, options?.cwd);
+        }
+        catch (err) {
+            this.log.warn({ command, args }, "spawn permission denied");
+            throw err;
+        }
         // Enforce maxProcesses budget
         if (this.maxProcesses !== undefined && this.processTable.runningCount() >= this.maxProcesses) {
+            this.log.warn({ command, running: this.processTable.runningCount(), max: this.maxProcesses }, "process limit reached");
             throw new KernelError("EAGAIN", "maximum process limit reached");
         }
         // Allocate PID atomically
@@ -483,44 +529,34 @@ class KernelImpl {
         // 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;
+        // Resolve output callbacks.  Drivers invoke BOTH ctx.onStdout and
+        // proc.onStdout per message, so the two must never point at the same
+        // callback — otherwise the host sees every chunk twice.
+        //
+        //   ctx callbacks  — kernel-internal routing (pipes, parent forwarding)
+        //                    + temporary buffer during spawn() to catch any
+        //                    synchronous output (disabled right after spawn).
+        //   proc callbacks — user / host callback (options.onStdout) or buffer
+        //                    for later replay.  Set AFTER spawn returns.
+        let ctxStdoutCb;
+        let ctxStderrCb;
         if (stdoutPiped) {
-            stdoutCb = this.createPipedOutputCallback(table, 1, pid);
+            ctxStdoutCb = 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;
-                }
+        else if (!options?.onStdout && callerPid !== undefined) {
+            const parent = this.processTable.get(callerPid);
+            if (parent?.driverProcess.onStdout) {
+                ctxStdoutCb = parent.driverProcess.onStdout;
             }
-            if (!stdoutCb)
-                stdoutCb = (data) => stdoutBuf.push(data);
         }
         if (stderrPiped) {
-            stderrCb = this.createPipedOutputCallback(table, 2, pid);
+            ctxStderrCb = this.createPipedOutputCallback(table, 2, pid);
         }
-        else {
-            if (options?.onStderr) {
-                stderrCb = options.onStderr;
+        else if (!options?.onStderr && callerPid !== undefined) {
+            const parent = this.processTable.get(callerPid);
+            if (parent?.driverProcess.onStderr) {
+                ctxStderrCb = parent.driverProcess.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;
@@ -529,27 +565,45 @@ class KernelImpl {
         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
+        // Build process context with pre-wired callbacks.
+        // When not piped/forwarded, ctx gets a temporary buffer so that any
+        // data emitted synchronously during driver.spawn() is captured.
+        const resolvedCwd = options?.cwd ?? this.cwd;
         const ctx = {
             pid,
             ppid: callerPid ?? 0,
-            env: { ...baseEnv, ...options?.env },
-            cwd: options?.cwd ?? this.cwd,
+            env: { ...baseEnv, ...options?.env, PWD: resolvedCwd },
+            cwd: resolvedCwd,
             fds: { stdin: 0, stdout: 1, stderr: 2 },
             stdinIsTTY,
             stdoutIsTTY,
             stderrIsTTY,
-            onStdout: stdoutCb,
-            onStderr: stderrCb,
+            streamStdin: options?.streamStdin,
+            onStdout: ctxStdoutCb ?? (stdoutPiped ? undefined : (data) => stdoutBuf.push(data)),
+            onStderr: ctxStderrCb ?? (stderrPiped ? undefined : (data) => stderrBuf.push(data)),
         };
         // Spawn via driver
         const driverProcess = driver.spawn(command, args, ctx);
-        // Capture data emitted via DriverProcess callbacks after spawn returns.
+        this.log.debug({
+            pid, command, driver: driver.name, callerPid,
+            stdinIsTTY, stdoutIsTTY, stderrIsTTY,
+        }, "process spawned");
+        // After spawn, disable the temporary ctx buffer so that async output
+        // flows only through proc.onStdout — prevents double-delivery.
+        // Pipe/parent-forwarding callbacks stay active (they live in ctxStdoutCb).
+        if (!stdoutPiped) {
+            ctx.onStdout = ctxStdoutCb;
+        }
+        if (!stderrPiped) {
+            ctx.onStderr = ctxStderrCb;
+        }
+        // User/host callback goes ONLY on driverProcess (never on ctx) to
+        // avoid double-delivery — drivers invoke both ctx and proc callbacks.
         if (!stdoutPiped) {
-            driverProcess.onStdout = stdoutCb ?? ((data) => stdoutBuf.push(data));
+            driverProcess.onStdout = options?.onStdout ?? ((data) => stdoutBuf.push(data));
         }
         if (!stderrPiped) {
-            driverProcess.onStderr = stderrCb ?? ((data) => stderrBuf.push(data));
+            driverProcess.onStderr = options?.onStderr ?? ((data) => stderrBuf.push(data));
         }
         // Register in process table
         const entry = this.processTable.register(pid, driver.name, command, args, ctx, driverProcess);
@@ -643,9 +697,6 @@ class KernelImpl {
                 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);
@@ -768,14 +819,8 @@ class KernelImpl {
                 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);
+                // Delegate positional write to VFS.
+                await this.pwriteDescription(entry.description, Number(offset), data);
                 return data.length;
             },
             fdDup: (pid, fd) => {
@@ -894,6 +939,7 @@ class KernelImpl {
                 return this.spawnManaged(command, args, {
                     env: ctx.env,
                     cwd: ctx.cwd,
+                    streamStdin: ctx.streamStdin,
                     onStdout: ctx.onStdout,
                     onStderr: ctx.onStderr,
                     stdinFd: ctx.stdinFd,
@@ -914,6 +960,7 @@ class KernelImpl {
                 // Negative PID = process group kill, handled by kernel directly
                 if (pid >= 0)
                     assertOwns(pid);
+                this.log.debug({ pid, signal }, "signal delivery");
                 this.processTable.kill(pid, signal);
             },
             getpid: (pid) => {
@@ -1095,6 +1142,7 @@ class KernelImpl {
                     throw new KernelError("ENOTDIR", `not a directory: ${path}`);
                 }
                 entry.cwd = path;
+                entry.env.PWD = path;
             },
             // Alarm (SIGALRM)
             alarm: (pid, seconds) => {
@@ -1273,7 +1321,7 @@ class KernelImpl {
         }
         // Close all FDs and remove the table
         this.fdTableManager.remove(pid);
-        // Release inode-backed file data after the last shared reference closes.
+        // Flush buffered writes when the last shared reference closes.
         for (const description of descriptions.values()) {
             if (description.refCount <= 0) {
                 this.releaseDescriptionInode(description);
@@ -1316,56 +1364,30 @@ class KernelImpl {
         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;
+        // Flush buffered writes to durable storage when the last FD is closed.
+        void this.vfs.fsync?.(description.path);
     }
     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 pwriteDescription(description, offset, data) {
+        await this.vfs.pwrite(description.path, offset, data);
+    }
     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) {

package/dist/kernel/mount-table.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Mount Table.
+ *
+ * Linux-style VFS mount table that routes paths to mounted filesystem backends
+ * by longest-prefix matching. Replaces the hardcoded layer composition
+ * (DeviceLayer wraps ProcLayer wraps base FS) with a unified routing table.
+ */
+import type { VirtualDirEntry, VirtualDirStatEntry, VirtualFileSystem, VirtualStat } from "./vfs.js";
+export interface MountOptions {
+    readOnly?: boolean;
+}
+export interface MountEntry {
+    path: string;
+    readOnly: boolean;
+}
+export declare class MountTable implements VirtualFileSystem {
+    /**
+     * Mounts sorted by path length descending so longest-prefix match is first hit.
+     */
+    private mounts;
+    constructor(rootFs: VirtualFileSystem);
+    /**
+     * Mount a filesystem at the given path.
+     * Auto-creates the mount point directory in the parent filesystem if needed.
+     */
+    mount(path: string, fs: VirtualFileSystem, options?: MountOptions): void;
+    /**
+     * Unmount the filesystem at the given path.
+     */
+    unmount(path: string): void;
+    /**
+     * List all current mounts.
+     */
+    getMounts(): ReadonlyArray<MountEntry>;
+    private resolve;
+    private assertWritable;
+    readFile(path: string): Promise<Uint8Array>;
+    readTextFile(path: string): Promise<string>;
+    readDir(path: string): Promise<string[]>;
+    readDirWithTypes(path: string): Promise<VirtualDirEntry[]>;
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<VirtualStat>;
+    lstat(path: string): Promise<VirtualStat>;
+    realpath(path: string): Promise<string>;
+    readlink(path: string): Promise<string>;
+    pread(path: string, offset: number, length: number): Promise<Uint8Array>;
+    pwrite(path: string, offset: number, data: Uint8Array): Promise<void>;
+    writeFile(path: string, content: string | Uint8Array): Promise<void>;
+    createDir(path: string): Promise<void>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    removeFile(path: string): Promise<void>;
+    removeDir(path: string): Promise<void>;
+    symlink(target: string, linkPath: string): Promise<void>;
+    link(oldPath: string, newPath: string): Promise<void>;
+    rename(oldPath: string, newPath: string): Promise<void>;
+    chmod(path: string, mode: number): Promise<void>;
+    chown(path: string, uid: number, gid: number): Promise<void>;
+    utimes(path: string, atime: number, mtime: number): Promise<void>;
+    truncate(path: string, length: number): Promise<void>;
+    fsync(path: string): Promise<void>;
+    copy(srcPath: string, dstPath: string): Promise<void>;
+    readDirStat(path: string): Promise<VirtualDirStatEntry[]>;
+    /**
+     * Get basenames of child mount points under a directory.
+     * For example, if mounts exist at /dev and /proc, calling with "/" returns ["dev", "proc"].
+     */
+    private getChildMountBasenames;
+    /**
+     * Synchronous open preparation (O_CREAT, O_EXCL, O_TRUNC).
+     * Delegates to the underlying backend's prepareOpenSync if it exists.
+     */
+    prepareOpenSync(path: string, flags: number): boolean;
+}