acdream/docs/research/2026-05-20-phase-a4-shipped-cell-pingpong-finding.md

# Phase A4 shipped + cell-tracking ping-pong finding — 2026-05-20

**Status:** A4 (multi-cell BSP iteration) shipped in 3 commits + 1 revert + 1 reapply
+ 1 doc. Build green, 1139 + 8 baseline failures (same as pre-A4 baseline).
A4 is **dormant in practice** because of a separate, pre-existing cell-tracking
bug at the inn doorway that prevents the player from stably remaining in an
indoor cell.

## TL;DR

- A4 ports retail's `CTransition::check_other_cells` (`acclient_2013_pseudo_c.txt:272717-272798`).
  After the primary cell's BSP returns OK, every other cell the foot-sphere overlaps
  is queried via `BSPQuery.FindCollisions`. Halt on first
  Collided/Adjusted/Slid; Slid clears the contact-plane fields. Matches retail
  exactly.
- 10 new unit tests pass; full test suite holds at the prior 8-failure baseline.
  Three commits land the slices (FindCellSet overload → CheckOtherCells helper →
  FindEnvCollisions wire-up).
- **Visual verification surfaced a different bug**: walking into the Holtburg
  inn ping-pongs the player's CellId between indoor `0xA9B40164` and outdoor
  `0xA9B40022` rapidly. Indoor BSP DOES detect walls (Collided / Adjusted /
  Slid all fire on push-back), but the push-back moves the sphere outside the
  indoor CellBSP's volume → `ResolveCellId` reclassifies the player as outdoor
  → next tick bypasses indoor BSP entirely → player advances freely → re-enters
  → repeats.
- Because the player never STAYS in an indoor cell, A4's multi-cell pass is
  rarely (if ever) actually exercised in production. The user's reported
  "walls walk through everywhere in the inn" reproduces fully with A4 wire-up
  reverted, confirming A4 is not the cause.

## What shipped

| SHA | Phase | Description |
|---|---|---|
| `b100d54` | A4 spec | docs/superpowers/specs/2026-05-20-phase-a4-multi-cell-bsp-design.md |
| `a8a0366` | A4 plan | docs/superpowers/plans/2026-05-20-phase-a4-multi-cell-bsp.md |
| `e6369e2` | A4 slice 1 | `CellTransit.FindCellSet` overload + 3 unit tests |
| `493c5e5` | A4 slice 2 | `Transition.CheckOtherCells` + `ApplyOtherCellResult` + 6 unit tests |
| `967d065` | A4 slice 3 | Wire `CheckOtherCells` into `FindEnvCollisions` + 1 integration test |
| `3add110` | A4 revert | Temporary revert of slice 3 to confirm A4 wasn't the cause |
| `691493e` | A4 reapply | Restored slice 3 after revert test proved A4 not the cause |

Total: ~380 LOC added (3 new test files + helper methods); 1139 + 8 baseline
maintained throughout.

## Visual verification — what we tested

Launched twice with the light-probe set (`ACDREAM_PROBE_INDOOR_BSP`,
`ACDREAM_PROBE_CELL`, `ACDREAM_PROBE_CELL_CACHE`).

### Launch 1 — A4 wire-up active (`launch-a4.log`, 782 lines)

User walked from spawn toward the Holtburg inn. Log captured:
- Player CellId stayed at outdoor `0xA9B4002A` the entire session.
- 0 indoor-bsp probes fired.
- 0 other-cells probes fired (A4 wire-up only runs for indoor cells).
- User reported "all interior walls in the inn can be walked through; going
  from indoor to outdoor broken."

But — A4 wire-up only fires when `cellLow >= 0x0100`. The player never reached
that state. So A4 couldn't possibly be the cause of the reported behavior.

### Launch 2 — A4 wire-up reverted (`launch-revert2.log`, 18490 lines)

User walked into and out of the inn multiple times. Log captured:
- 18 cell-transit events: outdoor cells `0xA9B40021` / `0xA9B40022` /
  `0xA9B4002A` ping-ponging with indoor cell `0xA9B40164` (vestibule).
- 11 `[check-bldg] inside=True` events — player crossed the building threshold.
- 61 indoor-bsp queries against `0xA9B40164` (58) and `0xA9B40162` (3).
- Indoor BSP results: 40 OK + 7 Adjusted + 7 Collided + 7 Slid.
- User confirmed: "walls still walked through (same bug)" with A4 reverted.

**The bug reproduces with A4 reverted, proving A4 is not responsible.**

## The actual bug — cell-tracking ping-pong at doorway threshold

The repeating cycle observed in the revert log:

1. Player at outdoor cell `0xA9B40022`, walking toward inn door.
2. `CheckBuildingTransit` returns `inside=True` for portal to `0xA9B40164`.
3. ResolveCellId promotes CellId to `0xA9B40164`.
4. Next tick: indoor branch of FindEnvCollisions fires. BSP query against
   `0xA9B40164`'s walls returns Adjusted/Collided/Slid. The sphere is pushed
   back (Adjusted/Slid) or halted (Collided).
5. The push-back moves the sphere's world position BACK toward the outdoor
   side, beyond the indoor CellBSP's volume.
6. ResolveCellId re-evaluates: indoor CellBSP no longer contains the sphere
   center → falls through to outdoor resolution → returns `0xA9B40022`.
7. CellId flips back to outdoor. Next tick: indoor BSP not queried, player
   keeps advancing.
8. Player re-crosses the building threshold → goto 2.

Net effect: the player visually moves through the doorway zone, walls
intermittently push them back, but most ticks classify them as OUTDOOR and
those ticks bypass wall collision entirely. The aggregate behavior LOOKS LIKE
"walls walk through" even though wall hits are firing.

### Why A4 doesn't help here

A4 multi-cell iteration only runs when the primary cell BSP returns OK. In the
ping-pong cycle, the primary cell BSP returns NON-OK (Collided/Adjusted/Slid)
on most indoor frames — so A4 short-circuits early at the existing `if (cellState
!= TransitionState.OK) return cellState;` path. A4 would help if the player
were STABLY indoor (cellLow >= 0x100) AND the primary cell's BSP had sparse
geometry that missed walls in adjacent cells. The ping-pong prevents both
conditions.

### Why this is a Bug A cousin

The 2026-05-20 Bug A investigation
([docs/research/2026-05-20-indoor-walking-bug-a-handoff.md](2026-05-20-indoor-walking-bug-a-handoff.md))
documented a similar doorway-edge problem: indoor cell floor polys don't
extend past the doorway threshold, causing free-fall when stepping out.

The current ping-pong is the same family of bug, different symptom: the
indoor CellBSP volume doesn't extend past the doorway threshold either, so
the push-back from a wall collision exits the cell's containment volume,
and the cell-id resolver bounces the player back to outdoor.

Hypothesis: the inn's vestibule cell `0xA9B40164` has a CellBSP that's tightly
bounded to the room's interior volume. The doorway threshold is right at the
boundary. Walking against an interior wall pushes the foot-sphere back toward
the boundary → exits CellBSP → outdoor classification.

## Next steps (not blocking A4 ship)

Two paths to investigate the ping-pong, both out of A4's scope:

1. **CellBSP-volume retention.** Match retail's behaviour: once a player enters
   an indoor cell, don't flip back to outdoor until they cross the EXIT portal
   plane, not just because they exited the CellBSP volume on a push-back.
   Likely a `ResolveCellId` modification that prefers the previous indoor
   classification when sphere is "close enough" to the indoor CellBSP volume.

2. **CellBSP-volume expansion.** Pad the indoor cell's CellBSP volume by the
   sphere radius (~0.48m) on all sides. The push-back stays within the
   padded volume. Risk: may incorrectly classify nearby outdoor positions as
   indoor.

The retail oracle for cell-id stickiness is at
`acclient_2013_pseudo_c.txt:308742-308783` (`CObjCell::find_cell_list` Position-
variant) and the cell-array hysteresis logic around it. Not yet ported in
detail.

## Why ship A4 anyway

- **Correctness.** A4 matches retail's `check_other_cells` exactly. 10 unit
  tests pin the halt semantics + integration test verifies the wire-up. Pure
  port, no design improvisation.
- **No regressions.** 1139-passing + 8-pre-existing-failing baseline holds.
  All A1 / A1.5 / A1.6 / A1.7 / Bug B fixes remain green.
- **Foundation for A3.** A3 (synthesis removal) is unblocked by A4 being in
  place — it can rely on multi-cell BSP coverage for floor synthesis once the
  ping-pong is fixed and players stay indoor long enough.
- **Reverting it would lose work.** A4 is correct and tested. The dormant
  state is caused by an unrelated bug. Reverting would just make the
  unrelated bug harder to investigate (no multi-cell foundation to build on).

## What this is NOT

This is **NOT** a fix for the user's "walls walk through" report. That bug is
pre-existing, caused by cell-tracking instability at doorway thresholds.

This is **NOT** a regression introduced by A4. The bug reproduces fully with
A4's wire-up reverted (verified by `launch-revert2.log`).

This is **NOT** the same as Bug A (synthesis removal). Bug A's symptom was
free-fall on doorway exit; this is wall walk-through due to CellId classification
flipping back to outdoor on each push-back.

## Code anchors

- Phase A4 wire-up: [src/AcDream.Core/Physics/TransitionTypes.cs:1614-1631](../../src/AcDream.Core/Physics/TransitionTypes.cs#L1614).
- `CheckOtherCells` + `ApplyOtherCellResult`: TransitionTypes.cs (search `CheckOtherCells`).
- `FindCellSet` overload: [src/AcDream.Core/Physics/CellTransit.cs](../../src/AcDream.Core/Physics/CellTransit.cs) (search `FindCellSet`).
- ResolveCellId outdoor branch (where the ping-pong happens): [src/AcDream.Core/Physics/PhysicsEngine.cs:259-329](../../src/AcDream.Core/Physics/PhysicsEngine.cs#L259).

## Probe captures

- `launch-a4.log` (782 lines) — A4 active, player stayed outdoor (didn't reach
  inn). Confirms A4's indoor branch never fired in that session.
- `launch-revert.log` (1.2M lines) — A4 reverted, player parked at outdoor cell
  with 400K+ `[check-bldg]` probes all returning `inside=False`. Player never
  moved.
- `launch-revert2.log` (18490 lines) — A4 reverted, player walked into inn
  multiple times. Captured the ping-pong cycle. Indoor BSP results breakdown:
  40 OK + 7 Adjusted + 7 Collided + 7 Slid. 11 `inside=True` building-transit
  events.

## How to start a fresh session

Open a new Claude Code session, then:

```
Pick up the cell-tracking ping-pong investigation that blocked Phase A4
from being exercised in practice.

1. Read docs/research/2026-05-20-phase-a4-shipped-cell-pingpong-finding.md
   FIRST. It documents A4 ship (correct, dormant) + the ping-pong bug it
   surfaced.

2. A4 is shipped (3 commits at e6369e2, 493c5e5, 691493e). Don't touch it.
   1139 + 8 baseline holds.

3. The real M2 blocker: at the Holtburg inn doorway, CellId ping-pongs
   between 0xA9B40022 (outdoor) and 0xA9B40164 (vestibule) every few ticks
   because indoor BSP push-back exits the indoor CellBSP volume → outdoor
   reclassification → walls bypassed on outdoor ticks.

4. Investigate cell-id hysteresis. Retail oracle:
   acclient_2013_pseudo_c.txt:308742-308783 (CObjCell::find_cell_list
   Position-variant). Look for the cell-array stickiness logic that retail
   uses to prevent ping-pong.

5. CLAUDE.md rules: no workarounds, retail-faithful, probe-first.

State M2 as the milestone, "cell-tracking ping-pong fix" as the phase.
```