From 82045805fdcd1b1b5503092ec0ad1a9cf0f46ce9 Mon Sep 17 00:00:00 2001 From: Erik Date: Thu, 4 Jun 2026 08:52:56 +0200 Subject: [PATCH] =?UTF-8?q?docs(p2):=20session=20wrap=20=E2=80=94=20P1=20d?= =?UTF-8?q?one,=20P2=20(Path=205=20step-up)=20localized;=20handoff=20+=20p?= =?UTF-8?q?lan/CLAUDE.md=20update?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit P1 membership is DONE (proven to already match retail; the 0/11 was a cdb capture artifact; merged + pushed). P2 root cause localized to BSP Path 5 grounded step-up: the Path 5 wrappers (DoStepUp=retail step_up, DoStepDown=retail step_down) are verified faithful + reached; the divergence is in the step-up CLIMB (find_walkable/step_sphere_down up-adjust when sp.StepUp=true). - docs/research/2026-06-03-p2-door-stepup-handoff.md: canonical P2 pickup + fresh-session prompt + DO-NOT-RETRY (the wrappers) + the tooling note (xunit swallows Console.WriteLine). - master-plan §3: P1 marked DONE + the (a)-(d) deletes/unifications re-scoped to approval-gated refactors of working code; P2 localization recorded. - CLAUDE.md M1.5: dated 2026-06-03 pointer (P1 done, P2 active, render seam in P3/P4, pickup doc). Co-Authored-By: Claude Opus 4.8 (1M context) --- CLAUDE.md | 24 ++- .../2026-06-03-p2-door-stepup-handoff.md | 171 ++++++++++++++++++ ...batim-spatial-pipeline-port-master-plan.md | 28 ++- 3 files changed, 220 insertions(+), 3 deletions(-) create mode 100644 docs/research/2026-06-03-p2-door-stepup-handoff.md diff --git a/CLAUDE.md b/CLAUDE.md index 965948f6..590cf0f0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -761,7 +761,29 @@ Apparatus `ACDREAM_PROBE_FLAP` + `tools/A8CellAudit` are committed + ready. Do N H1 (PVS grounding) or H2 (`PortalSide` side-test) — both evidence-disproven. **Currently working toward: M1.5 — Indoor world feels right** (resumed -from 2026-05-20 baseline after Phase O ship). **A6.P1 + A6.P2 + A6.P3 +from 2026-05-20 baseline after Phase O ship). + +**2026-06-03 — P1 membership DONE + P2 active (read this first).** The verbatim spatial-pipeline +port (master plan +[`docs/superpowers/specs/2026-06-03-verbatim-spatial-pipeline-port-master-plan.md`](docs/superpowers/specs/2026-06-03-verbatim-spatial-pipeline-port-master-plan.md)) +is the active effort. **P1 (membership) = DONE** — proven to ALREADY match retail; the believed +doorway "0/11 lag" was a cdb CAPTURE ARTIFACT (`change_cell` logs `m_position` before `set_frame` +writes it). Aligned re-capture → production gate 9/9 with NO code change; live `[cell-transit]` clean. +Merged + pushed to both remotes (HEAD `f0d37d8`). **P2 (door/building-shell collision) = IN PROGRESS, +root cause LOCALIZED** to **BSP Path 5 grounded step-up** — the Path 5 wrappers (`DoStepUp`=retail +`step_up`, `DoStepDown`=retail `step_down`) are verified faithful; the divergence is in the step-up +CLIMB (`find_walkable`/`step_sphere_down` up-adjust). The 5 failing Core tests are P2's target. The +visible doorway seam has moved from physics into the RENDER path (P3 camera-collision + P4 PView seal). +The (a)–(d) membership cleanups (remove `ResolveCellId`, unify `find_env_collisions`, intrinsic +building stabs, per-cell collision graph) are **approval-gated refactors of WORKING code**. **CANONICAL +PICKUP:** +[`docs/research/2026-06-03-p2-door-stepup-handoff.md`](docs/research/2026-06-03-p2-door-stepup-handoff.md) +(+ the P1 RESOLVED banner in +[`docs/research/2026-06-03-p1-membership-swept-advance-handoff.md`](docs/research/2026-06-03-p1-membership-swept-advance-handoff.md) +and the visual-gate/render-residuals note +[`docs/research/2026-06-03-p1-visual-gate-render-residuals.md`](docs/research/2026-06-03-p1-visual-gate-render-residuals.md)). + +**A6.P1 + A6.P2 + A6.P3 slice 1 SHIPPED 2026-05-21.** **A6.P3 slice 2 v2 SHIPPED 2026-05-22** (commit `f8d669b`): tried removing the L622 per-tick CP seed (`892019b` v1) but it broke BSP step_up at the last step of stairs; diff --git a/docs/research/2026-06-03-p2-door-stepup-handoff.md b/docs/research/2026-06-03-p2-door-stepup-handoff.md new file mode 100644 index 00000000..f688d2da --- /dev/null +++ b/docs/research/2026-06-03-p2-door-stepup-handoff.md @@ -0,0 +1,171 @@ +# P2 pickup handoff — door / building-shell collision = BSP Path 5 grounded step-up + +> **Canonical pickup for the next session.** Branch `claude/thirsty-goldberg-51bb9b` +> (do NOT branch/worktree; do NOT push without asking; NEVER `git stash`/`gc`). PowerShell on +> Windows; launch logs are UTF-16. Read this FIRST. + +## State both altitudes + +- **Milestone:** M1.5 — Indoor world feels right. +- **Effort:** the VERBATIM spatial-pipeline port (master plan: + `docs/superpowers/specs/2026-06-03-verbatim-spatial-pipeline-port-master-plan.md`). +- **P1 (membership) = DONE.** Proven to already match retail; the "0/11 lag" was a cdb capture + artifact. Merged to `main` + pushed to both remotes (HEAD `f0d37d8`). See + `docs/research/2026-06-03-p1-membership-swept-advance-handoff.md` (RESOLVED banner) + + `memory/project_retail_membership_criterion.md`. +- **P2 (door / building-shell collision) = IN PROGRESS, root cause LOCALIZED.** The fix is the next step. +- **Next concrete step:** read+compare acdream `find_walkable`/`step_sphere_down` vs retail + `BSPTREE::step_sphere_down` (pc:323665) + `find_walkable`, pin the step-up CLIMB divergence, and + drive `B1_GroundedMover_LowStep_StepsUp` + the door apparatus RED→GREEN. + +## TL;DR (the P2 finding) + +All **5 failing Core tests** localize to **BSP Path 5 (the grounded `Contact + StepSphereUp` branch)**: +| Test | Symptom | +|---|---| +| `BSPStepUpTests.B1_GroundedMover_LowStep_StepsUp` | grounded mover wall-slides a **walkable 0.25 m step** instead of stepping up (`CurPos.Z` stays 0). The cleanest isolation of the bug. | +| `BSPStepUpTests.D4_AirborneMover_TallWall_PersistsSlidingNormalAcrossFrames` | airborne tall-wall sliding-normal count (`Expected: 2`) — Path 4/5 sliding-normal family. | +| `DoorCollisionApparatusTests.Apparatus_Grounded_50cmOffCenter_FrontApproach_DocumentsBug` | synthetic door + grounded off-center: now blocks at tick 0 with an `(0,0,1)` up-normal + goes airborne (Path 5 step-up artifact, not a faithful door block). | +| `DoorBugTrajectoryReplayTests.LiveCompare_DoorOffCenterWalkthrough_Tick13558` | replay of captured live tick diverges from the engine (documents-the-bug). | +| `DoorBugTrajectoryReplayTests.LiveCompare_DoorBlocksFromOutside_Tick22760` | same, outdoor-block tick. | + +These have been the documented baseline RED set for a while (they are P2's target). They did NOT +regress this session — P1's work only touched conformance tests + docs. + +## Root cause — PRECISELY localized (the whole upstream chain is verified faithful) + +For B1 (the cleanest case), the path is reached + dispatched correctly; the divergence is deep in the +climb. Verified faithful and ruled out this session (DO NOT re-investigate these — see DO-NOT-RETRY): + +1. **Path 5 dispatch is reached.** `BSPStepUpFixtures.MakeGroundedTransition` sets `State = Contact | + OnWalkable` + `StepDown=true` — but that `StepDown` is `ObjectInfo`'s flag; the Path 3 dispatch + gates on the `SpherePath.StepDown` flag (only set during a step-down probe), so the **main sweep + correctly lands in Path 5's `Contact` branch** (`BSPQuery.cs:1814`). +2. **Recursion guard passes.** `if (engine is not null && !path.StepUp && !path.StepDown) return + StepSphereUp(...)` (`BSPQuery.cs:1848`) — on the main sweep both `SpherePath` flags are false → + `StepSphereUp` → `DoStepUp` IS called on the wall hit. +3. **`DoStepUp` (`TransitionTypes.cs:3254`) = faithful port of retail `CTransition::step_up` + (pc:273099).** Same structure: clear contact-plane, `stepDownHeight = OnWalkable ? StepUpHeight : + 0.04`, `walkableAllowance = OnWalkable ? GetWalkableZ() : LandingZ`, call `DoStepDown(...)`, return + its result. (acdream adds a restore-contact-plane-on-failure block — benign.) +4. **`DoStepDown` (`TransitionTypes.cs:3074`) = faithful port of retail `CTransition::step_down` + (pc:272946).** Skips the down-offset when `StepUp` is set, runs `TransitionalInsert(5)`, accepts + iff `OK && ContactPlaneValid && ContactPlane.N.z >= walkableZ`, then placement-validates. + +**So the divergence is INSIDE the step-up climb:** `DoStepDown` → `TransitionalInsert(5)` → Path 3 +`step_sphere_down` → **`find_walkable`'s upper-floor find + sphere-up-adjust when `sp.StepUp=true`**. +It fails to locate/lift onto the 0.25 floor within the 0.30 budget → `DoStepDown` returns false → +`StepUpSlide` → wall-slide → `Z=0`. The retail oracle for the climb is `BSPTREE::step_sphere_down` +(`@ 0x53a210` pc:323665) + `BSPNODE/BSPLEAF::find_walkable` + `adjust_sphere_to_plane`. + +acdream code map: `BSPQuery.StepSphereUp` (`:1372`), `BSPQuery.step_sphere_down` (`:1206`), +`BSPQuery.find_walkable` (`:693`), `BSPQuery.AdjustSphereToPlane` (search it), `Transition.DoStepUp` +(`:3254`), `Transition.DoStepDown` (`:3074`). + +## ⚠ TOOLING NOTE (cost me a probe cycle — don't repeat) + +**xunit swallows `Console.WriteLine`.** The built-in `ACDREAM_DUMP_STEPUP=1` trace (in `DoStepUp`) +and the `[step-walk]` probe (`PhysicsDiagnostics.ProbeStepWalkEnabled`) both print via `Console` → +they do NOT surface in `dotnet test ... -l "console;verbosity=detailed"`. The tests that DID show +output used `ITestOutputHelper` (`_out.WriteLine`). So to trace which climb condition fails +(`TransitionalInsert(5)` result / contact-plane / `N.z` / placement), **add an `ITestOutputHelper`-based +trace to B1 (or a focused harness) — don't rely on the `Console` probes inside the engine.** + +## DO-NOT-RETRY (verified faithful this session) + +1. Path 5 dispatch / the Contact-branch reachability — confirmed B1 reaches Path 5. +2. The recursion guard / `StepSphereUp` call — confirmed `DoStepUp` is called. +3. `DoStepUp` vs retail `step_up` — faithful, ruled out. +4. `DoStepDown` vs retail `step_down` — faithful, ruled out. +The bug is downstream in `find_walkable`/`step_sphere_down`'s **step-up adjust**. Start there. + +## Next steps (evidence-first — the door saga burned many SPECULATIVE fixes; do NOT repeat) + +1. **Read+compare** acdream `BSPQuery.find_walkable` (`:693`) + `step_sphere_down` (`:1206`) + + `AdjustSphereToPlane` against retail `BSPTREE::step_sphere_down` (pc:323665) + `BSPNODE/BSPLEAF:: + find_walkable` + `adjust_sphere_to_plane`. Focus on the `step_up==1` path: how retail lifts the + sphere onto a step within `step_down_amt`, and where acdream fails to. +2. **Instrument B1 with `ITestOutputHelper`** (Console is swallowed — see tooling note) to pin which + condition fails: does `TransitionalInsert(5)` return OK? is `ContactPlaneValid` set? is the landing + `N.z >= walkableZ`? does placement (`TransitionalInsert(1)`) reject? `B1` is sub-second, headless. +3. **Fix the climb verbatim** (cite the decomp anchor), drive `B1` GREEN, then `B2` (must still + block the 5 m wall), then the door apparatus (`Apparatus_Grounded_50cmOffCenter…` flips to + block-not-walkthrough → rewrite its assertion to `Assert.True(blocked) && pos.Y < 12.0`), then the + 2 `LiveCompare` ticks, then `D4`. +4. **Definitive cross-check if the decomp is ambiguous:** cdb-attach to retail at a Holtburg cottage + doorway, break on `CTransition::step_up`/`step_down`/`BSPTREE::step_sphere_down`, walk a low step + + the door, capture what retail does. PDB MATCHES; tooling in `tools/cdb/` (CLAUDE.md "Retail debugger + toolchain"). Needs the user's retail client up + walking. +5. **User visual gate:** at a doorway, walk through cleanly (foot Y stable, no oscillation), walls + block; step up a low step (cottage stair) climbs. + +## Test baseline (going into the P2 fix) + +Core **1309 pass / 5 fail / 1 skip** — the 5 are exactly this P2 target (`Apparatus_Grounded…`, +`LiveCompare_DoorOffCenterWalkthrough_Tick13558`, `LiveCompare_DoorBlocksFromOutside_Tick22760`, +`BSPStepUpTests.D4…`, `BSPStepUpTests.B1…`). Conformance 60 pass / 1 skip / 0 fail. App 177 green. + +## Parked (do NOT touch without explicit user approval) + +- **(a)–(d) membership cleanups** — approval-gated refactors of WORKING code (CLAUDE.md "don't replace + working retail-faithful logic without approval"): (a) remove redundant `ResolveCellId` (already out + of the prod per-frame path; survives only in the `DataCache==null` test fallback); (b) unify the + forked `find_env_collisions`; (c) replace the `CheckBuildingTransit` bridge with intrinsic building + stabs in `find_transit_cells`; (d) make the per-cell ObjCell graph the collision authority (collision + still uses the landblock-wide `ShadowObjectRegistry`). The one soft spot: outdoor→indoor `0031↔0170` + building-entry is live-clean but NOT conformance-locked (rides on `CheckBuildingTransit`). +- **Render residuals (P3/P4)** — the VISIBLE doorway seam is now in the render path: the flap = + camera-collision residual (chase eye drifts out of the cell → viewer-cell flips; master-plan P3, + `SmartBox::update_viewer`); the void = unported PView seal (P4). Membership (physics) is correct. + See `docs/research/2026-06-03-p1-visual-gate-render-residuals.md`. Master-plan order: P2 → P3 → P4. + +--- + +## FRESH-SESSION PROMPT (copy-paste) + +``` +Continue the VERBATIM retail spatial-pipeline port for acdream. Branch claude/thirsty-goldberg-51bb9b +(do NOT branch/worktree; do NOT push without asking; NEVER git stash/gc). PowerShell on Windows; +launch logs are UTF-16. + +STATE: M1.5 (Indoor world feels right). P1 membership = DONE (proven to already match retail; the +"0/11 lag" was a cdb capture artifact; merged + pushed, HEAD f0d37d8). P2 (door/building-shell +collision) = IN PROGRESS, root cause LOCALIZED to BSP Path 5 grounded step-up. The fix is the job. + +READ FIRST (canonical, in order): +1. docs/research/2026-06-03-p2-door-stepup-handoff.md (THIS handoff — the localization, the + DO-NOT-RETRY list, the tooling note, the next steps). +2. docs/superpowers/specs/2026-06-03-verbatim-spatial-pipeline-port-master-plan.md (§3 P2; §1/§2 B3/B4). +3. docs/research/2026-05-25-door-bug-partial-fix-shipped.md (the door saga state + its do-not list). + +THE FINDING: all 5 failing Core tests localize to BSP Path 5 (grounded Contact + StepSphereUp). For +B1 (cleanest: a grounded mover wall-slides a walkable 0.25 m step with a 0.30 m budget, Z stays 0), +the whole upstream chain is VERIFIED FAITHFUL + correctly reached — Path 5 dispatch, the recursion +guard, DoStepUp (= retail CTransition::step_up pc:273099), DoStepDown (= retail step_down pc:272946). +The divergence is INSIDE the step-up CLIMB: DoStepDown → TransitionalInsert(5) → Path 3 +step_sphere_down → find_walkable's upper-floor find + sphere-up-adjust when sp.StepUp=true. It fails +to lift onto the 0.25 floor → StepUpSlide → wall-slide. + +DO NOT RE-INVESTIGATE (verified faithful): Path 5 dispatch, the recursion guard, DoStepUp, DoStepDown. +DO NOT speculate on the BSP fix without apparatus (the door saga burned many speculative fixes). +TOOLING: xunit swallows Console.WriteLine — the ACDREAM_DUMP_STEPUP / [step-walk] probes don't surface +in the runner; instrument B1 with ITestOutputHelper to trace the climb conditions. + +THE JOB (P2 fix, evidence-first): +1. Read+compare acdream BSPQuery.find_walkable (:693) / step_sphere_down (:1206) / AdjustSphereToPlane + vs retail BSPTREE::step_sphere_down (pc:323665) + BSPNODE/BSPLEAF::find_walkable + adjust_sphere_to_plane, + focused on the step_up==1 climb. Pin the divergence (instrument B1 with ITestOutputHelper if needed). +2. Port the climb verbatim (cite the anchor). Drive RED→GREEN: B1 (steps up), then B2 (still blocks the + 5 m wall), then DoorCollisionApparatusTests.Apparatus_Grounded_50cmOffCenter (flips to block — then + rewrite its documents-the-bug assertion to Assert.True(blocked) && pos.Y < 12.0), then the 2 + LiveCompare ticks, then D4. +3. If the decomp is ambiguous: cdb-attach to retail at a cottage doorway (break on step_up/step_down/ + step_sphere_down) — needs the user's retail client. PDB matches; tools/cdb/. +4. USER VISUAL GATE: walk through a doorway cleanly (foot Y stable, walls block); step up a cottage + stair (climbs). + +TEST BASELINE: Core 1309 pass / 5 fail (the P2 target above) / 1 skip; Conformance 60 pass / 1 skip; +App 177 green. PARKED (need explicit approval): the (a)-(d) membership cleanups + the render residuals +(P3/P4 — the visible doorway flap/void). Do NOT speculate a Path-5 fix before the climb divergence is +pinned with evidence. +``` diff --git a/docs/superpowers/specs/2026-06-03-verbatim-spatial-pipeline-port-master-plan.md b/docs/superpowers/specs/2026-06-03-verbatim-spatial-pipeline-port-master-plan.md index 47e7406a..41c9d3cb 100644 --- a/docs/superpowers/specs/2026-06-03-verbatim-spatial-pipeline-port-master-plan.md +++ b/docs/superpowers/specs/2026-06-03-verbatim-spatial-pipeline-port-master-plan.md @@ -121,8 +121,32 @@ The render rides on stable membership + a stable viewer. Port bottom-up so each **P0 first** because it's the apparatus that makes "verbatim" checkable. - **P0 — Conformance apparatus (before any port).** Headless fixtures of the Holtburg cottage neighborhood (cells `0xA9B4003x` + `0xA9B4017x`, the building stab, the cellar) loaded from the real dats. Golden tests that assert *retail* outcomes: `find_cell_list` returns the same cell as a captured retail trace at the threshold; `point_in_cell` matches; the PVS visible-set for a given (cell, eye) matches. Use the existing `ACDREAM_CAPTURE_RESOLVE` + cdb retail traces. **This is how we know a port is verbatim, not vibes.** -- **P1 — Membership (A) + uniform collision (B1).** Port `find_cell_list`/`find_transit_cells`/`find_building_transit_cells`/`add_all_outside_cells` intrinsic; delete `CheckBuildingTransit`. Port uniform `find_env_collisions` (no fork). One `point_in_cell` criterion everywhere. **Gate:** stand in the cottage doorway — the cell does NOT ping-pong (`[cell-transit]` DELTA=0 standing still, no `0031↔0170↔0171`); walk in/out is a clean monotonic cell sequence. -- **P2 — Door/building-shell collision (B3/B4).** Fix the push-back bounce (the 3 failing Core door tests go green). **Gate:** stand in the doorway — no position oscillation (foot Y stable); walk through cleanly; walls block. +- **P1 — Membership (A) — ✅ DONE 2026-06-03 (premise REVERSED).** acdream's membership ALREADY + matches retail; the believed "0/11 lag" was a cdb CAPTURE ARTIFACT (`CPhysicsObj::SetPositionInternal` + calls `change_cell` at :283456 BEFORE `set_frame` writes `m_position` at :283458, so the golden + paired each frame's new cell with the previous frame's position). An aligned re-capture + (`tools/cdb/find-cell-list-capture-aligned.cdb`) makes the production gate read **9/9 with NO code + change**, and the live visual gate is clean (`[cell-transit]` monotonic, no ping-pong). Both retail + and acdream pick with center-only `point_in_cell` on `global_sphere[0]`; commit via + `validate_transition` = the `find_cell_list` pick — structurally identical. See + `docs/research/2026-06-03-p1-membership-swept-advance-handoff.md` (RESOLVED banner) + + `memory/project_retail_membership_criterion.md`. **RE-SCOPED:** the original P1 + deletes/unifications — (a) demote/remove `ResolveCellId` (already out of the prod per-frame path), + (b) unify the forked `find_env_collisions`, (c) replace `CheckBuildingTransit` with intrinsic + building stabs in `find_transit_cells`, (d) make the per-cell ObjCell graph the collision authority + — are now **approval-gated refactors of WORKING code, NOT bug fixes**; they wait for explicit user + approval (CLAUDE.md "don't replace working retail-faithful logic without approval"). One soft spot: + outdoor→indoor `0031↔0170` building-entry is live-clean but NOT conformance-locked (rides on the + un-ported `CheckBuildingTransit` bridge). +- **P2 — Door/building-shell collision (B3/B4) — IN PROGRESS, root cause LOCALIZED 2026-06-03.** The + 5 failing Core tests localize to **BSP Path 5 grounded step-up**. The wrappers — Path 5 dispatch + (Contact branch), the recursion guard, `DoStepUp` (= retail `CTransition::step_up` pc:273099), + `DoStepDown` (= retail `step_down` pc:272946) — are verified faithful + correctly reached; the + divergence is in the step-up CLIMB itself (`find_walkable`/`step_sphere_down`'s upper-floor find + + sphere-up-adjust when `sp.StepUp=true`; retail `BSPTREE::step_sphere_down` pc:323665). Cleanest + isolation: `B1_GroundedMover_LowStep_StepsUp` (wall-slides a walkable 0.25 m step). Pickup: + `docs/research/2026-06-03-p2-door-stepup-handoff.md`. **Gate:** stand in the doorway — no position + oscillation (foot Y stable); walk through cleanly; walls block; step up a low cottage stair (climbs). - **P3 — Camera viewer-cell (C1/C3).** Port `find_visible_child_cell` + the faithful `update_viewer` start-cell/fallbacks. **Gate:** `viewerCell` is stable + correct as the camera orbits across boundaries (no `[flap-cam]` thrash). - **P4 — PView render (D2–D9), the core.** Replace `PortalVisibilityBuilder`/`ProjectToNdc`/`ScreenPolygonClip` with `ConstructView`/`InitCell`/`ClipPortals`/`GetClip`/`AddViewToPortals` + `portal_view_type`/`update_count`; re-port `DrawCells`' seal verbatim. **Gate:** cottage interior sealed (opaque walls, no transparent/flap, no void), sky/terrain through the door only. - **P5 — Outside-looking-in (D8).** `DrawPortal` + `ConstructView(CBldPortal)`. **Gate:** from the street the interior renders through the door (no see-through box).