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 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

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.