acdream/docs/research/2026-06-10-105-110-white-textures-nearplane-handoff.md

# HANDOFF — #105 intermittent missing indoor textures × #110 near-plane correlation

> **✅ CLOSED 2026-06-10 (same day).** Root cause: the per-frame staged-texture flush
> (WB `GameScene.cs:975` → `ObjectMeshManager.GenerateMipmaps()`) was dropped in the
> N.4/O-T4 extraction; fix `c787201`, znear=0.1 re-landed `d4b5c71`. §4's "only credible
> link" (upload pressure) was exactly right. **Read the close-out instead:**
> `2026-06-10-105-110-CLOSED-staged-texture-flush-drop.md`. This document is historical.

**Date:** 2026-06-10 (late). **Branch:** `claude/thirsty-goldberg-51bb9b`, HEAD `8bd3492`.
**Status:** #105 struck twice today with the dat-side tripwires SILENT (= GL-side); the
retail near-plane fix (`137b4f2`, 0.1 m) was bisect-implicated in those two runs and
REVERTED (`8bd3492`) pending this investigation. **One investigation, three payoffs:**
attribute + kill the chronic #105, settle whether the near plane is innocent (#110), and
re-land `znear=0.1` which closes the §4 corner see-through-wall.

Read this top-to-bottom before touching code. The render digest
(`claude-memory/project_render_pipeline_digest.md`) carries the distilled state + the
DO-NOT-RETRY table — this doc is the deep-dive for THIS investigation.

---

## 0. TL;DR

1. **#105 (chronic since ~2026-06-08):** indoor wall/cell textures intermittently render
   wrong ("missing" — exact appearance white-vs-invisible NOT yet confirmed by the user;
   question outstanding). Today it struck on 2 consecutive launches. The four dat-side
   tripwires (`[dat-miss]`/`[tex-miss]`/`[tex-skip]`/`[cell-miss]`, commit `7433b70`)
   produced ZERO output on both bad runs → per the #105 protocol the failure is
   **GL-side**: staged mesh/texture upload, bindless handle creation/residency, or the
   per-batch handle plumbing — NOT a failed dat read.
2. **#110:** both bad runs were on the near-plane build (`znear=0.1`, `137b4f2`); the
   very next run with `znear=1.0` (working-tree bisect) rendered clean. 2-bad-on-0.1 /
   1-good-on-1.0 is *suggestive, not conclusive* — #105 is intermittent and could have
   coincided. No mechanism is known by which znear touches texturing (see §4 for the
   honest candidate list). The change is reverted; all four cameras carry a ⚠️ comment
   pointing here.
3. **The leverage:** if #105 is independent (most likely), fixing it exonerates the near
   plane → re-land `0.1` → §4 corner fix complete. If the near plane genuinely raises
   #105's trigger probability (e.g. more close-up geometry → more upload pressure), the
   fix is still in the #105 path — the near plane just becomes the best repro lever.

## 1. Today's run matrix (the evidence)

| Run (log, worktree root, untracked) | Build (near) | Indoor textures | Notes |
|---|---|---|---|
| `flood-fix-gate.log` | `dac8f6a` (1.0) | OK | user gated the flood fix: transitions clean |
| `flood-fix-gate2.log` | `dac8f6a` (1.0) | OK (no complaint) | #107 spawn wedge run |
| `flood-fix-gate3.log` | `dac8f6a` (1.0) | OK (no complaint) | #107 again |
| `nearplane-gate.log` | `137b4f2` (0.1) | UNKNOWN | user asked to relaunch without detail |
| `nearplane-gate2.log` | `137b4f2` (0.1) | **MISSING** | tripwires silent (checked: 0/0/0/0) |
| `nearplane-gate3.log` | `137b4f2` (0.1) | **MISSING** | fresh launch, same |
| `nearplane-bisect.log` | tree (1.0 on RetailChaseCamera) | **OK** | the bisect run |

Also relevant: the clean-launch #105 occurrence on 2026-06-09 (35-line log, zero errors,
PRE-near-plane) — proof #105 strikes on `znear=1.0` builds too. The near plane cannot be
the sole cause; the open question is independence vs trigger-probability.

## 2. #105 history — what is already settled (DO NOT REDO)

From `docs/research/2026-06-09-dat-reader-thread-safety-investigation.md` + the digest:

- **Concurrent dat READS are SAFE** (Chorizite.DatReaderWriter 2.1.7): source audit + the
  in-tree hammer `DatConcurrencyStressTests` (~1.1 M concurrent reads, zero anomalies).
  The "thread-unsafe dat reader" lore is refuted for the read path. Do not re-litigate.
- **The teardown AccessViolations were dispose-during-read** (decode pool + streamer not
  quiesced before `DatCollection.Dispose` unmapped views) — FIXED `8fadf77`.
- **The "heavy probes cause white walls" framing is PARTIAL at best** — a clean 35-line
  launch reproduced white walls; a heavily-probed run rendered fine. Probe load skews
  timing (still avoid `ACDREAM_PROBE_FLAP` for visual gates) but is not the cause.
- **Every silent dat-miss exit is tripwired** (`7433b70`): `[dat-miss]` (DatCollection
  returns null), `[tex-miss]`/`[tex-skip]` (texture resolve/upload skips), `[cell-miss]`
  (EnvCell load misses). Zero output when healthy. Both of today's bad runs: zero output
  → **the dat → decode → staged-data side delivered; the loss is between staging and the
  draw.**

## 3. The GL-side texture path — anatomy + where it can lose textures

The modern pipeline (N.4/N.5, mandatory — see `reference_modern_rendering_pipeline.md`):

1. **Decode/stage:** `ObjectMeshManager.PrepareMeshDataAsync(id, isSetup)` background-
   decodes mesh + texture data → auto-enqueues to `_stagedMeshData`.
2. **Drain:** `WbMeshAdapter.Tick()` (render thread, per frame) drains the staged queue,
   creates GL resources, populates `AcSurfaceMetadataTable` (per-batch translucency /
   luminosity / fog metadata).
3. **Texture upload:** `TextureCache` `GetOrUpload*Bindless` → GL texture (parallel
   Texture2DArray uploads via `UploadRgba8AsLayer1Array`) → `glGetTextureHandleARB` →
   `glMakeTextureHandleResidentARB`. Returns the 64-bit handle.
4. **Per-batch plumbing:** the handle lands in `ObjectRenderBatch.BindlessTextureHandle`.
   - Entities: `WbDrawDispatcher` Phase 5 uploads `_batchSsbo` (binding=1,
     `(uvec2 handle, uint layer, uint flags)` per group).
   - Cell shells: `EnvCellRenderer.RenderModernMDIInternal` packs `ModernBatchData
     { TextureHandle, TextureIndex }` → `_modernBatchBuffer` (SSBO binding=1, bound at
     EnvCellRenderer.cs:1211).
5. **Sampling:** `mesh_modern.frag` constructs `sampler2DArray(handle)` from the uvec2.
   **A zero handle samples garbage/black/white (undefined)** — this is the classic
   "white walls" appearance.

Loss candidates between staging and draw (ranked):

- **(a) Zero handle at draw time** — the batch was prepared before its texture upload
  completed, and nothing back-patches the handle. Known to exist transiently (textures
  pop in); a bug would make it PERSIST. ⚠️ **There is an EXISTING probe for exactly
  this:** `ACDREAM_PROBE_SHELL=1` (`RenderingDiagnostics.ProbeShellEnabled`) prints, per
  visible cell, gfxObj/batch counts AND `zh=` (zero-bindless-handle batch count) — see
  RenderingDiagnostics.cs:120-130. **One bad-run launch with this probe splits the
  search space in half** (zh>0 ⇒ upload/handle side; zh==0 ⇒ resident-but-wrong-content
  or sampling/state side).
- **(b) Residency loss / never-made-resident** — handle non-zero but
  `MakeTextureHandleResidentARB` skipped or undone → same visual, but zh probe reads 0.
  Needs a residency assert (glIsTextureHandleResidentARB sweep) or RenderDoc.
- **(c) Upload raced/dropped under pressure** — `MaxCompletionsPerFrame` (QualityPreset)
  caps streaming completions per frame; a drop/requeue bug under burst load would lose
  whole cells' textures. Would likely show as *some* cells white, others fine.
- **(d) Texture content wrong but handle valid** — array-layer mixups (zh==0, content
  white). RenderDoc territory.

## 4. #110 — what `znear` can and cannot plausibly do (senior-dev honest list)

`znear` enters the system in exactly one object: the projection matrix
(`CreatePerspectiveFieldOfView(FovY, aspect, znear, 5000f)` in RetailChaseCamera /
ChaseCamera / FlyCamera / OrbitCamera — all currently 1.0 with ⚠️ comments).
Downstream consumers of `viewProj`:

| Consumer | Effect of 0.1 vs 1.0 | Texture relevance |
|---|---|---|
| Rasterization | geometry 0.1–1.0 m from the eye now draws; depth distribution shifts (D24 @ 5 m: ~1.5 µm → ~15 µm) | none direct; z-fighting would flicker, not "lose" textures |
| Frustum culls (terrain/entity/EnvCell prepare) | strictly MORE visible (near plane closer) | **more batches prepared per frame → more uploads in flight → raises (a)/(c) trigger probability** ← the only credible #105×#110 link found |
| PortalVisibilityBuilder flood | viewProj changes per-vertex w by near-plane row only in z-row; flood clip planes are (nx,ny,0,dw) — x,y,w-based; the flood is conformance-gated (`CornerSweep_FloodIsCompleteAndMonotone`) | none |
| gl_ClipDistance regions / terrain UBO | x,y,w-based, near-independent | none |
| Doorway scissor | computed from NdcAabb, projection-independent at the box level | none |

**Conclusion to verify, not assume:** the most credible story is that `znear=0.1` makes
close-up geometry (the wall right behind the camera, the doorframe you're brushing)
*newly visible*, inflating per-frame prepare/upload pressure indoors, which raises the
probability of the pre-existing #105 loss. If true: fixing #105 exonerates the near
plane entirely. The alternative (0.1 breaks texturing via a mechanism not in this table)
needs RenderDoc evidence before being believed.

## 5. Investigation plan (staged, evidence-first)

**Phase A — attribute with the existing probe (cheap, decisive split):**
1. Launch with `ACDREAM_PROBE_SHELL=1` (+ the always-on dat tripwires). Flip-launch until
   a bad run reproduces (today it was 2/3 on the 0.1 build — consider temporarily
   re-applying 0.1 to the working tree as the REPRO LEVER ONLY, clearly uncommitted).
2. On a bad run: read `[shell]` lines for the affected cells. `zh>0` ⇒ path (a)/(b):
   zero/never-patched handles — go to Phase C1. `zh==0` ⇒ path (b)/(d) — go to Phase C2.
3. ALSO capture the user's answer: **white surfaces vs invisible walls** (outstanding
   question — invisible would point at visibility/depth instead and reshape this plan).

**Phase B — settle the #110 correlation statistically (parallel, mechanical):**
Alternate launches 0.1 / 1.0 (working-tree flip on RetailChaseCamera only), ≥4 runs per
arm, record texture state per run (the `[shell] zh=` counts make this detectable WITHOUT
user eyes if path (a)). Independence ⇒ bad runs appear in both arms. The 2026-06-09
clean-launch occurrence already proves 1.0 is not immune.

**Phase C — root-cause:**
- **C1 (zero handles):** instrument the staging→handle path: log every batch that reaches
  the draw SSBO with handle==0 (entity + EnvCell sides), plus `WbMeshAdapter.Tick` drain
  counts and `TextureCache` upload completions per frame. Find who created a batch before
  its texture and never back-patched. Fix = the back-patch / ordering, NOT a retry loop.
- **C2 (valid handles, wrong output):** RenderDoc the bad frame (GPU truth): inspect
  binding=1 SSBO contents, handle residency, sampled texture content, and the draw state
  of an affected wall batch.

**Phase D — close out:** fix #105 root cause → flip-test again (both arms clean) →
re-land `znear=0.1` (re-apply the `137b4f2` payload: 4 cameras + restore the retail
citation comments) → user re-gates the §4 corner press (wall must stay solid at the
camera) + a distance scan for any new z-shimmer (none expected; retail ships 0.1).

## 6. Repro notes + session-ops gotchas (cost real time today)

- **Repro spot:** Holtburg houses near the player's parked position (the user was trying
  on a house interior; exact house id unconfirmed — textures were missing across the
  interior). Frequency today: 2 of 3 launches on the 0.1 build.
- **#107 interference:** logging in while parked INDOORS wedges the player (stuck in
  air/wall, 3-for-3 today — filed). For THIS investigation prefer ending test sessions
  with the character OUTDOORS so logins are clean. If wedged: relaunch; it intermittently
  recovers.
- **ACE session hold:** graceful window close ⇒ ~3–5 s; hard kill ⇒ ~3 min of
  `session failed` (exit 29). The launch protocol + wait loop used all day is in this
  session's transcript; `auto-entered player mode` is the in-world marker.
- **⚠️ PowerShell 5.1 `Get-Content`/`Set-Content` MANGLES UTF-8 source files** (reads
  CP1252, writes mojibake — corrupted all four camera files today; recovered via
  `git checkout` + redoing edits with the Edit tool). **Never bulk-edit source with
  PS5.1 string replace.**
- **Tee-Object logs are UTF-16LE** — Python analyzers must BOM-detect; PowerShell
  `Select-String` handles them natively.
- Probes: `ACDREAM_PROBE_SHELL` is heavy-ish (per-prepare dumps) — short runs. The dat
  tripwires are always-on and free. NEVER judge visuals under `ACDREAM_PROBE_FLAP`.

## 7. What ELSE is open (do not drift into these)

Priority order (set 2026-06-10, digest carries it): **this investigation (#105+#110)** →
**#107** indoor-login spawn wedge (physics; `ACDREAM_CAPTURE_RESOLVE` apparatus ready) →
**#108** cellar-ascent grass sweep + **#109** far-exit-door oscillation (one render
session, probe captures at their spots) → **#99/A6.P4** per-cell shadow architecture
(planned phase). The §4 flood strobe is FIXED (`dac8f6a`, user-gated) — its conformance
gate (`CornerSweep_FloodIsCompleteAndMonotone`) and the corner-seal characterization
(`CameraCornerSealReplayTests`) must stay green through any change here.

## 8. Today's commit ledger (context for blame/diff archaeology)

| Commit | What |
|---|---|
| `682cba3` | [clip-route] probe apparatus (outdoor flap) |
| `c4df241` | outdoor full-world flap FIX (EnvCellRenderer DepthMask(false) leak → depth-clear no-op) |
| `df2ef7c` | flap close-out doc |
| `b21bb28` | corner-seal replay — camera-penetration hypothesis REFUTED (openings, not walls) |
| `482b0de` | corner-seal handoff doc |
| `dac8f6a` | §4 flood strobe FIX (homogeneous reciprocal clip + collinear-aware dedup) — user-gated |
| `137b4f2` | near plane 1.0→0.1 (retail znear) + issues #107–#109 filed |
| `8bd3492` | near plane reverted to 1.0 pending #110; #110 filed |

Test baseline: App **223**, Core **1377** green + 4 pre-existing #99-era failures
(DoorBugTrajectoryReplay ×2 / DoorCollisionApparatus / BSPStepUp) + 1 skip, UI **420**,
Net **294**. ACE on `127.0.0.1:9000`, `testaccount/testpassword`, `+Acdream`.