acdream/docs/research/2026-08-03-c4-route-2-implementation-plan.md

# C4 route 2 — ForcePosition: implementation plan (2026-08-03)

Executes `docs/research/2026-08-03-c4-route-2-contract.md`. The contract is the
WHAT; this is the verified HOW. Every claim below was checked against source or
the named retail decomp in this session — do not re-derive them, and do not
contradict them without new evidence.

## 1. Retail truth (verified this session, not inherited)

`SmartBox::HandleReceivedPosition` @0x00453FD0
(`docs/research/named-retail/acclient_2013_pseudo_c.txt:92896`). The
FORCE_POSITION branch is the whole route:

```
if (arg2 == player && newer_event(player, FORCE_POSITION_TS, arg9))
{
    if (<force ts is not older>)
    {
        get_heading(player);
        Frame::set_heading(&dest, heading);      // 00454068 preserve OUR heading
        SmartBox::BlipPlayer(this, &dest);       // 00454074
        player->update_times[0] = arg7;          // 00454079 stamp POSITION_TS
        cmdinterp->SendPositionEvent();          // 00454091 ack
        return;                                  // 0045409d
    }
}
```

`SmartBox::BlipPlayer` @0x00453940 (line 92528) is:

```
distance = Position::distance(&player->m_position, dest);
CPhysicsObj::SetPositionSimple(player, dest, 1);     // 00453968
SmartBox::PlayerPositionUpdated(this, 0, distance);  // 00453976
```

`CPhysicsObj::SetPositionSimple` @0x005162B0 (line 284276) with `arg3 != 0`
builds `SetPositionStruct` with flags **`0x1012`** and calls
`CPhysicsObj::SetPosition`. `0x1012` decodes against
`src/AcDream.Core/Physics/PhysicsSetPosition.cs:63-76` as
`Teleport(0x002) | Slide(0x010) | SendPositionEvent(0x1000)` — byte-for-byte
`RuntimeAuthoritativePositionRouteClassifier.AuthoritativeTeleportFlags`
(`RuntimeAuthoritativePositionRouteClassifier.cs:198-200`). **The pinned
classifier route is confirmed correct; do not touch it.**

Three consequences that decide this slice:

### 1a. ForcePosition is a real SetPosition, not a snap

Retail runs the full transition with Teleport|Slide. Today's
`PlayerMovementController.BlipPosition`
(`src/AcDream.Runtime/Gameplay/PlayerMovementController.cs:1923-1937`) is
`_body.SnapToCell(...)` — no transition, no collision, no contact plane, no
shadow commit, no `FullCellId`/`PlacementCommitVersion` advance. Closing that
gap is the point of route 2.

### 1b. The force branch runs NO ConstrainTo

Every `CPhysicsObj::ConstrainTo` call in `HandleReceivedPosition` is at
0x00454272 (remote MoveOrTeleport tail), 0x0045418A (player teleport-newer
branch), and 0x004541EC (player ordinary branch). The force branch returns at
0x0045409D, **before all three**. The classifier already encodes this as
`ConstrainPhase: None`.

`BlipPosition` calls `RearmConstraintLeashAtCurrentPosition()` and its comment
cites *"retail 'Player, normal' branch"* — a branch `BlipPlayer` is not on.
That leash re-arm is an unbacked deviation on this route.

**Required:** the new route honours `ConstrainPhase: None` — no leash re-arm on
ForcePosition. Call it out explicitly in the commit message as a named
behaviour change with these addresses, and add it to the connected gate's watch
list (#167 was a leash bug; the user's live observation governs). Do not touch
`ArmConstraintLeashAtCommittedPlacement` (C3c/AD-42 first-entry) or the
teleport/`CommitPreparedPosition` callers — they are on branches that DO
constrain.

### 1c. Heading preservation already happens upstream — do not re-derive it

Retail replaces the destination heading with the player's current heading
BEFORE the SetPosition. Our accepted-position merge already does this via the
`forcePositionRotation` argument
(`RuntimeLiveEntitySessionController.cs:179`, App's
`_authorityGate.TryAcceptPosition(..., _playerController.BodyOrientation, ...)`
at `LiveEntityNetworkUpdateController.cs:1050-1052`). Verify it lands in
`record.Snapshot` before you build the route request; assert it in a test. The
seam must NOT apply a second heading substitution.

Also noted, NOT in scope: retail's `PlayerPositionUpdated(this, 0, distance)`
gates `set_viewer`/`LScape::update_viewpoint` on
`distance >= GetAutonomyBlipDistance` (0x004538C0-0x004538E2). We publish the
render root unconditionally. File it as a follow-up observation in the closeout
note; do not change it here.

## 2. Verified mechanism map

| Thing | Location | Note |
|---|---|---|
| Route classifier (pinned, correct) | `RuntimeAuthoritativePositionRouteClassifier.cs:308` | one production consumer today: `RuntimeInitialCreateContinuationExecutor.cs:1948` |
| Begin | `RuntimeSetPositionState.TryBeginExclusiveAuthoredPlacement:1309` | no first-entry-only precondition |
| Prepare+submit+commit | `RuntimeSetPositionState.TryPrepareAndSubmitAuthoredPlacement:1658` → `PrepareMover:1522` → `SubmitPreparedPlacementCore:2777` → `Engine.SetPosition:2962` → `CommitCanonical:4411` | |
| Deferred wake | `CommitCollisionGeneration:3973` → `RetryDeferred:4192` → `CommitCanonical:4374` | drives parked operations without our help |
| **The template to mirror** | `RuntimeFirstEntryDriveController.TryCompleteContinuationPlacement:280-380` | begin/prepare/submit + outcome switch + projection acknowledgement |
| Runtime world frame | `RuntimePhysicsState.ObserveLocalWorldFrame:535`; `resolveWorldOffsetFromRuntimeFrame` param | **use it** — satisfies contract §7, one conversion site |
| App projector (already exists) | `LiveEntityRuntime.TryApplyRuntimePlacementPlace` (`LiveEntityRuntime.cs:1231+`) | writes `entity.SetPosition(projection.WorldPosition)`, `entity.Rotation`, `entity.ParentCellId = token.ExactCellId`, `RebucketLiveEntity` — from the COMMITTED result |
| App sink | `RuntimePlacementPresentationSink.TryApply:67` / `TryPublishPlace:162` | |
| Headless sink | `HeadlessRuntimePlacementProjectionSink` | |

**This is the crux:** `TryApplyRuntimePlacementPlace` already performs, from
canonical committed state, exactly the four writes the generic tail performs
from raw wire (`LiveEntityNetworkUpdateController.cs:1264-1281`). Deleting the
generic tail for the local player is a straight substitution of the committed
result for the wire guess — not a loss of function.

## 3. The two duplicate authorities to delete

**Graphical** — `src/AcDream.App/Physics/LocalForcePositionTransaction.cs`
(whole file) and its single call site
`LiveEntityNetworkUpdateController.cs:1113-1129`; plus the generic tail
`:1264-1282` **for the local player only** (remotes still need it — that is
route 4).

**Headless** — `RuntimeLiveEntitySessionController.OnPositionUpdated:217-231`'s
`ProjectPosition(..., isLocalPlayer: true, ForcePosition)` +
`SendImmediatePosition` pair, and
`HeadlessSessionWorldProjection.BlipLocalPlayer:707-727`. Headless has no
`WorldEntity` in this path, so it has only the first duplicate — but it is a
duplicate all the same, and contract §4 requires both hosts on the identical
Runtime path.

## 4. Design

New Runtime type, modelled directly on `RuntimeFirstEntryDriveController`:

**`src/AcDream.Runtime/Session/RuntimeAcceptedPositionDriveController.cs`**

Constructor takes the same collaborators that controller takes
(`_entityObjects`, `IPreparedCollisionSource`, the simulation clock,
`LocalPlayerOutboundController`, the session accessor, the local-player
identity). Follow that file's ctor and null-validation style exactly.

### Entry point

```csharp
internal RuntimeAcceptedPositionExecutionStatus TryExecuteAcceptedLocalPosition(
    RuntimeEntityRecord record,
    in WorldSession.EntityPositionUpdate update,
    PositionTimestampDisposition disposition,
    in AcceptedPhysicsTimestamps timestamps,
    ushort previousTeleportSequence);
```

**Scope this slice to ForcePosition on the live local player.** Any other
disposition, any other entity kind, and the not-applicable cases below return
`NotApplicable`, and the caller then does exactly what it does today. Route 2
must not perturb routes 1/3/4.

Return `NotApplicable` when:
- `disposition is not PositionTimestampDisposition.ForcePosition`;
- the record is not the local player;
- `record.PhysicsBody is null` (no canonical body → nothing to place);
- **an initial-Create residence is still active for the record.** Route 1 owns
  it: the executor already retains the Position as a tail action
  (`RuntimeInitialCreateContinuationExecutor.ApplyPositionAction`) and already
  carries `SendPositionImmediately` (`:717`, `:2576`). Confirm that ack
  actually fires on that path and say so in the closeout; if it does not, that
  is a route-1 defect — file it, do not paper over it here.

### Body

1. Build `RuntimeAcceptedPositionRouteRequest` deriving every field the way
   `RuntimeInitialCreateContinuationExecutor.ApplyPositionAction:1907-1946`
   derives it. Specifically: `HasContact = update.IsGrounded` (the wire bit,
   never a live body query); `HasAnimations` from
   `Snapshot.MotionTableId ?? Snapshot.Physics?.MotionTableId` non-zero;
   `CommittedCellId = record.FullCellId`; `PlacementFacts` from
   `record.FinalPhysicsState` and `Snapshot.SetupTableId is not null`;
   `Source = PositionEvent`; `UsePositionFromServer` and `PlayerDistance` from
   the same Runtime owners C0 established (`RuntimeCharacterState.AutonomyLevel
   != 2`; the live movement controller). Read C0's notes in
   `docs/plans/2026-08-02-placement-cutover.md` first.
2. `ClassifyAcceptedPosition`. Not accepted → stamp-only, mirroring
   `:1950-1984`; return without ack.
3. `TryBeginExclusiveAuthoredPlacement(record, record.PositionAuthorityVersion,
   route.OperationKind)`. Invalid token → `Contention`; the caller retries on a
   later packet. Do NOT invent a retry loop.
4. `TryPrepareAndSubmitAuthoredPlacement(record, token, route.OperationKind,
   route.SetPositionFlags, _collisionSource, _clock.SimulationTimeSeconds,
   out outcome, resolveWorldOffsetFromRuntimeFrame: true)`.
5. Outcome switch, mirroring `TryCompleteContinuationPlacement:340-380`:
   - `CommittedHostAcknowledgementPending` → §4a reconcile, then §4b ack.
   - `DeferredCell` → §4c.
   - anything else → forget + `PublishCancellation`; **no ack**.

### 4a. Post-commit local reconciliation

`CommitCanonical` writes the body, contact plane, `FullCellId`,
`PlacementCommitVersion`, shadow membership and the spatial acknowledgement. It
does NOT do the three controller-local things `BlipPosition` also did. Add ONE
new method to `PlayerMovementController` next to `BlipPosition`, e.g.
`CommitCanonicalForcePositionFrame()`, that:

- resets `_prevPhysicsPos`/`_currPhysicsPos` to the committed body position
  (kills the render-lerp residual);
- calls `UpdateCellId(_body.CellPosition.ObjCellId, "force-position")` so the
  render root chokepoint `PhysicsEngine.UpdatePlayerCurrCell` still runs;
- does **not** re-arm the constraint leash (§1b);
- does **not** write the body — the canonical commit already did.

Then `BlipPosition` has no remaining caller: **delete it** along with
`HeadlessSessionWorldProjection.BlipLocalPlayer`. If a test is its only other
caller, the test moves to the new path — do not keep the method alive for
tests.

### 4b. The ack

`SendPositionImmediately` is an OUTPUT of the committed route. Fire
`LocalPlayerOutboundController.SendImmediatePosition(session, controller)`
only after §4a, only when `route.SendPositionImmediately`, and only once. This
is the named behaviour change the contract calls out: today the packet leaves
before any commit and the trailing `isCurrent()` cannot recall it.

### 4c. Deferred cell

`DeferredCell` means the destination landblock's collision generation is not
ready; the operation parks and the existing `CommitCollisionGeneration` wake
resubmits and commits it. The ack must still fire exactly once, after that
commit.

Retain the pending ack keyed by the placement token, and resolve it on a pump
`Advance()` called from the SAME two host sites that already call
`RuntimeFirstEntryDriveController.DriveAll()` —
`LiveEntityHydrationController.cs:405` (graphical) and
`HeadlessSessionWorldProjection.cs:571,594,612` (headless). Find the existing
read-only way to ask "did this token's operation commit / is it gone" before
adding anything; only add a minimal internal query to `RuntimeSetPositionState`
if none exists. Fire once on the commit transition; drop the pending ack on
cancellation, supersession, entity teardown, generation change and reset, and
fold its count into the ownership ledger / `IsConverged` so a leaked pending
ack cannot hide.

Also consume the parked `Withdraw` at the FIFO head exactly the way
`TryCompleteContinuationPlacement:351-365` does, if and only if it is ours.

### 4d. Host cutover

- **App** `LiveEntityNetworkUpdateController.OnPosition`: replace the
  `LocalForcePositionTransaction.Apply` block with the Runtime call. When the
  status is anything other than `NotApplicable`, return before the generic tail
  — App projects the committed result through the existing placement sink. Keep
  every currency re-check that is still meaningful. Inject the Runtime seam the
  way the class already borrows Runtime owners (`_localPlayerOutbound` is the
  precedent); do not add a service locator or a window back-reference.
- **Headless** `RuntimeLiveEntitySessionController.OnPositionUpdated`: replace
  the `ProjectPosition(isLocalPlayer: true, ForcePosition)` +
  `SendImmediatePosition` pair with the same call. Leave the `Apply`-
  disposition `OfferTeleportDestination` and `TryCompletePortal` alone — route 3.
- Delete `LocalForcePositionTransaction.cs`.

## 5. Non-negotiables

- Root causes only. No timeout, grace period, suppression flag,
  catch-and-swallow, duplicated placement writer, or test-only bypass.
- Never `git add -A` / `git add .` / `git reset --hard` / `git checkout -- <path>`.
- Do not weaken an existing assertion to make a test pass. If a fixture models
  the old duplicate-write behaviour, re-model it on the committed projection.
- Cite retail as `named symbol @address` (+ the pseudo-C line) in every comment
  on ported behaviour.
- Update `docs/ISSUES.md` and
  `docs/architecture/retail-divergence-register.md` in the SAME commit as the
  behaviour change. AP-131 is **not** retired here — its named legacy Position
  caller is route 4.

## 6. Acceptance

1. Focused Runtime tests for the seam: force route classification; ack strictly
   after commit; ack exactly once; no ack on a rejected/cancelled operation;
   the displaced-authority case that `LocalForcePositionTransaction`'s trailing
   `isCurrent()` covered today; the `DeferredCell` → wake → commit → single ack
   sequence; heading preserved; leash NOT re-armed; `NotApplicable` while a
   first-entry residence is active.
2. App tests proving the generic tail no longer double-writes the local player,
   and that the committed projection is what moves the render entity.
3. Headless tests proving the identical Runtime path.
4. `dotnet build -c Release` clean.
5. **Complete Release solution suite green — not a focused subset.** Baseline
   **10,844 passed / 4 skipped / 0 failed**. Any deviation is a regression
   introduced by this work.
6. Connected (user-gated): a server-forced correction leaves the player at the
   corrected position, heading preserved, exactly one outbound
   `AutonomousPosition`, no double-apply, and no leash misbehaviour after the
   correction.