Module fs 

Filesystem methods + path guards + supporting types + the in-process VirtualFileSystem mount contract.

Ported from packages/core/src/agent-os.ts (fs methods + _assertSafeAbsolutePath / _assertWritableAbsolutePath), runtime-compat.ts (VirtualStat, VirtualFileSystem), and filesystem-snapshot.ts (snapshot export types).

Parity notes: every method runs the path guards first; mkdir recursive uses the WRITABLE guard, non-recursive uses the SAFE guard. writeFile does NOT create parents; writeFiles DOES. Batch methods NEVER reject (per-entry error strings). Snapshot wire format keeps octal-string mode and utf8/base64 content verbatim.

Structs

BatchReadResult

Result of a single batch read (never an Err). content is None on failure.

BatchWriteEntry

A batch write entry.

BatchWriteResult

Result of a single batch write (never an Err).

DeleteOptions

Options for delete.

DirEntry

An entry returned by readdir_recursive.

FilesystemEntry

A single snapshot entry. mode is an OCTAL STRING (e.g. "0755"). content is utf8 or base64.

FilesystemSnapshotEntries

{ entries: FilesystemEntry[] }.

FilesystemSnapshotExport

{ format: "agentos-filesystem-snapshot-v1"; filesystem: { entries } }.

MkdirOptions

Options for mkdir.

MountFsOptions

Options for mount_fs.

MountedFs

A registered in-process mount: the live VirtualFileSystem driver plus the read_only flag forwarded from MountFsOptions. TS mountFs passes { readOnly } through to kernel.mountFs, which enforces read-only mount semantics; the flag is retained here so the option is not structurally dropped before the mount-dispatch path consumes it.

ReaddirRecursiveOptions

Options for readdir_recursive. max_depth None = unlimited, Some(0) = immediate children only; exclude matches basenames at any depth.

RootSnapshotExport

{ kind: "snapshot-export"; source }.

VirtualDirEntry

A directory entry with a known type, returned by read_dir_with_types on the mount contract.

VirtualStat

Stat result. 16 fields; *_ms time fields are f64 (JS ms, possibly fractional).

Enums

DirEntryType

The type of a directory entry.

FileContent

string | Uint8Array file content.

FilesystemEntryEncoding

Snapshot content encoding.

SnapshotExportKind

The literal "snapshot-export" tag.

Traits

VirtualFileSystem

The 25-method mount backend contract. A mount_fs driver implements this trait; it is a live in-process object and cannot cross an RPC boundary.