horon-engine

Store data as a tree. Query it as a space.

The idea

Organize data in paths, like files in folders. The engine embeds that tree in hyperbolic space, so structural similarity becomes spatial proximity. One query primitive answers most questions: "what's nearby?"

Why hyperbolic space fits trees

Hyperbolic space grows exponentially with radius. Trees grow exponentially with depth. The match is exact: the engine places every node with Sarkar's construction, items in the same branch cluster, items in distant branches sit far apart. Each leaf insertion preserves the spatial structure with O(1) work, so the tree is its own spatial index. Proof: PROOF.md.

In production

A production course recommender runs on this engine: 183 courses and 741 students in one tree file. Recommendations are geometric, courses close to a student's enrollment history rather than keyword matches. The same file reveals miscategorized courses, demand gaps, and domains that share student populations.

Quick start

use horon_engine::Store;

let store = Store::new();

// Tree storage; parents are auto-created
store.put("/courses/trauma/emdr_basis", b"EMDR Basiscursus").unwrap();
store.put("/courses/trauma/emdr_kind", b"EMDR Kind & Jeugd").unwrap();
store.put("/courses/systemisch/eft", b"Emotion Focused Therapy").unwrap();

// Retrieval and hierarchy
let data = store.get("/courses/trauma/emdr_basis").unwrap();
let kids = store.children("/courses/trauma").unwrap();

// Spatial query: structurally nearby nodes.
// emdr_kind comes first (same branch), then eft (sibling branch).
let neighbors = store.neighbors("/courses/trauma/emdr_basis", 3).unwrap();

// Metadata
store.set_meta("/courses/trauma/emdr_basis", "capacity", "24").unwrap();

Semantic dimensions

Any node can carry a coordinate vector encoding domain meaning: categories, popularity, demand signals. Queries then run over any slice of those dimensions, and different slices answer different questions from the same data.

// Attach a 40-dimension coordinate vector (Q64.64, 16 bytes per dim)
let coords: Vec<u8> = encode_my_dimensions(...);
store.set_semantic("/courses/trauma/emdr_basis", coords.clone()).unwrap();

// The 5 nearest nodes by dimensions 16..33 (category axes),
// as Vec<(path, distance)> sorted by distance across exactly those dims
let similar = store.nearest_semantic(&coords, 5, 16..33).unwrap();

// Distance between two coordinate vectors, no store involved
let dist = Store::semantic_distance(&coords_a, &coords_b, 16..33);

This is how a catalog separates an item's labeled category from where its population actually positions it. The gap between the two is a miscategorization, visible in geometry and invisible in metadata.

Install

[dependencies]
horon-engine = "0.5"

All arithmetic is gMath Q64.64 fixed point. The determinism contract is defined on the embedded profile, so build with:

GMATH_PROFILE=embedded cargo build

API reference

All methods take &self. Share freely via Arc<Store> across threads. Per-symbol truth lives in the docblocks: cargo doc --open.

HTTStorage, the layer below

Store wraps HTTStorage. Reach for it when you need direct control over embedding dimension or grid resolution:

use horon_engine::{HTTStorage, HTTStorageConfig};

let storage = HTTStorage::new(HTTStorageConfig {
    dimension: 8,
    max_memory_nodes: 50_000,
    cache_size: 5_000,
    grid_resolution: 128,
    ..Default::default()
});
storage.store("/data", b"value", Some("text/plain".into())).unwrap();

QueryAdapter

Pluggable query interface for building custom query languages on top of the store:

use horon_engine::store::{QueryAdapter, QueryResult};

impl QueryAdapter for MyAdapter {
    fn execute(&self, store: &Store, query: &str) -> Result<Vec<QueryResult>, StoreError> {
        // Parse query, call store methods, return results
    }
}

Concurrency

• Reads are lock-free: get, exists, children, get_meta, and all spatial queries. No reader ever blocks another reader.
• Writes stripe on the parent node: 64 lock stripes, so independent subtrees write in parallel.
• The spatial index is ~61 buckets, each with its own VP-tree and lock.
• There is no outer lock. Every method takes &self; wrap in Arc<Store> and share across threads, async tasks, or HTTP handlers.

How it works

Traditional trees scale lookups with depth. Spatial indexes do not understand hierarchy. Five mechanisms remove the choice:

1. Sarkar embedding. Every node gets a position in the Poincare disk; children sit at hyperbolic distance tau from their parent via Mobius reflection. The tree is its own spatial index.
2. Path lookup. Path to node is an O(1) HashMap access, independent of the spatial index. Nodes are additionally sharded into ~61 fixed buckets backing the VP-tree layer; that partition does not track hyperbolic growth, so occupancy is uneven and query cost suffers. Query results do not depend on it.
3. Per-bucket VP-trees. Range and KNN queries in O(log n) under the hyperbolic metric.
4. Nielsen power diagram. A Poincare-to-Klein projection and a uniform grid propose candidates for point location. The grid is an accelerator, not an oracle: it holds one owner per tile and Sarkar drives cells below tile size within a few levels, so the answer is always decided by hyperbolic distance.
5. Semantic dimensions. Orthogonal to the spatial embedding: Euclidean distance over user-defined dimension slices, no tree change required.

Determinism

All geometry is gMath Q64.64 fixed point. There are no floats in the compute path. The same operation sequence produces bit-identical state on any platform; that property is what lets a write-ahead log double as a replication protocol. CI runs the suite on x86-64 and arm64.

Current limitations

Stated plainly, because they affect how you should configure the engine.

• tau must scale with fan-out. PROOF.md's Delaunay guarantee holds only when tau >= -log(tan(pi / (2 * d_max))) for the tree's maximum node degree. The default tau = 1.0 satisfies that up to d_max ~= 4.5. Beyond it the tree is still embedded, queried and returned correctly — it is simply outside the proven regime. Set it with StoreConfig::tau() for wider trees.

• Depth is bounded by precision, not by the format. A node sits at hyperbolic radius depth * tau, and the Q64.64 distance kernel holds metric fidelity to a radius of about 17.5 (saturating near 22). So tau = 1.0 gives usable depth ~17, and raising tau for wider trees lowers reachable depth proportionally.

• nearest is O(log n), not O(1). The point-location grid cannot name a node whose power cell is smaller than a grid tile, which Sarkar placement causes within a few levels. The grid proposes candidates only.

Performance

Measured 2026-07 on an i7-7700 (4c/8t) with GMATH_PROFILE=embedded. Full tables, machine specs, and reproduction commands: BENCHMARKS.md.

Geometric primitives run in nanoseconds (grid probe ~15 ns, power distance ~24 ns). Full-API queries pay for exact hyperbolic verification of every candidate. Concurrent read throughput: ~2.6M reads/sec on 8 threads.

These rows predate 0.5.0, whose proxy-space release cut the cost of every ranking loop (bulk insert and structural KNN most of all — fresh-tree insertion dropped roughly an order of magnitude). Treat the table as an upper bound until BENCHMARKS.md is re-measured on the reference machine.

Persistence

The engine is in-memory. Horon persists it: the .htt single-file format with WAL durability, zstd compression, snapshot compaction, and geometric access control.

use horon::Horon;

let htt = Horon::open("data.htt")?;
htt.put("/config/db", b"postgres://localhost")?;
htt.compact()?;

Architecture

Store                         <- public API, all &self, Arc-shareable
  └─ HTTStorage               <- path normalization, CRUD, striped parent locks
       └─ HyperbolicTreeTensor     <- path-to-signature maps (DashMap)
            └─ HyperbolicTensorNetwork  <- Sarkar embedding, spatial index
                 ├─ HyperbolicHashTable  <- ~61 buckets, per-bucket VP-trees
                 ├─ PoincareDisk         <- hyperbolic geometry, Mobius transforms
                 └─ PointLocationGrid    <- candidate proposer (not an oracle)

Ecosystem

• gMath: Q64.64 fixed-point arithmetic with ZASC-Binary transcendentals.
• Horon: .htt WAL persistence over this engine.

Limits worth knowing

• Depth is a precision budget: Q64.64 supports roughly 44/τ levels before sibling separation degrades near the disk boundary; the engine warns as inserts approach it.
• Extreme fan-out (on the order of 1000+ siblings under one parent) can quantize to colliding position signatures; insertion probes forward to the next free slot, so placement stays correct but the golden-angle spacing guarantee weakens. Keep realistic tree shapes.
• Semantic dimensions are capped at 255 per node (16 reserved + up to 239 user); distances run over any slice of them.
• The engine is in-memory and single-process by design — durability, concurrent readers, and the on-disk layout live in Horon.

Recent work

• Semantic disk: the concept taxonomy embedded hyperbolically, positions derived from affinity dimensions (docs/SEMANTIC_DISK.md).
• Semantic spatial index: lazy per-slice VP-trees, ~690x faster at 10k nodes (docs/SEMANTIC_INDEX.md), plus find_similar and find_outliers.
• In Horon: temporal epochs (v0.6.0) and WAL-based replication (v0.5.0).

Author

Built by Niels Erik Toren. Support addresses and contribution guidelines live in the Horon README.

Disclaimer

This software is provided "as is", without warranty of any kind, express or implied. Use of this software is entirely at your own risk. In no event shall the author or contributors be held liable for any damages arising from the use or inability to use this software.

License

Apache-2.0 (see LICENSE).