README.md

# rob-rbyte-v3

Residue router for the SAIR Modular Arithmetic Challenge. Entry class
`model.ResidueRouterV1`, output base 256. Covers tiers 1-4.

Routing is by the size of `p`. Operands are reduced mod p inside
`predict_digits` (the two-argument normalization both reference models use: a
with p, then b with p, never all three).

- **Tiers 1-2 (p <= 251):** the v1 residue specialist. Each operand residue is
  embedded through a shared per-(prime, residue) table; the two vectors are
  added (a discrete-log inductive bias: logs add under multiplication); a
  residual MLP trunk transforms the sum; logits score against a per-(prime,
  class) output table masked to the p classes of the current prime. The answer
  is one base-256 digit. ~2.9M parameters.

- **Tier 3 (251 < p < 65536):** two trained shared local-rule step nets
  composed through fixed wiring. After reduction x, y are 16-bit residues. A
  MULTIPLY step learns the shared carry rule over the carry-save column sums
  and, composed closed-loop through a fixed parity readout, emits the exact
  32-bit product t = x*y. A REDUCTION step learns the shared per-nibble
  borrow/compare rule and, composed through fixed restoring-division wiring,
  emits r = t mod p in [0, p). Plain GELU MLPs, width 96, depth 3, ~20k params
  each.

- **Tier 4 (65536 <= p < 2^32):** the SAME two rules at 32-bit geometry. After
  reduction x, y are 32-bit residues. The MULTIPLY step learns the carry rule
  over the 63 carry-save columns (sum <= 32, carry <= 31) and, composed through
  the parity readout widened to 64 bits, emits the 64-bit product as BITS (the
  product overflows signed int64, so it is never materialized as an integer).
  The REDUCTION step is the identical 512-case per-nibble borrow rule, composed
  over 64 division positions x 9 nibbles, emitting r = t mod p in [0, p). The
  multiply step is GELU MLP width 128 depth 3 (~35k params), the reduction step
  width 96 depth 3 (~20k params). The two techniques flagged for tier 4 shape
  training: reciprocal-operand framing (each triple traced as both (x,y) and
  (y,x)) and Charton-Kempe two-set sampling (a small repeated set + a large
  fresh set).

- **Tiers 5-10 (p >= 2^32):** outside the trained regime; returns [0].

## Provenance

In every tier the carry-save column sums, parity readout, bit shifts,
restoring-division topology, and ge-from-final-borrow decision are fixed
scaffold. The two nontrivial decisions, the carry rule and the borrow/compare
rule, reside in trained MLP parameters (separate nets per tier-3 / tier-4
geometry). Randomizing a step net collapses its tier:

- tier 3 random-weight pipeline: exact = 0.000000; trained mul + random red =
  0.002196 (chance). See `t3_collapse_receipt.json`.
- tier 4 random-weight pipeline: exact = 0.000000; trained mul + random red =
  0.000000. See `t4_collapse_receipt.json`.

Both tier-3 and tier-4 multiply/reduction step nets reach per-case exactness
1.0 on their full enumerated domains (tier 3: mul 272-case / red 512-case; tier
4: mul 1056-case / red 512-case), so the composed pipelines are exact by the
fixed wiring. Five 17-32-bit primes are held out by identity for tier 4 and
appear in no training trace; the composed tier-4 pipeline is exact (1.0) on all
five on uniform residue pairs and the four edge cases (`t4_collapse_receipt.json`
and `experiments/013-t4-lifted-step/`). The tier-3 held-out primes (33343,
45137, 54497, 55061, 62071) are likewise exact.

## Public benchmark (1100 problems, fixed seed)

Run through the official pipeline (`modchallenge evaluate ./submission/rob-rbyte-v3
--total 1100`); the per-tier accuracy and `highest_tier_above_90` come from the
official decoder, not an internal tensor check:

- overall_accuracy = 0.412
- highest_tier_above_90 = 4
- deterministic = True (two full runs bit-identical per tier)
- tier 1 = 1.000, tier 2 = 1.000, tier 3 = 1.000, tier 4 = 1.000
- tier-4 inference 0.1s for 100 problems (300s budget); full eval ~10s

See `EVALS.log` and `eval_official_1100.json` for the full breakdown and
`manifest.json` for the model and training descriptions.

Static check: clean. No sympy / gmpy2 / eval / exec / subprocess on any path.

## Files

`model.py` (architectures + routing + fixed wiring), `weights.safetensors`
(tier-1/2 specialist), `t3_mul.safetensors` / `t3_red.safetensors` (tier-3 step
nets), `t4_mul.safetensors` / `t4_red.safetensors` (tier-4 step nets),
`config.json` (per-specialist hyperparameters), `manifest.json`,
`t3_collapse_receipt.json`, `t4_collapse_receipt.json`, `EVALS.log`,
`eval_official_1100.json`.