stillwater-sc
diff --git a/‎.github/workflows/cmake.yml‎
Lines changed: 1 addition & 1 deletion b/‎.github/workflows/cmake.yml‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎CHANGELOG.md‎
Lines changed: 7 additions & 0 deletions b/‎CHANGELOG.md‎
Lines changed: 7 additions & 0 deletions
diff --git a/‎CMakeLists.txt‎
Lines changed: 1 addition & 1 deletion b/‎CMakeLists.txt‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎docs/number-systems/README.md‎
Lines changed: 133 additions & 0 deletions b/‎docs/number-systems/README.md‎
Lines changed: 133 additions & 0 deletions
diff --git a/‎docs/number-systems/areal.md‎
Lines changed: 112 additions & 0 deletions b/‎docs/number-systems/areal.md‎
Lines changed: 112 additions & 0 deletions
@@ -2,7 +2,7 @@ name: CMake
 
 on:
   push:
-    branches: [ v3.98, main ]
+    branches: [ v3.99, main ]
   pull_request:
     branches: [ main ]
 
 
@@ -28,6 +28,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - **MinGW GCC IPA ICF bug**: function splitting + Identical Code Folding incorrectly merges `lns<4>::setbit.part.0` with `lns<8>::setbit.part.0`, causing all negative LNS values to lose their sign bit when multiple `lns<nbits>` instantiations exist in the same translation unit. Fix: `-fno-ipa-icf`
   - **MinGW software `std::fma()` precision bug**: off by 1-2 ULPs for some inputs, breaking error-free transformations (`two_prod`) in `floatcascade`. Fix: `-mfma` to use hardware FMA3 instructions
 
+### Fixed
+
+#### 2026-02-13 - Fix blockbinary operator[] vs test() misuse in posit components
+
+- **`positFraction.hpp` stack-buffer-overflow** (ASan CI failure): `blockbinary::operator[]` is a **block/limb** index accessor, but was used with **bit** indices in three locations — `operator<<`, `get_fixed_point()`, and `denormalize()`. For `posit<16,1,uint8_t>` with `fbits=12`, accessing `_block[11]` tried to read block 11 of a 2-block array. Fixed all three to use `_block.test(i)` for proper bit-level access.
+- **`posit_impl.hpp` reciprocal sign extraction**: `_block[nbits-1]` used block index instead of bit index to read the sign bit. For `posit<16,1,uint8_t>`, `_block[15]` accessed block 15 of a 2-block array. Fixed to `_block.test(nbits-1)`.
+
 - **All 390 CI_LITE tests pass** on MinGW+Wine after fixes
 
 #### 2026-02-13 - Rewrite Atomic Fused Operators to blocktriple and Extract Quire from posit.hpp
 
@@ -20,7 +20,7 @@ if(NOT DEFINED UNIVERSAL_VERSION_MAJOR)
   set(UNIVERSAL_VERSION_MAJOR 3)
 endif()
 if(NOT DEFINED UNIVERSAL_VERSION_MINOR)
-  set(UNIVERSAL_VERSION_MINOR 98)
+  set(UNIVERSAL_VERSION_MINOR 99)
 endif()
 if(NOT DEFINED UNIVERSAL_VERSION_PATCH)
   set(UNIVERSAL_VERSION_PATCH 1)
 
@@ -0,0 +1,133 @@
+# Universal Number Systems Guide
+
+This directory contains comprehensive documentation for each number system in the Universal library. Each document explains **why** the number system exists, **what** it does, and **how** to use it to solve specific problems.
+
+## Number Systems by Category
+
+### Integer and Fixed-Point
+
+| Type | Bits | Description | Best For |
+|------|------|-------------|----------|
+| [integer](integer.md) | N | Arbitrary-width signed integer | Cryptography, combinatorics, wide counters |
+| [fixpnt](fixpnt.md) | N | Binary fixed-point with configurable radix | DSP, control systems, embedded (no FPU) |
+| [rational](rational.md) | 2N | Exact numerator/denominator fraction | Symbolic math, exact geometry, financial |
+
+### Configurable Floating-Point
+
+| Type | Bits | Description | Best For |
+|------|------|-------------|----------|
+| [cfloat](cfloat.md) | 4-256 | Fully parameterized IEEE-compatible float | Mixed-precision research, custom HW design |
+| [bfloat16](bfloat16.md) | 16 | Google Brain Float (8-bit exponent, 7-bit fraction) | Neural network training, TPU workloads |
+| [areal](areal.md) | N | Faithful float with uncertainty bit | Verified computing, uncertainty tracking |
+| [dfloat](dfloat.md) | N | Decimal floating-point (base-10) | Financial systems, regulatory compliance |
+
+### Micro-Precision and Block-Scaled (AI Quantization)
+
+| Type | Bits | Description | Best For |
+|------|------|-------------|----------|
+| [microfloat](microfloat.md) | 4-8 | OCP MX element types (e2m1, e4m3, e5m2) | AI model elements, quantization validation |
+| [e8m0](e8m0.md) | 8 | Exponent-only power-of-two scale | Block scale factor for MX format |
+| [mxfloat](mxfloat.md) | Block | OCP Microscaling block format | AI inference, model compression (OCP) |
+| [nvblock](nvblock.md) | Block | NVIDIA NVFP4 block format | GPU inference, NVIDIA accelerators |
+
+### Posit Family (UNUM Type III)
+
+| Type | Bits | Description | Best For |
+|------|------|-------------|----------|
+| [posit](posit.md) | N | Tapered-precision floating-point (current v2) | General numeric, more precision than IEEE |
+| [posit1](posit1.md) | N | Original posit implementation (legacy v1) | Quire/FDP support, backward compatibility |
+| [posito](posito.md) | N | Experimental posit variant | Differential testing, research |
+| [quire](quire.md) | Wide | Super-accumulator for exact dot products | Reproducible linear algebra, BLAS |
+| [takum](takum.md) | N | Bounded-range tapered float | General computing, predictable range |
+
+### Interval and Uncertainty Arithmetic
+
+| Type | Bits | Description | Best For |
+|------|------|-------------|----------|
+| [valid](valid.md) | 2N | Interval arithmetic with posit-encoded bounds | Verified computing with posit precision |
+| [interval](interval.md) | 2N | Generic interval over any scalar type | Tolerance analysis, uncertainty propagation |
+| [sorn](sorn.md) | N | Set of operand range numbers | Rigorous uncertainty, safety-critical bounds |
+| [unum2](unum2.md) | N | Configurable exact-value lattice | Research, custom value distributions |
+
+### Logarithmic Number Systems
+
+| Type | Bits | Description | Best For |
+|------|------|-------------|----------|
+| [lns](lns.md) | N | Single-base logarithmic (base 2) | DSP, multiply-heavy workloads, low-power HW |
+| [dbns](dbns.md) | N | Double-base logarithmic (base 0.5 and 3) | Research, mixed-radix applications |
+
+### Extended Precision (Multi-Component)
+
+| Type | Bits | Decimal Digits | Description | Best For |
+|------|------|---------------|-------------|----------|
+| [dd](dd.md) | 128 | ~31 | Double-double (2 doubles) | Extended precision, ill-conditioned systems |
+| [qd](qd.md) | 256 | ~64 | Quad-double (4 doubles) | Ultra-high precision, constant computation |
+| [dd_cascade](dd_cascade.md) | 128 | ~31 | DD via unified cascade framework | Consistent API across precision tiers |
+| [td_cascade](td_cascade.md) | 192 | ~48 | Triple-double (3 doubles) | Intermediate precision tier |
+| [qd_cascade](qd_cascade.md) | 256 | ~64 | QD via unified cascade framework | Consistent API across precision tiers |
+
+### Compressed Floating-Point
+
+| Type | Description | Best For |
+|------|-------------|----------|
+| [zfpblock](zfpblock.md) | ZFP block-based float compression (1D/2D/3D) | Scientific data storage, simulation checkpoints |
+
+### Complex Number Support
+
+| Type | Description | Best For |
+|------|-------------|----------|
+| [complex](complex.md) | Complex arithmetic for any Universal scalar | FFT, signal processing, quantum computing |
+
+## Choosing a Number System
+
+### By Application Domain
+
+| Domain | Recommended Types |
+|--------|-------------------|
+| **Deep Learning Inference** | microfloat, mxfloat, nvblock, bfloat16, cfloat(fp8) |
+| **Deep Learning Training** | bfloat16, cfloat(fp16/fp32), posit |
+| **DSP / Signal Processing** | fixpnt, lns, complex |
+| **Financial / Accounting** | dfloat, rational, fixpnt |
+| **Embedded (no FPU)** | fixpnt, integer |
+| **Scientific HPC** | dd, qd, posit, cfloat |
+| **Verified / Validated Computing** | interval, valid, areal, sorn |
+| **Reproducible Linear Algebra** | posit + quire |
+| **Cryptography / Big Numbers** | integer |
+| **Data Compression** | zfpblock |
+| **Custom Hardware Design** | cfloat, posit, takum, lns |
+
+### By Precision Need
+
+| Precision | Type | Decimal Digits |
+|-----------|------|---------------|
+| 2 digits | bfloat16 | ~2 |
+| 3 digits | cfloat(fp8), microfloat | ~2-3 |
+| 7 digits | cfloat(fp32), posit<32,2> | ~7-8 |
+| 16 digits | cfloat(fp64), double | ~16 |
+| 31 digits | dd, dd_cascade | ~31 |
+| 48 digits | td_cascade | ~48 |
+| 64 digits | qd, qd_cascade | ~64 |
+| Exact | rational, integer, quire | Unlimited (within nbits) |
+
+## Quick Start
+
+Every number system is header-only. Include the type and start computing:
+
+```cpp
+#include <universal/number/posit/posit.hpp>  // or any type
+using namespace sw::universal;
+
+// Plug-in replacement pattern
+template<typename Real>
+Real my_algorithm(Real a, Real b) {
+    return (a + b) * (a - b);
+}
+
+// Use with any Universal type
+auto r1 = my_algorithm(posit<32,2>(3.0), posit<32,2>(4.0));
+auto r2 = my_algorithm(cfloat<16,5,uint16_t,true,false,false>(3.0),
+                        cfloat<16,5,uint16_t,true,false,false>(4.0));
+auto r3 = my_algorithm(dd(3.0), dd(4.0));
+```
+
+For detailed usage patterns, see the `api/api.cpp` test file in each number system's regression test directory under `static/`.
@@ -0,0 +1,112 @@
+# Areal: Faithful Floating-Point with Uncertainty Bit
+
+## Why
+
+IEEE-754 floating-point silently rounds every result to the nearest representable value. After a chain of operations, you have no idea how much rounding error has accumulated -- the final answer looks just as precise as every intermediate result, even if it's completely wrong. The only way to discover the error is to re-run the computation in higher precision, which is expensive and often impractical.
+
+The `areal` type solves this with a single-bit innovation: the **uncertainty bit (ubit)**. The least significant bit of every areal value indicates whether the value is exact or approximate. When an operation produces a result that falls between two representable values, the ubit is set to 1, meaning "the true value lies between this encoding and the next." You get faithful floating-point arithmetic where every result honestly reports whether it was rounded.
+
+## What
+
+`areal<nbits, es, bt>` is a faithful floating-point with an uncertainty bit:
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `nbits` | `unsigned` | -- | Total bits (minimum: es + 3) |
+| `es` | `unsigned` | -- | Exponent bits |
+| `bt` | typename | `uint8_t` | Storage block type |
+
+### Encoding
+
+```
+[sign : 1 bit] [exponent : es bits] [fraction : fbits] [ubit : 1 bit]
+```
+
+Where `fbits = nbits - 2 - es` (the uncertainty bit takes one bit from what would be fraction in a standard float).
+
+### The Uncertainty Bit
+
+- **ubit = 0**: The value is *exactly* the represented floating-point value
+- **ubit = 1**: The true value lies *strictly between* this encoding and the next representable value
+
+This provides a faithful bound: the true result is always within one ULP of the stored value, and you *know* when it's not exact.
+
+### Key Properties
+
+- **Faithful rounding**: every result is within 1 ULP of the true value, with ubit indicating exactness
+- **Gradual underflow**: subnormal numbers for smooth transition to zero
+- **Gradual overflow**: values beyond maxpos mapped with ubit=1
+- **No rounding modes**: the ubit replaces the complexity of IEEE rounding modes
+- **Configurable precision**: any combination of nbits and es
+
+## How It Works
+
+When an arithmetic operation produces a result that is exactly representable, the result is stored with ubit=0. When the result falls between two consecutive representable values, the lower value is stored with ubit=1, indicating "the true value is between here and the next encoding." This is simpler than IEEE rounding modes and provides strictly more information: you always know whether the result was exact.
+
+The overflow behavior is also graceful: instead of jumping to infinity, an areal beyond maxpos is stored as maxpos with ubit=1, meaning "the true value is somewhere above maxpos." Similarly, underflow toward zero sets the ubit to indicate imprecision near the bottom of the range.
+
+## How to Use It
+
+### Include
+
+```cpp
+#include <universal/number/areal/areal.hpp>
+using namespace sw::universal;
+```
+
+### Basic Usage
+
+```cpp
+areal<8, 2> a(1.0f);    // Exact: ubit = 0
+areal<8, 2> b(0.1f);    // Not exactly representable: ubit = 1
+
+auto c = a + b;
+std::cout << to_binary(c) << " = " << c << std::endl;
+// The ubit tells you whether this result is exact
+```
+
+### Verified Computation
+
+```cpp
+template<typename Real>
+bool is_result_exact(Real a, Real b) {
+    Real result = a * b;
+    // Check the uncertainty bit to verify exactness
+    return !result.test(0);  // ubit is bit 0
+}
+
+areal<16, 5> x(2.0f), y(3.0f);
+// 2.0 * 3.0 = 6.0, which is exactly representable
+assert(is_result_exact(x, y));
+
+areal<16, 5> p(1.0f), q(3.0f);
+// 1.0 / 3.0 is not exactly representable
+// The result will have ubit = 1
+```
+
+### Tracking Precision Loss
+
+```cpp
+// Count how many operations in a chain produce inexact results
+template<typename Real>
+size_t count_roundings(const std::vector<Real>& values) {
+    size_t inexact_count = 0;
+    Real sum(0);
+    for (const auto& v : values) {
+        sum += v;
+        if (sum.test(0)) ++inexact_count;  // ubit set means rounding occurred
+    }
+    return inexact_count;
+}
+```
+
+## Problems It Solves
+
+| Problem | How areal Solves It |
+|---------|-----------------------|
+| No way to know if a floating-point result was rounded | Uncertainty bit explicitly marks inexact results |
+| IEEE rounding modes are complex and rarely used correctly | Single ubit replaces all rounding mode logic |
+| Overflow jumps to infinity, destroying information | Gradual overflow with ubit=1 preserves "above maxpos" |
+| Underflow flushes to zero prematurely | Gradual underflow with subnormals + ubit |
+| Validated numerics requires expensive interval arithmetic | Single extra bit provides faithful bounds |
+| Reproducibility debates about rounding mode choices | Ubit is deterministic: no mode selection needed |