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

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

@@ -93,6 +93,7 @@ export declare class SocketTable {
     private readonly hostAdapter?;
     private readonly vfs?;
     private readonly getSignalState?;
+    private readonly processExists?;
     /** Bound/listening address → socket ID. Used for EADDRINUSE and TCP routing. */
     private listeners;
     /** Bound UDP address → socket ID. Separate from TCP listeners. */
@@ -103,7 +104,9 @@ export declare class SocketTable {
         hostAdapter?: HostNetworkAdapter;
         vfs?: VirtualFileSystem;
         getSignalState?: (pid: number) => ProcessSignalState;
+        processExists?: (pid: number) => boolean;
     });
+    hasHostNetworkAdapter(): boolean;
     /**
      * Create a new socket owned by the given process.
      * Returns the kernel socket ID.
@@ -279,6 +282,10 @@ export declare class SocketTable {
     private startAcceptPump;
     /** Look up a listening socket by exact address key. */
     private getListeningSocket;
+    /** Replay stored socket options onto a host-backed connection. */
+    private applySocketOptionsToHostSocket;
+    /** Best-effort option forwarding for host-backed sockets. */
+    private applySocketOptionToHostSocket;
     /** Peek up to maxBytes from a socket's readBuffer without consuming. */
     private peekFromBuffer;
     /** Consume up to maxBytes from a socket's readBuffer. */

package/dist/kernel/socket-table.js

@@ -68,6 +68,7 @@ export class SocketTable {
     hostAdapter;
     vfs;
     getSignalState;
+    processExists;
     /** Bound/listening address → socket ID. Used for EADDRINUSE and TCP routing. */
     listeners = new Map();
     /** Bound UDP address → socket ID. Separate from TCP listeners. */
@@ -78,6 +79,10 @@ export class SocketTable {
         this.hostAdapter = options?.hostAdapter;
         this.vfs = options?.vfs;
         this.getSignalState = options?.getSignalState;
+        this.processExists = options?.processExists;
+    }
+    hasHostNetworkAdapter() {
+        return this.hostAdapter !== undefined;
     }
     /**
      * Create a new socket owned by the given process.
@@ -87,6 +92,9 @@ export class SocketTable {
         if (this.sockets.size >= this.maxSockets) {
             throw new KernelError("EMFILE", "too many open sockets");
         }
+        if (this.processExists && !this.processExists(pid)) {
+            throw new KernelError("ESRCH", `cannot create socket for unknown pid ${pid}`);
+        }
         const id = this.nextSocketId++;
         const socket = {
             id,
@@ -196,19 +204,26 @@ export class SocketTable {
             throw new KernelError("EINVAL", "socket must be bound before listen");
         }
         socket.backlogLimit = Math.max(0, backlogSize);
-        // Permission check for listen
-        if (this.networkCheck) {
+        // AF_UNIX listeners stay entirely in-kernel, so host-network policy
+        // only applies to inet listeners.
+        if (socket.localAddr && isInetAddr(socket.localAddr)) {
             this.checkNetworkPermission("listen", socket.localAddr);
         }
         // External listen — delegate to host adapter
-        if (options?.external && this.hostAdapter && socket.localAddr && isInetAddr(socket.localAddr)) {
+        if (options?.external &&
+            this.hostAdapter &&
+            socket.localAddr &&
+            isInetAddr(socket.localAddr)) {
             const hostListener = await this.hostAdapter.tcpListen(socket.localAddr.host, socket.requestedEphemeralPort ? 0 : socket.localAddr.port);
             socket.hostListener = hostListener;
             socket.external = true;
             // Update port for ephemeral (port 0) bindings
             if (socket.requestedEphemeralPort || socket.localAddr.port === 0) {
                 const oldKey = addrKey(socket.localAddr);
-                socket.localAddr = { host: socket.localAddr.host, port: hostListener.port };
+                socket.localAddr = {
+                    host: socket.localAddr.host,
+                    port: hostListener.port,
+                };
                 // Re-register in listeners map with actual port
                 this.listeners.delete(oldKey);
                 this.listeners.set(addrKey(socket.localAddr), socketId);
@@ -266,7 +281,9 @@ export class SocketTable {
      */
     shutdown(socketId, how) {
         const socket = this.requireSocket(socketId);
-        if (socket.state !== "connected" && socket.state !== "write-closed" && socket.state !== "read-closed") {
+        if (socket.state !== "connected" &&
+            socket.state !== "write-closed" &&
+            socket.state !== "read-closed") {
             throw new KernelError("ENOTCONN", "socket is not connected");
         }
         // Propagate half-close/full-close semantics to real host sockets so
@@ -341,6 +358,7 @@ export class SocketTable {
     setsockopt(socketId, level, optname, optval) {
         const socket = this.requireSocket(socketId);
         socket.options.set(optKey(level, optname), optval);
+        this.applySocketOptionToHostSocket(socket, level, optname, optval);
     }
     /** Toggle non-blocking behavior for an existing socket. */
     setNonBlocking(socketId, nonBlocking) {
@@ -395,16 +413,17 @@ export class SocketTable {
         }
         // Unix domain sockets: check VFS for socket file existence
         if (isUnixAddr(addr) && this.vfs) {
-            if (!await this.vfs.exists(addr.path)) {
+            if (!(await this.vfs.exists(addr.path))) {
                 throw new KernelError("ECONNREFUSED", `connection refused: ${addr.path}`);
             }
         }
         const listener = this.findListener(addr);
         if (!listener) {
-            // External connection — check permission (throws EACCES if denied)
-            if (this.networkCheck) {
-                this.checkNetworkPermission("connect", addr);
+            if (isUnixAddr(addr)) {
+                throw new KernelError("ECONNREFUSED", `connection refused: ${addr.path}`);
             }
+            // Check external connections through the deny-by-default network policy.
+            this.checkNetworkPermission("connect", addr);
             // Route through host adapter if available
             if (this.hostAdapter && isInetAddr(addr)) {
                 if (socket.nonBlocking) {
@@ -418,6 +437,7 @@ export class SocketTable {
                 socket.external = true;
                 socket.remoteAddr = addr;
                 socket.hostSocket = hostSocket;
+                this.applySocketOptionsToHostSocket(socket);
                 this.startReadPump(socket);
                 return;
             }
@@ -467,8 +487,9 @@ export class SocketTable {
         if (socket.state !== "connected" && socket.state !== "read-closed") {
             throw new KernelError("ENOTCONN", "socket is not connected");
         }
-        // Permission check for external sockets
-        if (socket.external && this.networkCheck) {
+        // Re-check outbound external writes so pre-existing host sockets still
+        // honor deny-by-default network policy.
+        if (socket.external) {
             this.checkNetworkPermission("connect", socket.remoteAddr);
         }
         // External socket: write to host socket
@@ -480,16 +501,12 @@ export class SocketTable {
             return data.length;
         }
         if (socket.peerId === undefined) {
-            throw new KernelError("EPIPE", nosignal
-                ? "broken pipe (MSG_NOSIGNAL)"
-                : "broken pipe: peer closed");
+            throw new KernelError("EPIPE", nosignal ? "broken pipe (MSG_NOSIGNAL)" : "broken pipe: peer closed");
         }
         const peer = this.sockets.get(socket.peerId);
         if (!peer) {
             socket.peerId = undefined;
-            throw new KernelError("EPIPE", nosignal
-                ? "broken pipe (MSG_NOSIGNAL)"
-                : "broken pipe: peer closed");
+            throw new KernelError("EPIPE", nosignal ? "broken pipe (MSG_NOSIGNAL)" : "broken pipe: peer closed");
         }
         // Enforce SO_RCVBUF on the peer's receive buffer
         const rcvBuf = peer.options.get(optKey(SOL_SOCKET, SO_RCVBUF));
@@ -524,7 +541,9 @@ export class SocketTable {
             return this.consumeFromBuffer(socket, maxBytes);
         }
         // Buffer empty — check for EOF (peer gone or peer shut down write)
-        if (socket.peerId === undefined || !this.sockets.has(socket.peerId) || socket.peerWriteClosed) {
+        if (socket.peerId === undefined ||
+            !this.sockets.has(socket.peerId) ||
+            socket.peerWriteClosed) {
             return null;
         }
         // No data available
@@ -570,10 +589,10 @@ export class SocketTable {
         }
         // External routing via host adapter
         if (socket.hostUdpSocket && this.hostAdapter && isInetAddr(destAddr)) {
-            if (this.networkCheck) {
-                this.checkNetworkPermission("connect", destAddr);
-            }
-            this.hostAdapter.udpSend(socket.hostUdpSocket, new Uint8Array(data), destAddr.host, destAddr.port).catch(() => { });
+            this.checkNetworkPermission("connect", destAddr);
+            this.hostAdapter
+                .udpSend(socket.hostUdpSocket, new Uint8Array(data), destAddr.host, destAddr.port)
+                .catch(() => { });
             return data.length;
         }
         // No loopback target, no host adapter — silently drop (UDP semantics)
@@ -647,12 +666,12 @@ export class SocketTable {
         if (socket.state !== "bound") {
             throw new KernelError("EINVAL", "socket must be bound before external UDP bind");
         }
-        if (!this.hostAdapter || !socket.localAddr || !isInetAddr(socket.localAddr)) {
+        if (!this.hostAdapter ||
+            !socket.localAddr ||
+            !isInetAddr(socket.localAddr)) {
             throw new KernelError("EINVAL", "host adapter and inet address required");
         }
-        if (this.networkCheck) {
-            this.checkNetworkPermission("listen", socket.localAddr);
-        }
+        this.checkNetworkPermission("listen", socket.localAddr);
         const hostUdpSocket = await this.hostAdapter.udpBind(socket.localAddr.host, socket.localAddr.port);
         socket.hostUdpSocket = hostUdpSocket;
         socket.external = true;
@@ -680,10 +699,11 @@ export class SocketTable {
         const closed = socket.state === "closed";
         const readClosed = socket.state === "read-closed";
         const writeClosed = socket.state === "write-closed";
+        const pendingAccept = socket.state === "listening" && socket.backlog.length > 0;
         // UDP: readable when datagramQueue has data
         const readable = socket.type === SOCK_DGRAM
             ? socket.datagramQueue.length > 0 || closed
-            : socket.readBuffer.length > 0 || closed || readClosed;
+            : socket.readBuffer.length > 0 || pendingAccept || closed || readClosed;
         const writable = socket.state === "connected" ||
             socket.state === "created" ||
             socket.state === "read-closed" ||
@@ -756,6 +776,15 @@ export class SocketTable {
         }
     }
     destroySocket(socket) {
+        // Tear down queued-but-unaccepted connections with the listener so they
+        // cannot leak detached server-side sockets after the listening endpoint closes.
+        for (const pendingId of [...socket.backlog]) {
+            const pending = this.sockets.get(pendingId);
+            if (pending) {
+                this.destroySocket(pending);
+            }
+        }
+        socket.backlog.length = 0;
         // Propagate EOF to peer: clear peer link and wake readers
         if (socket.peerId !== undefined) {
             const peer = this.sockets.get(socket.peerId);
@@ -829,7 +858,9 @@ export class SocketTable {
     startExternalConnect(socket, addr) {
         if (!this.hostAdapter)
             return;
-        this.hostAdapter.tcpConnect(addr.host, addr.port).then(hostSocket => {
+        this.hostAdapter
+            .tcpConnect(addr.host, addr.port)
+            .then((hostSocket) => {
             const current = this.sockets.get(socket.id);
             if (!current || current !== socket || current.state === "closed") {
                 hostSocket.close().catch(() => { });
@@ -839,8 +870,10 @@ export class SocketTable {
             current.external = true;
             current.remoteAddr = addr;
             current.hostSocket = hostSocket;
+            this.applySocketOptionsToHostSocket(current);
             this.startReadPump(current);
-        }).catch(() => {
+        })
+            .catch(() => {
             const current = this.sockets.get(socket.id);
             if (!current || current !== socket || current.state === "closed") {
                 return;
@@ -859,7 +892,8 @@ export class SocketTable {
         const hostListener = socket.hostListener;
         const pump = async () => {
             try {
-                while (socket.state === "listening" && socket.hostListener === hostListener) {
+                while (socket.state === "listening" &&
+                    socket.hostListener === hostListener) {
                     const hostSocket = await hostListener.accept();
                     if (socket.backlog.length >= socket.backlogLimit) {
                         hostSocket.close().catch(() => { });
@@ -872,6 +906,7 @@ export class SocketTable {
                     connSock.external = true;
                     connSock.hostSocket = hostSocket;
                     connSock.localAddr = socket.localAddr;
+                    this.applySocketOptionsToHostSocket(connSock);
                     // Start read pump for the accepted socket
                     this.startReadPump(connSock);
                     // Queue in listener's backlog
@@ -895,6 +930,27 @@ export class SocketTable {
             return null;
         return sock;
     }
+    /** Replay stored socket options onto a host-backed connection. */
+    applySocketOptionsToHostSocket(socket) {
+        for (const [key, value] of socket.options.entries()) {
+            const [level, optname] = key.split(":").map(Number);
+            if (Number.isNaN(level) || Number.isNaN(optname))
+                continue;
+            this.applySocketOptionToHostSocket(socket, level, optname, value);
+        }
+    }
+    /** Best-effort option forwarding for host-backed sockets. */
+    applySocketOptionToHostSocket(socket, level, optname, optval) {
+        if (!socket.external || !socket.hostSocket) {
+            return;
+        }
+        try {
+            socket.hostSocket.setOption(level, optname, optval);
+        }
+        catch {
+            // Host adapters may not support every kernel-tracked option.
+        }
+    }
     /** Peek up to maxBytes from a socket's readBuffer without consuming. */
     peekFromBuffer(socket, maxBytes) {
         const chunks = [];
@@ -972,7 +1028,9 @@ export class SocketTable {
         if (socket.external) {
             return !socket.peerWriteClosed;
         }
-        return socket.peerId !== undefined && this.sockets.has(socket.peerId) && !socket.peerWriteClosed;
+        return (socket.peerId !== undefined &&
+            this.sockets.has(socket.peerId) &&
+            !socket.peerWriteClosed);
     }
     /** Wait for socket readiness or an interrupting signal. */
     async waitForSocketWake(waiters, pid, op) {
@@ -1048,7 +1106,8 @@ export class SocketTable {
                 continue;
             if (existing.localAddr.port !== addr.port)
                 continue;
-            const existingIsWildcard = existing.localAddr.host === "0.0.0.0" || existing.localAddr.host === "::";
+            const existingIsWildcard = existing.localAddr.host === "0.0.0.0" ||
+                existing.localAddr.host === "::";
             if (isWildcard || existingIsWildcard)
                 return true;
         }
@@ -1061,12 +1120,16 @@ export class SocketTable {
         const hostUdpSocket = socket.hostUdpSocket;
         const pump = async () => {
             try {
-                while (socket.state !== "closed" && socket.hostUdpSocket === hostUdpSocket) {
+                while (socket.state !== "closed" &&
+                    socket.hostUdpSocket === hostUdpSocket) {
                     const result = await hostUdpSocket.recv();
                     if (socket.datagramQueue.length < MAX_UDP_QUEUE_DEPTH) {
                         socket.datagramQueue.push({
                             data: result.data,
-                            srcAddr: { host: result.remoteAddr.host, port: result.remoteAddr.port },
+                            srcAddr: {
+                                host: result.remoteAddr.host,
+                                port: result.remoteAddr.port,
+                            },
                         });
                         socket.readWaiters.wakeOne();
                     }
@@ -1097,7 +1160,8 @@ export class SocketTable {
                 continue;
             if (existing.localAddr.port !== addr.port)
                 continue;
-            const existingIsWildcard = existing.localAddr.host === "0.0.0.0" || existing.localAddr.host === "::";
+            const existingIsWildcard = existing.localAddr.host === "0.0.0.0" ||
+                existing.localAddr.host === "::";
             if (isWildcard || existingIsWildcard)
                 return true;
         }

package/dist/kernel/types.d.ts

@@ -6,6 +6,27 @@
  */
 import type { WaitQueue } from "./wait.js";
 export type { VirtualFileSystem, VirtualDirEntry, VirtualStat, } from "./vfs.js";
+/**
+ * Minimal structured logger interface for kernel diagnostics.
+ * Compatible with pino and any logger that supports child loggers.
+ * The kernel never depends on pino directly — embedders pass their own logger.
+ */
+export interface KernelLogger {
+    trace(obj: Record<string, unknown>, msg?: string): void;
+    debug(obj: Record<string, unknown>, msg?: string): void;
+    info(obj: Record<string, unknown>, msg?: string): void;
+    warn(obj: Record<string, unknown>, msg?: string): void;
+    error(obj: Record<string, unknown>, msg?: string): void;
+    child(bindings: Record<string, unknown>): KernelLogger;
+}
+/** No-op logger that discards all records. */
+export declare const noopKernelLogger: KernelLogger;
+/** A filesystem to mount at a specific path inside the kernel VFS. */
+export interface FsMount {
+    path: string;
+    fs: import("./vfs.js").VirtualFileSystem;
+    readOnly?: boolean;
+}
 export interface KernelOptions {
     filesystem: import("./vfs.js").VirtualFileSystem;
     permissions?: Permissions;
@@ -15,6 +36,10 @@ export interface KernelOptions {
     maxProcesses?: number;
     /** Host network adapter for external socket routing (TCP, UDP, DNS). */
     hostNetworkAdapter?: import("./host-adapter.js").HostNetworkAdapter;
+    /** Structured debug logger for kernel diagnostics. Defaults to silent no-op. */
+    logger?: KernelLogger;
+    /** Additional filesystems to mount at boot (after /dev and /proc). */
+    mounts?: FsMount[];
 }
 export interface Kernel {
     /** Mount a runtime driver. Calls driver.init() and registers its commands. */
@@ -49,15 +74,23 @@ export interface Kernel {
      * Returns the shell exit code.
      */
     connectTerminal(options?: ConnectTerminalOptions): Promise<number>;
+    /** Mount a filesystem at the given path. */
+    mountFs(path: string, fs: import("./vfs.js").VirtualFileSystem, options?: {
+        readOnly?: boolean;
+    }): void;
+    /** Unmount the filesystem at the given path. */
+    unmountFs(path: string): void;
     readFile(path: string): Promise<Uint8Array>;
     writeFile(path: string, content: string | Uint8Array): Promise<void>;
     mkdir(path: string): Promise<void>;
     readdir(path: string): Promise<string[]>;
     stat(path: string): Promise<import("./vfs.js").VirtualStat>;
     exists(path: string): Promise<boolean>;
+    removeFile(path: string): Promise<void>;
+    removeDir(path: string): Promise<void>;
+    rename(oldPath: string, newPath: string): Promise<void>;
     readonly socketTable: import("./socket-table.js").SocketTable;
     readonly timerTable: import("./timer-table.js").TimerTable;
-    readonly inodeTable: import("./inode-table.js").InodeTable;
     readonly commands: ReadonlyMap<string, string>;
     readonly processes: ReadonlyMap<number, ProcessInfo>;
     /** Number of pending zombie cleanup timers (test observability). */
@@ -84,6 +117,8 @@ export interface SpawnOptions extends ExecOptions {
     stdoutFd?: number;
     /** FD in caller's table to wire as child's stderr (pipe write end). */
     stderrFd?: number;
+    /** Enable streaming stdin: writeStdin() delivers data immediately instead of buffering until closeStdin(). */
+    streamStdin?: boolean;
 }
 export interface ManagedProcess {
     pid: number;
@@ -172,6 +207,8 @@ export interface ProcessContext {
     stdinIsTTY?: boolean;
     stdoutIsTTY?: boolean;
     stderrIsTTY?: boolean;
+    /** Enable streaming stdin delivery (writeStdin data arrives immediately). */
+    streamStdin?: boolean;
     /** Kernel-provided callback for stdout data emitted during spawn. */
     onStdout?: (data: Uint8Array) => void;
     /** Kernel-provided callback for stderr data emitted during spawn. */
@@ -292,8 +329,6 @@ export interface FDStat {
 export interface FileDescription {
     id: number;
     path: string;
-    /** Stable inode identity for FD I/O after the pathname is unlinked. */
-    inode?: number;
     cursor: bigint;
     flags: number;
     refCount: number;
@@ -348,6 +383,8 @@ export interface ProcessEntry {
     exitReason: "normal" | "signal" | null;
     /** Signal that killed the process (0 = normal exit). */
     termSignal: number;
+    /** Epoch ms when the process was registered. */
+    startTime: number;
     exitTime: number | null;
     env: Record<string, string>;
     cwd: string;
@@ -368,11 +405,15 @@ export interface ProcessInfo {
     sid: number;
     driver: string;
     command: string;
+    args: string[];
+    cwd: string;
     status: "running" | "stopped" | "exited";
     exitCode: number | null;
+    startTime: number;
+    exitTime: number | null;
 }
 /** POSIX error codes used by the kernel. */
-export type KernelErrorCode = "EACCES" | "EADDRINUSE" | "EAGAIN" | "EBADF" | "ECONNREFUSED" | "EINPROGRESS" | "EINTR" | "EEXIST" | "EINVAL" | "EIO" | "EISDIR" | "EMFILE" | "EMSGSIZE" | "ENOENT" | "ENOSPC" | "ENOSYS" | "ENOTCONN" | "ENOTEMPTY" | "ENOTDIR" | "EPERM" | "EPIPE" | "ESPIPE" | "ESRCH" | "ETIMEDOUT";
+export type KernelErrorCode = "EACCES" | "EADDRINUSE" | "EAGAIN" | "EBADF" | "ECONNREFUSED" | "EINPROGRESS" | "EINTR" | "EEXIST" | "EINVAL" | "ELOOP" | "EIO" | "EISDIR" | "EMFILE" | "EMSGSIZE" | "ENOENT" | "ENOSPC" | "ENOSYS" | "ENOTCONN" | "ENOTEMPTY" | "ENOTDIR" | "EPERM" | "EPIPE" | "EROFS" | "ESPIPE" | "ESRCH" | "ETIMEDOUT" | "EXDEV";
 /**
  * Structured error for kernel operations.
  * Carries a machine-readable `code` so callers can map to errno without

package/dist/kernel/types.js

@@ -4,6 +4,15 @@
  * The kernel is the shared OS layer. All runtimes make "syscalls" to the
  * kernel for filesystem, process, pipe, and FD operations.
  */
+/** No-op logger that discards all records. */
+export const noopKernelLogger = {
+    trace() { },
+    debug() { },
+    info() { },
+    warn() { },
+    error() { },
+    child() { return noopKernelLogger; },
+};
 // FD open flags
 export const O_RDONLY = 0;
 export const O_WRONLY = 1;

package/dist/kernel/vfs.d.ts

@@ -2,8 +2,25 @@
  * Virtual Filesystem interface.
  *
  * POSIX-complete interface that all filesystem backends must implement.
- * Extends the original secure-exec VirtualFileSystem with symlinks,
- * links, permissions, and metadata operations needed by WasmVM's WASI polyfill.
+ * The primary implementation is ChunkedVFS, which composes an FsMetadataStore
+ * (directory tree, inodes, chunk mapping) with an FsBlockStore (key-value blob
+ * store) to provide tiered storage with optional write buffering and versioning.
+ *
+ * Error behavior (KernelError codes):
+ * - ENOENT: path does not exist (readFile, stat, pread, pwrite, truncate, readlink, etc.)
+ * - EISDIR: operation targets a directory when a file is expected (readFile, pread, pwrite)
+ * - ENOTDIR: intermediate path component is not a directory
+ * - EEXIST: target already exists (createDir without recursive, link to existing)
+ * - ELOOP: symlink resolution exceeds 40 levels
+ * - ENOTEMPTY: removeDir on non-empty directory
+ * - EPERM: link to directory
+ * - EXDEV: cross-mount copy (raised by MountTable, not VFS directly)
+ *
+ * Optional methods (fsync, copy, readDirStat) may be absent. The kernel and
+ * MountTable use optional chaining and provide fallbacks where needed.
+ *
+ * Usage: create via `createChunkedVfs()` from `./vfs/chunked-vfs.ts`, or use
+ * `createInMemoryFileSystem()` from the package root for the default in-memory VFS.
  */
 export interface VirtualDirEntry {
     name: string;
@@ -11,6 +28,9 @@ export interface VirtualDirEntry {
     isSymbolicLink?: boolean;
     ino?: number;
 }
+export interface VirtualDirStatEntry extends VirtualDirEntry {
+    stat: VirtualStat;
+}
 export interface VirtualStat {
     mode: number;
     size: number;
@@ -51,4 +71,12 @@ export interface VirtualFileSystem {
     truncate(path: string, length: number): Promise<void>;
     /** Read a range from a file without loading the entire file into memory. */
     pread(path: string, offset: number, length: number): Promise<Uint8Array>;
+    /** Write data at a specific offset without replacing the entire file. */
+    pwrite(path: string, offset: number, data: Uint8Array): Promise<void>;
+    /** Flush buffered writes for the given path to durable storage. */
+    fsync?(path: string): Promise<void>;
+    /** Copy a file within the same filesystem. */
+    copy?(srcPath: string, dstPath: string): Promise<void>;
+    /** Combined readdir + stat. Avoids N+1 queries for directory listings. */
+    readDirStat?(path: string): Promise<VirtualDirStatEntry[]>;
 }

package/dist/kernel/vfs.js

@@ -2,7 +2,24 @@
  * Virtual Filesystem interface.
  *
  * POSIX-complete interface that all filesystem backends must implement.
- * Extends the original secure-exec VirtualFileSystem with symlinks,
- * links, permissions, and metadata operations needed by WasmVM's WASI polyfill.
+ * The primary implementation is ChunkedVFS, which composes an FsMetadataStore
+ * (directory tree, inodes, chunk mapping) with an FsBlockStore (key-value blob
+ * store) to provide tiered storage with optional write buffering and versioning.
+ *
+ * Error behavior (KernelError codes):
+ * - ENOENT: path does not exist (readFile, stat, pread, pwrite, truncate, readlink, etc.)
+ * - EISDIR: operation targets a directory when a file is expected (readFile, pread, pwrite)
+ * - ENOTDIR: intermediate path component is not a directory
+ * - EEXIST: target already exists (createDir without recursive, link to existing)
+ * - ELOOP: symlink resolution exceeds 40 levels
+ * - ENOTEMPTY: removeDir on non-empty directory
+ * - EPERM: link to directory
+ * - EXDEV: cross-mount copy (raised by MountTable, not VFS directly)
+ *
+ * Optional methods (fsync, copy, readDirStat) may be absent. The kernel and
+ * MountTable use optional chaining and provide fallbacks where needed.
+ *
+ * Usage: create via `createChunkedVfs()` from `./vfs/chunked-vfs.ts`, or use
+ * `createInMemoryFileSystem()` from the package root for the default in-memory VFS.
  */
 export {};

package/dist/shared/api-types.d.ts

@@ -29,6 +29,10 @@ export interface ProcessConfig {
     stdoutIsTTY?: boolean;
     /** Whether stderr is a TTY (PTY slave attached) */
     stderrIsTTY?: boolean;
+    /** Terminal columns (from PTY dimensions). */
+    cols?: number;
+    /** Terminal rows (from PTY dimensions). */
+    rows?: number;
 }
 export interface OSConfig {
     platform?: string;
@@ -72,6 +76,8 @@ export interface ExecOptions {
     timingMitigation?: TimingMitigation;
     /** Optional streaming hook for console output events */
     onStdio?: StdioHook;
+    /** Override execution mode. 'run' mode processes async operations (timers, network). */
+    mode?: "exec" | "run";
 }
 export interface ExecResult extends ExecutionStatus {
 }