acdream/docs/research/2026-08-04-c4-route-4b-1-contract.md

C4 route 4b-1 — remote placement infrastructure: pinned contract (2026-08-04)

Scoping and the three-way split: 2026-08-04-c4-route-4b-scoping-and-split.md.

4b-1 builds the machinery and changes NO remote behaviour. It has no production caller, or is called for zero classifications. 4b-2 (far branch) and 4b-3 (teleport / cell-less) flip it on afterwards.

The reason for landing it alone: 4b-1 is where the park-withdraws-the-entity failure mode is decided, and that decision must be reviewed on its own signal, not alongside a ~700-line class deletion.

Scope — build these five things

1. A per-entity remote placement owner in AcDream.Runtime.
2. A Position-time service-window guard, with a Runtime-facing interface and implementations for both hosts.
3. The refuse-rather-than-park policy (see "The central decision").
4. N3 — headless never calls RetryPending after construction.
5. Parked-count observability wired into the ownership ledger and report.json.

The central decision — refuse, do not park

A Runtime DeferredCell park withdraws the entity from the world: ParkDeferred sets body.InWorld = false, clears TransientStateFlags.Active, suspends the object clock, calls WithdrawCanonical, and publishes a Withdraw.

RuntimeEntityObjectLifetime's Forget-on-every-accepted-Position then kills the park without restoring any of that — CancelCoreDeferred removes the operation and rewrites the Withdraw into a Discard; it does not set InWorld back, resume the clock, or re-enter residency.

So packet N parks entity E (invisible AND intangible); packet N+1 ~150 ms later Forgets the park; and if N+1 classifies Interpolate, no placement runs and E stays withdrawn indefinitely. The producing sequence is mundane: a remote appears beyond 96 m, walks toward you, crosses inside 96 m.

Therefore: a remote whose destination is not placeable now must NOT open a park. It keeps its last committed pose and waits. The next packet IS the retry, because remote Positions are a 5-10 Hz stream. This is also retail-shaped — retail's world is fully resident, so "arrived but not placeable" is unrepresentable there.

If you conclude the refusal cannot be expressed without touching RuntimeSetPositionState's park machinery, STOP and report rather than adding a withdrawal-restore path inside a 5,652-line class.

Two transfer errors — named so they are not repeated

Route 2's controller is the architectural model. Two of its parts must NOT be ported, and both would look correct to an implementer copying it:

• The ack machinery. PositionEventOwed, positionEventOwed, the SendPositionEvent plumbing — retail's remote arm has NO SendPositionEvent. HandleReceivedPosition @0x00453FD0 calls it only on the local-player FORCE_POSITION branch. Delete the concept, do not carry it.
• The re-issue funnel. Route 2 re-issues because a ForcePosition is a one-shot correction ACE never repeats, so a dropped one is lost. A remote Position is a repeated stream; re-issuing packet N after N+1 has merged would apply a pose the newer packet already superseded. Same class of error as the route-2-to-4a rebucket mistake, in reverse.

Per-entity state

Route 2's _pending is ONE slot and RetainPending throws on a second live pending. That shape does not transfer. Required:

• A per-key map, with route 2's single-owner invariant re-derived per entity.
• The ownership ledger count becomes a dictionary count that must converge to zero at teardown, reset, and generation change.
• Bounded, non-allocating iteration for any pump — RuntimeFirstEntryDriveController._driveScratch is the in-repo template.
• Per-entity currency: GUID reuse, incarnation change, generation change, an entity torn down mid-drain, and two entities interleaved must all be safe. A pure function does not by itself make the CALLER re-validate identity.

The service-window guard

• Headless has one: IHeadlessCollisionNeighborhood.IsWithinServiceWindow (HeadlessSessionWorldProjection.cs:27, impl :245-257) — a Chebyshev dx <= 1 && dy <= 1 test against _requestedCenterLandblock. Its only consumer today is Create-time.
• The graphical host has none. It must be built from GpuWorldState.IsNearTier / IsNearTierOrPending, StreamingController.NearRadius and the observer centre, exposed to Runtime through an interface mirroring the headless one.
• Unproven, and you must establish it: that near-tier residency is exactly co-extensive with collision publication. The four gating call sites are consistent with it; the retirement side is unverified. If it is not co-extensive, say so and propose the correct predicate rather than shipping the assumption.
• ToCellessCreateRoute does not apply. It produces AwaitFreshPosition, its only consumer operates on a residence lease, and it refuses once FullCellId != 0. A steady-state Position has no residence by construction. 4b-1 needs its own "decline this placement" outcome.

N3 — fix regardless

HeadlessSessionEventRoute.Attach constructs the subscription with retryPendingOnSubscribe: true and that is the ONLY RetryPending call headless ever makes. PumpFirstEntry calls IsReady, DriveAll and Advance — not RetryPending. The graphical host binds it correctly per frame. RuntimePlacementProjectionSubscription.OnPlacement only projects when the new delta IS the FIFO head, so a declined head is never revisited.

Add RetryPending() to the headless pump in the same order the graphical route uses (drives first, retry last). This is a latent defect in shipped code; fix it whether or not 4b-1 flips headless remotes.

Must prove, not assume

ParkCollisionResidents throws on overlap — for every spatial root in a retiring landblock prefix that holds an active operation (RuntimeSetPositionState.cs:3387-3395). With N remotes holding operations, an ordinary streaming retirement becomes session-fatal. It is unreachable today only because steady-state remotes hold no operations. 4b-1 must demonstrate it stays unreachable under the new design — that is the concrete failure #277's bound was protecting, and it is a gate item, not a note.

Do NOT touch

• AP-135's two writes (rmState.CellId, LastServerPos/LastServerPosTime) on the airborne branches. They are 4a-owned dispositions and AP-135 does not retire with 4b. They sit inside the method 4b rewrites, which is the trap.
• RemoteTeleportController, RemoteTeleportPlacement, remotePlacementRequired — 4b-3.
• The legacy far halves in either arm — 4b-2.
• ConstrainTo arming. Retail has exactly ONE site on the remote arm (@0x00454272); all three nonzero-returning MoveOrTeleport branches funnel through it. Do not add a second. 4b-2/4b-3 fold the existing arm outward.
• Route 1's executor. RuntimeAcceptedPositionRouteRequests is shared with it; any change there is a regression in shipped functionality.

Contract

1. The owner is Runtime-resident and presentation-independent; both hosts can drive it.
2. It has no production caller, or is called for zero classifications. 4b-1 changes no remote behaviour, and the existing connected routes must be unchanged.
3. No ack. No re-issue funnel. Per-entity state.
4. A non-placeable destination is refused, not parked.
5. The ownership ledger includes the per-entity pending count and converges to zero at teardown, reset, and generation change.
6. ParkCollisionResidents's overlap throw is demonstrably unreachable.
7. Nothing in the "Do NOT touch" list changes.

Acceptance

• Focused Runtime tests: per-entity independence, currency across GUID reuse / incarnation / generation / teardown, the refusal outcome, ledger convergence, and the service-window predicate on both hosts.
• A test for the §"central decision" sequence specifically: attempt a placement whose destination is not placeable, deliver a second accepted Position that classifies Interpolate, and assert the entity is still in the world — InWorld true, clock running, residency intact. That is the invisible-and-intangible failure, and it must be pinned before 4b-2 flips anything on.
• Complete Release suite green. Baseline 10,938 passed / 4 skipped / 0 failed. Two known flakes, do NOT chase and do NOT conflate: #302 (PortalProjectionTests.ClipToRegion_FrameOwnedStore_ReusesExactResultArray, a GC-allocation assertion in App.Tests) and #308 (NakEmissionTests.LossSoak_..., a wall-clock deadline in Core.Net.Tests that fails only under full-suite load). If either appears, re-run and say which.
• No connected gate: 4b-1 changes no behaviour, so there is nothing for a user to observe. Say so rather than inventing one.

Budget

~700-1,000 non-comment production lines. Route 4a came in at 364, which was 91% of its ~400 budget — not "well under". If 4b-1 exceeds 1,000, stop and report before continuing rather than pushing through.