# 6. Streaming map validator (PR F, tooling)

## Problem

Setup validated every converted map by launching the game once per map
(`skate3rust --assets <stage> --map <map> --check-assets`, inside each
`map_job` subprocess), plus a `--test-world --check-assets` launch before and
after the map stage and one per recovered old map. Each launch cost ~7–8 s, of
which only 0.1–2 s depended on the map: ~6 s was the same stock loading
(skater runtime 3.2 s, controls + camera 2.5 s) repeated every time.

The check was also weak: a map passed as long as it loaded. It did not catch the
spawn problems found in play (skater falling into the void on MegaPark, standing
on an invisible collision-only floor in Industrial).

## Change

### Game: `skate3rust --assets <dir> --validate-maps`

New module `crates/skate-game/src/map_validation.rs`, dispatched from `main.rs`
after the stock loads (config, gameplay config, manifest, graphs):

- Loads once: animation source, controls and camera (fail fast, like
  `--check-assets`). Prints `SKATE_VALIDATOR_READY seconds=…` on stdout.
- Reads one request per stdin line (a `.skate` path or `TEST_WORLD`) and answers
  with one `SKATE_MAP_CHECK {json}` stdout line; exits 0 at EOF. All other game
  output stays on stderr. Works through the crash supervisor, which forwards the
  child's stdout/stderr unchanged and lets it inherit stdin.
- Per request:
  - **errors** (the map is rejected, as before): map load,
    `skate_world::validate_runtime`, physics with the map's collision, skater
    runtime. A panic inside one map becomes that map's error (`catch_unwind`).
  - **warnings** (reported, never rejecting): from
    `physics/startup_check.rs` — no collision within 10 m below the spawn; deck
    spawned away from the map spawn/heading; a neutral startup (zero actions,
    as with no controller) must settle with wheel support for 12 consecutive
    ticks within 240 ticks (4 s at 60 Hz), with finite body state, no physics
    failure and a solved wheel contact; and the collision floor under the spawn
    must have a visible (render) surface within 1 m.
  - JSON fields: `path, ok, errors, warnings, collision_triangles, spawn,
    support_drop, grounded_ticks, visible_floor_gap, seconds, timings`.
- `--check-assets` is unchanged.

### Setup (`tools/asset_pipeline/install.py`)

- `MapValidator` runs one validator process; `start_validator` falls back to
  per-map `--check-assets` launches if it cannot start (e.g. an older game exe),
  and `validate()` falls back for the rest of the run if the process dies.
- The pre-map stock check, every map (as soon as its conversion finishes, while
  the remaining maps keep converting), recovered old maps and the final
  test-world check all go to the same process. The per-map launch was removed
  from `convert_map`.
- Process launching (packaged-exe DLL/PATH handling) moved from `run()` into a
  shared `spawn()`; `run()` behaves as before.
- Warnings are written to `assets/private/map-status/<map>-validation.json`
  (`status: "warning"`) by `record_validation`. New module
  `validation_report.py` wraps `optional_content.summary` and adds them to
  `setup-report.json` and the setup message; `install.py` and `tools/setup.py`
  call the wrapper. `optional_content.py` itself is deliberately untouched: it is
  part of the hud/environment/maps fingerprints **and** of every
  character-customiser stage version (`customiser_cache.SHARED`), so editing it
  would make every existing installation rebuild the customiser (~4 min), which
  has no equivalence mechanism. (A first version edited it; the fingerprint
  check that caught this compares against the committed tree, not a local
  install.)
- `pipeline-equivalence.json`: removing validation from `convert_map` changes the
  `maps` fingerprint without changing any output, so an old→new pair is added
  (combined with PR G's stream change, see doc 8). Verified: an installation
  built from the committed code rebuilds no group, and the customiser
  fingerprint and all five stage versions are unchanged.

## Verification

- Validator on the test world and all 10 maps: all `ok`, no warnings; collision
  triangle counts equal the post-volume-fix baseline.
- Negative cases (bad spawns written into copies of real maps):
  MegaPark's old void spawn → "no collision within 10 m below the spawn" +
  "wheels never found support"; Industrial's old harbour-bed spawn → "no visible
  surface … (invisible collision)".
- Known limit: a spawn on a solid, visible roof (Industrial Skate Park's old
  roof spawn) is not flagged — rooftops are legitimate skate spots; only
  authored start data (doc 4) distinguishes them.
- Unit tests: `map_validation::tests` (visible-surface heights, single-line JSON
  with the documented fields); Python `test_map_validator.py` with a fake
  validator speaking the protocol (results, warnings into `setup-report.json`,
  start failure fallback, process death, request injection, pipes closed under
  `-W error::ResourceWarning`). Existing setup/pipeline suites pass (40 tests).
- Fingerprints: with the equivalence pairs, an existing installation rebuilds
  no groups.
- Full setup with the real game: see "Setup run" below.

### Setup run

Full fresh setup from the extracted disc with the real game exe (Windows 11,
i7-14700KF, 3 map workers): **466 s, 0 warnings**; the validator was used
throughout (no fallback).

| Step | Before | After |
|---|---|---|
| Pre-map stock check (`--test-world --check-assets` → validator start + `TEST_WORLD`) | ~6 s | ~1 s |
| Per-map validation | ~7–9 s each, inside each map job | 0.28–1.79 s each, in the parent while other maps convert |
| Map stage (convert + validate 10 maps) | ~217 s | 183 s |

Per-map `phase_seconds.validate` in `maps.json`: University 1.54, DownTown 1.79,
Industrial 1.11, parks 0.28–0.37 s. Afterwards `check_maps`-style validation of
all maps: all ok, no warnings, collision triangles identical; baked spawns
identical to the authored values (doc 4).

## Notes

- The ignored private test `private_extracted_map_supports_production_gameplay_startup`
  uses a fixed 24-tick window and fails on Industrial Skate Park, whose authored
  start is 0.75 m above the floor (≈0.39 s ≈ 23–24 ticks of fall). The map is
  fine in play; the validator uses the settle rule above instead. The test was
  left unchanged.
- Without PR E (collection index) every per-map check would still take ~5.8 s.

## Files

- `crates/skate-game/src/map_validation.rs` (new), `physics/startup_check.rs` (new),
  `main.rs`, `config.rs`, `physics.rs`, `skater_animation.rs` (`AnimationSource::load` visibility),
  `retail_character.rs` + `tests/map_transition.rs` (new `Config` field in test literals)
- `tools/asset_pipeline/install.py`, `validation_report.py` (new), `pipeline-equivalence.json`,
  `test_map_validator.py` (new), `tools/setup.py` (message wording)