Crate horon_engine 

horon-engine

horon-engine is a Rust implementation of the Hyperbolic Tree Tensor data structure: hierarchical data embedded in the Poincaré disk so that tree structure becomes spatial proximity. Path lookups are hash-map access; spatial queries are answered exactly by a computed cell index.

Core Principles

1. Hyperbolic Geometry: Maps hierarchical data into hyperbolic space using the Poincaré disk model
2. Spatial Indexing: a computed cell index — radial bands × angular sectors — walked outward until a proven lower bound rules out every unvisited cell
3. Exact by default: no candidate cap, no window, no count-based stopping rule. Degradation is toward slow, never toward wrong.

Key Features

• Honest costs: get/exists are hash-map access. Spatial queries are not O(1) — they cost as many cells as the bound needs to rule out, which depends on tree shape; see BENCHMARKS.md for measured figures. Semantic queries use lazy per-slice VP-trees above a node floor and a linear scan below — see Store::nearest_semantic and docs/SEMANTIC_INDEX.md.
• Spatial Queries: Find nearest neighbors and range queries in hyperbolic space
• Architecture: docs/ARCHITECTURE.md — the three coordinate systems and which query serves each. Read it first; the distinction is easy to get backwards.
• Mathematically Grounded: Sarkar embedding (see PROOF.md). PROOF.md’s Delaunay guarantee is conditional on tau >= -log(tan(pi/(2*d_max))) and the default tau = 1.0 satisfies it only up to d_max ~= 4.5 (see StoreConfig::tau) — but since 0.6.0 no query path depends on it. A violated bound costs spacing quality, not correctness. See docs/GEOMETRY_TRACK.md.
• Deterministic Results: Q64.64 fixed-point arithmetic for bit-identical results across platforms
• Extensible: Modular architecture with pluggable components and extension system

Basic Usage

use horon_engine::{HTTStorage, HTTStorageConfig};

// Create storage configuration
let config = HTTStorageConfig::default();

// Create HTT storage
let storage = HTTStorage::new(config);

// Store and retrieve data
storage.store("/example/path", b"Hello, HTT!", None).unwrap();
let data = storage.retrieve("/example/path").unwrap();
assert_eq!(data, b"Hello, HTT!");

Re-exports

pub use error::HTTError;

pub use error::HTTResult;

pub use registry::ComponentRegistry;

pub use registry::HTTComponentRegistry;

pub use registry::RegistryError;

pub use metrics::MetricsProvider;

pub use metrics::SimpleMetrics;

pub use config::HTTStorageConfig;

pub use tree_tensor::HTTConfig;

pub use hash_table::GeometricSignature;

pub use hyperbolic_geometry::PoincareDisk;

pub use hyperbolic_geometry::HyperbolicPoint;

pub use hyperbolic_geometry::distance_to_ratio;

pub use tensor_network::HyperbolicTensorNetwork;

pub use tensor_network::CompressedNode;

pub use tensor_network::NodeMetadata;

pub use tree_tensor::HyperbolicTreeTensor;

pub use storage::HTTStorage;

pub use extension::HTTExtension;

pub use extension::HTTStorageProvider;

pub use extension::ExtensionRegistry;

pub use klein::KleinPoint;

pub use klein::poincare_to_klein;

pub use klein::klein_to_poincare;

pub use klein::power_distance;

pub use store::Store;

pub use store::StoreConfig;

pub use store::StoreError;

pub use store::QueryAdapter;

pub use store::QueryResult;

pub use store::SemanticOutlier;

pub use semantic_disk::SemanticDisk;

Modules

cell_index

Hyperbolic cell index — a node’s cell is computed from its coordinates.

concurrency

concurrency.rs - Striped locking for parallel writes to independent subtrees

config

config.rs - Configuration System for horon-engine storage

constants

Shared fixed-point constants for the engine.

error

Error handling for the horon-engine library

extension

extension.rs - Pluggable Extension System for horon-engine

hash_table

hash_table.rs — geometric node identity

hyperbolic_geometry

hyperbolic_geometry.rs - Poincaré Disk Model Implementation for horon-engine

init

init.rs - Initialization Module for horon-engine storage

klein

klein.rs — Klein Projective Model + Nielsen Power Diagram

metric_tree

Generic static VP-tree over a pluggable metric (the semantic-index core).

metrics

Performance metrics collection for horon-engine

registry

registry.rs - ComponentRegistry for module independence

semantic_disk

Semantic disk — taxonomy-embedded meaning space (E+D design).

semantic_index

Lazy per-slice semantic index cache with epoch invalidation.

storage

storage.rs - Hierarchical Storage Implementation

store

store.rs - Simple, ergonomic wrapper around HTTStorage

tensor_network

tensor_network.rs - Hyperbolic Tensor Network for Hierarchical Data

tree_tensor

tree_tensor.rs - Hyperbolic Tree Tensor Core Implementation

utils

utils.rs - Optimization and Utility Functions for horon-engine

Constants

AUTHORS

Crate authors (from Cargo.toml)

DESCRIPTION

Crate description (from Cargo.toml)

VERSION

Version information