fix(physics): enforce retail step-down support radius (#273)

docs/architecture/retail-divergence-register.md

@@ -128,7 +128,7 @@ AP-94..AP-112 for the confirmed retail-UI completion gaps.
 |---|---|---|---|---|---|
 | AP-1 | Snap-path Z settle: validated claims ground on their own walkable polys, but floor-less claims (thresholds, stair lips) fall through to a legacy nearest-in-Z scan over every CellSurface in the landblock; retail settles via `CheckPositionInternal` → `find_valid_position` | `src/AcDream.Core/Physics/PhysicsEngine.cs:614` | `find_valid_position` unported; the **#111** fix narrowed the legacy pick's blast radius (validated claims bypass it) rather than replacing it | A threshold/stair-lip snap can still pick a neighbouring cell's same-height floor by iteration order — wrong cell or Z at login/teleport arrival (the #111 clobber class) | `SetPositionInternal` :283426 → find_valid_position |
 
-| AP-3 | Step-down chain triggered only when contact is invalid OR steeper than walkable; retail's `transitional_insert` OK-path ALWAYS runs it | `src/AcDream.Core/Physics/TransitionTypes.cs:1197` | Conditional preserves the observed-to-matter cases (edge departure, steep cliff-slide) without running the chain every step (per pc:273191 agent reports) | Steps where retail runs step-down despite a valid walkable contact (bump maintenance, edge-slide arming) are skipped — float-off or missed edge slides in untested geometry | `transitional_insert` OK-path pc:273191 |
+| AP-3 | Step-down chain also runs for a valid contact plane when that plane is steeper than walkable; retail's `transitional_insert` OK-path returns immediately for every valid contact plane and enters the step-down tail only when contact is invalid | `src/AcDream.Core/Physics/TransitionTypes.cs` (`TransitionalInsert`) | The added steep-contact entry preserves the current cliff-slide compensation while the response-layer state/order family remains open (AP-4/AD-53/AD-54/TS-4) | A steep valid contact can enter step-down/edge response where retail restores or validates state through its normal contact path, producing different retry and slide behavior | `CTransition::transitional_insert` 0x0050B6F0, named-retail pseudo-C pc:273191–273307 |
 | AP-4 | CliffSlide check moved BEFORE retail's Branch-1 (`!OnWalkable` → restore+OK) gate, compensating our L.2.3i FloorZ OnWalkable bookkeeping | `src/AcDream.Core/Physics/TransitionTypes.cs:1316` | Retail's order with our incomplete OnWalkable stops the player dead every frame on steep slopes ("stay on the roof"); reorder restores downhill drift | CliffSlide fires in states where retail's Branch 1 would restore-and-OK — body slides where retail holds, e.g. contact-plane-bearing steep geometry near edges | retail EdgeSlide dispatch order (transitional_insert step-down failure) |
 | AP-5 | Step-down skips Placement validation for the contact-maintenance call (`runPlacement=false`); ACE/retail run it unconditionally (kept for DoStepUp) | `src/AcDream.Core/Physics/TransitionTypes.cs:3393` | Residual wall-slide artifacts made Placement misfire, leaving players stuck near walls; the skip was the targeted L.2.3h fix | Step-down can settle into positions Placement would reject — slight wall embedding, or accepting a step-down through overlap geometry retail catches | `CTransition::step_down` pc:272952; ACE Transition.cs:731-741 |
 | ~~AP-7~~ | **RETIRED 2026-07-30 (Campaign P Slice P2) — the "state gate" was a BN decompiler artifact, not a locomotion exemption.** `calc_friction` now ports retail's confirmed 0.25f threshold (`if (angle >= 0.25f) return;`) unconditionally, no special-cased gate. The "state check at pc:276702" the old row cited is `PhysicsState.Sledding` (confirmed via ACE's `PhysicsObj.calc_friction`, references/ACE/Source/ACE.Server/Physics/PhysicsObj.cs:2120-2141, and `SLEDDING_PS=0x800000` in acclient.h:2838) — it gates the 1.5625/6.25/near-flat friction-value OVERRIDE, not the threshold return itself; acdream had no live Sledding setter then or now (see #166 research, docs/research/2026-07-30-response-layer-edge-family-pseudocode.md §3), so the branch was simply unreachable dead code, not an exemption for ordinary walking. The reverted 2026-04-30 L.3c attempt (naive 0.0→0.25 bump, forward locomotion 3→0.16 m/s in `PlayerMovementControllerTests`) does not reproduce on the production graphical local-player path post-R6: `PlayerMovementController` zeroes `Velocity.X/Y` to exactly zero every tick before `calc_friction` runs whenever animation root motion drives the walk, so friction has no horizontal velocity left to hammer (pinned at the PhysicsBody level by `GroundedRootMotion_FrictionThreshold_DoesNotHammerLocomotionTests`). The headless/`get_state_velocity` movement-controller path and remote/NPC movers still feed real velocity into this function and remain the ones to watch if a similar regression resurfaces there. **CORRECTION (2026-07-30, same day, #265/#166 capture bisect):** the sentence above undersold the gap — `calc_friction` wasn't merely "no horizontal velocity to hammer," it was structurally UNREACHABLE with meaningful data on ANY grounded path: (a) the animation-root-motion path zeroed `Velocity.X/Y` outright every tick (the actual #265/#166 root cause, ten days pre-existing, not a Campaign-P regression), and (b) `PhysicsBody.GroundNormal` — the vector `calc_friction` dots velocity against — had ZERO production writers anywhere and silently defaulted to `Vector3.UnitZ` forever, so even surviving velocity would have been tested against a fake flat-ground normal on any real slope. Both gaps are now closed: `PlayerMovementController.cs`'s grounded block no longer reconstructs `Velocity` for the animation-root-motion case, and `PhysicsEngine.cs` syncs `body.GroundNormal` from the committed `ContactPlane.Normal` at the same commit point that already publishes `ContactPlane`. The 0.25f threshold port itself (this row's original subject) was always correct — it just had nothing real to operate on until this fix. See `docs/research/2026-07-30-265-capture-bisect.md`'s as-fixed addendum. | `src/AcDream.Core/Physics/PhysicsBody.cs` (`calc_friction`); `src/AcDream.Core/Physics/PhysicsEngine.cs` (`GroundNormal` wiring); `src/AcDream.Runtime/Gameplay/PlayerMovementController.cs` (grounded-velocity fix); `tests/AcDream.Core.Tests/Physics/PhysicsBodyTests.cs` (AP-7 test block); `tests/AcDream.Core.Tests/Physics/Issue265SteepSlopeCaptureBisectTests.cs`; `tests/AcDream.Runtime.Tests/Gameplay/PlayerMovementControllerTests.cs` | — | — | `CPhysicsObj::calc_friction` pc:276694-276822 (0050ee70); ACE `PhysicsObj.calc_friction` PhysicsObj.cs:2120-2141; `docs/research/2026-07-30-response-layer-edge-family-pseudocode.md` §1; `docs/research/2026-07-30-265-capture-bisect.md` |

docs/research/2026-07-31-issue273-tight-gap-support.md

@@ -0,0 +1,95 @@
+# Issue #273 — Holtburg tight-gap support validation
+
+**Date:** 2026-07-31
+**Status:** implementation, automated gates, and exact live gate pass
+**Scope:** grounded player step-down support at a floor edge beside a static
+cylinder
+
+## Captured scene
+
+The reproducible gap is in outdoor cell `0xA9B40032`, between:
+
+- building shell GfxObj `0x01000F69`, placed at
+  `(158.178, 37.7055, 94.0)` with quaternion
+  `(w=.939319, x=0, y=0, z=-.343045)`;
+- static post `0xCA9B4027`, placed at `(160.173, 34.487, 95.975)`,
+  represented by its Setup-authored cylinder (`radius=.282`,
+  `height=5.564`);
+- the local player Setup's exact two spheres (`radius=.48`, origins
+  `z=.475` and `z=1.35`).
+
+The building's supporting ledge terminates at local `x=4`. The first
+post-side response moved the player's foot-sphere center to approximately
+local `x=4.33`. The full `.48` movement sphere still overlapped the floor, so
+the existing step-down path accepted the candidate. Repeated frames then
+carried the player around the post and outside the building shell.
+
+The fixture
+`tests/AcDream.Core.Tests/Fixtures/issue273/0x01000F69.gfxobj.json` preserves
+the installed DAT PhysicsBSP. The replay in
+`Issue273HoltburgTightGapReplayTests` uses the captured object placement,
+player spheres, static posts, and movement offsets.
+
+## Retail mechanism
+
+The missing rule is not extra collision padding and is not a larger player
+sphere. It is retail's second-stage support validation:
+
+1. `CTransition::step_down` (`0x0050B2A0`) performs the ordinary downward
+   collision probe.
+2. After finding a walkable contact plane, an EdgeSlide mover that is not in
+   StepUp calls `CTransition::check_walkable` (`0x0050AFF0`). The binary
+   sequence is `test ah,2` at `0x0050B36A`, which is state bit `0x200`
+   (`EdgeSlide`), followed by the `step_up == 0` test and call at
+   `0x0050B380`.
+3. `CTransition::check_walkable` first calls
+   `SPHEREPATH::check_walkables` (`0x0050C3E0`).
+4. `SPHEREPATH::check_walkables` halves the saved foot-sphere radius and
+   calls `CPolygon::check_walkable` (`0x00538E60`).
+5. If the remembered polygon does not support that smaller sphere,
+   `CTransition::check_walkable` performs a downward CheckWalkable insertion.
+   BSP leaves require both `walkable_hits_sphere` and
+   `CPolygon::check_small_walkable` (`BSPLEAF::hits_walkable`,
+   `0x0053D670`).
+6. If neither check finds support, `CTransition::step_down` rejects the
+   candidate and the existing edge-response chain handles it.
+
+ACDream already had the small-radius BSP-leaf test, but
+`DoCheckWalkable` treated the mere presence of a remembered polygon as
+success, and the ordinary `DoStepDown(..., runPlacement:false)` path never
+called it. This let a full-radius overlap stand in for actual foot support.
+
+## Port
+
+- `BSPQuery.CheckWalkableSupport` is the shared resolved-polygon form of
+  retail `CPolygon::check_walkable`.
+- `SpherePath.CheckWalkables` implements the retail half-radius remembered
+  polygon check without mutating canonical sphere state.
+- `Transition.DoCheckWalkable` now tests the remembered polygon rather than
+  treating a non-null polygon as sufficient.
+- `Transition.DoStepDown` restores the EdgeSlide/non-StepUp support gate
+  before the existing placement-policy seam.
+
+There are no location checks, object IDs, guessed radii, widened collision
+shapes, or gap-specific tolerances in the production fix.
+
+## Regression impact
+
+The existing #271 staircase-side replay begins with its center `.288 m`
+outside a tread whose retail half-radius support boundary is `.24 m`.
+Retail may therefore stop that exact candidate. The test now preserves the
+original user-visible invariant—never reverse or accelerate downhill—without
+requiring forward progress beyond retail's support boundary. The ordinary
+continuous staircase replay still requires and achieves forward progress.
+
+## Gates
+
+- issue #273 fixture/replay: 3 passed;
+- focused BSP, step-up, edge-slide, #185/#271 family: 42 passed / 1 skipped;
+- complete Core tests: 4,111 passed / 2 skipped;
+- Release solution build: passed;
+- complete Release solution tests: 10,068 passed / 5 skipped.
+
+The user accepted the exact in-client Holtburg gap gate on 2026-07-31: the
+gap blocks from the tested approach, and the adjacent movement checks remain
+healthy.