nx_compare_beat.nx source
↩ module page · 270 lines · 13074 B
1// nx_compare_beat.nx -- THE CLOCK BEAT for the whole /compare surface (2026-08-08).
2//
3// WHY THIS EXISTS. /compare had NO beat. The hub sat 2.6 days stale (generated_unix 1786014355 while
4// the domain artifacts regenerated fine) because nx_compare_regen SKIPS the hub whenever
5// buildroot/knowledge/compare/registry is absent -- and that registry is only ever kept at
6// nishihost/knowledge/compare/registry. The skip does NOT increment fails, so the run still printed
7// "verdict=GREEN" while serving a stale index.
8// (STAR)A SKIP THAT DOES NOT COUNT AS A FAILURE IS A GREEN THAT MEANS NOTHING.
9//
10// WHAT IT DOES. Argless, because the clock execve's its organ with an EMPTY argv:
11// 1. refresh buildroot/knowledge/compare/registry FROM the nishihost SSOT, atomically (tmp+rename)
12// 2. fork the EXISTING nx_compare_regen.elf buildroot ../sites/nishifamily/compare/ (path RESOLVED)
13//
14// WHY THE REFRESH IS THE WHOLE POINT. nx_compare_regen deliberately refuses to emit the hub from a
15// possibly-stale buildroot snapshot ("it is multi-session contended on the laptop; regenerating from a
16// stale snapshot would clobber parallel additions"). That objection is REAL, and this does not waive
17// it -- it answers it: a copy taken one syscall before the run cannot be stale. The registry is itself
18// SELF-ASSEMBLED from the live hub + the local *.matrix union, so it is derived state, not a hand list.
19// This is exactly what feedback-nas-is-hub-laptop-is-worker prescribes: "if a regen SKIPS a surface
20// because the registry isn't synced here, the fix is to make the registry + assembler live on the NAS".
21//
22// COMPOSES, NEVER RE-IMPLEMENTS. The generator stays nx_swcompare_hub and the installer stays
23// nx_compare_regen: this organ adds a caller, not a second ruler. Domains AND hub come from one pass.
24//
25// FAILS CLOSED. An unreadable or EMPTY SSOT refuses (exit 2) rather than publishing an empty hub --
26// (STAR)REFUSE TO CALL AN EMPTY WORLD GREEN. A failed copy refuses (exit 3) WITHOUT running the regen,
27// so a half-written registry can never reach the emitter.
28//
29// license_tier: ORIGINAL No hw writes (Rule 26). expect_exit: 0
30import "nx_syscalls.nx"
31
32const CB_SSOT: *u8 = "knowledge/compare/registry"
33const CB_TMP: *u8 = "buildroot/knowledge/compare/registry.nxnew"
34const CB_DST: *u8 = "buildroot/knowledge/compare/registry"
35// RESOLVED AT RUNTIME, NEVER ASSUMED. nx_compare_regen.elf lives at the nishihost ROOT; "_offc/" was
36// the wrong guess, and fork+execve of a missing ELF exits 127 -- which would make this beat a SILENT
37// NO-OP that still reports success on every window.
38// (STAR)LS THE BINARY YOU FORK: AN ABSENT ARTIFACT MUST REFUSE, NEVER NO-OP.
39const CB_REGEN_A: *u8 = "nx_compare_regen.elf"
40const CB_REGEN_B: *u8 = "_offc/nx_compare_regen.elf"
41const CB_FLEET_A: *u8 = "nx_compare_rank_fleet.elf" // PR4: the fleet ranker forked after every GREEN regen
42const CB_FLEET_B: *u8 = "_offc/nx_compare_rank_fleet.elf"
43const CB_ROOT: *u8 = "buildroot"
44const CB_OUT: *u8 = "../sites/nishifamily/compare/"
45const CB_PATHENV: *u8 = "PATH=/usr/bin:/bin"
46
47// DEAD-MAN STAMP. knowledge/registry/cron_heartbeats.tsv reads "ts=" out of this file and compares its
48// age to max-age. Written ONLY after a GREEN regen, so a beat that starts failing goes STALE and the
49// watch reports it -- a stamp written unconditionally would report liveness while publishing nothing.
50// (STAR)A HEARTBEAT THAT BEATS ON FAILURE IS NOT A HEARTBEAT, IT IS A LIGHT THAT IS ALWAYS ON.
51const CB_STAMP: *u8 = "knowledge/status/compare_beat.stamp"
52
53const CB_MODE0644: i64 = 420 // 0644
54const CB_ARGVCAP: i64 = 64
55const CB_ENVPCAP: i64 = 16
56const CB_STCAP: i64 = 16
57const CB_NUMCAP: i64 = 24
58const CB_EXITSHIFT: i64 = 8
59const CB_EXITMASK: i64 = 255
60
61func cb_w(s: *u8) -> i64 { var n: i64 = 0; while s[n] != (0 as u8) { n = n + 1 } sys_write(1, s, n); return 0 }
62
63func cb_exists(p: *u8) -> i64 { let fd: i64 = sys_openat_rd(p); if fd < 0 { return 0 } sys_close(fd); return 1 }
64
65func cb_wfd(fd: i64, s: *u8) -> i64 { var n: i64 = 0; while s[n] != (0 as u8) { n = n + 1 } sys_write(fd, s, n); return 0 }
66
67func cb_nfd(fd: i64, v: i64) -> i64 {
68 var m: i64 = v
69 let t: *u8 = sys_mmap(CB_NUMCAP)
70 var k: i64 = 0
71 if m == 0 { t[0] = 48 as u8; k = 1 }
72 while m > 0 { t[k] = (48 + (m % 10)) as u8; m = m / 10; k = k + 1 }
73 let o: *u8 = sys_mmap(CB_NUMCAP)
74 var i: i64 = 0
75 while i < k { o[i] = t[k-1-i]; i = i + 1 }
76 sys_write(fd, o, k)
77 return 0
78}
79
80// Writes "compare_beat ts=<epoch>\n" (the format cron_watch already reads from cron_watch.stamp).
81// Returns 1 on write, 0 if the stamp could not be opened -- reported, never fatal: a beat that
82// regenerated the surface correctly must not be recorded RED because a stamp failed.
83//
84// v1 OF THIS FUNCTION CRASHED THE PARENT (2026-08-08, caught by running it). It walked a
85// `const CB_TSMARK: *u8 = "ts="` through a local `let p` and indexed p[i]. A string-literal const
86// substitutes INLINE, so the terminator never compares equal, the loop ran off its buffer, and the
87// process died AFTER the regen had already succeeded -- taking both the stamp and the final verdict
88// line with it while the surface looked perfectly published.
89// (STAR)A CRASH AFTER THE WORK IS DONE LOOKS EXACTLY LIKE SUCCESS FROM THE ARTIFACT SIDE.
90// The fix is the proven form: PASS the literal as a PARAMETER (cb_wfd) and never index it locally.
91// THE STAMP IS A HEARTBEAT, NOT A VERDICT (2026-08-24). It used to be written ONLY when the regen exited 0, so
92// while ANY domain refused to publish (six did, for days) the stamp aged for 3.03 days and every liveness
93// reader concluded the beat was dead -- while it was firing every 21600 s and publishing 149 artifacts a run.
94// A REFUSING RUN AND A MISSING RUN WERE INDISTINGUISHABLE FROM OUTSIDE. Now every run stamps: ts= carries
95// liveness (unchanged prefix, so ts= readers are unaffected), and regen_exit= / verdict= carry the outcome as
96// CONTENT, so the stamp can say alive-and-RED instead of saying nothing.
97// the pre-stamp: liveness of the DISPATCH, written before the regen is forked. Same file, same ts= prefix, a
98// phase= field instead of a verdict; the final cb_stamp overwrites it when the run survives to the end.
99func cb_stamp_started() -> i64 {
100 let fd: i64 = sys_openat_wr(CB_STAMP, CB_MODE0644)
101 if fd < 0 { return 0 }
102 cb_wfd(fd, "compare_beat ts=" as *u8)
103 cb_nfd(fd, sys_now_realtime_sec())
104 cb_wfd(fd, " phase=STARTED verdict=UNFINISHED (no final stamp yet: still running, or killed by the clock deadline)" as *u8)
105 let nl: *u8 = sys_mmap(4)
106 nl[0] = 10 as u8
107 sys_write(fd, nl, 1)
108 sys_close(fd)
109 return 1
110}
111func cb_stamp(code: i64) -> i64 {
112 let fd: i64 = sys_openat_wr(CB_STAMP, CB_MODE0644)
113 if fd < 0 { return 0 }
114 cb_wfd(fd, "compare_beat ts=" as *u8)
115 cb_nfd(fd, sys_now_realtime_sec())
116 cb_wfd(fd, " regen_exit=" as *u8)
117 cb_nfd(fd, code)
118 if code == 0 { cb_wfd(fd, " verdict=GREEN" as *u8) } else { cb_wfd(fd, " verdict=RED" as *u8) }
119 let nl: *u8 = sys_mmap(4)
120 nl[0] = 10 as u8
121 sys_write(fd, nl, 1)
122 sys_close(fd)
123 return 1
124}
125
126func cb_wn(v: i64) -> i64 {
127 var m: i64 = v
128 if m < 0 { cb_w("-" as *u8); m = 0 - m }
129 let t: *u8 = sys_mmap(CB_NUMCAP)
130 var k: i64 = 0
131 if m == 0 { t[0] = 48 as u8; k = 1 }
132 while m > 0 { t[k] = (48 + (m % 10)) as u8; m = m / 10; k = k + 1 }
133 let o: *u8 = sys_mmap(CB_NUMCAP)
134 var i: i64 = 0
135 while i < k { o[i] = t[k-1-i]; i = i + 1 }
136 sys_write(1, o, k)
137 return 0
138}
139
140func main() -> i64 {
141 cb_w("=== NX-COMPARE-BEAT -- refresh registry from SSOT, then regen the whole /compare surface ===\n" as *u8)
142
143 // 1. READ THE SSOT. Absent or empty => REFUSE, never publish an empty hub.
144 let lp: *i64 = sys_mmap(8) as *i64
145 lp[0] = 0
146 let data: *u8 = sys_read_file(CB_SSOT, lp)
147 if (data as i64) == 0 {
148 cb_w(" REFUSE: cannot read SSOT knowledge/compare/registry (regen NOT run)\n" as *u8)
149 sys_exit(2)
150 return 2
151 }
152 let n: i64 = lp[0]
153 if n <= 0 {
154 cb_w(" REFUSE: SSOT registry is EMPTY (regen NOT run)\n" as *u8)
155 sys_exit(2)
156 return 2
157 }
158
159 // 2. ATOMIC REFRESH of the buildroot copy: full write to .nxnew, then rename over.
160 let fd: i64 = sys_openat_wr(CB_TMP, CB_MODE0644)
161 if fd < 0 {
162 cb_w(" REFUSE: cannot open buildroot registry tmp for write (regen NOT run)\n" as *u8)
163 sys_exit(3)
164 return 3
165 }
166 var off: i64 = 0
167 while off < n {
168 let wr: i64 = sys_write(fd, (data as i64 + off) as *u8, n - off)
169 if wr <= 0 {
170 sys_close(fd)
171 cb_w(" REFUSE: short write to buildroot registry tmp (regen NOT run)\n" as *u8)
172 sys_exit(3)
173 return 3
174 }
175 off = off + wr
176 }
177 sys_close(fd)
178 if sys_renameat(CB_TMP, CB_DST) < 0 {
179 cb_w(" REFUSE: rename of buildroot registry failed (regen NOT run)\n" as *u8)
180 sys_exit(3)
181 return 3
182 }
183 cb_w(" registry refreshed from SSOT bytes=" as *u8)
184 cb_wn(n)
185 cb_w("\n" as *u8)
186
187 // 3. RESOLVE THE REGEN BINARY BEFORE FORKING. Refuse loudly if absent -- exit 127 from a failed
188 // execve is indistinguishable from a successful no-op run at this distance.
189 var regen: *u8 = CB_REGEN_A
190 if cb_exists(regen) == 0 {
191 regen = CB_REGEN_B
192 if cb_exists(regen) == 0 {
193 cb_w(" REFUSE: nx_compare_regen.elf not found in . or _offc/ (regen NOT run)\n" as *u8)
194 sys_exit(4)
195 return 4
196 }
197 }
198 cb_w(" regen binary resolved: " as *u8)
199 cb_w(regen)
200 cb_w("\n" as *u8)
201
202 // 3b. PRE-STAMP (2026-08-24): the clock SIGKILLs any dispatch that outlives one window, and every 21600 s row shares
203 // one next_due, so this beat fires inside a stampede on a saturated box and can die mid-regen. A kill before the
204 // final stamp used to be indistinguishable from a beat that never ran. Now the stamp says STARTED first; a
205 // reader that finds STARTED with no later verdict knows the beat fired and was killed, not that it is dead.
206 cb_stamp_started()
207 // 4. FORK THE EXISTING REGEN -- one ruler for domains AND hub.
208 let pid: i64 = sys_fork()
209 if pid == 0 {
210 let argv: *i64 = sys_mmap(CB_ARGVCAP) as *i64
211 argv[0] = regen as i64
212 argv[1] = CB_ROOT as i64
213 argv[2] = CB_OUT as i64
214 argv[3] = 0
215 let envp: *i64 = sys_mmap(CB_ENVPCAP) as *i64
216 envp[0] = CB_PATHENV as i64
217 envp[1] = 0
218 sys_execve(regen, argv, envp)
219 sys_exit(127)
220 }
221 let st: *i64 = sys_mmap(CB_STCAP) as *i64
222 st[0] = 0
223 sys_wait4(pid, st, 0)
224 let code: i64 = (st[0] >> CB_EXITSHIFT) & CB_EXITMASK
225
226 cb_w("NX-COMPARE-BEAT regen_exit=" as *u8)
227 cb_wn(code)
228 if code == 0 {
229 if cb_stamp(code) == 1 { cb_w(" stamp=WRITTEN" as *u8) } else { cb_w(" stamp=FAILED" as *u8) }
230 cb_w(" verdict=GREEN\n" as *u8)
231 // 5. RE-RANK THE FLEET ON THE SAME BEAT (PR4, operator 2026-08-18: "as we work and unlock
232 // work in parallel it is updating all our compare and we move together as a fleet"). The
233 // regen just re-MEASURED every watch symbol; the queue every seat reads must move in the same
234 // breath or two seats pick the same #1 in the drift window. Runs AFTER the GREEN stamp so a
235 // ranking hiccup can never make a good regen read stale; its own exit is announced, never
236 // folded into this verdict. Resolved at runtime; absent = REFUSED aloud, never a fake rank.
237 var fleet: *u8 = CB_FLEET_A
238 let ff: i64 = sys_openat_rd(fleet)
239 if ff >= 0 { sys_close(ff) } else {
240 let ff2: i64 = sys_openat_rd(CB_FLEET_B)
241 if ff2 >= 0 { sys_close(ff2); fleet = CB_FLEET_B } else { fleet = 0 as *u8 }
242 }
243 if (fleet as i64) == 0 {
244 cb_w(" RANK-FLEET REFUSED: nx_compare_rank_fleet.elf not found in . or _offc/ (queue NOT re-ranked this beat -- promote it)\n" as *u8)
245 } else {
246 let fpid: i64 = sys_fork()
247 if fpid == 0 {
248 let fav: *i64 = sys_mmap(CB_ARGVCAP) as *i64
249 fav[0] = fleet as i64
250 fav[1] = 0
251 let fenv: *i64 = sys_mmap(CB_ENVPCAP) as *i64
252 fenv[0] = CB_PATHENV as i64
253 fenv[1] = 0
254 sys_execve(fleet, fav, fenv)
255 sys_exit(127)
256 }
257 let fst: *i64 = sys_mmap(CB_STCAP) as *i64
258 fst[0] = 0
259 sys_wait4(fpid, fst, 0)
260 cb_w(" RANK-FLEET exit=" as *u8); cb_wn((fst[0] >> CB_EXITSHIFT) & CB_EXITMASK); cb_w(" (queue re-ranked on this beat)\n" as *u8)
261 }
262 sys_exit(0)
263 return 0
264 }
265 // RED still stamps (heartbeat), and the stamp's own content says RED -- see cb_stamp.
266 if cb_stamp(code) == 1 { cb_w(" stamp=WRITTEN-RED" as *u8) } else { cb_w(" stamp=FAILED" as *u8) }
267 cb_w(" verdict=RED\n" as *u8)
268 sys_exit(1)
269 return 1
270}