nx_perf_pct_gate.nx source

1// nx_perf_pct_gate.nx -- KNOWN-ANSWER GATE for the frame-time percentile arithmetic the served page 2// publishes (gameengine GE50, symbol ft_percentile_kat). 3// 4// WHY THIS GATE EXISTS, from a mirrored primary source rather than a hunch: the industry's reference 5// frame-time instrument, Intel PresentMon, records in its own v2.5.0 release notes (2026-06-29) that its 6// percentile calculation was WRONG and that 99 percent was effectively reporting MAX. A percentile that 7// quietly degenerates to the maximum turns every p99 claim into a worst-frame claim, and nobody can tell 8// from the number. Our p50 p95 p99 are computed by nx_perf_lib (pf_pct) inside the wasm engine and 9// beaconed by the page, and until this file they had NEVER been checked against a sequence whose 10// percentiles are known by construction. The lib's own header carries the claim "p50 of 1..100 is 50, 11// p99 is 99, p100 is 100" as PROSE; this gate makes it a TOOTH. 12// 13// METHOD UNDER TEST (nx_perf_lib.nx): nearest-rank over a 0..PF_CLAMP_MS integer-ms histogram, 14// rank = ceil(permil x n / 1000), clamped to [1, n]; an empty window answers PF_UNOBSERVED. 15// Every expected value below is DERIVED from that definition and printed with gv_check_eq, so the number 16// tested and the number published cannot drift apart. The decisive tooth is the neg-control: a window of 17// 99 identical frames and ONE outlier has p99 == the common value and worst == the outlier; an 18// implementation with PresentMon's defect returns the outlier for p99 and FAILS here. 19// In-process (imports the lib): a gate that forked the wasm would prove the module, this proves the ruler. 20// license_tier: ORIGINAL No hw writes (Rule 26). 21import "nx_syscalls.nx" 22import "nx_gate_verdict.nx" 23import "nx_perf_lib.nx" 24 25// KAT fixtures, each named for what it isolates. Sizes are fixture facts, not tunables. 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 37// The referee fixture: p50 and p95 must FIT while p99 does NOT. With nearest-rank over 100 samples, p99 is the 38// 99th smallest, so ONE outlier never reaches it (that is exactly the neg-control above) -- TWO do, while p95 39// (the 95th smallest) still reads the common value. Derived from the definition, not tuned. 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 48// teeth the KAT function runs; asserted by main so a tooth that silently stops running lowers the count 49const KP_KAT_TEETH: i64 = 16 50 51func kp_region() -> *i64 { 52 let r: *i64 = sys_mmap(pf_words() * KP_I64_BYTES) as *i64 53 pf_init(r) 54 return r 55} 56func kp_push_n(r: *i64, n: i64, ms: i64) -> i64 { 57 var i: i64 = 0 58 while i < n { pf_push(r, ms, KP_BUDGET_MS); i = i + 1 } 59 return n 60} 61func kp_push_ramp(r: *i64, n: i64) -> i64 { 62 var i: i64 = 1 63 while i <= n { pf_push(r, i, KP_BUDGET_MS); i = i + 1 } 64 return n 65} 66 67// THE SYMBOL THE BOARD WATCHES (gameengine GE50, ft_percentile_kat): the known-answer teeth over pf_pct. 68// A watch that keys on a name rewards writing the name, so this function IS the capability -- it runs the 69// teeth and returns their count -- never a stub that exists to flip a cell. 70func ft_percentile_kat(ctr: *i64) -> i64 { 71 // ---- the lib's own documented claim, as teeth -------------------------------------------- 72 let ramp: *i64 = kp_region() 73 kp_push_ramp(ramp, KP_RAMP_N) 74 gv_check_eq("fixture-reached-the-window-holds-the-ramp (n)" as *u8, pf_n(ramp), KP_RAMP_N, ctr) 75 gv_check_eq("p50-of-1..100-is-50 (rank ceil(0.5x100)=50)" as *u8, pf_pct(ramp, KP_PERMIL_P50), 50, ctr) 76 gv_check_eq("p95-of-1..100-is-95 (rank ceil(0.95x100)=95)" as *u8, pf_pct(ramp, KP_PERMIL_P95), 95, ctr) 77 gv_check_eq("p99-of-1..100-is-99 (rank ceil(0.99x100)=99, NOT the max)" as *u8, pf_pct(ramp, KP_PERMIL_P99), 99, ctr) 78 gv_check_eq("p100-of-1..100-is-100 (rank n is the max, legitimately)" as *u8, pf_pct(ramp, KP_PERMIL_P100), 100, ctr) 79 gv_check_eq("worst-is-p100 (pf_worst composes pf_pct at PF_PERMIL)" as *u8, pf_worst(ramp), 100, ctr) 80 81 // ---- THE DECISIVE NEG-CONTROL: PresentMon's defect must fail here ---------------------------- 82 let out: *i64 = kp_region() 83 kp_push_n(out, KP_OUTLIER_N, KP_COMMON_MS) 84 pf_push(out, KP_OUTLIER_MS, KP_BUDGET_MS) 85 gv_check_eq("fixture-reached-99-common-plus-one-outlier (n)" as *u8, pf_n(out), KP_OUTLIER_N + 1, ctr) 86 gv_check_eq("neg-control-p99-is-NOT-the-lone-outlier (rank 99 of 100 lands on the common value)" as *u8, pf_pct(out, KP_PERMIL_P99), KP_COMMON_MS, ctr) 87 gv_check_eq("positive-control-worst-IS-the-outlier (so the outlier was really in the window)" as *u8, pf_worst_ever(out), KP_OUTLIER_MS, ctr) 88 gv_check_eq("positive-control-p100-IS-the-outlier (rank n reaches it; only p100 may equal max here)" as *u8, pf_pct(out, KP_PERMIL_P100), KP_OUTLIER_MS, ctr) 89 90 // ---- the rank boundary by hand on a tiny window -------------------------------------------- 91 let tiny: *i64 = kp_region() 92 kp_push_ramp(tiny, KP_TINY_N) 93 gv_check_eq("tiny-p1-rank-ceil(0.03)-clamps-to-1 -> 1" as *u8, pf_pct(tiny, KP_PERMIL_P1), 1, ctr) 94 gv_check_eq("tiny-p50-rank-ceil(1.5)=2 -> 2" as *u8, pf_pct(tiny, KP_PERMIL_P50), 2, ctr) 95 gv_check_eq("tiny-p99-rank-ceil(2.97)=3 -> 3" as *u8, pf_pct(tiny, KP_PERMIL_P99), 3, ctr) 96 97 // ---- an empty window ABSTAINS: a percentile that reads 0 frames as 0 ms would pass on the empty set 98 let empty: *i64 = kp_region() 99 gv_check_eq("neg-control-empty-window-p50-is-UNOBSERVED-not-0" as *u8, pf_pct(empty, KP_PERMIL_P50), PF_UNOBSERVED, ctr) 100 gv_check_eq("neg-control-empty-window-worst_ever-is-UNOBSERVED" as *u8, pf_worst_ever(empty), PF_UNOBSERVED, ctr) 101 gv_check_eq("neg-control-empty-window-spikes-is-UNOBSERVED" as *u8, pf_spikes(empty), PF_UNOBSERVED, ctr) 102 103 return KP_KAT_TEETH 104} 105 106func main() -> i64 { 107 let ctr: *i64 = gv_ctr() 108 gv_puts("nx_perf_pct_gate -- the percentile ruler the page beacons, checked against known answers\n\n" as *u8) 109 110 let kat_teeth: i64 = ft_percentile_kat(ctr) 111 gv_check_eq("fixture-reached-the-percentile-KAT-ran-every-declared-tooth" as *u8, kat_teeth, KP_KAT_TEETH, ctr) 112 // the referee tooth below needs the outlier window again: rebuilt deterministically, not shared 113 let out: *i64 = kp_region() 114 kp_push_n(out, KP_OUTLIER_N, KP_COMMON_MS) 115 pf_push(out, KP_OUTLIER_MS, KP_BUDGET_MS) 116 let ramp: *i64 = kp_region() 117 kp_push_ramp(ramp, KP_RAMP_N) 118 119 // ---- the clamp: an absurd frame is recorded AT the clamp and still counted as worst ---------- 120 let cl: *i64 = kp_region() 121 pf_push(cl, KP_COMMON_MS, KP_BUDGET_MS) 122 pf_push(cl, KP_OVER_CLAMP_MS, KP_BUDGET_MS) 123 gv_check_eq("over-clamp-frame-is-recorded-AT-the-clamp (pf_sample)" as *u8, pf_sample(cl, 1), pf_clamp_ms(), ctr) 124 gv_check_eq("over-clamp-frame-still-counts-as-worst_ever" as *u8, pf_worst_ever(cl), pf_clamp_ms(), ctr) 125 gv_check_eq("over-clamp-frame-still-counts-as-over-budget (pf_over)" as *u8, pf_over(cl), 1, ctr) 126 127 // ---- the window is a ring: pushes past PF_N evict the oldest, cumulative counters do not forget 128 let win: *i64 = kp_region() 129 let total: i64 = pf_window() + KP_WINDOW_EXTRA 130 kp_push_ramp(win, total) 131 gv_check_eq("window-count-caps-at-PF_N" as *u8, pf_n(win), pf_window(), ctr) 132 gv_check_eq("cumulative-total-remembers-every-push (a ring reports the recent, the counter the worst)" as *u8, pf_total(win), total, ctr) 133 gv_check_eq("oldest-surviving-sample-is-the-(KP_WINDOW_EXTRA+1)th-push" as *u8, pf_sample(win, 0), KP_WINDOW_EXTRA + 1, ctr) 134 gv_check_eq("newest-sample-is-the-last-push" as *u8, pf_sample(win, pf_window() - 1), total, ctr) 135 gv_check_eq("sample-past-the-count-is-UNOBSERVED" as *u8, pf_sample(win, pf_window()), PF_UNOBSERVED, ctr) 136 137 // ---- jank: frames above PF_SPIKE_MULT x median ------------------------------------------------ 138 let sp: *i64 = kp_region() 139 kp_push_n(sp, KP_SPIKE_BASE_N, KP_COMMON_MS) 140 pf_push(sp, KP_SPIKE_MS, KP_BUDGET_MS) 141 gv_check_eq("spike-count-is-one (50 > 2 x median 10)" as *u8, pf_spikes(sp), 1, ctr) 142 gv_check_eq("spike-permil-is-100 (1 of 10)" as *u8, pf_spikes_permil(sp), 100, ctr) 143 144 // ---- the referee is three-state and NAMES its failing conjunct --------------------------------- 145 let why: *i64 = sys_mmap(KP_I64_BYTES) as *i64 146 let few: *i64 = kp_region() 147 kp_push_n(few, KP_REF_MIN_N - 1, KP_COMMON_MS) 148 gv_check_eq("neg-control-referee-ABSTAINS-below-min_n (never acquits on the empty-ish set)" as *u8, pf_referee(few, KP_BUDGET_MS, KP_REF_MIN_N, 1000, 1000, 1000, 1000, why), PF_ABSTAIN, ctr) 149 // p50 and p95 fit the budget, p99 does not: the conjunct index must read 3 150 let ref: *i64 = kp_region() 151 kp_push_n(ref, KP_REF_COMMON_N, KP_COMMON_MS) 152 kp_push_n(ref, KP_REF_OUTLIER_N, KP_OUTLIER_MS) 153 gv_check_eq("fixture-reached-p95-fits-and-p99-overspends (p95 reads the common value)" as *u8, pf_pct(ref, KP_PERMIL_P95), KP_COMMON_MS, ctr) 154 gv_check_eq("fixture-reached-p99-is-the-outlier-with-two-of-them" as *u8, pf_pct(ref, KP_PERMIL_P99), KP_OUTLIER_MS, ctr) 155 let v: i64 = pf_referee(ref, KP_BUDGET_MS, KP_REF_MIN_N, 1000, 1000, 1000, 1000, why) 156 gv_check_eq("referee-RED-when-only-p99-overspends" as *u8, v, PF_RED, ctr) 157 gv_check_eq("referee-NAMES-the-p99-conjunct (why=3, never a guess between three)" as *u8, why[0], 3, ctr) 158 gv_check_eq("referee-GREEN-on-the-ramp-at-a-generous-budget" as *u8, pf_referee(ramp, 200, KP_REF_MIN_N, 1000, 1000, 1000, 1000, why), PF_GREEN, ctr) 159 160 // ---- the ABSOLUTE long-frame axis from the LoAF standard: 50 ms counts, 49 does not ---------- 161 let lf: *i64 = kp_region() 162 pf_push(lf, PF_LONG_FRAME_MS - 1, KP_BUDGET_MS) 163 pf_push(lf, PF_LONG_FRAME_MS, KP_BUDGET_MS) 164 pf_push(lf, PF_LONG_FRAME_MS + 1, KP_BUDGET_MS) 165 gv_check_eq("long-frames-count-at-and-over-50ms-not-under (LoAF: duration reaches 50 ms)" as *u8, pf_long(lf), 2, ctr) 166 let lfe: *i64 = kp_region() 167 gv_check_eq("neg-control-empty-window-long-frames-is-UNOBSERVED" as *u8, pf_long(lfe), PF_UNOBSERVED, ctr) 168 gv_check_eq("long-frame-bar-is-the-standard's-50ms (the const is data the gate reads, not a literal it repeats)" as *u8, PF_LONG_FRAME_MS, 50, ctr) 169 // Raw timing preserves both tail values; p99 must not collapse to either the cap or maximum. 170 let raw: *i64 = kp_region() 171 kp_push_n(raw, KP_REF_COMMON_N, KP_COMMON_MS) 172 pf_push_raw(raw, KP_OVER_CLAMP_MS, KP_BUDGET_MS) 173 pf_push_raw(raw, 1000000000, KP_BUDGET_MS) 174 gv_check_eq("raw-ring-retains-5000ms" as *u8, pf_sample(raw, KP_REF_COMMON_N), KP_OVER_CLAMP_MS, ctr) 175 gv_check_eq("raw-p95-stays-common" as *u8, pf_pct(raw, KP_PERMIL_P95), KP_COMMON_MS, ctr) 176 gv_check_eq("raw-p99-is-5000-not-cap-or-max" as *u8, pf_pct(raw, KP_PERMIL_P99), KP_OVER_CLAMP_MS, ctr) 177 gv_check_eq("raw-worst-retains-long-suspend" as *u8, pf_worst(raw), 1000000000, ctr) 178 gv_check_eq("raw-worst-ever-retains-long-suspend" as *u8, pf_worst_ever(raw), 1000000000, ctr) 179 kp_push_n(raw, pf_window(), KP_COMMON_MS) 180 gv_check_eq("raw-tail-eviction-restores-window-percentile" as *u8, pf_worst(raw), KP_COMMON_MS, ctr) 181 gv_check_eq("raw-tail-eviction-retains-lifetime-worst" as *u8, pf_worst_ever(raw), 1000000000, ctr) 182 gv_values_head() 183 gv_kv("ramp_p50" as *u8, pf_pct(ramp, KP_PERMIL_P50)) 184 gv_kv("ramp_p95" as *u8, pf_pct(ramp, KP_PERMIL_P95)) 185 gv_kv("ramp_p99" as *u8, pf_pct(ramp, KP_PERMIL_P99)) 186 gv_kv("outlier_p99" as *u8, pf_pct(out, KP_PERMIL_P99)) 187 gv_kv("outlier_worst" as *u8, pf_worst_ever(out)) 188 gv_kv("window" as *u8, pf_window()) 189 gv_kv("clamp_ms" as *u8, pf_clamp_ms()) 190 return gv_verdict("nx_perf_pct_gate" as *u8, ctr, "nearest-rank over integer-ms bins, every expected value derived from the definition and printed beside the actual; an implementation whose p99 degenerates to the maximum cannot pass" as *u8) 191}