acdream/docs/plans/2026-08-02-placement-cutover.md

# Placement production cutover — campaign plan (2026-08-02)

The final leg of the remaining physics-divergence campaign before AP-22 and
AD-10: route graphical AND headless production placement through the
residence + continuation-executor owner (`38fd4b8d` / `30012361` /
`5db3de3c`), delete the legacy duplicate authorities, and retire AP-1/AD-1
behind connected + user-visual gates.

**Inputs (read in order):**
1. [`2026-08-02-runtime-continuation-executor-handoff.md`](../research/2026-08-02-runtime-continuation-executor-handoff.md)
   — the completed dormant mechanism and its cutover notes.
2. [`2026-08-02-cutover-route-inventory.md`](../research/2026-08-02-cutover-route-inventory.md)
   — the full 8-route, both-host call-chain inventory with exact file:line
   for every duplicate authority to remove. THE map for all slices below.
3. [`2026-07-31-remaining-physics-campaign-handoff.md`](../research/2026-07-31-remaining-physics-campaign-handoff.md)
   — the original per-route requirements and prerequisite definitions.

**Standing discipline per slice:** pinned contract → single implementer →
independent retail-conformance + architecture/adversarial reviews (both must
PASS on the final diff) → focused + complete Runtime + Release build +
complete solution gates → bisectable behavior commit (register rows in the
same commit) → docs/handoff commit. No workarounds; no fused slices.

## Confirmed pre-cutover gaps (from the inventory)

- The executor publishes only generic entity deltas; nothing bridges its
  completion to `RuntimePlacementProjectionChannel`, so no host can learn
  "my initial placement committed" through the built observer seam.
- No atomic controller/body publication owner exists (prerequisite C);
  App and headless hand-write divergent `PlayerMovementController`
  construction, and `SubmitPreparedPlacement` requires a canonical
  `PhysicsBody` that nothing currently publishes atomically.
- The dormant placement path's 1,880 B/operation (2,048 cap) allocation
  remains the activation blocker for frame-frequency routes.
- `Execute`'s live inputs (`UsePositionFromServer`, `PlayerDistance`) are
  computed by no host; they must derive from Runtime's own character-option
  and local-player owners.
- `RuntimePortalPlacementAuthority` has zero producing call sites; the
  adapter from `RuntimeWorldTransitState` does not exist.
- The exact-Setup mover chain (`PrepareMover` /
  `RuntimeSetPositionMoverPreparer.TryBuild` /
  `IPreparedCollisionSource.ReadSetupCollision`) exists piecewise, unwired.
- Route-6 split-recovery creates need an effect-replay suppression signal;
  route-7 needs `TryCommitParent`/`CommitWithdrawal` cancellation-symmetry
  fixes and host-visible cancellation receipts; headless lacks any
  parent-realize sequence (pre-existing, adjacent).

## Slices

- **C0 — Runtime bridge + live inputs — COMPLETE at `67f63e85`
  (2026-08-02, dual reviews PASS).** The executor publishes an
  acknowledge-only `ExecutorCompleted` receipt through the one placement
  stream (registered before dispatch; correlation reaped on
  acknowledgement/discard/clear; `PendingCompletionReceiptCount` in
  `IsConverged`); all three production sinks acknowledge-and-ignore the
  kind via early returns proven behavior-preserving for every other kind
  (sanctioned seam completion — provably inert, no production publisher);
  `UsePositionFromServer` derives retail-exactly from
  `RuntimeCharacterState.AutonomyLevel != 2` and `PlayerDistance` from the
  live movement controller with null-safe fallback to the caller struct;
  `TryPrepareAndSubmitAuthoredPlacement` chains the prepared-collision
  Setup read through `PrepareMover` to submission with zero validation
  changes; `TryCommitParent`/`CommitWithdrawal` gained the sibling
  cancellation flow (the `LeaveWorld` omission in `TryCommitParent` is
  retail-REQUIRED per `set_parent` 0x00515A90:283832-283833's single gated
  `leave_world`). Not fully dormant by design: the two cancellation fixes
  change live Runtime paths production already calls; everything else has
  no production caller.
  **C3 prerequisites recorded from C0's reviews:** (a) the completion
  receipt/trace surface is internal-only — C3 must define the public host
  consumption shape when it wires the hosts; (b) `PlayerDistance` is
  resolved once per `Execute` entry, not per continuation — a multi-Position
  FIFO classifies later entries against entry-time distance (documented
  deferral; refine at C3/C4 if the connected gates show it matters);
  (c) any future host exposure of `TrySetAutonomyLevel` must carry retail's
  `SendAutonomyLevelEvent` (699550).
- **C1 — atomic controller/body publication — SATISFIED BY EXISTING
  MECHANISM (research finding 2026-08-02, plan amended same session).**
  `RuntimeLocalPlayerPhysicsPublicationState` (1,033 lines) plus the
  ~15-method dormant local-activation family on `RuntimeSetPositionState`
  already implement the full sanctioned option-2 transaction:
  off-canonical preparation against a scratch quantum clock and a sealed
  candidate controller, one validated atomic Commit, and a staged
  Evaluate/Commit/FinalizeActivation chain re-validated against
  PhysicsOwnershipEpoch/ObjectClockEpoch/ControllerOwnershipEpoch/session
  identity at every entry — with zero production callers. See
  [`2026-08-02-canonical-body-writer-map.md`](../research/2026-08-02-canonical-body-writer-map.md)
  (6 canonical body writers; the two host escape hatches; both hosts'
  divergences). The remaining work — routing both hosts' local-player
  construction through the publication lifecycle, sealing the public
  `RuntimeLocalPlayerMovementState.Controller` setter, retiring App's
  direct object-clock bypasses, and containing headless's uncaught
  prepared-collision `InvalidDataException` — IS the C3 route-1 flip and
  moves there. No separate C1 commit.
- **C2 — placement allocation budget — COMPLETE at `63c601ff`
  (2026-08-02, dual reviews PASS after two fix rounds).** 2,032 → 944
  B/op via pooled operation envelopes (bounded, reset-at-rent, double-
  retire guarded, reset/dispose-cleared, ledger-visible), a cached
  collision-callback delegate over an explicit context stack, and a
  non-boxing pending-head read; gate tightened to 1,536. The pooling
  forced a class-wide staleness rework: captured-token-vs-fresh-lookup at
  every reentrancy-spanning frame (26-site audit), hoisted stack locals
  for retail's handle_all_collisions bits, token-gated bookkeeping
  writes, and a deliberately identity-agnostic settle path (retail's
  SetPositionInternal completes unconditionally even for displaced
  operations).
  **Residual floor (documented at the gate, decision deferred to the C3
  activation gate where the user is in the loop):** ~520 B/op inside
  Core's `PhysicsEngine.SetPosition` (transition init / query-footprint
  materialization — a potential C2b if C3's connected profile shows it
  matters) and ~208 B/op of sorted-tree node per pending receipt.
  **Maintenance notes from review (no action):** the no-reentrancy
  proofs on the 15 surviving reference-based currency checks are
  comment-enforced; `IsCurrent(Operation)` remains available and a new
  reentrancy-spanning call site would silently inherit the tautology —
  its doc comment warns.
- **C3 — spawn-frequency cutover: routes 1 + 8 — DECOMPOSED 2026-08-02
  after the first implementation pass stopped with findings.** C3-1 (the
  public executor-completion surface via
  `RuntimePlacementProjectionChannel.TryGetInitialCreateCompletion`)
  landed separately. Two structural gaps halted the flip, both real and
  neither in the planning docs:
  **(B)** the local player's residence lease opens its SetPosition
  operation at Create time, but `SubmitPreparedPlacementCore` requires a
  pre-existing canonical body that only the zero-caller publication chain
  can attach — first-entry needs an explicit resumable sequence
  (begin-placement → publication Prepare/Commit attaches the body →
  authored-mover submit → Place receipt → Execute), which matches the
  campaign handoff's route-1 required order but exists nowhere as a
  driveable state machine;
  **(C)** ordinary remote-creature Creates classify to `SetPosition` but
  have NO production body-construction path at Create time (bodies arrive
  with first motion today; retail constructs physics at CreateObject via
  `ACCObjectMaint::CreateObject`/`set_description`, which our retail
  notes fully document — the defaults come from the wire PhysicsDesc,
  not invention).
  Sub-slices, each with the standing contract/dual-review/gate
  discipline:
  - **C3a — Runtime first-entry sequencing — COMPLETE at `960373df`
    (2026-08-02, dual reviews PASS).** `RuntimeLocalPlayerFirstEntryState`:
    five stages (mover-prep → publication Prepare/Commit → activation →
    acknowledgement → Execute) in retail's own order — mover shapes
    BEFORE placement, matching makeObject/set_description preceding
    enter_world; the original contract prose had it backwards and the
    tested preconditions forced the faithful order. Acknowledge-stage
    authority discrimination, automatic convergence through the (now
    multicast, snapshot-iterated) retirement fan-out, ownership-ledger
    fold, transactional late-bind Publication seam. Dormant: C3c's first
    act is the GameRuntime binding + production Advance drive.
    **Carried findings for C3c:** the controller is live from the
    activation commit onward (abandonment leaves it to ordinary entity
    teardown — retail has no entry-flow rollback); EvaluateActivation's
    post-commit DeferredCell overload is encapsulated behind Advance.
  - **C3b — remote body construction at Create — COMPLETE at `0934a121`
    (2026-08-02, dual reviews PASS).** `RuntimeRemoteBodyDescription` +
    `RuntimeRemoteFirstEntryState`: the full `set_description` order with
    the byte-certain gates (friction [0,1] inclusive, NaN sanctioned-skip;
    elasticity clamp with retail's unordered-to-zero; translucency
    != 0.0f), the movement-branch discriminator on retail's
    `movement_buffer != 0` (empty-buffer → placement branch, no autonomy),
    motion-table zero-id pass, ctor-defaults for absent wire fields, and
    never-clobber coexistence with the build-at-first-motion production
    path. The acknowledge discriminator is one shared body
    (`RuntimeFirstEntryAcknowledgement`) for both conductors. Dormant.
  - **C3c — the host flips (production) — COMPLETE at `529e0e9d`
    (2026-08-02, dual Opus reviews: initial FAIL 2+2 MAJOR → R1 fix
    round → delta PASS both).** Both hosts register initial Creates
    through residence + conductors via the shared
    `RuntimeFirstEntryDriveController`; Controller setter sealed;
    rebucketing presentation-only strictly while the residence is
    ACTIVE (post-residence entities take the full legacy path including
    the `prepare_to_enter_world` clock edges); content-less headless
    keeps pre-flip direct registration. Five fix slices landed inside
    the cutover, each connected-gated: F1 (Runtime ownership seam for
    movement stats/server physics — the post-logout retired-controller
    crash), F2 (the login activation wedge: admission-prefix gate
    factored from the seal, rearm generation identity, auto-entry
    requires the published controller), F3 (landblock-prefix 0-sentinel
    → explicit absent-id; corner landblocks legal), F4 (diagnosis only:
    the nine-stop soak's convergence failure is pre-existing `6b28ff99`
    whole-world collision-clone throughput — its fix is the next slice
    before C5), F5 (local-player first-entry ground contact via the
    shared `SpawnPlacementSettler` at `FinalizeActivation`; the
    standing-cast airborne rejections are gone; register AD-61). R1
    additionally armed the login constraint leash at the committed
    placement (`HandleReceivedPosition` 0x00453FD0 analog) and
    refreshed AD-42. Final gates: complete solution 10,816/0/4 skips;
    lifecycle/reconnect gate PASS (`connected-world-gate-20260802-
    175401`). Closeout:
    [`2026-08-02-c3c-cutover-closeout.md`](../research/2026-08-02-c3c-cutover-closeout.md).
    **Carried to C4/C5:** route-1 far-Create service-window conversion
    if either streaming/broadcast radius changes (#276); the
    window-departure park narrowing; `NotifyRetirement`-on-active-entry
    subscriber invariant; the reachable equip-mid-conductor fail-fast;
    settle-CellId discard (#276-adjacent, see ISSUES).
- **C4 — remaining routes: 2 (ForcePosition), 3 (portal, with the
  `RuntimeWorldTransitState` → `RuntimePortalPlacementAuthority` adapter),
  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).** 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.** Delete every superseded legacy
  path; parity tests; exact lifecycle/reconnect + canonical nine-stop
  connected routes; two-client observation; **user visual matrix** (the
  campaign's stopping point for user acceptance). Retire AP-1, AD-1,
  AP-131, AD-60's legacy half, and close #275. Update register/roadmap/
  milestones/architecture/memory + successor handoff.

After C5: AP-22 (authored collision shapes), then AD-10 (remote
contact-plane projection), then the campaign's final matrix and ledger
closeout; vendor Slice 5 resumes.