Virtual Filesystem (VFS)

All tool operations are mediated through a Virtual Filesystem (VFS) layer inspired by FUSE.

Architecture Overview

The VFS sits between the tool handlers and the underlying cache/provider layers, providing immediate write visibility and FUSE-like cache coherence.

Read/Write Flow

Operation Resolution

Operation	Resolution
get()	Cache hit → return. Tombstoned → throw. Else → provider fallback.
stat()	Inode overlay → cached content size → provider headObject.
list()	Provider listing – tombstones + overlay dirIndex entries.
put()	Cache set + markDirty + inode update + dirIndex. Immediate visibility.
remove()	Provider deleteObject + cache evict + tombstone. Immediate invisibility.

Key Components

Inodes

The inode table is an in-memory map of file metadata (size, timestamps, content hash). When a file is written, the inode is immediately updated — subsequent stat() calls reflect the new state without waiting for the provider flush.

DirIndex

The directory index tracks parent-child relationships. When a file is written to s3://bucket/a/b/c.txt, the dirIndex records:

• a/ contains b/
• a/b/ contains c.txt

This allows list_directory to return newly created files immediately, even before they're flushed to the provider.

Tombstones

When a file is deleted, a tombstone marker prevents it from reappearing via provider listing or cache reads. Tombstones are cleared once the delete propagates to the provider.

Persistence

VFS metadata is persisted to the CacheStore under __vfs__/* keys. On startup, VirtualFS.hydrate() restores state; corrupted data is silently discarded. This allows the VFS to survive process restarts when using a persistent cache backend (filesystem or Redis).

Write-Back Flushing

Dirty entries are flushed to the provider after a configurable debounce window (default: 2000ms). The vfs.flush() method is called on graceful shutdown to ensure no data is lost.