TeslaRel410/restoration/source410/BT/HEAT.NOTES.md

# HEAT.CPP / POWERSUB.CPP — the power/heat wave (Phase 5.3.10, 2026-07-21)

The mech's thermal + electrical economy is LIVE: weapons dump firing heat into
their own sinks, the sinks conduct through the Condenser bank into the central
HeatSink, temperatures drive the degradation/failure alarms, and every powered
subsystem tracks its generator through the electrical state machine.

## The heat topology (wire-verified on TEST.EGG)

`linkedSinkIndex` (the previously-missing HeatSink resource int — see below)
wires the authored conduction graph at construction:

    weapons / equipment  ->  Condenser1..6 (slots 4-9)  ->  central HeatSink (slot 2)
    GeneratorA..D (10-13) ->  Condensers
    Reservoir (3)         ->  central HeatSink

Authored values match the BT411 calibration audit EXACTLY: central bank mass
1.39e6, PPC's own sink 174000, thresholds 77 start / 1000 degradation / 2000
failure, PPC conductance 86800.  (The central sink's own `linkedSinkIdx=5` is a
FORWARD reference — Condenser2 isn't constructed yet at slot 2's ctor — so its
drain is unwired; a post-walk fixup is a small future item.  Everything drains
INTO it fine.)

## Reconstructed

- **HeatSink::HeatSinkSimulation** (@004ad924): absorb pendingHeat → T =
  E/mass → UpdateHeatLoad (15-sample filter) → ConductHeat → alarm thresholds.
  Installed by the HeatSink ctor (derived classes override and chain it).
- **ConductHeat / ComputeHeatFlow** (@004ad8ac/@004ad9ec): the two-body
  equilibrium relaxation — `(T·massScale − (E_other+pending+E_own)/denom)·tau·
  (1−exp(−dt·conductance·(coolant/capacity)·flowScale/denom))`.  Verified:
  flow == 0 exactly at uniform temperature; a fired PPC bleeds ~170K units/step
  into Condenser4.
- **PoweredSubsystem ctor + PoweredSubsystemSimulation** (@004b0f74/@004b0bd0):
  resolves `voltageSourceIndex` from the roster (GeneratorA-D — wire-verified),
  attaches the tap (`Generator::TapVoltageSource`, −1 when full), and runs the
  electrical FSM (Starting=0 / NoVoltage=1 / Shorted=2 / GeneratorOff=3 /
  Ready=4) watching the generator state.  Deferred: the AutoConnect
  replacement-generator hunt (needs the status flags / damage wave).
- **Generator::GeneratorSimulation** (PARTIAL): heat step + start/short-recovery
  timers; the load model (voltage sag, I²R self-heat feeding the charge
  integration) joins the electrical-charge wave (TrackSeekVoltage).
- **Sensor::SensorSimulation** upgraded to the authentic gating (@004b1c4c):
  power step first, radar = 1 − damage, electrical-Ready gate (badVoltage),
  heat-state switch (Degradation ×0.5, Failure → 0).  Verified: voltState=4,
  radar 100% on the healthy mech.
- Weapons: Emitter/Projectile sims run the power step at their head; the
  Loading recharge is gated on electrical Ready (authentic @4bbdf5); FireWeapon
  dumps the firing heat.

## Heat units (1e7-native) — TWO authoring conventions

The heat chain is 1e7-unit-native (BT411 audit).  The stream stores
`heatCostToFire` in TWO conventions:
- **Energy weapons: small units** (PPC = 11) — the ×1e7 comes from the energy
  closed form ((1−dF)·E ≈ heatCost·1e7 at full charge).  Our partial multiplies
  by 1e7 pending the charge model.
- **Ballistics: native units** (SRM6 = 5.06e7) — dumped RAW.  (Double-scaling
  this to 5e14 was the runaway-temperature bug during bring-up.)
Both land ~+640K on the weapon's own sink — the consistent design magnitude.

## The resource-alignment resolution (wire-verified, closes the +3 mystery)

The raw-stream dumps pinned the FULL ancestry alignment:
- `HeatSink__SubsystemResource.linkedSinkIndex` — THE missing int that shifted
  every descendant block +1 (PoweredSubsystem's voltageSourceIndex previously
  read the linked-sink index — hence "power sources" appearing to be
  Condensers).
- The MechWeapon pip tail is `pipPosition(int) + pipColor(3 floats) +
  pipExtendedRange(int)` (+2) — matches BT411's verified overlay exactly.
- +1 +2 = the +3 the interim ProjectileWeapon pad compensated; the pad is gone.
- True bhk1 reads: PPC recharge **5.0 s** (not the misaligned 1.0), discharge
  0.99 s, range 900, damage 12, heatCost 11, pipColor (0,0,1); SRM6 recharge
  5 s, range 800, salvo damage 35, missileCount 6.

## VERIFIED (BT_FORCE_FIRE + BT_POWER_LOG)

PPC: 77° → fires → ~709° → relaxes to 441° across its 5 s reload → sustained
fire climbs the residual 441 → 674 → 838 → 960 — brushing the 1000° degradation
threshold: the authentic fire-discipline game.  SRM salvos spike +641K and
cross degradation after three.  Condensers absorb and pass to the central
bank.  Neutral run: sensor Ready/100%, mech holds, zero Fail.

## Heat consequences (Phase 5.3.11, 2026-07-22)

The weapon-side consequences are wired and VERIFIED under sustained fire:

- **Ballistic gate 1** (@4bbd36): weapon destroyed-state or its own sink at
  FailureHeat pins full recoil + the unavailable alarm (the NoAmmo roach-motel
  re-asserts).  (Mech-disabled half joins the damage wave.)
- **CheckForJam** (@4bbfcc): `p = 0.41·T/failT` clamped [minJamChance, 1.0],
  rolled per granted shot against the MUNGA uniform `Random`.  Interim gate:
  heat-degraded only (stands in for the deferred `LiveFireEnabled` novice
  switch AND the trivially-true `heatLoad>0` early-out — the exact spurious-
  cold-jam trap the BT411 port documented).  Verified: SRM6s jam at
  T≈1200-1320 (24%+ rolls past the 1000° threshold), stay jammed.
- **Emitter hard gate** (@4baab9): FailureHeat drops the beam state + charge
  each frame; SELF-RECOVERING — conduction cools the sink below 2000° and the
  weapon resumes from Loading.  Verified: the PPC settles into an emergent
  thermal duty cycle (fire at ~1930° → spike 2562° → shutdown → cool → refire);
  the lasers oscillate around ~2200°.

## The experience gates + the coolant wave (Phase 5.3.12, 2026-07-22)

**The player-experience gates are LIVE** (the workflow dossier recovered every
body from the BT411 RE):

- `HeatSink::HeatModelActive()` (binary FUN_004ad7d4): owner mech →
  `Entity::GetPlayerLink()` → `BTPlayer::heatModelOn` — ON only for veteran /
  expert.  Gates BOTH phases of HeatSinkSimulation (absorb/conduct AND
  UpdateCoolant) and every weapon fire-heat dump.  Standard mode has NO heat
  consequences — authentic.  NULL player link reads ON (dev-permissive).
- `ProjectileWeapon::LiveFireEnabled()`: playerLink → `simLive` — 0 only for
  novice, whose ballistics never jam.  `CheckForJam` is now the AUTHENTIC form:
  LiveFireEnabled early-out + the `heatLoad <= 0` early-out (with the model off
  heatLoad stays 0, so standard mode never jams either) + the minJamChance
  floor (a veteran+ launcher carries its authored ~5% cold jam chance — the
  interim heat-degraded gate is retired).
- BTPlayer's flag block renamed to its TRUE semantics (simLive @0x25c,
  heatModelOn @0x260, advancedDamageOn/2, levelFlag26c/270, experienceLevel) —
  the ctor rows were already binary-accurate; only the names/types were the
  old "display toggles" misread.

**THE LOAD-BEARING FIX found on the way: `Mech` ctor `SetValidFlag()`.**
Every 1995 entity ctor tail marks itself valid; ours didn't — and
`Entity::Dispatch` routes messages to an INVALID entity into the deferred
event queue, so the PlayerLink bind (and every directly-dispatched mech
message) silently never landed.  The experience gates read a NULL player
forever (permissive ON) until this one authentic line was restored.

**The coolant system** (all bodies authentic from the dossier, constants
byte-verified: HeatLoadScale 0.002 → heatLoad now lives in the [0,1] band,
HeatEqualizeEpsilon 1e-4, draw floor 0.0025 / ON 0.003, draw gate 1e-4):
- `UpdateCoolant` (@004adbf8): coolantDraw = own structural damage × heatLoad
  (an UNDAMAGED mech leaks nothing — the bars stay full), drain, top-up via
  the virtual `DrawCoolant`, and the active-flag hysteresis.
- `BalanceCoolant` (@004ada94): full clamp chain, called from ConductHeat.
- `DrawCoolant` base = 0; **Reservoir overrides it as THE SOURCE** (@4af3b0).
- **Reservoir reconstructed** (@4af408): capacity overlays thermalCapacity
  (streamed 20), squirtMass 0.5, `CoolantSimulation` + `InjectCoolant`
  (@4aefa4, the full flush distribution: condensers → weapons → heatables →
  master with intentional duplicate weighting, squirts only leave the tank,
  the chill only cools).  `BT_FORCE_FLUSH=1` dev hook (the cockpit
  InjectCoolant button joins the message wave).  Deferred: the
  AggregateHeatSink master-bank attach + the 0.05×count capacity rescale.
- **Condenser refrigeration** (@4ae4d8): valveState inits 1, massScale =
  (1 − own damage) × refrigerationFactor (streamed 3.0) clamped ≥ 1 each
  frame — the condenser pumps heat as if 3× hotter, chilling itself below
  ambient; that chill is what cools the weapons.  INTERIM: coolantFlowScale
  stays 1.0 (authentic streams 0 + the MoveValve/BTRecomputeCondenserValves
  share assignment — the cockpit-button wave; zeroing it now would strand
  condenser heat).

**VERIFIED headlessly, both directions of the experience lever** (TESTNOV.EGG
= TEST.EGG with `experience=novice`):
- NOVICE: 212 fire cycles ALL at T=77, zero jams, zero shutdowns, coolant
  static — the heat model authentically absent.
- EXPERT: playerLink resolves, the full economy runs (PPC duty cycle now
  sawing ~650-1200° — the refrigeration pump drains harder than before — 119
  shutdowns + 2 authentic jams under forced sustained fire).  Zero Fail in
  both.

## Still deferred

The electrical charge model (TrackSeekVoltage / voltage sag / I²R), the
mech-disabled halves of the weapon gates (damage wave), the AggregateHeatSink
family (the central bank's count/radiator loop + reservoir attach + capacity
rescale + its forward-linked drain), the MoveValve / ToggleCooling /
InjectCoolant cockpit-button message handlers + BTRecomputeCondenserValves,
Myomers movement heat, jam recovery via ResetToInitialState (mission reset).

## The cockpit-button message layer (Phase 5.3.13, 2026-07-24)

The subsystem-family button messages are LIVE through the authentic Receiver
dispatch -> per-class handler-table path (the id space decodes cleanly:
Receiver::NextMessageID == 3, so ToggleCooling = 3 on the HeatSink chain and
the per-class id 4 is MoveValve on a Condenser / InjectCoolant on the
Reservoir -- the same number, different class, exactly the binary's
per-receiver-class convention):

- **HeatSink::ToggleCoolingMessageHandler** (@004ad6f8, id 3): novice-locked,
  press-only; toggles coolantAvailable + coolantFlowScale together (OFF
  strands this sink's heat until switched back).
- **Condenser::MoveValveMessageHandler** (@4ae464, id 4): novice-locked,
  press-only; cycles the valve 1 -> 5 -> 50 -> 0 -> 1 and calls
  **Condenser::RecomputeValves** (@0049f788): every condenser's
  coolantFlowScale = valve / sum-of-valves.  The Condenser ctor now streams
  the authentic flowScale = 0; the Mech ctor seeds the shares once at spawn
  (all valves 1 -> equal shares) -- retiring the flowScale=1 interim.  (The
  condenser-alarm change pulse joins the gauge wave.)
- **Reservoir::InjectCoolantMessageHandler** (@4aee70, id 4): novice-locked;
  press raises the inject alarm when the tank holds charge (flush-cloud psfx
  deferred), release drops it.
- **MechSubsystem::NoviceLockout()** (@4ac9c8): owner -> playerLink ->
  experience == novice; unlinked mechs read unlocked.
- DEV harness: BT_PRESS_VALVE / BT_PRESS_FLUSH dispatch the REAL messages
  ~6 s in (Mech::Simulate).

VERIFIED: spawn shares 6 x 0.166667; one MoveValve press -> Condenser1
valve=5 flow=0.5, the others 0.1 (valve/sum exactly); the flush arms via the
real button message; NOVICE: both presses swallowed by the lockout (valve
lines stay spawn-only, zero flush).  Zero Fail throughout.

## The heat-sink BANK (Phase 5.3.14, 2026-07-24)

**AggregateHeatSink reconstructed** -- the binary's 0x0BBE class (the value our
VDATA enum names HeatSinkClassID; there is NO streamed plain-HeatSink -- the
walk now builds the bank).  Ctor (@4ae8d0): heatSinkCount from res +0xFC
(bhk1 = 6, matching its six condensers), thermalConductance x 0.1 x count
(231000 -> 138600), ambient setpoint 300 (the mission-temperature overwrite
joins the Mech-PlayerLink wave).

**RadiatorSimulation** (@4ae73c) replaces the base heat step on the bank --
THE system's only heat exit: relax toward the ambient target with rate
k = conductance x (1 - damage) x (coolant/capacity) x flowScale / mass, then
top the bank's coolant from the attached store via the DrawCoolant virtual
(base 0 until the reservoir attach wave).  VERIFIED signed-correct: the bank
warms 77 -> 300 from the cold start (shed positive, absorbing toward
ambient), then flips negative (-48K.. -167K/step) as fired heat pushes it
past ambient -- actively radiating the mech's heat away.

**Reservoir master rescale**: capacity = 0.05 x bankCount x streamed
(0.05 x 6 x 20 = 6 -- the authentic tank), coolant refilled to it.

Zero Fail; the full expert economy regression stays green.

## The electrical charge model (Phase 5.3.15, 2026-07-24)

The emitter charge cycle is REAL (all bodies authentic from the BT411 RE):

- **Resource fix (wire-verified)**: the Emitter block is graphicLength,
  dischargeTime, seekVoltage[5] (FRACTIONS of the generator's rated voltage,
  -1 sentinel), seekVoltageRecommendedIndex.  The earlier two-field guess had
  read seekVoltage[3] = 0.99 as "dischargeTime 0.99 s" -- the TRUE PPC
  discharge is 0.2 s, and the calibration reads seekV = {6000, 7000, 8000,
  9900} x rated 10000, rec gear 2, exactly the documented curve.
- **Ctor calibration** (@004bb120): energyTotal = (damage + heat) x 1e7 (PPC
  2.3e8); EC pins E = 0.5 V^2 EC to energyTotal at the recommended gear;
  voltageScale calibrates the exponential charge to reach seekV[rec] in the
  authored RechargeRate seconds on a COLD generator; damageFraction = the
  damage share.
- **TrackSeekVoltage** (@004ba838): seekRate = (genV - level)/ChargeTimeScale;
  level += rate/EC x dt; and the charging I^2R loss lands in the GENERATOR's
  pendingHeat -- recharging weapons is what heats generators.  VERIFIED:
  GeneratorA at 477.9 K charging its PPC (BT411 predicted ~+480K), GeneratorD
  (avionics only) idle at 77.
- **ChargeTimeScale** (@004b0d50, PoweredSubsystem): the base voltageScale
  stretched by (1 + thermalResistivity x generator temp rise) -- hot
  generators charge slower.  The feedback loop is CLOSED.
- **Emitter::ComputeOutputVoltage** override (@004ba738, now virtual as in the
  binary vtable): dial = level/seekV[gear], snap to 1.0 within 0.01, over-1
  clamp zeroes.
- **Sub-stepped Loading** (the BT411 weapon-brick fix): the charge integrates
  in 1/60 s slices so the +-0.01 Loaded snap window can't be jumped by a dt
  spike; plus the DOCUMENTED-DIVERGENCE overcharge rescue (the binary
  deadlocks a weapon whose level lands above a re-geared snap window).
  VERIFIED: the PPC loads at level ~7920 -- inside the exact [7920, 8080]
  window from the binary's disasm.
- **FireWeapon energy algebra** (@004bace8): damage/heat = the two
  energy shares x chargeRatio^2 (level/seekV[rec]).  VERIFIED: dmg=11.78,
  heat=1.079e8 at ratio 0.9906 -- ~98% of authored at the snap edge.  The
  heatCost x 1e7 partial is retired; the heat now comes from the ENERGY.

Deferred: the ToggleSeekVoltage gear button (needs the energy-weapon message
table ids 4..0xb with pads), ServiceDischarge (replicant beam path), the beam
build + damage submission (targeting/render waves).