nx_ioconfirm_checked_test_20260907.nx source
↩ module page · 316 lines · 15086 B
1// nx_ioconfirm.nx -- THE CONFIRMED I/O-STORM LEVEL: maintained continuously, read in constant time.
2// Rung DG7, /compare/degradation.
3//
4// WHY THIS EXISTS, MEASURED. The D-state witness that gates every build on this estate reads /proc/stat
5// ONCE. nx_blkprofile sampled 2,400 times at 100 ms on 2026-09-04 and found procs_blocked with median 4
6// against a bar of 8, p90 8, max 15, and 118 permil of SINGLE samples at or above the bar. So roughly one
7// build in eight is refused by a transient spike on a box whose sustained level is HALF the bar. Two
8// nx_dstate rosters 90 s apart shared only four pids: the D population is mostly churn over a small
9// persistent core.
10//
11// AND THE OBVIOUS FIX IS THE WRONG ONE, WHICH IS THE POINT OF THIS ORGAN. Making the gate take a median
12// AT DECISION TIME is already built and wired (ioa_measure_median, armed by two keys in build_admit.conf)
13// and the same run shows why it must not be armed: the refusal curve is STILL FALLING at a 12,000 ms span
14// (118 -> 36 permil) and has not flattened, so any span wide enough to help costs SECONDS on EVERY
15// admission check -- the clock dispatcher's pre-dispatch call included. That does not remove the stall, it
16// relocates it onto every caller. build_admit.conf refuses arming for exactly this reason and asks for the
17// cost to be measured first. It now has been, and the answer is no.
18//
19// THIS IS THE AEROSPACE ANSWER INSTEAD. Flight control does not confirm a fault inside the control law; a
20// monitor confirms CONTINUOUSLY and the law reads an already-confirmed state. So: a beat pays the whole
21// confirmation window once per cadence, off the critical path, and every consumer reads one small file in
22// constant time. The window costs the beat its span and costs the consumer nothing.
23//
24// FRESHNESS IS PART OF THE ANSWER, NOT A FOOTNOTE. A stale level is WORSE than none: it decides with
25// authority about a box it last saw minutes ago. `read` returns FRESH, STALE and ABSENT as three distinct
26// exits so a consumer that cannot get FRESH falls back to its own single sample -- degrade to the
27// incumbent, never acquit on a reading nobody took.
28//
29// KEY NAMES ARE DELIBERATELY NOT build_admit.conf's. That conf is parsed by PLAIN SUBSTRING with no
30// comment handling, and its own header records a measured incident where prose describing a key ARMED it.
31// This file uses confirm_samples and confirm_gap_ms so its bytes can never be mistaken for that envelope.
32//
33// COMPOSES, DOES NOT RE-IMPLEMENT: ioa_measure_median is the same sampler nx_build_admit would use if it
34// were armed, so the level published here is the level that gate would have computed -- one ruler, not two.
35
36import "nx_syscalls.nx"
37import "nx_ioadmit_lib.nx"
38import "nx_atomic_rewrite.nx"
39
40const IC_STDOUT: i64 = 1
41const IC_STDERR: i64 = 2
42const IC_OUTCAP: i64 = 8192
43const IC_MEAS_BYTES: i64 = 64
44const IC_BOX_BYTES: i64 = 64
45const IC_MODE_644: i64 = 420
46const IC_UNREADABLE: i64 = 0 - 1
47const IC_EXIT_STALE: i64 = 1
48const IC_EXIT_USAGE: i64 = 2
49const IC_EXIT_ABSENT: i64 = 3
50const IC_EXIT_UNMEASURED: i64 = 4
51const IC_EXIT_BUSY: i64 = 5
52const IC_LOCK_SUFFIX_BYTES: i64 = 5
53const IC_NUL_BYTES: i64 = 1
54// DEFAULTS ARE THE WIDEST SPAN ACTUALLY MEASURED, AND THAT IS A FLOOR RATHER THAN AN OPTIMUM: the DG1 run
55// stopped at 12,000 ms with the curve still falling, so a wider window is likely better and is NOT yet
56// evidenced. A beat pays this span once per cadence, so widening it is cheap -- but it must be MEASURED
57// before it is claimed, and this constant is the last value that was.
58const IC_DEF_SAMPLES: i64 = 5
59const IC_DEF_GAP_MS: i64 = 3000
60// The freshness bound must exceed the producing cadence or the axis is blind by construction. Stated here
61// rather than assumed: at the estate's 300 s status cadence this leaves two whole missed beats of margin.
62const IC_DEF_MAX_AGE_S: i64 = 900
63const IC_STATUS: *u8 = "knowledge/status/ioconfirm.status"
64const IC_STATUS_UP: *u8 = "../knowledge/status/ioconfirm.status"
65const IC_CH_MINUS: i64 = 45
66const IC_CH_0: i64 = 48
67const IC_CH_9: i64 = 57
68const IC_CH_BEAT: i64 = 98
69const IC_CH_READ: i64 = 114
70const IC_KEY_TS: *u8 = "ts="
71const IC_KEY_CONF: *u8 = "blocked_confirmed="
72
73func ic_slen(s: *u8) -> i64 { var n: i64 = 0; while s[n] != (0 as u8) { n = n + 1 } return n }
74func ic_werr(s: *u8) -> i64 { sys_write(IC_STDERR, s, ic_slen(s)); return 0 }
75
76func ic_puts(b: *u8, off: i64, s: *u8) -> i64 {
77 var o: i64 = off
78 var j: i64 = 0
79 while s[j] != (0 as u8) { b[o] = s[j]; o = o + 1; j = j + 1 }
80 return o
81}
82
83func ic_puti(b: *u8, off: i64, v: i64) -> i64 {
84 var o: i64 = off
85 var x: i64 = v
86 if x < 0 { b[o] = IC_CH_MINUS as u8; o = o + 1; x = 0 - x }
87 var d: i64 = 1
88 var t: i64 = x
89 while t >= 10 { d = d * 10; t = t / 10 }
90 while d > 0 {
91 let q: i64 = x / d
92 b[o] = (IC_CH_0 + q) as u8
93 o = o + 1
94 x = x - q * d
95 d = d / 10
96 }
97 return o
98}
99
100func ic_atoi(s: *u8) -> i64 {
101 let n: i64 = ic_slen(s)
102 if n <= 0 { return IC_UNREADABLE }
103 var v: i64 = 0
104 var i: i64 = 0
105 var bad: i64 = 0
106 while i < n {
107 let c: i64 = s[i] as i64
108 if c < IC_CH_0 { bad = 1 }
109 if c > IC_CH_9 { bad = 1 }
110 if bad == 0 { v = v * 10 + (c - IC_CH_0) }
111 i = i + 1
112 }
113 if bad == 1 { return IC_UNREADABLE }
114 return v
115}
116
117func ic_now() -> i64 {
118 let tb: *i64 = sys_mmap(IC_BOX_BYTES) as *i64
119 tb[0] = 0
120 sys_clock_gettime_real(tb)
121 let t: i64 = tb[0]
122 sys_munmap(tb, IC_BOX_BYTES)
123 return t
124}
125
126// LINE-ANCHORED integer read: the value after `key` on the line that STARTS with key. Anchoring at the
127// line start is what stops a key matching inside another key's value or inside prose -- the estate has
128// lost a whole verdict to an unanchored match reading its own explanatory sentence as data.
129func ic_field(buf: *u8, n: i64, key: *u8) -> i64 {
130 let kl: i64 = ic_slen(key)
131 var p: i64 = 0
132 var res: i64 = IC_UNREADABLE
133 var atline: i64 = 1
134 while p < n {
135 if atline == 1 {
136 if p + kl <= n {
137 var m: i64 = 0
138 var hit: i64 = 1
139 while m < kl {
140 if buf[p + m] != key[m] { hit = 0 }
141 m = m + 1
142 }
143 if hit == 1 {
144 if res < 0 {
145 var q: i64 = p + kl
146 var v: i64 = 0
147 var got: i64 = 0
148 var stop: i64 = 0
149 while q < n {
150 let c: i64 = buf[q] as i64
151 if c < IC_CH_0 { stop = 1 }
152 if c > IC_CH_9 { stop = 1 }
153 if stop == 0 { v = v * 10 + (c - IC_CH_0); got = 1; q = q + 1 } else { q = n }
154 }
155 if got == 1 { res = v }
156 }
157 }
158 }
159 }
160 atline = 0
161 if buf[p] == (10 as u8) { atline = 1 }
162 p = p + 1
163 }
164 return res
165}
166
167func main(argc: i64, argv: *i64) -> i64 {
168 if argc < 2 {
169 ic_werr("usage: nx_ioconfirm beat [samples] [gap_ms] [outpath] | nx_ioconfirm read [path] [max_age_s]\n" as *u8)
170 sys_exit(IC_EXIT_USAGE)
171 return IC_EXIT_USAGE
172 }
173 let verb: *u8 = argv[1] as *u8
174 let ob: *u8 = sys_mmap(IC_OUTCAP)
175 var off: i64 = 0
176
177 if verb[0] == (IC_CH_BEAT as u8) {
178 var k: i64 = IC_DEF_SAMPLES
179 var gap: i64 = IC_DEF_GAP_MS
180 var path: *u8 = IC_STATUS
181 if argc > 2 { let a: *u8 = argv[2] as *u8; let v: i64 = ic_atoi(a); if v > 0 { k = v } }
182 if argc > 3 { let b: *u8 = argv[3] as *u8; let v2: i64 = ic_atoi(b); if v2 > 0 { gap = v2 } }
183 if argc > 4 { path = argv[4] as *u8 }
184 if k > IOA_MEDIAN_MAX_K {
185 ic_werr("nx_ioconfirm beat: samples exceeds IOA_MEDIAN_MAX_K, the bound the shared sampler enforces -- REFUSING\n" as *u8)
186 sys_exit(IC_EXIT_USAGE)
187 return IC_EXIT_USAGE
188 }
189 // Hold across sampling and commit: updated beats cannot overwrite in reverse completion order.
190 let lockpath: *u8 = sys_mmap(ic_slen(path)+IC_LOCK_SUFFIX_BYTES+IC_NUL_BYTES)
191 var lo: i64 = ic_puts(lockpath,0,path)
192 lo = ic_puts(lockpath,lo,".lock" as *u8); lockpath[lo] = 0 as u8
193 let lockfd: i64 = sys_openat_rdwr(lockpath,MODE_0644)
194 if lockfd < 0 { ic_werr("IOCONFIRM-BEAT verdict=PUBLICATION-FAILED reason=lock-open\n" as *u8); return IC_EXIT_UNMEASURED }
195 if sys_flock(lockfd,SYS_LOCK_EX | SYS_LOCK_NB) != 0 {
196 sys_close(lockfd)
197 ic_werr("IOCONFIRM-BEAT verdict=BUSY reason=writer-lock-unavailable status-not-written-by-this-beat\n" as *u8)
198 return IC_EXIT_BUSY
199 }
200 let mm: *i64 = sys_mmap(IC_MEAS_BYTES) as *i64
201 if ioa_measure_median(mm, k, gap) != 0 {
202 sys_close(lockfd)
203 ic_werr("nx_ioconfirm beat: /proc/stat UNREADABLE across the whole window -- writing NOTHING, because a status file nobody could measure would be read as a level\n" as *u8)
204 sys_exit(IC_EXIT_UNMEASURED)
205 return IC_EXIT_UNMEASURED
206 }
207 let ncpu: i64 = mm[0]
208 let conf: i64 = mm[1]
209 let got: i64 = mm[2]
210 var bar: i64 = IC_UNREADABLE
211 if ncpu > 0 { bar = ncpu * IOA_BLOCKED_PER_CPU }
212 off = ic_puts(ob, off, "ts=" as *u8); off = ic_puti(ob, off, ic_now())
213 off = ic_puts(ob, off, "\nncpu=" as *u8); off = ic_puti(ob, off, ncpu)
214 off = ic_puts(ob, off, "\nblocked_confirmed=" as *u8); off = ic_puti(ob, off, conf)
215 off = ic_puts(ob, off, "\nbar=" as *u8); off = ic_puti(ob, off, bar)
216 off = ic_puts(ob, off, "\nconfirm_samples=" as *u8); off = ic_puti(ob, off, got)
217 off = ic_puts(ob, off, "\nconfirm_requested=" as *u8); off = ic_puti(ob, off, k)
218 off = ic_puts(ob, off, "\nconfirm_gap_ms=" as *u8); off = ic_puti(ob, off, gap)
219 off = ic_puts(ob, off, "\nspan_ms=" as *u8); off = ic_puti(ob, off, (got - 1) * gap)
220 off = ic_puts(ob, off, "\nproducer=nx_ioconfirm\n" as *u8)
221 let commit_rc: i64 = atomic_rewrite_checked(path,ob,off)
222 let unlock_rc: i64 = sys_close(lockfd)
223 if commit_rc != 0 {
224 var eo: i64 = 0
225 let err: *u8 = sys_mmap(IC_OUTCAP)
226 eo = ic_puts(err,eo,"IOCONFIRM-BEAT verdict=PUBLICATION-FAILED rc=" as *u8)
227 eo = ic_puti(err,eo,commit_rc)
228 if commit_rc == AR_CHECK_UNCERTAIN { eo = ic_puts(err,eo," state=UNCERTAIN-after-rename inspect-path=" as *u8) }
229 else { eo = ic_puts(err,eo," state=NOT-COMMITTED-by-this-beat path=" as *u8) }
230 eo = ic_puts(err,eo,path); eo = ic_puts(err,eo,"\n" as *u8)
231 sys_write(IC_STDERR,err,eo)
232 return IC_EXIT_UNMEASURED
233 }
234 if unlock_rc != 0 {
235 ic_werr("IOCONFIRM-BEAT verdict=PUBLICATION-UNCERTAIN reason=lock-close-after-commit inspect-status\n" as *u8)
236 return IC_EXIT_UNMEASURED
237 }
238 let w: i64 = off
239 // THE RECEIPT ANNOUNCES ITS OWN WRITE. A publisher that does not say how many bytes it wrote turns
240 // "did my write land?" into a hunt instead of a number.
241 var o2: i64 = 0
242 let rb: *u8 = sys_mmap(IC_OUTCAP)
243 o2 = ic_puts(rb, o2, "IOCONFIRM-BEAT wrote=" as *u8); o2 = ic_puti(rb, o2, w)
244 o2 = ic_puts(rb, o2, " of=" as *u8); o2 = ic_puti(rb, o2, off)
245 o2 = ic_puts(rb, o2, " blocked_confirmed=" as *u8); o2 = ic_puti(rb, o2, conf)
246 o2 = ic_puts(rb, o2, " bar=" as *u8); o2 = ic_puti(rb, o2, bar)
247 o2 = ic_puts(rb, o2, " samples=" as *u8); o2 = ic_puti(rb, o2, got)
248 o2 = ic_puts(rb, o2, " span_ms=" as *u8); o2 = ic_puti(rb, o2, (got - 1) * gap)
249 o2 = ic_puts(rb, o2, " path=" as *u8); o2 = ic_puts(rb, o2, path)
250 o2 = ic_puts(rb, o2, "\nverdict=MEASURED\n" as *u8)
251 sys_write(IC_STDOUT, rb, o2)
252 if w != off { return IC_EXIT_UNMEASURED }
253 return 0
254 }
255
256 if verb[0] != (IC_CH_READ as u8) {
257 ic_werr("usage: nx_ioconfirm beat [samples] [gap_ms] [outpath] | nx_ioconfirm read [path] [max_age_s]\n" as *u8)
258 sys_exit(IC_EXIT_USAGE)
259 return IC_EXIT_USAGE
260 }
261
262 var maxage: i64 = IC_DEF_MAX_AGE_S
263 var rpath: *u8 = IC_STATUS
264 var explicit: i64 = 0
265 if argc > 2 { rpath = argv[2] as *u8; explicit = 1 }
266 if argc > 3 { let c: *u8 = argv[3] as *u8; let v3: i64 = ic_atoi(c); if v3 > 0 { maxage = v3 } }
267 let box: *i64 = sys_mmap(IC_BOX_BYTES) as *i64
268 box[0] = 0
269 var src: *u8 = rpath
270 var buf: *u8 = sys_read_file(rpath, box)
271 // TWO ROOTS when the caller did not name one: a bare path is CWD-relative and this estate runs organs
272 // from both the serving root and buildroot/. An explicit path is honoured exactly as given.
273 if box[0] <= 0 { if explicit == 0 { box[0] = 0; src = IC_STATUS_UP; buf = sys_read_file(IC_STATUS_UP, box) } }
274 let n: i64 = box[0]
275 if n <= 0 {
276 off = ic_puts(ob, off, "IOCONFIRM-READ verdict=ABSENT path=" as *u8)
277 off = ic_puts(ob, off, rpath)
278 off = ic_puts(ob, off, " -- no confirmed level exists. A CONSUMER MUST FALL BACK TO ITS OWN SINGLE SAMPLE:\n absence is not a quiet box, it is an unmeasured one, and it must never read as headroom.\n" as *u8)
279 sys_write(IC_STDOUT, ob, off)
280 sys_exit(IC_EXIT_ABSENT)
281 return IC_EXIT_ABSENT
282 }
283 let ts: i64 = ic_field(buf, n, IC_KEY_TS)
284 let conf: i64 = ic_field(buf, n, IC_KEY_CONF)
285 let now: i64 = ic_now()
286 var age: i64 = IC_UNREADABLE
287 if ts > 0 { age = now - ts }
288 off = ic_puts(ob, off, "IOCONFIRM-READ path=" as *u8); off = ic_puts(ob, off, src)
289 off = ic_puts(ob, off, " blocked_confirmed=" as *u8); off = ic_puti(ob, off, conf)
290 off = ic_puts(ob, off, " ts=" as *u8); off = ic_puti(ob, off, ts)
291 off = ic_puts(ob, off, " age_s=" as *u8); off = ic_puti(ob, off, age)
292 off = ic_puts(ob, off, " max_age_s=" as *u8); off = ic_puti(ob, off, maxage)
293 if conf < 0 {
294 off = ic_puts(ob, off, " verdict=ABSENT -- the file exists and carries no readable level\n" as *u8)
295 sys_write(IC_STDOUT, ob, off)
296 sys_exit(IC_EXIT_ABSENT)
297 return IC_EXIT_ABSENT
298 }
299 // A NEGATIVE AGE IS NOT FRESH. A future stamp means clock skew or a forged write, and both are
300 // unobservable rather than healthy -- the flattering reading is the one that must be refused.
301 if age < 0 {
302 off = ic_puts(ob, off, " verdict=STALE reason=future-timestamp-clock-skew-or-forged\n" as *u8)
303 sys_write(IC_STDOUT, ob, off)
304 sys_exit(IC_EXIT_STALE)
305 return IC_EXIT_STALE
306 }
307 if age > maxage {
308 off = ic_puts(ob, off, " verdict=STALE -- older than the freshness bound. FALL BACK to a single sample.\n" as *u8)
309 sys_write(IC_STDOUT, ob, off)
310 sys_exit(IC_EXIT_STALE)
311 return IC_EXIT_STALE
312 }
313 off = ic_puts(ob, off, " verdict=FRESH\n" as *u8)
314 sys_write(IC_STDOUT, ob, off)
315 return 0
316}