feat(physics): port canonical retail set-position core

docs/architecture/retail-divergence-register.md

@@ -74,6 +74,12 @@ by the DAT-authored portal-space viewport. Recent additions and splits:
 AD-47/AD-48 (Vulkan sample/present behavior), AD-50..AD-52 (Campaign N), and
 AD-53..AD-55 (Campaign P response-layer findings).
 
+AD-2 clarification (placement Slice 4A, 2026-07-31): Core never creates cells
+during placement, so retail `DoNotCreateCells` has no differential synchronous
+loader branch there. Slice 4B must preserve the flag while mapping successful
+deferred placement to exact-cell, generation-scoped asynchronous admission;
+the presence of the flag in the immutable request is not claimed as exactness.
+
 | # | Divergence | Where (file:line) | Why it is safe / justified | Risk if assumption breaks | Retail oracle |
 |---|---|---|---|---|---|
 | ~~AD-53~~ | **RETIRED 2026-07-31 (Campaign P Slice 1B).** `Transition.CliffSlide` now consumes only `collision_info.last_known_contact_plane.N`, exactly as retail does. The invented `LastWalkablePlane -> LastKnownContactPlane -> UnitZ` fallback chain is gone; invalid/default or parallel data takes retail's degenerate `OK_TS` return. | `src/AcDream.Core/Physics/TransitionTypes.cs` (`CliffSlide`); `tests/AcDream.Core.Tests/Physics/RetailEdgeResponseOrderingTests.cs` | — | — | `CTransition::cliff_slide` pc:272397 (0050a6d0); `last_known_contact_plane` maintenance pc:272659-272668 (~0050ad07) |
@@ -126,7 +132,7 @@ AD-53..AD-55 (Campaign P response-layer findings).
 
 ---
 
-## 3. Documented approximation (AP) — 87 active rows (AP-5 retired 2026-07-31 at Campaign P Slice 2A — every successful `step_down` now performs retail's final `PLACEMENT_INSERT`; AP-3/AP-4 retired 2026-07-31 at Campaign P Slice 1B — `transitional_insert` and `edge_slide` now preserve retail's valid-contact early return and Branch-1-first order; AP-127 retired 2026-07-31 by #268 — the complete augmentation chain is shared by character UI and Runtime movement; AP-30 retired 2026-07-30 by the movement parity audit — retail Frame::is_equal genuinely uses the 0.0002 epsilon [byte-confirmed], so the row recorded a NON-divergence; acdream already matches; AP-129 narrowed 2026-07-30 at the P4 Opus review fix — `CanMoveInto`/`RestrictionDB::IsAllowedIn` are now ported and fed end-to-end (CreateObject HouseOwner/HouseRestrictions/Monarch tail fields + live `House_UpdateRestrictions 0x0248`, resolved through `PhysicsEngine.Objects`), retiring the original "CanMoveInto entirely unmodeled, unconditional fail-closed" gap the row described — the review was triggered by `RestrictionObjPrevalenceInspectionTests` showing 103,766 of 729,888 installed EnvCells (the whole housing estate) carry a baked `RestrictionObj`, so the unconditional fail-closed default would have locked every house for every player including its own owner; AP-10 retired 2026-07-30 at Campaign P Slice P4 — restored retail's 0.1 m dry-corner water sink-in, full suite green proving the sticky-bit no-regression argument; AP-71 retired same slice — `check_entry_restrictions` ported at the head of the indoor `FindEnvCollisions` branch, `CellPhysics.RestrictionObj` wired from the DAT-baked `EnvCell` field in both the dev and production caching paths; AP-128 filed 2026-07-30 at the P3 Opus review — PK-timer clock basis; AP-25 retired 2026-07-30 at Campaign P Slice P1 — the vitae/enchantment-aware run/jump skill chain; AP-7 retired 2026-07-30 at Campaign P Slice P2 — `calc_friction`'s threshold ported to retail's confirmed 0.25f; its still-open cos(10°)-vs-0.99999536f Sledding constant question moved to AD-55)
+## 3. Documented approximation (AP) — 87 active rows (AP-1 narrowed 2026-07-31 by placement/streaming Slice 4A — the pure canonical retail `SetPosition` transaction exists, but production routes and lost-cell lifetime remain on the legacy resolver until Slice 4B; AP-5 retired 2026-07-31 at Campaign P Slice 2A — every successful `step_down` now performs retail's final `PLACEMENT_INSERT`; AP-3/AP-4 retired 2026-07-31 at Campaign P Slice 1B — `transitional_insert` and `edge_slide` now preserve retail's valid-contact early return and Branch-1-first order; AP-127 retired 2026-07-31 by #268 — the complete augmentation chain is shared by character UI and Runtime movement; AP-30 retired 2026-07-30 by the movement parity audit — retail Frame::is_equal genuinely uses the 0.0002 epsilon [byte-confirmed], so the row recorded a NON-divergence; acdream already matches; AP-129 narrowed 2026-07-30 at the P4 Opus review fix — `CanMoveInto`/`RestrictionDB::IsAllowedIn` are now ported and fed end-to-end (CreateObject HouseOwner/HouseRestrictions/Monarch tail fields + live `House_UpdateRestrictions 0x0248`, resolved through `PhysicsEngine.Objects`), retiring the original "CanMoveInto entirely unmodeled, unconditional fail-closed" gap the row described — the review was triggered by `RestrictionObjPrevalenceInspectionTests` showing 103,766 of 729,888 installed EnvCells (the whole housing estate) carry a baked `RestrictionObj`, so the unconditional fail-closed default would have locked every house for every player including its own owner; AP-10 retired 2026-07-30 at Campaign P Slice P4 — restored retail's 0.1 m dry-corner water sink-in, full suite green proving the sticky-bit no-regression argument; AP-71 retired same slice — `check_entry_restrictions` ported at the head of the indoor `FindEnvCollisions` branch, `CellPhysics.RestrictionObj` wired from the DAT-baked `EnvCell` field in both the dev and production caching paths; AP-128 filed 2026-07-30 at the P3 Opus review — PK-timer clock basis; AP-25 retired 2026-07-30 at Campaign P Slice P1 — the vitae/enchantment-aware run/jump skill chain; AP-7 retired 2026-07-30 at Campaign P Slice P2 — `calc_friction`'s threshold ported to retail's confirmed 0.25f; its still-open cos(10°)-vs-0.99999536f Sledding constant question moved to AD-55)
 
 Wave-0 UI ledger repair (2026-07-10) retired stale AP-38, resolved the AP-84
 collision, restored overwritten paperdoll rows as AP-92/AP-93, and registered
@@ -134,7 +140,7 @@ AP-94..AP-112 for the confirmed retail-UI completion gaps.
 
 | # | Divergence | Where (file:line) | Why it is safe / justified | Risk if assumption breaks | Retail oracle |
 |---|---|---|---|---|---|
-| AP-1 | Snap-path Z settle: validated claims ground on their own walkable polys, but floor-less claims (thresholds, stair lips) fall through to a legacy nearest-in-Z scan over every CellSurface in the landblock; retail settles via `CheckPositionInternal` → `find_valid_position` | `src/AcDream.Core/Physics/PhysicsEngine.cs:614` | `find_valid_position` unported; the **#111** fix narrowed the legacy pick's blast radius (validated claims bypass it) rather than replacing it | A threshold/stair-lip snap can still pick a neighbouring cell's same-height floor by iteration order — wrong cell or Z at login/teleport arrival (the #111 clobber class) | `SetPositionInternal` :283426 → find_valid_position |
+| AP-1 | **NARROWED 2026-07-31 (placement/streaming Slice 4A).** Core now exposes the pure retail `SetPosition` → `AdjustPosition` → `CheckPositionInternal` → `find_valid_position` transaction, including exact sphere initialization, two distinct placement validators, step-down schedule, force classes, flags/scatter, signed no-slide predicate, error values, and an explicit deferred-residence result. Production zero-delta routes deliberately still use the legacy nearest-in-Z/terrain-lift resolver because its `ResolveResult` cannot represent a successful lost-cell transition. Slice 4B must cut every authoritative route to the canonical packet and install the Runtime lost-cell owner before this row retires. | `src/AcDream.Core/Physics/PhysicsSetPosition.cs`; `src/AcDream.Core/Physics/PhysicsEngine.cs`; `src/AcDream.Core/Physics/TransitionTypes.cs`; `tests/AcDream.Core.Tests/Physics/PhysicsSetPositionTests.cs`; `docs/research/2026-07-31-canonical-set-position.md` | Split preserves production behavior while the immutable placement mechanism and its oracle gates land independently | Until 4B, fresh spawn, same-generation refresh, authoritative Position, portal arrival, external teleport, parent detach, pickup release, and world-drop hydration can still run the old approximation and cannot park/wake an exact lost-cell frame | `CPhysicsObj::SetPosition` 0x005160C0; `SetPositionInternal` 0x00515BD0; `AdjustPosition` 0x00511D80; `CheckPositionInternal` 0x00511E90; `CTransition::find_valid_position` 0x0050C310; `find_placement_position` 0x0050C170; `validate_placement_transition` 0x0050ADC0; `validate_placement` 0x0050B210 |
 
 | ~~AP-3~~ | **RETIRED 2026-07-31 (Campaign P Slice 1B).** `TransitionalInsert` now returns `OK_TS` immediately for every valid contact plane. Its ordinary StepDown tail is reachable only from invalid contact and retains the retail Contact / `!sphere_path.step_down` / check-cell / ObjectInfo.StepDown gates plus the exact one-versus-two-sphere probe split. | `src/AcDream.Core/Physics/TransitionTypes.cs` (`TransitionalInsert`, `GetStepDownProbePlan`); `tests/AcDream.Core.Tests/Physics/RetailEdgeResponseOrderingTests.cs` | — | — | `CTransition::transitional_insert` 0x0050B6F0, named-retail pseudo-C pc:273191–273307 |
 | ~~AP-4~~ | **RETIRED 2026-07-31 (Campaign P Slice 1B).** `EdgeSlideAfterStepDownFailed` now evaluates retail Branch 1 (`!OnWalkable || !EdgeSlide` → restore + `OK_TS`) before the steep-contact `CliffSlide` branch. The former compensation is removed. | `src/AcDream.Core/Physics/TransitionTypes.cs` (`EdgeSlideAfterStepDownFailed`); `tests/AcDream.Core.Tests/Physics/RetailEdgeResponseOrderingTests.cs` | — | — | `CTransition::edge_slide` 0x0050B3D0, named-retail pseudo-C pc:273001–273090 |

docs/research/2026-07-31-canonical-set-position.md

@@ -0,0 +1,142 @@
+# Canonical retail `SetPosition` — placement/streaming Slice 4A
+
+## Scope
+
+This note pins the pure physics half of the placement/streaming closeout.
+Slice 4A lands the retail placement transaction as a separately testable Core
+mechanism. It deliberately does **not** replace the production snap-only
+resolver yet: Runtime lost-cell ownership and the complete inbound-route
+cutover remain Slice 4B. AP-1 and AD-1 therefore remain active until that
+cutover is complete.
+
+Named-retail oracle, Sept 2013 EoR:
+
+- `CPhysicsObj::SetPosition` `0x005160C0`
+- `CPhysicsObj::SetPositionInternal` `0x00515BD0`
+- `CPhysicsObj::AdjustPosition` `0x00511D80`
+- `CPhysicsObj::CheckPositionInternal` `0x00511E90`
+- `CTransition::find_valid_position` `0x0050C310`
+- `CTransition::find_placement_position` `0x0050C170`
+- `CTransition::find_placement_pos` `0x0050BA50`
+- `CTransition::validate_placement_transition` `0x0050ADC0`
+- `CTransition::validate_placement` `0x0050B210`
+- `CPhysicsObj::ForceIntoCell` `0x00515660`
+- `CPhysicsObj::handle_all_collisions` `0x00514780`
+
+## Retail transaction
+
+```text
+SetPosition(request):
+    transition = makeTransition()              // GENERAL_FAILURE if none
+    init_object(transition, object)
+
+    if the PartArray has no spheres:
+        init_sphere(1, dummy center=(0,0,0.1), radius=0.1, scale=1)
+    else:
+        init_sphere(first min(count,2) authored spheres, exact object scale)
+
+    if flags & RANDOM_SCATTER (0x200):
+        return scatter only
+
+    result = SetPositionInternal(request)
+    if result != OK and flags & SCATTER (0x100):
+        return scatter
+    return result
+
+SetPositionInternal(request):
+    AdjustPosition(request frame, first sphere, noCreate=(flags & 0x20))
+    if no resident cell:
+        store the adjusted authoritative frame and enter lost-cell lifetime
+        return OK
+
+    if the live weenie is Hook, Storage, or Corpse:
+        return ForceIntoCell(resident cell, frame)
+
+    set do_not_load_cells from flag 0x20
+    if !CheckPositionInternal(...):
+        handled = handle_all_collisions(...)
+        return handled ? COLLIDED : NO_VALID_POSITION
+    if transition.curr_cell == null:
+        return NO_CELL
+    commit the complete transition
+    return OK
+```
+
+`AdjustPosition` branches on the claimed cell shape. A direct outdoor claim
+runs pure `LandDefs::adjust_to_outside` normalization before visible-cell
+lookup. An indoor claim first resolves the visible cell and child; only a
+resident indoor cell marked `seen_outside` falls back to outdoor
+normalization. An absent indoor cell (including the `0xFFFF` sentinel) remains
+the exact claimed cell/frame. A map-edge outdoor normalization failure stores
+cell zero with the otherwise unchanged frame. The old `max(terrainZ, z)` lift
+and nearest-in-Z scan do not occur in this canonical mechanism.
+
+`CheckPositionInternal` calls the complete placement transition. Without the
+slide flag, retail accepts the result only when signed
+`resolvedX-requestedX <= 0.0500000007`, the same signed Y condition holds, and
+the cell is unchanged. Z is not part of that predicate. The resolved origin is
+accepted while the requested orientation remains intact.
+
+## Two validators, not one
+
+The similarly named retail helpers have different contracts and stay separate
+in the port:
+
+- `validate_placement_transition` is the inner `find_placement_pos` validator.
+  Any non-OK state from `COLLIDED` through `SLID`, when sliding is permitted,
+  resets `COLLISIONINFO`; it never retries placement.
+- `validate_placement` is the outer initial/final validator. Only `ADJUSTED`
+  or `SLID`, and only while its retry argument is true, performs one
+  `placement_insert`; `COLLIDED` neither resets nor retries.
+
+Step-down is disabled only for missiles. For fewer than two spheres retail
+first clamps the requested height to half the radius when the sphere diameter
+is less than or equal to that height. It then performs one full probe when the
+diameter is greater than the resulting height, otherwise two half probes.
+Equality belongs to the two-half-probe branch.
+
+## Modern seam
+
+`PhysicsEngine.SetPosition` returns one immutable
+`PhysicsSetPositionResult`. `SetPositionError` retains the header values
+(`OK=0`, `GENERAL=1`, `NO_VALID=2`, `NO_CELL=3`, `COLLIDED=4`,
+`INVALID_ARGS=0x100`) while `PhysicsResidenceDisposition` separately reports
+`Committed`, `DeferredCell`, or `Unchanged`. Missing content is therefore
+successful-but-deferred, never misreported as a placement failure.
+
+The result carries the complete commit packet: root/cell-local frame,
+contact/walkable/water state, sliding and collision normals, stationary-fall
+counter, a complete immutable `COLLISIONINFO` snapshot for the real
+`handle_all_collisions` callback (including contact/last-contact, sliding,
+collision normal, stationary-fall, environment, adjustment, and object
+fields), the callback result, and an explicit shadow action. A PhysicsBSP or changed-cell force commit
+requests canonical shadow recalculation; a non-BSP transition replaces its
+shadows only when the transition produced a nonempty cell array, otherwise it
+preserves the prior list. Unchanged force placement changes only the frame.
+
+Core never creates cells synchronously, so retail flag `0x20`
+(`DoNotCreateCells`) has no differential loader branch inside this pure
+mechanism. Both flag states can only observe already-published immutable cell
+content and otherwise return `DeferredCell`. Carrying the flag into exact-cell,
+generation-scoped async admission is part of the still-open Slice 4B
+adaptation tracked with AD-2; this slice does not claim a dead SpherePath field
+as exact behavior.
+
+The existing public `Resolve` compatibility entry remains entirely unchanged
+for production movement and zero-delta callers. Its result cannot represent a
+successful-but-deferred residence, so hiding `DeferredCell` inside
+`ResolveResult.Ok` would corrupt the contract. Slice 4B will route every
+authoritative placement family through `SetPosition`, atomically install its
+packet, and own exact lost-cell wakeup/commit.
+
+## Automated oracle
+
+`PhysicsSetPositionTests` pins error values, absent/invalid outdoor and indoor
+claims, cross-landblock frame normalization, map-edge failure and the `0xFFFF`
+sentinel, dummy/authored sphere setup, nonpositive scale, Ethereal seeding,
+explicit-only PathClipped, missile step-down, exact equality schedules, both validators,
+the late compass sample's float bits, signed no-slide behavior, actual
+collision-handler mapping, force-class policy, explicit shadow actions, null
+current-cell wakeup, ten-record scratch exhaustion, exact scatter ordering,
+failed-probe scratch lifetime, and deferred-scatter stop. The legacy public
+Resolve fixture remains unchanged until Slice 4B.