acdream/docs/plans/2026-07-25-modern-runtime-slice-i.md

# Modern runtime Slice I — flat collision assets and zero-allocation physics

**Status:** I0–I3 COMPLETE — retail oracle, zero-allocation transition
scratch, deterministic immutable collision records, and complete prepared
package fixed; I4 active
**Parent:** `2026-07-24-modern-runtime-architecture.md`, Slice I
**Purpose:** remove parsed DAT object graphs and steady collision allocations
without changing one retail collision decision, float, comparison, or traversal
order.

## 1. Non-negotiable boundaries

1. Retail collision math is frozen. This slice changes storage and scratch
   ownership only.
2. Every float read from DAT is copied bit-for-bit. The bake performs no
   normalization, quantization, coordinate conversion, `double` round-trip, or
   plane reconstruction.
3. Positive/negative child order, polygon order within every leaf, early
   returns, epsilon comparisons, and contact-selection tie behavior remain
   exact.
4. The current object-graph traversal remains an executable oracle until the
   flat traversal passes mass differential and connected gates.
5. Physics `Transition` reuse lands only after reset-completeness,
   cross-mover-identity, failure, and reentrancy tests prove that no state can
   leak between resolves.
6. No GL/App dependency enters Core. Flat collision records live in
   `AcDream.Core`; serialization and package access live in `AcDream.Content`;
   the bake tool produces them offline.
7. The active G4 render cutover is independent. Its exact visual rollback
   remains:

   ```text
   git revert ef1d263337997bb030eadb7b8e71d73dc659907a
   ```

## 2. Target data architecture

The runtime collision representation is immutable, array-backed, and addressed
by integer index:

```text
FlatCollisionAsset
├── FlatPhysicsBsp
│   ├── FlatBspNode[]          child indices; -1 = no child
│   ├── int[]                  leaf polygon-index stream
│   ├── FlatPolygon[]          plane, cull mode, id, vertex range
│   └── Vector3[]              verbatim polygon vertices
├── FlatCellContainmentBsp     split planes + positive/negative indices
├── FlatSetupCollision         cyl/sphere records + verbatim dimensions
└── EnvCellTopology            portals, visible cells, seen-outside
```

Node order is deterministic pre-order. The flattener records the original
positive child before the negative child and retains each source leaf's
polygon list order. Traversal follows indices using the same recursive
control flow as the current retail port; “flat” does not mean a new collision
algorithm.

Per-EnvCell world transform remains publication state, not baked geometry.
CellStruct collision geometry can therefore alias by exact source identity;
cell-specific portals, visibility, `seen_outside`, and placement remain a
separate small payload/publication record.

## 3. Execution slices

### I0 — oracle inventory and fixed evidence

1. Grep named retail before touching traversal:
   - `BSPTREE::find_collisions`
   - `BSPNODE::find_walkable`
   - `BSPLEAF::find_walkable`
   - `BSPNODE::sphere_intersects_*`
   - `BSPNODE::point_inside_cell_bsp`
   - `CTransition::find_transitional_position`
   - `CTransition::init_path`
   - `CPhysicsObj::transition`
2. Cross-reference ACE and the existing acdream pseudocode/trajectory notes.
3. Write one collision-layout pseudocode note that separates:
   source storage, traversal order, mutable query scratch, and returned
   side-effects.
4. Inventory every production call into `BSPQuery`, every field read from
   `PhysicsBSPNode`, `CellBSPNode`, `ResolvedPolygon`, `CellPhysics`,
   `GfxObjPhysics`, and `SetupPhysics`, and every raw DAT graph retained by
   `LandblockBuild`/`PhysicsDatBundle`.
5. Capture representative installed-DAT fixtures:
   - outdoor/no-BSP;
   - Facility Hub and cottage indoor cells;
   - staircase/ramp and cellar-lip cases;
   - a multipart door/building shell;
   - projectile/thin-wall geometry;
   - cells with asymmetric/null BSP children;
   - leaves with multiple polygons and equal-distance candidates.
6. Record allocation baselines for player, remote, projectile, and camera
   resolve loops.

Gate: source inventory is complete, fixtures reproduce through the current
graph path, and no behavior code changed.

### I1 — reusable transition and query scratch

1. Add explicit `ResetForReuse` methods to `ObjectInfo`, `CollisionInfo`,
   `SpherePath`, and `Transition`.
2. Reset every scalar, nullable, property backing field, diagnostic counter,
   collision GUID list, sphere element, walkable reference, backup value, and
   transient flag. Retain only storage identity whose contents are completely
   reset.
3. Give each `PhysicsEngine` one owned transition lease. The normal
   update-thread path rents, initializes, resolves, snapshots the value-only
   result, and returns in `finally`.
4. Make reentrancy explicit and tested. Never hand one mutable transition to
   two concurrent/nested resolves and never silently share session scratch.
5. Reuse walkable vertex arrays only when their exact logical length matches;
   allocate only on a true size change. No larger-capacity array may leak stale
   vertices into polygon math.
6. Convert short-lived `BSPQuery.CollisionSphere` reference objects to
   value/ref scratch while preserving each mutation/copy boundary.
7. Add structural reflection tests that poison every resettable member, reset,
   and compare its complete value graph with a fresh instance while asserting
   retained buffer identities.
8. Differential-run fresh-transition and reused-transition engines across
   success, collision, failure, placement, grounded, airborne, sliding,
   step-up/down, two-sphere, projectile, and camera cases.

Gate: bit-identical `ResolveResult` and body side effects, no state leakage
when alternating hostile fixtures between different mover IDs, and zero
steady transition/query-scratch allocation. **PASSED 2026-07-25:** the expanded
118-test graph oracle, structural poison/reset suite, hostile fresh-vs-reused
differential, Core/solution Release gates, and all five measured profiles pass.
Issue #237 is closed. Evidence:
[`../research/2026-07-25-slice-i1-transition-scratch.md`](../research/2026-07-25-slice-i1-transition-scratch.md).

### I2 — immutable flat collision schema and flattener

1. Add Core-only flat record types with explicit index/range contracts.
2. Flatten physics and containment BSPs iteratively during preparation while
   emitting deterministic pre-order node arrays.
3. Copy planes, spheres, vertices, setup dimensions, and collision metadata
   verbatim. Tests compare every float via `SingleToInt32Bits`.
4. Resolve each leaf polygon ID to a direct polygon index at preparation time.
   Missing IDs are corruption, not a runtime fallback.
5. Validate:
   - child indices/ranges;
   - acyclic/reachable tree shape;
   - polygon and vertex ranges;
   - source-vs-flat node, child, polygon, and float identity;
   - deterministic output independent of dictionary enumeration.
6. Keep source graph and flat asset together only in test/shadow fixtures.

Gate: round-trip structural equality over synthetic edge cases and installed
DAT samples; no traversal cutover yet. **PASSED 2026-07-25:** 13 focused
structural/installed-DAT tests, the 131-test expanded Slice I oracle, complete
Core/solution Release gates, exact float-bit comparisons, and corruption
tripwires pass. The graph route remains the only executable traversal.
Evidence:
[`../research/2026-07-25-slice-i2-flat-collision-schema.md`](../research/2026-07-25-slice-i2-flat-collision-schema.md).

### I3 — package serialization, bake, and prepared collision source

1. Append new `PakAssetType` values; never renumber the existing mesh values.
2. Bump `CurrentBakeToolVersion` because a complete production package now
   includes collision assets.
3. Add strict little-endian serializers with checked counts/ranges, exact float
   bits, cancellation, CRC coverage, corruption rejection, and trailing-byte
   rejection.
4. Add a typed `IPreparedCollisionSource` over the existing memory-mapped pak.
   It shares package/catalog lifetime but does not overload the render-only
   `ObjectMeshData` API.
5. Bake:
   - GfxObj physics BSP + polygons + visual bounds;
   - Setup cylinder/sphere/dimension records;
   - CellStruct physics BSP + containment BSP + physics/portal polygons;
   - EnvCell topology records.
6. Alias only byte-identical immutable collision payloads. Cell-specific
   topology and world placement cannot be aliased merely because geometry is.
7. Extend full-bake determinism, two-thread equivalence, corruption,
   cancellation, publish-transaction, and catalog-completeness tests.

Gate: two independent bakes are byte-identical; every collision key required
by the canonical route is present; a failed/cancelled bake cannot replace the
last good pak. **PASSED 2026-07-25:** two complete 29,908,271,024-byte bakes
with different worker counts produced the same SHA-256 and 2,232,170 typed
keys with zero failures. Strict serialization/corruption/cancellation gates,
representative installed-package reads, Release build, and 8,371 solution
tests / 5 skips pass. Production traversal remains graph-only. Evidence:
[`../research/2026-07-25-slice-i3-prepared-collision-package.md`](../research/2026-07-25-slice-i3-prepared-collision-package.md).

### I4 — flat traversal shadow implementation

1. Port each current entry point line-for-line against integer-index nodes:
   - point-in-cell;
   - sphere/cell overlap;
   - walkable search;
   - six-path moving collision dispatcher;
   - static sphere/polygon overlap;
   - time-of-impact overlap.
2. Share only polygon-level math that is storage-independent. Do not
   “simplify” recursion, branch ordering, or early returns.
3. Preserve mutation semantics for valid-position spheres, hit polygon, path,
   contact plane, slide normal, walk interpolation, and transition state.
4. Add a differential harness that executes old and flat queries from cloned
   transition/body inputs and compares:
   - bool/enum result;
   - all output vectors/planes by float bits;
   - selected polygon ID;
   - path/collision/object side effects;
   - cell membership and final `ResolveResult`.
5. Sweep a large installed-DAT sample with randomized points, spheres,
   movement vectors, insert modes, orientations, scales, and boundary values.
6. Require explicit fixtures for null children, on-plane equality, radius
   equality, equal candidate distances, multi-polygon leaf order, and deep
   trees.

Gate: zero differential mismatch. Any mismatch blocks cutover; no tolerance
band is permitted for deterministic scalar results.

### I5 — dual publication and connected shadow gate

1. Extend collision preparation so a `LandblockBuild` carries immutable flat
   assets and small placement/topology records rather than reparsing them on
   the update thread.
2. During the shadow phase, publish both current and flat views under one
   landblock generation/receipt.
3. Keep the current graph path authoritative. Run sampled flat queries from
   cloned inputs and emit a deterministic mismatch artifact without affecting
   gameplay.
4. Verify load, pending-to-loaded, demotion, rehydrate, same-location revisit,
   removal, cancellation, and session reset release both views exactly once.
5. Run connected login, indoor/outdoor portal churn, doors, ramps, jumping,
   projectiles, camera collision, and graceful reconnect.

Gate: zero shadow mismatch and no retained collision owner after landblock or
session teardown.

### I6 — production cutover and graph removal

1. Flip canonical `PhysicsDataCache` records and every `BSPQuery` production
   call to flat assets in one bisectable commit.
2. Keep the graph route as an automated referee for the first cutover gate,
   with an exact revert command recorded in this plan and project memory.
3. After automated and user correctness acceptance, remove:
   - production `PhysicsBSPTree`/`CellBSPTree` retention;
   - production polygon dictionaries and vertex DBObj graphs;
   - raw collision graphs from streaming build/publication payloads;
   - obsolete graph adapters and referee code.
4. Live-DAT tooling may parse source graphs only to produce/compare flat
   assets; gameplay production never falls back from a missing/corrupt prepared
   collision asset.

Gate: trajectories and collision fixtures remain bit-identical, package-only
startup succeeds, and retained-memory accounting shows no parsed collision
DBObj graph after stable world reveal.

### I7 — allocation, soak, and documentation closeout

1. Measure capped and uncapped resolve allocation separately for player,
   remotes, projectiles, and camera.
2. Run the canonical connected lifecycle/reconnect route and the nine-stop R6
   portal soak.
3. Repeat indoor door/ramp/cellar, jump/fall, combat/projectile, and camera-wall
   gates.
4. Under RDP, accept correctness and lifecycle evidence only; defer absolute
   GPU/frame-time acceptance to a physical-display run.
5. Update architecture, WorldBuilder inventory, milestones, roadmap, issue
   ledger, divergence register, and both physics/render memory digests.

Final gate:

- full Release build and solution tests;
- zero deterministic old-vs-flat mismatch;
- zero steady transition/query-scratch allocation;
- no raw collision graph in production stable state;
- connected portal/reconnect/interaction routes pass;
- exact cutover rollback recorded before user verification.

## 4. Commit order

Each unit is independently buildable and reversible:

1. `docs(physics): pin Slice I collision oracle and fixtures`
2. `perf(physics): reuse reset-complete transition scratch`
3. `feat(physics): define deterministic flat collision assets`
4. `feat(content): bake and read flat collision assets`
5. `feat(physics): add differential flat BSP traversal`
6. `feat(streaming): shadow-publish flat collision assets`
7. `perf(physics): cut production traversal to flat assets`
8. `refactor(physics): remove parsed collision graphs`
9. `docs(physics): close Slice I evidence and roadmap`

The exact production-cutover commit and its `git revert <sha>` command are
added to this plan and `claude-memory/project_physics_collision_digest.md`
immediately when step 7 lands, before any visual/correctness gate.