acdream/docs/research/2026-05-21-phase-o-t1-prompt.md

# Phase O — Task O-T1 — Session Handoff Prompt

**Copy everything below the line into a fresh Claude Code session.**
The prompt is self-contained — the new session reads it once and has
all the context it needs.

---

You are starting **Phase O — Task O-T1** on acdream. Phase O is **active**
(pre-empts M1.5 by user direction 2026-05-21). The full phase spec is at:

```
docs/superpowers/specs/2026-05-21-phase-o-dat-path-unification-design.md
```

**Read that spec first** (sections 1-4 are the most relevant to this task).
Also read the auto-loaded CLAUDE.md "Currently working toward: Phase O" block.

## What you're doing

Phase O extracts the WorldBuilder code we actually use into our own repo
so we can drop the project references and run with **one dat reader**
(`DatCollection`) instead of two. Task O-T1 is the safety pass that
must happen BEFORE any extraction: produce a closure of every WB type
and file we transitively use, so T2–T7 don't miss a dependency and
break the build at the "drop project references" step.

**This is the `/investigate` skill territory — REPORT-ONLY.** Do not
move files, do not edit source, do not run `dotnet build/test`. Read
files, run read-only diagnostics (`grep`, `git`, `find`), and produce
a single markdown audit document. The user will review and approve
before any extraction starts in a later session.

## Inputs available to you

- **Our code that consumes WB**:
  - `src/AcDream.App/Rendering/Wb/*.cs` — adapters that wrap WB.
    Start with `WbMeshAdapter.cs` and `WbDrawDispatcher.cs`.
  - `src/AcDream.App/Rendering/TerrainModernRenderer.cs` — uses some
    WB types but is our own renderer.
  - Anywhere else with `using WorldBuilder.*` or
    `using Chorizite.OpenGLSDLBackend*`. Grep for both.
- **The WB source itself**:
  - `references/WorldBuilder/WorldBuilder.Shared/` — types we use directly
  - `references/WorldBuilder/Chorizite.OpenGLSDLBackend/` — the rendering code
    we use (`ObjectMeshManager`, `TextureHelpers`, `SceneryHelpers`,
    `LandSurfaceManager`, `OpenGLGraphicsDevice`, `Frustum`, etc.)
- **CSProj files** (the formal dependency boundary):
  - `src/AcDream.App/AcDream.App.csproj` — has the WB ProjectReference entries
  - `src/AcDream.Core/AcDream.Core.csproj` — same

## Concrete steps

1. **Direct-use enumeration.** Find every `using WorldBuilder.*` and
   `using Chorizite.OpenGLSDLBackend*` line in `src/AcDream.*`. For each
   file, list the specific WB types it references (e.g.,
   `ObjectMeshManager`, `OpenGLGraphicsDevice`, `TextureKey`,
   `ObjectRenderBatch`). Don't forget `nameof()` and string references
   in tests.

2. **Transitive closure.** For each WB type in the direct-use set, open
   its file in `references/WorldBuilder/` and list its dependencies on
   *other* WB types. Walk the graph until closed. Be systematic —
   `ObjectMeshManager` will pull on a lot.

3. **Per-file inventory.** For each WB file in the closure:
   - Path (relative to `references/WorldBuilder/`)
   - Line count (`wc -l`)
   - One-line role description
   - Direct callers in our codebase (if any) or in WB (if transitive)
   - Whether it touches `IDatReaderWriter` / `DefaultDatReaderWriter`
     (these become DatCollection-swap candidates)
   - Whether it touches GL state directly (matters for T3 — GL infra
     extraction has different risk than dat-touching code)

4. **Categorize by extraction task**. Bucket each file into one of:
   - **T3 candidate** (texture / GL infrastructure, no dat dep)
   - **T4 candidate** (mesh pipeline)
   - **T5 candidate** (scenery / terrain blending)
   - **T6 candidate** (EnvCell / portal)
   - **NOT EXTRACTED** (we use it via project reference today but
     can drop entirely — e.g., the WB editor tools, anything not in
     our render path). Justify the "not extracted" call for each.

5. **Hidden-dependency probes** (the things that bite at T7):
   - Does WB use any `internal` types that are only accessible to
     classes inside the WB project? If so, we'll have to make them
     `public` or copy more.
   - Does WB use any source generators, .targets files, or build
     hooks that we'd need to replicate?
   - Are there resource files (.png, .glsl, .shader) we need to copy?
   - Does WB's `DefaultDatReaderWriter` differ from our `DatCollection`
     in any behavioral way that would matter when we swap? (Caching,
     thread safety, the same-file-different-handle thing, etc.)
     Don't fully audit — just flag the questions.

6. **Thread-model spot-check** (open question O-Q1 in the spec):
   - Is `ObjectMeshManager` called from the render thread only, or
     does our `LandblockStreamer` worker thread call into it?
     `grep` for the call sites. If the worker thread reaches WB code,
     flag it — we may have a latent race today that becomes obvious
     after extraction.

## Output

Write the audit to:

```
docs/research/2026-05-21-phase-o-t1-wb-audit.md
```

Suggested structure:

```markdown
# Phase O — Task O-T1 — WB Usage Audit

## Direct use surface
(Table of (our file, WB types used))

## Transitive closure
(Tree or table walking from direct types through WB internals)

## Per-file inventory
(Table: path, LOC, role, dat-touch?, GL-touch?, target task bucket)

## Extraction-task mapping
- **T3 (GL infra):** N files, ~M LOC
- **T4 (mesh):** N files, ~M LOC
- **T5 (scenery/terrain):** N files, ~M LOC
- **T6 (EnvCell/portal):** N files, ~M LOC
- **NOT extracted:** N files, with justifications

## Hidden-dependency risks
(Bulleted list of things flagged in step 5)

## Thread-model finding
(Yes/no + evidence on whether WB is called from the worker thread)

## Open questions for user
(Anything unclear that the user needs to call before T2 starts)
```

**Cap the audit doc at ~500 lines.** If the closure is bigger than that,
inline the per-file table for the top 30 files by LOC and link to a
separate appendix file for the long tail.

## Acceptance for O-T1

- Audit doc exists at the path above.
- Every file in the closure is bucketed (T3 / T4 / T5 / T6 / NOT).
- Hidden-dependency risks section has at least the four items in
  step 5 addressed (even if the answer is "none found").
- No source code edited. No `dotnet build/test`. No project files
  touched. (Verify with `git status` at the end — only the new
  audit doc + maybe `git ls-files | grep WorldBuilder | wc -l`-style
  diagnostic output should appear.)

## When you're done

Report back in chat with:

1. Total LOC of the closure (the rough size of the extraction).
2. The bucket breakdown (how many files / LOC per task).
3. Any sharp edges flagged in the hidden-dependency risks section.
4. Your honest read on whether the 7-8 day estimate in spec §5 is
   reasonable given what you found, or whether it needs a revision.

**Then stop.** Do not start T2. The user reviews the audit before
extraction begins.

## Reminders

- You are operating under the `/investigate` skill rules (no edits).
- `references/WorldBuilder/` is the source to grep through, NOT to edit.
- WB is MIT-licensed; the eventual extraction is license-clean. You
  don't need to think about that here.
- If something in the audit surfaces a reason Phase O shouldn't
  proceed (e.g., WB has a license clause we missed, or the closure
  is 50K LOC instead of 5K), say so clearly. We'd rather know now.