fix(grab): Euler-extract gimbal-lock tolerance — actual fix for the reported grab inversion

[JRickey]

Summary

Real fix for the "victim upside-down with torso clipped into ground" grab-hold bug. Supersedes PR #204 (which landed earlier today based on the TC fork's stale-FTParts-transform-cache diagnosis and turned out to be a no-op for the offline reproducer — kept as defensive coverage).

JR reproduced the bug after PR #204 merged: Pikachu → Samus on Dreamland, ~50° tilt visible on the held victim. Live trace under `SSB64_GRAB_TRACE=1`:

• `root_cache_pre = 0` and `hand_cache_pre = 0` on every one of 975 traced frames → PR fix(grab): port engine-only subset of TC grab-coupling geometry fixes #204's invalidate had nothing to clear.
• Actual hand world matrix's X-axis row: `(0.0025, -0.0030, 0.9999923110)`.
• `func_ovl2_800EDA0C` (`gm/gmcollision.c:285`) gimbal-lock branch uses exact float equality `dst[0][2] == 1.0F`. `0.9999923 != 1.0F` → general branch fires → `atan2(-0.003, 0.0025) = -0.866` extracted as `rotate.z` from quantization noise → ~50° spurious roll → tilted victim.

The check was always fragile; IDO/MIPS rounding lands at exact `1.0F` often enough that vanilla N64 works; modern toolchains' float math doesn't.

Fix

One-line tolerance under `#ifdef PORT` in `func_ovl2_800EDA0C`:

```c
#ifdef PORT
if ((dst[0][2] <= -0.9999F) || (dst[0][2] >= 0.9999F))
#else
if ((dst[0][2] == -1.0F) || (dst[0][2] == 1.0F))
#endif
```

`0.9999F` ≈ within 0.81° of pure ±90° yaw — narrow gimbal-lock window, doesn't trip for real rotations. After fix, trace shows `victim_out_rot.z = 0.000000` across the entire hold. Visual repro confirmed corrected by JR.

Also covers `scSubsysFighterOpeningProcUpdate` (Master Hand opening movie) which uses the same extraction pattern.

Files

• `decomp/src/gm/gmcollision.c` — the one-line tolerance
• `decomp/src/ft/ftcommon/ftcommoncapturepulled.c` — comment update only, noting PR fix(grab): port engine-only subset of TC grab-coupling geometry fixes #204's invalidate is defensive coverage rather than the offline fix
• `docs/bugs/grab_pose_eulerextract_gimbal_2026-05-23.md` — full investigation, repro methodology, audit hook for similar precision-sensitive matched-decomp patterns
• `docs/bugs/README.md` — index updated; PR fix(grab): port engine-only subset of TC grab-coupling geometry fixes #204's entry retitled "PARTIALLY APPLIES (defensive); not the offline-bug fix" so future readers don't chase the same wrong tree

Decomp commit `055659e35` on `JRickey/ssb-decomp-re#port-patches`.

Test plan

• Build clean (`cmake --build build --target ssb64 -j 4`), no new warnings
• Manual: Pikachu → Samus on Dreamland — victim upright in hold, no tilt (JR confirmed in-app)
• Trace confirms `victim_out_rot.z = 0.0` across 975 ticks of held grab
• Sanity: other grabber/victim pairs still hold correctly (no new tilt introduced by the tolerance widening — should be safe given 0.9999 = 0.81° band)
• Sanity: Master Hand opening movie still poses fighter models correctly (shares the `func_ovl2_800EDA0C` path)

🤖 Generated with Claude Code