nx_frame_pacing_lib.nx source
↩ module page · 324 lines · 14419 B
1// nx_frame_pacing_lib.nx -- THE NATIVE HALF OF THE FRAME-BUDGET RULER: one conf reader, one plane reader, one
2// frames reader and ONE judgement call shared by every native consumer (the pacing gate, the world telemetry
3// sink, any future beat). nx_perf_lib holds the arithmetic and is wasm-compatible by construction (no syscalls);
4// this lib is the layer that touches the conf and the SOVEREIGN STORE PLANE, so the wasm engine, the served HUD,
5// the gate and the sink all compute the same numbers from the same window and read the same bands.
6//
7// THE PLANE, NOT A FILE (operator 2026-09-02: "you just built with tsv yet again instead of sota data file
8// systems"; the 2026-08-13 standing order already forbade third-party formats in the plane). Frame windows are
9// rows of the seg-store plane knowledge/store/frametrace- written through nx_store_seed_lib (the same locked
10// append every board uses), never a .tsv beside it. One row per beacon:
11// id=<world>_<ts> | world | ts | budget(ms:src) | n | total | page p50/p95/p99 | sink p50/p95/p99 | worst |
12// worst_ever | spikes | over | verdict:why | twins | frames_csv (15 columns, under the 16-col plane cap)
13// The plane is append-only, so it IS the time spine: the latest row for a world is the current window and every
14// earlier row is history -- readable by any seat through `nx_store_put knowledge/store/frametrace- load`.
15//
16// THE CONF (knowledge/frame_pacing.conf): `key=value` rows, `#` comments:
17// budget_ms min_samples p50_permil p95_permil p99_permil jank_permil
18// Bands are permil OF THE BUDGET so one conf serves every display refresh rate.
19// license_tier: ORIGINAL No hw writes (Rule 26).
20import "nx_syscalls.nx"
21import "nx_perf_lib.nx"
22import "nx_store_seed_lib.nx"
23
24const FPC_CONF: *u8 = "knowledge/frame_pacing.conf"
25const FPC_PLANE: *u8 = "knowledge/store/frametrace-"
26// conf slots (an i64 array of FPC_N)
27const FPC_BUDGET: i64 = 0
28const FPC_MIN_N: i64 = 1
29const FPC_P50: i64 = 2
30const FPC_P95: i64 = 3
31const FPC_P99: i64 = 4
32const FPC_JANK: i64 = 5
33const FPC_N: i64 = 6
34const FPC_ABSENT: i64 = 0 - 1
35const FPC_WORLD_MAX: i64 = 32 // a world name longer than this is not one of ours (beach, craft, vale ...)
36// plane row columns (0 = id)
37const FPC_COL_ID: i64 = 0
38const FPC_COL_WORLD: i64 = 1
39const FPC_COL_TS: i64 = 2
40const FPC_COL_BUDGET: i64 = 3
41const FPC_COL_N: i64 = 4
42const FPC_COL_TOTAL: i64 = 5
43const FPC_COL_PAGE: i64 = 6
44const FPC_COL_SINK: i64 = 7
45const FPC_COL_WORST: i64 = 8
46const FPC_COL_WEVER: i64 = 9
47const FPC_COL_SPIKES: i64 = 10
48const FPC_COL_OVER: i64 = 11
49const FPC_COL_VERDICT: i64 = 12
50const FPC_COL_TWINS: i64 = 13
51const FPC_COL_FRAMES: i64 = 14
52const FPC_COLS: i64 = 15
53const FPC_CH_NL: i64 = 10
54const FPC_CH_CR: i64 = 13
55const FPC_CH_TAB: i64 = 9
56const FPC_CH_HASH: i64 = 35
57const FPC_CH_EQ: i64 = 61
58const FPC_CH_COLON: i64 = 58
59const FPC_CH_0: i64 = 48
60const FPC_CH_9: i64 = 57
61const FPC_CH_a: i64 = 97
62const FPC_CH_z: i64 = 122
63const FPC_CH_UNDERSCORE: i64 = 95
64const FPC_CH_COMMA: i64 = 44
65const FPC_CH_LBRACK: i64 = 91
66const FPC_CH_RBRACK: i64 = 93
67const FPC_CH_SPACE: i64 = 32
68const FPC_WHY_NONE: i64 = 0
69
70func fpc_slen(s: *u8) -> i64 { var n: i64 = 0; while s[n] != (0 as u8) { n = n + 1 } return n }
71func fpc_eol(b: *u8, n: i64, i: i64) -> i64 { var j: i64 = i; var f: i64 = n; var go: i64 = 1; while go == 1 { if j >= n { go = 0 } else { if b[j] == (FPC_CH_NL as u8) { f = j; go = 0 } else { j = j + 1 } } } return f }
72func fpc_slice_eq(b: *u8, a: i64, e: i64, lit: *u8) -> i64 {
73 let l: i64 = fpc_slen(lit)
74 if e - a != l { return 0 }
75 var i: i64 = 0
76 while i < l { if b[a + i] != lit[i] { return 0 } i = i + 1 }
77 return 1
78}
79// decimal integer in [s,e) (leading spaces allowed, optional '-'); FPC_ABSENT when no digit
80func fpc_slice_int(b: *u8, s: i64, e: i64) -> i64 {
81 var i: i64 = s
82 while i < e { if b[i] == (FPC_CH_SPACE as u8) { i = i + 1 } else { i = e + i - i } }
83 var p: i64 = s
84 while p < e { if b[p] == (FPC_CH_SPACE as u8) { p = p + 1 } else { p = e + p - p } }
85 // (the two loops above only skip spaces; recompute the true start)
86 var q: i64 = s
87 var go0: i64 = 1
88 while go0 == 1 { if q >= e { go0 = 0 } else { if b[q] == (FPC_CH_SPACE as u8) { q = q + 1 } else { go0 = 0 } } }
89 var neg: i64 = 0
90 if q < e { if b[q] == (45 as u8) { neg = 1; q = q + 1 } }
91 var v: i64 = 0
92 var any: i64 = 0
93 var go: i64 = 1
94 while go == 1 { if q >= e { go = 0 } else { let c: i64 = b[q] as i64; if c >= FPC_CH_0 { if c <= FPC_CH_9 { v = v*10 + (c-FPC_CH_0); any = 1; q = q + 1 } else { go = 0 } } else { go = 0 } } }
95 if any == 0 { return FPC_ABSENT }
96 if neg == 1 { return 0 - v }
97 return v
98}
99
100// conf reader: `key=value` rows, `#` comments; FPC_ABSENT when the key is absent so the caller can SKIP by name
101func fpc_conf_int(buf: *u8, n: i64, key: *u8) -> i64 {
102 let kl: i64 = fpc_slen(key)
103 var i: i64 = 0
104 while i < n {
105 var atstart: i64 = 0
106 if i == 0 { atstart = 1 } else { if buf[i-1] == (FPC_CH_NL as u8) { atstart = 1 } }
107 if atstart == 1 {
108 var k: i64 = 0
109 var ok: i64 = 1
110 while k < kl { if i + k >= n { ok = 0; k = kl } else { if buf[i+k] != key[k] { ok = 0; k = kl } else { k = k + 1 } } }
111 if ok == 1 { if i + kl < n { if buf[i+kl] == (FPC_CH_EQ as u8) {
112 let v: i64 = fpc_slice_int(buf, i + kl + 1, fpc_eol(buf, n, i))
113 if v >= 0 { return v }
114 } } }
115 }
116 i = i + 1
117 }
118 return FPC_ABSENT
119}
120
121// load every band into out[0..FPC_N); returns how many rows were PRESENT (FPC_N = complete), -1 when the conf
122// itself is unreadable. A caller that judges with fewer than FPC_N rows is judging against an absent bar.
123func fpc_load(path: *u8, out: *i64) -> i64 {
124 let lp: *i64 = sys_mmap(16) as *i64
125 let b: *u8 = sys_read_file(path, lp)
126 if (b as i64) == 0 { return 0 - 1 }
127 let n: i64 = lp[0]
128 out[FPC_BUDGET] = fpc_conf_int(b, n, "budget_ms" as *u8)
129 out[FPC_MIN_N] = fpc_conf_int(b, n, "min_samples" as *u8)
130 out[FPC_P50] = fpc_conf_int(b, n, "p50_permil" as *u8)
131 out[FPC_P95] = fpc_conf_int(b, n, "p95_permil" as *u8)
132 out[FPC_P99] = fpc_conf_int(b, n, "p99_permil" as *u8)
133 out[FPC_JANK] = fpc_conf_int(b, n, "jank_permil" as *u8)
134 var present: i64 = 0
135 var i: i64 = 0
136 while i < FPC_N { if out[i] >= 0 { present = present + 1 } i = i + 1 }
137 return present
138}
139
140// ---- plane rows: TAB-separated columns, one row per line as sts_load_fit returns them ----
141// start offset of column `col` within row [s,e); FPC_ABSENT when the row has fewer columns
142func fpc_col_start(b: *u8, s: i64, e: i64, col: i64) -> i64 {
143 var c: i64 = 0
144 var p: i64 = s
145 while c < col {
146 var go: i64 = 1
147 while go == 1 { if p >= e { go = 0 } else { if b[p] == (FPC_CH_TAB as u8) { go = 0 } else { p = p + 1 } } }
148 if p >= e { return FPC_ABSENT }
149 p = p + 1
150 c = c + 1
151 }
152 return p
153}
154// end offset (exclusive) of the column starting at s: the next TAB or e
155func fpc_col_end(b: *u8, s: i64, e: i64) -> i64 {
156 var p: i64 = s
157 var go: i64 = 1
158 while go == 1 { if p >= e { go = 0 } else { if b[p] == (FPC_CH_TAB as u8) { go = 0 } else { p = p + 1 } } }
159 return p
160}
161// column `col` of row [s,e) as an integer (the FIRST integer in the column: `16:page` reads 16); FPC_ABSENT if none
162func fpc_col_int(b: *u8, s: i64, e: i64, col: i64) -> i64 {
163 let cs: i64 = fpc_col_start(b, s, e, col)
164 if cs < 0 { return FPC_ABSENT }
165 return fpc_slice_int(b, cs, fpc_col_end(b, cs, e))
166}
167
168// the LATEST frametrace- row for `world`: the whole plane is scanned (rows are appended in time order, so the last
169// match is the current window); the row (no newline) is copied into out. Returns its length, 0 when the world has
170// no row yet, -1 when the plane is unreadable/unseeded. `rows_seen` receives the scanned row count so a caller can
171// print its coverage instead of asserting it.
172func fpc_plane_latest(prefix: *u8, world: *u8, out: *u8, cap: i64, rows_seen: *i64) -> i64 {
173 let lp: *i64 = sys_mmap(16) as *i64
174 let b: *u8 = sts_load_fit(prefix, lp)
175 rows_seen[0] = 0
176 if (b as i64) == 0 { return 0 - 1 }
177 let n: i64 = lp[0]
178 var best_s: i64 = 0 - 1
179 var best_e: i64 = 0
180 var i: i64 = 0
181 while i < n {
182 let e: i64 = fpc_eol(b, n, i)
183 if e > i { if b[i] != (FPC_CH_HASH as u8) {
184 rows_seen[0] = rows_seen[0] + 1
185 let ws: i64 = fpc_col_start(b, i, e, FPC_COL_WORLD)
186 if ws >= 0 { if fpc_slice_eq(b, ws, fpc_col_end(b, ws, e), world) == 1 { best_s = i; best_e = e } }
187 } }
188 i = e + 1
189 }
190 if best_s < 0 { return 0 }
191 var o: i64 = 0
192 var j: i64 = best_s
193 while j < best_e { if o < cap - 1 { if b[j] != (FPC_CH_CR as u8) { out[o] = b[j]; o = o + 1 } } j = j + 1 }
194 out[o] = 0 as u8
195 return o
196}
197// the frames column of a row into the perf region: comma-separated integer ms, oldest first. Returns the count
198// pushed, -1 when the column is absent, -2 when a non-integer byte sits inside it.
199func fpc_row_frames(row: *u8, n: i64, r: *i64, budget_ms: i64) -> i64 {
200 let cs: i64 = fpc_col_start(row, 0, n, FPC_COL_FRAMES)
201 if cs < 0 { return 0 - 1 }
202 return fpc_csv_parse(row, cs, fpc_col_end(row, cs, n), r, budget_ms)
203}
204// Representation limit keeps a complete window's sum and mean-times-ten inside signed i64.
205const FPC_FRAME_MAX_MS: i64 = 9223372036854775807 / PF_N / 10
206func fpc_frame_space(c: i64) -> i64 {
207 if c == 32 { return 1 }; if c == 9 { return 1 }
208 if c == 10 { return 1 }; if c == 13 { return 1 }
209 return 0
210}
211func fpc_csv_parse(b: *u8, s: i64, e: i64, r: *i64, budget_ms: i64) -> i64 {
212 if s < 0 { return 0 - 2 }; if e < s { return 0 - 2 }
213 // The first pass validates the whole window. No rejected request can partly alter the recorder.
214 var pass: i64 = 0
215 var count: i64 = 0
216 while pass < 2 {
217 var p: i64 = s
218 count = 0
219 while p < e { if fpc_frame_space(b[p] as i64) == 1 { p = p + 1 } else { break } }
220 while p < e {
221 var v: i64 = 0
222 var digits: i64 = 0
223 while p < e {
224 let c: i64 = b[p] as i64
225 if c < FPC_CH_0 { break }; if c > FPC_CH_9 { break }
226 let d: i64 = c - FPC_CH_0
227 if v > (FPC_FRAME_MAX_MS-d)/10 { return 0 - 2 }
228 v = v*10+d; digits = digits + 1; p = p + 1
229 }
230 if digits == 0 { return 0 - 2 }
231 count = count + 1
232 if count > PF_N { return 0 - 2 }
233 if pass == 1 { pf_push_raw(r, v, budget_ms) }
234 while p < e { if fpc_frame_space(b[p] as i64) == 1 { p = p + 1 } else { break } }
235 if p < e {
236 if b[p] != (FPC_CH_COMMA as u8) { return 0 - 2 }
237 p = p + 1
238 while p < e { if fpc_frame_space(b[p] as i64) == 1 { p = p + 1 } else { break } }
239 if p == e { return 0 - 2 }
240 }
241 }
242 pass = pass + 1
243 }
244 return count
245}
246
247// the `"frames":[a,b,c]` array of a telemetry beacon, pushed into the perf region in order; returns the count
248// pushed, -1 when the key is absent, -2 when malformed or outside the frame/value bounds.
249// One beacon carries at most PF_N samples; refusal leaves the recorder unchanged.
250func fpc_frames_parse(b: *u8, n: i64, r: *i64, budget_ms: i64) -> i64 {
251 let key: *u8 = "\"frames\":[" as *u8
252 let kl: i64 = fpc_slen(key)
253 var at: i64 = 0 - 1
254 var i: i64 = 0
255 while i + kl <= n {
256 var m: i64 = 1
257 var k: i64 = 0
258 while k < kl { if b[i+k] != key[k] { m = 0; k = kl } else { k = k + 1 } }
259 if m == 1 { at = i; i = n } else { i = i + 1 }
260 }
261 if at < 0 { return 0 - 1 }
262 // the array body ends at the first ']'
263 var e: i64 = at + kl
264 var closed: i64 = 0
265 var go: i64 = 1
266 while go == 1 { if e >= n { go = 0 } else { if b[e] == (FPC_CH_RBRACK as u8) { closed = 1; go = 0 } else { e = e + 1 } } }
267 if closed == 0 { return 0 - 2 }
268 return fpc_csv_parse(b, at + kl, e, r, budget_ms)
269}
270
271// a world name is [a-z0-9_]{1,FPC_WORLD_MAX}: it names a plane row and a file, so anything else is refused
272func fpc_world_safe(w: *u8, n: i64) -> i64 {
273 if n <= 0 { return 0 }
274 if n > FPC_WORLD_MAX { return 0 }
275 var i: i64 = 0
276 while i < n {
277 let c: i64 = w[i] as i64
278 var ok: i64 = 0
279 if c >= FPC_CH_a { if c <= FPC_CH_z { ok = 1 } }
280 if c >= FPC_CH_0 { if c <= FPC_CH_9 { ok = 1 } }
281 if c == FPC_CH_UNDERSCORE { ok = 1 }
282 if ok == 0 { return 0 }
283 i = i + 1
284 }
285 return 1
286}
287
288// append one row to the plane (locked); an unseeded plane is BOOTSTRAPPED by the first row, exactly as the
289// nx_store_put verb does. Returns >=0 on success, negative on refusal (lock, CAS collision, cap).
290func fpc_plane_append(prefix: *u8, row: *u8, n: i64) -> i64 {
291 let rc: i64 = sts_append_fast_locked(prefix, row, n)
292 if rc >= 0 { return rc }
293 if rc == (0 - 1) {
294 // no q:n row: the plane does not exist yet -> seed it with this one row (a newline-terminated flat buffer)
295 let seed: *u8 = sys_mmap(n + 2)
296 var i: i64 = 0
297 while i < n { seed[i] = row[i]; i = i + 1 }
298 seed[n] = FPC_CH_NL as u8
299 let src: i64 = sts_seed(prefix, seed, n + 1)
300 sys_munmap(seed, n + 2)
301 return src
302 }
303 return rc
304}
305
306// THE ONE JUDGEMENT CALL: the region against the conf bands; budget_ms is the DISPLAY budget the frames were
307// measured against (the page's, when known; the conf's otherwise). why[0] names the failing conjunct.
308func fpc_judge(r: *i64, conf: *i64, budget_ms: i64, why: *i64) -> i64 {
309 return pf_referee(r, budget_ms, conf[FPC_MIN_N], conf[FPC_P50], conf[FPC_P95], conf[FPC_P99], conf[FPC_JANK], why)
310}
311func fpc_verdict_name(v: i64) -> *u8 {
312 if v == PF_GREEN { return "GREEN" as *u8 }
313 if v == PF_RED { return "RED" as *u8 }
314 if v == PF_ABSTAIN { return "ABSTAIN" as *u8 }
315 return "UNCLASSIFIED" as *u8
316}
317func fpc_why_name(w: i64) -> *u8 {
318 if w == FPC_WHY_NONE { return "-" as *u8 }
319 if w == 1 { return "p50-over-band" as *u8 }
320 if w == 2 { return "p95-over-band" as *u8 }
321 if w == 3 { return "p99-over-band" as *u8 }
322 if w == 4 { return "jank-over-band" as *u8 }
323 return "unnamed-conjunct" as *u8
324}