acdream/docs/research/2026-08-08-345-d0-branch-pin.md

#345 D0 — branch pin, round 2: the routing is retail-faithful; the profile contradiction stands unresolved

Order: implementation session, per docs/research/2026-08-08-345-fix-contract.md and docs/research/2026-08-08-345-mechanism-contract.md. This session's mandate was to find the branch the first D0 pass (docs/research/2026-08-08-345-pseudocode.md) missed — the fix contract's premise, from the live cdb profile, is that retail's transitional_insert reaches edge_slide/cliff_slide every tick during the glide while ours dead-loops without ever reaching it.

Verdict: the premise's specific mechanism ("Adjusted lets the insert proceed to step-down, ours treats it as retry-from-scratch") is REFUTED by a clean re-trace and by two independent, empirical, byte-for-byte reproductions in a synthetic fixture. Our TransitionalInsert/InsertIntoCell/CheckOtherCells routing is faithful to the decompiled retail control flow for this exact topology (grounded-on-flat, step crosses into too-steep terrain). The contradiction against the live retail profile is real and unresolved — this session SOPS per the fix contract's explicit fallback rather than making an unproven change.

What this session did beyond the first D0 pass

The first pass (2026-08-08-345-pseudocode.md) traced ValidateWalkable, TransitionalInsert's switch, CheckOtherCells, ValidateTransition, and SetSlidingNormal, and concluded retail's own algorithm converges to the same zero-yield stop. It left one explicit open question: does retail's CObjCell::find_cell_list/our CellTransit.FindCellSet broadphase actually include the neighboring too-steep cell as an "other cell" to test, or does the narrower real geometry not reach it at all — a question it said needed a live cdb trace, not more code reading.

This session did three additional things the first pass did not:

1. Read CTransition::step_down (0x0050b2a0) in full — the function transitional_insert's step-down/edge-slide block actually calls before edge_slide. This is the literal mechanism the fix contract's hypothesis named. Confirmed: step_down sets sphere_path.step_down=1, moves check_pos.z -= arg2, and calls transitional_insert(this, 5) recursively at the LOWERED position — but this whole apparatus is gated behind transitional_insert's own if (edi == OK_TS) block (pc:273191, 0x0050b787), which is reached only when both the primary insert_into_cell and check_other_cells return OK_TS for the CURRENT (un-lowered) attempt.
2. Read CTransition::check_other_cells's switch (0x0050ae50, pc:272733-272753) byte-for-byte — case COLLIDED_TS/ADJUSTED_TS (2/3) both return result immediately, no further cells tried, no state reset. This is a clean 4-way integer switch on a virtual call's return value — no x87, no missing flag tests, no BN garbling. High confidence in this reading.
3. Built two independent synthetic terrain fixtures (not committed — thrown away after use, see below) and ran them through the real PhysicsEngine.ResolveWithTransition → Transition.FindTransitionalPosition → TransitionalInsert pipeline with the project's own instrumentation (ACDREAM_PROBE_STEP_WALK, ACDREAM_DUMP_TRANSIT_FAIL, ACDREAM_PROBE_INDOOR_BSP, ACDREAM_DUMP_EDGE_SLIDE) to get ground truth instead of continuing to hand-derive float comparisons.

The two empirical fixtures

Both: a grounded player-flagged mover (radius 0.48, ObjectInfoState.IsPlayer | EdgeSlide, oi.OnWalkable=true, oi.Contact=true), resting on flat terrain (N=(0,0,1)), given a diagonal (45°-ish) horizontal-only request that lands on a terrain triangle with N.z=0.6 (< PhysicsGlobals.FloorZ=0.6642, i.e. genuinely too steep — matching the fix contract's "N.z≈0.6" scenario).

Fixture A — steep triangle in a NEIGHBORING outdoor cell (request crosses a 24 m terrain-cell boundary). Result: the PRIMARY cell's terrain query is out-of-bounds for the new XY (SampleTerrainWalkableInCell's fixed-cell bounds check, PhysicsEngine.cs:1076-1080 — itself a documented, intentional retail mirror: "retail continues dispatching the captured CObjCell*") and passes through as OK. CheckOtherCells (TransitionTypes.cs:2999-3010) then finds the true neighboring cell, calls ValidateWalkable, gets the below-surface "too steep" branch (dist=-0.04, sp.StepDown=false at this point since we're still in the un-lowered outer attempt, walkable=false since N.z(0.6) < WalkableAllowance(FloorZ=0.6642)), returns TransitionState.Adjusted unconditionally (the branch always returns Adjusted regardless of whether the push guard fired — ValidateWalkable, TransitionTypes.cs:3785). ApplyOtherCellResult (TransitionTypes.cs:3316-3333) halts on Adjusted. RunCheckOtherCellsAndAdvance returns Adjusted. TransitionalInsert (TransitionTypes.cs:2055-2065) sees otherState != OK, sets transitState = otherState, and continues the outer retry — never reaching the ci.ContactPlaneValid/step-down gate at line 2248/2252 at all. Three outer attempts, byte-identical dist=-0.04000 each time (the query never changes because nothing in the ADJUSTED path perturbs sp.CheckPos). ValidateTransition then forces OK, reverts to the start position: 0% XY yield, [transit-fail] STUCK-TICK fires.

Fixture B — steep triangle WITHIN the SAME primary cell (both start and target inside one 24 m cell's own quad; the too-steep triangle is one of the cell's own two split triangles, N=(-0.8,0,0.6), reached via the diagonal split so no other-cell dispatch is needed at all). Result: even cleaner — InsertIntoCell's OWN inner retry loop (TransitionTypes.cs:2383-2390, up to 3 attempts) calls FindPrimaryCellCollisions → FindEnvCollisions → ValidateWalkable directly, gets Adjusted on every one of its 3 attempts (dist=-9.74400 identical all 3, deep penetration by design), and returns Adjusted from InsertIntoCell itself — before check_other_cells is even called. TransitionalInsert's outer switch, case ADJUSTED_TS: { neg_poly_hit = 0; break; } (TransitionTypes.cs:2030-2037), skips the entire if (edi == OK_TS) block. 3 outer attempts × 3 inner attempts = 9 total [transit-fail-insert] lines, every one env=Adjusted, never reaching environment=OK. DoStepDown/EdgeSlideAfterStepDownFailed are never called — zero edge-slide: diagnostic lines fire in this fixture's log, confirmed by grep. 0% XY yield, STUCK-TICK fires, identical fingerprint to Fixture A and to the original captured bug (spStepDown=False, guardPassed=False, outcome=Adjusted, byte-identical dist every attempt).

Both fixtures independently, by two structurally different routes (neighbor cell vs. same cell), reproduce the exact captured #345 fingerprint from docs/ISSUES.md — and both do so by faithfully executing the documented retail control flow (check_other_cells's unconditional early return on Adjusted; transitional_insert's post-switch edi==OK_TS gate). Neither fixture ever reaches DoStepDown/EdgeSlideAfterStepDownFailed/CliffSlide — which the trap-list machinery (RetailEdgeResponseOrderingTests.cs, already green) proves is itself faithful and reachable once a clean OK attempt occurs. The problem, if it is a problem in acdream's code at all, is never reaching a clean OK attempt in the first place — which is exactly what retail's own decompiled insert_into_cell/check_other_cells say should happen for this topology too.

Why this is a STOP, not a D1 fix

The fix contract's own hypothesis was specific: "does retail's grounded step run a step-down phase per sub-step such that validate_walkable's Adjusted-on- steep lets the insert PROCEED to that phase ... where ours treats the primary's Adjusted as retry-the-insert?" This session traced the exact function (step_down) and the exact gate (transitional_insert's if (edi == OK_TS)) the hypothesis named, byte-for-byte, and found retail's own code does not let an Adjusted result proceed to the step-down phase — it retries from scratch, identically to acdream's port. The hypothesis, taken literally, is refuted, not confirmed. Two independently-constructed fixtures running acdream's real TransitionalInsert/InsertIntoCell/CheckOtherCells production code confirm this refutation empirically, not just on paper.

This leaves the contradiction between:

• the pseudo-C (hand-traced + empirically reproduced twice): this topology should dead-loop, in BOTH retail and acdream, and
• the live cdb profile (345-retail-glide.cdb.log): retail's glide fires edge_slide/cliff_slide 594 times each, in lockstep, step_up zero,

genuinely unresolved. Per the fix contract ("if the hypothesis is wrong, keep going until you find the branch that produces the profile") this session kept going — through step_down, check_other_cells, InsertIntoCell's own retry loop, CheckOtherCells's cell-set dispatch (RunCheckOtherCellsAndAdvance, TransitionTypes.cs:3562-3636, CellTransit.FindCellSet) — and found every one of those to be a faithful, citable, non-garbled port. No garbled Binary-Ninja decision point was found in the functions actually exercised by this topology (insert_into_cell, transitional_insert's switch, check_other_cells's switch, step_down) — all were clean integer dispatches, not x87/flag-test mush, so this is not a "note the address and STOP for byte-decode" situation either.

What remains unresolved, and is out of this session's scope to fix by guessing:

• Whether retail's actual Rithwic terrain topology differs structurally from both synthetic fixtures here in some way that changes which branch fires — e.g. a shallower approach that keeps the primary/other-cell query in the "above" branch for more of the glide, letting more attempts reach a clean OK and hence step_down/edge_slide (this is plausible in principle: the live profile's set_sliding_normal count, 538, is lower than edge_slide/ cliff_slide's 594, meaning not every edge_slide call reaches cliff_slide's effective branch — consistent with a live approach that spends some attempts in "above" and only some in "below-and-caught").
• Whether CellTransit.FindCellSet's broadphase (feeding CheckOtherCells's cellSet) is over- or under-inclusive relative to retail's real CObjCell::find_cell_list for a moving sphere near a terrain-cell boundary — the same open question the first D0 pass flagged, still open, still requiring the live cdb trace named in that pass's own recommendation (validate_walkable @0x0050d010 / transitional_insert @0x0050b6f0 / adjust_sphere_to_plane @0x00538210 while the glide happens), which this text-only session cannot execute.

Per the fix contract's acceptance rule #4 ("Any contradiction between the profile, the pseudo-C, and our code that you cannot resolve → STOP and report with the evidence. A correct STOP is a success."), this session stops here. No production code was changed. The two throwaway diagnostic fixtures used to gather this evidence were deleted before this document was written; they are reproducible from the exact parameters quoted above if a future session wants to re-verify or extend them (in particular: a graduated multi-triangle terrain fixture that keeps some attempts in the "above" branch, to test the "live approach spends only some attempts below" theory above).

Trap list compliance

No change was made to ValidateWalkable's math, AdjustOffset, the #331 absorb, the #32 setter split, DoStepUp/DoStepDown internals, the edge-family response bodies, or the stepDownHeight = oi.StepUpHeight oddity. RetailEdgeResponseOrderingTests.cs (unmodified) already pins that DoStepDown→EdgeSlideAfterStepDownFailed→CliffSlide chain as faithful and reachable from a clean OK attempt — this session's fixtures corroborate that finding rather than contradicting it; the gap is entirely upstream of it.

Parent addendum (2026-08-08, post-STOP): the ACE cross-check sharpens the question

references/ACE/Source/ACE.Server/Physics/Transition.cs:779-934 (TransitionalInsert) — an independent port of the same retail loop — shows EdgeSlide is reachable ONLY from the transitState == OK arm: insert succeeds → the grounded step-down block runs → StepDown fails → EdgeSlide(ref transitState, ...). On Adjusted the loop merely clears NegPolyHit and retries, exactly as our port and this doc's fixtures show.

Therefore the live profile (594 edge_slide/cliff_slide lockstep per run, step_up=0) FORCES the conclusion that retail's primary insert RETURNS OK per tick in the glide scenario, while ours returns Adjusted 3×3 per tick. The missed branch is not routing-after-Adjusted; it is whatever prevents retail's per-tick check position from tripping validate_walkable's below-plane push (@0x0050d010 mover arm, return ADJUSTED_TS) in the first place — most plausibly the interplay of the previous tick's edge/cliff slide having already moved the request, or a check-position seeding difference at insert entry.

Falsifiable predictions for the round-2 capture (tools/cdb/345-glide-stacks.cdb):

1. tins (transitional_insert) counts ~1 per tick — NO retry storm in retail (ours: 9 attempts/tick).
2. stepdown runs in lockstep with edge (≈594 scale).
3. The edge_slide stacks show transitional_insert (or find_transitional_position) directly — the OK-arm step-down block — with NO intervening validate/adjust retry frames.

If prediction 1 fails (retail also retry-storms), the divergence is inside the retry's convergence instead, and the Adjusted-production question reopens. Either way the capture discriminates.

D0 RESOLVED (2026-08-08, parent session): the missed branch is validate_walkable's RETURN SCOPING — byte-proven

Capstone disassembly of the PDB-paired binary (C:\Users\erikn\Downloads\ acclient.exe, v11.4186) at OBJECTINFO::validate_walkable @0x0050d010:

0050d020  mov edi, 1
0050d025  mov [esp+0xc], edi        ; var_1c = 1 = OK_TS  (return-value slot)
...below-plane arm...
0050d1a9  test ecx, ecx             ; sp->step_down
0050d1af  jne 0x50d1bf              ;   set → guard body
0050d1b1  test byte [ebp+4], 2      ; oi->state & OnWalkable
0050d1b5  je 0x50d1bf               ;   clear → guard body
0050d1b7  test eax, eax             ; is_valid_walkable(N)
0050d1b9  je 0x50d251               ;   TOO STEEP → SKIP guard body ENTIRELY
0050d1bf  ...set_contact_plane, step-down interp (fail: mov eax,2 → COLLIDED),
0050d244  call add_offset_to_check_pos    ; the push
0050d249  mov dword [esp+0x10], 3   ; var_1c = ADJUSTED — ONLY after the push
0050d251  ...collision-normal tail (Contact set → skipped)...
0050d271  mov eax, [esp+0x10]       ; return var_1c

The guard-fail path (grounded mover, OnWalkable, too-steep plane) never touches var_1c: retail returns OK. The steep below-plane is deliberately ignored by primary walkable validation; the insert proceeds, the OK-arm step-down phase runs at the advanced position, its walkable probe fails on the steep landing (check_walkable early-out: 0050d187 mov eax,2 — COLLIDED, also byte-confirmed), StepDown fails, and EdgeSlide / CliffSlide produce the per-tick lateral glide. Every round-1 counter (594 edge/cliff lockstep, step_up=0, walkable_hits_sphere=0, adjust_sphere_to_plane=0, vwalk high) is reproduced by this reading.

ACE misported this (ObjectInfo.cs:169 returns Adjusted unconditionally after the guard block) and acdream inherited the shape. Binary Ninja had var_1c = 3 correctly scoped inside the guard all along (pc:274525+ region) — but its void return typing and bare return; statements hid the return-value mechanics from every prior reading.

The fix (supersedes the contract's D1 scope, per its own "find the real branch" clause): in our ValidateWalkable below-plane arm (TransitionTypes.cs:3744-3785), return Adjusted only when the guard passed and the push executed; return OK when the guard fails. No routing change in TransitionalInsert is needed — the existing OK-arm step-down block + edge family already produce the cascade (proven live-healthy by this morning's 18 clean edge-family entries).

Also byte-confirmed while here: the step-down interp failure returns COLLIDED (0050d28b mov eax,2) — ACE and our port are RIGHT there; BN's bare return hid it. And the check_walkable early-out returns COLLIDED (0050d187) — all three agree.

Flagged secondary (file, don't chase): retail's guard calls CPhysicsObj::is_valid_walkable(N) (fixed retail threshold) at BOTH the resting and below-plane sites; ours tests N.z >= sp.WalkableAllowance. In this scenario both reject N.z=0.6, so it is not #345's cause — but the operand difference needs its own conformance check.