acdream/docs/plans/2026-08-03-recent-regression-cleanup.md

# Recent-regression cleanup — plan (2026-08-03)

Three defects introduced by the 2026-08-02/03 stabilization batch, found while
reconciling the #281 test failures. All three are **ours, days old, and inside
the least-verified code in the tree**. They are cleared before C4 resumes so
six more placement routes are not stacked on top of them.

Issues: #282 (two cell fields), #283 (two world origins), #284 (silent park).

## Status — CLOSED 2026-08-03

All three landed and are user-accepted.

| Slice | Issue | Commit | Outcome |
|---|---|---|---|
| S1 | #284 | `97d11e6c` | Park reasons named; terminal on the contradictory state |
| S2 | #282 | `3c36b4cc` | One cell owner (`VisibilityCellId`); register row AP-133 |
| S3 | #283 | `898ff18b` → `89cf1e66` | Measured UNREACHABLE; permanent invariant instead of a restructure |

Connected Release gate (retail UI) on S1+S2: user verdict "works fine"; log
showed 9 completed reveals, 58 reveal events all `failures=0`, zero unhandled
exceptions, zero parked placements, graceful exit (`0c14c402`).

S3's probe run recorded zero disagreements across 11 reveals and six landblocks
spanning ~45 km, so ownership was deliberately left alone — the evidence
disproved the hypothesis, and the guard exists to keep it disproven.

Final complete Release solution: **10,844 passed / 4 skipped / 0 failed.**

Next: the original campaign order below, starting at C4 route 2.

## Why these first

Every one is an instance of the exact weakness the placement campaign exists to
remove: **two owners of one fact, with no single writer keeping them agreed.**
#282 duplicates "which cell is this in". #283 duplicates "where is zero". #284
is why both stayed invisible. Fixing them inside C4 would mean diagnosing them
through C4's much larger diff.

## Standing discipline for this plan

- Retail is the oracle. Grep `docs/research/named-retail/acclient_2013_pseudo_c.txt`
  by `class::method` before writing.
- Root causes only. No timeouts, grace periods, suppression flags, or
  catch-and-ignore. #284 in particular is observability + fail-fast, never a
  retry cap.
- **The complete Release solution suite must be green before every commit.**
  Focused-run-only gating is exactly what let #281–#284 ship. The full suite
  takes about 30 seconds; there is no excuse.
- Each fix is its own bisectable commit with root-cause evidence, and updates
  the issue + divergence ledgers in that same commit.

---

## S1 — #284: make a parked placement visible (do this first)

Smallest, and it turns the other two from archaeology into observation.

1. Classify the park reason at the single site that produces it
   (`RuntimeSetPositionState.PrepareMover`): awaiting collision generation,
   awaiting Setup, awaiting world frame.
2. Fold per-reason parked counts into the existing physics ownership snapshot
   (`RuntimePhysicsState.CaptureOwnership`) so they appear wherever ledgers are
   already asserted, and in the connected gates' `report.json`.
3. Fail fast on unresolvable parks. A park awaiting the world frame *while a
   local player is already registered* is not a wait — it is a contradiction.
   Surface it as a committed invariant exception, the pattern `01f4791e`
   established for receipt-ledger violations.
4. Convergence contract: parked entries must be zero at every stable
   checkpoint. Wire that into the lifecycle/nine-stop gate assertions.

**Tests:** each park reason is reported exactly once and clears on resolution;
the contradictory park throws rather than retrying; ledgers converge to zero.
**Gate:** focused Runtime + complete solution suite.

---

## S2 — #282: one owner for an entity's visibility cell

1. **Establish the retail model.** `CPhysicsObj::set_cell_id` @0x0050f4f0,
   `change_cell` @0x00513390, `set_cell_id_recursive` @0x00510da0,
   `ShouldDrawParticles` @0x0050fe60. Retail carries ONE cell per physics
   object, and particle gating reads that same cell. Write the pseudocode note
   before touching C#.
2. **Audit the writers.** 12+ sites write `ParentCellId`
   (`LiveEntityNetworkUpdateController` ×4, `RemotePhysicsUpdater` ×2,
   `ProjectileController` ×3, `LiveEntityOrdinaryPhysicsUpdater`,
   `LocalPlayerProjectionController`, `RemoteTeleportController`, …); 3 write
   `EffectCellId`, all in `LiveEntityRuntime`. For each `ParentCellId` writer
   record whether it also rebuckets — a rebucket with an exact cell currently
   repairs the pair by accident. Produce the table before choosing the fix.
3. **Decide the shape.** `EffectCellId`'s documented purpose is narrow: outdoor
   dat stabs that keep a null render parent while retail still gives them an
   outdoor landcell. Live/interior entities were explicitly meant to use
   `ParentCellId`. Preferred fix, in retail's direction: live entities stop
   populating `EffectCellId`, the stab case keeps it as the documented
   exception, and one owner writes the visibility cell that the effects path
   reads. If the audit shows live entities genuinely need it, the alternative
   is a single writer that maintains both — but never 12 independent writers
   against a field that wins.
4. **Divergence register.** The two-field split is an adaptation from retail's
   single cell. Add the row if none exists; delete it if step 3 collapses the
   split.

**Tests:** an entity crossing a cell boundary keeps its particles and lights
attached; an equipped/attached child keeps its parent-relative behaviour; the
outdoor dat stab case is unchanged.
**Gate:** focused App + complete suite, then a **user visual check** — a
monster with an active spell effect crossing a cell boundary, and a lit static
object, indoors and outdoors.

---

## S3 — #283: one owner for the world origin

Sequenced last of the three and immediately before C4 route 3, which touches
the same portal code.

1. **Prove or disprove reachability first.** With S1 landed, assert at the
   placement site that Runtime's frame center and App's `LiveWorldOriginState`
   center agree; run the portal/recall routes. If they never diverge in
   practice, the fix is a permanent invariant rather than a behaviour change —
   record that and stop. Do not restructure on a hypothesis.
2. **Retail evidence.** How retail rebases its landblock offsets across a
   teleport, and the ordering around `TAS_TUNNEL_CONTINUE` — the same
   sequence #280 already needs read. Read once, use twice.
3. **Fix shape.** Runtime owns the world frame; App projects it. Today
   `LiveWorldOriginState` is an independent owner with its own rebase edge.
   Make it a projection of Runtime's frame, so there is exactly one origin and
   the retirement-driven edge becomes a *publication* of that origin rather
   than a second decision. This is the same ownership move the campaign has
   already applied to entities, physics, and placement.
4. **Ordering invariant.** No placement may commit against an origin the
   render side has not adopted. Whether that is expressed as a gate or made
   structurally impossible falls out of step 3.

**Tests:** a teleport whose old-window retirement lags by many frames cannot
commit a placement against a mismatched origin; frame and origin rebase
together; ordinary movement rebases neither (already pinned by
`RuntimeWorldFrameTests`).
**Gate:** focused + complete suite, lifecycle/reconnect, and a **user visual
check** on repeated portal/recall arrivals with objects present.

---

## After S1–S3

Resume the original campaign order, unchanged:

1. **C4 routes 2–7** — ForcePosition, portal (with S3 landed), remote
   Create/Position, projectile correction, drops, pickup/parent/delete.
   Fold in #276 and #277 where their route becomes authoritative.
2. **#280** — retail destination prefetch, landed adjacent to route 3.
3. **C5** — delete superseded writers, complete suite, lifecycle/reconnect,
   nine-stop soak **on the final binary**, two-client observation, the #269/#278
   slope-glide check. Only then retire AP-1, AD-1, AP-131, and AD-60's legacy
   half.
4. **AP-22** — `ShadowShapeBuilder` as sole authority for authored Setup
   collision shapes.
5. **AD-10** — remote contact-plane projection through the real transition
   sweep.
6. Final movement/collision matrix; ledger, architecture, roadmap, milestones,
   memory, `CLAUDE.md`, `AGENTS.md`. Vendor Slice 5 resumes only after that.