Skip to content

spectral-init 0.1.0 release readiness (plan phases 0–6) - #268

Open
Trecek wants to merge 113 commits into
mainfrom
impl-crates_io_release_readiness_plan-20261111-144948
Open

Trecek wants to merge 113 commits into
mainfrom
impl-crates_io_release_readiness_plan-20261111-144948

Conversation

@Trecek

@Trecek Trecek commented Nov 12, 2026

Copy link
Copy Markdown
Contributor

Summary

Takes spectral-init from "cannot be packaged" to ready for a 0.1.0 release on crates.io. The work follows the release-readiness plan, phases 0 to 6, one commit per phase. The release itself (version bump, publish, tags), the umap-rs fork and the research-repository split are later phases and are not in this PR.

This is a breaking change of the public API. Nothing has been published yet, so no downstream user is affected.

What changes

Crate boundary. The repository becomes a workspace. The root package is the library and nothing else; the trustworthiness metric and its tools move to trustworthiness/, and benches, sweeps and exporters move to eval/. Neither is published. The package is an allow-list: 97 KiB instead of roughly 119 MiB.

Public API. One entry point:

pub fn spectral_init(
    graph: CsMatViewI<'_, f32, u32, usize>,
    data: Option<ArrayView2<'_, f32>>,
    config: &SpectralInitConfig,
) -> Result<Array2<f32>, SpectralError>
  • SpectralInitConfig::new(n_components) with with_seed, with_compute_mode, with_dense_memory_budget.
  • SpectralError has one typed variant per failure; there is no string catch-all.
  • sprs and ndarray are re-exported. All modules are private; internals are reachable only through a hidden __internal feature used by the crate's own tests and by eval/.
  • The public API is recorded in .github/api-snapshot.txt.

Behaviour.

  • The input is validated before any numerics: square, symmetric (relative tolerance 1e-6), finite, non-negative. CSR and CSC are both accepted; stored zeros are absent edges.
  • Self-loops count towards degree and adjacency, as in umap-learn.
  • spectral_init no longer panics. The last solver level is checked like the others, and a dense memory budget (4 GiB by default) bounds every dense matrix a solver allocates.
  • The result is always in standard (row-major) layout, which umap-rs requires.
  • Random numbers come from ChaCha12Rng. The stream is identical to the previous StdRng, so fixture tests are unchanged.

Portability and unsafe. No target-cpu override remains; SIMD is chosen by run-time detection. CsrOperatorSimd::new returns None unless everything the AVX2 kernel relies on holds, including an index pointer that starts at zero. Every unsafe block has a // SAFETY: comment, and the kernel's tests run under Miri.

umap-rs. umap-rs 0.4.5 is a dev-dependency, exercised by examples/umap_rs.rs and tests/public_api/umap_rs.rs. docs/umap-rs-integration.md documents the sequence and carries evidence tables that involve no optimizer.

Docs and legal. README and user guide are rewritten against the real API, and every Rust snippet in them runs as a doctest. Licence is MIT OR Apache-2.0. Two of the three KaTeX integrity hashes were wrong and are fixed. Adds CHANGELOG.md, CONTRIBUTING.md, SECURITY.md.

CI. test.yml becomes ci.yml with a test matrix (Linux x86_64 and aarch64, macOS, Windows, and an x86-64-v3 leg); the aggregate job keeps the name cargo nextest. New workflows: deps.yml (cargo-deny, cargo-machete), docs.yml (docs.rs build, KaTeX hashes), api.yml (API snapshot). Actions are pinned to commit SHAs. Dependabot is configured.

Verified locally (x86_64 Linux, final commit)

  • cargo fmt --all --check; clippy with -D warnings for the library alone and for the workspace with all features
  • cargo nextest run --locked --workspace --all-features --profile ci: 411 passed, 11 skipped
  • 23 doctests; default-feature cargo test
  • rustdoc with -D warnings; cargo docs-rs
  • Package gate on the clean tree: file list equals the allow-list, and the unpacked crate passes its own tests and cargo publish --dry-run
  • README quick start compiled against the unpacked crate in a project outside the repository
  • API snapshot, purity gate, KaTeX hash gate, cargo deny, cargo machete
  • Miri on the AVX2 kernel tests: 13 passed

Not verified — please look at the CI results of this PR

  • The workflows have never run before this PR. They also move actions/checkout and actions/upload-artifact from v4 to v7.
  • aarch64, macOS and Windows. Only type-checks were possible locally. Fixture comparisons keep their x86_64 tolerances on every target; if a leg fails on a tolerance, the figure has to be measured from that run.
  • MSRV 1.88. No 1.88 toolchain was available locally; the msrv job is the first real check.

Known issues for the reviewer

  • AutoSkillit merge gate. test_check runs the command in main's .autoskillit/config.yaml, which still passes --features testing. That feature no longer exists, so the gate fails on this branch until the updated config is on main.
  • Two links do not resolve yet. The README and the integration guide point at the fork branch TalonT-Org/umap-rs/tree/spectral-init and at the tag research-baseline-pre-0.1. Both are owner steps of the plan.
  • Licence of the workspace members. Only the published crate is MIT OR Apache-2.0; trustworthiness/ and eval/ still declare MIT.
  • SECURITY.md sends reports to GitHub private vulnerability reporting, which has to be enabled on the repository.
  • Differences from the plan. The API snapshot omits blanket impls so that dependency updates do not change it; cargo deny runs with --workspace; eval/ declares rust-version = "1.89" because one bench uses AVX-512 intrinsics.

Not in this PR

Issue triage and follow-up issues, the release rehearsal and publish, Trusted Publishing, the umap-rs fork, and the research-repository split.

🤖 Generated with Claude Code

Trecek and others added 30 commits November 11, 2026 15:17
Repository hygiene
- Track the pending .autoskillit/.gitignore entries.
- Replace the 11 tracked absolute symlinks under research/ with a DATA.md
  per directory naming each source file and its regenerating script; add
  research/README.md pointing at the research-baseline-pre-0.1 tag.

Manifest truth
- rust-version 1.88 (let-chains), valid keywords, no documentation key,
  an include allow-list, docs.rs metadata reduced to rustdoc-args.
- Track Cargo.lock (regenerated; rand, crossbeam-epoch and the yanked
  private-gemm-x86 advisories are gone).
- MSRV text updated in README, user guide and the bug-report template.

Portable build
- Delete .cargo/config.toml (target-cpu=native).
- Trustworthiness x-distance kernel: runtime AVX2+FMA dispatch instead of
  compile-time target_feature gating; guard the unit test and the bench.

Lint and docs
- Pass ComputeMode::RustNative at the 8 stale solve_eigenproblem_pub call
  sites in lobpcg_bench and simd_spmv_exp.
- Clear every --all-targets --all-features clippy diagnostic and all
  rustdoc errors.

Tests
- Remove the 28 stale fixture-gated #[ignore] attributes.
- Move the fixture-reading unit tests out of src/: scaling and operator
  tests become integration tests; the components tests duplicated
  test_comp_c_components and are dropped.

CI
- Add .github/scripts/check-package.sh and the package allow-list.
- test.yml: no RUSTFLAGS, --locked, clippy --all-targets without
  -A missing_docs, docs and doctest gate, MSRV job, package gate.

Co-Authored-By: Claude <noreply@anthropic.com>
… packages

Workspace
- The root manifest becomes a workspace with two unpublished members:
  `trustworthiness/` (metric, AVX2 kernels, `trustworthiness` and
  `tw_profiler` binaries, `cli`/`profiling` features; no dependency on
  spectral-init) and `eval/` -> `spectral-init-eval` (solver benches,
  sweeps, exporters, report structs).
- The root package drops its binaries, benches, the `testing`, `cli` and
  `profiling` features and the dependencies only they needed.

Library
- `src/metrics.rs` is split: solver thresholds and residual checks move to
  `src/solvers/quality.rs`; diagnostics move to test support; the
  trustworthiness code and the report structs move to their packages.
- All modules are private. A hidden `__internal` feature exposes
  `spectral_init::__internal` for the crate's own tests and `eval`.
- `SolverParams`, `QualityGates`, `SolverLevel` and `SolveReport` replace
  the SPECTRAL_* environment knobs and the stderr timing lines;
  `solve_eigenproblem` returns `Result<(EigenResult, SolveReport), _>` and
  each solver call site logs its report through `log::debug!`.

Tests
- Integration tests become two auto-discovered binaries: `public_api`
  (default features) and `internals` (`__internal`). `tests/common` is
  split into `fixtures.rs`, `internals.rs` and `diagnostics.rs`, shared
  with `eval` by path-include.
- Measurement-style tests move to `eval/tests`; their real assertions
  (SIMD/scalar parity, warm-restart behaviour) stay with the library in
  `tests/internals`. Tests that mutated the environment now pass
  `SolverParams`.
- `eval` writes to `temp/eval/` unless RESULTS_DIR is set.

Readers
- CI workflows, the merge-gate test command, nextest profiles, experiment
  skills, visual-eval scripts and docs follow the new package, feature and
  binary names. Add `.github/scripts/check-purity.sh`.

`eval` declares rust-version 1.89: its `simd_spmv_exp` bench uses AVX-512
intrinsics that are stable from that release.

Co-Authored-By: Claude <noreply@anthropic.com>
Entry point and configuration
- `spectral_init(graph: CsMatViewI<f32, u32, usize>, data: Option<ArrayView2<f32>>,
  config: &SpectralInitConfig) -> Result<Array2<f32>, SpectralError>`.
- `SpectralInitConfig` is opaque: `new(n_components)`, `with_seed`,
  `with_compute_mode`, `with_dense_memory_budget`, getters; no `Default`.
- `sprs` and `ndarray` are re-exported.
- The returned array is always in standard (row-major) layout.

Errors and validation
- `SpectralError` gets typed, `#[non_exhaustive]` struct variants and derives
  `Clone + PartialEq`; the string catch-all is gone.
- `src/validate.rs` checks the caller's matrix before any numerics, in a fixed
  precedence: InvalidParameter, NotSquare, TooFewNodes, NonFiniteWeight,
  NegativeWeight, NotSymmetric, DegreeOverflow, DataShapeMismatch,
  NonFiniteData. CSR and CSC storage are accepted; stored zeros are absent
  edges.

Numerics
- Self-loops take part in degree and adjacency (`L_ii = 1 - w_ii / d_i`), as in
  umap-learn; every diagonal entry is stored.
- The solver chain is fallible end to end. A dense memory budget guards
  Level 0, Level 4, Level 5 and the centroid affinity; Level 5 is gated on
  finiteness and residual and reports DenseBudgetExceeded or
  ConvergenceFailure instead of panicking.
- Random numbers come from `rand_chacha::ChaCha12Rng` (bit-identical to the
  previous `StdRng` stream; pinned by a golden file).

Tests
- Validation and tolerance calibration, self-loop reference fixture with its
  generator, no-panic property tests for the entry point and the solver
  chain, escalation and budget, trait contracts, seed contract, output
  layout.

Gates
- Public API snapshot `.github/api-snapshot.txt` with
  `.github/scripts/check-api.sh`; the purity gate forbids `StdRng` in `src/`;
  the package allow-list gains `src/error.rs` and `src/validate.rs`.

Co-Authored-By: Claude <noreply@anthropic.com>
SIMD soundness
- `CsrOperatorSimd::new` returns `Option`: `None` unless the matrix is square
  CSR with a zero-based index pointer, its column indices fit 32 bits
  (`simd_index_fits`) and the CPU has AVX2 and FMA. `solve_eigenproblem`
  uses the scalar operator on `None`.
- `apply` hard-asserts the vector lengths the gather kernel relies on; the
  raw-slice test entry `spmv_avx2_gather` is an `unsafe fn` with a `# Safety`
  section. Every `unsafe` block carries a `// SAFETY:` comment.
- SIMD code is gated on `target_arch = "x86_64"` throughout.

Lints
- `[lints]`: `unsafe_op_in_unsafe_fn`, `missing_docs`,
  `clippy::undocumented_unsafe_blocks` and `rustdoc::broken_intra_doc_links`
  are denied for every target of the root package.

Dependencies
- `sprs` without default features; `faer` with `std`, `rayon` and
  `sparse-linalg` only.
- `src/solvers/nd16_bridge.rs` is the only user of `ndarray16` and
  `linfa_linalg`; the purity gate enforces it.

Tests
- `tests/internals/simd.rs`: scalar/AVX2 SpMV parity on the fixture
  Laplacians, end-to-end agreement of the two compute modes, refusal of
  non-square and CSC input, the `i32::MAX` boundary, panics on mismatched
  lengths, and a compile-time check that the raw entry stays `unsafe`.
- `tests/determinism_threads.rs`: one and four threads agree within 1e-5
  (observed: identical for n = 500, 1.2e-10 for n = 1500); the crate docs
  state the figure and how to pin the thread configuration.
- A unit test with 1 to 12 non-zeros per row drives the kernel's vector loop
  and scalar tail; it runs under Miri.

CI
- The test job becomes a matrix (`ubuntu-latest`, `ubuntu-24.04-arm`,
  `macos-15`, `windows-latest`, and x86-64-v3), with no RUSTFLAGS on the
  default legs. A job named `cargo nextest` reports the aggregate result.
- Add a Miri job for the AVX2 kernel.
- `t_profiler_02_stderr_capture_writes_file` is Unix-only, like the feature
  it tests.

Co-Authored-By: Claude <noreply@anthropic.com>
Integration
- `umap-rs` 0.4.5 becomes a dev-dependency; the library itself depends on no
  UMAP implementation.
- `examples/umap_rs.rs`: synthetic data, brute-force k-NN,
  `Umap::learn_manifold`, `spectral_init` on `manifold.graph()`, then the
  `Optimizer`, with the default-epoch rule and the NaN marking of isolated
  vertices that `Umap::fit` performs.
- `tests/public_api/umap_rs.rs`: on fixture data, the learned graph passes
  validation, the initialization is `(n, n_components)`, finite and in
  standard layout, both `Optimizer::new` and `Umap::fit` accept it, and a
  graph built with `symmetrize = false` is rejected as `NotSymmetric`.
- Tolerance calibration: `umap-rs` graphs for `set_op_mix_ratio` 0.3, 0.5,
  0.7 and 1.0 pass validation on all nine datasets (measured asymmetry at
  most 1.2e-7 relative; the tolerance stays 1e-6).

Evidence
- `eval/src/assess.rs` holds the accuracy and parity measurements against
  the umap-learn fixtures; `test_metrics_assess` and the new
  `init_evidence` binary share them.
- `init_evidence` reports residuals, eigenvalue errors and subspace agreement
  on connected graphs, component counts and separation on disconnected ones,
  and trustworthiness of the raw initial coordinates for the spectral and
  for a uniform random initialization.

Docs
- `docs/umap-rs-integration.md`: the `Optimizer` sequence and the `fit`
  variant, what to know (`symmetrize`, mix ratio, `data`, rescaling, isolated
  vertices), umap-learn's edge pruning, the dated state of `umap-rs`, a
  zero-copy CSR recipe for other implementations, and the evidence tables.
  Its Rust snippets run as doctests, and the guide ships in the package.

Co-Authored-By: Claude <noreply@anthropic.com>
README
- States what the crate computes and for which inputs, with a compiled quick
  start through the re-exported `sprs`, the `umap-rs` snippet, both compute
  modes as they behave on every target, the solver chain and the dense memory
  budget, the full error table with a fallback `match`, platforms, the
  reproducibility contract, the semver policy, the two integration routes and
  acknowledgements.
- Drops the quality overclaim, the stale performance table and the stale
  testing and requirements sections.

Guides
- `docs/user-guide.md` is rewritten against the real API: building the graph,
  configuration, disconnected graphs and `data`, every error variant,
  reproducibility and threads, performance notes.
- README, user guide and integration guide are attached to the crate under
  `cfg(doctest)`, so every Rust snippet compiles and runs; both guides ship in
  the package.
- Internal reports move from `docs/` to `research/reports/` (benchmark plan and
  report, implementation report, metric definitions), with their links and the
  report generator's output path updated.

Source docs
- Crate docs: accurate algorithm, compute-mode and parity statements; the
  `umap-rs` section names the API that exists.
- Stale solver level labels corrected; tracker references removed from `src/`
  and `eval/benches/`; "bit-for-bit" and "exactly" claims replaced by what the
  tests verify.
- `tests/README.md`: fixtures are tracked; loaders and datasets described as
  they are.

KaTeX
- Two of the three subresource-integrity hashes in `docs/katex-header.html`
  were wrong; all three now match the files, as checked against the CDN and
  the npm tarball. `.github/scripts/check-sri.sh` verifies them in the docs
  job.

Project files
- `CHANGELOG.md` (Keep a Changelog) with the 0.1.0 entry.
- License `MIT OR Apache-2.0`: `LICENSE-MIT` (the former `LICENSE`) and
  `LICENSE-APACHE`.
- `.github/CONTRIBUTING.md` and `.github/SECURITY.md`.
- `CLAUDE.md`: six-level chain and dense budget, workspace test command,
  architecture, dependencies and report path as they are now.

Co-Authored-By: Claude <noreply@anthropic.com>
Packaging
- `include` gains `/CHANGELOG.md`; the allow-list matches the finished tree.

Workflows
- `test.yml` becomes `ci.yml`: fmt, both clippy configurations, the purity
  gate, rustdoc and doctests, the test matrix, MSRV, the package gate and
  Miri. The aggregate job keeps the name `cargo nextest`.
- The two slow tests move from `slow-tests.yml` into a `ci.yml` job that runs
  on the weekly schedule only; the aggregate job counts it as passed when it
  is skipped.
- `deps.yml`: `cargo deny` with `.config/deny.toml`, and `cargo machete`.
- `docs.yml`: the docs.rs build through `cargo docs-rs`, and the KaTeX
  integrity hashes.
- `api.yml`: the public API snapshot, with the nightly toolchain and
  cargo-public-api both pinned.
- Every workflow runs on `merge_group` without a path filter, pins its
  actions to commit SHAs, has read-only default permissions, a concurrency
  group and a timeout on every job.

Dependency policy
- `.config/deny.toml`: licence allow-list (dev-dependencies included),
  documented ignores for the `zip` advisories that reach the workspace only
  through ndarray-npy and for the unmaintained `paste` macro, and documented
  skips for the duplicate versions that linfa-linalg, faer's support crates
  and sprs's `alga` feature bring in.
- `.github/dependabot.yml` for Cargo and GitHub Actions.

Co-Authored-By: Claude <noreply@anthropic.com>
… NaN propagation

- Move LOBPCG_ACCEPT_TOL into lobpcg.rs and SINV_LINFA_TOL into sinv.rs as
  private consts: they are linfa's per-step stopping tolerances, not chain
  gates, so quality.rs now holds only the chain's acceptance thresholds and
  residual checks. Reword their docs to state value and role without the
  historical "Remains at" phrasing.
- Name the warm-restart seed binding instead of the positional `.1`.
- Add t_maxresid_02: a NaN residual in either eigenpair makes
  max_eigenpair_residual return NaN, so the gate cannot accept it.

Review findings #95, #127, #98, #30 (PR #268).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Levels 1-3 logged only the poor-quality path; a solver that returned no
result escalated without a log line. Log "produced no result, escalating"
for each, as Level 4 already does, and drop the "silently" wording from the
Level 2 comments.

Review finding #54 (PR #268).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`level_elapsed` was a `[_; 6]` indexed by `SolverLevel as usize` with no link
to the variant count. Add `SolverLevel::COUNT` and use it for the array type
in SolveReport, `accepted()` and the chain, and pin it in the discriminant
test.

Review finding #91 (PR #268).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`sym_eig` discarded faer's error with `.ok()?`, so the chain only reported
"Level 4 (rSVD) produced no result". Log the error at warn level before
returning None, matching how dense_evd reports the same faer failure.

Review finding #55 (PR #268).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
An invalid request, the dense-sketch budget rejection and a failed projected
eigenproblem all returned a bare None. Log the first two at debug level (the
third is logged by sym_eig), and route the budget check through
check_dense_budget so the message carries the required and budget byte counts.

Review finding #56 (PR #268).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The test hard-coded 288 bytes, which only holds while the default
oversampling yields k = 6 for n = 6. Compute the expected sketch with
`dense_bytes(n, rsvd_k_sub(n, rank, None))` so the boundary follows the
formula.

Review finding #35 (PR #268).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`from_nd16_array2` was `from_nd16_view2(a.view())` under a second name. Use
the view conversion at its one call site, keep the logical-layout rationale on
`from_nd16_view2`, and point the conversion tests at it.

Review finding #150 (PR #268).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
linfa returns Ok when the iteration budget runs out, so `Converged` does not
guarantee every eigenpair met the tolerance; say so, and that callers must
still check residuals (they do). `Partial` arises from a numerical error after
an iterate exists. Add a test for the `Failed` arm (a starting block wider than
the problem).

Review finding #34 (PR #268).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…odule

The module itself is `#[doc(hidden)]`, which already hides everything in it;
the thirteen per-re-export attributes changed nothing (rustdoc with
`--features __internal` still emits no `__internal` page).

Review finding #124 (PR #268).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Every other `__internal` re-export names its items; the `quality::*` glob
silently widened the surface whenever quality.rs gained an item. Name the six
items the tests and eval harness use.

Review finding #96 (PR #268).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…er test

`assert_eq!(cfg.clone(), cfg)` cannot fail for a derived Clone/PartialEq and
asserted nothing about the setters.

Review finding #32 (PR #268).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Every queued node is a row index below `n`, so `outer_view` always returns a
row. The `else { continue; }` arm was unreachable and, were the invariant ever
broken, would silently under-count components instead of surfacing the bug.

Review finding #145 (PR #268).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…raph

Every member index is below the node count (an out-of-range one already panics
at `lookup[orig] = local`), so `outer_view` always returns a row. Expect it
instead of silently skipping, which would have dropped edges.

Review finding #146 (PR #268).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nicking

`trustworthiness` asserted that x is in standard layout whenever the AVX2
X-distance path applied, so the same valid F-order input panicked on AVX2
hosts and scored correctly elsewhere. Gate the SIMD path on
`x.is_standard_layout()` as the Y path already does, and test a column-major
x with d_x = 12 against the brute-force reference and its C-order copy.

Review finding #63 (PR #268).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The X and Y steps each carried two verbatim copies of the scalar loop (the
x86_64 `else` arm and the non-x86_64 block), kept in sync by hand. Add
`dist_sq_scalar`, define the SIMD flags as `false` off x86_64, and branch once
per step so each step has a single scalar path. The summation order is
unchanged, so results are bit-identical.

Review findings #128, #129 (PR #268).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ntracts

`dist_sq_avx2_looped` is publicly re-exported (doc-hidden), yet its `# Safety`
section listed only the length and d_x >= 10 conditions, which are not safety
requirements (the kernel sums the common prefix), and omitted the one that is:
AVX2 and FMA must be available at run time. State that, and move the length
note out of the Safety section. `dist_sq_2d_avx2_batch` now lists AVX2 as a
requirement instead of describing its call site.

Review finding #62 (PR #268).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ic value

`t_tws_04` asserted that two seeds give different trustworthiness values, but
the penalty sums are integers, so two distinct samples can legitimately score
the same. Extract the sampling into `sample_query_indices` and assert that
different seeds sample different query rows; same-seed determinism stays
covered by t_tws_03.

Review finding #42 (PR #268).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`trustworthiness_brute_force` duplicated `trustworthiness_brute_force_subsampled`
line for line apart from the row set and the leading denominator factor, both
of which coincide when every row is a query. Make it a wrapper that passes all
rows, so a fix to the oracle applies to every test that uses it.

Review finding #157 (PR #268).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…eature

The feature comment said the `[timing:<step>]` lines are "parsed by the
tw_profiler binary", but `tw_profiler` requires only `cli`, and a `cli` build
emits no timing lines. Document that per-step timings need
`--features cli,profiling`, in the manifest, the profiler's header and the
crate's feature table. `step_timing` is optional by design, so the wiring
stays as it is.

Review finding #131 (PR #268).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
"builds spectral initialization in is at" did not parse. Both copies now say
the fork has spectral initialization built in.

Review findings #107, #85, #108 (PR #268).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… guide

The guide pinned the example to `blob/main` on GitHub while every other in-repo
documentation link is relative; the guide ships in the package next to
`examples/`, so `../examples/umap_rs.rs` is the consistent target.

Review finding #112 (PR #268).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ent skill

The sentence placed the metrics files at `.autoskillit/temp/run-experiment/`
"relative to the worktree" while the test runs with `eval/` as its working
directory. Say that a relative RESULTS_DIR would resolve under `eval/`, and
name the absolute output directory.

Review finding #109 (PR #268).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… skills

Both skills' inventory steps read `eval/src/` (assessment report structures)
as a metric source, but their canonical-name lists omitted it, so a metric
defined only there had to be flagged "NEW".

Review findings #133, #134 (PR #268).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Trecek and others added 26 commits November 12, 2026 13:20
run_lobpcg_test received each dataset's node count as `_expected_n` and never
read it. It now asserts the Laplacian has that many rows, like the sibling
comp_d_dense_evd module does.

Review finding #127 (ReviewPR iteration 2).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…g modules

comp_d_rsvd.rs spelled out crate::fixtures::, crate::internals:: and
spectral_init::__internal:: paths inline in its macro body. Every other comp_*
module imports them with `use`, and now this one does too. No behaviour change.

Review finding #88 (ReviewPR iteration 2).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
test_ring_2000_warm_restart_fires made the same lobpcg_solve call on
ring_laplacian(2000) with seed 42 and the same `restart_count > 0` assertion
as solver_invariants::test_inv_lobpcg_convergence_ill_conditioned, in the same
test binary. It doubled an expensive solve without adding coverage. The path_2000
test that referred to it "above" now states the FP-sensitivity note itself
and points to the remaining ring_2000 test.

Review finding #132 (ReviewPR iteration 2).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ader

The header claimed seven connected datasets, carried over from the deleted
integration file, but the module tests five. Its exclusion note also listed
only two of the four disconnected datasets. Comment-only change.

Review finding #112 (ReviewPR iteration 2).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
determinism_threads.rs is its own test binary with a single test, so no code
in the process runs after the test returns to see the global faer parallelism
the RestoreParallelism guard put back. The guard is gone, and the module doc
says the setting stays changed, which is why the binary holds one test.

Review finding #131 (ReviewPR iteration 2).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
a_one_ulp_asymmetry_passes_validation repeated perturb_one_weight's search for
the first off-diagonal edge and its CSR rebuild inline. The helper is now
with_first_edge_changed(graph, change). It takes the edit as a closure, so the
1e-3 scaling and the one-ULP nudge both go through it.

Review finding #109 (ReviewPR iteration 2).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`hits="$(grep ... || true)"` turned grep's status 2 (invalid pattern,
unreadable file, missing grep) into "no match", so the gate printed "purity
gate passed" without checking anything. forbid() now records grep's status and
exits 2 on anything above 1. A probe with an unbalanced parenthesis in a pattern
now stops the gate with exit 2, and the clean tree still passes.

Review finding #59 (ReviewPR iteration 2).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The "library must not print or read the environment" rule matched only
println!, eprintln!, dbg!, env::var and SPECTRAL_, so print!, eprint!,
io::stdout(), io::stderr() and env::args() passed. The pattern now covers
them. src/ has none, so the gate still passes; a probe confirms all eleven
forms match and format!/write!(f, ..) do not.

Review finding #60 (ReviewPR iteration 2).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The gate inspected only lines that already carried an `integrity` attribute.
A <script src> or <link href> added to docs/katex-header.html without one
(which rustdoc puts into every docs.rs page) still produced "SRI gate passed".
It now fails on any src/href resource without an integrity attribute and on any
protected resource not loaded over https. A probe header with one of each is
rejected, and the real header still passes (3 resources).

Review finding #61 (ReviewPR iteration 2).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The README stated that every directory under research/ is one dated
experiment, but research/reports/ (the implementation report, the MERFISH
benchmark plan and report, and the metric definitions) is not. It now gets one
paragraph of its own.

Review finding #103 (ReviewPR iteration 2).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
When the forward `perm` field was removed, the comment on the surviving
`inv_perm` lost the word "inverse" and so described the forward permutation.
inv_perm maps sorted positions back to original rows. Comment-only change.

Review finding #91 (ReviewPR iteration 2).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ern crate

It was the only eval file whose header used plain `//` comments, so its
description and run command never reached the module docs. The header is now
`//!`, like its siblings. The redundant `extern crate ndarray16;` above
`use ndarray16 as nd16;` (the only one in the repository) is gone.

Review findings #95, #115 (ReviewPR iteration 2).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…PLING

`.parse().ok()` turned a malformed value such as "100x" into "unset". The
sweep then ran with the default oversampling and emitted SWEEP_ROW lines for
an experiment other than the one requested. A set but unparsable value now
panics with the raw string; leaving it unset still sweeps the default.

Review finding #57 (ReviewPR iteration 2).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
test_rq3_threshold asserted `level as u8 == 0` and `>= 1`, and
test_solver_level_parity compared u8 levels against the literal 3. Both now
compare SolverLevel variants (DenseEvd, LobpcgRegularized), as the internals
tests do. The u8 values stay where they are recorded (stdout, the
subspace_angle.txt summary).

Review findings #116, #117 (ReviewPR iteration 2).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Six call sites in three eval tests created the directory returned by
spectral_init_eval::results_dir() themselves, and test_simd_lobpcg_parity
wrapped it in a local results_dir() just to do so. results_dir() now creates
the directory, panicking with the path if it cannot. The per-site
create_dir_all calls and the wrapper are gone. Sub-directories (eigenvectors/,
rq3_threshold/) are still created where they are used.

Review finding #96 (ReviewPR iteration 2).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
MetricResult, AssessmentReport and ExperimentMetrics derived Serialize and
Deserialize, but the JSON the harness writes (accuracy_metrics.json,
parity_metrics.json) is built field by field as serde_json::Value and read back
the same way. The only users of the derives were three round-trip tests that
existed to exercise them. The derives, those tests and eval's `serde`
dependency are removed; Cargo.lock loses that one edge. serde_json stays, since
init_evidence and the tests use it.

Review finding #139 (ReviewPR iteration 2).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The block that runs one untimed solve, to prime caches and report the solver
level, was copied into bench_lobpcg_blobs5000, _merfish_10k and _merfish_100k
with only the label changed. It is now warm_up_and_report(label, laplacian,
seed, params). The stderr line is unchanged.

Review finding #93 (ReviewPR iteration 2).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
All four export tests (10k, 20k, 100k, 250k) built degrees, the inverse square
roots and the normalized Laplacian, ran the solver chain and printed
SOLVER_LEVEL inline. print_solver_level(&graph) now does that once, keeping the
comment on why the level comes from the internal seam. The output format the
Python sweep harness parses is unchanged.

Review finding #94 (ReviewPR iteration 2).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… subgraph

The accuracy report extracted each component through extract_subgraph_local,
a copy of the crate-private extract_subgraph that this PR's changes to the
original (view signature, `.expect` in place of a silent skip) never reached.
extract_subgraph is now `pub` with its preconditions documented, re-exported
from the hidden, semver-exempt `__internal` module next to embed_disconnected,
and the report calls it. Its per-component residuals are bit-identical before
and after (blobs_50, blobs_500, blobs_5000, disconnected_200).

Review finding #138 (ReviewPR iteration 2, maintainer-approved recommendation).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ature

`pub use kernels::dist_sq_avx2_looped` put an unsafe, target-feature kernel in
the trustworthiness crate's default public surface only so that
benches/dist_sq_bench.rs could call it. It is now exported only under a hidden,
semver-exempt `__bench` feature, which the bench requires. This mirrors how the
root crate gates its own AVX2 kernel behind `__internal`, and means a later
`publish = true` needs no restructuring. The library's own call goes through
`kernels::`. CI is unaffected (it builds with --all-features). A plain
`cargo bench -p trustworthiness` now skips dist_sq_bench, so its run line names
the feature.

Review finding #10 (ReviewPR iteration 2; round-1 #8), maintainer-approved recommendation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
eval/src/lib.rs is the only place where a library compiles source from another
package's tests/ directory, and nothing there said so. A two-line comment now
names the shared tests/common/ copy and points to tests/README.md. The sharing
itself stays for 0.1.0: the published crate ships none of these files, and a
fixtures-only crate is deferred until a third package needs the helpers.

Review findings #5, #15 (ReviewPR iteration 2; round-1 #23), maintainer-approved recommendation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
README.md linked the report through the research-baseline-pre-0.1 tag, which
does not exist on origin yet (404). crates.io freezes the README at publish, and
nothing protects tags from being moved or deleted. The link now uses the
full-SHA permalink of 4e22516, where the file sits at docs/ byte-identical to
research/reports/ (blob 2d14066); it returns 200. The four editable research/
references keep naming the tag.

Review finding #102 (ReviewPR iteration 2; round-1 #132/#135), maintainer-approved recommendation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… build

linfa-linalg's LOBPCG (solver levels 1-3) is built on ndarray 0.16, and this
crate and umap-rs use 0.17. So every build also compiles ndarray 0.16, rand 0.8
and thiserror 1, none of which reaches the public API. The user guide's
Requirements section now says so. Both dependencies stay for 0.1.0, because
making LOBPCG optional would break the six-level chain.

Review finding #18 (ReviewPR iteration 1), maintainer-approved recommendation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
fixtures::path_laplacian put -0.5 at L[1,0] and L[n-2,n-1], where
-1/sqrt(d_i d_j) = -1/sqrt(2). The matrix was asymmetric (max |L - L^T| = 0.21
at n = 2000), and sqrt(degree) was not in its null space, so no symmetric
eigensolver could converge on it below about 1.8e-5. It now builds every
off-diagonal from the degrees. A new test pins it to compute_degrees +
build_normalized_laplacian on make_path for n = 2, 3, 4 and 50 and checks
L · sqrt(d) = 0. The old builder fails that test. The bug predates this PR
(9a93475, #77).

With the fixture fixed, test_path_2000_warm_restart_majority_converged passes
(3/3 seeds, 6.6 s in the test profile), so its stale "times out without
optimisation" ignore is removed. It is now the only running test that fails
when the warm restarts are removed.

Round-1 observation A, maintainer-approved recommendation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…te test

test_ring_2000_warm_restart_converges asserted a residual below 1e-5 from
before #128 raised the restart iteration cap. It now ends at 1.09e-5 after four
passes (bit-identical in release and the test profile), so it was permanently
#[ignore]d and protected nothing. Its replacement,
test_ring_2000_warm_restart_meets_the_level_1_gate, asserts what the chain
needs: at least one restart, and a final residual under LOBPCG_QUALITY_THRESHOLD
(2e-5). It fails when the restarts are removed (the first pass ends at 3.25e-4)
and runs in about 3 s.

The module doc no longer blames opt-level. The iterations are chaotic at
roundoff level, so the tests pin only the chain's gates. test_path_2000_warm_restart_fires
no longer claims that a single-pass loop gives restart_count 0. restart_count
counts every unconverged pass, so that test shows only that the first pass does
not converge.

Round-1 observation B, maintainer-approved recommendation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…n first pass

eval/tests/test_warm_restart_benefit.rs built its no-restart baseline from a
hand copy of lobpcg_solve's start-up code (Chebyshev filter, initial block,
StdRng, literal ChFSI constants). Nothing tied the copy to production, and
production's filter has since been rewritten. The baseline also skipped
production's Rayleigh-Ritz step, so a row whose first pass converged could
report improvement_ratio 346359.

lobpcg_solve is now a wrapper over lobpcg_solve_with_restarts(..,
max_warm_restarts) passing the unchanged MAX_WARM_RESTARTS, so the solver
chain and both ComputeModes compute exactly what they did before. The new
function is exported through the hidden `__internal` module. The eval baseline
is the same solver with 0 restarts. The ~125-line replica and eval's
linfa-linalg and ndarray16 dev-dependencies are gone (Cargo.lock updated).
Before vs after on all 30 METRIC rows:
- restart_count and the with-restart residual are unchanged;
- all 14 rows whose first pass converges now show exactly 1.00;
- no baseline is NaN;
- the eval run takes 26 s instead of 54 s.

New tests: a unit test that 0 restarts and the default agree when the first
pass converges, and test_ring_2000_first_pass_alone_misses_the_level_1_gate,
which pins restart_count 1 and a residual above the gate when restarts are
off.

Review findings #33, #140 (ReviewPR iteration 2), maintainer-approved recommendation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Trecek and others added 3 commits November 12, 2026 15:22
…ation test

clippy 1.100 (CI's stable) rejects the index loop over report.level_elapsed
with needless_range_loop, failing the workspace clippy gate. Iterate the
array and skip the Level 0 slot instead; the same five levels are checked.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
linfa sorts eigenvalues with partial_cmp(..).expect(..), so an iterate that
turns NaN panics inside it (eigh.rs:327, "NaN values in array"). On the
aarch64 CI leg the solver-chain no-panic property test found such a graph
(n = 14, n_components = 4, self-loops, dense budget 256 bytes), and the
panic unwound through solve_eigenproblem, breaking the crate's no-panic
contract.

nd16_bridge::lobpcg, the crate's only call into linfa, now runs it under
catch_unwind and reports a panic as LobpcgOutcome::Failed, so Levels 1-3
escalate as on any other failure. The outcome mapping happens inside the
closure so it returns the small LobpcgOutcome rather than linfa's large
Result (clippy result_large_err). spectral_init's docs state that a build
with panic = "abort" aborts instead.

A unit test drives the bridge with an operator that returns NaN (it panicked
before this change), and the CI failure seed is saved in
tests/internals/no_panic.proptest-regressions so every run replays it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…art eval

test_epsilon_bridge_sweep panicked on every Linux CI leg because
lobpcg_solve returned None for epsilon_bridge_1000_bw1e0 seed=42. The
epsilon-bridge Laplacian's third eigenvalue is shared by ~2000 vectors,
so whether LOBPCG's Gram matrices stay factorable there depends on
platform rounding: the same row converges to 1.9e-14 on x86_64 WSL, macOS
and Windows. None is lobpcg_solve's documented escalation outcome (the
chain moves on to Level 2), not a defect.

The measurement now prints that row with restart_count=none and NaN
residuals (the zero-restart baseline is necessarily None too) and goes on
to the next seed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant