acdream/docs/research/2026-05-26-a8-wb-full-port-rr1-shipped-handoff.md

Phase A8 — RR1 cleanup SHIPPED. Handoff for RR2 spike in fresh session.

Date: 2026-05-26 (PM, end of session) Branch: claude/strange-albattani-3fc83c (worktree at .claude/worktrees/strange-albattani-3fc83c) HEAD: 29e306b (RR1 footer-marks) Build: green (0 errors, 0 warnings in App; 6 warnings in test projects are pre-existing lint) Tests: within documented 14-23 flaky window

---

TL;DR

This session pivoted Phase A8 from "WB-faithful restructure" to "full WorldBuilder RenderInsideOut + RenderOutsideIn port" after RR0 falsification revealed R3+R3.5's bugs were structural (BFS-wide cell rendering), not just workaround-induced.

Shipped this session:

• ✅ RR0 falsification spike (proved Issues A+C are R3-caused, not pre-existing on main)
• ✅ Re-brainstorm with new design doc
• ✅ 12-task implementation plan
• ✅ RR1 cleanup: [vis] probe committed; R3+R3.5 v1+v2 reverted; old design+plan footer-marked as superseded

Next: RR2 spike — inspect LandBlockInfo.Buildings data shape + WB's interior-portal walk algorithm before implementing BuildingLoader in RR3.

---

State altitudes

• Currently working toward: M1.5 — Indoor world feels right
• Current phase: A8 — full WorldBuilder RenderInsideOut + RenderOutsideIn port
• Tasks remaining: RR2 (spike) → RR3-RR11 (impl + visual gates) → RR12 (ship)
• Estimated remaining: 8-10 sessions / 1.5-2 weeks calendar

---

What shipped this session (8 commits)

SHA	What
f9bab50	docs(research): RR0 findings — A+C caused by R3, NOT pre-existing on main
ea60d1f	docs(spec): Full WB RenderInsideOut + RenderOutsideIn port design
651e7e2	docs(plan): 12-task implementation plan
84c4a70	diag(render): [vis] probe — light up dormant ProbeVisibilityEnabled
664ca9c	Revert R3.5 v2 (2bfeafd)
b931038	Revert R3.5 v1 (38d5374)
fd721af	Revert R3 (60f07bc) — with [vis] probe preserved through conflict
29e306b	docs: superseded the prior restructure design + plan

Kept (NOT reverted): R1 (ed72704 IsBuildingShell tag) + R2 (55f26f2 EntitySet partition) + Tasks 1-6 infrastructure (PortalPolygons, IndoorCellStencilPipeline, portal_stencil shaders, ProbeVisibilityEnabled). All consumed as-is by the upcoming work.

---

Canonical pickup docs (READ FIRST in fresh session)

In order:

1. docs/superpowers/specs/2026-05-26-phase-a8-wb-full-port-design.md — the approved design. Single source of truth for what's being built.
2. docs/superpowers/plans/2026-05-26-phase-a8-wb-full-port.md — 12-task plan. Pickup at RR2.
3. docs/research/2026-05-26-a8-rr0-falsification-findings.md — evidence that triggered the scope expansion.
4. references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/VisibilityManager.cs:73-330 — the proven reference (RenderInsideOut Steps 1-5 at 73-239; RenderOutsideIn at 241-330).
5. CLAUDE.md — "Currently working toward" section.

---

RR2 — the spike

Goal

Before implementing BuildingLoader in RR3, verify (a) what fields DatReaderWriter.Types.BuildingInfo exposes (specifically the portal list field name + the per-portal OtherCellId); (b) how WB's PortalRenderManager actually computes a building's full cell set from BuildingInfo entries (the interior-portal walk algorithm).

The plan's RR3 tests reference building.Portals and BldPortal.OtherCellId — RR2 confirms or corrects those names.

Steps (per plan §RR2, 6 sub-steps)

1. RR2-S1 — Inspect BuildingInfo struct shape:

   grep -rn "class BuildingInfo\|struct BuildingInfo\|record BuildingInfo" references/Chorizite.DatReaderWriter/ 2>/dev/null | head -5
   

   Or look in NuGet cache: ~/.nuget/packages/chorizite.datreaderwriter/*/lib/*/BuildingInfo.cs. Also document what LandblockLoader.cs:74-87 references.

2. RR2-S2 — Read WB PortalRenderManager.cs:518-551 (or grep BuildingPortalGPU + EnvCellIds):

   grep -n "BuildingPortalGPU\|EnvCellIds" references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/PortalRenderManager.cs | head -10
   

   Document the interior-portal walk algorithm.

3. RR2-S3 — Live-inspect a Holtburg cottage's BuildingInfo. Add a temporary diagnostic in src/AcDream.Core/World/LandblockLoader.cs:74-87 (the Buildings loop):

   Console.WriteLine($"[building-shape] lb=0x{landblockId:X8} idx={i} ModelId=0x{building.ModelId:X8} " +
       $"Frame.Origin=({building.Frame.Origin.X:F1},{building.Frame.Origin.Y:F1},{building.Frame.Origin.Z:F1}) " +
       $"Portals={building.Portals?.Count ?? 0}");
   if (building.Portals is not null)
   {
       foreach (var p in building.Portals)
           Console.WriteLine($"[building-shape]   portal -> OtherCellId=0x{p.OtherCellId:X8} " +
               $"(remaining fields: {p.GetType().GetProperties().Length} total)");
   }
   

   Build + launch + walk to Holtburg. Capture log. Then git checkout HEAD -- src/AcDream.Core/World/LandblockLoader.cs to revert.

4. RR2-S4 — Write docs/research/2026-05-26-a8-buildings-data-shape.md with 5 sections (per plan).

5. RR2-S5 — Commit findings.

6. RR2-S6 — Gate decision:

   • Data shape compatible with design → proceed to RR3.
   • Data shape incompatible → STOP, re-brainstorm.

Expected duration

~30-60 minutes including live-inspect cycle.

Human-in-the-loop step

RR2-S3 (live-inspect) needs the user to launch + walk into a cottage + report.

---

Quick context primer for a fresh session

Why this phase

RR0 falsification proved:

• HEAD (R3.5 v2): Issues A + C reproduce
• R3 baseline (60f07bc): same A + C (R3.5 patches didn't help)
• main (7034be9, no A8 work): A + C don't reproduce, BUT constant #78 (houses below terrain from inside)

R3's stencil work fixed #78 but introduced A + C by rendering all 16 BFS-reachable cells at full screen extent. The fix is per-portal recursive culling (what retail + WB both do). For acdream's stack, WB's stencil approach is closer to existing infrastructure than retail's polygon-clip scissor.

Why full WB port (not minimum)

The user explicitly chose "full WB port now" over (a) revert all A8 and live with #78 or (b) keep R1+R2 and revert only R3+R3.5. Decision recorded in the design doc's "Brainstorm outcomes" section.

What's in scope (per design)

• WB RenderInsideOut Steps 1-5 (including 3-stencil-bit cross-building visibility, Step 5)
• WB RenderOutsideIn (cottage interiors visible through windows from outside)
• Per-building cell association (Building + BuildingRegistry + LoadedCell.BuildingId — Option C dual-indexed per user's Q2 answer)
• Single strict cameraInsideBuilding gate (drop grace for render path; CellVisibility's grace stays alive for non-render consumers)
• Stencil-gated sky inside indoor branch (acdream enhancement over WB)

What's NOT in scope

• Retail polygon-clip scissor port (multi-week alternative)
• Cell-side BuildingId as SOLE data source (Option B — rejected for awkward API)
• Reverting R1+R2 (kept — orthogonal infrastructure)

---

Files state at session end

Branch:        claude/strange-albattani-3fc83c
HEAD:          29e306b (RR1 footer-marks)
Working tree:  clean (only untracked log files + research docs from prior sessions)
Build:         green
Tests:         within flaky window

Uncommitted predecessor docs (intentionally not committed by previous sessions):
  docs/research/2026-05-26-a8-entity-taxonomy.md
  docs/superpowers/plans/2026-05-26-phase-a8-indoor-cell-visibility-culling.md
  docs/superpowers/plans/2026-05-26-phase-a8-replan.md
  (plus several A6 / issue-78 / issue-101 / cellar saga docs)
These are not blocking — they were referenced by handoff docs that DID get
committed, so the chain works at the file-system level. If a fresh session
wants tidy git history, run a single tidy-up commit gathering these.

---

Pickup prompt for fresh session

Phase A8 — full WB RenderInsideOut + RenderOutsideIn port. RR1 cleanup
shipped 2026-05-26 PM (commits 84c4a70 → 29e306b). Pick up at RR2 (spike).

Read first (REQUIRED, in order):
  1. docs/research/2026-05-26-a8-wb-full-port-rr1-shipped-handoff.md
     (this doc)
  2. docs/superpowers/specs/2026-05-26-phase-a8-wb-full-port-design.md
     (the approved design)
  3. docs/superpowers/plans/2026-05-26-phase-a8-wb-full-port.md
     (12-task plan; pick up at RR2)
  4. docs/research/2026-05-26-a8-rr0-falsification-findings.md
     (evidence triggering the scope expansion)
  5. references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/VisibilityManager.cs:73-330
     (the proven reference)
  6. CLAUDE.md — "Currently working toward" line + A8 paragraph

State both altitudes:
  Currently working toward: M1.5 — Indoor world feels right
  Current phase: A8 — full WB port
  HEAD: 29e306b (RR1 footer-marks)
  Test baseline: build green; ~14-23 flaky test window (pre-existing)

Session flow:

### RR2 — spike (this session)

Per plan §RR2, 6 steps:
  S1: inspect DatReaderWriter.BuildingInfo via grep/nuget
  S2: read WB PortalRenderManager:518-551
  S3: live-inspect a Holtburg cottage's BuildingInfo (temp diagnostic in
      LandblockLoader.cs, launch, user walks to cottage, capture log,
      revert diagnostic)
  S4: write docs/research/2026-05-26-a8-buildings-data-shape.md
  S5: commit findings
  S6: gate — if data shape compatible, proceed to RR3; else re-brainstorm

Expected ~30-60 min. Single commit.

### RR3-RR12 — subsequent sessions

Subagent-driven (one fresh Sonnet subagent per code task with two-stage
review). Direct orchestration for RR8/RR10/RR12 visual gates.

## Constraints

- Per CLAUDE.md "no workarounds" rule — fix root causes. The new design
  is the proper fix; don't iterate on R3.5-style symptom patches.
- WB code under references/WorldBuilder/ is MIT-licensed and the same
  stack as acdream (Silk.NET, .NET); port verbatim where possible with
  WB line refs in comments.
- Visual verification is the acceptance test. RR8 gate must close #78
  + R4 Issues A + C BEFORE proceeding to RR9 (Step 5).
- DO NOT re-revert R1 (ed72704) + R2 (55f26f2) — they're orthogonal
  infrastructure consumed by the upcoming work.

## What success looks like

After all 12 tasks ship (~1.5-2 weeks calendar):
  - Standing inside Holtburg cottage / cellar / inn / dungeon: all walls
    solid. Sky visible through windows.
  - Exit/entry transitions clean (Issues A + C closed).
  - Cross-building visibility (Step 5) working — inn → cottage interior.
  - Cottage interiors visible from outside through windows
    (RenderOutsideIn).
  - #78 closed; #102 closed; no regression on #100.
  - M1.5 indoor scope fully shipped.

---

Why pause now

The session has covered ~8 hours of brainstorm + design + plan + cleanup. Context budget is substantial. A fresh session for RR2 (the spike) lets the upcoming long stretch of RR3-RR12 implementation start with maximum context room for the subagents to consume. This is exactly the milestone-discipline rhythm CLAUDE.md describes.

Tomorrow's session opens with the pickup prompt above. The work is well-shaped: RR2 is small (≤1 hour); each of RR3-RR11 is one or two sessions of subagent-dispatched work with two-stage review; RR8 + RR10 + RR12 are visual gates that need ~30 min each of you driving the test client.

Good night. M1.5 is closer than it was this morning.