fix(bench): make v0.4.3 comparisons correctness-aware

- Adapt the shared benchmark harness across v0.4.3 API differences without changing measured operations
- Exclude invalid balanced-range baselines while requiring current samples and reporting unavailable comparisons
- Preserve benchmark provenance, suite-specific fallback commands, and publication rollback guarantees
- Harden Windows Git input, changelog links, and version-reference parsing across platforms

Author: acgetchell

Cargo.toml

@@ -25,6 +25,7 @@ include = [
     "/docs/assets/**/*.csv",
     "/docs/assets/**/*.jpg",
     "/docs/assets/**/*.png",
+    "/docs/assets/**/*.provenance.json",
     "/docs/assets/**/*.svg",
     "/examples/**/*.rs",
     "/src/**/*.rs",
@@ -88,6 +89,7 @@ unsafe_code = "forbid"
 missing_docs = { level = "deny", priority = 0 }
 dead_code = { level = "deny", priority = 0 }
 unreachable_pub = { level = "deny", priority = 0 }
+unexpected_cfgs = { level = "deny", priority = 0, check-cfg = [ 'cfg(la_stack_v0_4_3_api)' ] }
 
 [lints.rustdoc]
 bare_urls = "deny"

benches/common/exact.rs

@@ -7,7 +7,7 @@ use core::cmp::Ordering;
 use std::fmt::{self, Display};
 use std::num::NonZeroU64;
 
-use la_stack::{DeterminantSign, LaError, Matrix, UnrepresentableReason, Vector};
+use la_stack::{LaError, Matrix, UnrepresentableReason, Vector};
 use num_bigint::BigInt;
 use num_rational::BigRational;
 use num_traits::{FromPrimitive, Signed, ToPrimitive, Zero};
@@ -19,8 +19,10 @@ pub const RANDOM_SEED: [u8; 32] = [0; 32];
 
 /// Configuration errors for exact-arithmetic benchmark input generation.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
+#[non_exhaustive]
 pub enum ExactBenchConfigError {
     /// The inclusive lower bound was greater than the inclusive upper bound.
+    #[non_exhaustive]
     UnorderedRange {
         /// Inclusive lower bound.
         min: i16,
@@ -153,6 +155,29 @@ fn require_ok<T, E: Display>(result: Result<T, E>, operation: &str) -> T {
     }
 }
 
+/// Return one matrix entry through the bounds-checked API shared by current and
+/// v0.4.3 releases.
+fn stored_matrix_entry<const D: usize>(matrix: &Matrix<D>, row: usize, col: usize) -> f64 {
+    matrix
+        .get(row, col)
+        .unwrap_or_else(|| panic!("matrix entry ({row}, {col}) is outside dimension {D}"))
+}
+
+/// Normalize the exact determinant-sign API across the v0.4.3 compatibility
+/// boundary used only by historical benchmark worktrees.
+#[cfg(not(la_stack_v0_4_3_api))]
+fn checked_det_sign<const D: usize>(matrix: &Matrix<D>) -> i8 {
+    matrix.det_sign_exact().as_i8()
+}
+
+#[cfg(la_stack_v0_4_3_api)]
+fn checked_det_sign<const D: usize>(matrix: &Matrix<D>) -> i8 {
+    require_ok(
+        matrix.det_sign_exact(),
+        "exact determinant sign oracle check",
+    )
+}
+
 /// Return a deterministic, strictly diagonally-dominant matrix entry.
 #[inline]
 #[expect(
@@ -349,14 +374,13 @@ fn next_permutation(values: &mut [usize]) -> bool {
 
 /// Compute a determinant with the independent factorial-time Leibniz formula.
 fn determinant_leibniz<const D: usize>(matrix: &Matrix<D>) -> BigRational {
-    let rows = matrix.as_rows();
     let mut determinant = BigRational::zero();
     let mut permutation: [usize; D] = from_fn(|index| index);
 
     loop {
         let mut term = BigRational::from_integer(BigInt::from(1));
         for (row, &col) in permutation.iter().enumerate() {
-            term *= rational_from_f64(rows[row][col]);
+            term *= rational_from_f64(stored_matrix_entry(matrix, row, col));
         }
         if permutation_is_even(&permutation) {
             determinant += term;
@@ -372,11 +396,11 @@ fn determinant_leibniz<const D: usize>(matrix: &Matrix<D>) -> BigRational {
 }
 
 /// Return the exact determinant sign implied by an independent rational value.
-fn determinant_sign(exact: &BigRational) -> DeterminantSign {
+fn determinant_sign(exact: &BigRational) -> i8 {
     match exact.cmp(&BigRational::zero()) {
-        Ordering::Less => DeterminantSign::Negative,
-        Ordering::Equal => DeterminantSign::Zero,
-        Ordering::Greater => DeterminantSign::Positive,
+        Ordering::Less => -1,
+        Ordering::Equal => 0,
+        Ordering::Greater => 1,
     }
 }
 
@@ -474,7 +498,7 @@ fn assert_exact_residual<const D: usize>(input: &ExactInput<D>, solution: &[BigR
     for row in 0..D {
         let mut observed = BigRational::zero();
         for (col, value) in solution.iter().enumerate() {
-            observed += rational_from_f64(input.matrix.as_rows()[row][col]) * value;
+            observed += rational_from_f64(stored_matrix_entry(&input.matrix, row, col)) * value;
         }
         assert_eq!(observed, rational_from_f64(input.rhs.as_array()[row]));
     }
@@ -499,7 +523,7 @@ pub fn validate_exact_fixture<const D: usize>(input: ExactInput<D>) -> Validated
         determinant
     );
     assert_eq!(
-        input.matrix.det_sign_exact(),
+        checked_det_sign(&input.matrix),
         determinant_sign(&determinant)
     );
     assert_strict_scalar(input.matrix.det_exact_f64(), &determinant, None);

benches/common/vs_linalg.rs

@@ -4,8 +4,58 @@
 
 use faer::linalg::solvers::{Ldlt as FaerLdlt, PartialPivLu};
 use faer::perm::PermRef;
+use la_stack::{LaError, Tolerance, Vector};
 use nalgebra::SMatrix;
 
+/// Evaluate la-stack's dot product through the ownership contract used by the
+/// selected library revision.
+///
+/// # Errors
+///
+/// Returns the selected revision's typed error if finite inputs overflow during
+/// dot-product accumulation.
+#[cfg(not(la_stack_v0_4_3_api))]
+#[inline]
+pub fn la_stack_dot<const D: usize>(left: &Vector<D>, right: &Vector<D>) -> Result<f64, LaError> {
+    left.dot(right)
+}
+
+/// Evaluate the v0.4.3 by-value dot-product API without changing benchmark
+/// inputs or the mathematical operation.
+///
+/// # Errors
+///
+/// Returns v0.4.3's typed error if finite inputs overflow during dot-product
+/// accumulation.
+#[cfg(la_stack_v0_4_3_api)]
+#[inline]
+pub fn la_stack_dot<const D: usize>(left: &Vector<D>, right: &Vector<D>) -> Result<f64, LaError> {
+    (*left).dot(*right)
+}
+
+/// Parse a tolerance through the constructor exposed by the selected library
+/// revision.
+///
+/// # Errors
+///
+/// Returns a typed error when `value` is negative or non-finite.
+#[cfg(not(la_stack_v0_4_3_api))]
+#[inline]
+pub const fn la_stack_tolerance(value: f64) -> Result<Tolerance, LaError> {
+    Tolerance::try_new(value)
+}
+
+/// Parse a tolerance through v0.4.3's pre-`try_` constructor name.
+///
+/// # Errors
+///
+/// Returns a typed error when `value` is negative or non-finite.
+#[cfg(la_stack_v0_4_3_api)]
+#[inline]
+pub const fn la_stack_tolerance(value: f64) -> Result<Tolerance, LaError> {
+    Tolerance::new(value)
+}
+
 /// Return `det(P)` for faer's permutation representation.
 ///
 /// Sign(det(P)) is +1 for even permutations and -1 for odd. Parity is computed
@@ -127,11 +177,13 @@ pub fn make_pivoting_matrix_rows<const D: usize>() -> [[f64; D]; D] {
 /// Build a positive-definite diagonal matrix spanning 112 binary exponents at D=8.
 ///
 /// Each successive pivot is `2^-16` times the previous one. Benchmarks use a
-/// zero tolerance so the complete, finite factorization remains in scope.
+/// zero tolerance so the complete, finite factorization remains in scope. The
+/// fixed return dimension prevents extending the progression until a diagonal
+/// entry underflows to zero and destroys positive-definiteness.
 #[inline]
 #[must_use]
-pub fn make_ill_conditioned_matrix_rows<const D: usize>() -> [[f64; D]; D] {
-    let mut rows = [[0.0; D]; D];
+pub fn make_ill_conditioned_matrix_rows() -> [[f64; 8]; 8] {
+    let mut rows = [[0.0; 8]; 8];
     let mut diagonal = 1.0;
     for (index, row) in rows.iter_mut().enumerate() {
         row[index] = diagonal;

benches/vs_linalg.rs

@@ -19,15 +19,15 @@ use faer::mat::AsMatRef;
 use faer::{Mat, Side};
 use nalgebra::{Const, DimMin, SMatrix, SVector};
 
-use la_stack::{DEFAULT_SINGULAR_TOL, Matrix, Tolerance, Vector};
+use la_stack::{DEFAULT_SINGULAR_TOL, Matrix, Vector};
 
 #[path = "common/vs_linalg.rs"]
 pub mod vs_linalg_common;
 
 use vs_linalg_common::{
-    faer_det_from_ldlt, faer_det_from_partial_piv_lu, make_balanced_dynamic_range_rows,
-    make_ill_conditioned_matrix_rows, make_matrix_rows, make_pivoting_matrix_rows,
-    make_vector_array, matrix_entry, nalgebra_inf_norm, vector_entry,
+    faer_det_from_ldlt, faer_det_from_partial_piv_lu, la_stack_dot, la_stack_tolerance,
+    make_balanced_dynamic_range_rows, make_ill_conditioned_matrix_rows, make_matrix_rows,
+    make_pivoting_matrix_rows, make_vector_array, matrix_entry, nalgebra_inf_norm, vector_entry,
 };
 
 /// Return a successful benchmark operation result or panic with the named operation.
@@ -489,7 +489,7 @@ fn register_vector_benchmarks<const D: usize>(group: &mut BenchmarkGroup<'_, Wal
 
     group.bench_function("la_stack_dot", |bencher| {
         bencher.iter(|| {
-            let result = require_ok(black_box(&v1).dot(black_box(&v2)), "la_stack dot");
+            let result = require_ok(la_stack_dot(black_box(&v1), black_box(&v2)), "la_stack dot");
             black_box(result);
         });
     });
@@ -577,22 +577,19 @@ fn register_matrix_norm_benchmarks<const D: usize>(group: &mut BenchmarkGroup<'_
 }
 
 /// Register D=8 stress cases that exercise pivoting, conditioning, and scaled products.
-fn register_stress_benchmarks<const D: usize>(group: &mut BenchmarkGroup<'_, WallTime>) {
-    if D != 8 {
-        return;
-    }
-
-    let zero_tolerance = require_ok(Tolerance::try_new(0.0), "zero benchmark tolerance");
+fn register_stress_benchmarks(group: &mut BenchmarkGroup<'_, WallTime>) {
+    let zero_tolerance = require_ok(la_stack_tolerance(0.0), "zero benchmark tolerance");
     let pivoting = require_ok(
-        Matrix::<D>::try_from_rows(make_pivoting_matrix_rows()),
+        Matrix::<8>::try_from_rows(make_pivoting_matrix_rows()),
         "pivoting benchmark matrix construction",
     );
     let ill_conditioned = require_ok(
-        Matrix::<D>::try_from_rows(make_ill_conditioned_matrix_rows()),
+        Matrix::<8>::try_from_rows(make_ill_conditioned_matrix_rows()),
         "ill-conditioned benchmark matrix construction",
     );
+    #[cfg(not(la_stack_v0_4_3_api))]
     let balanced = require_ok(
-        Matrix::<D>::try_from_rows(make_balanced_dynamic_range_rows()),
+        Matrix::<8>::try_from_rows(make_balanced_dynamic_range_rows()),
         "balanced-range benchmark matrix construction",
     );
 
@@ -638,15 +635,18 @@ fn register_stress_benchmarks<const D: usize>(group: &mut BenchmarkGroup<'_, Wal
         );
     });
 
+    #[cfg(not(la_stack_v0_4_3_api))]
     let balanced_lu = require_ok(
         balanced.lu(zero_tolerance),
         "balanced-range LU factorization",
     );
+    #[cfg(not(la_stack_v0_4_3_api))]
     let balanced_ldlt = require_ok(
         balanced.ldlt(zero_tolerance),
         "balanced-range LDLT factorization",
     );
 
+    #[cfg(not(la_stack_v0_4_3_api))]
     group.bench_function("la_stack_det_from_lu_balanced_range", |bencher| {
         bencher.iter(|| {
             let det = require_ok(
@@ -657,6 +657,7 @@ fn register_stress_benchmarks<const D: usize>(group: &mut BenchmarkGroup<'_, Wal
         });
     });
 
+    #[cfg(not(la_stack_v0_4_3_api))]
     group.bench_function("la_stack_det_from_ldlt_balanced_range", |bencher| {
         bencher.iter(|| {
             let det = require_ok(
@@ -669,7 +670,7 @@ fn register_stress_benchmarks<const D: usize>(group: &mut BenchmarkGroup<'_, Wal
 }
 
 macro_rules! define_vs_linalg_benches_for_dim {
-    ($fn_name:ident, $d:literal) => {
+    ($fn_name:ident, $d:literal $(, $register_stress:ident)?) => {
         fn $fn_name(c: &mut Criterion) {
             let mut group = c.benchmark_group(concat!("d", stringify!($d)));
             register_determinant_benchmarks::<$d>(&mut group);
@@ -682,7 +683,9 @@ macro_rules! define_vs_linalg_benches_for_dim {
             register_precomputed_ldlt_determinant_benchmarks::<$d>(&mut group);
             register_vector_benchmarks::<$d>(&mut group);
             register_matrix_norm_benchmarks::<$d>(&mut group);
-            register_stress_benchmarks::<$d>(&mut group);
+            $(
+                $register_stress(&mut group);
+            )?
             group.finish();
         }
     };
@@ -692,7 +695,7 @@ define_vs_linalg_benches_for_dim!(bench_d2, 2);
 define_vs_linalg_benches_for_dim!(bench_d3, 3);
 define_vs_linalg_benches_for_dim!(bench_d4, 4);
 define_vs_linalg_benches_for_dim!(bench_d5, 5);
-define_vs_linalg_benches_for_dim!(bench_d8, 8);
+define_vs_linalg_benches_for_dim!(bench_d8, 8, register_stress_benchmarks);
 define_vs_linalg_benches_for_dim!(bench_d16, 16);
 define_vs_linalg_benches_for_dim!(bench_d32, 32);
 define_vs_linalg_benches_for_dim!(bench_d64, 64);

docs/BENCHMARKING.md

@@ -81,6 +81,20 @@ Criterion selection/commands, and both correctness-gate results. The report
 reader rejects malformed or mismatched provenance and incomplete selected-suite
 coverage.
 
+The shared harness carries an explicit v0.4.3-only API adapter for renamed or
+ownership-adjusted calls (`det_sign_exact`, `Tolerance`, and vector dot
+products). The adapter changes only how the same operation is invoked; it does
+not patch either library implementation. Comparison builds cap lint diagnostics
+at warning for both revisions because the current manifest's lint policy may
+reject historical source that predates a lint, even though that source remains
+valid benchmark input.
+
+The v0.4.3 LU/LDLT balanced-range determinant paths return an incorrect zero,
+so their two D=8 stress rows are deliberately not timed as baselines. Reports
+leave those baselines explicitly unavailable rather than presenting invalid
+performance evidence. The other v0.4.3 D=8 pivoting and ill-conditioned rows
+remain in the comparison.
+
 This command does not depend on existing local `target/criterion/` baselines.
 It is slower than reusing a saved baseline, but less sensitive to stale local
 benchmark state.

scripts/archive_changelog.py

@@ -320,14 +320,8 @@ def _archive_dir_link_prefix(archive_dir: Path, changelog_parent: Path) -> str:
         try:
             archive_dir_rel = Path(os.path.relpath(archive_dir, changelog_parent)).as_posix()
         except ValueError as err:
-            archive_dir_rel = archive_dir.as_posix()
-            LOGGER.warning(
-                "Could not compute relative archive directory: %s; archive_dir=%s changelog_parent=%s; generated Markdown links use %s",
-                err,
-                archive_dir,
-                changelog_parent,
-                archive_dir_rel,
-            )
+            msg = "cannot compute relative archive links because the archive and changelog directories are on different filesystem roots"
+            raise ValueError(msg) from err
         if archive_dir_rel == ".." or archive_dir_rel.startswith("../") or Path(archive_dir_rel).is_absolute():
             LOGGER.warning(
                 "Archive directory %s is outside changelog directory %s; generated Markdown links use %s",