acdream/docs/research/2026-08-08-345-pseudocode.md

#345 D0 — retail pseudocode pin: does transitional_insert slide on a too-steep OTHER-cell plane while already grounded?

Order: implementation-session D0, per the mechanism contract (docs/research/2026-08-08-345-mechanism-contract.md) and the mechanism-caught finding in docs/ISSUES.md #345. Grep-named-first, pseudocode-before-port, per CLAUDE.md's workflow.

Verdict up front: retail does NOT slide here either. Followed by hand through four retail functions (cross-checked against an independent C# reference for one of them), the mechanism converges to the exact same "0% yield, repeat forever, collN=(0,0,1), slidingNormal=(0,0,0)" fingerprint the capture shows. This is not a carry-forward bug — see "What the mechanism-session's framing got wrong" below. Per the session contract's explicit fallback, this STOPS here without a D1/D2/D3 fix.

The scenario being traced

Player is grounded, walking on a nearly-flat (~6.8°) approach terrain triangle (the PRIMARY cell). The requested horizontal offset carries the sphere's overlap into an ADJACENT (OTHER) terrain cell whose triangle is too steep to be walkable: N=(0.799,0.050,0.599), N.z=0.599 just under FloorZ(≈0.664). Captured fingerprint (345-mechanism.log:279, mover 0x000F4243, and docs/ISSUES.md #345's own summary): dist=-0.34680 (a different capture in the same class logged -0.268 — same mechanism, different exact stance), oiContact=True, spStepDown=False, guardPassed=False, outcome=Adjusted, identical on every one of 6 attempts within the stuck tick, final resolve position byte-identical to input, collN=(0,0,1), slidingNormal=(0,0,0), carried contact = the flat approach terrain, transient=0x3 (Contact|OnWalkable).

1. OBJECTINFO::validate_walkable (retail 0x0050d010, pc:274479-274617)

Grep-named-first target from the contract. The "below the surface" branch (our scenario: dist < -EPSILON) is:

zDist = dist / N.z
walkable = is_valid_walkable(N)                    // N.z >= FloorZ, ours: sp.WalkableAllowance
if (step_down != 0 || (state & ON_WALKABLE) == 0 || walkable != 0) {
    set_contact_plane(plane, cellId)
    if (step_down) { ...interpolation reject... }
    AddOffsetToCheckPos(0, 0, -zDist)               // THE PUSH — pc:274604-274607
}
if ((state & CONTACT) == 0 && step_down == 0) {
    set_collision_normal(plane)
    collided_with_environment = 1
}
return ADJUSTED_TS

Cross-checked against references/ACE/Source/ACE.Server/Physics/ObjectInfo.cs:142-170 (ObjectInfo.ValidateWalkable, independently-authored C# port of the same algorithm) — identical structure, same three-way OR gate before the push.

The push (AddOffsetToCheckPos) is gated behind step_down || !OnWalkable || walkable. In our scenario: step_down is false (confirmed by the trace's spStepDown=False), walkable is false (0.599 < FloorZ), so the push fires only if OnWalkable is false. Our C# (TransitionTypes.cs:3746-3769) ports this gate verbatim: if (sp.StepDown || !oi.OnWalkable || walkable).

Is OnWalkable true here? Yes — confirmed by PhysicsEngine.cs:2026-2047: at the start of every resolve, when the body is in contact with a valid plane and not moving away from it (check_contact's success branch, ported faithfully per the #32 commit history), if (body.OnWalkable) transition.ObjectInfo.State |= OnWalkable;. The player IS resting on the flat approach terrain — body.OnWalkable is true — so oi.OnWalkable is true for this entire resolve.

Conclusion: the push never fires. ValidateWalkable returns ADJUSTED_TS with ZERO state mutation — no SetContactPlane, no AddOffsetToCheckPos, and (since !oi.Contact is false per the trace's oiContact=True) no SetCollisionNormal either. This is retail's own intentional design: a sphere already stably grounded elsewhere does not get shoved around by an incidental graze against a DIFFERENT, non-walkable patch. There is no "adjustment" to carry forward — there never was one to begin with. The mechanism-session's framing ("push-up... the adjustment does not carry forward between attempts") named the right symptom (identical dist every attempt) but the wrong cause (it isn't that a real push gets discarded; it's that the push never executes at all, precisely as retail specifies for a grounded-elsewhere mover).

2. CTransition::transitional_insert (retail 0x0050b6f0, pc:273137-273364)

edi = INVALID_TS
for (attempt = 0; attempt < numAttempts; attempt++) {
    edi = insert_into_cell(check_cell, numAttempts)
    switch (edi) {
        case OK_TS:
            edi = check_other_cells(check_cell)      // overwrites edi
            if (edi != OK_TS) neg_poly_hit = 0
            if (edi == COLLIDED_TS) return COLLIDED_TS
            break                                      // falls to "if edi==OK_TS" below
        case COLLIDED_TS:
            neg_poly_hit = 0
            return edi
        case ADJUSTED_TS:
            neg_poly_hit = 0
            break                                      // falls straight to loop-bottom, no retry-with-state
        case SLID_TS:
            contact_plane_valid = 0; contact_plane_is_water = 0
            neg_poly_hit = 0
            break
    }
    if (edi == OK_TS) {
        ...sphere_path.collide handling (Phase 3)...
        ...neg_poly_hit dispatch (step_up / step_up_slide / slide_sphere)...
    }
    // loop-bottom: unconditional retry up to numAttempts, no early exit besides
    // the explicit returns above
}
return edi

Our C# (TransitionTypes.cs:1991-2037 for the switch, 2052-2065 for the check_other_cells dispatch) matches this line-for-line: InsertIntoCell result dispatches through the same Collided-returns/Adjusted-clears-neg-poly-continues/Slid-clears-contact- continues shape; OK_TS alone proceeds to RunCheckOtherCellsAndAdvance (our name for check_other_cells), whose non-OK result also just continues the outer loop with no special-cased state restoration — identical to retail's break that skips the big Phase-3 block and falls to the unconditional loop-bottom retry.

Neither retail nor our port does anything to "feed the adjusted CheckPos forward" on an ADJUSTED_TS from check_other_cells — both simply retry the WHOLE insert_into_cell from scratch. Since ValidateWalkable made zero mutation (§1), retrying from scratch necessarily reproduces the identical primary-insert-OK, other-cell-Adjusted-with-identical-dist sequence every attempt. This is exactly the observed fingerprint, and it is retail-faithful.

3. CTransition::check_other_cells (retail 0x0050ae50, pc:272717-272798)

Iterates the sphere's overlapping OTHER cells (find_cell_list), calling each cell's virtual find_collisions. Its switch: COLLIDED_TS and ADJUSTED_TS (cases 2 and 3) both return result immediately — no further cells are tried, no retry loop of its own. SLID_TS (case 4) clears the contact plane fields then also returns immediately. Only OK_TS continues to the next cell. Our C# CheckOtherCells / ApplyOtherCellResult (TransitionTypes.cs:2952-3030) halts the same way. No divergence found here.

4. CTransition::validate_transition (retail 0x0050aa70, pc:272547-272689)

Called as validate_transition(this, transitional_insert(this, 3), &out) directly from find_transitional_position (retail 0x0050bdf0, pc:273743 — the ordinary per-substep walking driver, confirmed calling exactly transitional_insert(this, 3) then validate_transition, matching our TransitionTypes.cs:1611/1621 TransitionalInsert(3, engine) → ValidateTransition(result) pairing byte-for-byte). On a non-OK, non-INVALID result (COLLIDED/ADJUSTED/SLID — all three, treated identically):

if (last_known_contact_plane_valid) {
    kill_velocity()
    if (radius + EPSILON > |dot(N_lkcp, curr_center) + d_lkcp|)   // still within
        set_contact_plane(last_known_contact_plane)               // reach of LKCP?
}
if (!collision_normal_valid)
    set_collision_normal(UP)                       // the (0,0,1) DEFAULT FILL
set_check_pos(curr_pos, curr_cell)                  // DISCARD — revert to pre-step position
result = OK_TS                                      // FORCE OK — the whole substep nets zero
...
if (collision_normal_valid)
    set_sliding_normal(collision_normal)            // sliding_normal = f(UP) below

Our C# ValidateTransition (TransitionTypes.cs:6194-6226) ports this exactly, including the LastKnownContactPlaneValid proximity gate (TransitionTypes.cs:6203-6219), the !CollisionNormalValid UP default (6221-6222, the literal source of the trace's collN=(0,0,1) — confirming the mechanism-session's own annotation that this normal "comes from the failure path's result-filling, not from ValidateWalkable's guard"), the SetCheckPos revert + forced OK_TS (6224-6225), and the SetSlidingNormal(CollisionNormal) call (6229-6230).

Because the player is still resting on the flat approach terrain, curr_center is (by construction) essentially ON that plane, so the LKCP-proximity check always passes — the flat terrain gets restored as the CURRENT contact plane on every failed substep. That is why the capture shows carried contact = the flat approach terrain, not the steep face — the steep face never gets registered as a contact at all (§1), and this LKCP restore keeps re-confirming OnWalkable = true (ContactPlane.Normal.Z(0.993) >= FloorZ) at the tail of ValidateTransition (TransitionTypes.cs:6252-6255) — which is exactly the OnWalkable seed §1 needs to keep suppressing the push on the NEXT resolve. This is a self-sustaining, retail-faithful attractor: stay resting on flat ground behind you → steep OTHER-cell touch is silently ignored → contact plane keeps re-anchoring to the flat ground → OnWalkable stays true → the steep touch keeps being silently ignored. There is no state transition inside this mechanism that would break the cycle.

5. COLLISIONINFO::set_sliding_normal (the "#331 absorb")

TransitionTypes.cs:553-559 projects the incoming normal to XY only and re-normalizes:

SlidingNormal = new Vector3(normal.X, normal.Y, 0f);
if (SlidingNormal.LengthSquared() > EpsilonSq)
    SlidingNormal = Vector3.Normalize(SlidingNormal);

Fed the §4 UP default (0,0,1), this produces SlidingNormal=(0,0,0) — exactly the captured slidingNormal=(0,0,0). Per the trap inventory (docs/research/2026-08-08-345-mechanism-contract.md + CLAUDE.md "Current state"), this XY-projection is the retail-faithful #331 absorb and is explicitly off-limits to touch. It is not the cause here — it is a correct, downstream consequence of the §4 UP default, which is itself a correct, downstream consequence of §1's guard never firing.

What the mechanism-session's framing got wrong

The probe (ACDREAM_DUMP_TRANSIT_FAIL) correctly found WHERE the identical-dist loop lives (ValidateWalkable's below-branch, TransitionalInsert's retry). It inferred WHY from the symptom's shape ("push-up... doesn't carry forward") without visibility into oi.OnWalkable or the push guard itself — the probe's trace only carries oiContact/ spStepDown (the second, SetCollisionNormal, guard), not the first (AddOffsetToCheckPos) guard's inputs. Reading the guard from source (sp.StepDown || !oi.OnWalkable || walkable, all three legs resolvable statically for this scenario) shows the push is never attempted, so there is nothing to "carry forward" in the first place.

Conclusion

Every function in the chain — ValidateWalkable, TransitionalInsert, CheckOtherCells, ValidateTransition, SetSlidingNormal — is a faithful, citable port, and hand-tracing them against this exact scenario reproduces every byte of the captured fingerprint (collN=(0,0,1), slidingNormal=(0,0,0), identical dist per attempt, carried contact = approach terrain, byte-identical position in/out). Retail's own algorithm, run by hand against this geometry, does not slide — it converges to the same zero-yield stop. Per the mechanism-session contract's explicit fallback ("If retail turns out NOT to slide here either, STOP and report — the user's expectation would then be the divergence, a different decision"), this session stops here. No ValidateWalkable/TransitionalInsert/ValidateTransition change is made; #331, #32, and AD-65 are untouched, matching the trap inventory.

Open question for whoever picks this up next

The one link in this chain NOT fully verified against retail is cell membership: does retail's CObjCell::find_cell_list (feeding check_other_cells's cell array) actually include this neighboring too-steep OTHER cell from the player's exact resting position, or does our CellTransit/other-cells construction query a cell retail's narrower geometry test would not have reached at all? That is a genuinely different question from anything traced above (a broadphase/ cell-array question, not a walkable-response question), and it is the one place this D0 pass had to reason from citation rather than from a direct retail-vs-acdream A/B. The toolchain's own guidance applies here: this is exactly the "what does retail actually DO at runtime" class of question the cdb toolchain (memory/reference_retail_debugger.md) exists for — attach to a live retail client at the identical Rithwic steep face and confirm whether retail's player is ALSO immovable at this exact stance, or whether it is already sliding by the time the sphere reaches this position (which would point at the cell-array question above, not at anything in this document).