wave pairing: 36-58% of GF/DecayGF/KNN learning samples were MISLABELLED

The audit inferred (from code) that GF/DecayGF/KNN pop the OLDEST wave on
resolution, while under bmPath bullets leave the arena in NON-FIFO order - so an
outcome could be attached to the wrong wave. It also noted that `starved=0` does
NOT rule this out. Both halves are now MEASURED.

MISPAIRING RATE (10 DrussGT fixtures, real VirtualTracker, 344k resolutions/gun):
  gun         bmPath mispair   label err      bmPoint mispair   label err
  GuessFactor     36.48%         19.39%           18.24%          7.62%
  DecayGF         36.85%         19.52%           20.57%          8.64%
  KNN             57.91%         27.63%           29.75%         11.58%
  (starved = 0 everywhere, exactly as the audit predicted)
So ~1 in 5 GF/DecayGF learning samples and ~1 in 4 KNN samples carried a WRONG
guess-factor bin. This is a material corruption of the learning signal.

FIX: the same fireTick-keyed ring scheme `tsetlin.nim`/`tm_selector.nim` already
use - `slot = (fireTick*4 + bin) mod 1024` (period 256 ticks, longer than the
~91-tick max flight), looked up by exact key. Public interfaces unchanged; added
`waveResolved`/`waveMispaired` integrity counters. AFTER: mispaired = 0 and
starved = 0, both metrics, all three guns.

EFFECT ON HIT RATE: SMALL AND NOT SIGNIFICANT. bmPath 4000 samples/gun:
  GuessFactor 23.20% -> 23.02% (-0.18pp, per-run sign-flip p=0.750)
  DecayGF     23.80% -> 24.25% (+0.45pp, p=0.625)
  KNN         18.27% -> 18.80% (+0.53pp, p=0.547)
bmPoint: +0.05 / +0.33 / -0.15pp, p = 1.00 / 0.50 / 0.50. Per-run ranges overlap
almost completely. A bullet-level z-test is anti-conservative (bullets within a
fixture share a trajectory) and its KNN p=1.9e-16 cannot be trusted given ~10
effective independent runs.
PLAIN READING: this is a CORRECTNESS fix, not a measurable hit-rate win. It
removes a 36-58% mislabelling of the learning signal; the point estimates move by
at most ~0.5pp, within run-to-run noise. Stated plainly rather than oversold.

A REGRESSION IT CAUGHT IN ITSELF (and this explains the SIGSEGV another job saw
and correctly attributed to a concurrent knn_gun.nim rewrite): the first
implementation put an inline `array[1024, KNNWave]` (~100KB) inside each gun,
which overflowed the default 8MB stack and made `test_power_selection` SIGSEGV.
Causation was proven by stashing only the three gun files (test passed), then
fixed by making the rings heap-backed `seq`. Verified: `test_power_selection`
3 PASS on the default stack, and zero inline `array[1024]` remain.

Guards: test_wave_pairing 17 (new, pure), test_gun_harness 39,
test_vbullet_metric 11, test_power_selection 3, test_adaptive_radar 41,
test_tfil_ring_weights 24, test_power_policy 26, test_ram_decision 28.
ModularBot compiles. Adds audit_wave_pairing.nim and compare_pairing.nim.

common_libs/guns/decay_gf.nim

@@ -1,6 +1,7 @@
 ## Recency-weighted GF gun: exponential decay on histogram bins.
 ## decay=0.998/tick gives ~350-tick half-life — adapts to mid-battle strategy shifts.
-## Everything else identical to guess_factor.nim, including per-power-bin wave queues.
+## Everything else identical to guess_factor.nim, including exact (fireTick,
+## powerBin)-keyed wave pairing (see guess_factor.nim for the measured FIFO defect).
 
 import std/math
 import gun_harness/gun_interface
@@ -11,29 +12,35 @@ const
   GFBins     = 31
   GFPrior    = 0.1
   DecayRate  = 0.998  # ponytail: single global decay, tune if adaptation too slow/fast
-  DecayWaveCompactAt = 64
+  DecayWaveRingSlots = 1024  # (fireTick, powerBin) ring; see guess_factor.nim
 
 type
   DWave = object
     fireX, fireY: float
     fireBearing:  float
+    fireTick:     int
+    bin:          int
+    alive:        bool
 
   DecayGFGun* = object
     bins:             array[GFBins, float]
-    # One wave queue per power bin; a resolved bullet only learns from a wave
-    # queued for its own bin (matched on bulletSpeed / bulletPower).
-    waves:            array[len(vb.PowerBins), seq[DWave]]
-    waveHead:         array[len(vb.PowerBins), int]   # O(1) pop cursor
+    # Exact (fireTick, powerBin)-keyed ring; a resolved bullet is matched to the
+    # wave it actually fired, no matter how many other shots resolved first.
+    # Heap-backed (seq): see guess_factor.nim.
+    waves:            seq[DWave]
     waveStoredTick:   array[len(vb.PowerBins), int]   # last tick a wave was queued for this bin
     vt:               VelocityTracker  # enemy velocity history (base selection)
     cachedTick:       int   # last tick bins were decayed
     wavePushes*:      int
     waveStarved*:     int
+    waveResolved*:      int
+    waveMispaired*:     int  # ring-slot collision (impossible by design)
     debugGraphics*:   bool
 
 proc initDecayGFGun*(): DecayGFGun =
   result.cachedTick = -1
   result.debugGraphics = false
+  result.waves = newSeq[DWave](DecayWaveRingSlots)
   for b in 0..<len(vb.PowerBins):
     result.waveStoredTick[b] = -1
   let center = (GFBins - 1) div 2
@@ -47,7 +54,7 @@ proc gfToIndex(gf: float): int {.inline.} =
 proc indexToGF(idx: int): float {.inline.} =
   float(idx) / float(GFBins - 1) * 2.0 - 1.0
 
-proc peakBin(g: DecayGFGun): int =
+proc peakBin*(g: DecayGFGun): int =
   var best = 0
   for i in 1..<GFBins:
     if g.bins[i] > g.bins[best]:
@@ -66,15 +73,8 @@ proc binForPower(power: float): int {.inline.} =
       return i
   -1
 
-proc takeOldestWave(g: var DecayGFGun, binIdx: int): (bool, DWave) =
-  if binIdx < 0 or g.waveHead[binIdx] >= g.waves[binIdx].len:
-    return (false, DWave())
-  result = (true, g.waves[binIdx][g.waveHead[binIdx]])
-  inc g.waveHead[binIdx]
-  if g.waveHead[binIdx] >= DecayWaveCompactAt and
-     g.waveHead[binIdx] * 2 >= g.waves[binIdx].len:
-    g.waves[binIdx] = g.waves[binIdx][g.waveHead[binIdx] .. g.waves[binIdx].high]
-    g.waveHead[binIdx] = 0
+proc waveSlot(fireTick, binIdx: int): int {.inline.} =
+  ((fireTick * len(vb.PowerBins)) + binIdx) mod DecayWaveRingSlots
 
 proc predict*(g: var DecayGFGun, state: WorldState, bulletSpeed: float): GunPrediction =
   if bulletSpeed <= 0.0:
@@ -97,7 +97,10 @@ proc predict*(g: var DecayGFGun, state: WorldState, bulletSpeed: float): GunPred
   # call for the selected bin lands on the same tick and reuses the queued wave.
   let binIdx = binForSpeed(bulletSpeed)
   if binIdx >= 0 and g.waveStoredTick[binIdx] != state.tick:
-    g.waves[binIdx].add DWave(fireX: state.selfX, fireY: state.selfY, fireBearing: f.bearing)
+    let slot = waveSlot(state.tick, binIdx)
+    g.waves[slot] = DWave(fireX: state.selfX, fireY: state.selfY,
+                          fireBearing: f.bearing, fireTick: state.tick,
+                          bin: binIdx, alive: true)
     g.waveStoredTick[binIdx] = state.tick
     inc g.wavePushes
 
@@ -113,13 +116,21 @@ proc predict*(g: var DecayGFGun, state: WorldState, bulletSpeed: float): GunPred
   )
 
 proc onResult*(g: var DecayGFGun, e: FeedbackEvent) =
-  let binIdx = binForPower(e.bulletPower)
+  let binIdx =
+    if e.powerBin >= 0 and e.powerBin < len(vb.PowerBins): e.powerBin
+    else: binForPower(e.bulletPower)
   if binIdx < 0: return
 
-  let (found, w) = g.takeOldestWave(binIdx)
-  if not found:
+  let slot = waveSlot(e.fireTick, binIdx)
+  var w = addr g.waves[slot]
+  if not w.alive:
     inc g.waveStarved
     return
+  if w.fireTick != e.fireTick:
+    inc g.waveMispaired
+    inc g.waveStarved
+    return
+  inc g.waveResolved
 
   let speed  = bulletSpeed(e.bulletPower)
   let mea    = arcsin(clamp(8.0 / speed, -1.0, 1.0))
@@ -136,3 +147,5 @@ proc onResult*(g: var DecayGFGun, e: FeedbackEvent) =
   for i in 0..<GFBins:
     let d = abs(i - centerIdx)
     g.bins[i] += 1.0 / float(1 + d)
+
+  w.alive = false