fix(mps): harden SRC adaptive stopping rule at extreme scale

[ultimatile]

Summary

The adaptive stopping rule of successive randomized compression (SRC) degraded toward false convergence at representational extremes: a saturated accumulated sketch norm made err <= cutoff * inf accept any finite estimate at the first round, overflowed R^-1 row norms collapsed the leave-one-out estimate to zero through recip(), and a panel column norm past f64::MAX produced a non-finite QR diagonal that the rank test misread as exact rank deficiency (inf <= inf tolerance) — each returning a finite but uncertified state as a success. This PR hardens all three regimes so every degradation now points toward growth, a correct convergence, or an explicit error. Closes #483.

Changes

• ariadnetor-core: the scale-safe accumulator behind scale_safe_norm is now public (NormAccumulator with push / push_scalar / scale / sumsq), exposing the dlassq-style (scale, sumsq) representation that stays exact past the point where the finished norm saturates. push_scalar enters elements component-wise, because a complex modulus can overflow with finite components.
• ariadnetor-linalg: IncrementalQr::append scans the candidate diagonal before the rank test and reports a new terminating QrAppendOutcome::NonFinite { diagnostic } instead of letting inf masquerade as rank deficiency or NaN as full rank; the inverse update is suppressed and into_orthonormal_q's guarantee is scoped accordingly.
• ariadnetor-mps: the sweep accumulates the sketch norm in the (scale, sumsq) form, evaluates the stopping comparison in the log domain (with p the current sketch width, no product of cutoff, scale, and sqrt(sumsq / p) is ever formed, so no operand ordering can saturate an intermediate), treats an uninformative estimator — non-finite row norms or a saturated reciprocal norm — as "not converged" (leave_one_out_estimate now returns Option), and surfaces a degenerated QR factor in adaptive mode as ApplyError::NonFinite carrying the observed diagonal.

Impact

• apply_successive_randomized_dense: adaptive-path behavior only; public signature and dispatch unchanged. Fixed mode never claims the cutoff guarantee, ignores the append outcome as before, and stays covered by the elementwise result-boundary scans (check_finite on panels and assembled sites).
• QrAppendOutcome gains a variant and drops Eq (the diagnostic payload is f64); the workspace has no exhaustive matches.
• Existing consumers of scale_safe_norm / combine_norms are behaviorally unchanged.

Test plan

• Scale invariance at norm saturation: one site scaled into the window where the accumulated sketch norm exceeds f64::MAX while every per-round panel norm stays representable; bond selection must match the unit-scale run (fails before the fix with the bond stuck at the saturating round).
• Panel-norm overflow surfaces ApplyError::NonFinite instead of a bond-stuck Ok; fixed mode driven through the same degenerated factor is tolerated and the overflowed weight is caught by the check_finite scan over the assembled sites — the test asserts the detection site, which distinguishes the documented tolerance (error at the assembled-site scan) from a hypothetical fixed-mode error at the append itself.
• Unit level: NormAccumulator representation identity, saturation, and modulus-overflow survival; leave_one_out_estimate Option contract including the all-finite-but-saturated reciprocal case; IncrementalQr non-finite outcomes for a first-append overflow column and a projected overflow block, with termination and inverse-state hygiene.
• cargo test --workspace, cargo clippy --workspace --all-targets (warnings denied), and cargo doc --no-deps on the touched crates: all clean.

Notes

• The estimator-collapse regime (R_ii inside [rank tolerance, 1/MAX)) is covered at the Option-contract unit level; an end-to-end fixture proved unreachable for the existing integration fixtures without magic RNG-tied magnitudes.
• Fixed mode can still return a state whose degenerated single-append factor passed the elementwise scans while its canonical-form label claims right-orthogonality the site may no longer satisfy; this predates the change (the same input previously took the rank-deficient path to the same result) and is documented at the NonFinite handling in apply_successive_randomized_dense — tracked by SRC fixed mode keeps a right-orthogonality label a degenerated QR factor may violate #485.

Summary by CodeRabbit

• New Features

  • Exposed reusable norm accumulation utilities, including support for real and complex values.
  • Added explicit reporting for non-finite QR results caused by numerical overflow.

• Bug Fixes

  • Improved adaptive randomized processing for overflow and saturated norm calculations.
  • Prevented invalid convergence decisions when numerical diagnostics are unavailable.
  • Clarified error reporting for non-finite quantities and QR breakdowns.

• Documentation

  • Updated API documentation to describe non-finite outcomes, termination behavior, and affected results.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 73697f26-e150-415e-acc5-2d3d176f3d39

📥 Commits

Reviewing files that changed from the base of the PR and between fdb7383 and d0c3810.

📒 Files selected for processing (8)

• crates/ariadnetor-core/src/lib.rs
• crates/ariadnetor-core/src/norm.rs
• crates/ariadnetor-linalg/src/incremental_qr.rs
• crates/ariadnetor-linalg/src/incremental_qr/tests.rs
• crates/ariadnetor-mps/src/apply/successive_randomized.rs
• crates/ariadnetor-mps/src/apply/successive_randomized/tests.rs
• crates/ariadnetor-mps/src/types.rs
• crates/ariadnetor-mps/tests/mps/apply_successive_randomized.rs

---

📝 Walkthrough

Walkthrough

The changes expose NormAccumulator, add non-finite termination reporting to incremental QR, and harden successive randomized compression against norm saturation, uninformative inverse-row norms, and QR degeneration. Documentation and regression tests cover adaptive and fixed-mode behavior.

Changes

SRC numerical robustness

Layer / File(s)	Summary
Public scale-safe norm accumulator crates/ariadnetor-core/src/lib.rs, crates/ariadnetor-core/src/norm.rs	NormAccumulator and its operations are publicly exported, scalar components can be accumulated separately, and saturation behavior is tested.
Non-finite incremental QR outcome crates/ariadnetor-linalg/src/incremental_qr.rs, crates/ariadnetor-linalg/src/incremental_qr/tests.rs	Non-finite candidate diagonals now terminate the factorization, suppress inverse updates, return diagnostics, and are covered by overflow tests.
Adaptive SRC validation and convergence crates/ariadnetor-mps/src/apply/successive_randomized.rs, crates/ariadnetor-mps/src/apply/successive_randomized/tests.rs, crates/ariadnetor-mps/src/types.rs, crates/ariadnetor-mps/tests/mps/apply_successive_randomized.rs	Adaptive SRC uses scale-safe accumulation and log-domain convergence checks, rejects uninformative estimates, surfaces QR degeneration, and tests scale saturation plus fixed-mode handling.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Apply as apply_successive_randomized_dense
  participant Norm as NormAccumulator
  participant QR as IncrementalQr
  participant Result as ApplyError
  Apply->>Norm: accumulate panel scalars
  Apply->>QR: append panel
  QR-->>Apply: QR outcome and inverse-row norms
  Apply->>Norm: read scale and sumsq
  Apply->>Apply: evaluate adaptive convergence
  Apply-->>Result: report NonFinite when QR certification degenerates

Loading

Possibly related issues

• Migrate truncation-error accumulations onto the scale-safe kernel #480 — The shared NormAccumulator introduced here supports the scale-safe norm accumulation objective described by the issue.
• SRC fixed mode keeps a right-orthogonality label a degenerated QR factor may violate #485 — The QR NonFinite outcome and fixed-mode downstream handling directly overlap with this change.

Possibly related PRs

• ultimatile/ariadnetor#477 — Shares the SRC incremental-QR workflow extended by the new NonFinite outcome.
• ultimatile/ariadnetor#479 — Shares changes to QR inverse-row norms and SRC adaptive estimation.

Poem

A rabbit saw norms climb high,
Then taught their sums to safely fly.
QR found infinities in the hay,
So growth was stopped without delay.
Adaptive paths now test with care—
“No false convergence,” twitching there!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: hardening SRC adaptive stopping at extreme numeric scales.
Linked Issues check	✅ Passed	The PR addresses #483 by preventing false convergence from norm saturation and overflowed row norms, while also handling QR diagonal overflow.
Out of Scope Changes check	✅ Passed	The changes stay within the SRC stability work; the public exports, QR handling, and tests all support the stated objectives.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/483-src-stopping-rule-saturation

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}