Struct VersionedEngram 

pub struct VersionedEngram {
    pub chunk_store: VersionedChunkStore,
    pub corrections: VersionedCorrectionStore,
    pub manifest: VersionedManifest,
    /* private fields */
}

A fully versioned engram with optimistic locking

This is the top-level structure that coordinates all versioned components. It provides high-level read/write operations with ACID-like properties.

Fields

chunk_store: VersionedChunkStore

Versioned chunk store (NOT the VSA codebook - that’s in embeddenator-vsa)

corrections: VersionedCorrectionStore

Versioned corrections

manifest: VersionedManifest

Versioned manifest

Implementations

impl VersionedEngram

pub fn new(_dimensionality: usize) -> Self

Create a new versioned engram with default dimensionality

Arguments

• dimensionality - Reserved for future use. The actual dimensionality is determined by SparseVec::new() which uses the system’s configured default. This parameter is preserved in the API for future VSA codebook integration when the dimensionality becomes configurable.

pub fn with_root(root: Arc<SparseVec>) -> Self

Create a versioned engram with an existing root vector

pub fn version(&self) -> u64

Get the current global version

pub fn root_version(&self) -> u64

Get the current root version

pub fn root(&self) -> Arc<SparseVec>

Get a reference to the root vector

pub fn update_root( &self, new_root: Arc<SparseVec>, expected_version: u64, ) -> VersionedResult<u64>

Update the root vector with Compare-And-Swap (CAS)

This is the core operation for optimistic locking on the root. It attempts to update the root only if the current version matches the expected version.

pub fn bundle_chunk(&self, chunk_vec: &SparseVec) -> Result<u64, String>

Bundle a chunk into the root with automatic retry

This operation superimposes a new chunk vector into the root using the VSA bundle operation (XOR for binary vectors). The bundling is performed with optimistic locking and automatic retry on version conflicts.

Algorithm

1. Read current root and its version
2. Create new root by bundling: new_root = current_root ⊕ chunk_vec
3. Attempt CAS update with optimistic locking
4. Retry with exponential backoff if version conflict detected

Arguments

• chunk_vec - The chunk vector to bundle into the root

Returns

• Ok(new_version) - The new root version after successful bundle
• Err(e) - Error after max retries exceeded or other failure

pub fn begin_transaction(&self) -> Transaction

Begin a new transaction

pub fn commit_transaction(&self, tx: Transaction) -> Result<(), String>

Commit a transaction

pub fn abort_transaction(&self, tx: Transaction)

Abort a transaction

pub fn transaction_stats(&self) -> TransactionStats

Get transaction statistics

pub fn stats(&self) -> EngramStats

Get comprehensive engram statistics

Trait Implementations

impl Clone for VersionedEngram

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Default for VersionedEngram

fn default() -> Self

Returns the “default value” for a type.