acdream/docs/research/2026-08-01-runtime-initial-placement-admission-handoff.md

Runtime initial-placement admission handoff - 2026-08-01

Status: this remains the 30012361 admission-checkpoint history. The continuation executor this file scoped as "the next implementation boundary" is complete at 5db3de3c; the current boundary (production cutover) is recorded in 2026-08-02-runtime-continuation-executor-handoff.md.

Purpose and exact stopping point

Behavior commit 30012361e12222e8271b1531574257ba910c77cb completes the bounded Runtime admission checkpoint requested by the user. While an entity's first authored placement is waiting, every later accepted same-incarnation update is preserved in exact arrival order without changing or displaying the entity early.

In plain terms, Runtime now has a sealed mailbox behind the pending initial placement. Network sequence checks still decide which messages are fresh, but accepted messages wait in that mailbox. The visible/canonical entity remains at its original frozen Create state until a later executor is authorized to apply the mailbox.

This checkpoint deliberately does not implement that executor, switch the graphical or headless production routes, begin AP-22 authored shape work, or begin AD-10 remote slope projection. AP-1 and AD-1 therefore remain open.

This file supersedes the admission-status portions of 2026-08-01-runtime-initial-create-residence-handoff.md; that earlier file remains the foundation history for commit 38fd4b8d.

Exact workspace and Git state

• Worktree: C:\Users\erikn\.codex\worktrees\af5e\acdream
• Branch: codex/port-claude-agents
• Behavior checkpoint: 30012361e12222e8271b1531574257ba910c77cb
• Residence foundation: 38fd4b8dc952236d4b98518c67335026c7815656
• Documentation checkpoint: the commit containing this file
• No push or merge is part of this checkpoint.

The worktree intentionally contains unrelated user changes or pre-existing stat/line-ending noise. Do not stage, restore, normalize, or rewrite these paths when continuing:

• AGENTS.md (real unrelated content change);
• src/AcDream.App/Input/PlayerModeController.cs;
• src/AcDream.App/Interaction/PlayerInteractionMovementSink.cs;
• src/AcDream.App/Rendering/LiveAnimationPresentationContext.cs;
• src/AcDream.Runtime/Physics/RuntimeRemotePhysicsUpdater.cs;
• tests/AcDream.Core.Tests/Physics/CellTransitTests.cs;
• tests/AcDream.Core.Tests/Physics/Issue133DungeonTeleportPrefixTests.cs;
• tools/A8CellAudit/A8CellAudit.csproj.

Always stage exact paths. Never use git add -A in this worktree.

What 30012361 owns

One exact pending owner

RuntimeInitialCreateResidenceState owns one transaction per exact RuntimeEntityKey, not per server GUID alone. It retains:

• the deep-frozen initial Create packet and placement operation;
• the exact residence token, generation, placement authority, and revision;
• a monotonic sequence for accepted continuations;
• one immutable, mixed-kind FIFO in original arrival order;
• completion/adoption and teardown receipts.

The accepted continuation kinds are:

1. same-incarnation Create;
2. ObjDesc;
3. Parent;
4. Pickup;
5. Position;
6. Movement;
7. State;
8. Vector.

There is no coalescing, sorting by message type, or replacement of an earlier accepted FIFO item by a later one.

Frozen public state

While the initial residence is pending:

• retail timestamp gates advance for accepted updates;
• RuntimeEntityRecord.Snapshot remains unchanged;
• the public accepted-snapshot view remains unchanged;
• no entity/object event is published;
• no projection acknowledgement callback runs;
• parent commitment, world placement, rendering, radar, picking, physics, audio, and other presentation remain unchanged;
• every accepted payload is retained as an immutable typed action.

This is intentional gate-only acceptance. It is not an alternative canonical snapshot and must not grow into one.

Immutable payload boundary

RuntimeInitialCreateAdmissionFreezer copies every parser-owned mutable collection that can outlive packet dispatch:

• EntitySpawn animation-part, texture, and sub-palette arrays;
• ObjDesc model arrays;
• motion command lists;
• Physics Movement raw bytes and motion commands;
• Physics child attachments.

Same-incarnation Create is retained as one atomic envelope. Its actions retain retail's packet-tail order:

1. AP-119 pre-tail description adaptation;
2. ObjDesc;
3. exactly one of Parent, Position, or Pickup;
4. Movement;
5. State;
6. Vector;
7. Weenie description;
8. resident-cell cleanup.

Position facts remain raw

A deferred Position retains the typed packet plus the timestamp disposition and accepted gate facts. It does not prematurely choose interpolation, teleport hooks, or final movement behavior. The new explicit RuntimePositionConstrainPhase distinguishes retail's local ordinary constrain-before route from remote/teleport constrain-after routes, but the future executor must still sample the required live inputs at the retail decision point.

No selected UI target, presentation state, or host-specific route is stored in the admission owner.

Missing-parent behavior

Named retail resolves a nonzero parent before child object lookup and child timestamp admission. Runtime now follows that order:

• a child Create whose parent is not addressable is stored as the complete raw frozen Create packet;
• no child entity record, accepted snapshot, timestamp gate, local ID, event, or residence lease exists yet;
• the queue is keyed by parent GUID but each entry also has a monotonic AdmissionId which is never reset, preventing reset/reconnect ABA reuse;
• a later parent Create may consume only the exact admission token it peeked;
• deleting or replacing a still-missing parent does not discard its queued child Create, matching retail's GUID-keyed placeholder behavior;
• an exact child Delete removes an equal/older deferred child generation even if no child timestamp gate exists;
• generation cleanup preserves an equal or newer deferred child Create and discards only older ownership.

Raw missing-parent replay and actual child creation belong to the future continuation executor/cutover. They are not performed by this checkpoint.

Malformed and saturation behavior

All structural and capacity checks run before consuming a timestamp gate.

• Non-finite Vector and Position payloads are rejected without sequence consumption.
• A full/saturated continuation owner fails before gate acceptance; there is no fallback to ordinary immediate mutation.
• Flattened EntitySpawn projections must exactly agree with the embedded PhysicsDesc for identity, Position, relevant timestamps, parent, and placement.
• When PhysicsDesc is absent, every flattened PhysicsDesc projection must also be absent or zero: Position, Setup, Motion, PhysicsState, scale, friction, elasticity, timestamps, parent, and placement.
• Instance sequence zero remains legal and is covered on the active pending FIFO path.

The last rule prevents synthetic or corrupt packets from creating two contradictory placement authorities even though the production parser normally constructs those projections from one source.

Lifetime and failure guarantees

• Delete cancels the matching residence and its FIFO before the exact entity can be reused.
• New incarnation/GUID reuse cannot observe or adopt an older incarnation's FIFO.
• Session reset/reconnect clears active residence, completed-unadopted batches, deferred raw creates, accepted timestamp ownership, and operation state.
• Reentrant teardown callbacks cannot resurrect the detached owner.
• Completion/adoption revisions cannot wrap into a valid stale token.
• Parent raw-admission IDs cannot wrap or reset into an ABA match.
• Every ownership ledger converges to zero on reset/disposal.

Named-retail oracle

The behavior and reviews used these named-retail anchors:

• SmartBox::HandleCreateObject 0x00454C80 - Create packet ordering and missing-parent precondition;
• SmartBox::ProcessObjectNetBlobs 0x00454B20 - queued packet replay order;
• SmartBox::HandleReceivedPosition 0x00453FD0 - standalone Position route;
• SmartBox::HandleDeleteObject 0x00451EA0 - GUID-keyed delete behavior;
• ACCObjectMaint::CreateObject 0x00558870 - logical object creation;
• CPhysicsObj::set_description 0x00514F40 - PhysicsDesc application order;
• CPhysicsObj::SetPositionInternal 0x00515330 - canonical placement.

Research must continue from docs/research/named-retail/acclient_2013_pseudo_c.txt; use the older Ghidra chunks only as a fallback.

Files in the behavior checkpoint

• src/AcDream.Runtime/Entities/InboundPhysicsStateController.cs
• src/AcDream.Runtime/Entities/ParentAttachmentState.cs
• src/AcDream.Runtime/Entities/RuntimeEntityDirectory.cs
• src/AcDream.Runtime/Entities/RuntimeEntityObjectLifetime.cs
• src/AcDream.Runtime/Entities/RuntimeInitialCreateAdmissionFreezer.cs
• src/AcDream.Runtime/Entities/RuntimeInitialCreateResidenceState.cs
• src/AcDream.Runtime/Physics/RuntimeAuthoritativePositionRouteClassifier.cs
• tests/AcDream.Runtime.Tests/Entities/RuntimeInitialCreateResidenceStateTests.cs
• tests/AcDream.Runtime.Tests/Physics/RuntimeAuthoritativePositionRouteClassifierTests.cs

Automated evidence

Final primary-agent gates on the exact behavior diff:

• focused initial-residence/classifier tests: 89 passed, 0 failed;
• complete Runtime tests: 829 passed, 0 failed;
• complete Release build: 0 warnings, 0 errors;
• complete Release solution: 10,622 passed, 4 intentional skips;
• git diff --check: clean.

Per-project final solution totals:

• App: 4,027 passed / 3 skipped;
• Bake: 15 passed;
• CLI: 4 passed;
• Content: 124 passed;
• Core.Net: 762 passed;
• Core: 4,242 passed / 1 skipped;
• Headless: 76 passed;
• Runtime: 829 passed;
• UI abstractions: 543 passed.

Independent final results:

• retail-conformance reviewer: PASS;
• architecture/adversarial reviewer: PASS.

The reviews explicitly checked exact retail order, gate-only frozen state, missing-parent placeholder lifetime, zero instance, delete/reset/GUID reuse, deep freezing, malformed duplicated projections, capacity preflight, reentrancy, and the absence of executor/cutover work.

No connected visual gate is required for this checkpoint because production graphical and headless routes remain unchanged and the new owner is exercised only through deterministic Runtime tests.

Deliberately unchanged production routes

At this checkpoint:

• graphical Create/Position still use the existing App route;
• headless Create/Position still use the existing no-window projection route;
• no host drains RuntimeInitialCreateResidenceState.Continuations;
• no raw missing-parent child Create is replayed;
• no new gameplay/presentation callback is emitted;
• no AP-1 or AD-1 divergence row is retired;
• AP-22 and AD-10 are untouched.

Do not mistake the stored FIFO for completed game behavior. The clean next boundary is the executor that applies it.

Next implementation boundary

Implement only the Runtime continuation executor and retail Create tail.

The executor must:

1. consume the exact initial placement acknowledgement once;
2. capture executor-time inputs at the retail decision point;
3. apply the initial Create tail in retail order;
4. drain mixed continuations strictly by retained sequence;
5. preserve same-Create atomicity;
6. keep the FIFO head retryable if an external host receipt is temporarily unavailable;
7. make every hook, timestamp, placement, and event side effect exactly once;
8. consume a raw missing-parent Create only through its exact AdmissionId;
9. abandon safely on delete, reset, replacement, or generation mismatch;
10. produce host-independent immutable results rather than calling App or headless presentation directly.

Do not combine the executor with graphical/headless cutover. After the executor is independently green, the following checkpoint may switch every Create, Position, ForcePosition, Parent, Pickup, withdrawal, remote, projectile, dropped-item, and teardown route across both hosts together.

Only after executor plus all-host cutover and connected gates pass may AP-1 and AD-1 retire. AP-22 and AD-10 remain later independent slices.

Rollback

Revert this behavior checkpoint without disturbing the prior residence foundation:

git revert 30012361e12222e8271b1531574257ba910c77cb

The documentation checkpoint containing this file is separate and may be reverted independently if only the handoff text needs correction.

Resume checklist

1. Open the exact worktree and branch above.
2. Confirm git log -3 --oneline contains behavior 30012361 and the documentation commit containing this file.
3. Preserve every unrelated dirty path listed above.
4. Read this file, docs/architecture/acdream-architecture.md, docs/research/2026-08-01-runtime-initial-create-residence-handoff.md, and docs/research/2026-07-31-canonical-set-position.md.
5. Re-run the focused 89-test gate before changing admission/execution code.
6. Begin only the continuation executor. Do not begin production cutover, AP-22, AD-10, or vendor work in the same checkpoint.