docs / specification / gpu

Cajeta value-type catalog

Status: design-stage reference. This catalogs the operator-overloaded value types cajeta intends to ship and their canonical operator-overload signatures, so that when it is time to write definitions the surface is already specified. It is a companion to OperatorOverloading.md.

The @ValueType operator-overloading mechanism it relies on has since landed (plans/value-type-overloading-plan.md, shipped 2026-06-05): @ValueType POD classes carry VALUE_TYPE_FLAG and dispatch operators via a relaxed gate, with their operators force-inlined to flat IR (preserving by-value GPU marshalling). What is still design-stage is the type definitions themselves — of everything below, only Vector / Matrix / Quaternion (compiler intrinsics carrying their own type flags, not declared @ValueType classes) and the device-only CooperativeMatrix exist in code today; the rest is specified here but unwritten.

Priority: now = needed for current ML/GPU work · soon = next · later = justified-but-speculative.

Corrections (2026-06-04) — these override the raw per-row notes below, which were generated before the design decisions were locked:

• No templated operators; matmul * is compiler-intrinsic for built-in Matrix/Tensor (owner decision). Operator overloads are concrete (specific LHS × specific RHS). Any row marking K-generic matmul as “FORBIDDEN” / “needs method-templated operators” OR as a operator*<K> template is superseded: for the compiler-known value types Matrix/Tensor, M1 * M2 lowers to matmul by the compiler reading R/K/C off the (already concrete) operand types in codegen — exactly like Vector’s operators, no template anywhere. Element-wise multiply is the method a.hadamard(b).
• Instance mutating operators are forbidden on value types (owner decision). Any operator[]= / operator++ / operator-- row is conceptual only: value types are by-value Copy, so in-place mutation would mutate a copy. Writes use whole-value reassignment (m = m.with(...), m[r][c]=v rewrites the whole value via flat-lane insert); m += n desugars to m = m + n. Read operator[] is fine.
• The catalog is auto-generated from the design workflow and still has duplicate/conflicting rows for a few types (e.g. Matrix); a consolidation pass is pending. Treat the conventions section + these corrections as authoritative when they disagree with a row.

Operator-signature conventions

Canonical conventions the catalog/docs must follow (grounded in OperatorOverloading.md and CajetaLlvmVisitor.h:1074-1167 enforcement): (1) BINARY arithmetic/bitwise/comparison (+, -, *, /, %, &, |, ^, <<, >>, ==, <) and NON-mutating UNARY (+, -, !, ~): public static with explicit operands, no this. Binary = exactly 2 params; unary = exactly 1 param. Shape: public static R operator+(LHS a, RHS b) and public static R operator-(T a). Return type R is the owned result. (2) For a value type V, the canonical homogeneous arithmetic signature is public static V operator+(V a, V b); mixed forms like public static V operator*(V a, float32 s) (and the swapped (float32 s, V a) if commutativity is wanted) are declared explicitly — there is NO implicit scalar broadcast for value types. (3) COMPARISON: declare only operator== and operator<; the compiler DERIVES != (¬==), > (swapped <), >= (¬<), <= (swapped ¬<) via BinaryOpExpression.cpp:715-754. Both == and < return bool. Do not declare the derived four unless a partial order needs them. (4) MUTATING UNARY ++/— and INDEXED []/[]=: INSTANCE methods, NO static. operator++() 0 params return void; operator[](IdxT i) 1 param returns element (a borrow tied to receiver); operator[]=(IdxT i, ElemT v) 2 params return void. (5) COMPOUND-ASSIGN (+=, -=, …): omit by default (auto-derived as a = a + b from the static binary form); declare an explicit instance operator+=(RHS b) (1 param, void) only for in-place mutation. (6) @ValueType operators that must run in kernels are additionally marked @Device and constrained to primitive scalar/vector ops (no alloca/GEP/heap) so they device-inline cleanly. (7) NO templated operators — operator overloads are concrete (a specific LHS type × a specific RHS type). Shape-generic matmul is NOT a user operator: for the compiler-known value types Matrix/Tensor, M1 * M2 is compiler-intrinsic (the compiler reads R/K/C off the concrete operand types and emits matmul, like Vector’s operators — no template, no inference machinery). Element-wise multiply is the method a.hadamard(b). User-defined value types use only concrete operator overloads. (8) Operator bodies should be small/pure to honor the AlwaysInline size guard and the by-value/no-side-effect marshalling contract.

Type index

• AABB (BoundingBox) — now — Axis-aligned bounding box for collision detection, spatial queries, and BVH nodes.
• Color (RGBA) — now — 4-component color representation (R,G,B,A).
• Complex — now — Cartesian complex numbers: a + bi.
• CooperativeMatrix<T,Rows,Cols,Use> — now — Device-only tile-sized matrix multiply via hardware matrix cores (WMMA), living distributed across a wavefront’s per-invocation registers.
• DualNumber — now — Automatic differentiation (forward-mode) for SPELA per-layer local-loss gradients.
• Float16 — now — IEEE 754 binary16 (16-bit half precision) as a standalone scalar value type.
• Matrix<T,R,C> — now — Fixed-size R×C matrix.
• Ray — now — Parametric ray for intersection tests, ray casting, visibility queries.
• Tensor<T,Dims…> — now — N-dimensional array value type for ML workloads (the workhorse of SPELA/Caramelo).
• Transform (Mat4) — now — Homogeneous 4×4 transformation matrix for 3D graphics.
• Vector<T,N> — now — Fixed-width numeric vector with N lanes of element type T, lowering to LLVM .
• BFloat16 — soon — Google’s bfloat16 (16-bit brain float) format: 1 sign + 8 exponent + 7 mantissa bits, matching the range of float32 but with coarser mantissa precision.
• Float8E4M3 — soon — 8-bit floating point, E4M3 format (4-bit exponent, 3-bit mantissa, no implicit bit, no -0).
• Float8E5M2 — soon — 8-bit floating point, E5M2 format (5-bit exponent, 2-bit mantissa, implicit bit, supports ±∞).
• Plane — soon — Planar surface defined by normal + distance from origin.
• Quaternion — soon — Unit quaternion for 3-D rotations: w + xi + yj + z*k.
• Rect (Bounds2D) — soon — 2D axis-aligned rectangle for UI layout, sprite bounds, texture regions, 2D spatial queries.
• SaturatingInt — soon — Signed/unsigned integer wrapper that saturates on overflow (a += b caps at T.
• WrappingInt — soon — Signed/unsigned integer wrapper with wrapping (two’s-complement) arithmetic on overflow.
• FixedPoint<T, uint32 Frac> — later — Deterministic fixed-point arithmetic for finance (pennies, cents), physics-based games (deterministic lockstep multiplayer), and embedded ML inference where float rounding non-determinism is unacceptable.
• Interval — later — Validated numerics for robust geometric computation, physics simulation, and scientific computing where correctness matters more than speed.
• Range (Interval) — later — 1D interval [min, max] for 1D spatial queries, clip planes, animation timelines, parameter ranges.

AABB (BoundingBox)

• Priority: now · Families: geometric-graphics
• Type params: <T extends Numeric = float32>
• Element types: T: float32 (graphics/ray tracing); int32 (discrete spatial indexing)
• Purpose: Axis-aligned bounding box for collision detection, spatial queries, and BVH nodes. Foundation for ray tracing (ray query) and spatial indexing (SpatialIndex).
• Representation: Two Vector<T,3> endpoints (minPoint, maxPoint). Distinct type (not generic pair) to enable semantic methods and prevent confusion.
• GPU notes: Used as bounding-box geometry in ray-query operations (AccelerationStructure.buildAabbs). Kernel-arg marshalling: two Vector<T,3> fields, passed by value. Device: intersection/overlap queries compile to SIMD min/max. SpatialIndex wraps each datum in an AABB; ray query walks the BVH (ray-box intersection native in RT hardware).
• Depends on: Vector<T,3> (foundation exists), Numeric bound (from Vector)

Methods: public boolean contains(Vector<T,3> point), public boolean containsBox(AABB<T> other), public boolean overlaps(AABB<T> other), public Vector<T,3> center(), public Vector<T,3> halfExtent(), public Vector<T,3> extent(), public T surfaceArea(), public T volume(), public AABB<T> expand(Vector<T,3> point), public AABB<T> expand(T epsilon), public T distanceToPoint(Vector<T,3> point)

Color (RGBA)

• Priority: now · Families: geometric-graphics
• Type params: no type parameter (fixed float32)
• Element types: float32 (normalized [0,1] per channel, typical); float16 (RGBA16F textures); uint8 (packed RGBA32)
• Purpose: 4-component color representation (R,G,B,A). Alias or distinct type for graphics and image processing. Foundation type for texture sampling, framebuffer output, and UI rendering.
• Representation: Four color channels (red, green, blue, alpha). Recommendation: distinct type with Vector-like ops, not an alias, to enable semantic methods (sRGB conversion, premultiply).
• GPU notes: Texture2D.sample(sampler, u, v) currently extracts lane-0 of <4 x float32> (cajeta-gpu-plan A3/S6 RGBA bridge, deferred). Once that lands, sample() returns Color directly. Color marshalling matches framebuffer formats (float32 RGBA, half RGBA, uint8 RGBA); no marshalling penalty.
• Depends on: Vector<float32,4> or distinct type system, Texture2D (for return type of sample())

Methods: public float32 red(), public float32 green(), public float32 blue(), public float32 alpha(), public Color withAlpha(float32 newAlpha), public Color toSRgb(), public static Color fromSRgb(Color srgbColor), public Color premultiply(), public Color unpremultiply()

Complex

• Priority: now · Families: Value Types — Survey Gaps (Operator-Overloaded), numeric-complex
• Type params: <T extends Floating>
• Element types: float16, float32, float64 (element type constrained by )
• Purpose: Cartesian complex numbers: a + bi. Element type T must be float16, float32, or float64 (Floating bound). Supports arithmetic (+/-/*/÷), conjugate, absolute magnitude, phase angle, conversion to/from polar form.
• Representation: Struct with two T fields (real, imag); lowered as aggregate (either two separate SSA values or a packed struct per ABI). By-value on stack for small T. Host and device lowering identical.
• GPU notes: Complex and Complex vector SIMD-friendly: two LLVM scalars = struct or pair of SSA values. Device lowering mirrors host (no special intrinsics needed; all ops decompose to scalar arithmetic). Vector<Complex, N> is deferred — would be useful for FFT/signal work but requires operator-overload gateway unlocking Complex first. Device math (sin/cos/atan2 for phase) already supported via Math.{sin,cos,atan2} device lowering (xpu-plan B2-Inc1).
• Depends on: Floating (marker bound), hash() for structural equality

Methods: public Complex<T> conjugate(), public T abs(), public T absSq(), public T phase(), toPolar(…), public static Complex<T> fromPolar(T magnitude, T phase), public int64 hash() override, public T real(), public T imag(), public static Complex<T> conj(Complex<T> z), public static T abs(Complex<T> z), public static T absSq(Complex<T> z), public static T arg(Complex<T> z), public static Complex<T> exp(Complex<T> z), public static Complex<T> log(Complex<T> z), public static Complex<T> pow(Complex<T> z, T exponent), public static Complex<T> sin(Complex<T> z), public static Complex<T> cos(Complex<T> z)

CooperativeMatrix<T,Rows,Cols,Use>

• Priority: now · Families: tensor-ml
• Type params: <T extends Numeric, uint32 Rows, uint32 Cols, uint32 Use>
• Element types: float16 (IEEE binary16), float32
• Purpose: Device-only tile-sized matrix multiply via hardware matrix cores (WMMA), living distributed across a wavefront’s per-invocation registers. Maps to SPIR-V OpTypeCooperativeMatrixKHR. A single fused MMA (multiply-add) is one tile-sized operation on the matrix-core register file. T is the element type (float16, float32); Rows=Cols for v1 square tiles; Use is 0 (MatrixA), 1 (MatrixB), 2 (Accumulator).
• Representation: Opaque device-only type (no host layout). At device lowering, alloca a target(“spirv.CooperativeMatrixKHR”, T, scope, Rows, Cols, Use) in Function storage; each value lives in register file, never heap/addressable memory.
• GPU notes: VULKAN-ONLY in v1 (SPV_KHR_cooperative_matrix + SPV_KHR_vulkan_memory_model). Register residency on RDNA3 WMMA cores; bit-exact matmul via hardware fused MMA (CM5 verified on Radeon 8060S). Other backends: clean unsupported diagnostic. No method-templated operators needed — each overload (splat/mma/load/store) specializes on concrete (T, Rows, Cols, Use) from the class instantiation, resolved at device-lowering time by the DeviceLowerer. Device lowering intercepts method calls; no user-visible MMA implementation.
• Depends on: KernelBuffer (global device-memory binding), Non-type template parameter substrate (uint32 Rows/Cols/Use constants), float16 element type (IEEE binary16 — remapped from prior bfloat misnomer in CM5a)

Methods: public void load(KernelBuffer<T> src, uint32 offset, uint32 layout, uint32 stride), public void splat(T value), mma(…), public void store(KernelBuffer<T> dst, uint32 offset, uint32 layout, uint32 stride)

DualNumber

• Priority: now · Families: Value Types — Survey Gaps (Operator-Overloaded)
• Type params: <T extends Floating>
• Element types: float16, float32, float64 (floating-point only; integer autodiff is out of scope)
• Purpose: Automatic differentiation (forward-mode) for SPELA per-layer local-loss gradients. A dual number carries both the value and its derivative with respect to one independent variable. Essential for SPELA’s closed-form per-layer update — avoids the full reverse-mode autodiff stack that generic deep learning frameworks need.
• Representation: Two fields: real (T) and dual (T). Lowers to struct { T val; T deriv; } by value. Marshals to two consecutive elements in device buffers.
• GPU notes: By-value marshalling as two-field struct; device kernel forward pass uses dual numbers, back-substitutes gradient into per-layer parameter updates. No reverse-mode accumulation graph needed — SPELA’s closed-form is the feature. On non-Vulkan (CPU/AMD/NVIDIA, non-ray-query paths): device lowering treats as a simple 2-element composite, no special ops.
• Depends on: Vector<T,N> (for broadcasting scalar operations), Math.{sin,cos,exp,log} (device math B2)

Methods: public T value(), public T deriv(), public static DualNumber<T> sin(DualNumber<T> x), public static DualNumber<T> cos(DualNumber<T> x), public static DualNumber<T> exp(DualNumber<T> x), public static DualNumber<T> log(DualNumber<T> x), public static DualNumber<T> pow(DualNumber<T> base, T exponent)

Float16

• Priority: now · Families: numeric-complex
• Type params: (no type parameters — scalar only)
• Element types: N/A (scalar, not parameterized). Can be element type of Vector<float16, N> and Matrix<float16, R, C> once those types exist.
• Purpose: IEEE 754 binary16 (16-bit half precision) as a standalone scalar value type. Distinct from a Vector<float16, N>. Supports arithmetic, comparisons, and explicit casting to/from float32/float64. Primary use: ML models (FP16 training/inference), graphics (16-bit vertex attributes, texture formats), and dense tensor storage.
• Representation: LLVM half type (Type::getHalfTy). Lowered as a scalar in registers or stack. By-value marshalling to kernels. Device lowering: native float arithmetic on modern GPUs (Tesla, RDNA, Vulkan VK_FORMAT_R16_SFLOAT).
• GPU notes: Already supported in the type system (CajetaType::FLOAT16_TYPE_ID, llvm::Type::getHalfTy). CM5a (2026-06-04) remapped float16 from bfloat to IEEE-half to match device cooperative-matrix component types. Device Math intrinsics (B2-Inc1) already lower float16 ops to native instructions. No additional backend work needed; already green on CPU/Vulkan/AMD.
• Depends on: none; primitive

Methods: public float32 toFloat32(), public float64 toFloat64(), public static float16 fromFloat32(float32 x, RoundingMode mode = NEAREST_EVEN), public boolean isNaN(), public boolean isInfinite(), public boolean isFinite()

Matrix<T,R,C>

• Priority: now · Families: geometric-graphics, linear-algebra, tensor-ml
• Type params: <T extends Numeric, uint32 R, uint32 C>
• Element types: non-bool numeric primitives (same as Vector<T,N>)
• Purpose: Fixed-size R×C matrix. Value type for small linear algebra (3×3 rotations, 4×4 transforms). Proposed flat vector representation <R*C x T> or array-of-rows Vector<T,C>[R]. By-value kernel marshalling, register residency on GPU (proposed).
• Representation: Flat <R*C x T> LLVM vector type (or array-of-vectors), by-value POD marshalling. Kernel-arg marshalling identical to Vector — register residency, guaranteed inlining, no memory traffic.
• GPU notes: Planned register residency if flat <R*C x T>. By-value kernel marshalling (all-primitive fields, POD). Device lowering: flat-vector ops or row-loop inlining. CooperativeMatrix is separate device-only type (matrix-core register file, not a host value type).
• Depends on: Numeric, Vector<T,C> (for row access), linalg library

Methods (live): transpose(), identity() (square), row(i), col(j), hadamard(other); determinant() → scalar and inverse() → Matrix<T,N,N> (square 2×2/3×3/4×4, float). Mask (on a Matrix<boolean,R,C> from a comparison): all()/any() → boolean, select(whenTrue, whenFalse) → per-lane blend (MaskSelect.md). Deferred: norm(), matmul() method form (use the * intrinsic).

Ray

• Priority: now · Families: geometric-graphics
• Type params: <T extends Floating = float32>
• Element types: T: float32 (graphics); float16 (low-precision approximation)
• Purpose: Parametric ray for intersection tests, ray casting, visibility queries. Used in graphics (picking, shadows) and science (Monte-Carlo transport). Foundation type for ray-query operations.
• Representation: Origin (Vector<T,3>) + Direction (Vector<T,3> unit normalized). Parametric: P(t) = origin + t*direction, t ∈ [tMin, tMax].
• GPU notes: Primarily a host type for camera/graphics setup and spatial-query construction. Device-side: RayQuery (kernel-local opaque) represents traversal state. Ray host type marshals scalar components into RayQuery.initialize(). Origin/direction normalized on host; kernel does not re-normalize.
• Depends on: Vector<T,3> (foundation exists), AABB (for intersection testing)

Methods: public Ray(Vector<T,3> origin, Vector<T,3> direction, T tMin, T tMax), public Vector<T,3> pointAt(T t), public Ray<T> normalize(), public Vector<T,3> getOrigin(), public Vector<T,3> getDirection(), public T distanceToPoint(Vector<T,3> point), public boolean intersectAABB(AABB<T> box)

Tensor<T,Dims…>

• Priority: now · Families: tensor-ml
• Type params: <T extends Numeric, Dims... extends uint32>
• Element types: float16 (IEEE binary16), float32, float64, int8, int16, int32, int64; bfloat16 (future distinct keyword, distinct from float16); fp8 E4M3 / E5M2 (future, stored as i8, semantics via runtime helpers)
• Purpose: N-dimensional array value type for ML workloads (the workhorse of SPELA/Caramelo). Parameterized by element type T and shape dimensions (Dims = compile-time shape constants, e.g., Tensor<float32, 64, 32, 16> for a 3-D 64×32×16 tensor). Represents dense numeric data: matrices, batched matrices, feature maps, activations. On host: stack/heap allocation, element/slice access, elementwise + reductions. On device: GPU register/shared/global residency, cooperative-matrix binding, matmul/conv kernels.
• Representation: By-value POD on host (small fixed-shape tensor: flat <RCD x T> on stack or heap; the representation is an implementation detail, not part of the surface). On device: kernel-local allocations (Private for register, Shared for LDS, Global for buffers via KernelBuffer). No vtable; no heap indirection for shape metadata (compile-time-constant dims).
• GPU notes: On Vulkan compute kernels, a small Tensor passed by value marshals as a POD struct (field-by-field) to a descriptor-SSBO (read-only); large tensors are KernelBuffer parameters (bound as descriptors). A Tensor operand in a @Kernel is device-only (no host stub). Device lowering: elementwise ops → vectorized LLVM ops (fmul, fsub, etc.) that map to SIMD/GPU vector instructions per element type. Matmul on compatible device shapes targets CooperativeMatrix when available (Vulkan); fallback is a generic tiling loop. Device lowering does NOT inline arbitrary user operator-method calls inside kernels — only cooperative-matrix/ray-query method bodies are intercepted/lowered.
• Depends on: Element type T (Numeric primitives + float16/bfloat16/fp8), Non-type template parameter substrate (compile-time uint32 dimension constants), Method-templated static operators (BLOCKED; design decision needed for matmul), Multi-index operator[i,j] syntax (blocked on lexer pass per OperatorOverloading.md)

Methods: public T sum() — or — public Tensor<T,OtherDims...> sum(uint32 axis), public T mean() — or — public Tensor<T,OtherDims...> mean(uint32 axis), public T max() — or — public Tensor<T,OtherDims...> max(uint32 axis), public T min() — or — public Tensor<T,OtherDims...> min(uint32 axis), public Tensor<T,DimC,DimA,DimB> transpose(uint32 axes...), public Tensor<T,R,C> matmul(Tensor<T,K,C> other), public Tensor<T,NewDims...> reshape(NewDims... shape)

Transform (Mat4)

• Priority: now · Families: geometric-graphics
• Type params: no type parameter (fixed float32)
• Element types: float32 (fixed, not parameterized)
• Purpose: Homogeneous 4×4 transformation matrix for 3D graphics. Translation, rotation, scale, perspective. Foundation for camera matrices, object poses, viewport transforms.
• Representation: 4×4 row-major float32 matrix = Matrix<float32,4,4>. Reuses Matrix flat <16 x float32> representation.
• GPU notes: Transform is specialization of Matrix<float32,4,4>; no separate lowering. Vertex shaders use Transforms for model/view/projection matrices. By-value kernel-arg: passed as <16 x float32>. Construct functions synthesized at compile-time (host JIT); device kernels consume by value.
• Depends on: Matrix<float32,4,4> (Transform is alias/wrapper), Vector<float32,3>, Vector<float32,4> (used in operator* signatures), Quaternion (extractRotation output)

Methods: public Transform inverse(), public Transform transpose(), public static Transform translation(float32 x, float32 y, float32 z), public static Transform rotationX(float32 angleRadians), public static Transform rotationY(float32 angleRadians), public static Transform rotationZ(float32 angleRadians), public static Transform scale(float32 x, float32 y, float32 z), perspective(…), orthographic(…), lookAt(…), public Vector<float32,3> extractTranslation(), public Quaternion<float32> extractRotation()

Vector<T,N>

• Priority: now · Families: linear-algebra
• Type params: <T extends Numeric, uint32 N>
• Element types: non-bool numeric primitives: int8, int16, int32, int64, float32, float64, float16, bfloat16, float8e4m3, and other fp dtypes
• Purpose: Fixed-width numeric vector with N lanes of element type T, lowering to LLVM . PRIMITIVE_FLAG|VECTOR_FLAG value type: passed by value, no heap, no vtable. Element-wise arithmetic, component/index access, dot/length/normalize geometry helpers.
• Representation: LLVM FixedVectorType , flat SSA value, register-resident on GPU. By-value kernel-arg marshalling (KernelArgTrait: PRIMITIVE_FLAG admits by value).
• GPU notes: Register residency: flat SSA, no memory traffic. Native SIMD/GPU vector instructions. By-value kernel marshalling (PRIMITIVE_FLAG). Device lowering: KernelLowering.cpp intercepts known types, emits intrinsic IR. Guaranteed inlining. Live: CPU JIT, Vulkan, AMD, NVIDIA (emit-only).
• Depends on: Numeric (element type), vecops (VectorOps.h helpers)

Status (2026-06-05) — Vector operators are COMPILER INTRINSICS, not declared overloads. Vector<T,N> is a bare CajetaVector carrying PRIMITIVE_FLAG | VECTOR_FLAG, so it is excluded from the operator-dispatch gate on both counts (!CajetaClass and PRIMITIVE_FLAG). Its + - * / == [] are intercepted in BinaryOpExpression/ArrayIndexExpression (host) and KernelLowering (device) and emitted as flat <N x T> SSA — the signatures in the table below are documentary (the canonical surface a future declared form would expose), not source the compiler reads. Consequences:

• Vector is the register-residency reference the @ValueType mechanism preserves: emitted IR is byte-identical to the pre-mechanism intrinsic path, pinned by the S0 golden oracle (test/expression/VectorHostGoldenIrTests.cpp host + XpuVectorDeviceTests device).
• Vector’s operator[] read and operator[]= element-write are intrinsic mutable-vector ops and are exempt from the S3 @ValueType mutating-operator ban — that ban (CAJETA_ERROR_VALUE_TYPE_MUTATING_OPERATOR) forbids declaring a mutating operator on a by-value @ValueType CajetaClass; Vector is not one, and v[i] = x mutates the value’s inline slot directly via insertelement.
• Synthesizing declared Vector operator signatures (making the surface above real source backed by the interception, gate still bypassing CajetaVector) is deferred (documentary-first, plan Decision #5). The intrinsic path is the implementation; a declared façade would be ergonomic sugar only.

Component / swizzle reads: .x/.y/.z/.w (and .r/.g/.b/.a) read one lane; a 2-4 letter swizzle .xy/.xyz/.xxyy/.zyx reads a Vector<T,M> (repeats allowed; lowers to shufflevector). Out-of-range letters → CAJETA_ERROR_VECTOR_COMPONENT. Swizzle writes (v.xy = …) deferred.

Methods:

• geometry/math: dot(other), length(), normalize(); cross(other) (3-D), reflect(n), refract(n, eta), distance(other); min(b), max(b), clamp(lo, hi), lerp(b, t) — float element, v1; integer min/max deferred.
• integer dot (DP4a): on Vector<int8,4> / Vector<uint8,4>, dot(other) → int32 and the fused dot(other, acc) → acc + dot. Signedness is the element type (OpSDot/OpUDot); Vulkan emits the SPV_KHR_integer_dot_product hardware unit, other backends a portable widening reduce (bit-exact). 4-lane 8-bit only, v1. See IntegerDotProduct.md.
• mask (on a Vector<boolean,N> from a comparison): all()/any() → boolean, select(whenTrue, whenFalse) → per-lane blend. Masks are register-only — KernelBuffer<Vector<boolean,N>> / bool-vector kernel args stay ABI-rejected.

BFloat16

• Priority: soon · Families: numeric-complex
• Type params: (no type parameters — scalar only)
• Element types: N/A (scalar). Can be element type of Vector<bfloat16, N> and Matrix<bfloat16, R, C>.
• Purpose: Google’s bfloat16 (16-bit brain float) format: 1 sign + 8 exponent + 7 mantissa bits, matching the range of float32 but with coarser mantissa precision. Used in TPU training, some NVIDIA tensor-core workflows, and quantized LLM inference. Distinct from IEEE float16 (which has 5 exp + 10 mantissa).
• Representation: LLVM bfloat type (Type::getBFloatTy). Lowered as a scalar. By-value marshalling. Device: native on recent NVIDIA (NVIDIA compute ≥8.0, sm_90), AMD, and TPUs; emulated on older/other targets via float32 → truncate.
• GPU notes: LLVM support: Type::getBFloatTy exists; arithmetic intrinsics map to bf16 fcmp/fadd/etc. Device math (xpu-plan C2, Tier-2) — port OpenCL-flavor bfloat16 atomics/ops to Vulkan Shader flavor (SPV_KHR_bfloat16 capability). Deferred: bfloat16 arithmetic is Tier-2 (in LLVM but not Shader-flavor-exposed); needs SPIR-V backend port. Cooperative matrix CM5c only exposes f16/f16→f32 config on current hardware; bfloat16 configs may surface on newer hardware and will need device support. The scalar primitive itself is already registered (BFLOAT16_TYPE_ID, llvm::Type::getBFloatTy); what is deferred is the Shader-flavor device arithmetic lowering, so for now treat as ‘primitive present, device math pending’.
• Depends on: none; primitive (registered; device-arithmetic lowering deferred)

Methods: public float32 toFloat32(), public float64 toFloat64(), public static bfloat16 fromFloat32(float32 x, RoundingMode mode = NEAREST_EVEN), public float16 toFloat16(RoundingMode mode = NEAREST_EVEN)

Float8E4M3

• Priority: soon · Families: numeric-complex
• Type params: (no type parameters — scalar only)
• Element types: N/A (scalar). Element type of Vector<float8e4m3, N> useful for dense tensor storage and training.
• Purpose: 8-bit floating point, E4M3 format (4-bit exponent, 3-bit mantissa, no implicit bit, no -0). Used in very-low-precision ML training (especially with stochastic rounding and gradient clipping), quantized LLM inference, and dense tensor formats (OCP Tensor Float 32 extended). Narrower range than float8e5m2 but finer precision near zero.
• Representation: Opaque 8-bit type (registered as FLOAT8E4M3_TYPE_ID in CajetaType). Lowered to i8 storage, arithmetic via float32 (load as f32, compute, truncate back). Device: LLVM backend has SPIRVSubtarget float8 modes; emulate on CPU via C intrinsics.
• GPU notes: Device: SPIR-V backend has SPV_KHR_float_controls + float8 modes; NVIDIA libdevice has fp8 math; AMD OCml supports fp8 GEMM. CPU: intrinsic C quantization routines via llvm.convert.to.fp8. Priority: xpu-plan C2 Tier-3 — no LLVM backend support yet (E4M3 is not in the current SPIR-V backend). Deferred pending upstream LLVM fp8 work (LLVM 25+?). For now, type skeleton exists in runtime (boxed Float8E4M3 per CajetaMath.md), but primitive float8e4m3 scalar and arithmetic operators land when the type system + device lowering infrastructure exist (Part B1/B2 in xpu-plan).
• Depends on: RoundingMode (for casting); cajeta.math.math for quantization helpers

Methods: public float32 toFloat32(), public float64 toFloat64(), fromFloat32(…), public float8e4m3 saturatingAdd(float8e4m3 other), public float8e4m3 saturatingSub(float8e4m3 other), public float8e4m3 saturatingMul(float8e4m3 other), public boolean isNaN(), public boolean isInfinite(), public boolean isFinite()

Float8E5M2

• Priority: soon · Families: numeric-complex
• Type params: (no type parameters — scalar only)
• Element types: N/A (scalar). Element type of Vector<float8e5m2, N>.
• Purpose: 8-bit floating point, E5M2 format (5-bit exponent, 2-bit mantissa, implicit bit, supports ±∞). Used in quantized neural networks where range matters more than mantissa precision, and in OCP Tensor Float 32. Complements Float8E4M3 (wider range, coarser precision).
• Representation: Opaque 8-bit type (FLOAT8E5M2_TYPE_ID). Stored as i8, arithmetic via float32 upconvert/downconvert, same path as E4M3.
• GPU notes: Deferred as per Float8E4M3 — C2 Tier-3. Device support available on NVIDIA sm_90, AMD RDNA, via downstream LLVM patches. Host: C intrinsic quantization.
• Depends on: RoundingMode

Methods: public float32 toFloat32(), public float64 toFloat64(), fromFloat32(…), public float8e4m3 toFloat8E4M3(RoundingMode mode = NEAREST_EVEN), public boolean isInfinite(), public boolean isNaN(), public boolean isFinite()

Plane

• Priority: soon · Families: geometric-graphics
• Type params: <T extends Floating = float32>
• Element types: T: float32 (typical)
• Purpose: Planar surface defined by normal + distance from origin. Used in visibility testing, clipping, collision detection. Graphics-adjacent (frustum culling).
• Representation: Normal vector (Vector<T,3> unit normalized) + scalar distance (d). Implicit form: normal · (point - origin) = d.
• GPU notes: Host/graphics type for camera frustum setup and geometric predicates. Device: used in fragment shaders for lighting/visibility (compute signed distance via dot product). No special device lowering; by-value struct (normal + scalar).
• Depends on: Vector<T,3> (foundation exists)

Methods: public Plane(Vector<T,3> normal, T distance), public T signedDistance(Vector<T,3> point), public Vector<T,3> project(Vector<T,3> point), public Vector<T,3> reflect(Vector<T,3> vector), public Vector<T,3> getNormal(), public T getDistance()

Quaternion

• Priority: soon · Families: Value Types — Survey Gaps (Operator-Overloaded), geometric-graphics, linear-algebra, tensor-ml
• Type params: <T extends Numeric>
• Element types: numeric primitives T: float32, float64 (float-only for most methods)
• Purpose: Unit quaternion for 3-D rotations: w + xi + yj + zk. By-value semantics. Composition via operator, vector rotation, interpolation (slerp/nlerp).
• Representation: Four fields (normalized): w (scalar), x, y, z (vector). Lowers to struct { T w; T x; T y; T z; } or [4 x T] by value. Can use Vector<T,4> as backing for swizzle-friendly layouts.
• GPU notes: Register residency: {T,T,T,T} = 4 floats = 16 bytes, small SSA aggregate. By-value kernel marshalling (4 numeric fields, POD). Device lowering: methods inline to vector/scalar ops. Used in graphics, robotics, game physics. Unrelated to CooperativeMatrix (device-only matrix core).
• Depends on: Numeric, Vector<T,3>, Matrix<T,3,3>, Math (sin, cos, sqrt, atan2)

Status (2026-06-05) — LIVE (host + CPU/Vulkan), a compiler intrinsic like Vector/Matrix. CajetaQuaternion carries QUATERNION_FLAG | PRIMITIVE_FLAG, lowering to a flat <4 x T> = (w, x, y, z); float element only (CAJETA_ERROR_QUATERNION_ELEMENT_TYPE). Construction new/stack Quaternion<T>(w,x,y,z). Operators (intrinsic, the table below is documentary): * = Hamilton product Quaternion*Quaternion and vector rotation Quaternion*Vector<T,3> (→ rotated Vector<T,3>); + - element-wise. Methods: normalize(), conjugate(), length(), dot(other), and the interpolators slerp(other, t) (constant angular velocity; acos/sin via the device transcendental seam, branchless with an automatic near-parallel nlerp fallback) and nlerp(other, t) (cheaper normalized lerp). Both run on CPU/Vulkan/AMD. The ==→boolean row below is superseded by the value-type comparison-mask rule (MaskSelect.md) and is not implemented for Quaternion in v1.

Methods: public static Quaternion<T> identity(), public static Quaternion<T> fromAxisAngle(Vector<T,3> axis, T angleRadians), public static Quaternion<T> fromEuler(T roll, T pitch, T yaw), public static Quaternion<T> fromMatrix(Matrix<T,3,3> m), public static Quaternion<T> fromTwoVectors(Vector<T,3> from, Vector<T,3> to), public Quaternion<T> inverse(), public Quaternion<T> conjugate(), public Quaternion<T> normalize(), public T norm(), public T dot(Quaternion<T> other), public Matrix<T,3,3> toMatrix(), public Vector<T,3> toEuler(), public static Quaternion<T> slerp(Quaternion<T> a, Quaternion<T> b, T t), public static Quaternion<T> nlerp(Quaternion<T> a, Quaternion<T> b, T t), public T magnitude(), public T angle(), public static Quaternion<T> conjugate(Quaternion<T> q), public static Quaternion<T> inverse(Quaternion<T> q), public static T norm(Quaternion<T> q), public static Quaternion<T> normalize(Quaternion<T> q), public static T dot(Quaternion<T> p, Quaternion<T> q), public static Quaternion<T> slerp(Quaternion<T> p, Quaternion<T> q, T t), public static Vector<T,3> rotateVector(Quaternion<T> q, Vector<T,3> v), public static Matrix<T,3,3> toMatrix(Quaternion<T> q)

Rect (Bounds2D)

• Priority: soon · Families: geometric-graphics
• Type params: <T extends Numeric = float32>
• Element types: T: float32 (continuous UI/graphics); uint32 (pixel-grid texture regions); int32 (discrete spatial indexing)
• Purpose: 2D axis-aligned rectangle for UI layout, sprite bounds, texture regions, 2D spatial queries. Foundation for UI rendering and 2D graphics.
• Representation: Two Vector<T,2> endpoints (minPoint, maxPoint). Analogous to AABB but in 2D.
• GPU notes: 2D graphics-only type (UI, sprite rendering, texture atlasing). Host-side construction; device use optional (2D compute shaders). Marshalled as two Vector<T,2> by value.
• Depends on: Vector<T,2> (foundation exists), Numeric bound (from Vector)

Methods: public boolean contains(Vector<T,2> point), public boolean containsRect(Rect<T> other), public boolean overlaps(Rect<T> other), public Vector<T,2> center(), public Vector<T,2> extent(), public T width(), public T height(), public T area(), public Rect<T> expand(Vector<T,2> point), public Rect<T> inset(T amount)

SaturatingInt

• Priority: soon · Families: numeric-complex
• Type params: <T extends Integral>
• Element types: int8, int16, int32, int64, uint8, uint16, uint32, uint64 (element type constrained by )
• Purpose: Signed/unsigned integer wrapper that saturates on overflow (a += b caps at T.MAX if overflow, floors at T.MIN on underflow). Useful for graphics (clamped color channels), signal processing (fixed-point saturation), and neural-network quantization where wrapping would corrupt semantics. Distinct from wrapping-arithmetic variants.
• Representation: Wrapper around T (int8/16/32/64 or corresponding unsigned). Stored by value. Host lowering: checked arithmetic + conditional MAX/MIN assignment. Device: use LLVM saturating arithmetic intrinsics (llvm.sadd.sat / llvm.uadd.sat on targets that support them; fallback to scalar clamp).
• GPU notes: Requires device-lowering knowledge of saturating intrinsics. NVPTX (llvm.nvvm.sad.*), AMD (llvm.amdgcn.add.sat), and SPIR-V (none standard; emulate via checked arithmetic) all differ. Deferred until device math (xpu-plan B2) standardizes the lowering surface.
• Depends on: Integral (marker bound)

Methods: public SaturatingInt<T> saturatingAdd(SaturatingInt<T> other), public SaturatingInt<T> saturatingSub(SaturatingInt<T> other), public SaturatingInt<T> saturatingMul(SaturatingInt<T> other), public SaturatingInt<T> saturatingNeg()

WrappingInt

• Priority: soon · Families: numeric-complex
• Type params: <T extends Integral>
• Element types: int8, int16, int32, int64, uint8, uint16, uint32, uint64 (element type constrained by )
• Purpose: Signed/unsigned integer wrapper with wrapping (two’s-complement) arithmetic on overflow. Matches Rust’s std::num::Wrapping; useful for modular arithmetic, checksums, hash functions, and explicit bit-manipulation code where wrapping is the intended behavior.
• Representation: Wrapper around T (int8/16/32/64 or unsigned). Stored by value. Lowering: plain unchecked arithmetic (same as built-in primitives); semantics are that overflow wraps.
• GPU notes: No special device lowering needed — wrapping is the default arithmetic semantics on both CPU and GPU. Plain IR emit identical to built-in int arithmetic.
• Depends on: Integral (marker bound)

Methods: public WrappingInt<T> wrappingAdd(WrappingInt<T> other), public WrappingInt<T> wrappingSub(WrappingInt<T> other), public WrappingInt<T> wrappingMul(WrappingInt<T> other), public WrappingInt<T> wrappingNeg()

FixedPoint<T, uint32 Frac>

• Priority: later · Families: Value Types — Survey Gaps (Operator-Overloaded)
• Type params: <T extends Integral, uint32 Frac>
• Element types: int32, int64, uint32, uint64
• Purpose: Deterministic fixed-point arithmetic for finance (pennies, cents), physics-based games (deterministic lockstep multiplayer), and embedded ML inference where float rounding non-determinism is unacceptable. Trades range for precision: Frac bits hold the fractional part, the rest the integer. No rounding surprises across platforms.
• Representation: Single integral field raw (T, usually int32/int64). The value is raw / 2^Frac (logical), but stored as the raw bit pattern. Lowers to struct { T raw; } by value, with operator codegen scaling by 2^Frac.
• GPU notes: By-value raw-field marshalling; integer arithmetic only, no float ops, so fully deterministic across all backends (CPU/AMD/NVIDIA/Vulkan). Common in physics-engine kernels (collision detection, constraint solvers) and financial simulations. No special GPU support needed — shifts/multiplies are standard integer ops.
• Depends on: Math.abs (for fixed-point absolute value), Integer bit shift operators (no overload; built-in)

Methods: public static FixedPoint<T,Frac> from(float64 realValue), public T toInt(), public float64 toFloat(), public T frac(), public static FixedPoint<T,Frac> round(FixedPoint<T,Frac> a, uint32 newFrac), public static FixedPoint<T,Frac> abs(FixedPoint<T,Frac> a)

Interval

• Priority: later · Families: Value Types — Survey Gaps (Operator-Overloaded)
• Type params: <T extends Floating>
• Element types: float32, float64 (float16 interval width too coarse for meaningful bounds in most cases)
• Purpose: Validated numerics for robust geometric computation, physics simulation, and scientific computing where correctness matters more than speed. Tracks the range [lo, hi] guaranteed to contain the true value, catching rounding errors and instability in accumulations. Used in point-in-polygon, ray-triangle intersection, constraint-solver iterations, uncertainty quantification.
• Representation: Two fields: lo (T, rounded down) and hi (T, rounded up). Lowers to struct { T lo; T hi; } by value. Requires rounding-mode control at the arithmetic level (not just the type level) — CPU support is native (FENV / FLT_ROUNDS), GPU support varies (SPIR-V has no RoundingMode cap; cuComplex on NVIDIA is native; RDNA has rounding instructions).
• GPU notes: Device support is incomplete: SPIR-V lacks an RoundingMode capability or instruction-level rounding control. On CPU (LLJIT) and AMD (AMDGPU has rounding instructions per ISA), rounding is implementable. On Vulkan, must simulate via software (expensive — two instructions per op instead of one, plus atomics for certain patterns). NVIDIA CUDA has native rounding in PTX. Recommendation: defer full GPU support to after B2/B3/C1 lands; CPU-only interval arithmetic is useful for host-side validation/constraint solving (ODE integrators, geometric predicates). Surface the type; mark device kernel use as XPU-N02 (not supported) until GPU rounding is available.
• Depends on: Math.{sqrt,sin,cos} (transcendental interval bounds), fenv (host rounding control; see GPU notes)

Methods: public T width(), public T midpoint(), public boolean contains(T x), public static Interval<T> sqrt(Interval<T> x), public static Interval<T> sin(Interval<T> x), public static Interval<T> cos(Interval<T> x), public static Interval<T> intersection(Interval<T> a, Interval<T> b), public static Interval<T> union(Interval<T> a, Interval<T> b)

Range (Interval)

• Priority: later · Families: geometric-graphics
• Type params: <T extends Numeric>
• Element types: T: any Numeric (float32 for continuous; int32/uint32 for discrete counts/bounds)
• Purpose: 1D interval [min, max] for 1D spatial queries, clip planes, animation timelines, parameter ranges. Lightweight foundation for range-based algorithms.
• Representation: Two scalar endpoints (min, max). Pure scalar pair (no Vector involved).
• GPU notes: Utility type (no special GPU lowering). Used in host-side logic (clip planes, timelines); kernel-local ranges typically computed inline (loop bounds, parameter constraints), not marshalled as type.
• Depends on: Numeric bound (primitive validation)

Methods: public boolean contains(T value), public boolean containsRange(Range<T> other), public boolean overlaps(Range<T> other), public T length(), public T clamp(T value), public Range<T> expand(T value)

Source: docs/specification/gpu/ValueTypeCatalog.md · 42 min read · 9273 words