Struct VirtualFs 

pub struct VirtualFs { /* private fields */ }

Copy-on-write filesystem over one immutable snapshot.

Implementations

impl VirtualFs

pub fn new(base: BaseSnapshot) -> VirtualFs

Begin a new isolated virtual transaction.

pub fn base_node_count(&self) -> usize

Return the number of base manifest nodes, including the virtual root.

pub fn with_effect_origin<T>( &mut self, origin: EffectOrigin, operation: impl FnOnce(&mut VirtualFs) -> T, ) -> T

Run an operation while attributing every emitted effect to origin.

Adapters use this narrow scope to preserve the typed source of observations without duplicating filesystem semantics. Nested scopes restore the previous origin when the operation returns.

pub fn base_snapshot_id(&self) -> SnapshotId

Return the immutable base snapshot identity.

pub fn exists(&mut self, path: &VPath) -> bool

Test path existence and record the metadata dependency.

pub fn metadata(&mut self, path: &VPath) -> Result<NodeState, VfsError>

Read virtual metadata without following symbolic links.

Errors

Returns VfsError::NotFound when path is absent.

pub fn read(&mut self, path: &VPath) -> Result<Vec<u8>, VfsError>

Read regular-file bytes from virtual state.

Errors

Returns an error for absent paths, non-files, stale lazy content, or blob-store verification failures.

pub fn read_link(&mut self, path: &VPath) -> Result<Vec<u8>, VfsError>

Read an opaque symbolic-link target without following it.

Errors

Returns an error for absent paths, non-links, stale lazy content, or blob errors.

pub fn read_dir(&mut self, path: &VPath) -> Result<Vec<VPath>, VfsError>

List immediate child paths in canonical order.

Errors

Returns an error when path is absent or not a directory.

pub fn write(&mut self, path: &VPath, bytes: &[u8]) -> Result<(), VfsError>

Create or replace a regular file in the overlay.

Errors

Returns an error when the parent is absent/non-directory, the target is a directory/link, or immutable blob storage fails.

pub fn append(&mut self, path: &VPath, suffix: &[u8]) -> Result<(), VfsError>

Append bytes to a regular file using the same read/write semantics.

Errors

Returns the same errors as Self::read or Self::write.

pub fn mkdir(&mut self, path: &VPath, mode: u32) -> Result<(), VfsError>

Create one empty directory.

Errors

Returns an error when the path exists or its parent is unavailable.

pub fn unlink(&mut self, path: &VPath) -> Result<(), VfsError>

Delete one regular file or opaque symbolic link.

Errors

Returns an error when the path is absent or is a directory/root.

pub fn rmdir(&mut self, path: &VPath) -> Result<(), VfsError>

Delete one empty directory.

Errors

Returns an error when the path is absent, non-directory, non-empty, or root.

pub fn remove_tree(&mut self, path: &VPath) -> Result<(), VfsError>

Recursively delete a virtual subtree while expanding every affected write.

Errors

Returns an error when the root path is absent or targets the virtual root.

pub fn rename(&mut self, from: &VPath, to: &VPath) -> Result<(), VfsError>

Move a file, link, or directory subtree without touching the host.

Existing non-directory destinations are replaced. A directory may replace only an empty directory. Symlinks are moved as opaque nodes and never followed.

Errors

Returns an error for root/overlapping moves, absent sources, invalid parents, or incompatible/non-empty destinations.

pub fn canonical_diff(&self) -> Result<CanonicalDiff, VfsError>

Produce the exact path-ordered diff between base and final virtual state.

Descendant closure is expanded for subtree tombstones, so a recursive delete is never represented as a misleading one-path change.

Errors

Returns an error if changed lazy content cannot be captured and verified.

pub fn effects(&self) -> &[EffectEvent]

Return the observed effect ledger.

This excludes host-only evidence capture.

pub fn capture_before_content<'a>( &self, paths: impl IntoIterator<Item = &'a VPath>, maximum: usize, ) -> Result<(), VfsError>

Capture bounded base content before finalizing a reviewable transaction.

The trusted caller must authorize content reads for every supplied path. Existing read/write observations and guest effects are not modified. Call canonical_diff afterwards to bind any newly materialized before identities. Paths exceeding the remaining byte budget retain their lazy stamp.

Errors

Returns an error if base content changed during capture or cannot be read.

pub fn read_set(&self) -> &BTreeMap<VPath, ReadObservation>

Return base dependencies observed by virtual execution.

pub fn write_set(&self) -> &BTreeMap<VPath, WritePrecondition>

Return base preconditions for every virtual write.

pub fn metrics(&self) -> VfsMetrics

Return bounded transaction-local size metrics.

pub fn materialized_final_state( &self, ) -> Result<BTreeMap<VPath, NodeState>, VfsError>

Materialize final virtual state for verification/test harnesses.

This intentionally scans the full snapshot and is not used by transaction hot paths; production decisions use Self::canonical_diff.

Errors

Returns an error when visible lazy content cannot be verified.