Module contrastive 

Contrastive search — find the rows whose solution diverged most from a baseline. ADR-001 roadmap item #6.

The architectural shape RuView, Cognitum, and Ruflo’s inner loops actually want: not “give me the whole solution vector”, but “tell me which entries crossed a boundary big enough to wake an agent”. This is the change-driven activation primitive the ADR’s thesis turns on.

API

let top_k = find_anomalous_rows(&baseline, &current, 5);
for AnomalyRow { row, baseline, current, anomaly } in top_k {
    println!("row {row}: was {baseline}, now {current} (Δ={anomaly})");
}

Complexity

The current implementation is O(n log k) — one pass over the solution vectors with a k-sized min-heap. That’s already useful (avoids O(n log n) of a full sort) but not yet the O(k · log n) the ADR promised. The follow-up will land a direct path that computes only the top-k entries of the new solution via the sublinear- Neumann single-entry primitive, without ever materialising the full current solution. Tracked as a // TODO(ADR-001 #6 phase 2): in the source.

Structs

AnomalyRow

One row’s anomaly report.

ContrastiveSolveOnChangeOp

Marker type with a Complexity impl for contrastive_solve_on_change.

ContrastiveSolveOnChangeSublinearOp

Op marker for the SubLinear orchestrator variant.

FindAnomalousRowsOp

Marker type with a Complexity impl for find_anomalous_rows.

Functions

contrastive_solve_on_change

One-shot contrastive solve: given a previous solution + a sparse RHS delta, return the top-k rows whose value diverged most under the new RHS, without scanning the full solution vector.

contrastive_solve_on_change_sublinear

SubLinear sibling of contrastive_solve_on_change: skips the inner solve_on_change and uses per-entry sublinear Neumann queries scoped to the closure of the delta’s support. End-to-end SubLinear in n for sparse DD matrices with bounded depth — the phase-2B realisation of the ADR-001 contract.

contrastive_solve_on_change_sublinear_auto

Magic-number-free sibling of contrastive_solve_on_change_sublinear. Takes only (matrix, prev, b_new, delta, tolerance, k) and auto-tunes both closure_depth and max_terms from the matrix’s coherence via crate::coherence::optimal_neumann_terms.

contrastive_solve_on_change_sublinear_auto_with_rho

Tightest-bound contrastive sibling: takes a caller-supplied spectral-radius rho (e.g. from crate::coherence::approximate_spectral_radius) and uses it for tighter Neumann-depth tuning than the loose (1 - coherence) bound. See crate::incremental::solve_on_change_sublinear_auto_with_rho for the non-contrastive sibling.

find_anomalous_rows

Return the k rows whose current value diverged most from baseline.

find_anomalous_rows_in_subset

Top-k variant constrained to a caller-supplied candidate set. Skips the rest of the solution vector entirely.

find_rows_above_threshold

Return only the rows whose anomaly score exceeds threshold. Useful as the boundary-crossing primitive for change-driven activation: an agent stays asleep until at least one entry crosses the threshold.