docs(physics): hand off initial create residence

docs/plans/2026-04-11-roadmap.md

@@ -66,17 +66,17 @@ waived the general sweep and explicitly deferred the barred-house gate as
 authorized retirement of the remaining proven collision/placement gaps before
 vendor work resumes. Nested retry, edge/StepDown/Path-6 ordering, exact cell
 availability, atomic collision generations, canonical Core SetPosition,
-Runtime lost-cell residence, and the dormant placement receipt channel are
-landed. Placement Slice 4B2 checkpoint 2 adds the presentation-free Runtime
-owner for retail collision tracking, environment latch, ordered callbacks,
-missile-state clearing, expiry/force-end lifetime, and SetPosition's exact
-report-result boolean. It deliberately does not activate an App or Headless
-production route. Next are exact authored mover preparation, the atomic shared
-body/controller transaction, presentation-only placement observers, collision-
-prefix quiescence, and the all-route cutover which can retire AP-1/AD-1. AP-22
-authored object shapes and AD-10 remote contact-plane projection follow, then
-the final matrix and ledger closeout. Detailed handoff:
-[`2026-07-31-runtime-set-position-collision-reporting-handoff.md`](../research/2026-07-31-runtime-set-position-collision-reporting-handoff.md).
+Runtime lost-cell residence, authored mover/body preparation, placement
+receipts and observers, collision-prefix replacement, authoritative route
+classification, and initial Create residence are landed as bisectable
+checkpoints. Commit `38fd4b8d` retains the accepted Create placement plus
+fresher Position FIFO until exact placement and ordered adoption complete.
+Production Create registration is not yet cut over. Next are the synchronous
+Runtime continuation executor, retail's exact Create tail ordering, and the
+all-host/all-route cutover which can retire AP-1/AD-1. AP-22 authored object
+shapes and AD-10 remote contact-plane projection follow, then the final matrix
+and ledger closeout. Current handoff:
+[`2026-08-01-runtime-initial-create-residence-handoff.md`](../research/2026-08-01-runtime-initial-create-residence-handoff.md).
 
 ---
 

docs/plans/2026-05-12-milestones.md

@@ -91,14 +91,15 @@ broaden the feature surface. Slices 1–4 are user-accepted. Campaign P's
 connected feel matrix closed on 2026-07-31 with tight-gap collision clearance
 (#273) and the deferred restricted-house gate (#274) explicitly carried. The
 user subsequently authorized the remaining physics-divergence closeout before
-vendor work. Placement Slice 4B2 checkpoint 2 now gives Runtime the retail
-SetPosition collision table, environment latch, ordered report callbacks, and
-exact report-result owner without activating production placement. The
-remaining order is authored mover/body preparation, atomic graphical/no-window
-body publication, presentation-only projection and prefix quiescence, then the
-all-route SetPosition cutover; AP-22 shape fidelity and AD-10 remote contact-
-plane projection follow. Resume Slice 5 vendor browsing only after that
-closeout or a new explicit user direction.
+vendor work. Placement Slice 4B2 is now complete through dormant SetPosition
+activation, graphical/no-window placement receipts, collision-prefix
+replacement, authoritative route classification, pre-placement App staging,
+and Runtime's initial Create residence/FIFO transaction at `38fd4b8d`.
+Production Create registration is not yet cut over. The remaining order is one
+synchronous continuation executor with retail's exact Create tail, the all-
+host/all-route cutover, AP-22 shape fidelity, AD-10 remote contact-plane
+projection, and the final matrix/ledger closeout. Resume Slice 5 vendor
+browsing only after that closeout or a new explicit user direction.
 
 The separately authorized modern-runtime performance program has completed
 Slices A–D: corrected measurement, prepared-package bake/dedup, package-only

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

@@ -0,0 +1,297 @@
+# Runtime initial Create residence handoff - 2026-08-01
+
+## 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.

memory/project_collision_port.md

@@ -1,5 +1,22 @@
 # Collision System Port - Status and Plan
 
+## 2026-08-01 initial Create residence checkpoint
+
+The dormant Runtime SetPosition path is now complete through activation,
+graphical/no-window placement receipts, collision-prefix quiescence, exact
+authoritative route classification, pre-placement App staging, and initial
+Create residence. Commit `38fd4b8d` owns the accepted initial Create frame,
+cell-less pending lifetime, fresher Position FIFO, exact completion/adoption
+revision, and reentrant teardown. Its retail and continuation handoff is:
+
+- `docs/research/2026-08-01-runtime-initial-create-residence-handoff.md`
+
+Production Create registration has not yet been cut over. Next, implement the
+synchronous Runtime continuation executor and exact Create tail order
+(visual, Parent/Position/Pickup, Movement, State, Vector, WeenieDesc, cleanup),
+then cut graphical and no-window hosts over together. AP-1/AD-1 remain open
+until that cutover. AP-22 and AD-10 follow as separate behavior slices.
+
 ## 2026-07-31 placement checkpoint 2
 
 Runtime now owns the retail collision-report state required by canonical