Blame for docs/VALIDATION_AND_MILESTONES.md

# Validation, milestones, decisions, and completion gates

The stages below are dependency gates rather than calendar estimates. One playable slice proves integration; it does not reduce the requested all-content/all-game scope. Use task IDs in the linked TODO documents to form implementation issues once the relevant research evidence exists.

## Routine validation

Use the [Rust cargo xtask runner](TESTING.md) for affected report regeneration and dependency-selected tests before each task commit. Run `cargo xtask test-full --since <batch-base>` before pushing a batch. This replaces repeating the entire Python suite after every small task; platform/runtime milestone checks below remain separate.

## Dependency order

```mermaid
flowchart TD
    A[Reference identity and all-file inventory] --> B[Original execution and evidence harness]
    A --> C[VFS and original format specifications]
    A --> D[Bevy and Solari hardware proof]
    B --> E[Native and QVM ABI, rules and traces]
    C --> F[Versioned conversion pipeline]
    E --> G[Shared simulation and headless server]
    F --> H[Bevy world, animation, audio and UI]
    D --> I[Complete Solari material and rendering port]
    H --> I
    E --> J[Network and demo specification]
    G --> K[Prediction, multiplayer and compatibility]
    J --> K
    G --> L[All modes, entities, gear and bots]
    K --> M[Full content and platform conformance]
    L --> M
    I --> M
    F --> M
    M --> N[Packaging, documentation and release]
```

Every subsystem also loops through specification → fixtures → implementation → comparison → corrected findings. Early evidence can change architecture; keep those changes recorded and rerun affected tests.

## Milestones and exit criteria

| Gate | Required outputs | Exit evidence |
| --- | --- | --- |
| M0: Research baseline | Reusable inventory, all-file/member coverage register, pinned reference, research setup, rights/source/service registers | Inputs reproduce the static inventory; every item has an analysis task; reference client/server can be observed or an alternative execution environment is established. |
| M1: Platform feasibility | Pinned Bevy/Solari candidate and macOS/Linux prototype results, hardware/denoising/material/animation decisions | Actual representative machines render the test scene and imported/animated test content; blockers and required renderer extensions have a plan. Raster-only results do not pass the Solari requirement. |
| M2: Engine and content contracts | VFS, formats, native/library responsibilities, QVM decoder/ABI, units, schemas | Candidate resolution matches controlled reference tests; every format has a parser/analysis plan; QVM instructions and required syscalls are mapped sufficiently for tested slices. |
| M3: Complete initial asset pipeline | Unpacking and batch conversion, audit, dependency graph, reports | All archive variants can be inspected; required selected content converts with tracked gaps; known Paris and FRF1 overrides are resolved correctly. |
| M4: Movement/world slice | One representative map and jump fixture, collision, movement, client camera, headless simulation | Golden movement/collision traces pass; stairs/walls/ladders/water/movers and frame-rate independence have evidence; map reload cleans up. |
| M5: Combat/network slice | One complete firearm, melee/projectile examples, damage/health, Rust client/server, prediction | Two native-platform clients complete a controlled match; weapon/hit/damage traces and impaired-network tests pass. |
| M6: Complete rules and interactive world | All weapons/gear, 47 observed entity classes plus discovered supported classes, all 11 modes/modifiers, match/admin behavior | Every required rule/state transition has evidence and tests, including simultaneous/timer/disconnect edge cases. |
| M7: Full presentation port | Every shader's mapping, models/animation/attachments, Solari and legacy comparison rendering, audio, video, fonts/UI/HUD | Full material/effect coverage reports; tested raytraced animation and denoising; no silently omitted original rendering behavior. |
| M8: Bots, demos, services, compatibility | Navigation/bots, recording/playback, discovery/download/auth strategy, original compatibility decision/implementation | Per-map bot tests and controlled demos pass; required compatibility directions work; external-service behavior/failures documented. |
| M9: Exhaustive analysis/content coverage | Every installation file and member variant analysed, all maps/assets validated, handbook complete | All-file analysis matrix has no unaccounted rows; unused/obsolete/overridden content documented; required runtime assets have no unresolved blocker. |
| M10: Cross-platform release qualification | Native packages, CI/conformance, GPU performance reports, long-run/network/parser robustness, installation docs | Full declared macOS/Linux and GPU matrix passes; minimum hardware/OS/driver/performance promises have measured evidence. |
| M11: Entire-game completion | All required research, runtime, content, Solari, multiplayer, documentation and release deliverables | Goals G1–G9 satisfied; differences explicitly reviewed; no required task hidden behind a fallback or unapproved exclusion. |

M0–M3 are the recommended first work tranche. Investigate platform blockers early while research progresses; do not spend the entire asset conversion effort before proving required rendering behavior. Move through an integrated movement/combat slice before expanding every ruleset, while continuing exhaustive static analysis.

## Decisions that must be recorded

| Decision | Evidence needed | Resolve before |
| --- | --- | --- |
| Reference source/fork match and implementation license | Binary/source comparison, bundled licenses, copied-code policy | Reusing upstream implementation |
| Asset use/distribution and replacement strategy | Supplied restrictions, contributor credits, permitted media model | Public asset packaging/release |
| Rust/Bevy/Solari versions and patches | Exact release/commit capability tests | Renderer interfaces and lockfile |
| GPU/OS/CPU matrix, Intel Mac/Linux ARM64 scope | Native runs and measured limits | Public platform promises |
| macOS/Linux denoising strategy | Moving-scene image quality and frame cost | Full Solari presentation gate |
| Legacy shader/hybrid rendering architecture | Every directive/material family, ray participation | Material schema freeze |
| MD3 animation and raytracing geometry strategy | Fidelity, memory, upload and acceleration-structure tests | Model/animation runtime format |
| Coordinates, units, collision and numeric behavior | Reference traces and format contracts | Authoritative simulation freeze |
| Shared fixed-step simulation and scheduling | Timing measurements and deterministic replay | Prediction/network architecture |
| Original-wire compatibility vs new protocol/adapter | Protocol recovery, services, pure checks, executable tests | Multiplayer release scope |
| Bot navigation import vs regeneration | AAS semantics, traversal/objective tests | Navigation format freeze |
| Official services vs supported replacements | Protocol, permission/access, availability, failure behavior | Online feature contract |
| Original defect compatibility vs correction | Trigger, impact, parity need and security implications | Related implementation/test expectations |
| Runtime formats and package/schema upgrades | Required fidelity, startup/storage/memory constraints | Converter/runtime package contracts |

These are future engineering decisions to resolve with evidence, not requests for permission to write this plan. Existing user scope includes researching every file and implementing the eventual Rust game; this current deliverable is documentation only.

## Risks and concrete mitigations

| Risk | Mitigation and closure evidence |
| --- | --- |
| No complete gameplay source in the cache | QVM decoder, native ABI mapping, instrumented reference oracle, behavior fixtures; track unresolved reachability explicitly. |
| Legacy binaries difficult to run | Suitable Linux reference environment and alternate native architectures; record platform failures and retain static analysis paths. |
| Wrong asset version/case resolution | Preserve all variants; reproduce runtime VFS; regression cases for Paris and FRF1. |
| Solari platform/denoiser/material/animation gaps | Early real-GPU spike, renderer patch/hybrid plan, per-shader mapping, quality/performance acceptance tests. |
| MD3 animation data and BLAS cost | Exact-frame representation benchmarks, resource budgets and measured acceleration-structure strategy. |
| Modern physics changes movement | Custom reference-compatible traces/controller; differential usercmd replay. |
| Network/demo or service compatibility underestimated | Early packet/demo capture and explicit compatibility/service contract; interoperability exit gate. |
| Baked art/lightmaps change under Solari | Separate legacy comparison and calibrated Solari profile; no double lighting; readability/image tests. |
| Unused/overridden files silently omitted | Every file/member occurrence has an analysis record and audited final disposition. |
| Original media redistribution constraints | Per-asset provenance and permission/replacement/user-import distribution decision before release. |
| “Almost complete” after one map/mode | Explicit all-mode, all-map, all-shader, all-entity, command/cvar and all-file matrices and M11 closure. |

## Validation TODO: evidence and conformance harness

- [ ] QA-001 Define fixture IDs, input hashes, environment/cvar/map/mode requirements, outputs, clocks, units, tolerances, and intentional differences.
- [ ] QA-002 Implement deterministic usercmd replay, state/event snapshots, golden trace comparison, and useful first-divergence reports.
- [ ] QA-003 Implement reference QVM/native function capture where practical and black-box session fixtures where internals remain inaccessible.
- [ ] QA-004 Compare integer/enums/IDs/events/packet bytes exactly where the contract requires it; measure float tolerances explicitly by subsystem.
- [ ] QA-005 Compare macOS/Linux simulation traces and seeded randomness; investigate scheduler/architecture differences instead of assuming determinism.
- [ ] QA-006 Add per-rule coverage linking research findings to converted data, implementation and tests.
- [ ] QA-007 Create reproducible captures for all modes/weapon types/objectives/entities and configuration boundaries.
- [ ] QA-008 Version fixtures and rebaseline only with documented evidence, preserving changed-reference provenance.

## Validation TODO: complete folder and content coverage

- [ ] QA-009 Require every one of the 39 initial installation files and all 9,835 member occurrences to have analysis status, findings, dependencies, and disposition.
- [ ] QA-010 Require analysis of all executables/libraries/platform resources, embedded payloads, discarded patch versions, auxiliary databases and authoring files.
- [ ] QA-011 Detect newly discovered files/payloads and extend the all-file register rather than freezing scope at the initial counts.
- [ ] QA-012 Verify every format/variant and every shader directive/combination in the parsed inventory, including unused content and malformed cases.
- [ ] QA-013 Require every required asset's transitive dependencies to resolve in the final package with correct VFS selection/case semantics.
- [ ] QA-014 Compare source/converted geometry bounds/counts/winding/UVs, animation frames/tag transforms, skin mapping, fonts, and audio metadata.
- [ ] QA-015 Audit all image alpha/texture sampling/mipmap behavior and all shader legacy/Solari mappings.
- [ ] QA-016 Audit every observed/supported entity class and every active weapon/item/gear ID with evidence and fixtures.
- [ ] QA-017 Verify archive/converter/runtime parser negative tests and resource limits, with fuzzing targeted at complex binary/text inputs.
- [ ] QA-018 Rebuild bundles twice from clean outputs and compare manifests/hashes; test cache invalidation/version migrations.

## Validation TODO: gameplay, modes, bots, and administration

- [ ] QA-019 Cover movement on flats/slopes/stairs/corners, wall jumps, ledges/ladders/water/movers, injuries/stamina/gear, and latency/frame-rate variations.
- [ ] QA-020 Cover every weapon's firing/reloading/modes/ammo/recoil/spread/scope/animation/audio/attachments and interruption/death cases.
- [ ] QA-021 Cover every damage region/armor state, melee/projectile/radius/fall/environment damage, bleeding/healing and friendly/self damage.
- [ ] QA-022 Complete scripted matches for all 11 modes and all supported modifiers, including warmup/round/match/intermission/mapcycle transitions.
- [ ] QA-023 Cover spawn/respawn/waves/protection/occupied spawns, reconnects/disconnects, spectators/substitutes and match readiness/timeouts/swaps.
- [ ] QA-024 Cover simultaneous kill/objective/timer events and every original changelog regression relevant to recovered behavior.
- [ ] QA-025 Test every supported command/cvar range/flag/permission/mode restriction, persistence/latching, aliases/macros, and error behavior.
- [ ] QA-026 Test rcon/referee/voting/bans/mutes/flood/teamkill/inactivity/log/stat/admin flows and service outage behavior.
- [ ] QA-027 Test bot navigation and objective behavior on every map and supported mode, including ladders/jumps/water/movers and stuck recovery.
- [ ] QA-028 Run long matches and repeated map changes/restarts to detect state leaks, missing resets, resource accumulation and clock wrap issues.

## Validation TODO: networking and demos

- [ ] QA-029 Complete codec fixtures for framing/fragmentation/compression/baselines/deltas/usercmds/events/configstrings/content negotiation.
- [ ] QA-030 Test Rust client/server on both platforms with cross-platform peers and headless servers.
- [ ] QA-031 Test every required original client/server interoperability direction against the pinned reference; include pure/package checks and version rejection.
- [ ] QA-032 Test controlled packet loss/reordering/duplication/jitter/high latency/bandwidth limits, reconnect/timeouts, and reliable overflow handling.
- [ ] QA-033 Verify prediction/reconciliation/lag compensation and compare event/score/objective outcomes under impaired transport.
- [ ] QA-034 Test discovery/browser/favorites/status/download cancel/resume/package reload/auth failure modes without depending solely on public services.
- [ ] QA-035 Test original and new demos per the chosen contract, including metadata/version/map requirements, seek/pause/camera/audio and deterministic outcomes.
- [ ] QA-036 Test malformed/truncated/oversized network and demo input without crashes, unbounded allocation, or invalid state transitions.

## Validation TODO: presentation and performance

- [ ] QA-037 Create visual comparison fixtures for each map/material/effect family, model/skin/animation state, UI/HUD layout and camera mode.
- [ ] QA-038 Separate structural visual comparisons from intentionally changed Solari illumination, with accepted brightness/visibility tolerances.
- [ ] QA-039 Test raytraced animated geometry/attachments, moving shadows/reflections, masked/transparent surfaces, fog/portals and hybrid composition.
- [ ] QA-040 Test moving-scene noise, denoising/ghosting, first-person weapons, camera cuts/teleports/respawns, emissive flashes and night vision.
- [ ] QA-041 Test every sound family/event/frame/loop, environmental/spatial output, music/radio priority and video synchronization.
- [ ] QA-042 Test supported resolutions/DPI/window modes, mouse/text focus, resizing, device hot-plug, X11/Wayland and macOS fullscreen/Retina behavior.
- [ ] QA-043 Establish explicit performance budgets on representative hardware: frame percentiles, input latency, server tick cost, bandwidth, CPU/GPU memory and startup/load times.
- [ ] QA-044 Measure Solari sample/denoising/BLAS/material/texture costs on largest maps and full matches, including view weapons, bots and effects.
- [ ] QA-045 Test headless server memory/CPU/network budgets separately from the graphical client.
- [ ] QA-046 Profile cold/warm loads, shader compilation, asset streaming, map reloads, GPU validation warnings and long-session stability.
- [ ] QA-047 Publish measured requirements and benchmark methods; the original `com_maxfps 125` setting is context, not an established rewrite performance guarantee.

## Validation TODO: release and documentation

- [ ] QA-048 Test a clean checkout and user-supplied installation through import/conversion/build/launch without undeclared local dependencies.
- [ ] QA-049 Test native packages on clean macOS/Linux environments, including CPU architecture, drivers, shared libraries, permissions and data paths.
- [ ] QA-050 Verify first-launch asset/hardware/service diagnostics and graceful unsupported-device/content handling.
- [ ] QA-051 Review licenses/attribution/source notices and validate the agreed bundle/user-import/replacement-media policy.
- [ ] QA-052 Finish user, developer, research, server, content-authoring, build, installation and troubleshooting guides with working commands.
- [ ] QA-053 Publish per-platform/Solari/content/gameplay/interoperability matrices and the list of intentional differences and remaining unsupported optional tiers.
- [ ] QA-054 Audit every unchecked task against goals and resolve all required blockers; scope changes require explicit recorded agreement rather than silent omission.
- [ ] QA-055 Record final M11 acceptance evidence and release hashes; do not label the entire rewrite complete while required features or file analysis are missing.

## Per-map completion checklist

Each entry requires analysis of all archived variants, dependencies, materials, geometry/collision/entities/navigation, conversion, native macOS/Linux loading, legacy and Solari presentation, a gameplay pass for every declared/supported compatible mode, and bots where applicable. Preserve unsupported-mode handling and special features in its coverage record. The jump demonstration has its explicit research/example role rather than an assumed full matchmaking role.

- [ ] MAP-001 Complete `ut4_abbey` and every archived variant (initial candidate: `zUrT43_002.pk3`; 93 entity records).
- [ ] MAP-002 Complete `ut4_algiers` and every archived variant (initial candidate: `zUrT43_002.pk3`; 156 entity records).
- [ ] MAP-003 Complete `ut4_austria` and every archived variant (initial candidate: `zUrT43_002.pk3`; 147 entity records).
- [ ] MAP-004 Complete `ut4_bohemia` and every archived variant (initial candidate: `zUrT43_002.pk3`; 377 entity records).
- [ ] MAP-005 Complete `ut4_casa` and every archived variant (initial candidate: `zUrT43_002.pk3`; 498 entity records).
- [ ] MAP-006 Complete `ut4_cascade` and every archived variant (initial candidate: `zUrT43_002.pk3`; 359 entity records).
- [ ] MAP-007 Complete `ut4_docks` and every archived variant (initial candidate: `zUrT43_002.pk3`; 604 entity records).
- [ ] MAP-008 Complete `ut4_dressingroom` and every archived variant (initial candidate: `zUrT43_002.pk3`; 83 entity records).
- [ ] MAP-009 Complete `ut4_eagle` and every archived variant (initial candidate: `zUrT43_002.pk3`; 359 entity records).
- [ ] MAP-010 Complete `ut4_elgin` and every archived variant (initial candidate: `zUrT43_002.pk3`; 532 entity records).
- [ ] MAP-011 Complete `ut4_firingrange` and every archived variant (initial candidate: `zUrT43_002.pk3`; 55 entity records).
- [ ] MAP-012 Complete `ut4_ghosttown` and every archived variant (initial candidate: `zUrT43_002.pk3`; 242 entity records).
- [ ] MAP-013 Complete `ut4_herring` and every archived variant (initial candidate: `zUrT43_002.pk3`; 431 entity records).
- [ ] MAP-014 Complete `ut4_jumpents` and every archived variant (initial candidate: `ut4_jumpents.pk3`; 20 entity records; example/timer fixture).
- [ ] MAP-015 Complete `ut4_killroom` and every archived variant (initial candidate: `zUrT43_002.pk3`; 25 entity records).
- [ ] MAP-016 Complete `ut4_kingdom` and every archived variant (initial candidate: `zUrT43_002.pk3`; 390 entity records).
- [ ] MAP-017 Complete `ut4_kingpin` and every archived variant (initial candidate: `zUrT43_002.pk3`; 302 entity records).
- [ ] MAP-018 Complete `ut4_mandolin` and every archived variant (initial candidate: `zUrT43_003.pk3`; 483 entity records).
- [ ] MAP-019 Complete `ut4_mykonos_a17` and every archived variant (initial candidate: `zUrT43_003.pk3`; 162 entity records).
- [ ] MAP-020 Complete `ut4_oildepot` and every archived variant (initial candidate: `zUrT43_003.pk3`; 227 entity records).
- [ ] MAP-021 Complete `ut4_paris` and every archived variant (initial candidate: `zUrT43_021.pk3`; 522 entity records).
- [ ] MAP-022 Complete `ut4_prague` and every archived variant (initial candidate: `zUrT43_003.pk3`; 268 entity records).
- [ ] MAP-023 Complete `ut4_prominence` and every archived variant (initial candidate: `zUrT43_003.pk3`; 135 entity records).
- [ ] MAP-024 Complete `ut4_raiders` and every archived variant (initial candidate: `zUrT43_003.pk3`; 319 entity records).
- [ ] MAP-025 Complete `ut4_ramelle` and every archived variant (initial candidate: `zUrT43_003.pk3`; 536 entity records).
- [ ] MAP-026 Complete `ut4_ricochet` and every archived variant (initial candidate: `zUrT43_003.pk3`; 387 entity records).
- [ ] MAP-027 Complete `ut4_riyadh` and every archived variant (initial candidate: `zUrT43_003.pk3`; 212 entity records).
- [ ] MAP-028 Complete `ut4_sanc` and every archived variant (initial candidate: `zUrT43_003.pk3`; 404 entity records).
- [ ] MAP-029 Complete `ut4_suburbs` and every archived variant (initial candidate: `zUrT43_003.pk3`; 664 entity records).
- [ ] MAP-030 Complete `ut4_subway` and every archived variant (initial candidate: `zUrT43_003.pk3`; 327 entity records).
- [ ] MAP-031 Complete `ut4_swim` and every archived variant (initial candidate: `zUrT43_003.pk3`; 538 entity records).
- [ ] MAP-032 Complete `ut4_thingley` and every archived variant (initial candidate: `zUrT43_004.pk3`; 416 entity records).
- [ ] MAP-033 Complete `ut4_tombs` and every archived variant (initial candidate: `zUrT43_004.pk3`; 668 entity records).
- [ ] MAP-034 Complete `ut4_turnpike` and every archived variant (initial candidate: `zUrT43_004.pk3`; 248 entity records).
- [ ] MAP-035 Complete `ut4_uptown` and every archived variant (initial candidate: `zUrT43_004.pk3`; 647 entity records).

## Tracking completeness

Track separately: **analysed file/member occurrences**, **specified/recovered behaviors**, **converted content**, **implemented features**, and **passed conformance fixtures**. These percentages have different denominators and cannot substitute for one another. Report blockers by goal and milestone. Initial static inspection is evidence for inventory/headers; it is not a completion mark for any full subsystem.