acdream/docs/superpowers/specs/2026-06-08-portal-flood-enqueue-once-port-design.md

# Portal-Flood Enqueue-Once Port — the indoor "flap" fix (verified design)

**Date:** 2026-06-08
**Branch:** `claude/thirsty-goldberg-51bb9b`
**Status:** Design approved (brainstorm). Pending implementation plan.

> **Supersedes** the enqueue logic in `docs/superpowers/specs/2026-06-08-portal-flood-membership-stability-design.md`
> (whose §4 enqueue-once was an *incomplete* attempt — it dropped the `AddToCell` growth half) and the
> physics-rest direction in `docs/research/2026-06-08-flap-rootcause-physics-rest-handoff.md` (refuted).
> **Diagnosis evidence:** `docs/research/2026-06-08-flap-physics-diagnosis-REFUTED-its-render-membership.md`
> + this session's two adversarial verification agents (retail decomp + acdream code/data).

---

## 1. Summary

The indoor render **flap** (interior textures battling / popping in and out at a building doorway) is a
**render-side portal-flood membership instability**: as the camera **eye** moves (turning the camera, or
the camera's smoothing-glide after a turn), the set of cells the flood deems visible **oscillates**
(e.g. `8↔3`) even though the eye sweeps **monotonically**. The root is acdream's **re-enqueue-on-growth
"drift"** in `PortalVisibilityBuilder.Build` (`cs:322`, `MaxReprocessPerCell = 16`): a cell whose view
grows is re-enqueued and its portals **re-clipped from the grown (drifted) view** each round; under
sub-cm eye motion each frame re-clips slightly differently → the visible set flips.

The fix is a **verbatim port of retail's enqueue-once portal traversal** (`PView::ConstructView` +
`AddViewToPortals`): a cell is enqueued **only on first discovery**; its portals are clipped **exactly
once** (at pop); later growth into an already-discovered cell is unioned **incrementally in place**
(`AddToCell`) and its draw-list slot re-ordered (`FixCellList`) — **never re-enqueued, never re-clipped
from scratch**. This makes the visible set a deterministic function of the **root + geometry**, so it no
longer drifts with eye jitter. Localized to `PortalVisibilityBuilder`. No camera, physics, rooting, clip-
math, or seal change.

---

## 2. Root cause — verified this session

### 2.1 What the flap is NOT (refuted with primary evidence)
- **Not physics.** `door-recheck-capture.jsonl`: **216,300 standstill physics records, 0 position
  re-snaps** — the body is byte-stable at rest. Deterministic tests (flat terrain + indoor cell, resolver
  + full controller) confirm: a resting body holds a byte-identical position. The 2026-06-08 AM
  "physics rest µm-jitter" diagnosis is refuted.
- **Not the camera rooting or the inside/outside toggle.** Verified against retail (agent 1):
  `SmartBox::RenderNormalMode` (0x453aa0) calls **`DrawInside(viewer_cell)`** (decomp 92675), and
  `SmartBox::update_viewer` (0x453ce0) sets `viewer_cell` from a **swept `CTransition`** seeded at the
  **player's cell** (`init_path(cell_1, …)` 92866 → `viewer_cell = sphere_path.curr_cell` 92871). So
  rooting at the camera's `viewer_cell` and toggling `DrawInside`/`LScape::draw` are **retail-faithful**.
  The locked-design claim "root at the player cell" (`2026-06-02 …redesign-design.md` §1.5) is **wrong**;
  acdream's current `clipRoot = viewerRoot ?? _outdoorNode` (eye-cell rooting) is correct and stays.
- **Not camera drift at rest.** When the eye is byte-stable (hands-off idle), the flood is rock-stable
  (203/181/178-frame byte-identical-eye runs hold a single flood value). The camera settles; the flap
  fires **only while the eye moves**.

### 2.2 What the flap IS (verified — agent 2 + live capture)
- The flood oscillates **only when the eye moves**: across ~7,800 flood flips, **3** had a byte-identical
  eye (all startup/streaming); **~87 %** of eye-motion flips have a **byte-identical player** position.
  A clean burst (yaw byte-constant, eye gliding monotonically 18→5 mm/frame as the camera settles) shows
  flood `8→3→8…` — **non-monotonic membership under a monotonic eye sweep**.
- The mechanism is the **re-enqueue/re-clip drift**: `PortalVisibilityBuilder.cs:322`
  `if (grew && popCounts.GetValueOrDefault(neighbourId) < MaxReprocessPerCell && queued.Add(neighbourId))
  todo.Insert(neighbour, dist);` re-enqueues a grown neighbour up to 16×; each re-process re-clips the
  cell's portals from its grown view, so sub-cm eye jitter walks `ClipToRegion`'s surviving-vertex count
  across the empty/non-empty boundary → the deep cluster `{0172-0175}` drops/returns → the flap.
- **Sub-issue "C" (indoor flood=2 / "missing textures") is mostly a *symptom* of this drift**, not a
  missing seal: the landscape-through-the-door seal **is** present in the indoor path
  (`RetailPViewRenderer.DrawInside` → `DrawLandscapeThroughOutsideView`). When the flood drops `8→3`,
  the `OutsideView`/terrain/cell clip shrinks → things vanish. Fixing the drift removes the symptom.

---

## 3. Retail grounding (the traversal being ported)

All from `docs/research/named-retail/acclient_2013_pseudo_c.txt`:

- **`PView::ConstructView`** (0x5a57b0, :433750): `InitCell(root)` + `InsCellTodoList(root)`, then a loop
  that **pops one cell at a time** from the todo list, **appends it to the draw list** (← that is
  membership), sets `cell_view_done = 1` (:433784), runs `ClipPortals` once, then `AddViewToPortals`.
- **`PView::AddViewToPortals`** (0x5a52d0, :433446): for each visible portal to a neighbour, three cases
  keyed on the neighbour's stamps (`processed_stamp` = `*(view+0x44)`, `view_stamp` = `*(view+0x38)`):
  - **First discovery** (`processed_stamp == 0`, :433478): `InitCell(neighbour)` + `InsCellTodoList`
    (**enqueue once**).
  - **Growth** (`processed_stamp != view_stamp`, :433492): `AddToCell(neighbour)` + if already drawn
    `FixCellList`; then `processed_stamp = view_stamp`. **No re-enqueue. No re-clip from scratch.**
  - **Already current** (`processed_stamp == view_stamp`): **nothing**.
- **`PView::AddToCell`** (0x5a4d90, :433050): clips the cell's portals against **only the newly-added
  view slices** (`for i = esi[0x11]; i < esi[0xe]`) — an **incremental** union, not a full re-clip; it
  does **not** re-contribute to `OutsideView`.
- **`PView::FixCellList`** (0x5a5250, :433407) → `AdjustDrawList` (:433107): **re-orders** the grown cell
  in the draw list to preserve draw order. No re-flood.
- **`PView::InitCell`** (0x5a4b70, :432896): seeds the cell's view, clips its portals against the full
  incoming view, stamps with `master_timestamp`; returns whether the cell is non-empty (→ enqueue).

So retail clips each cell's portals **exactly once** (at pop). Late growth refines a cell's own view +
draw order, never its downstream flood. This is the `cell_view_done` "process each cell once" guarantee.

---

## 4. The fix (design)

**Scope: `PortalVisibilityBuilder.Build` only.** Replace the re-enqueue-on-growth fixpoint with retail's
enqueue-once traversal. Concretely:

**Change A — enqueue-once (`Build` ~308-328).** Today:

    var nview = GetOrCreate(frame.CellViews, neighbourId);
    bool grew = AddRegion(nview, clippedRegion);                 // union in place (= retail AddToCell)
    if (grew && popCounts.GetValueOrDefault(neighbourId) < MaxReprocessPerCell && queued.Add(neighbourId))
        todo.Insert(neighbour, dist);                            // RE-ENQUEUE on growth ← the drift

New: enqueue a neighbour into `todo` **only on first discovery** — i.e. when it has **no `CellViews`
entry yet** (retail `processed_stamp == 0` → `InitCell` + `InsCellTodoList`). On growth into an
already-discovered neighbour, **keep `AddRegion`** (incremental union = `AddToCell`) and re-order it in
the draw list if already present (`FixCellList`, §Change C), but **do not** re-insert into `todo`.

**Change B — remove the re-enqueue machinery.** Delete `MaxReprocessPerCell`, `popCounts`, and the
per-pop re-enqueue / `queued`-reset logic in the pop loop. Termination is now by construction (each cell
enqueued ≤1, popped ≤1; ≤N cells total), matching retail `cell_view_done`. The `MaxReprocessPerCell` cap
existed **only** as a termination band-aid for the re-enqueue — with enqueue-once it is dead.

**Change C — draw-list re-order on growth (`FixCellList`).** When growth unions into an
already-discovered cell that is **already in `OrderedVisibleCells`**, re-position it to preserve
closest-first draw order (retail `AdjustDrawList` :433107). If acdream's `OrderedVisibleCells` is already
distance-sorted at assembly time and order is not load-bearing for correctness, this degrades to a no-op
— confirm during implementation; do **not** add ordering machinery the renderer doesn't consume.

**Unchanged (explicitly):** the per-portal clip (`ProjectToClip`/`ClipToRegion`), the
`EyeInsidePortalOpening` degenerate-portal guard (`Build:235-244`), the reciprocal `OtherPortalClip`, the
`OutsideView` exit contribution, the rooting (`clipRoot = viewerRoot ?? _outdoorNode`), the camera, and
the landscape-through-door seal. No new predicate, no robustness heuristic, no hysteresis.

**Why this is the flap fix, not a band-aid:** with each cell's portals clipped once, the visible set is a
deterministic function of `(root, geometry)` — independent of the per-round re-clip path. Sub-cm eye
jitter changes the *projection* (and thus what's drawn within each clipped cell, correctly) but no longer
changes *which cells are members*. The membership stops oscillating; the textures stop battling.

---

## 5. The `Build_ViewGrowthAfterDoneCell` question (open item, resolve during implementation)

The re-enqueue was added 2026-06-07 "to propagate late-discovered slices to exit portals," and
`PortalVisibilityBuilderTests.Build_ViewGrowthAfterDoneCell_PropagatesNewSlicesToExit` encodes that. But
the decomp shows retail's `AddToCell` (:433050) only clips the cell's **own** portals against new slices
+ re-orders draw position — it does **not** re-contribute to `OutsideView` (the exit slice is emitted by
`ClipPortals` at pop, once). So "late growth reaches the exit/OutsideView" appears to be **non-retail**.

**Action:** read `PView::ClipPortals` (the OutsideView contribution site) during implementation to
confirm. If confirmed, this test encodes the non-faithful re-enqueue behavior and is **corrected to
match retail** (late growth refines the cell's view + draw order, not the OutsideView). It will **not**
be satisfied by reinstating the re-enqueue. If the OutsideView tests
(`Builder_Cellar_WindowClippedToStairwell`, look-in tests) shrink, that is the retail behavior, handled
retail's way — not by re-adding the drift.

---

## 6. Testing (TDD)

The flap manifests only under live µm/mm eye motion at a specific grazing geometry, so the **visual gate
is acceptance**; the unit layer pins determinism + guards regressions.

1. **Deterministic eye-sweep stability (new, the RED→GREEN driver).** In `AcDream.App.Tests`
   (alongside `PortalVisibilityBuilderTests`, since `PortalVisibilityBuilder` is an App-layer type), build
   the flood at a sequence of eye positions stepping across the grazing door angle (sub-cm steps
   reproducing the live sweep). **Assert each cell's membership across the sweep is a single contiguous
   run** — no `present→absent→present` (or `absent→present→absent`) flicker for any cell. That is the
   precise anti-flap property (the live capture showed `8→3→8→3`, multiple transitions per cell). RED
   under the re-enqueue drift; GREEN after enqueue-once. *Fixture note:* the captured dumps live at
   `tests/AcDream.Core.Tests/Fixtures/flap-doorway/0xA9B4017{0..5}.json`; the test must reach them
   (shared path or copied into `AcDream.App.Tests/Fixtures`) and the cells must carry the portal graph +
   clip planes `Build` consumes. If the cell-dump format omits portals/clip-planes, the impl plan either
   extends the dump or synthesizes a minimal doorway portal topology reproducing the grazing geometry —
   surface this as the first implementation step, do not silently weaken the test.
2. **Enqueue-once termination + dedup (new).** Diamond (a cell reachable from two parents) + cycle
   fixtures: assert the flood terminates with `MaxReprocessPerCell` removed, `OrderedVisibleCells` is
   deduped, each reachable cell present exactly once, and (if a per-cell pop counter is cheap to surface)
   each cell popped ≤1.
3. **No membership regression.** `Build_IsDeterministic_*`, `Build_EyeStandingInInteriorPortal_FloodsNeighbour`,
   `Build_CollapsedInteriorPortalNearEyeBeyondHalfMeter_FloodsNeighbour`,
   `Build_DegeneratePortalToTheSide_NotFlooded_NoOverInclusion` (#95 guard), and the cellar/window/look-in
   tests stay **green**. `Build_ViewGrowthAfterDoneCell_PropagatesNewSlicesToExit` is handled per §5.
4. **Visual gate (user) — acceptance.** At the cottage doorway: turn the camera back and forth and walk
   through — the interior rooms render steadily, no battling/popping; the `[pv-input]` flood is stable
   for a given eye pose. Re-run with `launch-flap-capture.ps1`.

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

---

## 7. Scope / non-goals

- **In scope:** `PortalVisibilityBuilder.Build` enqueue logic (enqueue-once; remove
  `MaxReprocessPerCell`/`popCounts`/re-enqueue; incremental union on growth; draw-order re-position) + the
  new/updated tests; reading `ClipPortals` to settle §5.
- **Non-goals (deferred / untouched):**
  - **No rooting change** — eye-cell rooting (`clipRoot = viewerRoot ?? _outdoorNode`) is retail-faithful
    (§2.1). The locked design's "root at player cell" is refuted, not implemented.
  - **No clip-math change** (`ProjectToClip`/`ClipToRegion`), no `EyeInsidePortalOpening` change, no
    overlap predicate, no hysteresis/robustness heuristic.
  - **No camera, physics, or seal change.** The landscape-through-door seal already exists; C is a symptom
    of the drift and resolves with it.
  - The 4 GREEN physics rest-stability tests added this session stay as regression guards (they document
    that physics rest is bit-stable → the flap is not physics).

---

## 8. Apparatus + references

- **Diagnosis + verification:** `docs/research/2026-06-08-flap-physics-diagnosis-REFUTED-its-render-membership.md`;
  this session's two adversarial verification agents (retail decomp CONFIRMED rooting/seal; acdream
  code/data CONFIRMED physics-out + eye-driven + the `cs:322` drift).
- **Captured fixtures:** `tests/AcDream.Core.Tests/Fixtures/flap-doorway/0xA9B4017{0..5}.json`;
  `flap-doorway-resolve.jsonl`. Apparatus: `launch-flap-capture.ps1`, `analyze_flap_live.py`,
  `find_burst.py`, the `[pv-input]` probe (`ACDREAM_PROBE_PVINPUT`, now logs eye/player/rawPlayer/yaw).
- **Retail decomp anchors:** `ConstructView` :433750, `AddViewToPortals` :433446, `InitCell` :432896,
  `AddToCell` :433050, `FixCellList` :433407 / `AdjustDrawList` :433107, `InsCellTodoList` :433183,
  `SmartBox::update_viewer` :92761, `SmartBox::RenderNormalMode` :92635.
- **Superseded:** `2026-06-08-portal-flood-membership-stability-design.md` §4 (incomplete enqueue-once);
  `2026-06-08-flap-rootcause-physics-rest-handoff.md` (physics direction, refuted).
- **Memory to correct after ship:** `project_indoor_flap_rootcause` (root = the `PortalVisibilityBuilder`
  re-enqueue/re-clip **drift** under a moving eye; rooting/toggle is retail-faithful; physics + camera
  exonerated).