feat(validation): guard README dependency snippets

- Add a generic docs-version sync check that compares Markdown dependency
  snippets against the Cargo package name and version
- Run the docs-version check from the repository Semgrep policy lane
- Refresh README determinant examples with explicit fallible handling and
  hidden doctest mirrors
- Update CI uv pins to 0.11.19

Author: acgetchell

.github/workflows/ci.yml

@@ -30,7 +30,7 @@ env:
   RUMDL_VERSION: "0.2.6"
   TAPLO_VERSION: "0.10.0"
   TYPOS_VERSION: "1.47.1"
-  UV_VERSION: "0.11.18"
+  UV_VERSION: "0.11.19"
   ZIZMOR_VERSION: "1.25.2"
 
 jobs:

.github/workflows/semgrep-sarif.yml

@@ -24,7 +24,7 @@ permissions:
   actions: read
 
 env:
-  UV_VERSION: "0.11.18"
+  UV_VERSION: "0.11.19"
 
 jobs:
   semgrep-sarif:

AGENTS.md

@@ -159,6 +159,20 @@ When user requests commit message generation:
   take references (`&T`, `&mut T`, `&[T]`) as arguments and return borrowed views (`&T`, `&[T]`) when possible.
   Only take ownership or return `Vec`/allocated data when required.
 
+### Documentation
+
+- `src/lib.rs` includes `README.md` with `#![doc = include_str!("../README.md")]`, so README examples are the
+  docs.rs landing page examples.
+- When changing Rust examples in `README.md`, mirror executable versions in the private `readme_doctests` module in
+  `src/lib.rs`. Keep mirrors hidden/private so they do not duplicate the docs.rs landing page, but make them runnable
+  by `cargo test --doc`.
+- README examples that require optional features may remain `rust,ignore` in README for default-feature doctest
+  compatibility, but must have a `#[cfg(feature = "...")]` hidden doctest mirror in `src/lib.rs` and be verified with
+  the matching feature set (for example, `cargo test --features exact --doc`).
+- When intentionally updating package versions or dependency snippets, keep README `la-stack` dependency examples in
+  sync with the package `version` in `Cargo.toml`. Do not perform version bumps unless explicitly requested by the
+  maintainer; see **Public-API stability** above.
+
 ### Dimension Coverage (2D–5D)
 
 This library uses `const`-generic dimensions. Tests for dimension-generic code

README.md

@@ -68,7 +68,7 @@ Add this to your `Cargo.toml`:
 
 ```toml
 [dependencies]
-la-stack = "0.4.1"
+la-stack = "0.4.2"
 ```
 
 Solve a 5×5 system via LU:
@@ -120,7 +120,16 @@ fn main() -> Result<(), LaError> {
         [0.0, 0.0, 0.0, 1.0, 2.0],
     ])?;
 
-    let det = a.ldlt(DEFAULT_SINGULAR_TOL)?.det()?;
+    let ldlt = match a.ldlt(DEFAULT_SINGULAR_TOL) {
+        Ok(ldlt) => ldlt,
+        Err(err @ LaError::Asymmetric { row, col, .. }) => {
+            eprintln!("LDLT requires symmetry; first mismatch at ({row}, {col})");
+            return Err(err);
+        }
+        Err(err) => return Err(err),
+    };
+
+    let det = ldlt.det()?;
     assert!((det - 1.0).abs() <= 1e-12);
 
     Ok(())
@@ -149,18 +158,20 @@ evaluation when inputs are known:
 use la_stack::prelude::*;
 
 // Evaluated entirely at compile time — no runtime cost.
-const DET: Result<Option<f64>, LaError> = {
-    let m = match Matrix::<3>::try_from_rows([
-        [2.0, 0.0, 0.0],
-        [0.0, 3.0, 0.0],
-        [0.0, 0.0, 5.0],
-    ]) {
-        Ok(matrix) => matrix,
-        Err(_) => panic!("matrix entries must be finite"),
-    };
-    m.det_direct()
+const DET: Result<Option<f64>, LaError> = match Matrix::<4>::try_from_rows([
+    [2.0, 0.0, 0.0, 0.0],
+    [0.0, 3.0, 0.0, 0.0],
+    [0.0, 0.0, 5.0, 0.0],
+    [0.0, 0.0, 0.0, 7.0],
+]) {
+    Ok(matrix) => matrix.det_direct(),
+    Err(err) => Err(err),
 };
-assert_eq!(DET, Ok(Some(30.0)));
+
+fn main() -> Result<(), LaError> {
+    assert_eq!(DET?, Some(210.0));
+    Ok(())
+}
 ```
 
 The public `det()` method automatically dispatches through the closed-form path
@@ -180,13 +191,14 @@ rationals (this pulls in `num-bigint`, `num-rational`, and `num-traits` for
 
 ```toml
 [dependencies]
-la-stack = { version = "0.4.1", features = ["exact"] }
+la-stack = { version = "0.4.2", features = ["exact"] }
 ```
 
 **Determinants:**
 
 - **`det_exact()`** — returns the exact determinant as a `BigRational`
 - **`det_exact_f64()`** — returns the exact determinant converted to the nearest `f64`
+  (or `LaError::Overflow` when the exact value is unrepresentable)
 - **`det_sign_exact()`** — returns the provably correct sign (−1, 0, or +1)
 
 **Linear system solve:**
@@ -208,6 +220,19 @@ fn main() -> Result<(), LaError> {
 
     let det = m.det_exact()?;
     assert_eq!(det, BigRational::from_integer(0.into())); // exact zero
+    let det_f64 = m.det_exact_f64()?;
+    assert_eq!(det_f64, 0.0);
+
+    // If the exact determinant cannot fit in f64, keep the BigRational value.
+    let big = f64::MAX / 2.0;
+    let huge = Matrix::<3>::try_from_rows([
+        [0.0, 0.0, 1.0],
+        [big, 0.0, 1.0],
+        [0.0, big, 1.0],
+    ])?;
+    let huge_det = huge.det_exact()?;
+    assert_eq!(huge.det_exact_f64(), Err(LaError::Overflow { index: None }));
+    println!("exact determinant = {huge_det}");
 
     // Exact linear system solve
     let a = Matrix::<2>::try_from_rows([[1.0, 2.0], [3.0, 4.0]])?;

docs/BENCHMARKING.md

@@ -46,10 +46,10 @@ just bench-vs-linalg
 just bench-exact
 
 # Save an exact baseline (e.g., before optimising)
-just bench-save-baseline v0.4.1
+just bench-save-baseline <baseline>
 
 # Compare current code against a saved baseline
-just bench-compare v0.4.1
+just bench-compare <baseline>
 
 # Generate a snapshot without comparison
 just bench-compare

examples/const_det_4x4.rs

@@ -6,37 +6,38 @@
 use la_stack::prelude::*;
 
 /// An example 4×4 matrix with small integer entries.
-const MAT: Matrix<4> = match Matrix::<4>::try_from_rows([
+const MAT: Result<Matrix<4>, LaError> = Matrix::<4>::try_from_rows([
     [1.0, 2.0, 3.0, 4.0],
     [5.0, 6.0, 7.0, 8.0],
     [2.0, 6.0, 1.0, 5.0],
     [3.0, 8.0, 2.0, 9.0],
-]) {
-    Ok(matrix) => matrix,
-    Err(_) => panic!("matrix entries must be finite"),
-};
+]);
 
 /// Determinant computed at compile time.
-const DET: f64 = match MAT.det_direct() {
-    Ok(Some(d)) => d,
-    Ok(None) => panic!("det_direct only supports D <= 4"),
-    Err(_) => panic!("matrix entries must be finite"),
+const DET: Result<Option<f64>, LaError> = match MAT {
+    Ok(matrix) => matrix.det_direct(),
+    Err(err) => Err(err),
 };
 
 fn main() -> Result<(), LaError> {
+    let mat = MAT?;
+
     println!("4×4 matrix:");
     for r in 0..4 {
         print!("  [");
         for c in 0..4 {
             if c > 0 {
                 print!(", ");
             }
-            print!("{:5.1}", MAT.get_checked(r, c)?);
+            print!("{:5.1}", mat.get_checked(r, c)?);
         }
         println!("]");
     }
     println!();
-    println!("det (computed at compile time) = {DET}");
+    match DET? {
+        Some(det) => println!("det (computed at compile time) = {det}"),
+        None => println!("det_direct is only available for D <= 4"),
+    }
 
     Ok(())
 }

justfile

@@ -461,11 +461,12 @@ python-sync: _ensure-uv
 
 python-typecheck: python-sync
     uv run ty check scripts/
-    uv run mypy scripts/archive_changelog.py scripts/bench_compare.py scripts/check_semgrep_fixtures.py scripts/criterion_dim_plot.py scripts/tag_release.py scripts/postprocess_changelog.py scripts/subprocess_utils.py
+    uv run mypy scripts/archive_changelog.py scripts/bench_compare.py scripts/check_docs_version_sync.py scripts/check_semgrep_fixtures.py scripts/criterion_dim_plot.py scripts/tag_release.py scripts/postprocess_changelog.py scripts/subprocess_utils.py
 
 # Repository-owned Semgrep rules for project-specific diagnostics.
 semgrep: _ensure-uv
     uv run semgrep --metrics off --error --strict --timeout 30 --config semgrep.yaml .
+    uv run check-docs-version-sync
 
 # Fixture tests for repository-owned Semgrep rules.
 semgrep-test: _ensure-uv

pyproject.toml

@@ -41,11 +41,12 @@ bench-compare = "bench_compare:main"
 criterion-dim-plot = "criterion_dim_plot:main"
 postprocess-changelog = "postprocess_changelog:main"
 tag-release = "tag_release:main"
+check-docs-version-sync = "check_docs_version_sync:main"
 
 # Configure setuptools to find modules in scripts/ directory.
 [tool.setuptools]
 package-dir = { "" = "scripts" }
-py-modules = [ "archive_changelog", "bench_compare", "check_semgrep_fixtures", "criterion_dim_plot", "postprocess_changelog", "subprocess_utils", "tag_release" ]
+py-modules = [ "archive_changelog", "bench_compare", "check_docs_version_sync", "check_semgrep_fixtures", "criterion_dim_plot", "postprocess_changelog", "subprocess_utils", "tag_release" ]
 
 [tool.ruff]
 line-length = 160

scripts/check_docs_version_sync.py

@@ -0,0 +1,131 @@
+"""Check that documentation dependency snippets match Cargo.toml."""
+
+from __future__ import annotations
+
+import re
+import sys
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+SKIP_DIRS = frozenset(
+    {
+        ".git",
+        ".mypy_cache",
+        ".pytest_cache",
+        ".ruff_cache",
+        ".tmp_pycache",
+        ".venv",
+        "target",
+    }
+)
+
+
+@dataclass(frozen=True)
+class PackageInfo:
+    """Cargo package identity used in documented dependency snippets."""
+
+    name: str
+    version: str
+
+
+@dataclass(frozen=True)
+class DependencySnippet:
+    """A documented dependency version snippet for the current package."""
+
+    path: Path
+    line: int
+    version: str
+    text: str
+
+
+@dataclass(frozen=True)
+class VersionMismatch:
+    """A dependency snippet whose version does not match Cargo.toml."""
+
+    snippet: DependencySnippet
+    package: PackageInfo
+
+
+def _read_cargo_package_info(cargo_toml: Path) -> PackageInfo:
+    data: dict[str, Any] = tomllib.loads(cargo_toml.read_text(encoding="utf-8"))
+    package = data.get("package")
+    if not isinstance(package, dict):
+        msg = f"{cargo_toml} is missing a [package] table"
+        raise TypeError(msg)
+
+    name = package.get("name")
+    if not isinstance(name, str):
+        msg = f"{cargo_toml} is missing a string package.name"
+        raise TypeError(msg)
+
+    version = package.get("version")
+    if not isinstance(version, str):
+        msg = f"{cargo_toml} is missing a string package.version"
+        raise TypeError(msg)
+    return PackageInfo(name=name, version=version)
+
+
+def _iter_markdown_files(root: Path) -> list[Path]:
+    return sorted(path for path in root.rglob("*.md") if path.is_file() and not (set(path.relative_to(root).parts) & SKIP_DIRS))
+
+
+def _dependency_regex(package_name: str) -> re.Pattern[str]:
+    escaped_name = re.escape(package_name)
+    return re.compile(rf'(?<![\w.-]){escaped_name}\s*=\s*(?:"(?P<plain>[^"]+)"|\{{\s*version\s*=\s*"(?P<table>[^"]+)")')
+
+
+def _dependency_snippets(path: Path, package_name: str) -> list[DependencySnippet]:
+    dependency_re = _dependency_regex(package_name)
+    snippets: list[DependencySnippet] = []
+    for line_number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1):
+        for match in dependency_re.finditer(line):
+            version = match.group("plain") or match.group("table")
+            snippets.append(
+                DependencySnippet(
+                    path=path,
+                    line=line_number,
+                    version=version,
+                    text=line.strip(),
+                )
+            )
+    return snippets
+
+
+def find_version_mismatches(root: Path) -> list[VersionMismatch]:
+    """Return documented dependency snippets for this crate that are stale."""
+
+    package = _read_cargo_package_info(root / "Cargo.toml")
+    mismatches: list[VersionMismatch] = []
+    for path in _iter_markdown_files(root):
+        for snippet in _dependency_snippets(path, package.name):
+            if snippet.version != package.version:
+                mismatches.append(VersionMismatch(snippet=snippet, package=package))
+    return mismatches
+
+
+def main() -> int:
+    root = Path(sys.argv[1]).resolve() if len(sys.argv) > 1 else Path.cwd()
+    try:
+        mismatches = find_version_mismatches(root)
+    except (OSError, TypeError, tomllib.TOMLDecodeError) as error:
+        print(f"Could not check documentation dependency versions: {error}", file=sys.stderr)
+        return 1
+
+    if not mismatches:
+        return 0
+
+    print("Documentation dependency snippets are out of sync with Cargo.toml:", file=sys.stderr)
+    for mismatch in mismatches:
+        snippet = mismatch.snippet
+        rel_path = snippet.path.relative_to(root)
+        print(
+            f"  {rel_path}:{snippet.line}: {mismatch.package.name} found {snippet.version}, expected {mismatch.package.version}: {snippet.text}",
+            file=sys.stderr,
+        )
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())