nx_capres_lib.nx source
↩ module page · 311 lines · 12619 B
1// nx_capres_lib.nx -- CAPTURE-RESOLUTION RULER core (LIB, no main).
2// Operator standing order 2026-08-28: "when you screenshot it needs to be full resolution not this
3// bullshit sampled tiny stuff make sure this is true everywhere, we are fine with the cost to make
4// sure the product is the best it can be."
5//
6// THE DEFECT THIS EXISTS TO MAKE REFUSABLE. A capture is evidence, and a capture taken below the
7// resolution the product actually renders at is evidence about a different, smaller subject. The
8// estate had no way to say so mechanically: nx_world_snap announced w= and h= but nothing said what
9// FULL was, so 240x150 and 1920x1200 read identically to every consumer. MEASURED 2026-08-28 the
10// world capture instrument was emitting 36,000 of the engine's 2,304,000 native pixels -- 15 permil
11// -- and the number moved with how busy the box was, because the resolution was being chosen by an
12// adaptive frame-time governor rather than by anyone.
13//
14// THREE QUESTIONS, THREE ANSWERS, AND THE THIRD IS THE ONE EVERYONE FORGETS:
15// 1. what resolution IS this capture -> cr_dims (read it, never assume it)
16// 2. is that the subject's FULL resolution -> cr_permil + cr_verdict
17// 3. can the JUDGE about to score it even SEE -> cr_judge
18// that many pixels
19// (3) is the hidden half. A downsampling ruler makes every quality improvement unmeasurable and every
20// regression invisible, and it fails SILENTLY -- a judge that internally reads a 400x240 window of a
21// 1920x1200 frame returns a confident number about the top 50 rows. A capture policy that fixes only
22// the camera and leaves the ruler blind fixes nothing.
23//
24// ABSTAIN, NEVER ACQUIT. An unreadable artifact, an unknown subject and an unknown judge all return
25// UNPROVEN. "I could not look" is not "it is fine" -- the estate has paid for that confusion before.
26//
27// DATA-DRIVEN BY CONSTRUCTION (rules 11 + 17): every resolution this lib compares against is read
28// from knowledge/capres.conf. There is no resolution literal in this file, and there must never be
29// one: a ruler carrying its own copy of the subject's size is a second owner of that number.
30//
31// PLAIN-IF ONLY (no else) -- the imported-else parser landmine, debt 1784673261, the same reason
32// nx_charjudge_lib says so in its own header.
33// license_tier: ORIGINAL No hw writes (Rule 26).
34import "nx_syscalls.nx"
35
36const CR_PERMIL: i64 = 1000 // permil base; res_permil == CR_PERMIL is exactly "full"
37const CR_CONF: *u8 = "knowledge/capres.conf" as *u8
38
39const CR_KIND_UNKNOWN: i64 = 0
40const CR_KIND_PNG: i64 = 1
41const CR_KIND_NXFH1: i64 = 2
42
43// VERDICTS. These ARE the exit codes: one scale, so a caller branching on the number and a reader
44// branching on the word can never disagree.
45const CR_V_FULL: i64 = 0
46const CR_V_REDUCED: i64 = 1
47const CR_V_UNPROVEN: i64 = 3
48
49// JUDGE VERDICTS, on the same scale for the same reason.
50const CR_J_SEES: i64 = 0
51const CR_J_BLIND: i64 = 1
52
53// PNG signature + IHDR geometry -- RFC 2083 sections 12.11 and 11.2.2. These are FORMAT FACTS, not
54// tuning: the signature is eight fixed bytes and IHDR's width and height are the first two 4-byte
55// big-endian fields of the first chunk, so their offsets are 8(sig) + 4(len) + 4(type) = 16 and 20.
56const CR_PNG_S0: i64 = 137
57const CR_PNG_S1: i64 = 80
58const CR_PNG_S2: i64 = 78
59const CR_PNG_S3: i64 = 71
60const CR_PNG_S4: i64 = 13
61const CR_PNG_S5: i64 = 10
62const CR_PNG_S6: i64 = 26
63const CR_PNG_S7: i64 = 10
64const CR_PNG_IHDR_W_OFF: i64 = 16
65const CR_PNG_IHDR_H_OFF: i64 = 20
66const CR_PNG_HDR_MIN: i64 = 24 // the shortest prefix that carries both IHDR dimensions
67const CR_U32_BYTES: i64 = 4
68const CR_BYTE_BASE: i64 = 256
69
70// NXFH1 magic is the six bytes "NXFH1 " including the separating space. nx_nxfh_lib OWNS the format;
71// this is a reader of its header line only.
72const CR_NXFH_MAGIC_LEN: i64 = 6
73
74const CR_ASCII_0: i64 = 48
75const CR_ASCII_9: i64 = 57
76const CR_ASCII_NL: i64 = 10
77const CR_ASCII_EQ: i64 = 61
78const CR_ASCII_HASH: i64 = 35
79const CR_ASCII_X: i64 = 120 // the separator in <w>x<h>
80const CR_DEC_BASE: i64 = 10
81const CR_CURSOR_BYTES: i64 = 16 // one i64 cursor cell, page-rounded by mmap
82
83// HEADER-ONLY READ. Sizing a buffer from the FILE would pull a 14 MB NXFH1 into memory to answer a
84// question the first 32 bytes settle, and this ruler is meant to run over every capture in the
85// estate. Resource excellence is a shipping criterion, not tidiness.
86const CR_HDR_READ: i64 = 128
87
88// Scan a decimal at pos[0], advance pos[0] past it, return the value.
89// A SEPARATE FLAG ends the loop. Breaking by clobbering the cursor is the idiom that erases where the
90// scan stopped -- this estate has written that defect four times in one day.
91func cr_num_at(b: *u8, n: i64, pos: *i64) -> i64 {
92 var v: i64 = 0
93 var i: i64 = pos[0]
94 var go: i64 = 1
95 while go == 1 {
96 if i >= n { go = 0 }
97 if go == 1 {
98 let c: i64 = b[i] as i64
99 var dig: i64 = 0
100 if c >= CR_ASCII_0 { if c <= CR_ASCII_9 { dig = 1 } }
101 if dig == 1 { v = v*CR_DEC_BASE + (c - CR_ASCII_0); i = i + 1 }
102 if dig == 0 { go = 0 }
103 }
104 }
105 pos[0] = i
106 return v
107}
108
109// Read a big-endian u32 at off. Format fact, not arithmetic taste.
110func cr_be32(b: *u8, off: i64) -> i64 {
111 var v: i64 = 0
112 var i: i64 = 0
113 while i < CR_U32_BYTES {
114 v = v*CR_BYTE_BASE + (b[off+i] as i64)
115 i = i + 1
116 }
117 return v
118}
119
120// Classify a capture header. out[0]=kind out[1]=w out[2]=h. Returns the kind.
121// A HEADER THAT DOES NOT PARSE IS UNKNOWN, NEVER ZERO-BY-ZERO: a 0x0 capture would satisfy nothing
122// while still being a number, and the caller must be able to tell "I read 0" from "I could not read".
123func cr_dims(b: *u8, n: i64, out: *i64) -> i64 {
124 out[0] = CR_KIND_UNKNOWN
125 out[1] = 0
126 out[2] = 0
127 if n >= CR_PNG_HDR_MIN {
128 var sig: i64 = 1
129 if (b[0] as i64) != CR_PNG_S0 { sig = 0 }
130 if (b[1] as i64) != CR_PNG_S1 { sig = 0 }
131 if (b[2] as i64) != CR_PNG_S2 { sig = 0 }
132 if (b[3] as i64) != CR_PNG_S3 { sig = 0 }
133 if (b[4] as i64) != CR_PNG_S4 { sig = 0 }
134 if (b[5] as i64) != CR_PNG_S5 { sig = 0 }
135 if (b[6] as i64) != CR_PNG_S6 { sig = 0 }
136 if (b[7] as i64) != CR_PNG_S7 { sig = 0 }
137 if sig == 1 {
138 out[0] = CR_KIND_PNG
139 out[1] = cr_be32(b, CR_PNG_IHDR_W_OFF)
140 out[2] = cr_be32(b, CR_PNG_IHDR_H_OFF)
141 return CR_KIND_PNG
142 }
143 }
144 if n > CR_NXFH_MAGIC_LEN {
145 let mg: *u8 = "NXFH1 " as *u8
146 var m: i64 = 1
147 var k: i64 = 0
148 while k < CR_NXFH_MAGIC_LEN {
149 if b[k] != mg[k] { m = 0 }
150 k = k + 1
151 }
152 if m == 1 {
153 let pos: *i64 = sys_mmap(CR_CURSOR_BYTES) as *i64
154 pos[0] = CR_NXFH_MAGIC_LEN
155 let w: i64 = cr_num_at(b, n, pos)
156 pos[0] = pos[0] + 1
157 let h: i64 = cr_num_at(b, n, pos)
158 sys_munmap(pos as *u8, CR_CURSOR_BYTES)
159 if w > 0 { if h > 0 {
160 out[0] = CR_KIND_NXFH1
161 out[1] = w
162 out[2] = h
163 return CR_KIND_NXFH1
164 } }
165 }
166 }
167 return CR_KIND_UNKNOWN
168}
169
170// Read the header of a capture file into a caller buffer. Returns bytes read, or -1.
171func cr_read_hdr(path: *u8, b: *u8) -> i64 {
172 let fd: i64 = sys_openat_rd(path)
173 if fd < 0 { return 0 - 1 }
174 let got: i64 = sys_read(fd, b, CR_HDR_READ)
175 sys_close(fd)
176 return got
177}
178
179// One call: what resolution is the capture at <path>? out[0]=kind out[1]=w out[2]=h.
180func cr_dims_of_file(path: *u8, out: *i64) -> i64 {
181 let b: *u8 = sys_mmap(CR_HDR_READ)
182 let got: i64 = cr_read_hdr(path, b)
183 var k: i64 = CR_KIND_UNKNOWN
184 if got > 0 { k = cr_dims(b, got, out) }
185 if got <= 0 { out[0] = CR_KIND_UNKNOWN; out[1] = 0; out[2] = 0 }
186 sys_munmap(b, CR_HDR_READ)
187 return k
188}
189
190// Look up "<key>=<w>x<h>" in the conf. out[0]=w out[1]=h. Returns 1 found / 0 absent.
191// FIRST MATCH WINS and later duplicates are ignored -- but a conf that permits two answers for one
192// key is a coin flip wearing a schema, so nx_capres_gate carries a tooth that the shipped conf has
193// no duplicate keys. The reader is not the right place to paper over that.
194func cr_conf_res(path: *u8, key: *u8, out: *i64) -> i64 {
195 out[0] = 0
196 out[1] = 0
197 let lenp: *i64 = sys_mmap(CR_CURSOR_BYTES) as *i64
198 lenp[0] = 0
199 let buf: *u8 = sys_read_file(path, lenp)
200 if (buf as i64) == 0 { return 0 }
201 let n: i64 = lenp[0]
202 var kn: i64 = 0
203 while key[kn] != (0 as u8) { kn = kn + 1 }
204 var i: i64 = 0
205 var found: i64 = 0
206 while i < n {
207 var e: i64 = i
208 var go: i64 = 1
209 while go == 1 {
210 if e >= n { go = 0 }
211 if go == 1 { if buf[e] == (CR_ASCII_NL as u8) { go = 0 } }
212 if go == 1 { e = e + 1 }
213 }
214 if found == 0 { if e > i { if (buf[i] as i64) != CR_ASCII_HASH {
215 var hit: i64 = 1
216 if i + kn >= e { hit = 0 }
217 if hit == 1 {
218 var k: i64 = 0
219 while k < kn {
220 if buf[i+k] != key[k] { hit = 0 }
221 k = k + 1
222 }
223 }
224 if hit == 1 { if (buf[i+kn] as i64) == CR_ASCII_EQ {
225 let pos: *i64 = sys_mmap(CR_CURSOR_BYTES) as *i64
226 pos[0] = i + kn + 1
227 let w: i64 = cr_num_at(buf, e, pos)
228 var okx: i64 = 0
229 if pos[0] < e { if (buf[pos[0]] as i64) == CR_ASCII_X { okx = 1 } }
230 if okx == 1 {
231 pos[0] = pos[0] + 1
232 let h: i64 = cr_num_at(buf, e, pos)
233 if w > 0 { if h > 0 { out[0] = w; out[1] = h; found = 1 } }
234 }
235 sys_munmap(pos as *u8, CR_CURSOR_BYTES)
236 } }
237 } } }
238 i = e + 1
239 }
240 return found
241}
242
243// Count how many rows declare <key>. The duplicate-key detector: a conf with two answers for one key
244// silently makes first-match-versus-last-match decide a verdict.
245func cr_conf_count(path: *u8, key: *u8) -> i64 {
246 let lenp: *i64 = sys_mmap(CR_CURSOR_BYTES) as *i64
247 lenp[0] = 0
248 let buf: *u8 = sys_read_file(path, lenp)
249 if (buf as i64) == 0 { return 0 }
250 let n: i64 = lenp[0]
251 var kn: i64 = 0
252 while key[kn] != (0 as u8) { kn = kn + 1 }
253 var i: i64 = 0
254 var c: i64 = 0
255 while i < n {
256 var e: i64 = i
257 var go: i64 = 1
258 while go == 1 {
259 if e >= n { go = 0 }
260 if go == 1 { if buf[e] == (CR_ASCII_NL as u8) { go = 0 } }
261 if go == 1 { e = e + 1 }
262 }
263 if e > i { if (buf[i] as i64) != CR_ASCII_HASH {
264 var hit: i64 = 1
265 if i + kn >= e { hit = 0 }
266 if hit == 1 {
267 var k: i64 = 0
268 while k < kn {
269 if buf[i+k] != key[k] { hit = 0 }
270 k = k + 1
271 }
272 }
273 if hit == 1 { if (buf[i+kn] as i64) == CR_ASCII_EQ { c = c + 1 } }
274 } }
275 i = e + 1
276 }
277 return c
278}
279
280// The capture's size as a fraction of the subject's declared full size, in permil.
281// Returns -1 when the denominator is unusable -- an UNPROVEN denominator must never silently become a
282// pass. Binding the assertion to its denominator is the whole point.
283func cr_permil(cw: i64, ch: i64, fw: i64, fh: i64) -> i64 {
284 if cw <= 0 { return 0 - 1 }
285 if ch <= 0 { return 0 - 1 }
286 if fw <= 0 { return 0 - 1 }
287 if fh <= 0 { return 0 - 1 }
288 return cw*ch*CR_PERMIL/(fw*fh)
289}
290
291// PURE. The gate unit-tests this directly, which is why it takes a number and not a file.
292func cr_verdict(permil: i64) -> i64 {
293 if permil < 0 { return CR_V_UNPROVEN }
294 if permil >= CR_PERMIL { return CR_V_FULL }
295 return CR_V_REDUCED
296}
297
298// Can a judge whose ceiling is jw x jh SEE a capture of cw x ch?
299// BLIND means the judge cannot examine this many pixels: whatever it prints is a statement about a
300// downsample, a crop or a prefix -- never about the image it was handed. That is not a low score, it
301// is NO SCORE, and a caller must be able to tell those apart.
302// PURE, for the same reason cr_verdict is.
303func cr_judge(cw: i64, ch: i64, jw: i64, jh: i64) -> i64 {
304 if cw <= 0 { return CR_V_UNPROVEN }
305 if ch <= 0 { return CR_V_UNPROVEN }
306 if jw <= 0 { return CR_V_UNPROVEN }
307 if jh <= 0 { return CR_V_UNPROVEN }
308 if cw > jw { return CR_J_BLIND }
309 if ch > jh { return CR_J_BLIND }
310 return CR_J_SEES
311}