SirRoboGarage/common_libs/tests/audit_wave_pairing.nim

## Task 1 + Task 3 measurement: wave-pairing audit and before/after hit rates for
## the three learned GF guns (GuessFactor / DecayGF / KNN).
##
## Replays the committed DrussGT fixtures through the REAL VirtualTracker, exactly
## as common_libs/gun_harness/offline_range.replayFixture does, but keeps handles
## to the concrete guns so it can read their pairing-audit counters and dump the
## raw per-bullet hit booleans for a later bullet-level permutation test.
##
## Run:
##   nim c -r --path:common_libs common_libs/tests/audit_wave_pairing.nim <tag> [metric]
##     tag    = label written into /tmp/wavepair_<tag>_<metric>.txt
##     metric = path (default, shipped) | point | both

import std/[os, math, strformat, tables, algorithm, random]
import gun_harness/gun_interface
import gun_harness/virtual_bullets as vb
import gun_harness/offline_range
import guns/guess_factor
import guns/decay_gf
import guns/knn_gun

const fixturesDir = currentSourcePath().parentDir.parentDir.parentDir / "tools" / "fixtures"
const GunNames = ["GuessFactor", "DecayGF", "KNN"]

type
  Ref[G] = ref object
    g: G

proc mkRef[G](v: G): Ref[G] = Ref[G](g: v)

proc driver[G](name: string, r: Ref[G]): GunDriver =
  result.name = name
  result.predictCb = proc(s: WorldState, sp: float): GunPrediction = r.g.predict(s, sp)
  result.resultCb  = proc(e: FeedbackEvent) = r.g.onResult(e)
  result.readyCb   = nil

proc collectOne(fx: Fixture, drivers: seq[GunDriver], metric: BulletMetric,
                perGunHits: ref seq[seq[bool]]): seq[GunReport] =
  let tid = fx.enemyId
  var tracker = vb.initTracker(drivers.len, metric)
  for si in 0..<fx.states.len:
    let state = fx.states[si]
    for gi in 0..<drivers.len:
      var preds: array[len(PowerBins), GunPrediction]
      for i in 0..<len(PowerBins):
        preds[i] = drivers[gi].predictCb(state, bulletSpeed(PowerBins[i]))
      tracker.spawnBullets(gi, preds, state, tid)
    let act = fx.states[si]
    var enemyPositions: Table[int, tuple[x, y: float, lastSeenTick: int, alive: bool]]
    var lst = act.tick
    if si < fx.lastSeen.len and fx.lastSeen[si] >= 0: lst = fx.lastSeen[si]
    enemyPositions[tid] = (x: act.enemyX, y: act.enemyY, lastSeenTick: lst, alive: true)
    let dref = drivers
    tracker.tickBullets(state, enemyPositions,
      proc(gunId: GunId, binIdx: int, e: FeedbackEvent) =
        dref[gunId].resultCb(e)
        perGunHits[gunId].add e.hit)
  let fit = tracker.fitnessFor(tid)
  for gi in 0..<drivers.len:
    var r = GunReport(name: drivers[gi].name)
    for binIdx in 0..<len(PowerBins):
      let fw = fit[gi].bins[binIdx]
      let n = min(fw.count, WindowSize)
      for k in 0..<n:
        if fw.hits[k]: inc r.hits
      r.shots += n
    result.add r

proc rate(h, n: int): float = (if n == 0: 0.0 else: h.float / n.float * 100.0)

proc runMetric(mname: string, metric: BulletMetric, tag: string) =
  echo "################################################################"
  echo "### METRIC = ", mname, " (", metric, ")"
  echo "################################################################"
  var pooled = [0, 0, 0]
  var pooledN = [0, 0, 0]
  var perGunHits: seq[seq[bool]]
  perGunHits.setLen(3)
  var perFixtureRate: array[3, seq[float]]

  var files: seq[string]
  for f in walkFiles(fixturesDir / "tr_drussgt_*.jsonl"): files.add f
  for f in walkFiles(fixturesDir / "drussgt_*.jsonl"): files.add f
  files.sort()

  # Totals accumulated from FRESH guns per fixture (no cross-fixture learning).
  var totResolved, totMispaired, totStarved, totPushes: array[3, int]

  for path in files:
    var fx = loadFixture(path)
    if fx.states.len < 50: continue
    let gfRef  = mkRef(initGFGun())
    let decRef = mkRef(initDecayGFGun())
    let knnRef = mkRef(initKNNGun())
    let drivers = @[driver("GuessFactor", gfRef), driver("DecayGF", decRef),
                    driver("KNN", knnRef)]
    let thisHits = new(seq[seq[bool]])
    thisHits[].setLen(3)
    let reps = collectOne(fx, drivers, metric, thisHits)
    var line = fmt"{extractFilename(path):<42}"
    for gi in 0..<3:
      let r = reps[gi]
      pooled[gi] += r.hits; pooledN[gi] += r.shots
      perFixtureRate[gi].add rate(r.hits, r.shots)
      for h in thisHits[gi]: perGunHits[gi].add h
      line.add fmt" {GunNames[gi]}={r.hits:>4}/{r.shots:<4}"
    echo line
    totResolved[0] += gfRef.g.waveResolved;  totMispaired[0] += gfRef.g.waveMispaired
    totMispaired[0] += gfRef.g.waveMispaired; totStarved[0] += gfRef.g.waveStarved
    totPushes[0] += gfRef.g.wavePushes
    totResolved[1] += decRef.g.waveResolved; totMispaired[1] += decRef.g.waveMispaired
    totStarved[1] += decRef.g.waveStarved
    totPushes[1] += decRef.g.wavePushes
    totResolved[2] += knnRef.g.waveResolved; totMispaired[2] += knnRef.g.waveMispaired
    totStarved[2] += knnRef.g.waveStarved
    totPushes[2] += knnRef.g.wavePushes

  echo ""
  echo "── pooled hit rate (", mname, ") ──"
  for gi in 0..<3:
    echo fmt"{GunNames[gi]:<12} {pooled[gi]:>5}/{pooledN[gi]:<6} {rate(pooled[gi], pooledN[gi]):>6.2f}%   per-fixture min/max {min(perFixtureRate[gi]):.1f}/{max(perFixtureRate[gi]):.1f}"

  echo ""
  echo "── pairing audit (", mname, ") ──"
  echo "gun          resolved  mispaired  mispair%  starved  pushes"
  for gi, name in GunNames:
    echo fmt"{name:<12} {totResolved[gi]:>8} {totMispaired[gi]:>10} {rate(totMispaired[gi], totResolved[gi]):>8.2f}  {totStarved[gi]:>7}  {totPushes[gi]:>6}"

  # Dump per-gun hit booleans for the cross-build permutation test.
  for gi in 0..<3:
    let path = fmt"/tmp/wavepair_{tag}_{mname}_{GunNames[gi]}.txt"
    var f = open(path, fmWrite)
    defer: f.close()
    for h in perGunHits[gi]:
      f.writeLine(if h: "1" else: "0")
    echo fmt"dumped {perGunHits[gi].len} outcomes -> {path}"

proc main() =
  let tag = if paramCount() >= 1: paramStr(1) else: "run"
  let metricArg = if paramCount() >= 2: paramStr(2) else: "path"
  case metricArg
  of "point": runMetric("point", bmPoint, tag)
  of "both":  (runMetric("path", bmPath, tag); runMetric("point", bmPoint, tag))
  else:       runMetric("path", bmPath, tag)
  echo "\ndone."

when isMainModule:
  randomize(1)
  main()