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

# C4 route 4 — scoping, and a stop-and-re-plan (2026-08-03)

Scoped at HEAD `e3b766d9`, after route 2 shipped. **This is not a contract.** The
scoping says route 4 is materially larger than the budget it was given, so the
correct next action is a user decision, not an implementation pass.

## The budget, and how it failed

After route 2 I pinned a falsifiable bet: *routes 4-7 reuse the seam route 2
built, so their marginal cost should be far lower — well under 400 production
lines. If route 4 also costs ~900, the bet is dead and that is the signal to
stop and simplify.*

**Estimate: 1,500-2,500 lines of new/changed production code**, plus ~1,700
lines of test re-modelling. The bet failed before implementation started.

But it failed for a reason worth stating precisely, because it changes what to
do about it: **the seam generalises fine. Route 2 was just not a representative
unit.**

| | route 2 | route 4 |
|---|---|---|
| entities | 1 (local player) | N (every visible remote) |
| dispositions | 1 (ForcePosition) | 4 (SetPosition / SetPositionSimple / Interpolate / NoPositionOperation) |
| execution paths | 1 | 2 (canonical SetPosition **and** the interpolation queue) |
| teleport hook | never | `BeforePositionOperation` |
| constrain phase | never | `AfterPositionOperation` |
| duplicate authorities to delete | 2 | **6** |
| outbound ack | owns it | none |
| frequency | ~never | 5-10 Hz x N |

I chose route 2 first because it was simplest to reason about, then used it to
calibrate everything after it. That was the error: a one-entity, one-disposition,
no-interpolation route is the floor, not the median.

## What is genuinely reusable (the good news)

- The begin/prepare/submit/commit chain is **entity-kind agnostic** — no
  local-player precondition anywhere in `TryBeginExclusiveAuthoredPlacement` →
  `TryPrepareAndSubmitAuthoredPlacement` → `SubmitPreparedPlacementCore`.
- The classifier's remote branches are **retail-exact already** (verified against
  `CPhysicsObj::MoveOrTeleport` @0x00516330 on all five behaviours).
- The placement receipt → presentation path is already entity-agnostic; C3c
  drives remote Creates through it today.
- **All remote physics state already lives in Runtime** (J5.5) — `RemoteMotion`,
  `EntityPhysicsHost`, the interpolation queue. No assembly boundary to cross.
- **`RuntimeAcceptedPositionDriveController` itself is ~15-20% liftable** — the
  architecture, not the code. It is single-entity and ack-owning by construction
  (`_pending` is one slot and `RetainPending` throws on a second).

## Four findings that change the campaign plan, not just route 4

**1. Route 4's Create half is already done.** C3b/C3c landed
`RuntimeRemoteFirstEntryState` + `RuntimeRemoteBodyDescription` and flipped both
hosts' Creates onto the residence conductor. Route 4's remaining work is
**steady-state remote Position plus the deletions**. The route title is
misleading and will send an implementer hunting for a flip that already happened.

**2. AP-131 cannot be retired by route 4.** The row covers two halves: the
`!HasAnims` gate on `SetPlacementFrame`, and the FORCE_POSITION branch skipping
`unset_parent`. Route 2 did **not** fix the second — it consumes an
already-merged snapshot, so a ForcePosition still passes
`installPlacementFrame: true, clearParent: true`. Retiring AP-131 needs the
unconditional merge gone for *every* Position: remote (route 4), local
ForcePosition (a route-2 residual), **and local ordinary-Apply — which no route
in the eight-route inventory owns.** Either widen route 4 or move AP-131 to C5
with those two as prerequisites. Pinning "route 4 retires AP-131" pins something
route 4 alone cannot deliver.

**3. #277's bound breaks.** Its safety argument is that the collision window is
strictly larger than ACE's Create-broadcast group, so the far set is empty. That
is a statement about *Creates*. A steady-state Position can carry a remote out of
the window with no Create at all — a creature wandering off, or the >=96 m
far-snap branch by definition targeting something distant. Route 4 introduces a
second producer of far parks the radius argument never covered. Needs a
Position-time service-window guard on **both** hosts; headless has the predicate,
the graphical host has none and one must be built.

**4. N3 stops being latent.** The route-2 round-2 finding — headless never calls
`RetryPending` after construction, so a declined `Place` would wedge the ordered
stream — was filed as latent because headless remotes produced no placement
receipts. Route 4 makes them produce receipts for the first time. **Fix N3 in
route 4 or the headless stream wedges.**

## Three unfiled divergences found during scoping

Our production remote path diverges from the retail classifier on five
behaviours; three have no register row:

- **NPC airborne hard-snap** (`LiveEntityNetworkUpdateController.cs:1819-1823`)
  writes `Body.Position`/`Orientation` and never consults `update.IsGrounded` at
  all — it branches on the client-tracked `rmState.Airborne`. Retail returns 0
  and writes nothing (@0x0051636D).
- **`ConstrainTo` armed before the operation, unconditionally** (`:1522-1529`),
  so it arms on the airborne no-op retail skips and anchors to the *pre*-move
  position on the far branch. Retail arms it *after* a nonzero `MoveOrTeleport`,
  anchored to the post-move `m_position` (@0x00454254-@0x00454272).
- **`ConstrainTo` never armed on the remote teleport branch** (the path returns
  at `:1504`, before `:1522`), where retail *does* re-arm after `teleport_hook`'s
  `UnConstrain`.

Route 4 fixes all three by construction — which means **route 4 is a behaviour
change to every visible creature in the game, not a refactor.**

## Allocation: not the blocker anyone feared

The inventory's "frame-frequency routes are blocked on placement allocation"
warning was written pre-C2 and before anyone checked which branch remotes take.
The steady state — nearby, grounded, non-teleporting — classifies to
**`Interpolate`, which runs no SetPosition at all**. The 944 B/op cost applies
only to teleports, cellless first placements, and >=96 m remotes.

Arithmetic (assumptions, not a capture): 40 remotes x 7 Hz with ~10% on a
SetPosition branch ~= 26 KB/s. Pathological dense-town worst case ~= 264 KB/s,
about 2.4% of the Slice-G5 profile. **Not a blocker — provided the near branch
stays out of `SetPosition`.** The contract must forbid routing every remote
Position through it "for uniformity".

Unmeasured and worth measuring before pinning a budget: the legacy path's actual
cost (no gate covers `PhysicsEngine.SetPosition`), and the real near/far split in
live play.

## Route 4's one big advantage: it is trivially observable

Route 2 cost five review rounds largely because nothing a user could do would
trigger it. Route 4 is the opposite — every remote entity exercises it
continuously. Six checks, all within two minutes of ordinary play with a second
character:

1. **Near interpolate** — second character walks/runs in a circle 5-15 m away.
   Smooth motion, no per-packet stepping.
2. **Airborne no-op** — they jump, and jump off a ledge. Clean parabola, clean
   landing. Watch for invisible-but-solid, the #184 signature.
3. **Far-snap** — they run >96 m and back. No freeze at the boundary, no wrong Z.
4. **Remote teleport** — portal/recall out and back, plus an admin `@teleto`.
   Arrive grounded, animating, immediately targetable.
5. **The leash** — route 4 moves `ConstrainTo` from before to after, stops arming
   it on the airborne no-op, starts arming it on teleport. #167 was a leash bug.
6. **Creature blast radius** — pull a drudge, let it chase, melee it, let it die.

Weight this gate heavily. All four route-2 states were green and three were
defective; route 4 finally has a real oracle.

## The decision

Route 4 is worth doing — it fixes three unfiled divergences affecting every
creature, retires the largest duplicate-authority cluster in the codebase, and
builds the seam route 5 needs (the classifier gives Projectile *identical*
branches to Remote). But it is a 1,500-2,500 line behaviour change, not a wiring
job, and it should not start on a budget everyone knows is wrong.

Options, in the order I would rank them:

**A. Split route 4 into 4a and 4b.** 4a = the interpolation/near path plus the
airborne no-op (the steady state, highest visible value, no park hazard, no
service-window work). 4b = teleport/far/cellless, which is where the parks, the
service-window guard, N3 and #277 all live. Each gets its own contract, gate and
review. Roughly halves the blast radius per commit and puts the observable win
first.

**B. Do route 4 whole against a corrected budget** (~2,000 lines, 2-3
implementation passes, one adversarial review per pass). Honest, but it is a
large single commit touching every visible creature.

**C. Defer route 4; do routes 5-7 first.** Rejected — route 5 needs the same
seam, so this just moves the cost.

**D. Stop the campaign here and simplify instead.** The complexity concern that
prompted the budget is real, and `RuntimeSetPositionState` at 5,652 lines is the
obvious target. But route 4 is where three live divergences get fixed, so
stopping leaves known-wrong behaviour in the client.

**Recommendation: A.** It respects the budget's intent — keep each landing small
enough to review — without abandoning work that fixes real bugs. It also front-
loads the part with a clean live gate and defers the part with the known traps.