nx_bench_receipt_lib.nx source
↩ module page · 318 lines · 16082 B
1// nx_bench_receipt_lib.nx -- THE ONE READER, ONE VERDICT AND ONE SERIALISER for a /compare <dom>.bench receipt
2// (2026-09-01, lang leg: "meet and exceed gcc and rust, independently verified, reproducible, visible").
3//
4// WHY A LIB. A benchmark receipt is read by THREE organs -- the writer that measures (nx_lang_h2h), the two
5// /compare generators that render it (bench_pass in nx_swcompare_lib), and the gate that judges it
6// (nx_lang_h2h_gate). WHEN THREE ORGANS MUST AGREE ON WHAT "VALID" MEANS, MAKE DISAGREEMENT IMPOSSIBLE BY
7// CONSTRUCTION: there is exactly one classifier (br_verdict), one row grammar (br_parse / br_write) and one
8// ratio rule (permil of the reference arm's median). The writer calls br_verdict BEFORE it serialises and the
9// reader calls it AFTER it parses, so a receipt whose written @verdict disagrees with its rows is detectable.
10//
11// THE RECEIPT (knowledge/compare/<dom>.bench), a data file the emitter renders for ANY domain:
12// @title <text> @workload <text: what every arm computes and the checksum it must print>
13// @host <hostname>|<cpu model>|<kernel>|nproc=<n>
14// @runs <n> @ref <arm name that is the 1.00x baseline> @asof <epoch>
15// @repro <the exact command that regenerates this file> @writer <organ>
16// @verdict VALID|VOID|UNMEASURABLE|EMPTY (written by the writer, RE-DERIVED by every reader)
17// arm|<name>|<toolchain>|<version>|<source>|<source_sha256>|<bin_bytes>|<bin_sha256>|<runs>|<min_us>|<median_us>|<checksum>|<status>|<note>
18// STATUS per arm: VALID (measured, checksum equals the reference arm's), VOID (measured, checksum DIFFERS --
19// the arm did not do the same work, so its time is not comparable and is never ranked), UNMEASURABLE (the
20// toolchain is not declared on the measuring host -- an absence, never a loss), BUILD-FAIL, RUN-FAIL.
21// VERDICT for the receipt: EMPTY (no arm rows), UNMEASURABLE (the reference arm is not VALID, so no ratio
22// exists), VOID (any measured arm disagrees on the checksum), VALID otherwise.
23// A ratio is permil of the reference median: 1000 = 1.00x, 2020 = 2.02x slower. Only VALID arms carry one.
24// NOTHING HERE IS A THRESHOLD: the lib says what was measured; the gate says what is acceptable.
25// license_tier: ORIGINAL No hw writes (Rule 26). LIB (no main).
26import "nx_syscalls.nx"
27
28const BR_MAXARMS: i64 = 32
29const BR_STRIDE: i64 = 16
30const BR_A_NAME: i64 = 0
31const BR_A_TOOL: i64 = 1
32const BR_A_VER: i64 = 2
33const BR_A_SRC: i64 = 3
34const BR_A_SRCSHA: i64 = 4
35const BR_A_BINBYTES: i64 = 5
36const BR_A_BINSHA: i64 = 6
37const BR_A_RUNS: i64 = 7
38const BR_A_MIN: i64 = 8
39const BR_A_MED: i64 = 9
40const BR_A_CHK: i64 = 10
41const BR_A_STATUS: i64 = 11
42const BR_A_NOTE: i64 = 12
43const BR_A_RATIO: i64 = 13
44const BR_H_TITLE: i64 = 0
45const BR_H_WORKLOAD: i64 = 1
46const BR_H_HOST: i64 = 2
47const BR_H_RUNS: i64 = 3
48const BR_H_REF: i64 = 4
49const BR_H_ASOF: i64 = 5
50const BR_H_REPRO: i64 = 6
51const BR_H_WRITER: i64 = 7
52const BR_H_WRITTEN_VERDICT: i64 = 8
53const BR_H_N: i64 = 9
54const BR_ST_UNKNOWN: i64 = 0
55const BR_ST_VALID: i64 = 1
56const BR_ST_VOID: i64 = 2
57const BR_ST_UNMEASURABLE: i64 = 3
58const BR_ST_BUILDFAIL: i64 = 4
59const BR_ST_RUNFAIL: i64 = 5
60const BR_V_EMPTY: i64 = 0
61const BR_V_VALID: i64 = 1
62const BR_V_VOID: i64 = 2
63const BR_V_UNMEASURABLE: i64 = 3
64const BR_V_UNWRITTEN: i64 = 0 - 1
65const BR_ARM_FIELDS: i64 = 14
66const BR_MAXF: i64 = 20
67const BR_PERMIL: i64 = 1000
68const BR_TEN: i64 = 10
69const BR_PIPE: i64 = 124
70const BR_NL: i64 = 10
71const BR_HASH: i64 = 35
72const BR_AT: i64 = 64
73const BR_MINUS: i64 = 45
74const BR_DOT: i64 = 46
75const BR_ZERO: i64 = 48
76const BR_NINE: i64 = 57
77const BR_LOWER_X: i64 = 120
78const BR_WORD: i64 = 8
79const BR_ROW_RESERVE: i64 = 4096
80const BR_NO_RATIO: i64 = 0 - 1
81
82func br_slen(s: *u8) -> i64 { var n: i64 = 0; while s[n] != (0 as u8) { n = n + 1 } return n }
83func br_streq(a: *u8, b: *u8) -> i64 { var i: i64 = 0; while a[i] != (0 as u8) { if a[i] != b[i] { return 0 } i = i + 1 } if b[i] != (0 as u8) { return 0 } return 1 }
84func br_starts(s: *u8, pfx: *u8) -> i64 { var i: i64 = 0; while pfx[i] != (0 as u8) { if s[i] != pfx[i] { return 0 } i = i + 1 } return 1 }
85// optional leading minus, then digits; anything else ends the number. An empty field reads 0.
86func br_atoi(s: *u8) -> i64 {
87 var i: i64 = 0
88 var neg: i64 = 0
89 if (s[0] as i64) == BR_MINUS { neg = 1; i = 1 }
90 var v: i64 = 0
91 while s[i] != (0 as u8) {
92 let c: i64 = s[i] as i64
93 if c < BR_ZERO { break }
94 if c > BR_NINE { break }
95 v = v * BR_TEN + (c - BR_ZERO)
96 i = i + 1
97 }
98 if neg == 1 { return 0 - v }
99 return v
100}
101func br_cat(dst: *u8, off: i64, s: *u8) -> i64 {
102 var o: i64 = off
103 var i: i64 = 0
104 while s[i] != (0 as u8) { dst[o] = s[i]; o = o + 1; i = i + 1 }
105 dst[o] = 0 as u8
106 return o
107}
108func br_put(dst: *u8, off: i64, c: i64) -> i64 { dst[off] = c as u8; dst[off + 1] = 0 as u8; return off + 1 }
109func br_catn(dst: *u8, off: i64, v: i64) -> i64 {
110 var o: i64 = off
111 var m: i64 = v
112 if m < 0 { o = br_put(dst, o, BR_MINUS); m = 0 - m }
113 let t: *u8 = sys_mmap(32)
114 var k: i64 = 0
115 if m == 0 { t[0] = BR_ZERO as u8; k = 1 }
116 while m > 0 { t[k] = (BR_ZERO + (m % BR_TEN)) as u8; m = m / BR_TEN; k = k + 1 }
117 var j: i64 = 0
118 while j < k { dst[o] = t[k - 1 - j]; o = o + 1; j = j + 1 }
119 dst[o] = 0 as u8
120 return o
121}
122func br_status_name(c: i64) -> *u8 {
123 if c == BR_ST_VALID { return "VALID" as *u8 }
124 if c == BR_ST_VOID { return "VOID" as *u8 }
125 if c == BR_ST_UNMEASURABLE { return "UNMEASURABLE" as *u8 }
126 if c == BR_ST_BUILDFAIL { return "BUILD-FAIL" as *u8 }
127 if c == BR_ST_RUNFAIL { return "RUN-FAIL" as *u8 }
128 return "UNKNOWN" as *u8
129}
130func br_status_code(s: *u8) -> i64 {
131 if br_streq(s, "VALID" as *u8) == 1 { return BR_ST_VALID }
132 if br_streq(s, "VOID" as *u8) == 1 { return BR_ST_VOID }
133 if br_streq(s, "UNMEASURABLE" as *u8) == 1 { return BR_ST_UNMEASURABLE }
134 if br_streq(s, "BUILD-FAIL" as *u8) == 1 { return BR_ST_BUILDFAIL }
135 if br_streq(s, "RUN-FAIL" as *u8) == 1 { return BR_ST_RUNFAIL }
136 return BR_ST_UNKNOWN
137}
138func br_verdict_name(v: i64) -> *u8 {
139 if v == BR_V_VALID { return "VALID" as *u8 }
140 if v == BR_V_VOID { return "VOID" as *u8 }
141 if v == BR_V_UNMEASURABLE { return "UNMEASURABLE" as *u8 }
142 if v == BR_V_EMPTY { return "EMPTY" as *u8 }
143 return "UNWRITTEN" as *u8
144}
145func br_verdict_code(s: *u8) -> i64 {
146 if br_streq(s, "VALID" as *u8) == 1 { return BR_V_VALID }
147 if br_streq(s, "VOID" as *u8) == 1 { return BR_V_VOID }
148 if br_streq(s, "UNMEASURABLE" as *u8) == 1 { return BR_V_UNMEASURABLE }
149 if br_streq(s, "EMPTY" as *u8) == 1 { return BR_V_EMPTY }
150 return BR_V_UNWRITTEN
151}
152// NUL-splits s on the pipe IN PLACE (the compare-surface convention); returns the field count
153func br_split(s: *u8, fld: *i64, maxf: i64) -> i64 {
154 var c: i64 = 1
155 fld[0] = s as i64
156 var i: i64 = 0
157 while s[i] != (0 as u8) {
158 if (s[i] as i64) == BR_PIPE { s[i] = 0 as u8; if c < maxf { fld[c] = (s as i64) + i + 1; c = c + 1 } }
159 i = i + 1
160 }
161 return c
162}
163func br_init(hdr: *i64, arms: *i64) -> i64 {
164 var i: i64 = 0
165 while i < BR_H_N { hdr[i] = ("" as *u8) as i64; i = i + 1 }
166 hdr[BR_H_RUNS] = 0
167 hdr[BR_H_ASOF] = 0
168 hdr[BR_H_WRITTEN_VERDICT] = BR_V_UNWRITTEN
169 var a: i64 = 0
170 while a < BR_MAXARMS * BR_STRIDE { arms[a] = 0; a = a + 1 }
171 return 0
172}
173// PARSE. Mutates buf (line and field NUL-termination, the convention every compare reader uses). Returns the arm count.
174func br_parse(buf: *u8, n: i64, hdr: *i64, arms: *i64) -> i64 {
175 br_init(hdr, arms)
176 let fld: *i64 = sys_mmap(BR_MAXF * BR_WORD) as *i64
177 var count: i64 = 0
178 var p: i64 = 0
179 while p < n {
180 var e: i64 = p
181 while e < n { if (buf[e] as i64) == BR_NL { break } e = e + 1 }
182 buf[e] = 0 as u8
183 let line: *u8 = (buf as i64 + p) as *u8
184 p = e + 1
185 if line[0] == (0 as u8) { } else { if (line[0] as i64) == BR_HASH { } else {
186 if (line[0] as i64) == BR_AT {
187 if br_starts(line, "@title " as *u8) == 1 { hdr[BR_H_TITLE] = (line as i64) + 7 } else {
188 if br_starts(line, "@workload " as *u8) == 1 { hdr[BR_H_WORKLOAD] = (line as i64) + 10 } else {
189 if br_starts(line, "@host " as *u8) == 1 { hdr[BR_H_HOST] = (line as i64) + 6 } else {
190 if br_starts(line, "@runs " as *u8) == 1 { hdr[BR_H_RUNS] = br_atoi((line as i64 + 6) as *u8) } else {
191 if br_starts(line, "@ref " as *u8) == 1 { hdr[BR_H_REF] = (line as i64) + 5 } else {
192 if br_starts(line, "@asof " as *u8) == 1 { hdr[BR_H_ASOF] = br_atoi((line as i64 + 6) as *u8) } else {
193 if br_starts(line, "@repro " as *u8) == 1 { hdr[BR_H_REPRO] = (line as i64) + 7 } else {
194 if br_starts(line, "@writer " as *u8) == 1 { hdr[BR_H_WRITER] = (line as i64) + 8 } else {
195 if br_starts(line, "@verdict " as *u8) == 1 { hdr[BR_H_WRITTEN_VERDICT] = br_verdict_code((line as i64 + 9) as *u8) } } } } } } } } }
196 } else {
197 let nf: i64 = br_split(line, fld, BR_MAXF)
198 if br_streq(fld[0] as *u8, "arm" as *u8) == 1 { if nf >= BR_ARM_FIELDS { if count < BR_MAXARMS {
199 let b: i64 = count * BR_STRIDE
200 arms[b + BR_A_NAME] = fld[1]
201 arms[b + BR_A_TOOL] = fld[2]
202 arms[b + BR_A_VER] = fld[3]
203 arms[b + BR_A_SRC] = fld[4]
204 arms[b + BR_A_SRCSHA] = fld[5]
205 arms[b + BR_A_BINBYTES] = br_atoi(fld[6] as *u8)
206 arms[b + BR_A_BINSHA] = fld[7]
207 arms[b + BR_A_RUNS] = br_atoi(fld[8] as *u8)
208 arms[b + BR_A_MIN] = br_atoi(fld[9] as *u8)
209 arms[b + BR_A_MED] = br_atoi(fld[10] as *u8)
210 arms[b + BR_A_CHK] = br_atoi(fld[11] as *u8)
211 arms[b + BR_A_STATUS] = br_status_code(fld[12] as *u8)
212 arms[b + BR_A_NOTE] = fld[13]
213 arms[b + BR_A_RATIO] = BR_NO_RATIO
214 count = count + 1
215 } } }
216 }
217 } }
218 }
219 return count
220}
221// LOAD a receipt file: -1 when the file is absent or empty (a named absence, never zero arms). The buffer is
222// sized from the file and kept alive, because every string slot points into it.
223func br_load(path: *u8, hdr: *i64, arms: *i64) -> i64 {
224 let ln: *i64 = sys_mmap(BR_WORD * 2) as *i64
225 let b: *u8 = sys_read_file(path, ln)
226 if (b as i64) == 0 { br_init(hdr, arms); return 0 - 1 }
227 let n: i64 = ln[0]
228 if n <= 0 { br_init(hdr, arms); return 0 - 1 }
229 return br_parse(b, n, hdr, arms)
230}
231func br_ref_index(hdr: *i64, arms: *i64, n: i64) -> i64 {
232 let ref: *u8 = hdr[BR_H_REF] as *u8
233 if ref[0] == (0 as u8) { return 0 - 1 }
234 var i: i64 = 0
235 while i < n { if br_streq(arms[i * BR_STRIDE + BR_A_NAME] as *u8, ref) == 1 { return i } i = i + 1 }
236 return 0 - 1
237}
238// THE VERDICT. Re-derives per-arm VOID from the checksums (a VALID row whose checksum differs from the
239// reference arm's becomes VOID, whatever the file said), fills every VALID arm's ratio, and returns BR_V_*.
240func br_verdict(hdr: *i64, arms: *i64, n: i64) -> i64 {
241 if n <= 0 { return BR_V_EMPTY }
242 let r: i64 = br_ref_index(hdr, arms, n)
243 if r < 0 { return BR_V_UNMEASURABLE }
244 let rb: i64 = r * BR_STRIDE
245 if arms[rb + BR_A_STATUS] != BR_ST_VALID { return BR_V_UNMEASURABLE }
246 if arms[rb + BR_A_MED] <= 0 { return BR_V_UNMEASURABLE }
247 let refchk: i64 = arms[rb + BR_A_CHK]
248 let refmed: i64 = arms[rb + BR_A_MED]
249 var anyvoid: i64 = 0
250 var i: i64 = 0
251 while i < n {
252 let b: i64 = i * BR_STRIDE
253 arms[b + BR_A_RATIO] = BR_NO_RATIO
254 var st: i64 = arms[b + BR_A_STATUS]
255 if st == BR_ST_VALID { if arms[b + BR_A_CHK] != refchk { st = BR_ST_VOID; arms[b + BR_A_STATUS] = st } }
256 if st == BR_ST_VOID { anyvoid = 1 }
257 if st == BR_ST_VALID { arms[b + BR_A_RATIO] = (arms[b + BR_A_MED] * BR_PERMIL) / refmed }
258 i = i + 1
259 }
260 if anyvoid == 1 { return BR_V_VOID }
261 return BR_V_VALID
262}
263// "2.02x" from permil; a missing ratio prints a dash
264func br_ratio_text(permil: i64, dst: *u8, off: i64) -> i64 {
265 if permil < 0 { return br_put(dst, off, BR_MINUS) }
266 var o: i64 = br_catn(dst, off, permil / BR_PERMIL)
267 o = br_put(dst, o, BR_DOT)
268 let centi: i64 = (permil % BR_PERMIL) / BR_TEN
269 if centi < BR_TEN { o = br_put(dst, o, BR_ZERO) }
270 o = br_catn(dst, o, centi)
271 o = br_put(dst, o, BR_LOWER_X)
272 return o
273}
274// SERIALISE the canonical text. Returns the byte count; the writer checks it against cap. The header comment
275// carries the NX-DERIVED stamp so the memory plane and every reachability census see a regenerated artefact,
276// never authored memory.
277func br_write(dst: *u8, cap: i64, dom: *u8, hdr: *i64, arms: *i64, n: i64, verdict: i64) -> i64 {
278 var o: i64 = 0
279 o = br_put(dst, o, BR_HASH)
280 o = br_cat(dst, o, " " as *u8); o = br_cat(dst, o, dom)
281 o = br_cat(dst, o, ".bench -- NX-DERIVED: regenerated artefact, not authored memory. Written by " as *u8)
282 o = br_cat(dst, o, hdr[BR_H_WRITER] as *u8)
283 o = br_cat(dst, o, "; read by nx_bench_receipt_lib (both /compare generators and the gate share this one reader).\n" as *u8)
284 o = br_put(dst, o, BR_HASH)
285 o = br_cat(dst, o, " arm|name|toolchain|version|source|source_sha256|bin_bytes|bin_sha256|runs|min_us|median_us|checksum|status|note\n" as *u8)
286 o = br_put(dst, o, BR_HASH)
287 o = br_cat(dst, o, " every arm runs the SAME workload and must print the SAME checksum as the @ref arm or its row is VOID; a ratio is the median vs the @ref median.\n" as *u8)
288 o = br_cat(dst, o, "@title " as *u8); o = br_cat(dst, o, hdr[BR_H_TITLE] as *u8); o = br_put(dst, o, BR_NL)
289 o = br_cat(dst, o, "@workload " as *u8); o = br_cat(dst, o, hdr[BR_H_WORKLOAD] as *u8); o = br_put(dst, o, BR_NL)
290 o = br_cat(dst, o, "@host " as *u8); o = br_cat(dst, o, hdr[BR_H_HOST] as *u8); o = br_put(dst, o, BR_NL)
291 o = br_cat(dst, o, "@runs " as *u8); o = br_catn(dst, o, hdr[BR_H_RUNS]); o = br_put(dst, o, BR_NL)
292 o = br_cat(dst, o, "@ref " as *u8); o = br_cat(dst, o, hdr[BR_H_REF] as *u8); o = br_put(dst, o, BR_NL)
293 o = br_cat(dst, o, "@asof " as *u8); o = br_catn(dst, o, hdr[BR_H_ASOF]); o = br_put(dst, o, BR_NL)
294 o = br_cat(dst, o, "@repro " as *u8); o = br_cat(dst, o, hdr[BR_H_REPRO] as *u8); o = br_put(dst, o, BR_NL)
295 o = br_cat(dst, o, "@writer " as *u8); o = br_cat(dst, o, hdr[BR_H_WRITER] as *u8); o = br_put(dst, o, BR_NL)
296 o = br_cat(dst, o, "@verdict " as *u8); o = br_cat(dst, o, br_verdict_name(verdict)); o = br_put(dst, o, BR_NL)
297 var i: i64 = 0
298 while i < n {
299 let b: i64 = i * BR_STRIDE
300 if o + BR_ROW_RESERVE > cap { return o }
301 o = br_cat(dst, o, "arm|" as *u8); o = br_cat(dst, o, arms[b + BR_A_NAME] as *u8)
302 o = br_put(dst, o, BR_PIPE); o = br_cat(dst, o, arms[b + BR_A_TOOL] as *u8)
303 o = br_put(dst, o, BR_PIPE); o = br_cat(dst, o, arms[b + BR_A_VER] as *u8)
304 o = br_put(dst, o, BR_PIPE); o = br_cat(dst, o, arms[b + BR_A_SRC] as *u8)
305 o = br_put(dst, o, BR_PIPE); o = br_cat(dst, o, arms[b + BR_A_SRCSHA] as *u8)
306 o = br_put(dst, o, BR_PIPE); o = br_catn(dst, o, arms[b + BR_A_BINBYTES])
307 o = br_put(dst, o, BR_PIPE); o = br_cat(dst, o, arms[b + BR_A_BINSHA] as *u8)
308 o = br_put(dst, o, BR_PIPE); o = br_catn(dst, o, arms[b + BR_A_RUNS])
309 o = br_put(dst, o, BR_PIPE); o = br_catn(dst, o, arms[b + BR_A_MIN])
310 o = br_put(dst, o, BR_PIPE); o = br_catn(dst, o, arms[b + BR_A_MED])
311 o = br_put(dst, o, BR_PIPE); o = br_catn(dst, o, arms[b + BR_A_CHK])
312 o = br_put(dst, o, BR_PIPE); o = br_cat(dst, o, br_status_name(arms[b + BR_A_STATUS]))
313 o = br_put(dst, o, BR_PIPE); o = br_cat(dst, o, arms[b + BR_A_NOTE] as *u8)
314 o = br_put(dst, o, BR_NL)
315 i = i + 1
316 }
317 return o
318}