acdream/docs/research/2026-08-03-c4-route-4a-contract.md

C4 route 4a — remote steady-state Position: pinned contract (2026-08-03)

Route 4 split into 4a/4b by user direction after scoping put the whole route at 1,500-2,500 lines against a ~400 budget. Scoping: 2026-08-03-c4-route-4-scoping.md.

4a is the steady state: the two classifier branches that perform NO SetPosition. Everything that parks, teleports, or snaps is 4b.

Scope — exactly two classifier branches

RuntimeAuthoritativePositionRouteClassifier.ClassifyAcceptedPosition (:393-472), remote/projectile arms:

Branch	Condition	Runs SetPosition?	In 4a?
NoPositionOperation	!effectiveContact (wire IsGrounded == false)	no	YES
Interpolate	contact, PlayerDistance < 96 m	no	YES
SetPositionSimple	contact, PlayerDistance >= 96 m	yes	no — 4b
SetPosition	TeleportAdvanced or CommittedCellId == 0	yes	no — 4b

Because neither 4a branch performs a placement, 4a has no deferred-cell park, no service-window guard, no allocation exposure, and no interaction with Forget-on-every-accepted-Position. That is the entire reason for the split; do not drag any of it in.

Staged cutover — the one sanctioned dual path

4a routes the two no-placement branches through the new Runtime seam and leaves the other two on the legacy App path until 4b. This is a staged cutover, not a duplicate authority, and it is only sanctioned under these conditions:

1. The discriminator is the CLASSIFIER ITSELF, not a heuristic, a flag, or a guess. One classification, one owner, mutually exclusive by construction.
2. For a classification 4a owns, the legacy path must not run at all — not partially, not "just the render write". Route 2's original defect was exactly a second writer running after the canonical one.
3. The fallback is temporary and 4b deletes it. Record that in the code comment at the branch point, with a pointer to this contract.

If you find yourself needing a condition beyond "what did the classifier say", STOP and report — that means the seam is wrong.

Retail truth (verify each yourself; do not trust this table)

CPhysicsObj::MoveOrTeleport @0x00516330 (pseudo-C 284304):

• Airborne no-op @0x0051638E / @0x0051636D: arg4 == 0 (the wire has_contact bit) -> return 0. Nothing is written at all.
• Near interpolate @0x005163AF: player_distance < 96f -> InterpolateTo(arg2, IsMovingTo()). No body write.
• player_distance is retail's own field — distance to the local player.

SmartBox::HandleReceivedPosition @0x00453FD0, remote branch:

• unset_parent @0x00454129 unconditional; SetPlacementFrame @0x00454142 gated on !HasAnims.
• ConstrainTo @0x00454272 runs AFTER MoveOrTeleport returns nonzero, anchored to &arg2->m_position — the object's own position read live, i.e. POST-move. It does not run when MoveOrTeleport returned 0 (the airborne no-op).

The two divergences 4a must fix

D1 — the NPC airborne branch ignores the wire bit. LiveEntityNetworkUpdateController.cs:1819-1823 hard-snaps Body.Position/Orientation for NPCs and branches on the client-tracked rmState.Airborne flag, never consulting update.IsGrounded. Retail writes nothing. Player remotes already behave correctly (:1590-1599); NPCs do not. No register row exists.

D2 — ConstrainTo is armed before the operation, unconditionally. :1522-1529 arms it ahead of the branch, so it fires on the airborne no-op retail skips and anchors to the PRE-move position. Retail arms it after, only on a nonzero return, anchored post-move. No register row exists.

(The third divergence — ConstrainTo never armed on the remote teleport branch — is on a 4b path. Leave it; 4b owns it.)

Duplicate authorities 4a deletes

Only the parts reachable from the two 4a branches:

• The generic tail's remote RENDER-POSE writes (entity.SetPosition / ParentCellId / Rotation) for a remote whose classification is Interpolate or NoPositionOperation.

  CORRECTED 2026-08-03 (review finding R1, 2026-08-03-c4-route-4a-review-findings.md). This bullet originally also listed RebucketLiveEntity, and said the result "must reach the render entity through the existing placement-projection sink instead — the same substitution route 2 made." That instruction was copied from route 2 and does not transfer: route 2 performs a placement and therefore has a committed receipt to project, while NEITHER 4a branch performs a placement, so nothing substitutes for the bucket transaction. The rebucket keeps running for both 4a classifications. It is the only site that moves an ordinary moving remote's draw bucket, commits its canonical FullCellId, and recovers a pending bucket promotion (GpuWorldState, the 2026-07-03 invisible-player fix); deleting it produced the #184-class invisible-but-solid creature through a different door.

• The player-remote near/far routing at :1653-1702 and the NPC copy at :1826-1871 — the near half only. Each has its own duplicated copies of MaxPhysicsDistance = 96f and BodySnapThreshold = 4f; the far half stays until 4b.

• The airborne no-op blocks at :1590-1599 (player) and :1819-1823 (NPC).

• The unconditional ConstrainTo at :1522-1529.

Do NOT touch RemoteTeleportController, RemoteTeleportPlacement, or the remotePlacementRequired path — all 4b.

Load-bearing acdream additions that must survive

AP-87 (retail-divergence-register.md:242) — the bodyToTarget > 4 m and !willBeDrTicked snap conditions on the near branch are NOT in retail and NOT in the classifier. They are load-bearing: they prevent the #184 invisible-but-solid monster. Either carry them explicitly as an acdream policy layer over the retail classification, or retire them with live evidence and the register row deleted in the same commit. Silently dropping them by delegating to the classifier is the failure mode. Say which you chose.

TS-44 (:1792-1801) — sticky-melee suppression of the NPC snap. Same rule.

Contract

1. One Runtime owner executes the accepted remote Position for the two 4a classifications; App projects the result.

2. Both hosts drive the identical Runtime entry point.

3. The interpolation queue (RemoteMotion.Interp) stays the owner of near motion — 4a routes to it, it does not replace it. All of it is already in Runtime (J5.5); no assembly boundary is crossed.

4. Stale sequences, GUID reuse, incarnation change, and generation change cannot commit old state. N entities, so per-entity currency — route 2's _pending was one slot and RetainPending threw on a second; that shape does not transfer.

5. The airborne branch writes NOTHING (retail returns 0). Not the body, not the render entity, not the cell.

   AMENDED 2026-08-03/04 (review finding R4). As shipped, the branch retains exactly two acdream bookkeeping writes — rmState.CellId and LastServerPos/LastServerPosTime — on both arms. These are not part of retail's model (retail's MoveOrTeleport has no catch-up sweep and no staleness timer to keep alive), and dropping them would break the per-tick free-fall sweep and the staleness timer respectively. Verified NOT a canonical cell commit for ordinary remotes: RemoteMotion.CellId only delegates to RuntimePhysicsState when _canonicalCellWriter is bound, which is projectiles-only, and projectiles return earlier. Recorded as register row AP-135. Everything else the branch used to do — body pose, queue, leash, render entity, shadow publish, and the velocity-derived animation cycle — is genuinely skipped.

6. ConstrainTo moves to after the operation, anchored post-move, and does not run on the airborne branch.

7. No behaviour change to the far, teleport, or cell-less branches.

Acceptance

• Focused Runtime tests for both branches, per-entity currency, and the AP-87 / TS-44 decision.
• App tests proving the generic tail no longer double-writes a remote on a 4a classification — behavioural, not a source-text pin. Route 2's equivalent was source-pinned and that gap is filed as #292; do not repeat it.
• Complete Release suite green. Baseline at the time of writing: 10,904 passed / 4 skipped / 0 failed. Known flake #302 (PortalProjectionTests.ClipToRegion_FrameOwnedStore_ReusesExactResultArray, ~1 in 6) — re-run, do not chase.
• Connected (user-gated), and unlike route 2 this is trivial: stand still, have a second character walk and run in a circle 5-15 m away, turning in place. Motion must be continuous and smooth with no per-packet stepping. Then have them jump and jump off a ledge — a clean parabola, clean landing, no mid-air correction, and critically no invisible-but-solid body (the #184 / AP-87 signature). Then pull a drudge, let it chase, melee it, let it die.
• Divergence ledger: D1 and D2 retired by fix in the same commit. AP-131 stays. AP-87 / TS-44 either stay with justification or are retired with evidence.
• Added 2026-08-03 (review finding R15). D1 makes ACE's wire IsGrounded newly load-bearing for NPC remotes: ACE emits it from TransientState & OnWalkable (PositionPack.cs:73), while acdream's NPC free-fall was gated on the client-tracked rmState.Airborne (set only by 0xF74E VectorUpdate or !Body.OnWalkable, never from the wire bit). A creature ACE reports as not-in-contact while the client believes it grounded now receives NO correction where the legacy routing pulled it. Push a monster off a ledge / pull one down a cliff, and confirm it falls and lands without hovering, without a mid-air correction, and without an invisible-but-solid body.

Budget

Stated up front so it can fail: 4a should be well under 400 production lines, because it adds no placement machinery — it routes two no-op classifications and deletes their duplicates. If it exceeds that, stop and report before continuing; that would mean the split did not actually isolate the cheap half and 4b needs re-planning too.