diff --git a/docs/ISSUES.md b/docs/ISSUES.md index bfe40dfd..43677b55 100644 --- a/docs/ISSUES.md +++ b/docs/ISSUES.md @@ -99,6 +99,25 @@ Copy this block when adding a new issue: --- +## #275 — Unify the legacy Position wire path onto the executor's route classifier + +**Status:** OPEN — post-cutover (physics campaign, filed 2026-08-02) +**Severity:** LOW (internal refactor debt; not a retail divergence) +**Component:** Runtime / inbound Position + +**Description:** the legacy `InboundPhysicsStateController.TryApplyPosition` +(today's only production Position wire caller) has no route-classification or +contact concept; the continuation executor's `ApplyPositionAction` runs +`RuntimeAuthoritativePositionRouteClassifier` with the wire's own `IsGrounded` +bit and threads the classified `installPlacementFrame`/`clearParent` flags +(register rows AP-131 documents the legacy caller's unconditional flags, AD-60 +the cell-semantics difference). When the production cutover wires the executor +in, unify the legacy caller onto the same classifier (or delete it with the +route) and retire AP-131/AD-60's legacy halves. See +`InboundPhysicsStateController.TryApplyPosition` remarks. + +--- + ## #274 — Restricted/barred-house entry needs a connected retail comparison **Status:** OPEN — explicitly deferred by the user on 2026-07-31 diff --git a/docs/architecture/acdream-architecture.md b/docs/architecture/acdream-architecture.md index cd2422b7..6a356684 100644 --- a/docs/architecture/acdream-architecture.md +++ b/docs/architecture/acdream-architecture.md @@ -233,6 +233,9 @@ src/ boundary for dormant initial placement RuntimeInitialCreateResidenceState.cs -> exact-incarnation initial placement lease and accepted mixed-update FIFO + RuntimeInitialCreateContinuationExecutor.cs -> retry-idempotent + adoption + retail Create tail + strict-order + FIFO/replay execution over the residence Gameplay/ RuntimeCommunicationState.cs -> one chat/social owner + ordered stream RuntimeInventoryState.cs -> exact object-table borrower + inventory @@ -608,9 +611,25 @@ 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. +The admission checkpoint (`30012361`) intentionally stopped before executing +the FIFO. The continuation executor (`5db3de3c`, +`RuntimeInitialCreateContinuationExecutor`) completes the mechanism: one +synchronous, retry-idempotent `Execute` transaction adopts the acknowledged +initial placement exactly once, emits the local player's after-enter-world +hook request, replays deferred missing-parent raw Creates and queued parent +relations by parent GUID (whole-bucket detach, FIFO dispatch, +cancellation-aware restore windows), and drains the mixed FIFO strictly by +sequence — classifying each retained Position at execution time with live +inputs and driving authored placements through the canonical +`RuntimeSetPositionState` lifecycle with retryable yields. Apply bodies are +shared with the legacy fused inbound paths through gate-less instance seams +that keep the one snapshot store in lockstep; same-incarnation Create +envelopes apply atomically with buffered publication; every abandonment path +retires the residence and converges the combined ownership ledger. The +executor has NO production caller yet — graphical and no-window Create still +use legacy `RegisterEntity` — and the next checkpoint must switch both +production routes onto 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 diff --git a/docs/plans/2026-04-11-roadmap.md b/docs/plans/2026-04-11-roadmap.md index 587db849..5afef9d6 100644 --- a/docs/plans/2026-04-11-roadmap.md +++ b/docs/plans/2026-04-11-roadmap.md @@ -76,12 +76,20 @@ 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). +covered. Commit `5db3de3c` (2026-08-02) completes the continuation executor: +retry-idempotent single adoption of the acknowledged initial placement, +retail's exact Create tail, GUID-keyed deferred-child and parent-relation +replay with cancellation-aware windows, strict-sequence mixed-FIFO drain with +execution-time retail Position routing, shared apply bodies keeping one +snapshot store in lockstep, and converged ownership ledgers on every +abandonment path — dual independent reviews PASS; register rows +AD-59/AD-60/AP-130/AP-131/AP-132/TS-62/TS-63 filed in the same commit. +Production Create registration is not yet cut over (the executor has no +production caller). Next is the all-host/all-route cutover which can retire +AP-1/AD-1 behind its connected/visual gates. AP-22 authored object shapes and +AD-10 remote contact-plane projection follow, then the final matrix and +ledger closeout. Current handoff: +[`2026-08-02-runtime-continuation-executor-handoff.md`](../research/2026-08-02-runtime-continuation-executor-handoff.md). --- diff --git a/docs/plans/2026-05-12-milestones.md b/docs/plans/2026-05-12-milestones.md index 3f83721d..42beaa8a 100644 --- a/docs/plans/2026-05-12-milestones.md +++ b/docs/plans/2026-05-12-milestones.md @@ -99,14 +99,22 @@ 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. +placement waits. The continuation executor is complete at `5db3de3c` +(2026-08-02): one retry-idempotent Runtime `Execute` transaction adopts the +acknowledged initial placement exactly once, applies retail's Create tail, +replays deferred missing-parent raw Creates and queued parent relations by +parent GUID with cancellation-aware detach/restore windows, and drains the +mixed FIFO strictly by sequence with execution-time retail Position routing +through the canonical SetPosition lifecycle. Independent retail-conformance +and architecture/adversarial reviews both PASS after five implementation +rounds; register rows AD-59/AD-60/AP-130/AP-131/AP-132/TS-62/TS-63 document +the slice's deviations; Runtime tests 903/903, complete Release solution +10,696/4 skips. Production Create registration is still NOT cut over — the +executor has no production caller. The remaining order is the all-host/ +all-route cutover (which can retire AP-1/AD-1 behind its connected/visual +gates), 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-placement-admission-handoff.md b/docs/research/2026-08-01-runtime-initial-placement-admission-handoff.md index 4a3ec33f..06e790f3 100644 --- a/docs/research/2026-08-01-runtime-initial-placement-admission-handoff.md +++ b/docs/research/2026-08-01-runtime-initial-placement-admission-handoff.md @@ -1,5 +1,11 @@ # Runtime initial-placement admission handoff - 2026-08-01 +> **Status:** this remains the `30012361` admission-checkpoint history. The +> continuation executor this file scoped as "the next implementation +> boundary" is complete at `5db3de3c`; the current boundary (production +> cutover) is recorded in +> [`2026-08-02-runtime-continuation-executor-handoff.md`](2026-08-02-runtime-continuation-executor-handoff.md). + ## Purpose and exact stopping point Behavior commit `30012361e12222e8271b1531574257ba910c77cb` diff --git a/docs/research/2026-08-02-runtime-continuation-executor-handoff.md b/docs/research/2026-08-02-runtime-continuation-executor-handoff.md new file mode 100644 index 00000000..a19cb239 --- /dev/null +++ b/docs/research/2026-08-02-runtime-continuation-executor-handoff.md @@ -0,0 +1,211 @@ +# Runtime initial-placement continuation executor handoff - 2026-08-02 + +## Purpose and exact stopping point + +Behavior commit `5db3de3c7ab2c6350d11af7f34b852464fc1e0f9` implements the +Runtime continuation executor: the missing mechanism that, once an entity's +initial authored placement is acknowledged, adopts that placement exactly +once, applies the retail Create tail, replays deferred missing-parent work, +and drains the admission checkpoint's mixed continuation FIFO in exact +arrival order with retail route decisions made at execution time. The +residence system built by `38fd4b8d` (residence/FIFO) and `30012361` +(admission) is now COMPLETE as a mechanism: an entity can enter the world +through it and every packet accepted while its placement was pending is +applied exactly once, in order, with retail semantics. + +This checkpoint deliberately does NOT cut the graphical or headless +production routes over — `RuntimeLiveEntitySessionController.cs` (headless) +and App's `LiveEntityRuntime` still call legacy `RegisterEntity`, and no host +calls `Execute`. It does not begin AP-22 or AD-10 and does not retire +AP-1/AD-1. The executor is exercised by deterministic Runtime tests only, so +no connected visual gate was required. + +This file supersedes the executor-boundary portions of +[`2026-08-01-runtime-initial-placement-admission-handoff.md`](2026-08-01-runtime-initial-placement-admission-handoff.md). + +## Exact workspace and Git state + +- Worktree: `C:\Users\erikn\.codex\worktrees\af5e\acdream` +- Branch: `codex/port-claude-agents` +- Behavior checkpoint: `5db3de3c7ab2c6350d11af7f34b852464fc1e0f9` +- Documentation checkpoint: the commit containing this file +- The same eight unrelated dirty paths as the admission handoff remain + intentionally unstaged; never stage by blanket. +- No push or merge is part of this checkpoint. + +## What the executor owns + +`RuntimeInitialCreateContinuationExecutor` (constructed inside +`RuntimeEntityObjectLifetime` beside the residence state; internal +`InitialCreateExecution`; generation bound through `BindEventContext`) owns, +per exact `RuntimeEntityKey` + lease: + +- the synchronous, retry-idempotent `Execute` transaction: + `Complete` -> `AdoptCompletedPlacement` (consumes the acknowledged initial + placement exactly once, resolving the `HasRetainedCompletion` deadlock so + later authored placements for the key can begin, with `PlacementAdopted` + keeping the completed entry current) -> AfterEnterWorld hook request + (local player, exactly once) -> deferred replay -> strict-sequence FIFO + drain -> `ConsumeExecuted` release (adoption-revision-checked; `Revised` + re-drains only the tail); +- per-continuation applies through gate-less instance seams on + `InboundPhysicsStateController` (`ApplyAccepted*Snapshot`) that read and + write the ONE snapshot store — the legacy fused paths are re-expressed as + gate + the same shared merge bodies, so there is no drift and no second + canonical snapshot; +- execution-time Position routing via + `RuntimeAuthoritativePositionRouteClassifier.ClassifyAcceptedPosition` + with live inputs: the retained wire packet's own `IsGrounded` bit as the + server-asserted contact (never the local body), the data-driven + `(MotionTableId ?? Physics?.MotionTableId)` animation proxy (AP-130), live + distance/`UsePositionFromServer`, and the record's committed cell — driving + authored placements for SetPosition routes through the canonical + `RuntimeSetPositionState` Begin/Watch/resume lifecycle with a retryable + `AwaitingContinuationPlacement` yield (a contention flavor with no pending + token means "retry Execute later"); +- atomic `SameIncarnationCreate` envelopes: per-stage index idempotency, + buffered publication flushed in stage order after the final stage (AD-59), + the object-table apply via the accepted-spawn seam (result observed; a + nested replacement abandons), and the three-branch resident-cell + disposition (TS-63); +- missing-parent replay, both flavors, keyed by parent GUID exactly as + retail's `QueueBlobForObject`/`ProcessObjectNetBlobs`: raw child Creates + AND queued accepted parent relations, drained in the initial tail with + whole-bucket atomic detach, per-entry exception containment + (`ReplayFailureCount`/`LastReplayFailure`), typed outcomes + (Registered/ReDeferred/Rejected; ParentApplied/DeferredAwaitingParent/ + DiscardedStaleParent), and cancellation-aware restore windows whose tokens + record every cancellation fired while a batch is detached (ABA-safe; + a cleared token restores nothing); +- the field-masked executor baseline: each apply re-syncs ONLY the tracked + fields its own mutations moved, before publication, so external mutations + are detected in every quiet window and publish-callback; +- one shared abandonment routine on every non-retryable exit: forgets any + pending continuation placement (cancellation published), retires the + residence through the lifetime choke point, discards progress, returns a + typed status — the combined ownership ledger (residences, executor + progress, deferred buckets, replay windows, placement watches) converges, + and residence retirement notifies the executor + (`BindRetirementNotification`); +- an ordered immutable execution receipt/trace carrying every fact a cutover + host needs: per-action kind/sequence/stage, Position route facts + (disposition, constrain phase, teleport-hook phase, stop-interpolation, + zero-velocity, preserve-heading, send-position-immediately, unparent), + replay outcomes, and resident-cell dispositions. + +## Retail anchors proven this slice + +Beyond the admission handoff's eight anchor functions: + +- retail's local-ordinary interpolate gate is + `UsePositionFromServer && wire-contact` — `PositionPack` bit 0x4 → + `has_contact` (pseudo-C 284654) → `UnpackPositionEvent` arg5 (93092) → + the gate at 93044. The earlier research note's "isForce" reading was a + misnomer disproven during review; the shipped classifier was correct. +- `ProcessObjectNetBlobs` detaches the whole per-GUID bucket before + dispatching (93617 → 93649) — mirrored by the detach/restore windows. +- missing-parent relations are QUEUED by parent GUID (standalone parent + handler 0x004535D0: lookup 92312, queue 92326; `QueueBlobForObject` + 0x005092D0's GUID-keyed placeholder bucket 271082-271088) — never + discarded; the round-4 discard was overturned on this evidence. +- `HandleReceivedPosition`'s `HasAnims` gate (92992) is animation-queue + presence (`CSequence::has_anims` = non-empty list), anchoring AP-130. +- the same-incarnation tail order and resident-cell cleanup + (93865..93943) are mirrored stage-for-stage, with the claimedCell==0 + destruction branch proven structurally unreachable for admitted envelopes + (every envelope carries a WeenieDescription by shape). + +## Divergence register + +Rows filed in the behavior commit: **AD-59** (envelope buffered live-record +events), **AD-60** (executor canonical cell semantics — wire positions never +directly commit residency), **AP-130** (HasAnims MotionTableId proxy), +**AP-131** (legacy Position merge's unconditional placement-frame/parent- +clear flags — retired by construction at cutover), **AP-132** (parent +incarnation gating vs retail's pointer-only GUID replay), **TS-62** (no live +ConstrainTo binding in the dormant slice — trace-only), **TS-63** +(resident-cell abandonment/delegation split). AP-1 and AD-1 remain open +until the cutover. Issue **#275** tracks the post-cutover unification of the +legacy Position path onto the classifier. + +## Validation + +- Focused executor/residence/classifier gate: **161/161**. +- Complete Runtime project: **903/903** (829 baseline + 74 slice tests). +- Complete Release solution: **10,696 passed / 4 intentional skips / 0 + failed** (`-m:1`, installed `acdream.pak`); Release build 0 errors, + 21 pre-existing test-project warnings. +- `git diff --check` clean; the eight unrelated dirty paths untouched. +- Independent reviews (both read-only, both required to PASS): the + retail-conformance reviewer and the architecture/adversarial reviewer each + ran four passes across five implementation rounds. Finding classes fixed + at root cause along the way: wire-vs-body contact source; two-store + snapshot divergence; WeenieDescription wholesale-overwrite; non-converging + abandonment; reentrant mid-drain residence retirement; the + acknowledged-completion leak that would have blocked all future placements + for a key; per-field baseline blessing; replay exception containment and + detached-batch resurrection; and the stale-parent discard overturned in + favor of retail's queue-by-parent-GUID replay. Final verdicts: RETAIL + REVIEW: PASS; ARCHITECTURE REVIEW: PASS (three residual NOTEs, all + defense-in-depth observations, none blocking). + +## Production routes intentionally unchanged + +Graphical Create still flows through `LiveEntityRuntime.RegisterEntity`; +headless still uses `RuntimeLiveEntitySessionController`'s legacy +`RegisterEntity`; no production code calls +`RegisterEntityWithInitialResidence` or `Execute`. The residence+executor +system is a complete, reviewed, dormant mechanism awaiting the cutover. + +## Next implementation boundary — the production cutover + +Route graphical AND headless registration through the residence+executor +owner together, then every Create, Position, ForcePosition, Parent, Pickup, +withdrawal, delete, remote-movement, projectile-correction, and dropped-item +edge through the same transaction. Hosts project immutable Runtime results +only; they may not resolve a second placement or create another body. Delete +the legacy duplicate paths only after parity tests pass (this retires AP-131 +and closes #275 by construction). Run the exact lifecycle/reconnect and +canonical nine-stop connected routes, two-client observation, and the user +visual matrix. Only then retire AP-1 and AD-1. + +Cutover-specific notes from this slice: + +- The execution receipt carries every route fact a host must bind — the + constrain phases and stop-interpolation/zero-velocity flags (TS-62), the + teleport-hook phases, and the send-position-immediately echo. +- `AwaitingContinuationPlacement` has two flavors: pending token (host must + prepare/submit/acknowledge the placement, then retry Execute) and + contention (no pending token; retry Execute after the conflicting + operation resolves). +- The dormant placement path's 1,880-bytes/operation allocation budget + (2,048 cap) remains the standing 4B2 activation blocker for + frame-frequency traffic; resolve or budget it before the cutover routes + high-frequency Position traffic through the owner. + +After the cutover: **AP-22** (authored collision shapes; +`ShadowShapeBuilder` sole authority), then **AD-10** (remote contact-plane +projection), then the final automated + connected matrix and ledger +synchronization close the campaign; vendor Slice 5 resumes after. + +## Rollback + +```powershell +git revert 5db3de3c7ab2c6350d11af7f34b852464fc1e0f9 +``` + +The documentation checkpoint containing this file is separate and may be +reverted independently. Do not revert the `38fd4b8d`/`30012361` foundation +beneath it without a separately proven defect. + +## Resume checklist + +1. Continue in the exact worktree/branch above; confirm `git log` contains + `5db3de3c` and the documentation commit containing this file. +2. Preserve the eight unrelated dirty paths; never `git add -A`. +3. Read this file, the admission handoff, and + `docs/architecture/acdream-architecture.md`. +4. Re-run the focused gate before modifying execution code: + the Residence + Classifier + Executor filter must report 161/161. +5. Begin ONLY the production cutover checkpoint. Do not fold AP-22, AD-10, + or vendor work into it.