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:

# 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.