# The AAB3 tower "broken stairs + water barrel" — fundamental handoff (2026-06-11 late)

**Branch:** `claude/thirsty-goldberg-51bb9b`. **Nothing on main.** Suites green:
App 242 + 1 skip / Core 1422 + 2 skips / UI 420 / Net 294.
**The user logged out INSIDE the tower in the BROKEN state** — the next login
restores there (claim `0xAAB30107` validates cleanly now), so the broken state
is one login away for the next session.

## 0. The one fact that reframes everything (READ THIS FIRST)

`user-session-capture2.log` — the user standing IN the tower, broken stairs +
barrel visible on screen — final dispatcher diagnostics:

```
[WB-DIAG] entSeen=11808510 entDrawn=11808510 meshMissing=0 ...
```

**meshMissing=0. entSeen == entDrawn. Every referenced mesh is loaded and every
walked entity is drawn — while the user SEES broken stairs.** The staircase is
NOT missing from the pipeline. It is being **drawn wrong** (wrong transforms,
wrong batches, or a stale partial classification). Every "the mesh didn't
load" theory is now DEAD for the persistent symptom. (226 ids — including
stair part `0x01000E2A` — DID go transiently missing during the login churn
and were self-healed by the new point-of-use re-arm; the question is what got
built or cached wrong during that window and STAYS wrong.)

## 1. Symptom + reproduction (user-verified, multiple sessions)

- The AAB3 tower (building[1], model `0x01001117`, cells `0x0107..0x010A`;
  user pinned it by logging out inside — `[snap] claim=0xAAB30107`).
- Its spiral staircase = ONE cell static: **Setup `0x020003F2`, 43 parts**
  (5 platforms `0x01000E2A` + 38 steps `0x01000E2B/2C/2D/2F/31/32`),
  placement frames spiral z 0.35→15.15 (dat-proven,
  `Issue119TowerDumpTests`). Four `0x020005D8` statics (part `0x01001774`,
  barrel-shaped — REAL water-barrel models per the user's screenshot) sit at
  wall positions.
- **Broken state** (reproduces on teleport-heavy / run-back logins, ~3 of 4
  attempts): stairs render PARTIALLY or not at all (collision intact — the
  invisible stairs are walkable to the top), and "a water barrel" shows near
  the floor. **Clean state** (reproduced twice, screenshots in worktree:
  `tower-rearm-verify.png`, `tower-selfheal-verify.png`): full spiral
  staircase, no complaints. Same build can produce both — the divergence is
  SESSION-SHAPED (what happened during login/streaming), and once broken it
  stays broken for the session.
- User axiom: **the barrel is NOT in the tower in retail.** (It IS in the
  dat's `0x0107.StaticObjects`. Unresolved tension — but note H-A below
  predicts the "barrel" may not be the dat barrel at all.)

## 2. What was FIXED today (all verified, all committed — do not re-litigate)

| Fix | Commit | Verified by |
|---|---|---|
| #118 house-exit vanish (seal vs dynamics order) | `5a80a2e` | user gate "Yes solved" |
| #120 flood ping-pong (CellView containment) | `dede7e4` | 0 `[pv-ERROR]` since (was 24/session); #122 cured |
| #121 portals invisible (dynamics-owner particle pass) | `c446473` | user gate "Yes" |
| #125 WB_DIAG GL-error cascade (query ring begun-flags) | `fcade06` | 0 `[wb-error]` under diag |
| Render lift leaking into the visibility graph | `f35cb8b` | captured-frame replay both arms (`CapturedTopOfStairs_*`) |
| #126 restore re-derived Z (now commits server Z — retail SetPositionInternal 0x00515bd0 shape) | `120aeff` | clean `VALIDATED` snaps since |
| #128 first-ever-only Prepare gate | re-arm commit | `[mesh-miss]` self-heal observed live (226 ids re-requested) |
| Point-of-use re-request (mesh absence now impossible) | last commit | final `meshMissing=0` in the broken session — which is exactly what KILLED the absence theory |

Each fix was real; none was THE tower bug. The user's "running in circles"
critique stands: the persistent symptom survives all of them.

## 3. The live hypothesis space (ranked — design the probe, don't guess)

**H-A — hydration-time MeshRef corruption (top suspect).** The staircase
entity's 43 MeshRefs are built ONCE at landblock hydration
(`GameWindow.BuildInteriorEntitiesForStreaming` → `SetupMesh.Flatten(setup)`,
GameWindow ~5611-5627). `SetupMesh.Flatten` falls back to **identity
transforms** when the placement-frame lookup comes up short
(`SetupMesh.cs:57-61`: `i < defaultAnim.Frames.Count` else identity), and
returns per-part frames from `setup.PlacementFrames` (Resting → Default →
first). If, during the login burst, the Setup object or its frames read
DEGRADED (a dat-race / partially-hydrated object — see
`feedback_phase_a1_hotfix_saga`: DatCollection thread-safety + "objects can
cache half-parsed"), Flatten yields identity (or partial) transforms → **all
43 parts draw stacked at the entity origin = a barrel-shaped pile** ("the
water barrel"!!) with a few parts elsewhere ("broken stairs"). MeshRefs are
never rebuilt → broken all session. PREDICTS: the "barrel" the user sees may
be the collapsed staircase, not the dat barrel; meshMissing=0; entity drawn.
**Probe:** dump the live entity's MeshRefs (count + per-part transform
translations) in the broken state — if translations are ~zero/identity, H-A
is confirmed and the fix is hydration-side (retry/validate Flatten inputs, or
rebuild MeshRefs when degraded).

**H-B — Tier-1 classification cache served a partial/stale batch set.** The
entity classified during the transient-miss window; some path caches an
incomplete batch set that the cache hit then serves forever (static entity →
fast path → never re-classified). The known #53 vetoes (null renderData per
MeshRef; null Setup part — both patched) read correct, but a batch-level
partial (renderData present, batches not yet complete during atlas staging)
may not be vetoed. PREDICTS: drawn entity, wrong/missing batches; fixable by
invalidating the cache entry when any of the entity's ids finishes loading
AFTER the classification. **Probe:** `EntityClassificationCache` dump for the
staircase entity id in the broken state (batch count vs the clean session's).

**H-C — draw-side transform composition** (`ComposePartWorldMatrix` /
`meshRef.PartTransform` path) — least likely (the same code draws the clean
sessions), but the per-part dump from H-A's probe exonerates or implicates it
for free.

## 4. The decisive next step (ONE probe, one launch)

Add a one-shot diagnostic (env-gated, e.g. `ACDREAM_DUMP_ENTITY=0x020003F2`):
at first draw of any entity whose `SourceGfxObjOrSetupId` matches, print:
- `MeshRefs.Count` (expect 43),
- per MeshRef: `GfxObjId` + `PartTransform.Translation` (expect the dat
  spiral: platforms at (0,3,1.55)…(3,3,11.95), steps ascending — compare
  `Issue119TowerDumpTests.DumpTowerStairSetups` output),
- whether the Tier-1 cache has an entry + its batch count.

Launch (the user's save restores INSIDE the tower; the broken state is
probable on first login), read the dump:
- identity/collapsed translations → **H-A**: fix at hydration (validate
  Flatten's inputs; rebuild MeshRefs on degraded reads; likely also explains
  "barrel" as the collapsed pile).
- correct translations + small/odd batch count → **H-B**: cache
  invalidation on late load completion.
- correct everything → H-C: instrument ComposePartWorldMatrix for this id.

## 5. Also pinned today, port pending (the SECOND remaining tower artifact)

The climb strobes + top-of-tower roof/floor flap while TURNING (user: "the
roof and floor up top still flaps when turning") = the knife-edge in-plane
portal clip family, mechanically pinned by capture + replay:
- The eye riding/crossing HORIZONTAL portal planes (spiral climbs, the deck)
  → side test allows (in-plane window) but OUR clip collapses the portal to
  EMPTY → the cell behind drops ([viewer-diff] `removed=[0xAAB30107,0x010A]`
  at the top; mid-climb `removed=[0x0108/0x0109]`).
- Retail has no hole: `ACRender::polyClipFinish` (0x006b6d00, pc:702749) —
  read today: a homogeneous Sutherland-Hodgman whose FIRST pass clips the
  polygon at **W=0 (the eye plane)** with full intersection emission
  (pc:702889-702978: scans vertex W, runs the W-clip pass, REQUIRES ≥3
  output verts, THEN clips against the portal-view edges in homogeneous
  space, `< 3 → return` per edge). **cdstW = 0.000199999995, PINNED at
  0x007247d5** (where it's consumed still to be mapped — grep reads of the
  global 0x008fb788; `landPolysDraw` at 0x006b7040 uses 0.0002 inline for
  plane side tests).
- THE PORT: match `PortalProjection.ProjectToClip`'s near-eye behavior
  (currently `EyePlaneW=1e-4` + empty-collapse) to polyClipFinish's W=0-clip
  semantics; then DELETE the `EyeInsidePortalOpening` rescue (the documented
  cdstW-gap compensation, T2 ledger) and re-run the full harness suite
  (CornerFloodReplay + Issue120 + TowerAscent + the captured-frame pins).

## 6. Apparatus inventory (new this session — use, don't rebuild)

| Tool | Where | Purpose |
|---|---|---|
| `[viewer]` probe | `ACDREAM_PROBE_VIEWER=1` | print-on-change root/flood/outPolys/pCell + eye@mm + fwd |
| `[viewer-diff]` | same flag | names cells entering/leaving the flood per change |
| `[mesh-miss]` | `ACDREAM_WB_DIAG=1` | once-per-id missing-mesh naming + point-of-use re-request |
| `HouseExitWalkReplayTests` | App.Tests | #118 pins (cone + seal-depth + straddle) |
| `Issue120ReciprocalPingPongTests` | App.Tests | #120 pins + `LoadAllInteriorCells` helper |
| `TowerAscentReplayTests` | App.Tests | captured-frame replay + lift canary + gate-by-gate diagnostic |
| `Issue127FloodFlipReplayTests` | App.Tests | outdoor flood replay (stable — flood math exonerated for the 4 cm pair) |
| `Issue119TowerDumpTests` / `Issue119UpNullGfxObjDumpTests` | Core.Tests | tower dat truth / no-draw GfxObj class |
| Session logs (worktree root) | `user-session-capture2.log` (THE broken-state evidence), `tower-rearm-gate.log`, `flap-diff-capture.log`, screenshots | capture record |

## 7. Open issues ledger (post-session state)

- **#119/#128 tower stairs**: OPEN — the drawn-but-wrong layer (§3-4). THE
  priority.
- **knife-edge clip port** (§5): OPEN — second priority; kills climb strobes,
  top flap, and retires the rescue + #120's window class.
- **#124** far-building back walls (interior-root look-in floods missing —
  lead documented in ISSUES), **#127** distant-building churn (narrowed),
  **#108-residual** cellar grass band, **#112** hill-cottage transparency,
  **#113** phantom stairs: all OPEN with leads in ISSUES.md.
- The user axiom stands: **barrel not in retail** — re-evaluate after H-A
  resolves (the "barrel" may be the collapsed staircase).

## 8. Paste-ready pickup prompt

```
Pick up acdream as a SENIOR 3D ENGINE DEVELOPER on the AAB3 tower
"broken stairs + water barrel" bug. Worktree branch
claude/thirsty-goldberg-51bb9b. Nothing goes to main.

READ FIRST (in order):
1. docs/research/2026-06-11-tower-stairs-fundamental-handoff.md — THE
   handoff. Its §0 fact reframes the bug: in the user's broken-state
   session (user-session-capture2.log) the dispatcher reports
   meshMissing=0 / entSeen==entDrawn WHILE broken stairs are on screen —
   the staircase is DRAWN WRONG, not missing. All mesh-absence theories
   are dead (8 real fixes shipped today; none was this).
2. Memory digests: project_render_pipeline_digest +
   project_physics_collision_digest (DO-NOT-RETRY tables apply).

DO NEXT — the decisive probe (handoff §4): add ACDREAM_DUMP_ENTITY-style
one-shot diag printing the staircase entity's (SourceGfxObjOrSetupId
0x020003F2) MeshRefs count + per-part transform translations + Tier-1
cache state at first draw. The user's save restores INSIDE the tower;
the broken state reproduces on teleport-heavy logins (~3 of 4). One
launch + the dump decides H-A (hydration-time MeshRef corruption via
SetupMesh.Flatten identity fallback — top suspect; predicts the "barrel"
IS the collapsed staircase) vs H-B (Tier-1 cache partial batch set) vs
H-C (draw-side compose). Fix the confirmed branch ROOT-CAUSE-FIRST (no
band-aids; the user has explicitly demanded the fundamental fix).

THEN — the knife-edge clip port (handoff §5): match
PortalProjection.ProjectToClip's near-eye clip to retail
ACRender::polyClipFinish (0x006b6d00, pc:702749; cdstW=0.0002 pinned at
0x007247d5): W=0 eye-plane clip with intersection emission, never
empty-collapse for in-plane portals; then DELETE the
EyeInsidePortalOpening rescue and re-run the full harness suite. This
kills the climb strobes + the top-of-tower roof/floor flap while
turning (the user's other standing report).

The user's reports are AXIOMS. Visual gates are the acceptance tests.
Build + test green per commit (App 242+1skip / Core 1422+2skip / UI 420
/ Net 294). When launching for the user: launch, hand over, do NOT
foreground/screenshot the window while they play; read logs when told.
```