Erik 3f2b2dc3ed docs: #345 mechanism-session contract — a self-selecting transition-phase trace before any theory

The probe design: fires only on the stuck-tick predicate (zero XY yield
against nonzero request), printing per-attempt phase outcomes, step-up/
step-down verdicts, every ValidateWalkable branch with its flag guards
at the SetCollisionNormal site, and the AdjustOffset pair — the
collN=(0,0,1) fingerprint's producer names itself. Trap inventory from
the week's do-not-retry ledger attached so the eventual fix cannot
stumble into a retail-faithful mechanism.

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

2026-08-07 09:46:13 +02:00

3.2 KiB

Raw Blame History

#345 mechanism-session contract — who eats angled input on the steep-slope approach?

Date: 2026-08-08. Order: after #344 lands. This is an instrumentation session, not a fix session — the fix contract gets written from the capture, not before.

Evidence in hand (do not re-derive)

uphill-45deg-capture.jsonl: 838 uniform stuck ticks — request ~0.23 m/tick at 45° to the face, result byte-identical to input position, collisionNormalValid=True with collN=(0,0,1) (straight up), slidingNormal=(0,0,0), carried contact = the ~6.8° approach terrain (-0.083,0.083,0.993), transient=0x3 (Contact|OnWalkable).
uphill-slide-capture.log: the steep face itself was reached only 18 times; every reach took branch2 cliff-slide with a healthy applied constraint. The eater is UPSTREAM of the face.
uphill-AB-precampaign.jsonl: identical 0.0%-yield signature on the pre-campaign binary — pre-existing, Campaign S exonerated.
Ruled out by measurement: the #331 sliding absorb (no latch), cliff-slide degeneracy (#32 fixed, visibly healthy), all Campaign S landings.

The one probe this session builds

A per-tick TRANSITION PHASE TRACE, ACDREAM_DUMP_TRANSIT_FAIL=1, firing ONLY when a resolve returns zero XY displacement against a nonzero XY request (the stuck-tick predicate — self-selecting, so a normal session prints nothing). For each such tick, one line each for:

every TransitionalInsert attempt: attempt #, phase reached (env/building/objects), each phase's TransitionState, and on Collided the colliding polygon's plane normal + which BSP/terrain source produced it;
every step-up entry and its step-down verdict (reuse/extend ACDREAM_DUMP_STEPUP's existing lines — they already print the input normal and the landing verdict);
every ValidateWalkable outcome on the tick: dist, waterDepth, which branch (resting / below-push / CheckWalkable-fail), and BOTH flag guards (oi.Contact, sp.StepDown) at its SetCollisionNormal site — the collN=(0,0,1) fingerprint most plausibly comes from a SetCollisionNormal(groundNormal) somewhere, and this names which.
the final AdjustOffset input/output pair for the tick.

House rules: lives in PhysicsDiagnostics (rule 5), self-selecting trigger, zero cost when off, mover id on every line (feedback_probe_identity_attribution).

The session

Build with the probe → the user repeats the exact 45° protocol (~1 min) → read the trace → the failing phase + normal source IS the mechanism → write the fix contract from it, citing the retail counterpart (grep-named-first: CTransition::transitional_insert family, the step-down refusal path, validate_walkable's collision-normal writes — all already mapped in this repo's pseudocode docs).

Known trap inventory for the eventual fix (from this week's do-not-retry ledger)

The #331 absorb is retail-faithful — whatever the fix is, that characterization pin must stay green. The #32 setter split must not be re-latched. AD-65's snap arm is byte-anchored. The step-up chain's stepDownHeight = oi.StepUpHeight oddity is retail-verbatim (#338's research). Do not touch any of these on a theory.

3.2 KiB Raw Blame History