Struct VersionedFileEntry 

pub struct VersionedFileEntry {

    pub path: String,
    pub file_type: FileType,
    pub permissions: FilePermissions,
    pub symlink_target: Option<String>,
    pub hardlink_target: Option<String>,
    pub device_id: Option<(u32, u32)>,
    pub is_text: bool,
    pub size: usize,
    pub chunks: Vec<ChunkId>,
    pub chunk_offsets: Option<Vec<ChunkOffset>>,
    pub deleted: bool,
    pub compression_codec: Option<u8>,
    pub uncompressed_size: Option<usize>,
    pub encoding_format: Option<u8>,
    pub version: u64,
    pub created_at: Instant,
    pub modified_at: Instant,
}

A versioned file entry in the manifest

Fields

path: String

File path (relative to engram root)

file_type: FileType

Type of file (regular, symlink, device, etc.)

permissions: FilePermissions

Unix permissions (uid, gid, mode)

symlink_target: Option<String>

Symlink target path (only for FileType::Symlink)

hardlink_target: Option<String>

Hardlink target path (only for FileType::Hardlink)

device_id: Option<(u32, u32)>

Device major/minor numbers (only for char/block devices)

is_text: bool

Is this a text file? (affects encoding strategy)

size: usize

Size of the file in bytes

chunks: Vec<ChunkId>

List of chunk IDs that make up this file

chunk_offsets: Option<Vec<ChunkOffset>>

Byte-offset index for range queries (optional for backward compatibility)

When present, enables O(log n) byte-offset lookups instead of sequential scanning. Each entry maps a chunk ID to its byte offset within the file. If None, offsets can be computed from chunk sizes (requires chunk_store access).

deleted: bool

Is this file marked as deleted? (soft delete)

compression_codec: Option<u8>

Compression codec used (0=None, 1=Zstd, 2=Lz4) None means no compression (backward compatible)

uncompressed_size: Option<usize>

Original uncompressed size (for compressed files)

encoding_format: Option<u8>

Encoding format version for holographic storage 0 = Legacy (Codebook.project() - ~0% accuracy) 1 = ReversibleVSA (ReversibleVSAEncoder - ~94% accuracy) None = standard VSA encoding (not holographic)

version: u64

Version number of this file entry

created_at: Instant

When this file was created

modified_at: Instant

When this file was last modified

Implementations

impl VersionedFileEntry

pub fn new( path: String, is_text: bool, size: usize, chunks: Vec<ChunkId>, ) -> Self

Create a new file entry for a regular file

pub fn new_with_metadata( path: String, file_type: FileType, permissions: FilePermissions, is_text: bool, size: usize, chunks: Vec<ChunkId>, ) -> Self

Create a new file entry with full metadata

pub fn new_symlink( path: String, target: String, permissions: FilePermissions, ) -> Self

Create a symlink entry

pub fn new_hardlink( path: String, target: String, permissions: FilePermissions, ) -> Self

Create a hardlink entry

pub fn new_device( path: String, is_char: bool, major: u32, minor: u32, permissions: FilePermissions, ) -> Self

Create a device node entry (Option C: with encoded data)

Option C encodes actual device data for block devices (e.g., loop devices). For most devices in /dev, this will be empty. For block devices with actual content (like a disk image mounted as a loop device), this allows encoding the full device content.

Arguments

• path - Device path (e.g., “/dev/loop0”)
• is_char - true for character device, false for block device
• major - Major device number
• minor - Minor device number
• permissions - Unix permissions
• size - Size of device data (0 for metadata-only)
• chunks - Chunk IDs for device data (empty for metadata-only)

pub fn new_device_with_data( path: String, is_char: bool, major: u32, minor: u32, permissions: FilePermissions, size: usize, chunks: Vec<ChunkId>, ) -> Self

Create a device node entry with data (Option C full encoding)

Use this for block devices that have actual content to encode, such as loop devices or disk images.

pub fn new_device_compressed( path: String, is_char: bool, major: u32, minor: u32, permissions: FilePermissions, compressed_size: usize, uncompressed_size: usize, compression_codec: u8, chunks: Vec<ChunkId>, ) -> Self

Create a device node with compressed data (Option C)

pub fn new_special( path: String, file_type: FileType, permissions: FilePermissions, ) -> Self

Create a special file entry (FIFO or socket - metadata only)

pub fn new_compressed( path: String, is_text: bool, compressed_size: usize, uncompressed_size: usize, compression_codec: u8, chunks: Vec<ChunkId>, ) -> Self

Create a new file entry with compression metadata

pub fn new_compressed_with_metadata( path: String, permissions: FilePermissions, is_text: bool, compressed_size: usize, uncompressed_size: usize, compression_codec: u8, chunks: Vec<ChunkId>, ) -> Self

Create a new file entry with compression and full metadata

pub fn update(&self, new_chunks: Vec<ChunkId>, new_size: usize) -> Self

Create an updated version of this file entry

pub fn update_compressed( &self, new_chunks: Vec<ChunkId>, compressed_size: usize, uncompressed_size: usize, compression_codec: u8, ) -> Self

Create an updated version with new compression settings

pub fn mark_deleted(&self) -> Self

Mark this file as deleted

pub fn new_holographic( path: String, is_text: bool, size: usize, chunks: Vec<ChunkId>, encoding_format: u8, ) -> Self

Create a new file entry for holographic storage with encoding format

pub fn is_regular_file(&self) -> bool

Check if this entry represents a regular file with content

pub fn is_metadata_only(&self) -> bool

Check if this entry is metadata-only (no data to encode)

pub fn build_offset_index(&mut self, chunk_sizes: &[usize])

Build the chunk offset index from chunk sizes

This populates chunk_offsets for O(log n) byte-offset lookups. Call this after creating chunks when you know the sizes.

Arguments

• chunk_sizes - The decoded (original) size of each chunk in order

pub fn new_with_offsets( path: String, is_text: bool, size: usize, chunks: Vec<ChunkId>, chunk_sizes: Vec<usize>, ) -> Self

Create a new file entry with pre-computed chunk offsets

This is the preferred constructor when chunk sizes are known at creation time.

pub fn new_holographic_with_offsets( path: String, is_text: bool, size: usize, chunks: Vec<ChunkId>, chunk_sizes: Vec<usize>, encoding_format: u8, ) -> Self

Create a holographic file entry with pre-computed chunk offsets

pub fn has_offset_index(&self) -> bool

Check if this entry has a chunk offset index

pub fn find_chunk_at_offset( &self, byte_offset: usize, ) -> Option<(ChunkId, usize)>

Find the chunk containing a given byte offset

Returns None if the offset is beyond the file size. Uses binary search when offset index is present (O(log n)). Falls back to linear search otherwise (O(n)).

pub fn chunks_for_range( &self, start_offset: usize, length: usize, ) -> Vec<ChunkRange>

Find all chunks needed to satisfy a byte range read

Returns a list of ChunkRange specifying which chunks to read and which portions of each chunk to include.

Arguments

• start_offset - Start byte offset in the file
• length - Number of bytes to read

Returns

Vec of ChunkRange for each chunk involved in the read. Returns empty Vec if start_offset >= file size.

pub fn computed_size(&self) -> usize

Get the total data size covered by all chunks (from offset index)

Returns file size if no offset index, or the computed total from chunks.

Trait Implementations

impl Clone for VersionedFileEntry

fn clone(&self) -> VersionedFileEntry

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for VersionedFileEntry

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.