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.
This commit is contained in:
2026-09-22 01:33:31 +02:00
parent 1ea72c7f14
commit 4657fe715e
6 changed files with 586 additions and 65 deletions
+32 -18
View File
@@ -14,6 +14,7 @@ const
KernelW = 0.3 # Gaussian kernel width multiplier
DensityBins = 60 # scan resolution for peak-GF search
NFeat = 8 # feature vector length (see buildFeatures)
KNNWaveRingSlots = 1024 # exact (fireTick, powerBin) ring; see guess_factor.nim
type
Obs = object
@@ -23,15 +24,18 @@ type
KNNWave = object
fireX, fireY: float
fireBearing: float
fireTick: int
bin: int
alive: bool
feat: array[NFeat, float]
KNNGun* = object
obs: seq[Obs]
obsHead: int # ring-buffer write index
# 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
# 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[KNNWave]
waveStoredTick: array[len(vb.PowerBins), int] # last tick a wave was queued for this bin
# per-tick cache
cachedTick: int
@@ -46,12 +50,15 @@ type
timeSinceDirChange: int
wavePushes*: int
waveStarved*: int
waveResolved*: int
waveMispaired*: int # ring-slot collision (impossible by design)
debugGraphics*: bool
proc initKNNGun*(): KNNGun =
result.cachedTick = -1
result.lastDirection = 1.0
result.debugGraphics = false
result.waves = newSeq[KNNWave](KNNWaveRingSlots)
for b in 0..<len(vb.PowerBins):
result.waveStoredTick[b] = -1
for i in 0..<NFeat:
@@ -141,16 +148,9 @@ proc binForPower(power: float): int {.inline.} =
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
proc waveSlot(fireTick, binIdx: int): int {.inline.} =
## Exact (fireTick, powerBin) key -> ring slot (same scheme as tsetlin.nim).
((fireTick * len(vb.PowerBins)) + binIdx) mod KNNWaveRingSlots
# ── Gun interface ─────────────────────────────────────────────────────────────
@@ -186,6 +186,7 @@ proc predict*(g: var KNNGun, state: WorldState, bulletSpd: float): GunPrediction
fireX: state.selfX,
fireY: state.selfY,
fireBearing: bearing,
fireTick: state.tick,
feat: feat,
)
g.lastSpeed = state.enemySpeed
@@ -202,7 +203,10 @@ proc predict*(g: var KNNGun, state: WorldState, bulletSpd: float): GunPrediction
# differs per bin); override the shared per-tick template here.
var w = g.tickWave
w.fireBearing = f.bearing
g.waves[binIdx].add w
w.fireTick = state.tick
w.bin = binIdx
w.alive = true
g.waves[waveSlot(state.tick, binIdx)] = w
g.waveStoredTick[binIdx] = state.tick
inc g.wavePushes
@@ -298,12 +302,20 @@ proc predict*(g: var KNNGun, state: WorldState, bulletSpd: float): GunPrediction
)
proc onResult*(g: var KNNGun, 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))
@@ -323,3 +335,5 @@ proc onResult*(g: var KNNGun, e: FeedbackEvent) =
# ring buffer
g.obs[g.obsHead] = Obs(feat: w.feat, gf: gf)
g.obsHead = (g.obsHead + 1) mod MaxObs
w.alive = false