Struct HTTStorage 

pub struct HTTStorage { /* private fields */ }

HTT Storage Backend implementation.

Uses Hyperbolic Tree Tensors for efficient hierarchical data storage with O(1) operations and spatial queries.

Implementations

impl HTTStorage

pub fn new(config: HTTStorageConfig) -> Self

Create a new HTT storage instance.

pub fn shared_htt(&self) -> &SharedHTT

Get the shared HTT instance.

pub fn store_data_only( &self, key: &str, value: &[u8], content_type: Option<String>, ) -> IntegrationResult<()>

Store data without geometric embedding (data + semantic only).

Much faster than store() — skips Sarkar embedding. Use for bulk loading when spatial queries are not needed (semantic queries still work).

pub fn store( &self, key: &str, value: &[u8], content_type: Option<String>, ) -> IntegrationResult<()>

Store data by key.

Batch-creates missing ancestor directories under a single write lock before inserting the target node. This avoids the previous recursive approach which acquired/released the lock once per ancestor.

pub fn store_positioned( &self, key: &str, value: &[u8], content_type: Option<String>, child_index: u32, ) -> IntegrationResult<()>

Store data with an explicit child_index for deterministic Sarkar reconstruction.

Same as store() but passes child_index through so the node gets the same geometric position regardless of insertion order. Used during snapshot replay.

pub fn retrieve(&self, key: &str) -> IntegrationResult<Vec<u8>>

Retrieve data by key.

pub fn delete(&self, key: &str) -> IntegrationResult<()>

Delete data by key.

pub fn list(&self, prefix: &str) -> IntegrationResult<Vec<String>>

List keys with a prefix.

pub fn exists(&self, key: &str) -> bool

Check if a key exists.

pub fn get_metadata( &self, key: &str, ) -> IntegrationResult<HashMap<String, String>>

Get metadata for a key.

pub fn set_metadata( &self, key: &str, meta_key: &str, meta_value: &str, ) -> IntegrationResult<()>

Set metadata for a key.

pub fn set_semantic(&self, key: &str, coords: Vec<u8>) -> IntegrationResult<()>

Set semantic coordinates for a key (raw Q64.64 bytes, 16 bytes per dimension).

pub fn get_semantic(&self, key: &str) -> IntegrationResult<Vec<u8>>

Get semantic coordinates for a key (raw Q64.64 bytes).

pub fn position(&self, key: &str) -> IntegrationResult<HyperbolicPoint>

The hyperbolic (Poincaré) position of a stored key.

pub fn embed_existing(&self, key: &str) -> IntegrationResult<bool>

Upgrade a data-only key to a full geometric embedding (embed-on-demand — see crate::tree_tensor::HyperbolicTreeTensor::embed_existing). Returns whether this call performed the upgrade.

pub fn semantic_epoch(&self) -> u64

Monotone counter of semantic-relevant mutations (see crate::tensor_network::HyperbolicTensorNetwork::semantic_epoch).

pub fn find_nearest( &self, path: &str, k: usize, ) -> IntegrationResult<Vec<String>>

Find the k nearest stored keys to the given key’s position in hyperbolic space. Returns paths sorted by ascending hyperbolic distance.

pub fn find_in_radius( &self, path: &str, radius: FixedPoint, ) -> IntegrationResult<Vec<String>>

Find all keys within hyperbolic radius of the given key.

pub fn nearest_semantic( &self, query_coords: &[u8], k: usize, dim_range: &Range<usize>, ) -> IntegrationResult<Vec<(String, FixedPoint)>>

Find the k nearest nodes by Euclidean distance across a dimensional slice.

query_coords: raw Q64.64 bytes for the query point. k: number of results. dim_range: which dimensions to compare.

Returns paths sorted by distance ascending.

pub fn neighbors_semantic( &self, path: &str, k: usize, dim_range: &Range<usize>, ) -> IntegrationResult<Vec<(String, FixedPoint)>>

Find the k nearest nodes to an existing node by semantic dimensional distance. The queried node is excluded from results.

pub fn nearest_neighbor_point( &self, coords: &[FixedPoint], ) -> IntegrationResult<(String, FixedPoint)>

Find the nearest stored node to an arbitrary point in the Poincaré disk.

The power-diagram grid supplies candidates in O(1); the answer is then decided by hyperbolic distance against the VP-tree’s candidate as well, so the result is the true nearest node.

Complexity: O(log n). The grid alone cannot decide the query — it holds one owner per tile, and Sarkar placement drives power cells below tile size within a few levels, so a grid hit may name a node that is not nearest. Coordinates are in f32 (user-facing boundary); converted internally to FixedPoint. Returns (path, hyperbolic_distance_as_FixedPoint).

pub fn nearest_neighbor_point_k( &self, coords: &[FixedPoint], k: usize, ) -> IntegrationResult<Vec<(String, FixedPoint)>>

Find the k nearest stored nodes to an arbitrary point in the Poincaré disk.

Returns (path, hyperbolic_distance) sorted by ascending distance.

pub fn node_count(&self) -> usize

Total number of nodes in the tree, including the root node.

pub fn stats(&self) -> HashMap<String, String>

Get storage statistics.