acdream/docs/research/2026-08-02-collision-throughput-handoff/docs-drafts.md

Docs-commit drafts — collision publication-throughput fix (O1/O2/O3)

HISTORICAL DRAFT — DO NOT APPLY WHOLESALE (2026-08-03). The O1/O2/O3 implementation landed in 71604331 and the user-visible stabilization fixes continued through 175ad6b0. This draft predates that work, assigns issue number #280 to the collision clone even though #280 now canonically tracks incomplete portal-destination prefetch, and names ledger edits that must be re-audited against the final production tree. It remains only as research evidence. Use NEXT-AGENT-PROMPT.md, the campaign plan, and the live divergence register for current work.

Drafted per contract; NOT applied to the repo. Apply in the docs commit after code review. Register judgment executed as pinned: AD-6 stays retired with a successor note; the residual timing/order compression gets a NEW row (AD-62).

---

1. docs/architecture/retail-divergence-register.md

1a. Append to the retired AD-6 row (line 113), at the end of column 2

Successor note (2026-08-02, collision publication-throughput fix O1/O2/O3): the whole-world staging clone, the owner-mutation journal, the peer-rebase/retirement cursors, and the zero-managed-byte whole-root transfer this row describes were deleted. The shipped mechanism is now the per-landblock delta commit this row's retail anchor always pointed at: admission captures an O(1) empty target-only staging root (PhysicsEngine.CollisionStagingBuilder), the seal enumerates one prefix's installed keys through the CollisionWorldState per-prefix ledgers, and PhysicsEngine.CommitLandblockReplacement drains the sealed delta into the ACTIVE root in one synchronous update-thread call, recalculating every associated owner's cross-cells against the live world (ShadowObjectRegistry.ApplyCommittedOwnerReplacement + RefloodPrefixOwnersAfterReplacement; retail CObjCell::init_objects 0x0052b420 → CPhysicsObj::recalc_cross_cells 0x00515a30). Equivalence is pinned by CommitTimeRefloodMatchesPrecomputedReflood; world-size independence by CollisionPreparationCostIsIndependentOfResidentWorldSize. Residual timing/order compression vs retail: AD-62.

1b. New row AD-62 (residual timing/order compression), adaptation class

| AD-62 | Adaptation. Commit-time collision reflood granularity/order: retail runs CObjCell::init_objects per CELL at cell hydration and CPhysicsObj::recalc_cross_cells per object as each cell loads; acdream runs the equivalent once per LANDBLOCK replacement inside the single synchronous activation call, walking the sealed owner list then the live prefix-owner slots (per-landblock granularity matches the streaming unit, same compression ShadowObjectRegistry.RefloodLandblock has always carried). An owner becoming target-associated mid-publication refloods at activation (the prefix-slot sweep) rather than at its own cell's hydration instant; a stationary owner adjacent to the target whose flood would only change through building/EnvCell bridges can carry frame-stale cross-cells between the seal capture and the activation sweep (movers self-heal per SetPositionInternal). | src/AcDream.Core/Physics/PhysicsEngine.cs (CommitLandblockReplacement); src/AcDream.Core/Physics/ShadowObjectRegistry.cs (ApplyCommittedOwnerReplacement, RefloodPrefixOwnersAfterReplacement) | Late/stale cross-cell rows for a non-moving seam object for a few frames around a landblock publication — an object collidable through a wall seam or briefly not collidable where new topology landed | Low | CObjCell::init_objects 0x0052b420; CPhysicsObj::recalc_cross_cells 0x00515a30; CPhysicsObj::SetPositionInternal tail 0x00515330 |

---

2. claude-memory/project_physics_collision_digest.md — DO-NOT-RETRY additions

• Do not re-introduce a whole-world staging clone for collision generations. The atomic unit is the landblock delta applied in one update-thread call (PhysicsEngine.CommitLandblockReplacement); the runtime is single-threaded and a root swap buys nothing. The clone made ring load O(N²) (the C3c late-monster-pop-in / stuck-portal-space soak failure, issue #280). Deleted 2026-08-02.
• Batching N staging-clone leaves per step is not a fix — measured 1.8× at N=256, not convergence, and it trips the committed one-work-unit seal invariant. The fix was removing the clone, not tuning it.

3. docs/research/2026-07-31-atomic-collision-generation.md — update

Add a banner at the top:

SUPERSEDED IN PART (2026-08-02). Steps 2 (whole-world staging clone), 3 (owner-mutation journal write-through), 5 (journal coalescing/compaction), 6 (peer rebases), 7 (draft retirement cursors), and 8 (whole-root transfer) describe machinery deleted by the collision publication-throughput fix (O1/O2/O3). The atomicity requirement they served — "the multi-frame build must not be observable" — is now met by one synchronous per-landblock delta apply under prefix quiescence with commit-time owner refloods against the live world (retail init_objects → recalc_cross_cells). The admission fairness half (quiescence, prefix mutation permissions, ordered activation) is unchanged and still accurate. Deterministic-evidence entries that name the journal/rebase/retirement tests refer to tests deleted with the machinery; their replacements are CollisionPreparationCostIsIndependentOfResidentWorldSize, CommitAppliesOneLandblockDeltaInASingleCall, and CommitTimeRefloodMatchesPrecomputedReflood.

4. memory/project_collision_port.md

Remove/replace the 37-line block 6b28ff99 added (the starvation-free clone description) with a pointer to the new mechanism (same content as 1a).

5. docs/ISSUES.md — file the regression as its own issue

• #280 — OPEN → fixed pending review: collision staging clone made ring load O(N²) (filed 2026-08-02). The per-publication whole-world staging clone (be94bc9b synchronous, 6b28ff99 metered) plus the seal's full-map scans cost ~2-3× resident world per landblock publication, so an N-landblock ring cost O(N²) and the far ring never converged. F4 measured median 19,736 leaves / 3.64 ms per publication; C3c made it user-visible (late monster pop-in, extended/stuck portal space, portal-exit pop-in, nine-stop soak failure 20260802-143157) but did not cause it. Fix: O1 per-prefix installed-key ledger; O2 per-landblock delta commit (restores be94bc9b's O(changed) apply); O3 empty staging root + commit-time reflood (retail init_objects → recalc_cross_cells) + journal/ rebase/retirement machinery deleted. Reference the O1/O2/O3 commits here when they land.

6. Milestones/roadmap

No phase-table change needed: this is Modern Runtime infrastructure follow-up inside the active campaign context; the C3c smoke-test findings list in ISSUES (#278 additions) should get items (d)/(e)/(f)-class re-observed after the soak gate passes.

7. Commit-message notes for the slice commits

• O1: fix(physics): #280 O1 - per-prefix installed-key ledger; seal scans and landblock removals become O(prefix keys) — behavior-identical; new test CollisionSealWorkIsIndependentOfResidentWorldSize.
• O2: fix(physics): #280 O2 - restore per-landblock delta commit (be94bc9b shape) at PhysicsEngine.CommitLandblockReplacement — notes: staging-slot owner-list widening (direct-staged owners), staging-root revoke, zero-byte commit asserts → O(target payload) bounds (commit-time reflood + dictionary node inserts allocate; world-size independence pinned by the O3 test).
• O3: fix(physics): #280 O3 - empty staging root; commit-time reflood (init_objects → recalc_cross_cells); delete journal/rebase/retirement machinery — 9 mechanism tests deleted, 2 contract tests added.