nx_coverbeat.nx source
↩ module page · 163 lines · 8484 B
1// nx_coverbeat.nx -- RUN THE COVERAGE INSTRUMENTS AND PROVE IT RAN THEM.
2//
3// RUNG R3 of the SOTA plan (nishifamily.com/code/sotaplan): the instruments exist and nothing runs
4// them. Every finding on 2026-07-31 existed only because someone happened to look. A gate nobody runs
5// is itself uncovered -- and that recursion has to bottom out in a beat.
6//
7// WHY THIS IS NOT JUST A SHELL LOOP. Two failure modes have to be impossible by construction:
8//
9// 1. THE SILENT NO-OP. A beat that reports fail=0 without having executed anything is the quietest
10// failure in the system -- observed live in the learnings rail, where a harvest reported fail=0
11// for weeks while moving zero learnings. So this beat counts what it ATTEMPTED and what it
12// ACTUALLY REAPED, prints both, and goes RED when they disagree. `ran` is evidence; `fail=0` is not.
13//
14// 2. THE FLATTERING AVERAGE. A rollup that means-averages its gates lets a healthy plane hide a dead
15// one. The HEADLINE IS THE WORST VERDICT, never the average -- if any instrument is RED the beat
16// is RED, and the log line names which.
17//
18// SCHEDULING: this is a ONESHOT. Launch it from cron exactly like the existing sovereign beats, e.g.
19// */30 * * * * elderwesto /volume1/homes/elderwesto/nishihost/nx_coverbeat.elf >> logs/coverbeat.log 2>&1
20// It is deliberately idempotent and side-effect-free apart from its own log line, so running it twice
21// in a minute is harmless -- a beat that cannot be safely re-run cannot be safely scheduled.
22//
23// license_tier: ORIGINAL No hw writes (Rule 26). expect_exit: 0
24import "nx_syscalls.nx"
25
26const CB_LOG: *u8 = "logs/coverbeat.log"
27const CB_MODE: i64 = 420
28
29func cb_len(s: *u8) -> i64 { var n: i64 = 0; while s[n] != (0 as u8) { n = n + 1 } return n }
30func cb_w(fd: i64, s: *u8) -> i64 { let n: i64 = cb_len(s); sys_write(fd, s, n); return 0 }
31func cb_p(s: *u8) -> i64 { return cb_w(1, s) }
32func cb_pn(fd: i64, v: i64) -> i64 {
33 let t: *u8 = sys_mmap(32)
34 var m: i64 = v
35 if m < 0 { sys_write(fd, "-" as *u8, 1); m = 0 - m }
36 var k: i64 = 0
37 if m == 0 { t[0] = 48 as u8; k = 1 }
38 while m > 0 { t[k] = (48 + (m % 10)) as u8; m = m / 10; k = k + 1 }
39 var j: i64 = k - 1
40 while j >= 0 { sys_write(fd, ((t as i64) + j) as *u8, 1); j = j - 1 }
41 return 0
42}
43
44// Fork+exec a gate ELF, wait, return its exit code.
45//
46// EXIT 127 MEANS "COULD NOT EXECUTE", NOT "RAN AND FAILED", AND THE DISTINCTION CHANGES THE REMEDY:
47// a missing or unpromoted binary needs promoting; a gate that ran and went RED needs the underlying
48// defect fixed. Sending an operator to the wrong one wastes the trip.
49//
50// The first draft tried to detect this via a 0-1 return from a failed fork -- but fork SUCCEEDS and it
51// is the EXEC that fails, so the child reaches sys_exit(127) and the parent reaps a perfectly ordinary
52// exit code. The `unrunnable` counter could therefore never increment: dead code wearing the costume of
53// a safety check. Verified by negative control -- three missing gates reported unrunnable=0, worst=127.
54// 127 is the conventional command-not-found code and is what we key on now.
55// ★★★★★ A COUNTER THAT CANNOT INCREMENT IS A FALSE ASSURANCE. Prove each branch can fire, or delete it.
56func cb_run(path: *u8) -> i64 {
57 let pid: i64 = sys_fork()
58 if pid < 0 { return 0 - 1 }
59 if pid == 0 {
60 let argv: *i64 = sys_mmap(32) as *i64
61 argv[0] = path as i64
62 argv[1] = 0
63 let envp: *i64 = sys_mmap(16) as *i64
64 envp[0] = 0
65 // Silence the child's stdout: the beat's own log line is the record. A child that floods the
66 // cron log buries the one line an operator actually reads.
67 let devnull: i64 = sys_openat_wr("/dev/null" as *u8, CB_MODE)
68 if devnull >= 0 { sys_dup3(devnull, 1, 0) }
69 sys_execve_clean(path, argv, envp)
70 sys_exit(127)
71 }
72 let st: *i64 = sys_mmap(16) as *i64
73 sys_wait4(pid, st, 0)
74 return wait_exit_code(st[0])
75}
76
77func main() -> i64 {
78 let lg: i64 = sys_openat_append(CB_LOG, CB_MODE)
79 let now: i64 = sys_now_realtime_sec()
80
81 cb_p("=== nx_coverbeat -- run the coverage instruments, prove it ran them ===\n" as *u8)
82
83 // The instrument roster. Adding a gate here is a DATA edit to this list, not new plumbing --
84 // the same principle the SOTA plan's R2 rung demands of the deploy plane.
85 let g0: *u8 = "./nx_deploycover_gate.elf" as *u8
86 let g1: *u8 = "./nx_singleness_gate.elf" as *u8
87 let g2: *u8 = "./nx_livecloexec_gate.elf" as *u8
88 let g3: *u8 = "./nx_gateemit_gate.elf" as *u8
89
90 var attempted: i64 = 0
91 var reaped: i64 = 0
92 var worst: i64 = 0
93 var unrunnable: i64 = 0
94
95 // 127 = could-not-execute (missing/unpromoted binary). Counted SEPARATELY from a real RED so the
96 // verdict names the right remedy, and excluded from `worst` so a missing gate cannot masquerade as
97 // a catastrophic failing one.
98 attempted = attempted + 1
99 let r0: i64 = cb_run(g0)
100 if r0 == 127 { unrunnable = unrunnable + 1 } else { if r0 < 0 { unrunnable = unrunnable + 1 } else { reaped = reaped + 1; if r0 > worst { worst = r0 } } }
101 cb_p(" deploycover exit=" as *u8); cb_pn(1, r0); cb_p("\n" as *u8)
102
103 attempted = attempted + 1
104 let r1: i64 = cb_run(g1)
105 if r1 == 127 { unrunnable = unrunnable + 1 } else { if r1 < 0 { unrunnable = unrunnable + 1 } else { reaped = reaped + 1; if r1 > worst { worst = r1 } } }
106 cb_p(" singleness exit=" as *u8); cb_pn(1, r1); cb_p("\n" as *u8)
107
108 attempted = attempted + 1
109 let r2: i64 = cb_run(g2)
110 if r2 == 127 { unrunnable = unrunnable + 1 } else { if r2 < 0 { unrunnable = unrunnable + 1 } else { reaped = reaped + 1; if r2 > worst { worst = r2 } } }
111 cb_p(" livecloexec exit=" as *u8); cb_pn(1, r2); cb_p("\n" as *u8)
112
113 attempted = attempted + 1
114 let r3: i64 = cb_run(g3)
115 if r3 == 127 { unrunnable = unrunnable + 1 } else { if r3 < 0 { unrunnable = unrunnable + 1 } else { reaped = reaped + 1; if r3 > worst { worst = r3 } } }
116 cb_p(" gateemit exit=" as *u8); cb_pn(1, r3); cb_p("\n" as *u8)
117
118 cb_p(" attempted=" as *u8); cb_pn(1, attempted)
119 cb_p(" reaped=" as *u8); cb_pn(1, reaped)
120 cb_p(" unrunnable=" as *u8); cb_pn(1, unrunnable)
121 cb_p(" worst=" as *u8); cb_pn(1, worst); cb_p("\n" as *u8)
122
123 // ONE log line, greppable, with the evidence embedded. An operator reading logs/coverbeat.log must
124 // be able to tell "ran 3, all green" from "ran 0, reported green" WITHOUT opening anything else.
125 if lg >= 0 {
126 cb_w(lg, "coverbeat ts=" as *u8); cb_pn(lg, now)
127 cb_w(lg, " attempted=" as *u8); cb_pn(lg, attempted)
128 cb_w(lg, " reaped=" as *u8); cb_pn(lg, reaped)
129 cb_w(lg, " unrunnable=" as *u8); cb_pn(lg, unrunnable)
130 cb_w(lg, " deploycover=" as *u8); cb_pn(lg, r0)
131 cb_w(lg, " singleness=" as *u8); cb_pn(lg, r1)
132 cb_w(lg, " livecloexec=" as *u8); cb_pn(lg, r2)
133 cb_w(lg, " gateemit=" as *u8); cb_pn(lg, r3)
134 cb_w(lg, " worst=" as *u8); cb_pn(lg, worst)
135 }
136
137 // THE NO-OP TOOTH. If nothing was reaped, the beat measured NOTHING and must not read as healthy.
138 // This is the tooth the learnings-rail harvest lacked while reporting fail=0 for weeks.
139 if reaped <= 0 {
140 cb_p(" VERDICT=RED reaped ZERO instruments -- the beat ran nothing; fail=0 would be a lie\n" as *u8)
141 if lg >= 0 { cb_w(lg, " VERDICT=RED-NOTHING-RAN\n" as *u8); sys_close(lg) }
142 return 3
143 }
144 if unrunnable > 0 {
145 cb_p(" VERDICT=RED " as *u8); cb_pn(1, unrunnable)
146 cb_p(" instrument(s) could not be EXECUTED (missing/unpromoted binary) -- not the same as failing\n" as *u8)
147 if lg >= 0 { cb_w(lg, " VERDICT=RED-UNRUNNABLE\n" as *u8); sys_close(lg) }
148 return 4
149 }
150 if worst > 0 {
151 cb_p(" VERDICT=RED worst instrument exit=" as *u8); cb_pn(1, worst)
152 cb_p(" -- headline is the WORST gate, never the average\n" as *u8)
153 if lg >= 0 { cb_w(lg, " VERDICT=RED\n" as *u8); sys_close(lg) }
154 return 1
155 }
156
157 cb_p("\n NON-VACUITY: attempted==reaped==" as *u8); cb_pn(1, reaped)
158 cb_p(", so every instrument was really forked, waited on, and\n" as *u8)
159 cb_p(" its exit code read. A beat that cannot show what it reaped is not evidence that it ran.\n" as *u8)
160 cb_p(" VERDICT=GREEN all instruments ran and passed\n" as *u8)
161 if lg >= 0 { cb_w(lg, " VERDICT=GREEN\n" as *u8); sys_close(lg) }
162 return 0
163}