feat(cohomology): Dynamic Cohomological Error Correction — semantic syndrome, sparse repair, mincut containment (#669)

[ruvnet]

Summary

Implements the RFC in #669: a new mathematical primitive crates/ruvector-cohomology that ingests a dynamic heterogeneous constraint graph (a cellular sheaf with affine edge observations), decides whether a globally coherent explanation exists, localizes the irreducible contradiction, emits a deterministic signed witness, proposes a cost-aware group-sparse repair or quarantine boundary, and verifies post-intervention syndrome energy — Phases 0–5 of the RFC.

Definition-of-done loop (detect → localize → isolate → repair → verify → sign) is implemented end-to-end in mincut_bridge::run_containment and exercised in tests.

Mathematical correction (Phase 0)

• Corrected the H⁰/H¹ semantics: for a linear sheaf the zero section is always global, so nontrivial H¹ means edge data unexplainable by any vertex assignment (H¹ = C¹/im δ), not "no global section exists" (H⁰ = ker δ is the space of global sections). Fixed in prime-radiant/src/cohomology/obstruction.rs docs and recorded in ADR-272.
• Syndrome is the affine formulation from the RFC: x* = argmin ‖W^{1/2}(δx − b)‖², s = b − δx* (the weighted projection of b onto (im δ)^{⊥_W}).

What's in the crate

Module	Content
operator	Serializable LinearRestriction + RestrictionMap (identity/scale/projection/orthogonal/bounded-dense) with apply_transpose, sound norm bounds, canonical SHA-256 hashes, boundary validation before allocation — replaces closure-based maps
block_sparse	Deterministic sorted indexing/orientation; matrix-free δ, δᵀ, δᵀWδ assembled from both endpoint restrictions; dense assembly only for the oracle
affine, syndrome	Observations b, weights W, minimum-norm gauge; production path = matrix-free CG with residual certificate; reference path = column-pivoted rank-revealing Householder QR (exact)
harmonic	Harmonic basis canonicalized with QR against a hashed probe (handles degenerate subspaces); LOBPCG for nullity/spectral gap — dominant power iteration is never used
repair, solvers/admm	Group-sparse ADMM with per-edge cost c_e = α·business + β·security + γ·latency + η·reversal, protected edges immutable without explicit authorization, debias refit so the selected support cancels its contradiction exactly
dynamic, partition	Bounded cell partition, all 8 edit classes, dirty-cell tracking, cheap estimate(), exact flush() ≡ batch, epochs + deterministic edit receipts, periodic partition rebuild
transport	Exact orthogonal frame transport (x_new = Q_new Q_oldᵀ x_old, ρ ← ρRᵀ), cycle-consistency defect, coherent-negative-control guard for map updates
mincut_bridge	Syndrome→tension (τ_e = α‖s_e‖ + β·leverage + γ·uncertainty + ζ·severity), deterministic Dinic quarantine boundary (seeds vs healthy), isolate-first/repair-first policies, signed intervention receipts; optional ruvector-mincut global cut behind the mincut feature
witness	Canonical witnesses: epochs, sorted ids, operator/observation/weight hashes, gauge + solver config, quantized energies/support/harmonic coordinates, SHA-256 seal — solver float noise never enters the hash

Dependencies: serde, sha2, thiserror only (plus optional in-workspace ruvector-mincut). All solvers are hand-rolled, deterministic, and matrix-free where it matters.

Test results (29 tests, all passing; clippy-clean)

• exact_small: dense-oracle agreement ≤ 1e-10; closed-form cycle syndrome (energy = defect²/3 on a triangle); tree always coherent; H⁰ nullity via LOBPCG; oracle vs production witnesses agree
• property: zero false contradiction certificates on coherent constructions; s ⊥_W im δ; flush() ≡ batch (energy + identical witness hash); repair localizes planted contradictions; ADMM objective within 10% of exhaustive optimum
• determinism: 100 repeated runs → same witness hash; permuted edge-insertion order → same hash; canonical tie-breaking on quantized energies
• drift: orthogonal frame drift manufactures zero contradiction and leaves genuine contradiction energy invariant to 1e-9; map-update guard rejects contradiction-manufacturing maps and passes legitimate transport
• adversarial: validation bombs (NaN/dim/norm/orthogonality/allocation), protected-edge authorization, Byzantine cluster quarantined exactly along its bridge boundary, cost policy routes repair away from expensive edges

Bench snapshot (cargo bench -p ruvector-cohomology)

• local edit on 10k-vertex/15k-edge dim-8 sheaf: median 0.6µs, p99 1.4µs; estimate() ~1.4µs
• planted-cycle localization (n=500, 5 planted, redundant cycles): precision 1.00 / recall 1.00
• sparse repair: support 2–3 edges, post-repair energy ~1e-18 (debiased)
• containment loop end-to-end: ~8ms at n=200, verified receipts under both policies

Notes / follow-ups

• Per-edge weights are scalar (block-diagonal W per edge stalk is a straightforward extension)
• Statistical leverage currently uses the energy-fraction proxy
• The 100k-vertex/1M-edge performance gate needs the reference target hardware; the bench suite covers all required dimensions
• Phase 6 integrations (Ruflo memory, tool authorization, telemetry, embedding migration) build on this crate as follow-up work

Closes #669

🤖 Generated with claude-flow

https://claude.ai/code/session_017JAAahT1mcT1GahYxPDmaS

---

Generated by Claude Code