diff --git a/docs/architecture/acdream-architecture.md b/docs/architecture/acdream-architecture.md index 4caf2952..cd2422b7 100644 --- a/docs/architecture/acdream-architecture.md +++ b/docs/architecture/acdream-architecture.md @@ -225,8 +225,14 @@ src/ RuntimeEntityObjectLifetime.cs -> one entity/object lifetime root RuntimeEntityObjectEventStream.cs -> canonical ordered entity/object deltas RuntimeEntityObjectViews.cs -> direct allocation-free borrowed views - InboundPhysicsStateController.cs -> retail timestamp/snapshot authority - ParentAttachmentState.cs -> generation-exact parent relations + InboundPhysicsStateController.cs -> retail timestamp/snapshot authority, + including gate-only dormant acceptance + ParentAttachmentState.cs -> generation-exact parent relations plus raw + missing-parent Create admission + RuntimeInitialCreateAdmissionFreezer.cs -> immutable parser-payload copy + boundary for dormant initial placement + RuntimeInitialCreateResidenceState.cs -> exact-incarnation initial + placement lease and accepted mixed-update FIFO Gameplay/ RuntimeCommunicationState.cs -> one chat/social owner + ordered stream RuntimeInventoryState.cs -> exact object-table borrower + inventory @@ -591,6 +597,21 @@ server-GUID/incarnation map, Runtime local-ID allocation/reverse lookup, accepted snapshots and timestamp gates, parent state, session/operation versions, and exact tombstones. `RuntimeEntityRecord` is presentation-free. +Initial world placement has one deliberate dormant exception to ordinary +snapshot publication. While an exact `RuntimeInitialCreateResidenceState` +lease is waiting for its first canonical placement, retail timestamp gates may +accept later same-incarnation Create, ObjDesc, Parent, Pickup, Position, +Movement, State, and Vector packets, but neither the canonical record, public +accepted snapshot, event stream, nor presentation changes. Runtime retains +deep-frozen typed actions in one monotonic arrival-ordered FIFO under the exact +entity key. A Create whose parent is not yet addressable is retained even +earlier as a complete raw packet, before child timestamp admission, and is +guarded by a non-reused admission token. Delete, generation replacement, +reset, GUID reuse, and reentrant teardown discard only the matching ownership. +This checkpoint (`30012361`) intentionally stops before executing the FIFO or +switching graphical/no-window production routes; that later cutover must use +this owner rather than create another snapshot or placement path. + `LiveEntityRuntime` is the App projection/lifecycle host. `RegisterLiveEntity` first creates or refreshes canonical Runtime state without an App record. `MaterializeLiveEntity` claims the Runtime local ID and creates diff --git a/docs/plans/2026-04-11-roadmap.md b/docs/plans/2026-04-11-roadmap.md index a4337243..587db849 100644 --- a/docs/plans/2026-04-11-roadmap.md +++ b/docs/plans/2026-04-11-roadmap.md @@ -71,12 +71,17 @@ 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). +Commit `30012361` completes the bounded inbound-admission checkpoint: all +accepted mixed updates remain deep-frozen in exact arrival order while the +initial placement waits, with no early canonical/public snapshot, event, or +presentation mutation. Missing-parent raw Create, delete, reconnect/reset, +GUID reuse, malformed projections, saturation, and reentrant teardown are +covered. 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-placement-admission-handoff.md`](../research/2026-08-01-runtime-initial-placement-admission-handoff.md). --- diff --git a/docs/plans/2026-05-12-milestones.md b/docs/plans/2026-05-12-milestones.md index 85ec123c..3f83721d 100644 --- a/docs/plans/2026-05-12-milestones.md +++ b/docs/plans/2026-05-12-milestones.md @@ -95,11 +95,18 @@ 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 bounded admission checkpoint is complete at `30012361`: every accepted +same-incarnation Create, ObjDesc, Parent, Pickup, Position, Movement, State, +and Vector update is retained as a deep-frozen, arrival-ordered Runtime action +without changing the canonical/public snapshot or presentation while initial +placement waits. Raw missing-parent Create packets remain pre-timestamp, and +delete, reconnect/reset, GUID reuse, malformed projections, FIFO saturation, +and reentrant teardown are covered. 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 index 9327c452..5bab7ad8 100644 --- 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 diff --git a/docs/research/2026-08-01-runtime-initial-placement-admission-handoff.md b/docs/research/2026-08-01-runtime-initial-placement-admission-handoff.md new file mode 100644 index 00000000..4a3ec33f --- /dev/null +++ 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.