acdream/docs/superpowers/specs/2026-05-21-indoor-walk-miss-probe-design.md

# Indoor walk-miss probe (ISSUES #83 H-disambiguation spike)

**Date:** 2026-05-21
**Status:** Spec — awaiting user review before plan-writing.
**Phase:** Indoor walking, ISSUES #83 next step. Spike-only — no behavior changes.
**Author:** Claude Opus 4.7.

## Summary

Indoor walking glitches at floor-poly edges and doorway thresholds
(stuck-falling animation). The previous session's investigation
(`docs/research/2026-05-20-indoor-walking-bug-a-handoff.md`) narrowed
the open question to: **when `TryFindIndoorWalkablePlane` returns MISS,
why?** Three live hypotheses (H1 multi-cell iteration missing, H2 probe
distance too short, H3 floor poly absent / `walkable_hits_sphere`
rejection). A single composite probe answers all three in one capture
session. **No physics behavior changes.** The fix is designed in a
follow-up session after the probe data points at the right hypothesis.

## Goal

Add a diagnostic probe set that, at a single Holtburg test run covering
doorway crossing + 2nd-floor edge + cellar descent, produces enough
per-MISS evidence to pick between H1/H2/H3 without attaching cdb to
retail.

## What the probe must capture

For each `[indoor-walkable] ... result=MISS` event, emit a paired
`[walk-miss]` line with:

| Field | Purpose |
|---|---|
| `cellId` | Cross-reference with the cell-load dump. |
| `foot.W` (world XY,Z) | Where the foot sphere is. |
| `foot.L` (cell-local XY,Z) | Cell-local position used by the BSP. |
| `floorPolyCount` | How many walkable-eligible polys this cell holds. |
| `nearest.polyId` | Poly id of the closest walkable poly (XY-overlapping foot, then nearest by `dz`). |
| `nearest.containsFootXY` | `true` if foot XY is inside the poly's local-XY bounding box. |
| `nearest.dz` | Signed vertical distance from foot to the poly plane (positive = foot above poly). |
| `nearest.normalZ` | Normal Z of the poly (high = horizontal floor, low = steep ramp). |
| `landcell.hasTerrain` | Does `engine.SampleTerrainWalkable(foot.X, foot.Y)` return non-null? |
| `landcell.terrainZ` | If yes: the terrain plane Z at that XY (compute as `-D/normal.Z`). |
| `landcell.dz` | `foot.Z - landcell.terrainZ` (positive = foot above terrain). |

Once-per-cell, when `CellPhysics` is cached, emit a `[floor-polys]`
dump:

| Field | Purpose |
|---|---|
| `cellId` | The envCell. |
| `walkableCount` | Polys with `Plane.Normal.Z >= FloorZ`. |
| Per walkable poly: `id, normalZ, bboxLocalXY, planeZAtBboxCenter` | Lets us reconstruct floor coverage offline. |

Both gated on a single new `ProbeWalkMissEnabled` flag.

## Disambiguation matrix (after the run)

Aggregate the `[walk-miss]` lines from the capture, then:

- **`landcell.hasTerrain == true` AND `abs(landcell.dz) < 0.2 m`** → **H1
  confirmed.** Multi-cell iteration would have grounded the player on the
  outdoor LandCell's terrain at the threshold. Fix: port retail's
  `check_other_cells` loop.
- **`nearest.containsFootXY == true` AND `nearest.dz > 0.5 m` AND
  `nearest.dz < 5 m`** → **H2 confirmed.** Floor poly XY-overlaps the
  foot but sits below the 0.5 m probe distance. Fix: increase
  `INDOOR_WALKABLE_PROBE_DISTANCE` (with the retail-faithful constant
  pulled from `acclient_2013_pseudo_c.txt` or the OBJECTINFO step-down
  height).
- **`nearest.containsFootXY == true` AND `nearest.dz <= 0.5 m` AND
  `nearest.normalZ >= FloorZ`** → **H3 candidate.** Poly is XY-aligned,
  within the probe, walkable-slope — should hit but doesn't. Next step:
  cdb attach to retail at `BSPLEAF::find_walkable` to compare poly iter
  with ours.
- **`nearest.containsFootXY == false` AND `landcell.hasTerrain == false`**
  → **H1+H3 combination.** Both indoor and outdoor have no floor here;
  retail must do something we haven't found. cdb attach required.

## Components

### 1. `PhysicsDiagnostics.ProbeWalkMissEnabled`

New static property in `src/AcDream.Core/Physics/PhysicsDiagnostics.cs`,
matching the existing pattern (`ProbeIndoorBspEnabled`, etc):

- Env var: `ACDREAM_PROBE_WALK_MISS=1`.
- Runtime-toggleable via property setter.
- No DebugPanel mirror — one-shot diagnostic, not a persistent toggle.

### 2. Per-MISS `[walk-miss]` log line

In `Transition.FindEnvCollisions` (`TransitionTypes.cs:1538` — the
existing MISS branch of `TryFindIndoorWalkablePlane`'s caller). When
`ProbeWalkMissEnabled`:

1. Walk `cellPhysics.Resolved` for walkable-eligible polys (where
   `poly.Plane.Normal.Z >= PhysicsGlobals.FloorZ`).
2. For each: compute the XY bbox from `poly.Vertices`, compute the
   plane Z at the foot's local XY (`Z = (-D - normal.X*X - normal.Y*Y) /
   normal.Z`), track the one with smallest `|dz|` where foot XY ∈ bbox
   (tiebreaker: smallest `dz` across all polys).
3. Call `engine.SampleTerrainWalkable(foot.X, foot.Y)` for the LandCell
   probe.
4. Emit the line.

Zero cost when flag is off (single bool check guards the whole block).

### 3. One-shot `[floor-polys]` cell-load dump

In `PhysicsDataCache.CacheCellStruct` (immediately after the existing
`[cell-cache]` block at `PhysicsDataCache.cs:182`). When
`ProbeWalkMissEnabled`:

- For each `poly` in `resolved` where `Normal.Z >= FloorZ`: log id,
  normalZ, bbox, `planeZAtCenter`.
- Aggregate into one line if walkableCount ≤ 6, else multi-line.

Fires once per cell — `_cellStruct` is keyed by id with `ConcurrentDictionary` so a second cache call is a no-op (existing path).

### 4. Test coverage

`tests/AcDream.Core.Tests/Physics/IndoorWalkMissProbeTests.cs`:

- `ProbeWalkMiss_StaticApi_Roundtrip` — flag get/set roundtrip with
  finally-restore (mirrors `PhysicsDiagnosticsTests`).
- `WalkMissDiagnostic_SelectsNearestWalkablePoly_WhenFootXYInsideBbox`
  — given a `CellPhysics` with two walkable polys at different Z, the
  per-MISS aggregator picks the one closest by `dz`. Uses the same
  `IndoorWalkablePlaneTests` fixture style.
- `WalkMissDiagnostic_FallsBackToNearestPolyByDz_WhenFootXYOutsideAllBboxes`
  — given a foot XY outside every floor-poly bbox, the aggregator
  reports `containsFootXY=false` and returns the nearest by `dz` for
  context (or null if no walkable polys exist).

The actual log-format roundtrip (capturing stdout) is not unit-tested —
that's verified by the live capture per acceptance criterion below.

## Acceptance criteria

1. `dotnet build` green.
2. `dotnet test` green (existing tests untouched + 3 new tests).
3. A live capture at Holtburg with the env var on produces:
   - `[floor-polys]` lines for every loaded indoor cell.
   - At least one `[walk-miss]` line at the cottage doorway threshold.
   - At least one `[walk-miss]` line at an inn 2nd-floor edge.
   - Aggregated counts let us classify each MISS into H1/H2/H3 per the
     disambiguation matrix.
4. When `ACDREAM_PROBE_WALK_MISS` is unset, normal play produces zero
   `[walk-miss]` / `[floor-polys]` lines (zero-cost gate).

## Out of scope

- No fix to the underlying glitch — that's a follow-up session after the
  probe data lands.
- No changes to `TryFindIndoorWalkablePlane`, `FindWalkableSphere`,
  `BSPQuery.FindCollisions`, or any physics behavior.
- No retail cdb attach — that's the H3-only fallback path.
- No new DebugPanel checkbox — keep the probe lean.
- No removal of the existing `[indoor-bsp]` / `[indoor-walkable]` /
  `[cp-write]` probes — they're complementary.

## Risks

- **R1: `[floor-polys]` dump blows up the log.** Holtburg has hundreds
  of loaded cells. Per cell, typical walkable poly count is 1-4
  (cottages) up to ~10 (inn ground floor). Worst-case dump volume ~3 KB
  per cell × 200 cells = ~600 KB. Acceptable.
  *Mitigation:* none needed at this scale.

- **R2: Per-MISS line at 99.87% miss rate floods the log.** A 60-second
  capture at 30 Hz with one MISS per tick = ~1800 lines. At ~300 bytes
  each ≈ 540 KB. Acceptable. The user already produced 51k-line cp-write
  logs without issue.
  *Mitigation:* none needed.

- **R3: The probe doesn't disambiguate — the data falls into the
  "H1+H3 combination" cell.** Then we attach cdb to retail and gather
  ground truth. This is the planned fallback per CLAUDE.md "Retail
  debugger toolchain" section.
  *Mitigation:* the disambiguation matrix has an entry for this case.

- **R4: The probe finds the answer is *also* in a code path we haven't
  read yet** (e.g. `precipice_slide`, `cliff_slide`, `step_up_slide`).
  Then the next session's design exercises a new decomp read.
  *Mitigation:* unavoidable — the probe is the cheapest first move.

## Why this is the right next step

- **Falsifiable in one capture** — no iterative back-and-forth.
- **No behavior change** — can't regress the M1 demo paths (door open,
  pickup, NPC click).
- **Cheap implementation** — ~80 lines of code, 3 tests, one commit.
- **The previous session's premature design lesson (Bug A) explicitly
  flagged "probe-first, design-second" as the rule.** This is that rule
  applied.

## References

- `docs/research/2026-05-20-indoor-walking-bug-a-handoff.md` — the
  comprehensive previous-session handoff that motivated this spec.
- `docs/research/2026-05-21-indoor-walking-doorway-investigation-prompt.md`
  — the pickup brief.
- `docs/superpowers/specs/2026-05-20-indoor-bsp-worldorigin-fix-design.md`
  — Bug B (shipped), the immediately-prior spec in the series.
- Retail decomp anchors:
  - `acclient_2013_pseudo_c.txt:272717-272798` —
    `CTransition::check_other_cells` (H1 candidate).
  - `:323725-323939` — `BSPTREE::find_collisions` (H3 candidate).
  - `:323006-323028` — `CPolygon::walkable_hits_sphere` (H3 candidate).
- Code anchors:
  - `src/AcDream.Core/Physics/TransitionTypes.cs:1294` —
    `TryFindIndoorWalkablePlane`.
  - `src/AcDream.Core/Physics/TransitionTypes.cs:1538` — MISS log site.
  - `src/AcDream.Core/Physics/PhysicsDiagnostics.cs:223` —
    `ProbeCellCacheEnabled` (template for new flag).
  - `src/AcDream.Core/Physics/PhysicsDataCache.cs:182` — `[cell-cache]`
    pattern (template for `[floor-polys]`).