nx_perf_pct_gate.nx
buildroot/runtime/nx_perf_pct_gate.nx
about
nx_perf_pct_gate.nx -- KNOWN-ANSWER GATE for the frame-time percentile arithmetic the served page
publishes (gameengine GE50, symbol ft_percentile_kat).
WHY THIS GATE EXISTS, from a mirrored primary source rather than a hunch: the industry's reference
frame-time instrument, Intel PresentMon, records in its own v2.5.0 release notes (2026-06-29) that its
percentile calculation was WRONG and that 99 percent was effectively reporting MAX. A percentile that
quietly degenerates to the maximum turns every p99 claim into a worst-frame claim, and nobody can tell
from the number. Our p50 p95 p99 are computed by nx_perf_lib (pf_pct) inside the wasm engine and
beaconed by the page, and until this file they had NEVER been checked against a sequence whose
percentiles are known by construction. The lib's own header carries the claim "p50 of 1..100 is 50,
p99 is 99, p100 is 100" as PROSE; this gate makes it a TOOTH.
METHOD UNDER TEST (nx_perf_lib.nx): nearest-rank over a 0..PF_CLAMP_MS integer-ms histogram,
rank = ceil(permil x n / 1000), clamped to [1, n]; an empty window answers PF_UNOBSERVED.
Every expected value below is DERIVED from that definition and printed with gv_check_eq, so the number
tested and the number published cannot drift apart. The decisive tooth is the neg-control: a window of
99 identical frames and ONE outlier has p99 == the common value and worst == the outlier; an
implementation with PresentMon's defect returns the outlier for p99 and FAILS here.
In-process (imports the lib): a gate that forked the wasm would prove the module, this proves the ruler.
license_tier: ORIGINAL No hw writes (Rule 26).
dependencies 3 imports · 0 importers
imports: nx_syscalls.nxnx_gate_verdict.nxnx_perf_lib.nx
imported by: nobody (leaf or entry point)
call flow from main pre-order; caps 40 nodes / depth 6 declared; ↻ = already shown
structs
| none |
consts
| 26 | const KP_RAMP_N: i64 = 100 // 1..100: rank arithmetic reads straight off the value |
| 27 | const KP_OUTLIER_N: i64 = 99 // 99 common frames beside ONE outlier: p99 must not be the outlier |
| 28 | const KP_COMMON_MS: i64 = 10 |
| 29 | const KP_OUTLIER_MS: i64 = 500 |
| 30 | const KP_OVER_CLAMP_MS: i64 = 5000 // above PF_CLAMP_MS: recorded AT the clamp, counted as worst |
| 31 | const KP_WINDOW_EXTRA: i64 = 5 // pushes past the window: the oldest KP_WINDOW_EXTRA must be gone |
| 32 | const KP_SPIKE_BASE_N: i64 = 9 // 9 x common + 1 spike: median x PF_SPIKE_MULT is the jank bar |
| 33 | const KP_SPIKE_MS: i64 = 50 |
| 34 | const KP_TINY_N: i64 = 3 // {1,2,3}: the ceil at the rank boundary is visible by hand |
| 35 | const KP_BUDGET_MS: i64 = 16 // a 60 Hz budget for the pushes; the referee teeth pick their own |
| 36 | const KP_REF_MIN_N: i64 = 10 |
| 40 | const KP_REF_COMMON_N: i64 = 98 |
| 41 | const KP_REF_OUTLIER_N: i64 = 2 |
| 42 | const KP_PERMIL_P1: i64 = 10 |
| 43 | const KP_PERMIL_P50: i64 = 500 |
| 44 | const KP_PERMIL_P95: i64 = 950 |
| 45 | const KP_PERMIL_P99: i64 = 990 |
| 46 | const KP_PERMIL_P100: i64 = 1000 |
| 47 | const KP_I64_BYTES: i64 = 8 |
| 49 | const KP_KAT_TEETH: i64 = 16 |
functions
| 51 | func kp_region() -> *i64 |
| 56 | func kp_push_n(r: *i64, n: i64, ms: i64) -> i64 |
| 61 | func kp_push_ramp(r: *i64, n: i64) -> i64 |
| 70 | func ft_percentile_kat(ctr: *i64) -> i64 |
| 106 | func main() -> i64 |