302 lines
14 KiB
Markdown
302 lines
14 KiB
Markdown
# 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.
|