@nimbus-sh/core 0.1.0

package/src/substrate/lifo/kernel/vfs/index.ts

@@ -0,0 +1,9 @@
+export { VFS } from './VFS.js';
+export { VFSError, ErrorCode } from './types.js';
+export {
+  S_IFMT, S_IFREG, S_IFDIR, S_IFCHR, S_IFLNK, isCharacterDevice, fileTypeChar,
+} from './types.js';
+export type { INode, ChunkRef, Stat, Dirent, FileType, ErrorCodeType, VirtualProvider, MountProvider, VFSWatchEvent, VFSWatchListener, VFSEventType } from './types.js';
+export { NativeFsProvider } from './providers/NativeFsProvider.js';
+export type { NativeFsModule } from './providers/NativeFsProvider.js';
+export { getMimeType, getFileCategory, isBinaryMime } from '../../utils/mime.js';

package/src/substrate/lifo/kernel/vfs/providers/DevProvider.ts

@@ -0,0 +1,172 @@
+import type { MountProvider, Stat, Dirent } from '../types.js';
+import { VFSError, ErrorCode, S_IFCHR, S_IFDIR } from '../types.js';
+
+/**
+ * DevProvider — the character devices mounted at `/dev`.
+ *
+ * Device nodes are not files with contents; they are byte sources and sinks.
+ * That distinction is carried by two things and nothing else:
+ *
+ *   - `stat().mode` sets `S_IFCHR`, so `ls -l` renders `crw-rw-rw-` and tools
+ *     can tell a device from a regular file. Size is 0, as on real Unix.
+ *   - `readRange()` generates the requested bytes on demand, so a device has
+ *     no content ceiling — the caller's bound is the only bound.
+ *
+ * `readFile()` is a whole-file read with no bound. On a device that produces
+ * bytes forever that request cannot be answered, so it fails loudly instead
+ * of silently handing back an arbitrary prefix. Bounded readers (`head -c N`,
+ * `dd count=N`, shell redirections) go through `readRange` and work.
+ */
+
+const DEV_MODE = S_IFCHR | 0o666;
+const DIR_MODE = S_IFDIR | 0o755;
+
+/**
+ * Largest buffer a single `readRange` will materialise. Returning fewer bytes
+ * than asked for is ordinary read(2) behaviour, so callers already loop; this
+ * just keeps one call from allocating an unbounded buffer.
+ */
+const MAX_DEVICE_READ = 1024 * 1024;
+
+/** `crypto.getRandomValues` rejects requests larger than this. */
+const RANDOM_FILL_CHUNK = 65536;
+
+interface DevNode {
+  /** Devices that never reach EOF cannot answer an unbounded whole-file read. */
+  readonly unbounded: boolean;
+  /** Fill `out` with this device's bytes. Absent means the device is always at EOF. */
+  readonly fill?: (out: Uint8Array) => void;
+  readonly write: (bytes: Uint8Array) => void;
+}
+
+const discard = (): void => { /* device sink */ };
+
+function fillRandom(out: Uint8Array): void {
+  for (let i = 0; i < out.length; i += RANDOM_FILL_CHUNK) {
+    crypto.getRandomValues(out.subarray(i, Math.min(out.length, i + RANDOM_FILL_CHUNK)));
+  }
+}
+
+// Uint8Array is born zeroed, so /dev/zero and /dev/full need no fill body —
+// they only need to declare that they produce bytes forever.
+const zeros = (): void => { /* already zero */ };
+
+const DEVICES: ReadonlyMap<string, DevNode> = new Map<string, DevNode>([
+  ['null', { unbounded: false, write: discard }],
+  ['zero', { unbounded: true, fill: zeros, write: discard }],
+  ['full', {
+    unbounded: true,
+    fill: zeros,
+    write: () => { throw new VFSError(ErrorCode.EINVAL, 'ENOSPC: no space left on device'); },
+  }],
+  ['random', { unbounded: true, fill: fillRandom, write: discard }],
+  ['urandom', { unbounded: true, fill: fillRandom, write: discard }],
+  // The standard-stream nodes exist so `test -e` and `ls` see them. The shell
+  // resolves `/dev/stdin`, `/dev/stdout` and `/dev/stderr` to the invoking
+  // process's own descriptors before a redirection ever reaches this provider.
+  ['stdin', { unbounded: false, write: discard }],
+  ['stdout', { unbounded: false, write: discard }],
+  ['stderr', { unbounded: false, write: discard }],
+  ['tty', { unbounded: false, write: discard }],
+]);
+
+export class DevProvider implements MountProvider {
+  private norm(subpath: string): string {
+    return subpath.replace(/^\/+/, '').replace(/\/+$/, '');
+  }
+
+  private node(subpath: string): DevNode {
+    const name = this.norm(subpath);
+    const node = DEVICES.get(name);
+    if (!node) throw new VFSError(ErrorCode.ENOENT, `'/dev/${name}': no such device`);
+    return node;
+  }
+
+  readFile(subpath: string): Uint8Array {
+    if (this.norm(subpath) === '') {
+      throw new VFSError(ErrorCode.EISDIR, `'/dev': is a directory`);
+    }
+    const node = this.node(subpath);
+    if (node.unbounded) {
+      throw new VFSError(
+        ErrorCode.EINVAL,
+        `'/dev/${this.norm(subpath)}': character device produces bytes without end — read a bounded slice (head -c N, dd count=N)`,
+      );
+    }
+    return new Uint8Array(0);
+  }
+
+  readFileString(subpath: string): string {
+    return new TextDecoder().decode(this.readFile(subpath));
+  }
+
+  readRange(subpath: string, _offset: number, length: number): Uint8Array {
+    const node = this.node(subpath);
+    if (!node.fill) return new Uint8Array(0);
+    const out = new Uint8Array(Math.min(length, MAX_DEVICE_READ));
+    node.fill(out);
+    return out;
+  }
+
+  writeFile(subpath: string, content: string | Uint8Array): void {
+    const node = this.node(subpath);
+    node.write(typeof content === 'string' ? new TextEncoder().encode(content) : content);
+  }
+
+  writeRange(subpath: string, _offset: number, bytes: Uint8Array): void {
+    this.node(subpath).write(bytes);
+  }
+
+  truncate(subpath: string, _size: number): void {
+    // Devices have no length to set; the node must still exist.
+    this.node(subpath);
+  }
+
+  exists(subpath: string): boolean {
+    const name = this.norm(subpath);
+    return name === '' || DEVICES.has(name);
+  }
+
+  stat(subpath: string): Stat {
+    const name = this.norm(subpath);
+    if (name === '') {
+      return { type: 'directory', size: DEVICES.size, ctime: 0, mtime: 0, mode: DIR_MODE };
+    }
+    this.node(subpath);
+    return { type: 'file', size: 0, ctime: 0, mtime: 0, mode: DEV_MODE };
+  }
+
+  readdir(subpath: string): Dirent[] {
+    const name = this.norm(subpath);
+    if (name !== '') {
+      this.node(subpath);
+      throw new VFSError(ErrorCode.ENOTDIR, `'/dev/${name}': not a directory`);
+    }
+    return [...DEVICES.keys()].map((device) => ({ name: device, type: 'file' as const }));
+  }
+
+  unlink(subpath: string): void {
+    this.node(subpath);
+    throw new VFSError(ErrorCode.EINVAL, `'/dev/${this.norm(subpath)}': operation not permitted`);
+  }
+
+  mkdir(subpath: string): void {
+    throw new VFSError(ErrorCode.EINVAL, `'/dev/${this.norm(subpath)}': read-only filesystem`);
+  }
+
+  rmdir(subpath: string): void {
+    throw new VFSError(ErrorCode.EINVAL, `'/dev/${this.norm(subpath)}': read-only filesystem`);
+  }
+
+  rename(oldSubpath: string): void {
+    throw new VFSError(ErrorCode.EINVAL, `'/dev/${this.norm(oldSubpath)}': read-only filesystem`);
+  }
+
+  copyFile(srcSubpath: string): void {
+    throw new VFSError(ErrorCode.EINVAL, `'/dev/${this.norm(srcSubpath)}': read-only filesystem`);
+  }
+
+  isDirectory(subpath: string): boolean {
+    return this.norm(subpath) === '';
+  }
+}

package/src/substrate/lifo/kernel/vfs/providers/NativeFsProvider.ts

@@ -0,0 +1,198 @@
+import type { MountProvider, Stat, Dirent } from '../types.js';
+import { VFSError, ErrorCode } from '../types.js';
+
+/**
+ * Minimal interface for the subset of Node.js `fs` sync methods we need.
+ * Consumers pass this in so we avoid a hard dependency on `node:fs`.
+ */
+export interface NativeFsModule {
+  readFileSync(path: string): Uint8Array;
+  writeFileSync(path: string, data: string | Uint8Array): void;
+  existsSync(path: string): boolean;
+  statSync(path: string): { isFile(): boolean; isDirectory(): boolean; size: number; mtimeMs: number; ctimeMs: number; mode: number };
+  readdirSync(path: string, options: { withFileTypes: true }): Array<{ name: string; isFile(): boolean; isDirectory(): boolean }>;
+  unlinkSync(path: string): void;
+  mkdirSync(path: string, options?: { recursive?: boolean }): void;
+  rmdirSync(path: string): void;
+  renameSync(oldPath: string, newPath: string): void;
+  copyFileSync(src: string, dest: string): void;
+}
+
+/**
+ * A MountProvider that delegates to a native filesystem via sync Node.js APIs.
+ *
+ * All subpaths are sandboxed to `rootPath` -- any attempt to escape via `..`
+ * is rejected with EINVAL.
+ */
+export class NativeFsProvider implements MountProvider {
+  private rootPath: string;
+  private fs: NativeFsModule;
+  private readOnly: boolean;
+
+  constructor(rootPath: string, fsModule: NativeFsModule, options?: { readOnly?: boolean }) {
+    // Normalize: strip trailing slash unless it's the root itself
+    this.rootPath = rootPath.endsWith('/') && rootPath.length > 1
+      ? rootPath.slice(0, -1)
+      : rootPath;
+    this.fs = fsModule;
+    this.readOnly = options?.readOnly ?? false;
+  }
+
+  // ─── Path sandboxing ───
+
+  private resolveSafe(subpath: string): string {
+    // Normalize the subpath: remove leading slash, resolve . and ..
+    const clean = subpath.startsWith('/') ? subpath.slice(1) : subpath;
+    const parts = clean.split('/').filter(Boolean);
+    const resolved: string[] = [];
+
+    for (const part of parts) {
+      if (part === '.') continue;
+      if (part === '..') {
+        if (resolved.length === 0) {
+          throw new VFSError(ErrorCode.EINVAL, `path '${subpath}' escapes mount root`);
+        }
+        resolved.pop();
+      } else {
+        resolved.push(part);
+      }
+    }
+
+    const relative = resolved.join('/');
+    return relative ? `${this.rootPath}/${relative}` : this.rootPath;
+  }
+
+  private assertWritable(): void {
+    if (this.readOnly) {
+      throw new VFSError(ErrorCode.EINVAL, 'filesystem is mounted read-only');
+    }
+  }
+
+  // ─── Read operations ───
+
+  readFile(subpath: string): Uint8Array {
+    const fullPath = this.resolveSafe(subpath);
+    try {
+      return this.fs.readFileSync(fullPath);
+    } catch (err: unknown) {
+      throw this.wrapError(err, subpath);
+    }
+  }
+
+  readFileString(subpath: string): string {
+    const data = this.readFile(subpath);
+    return new TextDecoder().decode(data);
+  }
+
+  exists(subpath: string): boolean {
+    const fullPath = this.resolveSafe(subpath);
+    return this.fs.existsSync(fullPath);
+  }
+
+  stat(subpath: string): Stat {
+    const fullPath = this.resolveSafe(subpath);
+    try {
+      const s = this.fs.statSync(fullPath);
+      return {
+        type: s.isDirectory() ? 'directory' : 'file',
+        size: s.size,
+        ctime: Math.floor(s.ctimeMs),
+        mtime: Math.floor(s.mtimeMs),
+        mode: s.mode,
+      };
+    } catch (err: unknown) {
+      throw this.wrapError(err, subpath);
+    }
+  }
+
+  readdir(subpath: string): Dirent[] {
+    const fullPath = this.resolveSafe(subpath);
+    try {
+      const entries = this.fs.readdirSync(fullPath, { withFileTypes: true });
+      return entries.map((e) => ({
+        name: e.name,
+        type: e.isDirectory() ? 'directory' as const : 'file' as const,
+      }));
+    } catch (err: unknown) {
+      throw this.wrapError(err, subpath);
+    }
+  }
+
+  // ─── Write operations ───
+
+  writeFile(subpath: string, content: string | Uint8Array): void {
+    this.assertWritable();
+    const fullPath = this.resolveSafe(subpath);
+    try {
+      this.fs.writeFileSync(fullPath, content);
+    } catch (err: unknown) {
+      throw this.wrapError(err, subpath);
+    }
+  }
+
+  unlink(subpath: string): void {
+    this.assertWritable();
+    const fullPath = this.resolveSafe(subpath);
+    try {
+      this.fs.unlinkSync(fullPath);
+    } catch (err: unknown) {
+      throw this.wrapError(err, subpath);
+    }
+  }
+
+  mkdir(subpath: string, options?: { recursive?: boolean }): void {
+    this.assertWritable();
+    const fullPath = this.resolveSafe(subpath);
+    try {
+      this.fs.mkdirSync(fullPath, options);
+    } catch (err: unknown) {
+      throw this.wrapError(err, subpath);
+    }
+  }
+
+  rmdir(subpath: string): void {
+    this.assertWritable();
+    const fullPath = this.resolveSafe(subpath);
+    try {
+      this.fs.rmdirSync(fullPath);
+    } catch (err: unknown) {
+      throw this.wrapError(err, subpath);
+    }
+  }
+
+  rename(oldSubpath: string, newSubpath: string): void {
+    this.assertWritable();
+    const oldFull = this.resolveSafe(oldSubpath);
+    const newFull = this.resolveSafe(newSubpath);
+    try {
+      this.fs.renameSync(oldFull, newFull);
+    } catch (err: unknown) {
+      throw this.wrapError(err, newSubpath);
+    }
+  }
+
+  copyFile(srcSubpath: string, destSubpath: string): void {
+    this.assertWritable();
+    const srcFull = this.resolveSafe(srcSubpath);
+    const destFull = this.resolveSafe(destSubpath);
+    try {
+      this.fs.copyFileSync(srcFull, destFull);
+    } catch (err: unknown) {
+      throw this.wrapError(err, destSubpath);
+    }
+  }
+
+  // ─── Error mapping ───
+
+  private wrapError(err: unknown, subpath: string): VFSError {
+    if (err instanceof VFSError) return err;
+    const msg = err instanceof Error ? err.message : String(err);
+    const code = (err as { code?: string })?.code;
+    if (code === 'ENOENT') return new VFSError(ErrorCode.ENOENT, `'${subpath}': ${msg}`);
+    if (code === 'EEXIST') return new VFSError(ErrorCode.EEXIST, `'${subpath}': ${msg}`);
+    if (code === 'EISDIR') return new VFSError(ErrorCode.EISDIR, `'${subpath}': ${msg}`);
+    if (code === 'ENOTDIR') return new VFSError(ErrorCode.ENOTDIR, `'${subpath}': ${msg}`);
+    if (code === 'ENOTEMPTY') return new VFSError(ErrorCode.ENOTEMPTY, `'${subpath}': ${msg}`);
+    return new VFSError(ErrorCode.EINVAL, `'${subpath}': ${msg}`);
+  }
+}

package/src/substrate/lifo/kernel/vfs/providers/ProcProvider.ts

@@ -0,0 +1,144 @@
+import type { VirtualProvider, Stat, Dirent } from '../types.js';
+import { VFSError, ErrorCode } from '../types.js';
+import { encode } from '../../../utils/encoding.js';
+
+export class ProcProvider implements VirtualProvider {
+  private generators = new Map<string, () => string>();
+
+  constructor() {
+    this.generators.set('cpuinfo', () => {
+      const cores = typeof navigator !== 'undefined'
+        ? navigator.hardwareConcurrency ?? 1
+        : 1;
+      const lines: string[] = [];
+      for (let i = 0; i < cores; i++) {
+        lines.push(`processor\t: ${i}`);
+        lines.push(`model name\t: Browser Virtual CPU`);
+        lines.push(`cpu cores\t: ${cores}`);
+        lines.push('');
+      }
+      return lines.join('\n');
+    });
+
+    this.generators.set('meminfo', () => {
+      const perf = typeof performance !== 'undefined' ? performance : null;
+      const memory = (perf as unknown as { memory?: { jsHeapSizeLimit: number; usedJSHeapSize: number; totalJSHeapSize: number } })?.memory;
+      if (memory) {
+        const totalKB = Math.floor(memory.jsHeapSizeLimit / 1024);
+        const usedKB = Math.floor(memory.usedJSHeapSize / 1024);
+        const freeKB = totalKB - usedKB;
+        return [
+          `MemTotal:       ${totalKB} kB`,
+          `MemFree:        ${freeKB} kB`,
+          `MemUsed:        ${usedKB} kB`,
+          `HeapTotal:      ${Math.floor(memory.totalJSHeapSize / 1024)} kB`,
+          '',
+        ].join('\n');
+      }
+      return [
+        'MemTotal:       2097152 kB',
+        'MemFree:        1048576 kB',
+        'MemUsed:        1048576 kB',
+        '',
+      ].join('\n');
+    });
+
+    this.generators.set('uptime', () => {
+      const seconds = typeof performance !== 'undefined'
+        ? (performance.now() / 1000).toFixed(2)
+        : '0.00';
+      return `${seconds} ${seconds}\n`;
+    });
+
+    this.generators.set('version', () => {
+      const ua = typeof navigator !== 'undefined' ? navigator.userAgent : 'Node.js';
+      return `Lifo 1.0.0 (${ua})\n`;
+    });
+  }
+
+  private isNetPath(subpath: string): boolean {
+    return subpath === '/net' || subpath === '/net/info';
+  }
+
+  private getNetInfo(): string {
+    const conn = typeof navigator !== 'undefined'
+      ? (navigator as unknown as { connection?: { effectiveType?: string; downlink?: number; rtt?: number; type?: string } }).connection
+      : undefined;
+    if (conn) {
+      return [
+        `type:          ${conn.type ?? 'unknown'}`,
+        `effectiveType: ${conn.effectiveType ?? 'unknown'}`,
+        `downlink:      ${conn.downlink ?? 0} Mbps`,
+        `rtt:           ${conn.rtt ?? 0} ms`,
+        '',
+      ].join('\n');
+    }
+    return 'Network information not available\n';
+  }
+
+  private generate(subpath: string): string {
+    // Normalize: '/cpuinfo' -> 'cpuinfo'
+    const name = subpath.startsWith('/') ? subpath.slice(1) : subpath;
+
+    if (name === 'net/info') {
+      return this.getNetInfo();
+    }
+
+    const gen = this.generators.get(name);
+    if (!gen) {
+      throw new VFSError(ErrorCode.ENOENT, `'/proc${subpath}': no such file`);
+    }
+    return gen();
+  }
+
+  readFile(subpath: string): Uint8Array {
+    return encode(this.readFileString(subpath));
+  }
+
+  readFileString(subpath: string): string {
+    return this.generate(subpath);
+  }
+
+  exists(subpath: string): boolean {
+    if (subpath === '/') return true;
+    if (this.isNetPath(subpath)) return true;
+    const name = subpath.startsWith('/') ? subpath.slice(1) : subpath;
+    return this.generators.has(name);
+  }
+
+  stat(subpath: string): Stat {
+    if (!this.exists(subpath)) {
+      throw new VFSError(ErrorCode.ENOENT, `'/proc${subpath}': no such file`);
+    }
+
+    if (subpath === '/' || subpath === '/net') {
+      return { type: 'directory', size: 0, ctime: 0, mtime: Date.now(), mode: 0o555 };
+    }
+
+    const content = this.generate(subpath);
+    return {
+      type: 'file',
+      size: content.length,
+      ctime: 0,
+      mtime: Date.now(),
+      mode: 0o444,
+    };
+  }
+
+  readdir(subpath: string): Dirent[] {
+    if (subpath === '/') {
+      const entries: Dirent[] = [];
+      for (const name of this.generators.keys()) {
+        entries.push({ name, type: 'file' });
+      }
+      entries.push({ name: 'net', type: 'directory' });
+      return entries;
+    }
+
+    if (subpath === '/net') {
+      return [{ name: 'info', type: 'file' }];
+    }
+
+    throw new VFSError(ErrorCode.ENOTDIR, `'/proc${subpath}': not a directory`);
+  }
+}

package/src/substrate/lifo/kernel/vfs/types.ts

@@ -0,0 +1,145 @@
+import type { VfsCred } from '../../../../runtime/os-contracts.js';
+
+/**
+ * What a stat can report.
+ *
+ * `symlink` is here because a mounted provider can return one — the durable
+ * filesystem models symlinks — and the in-memory tree simply never produces
+ * it. Leaving it out did not make symlinks go away; it made the one mount
+ * that has them require a cast at every call site.
+ */
+export type FileType = 'file' | 'directory' | 'symlink';
+
+export type VFSEventType = 'create' | 'modify' | 'delete' | 'rename';
+
+export interface VFSWatchEvent {
+  type: VFSEventType;
+  path: string;
+  oldPath?: string; // only for 'rename'
+  fileType: FileType;
+}
+
+export type VFSWatchListener = (event: VFSWatchEvent) => void;
+
+export interface ChunkRef {
+  hash: string;
+  size: number;
+}
+
+export interface INode {
+  type: FileType;
+  name: string;
+  data: Uint8Array;         // file content (empty for dirs; empty for chunked files)
+  children: Map<string, INode>;  // dir entries (empty map for files)
+  ctime: number;
+  mtime: number;
+  mode: number;
+  mime?: string;            // MIME type (files only, auto-detected)
+  blobRef?: string;         // content-hash key into BlobStore (small files)
+  chunks?: ChunkRef[];      // chunk manifest for large files (>= 1MB)
+  storedSize?: number;      // authoritative size when chunked (data is empty)
+}
+
+/**
+ * `st_mode` file-type bits. `Stat.type` only distinguishes file from
+ * directory, so anything finer — a character device, a symlink — is carried
+ * in the mode, exactly as Unix does it. `ls -l` and `stat` read the leading
+ * type character from here.
+ */
+export const S_IFMT = 0o170000;
+export const S_IFREG = 0o100000;
+export const S_IFDIR = 0o040000;
+export const S_IFCHR = 0o020000;
+export const S_IFLNK = 0o120000;
+
+/** True for a character device such as `/dev/zero`, which streams rather than stores. */
+export function isCharacterDevice(mode: number): boolean {
+  return (mode & S_IFMT) === S_IFCHR;
+}
+
+/** The `ls -l` type character for a mode, falling back to the coarse `Stat.type`. */
+export function fileTypeChar(mode: number, type: FileType): string {
+  switch (mode & S_IFMT) {
+    case S_IFCHR: return 'c';
+    case S_IFLNK: return 'l';
+    case S_IFDIR: return 'd';
+    case S_IFREG: return '-';
+    default: return type === 'directory' ? 'd' : '-';
+  }
+}
+
+export interface Stat {
+  type: FileType;
+  size: number;
+  ctime: number;
+  mtime: number;
+  mode: number;
+  uid?: number;
+  gid?: number;
+  mime?: string;
+}
+
+export interface Dirent {
+  name: string;
+  type: FileType;
+}
+
+export const ErrorCode = {
+  ENOENT: 'ENOENT',
+  EEXIST: 'EEXIST',
+  ENOTDIR: 'ENOTDIR',
+  EISDIR: 'EISDIR',
+  ENOTEMPTY: 'ENOTEMPTY',
+  EINVAL: 'EINVAL',
+  EXDEV: 'EXDEV',
+} as const;
+
+export type ErrorCodeType = (typeof ErrorCode)[keyof typeof ErrorCode];
+
+export interface VirtualProvider {
+  readFile(subpath: string): Uint8Array;
+  readFileString(subpath: string): string;
+  /**
+   * Read at most `length` bytes at `offset` without materialising the whole
+   * file. Short reads are legal (read(2) semantics) — callers must loop until
+   * they get what they need or an empty result signals EOF. Providers that
+   * cannot serve a slice cheaply omit this; `VFS.readRange` then slices a
+   * whole-file read for them.
+   */
+  readRange?(subpath: string, offset: number, length: number): Uint8Array;
+  writeFile?(subpath: string, content: string | Uint8Array): void;
+  exists(subpath: string): boolean;
+  stat(subpath: string): Stat;
+  readdir(subpath: string): Dirent[];
+  access?(subpath: string, mode: number): void;
+  as?(cred: VfsCred): VirtualProvider;
+}
+
+export interface MountProvider extends VirtualProvider {
+  writeFile(subpath: string, content: string | Uint8Array): void;
+  /**
+   * Write `bytes` at `offset`, growing the file as needed, without rewriting
+   * the parts of it the range does not touch. Providers that cannot do this
+   * omit it; `VFS.writeRange` then splices via a whole-file read/write.
+   */
+  writeRange?(subpath: string, offset: number, bytes: Uint8Array): void;
+  truncate?(subpath: string, size: number): void;
+  unlink(subpath: string): void;
+  mkdir(subpath: string, options?: { recursive?: boolean }): void;
+  rmdir(subpath: string): void;
+  rename(oldSubpath: string, newSubpath: string): void;
+  copyFile(srcSubpath: string, destSubpath: string): void;
+  /** Set permission bits. Providers without chmod reject it (read-only fs). */
+  chmod?(subpath: string, mode: number): void;
+  chown?(subpath: string, uid: number | null, gid: number | null): void;
+}
+
+export class VFSError extends Error {
+  code: ErrorCodeType;
+
+  constructor(code: ErrorCodeType, message: string) {
+    super(`${code}: ${message}`);
+    this.code = code;
+    this.name = 'VFSError';
+  }
+}