perf(exact): restore small-matrix det_sign_exact throughput

[acgetchell]

• Reuse proof-bearing shared minors for D4 determinant and permanent evaluation.
• Restore the dense D3 filter while preserving sparse, overflow, and underflow fallbacks.
• Require headline benchmarks to exercise the intended filter and document historical harness overhead.

Closes #157

Summary by CodeRabbit

• Performance

  • Improved determinant calculations for dense 3×3 and 4×4 matrices.
  • Reduced unnecessary computation in common determinant and error-bound paths.

• Reliability

  • Improved handling and reporting of legitimate arithmetic overflow during determinant calculations.
  • Strengthened determinant error-bound validation for exact sign results.

• Documentation

  • Clarified benchmark comparisons and the conditions required for meaningful historical performance analysis.

• Tests

  • Added coverage for dense-matrix overflow behavior and stable exact-filter results.

[coderabbitai]

📝 Walkthrough

Walkthrough

D=3 and D=4 determinant fast paths now use streamlined arithmetic and shared-minor proof handling. Error-bound and overflow tests expand coverage, while benchmark assertions and documentation clarify direct-filter behavior and historical comparison methodology.

Changes

Determinant fast paths and benchmark validation

Layer / File(s)	Summary
D4 shared-minor determinant path src/matrix.rs	Adds Det4SharedMinorInput and uses it to route eligible D=4 direct determinant evaluations through shared-minor dense kernels.
Error bounds and overflow validation src/matrix.rs	Refactors D=4 error-bound calculation, streamlines the dense D=3 permanent path, and tests legitimate overflow handling for dense D=3 and D=4 matrices.
Benchmark filter validation tests/exact_bench_config.rs, benches/common/exact.rs, docs/BENCHMARKING.md	Validates direct-filter conclusiveness across benchmark fixtures, asserts certified estimates exceed their error bounds, and documents historical harness differences.

Estimated code review effort: 4 (Complex) | ~45 minutes

Possibly related issues

• Investigate det_direct regressions for D=2..4 #158 — Directly concerns determinant hot paths for D=3–4 and related benchmark and test coverage.

Possibly related PRs

• acgetchell/la-stack#34 — Adds and dispatches closed-form small-dimension det_direct paths touched by these fast-path changes.
• acgetchell/la-stack#45 — Provides related determinant error-bound machinery used by direct sign certification.
• acgetchell/la-stack#178 — Reworks the determinant and error-bound infrastructure modified here.

Suggested labels: documentation, performance, enhancement, testing, api, rust

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is concise and matches the PR's main goal: restoring small-matrix det_sign_exact throughput.
Linked Issues check	✅ Passed	The changes restore throughput, add regression coverage, and update benchmarks/docs in line with issue #157's requirements.
Out of Scope Changes check	✅ Passed	All changes map to the regression fix, tests, and benchmark/documentation work described in the linked issue.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ 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 perf/157-det-sign-exact-regression

---

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

[codecov]

Codecov Report

❌ Patch coverage is 99.33333% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 97.77%. Comparing base (e17a58b) to head (b8bfa9f).
⚠️ Report is 2 commits behind head on main.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
src/matrix.rs	99.33%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #182      +/-   ##
==========================================
- Coverage   97.77%   97.77%   -0.01%     
==========================================
  Files           8        8              
  Lines        4684     4768      +84     
==========================================
+ Hits         4580     4662      +82     
- Misses        104      106       +2     

Flag	Coverage Δ
unittests	97.77% <99.33%> (-0.01%)	⬇️

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.

[coderabbitai]

🧹 Nitpick comments (2)

tests/exact_bench_config.rs (1)

151-162: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Generate per-dimension tests through the required macro.

This test manually repeats the D=2–5 baseline assertions. Use a dimension-literal macro to generate independently named tests while retaining the adversarial fixture checks.

As per coding guidelines, dimension-generic tests must use a macro invoked for D=2, 3, 4, and 5.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/exact_bench_config.rs` around lines 151 - 162, Replace the repeated
baseline assertions in det_sign_exact_benchmark_filter_paths_are_stable with the
required dimension-literal macro, invoking it for dimensions 2, 3, 4, and 5 to
generate independently named tests. Keep the near_singular_3x3_input,
large_entries_3x3_input, and Hilbert fixture assertions in the test coverage.

Source: Coding guidelines

src/matrix.rs (1)

1866-1884: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Add matching det_errbound/det_direct_with_errbound assertions for the new overflow fixtures.

These tests correctly exercise the new dense shared-minor/permanent kernels for det_direct()/det(), but the same matrices would be a good check that det4_dense_abs_permanent_elements / det3_abs_permanent_elements's dense path — the actual bound-computation code changed by this PR — also surfaces NonFinite rather than silently returning an unbounded or incorrect value. Note the expected error differs: det_errbound()/det_direct_with_errbound() classify the failure as ArithmeticOperation::DeterminantErrorBound (checked before the determinant's own finiteness in det_direct_with_errbound_from_arithmetic), not Determinant.

Based on the coding guideline "Unit tests should cover known values, error paths, and dimension-generic correctness across D=2..=5," and since this is precisely the changed critical path, this seems worth the small addition. Happy to draft the two test functions if useful.

🧪 Proposed additional coverage

#[test]
fn det_errbound_d3_dense_reports_legitimate_overflow() {
    let scale = 1.6e102;
    let m = black_box(
        Matrix::<3>::try_from_rows([
            [4.0 * scale, scale, scale],
            [scale, 4.0 * scale, scale],
            [scale, scale, 4.0 * scale],
        ])
        .unwrap(),
    );
    assert_eq!(
        m.det_errbound(),
        Err(LaError::non_finite_computation_scalar(
            ArithmeticOperation::DeterminantErrorBound
        ))
    );
}

#[test]
fn det_errbound_d4_dense_reports_legitimate_overflow() {
    let scale = 3.2e76;
    let m = black_box(
        Matrix::<4>::try_from_rows([
            [4.0 * scale, scale, scale, scale],
            [scale, 4.0 * scale, scale, scale],
            [scale, scale, 4.0 * scale, scale],
            [scale, scale, scale, 4.0 * scale],
        ])
        .unwrap(),
    );
    assert_eq!(
        m.det_errbound(),
        Err(LaError::non_finite_computation_scalar(
            ArithmeticOperation::DeterminantErrorBound
        ))
    );
}

Also applies to: 1938-1957

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/matrix.rs` around lines 1866 - 1884, Add matching overflow tests
alongside det_direct_d3_dense_reports_legitimate_overflow and the corresponding
D4 fixture, asserting both det_errbound() and det_direct_with_errbound() return
non_finite_computation_scalar(ArithmeticOperation::DeterminantErrorBound). Reuse
the existing dense matrices and black_box setup, while preserving the
determinant tests’ expected Determinant error classification.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/matrix.rs`:
- Around line 1866-1884: Add matching overflow tests alongside
det_direct_d3_dense_reports_legitimate_overflow and the corresponding D4
fixture, asserting both det_errbound() and det_direct_with_errbound() return
non_finite_computation_scalar(ArithmeticOperation::DeterminantErrorBound). Reuse
the existing dense matrices and black_box setup, while preserving the
determinant tests’ expected Determinant error classification.

In `@tests/exact_bench_config.rs`:
- Around line 151-162: Replace the repeated baseline assertions in
det_sign_exact_benchmark_filter_paths_are_stable with the required
dimension-literal macro, invoking it for dimensions 2, 3, 4, and 5 to generate
independently named tests. Keep the near_singular_3x3_input,
large_entries_3x3_input, and Hilbert fixture assertions in the test coverage.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: e8780e88-6905-47c4-b533-0d9503903dc8

📥 Commits

Reviewing files that changed from the base of the PR and between e17a58b and b8bfa9f.

📒 Files selected for processing (4)

• benches/common/exact.rs
• docs/BENCHMARKING.md
• src/matrix.rs
• tests/exact_bench_config.rs