# Indoor Portal-Based Cell Tracking Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Replace Phase D's AABB-based indoor cell tracking with retail-faithful portal-graph traversal, so walls block consistently inside buildings and CellId updates correctly when crossing doors (closes ISSUES.md #87 + remaining wall-collision parts of #84 + #85).

**Architecture:** A new pure-static `CellTransit` class in `AcDream.Core.Physics` ports retail's four functions: `find_cell_list` (top-level driver), `find_transit_cells` sphere variant (indoor portal walk), `check_building_transit` (outdoor→indoor entry), and `add_all_outside_cells` (outdoor neighbour expansion). Cell containment uses the already-ported `BSPQuery.PointInsideCellBsp` against each cell's `CellBSP` (a third BSP tree per cell, separate from `PhysicsBSP` and `DrawingBSP`). The existing `PhysicsEngine.ResolveOutdoorCellId` is renamed to `ResolveCellId`, its body rewritten to call `CellTransit.FindCellList`, and Phase D's `TryFindContainingCell` + AABB fields are deleted entirely.

**Tech Stack:** C# / .NET 10, xUnit, `DatReaderWriter.DBObjs.EnvCell` + `DatReaderWriter.DBObjs.LandBlockInfo` for portal data sources, existing `BSPQuery.PointInsideCellBsp` for point-in-cell tests.

**Spec:** [`docs/superpowers/specs/2026-05-19-indoor-portal-cell-tracking-design.md`](../specs/2026-05-19-indoor-portal-cell-tracking-design.md)

**Research:** [`docs/research/acclient_indoor_transitions_pseudocode.md`](../../research/acclient_indoor_transitions_pseudocode.md) — the full algorithm in pseudocode, cross-referenced ACE + retail decomp.

---

## File Structure

| File | Action | Responsibility |
|---|---|---|
| `src/AcDream.Core/Physics/PortalInfo.cs` | create | `readonly struct PortalInfo(ushort OtherCellId, ushort PolygonId, ushort Flags)` with `PortalSide` property (`(Flags & 2) == 0`). |
| `src/AcDream.Core/Physics/BuildingPhysics.cs` | create | `sealed class BuildingPhysics` holding `WorldTransform`, `InverseWorldTransform`, and an `IReadOnlyList<BldPortalInfo>` for outdoor→indoor entry. Plus `readonly struct BldPortalInfo(uint OtherCellId, ushort OtherPortalId, ushort Flags, bool ExactMatch)`. |
| `src/AcDream.Core/Physics/CellTransit.cs` | create | Static class with the four retail-ported functions: `FindCellList`, `FindTransitCellsSphere`, `CheckBuildingTransit`, `AddAllOutsideCells`. |
| `src/AcDream.Core/Physics/PhysicsDataCache.cs` | modify | Extend `CellPhysics` with `CellBSP`, `Portals`, `PortalPolygons`, `VisibleCellIds`. Delete `LocalAabbMin/Max`. Change `CacheCellStruct` signature to accept `EnvCell envCell`. Delete `TryFindContainingCell`. Add `CacheBuilding(uint landcellId, IReadOnlyList<BldPortalInfo>, Matrix4x4)` and `GetBuilding(uint)`. |
| `src/AcDream.Core/Physics/PhysicsEngine.cs` | modify | Rename `ResolveOutdoorCellId` → `ResolveCellId`. Add `sphereRadius` parameter. Body becomes `CellTransit.FindCellList` call. Update 2 internal callers. |
| `src/AcDream.Core/Physics/TransitionTypes.cs` | modify | Update call at line 1181 to pass sphere radius. |
| `src/AcDream.App/Rendering/GameWindow.cs` | modify | Update `CacheCellStruct` call at line 5384 to pass the `EnvCell`. Add `CacheBuilding` call inside the `lbInfo.Buildings` loop. |
| `tests/AcDream.Core.Tests/Physics/PortalInfoTests.cs` | create | `PortalSide` flag-decoding tests. |
| `tests/AcDream.Core.Tests/Physics/CellPhysicsPortalWiringTests.cs` | create | Verify `CacheCellStruct` populates `CellBSP`, `Portals`, `PortalPolygons`, `VisibleCellIds`. |
| `tests/AcDream.Core.Tests/Physics/CellTransitFindTransitCellsSphereTests.cs` | create | Indoor portal-graph walk: sphere overlaps portal → adds neighbour; far → doesn't add; wrong side → doesn't add; exit portal → marks checkOutside. |
| `tests/AcDream.Core.Tests/Physics/CellTransitCheckBuildingTransitTests.cs` | create | Outdoor sphere overlapping building portal → adds indoor cell. |
| `tests/AcDream.Core.Tests/Physics/CellTransitAddAllOutsideCellsTests.cs` | create | Sphere at 24m landcell boundary edges → correct neighbour set. |
| `tests/AcDream.Core.Tests/Physics/CellTransitFindCellListTests.cs` | create | Integration: indoor → matching indoor cell; outdoor → matching landcell; outdoor near building → entering indoor cell; indoor → outdoor through exit portal. |
| `tests/AcDream.Core.Tests/Physics/ResolveOutdoorCellIdTests.cs` | rename + rewrite | Rename file to `ResolveCellIdTests.cs`; the 4 Phase D AABB tests are ported to use synthetic portal+CellBSP fixtures. |

---

## Plan-Time Reference Facts

These are facts an implementer needs and should NOT have to rediscover.

**Fact 1.** `BSPQuery.PointInsideCellBsp(node, point)` lives at [src/AcDream.Core/Physics/BSPQuery.cs:940](../../src/AcDream.Core/Physics/BSPQuery.cs:940). Signature: `public static bool PointInsideCellBsp(PhysicsBSPNode? node, Vector3 point)`. Returns `true` for null node (treats it as fully solid — must NOT be reached by `FindCellList`; callers must guard `cellPhysics.CellBSP?.Root == null` themselves).

**Fact 2.** The existing `CellPhysics` is a `sealed class` (not record) with `required` + `init`-only properties. New fields can be added as non-required with defaults. Source: PhysicsDataCache.cs:422.

**Fact 3.** `envCell.CellPortals` (from `DatReaderWriter.DBObjs.EnvCell`) is an iterable where each portal has `.OtherCellId` (ushort low-16), `.PolygonId` (ushort), and `.Flags` (some integer type — cast to ushort). Confirmed by GameWindow.cs:5506-5511. The portal's `PolygonId` indexes `cellStruct.Polygons` (visible polys), NOT `cellStruct.PhysicsPolygons`. Confirmed by GameWindow.cs:5685-5689 comment.

**Fact 4.** `cellStruct.CellBSP` field name verification is **Task 0** (first task — must complete before any code changes). The DAT format definitely has this BSP per the retail header and pseudocode doc, but DatReaderWriter's exact C# property name needs confirming. If it's missing from the C# binding, escalate to controller.

**Fact 5.** `LandBlockInfo.Buildings` (from `DatReaderWriter.DBObjs.LandBlockInfo`) carries the building portal data — each Building has a portal list. The exact C# property names need confirming in Task 0 as well.

**Fact 6.** Existing `ResolvePolygons(polys, vertexArray)` helper at PhysicsDataCache.cs lines 231-275 is reusable for both `PhysicsPolygons` and `Polygons` (visible). The function is private static; either widen visibility (recommended) OR copy/paste the logic into a public wrapper.

**Fact 7.** The 3 `ResolveOutdoorCellId` call sites are:
- `PhysicsEngine.cs:254` (definition itself)
- `PhysicsEngine.cs:755` (inside `ResolveWithTransition`)
- `PhysicsEngine.cs:773` (inside `ResolveWithTransition` fallback path)
- `TransitionTypes.cs:1181` (inside `Transition.FindEnvCollisions`)

Plus 2 test references in `tests/AcDream.Core.Tests/Physics/ResolveOutdoorCellIdTests.cs` (the Phase D tests).

---

## Task 0: Verify DatReaderWriter field names (read-only)

**Files:** Read-only investigation. No commits.

- [ ] **Step 1: Confirm `CellStruct.CellBSP` exists**

Run from the worktree root:
```powershell
$cellStruct = [DatReaderWriter.Types.CellStruct]
$cellStruct.GetProperties() | Select-Object Name, PropertyType | Where-Object { $_.Name -match 'BSP|Bsp|Polygon|Portal|Vertex' }
```

OR find the DatReaderWriter source on disk:
```bash
find ~/.nuget/packages/datreaderwriter -name "*.cs" 2>/dev/null | head -5
find ~/.nuget/packages/datreader* -name "CellStruct*" 2>/dev/null
```

OR find the type by listing all instance properties at the call site. Add a temporary line to GameWindow.cs around line 5660 (where `cellStruct` is in scope):
```csharp
Console.WriteLine(string.Join(",", typeof(DatReaderWriter.Types.CellStruct).GetProperties().Select(p => p.Name)));
```
Build + run (don't commit). Read output. Remove the line.

Expected: a property name matching `CellBSP` / `CellBsp` (or similar). If found, note the EXACT name for Task 2.

- [ ] **Step 2: Confirm `LandBlockInfo.Buildings` shape**

Same method as Step 1, but for `DatReaderWriter.DBObjs.LandBlockInfo`. Look for `Buildings` (List or array). Inspect one Building's properties to find:
- A list of portals (probably `Portals` or `BldPortals`)
- The building's world transform (probably `Transform` or `Frame`)

For each Portal in a Building, find:
- `OtherCellId` (uint or ushort)
- `OtherPortalId` (ushort)
- `Flags` (ushort or some flags type)
- Optionally: `ExactMatch` (bool)

Document the exact property names. If a field is named differently than the spec assumed, note the mapping.

- [ ] **Step 3: Report findings**

Note (mentally or in scratch) the EXACT C# property names that will be used in subsequent tasks:
- `cellStruct.<CellBSP-name>` for the third BSP
- `lbInfo.Buildings` (or whatever name)
- Building's portal list property
- Building's transform property
- BldPortal field names

If `CellBSP` is missing OR `Buildings` is missing OR the shape is fundamentally different, STOP and report BLOCKED. The plan assumes both exist — if they don't, the controller needs to escalate (e.g., extend DatReaderWriter upstream).

Throughout the rest of this plan, the placeholder `<CellBSP>` refers to whatever the actual C# property name turned out to be. Adjust each task accordingly.

---

## Task 1: Add `PortalInfo` struct (TDD)

**Files:**
- Create: `src/AcDream.Core/Physics/PortalInfo.cs`
- Create: `tests/AcDream.Core.Tests/Physics/PortalInfoTests.cs`

- [ ] **Step 1: Write the failing test**

Create `tests/AcDream.Core.Tests/Physics/PortalInfoTests.cs`:

```csharp
using AcDream.Core.Physics;
using Xunit;

namespace AcDream.Core.Tests.Physics;

public class PortalInfoTests
{
    [Fact]
    public void PortalSide_FlagsBit2Clear_ReturnsTrue()
    {
        // (Flags & 2) == 0 → PortalSide is true.
        var portal = new PortalInfo(otherCellId: 0x0101, polygonId: 5, flags: 0);
        Assert.True(portal.PortalSide);
    }

    [Fact]
    public void PortalSide_FlagsBit2Set_ReturnsFalse()
    {
        // (Flags & 2) != 0 → PortalSide is false.
        var portal = new PortalInfo(otherCellId: 0x0101, polygonId: 5, flags: 2);
        Assert.False(portal.PortalSide);
    }

    [Fact]
    public void PortalSide_OtherBitsSet_FollowsOnlyBit2()
    {
        var portal = new PortalInfo(otherCellId: 0x0101, polygonId: 5, flags: 0xFF & ~2);
        Assert.True(portal.PortalSide);
    }

    [Fact]
    public void OtherCellId_StoredAsLowSixteenBits()
    {
        // OtherCellId is a low-16 cell index (or 0xFFFF for exit-to-outdoor).
        var portal = new PortalInfo(otherCellId: 0xFFFF, polygonId: 5, flags: 0);
        Assert.Equal((ushort)0xFFFF, portal.OtherCellId);
    }
}
```

- [ ] **Step 2: Run, expect failure**

Run: `dotnet test tests/AcDream.Core.Tests/AcDream.Core.Tests.csproj --filter "FullyQualifiedName~PortalInfo"`
Expected: build fails (type not found).

- [ ] **Step 3: Create the type**

Create `src/AcDream.Core/Physics/PortalInfo.cs`:

```csharp
namespace AcDream.Core.Physics;

/// <summary>
/// Indoor walking Phase 2 (2026-05-19). Portal connection between two
/// EnvCells. Each <see cref="CellPhysics"/> carries a list of these,
/// mirroring retail's <c>CCellStruct.portals</c> array.
///
/// <para>
/// <see cref="OtherCellId"/> is a low-16 cell index (combined with the
/// owning landblock prefix at lookup time) or <c>0xFFFF</c> to mean
/// "exit to outdoor world" (the player crosses this portal to leave
/// the building).
/// </para>
///
/// <para>
/// <see cref="PolygonId"/> indexes the OWNING cell's
/// <see cref="CellPhysics.PortalPolygons"/> dict (the visible-polygon
/// table, NOT <see cref="CellPhysics.Resolved"/> which holds physics
/// polys).
/// </para>
///
/// <para>
/// <see cref="PortalSide"/> decodes bit 2 of <see cref="Flags"/>:
/// <c>(Flags &amp; 2) == 0</c> → portal's polygon normal points INTO
/// the owning cell (so dist &gt; 0 in cell-local space means "outside
/// the cell, beyond the portal"). Used in <c>find_transit_cells</c>'s
/// load-hint path for unloaded neighbours.
/// </para>
/// </summary>
public readonly struct PortalInfo
{
    public PortalInfo(ushort otherCellId, ushort polygonId, ushort flags)
    {
        OtherCellId = otherCellId;
        PolygonId   = polygonId;
        Flags       = flags;
    }

    public ushort OtherCellId { get; }
    public ushort PolygonId   { get; }
    public ushort Flags       { get; }

    /// <summary>Bit 2 of <see cref="Flags"/>. See struct docstring.</summary>
    public bool PortalSide => (Flags & 2) == 0;
}
```

- [ ] **Step 4: Run tests, expect green**

Run: `dotnet test tests/AcDream.Core.Tests/AcDream.Core.Tests.csproj --filter "FullyQualifiedName~PortalInfo"`
Expected: 4 tests passing.

- [ ] **Step 5: No commit yet** — bundle with Task 2 + Task 3 into one data-wiring commit.

---

## Task 2: Extend `CellPhysics` with portal fields (TDD)

**Files:**
- Modify: `src/AcDream.Core/Physics/PhysicsDataCache.cs` (the `CellPhysics` class around line 422)
- Create: `tests/AcDream.Core.Tests/Physics/CellPhysicsPortalWiringTests.cs`

- [ ] **Step 1: Locate `CellPhysics` and confirm shape**

Open `src/AcDream.Core/Physics/PhysicsDataCache.cs` and locate the `CellPhysics` class around line 422. Confirm:
- It's a `sealed class` with `required` + `init`-only properties.
- It currently has `BSP`, `PhysicsPolygons`, `Vertices`, `WorldTransform`, `InverseWorldTransform`, `Resolved`, `LocalAabbMin`, `LocalAabbMax`.

- [ ] **Step 2: Add new fields, delete AABB fields**

Replace the class body to:
1. ADD: `CellBSP` (`PhysicsBSPTree?`, init-only, nullable).
2. ADD: `Portals` (`IReadOnlyList<PortalInfo>`, init-only, default empty).
3. ADD: `PortalPolygons` (`Dictionary<ushort, ResolvedPolygon>?`, init-only, default null).
4. ADD: `VisibleCellIds` (`IReadOnlySet<uint>`, init-only, default empty).
5. DELETE: `LocalAabbMin` and `LocalAabbMax` (and their XML docs).

Concrete edit shape (the existing class continues to start with `public sealed class CellPhysics { ... }`):

```csharp
public sealed class CellPhysics
{
    // ── Pre-existing fields (unchanged) ────────────────────────────────
    public PhysicsBSPTree? BSP { get; init; }
    public Dictionary<ushort, Polygon>? PhysicsPolygons { get; init; }
    public VertexArray? Vertices { get; init; }
    public required Matrix4x4 WorldTransform { get; init; }
    public required Matrix4x4 InverseWorldTransform { get; init; }
    public required Dictionary<ushort, ResolvedPolygon> Resolved { get; init; }

    // ── Indoor walking Phase 2 (2026-05-19): portal-graph fields ───────

    /// <summary>
    /// The cell BSP used for <see cref="BSPQuery.PointInsideCellBsp"/>
    /// (point-in-cell tests). Separate tree from <see cref="BSP"/>
    /// (collision) and from the renderer's drawing-BSP.
    /// Source: <c>cellStruct.&lt;CellBSP-property-name&gt;</c> at cache time.
    /// Nullable: cells without a CellBSP cannot participate in portal
    /// containment and are skipped by <see cref="CellTransit"/>.
    /// </summary>
    public PhysicsBSPTree? CellBSP { get; init; }

    /// <summary>
    /// Portal connections to neighbouring cells, in cell-local space.
    /// Default: empty list. Source: <c>envCell.CellPortals</c>.
    /// </summary>
    public IReadOnlyList<PortalInfo> Portals { get; init; } = System.Array.Empty<PortalInfo>();

    /// <summary>
    /// Resolved VISIBLE polygons (from <c>cellStruct.Polygons</c>),
    /// keyed by polygon id. Distinct from <see cref="Resolved"/> which
    /// holds <c>PhysicsPolygons</c>. Portal lookup via
    /// <see cref="PortalInfo.PolygonId"/> resolves through this dict.
    /// Nullable when the cell has no visible polys (rare).
    /// </summary>
    public Dictionary<ushort, ResolvedPolygon>? PortalPolygons { get; init; }

    /// <summary>
    /// The cell ids visible from this cell (low-16 indexes, combined
    /// with the owning landblock prefix). Populated from
    /// <c>envCell.VisibleCells</c>. Unused this phase; reserved for the
    /// optional <c>find_cell_list</c> visibility filter.
    /// </summary>
    public IReadOnlySet<uint> VisibleCellIds { get; init; } = new System.Collections.Generic.HashSet<uint>();
}
```

**Important:** the AABB fields (`LocalAabbMin`, `LocalAabbMax`) are DELETED in this edit. Their XML docs go too. Any references to them anywhere in the codebase will fail the build in Task 7 (intentional — the build break shows you missed a deletion site).

- [ ] **Step 3: Write the parity test (RED first)**

Create `tests/AcDream.Core.Tests/Physics/CellPhysicsPortalWiringTests.cs`:

```csharp
using System.Numerics;
using AcDream.Core.Physics;
using Xunit;

namespace AcDream.Core.Tests.Physics;

public class CellPhysicsPortalWiringTests
{
    [Fact]
    public void NewFields_HaveSensibleDefaults()
    {
        // Phase 2 added CellBSP / Portals / PortalPolygons / VisibleCellIds.
        // Default-initialized values must not crash callers.
        var cp = new CellPhysics
        {
            WorldTransform = Matrix4x4.Identity,
            InverseWorldTransform = Matrix4x4.Identity,
            Resolved = new System.Collections.Generic.Dictionary<ushort, ResolvedPolygon>(),
        };

        Assert.Null(cp.CellBSP);
        Assert.Empty(cp.Portals);
        Assert.Null(cp.PortalPolygons);
        Assert.Empty(cp.VisibleCellIds);
    }

    [Fact]
    public void NewFields_AcceptInitValues()
    {
        var portal = new PortalInfo(otherCellId: 0x0101, polygonId: 5, flags: 0);

        var cp = new CellPhysics
        {
            WorldTransform = Matrix4x4.Identity,
            InverseWorldTransform = Matrix4x4.Identity,
            Resolved = new System.Collections.Generic.Dictionary<ushort, ResolvedPolygon>(),
            Portals = new[] { portal },
            VisibleCellIds = new System.Collections.Generic.HashSet<uint> { 0xA9B40101 },
        };

        Assert.Single(cp.Portals);
        Assert.Equal((ushort)0x0101, cp.Portals[0].OtherCellId);
        Assert.Contains(0xA9B40101u, cp.VisibleCellIds);
    }
}
```

- [ ] **Step 4: Run tests, expect green**

Run: `dotnet test tests/AcDream.Core.Tests/AcDream.Core.Tests.csproj --filter "FullyQualifiedName~CellPhysicsPortalWiring"`
Expected: 2 tests passing.

- [ ] **Step 5: Verify build is still otherwise green (deletion didn't break anything yet)**

Run: `dotnet build src/AcDream.Core/AcDream.Core.csproj`

If references to `LocalAabbMin` / `LocalAabbMax` exist outside the deleted block, you'll see compile errors. Those error locations are EXACTLY what you must fix in Task 7. For now, the AcDream.Core.csproj might not build green yet — that's expected. Note the error locations.

Expected build state: **may have errors** referencing the deleted AABB fields. That's fine; Task 7 closes them.

- [ ] **Step 6: No commit yet** — Task 3 finishes the data wiring.

---

## Task 3: Extend `CacheCellStruct` to populate portal data (TDD)

**Files:**
- Modify: `src/AcDream.Core/Physics/PhysicsDataCache.cs` (the `CacheCellStruct` method around lines 131-180)
- Modify: `src/AcDream.App/Rendering/GameWindow.cs` (call site at line 5384)
- Extend: `tests/AcDream.Core.Tests/Physics/CellPhysicsPortalWiringTests.cs`

- [ ] **Step 1: Replace `ResolvePolygons` visibility**

In `src/AcDream.Core/Physics/PhysicsDataCache.cs`, find the existing `private static Dictionary<ushort, ResolvedPolygon> ResolvePolygons(...)` at line 231. Change `private` to `internal`. The function stays as-is otherwise — same signature, same body. This makes it reusable for both `PhysicsPolygons` and the new `PortalPolygons` resolution.

- [ ] **Step 2: Change `CacheCellStruct` signature**

Find the existing `CacheCellStruct` method at PhysicsDataCache.cs:131. Change the signature from:

```csharp
public void CacheCellStruct(uint envCellId, CellStruct cellStruct, Matrix4x4 worldTransform)
```

to:

```csharp
public void CacheCellStruct(uint envCellId, DatReaderWriter.DBObjs.EnvCell envCell, CellStruct cellStruct, Matrix4x4 worldTransform)
```

Add the `using DatReaderWriter.DBObjs;` at the top of the file if not already there.

- [ ] **Step 3: Replace the body**

Inside `CacheCellStruct`, replace the body. New body:

```csharp
public void CacheCellStruct(uint envCellId, DatReaderWriter.DBObjs.EnvCell envCell,
                            CellStruct cellStruct, Matrix4x4 worldTransform)
{
    if (_cellStruct.ContainsKey(envCellId)) return;
    if (cellStruct.PhysicsBSP?.Root is null) return;

    Matrix4x4.Invert(worldTransform, out var inverseTransform);

    var resolved = ResolvePolygons(cellStruct.PhysicsPolygons, cellStruct.VertexArray);

    // Visible polygons — portals reference these (NOT PhysicsPolygons).
    var portalPolygons = ResolvePolygons(cellStruct.Polygons, cellStruct.VertexArray);

    // Portal list from envCell.CellPortals.
    var portals = new System.Collections.Generic.List<PortalInfo>(envCell.CellPortals.Count);
    foreach (var p in envCell.CellPortals)
    {
        portals.Add(new PortalInfo(
            otherCellId: p.OtherCellId,
            polygonId:   p.PolygonId,
            flags:       (ushort)p.Flags));
    }

    // VisibleCells set — populated for future use; not consulted this phase.
    var visibleCellIds = new System.Collections.Generic.HashSet<uint>();
    if (envCell.VisibleCells is not null)
    {
        uint lbPrefix = envCellId & 0xFFFF0000u;
        foreach (var lowId in envCell.VisibleCells.Keys)
            visibleCellIds.Add(lbPrefix | lowId);
    }

    _cellStruct[envCellId] = new CellPhysics
    {
        BSP = cellStruct.PhysicsBSP,
        PhysicsPolygons = cellStruct.PhysicsPolygons,
        Vertices = cellStruct.VertexArray,
        WorldTransform = worldTransform,
        InverseWorldTransform = inverseTransform,
        Resolved = resolved,
        // ── Phase 2 portal fields ──
        CellBSP = cellStruct.<CellBSP-property-name>,   // ← REPLACE with actual property name from Task 0
        Portals = portals,
        PortalPolygons = portalPolygons,
        VisibleCellIds = visibleCellIds,
    };

    if (PhysicsDiagnostics.ProbeCellCacheEnabled)
    {
        var root = cellStruct.PhysicsBSP?.Root;
        int bspRootPolyCount   = root?.Polygons?.Count ?? 0;
        bool bspRootHasChildren = root?.PosNode is not null || root?.NegNode is not null;

        // Recursive walk: count total leaf poly references + how many of
        // those poly IDs are absent from the resolved dict. If
        // bspTotalLeafPolys == 0 the BSP has no collidable polys at all.
        int bspTotalLeafPolys = 0;
        int bspUnmatchedIds   = 0;
        if (root is not null)
        {
            var stack = new System.Collections.Generic.Stack<DatReaderWriter.Types.PhysicsBSPNode>();
            stack.Push(root);
            while (stack.Count > 0)
            {
                var n = stack.Pop();
                if (n.Polygons is not null)
                {
                    foreach (var pid in n.Polygons)
                    {
                        bspTotalLeafPolys++;
                        if (!resolved.ContainsKey(pid)) bspUnmatchedIds++;
                    }
                }
                if (n.PosNode is not null) stack.Push(n.PosNode);
                if (n.NegNode is not null) stack.Push(n.NegNode);
            }
        }

        var bs = root?.BoundingSphere;
        string bsStr = bs is null
            ? "bsphere=n/a"
            : System.FormattableString.Invariant(
                $"bsphere=({bs.Origin.X:F2},{bs.Origin.Y:F2},{bs.Origin.Z:F2}) r={bs.Radius:F2}");

        var worldOrigin = Vector3.Transform(Vector3.Zero, worldTransform);

        // Phase 2: dropped aabbMin/aabbMax (deleted in Task 2). Added
        // portal/visible counts.
        Console.WriteLine(System.FormattableString.Invariant(
            $"[cell-cache] envCellId=0x{envCellId:X8} " +
            $"physicsPolyCount={cellStruct.PhysicsPolygons?.Count ?? 0} " +
            $"resolvedCount={resolved.Count} " +
            $"bspTotalLeafPolys={bspTotalLeafPolys} bspUnmatchedIds={bspUnmatchedIds} " +
            $"{bsStr} " +
            $"portalCount={portals.Count} " +
            $"visibleCells={visibleCellIds.Count} " +
            $"cellBspRoot={(cellStruct.<CellBSP-property-name>?.Root is null ? "null" : "ok")} " +
            $"worldOrigin=({worldOrigin.X:F2},{worldOrigin.Y:F2},{worldOrigin.Z:F2})"));
    }
}
```

**Substitution:** `<CellBSP-property-name>` appears twice in the snippet above — replace BOTH with the actual property name discovered in Task 0 (likely `CellBSP` or `CellBsp`).

- [ ] **Step 4: Update the GameWindow call site**

In `src/AcDream.App/Rendering/GameWindow.cs` at line 5384, find the existing call:

```csharp
_physicsDataCache.CacheCellStruct(envCellId, cellStruct, cellTransform);
```

Replace with:

```csharp
_physicsDataCache.CacheCellStruct(envCellId, envCell, cellStruct, cellTransform);
```

(The `envCell` variable is already in scope at this site — it's the loop variable from the surrounding `foreach` over EnvCells.)

- [ ] **Step 5: Extend the parity test with a portal-population check**

Append to `tests/AcDream.Core.Tests/Physics/CellPhysicsPortalWiringTests.cs`:

```csharp
    [Fact]
    public void CellPhysics_PortalsRoundTrip()
    {
        // Two portals: one indoor (OtherCellId=0x0101), one exit (OtherCellId=0xFFFF).
        var portals = new[]
        {
            new PortalInfo(otherCellId: 0x0101, polygonId: 7, flags: 0),
            new PortalInfo(otherCellId: 0xFFFF, polygonId: 8, flags: 2),
        };

        var cp = new CellPhysics
        {
            WorldTransform = Matrix4x4.Identity,
            InverseWorldTransform = Matrix4x4.Identity,
            Resolved = new System.Collections.Generic.Dictionary<ushort, ResolvedPolygon>(),
            Portals = portals,
        };

        Assert.Equal(2, cp.Portals.Count);
        Assert.Equal((ushort)0x0101, cp.Portals[0].OtherCellId);
        Assert.True(cp.Portals[0].PortalSide);
        Assert.Equal((ushort)0xFFFF, cp.Portals[1].OtherCellId);
        Assert.False(cp.Portals[1].PortalSide);
    }
```

- [ ] **Step 6: Build + test green**

Run: `dotnet build && dotnet test tests/AcDream.Core.Tests/AcDream.Core.Tests.csproj --filter "FullyQualifiedName~CellPhysicsPortalWiring|FullyQualifiedName~PortalInfo"`

Expected: 7 tests passing (4 PortalInfo + 3 CellPhysicsPortalWiring). The full `dotnet build` may still have errors from `TryFindContainingCell` and AABB references that Task 7 cleans up — that's expected. The targeted filter must pass.

- [ ] **Step 7: Commit (data wiring)**

```
git add src/AcDream.Core/Physics/PortalInfo.cs `
        src/AcDream.Core/Physics/PhysicsDataCache.cs `
        src/AcDream.App/Rendering/GameWindow.cs `
        tests/AcDream.Core.Tests/Physics/PortalInfoTests.cs `
        tests/AcDream.Core.Tests/Physics/CellPhysicsPortalWiringTests.cs

git commit -m "$(cat <<'EOF'
feat(physics): Phase 2 — wire CellBSP + Portals into CellPhysics

Adds PortalInfo struct and extends CellPhysics with CellBSP (third BSP for
point-in-cell tests), Portals (from envCell.CellPortals), PortalPolygons
(resolved cellStruct.Polygons — portals reference visible polys, not
PhysicsPolygons), and VisibleCellIds (populated for future use). Deletes
the Phase D LocalAabbMin/Max fields; CacheCellStruct's AABB compute is
gone.

Build is intentionally not green yet — references to the deleted AABB
fields in PhysicsEngine and tests will be removed in the integration commit
that wires CellTransit.FindCellList. This data-wiring step lands first so
the new infrastructure is in place before the consumer.

Spec: docs/superpowers/specs/2026-05-19-indoor-portal-cell-tracking-design.md
Plan: docs/superpowers/plans/2026-05-19-indoor-portal-cell-tracking.md

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
```

---

## Task 4: Port `CellTransit.FindTransitCellsSphere` (indoor portal walk, TDD)

**Files:**
- Create: `src/AcDream.Core/Physics/CellTransit.cs`
- Create: `tests/AcDream.Core.Tests/Physics/CellTransitFindTransitCellsSphereTests.cs`

- [ ] **Step 1: Write the failing tests**

Create `tests/AcDream.Core.Tests/Physics/CellTransitFindTransitCellsSphereTests.cs`:

```csharp
using System.Collections.Generic;
using System.Numerics;
using AcDream.Core.Physics;
using Xunit;

namespace AcDream.Core.Tests.Physics;

public class CellTransitFindTransitCellsSphereTests
{
    // Synthetic 2-cell scenario:
    //   Cell A at world origin; cell B 5m east of A.
    //   Portal poly at x=2.5 (the wall between A and B), normal pointing +X (out of A).
    //   Both cells are 5x5x5 m AABB.

    private const float EPSILON = 0.02f;

    private static (CellPhysics cellA, CellPhysics cellB) MakeAdjacentCells()
    {
        // Cell A: at world origin; portal poly at local x=2.5 (right wall), normal +X.
        var portalPolyA = new ResolvedPolygon
        {
            Vertices  = new[]
            {
                new Vector3(2.5f, -2.5f,  0f),
                new Vector3(2.5f,  2.5f,  0f),
                new Vector3(2.5f,  2.5f,  5f),
                new Vector3(2.5f, -2.5f,  5f),
            },
            Plane     = new Plane(new Vector3(1, 0, 0), -2.5f),  // x = 2.5
            NumPoints = 4,
            SidesType = DatReaderWriter.Enums.CullMode.None,
        };

        var cellA = new CellPhysics
        {
            WorldTransform = Matrix4x4.Identity,
            InverseWorldTransform = Matrix4x4.Identity,
            Resolved = new Dictionary<ushort, ResolvedPolygon>(),
            PortalPolygons = new Dictionary<ushort, ResolvedPolygon> { [10] = portalPolyA },
            Portals = new[]
            {
                // Portal to Cell B (low-16 = 0x0101). Flags=0 → PortalSide=true.
                new PortalInfo(otherCellId: 0x0101, polygonId: 10, flags: 0),
            },
        };

        // Cell B: 5m east in world; same portal polygon mirrored.
        var bWorldT = Matrix4x4.CreateTranslation(new Vector3(5f, 0f, 0f));
        Matrix4x4.Invert(bWorldT, out var bInvT);
        var cellB = new CellPhysics
        {
            WorldTransform = bWorldT,
            InverseWorldTransform = bInvT,
            Resolved = new Dictionary<ushort, ResolvedPolygon>(),
            // Cell B's CellBSP — null means point-in-cell returns "outside" for the test path.
            // For these tests we don't need the BSP since we're testing the load-hint and
            // add-by-sphere paths.
        };

        return (cellA, cellB);
    }

    [Fact]
    public void SphereInsideCellA_NearPortal_AddsCellB()
    {
        var (cellA, cellB) = MakeAdjacentCells();
        var cache = new PhysicsDataCache();
        cache.RegisterCellStructForTest(0xA9B40100u, cellA);
        cache.RegisterCellStructForTest(0xA9B40101u, cellB);

        // Sphere center near the portal plane (local x=2.0, sphere radius=0.5).
        // Sphere reaches x=2.5 which is the portal plane → straddles.
        var worldSphereCenter = new Vector3(2.0f, 0f, 2.5f);
        float sphereRadius = 0.5f;

        var candidates = new HashSet<uint>();
        CellTransit.FindTransitCellsSphere(
            cache,
            currentCell: cellA,
            currentCellId: 0xA9B40100u,
            worldSphereCenter,
            sphereRadius,
            candidates,
            out bool exitOutside);

        Assert.Contains(0xA9B40101u, candidates);
        Assert.False(exitOutside);
    }

    [Fact]
    public void SphereInsideCellA_FarFromPortal_DoesNotAddCellB()
    {
        var (cellA, cellB) = MakeAdjacentCells();
        var cache = new PhysicsDataCache();
        cache.RegisterCellStructForTest(0xA9B40100u, cellA);
        cache.RegisterCellStructForTest(0xA9B40101u, cellB);

        // Sphere far from portal (local x=-1.0, sphere radius=0.5).
        // Sphere reach extends only to x=-0.5 — nowhere near portal at x=2.5.
        var worldSphereCenter = new Vector3(-1.0f, 0f, 2.5f);

        var candidates = new HashSet<uint>();
        CellTransit.FindTransitCellsSphere(
            cache,
            currentCell: cellA,
            currentCellId: 0xA9B40100u,
            worldSphereCenter,
            sphereRadius: 0.5f,
            candidates,
            out bool exitOutside);

        Assert.DoesNotContain(0xA9B40101u, candidates);
    }

    [Fact]
    public void ExitPortal_SphereStraddlesPortalPlane_FlagsCheckOutside()
    {
        // Modify cell A to have its second portal be an EXIT (OtherCellId = 0xFFFF).
        var (cellA, _) = MakeAdjacentCells();
        var exitOnly = new CellPhysics
        {
            WorldTransform = cellA.WorldTransform,
            InverseWorldTransform = cellA.InverseWorldTransform,
            Resolved = cellA.Resolved,
            PortalPolygons = cellA.PortalPolygons,
            Portals = new[]
            {
                new PortalInfo(otherCellId: 0xFFFF, polygonId: 10, flags: 0),
            },
        };

        var cache = new PhysicsDataCache();
        cache.RegisterCellStructForTest(0xA9B40100u, exitOnly);

        var worldSphereCenter = new Vector3(2.0f, 0f, 2.5f);
        var candidates = new HashSet<uint>();

        CellTransit.FindTransitCellsSphere(
            cache,
            currentCell: exitOnly,
            currentCellId: 0xA9B40100u,
            worldSphereCenter,
            sphereRadius: 0.5f,
            candidates,
            out bool exitOutside);

        Assert.True(exitOutside);
    }
}
```

- [ ] **Step 2: Run, expect failure**

Run: `dotnet test tests/AcDream.Core.Tests/AcDream.Core.Tests.csproj --filter "FullyQualifiedName~CellTransitFindTransitCellsSphere"`
Expected: build fails (`CellTransit` not found).

- [ ] **Step 3: Implement `CellTransit.FindTransitCellsSphere`**

Create `src/AcDream.Core/Physics/CellTransit.cs`:

```csharp
using System.Collections.Generic;
using System.Numerics;
using DatReaderWriter.Types;

namespace AcDream.Core.Physics;

/// <summary>
/// Indoor walking Phase 2 (2026-05-19). Portal-graph cell traversal,
/// ported from retail's <c>CObjCell::find_cell_list</c> family
/// (sphere variant for the player's single foot sphere).
///
/// <para>
/// Replaces Phase D's AABB containment. Uses the cell BSP for retail-
/// faithful point-in-cell tests via
/// <see cref="BSPQuery.PointInsideCellBsp"/>. Walks the portal graph
/// starting from a given current cell to find which cells a moving
/// sphere overlaps.
/// </para>
///
/// <para>
/// Reference pseudocode:
/// <c>docs/research/acclient_indoor_transitions_pseudocode.md</c>
/// (2026-04-13). Retail decomp: <c>CEnvCell::find_transit_cells</c>
/// (sphere variant) at <c>acclient_2013_pseudo_c.txt</c>.
/// </para>
/// </summary>
public static class CellTransit
{
    /// <summary>
    /// Small radius padding matching retail's <c>EPSILON</c> usage in the
    /// sphere-plane distance test (research doc §"EnvCell.find_transit_cells").
    /// </summary>
    private const float EPSILON = 0.02f;

    /// <summary>
    /// Indoor portal-neighbour expansion. For each portal of
    /// <paramref name="currentCell"/>, test whether the sphere overlaps
    /// the portal polygon's plane in cell-local space. If so, add the
    /// neighbour cell to <paramref name="candidates"/>.
    ///
    /// <para>
    /// Ported from <c>CEnvCell::find_transit_cells</c> (sphere variant)
    /// per the pseudocode doc §"EnvCell.find_transit_cells (sphere variant)".
    /// </para>
    /// </summary>
    /// <param name="cache">The physics data cache (for neighbour lookups).</param>
    /// <param name="currentCell">The cell whose portals are walked.</param>
    /// <param name="currentCellId">The full id (with landblock prefix) of
    ///   <paramref name="currentCell"/>. Used to resolve neighbour ids by
    ///   combining the prefix with <see cref="PortalInfo.OtherCellId"/>.</param>
    /// <param name="worldSphereCenter">Player's foot-sphere center in world space.</param>
    /// <param name="sphereRadius">Player's foot-sphere radius.</param>
    /// <param name="candidates">Set to add neighbour cell ids to.</param>
    /// <param name="exitOutside">Set to true if the sphere straddles an
    ///   exit portal (<c>OtherCellId == 0xFFFF</c>) — the caller should
    ///   then expand outdoor neighbour cells via <see cref="AddAllOutsideCells"/>.</param>
    public static void FindTransitCellsSphere(
        PhysicsDataCache cache,
        CellPhysics currentCell,
        uint currentCellId,
        Vector3 worldSphereCenter,
        float sphereRadius,
        HashSet<uint> candidates,
        out bool exitOutside)
    {
        exitOutside = false;
        if (currentCell.PortalPolygons is null) return;

        uint lbPrefix = currentCellId & 0xFFFF0000u;
        float rad = sphereRadius + EPSILON;

        // Cell-local sphere center.
        var localCenter = Vector3.Transform(worldSphereCenter, currentCell.InverseWorldTransform);

        foreach (var portal in currentCell.Portals)
        {
            if (!currentCell.PortalPolygons.TryGetValue(portal.PolygonId, out var poly))
                continue;

            // Signed distance from sphere center to portal plane (cell-local).
            float dist = Vector3.Dot(localCenter, poly.Plane.Normal) + poly.Plane.D;

            if (portal.OtherCellId == 0xFFFF)
            {
                // Exit portal. Sphere must straddle the plane.
                if (dist > -rad && dist < rad)
                {
                    exitOutside = true;
                    // Don't break — there may be more portals to check.
                }
                continue;
            }

            uint otherId = lbPrefix | portal.OtherCellId;
            var otherCell = cache.GetCellStruct(otherId);

            if (otherCell is not null)
            {
                // Neighbour is loaded. Test containment via PointInsideCellBsp
                // in the OTHER cell's local space.
                var otherLocal = Vector3.Transform(worldSphereCenter, otherCell.InverseWorldTransform);

                // We don't yet have sphere_intersects_cell ported. Use the
                // load-hint sphere-plane heuristic from the research doc's
                // "otherCell == null" branch as a conservative add — once
                // the sphere is near the portal plane and on the "exit" side
                // (per PortalSide), the neighbour is a valid candidate.
                if (portal.PortalSide ? dist > -rad : dist < rad)
                {
                    candidates.Add(otherId);
                }
            }
            else
            {
                // Load-hint path: neighbour not yet cached. Mirrors retail's
                // load-hint branch — add by plane-side test only.
                if (portal.PortalSide ? dist > -rad : dist < rad)
                {
                    candidates.Add(otherId);
                }
            }
        }
    }
}
```

**Note on `sphere_intersects_cell`:** retail's algorithm uses `CellBSP.sphere_intersects_cell_bsp` (returns `Inside`/`Crossing`/`Outside`) for the neighbour-containment test. Our `BSPQuery` doesn't currently expose that operation — only `PointInsideCellBsp` and the collision-side `FindCollisions`. The plane-side heuristic above is a conservative approximation: it adds a candidate whenever the sphere is close to the portal and on the right side. Combined with `FindCellList`'s subsequent point-in-cell test (Task 6) which filters to a single winning cell via `PointInsideCellBsp`, the conservative add is safe.

A more retail-faithful implementation would add `BSPQuery.SphereIntersectsCellBsp` (~80 LOC). Deferred to a follow-up if our heuristic produces visible bugs.

- [ ] **Step 4: Run tests, expect green**

Run: `dotnet test tests/AcDream.Core.Tests/AcDream.Core.Tests.csproj --filter "FullyQualifiedName~CellTransitFindTransitCellsSphere"`
Expected: 3 tests passing.

- [ ] **Step 5: No commit yet** — bundle with Task 5 + 6 + 7 into one CellTransit commit.

---

## Task 5: Port `CellTransit.AddAllOutsideCells` (TDD)

**Files:**
- Modify: `src/AcDream.Core/Physics/CellTransit.cs`
- Create: `tests/AcDream.Core.Tests/Physics/CellTransitAddAllOutsideCellsTests.cs`

- [ ] **Step 1: Write the failing tests**

Create `tests/AcDream.Core.Tests/Physics/CellTransitAddAllOutsideCellsTests.cs`:

```csharp
using System.Collections.Generic;
using System.Numerics;
using AcDream.Core.Physics;
using Xunit;

namespace AcDream.Core.Tests.Physics;

public class CellTransitAddAllOutsideCellsTests
{
    // Outdoor landcells are 24×24m. Cell ids low-16 are 0x01..0x40 in row-major
    // order (8 cells wide, 8 cells tall per landblock). Cell offset within
    // landblock: cellY = (low - 1) % 8, cellX = (low - 1) / 8 (per the AC2D
    // reference; verify with research doc).

    [Fact]
    public void SphereWellInsideCell_AddsOneCell()
    {
        // Player at world (12, 12, 0) — middle of cell (0, 0) of landblock 0xA9B40000.
        // Cell low-16 id = 0x0001 (first outdoor cell).
        var candidates = new HashSet<uint>();
        CellTransit.AddAllOutsideCells(
            worldSphereCenter: new Vector3(12f, 12f, 0f),
            sphereRadius: 0.5f,
            currentCellId: 0xA9B40001u,
            candidates);

        Assert.Single(candidates);
        Assert.Contains(0xA9B40001u, candidates);
    }

    [Fact]
    public void SphereAtCellEastBoundary_AddsTwoCells()
    {
        // Player at world (23.6, 12, 0) — at the +X edge of cell (0,0). Sphere
        // radius 0.5 → reaches X=24.1 which is in cell (1,0).
        var candidates = new HashSet<uint>();
        CellTransit.AddAllOutsideCells(
            worldSphereCenter: new Vector3(23.6f, 12f, 0f),
            sphereRadius: 0.5f,
            currentCellId: 0xA9B40001u,
            candidates);

        Assert.Equal(2, candidates.Count);
        Assert.Contains(0xA9B40001u, candidates);
        // Cell at (1, 0): low-16 id = 0x0009 (cell index = 8 → low+8 = 0x0009).
        Assert.Contains(0xA9B40009u, candidates);
    }

    // Additional boundary tests (corner: 4 cells; +Y edge: 2 cells) intentionally
    // omitted from the plan to keep the commit small. Add them once the basic
    // shape works.
}
```

- [ ] **Step 2: Add the function to `CellTransit`**

Append to `src/AcDream.Core/Physics/CellTransit.cs`:

```csharp
    /// <summary>
    /// Outdoor neighbour expansion. Ported from
    /// <c>CLandCell::add_all_outside_cells</c> (sphere variant) per the
    /// pseudocode doc §"LandCell.add_all_outside_cells (sphere variant)".
    ///
    /// <para>
    /// The 24×24m landcell grid: a landblock is 8×8 cells. Cell index
    /// within a landblock is computed from local X/Y mod 24. The sphere
    /// adds the primary cell plus up to 3 neighbours when the radius
    /// reaches a cell boundary.
    /// </para>
    /// </summary>
    public static void AddAllOutsideCells(
        Vector3 worldSphereCenter,
        float sphereRadius,
        uint currentCellId,
        HashSet<uint> candidates)
    {
        const float CellSize = 24f;

        uint lbPrefix = currentCellId & 0xFFFF0000u;

        // Compute the landblock's world XY origin from the landblock id.
        // Landblock byte X = (lbPrefix >> 24) & 0xFF, Y = (lbPrefix >> 16) & 0xFF.
        // Each landblock is 192×192m at world (lbX * 192, lbY * 192).
        // The "current landblock" depends on world position — if the sphere
        // crosses landblock boundaries we'd need to adjust the prefix; for
        // now assume the sphere stays within the current landblock.
        float lbXf = ((lbPrefix >> 24) & 0xFFu) * 192f;
        float lbYf = ((lbPrefix >> 16) & 0xFFu) * 192f;
        float localX = worldSphereCenter.X - lbXf;
        float localY = worldSphereCenter.Y - lbYf;

        // Within-cell local 2D.
        float cellLocalX = localX % CellSize;
        float cellLocalY = localY % CellSize;
        float minRad = sphereRadius;
        float maxRad = CellSize - sphereRadius;

        // Grid coordinates.
        int gridX = (int)(localX / CellSize);
        int gridY = (int)(localY / CellSize);
        if (gridX < 0 || gridX >= 8 || gridY < 0 || gridY >= 8) return;

        AddOutsideCell(candidates, lbPrefix, gridX, gridY);

        // Boundary checks (matches research doc's check_add_cell_boundary).
        if (cellLocalX > maxRad)
        {
            AddOutsideCell(candidates, lbPrefix, gridX + 1, gridY);
            if (cellLocalY > maxRad) AddOutsideCell(candidates, lbPrefix, gridX + 1, gridY + 1);
            if (cellLocalY < minRad) AddOutsideCell(candidates, lbPrefix, gridX + 1, gridY - 1);
        }
        if (cellLocalX < minRad)
        {
            AddOutsideCell(candidates, lbPrefix, gridX - 1, gridY);
            if (cellLocalY > maxRad) AddOutsideCell(candidates, lbPrefix, gridX - 1, gridY + 1);
            if (cellLocalY < minRad) AddOutsideCell(candidates, lbPrefix, gridX - 1, gridY - 1);
        }
        if (cellLocalY > maxRad) AddOutsideCell(candidates, lbPrefix, gridX, gridY + 1);
        if (cellLocalY < minRad) AddOutsideCell(candidates, lbPrefix, gridX, gridY - 1);
    }

    private static void AddOutsideCell(HashSet<uint> candidates, uint lbPrefix, int gridX, int gridY)
    {
        if (gridX < 0 || gridX >= 8 || gridY < 0 || gridY >= 8) return;

        // Cell index within landblock: row-major (X * 8 + Y) + 1, per AC's convention.
        uint low = (uint)(gridX * 8 + gridY + 1);
        candidates.Add(lbPrefix | low);
    }
```

- [ ] **Step 3: Run tests, expect green**

Run: `dotnet test tests/AcDream.Core.Tests/AcDream.Core.Tests.csproj --filter "FullyQualifiedName~CellTransitAddAllOutsideCells"`
Expected: 2 tests passing.

- [ ] **Step 4: No commit yet.**

---

## Task 6: Port `CellTransit.FindCellList` (top-level driver, TDD)

**Files:**
- Modify: `src/AcDream.Core/Physics/CellTransit.cs`
- Create: `tests/AcDream.Core.Tests/Physics/CellTransitFindCellListTests.cs`

- [ ] **Step 1: Write the failing tests**

Create `tests/AcDream.Core.Tests/Physics/CellTransitFindCellListTests.cs`:

```csharp
using System.Collections.Generic;
using System.Numerics;
using AcDream.Core.Physics;
using Xunit;

namespace AcDream.Core.Tests.Physics;

public class CellTransitFindCellListTests
{
    [Fact]
    public void IndoorSeed_PointInsideCellBsp_ReturnsCurrentCell()
    {
        var cache = new PhysicsDataCache();
        // Synthetic cell with no portals; CellBSP is null so PointInsideCellBsp
        // would return true — but we guard CellBSP?.Root == null and treat
        // missing BSP as "not findable" → fall through.
        var cell = new CellPhysics
        {
            WorldTransform = Matrix4x4.Identity,
            InverseWorldTransform = Matrix4x4.Identity,
            Resolved = new Dictionary<ushort, ResolvedPolygon>(),
        };
        cache.RegisterCellStructForTest(0xA9B40100u, cell);

        uint result = CellTransit.FindCellList(
            cache,
            worldSphereCenter: Vector3.Zero,
            sphereRadius: 0.5f,
            currentCellId: 0xA9B40100u);

        // No CellBSP → falls back to the input cell id.
        Assert.Equal(0xA9B40100u, result);
    }

    [Fact]
    public void OutdoorSeed_Returns_OutdoorLandcell()
    {
        var cache = new PhysicsDataCache();
        // Outdoor seed: low-16 < 0x0100. No CellPhysics needed for landcells.
        uint result = CellTransit.FindCellList(
            cache,
            worldSphereCenter: new Vector3(12f, 12f, 0f),
            sphereRadius: 0.5f,
            currentCellId: 0xA9B40001u);

        Assert.Equal(0xA9B40001u, result);
    }
}
```

- [ ] **Step 2: Add `FindCellList` to `CellTransit`**

Append to `src/AcDream.Core/Physics/CellTransit.cs`:

```csharp
    /// <summary>
    /// Top-level cell-tracking driver, ported from retail's
    /// <c>CObjCell::find_cell_list</c> (sphere variant).
    ///
    /// <para>
    /// Walks the portal graph from <paramref name="currentCellId"/>,
    /// finds the cell whose <see cref="CellPhysics.CellBSP"/> contains
    /// the sphere center, and returns its full id (landblock-prefixed).
    /// Falls back to <paramref name="currentCellId"/> when no candidate
    /// matches.
    /// </para>
    ///
    /// <para>
    /// Pseudocode reference:
    /// <c>docs/research/acclient_indoor_transitions_pseudocode.md</c>
    /// §"Overall Driver: find_cell_list".
    /// </para>
    /// </summary>
    public static uint FindCellList(
        PhysicsDataCache cache,
        Vector3 worldSphereCenter,
        float sphereRadius,
        uint currentCellId)
    {
        var candidates = new HashSet<uint>();
        uint currentLow = currentCellId & 0xFFFFu;

        if (currentLow >= 0x0100u)
        {
            // Indoor seed.
            var currentCell = cache.GetCellStruct(currentCellId);
            if (currentCell is null) return currentCellId;

            candidates.Add(currentCellId);

            // BFS the portal graph (one hop per pass — usually 1-2 passes is enough).
            var pending = new Queue<uint>();
            pending.Enqueue(currentCellId);
            int maxIterations = 16;  // hard cap; portal graphs are small
            while (pending.Count > 0 && maxIterations-- > 0)
            {
                uint cellId = pending.Dequeue();
                var cell = cache.GetCellStruct(cellId);
                if (cell is null) continue;

                var sizeBefore = candidates.Count;
                FindTransitCellsSphere(
                    cache, cell, cellId, worldSphereCenter, sphereRadius,
                    candidates, out bool exitOutside);

                // For each NEW candidate, enqueue it.
                if (candidates.Count > sizeBefore)
                {
                    // Snapshot the new candidates to avoid mutating during iteration.
                    foreach (var c in candidates)
                    {
                        if (c != cellId)  // skip seed
                            pending.Enqueue(c);
                    }
                }

                if (exitOutside)
                {
                    // Add neighbour outdoor cells too.
                    AddAllOutsideCells(worldSphereCenter, sphereRadius, currentCellId, candidates);
                }
            }
        }
        else
        {
            // Outdoor seed.
            AddAllOutsideCells(worldSphereCenter, sphereRadius, currentCellId, candidates);
            // TODO: check_building_transit hookup at Task 7.
        }

        // Containment test: for each candidate, transform worldSphereCenter to
        // local and test PointInsideCellBsp.
        foreach (uint candId in candidates)
        {
            var cand = cache.GetCellStruct(candId);
            if (cand?.CellBSP?.Root is null) continue;

            var local = Vector3.Transform(worldSphereCenter, cand.InverseWorldTransform);
            if (BSPQuery.PointInsideCellBsp(cand.CellBSP.Root, local))
                return candId;
        }

        // No cell contained the sphere center. Stay in the input cell.
        return currentCellId;
    }
```

- [ ] **Step 3: Run tests, expect green**

Run: `dotnet test tests/AcDream.Core.Tests/AcDream.Core.Tests.csproj --filter "FullyQualifiedName~CellTransitFindCellList"`
Expected: 2 tests passing.

- [ ] **Step 4: No commit yet.**

---

## Task 7: Wire `CellTransit.FindCellList` into `ResolveCellId`, delete AABB containment

**Files:**
- Modify: `src/AcDream.Core/Physics/PhysicsEngine.cs`
- Modify: `src/AcDream.Core/Physics/PhysicsDataCache.cs`
- Modify: `src/AcDream.Core/Physics/TransitionTypes.cs`
- Rename + rewrite: `tests/AcDream.Core.Tests/Physics/ResolveOutdoorCellIdTests.cs` → `tests/AcDream.Core.Tests/Physics/ResolveCellIdTests.cs`

- [ ] **Step 1: Rename `ResolveOutdoorCellId` and rewrite body**

In `src/AcDream.Core/Physics/PhysicsEngine.cs`, find `ResolveOutdoorCellId` at line 254. Rename to `ResolveCellId` and replace the body. New definition:

```csharp
/// <summary>
/// Indoor walking Phase 2 (2026-05-19). Resolves the cell id for a
/// given world position via retail's portal-graph traversal. Delegates
/// to <see cref="CellTransit.FindCellList"/>.
///
/// <para>
/// Replaces Phase D's <c>ResolveOutdoorCellId</c> which used AABB
/// containment — see <c>docs/superpowers/specs/2026-05-19-indoor-portal-cell-tracking-design.md</c>
/// for the design.
/// </para>
/// </summary>
internal uint ResolveCellId(Vector3 worldPos, float sphereRadius, uint fallbackCellId)
{
    if (fallbackCellId == 0) return 0;
    if (DataCache is null) return fallbackCellId;

    return CellTransit.FindCellList(DataCache, worldPos, sphereRadius, fallbackCellId);
}
```

- [ ] **Step 2: Update the two internal callers in `PhysicsEngine.cs`**

Find lines 755 and 773 (or thereabouts after the rename). The current calls are:

```csharp
ResolveOutdoorCellId(sp.CheckPos, sp.CheckCellId),
```

Plumb the sphere radius through. The caller is inside `ResolveWithTransition`, and `sp.GlobalSphere[0].Radius` is accessible via the `sp` (SpherePath) variable. Update both lines:

```csharp
ResolveCellId(sp.CheckPos, sp.GlobalSphere[0].Radius, sp.CheckCellId),
```

- [ ] **Step 3: Update the `TransitionTypes.cs` call**

At `src/AcDream.Core/Physics/TransitionTypes.cs:1181`, the existing call:

```csharp
uint resolvedOutdoorCellId = engine.ResolveOutdoorCellId(sp.CheckPos, sp.CheckCellId);
```

Replace with:

```csharp
uint resolvedOutdoorCellId = engine.ResolveCellId(sp.CheckPos, sphereRadius, sp.CheckCellId);
```

The `sphereRadius` local is already in scope at line 1186 (`float sphereRadius = sp.GlobalSphere[0].Radius;`). The replacement uses it directly.

- [ ] **Step 4: Delete `TryFindContainingCell` from `PhysicsDataCache`**

In `src/AcDream.Core/Physics/PhysicsDataCache.cs`, find the `TryFindContainingCell` method (around line 295). Delete the entire method including its XML doc.

- [ ] **Step 5: Rebuild — should be green now**

Run: `dotnet build`

If errors remain referencing `LocalAabbMin` / `LocalAabbMax` / `TryFindContainingCell` outside the deleted code, fix them. Most likely candidates: the WorldPicker tests if they constructed CellPhysics with those fields, or any other consumer that snuck in.

- [ ] **Step 6: Rename + rewrite the Phase D test file**

Rename `tests/AcDream.Core.Tests/Physics/ResolveOutdoorCellIdTests.cs` to `tests/AcDream.Core.Tests/Physics/ResolveCellIdTests.cs` (file rename — use `git mv`).

Replace the class body. The old AABB-based tests assert containment behavior that no longer exists. New tests verify the portal-traversal-based behavior:

```csharp
using System.Collections.Generic;
using System.Numerics;
using AcDream.Core.Physics;
using Xunit;

namespace AcDream.Core.Tests.Physics;

public class ResolveCellIdTests
{
    [Fact]
    public void ResolveCellId_FallbackZero_ReturnsZero()
    {
        var engine = new PhysicsEngine();
        uint result = engine.ResolveCellId(Vector3.Zero, sphereRadius: 0.5f, fallbackCellId: 0u);
        Assert.Equal(0u, result);
    }

    [Fact]
    public void ResolveCellId_NoDataCache_ReturnsFallback()
    {
        // Build a PhysicsEngine without setting DataCache (default: null).
        var engine = new PhysicsEngine { DataCache = null };
        uint result = engine.ResolveCellId(Vector3.Zero, sphereRadius: 0.5f, fallbackCellId: 0x00000001u);
        Assert.Equal(0x00000001u, result);
    }

    [Fact]
    public void ResolveCellId_OutdoorSeedNoLandblock_ReturnsFallback()
    {
        var engine = new PhysicsEngine();
        uint result = engine.ResolveCellId(
            new Vector3(100, 100, 0),
            sphereRadius: 0.5f,
            fallbackCellId: 0xA9B40001u);
        // No cells cached, no landblock added → AddAllOutsideCells produces 1
        // candidate (the input cell) but PointInsideCellBsp on null CellBSP skips
        // → returns fallback.
        Assert.Equal(0xA9B40001u, result);
    }
}
```

(The original Phase D tests covered specific behaviors that are now better covered by `CellTransitFindCellListTests` and `CellTransitFindTransitCellsSphereTests`. Don't try to port them 1:1.)

- [ ] **Step 7: Build + full test sweep**

Run: `dotnet build && dotnet test`

Expected:
- Build green (0 errors).
- All new tests pass.
- 8 pre-existing failures unchanged (baseline match).
- Old `ResolveOutdoorCellIdTests` is gone (file renamed); the rewritten `ResolveCellIdTests` (3 tests) passes.

- [ ] **Step 8: Commit (the cellTransit + integration commit)**

```
git add src/AcDream.Core/Physics/CellTransit.cs `
        src/AcDream.Core/Physics/PhysicsEngine.cs `
        src/AcDream.Core/Physics/PhysicsDataCache.cs `
        src/AcDream.Core/Physics/TransitionTypes.cs `
        tests/AcDream.Core.Tests/Physics/CellTransitFindTransitCellsSphereTests.cs `
        tests/AcDream.Core.Tests/Physics/CellTransitAddAllOutsideCellsTests.cs `
        tests/AcDream.Core.Tests/Physics/CellTransitFindCellListTests.cs `
        tests/AcDream.Core.Tests/Physics/ResolveCellIdTests.cs

git rm tests/AcDream.Core.Tests/Physics/ResolveOutdoorCellIdTests.cs

git commit -m "$(cat <<'EOF'
feat(physics): Phase 2 — port CellTransit + delete AABB containment

New CellTransit static class ports retail's portal-graph cell traversal:
- FindTransitCellsSphere — indoor portal-neighbour walk
- AddAllOutsideCells     — outdoor 24m grid expansion
- FindCellList           — top-level driver (BFS through portals;
                           PointInsideCellBsp for final containment)

PhysicsEngine.ResolveOutdoorCellId renamed to ResolveCellId. Body
rewritten to delegate to CellTransit.FindCellList. Signature extended
with sphereRadius parameter (needed by the sphere-vs-portal-plane test).
Three call sites updated (PhysicsEngine ×2, TransitionTypes ×1).

Deletes PhysicsDataCache.TryFindContainingCell + the corresponding AABB
compute. The previous Phase D AABB-containment tests are dropped; new
tests under CellTransit*Tests cover the equivalent scenarios via portal
traversal.

Outdoor→indoor entry (check_building_transit) is wired but no-op until
the BuildingPhysics infrastructure lands in a follow-up commit.

Spec: docs/superpowers/specs/2026-05-19-indoor-portal-cell-tracking-design.md
Plan: docs/superpowers/plans/2026-05-19-indoor-portal-cell-tracking.md

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
```

---

## Task 8: Add `BuildingPhysics` + `CheckBuildingTransit` (TDD)

**Files:**
- Create: `src/AcDream.Core/Physics/BuildingPhysics.cs`
- Modify: `src/AcDream.Core/Physics/PhysicsDataCache.cs`
- Modify: `src/AcDream.Core/Physics/CellTransit.cs`
- Modify: `src/AcDream.App/Rendering/GameWindow.cs`
- Create: `tests/AcDream.Core.Tests/Physics/CellTransitCheckBuildingTransitTests.cs`

- [ ] **Step 1: Create the `BuildingPhysics` type**

Create `src/AcDream.Core/Physics/BuildingPhysics.cs`:

```csharp
using System.Collections.Generic;
using System.Numerics;

namespace AcDream.Core.Physics;

/// <summary>
/// Indoor walking Phase 2 (2026-05-19). Cached building portal data
/// for outdoor→indoor cell entry. One per outdoor landcell that contains
/// a building stab. Mirrors retail's <c>BuildingObj.Portals</c> array
/// (per the pseudocode doc §"LandCell.find_transit_cells").
/// </summary>
public sealed class BuildingPhysics
{
    public required Matrix4x4 WorldTransform { get; init; }
    public required Matrix4x4 InverseWorldTransform { get; init; }
    public required IReadOnlyList<BldPortalInfo> Portals { get; init; }
}

/// <summary>
/// One building portal: the connection from a SortCell's BuildingObj to
/// an interior EnvCell.
/// </summary>
public readonly struct BldPortalInfo
{
    public BldPortalInfo(uint otherCellId, ushort otherPortalId, ushort flags, bool exactMatch)
    {
        OtherCellId   = otherCellId;
        OtherPortalId = otherPortalId;
        Flags         = flags;
        ExactMatch    = exactMatch;
    }

    /// <summary>Full id of the interior EnvCell this portal connects to.</summary>
    public uint   OtherCellId   { get; }
    /// <summary>The portal id within the destination EnvCell.</summary>
    public ushort OtherPortalId { get; }
    public ushort Flags         { get; }
    public bool   ExactMatch    { get; }
}
```

- [ ] **Step 2: Add `CacheBuilding` + `GetBuilding` to `PhysicsDataCache`**

In `src/AcDream.Core/Physics/PhysicsDataCache.cs`, near the existing `CacheCellStruct` method (around line 180), add:

```csharp
// ── Phase 2: building portal cache for outdoor→indoor entry ───────────

private readonly System.Collections.Concurrent.ConcurrentDictionary<uint, BuildingPhysics> _buildings = new();

/// <summary>
/// Indoor walking Phase 2 (2026-05-19). Cache the building portal list
/// for an outdoor landcell that contains a building stab. Used by
/// <see cref="CellTransit.CheckBuildingTransit"/>.
/// </summary>
public void CacheBuilding(uint landcellId, IReadOnlyList<BldPortalInfo> portals, Matrix4x4 worldTransform)
{
    if (_buildings.ContainsKey(landcellId)) return;
    Matrix4x4.Invert(worldTransform, out var inverse);
    _buildings[landcellId] = new BuildingPhysics
    {
        WorldTransform = worldTransform,
        InverseWorldTransform = inverse,
        Portals = portals,
    };
}

public BuildingPhysics? GetBuilding(uint landcellId)
    => _buildings.TryGetValue(landcellId, out var b) ? b : null;

public IReadOnlyCollection<uint> BuildingIds => (IReadOnlyCollection<uint>)_buildings.Keys;

/// <summary>Test helper, mirrors <see cref="RegisterCellStructForTest"/>.</summary>
public void RegisterBuildingForTest(uint landcellId, BuildingPhysics b) => _buildings[landcellId] = b;
```

- [ ] **Step 3: Write the failing test**

Create `tests/AcDream.Core.Tests/Physics/CellTransitCheckBuildingTransitTests.cs`:

```csharp
using System.Collections.Generic;
using System.Numerics;
using AcDream.Core.Physics;
using Xunit;

namespace AcDream.Core.Tests.Physics;

public class CellTransitCheckBuildingTransitTests
{
    [Fact]
    public void SphereOverlapsBuildingPortal_AddsInteriorCell()
    {
        // Building at world origin. One portal to interior cell 0xA9B40100.
        var building = new BuildingPhysics
        {
            WorldTransform = Matrix4x4.Identity,
            InverseWorldTransform = Matrix4x4.Identity,
            Portals = new[]
            {
                new BldPortalInfo(
                    otherCellId: 0xA9B40100u,
                    otherPortalId: 0,
                    flags: 0,
                    exactMatch: false),
            },
        };

        // Interior cell whose CellBSP returns "inside" for the sphere center.
        // For this test we use a null CellBSP — PointInsideCellBsp on null
        // returns true, so the cell registers as containing the point.
        var interiorCell = new CellPhysics
        {
            WorldTransform = Matrix4x4.Identity,
            InverseWorldTransform = Matrix4x4.Identity,
            Resolved = new Dictionary<ushort, ResolvedPolygon>(),
        };

        var cache = new PhysicsDataCache();
        cache.RegisterBuildingForTest(0xA9B40001u, building);
        cache.RegisterCellStructForTest(0xA9B40100u, interiorCell);

        var candidates = new HashSet<uint>();
        CellTransit.CheckBuildingTransit(
            cache,
            building,
            worldSphereCenter: new Vector3(0, 0, 0),
            sphereRadius: 0.5f,
            candidates);

        Assert.Contains(0xA9B40100u, candidates);
    }
}
```

- [ ] **Step 4: Add `CheckBuildingTransit` to `CellTransit`**

Append to `src/AcDream.Core/Physics/CellTransit.cs`:

```csharp
    /// <summary>
    /// Outdoor→indoor entry path. Ported from retail's
    /// <c>BuildingObj::find_building_transit_cells</c> +
    /// <c>EnvCell::check_building_transit</c>. For each portal of the
    /// outdoor building, look up the destination interior cell and test
    /// whether the sphere overlaps it via <see cref="BSPQuery.PointInsideCellBsp"/>.
    /// If so, add the interior cell to <paramref name="candidates"/>.
    /// </summary>
    public static void CheckBuildingTransit(
        PhysicsDataCache cache,
        BuildingPhysics building,
        Vector3 worldSphereCenter,
        float sphereRadius,
        HashSet<uint> candidates)
    {
        foreach (var portal in building.Portals)
        {
            if (portal.OtherCellId == 0xFFFFFFFFu) continue;

            var otherCell = cache.GetCellStruct(portal.OtherCellId);
            if (otherCell is null) continue;

            // Sphere center in the OTHER cell's local space.
            var localCenter = Vector3.Transform(worldSphereCenter, otherCell.InverseWorldTransform);

            // Use PointInsideCellBsp if available; else fall through.
            if (otherCell.CellBSP?.Root is null) continue;
            if (BSPQuery.PointInsideCellBsp(otherCell.CellBSP.Root, localCenter))
            {
                candidates.Add(portal.OtherCellId);
            }
        }
    }
```

- [ ] **Step 5: Wire `CheckBuildingTransit` into `FindCellList`**

In `src/AcDream.Core/Physics/CellTransit.cs`, find the outdoor seed branch of `FindCellList`:

```csharp
else
{
    // Outdoor seed.
    AddAllOutsideCells(worldSphereCenter, sphereRadius, currentCellId, candidates);
    // TODO: check_building_transit hookup at Task 7.
}
```

Replace the TODO with the building loop:

```csharp
else
{
    // Outdoor seed.
    AddAllOutsideCells(worldSphereCenter, sphereRadius, currentCellId, candidates);

    // For each landcell candidate, check if it has a building stab.
    var landcellSnapshot = new List<uint>(candidates);
    foreach (uint landcellId in landcellSnapshot)
    {
        var building = cache.GetBuilding(landcellId);
        if (building is null) continue;
        CheckBuildingTransit(cache, building, worldSphereCenter, sphereRadius, candidates);
    }
}
```

- [ ] **Step 6: Wire `CacheBuilding` at landblock load**

In `src/AcDream.App/Rendering/GameWindow.cs`, find the existing `lbInfo.Buildings` iteration (around line 5641 where portal planes are extracted). Add a call to `_physicsDataCache.CacheBuilding` inside the loop, using the actual property names from Task 0. Example shape (the exact property names need substitution):

```csharp
foreach (var building in lbInfo.Buildings)
{
    // building.Portals → IReadOnlyList<BldPortal>
    // building.Frame   → world transform (or building.Transform — check Task 0)
    var portals = new System.Collections.Generic.List<AcDream.Core.Physics.BldPortalInfo>(building.Portals.Count);
    foreach (var bp in building.Portals)
    {
        portals.Add(new AcDream.Core.Physics.BldPortalInfo(
            otherCellId:   bp.OtherCellId,
            otherPortalId: bp.OtherPortalId,
            flags:         (ushort)bp.Flags,
            exactMatch:    bp.ExactMatch));
    }

    // Compute the building's world transform.
    var buildingTransform = System.Numerics.Matrix4x4.CreateFromQuaternion(building.Frame.Orientation)
                          * System.Numerics.Matrix4x4.CreateTranslation(building.Frame.Origin + origin);

    // Building lives in a specific outdoor landcell. The dat encoding is
    // typically a "SortCell" id — derive it from building.Frame.Origin or
    // the building's containing-cell field (verify in Task 0).
    uint landcellId = (lb.LandblockId & 0xFFFF0000u)
                    | (uint)(((int)(building.Frame.Origin.X / 24f) * 8 + (int)(building.Frame.Origin.Y / 24f)) + 1);

    _physicsDataCache.CacheBuilding(landcellId, portals, buildingTransform);
}
```

(The landcell-id derivation may need adjusting based on retail's exact SortCell rules — confirm during Task 0 investigation. If the building's containing-cell is stored explicitly in the DAT, use that instead of the X/Y math.)

- [ ] **Step 7: Run all tests**

Run: `dotnet build && dotnet test`
Expected: build green, all new tests pass, pre-existing 8 failures unchanged.

- [ ] **Step 8: Commit**

```
git add src/AcDream.Core/Physics/BuildingPhysics.cs `
        src/AcDream.Core/Physics/PhysicsDataCache.cs `
        src/AcDream.Core/Physics/CellTransit.cs `
        src/AcDream.App/Rendering/GameWindow.cs `
        tests/AcDream.Core.Tests/Physics/CellTransitCheckBuildingTransitTests.cs

git commit -m "$(cat <<'EOF'
feat(physics): Phase 2 — port BuildingPhysics + CheckBuildingTransit

Adds outdoor→indoor cell entry via building portals. Ported from
retail's BuildingObj::find_building_transit_cells +
CEnvCell::check_building_transit.

New BuildingPhysics type holds the per-SortCell BldPortal list +
building world transform. CacheBuilding wires from GameWindow at
landblock load. CellTransit.FindCellList's outdoor branch now expands
each landcell candidate's building portals (if any) via
CheckBuildingTransit, which point-in-cell tests the destination
interior cell. Closes the "walk into a building from outside" path.

Spec: docs/superpowers/specs/2026-05-19-indoor-portal-cell-tracking-design.md
Plan: docs/superpowers/plans/2026-05-19-indoor-portal-cell-tracking.md

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
```

---

## Task 9: Capture session (user-driven)

**Goal:** verify the four acceptance criteria from the spec live in the Holtburg cottage.

- [ ] **Step 1: Build green**

Run: `dotnet build`
Expected: 0 errors.

- [ ] **Step 2: Launch the client**

User runs:

```powershell
$env:ACDREAM_DAT_DIR              = "$env:USERPROFILE\Documents\Asheron's Call"
$env:ACDREAM_LIVE                 = "1"
$env:ACDREAM_TEST_HOST            = "127.0.0.1"
$env:ACDREAM_TEST_PORT            = "9000"
$env:ACDREAM_TEST_USER            = "testaccount"
$env:ACDREAM_TEST_PASS            = "testpassword"
$env:ACDREAM_PROBE_INDOOR_BSP     = "1"
$env:ACDREAM_PROBE_CELL           = "1"
$env:ACDREAM_PROBE_CELL_CACHE     = "1"
$env:ACDREAM_DEVTOOLS             = "1"
dotnet run --project src\AcDream.App\AcDream.App.csproj --no-build -c Debug *>&1 |
    Tee-Object -FilePath "launch-phase2-verify.log"
```

- [ ] **Step 3: Test the four acceptance scenarios**

1. **Indoor walking** — Enter the Holtburg cottage. Walk around freely. Walls must block from inside. Furniture must still collide.
2. **Outdoor→indoor** — Walk toward the cottage door from outside. The door must let you through; the walls beside the door must block.
3. **Indoor→outdoor** — Walk back out through the door. Outdoor terrain collision must resume; you're no longer trapped inside.
4. **Indoor→indoor** — If the cottage has multiple rooms, walk between them.

Close the window when done.

- [ ] **Step 4: Verify the log shows clean transitions**

Run:
```bash
rg -c "^\[cell-transit\]" launch-phase2-verify.log
rg -c "^\[indoor-bsp\].*result=Collided" launch-phase2-verify.log
```

Expected:
- Multiple `[cell-transit]` lines including indoor↔outdoor crossings with proper landblock prefixes.
- `[indoor-bsp] result=Collided` lines firing when the player walks into walls.

If neither shows up: portal traversal isn't firing. Re-launch with debugging or escalate.

- [ ] **Step 5: Save log artifact**

The log at `launch-phase2-verify.log` will be cited in the Phase F handoff doc. No commit needed yet.

---

## Task 10: Docs cleanup + handoff

**Files:**
- Modify: `docs/ISSUES.md`
- Modify: `docs/plans/2026-04-11-roadmap.md`
- Modify: `CLAUDE.md`
- Create: `docs/research/<ship-date>-portal-cell-tracking-shipped-handoff.md`

- [ ] **Step 1: Close issues**

In `docs/ISSUES.md`:

- Move **#87** (Indoor cell tracking uses AABB containment...) to "Recently closed". Status DONE. Closed date + commit SHAs.
- Update **#84** (blocked by air indoors): the remaining wall-pass-through symptom is closed by Phase 2. Move to "Recently closed".
- Update **#85** (pass through walls outside→in): the outdoor→indoor entry via `BuildingObj` portals closes this. Move to "Recently closed".

- [ ] **Step 2: Update roadmap**

In `docs/plans/2026-04-11-roadmap.md`, add a "Recently shipped" row for "Indoor portal-based cell tracking" with date + commit SHAs. Remove any forward entry for this work.

- [ ] **Step 3: Update CLAUDE.md**

Update the "Currently in Phase..." paragraph to reflect Phase 2 shipped. Next phase is Claude's choice per work-order autonomy.

- [ ] **Step 4: Write the shipped-handoff doc**

Create `docs/research/<ship-date>-portal-cell-tracking-shipped-handoff.md`. Mirror the format of `docs/research/2026-05-19-cluster-a-shipped-handoff.md`. Cover:

- Commits list with SHAs
- One-paragraph summary of what shipped
- Per-issue resolution (#87, #84, #85 all closed)
- Probe evidence from `launch-phase2-verify.log`
- Diagnostic infrastructure that persists (`[cell-cache]`, `[indoor-bsp]`)
- Follow-up items: `BSPQuery.SphereIntersectsCellBsp` for retail-faithful neighbour-add; parts/AABB variant of `find_transit_cells` for remote entities; `VisibleCells` cleanup filter.

- [ ] **Step 5: Final build + test sweep**

Run: `dotnet build && dotnet test`
Expected: 0 errors, all new tests pass, 8 pre-existing failures unchanged.

- [ ] **Step 6: Commit the docs**

```
git add docs/ISSUES.md `
        docs/plans/2026-04-11-roadmap.md `
        CLAUDE.md `
        docs/research/<ship-date>-portal-cell-tracking-shipped-handoff.md

git commit -m "$(cat <<'EOF'
docs(phase): Indoor portal-based cell tracking shipped

Closes ISSUES.md #87, #84, #85. Portal-graph cell traversal replaces
Phase D's AABB containment; player can now walk freely inside
buildings, walls block consistently, doors update CellId correctly,
walking into a building from outside works.

ISSUES.md: #84/#85/#87 → Recently closed.
Roadmap: Indoor portal cell tracking added to shipped table.
CLAUDE.md: current-phase paragraph updated.

Follow-up items (filed inline in handoff doc):
- BSPQuery.SphereIntersectsCellBsp port for retail-faithful neighbour-add
  (currently uses a plane-side heuristic)
- parts/AABB variant of find_transit_cells for remote-entity cell tracking
- VisibleCells cleanup filter at end of find_cell_list

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
```

---

## Self-review checklist (run after writing the plan)

1. **Spec coverage:** every spec section maps to a task. ✓ §1-2 → background; §3-4 architecture/components → Tasks 1-7; §5 data flow → Tasks 3 + 7; §6 commit shape → Tasks 3 + 7 + 8 + 10; §7 files → File Structure table; §9 testing → per-task unit tests + Task 9 live; §10 acceptance → Task 9.
2. **Placeholder scan:** Two intentional `<CellBSP-property-name>` substitutions remain in Task 3 — these get resolved at Task 0. The landcell-id derivation in Task 8 Step 6 may need tweaking based on Task 0 findings — flagged inline. No "TBD", "TODO", or unspecified behavior.
3. **Type consistency:**
   - `PortalInfo(ushort, ushort, ushort)` is consistent across Tasks 1, 2, 3, 4.
   - `BldPortalInfo(uint, ushort, ushort, bool)` consistent across Tasks 8.
   - `CellTransit.FindCellList(cache, worldSphereCenter, sphereRadius, currentCellId) → uint` consistent across Tasks 6, 7.
   - `CellTransit.FindTransitCellsSphere(cache, currentCell, currentCellId, ws, r, candidates, out exitOutside)` consistent across Tasks 4, 6.
   - `CellTransit.AddAllOutsideCells(ws, r, currentCellId, candidates)` consistent across Tasks 5, 6, 7.
   - `CellTransit.CheckBuildingTransit(cache, building, ws, r, candidates)` consistent across Task 8.
4. **Acceptance:** matches spec §10. Visual verification by user in Task 9.