acdream/docs/research/2026-06-03-p0-conformance-apparatus-notes.md

# P0 — Conformance apparatus notes (characterized topology + goldens)

2026-06-03. Companion to [`docs/superpowers/plans/2026-06-03-p0-conformance-apparatus.md`](../superpowers/plans/2026-06-03-p0-conformance-apparatus.md).
Source of truth for the cell ids + golden inputs the P0 conformance tests pin. All values below
were **characterized from the real client dats** (not guessed) by
`CottageDoorwayCharacterizationTests` against `%USERPROFILE%\Documents\Asheron's Call`.

## Characterized Holtburg (landblock 0xA9B4) indoor neighborhood

Scanned `0xA9B40140..0xA9B4017F`. All cells load with a real ContainmentBsp and `seenOutside=1`.
Cells share a per-BUILDING world origin (the building's reference frame). The distinct buildings:

| Cell range | World origin | Stab | Identity |
|---|---|---|---|
| `0140..0150` (17 cells) | (130.50, 11.50, 94.00) | 17 | **Cottage-with-cellar** (#98 cellar saga; exit portals at 0145,014C,014E,014F,0150) |
| `0151..0169` (25 cells) | (107.50, 36.00, 94.00) | 24 | Larger building (inn) |
| `016A..016E` (5 cells) | (79.50, 37.50, 94.00) | 4 | Small building |
| **`016F..0175` (7 cells)** | **(161.93, 7.50, 94.00)** | 6 | **THE doorway-threshold building (master-plan 0170/0171)** |
| `0176..0178` | (65.21, 156.63, 66.00) | 2 | — |
| `0179..017A` | (158.18, 37.71, 94.00) | 1 | — |
| `017B..017F` | (161.72, 105.05, 66.00) | 4 | — |

## The pinned threshold topology (master-plan `0031↔0170↔0171`)

Building at world origin **(161.93, 7.50, 94.00)**:

| Cell | Role | Portal dests | seenOutside | BSP |
|---|---|---|---|---|
| `0xA9B40170` | **vestibule / doorway** | `[0xFFFF (exit→outdoor), 0x0171]` | 1 | real |
| `0xA9B40171` | **room** (behind the door) | `[0x0170, 0x0173, 0x0175]` | 1 | real |

Grid math confirms the outdoor side: origin (161.93, 7.50) → gridX = ⌊161.93/24⌋ = 6,
gridY = ⌊7.5/24⌋ = 0 → landcell id `6*8 + 0 + 1 = 49 = 0x31` → **outdoor landcell `0xA9B40031`**.
So the player crossing the doorway traverses `0031 (outdoor) → 0170 (vestibule, via the 0xFFFF exit
portal) → 0171 (room)` — exactly the master-plan ping-pong `0031↔0170↔0171`. **Verified real.**

> Naming note: a 2026-05-21 capture dir called `0170/0171` the "inn 2nd floor"; that label was
> loose. By geometry it is the 7-cell building at (161.93, 7.50). Identity (cottage vs inn) is
> irrelevant to the conformance — what matters is `0170` carries the exit portal (the doorway) and
> `0171` is the room behind it.

## Golden interior points (verified `point_in_cell == true`)

Cell-LOCAL points whose `EnvCell.PointInCell(world)` returns true (the world form is
`Vector3.Transform(local, cellPhysics.WorldTransform)`):

| Cell | Interior LOCAL point | Interior WORLD point | Notes |
|---|---|---|---|
| `0xA9B40170` | (5.865, -8.449, 0.417) | (156.06, 15.95, 94.42) | 115/125 grid-inset points inside (small/irregular vestibule) |
| `0xA9B40171` | (6.55, -3.25, 4.60) | (157.01, 13.69, 95.53)* | bounds-center = bsphere origin; 125/125 inside (clean box) |

\* world recomputed by the test at runtime via the cell's WorldTransform; the value above is the
firstInside probe — the canonical bsphere-origin local (6.55,-3.25,4.60) is also fully interior.

These are **retail-faithful by construction**: the ContainmentBsp is loaded from the same dats
retail loads, so a geometrically-correct containment answer is the retail answer.

## Golden provenance summary

| Golden | Provenance | Status |
|---|---|---|
| `point_in_cell` (interior true, far-away false) | geometric (real dat BSP) | autonomous (Task 3) |
| `find_cell_list` deep-inside picks `0171`/`0170` | geometric (real dat cells) | autonomous (Task 4) |
| `find_cell_list` doorway-threshold pick | **retail cdb trace** | Task 6 — USER GATE / mine existing traces |
| PVS visible-set | retail cdb `cell_draw_list` trace | deferred to P4 (Task 7 scaffold) |

## Existing retail traces — mined, NOT usable for membership

`docs/research/2026-05-21-a6-captures/*/retail.log` + `retail.decoded.log` were grepped for
`change_cell` / `curr_cell` / `find_cell_list` / `cell=0x` / `insert_into_cell`. **Zero matches in
any retail log** — all 15,492 membership/cell-id matches are in the paired `acdream.log` files
(our own probe output). The committed retail traces are collision-only (`find_collisions`
hit-counters, `set_neg_poly_hit`, etc.); they carry no membership cell-id or position. So the
retail-trace-backed threshold golden **cannot** be built from existing data — a live capture is
required (`tools/cdb/find-cell-list-capture.cdb`).

## Retail capture — DONE (2026-06-03). The P0 gate is MET.

Captured live from retail (cdb on `CPhysicsObj::change_cell`, symbol-driven, PDB MATCH) at the
"Agent of Arcanum" house — which by geometry IS the `0170`/`0171` building. **22 transitions, a
perfectly clean monotonic `0031↔0170↔0171` sequence, NO ping-pong** (retail's membership is
correct-by-construction, as the master plan asserts). Golden fixture committed at
`tests/AcDream.Core.Tests/Conformance/Fixtures/find-cell-list-threshold.log`. Capture+decode
tooling: `tools/cdb/find-cell-list-capture.cdb` + `tools/cdb/decode_fcl_capture.py`.

## ★ ROOT-CAUSE FINDING (the central P1 work) ★

The per-transition containment diagnostic (`ThresholdDivergenceDiagnosticTests`) shows **all 22
transitions diverge**, for ONE reason:

| retail transition | retail picks | acdream `FindCellList` | foot `in_seed` | `in_0170` | `in_0171` |
|---|---|---|---|---|---|
| `0170→0171` (enter room) | **0171** | 0170 | 1 | 1 | **0** |
| `0171→0170` (leave room) | **0170** | 0171 | 1 | 0 | **1** |
| `0170→0031` (exit bldg)  | **0031** | 0170 | 1 | 1 | 0 |
| `0031→0170` (enter bldg) | **0170** | 0031 | 0 | 0/1 | 0 |

**Retail transitions membership at the PORTAL CROSSING** (`CEnvCell::find_transit_cells` — the
sphere crosses the doorway polygon plane). **acdream's `FindCellList` re-picks by POINT-IN-CELL
containment at the foot.** So retail commits the neighbour cell BEFORE the foot point is
geometrically inside it (it enters room `0171` while the foot is still inside vestibule `0170`'s
BSP, `in_0171=0`), and acdream lags. This is the master-plan §0 "hysteresis gap" diagnosis
confirmed against live retail — and it is NOT a per-cell hysteresis or a building-entry-only split;
it is a single criterion mismatch (directed portal crossing vs point-in-cell) that affects EVERY
threshold transition.

**P1's central job:** port `CEnvCell::find_transit_cells` (`@ 0x52c820 pc:309968`) directed
portal-crossing so membership transitions at the doorway plane, not at the BSP-containment
boundary. (Plus intrinsic building entry A3 + uniform `find_env_collisions` B1.) The
documents-the-bug test `FindCellList_DoorwayThreshold_DivergesFromRetail_PendingP1` PASSES while
this diverges and FAILS when P1 lands → rewrite it to assert the full sequence then.

**P1 design nuances (from reading `find_transit_cells` @ pc:309968 + the acdream membership map):**
1. `find_transit_cells` (sphere variant) STRUCTURE: per portal —
   (a) exit portal (`other_cell_id == 0xffffffff`): if a sphere crosses the exit-portal polygon
   plane toward outside → set `exitOutside`; (b) interior/building portal with a LOADED neighbour:
   if a sphere `CCellStruct::sphere_intersects_cell(neighbour) != OUTSIDE` → `add_cell(neighbour)`;
   (c) interior/building portal with an UNLOADED neighbour: if a sphere crosses the portal POLYGON
   plane (`dist` vs ±(radius+0.0002), honoring `exact_match`) → `add_cell(other_cell_id)`. After
   all portals, `if (exitOutside) add_all_outside_cells`. The transition's `curr_cell` then advances
   to the crossed/overlapped neighbour — BEFORE foot-containment.
2. **acdream already has `CellTransit.FindTransitCellsSphere`** (a partial port of exactly this:
   exit→exitOutside, loaded-neighbour→`SphereIntersectsCellBsp`, unloaded→plane-distance). So P1 is
   NOT writing find_transit_cells from scratch — it is making `curr_cell` ADVANCEMENT use the
   portal-crossing result (the candidate the sphere crossed into) as the membership answer, instead
   of `FindCellSet`/`FindCellList`'s point-in-cell interior-wins pick. Audit `RunCheckOtherCellsAndAdvance`
   + `SetCheckPos` (the swept-cell advance) — that is where the pick criterion gets chosen.
3. **Test against the PRODUCTION path, not bare `FindCellList`.** The P0 documents-the-bug test
   calls `FindCellList` directly (unit-level). P1's conformance must replay the golden POSITIONS
   through `PhysicsEngine.ResolveWithTransition` (a trajectory, like `CellarUpTrajectoryReplay`,
   seeded incl. the outdoor landcell `0031`) and assert the swept `CellId` sequence matches the
   captured retail `change_cell` sequence. Bare-`FindCellList` is the unit pin; the trajectory is
   the integration gate. (Needs the outdoor landcell + building portal loaded — more than the
   building-only cache P0 uses.)

## ⚠ CORRECTION (same session, after reading `point_in_cell` + an architect pass)

The "all 22 diverge → retail uses portal-crossing, acdream uses point-in-cell" framing above is the
**probe-level** result and is **likely a test artifact**. Two decomp reads correct it:

1. **Retail's `find_cell_list` PICK is center-only `point_in_cell`, NOT radius-aware.**
   `CObjCell::find_cell_list` pick @ pc:308810 calls `vtable[0x84]` = `CEnvCell::point_in_cell`
   (`@ 0x52c300 pc:309677`) → `globaltolocal` → `CCellStruct::point_in_cell` (`@ 0x5338f0 pc:317657`)
   → **`BSPTREE::point_inside_cell_bsp(cell_bsp, point)`** — a center-only point test. The
   radius-aware `sphere_intersects_cell_bsp` is a SEPARATE method (`CCellStruct::sphere_intersects_cell`
   `@ 0x533900 pc:317666`), used by `find_transit_cells`' SET-BUILD, not the pick. So acdream's pick
   criterion (`PointInsideCellBsp`) ALREADY matches retail. An architect hypothesis that the fix is
   "use `SphereIntersectsCellBsp` in the pick" is **FALSIFIED** — that would DIVERGE from retail.

2. **The pick point retail tests is `global_sphere[0].center` (the swept sphere center), not the foot
   origin.** `find_cell_list(&check_pos, num_sphere, global_sphere, …)` (pc:309088); the pick tests
   `arg3->center` = `global_sphere[0].center`. The P0 `FindCellList_DoorwayThreshold_*` tests + the
   diagnostic fed `pick.Position` = the captured `m_position.frame.m_fOrigin` (the FOOT origin at the
   resting position), NOT the sphere center, and NOT through the sweep. The diagnostic's own data shows
   the tell: retail always commits the cell AHEAD of motion while the foot is still behind
   (`0170→0171` with `in_0171=0`; `0171→0170` with `in_0170=0`) — the signature of the **swept sphere
   center crossing the portal**, which a static foot-point probe cannot reproduce.

**What this means for P1.** The membership criterion may NOT be broken; acdream's production
`ResolveWithTransition` already feeds `sp.GlobalSphere` (the sphere center) through the swept
transition. The DECISIVE, evidence-first first step is the **production-path trajectory conformance**
(replay the golden positions through `ResolveWithTransition`, assert the swept `CellId` sequence ==
retail's `change_cell` sequence). Outcomes: (a) production MATCHES → the bare-`FindCellList`
divergence was a probe artifact, P1 shrinks to building-entry cleanup (big de-risk); (b) diverges,
fixed by the right point/sweep → small + localized; (c) still diverges → a real bug, design from THAT
evidence. **Do NOT design or code a P1 membership "fix" before the production-path test exists and its
RED/GREEN is read.** The P0 `..._DivergesFromRetail_PendingP1` test is a UNIT-level pin only, NOT
evidence of a production divergence.

## P0 status / P1-entry checklist — COMPLETE

**Apparatus: COMPLETE + GREEN.** (Conformance suite 59 pass / 1 skip / 0 fail.)
- ✅ Dat-backed fixture loader (`ConformanceDats`).
- ✅ Characterized + pinned cottage-doorway topology (`0031↔0170↔0171` verified real).
- ✅ `point_in_cell` goldens vs real dat BSP.
- ✅ `find_cell_list` unambiguous goldens (interior picks + stale-seed re-pick stability).
- ✅ Retail-trace parser + cdb capture script + decoder + README.
- ✅ PVS-golden scaffold (skipped; filled in P4).
- ✅ **Retail-trace golden captured + the threshold divergence pinned (documents-the-bug, GREEN).**
- ✅ **P0 GATE MET: ≥1 retail-trace-backed assertion exists. P1 may begin.**

**Re-scope note for P1 (discovered during P0):** this branch already carries the membership
"Stage 1" work the master plan's §2 "acdream now" column lists as partial — `CellArray` (ordered
CELLARRAY / R1 flap fix), `FindCellSet`'s interior-wins pick (cites pc:308788-308825),
`RunCheckOtherCellsAndAdvance` (collide-then-pick), swept `sp.CurCellId` return, player-only
`UpdatePlayerCurrCell`. **Per the CORRECTION above, the pick criterion is NOT confirmed wrong** —
retail's pick is center-only `point_in_cell`, same as acdream's. P1's TRUE first step is the
production-path conformance to find where (if anywhere) production membership actually diverges from
the retail `change_cell` golden, THEN the (likely small) fix, THEN delete `CheckBuildingTransit` +
unify `find_env_collisions` + demote `ResolveCellId` to seed-only. Re-confirm against the code +
the production-path evidence when P1 starts — do not port a "portal-crossing pick" on the probe
artifact.