# C1 body/controller-publication writer map (2026-08-02)

Repo: `C:\Users\erikn\.codex\worktrees\af5e\acdream`, branch `codex/port-claude-agents`,
HEAD `ae296393`. READ-ONLY research; this file is the only write target.

Context read: `docs/plans/2026-08-02-placement-cutover.md` (slice C1),
`docs/research/2026-07-31-remaining-physics-campaign-handoff.md` (rejected-prototype
section, lines 143-168; prerequisite C, lines 203-221), and
`docs/research/2026-08-02-cutover-route-inventory.md` route 1 + prerequisite-C
section (lines 174-220) + route 8 (headless).

---

## 1. Every writer of `RuntimeEntityRecord.PhysicsBody`

`PhysicsBody` is `public PhysicsBody? PhysicsBody { get; private set; }`
(`src/AcDream.Runtime/Entities/RuntimeEntityRecord.cs:72`). The ONLY mutator is
the internal method `SetPhysicsBody(PhysicsBody? body)`
(`RuntimeEntityRecord.cs:176-182`):
```
internal void SetPhysicsBody(PhysicsBody? body)
{
    if (ReferenceEquals(PhysicsBody, body)) return;
    PhysicsBody = body;
    PhysicsOwnershipEpoch++;   // <-- the ONLY place PhysicsOwnershipEpoch is bumped
}
```
So every "writer" is a caller of `.SetPhysicsBody(...)` (all 6 call sites, confirmed
by full-repo grep, zero others):

1. **`RuntimeEntityDirectory.cs:359`** — inside
   `GetOrCreatePhysicsBody(RuntimeEntityRecord record, Func<incarnation,PhysicsBody> factory)`
   (need exact surrounding signature — read below). Public/internal API used by
   the route-1 "SECOND, narrower body-construction duplicate authority" for
   non-player static-animating physics objects
   (`DatLiveEntityProjectionMaterializer.cs:1003-1016`, per the route inventory).
   Guard: only sets if record has no body yet (idempotent-create pattern) — see
   full read below for exact guard.
2. **`RuntimeEntityObjectLifetime.cs:766`** — `Entities.SetPhysicsBody(canonical, null)`
   inside a teardown method (need to confirm exact method — likely delete/retire
   path, paired with `Entities.SetPhysicsBodyAcquisitionInProgress(canonical, false)`
   at line 767 in the SAME method). Clears body on deletion/teardown.
3. **`RuntimeLocalPlayerPhysicsPublicationState.cs:405`** — `candidate.Record.SetPhysicsBody(candidate.Body)`
   inside `Commit(token, out activationToken)` (lines 373-411). **THIS IS THE
   DORMANT OPTION-2 MECHANISM** — see section 4 below. Guarded by `IsCurrent(candidate)`
   (epoch/session/identity/null-state re-check, lines 891-922) immediately before,
   and by `_physics.SetPosition.PrepareDormantLocalActivationOwnership(...)` called
   first (line 394) as the "seal the exact SetPosition owner before the
   irreversible no-fail suffix" step — i.e. this call site DOES chain into
   PrepareDormantLocalActivationOwnership per task 4's target.
4. **`RuntimeLocalPlayerPhysicsPublicationState.cs:1025`** — `_entities.SetPhysicsBody(activation.Record, null)`
   inside `DiscardActivation()` (994-1032), the rollback/teardown path for the
   SAME dormant mechanism — only fires if `_entities.IsCurrent(activation.Record)`
   AND `ReferenceEquals(activation.Record.PhysicsBody, activation.Body)` (i.e.
   never clobbers a body some OTHER newer owner already installed — the exact
   anti-pattern the rejected prototype failed on).
5. **`RuntimePhysicsState.cs:1558`** — `Entities.SetPhysicsBody(record, candidateBody)`
   — need full read; this is inside the remote/projectile body-binding family
   (see section 3).
6. **`RuntimePhysicsState.cs:1666`** — `Entities.SetPhysicsBody(record, candidate)`
   — need full read; this is the OTHER binding site, guarded by
   `PhysicsBodyAcquisitionInProgress` (set true at :1645, cleared at :1676/1678).

**Writer count: 6 call sites, across 3 files** (`RuntimeEntityDirectory.cs` x1,
`RuntimeEntityObjectLifetime.cs` x1, `RuntimeLocalPlayerPhysicsPublicationState.cs` x2,
`RuntimePhysicsState.cs` x2).

## Consumers of `PhysicsOwnershipEpoch`

Only bumped in one place (`RuntimeEntityRecord.SetPhysicsBody`, above). Consumers
(all in `RuntimeLocalPlayerPhysicsPublicationState.cs`) treat it as a
compare-and-reject epoch stamped into every token/activation struct:
- `RuntimeLocalPlayerPhysicsPublicationToken.PhysicsOwnershipEpoch` (field, :53)
  captured at `Prepare` time (:314).
- `RuntimeLocalPlayerPhysicsActivationToken.PhysicsOwnershipEpoch` (:70) captured
  as `token.PhysicsOwnershipEpoch + 1UL` (:328) — i.e. the activation token
  encodes "the epoch AFTER my own commit bumps it", so `IsActivationCurrent`
  (931-962) and `IsActivationOwnershipEnvelopeCurrent` (717-745) comparing
  `activation.Record.PhysicsOwnershipEpoch == activation.Token.PhysicsOwnershipEpoch`
  will FAIL (reject) the instant any OTHER writer (remote/projectile bind, GC
  clear, non-player static body creation via `RuntimeEntityDirectory` — none of
  which should ever touch a local-player record, but the check is defense-in-depth)
  touches the same record's PhysicsBody between prepare and commit.
- `IsCurrent(candidate)` (891-922, pre-Commit re-check) also compares
  `candidate.Record.PhysicsOwnershipEpoch == candidate.Token.PhysicsOwnershipEpoch`
  (unincremented — i.e. "nobody touched the body between Prepare and Commit").

**This IS the reentrancy defense the rejected prototype lacked** — see section 6.

## 2. The two production local-player controller constructions, end to end

### Graphical: `PlayerModeController.BuildControllerAndCamera`
`src/AcDream.App/Input/PlayerModeController.cs:244-525`. Constructor list
(52-74) shows it is injected with `RuntimeLocalPlayerMovementState controllerSlot`
(the SAME slot type headless writes) — confirms the route-inventory's "open
question" (2026-08-02-cutover-route-inventory.md:204-207): **App DOES write
`_controllerSlot.Controller = controller` directly, at line 486.** Not a
mystery/asymmetry — both hosts write the exact same public setter.

Steps, in order:
1. `_approachCompletions.BeginControllerLifetime()` (250) — App-only approach
   lifecycle token.
2. Capture rollback snapshots: `_camera.CaptureState()` (255),
   `_shadow.Capture()` (256) — presentation-only.
3. `new PlayerMovementController(_physics, playerRecord.ObjectClock, PlayerMovementConstructionOptions.From(_skills.Snapshot))`
   (259-262) — **uses the PUBLIC constructor**, whose default publication
   lifecycle is `StandalonePublished` (`PlayerMovementController.cs:617-626`),
   NOT `CandidatePreparing`/`CreatePublicationCandidate`. This is the key
   divergence from the dormant mechanism (section 4): this controller never
   enters the `CandidatePreparing -> CandidateSealed -> RuntimeOwnedDormant ->
   RuntimePublished` lifecycle at all.
4. Builds `MoveToManager`/`EntityPhysicsHost` closures over captured locals
   (267-346) — presentation-adjacent glue, host-specific.
5. `EntityPhysicsHostComposition.SelectStableHostWithoutRebind` (347-350) —
   canonical-state read (checks `LiveEntityRecord.PhysicsHost`).
6. `RuntimeMovementSkillProjection.ApplyTo(_skills, controller)` (366-368).
7. `ApplyStepHeights(controller, playerEntity, playerGuid)` (375) — **reads
   `DatReaderWriter.DBObjs.Setup` directly** (per headless's own comment
   contrasting itself, `HeadlessSessionWorldProjection.cs:685-689`) — NOT
   through the prepared-collision/`IPreparedCollisionSource` seam headless
   uses. Divergence #1.
8. `_controllerSlot.BeginMotionPreparation(controller, drainPriorAnimationQueue)`
   (404-407) — the ONE existing narrow "preparation lease" concept already in
   `RuntimeLocalPlayerMovementState` (separate from the dormant physics
   publication state) that lets a synchronous PartArray/type-5 completion
   reach the candidate `MotionInterpreter` before publish.
9. **Duplicate authority** — `_physics.Resolve(...)` (409-413) then
   `_physics.ResolvePlacement(...)` (422-430) — direct canonical-state-free
   collision resolve, entirely outside `RuntimeSetPositionState`.
10. `controller.PreparePositionForCommit(...)` (434-437),
    `controller.SetBodyOrientation(...)` (438).
11. Camera construction + `_camera.EnterChaseMode(...)` (440-447) —
    presentation-only, but happens BEFORE the final canonical commit (445-447
    precede line 482-484) — i.e. camera activation today is NOT gated on a
    Runtime placement acknowledgement.
12. Re-check host stability (449-458) — throws if the host changed during
    camera activation (defensive, but ad hoc — not an epoch/token check, a
    bespoke `ReferenceEquals` re-read).
13. Shadow sync (`_shadow.SyncPose(...)`, 460-466).
14. `EntityPhysicsHostComposition.InstallOrRebind(...)` (472-475) + another
    `ReferenceEquals` stability re-check (476-480).
15. **Duplicate authority — final commit** (482-484):
    `playerEntity.SetPosition(initial.Position); playerEntity.ParentCellId =
    initial.CellId; controller.CommitPreparedPosition();` — direct writes to
    the App-side `WorldEntity`/render sidecar AND `controller`'s own internal
    frame, bypassing any Runtime `Place` receipt or `RuntimeEntityRecord`
    write. **`RuntimeEntityRecord.PhysicsBody`/`PhysicsOwnershipEpoch` are
    NEVER touched anywhere in this method** — `controller.PhysicsBody` (the
    `_body` field created in step 3) stays a private field of the
    `StandalonePublished` controller; nothing calls
    `Entities.SetPhysicsBody(playerRecord, controller.PhysicsBody)`. This
    means TODAY the canonical `RuntimeEntityRecord.PhysicsBody` slot for the
    graphical local player is **never populated at all** by this path — a
    previously-unstated confirmation that `SubmitPreparedPlacement`'s
    `operation.Record.PhysicsBody is not { } body` requirement (section 3)
    would REJECT any ordinary (non-initial) SetPosition submitted for the
    graphical local player today, because no writer ever puts a body on that
    record. (Route 2's "ForcePosition" duplicate authority,
    `LocalForcePositionTransaction`, works around this by mutating
    `PlayerMovementController`'s own body directly via `BlipPosition`, never
    touching `RuntimeEntityRecord.PhysicsBody` either — internally consistent
    with each other, both equally disconnected from the canonical record.)
16. Slot commits (485-492): `_hostSlot.Host`, `_controllerSlot.Controller =
    controller` (the public, unguarded setter — bumps `ControllerOwnershipEpoch`
    unconditionally, see section 4), `_chase.Legacy/Retail`, `_mode.IsPlayerMode
    = true`.
17. `catch`: rolls back camera + shadow only (494-518); does NOT roll back
    steps 15-16 because those are the LAST lines before `lifetimeCommitted =
    true` — structurally "hope nothing after this throws" rather than an
    explicit no-fail invariant.

**Canonical-state mutations in this method: NONE on `RuntimeEntityRecord`**
(no `SetPhysicsBody`, no `SetFullCell`, no object-clock call) — everything
mutated is App-local (`WorldEntity`, `PlayerMovementController`'s private
body, `RuntimeLocalPlayerMovementState.Controller`,
`LocalPlayerPhysicsHostSlot`, camera, shadow). The ONLY canonical-record
writes for the local player's initial placement happen earlier in the
hydration pipeline (`LiveEntityRuntime.MaterializeLiveEntity`/
`RebucketLiveEntity`, route 1 hops 9-11) — entirely disjoint from this method.

### Headless: `HeadlessSessionWorldProjection.CreateController` + `SynchronizeLocalPlayer`
`src/AcDream.Headless/Hosting/HeadlessSessionWorldProjection.cs:566-655`
(read in full).

`SynchronizeLocalPlayer` (566-615):
1. Guards on `record.ServerGuid == _runtime.PlayerIdentity.ServerGuid` and a
   present `Snapshot.Position` (568-573).
2. `_collision.CenterOn(position.LandblockId)` (575) — headless collision-
   neighborhood readiness, no graphical analog.
3. `_runtime.MovementOwner.Controller ?? CreateController(record)` (576-578)
   — lazy-construct-once via the SAME public `Controller` getter/setter
   `RuntimeLocalPlayerMovementState` exposes; no reentrancy guard against two
   concurrent calls both observing `null` (single-threaded host loop makes
   this safe in practice today, not structurally).
4. `_runtime.EntityObjects.Physics.Engine.Resolve(...)` (589-594) then
   `.ResolvePlacement(...)` (595-605) — **the exact same duplicate-authority
   shape as graphical step 9**, hardcoded `DefaultRadius`/`DefaultHeight`
   constants (visible in the call, actual values not read here) instead of
   `_motionBindings.GetSetupCylinder`.
5. `controller.SetPosition(...)` + `controller.SetBodyOrientation(...)`
   (610-614) — **duplicate final commit**, headless's version of graphical
   step 15. Also never touches `RuntimeEntityRecord.PhysicsBody`.

`CreateController` (639-655):
1. `new PlayerMovementController(_runtime.EntityObjects.Physics.Engine, record.ObjectClock, PlayerMovementConstructionOptions.From(_runtime.CharacterOwner.MovementSkills.Snapshot))`
   (642-646) — **same PUBLIC constructor / `StandalonePublished` lifecycle**
   as graphical step 3.
2. `ApplySetupStepHeights(record, controller)` (649, body at 657-691) —
   **reads via `_preparedCollision.ReadSetupCollision(setupId)`** (668-679),
   the prepared-asset seam, NOT raw DAT — divergence #1 mirrored (headless
   uses the "correct"/prerequisite-B-aligned source; graphical does not).
   **Throws `InvalidDataException`** if the read status isn't `Loaded`
   (672-675) — propagates uncaught up through `SynchronizeLocalPlayer` ->
   `ProjectSpawn`/`ProjectPosition` -> the wire-dispatch call chain. This IS
   gate 10 (late headless prepared-collision failure) manifesting today as an
   unhandled exception, not a retry.
3. `RuntimeMovementSkillProjection.ApplyTo(_runtime.CharacterOwner.MovementSkills, controller)`
   (650-652).
4. `_runtime.MovementOwner.Controller = controller;` (653) — **the exact
   same public setter graphical step 16 uses.**

**No headless equivalent of graphical steps 1 (approach lifetime), 8 (motion
preparation lease), 11-14 (camera + host-stability re-checks), 17 (camera/
shadow rollback)** — headless has no camera/shadow/approach concept at all
(confirmed, matches the route inventory's "No headless equivalent of
graphical hops 12-14/19").

### Top divergences between the two hosts (summary)
1. **Setup/collision data source**: App reads raw DAT (`ApplyStepHeights` via
   `_dats`/`_datLock`); headless reads the prepared/baked asset
   (`ApplySetupStepHeights` via `IPreparedCollisionSource`). Same target
   values, different pipeline — a real fidelity risk if the two ever diverge
   (baking staleness).
2. **Default cylinder fallback**: App falls back to `0.48f`/`1.835f` inline
   (`PlayerModeController.cs:416-420`) when `GetSetupCylinder` returns
   `< 0.05f` radius; headless uses named `DefaultRadius`/`DefaultHeight`
   constants at the `ResolvePlacement` call site (:599-600) — same intended
   values, defined in two places.
3. **Failure handling**: App's `BuildControllerAndCamera` has an explicit
   try/catch/rollback for camera+shadow; headless's `CreateController`/
   `ApplySetupStepHeights` has NO surrounding try/catch — a prepared-collision
   read failure is a raw unhandled exception today.
4. **Presentation surface**: App additionally owns approach-completion
   lifetime, motion-preparation lease, chase camera, shadow sync — none of
   which headless has or needs.
5. **Neither host touches `RuntimeEntityRecord.PhysicsBody`, `PhysicsOwnershipEpoch`,
   or any `RuntimeSetPositionState` API** — both are 100% off to the side of
   the canonical record, confirmed by exhaustive grep (section 1's 6 writer
   call sites do not include either `PlayerModeController.cs` or
   `HeadlessSessionWorldProjection.cs`).

---

## 3. Every other body binding/consumer

- **Remote dead-reckoning** (`RuntimeRemotePhysicsUpdater.cs` — flagged
  protected/dirty, read-only, NOT modified): grep confirms it only READS
  `record.PhysicsBody` via `ReferenceEquals(record.PhysicsBody, remote.Body)`
  currency checks (line 817) — it does not call `SetPhysicsBody`. The actual
  writer for remote motion is `RuntimePhysicsState.SetRemoteMotion`
  (`RuntimePhysicsState.cs:1446-1570`, full read) — throws
  `InvalidOperationException` on: binding-already-in-progress (1460-1464),
  body-would-be-replaced when a body already exists and doesn't match
  (1487-1492), losing an existing remote-placement contract (1493-1498), or
  post-callback ownership drift detected via a captured
  `sessionVersion`/`expectedBody`/`expectedRuntime` triple re-checked after
  the bind callback (1539-1549, "changed ownership during remote-motion
  binding"). Calls `Entities.SetPhysicsBody(record, candidateBody)` (:1558)
  ONLY when `expectedBody is null` (first bind) via `InitializeNewPhysicsBody`
  (:1556) — i.e. this is throw-on-conflict exclusivity (Option-1 flavor), not
  epoch/token gating. For a LOCAL PLAYER record this path should never fire
  (remote motion is for non-local entities) but the guard is defense-in-depth
  and IS one of the explicit gate checks
  (`!activation.Record.RemoteMotionBindingInProgress`/`RemoteMotion is null`)
  the dormant local-publication mechanism re-validates at every stage
  (section 4).
- **Projectile binding**: `RuntimeProjectilePhysicsUpdater.cs` similarly only
  READS `record.PhysicsBody` (lines 447, 459, `ReferenceEquals` currency
  checks). The writer is `RuntimePhysicsState.BindProjectile`
  (`RuntimePhysicsState.cs:1309-1382`, full read) — same throw-on-conflict
  shape: binding-in-progress (1343-1347), body-mismatch on rebind
  (1330-1337), must-already-own-canonical-body-before-binding
  (1348-1352, "projectile must borrow its canonical physics body" — i.e.
  UNLIKE remote motion, `BindProjectile` requires `record.PhysicsBody` to
  ALREADY be non-null and matching BEFORE it will bind — it never calls
  `InitializeNewPhysicsBody`/`SetPhysicsBody` itself for a first-time body;
  something else (route 5's `ProjectileController.TryBind`,
  `ProjectileController.cs:176-265` per the route inventory) must construct
  the body ad hoc first via a DIFFERENT path than `GetOrCreatePhysicsBody`
  — worth flagging: **this is a 7th, App-side, ad hoc body-construction site
  not funneled through any of the 6 canonical writer methods** — App's
  `ProjectileController.TryBind` constructs a body and must be setting it onto
  the record through some other route (not confirmed by this pass; App-side
  `ProjectileController.cs` was not read in full — flag as open item, but it
  is explicitly OUT of C1's local-player scope per the campaign handoff's
  gate list item "remote and projectile binding/update" being about
  *interaction with* the local-player transaction, not projectile's own
  authority).
- **`RuntimeSetPositionState.SubmitPreparedPlacement`** (`RuntimeSetPositionState.cs:2224-2274`,
  full read): requires `operation.Record.PhysicsBody is not { } body` to
  already be true (line 2254) — i.e. EVERY non-initial-construction
  SetPosition submission (ForcePosition, portal, remote Position, projectile
  correction) requires a body to already exist on the record, confirming the
  6 writer sites in section 1 are the exhaustive set of "who can put the
  FIRST body on a record." For the local player specifically, only
  `RuntimeLocalPlayerPhysicsPublicationState.Commit` (section 4) does this
  today (dormant, unwired); in PRODUCTION, no writer ever populates
  `RuntimeEntityRecord.PhysicsBody` for either host's local player (section
  2 finding) — meaning `SubmitPreparedPlacement` would reject a local-player
  submission in production today, which is consistent with the route
  inventory's finding that Route 2 (ForcePosition) and Route 3 (portal) both
  bypass `RuntimeSetPositionState` entirely via their own duplicate
  authorities instead.
- **`RuntimeSetPositionState.PrepareDormantLocalActivationOwnership`**: see
  section 4 — the ONE place the local-player-specific dormant body attach
  happens; requires a pre-opened `Operation` in stage `AwaitingPreparation`
  from `TryBeginExclusiveAuthoredPlacement`.
- **Object-clock epoch transitions**
  (`RuntimeEntityRecord.SuspendObjectClock`/`ResetObjectClockForEnterWorld`,
  both `internal`, bump `ObjectClockEpoch`): full call-site grep found BOTH
  the expected `RuntimeEntityDirectory` wrapper call sites (which run
  `EnsureKnown(record)` first, `RuntimeEntityDirectory.cs:311-321`) AND
  **direct unwrapped calls from `src/AcDream.App/World/LiveEntityRuntime.cs`
  at lines 879, 891, 897, 1258, 3030, 3033** — App calls
  `record.SuspendObjectClock()`/`record.ResetObjectClockForEnterWorld(...)`
  straight on the `RuntimeEntityRecord` (accessible because these are
  `internal` and `AcDream.App` has `InternalsVisibleTo`), bypassing the
  `RuntimeEntityDirectory` facade's `EnsureKnown` check entirely. This is
  inside `LiveEntityRuntime`'s `RebucketLiveEntity`-family code (comment
  references `prepare_to_enter_world`/retail `update_object`'s parent
  early-out — matches the already-known route-1/prerequisite-D
  `RebucketLiveEntity` duplicate authority). **Previously-unstated
  implication for C1**: the SAME record whose `ObjectClockEpoch` the dormant
  publication mechanism gates on can have its epoch bumped by this
  direct-call path DURING the window between
  `RuntimeLocalPlayerPhysicsPublicationState.Prepare` and `.Commit()`/
  `.CommitActivation()` if `RebucketLiveEntity` runs concurrently for the
  SAME entity (e.g. a second CreateObject/Position causing a re-rebucket
  mid-construction) — the epoch check (`IsCurrent`/`IsActivationOwnershipEnvelopeCurrent`
  comparing `record.ObjectClockEpoch == token.ObjectClockEpoch`) WOULD catch
  and reject this correctly (fail-safe), but it confirms the gate is load-
  bearing against a REAL, already-existing production writer, not a
  hypothetical.
- **Deletion/teardown**: `RuntimeEntityObjectLifetime.TryAcceptDelete`
  (`RuntimeEntityObjectLifetime.cs:1555+`) calls `Entities.TryDelete` then
  `Entities.RemoveActive(active)` (1587) — this IMMEDIATELY flips
  `Entities.IsCurrent(record)` to `false` for that record (removes it from
  the active-by-guid table), which is the single check
  `CanPrepare`/`IsCurrent`/`IsActivationCurrent`/every gate in section 4
  depends on — so a delete landing at any point rejects the in-flight
  publication transaction on its NEXT check. Full body clear happens later
  in `RuntimeEntityObjectLifetime.CompleteProjectionRetirement`
  (:745-771, called from `RetireCanonicalOnly`/the graphical teardown-ack
  path): `Entities.SetPhysicsBody(canonical, null)` (:766) after
  `Physics.SetPosition.Forget(canonical, releasePreparedMover: true)` (:753,
  cancels any in-flight ordinary placement) and
  `ForgetInitialCreateResidence(canonical)` (:751, cancels any in-flight
  residence lease) — i.e. deletion cancels BOTH placement-lease families
  before clearing the body, consistent with prerequisite E's "quiesce before
  demote" discipline (though for landblock collision, not entity teardown —
  the pattern rhymes).
- **`RuntimePhysicsState` per-frame body access**: `RuntimeOrdinaryPhysicsUpdater.cs`,
  `RuntimeRemotePhysicsUpdater.cs`, `RuntimeProjectilePhysicsUpdater.cs` each
  gate their per-tick work on `record.PhysicsBody is not { } body` /
  `ReferenceEquals(record.PhysicsBody, body)` currency checks (grep-confirmed,
  e.g. `RuntimeOrdinaryPhysicsUpdater.cs:68,284`) — read-only w.r.t. the
  `PhysicsBody` reference itself (they mutate the BODY's internal fields
  every tick, which is expected/normal simulation, not an ownership-slot
  write). No workset iterates and calls `SetPhysicsBody`. `RuntimePhysicsState.cs`
  itself has only two visible "workset" mentions (`ClearSpatialWorksets` at
  :1951, a doc-comment at :1307) — the ordinary/remote/projectile worksets
  live in their respective `RuntimeXPhysicsUpdater` files, out of this pass's
  read budget beyond the grep-confirmed read-only currency pattern above.

---

## 4. `RuntimeSetPositionState.PrepareDormantLocalActivationOwnership` — nucleus or dead end?

**Definition** (`RuntimeSetPositionState.cs:1026-1052`, full read):
```csharp
internal void PrepareDormantLocalActivationOwnership(
    RuntimeEntityRecord record, PhysicsBody body,
    in RuntimeEntityPlacementToken token)
{
    ...
    if (!token.IsValid
        || record.Key != token.Entity
        || !_operations.TryGetValue(token.Entity, out Operation? operation)
        || operation.Token != token
        || operation.Stage is not RuntimeEntityPlacementStage.AwaitingPreparation
        || !ReferenceEquals(operation.Record, record)
        || record.PhysicsBody is not null       // <- record must have NO body yet
        || !IsCurrent(operation)
        || body.InWorld
        || (body.TransientState & TransientStateFlags.Active) != 0)
    {
        throw new InvalidOperationException(
            "Dormant local activation must bind to the exact current placement owner.");
    }
    operation.Body = body;
    operation.DormantLocalActivation = true;
}
```
It THROWS (does not return a status) on any invariant violation — by design a
"this should be structurally impossible if the caller validated first"
assertion, not a retryable rejection. It requires a PRE-EXISTING placement
`Operation` already opened via `TryBeginExclusiveAuthoredPlacement`
(`RuntimeSetPositionState.cs:1004-1024`) in stage `AwaitingPreparation` — i.e.
it is NOT a standalone entry point; it is ONE STEP inside a larger chain that
also needs prerequisite B's mover-preparation authority
(`IsExactPreparedPlacementCurrent`, `RuntimeSetPositionState.cs:1318-1340`)
satisfied for the SAME token/command before
`RuntimeLocalPlayerPhysicsPublicationState.CanPrepare` will even call it.

**What it was built for**: it is called from exactly ONE place in the whole
repo — `RuntimeLocalPlayerPhysicsPublicationState.Commit`
(`RuntimeLocalPlayerPhysicsPublicationState.cs:394-397`), as the "seal the
exact SetPosition owner before the irreversible no-fail suffix" step,
immediately before `candidate.Controller.CommitRuntimeOwnership(...)` and
`candidate.Record.SetPhysicsBody(candidate.Body)`. It exists purely to make
the PLACEMENT OPERATION (owned by `RuntimeSetPositionState`) and the BODY
(owned by `RuntimeEntityRecord`) become mutually aware atomically, so that
the SAME operation can later be walked through the full retail SetPosition
staged commit (ground phase -> collision dispatch -> response -> final
commit) via `TryEvaluateDormantLocalActivation` ->
`TryPrepareDormantLocalActivationCommit` ->
`TryApplyDormantLocalActivationCommit` ->
`TryPrepareDormantLocalActivationFinalCommit` ->
`TryApplyDormantLocalActivationFinalCommit`
(`RuntimeSetPositionState.cs:2025-2077`, full read of the final-commit
method) — the LAST of which is where `_entities.SetFullCell`,
`_entities.AdvancePlacementCommit`, `body.InWorld = true`,
`_entities.SetPhysicsHost`, `controller.CommitRuntimeActivationFrame()`,
`_physics.Engine.UpdatePlayerCurrCell`, `_physics.AcknowledgeSpatialProjection`,
`_entities.ResetObjectClockForEnterWorld` (object-clock epoch bump, task 3),
and `controller.ActivateRuntimePublication()` (controller goes LIVE) ALL
happen in one synchronous, no-branch-for-failure block (:2025-2077), gated
immediately before by `IsDormantLocalActivationPrephaseCurrent`/re-validated
epoch checks. **This is genuinely the full retail SetPosition commit,
already ported, already wired to the same body/controller the dormant
publication candidate built.**

**Verdict: NUCLEUS, not a dead end** — but it is only ONE LOAD-BEARING STEP
inside a much larger, ALREADY-COMPLETE mechanism:
`RuntimeLocalPlayerPhysicsPublicationState` (1033 lines,
`src/AcDream.Runtime/Gameplay/RuntimeLocalPlayerPhysicsPublicationState.cs`)
+ its ~15 `RuntimeSetPositionState` dormant-activation methods. Constructed
once at `GameRuntime.cs:261` and exposed via
`RuntimeLocalPlayerMovementState.PhysicsPublication` (:59-61, itself
`internal`, throws if unbound). **Confirmed by exhaustive grep: ZERO
production callers in `src/AcDream.App/` or `src/AcDream.Headless/`** — the
only callers anywhere are `tests/AcDream.Runtime.Tests/Gameplay/RuntimeLocalPlayerPhysicsPublicationStateTests.cs`.
This is, functionally, **Option 2 from the rejected-prototype note ("Off-
canonical preparation followed by one validated atomic Runtime commit that
publishes the prepared controller/body relationship without copying stale
state over newer authority") already built end to end** — complete with:
- a `Prepare`/`Commit`/`Discard` triad for the BODY/CONTROLLER pair
  (analogous to, and reusing, the SAME token-epoch pattern as
  `RuntimeSetPositionState`'s ordinary placement operations);
- a SEPARATE `EvaluateActivation`/`CommitActivation`/`DiscardActivation` triad
  for actually driving the body through retail SetPosition's staged commit
  once the body/controller pair is sealed;
- re-validation of `PhysicsOwnershipEpoch`, `ObjectClockEpoch`,
  `ControllerOwnershipEpoch`, `SessionLifetimeVersion`, identity
  `ServerGuid`+`Revision`, and null/in-progress state for RemoteMotion/
  Projectile/PhysicsHost/DeleteAcceptedForTeardown at EVERY external entry
  point (`CanPrepare`, `IsCurrent`, `IsActivationCurrent`,
  `IsActivationOwnershipEnvelopeCurrent`,
  `IsCommittedActivationSuffixCurrent`) — this IS the reentrancy defense the
  rejected snapshot-lease prototype explicitly lacked (see section 6).

**What is genuinely missing (the real C1 work), given this mechanism already
exists:**
1. Nobody calls `TryBeginExclusiveAuthoredPlacement` + prerequisite B's
   `PrepareMover`/`ReadSetupCollision` chain + `PhysicsPublication.Prepare`/
   `Commit`/`EvaluateActivation`/`CommitActivation` from either host — this IS
   the wiring gap, exactly like every other route in the cutover.
2. **The public `RuntimeLocalPlayerMovementState.Controller` setter
   (`RuntimeLocalPlayerMovementState.cs:37-50`) remains a live, unguarded
   escape hatch** — both `PlayerModeController.BuildControllerAndCamera:486`
   and `HeadlessSessionWorldProjection.CreateController:653` write it
   directly today, and NOTHING stops either host from continuing to do so
   even after C1 wires the dormant mechanism, unless that direct-write path
   is deleted/sealed off (e.g. made `internal` to only
   `RuntimeLocalPlayerPhysicsPublicationState`/`CommitRuntimeOwnedController`).
   The setter has NO epoch/token check on write (`CanCommitRuntimeOwnedController`
   is a SEPARATE, unused-by-the-setter validation method) — it will happily
   accept a second unguarded assignment even while a dormant activation is
   in flight, silently retiring whatever the dormant mechanism just
   published (`_controller?.RetireRuntimePublication()` at :45, which is a
   real no-op for anything not currently `RuntimeOwnedDormant`/
   `RuntimePublished` — see section 6 gate 7). **This is the single most
   important pre-existing defect C1 must close: the "exclusive" adjective in
   prerequisite C's "one Runtime-owned exclusive/versioned...transaction"
   is not yet true while this direct setter remains reachable from hosts.**
3. Neither `new PlayerMovementController(physics, objectClock, options)`
   (public ctor, `StandalonePublished`) call site in the two hosts has been
   swapped for `PlayerMovementController.CreatePublicationCandidate` — until
   that swap happens, controllers built by either host never enter the
   `CandidatePreparing/CandidateSealed/RuntimeOwnedDormant/RuntimePublished`
   lifecycle the dormant mechanism's gates all key off of.

---

## 5. `PlayerMovementController` construction requirements

Constructor needs (from both direct-ctor call sites AND
`CreatePublicationCandidate`, `PlayerMovementController.cs:617-690`):
- `PhysicsEngine physics` (shared engine reference, both hosts pass their own
  `RuntimePhysicsState`/`_runtime.EntityObjects.Physics.Engine`).
- `RetailObjectQuantumClock? objectClock` — App passes `playerRecord.ObjectClock`
  (the CANONICAL record's clock, `RuntimeEntityRecord.ObjectClock` at
  `RuntimeEntityRecord.cs:62`, always non-null per its field initializer);
  headless passes `record.ObjectClock` identically. The dormant mechanism's
  `CreatePublicationCandidate` instead passes a THROWAWAY
  `new RetailObjectQuantumClock()` (`PlayerMovementController.cs:687-688`) at
  construction time and only swaps in the REAL
  `candidate.Record.ObjectClock` later, inside `Commit`, via
  `controller.CommitRuntimeOwnership(candidate.Record.ObjectClock)`
  (`RuntimeLocalPlayerPhysicsPublicationState.cs:403-404` ->
  `PlayerMovementController.cs:774-786`) — i.e. the dormant candidate is
  built against a SCRATCH clock so construction can never observe or mutate
  the canonical record's real clock before the atomic commit swaps it in.
  This is exactly the "off-canonical preparation" half of Option 2.
- `PlayerMovementConstructionOptions` (RunSkill/JumpSkill) — both hosts build
  via `PlayerMovementConstructionOptions.From(<a RuntimeMovementSkillState
  snapshot>)`; the dormant mechanism's `Prepare` also takes this as a caller-
  supplied parameter (`Prepare(..., PlayerMovementConstructionOptions
  options, ...)`, :191) — no divergence in shape, only in WHERE the skill
  snapshot is read from (App's local `_skills` field vs. headless's
  `_runtime.CharacterOwner.MovementSkills` vs. the dormant mechanism taking
  it as a caller parameter either way).

What construction MUTATES (beyond the private `_body`): `LocalEntityId`,
`StepUpHeight`/`StepDownHeight` (Setup-derived), `SphereList` (Setup-derived,
prerequisite B territory), `ObjectScale`, initial position/orientation via
`PreparePositionForCommit`/`SetBodyOrientation`, physics state via
`ApplyPhysicsState`, `MoveToFactory`/`PositionManager`
(`MovementManager`/`MotionInterpreter` wiring). ALL of this is exactly what
`RuntimeLocalPlayerPhysicsPublicationState.Prepare`
(`RuntimeLocalPlayerPhysicsPublicationState.cs:187-355`) already does against
its private `CreatePublicationCandidate`-built controller, reading
`command.Physics.StepUpHeight/StepDownHeight/Spheres/Scale/Position/CellId/
CellLocalPosition/Orientation` from the CALLER-SUPPLIED
`RuntimeSetPositionCommand` (i.e. the command already carries everything
prerequisite B's mover-preparation chain produces) rather than reaching into
DAT/prepared-collision itself.

**What an "off-canonical preparation followed by one validated atomic commit"
must DEFER** (confirmed by the dormant mechanism's own design, section 4):
- The record's REAL `ObjectClock` (use a scratch clock during prep).
- `RuntimeEntityRecord.PhysicsBody`/`PhysicsOwnershipEpoch` (never touch the
  canonical record during prep; only `SetPhysicsBody` inside `Commit`, and
  only after `PrepareDormantLocalActivationOwnership` succeeds).
- `RuntimeLocalPlayerMovementState.Controller`/`ControllerOwnershipEpoch`
  (only via `CommitRuntimeOwnedController`, never the public setter, during
  prep).
- `body.InWorld`/`TransientState.Active` (explicitly forced false during prep,
  `Prepare`, :292-293) — the body must not be simulatable until the LATER
  activation commit flips it (`TryApplyDormantLocalActivationFinalCommit`,
  `body.InWorld = true` at :2056).
- World-residence/host/shadow/camera publication (all deferred to the
  activation phase / presentation-observer layer, never inside `Prepare`).

---

## 6. Adversarial gate list — exact code paths that would race TODAY

(Campaign handoff's list, `docs/research/2026-07-31-remaining-physics-campaign-handoff.md:210-221`.)
For each: what the ALREADY-BUILT dormant mechanism does (if wired) vs. what
the CURRENT production direct-construction paths do (today, unwired).

1. **Nested construction** — Dormant: `CanPrepare` requires `_activation is
   null` AND `record.PhysicsBody is null` AND `_movement.Controller is null`
   (`RuntimeLocalPlayerPhysicsPublicationState.cs:862-889`) — a second
   `Prepare` while one is in flight is REJECTED structurally. Today: NEITHER
   `BuildControllerAndCamera` NOR `CreateController` has any such guard —
   `CreateController`'s `_runtime.MovementOwner.Controller ?? CreateController(record)`
   (`HeadlessSessionWorldProjection.cs:576-578`) is a bare null-coalesce, not
   an atomic test-and-set; only single-threaded host-loop scheduling
   prevents an actual race today.
2. **Reentrant SetPosition** — Dormant: every gate re-checks
   `PhysicsOwnershipEpoch`/`record.PositionAuthorityVersion` currency.
   Today: `BuildControllerAndCamera`'s final mutation
   (`playerEntity.SetPosition`/`ParentCellId`/`CommitPreparedPosition`,
   PlayerModeController.cs:482-484) has zero epoch check — a same-thread
   reentrant call (e.g. from a nested wire dispatch) would silently
   clobber with no detection.
3. **Remote and projectile binding/update** — Dormant: `CanPrepare`/
   `IsCurrent`/`IsActivationCurrent` all check `record.RemoteMotion is null`,
   `record.Projectile is null`, `!RemoteMotionBindingInProgress`,
   `!ProjectileBindingInProgress` (defense-in-depth; should never legitimately
   fire for a local-player record). Today: no such check exists in either
   host's direct construction path.
4. **Deletion and same-GUID new incarnation** — Dormant: `_entities.IsCurrent(record)`
   checked at every gate; `TryAcceptDelete` -> `RemoveActive` flips this
   immediately (section 3). Today: `BuildControllerAndCamera`/`CreateController`
   take a fixed `RuntimeEntityRecord`/`WorldEntity` parameter with NO
   re-validation against current canonical identity at the final commit.
5. **Projection-owner replacement** — Dormant: `_entities.SessionLifetimeVersion
   == token.SessionGenerationAuthority` checked throughout. Today: no
   generation check in either direct path.
6. **Object-clock epoch change** — Dormant: `ObjectClockEpoch` compared at
   every gate (section 3/4). Today: no check; AND there is a REAL, live
   concurrent writer already in production —
   `LiveEntityRuntime.cs:879/891/897/1258/3030/3033`'s direct
   `record.SuspendObjectClock()`/`ResetObjectClockForEnterWorld(...)` calls
   inside the `RebucketLiveEntity` family (section 3) — this is not a
   hypothetical gate, it is a currently-active call path on the SAME record
   type.
7. **Reset and disposal** — Dormant: `ResetSession()`/`Dispose()` on
   `RuntimeLocalPlayerMovementState` explicitly cascade into
   `_physicsPublication?.ResetSession()`/`Dispose()`
   (`RuntimeLocalPlayerMovementState.cs:244-295`), which tear down
   candidate/activation state via `ReferenceEquals`-gated clears (never
   clobbering a newer owner, `DiscardActivation`,
   `RuntimeLocalPlayerPhysicsPublicationState.cs:1002-1032`). Today's direct-
   construction controllers are built via the PUBLIC constructor
   (`StandalonePublished` lifecycle) — **`RetireRuntimePublication()`
   (`PlayerMovementController.cs:837-846`) only transitions
   `RuntimeOwnedDormant`/`RuntimePublished` state; it is a NO-OP for
   `StandalonePublished` controllers** — a previously-unstated finding: TODAY,
   `ResetSession()`/`Dispose()`/replacing `.Controller` on either host's
   directly-built controller produces NO explicit lifecycle transition at
   all; the controller is simply dropped/GC'd. Not a visible bug today
   (nothing reads `IsRuntimePublished` for these), but it means today's
   controllers are invisible to the exact teardown bookkeeping C1's target
   mechanism relies on.
8. **Commit and rollback after replacement** — Dormant: ALL validation
   happens before the single canonical mutation
   (`PrepareDormantLocalActivationOwnership`, which itself throws leaving
   state untouched on failure); everything after is documented as
   "callback-free, non-allocating, and cannot fail"
   (`RuntimeLocalPlayerPhysicsPublicationState.cs:391-393`) — no rollback-
   after-newer-authority path exists BECAUSE nothing after that point can
   fail by construction. Today: `BuildControllerAndCamera`'s try/catch rolls
   back camera+shadow only; the final `playerEntity.SetPosition`/
   `ParentCellId`/`CommitPreparedPosition` triad (482-484) has nothing after
   it that can throw, so it's accidentally safe today, not structurally
   guaranteed.
9. **Late graphical camera/shadow/host failure** — Today: `BuildControllerAndCamera`
   DOES handle this (explicit `_camera.RestoreState`/`_shadow.Restore` in the
   catch block, 494-518) — this is the ONE gate the CURRENT graphical path
   already handles reasonably. The dormant Runtime-side mechanism has NO
   camera/shadow concept (presentation-independent by design) — C1 must
   layer this handling in the PRESENTATION/observer phase (post-Runtime-
   commit), matching prerequisite D's rule that a host exception must not
   roll Runtime back, only retry the FIFO head.
10. **Late headless prepared-collision failure** — Today:
    `ApplySetupStepHeights` (`HeadlessSessionWorldProjection.cs:657-691`)
    throws a raw, uncaught `InvalidDataException` (672-675) if the prepared
    Setup collision isn't `Loaded` — this propagates up through
    `CreateController` -> `SynchronizeLocalPlayer` -> `ProjectSpawn`/
    `ProjectPosition` with NO try/catch anywhere in between (grep-confirmed
    no surrounding try/catch in `HeadlessSessionWorldProjection.cs`'s these
    methods) — a genuinely unhandled-exception risk in production headless
    TODAY, not just a hypothetical C1 gate.

---

## Summary for the C1 contract

- **Writer count**: 6 confirmed call sites of `RuntimeEntityRecord.SetPhysicsBody`
  across 3 files (`RuntimeEntityDirectory.cs:359`,
  `RuntimeEntityObjectLifetime.cs:766`,
  `RuntimeLocalPlayerPhysicsPublicationState.cs:405,1025`,
  `RuntimePhysicsState.cs:1558,1666`) — plus a probable 7th App-side ad hoc
  projectile body-construction site not yet traced to a canonical writer
  (flagged, out of local-player scope).
- The dormant `RuntimeLocalPlayerPhysicsPublicationState` +
  `RuntimeSetPositionState`'s ~15 dormant-activation methods already
  implement essentially the COMPLETE Option 2 transaction (off-canonical
  prepare against a scratch clock/sealed candidate controller, single
  validated atomic commit, full retail-staged SetPosition activation) with
  epoch/token/generation/identity re-validation at every external entry
  point — it has ZERO production callers in either host.
- The single largest remaining defect even AFTER wiring: the public
  `RuntimeLocalPlayerMovementState.Controller` setter is an unguarded escape
  hatch both hosts currently use directly; it must be sealed (made
  unreachable from hosts, or itself epoch-gated) for the word "exclusive" in
  prerequisite C to be true.