# Handoff: #184 Slice 2 — extract `RemotePhysicsUpdater` (2a) + unify the player/NPC remote fork (2b)

**Date:** 2026-07-07 · **Status:** ✅ DONE — 2a shipped `e1ac56cc` (byte-exact extract), 2b shipped
`ddb5a967` (fork collapse), **visual gate PASSED 2026-07-08 (user: "Looks good") → #184 FULLY CLOSED.**
A 3-lens adversarial review (workflow `wf_b163315b-14f`) corrected the plan below in one place: the
player gate is NOT "players de-overlap" — retail lets two non-PK players WALK THROUGH each other (PvP
exemption), so the remote-player mover was given `IsPlayer|EdgeSlide` (§4-adjacent). 2b's player win is
that players now collide with monsters + terrain + walls (Path A skipped all collision) while still
passing through each other. See the physics digest banner + ISSUES #184 for the shipped writeup.

**Read these first (in order):**
1. This handoff — the plan, the exact sites, the #40 verdict, the seams.
2. Physics digest banner (SSOT): `claude-memory/project_physics_collision_digest.md` — the #184
   Slice 1 + Slice 3 banners (what shipped, the shadow-follows-resolved mechanism, the placement-snap).
3. Design spec: `docs/superpowers/specs/2026-07-07-remote-creature-deoverlap-design.md` §2.5 (the
   original Slice 2/3 staging) + §5 (register bookkeeping — the #40 retirement).
4. Research behind this handoff: workflow `wf_c6a2e2b9-833` (3 read-only Opus agents: #40 risk /
   extraction design / unification correctness). Findings distilled here.

---

## 0. Where #184 stands (what shipped, what this is)

The reported symptom — packed **monsters** interpenetrating (retail barely overlaps on the SAME ACE)
— is **FIXED and visually gated**. Two commits on `claude/vigorous-joliot-f0c3ad`:
- `37a94e1f` — **Slice 1**: NPC `UpdatePosition` → retail `MoveOrTeleport` **placement-snap** +
  grounded movement driven by the interp **catch-up** feeding the kept `ResolveWithTransition` sweep
  + **shadow-follows-resolved** (`SyncRemoteShadowToBody`, the load-bearing de-overlap persistence).
- `f51c1dff` — **Slice 3**: the sweep's mover sphere is **Setup-derived** (`GetSetupCylinder` =
  `setup.Radius`/`setup.Height` × ObjScale) so big/small monsters de-overlap at true radii.

Both gates passed (crowd de-overlap; large-monster spacing). Core 2621 / App 741 green.
`RemoteDeOverlapMechanismTests` (4 tests) proves the mechanism in Core.

**Slice 2 is the last piece — it is FAITHFULNESS + STRUCTURE, not a bug fix.** It does two things:
- **2a (behavior-neutral):** extract the per-remote dead-reckoning update out of the >10k-line
  `GameWindow.cs` into a testable `RemotePhysicsUpdater` (Code Structure Rule 1).
- **2b (behavior change, GATED):** collapse the **two-path fork** — "Path A" (grounded PLAYER
  remotes) currently OMITS the sweep; make it run the SAME catch-up+sweep+shadow-follows-resolved as
  "Path B" (NPCs), so **packed players de-overlap too** and the "#40 remotes skip the transition"
  adaptation is retired. The user-visible payoff is minor (players rarely pack); the real win is
  retail-faithfulness (retail's `UpdateObjectInternal` has NO player/remote fork).

---

## 1. THE #40 VERDICT — DEAD (high confidence). 2b is SAFE. (do NOT re-investigate)

Path A skips the sweep because of a comment citing **issue #40** ("running our sweep on tiny
per-frame queue catch-up deltas amplifies micro-bounces into visible position blips — staircase +
flat-ground blips", `GameWindow.cs:10392-10399`). The research settled that #40 is a **stale
observation** and adding the sweep to Path A will NOT reintroduce it:

- **The decisive cross-check:** Path B (NPCs) ALREADY runs the EXACT #40-feared configuration in
  production TODAY — clears `Body.Velocity`, drives translation purely from
  `RemoteMotionCombiner.ComputeOffset` catch-up (the SAME driver Path A uses), and calls
  `ResolveWithTransition` every tick on those tiny deltas. Path B's own comment says so:
  *"Matches Path A's grounded model (:10113); clearing velocity mirrors Path A (:10125)"*
  (`GameWindow.cs` ~:10489). It does NOT blip — #170/#171/#184 gates all passed.
- **Empirical proof in Core:** `RemoteDeOverlapMechanismTests.ConvergingCreatures_RealInterpLoop_DeOverlapsAndAbsorbsTheStallBlip`
  drives the REAL `ComputeOffset → InterpolationManager.AdjustOffset` catch-up (incl. the
  `fail_count>3` blip-to-tail) for 600 ticks and asserts every tick's net move stays < 0.30 m — the
  sweep absorbs the stall-blip.
- **#40 predates the sweep rebuild:** #40 closed **2026-05-05** (commit `40d88b9`), against the
  ORIGINAL BSP-layer sweep. Every relevant sweep-internals rebuild landed AFTER: the CSphere
  collision-family port (#182, `96ae2740`, 2026-07-07), the #137 corridor sliding-normal/phantom-wall
  fixes, the L.2.3 step-height series, the #170/#171 chase/sticky work. #40 is against a sweep that
  no longer exists.
- **The slope-staircase half is STRENGTHENED, not reintroduced:** Path A already samples
  `terrainNormal` and passes it to `ComputeOffset` (the 2026-05-05 slope-staircase fix, `:10287`);
  adding the sweep additionally provides retail terrain-Z snap along the slope.

**Cheapest way to confirm #40 is dead BEFORE the visual gate (do this in 2b):** extend
`RemoteDeOverlapMechanismTests` with a converging PLAYER-config pair (same `RealInterpLoop` shape,
player body/flags) and assert the same `maxSpike < 0.30`. If it passes, #40 is dead in code.

---

## 2. The plan — 2a FIRST (fork-preserving), then 2b (unify, gated)

**Order matters: 2a before 2b.** Do 2a as a strictly fork-preserving **pure refactor** (the Path A /
Path B fork stays inside the new class, byte-for-byte), verify suites green (behavior-neutral, NO
gate needed — the two passing gates remain a clean baseline), commit. THEN do 2b as a separate diff
that merges the fork inside the now-clean class, with its own test + review + visual gate. Combining
them would blow away the clean before/after baseline and make a gate failure unattributable.

⚠️ **2b is NOT a trivial "delete Path A."** Path A is *mostly* subtractive but has small
player-specific bits Path B lacks (see §4). Merging by editing Path B's shared logic risks
regressing NPCs — reconcile carefully.

---

## 3. Slice 2a — the extraction (behavior-neutral)

### 3.1 The seam (all line numbers are HEAD `f51c1dff`, current)

- **Extract:** the POSITION block of the `foreach (var kv in _animatedEntities)` loop in
  `TickAnimations` (`GameWindow.cs`): from `uint serverGuid = ae.Entity.ServerGuid` (~:10152)
  through the sticky-lease tail `rm.Host?.PositionManager.UseTime();` (~:10873), gated by
  `if (ae.Sequencer is not null && serverGuid != 0 && serverGuid != _playerServerGuid &&
  _remoteDeadReckon.TryGetValue(serverGuid, out var rm) && rm.LastServerPosTime > 0)` (~:10167-10182).
- **DO NOT extract** the ANIMATION/RENDER half below ~:10876 (seqFrames/`Sequencer.Advance`,
  `MotionDoneTarget` bind, `ConsumePendingHooks`, PARTSDIAG, MeshRef rebuild). It drives the
  sequencer + hook router + rendering and must stay in `GameWindow`.

### 3.2 Signature + deps

- `RemotePhysicsUpdater.Tick(RemoteMotion rm, AnimatedEntity ae, float dt, int liveCenterX, int liveCenterY)`.
  Per-call state is exactly `rm`, `ae`, `dt`; `serverGuid` derives from `ae.Entity.ServerGuid`;
  `_liveCenterX/Y` are passed per-call (they change on streaming recenter — DO NOT snapshot them in
  the constructor).
- **Constructor deps** (all pure services, no GL/render coupling): `PhysicsEngine _physicsEngine`,
  `PhysicsDataCache _physicsDataCache`, and the live `IReadOnlyDictionary<uint, EntitySpawn>
  _lastSpawnByGuid` (a shared reference GameWindow mutates; the updater only reads it, for
  `GetSetupCylinder`).
- **Location:** `src/AcDream.App/Physics/RemotePhysicsUpdater.cs` (App-layer — it needs the App-owned
  `RemoteMotion`/`AnimatedEntity` types and the helpers). Register the file if a new folder.

### 3.3 Helpers to move (with the block)

| Helper | Site | How it moves |
|---|---|---|
| `IsPlayerGuid` | `:1032` static `(guid & 0xFF000000u)==0x50000000u` | static on the updater (or a tiny shared static) |
| `ApplyPositionManagerDelta` | `:4607` static, pure (body+delta) | static on the updater |
| `TickRemoteMoveTo` | `:4864` body is just `rm.Movement.UseTime();` | inline into the updater |
| `GetSetupCylinder` | `:4572` deps `_physicsDataCache` + `_lastSpawnByGuid` | move to the updater (constructor deps) |
| `SyncRemoteShadowToBody` | `:4633` deps `_liveCenterX/Y` + `_physicsEngine.ShadowObjects` | move to the updater; take `liveCenterX/Y` as args (already the plan for `Tick`) |
| `ApplyServerControlledVelocityCycle` | `:5570` Path-B-only anim-cycle; Core calls only (`ae.Sequencer`, `IsPlayerGuid`, `ServerControlledLocomotion.PlanFromVelocity`) | move verbatim for behavior-neutral 2a (candidate to relocate to the anim half later) |

### 3.4 ⚠️ The one seam WRINKLE — the two helpers are ALSO called outside the DR loop

- `GetSetupCylinder` is also called by `StickToObjectFromWire` (~:4662) and other moveto/sticky
  sites (`:4441-4442, :4492, :4662, :13820-13821, :13872`).
- `SyncRemoteShadowToBody` is also called by the NPC UP-branch tail in `OnLivePositionUpdated`
  (~:6156, the Slice-1 first-UP/no-Sequencer shadow sync).

**Decision to make in 2a:** either (a) move both into `RemotePhysicsUpdater` and have `GameWindow`
call them back through the `_remotePhysicsUpdater` instance from those other sites (clean ownership,
but a general `GetSetupCylinder` living on the updater is a slightly odd home), OR (b) keep
`GetSetupCylinder` on `GameWindow` and pass it to the updater as a `Func` dep, moving only
`SyncRemoteShadowToBody`. **Recommendation:** (a) — `GameWindow` holds `_remotePhysicsUpdater` and
calls `_remotePhysicsUpdater.GetSetupCylinder(...)` / `.SyncRemoteShadowToBody(..., _liveCenterX,
_liveCenterY)` from the ~3 other sites. It's the cleanest single-owner.

### 3.5 2a acceptance
- `GameWindow.cs` shrinks by the position block (~700 lines) → `Tick(...)` call.
- Suites green (Core 2621 / App 741), NO behavior change, NO gate.
- The fork (`if (IsPlayerGuid(serverGuid) && !rm.Airborne)`) is PRESERVED inside the updater.

---

## 4. Slice 2b — unify the fork (behavior change, GATED)

### 4.1 The delta: make grounded PLAYER remotes run the sweep

Path A (grounded player remotes, `GameWindow.cs:10194-10429`) is Path B minus:
1. `ResolveWithTransition` (the sweep) — "Step 4b INTENTIONALLY OMITTED" (`:10392-10399`).
2. `SyncRemoteShadowToBody` (shadow-follows-resolved).
3. the `#173` velocity bounce + the airborne landing detection (both no-op for a grounded body).

But Path A ALSO has bits Path B does NOT — **these must survive the merge (do not regress players
OR NPCs):**
- **Omega fallback:** Path A applies `ObservedOmega ∥ seqOmega` (`:10351` — falls back to the
  sequencer's synthesized omega when `ObservedOmega==0`). Path B applies `ObservedOmega` ONLY.
  Reconcile so players keep the seqOmega fallback WITHOUT changing NPC omega behavior (do NOT just
  bolt the fallback onto Path B's shared omega — verify against NPC turning first).
- **Compose fallback:** Path A has `else { rm.Body.Position += offset; }` when `rm.Host` is null
  (`:10318-10321`). Path B's equivalent is `else if (!rm.Airborne) { rm.Body.Position += ComputeOffset(...); }`.
- **Diagnostics:** Path A's `[SLOPE]` (ACDREAM_SLOPE_DIAG) and `[OMEGA_DIAG]`/`[VEL_DIAG]`
  (ACDREAM_REMOTE_VEL_DIAG) blocks — keep or fold as desired (diagnostic-only).
- Path B's grounded stale-velocity anim-stop is gated `!IsPlayerGuid` (`ApplyServerControlledVelocityCycle`)
  — so it already no-ops for players; leave that gate.

**Cleanest merge (do it inside the extracted class):** one grounded path = `ComputeOffset` catch-up
(seed the sticky delta frame) → omega (`ObservedOmega ∥ seqOmega`) → `calc_acceleration` +
`UpdatePhysicsInternal` → the sweep → store resolved → `SyncRemoteShadowToBody` → `#173` bounce →
landing. Players and NPCs differ only in the `!IsPlayerGuid`-gated anim-cycle stop and the diagnostics.

### 4.2 ⚠️ THE COUPLED SHADOW-SYNC EDIT (research finding 9 — do NOT miss this)

Slice 1 made the per-UP raw-worldPos shadow sync in `OnLivePositionUpdated` (~:5699) **PLAYERS-ONLY**
(NPC shadows follow the resolved body via `SyncRemoteShadowToBody` in the tick). If 2b now gives
players the tick sweep + `SyncRemoteShadowToBody`, then the `:5699` players-only raw-pos sync becomes
the STALE one — packed players would de-overlap in-tick but re-snap-to-overlap once per UP. **Retire
/ unify `:5699`** so players also get resolved-body sync (mirror how Slice 1 handled NPCs: consider a
player UP-branch tail `SyncRemoteShadowToBody` for the first-UP / no-tick case, and remove or
airborne-gate the `:5699` raw sync). This edit is OUTSIDE the DR loop — that is exactly why 2b is its
own reviewed diff.

### 4.3 Register bookkeeping (in the 2b commit)
- **Retire the "#40 remotes skip the transition / server already collision-resolved" adaptation** —
  the register row + the `GameWindow.cs:10207-10208` premise (ISSUES.md #40 anchors ~:4536/:4551).
  Cite that Path B already carries the sweep with passing gates.
- Any new adaptation the merge introduces (e.g. the omega-fallback reconciliation) gets its row.
- Move the AP-86 note about `:5699` being players-only if that changes.

### 4.4 2b test + gate
- **Test first:** the converging PLAYER-pair `RealInterpLoop` test (§1) — proves no #40 blip + players
  de-overlap, in Core, before the gate.
- **Visual gate (the acceptance test):** (a) a player remote running up/down a hill — no slope
  staircase; (b) two player remotes packed side-by-side on flat ground — steady-state XY unchanged
  (no blip) + they de-overlap; (c) a regression pass on remote walk/run/jump/land/turn — UNCHANGED.
- Suites green (Core / App).

---

## 5. Preserve-list (regression watch — the frozen R4/R5 arc)
- The sweep + transition internals, the shadow registry, `CollisionExemption` — untouched.
- Sticky melee #171 (the `snapSuppressedByStick` gate + `StickyManager` overwrite of the seeded
  frame) — survives; it's in Path B and the shared compose.
- The airborne remote path (already goes through Path B via `IsPlayerGuid && Airborne`) — 2b changes
  only the GROUNDED player case; airborne is already swept.
- The omega integration (both `ObservedOmega` and the seqOmega fallback for players).
- The `node_fail_counter` blip watchdog.
- Slices 1 + 3 (shadow-follows-resolved, placement-snap, Setup-derived sphere) — the base; unchanged.
- The `#42` self-collision self-skip (`movingEntityId: kv.Key`) — confirm it's passed on the unified
  player path (Path A currently does NOT call the sweep, so this is new for players).

## 6. Pointers
- Research: workflow `wf_c6a2e2b9-833` (this session) — the #40 verdict + extraction design +
  unification correctness, with file:line evidence.
- Slices 1/3 commits: `37a94e1f`, `f51c1dff`. The #184 arc plan/design:
  `docs/superpowers/specs/2026-07-07-remote-creature-deoverlap-design.md`;
  `docs/research/2026-07-07-remote-creature-deoverlap-handoff.md`.
- Digest (SSOT + the failed-attempt lesson): `claude-memory/project_physics_collision_digest.md`.
- Tests: `tests/AcDream.Core.Tests/Physics/RemoteDeOverlapMechanismTests.cs` (extend with the
  player-config `RealInterpLoop`).
- The register: `docs/architecture/retail-divergence-register.md` (retire #40; AP-86/AP-87 are the
  #184 rows; TS-46 is the sphere-scalar residual).