nx_frame_pacing_gate.nx source
↩ module page · 185 lines · 11580 B
1// nx_frame_pacing_gate.nx -- THE PACING REFEREE (gameengine GE15 pf_referee + GE32 perf_frame, 2026-09-02).
2//
3// Two subjects in one gate, both through nx_perf_lib (the ONE frame-budget ruler the wasm engine, the served HUD,
4// the telemetry sink and this gate all share):
5// (1) the RULER: nearest-rank percentiles, spike count, worst-ever and over-budget counters, the ring window, the
6// clamp and the self-heal -- exact fixtures whose answers are arithmetic, plus a referee over synthetic traces
7// with a planted stall (the anti-vacuity tooth: a referee that passes the stall is not a referee).
8// (2) the LIVE WINDOW: the latest frametrace- plane row for the beach world (written by nx_world_telemetry from a
9// real visitor's beacon) judged against knowledge/frame_pacing.conf -- a NAMED SKIP through gv_need when either
10// is absent, never a green. The plane is read through nx_frame_pacing_lib (fpc_plane_latest / fpc_row_frames),
11// the same reader the sink's peers use; no file format of its own.
12// Bands are conf rows, never literals here. license_tier: ORIGINAL No hw writes (Rule 26). expect_exit: 0
13import "nx_gate_verdict.nx"
14import "nx_frame_pacing_lib.nx"
15
16const FP_WORLD: *u8 = "beach"
17const FP_WORLD_N: i64 = 5
18const FP_REGION_BYTES: i64 = 10120 // PF_WORDS x 8 = 1265 x 8
19const FP_ROW_CAP: i64 = 8192
20const FP_SUBJECTS: i64 = 1 // live windows judged
21// fixture shapes (named, not bare)
22const FP_FIX_STEADY_MS: i64 = 10
23const FP_FIX_STEADY_N: i64 = 100
24const FP_FIX_STALL_MS: i64 = 40
25const FP_FIX_STALL_N: i64 = 10
26const FP_FIX_BUDGET_MS: i64 = 24
27const FP_FIX_RAMP_N: i64 = 100
28const FP_FIX_WRAP_N: i64 = 300
29const FP_FIX_WRAP_MOD: i64 = 50
30const FP_FIX_HUGE_MS: i64 = 5000
31const FP_FIX_GARBAGE: i64 = 999999
32const FP_TRACE_60HZ_MS: i64 = 16
33const FP_TRACE_N: i64 = 600
34const FP_TRACE_STALL_EVERY: i64 = 10
35const FP_TRACE_SHORT_N: i64 = 30
36const FP_60: i64 = 60
37const FP_30: i64 = 30
38const FP_BUDGET_60_MS: i64 = 16
39const FP_BUDGET_30_MS: i64 = 33
40const FP_CSV_FIX_N: i64 = 5
41const FP_SHORT_ROW: i64 = 20
42
43func fp_region() -> *i64 { return sys_mmap(FP_REGION_BYTES) as *i64 }
44
45func main(argc: i64, argv: *i64) -> i64 {
46 gv_head("nx_frame_pacing_gate -- frame-budget statistics in one sovereign ruler, and the pacing referee over the live plane window" as *u8)
47 let ctr: *i64 = gv_ctr()
48 gv_subjects("live frame windows judged against the conf bands" as *u8, FP_SUBJECTS, ctr)
49 let why: *i64 = sys_mmap(16) as *i64
50
51 // (1a) the empty window abstains
52 let r0: *i64 = fp_region()
53 pf_init(r0)
54 gv_check("empty-window-count-is-zero" as *u8, pf_n(r0) == 0, ctr)
55 gv_check("neg-control-empty-window-p50-is-UNOBSERVED-not-0" as *u8, pf_pct(r0, 500) == PF_UNOBSERVED, ctr)
56 gv_check("neg-control-empty-window-spikes-is-UNOBSERVED-not-0" as *u8, pf_spikes(r0) == PF_UNOBSERVED, ctr)
57 gv_check("neg-control-empty-window-worst-ever-is-UNOBSERVED" as *u8, pf_worst_ever(r0) == PF_UNOBSERVED, ctr)
58 gv_check("referee-abstains-on-the-empty-window" as *u8, pf_referee(r0, FP_FIX_BUDGET_MS, 1, 1000, 1200, 2000, 50, why) == PF_ABSTAIN, ctr)
59
60 // (1b) steady frames plus stalls: exact statistics
61 var i: i64 = 0
62 while i < FP_FIX_STEADY_N { pf_push(r0, FP_FIX_STEADY_MS, FP_FIX_BUDGET_MS); i = i + 1 }
63 i = 0
64 while i < FP_FIX_STALL_N { pf_push(r0, FP_FIX_STALL_MS, FP_FIX_BUDGET_MS); i = i + 1 }
65 gv_check("fixture-reached-condition-110-frames-in-window" as *u8, pf_n(r0) == FP_FIX_STEADY_N + FP_FIX_STALL_N, ctr)
66 gv_check("p50-of-100x10-plus-10x40-is-10" as *u8, pf_pct(r0, 500) == FP_FIX_STEADY_MS, ctr)
67 gv_check("p95-of-100x10-plus-10x40-is-40" as *u8, pf_pct(r0, 950) == FP_FIX_STALL_MS, ctr)
68 gv_check("p99-of-100x10-plus-10x40-is-40" as *u8, pf_pct(r0, 990) == FP_FIX_STALL_MS, ctr)
69 gv_check("worst-in-window-is-40" as *u8, pf_worst(r0) == FP_FIX_STALL_MS, ctr)
70 gv_check("spikes-count-the-10-stalls-above-2x-median" as *u8, pf_spikes(r0) == FP_FIX_STALL_N, ctr)
71 gv_check("over-budget-counts-the-10-frames-above-24ms" as *u8, pf_over(r0) == FP_FIX_STALL_N, ctr)
72 gv_check("mean-x10-is-127-tenths" as *u8, pf_mean_x10(r0) == (FP_FIX_STEADY_N*FP_FIX_STEADY_MS + FP_FIX_STALL_N*FP_FIX_STALL_MS)*10/(FP_FIX_STEADY_N + FP_FIX_STALL_N), ctr)
73 gv_check("referee-RED-on-the-stalls-naming-the-p95-conjunct" as *u8, pf_referee(r0, FP_FIX_BUDGET_MS, 1, 1000, 1200, 2000, 50, why) == PF_RED, ctr)
74 gv_check("referee-names-which-conjunct-failed" as *u8, why[0] == 2, ctr)
75
76 // (1c) exact percentiles on a ramp 1..100
77 let r1: *i64 = fp_region()
78 pf_init(r1)
79 i = 1
80 while i <= FP_FIX_RAMP_N { pf_push(r1, i, 0); i = i + 1 }
81 gv_check("ramp-p50-is-50" as *u8, pf_pct(r1, 500) == 50, ctr)
82 gv_check("ramp-p95-is-95" as *u8, pf_pct(r1, 950) == 95, ctr)
83 gv_check("ramp-p99-is-99" as *u8, pf_pct(r1, 990) == 99, ctr)
84 gv_check("ramp-worst-is-100" as *u8, pf_worst(r1) == FP_FIX_RAMP_N, ctr)
85 gv_check("ramp-oldest-sample-is-1" as *u8, pf_sample(r1, 0) == 1, ctr)
86 gv_check("ramp-sample-past-count-is-UNOBSERVED" as *u8, pf_sample(r1, FP_FIX_RAMP_N) == PF_UNOBSERVED, ctr)
87 gv_check("zero-budget-counts-nothing-over" as *u8, pf_over(r1) == 0, ctr)
88
89 // (1d) the window wraps, the cumulative counters do not
90 let r2: *i64 = fp_region()
91 pf_init(r2)
92 i = 0
93 while i < FP_FIX_WRAP_N { pf_push(r2, i % FP_FIX_WRAP_MOD, 0); i = i + 1 }
94 gv_check("window-holds-exactly-PF_N-after-300-pushes" as *u8, pf_n(r2) == pf_window(), ctr)
95 gv_check("total-counts-every-push-past-the-window" as *u8, pf_total(r2) == FP_FIX_WRAP_N, ctr)
96 gv_check("oldest-sample-after-wrap-is-push-44" as *u8, pf_sample(r2, 0) == (FP_FIX_WRAP_N - pf_window()) % FP_FIX_WRAP_MOD, ctr)
97 gv_check("worst-ever-is-49-across-the-whole-run" as *u8, pf_worst_ever(r2) == FP_FIX_WRAP_MOD - 1, ctr)
98
99 // (1e) clamp and self-heal
100 pf_push(r2, FP_FIX_HUGE_MS, 0)
101 gv_check("a-5000ms-frame-is-recorded-at-the-1000ms-clamp" as *u8, pf_worst_ever(r2) == pf_clamp_ms(), ctr)
102 let r3: *i64 = fp_region()
103 r3[0] = FP_FIX_GARBAGE
104 r3[1] = FP_FIX_GARBAGE
105 pf_push(r3, FP_FIX_STEADY_MS, 0)
106 gv_check("neg-control-garbage-header-self-heals-to-one-sample" as *u8, pf_n(r3) == 1, ctr)
107 gv_check("self-healed-total-restarts-at-one" as *u8, pf_total(r3) == 1, ctr)
108
109 // (1f) the budget half composes nx_frame_budget
110 gv_check("budget-ms-for-60Hz-composes-fb_budget_us" as *u8, pf_budget_ms(FP_60) == FP_BUDGET_60_MS, ctr)
111 gv_check("budget-ms-for-30Hz-composes-fb_budget_us" as *u8, pf_budget_ms(FP_30) == FP_BUDGET_30_MS, ctr)
112 gv_check("fits-is-fb_fits" as *u8, pf_fits(FP_FIX_STEADY_MS, FP_BUDGET_60_MS) == 1, ctr)
113 gv_check("neg-control-a-stall-does-not-fit-the-60Hz-budget" as *u8, pf_fits(FP_FIX_STALL_MS, FP_BUDGET_60_MS) == 0, ctr)
114
115 // (1g) the plane readers of nx_frame_pacing_lib: a synthetic row round-trips its frames column
116 let rowb: *u8 = sys_mmap(FP_ROW_CAP)
117 var ro: i64 = 0
118 let fix: *u8 = "beach_1\tbeach\t1\t16:page\t5\t5\t16/16/40\t16/16/40\t40\t40\t1\t1\tRED:p99-over-band\tAGREE\t16,16,16,16,40" as *u8
119 while fix[ro] != (0 as u8) { rowb[ro] = fix[ro]; ro = ro + 1 }
120 let rr: *i64 = fp_region()
121 pf_init(rr)
122 let fr: i64 = fpc_row_frames(rowb, ro, rr, FP_BUDGET_60_MS)
123 gv_check("plane-row-frames-column-parses-five-samples" as *u8, fr == FP_CSV_FIX_N, ctr)
124 gv_check("plane-row-frames-worst-is-the-planted-stall" as *u8, pf_worst(rr) == FP_FIX_STALL_MS, ctr)
125 gv_check("plane-row-budget-column-reads-the-integer-before-its-source" as *u8, fpc_col_int(rowb, 0, ro, FPC_COL_BUDGET) == FP_BUDGET_60_MS, ctr)
126 let wcs: i64 = fpc_col_start(rowb, 0, ro, FPC_COL_WORLD)
127 gv_check("plane-row-world-column-is-beach" as *u8, fpc_slice_eq(rowb, wcs, fpc_col_end(rowb, wcs, ro), FP_WORLD) == 1, ctr)
128 gv_check("neg-control-a-row-with-too-few-columns-has-no-frames" as *u8, fpc_row_frames(rowb, FP_SHORT_ROW, rr, FP_BUDGET_60_MS) == (0 - 1), ctr)
129 gv_check("world-name-rule-accepts-beach" as *u8, fpc_world_safe(FP_WORLD, FP_WORLD_N) == 1, ctr)
130 gv_check("neg-control-world-name-rule-refuses-a-path" as *u8, fpc_world_safe("../etc" as *u8, 6) == 0, ctr)
131
132 // (2) the referee on synthetic traces
133 let rc: *i64 = fp_region()
134 pf_init(rc)
135 i = 0
136 while i < FP_TRACE_N { pf_push(rc, FP_TRACE_60HZ_MS, FP_BUDGET_60_MS); i = i + 1 }
137 gv_check("clean-60Hz-trace-reads-GREEN" as *u8, pf_referee(rc, FP_BUDGET_60_MS, 120, 1000, 1200, 2000, 50, why) == PF_GREEN, ctr)
138 let rs: *i64 = fp_region()
139 pf_init(rs)
140 i = 0
141 while i < FP_TRACE_N { if i % FP_TRACE_STALL_EVERY == 0 { pf_push(rs, FP_FIX_STALL_MS, FP_BUDGET_60_MS) } else { pf_push(rs, FP_TRACE_60HZ_MS, FP_BUDGET_60_MS) } i = i + 1 }
142 gv_check("fixture-reached-condition-planted-stalls-are-in-the-window" as *u8, pf_spikes(rs) > 0, ctr)
143 gv_check("neg-control-planted-periodic-stall-reads-RED" as *u8, pf_referee(rs, FP_BUDGET_60_MS, 120, 1000, 1200, 2000, 50, why) == PF_RED, ctr)
144 let rt: *i64 = fp_region()
145 pf_init(rt)
146 i = 0
147 while i < FP_TRACE_SHORT_N { pf_push(rt, FP_TRACE_60HZ_MS, FP_BUDGET_60_MS); i = i + 1 }
148 gv_check("short-trace-ABSTAINS-under-the-min-sample-denominator" as *u8, pf_referee(rt, FP_BUDGET_60_MS, 120, 1000, 1200, 2000, 50, why) == PF_ABSTAIN, ctr)
149
150 // (3) the LIVE window from the plane against the conf bands -- a named SKIP when either input is absent
151 let conf: *i64 = sys_mmap(FPC_N * 8) as *i64
152 let cpres: i64 = fpc_load(FPC_CONF, conf)
153 var confok: i64 = 0
154 if cpres >= 0 { confok = 1 }
155 if gv_need("conf-readable-knowledge/frame_pacing.conf" as *u8, confok, ctr) == 1 {
156 gv_check("conf-carries-every-band-row" as *u8, cpres == FPC_N, ctr)
157 let rows_seen: *i64 = sys_mmap(8) as *i64
158 let rowl: i64 = fpc_plane_latest(FPC_PLANE, FP_WORLD, rowb, FP_ROW_CAP, rows_seen)
159 gv_puts(" plane rows scanned=" as *u8); gv_num(rows_seen[0]); gv_puts(" latest_beach_row_bytes=" as *u8); gv_num(rowl); gv_puts("\n" as *u8)
160 var rowok: i64 = 0
161 if rowl > 0 { rowok = 1 }
162 if gv_need("live-window-present-in-knowledge/store/frametrace-for-beach" as *u8, rowok, ctr) == 1 {
163 let rl: *i64 = fp_region()
164 pf_init(rl)
165 var bud: i64 = fpc_col_int(rowb, 0, rowl, FPC_COL_BUDGET)
166 if bud <= 0 { bud = conf[FPC_BUDGET] }
167 let nfr: i64 = fpc_row_frames(rowb, rowl, rl, bud)
168 gv_check("live-window-frames-column-parses" as *u8, nfr > 0, ctr)
169 let v: i64 = fpc_judge(rl, conf, bud, why)
170 gv_puts(" live window frames=" as *u8); gv_num(nfr)
171 gv_puts(" budget_ms=" as *u8); gv_num(bud)
172 gv_puts(" p50=" as *u8); gv_num(pf_pct(rl, 500))
173 gv_puts(" p95=" as *u8); gv_num(pf_pct(rl, 950))
174 gv_puts(" p99=" as *u8); gv_num(pf_pct(rl, 990))
175 gv_puts(" worst=" as *u8); gv_num(pf_worst(rl))
176 gv_puts(" spikes_permil=" as *u8); gv_num(pf_spikes_permil(rl))
177 gv_puts(" verdict=" as *u8); gv_puts(fpc_verdict_name(v))
178 gv_puts(" why=" as *u8); gv_puts(fpc_why_name(why[0])); gv_puts("\n" as *u8)
179 gv_check("live-window-has-enough-samples-to-judge" as *u8, v != PF_ABSTAIN, ctr)
180 gv_check("live-window-inside-the-conf-bands" as *u8, v == PF_GREEN, ctr)
181 }
182 }
183
184 return gv_verdict("nx_frame_pacing_gate" as *u8, ctr, "one frame-budget ruler for engine, HUD, sink and referee; the live window is a plane row, the referee abstains below the sample floor" as *u8)
185}