acdream/docs/research/2026-05-24-door-collision-session-end-handoff.md

# Door collision — end-of-session handoff (2026-05-24, late)

**Branch:** `claude/strange-albattani-3fc83c`
**Worktree:** `C:\Users\erikn\source\repos\acdream\.claude\worktrees\strange-albattani-3fc83c`

## TL;DR — what was actually accomplished

**No user-visible bug was fixed this session.** The door bug the user
reported at the start (center blocks, off-center walks through,
inside-out walks through) is **identically reproducible after the
4 commits** as it was before them.

What changed: infrastructure. Server-spawned doors now register
multi-part shadow shapes (cylinder + BSP slab) instead of one
cylinder approximation. The BSP slab is queried 135 times per door
near approach but produces **zero collision hits**, so observed
behavior is unchanged.

**Don't re-do the infrastructure.** It's correctly built and necessary
for any future fix. The remaining work is downstream of it.

## Commits landed (4)

```
163a1f0 diag(phys): [bsp-test] probe + grounded apparatus test + handoff
ca9341c feat(phys): A6.P4 Task 7 — RegisterLiveEntityCollision uses ShadowShapeBuilder + RegisterMultiPart
3b7dc46 fix(phys): GetNearbyObjects dedup-by-entityId silently drops multi-part shadows
e1d94d7 test(phys): door setup + GfxObj dat-inspection — Hypothesis A falsified
```

**Real-but-latent value from these:**
- The dedup-by-entityId issue (3b7dc46) was a latent footgun: any
  future attempt at multi-part shadows (NPCs with hit-region capsules,
  multi-part creatures, props with separated collision) would have
  silently dropped all but the first shape. Now safe.
- The dat-inspection (e1d94d7) proved part 0 (`0x010044B5`) has a
  real 1.9×0.26×2.5 m BSP slab in the dat. A future fix doesn't have
  to question whether the data exists.
- The Task 7 wiring (ca9341c) puts the right architecture in place —
  doors now register the shapes retail expects (cyl per CylSphere +
  cyl per Sphere + BSP per Part-with-BSP).
- The `[bsp-test]` probe (163a1f0) fires before the cache lookup,
  distinguishing "cache miss → silent skip" from "queried but no
  hit" — neither of which `[resolve-bldg]` ever showed.

**Brutally clear: zero of these commits change observed door behavior.**

## What we now know vs. what we don't

### Known (from this session's probes)

- `0x010044B5` PhysicsBSP has 6 collision-bearing polygons forming a
  1.925 × 0.261 × 2.490 m door slab. All `SidesType=Landblock`
  (two-sided). Bounding sphere radius 1.975 m. Verified by direct
  dat read.
- `0x010044B6` (the two leaf parts) have `HasPhysics=false`,
  `PhysicsBSP=null`, `PhysicsPolygons.Count=0`. Visual-only by retail
  design — our skip matches retail's
  `CPhysicsPart::find_obj_collisions:275051`.
- Live Holtburg doors register with `shapes=cyl1+bsp1`. Cache is
  populated. BSP entries are visited (135x for one door at player
  approaches as close as 0.42 m).
- The BSP traversal produces ZERO attributed hits during live walking
  (all 19 `[resolve-bldg]` lines show `gfxObj=0x00000000`, which is
  the Cylinder shape). Whatever is happening inside
  `SphereIntersectsPolyInternal` or the dispatch around it is
  swallowing the hit silently.

### NOT known (don't speculate further)

- **Whether `DoStepUp` is involved.** The prior handoff doc
  (`2026-05-24-door-collision-task7-shipped-but-bug-remains.md`)
  asserted "step-up incorrectly succeeds" as the leading hypothesis.
  That was over-reach. In the apparatus, `ACDREAM_DUMP_STEPUP=1`
  produced no `stepup: ENTER` lines — `DoStepUp` was never called.
  So the apparatus shows `hit=yes n=(0,0,1)` from some OTHER path
  (terrain step-down? walkable poly preservation?). It does not
  confirm step-up is the production bug.
- **Whether the production hit happens at the BSP polygon edge test,
  the BSP node traversal, or some other layer.**
- **Whether the production code path is the same as the apparatus
  path 5 in the first place.**

The earlier framing of "step-up is the bug" was a guess I inflated
into a conclusion. Treat it as a candidate, not a finding.

## Proper next move

**Same pattern that closed issue #98 after 6+ failed speculation rounds:
live capture + apparatus replay.**

The infrastructure for this already exists in the codebase:

1. `ACDREAM_CAPTURE_RESOLVE=<path>` env var (see
   `src/AcDream.Core/Physics/PhysicsResolveCapture.cs`) captures every
   player-side `PhysicsEngine.ResolveWithTransition` call as a JSON
   Lines record with full `PhysicsBody` before-and-after snapshots.
2. `CellarUpTrajectoryReplayTests.LoadCapturedRecord` +
   `AssertCallMatchesCapture` replay a captured record through a
   harness engine and emit the first per-field divergence between
   live and harness outputs.

The plan:

1. Launch with `ACDREAM_CAPTURE_RESOLVE=door-walkthrough.jsonl`
   (no other probes — capture is independent).
2. Walk into a closed Holtburg cottage door 50 cm off-center.
3. Close gracefully. Save the JSONL.
4. Write a new test `LiveCompare_DoorOffCenterWalkthrough` that loads
   the failing-tick record and replays it through a harness with the
   real `0x010044B5` BSP hydrated + registered via
   `RegisterMultiPart`. Compare per-field.
5. The first divergent field names the broken assumption. Fix that.

This is concrete, deterministic, and doesn't ask you to relaunch
multiple times for each fix attempt. The harness round-trip is <500
ms; a fix iteration is ~3 seconds.

## What NOT to do

1. **Do NOT re-do the multi-part registration.** It's correct. The
   dedup fix is correct. Task 7 is correct. Verified by 53/53 tests
   in the targeted scope.
2. **Do NOT speculate-and-fix.** This session burned cycles on a
   "step-up is the bug" hypothesis that wasn't supported by the
   evidence. The apparatus-first rule (`feedback_apparatus_for_physics_bugs.md`)
   exists for exactly this. Build the apparatus before the fix.
3. **Do NOT re-investigate whether the door has BSP polygons.**
   It does. 6 of them. Forming a full door slab. Cached. Visited.
4. **Do NOT relaunch with more probes hoping for an obvious signal.**
   The probes we have already say "BSP visited 135 times, no hits."
   More log lines won't tell us WHY it doesn't hit. The apparatus
   replay will.

## Files to read first

- This doc (you're in it).
- `docs/research/2026-05-24-door-dat-inspection-findings.md` — the
  dat data, polygon layout, bounding sphere center vs frame offset.
- `docs/research/2026-05-24-door-collision-task7-shipped-but-bug-remains.md`
  — the prior end-of-session handoff. **Read with skepticism** — its
  "leading hypothesis" section overstates confidence in the step-up
  theory (corrected here).
- `tests/AcDream.Core.Tests/Physics/CellarUpTrajectoryReplayTests.cs`
  — the capture+replay pattern to mirror for the door bug. See
  `LiveCompare_*` tests.

## State of the M1.5 milestone

Doors at Holtburg cottages: center blocks, off-center walks through,
inside-out walks through. Same as it was 24 hours ago. The walking-
through case is the actual user pain point. Until the apparatus
replay names the divergence, treat M1.5 indoor-world as still
incomplete on the door front.

The infrastructure is in place for the eventual fix. The fix itself
remains future work.

## Pickup prompt for the next session

```
Door collision investigation. Previous session shipped infrastructure
(multi-part registration + GetNearbyObjects dedup fix) but did NOT fix
the user-visible bug: off-center / inside-out approaches still walk
through closed Holtburg cottage doors.

  Read docs/research/2026-05-24-door-collision-session-end-handoff.md

  State both altitudes:
    Currently working toward: M1.5 — Indoor world feels right
    Current phase: A6.P4 door bug — apparatus replay phase.
                   Multi-part registration shipped; need live capture
                   + per-field divergence comparison to identify why
                   the door's BSP slab fires zero attributed hits
                   despite being visited 135x per approach.

  First move: launch the client with ACDREAM_CAPTURE_RESOLVE=<path>,
  walk into a closed Holtburg cottage door 50 cm off-center, close
  gracefully. Then write a LiveCompare_* test in CellarUpTrajectoryReplayTests
  that loads the captured failing tick + replays through a harness
  with the door BSP hydrated via the existing 0x010044B5 dat read
  pattern and registered via RegisterMultiPart.

  DO NOT redo the multi-part registration. DO NOT speculate about
  step-up without evidence — the apparatus tested DoStepUp and it
  didn't fire. The bug is upstream of step-up. The replay will name
  the actual divergence.
```