# P3 — Locomotion Cutover (procedural slide → animation-driven gait)

Plan from the `p3-locomotion-cutover-scope` workflow (4 maps, source-verified). Goal: make BT movement
ANIMATION-DRIVEN (the walk/run clip's `[RootTranslation].z` IS the speed; feet plant by construction),
replacing the bring-up procedural slide + disconnected `gBodyAnim`.

## Ground truth (verified)
The real two-channel gait is reconstructed but **bracketed by no-op stubs on BOTH ends**, so it can't just
be "called on":
- **INPUT stubs:** `legAnimation@0x65c` / `bodyAnimation@0x6bc` are `ReconSeq` (mech.hpp:508-509);
  `ReconSeq::Advance()` returns 0, `SelectSequence`/`Reset` no-op, `keyframeData==NULL` (mechrecon.hpp:225-236).
- **OUTPUT stub:** `Matrix34 == ReconMatrix` no-op (mechrecon.hpp:460); its `SetRotation/FromQuaternion` write
  nothing → `IntegrateMotion`'s world-step (mech4.cpp:206-285) commits nothing even with nonzero input.
- `IntegrateMotion` is REAL logic (not a stub) but dead (input 0, output stub); its only caller `Mech::Simulate`
  (mech4.cpp:307) has 0 call sites. The live tick is bring-up `Mech::PerformAndWatch` (mech4.cpp:549).
- `LoadLocomotionClips` (mech3.cpp:325) would CRASH today (reads `keyframeData[..]` on the NULL stub).
- **The lever that already works:** `gBodyAnim->Animate(dt,True)` (mech4.cpp) runs the REAL engine
  `AnimationInstance::Animate` (JMOVER.cpp:1474-1700), cycling joints AND returning the clip's per-frame
  root-translation distance — which the stand-in threw away. That is the smallest safe cutover.

## Steps (each independently build+test; mech keeps moving throughout)
- **✅ STEP 1 — DONE (commit below): forward travel animation-driven via the working `AnimationInstance`.**
  Use the `adv` that `gBodyAnim->Animate(dt,True)` returns as the forward step (`localOrigin.linearPosition
  += facing * adv`); removed the `kDriveMaxSpeed * throttle * dt` slide (mech4.cpp). VERIFIED: mech walks at
  the clip's authentic ~60 u/s (was a guessed 30), FORWARD (−Z), feet plant (travel==stride); combat +
  damage un-regressed; no crash.
- **✅ STEP 2 — DONE: gait clip selection by throttle** (walk/run/reverse). `|throttle| >= 0.5` → run
  (`blhrrl` id 904), else walk (`blhwwl` id 898); throttle sign → direction (negative backs up); SetAnimation
  only on gait change (tracked by `gCurrentGait`). Added a forced-throttle VALUE (`BT_FORCE_THROTTLE=<v>`,
  btl4main.cpp) for headless testing. VERIFIED: run ~60 u/s, walk ~22 u/s (walk is ~1/3 of run — authentic
  per-clip speeds, NOT a scalar of one guess), reverse backs up (pos.z increases); combat un-regressed (enemy
  DESTROYED at walk speed, 8 hits). NOTE: the blh set has no dedicated reverse CYCLE clip (stand/walk/run +
  transitions only) → reverse plays the forward clip and drives the body backward (bring-up; real reverse in STEP 7).
- **STEP 3 — back the embedded controllers with real `AnimationInstance`** (`ReconSeq`→`AnimationInstance`,
  0x60 bytes each at 0x65c/0x6bc; adapters SelectSequence→SetAnimation, Advance→Animate, Reset, keyframe
  accessors). Infrastructure only; live path unchanged.
- **STEP 4 — call `LoadLocomotionClips(model)` at model build** (mech3.cpp:325) to populate
  `animationClips[]`/`namedClip[]` + stride caps (`standSpeed`, `walkStrideLength`, ...). Safe after Step 3.
- **STEP 5 — bring-up feed for `movementMode@0x40` + `bodyTargetSpeed@0x6b4` + `commandedSpeed`** from
  `gBTDrive.throttle` (the real `MechControlsMapper::InterpretControls` is deferred — reads unsafe App offsets).
- **STEP 6 — back `Matrix34`/`ReconMatrix` with the real engine affine matrix + base-region audit** of
  `IntegrateMotion`'s transform offsets (`+0x260` dual-use pos/quat suspected mislabel; `+0x100` labeled
  maxSpeed but used as `localToWorld`) vs `part_012.c`, anchored from `damageZoneCount@0x11c`.
- **STEP 7 — THE FULL CUTOVER:** run the real two-channel gait (`AdvanceLegAnimation`/`AdvanceBodyAnimation`
  + `IntegrateMotion`) in `PerformAndWatch`, retiring the Step-1/2 stand-in translation + free-standing
  `gBodyAnim`. Gives the authentic locally-simulated + displayed-motion gait.

**Deferred polish (post-core):** airborne/fall gaits (AdvanceBody/LegAnimationAirborne), torso-twist-to-target
(Torso is FULLY reconstructed — TorsoSimulation twist/elevation @004b5cf0 + WriteJoints; needs wiring), gyro sway.

**First-milestone recommendation:** Steps 1-2 give a visibly correct animation-driven walk/run (real speeds,
feet plant) on the already-proven engine path, with near-zero risk. Steps 3-7 are the deeper "authentic
two-channel gait" and can follow once the milestone is banked.

---

## ⭐ BASE-REGION RECONCILIATION (the STEP-6 audit — ground truth, the shared P3/P5/gyro de-risk)

This is THE root cause behind the P5 teardown crash, the gyro `+4` cross-link landmine, the dead `Mech::Simulate`
stomps, AND why `IntegrateMotion` can't be revived: the reconstructed `IntegrateMotion`/`Simulate` (mech4.cpp) use
**1995 raw binary offsets** (`this+0xNN`) that, in the 2007 RP411 engine base layout, land ON live engine fields.

**Ground-truth compiled layout (cdb `dt btl4!Mover` / `!JointedMover` / `!Mech`, from btl4.pdb):**
```
engine Mover/JointedMover:                          reconstructed Mech own region:
  +0x0C8 localToWorld (LinearMatrix)                  +0x3D4 torsoAimCurrent
  +0x0F8 localOrigin (Origin)                         +0x3E0 torsoAimTarget
  +0x114 damageZoneCount  +0x11C subsystemCount       +0x3EC netOrientation (EulerAngles)
  +0x124 updateOrigin (Origin)                        +0x458 movementMode   +0x45C movementFlags
  +0x194 creationTime (Time)                          +0x468 airborneSelect +0x46C forwardCycleRate
  +0x250 projectedOrigin (Origin)                     +0x4A4 groundCycleRate +0x4A8 airborneCycleRate
  +0x26C previousOrigin (Origin)                      +0x4C8 deathAnimationLatched
  +0x288 projectedVelocity (Motion)                   +0x4D4 legAnimation  +0x4E0 bodyAnimation (ReconSeq)
  +0x2A0 updateAcceleration (Motion)                  +0x500 arrivalTime  +0x504 simTime  +0x508 spinRate
  +0x2B8 updateVelocity (Motion)                      +0x598 motionEventName  +0x5A4 motionEventArmed
  +0x2D0 nextUpdate (Time)
  +0x2D4..0x2EC collision cluster (Count/Volume/Template/containedByNode/Lists/last/Assistant)
  +0x2F0 segmentTable  +0x308 segmentCount  +0x30C jointSubsystem   (JointedMover ends 0x318)
```

**The stomp table — every `IntegrateMotion` raw offset vs the engine field it corrupts, and the correct target:**
| raw offset (1995) | intended 1995 field | 2007 engine field it STOMPS | correct target (declared member) |
|---|---|---|---|
| `this+0x100` | motion payload A | `localOrigin` (0xF8-0x114) | (relocate) `motionPayloadA` |
| `this+0x12c` | motion payload B | `updateOrigin` (0x124-0x140) | (relocate) `motionPayloadB` |
| `this+0x260` | motionDelta (Quat) | `projectedOrigin` (0x250-0x26c) | **declare** `motionDelta` |
| `this+0x26c` | worldPose (Quat) | `previousOrigin` (0x26c-0x288) | **declare** `worldPose` |
| `this+0x298`/`0x29c` | angular accum | `projectedVelocity` (0x288-0x2a0) | **declare** `angularAccum` |
| `this+0x2a4` | torsoAimTarget | `updateAcceleration` (0x2a0-0x2b8) | ✅ existing `torsoAimTarget`@0x3E0 |
| `this+0x2d4` | netOrientation | `collisionVolumeCount` | ✅ existing `netOrientation`@0x3EC |
| `this+0x598`/`0x5a4` | motionEventName/Armed | (past base, in Mech region) | ✅ existing `motionEventName`/`motionEventArmed` |

So `torsoAimTarget`, `netOrientation`, `motionEventName/Armed`, `arrivalTime`, `simTime`, `spinRate`, `movementMode/
Flags`, cycle rates ARE already relocated as declared Mech members — but `IntegrateMotion` still reads the RAW
offsets for them AND for the 3 un-declared motion fields (`motionDelta`/`worldPose`/`angularAccum`) + the 2 motion
payloads. Reviving `IntegrateMotion` as-is would corrupt `projectedOrigin`/`previousOrigin`/`projectedVelocity`/
`updateAcceleration`/the collision cluster → exactly the P5 teardown heap corruption.

## STEP-6/7 attack (revised, concrete)
1. **Lock the ground truth** (compile-time): `friend struct MechBaseLayoutCheck` with `static_assert(offsetof(...))`
   on the engine-base fields (localOrigin@0xF8, projectedOrigin@0x250, previousOrigin@0x26c, collision cluster
   @0x2d4-0x2ec, segmentTable@0x2f0) + the relocated members (netOrientation@0x3EC, torsoAimTarget@0x3E0,
   arrivalTime@0x500, spinRate@0x508). Any future raw-offset stomp then fails the build.
2. **Declare the 3 missing motion members** (`motionDelta`/`worldPose` Quaternion, `angularAccum` Vector3D) +
   the 2 motion payloads in the Mech's OWN region (offset > 0x318), so nothing lands on the engine base.
3. **Convert every `IntegrateMotion` raw `this+0xNN` (0xNN < 0x318) to the declared member** per the table above.
   Same pass for the dead `Simulate` (so it's revivable) — this is the base-region audit HARD_PROBLEMS wanted.
4. **Back the 3 stub families with real engine types:** `ReconMatrix`→`AffineMatrix` ops (Identity/FromQuaternion/
   transform-vector); `ReconQuat*`→real `Quaternion`; `ReconSeq`→real `AnimationInstance` (the two-channel gait
   input, 0x60 bytes each @legAnimation/bodyAnimation).
5. **Revive `IntegrateMotion` in `PerformAndWatch`** (the cutover), retiring the Step-1/2 stand-in translation.
   Verify: mech walks via the real gait, no engine-base stomp, no teardown crash, combat/heat un-regressed.

Payoff: this ALSO fixes the gyro cross-link (write to the correct relocated field, not gyro+4), makes the dead
`Simulate` revivable, and removes the P5 teardown corruptor — the single highest-leverage de-risk in the port.

### PROGRESS (this pass)
- ✅ **STEP 1 — layout locked:** `MechBaseLayoutCheck` (mech4.cpp, friend of Mech) static_asserts the engine-base
  offsets (localOrigin@0xF8, projectedOrigin@0x250, previousOrigin@0x26c, collision cluster@0x2d4-0x2ec,
  collisionLists@0x2e4, segmentTable@0x2f0) + the relocated members (torsoAimTarget@0x3E0, netOrientation@0x3EC,
  arrivalTime@0x500, spinRate@0x508). All pass — the ground truth is proven in code; any stomp now fails the build.
- ✅ **STEP 2/3 (partial) — declared the missing motion members** (mech.hpp, appended so no locked offset shifts):
  `motionDelta`/`worldPose`/`worldPoseBase`/`angularAccum` (Quaternion) + `motionSourceA/B`/`motionEventVector`
  (Vector3D).  **Converted the LIVE-PATH functions** `IntegrateMotion` (@004ab1c8) and `DeadReckonPose` (@004ab188)
  — every raw `this+0xNN` (<0x318) now uses the declared member (0x260→motionDelta, 0x26c→worldPose, 0x298→
  angularAccum, 0x100/0x12c→motionSourceA/B, 0x598→motionEventVector, 0x2a4→torsoAimTarget, 0x2d4→netOrientation,
  0x138→worldPoseBase).  Build green, combat un-regressed (TARGET DESTROYED, 0 crashes).  The dead `Simulate`
  (@004ab430) still holds raw offsets — DEFERRED (off the cutover path; convert when/if reviving it).
- ✅ **STEP 4 (partial) — `ReconMatrix` backed** with the real engine `AffineMatrix` (mechrecon.hpp): `Identity`→
  `BuildIdentity()`, `FromQuaternion`/`SetRotation`→`operator=(const Quaternion&)`.  SAFE: its only live caller
  (IntegrateMotion) uses a LOCAL `bodyFrame`; other callers are the dead Simulate.
- ✅ **STEP 4 — `ReconQuat` backed** (mechrecon.hpp): `ReconQuatIdentity`→`Quaternion::Identity`,
  `ReconQuatIntegrate`→`Quaternion::Add(source, Vector3D delta)` (the exact FUN_00409f58 integrate).  SAFE: all its
  callers are dead (Simulate + the dead-until-cutover IntegrateMotion/DeadReckonPose).  Also relocated the last
  live-adjacent raw offset: the `this+0x1dc` "aim/torso" clear → a declared `aimRate` (Quaternion) member.  (NOTE: I
  earlier miscalled mech4.cpp:447 a LIVE PerformAndWatch call — it is actually in the dead `Simulate` telemetry tail
  (<0x551 where PerformAndWatch starts), so ReconQuat had no live caller after all.)  Build green, combat un-regressed.
- ⚠ **STEP 4 remaining — the GAIT (`ReconSeq`) is the hard final piece, NOT a drop-in.**  Verified: the leg/body
  controllers use `SelectSequence`/`Advance`/`Reset` (FUN_004277a8/0042790c/004283b8) — a BT-specific **SequenceController**
  keyframe player that **does NOT exist in the RP411 engine** (grep of MUNGA found no SelectSequence/Sequence/Controller).
  So "ReconSeq→AnimationInstance" (the STEP-3 note) is inaccurate.  TWO approaches, a real fork:
    (A) **Reconstruct the SequenceController** from the binary (FUN_004277a8/0042790c/004283b8 + its keyframe-table
        struct) and keep the authentic two-channel gait (AdvanceLeg/BodyAnimation + IntegrateMotion).  Most faithful;
        biggest.  NOTE: retyping legAnimation/bodyAnimation to the full controller GROWS the Mech (they are ~0xC now vs
        the binary's 0x60 each), shifting the relocated members after them (arrivalTime/spinRate) — update those
        MechBaseLayoutCheck locks (they are by-name relocations, safe to move; the engine-base locks must NOT move).
    (B) **Rewrite AdvanceLeg/BodyAnimation onto the engine `AnimationInstance`** (which STEP 1-2 already proved can
        play the gait clips).  Less faithful to the exact controller, reuses the engine, no SequenceController rebuild.
  Also still a stub: **`FUN_00408744`** (mechrecon.hpp:391) — the world-step transform (transform angularAccum by the
  bodyFrame matrix) IntegrateMotion needs; back it (AffineMatrix·Vector3D) as part of the cutover.
- **STEP 7 (revive) is unchanged** but gated on the gait decision above.

---

## ⭐ SequenceController RECONSTRUCTION SPEC (chosen path A — from the binary, part_003.c)

The BT gait controller (embedded `legAnimation`@0x65c / `bodyAnimation`@0x6bc, 0x60 bytes each). It is a BT-specific
keyframe animation player (NOT in the RP411 engine). Full decomp read: ctor @00427768, SelectSequence @004277a8,
Advance @0042790c, Reset @004283b8, dtor @004278d4. It parses the SAME animation-clip resource format the engine
`AnimationInstance` uses and writes joints through the SAME `Joint` API already backed for the gyro/torso.

**Object layout (0x60; offsets are byte offsets into the controller):**
```
+0x00 vtable (Plug base, FUN_00415e90 ctor)      +0x34 rootTranslation[] table (0xC/frame; .z@+8 = stride)
+0x0c (base refcount region)                      +0x38 jointSubsystem  (resolved from owner Mech +0x31c)
+0x14 frameCount   (resource hdr[0])              +0x3c currentFrame (int)
+0x18 jointCount   (resource hdr[1])              +0x40 owner (Mech*)
+0x1c jointIndices[] (jointCount ints)            +0x44 clipResource (ref-counted handle)
+0x20 hdr+2 (metadata ptr)                        +0x48 finishedCallback  (Mech method ptr)
+0x24 frameTimes[]  (frameCount floats)           +0x4c cbArg2   +0x50 cbArg3
+0x28 keyframeBase   +0x2c keyframeCursor         +0x54 currentTime (Scalar)
```
**Methods (behaviour + engine mapping):**
- **ctor(mech):** Plug base; store owner@0x40; `jointSubsystem@0x38 = mech->GetJointSubsystem()` (binary resolves
  mech+0x31c); clipResource@0x44 = 0.
- **SelectSequence(clipID, cb, a2, a3):** store cb@0x48/a2@0x4c/a3@0x50; reset currentFrame@0x3c + currentTime@0x54;
  release old clipResource; `FindResourceDescription(clipID)` → clipResource@0x44; parse the clip: frameCount@0x14,
  jointCount@0x18, jointIndices@0x1c, frameTimes@0x24, keyframe pointers@0x28/0x2c; compute the per-frame keyframe
  stride@0x34 by summing joint DOF sizes (hinge<3 →8B, ball==4 →0xC, balltrans==5 →0x18).
- **Advance(dt, moveJoints) -> Scalar distance:** `t = currentTime + dt`.  Walk keyframes while `frameTimes[cur] <= t`:
  for each joint (jointSubsystem->GetJoint(jointIndices[i])) snap to the keyframe pose (hinge→SetRotation(Radian),
  ball→SetRotation(EulerAngles), balltrans→ + SetTranslation) IF moveJoints; accumulate `distance += (frameTimes[cur]
  - currentTime) * rootTranslation[cur].z`; advance cur/currentTime.  If clip ended (cur==frameCount): call the
  finishedCallback (owner->*cb)(clipResource, carryover, moveJoints) and add its distance.  Else interpolate the
  partial frame (ratio = (t - currentTime)/(frameTimes[cur]-currentTime)); per joint LERP/SLERP between keyframes
  (FUN_00409390 slerp / FUN_00408848 translation-lerp / FUN_00408dd4 hinge-lerp) and write; accumulate the partial
  distance.  Return distance.  Engine helper map: joint iter→`JointSubsystem::GetJoint`; GetEulerAngles=FUN_0041cfa0;
  SetRotation(Radian)=FUN_0041d0a8; SetRotation(EulerAngles)=FUN_0041d020; SetTranslation=FUN_0041d11c;
  SetHinge/direct=FUN_0041cfc8; close-enough=FUN_00408d78(radian)/FUN_004091f4(euler)/FUN_004084fc(point);
  slerp=FUN_00409390; fabsf=FUN_004dcd00.
- **Reset(loop):** reset each joint to a default pose (identity quat + default euler/translation) via the per-type set.
- **dtor:** reinstall vtable + release clipResource.

**Wiring:** replace the `ReconSeq` stub (mechrecon.hpp) with this class (keep a `typedef ... ReconSeq` so mech2's
`legAnimation.SelectSequence/Advance/Reset` calls are unchanged); retype is automatic.  The Mech GROWS (0xC→0x60 per
controller = +0xA8) → move + update the by-name locks after them (arrivalTime/simTime/spinRate); engine-base locks
UNCHANGED.  The Mech ctor must construct legAnimation/bodyAnimation with `this` (owner).  Then STEP 7 cutover.

### ✅ BUILT (seqctl.cpp) — the SequenceController is reconstructed, linked, integrated (inert until the cutover)
- `SequenceController` class in mechrecon.hpp (extends the old ReconSeq: keeps keyframeCount/keyframeTimes/keyframeData
  accessors for mech3; adds the real fields; `typedef SequenceController ReconSeq`).  `seqctl.cpp` implements Init
  (ctor logic — resolves `owner->GetJointSubsystem()`), SelectSequence (find via `application->GetResourceFile()->
  SearchList(clip_id, 16)` + Lock + parse frameCount/jointCount/jointIndices/frameTimes/pose-base/rootTranslations),
  Advance (snap full keyframes + interpolate the partial frame via the engine Joint API, accumulate the
  rootTranslation.z distance, loop at end-of-clip), Reset (neutral pose per joint type), dtor (Unlock the clip).
  `Hinge`==8B confirmed (`{int axisNumber; Radian rotationAmount}`) → keyframe hinge snap `SetHinge(*(Hinge*)cursor)`
  is byte-faithful.  Joint I/O reuses the same engine API the gyro/torso use (GetJointType/GetEulerAngles/GetTranslation
  / SetHinge/SetRotation(Radian|EulerAngles)/SetTranslation).
- Added seqctl.cpp to btbuild/CMakeLists.txt.  Full build GREEN; combat un-regressed (TARGET DESTROYED, 0 crashes).
  Inert for now: its callers (mech2 AdvanceLeg/BodyAnimation via IntegrateMotion, mech3 LoadLocomotionClips) are all
  DEAD until the cutover, so the retype + link changes no live behavior.
- **Two known simplifications to revisit at the cutover (STEP 7):** (a) end-of-clip currently loops directly (reset to
  frame 0) instead of invoking the stored member-fn-ptr finished-callback @0x48 — faithful in INTENT (that callback is
  Mech::OnBodyAnimFinished's re-arm), refine if a non-looping callback is needed; (b) partial-frame rotation uses a
  component LERP of the euler/hinge (the binary FUN_00409390 slerps) — visually identical for small gait deltas, upgrade
  to slerp if needed.
- **Remaining for STEP 7 cutover (task 13):** (1) Mech ctor must call `legAnimation.Init(this)` + `bodyAnimation.Init(this)`
  (currently default-constructed with jointSubsystem=0 — fine while inert, REQUIRED before use); (2) call
  `LoadLocomotionClips(model)` at model build to populate the clips; (3) back the `FUN_00408744` world-step transform;
  (4) revive `IntegrateMotion` in `PerformAndWatch`, retiring the STEP-1/2 stand-in.  First point where it all
  runtime-verifies together.

### ✅ STEP 7 CUTOVER — DONE & VERIFIED LIVE (gated `BT_GAIT_CUTOVER=1`; the real controller drives locomotion)
Rather than reviving the FULL `IntegrateMotion` (leg+body channels + world-step + DeadReckonPose, whose position-apply
lives in the dead `Simulate`/`MoveAndCollide`) in one leap, the cutover swaps the STEP-1/2 forward-step SOURCE to the
real `SequenceController` on the PROVEN position path (`localOrigin += facing*adv`).  This runtime-verifies the
reconstructed controller with minimal risk and is the meaningful milestone (the authentic gait controller drives the
mech).  Implemented + verified:
- **(1) DONE** — Mech ctor (`mech.cpp`, after the body-load `ResolveJoint("jointlocal")`, where `jointSubsystem` is
  valid) calls `legAnimation.Init(this)` + `bodyAnimation.Init(this)`.  Runs always (harmless when the cutover is off).
- **cutover branch** — `PerformAndWatch` (mech4.cpp), gated `static int s_gaitCutover = getenv("BT_GAIT_CUTOVER")`.
  On a gait CHANGE it `bodyAnimation.SelectSequence(ResolveAnimationClip("blh",suffix), (void*)1 /*loop*/, 0, 0)`; each
  frame `adv = bodyAnimation.Advance(dt,1)` (the real controller animates the skeleton AND returns the clip forward
  step) → `localOrigin.linearPosition += facing*adv*dir`.  STEP-1/2 `gBodyAnim` path preserved as the `else` (default).
- **KEY BUG (found via cdb av in `ResourceFile::SearchList+0x77`, RESOURCE.cpp:498):** `SelectSequence` fetched the
  clip with `rf->SearchList(clip_id, 16)` — but `SearchList(list_id,type)` treats its arg as a resource LIST (reads the
  resource's data as an ID array + iterates) → it walked clip 904's animation bytes as garbage resource IDs → crash.
  The `clip_id` from `ResolveAnimationClip` is already a DIRECT resource ID → fixed to `rf->FindResourceDescription(clip_id)`
  + `Lock`, which mirrors the engine's own clip load `AnimationInstance::SetAnimation` (JMOVER.cpp:1406) EXACTLY (same
  header layout too: hdr[0]=frameCount, hdr[1]=jointCount, hdr[2]=footStepThreshold skipped, hdr[3]=jointIndices).
- **Verified live under cdb** (`BT_FORCE_THROTTLE=1 BT_GAIT_CUTOVER=1`): `[gait] SequenceController -> blhrrl id=904
  (run)`, mech walks (adv≈1.07, matching the STEP-1/2 baseline; pos advances), 0 crashes.  Combat regression
  (`+BT_SPAWN_ENEMY +BT_FORCE_FIRE`): identical to a same-harness BASELINE (no-cutover) run — both fire/heat/damage the
  same (`FIRED #1..#141`, `structure` climbs 0.133/hit) and both walk PAST the stationary dummy before 8 hits (no
  DESTROY in-window) — i.e. NOT a regression, just harness geometry.  `SequenceController::Advance` runs live for the
  first time with no crash.
- **DECOMP FACT (`Advance@0042790c` raw, part_003.c:6722):** distance is LUMPY BY DESIGN — whole keyframes add
  `(frameTimes[cur]-currentTime)*rootTrans[cur].z` (matches seqctl.cpp:217); the partial-frame else-branch (6821)
  interpolates joints but adds NO distance; end-of-clip (6814) CALLS the finished-callback `@0x48` recursively (passing
  the carryover time) and folds its return into distance.  Smoothness in the real game comes from VELOCITY integration
  in `IntegrateMotion`, not per-Advance — so applying `adv` directly to position (this cutover) is inherently lumpy;
  that's expected, faithful to the distance fn, and superseded once the velocity path lands.
- **STILL GATED (not default) pending fidelity refinements:** (a) end-of-clip `carryover*stride[last]` in place of the
  recursive finished-callback `@0x48` (source of the occasional adv spike at loop boundaries — needs `OnBodyAnimFinished`
  wired as the real member-fn-ptr callback that re-arms + recursively continues `Advance`); (b) component-LERP → slerp
  (`FUN_00409390`); (c) the deep win — the FULL `IntegrateMotion` velocity path (leg+body via mech2 `AdvanceLeg/
  BodyAnimation`, the `FUN_00408744` world-step, `DeadReckonPose`) which smooths the lumpy step and enables MP dead-reckon.

### ✅ STEP 7 DEEPER — the AUTHENTIC world-step (real velocity model) drives locomotion LIVE
Took the "harder path": replaced the cutover's direct position slide with the real `IntegrateMotion`
motion-tail (`@004ab1c8`), so the mech now moves through the authentic velocity→rotate→integrate model.
- **`FUN_00408744` BACKED** (mechrecon.hpp; was a no-op template stub): the world-step matrix×vector
  (part_000.c:8331, `out[i]=Σ_j v[j]·M(i,j)`). Backed via the engine `AffineMatrix::GetFromAxis` column
  basis — `out = v.x·colX + v.y·colY + v.z·colZ` reproduces the raw row-dot EXACTLY, and it is the SAME
  `GetFromAxis` convention the drive facing uses, so sign-consistent. Only real caller = mech4.cpp:304
  (gyro only name-drops it in comments).
- **KEY MAPPING (verified):** the 1995 motion transform `{ Point3D @0x260; Quaternion @0x26c }` IS the
  engine `localOrigin` — `Origin = { Point3D linearPosition; Quaternion angularPosition }` (ORIGIN.h:15);
  raw `FUN_0040ab44` builds the matrix from BOTH halves (rot from 0x26c, translation from 0x260). So the
  motion state maps directly onto `localOrigin`, NOT the parallel `motionDelta`/`worldPose` placeholders.
- **Cutover branch now (mech4.cpp):** `adv = bodyAnimation.Advance` → `localVel = {0,0,-adv/dt}` →
  `Matrix34::FromQuaternion(orient, localOrigin.angularPosition)` → `FUN_00408744(worldVel, localVel,
  orient)` → `localOrigin.linearPosition += worldVel*dt`. == `facing*adv`, through the real machinery.
- **Latent bug fixed** in the (still-dead) full `IntegrateMotion`: it set only `spinRate`@0x508 and left
  `angularAccum[2]` (velocity.z the world-step reads) stale → now sets `angularAccum[2] = -adv/dt`.
- **Verified:** walk-only `BT_GAIT_CUTOVER=1` walks straight fwd ~60 u/s, 0 crashes; combat fire/damage
  identical to STEP-1/2. ⚠ A combat run faulted in the ENGINE BGF loader (`bld08.bgf`, `Builder::~Builder`)
  walking into a building's range — pre-existing heap fragility, position-dependent (STEP-1/2 fired 600+
  clean), NOT the world-step (zero heap ops). Track separately.

### Remaining full-`IntegrateMotion` work (the rest of the harder path)
1. **`AdvanceBodyAnimation` gait STATE MACHINE** (mech2.cpp:506, real — stand→walk→run transitions via
   `SetBodyAnimation(state)` → `animationClips[state]`) in place of the inline `ResolveAnimationClip`+
   `SelectSequence`. Needs #2.
2. **`LoadLocomotionClips`** (mech3.cpp:326, real) called at model build (Mech ctor) to populate
   `namedClip[]`/`animationClips[]` + gait-speed caps (standSpeed/walkStride/reverseSpeedMax/gimp…) —
   measured via `legAnimation.SelectSequence` + `keyframeData` (now that the SequenceController is real).
   OPEN: reconcile `namedClip[]`@0x5e0 vs `animationClips[]`@0x5cc + the state→clip index mapping.
3. **Orientation INTEGRATION** — the real turn is angular-rate integration into `localOrigin.angular
   Position` (raw `FUN_00409f58(0x26c, 0x26c, angRate*dt)`), driven by control input, not the bring-up
   `gDriveHeading`. (Bring-up keeps `gDriveHeading` until the controls mapper is un-bypassed.)
4. **Velocity STORAGE + `DeadReckonPose`** — store the world velocity (raw @0x298) for MP dead-reckon;
   `DeadReckonPose(fraction)` projects the render pose forward between sim ticks (the true render smoothing).
5. Then call the real `Mech::IntegrateMotion` (retargeted to `localOrigin`) from the cutover, retiring the
   inline world-step.

### ✅ STEP 2 (steps 1-2 of the full IntegrateMotion) — LoadLocomotionClips + the gait STATE MACHINE drive the walk LIVE
Gated `BT_GAIT_SM` (requires `BT_GAIT_CUTOVER`).  The real `Mech::AdvanceBodyAnimation` now drives locomotion.
- **Step 1 — `LoadLocomotionClips`** called in the Mech ctor (gated), completes cleanly for the Blackhawk:
  resolves the full gait set + measures the speed caps (verified `walkStride=22.02`, `standSpeed=6.83`).
  **RECONCILIATION FIX:** `namedClip[]`@0x5e0 and `animationClips[]`@0x5cc were declared as SEPARATE arrays
  but in the binary are ONE (`namedClip[i]==animationClips[i+5]`, 0x5e0==0x5cc+0x14) -> the loader's writes
  weren't visible to `SetBodyAnimation`/`MeasureClipStride`.  Fixed: `namedClip` is a pointer aliased to
  `&animationClips[5]` (ctor).  Same class of bug as the field-shadowing systemic issue.
- **Step 2 — `AdvanceBodyAnimation` state machine** drives the walk: case 6/7 slews `bodyCycleSpeed` toward
  `bodyTargetSpeed` with the loaded caps, Advances `animationClips[6]=wwr`, returns the cycle distance ->
  world-step.  **FIX:** `bodyAnimationState`@0x728 == `bodyStateAlarm.level` (also declared-separate) -> re-synced
  from the alarm at the top of AdvanceBodyAnimation so `SetBodyAnimation`'s level reaches the switch.
- Verified live: mech walks forward (z 1600->-975), `adv~0.35-0.42` (authentic walk cadence, < run's 1.07),
  clip loops its 15 keyframes, 0 crashes.
- **Bring-up substitute (MARKED, mech2.cpp):** `SetBodyAnimation` passes a non-null loop sentinel `(void*)1`
  where the binary passes `PTR_LAB_0050d6fc` = the real body finished-callback (gait TRANSITION stand->walk->run
  + leg alternation, @0x48).  Without a non-null cb the SequenceController leaves the cycle stuck at its last
  keyframe (`adv=0`).  Reconstruct `PTR_LAB_0050d6fc` for authentic transitions.

### Remaining for the FULL gait (after steps 1-2)
1. **Reconstruct `PTR_LAB_0050d6fc`** (+ the leg `PTR_LAB_0050d6f0`) -- the finished-callback that transitions
   gait states (stand->walk->run->reverse) + alternates legs.  Replaces the `(void*)1` loop sentinel.
2. **LEG channel** `AdvanceLegAnimation` for visible leg stepping (body channel already drives world motion).
3. **Gait SELECTION** from throttle -> `bodyTargetSpeed`/`movementMode` (currently forces walk state 6);
   wire walk/run/reverse via the real commanded speed (the `MechControlsMapper` is still bypassed).
4. Then orientation integration + velocity storage + DeadReckonPose (the later IntegrateMotion pieces).

### ✅ TRANSITION CALLBACK — reconstructed + wired (walk/run leg alternation + walk->run transition)
The real gait finished-callback (was a `(void*)1` loop sentinel).
- **Resolved the .data fn ptr by PE-parsing** BTL4OPT.EXE: `PTR_LAB_0050d6fc`@0x50d6fc -> body cb **0x4a6d8c**;
  `PTR_LAB_0050d6f0`@0x50d6f0 -> leg cb **0x4a6928**; cbArg2/3 = 0.  Neither in the assert-anchored decomp, so
  **disassembled with capstone** + decoded the jump table (byte idx @0x4a6de9, dword targets @0x4a6e0a; 33 states
  -> 10 handlers).  Reusable: `/tmp/readptr.py` (PE VA->DWORD) + `/tmp/disas.py`, `/tmp/jt.py`, `/tmp/dh*.py`.
- **Reconstructed `Mech::BodyClipFinished` (= FUN_004a6d8c)** byte-for-byte (mech2.cpp): dispatch on
  bodyAnimationState, compare bodyTargetSpeed to the caps (standSpeed/walkStrideLength/reverseSpeedMax), pick the
  next state, `SetBodyAnimation(next)` (re-binds with THIS callback) + `bodyAnimation.Advance(carryover-derived)`
  via the shared tail `Mech::BodyTransition`.  Walk 6<->7, run 12<->13, stop->8/9, walk->run 6->11->12.
- **Plumbing:** `SequenceController::Advance` now CALLS `cbCode` as `Scalar(*)(Mech*,unsigned,Scalar,int)` at
  end-of-clip (matches the binary `**(code**)(this+0x48)`), folding the returned distance.  `SetBodyAnimation`
  passes `&Mech::BodyClipFinished`; the inline cutover passes `&Mech::LoopBodyClip` (bring-up loop).
- **Verified live (cdb):** walk alternates 6<->7 (adv~0.42), run alternates 12<->13 (adv~0.5-0.85), walk->run
  transition fires (6->11->12), pos advances, 0 crashes; inline cutover (LoopBodyClip) + combat un-regressed.
- **Fixed a bring-up gap:** `reverseSpeedMax2`@0x7a0 (run bodyCycleSpeed clamp) unset by LoadLocomotionClips ->
  0xCDCDCDCD -> run exploded; set to reverseStrideLength (case-12 divisor -> ratio~1).
- **Remaining:** LEG callback FUN_004a6928 (state@0x3b0 + motion source@0x128); airborne FUN_004a6344; gimp
  handlers (16-19; targets 0x70b2/0x7161 undecoded); gait SELECTION from real throttle (mapper still bypassed).

### ✅ PILLAR A COMPLETE — leg channel + orientation + velocity storage + DEFAULT-ON
- **LEG finished-callback** FUN_004a6928 (== PTR_LAB_0050d6f0) reconstructed (`Mech::LegClipFinished`,
  mech2.cpp): jump table @0x4a69aa decoded (same 33-state shape as the body's); compares the LIVE mapper
  speedDemand (*(subsystemArray[0])+0x128 -> typed mirror controlsMapper), slews legCycleSpeed@0x348,
  re-arms via SetLegAnimation; gimp alternates 0x12<->0x13 with |ratio| (gimpStrideLength stored negative).
- **Two-channel split LIVE** (real-controls): leg = joints from live demand, body = motion only
  (Advance(dt, 0)).  Natural Standing entry verified: legState 0 -> 5 -> 11 -> 13<->12 @ 61.5 u/s.
- **RAW FIX: Standing case INVERTED in BOTH channels** (raw case 0: standSpeed < commanded -> walk(5);
  commanded < 0 -> reverse(0x10); else stand).  Also: AdvanceLegAnimation controlSource double-deref AV ->
  controlsMapper->speedDemand; legAnimationState==legStateAlarm.level re-sync.
- **Orientation**: yaw rate composed via Quaternion::Add (FUN_00409f58 form) -- spawn orientation kept
  authentic (turn-rate constant still bring-up).
- **Velocity storage every frame**: worldLinearVelocity + localVelocity (fwd -Z + yaw rate) == the
  Mover::WriteUpdateRecord publish set = the MP dead-reckon writer data.
- **DEFAULTS FLIPPED** (BTEnvOn): BT_GAIT_CUTOVER / BT_GAIT_SM / BT_COLLISION / BT_REAL_CONTROLS default
  ON; "=0" opts back to the bring-up paths (verified).  BT_SPAWN_ENEMY now places the dummy along the
  spawn FACING (the authentic orientation exposed the old fixed-offset assumption).
- Verified: env-free default run = full authentic chain, combat damage -> 0.933, 0 crashes; all =0
  fallbacks work.  P3 is CLOSED for multiplayer purposes (the update-writer data is maintained).

### v5 (2026-07-09, task #49) — CHANNEL ROLES CORRECTED FROM RAW DISASM: display+travel = LEG
User-reported recurrence of "legs stutter / lose sync" (live [sync]: advSum/legSum drifted 5->92 during
walk-up churn then locked).  Reproduced headlessly (BT_FORCE_OSC feathering + BT_FORCE_TURN; per-frame
BT_SYNC_LOG probe): the SEED is the bring-up trn trigger arming only the LEG channel (walk re-entry lands
1 frame apart -> clip phase offset); the AMPLIFIER is a demand change landing between the two channels'
end-of-clip callbacks -> DIVERGENT next-state picks (one winds down, one keeps walking) -> opposite-phase
churn (observed bs=6 ls=7).  Under v4 (display+travel = body) the out-of-phase LEG pose showed through on
every frame the body didn't write (Standing/wind-down) = the visible stutter.
DISASM GROUND TRUTH (both Advance fns have NO static decomp caller; found by byte-scanning CODE for e8
calls): the master perf (0x4a9b5c gap region) calls AdvanceLegAnimation @0x4aa399 (airborne @0x4aa388) and
stores -dist/dt into localVelocity (+0x1cc) == the LEG drives local travel (and pose, writing last);
IntegrateMotion (0x4ab1c8; body advance @0x4ab312; caller FUN_004ab430 = the projected-origin updater)
stores -dist/dt into projectedVelocity (+0x2a0) == the BODY is the dead-reckoning PROJECTOR, locally
invisible.  v4's reading of 0x4ab430 as the travel source was WRONG.
FIX (mech4.cpp): advance body FIRST (projection; writes overwritten), leg LAST (displayed pose); travel =
legAdv under the two-channel split (travelAdv selector; single-channel path keeps adv).  Display == travel
through the LEG by construction; body drift can no longer show.  VERIFIED: trn+feather repro clean; straight
drive locked (adv==proj); solo goto=enemy kill chain intact; MP 2-node drive-to-range cross-pod kill intact
(hdlr=241, DESTROYED).  FOLLOW-UPS: wire the body adv into the named projectedVelocity member (the +0x2a0
store, currently diagnostic-only); locate the authentic trn entry dispatcher (would also arm... TBD).
New gated instruments: BT_SYNC_LOG (per-frame channel divergence), BT_FORCE_OSC=<s> (throttle feathering).