acdream/docs/research/2026-05-23-a6-p3-issue98-replay-comparison.md

# A6.P3 issue #98 — acdream replay vs retail cdb comparison

**Date:** 2026-05-23
**Worktree:** `C:\Users\erikn\source\repos\acdream\.claude\worktrees\strange-albattani-3fc83c`
**Status:** Apparatus complete. Divergence identified. Fix plan to follow.

This document closes the loop on Step 5 of
[`C:\Users\erikn\.claude\plans\i-did-some-work-sharded-acorn.md`](../../C:/Users/erikn/.claude/plans/i-did-some-work-sharded-acorn.md).
It compares acdream's deterministic-replay output against the retail
cdb capture taken at the equivalent scenario, and names the
divergence target for the (next) fix plan.

The four prior sessions (2026-05-22 AM + PM, 2026-05-23 AM + PM)
shipped 10+ speculative fixes without data. This session shipped the
apparatus that turns the next attempt into evidence-driven work
(commits `35b37df` → `6f666c1` on top of slice 5's `cf3deff`).

---

## TL;DR — the divergence target

**Retail's `BSPLEAF::find_walkable` accepts the cottage main floor
polygon when the sphere is RESTING ON TOP of it.** Sphere local
Z = +radius (= +0.48 in the cottage cell). Sphere world Z ≈ 94.48
(cottage floor at world Z=94, plus radius).

**acdream's failing-frame sphere is 0.69m BELOW the cottage main floor
plane** when our walkable query runs. Sphere local Z = -0.6883 in
0xA9B40143. Sphere world Z ≈ 93.31.

Delta: **retail's sphere is 1.17 m higher** at the equivalent decision
point. Either:

1. Our step-up sequence doesn't lift the sphere high enough before
   `find_walkable` is called against the cottage cell, OR
2. We're calling `find_walkable` against the cottage cell using the
   wrong sphere reference (foot-sphere center instead of the step-
   lifted center), OR
3. The cellar→cottage transition in retail happens GRADUALLY across
   many physics ticks (the sphere climbs the ramp one step at a time),
   and acdream's per-tick climb is too small.

The fix plan needs to choose between (1), (2), and (3) — most likely
(3) given retail's BPE-write distribution.

A surprising secondary finding: **`CPolygon::find_crossed_edge` fires
ONLY ONCE in 35K probe hits in retail.** Our replay harness uses
`FindCrossedEdge` as the primary edge-containment test. Either retail
takes a different path through the walkable predicate cascade, or
acdream is over-reliant on the edge test for a case retail doesn't
hit.

---

## Apparatus shipped this session

Six commits on top of `cf3deff` (slice 5):

| Commit  | What |
|---------|------|
| `35b37df` | chore(phys): A6.P3 #98 triage — revert neg-poly + bldg-check experiments. Kept: render-vs-physics origin split (GameWindow), terrain-hole cutout, multi-sphere CellTransit, step-walk diagnostic probes. Reverted: neg-poly path split, bldg-check flag, isBuilding propagation, IsLandblockBuilding. Test baseline restored to 1148+8 base. |
| `f62a873` | feat(phys): Step 2 — cell-dump probe (`ACDREAM_DUMP_CELLS=0xA9B4xxxx,...`) + JSON DTOs (`CellDump`, `PolygonDump`, etc.) + `CellDumpSerializer` (Capture / Read / Write / Hydrate) + 4 round-trip tests. |
| `3f56915` | capture(phys): Three cell fixtures from live capture — 0xA9B40143 (14 polys), 0xA9B40146 (4 polys), 0xA9B40147 (37 polys). All share worldOrigin=(130.5, 11.5, 94.0) with 180° yaw. |
| `856aa78` | test(phys): Step 3 — `Issue98CellarUpReplayTests` — 7 tests reproducing the live failure pattern deterministically (<1ms per test). Confirms 0xA9B40143 poly 0x0004 rejected at the failing-frame sphere; 0xA9B40146 has no walkable candidate at all. |
| `6f666c1` | tools(cdb): Step 4 — `issue98-cellar-up-find-walkable.cdb` + `issue98-runner.ps1` for retail-side capture. BPA/B/C/D/E/F break on find_walkable, walkable_hits_sphere, find_crossed_edge, check_other_cells, set_contact_plane, adjust_sphere_to_plane. |
| (this doc) | Step 5 — divergence comparison. |

---

## Raw data — retail cdb capture

Capture: [`docs/research/2026-05-23-a6-captures/cellar_up_capture_1/retail.log`](2026-05-23-a6-captures/cellar_up_capture_1/retail.log)
(decoded: `retail.decoded.log`)

User ran retail acclient.exe v11.4186 attached via
`tools/cdb/issue98-runner.ps1 -ScenarioTag "cellar_up_capture_1"`. They
walked up and down a Holtburg cottage cellar stair several times. cdb
captured 35,219 BP hits over ~5 seconds of motion.

Hit distribution:

| BP  | Function                                     | Hits   | Notes |
|-----|----------------------------------------------|--------|-------|
| BPA | `BSPLEAF::find_walkable`                     | 6,160  | per-leaf walkable query |
| BPB | `CPolygon::walkable_hits_sphere`             | 7,028  | per-polygon overlap test |
| BPC | `CPolygon::find_crossed_edge`                | **1**  | almost never fires! |
| BPD | `CTransition::check_other_cells`             | 21,422 | outer dispatcher fires very frequently |
| BPE | `COLLISIONINFO::set_contact_plane`           | **161**| ContactPlane writes |
| BPF | `CPolygon::adjust_sphere_to_plane`           | 431    | sphere projections |

### BPE — retail's accepted ContactPlanes

Every one of the 161 BPE writes lands on one of TWO planes:

```
n=(0, 0, 1)  d=-93.9998  →  world Z=94    (cottage main floor)
n=(0, 0, 1)  d=-90.9500  →  world Z=90.95 (cellar floor)
```

Retail's ContactPlane is **never** set to:
- the cellar ramp (normal ≈ (0, -0.719, 0.695))
- any of the cellar wall polygons
- the cellar ceiling (poly 0x0020 in our nomenclature — normal=(0,0,-1) at world Z=93.82)

The transition cellar floor → cottage main floor happens directly:
ContactPlane shifts from `d=-90.95` to `d=-93.9998` with no
intermediate plane.

### BPA — sphere position at each cottage-floor acceptance

The find_walkable call immediately before each BPE write to the
cottage floor shows a consistent sphere position pattern:

| BPE hit | Last BPA before        | Sphere LOCAL                  | Notes |
|---------|------------------------|-------------------------------|-------|
| #1      | hit#435 (cell B)       | (-0.3270, 0.5998, +0.6300)    | first cottage-floor accept |
| #50     | hit#2533 (cell B)      | (-0.3131, 0.7340, +0.6300)    | cz unchanged |
| #100    | hit#3822 (cell B)      | (-0.3245, 0.3292, +0.6300)    | cz unchanged |
| #160    | hit#6159 (cell B)      | (-0.3195, 0.5271, +0.6300)    | cz unchanged |

Sphere local Z is consistently **+0.6300** in cell B at the moment
retail accepts. Cell B's cottage floor plane is at local Z=-0.15
(observed from BPB hit#7012 with plane d=-0.15), so the sphere is
0.78m above that floor. Sphere radius 0.48 → sphere bottom is 0.30m
above the floor — close enough that `walkable_hits_sphere` accepts.

The find_walkable hit just BEFORE the cell-B query (hit#433, hit#2532,
hit#3820, hit#6158) lands in a different cell ("cell A") at local
position ≈ `(-11.12, 7.16, +0.48)`. Cell A's cottage floor plane is at
local Z=0 → sphere is 0.48m above (= sphere radius), perfectly resting
on the floor.

**Both cells consistently see the sphere at `local Z = +0.48 to +0.63`
at the acceptance moment.** Sphere world Z ≈ 94.48 — the sphere has
been lifted ABOVE the cottage floor.

---

## acdream replay — sphere position at the equivalent moment

Replay anchor: failing-frame sphere world position
`(141.7164, 8.3937, 92.0093)` r=0.4800, from
[`a6-issue98-negpoly-20260523-135032.out.log`](../../a6-issue98-negpoly-20260523-135032.out.log)
line 11338 (`[walkable-nearest]`) + 11339 (`[issue98-walkable-detail]`).

In cell 0xA9B40143 (cottage neighbour, 14 physics polys):

```
sphere LOCAL = (-11.2892, 4.3653, -0.6883)
nearest walkable: poly 0x0004
  plane n=(0,0,1) d=0  (local) →  world Z=94 (cottage floor)
  verts: [(-6.2, 7.6, 0), (-10.0, 7.6, 0), (-10.0, 2.8, 0)]
  signed distance from plane: -0.6883
  abs distance: 0.6883
  gap (abs - radius): 0.2083
  insideEdges: FALSE   (sphere XY beyond triangle edge by 1.29 m on X)
  overlapsSphere: FALSE (|0.6883| > radius 0.48)
```

In cell 0xA9B40146 (cottage neighbour, 4 physics polys):

```
sphere LOCAL = (similar)
nearest walkable: NONE
  (the cell has no Z-up polygon close enough to be selected)
```

In cell 0xA9B40147 (cellar primary, 37 physics polys):

```
sphere LOCAL = (-11.2164, 3.1063, -1.9907)
nearest walkable: the cellar ramp (poly 0x0008 — n=(0,-0.719, 0.695))
  → accepted as ContactPlane
```

Our replay confirms the live failure: cottage-cell walkable queries
return no usable result; cellar ramp is the only ContactPlane we ever
get.

---

## Side-by-side comparison

| Field                                   | Retail (BPE #1)     | acdream (negpoly fail) |
|-----------------------------------------|---------------------|-------------------------|
| Sphere world Z                          | **94.48**           | **92.01**               |
| Cottage floor plane (world)             | Z = 94              | Z = 94                  |
| Sphere position vs cottage floor        | **+0.48 m ABOVE**   | **-1.99 m BELOW**       |
| Sphere top vs cottage floor             | +0.96 m above       | -1.51 m below           |
| Walkable accepted in cottage cell?      | **YES** — sphere rests on plane | **NO** — sphere far below plane |
| ContactPlane set to cottage floor?      | **YES** (161 times) | **NO** (never)          |
| find_crossed_edge invocations           | 1 (in 35K BPs)      | (used heavily by our walkable test) |
| check_other_cells invocations           | 21,422              | (per-tick, similar order) |

**Sphere world Z delta: 2.47 m.** Retail's sphere is nearly 2.5 m
higher than ours at the equivalent decision point.

---

## Plausible fix targets, in priority order

These are HYPOTHESES — the fix plan must verify each before changing
code. Each is testable against the replay harness without launching
the client.

### Target 1 (highest confidence): step-up + ramp climb doesn't gain enough Z per tick

Retail's data shows the sphere climbs the ramp GRADUALLY across many
ticks — BPB hits move smoothly from sphere local Z=-2.57 (resting on
cellar floor) through intermediate values up to sphere local Z=+0.48
(resting on cottage floor) over ~7,000 walkable_hits_sphere calls.

Our `[step-walk]` diagnostic from the failing log shows the sphere
oscillating at world Z ≈ 92.0 — never gaining altitude. The ramp's
ContactPlane is being set but `AdjustOffset` is consuming all
WalkInterp on the lift, leaving nothing for forward motion (slice 7
handoff's reading was right on this).

Look at:
- `Transition.AdjustOffset` — when ContactPlane is the ramp, forward
  motion should project to ramp-local, gaining Z. Does it?
- `Transition.DoStepUp` — when does step-up fire? Is it lifting by
  the right amount? Compare to retail's step_sphere_up.
- The interaction between WalkInterp depletion and step-up — does our
  step-up reset WalkInterp like retail does?

### Target 2: cottage-cell candidacy uses wrong sphere reference

Retail iterates cells with the SAME sphere across find_walkable calls
in a tick. The sphere position visible to find_walkable for the
cottage cell is already at the lifted position. acdream's
`CellTransit.FindCellSet` uses `sp.GlobalSphere` — but at what tick
phase? If we use the pre-step-up sphere center to decide cottage-cell
candidacy, but then run the walkable query at the same pre-step-up
position, we'll never see the cottage cell as walkable.

Look at:
- `CheckOtherCells` in `TransitionTypes.cs` — what sphere does it
  pass to `BSPQuery.FindCollisions`? Does it use the step-lifted
  position or the pre-step position?
- The retail oracle `CTransition::check_other_cells` at
  `acclient_2013_pseudo_c.txt:272717-272798`.

### Target 3: find_crossed_edge is over-used in our walkable acceptance

Retail's BPC hit count of 1 in 35K is a striking outlier. Either
retail's walkable acceptance never needs the edge containment test
(because `walkable_hits_sphere` does enough), or `find_crossed_edge` is
gated behind a different code path we're not hitting.

Look at:
- `BSPQuery.FindCrossedEdge` — when is it called? Compare to retail's
  `CPolygon::find_crossed_edge`. Maybe we call it in step-up, retail
  doesn't.

This is a SECONDARY target — not directly the issue #98 failure mode,
but a code-shape divergence worth investigating once the primary fix
lands.

### Target 4 (low confidence): the cellar ramp normal-Z is wrong

If our cellar ramp polygon has a slightly wrong normal compared to
retail, AdjustOffset's slope projection would compute different Z
gains. The polydump capture shows ramp normal (0, -0.7190, 0.6950);
the JSON fixture has the same. Likely not the bug, but worth
verifying via `dotnet test` after any fix attempt.

---

## What the apparatus delivers for future fix attempts

1. **`Issue98CellarUpReplayTests`** runs in <200ms with no client
   launch. Any change to `BSPQuery.FindCrossedEdge`, polygon
   containment, or cell transform shows up instantly.

2. **JSON fixtures in `tests/AcDream.Core.Tests/Fixtures/issue98/`**
   are real-geometry captures. Any future fix can call
   `CellDumpSerializer.Hydrate` to load them and drive the predicates
   directly.

3. **`tools/cdb/issue98-runner.ps1`** is reusable. Any new
   hypothesis can be re-captured against retail with a 5-minute user
   action.

4. **`tools/cdb/decode_retail_hex.py`** decodes the hex-bits format —
   no changes needed.

5. The retail comparison data is checked into
   `docs/research/2026-05-23-a6-captures/cellar_up_capture_1/` —
   future analyses can re-grep without re-capturing.

---

## What this plan does NOT do

This document does not ship a fix. The fix is the next plan, scoped to
Target 1 (most likely) or Target 2 (next likely). The user should
review this divergence reading before authorizing implementation.

Per CLAUDE.md and the systematic-debugging mandate: 4 prior sessions
guessed and were wrong. This plan refuses to be the 5th.

---

## Pickup prompt for the fix plan

Open this worktree:
`C:\Users\erikn\source\repos\acdream\.claude\worktrees\strange-albattani-3fc83c`

Then:

```
A6.P3 issue #98 — apparatus complete; ready to write the fix plan.

Read FIRST:
  docs/research/2026-05-23-a6-p3-issue98-replay-comparison.md
  tests/AcDream.Core.Tests/Physics/Issue98CellarUpReplayTests.cs
  docs/research/2026-05-23-a6-captures/cellar_up_capture_1/retail.decoded.log

State both altitudes:
  Currently working toward: M1.5 — Indoor world feels right
  Current phase: A6.P3 — fix #98 cellar-up (fix plan)
  Next concrete step: pick Target 1 (step-up Z gain) or Target 2
  (cottage-cell sphere reference) from the comparison doc and write
  the fix plan against it. NO speculative fixes — use the replay
  harness to verify the hypothesis before writing code.

The fix MUST be evidence-driven. The replay harness gives us a 200ms
test loop; a fix that doesn't change the failing assertions in
Issue98CellarUpReplayTests is not the fix.

Test baseline: 1167 + 8 (with apparatus). Maintain through any fix.
CLAUDE.md rules apply. No workarounds without explicit approval.
```