feat(content): bake and read flat collision assets

Append strict collision/topology payloads to the existing prepared package so later physics cutover can drop parsed DAT graphs without adding a second mapping or changing traversal behavior. The full 2,232,170-key catalog is deterministic across worker counts, exact-byte aliased, corruption-isolated, and cancellation-safe.

docs/research/2026-07-25-slice-i3-prepared-collision-package.md

@@ -0,0 +1,97 @@
+# Slice I3 — prepared flat-collision package
+
+**Date:** 2026-07-25
+**Scope:** Modern Runtime Slice I3 only
+**Behavioral boundary:** storage, serialization, bake, and prepared lookup;
+production collision traversal remains on the parsed-DAT graph oracle.
+
+## Result
+
+The existing format-1 `acdream.pak` now carries four appended asset types:
+
+| Numeric type | Payload |
+|---:|---|
+| 4 | GfxObj collision BSP, polygon table, bounding sphere, and visual bounds |
+| 5 | Setup cylinders, spheres, and movement dimensions |
+| 6 | reusable CellStruct physics BSP, containment BSP, and portal polygons |
+| 7 | independently keyed EnvCell portals, visibility, and `seen_outside` |
+
+The existing mesh type values 1–3 did not change. Bake-tool identity advanced
+from 3 to 4; the package binary container remains format 1.
+
+`FlatCollisionAssetSerializer` is a strict little-endian codec. It:
+
+- writes every `float` through `SingleToInt32Bits`;
+- retains node, polygon, vertex, Setup-shape, portal, and visible-cell order;
+- checks counts before allocation and validates combined byte requirements;
+- checks cancellation during large rows;
+- rejects wrong payload kinds, unsupported schema versions, non-zero reserved
+  bits, invalid enum/tree/range contracts, truncation, and trailing bytes;
+- remains behind the package entry CRC, so a CRC or structural fault marks
+  only that typed entry corrupt.
+
+`IPreparedCollisionSource` is separate from the render-only
+`IPreparedAssetSource` API. `PakPreparedAssetSource` implements both over the
+same `PakReader` and therefore maps the 29.9 GB immutable package once, not
+once per subsystem. Render and collision counters are independent.
+
+CellStruct collision geometry is addressed by every EnvCell source key. The
+bake emits ordinary TOC aliases within the same source group and across groups
+only after comparing the complete serialized payload bytes. Per-cell topology
+is always written under its own key and is never inferred from shared render
+geometry.
+
+## Complete installed-DAT bake
+
+Two independent full bakes used 16 and 7 workers:
+
+| Metric | Result |
+|---|---:|
+| GfxObj mesh keys | 15,318 |
+| Setup mesh keys | 5,935 |
+| EnvCell mesh keys | 729,888 |
+| GfxObj collision keys | 15,318 |
+| Setup collision keys | 5,935 |
+| CellStruct collision keys | 729,888 |
+| EnvCell topology keys | 729,888 |
+| Total typed keys | 2,232,170 |
+| Physical blobs | 781,196 |
+| Failures | 0 |
+| File bytes | 29,908,271,024 |
+| SHA-256 | `FEE8595D512DCB119C98B3D9911CDF9A905C97B624BCB826CEAF8DFD3F67269C` |
+
+Both complete files have identical length and SHA-256. Exact-byte
+deduplication produced:
+
+- 9,363 physical GfxObj collision blobs behind 15,318 keys;
+- 979 physical Setup collision blobs behind 5,935 keys;
+- 2,596 physical CellStruct collision blobs behind 729,888 keys.
+
+The 16-worker bake completed and validated in 107.5 seconds; the 7-worker bake
+completed and validated in 80.5 seconds. Peak bake-process memory was
+4.43–4.89 GB working set and 3.81–4.21 GB private. This is offline extraction
+state and is not mapped as committed client memory; the production source
+memory-maps the immutable file and pages only accessed ranges.
+
+The validated bake-tool-4 package was installed at the machine-local DAT
+location for subsequent Slice I gates.
+
+## Verification
+
+- strict codec round-trip and exact-float-bit tests for all four payloads;
+- every truncation of a representative payload rejected;
+- wrong-kind, negative/impossible count, trailing-byte, CRC, and valid-CRC
+  structural-corruption tests;
+- concurrent prepared reads and separate render/collision accounting;
+- raw-DAT versus current cached-source preparation on representative installed
+  GfxObjs, Setups, and EnvCells;
+- filtered 1/8- and 8/3-worker bake equivalence and exact alias tests;
+- complete installed package reads for representative GfxObj, Setup,
+  CellStruct, and EnvCell topology keys;
+- failed validation and timed cancellation preserve the last published file;
+- Release build: zero warnings;
+- complete Release suite: 8,371 passed / 5 skipped.
+
+No divergence-register row changes: no gameplay decision or traversal route
+changed. Slice I4 adds the flat traversal referee while the graph path remains
+authoritative.