fix(physics): activate collision generations atomically

docs/architecture/acdream-architecture.md

@@ -485,8 +485,21 @@ What exists and is active:
   collision assets loaded from the validated prepared package. Production
   retains no parsed DAT collision graph; graph construction is restricted to
   bake/equivalence tools and explicit test oracles.
-- `ShadowObjectRegistry` gives movement a broadphase over nearby objects and
-  buildings.
+- Landblock collision activation is generation-owned by
+  `RuntimePhysicsState`. Graphical and no-window hosts populate a private
+  `PreparedLandblockCollisionGeneration` over bounded cursors; its cache,
+  `CellGraph`, engine landblock, buildings, static shadows, and dynamic-owner
+  refloods are never visible through the borrowed live engine. Runtime validates
+  the exact admission plus every affected dynamic shadow-owner version, seals
+  the complete replacement, and commits it synchronously on the one update
+  thread before emitting `CollisionGenerationCommitted`. A moving, spawned, or
+  deleted owner makes the generation not-ready and returns only that dirty owner
+  to the cursor-budgeted refresh phase. Thus readers see the complete old
+  generation or complete new generation, never a mixed cell/cache/shadow world.
+- `ShadowObjectRegistry` gives movement a per-cell broadphase over nearby
+  objects and buildings. Streaming reflood is structurally part of the Runtime
+  collision-generation commit; there is no independent post-publication
+  reflood suffix.
 - `TerrainSurface` uses triangle-aware terrain contact; older "bilinear terrain
   Z" descriptions are historical B.3 language, not current architecture.
 

docs/architecture/retail-divergence-register.md

@@ -89,7 +89,7 @@ AD-53..AD-55 (Campaign P response-layer findings).
 | AD-1 | Lost-cell machinery replaced by recoverable outdoor demote (**#107** safety net) + outdoor-restore `max(terrainZ, z)` under-terrain lift; retail goes `GotoLostCell` | `src/AcDream.Core/Physics/PhysicsEngine.cs:553` (+ :808) | acdream has no lost-cell state machine; outdoor landcell is the recoverable equivalent; the #107 auto-entry hold should make the demote branch unreachable | Gap in the hold → player committed to outdoor terrain inside/under a building (fake-grounded spawn, fall-through); a legit below-heightmap server restore is silently lifted — upward warp vs server | `GotoLostCell` pc:283418; `SetPositionInternal` 0x00515bd0, pc:283892-283945 |
 | AD-2 | Async readiness gates replace retail's synchronous destination cell load. **#229 refinement (2026-07-20):** login and F751 portal-space exit now share `WorldRevealReadinessBarrier`, so neither path can expose the normal viewport until the same render-publication, composite-texture, and collision domains converge. A hydratable indoor claim requires its owning Near-tier static/EnvCell mesh set, destination composites, and exact EnvCell physics (`IsSpawnCellReady`); an outdoor claim requires those render domains plus terrain/collision residency for the required Near ring. Hard-recenter generations and tier-aware completion application prevent stale overlapping loads/unloads or Far/Near jobs from opening or erasing the gate; mesh upload remains separate from balanced landblock ownership. Claims beyond NumCells still take the loud unhydratable-placement path. `RuntimeWorldTransitState` owns the shared reveal generation, accepted readiness, transit correlation, and exact generation/cell-scoped host-acknowledgement suffix. `WorldRevealCoordinator` is a graphical adapter holding only App resource receipts; normalized Runtime checkpoints observe ownership without defining another readiness path. **Slice E3 refinement (2026-07-24):** the same generation now publishes an immediate `WorldGenerationQuiescence` edge: old-world drawing/spatial queries, simulation/effect clocks, reconciliation, targeting, and 3-D audio stop while retained physical teardown advances through metered cursors and destination network/UI/streaming/readiness remain live. **Slice E4 refinement (2026-07-24):** accepted render/physics/static publication may span update frames through retained exact cursors, but reveal still consumes only the completed spatial/render-ready generation; building and EnvCell snapshots remain invisible until complete and the final spatial identity swap stays observer-atomic. **Slice E5 refinement (2026-07-24):** the reveal generation owns one exact destination reservation across every typed budget dimension. Stale completion cannot consume or clear its replacement, and hydratable incomplete content is never force-revealed; portal transit retains the DAT tunnel and centered retail wait cue until readiness converges. The hold→materialize→regain-control lifecycle remains owned by `TeleportAnimSequencer`. | `src/AcDream.Runtime/World/RuntimeWorldTransitState.cs`; `src/AcDream.App/Streaming/WorldRevealCoordinator.cs`; `src/AcDream.App/Streaming/WorldGenerationQuiescence.cs`; `src/AcDream.App/Streaming/WorldRevealReadinessBarrier.cs`; `src/AcDream.App/Streaming/StreamingOriginRecenterCoordinator.cs`; `src/AcDream.App/Streaming/LandblockPresentationPipeline.cs`; `src/AcDream.App/Streaming/StreamingController.cs`; `src/AcDream.App/Rendering/PortalTunnelPresentation.cs`; `src/AcDream.App/UI/PortalWaitNoticeController.cs`; `src/AcDream.App/Streaming/GpuWorldState.cs` (`IsRenderReady`); `src/AcDream.App/Rendering/Wb/LandblockSpawnAdapter.cs`; `src/AcDream.Core/Physics/PhysicsEngine.cs` (`IsSpawnCellReady`, `IsNeighborhoodTerrainResident`) | This is the asynchronous equivalent of retail leaving `SmartBox::position_update_complete` false while `CellManager::blocking_for_cells` is set: neither initial login nor portal arrival may reveal or continue simulating an old/partial collision world, a terrain-only Far shell, or a published-but-not-drawable GPU landblock. Indoor does not require a terrain heightmap, only the owning render landblock and exact EnvCell. | Gate opens early → grey/untextured first login or portal reveal, free-fall, wrong-cell rooting, missing scenery, or a still-active old generation; predicate never satisfies (streamer/DAT/upload failure) → login remains behind the world render gate, while portal transit remains in the authored tunnel and presents the centered wait cue after five seconds. | `SmartBox::UseTime` 0x00455410; `gmSmartBoxUI::UseTime` 0x004D6E30; `gmSmartBoxUI::EndTeleportAnimation` 0x004D65A0 |
 | AD-5 | Outdoor `point_in_cell` is an identity compare against the global XY-column cell from `LandDefs.AdjustToOutside` (no per-cell containment test) | `src/AcDream.Core/Physics/CellTransit.cs:865` | Landcells are disjoint 24 m columns — identity-compare against the column under the sphere centre is exactly equivalent to retail's per-candidate test | If block-origin/lcoord math is wrong at a landblock seam, the compare silently never matches — outdoor membership freezes at boundaries (the pre-#106 symptom) | `find_cell_list` pick pc:308788-308825; `CLandCell::point_in_cell` (get_block_offset pc:308804) |
-| AD-6 | Per-LANDBLOCK shadow re-flood on hydration vs retail per-CELL `recalc_cross_cells` | `src/AcDream.Core/Physics/ShadowObjectRegistry.cs:339` | The streaming unit IS the landblock; one hook per hydration event covers both race directions (entity-before-cells, cells-after-spawn) | Any cell-hydration path that doesn't raise the landblock hook leaves an entity's shadow set stale — walk-through / missing collisions in just-streamed cells | `CObjCell::init_objects` → `recalc_cross_cells`, 0x0052b420 / 0x00515a30 |
+| ~~AD-6~~ | **RETIRED 2026-07-31 (placement/streaming Slice 3B).** Cell/cache/topology/building/static-shadow publication plus retained dynamic-owner `recalc_cross_cells` is one Runtime-owned collision generation. App and Headless build only an off-side `PreparedLandblockCollisionGeneration`; the complete previous generation remains queryable until the one update-thread commit. Every affected dynamic owner carries an exact mutation version. Movement, spawn, or deletion during staging rejects activation and returns only dirty owners to a bounded refresh cursor; a stale admission/recenter/cancellation can dispose only its private generation. The commit installs the precomputed cell rows before its single notification/readiness acknowledgement, so no optional hydration callback can omit reflood and no observer sees mixed old/new cells. | `src/AcDream.Runtime/Physics/RuntimePhysicsState.cs` (`PrepareCollisionGeneration`, `CommitCollisionGeneration`); `src/AcDream.Core/Physics/PhysicsDataCache.cs`; `PhysicsEngine.cs`; `ShadowObjectRegistry.cs`; `src/AcDream.App/Streaming/LandblockPhysicsPublisher.cs`; `src/AcDream.Headless/Hosting/HeadlessSessionWorldProjection.cs`; `tests/AcDream.Runtime.Tests/Physics/RuntimePhysicsStateTests.cs`; `tests/AcDream.App.Tests/Streaming/LandblockPhysicsPublisherTests.cs` | — | — | `CObjCell::init_objects` → `CPhysicsObj::recalc_cross_cells`, 0x0052b420 / 0x00515a30; `CPhysicsObj::SetPositionInternal` shadow replacement tail 0x00515330 |
 | AD-10 | Remote slope projection relocated to the queue-empty/head-reached combiner boundary; retail projects inside `CTransition::adjust_offset` during the sweep | `src/AcDream.Core/Physics/PositionManager.cs:47` | Remote bodies don't run a full local transition sweep; boundary projection removes the ~5 Hz Z staircase on slopes, no-op on flat ground | The single-point terrain-normal sample can differ from the sweep's contact plane (cell boundaries, props underfoot) — remote Z drift / stair-stepping | `CTransition::adjust_offset` pc:272296-272346 |
 | ~~AD-11~~ | **RETIRED 2026-07-23** — the matching binary disproved the old nonzero interpretation: `ItemUses::IsUseable` executes `not bitfield; and eax,1`, so absent/reset zero is usable and only `USEABLE_NO` disables use. Toolbar, item policy, and world interaction now share that exact Core predicate. | `src/AcDream.Core/Items/ClientObject.cs` (`ItemUseability.IsUseable`); `src/AcDream.Core/Items/ItemInteractionPolicy.cs`; `src/AcDream.App/Interaction/WorldSelectionQuery.cs` | — | — | `ItemUses::IsUseable @ 0x004FCCC0`; matching v11.4186 instructions recorded in `docs/research/2026-07-23-retail-item-use-and-autowear-pseudocode.md` |
 | AD-12 | SecondaryAttributeTable coefficients hardcoded (Health=End×0.5, Stam=End×1.0, Mana=Self×1.0) instead of dat-read; unknown attributes contribute 0 | `src/AcDream.Core/Player/LocalPlayerState.cs:279` | Coefficients never vary across retail dat versions; re-confirmed by ACE AttributeFormula.cs + holtburger; dat port can replace later | A customized portal.dat with modified vital formulas silently yields wrong max-vitals; a missing attribute snapshot underestimates max | SecondaryAttributeTable portal.dat 0x0E0..0x0E2; `CreatureVital::GetMaxValue` 0x0058F2DD |

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

@@ -0,0 +1,72 @@
+# Atomic collision-generation activation (Slice 3B)
+
+## Retail anchor
+
+Retail hydrates a cell synchronously. `CObjCell::init_objects`
+(`0x0052B420`) visits objects associated with that cell and invokes
+`CPhysicsObj::recalc_cross_cells` (`0x00515A30`). The final position path also
+replaces shadows as one `SetPositionInternal` operation (`0x00515330`). Retail
+therefore never exposes a world where the new cell exists but the objects that
+overlap it still have their old cross-cell set.
+
+Acdream streams a landblock over several update frames. Literal per-cell
+mutation during those frames was not equivalent: the active `PhysicsDataCache`,
+`CellGraph`, `PhysicsEngine`, buildings, static shadows, and retained-object
+refloods changed at different cursors. Collision queries could observe a mixed
+generation, and correctness depended on a later optional landblock callback.
+
+## Ported adaptation
+
+The asynchronous unit is now one Runtime-owned collision generation:
+
+1. `BeginCollisionAdmission` issues the exact Runtime/landblock generation.
+2. `PrepareCollisionGeneration` clones the bounded resident spatial records
+   into a private cache, graph, engine, and shadow registry. Global immutable
+   GfxObj/Setup catalogs are not copied; the accepted build's exact closure is
+   populated by the existing cursors.
+3. App and Headless publish terrain, EnvCells, topology, buildings, prepared
+   collision assets, static owners, and retained dynamic-owner cell sets only
+   into that private generation.
+4. Each dynamic owner refresh captures its exact `ShadowObjectRegistry`
+   mutation version. Movement, state/payload change, spawn, suspension, or
+   deletion changes that version.
+5. `CommitCollisionGeneration` validates the admission, exact affected-owner
+   set, and all captured versions. If any owner is dirty, it returns the sorted
+   dirty IDs without touching the active world; App advances those IDs through
+   its existing work meter and retries.
+6. Once fresh, Runtime precomputes the replacement arrays and synchronously
+   replaces the landblock's cache/graph/engine/building/static and dynamic
+   shadow state on the same update thread. Only after the complete replacement
+   does it emit `CollisionGenerationCommitted` and a ready acknowledgement.
+
+The stable borrowed `PhysicsEngine` and `PhysicsDataCache` object identities do
+not change. Presentation and no-window hosts use the same Runtime transaction.
+Network workers still enqueue immutable messages and cannot mutate collision or
+shadow state.
+
+## Failure and lifetime rules
+
+- A newer admission invalidates an older prepared generation.
+- Demotion, withdrawal, reset, and disposal invalidate the admission before
+  changing the active generation.
+- Disposing a stale/cancelled prepared generation clears only its private
+  engine/cache/shadows.
+- The prior complete generation remains queryable throughout preparation.
+- The commit notification is the future lost-cell-registry seam. Slice 3B does
+  not implement `GotoLostCell` or change `SetPosition` recovery behavior.
+
+## Deterministic evidence
+
+The focused Runtime/App tests pin:
+
+- previous terrain/cells/buildings/statics remain visible until commit;
+- exactly one notification after a successful complete activation;
+- stale admission replacement has no active-world side effect;
+- movement during staging rejects, refreshes only the dirty owner, and then
+  installs its latest cell set;
+- spawn and deletion during staging both reject stale activation;
+- graphical and no-window publishers use the same Runtime transaction;
+- removal and terminal teardown converge the active ownership ledger.
+
+This retires divergence row AD-6. The remaining lost-cell state-machine work is
+deliberately outside this slice.