Crate cjc_runtime 

CJC Runtime System

This crate provides the core runtime infrastructure for the CJC deterministic numerical programming language. It is the largest crate in the workspace and underpins both the AST tree-walk interpreter (cjc-eval) and the MIR register machine executor (cjc-mir-exec).

Core Abstractions

• Buffer<T> – Deterministic memory allocation with COW (copy-on-write) semantics. Cloning is O(1); mutation triggers a deep copy only when shared.
• Tensor – N-dimensional tensor backed by Buffer<f64>. Supports element-wise arithmetic (SIMD-accelerated), matrix multiplication (tiled + parallel), and numerically-stable reductions via BinnedAccumulatorF64.
• Value – The universal tagged-union value type that flows through both interpreters. Covers scalars, strings, tensors, closures, structs, enums, and opaque type-erased objects (AD graphs, tidy views, quantum states).
• RuntimeError – Error type for all fallible runtime operations.

Determinism Guarantees

• All floating-point reductions use Kahan or BinnedAccumulatorF64 summation.
• Ordered containers only (BTreeMap/BTreeSet) – no HashMap/HashSet.
• DetMap provides a deterministic hash map with murmurhash3 hashing.
• SIMD kernels avoid hardware FMA for bit-identical cross-platform results.
• RNG is SplitMix64 with explicit seed threading (cjc-repro).

Memory Model

• NoGC tier: Buffer<T>, Tensor, AlignedByteSlice – zero GC overhead, COW semantics.
• GC tier: GcHeap / GcRef – RC-backed object slab for class instances.
• Arena tier: FrameArena / ArenaStore – bump allocation per function frame for non-escaping temporaries.

Module Organization

Layer	Modules
Core types	value, error, buffer, tensor, tensor_dtype
Builtins	builtins – shared stateless dispatch for both executors
Accumulation	accumulator, dispatch
Linear algebra	linalg, sparse, sparse_solvers, sparse_eigen
Statistics	stats, distributions, hypothesis
Data	json, datetime, window, timeseries
ML / NN	ml, fft, clustering, optimize, interpolate
Memory	gc, object_slab, frame_arena, binned_alloc, aligned_pool
SIMD / Perf	tensor_simd, tensor_tiled, tensor_pool

Re-exports

pub use buffer::Buffer;

pub use tensor::Tensor;

pub use scratchpad::Scratchpad;

pub use aligned_pool::AlignedPool;

pub use aligned_pool::AlignedByteSlice;

pub use paged_kv::KvBlock;

pub use paged_kv::PagedKvCache;

pub use gc::GcRef;

pub use gc::GcHeap;

pub use binned_alloc::BinnedAllocator;

pub use frame_arena::FrameArena;

pub use frame_arena::ArenaStore;

pub use object_slab::ObjectSlab;

pub use object_slab::SlabRef;

pub use sparse::SparseCsr;

pub use sparse::SparseCoo;

pub use tensor_tiled::TiledMatmul;

pub use det_map::DetMap;

pub use det_map::murmurhash3;

pub use det_map::murmurhash3_finalize;

pub use det_map::value_hash;

pub use det_map::values_equal_static;

pub use value::Value;

pub use value::Bf16;

pub use value::FnValue;

pub use error::RuntimeError;

pub use tensor_dtype::DType;

pub use tensor_dtype::TypedStorage;

Modules

accumulator

BinnedAccumulator for order-invariant deterministic floating-point summation. BinnedAccumulator — Deterministic, order-invariant floating-point summation.

aligned_pool

16-byte-aligned memory pool for SIMD-friendly byte buffers. Aligned memory pool – 16-byte aligned allocation for SIMD readiness.

binned_alloc

Size-class binned allocator for deterministic memory management. Deterministic Binned Free Lists

buffer

COW (copy-on-write) buffer – the memory primitive under Tensor. COW (Copy-on-Write) buffer – the fundamental memory primitive under Tensor.

builtins

Stateless builtin function dispatch shared by both interpreters.

clustering

Clustering algorithms (k-means, DBSCAN). Clustering algorithms — K-Means, DBSCAN, Agglomerative.

complex

Complex number arithmetic with deterministic fixed-sequence operations. Complex BLAS — ComplexF64 with Fixed-Sequence Arithmetic.

datetime

Pure-arithmetic datetime manipulation (epoch-based, no system clock). DateTime support for CJC.

det_map

Deterministic hash map using MurmurHash3 – iteration order is fixed. Deterministic map with insertion-order iteration.

differentiate

Numerical differentiation (finite differences). Numerical Differentiation — deterministic finite-difference routines.

dispatch

Hybrid summation strategy dispatch (Kahan vs Binned) based on execution context. Hybrid Summation Dispatch — Routes reductions to the appropriate accumulator.

distributions

Probability distribution functions (CDF, PDF, PPF) for Normal, t, chi2, F. Probability distributions — CDF, PDF, PPF for Normal, t, Chi-squared, F, Binomial, Poisson.

error

RuntimeError enum for all fallible runtime operations.

f16

IEEE 754 half-precision (f16) floating-point type. Half Precision (f16) — IEEE 754 binary16 with promotion to f64.

fft

Fast Fourier Transform (radix-2 Cooley-Tukey). FFT — Cooley-Tukey radix-2 FFT, inverse FFT, real FFT, PSD.

frame_arena

Bump-arena per function frame for non-escaping temporaries. Frame Arena — bump allocator for non-escaping values.

gc

GC heap abstraction wrapping the RC-backed object slab. GC compatibility layer — thin wrapper over ObjectSlab.

hypothesis

Hypothesis testing: t-test, chi-squared test, paired t-test. Statistical hypothesis tests — t-test (one-sample, two-sample, paired), chi-squared goodness-of-fit, ANOVA, F-test.

integrate

Numerical integration (trapezoidal, Simpson’s rule). Numerical Integration — deterministic quadrature routines.

interpolate

Interpolation primitives (linear, cubic spline). Interpolation & Curve Fitting

json

JSON parse/stringify builtins for CJC values. Hand-rolled JSON parser and emitter for CJC.

kernel

Raw-pointer kernel functions that operate directly on f64 slices.

lib_registry

Library registry for module-system symbol lookup. Library Registry — informational trait for CJC library self-description.

linalg

Dense linear algebra: determinant, solve, eigenvalues, SVD, QR, LU. Dense linear algebra operations on Tensor.

ml

Machine learning loss functions and optimizer state types. ML Toolkit — loss functions, optimizers, activations, metrics.

object_slab

RC-backed object slab for class instances (replaces mark-sweep GC). Object Slab — deterministic RC-backed replacement for mark-sweep GC.

ode

ODE solver primitives (Euler, RK4 step functions). ODE / PDE Solver Infrastructure — Minimal Primitives

optimize

Numerical optimization (gradient descent, L-BFGS, Nelder-Mead). Optimization & Root Finding — deterministic numerical solvers.

paged_kv

Block-paged KV-cache (vLLM-style) for efficient autoregressive decoding. Block-paged KV-cache – vLLM-style block paging for transformer inference.

quantized

Quantized tensor storage (4-bit, 8-bit) for memory-efficient inference. Quantized BLAS — i8/i4 dequantization into BinnedAccumulator.

scratchpad

Pre-allocated KV-cache scratchpad for zero-allocation transformer inference. KV-cache scratchpad – zero-allocation state persistence for transformer inference.

sparse

Sparse matrix types: CSR and COO representations. Sparse matrix representations and arithmetic.

sparse_eigen

Sparse eigenvalue solvers (Lanczos, Arnoldi). Sparse Eigenvalue Solvers — Lanczos and Arnoldi

sparse_solvers

Direct sparse solvers (LU factorization, triangular solve). Iterative solvers for sparse linear systems.

stationarity

Time-series stationarity tests (ADF). Stationarity tests for time series analysis. ADF (Augmented Dickey-Fuller), KPSS, and Phillips-Perron tests. All use Kahan-compensated sums for numerical determinism.

stats

Descriptive and inferential statistics functions. Descriptive statistics — population & sample variance, sd, se, median, quantile, IQR, skewness, kurtosis, z-score, standardize.

tensor

N-dimensional tensor with element-wise, reduction, linalg, and NN operations. N-dimensional tensor with element-wise, reduction, linalg, and NN operations.

tensor_dtype

Typed tensor storage: DType enum and byte-first TypedStorage. Typed tensor infrastructure: DType enum and TypedStorage.

tensor_pool

Tensor memory pool for reducing allocation pressure in hot loops. Thread-local tensor buffer pool for reusing allocations.

tensor_simd

AVX2 SIMD kernels for element-wise and unary tensor operations. SIMD acceleration for tensor operations (AVX2, 4-wide f64).

tensor_tiled

L2-cache-friendly tiled matrix multiplication engine. Tensor Tiling — L2-friendly tiled matrix multiplication.

timeseries

Time-series analysis utilities (autocorrelation, differencing). Time series analysis functions.

value

The universal Value tagged union and supporting types (Bf16, FnValue). The universal runtime value type for the CJC interpreter.

window

Rolling window aggregations (sum, mean, min, max). Sliding-window functions for CJC.