118 lines
7.7 KiB
Markdown
118 lines
7.7 KiB
Markdown
# 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.
|