horizon-airdef/docs/playable-validation.md

First playable release validation

Version 0.2.0 targets Minecraft 26.3 / Fabric 0.19.5 / Java 25. This is an initial playable Java optimization stack, not a completed renderer rewrite. Measurements here establish what was actually checked.

Local checks

• Official client runs through a Wayland virtual screen in built-in limited demo mode, without Microsoft credentials. Normal Mac play uses licensed Prism sign-in.

• Balanced stack (Sodium, Lithium, FerriteCore, ImmediatelyFast, EntityCulling, Distant Horizons, Fabric API, Horizon Lab) reaches the menu, loads the demo world, logs in locally, renders terrain, and saves/quits.

• DH generates and accepts the current configuration schema: 128-chunk LOD radius, two background threads at 0.5 run-time ratio, priority 3. No old-version guessed config keys.

• A missing desktop AWT component in the local headless JRE initially caused a DH cloud-texture error. Installing the complete Java 25 runtime resolved it; this was an environment issue, not a packaged mod change.

• Native libraries are chosen by OS and architecture, including ARM64 selection when the official manifest has OS-only rules. Builds use portable / ZIP paths on Windows too.

• The official Prism 11.1.1 macOS ZIP was downloaded, SHA-256 verified, and its actual app layout checked. Its launcher executable is a universal Mach-O containing x86_64 and arm64. The starter does not redistribute it or disable macOS security checks.

• Dedicated-server optimized dependencies and original mod initialize with the real server game JAR; EULA-false startup exits as expected. No license acceptance is made on the user's behalf. Integrated-server gameplay is a separate client check.

• The original recorder loads with the vanilla renderer and F8 starts/stops it during actual demo gameplay. A persistent virtual keyboard is needed on this headless compositor: removing the last temporary keyboard otherwise removes window focus and auto-pauses the game. This is a test harness detail, not a change to pause behavior or focus exclusions.

• That runtime check wrote both raw CSV/JSON pairs, containing 69 actual frame intervals and 744 actual integrated-server tick durations. GPU/backend/driver and render settings were captured. The comparison tool successfully reads these real report files. This short, cold, software-rendered run validates capture/output only; it is not a performance baseline to compare with a real Mac.

• Build/metrics/pack tests pass on actual hosted Apple Silicon macOS 26, Windows x64 and Linux x64 runners. The Windows run exposed an existing decompilation-coverage path separator mismatch; paths are now normalized to match JAR SourceFile metadata.

• 17 offline Python tests cover corrupt/cached artifacts, server extraction/traversal rejection, decompilation inventory, publication exclusions, dependency closure, safe download paths, pack format, OS/ARM native selection, and comparison mismatches.

• Original Java metrics tests cover percentiles, the average of the slowest 1% (not the reciprocal of p99), stall boundaries, bounded samples/overflow, filename sanitization, exclusions and player counts.

• Existing three Rust differential tests, formatting and Clippy checks pass. Rust kernels remain unintegrated.

• The exact published balanced pack was then re-run through real demo world rendering, with its published original mod binary checked byte-for-byte against the runtime. F8 produced nonempty frame/tick JSON and matching raw CSV; each reported sample count and mean duration were checked against the CSV.

Interpretation limits

Generated pack options now carry data version 5023, verified against version.json inside the checksum-verified Minecraft 26.3 JAR. Without this marker, the game's legacy-options migration reset the intended backend to Default. The fixed Vulkan preference starts the actual Vulkan backend with the pinned Sodium/DH/ImmediatelyFast stack, renders the demo world, and records 256 frame intervals / 2,372 server ticks over 120 seconds with matching CSV/JSON and 119–121 RSS samples. The frame report identifies Vulkan and its driver. DH data continues updating and saves/databases close cleanly. With an unavailable Vulkan driver path confined to a separate test process, the game reports backend creation failure and reaches the menu using its OpenGL fallback. These checks do not establish Vulkan speed, distant-LOD visual correctness, shader compatibility, or behavior on the user's Mac. Balanced remains the OpenGL first test; Vulkan remains an optional independent comparison.

The 0.7.0 optional debounce queue hook initializes and renders with the combined adaptive/pacing controls. The exact candidate JAR wrote 643 frame intervals and 2,408 server-tick samples over 120 seconds; CSV counts and means match the reports, which capture all three controls as enabled and include resident-memory samples. Thread inspection reached the injected debounce parking path, DH terrain data continued updating, and worlds/databases/workers closed cleanly. The actual publisher queue microbenchmark passes identity/priority/count checks on Linux, Windows and Apple Silicon macOS; its raw results and timing overshoot are documented in the queue experiment. These are separate from game-FPS, block-update-latency or RAM-reduction claims. All eleven pack overrides retain simulation distance 12 and explicitly set the intended experimental flags.

The 0.6.0 resident-memory sampler ran in the actual adaptive-pacing demo world. A 120-second recording produced 370 frame intervals and 2,407 server-tick samples; both CSV counts and mean durations match their JSON summaries. Each report has 120 successful RSS samples, a peak of about 2,643 MiB, and a last-sample age under 800 ms. The runtime JAR matches the release candidate byte-for-byte. After capture, the sampler thread waits without further scheduled reads. Native-read tests also pass on hosted Windows x64, Linux x64 and Apple Silicon macOS 26; unsupported reader behavior preserves timing samples and omits unavailable RSS fields. These numbers validate reporting in this particular software-rendered workload, not a RAM reduction or a prediction of the user's Mac memory use.

The 0.5.0 offline viewer passed Chromium checks using real frame/tick JSON and CSV files, charts, exports, malformed inputs, kind mismatches, escaped profile labels, and mobile layout. It is self-contained and has no network dependencies. Its game runtime classes are identical to 0.4.0, apart from mod version metadata.

The 0.4.0 worker-pacing hook also renders the demo world with the complete mod stack. Both pacing and adaptive controls are captured as enabled in the final build's 120-second frame report. It produced 359 frame intervals and 2,401 integrated-server tick samples, verified against raw CSV counts and heap/resource fields. The DH database received terrain-data updates during this run. The earlier hook build saved/quitted and closed its databases/workers cleanly. Hosted executor benchmarks pass on Linux, Windows and Apple Silicon macOS; their results remain separate from game-performance claims. The revised policy tests include 1 ms and 15 ms timer overshoot and bounded credit after long stalls.

The 0.3.0 adaptive profile rendered the actual demo world and applied live DH duty-cycle changes from 0.5 down to 0.05 under software-renderer frame pressure. Opening the pause menu released the override and reported an effective ratio of 0.5 again. A separate baseline instance starts without DH. API adapter tests cover suspension/resumption, changed user ceilings, and yielding to an existing or changed override from another mod. The real recorder wrote 193 frame intervals and 1,651 integrated-server tick samples, with matching CSV counts, sampled heap peaks and process CPU data. Dedicated-server 0.3.0 dependencies initialize and exit with EULA false. No populated server result is inferred. The updated offline suite has 19 Python tests, including upgrade backups and refusing to replace an unrelated JAR with a matching filename.

A 60-second JFR recording identified foreground, server and DH worker activity. It also demonstrated why allocation sampling must be corroborated: large sample weights at timestamp boxing did not correspond to the largest per-thread allocation counter deltas. Profiles stay private under .local/; neither sample weights nor this software-renderer workload establish a real-hardware optimization result.

The local Linux host uses Mesa llvmpipe software rendering. It is useful for mod/mixin/startup/report validation, not for predicting M2 Pro, Windows GPU or Linux discrete-GPU performance. Warm-up/world loading on this host is slow. Demo credentials produce expected unavailable account-properties/Realms logs, and chat availability can be restricted; the independent F8 measurement shortcut avoids relying on chat.

CI compiles/builds on Linux, Windows and Apple Silicon macOS. Successful compilation is not graphics, authentication, UI or Mac-driver runtime validation. macOS 27 and the user's actual M2 Pro have not been tested here. Optional cinematic shaders and Vulkan are experiments; the OpenGL balanced pack is the first manual test.

No numerical game speedup, least-memory claim, exhaustive vanilla equivalence, universal GPU support, or 50-active-player result is claimed. Worlds need copies, repeated matched routes and real hardware measurements before decisions about deeper replacements. New terrain generation and steady-state rendering are separate workloads.

Release content

Packs embed only the original MIT Horizon Lab JAR and config. Mod/game/library downloads retain upstream licenses and are checked against pinned hashes. No game JAR, class, decompiled source, asset, world or credential is committed or uploaded in a starter. The narrow publication allowance is for original Java under dev/horizonlab, and the built JAR checks its emitted class namespace.