nx_absent.nx source
↩ module page · 250 lines · 13311 B
1// nx_absent.nx -- PROVE ABSENCE, OR REFUSE TO CLAIM IT. Sovereign, no shell, no client-side filtering.
2//
3// WHY THIS EXISTS, measured on myself 2026-08-07: three times in one day I ran a search, piped it through a
4// filter, saw no hits, and concluded the thing was ABSENT. Every time the tool had HONESTLY declared its own
5// partiality -- `NX-TRUNCATED OUTPUT-IS-PARTIAL capture_cap=163840`, `BUDGET-EXCEEDED partial=1`,
6// `coverage_complete=0` -- and every time my filter discarded that line before I read it. Once it made a grep
7// over 22,000 files read as a clean absence and I began doubting a correct census; once I was one step from
8// filing a sev-9 that was flatly untrue.
9// THE SEARCHER WAS NEVER THE DEFECT. THE READER WAS. So this organ does not re-implement search: it COMPOSES
10// nx_shelltool (already honest, already coverage-declaring) and moves the verdict OUT OF THE PAYLOAD AND INTO
11// THE EXIT CODE.
12// ★★★★★★ AN ADVISORY IN A PAYLOAD IS DISCARDABLE; AN EXIT CODE IS BRANCHED ON. If a fact must not be
13// ignored, it cannot live only in text that a caller is free to grep away.
14// ★★★★★ `matches=0` IS NOT ABSENCE -- IT IS ABSENCE *WITHIN WHATEVER WAS SCANNED*. Absence is a claim about
15// the WHOLE corpus, so it requires proof of complete coverage, and this organ will not issue that claim
16// without it.
17//
18// THREE STATES, because two would force a lie (the ecosystem's own law: a probe that cannot tell MET from
19// UNOBSERVABLE reports failure as success):
20// exit 0 ABSENT-PROVEN 0 matches AND coverage_complete=1 AND no truncation marker
21// exit 1 PRESENT >=1 match (the corpus contains it; absence is refuted)
22// exit 3 UNPROVEN coverage was partial -> NO CONCLUSION IS AVAILABLE, in either direction
23// exit 2 usage
24// UNPROVEN is deliberately NOT folded into either answer. Folding it into PRESENT would cry wolf; folding it
25// into ABSENT is exactly the mistake this organ was built to make impossible.
26//
27// usage: nx_absent <pattern> <dir> [ext]
28// license_tier: ORIGINAL Read-only: forks a read-only searcher, writes nothing. (Rule 26)
29import "nx_syscalls.nx"
30import "nx_tool_run.nx"
31
32const AB_SHELLTOOL: *u8 = "/volume1/homes/elderwesto/nishihost/nx_shelltool.elf"
33const AB_CAP: i64 = 1048576
34const AB_RC_PRESENT: i64 = 1
35const AB_RC_USAGE: i64 = 2
36const AB_RC_UNPROVEN: i64 = 3
37const AB_SHOW: i64 = 12 // matching lines echoed on PRESENT; the cap is printed
38
39func ab_puts(s: *u8) -> i64 { var n: i64 = 0; while s[n] != (0 as u8) { n = n + 1 } sys_write(1, s, n); return 0 }
40func ab_putn(v: i64) -> i64 {
41 let b: *u8 = sys_mmap(32)
42 let t: *u8 = sys_mmap(32)
43 var m: i64 = v
44 if m < 0 { sys_write(1, "-" as *u8, 1); m = 0 - m }
45 var k: i64 = 0
46 if m == 0 { t[0] = 48 as u8; k = 1 }
47 while m > 0 { t[k] = (48 + (m % 10)) as u8; m = m / 10; k = k + 1 }
48 var i: i64 = 0
49 while i < k { b[i] = t[k - 1 - i]; i = i + 1 }
50 sys_write(1, b, k)
51 return 0
52}
53func ab_at(buf: *u8, i: i64, n: i64, needle: *u8) -> i64 {
54 var k: i64 = 0
55 while needle[k] != (0 as u8) {
56 if i + k >= n { return 0 }
57 if buf[i + k] != needle[k] { return 0 }
58 k = k + 1
59 }
60 return 1
61}
62func ab_has(buf: *u8, n: i64, needle: *u8) -> i64 {
63 var i: i64 = 0
64 while i < n {
65 if ab_at(buf, i, n, needle) == 1 { return 1 }
66 i = i + 1
67 }
68 return 0
69}
70// integer immediately after `needle`, or -1 if the needle never appears. LAST occurrence wins, because the
71// envelope is emitted at the END of the transcript and an earlier match line may contain the same token.
72func ab_num_after(buf: *u8, n: i64, needle: *u8) -> i64 {
73 var found: i64 = 0 - 1
74 var i: i64 = 0
75 while i < n {
76 if ab_at(buf, i, n, needle) == 1 {
77 var j: i64 = i
78 while needle[j - i] != (0 as u8) { j = j + 1 }
79 var v: i64 = 0
80 var got: i64 = 0
81 while j < n {
82 let c: i64 = buf[j] as i64
83 if c < 48 { j = n }
84 else {
85 if c > 57 { j = n }
86 else { v = v * 10 + (c - 48); got = 1; j = j + 1 }
87 }
88 }
89 if got == 1 { found = v }
90 }
91 i = i + 1
92 }
93 return found
94}
95
96func main(argc: i64, argv: *i64) -> i64 {
97 if argc < 3 {
98 ab_puts("usage: nx_absent <pattern> <dir> [ext]\n" as *u8)
99 ab_puts(" exit 0 ABSENT-PROVEN | 1 PRESENT | 3 UNPROVEN (partial coverage -- no conclusion) | 2 usage\n" as *u8)
100 ab_puts(" matches=0 alone is NOT absence: it is absence within whatever was scanned.\n" as *u8)
101 return AB_RC_USAGE
102 }
103 let pat: *u8 = argv[1] as *u8
104 let dir: *u8 = argv[2] as *u8
105
106 let av: *i64 = sys_mmap(64) as *i64
107 av[0] = AB_SHELLTOOL as i64
108 av[1] = "grep" as *u8 as i64
109 av[2] = pat as i64
110 av[3] = dir as i64
111 if argc >= 4 { av[4] = argv[3]; av[5] = 0 }
112 else { av[4] = 0 }
113
114 let out: *u8 = sys_mmap(AB_CAP + 1)
115 let olen: *i64 = sys_mmap(16) as *i64
116 let rc: i64 = tr_run_capture(AB_SHELLTOOL, av, out, AB_CAP, olen)
117 let n: i64 = olen[0]
118
119 // A HARNESS FAILURE IS NOT AN ABSENCE EITHER. If the searcher could not be run at all we know nothing,
120 // so this is UNPROVEN -- never 0.
121 if rc < 0 {
122 ab_puts("NX-ABSENT verdict=UNPROVEN reason=harness-failure rc=" as *u8); ab_putn(rc)
123 ab_puts(" (could not run the searcher -- no conclusion in either direction)\n" as *u8)
124 return AB_RC_UNPROVEN
125 }
126 if rc == 127 {
127 ab_puts("NX-ABSENT verdict=UNPROVEN reason=searcher-not-found path=" as *u8); ab_puts(AB_SHELLTOOL)
128 ab_puts("\n" as *u8)
129 return AB_RC_UNPROVEN
130 }
131
132 let matches: i64 = ab_num_after(out, n, "matches=" as *u8)
133 let complete: i64 = ab_num_after(out, n, "coverage_complete=" as *u8)
134 let cc: i64 = ab_num_after(out, n, "corpus_complete=" as *u8) // -1 = producer does not emit it
135 // KNOWN IMPRECISION, STATED RATHER THAN DISCOVERED LATER: this marker scan reads the WHOLE capture and
136 // cannot tell an envelope line from match CONTENT, so searching FOR one of these strings sets trunc=1
137 // from the hits themselves (observed: pattern "BUDGET-EXCEEDED" -> matches=15 corpus_complete=1
138 // truncated=1). It is HARMLESS BY ORDERING, not by luck: a false trunc needs matches>0, and matches>0
139 // short-circuits to PRESENT before trunc is consulted; with 0 matches no match line exists to trip it,
140 // so only a real envelope marker can fire. Now that corpus_complete exists and is preferred, this path
141 // is fallback-only. ★DOCUMENT THE IMPRECISION YOU CHOSE TO LIVE WITH, OR THE NEXT READER WILL TRUST IT
142 // AS EXACT.
143 var trunc: i64 = 0
144 if ab_has(out, n, "NX-TRUNCATED" as *u8) == 1 { trunc = 1 }
145 if ab_has(out, n, "OUTPUT-IS-PARTIAL" as *u8) == 1 { trunc = 1 }
146 if ab_has(out, n, "BUDGET-EXCEEDED" as *u8) == 1 { trunc = 1 }
147 if ab_has(out, n, "partial=1" as *u8) == 1 { trunc = 1 }
148
149 ab_puts("NX-ABSENT pattern=" as *u8); ab_puts(pat)
150 ab_puts(" dir=" as *u8); ab_puts(dir)
151 ab_puts(" matches=" as *u8); ab_putn(matches)
152 ab_puts(" coverage_complete=" as *u8); ab_putn(complete)
153 ab_puts(" corpus_complete=" as *u8); ab_putn(cc)
154 ab_puts(" truncated=" as *u8); ab_putn(trunc)
155 ab_puts(" searcher_exit=" as *u8); ab_putn(rc)
156 ab_puts(" captured_bytes=" as *u8); ab_putn(n)
157 ab_puts("\n" as *u8)
158
159 // ORDER MATTERS AND IS DELIBERATE: partiality is checked BEFORE the match count, because a truncated
160 // scan that happened to find something still cannot support an ABSENCE claim -- and more importantly a
161 // truncated scan that found NOTHING must never reach the 0-branch.
162 // MY OWN CAPTURE LIMIT IS A COVERAGE LIMIT TOO -- checked FIRST, because it is the one the searcher
163 // cannot tell me about. If tr_run_capture filled the buffer, the tail of the transcript (which is where
164 // the envelope LIVES) may never have arrived, so matches= and coverage_complete= are themselves suspect.
165 // I built this organ to stop trusting a partial read and would have shipped it trusting my own.
166 // ★A GUARD THAT POLICES ITS INPUT SOURCE BUT NOT ITS OWN BUFFER HAS MOVED THE BLIND SPOT, NOT CLOSED IT.
167 if n >= AB_CAP {
168 ab_puts(" verdict=UNPROVEN reason=capture-full captured=" as *u8); ab_putn(n)
169 ab_puts(" cap=" as *u8); ab_putn(AB_CAP)
170 ab_puts(" -- MY capture buffer filled, so the searcher envelope may be missing entirely.\n" as *u8)
171 return AB_RC_UNPROVEN
172 }
173 // ★★★★★ THE ASYMMETRY, AND I GOT IT BACKWARDS IN v1: PRESENCE IS ESTABLISHED BY ONE WITNESS; ABSENCE
174 // REQUIRES EXHAUSTIVE COVERAGE. A truncated scan that FOUND the thing has still found it -- truncation
175 // can only ever invalidate the ABSENT verdict, never a positive one. v1 tested partiality first and so
176 // discarded valid positives: MEASURED on pattern "BUDGET-EXCEEDED", which returned 12 REAL matches and
177 // was answered UNPROVEN. Being conservative in the WRONG DIRECTION is not safety, it is lost evidence.
178 // So the coverage tests are now gated on matches == 0, which is the only case where coverage decides.
179 if matches == 0 {
180 // PREFER THE CORPUS-LEVEL FIELD WHEN THE PRODUCER EMITS IT (added to nx_shelltool 2026-08-07 after
181 // this organ neg-control proved coverage_complete=1 coexists with BUDGET-EXCEEDED). corpus_complete
182 // answers the question absence actually depends on -- was every file VISITED -- while
183 // coverage_complete answers whether each VISITED file was read to its end. Two questions, and only
184 // one of them licenses an absence claim.
185 // THE MARKER HEURISTICS STAY AS THE FALLBACK, deliberately: a consumer that understood ONLY the new
186 // token would go blind against every producer that predates it, and going blind quietly is the
187 // failure this organ exists to prevent. ★A NEW FIELD IS AN UPGRADE ONLY IF ITS ABSENCE STILL WORKS.
188 if cc == 0 {
189 ab_puts(" verdict=UNPROVEN reason=corpus-incomplete (corpus_complete=0) -- the walk did not visit\n" as *u8)
190 ab_puts(" every candidate file, so zero matches is absence WITHIN THE VISITED SUBSET only.\n" as *u8)
191 return AB_RC_UNPROVEN
192 }
193 // cc == 1 is AUTHORITATIVE: fall straight through to ABSENT-PROVEN below. The marker heuristics run
194 // ONLY when the producer emitted no corpus-level field at all (cc < 0). The inner block is left at
195 // this indent deliberately so the diff stays reviewable -- the guard is one line, not a re-layout.
196 if cc < 0 {
197 if trunc == 1 {
198 ab_puts(" verdict=UNPROVEN reason=truncated -- the searcher declared its output PARTIAL, so a zero\n" as *u8)
199 ab_puts(" match count is absence WITHIN THE SCANNED SUBSET only. FIX: narrow the dir/ext, or raise\n" as *u8)
200 ab_puts(" shelltool_budget.conf deliberately. Do NOT read this as absence.\n" as *u8)
201 return AB_RC_UNPROVEN
202 }
203 if complete != 1 {
204 ab_puts(" verdict=UNPROVEN reason=coverage-not-declared-complete (coverage_complete!=1). Absence is a\n" as *u8)
205 ab_puts(" claim about the WHOLE corpus and this run did not prove it covered one.\n" as *u8)
206 return AB_RC_UNPROVEN
207 }
208 }
209 }
210 if matches < 0 {
211 ab_puts(" verdict=UNPROVEN reason=no-envelope (the searcher emitted no matches= line, so its own\n" as *u8)
212 ab_puts(" coverage is unknown to us -- an unparsable receipt is not a clean one).\n" as *u8)
213 return AB_RC_UNPROVEN
214 }
215 if matches > 0 {
216 ab_puts(" verdict=PRESENT -- absence REFUTED. First matches (cap " as *u8); ab_putn(AB_SHOW)
217 ab_puts(", declared):\n" as *u8)
218 var shown: i64 = 0
219 var i: i64 = 0
220 var bol: i64 = 1
221 while i < n {
222 if bol == 1 {
223 if shown < AB_SHOW {
224 if ab_at(out, i, n, "--" as *u8) == 0 {
225 if ab_at(out, i, n, "NX-" as *u8) == 0 {
226 var j: i64 = i
227 while j < n { if out[j] == (10 as u8) { j = n } else { j = j + 1 } }
228 var e: i64 = i
229 while e < n { if out[e] == (10 as u8) { e = n } else { e = e + 1 } }
230 ab_puts(" " as *u8)
231 var k: i64 = i
232 while k < n {
233 if out[k] == (10 as u8) { k = n }
234 else { sys_write(1, ((out as i64) + k) as *u8, 1); k = k + 1 }
235 }
236 ab_puts("\n" as *u8)
237 shown = shown + 1
238 }
239 }
240 }
241 }
242 if out[i] == (10 as u8) { bol = 1 }
243 else { bol = 0 }
244 i = i + 1
245 }
246 return AB_RC_PRESENT
247 }
248 ab_puts(" verdict=ABSENT-PROVEN -- zero matches AND the searcher declared coverage_complete=1 with no\n" as *u8)
249 ab_puts(" truncation marker. THIS is the only state in which absence may be asserted.\n" as *u8)
250 return 0
251}