acdream/docs/research/2026-06-08-flap-rootcause-physics-rest-handoff.md

Handoff — the indoor FLAP traced to a physics rest µm-jitter; prior diagnoses REFUTED — 2026-06-08

CANONICAL PICKUP for the indoor render flap. This session refuted the 2026-06-07 cutover-flip diagnosis AND an enqueue-once attempt, confirmed the real mechanism with primary evidence, and traced the root all the way down to a physics resting-position µm jitter. The fix is in physics (rest-stability), is teed up, and needs one more higher-precision trace to pin the exact cause before porting. Spec: docs/superpowers/specs/2026-06-08-portal-flood-membership-stability-design.md (its §4 enqueue-once design is REFUTED — see §3 here; its §6 physics contingency is now the active direction).

---

1. What the flap IS (confirmed, primary evidence)

At the Holtburg cottage doorway threshold, the portal-visibility flood set oscillates frame-to-frame (ids=[0170,0171,0172,0173,0174,0175] ↔ [0170,0171], i.e. 6↔2 cells) from a stable viewer cell (root=0xA9B40170, outRoot=n). The deep 0172-0175 cluster pops in/out → textures "battle."

• It is NOT see-through walls from outside (standing outside with the door closed is stable — user visual gate), NOT the outdoor node, NOT a root toggle, NOT nondeterminism.
• PortalVisibilityBuilder.Build is a pure deterministic function (proved by PortalVisibilityBuilderTests.Build_IsDeterministic_*, passes). So the flip requires a varying input.
• The high-precision [pv-input] probe (6 dp) shows the camera eye AND the player RenderPosition carry perpetual ~1–8 µm float jitter at rest (e.g. player Z 94.000000 ↔ 94.000008). At the threshold a grazing portal's clip is so knife-edge that this µm jitter flips its empty/non-empty result → the flood membership flips → the flap.

Mechanism chain: physics resting position blips ~µm → ComputeRenderPosition Lerp surfaces it as µm eye jitter → the portal-flood clip (clip-non-empty membership) is µm-sensitive at the grazing threshold portal → flips → flap. Retail is flap-free because its authoritative local position is bit-stable at rest (so its same clip-non-empty membership never crosses the boundary).

2. REFUTED — the 2026-06-07 cutover-flip diagnosis (do NOT act on its F1/F2)

docs/research/2026-06-07-cutover-flip-render-residuals-diagnosis-handoff.md is wrong on its load-bearing claims (primary evidence in this session):

• "See-through from outside" — not reproduced (outside, door closed, is stable).
• "Walls ARE the EnvCell shells; ModelId is a partial frame" — refuted: the cottage ModelId GfxObj 0x01000A2B is a full closed exterior (76 render polys, bbox 20×18×10.4 m, 46 outward-facing walls + roof — tools/A8CellAudit gfxobj 0x01000A2B). EnvCell shells are interior-facing. F2 (EnvCell back-faces) targets the wrong geometry.
• "Oscillation = outdoor-node flood (1↔13)" — corrected: it is the indoor flood, stable root, 2↔6. F1 targeted the wrong root.
• "branch=RetailPViewInside every frame proves the flap is gone" — tautological (post-flip clipRoot = viewerRoot ?? _outdoorNode is ~never null, so branch can't report OutdoorRoot).

3. REFUTED — enqueue-once traversal (TDD caught it)

Hypothesis: the flap is acdream's MaxReprocessPerCell re-enqueue drift; restore retail's enqueue-once (first-discovery only, no re-enqueue). Refuted: retail does NOT stop at first discovery — its AddViewToPortals growth branch calls AddToCell (decomp :433494), so a cell's later-grown view IS propagated (late slices reach exit portals). The existing test PortalVisibilityBuilderTests.Build_ViewGrowthAfterDoneCell_PropagatesNewSlicesToExit encodes exactly this retail behavior; enqueue-once broke it. The change + its test were reverted (tree clean, 27 portal tests green). The divergence is the re-clip DRIFT, not the propagation — and underneath, the flap is the µm input jitter (which removing the drift would only reduce, not eliminate; Build is deterministic so only a bit-stable INPUT guarantees no flap).

4. The root — physics resting position not bit-stable

PlayerMovementController.ComputeRenderPosition (line 810): Vector3.Lerp(_prevPhysicsPos, _currPhysicsPos, alpha). Lerp(a, a, t) == a exactly, so the µm RenderPosition jitter means _prev != _curr — the physics body's resting position blips ~µm between ticks. Retail's kill_velocity (OBJECTINFO::kill_velocity = set_velocity(0), decomp :274467) is called by validate_transition (:272567) on every grounded collision/slide with a valid contact plane, keeping rest bit-stable.

acdream rest path:

• calc_acceleration (PhysicsBody.cs:191) zeroes gravity only when Contact && OnWalkable && !Sledding.
• UpdatePhysicsInternal (PhysicsBody.cs:352) skips position integration when velocity <= 0.
• Player flags set per tick in PlayerMovementController (1271-1301): Contact|OnWalkable only when resolveResult.IsOnGround && Velocity.Z <= 0; else cleared → gravity.
• acdream's kill_velocity (PhysicsEngine.cs:837) is narrower than retail's — fires only on ObjectInfo.VelocityKilled (the airborne steep-roof/wall reset), NOT on every grounded contact.

So at a clean rest the position is bit-stable; the blip is an intermittent failure (a stray gravity tick / µm velocity residual / contact-plane not re-established). The [resolve] probe (3 dp) shows the body stable to mm at spawn rest (94.000 repeated) — confirming the blip is sub-mm, below that probe's precision — and shows groundedIn=True but walkable=False cp=none (no contact plane established at rest), a lead toward the Contact/contact-plane path.

5. NEXT STEPS (the physics rest-stability fix)

1. Higher-precision physics rest trace (REQUIRED before fixing). The 3-dp [resolve] probe is too coarse. Add a 6-dp per-tick probe of the resting body: _body.Position, Velocity, Acceleration, TransientState (Contact/OnWalkable), resolveResult.IsOnGround, contact-plane valid. Launch, let the character sit at spawn (no input needed — autonomous), capture ~10 s, and find the tick where the position blips µm and which condition failed (gravity applied? velocity residual? resolve re-snap? Contact cleared?).
2. Port the retail-faithful rest-stability fix for the pinned cause — most likely one of: (a) broaden kill_velocity to match retail's validate_transition (zero velocity on every grounded contact with a valid contact plane, :272567); (b) ensure the Contact flag / contact plane is re-established on the zero-distance rest sweep so calc_acceleration keeps gravity off; (c) a retail-faithful "supported body at rest is frozen" (skip integration/resolve when grounded + zero velocity + no movement input). TDD: a test asserting the resting body position is bit-stable across N ticks with no input.
3. Visual gate at the cottage doorway threshold: hold still — the 2↔6 oscillation is gone (re-run [pv-input]/[render-sig], flood ids= constant at rest).

DO NOT RETRY: the overlap-predicate render band-aid (rejected by user — not retail); enqueue-once (refuted, §3); any render-side debounce/grace (forbidden).

6. Apparatus (committed this session) + state

• Keep (real regression value): PortalVisibilityBuilderTests.Build_IsDeterministic_* (proves Build deterministic); tools/A8CellAudit gfxobj mode (dumps render geometry — used to refute the ModelId claim).
• Diagnostic probes (env-gated, inert off; KEEP for the physics trace + flap visual gate, strip after the fix ships): [pv-input] (ACDREAM_PROBE_PVINPUT, 6-dp Build inputs + flood count, RenderingDiagnostics + GameWindow); the outRoot=/bshell= fields on [render-sig]; launch-pvinput.ps1, launch-bshell-probe.ps1, launch-resolve.ps1.
• Tree: PortalVisibilityBuilder.cs reverted to the re-enqueue (no functional change shipped). Build green; App.Tests green (portal-visibility 27/27).
• Memory to update: project_indoor_flap_rootcause (root is the physics rest µm-jitter, not the render diagnosis or enqueue-once).