# Code Organization
Module, feature, and file-placement guidance for the published Rust library and
its unpublished comparison-benchmark package.
Read [AGENTS.md](../AGENTS.md) for agent rules and use the
[contributor workflow](../CONTRIBUTING.md) for setup and validation commands.
## Contents
- [Library modules](#library-modules)
- [Feature boundaries](#feature-boundaries)
- [Tests and examples](#tests-and-examples)
- [Benchmarks and support tooling](#benchmarks-and-support-tooling)
- [Documentation owners](#documentation-owners)
## Library modules
`src/lib.rs` wires private implementation modules and public re-exports. It
also owns the documentation-only `guide` module, the private README doctest
mirrors, and the public prelude. There is no `src/main.rs`.
| [`src/angle.rs`](../src/angle.rs) | `VectorAngle` slice extension trait, direction scaling, and the shared unsigned-angle kernel |
| [`src/error.rs`](../src/error.rs) | `LaError` and typed singularity, non-finite, positive-semidefinite, tolerance, factorization, arithmetic-operation, and exact-conversion categories |
| [`src/exact.rs`](../src/exact.rs) | Exact determinants and solves, determinant-sign filtering, and exact-to-`f64` conversion |
| [`src/gram.rs`](../src/gram.rs) | Fixed-size Gram construction from vector dot products |
| [`src/interval.rs`](../src/interval.rs) | Interval scalars, matrices, and determinant-sign certification |
| [`src/ldlt.rs`](../src/ldlt.rs) | Unpivoted `Ldlt<D>` factorization for exactly symmetric positive-definite matrices, solves, and determinants |
| [`src/lu.rs`](../src/lu.rs) | Partially pivoted `Lu<D>` factorization, solves, and determinants |
| [`src/matrix.rs`](../src/matrix.rs) | `Matrix<D>`, finite storage, accessors, matrix operations, norms, and direct determinant APIs |
| [`src/norm.rs`](../src/norm.rs) | Exact range-boundary fallback for the approximate Euclidean norm |
| [`src/rational.rs`](../src/rational.rs) | `RationalMatrix<D>` and `RationalVector<D>`, canonical rational inputs, and denominator clearing for exact arithmetic |
| [`src/rounding.rs`](../src/rounding.rs) | Shared binary64 rounding primitives for certified arithmetic |
| [`src/scaled_product.rs`](../src/scaled_product.rs) | Allocation-free scaled products for floating-point factor diagonals |
| [`src/tolerance.rs`](../src/tolerance.rs) | Validated singular-tolerance policy |
| [`src/vector.rs`](../src/vector.rs) | `Vector<D>`, finite storage, reductions, norms, and certified scalar results |
Keep shared arithmetic invariants in the lowest owning module and expose public
items through `src/lib.rs`. Mathematical derivations and algorithm references
belong in [Mathematical basis](mathematical_basis.md) and
[REFERENCES.md](../REFERENCES.md).
## Feature boundaries
The [Cargo manifest](../Cargo.toml) owns feature and dependency declarations.
- **`exact`** gates `src/exact.rs`, `src/rational.rs`, their additional tests,
exact guides, and exact-arithmetic examples. It enables `det_exact()`,
strict `det_exact_f64()`, rounded `det_exact_rounded_f64()`,
`det_sign_exact()`, `solve_exact()`, strict `solve_exact_f64()`, and
rounded `solve_exact_rounded_f64()` for finite binary64 inputs, plus the
rational-input types.
- `det_sign_exact()` is infallible for finite-by-construction `Matrix` values.
Exact-value, conversion, and solve APIs retain their genuine scale,
representation, and singularity failures.
- `ExactF64Conversion` converts an already-computed determinant or solution
under the strict or rounded contract without rerunning exact elimination.
Feature-gated re-exports include `DeterminantSign`, `ExactF64Conversion`,
`RationalMatrix`, `RationalVector`, `BigInt`, `BigRational`, `FromPrimitive`,
`ToPrimitive`, and `Signed`.
- Typed error categories, including `UnrepresentableReason`, remain available
without `exact`; matching errors must not require optional arithmetic
dependencies.
- The scaled `BigInt` determinant core uses direct expansions for D≤4 and
fraction-free Bareiss elimination for D≥5. Exact signs add a floating-point
filter for D≤4. Exact solves use fraction-free forward elimination with
first-non-zero pivoting and `BigRational` back-substitution. Rational inputs
use direct substitution for triangular systems (including row permutations),
and otherwise clear denominators before reusing the integer backend.
- **`bench`** is a cfg-only gate for benchmark targets. Benchmark libraries
remain dev-dependencies. Nalgebra and faer belong only to the unpublished
`la-stack-comparison` package under `benches/comparison`, so exact benchmark
builds do not compile either peer library.
## Tests and examples
- Rust unit tests live in inline `#[cfg(test)]` modules in `src/*.rs`.
- `tests/proptest_*.rs` covers angles, matrix, vector, factorization, exact, rational,
interval, and Gram properties. Exact and rational suites require `exact`.
- Other `tests/*.rs` suites cover regressions, API contracts, allocation
behavior, conversion boundaries, and benchmark inputs. Shared property-test
configuration lives in `tests/common/`.
- `tests/vector_angles.rs` owns independent analytical angle regressions,
typed operand/shape errors, and allocation evidence. `tests/angle_bench_inputs.rs`
runs the independent fixture gates shared with the angle benchmark.
- `tests/rational_structured_solve.rs` checks triangular solves against the
captured Gaussian reference, exact residuals, and typed singularity metadata
through D=8, including arbitrary row permutations and wide rational inputs.
- `benches/comparison/tests/vs_linalg_inputs.rs` checks the shared comparison
fixtures. `just test-bench-inputs` and the full CI test pass include both
workspace packages.
- `tests/semgrep/` contains deliberate static-analysis fixtures, not ordinary
runnable API examples.
- Python tests live under `scripts/tests/` and run with pytest through
`just test-python` or the aggregate validation workflows.
- `examples/` contains complete runnable workflows. README mirrors and public
guide doctests live in `src/lib.rs`.
Use [Testing guidance](dev/testing.md) for dimension coverage and test design,
and [Documentation guidance](dev/docs.md) for executable-example ownership.
## Benchmarks and support tooling
`benches/` contains Criterion suites for angles, exact arithmetic, Gram construction,
intervals, linear forms, structured rational solves, and nalgebra/faer comparisons. Helpers under
`benches/common/` own fixture and oracle validation. Exact benchmark helpers
accept only `ValidatedExactInput`, after independent validation outside timing.
Adversarial groups include near-singular, large-entry, and Hilbert inputs.
`benches/common/angle.rs` owns the independently checked angle fixtures and
the stable comparison kernel; `benches/angle.rs` separates prepared vectors,
borrowed slices, and construction costs.
`benches/common/rational_solve.rs` owns the structured rational fixtures and
captured Delaunay Gaussian control. `benches/rational_solve.rs` separates
construction, prepared solves, and full runtime-dispatch adapter costs;
`tests/exact_bench_config.rs` includes its independent fixture gates.
The root package is the default workspace member. `benches/comparison/Cargo.toml`
owns the `vs_linalg` target at `benches/vs_linalg.rs` and its input test. Select
it with `just bench-vs-linalg` or Cargo's `-p la-stack-comparison`. Both packages
inherit the root workspace lints and share the lockfile and target directory.
The [Benchmarking guide](BENCHMARKING.md) owns benchmark commands, methodology,
baselines, output locations, and report promotion. The [Scripts guide](../scripts/README.md)
owns the Python script inventory and entry points for comparisons and plotting.
The pinned published `research-repo-tools` dependency
owns changelog generation, normalization, minor-series archiving, note lookup,
and tag preparation through its CLI. Consumer identity and dependency-body policy
stay in `[tool.research-repo-tools.changelog]` in `pyproject.toml`, with
formatting in `changelog-rumdl.toml`; no common template is copied locally.
focused integration checks live in `scripts/tests/test_changelog_integration.py`.
The same dependency owns CodeRabbit review orchestration through thin Just
wrappers. `scripts/tests/test_review_integration.py` owns consumer wiring checks
with local stubs; the [contributor review workflow](../CONTRIBUTING.md#coderabbit-review)
owns prerequisites and invocation policy.
The [justfile](../justfile) owns executable development workflows.
`osv-scanner.toml` owns temporary advisory-specific dependency exceptions, and
`.gitleaks.toml` owns narrow secret-scan false-positive exceptions. Their rationale
and review policy belong in [Security Checks](../SECURITY.md#security-checks).
The shared package also owns managed tool installation, verification, and update
implementation. `.python-version`, `rust-toolchain.toml`, and `pyproject.toml`
own consumer declarations; `scripts/tests/test_toolchain_integration.py` checks
actual recipe sequencing and native managed execution. The
`.github/actions/setup-tools/action.yml` composite synchronizes the locked PyPI
package and exports verified paths for CI. Release callers disable its caches.
Release metadata, version checks, Markdown line checks, and Semgrep fixture
validation also belong to the shared CLI. Consumer policy stays in
`pyproject.toml`; `scripts/tests/test_maintenance_integration.py` verifies the
actual release selectors and preservation of scientific evidence.
`scripts/tests/test_cargo_update_integration.py` exercises native dependency
upgrades and coupled exclusions against a disposable local registry.
The shared package also owns process discovery, captured/live execution, exact
byte transport, CPU metadata, diagnostics, and zizmor authentication. Consumers
call its public process API directly. Shared Criterion estimates replace local
timing wrappers. Tests use shared Just inspection and retain scientific
selection and consumer policy checks.
Performance consumers use shared Criterion parsing and estimate/comparison
validation, digest verification, archive extraction, byte-preserving document
sections, and multi-file transactions. Shared rendering produces complete-run
reports, coordinate SVG, timing CSV and document tables. Historical artifact
bytes and fingerprint framing remain frozen; declarative shared conversion reads
the original CSV/metadata without a legacy writer. Published v0.1.9
owns common-harness orchestration, completeness, worktrees, complete run retention,
validated latest selection, and transactional report publication.
Generic parsing, staging, and rollback tests belong upstream; local
tests verify the scientific and retained-artifact integration boundaries.
Hosted Dependabot approvals use the pinned shared
GitHub workflow; the [rollout guide](dev/MANAGING_CHANGES.md#dependabot-approval-rollout)
owns settings and deployment verification.
`tooling/criterion-inventory.toml` declares native full-suite list commands and
minimum scientific report/plot coverage. `tooling/criterion-saved.toml` declares
complete saved-sample requirements. Shared discovery and saved-sample APIs own
inventory parsing and exact raw-file verification. The release workflow packages only datasets that pass
that gate; its regression and archive tests live in
`scripts/tests/test_release_baseline.py`.
`tooling/performance.just` declares native Cargo commands, features, and input
gates for both local measurements and release inventories.
`tooling/performance.toml` uses the shared measurement schema for source/harness
inputs, probes, timeouts, and compatibility fields.
`tooling/performance-policy.toml` owns the scientific metric catalog, exact groups,
peer mappings and historical API availability. `scripts/performance_runs.py`
binds those declarations to scientific coverage, release compatibility and
named reference-phase assertions. `scripts/archive_performance.py` composes
shared APIs for tracked-only measurements, metadata-free historical raw archives
and la-stack README publication.
`tooling/performance-plot.toml` declares dimensions, units, series and axes.
`tooling/performance-report.toml` owns the canonical report path, title, and shared history path.
`tooling/performance-legacy.toml` declares shared historical comparison conversion.
The old comparison renderer, CSV/provenance writer, summary reader, plotter,
release-inventory wrapper and Python packaging are removed. Only the two
consumer adapters remain; `scripts/tests/test_performance_workflow.py` verifies
installed-package integration and offline replay. Shared renderers preserve the
figure’s scientific coordinates, units and originating series. The
[adoption record](dev/performance-tooling-adoption.md) owns retained-helper
dispositions, Python 3.15 review and native validation gates.
`tooling/semgrep/` owns a locked Python 3.14 environment for Semgrep 1.180.0
while its wheels exclude Python 3.15. Local scans, shared fixture validation
and hosted SARIF use it; ordinary support scripts use Python 3.15.
`.github/actions/prepare-release-benchmarks/action.yml` groups tool installation,
input validation, and inventory under the release workflow's shared setup timeout.
`.github/workflows/publish-crates.yml` owns the reviewed-release event, native
Cargo dry-run, deployment approval and OIDC upload. The publishing declaration
in `pyproject.toml` selects `la-stack`, native checks and the Criterion asset;
shared release gates own generic identity, ancestry and registry checks.
`scripts/tests/test_release_publishing.py` owns installed-package consumer checks
and upload-barrier tests. The [release guide](RELEASING.md) owns account setup,
manual publication, registry verification and recovery.
## Documentation owners
Use [Documentation guidance](dev/docs.md) for README, references, mathematical
background, rustdoc, and generated-file ownership. Focused operational rules
live in `docs/dev/`; human setup and validation guidance lives in
[CONTRIBUTING.md](../CONTRIBUTING.md). Release procedures belong in
[Releasing](RELEASING.md).
[Managing changes](dev/MANAGING_CHANGES.md) owns Git and GitHub procedures.
[Measuring coverage](MEASURING_COVERAGE.md) owns local and CI coverage execution.
The generated [performance report](performance.md) records measured results;
[Benchmarking](BENCHMARKING.md) owns the commands that produce and compare them.
[Local benchmark summaries](performance/README.md) owns complete versioned local
datasets. Completed optimization studies belong under
[archived performance studies](archive/performance/studies/README.md).
The [Rust 1.99 study](archive/performance/studies/rust-1.99.md) owns the compiler
migration baseline and its retained measurements; it is separate from generated
release-to-release reports.
The [interval and certified-reduction study](archive/performance/studies/interval-reductions.md)
owns the #247/#248 same-toolchain comparisons and downstream adoption evidence.
The [vector-angle study](archive/performance/studies/vector-angles.md) owns the
#249 formulation decision, comparative timings, and retained source provenance.
The [triangular rational solve study](archive/performance/studies/rational-triangular.md)
owns the #246 Rust 1.99 baseline, adapter/kernel comparisons, and retained evidence.
The [algebraic floating-point study](archive/performance/studies/algebraic-float.md)
owns the #250 numerical/performance experiment and its raw evidence.
The [validation index](validation/README.md) maps arithmetic contracts
to independent tests and owns dated validation decisions and their limitations.
The [algebraic floating-point decision](validation/algebraic-floating-point.md)
records rejection and the maintainer's closure of unperformed prototype work.
Mathematical guarantees remain in `mathematical_basis.md`; performance archives
retain measurement data and experimental sources.
When adding, removing, renaming, or moving files, update the applicable ownership
rows here. Prefer links to the detailed owner over copying its procedure into
this map or `AGENTS.md`.