From f670db4327ff1ebc48176a7565f64e1cc47a60dc Mon Sep 17 00:00:00 2001 From: Erik Date: Sun, 2 Aug 2026 20:08:34 +0200 Subject: [PATCH] docs: next-agent handoff prompt for the collision/placement regressions Self-contained task brief: P1 retirement-receipt exception loop, P2 feel-test placement failures, P3 soak residuals re-judgment, P4 door approach regression, P5 spell-particle deferral, P6 re-verifications; process, gates, and commit rules included. Co-Authored-By: Claude Fable 5 --- .../NEXT-AGENT-PROMPT.md | 155 ++++++++++++++++++ 1 file changed, 155 insertions(+) create mode 100644 docs/research/2026-08-02-collision-throughput-handoff/NEXT-AGENT-PROMPT.md diff --git a/docs/research/2026-08-02-collision-throughput-handoff/NEXT-AGENT-PROMPT.md b/docs/research/2026-08-02-collision-throughput-handoff/NEXT-AGENT-PROMPT.md new file mode 100644 index 00000000..263e3ba9 --- /dev/null +++ b/docs/research/2026-08-02-collision-throughput-handoff/NEXT-AGENT-PROMPT.md @@ -0,0 +1,155 @@ +# Task: diagnose and fix the acdream collision/placement regressions, then COMMIT the fixes + +Work EXCLUSIVELY in `C:\Users\erikn\.codex\worktrees\af5e\acdream`, branch +`codex/port-claude-agents`, HEAD `71604331`. Read `CLAUDE.md` at the repo +root FIRST — its rules bind you (grep-named-retail-first workflow, no +workarounds, divergence-register bookkeeping, connected gates, launch +instructions). The user's in-game observations quoted below are AXIOMS — +they override any green gate number. + +## Standing constraints + +- NEVER `git add -A`, `git add .`, `git reset --hard`, or + `git checkout -- `. Stage exact paths only. +- NEVER stage, revert, or normalize these user-local files: `AGENTS.md`, + `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 root + `implementer-progress.md`, and any `launch-*.log`. +- No workarounds without explicit user approval: root causes only — no + rate knobs, grace periods, suppression flags, or catch-and-swallow. +- Do not push. Commit locally to `codex/port-claude-agents` only. +- Connected gates need the user's ACE server at `127.0.0.1:9000` + (normally up). Follow CLAUDE.md's "Logout-before-reconnect" graceful- + close discipline between client launches. If ACE is unreachable, STOP + and report — never fake or skip a connected gate. + +## Where everything is + +- **This directory** (`docs/research/2026-08-02-collision-throughput-handoff/`): + `design-note.md` (the approved D2 delta-commit design), + `implementer-progress.md` (the complete campaign evidence trail — read + the `## Collision-clone O1/O2/O3` and `## C3c-F4` sections first), + `docs-drafts.md` (register/digest drafts NOT yet applied), + `user-observations-*.md` (the axioms). +- Campaign plan: `docs/plans/2026-08-02-placement-cutover.md`. C3c + closeout: `docs/research/2026-08-02-c3c-cutover-closeout.md`. Issues: + `docs/ISSUES.md` #276–#279. +- Recent commits: `529e0e9d` (C3c production placement cutover — REVIEWED + and accepted), `f4ef2b2a`/`c52ce14a` (docs), `71604331` (the O1–O3 + collision delta-commit — **WIP, ON HOLD, NO review passed it**; its + commit message summarizes state). +- Logs (untracked): `launch-feeltest-oclone.log` (the FAILING user feel + test on the O-tree), `logs/connected-r6-soak-20260802-194423.*` + (current soak: Passed=false, 4 failures), + `logs/connected-r6-soak-20260802-143157.*` (pre-O soak: 37 failures), + `logs/connected-r6-soak-20260727-004942.artifacts` (last fully-PASSING + baseline), `logs/connected-world-gate-20260802-193029` (lifecycle PASS + on the O-tree). + +## Problems to diagnose and fix (priority order) + +**P1 — the retirement-receipt exception loop (smoking gun).** +`launch-feeltest-oclone.log` contains **243** occurrences of +`streaming: origin-recenter preparation will resume: +System.InvalidOperationException: Landblock already has a full +retirement receipt.` — a continuous catch-retry loop during origin +recenter. Find the receipt-lifecycle break introduced (or exposed) by +the O1–O3 diff (`git show 71604331`): the retirement machinery is +`RuntimePhysicsState.AdvanceCollisionRetirementMutation` (~:1880-1990), +`StreamingController.cs` `AdvanceRetirements` call sites (:648/:670/:689/:736), +recenter adoption at `LandblockPresentationPipeline.cs:322-345`. The +catch-and-resume site that swallows this exception may itself violate +the no-silent-catch rule — evaluate it too. + +**P2 — user-visible placement failures on the O-tree (the axioms).** +Quote: "Monsters pop into existence as I run by them. ran to a different +place, spawned in the air long in front of me, stabs are placed +incorrectly. This is not how retail worked. I could see monsters way in +front of me." Suspects, in order: (a) P1's stalled/looping recenter +preparation starving placement; (b) the commit-time reflood diverging +from the deleted staged-clone world in live conditions +(`PhysicsEngine.CommitLandblockReplacement` + +`RefloodPrefixOwnersAfterReplacement`; the oracle test +`CommitTimeRefloodMatchesPrecomputedReflood` covers only 3 landblock +archetypes and may under-cover); (c) siblings of the staged-owner +admission gap the implementer already fixed once (ShadowObjectRegistry +phase 2); (d) ordering between the reflood and admission +commit/RetryDeferred for operations parked on the republished prefix. +Note: under C3c rules entities WAIT for collision before placing — so +"spawned mid-air" means placement completed against wrong/incomplete +collision, not merely late. + +**P3 — the soak's 4 remaining failures.** +`connected-r6-soak-20260802-194423.report.json`: +`pendingLandblockRetirements`=131/122 at sawato-baseline/plateau, +`waitCueShown=true` at holtburg, cpuUs p99 over-limit at the six +non-Caul stops. The WIP's "exposed pre-existing" classification +(reasoning in `implementer-progress.md ## Collision-clone`) was made +BEFORE P1 was discovered — re-judge it against the exception loop. + +**P4 — door/use approach regression (in COMMITTED C3c code, `529e0e9d`).** +Quote: "I dont approach doors when I use them." Using a door no longer +walks the character to it first. Prime suspect: +`src/AcDream.App/Input/PlayerModeController.cs`'s conditional MoveTo +bind (`if (controller.MoveTo is { } moveTo)`) — the legacy path CREATED +the MoveToManager at attach via factory; the flip only binds approach +callbacks IF Runtime's publication chain already ran `MakeMoveToManager` +(`RuntimeLocalPlayerPhysicsPublicationState`). Establish when (or +whether) Runtime creates it relative to player-mode attach; the +interaction flow is `SelectionInteractionController` → +approach-MoveTo → use (see `claude-memory/project_interaction_pipeline.md` +and register row AD-27). + +**P5 — intermittent spell particle loss (#279, C3c-era).** +One-shot VFX/scripts arriving while their entity is in C3c's +suppressed-until-receipt window are dropped instead of deferred; retail +queues scripts for not-yet-in-world objects (grep +`docs/research/named-retail/acclient_2013_pseudo_c.txt` for the +PlayScript/pending-script handling around `HandleCreateObject` +0x00454C80 / `set_hidden` 0x00514C60). Route the deferral through the +presentation-binding moment +(`TryApplyInitialCreateCompletionPresentation` in +`src/AcDream.App/World/LiveEntityRuntime.cs` and the equivalent headless +sink). + +**P6 — verify after P1–P3 land:** purple materialization haze re-firing +while standing still (#278a — believed the same root as the visibility +edges), the monster pop-in re-check, slope-glide vs open #269. + +## Required process per fix + +1. Root cause with file:line evidence BEFORE writing the fix; for any + AC-specific behavior, cite the named-retail decomp. +2. Tests that fail pre-fix and pass post-fix. +3. Any new retail deviation gets its register row + (`docs/architecture/retail-divergence-register.md`) in the SAME + commit; when the collision work lands for real, APPLY the prepared + `docs-drafts.md` entries (AD-6 successor note, AD-62, digest entries, + #280) rather than re-deriving them. +4. Gates before each commit: `dotnet build AcDream.slnx -c Release`; + `dotnet test AcDream.slnx -c Release --no-build --no-restore -m:1` + with `ACDREAM_PAK_PATH=C:\Users\erikn\Documents\Asheron's Call\acdream.pak` + (baseline: 10,812 passed / 0 failed / 4 skipped); + `tools/run-connected-world-lifecycle-gate.ps1` must PASS; then + `tools/run-connected-r6-soak.ps1` — the FINAL acceptance: + `report.json` `Passed=true`, zero failures, `waitCueShown=false` at + all nine stops, per-checkpoint cpuUs p99 within +10% of the + 20260727-004942 baseline. READ `report.json`, never the markers log. + A failure whose only signature is `activeTeleportCount=1` at a stable + checkpoint is user interference — one clean re-run allowed; any other + failure is real: fix it, don't re-run past it. +5. COMMIT each completed fix as its own bisectable commit on + `codex/port-claude-agents` with a message explaining the why. +6. Manual verification launch (for the user): the PowerShell launch in + CLAUDE.md "Running the client against the live server", plus + `ACDREAM_RETAIL_UI=1`. + +## Final deliverable + +Per-problem disposition (root cause → fix → evidence), the commit SHAs, +full gate numbers including the soak report values, and an explicit list +of anything left open.