FOiL Hot-Path Mersenne Plan — Certified Strength Reductions

Companion to open-source/gnosis-math/Gnosis/FoilMersenneHotPath.lean (and GriessAeonMeshDescent.lean / MonsterUnresolvedSignal.lean, which prove the band geometry these rewrites rely on). Every rewrite below is backed by a named Lean theorem, so each is a certified-equivalent refactor: the only open question per item is profitability on target hardware, which the existing benches (bench-foil-entropy-ramp, bench-hope-jar-e8, bench-foil-loser-policy) can answer.

The structural fact

The Griess band decomposition 196884 = 300 + 98280 + 98304 (proved: MonsterUnresolvedSignal.griess_band_decomposition) has Mersenne/power-of-two shape (proved: GriessAeonMeshDescent.bands_mersenne_twins, griess_dim_mersenne_form):

Every modulus FOiL touches on its critical path is a Mersenne number or a power of two. Hence:

1. Division-free Fano routing in pump_entropy

Where: polyglot/src/foil_runtime.rs (pump_entropy, query hash → Fano point), distributed-inference/src/mycelial_fano_router.rs.

Change: replace hash % 7 with the Mersenne fold (FoilMersenneHotPath.fano_mod7_fold):

#[inline(always)]
fn fano_point(h: u64) -> u8 {
    // x % 7 == ((x >> 3) + (x & 7)) % 7  — Lean: fano_mod7_fold
    let mut x = h;
    while x >= 7 { x = (x >> 3) + (x & 7); }   // each step certified
    (if x == 7 { 0 } else { x }) as u8         // fold can land on 7 ≡ 0
}

For a 64-bit hash this converges in ≲ 21 shift-add steps worst case and ~3 typical, with no div µop. On hot loops that route every predicted entropy key, removing the 20–40-cycle integer division is the win. (LLVM already strength-reduces constant % 7 to multiply-shift; the fold variant matters on ports saturated by multiplies — measure both, the theorem covers the fold variant, the multiplier variant is compiler-trusted.)

2. Packed u32 keys replacing format! string keys

Where: distributed-inference/src/gnosis_foil.rs (rf_fibonacci_shape_key builds a String per lookup; cache compares strings; async loser queue is keyed by it).

Change: address every Monster column / shape key as (band: 2 bits, block: 13 bits, phase: 4 bits) packed into one word:

#[inline(always)]
fn pack_key(band: u32, block: u32, phase: u32) -> u32 {
    (band << 17) | (block << 4) | phase
}

Certified by packKey_unpack_phase / packKey_unpack_block / packKey_unpack_band (exact roundtrip given band < 4, block < 2^13, phase < 16) and packKey_lt (fits in 19 bits — a u32 with 13 bits of headroom for the RF shape fields, or the low word of a 64-bit key with the Fibonacci index n in the high word). Field widths are not guesses: the largest arena is the frame band's exactly 2^13 blocks (frame_arena_geometry), bands count 3, Aeon phase < 12 < 16.

Effect: no heap allocation per lookup, no format!, hash = identity or one multiply (FxHash on u64), equality = one cmp instead of memcmp. This is typically the single largest win available when a cache key is currently a formatted string.

3. Mask-indexed frame arena

Where: any indexing into the Hope-Jar / carrier arenas (gnosis_foil.rs, hope_jar paths).

Change: lay the carrier out band-major (Sym² | pair | frame). The frame arena has exactly 2^13 Aeon blocks, so:

let blk  = k & 8191;   // k % 8192  — Lean: frame_arena_mask
let page = k >> 13;    // k / 8192  — Lean: frame_arena_shift

Seams sit at blocks 25 and 8215 (frame_arena_geometry), so band dispatch is two unsigned compares. For hashing into the fused pair+frame carrier, % 8191 (prime! — good distribution) reduces by fold instead of division (griess_mersenne_mod_fold), making "mod by a prime" cost shift-add.

4. No % 12 on the hot path at all

Where: foil_admission_gate.rs (resident_gnosis_clock_phase_of_nat_tick: tick % 12), fano_runtime.rs Aeon gates.

Change: store columns/ticks as (block, phase) pairs from ingest — aeon_split_roundtrip proves the split is lossless and the phase bounded — and increment the phase with a compare-and-reset instead of re-deriving it with % 12:

phase += 1; if phase == 12 { phase = 0; block += 1; }

The mesh-blindness results (GriessAeonMeshDescent. mesh_cannot_resolve_griess_bands) also license a free early-out: any two columns with equal phase produce monsterPairAeonGate = none, so the gate should test phase_a == phase_b first (one compare, no allocation) and only then build the [i, j] label — and a 12×12 LUT of 66 NonZeroU8 gate ranks replaces the Option<Vec<usize>> allocation entirely (144-byte table, L1-resident).

5. Band-aligned sharding is free

bands_tile_aeon_blocks + band_boundaries_alias_to_phase_zero: the three Griess bands tile whole Aeon blocks and their seams all sit on phase 0. Sharding the 196884-column carrier at columns 300 and 98580 therefore never splits a phase block, and seam-pair gates are provably none — zero cross-shard gate traffic at the seams. If the loser-cache workers (FOIL_ASYNC_LOSER_WORKERS) are ever sharded by band, this is the layout to use.

Bench checklist

1. cargo bench baseline on bench-foil-entropy-ramp + bench-hope-jar-e8.
2. Land #2 (packed keys) first — biggest expected delta, easiest A/B.
3. #4's early-out + LUT next (allocation removal on the gate path).
4. #1/#3 are micro-wins; accept only if the ramp bench moves.

Theorem IDs for the certificate trail: FoilMersenneHotPath.mersenne_mod_fold, .fano_mod7_fold, .pair_band_mod_fold, .griess_mersenne_mod_fold, .frame_arena_mask, .frame_arena_shift, .frame_arena_geometry, .packKey_unpack_phase, .packKey_unpack_block, .packKey_unpack_band, .packKey_lt, .aeon_split_roundtrip, .foil_hot_path_certified.

Implementation ledger

The certified primitives live in distributed-inference/src/foil_mersenne_hot_path.rs (one function per theorem, equivalence-tested against the div/%/format! forms they replace). Wired in:

1. Fano fold — fano_point_of_hash (iterated fano_mod7_fold) is available and equivalence-tested, but the router hot path keeps % 7: the A/B below measured the compiler's multiply-shift at ~2 ns vs ~17 ns for the fold on an idle multiplier port, exactly the caveat §1 flagged. The fold remains the certified variant for multiplier-saturated ports.
2. Packed keys — gnosis_foil::rf_fibonacci_packed_shape_key / rf_fibonacci_packed_dynamic_shape_key: the format! identity packed into disjoint bit fields of one word (equality coincides with string-key equality, no allocation). The Monster-column address is foil_mersenne_hot_path::monster_column_foil_key (ingest split + two seam compares + pack_foil_key), injective across all 196884 columns. The serialized RfFibonacciSmartSkipCache.shape_key string field is kept for wire compatibility; the match path already compares integers.
3. Mask-indexed arenas — frame_arena_block/frame_arena_page primitives; FanoMycelialRouteCache rounds its monster route arenas to powers of two and selects slots with AND instead of %.
4. No % 12 on the hot path — fano_runtime:: monster_phase_pair_to_aeon_gate takes already-split phases (equal-phase early-out is the first compare); the three monster routing fns no longer re-derive phases through monster_pair_to_aeon_gate. The foil_admission_gate carrier key is a 144-byte 12×12 LUT of nonzero gate ranks (diagonal 0 = the certified none), and ResidentGnosisClock / AeonPhaseClock advance (block, phase) by compare-and-reset after a single ingest split.
5. Band-aligned sharding — seam constants exported (SYM_SQUARE_SEAM_*, PAIR_FRAME_SEAM_*, both column seams phase 0), monster_band_of_block is the two-compare dispatch.

Everything above is certified meaning-preserving and unit-tested for equivalence.

Measured (x86-64 dev container, rustc -O, 20M-op A/B per primitive)

The §1 caveat was right: LLVM strength-reduces every constant modulus to multiply-shift, so the fold only pays when multiply ports are saturated. The wins are exactly where the plan predicted — the allocation-free packed key first, then the allocation/loop removals on the gate path, then the runtime-length mask.