erik/acdream
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2

feat(physics): C4 route 2 — ForcePosition through the canonical placement

Browse source 
A local-player ForcePosition had TWO independent writers for one accepted
packet: LocalForcePositionTransaction snapped the physics body
(PlayerMovementController.BlipPosition, a raw SnapToCell with no collision
resolve), while LiveEntityNetworkUpdateController's generic tail separately
wrote position/cell/rotation to the render WorldEntity from the raw wire and
rebucketed it. Two stores, one packet — the divergence class 670f307c fixed on
the remote path. The outbound AutonomousPosition ack also fired BEFORE any
canonical commit existed: we told ACE "got it, I'm here" before deciding where
"here" was, and the trailing isCurrent() could only suppress the continuation,
never recall the packet.

RuntimeAcceptedPositionDriveController is now the one Runtime-owned seam. Both
hosts call the identical TryExecuteAcceptedLocalPosition; App and headless
project the committed result through the existing placement projection sink
(LiveEntityRuntime.TryApplyRuntimePlacementPlace already performed the same
four writes, from committed state rather than a wire guess).

Retail: SmartBox::HandleReceivedPosition @0x00453FD0's FORCE_POSITION branch is
get_heading -> Frame::set_heading -> SmartBox::BlipPlayer @0x00453940 -> stamp
POSITION_TS -> SendPositionEvent @0x00454091 -> return @0x0045409D. BlipPlayer
is CPhysicsObj::SetPositionSimple @0x005162B0 with flags 0x1012
(Teleport|Slide|SendPositionEvent) — a real collision-resolving SetPosition,
not a snap. The pinned classifier already encoded this exactly.

Named behaviour changes:

* The ack is now an OUTPUT of the committed route, fired strictly after the
  canonical commit and exactly once per accepted force packet.
* The ForcePosition route no longer re-arms the constraint leash. The force
  branch returns at 0x0045409D, ahead of all three ConstrainTo sites
  (0x00454272, 0x0045418A, 0x004541EC); the old re-arm cited retail's "Player,
  normal" branch, which BlipPlayer is not on. The teleport, CommitPreparedPosition
  and first-entry callers legitimately still constrain and are untouched.
* A force correction that terminates WITHOUT committing still sends its
  position event and is not retried — retail's BlipPlayer discards
  SetPositionSimple's SetPositionError return and acks unconditionally.

A single _pending funnel owns the in-flight placement, deciding on the token's
PositionAuthorityVersion against the record's: equal -> clear; advanced with the
newest accepted event still a force -> re-issue, re-classified; advanced to an
ordinary Apply -> clear, since newer server truth owns that pose. This closes a
double-apply/double-ack and a silently-dropped correction that two earlier
iterations of this slice each introduced.

AD-62 records the residual: a ForcePosition our async collision publication
cannot carry to a committed placement is not re-applied. Retail has no park —
its world is fully resident and its placement synchronous — so the state is
unreachable there. AP-131 is NOT retired; its legacy Position caller is route 4.

Deleted: LocalForcePositionTransaction, PlayerMovementController.BlipPosition,
HeadlessSessionWorldProjection.BlipLocalPlayer.

Gates: complete Release solution 10,858 passed / 4 skipped / 0 failed (baseline
10,844/4/0). Two independent Opus reviews (retail-conformance and
architecture/adversarial) PASS on the final diff after three FAIL rounds; every
intermediate state was fully green, so the suite caught none of the four real
defects. Connected acceptance is NOT run: nothing a user can do makes ACE emit
a ForcePosition without retail's @pklite, which acdream does not implement — see
docs/research/2026-08-03-c4-route-2-visual-gate.md.

Known gap, recorded not claimed: the plan's acceptance item 2 is unmet. The App
double-write check is a source pin, and "the committed projection moves the
render entity" is uncovered at any layer (#292). Filed alongside: #286-#291,
#293-#296.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Erik 2026-08-03 18:46:36 +02:00
parent 22a5c95400
commit 9966b53174
25 changed files with 4292 additions and 195 deletions
Download patch file Download diff file Expand all files Collapse all files

306
docs/ISSUES.md
View file

@ -140,6 +140,302 @@ reconciling #281's 43 test failures.
fired — the log shows zero `world frame is unreachable` failures and zero
parked placements across 9 completed reveals.
## C4 route 2 — ForcePosition placement cutover — 2026-08-03
Plan: [`2026-08-03-c4-route-2-implementation-plan.md`](research/2026-08-03-c4-route-2-implementation-plan.md);
contract: [`2026-08-03-c4-route-2-contract.md`](research/2026-08-03-c4-route-2-contract.md).
- **#285 — DONE (2026-08-03) — a ForcePosition on the local player wrote two
independent stores from one packet, and the outbound ack left before any
canonical commit existed.** `LocalForcePositionTransaction.Apply`
(App)/`HeadlessSessionWorldProjection.BlipLocalPlayer` (headless) drove
`PlayerMovementController.BlipPosition` — a raw `PhysicsBody.SnapToCell`
with no transition, no collision, no contact-plane resolve, no
`FullCellId`/`PlacementCommitVersion` advance — while the generic tail
(`LiveEntityNetworkUpdateController.cs`) independently wrote the
render-facing `WorldEntity` from the same wire frame; the App/no-window ack
(`LocalPlayerOutboundController.SendImmediatePosition`) fired immediately
after the blip, before either write's result was known. Same divergence
class as the remote-placement bug `670f307c` fixed.
**Fix:** `RuntimeAcceptedPositionDriveController`
(`src/AcDream.Runtime/Session/RuntimeAcceptedPositionDriveController.cs`) is
the single Runtime-owned accepted-Position execution seam for a
ForcePosition on an already-live local player: it drives the SAME
`RuntimeSetPositionState.TryBeginExclusiveAuthoredPlacement` +
`TryPrepareAndSubmitAuthoredPlacement` transaction every other placement
uses (retail `CPhysicsObj::SetPositionSimple` @0x005162B0, flags `0x1012`,
called from `SmartBox::BlipPlayer` @0x00453940), reconciles the
controller's render-lerp/cell state
(`PlayerMovementController.CommitCanonicalForcePositionFrame`, replacing
the deleted `BlipPosition`), and fires the ack strictly AFTER that commit —
never before it. `LocalForcePositionTransaction.cs` and
`HeadlessSessionWorldProjection.BlipLocalPlayer` are deleted outright, not
adapted; the generic render-tail write is skipped for the local player's
ForcePosition (App now projects the committed result through the existing
`RuntimePlacementPresentationSink`, the same seam every other placement
already uses).
**Two named behaviour changes, both retail-exact per this session's
verification:** (1) the outbound `AutonomousPosition` ack is now an OUTPUT
of the committed route, not a step alongside it — retail's
`cmdinterp->SendPositionEvent()` @0x00454091 runs after
`SmartBox::BlipPlayer` @0x00454074 returns, and the deleted transaction's
trailing `isCurrent()` recheck (which could only suppress the
*continuation*, not an ack that had already left) is now structurally
impossible; (2) the constraint leash is NOT re-armed on this route — every
`CPhysicsObj::ConstrainTo` call in `HandleReceivedPosition`
(@0x00454272/0x0045418A/0x004541EC) is on a branch the FORCE_POSITION early
return (@0x0045409D) never reaches. `BlipPosition`'s leash re-arm (added at
#167 Slice P5, commit `7719d25b`) was an unbacked deviation for this exact
branch — it was correct for retail's "Player, normal" branch that Slice P5
was modeling in general, but `SmartBox::BlipPlayer` is not on that branch.
#167's own historical write-up (below) is superseded for its `BlipPosition`
half by this entry.
**New behaviour (retail fidelity gain, not a regression):** the ForcePosition
now runs retail's REAL `SetPosition` collision resolve — a placement sphere
or authored Setup, not a bare teleport-shaped snap — so a corrected Z can
differ from the wire's literal Z by the placement sphere's own settle.
**R7 review correction (2026-08-03):** the FIRST implementation pass wrote
this paragraph against a fixture bug, not retail behavior — its headless
test fixture's dummy Setup sphere had its centre AT the origin (offset ==
radius), which lifted a settled origin a FULL 0.48 m radius above the
floor and was asserted as if that were the retail-correct answer. Retail's
`BlipPlayer` has never lifted the origin by a sphere radius. The real dat
human Setup `0x02000001`'s foot sphere is `(0,0,0.475) r=.48`
(`Ts46SphereListConformanceTests.cs:35-39`), whose bottom sits at
`origin + 0.475 − 0.48 = origin − 0.005` — so a settled origin lands
**within 5 mm** of the floor it rests on, not a sphere radius above it.
The headless fixture now uses the dat-exact sphere and asserts the
measured `Z = 50.005f` (`HeadlessSessionHostTests.cs`,
`WorldProjectionIgnoresNormalEchoButBlipsForcePosition`).
Runtime tests: `tests/AcDream.Runtime.Tests/Session/RuntimeAcceptedPositionDriveControllerTests.cs`
(classification/NotApplicable guards, ack-strictly-after-commit, ack
exactly once, the displaced-authority Contention case, the DeferredCell
park→wake→commit sequence, heading preservation, leash NOT re-armed, and —
added in the fix round — re-issue-from-canonical when a subsequent
accepted Position's merge-time `Forget` cancels a watched DeferredCell
park). **R8 review correction (2026-08-03):** the DeferredCell test's name
and assertions in the FIRST pass claimed a single-ack-after-wake sequence
the fixture does not exercise — this fixture's cross-landblock resolve
measures `InContact=false` (no subsequent physics tick sweeps the body
onto the terrain in this bare-Runtime harness), so no ack fires after the
wake at all today. The test is renamed
`DeferredCell_ParksThenCommitsAndNeverDoubleAcksAfterTheCollisionGenerationWakes`
and no longer pins the current zero-ack count with an assertion (a pinning
`Assert.Empty` would fail — and read as a regression — the day Contact
correctly starts flipping); it captures the ack count once and asserts
only that further `Advance()` pumps never change it. The
park→wake→commit→single-ack sequence remains unverified pending a harness
that drives a real physics tick to establish ground contact.
**Fix-round corrections (2026-08-03), both dual reviews having FAILed the
first pass — see
[`2026-08-03-c4-route-2-review-findings.md`](research/2026-08-03-c4-route-2-review-findings.md)
for the full R1-R9 list:** (R1, HIGH) the DeferredCell park could not
survive in production — `RuntimeEntityObjectLifetime.TryApplyPosition`
Forgets the entity's in-flight SetPosition on EVERY accepted Position (any
disposition), so a park outliving one ACE broadcast (~100-200 ms) was
cancelled before its collision generation could ever commit it, silently
losing the correction forever. `RuntimeAcceptedPositionDriveController.Advance`
now detects the dead watch (`IsPlacementCompletionTracked`) and re-issues
the SAME route from the entity's current canonical snapshot rather than
leaking `_pending`. (R2, HIGH) headless lost `BlipLocalPlayer`'s collision-
neighborhood re-centering; restored via the new
`IRuntimeDirectWorldProjection.CenterOnAcceptedForcePosition`. (R3, HIGH)
the headless login-window ForcePosition fallback was dropped; restored.
(R4, MEDIUM-HIGH) the force-ack was stealing a `Place` receipt the
presentation sink had legitimately declined for its own retry contract;
removed. (R5, MEDIUM-HIGH) corrected the `Rejected` status doc's false
"no SetPosition ran" claim. (R6, MEDIUM) `_pending` could leak forever on
a mid-session cancellation (now caught by the same R1 detection) and
`SubmitAndResolve` could silently overwrite a still-live pending (now
guarded, throws on the invariant violation). (R9, LOW hygiene) a stale
`BlipPosition` doc cref, `HeadlessSessionHost._currentSession` never
cleared on teardown, and the streaming observer/pose-dirty side effects
firing for a `Rejected`/`Contention` status the route explicitly declined
to place into. Complete Release solution after the fix round:
**10,853 passed / 4 skipped / 0 failed** (10,857 total) — App 4,058/3,
Bake 15/0, Cli 4/0, Content 124/0, Core.Net 762/0, Core 4,247/1, Headless
79/0, Runtime 1,021/0, UI.Abstractions 543/0.
**Round 2 fix (2026-08-03), both delta reviews having FAILed the fix round
— see the "ROUND 2" section of
[`2026-08-03-c4-route-2-review-findings.md`](research/2026-08-03-c4-route-2-review-findings.md):**
round 1 bolted the re-issue onto ad-hoc per-branch `_pending` bookkeeping,
which had no single owner and no single lifecycle rule; that is the shared
root cause of all three round-2 blockers. Replaced with ONE funnel:
`RuntimeAcceptedPositionDriveController.SettlePending` is the sole terminal
writer of `_pending`, `RetainPending` the sole outstanding writer, and
`AbandonPending` the sole teardown writer. Its ONE decision input is the
terminal operation token's `PositionAuthorityVersion`
(`RuntimeSetPositionState.cs:50`) versus the live record's current value —
equal ⇒ clear, no re-issue (fixes **N1**: one server correction now
produces exactly one canonical placement and exactly one outbound
`AutonomousPosition`, never two); advanced with the newest accepted event
still a ForcePosition ⇒ re-issue it, re-classified from the current record
via the newly recorded `_newestForce` observation (fixes **B1**: a
correction blocked by a woken park's retained completion is no longer lost);
advanced with the newest accepted event now an ordinary `Apply` ⇒ clear, no
re-issue (fixes **N2**: the round-1 shape reused the stale force route and
would have applied `Teleport|Slide` + an ack retail never sends to an
ordinary pose, skipping that branch's `ConstrainTo`). Complete Release
solution after round 2: **10,856 passed / 4 skipped / 0 failed** — App
4,058/3, Bake 15/0, Cli 4/0, Content 124/0, Core.Net 762/0, Core 4,247/1,
Headless 79/0, Runtime 1,024/0, UI.Abstractions 543/0.
Round 3 closed the conformance reviewer's one remaining blocker: a terminal
outcome that never committed now sends the packet's retail position event
carrying the body's unchanged pose, because `SmartBox::BlipPlayer`
@0x00453940 DISCARDS `CPhysicsObj::SetPositionSimple`'s
@0x005162B0 `enum SetPositionError` (other retail callers test it,
`== OK_SPE` @0x0055605D) and returns `void`, after which
`SmartBox::HandleReceivedPosition` @0x00453FD0 runs
`cmdinterp->SendPositionEvent()` @0x00454091 unconditionally and returns
@0x0045409D. Retail's rule is: attempt once, do not move on failure,
acknowledge regardless, never retry — so route 2 acks exactly once per begun
placement, from the commit path or from the settle, never both and never
zero.
Divergence register: **AD-62 filed** (round 2, rewritten round 3) — the
deferred-placement adaptation means a ForcePosition that cannot commit when
it arrives, and is then retired without commit, is not re-applied. As of
round 3 its position-event ack IS still sent whenever the placement was begun
AND that packet's descriptor reaches its own terminal settle. The ack is lost
in two narrower groups: where no placement was ever begun (an
externally-blocked `Contention`; a re-issue marker that never begins), and —
begun but displaced — where a newer force supersedes the packet before its
settle, since `SettlePending` nulls `_pending` without reading it (AD-62
shape (v)). Replaying that one would emit a stale-sequence report carrying
the newer packet's pose; the displacing packet always acks. Retail's
`SmartBox::BlipPlayer` is synchronous against a fully resident world and
reaches none of these states. The route-2 cutover ITSELF still adds no
deviation (it closes the
duplicate-authority + premature-ack bug); AP-131 is explicitly NOT retired
here (its named legacy `TryApplyPosition` caller is route 4's job, not
route 2's).
- **#286 — OPEN — headless never calls `RetryPending` on its placement
projection subscription.** `RuntimePlacementProjectionSubscription.RetryPending`
has exactly one caller in the tree, `GraphicalSessionEventRoute.cs:109,113`;
`HeadlessSessionEventRoute` constructs the subscription
(`HeadlessSessionEventRoute.cs:22`) but nothing pumps its retry. C4 route
2's R4 fix deliberately stopped the force-ack from consuming a `Place` the
sink declined, on the contract that the subscription's OWN retry re-offers
it — so on headless a declined `Place` would sit at the FIFO head and wedge
the ordered stream. Latent: not proven reachable today (the headless sink's
decline conditions may be unreachable given its bounded collision window).
Fix shape: give the headless host the same per-tick retry pump the
graphical route has, or prove the decline unreachable and record why.
Filed from the C4 route-2 round-2 review (N3).
- **#287 — OPEN — `RuntimeAcceptedPositionDriveController.Advance` has no
reentrancy latch.** Its template `RuntimeFirstEntryDriveController.DriveAll`
guards with `_driving` (`RuntimeFirstEntryDriveController.cs:61,130,132,146`);
the accepted-position drive does not, even though `Advance` can now re-enter
`SubmitAndResolve` through the `SettlePending` re-issue. No live re-entrant
path exists today (the funnel's recursion is bounded at one level and every
host pumps `Advance` from a single synchronous cadence point). Hygiene, not
a live defect. Filed from the C4 route-2 round-2 review (N4).
- **#288 — OPEN — two side effects were dropped when
`HeadlessSessionWorldProjection.BlipLocalPlayer` became
`CenterOnAcceptedForcePosition`.** (a) The deleted method also restored
`controller.LocalEntityId = record.LocalEntityId ?? 0u`; the replacement
(`HeadlessSessionWorldProjection.cs`, `CenterOnAcceptedForcePosition`) does
not. Inert today — nothing clears the id between publication and a
ForcePosition — but it is an unreplaced deletion, not a decision. (b)
`_movementTruthDiagnostics.OnServerEcho` no longer fires for a local
ForcePosition on the graphical host, because that route returns before the
generic tail (`LiveEntityNetworkUpdateController.cs`). Diagnostic-only.
Filed from the C4 route-2 round-2 review (N5).
- **#289 — OPEN — two doc comments still cite the deleted
`PlayerMovementController.BlipPosition`.** `src/AcDream.Core/Physics/Motion/ConstraintManager.cs:25`
and `src/AcDream.Core/Physics/PhysicsBody.cs:442` both name it inside `<c>`
tags, so they are build-safe (unlike a `<see cref="..."/>`, which R9 already
fixed) but false: C4 route 2 deleted the member. Left as-is they become the
citation a future session trusts. Filed from the C4 route-2 round-2 review
(R9 residue).
- **#290 — OPEN — route 1's classified `SendPositionImmediately` never fires
an ack.** The C4 plan required confirming whether the outbound position ack
fires while an initial-Create residence owns the record. It does not:
`RuntimeInitialCreateContinuationExecutor` consumes
`SendPositionImmediately` only as a trace fact (`:717`, `:2576`), never as
an outbound send. Not a regression (route 1 predates route 2 and behaves
exactly as before), but retail's FORCE_POSITION branch acks unconditionally
after `BlipPlayer`, so a ForcePosition admitted during the login residence
window is one retail ack we do not send. Decide at route 4/C5 whether the
residence tail should send it. Filed because the plan required filing it.
- **#291 — OPEN — the headless 3x3 collision window needs a divergence
register row.** C4 route 2's R2 fix promoted it to a NAMED member of the
Runtime-facing contract (`IRuntimeDirectWorldProjection.CenterOnAcceptedForcePosition`)
with an explicit ordering requirement — re-center BEFORE the placement
submits — that retail has no analogue for (retail has every landblock
resident). No existing row covers it: AD-6 is retired and AD-2 is the
graphical reveal barrier. Recommend one AD row naming the window, the
ordering requirement, and the symptom if it breaks (a `DeferredCell` park
the window can never publish). Filed from the C4 route-2 round-2 review.
- **#292 — OPEN — C4 route 2 acceptance item 2 is source-pinned, not
proven.** Recorded gap from round-2 finding B2 (the plan's own text is
corrected at
[`2026-08-02-placement-cutover.md`](plans/2026-08-02-placement-cutover.md)).
First half — "the generic tail no longer double-writes the local player" —
is pinned only by a source-text regex, which a differently spelled second
write would pass, and no test exercises the branch. Second half — "the
committed projection is what moves the render entity" — is uncovered at any
layer: no test drives a route-2 ForcePosition through
`RuntimePlacementPresentationSink` / `TryApplyRuntimePlacementPlace` and
asserts the `WorldEntity` moved. Given R4, that is exactly the seam whose
failure is silent (canonical body moves, render entity stays). Fix shape: an
App-layer end-to-end test asserting the render entity's position/cell came
from the committed placement receipt.
- **#293 — OPEN — the DeferredCell park still consumes `Withdraw` receipts the
sink may have declined.** `RuntimeAcceptedPositionDriveController.SubmitAndResolve`'s
`DeferredCell` branch drains the head of the placement FIFO while it is a
`Withdraw` for this entity and calls `AcknowledgeProjection` on it
(`RuntimeAcceptedPositionDriveController.cs:709-716`). That is the exact
receipt-stealing shape R4 removed for `Place`: the R4 fix's whole argument is
that `RuntimePlacementProjectionSubscription` deliberately leaves a receipt
the sink declined at the FIFO head for its own later retry, and that this
route has no follow-up binding to cover it. The `Withdraw` drain was left
unchanged in round 1 because it is copied verbatim from
`RuntimeFirstEntryDriveController.TryCompleteContinuationPlacement`, but the
same asymmetry applies — that controller's residence guarantees the decline,
this one's does not. Fix shape: decide whether a declined `Withdraw` is
reachable for this route and either drop the drain (letting the
subscription's retry own it, as `Place` now does) or record why the decline
cannot happen here. Filed from the C4 route-2 round-3 adversarial review.
- **#294 — OPEN — the deferred wake reconciles and acks BEFORE the funnel's
currency guard.** `RuntimeAcceptedPositionDriveController.Advance` consumes
the acknowledged placement and immediately calls `ReconcileAndAcknowledge`
(`:452`), and only then enters `SettlePending`, which is where the
entity-still-active / still-the-local-player / still-the-same-incarnation
checks live (`TryGetActive`, `ServerGuid`, `PhysicsBody`, `key !=
terminalToken.Entity`). So a wake that lands after the entity departed the
world, stopped being the local player, or released its incarnation still
runs the controller-local reconcile and can still send an outbound
`AutonomousPosition`. `ReconcileAndAcknowledge`'s own
`record.ServerGuid != _localPlayerServerGuid()` test uses the RETAINED
record, not a re-resolved active one, so it does not cover the departed
case. Ordering, not a workaround: the currency guard belongs before the
reconcile. Filed from the C4 route-2 round-3 adversarial review.
- **#295 — OPEN — the re-issue retry marker inflates
`AcceptedPositionDrivePendingCount`.** When `SettlePending`'s re-issue cannot
begin, it parks the terminal descriptor as a retry marker in `_pending`. That
marker is not an in-flight placement — its token is dead by construction —
but `PendingCount` (`:259`) and the ownership ledger registered at `:255-256`
both report it as one. Any convergence reader (`CaptureOwnership`,
`GameWindowLifetime.DisposeGameRuntime`'s non-convergence throw) therefore
sees a placement that does not exist, and a marker that outlives its
usefulness reads as a wedged operation rather than as "a re-issue is owed".
Fix shape: count in-flight placements and owed re-issues separately, or give
the marker its own field. Filed from the C4 route-2 round-3 adversarial
review.
- **#296 — OPEN — a retryable prepare is reported to hosts as `Contention`.**
`SubmitAndResolve` returns `RuntimeAcceptedPositionExecutionStatus.Contention`
for a retryable preparation status (`RetrySetupUnavailable` /
`RetryWorldFrameUnavailable`, `:661`), reusing the status whose documented
meaning is "begin failed; the entity already owns an operation". The two are
materially different: the retryable case DID begin, IS retained in `_pending`,
and WILL be re-driven by the next `Advance` pump, while true `Contention` may
have recorded nothing at all (register row AD-62 shape (iv)). Hosts cannot
distinguish them — `LiveEntityNetworkUpdateController` branches on the status
— and neither can a future reader of the enum doc. Fix shape: a distinct
status (or a documented union) so the retained-and-pumping case is not
conflated with the dropped case. Filed from the C4 route-2 round-3
adversarial review.
## C3c placement cutover — 2026-08-02
- **#276 — OPEN — SpawnPlacementSettler discards the settle's resolved
@ -4913,6 +5209,16 @@ gate is `PhysicsBody.IsFullyConstrained` (former TS-35) via
`jump_is_allowed`. Decomp: `docs/research/2026-07-03-r5-managers/`,
`docs/research/2026-07-30-constraint-leash-constants.md`.
**2026-08-03 correction (C4 route 2, #285):** the `BlipPosition` half of this
arming site was an unbacked deviation for the ForcePosition branch
specifically — `SmartBox::BlipPlayer` (0x00453940), the function
`HandleReceivedPosition`'s FORCE_POSITION branch calls, is not on the
"Player, normal" branch this slice modeled; retail's FORCE_POSITION early
return (0x0045409D) precedes every `ConstrainTo` call. `BlipPosition` is
deleted; the leash is no longer (re)armed on a ForcePosition. The arming
site for every OTHER inbound position (remotes, the local player's ordinary
teleport/`SetPosition`) is unaffected.
**Acceptance:** the two constants are recovered (byte-decoded from the
binary), acdream arms the leash on inbound server positions,
`IsFullyConstrained` fires while rubber-banding, and a jump attempt inside

3
docs/architecture/retail-divergence-register.md
View file

@ -62,7 +62,7 @@ accepted-divergence entries (#96, #49, #50).
---
## 2. Adaptation (AD) — 47 active rows (AD-61 filed 2026-08-02, C3c review round 1 — the #270 settle compression now covers the local player; AD-42 refreshed same round — its cited App-side login resolve split was deleted by the C3c flip, the split survives only on the unflipped remote-teleport/headless portal-resync paths; AD-59/AD-60 filed 2026-08-02, continuation-executor slice)
## 2. Adaptation (AD) — 48 active rows (AD-62 filed 2026-08-03, C4 route 2 round 2 — a deferred ForcePosition retired without committing is not re-applied and its ack is not sent; AD-61 filed 2026-08-02, C3c review round 1 — the #270 settle compression now covers the local player; AD-42 refreshed same round — its cited App-side login resolve split was deleted by the C3c flip, the split survives only on the unflipped remote-teleport/headless portal-resync paths; AD-59/AD-60 filed 2026-08-02, continuation-executor slice)
Recent retirements: AD-3/AD-4 retired 2026-07-31 by exact active/per-candidate
visible-cell availability, full-catalog containment-root validation, and the
@ -155,6 +155,7 @@ readiness/requeue adaptation. See
| AD-59 | **Filed 2026-08-02 (physics campaign, continuation-executor slice).** The `SameIncarnationCreate` envelope buffers one publish per committed stage and flushes them ALL, in stage order, only after the LAST stage commits (constant-true per-field predicate, `IsCurrent`-checked at flush - the per-field closure variant was invalidated by WeenieDescription's six-field `AdvanceCreateAuthority`). A subscriber sees N back-to-back events with no interleaved observation point, each carrying the FINAL merged post-envelope record state, not per-stage state. | `src/AcDream.Runtime/Entities/RuntimeInitialCreateContinuationExecutor.cs` (`ApplyEnvelope` buffered-publish tail; `Publish`/`PublishNow`) | Retail's own tail is one synchronous critical section, and retail emits ONE notice per Create (`ECM_Physics::SendNotice_CreateObject`, fired whenever a weenie exists, independent of the physics-registration outcome) - never N per-internal-step notices. The buffered flush is closer to retail's one-signal model than per-step publication would be, though not a literal 1:1 match. | A subscriber diffing consecutive `Updated` events from the SAME envelope to isolate one stage's delta gets every stage's cumulative state on each event - silently wrong incremental-diff logic, not a crash. | `SmartBox::HandleCreateObject` 0x00454C80 same-incarnation tail (one synchronous critical section); `ACCObjectMaint::CreateObject` 0x00558870 step 11 (`ECM_Physics::SendNotice_CreateObject`) |
| AD-60 | **Filed 2026-08-02 (physics campaign, continuation-executor slice).** Executor Position-continuation merges never directly commit residency: `ApplyPositionAction` refreshes `canonical.Snapshot.Position` with the retained wire pose but withholds the derived `FullCellId` (`RefreshSnapshot(..., refreshPosition: false)`); only a Runtime `SetPosition` commit (the continuation's own classified placement) or a later simulation full-cell commit may change residency. The LEGACY immediate-apply path's `RefreshSnapshot(canonical, snapshot, refreshPosition: acceptedPosition)` (`RuntimeEntityObjectLifetime.cs:1338`) still derives `FullCellId` from bare wire acceptance - that coarser rule is part of the AP-1 divergence this campaign is removing, not something this row blesses. | `src/AcDream.Runtime/Entities/RuntimeInitialCreateContinuationExecutor.cs` (`ApplyPositionAction`, the CANONICAL CELL SEMANTICS comment) | Matches retail exactly: `HandleReceivedPosition` never writes a resident cell - `enter_world`/`MoveOrTeleport`'s placement commit and `SetPosition` do; also matches the classifier's documented cellless rule. | If a future change passes `refreshPosition: true` here, a wire Position would make a cellless canonical body resident without any placement/collision commit - the classic AP-1-shaped bug this campaign exists to close. | `SmartBox::HandleReceivedPosition` 0x00453FD0; `RuntimeAuthoritativePositionRouteClassifier.ClassifyAcceptedPosition` comment |
| AD-61 | **Filed 2026-08-02 (C3c review round 1).** The #270 settle-timing compression now covers the LOCAL player: `RuntimeLocalPlayerPhysicsPublicationState.SettleFirstEntryGroundContact` runs the shared `SpawnPlacementSettler` exactly once after the dormant activation's final commit (suffix-current authority only), compressing retail's first post-`enter_world` gravity frame — which grants CONTACT/ON_WALKABLE from a real touch — into the placement transaction. The legacy App-era force-seed (`Contact\|OnWalkable\|Active` in `PlayerMovementController.SetPositionCore`) still RUNS during publication-candidate preparation and is then OVERWRITTEN by the faithful activation commit + settle (it was never deleted). Caveat (review minor M2): the settler commits `settle.Position` but discards `settle.CellId` — a settle whose few-cm sweep crosses a cell boundary keeps the placement cell until the next resolve corrects it (inherited #270 semantics; ISSUES entry filed) | `src/AcDream.Runtime/Gameplay/RuntimeLocalPlayerPhysicsPublicationState.cs` (`SettleFirstEntryGroundContact`); `src/AcDream.Core/Physics/SpawnPlacementSettler.cs` (`TrySettle`); overwritten seed `src/AcDream.Runtime/Gameplay/PlayerMovementController.cs` (`SetPositionCore`) | Timing compression only: contact comes exclusively from the sweep's real touch (no caller-bool seeding, no forced transients), an airborne spawn stays genuinely airborne, and the overwritten force-seed leaves no observable residue past the activation commit — the committed state is exactly what retail's first gravity frame produces | A settle crossing a cell boundary reports the stale placement cell for the frames before the next resolve; a future reader trusting `SetPositionCore`'s "treat as grounded" seed comment could reintroduce the Contact-without-plane state the landing family calls unrepresentable | `CPhysicsObj::enter_world` 0x00516170; `SmartBox::HandleCreateObject` 0x00454C80 |
| AD-62 | **Filed 2026-08-03 (C4 route 2, round 2); rewritten round 3.** General rule: an accepted local-player ForcePosition that this route does not carry through to a committed canonical placement is never re-applied. That half matches retail — `SmartBox::BlipPlayer` attempts the placement exactly once and never retries. What diverges is that acdream has non-commit outcomes retail cannot reach at all, because retail's world is fully resident and its placement synchronous. Round 3 narrowed the loss to the re-apply alone wherever the packet's placement was actually BEGUN: the retail position event now fires at that packet's terminal outcome whether or not the placement committed (`SettlePending`'s `positionEventOwed` path), matching `BlipPlayer` discarding `SetPositionSimple`'s `enum SetPositionError` and `HandleReceivedPosition` acking unconditionally @0x00454091. Shapes losing ONLY the re-apply: (i) the destination landblock's collision generation is unpublished so the placement parks (`DeferredCell`) and is then retired by a non-position cause (collision-generation retirement, the lost-cell deadline, `ParkCollisionResidents`) with the accepted authority unmoved — the funnel's EQUAL branch; (ii) the same park superseded by a newer ordinary `Apply` Position which now owns the pose — the ADVANCED+ordinary branch; (iii) any OTHER `PositionAuthorityVersion` advance moving the record out from under the funnel's re-issue test — `TryApplyPickup` (`RuntimeEntityObjectLifetime.cs:1116`), `CommitPositionChannelUpdate` (`:2041`), `AdvanceCreateAuthority` (`:2466`) — effectively unreachable for a live local player, but they fail silently in the same direction and the funnel cannot tell them from (ii). Shapes still losing BOTH the re-apply and the ack because no placement was ever begun for that packet: (iv) a `Contention` whose blocking operation is EXTERNAL to this drive (a concurrent portal/teleport placement owns the entity) — nothing is recorded in `_pending`, so nothing pumps it and the packet is dropped outright; (vi) a re-issue retry marker whose re-issue never manages to begin before the funnel clears it. Losing BOTH for a DIFFERENT reason — the placement WAS begun, but the descriptor was displaced before reaching its own terminal settle: (v) a packet superseded by a newer force whose own placement begins cleanly — `SettlePending` opens by nulling `_pending` without reading it, so the older descriptor's owed ack is discarded. Replaying it would be worse than losing it (a stale-sequence report carrying the newer packet's committed pose), and the displacing packet always acks, so ACE always receives a report for the newest force. The `DeferredCell` park is NOT a precondition of this row: shapes (iv)-(vi) never park. In every shape the body stays where the last successful placement left it and the next accepted Position (ACE broadcasts at 5-10 Hz) carries the corrected pose forward. | `src/AcDream.Runtime/Session/RuntimeAcceptedPositionDriveController.cs` (`SettlePending` — the single terminal-outcome funnel: its `positionEventOwed` ack and its two non-reissuing branches; and `TryExecuteAcceptedLocalPosition`'s `Contention` return) | Retail has no park and no external placement authority: `SmartBox::BlipPlayer` runs synchronously against a fully resident world, so "arrived but not yet placeable" and "another placement owns this entity" are both unrepresentable there. Those are our async collision-publication and single-placement-authority adaptations. Re-issuing a retired force instead would be worse than not: shape (ii) would stamp the force route's `Teleport\|Slide` flags and an unconditional ack onto an ordinary echo's pose while skipping the `ConstrainTo` the ordinary branch runs (`RuntimeAuthoritativePositionRouteClassifier.cs:368-388`), and shape (i) can re-issue into the same persistent cancellation cause indefinitely. The drive still owns at most one in-flight placement and still re-issues whenever the newest accepted event IS a still-unserved ForcePosition. | A server correction whose destination collision is slow to publish, or which lands while another placement authority owns the entity, can be silently skipped: the player stays at the pre-correction pose for one broadcast interval (~100-200 ms). Sustained (a slow-publishing destination correcting repeatedly) this reads as rubber-banding that does not take. In shapes (iv)-(vi) ACE additionally receives one fewer `AutonomousPosition` than retail would have sent, so the server cannot tell its force was not applied. | `SmartBox::HandleReceivedPosition` @0x00453FD0 FORCE_POSITION branch (`SendPositionEvent` @0x00454091, early return @0x0045409D); `SmartBox::BlipPlayer` @0x00453940 (discards the error, returns void); `CPhysicsObj::SetPositionSimple` @0x005162B0 (returns `enum SetPositionError`; other callers test `== OK_SPE` @0x0055605D/@0x00556021); `CommandInterpreter::SendPositionEvent` @0x006B4770 |
---

67
docs/plans/2026-08-02-placement-cutover.md
View file

@ -252,9 +252,70 @@ same commit) → docs/handoff commit. No workarounds; no fused slices.
4 (remote Create/Position; delete `RemoteTeleportController`/`Placement`
and the inline MoveOrTeleport duplicate), 5 (projectile authoritative),
6 (drops + split-recovery marking), 7 (residual pickup/parent/delete
polish). — OPEN at the 2026-08-03 handoff.** May land as more than one
commit if a route proves large;
each sub-landing keeps the full review discipline.
polish). — route 2 implementation COMPLETE, pending review, at the
2026-08-03 handoff; routes 3/4/5/6/7 remain OPEN.**
**Route 2 (ForcePosition) — implemented 2026-08-03, contract:**
[`2026-08-03-c4-route-2-contract.md`](../research/2026-08-03-c4-route-2-contract.md),
**plan:** [`2026-08-03-c4-route-2-implementation-plan.md`](../research/2026-08-03-c4-route-2-implementation-plan.md).
`RuntimeAcceptedPositionDriveController`
(`src/AcDream.Runtime/Session/RuntimeAcceptedPositionDriveController.cs`)
is the single accepted-Position execution seam for a ForcePosition on the
already-live local player; `LocalForcePositionTransaction` and
`HeadlessSessionWorldProjection.BlipLocalPlayer` are deleted, and the
generic App render-tail is skipped for the local player's ForcePosition.
Named behaviour changes (both retail-exact, ISSUES #285): the outbound
ack now fires strictly after the canonical commit, and the constraint
leash is no longer re-armed on this route (retail's FORCE_POSITION branch
never reaches `ConstrainTo`).
**Fix round (2026-08-03):** both independent dual reviews (retail-
conformance + architecture/adversarial) FAILed the first pass — see
[`2026-08-03-c4-route-2-review-findings.md`](../research/2026-08-03-c4-route-2-review-findings.md)
for the full R1-R9 list. The critical finding (R1) was that the
DeferredCell park could not survive a single ACE broadcast interval in
production (`RuntimeEntityObjectLifetime.TryApplyPosition`'s unconditional
`Forget` on every accepted Position cancelled it before its collision
generation could commit), silently dropping the correction forever;
`RuntimeAcceptedPositionDriveController.Advance` now detects the dead
watch and re-issues from the entity's current canonical snapshot. R2/R3
restored headless's collision re-centering and login-window fallback; R4
stopped the force-ack from stealing a receipt the presentation sink had
legitimately declined; R5/R6/R9 corrected false doc claims, closed a
`_pending`-leak/overwrite gap, and fixed streaming-observer/pose-dirty
side effects firing on a declined placement. R7 corrected a fixture bug
(a dummy Setup sphere with its centre at the origin) that had been
written up as a retail fidelity gain; R8 added App-layer double-write
source pins and corrected an overclaimed single-ack test. Full detail:
[`2026-08-03-c4-route-2-review-findings.md`](../research/2026-08-03-c4-route-2-review-findings.md).
Complete Release solution after the fix round: **10,853 passed / 4
skipped / 0 failed** (baseline 10,844/4/0; first pass 10,848/4/0).
**Acceptance item 2 is NOT met — recorded gap, B2 (2026-08-03 round 2).**
An earlier revision of this paragraph claimed R8 "added the App-layer
double-write source pins the plan's own acceptance item required". That was
a claim of coverage this changeset does not have, and it is corrected here
rather than left as the citation a future session trusts (same rule that
produced R7). The truth, per the adversarial review:
- *First half — "the generic tail no longer double-writes the local
player":* **source-pinned, not proven.** The pin is a regex/`Assert.Single`
over `LiveEntityNetworkUpdateController`'s source text, so it would still
pass if a second write were spelled differently, and **no test exercises
the branch** at runtime.
- *Second half — "the committed projection is what moves the render
entity":* **uncovered at any layer.** No test drives a route-2
ForcePosition through `RuntimePlacementPresentationSink` /
`TryApplyRuntimePlacementPlace` and asserts the `WorldEntity` actually
moved. Given R4 (the force-ack no longer consumes a declined `Place`),
this is precisely the seam whose failure mode is silent: the canonical
body moves and the render entity stays put.
Closing this gap needs an App-layer test that runs the accepted
ForcePosition end to end and asserts the render entity's position/cell came
from the committed placement receipt — carry it into C5's parity tests or
file it before this sub-landing closes.
**Not yet done:** both reviews must be RE-RUN on this fixed diff, and the
connected (user-gated) acceptance gate this campaign's standing
discipline requires, before this sub-landing is considered closed — those,
and the commit itself, are next. May land as more than one commit if a
route proves large; each sub-landing keeps the full review discipline.
- **C5 — legacy deletion + closeout gates — OPEN.** Delete every superseded legacy
path; parity tests; exact lifecycle/reconnect + canonical nine-stop
connected routes; two-client observation; **user visual matrix** (the

291
docs/research/2026-08-03-c4-route-2-implementation-plan.md Normal file
View file

@ -0,0 +1,291 @@
# 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.

479
docs/research/2026-08-03-c4-route-2-review-findings.md Normal file
View file

@ -0,0 +1,479 @@
# C4 route 2 — dual review findings and required fixes (2026-08-03)
Both mandated reviews returned **FAIL** on the first implementation pass.
Nothing is committed. This is the consolidated fix list; it supersedes the
implementer's own closing report where they disagree.
Reviews: retail-conformance (Opus) and architecture/adversarial (Opus), run
independently against the same uncommitted diff.
## Verified correct — do not churn these
Both reviews independently confirmed, with addresses:
- `AuthoritativeTeleportFlags` = `Teleport|Slide|SendPositionEvent` = `0x1012`,
byte-exact against `CPhysicsObj::SetPositionSimple` @0x005162B0.
- Leash re-arm removal is retail-correct: the FORCE_POSITION branch returns at
0x0045409D, strictly before all three `ConstrainTo` sites (0x00454272,
0x0045418A, 0x004541EC). The teleport / `CommitPreparedPosition` /
`ArmConstraintLeashAtCommittedPlacement` callers correctly still constrain.
- Heading preservation happens exactly once, upstream in
`InboundPhysicsStateController.ApplyAcceptedPosition:788-798`. The seam does
not re-apply or drop it.
- Ack ordering is correct and fires exactly once on both the synchronous and
the deferred path; the `CanSendPositionEvent` gate matches retail's
`CommandInterpreter::SendPositionEvent` @0x006B4770, and correctly does NOT
apply `ShouldSendPositionEvent`'s rate limit (retail's force branch calls
SendPositionEvent directly).
- Route-request field derivation matches the continuation executor field for
field.
- Contract items 2, 4 (the Runtime command itself), 6, and 7 pass. AP-131
correctly not retired.
- The re-modelled `PlayerMovementControllerTests` are relocations, not
weakenings.
## Required fixes, in priority order
### R1 — HIGH — the DeferredCell park cannot survive in production
`RuntimeEntityObjectLifetime.cs:1636` calls `Physics.SetPosition.Forget(canonical)`
on EVERY accepted Position, which unconditionally cancels the entity's in-flight
operation. ACE broadcasts at 5-10 Hz, so any park lasting longer than ~100-200 ms
is guaranteed to be cancelled before its collision generation commits — exactly
the far-destination case the deferred path exists to serve.
Chain: park -> cancelled -> `RetryDeferred` never runs -> no `Place` receipt ->
`ReconcileAndAcknowledge` never runs -> **the body is never moved and no ack is
ever sent.** The old `LocalForcePositionTransaction` / `BlipLocalPlayer` pair
applied the correction synchronously and unconditionally. Retail's `BlipPlayer`
@0x00453940 has no "give up quietly" state at all.
**Park-and-hope is not a valid mechanism here. Required direction:**
1. Do not open a park that can never wake. Before submitting, establish that the
destination's collision is publishable (R2), and mirror the existing
C3c-R1-F7 guard shape (`IHeadlessCollisionNeighborhood.IsWithinServiceWindow`,
`HeadlessSessionWorldProjection.cs:20-27`) rather than inventing a new one.
2. Where a park still legitimately occurs, the seam must detect that its
operation was cancelled — `RuntimeSetPositionState.IsPlacementCompletionTracked`
(`:1245`) is the existing read-only query — and **re-issue the placement from
the current canonical snapshot** on the next accepted Position or `Advance()`.
The snapshot already carries the latest accepted pose, so re-issuing is
correct, not a replay of stale state.
3. A force correction must never be silently dropped. That is the retail
invariant this route exists to preserve.
Do NOT resolve this with a timeout, a settle window, a retry counter, or by
exempting ForcePosition from `Forget`. If you conclude the correct answer is a
deliberate, cited divergence, STOP and report rather than shipping one.
### R2 — HIGH — headless lost its destination-collision publication
`HeadlessSessionWorldProjection.BlipLocalPlayer` (deleted) called
`_collision.CenterOn(position.LandblockId)`. The headless collision neighborhood
is a hard 3x3 window (`BuildPublicationPlan`, `:462-488`) moved ONLY by
`CenterOn`. The surviving callers are spawn (`:562`), the controller-null login
branch (`:603`), teleport prep (`:640`) and portal arrival (`:683`) — a
ForcePosition on a live local player now reaches none of them. `PumpFirstEntry`
(`:624`) polls the stale `_requestedLocalPlayerCell`, which nothing updates on
this path either.
Restore a real mechanism (re-center plus the `_requestedLocalPlayerCell`
update), or gate on `IsWithinServiceWindow` and handle out-of-window explicitly.
The deleted `CenterCount` assertion in `HeadlessSessionHostTests.cs:430` is the
invariant; restore it rather than the changed number.
The in-test justification ("retail's BlipPlayer has no streaming-window
concept") is true of retail and irrelevant: the window is OUR adaptation, and
retail has no equivalent because retail has every landblock resident.
### R3 — HIGH — login-window ForcePosition now does nothing at all
`RuntimeLiveEntitySessionController.cs:229-254`. Previously every accepted local
Position ran `_worldProjection.ProjectPosition`, whose controller-null branch
(`HeadlessSessionWorldProjection.cs:593-607`) set `_requestedLocalPlayerCell`,
called `CenterOn`, and pumped `_firstEntry.DriveAll()`. Now a ForcePosition
takes the new branch, the drive returns `NotApplicable` (residence active), and
nothing happens.
Restore the pump for the controller-absent case, and delete the comment at
`:239-240` claiming "there is no legacy fallback to run instead" — there was
one; it is the `else` branch this change routed around.
### R4 — MEDIUM-HIGH — the force-ack steals a receipt the sink declined
`RuntimeAcceptedPositionDriveController.cs:366-375` unconditionally calls
`AcknowledgeProjection(outcome.Projection)`. `RuntimePlacementProjectionSubscription`
deliberately leaves a declined `Place` at the FIFO head for a later retry
(`:118-121`); this consumes and destroys it.
The sink declines for real production reasons — `!_spatial.IsLoaded(landblock)`
(`LiveEntityRuntime.cs:1210-1219`) and stale transit authority
(`RuntimePlacementPresentationSink.cs:90-96`). In those cases `entity.SetPosition`
/ `Rotation` / `ParentCellId` / `RebucketLiveEntity` / `IsSpatiallyProjected`
are never written, and because the generic tail is now skipped there is no
second writer to cover it — the render entity silently stays put while the
canonical body moved.
The `RuntimeFirstEntryDriveController` mirror is safe ONLY because a residence
makes the sink decline by design and a follow-up `ExecutorCompleted` receipt
re-binds presentation. Route 2 has no such follow-up. Drop the force-ack and let
the subscription's retry contract stand, or provide a real follow-up binding.
### R5 — MEDIUM-HIGH — `Contention` and `Rejected` silently drop the correction
`RuntimeAcceptedPositionDriveController.cs:265-271` returns `Contention` when
`TryBeginExclusiveAuthoredPlacement` fails; neither status creates a pending
entry, and both hosts then return without blipping or acking
(`LiveEntityNetworkUpdateController.cs:1140`). The `Contention` doc comment
promises "a later accepted Position, or this controller's own Advance pump,
retries" — the pump provably cannot retry something never recorded, and a later
Position carries a different pose. Retail always applies.
The most likely trigger is R1's parked operation, which makes every subsequent
ForcePosition `Contention`. Fixing R1 largely fixes this; the status handling
must still not silently drop.
Also fix the `Rejected` enum doc: it claims "No SetPosition ran; no ack was
sent", which is false at the two `SubmitAndResolve` sites (`:361`, `:415`) where
a SetPosition ran and was cancelled.
### R6 — MEDIUM — `_pending` leaks and can be silently overwritten
`RuntimeAcceptedPositionDriveController.cs:289-324`. `Advance()` exits only on
record-key release or acknowledged completion. A mid-session cancellation
(supersession, lost-cell deadline, `ParkCollisionResidents`, generation cancel —
all route through `ForgetPlacementCompletionCore`) leaves `_pending` set
forever, so `AcceptedPositionDrivePendingCount` keeps `IsConverged` false for
the rest of the session. `GameWindowLifetime.DisposeGameRuntime:490-498` throws
on non-convergence.
Plan §4c required dropping the pending ack on cancellation, supersession,
teardown, generation change and reset. Only teardown and reset shipped. Use
`IsPlacementCompletionTracked`. Also: the `_pending = null` cleanups are all
guarded by `if (!firstAttempt)`, and `SubmitAndResolve(firstAttempt: true)`
assigns `_pending` without inspecting an existing one — make it refuse to
overwrite a live pending.
### R7 — MEDIUM — the 0.48 fixture, the changed assertion, and the false doc
**This is a test-fixture artifact, NOT a production regression.** The headless
fixture's `LoadedSetupCollisionSource` returns one sphere
`(Vector3.Zero, 0.48f)` — centre AT the origin, bottom 0.48 m below the feet.
The real human Setup `0x02000001` is `(0,0,0.475) r=0.48` plus
`(0,0,1.350) r=0.48` (`Ts46SphereListConformanceTests.cs:35-39`), so the foot
sphere's bottom is origin - 0.005 and a settled origin lands on the floor within
5 mm. The control is in this same changeset: the new Runtime fixture uses the
dummy sphere (offset == radius) and asserts the origin lands exactly on the
floor (`RuntimeAcceptedPositionDriveControllerTests.cs:178`).
Required:
1. Give the headless fixture the retail offset `(0f, 0f, 0.475f) r=0.48` and
**restore the `Z == 50f` assertion**. Changing an assertion to match new
output is the plan's own forbidden move.
2. Delete the false comment at `HeadlessSessionHostTests.cs:419-427` — it
describes the sphere CENTRE and then asserts it about `controller.Position`,
which is the ORIGIN (`PlayerMovementController.cs:304` -> `PhysicsBody.cs:153`,
retail `CPhysicsObj::m_position.frame.origin`).
3. Correct the `docs/ISSUES.md` #285 "retail fidelity gain" paragraph. Retail's
`BlipPlayer` has never lifted the origin by a sphere radius. Left as-is this
becomes the citation a future session trusts.
### R8 — MEDIUM — acceptance gaps
- No App-layer test exists proving the generic tail no longer double-writes the
local player and that the committed projection is what moves the render
entity. The plan's acceptance item 2 is unmet; three App tests were deleted
and replaced with a comment. Given R4, this is precisely the seam that is
broken.
- `RuntimeAcceptedPositionDriveControllerTests.cs:310-311` asserts
`acksAfterFirstResolve <= 1`, so the test **passes with zero acks** — the
DeferredCell park -> wake -> commit -> single-ack sequence is unverified,
while `docs/ISSUES.md` claims it is covered. Fix the fixture so the contact
gate is satisfied and assert exactly one, or state plainly that it is
unverified. Do not leave the overclaim in the record.
### R9 — LOW — hygiene
- `RuntimeAcceptedPositionDriveController` is `public sealed` with an internal
ctor and all-internal members; its template `RuntimeFirstEntryDriveController`
is `internal sealed`. Make it internal unless the public surface is genuinely
required (if it is, say why).
- `PlayerMovementController.cs:632` has a stale `<see cref="BlipPosition"/>` to
a deleted member. Harmless only while `GenerateDocumentationFile` is off;
`TreatWarningsAsErrors` is on, so it breaks the build the day docs are enabled.
- `HeadlessSessionHost._currentSession` is never cleared on teardown.
- Headless without a content lease leaves the drive controller null, so the
ForcePosition and its ack are dropped entirely
(`HeadlessSessionHost.cs:568-581`); previously the ack fired unconditionally.
- `LiveEntityNetworkUpdateController.cs:1140-1155` fires
`MarkLiveOwnerPoseDirty` and `ObserveAcceptedLocalPosition` for ANY non-
`NotApplicable` status including `Rejected` and `Contention` — moving the
streaming observer to a landblock we explicitly refused to place into.
## Gate
Unchanged: complete Release solution suite, not a focused subset. Pre-change
baseline is 10,844 / 4 skipped / 0 failed; the first pass reached 10,848 with
the defects above, so a green suite is necessary and demonstrably not
sufficient. Both reviews must be re-run on the fixed diff before commit.
---
# ROUND 2 — residuals after the R1-R9 fix round (2026-08-03)
Both delta reviews returned FAIL again. Suite is green at 10,853 / 4 / 0, which
again proves nothing. R2, R3, R4, R5, R6, R7 and R9 are confirmed genuinely
fixed and must not be churned. Three blocking residuals remain, and **two of
them are defects in the R1 reissue mechanism itself.**
**Root of the problem: `_pending` has no single owner and no single lifecycle
rule.** Round 1 bolted reissue onto ad-hoc per-branch bookkeeping. B1 wants MORE
reissuing, N1 wants LESS, and N2 wants reissue to be a DIFFERENT route — they
look contradictory only because there is no unifying rule. There is one.
## The unified mechanism (implement exactly this — it replaces the ad-hoc rules)
`RuntimeEntityPlacementToken` already carries `PositionAuthorityVersion`
(`RuntimeSetPositionState.cs:50`). Make that the single decision input.
**One rule:** the drive owns at most one in-flight placement for the local
player. After any terminal outcome, and on every `Advance()`, compare the
committed/parked token's `PositionAuthorityVersion` against the live record's
current `PositionAuthorityVersion`:
- **Equal** — the canonical accepted authority has not moved since this
operation began. Nothing is outstanding. Clear `_pending`. Do not reissue.
- **Advanced** — a newer accepted Position arrived while we were in flight, and
it may have been the thing that killed our operation. Consult the newest
accepted event's disposition (do NOT reuse `stale.Route`):
- still **ForcePosition** — reissue, re-classifying from the current record.
- now an ordinary **Apply** — clear `_pending` and do NOT reissue. The
correction was superseded by newer server truth; the ordinary route owns
that pose. This is not a silent drop: retail applies each event as it
arrives, and a force correction overtaken by a newer position is moot.
Route every terminal branch through one `_pending` funnel. No branch may assign
or clear it directly.
### B1 — BLOCKING — a force correction is still silently dropped (conformance)
When a parked operation wakes and its `Place` is ACCEPTED by the sink, the
operation leaves `_operations` but the completion is retained. `CancelCoreDeferred`
then returns early at `RuntimeSetPositionState.cs:5141` without reaching
`ForgetPlacementCompletionCore`, so the retained completion survives. The next
ForcePosition hits `HasRetainedCompletion` (`:1319`) -> invalid token ->
`Contention` (`RuntimeAcceptedPositionDriveController.cs:289-295`); both hosts
return without placing or acking, and the next `Advance()` consumes the OLD
completion and acks the OLD pose. That packet's correction is lost.
One-frame window on the graphical host only (`_session.Tick()` inbound dispatch
precedes `RetryPending()` in `RetailLiveFrameCoordinator`); headless is immune
because its pump is adjacent to the readiness check. The DECLINED-`Place`
variant is unaffected and needs no change.
The unified rule fixes this: the new packet advanced `PositionAuthorityVersion`
past the committed token, and the newest event is a ForcePosition, so it
reissues.
### N1 — BLOCKING — stale `_pending` causes a second placement AND a second ack
`SubmitAndResolve(firstAttempt: true)` (`:297`) never inspects `_pending`, and
only the `!firstAttempt` branches clear it (`:508-511`, `:482-484`, `:549-551`).
So: park -> `Forget` wipes the watch -> the same packet's ForcePosition Begins
cleanly and Commits -> ack fires -> `_pending` still holds the dead P1 -> next
`Advance()` finds the watch dead -> `ReissueFromCanonical` -> **a second
canonical placement and a second outbound `AutonomousPosition` for one server
correction.**
That is the double-apply/double-ack class this entire slice exists to delete
(`670f307c`), reintroduced. `AssignPending` does not catch it because it is only
reached on the DeferredCell/retryable branches. The unified funnel fixes it:
equal versions -> clear, no reissue.
### N2 — BLOCKING — reissue applies force semantics to an ordinary pose
`ReissueFromCanonical` (`:418-447`) reuses `stale.Route` verbatim —
`SetPositionSimple` + `Teleport|Slide|SendPositionEvent` +
`SendPositionImmediately: true`. But the commonest way a park dies is an
ordinary `Apply` Position, whose retail route
(`RuntimeAuthoritativePositionRouteClassifier.cs:368-388`) is
`Interpolate`/`NoPositionOperation`, `PhysicsSetPositionFlags.None`,
`ConstrainPhase.BeforePositionOperation`, `SendPositionImmediately: false`.
So the reissue converts an ordinary server echo into a hard `Teleport|Slide`
canonical placement, sends an ack retail would never send on that branch, and
skips the `ConstrainTo` the ordinary branch runs. My round-1 direction sanctioned
re-issuing THE CORRECTION; it did not sanction re-classifying a different
disposition's pose as a force. The unified rule fixes this by consulting the
newest accepted disposition.
If any residual divergence remains after this, it needs a
`docs/architecture/retail-divergence-register.md` row in the same commit.
### B2 — BLOCKING (record accuracy) — the plan claims coverage it does not have
`docs/plans/2026-08-02-placement-cutover.md:287` reads "R8 added the App-layer
double-write source pins the plan's own acceptance item required." That is a
claim of coverage. The truth, per the adversarial review:
- acceptance item 2's first half is **source-pinned, not proven** — the
`Assert.Single` regex would still pass if a second write were spelled
differently, and no test exercises the branch;
- acceptance item 2's second half — **"the committed projection is what moves
the render entity"** — is **uncovered at any layer**. No test drives a route-2
ForcePosition through `RuntimePlacementPresentationSink` /
`TryApplyRuntimePlacementPlace` and asserts the `WorldEntity` moved.
Correct the text to record the gap explicitly. A documented gap is acceptable;
a false claim of coverage is not. Same rule that produced R7.
## Non-blocking — record, do not fix in this round
- **N3** — headless never calls `RetryPending` after construction (grep finds no
caller outside `src/AcDream.App/`). R4's fix depends on the subscription's
retry, so a declined headless `Place` would wedge the ordered stream. Latent,
not proven reachable. File it.
- **N4** — `Advance()` lacks the `_driving` reentrancy latch its template
`RuntimeFirstEntryDriveController.DriveAll:128-148` has. No live re-entrant
path today. Hygiene.
- **N5** — `CenterOnAcceptedForcePosition` does not restore
`controller.LocalEntityId = record.LocalEntityId ?? 0u` (inert today, but an
unreplaced deletion); `_movementTruthDiagnostics.OnServerEcho` no longer fires
for a local ForcePosition (diagnostic only).
- **R9 residue** — `ConstraintManager.cs:25` and `PhysicsBody.cs:442` still cite
the deleted `BlipPosition` in `<c>` tags (build-safe, but false docs).
- **Route-1 ack** — the plan required confirming whether the ack fires while an
initial-Create residence owns the record. It does not; `SendPositionImmediately`
is consumed only as a trace fact in the continuation executor (`:717`, `:2576`).
Not a regression, but the plan said file it. File it.
- **AD register row** — the headless 3x3 collision window is now a named member
of the Runtime-facing `IRuntimeDirectWorldProjection` contract with an ordering
requirement retail has no analogue for, and no existing row covers it (AD-6 is
retired; AD-2 is the graphical reveal barrier). Recommend a row.
- **Stale comment** — the `HeadlessSessionHostTests` comment references "the
previous 50.48f assertion", which does not exist at HEAD.
---
# ROUND 3 — final round (2026-08-03)
The round-3 **adversarial** review returned **PASS**. The round-3
**conformance** review returned **FAIL on one item**. This round closes that
item and files the adversarial review's non-blocking findings. The round-2
unified `_pending` funnel was confirmed sound by both reviewers and was NOT
restructured.
## The blocker — a terminal-without-commit sent no ack (CLOSED)
`SettlePending`'s Equal branch was reached both by a successful commit and by a
terminal outcome that never committed (non-retryable prepare failure, the
`default:` Rejected/Cancelled branch, and both `Advance` death branches). In the
non-commit case the body never moved AND no outbound `AutonomousPosition` left.
The conformance reviewer proposed a `committed` flag plus a
one-re-issue-per-`Advance` guard. That is more than retail requires, and the
retail evidence was re-verified from
`docs/research/named-retail/acclient_2013_pseudo_c.txt` before coding:
- `SmartBox::BlipPlayer` @0x00453940 (line 92528) calls
`CPhysicsObj::SetPositionSimple(this->player, edi_1, 1)` @0x00453968 and
**discards its return value**. `BlipPlayer` itself returns `void`.
- `CPhysicsObj::SetPositionSimple` @0x005162B0 (line 284276) is declared
`enum SetPositionError __thiscall`. Other retail call sites DO test it —
`if (CPhysicsObj::SetPositionSimple(...) == OK_SPE)` at @0x0055605D and
@0x00556021 — which proves the discard in `BlipPlayer` is deliberate, not a
decompiler artifact.
- `SmartBox::HandleReceivedPosition` @0x00453FD0's FORCE_POSITION branch calls
`SmartBox::BlipPlayer` @0x00454074, stamps `update_times[0]` @0x00454079, then
runs `cmdinterp->SendPositionEvent()` @0x00454091 **unconditionally** and
returns @0x0045409D.
Retail's semantics are therefore: **attempt the placement once; if it fails the
body simply does not move; acknowledge regardless; never retry.** No commit flag
and no recursion guard are needed to express that.
**Implemented.** The ack is now sent exactly once per BEGUN placement, at its
terminal outcome — from `ReconcileAndAcknowledge` on the commit path, or from
`SettlePending` on a non-commit terminal. `SettlePending` gained a
`positionEventOwed` parameter; `Pending` gained a `PositionEventOwed` field so
the re-issue retry marker (which stands for a packet whose placement was never
begun) cannot double-ack. The commit paths pass `false` because their ack has
already left. The non-commit ack runs no reconciliation — the body did not move,
so there is no committed frame to reconcile — and therefore carries the body's
unchanged pose, which is exactly what retail's ack carries after a failed
`SetPositionSimple` and is informative to the server: its force did not take.
The `CanSendPositionEvent` gate was left untouched; it is retail's own
(`CommandInterpreter::SendPositionEvent` @0x006B4770 tests the transient-state
contact bits), so a legitimately airborne body still suppresses the send on both
paths.
`ReconcileAndAcknowledge` was split so both paths share one outbound site,
`SendPositionEvent`.
## Other items closed this round
- **AD-62 rewritten.** The `DeferredCell`-park precondition is dropped — it was
never required, and the never-parked failure paths reach the same outcome. The
row now leads with the general rule and keeps the named shapes as examples,
adds the externally-blocked `Contention` shape (nothing recorded, nothing
pumps it) and the other `PositionAuthorityVersion` advances (`TryApplyPickup`
`RuntimeEntityObjectLifetime.cs:1116`, `CommitPositionChannelUpdate` `:2041`,
`AdvanceCreateAuthority` `:2466`), and separates the shapes that now lose only
the re-apply from the narrower shapes that still lose the ack too.
- **Overstated doc corrected.** `AcceptedForceObservation`'s comment claimed the
record's current version equals the recorded force's version *if and only if*
the newest accepted event was that force. False — `AdvancePositionAuthority`
has four call sites. It is now stated as the one-way test it actually is.
- **Vacuous assertion deleted.** The `gameActions.Count <= 2` assertion in
`Advanced_ReissuesWhenTheNewestAcceptedEventIsStillAForcePosition` could not
fail: that fixture's `CommitLandblockCollision` adds both landblocks at
`worldOffsetX/Y: 0f` while the world frame places the deferred landblock at
+192/+192, so the body lands over no terrain, `InContact` is false, and every
ack is suppressed — the count is 0. It was also too loose to encode "at most
one per packet". Deleted rather than shipped; the test's real discriminators
(body position, `PendingCount`) stay.
## Tests
Two added, both with a verified discrimination check (the implementation was
temporarily broken in each direction and the intended test observed to fail,
then reverted and re-verified):
- `TerminalWithoutCommit_SendsExactlyOnePositionEventAndLeavesTheBodyUnmoved` —
a park retired without committing sends exactly one `AutonomousPosition`,
performs no placement of its own, and never repeats on further pumps.
- `Committed_SendsExactlyOnePositionEventAcrossTheCommitAndTheSettle` — the new
settle-side ack does not become a second ack on the committed path.
Two existing tests changed their ack expectation from `Assert.Empty` to
`Assert.Single`, because they exercise terminal-without-commit paths whose
`Empty` encoded the defect this round removes:
`Equal_ClearsPendingWithoutReissuingWhenNoNewerAcceptedAuthorityArrived` and
`Advanced_DoesNotReissueWhenTheNewestAcceptedEventIsAnOrdinaryApply`. In the
latter the single ack belongs to the FORCE packet, not to the ordinary echo —
retail's ordinary branch has no unconditional `SendPositionEvent`.
Measurement note, recorded because it corrects an assumption in this file's
round-2 text: the `DeferredCell` park these fixtures use is the POST-engine
quiescence park, so `_physics.Engine.SetPosition` has already moved the
canonical body to the destination while the placement itself is withdrawn and
parked. The new test therefore captures its unmoved/no-further-placement
baselines at the park, and asserts them across the terminal settle, which is the
thing under test.
## Filed, not fixed
`docs/ISSUES.md` #293 (the `DeferredCell` branch still consumes `Withdraw`
receipts the sink may have declined — the same shape R4 removed for `Place`),
#294 (`ReconcileAndAcknowledge` runs before the funnel's currency guard on the
deferred wake), #295 (the retry marker inflates
`AcceptedPositionDrivePendingCount`, which is an in-flight-placement counter),
#296 (a retryable prepare is reported to hosts as `Contention`, conflating a
retained-and-pumping case with a dropped one).
## Gate
Complete Release solution suite, unchanged discipline: green is necessary and
demonstrably not sufficient — all four prior states were green and three were
defective.

135
docs/research/2026-08-03-c4-route-2-visual-gate.md Normal file
View file

@ -0,0 +1,135 @@
# C4 route 2 — ForcePosition: connected visual gate (2026-08-03)
The user-facing acceptance test for route 2. Route 2 is code-complete and
suite-green before this runs; this document is the hand-off.
## Why the obvious recipe does NOT work
The route-2 contract's acceptance line says *"ACE `@teleport`-style
displacement"*. That is wrong about which route it exercises, and following it
would have produced a false pass.
Verified in ACE this session: `PositionPack`'s constructor
(`references/ACE/Source/ACE.Server/Network/Structure/PositionPack.cs:36-57`)
advances `ObjectTeleport` when `adminMove == true` (lines 49-52) and only ever
*reads* `ObjectForcePosition` (line 54). Every admin move command —
`@teleto`, `@teletome`, `@teleloc`, `@movetome` — routes through
`Player_Location.cs:654 Teleport()` / `SendUpdatePosition(true)` and therefore
advances **TELEPORT_TS, not FORCE_POSITION_TS**. Those commands exercise
**route 3**, not route 2.
`SequenceType.ObjectForcePosition` is advanced at exactly **two** places in the
whole ACE tree:
1. `references/ACE/Source/ACE.Server/WorldObjects/Player.cs:1148` — the PK Lite
entry collision bump.
2. `references/ACE/Source/ACE.Server/WorldObjects/Player_Tick.cs:488` — the
anti-cheat z-position rubber-band.
(2) requires the server to believe you are fly-hacking — same landblock, a
claimed Z more than 10 units above your last ground contact, more than a second
after your last jump, Jump skill under 1000, and still flagged airborne. It is
not reachable by legitimate play and there is no command path into it. Do not
build the gate on it.
So (1) is the gate.
## The only reliable lever is deferred — what that means
The reachable trigger is the PK Lite entry-collision bump, which requires
retail's `@pklite`. That is a **client** command, not a server one — ACE has no
`pklite` text-command handler, so typing `@pklite` into chat today forwards as
inert text. Retail's client turns it into a game action instead:
- `ClientCommunicationSystem::DoPKLite` @`0x0057A490`
(`acclient_2013_pseudo_c.txt:390106`) — rejects with error `0x507` when
`ACCWeenieObject::IsPlayerKiller` @`0x0058C910` is true (PK bit `0x20` OR
PKLite bit `0x2000000`), otherwise calls
- `CM_Character::Event_EnterPKLite` @`0x006A13F0` (line 680071) — a 12-byte
parameterless game action, opcode `0x28F`, no payload.
acdream does not implement it, and **the user deferred implementing it
(2026-08-03).** Scoping is preserved in this session's research so it can be
picked up cheaply: ~40 lines of production code across `ClientCommandId`,
`RetailClientCommandCatalog`, `ClientCommandRequests.BuildParameterless`,
`WorldSession`, `ClientCommandController`, `LiveSessionCommandRouter`, and
`LiveSessionRuntimeFactory` — every pattern already exists, including
`WeenieError 0x0507`.
**Consequence, stated plainly: route 2's own behaviour is NOT visually
verifiable in this campaign.** Nothing a user can do makes ACE emit a
ForcePosition. Route 2's acceptance therefore rests on its automated Runtime /
App / Headless tests and the complete Release suite. The connected pass below
is a **regression check on the blast radius**, not acceptance of the new route.
Do not record it as the latter.
## What the connected pass actually covers
Launch acdream in **Release** with `ACDREAM_RETAIL_UI=1` against the local ACE
at `127.0.0.1:9000`.
Route 2 deletes `PlayerMovementController.BlipPosition` and
`HeadlessSessionWorldProjection.BlipLocalPlayer`, removes App's generic-tail
double-write for the local player, and re-routes the local player's accepted
placement through the canonical Runtime SetPosition transaction. So the things
to confirm are that ordinary play is untouched:
- Ordinary running, turning, walk/run toggle. No tethering, no rubber-band, no
drift against the server.
- A jump and a landing.
- Walking through a doorway into an interior and back out.
- A portal recall, and a portal into a dungeon.
- Two-client observation: `+Acdream` seen from the retail client moves smoothly
and lands where acdream shows it.
Anything wrong there is route 2's fault even though route 2 did not intend to
touch it.
## Optional cheap shot (may not fire)
The second ACE call site is the anti-cheat z-position rubber-band
(`Player_Tick.cs:459-490`). It needs: same landblock as your last ground
contact, a claimed Z more than 10 units above it, more than a second since your
last jump, Jump skill under 1000, and the server still flagging you airborne.
There is no command path into it and normal play cannot satisfy it (falling
makes the Z delta negative, and walking up terrain keeps refreshing the ground
position), but a `@teleloc` straight up ~15 units within the same landblock is
a two-minute experiment with a definitive tell: ACE's console logs
`z-pos hacking detected for +Acdream` at `Player_Tick.cs:486` immediately
before it force-bumps you.
If that line appears, you have a genuine ForcePosition and the checks below
apply. If it does not, the route is untested by observation — which is the
expected outcome.
**If a ForcePosition does occur, must be true:**
- You end up at the corrected position and stay there. No visible double-apply,
no snap-then-yank-back over one or two frames.
- **Your facing does not change.** Retail's force branch replaces the
destination heading with your current heading before placing
(`HandleReceivedPosition` @`0x00453FD0`, `Frame::set_heading` at
`0x00454068`).
- Exactly **one** outbound `AutonomousPosition` for the correction.
**The two named behaviour changes:**
1. **The ack now fires after the canonical commit, not before it.** Previously
the client told ACE "got it, I'm here" before deciding where "here" was.
Symptom of a regression: ACE re-sending corrections, or a visible fight
between client and server position after the bump.
2. **The ForcePosition route no longer re-arms the constraint leash.** Retail's
force branch returns at `0x0045409D`, ahead of all three `ConstrainTo` call
sites (`0x00454272`, `0x0045418A`, `0x004541EC`); our old `BlipPosition`
re-armed the leash citing a branch it was not on. #167 was a leash bug, so
this is the change most worth your eyes if you get a bump. Symptom of a
problem: after the bump, movement feels tethered, rubber-bands back toward
the pre-bump spot, or the leash trips on ordinary running shortly after.
## Known, deliberately unchanged
Retail's `SmartBox::PlayerPositionUpdated` (@`0x00453870`) gates its
`set_viewer` / `LScape::update_viewpoint` re-seat on
`distance >= GetAutonomyBlipDistance` (`0x004538C0-0x004538E2`). We publish the
render root unconditionally. Not changed in this slice; recorded here so the
next reader does not rediscover it as a bug.