fix(guns): per-bin wave queues unbreak GF/DecayGF/KNN learning; fix vbullet drops

Wave queues (guess_factor, decay_gf, knn_gun): predict() stored ONE wave
per tick while onResult() popped one per resolved bullet (~4/tick), so the
queue drained to empty within a few dozen ticks, ~3 of every 4 resolutions
returned without learning, and the survivor paired with a same-tick wave
(bearingDelta ~= 0) pinning the histogram at centre. PROOF: GF.vHits ==
HeadOn.vHits and DecayGF.vHits == HeadOn.vHits byte-for-byte in every one
of 50 rounds — the guns had degenerated to HeadOn.

Now each gun keeps a per-bin FIFO with an O(1) head cursor. At most one
push per (tick, bin) so the fire site's 5th predict() call is a no-op, and
onResult pops the oldest wave of its OWN bin via e.bulletPower. Aiming
math untouched (it was already correct: 0 deg = East, CCW+).

maxBullets 2048 -> 8192: the rack spawns 52 bullets/tick so the ring wrapped
every ~39 ticks while a long power-3 shot needs ~90, silently discarding
unresolved bullets and biasing every measured hit rate by range. Added a
droppedBullets counter so a future overflow is measurable, and wavePushes/
waveStarved counters on the three guns. After the fix: vDropped = 0 and
vStarved = 0 across all 48 recorded rounds.

fitnessFor is now exported, deterministic (enemies iterated in ascending id
order) and shared by the selector and the stats dump, replacing a hand-rolled
merge in ModularBot that never advanced its window head.

Round lines gain additive keys: vDropped, vStarved.

common_libs/gun_harness/virtual_bullets.nim

@@ -6,12 +6,16 @@
 import std/math
 import std/tables
 import std/random
+import std/algorithm
 import gun_interface
 
 const
   PowerBins*    = [1.0, 1.5, 2.0, 3.0]  ## 4 bins; ponytail: fixed array, add runtime config if needed
   WindowSize*   = 100                     ## rolling window ticks for fitness
-  MaxBullets*   = 2048                    ## hard cap; ponytail: ring buffer, resize if more guns added
+  MaxBullets*   = 8192                    ## hard cap; ring buffer. 52 spawns/tick and a
+                                          ## full-map long shot (~90 ticks) need ~4700 slots;
+                                          ## 8192 wraps only after ~157 ticks. Each VirtualBullet
+                                          ## is 88 bytes, so this array costs ~704 KiB.
   MinHitRate*          = 0.40   ## 40% threshold for acceptable power selection
   MinObsBeforeCompete* = 50    ## min observations before a gun×bin enters competition
   TieMargin*           = 0.02  ## guns within this hit-rate margin of best are tied
@@ -45,6 +49,7 @@ type
     head*:      int  ## ring buffer head
     numGuns*:   int
     fitness*:   Table[int, seq[GunFitness]]  ## keyed by enemy bot ID, indexed by GunId
+    droppedBullets*: int  ## unresolved bullets clobbered by the ring buffer (should stay 0)
 
 proc initTracker*(numGuns: int): VirtualTracker =
   result.numGuns = numGuns
@@ -75,6 +80,11 @@ proc spawnBullets*(t: var VirtualTracker, gunId: GunId,
     let pred    = predictions[binIdx]
     let fireDist = hypot(pred.x - state.selfX, pred.y - state.selfY)
     let slot    = t.head mod MaxBullets
+    # Measurement integrity: if the slot we are about to overwrite still holds an
+    # unresolved bullet, that bullet will never be scored. Count it instead of
+    # silently dropping it (non-zero after a battle means MaxBullets is too small).
+    if t.bullets[slot].active:
+      inc t.droppedBullets
     t.bullets[slot] = VirtualBullet(
       gunId:      gunId,
       powerBin:   binIdx,
@@ -140,20 +150,30 @@ proc tickBullets*(t: var VirtualTracker, state: WorldState,
     onResolved(b.gunId, b.powerBin, fe)
     b.active = false
 
-proc fitnessFor(t: VirtualTracker, targetId: int): seq[GunFitness] =
+proc fitnessFor*(t: VirtualTracker, targetId: int): seq[GunFitness] =
   ## Returns fitness seq for targetId, or merges all enemies as fallback.
-  ## ponytail: merge is O(enemies*guns*bins), fine for small counts
+  ##
+  ## The fallback is a RECENCY-WEIGHTED AGGREGATE over the last WindowSize
+  ## samples, NOT a pooled rate: each per-enemy window is replayed into one fresh
+  ## window, so once the total exceeds WindowSize the earliest samples are
+  ## overwritten by later ones. Enemies are visited in ascending target-id order
+  ## so the result is identical on every run (std/tables iteration order is hash
+  ## order and therefore nondeterministic).
+  ## ponytail: merge is O(enemies*guns*bins*WindowSize), fine for small counts
   if targetId >= 0 and targetId in t.fitness:
     return t.fitness[targetId]
-  # Aggregate across all enemies
+  # Aggregate across all enemies, deterministically ordered.
   result = newSeq[GunFitness](t.numGuns)
-  for perEnemy in t.fitness.values:
+  var enemyIds: seq[int]
+  for id in t.fitness.keys: enemyIds.add id
+  enemyIds.sort()
+  for id in enemyIds:
+    let perEnemy = t.fitness[id]
     for gunId in 0..<t.numGuns:
       for binIdx in 0..<len(PowerBins):
         let src = perEnemy[gunId].bins[binIdx]
-        var dst = addr result[gunId].bins[binIdx]
         for k in 0..<min(src.count, WindowSize):
-          dst[].record(src.hits[k])
+          result[gunId].bins[binIdx].record(src.hits[k])
 
 proc bestPower*(t: VirtualTracker, gunId: GunId, targetId: int = -1): (int, float) =
   ## Returns (binIdx, power) with highest power that has >= MinHitRate.

common_libs/guns/decay_gf.nim

@@ -1,14 +1,16 @@
 ## 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.
+## Everything else identical to guess_factor.nim, including per-power-bin wave queues.
 
 import std/math
 import gun_harness/gun_interface
+import gun_harness/virtual_bullets as vb  # PowerBins
 
 const
   GFBins     = 31
   GFPrior    = 0.1
   DecayRate  = 0.998  # ponytail: single global decay, tune if adaptation too slow/fast
+  DecayWaveCompactAt = 64
 
 type
   DWave = object
@@ -17,14 +19,21 @@ type
 
   DecayGFGun* = object
     bins:             array[GFBins, float]
-    waves:            seq[DWave]
-    cachedTick:       int
-    cachedWaveStored: bool
+    # 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
+    waveStoredTick:   array[len(vb.PowerBins), int]   # last tick a wave was queued for this bin
+    cachedTick:       int   # last tick bins were decayed
+    wavePushes*:      int
+    waveStarved*:     int
     debugGraphics*:   bool
 
 proc initDecayGFGun*(): DecayGFGun =
   result.cachedTick = -1
   result.debugGraphics = false
+  for b in 0..<len(vb.PowerBins):
+    result.waveStoredTick[b] = -1
   let center = (GFBins - 1) div 2
   for i in 0..<GFBins:
     let d = abs(i - center)
@@ -43,6 +52,28 @@ proc peakBin(g: DecayGFGun): int =
       best = i
   best
 
+proc binForSpeed(spd: float): int {.inline.} =
+  for i in 0..<len(vb.PowerBins):
+    if abs(spd - bulletSpeed(vb.PowerBins[i])) < 1e-6:
+      return i
+  -1
+
+proc binForPower(power: float): int {.inline.} =
+  for i in 0..<len(vb.PowerBins):
+    if abs(power - vb.PowerBins[i]) < 1e-6:
+      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 predict*(g: var DecayGFGun, state: WorldState, bulletSpeed: float): GunPrediction =
   if bulletSpeed <= 0.0:
     return GunPrediction(x: state.enemyX, y: state.enemyY)
@@ -57,12 +88,15 @@ proc predict*(g: var DecayGFGun, state: WorldState, bulletSpeed: float): GunPred
     # Decay all bins once per tick
     for i in 0..<GFBins:
       g.bins[i] *= DecayRate
-    g.cachedTick       = state.tick
-    g.cachedWaveStored = false
+    g.cachedTick = state.tick
 
-  if not g.cachedWaveStored:
-    g.waves.add DWave(fireX: state.selfX, fireY: state.selfY, fireBearing: bearing)
-    g.cachedWaveStored = true
+  # Queue at most one wave per (tick, power bin); the fire site's extra predict()
+  # 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: bearing)
+    g.waveStoredTick[binIdx] = state.tick
+    inc g.wavePushes
 
   let peak    = g.peakBin()
   let peakGF  = indexToGF(peak)
@@ -76,10 +110,13 @@ proc predict*(g: var DecayGFGun, state: WorldState, bulletSpeed: float): GunPred
   )
 
 proc onResult*(g: var DecayGFGun, e: FeedbackEvent) =
-  if g.waves.len == 0: return
+  let binIdx = binForPower(e.bulletPower)
+  if binIdx < 0: return
 
-  let w = g.waves[0]
-  g.waves.delete(0)
+  let (found, w) = g.takeOldestWave(binIdx)
+  if not found:
+    inc g.waveStarved
+    return
 
   let speed  = bulletSpeed(e.bulletPower)
   let mea    = arcsin(clamp(8.0 / speed, -1.0, 1.0))

common_libs/guns/guess_factor.nim

@@ -1,14 +1,16 @@
 ## Guess-factor gun: statistical targeting via GF histogram.
 ## Bins: 31, ranging GF -1 (max CW escape) to +1 (max CCW escape).
-## Learns from virtual bullet outcomes; caches wave state per-tick.
+## Learns from virtual bullet outcomes; queues one wave per (tick, power bin).
 
 import std/[math, strformat]
 import gun_harness/gun_interface
+import gun_harness/virtual_bullets as vb  # PowerBins: the four power bins the harness spawns
 
 const
   GFBins   = 31
   GFPrior  = 0.1
   DebugGF* = false
+  WaveCompactAt = 64  ## compact a bin's wave seq once this many entries are consumed
 
 type
   Wave = object
@@ -18,15 +20,20 @@ type
 
   GFGun* = object
     bins:             array[GFBins, float]
-    waves:            seq[Wave]         # pending unresolved waves
-    # per-tick cache: store wave only once across multiple power-bin calls
-    cachedTick:       int
-    cachedWaveStored: bool
+    # One wave queue per power bin. The owning bin is fixed at push time (from the
+    # bulletSpeed argument) and at pop time (from FeedbackEvent.bulletPower), so a
+    # resolved bullet is always paired with a wave from its own bin.
+    waves:            array[len(vb.PowerBins), seq[Wave]]
+    waveHead:         array[len(vb.PowerBins), int]   # O(1) pop cursor into waves[bin]
+    waveStoredTick:   array[len(vb.PowerBins), int]   # last tick a wave was queued for this bin
+    wavePushes*:      int  # total waves enqueued (== one per (tick, bin))
+    waveStarved*:     int  # onResult found an empty queue for its own bin
     debugGraphics*:   bool
 
 proc initGFGun*(): GFGun =
-  result.cachedTick = -1
   result.debugGraphics = false
+  for b in 0..<len(vb.PowerBins):
+    result.waveStoredTick[b] = -1
   # Seed with a head-on prior: triangular bump at bin 15 (GF=0).
   # Prevents the cold-start tie-break to GF=-1 (bin 0) that poisons early fitness.
   let center = (GFBins - 1) div 2  # = 15
@@ -47,6 +54,34 @@ proc peakBin(g: GFGun): int =
       best = i
   best
 
+proc binForSpeed(spd: float): int {.inline.} =
+  ## Map a virtual-bullet speed back to its power-bin index. All four bin speeds
+  ## are exactly representable floats; the epsilon is belt-and-braces only.
+  for i in 0..<len(vb.PowerBins):
+    if abs(spd - bulletSpeed(vb.PowerBins[i])) < 1e-6:
+      return i
+  -1
+
+proc binForPower(power: float): int {.inline.} =
+  ## Map a FeedbackEvent.bulletPower back to its power-bin index.
+  for i in 0..<len(vb.PowerBins):
+    if abs(power - vb.PowerBins[i]) < 1e-6:
+      return i
+  -1
+
+proc takeOldestWave(g: var GFGun, binIdx: int): (bool, Wave) =
+  ## Pop the oldest unresolved wave for this bin (O(1) amortized via waveHead).
+  ## Returns (false, default) when the bin's queue is empty.
+  if binIdx < 0 or g.waveHead[binIdx] >= g.waves[binIdx].len:
+    return (false, Wave())
+  result = (true, g.waves[binIdx][g.waveHead[binIdx]])
+  inc g.waveHead[binIdx]
+  # Amortized O(1): drop the consumed prefix once it dominates the queue.
+  if g.waveHead[binIdx] >= WaveCompactAt 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 predict*(g: var GFGun, state: WorldState, bulletSpeed: float): GunPrediction =
   if bulletSpeed <= 0.0:
     return GunPrediction(x: state.enemyX, y: state.enemyY)
@@ -57,18 +92,17 @@ proc predict*(g: var GFGun, state: WorldState, bulletSpeed: float): GunPredictio
   let bearing = arctan2(dy, dx)
   let mea    = arcsin(clamp(8.0 / bulletSpeed, -1.0, 1.0))
 
-  # Store one wave per tick regardless of how many power bins call us
-  if state.tick != g.cachedTick:
-    g.cachedTick = state.tick
-    g.cachedWaveStored = false
-
-  if not g.cachedWaveStored:
-    g.waves.add Wave(
+  # Queue at most one wave per (tick, power bin). The fire site's extra predict()
+  # 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 Wave(
       fireX:       state.selfX,
       fireY:       state.selfY,
       fireBearing: bearing,
     )
-    g.cachedWaveStored = true
+    g.waveStoredTick[binIdx] = state.tick
+    inc g.wavePushes
 
   let peak = g.peakBin()
   let peakGF = indexToGF(peak)
@@ -78,7 +112,7 @@ proc predict*(g: var GFGun, state: WorldState, bulletSpeed: float): GunPredictio
   let py = state.selfY + sin(gfAngle) * dist
 
   when DebugGF:
-    echo fmt"[gf-dbg] predict: peakGF={peakGF:.2f} peakBin={peak} mea={radToDeg(mea):.1f}° aimAngle={radToDeg(gfAngle):.1f}° waves={g.waves.len}"
+    echo fmt"[gf-dbg] predict: peakGF={peakGF:.2f} peakBin={peak} mea={radToDeg(mea):.1f}° aimAngle={radToDeg(gfAngle):.1f}° waves={g.waves[binIdx].len}"
 
   GunPrediction(
     x: clamp(px, BotRadius, state.arenaWidth  - BotRadius),
@@ -86,17 +120,15 @@ proc predict*(g: var GFGun, state: WorldState, bulletSpeed: float): GunPredictio
   )
 
 proc onResult*(g: var GFGun, e: FeedbackEvent) =
-  ## Called when a virtual bullet resolves. Match the wave by predicted point,
-  ## compute actual GF, and increment the histogram with a smoothing kernel.
-  ## We don't have the original wave tick here, so we use the prediction coords
-  ## to identify and remove the matching wave.
-  ## ponytail: O(n) scan over waves; waves list stays tiny (< a dozen at a time)
-  if g.waves.len == 0:
-    return
+  ## Called when a virtual bullet resolves. Pop the OLDEST unresolved wave from
+  ## this bullet's own power-bin queue, compute the actual GF, and smooth-add it.
+  let binIdx = binForPower(e.bulletPower)
+  if binIdx < 0: return
 
-  # Pop the oldest wave (FIFO matches bullet resolution order)
-  let w = g.waves[0]
-  g.waves.delete(0)
+  let (found, w) = g.takeOldestWave(binIdx)
+  if not found:
+    inc g.waveStarved
+    return
 
   # Recompute mea from the actual bullet power (correct per-bin, not the cached first-bin mea)
   let speed = bulletSpeed(e.bulletPower)

common_libs/guns/knn_gun.nim

@@ -5,6 +5,7 @@
 
 import std/[math]
 import gun_harness/gun_interface
+import gun_harness/virtual_bullets as vb  # PowerBins
 
 const
   MaxObs     = 2000    # ring-buffer cap
@@ -25,10 +26,14 @@ type
   KNNGun* = object
     obs:                seq[Obs]
     obsHead:            int         # ring-buffer write index
-    waves:              seq[KNNWave]
+    # One wave queue per power bin; matched on bulletSpeed / bulletPower so a
+    # resolved bullet only ever learns from a wave fired with the same power.
+    waves:              array[len(vb.PowerBins), seq[KNNWave]]
+    waveHead:           array[len(vb.PowerBins), int]   # O(1) pop cursor
+    waveStoredTick:     array[len(vb.PowerBins), int]   # last tick a wave was queued for this bin
     # per-tick cache
     cachedTick:         int
-    cachedWaveStored:   bool
+    tickWave:           KNNWave     # wave template for the current tick (features computed once)
     # rolling normalization ranges
     featMin:            array[7, float]
     featMax:            array[7, float]
@@ -36,12 +41,16 @@ type
     lastSpeed:          float
     lastDirection:      float        # +1 or -1
     timeSinceDirChange: int
+    wavePushes*:        int
+    waveStarved*:       int
     debugGraphics*:     bool
 
 proc initKNNGun*(): KNNGun =
   result.cachedTick    = -1
   result.lastDirection = 1.0
   result.debugGraphics = false
+  for b in 0..<len(vb.PowerBins):
+    result.waveStoredTick[b] = -1
   for i in 0..6:
     result.featMin[i] =  1e18
     result.featMax[i] = -1e18
@@ -105,6 +114,32 @@ proc euclidean(a, b: array[7, float]): float {.inline.} =
     result += d * d
   result = sqrt(result)
 
+proc binForSpeed(spd: float): int {.inline.} =
+  ## Map a virtual-bullet speed back to its power-bin index. All four bin speeds
+  ## are exactly representable floats; the epsilon is belt-and-braces only.
+  for i in 0..<len(vb.PowerBins):
+    if abs(spd - bulletSpeed(vb.PowerBins[i])) < 1e-6:
+      return i
+  -1
+
+proc binForPower(power: float): int {.inline.} =
+  ## Map a FeedbackEvent.bulletPower back to its power-bin index.
+  for i in 0..<len(vb.PowerBins):
+    if abs(power - vb.PowerBins[i]) < 1e-6:
+      return i
+  -1
+
+proc takeOldestWave(g: var KNNGun, binIdx: int): (bool, KNNWave) =
+  ## Pop the oldest unresolved wave for this bin (O(1) amortized via waveHead).
+  if binIdx < 0 or g.waveHead[binIdx] >= g.waves[binIdx].len:
+    return (false, KNNWave())
+  result = (true, g.waves[binIdx][g.waveHead[binIdx]])
+  inc g.waveHead[binIdx]
+  if g.waveHead[binIdx] >= 64 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
+
 # ── Gun interface ─────────────────────────────────────────────────────────────
 
 proc predict*(g: var KNNGun, state: WorldState, bulletSpd: float): GunPrediction =
@@ -119,8 +154,7 @@ proc predict*(g: var KNNGun, state: WorldState, bulletSpd: float): GunPrediction
 
   # Track direction change — update state once per tick
   if state.tick != g.cachedTick:
-    g.cachedTick       = state.tick
-    g.cachedWaveStored = false
+    g.cachedTick = state.tick
 
     let relHead  = state.enemyHeading - bearing
     let latVel   = state.enemySpeed * sin(relHead)
@@ -131,18 +165,26 @@ proc predict*(g: var KNNGun, state: WorldState, bulletSpd: float): GunPrediction
     else:
       inc g.timeSinceDirChange
 
-  # Store wave once per tick
-  if not g.cachedWaveStored:
+    # Compute the tick's feature vector ONCE, before lastSpeed is advanced, so
+    # every power bin fired this tick shares identical features. lastSpeed is
+    # only advanced here (once/tick), not once per bin.
     let feat = buildFeatures(state, g.lastSpeed, g.lastDirection, g.timeSinceDirChange)
     g.updateMinMax(feat)
-    g.waves.add KNNWave(
+    g.tickWave = KNNWave(
       fireX:       state.selfX,
       fireY:       state.selfY,
       fireBearing: bearing,
       feat:        feat,
     )
     g.lastSpeed = state.enemySpeed
-    g.cachedWaveStored = true
+
+  # Queue at most one wave per (tick, power bin). The fire site's extra predict()
+  # call for the selected bin lands on the same tick and reuses the queued wave.
+  let binIdx = binForSpeed(bulletSpd)
+  if binIdx >= 0 and g.waveStoredTick[binIdx] != state.tick:
+    g.waves[binIdx].add g.tickWave
+    g.waveStoredTick[binIdx] = state.tick
+    inc g.wavePushes
 
   # Cold start — no data yet
   if g.obs.len == 0:
@@ -236,10 +278,12 @@ proc predict*(g: var KNNGun, state: WorldState, bulletSpd: float): GunPrediction
   )
 
 proc onResult*(g: var KNNGun, e: FeedbackEvent) =
-  if g.waves.len == 0: return
-
-  let w = g.waves[0]
-  g.waves.delete(0)
+  let binIdx = binForPower(e.bulletPower)
+  if binIdx < 0: return
+  let (found, w) = g.takeOldestWave(binIdx)
+  if not found:
+    inc g.waveStarved
+    return
 
   let speed  = bulletSpeed(e.bulletPower)
   let mea    = arcsin(clamp(8.0 / speed, -1.0, 1.0))