cjc-runtime 0.1.3

Runtime library: values, builtins, tensors, COW buffers
Documentation

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]