diff --git a/docs/research/2026-05-26-a8-wb-full-port-rr1-shipped-handoff.md b/docs/research/2026-05-26-a8-wb-full-port-rr1-shipped-handoff.md new file mode 100644 index 0000000..5d85394 --- /dev/null +++ b/docs/research/2026-05-26-a8-wb-full-port-rr1-shipped-handoff.md @@ -0,0 +1,250 @@ +# 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](../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](../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](2026-05-26-a8-rr0-falsification-findings.md)** — evidence that triggered the scope expansion. +4. **[references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/VisibilityManager.cs:73-330](../../references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/VisibilityManager.cs)** — the proven reference (RenderInsideOut Steps 1-5 at 73-239; RenderOutsideIn at 241-330). +5. **[CLAUDE.md](../../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: + ```bash + 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`): + ```bash + 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): + + ```csharp + 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.