acdream/docs/research/2026-08-02-runtime-continuation-executor-handoff.md

Runtime initial-placement continuation executor handoff - 2026-08-02

Purpose and exact stopping point

Behavior commit 5db3de3c7ab2c6350d11af7f34b852464fc1e0f9 implements the Runtime continuation executor: the missing mechanism that, once an entity's initial authored placement is acknowledged, adopts that placement exactly once, applies the retail Create tail, replays deferred missing-parent work, and drains the admission checkpoint's mixed continuation FIFO in exact arrival order with retail route decisions made at execution time. The residence system built by 38fd4b8d (residence/FIFO) and 30012361 (admission) is now COMPLETE as a mechanism: an entity can enter the world through it and every packet accepted while its placement was pending is applied exactly once, in order, with retail semantics.

This checkpoint deliberately does NOT cut the graphical or headless production routes over — RuntimeLiveEntitySessionController.cs (headless) and App's LiveEntityRuntime still call legacy RegisterEntity, and no host calls Execute. It does not begin AP-22 or AD-10 and does not retire AP-1/AD-1. The executor is exercised by deterministic Runtime tests only, so no connected visual gate was required.

This file supersedes the executor-boundary portions of 2026-08-01-runtime-initial-placement-admission-handoff.md.

Exact workspace and Git state

• Worktree: C:\Users\erikn\.codex\worktrees\af5e\acdream
• Branch: codex/port-claude-agents
• Behavior checkpoint: 5db3de3c7ab2c6350d11af7f34b852464fc1e0f9
• Documentation checkpoint: the commit containing this file
• The same eight unrelated dirty paths as the admission handoff remain intentionally unstaged; never stage by blanket.
• No push or merge is part of this checkpoint.

What the executor owns

RuntimeInitialCreateContinuationExecutor (constructed inside RuntimeEntityObjectLifetime beside the residence state; internal InitialCreateExecution; generation bound through BindEventContext) owns, per exact RuntimeEntityKey + lease:

• the synchronous, retry-idempotent Execute transaction: Complete -> AdoptCompletedPlacement (consumes the acknowledged initial placement exactly once, resolving the HasRetainedCompletion deadlock so later authored placements for the key can begin, with PlacementAdopted keeping the completed entry current) -> AfterEnterWorld hook request (local player, exactly once) -> deferred replay -> strict-sequence FIFO drain -> ConsumeExecuted release (adoption-revision-checked; Revised re-drains only the tail);
• per-continuation applies through gate-less instance seams on InboundPhysicsStateController (ApplyAccepted*Snapshot) that read and write the ONE snapshot store — the legacy fused paths are re-expressed as gate + the same shared merge bodies, so there is no drift and no second canonical snapshot;
• execution-time Position routing via RuntimeAuthoritativePositionRouteClassifier.ClassifyAcceptedPosition with live inputs: the retained wire packet's own IsGrounded bit as the server-asserted contact (never the local body), the data-driven (MotionTableId ?? Physics?.MotionTableId) animation proxy (AP-130), live distance/UsePositionFromServer, and the record's committed cell — driving authored placements for SetPosition routes through the canonical RuntimeSetPositionState Begin/Watch/resume lifecycle with a retryable AwaitingContinuationPlacement yield (a contention flavor with no pending token means "retry Execute later");
• atomic SameIncarnationCreate envelopes: per-stage index idempotency, buffered publication flushed in stage order after the final stage (AD-59), the object-table apply via the accepted-spawn seam (result observed; a nested replacement abandons), and the three-branch resident-cell disposition (TS-63);
• missing-parent replay, both flavors, keyed by parent GUID exactly as retail's QueueBlobForObject/ProcessObjectNetBlobs: raw child Creates AND queued accepted parent relations, drained in the initial tail with whole-bucket atomic detach, per-entry exception containment (ReplayFailureCount/LastReplayFailure), typed outcomes (Registered/ReDeferred/Rejected; ParentApplied/DeferredAwaitingParent/ DiscardedStaleParent), and cancellation-aware restore windows whose tokens record every cancellation fired while a batch is detached (ABA-safe; a cleared token restores nothing);
• the field-masked executor baseline: each apply re-syncs ONLY the tracked fields its own mutations moved, before publication, so external mutations are detected in every quiet window and publish-callback;
• one shared abandonment routine on every non-retryable exit: forgets any pending continuation placement (cancellation published), retires the residence through the lifetime choke point, discards progress, returns a typed status — the combined ownership ledger (residences, executor progress, deferred buckets, replay windows, placement watches) converges, and residence retirement notifies the executor (BindRetirementNotification);
• an ordered immutable execution receipt/trace carrying every fact a cutover host needs: per-action kind/sequence/stage, Position route facts (disposition, constrain phase, teleport-hook phase, stop-interpolation, zero-velocity, preserve-heading, send-position-immediately, unparent), replay outcomes, and resident-cell dispositions.

Retail anchors proven this slice

Beyond the admission handoff's eight anchor functions:

• retail's local-ordinary interpolate gate is UsePositionFromServer && wire-contact — PositionPack bit 0x4 → has_contact (pseudo-C 284654) → UnpackPositionEvent arg5 (93092) → the gate at 93044. The earlier research note's "isForce" reading was a misnomer disproven during review; the shipped classifier was correct.
• ProcessObjectNetBlobs detaches the whole per-GUID bucket before dispatching (93617 → 93649) — mirrored by the detach/restore windows.
• missing-parent relations are QUEUED by parent GUID (standalone parent handler 0x004535D0: lookup 92312, queue 92326; QueueBlobForObject 0x005092D0's GUID-keyed placeholder bucket 271082-271088) — never discarded; the round-4 discard was overturned on this evidence.
• HandleReceivedPosition's HasAnims gate (92992) is animation-queue presence (CSequence::has_anims = non-empty list), anchoring AP-130.
• the same-incarnation tail order and resident-cell cleanup (93865..93943) are mirrored stage-for-stage, with the claimedCell==0 destruction branch proven structurally unreachable for admitted envelopes (every envelope carries a WeenieDescription by shape).

Divergence register

Rows filed in the behavior commit: AD-59 (envelope buffered live-record events), AD-60 (executor canonical cell semantics — wire positions never directly commit residency), AP-130 (HasAnims MotionTableId proxy), AP-131 (legacy Position merge's unconditional placement-frame/parent- clear flags — retired by construction at cutover), AP-132 (parent incarnation gating vs retail's pointer-only GUID replay), TS-62 (no live ConstrainTo binding in the dormant slice — trace-only), TS-63 (resident-cell abandonment/delegation split). AP-1 and AD-1 remain open until the cutover. Issue #275 tracks the post-cutover unification of the legacy Position path onto the classifier.

Validation

• Focused executor/residence/classifier gate: 161/161.
• Complete Runtime project: 903/903 (829 baseline + 74 slice tests).
• Complete Release solution: 10,696 passed / 4 intentional skips / 0 failed (-m:1, installed acdream.pak); Release build 0 errors, 21 pre-existing test-project warnings.
• git diff --check clean; the eight unrelated dirty paths untouched.
• Independent reviews (both read-only, both required to PASS): the retail-conformance reviewer and the architecture/adversarial reviewer each ran four passes across five implementation rounds. Finding classes fixed at root cause along the way: wire-vs-body contact source; two-store snapshot divergence; WeenieDescription wholesale-overwrite; non-converging abandonment; reentrant mid-drain residence retirement; the acknowledged-completion leak that would have blocked all future placements for a key; per-field baseline blessing; replay exception containment and detached-batch resurrection; and the stale-parent discard overturned in favor of retail's queue-by-parent-GUID replay. Final verdicts: RETAIL REVIEW: PASS; ARCHITECTURE REVIEW: PASS (three residual NOTEs, all defense-in-depth observations, none blocking).

Production routes intentionally unchanged

Graphical Create still flows through LiveEntityRuntime.RegisterEntity; headless still uses RuntimeLiveEntitySessionController's legacy RegisterEntity; no production code calls RegisterEntityWithInitialResidence or Execute. The residence+executor system is a complete, reviewed, dormant mechanism awaiting the cutover.

Next implementation boundary — the production cutover

Route graphical AND headless registration through the residence+executor owner together, then every Create, Position, ForcePosition, Parent, Pickup, withdrawal, delete, remote-movement, projectile-correction, and dropped-item edge through the same transaction. Hosts project immutable Runtime results only; they may not resolve a second placement or create another body. Delete the legacy duplicate paths only after parity tests pass (this retires AP-131 and closes #275 by construction). Run the exact lifecycle/reconnect and canonical nine-stop connected routes, two-client observation, and the user visual matrix. Only then retire AP-1 and AD-1.

Cutover-specific notes from this slice:

• The execution receipt carries every route fact a host must bind — the constrain phases and stop-interpolation/zero-velocity flags (TS-62), the teleport-hook phases, and the send-position-immediately echo.
• AwaitingContinuationPlacement has two flavors: pending token (host must prepare/submit/acknowledge the placement, then retry Execute) and contention (no pending token; retry Execute after the conflicting operation resolves).
• The dormant placement path's 1,880-bytes/operation allocation budget (2,048 cap) remains the standing 4B2 activation blocker for frame-frequency traffic; resolve or budget it before the cutover routes high-frequency Position traffic through the owner.

After the cutover: AP-22 (authored collision shapes; ShadowShapeBuilder sole authority), then AD-10 (remote contact-plane projection), then the final automated + connected matrix and ledger synchronization close the campaign; vendor Slice 5 resumes after.

Rollback

git revert 5db3de3c7ab2c6350d11af7f34b852464fc1e0f9

The documentation checkpoint containing this file is separate and may be reverted independently. Do not revert the 38fd4b8d/30012361 foundation beneath it without a separately proven defect.

Resume checklist

1. Continue in the exact worktree/branch above; confirm git log contains 5db3de3c and the documentation commit containing this file.
2. Preserve the eight unrelated dirty paths; never git add -A.
3. Read this file, the admission handoff, and docs/architecture/acdream-architecture.md.
4. Re-run the focused gate before modifying execution code: the Residence + Classifier + Executor filter must report 161/161.
5. Begin ONLY the production cutover checkpoint. Do not fold AP-22, AD-10, or vendor work into it.