code wiki / (root) / nx_perf_pct_gate.nx

nx_perf_pct_gate.nx

buildroot/runtime/nx_perf_pct_gate.nx

12827 B191 linesdepth 3pulls 5 transitivereach 0 importersview sourcekind gate/prooftopic perf
docsdependenciesstructsconstsfunctions

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

nx_syscalls.nx nx_gate_verdict.nx nx_perf_lib.nx nx_perf_pct_gate.nx

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

main gv_ctr sys_mmap nxa_die sys_write sys_exit nxa_lock_take nxa_lock_addr sys_write ↻ nxa_lock_give nxa_lock_addr ↻ nxa_report_overrun sys_write ↻ nxa_dump_printable sys_write ↻ nxa_dump_sizes sys_write ↻ gv_puts sys_write ↻ ft_percentile_kat kp_region sys_mmap ↻ pf_words pf_init kp_push_ramp pf_push pf_push_raw pf_valid pf_init ↻ gv_check_eq gv_check gv_puts ↻ gv_puts ↻ gv_num sys_mmap ↻ sys_write ↻ sys_munmap pf_n pf_pct pf_hist

structs

none

consts

26const KP_RAMP_N: i64 = 100 // 1..100: rank arithmetic reads straight off the value
27const KP_OUTLIER_N: i64 = 99 // 99 common frames beside ONE outlier: p99 must not be the outlier
28const KP_COMMON_MS: i64 = 10
29const KP_OUTLIER_MS: i64 = 500
30const KP_OVER_CLAMP_MS: i64 = 5000 // above PF_CLAMP_MS: recorded AT the clamp, counted as worst
31const KP_WINDOW_EXTRA: i64 = 5 // pushes past the window: the oldest KP_WINDOW_EXTRA must be gone
32const KP_SPIKE_BASE_N: i64 = 9 // 9 x common + 1 spike: median x PF_SPIKE_MULT is the jank bar
33const KP_SPIKE_MS: i64 = 50
34const KP_TINY_N: i64 = 3 // {1,2,3}: the ceil at the rank boundary is visible by hand
35const KP_BUDGET_MS: i64 = 16 // a 60 Hz budget for the pushes; the referee teeth pick their own
36const KP_REF_MIN_N: i64 = 10
40const KP_REF_COMMON_N: i64 = 98
41const KP_REF_OUTLIER_N: i64 = 2
42const KP_PERMIL_P1: i64 = 10
43const KP_PERMIL_P50: i64 = 500
44const KP_PERMIL_P95: i64 = 950
45const KP_PERMIL_P99: i64 = 990
46const KP_PERMIL_P100: i64 = 1000
47const KP_I64_BYTES: i64 = 8
49const KP_KAT_TEETH: i64 = 16

functions

51func kp_region() -> *i64
56func kp_push_n(r: *i64, n: i64, ms: i64) -> i64
called by 2: ft_percentile_katmain calls 1: pf_push
61func kp_push_ramp(r: *i64, n: i64) -> i64
called by 2: ft_percentile_katmain calls 1: pf_push
70func ft_percentile_kat(ctr: *i64) -> i64
106func main() -> i64