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

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 {
 }

package/dist/shared/console-formatter.js

@@ -148,14 +148,14 @@ export function getConsoleSetupCode(budget = DEFAULT_CONSOLE_SERIALIZATION_BUDGE
       const formatConsoleArgs = ${formatConsoleArgs.toString()};
 
       globalThis.console = {
-        log: (...args) => _log(formatConsoleArgs(args, __consoleBudget)),
-        error: (...args) => _error(formatConsoleArgs(args, __consoleBudget)),
-        warn: (...args) => _error(formatConsoleArgs(args, __consoleBudget)),
-        info: (...args) => _log(formatConsoleArgs(args, __consoleBudget)),
-        debug: (...args) => _log(formatConsoleArgs(args, __consoleBudget)),
-        trace: (...args) => _error(formatConsoleArgs(args, __consoleBudget)),
-        dir: (...args) => _log(formatConsoleArgs(args, __consoleBudget)),
-        table: (...args) => _log(formatConsoleArgs(args, __consoleBudget)),
+        log: (...args) => _log(formatConsoleArgs(args, __consoleBudget) + "\\n"),
+        error: (...args) => _error(formatConsoleArgs(args, __consoleBudget) + "\\n"),
+        warn: (...args) => _error(formatConsoleArgs(args, __consoleBudget) + "\\n"),
+        info: (...args) => _log(formatConsoleArgs(args, __consoleBudget) + "\\n"),
+        debug: (...args) => _log(formatConsoleArgs(args, __consoleBudget) + "\\n"),
+        trace: (...args) => _error(formatConsoleArgs(args, __consoleBudget) + "\\n"),
+        dir: (...args) => _log(formatConsoleArgs(args, __consoleBudget) + "\\n"),
+        table: (...args) => _log(formatConsoleArgs(args, __consoleBudget) + "\\n"),
       };
     `;
 }

package/dist/shared/in-memory-fs.d.ts

@@ -1,64 +1,16 @@
-import { InodeTable } from "../kernel/inode-table.js";
-import type { VirtualDirEntry, VirtualFileSystem, VirtualStat } from "../kernel/vfs.js";
 /**
- * A fully in-memory VirtualFileSystem backed by inode-aware Maps.
- * Used as the default filesystem for the browser sandbox and for tests.
- * Paths are always POSIX-style (forward slashes, rooted at "/").
+ * Factory for creating an in-memory VirtualFileSystem backed by ChunkedVFS.
+ *
+ * Replaces the old monolithic InMemoryFileSystem with
+ * ChunkedVFS(InMemoryMetadataStore + InMemoryBlockStore).
  */
-export declare class InMemoryFileSystem implements VirtualFileSystem {
-    private inodeTable;
-    private files;
-    private fileContents;
-    private dirs;
-    private symlinks;
-    constructor(inodeTable?: InodeTable);
-    setInodeTable(inodeTable: InodeTable): void;
-    getInodeForPath(path: string): number | null;
-    readFileByInode(ino: number): Uint8Array;
-    writeFileByInode(ino: number, content: Uint8Array): void;
-    preadByInode(ino: number, offset: number, length: number): Uint8Array;
-    statByInode(ino: number): VirtualStat;
-    deleteInodeData(ino: number): void;
-    private listDirEntries;
-    readFile(path: string): Promise<Uint8Array>;
-    readTextFile(path: string): Promise<string>;
-    readDir(path: string): Promise<string[]>;
-    readDirWithTypes(path: string): Promise<VirtualDirEntry[]>;
-    writeFile(path: string, content: string | Uint8Array): Promise<void>;
-    prepareOpenSync(path: string, flags: number): boolean;
-    createDir(path: string): Promise<void>;
-    mkdir(path: string, _options?: {
-        recursive?: boolean;
-    }): Promise<void>;
-    private resolveIfSymlink;
-    private resolveSymlink;
-    private statForInode;
-    private statEntry;
-    exists(path: string): Promise<boolean>;
-    stat(path: string): Promise<VirtualStat>;
-    removeFile(path: string): Promise<void>;
-    removeDir(path: string): Promise<void>;
-    rename(oldPath: string, newPath: string): Promise<void>;
-    symlink(target: string, linkPath: string): Promise<void>;
-    readlink(path: string): Promise<string>;
-    lstat(path: string): Promise<VirtualStat>;
-    link(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>;
-    realpath(path: string): Promise<string>;
-    pread(path: string, offset: number, length: number): Promise<Uint8Array>;
-    truncate(path: string, length: number): Promise<void>;
-    private reindexInodes;
-    private cloneInode;
-    private allocateFileInode;
-    private allocateDirectoryInode;
-    private allocateSymlinkInode;
-    private updateFileMetadata;
-    private requirePathInode;
-    private requireFileInode;
-    private requireInode;
-    private ensureDirectory;
-    private adjustParentDirectoryLinkCount;
-}
-export declare function createInMemoryFileSystem(): InMemoryFileSystem;
+import type { VirtualFileSystem } from "../kernel/vfs.js";
+/**
+ * Create an in-memory VirtualFileSystem using the chunked storage architecture.
+ *
+ * The returned VFS stores all data in memory via InMemoryMetadataStore and
+ * InMemoryBlockStore, composed through ChunkedVFS. It also includes a
+ * synchronous `prepareOpenSync` method used by the kernel for O_CREAT/O_EXCL/O_TRUNC
+ * handling during fdOpen.
+ */
+export declare function createInMemoryFileSystem(): VirtualFileSystem;