diff --git a/docs/research/2026-06-12-doorway-artifacts-129-130-handoff.md b/docs/research/2026-06-12-doorway-artifacts-129-130-handoff.md new file mode 100644 index 00000000..1ed3e5cc --- /dev/null +++ b/docs/research/2026-06-12-doorway-artifacts-129-130-handoff.md @@ -0,0 +1,156 @@ +# Doorway artifacts #130 + #129 (+ #113 re-check, UN-2 desk work) — handoff (2026-06-12) + +**Branch state:** `claude/thirsty-goldberg-51bb9b` == `main` == pushed to BOTH +remotes (github + git.snakedesert.se) at `c007f5a`. Suites green: +App 246 + 1 skip / Core 1438 + 2 skips / UI 420 / Net 294. +CLAUDE.md is the NEW CONDENSED structure — orient via its `## Current state` +section (status ≤5 lines + pointers; do not re-add banners). + +## 0. What this session closed (do NOT re-litigate) + +| Closed | Root cause | Commits | +|---|---|---| +| **#119/#128** tower broken stairs + "water barrel" (user-gated) | (1) interior entity ids discarded the landblock X byte + Tier-1 cache hinted by PLAYER landblock → cross-entity batch serving; (2) anchor-±5m culling bounds didn't contain the mesh (gaze-dependent vanish); (3) the knife-edge in-plane portal clip | `3cf6bcc` probe, `2163308` cache/ids, `987313a` W=0 clip port + rescue DELETED, `1ca412d`+`6a9b529` vertex-derived bounds | +| **#112** hill-cottage transparent interior (user-gated) | the cottage's entry cell 0x104 is a 0.22 m threshold band; running tick-skips it, and the outdoor-seed pick had NO growing-array walk → the miss was ABSORBING (stuck outdoor-classified inside). Retail walks ONE growing array for every seed; ported verbatim | `be03146` (pins: `Issue112MembershipTests`) | +| **The divergence register** | 108 audited rows of every known acdream-vs-retail deviation; rules in CLAUDE.md (same-commit rows; scan-on-symptom) | `ebf61f9`, `3c3293a` — [docs/architecture/retail-divergence-register.md](../architecture/retail-divergence-register.md) | + +Durable lesson shipped to memory: [[feedback_culling_bounds_from_drawn_data]] +(culling volumes derive from the DATA that gets drawn, never a constant). + +## 1. THE QUEUE (in order) + +### #130 — background-color strip along the TOP outer edge of a doorway, looking out from inside (FIRST: suspected fresh regression) + +- **User report ("also NOW")** — plausibly a regression from `987313a` (the + W=0 clip port / EyeInsidePortalOpening rescue deletion). Fresh debt + outranks the queue. +- **Symptom:** standing inside looking out, a thin strip of clear/world + color runs along the outer TOP edge of the doorway opening. +- **Leads (ISSUES.md #130):** if the OutsideView's top edge sits ~1 px BELOW + the aperture's drawn shell edge, terrain isn't drawn in that strip while + the seal/punch cleared it → background. Suspects inside the port: + `MergeSubPixelVertices` shaving a top vertex; the exact-w boundary vs the + old 1e-4 epsilon shifting the projected edge; the deleted rescue no longer + substituting a full view for an eye-pressed doorway. Alternate: a 1-px + seal-vs-shell mismatch (#118-era machinery). +- **Plan:** (1) capture at a doorway showing the strip — + `ACDREAM_PROBE_VIEWER=1` + a screenshot + the `[snap]`/[viewer] eye+cell; + (2) replay the frame headlessly (CornerFloodReplayTests machinery: + `LoadCell`/`LoadBuilding` + `PortalVisibilityBuilder.Build`) and diff the + OutsideView top edge NDC against the aperture polygon's projected top + edge; (3) cross-check by locally reverting `987313a` at the same doorway. +- **⚠️ Discipline:** if it traces to the port, fix the EDGE MATH — the + rescue does NOT come back (CLAUDE.md no-workarounds; the rescue was the + documented compensation we just retired). + +### #129 — doors/doorways leak through terrain + houses from ~a landblock away + +- **Lead (top suspect, ISSUES.md #129):** #117's stencil depth-gate punch + (`478c549`, PortalDepthMaskRenderer) marks aperture pixels at biased true + depth with a CONSTANT 0.0005 NDC bias. Screen depth is non-linear: at + ~200 m that constant spans METERS of view depth → hills/houses in front + of the aperture get marked + far-Z punched → door-shaped leak through the + occluder. (A register row of the documented-approximation kind, in + effect.) +- **Fix shape:** re-derive the bias in EYE-SPACE (scale by w / convert a + fixed eye-space epsilon to per-pixel NDC), keeping #108's coverage (the + bias exists so the punch covers the aperture's own pixels at close range). +- **Falsification first:** capture at the spot (screenshot + [viewer] eye) + → confirm the leak patch matches a distant building's aperture polygon; + then a headless test on the bias math at 5 m vs 200 m depths. + +### #113 re-check (rides the first launch — costs one glance) + +- The hill-cottage phantom staircase (appearing at distance, half-embedded + in the wall). **Plausibly already dead**: the `2163308` cache fix killed + cross-entity batch serving (the phantom may have been a town twin wearing + the tower's staircase batches — distance-dependent via the old + player-landblock cache hints). +- If STILL present: the proper fix is the TS-20 register row — drawing-BSP + orphan polys (hall 0x010014C3 dict polys {0,1} referenced by NO + DrawingBSP node; retail draws by BSP traversal, we iterate the dict). + Spec + the histogram-on-a-door-GfxObj first step: + `docs/research/2026-06-11-building-render-holistic-port-handoff.md` (the + naive filter `e46d3d9` broke doors Holtburg-wide → un-applied `124c6cb`; + do not re-apply naively). + +### UN-2 — GetMaxSpeed contradictory justifications (DESK WORK — no user/launch needed) + +- `src/AcDream.Core/Physics/MotionInterpreter.cs` ~:972: the method doc's + upper paragraph says multiplying by RunAnimSpeed was "a misread of the + decomp — retail's catch-up IS that slow on purpose" (~5.9 m/s at run + 200); the implementation comment below it APPLIES ×RunAnimSpeed (4.0) + citing "ACE MotionInterp.cs:670-678 verified against retail" + (≈11.76 m/s). Both cannot be true — possible 4× remote catch-up error + (the #41 remote-blip family). +- Resolve via the oracle: grep `get_max_speed`/`InterpolationManager::adjust_offset` + in the named decomp; cdb-trace a live retail remote if the decomp is + ambiguous. Then fix the doc OR the code, and move the register row + UN-2 → its resolved kind (or delete it if ported exactly). + +### After these: #124 (far-building back walls through openings — interior-root +look-in floods missing, lead in ISSUES.md), #108-residual (cellar grass band, +eye-below-grade window), #127 (distant-building admission churn), #116 +(slide-response family, oracle-first). Closing this list ≈ the M1.5 → M2 +boundary (M2 = kill a drudge: combat). + +## 2. Apparatus inventory (use, don't rebuild) + +| Tool | How | For | +|---|---|---| +| `[viewer]`/`[viewer-diff]` probe | `ACDREAM_PROBE_VIEWER=1` | root/flood/outPolys/pCell + mm eye per change | +| `[cell-transit]` probe | `ACDREAM_PROBE_CELL=1` | player cell changes (membership side) | +| `[dump-entity]` probe | `ACDREAM_DUMP_ENTITY=0xID,0xID` | one-shot entity MeshRefs/cache/bounds dump (HYDRATE/DRAW/WALK-REJECT) | +| `[WB-DIAG]` counters | `ACDREAM_WB_DIAG=1` | entSeen/entDrawn/meshMissing + [mesh-miss] self-heal | +| CornerFloodReplayTests | App.Tests | dat-backed headless flood replay (LoadCell/LoadBuilding fixtures) — the #130 replay base | +| Issue112MembershipTests | Core.Tests | membership pick replay incl. RegisterBuildings helper | +| The divergence register | docs/architecture/ | scan on ANY unexplained symptom BEFORE instrumenting | +| Launch protocol | CLAUDE.md "Running the client" | build green FIRST; background launch + Tee to log; graceful close; ACE session rules | + +## 3. Process reminders + +- The user's reports are AXIOMS; visual gates are the acceptance tests. +- Launch, hand over, do NOT foreground/screenshot while they play; read + logs when told (live tail-reads of the Tee'd log are fine and effective — + the #112 capture was decided live this way). +- Register discipline: new deviation → row in the same commit; retired → + delete the row. Phase checklist now enforces it. +- Suites green per commit: App 246+1skip / Core 1438+2skip / UI 420 / Net 294. + +## 4. Paste-ready pickup prompt + +``` +Pick up acdream as a SENIOR 3D ENGINE DEVELOPER on the doorway render +artifacts. Branch claude/thirsty-goldberg-51bb9b == main (everything +pushed). Read FIRST: CLAUDE.md "Current state" (the condensed structure), +then docs/research/2026-06-12-doorway-artifacts-129-130-handoff.md (THE +handoff — queue, leads, apparatus), then the render digest +(claude-memory/project_render_pipeline_digest.md, DO-NOT-RETRY table +applies). + +WORK ORDER: +1. #130 — background strip at the doorway TOP edge looking out from + inside. Suspected REGRESSION from the W=0 clip port (987313a). Capture + at a doorway (ACDREAM_PROBE_VIEWER=1 + screenshot + eye/cell), then + headless replay (CornerFloodReplay machinery) diffing the OutsideView + top edge vs the aperture polygon's projected edge. If it's the port, + fix the EDGE MATH — the EyeInsidePortalOpening rescue does NOT come + back. +2. #129 — doors/doorways leak through terrain/houses at ~a landblock. + Top suspect: #117's stencil punch bias is a constant 0.0005 NDC + (478c549) — meters of real depth at 200 m. Falsify with a capture, + then re-derive the bias in eye-space; keep #108's aperture coverage. +3. #113 re-check rides the first launch: one glance at the hill-cottage + phantom stairs — plausibly dead via 2163308 (cache cross-serving). If + alive, the TS-20 register row + the holistic-port handoff own the fix. +DESK-WORK ALTERNATIVE (no user needed): UN-2 register row — resolve the +GetMaxSpeed ×4 contradiction (MotionInterpreter.cs ~:972) against the +named decomp / live cdb; possible 4x remote catch-up error. + +The user's reports are AXIOMS. Visual gates are the acceptance tests. +Build + test green per commit (App 246+1skip / Core 1438+2skip / UI 420 / +Net 294). Launch protocol per CLAUDE.md: build green first, background +launch with Tee to a log, hand over, read logs when told. Register +discipline applies: any new deviation gets its register row in the same +commit. +```