acdream/docs/research/2026-07-25-slice-g4-production-cutover-automated-gate.md

# Slice G4 Production Cutover — Automated Gate

**Date:** 2026-07-25

**Production cutover:** `ef1d263337997bb030eadb7b8e71d73dc659907a`

**Gated source:** `03b10183e95985c658e5975d2cc1a082a589738d`

**Result:** automated gate accepted; user visual gate pending

## Purpose

G4 makes the retained, scene-built `RenderFrameView` the production entity
source at the five existing retail PView stages. Terrain, buildings, EnvCells,
particles, alpha ordering, selection, lighting, mesh/texture ownership, and GL
execution retain their established owners. The old route is still built only
as a diagnostic referee while lifecycle automation is enabled; it is not
drawn.

## Cutover shape

- `RetailPViewRenderer` borrows the exact generation/frame-stamped product.
- `RetailPViewPassExecutor` expands its ordered route ranges at the same five
  PView stages used before the cutover.
- `WbDrawDispatcher` classifies and draws packed candidates through the
  established shader, texture, light, alpha, and selection owners.
- Unchanged static classifications and ordered scene indices persist across
  frames; only dirty records refresh.
- Full-scene digests and old/new comparisons are consumer-gated and absent
  from an ordinary launch.
- Production does not require or call the current-path referee.

## Corrections made before and during the gate

The first implementation pass found and corrected four integration costs
before the cutover commit:

1. ordinary runtime composition incorrectly required the optional comparison
   observer;
2. selection geometry was constructed twice;
3. a diagnostic scene digest sorted the full scene every production frame;
4. outdoor/dynamic indices were copied and sorted every frame despite stable
   membership.

The first exact nine-stop run then exposed an independent reveal-readiness
weakness. Composite warmup used the same 128-item limit for cheap candidate
discovery and expensive mesh/texture preparation. Caul's roughly 21,000
retained objects could exhaust the portal reveal window before discovery
finished. `129dd77d` separates those budgets.

A second run proved that a late membership edge could still restart the
whole-world follow-up scan. `03b10183` adds a stable destination-neighborhood
source over `GpuWorldState`'s canonical published buckets. Warmup now reads
only the 3×3 reveal neighborhood, including static and live projections while
the generation is deliberately quiesced. Both corrections apply equally to
the old and retained draw paths; neither changes the visual rollback boundary.

## Exact physical evidence

| Route | Report | Product comparisons | Final rebuild / cross-frame reuse | Result |
|---|---|---:|---:|---|
| Capped nine-stop | `logs/connected-r6-soak-20260725-043955.report.json` | 20,502 | 1 / 6,109 | pass |
| Uncapped nine-stop | `logs/connected-r6-soak-20260725-044923.report.json` | 24,463 | 2 / 6,037 | pass |
| Uncapped dense Arwic | `logs/connected-dense-town-20260725-045805.report.json` | 1,634 | 2 / 3,833 | pass |

Every route used a Release binary whose embedded commit exactly matched
`03b10183e95985c658e5975d2cc1a082a589738d`, exited with code zero through the
graceful logout path, and recorded:

- zero product/referee candidate mismatch;
- zero reveal invariant failure;
- every canonical reveal ready;
- zero composite warmup items at every stable checkpoint;
- zero pending render-journal operations or rejected scene deltas;
- retained-classification reuse across returns;
- fixed-camera PNG artifacts for every checkpoint.

Dense Arwic exercised 15,530 resident objects and 111 active animated statics.
Its final frame retained 4,949,760 bytes of packed classification and reused
3,833 unchanged visible projections.

## Performance interpretation

The connected G4 gate intentionally keeps the complete old route and
field-level referee enabled on every sampled frame. Dense Arwic therefore
reported 29.3 ms CPU p50 and roughly 10 MiB of diagnostic allocation per frame
while GPU p50 remained 1.8 ms. These are comparison-mode costs, not the
production-only result. An ordinary development launch after consumer-gating
measured roughly 8 ms with about 90 KiB frame-thread allocation in a dense
scene. The authoritative production-only performance matrix belongs to G5,
after the user visual gate permits deletion of the old route and transition
diagnostics.

## Deterministic gate

- Production composition succeeds without a comparison observer.
- The product routes in exact PView stage order.
- Transform-only scene updates preserve index revision and refresh only the
  dirty record.
- Membership/sort changes advance index revision and rebuild ordered indices.
- A 21,025-record warmup discovery completes independently of the conservative
  128-entity preparation/upload budget.
- Readiness snapshots include destination static/live projections even while
  ordinary gameplay visibility is quiesced.
- App Release: 3,775 passed / 3 skipped.
- Complete Release solution: 8,259 passed / 5 skipped.
- Release build: zero errors; the complete test build retains 16 pre-existing
  test warnings.

## Visual gate and rollback

The user must still inspect login, outdoor/dungeon portal transitions,
selection, alpha/translucency, animated/equipped objects, particles, radar,
and repeated destination returns before G4 can delete the old referee.

If that visual gate fails, the exact surgical command is:

```powershell
git revert ef1d263337997bb030eadb7b8e71d73dc659907a
```

Do not reset the branch and do not revert G3 (`6a026c5a`). The two
reveal-readiness corrections are valid on both draw paths and remain after the
cutover revert.