acdream/docs/research/2026-08-04-c4-route-4b-2-review-findings.md
Erik 7f1c1f5aa6 feat(physics): C4 route 4b-2 — remote far snap through the canonical placement
Flips the SetPositionSimple classification (contact, PlayerDistance >= 96 m) for
remotes onto 4b-1's drive controller and deletes both legacy far blocks, both
duplicated 96f/4f constant pairs, and both `?? Vector3.Zero` fabrications. The
4 m constant now exists exactly once. Teleport and cell-less stay legacy for
4b-3.

Retail: MoveOrTeleport @0x00516330's far branch runs StopInterpolating
@0x005163CB before SetPositionSimple @0x005163D9 and returns 1 @0x005163E8
regardless — the SetPositionError is discarded — so HandleReceivedPosition arms
ConstrainTo @0x00454272 post-move on commit AND on failure. The x87 parity
decode at @0x00516393-@0x0051639E puts exactly 96.0 on the far branch.
SetPositionSimple @0x005162B0 builds flags 0x1012 at @0x005162C4.

Non-commit outcomes still advance the body, because retail's SetPositionInternal
@0x00515BD0 commits the destination via store_position @0x00515CE2 when no cell
resolves. The partition is by STAGE, not heuristic, enforced by an exhaustive
switch: Refused/Contention/NotApplicable/RejectedPreparation store (the placement
never executed); Committed/Deferred/RejectedByPlacement do not (the engine ran
and refused, matching retail's non-storing returns @0x00515CB2 and @0x00515CD5).
Without this a refused far snap froze the remote with an emptied queue.

Also fixes a shipped defect this route made live: ParkDeferred's quiescence parks
withdrew the entity (InWorld=false, clock suspended, residency removed) and were
never restorable, while Forget(restoreCancelledPark: true) runs for every
accepted Position on every entity. The restorable decision now lives inside
ParkDeferred AFTER SnapToCell, reading body.CellPosition.ObjCellId — the value
RestoreParkWithdrawal actually restores at — against every live quiescence
rather than one minimum-OperationId token. The three pre-snap fields are hoisted
into locals because SnapToCell ends with InWorld = true. ParkCollisionResidents
passes restorableOnCancel: false explicitly; the plain unplaceable park is
provably unchanged. RestoreParkWithdrawal re-tests the prefix at restore time so
a retained route-2 park cannot re-admit into a prefix that began quiescing
during the park.

CanAttemptDestination is retained as an OPTIMISATION only, with the two Core
predicates it cannot reproduce written down at the pre-flight, plus the two
properties that depend on it staying there.

Four fix rounds and eight Opus reviews. The slice was fully green at 10,990,
10,997 and 11,004 while containing real defects — a frozen remote pinned as
correct by its own test, a fallback that over-wrote on the exact retail paths
that decline to store, and a park guard incomplete on two independent axes.

Register: AP-137 (leftover classifications take AP-87's catch-up; states the
cell-less enqueue-vs-place delta deferred to 4b-3, that RejectedData is applied
anyway, and the headless divergence), AP-138 (the refusable far placement),
AP-136 narrowed to match the relocation. #309's acceptance steps rewritten —
step 5 previously asserted a recovery the code does not perform — and gated on a
new ACDREAM_PROBE_PARK=1 signal so the check cannot pass while broken.

Suite 11,009 passed / 4 skipped / 0 failed against a measured 10,968 baseline.
The 10,973 figure recorded earlier was wrong and is corrected here.

Connected gate outstanding: the two-client far-snap walk and #309.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-04 07:55:56 +02:00

206 lines
12 KiB
Markdown

# C4 route 4b-2 — dual review FAIL + the pinned correction (2026-08-04)
Both mandated Opus reviews returned **FAIL**. Nothing is committed as final; the
work sits at WIP `dfd27896`.
Review A (retail faithfulness + deletions) confirmed **every retail citation**
independently, including the x87 parity decode proving exactly 96.0 takes the
FAR branch. The deletions are complete and exact, the "Do NOT touch" list was
respected, AP-87 was neither carried onto the far branch nor deleted from the
near branch, and the two-site `ConstrainTo` partition is exhaustive and disjoint.
Review B confirmed the `worldPos` decoy genuinely discriminates, both test
removals are real replacements rather than drops, and `OwnsFarSnap` is exact
against every classifier emission site. **Do not churn any of that.**
## The one root defect — everything else is downstream
**A refused / contended / rejected far snap leaves the remote frozen with an
emptied interpolation queue.**
`ApplyRemoteContactRouting` discards the status
(`LiveEntityNetworkUpdateController.cs:1002`, `_ = placementDrive.…`), while
`Interp.Clear()` has already run unconditionally on the route flag
(`RuntimeRemotePlacementDriveController.cs:485-487`). Three of five outcomes
move nothing: `Refused` (`:405`, `:624`), `Contention` (`:414`, `:588`),
`Rejected` (`:592`, `:630`). The body keeps its stale pose, the queue is empty,
and the next 5-10 Hz packet reproduces the state.
**Reachable, not theoretical.** The graphical service window is
`GpuWorldState.IsNearTier` — collision-published *right now*
(`GraphicalRemotePlacementServiceWindow.cs:89-90`) — with default near radius 4
(`GameWindow.cs:145`). A remote that is rendered but still streaming is refused
while genuinely beyond 96 m. `RetrySetupUnavailable` is reachable for any remote
whose prepared Setup collision has not resolved.
**Retail never does this.** The far branch always calls `SetPositionSimple`
@0x005163D9, and even when `SetPositionInternal` finds no cell it still commits
the destination pose — `store_position` @0x00515CE2, then
`GotoLostCell` @0x00515CF2 and `reenter_visibility` on cell arrival. That is the
finding AP-136 is built on. The deleted legacy block also always tracked. **The
shipped state is strictly further from retail than either.**
### Both reviewers' second MAJOR collapses into this one
Review B rated the `TryAdoptWireCellAfterRouting` arm-asymmetry MAJOR, arguing a
refused player far snap leaves `record.FullCellId` a landblock away from the
body and that `rmState.CellId` seeds the per-tick sweep — the #184
invisible-but-solid producer.
Review A found the same asymmetry and rated it MINOR with the mechanism:
`RebucketLiveEntity(update.Guid, p.LandblockId)` at `:1592` has **already**
committed the wire full cell to canonical
(`LiveEntityRuntime.cs:895-909`), and `RemoteMotion.CellId` reads through to
`record.FullCellId` for every bound remote (`RemoteMotion.cs:169-176` +
`RuntimePhysicsState.cs:965-984`). **Review A is right on the mechanism.** The
suppressed write is a no-op on refusal.
**Resolution: the cell/body divergence is real but is caused by the frozen body,
not by the suppression.** Fix the freeze and it disappears. Do not restructure
the suppression to chase it.
## The correction — pinned, not open for redesign
**On every non-commit outcome the far arm must still advance the body to the
accepted destination pose.** That is retail's `store_position`, and it restores
the tracking the deleted legacy block had.
Constraints on the fix:
- The status must stop being discarded at `:1002`.
- The service window stays an **optimisation**, not a correctness mechanism —
4b-1's review already ordered that framing corrected and it shipped
uncorrected. Do not delete it; do not let it be the reason a remote stops
tracking.
- Do **not** add a timer, retry, settle window, or suppression flag. The
fallback is a pose write because retail writes the pose, not because it makes
a symptom go away.
- `LiveEntityNetworkRemoteFarSnapIntegrationTests.cs:120-147` currently
**pins the freeze as correct** (`Assert.Equal(before, body.Position)`). It
must be inverted, not deleted quietly.
## Also required
**R1 — AP-137's justification is factually wrong (review A M2).** The row claims
the deleted `_playerController?.Position ?? Vector3.Zero` distance had "no
relationship to `player_distance`". It was streaming-origin-relative
(`LiveEntityNetworkUpdateController.cs:1360-1366`) and the streaming origin
recentres on the player's landblock — a biased but genuinely correlated proxy,
error bounded by roughly one landblock. The policy may still be right; the
stated reason is not true. Rewrite it to say what the deleted test actually
computed.
**R2 — AP-137 must state the cell-less delta (review A M3).** Retail routes a
cell-less body through @0x00516386`SetPosition` @0x00516420, an
**unconditional placement** sitting *before* the contact test. 4b-2 routes that
classification into `ApplyInterpolate`, which **enqueues** whenever
`!firstUp && willBeDrTicked && bodyToTarget <= 4 m`. For a cell-less remote
already tracking, acdream now queues where retail places — at *any* distance,
not only >=96 m. State it. If it should instead place, say so and change it.
**R3 — AP-137 must state that `RejectedData` is applied anyway.** It is the one
classification meaning "this payload failed validation"
(`classifier.cs:535-547`), and `UnroutedCatchUp` hands the same payload to
`ApplyInterpolate`. Not a regression — the legacy block did the same — but the
slice's stated purpose was an explicit handler, and the row omits it.
**R4 — a register row for the refusable far placement.** `grep` for
"Refused|service window" in the register returns zero. 4b-1 was dormant and owed
nothing; **4b-2 is the commit that makes it live and therefore owes the row**
(CLAUDE.md register rule 1). Whatever residual divergence survives the fix above
gets measured against retail's `store_position`/`GotoLostCell` behaviour.
**R5 — the two arms' guard/arm ordering must be identical (review A M4).**
| arm | routing | re-entrancy guard | post-op arm |
|---|---|---|---|
| player | `:2020` | `:2047-2054` (`return`) | `:2037`**before** the guard |
| NPC | `:2202` | `:2214-2221` (`return`) | `:2235`**after** the guard |
The NPC arm therefore arms `ConstrainTo` **zero** times on a superseded
incarnation, where retail arms unconditionally on the nonzero return
@0x00454254/@0x00454272. The player arm arms the leash on a possibly-superseded
`rmState.Host`. This also contradicts the diff's own new remarks at `:958-966`
("MUST re-validate … before writing anything else for the packet") — the player
arm writes the leash first.
**R6 — six comments the change falsifies** (review A m6; review B found the same
class independently as N6). This is the **fifth** consecutive slice shipping
stale comments asserting behaviour the code no longer has:
`LiveEntityNetworkUpdateController.cs:835`, `:868`, `:1589-1591`, `:2076-2081`;
`RuntimeEntityObjectLifetime.cs:600-605`; and
`RuntimeRemotePlacementDriveController.cs:106-143`, which still headlines "The
central decision — refuse, do not park" and asserts a cancelled park leaves the
entity invisible and intangible for the session — falsified at HEAD by the park
restore **this same class's** `CancelToken` uses (`:698-703`). 4b-1's review
already ordered that one corrected.
**R7 — three tests assert less than their names claim (review B N2/N3).**
- `NoClassificationAtAll_NearAndTicked_EnqueuesInsteadOfSnapping`
(`:191-213`) never inspects `remote.Interp`. A regression to "snap when
`bodyToTarget > 4 m`, else do nothing" passes it *and* its sibling. One
`Assert.True(remote.Interp.IsActive)` closes it.
- The `StopInterpolating` ordering test (`RuntimeRemotePlacementDriveControllerTests.cs:830-871`)
proves the clear is unconditional, not that it precedes the placement. Its doc
comment claims proof it does not have. Either pin the order or state plainly
that it is unobservable in acdream.
**R8 — the `DeferredCell` park branch has zero coverage (review B N5).** The
opt-in chain is correct by reading (`:623``:698-703`
`RuntimeSetPositionState.CancelCore``RestoreParkWithdrawal`), but no test in
4b-1 or 4b-2 exercises it, and the far arm is the first production path that can
provoke a park. Add the test: commit the destination collision generation, open
a `CollisionPrefixQuiescence` on the destination prefix, far-snap, then assert
`body.InWorld && record.ObjectClock.IsActive && record.FullCellId != 0`.
**R9 — currency across GUID reuse / incarnation / generation is undelivered
(review B N4).** Contract item 7 named five dimensions; two shipped
(interleaving, teardown). `_pending` and `_awaitingAcknowledgement` are keyed by
`RuntimeEntityKey` (guid+incarnation), so a reused GUID makes a *new* key and the
old entry self-heals only on a ledger read (`:670-688`) or in `Advance()`
(`:513-525`), which early-returns unless something is pending. Dead-incarnation
entries accumulate until `DetachRoute`. Converges at teardown; does **not**
converge in-session. Add the test: far-snap `G` at incarnation 1, retire it,
re-create `G` at incarnation 2, assert `RemotePlacementDrivePendingCount == 0`
**without** a teardown.
**R10 — `AirborneNoOperation` falls into `default:`** (review A m7). Unreachable
today — both callers early-return (`:1876-1881`, `:2130-2136`) — but the
`default:` comment asserts unreachability where an explicit case enforces it.
## Not blocking, recorded
- **n8**: `OwnsFarSnap` also matches the classifier's FORCE_POSITION shape
(`classifier.cs:329-345`), unreachable for remotes via `ValidAcceptedAuthority`
(`:522-525`) and `PhysicsTimestampGate` (`:190`). Defense-in-depth; note only.
- **NOT VERIFIED, carried**: what `SetPositionInternal` @0x00515330 does with the
0x1000 (`SendPositionEvent`) bit, which reaches
`TryPrepareAndSubmitAuthoredPlacement` for the far snap while the controller
doc argues acdream has "no ack" for remotes. Those are two different things
(the `SetPositionStruct` flag vs `CommandInterpreter::SendPositionEvent`
@0x00454091); 4b-1's review cleared only the latter. Settle with a read of
@0x00515330-@0x00515543.
- **Process**: `ParkCollisionResidents_StaysUnreachable_AfterRefusalAndAfterCommit`
(`RuntimeRemotePlacementDriveControllerTests.cs:782`) still calls the method
directly at `:824` — the shape 4b-1's finding B2 declared void. It shipped at
`2e8e09ac`, so it is outside this diff, but it is in the tree being counted as
evidence.
- **Headless (contract item 6) is satisfied vacuously.** Nothing in headless
constructs the drive controller and `RuntimeLiveEntitySessionController.OnPositionUpdated`
returns early for every non-local GUID (`:212-217`). The contract allowed this
only if stated plainly; AP-137 does not mention headless, and
`IRuntimeRemotePlacementServiceWindow`'s doc still describes the headless
implementation as a live consumer. State it.
## Gate
Complete Release suite, not a subset. **Corrected baseline: 10,968 / 4 / 0** at
`1b631f12`, measured independently in a throwaway worktree (App 4088, Runtime
1073). The 10,973 figure in the 4b-2 contract was wrong and propagated from an
earlier mis-record — an inflated baseline is exactly what would let a future
slice delete tests and still look green. The WIP state measured 10,990 / 4 / 0
while containing the freeze defect above.
Two known flakes, do not chase and do NOT conflate: **#302**
(`PortalProjectionTests…`, GC-allocation assertion, App.Tests) and **#308**
(`NakEmissionTests.LossSoak_…`, wall-clock deadline, Core.Net.Tests, full-suite
load only).