Phase 2: TQF-geodesic wiring — Triple Quad Formula pre-wiring filter and GeodesicIndex

[Mec-iS]

Parent macro-issue: #12
Depends on: #14 (Phase 1)

Goal

Add a structural pre-wiring stage (Stage C₀) that certifies edges as rational geodesics using the Triple Quad Formula (TQF), and build a GeodesicIndex of certified triples for downstream use by Phases 3 and 5.

---

Background: The Triple Quad Formula

For three collinear points with pairwise quadrances Q₁, Q₂, Q₃, the TQF states:

(Q₁ + Q₂ + Q₃)² = 2(Q₁² + Q₂² + Q₃²)

This is an algebraically exact collinearity test — no trigonometry, no sqrt, no floating-point transcendentals. It generalises to arbitrary dimension and works over any field, including rational numbers.

In the ArrowSpace context, a triple of centroids (i, j, k) satisfying TQF means the three centroids lie on a straight geodesic in the feature manifold — a rationally-certified low-curvature path. Edges along such paths have maximally stable spectral weights and carry the strongest Dirichlet energy signal.

---

New Stage C₀: apply_tqf_filter()

Algorithm (per directed edge i → j)

1. Find the shared nearest neighbour k of both i and j (already computed during k-NN build).
2. Compute:
   • Q₁ = quadrance(μ_i, μ_j)
   • Q₂ = quadrance(μ_j, μ_k)
   • Q₃ = quadrance(μ_i, μ_k)
3. Evaluate TQF residual: R = |(Q₁+Q₂+Q₃)² − 2(Q₁²+Q₂²+Q₃²)|
4. If R < eps: tag edge geodesic: true, store (i, j, k, Q₁, Q₂, Q₃) in GeodesicIndex.
5. Otherwise: edge is retained in the graph but tagged geodesic: false; weight unchanged.

The filter never removes edges — it only annotates them. This preserves Laplacian connectivity for all downstream stages.

pub fn apply_tqf_filter(
    graph: &mut WiringGraph,
    centroids: &CentroidMatrix,
    eps: f64,
) -> GeodesicIndex;

eps selection

Provide a helper:

/// Adaptive eps: eps = median(R) * 0.1 over all edge triples.
/// Gives ~10 % of the typical residual as the collinearity threshold.
pub fn estimate_tqf_eps(graph: &WiringGraph, centroids: &CentroidMatrix) -> f64;

---

CentroidState change

Add tqf_residual: f32 to CentroidState (Stage B Kalman output). This is the minimum TQF residual of all triples involving this centroid — a per-node curvature proxy computed during MST smoothing:

pub struct CentroidState {
    // ... existing fields ...
    /// Minimum TQF residual over all edge triples touching this centroid.
    /// 0.0 = lies on at least one certified geodesic.
    /// High value = all local paths are curved.
    pub tqf_residual: f32,
}

---

GeodesicIndex struct

/// A sorted, serialisable set of TQF-certified edge triples.
/// Versioned alongside the ArrowSpace index.
pub struct GeodesicIndex {
    /// Certified triples: (centroid_i, centroid_j, centroid_k, Q1, Q2, Q3)
    pub triples: Vec<GeodesicTriple>,
    /// eps used to certify this index
    pub eps: f64,
    /// WiringMetric used — must be QuadranceGaussian or QuadranceRational
    pub metric: WiringMetric,
    pub version: u32,
}

Serialises to a sidecar file <index_name>.geodesic.bin using the existing bincode convention.

---

Pipeline config

Add WiringMode to ArrowSpaceConfig:

pub enum WiringMode {
    /// Standard quadrance wiring. No TQF annotation. DEFAULT.
    Standard,
    /// Standard wiring + TQF annotation pass. Builds GeodesicIndex.
    /// Required by Phase 3 projectors and Phase 5 SpectralQuant.
    TqfAnnotated { eps: Option<f64> },  // None = auto via estimate_tqf_eps()
}

---

Tests

• Lattice test: On a regular 2D integer lattice input (TQF exactly satisfied), apply_tqf_filter() must certify 100 % of collinear triples at eps = 0.0.
• Random test: On uniformly random points in R², the geodesic fraction must be statistically low (< 5 % of triples at eps = 1e-6).
• CVE integration test: GeodesicIndex builds without panic; certified-geodesic fraction is logged; tqf_residual distribution is right-skewed.
• Round-trip test: Serialise and deserialise GeodesicIndex; all fields bit-exact.
• eps=None test: estimate_tqf_eps() returns a positive finite value on CVE.

---

Acceptance criteria

• apply_tqf_filter() implemented and passing all tests above.
• tqf_residual field on CentroidState populated during Stage B.
• GeodesicIndex serialises to <name>.geodesic.bin.
• WiringMode::TqfAnnotated plumbed through ArrowSpaceConfig.
• Overhead of the TQF annotation pass < 15 % of Stage C total wall time on CVE.
• All Phase 0 and Phase 1 regression tests still pass.