Zero — Core Runtime

The Immutable Substrate for High-Performance ML.
v1.4.0 — FROZEN

🔒 FROZEN CORE — This repository is frozen as of v1.3. Future changes require an approved spec under docs/specs/ and are governed by docs/ABI.md.

🧊 Status: v1.4 FROZEN

The Core Runtime is the freeze contract for transformer-class ML workloads. See docs/CORE_RUNTIME_SPEC.md for the authoritative surface and docs/EROSION_RULES.md for the compiler/runtime boundary.

Core primitives:

Primitive	Header	Description
Tensor	core/tensor.hpp	The only data container, O(1) strided views
Scalar	core/scalar.hpp	Rank-0 tensor, compile-time constants
DType	core/dtype.hpp	Orthogonal type system incl. BF16 and FP8
Struct	core/struct.hpp	Static aggregation, no methods
Control Flow	ir/control_flow.hpp	if/for/while → LLVM basic blocks
Functions	ir/function.hpp	Pure by default, explicit I/O
Memory	core/memory.hpp	Explicit allocation, device placement
Status	core/status.hpp	Non-throwing error model returned by every op
Generator	core/rng.hpp	RNG state primitive (state only; no algorithm)
Core Ops	ops/*.hpp	Elementwise, MatMul, Reduce, Reshape, Index ops

Infrastructure:

Component	Header	Description
Allocator	core/allocator.hpp	Pluggable memory allocators
Runtime	core/runtime.hpp	Seed control, deterministic mode
Stream	device/sync.hpp	Dispatch handle, final parameter on every op

🔧 Build

cmake -B build -DZERO_BUILD_TESTS=ON
cmake --build build --config Release
ctest --test-dir build -C Release

Sanitizer options:

cmake -B build-asan -DZERO_ENABLE_ASAN=ON    # AddressSanitizer
cmake -B build-ubsan -DZERO_ENABLE_UBSAN=ON  # UndefinedBehaviorSanitizer
cmake -B build-tsan -DZERO_ENABLE_TSAN=ON    # ThreadSanitizer

🧪 Tests

• 9 ctest binaries, all green ✅
  • ZeroBasicTest, ZeroBenchmark, ZeroActivationTest
  • ZeroDTypeFP8Test (spec 001), ZeroOpStatusTest (spec 002), ZeroOpStreamTest (spec 003), ZeroIndexOpsTest (spec 004), ZeroGeneratorTest (spec 005), ZeroContiguousTest (spec 006)
• Sanitizer-clean under ASAN / UBSAN / TSAN.
• Run: ctest --test-dir build --output-on-failure

📐 Architecture

Zero Source → Parser → AST → Zero IR
                              ↓
                    ┌─────────────────┐
                    │  Core Runtime   │  ← THIS REPO (FROZEN)
                    │  (Pure C++20)   │
                    └────────┬────────┘
                             ↓ Zero IR
                    ┌─────────────────┐
                    │  LLVM Backend   │  ← Separate repo
                    └─────────────────┘

🔒 Frozen Core Commitment

"If it can be implemented in Zero, it does not belong in the Core."

The runtime is now governed by three documents:

• docs/CORE_RUNTIME_SPEC.md — the surface
• docs/ABI.md — the stability rulebook
• docs/EROSION_RULES.md — the compiler/runtime boundary

Every future change starts with an Approved spec in docs/specs/. The root CLAUDE.md is the inviolable rule set every AI session loads when working in this repo.