acdream/docs/research/2026-08-01-runtime-initial-create-residence-handoff.md

# Runtime initial Create residence handoff - 2026-08-01

> **Status:** this remains the `38fd4b8d` residence-foundation history. The
> completed inbound-admission checkpoint and current continuation boundary are
> recorded in
> [`2026-08-01-runtime-initial-placement-admission-handoff.md`](2026-08-01-runtime-initial-placement-admission-handoff.md).

## Purpose and exact stopping point

Commit `38fd4b8dc952236d4b98518c67335026c7815656` adds the dormant Runtime
transaction which retains an entity's initial authored CreateObject placement
until canonical SetPosition succeeds and the ordered remainder of the Create
packet can be adopted. It does not yet cut the production App/Headless Create
route over, so AP-1 and AD-1 remain open.

This is the deliberate clean handoff requested by the user. In plain terms,
Runtime now has a tested holding area for a newly created world object while
its exact collision placement is being resolved. The object cannot become
half-visible, consume later position packets, or be silently replaced during
that interval. The next model starts at the executor/cutover boundary; it does
not need to repair or redesign this ownership transaction.

Do not start production cutover from an earlier checkpoint. Do not call this
campaign complete: AP-1, AD-1, AP-22, and AD-10 remain open.

## Exact workspace and Git state

- Worktree: `C:\Users\erikn\.codex\worktrees\af5e\acdream`
- Branch: `codex/port-claude-agents`
- Code checkpoint: `38fd4b8dc952236d4b98518c67335026c7815656`
- Immediately preceding host-staging checkpoint: `74103f75`
- No push or merge is part of this stopping point.

The worktree intentionally contains unrelated user changes/stat noise. Do not
stage, restore, normalize, or rewrite these paths as part of the continuation:

- `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`.

The paths after `AGENTS.md` currently have no content diff and are reported
because of pre-existing line-ending/stat noise. Always stage exact paths;
never use `git add -A`.

## Placement checkpoint chain

The current mechanism was built as bisectable commits. The directly relevant
chain, oldest first, is:

- `e84a388e` - pure Core retail SetPosition transaction;
- `4c02ac42` - Runtime deferred/lost-cell residence owner;
- `270f5154` - dormant placement receipt channel;
- `237d1184` - retail SetPosition collision-report owner;
- `442cb8f9` - exact authored mover preparation;
- `22651c82` - dormant Runtime local physics publication;
- `99f867f0` - sealed dormant SetPosition evaluation;
- `5785a07b` - dormant SetPosition activation;
- `ef436678` - placement acknowledgement ownership;
- `74c9b155`, `378ca95a`, `f05ed5c3` - graphical/headless projection seams;
- `99bf1751`, `9b0f59bd` - collision-prefix quiescence and atomic replacement;
- `0fbc7a1f` - hidden-object SetPosition ownership correction;
- `3f800a4a` - authoritative route classification;
- `74103f75` - inert App materialization before Runtime placement;
- `38fd4b8d` - initial Create residence, continuation FIFO, and adoption.

## Owned mechanism in `38fd4b8d`

`RuntimeInitialCreateResidenceState` now owns, per exact entity incarnation:

- the accepted initial Create frame and exact SetPosition operation;
- a cellless logical entity while authored placement is pending;
- a monotonic immutable FIFO for fresher Position continuations;
- accepted timestamp, position, vector, rotation, placement, and wire payloads;
- completion/adoption tokens and a revision which reject stale observers;
- exact authority revalidation across generation, identity, Create, position,
  placement, full-cell, deletion, reset, GUID reuse, and disposal;
- reentrant-safe cancellation at the lifetime commit boundary.

The public legacy registration path is intentionally unchanged. Production
behavior remains on the previous route until the continuation executor and
all-host cutover land together.

### Exact behavior now protected

- Initial/New Create admission is previewed without consuming timestamps;
  Existing and Stale packets still use the established gates.
- No collision generation is guessed. An initial residence can exist only
  after binding a real, nonzero generation.
- Fresh Parent wins over Position, matching the packet's relation priority.
- An absent or present-zero position cell remains cellless instead of being
  fabricated as an outdoor placement.
- Later accepted Position packets append to one immutable ordered FIFO. They
  cannot mutate the original placement operation or bypass it.
- A completed but not yet adopted transaction remains exclusive. A later
  Position revises the retained batch and invalidates the old adoption token;
  it cannot disappear between completion and acknowledgement.
- Placement acknowledgement uses exact identity, operation, generation,
  position authority, Create integration, full-cell, and placement-commit
  versions.
- Reset first detaches and clears ownership, then publishes cancellation, so a
  reentrant observer cannot invalidate enumeration or resurrect an owner.
- Delete, replacement, pickup, parent, withdrawal, reset, and disposal return
  cancellation receipts to the caller's safe publication boundary instead of
  invoking observers before later canonical mutation.
- Malformed initial or continuation packets fail before timestamp or canonical
  state consumption. A corrected packet with the same instance can recover.

The FIFO stores raw accepted Position facts rather than prematurely choosing
a final movement route. That is intentional: contact, animation state, the
server-position option, and player distance must be sampled at the same point
where retail makes the routing decision.

## Exact files in `38fd4b8d`

- `src/AcDream.Core/Physics/PhysicsTimestampGate.cs`
- `src/AcDream.Runtime/Entities/InboundPhysicsStateController.cs`
- `src/AcDream.Runtime/Entities/RuntimeEntityDirectory.cs`
- `src/AcDream.Runtime/Entities/RuntimeEntityObjectLifetime.cs`
- `src/AcDream.Runtime/Entities/RuntimeInitialCreateResidenceState.cs`
- `src/AcDream.Runtime/Physics/RuntimeAuthoritativePositionRouteClassifier.cs`
- `src/AcDream.Runtime/Physics/RuntimeSetPositionState.cs`
- `tests/AcDream.Core.Tests/Physics/MotionSequenceGateTests.cs`
- `tests/AcDream.Runtime.Tests/Entities/RuntimeInitialCreateResidenceStateTests.cs`
- `tests/AcDream.Runtime.Tests/Physics/RuntimeAuthoritativePositionRouteClassifierTests.cs`

## Retail order for the next slice

The next slice must preserve `SmartBox::HandleCreateObject` at `0x00454C80`:

1. visual description;
2. exactly one of Parent, Position, or Pickup relation;
3. Movement;
4. State;
5. Vector;
6. Weenie description;
7. final resident-cell validity cleanup.

Position routing must also preserve these named-retail distinctions:

- a same-incarnation Create position is not equivalent to standalone F748;
- ForcePosition performs its own timestamp/parent/placement route;
- remote near-contact interpolates, remote far-contact stops interpolation and
  performs SetPosition, and remote teleport invokes the teleport hook before
  SetPosition;
- local teleport performs SetPosition, then the player-teleported hook, then
  constrains to the authoritative frame and clears velocity;
- local ordinary Position constrains first and interpolates only when the
  server-position option and contact gate permit it.

Therefore every retained continuation must include its
`RuntimeAcceptedPositionSource`, and executor-time inputs must pin HasAnims,
UsePositionFromServer, contact, and distance before mutation. Parent/Pickup and
the same-Create Movement -> State -> Vector order must be part of the same
synchronous adoption transaction.

The principal named-retail anchors are:

- `SmartBox::HandleCreateObject` `0x00454C80`;
- `CPhysicsObj::SetPositionInternal` `0x00515330`;
- `PhysicsDesc::UnPack` `0x0051DDD0`;
- `CPhysicsObj::set_description` `0x00514F40`.

Use `docs/research/named-retail/acclient_2013_pseudo_c.txt` first and the older
Ghidra chunks only as a fallback.

## Validation and reviews

The implementation agent and reviewers reported:

- focused initial-residence and classifier tests: 79/79;
- complete Runtime tests: 819/819;
- Runtime Release build: zero warnings and errors;
- focused Core timestamp tests: 31/31;
- retail-conformance review: clean;
- architecture/adversarial review: clean;
- `git diff --check`: clean.

Primary-agent final gates after the behavior commit:

- complete Release solution build: succeeded, 0 errors;
- complete Release solution tests: 10,612 passed / 4 intentional skips;
- App: 4,027 passed / 3 skips;
- Core: 4,242 passed / 1 skip;
- Runtime: 819 passed;
- Core.Net: 762 passed;
- UI abstractions: 543 passed;
- Headless: 76 passed;
- Content: 124 passed;
- Bake: 15 passed;
- CLI: 4 passed.

The build reports 21 pre-existing test-project nullable/analyzer warnings. The
checkpoint introduces no build errors or new production warning.

Both independent reviews initially found real edge cases and the final code
includes their root-cause fixes:

- completed-but-unadopted Position packets could bypass the FIFO;
- cancellation callbacks could re-enter before the caller's canonical mutation;
- reset could enumerate live dictionaries while a callback mutated them;
- adoption did not initially validate every spatial/authority version.

Final retail-conformance and architecture/adversarial rereviews both passed.
No connected visual gate was required because the new API is dormant and no
production App or Headless route calls it yet.

## Production routes intentionally unchanged

This is the key handoff boundary. At this checkpoint:

- graphical Create still flows through
  `LiveEntityHydrationController.OnCreateCore`,
  `LiveEntityRuntime.RegisterLiveEntity`, and legacy `RegisterEntity`;
- graphical materialization still defaults to `LegacyImmediate` rather than
  the new `AwaitRuntimePlacement` residence;
- graphical Position still performs its existing world-position, rebucket,
  projectile, remote-motion, and shadow work;
- headless Create still uses `RuntimeLiveEntitySessionController.OnSpawned`,
  `HeadlessSessionWorldProjection.ProjectSpawn`, and its independent initial
  resolve/body construction;
- headless Position still uses its existing projection path;
- the new Runtime initial-residence API is reached by focused tests only.

Existing host adapters already observe Runtime placement receipts. Do not add
another observer architecture or a second GUID map.

## Next implementation boundary

Implement one Runtime continuation executor and exact ordered Create tail,
then route graphical and no-window registration through it without a mirror.
The executor must be synchronous or retry-idempotent around adoption revision;
failure must leave the exact FIFO head retryable. Only after both production
hosts and every Create/Position/ForcePosition/parent/pickup route use the same
owner may AP-1 and AD-1 retire.

### Required order for the next model

1. Add `RuntimeAcceptedPositionSource` to every retained continuation. A
   same-incarnation Create position and standalone F748 are not interchangeable.
2. Implement one Runtime-owned synchronous continuation executor. Capture
   `UsePositionFromServer`, animation/contact state, and player distance at the
   retail-equivalent decision point.
3. Execute initial placement once, consume its exact host acknowledgement,
   then drain the continuation FIFO in order with retail's hook ordering.
4. Serialize one Create packet as relation
   (Parent/Position/Pickup), Movement, State, Vector, WeenieDesc, cleanup.
5. Keep every side effect exactly-once. If execution can yield, make adoption
   revision/idempotence explicit so retry cannot replay hooks or position sends.
6. Switch graphical and headless registration together to the same Runtime
   owner. Hosts may project immutable results only; they may not resolve a
   second placement or create another body.
7. Route later Create, Position, ForcePosition, teleport, parent, pickup,
   withdrawal, delete, remote, projectile, and dropped-item edges through the
   same owner before deleting legacy paths.
8. Run focused tests, full Release build/tests, exact lifecycle/reconnect and
   nine-stop connected gates, then perform the user visual matrix. Only then
   retire AP-1 and AD-1.

Do not begin AP-22 or AD-10 until the production placement cutover is green.

### Subsequent independent slices

- **AP-22:** make `ShadowShapeBuilder` the only prepared Setup-shape authority;
  preserve authored cylinder order, use spheres only when cylinders are absent,
  allow truly shapeless Setups, and remove radius/height synthesis and sphere-
  to-cylinder coercion across graphical/headless/live publication.
- **AD-10:** remove terrain-normal preprojection from remote motion. Let the
  canonical transition resolver project against the actual retained contact
  plane, with tests where terrain and BSP/prop normals deliberately differ.
- Run the final connected matrix, synchronize ledgers/docs, and only then close
  the remaining physics-divergence campaign.

## Rollback

Revert the behavior checkpoint without disturbing the earlier placement
foundation:

```powershell
git revert 38fd4b8dc952236d4b98518c67335026c7815656
```

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

## Resume checklist

1. Continue in the exact worktree and branch recorded above.
2. Confirm `git rev-parse HEAD` includes both the behavior and documentation
   checkpoint commits.
3. Read this file, `docs/architecture/acdream-architecture.md`,
   `docs/research/2026-07-31-canonical-set-position.md`, and
   `docs/research/2026-07-31-runtime-set-position-collision-reporting-handoff.md`.
4. Run `git status --short` and preserve every unrelated path listed above.
5. Re-run the focused 79-test residence/classifier gate before modifying the
   transaction.
6. Begin only the continuation executor and ordered Create tail. Do not start
   AP-22/AD-10 or vendor work in the same commit.