nx_dstate_gate.nx source

1// nx_dstate_gate.nx -- THE GATE FOR nx_dstate'S ADMISSION CEILING: conf-sourced, announced, and bitten. 2// 3// SUBJECT: the nx_dstate ELF, forked for real. nx_dstate's contract is a FOUR-STATE EXIT -- 0 SAMPLED / 4// 3 UNMEASURED / 4 ADMISSION-REFUSED -- and /api/gate_run derives verdicts from exit codes, so every tooth 5// here asserts an EXIT CODE, and the content teeth additionally read what the subject printed. 6// 7// WHY THIS GATE EXISTS (2026-08-22): nx_dstate has read `admit_load_centi` from knowledge/dstate.conf since 8// 2026-08-14 and PRINTED its source on every run -- and knowledge/dstate.conf never existed in either 9// knowledge tree, so every run in the organ's history executed on its built-in default while the header 10// promised a conf. A documented knob with no file behind it is a magic number with a nicer comment. The 11// conf now exists; this gate is what keeps it load-bearing: a conf-sourced ceiling must be READ, ANNOUNCED 12// as `src=conf path=<the file actually read>`, and must CHANGE BEHAVIOUR -- a ceiling below the measured 13// load refuses the walk (exit 4), a ceiling above it admits (exit 0). An absent conf falls back to the 14// built-in AND SAYS SO (`src=builtin-default`), because a refusal to look and a fallback must never be silent. 15// 16// THE ANTI-VACUITY TOOTH IS T2: it asserts the low fixture's ceiling is actually BELOW the measured load, 17// read from the subject's own output. Without it, T3's "refuses" could pass on a box whose load happened to 18// be zero -- for the wrong reason. A RIGHT EXIT CODE FOR THE WRONG REASON IS THE MOST EASILY ACCEPTED 19// FALSE PROOF THERE IS. 20// 21// THE NEGATIVE CONTROLS are gv_bite pairs: (absent conf announces builtin) vs (present conf does not), and 22// (user_hz from conf is echoed) vs (no user_hz row leaves the default). A guard that announces builtin on 23// every run would pass the first half of each pair and fail the second. 24// 25// FIXTURES ARE ASSEMBLED AT RUNTIME under /tmp/nx_dstate_gate/ and nothing here shares a fixture with a 26// production beat (the production conf is knowledge/dstate.conf; this gate never reads or writes it). 27// Subject outputs are unlinked at SETUP -- a gate that is not idempotent reports on its first run and lies 28// about every run after. 29// 30// license_tier: ORIGINAL No hw writes (Rule 26). expect_exit: 0 31import "nx_syscalls.nx" 32import "nx_gate_verdict.nx" 33import "nx_tool_run.nx" 34 35const DG_SUBJECT_DEFAULT: *u8 = "_offc/nx_dstate.elf" 36 37// ---- nx_dstate's exit contract, RESTATED here so a change to it breaks this gate loudly ---- 38const DG_EXIT_SAMPLED: i64 = 0 39const DG_EXIT_UNMEASURED: i64 = 3 40const DG_EXIT_REFUSED: i64 = 4 41const DG_EXEC_FAILED: i64 = 127 42 43// ---- fixtures ---- 44const DG_DIR: *u8 = "/tmp/nx_dstate_gate" 45const DG_CONF_LOW: *u8 = "/tmp/nx_dstate_gate/low.conf" 46const DG_CONF_HIGH: *u8 = "/tmp/nx_dstate_gate/high.conf" 47const DG_CONF_HZ: *u8 = "/tmp/nx_dstate_gate/hz.conf" 48const DG_CONF_ABSENT: *u8 = "/tmp/nx_dstate_gate/does_not_exist.conf" 49// A ceiling of ZERO centi-load is below any measurable positive load BY CONSTRUCTION -- T2 asserts the box 50// actually measured above it, so the fixture is proven to have reached its condition rather than assumed. 51const DG_CEIL_BELOW_ANY_LOAD: i64 = 0 52// 10000.00 loadavg is not reachable on an 8-core host; it admits unconditionally so the walker RUNS. 53const DG_CEIL_UNREACHABLE: i64 = 1000000 54// any value that is NOT the organ's documented default proves the knob is read; 50 is chosen only because 55// it differs from 100 and still yields integer seconds from tick counts. 56const DG_HZ_NONDEFAULT: i64 = 50 57// nx_dstate.nx documents DS_ADMIT_DEFAULT = 1600 (2 x nx_ctxtop's 800: one pass, no window). Asserting the 58// printed built-in equals the documented one is a CONTRACT tooth: if someone changes the default without 59// changing the doc (or this gate), the gate says so. 60const DG_BUILTIN_CEIL_DOCUMENTED: i64 = 1600 61const DG_HZ_DEFAULT_DOCUMENTED: i64 = 100 62 63const DG_CAPTURE_CAP: i64 = 262144 64const DG_ARGV_SLOTS: i64 = 4 65const DG_WORD_BYTES: i64 = 8 66const DG_MODE_DIR: i64 = 493 // 0755 67const DG_ASCII_ZERO: i64 = 48 68const DG_ASCII_NINE: i64 = 57 69const DG_DECIMAL: i64 = 10 70const DG_MISS: i64 = 0 - 1 71 72func dg_write_text(path: *u8, s: *u8) -> i64 { 73 var n: i64 = 0 74 while s[n] != 0 { n = n + 1 } 75 let fd: i64 = sys_openat_wr(path, MODE_0644) 76 if fd < 0 { return 0 - 1 } 77 let wr: i64 = sys_write(fd, s, n) 78 sys_close(fd) 79 if wr != n { return 0 - 1 } 80 return n 81} 82func dg_exists(path: *u8) -> i64 { 83 let lp: *i64 = sys_mmap(DG_WORD_BYTES*2) as *i64 84 let b: *u8 = sys_read_file(path, lp) 85 if (b as i64) == 0 { return 0 } 86 return 1 87} 88// run `<subject> <confpath>` and capture; returns the child exit code or a negative harness sentinel 89func dg_run(subject: *u8, confpath: *u8, out: *u8, outlen: *i64) -> i64 { 90 let av: *i64 = sys_mmap(DG_WORD_BYTES*DG_ARGV_SLOTS) as *i64 91 av[0] = subject as i64 92 av[1] = confpath as i64 93 av[2] = 0 94 return tr_run_capture(subject, av, out, DG_CAPTURE_CAP, outlen) 95} 96// substring search over a captured buffer; 1 if present 97func dg_has(buf: *u8, n: i64, needle: *u8) -> i64 { 98 var nl: i64 = 0 99 while needle[nl] != 0 { nl = nl + 1 } 100 if nl == 0 { return 0 } 101 var i: i64 = 0 102 while i + nl <= n { 103 var k: i64 = 0 104 var ok: i64 = 1 105 while k < nl { if buf[i + k] != needle[k] { ok = 0; k = nl } else { k = k + 1 } } 106 if ok == 1 { return 1 } 107 i = i + 1 108 } 109 return 0 110} 111// the first integer immediately following the first occurrence of `key`; DG_MISS if absent 112func dg_int_after(buf: *u8, n: i64, key: *u8) -> i64 { 113 var kl: i64 = 0 114 while key[kl] != 0 { kl = kl + 1 } 115 var i: i64 = 0 116 while i + kl <= n { 117 var k: i64 = 0 118 var ok: i64 = 1 119 while k < kl { if buf[i + k] != key[k] { ok = 0; k = kl } else { k = k + 1 } } 120 if ok == 1 { 121 var p: i64 = i + kl 122 var v: i64 = 0 123 var digits: i64 = 0 124 var go: i64 = 1 125 while go == 1 { 126 if p >= n { go = 0 } else { 127 let c: i64 = (buf[p] & 255) as i64 128 if c < DG_ASCII_ZERO { go = 0 } 129 if c > DG_ASCII_NINE { go = 0 } 130 if go == 1 { v = v*DG_DECIMAL + (c - DG_ASCII_ZERO); digits = digits + 1; p = p + 1 } 131 } 132 } 133 if digits > 0 { return v } 134 return DG_MISS 135 } 136 i = i + 1 137 } 138 return DG_MISS 139} 140 141func main(argc: i64, argv: *i64) -> i64 { 142 let ctr: *i64 = gv_ctr() 143 gv_head("nx_dstate gate -- the admission ceiling is CONF-SOURCED, ANNOUNCED, and it changes behaviour" as *u8) 144 var subject: *u8 = DG_SUBJECT_DEFAULT 145 if argc >= 2 { subject = argv[1] as *u8 } 146 gv_puts(" subject: " as *u8) 147 gv_puts(subject) 148 gv_puts("\n\n" as *u8) 149 150 // ---- SETUP: mkdir, unlink anything a previous run left, write fixtures ---- 151 sys_mkdir(DG_DIR, DG_MODE_DIR) 152 sys_unlinkat(DG_CONF_LOW) 153 sys_unlinkat(DG_CONF_HIGH) 154 sys_unlinkat(DG_CONF_HZ) 155 sys_unlinkat(DG_CONF_ABSENT) 156 let w1: i64 = dg_write_text(DG_CONF_LOW, "# gate fixture -- a ceiling BELOW any measurable load\nadmit_load_centi=0\n" as *u8) 157 let w2: i64 = dg_write_text(DG_CONF_HIGH, "# gate fixture -- a ceiling no host reaches, so the walker RUNS\nadmit_load_centi=1000000\n" as *u8) 158 let w3: i64 = dg_write_text(DG_CONF_HZ, "# gate fixture -- unreachable ceiling + a NON-DEFAULT user_hz to prove the knob is read\nadmit_load_centi=1000000\nuser_hz=50\n" as *u8) 159 var setup: i64 = 0 160 if w1 > 0 { if w2 > 0 { if w3 > 0 { if dg_exists(DG_CONF_ABSENT) == 0 { setup = 1 } } } } 161 gv_check("setup-fixtures-written-and-absent-fixture-really-absent" as *u8, setup, ctr) 162 163 let cap1: *u8 = sys_mmap(DG_CAPTURE_CAP) 164 let cap3: *u8 = sys_mmap(DG_CAPTURE_CAP) 165 let cap5: *u8 = sys_mmap(DG_CAPTURE_CAP) 166 let cap7: *u8 = sys_mmap(DG_CAPTURE_CAP) 167 let ol: *i64 = sys_mmap(DG_WORD_BYTES*2) as *i64 168 169 // ---- T1: unreachable ceiling from a conf -> the walker RUNS, verdict SAMPLED, source announced ---- 170 let rc1: i64 = dg_run(subject, DG_CONF_HIGH, cap1, ol) 171 let n1: i64 = ol[0] 172 gv_puts(" [T1] high-ceiling conf rc=" as *u8) 173 gv_num(rc1) 174 gv_puts(" bytes=" as *u8) 175 gv_num(n1) 176 gv_puts("\n" as *u8) 177 var t1: i64 = 0 178 if rc1 == DG_EXIT_SAMPLED { if dg_has(cap1, n1, "verdict=SAMPLED" as *u8) == 1 { if dg_has(cap1, n1, "-- D-STATE" as *u8) == 1 { if dg_has(cap1, n1, "partition=RECONCILES" as *u8) == 1 { t1 = 1 } } } } 179 gv_check("conf-ceiling-above-load-admits-and-the-walker-runs (SAMPLED, roster printed, partition reconciles)" as *u8, t1, ctr) 180 var t1b: i64 = 0 181 if dg_has(cap1, n1, "src=conf" as *u8) == 1 { if dg_has(cap1, n1, "path=/tmp/nx_dstate_gate/high.conf" as *u8) == 1 { t1b = 1 } } 182 gv_check("announces-src=conf-and-names-the-file-actually-read" as *u8, t1b, ctr) 183 184 // ---- T2: ANTI-VACUITY -- the low fixture's ceiling is BELOW the measured load ---- 185 let load: i64 = dg_int_after(cap1, n1, "load_centi=" as *u8) 186 gv_puts(" [T2] measured load_centi=" as *u8) 187 gv_num(load) 188 gv_puts(" low-fixture ceiling=" as *u8) 189 gv_num(DG_CEIL_BELOW_ANY_LOAD) 190 gv_puts("\n" as *u8) 191 var t2: i64 = 0 192 if load != DG_MISS { if load > DG_CEIL_BELOW_ANY_LOAD { t2 = 1 } } 193 gv_check("anti-vacuity-low-fixture-is-genuinely-below-the-measured-load" as *u8, t2, ctr) 194 195 // ---- T3: ceiling below load -> REFUSES TO WALK, exit 4, and still names its source ---- 196 let rc3: i64 = dg_run(subject, DG_CONF_LOW, cap3, ol) 197 let n3: i64 = ol[0] 198 gv_puts(" [T3] low-ceiling conf rc=" as *u8) 199 gv_num(rc3) 200 gv_puts("\n" as *u8) 201 var t3: i64 = 0 202 if rc3 == DG_EXIT_REFUSED { if dg_has(cap3, n3, "verdict=REFUSED" as *u8) == 1 { if dg_has(cap3, n3, "src=conf" as *u8) == 1 { t3 = 1 } } } 203 gv_check("conf-ceiling-below-load-refuses-to-walk (exit 4, verdict=REFUSED, src still announced)" as *u8, t3, ctr) 204 205 // ---- T4: REFUSED and SAMPLED are DIFFERENT exit codes. "I refused to look" and "I looked and found 206 // nothing blocked" must never share an outcome; here both were observed and they differ. ---- 207 var t4: i64 = 0 208 if rc3 == DG_EXIT_REFUSED { if rc1 == DG_EXIT_SAMPLED { if rc3 != rc1 { t4 = 1 } } } 209 gv_check("refused-exit-4-and-sampled-exit-0-are-distinct-observed-outcomes" as *u8, t4, ctr) 210 211 // ---- T5: ABSENT conf -> built-in default, ANNOUNCED, at the documented value ---- 212 let rc5: i64 = dg_run(subject, DG_CONF_ABSENT, cap5, ol) 213 let n5: i64 = ol[0] 214 let ceil5: i64 = dg_int_after(cap5, n5, "admit_ceiling=" as *u8) 215 gv_puts(" [T5] absent conf rc=" as *u8) 216 gv_num(rc5) 217 gv_puts(" admit_ceiling=" as *u8) 218 gv_num(ceil5) 219 gv_puts("\n" as *u8) 220 var t5: i64 = 0 221 if dg_has(cap5, n5, "src=builtin-default" as *u8) == 1 { if ceil5 == DG_BUILTIN_CEIL_DOCUMENTED { t5 = 1 } } 222 // with the built-in ceiling the verdict is whatever the live load says -- SAMPLED or REFUSED are both 223 // honest here; what is NOT acceptable is UNMEASURED or a failed exec. 224 var rc5ok: i64 = 0 225 if rc5 == DG_EXIT_SAMPLED { rc5ok = 1 } 226 if rc5 == DG_EXIT_REFUSED { rc5ok = 1 } 227 if rc5ok == 0 { t5 = 0 } 228 gv_check("absent-conf-falls-back-to-the-DOCUMENTED-builtin-AND-announces-src=builtin-default" as *u8, t5, ctr) 229 230 // ---- T6: the bite pair -- absent announces builtin; present does NOT ---- 231 var fired_on_bad: i64 = 0 232 if dg_has(cap5, n5, "src=builtin-default" as *u8) == 1 { fired_on_bad = 1 } 233 var fired_on_good: i64 = 0 234 if dg_has(cap1, n1, "src=builtin-default" as *u8) == 1 { fired_on_good = 1 } 235 gv_bite("neg-control-absent-conf-announces-builtin-and-present-conf-does-not" as *u8, fired_on_bad, fired_on_good, ctr) 236 237 // ---- T7: user_hz is READ from the conf (the header promised this knob for a week before it existed) ---- 238 let rc7: i64 = dg_run(subject, DG_CONF_HZ, cap7, ol) 239 let n7: i64 = ol[0] 240 let hz7: i64 = dg_int_after(cap7, n7, "user_hz=" as *u8) 241 let hz1: i64 = dg_int_after(cap1, n1, "user_hz=" as *u8) 242 gv_puts(" [T7] hz conf rc=" as *u8) 243 gv_num(rc7) 244 gv_puts(" user_hz(conf)=" as *u8) 245 gv_num(hz7) 246 gv_puts(" user_hz(no row)=" as *u8) 247 gv_num(hz1) 248 gv_puts("\n" as *u8) 249 var t7: i64 = 0 250 if rc7 == DG_EXIT_SAMPLED { if hz7 == DG_HZ_NONDEFAULT { t7 = 1 } } 251 gv_check("user_hz-row-in-conf-is-read-and-announced" as *u8, t7, ctr) 252 var hz_bad: i64 = 0 253 if hz7 == DG_HZ_NONDEFAULT { hz_bad = 1 } 254 var hz_good: i64 = 0 255 if hz1 == DG_HZ_NONDEFAULT { hz_good = 1 } 256 // the "good" half also pins the documented default when no row is present 257 if hz1 != DG_HZ_DEFAULT_DOCUMENTED { hz_good = 1 } 258 gv_bite("neg-control-user_hz-follows-the-conf-row-and-defaults-to-the-documented-100-without-it" as *u8, hz_bad, hz_good, ctr) 259 260 // ---- T9: the subject must actually have RUN ---- 261 var ran: i64 = 1 262 if rc1 < 0 { ran = 0 } 263 if rc1 == DG_EXEC_FAILED { ran = 0 } 264 gv_check("neg-control-subject-actually-executed (not 127, not a harness sentinel)" as *u8, ran, ctr) 265 266 let rc: i64 = gv_verdict("DSTATE" as *u8, ctr, "the ceiling is data, the source is announced, and refusing is a different exit from sampling" as *u8) 267 sys_exit(rc) 268 return rc 269}