Architecture

Hologram is a content-addressed, UOR-native tensor runtime. A tensor graph is compiled to a .holo archive and executed through a runtime where every value carries a UOR-ADDR κ-label. Identical computation is addressed once and reused — memoized, deduplicated, and replayed — rather than recomputed.

Content-addressed execution

The runtime is one content-addressed buffer pool. A value lives in a single aligned buffer; a slot binds to it by κ-label.

• Re-executing identical inputs rebinds rather than recomputes — a graph-level memo hit is O(1) in graph size.
• Constants are pinned for the session’s lifetime.
• BufferArena is the pool: an aligned buffer pool that backs both intermediate values and pinned constants.

This is the “performance is content-addressing, not micro-optimization” principle: redundant compute is eliminated by identity, not by hand-tuning.

LUT materialization over finite quantum domains

A pure function over a finite quantum domain is its own content-addressed table, built bit-identically from the reference implementation:

• f16 / bf16 transcendentals (Sigmoid, Tanh, GELU, SiLU, Exp, Erf): the 16-bit domain has 65536 points, so the activation is materialized once as a [u16; 65536] table (128 KB, L2-resident). Dispatch is one lookup instead of widen → transcendental → narrow — ~28× faster on bf16 GELU, bit-identical.
• Byte (≤8-bit) domain: a 256-entry table.
• Quantized inference: a Dequantize → activation chain stores f32 but its realized domain is the quantized source’s (256 for i8, 16 for i4), so it densifies into a ≤256-entry table indexed by the quantized byte — ~27× faster, keyed on realized information content rather than storage width.
• f32 is computed (a 4 GB table is infeasible); reuse is structural, via the κ-label memo at the graph level.

Fusion

Fusion happens in two stages — compile-time rewriting and load-time content-addressed passes — so intermediates are never separately materialized.

Compile-time

The graph is desugared to primitive ops and algebraically elided:

• Bit-exact-sound identities and involutions are removed.
• Reshape becomes a relabel rather than a copy.
• Dead-code elimination drops unreachable nodes.

Load-time content-addressed passes

At session load, fusion passes collapse sub-graphs:

• Matmul epilogue — MatMul / Conv2d absorb a following activation and/or bias add (MatMulActivation, MatMulAddActivation), applied in-register.
• Dequantize → matmul (MatMulDequant) — the quantized weight is dequantized inside the kernel; the dense f32 weight is never materialized.
• Dequantize → activation — densified to a quantized-domain table (above).
• Expand → elementwise-binary (BroadcastBinary) — the broadcast operand is read with stride-0 indexing in place; the broadcast tensor is never built (zero-movement).

Matmul

f32 matmul is a cache-oblivious blocked SIMD kernel (AVX-512 → AVX2 → NEON → portable scalar, selected at runtime) with compile-time panel-packed constant weights (zero runtime copy). Quantized weights (i8 / i4) flow through the fused MatMulDequant path. f16 / bf16 widen into the same f32 engine — no scalar fallback; f64 is rejected loudly.

Memory tiers (optional)

With the tiered-exec feature, the PM_7 pass classifies each value’s memory tier by its quantum level, adding memory-affinity classification and observability without changing numerical results.

The .holo archive

Models are stored in .holo binary archives: a sectioned format addressed by UOR-ADDR κ-labels with a BLAKE3 footer. HoloWriter produces archives; HoloLoader reads them. Archives also carry the warm-start fold — the constant-only cone is materialized into the archive so the runtime cache is never cold on first execution.

Model parts compose as κ-labels via address::address_ring and address::compose_model (a commutative product, giving order-independent model identity).

C & WASM bindings

hologram-ffi exposes the pipeline through a C ABI: a session is referenced by an integer handle into a process-local table (hologram_session_load / _execute / _close). Source can be compiled either as text through hologram_compile_source or built directly through the hologram_source_builder_* ABI, including inline constants and file-backed constant references. Built for wasm32-unknown-unknown with --features wasm, the same FFI powers the browser demo.

Design Principles

Content-addressing, not micro-optimization

Redundant compute is eliminated by identity. The same κ-label addresses the same value once; reuse is memoization, deduplication, and replay.

Compute-once tables

A pure function over a finite quantum domain is materialized once as a lookup table, bit-identical to compute. Information content (the realized domain), not storage width, decides the table size.

One float engine, no fallback

f16 / bf16 widen into the single f32 engine; f64 is rejected loudly. There is no scalar fallback for the float engine.

Conventions

• Max 3 function arguments; builder pattern for more.
• Functions ≤ 15 lines.
• No TODOs, stubs, or unimplemented!().
• Serialisation uses rkyv exclusively; no serde.