docs(physics): hand off initial placement admission

2026-08-01 21:03:51 +02:00 · 2026-08-01 21:03:51 +02:00 · 4a8f74dc72
commit 4a8f74dc72
parent 30012361e1
5 changed files with 365 additions and 13 deletions
--- a/docs/research/2026-08-01-runtime-initial-create-residence-handoff.md
+++ b/docs/research/2026-08-01-runtime-initial-create-residence-handoff.md
@ -1,5 +1,10 @@
 # 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
--- a/docs/research/2026-08-01-runtime-initial-placement-admission-handoff.md
+++ b/docs/research/2026-08-01-runtime-initial-placement-admission-handoff.md
@ -0,0 +1,314 @@
+# Runtime initial-placement admission handoff - 2026-08-01
+
+## 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:
+
+```powershell
+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.