Mech milestone phase 2 kickoff: MechSubsystem base analysis (damage-model de-risk)

Begins phase 2 (MechSubsystem base + subsystem roster) with the base-class
analysis that keeps the reconstruction on the 4.10 damage model. Key findings:

- All base deps survive: Subsystem (SUBSYSTM.HPP + staged SUBSYSTM.CPP),
  DamageZone (DAMAGE), Mech__DamageZone + BT damage model (MECHDMG.HPP),
  AlarmIndicator (just built).
- Finding 1: the staged base Subsystem ctor sets damageZone=NULL, so the derived
  MechSubsystem creates the Mech__DamageZone (BT411's zone-creation is right).
- Finding 2 (CRITICAL): the damage model DIVERGED. 4.10 is per-damage-TYPE --
  DamageZone has defaultArmorPoints + damageScale[5] {collision/ballistic/
  explosive/laser/energy} and STREAMS its own armour (DAMAGE.CPP:335,413).
  BT411 reconstructed a per-FACING armorByFacing[5]/structureReference model that
  MechSubsystem hand-seeds -- those fields exist only in BT411's ReconDamageZone
  proxy, NOT in the 4.10 zone. So BT411's MechSubsystem ctor CANNOT be backdated
  verbatim; doing so would install a damage model the 4.10 engine doesn't
  implement, corrupting every subsystem.

Corrected approach (now fully scoped, ready to write): chain base Subsystem,
create Mech__DamageZone, add mech-specific members + TakeDamage override, let the
zone stream per-type armour. Full detail in MECHSUB.NOTES.md; the staged
MechSubsystem__SubsystemResource (per-facing, BT411-copied) is flagged for
re-derivation.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

restoration/source410/BT/MECHSUB.NOTES.md

@@ -0,0 +1,71 @@
+# MECHSUB — reconstruction notes (phase 2 kickoff, 2026-07-19)
+
+**Status: base-class ANALYSIS done; the reconstruction must be done FRESH against
+the 4.10 structure, NOT backdated from BT411 (its base class + damage model
+diverge). Key findings below de-risk the actual code.**
+
+MechSubsystem is the base of the ~30-class subsystem roster (sensor, gyro, torso,
+hud, generator, myomers, weapons…) the Mech ctor's segment-table walk
+instantiates. The staged MECHSUB.HPP is interface-only (one `Mech *owner`
+member, no bodies). Reconstructing the base is phase-2 step 1.
+
+## Dependencies (all survive in the 4.10 archive)
+
+- `Subsystem` (CODE/RP/MUNGA/SUBSYSTM.HPP) — the base.
+- `DamageZone` (CODE/RP/MUNGA/DAMAGE.HPP/.CPP) — the engine damage zone.
+- `Mech__DamageZone : public DamageZone` (CODE/BT/BT/MECHDMG.HPP) + the BT damage
+  model (MechCriticalSubsystem, redirect tables, critical hits).
+- `AlarmIndicator` (just reconstructed, MUNGA/ALARM.HPP) — statusAlarm.
+
+## Finding 1 — the base Subsystem DECLARES the zone but does NOT create it (RESOLVED)
+
+SUBSYSTM.HPP:181 declares `DamageZone *damageZone;` in the **base** Subsystem and
+its TakeDamage (SUBSYSTM.HPP:177-178) delegates `damageZone->TakeDamage(damage)`.
+The base ctors ARE reconstructed — **staged source410/MUNGA/SUBSYSTM.CPP** (built,
+in munga.lib; 38 Subsystem:: syms in the map). Both base ctors set
+`damageZone = NULL` (resource ctor line 63) — the base does **not** allocate the
+zone. So the DERIVED MechSubsystem creates the `Mech__DamageZone` (BT411's
+zone-creation is structurally right here) — but the ARMOUR it seeds must follow
+Finding 2 (per-type streamed), not BT411's per-facing hand-seed.
+
+## Finding 2 — CRITICAL: the damage model diverged
+
+The 4.10 base DamageZone (DAMAGE.HPP/CPP) is a **per-damage-TYPE** model:
+- members: `defaultArmorPoints` (Scalar) + `damageScale[Damage::DamageTypeCount]`
+  where DamageTypeCount = 5 = {Collision, Ballistic, Explosive, Laser, Energy}.
+- TakeDamage: `damageLevel += damage.damageAmount * damageScale[damage.damageType]`
+  (DAMAGE.CPP:413); the zone STREAMS its own armour (`*stream >> defaultArmorPoints;
+  *stream >> damageScale[ii]`, DAMAGE.CPP:335,340).
+
+BT411's reconstruction is a **per-FACING** model: `armorByFacing[5]` (front/back/
+left/right/top) + `structureReference`, **manually seeded** by MechSubsystem's
+resource ctor with an armour→absorption-coefficient inversion. Those field names
+(`armour[5]`, `structureReference`) exist only in BT411's `ReconDamageZone`
+proxy — NOT in the surviving 4.10 DamageZone/Mech__DamageZone. The staged
+`MechSubsystem__SubsystemResource` (armorByFacing[5]+structureReference) was
+copied from BT411 and is likewise suspect for 4.10.
+
+**Consequence:** BT411's MechSubsystem ctor (heat.cpp/mechsub.cpp) CANNOT be
+backdated verbatim — it would install a damage model the 4.10 engine's DamageZone
+doesn't implement, corrupting every subsystem's damage behaviour. The 4.10
+MechSubsystem must let the base Subsystem + DamageZone stream ctor handle armour
+(per-type), not hand-seed per-facing values.
+
+## Corrected reconstruction approach (fully scoped — ready to write)
+
+1. ~~Pin the base Subsystem ctor~~ **DONE (Finding 1)** — staged SUBSYSTM.CPP sets
+   `damageZone = NULL`; MechSubsystem creates the `Mech__DamageZone`.
+2. Reconstruct MechSubsystem: chain the base Subsystem, `new Mech__DamageZone(this,
+   index)`, add the mech-specific members (statusAlarm = AlarmIndicator, vital
+   flag, alarmModel, criticalReference, collisionCriticalHitWeight,
+   printSimulationState, configureActivePress) and the TakeDamage override, using
+   the 4.10 **per-type** damage model — let the zone stream its own armour
+   (defaultArmorPoints + damageScale[5]); do NOT hand-seed BT411's per-facing
+   armorByFacing[5]/structureReference.
+3. Re-derive `MechSubsystem__SubsystemResource` against the 4.10 DamageZone stream
+   format (the staged struct's per-facing fields are BT411-copied and suspect).
+4. Then the roster (GAUSS/PPC/SENSOR source + .TCP partials + decomp).
+
+Analysis complete; step 2 is the next code to write. This worksheet is the
+deliverable that keeps the subsystem foundation on the 4.10 damage model rather
+than BT411's divergent one.