feat!: expose exact determinant value (det_exact, det_exact_f64)

- Add `det_exact()` returning `BigRational` via Bareiss elimination
- Add `det_exact_f64()` converting exact result to f64
- Add `LaError::Overflow` for f64 conversion overflow
- Add `#[non_exhaustive]` to `LaError` for future extensibility
- Add shared `validate_finite()` helper; refactor `det_sign_exact()`
- Add `exact_det_3x3` example
- Macro-generate exact tests for D=2..5
- Update README, AGENTS.md, REFERENCES.md, typos.toml

BREAKING CHANGE: `LaError` is now `#[non_exhaustive]` and has a new
`Overflow` variant. Exhaustive matches on `LaError` must add a wildcard arm.

Author: acgetchell

AGENTS.md

@@ -56,6 +56,51 @@ When user requests commit message generation:
   take references (`&T`, `&mut T`, `&[T]`) as arguments and return borrowed views (`&T`, `&[T]`) when possible.
   Only take ownership or return `Vec`/allocated data when required.
 
+### Dimension Coverage (2D–5D)
+
+This library uses `const`-generic dimensions. Tests for dimension-generic code
+**must cover D=2 through D=5** whenever possible.
+
+#### Use macros for per-dimension test generation
+
+Define a macro that accepts a dimension literal and generates the full set
+of test functions for that dimension. Invoke it once per dimension:
+
+```rust
+macro_rules! gen_tests {
+    ($d:literal) => {
+        paste! {
+            #[test]
+            fn [<test_foo_ $d d>]() {
+                // assertions …
+            }
+        }
+    };
+}
+
+gen_tests!(2);
+gen_tests!(3);
+gen_tests!(4);
+gen_tests!(5);
+```
+
+#### Keep core logic in generic helper functions
+
+The macro body should be thin — primarily calling `const`-generic helpers and
+asserting results. This keeps the macro readable and the helpers independently
+testable.
+
+#### Reference examples
+
+- `src/matrix.rs` — `gen_public_api_matrix_tests!`
+- `src/exact.rs` — `gen_det_exact_tests!`, `gen_det_exact_f64_tests!`
+
+#### When single-dimension tests are acceptable
+
+Some tests are inherently dimension-specific (e.g. known values for a crafted
+matrix, error-handling with a specific layout). These do not need
+macro-ification.
+
 ### Python
 
 - Use `uv run` for all Python scripts (never `python3` or `python` directly)
@@ -98,7 +143,8 @@ just examples         # Run all examples
 - Run a single test (by name filter): `cargo test solve_2x2_basic` (or the full path: `cargo test lu::tests::solve_2x2_basic`)
 - Run exact-feature tests: `cargo test --features exact --verbose` (or `just test-exact`)
 - Run examples: `just examples` (or `cargo run --example det_5x5` / `cargo run --example solve_5x5` /
-  `cargo run --example const_det_4x4` / `cargo run --features exact --example exact_sign_3x3`)
+  `cargo run --example const_det_4x4` / `cargo run --features exact --example exact_det_3x3` /
+  `cargo run --features exact --example exact_sign_3x3`)
 - Spell check: `just spell-check` (uses `typos.toml` at repo root; add false positives to `[default.extend-words]`)
 
 ### Changelog
@@ -127,8 +173,10 @@ When creating or updating issues:
 
 ## Feature flags
 
-- `exact` — enables `det_sign_exact()` (adaptive-precision determinant sign via `BigRational`).
-  Gates `src/exact.rs`, additional tests, and the `exact_sign_3x3` example.
+- `exact` — enables exact determinant methods via `BigRational` arithmetic:
+  `det_exact()`, `det_exact_f64()`, and `det_sign_exact()`.
+  Also re-exports `BigRational` from the crate root and prelude.
+  Gates `src/exact.rs`, additional tests, and the `exact_det_3x3`/`exact_sign_3x3` examples.
   Clippy, doc builds, and test commands have dedicated `--features exact` variants.
 
 ## Code structure (big picture)
@@ -140,8 +188,9 @@ When creating or updating issues:
   - `src/matrix.rs`: `Matrix<const D: usize>` (`[[f64; D]; D]`) + helpers (`get`, `set`, `inf_norm`, `det`, `det_direct`)
   - `src/lu.rs`: `Lu<const D: usize>` factorization with partial pivoting (`solve_vec`, `det`)
   - `src/ldlt.rs`: `Ldlt<const D: usize>` factorization without pivoting for symmetric SPD/PSD matrices (`solve_vec`, `det`)
-  - `src/exact.rs`: `det_sign_exact()` — adaptive-precision determinant sign
-    (Shewchuk-style f64 filter + Bareiss in `BigRational`); `features = ["exact"]`
+  - `src/exact.rs`: `det_exact()`, `det_exact_f64()`, `det_sign_exact()` — exact determinant
+    value and sign via Bareiss in `BigRational`; `det_sign_exact()` adds a Shewchuk-style f64
+    filter for fast sign resolution; `features = ["exact"]`
 - Rust tests are inline `#[cfg(test)]` modules in each `src/*.rs` file.
 - Python tests live in `scripts/tests/` and run via `just test-python` (`uv run pytest`).
 - The public API re-exports these items from `src/lib.rs`.

CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- Expose exact determinant value (det_exact, det_exact_f64) [`b1a676c`](https://github.com/acgetchell/la-stack/commit/b1a676c8bd8fde98eb9915a9d2e528f1225f46bf)
+
 ## [0.2.2] - 2026-03-11
 
 ### Added
@@ -16,6 +22,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Bump actions/setup-node from 6.2.0 to 6.3.0 [`0f2fc34`](https://github.com/acgetchell/la-stack/commit/0f2fc348b06d72476610821c77945c265207ad05)
 - Bump taiki-e/install-action from 2.68.20 to 2.68.22 [`c3e49bd`](https://github.com/acgetchell/la-stack/commit/c3e49bdd75e3ca26117942da243dac1ee59eb7a1)
+- Release v0.2.2 [`432c7fe`](https://github.com/acgetchell/la-stack/commit/432c7fefea1039f85f4052ab4d12174ae7c2a69b)
 
 ## [0.2.1] - 2026-03-08
 
@@ -166,6 +173,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Add tarpaulin coverage upload [`7486dfd`](https://github.com/acgetchell/la-stack/commit/7486dfd54e16a6dbde41575c3f35a1acb65f57d2)
 
+[unreleased]: https://github.com/acgetchell/la-stack/compare/v0.2.2..HEAD
 [0.2.2]: https://github.com/acgetchell/la-stack/compare/v0.2.1..v0.2.2
 [0.2.1]: https://github.com/acgetchell/la-stack/compare/v0.2.0..v0.2.1
 [0.2.0]: https://github.com/acgetchell/la-stack/compare/v0.1.3..v0.2.0

Cargo.lock

@@ -19,6 +19,7 @@ faer = { version = "0.24.0", default-features = false, features = [ "std", "lina
 nalgebra = { version = "0.34.1", optional = true }
 num-bigint = { version = "0.4.6", optional = true }
 num-rational = { version = "0.4.2", features = [ "num-bigint-std" ], optional = true }
+num-traits = { version = "0.2.19", optional = true }
 
 [dev-dependencies]
 approx = "0.5.1"
@@ -28,7 +29,11 @@ proptest = "1.10.0"
 [features]
 default = [  ]
 bench = [ "criterion", "faer", "nalgebra" ]
-exact = [ "num-bigint", "num-rational" ]
+exact = [ "num-bigint", "num-rational", "num-traits" ]
+
+[[example]]
+name = "exact_det_3x3"
+required-features = [ "exact" ]
 
 [[example]]
 name = "exact_sign_3x3"

Cargo.toml

@@ -133,18 +133,22 @@ assert_eq!(DET, Some(30.0));
 The public `det()` method automatically dispatches through the closed-form path
 for D ≤ 4 and falls back to LU for D ≥ 5 — no API change needed.
 
-## 🔬 Exact determinant sign (`"exact"` feature)
+## 🔬 Exact arithmetic (`"exact"` feature)
 
 The default build has **zero runtime dependencies**.  Enable the optional
-`exact` Cargo feature to add `det_sign_exact()`, which returns the provably
-correct sign (−1, 0, or +1) of the determinant using adaptive-precision
-arithmetic (this pulls in `num-bigint` and `num-rational` for `BigRational`):
+`exact` Cargo feature to add exact determinant methods using adaptive-precision
+arithmetic (this pulls in `num-bigint`, `num-rational`, and `num-traits` for
+`BigRational`):
 
 ```toml
 [dependencies]
 la-stack = { version = "0.2.2", features = ["exact"] }
 ```
 
+- **`det_exact()`** — returns the exact determinant as a `BigRational`
+- **`det_exact_f64()`** — returns the exact determinant converted to the nearest `f64`
+- **`det_sign_exact()`** — returns the provably correct sign (−1, 0, or +1)
+
 ```rust,ignore
 use la_stack::prelude::*;
 
@@ -154,11 +158,17 @@ let m = Matrix::<3>::from_rows([
     [7.0, 8.0, 9.0],
 ]);
 assert_eq!(m.det_sign_exact().unwrap(), 0); // exactly singular
+
+let det = m.det_exact().unwrap();
+assert_eq!(det, BigRational::from_integer(0.into())); // exact zero
 ```
 
-For D ≤ 4, a fast f64 filter (error-bounded `det_direct()`) resolves the sign
-without allocating.  Only near-degenerate or large (D ≥ 5) matrices fall through
-to the exact Bareiss algorithm in `BigRational`.
+`BigRational` is re-exported from the crate root and prelude when the `exact`
+feature is enabled, so consumers don't need to depend on `num-rational` directly.
+
+For `det_sign_exact()`, D ≤ 4 matrices use a fast f64 filter (error-bounded
+`det_direct()`) that resolves the sign without allocating.  Only near-degenerate
+or large (D ≥ 5) matrices fall through to the exact Bareiss algorithm.
 
 ### Adaptive precision with `det_errbound()`
 
@@ -194,7 +204,7 @@ exposed for advanced use cases.
 | Type | Storage | Purpose | Key methods |
 |---|---|---|---|
 | `Vector<D>` | `[f64; D]` | Fixed-length vector | `new`, `zero`, `dot`, `norm2_sq` |
-| `Matrix<D>` | `[[f64; D]; D]` | Square matrix | `from_rows`, `zero`, `identity`, `lu`, `ldlt`, `det`, `det_direct`, `det_errbound`, `det_sign_exact`¹ |
+| `Matrix<D>` | `[[f64; D]; D]` | Square matrix | `lu`, `ldlt`, `det`, `det_direct`, `det_errbound`, `det_exact`¹, `det_exact_f64`¹, `det_sign_exact`¹ |
 | `Lu<D>` | `Matrix<D>` + pivot array | Factorization for solves/det | `solve_vec`, `det` |
 | `Ldlt<D>` | `Matrix<D>` | Factorization for symmetric SPD/PSD solves/det | `solve_vec`, `det` |
 
@@ -209,6 +219,7 @@ The `examples/` directory contains small, runnable programs:
 - **`solve_5x5`** — solve a 5×5 system via LU with partial pivoting
 - **`det_5x5`** — determinant of a 5×5 matrix via LU
 - **`const_det_4x4`** — compile-time 4×4 determinant via `det_direct()`
+- **`exact_det_3x3`** — exact determinant value of a near-singular 3×3 matrix (requires `exact` feature)
 - **`exact_sign_3x3`** — exact determinant sign of a near-singular 3×3 matrix (requires `exact` feature)
 
 ```bash
@@ -217,6 +228,7 @@ just examples
 cargo run --example solve_5x5
 cargo run --example det_5x5
 cargo run --example const_det_4x4
+cargo run --features exact --example exact_det_3x3
 cargo run --features exact --example exact_sign_3x3
 ```
 

README.md

@@ -59,7 +59,7 @@ elimination [7] in `BigRational`. See `src/exact.rs` for the full architecture d
    *Numerische Mathematik* 27 (1976/1977): 95–110.
    [Full text](https://eudml.org/doc/132435)
 
-### Exact determinant sign (`det_sign_exact`)
+### Exact determinant (`det_exact`, `det_exact_f64`, `det_sign_exact`)
 
 7. Bareiss, Erwin H. "Sylvester's Identity and Multistep Integer-Preserving Gaussian
    Elimination." *Mathematics of Computation* 22.103 (1968): 565–578.

REFERENCES.md

@@ -0,0 +1,48 @@
+//! Exact determinant value for a near-singular 3×3 matrix.
+//!
+//! This example demonstrates `det_exact()` and `det_exact_f64()`, which use
+//! arbitrary-precision rational arithmetic to compute the provably correct
+//! determinant value — even when the matrix is so close to singular that f64
+//! rounding could lose significant digits.
+//!
+//! Run with: `cargo run --features exact --example exact_det_3x3`
+
+use la_stack::prelude::*;
+
+fn main() {
+    // Base matrix: rows in arithmetic progression → exactly singular (det = 0).
+    //   [[1, 2, 3],
+    //    [4, 5, 6],
+    //    [7, 8, 9]]
+    //
+    // Perturb entry (0,0) by 2^-50 ≈ 8.9e-16.
+    // Exact det = 2^-50 × cofactor(0,0) = 2^-50 × (5×9 − 6×8) = −3 × 2^-50.
+    let perturbation = f64::from_bits(0x3CD0_0000_0000_0000); // 2^-50
+    let m = Matrix::<3>::from_rows([
+        [1.0 + perturbation, 2.0, 3.0],
+        [4.0, 5.0, 6.0],
+        [7.0, 8.0, 9.0],
+    ]);
+
+    let det_f64_approx = m.det_direct().unwrap();
+    let det_exact = m.det_exact().unwrap();
+    let det_exact_as_f64 = m.det_exact_f64().unwrap();
+
+    println!("Near-singular 3×3 matrix (perturbation = 2^-50 ≈ {perturbation:.2e}):");
+    for r in 0..3 {
+        print!("  [");
+        for c in 0..3 {
+            if c > 0 {
+                print!(", ");
+            }
+            print!("{:22.18}", m.get(r, c).unwrap());
+        }
+        println!("]");
+    }
+    println!();
+    println!("f64 det_direct()   = {det_f64_approx:+.6e}");
+    println!("det_exact()        = {det_exact}");
+    println!("det_exact_f64()    = {det_exact_as_f64:+.6e}");
+    println!();
+    println!("The exact determinant is −3/2^50 ≈ −2.66e-15.");
+}