fix: audit-remediation — address all 15 code review findings

[OldCrow]

Summary

Implements all 15 findings from the June 2026 independent code review of the v3.8.0 → v4.0.0 diff.

---

Findings addressed

Critical

• F1 — Data race in updateCache(): Added mutable std::mutex cache_mutex_ with double-checked locking to FullCovarianceGaussianDistribution and DiagonalGaussianDistribution. Explicit copy/move operations defined (std::mutex is non-copyable/non-movable).
• F2 — Null dereference in BasicHmm<ObservationVectorView>::getDistribution(): Both overloads now throw std::runtime_error with a descriptive message instead of unconditionally dereferencing null emission slots.

High

• F3 — Positional JSON parsing: from_json and from_json_mv now validate each key name before consuming its value. Reordered JSON is rejected with a clear error.
• F4 — VonMises CDF at −π: Changed x <= −π to x < −π in wrap_angle so getCumulativeProbability(−π) returns ~0.0 rather than ~1.0.
• F5 — Regularisation accumulation in setCovariance: cov_ now stores the unregularised matrix; reg_*I is applied only to a scratch copy for Cholesky factorisation. getCovariance() round-trips are idempotent.
• F6 — VonMises weighted fit() sumW inflation: sumW is now accumulated inside the finite-data filter loop, not over all weights.
• F7 — NaN pseudo_count passes guard: Changed if (c < 0.0) to if (!(c >= 0.0)) in both the constructor and setPseudoCount.

Medium

• F8 — k-means M < K produces duplicate centroids: seed_kmeanspp now throws std::invalid_argument when pts.size() < K.
• F9 — Ragged data in fit(): Both fit() overloads in FullCovarianceGaussianDistribution and DiagonalGaussianDistribution now check per-observation dimensionality.
• F10 — convergenceWindow <= 1 premature convergence: BasicViterbiTrainer constructors and setConfig throw when convergenceWindow < 2.

Low

• F11 — StudentTDistribution::getCumulativeProbability(NaN): Returns 0.0, consistent with getProbability(NaN).
• F12 — dimensions not cross-validated in from_json_mv: The manifest dimensions field is now cross-checked against each distribution's getDimension().
• F13 — Unbounded dim in distribution from_json: FullCovarianceGaussianDistribution::from_json and DiagonalGaussianDistribution::from_json now bound dim to [1, 1024].
• F14 — MAP discrete smoothing unnormalised: apply_discrete_smoothing re-normalises after the smoothing pass.
• F15 — Dead code in lloyd_update: Empty clusters now retain their previous centroid instead of collapsing to the zero vector.

---

Tests

• Updated 2 existing tests that asserted old broken behaviour (StudentT CDF NaN, FullCovariance default log_det).
• Added 24 new regression tests across 7 test files covering all previously-untested fix paths.

All 47 tests pass (0 failures).

---

Conversation: https://app.warp.dev/conversation/411a43b6-94f9-42bf-bc37-3987216f6798

Co-Authored-By: Oz [email protected]