Skip to main content

Crate aethelgard_avl

Crate aethelgard_avl 

Source
Expand description

§Sovereign-AVL

Sovereign-AVL is a NASA-grade, self-auditing data structure designed for environments where memory integrity and cryptographic certainty are non-negotiable.

It combines three fundamental architectural axioms to achieve “Sovereign” status:

  1. Generational Arena Storage: Eliminates Use-After-Free (Zombie Index) vulnerabilities.
  2. Merkle-Style Integrity: Every node is cryptographically tied to its children via BLAKE3 hashes.
  3. AVL Balancing: Guaranteed $O(\log n)$ performance for all operations.

§Quick Start

use aethelgard_avl::SovereignMap;
 
let map = SovereignMap::new();
 
// Secure insertion: Hashes are computed and propagated automatically.
map.insert("Aethelgard".to_string(), "Sovereign".to_string()).unwrap();
 
// Integrity-checked retrieval:
if let Ok(Some(val)) = map.get(&"Aethelgard".to_string()) {
    println!("Retrieved: {}", val);
}
 
// Full Recursive Audit:
map.full_audit().expect("Integrity violation detected!");

§Why Sovereign?

In mission-critical environments (Space, Medical, Financial), bit-flips and adversarial memory corruption are real threats. Sovereign-AVL assumes the memory is not trusted and verifies every bit on every access.

§⚖️ Limitations & Trade-offs

  • CPU Cost: BLAKE3 hashing on every update is expensive (~100x slower than BTreeMap).
  • Memory Cost: ~36-40 bytes of overhead per node (plus padding).
  • Write Contention: Uses a global RwLock, which might bottleneck high-frequency parallel writes.
  • Audit Latency: full_audit is $O(n)$ and can take several milliseconds for large trees.

Modules§

avl
error
storage

Structs§

SovereignIter
An iterator over the entries of a SovereignMap.
SovereignMap
A thread-safe, self-auditing AVL tree with sovereign integrity.