docs: #345 fix contract — the runtime profile is the oracle; find the branch the code reading missed

Retail's per-tick edge-family entry (594 lockstep firings, zero
step_up) is the constraint any pseudocode reading must reproduce — the
prior 'retries from scratch, retail-identical' conclusion is refuted by
the live profile, so D0's job is finding the branch that reading
missed, with the step-down-phase-ordering hypothesis named as a
candidate to verify rather than assume. Trap list absolute: the entire
proven-faithful response machinery is off-limits; the fix is routing
fidelity only.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs/research/2026-08-08-345-fix-contract.md

@@ -0,0 +1,67 @@
+# #345 fix contract — route the refused steep walkable into the edge family, as retail does every tick
+
+**Date:** 2026-08-08. **Implementer:** one Sonnet agent, after the AD-66
+reland lands (adjacent code; one physics change in flight at a time).
+**Review:** dual Opus (this is core movement). **Gate:** the user's glide —
+angled input into a too-steep hillside must slide laterally, scaling with
+angle, exactly as their retail observation ("it glides, faster the more
+angle") establishes as the axiom.
+
+## The oracle is a RUNTIME PROFILE, not a code reading
+
+Live cdb on the PDB-paired retail client during the user's 45° glide
+(`345-retail-glide.cdb.log`): `edge_slide` and `cliff_slide` fired **594
+times each in lockstep** (~30/s), `set_sliding_normal` 538, **`step_up` 0**,
+`adjust_sphere_to_plane`/`walkable_hits_sphere` 0. Retail's glide IS the
+edge family running per tick. Ours in the same scenario: 18 edge-family
+entries total; the stuck ticks (275, `345-mechanism.log` + the ISSUES
+anatomy) dead-loop insert retries with every phase OK and ValidateWalkable
+returning Adjusted on the steep plane, never reaching the edge family.
+
+**A prior code-reading pass concluded "Adjusted retries from scratch,
+retail-identical" — the profile REFUTES the completeness of that reading.**
+Retail demonstrably reaches edge_slide per tick from this same scenario;
+some branch the reading missed routes there.
+
+## D0 — find the missed branch (pseudocode doc first, mandatory)
+
+Candidate to verify FIRST (hypothesis, not conclusion): our stuck ticks all
+show `spStepDown=False` inside the failing validations — yet retail's edge
+family enters from the STEP-DOWN-FAILED branch, and retail's ordinary
+grounded step runs a step-down phase per sub-step. Question: in retail's
+`transitional_insert` (@0x0050b6f0) + `find_transitional_position`, when
+does the grounded step's step-down phase run relative to the primary
+collision, and does validate_walkable's Adjusted-on-steep let the insert
+PROCEED to that phase (whose failure then enters `edge_slide` @~0x0050b921,
+the anchor mapped in the #32 research) — where ours treats the primary's
+Adjusted as retry-the-insert? Pin from the pseudo-C with addresses; if the
+hypothesis is wrong, find the real branch — the PROFILE is the constraint
+any reading must reproduce (per-tick edge entry, zero step_up).
+
+## D1 — the minimal port
+
+Only the routing/branch fidelity in our `TransitionalInsert` /
+`FindTransitionalPosition` loop. The trap list is absolute: no changes to
+ValidateWalkable's math, AdjustOffset (fresh AD-66 landing!), the #331
+absorb, the #32 setter split, `DoStepUp`/`DoStepDown` internals, or the
+edge-family responses themselves (all proven faithful and live-healthy —
+this morning's 18 entries all applied clean constraints).
+
+## D2 — tests
+
+1. The measured scenario as a fixture (grounded mover, 45° request into an
+   N.z≈0.6 terrain plane): post-fix the LATERAL component survives (yield
+   > 0 in Y for an X-facing slope), scaling with angle (two angles
+   asserted, ordering only — no magic feel constants); perpendicular still
+   stops (retail's perpendicular observation).
+2. The trace fixture (`TransitFailProbeTests`) shows the changed anatomy —
+   the stuck-tick predicate should no longer fire at all on the angled
+   fixture (motion occurs).
+3. The #331 absorb pin, the AD-65/AD-66 conformance tests, and the uphill
+   no-flap guard all stay green untouched.
+4. Sabotage: revert the routing → the lateral test reds; restore.
+
+## Acceptance
+
+Clean-room full suite, exact totals; nothing committed; contradictions →
+STOP and report. Then dual review, then the user's glide gate.