typescript-virtual-container 1.4.6 → 1.4.8

package/src/VirtualFileSystem/index.ts

@@ -1,3 +1,4 @@
+/** biome-ignore-all lint/style/useNamingConvention: NW ? */
 import { EventEmitter } from "node:events";
 import * as fsSync from "node:fs";
 import * as path from "node:path";
@@ -18,7 +19,9 @@ import type {
 	InternalDirectoryNode,
 	InternalFileNode,
 	InternalNode,
+	InternalStubNode,
 } from "./internalTypes";
+import { appendJournalEntry, JournalOp, readJournal, truncateJournal } from "./journal";
 import { getNode, getParentDirectory, normalizePath } from "./path";
 
 // ── Persistence options ───────────────────────────────────────────────────────
@@ -46,6 +49,26 @@ export interface VfsOptions {
 	 * Required when `mode` is `"fs"`.
 	 */
 	snapshotPath?: string;
+	/**
+	 * Interval in milliseconds between automatic checkpoints in `"fs"` mode.
+	 * Set to `0` to disable automatic flushing (manual `flushMirror()` only).
+	 * Default: 30_000 (30 seconds).
+	 */
+	flushIntervalMs?: number;
+	/**
+	 * Trigger a checkpoint after this many write operations, regardless of the
+	 * timer interval. Prevents unbounded journal growth during bulk operations
+	 * (e.g. a 15 000-file SFTP transfer). Default: 500.
+	 * Set to `0` to disable write-count flushing.
+	 */
+	flushAfterNWrites?: number;
+	/**
+	 * Files larger than this threshold (bytes) are evicted from RAM after each
+	 * `flushMirror()` and reloaded on demand from the snapshot.
+	 * Default: 65536 (64 KB). Set to `0` to disable eviction.
+	 * Only applies to `"fs"` mode.
+	 */
+	evictionThresholdBytes?: number;
 }
 
 // ── VirtualFileSystem ─────────────────────────────────────────────────────────
@@ -77,6 +100,18 @@ class VirtualFileSystem extends EventEmitter {
 	private root: InternalDirectoryNode;
 	private readonly mode: VfsPersistenceMode;
 	private readonly snapshotFile: string | null;
+	/** Path to the WAL journal file (null in memory mode). */
+	private readonly journalFile: string | null;
+	/** Eviction threshold in bytes (0 = disabled). Files above this are purged after flush. */
+	private readonly evictionThreshold: number;
+	/** Max writes between forced flushes (0 = disabled). */
+	private readonly flushAfterNWrites: number;
+	/** Pending write counter since last checkpoint. */
+	private _writesSinceFlush = 0;
+	/** NodeJS timer handle for periodic auto-flush (null = disabled or stopped). */
+	private _flushTimer: ReturnType<typeof setInterval> | null = null;
+	/** True if the VFS has unflushed changes. */
+	private _dirty = false;
 	/** Active host-directory mounts: vPath → { hostPath, readOnly } */
 	private readonly mounts = new Map<string, { hostPath: string; readOnly: boolean }>();
 	/** True when running in a browser environment (no host FS access). */
@@ -96,8 +131,24 @@ class VirtualFileSystem extends EventEmitter {
 				options.snapshotPath,
 				"vfs-snapshot.vfsb",
 			);
+			this.journalFile = path.resolve(options.snapshotPath, "vfs-journal.bin");
+			this.evictionThreshold = options.evictionThresholdBytes ?? 64 * 1024; // 64 KB default
+			this.flushAfterNWrites = options.flushAfterNWrites ?? 500;
+			const intervalMs = options.flushIntervalMs ?? 30_000;
+			if (intervalMs > 0) {
+				this._flushTimer = setInterval(() => {
+					if (this._dirty) void this._autoFlush();
+				}, intervalMs);
+				// Don't block process exit on this timer
+				if (typeof this._flushTimer === "object" && this._flushTimer !== null && "unref" in this._flushTimer) {
+					(this._flushTimer as NodeJS.Timeout).unref();
+				}
+			}
 		} else {
 			this.snapshotFile = null;
+			this.journalFile = null;
+			this.evictionThreshold = 0; // disabled in memory mode
+			this.flushAfterNWrites = 0;
 		}
 		this.root = this.makeDir("", 0o755);
 	}
@@ -105,14 +156,15 @@ class VirtualFileSystem extends EventEmitter {
 	// ── Internal helpers ──────────────────────────────────────────────────────
 
 	private makeDir(name: string, mode: number): InternalDirectoryNode {
-		const now = new Date();
+		const now = Date.now();
 		return {
 			type: "directory",
 			name,
 			mode,
 			createdAt: now,
 			updatedAt: now,
-			children: new Map(),
+			children: Object.create(null) as Record<string, InternalNode>,
+			_childCount: 0,
 		};
 	}
 
@@ -122,7 +174,7 @@ class VirtualFileSystem extends EventEmitter {
 		mode: number,
 		compressed: boolean,
 	): InternalFileNode {
-		const now = new Date();
+		const now = Date.now();
 		return {
 			type: "file",
 			name,
@@ -134,6 +186,35 @@ class VirtualFileSystem extends EventEmitter {
 		};
 	}
 
+	private makeStub(name: string, content: string, mode: number): InternalStubNode {
+		const now = Date.now();
+		return { type: "stub", name, stubContent: content, mode, createdAt: now, updatedAt: now };
+	}
+
+	/**
+	 * Write a lazy stub — stores content as a plain string with no Buffer allocation.
+	 * Use for static rootfs files that may never be read. On first `writeFile()`,
+	 * the stub is promoted to a real `InternalFileNode`.
+	 * Parent directories are created when missing.
+	 */
+	public writeStub(targetPath: string, content: string, mode = 0o644): void {
+		const normalized = normalizePath(targetPath);
+		const { parent, name } = getParentDirectory(
+			this.root,
+			normalized,
+			true,
+			(p) => this.mkdirRecursive(p, 0o755),
+		);
+		const existing = parent.children[name];
+		if (existing?.type === "directory") {
+			throw new Error(`Cannot write stub '${normalized}': path is a directory.`);
+		}
+		// Don't overwrite a real file or an already-promoted node
+		if (existing?.type === "file") return;
+		if (!existing) parent._childCount++;
+		parent.children[name] = this.makeStub(name, content, mode);
+	}
+
 	private mkdirRecursive(targetPath: string, mode: number): void {
 		const normalized = normalizePath(targetPath);
 		if (normalized === "/") return;
@@ -142,11 +223,13 @@ class VirtualFileSystem extends EventEmitter {
 		let builtPath = "";
 		for (const part of parts) {
 			builtPath += `/${part}`;
-			let child = current.children.get(part);
+			let child = current.children[part];
 			if (!child) {
 				child = this.makeDir(part, mode);
-				current.children.set(part, child);
+				current.children[part] = child;
+				current._childCount++;
 				this.emit("dir:create", { path: builtPath, mode });
+				this._journal({ op: JournalOp.MKDIR, path: builtPath, mode });
 			} else if (child.type !== "directory") {
 				throw new Error(
 					`Cannot create directory '${builtPath}': path is a file.`,
@@ -168,7 +251,14 @@ class VirtualFileSystem extends EventEmitter {
 	public async restoreMirror(): Promise<void> {
 		if (this.mode !== "fs" || !this.snapshotFile) return;
 
-		if (!fsSync.existsSync(this.snapshotFile)) return;
+		if (!fsSync.existsSync(this.snapshotFile)) {
+			// No snapshot yet — but replay journal if it exists (crash after writes, before first flush)
+			if (this.journalFile) {
+				const entries = readJournal(this.journalFile);
+				if (entries.length > 0) this._replayJournal(entries);
+			}
+			return;
+		}
 
 		try {
 			const raw = fsSync.readFileSync(this.snapshotFile);
@@ -184,6 +274,11 @@ class VirtualFileSystem extends EventEmitter {
 				);
 			}
 			this.emit("snapshot:restore", { path: this.snapshotFile });
+			// Replay WAL journal on top of the loaded snapshot
+			if (this.journalFile) {
+				const entries = readJournal(this.journalFile);
+				if (entries.length > 0) this._replayJournal(entries);
+			}
 		} catch (err) {
 			// Corrupt or unreadable snapshot — start fresh and warn
 			console.warn(
@@ -210,7 +305,13 @@ class VirtualFileSystem extends EventEmitter {
 		fsSync.mkdirSync(dir, { recursive: true });
 		const binary = encodeVfs(this.root);
 		fsSync.writeFileSync(this.snapshotFile, binary);
+		// Checkpoint complete — truncate the journal (entries are now in the snapshot)
+		if (this.journalFile) truncateJournal(this.journalFile);
+		this._dirty = false;
+		this._writesSinceFlush = 0;
 		this.emit("mirror:flush", { path: this.snapshotFile });
+		// Evict large files from RAM now that the snapshot is on disk
+		this.evictLargeFiles();
 	}
 
 	/** Returns the current persistence mode. */
@@ -227,6 +328,174 @@ class VirtualFileSystem extends EventEmitter {
 
 	/** Creates a directory (and any missing parents). */
 
+
+
+	// ── Auto-flush scheduler ──────────────────────────────────────────────────
+
+	/** Internal: flush triggered by timer or write-count threshold. */
+	private async _autoFlush(): Promise<void> {
+		if (!this._dirty) return;
+		await this.flushMirror();
+	}
+
+	/** Mark VFS as having unflushed writes and trigger threshold flush if needed. */
+	private _markDirty(): void {
+		this._dirty = true;
+		if (this.flushAfterNWrites > 0) {
+			this._writesSinceFlush++;
+			if (this._writesSinceFlush >= this.flushAfterNWrites) {
+				this._writesSinceFlush = 0;
+				void this._autoFlush();
+			}
+		}
+	}
+
+	/**
+	 * Stop the automatic flush timer and perform a final checkpoint.
+	 * Call this when shutting down to ensure all data is persisted.
+	 *
+	 * @example
+	 * ```ts
+	 * process.on("SIGINT", async () => {
+	 *   await shell.vfs.stopAutoFlush();
+	 *   process.exit(0);
+	 * });
+	 * ```
+	 */
+	public async stopAutoFlush(): Promise<void> {
+		if (this._flushTimer !== null) {
+			clearInterval(this._flushTimer);
+			this._flushTimer = null;
+		}
+		if (this._dirty) await this.flushMirror();
+	}
+
+	/**
+	 * Replace the entire root tree — used internally by `bootstrapLinuxRootfs`
+	 * to hot-swap the static rootfs snapshot without going through importSnapshot
+	 * (which would re-journal every node in fs mode).
+	 * @internal
+	 */
+	public importRootTree(root: InternalDirectoryNode): void {
+		const prev = this._replayMode;
+		this._replayMode = true;
+		try { this.root = root; } finally { this._replayMode = prev; }
+	}
+
+	/** Serialise current tree to VFSB binary. Used for the static rootfs cache. */
+	public encodeBinary(): Buffer {
+		return encodeVfs(this.root);
+	}
+
+	/**
+	 * Release the in-memory VFS tree, freeing all InternalNode objects for GC.
+	 * The tree MUST be restored via `importRootTree()` before any VFS operation.
+	 * Called by IdleManager when freezing an idle shell.
+	 * @internal
+	 */
+	public releaseTree(): void {
+		// Replace root with a minimal stub — keeps the object alive but frees all children
+		this.root = this.makeDir("", 0o755);
+	}
+
+	/** Set to true during journal replay to suppress re-journaling. */
+	private _replayMode = false;
+
+	/** Append a journal entry if in fs mode and not replaying. */
+	private _journal(entry: Parameters<typeof appendJournalEntry>[1]): void {
+		if (this.journalFile && !this._replayMode) {
+			appendJournalEntry(this.journalFile, entry);
+			this._markDirty();
+		}
+	}
+
+	/** Replay a list of journal entries onto the in-memory tree. */
+	private _replayJournal(entries: ReturnType<typeof readJournal>): void {
+		this._replayMode = true;
+		try {
+			for (const e of entries) {
+				try {
+					if (e.op === JournalOp.WRITE) {
+						this.writeFile(e.path, e.content ?? Buffer.alloc(0), { mode: e.mode });
+					} else if (e.op === JournalOp.MKDIR) {
+						this.mkdir(e.path, e.mode);
+					} else if (e.op === JournalOp.REMOVE) {
+						if (this.exists(e.path)) this.remove(e.path, { recursive: true });
+					} else if (e.op === JournalOp.CHMOD) {
+						if (this.exists(e.path)) this.chmod(e.path, e.mode ?? 0o644);
+					} else if (e.op === JournalOp.MOVE) {
+						if (this.exists(e.path) && e.dest) this.move(e.path, e.dest);
+					} else if (e.op === JournalOp.SYMLINK) {
+						if (e.dest) this.symlink(e.dest, e.path);
+					}
+				} catch { /* ignore individual replay errors — best-effort */ }
+			}
+		} finally {
+			this._replayMode = false;
+		}
+	}
+
+
+	// ── RAM eviction ──────────────────────────────────────────────────────────
+
+	/**
+	 * Walk the in-memory tree and evict file contents that exceed
+	 * `evictionThreshold`. Called automatically after `flushMirror()`.
+	 * Safe to call at any time — evicted files are reloaded on demand.
+	 */
+	public evictLargeFiles(): void {
+		if (!this.snapshotFile || this.evictionThreshold === 0) return;
+		if (!fsSync.existsSync(this.snapshotFile)) return;
+		this._evictDir(this.root);
+	}
+
+	private _evictDir(dir: InternalDirectoryNode): void {
+		for (const node of Object.values(dir.children)) {
+			if (node.type === "directory") {
+				this._evictDir(node);
+			} else if (node.type === "file" && !node.evicted) {
+				const rawSize = node.compressed
+					? (node.size ?? node.content.length * 2) // estimate uncompressed
+					: node.content.length;
+				if (rawSize > this.evictionThreshold) {
+					node.size    = rawSize;
+					node.content = Buffer.alloc(0); // free heap
+					node.evicted = true;
+				}
+			}
+			// stubs: nothing to evict — content is already a plain string, not a Buffer
+		}
+	}
+
+	/**
+	 * Reload a single evicted file node's content from the current snapshot.
+	 * No-op if the node is not evicted.
+	 */
+	private _reloadEvicted(node: InternalFileNode, normalizedPath: string): void {
+		if (!node.evicted || !this.snapshotFile) return;
+		if (!fsSync.existsSync(this.snapshotFile)) return;
+		try {
+			// Load and parse the snapshot to find this specific node
+			const raw = fsSync.readFileSync(this.snapshotFile);
+			const tmpRoot = decodeVfs(raw);
+			const parts = normalizedPath.split("/").filter(Boolean);
+			let cur: InternalNode = tmpRoot;
+			for (const part of parts) {
+				if (cur.type !== "directory") return;
+				const next: InternalNode | undefined = cur.children[part];
+				if (!next) return;
+				cur = next;
+			}
+			if (cur.type === "file") {
+				node.content = cur.content;
+				node.compressed = cur.compressed;
+				node.evicted = undefined;
+			}
+		} catch {
+			// Snapshot unreadable — leave evicted; caller will get empty content
+		}
+	}
+
 	// ── Mount API ─────────────────────────────────────────────────────────────
 
 	/**
@@ -359,7 +628,7 @@ class VirtualFileSystem extends EventEmitter {
 			(p) => this.mkdirRecursive(p, 0o755),
 		);
 
-		const existing = parent.children.get(name);
+		const existing = parent.children[name];
 		if (existing?.type === "directory") {
 			throw new Error(
 				`Cannot write file '${normalized}': path is a directory.`,
@@ -373,20 +642,21 @@ class VirtualFileSystem extends EventEmitter {
 		const storedContent = shouldCompress ? gzipSync(rawContent) : rawContent;
 		const mode = options.mode ?? 0o644;
 
-		if (existing) {
+		if (existing && existing.type === "file") {
+			// Update real file in place
 			const f = existing as InternalFileNode;
 			f.content = storedContent;
 			f.compressed = shouldCompress;
 			f.mode = mode;
-			f.updatedAt = new Date();
+			f.updatedAt = Date.now();
 		} else {
-			parent.children.set(
-				name,
-				this.makeFile(name, storedContent, mode, shouldCompress),
-			);
+			// Create new real file — also promotes stubs (no _childCount change for stubs)
+			if (!existing) parent._childCount++;
+			parent.children[name] = this.makeFile(name, storedContent, mode, shouldCompress);
 		}
 
 		this.emit("file:write", { path: normalized, size: storedContent.length });
+		this._journal({ op: JournalOp.WRITE, path: normalized, content: rawContent, mode });
 	}
 
 	/**
@@ -401,10 +671,15 @@ class VirtualFileSystem extends EventEmitter {
 		}
 		const normalized = normalizePath(targetPath);
 		const node = getNode(this.root, normalized);
+		if (node.type === "stub") {
+			this.emit("file:read", { path: normalized, size: node.stubContent.length });
+			return node.stubContent;
+		}
 		if (node.type !== "file") {
 			throw new Error(`Cannot read '${targetPath}': not a file.`);
 		}
 		const f = node as InternalFileNode;
+		if (f.evicted) this._reloadEvicted(f, normalized);
 		const raw = f.compressed ? gunzipSync(f.content) : f.content;
 		this.emit("file:read", { path: normalized, size: raw.length });
 		return raw.toString("utf8");
@@ -419,10 +694,16 @@ class VirtualFileSystem extends EventEmitter {
 		}
 		const normalized = normalizePath(targetPath);
 		const node = getNode(this.root, normalized);
+		if (node.type === "stub") {
+			const buf = Buffer.from(node.stubContent, "utf8");
+			this.emit("file:read", { path: normalized, size: buf.length });
+			return buf;
+		}
 		if (node.type !== "file") {
 			throw new Error(`Cannot read '${targetPath}': not a file.`);
 		}
 		const f = node as InternalFileNode;
+		if (f.evicted) this._reloadEvicted(f, normalized);
 		const raw = f.compressed ? gunzipSync(f.content) : f.content;
 		this.emit("file:read", { path: normalized, size: raw.length });
 		return raw;
@@ -442,7 +723,9 @@ class VirtualFileSystem extends EventEmitter {
 
 	/** Updates mode bits on a node. */
 	public chmod(targetPath: string, mode: number): void {
-		getNode(this.root, normalizePath(targetPath)).mode = mode;
+		const normalized = normalizePath(targetPath);
+		getNode(this.root, normalized).mode = mode;
+		this._journal({ op: JournalOp.CHMOD, path: normalized, mode });
 	}
 
 	/** Returns metadata for a file or directory. */
@@ -478,6 +761,19 @@ class VirtualFileSystem extends EventEmitter {
 		const normalized = normalizePath(targetPath);
 		const node = getNode(this.root, normalized);
 		const name = normalized === "/" ? "" : path.posix.basename(normalized);
+		if (node.type === "stub") {
+			const s = node as InternalStubNode;
+			return {
+				type: "file",
+				name,
+				path: normalized,
+				mode: s.mode,
+				createdAt: new Date(s.createdAt),
+				updatedAt: new Date(s.updatedAt),
+				compressed: false,
+				size: s.stubContent.length,
+			};
+		}
 		if (node.type === "file") {
 			const f = node as InternalFileNode;
 			return {
@@ -485,10 +781,10 @@ class VirtualFileSystem extends EventEmitter {
 				name,
 				path: normalized,
 				mode: f.mode,
-				createdAt: f.createdAt,
-				updatedAt: f.updatedAt,
+				createdAt: new Date(f.createdAt),
+				updatedAt: new Date(f.updatedAt),
 				compressed: f.compressed,
-				size: f.content.length,
+				size: f.evicted ? (f.size ?? 0) : f.content.length,
 			};
 		}
 		const d = node as InternalDirectoryNode;
@@ -497,9 +793,9 @@ class VirtualFileSystem extends EventEmitter {
 			name,
 			path: normalized,
 			mode: d.mode,
-			createdAt: d.createdAt,
-			updatedAt: d.updatedAt,
-			childrenCount: d.children.size,
+			createdAt: new Date(d.createdAt),
+			updatedAt: new Date(d.updatedAt),
+			childrenCount: d._childCount,
 		};
 	}
 
@@ -517,7 +813,7 @@ class VirtualFileSystem extends EventEmitter {
 		if (node.type !== "directory") {
 			throw new Error(`Cannot list '${dirPath}': not a directory.`);
 		}
-		return Array.from((node as InternalDirectoryNode).children.keys()).sort();
+		return Object.keys((node as InternalDirectoryNode).children).sort();
 	}
 
 	/** Renders ASCII tree view of a directory hierarchy. */
@@ -533,10 +829,10 @@ class VirtualFileSystem extends EventEmitter {
 
 	private renderTreeLines(dir: InternalDirectoryNode, label: string): string {
 		const lines = [label];
-		const entries = Array.from(dir.children.keys()).sort();
+		const entries = Object.keys(dir.children).sort();
 		for (let i = 0; i < entries.length; i++) {
 			const name = entries[i]!;
-			const child = dir.children.get(name)!;
+			const child = dir.children[name]!;
 			const isLast = i === entries.length - 1;
 			const connector = isLast ? "└── " : "├── ";
 			const nextPrefix = isLast ? "    " : "│   ";
@@ -559,8 +855,9 @@ class VirtualFileSystem extends EventEmitter {
 
 	private computeUsage(node: InternalNode): number {
 		if (node.type === "file") return (node as InternalFileNode).content.length;
+		if (node.type === "stub") return node.stubContent.length;
 		let total = 0;
-		for (const child of (node as InternalDirectoryNode).children.values()) {
+		for (const child of Object.values((node as InternalDirectoryNode).children)) {
 			total += this.computeUsage(child);
 		}
 		return total;
@@ -575,7 +872,7 @@ class VirtualFileSystem extends EventEmitter {
 		if (!f.compressed) {
 			f.content = gzipSync(f.content);
 			f.compressed = true;
-			f.updatedAt = new Date();
+			f.updatedAt = Date.now();
 		}
 	}
 
@@ -588,7 +885,7 @@ class VirtualFileSystem extends EventEmitter {
 		if (f.compressed) {
 			f.content = gunzipSync(f.content);
 			f.compressed = false;
-			f.updatedAt = new Date();
+			f.updatedAt = Date.now();
 		}
 	}
 
@@ -613,10 +910,13 @@ class VirtualFileSystem extends EventEmitter {
 			content: Buffer.from(normalizedTarget, "utf8"),
 			mode: 0o120777,
 			compressed: false,
-			createdAt: new Date(),
-			updatedAt: new Date(),
+			createdAt: Date.now(),
+			updatedAt: Date.now(),
 		};
-		parent.children.set(name, symNode);
+		parent.children[name] = symNode;
+		parent._childCount++;
+		// Journal before emit
+		this._journal({ op: JournalOp.SYMLINK, path: normalizedLink, dest: normalizedTarget });
 		this.emit("symlink:create", {
 			link: normalizedLink,
 			target: normalizedTarget,
@@ -678,7 +978,7 @@ class VirtualFileSystem extends EventEmitter {
 		const node = getNode(this.root, normalized);
 		if (node.type === "directory") {
 			const dir = node as InternalDirectoryNode;
-			if (!options.recursive && dir.children.size > 0) {
+			if (!options.recursive && dir._childCount > 0) {
 				throw new Error(
 					`Directory '${normalized}' is not empty. Use recursive option.`,
 				);
@@ -690,8 +990,9 @@ class VirtualFileSystem extends EventEmitter {
 			false,
 			() => {},
 		);
-		parent.children.delete(name);
-		this.emit("node:remove", { path: normalized });
+		delete parent.children[name];
+		parent._childCount--;		this.emit("node:remove", { path: normalized });
+		this._journal({ op: JournalOp.REMOVE, path: normalized });
 	}
 
 	/** Moves or renames a node. */
@@ -718,9 +1019,12 @@ class VirtualFileSystem extends EventEmitter {
 			false,
 			() => {},
 		);
-		srcParent.children.delete(srcName);
+		delete srcParent.children[srcName];
+		srcParent._childCount--;
 		node.name = destName;
-		destParent.children.set(destName, node);
+		destParent.children[destName] = node;
+		destParent._childCount++;
+		this._journal({ op: JournalOp.MOVE, path: fromNormalized, dest: toNormalized });
 	}
 
 	// ── Snapshot serialisation ─────────────────────────────────────────────────
@@ -737,19 +1041,30 @@ class VirtualFileSystem extends EventEmitter {
 
 	private serializeDir(dir: InternalDirectoryNode): VfsSnapshotDirectoryNode {
 		const children: VfsSnapshotNode[] = [];
-		for (const child of dir.children.values()) {
-			children.push(
-				child.type === "file"
-					? this.serializeFile(child as InternalFileNode)
-					: this.serializeDir(child as InternalDirectoryNode),
-			);
+		for (const child of Object.values(dir.children)) {
+			if (child.type === "stub") {
+				// Serialize stub as a regular file node
+				children.push({
+					type: "file",
+					name: child.name,
+					mode: child.mode,
+					createdAt: new Date(child.createdAt).toISOString(),
+					updatedAt: new Date(child.updatedAt).toISOString(),
+					compressed: false,
+					contentBase64: Buffer.from(child.stubContent, "utf8").toString("base64"),
+				} satisfies VfsSnapshotFileNode);
+			} else if (child.type === "file") {
+				children.push(this.serializeFile(child as InternalFileNode));
+			} else {
+				children.push(this.serializeDir(child as InternalDirectoryNode));
+			}
 		}
 		return {
 			type: "directory",
 			name: dir.name,
 			mode: dir.mode,
-			createdAt: dir.createdAt.toISOString(),
-			updatedAt: dir.updatedAt.toISOString(),
+			createdAt: new Date(dir.createdAt).toISOString(),
+			updatedAt: new Date(dir.updatedAt).toISOString(),
 			children,
 		};
 	}
@@ -759,8 +1074,8 @@ class VirtualFileSystem extends EventEmitter {
 			type: "file",
 			name: file.name,
 			mode: file.mode,
-			createdAt: file.createdAt.toISOString(),
-			updatedAt: file.updatedAt.toISOString(),
+			createdAt: new Date(file.createdAt).toISOString(),
+			updatedAt: new Date(file.updatedAt).toISOString(),
 			compressed: file.compressed,
 			contentBase64: file.content.toString("base64"),
 		};
@@ -802,29 +1117,31 @@ class VirtualFileSystem extends EventEmitter {
 			type: "directory",
 			name,
 			mode: snap.mode,
-			createdAt: new Date(snap.createdAt),
-			updatedAt: new Date(snap.updatedAt),
-			children: new Map(),
+			createdAt: Date.parse(snap.createdAt),
+			updatedAt: Date.parse(snap.updatedAt),
+			children: Object.create(null) as Record<string, InternalNode>,
+			_childCount: 0,
 		};
 		for (const child of snap.children) {
 			if (child.type === "file") {
 				const f = child as VfsSnapshotFileNode;
-				dir.children.set(f.name, {
+				dir.children[f.name] = {
 					type: "file",
 					name: f.name,
 					mode: f.mode,
-					createdAt: new Date(f.createdAt),
-					updatedAt: new Date(f.updatedAt),
+					createdAt: Date.parse(f.createdAt),
+					updatedAt: Date.parse(f.updatedAt),
 					compressed: f.compressed,
 					content: Buffer.from(f.contentBase64, "base64"),
-				});
+				};
 			} else {
 				const sub = this.deserializeDir(
 					child as VfsSnapshotDirectoryNode,
 					child.name,
 				);
-				dir.children.set(child.name, sub);
+				dir.children[child.name] = sub;
 			}
+			dir._childCount++;
 		}
 		return dir;
 	}