diff --git a/docs/plans/2026-04-11-roadmap.md b/docs/plans/2026-04-11-roadmap.md index f631d63a..a4337243 100644 --- a/docs/plans/2026-04-11-roadmap.md +++ b/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). --- diff --git a/docs/plans/2026-05-12-milestones.md b/docs/plans/2026-05-12-milestones.md index 5c22e9c5..85ec123c 100644 --- a/docs/plans/2026-05-12-milestones.md +++ b/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 diff --git a/docs/research/2026-08-01-runtime-initial-create-residence-handoff.md b/docs/research/2026-08-01-runtime-initial-create-residence-handoff.md new file mode 100644 index 00000000..9327c452 --- /dev/null +++ b/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. diff --git a/memory/project_collision_port.md b/memory/project_collision_port.md index 5d8409ed..bf488e54 100644 --- a/memory/project_collision_port.md +++ b/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