nx_oracleband_lib.nx source
↩ module page · 186 lines · 7438 B
1// nx_oracleband_lib.nx -- LIB: READ A CITED ORACLE TABLE AND JUDGE A VALUE AGAINST IT (2026-08-25).
2//
3// WHY THIS EXISTS. The whole "load a banked reference table, find a key, check a value is inside its cited
4// band" capability lived as gf_load/gf_eq/gf_find/gf_band INSIDE nx_gamefeel_oracle_gate and nowhere else --
5// one consumer, private statics, and a conf path hardcoded into the loader. That is a general capability at
6// the narrowest possible adoption level: every organ in this estate that derives a constant from cited data
7// needs exactly this and could not reach it. Extracted, not retyped: the parser, the key compare and the
8// cross-multiplied band test are the gate's own code, and the gate now composes this instead of owning it,
9// so there is ONE oracle-table reader rather than one per lane.
10//
11// THREE THINGS THIS ADDS OVER THE PRIVATE VERSION, each because the private one could not do it:
12// 1. THE PATH IS AN ARGUMENT. gf_load hardcoded knowledge/gamefeel_oracle.conf, so a second oracle table
13// was unreachable without copying the file. ob_load takes the path.
14// 2. THE ROW CAP ANNOUNCES. GF_ROWCAP was 32 and SILENT: a table that outgrew it would be read as a
15// PREFIX and every absent-row verdict below it would read as an honest RED. A cap reached in silence
16// becomes a measurement nobody knows is partial, so ob_truncated() reports it and ob_load refuses.
17// 3. ob_pin -- ASSERT A COMPILED CONSTANT EQUALS ITS CITED ROW. A banded check proves a VALUE is in range;
18// it cannot notice that the constant compiled into an organ has drifted from the row it cites. Without
19// this the citation is decorative: edit either side and nothing complains. This is the tooth that makes
20// a citation load-bearing, and it belongs beside the band check rather than in one gate's main().
21//
22// FORMAT, unchanged from the table it was written for: comment lines start '#', rows are
23// key<TAB>min<TAB>max<TAB>... and only the first three fields are read. Integers only, no division anywhere;
24// the band compare is CROSS-MULTIPLIED so an integer truncation cannot silently pass a value.
25// license_tier: ORIGINAL No hw writes (Rule 26).
26import "nx_syscalls.nx"
27import "nx_gate_verdict.nx"
28
29const OB_ROWCAP: i64 = 256
30const OB_TAB: i64 = 9
31const OB_NL: i64 = 10
32const OB_HASH: i64 = 35
33
34static ob_n: i64
35static ob_raw: i64
36static ob_keys: i64 // *i64: per row, offset of key start (NUL-terminated in place)
37static ob_min: i64
38static ob_max: i64
39static ob_trunc: i64 // 1 = the table had more rows than OB_ROWCAP and was read as a PREFIX
40
41// rows parsed on the last ob_load, and whether that read was complete
42func ob_rows() -> i64 { return ob_n }
43func ob_truncated() -> i64 { return ob_trunc }
44
45// Load a cited oracle table. Returns row count, -1 = unreadable, -2 = MORE ROWS THAN THE CAP.
46// -2 is a REFUSAL, not a partial success: a prefix of an oracle table turns every row past the cap into a
47// missing row, and a missing row is RED by construction -- so a silent cap manufactures false failures.
48func ob_load(path: *u8) -> i64 {
49 let lp: *i64 = sys_mmap(16) as *i64
50 let b: *u8 = sys_read_file(path, lp)
51 if (b as i64) == 0 { return 0 - 1 }
52 let n: i64 = lp[0]
53 ob_raw = b as i64
54 ob_keys = sys_mmap(OB_ROWCAP*8)
55 ob_min = sys_mmap(OB_ROWCAP*8)
56 ob_max = sys_mmap(OB_ROWCAP*8)
57 let ka: *i64 = ob_keys as *i64
58 let mna: *i64 = ob_min as *i64
59 let mxa: *i64 = ob_max as *i64
60 ob_n = 0
61 ob_trunc = 0
62 var i: i64 = 0
63 while i < n {
64 // one LINE per outer pass; inner walks stop AT the newline via a flag -- an `i = n`
65 // sentinel breaks the OUTER walk too (the bug that read a full table as zero rows)
66 if b[i] == (OB_HASH as u8) {
67 var sk: i64 = 1
68 while sk == 1 {
69 if i >= n { sk = 0 } else {
70 if b[i] == (OB_NL as u8) { sk = 0 } else { i = i + 1 }
71 }
72 }
73 } else {
74 let ks: i64 = i
75 var field: i64 = 0
76 var v: i64 = 0
77 var mn: i64 = 0
78 var mx: i64 = 0
79 var sk2: i64 = 1
80 while sk2 == 1 {
81 if i >= n { sk2 = 0 } else {
82 let c: i64 = b[i]
83 if c == OB_NL { sk2 = 0 } else {
84 if c == OB_TAB {
85 if field == 0 { b[i] = 0 as u8 }
86 if field == 1 { mn = v }
87 if field == 2 { mx = v }
88 field = field + 1
89 v = 0
90 }
91 if c >= 48 { if c <= 57 { v = v*10 + (c - 48) } }
92 i = i + 1
93 }
94 }
95 }
96 if field >= 3 {
97 if ob_n < OB_ROWCAP {
98 ka[ob_n] = ks
99 mna[ob_n] = mn
100 mxa[ob_n] = mx
101 ob_n = ob_n + 1
102 } else { ob_trunc = 1 }
103 }
104 }
105 i = i + 1
106 }
107 if ob_trunc == 1 { return 0 - 2 }
108 return ob_n
109}
110
111func ob_eq(a: *u8, b: *u8) -> i64 {
112 var i: i64 = 0
113 while a[i] != (0 as u8) { if a[i] != b[i] { return 0 } i = i + 1 }
114 if b[i] != (0 as u8) { return 0 }
115 return 1
116}
117
118// find a band; returns row index or -1 (a MISSING row must read as failure, never as pass)
119func ob_find(key: *u8) -> i64 {
120 let ka: *i64 = ob_keys as *i64
121 var i: i64 = 0
122 while i < ob_n {
123 if ob_eq(((ob_raw + ka[i]) as *u8), key) == 1 { return i }
124 i = i + 1
125 }
126 return 0 - 1
127}
128
129func ob_lo(r: i64) -> i64 { let p: *i64 = ob_min as *i64; return p[r] }
130func ob_hi(r: i64) -> i64 { let p: *i64 = ob_max as *i64; return p[r] }
131
132// one banded check: value inside [min,max] of its cited row (all integer, no division)
133func ob_band(name: *u8, key: *u8, val: i64, ctr: *i64) -> i64 {
134 let r: i64 = ob_find(key)
135 gv_puts(" " as *u8)
136 gv_puts(name)
137 gv_puts(" = " as *u8)
138 gv_num(val)
139 if r < 0 {
140 gv_puts(" [UNBANKED -- no oracle row]\n" as *u8)
141 gv_check(name, 0, ctr)
142 return 0
143 }
144 let mn: i64 = ob_lo(r)
145 let mx: i64 = ob_hi(r)
146 gv_puts(" band [" as *u8)
147 gv_num(mn)
148 gv_puts(".." as *u8)
149 gv_num(mx)
150 gv_puts("]\n" as *u8)
151 var ok: i64 = 1
152 if val < mn { ok = 0 }
153 if val > mx { ok = 0 }
154 gv_check(name, ok, ctr)
155 return ok
156}
157
158// THE CITATION-IS-LOAD-BEARING TOOTH. Assert that the band endpoints COMPILED INTO a consumer are exactly
159// the cited row it claims to derive from. A band check proves a value is in range; only this notices that
160// the constant and the citation have drifted apart, which is silent on both sides otherwise.
161func ob_pin(name: *u8, key: *u8, lo: i64, hi: i64, ctr: *i64) -> i64 {
162 let r: i64 = ob_find(key)
163 gv_puts(" " as *u8)
164 gv_puts(name)
165 gv_puts(" compiled [" as *u8)
166 gv_num(lo)
167 gv_puts(".." as *u8)
168 gv_num(hi)
169 if r < 0 {
170 gv_puts("] vs [UNBANKED -- no oracle row]\n" as *u8)
171 gv_check(name, 0, ctr)
172 return 0
173 }
174 let mn: i64 = ob_lo(r)
175 let mx: i64 = ob_hi(r)
176 gv_puts("] vs cited [" as *u8)
177 gv_num(mn)
178 gv_puts(".." as *u8)
179 gv_num(mx)
180 gv_puts("]\n" as *u8)
181 var ok: i64 = 1
182 if lo != mn { ok = 0 }
183 if hi != mx { ok = 0 }
184 gv_check(name, ok, ctr)
185 return ok
186}