j140 rename the lead-gain corrector: BitBrain -> LEADGAIN (+ legacy TR_BITBRAIN_* aliases)

The gun at rack id 16 learned a multiplier for Pattern's lead, separately
per range band. It was called BITBRAIN and shipped a TR_BITBRAIN_* prefix,
which is why the name read as a neural network it no longer contains.

  guns/bitbrain_gun.nim -> guns/lead_gain.nim  (rack id 16 UNCHANGED)
  RackGunNames[16]       BITBRAIN -> LEADGAIN
  TR_BITBRAIN_* knobs    -> TR_LEADGAIN_*
  [bb] log line          -> [lg]

BACKWARD COMPATIBILITY is mandatory: the live .env carries
TR_RACK_BITBRAIN=both, TR_BITBRAIN_GAINS, TR_BITBRAIN_MEM=decay and
TR_BITBRAIN_LOG=1, and those must keep behaving identically. The new ADE+SBC
gun (next commit) claims the BITBRAIN name and the TR_BITBRAIN_* prefix, so
the namespace is disambiguated by ONE deterministic switch, TR_BITBRAIN_NET
(default 0):

  TR_BITBRAIN_NET unset/0 -> LEGACY: the 14 frozen legacy suffixes are aliases
                              for TR_LEADGAIN_*, and TR_RACK_BITBRAIN still
                              selects rack id 16. One [depr] line on stderr
                              names the new spelling of each honoured knob.
  TR_BITBRAIN_NET = 1      -> the TR_BITBRAIN_* names belong to the new gun.

The legacy suffix set and the new gun's knob set are DISJOINT, so no name is
ever claimed twice; the new name always wins over its alias.

Parity: shipped rack is still onlyPattern, shipped movement is still strafe.
Guards unchanged: test_env_report 25, test_rack_membership 48,
test_tm_pattern_registration 20, test_lead_gain_registration 13 (was
test_bitbrain_registration), test_bitbrain 56, test_gun_harness 39,
test_tfil_commit_env 30. New: test_lead_gain_legacy 24.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

common_libs/tests/run_prediction_quality.nim

@@ -3,7 +3,7 @@
 ## Reads the recorded live-vs-real-DrussGT corpus, drives each arm over the
 ## recorded enemy trajectory, and scores every tick×power-bin prediction against
 ## the aim-independent interception point (see prediction_quality.nim). Owns the
-## RANGE-BAND table that is "the bar" for the BitBrain campaign.
+## RANGE-BAND table that is "the bar" for the lead-gain campaign.
 ##
 ## NO CLOSED-LOOP CLAIM IS MADE HERE. Every arm below is an open-loop prediction
 ## scored on a FIXED trajectory. Wins, damage and survival are decided live.
@@ -16,7 +16,7 @@
 
 import std/[os, strformat, strutils, times, math]
 import gun_harness/[gun_interface, virtual_bullets, prediction_quality]
-import guns/[head_on, pattern_matcher, tm_horizon, bitbrain_gun]
+import guns/[head_on, pattern_matcher, tm_horizon, lead_gain]
 
 # arm indices (fixed order = fixed output)
 const
@@ -29,7 +29,7 @@ const
   A_G30* = 6
   A_NAIVE* = 7
   A_TMH* = 8
-  A_BB* = 9
+  A_LG* = 9
   # ── Phase 1: the MISSING gain sweep. Gains >= 1 were measured worse at every
   # band in Phase 0; the unexplored region is gain < 1. gain 0.0 is HeadOn
   # (A_HEADON) and gain 1.0 is Pattern (A_PATTERN), so only 0.25/0.50/0.75 are
@@ -40,12 +40,12 @@ const
   A_G075* = 12
   # Phase 1 fixed causal per-band gain rule: the hitProxy-argmax curve measured by
   # the sub-unity sweep ([1,1,1,0,0] == Pattern below 300 px, HeadOn above). This
-  # is the rule BitBrain must match; it needs no learning (range is known at fire
+  # is the rule the corrector must match; it needs no learning (range is known at fire
   # time). The table was selected in-sample from this corpus.
   A_BAND* = 13
   BandGainTable* = [1.0, 1.0, 1.0, 0.0, 0.0]
   ArmNames* = ["Oracle", "OracleQuant", "HeadOn", "Pattern", "PatternGain1.5",
-               "PatternGain2.0", "PatternGain3.0", "NaiveLinear", "TMHorizon", "BitBrain",
+               "PatternGain2.0", "PatternGain3.0", "NaiveLinear", "TMHorizon", "LeadGain",
                "PatternGain0.25", "PatternGain0.50", "PatternGain0.75", "PatternBandGain"]
 
 const
@@ -95,7 +95,7 @@ type Ctx = object
   pattern: PatternMatcherGun
   naive: NaiveLinearGun
   tmh: TmHorizonGun
-  bb: BitBrainGun
+  lg: LeadGainGun
   headon: HeadOnGun
   st: WorldState
   enemy: seq[EnemyInfo]
@@ -169,10 +169,10 @@ proc runRound(ctx: var Ctx, arms: var seq[ArmAcc], r: int) =
       let tp = predict(ctx.tmh, ctx.st, speed)
       let tl = wrap180(bearingDeg(ox, oy, tp.x, tp.y) - los)
       arms[A_TMH].record(rng, wrap180(tl - targetLead), tl, targetLead)
-      # BitBrain (base Pattern + ADE/SBC corrector)
-      let bp = predict(ctx.bb, ctx.st, speed)
+      # LEADGAIN (Pattern base + per-band learned lead gain)
+      let bp = predict(ctx.lg, ctx.st, speed)
       let bl = wrap180(bearingDeg(ox, oy, bp.x, bp.y) - los)
-      arms[A_BB].record(rng, wrap180(bl - targetLead), bl, targetLead)
+      arms[A_LG].record(rng, wrap180(bl - targetLead), bl, targetLead)
 
 proc runOne(runPath: string, arms: var seq[ArmAcc], shotsCont, shotsQuant: var ShotStat,
             doShots: bool, timing: bool, cont: bool): int =
@@ -185,7 +185,7 @@ proc runOne(runPath: string, arms: var seq[ArmAcc], shotsCont, shotsQuant: var S
     pattern: PatternMatcherGun(),
     naive: NaiveLinearGun(lastTick: -1),
     tmh: initTmHorizonGun(),
-    bb: initBitBrainGun(),
+    lg: initLeadGainGun(),
     headon: HeadOnGun(),
     st: WorldState(arenaWidth: c.arenaW, arenaHeight: c.arenaH),
     enemy: newSeq[EnemyInfo](1))
@@ -295,10 +295,10 @@ proc main() =
   let mHead = overallMean(arms, A_HEADON)
   let mPat = overallMean(arms, A_PATTERN)
   let mTmh = overallMean(arms, A_TMH)
-  let mBb = overallMean(arms, A_BB)
+  let mLg = overallMean(arms, A_LG)
   let mLin = overallMean(arms, A_NAIVE)
-  let ordOk = mHead > mPat and mHead > mTmh and mHead > mBb
-  echo fmt"3. HeadOn (static LOS) mean|err| = {mHead:.3f} deg vs Pattern {mPat:.3f} / TMHorizon {mTmh:.3f} / BitBrain {mBb:.3f}"
+  let ordOk = mHead > mPat and mHead > mTmh and mHead > mLg
+  echo fmt"3. HeadOn (static LOS) mean|err| = {mHead:.3f} deg vs Pattern {mPat:.3f} / TMHorizon {mTmh:.3f} / LeadGain {mLg:.3f}"
   let ordMsg = if ordOk: "OK (static gun worst among real guns)" else: "UNEXPECTED: a predictive gun is worse than static LOS"
   echo fmt"     -> {ordMsg}"
   echo fmt"     NaiveLinear mean|err| = {mLin:.3f} deg (over-leads; see the lead-gain sweep for why a larger"
@@ -317,7 +317,7 @@ proc main() =
   echo "=".repeat(120)
   echo "HEADROOM  --  the direct answer: how far each arm is from the oracle ceiling, per band"
   echo "=" .repeat(120)
-  let hdr = "band     Pattern n  Pattern|err|  Pattern hpx   Oracle hpx   headroom pp   naive hpx  TMHoriz hpx  BitBrain hpx"
+  let hdr = "band     Pattern n  Pattern|err|  Pattern hpx   Oracle hpx   headroom pp   naive hpx  TMHoriz hpx  LeadGain hpx"
   echo hdr
   echo "-".repeat(hdr.len)
   for b in 0 ..< NBands:
@@ -325,7 +325,7 @@ proc main() =
     let orc = arms[A_ORACLE].bands[b]
     let hp = pat.hitProxy
     let ohp = orc.hitProxy
-    echo fmt"{BandLabels[b]:<9} {pat.n:>8} {fmt3(meanAbs(pat)):>12} {fmt4(hp):>12} {fmt4(ohp):>12} {ohp - hp:>13.4f} {fmt4(arms[A_NAIVE].bands[b].hitProxy):>11} {fmt4(arms[A_TMH].bands[b].hitProxy):>12} {fmt4(arms[A_BB].bands[b].hitProxy):>13}"
+    echo fmt"{BandLabels[b]:<9} {pat.n:>8} {fmt3(meanAbs(pat)):>12} {fmt4(hp):>12} {fmt4(ohp):>12} {ohp - hp:>13.4f} {fmt4(arms[A_NAIVE].bands[b].hitProxy):>11} {fmt4(arms[A_TMH].bands[b].hitProxy):>12} {fmt4(arms[A_LG].bands[b].hitProxy):>13}"
   echo ""
   echo "hitProxy = fraction of tick-bins aimed within atan(18/range) of the true interception point."
   echo "headroom pp = oracle hitProxy - Pattern hitProxy = the absolute hit-probability points available"
@@ -403,17 +403,17 @@ proc main() =
     echo fmt"   {BandLabels[b]:<9} best gain {GainValues[bestHi]:.2f}  hitProxy {bestHp:.4f} vs Pattern {patHp:.4f}  => {bestHp-patHp:+.4f} pp"
   echo curve & "]"
   echo ""
-  echo "DIRECT COMPARISON — Pattern vs the FIXED causal per-band rule [1,1,1,0.00,0.00] vs BitBrain (learned online):"
-  let hdrd = "band      Pattern hpx   fixed-band hpx   BitBrain hpx   fixed-Pat pp   BB-Pat pp"
+  echo "DIRECT COMPARISON — Pattern vs the FIXED causal per-band rule [1,1,1,0.00,0.00] vs LeadGain (learned online):"
+  let hdrd = "band      Pattern hpx   fixed-band hpx   LeadGain hpx   fixed-Pat pp   BB-Pat pp"
   echo hdrd
   echo "-".repeat(hdrd.len)
   for b in 0 ..< NBands:
     let patHp = arms[A_PATTERN].bands[b].hitProxy
     let fixHp = arms[A_BAND].bands[b].hitProxy
-    let bbHp  = arms[A_BB].bands[b].hitProxy
+    let bbHp  = arms[A_LG].bands[b].hitProxy
     echo fmt"{BandLabels[b]:<9} {patHp:>11.4f} {fixHp:>16.4f} {bbHp:>14.4f} {fixHp-patHp:>+14.4f} {bbHp-patHp:>+10.4f}"
   echo "fixed-band hpx = the [1,1,1,0,0] table applied causally; it was selected in-sample."
-  echo "BitBrain is learned online from labels inside each run (cold start at gain 1.0)."
+  echo "LeadGain is learned online from labels inside each run (cold start at gain 1.0)."
   echo ""
   echo "LEAD CORRELATION PER GAIN (Pearson of applied lead with required lead). Pearson is invariant"
   echo "under positive scaling, so every g>0 column must be IDENTICAL to Pattern; g=0 has no lead and"
@@ -445,7 +445,7 @@ proc main() =
     let sp = arms[A_PATTERN].bands[b]
     let sn = arms[A_NAIVE].bands[b]
     let st = arms[A_TMH].bands[b]
-    let sb = arms[A_BB].bands[b]
+    let sb = arms[A_LG].bands[b]
     echo fmt"{BandLabels[b]:<9} {fmt3(meanAbs(arms[A_HEADON].bands[b])):>9} {fmt3(meanAbsReq(arms[A_HEADON].bands[b])):>9} {fmt3(meanAbsReq(sp)):>9} {fmt3(captureSlope(sp)):>10} {fmt3(leadCorr(sp)):>10} " &
          fmt"{fmt3(captureSlope(sn)):>10} {fmt3(leadCorr(sn)):>10} {fmt3(captureSlope(st)):>10} " &
          fmt"{fmt3(leadCorr(st)):>10} {fmt3(captureSlope(sb)):>10} {fmt3(leadCorr(sb)):>10}"