feat!(api): make Matrix and Vector finite by construction

- Parse raw matrix and vector storage through Matrix::try_from_rows and
  Vector::try_new, with private storage carrying the finite-entry invariant
  through downstream kernels.
- Rename LU and LDLT solves to solve, and remove compatibility aliases that
  weaken the finite-proof API model.
- Add Semgrep guardrails for the finite API contract and public-documentation
  unwrap/expect usage.
- Update benchmarks, examples, docs, and tooling pins for the new API and
  current Markdown/spelling lint behavior.

BREAKING CHANGE: Matrix::from_rows is no longer a public raw constructor; use
Matrix::try_from_rows for raw row-major input.

BREAKING CHANGE: Vector::new is no longer a public raw constructor; use
Vector::try_new for raw vector input.

BREAKING CHANGE: Lu::solve_vec and Ldlt::solve_vec are removed; use solve.

BREAKING CHANGE: DEFAULT_PIVOT_TOL is removed; use DEFAULT_SINGULAR_TOL.

Closes #137

Author: acgetchell

.github/workflows/ci.yml

@@ -27,9 +27,9 @@ env:
   CARGO_NEXTEST_VERSION: "0.9.137"
   DPRINT_VERSION: "0.54.0"
   JUST_VERSION: "1.51.0"
-  RUMDL_VERSION: "0.2.6"
+  RUMDL_VERSION: "0.2.9"
   TAPLO_VERSION: "0.10.0"
-  TYPOS_VERSION: "1.47.1"
+  TYPOS_VERSION: "1.47.2"
   UV_VERSION: "0.11.19"
   ZIZMOR_VERSION: "1.25.2"
 

AGENTS.md

@@ -36,11 +36,12 @@ invariant over the convenient edit.
 
 - Error enums are `#[non_exhaustive]`; public wrapper types are
   `#[must_use]`.
-- New functionality is additive: use the prelude for ergonomic re-exports;
-  never silently rename or remove a public item.
-- Pre-1.0 semver: `0.x.Y` is a patch-level additive bump, `0.X.y` is a
-  minor bump that may include breaking changes. Conventional-commit
-  types (`feat`, `fix`, `refactor`, …) mirror this convention.
+- New functionality is additive by default: use the prelude for ergonomic
+  re-exports, and avoid churn for its own sake.
+- Pre-1.0 semver: any `0.x.y` release may include breaking API changes when
+  they materially improve correctness, orthogonality, or long-term API clarity.
+  Do not keep compatibility aliases that weaken the public model; document
+  intentional breaks clearly in release notes and commit messages.
 - Do **not** automatically update the library version in `Cargo.toml`,
   `Cargo.lock`, README dependency snippets, or related docs during ordinary
   feature, fix, review, or hygiene work. Version bumps are maintainer-driven
@@ -68,7 +69,7 @@ invariant over the convenient edit.
   `Option` instead of relying on `panic!`, `assert!`, `unwrap`, or `expect`.
 - Borrow by default (`&T`, `&[T]`); return borrowed views when possible.
 - Type and function names match textbook vocabulary (`Matrix`, `Vector`,
-  `Lu`, `Ldlt`, `solve_vec`, `det`, `inf_norm`). Avoid Rust-ecosystem
+  `Lu`, `Ldlt`, `solve`, `det`, `inf_norm`). Avoid Rust-ecosystem
   abstractions that obscure the math.
 
 ### Scientific notation in docs
@@ -210,7 +211,7 @@ testable.
 #### Reference examples
 
 - `src/matrix.rs` — `gen_public_api_matrix_tests!`
-- `src/lu.rs` — `gen_public_api_pivoting_solve_vec_and_det_tests!`, `gen_public_api_tridiagonal_smoke_solve_vec_and_det_tests!`
+- `src/lu.rs` — `gen_public_api_pivoting_solve_and_det_tests!`, `gen_public_api_tridiagonal_smoke_solve_and_det_tests!`
 - `src/ldlt.rs` — `gen_public_api_ldlt_identity_tests!`, `gen_public_api_ldlt_diagonal_tests!`
 - `src/exact.rs` — `gen_det_exact_tests!`, `gen_det_exact_f64_tests!`, `gen_solve_exact_tests!`, `gen_solve_exact_f64_tests!`
 
@@ -354,11 +355,11 @@ When creating or updating issues:
 
 - This is a single Rust *library crate* (no `src/main.rs`). The crate root is `src/lib.rs`.
 - The linear algebra implementation is split across:
-  - `src/lib.rs`: crate root + shared items (`LaError`, `DEFAULT_SINGULAR_TOL`, `DEFAULT_PIVOT_TOL`) + re-exports
+  - `src/lib.rs`: crate root + shared items (`LaError`, `DEFAULT_SINGULAR_TOL`) + re-exports
   - `src/vector.rs`: `Vector<const D: usize>` (`[f64; D]`)
   - `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/lu.rs`: `Lu<const D: usize>` factorization with partial pivoting (`solve`, `det`)
+  - `src/ldlt.rs`: `Ldlt<const D: usize>` factorization without pivoting for symmetric SPD/PSD matrices (`solve`, `det`)
   - `src/exact.rs`: exact arithmetic behind `features = ["exact"]`:
     - Determinants: `det_exact()`, `det_exact_f64()`, `det_sign_exact()` via integer-only
       Bareiss in `BigInt` (`bareiss_det_int`); `det_sign_exact()` adds a Shewchuk-style

CHANGELOG.md

@@ -105,8 +105,8 @@ fn main() -> Result<(), LaError> {
 
     let b = Vector::<5>::try_new([14.0, 13.0, 12.0, 11.0, 10.0])?;
 
-    let lu = a.lu(DEFAULT_PIVOT_TOL)?;
-    let x = lu.solve_vec(b)?.into_array();
+    let lu = a.lu(DEFAULT_SINGULAR_TOL)?;
+    let x = lu.solve(b)?.into_array();
 
     // Floating-point rounding is expected; compare with a tolerance.
     let expected = [1.0, 2.0, 3.0, 4.0, 5.0];
@@ -330,18 +330,18 @@ compose the same bound themselves.
 
 | Type | Storage | Purpose | Key methods |
 |---|---|---|---|
-| `Vector<D>` | `[f64; D]` | Fixed-length vector for input and computation | `try_new`, `zero`, `dot`, `norm2_sq` |
-| `Matrix<D>` | `[[f64; D]; D]` | Square matrix for input and computation | See below |
-| `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` |
+| `Vector<D>` | `[f64; D]` | Finite fixed-length vector for input and computation | `try_new`, `zero`, `dot`, `norm2_sq` |
+| `Matrix<D>` | `[[f64; D]; D]` | Finite square matrix for input and computation | See below |
+| `Lu<D>` | `Matrix<D>` + pivot array | Factorization for solves/det | `solve`, `det` |
+| `Ldlt<D>` | `Matrix<D>` | Factorization for symmetric SPD/PSD solves/det | `solve`, `det` |
 
 Storage shown above reflects the intentional `f64` scalar model.
 
 `Matrix<D>` key methods: `lu`, `ldlt`, `det`, `det_direct`, `det_errbound`,
 `det_exact`¹, `det_exact_f64`¹, `det_sign_exact`¹, `solve_exact`¹, `solve_exact_f64`¹.
-Matrix and vector methods validate non-finite inputs at public API boundaries and
-carry private proof-bearing types through computation so successful factors do
-not store NaN or infinity.
+Matrix and vector constructors validate non-finite inputs at public API
+boundaries. After construction, `Matrix<D>` and `Vector<D>` carry that
+finite-storage invariant directly, so kernels do not revalidate stored entries.
 
 ¹ Requires `features = ["exact"]`.
 

README.md

@@ -16,7 +16,7 @@ use faer::{Mat, Side};
 use nalgebra::{SMatrix, SVector};
 use pastey::paste;
 
-use la_stack::{DEFAULT_PIVOT_TOL, DEFAULT_SINGULAR_TOL, Matrix, Vector};
+use la_stack::{DEFAULT_SINGULAR_TOL, Matrix, Vector};
 
 mod common {
     pub mod vs_linalg;
@@ -63,7 +63,6 @@ macro_rules! define_vs_linalg_benches_for_dim {
                     Vector::<$d>::try_new(make_vector_array::<$d>(1.0)),
                     "la_stack vector construction",
                 );
-
                 let na = SMatrix::<f64, $d, $d>::from_fn(|r, c| matrix_entry::<$d>(r, c));
                 let nrhs = SVector::<f64, $d>::from_fn(|i, _| vector_entry(i, 0.0));
                 let nv1 = SVector::<f64, $d>::from_fn(|i, _| vector_entry(i, 0.0));
@@ -75,7 +74,7 @@ macro_rules! define_vs_linalg_benches_for_dim {
                 let fv2 = Mat::<f64>::from_fn($d, 1, |i, _| vector_entry(i, 1.0));
 
                 // Precompute LU once for solve-only / det-only benchmarks.
-                let a_lu = require_ok(a.lu(DEFAULT_PIVOT_TOL), "precomputed la_stack LU");
+                let a_lu = require_ok(a.lu(DEFAULT_SINGULAR_TOL), "precomputed la_stack LU");
                 let a_ldlt = require_ok(a.ldlt(DEFAULT_SINGULAR_TOL), "precomputed la_stack LDLT");
                 let na_lu = na.clone().lu();
                 let na_cholesky = require_some(na.clone().cholesky(), "precomputed nalgebra Cholesky");
@@ -88,7 +87,7 @@ macro_rules! define_vs_linalg_benches_for_dim {
                 [<group_d $d>].bench_function("la_stack_det_via_lu", |bencher| {
                     bencher.iter(|| {
                         let lu = require_ok(
-                            black_box(a).lu(DEFAULT_PIVOT_TOL),
+                            black_box(a).lu(DEFAULT_SINGULAR_TOL),
                             "la_stack LU factorization",
                         );
                         let det = require_ok(lu.det(), "la_stack LU determinant");
@@ -124,7 +123,7 @@ macro_rules! define_vs_linalg_benches_for_dim {
                 [<group_d $d>].bench_function("la_stack_lu", |bencher| {
                     bencher.iter(|| {
                         let lu = require_ok(
-                            black_box(a).lu(DEFAULT_PIVOT_TOL),
+                            black_box(a).lu(DEFAULT_SINGULAR_TOL),
                             "la_stack LU factorization",
                         );
                         let _ = black_box(lu);
@@ -180,11 +179,11 @@ macro_rules! define_vs_linalg_benches_for_dim {
                 [<group_d $d>].bench_function("la_stack_lu_solve", |bencher| {
                     bencher.iter(|| {
                         let lu = require_ok(
-                            black_box(a).lu(DEFAULT_PIVOT_TOL),
+                            black_box(a).lu(DEFAULT_SINGULAR_TOL),
                             "la_stack LU factorization",
                         );
                         let x = require_ok(
-                            lu.solve_vec(black_box(rhs)),
+                            lu.solve(black_box(rhs)),
                             "la_stack LU solve",
                         );
                         let _ = black_box(x);
@@ -215,7 +214,7 @@ macro_rules! define_vs_linalg_benches_for_dim {
                             "la_stack LDLT factorization",
                         );
                         let x = require_ok(
-                            ldlt.solve_vec(black_box(rhs)),
+                            ldlt.solve(black_box(rhs)),
                             "la_stack LDLT solve",
                         );
                         let _ = black_box(x);
@@ -248,7 +247,7 @@ macro_rules! define_vs_linalg_benches_for_dim {
                 [<group_d $d>].bench_function("la_stack_solve_from_lu", |bencher| {
                     bencher.iter(|| {
                         let x = require_ok(
-                            a_lu.solve_vec(black_box(rhs)),
+                            a_lu.solve(black_box(rhs)),
                             "precomputed la_stack LU solve",
                         );
                         let _ = black_box(x);
@@ -276,7 +275,7 @@ macro_rules! define_vs_linalg_benches_for_dim {
                 [<group_d $d>].bench_function("la_stack_solve_from_ldlt", |bencher| {
                     bencher.iter(|| {
                         let x = require_ok(
-                            a_ldlt.solve_vec(black_box(rhs)),
+                            a_ldlt.solve(black_box(rhs)),
                             "precomputed la_stack LDLT solve",
                         );
                         let _ = black_box(x);

benches/vs_linalg.rs

@@ -58,12 +58,9 @@ API-invariant cleanup:
 
 - [#126](https://github.com/acgetchell/la-stack/issues/126) is resolved as an
   internal parse-don't-validate design rather than a public proof-bearing API.
-  `Matrix<D>` and `Vector<D>` remain the raw boundary types so callers can pass
-  deserialized, fixture, or otherwise unchecked `f64` storage and receive
-  structured diagnostics. Crate-private `FiniteMatrix<D>` and
-  `FiniteVector<D>` are validated domain types that carry the finite-entry proof
-  behind the scenes for LU, LDLT, determinant, error-bound, and exact-arithmetic
-  paths.
+  `Matrix<D>` and `Vector<D>` parse raw `f64` storage at construction and then
+  carry the finite-entry proof directly. Crate-private finite wrappers remain
+  only as implementation helpers at algorithm boundaries.
 - The public prelude stays focused on downstream composition: raw boundary
   types, factorization handles, tolerances, crate errors, dispatch helpers, and
   documented constants. Proof-bearing wrappers remain crate-private, and

docs/roadmap.md

@@ -14,7 +14,7 @@ fn main() -> Result<(), LaError> {
     ])?;
 
     // Compute via explicit LU factorization.
-    let lu = a.lu(DEFAULT_PIVOT_TOL)?;
+    let lu = a.lu(DEFAULT_SINGULAR_TOL)?;
     let det = lu.det()?;
 
     println!("det = {det}");

examples/det_5x5.rs

@@ -25,8 +25,8 @@ fn main() -> Result<(), LaError> {
     let b = Vector::<3>::try_new([1.0, 2.0, 3.0])?;
 
     // f64 LU solve (using zero pivot tolerance since the matrix is nearly singular
-    // and would be rejected by DEFAULT_PIVOT_TOL).
-    let lu_x = a.lu(Tolerance::new(0.0)?)?.solve_vec(b)?.into_array();
+    // and would be rejected by DEFAULT_SINGULAR_TOL).
+    let lu_x = a.lu(Tolerance::new(0.0)?)?.solve(b)?.into_array();
 
     // Exact solve.
     let exact_x = a.solve_exact(b)?;

examples/exact_solve_3x3.rs

@@ -16,7 +16,7 @@ fn main() -> Result<(), LaError> {
     let b = Vector::<3>::try_new([2.0, 4.0, 10.0])?;
 
     let ldlt = a.ldlt(DEFAULT_SINGULAR_TOL)?;
-    let x = ldlt.solve_vec(b)?.into_array();
+    let x = ldlt.solve(b)?.into_array();
     let det = ldlt.det()?;
 
     println!("A (3×3 SPD tridiagonal):");

examples/ldlt_solve_3x3.rs

@@ -16,8 +16,8 @@ fn main() -> Result<(), LaError> {
     // Choose x = [1, 2, 3, 4, 5]. Then b = A x = [14, 13, 12, 11, 10].
     let b = Vector::<5>::try_new([14.0, 13.0, 12.0, 11.0, 10.0])?;
 
-    let lu = a.lu(DEFAULT_PIVOT_TOL)?;
-    let x = lu.solve_vec(b)?.into_array();
+    let lu = a.lu(DEFAULT_SINGULAR_TOL)?;
+    let x = lu.solve(b)?.into_array();
 
     println!("x = {x:?}");
     Ok(())