nx_planescan.nx source
↩ module page · 238 lines · 12232 B
1// nx_planescan.nx -- SOVEREIGN SCALABLE PLANE ENUMERATION (the storage-foundation primitive).
2//
3// THE GAP (measured 2026-07-24): seg-store planes written by nx_sqlite_rows carry NO ids-index, so a plane
4// is fetchable ONLY by exact key -- you cannot count, list, or search it. And the naive workaround (loop
5// ss_get over guessed keys) LEAKS ~O(segments) mmaps per call (ss_get returns pointers INTO each segment's
6// mmap and never frees them) -> ~87k maps on a 93-seg plane -> vm.max_map_count crash (filed seq750).
7//
8// This is the leak-free primitive: read the manifest, map EACH segment .docs exactly ONCE, walk its records
9// in memory, munmap it. O(total-bytes) time, O(1) resident, ~1 mmap per segment (all freed). Record framing
10// = [kind:u8][klen:u32be][key][vlen:u32be][val] (ss_w32 big-endian); every offset bounded to the mapping.
11// Turns every plane into something you can count / search / paginate at scale. Importable (no main besides
12// selftest). Also the CANONICAL home of the hardened NXR1 field reader (was 3 copies; seq751).
13// license_tier: ORIGINAL Read-only over the plane, no hw writes (Rule 26).
14import "nx_syscalls.nx"
15import "nx_seg_store.nx"
16const PS_MAGIC_1024: i64 = 1024
17const PS_MAGIC_4096: i64 = 4096
18
19func ps_len(s: *u8) -> i64 { var n: i64=0; while s[n]!=(0 as u8){n=n+1} return n }
20func ps_cat(d: *u8, o: i64, s: *u8) -> i64 { var p: i64=o; var i: i64=0; while s[i]!=(0 as u8){ d[p]=s[i]; p=p+1; i=i+1 } return p }
21func ps_r32(p: *u8, o: i64) -> i64 { let a: i64=p[o]; let b: i64=p[o+1]; let c: i64=p[o+2]; let d: i64=p[o+3]; return (((((a<<8)|b)<<8)|c)<<8)|d }
22func ps_eq(a: *u8, b: *u8) -> i64 { var i: i64=0; while 1==1 { if a[i]!=b[i] { return 0 } if a[i]==(0 as u8) { return 1 } i=i+1 } return 0 }
23// does key[0..kl) start with the null-terminated prefix?
24func ps_key_has_prefix(key: *u8, kl: i64, prefix: *u8) -> i64 {
25 let pl: i64 = ps_len(prefix)
26 if pl > kl { return 0 }
27 var i: i64 = 0
28 while i < pl { if key[i] != prefix[i] { return 0 } i = i + 1 }
29 return 1
30}
31
32// CANONICAL hardened NXR1 field reader: bounds EVERY read to reclen (a scan over many records must never
33// walk past one), caps the copy to maxout. Returns value length copied, or -1 if absent/malformed.
34func ps_nxr1_field(rec: *u8, reclen: i64, key: *u8, out: *u8, maxout: i64) -> i64 {
35 if reclen < 8 { return 0 - 1 }
36 if rec[0] != (78 as u8) { return 0 - 1 } // 'N'
37 let klen: i64 = ps_len(key)
38 let n: i64 = ps_r32(rec, 4)
39 if n < 0 { return 0 - 1 }
40 if n > PS_MAGIC_1024 { return 0 - 1 }
41 var off: i64 = 8
42 var i: i64 = 0
43 while i < n {
44 if off + 4 > reclen { return 0 - 1 }
45 let kl: i64 = ps_r32(rec, off); off = off + 4
46 if kl < 0 { return 0 - 1 }
47 if off + kl > reclen { return 0 - 1 }
48 let kp: i64 = off; off = off + kl
49 if off + 4 > reclen { return 0 - 1 }
50 let vl: i64 = ps_r32(rec, off); off = off + 4
51 if vl < 0 { return 0 - 1 }
52 if off + vl > reclen { return 0 - 1 }
53 let vp: i64 = off; off = off + vl
54 if kl == klen {
55 var m: i64 = 1
56 var c: i64 = 0
57 while c < kl { if rec[kp + c] != key[c] { m = 0 } c = c + 1 }
58 if m == 1 {
59 var cap: i64 = vl
60 if cap > maxout - 1 { cap = maxout - 1 }
61 var w: i64 = 0
62 while w < cap { out[w] = rec[vp + w]; w = w + 1 }
63 out[cap] = 0 as u8
64 return cap
65 }
66 }
67 i = i + 1
68 }
69 return 0 - 1
70}
71
72// scan CONTROL: op 0 = COUNT; op 1 = FIND (key-prefix + NXR1 field==val -> copy val to outbuf).
73// ctx layout for FIND: field(*u8), val(*u8), outbuf(*u8), outcap(i64), outkey(*u8) ; found flips to 1.
74const PS_OP_COUNT: i64 = 0
75const PS_OP_FIND: i64 = 1
76
77// walk one mapped segment for records whose key starts with keyprefix. accumulates into st:
78// st[0]=op st[1]=count st[2]=found st[3]=field st[4]=val st[5]=outbuf st[6]=outcap st[7]=outkey
79func ps_walk_seg(b: *u8, sz: i64, keyprefix: *u8, st: *i64) -> i64 {
80 var j: i64 = 0
81 while j + 9 <= sz {
82 if st[0] == PS_OP_FIND { if st[2] == 1 { j = sz } }
83 if j < sz {
84 let kind: i64 = b[j]
85 let kl: i64 = ps_r32(b, j + 1)
86 let koff: i64 = j + 5
87 if kl < 0 { j = sz } else {
88 if koff + kl + 4 > sz { j = sz } else {
89 let vl: i64 = ps_r32(b, koff + kl)
90 let voff: i64 = koff + kl + 4
91 if vl < 0 { j = sz } else {
92 if voff + vl > sz { j = sz } else {
93 if kind == 1 {
94 if ps_key_has_prefix((b as i64 + koff) as *u8, kl, keyprefix) == 1 {
95 if st[0] == PS_OP_COUNT { st[1] = st[1] + 1 }
96 if st[0] == PS_OP_FIND {
97 let fbuf: *u8 = sys_mmap(PS_MAGIC_4096)
98 let gl: i64 = ps_nxr1_field((b as i64 + voff) as *u8, vl, st[3] as *u8, fbuf, PS_MAGIC_4096)
99 if gl >= 0 { if ps_eq(fbuf, st[4] as *u8) == 1 {
100 st[2] = 1
101 // copy the WHOLE matching record's value into outbuf (caller reads fields)
102 let ob: *u8 = st[5] as *u8
103 var cc: i64 = vl
104 if cc > st[6] - 1 { cc = st[6] - 1 }
105 var w: i64 = 0
106 while w < cc { ob[w] = b[voff + w]; w = w + 1 }
107 ob[cc] = 0 as u8
108 // and the key
109 let ok: *u8 = st[7] as *u8
110 var wk: i64 = 0
111 while wk < kl { ok[wk] = b[koff + wk]; wk = wk + 1 }
112 ok[kl] = 0 as u8
113 } }
114 sys_munmap(fbuf, PS_MAGIC_4096)
115 }
116 }
117 }
118 j = voff + vl
119 }}
120 }}
121 }
122 }
123 return 0
124}
125
126// core: read <prefix>manifest.txt, map+walk+munmap each segment. st carries op + results.
127func ps_scan(prefix: *u8, keyprefix: *u8, st: *i64) -> i64 {
128 let mp: *u8 = sys_mmap(512)
129 var mo: i64 = ps_cat(mp, 0, prefix)
130 mo = ps_cat(mp, mo, "manifest.txt" as *u8)
131 mp[mo] = 0 as u8
132 let szp: *i64 = sys_mmap(16) as *i64
133 let man: *u8 = sys_read_file(mp, szp)
134 if (man as i64) == 0 { return 0 }
135 let mlen: i64 = szp[0]
136 var ls: i64 = 0
137 var mi: i64 = 0
138 while mi <= mlen {
139 var eol: i64 = 0
140 if mi == mlen { eol = 1 } else { if man[mi] == (10 as u8) { eol = 1 } }
141 if eol == 1 {
142 var stop: i64 = 0
143 if st[0] == PS_OP_FIND { if st[2] == 1 { stop = 1 } }
144 if stop == 0 { if mi > ls {
145 let sp: *u8 = sys_mmap(512)
146 var so: i64 = ps_cat(sp, 0, prefix)
147 var kk: i64 = ls
148 while kk < mi { sp[so] = man[kk]; so = so + 1; kk = kk + 1 }
149 so = ps_cat(sp, so, ".docs" as *u8)
150 sp[so] = 0 as u8
151 let dszp: *i64 = sys_mmap(16) as *i64
152 let b: *u8 = sys_map_file(sp, dszp)
153 if (b as i64) != 0 { ps_walk_seg(b, dszp[0], keyprefix, st); sys_munmap(b, dszp[0]) }
154 } }
155 ls = mi + 1
156 }
157 mi = mi + 1
158 }
159 return 0
160}
161
162// PUBLIC: count live records whose key starts with keyprefix.
163func ps_count(prefix: *u8, keyprefix: *u8) -> i64 {
164 let st: *i64 = sys_mmap(8 * 8) as *i64
165 st[0] = PS_OP_COUNT; st[1] = 0
166 ps_scan(prefix, keyprefix, st)
167 return st[1]
168}
169// PUBLIC: find the first record (key starts keyprefix) whose NXR1 `field` == `val`; copy its value to
170// outbuf (<=outcap) and its key to outkey. Returns 1 found, 0 not.
171func ps_find_field(prefix: *u8, keyprefix: *u8, field: *u8, val: *u8, outbuf: *u8, outcap: i64, outkey: *u8) -> i64 {
172 let st: *i64 = sys_mmap(8 * 8) as *i64
173 st[0] = PS_OP_FIND; st[2] = 0
174 st[3] = field as i64; st[4] = val as i64; st[5] = outbuf as i64; st[6] = outcap; st[7] = outkey as i64
175 ps_scan(prefix, keyprefix, st)
176 return st[2]
177}
178
179func ps_puts(s: *u8) -> i64 { var n: i64=0; while s[n]!=(0 as u8){n=n+1} sys_write(1,s,n); return 0 }
180func ps_udec(v: i64) -> i64 { let d: *u8=sys_mmap(32); var m: i64=v; var k: i64=0; if m==0{d[0]=48;k=1}; let t: *u8=sys_mmap(32); while m>0{t[k]=(48+(m%10)) as u8;m=m/10;k=k+1}; var o: *u8=sys_mmap(32); var i: i64=0; while i<k{o[i]=t[k-1-i];i=i+1}; sys_write(1,o,k); return 0 }
181
182func ps_selftest() -> i64 {
183 var pass: i64 = 0
184 // T0 NXR1 field reader bounds-safe: a truncated record returns -1, not a segfault
185 let bad: *u8 = sys_mmap(16)
186 bad[0]=78 as u8; bad[1]=88 as u8; bad[2]=82 as u8; bad[3]=49 as u8 // "NXR1"
187 bad[4]=0 as u8; bad[5]=0 as u8; bad[6]=0 as u8; bad[7]=99 as u8 // n=99 fields but no data
188 let ob: *u8 = sys_mmap(64)
189 if ps_nxr1_field(bad, 8, "x" as *u8, ob, 64) == (0 - 1) { pass = pass + 1; ps_puts("T0 nxr1 bounds-safe on truncated rec: PASS\n" as *u8) } else { ps_puts("T0 nxr1 bounds-safe on truncated rec: FAIL\n" as *u8) }
190 // build a tiny self-contained plane fixture: 3 records key t:1..t:3 with NXR1 {k:vN}
191 sys_mkdir("tmp_planescan" as *u8, 511)
192 let pfx: *u8 = "tmp_planescan/ps-" as *u8
193 sys_unlinkat("tmp_planescan/ps-manifest.txt" as *u8)
194 sys_unlinkat("tmp_planescan/ps-seg-0.docs" as *u8)
195 sys_unlinkat("tmp_planescan/ps-seg-0.keys" as *u8)
196 let w: *i64 = ss_begin()
197 // NXR1 record built by hand: magic + count=1 + [klen 'k'][vlen 'vN']
198 var ri: i64 = 0
199 while ri < 3 {
200 let rec: *u8 = sys_mmap(64)
201 rec[0]=78 as u8; rec[1]=88 as u8; rec[2]=82 as u8; rec[3]=49 as u8
202 rec[4]=0 as u8; rec[5]=0 as u8; rec[6]=0 as u8; rec[7]=1 as u8 // 1 field
203 rec[8]=0 as u8; rec[9]=0 as u8; rec[10]=0 as u8; rec[11]=1 as u8 // klen=1
204 rec[12]=107 as u8 // 'k'
205 rec[13]=0 as u8; rec[14]=0 as u8; rec[15]=0 as u8; rec[16]=2 as u8 // vlen=2
206 rec[17]=118 as u8; rec[18]=(49 + ri) as u8 // 'v' + '1'/'2'/'3'
207 let key: *u8 = sys_mmap(16)
208 key[0]=116 as u8; key[1]=58 as u8; key[2]=(49 + ri) as u8; key[3]=0 as u8 // "t:1"
209 ss_add(w, 1, key, rec, 19)
210 ri = ri + 1
211 }
212 ss_commit(pfx, w, ss_next_segid(pfx))
213 // T1 COUNT the prefix
214 let cnt: i64 = ps_count(pfx, "t:" as *u8)
215 if cnt == 3 { pass = pass + 1; ps_puts("T1 ps_count(t:) == 3: PASS\n" as *u8) } else { ps_puts("T1 ps_count(t:) == 3: FAIL got=" as *u8); ps_udec(cnt); ps_puts("\n" as *u8) }
216 // T2 FIND by field: k == v2 -> found, its key is t:2
217 let outk: *u8 = sys_mmap(64)
218 let outv: *u8 = sys_mmap(64)
219 let f: i64 = ps_find_field(pfx, "t:" as *u8, "k" as *u8, "v2" as *u8, outv, 64, outk)
220 if f == 1 { if ps_eq(outk, "t:2" as *u8) == 1 { pass = pass + 1; ps_puts("T2 ps_find_field(k=v2) -> t:2: PASS\n" as *u8) } else { ps_puts("T2 ps_find_field(k=v2) -> t:2: FAIL\n" as *u8) } } else { ps_puts("T2 ps_find_field(k=v2) -> t:2: FAIL notfound\n" as *u8) }
221 // T3 NEG: a phantom value is NOT found
222 let f2: i64 = ps_find_field(pfx, "t:" as *u8, "k" as *u8, "v99" as *u8, outv, 64, outk)
223 if f2 == 0 { pass = pass + 1; ps_puts("T3 phantom value not found: PASS\n" as *u8) } else { ps_puts("T3 phantom value not found: FAIL\n" as *u8) }
224 ps_puts("nx_planescan selftest T=4 PASS=" as *u8); ps_udec(pass)
225 if pass == 4 { ps_puts(" verdict=GREEN\n" as *u8); return 0 }
226 ps_puts(" verdict=RED\n" as *u8)
227 return 1
228}
229
230func main(argc: i64, argv: *i64) -> i64 {
231 if argc >= 2 {
232 let v: *u8 = (argv[1]) as *u8
233 if ps_eq(v, "selftest" as *u8) == 1 { return ps_selftest() }
234 if ps_eq(v, "count" as *u8) == 1 { if argc >= 4 { ps_udec(ps_count((argv[2]) as *u8, (argv[3]) as *u8)); ps_puts("\n" as *u8); return 0 } }
235 }
236 ps_puts("usage: nx_planescan selftest | count <prefix> <keyprefix>\n" as *u8)
237 return 2
238}