nx_genver.nx source
↩ module page · 121 lines · 5089 B
1// nx_genver.nx -- shared differential-verification reporting for the sovereign gen migration.
2//
3// Every op organ in this lane answers the same question -- "does our result match the oracle's,
4// and by how much" -- so the tolerance ladder, the comparison rule and the report format live
5// here rather than being re-typed per organ. The previous generation of verify organs each
6// carried its own copy, which is why they drifted apart in tolerance and in what they printed,
7// and why no two of them could be compared.
8//
9// WHY A DISTRIBUTION AND NOT A VERDICT
10// A bare PASS cannot tell the next change whether it moved the number. These organs report the
11// error distribution across five decades, so a later tweak is measurable against a banked
12// baseline instead of being graded on whether it still says GREEN.
13//
14// WHY THE PASS BAND IS AN ARGUMENT AND NOT A CONSTANT
15// Measured 2026-08-06: the oracle's `mul_mat` against a Q8_0 weight is NOT an f32 matmul. ggml
16// quantizes the ACTIVATIONS too and does a blocked integer dot, so it never computes
17// dequant(W) @ x. An exact f64 reference deviates from the oracle by ~0.52% median / 9.8% max on
18// a Z-Image qkv projection -- and the sovereign f32 organ reproduced that same distribution to
19// within 3 elements in 11,520, i.e. the sovereign matmul is right and the ORACLE is the lower
20// precision one. Hardcoding "GREEN below 1e-2" would fail a CORRECT implementation for being
21// more accurate than the thing it is graded against.
22// ★ A TOLERANCE IS A CLAIM ABOUT THE REFERENCE'S PRECISION, NOT THE IMPLEMENTATION'S.
23// So the caller states the band its comparison is entitled to; the full distribution is always
24// reported regardless, and the band used is echoed so a report can never hide which one it took.
25//
26// COUNTER LAYOUT (caller allocates 8 i64):
27// c[0..4] fail counts at 1e-1, 1e-2, 1e-3, 1e-4, 1e-5
28// c[5] elements checked
29// c[6] flat index of the first element to exceed the PASS band, or -1
30// c[7] pass-band index (0 = 1e-1 ... 4 = 1e-5)
31// license_tier: ORIGINAL
32
33import "nx_syscalls.nx"
34import "nx_f32.nx"
35import "nx_f32_div.nx"
36import "nx_f32_cvt.nx"
37import "nx_strconv.nx"
38
39const NX_GENVER_NTOL: i64 = 5
40const NX_GENVER_CSIZE: i64 = 8
41
42// emit "<label>=<value>\n" on stdout
43func nx_genver_emit(label: *u8, value: i64) -> i64 {
44 let line: *u8 = sys_mmap(192)
45 var lo: i64 = 0
46 var i: i64 = 0
47 while label[i] != (0 as u8) { line[lo] = label[i]; lo = lo + 1; i = i + 1 }
48 line[lo] = 0x3D; lo = lo + 1 // '='
49 let dec: *u8 = sys_mmap(32)
50 let nd: i64 = nx_strconv_format_i64(value, dec)
51 var k: i64 = 0
52 while k < nd { line[lo] = dec[k]; lo = lo + 1; k = k + 1 }
53 line[lo] = 0x0A; lo = lo + 1
54 return sys_write(1, line, lo)
55}
56
57// Fill the tolerance ladder: 1e-1, 1e-2, 1e-3, 1e-4, 1e-5 as f32 bit patterns.
58func nx_genver_tols(tol: *i64) -> i64 {
59 let one: i64 = nx_i32_to_f32(1)
60 tol[0] = nx_f32_div(one, nx_i32_to_f32(10))
61 tol[1] = nx_f32_div(one, nx_i32_to_f32(100))
62 tol[2] = nx_f32_div(one, nx_i32_to_f32(1000))
63 tol[3] = nx_f32_div(one, nx_i32_to_f32(10000))
64 tol[4] = nx_f32_div(one, nx_i32_to_f32(100000))
65 return 0
66}
67
68// |got - want| > tol * max(|want|, 1)
69//
70// Relative where the reference is large, absolute where it is near zero. A pure relative test
71// lets a reference value near zero manufacture an enormous ratio from a negligible absolute
72// difference, which reads as a catastrophic failure and is not one.
73func nx_genver_exceeds(got: i64, want: i64, tol: i64) -> i64 {
74 let one: i64 = nx_i32_to_f32(1)
75 let aw: i64 = want & 0x7FFFFFFF
76 var scale: i64 = one
77 if nx_f32_lt(one, aw) == 1 { scale = aw }
78 let thr: i64 = nx_f32_mul(tol, scale)
79 let d: i64 = nx_f32_sub(got, want) & 0x7FFFFFFF
80 if nx_f32_lt(thr, d) == 1 { return 1 }
81 return 0
82}
83
84func nx_genver_init(c: *i64, pass_idx: i64) -> i64 {
85 var i: i64 = 0
86 while i < NX_GENVER_CSIZE { c[i] = 0; i = i + 1 }
87 c[6] = 0 - 1
88 var p: i64 = pass_idx
89 if p < 0 { p = 0 }
90 if p >= NX_GENVER_NTOL { p = NX_GENVER_NTOL - 1 }
91 c[7] = p
92 return 0
93}
94
95// Score one element against the whole ladder.
96func nx_genver_tally(c: *i64, tol: *i64, got: i64, want: i64, flat_idx: i64) -> i64 {
97 var t: i64 = 0
98 while t < NX_GENVER_NTOL {
99 if nx_genver_exceeds(got, want, tol[t]) == 1 {
100 c[t] = c[t] + 1
101 if t == c[7] { if c[6] < 0 { c[6] = flat_idx } }
102 }
103 t = t + 1
104 }
105 c[5] = c[5] + 1
106 return 0
107}
108
109// Print the measurement. Returns 0 when nothing exceeds the caller's declared pass band.
110func nx_genver_report(c: *i64) -> i64 {
111 nx_genver_emit("checked" as *u8, c[5])
112 nx_genver_emit("fail_1e1" as *u8, c[0])
113 nx_genver_emit("fail_1e2" as *u8, c[1])
114 nx_genver_emit("fail_1e3" as *u8, c[2])
115 nx_genver_emit("fail_1e4" as *u8, c[3])
116 nx_genver_emit("fail_1e5" as *u8, c[4])
117 nx_genver_emit("pass_band_idx" as *u8, c[7])
118 nx_genver_emit("first_bad_at_pass_band" as *u8, c[6])
119 if c[c[7]] != 0 { return 1 }
120 return 0
121}