From c8188e0ed695288a268f0b23d3d0f93ce56833d7 Mon Sep 17 00:00:00 2001
From: Erik <erik.nihlen@gmail.com>
Date: Sat, 13 Jun 2026 18:35:58 +0200
Subject: [PATCH] =?UTF-8?q?docs:=20correct=20stale=20UCG=20CellGraph=20com?=
 =?UTF-8?q?ments=20=E2=80=94=20the=20graph=20is=20active,=20not=20inert?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The "consumed by nobody (zero behavior change)" / "INERT in Stage 1 (no writer)"
comments predate the UCG becoming load-bearing. Verified against the call sites:
CellGraph is populated unconditionally in CacheCellStruct (before the idempotency
+ null-BSP guards, so BSP-less cells are included) and consumed for the player
render/lighting root (CurrCell, written at the PhysicsEngine.UpdatePlayerCurrCell
player chokepoint; read by GameWindow:7502/7717), the universal id->cell resolver
(GetVisible), the 3rd-person camera cell (FindVisibleChildCell), and the
block-local terrain origin (TryGetTerrainOrigin, read by CellTransit:484/736).
Comments only — no behavior change. Core suite 1445 passed / 2 skipped.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 src/AcDream.Core/Physics/PhysicsDataCache.cs | 12 ++++++++++--
 src/AcDream.Core/World/Cells/CellGraph.cs    | 19 ++++++++++++++-----
 2 files changed, 24 insertions(+), 7 deletions(-)

diff --git a/src/AcDream.Core/Physics/PhysicsDataCache.cs b/src/AcDream.Core/Physics/PhysicsDataCache.cs
index deec7ed3..7218e016 100644
--- a/src/AcDream.Core/Physics/PhysicsDataCache.cs
+++ b/src/AcDream.Core/Physics/PhysicsDataCache.cs
@@ -26,8 +26,16 @@ public sealed class PhysicsDataCache
     private readonly ConcurrentDictionary<uint, BuildingPhysics> _buildings = new();
 
     /// <summary>
-    /// UCG Stage 1: the unified cell graph, built alongside the legacy cell caches.
-    /// Consumed by nobody this stage (zero behavior change).
+    /// The unified cell graph (UCG): the active id-&gt;cell resolver and registry.
+    /// Populated unconditionally in <see cref="CacheCellStruct"/> — BEFORE the
+    /// idempotency + null-BSP guards, so BSP-less cells are registered too — and
+    /// consumed across the engine: the player render/lighting root
+    /// (<c>CellGraph.CurrCell</c>, written at the player chokepoint
+    /// <c>PhysicsEngine.UpdatePlayerCurrCell</c> and read by the renderer), the
+    /// universal id-&gt;cell lookup (<c>GetVisible</c>), the 3rd-person camera cell
+    /// (<c>FindVisibleChildCell</c>), and the block-local terrain origin
+    /// (<c>TryGetTerrainOrigin</c>, read by <c>CellTransit</c>'s pick + transit
+    /// paths). No longer inert.
     /// </summary>
     public UcgCellGraph CellGraph { get; } = new();
 
diff --git a/src/AcDream.Core/World/Cells/CellGraph.cs b/src/AcDream.Core/World/Cells/CellGraph.cs
index fb6269fd..00b19ce9 100644
--- a/src/AcDream.Core/World/Cells/CellGraph.cs
+++ b/src/AcDream.Core/World/Cells/CellGraph.cs
@@ -6,17 +6,26 @@ using AcDream.Core.Physics;   // TerrainSurface
 namespace AcDream.Core.World.Cells;
 
 /// <summary>
-/// The unified cell graph: the authoritative id-&gt;cell resolver and registry.
-/// Built alongside the legacy render/physics cell systems in Stage 1 and consumed
-/// by nobody (zero behavior change). Retail anchor: CObjCell::GetVisible (pseudo_c:308209).
-/// Worker-thread populated; reads are concurrency-safe.
+/// The unified cell graph: the active, authoritative id-&gt;cell resolver and registry.
+/// Populated unconditionally from
+/// <see cref="AcDream.Core.Physics.PhysicsDataCache.CacheCellStruct"/> (before its
+/// idempotency + null-BSP guards, so BSP-less cells are included) and consumed across
+/// the engine: <see cref="GetVisible"/> resolves any cell id, <see cref="CurrCell"/> is
+/// the player render/lighting root, <see cref="FindVisibleChildCell"/> resolves the
+/// 3rd-person camera cell, and <see cref="TryGetTerrainOrigin"/> supplies the block-local
+/// terrain origin for the LandDefs lcoord math. Retail anchor: CObjCell::GetVisible
+/// (pseudo_c:308209). Worker-thread populated; reads are concurrency-safe.
 /// </summary>
 public sealed class CellGraph
 {
     private readonly ConcurrentDictionary<uint, EnvCell> _envCells = new();
     private readonly ConcurrentDictionary<uint, (TerrainSurface Terrain, Vector3 Origin)> _terrain = new();
 
-    /// <summary>Player's current cell. Defined for Stage 2; INERT in Stage 1 (no writer).</summary>
+    /// <summary>The player's current cell — the render/lighting root. Written ONLY at the
+    /// player chokepoint <see cref="AcDream.Core.Physics.PhysicsEngine.UpdatePlayerCurrCell"/>
+    /// (NPCs never touch it — a per-entity writer was the cottage-doorway "blue-hole"
+    /// cause); read by the renderer for the player root (GameWindow). Left unchanged when
+    /// the id isn't yet resolvable in the graph (stale beats null).</summary>
     public ObjCell? CurrCell { get; internal set; }
 
     public bool Contains(uint envCellId) => _envCells.ContainsKey(envCellId);