nex-tagma
Standard reference implementation that consumes the Tagma coordinate space on top of neXus FIH storage
Abstract
nex-tagma is the nexus-tagma hub, a standard reference implementation that bridges the Tagma three-axis coordinate space and the neXus FIH three-dimensional storage. It demonstrates that the O(1) direct addressing, collision-free uniqueness, axis decomposition, and proximity properties of the Tagma coordinate system form an isomorphic mapping with the Fact-Inference-Hint three-dimensional cube. Every valid 16-bit Coord becomes a first-class coordinate in FIH storage.
nex-tagma serves as a bridge and an experimental ground for neXus core refactoring. Design decisions and structural insights gained here flow directly into formalize FIH coordinate system. The rationale for refactoring the current hash-based multi-index storage model into a native 3D cube addressing scheme is supplied by the empirical data—latency benchmarks, collision properties, and axis slicing performance—generated at each evolutionary stage of nex-tagma.
Identity
nex-tagma is a bridge that applies the three-axis coordinate system of Tagma to the FIH (Fact-Inference-Hint) three-dimensional storage structure of neXus. Design decisions and insights obtained here grow directly into the rationale for refactoring the nex core (Issue #139 – formalize FIH coordinate system).
Identity flow across three layers:
The linguistic equation is no coincidence: co-ordinare (to arrange together) = syn-tagma (that which is arranged together) declares that the Tagma project is the necessary realization of the Coord mechanism.
Three-Dimensional Structure Mapping
The correspondence of the three Tagma axes to the three FIH dimensions is structural, not metaphorical:
| Tagma Axis | FIH Dimension | Question |
|---|---|---|
| Axis 0 (origin) | origin | Where did the fact come from? |
| Axis 1 (creator) | creator | Who created it? |
| Axis 2 (type) | type | What kind of fact is it? |
Every valid (origin, creator, type) combination is encoded as one Tagma coordinate, mapped directly into an O(1) slot of the three-dimensional index. This is structurally superior to the existing hash-based multi-index approach (by_origin ∩ by_creator ∩ by_type → O(K)), because the coordinate space guarantees constant-time addressing without index intersection or bitmap maintenance.
The mapping uses the full coordinate space: 19 × 21 × 28 = 11,172 addressable coordinates per Coord. Each coordinate is a native Unicode scalar value, not an opaque hash. For multi-dimensional addressing, multiple coords compose into a CoordPath of arbitrary length, where each dimension occupies one Coord position rather than one axis within a Coord:
Property Transfer
The structural properties of the Tagma coordinate space transfer directly to FIH storage:
| Property | Tagma Coordinate | FIH Storage Application |
|---|---|---|
| O(1) direct addressing | C(i,m,f) = BASE + 588i + 28m + f |
storage[F][I][H] |
| Collision-free | coordinate = uniqueness guarantee | same (F,I,H) combination always the same slot |
| Axis decomposition | to_axes() → individual fields |
extract Fact only, extract Inference only, etc. |
| Proximity search | hamming_distance() |
similar fact/inference/hint O(1) exploration |
| Built-in validation | valid coordinate range embedded in type system | invalid FIH combinations structurally impossible |
All fact/inference/hint combinations map to a single three-dimensional cube, and the cube’s O(1) access + axis decomposition + proximity search connect directly to the detection tasks of the OODA scheduler (gap identification, contradiction detection, state-change sensing).
Performance Benchmarks
The following Criterion benchmark results were measured on ARMv8.4-A Firestorm from the nex crate benchmark suite (cargo bench -p nex). They compare the Tagma CoordSpaceN direct-address index (by_origin_creator fast path) against the legacy HashMap Vec intersection (fallback) at three data scales.
2-Axis Exist Query (origin X creator)
| Scale | Tagma | Legacy HashMap Intersection | Ratio |
|---|---|---|---|
| 10K facts, 100x100 grid | 65.7 ns | 3.12 us (Vec=100) | 47x |
| 100K facts, 200x500 grid | 61.6 ns | 12.2 us (Vec=500) | 198x |
| 500K facts, 500x2000 grid | 59.8 ns | 12.9 us (Vec=1000) | 215x |
Tagma cost is flat at ~60 ns regardless of data volume. Legacy cost grows linearly with axis cardinality: each additional 10x data multiplies the intersection cost by the Vec size.
Nonexist Query
| Type | Scale | Tagma | Legacy | Behavior |
|---|---|---|---|---|
| Fake nonexist (axis missing) | 10K | 36 ns | 39 ns | Both short-circuit |
| Real nonexist (combo missing) | 500K | 199 ns | 169 ns | Legacy still iterates Vec |
Fake nonexist (one axis value has zero entries) is fast for both because the HashMap returns empty Vec in O(1). Real nonexist (both axes exist but the specific combination does not) is where the asymmetry appears: Legacy still fetches both Vecs (1000 + 250 entries) and allocates a HashSet before finding nothing, while Tagma returns None at array access time.
Single-Axis HashMap (Baseline)
| Operation | Latency |
|---|---|
fact_ids_by_origin |
91 ns |
facts_by_creator |
92 ns |
Single-axis HashMap lookups remain the fastest path for simple queries. Tagma does not replace them – it replaces the multi-axis intersection.
Key Insight: Tagma Stays Flat
Tagma: 10K -> 100K -> 500K
65ns 62ns 60ns (flat)
Legacy: 10K -> 100K -> 500K
3us 12us 13us (linear growth)As data grows to millions, Tagma remains at ~60 ns. Legacy continues to climb: 10M facts would push Vec intersection to hundreds of microseconds. The advantage is structural – direct array addressing vs Vec scan is not an implementation detail but a complexity class difference.
Evolution Stages
nex-tagma evolves in stages, with each stage building on the previous and simultaneously feeding insights back to the nex core:
| Stage | Content | Status |
|---|---|---|
| 1 | Independent PoC – own coord.rs, SHA256 comparison benchmarks |
Complete (#150) |
| 2 | tagma-core dependency – reuse Coord type, remove own coord.rs | Complete (#151 Phase 1a) |
| 3 | nex storage integration – Tagma index on FIH storage | Complete (#151 Phase 1a) |
| 4 | 3D cube index experiments – axis slicing, proximity search, OODA integration | In Progress |
| 5 | Insight feedback → nex refactoring (#139 FIH coordinate system formalization) | In Progress |
Stage 1 (complete) established the baseline: a single Tagma coordinate is ~600x (0.38 ns vs 227 ns) faster than SHA256 for identity generation, with native axis decomposition and collision-free properties.
Stage 2 (complete) replaced the standalone PoC with the tagma-core library (#![no_std], zero OS dependencies), adding CoordSpaceN for N-dimensional fixed-depth addressing and DynCoordSpace for recursive variable-depth addressing with Slot::Both (value + child subtree at the same coordinate).
Stage 3 (complete) introduced CoordSpaceN<3, FihHash> as the multi-axis index inside FihCoord (~40 lines added). The storage IO layer, record types, FihHash serialization, and the Blackboard trait surface remain unchanged. Legacy HashMap indexes are preserved for backward compatibility and single-axis queries. The change replaces 3-Vec intersection with a direct CoordPath lookup.
Stage 4 is active: axis-slice queries, proximity search via Hamming distance, and OODA scheduler integration using the new index.