acdream/docs/research/2026-07-25-slice-i6-flat-production-cutover.md

Slice I6 — flat production collision cutover

Result

Commit 068a06518dd710ca5e7f166754cbb7789ca1ed0f makes the immutable prepared collision representation authoritative for gameplay. The parsed DAT graph remains temporarily resident only as the automated differential referee.

Production now:

• creates its PhysicsDataCache through the explicit production factory;
• fails publication when a required prepared GfxObj, Setup, CellStruct, or EnvCell topology record is genuinely absent;
• accepts idempotent publication when that flat asset is already resident;
• returns flat results even when the graph referee disagrees;
• uses flat containment for the unified cell graph;
• uses flat polygon tables for nearest indoor floor lookup;
• derives live/static BSP shape bounds and camera diagnostics from flat data.

Graph-only cache construction remains an explicit test/tooling oracle seam until the post-acceptance deletion commit.

Exact rollback

git revert 068a06518dd710ca5e7f166754cbb7789ca1ed0f

Do not revert the I3 package schema, I4 traversal, or I5 dual-publication commits.

Automated conformance

• Release build: pass.
• Complete Release solution: 8,402 passed / 5 skipped.
• Warm flat traversal: 0 B.
• Reused resolver scratch across player, remote, projectile, camera, and grounded mover families: 0 B/resolve.
• Retained render hot-path allocation fixtures: pass.
• Flat-authoritative mismatch fixture proves the graph cannot change gameplay.
• Production publication fixtures prove missing prepared data fails and an already-resident prepared asset remains idempotent.

Connected strict-publication/referee gate

Evidence: logs/connected-dense-town-20260725-165758.report.json.

• PASS with graceful authoritative logout and WM_CLOSE.
• Dense Arwic: 15,530 entities / 111 animated.
• Collision referee: 46,309 queries, 46,309 exact matches.
• Mismatches: 0.
• Referee faults: 0.
• Mismatch artifacts: 0.
• Stable cell residency: 292 graph / 292 flat during the referee window.

The first strict attempt correctly exposed an idempotency-contract defect: LiveCollisionAssetPublisher passed null after finding the prepared asset already resident, and the guard interpreted that as absent. The root fix makes the cache distinguish “already published” from “not provided”; strict missing package data still fails.

Production-like performance check

The normal connected gate intentionally enables the complete current-path render oracle and allocates about 10.8 MiB/frame in dense Arwic. It is a correctness observer, not a production performance measurement.

A separate Release run used the same dense-Arwic arrival and six-second camera turn with:

• uncapped rendering;
• no lifecycle artifact directory;
• no current-path render oracle;
• no collision referee;
• no runtime counter attachment.

Stable result:

• about 190–200 FPS;
• CPU p50 about 5.0 ms;
• CPU p95 about 5.9–7.3 ms;
• GPU p95 about 2.1 ms;
• update p95 about 1.4–1.8 ms;
• roughly 8% total-machine CPU;
• working set about 1.12 GiB;
• private bytes about 1.41 GiB;
• warm allocation about 84.6 KiB/frame in the dense scene.

The parsed graph is still resident in those memory figures. I6 graph removal must reduce that footprint and prove stable production graph counts are zero.

Physical-display full-route soak

An exact clean worktree at source/binary 9f37d1793674a7bf5101ef22d5c5d956b8d101a2 completed the canonical nine-stop route on the physical display:

• all nine checkpoints and every materialization passed;
• Caul, Holtburg, and return-to-Caul movement/jump/combat exercises passed;
• server-spawned/static lifecycle checks passed;
• final publication, retirement, worker, destination, control, unload, near/far, staged-upload, and composite-warmup backlogs were all zero;
• graph and flat residency agreed at 175 cells in the final stable state;
• graph retention remained intentional for the pending user gate;
• diagnostic-route memory plateaued at 2.020 GiB in Sawato and 2.061 GiB on final Caul rather than growing without bound;
• instrumented-route GPU p95 stayed at or below 2.8 ms.

The roughly 2 GiB diagnostic working set is not the ordinary client footprint: that route deliberately retains the old and new collision representations and enables the full current-path render oracle.

A separate ordinary uncapped Release client at Caul with about 21,025 live entities, no profiler, no render oracle, and no route automation produced this 20-sample physical-display result:

• 156 FPS average (140 minimum, 166 p95, 172 maximum);
• 6.42 ms average displayed frame time;
• 7.50% average whole-machine CPU;
• 27.07% average GPU 3D utilization;
• 1.080 GiB average working set;
• 1.291 GiB average private bytes.

The uncapped GPU percentage is demand created by rendering as fast as the CPU can submit frames, not evidence of a GPU bottleneck: measured GPU frame p95 remained below 3 ms while displayed frame time was about 6.4 ms. Memory remains above the target while both collision representations are intentionally resident; the accepted graph-removal step must measure the reduction.

A later 20-sample repeat from the same still-connected process confirmed the plateau: working set stayed exactly 1.059 GiB and private bytes exactly 1.236 GiB throughout the sample. It averaged 177.6 FPS / 5.65 ms, 7.67% whole-machine CPU, and 30.40% GPU 3D. The higher GPU percentage tracked the higher uncapped frame rate; it did not coincide with working-set growth.

Acceptance boundary

The automated cutover gate is complete. Before deleting the referee and parsed graph, the user must verify outdoor/indoor movement, doors, ramps/stairs, jump/fall, camera-wall collision, object interaction, combat/projectiles, and portal/reconnect behavior on the cutover commit.