Phase 4: Integer-quantised embedding substrate — QuadranceRational mode and Padé [2,2] edge weights

[Mec-iS]

Parent macro-issue: #12
Depends on: #15 (Phase 2), #16 (Phase 3)

Goal

Provide a fully integer/rational arithmetic path through the ArrowSpace pipeline for long-running, safety-critical, or cross-platform-exact deployments such as BioChain and metamaterial simulations. Every distance computation, every edge weight, and every Laplacian matrix entry must be expressible as an exact rational number with bounded error, and must produce bit-identical results on x86-64 and Apple Silicon.

---

Motivation

Floating-point arithmetic is non-associative. Two machines computing the same Laplacian in different SIMD widths may produce eigenvectors that differ in the last few bits — which, over thousands of simulation steps or across distributed BioChain nodes, accumulates into structural drift. The QuadranceRational mode eliminates this by:

1. Storing embeddings as i16 coordinates with per-dimension scale factors.
2. Computing quadrances exactly in i64 arithmetic.
3. Approximating the heat-kernel edge weight via a Padé [2,2] rational function (no exp, no transcendentals).
4. Storing the resulting Laplacian weights as (i64, i64) numerator/denominator pairs.

---

Deliverables

1. Integer-quantised embedding format

/// A single embedding quantised to i16 per dimension.
/// True value of dimension d = coords[d] as f32 * scale[d]
pub struct QuantisedEmbedding {
    pub coords: Vec<i16>,
    pub scale: Vec<f32>,   // per-dimension, stored once per corpus
}

/// Quantise an f32 embedding to i16 using per-dimension min/max.
/// Scale is chosen so the full i16 range covers [min_d, max_d].
pub fn quantise(embedding: &[f32], dim_stats: &DimStats) -> QuantisedEmbedding;

/// Reconstruct f32 from quantised form. Reconstruction error = quantisation noise.
pub fn dequantise(q: &QuantisedEmbedding) -> Vec<f32>;

Stored in a sidecar <index_name>.quant.bin. The f32 index is kept alongside for non-rational downstream consumers.

2. quadrance_i64()

Already scaffolded in Phase 0 (surfface-geometry). Wire into the QuadranceRational dispatch path in Stage C:

// QuadranceRational kernel path
let q_raw: i64 = quadrance_i64(&coords_i, &coords_j);
// q_scaled = q_raw * (scale_factor_num / scale_factor_den)  [rational]
let weight = pade22_exp_neg_rational(q_scaled_num, q_scaled_den, sigma_sq_num, sigma_sq_den);

3. Padé [2,2] rational edge weight

The standard heat-kernel weight is w = exp(-Q/4t). The Padé [2,2] approximation:

let x = Q / 4t
w ≈ (1 - x/2 + x²/12) / (1 + x/2 + x²/12)

This is exact rational arithmetic when Q, 4t, and all intermediate values are represented as (i64, i64) fractions. Maximum relative error vs. true exp is < 0.3 % for x ≤ 2 (covers the vast majority of k-NN pairs).

/// Padé [2,2] approximation of exp(-num/den) as a rational (out_num, out_den).
/// All arithmetic in i64; panics on overflow (use checked arithmetic).
pub fn pade22_exp_neg_rational(
    num: i64, den: i64
) -> (i64, i64);

4. Rational Laplacian weight storage

/// Laplacian weight stored as exact rational.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct RationalWeight {
    pub num: i64,
    pub den: i64,
}

impl RationalWeight {
    pub fn to_f64(self) -> f64 { self.num as f64 / self.den as f64 }
}

The rational Laplacian is serialised to <index_name>.rational_lap.bin. The standard f64 Laplacian is derived via to_f64() for all existing downstream consumers.

5. Cross-platform bit-exact CI

• Add a CI matrix job that builds and runs the rational Laplacian test on both ubuntu-latest (x86-64) and macos-latest (Apple Silicon).
• The test asserts byte-for-byte identical <index_name>.rational_lap.bin output.
• Property-based test (proptest): for any pair of i16 embedding vectors, quadrance_i64 must equal round(quadrance_f32) within quantisation error.

---

Error budget

Source	Max error
i16 quantisation	± scale_d / 2 per dimension
quadrance_i64 vs true Q	0 (exact)
Padé [2,2] vs exp	< 0.3 % relative for Q/4t ≤ 2
Laplacian entry vs f64	< 0.01 % (dominated by Padé)
Eigenvalue (Phase 5)	bounded by Laplacian entry error via Weyl's theorem

---

Tests

• quantise + dequantise round-trip: max reconstruction error < max_d_range / 65535 per dimension.
• pade22_exp_neg_rational: relative error vs f64::exp < 0.3 % for x ∈ [0, 2].
• RationalWeight::to_f64 agrees with f64 Laplacian to < 0.01 % on CVE.
• Cross-platform bit-exact: CI matrix (x86-64 + Apple Silicon) on rational_lap.bin.
• Overflow safety: pade22_exp_neg_rational uses checked arithmetic and returns Err rather than panicking on overflow.

---

Acceptance criteria

• WiringMetric::QuadranceRational fully operational end-to-end.
• QuantisedEmbedding serialised to sidecar.
• Rational Laplacian serialised to sidecar.
• Cross-platform bit-exact CI job passing on both architectures.
• All previous phase regression tests still pass.
• RationalWorldlineProjector (Phase 3) updated to use exact_rational: true path via quadrance_i64.