fix: correct interval bounds and support mutable dispatch captures

[acgetchell]

• Use magnitude-ordered FastTwoSum to avoid spurious non-finite errors in interval addition and subtraction near f64::MAX.
• Allow dimension-dispatch macro bodies to mutate captures while preserving support for consuming closures.
• Skip redundant GCD work when clearing rational denominators.
• Clarify numerical certificates, error provenance, and mutation guarantees in API documentation.
• Sort README API entries and document the existing Gram benchmark suite.

Summary by CodeRabbit

• Documentation

  • Clarified certified arithmetic, interval rounding, determinant error bounds, exact conversions, and supported dimensions.
  • Improved API examples and benchmarking guidance, including Gram matrix benchmarks.

• Bug Fixes

  • Improved numerical reliability for interval operations, certified reductions, determinant bounds, and extreme-value arithmetic.
  • Added clearer handling and validation of exact and floating-point solve results.

• Tests

  • Expanded coverage for determinants, solves, vector operations, interval behavior, dispatch macros, and matrix mutation.
  • Added regression tests for overflow, signed zero, rounding, and outward bounds.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Essentials

Run ID: ed7da048-6407-44f3-ad8f-0774a18a9e3a

📥 Commits

Reviewing files that changed from the base of the PR and between 3e0719f and 3fb215b.

📒 Files selected for processing (34)

• AGENTS.md
• Cargo.toml
• README.md
• REFERENCES.md
• benches/common/rational.rs
• benches/common/vs_linalg.rs
• docs/BENCHMARKING.md
• docs/mathematical_basis.md
• examples/const_det_4x4.rs
• examples/det_5x5.rs
• examples/exact_det_3x3.rs
• examples/exact_sign_3x3.rs
• examples/exact_solve_3x3.rs
• examples/ldlt_solve_3x3.rs
• examples/rational_input_5x5.rs
• examples/solve_5x5.rs
• src/error.rs
• src/exact.rs
• src/interval.rs
• src/lib.rs
• src/lu.rs
• src/matrix.rs
• src/rational.rs
• src/rounding.rs
• src/scaled_product.rs
• src/tolerance.rs
• src/vector.rs
• tests/exact_conversion_boundaries.rs
• tests/prelude_exports.rs
• tests/proptest_interval.rs
• tests/proptest_matrix.rs
• tests/proptest_rational.rs
• tests/proptest_vector.rs
• tests/regressions.rs

Included review availability: 2 reviews are currently available. Your included PR review attempts over the past 7 days set your current allowance at 3 reviews per hour.

---

📝 Walkthrough

Walkthrough

The changes refine floating-point residuals and interval bounds, expand exact arithmetic and dispatch contract tests, strengthen executable examples, and update numerical documentation, benchmarks, and validation guidance.

Changes

Numerical contracts and validation

Layer / File(s)	Summary
Rounding, interval, and vector behavior src/rounding.rs, src/interval.rs, src/vector.rs, tests/proptest_interval.rs, tests/regressions.rs	Magnitude-ordered FastTwoSum, outward bounds, certification loss, overflow handling, and interval examples receive updated behavior and tests.
Determinant error bounds src/matrix.rs	Documentation and tests cover optional bounds, non-finite errors, underflow-sensitive results, and matrix dimensions.

API and exact arithmetic

Layer / File(s)	Summary
Dispatch closure contracts src/lib.rs, tests/prelude_exports.rs	Dispatch macros now support mutable or consuming closures and skip closures for unsupported dimensions.
Exact decomposition and rational operations src/exact.rs, src/rational.rs, tests/proptest_rational.rs, Cargo.toml	Exact tests use proven-finite decomposition and an independent rational oracle. Rational documentation and denominator handling were expanded.

Examples and project support

Layer / File(s)	Summary
Executable numerical examples examples/*	Examples now assert determinant values, exact solutions, conversion bits, approximate results, signs, and structured errors.
Property tests and supporting cleanup tests/*, benches/common/*, src/lu.rs, src/tolerance.rs	Property coverage was expanded, while equivalent imports and structured assertions were simplified.
Documentation and benchmark guidance AGENTS.md, README.md, REFERENCES.md, docs/BENCHMARKING.md	Validation guidance, API ordering, numerical references, and benchmark-suite documentation were updated.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Merge Risk: ⚪ Minimal · up to 3fb21

This change improves extreme interval arithmetic, mutable dispatch captures, rational-operation efficiency, and validation coverage without any identified current-head merge blocker.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely identifies two primary changes: correcting interval bounds and supporting mutable dispatch captures.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/v0.4.6-pre-release

---

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.02%. Comparing base (3e0719f) to head (3fb215b).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #244      +/-   ##
==========================================
- Coverage   98.04%   98.02%   -0.03%     
==========================================
  Files          13       13              
  Lines        6694     6726      +32     
==========================================
+ Hits         6563     6593      +30     
- Misses        131      133       +2     

Flag	Coverage Δ
unittests	98.02% <100.00%> (-0.03%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.