feat(api)!: make exact f64 conversions strict

- Make Matrix and Vector the finite-by-construction public types for exact arithmetic.
- Add rounded exact-to-f64 APIs for determinant and solve callers that want explicit lossy conversion.
- Return typed Unrepresentable reasons when strict exact-to-f64 conversion would round or become non-finite.
- Specialize D4 exact determinants and keep determinant/error-bound zero coefficients from evaluating overflowing absent terms.
- Update exact benchmark comparison reporting to compare strict and rounded APIs against legacy v0.4.2 rows.

BREAKING CHANGE: strict exact-to-f64 APIs now return LaError::Unrepresentable instead of silently rounding, public Matrix and Vector construction is fallible, and the previous finite proof wrapper APIs are removed.

Author: acgetchell

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### ⚠️ Breaking Changes
+
+- Make exact f64 conversions strict
+
 ### Added
 
 - Guard README dependency snippets [`7137fee`](https://github.com/acgetchell/la-stack/commit/7137fee16ab33e08f4dc6a60e02417e3e7c4e020)
@@ -32,6 +36,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Keep the regular benchmark workflow focused on PR and main-branch comparison runs.
   - Document how to restore archived release baselines for future performance comparisons.
 - Feat!(api): make Matrix and Vector finite by construction [`1fa2f55`](https://github.com/acgetchell/la-stack/commit/1fa2f55cfac6f249a7e2bf30922901539e580dd8)
+- [**breaking**] Make exact f64 conversions strict [`8e33f1a`](https://github.com/acgetchell/la-stack/commit/8e33f1a8ec291bfcb6312375969efce076421e96)
+  - Add explicit rounded exact-to-f64 APIs for determinant and solve results
+  - Report exact conversion failures with typed Unrepresentable reasons
+  - Remove finite proof wrapper APIs now that Matrix and Vector carry finiteness directly
+  - Move error and tolerance contracts into first-class modules with prelude exports
+  - Update exact benchmarks to distinguish strict Result paths from rounded f64 paths
+  - Document and exercise the rounded fallback pattern for RequiresRounding errors
 
 ### Changed
 

docs/BENCHMARKING.md

@@ -193,6 +193,23 @@ local. The report includes per-dimension tables showing median times,
 percent change, speedup, and last-release nalgebra/faer context where a
 matching `vs_linalg` peer exists.
 
+For exact-arithmetic comparisons against v0.4.2 or older baselines, rows such
+as `det_exact_rounded_f64 (vs det_exact_f64)` mean the current rounded API is
+being compared to the historical lossy `*_exact_f64` benchmark. Rows such as
+`det_exact_f64_result (vs det_exact_f64)` intentionally show the overhead of
+the new strict conversion contract against that same historical baseline.
+
+The default `release-signal` scope reports exact-arithmetic rows whose inputs
+are fixed across versions: deterministic D=2..=5 cases plus adversarial fixed
+matrices. Random percentile groups are exploratory tail probes; each benchmark
+run selects p50/p95/p99 input sets by timing the implementation under test, so
+those rows can measure different corpus subsets across versions. Include them
+when investigating tails with:
+
+```bash
+uv run bench-compare v0.4.2 --suite exact --scope all-benches
+```
+
 To generate a current snapshot without a saved baseline:
 
 ```bash

scripts/bench_compare.py

@@ -43,16 +43,35 @@
 #
 # Mirrors the structure of `benches/exact.rs`: general-case per-dimension
 # groups (`exact_d{2..5}`), fixed-seed random percentile groups, plus
-# adversarial/extreme-input groups that share a fixed four-bench layout
-# (`det_sign_exact`, `det_exact`, `solve_exact`, `solve_exact_f64`).
-_EXTREME_BENCHES: list[str] = ["det_sign_exact", "det_exact", "solve_exact", "solve_exact_f64"]
+# adversarial/extreme-input groups that share a fixed five-bench layout
+# (`det_sign_exact`, `det_exact`, `solve_exact`, `solve_exact_f64_result`,
+# `solve_exact_rounded_f64`).
+_EXTREME_BENCHES: list[str] = [
+    "det_sign_exact",
+    "det_exact",
+    "solve_exact",
+    "solve_exact_f64_result",
+    "solve_exact_rounded_f64",
+]
 _RANDOM_PERCENTILE_BENCHES: list[str] = [f"{operation}_{percentile}" for operation in _EXTREME_BENCHES for percentile in ("p50", "p95", "p99")]
 
+_EXACT_DIMENSION_BENCHES: list[str] = [
+    "det",
+    "det_direct",
+    "det_exact",
+    "det_exact_f64_result",
+    "det_exact_rounded_f64",
+    "det_sign_exact",
+    "solve_exact",
+    "solve_exact_f64_result",
+    "solve_exact_rounded_f64",
+]
+
 EXACT_GROUPS: dict[str, list[str]] = {
-    "exact_d2": ["det", "det_direct", "det_exact", "det_exact_f64", "det_sign_exact", "solve_exact", "solve_exact_f64"],
-    "exact_d3": ["det", "det_direct", "det_exact", "det_exact_f64", "det_sign_exact", "solve_exact", "solve_exact_f64"],
-    "exact_d4": ["det", "det_direct", "det_exact", "det_exact_f64", "det_sign_exact", "solve_exact", "solve_exact_f64"],
-    "exact_d5": ["det", "det_direct", "det_exact", "det_exact_f64", "det_sign_exact", "solve_exact", "solve_exact_f64"],
+    "exact_d2": _EXACT_DIMENSION_BENCHES,
+    "exact_d3": _EXACT_DIMENSION_BENCHES,
+    "exact_d4": _EXACT_DIMENSION_BENCHES,
+    "exact_d5": _EXACT_DIMENSION_BENCHES,
     "exact_random_percentile_d2": _RANDOM_PERCENTILE_BENCHES,
     "exact_random_percentile_d3": _RANDOM_PERCENTILE_BENCHES,
     "exact_random_percentile_d4": _RANDOM_PERCENTILE_BENCHES,
@@ -63,6 +82,25 @@
     "exact_hilbert_5x5": _EXTREME_BENCHES,
 }
 
+EXACT_RELEASE_SIGNAL_GROUPS: frozenset[str] = frozenset(group for group in EXACT_GROUPS if not group.startswith("exact_random_percentile_d"))
+
+# v0.4.2 and earlier named the lossy exact-to-f64 benches after the public
+# `*_exact_f64` API. Current benches split that behavior into strict `*_result`
+# and lossy `*_rounded_f64` variants. Use the old baseline when present so
+# release reports show both compatibility-successor performance and strict
+# conversion overhead instead of silently dropping the new rows.
+EXACT_LEGACY_BASELINE_BENCHES: dict[str, str] = {
+    "det_exact_f64_result": "det_exact_f64",
+    "det_exact_rounded_f64": "det_exact_f64",
+    "solve_exact_f64_result": "solve_exact_f64",
+    "solve_exact_rounded_f64": "solve_exact_f64",
+}
+
+_EXACT_LEGACY_PREFIX_BASELINE_BENCHES: tuple[tuple[str, str], ...] = (
+    ("solve_exact_f64_result_", "solve_exact_f64_"),
+    ("solve_exact_rounded_f64_", "solve_exact_f64_"),
+)
+
 VS_LINALG_LA_STACK_ONLY_BENCHES_BY_METRIC: dict[str, list[str]] = {
     "det_via_lu": ["la_stack_det"],
 }
@@ -123,6 +161,7 @@ class Comparison:
     current_ns: float
     speedup: float  # baseline / current (>1 = faster)
     pct_change: float  # signed percent change (negative = faster)
+    baseline_bench: str | None = None
     baseline_nalgebra_ns: float | None = None
     baseline_faer_ns: float | None = None
 
@@ -231,6 +270,36 @@ def _collect_exact_results(criterion_dir: Path, sample: str, stat: str) -> list[
     return results
 
 
+def _legacy_exact_baseline_bench(bench: str) -> str | None:
+    """Return the legacy exact benchmark name for renamed rows."""
+    legacy_bench = EXACT_LEGACY_BASELINE_BENCHES.get(bench)
+    if legacy_bench is not None:
+        return legacy_bench
+
+    for current_prefix, legacy_prefix in _EXACT_LEGACY_PREFIX_BASELINE_BENCHES:
+        if bench.startswith(current_prefix):
+            return f"{legacy_prefix}{bench.removeprefix(current_prefix)}"
+
+    return None
+
+
+def _exact_baseline_path(group_dir: Path, bench: str, baseline_name: str) -> tuple[str, Path]:
+    """Return the exact benchmark baseline path, falling back to legacy names."""
+    base_path = group_dir / bench / baseline_name / "estimates.json"
+    if base_path.exists():
+        return (bench, base_path)
+
+    legacy_bench = _legacy_exact_baseline_bench(bench)
+    if legacy_bench is None:
+        return (bench, base_path)
+
+    legacy_path = group_dir / legacy_bench / baseline_name / "estimates.json"
+    if legacy_path.exists():
+        return (legacy_bench, legacy_path)
+
+    return (bench, base_path)
+
+
 def _ordered_vs_linalg_benches(group_dir: Path, sample: str) -> list[str]:
     """Return present vs_linalg benches in a stable, metric-aware order."""
     present = {child.name for child in group_dir.iterdir() if child.is_dir() and (child / sample / "estimates.json").exists()}
@@ -275,18 +344,22 @@ def _collect_exact_comparisons(
     criterion_dir: Path,
     baseline_name: str,
     stat: str,
+    scope: str,
 ) -> list[Comparison]:
     """Compare current exact-arithmetic results against a named baseline."""
     comparisons: list[Comparison] = []
 
     for group, benches in EXACT_GROUPS.items():
+        if scope == "release-signal" and group not in EXACT_RELEASE_SIGNAL_GROUPS:
+            continue
+
         group_dir = criterion_dir / group
         if not group_dir.is_dir():
             continue
 
         for bench in benches:
             new_path = group_dir / bench / "new" / "estimates.json"
-            base_path = group_dir / bench / baseline_name / "estimates.json"
+            baseline_bench, base_path = _exact_baseline_path(group_dir, bench, baseline_name)
 
             if not new_path.exists() or not base_path.exists():
                 continue
@@ -306,6 +379,7 @@ def _collect_exact_comparisons(
                     current_ns=new_point,
                     speedup=speedup,
                     pct_change=pct_change,
+                    baseline_bench=baseline_bench if baseline_bench != bench else None,
                 )
             )
 
@@ -346,6 +420,13 @@ def _baseline_peer_times(group_dir: Path, bench: str, baseline_name: str, stat:
     return (nalgebra_ns, faer_ns)
 
 
+def _comparison_bench_label(comparison: Comparison) -> str:
+    """Return the display label for a comparison table row."""
+    if comparison.baseline_bench is None:
+        return comparison.bench
+    return f"{comparison.bench} (vs {comparison.baseline_bench})"
+
+
 def _collect_vs_linalg_comparisons(
     criterion_dir: Path,
     baseline_name: str,
@@ -403,7 +484,7 @@ def _collect_comparisons(
     """Compare current (new) results against a named baseline."""
     comparisons: list[Comparison] = []
     if suite in ("all", "exact"):
-        comparisons.extend(_collect_exact_comparisons(criterion_dir, baseline_name, stat))
+        comparisons.extend(_collect_exact_comparisons(criterion_dir, baseline_name, stat, scope))
     if suite in ("all", "vs_linalg"):
         comparisons.extend(_collect_vs_linalg_comparisons(criterion_dir, baseline_name, stat, scope))
     return comparisons
@@ -542,7 +623,7 @@ def _comparison_tables(comparisons: list[Comparison], baseline_name: str) -> str
                 )
             for c in items:
                 cells = [
-                    c.bench,
+                    _comparison_bench_label(c),
                     _format_time(c.baseline_ns),
                     _format_time(c.current_ns),
                     _format_pct(c.pct_change),

scripts/tests/test_bench_compare.py

@@ -34,12 +34,20 @@ def _build_criterion_tree(criterion_dir: Path, stat: str = "median") -> None:
         group = criterion_dir / f"exact_d{d}"
         _write_estimates(group / "det" / "new" / "estimates.json", stat, det)
         _write_estimates(group / "det_exact" / "new" / "estimates.json", stat, det_exact)
+        _write_estimates(group / "det_exact_f64_result" / "new" / "estimates.json", stat, det_exact * 1.1)
+        _write_estimates(group / "det_exact_rounded_f64" / "new" / "estimates.json", stat, det_exact * 1.2)
+        _write_estimates(group / "solve_exact_f64_result" / "new" / "estimates.json", stat, det_exact * 1.3)
+        _write_estimates(group / "solve_exact_rounded_f64" / "new" / "estimates.json", stat, det_exact * 1.4)
 
     ns_group = criterion_dir / "exact_near_singular_3x3"
     _write_estimates(ns_group / "det_sign_exact" / "new" / "estimates.json", stat, 12000.0)
+    _write_estimates(ns_group / "solve_exact_f64_result" / "new" / "estimates.json", stat, 51000.0)
+    _write_estimates(ns_group / "solve_exact_rounded_f64" / "new" / "estimates.json", stat, 52000.0)
 
     random_group = criterion_dir / "exact_random_percentile_d3"
     _write_estimates(random_group / "det_exact_p95" / "new" / "estimates.json", stat, 33000.0)
+    _write_estimates(random_group / "solve_exact_f64_result_p95" / "new" / "estimates.json", stat, 54000.0)
+    _write_estimates(random_group / "solve_exact_rounded_f64_p95" / "new" / "estimates.json", stat, 55000.0)
 
 
 def _build_vs_linalg_tree(criterion_dir: Path, stat: str = "median") -> None:
@@ -196,7 +204,7 @@ def test_read_estimate_non_numeric_ci_bound_names_field(tmp_path: Path) -> None:
 def test_collect_results(tmp_path: Path) -> None:
     _build_criterion_tree(tmp_path)
     results = bench_compare._collect_results(tmp_path, "new", "median")
-    assert len(results) == 6  # 2 benches x 2 dims + 1 near-singular + 1 random percentile
+    assert len(results) == 18  # 6 benches x 2 dims + 3 near-singular + 3 random percentile
     groups = {r.group for r in results}
     assert "exact_d2" in groups
     assert "exact_d3" in groups
@@ -216,11 +224,37 @@ def test_collect_comparisons(tmp_path: Path) -> None:
         group = tmp_path / f"exact_d{d}"
         _write_estimates(group / "det" / "v0.3.0" / "estimates.json", "median", det)
         _write_estimates(group / "det_exact" / "v0.3.0" / "estimates.json", "median", det_exact)
+        _write_estimates(group / "det_exact_f64" / "v0.3.0" / "estimates.json", "median", det_exact * 1.1)
+        _write_estimates(group / "solve_exact_f64" / "v0.3.0" / "estimates.json", "median", det_exact * 1.3)
+    random_group = tmp_path / "exact_random_percentile_d3"
+    _write_estimates(random_group / "det_exact_p95" / "v0.3.0" / "estimates.json", "median", 66000.0)
+    _write_estimates(random_group / "solve_exact_f64_p95" / "v0.3.0" / "estimates.json", "median", 108000.0)
 
     comparisons = bench_compare._collect_comparisons(tmp_path, "v0.3.0", "median")
-    assert len(comparisons) == 4  # 2 benches x 2 dims (near-singular has no baseline)
+    assert len(comparisons) == 12  # 6 benches x 2 dims (near-singular has no baseline)
+    assert {c.group for c in comparisons} == {"exact_d2", "exact_d3"}
     for c in comparisons:
         assert c.speedup == pytest.approx(c.baseline_ns / c.current_ns)
+    assert {(c.bench, c.baseline_bench) for c in comparisons if c.baseline_bench is not None} == {
+        ("det_exact_f64_result", "det_exact_f64"),
+        ("det_exact_rounded_f64", "det_exact_f64"),
+        ("solve_exact_f64_result", "solve_exact_f64"),
+        ("solve_exact_rounded_f64", "solve_exact_f64"),
+    }
+
+    all_comparisons = bench_compare._collect_comparisons(
+        tmp_path,
+        "v0.3.0",
+        "median",
+        scope="all-benches",
+    )
+    assert len(all_comparisons) == 15
+    random_comparisons = [c for c in all_comparisons if c.group == "exact_random_percentile_d3"]
+    assert {(c.bench, c.baseline_bench) for c in random_comparisons} == {
+        ("det_exact_p95", None),
+        ("solve_exact_f64_result_p95", "solve_exact_f64_p95"),
+        ("solve_exact_rounded_f64_p95", "solve_exact_f64_p95"),
+    }
 
 
 def test_collect_comparisons_zero_current(tmp_path: Path) -> None:
@@ -301,12 +335,16 @@ def test_comparison_tables_per_dimension(tmp_path: Path) -> None:
         group = tmp_path / f"exact_d{d}"
         _write_estimates(group / "det" / "v0.3.0" / "estimates.json", "median", det)
         _write_estimates(group / "det_exact" / "v0.3.0" / "estimates.json", "median", det_exact)
+        _write_estimates(group / "det_exact_f64" / "v0.3.0" / "estimates.json", "median", det_exact * 1.1)
+        _write_estimates(group / "solve_exact_f64" / "v0.3.0" / "estimates.json", "median", det_exact * 1.3)
 
     comparisons = bench_compare._collect_comparisons(tmp_path, "v0.3.0", "median")
     tables = bench_compare._comparison_tables(comparisons, "v0.3.0")
     assert "### D=2" in tables
     assert "### D=3" in tables
     assert "| Benchmark | v0.3.0 | Latest | Change | Speedup |" in tables
+    assert "det_exact_rounded_f64 (vs det_exact_f64)" in tables
+    assert "solve_exact_f64_result (vs solve_exact_f64)" in tables
 
 
 def test_comparison_tables_include_vs_linalg_peer_context(tmp_path: Path) -> None: