# Portal-Flood Membership Stability — the indoor "flap" root-cause fix

**Date:** 2026-06-08
**Branch:** `claude/thirsty-goldberg-51bb9b`
**Status:** design approved (user, 2026-06-08); TDD implementation pending behind a visual gate.

---

## 1. Summary

The indoor render **flap** (textures "battling" at the doorway threshold) is **portal-flood
set-membership instability**: from a *stable* viewer cell, the PView BFS includes or excludes a
deeper cell cluster frame-to-frame, redrawing a different set each frame. The fix makes set
membership depend on a **stable visibility predicate** (side-test + view-region overlap) instead of
the **drift-prone surviving-vertex count** of the per-portal clip. Localized to
`PortalVisibilityBuilder`; no camera/movement/physics/clip-math rewrite.

---

## 2. Root cause — confirmed with primary evidence

### 2.1 What the flap actually is

Live `[render-sig]` + `[pv-input]` capture at the Holtburg cottage threshold (landblock `0xA9B4`),
standing at the doorway:

- The render root is **stable** (`root=0xA9B40170`, `outRoot=n`, i.e. an interior viewer cell — NOT
  the outdoor node, NOT a root toggle).
- The flood cell set **oscillates frame-to-frame**: `ids=[0170,0171,0172,0173,0174,0175]` (6) ↔
  `ids=[0170,0171]` (2). The deeper cluster `{0172,0173,0174,0175}` pops in/out.
- The oscillation occurs **at a byte-identical (to cm) eye AND player position** — e.g. three
  consecutive frames at eye `(155.55,15.45,96.05)`, player `(155.40,13.20,94.00)` with flood
  `6,2,6`.

### 2.2 Why it flips — the mechanism

1. `PortalVisibilityBuilder.Build` is a **pure** static function with all-fresh per-call state
   (new `frame`/`todo`/`queued`/`popCounts` every call). Proven deterministic by
   `PortalVisibilityBuilderTests.Build_IsDeterministic_IdenticalInputsGiveIdenticalVisibleSet`
   (passes). **So for identical inputs the output cannot flip** → the flip requires a varying input.
2. The high-precision `[pv-input]` probe (6 dp) shows the camera eye and the **player
   `RenderPosition` carry perpetual ~1–8 µm float jitter every frame** even "standing still"
   (e.g. player `94.000000 ↔ 94.000008`, eye `96.248863 ↔ 96.248871`). At most poses this is
   harmless; the flood is stable.
3. The per-portal clip is a faithful homogeneous port of retail's `polyClipFinish`
   (`PortalProjection.ProjectToClip` → `ClipToRegion`, w-aware Sutherland–Hodgman). But the
   **re-enqueue fixpoint** (`MaxReprocessPerCell`) re-clips a cell's view each round, and the
   codebase documents that this **drifts per round** (`PortalVisibilityBuilder.cs:43,151,732`:
   "ProjectToClip drift keeps a view growing forever").
4. At the threshold pose a deeper portal is **grazing** (oblique / near the eye) → it projects to a
   thin sliver. The per-round drift + the µm viewpoint jitter flip `ClipToRegion`'s surviving-vertex
   count across the `<3` boundary (PortalProjection.cs:118/121) → `clippedRegion.Count` flips
   `0 ↔ N` → the cull at **`PortalVisibilityBuilder.cs:235`**
   (`if (clippedRegion.Count == 0 && !EyeInsidePortalOpening) continue;`) drops the deeper cluster
   on the empty-clip frames → flood `2 ↔ 6` → the flap.

### 2.3 Why prior fixes did not work

- **boom-snap** (camera stabilization, shipped): the jitter is sub-cm and **perpetual** (it is in the
  player `RenderPosition`, propagating to the camera); snapping the boom distance did not make the
  viewpoint bit-exact, so the knife-edge still flips.
- **w-space clip** (`ProjectToClip`/`ClipToRegion`, shipped): this made the *single* clip robust, but
  the instability is in the **re-clip drift across rounds** + the membership gate's dependence on the
  surviving-vertex count, not in a single clip.
- **viewer-cell dead-zone** (tried, reverted): the root does not toggle here (`root=0170` stable), so
  a root-resolution dead-zone is irrelevant to this symptom.

### 2.4 What this REFUTES (the 2026-06-07 handoff diagnosis)

The predecessor handoff
(`docs/research/2026-06-07-cutover-flip-render-residuals-diagnosis-handoff.md`) is **wrong** on its
load-bearing claims; do not act on its F1/F2:

- "See-through walls from outside" — **not reproduced**: standing outside with the door closed is
  **stable** (user visual gate, 2026-06-08).
- "The walls ARE the EnvCell shells; the ModelId is a partial frame" — **refuted**: the cottage
  ModelId GfxObj `0x01000A2B` is a full closed exterior (76 render polys, bbox 20×18×10.4 m, 46
  outward-facing walls + roof; cross-checked vs the physics BSP + retail `DrawBuilding`). The EnvCell
  shells are interior-facing room surfaces. **F2 (build EnvCell back faces / double-side) targets the
  wrong geometry.**
- "Oscillation = outdoor-node flood instability (1↔13)" — **corrected**: it is the *indoor* flood
  (`outRoot=n`, stable root) swinging **2↔6**. F1 targeted the wrong root.
- "branch=RetailPViewInside every frame proves the flap is gone" — **tautological**: post-flip
  `clipRoot = viewerRoot ?? _outdoorNode` is essentially never null, so the `branch` label can no
  longer report `OutdoorRoot`. It proves nothing.

---

## 3. Retail grounding

Retail `PView::ConstructView` (decomp `acclient_2013_pseudo_c.txt:433750`): a cell becomes a draw-set
member the moment it is popped from the todo list (`:433783`). A neighbour is enqueued only if the
per-portal `ConstructView` (`:433827`) passes: the **side-test** (`:433832-433849`, `dot(viewpoint,
planeN)+d` vs a 0.2 mm epsilon → POSITIVE/IN_PLANE/NEGATIVE) **AND** `GetClip` (`:432344`) returns a
**non-empty** clip (`:433858` `if (arg3 != 0)`). `GetClip` projects via `xformStart` and clips via
`ACRender::polyClipFinish` (`:702749`).

So retail gates membership on a non-empty clip **too** — it never flaps because (a) it processes each
cell **once** (enqueue-once; no re-clip drift) and (b) its viewpoint is **bit-stable at rest** (the
authoritative local position does not move). acdream diverges on **both** (re-enqueue drift + µm
viewpoint jitter), and the two combine at the grazing portal.

The fix restores retail's **intent** — "the portal is visible through the accumulated view" — with a
predicate that is stable under acdream's residual drift/jitter, rather than the literal
drift-sensitive vertex count.

---

## 4. The fix (design)

**Principle:** set-membership is decided by a **stable** visibility predicate, not by the drift-prone
surviving-vertex count of the clip. The clip still computes the *draw* region; it no longer decides
*whether* a reachable cell is in the set.

**Change — localized to `PortalVisibilityBuilder` (the line-235 gate):**

- Today (`PortalVisibilityBuilder.cs:235-244`):
  ```
  if (clippedRegion.Count == 0)
  {
      if (!EyeInsidePortalOpening(poly, cell.WorldTransform, cameraPos)) continue; // cull
      foreach (var vp in activeViewPolygons) clippedRegion.Add(clone(vp));         // flood with parent view
  }
  ```
- New: when `clippedRegion.Count == 0` but the portal **passed the side-test** (already computed:
  `sideAllowed`, the stable plane-side test) **and its projection still overlaps the current view
  region** (a stable convex-overlap predicate — true for a thin grazing sliver inside the region,
  false for an off-screen portal), keep the neighbour by flooding it with the parent's view (the same
  substitution the `EyeInsidePortalOpening` branch already does). Otherwise cull as today.

The drift-prone `clippedRegion.Count` no longer flips membership; a portal that is genuinely visible
through the accumulated view (stable side-test + stable overlap) stays in the set every frame.

**The stable overlap predicate** (`PortalOverlapsView`, new small helper): does the portal's
projected polygon overlap any of the `activeViewPolygons`? Implemented to be stable for the
near/grazing case (the failure mode is `ClipToRegion` losing a vertex to float noise, NOT the gross
position of the sliver, which sits well inside the view region — so a robust "any-overlap" test
returns a steady boolean). Exact formulation is fixed in TDD (§5); candidates: (a) any portal NDC
vertex inside the region OR any region vertex inside the portal OR any edge crossing; (b) reuse the
existing `EyeInsidePortalOpening` 3D near-region test generalized from "eye in opening" to "eye within
the portal's view cone." The chosen formulation MUST keep the #95 guard test green.

**This subsumes the `EyeInsidePortalOpening` special-case** (a portal the eye stands in trivially
overlaps the full-screen region), so that ad-hoc patch is removed once the general predicate is in
place — fewer special cases, not more.

**#95 over-inclusion guard preserved:** an off-screen portal (2 m to the side) does not overlap the
view region → still culled. No visible-set blowup.

---

## 5. Verification (TDD)

Write the failing test first, then the fix.

1. **RED → GREEN — degenerate-clip membership.** New deterministic test in
   `PortalVisibilityBuilderTests`: construct an interior portal that (a) passes the side-test, (b)
   whose projection overlaps the view region, but (c) whose `ClipToRegion` returns `<3` verts
   (degenerate sliver — the live failure mode), and the eye is NOT standing in the opening. Assert the
   neighbour **is** in `OrderedVisibleCells`. RED today (culled at line 235 because not
   `EyeInsidePortalOpening`); GREEN after the fix (kept because side-test + overlap). This pins the
   gate change without needing to reproduce the exact µm knife-edge.
   - *Optional companion (robustness):* if a fixture can be found whose clip flips `<3 ↔ ≥3` under a
     µm eye nudge, add a test asserting `OrderedVisibleCells` is identical across the nudge. Skip if
     it proves too geometry-sensitive to construct stably — the deterministic test above is the gate.
2. **Stays GREEN — #95 over-inclusion guard.** `Build_DegeneratePortalToTheSide_NotFlooded_NoOverInclusion`
   (off-screen portal stays culled).
3. **Stays GREEN — existing behavior.** `Build_EyeStandingInInteriorPortal_FloodsNeighbour`,
   `Build_CollapsedInteriorPortalNearEyeBeyondHalfMeter_FloodsNeighbour`,
   `Build_IsDeterministic_IdenticalInputsGiveIdenticalVisibleSet`, and the existing cellar/window
   clip tests.
4. **Visual gate (user).** At the cottage doorway threshold, hold still — the 2↔6 oscillation is
   gone; the deeper rooms render steadily through the door. Walking in/out remains seamless.

`dotnet build` + `dotnet test` green before the visual gate.

---

## 6. Scope / non-goals

- **In scope:** `PortalVisibilityBuilder` (the line-235 gate + the `PortalOverlapsView` helper),
  removal of the now-subsumed `EyeInsidePortalOpening` force-flood branch, the new + existing tests.
- **Non-goals (explicitly deferred):**
  - No camera / movement / interpolation / physics changes (the µm viewpoint jitter is left as-is;
    the fix is robust to it).
  - No clip-math rewrite (`ProjectToClip`/`ClipToRegion` stay).
  - **Restoring retail's enqueue-once traversal** (removing the re-enqueue fixpoint, eliminating the
    per-round drift at its source) is a real, larger, retail-faithful improvement but a **separate
    step** — out of scope here. This fix neutralizes the drift's effect on membership without
    restructuring the BFS.

---

## 7. Apparatus (diagnostic probes added this session)

- **Keep:** `PortalVisibilityBuilderTests.Build_IsDeterministic_*` (regression value);
  `tools/A8CellAudit` `gfxobj` dump mode (reusable).
- **Strip after the fix is visually verified:** the `[pv-input]` probe + `RenderingDiagnostics.ProbePvInputEnabled`
  (GameWindow.cs / RenderingDiagnostics.cs), the `outRoot=`/`bshell=` fields added to `[render-sig]`,
  and `launch-bshell-probe.ps1` / `launch-pvinput.ps1`. All env-var-gated and inert when off; safe to
  leave until the visual gate passes, then remove.

---

## 8. References

- Diagnosis evidence + refutation: this session's `[render-sig]`/`[pv-input]` captures (cottage
  threshold), the `Build_IsDeterministic` test, the GfxObj `0x01000A2B` render-geometry dump.
- Retail decomp: `PView::ConstructView` `:433750`/`:433827`, `PView::GetClip` `:432344`,
  `ACRender::polyClipFinish` `:702749` (`docs/research/named-retail/acclient_2013_pseudo_c.txt`).
- Superseded: `docs/research/2026-06-07-cutover-flip-render-residuals-diagnosis-handoff.md` (wrong on
  see-through / EnvCell-walls / outdoor-node — see §2.4).
- Memory to correct: `project_indoor_flap_rootcause`, `reference_render_pipeline_state`.