`nx_seg_store.nx` source

↩ module page · 3231 lines · 143853 B
1// nx_seg_store.nx -- PART A of the sovereign storage substrate rung 1
2// (knowledge/specs/2026-06-09-tutoring-storage-substrate-rung1.md).
3//
4// Append-only IMMUTABLE segment store, pure NishiLang, NO SQL.  Model:
5//   - a segment is written once (seg-<id>.docs) and never mutated
6//   - new data => a NEW segment; deletes => tombstone entries (ADDITIVE law:
7//     history is never destroyed, old versions stay readable)
8//   - THE COMMIT POINT: segment temp file -> rename(2), then manifest temp ->
9//     rename(2).  Readers only see segments listed in manifest.txt, so a
10//     half-written segment (crash before commit) is INVISIBLE by construction.
11//     That is the crash-safety claim the gate proves by fault injection.
12//
13// Entry format inside .docs:  u8 kind (1=put 2=tombstone) | u32be klen | key
14//                             | u32be vlen | value-bytes
15// Values are nx_canon_cid canonical record bytes (content-addressed upstream).
16// "Directory" = a path PREFIX string (e.g. "/tmp/im123-"), so no mkdir is
17// needed (sys_mkdir landmine avoided); a durable store uses a knowledge/ prefix.
18//
19// Rung-2 additions 2026-06-10: sys_fsync (probe-proven x86 74) on every file
20// write + directory fsync after the commit renames = the IM3 power-loss debt
21// CLOSED at the code level; per-segment sorted key index seg-<id>.keys with
22// binary-search reads (ss_get_idx), scan path kept as the ORACLE the gate
23// races it against.  Honest remaining scope (flagged, NOT silent caps):
24// term-postings for text search (IM2 full: delta+bitpack), manifest cap 256
25// segments + 4096 keys/segment (compaction/merge = IM4).
26// license_tier: ORIGINAL
27
28import "nx_syscalls.nx"
29const SS_MAGIC_16777619: i64 = 16777619
30const SS_MAGIC_65536: i64 = 65536
31const SS_MAGIC_1048576: i64 = 1048576
32const SS_MAGIC_4096: i64 = 4096
33const SS_MAGIC_1024: i64 = 1024
34const SS_MAGIC_1039: i64 = 1039
35const SS_MAGIC_1040: i64 = 1040
36const SS_MAGIC_1071: i64 = 1071
37const SS_MAGIC_1072: i64 = 1072
38const SS_MAGIC_1279: i64 = 1279
39const SS_MAGIC_12352: i64 = 12352
40const SS_MAGIC_12543: i64 = 12543
41const SS_MAGIC_3040: i64 = 3040
42const SS_MAGIC_13312: i64 = 13312
43const SS_MAGIC_19903: i64 = 19903
44const SS_MAGIC_3400: i64 = 3400
45const SS_MAGIC_19968: i64 = 19968
46const SS_MAGIC_40959: i64 = 40959
47const SS_MAGIC_44032: i64 = 44032
48const SS_MAGIC_55215: i64 = 55215
49const SS_MAGIC_63744: i64 = 63744
50const SS_MAGIC_64255: i64 = 64255
51const SS_MAGIC_1469598103934665603: i64 = 1469598103934665603
52const SS_MAGIC_1099511628211: i64 = 1099511628211
53
54func ss_len(s: *u8) -> i64 {
  var n: i64 = 0
  while s[n] != (0 as u8) { n = n + 1 }
  return n
58}
59
60func ss_cat(dst: *u8, off: i64, s: *u8) -> i64 {
  var i: i64 = 0
  while s[i] != (0 as u8) { dst[off + i] = s[i]; i = i + 1 }
  return off + i
64}
65
66// append decimal of v
67func ss_catn(dst: *u8, off: i64, v: i64) -> i64 {
  var m: i64 = v
  var o: i64 = off
  if m < 0 { m = 0 - m; dst[o] = 45 as u8; o = o + 1 }
  let t: *u8 = sys_mmap(28)
  var k: i64 = 0
  if m == 0 { t[0] = 48 as u8; k = 1 }
  while m > 0 { t[k] = (48 + (m % 10)) as u8; m = m / 10; k = k + 1 }
  var i: i64 = 0
  while i < k { dst[o + i] = t[k - 1 - i]; i = i + 1 }
  return o + k
78}
79
80func ss_w32(p: *u8, off: i64, v: i64) -> i64 {
  p[off] = ((v >> 24) & 0xff) as u8
  p[off + 1] = ((v >> 16) & 0xff) as u8
  p[off + 2] = ((v >> 8) & 0xff) as u8
  p[off + 3] = (v & 0xff) as u8
  return off + 4
86}
87
88func ss_r32(p: *u8, off: i64) -> i64 {
  let a: i64 = p[off]
  let b: i64 = p[off + 1]
  let c: i64 = p[off + 2]
  let d: i64 = p[off + 3]
  return (((((a << 8) | b) << 8) | c) << 8) | d
94}
95
96// read whole file into fresh mmap; szout[0] = size (-1 if absent)
97func ss_readall(path: *u8, szout: *i64) -> *u8 {
  let fd: i64 = sys_openat_rd(path)
  if fd < 0 { szout[0] = 0 - 1; return 0 as *u8 }
  let sz: i64 = sys_lseek(fd, 0, 2)
  sys_lseek(fd, 0, 0)
  let buf: *u8 = sys_mmap(sz + 64)
  var got: i64 = 0
  var n: i64 = 1
  while n > 0 {
      n = sys_read(fd, (buf as i64 + got) as *u8, SS_MAGIC_65536)
      if n > 0 { got = got + n }
  }
  sys_close(fd)
  szout[0] = got
  return buf
112}
113
114// SEGMENT LOADER (2026-07-23, the mmap-serve rung): read a segment file EITHER by reading it fully into
115// anon RAM (usemmap=0, the historical default -- every consumer keeps this) OR by a read-only FILE-BACKED
116// mmap (usemmap=1). Same (ptr, *szout) contract as ss_readall, so it is a drop-in swap. mmap mode means:
117// load time ~0 (nothing copied), only TOUCHED pages become resident (a query reads its hits, not the whole
118// 1.6GB shard), the mapping is SHARED across forked children (read-only, no COW) AND backed by the OS page
119// cache that survives daemon restarts. This is what turns the RAM-bound serve ceiling into a disk-bound one
120// (research: "memory-mapped immutable segments give fast read-heavy retrieval"). Segments are append-only
121// immutable and readers never mutate segment bytes, so PROT_READ is safe by construction.
122func ss_loadfile(path: *u8, szout: *i64, usemmap: i64) -> *u8 {
  if usemmap == 1 {
      let m: *u8 = sys_map_file(path, szout)
      if (m as i64) != 0 { return m }
      // mmap failed (missing/empty) -> szout already 0; fall through to a normal read so callers that
      // treat "size 0" as absent behave identically to ss_readall's -1/empty on a missing file.
  }
  return ss_readall(path, szout)
130}
131
132func ss_writefile(path: *u8, bytes: *u8, n: i64) -> i64 {
  let fd: i64 = sys_openat_wr(path, 0x1a4)
  if fd < 0 { return 0 - 1 }
  var off: i64 = 0
  while off < n {
      let wr: i64 = sys_write(fd, (bytes as i64 + off) as *u8, n - off)
      if wr <= 0 { sys_close(fd); return 0 - 2 }
      off = off + wr
  }
  sys_fsync(fd)
  sys_close(fd)
  return 0
144}
145
146// fsync the directory holding the store files so the rename(2) commit point
147// itself reaches stable storage (power-loss closure of the IM3 debt; without
148// this only process-crash safety is proven).  prefix = ".../name-" => dir is
149// everything up to the last "/"; no slash => current directory.
150func ss_syncdir(prefix: *u8) -> i64 {
  let d: *u8 = sys_mmap(512)
  var last: i64 = 0 - 1
  var i: i64 = 0
  while prefix[i] != (0 as u8) {
      if prefix[i] == (47 as u8) { last = i }
      i = i + 1
  }
  if last < 0 {
      d[0] = 46 as u8
      d[1] = 0 as u8
  }
  if last >= 0 {
      var t: i64 = 0
      while t <= last { d[t] = prefix[t]; t = t + 1 }
      d[t] = 0 as u8
  }
  let fd: i64 = sys_openat_rd(d)
  if fd < 0 { return 0 - 1 }
  let rc: i64 = sys_fsync(fd)
  sys_close(fd)
  return rc
172}
173
174// segment writer state: w[0]=buf ptr, w[1]=len, w[2]=cap (heap-mmap idiom, no stack structs)
175// writer with a caller-sized buffer (compaction sizes it from the merged total -- no fixed cap).
176func ss_begin_cap(cap: i64) -> *i64 {
  let w: *i64 = sys_mmap(32) as *i64
  w[0] = sys_mmap(cap) as i64
  w[1] = 0
  w[2] = cap
  return w
182}
183// default single-write buffer (a document is ~KB; ss_add2 fail-closes if exceeded, never truncates).
184func ss_begin() -> *i64 {
  return ss_begin_cap(SS_MAGIC_1048576)
186}
187
188func ss_add(w: *i64, kind: i64, key: *u8, val: *u8, vlen: i64) -> i64 {
  return ss_add2(w, kind, key, ss_len(key), val, vlen)
190}
191
192// explicit key length (compaction feeds keys straight from .docs bytes, not null-terminated)
193func ss_add2(w: *i64, kind: i64, key: *u8, kl: i64, val: *u8, vlen: i64) -> i64 {
  let buf: *u8 = w[0] as *u8
  var o: i64 = w[1]
  if o + kl + vlen + 16 > w[2] { return 0 - 1 }
  buf[o] = kind as u8
  o = o + 1
  o = ss_w32(buf, o, kl)
  var t: i64 = 0
  while t < kl { buf[o] = key[t]; o = o + 1; t = t + 1 }
  o = ss_w32(buf, o, vlen)
  t = 0
  while t < vlen { buf[o] = val[t]; o = o + 1; t = t + 1 }
  w[1] = o
  return 0
207}
208
209// build "<prefix>seg-<id>.docs" (+ ".tmp" if tmp==1)
210func ss_segname(prefix: *u8, segid: i64, tmp: i64, out: *u8) -> i64 {
  var o: i64 = 0
  o = ss_cat(out, o, prefix)
  o = ss_cat(out, o, "seg-" as *u8)
  o = ss_catn(out, o, segid)
  o = ss_cat(out, o, ".docs" as *u8)
  if tmp == 1 { o = ss_cat(out, o, ".tmp" as *u8) }
  out[o] = 0 as u8
  return o
219}
220
221// length-aware byte-lex compare: <0, 0, >0 (shorter strict-prefix sorts first)
222func ss_kcmp(a: *u8, al: i64, b: *u8, bl: i64) -> i64 {
  var n: i64 = al
  if bl < n { n = bl }
  var i: i64 = 0
  while i < n {
      let ca: i64 = a[i]
      let cb: i64 = b[i]
      if ca != cb { return ca - cb }
      i = i + 1
  }
  return al - bl
233}
234
235// Build the sorted key index blob for a writer buffer (IM2 rung).  Within a
236// segment the LAST entry for a key wins (identical to scan semantics), so
237// duplicates are dropped keeping the later one.  Layout:
238//   "NXK1" | u32be N | N x u32be entry-rel-offset | entries:
239//   u8 kind | u32be klen | key | u32be voff(into .docs) | u32be vlen
240// Returns index byte length written into kout.
241func ss_build_keys(w: *i64, kout: *u8) -> i64 {
  let buf: *u8 = w[0] as *u8
  let blen: i64 = w[1]
  // capacity DATA-DRIVEN from the writer size (every record >= 9 bytes)
  let maxn: i64 = blen / 9 + 16
  let kls: *i64 = sys_mmap(8 * maxn) as *i64
  let kps: *i64 = sys_mmap(8 * maxn) as *i64
  let vos: *i64 = sys_mmap(8 * maxn) as *i64
  let vls: *i64 = sys_mmap(8 * maxn) as *i64
  let kinds: *i64 = sys_mmap(8 * maxn) as *i64
  var n: i64 = 0
  var i: i64 = 0
  while i + 9 <= blen {
      let kind: i64 = buf[i]
      let kl: i64 = ss_r32(buf, i + 1)
      let koff: i64 = i + 5
      let vl: i64 = ss_r32(buf, koff + kl)
      let voff: i64 = koff + kl + 4
      if n >= maxn { return 0 - 1 }
      kinds[n] = kind
      kls[n] = kl
      kps[n] = (buf as i64) + koff
      vos[n] = voff
      vls[n] = vl
      n = n + 1
      i = voff + vl
  }
  // sort by (key bytes, original index) -- bottom-up merge, stable; equal
  // keys end up chronological, so the LAST of a run is the shadowing entry
  let sidx: *i64 = sys_mmap(8 * (n + 16)) as *i64
  let stmp: *i64 = sys_mmap(8 * (n + 16)) as *i64
  i = 0
  while i < n { sidx[i] = i; i = i + 1 }
  // RESEARCH-DRIVEN FAST-PATH (Knuth TAOCP vol.3 5.2.5): when keys are UNIFORM length, a stable LSD radix
  // sort is O(width*n) and produces a result BIT-IDENTICAL to the stable merge sort (a stable sort is
  // unique).  Variable-length keys fall through to the merge sort.  Proven 5.1x on the index in nx_radix_index_bench.
  var ss_uniform: i64 = 1
  let ss_ul: i64 = kls[0]
  i = 1
  while i < n { if kls[i] != ss_ul { ss_uniform = 0 } i = i + 1 }
  var ss_radixed: i64 = 0
  if ss_uniform == 1 { if n > 64 { if ss_ul > 0 {
      let rcnt: *i64 = sys_mmap(256 * 8) as *i64
      var pos: i64 = ss_ul - 1
      while pos >= 0 {
          var c: i64 = 0
          while c < 256 { rcnt[c] = 0; c = c + 1 }
          i = 0
          while i < n { let kp: *u8 = kps[sidx[i]] as *u8; let kb: i64 = kp[pos] as i64; rcnt[kb] = rcnt[kb] + 1; i = i + 1 }
          var sm: i64 = 0
          c = 0
          while c < 256 { let tc: i64 = rcnt[c]; rcnt[c] = sm; sm = sm + tc; c = c + 1 }
          i = 0
          while i < n { let kp: *u8 = kps[sidx[i]] as *u8; let kb: i64 = kp[pos] as i64; stmp[rcnt[kb]] = sidx[i]; rcnt[kb] = rcnt[kb] + 1; i = i + 1 }
          i = 0
          while i < n { sidx[i] = stmp[i]; i = i + 1 }
          pos = pos - 1
      }
      ss_radixed = 1
  } } }
  if ss_radixed == 0 {
  var width: i64 = 1
  while width < n {
      var lo: i64 = 0
      while lo < n {
          var mid: i64 = lo + width
          if mid > n { mid = n }
          var hi: i64 = lo + 2 * width
          if hi > n { hi = n }
          var a2: i64 = lo
          var b2: i64 = mid
          var o2: i64 = lo
          while o2 < hi {
              var takea: i64 = 0
              if a2 < mid {
                  if b2 >= hi { takea = 1 } else {
                      if ss_kcmp(kps[sidx[a2]] as *u8, kls[sidx[a2]], kps[sidx[b2]] as *u8, kls[sidx[b2]]) <= 0 { takea = 1 }
                  }
              }
              if takea == 1 { stmp[o2] = sidx[a2]; a2 = a2 + 1 } else { stmp[o2] = sidx[b2]; b2 = b2 + 1 }
              o2 = o2 + 1
          }
          o2 = lo
          while o2 < hi { sidx[o2] = stmp[o2]; o2 = o2 + 1 }
          lo = lo + 2 * width
      }
      width = width * 2
  }
  }
  // collapse equal-key runs to their LAST (latest) entry
  let idx: *i64 = sys_mmap(8 * (n + 16)) as *i64
  var m: i64 = 0
  i = 0
  while i < n {
      var j: i64 = i + 1
      var run: i64 = 1
      while run == 1 {
          if j >= n { run = 0 }
          if run == 1 {
              if ss_kcmp(kps[sidx[j]] as *u8, kls[sidx[j]], kps[sidx[i]] as *u8, kls[sidx[i]]) == 0 { j = j + 1 } else { run = 0 }
          }
      }
      idx[m] = sidx[j - 1]
      m = m + 1
      i = j
  }
  // emit
  kout[0] = 78 as u8   // N
  kout[1] = 88 as u8   // X
  kout[2] = 75 as u8   // K
  kout[3] = 49 as u8   // 1
  ss_w32(kout, 4, m)
  let tbl: i64 = 8
  let base: i64 = 8 + 4 * m
  var o: i64 = base
  i = 0
  while i < m {
      let e: i64 = idx[i]
      ss_w32(kout, tbl + 4 * i, o - base)
      kout[o] = kinds[e] as u8
      o = o + 1
      o = ss_w32(kout, o, kls[e])
      let kp: *u8 = kps[e] as *u8
      var t: i64 = 0
      while t < kls[e] { kout[o] = kp[t]; o = o + 1; t = t + 1 }
      o = ss_w32(kout, o, vos[e])
      o = ss_w32(kout, o, vls[e])
      i = i + 1
  }
  return o
371}
372
373// FAULT INJECTION: write ONLY the temp file = death before the commit point.
374// The gate uses this to prove a half-written segment is invisible.
375func ss_crashwrite(prefix: *u8, w: *i64, segid: i64) -> i64 {
  let p: *u8 = sys_mmap(512)
  ss_segname(prefix, segid, 1, p)
  return ss_writefile(p, w[0] as *u8, w[1])
379}
380
381// ---- IM2b: term postings (text search on the store) ----
382// Tokenizer: lowercased alphanumeric runs, length 2..32 (longer runs
383// truncated at 32).  IDENTICAL function serves index build, query, and the
384// gate's brute-force oracle -- consistency by construction.
385// .terms layout: "NXT1" | u32be nterms | nterms x u32be entry-off | entries:
386//                u32be tlen | term | u32be postoff | u32be postlen | u32be dcount
387// .post  layout: "NXP1" | u32be ndocs | ndocs x u32be docs-entry-offset |
388//                per-term varint-delta docid streams (ascending; <=128 docs
389//                per segment block = exactly the spec's varint tail block;
390//                bitpacked 128-blocks = flagged optimization rung)
391
392// varint append (LE 7-bit, high bit = continue); returns new offset
393func ss_vw(p: *u8, off: i64, v: i64) -> i64 {
  var m: i64 = v
  var o: i64 = off
  var go: i64 = 1
  while go == 1 {
      let b7: i64 = m % 128
      m = m / 128
      if m > 0 { p[o] = (b7 + 128) as u8 } else { p[o] = b7 as u8; go = 0 }
      o = o + 1
  }
  return o
404}
405
406// varint read at pos[0]; advances pos
407func ss_vr(p: *u8, pos: *i64) -> i64 {
  var v: i64 = 0
  var sh: i64 = 0
  var go: i64 = 1
  while go == 1 {
      let b: i64 = p[pos[0]]
      pos[0] = pos[0] + 1
      v = v + ((b % 128) << sh)
      sh = sh + 7
      if b < 128 { go = 0 }
  }
  return v
419}
420
421// 256-entry token class table: tbl[c] = 0 for separators, else the
422// lowercased byte.  THE one tokenizer definition -- build, query and oracle
423// all tokenize through this table (semantic consistency by construction).
424func ss_tok_table(tbl: *u8) -> i64 {
  var c: i64 = 0
  while c < 256 {
      var v: i64 = 0
      if c >= 97 { if c <= 122 { v = c } }
      if c >= 65 { if c <= 90 { v = c + 32 } }
      if c >= 48 { if c <= 57 { v = c } }
      tbl[c] = v as u8
      c = c + 1
  }
  return 0
435}
436
437// ACCENT FOLD (2026-07-03, the Unicode rung): fold a decoded codepoint to its ASCII base letter --
438// Latin-1 Supplement (U+00C0-U+00FF) + Latin Extended-A (U+0100-U+017F) via 64/128-entry base-letter
439// tables ('.' = stays a separator: multiplication/division signs). "Kyōka" tokenizes as "kyoka" on BOTH
440// the index and query sides (same ss_tok_next2), so accented pages match plain-ASCII queries; compaction
441// re-tokenizes shards through ss_build_terms = the live upgrade path. Non-Latin (CJK etc.) folds to 0 =
442// separator -- CJK SEGMENTATION is a separate named rung, honestly not claimed here.
443func ss_fold_cp(cp: i64) -> i64 {
  if cp >= 192 { if cp <= 255 {
      let t: *u8 = "aaaaaaaceeeeiiiidnooooo.ouuuuytsaaaaaaaceeeeiiiidnooooo.ouuuuyty" as *u8
      let ch: i64 = t[cp - 192] as i64
      if ch == 46 { return 0 }
      return ch
  } }
  if cp >= 256 { if cp <= 383 {
      let t2: *u8 = "aaaaaaccccccccddddeeeeeeeeeegggggggghhhhiiiiiiiiiiiijjkkkllllllllllnnnnnnnnnoooooooorrrrrrssssssssttttttuuuuuuuuuuuuwwyyyzzzzzzs" as *u8
      return t2[cp - 256] as i64
  } }
  return 0
455}
456
457// MULTILINGUAL rung (2026-07-23, operator: index ru/eu/zh/ja/ko not just English):
458// decode ONE multibyte UTF-8 char at i -> packed (cp<<3)|adv; cp=0 when not a valid multibyte lead
459// (caller's ASCII fast path owns bytes <194). No allocations -- lives under the tf-scan hot loop.
460func ss_u8cp(b: *u8, sz: i64, i: i64) -> i64 {
  if i >= sz { return 1 }
  let c0: i64 = b[i] as i64
  if c0 < 194 { return 1 }
  if c0 < 224 {
      if i + 1 < sz { let c1: i64 = b[i+1] as i64; if c1 >= 128 { if c1 < 192 {
          return ((c0 - 192) * 64 + (c1 - 128)) * 8 + 2
      } } }
      return 1
  }
  if c0 < 240 {
      if i + 2 < sz {
          let c1: i64 = b[i+1] as i64
          let c2: i64 = b[i+2] as i64
          if c1 >= 128 { if c1 < 192 { if c2 >= 128 { if c2 < 192 {
              return ((c0 - 224) * SS_MAGIC_4096 + (c1 - 128) * 64 + (c2 - 128)) * 8 + 3
          } } } }
      }
      return 1
  }
  if i + 3 < sz { return 4 }
  return 1
482}
483// case-fold a Cyrillic/Greek codepoint to its lowercase WORD form (kept as UTF-8 in the token,
484// unlike ss_fold_cp which folds TO ASCII). 0 = not a word char in these scripts.
485func ss_fold_word_cp(cp: i64) -> i64 {
  if cp >= SS_MAGIC_1024 { if cp <= SS_MAGIC_1039 { return cp + 80 } }     // U+0400-040F upper -> U+0450-045F
  if cp >= SS_MAGIC_1040 { if cp <= SS_MAGIC_1071 { return cp + 32 } }     // А-Я -> а-я
  if cp >= SS_MAGIC_1072 { if cp <= SS_MAGIC_1279 { return cp } }          // а-я + Cyrillic ext: identity
  if cp >= 913 { if cp <= 937 { if cp != 930 { return cp + 32 } } }   // Greek Α-Ω -> α-ω (03A2 hole)
  if cp == 962 { return 963 }                            // final sigma -> sigma
  if cp >= 945 { if cp <= 969 { return cp } }            // α-ω identity
  return 0
493}
494// CJK char class for BIGRAM tokenization (no-space scripts + Hangul): Han + Ext-A + compat, kana, Hangul
495// syllables. Standard CJK IR practice: overlapping character bigrams, symmetric index+query.
496func ss_is_cjk(cp: i64) -> i64 {
  if cp >= SS_MAGIC_12352 { if cp <= SS_MAGIC_12543 { return 1 } }         // Hiragana U+SS_MAGIC_3040-309F + Katakana U+30A0-30FF
  if cp >= SS_MAGIC_13312 { if cp <= SS_MAGIC_19903 { return 1 } }         // CJK Ext-A U+SS_MAGIC_3400-4DBF
  if cp >= SS_MAGIC_19968 { if cp <= SS_MAGIC_40959 { return 1 } }         // CJK Unified U+4E00-9FFF
  if cp >= SS_MAGIC_44032 { if cp <= SS_MAGIC_55215 { return 1 } }         // Hangul syllables U+AC00-D7AF
  if cp >= SS_MAGIC_63744 { if cp <= SS_MAGIC_64255 { return 1 } }         // CJK Compat U+F900-FAFF
  return 0
503}
504
505// next token from b[pos[0]..sz): lowercased alnum run len>=2 (cap 32) into
506// tout (null-terminated); returns token length, or -1 when exhausted.
507// UTF-8 aware: Latin accents FOLD to ASCII (ss_fold_cp); Cyrillic/Greek case-fold and stay UTF-8
508// word chars (ss_fold_word_cp); CJK/kana/Hangul emit overlapping character BIGRAMS (isolated char =
509// unigram); everything else separates, whole sequences consumed so continuations never mangle a token.
510func ss_tok_next2(b: *u8, sz: i64, pos: *i64, tout: *u8, tbl: *u8) -> i64 {
  var i: i64 = pos[0]
  var l: i64 = 0
  while i < sz {
      // ASCII FAST PATH FIRST (one byte load, one compare added vs the pre-fold loop -- the tf scan
      // over 32KB x 128 candidates lives here; the reversed branch order cost p95 169->211ms)
      let c0: i64 = b[i] as i64
      if c0 < 194 {
          let m: i64 = tbl[c0]
          if m != 0 {
              if l < 32 { tout[l] = m as u8; l = l + 1 }
          }
          if m == 0 {
              if l >= 2 { pos[0] = i + 1; tout[l] = 0 as u8; return l }
              l = 0
          }
          i = i + 1
      } else {
          // UTF-8 lead byte (0xC2..0xF4): decode + classify
          let v1: i64 = ss_u8cp(b, sz, i)
          let cp: i64 = v1 >> 3
          let adv: i64 = v1 & 7
          // 1) Latin accent fold -> ASCII base letter continues the word
          var f: i64 = 0
          if cp > 0 { f = ss_fold_cp(cp) }
          if f != 0 {
              if l < 32 { tout[l] = f as u8; l = l + 1 }
              i = i + adv
          } else {
              // 2) Cyrillic/Greek word char: case-fold, keep as UTF-8 (2 bytes) in the token
              var wcp: i64 = 0
              if cp > 0 { wcp = ss_fold_word_cp(cp) }
              if wcp != 0 {
                  if l + 2 <= 32 {
                      tout[l] = (192 + wcp / 64) as u8
                      tout[l + 1] = (128 + (wcp % 64)) as u8
                      l = l + 2
                  }
                  i = i + adv
              } else {
                  // 3) CJK/kana/Hangul: overlapping bigrams (run>=2) / unigram (isolated char)
                  var cjk: i64 = 0
                  if cp > 0 { cjk = ss_is_cjk(cp) }
                  if cjk == 1 {
                      if l >= 2 { pos[0] = i; tout[l] = 0 as u8; return l }   // flush word; re-read this char next call
                      l = 0
                      let j: i64 = i + adv
                      let v2: i64 = ss_u8cp(b, sz, j)
                      let cp2: i64 = v2 >> 3
                      let adv2: i64 = v2 & 7
                      var cjk2: i64 = 0
                      if cp2 > 0 { cjk2 = ss_is_cjk(cp2) }
                      if cjk2 == 1 {
                          var x: i64 = 0
                          while x < adv { tout[x] = b[i + x]; x = x + 1 }
                          var y: i64 = 0
                          while y < adv2 { tout[adv + y] = b[j + y]; y = y + 1 }
                          tout[adv + adv2] = 0 as u8
                          // resume AT the second char while the run continues (overlap); past it at run end
                          let k: i64 = j + adv2
                          let v3: i64 = ss_u8cp(b, sz, k)
                          let cp3: i64 = v3 >> 3
                          var cjk3: i64 = 0
                          if cp3 > 0 { cjk3 = ss_is_cjk(cp3) }
                          if cjk3 == 1 { pos[0] = j } else { pos[0] = k }
                          return adv + adv2
                      }
                      var x2: i64 = 0
                      while x2 < adv { tout[x2] = b[i + x2]; x2 = x2 + 1 }
                      tout[adv] = 0 as u8
                      pos[0] = i + adv
                      return adv
                  }
                  // 4) separator (symbols, unclaimed scripts, stray sequences)
                  if l >= 2 { pos[0] = i + adv; tout[l] = 0 as u8; return l }
                  l = 0
                  i = i + adv
              }
          }
      }
  }
  pos[0] = sz
  if l >= 2 { tout[l] = 0 as u8; return l }
  return 0 - 1
594}
595
596// compat wrapper (one-shot callers; hot loops build the table once instead)
597func ss_tok_next(b: *u8, sz: i64, pos: *i64, tout: *u8) -> i64 {
  let tbl: *u8 = sys_mmap(272)
  ss_tok_table(tbl)
  return ss_tok_next2(b, sz, pos, tout, tbl)
601}
602
603// does the value contain token `term`?  (the gate's brute-force oracle)
604func ss_tok_has(b: *u8, sz: i64, term: *u8) -> i64 {
  let pos: *i64 = sys_mmap(16) as *i64
  pos[0] = 0
  let t: *u8 = sys_mmap(40)
  let tbl: *u8 = sys_mmap(272)
  ss_tok_table(tbl)
  var go: i64 = 1
  while go == 1 {
      let l: i64 = ss_tok_next2(b, sz, pos, t, tbl)
      if l < 0 { go = 0 }
      if go == 1 {
          var eq: i64 = 1
          var x: i64 = 0
          while eq == 1 {
              if t[x] != term[x] { eq = 0 }
              if eq == 1 { if t[x] == (0 as u8) { return 1 } }
              x = x + 1
          }
      }
  }
  return 0
625}
626
627// 64-bit FNV-1a over a null-terminated token
628func ss_fnv(s: *u8) -> i64 {
  var h: i64 = SS_MAGIC_1469598103934665603
  var i: i64 = 0
  while s[i] != (0 as u8) {
      h = h ^ (s[i] as i64)
      h = h * SS_MAGIC_1099511628211
      i = i + 1
  }
  if h < 0 { h = 0 - h }
  return h
638}
639
640// Build .terms (tblob) + .post (pblob) for a writer buffer; lengths into
641// louts[0]/louts[1].  Capacities are DATA-DRIVEN, derived from the writer
642// size (every record >= 9 bytes => docs <= blen/9; every counted (term,doc)
643// pair consumes >= 3 source bytes => pairs and unique terms <= blen/3) --
644// no fixed caps to silently or loudly hit; the construction bounds are
645// defensive-checked LOUD (-1) anyway.  Term lookup = open-addressing FNV
646// hash (O(1) per token); postings emit = counting buckets (O(pairs));
647// term dict ordering = bottom-up merge sort (O(n log n)).
648// 2026-07-03 PHRASE RUNG (additive): qblob receives the POSITIONS sidecar ("NXQ1" | u32 nterms |
649// u32 entryoff[nterms] | per-term entries), louts[2] = its length. An entry holds, for each posting doc
650// IN THE SAME (sorted-term, ascending-doc) ORDER as .post: varint(npos) + delta-varint token indexes.
651// Positions are indexes among EMITTED tokens (the same space the query tokenizer sees; 1-char words are
652// invisible to both sides, so they never break adjacency -- documented semantics, not an accident).
653func ss_build_terms(w: *i64, tblob: *u8, pblob: *u8, qblob: *u8, louts: *i64) -> i64 {
  let buf: *u8 = w[0] as *u8
  let blen: i64 = w[1]
  let maxdocs: i64 = blen / 9 + 16
  let maxterms: i64 = blen / 3 + 64
  let maxpairs: i64 = blen / 3 + 64
  let maxocc: i64 = blen / 2 + 64   // every emitted token consumes >= 2 bytes of source
  let docoff: *i64 = sys_mmap(8 * maxdocs) as *i64
  let pool: *u8 = sys_mmap(blen + SS_MAGIC_65536)
  var pooloff: i64 = 0
  let terms: *i64 = sys_mmap(8 * maxterms) as *i64
  var nterms: i64 = 0
  let pterm: *i64 = sys_mmap(8 * maxpairs) as *i64
  let pdoc: *i64 = sys_mmap(8 * maxpairs) as *i64
  var npairs: i64 = 0
  let oterm: *i64 = sys_mmap(8 * maxocc) as *i64
  let odoc: *i64 = sys_mmap(8 * maxocc) as *i64
  let opos: *i64 = sys_mmap(8 * maxocc) as *i64
  var nocc: i64 = 0
  var hts: i64 = 16
  while hts < maxterms * 2 { hts = hts * 2 }
  let ht: *i64 = sys_mmap(8 * hts) as *i64
  // per-term last-doc-seen (stores nd+1; 0 = never) -- O(1) per-doc dedupe
  let lastdoc: *i64 = sys_mmap(8 * maxterms) as *i64
  let tlens: *i64 = sys_mmap(8 * maxterms) as *i64
  var nd: i64 = 0
  var i: i64 = 0
  let pos: *i64 = sys_mmap(16) as *i64
  let tok: *u8 = sys_mmap(40)
  let ttbl: *u8 = sys_mmap(272)
  ss_tok_table(ttbl)
  while i + 9 <= blen {
      let kind: i64 = buf[i]
      let kl: i64 = ss_r32(buf, i + 1)
      let vl: i64 = ss_r32(buf, i + 5 + kl)
      let voff: i64 = i + 5 + kl + 4
      if nd >= maxdocs { return 0 - 1 }
      docoff[nd] = i
      if kind == 1 {
          pos[0] = voff
          var tokidx: i64 = 0
          var go: i64 = 1
          while go == 1 {
              let tl: i64 = ss_tok_next2(buf, voff + vl, pos, tok, ttbl)
              if tl < 0 { go = 0 }
              if go == 1 {
                  // find/create term id via the hash table (slot holds tid+1)
                  var tid: i64 = 0 - 1
                  var slot: i64 = ss_fnv(tok) % hts
                  var probe: i64 = 1
                  while probe == 1 {
                      if ht[slot] == 0 { probe = 0 } else {
                          let cand: i64 = ht[slot] - 1
                          let tp: *u8 = terms[cand] as *u8
                          var eq: i64 = 1
                          var x: i64 = 0
                          while eq == 1 {
                              if tp[x] != tok[x] { eq = 0 }
                              if eq == 1 { if tp[x] == (0 as u8) { tid = cand; eq = 0 } }
                              x = x + 1
                          }
                          if tid >= 0 { probe = 0 } else {
                              slot = slot + 1
                              if slot >= hts { slot = 0 }
                          }
                      }
                  }
                  if tid < 0 {
                      if nterms >= maxterms { return 0 - 1 }
                      if pooloff + tl + 2 >= blen + SS_MAGIC_65536 { return 0 - 1 }
                      let dst: *u8 = (pool as i64 + pooloff) as *u8
                      var x2: i64 = 0
                      while x2 <= tl { dst[x2] = tok[x2]; x2 = x2 + 1 }
                      terms[nterms] = dst as i64
                      tlens[nterms] = tl
                      tid = nterms
                      nterms = nterms + 1
                      pooloff = pooloff + tl + 1
                      ht[slot] = tid + 1
                  }
                  // per-doc dedupe: O(1) via the per-term last-doc-seen mark
                  if lastdoc[tid] != nd + 1 {
                      lastdoc[tid] = nd + 1
                      if npairs >= maxpairs { return 0 - 1 }
                      pterm[npairs] = tid
                      pdoc[npairs] = nd
                      npairs = npairs + 1
                  }
                  // EVERY occurrence carries its token index (the phrase rung's raw material)
                  if nocc >= maxocc { return 0 - 1 }
                  oterm[nocc] = tid
                  odoc[nocc] = nd
                  opos[nocc] = tokidx
                  nocc = nocc + 1
                  tokidx = tokidx + 1
              }
          }
      }
      nd = nd + 1
      i = voff + vl
  }
  // sort term ids by term bytes (bottom-up merge sort over sidx)
  let sidx: *i64 = sys_mmap(8 * (nterms + 16)) as *i64
  let stmp: *i64 = sys_mmap(8 * (nterms + 16)) as *i64
  var t3: i64 = 0
  while t3 < nterms { sidx[t3] = t3; t3 = t3 + 1 }
  var width: i64 = 1
  while width < nterms {
      var lo: i64 = 0
      while lo < nterms {
          var mid: i64 = lo + width
          if mid > nterms { mid = nterms }
          var hi: i64 = lo + 2 * width
          if hi > nterms { hi = nterms }
          var a2: i64 = lo
          var b2: i64 = mid
          var o2: i64 = lo
          while o2 < hi {
              var takea: i64 = 0
              if a2 < mid {
                  if b2 >= hi { takea = 1 } else {
                      if ss_kcmp(terms[sidx[a2]] as *u8, tlens[sidx[a2]], terms[sidx[b2]] as *u8, tlens[sidx[b2]]) <= 0 { takea = 1 }
                  }
              }
              if takea == 1 { stmp[o2] = sidx[a2]; a2 = a2 + 1 } else { stmp[o2] = sidx[b2]; b2 = b2 + 1 }
              o2 = o2 + 1
          }
          o2 = lo
          while o2 < hi { sidx[o2] = stmp[o2]; o2 = o2 + 1 }
          lo = lo + 2 * width
      }
      width = width * 2
  }
  // bucket pairs by term (counting sort; docs stay ascending within a term)
  let dcnt: *i64 = sys_mmap(8 * (nterms + 16)) as *i64
  var p9: i64 = 0
  while p9 < npairs { dcnt[pterm[p9]] = dcnt[pterm[p9]] + 1; p9 = p9 + 1 }
  let bstart: *i64 = sys_mmap(8 * (nterms + 16)) as *i64
  let bfill: *i64 = sys_mmap(8 * (nterms + 16)) as *i64
  var acc: i64 = 0
  var t9: i64 = 0
  while t9 < nterms {
      bstart[t9] = acc
      bfill[t9] = acc
      acc = acc + dcnt[t9]
      t9 = t9 + 1
  }
  let bdoc: *i64 = sys_mmap(8 * (npairs + 16)) as *i64
  p9 = 0
  while p9 < npairs {
      bdoc[bfill[pterm[p9]]] = pdoc[p9]
      bfill[pterm[p9]] = bfill[pterm[p9]] + 1
      p9 = p9 + 1
  }
  // emit .post: magic | ndocs | doc-offset table | per-term delta-varint streams
  pblob[0] = 78 as u8
  pblob[1] = 88 as u8
  pblob[2] = 80 as u8
  pblob[3] = 49 as u8
  ss_w32(pblob, 4, nd)
  var po: i64 = 8 + 4 * nd
  var d2: i64 = 0
  while d2 < nd { ss_w32(pblob, 8 + 4 * d2, docoff[d2]); d2 = d2 + 1 }
  let postoffs: *i64 = sys_mmap(8 * (nterms + 16)) as *i64
  let postlens: *i64 = sys_mmap(8 * (nterms + 16)) as *i64
  let dcounts: *i64 = sys_mmap(8 * (nterms + 16)) as *i64
  t3 = 0
  while t3 < nterms {
      let tid2: i64 = sidx[t3]
      postoffs[t3] = po
      var prev: i64 = 0
      var p4: i64 = bstart[tid2]
      let pend: i64 = bstart[tid2] + dcnt[tid2]
      while p4 < pend {
          po = ss_vw(pblob, po, bdoc[p4] - prev)
          prev = bdoc[p4]
          p4 = p4 + 1
      }
      postlens[t3] = po - postoffs[t3]
      dcounts[t3] = dcnt[tid2]
      t3 = t3 + 1
  }
  // emit .terms: magic | nterms | entry-off table | entries
  tblob[0] = 78 as u8
  tblob[1] = 88 as u8
  tblob[2] = 84 as u8
  tblob[3] = 49 as u8
  ss_w32(tblob, 4, nterms)
  let base: i64 = 8 + 4 * nterms
  var to: i64 = base
  t3 = 0
  while t3 < nterms {
      ss_w32(tblob, 8 + 4 * t3, to - base)
      let tp2: *u8 = terms[sidx[t3]] as *u8
      let tl2: i64 = tlens[sidx[t3]]
      to = ss_w32(tblob, to, tl2)
      var x3: i64 = 0
      while x3 < tl2 { tblob[to] = tp2[x3]; to = to + 1; x3 = x3 + 1 }
      to = ss_w32(tblob, to, postoffs[t3])
      to = ss_w32(tblob, to, postlens[t3])
      to = ss_w32(tblob, to, dcounts[t3])
      t3 = t3 + 1
  }
  // emit the POSITIONS sidecar blob (NXQ1): bucket occurrences by term (counting sort preserves the
  // (doc asc, position asc) collection order), then per SORTED term emit doc-runs aligned with .post:
  // varint(npos) + delta-varint token indexes. NOTE the magic: .post already uses "NXP1" -- NXQ1 here.
  let ocnt: *i64 = sys_mmap(8 * (nterms + 16)) as *i64
  var o9: i64 = 0
  while o9 < nocc { ocnt[oterm[o9]] = ocnt[oterm[o9]] + 1; o9 = o9 + 1 }
  let ostart: *i64 = sys_mmap(8 * (nterms + 16)) as *i64
  let ofill: *i64 = sys_mmap(8 * (nterms + 16)) as *i64
  var oacc: i64 = 0
  var t8: i64 = 0
  while t8 < nterms {
      ostart[t8] = oacc
      ofill[t8] = oacc
      oacc = oacc + ocnt[t8]
      t8 = t8 + 1
  }
  let obdoc: *i64 = sys_mmap(8 * (nocc + 16)) as *i64
  let obpos: *i64 = sys_mmap(8 * (nocc + 16)) as *i64
  o9 = 0
  while o9 < nocc {
      let f9: i64 = ofill[oterm[o9]]
      obdoc[f9] = odoc[o9]
      obpos[f9] = opos[o9]
      ofill[oterm[o9]] = f9 + 1
      o9 = o9 + 1
  }
  qblob[0] = 78 as u8
  qblob[1] = 88 as u8
  qblob[2] = 81 as u8
  qblob[3] = 49 as u8
  ss_w32(qblob, 4, nterms)
  let qbase: i64 = 8 + 4 * nterms
  var qo: i64 = qbase
  t3 = 0
  while t3 < nterms {
      let tid3: i64 = sidx[t3]
      ss_w32(qblob, 8 + 4 * t3, qo - qbase)
      var r0: i64 = ostart[tid3]
      let rend: i64 = ostart[tid3] + ocnt[tid3]
      while r0 < rend {
          // one doc-run: occurrences of THIS doc are contiguous (collection order)
          let dcur: i64 = obdoc[r0]
          var r1: i64 = r0
          var run9: i64 = 1
          while run9 == 1 {
              if r1 >= rend { run9 = 0 } else {
                  if obdoc[r1] == dcur { r1 = r1 + 1 } else { run9 = 0 }
              }
          }
          qo = ss_vw(qblob, qo, r1 - r0)
          var prevp: i64 = 0
          var r2: i64 = r0
          while r2 < r1 {
              qo = ss_vw(qblob, qo, obpos[r2] - prevp)
              prevp = obpos[r2]
              r2 = r2 + 1
          }
          r0 = r1
      }
      t3 = t3 + 1
  }
  louts[0] = to
  louts[1] = po
  louts[2] = qo
  return 0
921}
922
923// ---- IMPACT-ORDERED POSTINGS sidecar (2026-07-25, the WAND rung, seq606) ------------------------
924// .imp layout: "NXW1" | u32be nterms | nterms x u32be entry-off (relative to table end) | per SORTED
925// term (same ordinal as .terms/NXQ1): varint(k) then k x (varint docidx, varint tf) -- the k highest-
926// tf postings of the term (k = min(dcount, SS_IMP_K); set membership is by tf, walk order within).
927// WHY: per-term candidacy caps truncated in ASCENDING-DOC order, so a high-tf doc past the cap (an
928// entity's PROFILE page under a common name) could never become a candidate at any score. The impact
929// list makes the cap keep the BEST postings, and the stored tf makes candidacy need zero doc reads.
930// OPTIONAL like .pos: absent file -> readers fall back to ss_term; ss_write_seg emits it, so both
931// compaction AND nx_seg_imp_build (in-place, additive-only) are format-upgrade paths.
932const SS_IMP_K: i64 = 512
933
934// top-k selection threshold via a tf histogram (tf clamped into 1023 buckets so the scan is O(n+1024)
935// whatever the tf range): outs[0]=T, outs[1]=count(clamped tf > T). Emit contract used by builder and
936// reader: every clamped-tf>T item plus (k - outs[1]) clamped-tf==T items = exactly min(n,k) items.
937func ss_imp_thresh(tfs: *i64, n: i64, k: i64, outs: *i64) -> i64 {
  if n <= k { outs[0] = 0; outs[1] = n; return 0 }
  let hist: *i64 = sys_mmap(8 * SS_MAGIC_1024) as *i64
  var i: i64 = 0
  while i < n {
      var v: i64 = tfs[i]
      if v > 1023 { v = 1023 }
      if v < 0 { v = 0 }
      hist[v] = hist[v] + 1
      i = i + 1
  }
  var acc: i64 = 0
  var b: i64 = 1023
  var t: i64 = 0
  var going: i64 = 1
  while going == 1 {
      if b < 0 { going = 0 } else {
          if acc + hist[b] >= k { t = b; going = 0 } else { acc = acc + hist[b]; b = b - 1 }
      }
  }
  outs[0] = t
  outs[1] = acc
  return 0
960}
961
962// build the .imp blob from the three emitted index blobs alone (no writer-buffer access), so a LIVE
963// segment can be upgraded from its .idx + .pos without recompacting. Returns blob length, -1 LOUD on
964// malformed input. tf of (term,doc) = the NXQ1 doc-run occurrence count (npos), true value stored
965// unclamped -- the 1023 clamp exists only inside selection.
966func ss_build_imp(tb: *u8, tsz: i64, pb: *u8, psz: i64, qb: *u8, qsz: i64, wblob: *u8) -> i64 {
  if tsz < 8 { return 0 - 1 }
  if psz < 8 { return 0 - 1 }
  if qsz < 8 { return 0 - 1 }
  if qb[0] != (78 as u8) { return 0 - 1 }
  if qb[2] != (81 as u8) { return 0 - 1 }
  let nterms: i64 = ss_r32(tb, 4)
  if ss_r32(qb, 4) != nterms { return 0 - 1 }
  let nd: i64 = ss_r32(pb, 4)
  let tbase: i64 = 8 + 4 * nterms
  let qbase: i64 = 8 + 4 * nterms
  let docs: *i64 = sys_mmap(8 * (nd + 16)) as *i64
  let tfs: *i64 = sys_mmap(8 * (nd + 16)) as *i64
  let pv: *i64 = sys_mmap(16) as *i64
  let qv: *i64 = sys_mmap(16) as *i64
  let touts: *i64 = sys_mmap(32) as *i64
  wblob[0] = 78 as u8
  wblob[1] = 88 as u8
  wblob[2] = 87 as u8
  wblob[3] = 49 as u8
  ss_w32(wblob, 4, nterms)
  let wbase: i64 = 8 + 4 * nterms
  var wo: i64 = wbase
  var t: i64 = 0
  while t < nterms {
      ss_w32(wblob, 8 + 4 * t, wo - wbase)
      let eo: i64 = tbase + ss_r32(tb, 8 + 4 * t)
      let tl: i64 = ss_r32(tb, eo)
      let postoff: i64 = ss_r32(tb, eo + 4 + tl)
      let dcount: i64 = ss_r32(tb, eo + 4 + tl + 8)
      if dcount > nd { return 0 - 1 }
      // lockstep walk: .post deltas give ascending docs, the NXQ1 run headers give per-doc tf
      pv[0] = postoff
      qv[0] = qbase + ss_r32(qb, 8 + 4 * t)
      var prev: i64 = 0
      var i: i64 = 0
      while i < dcount {
          if qv[0] >= qsz { return 0 - 1 }
          prev = prev + ss_vr(pb, pv)
          docs[i] = prev
          let np: i64 = ss_vr(qb, qv)
          var sk: i64 = 0
          while sk < np { ss_vr(qb, qv); sk = sk + 1 }
          tfs[i] = np
          i = i + 1
      }
      ss_imp_thresh(tfs, dcount, SS_IMP_K, touts)
      let thr: i64 = touts[0]
      var k2: i64 = dcount
      if k2 > SS_IMP_K { k2 = SS_IMP_K }
      var room: i64 = k2 - touts[1]
      wo = ss_vw(wblob, wo, k2)
      // pass 1: every clamped tf > T; pass 2: clamped tf == T fills the remaining room
      var pass: i64 = 0
      while pass < 2 {
          i = 0
          while i < dcount {
              var cv: i64 = tfs[i]
              if cv > 1023 { cv = 1023 }
              var take: i64 = 0
              if pass == 0 { if cv > thr { take = 1 } }
              if pass == 1 { if cv == thr { if room > 0 { take = 1; room = room - 1 } } }
              if take == 1 { wo = ss_vw(wblob, wo, docs[i]); wo = ss_vw(wblob, wo, tfs[i]) }
              i = i + 1
          }
          pass = pass + 1
      }
      t = t + 1
  }
  return wo
1036}
1037
1038// build "<prefix>seg-<id>.terms" / ".post" (+ ".tmp")
1039func ss_auxname(prefix: *u8, segid: i64, ext: *u8, tmp: i64, out: *u8) -> i64 {
  var o: i64 = 0
  o = ss_cat(out, o, prefix)
  o = ss_cat(out, o, "seg-" as *u8)
  o = ss_catn(out, o, segid)
  o = ss_cat(out, o, ext)
  if tmp == 1 { o = ss_cat(out, o, ".tmp" as *u8) }
  out[o] = 0 as u8
  return o
1048}
1049
1050// write one segment's .docs + .keys files (temp -> rename each); NOT yet
1051// visible to readers until a manifest names it (commit or compaction swap)
1052// seq1730 COMPACTOR HOLE CLOSED: the guard used to sit at ss_commit ONLY, but compactors
1053// (nx_web_shard_compact.nx:165, nx_shard_compact.nx) call ss_write_seg DIRECTLY and then hand-write
1054// the manifest -- they never touch ss_commit, so the old placement had a hole EXACTLY where
1055// dp-web-pub- was actually corrupted. ss_write_seg is the deepest point BOTH paths share.
1056// ss_segid_ok is defined further down this file; forward references resolve (probed in isolation
1057// via nx_fwdref_probe: build exit=0 AND run exit=0), so no definition move and no compile-break
1058// window on a lib every organ imports.
1059func ss_write_seg(prefix: *u8, w: *i64, segid: i64) -> i64 {
  if ss_segid_ok(segid) == 0 {
      let eb: *u8 = sys_mmap(512)
      var eo: i64 = ss_cat(eb, 0, "SS-WRITE-SEG REFUSED: segid=" as *u8)
      eo = ss_catn(eb, eo, segid)
      eo = ss_cat(eb, eo, " is an ADDRESS or negative, not a segment id -- refusing to poison plane " as *u8)
      eo = ss_cat(eb, eo, prefix)
      eo = ss_cat(eb, eo, " (seq1730). NOTHING WRITTEN. Caller is deriving its id from a manifest array that holds POINTERS: parse the digits, or call ss_next_segid.\n" as *u8)
      sys_write(2, eb, eo)
      return 0 - 7
  }
  let pt: *u8 = sys_mmap(512)
  let pf: *u8 = sys_mmap(512)
  ss_segname(prefix, segid, 1, pt)
  ss_segname(prefix, segid, 0, pf)
  if ss_writefile(pt, w[0] as *u8, w[1]) != 0 { return 0 - 1 }
  if sys_renameat(pt, pf) != 0 { return 0 - 2 }
  // MERGED aux index (IM6c): keys + terms + post in ONE seg-<id>.idx file
  //   "NXI1" | u32be klen | u32be tlen | u32be plen | keys | terms | post
  // -- one write + fsync + rename instead of three (the race-localized
  // fsync-ceremony cost), same temp -> rename discipline.  Readers slice.
  let kblob: *u8 = sys_mmap(w[1] * 3 + SS_MAGIC_65536)
  let klen2: i64 = ss_build_keys(w, kblob)
  if klen2 < 0 { return 0 - 5 }
  let tblob: *u8 = sys_mmap(w[1] * 8 + SS_MAGIC_65536)
  let pblob: *u8 = sys_mmap(w[1] * 8 + SS_MAGIC_65536)
  let qblob: *u8 = sys_mmap(w[1] * 4 + SS_MAGIC_65536)
  let louts: *i64 = sys_mmap(32) as *i64
  if ss_build_terms(w, tblob, pblob, qblob, louts) != 0 { return 0 - 11 }
  let isz: i64 = 16 + klen2 + louts[0] + louts[1]
  let iblob: *u8 = sys_mmap(isz + 64)
  iblob[0] = 78 as u8
  iblob[1] = 88 as u8
  iblob[2] = 73 as u8
  iblob[3] = 49 as u8
  ss_w32(iblob, 4, klen2)
  ss_w32(iblob, 8, louts[0])
  ss_w32(iblob, 12, louts[1])
  var co: i64 = 16
  var ci: i64 = 0
  while ci < klen2 { iblob[co] = kblob[ci]; co = co + 1; ci = ci + 1 }
  ci = 0
  while ci < louts[0] { iblob[co] = tblob[ci]; co = co + 1; ci = ci + 1 }
  ci = 0
  while ci < louts[1] { iblob[co] = pblob[ci]; co = co + 1; ci = ci + 1 }
  let it: *u8 = sys_mmap(512)
  let if2: *u8 = sys_mmap(512)
  ss_auxname(prefix, segid, ".idx" as *u8, 1, it)
  ss_auxname(prefix, segid, ".idx" as *u8, 0, if2)
  if ss_writefile(it, iblob, isz) != 0 { return 0 - 7 }
  if sys_renameat(it, if2) != 0 { return 0 - 8 }
  // POSITIONS SIDECAR (2026-07-03, phrase rung): seg-<id>.pos = the NXQ1 blob. OPTIONAL by design --
  // an old segment simply lacks the file and phrase queries degrade to AND there; compaction rebuilds
  // through THIS function, so compacting a shard upgrades it. Same temp->rename discipline, fail LOUD.
  let qt: *u8 = sys_mmap(512)
  let qf: *u8 = sys_mmap(512)
  ss_auxname(prefix, segid, ".pos" as *u8, 1, qt)
  ss_auxname(prefix, segid, ".pos" as *u8, 0, qf)
  if ss_writefile(qt, qblob, louts[2]) != 0 { return 0 - 13 }
  if sys_renameat(qt, qf) != 0 { return 0 - 14 }
  // IMPACT sidecar (2026-07-25, WAND rung): seg-<id>.imp = the NXW1 blob. OPTIONAL like .pos --
  // readers fall back when absent; compaction runs through here so compacting upgrades a shard.
  let wcap: i64 = louts[0] * 2 + louts[1] * 10 + SS_MAGIC_65536
  let wblob2: *u8 = sys_mmap(wcap)
  let wlen: i64 = ss_build_imp(tblob, louts[0], pblob, louts[1], qblob, louts[2], wblob2)
  if wlen < 0 { return 0 - 15 }
  let wt: *u8 = sys_mmap(512)
  let wf: *u8 = sys_mmap(512)
  ss_auxname(prefix, segid, ".imp" as *u8, 1, wt)
  ss_auxname(prefix, segid, ".imp" as *u8, 0, wf)
  if ss_writefile(wt, wblob2, wlen) != 0 { return 0 - 16 }
  if sys_renameat(wt, wf) != 0 { return 0 - 17 }
  return 0
1132}
1133
1134// load a segment's index blobs: NEW merged .idx (sliced) or LEGACY 3-file
1135// (.keys/.terms/.post) fallback -- compaction is the format-upgrade path.
1136// outs: [0]=keys ptr [1]=keys sz [2]=terms ptr [3]=terms sz [4]=post ptr [5]=post sz
1137func ss_load_aux(prefix: *u8, segname: *u8, outs: *i64) -> i64 {
  return ss_load_aux2(prefix, segname, outs, 0)
1139}
1140func ss_load_aux2(prefix: *u8, segname: *u8, outs: *i64, usemmap: i64) -> i64 {
  let path: *u8 = sys_mmap(512)
  var o: i64 = 0
  o = ss_cat(path, o, prefix)
  o = ss_cat(path, o, segname)
  o = ss_cat(path, o, ".idx" as *u8)
  path[o] = 0 as u8
  let szp: *i64 = sys_mmap(16) as *i64
  let ib: *u8 = ss_loadfile(path, szp, usemmap)
  if szp[0] >= 16 { if ib[0] == (78 as u8) { if ib[2] == (73 as u8) {
      let kl: i64 = ss_r32(ib, 4)
      let tl: i64 = ss_r32(ib, 8)
      let pl: i64 = ss_r32(ib, 12)
      if 16 + kl + tl + pl <= szp[0] {
          outs[0] = (ib as i64) + 16
          outs[1] = kl
          outs[2] = (ib as i64) + 16 + kl
          outs[3] = tl
          outs[4] = (ib as i64) + 16 + kl + tl
          outs[5] = pl
          // Release this call's scratch before handing back (seq997). `ib` is NOT freed -- outs[] point
          // INTO it and the handle owns it from here; ss_close reclaims it as ONE mapping via the
          // merged-.idx branch. Leaking these two cost ~2 pages x nsegs x opens, the last T8 residual.
          sys_munmap(path, 512)
          sys_munmap(szp as *u8, 16)
          return 1
      }
  } } }
  // legacy fallback: three separate files
  var fi: i64 = 0
  while fi < 3 {
      var ext: *u8 = ".keys" as *u8
      if fi == 1 { ext = ".terms" as *u8 }
      if fi == 2 { ext = ".post" as *u8 }
      o = 0
      o = ss_cat(path, o, prefix)
      o = ss_cat(path, o, segname)
      o = ss_cat(path, o, ext)
      path[o] = 0 as u8
      outs[fi * 2] = ss_loadfile(path, szp, usemmap) as i64
      outs[fi * 2 + 1] = szp[0]
      fi = fi + 1
  }
  return 0
1184}
1185
1186// COMMIT: seg temp -> rename into place; manifest rewritten via temp -> rename.
1187// The manifest rename IS the commit point (atomicity without a txn engine).
1188// ---- seg-id sanity (seq1730: POINTER-SHAPED SEGIDS SILENTLY CORRUPTED SEVEN PLANES) ---------------
1189// A segment id is either a small counter (1, 2, 1001) or an epoch (sec ~1.8e9, ms ~1.8e12, us ~1.8e15).
1190// It is NEVER AN ADDRESS. Seven planes under knowledge/store were poisoned by a caller passing a pointer
1191// into the segid slot, and because ss_next_segid derives max(existing)+1, ONE poisoned id PINS that plane
1192// near 1.4e14 FOREVER: every later epoch-derived write then sorts BELOW the poisoned segment in supersede
1193// order, so its rows are shadowed by older data -- silently, unboundedly, while the writer sees rc=0.
1194// THE BAND IS SEPARABLE BY CONSTRUCTION, NOT BY TASTE: x86-64 user-space mmap lives under 2^47, and the
1195// observed poison sat at 1.35e14-1.41e14. Epoch-ms (~1.8e12) is two orders BELOW the low bound; epoch-us
1196// (~1.8e15) is an order ABOVE the high bound. So no legitimate id scale can collide with this window.
1197// BOUND HERE because ss_commit is THE ONE ACT EVERY WRITER PERFORMS -- 408 call sites, one chokepoint.
1198// A fix that needs 408 authors to remember it is not a fix.
1199const SS_SEGID_PTRBAND_LO: i64 = 10000000000000
1200const SS_SEGID_PTRBAND_HI: i64 = 140737488355328
1201
1202// 1 = a usable segment id, 0 = refuse (negative, or inside the user-space pointer band).
1203func ss_segid_ok(v: i64) -> i64 {
  if v < 0 { return 0 }
  if v >= SS_SEGID_PTRBAND_LO { if v < SS_SEGID_PTRBAND_HI { return 0 } }
  return 1
1207}
1208
1209func ss_commit(prefix: *u8, w: *i64, segid: i64) -> i64 {
  if ss_segid_ok(segid) == 0 {
      let eb: *u8 = sys_mmap(512)
      var eo: i64 = ss_cat(eb, 0, "SS-COMMIT REFUSED: segid=" as *u8)
      eo = ss_catn(eb, eo, segid)
      eo = ss_cat(eb, eo, " is an ADDRESS or negative, not a segment id -- refusing to poison plane " as *u8)
      eo = ss_cat(eb, eo, prefix)
      eo = ss_cat(eb, eo, " (seq1730). NOTHING WRITTEN. Fix the caller: it is passing a pointer into the third argument of ss_commit.\n" as *u8)
      sys_write(2, eb, eo)
      return 0 - 7
  }
  let wrc: i64 = ss_write_seg(prefix, w, segid)
  if wrc != 0 { return wrc }
  let mf: *u8 = sys_mmap(512)
  let mt: *u8 = sys_mmap(512)
  var o: i64 = 0
  o = ss_cat(mf, o, prefix)
  o = ss_cat(mf, o, "manifest.txt" as *u8)
  mf[o] = 0 as u8
  o = 0
  o = ss_cat(mt, o, prefix)
  o = ss_cat(mt, o, "manifest.tmp" as *u8)
  mt[o] = 0 as u8
  let szp: *i64 = sys_mmap(16) as *i64
  let old: *u8 = ss_readall(mf, szp)
  var osz: i64 = szp[0]
  if osz < 0 { osz = 0 }
  let nb: *u8 = sys_mmap(osz + 128)
  var no: i64 = 0
  var t: i64 = 0
  while t < osz { nb[no] = old[t]; no = no + 1; t = t + 1 }
  no = ss_cat(nb, no, "seg-" as *u8)
  no = ss_catn(nb, no, segid)
  nb[no] = 10 as u8
  no = no + 1
  if ss_writefile(mt, nb, no) != 0 { return 0 - 3 }
  if sys_renameat(mt, mf) != 0 { return 0 - 4 }
  // power-loss closure: the renames themselves reach stable storage
  ss_syncdir(prefix)
  return 0
1249}
1250
1251// ---- BATCHED DURABILITY (added 2026-08-01 ws=legal, PROFILE-DRIVEN, debt 1785610685) --------------
1252// MEASURED, not guessed: nx_regprof_test decomposed reg_put on a fresh plane and found
1253//   lock_cycle=35us u00b7 ss_get_absent=19us u00b7 ss_get@20seg=371us u00b7 reg_put=129335us steady-state.
1254// The lock is 0.03% of a write and the read path 0.3%, and cost FALLS as segments accumulate -- so
1255// neither the plane lock nor the full-index-per-segment shape is the cost. What remains is the
1256// per-commit DIRECTORY FSYNC on the line above: one durability barrier per appended row.
1257//
1258// u2605THE POINT: ss_commit is CORRECT and stays byte-for-byte unchanged. A single logical transaction
1259// that appends N rows does not need N barriers -- it needs ONE, at the end. Paying per row is paying
1260// for a guarantee nobody asked for at that granularity.
1261//
1262// ADDITIVE BY CONSTRUCTION: ss_commit and all 261 of its callers are untouched. A caller opts in by
1263// using ss_commit_deferred for the rows and calling ss_sync_now ONCE afterwards.
1264//
1265// u2605u2605THE HONEST BOUND, stated so nobody mistakes what this buys: after ss_commit_deferred the data IS
1266// VISIBLE -- the segment file is written and the manifest rename has already happened, so any reader
1267// sees the row immediately. ONLY DURABILITY ACROSS POWER LOSS is deferred. A crash between the last
1268// deferred commit and ss_sync_now can lose the tail of the batch. That is exactly the trade a batch
1269// wants and exactly the trade a single critical write must NOT make: u2605USE ss_commit FOR ROWS THAT MUST
1270// SURVIVE A CRASH ON THEIR OWN, ss_commit_deferred ONLY INSIDE A BATCH YOU WILL SYNC.
1271func ss_commit_deferred(prefix: *u8, w: *i64, segid: i64) -> i64 {
  if ss_segid_ok(segid) == 0 {
      let eb: *u8 = sys_mmap(512)
      var eo: i64 = ss_cat(eb, 0, "SS-COMMIT-DEFERRED REFUSED: segid=" as *u8)
      eo = ss_catn(eb, eo, segid)
      eo = ss_cat(eb, eo, " is an ADDRESS or negative, not a segment id -- refusing to poison plane " as *u8)
      eo = ss_cat(eb, eo, prefix)
      eo = ss_cat(eb, eo, ". NOTHING WRITTEN.\n" as *u8)
      sys_write(2, eb, eo)
      return 0 - 7
  }
  let wrc: i64 = ss_write_seg(prefix, w, segid)
  if wrc != 0 { return wrc }
  let mf: *u8 = sys_mmap(512)
  let mt: *u8 = sys_mmap(512)
  var o: i64 = 0
  o = ss_cat(mf, o, prefix)
  o = ss_cat(mf, o, "manifest.txt" as *u8)
  mf[o] = 0 as u8
  o = 0
  o = ss_cat(mt, o, prefix)
  o = ss_cat(mt, o, "manifest.tmp" as *u8)
  mt[o] = 0 as u8
  let szp: *i64 = sys_mmap(16) as *i64
  let old: *u8 = ss_readall(mf, szp)
  var osz: i64 = szp[0]
  if osz < 0 { osz = 0 }
  let nb: *u8 = sys_mmap(osz + 128)
  var no: i64 = 0
  var t: i64 = 0
  while t < osz { nb[no] = old[t]; no = no + 1; t = t + 1 }
  no = ss_cat(nb, no, "seg-" as *u8)
  no = ss_catn(nb, no, segid)
  nb[no] = 10 as u8
  no = no + 1
  if ss_writefile(mt, nb, no) != 0 { return 0 - 3 }
  if sys_renameat(mt, mf) != 0 { return 0 - 4 }
  // u2605deliberately NO ss_syncdir here -- that is the whole difference, and the caller owes one.
  return 0
1310}
1311
1312// u2605THE BARRIER THE BATCH OWES. Call once after a run of ss_commit_deferred. Idempotent and cheap to
1313// over-call: syncing a directory that is already durable is a no-op, so when in doubt, call it.
1314func ss_sync_now(prefix: *u8) -> i64 {
  ss_syncdir(prefix)
  return 0
1317}
1318
1319// -- named caps (rule-11 burn-down of the 256/260 magic-number class) ---------------------------------
1320// SS_MANIFEST_LEGACY_CAP: the byte-identical legacy API cap (ss_manifest/_file). UNCAPPED paths exist and
1321// are canonical: ss_manifest_dyn (enumeration) + ss_next_segid (writers). New code must NOT use the legacy
1322// capped pair -- past the cap, count-as-segid CLOBBERS the cap segment (the reg_put persistence bug class).
1323const SS_MANIFEST_LEGACY_CAP: i64 = 256
1324const SS_VER_SLOTS: i64 = 260     // per-key version buffer allocation (kinds/ptrs/lens/srcs slots)
1325const SS_VER_WINDOW: i64 = 256    // versions of ONE key a scan retains; on overflow the OLDEST slides out
                                // so the LATEST is ALWAYS kept (ss_get correctness for high-churn keys
                                // like every registry's __idx__, which gains a version per put)
1328
1329// parse a manifest-format file (one "seg-<id>" name per line) into segs[];
1330// returns count.  Serves BOTH the live manifest and the compaction archive.
1331// LEGACY-CAPPED (SS_MANIFEST_LEGACY_CAP): kept byte-identical for old callers; use ss_manifest_dyn.
1332func ss_manifest_file(prefix: *u8, fname: *u8, segs: *i64) -> i64 {
  let mf: *u8 = sys_mmap(512)
  var o: i64 = 0
  o = ss_cat(mf, o, prefix)
  o = ss_cat(mf, o, fname)
  mf[o] = 0 as u8
  let szp: *i64 = sys_mmap(16) as *i64
  let b: *u8 = ss_readall(mf, szp)
  let sz: i64 = szp[0]
  if sz <= 0 { return 0 }
  var cnt: i64 = 0
  var i: i64 = 0
  var ls: i64 = 0
  while i < sz {
      if b[i] == (10 as u8) {
          let name: *u8 = sys_mmap(128)
          var t: i64 = 0
          while ls + t < i { name[t] = b[ls + t]; t = t + 1 }
          name[t] = 0 as u8
          if cnt < SS_MANIFEST_LEGACY_CAP { segs[cnt] = name as i64; cnt = cnt + 1 }
          ls = i + 1
      }
      i = i + 1
  }
  return cnt
1357}
1358
1359// parse the LIVE manifest into segs[]; returns count
1360// LEGACY-CAPPED: writers must use ss_next_segid; enumerators ss_manifest_dyn.
1361func ss_manifest(prefix: *u8, segs: *i64) -> i64 {
  return ss_manifest_file(prefix, "manifest.txt" as *u8, segs)
1363}
1364
1365// SOTA data-driven manifest read (NO hardcoded cap -- the 256/260 magic-number cap is the debt this eats):
1366// read the live manifest ONCE, size the segs[] buffer from the ACTUAL entry count, and return the WHOLE
1367// corpus's live segment list. *out_segs receives the freshly-allocated, exactly-sized buffer; returns count.
1368// Sentinel guarding the stashed manifest-buffer slots in the segs slack. ss_manifest_free only trusts
1369// those slots when it sees this value, so a short read (cnt < mc, leaving a NAME pointer at segs[n])
1370// degrades to leaking rather than munmapping an address that was never a manifest buffer.
1371//
1372// DECLARED HERE, ABOVE ITS FIRST READER, 2026-07-26. It used to sit BELOW ss_manifest_file_dyn, which
1373// writes it at `segs[mc] = SS_MF_MAGIC`. A module const read before its declaration silently evaluated
1374// to 0, so the writer stamped 0 while ss_manifest_free compared against the real 0x53534D46 -- the
1375// sentinel COULD NEVER MATCH and the stashed manifest buffer (segs[n+1], size segs[n+2]) was NEVER
1376// munmapped. A real leak on every manifest read, in the most-shared primitive in the ecosystem, in the
1377// same memory class as seq905/seq975 that this file's own comments already reference. It stayed
1378// invisible until the sovereign compiler learned to REFUSE use-before-declaration instead of silently
1379// reading 0. KEEP THIS ABOVE ss_manifest_file_dyn.
1380const SS_MF_MAGIC: i64 = 0x53534D46
1381func ss_manifest_file_dyn(prefix: *u8, fname: *u8, out_segs: *i64) -> i64 {
  let mf: *u8 = sys_mmap(512)
  var o: i64 = 0
  o = ss_cat(mf, o, prefix)
  o = ss_cat(mf, o, fname)
  mf[o] = 0 as u8
  let szp: *i64 = sys_mmap(16) as *i64
  let b: *u8 = ss_readall(mf, szp)
  let sz: i64 = szp[0]
  if sz <= 0 { out_segs[0] = sys_mmap(64) as i64; return 0 }
  var mc: i64 = 0
  var i: i64 = 0
  while i < sz { if b[i] == (10 as u8) { mc = mc + 1 } i = i + 1 }
  // NAME POOL (seq905/seq975): each segment name used to get its OWN sys_mmap(128) -- a full 4 KiB page for
  // a 128-byte string, so an N-segment store burned N pages PER OPEN (the live 117-segment vault store:
  // ~468 KiB per open, leaked forever). One pooled allocation, sliced 128 bytes per name.
  // mf/szp are dead here (sz already extracted); free them rather than leak a page each per open.
  sys_munmap(mf, 512)
  sys_munmap(szp as *u8, 16)
  let namepool: *u8 = sys_mmap(128 * mc + 128)
  let segs: *i64 = sys_mmap(8 * mc + 64) as *i64
  // Hand the manifest read to ss_manifest_free via the slack slots (mc+8 slots exist; mc..mc+2 used).
  segs[mc] = SS_MF_MAGIC
  segs[mc + 1] = b as i64
  segs[mc + 2] = sz + 64
  out_segs[0] = segs as i64
  var cnt: i64 = 0
  var ls: i64 = 0
  i = 0
  while i < sz {
      if b[i] == (10 as u8) {
          let name: *u8 = sys_mmap(128)
          var t: i64 = 0
          while ls + t < i { name[t] = b[ls + t]; t = t + 1 }
          name[t] = 0 as u8
          if cnt < mc { let slot: *u8 = ((namepool as i64) + 128 * cnt) as *u8; var c2: i64 = 0; while name[c2] != (0 as u8) { slot[c2] = name[c2]; c2 = c2 + 1 } slot[c2] = 0 as u8; sys_munmap(name, 128); segs[cnt] = slot as i64; cnt = cnt + 1 } else { sys_munmap(name, 128) }
          ls = i + 1
      }
      i = i + 1
  }
  return cnt
1422}
1423// live-manifest convenience over ss_manifest_file_dyn (data-driven, no cap).
1424// ss_manifest_free -- release what ss_manifest_file_dyn handed back through out_segs. Names are POOLED
1425// contiguously from offset 0, so segs[0] IS the pool base -- no metadata slot and no signature change needed.
1426// Sizes are computed from the RETURNED count n, which is <= the allocated mc, so this UNDER-frees by at most
1427// a page rather than over-freeing: munmapping less than was mapped is safe, munmapping more can release a
1428// neighbouring mapping. Callers pair this with ss_manifest_dyn exactly as ss_close pairs with ss_open.
1429// SS_MF_MAGIC is declared at the TOP of this file, above ss_manifest_file_dyn which writes it.
1430// Declaring it here meant the writer read 0 and the sentinel never matched -- see the note there.
1431func ss_manifest_free(segs: *i64, n: i64) -> i64 {
  if (segs as i64) == 0 { return 0 }
  if n > 0 { if segs[0] != 0 { sys_munmap(segs[0] as *u8, 128 * n) } }
  // Stashed manifest buffer (sentinel-guarded; slots live in the +64 slack past mc, and n==mc in practice
  // because cnt increments exactly once per counted newline). This is the read `b` that ss_manifest_file_dyn
  // cannot free itself -- the name-parsing loop still needs it and that function has no single-exit tail.
  if segs[n] == SS_MF_MAGIC { if segs[n + 1] != 0 { if segs[n + 2] > 0 { sys_munmap(segs[n + 1] as *u8, segs[n + 2]) } } }
  sys_munmap(segs as *u8, 8 * n + 64)
  return 0
1440}
1441
1442func ss_manifest_dyn(prefix: *u8, out_segs: *i64) -> i64 {
  return ss_manifest_file_dyn(prefix, "manifest.txt" as *u8, out_segs)
1444}
1445
1446// CANONICAL next segment id for a commit under `prefix` = (max existing seg-<N> in the manifest) + 1,
1447// UNCAPPED. This is THE writer-side fix for the legacy-cap clobber class: deriving segid from the capped
1448// ss_manifest count returns the cap forever once exceeded, so every later commit overwrites the cap
1449// segment and concurrent writers clobber each other (proven: the toolreg store stuck at seg-256).
1450// Scanning for max is also duplicate-line-proof and hole-proof (ids only need uniqueness+monotonicity).
1451// Lifted from the proven reg_next_segid (nx_registry now delegates here). Empty/missing manifest -> 0.
1452func ss_next_segid(prefix: *u8) -> i64 {
  let mf: *u8 = sys_mmap(512)
  var o: i64 = ss_cat(mf, 0, prefix)
  o = ss_cat(mf, o, "manifest.txt" as *u8)
  mf[o] = 0 as u8
  let szp: *i64 = sys_mmap(16) as *i64
  let b: *u8 = ss_readall(mf, szp)
  let sz: i64 = szp[0]
  if sz <= 0 { return 0 }
  var mx: i64 = 0 - 1
  var i: i64 = 0
  while i + 4 <= sz {
      var m: i64 = 0
      if b[i] == (115 as u8) { if b[i+1] == (101 as u8) { if b[i+2] == (103 as u8) { if b[i+3] == (45 as u8) { m = 1 } } } }
      if m == 1 {
          var j: i64 = i + 4
          var v: i64 = 0
          var any: i64 = 0
          var go: i64 = 1
          while go == 1 { go = 0; if j < sz { let c: i64 = b[j] as i64; if c >= (48 as i64) { if c <= (57 as i64) { v = v * (10 as i64) + (c - (48 as i64)); any = 1; j = j + 1; go = 1 } } } }
          // seq1730 REPAIR HALF: a poisoned id must not PIN the plane. Skipping pointer-shaped ids in
          // the max scan means an already-corrupted manifest heals itself on the next write instead of
          // staying stuck near 1.4e14 forever. The poisoned SEGMENT stays on disk and readable (rule 13,
          // additive-only) -- it simply stops dictating what the next id may be.
          if any == 1 { if ss_segid_ok(v) == 1 { if v > mx { mx = v } } }
          i = j
      } else { i = i + 1 }
  }
  if mx < 0 { return 0 }
  return mx + 1
1482}
1483
1484// author=tutor (GALX-PROD-FULL): backward-compatible higher-capacity manifest readers.
1485// IDENTICAL parse to ss_manifest_file/ss_manifest, but the segment-slot cap is a PARAMETER
1486// rather than the hard 256 baked into ss_manifest_file. Callers supplying a segs[] buffer of
1487// at least `cap` slots (8*cap bytes) can browse the WHOLE corpus, not just the first 256.
1488// The originals ss_manifest_file/ss_manifest are left BYTE-IDENTICAL (cap 256) so all 16
1489// existing callers (260-slot buffers) keep their exact behavior; this is purely additive.
1490func ss_manifest_file_cap(prefix: *u8, fname: *u8, segs: *i64, cap: i64) -> i64 {
  let mf: *u8 = sys_mmap(512)
  var o: i64 = 0
  o = ss_cat(mf, o, prefix)
  o = ss_cat(mf, o, fname)
  mf[o] = 0 as u8
  let szp: *i64 = sys_mmap(16) as *i64
  let b: *u8 = ss_readall(mf, szp)
  let sz: i64 = szp[0]
  if sz <= 0 { return 0 }
  var cnt: i64 = 0
  var i: i64 = 0
  var ls: i64 = 0
  while i < sz {
      if b[i] == (10 as u8) {
          let name: *u8 = sys_mmap(128)
          var t: i64 = 0
          while ls + t < i { name[t] = b[ls + t]; t = t + 1 }
          name[t] = 0 as u8
          if cnt < cap { segs[cnt] = name as i64; cnt = cnt + 1 }
          ls = i + 1
      }
      i = i + 1
  }
  return cnt
1515}
1516
1517// parse the LIVE manifest into segs[] honoring a caller-supplied cap; returns count
1518func ss_manifest_cap(prefix: *u8, segs: *i64, cap: i64) -> i64 {
  return ss_manifest_file_cap(prefix, "manifest.txt" as *u8, segs, cap)
1520}
1521
1522// author=tutor (GALX-PROD-FULL): cap-aware sibling of ss_scan. Identical chronological
1523// version walk, but the segment list is read with ss_manifest_cap so it sees ALL segments
1524// up to `cap` (not just 256). The per-key kinds/ptrs/lens buffers count VERSIONS of one key
1525// (tiny, caller-sized), independent of segment count. ss_scan is left untouched.
1526func ss_scan_cap(prefix: *u8, key: *u8, kinds: *i64, ptrs: *i64, lens: *i64, cap: i64) -> i64 {
  let segs: *i64 = sys_mmap(8 * cap) as *i64
  let ns: i64 = ss_manifest_cap(prefix, segs, cap)
  let srcs: *i64 = sys_mmap(8 * cap) as *i64
  return ss_scan_seglist(prefix, segs, ns, key, kinds, ptrs, lens, srcs, 1, 0, SS_VER_WINDOW)
1531}
1532
1533// author=tutor (GALX-PROD-FULL): cap-aware sibling of ss_get for the FULL-corpus ingest
1534// dedup path. Same semantics (1=found,0=tombstoned,-1=absent) but scans up to `cap`
1535// segments so re-ingest stays idempotent past the 256th image. ss_get is left untouched.
1536func ss_get_cap(prefix: *u8, key: *u8, ptrout: *i64, lenout: *i64, cap: i64) -> i64 {
  let kinds: *i64 = sys_mmap(8 * SS_VER_SLOTS) as *i64
  let ptrs: *i64 = sys_mmap(8 * SS_VER_SLOTS) as *i64
  let lens: *i64 = sys_mmap(8 * SS_VER_SLOTS) as *i64
  let n: i64 = ss_scan_cap(prefix, key, kinds, ptrs, lens, cap)
  if n == 0 { return 0 - 1 }
  let last: i64 = n - 1
  if kinds[last] == 2 { return 0 }
  ptrout[0] = ptrs[last]
  lenout[0] = lens[last]
  return 1
1547}
1548
1549// walk a segment list CHRONOLOGICALLY for `key`, appending versions at cnt0;
1550// srcs[i]=srcval marks where each version came from.  Returns the new count.
1551// `cap` = the caller's version-buffer window. When a key has MORE versions than cap, the window SLIDES
1552// (oldest drops, newest kept) instead of silently truncating at the FIRST cap versions -- the old
1553// first-cap behavior made ss_get return a STALE value for any key with >cap versions (every registry's
1554// __idx__ index key gains one version per put, so registries past cap puts served a stale index).
1555func ss_scan_seglist(prefix: *u8, segs: *i64, ns: i64, key: *u8, kinds: *i64, ptrs: *i64, lens: *i64, srcs: *i64, srcval: i64, cnt0: i64, cap: i64) -> i64 {
  let kl0: i64 = ss_len(key)
  var cnt: i64 = cnt0
  var s: i64 = 0
  while s < ns {
      let path: *u8 = sys_mmap(512)
      var o: i64 = 0
      o = ss_cat(path, o, prefix)
      o = ss_cat(path, o, segs[s] as *u8)
      o = ss_cat(path, o, ".docs" as *u8)
      path[o] = 0 as u8
      let szp: *i64 = sys_mmap(16) as *i64
      let b: *u8 = ss_readall(path, szp)
      let sz: i64 = szp[0]
      var i: i64 = 0
      while i + 9 <= sz {
          let kind: i64 = b[i]
          let kl: i64 = ss_r32(b, i + 1)
          let koff: i64 = i + 5
          let vl: i64 = ss_r32(b, koff + kl)
          let voff: i64 = koff + kl + 4
          var eq: i64 = 1
          if kl != kl0 { eq = 0 }
          var t: i64 = 0
          while t < kl {
              if eq == 1 { if b[koff + t] != key[t] { eq = 0 } }
              t = t + 1
          }
          if eq == 1 {
              if cnt < cap {
                  kinds[cnt] = kind
                  ptrs[cnt] = (b as i64) + voff
                  lens[cnt] = vl
                  srcs[cnt] = srcval
                  cnt = cnt + 1
              } else {
                  // window full: slide the OLDEST version out so the LATEST is always retained
                  // (ss_get takes [cnt-1]; pre-fix this silently kept the FIRST cap versions = stale get)
                  var sh: i64 = 1
                  while sh < cap { kinds[sh-1] = kinds[sh]; ptrs[sh-1] = ptrs[sh]; lens[sh-1] = lens[sh]; srcs[sh-1] = srcs[sh]; sh = sh + 1 }
                  kinds[cap-1] = kind
                  ptrs[cap-1] = (b as i64) + voff
                  lens[cap-1] = vl
                  srcs[cap-1] = srcval
              }
          }
          i = voff + vl
      }
      s = s + 1
  }
  return cnt
1606}
1607
1608// scan LIVE committed segments CHRONOLOGICALLY for `key`; fills kinds/ptrs/lens
1609// (every version incl. tombstones = the time-travel surface); returns count.
1610func ss_scan(prefix: *u8, key: *u8, kinds: *i64, ptrs: *i64, lens: *i64) -> i64 {
  let sp: *i64 = sys_mmap(8) as *i64
  let ns: i64 = ss_manifest_dyn(prefix, sp)
  let segs: *i64 = sp[0] as *i64
  let srcs: *i64 = sys_mmap(8 * SS_VER_SLOTS) as *i64
  return ss_scan_seglist(prefix, segs, ns, key, kinds, ptrs, lens, srcs, 1, 0, SS_VER_WINDOW)
1616}
1617
1618// ARCHIVE TIME-TRAVEL (IM-AR): the FULL history surface.  Compaction retires
1619// segments into manifest-archive.txt without deleting them (additive law);
1620// this reads them back: every version of `key` across ARCHIVED segments
1621// (chronological, srcs=0) then LIVE segments (srcs=1).  Post-compaction the
1622// live merged segment re-states the latest archived version -- that copy is
1623// reported honestly as its own LIVE row, never collapsed.  Returns count.
1624func ss_scan_all(prefix: *u8, key: *u8, kinds: *i64, ptrs: *i64, lens: *i64, srcs: *i64) -> i64 {
  let asp: *i64 = sys_mmap(8) as *i64
  let na: i64 = ss_manifest_file_dyn(prefix, "manifest-archive.txt" as *u8, asp)
  let asegs: *i64 = asp[0] as *i64
  var cnt: i64 = ss_scan_seglist(prefix, asegs, na, key, kinds, ptrs, lens, srcs, 0, 0, SS_VER_WINDOW)
  let lsp: *i64 = sys_mmap(8) as *i64
  let nl: i64 = ss_manifest_dyn(prefix, lsp)
  let lsegs: *i64 = lsp[0] as *i64
  cnt = ss_scan_seglist(prefix, lsegs, nl, key, kinds, ptrs, lens, srcs, 1, cnt, SS_VER_WINDOW)
  return cnt
1634}
1635
1636// Binary-search an in-memory .keys blob for key.
1637// Returns kind (1 put / 2 tombstone) with voff/vlen in outs, or -1 not present,
1638// or -2 blob malformed.
1639func ss_idx_find(b: *u8, sz: i64, key: *u8, voffout: *i64, vlenout: *i64) -> i64 {
  if sz < 8 { return 0 - 2 }
  if b[0] != (78 as u8) { return 0 - 2 }
  if b[3] != (49 as u8) { return 0 - 2 }
  let n: i64 = ss_r32(b, 4)
  let base: i64 = 8 + 4 * n
  let kl0: i64 = ss_len(key)
  var lo: i64 = 0
  var hi: i64 = n - 1
  while lo <= hi {
      let mid: i64 = (lo + hi) / 2
      let eo: i64 = base + ss_r32(b, 8 + 4 * mid)
      let kind: i64 = b[eo]
      let kl: i64 = ss_r32(b, eo + 1)
      let c: i64 = ss_kcmp((b as i64 + eo + 5) as *u8, kl, key, kl0)
      if c == 0 {
          voffout[0] = ss_r32(b, eo + 5 + kl)
          vlenout[0] = ss_r32(b, eo + 5 + kl + 4)
          return kind
      }
      if c < 0 { lo = mid + 1 }
      if c > 0 { hi = mid - 1 }
  }
  return 0 - 1
1663}
1664
1665// per-call wrapper: load ONE segment's .keys from disk and search it
1666func ss_idx_lookup(prefix: *u8, segname: *u8, key: *u8, voffout: *i64, vlenout: *i64) -> i64 {
  let outs: *i64 = sys_mmap(8 * 8) as *i64
  ss_load_aux(prefix, segname, outs)
  return ss_idx_find(outs[0] as *u8, outs[1], key, voffout, vlenout)
1670}
1671
1672// OPEN-STORE HANDLE (the race-named read optimization): load the manifest and
1673// every live segment's .keys + .docs ONCE; lookups then binary-search in
1674// memory with zero per-call file IO.  Snapshot semantics: the handle sees the
1675// store as of open (immutable segments make this safe -- a later commit adds
1676// segments the handle simply does not list; reopen to see them).
1677// Layout: h[0]=nsegs; per segment i (8 slots): h[1+8i]=keys ptr, h[2+8i]=keys
1678// size, h[3+8i]=docs ptr, h[4+8i]=docs size, h[5+8i]=terms ptr, h[6+8i]=terms
1679// size, h[7+8i]=post ptr, h[8+8i]=post size; h[1+8*ns+i]=LIVE-DOC map ptr for
1680// segment i (1 byte per doc entry, 1 = this entry IS its key's current state
1681// -- computed ONCE here so term queries check currency in O(1) instead of a
1682// per-candidate keyed binary search).  Returns 0 ptr if no manifest.
1683// default open: read every segment file fully into anon RAM (historical behavior; ALL non-search consumers
1684// keep this -- small shards, byte-for-byte unchanged).
1685// ss_close -- give back EVERYTHING ss_open/ss_open2 mapped. Its ABSENCE was the seq905 keystone: ss_open
1686// loads every live segment's .keys/.docs/.terms/.post plus a derived live-doc map, and NOTHING ever released
1687// them, so EVERY seg-store consumer leaked BY CONSTRUCTION (`func ss_close` grepped to 0 matches ecosystem-
1688// wide while ss_open had dozens of callers). Measured cost 2026-07-25: ~20.6 GB of 24.3 GB swap consumed on
1689// the NAS, which parks long-running consumers in uninterruptible sleep -- at which point they stop making
1690// progress AND stop responding to SIGKILL, so the leak presents as a HANG, not as an OOM.
1691//
1692// Every size is DERIVABLE from the handle, so this needs no layout change and no new bookkeeping:
1693//   h[0]=ns; per segment i: keys(h[1+8i],h[2+8i]) docs(h[3+8i],h[4+8i]) terms(h[5+8i],h[6+8i])
1694//   post(h[7+8i],h[8+8i]); live-doc map h[1+8ns+i], sized dsz/9+16 exactly as ss_open2 allocated it.
1695//
1696// DELIBERATELY CONSERVATIVE on blob length: ss_readall maps sz+64 but REPORTS sz, while the usemmap=1 path
1697// maps exactly sz. We free the REPORTED size, never sz+64 -- unmapping past a file-backed mapping could
1698// release a NEIGHBOURING mapping, and a sub-page residue is strictly better than freeing memory we do not
1699// own. Pointers are nulled as freed and the handle is released LAST (all sizes are read out of it first), so
1700// a partially-populated handle from a failed open still closes cleanly. Null/zero entries are skipped.
1701// license_tier: ORIGINAL   No hw writes (Rule 26).
1702func ss_close(h: *i64) -> i64 {
  if (h as i64) == 0 { return 0 }
  let ns: i64 = h[0]
  if ns < 0 { return 0 }
  var s: i64 = 0
  while s < ns {
      let kp: i64 = h[1 + 8 * s]
      let ksz: i64 = h[2 + 8 * s]
      // MERGED-.idx DETECTION (seq997). ss_load_aux2 returns keys/terms/post as INTERIOR SLICES of ONE
      // mapping when the segment has a merged .idx (base = keys-16, total = 16+kl+tl+pl). Freeing those as
      // three independent mappings is WRONG and never releases the base. The LEGACY 3-file fallback DOES
      // return three separate allocations, so this must branch, not assume. Discriminator: exact adjacency
      // FIRST (pure arithmetic, no dereference), and only then the NXI header magic -- so keys-16 is read
      // only once it is known to sit inside the same mapping, never off the front of a legacy blob.
      var merged: i64 = 0
      if kp != 0 { if ksz > 0 { let mbase: *u8 = (kp - 16) as *u8
          if h[5 + 8 * s] == kp + ksz { if h[7 + 8 * s] == h[5 + 8 * s] + h[6 + 8 * s] {
              if mbase[0] == (78 as u8) { if mbase[2] == (73 as u8) { merged = 1 } } } } } }
      if merged == 1 { sys_munmap((kp - 16) as *u8, 16 + ksz + h[6 + 8 * s] + h[8 + 8 * s]) } else { if kp != 0 { if ksz > 0 { sys_munmap(kp as *u8, ksz) } } }
      let dpp: i64 = h[3 + 8 * s]
      let dsz: i64 = h[4 + 8 * s]
      if dpp != 0 { if dsz > 0 { sys_munmap(dpp as *u8, dsz) } }
      let tp: i64 = h[5 + 8 * s]
      let tsz: i64 = h[6 + 8 * s]
      if merged == 0 { if tp != 0 { if tsz > 0 { sys_munmap(tp as *u8, tsz) } } }
      let pp: i64 = h[7 + 8 * s]
      let psz: i64 = h[8 + 8 * s]
      if merged == 0 { if pp != 0 { if psz > 0 { sys_munmap(pp as *u8, psz) } } }
      let lmp: i64 = h[1 + 8 * ns + s]
      if lmp != 0 { if dsz >= 0 { sys_munmap(lmp as *u8, dsz / 9 + 16) } }
      h[1 + 8 * s] = 0
      h[3 + 8 * s] = 0
      h[5 + 8 * s] = 0
      h[7 + 8 * s] = 0
      h[1 + 8 * ns + s] = 0
      s = s + 1
  }
  h[0] = 0
  // QUERY SCRATCH ARENA -- six further mappings the handle OWNS, allocated in ss_open2's tail at
  // h[1+9ns]..h[6+9ns]. The first cut of ss_close missed these and the non-vacuous VmSize tooth caught it.
  // maxdocs is not stored anywhere, but it is DERIVABLE exactly as ss_open2 computed it (max over segments
  // of dsz/9+16, floor 16), so these free precisely with no handle-layout change. Sizes live in h[4+8q],
  // which the loop above never zeroes -- only pointers are nulled -- so this recompute is still valid here.
  var md: i64 = 16
  var q: i64 = 0
  while q < ns {
      let dz: i64 = h[4 + 8 * q]
      if dz / 9 + 16 > md { md = dz / 9 + 16 }
      q = q + 1
  }
  if h[1 + 9 * ns] != 0 { sys_munmap(h[1 + 9 * ns] as *u8, 64) }
  if h[2 + 9 * ns] != 0 { sys_munmap(h[2 + 9 * ns] as *u8, 32) }
  if h[3 + 9 * ns] != 0 { sys_munmap(h[3 + 9 * ns] as *u8, 8 * md) }
  if h[4 + 9 * ns] != 0 { sys_munmap(h[4 + 9 * ns] as *u8, 8 * md) }
  if h[5 + 9 * ns] != 0 { sys_munmap(h[5 + 9 * ns] as *u8, 8 * 68) }
  if h[6 + 9 * ns] != 0 { sys_munmap(h[6 + 9 * ns] as *u8, 8 * 68) }
  sys_munmap(h as *u8, 8 * (9 * ns + 16))
  return 0
1760}
1761
1762func ss_open(prefix: *u8) -> *i64 {
  return ss_open2(prefix, 0)
1764}
1765// usemmap=1: file-BACKED read-only maps for the segment files instead of read-all (the mmap-serve rung --
1766// the big web shard uses this so the ~1.25M-doc RAM ceiling becomes disk-bound; shared across forked
1767// children + page-cache-persistent). The derived live-doc map + query scratch stay ANON (they are computed
1768// + mutated). Handle layout is IDENTICAL either way, so every ss_hget/ss_term/ss_phrase reader is unchanged.
1769// ---- LINEAR SHADOW TABLE (2026-08-01) --------------------------------------------------------
1770// Defined HERE rather than imported: nx_livemap_fast.nx imports this file, so importing it back
1771// would be circular. These are the same functions that gate proved equivalent, renamed ssl_*.
1772//
1773// They replace the per-key rescan of all newer segments in ss_open2's live-doc map loop -- a scan
1774// that was O(keys x segments) and therefore QUADRATIC in segment count: 4,454,778 key entries over
1775// 96 segments on the live web shard, and worsening with every crawler commit.
1776const SSL_EMPTY: i64 = 0 - 1
1777
1778func ssl_pow2(n: i64) -> i64 {
  var p: i64 = 16
  while p < n { p = p * 2 }
  return p
1782}
1783
1784func ssl_total_keys(h: *i64, ns: i64) -> i64 {
  var t: i64 = 0
  var s: i64 = 0
  while s < ns {
      let kb: *u8 = h[1 + 8 * s] as *u8
      let ksz: i64 = h[2 + 8 * s]
      if ksz >= 8 { t = t + ss_r32(kb, 4) }
      s = s + 1
  }
  return t
1794}
1795
1796func ssl_key_eq(h: *i64, seg: i64, eo: i64, kb2: *u8, eo2: i64) -> i64 {
  let kb: *u8 = h[1 + 8 * seg] as *u8
  let kl: i64 = ss_r32(kb, eo + 1)
  let kl2: i64 = ss_r32(kb2, eo2 + 1)
  if kl != kl2 { return 0 }
  var i: i64 = 0
  while i < kl {
      if kb[eo + 5 + i] != kb2[eo2 + 5 + i] { return 0 }
      i = i + 1
  }
  return 1
1807}
1808
1809func ssl_hash_entry(kb: *u8, eo: i64) -> i64 {
  let kl: i64 = ss_r32(kb, eo + 1)
  var hsh: i64 = 0x811c9dc5
  var i: i64 = 0
  while i < kl {
      hsh = hsh ^ (kb[eo + 5 + i] as i64)
      hsh = (hsh * SS_MAGIC_16777619) & 0xffffffff
      i = i + 1
  }
  return hsh
1819}
1820
1821// Walk segments NEWEST-FIRST and refuse to overwrite an occupied slot: the first writer for a key
1822// is therefore the newest segment holding it, with no segment-number comparison needed.
1823func ssl_build(h: *i64, ns: i64, tbl_seg: *i64, tbl_eo: *i64, cap: i64) -> i64 {
  var i: i64 = 0
  while i < cap { tbl_seg[i] = SSL_EMPTY; i = i + 1 }
  let mask: i64 = cap - 1
  var inserted: i64 = 0
  var s: i64 = ns - 1
  while s >= 0 {
      let kb: *u8 = h[1 + 8 * s] as *u8
      let ksz: i64 = h[2 + 8 * s]
      if ksz >= 8 {
          let m: i64 = ss_r32(kb, 4)
          var e: i64 = 0
          while e < m {
              let eo: i64 = 8 + 4 * m + ss_r32(kb, 8 + 4 * e)
              let kl: i64 = ss_r32(kb, eo + 1)
              if kl < 500 {
                  var slot: i64 = ssl_hash_entry(kb, eo) & mask
                  var placed: i64 = 0
                  while placed == 0 {
                      if tbl_seg[slot] == SSL_EMPTY {
                          tbl_seg[slot] = s
                          tbl_eo[slot] = eo
                          inserted = inserted + 1
                          placed = 1
                      } else {
                          if ssl_key_eq(h, tbl_seg[slot], tbl_eo[slot], kb, eo) == 1 { placed = 1 } else { slot = (slot + 1) & mask }
                      }
                  }
              }
              e = e + 1
          }
      }
      s = s - 1
  }
  return inserted
1858}
1859
1860func ssl_lookup(h: *i64, tbl_seg: *i64, tbl_eo: *i64, cap: i64, kb: *u8, eo: i64) -> i64 {
  let mask: i64 = cap - 1
  var slot: i64 = ssl_hash_entry(kb, eo) & mask
  var guard: i64 = 0
  while guard < cap {
      if tbl_seg[slot] == SSL_EMPTY { return 0 - 1 }
      if ssl_key_eq(h, tbl_seg[slot], tbl_eo[slot], kb, eo) == 1 { return tbl_seg[slot] }
      slot = (slot + 1) & mask
      guard = guard + 1
  }
  return 0 - 1
1871}
1872
1873func ss_open2(prefix: *u8, usemmap: i64) -> *i64 {
  let sp: *i64 = sys_mmap(8) as *i64
  let ns: i64 = ss_manifest_dyn(prefix, sp)
  let segs: *i64 = sp[0] as *i64
  let h: *i64 = sys_mmap(8 * (9 * ns + 16)) as *i64
  h[0] = ns
  let aouts: *i64 = sys_mmap(8 * 8) as *i64
  // HOISTED (seq905): dp/dszp were allocated INSIDE the per-segment loop, so opening an N-segment store
  // leaked N page-sized scratch mappings PER OPEN -- and nothing could ever reclaim them because they are
  // not reachable from the returned handle, so even a correct ss_close could not help. One allocation,
  // reused per segment. Same lesson nx_treepack banked as "buffers hoisted, no mmap in inner loops".
  let dp: *u8 = sys_mmap(512)
  let dszp: *i64 = sys_mmap(16) as *i64
  var s: i64 = 0
  while s < ns {
      // dp hoisted above the loop (seq905)
      var o: i64 = 0
      o = ss_cat(dp, o, prefix)
      o = ss_cat(dp, o, segs[s] as *u8)
      o = ss_cat(dp, o, ".docs" as *u8)
      dp[o] = 0 as u8
      // dszp hoisted above the loop (seq905)
      h[3 + 8 * s] = ss_loadfile(dp, dszp, usemmap) as i64
      h[4 + 8 * s] = dszp[0]
      // index blobs: merged .idx slices (or legacy 3-file fallback)
      ss_load_aux2(prefix, segs[s] as *u8, aouts, usemmap)
      h[1 + 8 * s] = aouts[0]
      h[2 + 8 * s] = aouts[1]
      h[5 + 8 * s] = aouts[2]
      h[6 + 8 * s] = aouts[3]
      h[7 + 8 * s] = aouts[4]
      h[8 + 8 * s] = aouts[5]
      s = s + 1
  }
  // live-doc maps: derived from the .keys indexes, ONCE per open.  A .keys
  // entry is already its key's LATEST entry within its segment, so an entry
  // is current iff NO NEWER segment's index knows the key (put or
  // tombstone both shadow).  Docs not in their segment's .keys (shadowed
  // within the segment) stay dead.  Single-segment stores need ZERO probes.
  let vo9: *i64 = sys_mmap(16) as *i64
  let vl9: *i64 = sys_mmap(16) as *i64
  let kcp: *u8 = sys_mmap(512)
  // key -> NEWEST segment holding it, built ONCE per open (2026-08-01). Replaces the per-key
  // rescan of all newer segments in the loop below. Sized 2x the total entry count and rounded to
  // a power of two so the probe masks instead of dividing; open addressing wants <=50% load.
  let ssl_total: i64 = ssl_total_keys(h, ns)
  let ssl_cap: i64 = ssl_pow2(ssl_total * 2 + 16)
  let ssl_seg: *i64 = sys_mmap(8 * ssl_cap) as *i64
  let ssl_eo: *i64 = sys_mmap(8 * ssl_cap) as *i64
  ssl_build(h, ns, ssl_seg, ssl_eo, ssl_cap)
  var maxdocs: i64 = 16
  s = 0
  while s < ns {
      let kb: *u8 = h[1 + 8 * s] as *u8
      let ksz: i64 = h[2 + 8 * s]
      let pb: *u8 = h[7 + 8 * s] as *u8
      let dsz: i64 = h[4 + 8 * s]
      let lm: *u8 = sys_mmap(dsz / 9 + 16)
      h[1 + 8 * ns + s] = lm as i64
      if dsz / 9 + 16 > maxdocs { maxdocs = dsz / 9 + 16 }
      if ksz >= 8 { if h[8 + 8 * s] >= 8 {
          let nd9: i64 = ss_r32(pb, 4)
          let m9: i64 = ss_r32(kb, 4)
          var e9: i64 = 0
          while e9 < m9 {
              let eo: i64 = 8 + 4 * m9 + ss_r32(kb, 8 + 4 * e9)
              let kind9: i64 = kb[eo]
              let kl9: i64 = ss_r32(kb, eo + 1)
              let vof: i64 = ss_r32(kb, eo + 5 + kl9)
              if kind9 == 1 { if kl9 < 500 {
                  // shadowed by any newer segment knowing this key?
                  var shadowed: i64 = 0
                  // SHADOW TEST, NOW LINEAR (2026-08-01). This block asked `does any NEWER segment
                  // know this key` by RESCANNING every newer segment, once per key -- O(keys x
                  // segments) index probes, QUADRATIC in segment count: 4,454,778 key entries across
                  // 96 segments on the live web shard. It is the measured cause of the ~8 minute
                  // docportal pre-warm, and it got worse every time the crawler committed (87 -> 96
                  // segments in one session once the crawler's segments=0 bug was fixed). A correct
                  // fix at the leaf had surfaced a latent quadratic in the keystone.
                  // ssl_tbl is built ONCE per open, walking segments NEWEST-FIRST, so the first
                  // writer for a key is by construction the newest segment holding it. The entire
                  // rescan collapses to one hash probe.
                  // PROVEN BEFORE THE SWITCH, NOT AFTER: nx_livemap_fast_gate rebuilt every live-doc
                  // map this way and diffed it against the old implementation on the REAL shard --
                  // 96 segments, 4,454,778 entries, 177,262,743 bytes compared, MISMATCHED=0, 7/7.
                  // These maps decide which documents are visible at all, so a faster map that is
                  // subtly different would not make search fast, it would make search WRONG.
                  let newest9: i64 = ssl_lookup(h, ssl_seg, ssl_eo, ssl_cap, kb, eo)
                  if newest9 > s { shadowed = 1 }
                  if shadowed == 0 {
                      // map entry offset -> doc index via the .post doc table
                      let ioff: i64 = vof - 9 - kl9
                      var lo9: i64 = 0
                      var hi9: i64 = nd9 - 1
                      while lo9 <= hi9 {
                          let mid9: i64 = (lo9 + hi9) / 2
                          let dv: i64 = ss_r32(pb, 8 + 4 * mid9)
                          if dv == ioff { lm[mid9] = 1 as u8; lo9 = hi9 + 1 } else {
                              if dv < ioff { lo9 = mid9 + 1 } else { hi9 = mid9 - 1 }
                          }
                      }
                  }
              } }
              e9 = e9 + 1
          }
      } }
      s = s + 1
  }
  // query scratch arena (handle is single-threaded; queries allocate nothing)
  h[1 + 9 * ns] = sys_mmap(64) as i64
  h[2 + 9 * ns] = sys_mmap(32) as i64
  h[3 + 9 * ns] = sys_mmap(8 * maxdocs) as i64
  h[4 + 9 * ns] = sys_mmap(8 * maxdocs) as i64
  h[5 + 9 * ns] = sys_mmap(8 * 68) as i64
  h[6 + 9 * ns] = sys_mmap(8 * 68) as i64
  // PER-OPEN SCRATCH RELEASE (seq905/seq975): none of these are reachable from the returned handle, so
  // ss_close can NEVER reclaim them -- they must be given back HERE or every open leaks them forever.
  // All are dead past this point: dp/dszp and aouts served the segment loop; vo9/vl9/kcp served the
  // live-doc-map loop; sp was only the out-param holder. ss_manifest_free releases the segment-name pool
  // and the segs array (paired with ss_manifest_dyn exactly as ss_close pairs with ss_open).
  ss_manifest_free(segs, ns)
  sys_munmap(dp, 512)
  sys_munmap(dszp as *u8, 16)
  sys_munmap(aouts as *u8, 8 * 8)
  sys_munmap(vo9 as *u8, 16)
  sys_munmap(vl9 as *u8, 16)
  sys_munmap(kcp, 512)
  sys_munmap(sp as *u8, 8)
  // ssl_seg/ssl_eo (the 2026-08-01 key->newest-segment table) are DEAD past the live-doc loop and,
  // like everything else in this block, unreachable from the returned handle -- ss_close can never
  // reclaim them. They were the ONLY per-open allocations missing from this release list, and at
  // web-shard scale the pair is 2 x 8 x pow2(2 x 4.45M keys) = 256 MB PER REOPEN -- measured live
  // 2026-08-01 as orphaned 256MB anon VMAs accumulating in nx_docportal_admin_daemon (debt
  // 1785622778), one leaked pair per manifest change under an active crawler.
  // THE CHECKLIST LAW: WHEN YOU ADD A PER-OPEN ALLOCATION, ADD ITS RELEASE IN THE SAME EDIT --
  // this block exists precisely because seq905 paid for the same lesson.
  sys_munmap(ssl_seg as *u8, 8 * ssl_cap)
  sys_munmap(ssl_eo as *u8, 8 * ssl_cap)
  return h
2012}
2013
2014// handle get: identical semantics to ss_get_idx, zero file IO per call
2015// ---- CACHED OPEN (added 2026-07-25, debt seq962) -------------------------------------------------
2016// WHY: ss_open/ss_open2 read EVERY segment fully into anonymous RAM and there is NO ss_close anywhere
2017// in the tree, so a caller that opens PER REQUEST leaks the whole store per request. MEASURED on the
2018// live box: nx_hub_gw does 3 opens per HTTP request and grew VmData 1336 kB PER REQUEST, with
2019// VmSize==VmPeak (monotonic). Nine long-lived organs carried that same fingerprint, ~23.6 GiB of
2020// anonymous address space, which drove swap to 92.3% and the box into sustained thrash.
2021//
2022// THIS IS NOT A NEW IDEA -- it is an EXISTING in-tree remedy finally promoted into the primitive.
2023// The same cache was independently rediscovered at least three times and never generalized:
2024//   1. nx_docportal_search_seg.nx:128  dss_open_maybe_cached (manifest-signature invalidation)
2025//   2. nx_docportal_admin_daemon.nx:652 per-request ss_open measured ~0.7s/query without this
2026//   3. nx_store_seed_lib.nx:94          helped the reader family OOM the host. NOW: ss_open ONCE
2027// Three local patches, zero generalization -- fix the CLASS, not the call site.
2028//
2029// PURELY ADDITIVE BY DESIGN: there is NO munmap here. That is deliberate. ss_load_aux2 publishes
2030// INTERIOR POINTERS into a single mapping on the merged-.idx path but three INDEPENDENT mappings on
2031// the legacy path, and ss_open2 discards the return value that distinguishes them -- so any freeing
2032// close is a partial-unmap/use-after-free hazard until that ledger is fixed (debt seq947). Caching
2033// removes the leak without ever freeing: you cannot leak what you never allocate twice.
2034//
2035// LIVE-EDIT PRESERVED (nx_hub_gw depends on it): invalidation is the manifest (st_size, st_mtime),
2036// so editing a store is still picked up with NO restart -- on the next call.
2037// RESIDUAL (honest): a miss re-opens WITHOUT freeing the previous handle, so re-opens fall from
2038// per-request to per-store-EDIT. Bounded and rare; ss_close remains worth building for that path.
2039const SSC_SLOTS: i64 = 16
2040const SSC_W: i64 = 4
2041// RETIRE RING (seq1057). Capacity in HANDLES; slot 0 of the mapping holds the count, handles live at 1..n.
2042const SSC_RETIRE: i64 = 32
2043static ssc_tab: *i64      // SSC_SLOTS x SSC_W: [0]=prefix-copy ptr [1]=st_size [2]=st_mtime [3]=handle
2044static ssc_names: *u8     // SSC_SLOTS x 256 bytes of prefix copies (slot i at +i*256)
2045static ssc_scr: *u8       // one-shot scratch: [0..559]=path [560..719]=statbuf [720..735]=sig
2046static ssc_retired: *i64  // [0]=count, [1..SSC_RETIRE]=orphaned handles awaiting an explicit reap
2047
2048// allocate the cache ONCE (static POINTERS to lazy-mmap'd tables -- a BSS static ARRAY silently
2049// crashes handler modules on startup, so never use [N]i64 here).
2050func ssc_init() -> i64 {
  if (ssc_tab as i64) != 0 { return 1 }
  ssc_tab = sys_mmap(8 * SSC_SLOTS * SSC_W) as *i64
  ssc_names = sys_mmap(SSC_SLOTS * 256)
  ssc_scr = sys_mmap(SS_MAGIC_1024)
  ssc_retired = sys_mmap(8 * (SSC_RETIRE + 1)) as *i64
  return 1
2057}
2058
2059// ---- RETIRE / REAP (seq1057) -------------------------------------------------------------------
2060// THE PROBLEM: on a stale manifest signature ss_open_cached re-opens and OVERWRITES the cached handle.
2061// The previous handle's whole mapping set (segments, keys, docs, terms, post, live-doc maps, scratch
2062// arena) was simply dropped on the floor -- orphaned on every edit to that store.
2063//
2064// WHY NOT JUST ss_close(old) THERE: ss_open_cached hands back a RAW handle and promises the same handle
2065// semantics as ss_open. There is no refcount and no generation, so a caller that took the handle before
2066// the invalidation is still dereferencing it. Freeing inline would turn a bounded LEAK into an unbounded
2067// USE-AFTER-FREE in the most-shared primitive in the ecosystem. That trade is never worth it.
2068//
2069// THE SHAPE THAT IS SOUND WITHOUT TOUCHING ~180 READERS: retiring NEVER frees, so it cannot fault. The
2070// orphan is merely remembered instead of lost. Reclamation is an EXPLICIT, OPT-IN call that a consumer
2071// makes at a point where it knows it holds no handle -- the top of a request loop, between batches. Until
2072// a consumer opts in, behaviour is byte-for-byte what it is today, so this can never regress a caller.
2073//
2074// FAIL-SAFE DIRECTION: if the ring is full we DROP the pointer (leak it) rather than free it. Overflow
2075// degrades to exactly today's behaviour, never to a free that might still be in use.
2076func ssc_retire_handle(h: i64) -> i64 {
  if h == 0 { return 0 }
  let n: i64 = ssc_retired[0]
  if n >= SSC_RETIRE { return 0 }
  ssc_retired[1 + n] = h
  ssc_retired[0] = n + 1
  return 1
2083}
2084
2085// Release every retired handle. Returns how many were closed.
2086// *** CONTRACT: the CALLER guarantees no seg-store handle from ss_open_cached is still in use.
2087// Call it where that is structurally true (top of a request loop, between batches) -- never from inside
2088// a function that is holding a handle, and never from the primitive itself.
2089func ss_cache_reap() -> i64 {
  ssc_init()
  let n: i64 = ssc_retired[0]
  var i: i64 = 0
  var freed: i64 = 0
  while i < n {
      let h: i64 = ssc_retired[1 + i]
      if h != 0 { ss_close(h as *i64); freed = freed + 1 }
      ssc_retired[1 + i] = 0
      i = i + 1
  }
  ssc_retired[0] = 0
  return freed
2102}
2103
2104// How many orphans are awaiting a reap (observability for gates and daemons).
2105func ss_cache_retired() -> i64 {
  ssc_init()
  return ssc_retired[0]
2108}
2109func ssc_streq(a: *u8, b: *u8) -> i64 {
  var i: i64 = 0
  while a[i] != (0 as u8) {
      if b[i] != a[i] { return 0 }
      i = i + 1
  }
  if b[i] == (0 as u8) { return 1 }
  return 0
2117}
2118// manifest signature -> sig[0]=st_size sig[1]=st_mtime-sec ((0,0) when absent).
2119// Reuses the ONE static scratch buffer, so this probe allocates nothing per call.
2120func ssc_sig_of(prefix: *u8, sig: *i64) -> i64 {
  let mp: *u8 = ssc_scr
  var o: i64 = 0
  o = ss_cat(mp, o, prefix)
  o = ss_cat(mp, o, "manifest.txt" as *u8)
  mp[o] = 0 as u8
  let stb: *u8 = ((ssc_scr as i64) + 560) as *u8
  sig[0] = 0
  sig[1] = 0
  if sys_fstatat(mp, stb) == 0 {
      let szp: *i64 = ((stb as i64) + 48) as *i64
      let mtp: *i64 = ((stb as i64) + 88) as *i64
      sig[0] = szp[0]
      sig[1] = mtp[0]
  }
  return 0
2136}
2137// THE ONE OPEN long-lived readers should use. Same handle semantics as ss_open -- every ss_hget /
2138// ss_term / ss_phrase reader is unchanged. Fail-open: if the table is full we fall back to a plain
2139// ss_open rather than refusing, so caching can never break a caller.
2140func ss_open_cached(prefix: *u8) -> *i64 {
  ssc_init()
  let sig: *i64 = ((ssc_scr as i64) + 720) as *i64
  ssc_sig_of(prefix, sig)
  var i: i64 = 0
  var freeslot: i64 = 0 - 1
  while i < SSC_SLOTS {
      let np: i64 = ssc_tab[i * SSC_W]
      if np == 0 {
          if freeslot < 0 { freeslot = i }
      } else {
          if ssc_streq(np as *u8, prefix) == 1 {
              if ssc_tab[i * SSC_W + 3] != 0 {
                  if ssc_tab[i * SSC_W + 1] == sig[0] {
                      if ssc_tab[i * SSC_W + 2] == sig[1] { return ssc_tab[i * SSC_W + 3] as *i64 }
                  }
              }
              let hr: *i64 = ss_open(prefix)
              // seq1057: the previous handle used to be overwritten and lost here. Retiring does NOT
              // free it (a caller may still hold it) -- it only makes it reclaimable by ss_cache_reap.
              ssc_retire_handle(ssc_tab[i * SSC_W + 3])
              ssc_tab[i * SSC_W + 1] = sig[0]
              ssc_tab[i * SSC_W + 2] = sig[1]
              ssc_tab[i * SSC_W + 3] = hr as i64
              return hr
          }
      }
      i = i + 1
  }
  if freeslot < 0 { return ss_open(prefix) }
  let nm: *u8 = ((ssc_names as i64) + freeslot * 256) as *u8
  var k: i64 = 0
  while prefix[k] != (0 as u8) { if k < 255 { nm[k] = prefix[k] } k = k + 1 }
  if k > 255 { k = 255 }
  nm[k] = 0 as u8
  let hn: *i64 = ss_open(prefix)
  ssc_tab[freeslot * SSC_W] = nm as i64
  ssc_tab[freeslot * SSC_W + 1] = sig[0]
  ssc_tab[freeslot * SSC_W + 2] = sig[1]
  ssc_tab[freeslot * SSC_W + 3] = hn as i64
  return hn
2181}
2182
2183// PER-CALL SCRATCH, ALLOCATED ONCE (2026-07-30). ss_hget used to do TWO sys_mmap(16) calls PER
2184// INVOCATION and never free them. sys_mmap is a REAL mmap syscall (nx_syscalls.nx:167), not a bump
2185// allocator, so the kernel rounds each to a full page: ~8 KB LEAKED PER ss_hget CALL. ss_hget is the
2186// hottest read primitive in the ecosystem -- 205 call sites, and the loaders call it ONCE PER ROW --
2187// so a 10k-row scan leaked ~80 MB in scratch alone, dwarfing the per-open leak this lane started on.
2188//
2189// This is the SAME defect seq905 already fixed one function away: ss_open2's dp/dszp were allocated
2190// inside the per-segment loop and were hoisted out ("buffers hoisted, no mmap in inner loops"). The
2191// identical pattern in ss_hget was missed because the loop is in the CALLER, not in the function.
2192// ★LAW: a per-call allocation in a primitive is a per-CALLER-LOOP leak -- audit the primitive's call
2193// frequency, not just its own body.
2194//
2195// SAFE AS A STATIC: vo/vl are pure scratch for ss_idx_find's two outputs, written then read immediately
2196// with no intervening call that could re-enter ss_hget (VERIFIED: ss_idx_find does not call ss_hget).
2197// Static POINTER + lazy mmap is the established idiom here -- a BSS static ARRAY silently crashes
2198// handler modules on startup, so never use [N]i64.
2199static ssh_vo: *i64
2200static ssh_vl: *i64
2201func ss_hget(h: *i64, key: *u8, ptrout: *i64, lenout: *i64) -> i64 {
  let ns: i64 = h[0]
  if ns == 0 { return 0 - 1 }
  if (ssh_vo as i64) == 0 { ssh_vo = sys_mmap(16) as *i64 }
  if (ssh_vl as i64) == 0 { ssh_vl = sys_mmap(16) as *i64 }
  let vo: *i64 = ssh_vo
  let vl: *i64 = ssh_vl
  var s: i64 = ns - 1
  while s >= 0 {
      let r: i64 = ss_idx_find(h[1 + 8 * s] as *u8, h[2 + 8 * s], key, vo, vl)
      if r == 2 { return 0 }
      if r == 1 {
          if h[4 + 8 * s] < vo[0] + vl[0] { return 0 - 2 }
          ptrout[0] = h[3 + 8 * s] + vo[0]
          lenout[0] = vl[0]
          return 1
      }
      s = s - 1
  }
  return 0 - 1
2221}
2222
2223// binary-search a .terms blob; returns 1 + postoff/postlen/dcount in outs,
2224// -1 not found, -2 malformed/absent (old-format segment -> caller fails LOUD)
2225func ss_terms_find(tb: *u8, tsz: i64, term: *u8, outs: *i64) -> i64 {
  if tsz < 8 { return 0 - 2 }
  if tb[0] != (78 as u8) { return 0 - 2 }
  if tb[2] != (84 as u8) { return 0 - 2 }
  let n: i64 = ss_r32(tb, 4)
  let base: i64 = 8 + 4 * n
  let tl0: i64 = ss_len(term)
  var lo: i64 = 0
  var hi: i64 = n - 1
  while lo <= hi {
      let mid: i64 = (lo + hi) / 2
      let eo: i64 = base + ss_r32(tb, 8 + 4 * mid)
      let tl: i64 = ss_r32(tb, eo)
      let c: i64 = ss_kcmp((tb as i64 + eo + 4) as *u8, tl, term, tl0)
      if c == 0 {
          outs[0] = ss_r32(tb, eo + 4 + tl)
          outs[1] = ss_r32(tb, eo + 4 + tl + 4)
          outs[2] = ss_r32(tb, eo + 4 + tl + 8)
          return 1
      }
      if c < 0 { lo = mid + 1 }
      if c > 0 { hi = mid - 1 }
  }
  return 0 - 1
2249}
2250
2251// TERM SEARCH with CURRENT-STATE semantics.  A posting hit counts ONLY if it
2252// is the key's CURRENT entry (verified against the key index): a newer
2253// version without the term, or a tombstone, silently shadows older hits --
2254// stale text never answers for a live record.  Each current entry exists
2255// exactly once, so no dedup list is needed.  Returns match count (key
2256// ptr/len pairs into the handle's docs buffers), or -2 if ANY live segment
2257// lacks a .terms index (old-format -- fail LOUD, compaction is the upgrade
2258// path; never a silent partial answer).
2259func ss_term(h: *i64, term: *u8, kpout: *i64, klout: *i64, max: i64) -> i64 {
  let ns: i64 = h[0]
  var cnt: i64 = 0
  // loud pre-check: every live segment must carry the term index
  var s: i64 = 0
  while s < ns {
      if h[6 + 8 * s] < 8 { return 0 - 2 }
      s = s + 1
  }
  let outs: *i64 = h[1 + 9 * ns] as *i64
  let pos: *i64 = h[2 + 9 * ns] as *i64
  s = ns - 1
  while s >= 0 {
      let tb: *u8 = h[5 + 8 * s] as *u8
      let pb: *u8 = h[7 + 8 * s] as *u8
      let db: i64 = h[3 + 8 * s]
      let lm: *u8 = h[1 + 8 * ns + s] as *u8
      let r: i64 = ss_terms_find(tb, h[6 + 8 * s], term, outs)
      if r == 1 {
          pos[0] = outs[0]
          var prev: i64 = 0
          var k: i64 = 0
          while k < outs[2] {
              let d: i64 = prev + ss_vr(pb, pos)
              prev = d
              // currency check: O(1) via the handle's live-doc map (computed
              // once at open; identical semantics to the keyed re-verify)
              if lm[d] == (1 as u8) {
                  let eoff: i64 = ss_r32(pb, 8 + 4 * d)
                  let ep: *u8 = (db + eoff) as *u8
                  let kl: i64 = ss_r32(ep, 1)
                  if cnt < max {
                      kpout[cnt] = db + eoff + 5
                      klout[cnt] = kl
                      cnt = cnt + 1
                  }
              }
              k = k + 1
          }
      }
      s = s - 1
  }
  return cnt
2302}
2303
2304// MULTI-TERM AND (IM2c): keys whose CURRENT record contains EVERY term.
2305// A key's current entry lives in exactly ONE segment, so the AND is computed
2306// per segment: every term's postings list (sorted ascending doc ids) is
2307// merge-intersected (O(sum of list lengths)), then survivors pass the O(1)
2308// live-doc currency check -- same current-state semantics as ss_term (stale
2309// versions and tombstones never answer).  Returns match count into
2310// kpout/klout, or -2 when any live segment lacks a .terms index (fail LOUD,
2311// never a silent partial answer).
2312func ss_term_and(h: *i64, terms: *i64, nterms: i64, kpout: *i64, klout: *i64, max: i64) -> i64 {
  if nterms <= 0 { return 0 }
  let ns: i64 = h[0]
  var s: i64 = 0
  while s < ns {
      if h[6 + 8 * s] < 8 { return 0 - 2 }
      s = s + 1
  }
  if nterms == 1 { return ss_term(h, terms[0] as *u8, kpout, klout, max) }
  if nterms > 64 { return 0 - 3 }
  let outs: *i64 = h[1 + 9 * ns] as *i64
  let pos: *i64 = h[2 + 9 * ns] as *i64
  let poffs: *i64 = h[5 + 9 * ns] as *i64
  let pdcs: *i64 = h[6 + 9 * ns] as *i64
  var cnt: i64 = 0
  s = ns - 1
  while s >= 0 {
      let tb: *u8 = h[5 + 8 * s] as *u8
      let pb: *u8 = h[7 + 8 * s] as *u8
      let db: i64 = h[3 + 8 * s]
      let lm: *u8 = h[1 + 8 * ns + s] as *u8
      // every term must appear in THIS segment's dict or it contributes 0
      var allp: i64 = 1
      var t: i64 = 0
      while t < nterms {
          let r: i64 = ss_terms_find(tb, h[6 + 8 * s], terms[t] as *u8, outs)
          if r == 1 { poffs[t] = outs[0]; pdcs[t] = outs[2] } else { allp = 0 }
          t = t + 1
      }
      if allp == 1 {
          let la: *i64 = h[3 + 9 * ns] as *i64
          let lb: *i64 = h[4 + 9 * ns] as *i64
          // decode term 0 into la
          pos[0] = poffs[0]
          var prev: i64 = 0
          var na: i64 = 0
          var k: i64 = 0
          while k < pdcs[0] {
              prev = prev + ss_vr(pb, pos)
              la[na] = prev
              na = na + 1
              k = k + 1
          }
          // streaming two-pointer intersect with each further term's list
          t = 1
          while t < nterms {
              if na == 0 { t = nterms } else {
                  pos[0] = poffs[t]
                  prev = 0
                  var ai: i64 = 0
                  var nb: i64 = 0
                  k = 0
                  while k < pdcs[t] {
                      prev = prev + ss_vr(pb, pos)
                      var adv: i64 = 1
                      while adv == 1 {
                          if ai >= na { adv = 0 } else {
                              if la[ai] < prev { ai = ai + 1 } else { adv = 0 }
                          }
                      }
                      if ai < na { if la[ai] == prev { lb[nb] = prev; nb = nb + 1; ai = ai + 1 } }
                      k = k + 1
                  }
                  var c2: i64 = 0
                  while c2 < nb { la[c2] = lb[c2]; c2 = c2 + 1 }
                  na = nb
                  t = t + 1
              }
          }
          // survivors: O(1) currency check, then emit key ptr/len
          var i2: i64 = 0
          while i2 < na {
              let d: i64 = la[i2]
              if lm[d] == (1 as u8) {
                  let eoff: i64 = ss_r32(pb, 8 + 4 * d)
                  let ep: *u8 = (db + eoff) as *u8
                  if cnt < max {
                      kpout[cnt] = db + eoff + 5
                      klout[cnt] = ss_r32(ep, 1)
                      cnt = cnt + 1
                  }
              }
              i2 = i2 + 1
          }
      }
      s = s - 1
  }
  return cnt
2400}
2401
2402// ---- RANKING STATISTICS (additive, 2026-07-03: the BM25/IDF rung reads them) --------------------
2403// n_t: how many docs carry `term`, summed from each live segment's .terms dcount (the statistic
2404// ss_build_terms already persists). Write-time counts: a shadowed older version still counts -- for
2405// IDF ranking that bias is negligible and the read is O(log terms) per segment, no posting decode.
2406// Same loud contract as ss_term: -2 when any live segment lacks a .terms index.
2407func ss_term_dcount(h: *i64, term: *u8) -> i64 {
  let ns: i64 = h[0]
  var s: i64 = 0
  while s < ns {
      if h[6 + 8 * s] < 8 { return 0 - 2 }
      s = s + 1
  }
  let outs: *i64 = h[1 + 9 * ns] as *i64
  var n: i64 = 0
  s = 0
  while s < ns {
      let r: i64 = ss_terms_find(h[5 + 8 * s] as *u8, h[6 + 8 * s], term, outs)
      if r == 1 { n = n + outs[2] }
      s = s + 1
  }
  return n
2423}
2424// TERM-DICTIONARY ITERATION (additive, 2026-07-03: the typo/suggest rung reads the index's own sorted
2425// term dictionary -- the same .terms blobs the postings live in; no separate dictionary artifact).
2426// ss_term_count(h, s) = how many terms segment s indexes; ss_term_at fills term ptr/len + dcount for
2427// entry idx (terms are sorted within a segment). Returns 1 ok / 0 out-of-range or absent index.
2428func ss_term_count(h: *i64, s: i64) -> i64 {
  if s < 0 { return 0 }
  if s >= h[0] { return 0 }
  let tb: *u8 = h[5 + 8 * s] as *u8
  if h[6 + 8 * s] < 8 { return 0 }
  return ss_r32(tb, 4)
2434}
2435func ss_term_at(h: *i64, s: i64, idx: i64, tp_out: *i64, tl_out: *i64, dc_out: *i64) -> i64 {
  if s < 0 { return 0 }
  if s >= h[0] { return 0 }
  let tb: *u8 = h[5 + 8 * s] as *u8
  let tsz: i64 = h[6 + 8 * s]
  if tsz < 8 { return 0 }
  let n: i64 = ss_r32(tb, 4)
  if idx < 0 { return 0 }
  if idx >= n { return 0 }
  let base: i64 = 8 + 4 * n
  let eo: i64 = base + ss_r32(tb, 8 + 4 * idx)
  let tl: i64 = ss_r32(tb, eo)
  tp_out[0] = (tb as i64) + eo + 4
  tl_out[0] = tl
  dc_out[0] = ss_r32(tb, eo + 4 + tl + 8)
  return 1
2451}
2452
2453// N: how many "doc:"-prefixed put-keys the live segments' key indexes hold (each .keys entry is its
2454// key's latest-in-segment; cross-segment re-adds are prevented upstream by skip-if-present ingest, so
2455// this is the corpus size for IDF at O(total keys) once per query -- exactness via compaction later).
2456func ss_doc_count(h: *i64) -> i64 {
  let ns: i64 = h[0]
  var n: i64 = 0
  var s: i64 = 0
  while s < ns {
      let kb: *u8 = h[1 + 8 * s] as *u8
      if h[2 + 8 * s] >= 8 {
          let m9: i64 = ss_r32(kb, 4)
          var e9: i64 = 0
          while e9 < m9 {
              let eo: i64 = 8 + 4 * m9 + ss_r32(kb, 8 + 4 * e9)
              if (kb[eo] as i64) == 1 {
                  let kl9: i64 = ss_r32(kb, eo + 1)
                  if kl9 >= 4 {
                      if kb[eo + 5] == (100 as u8) { if kb[eo + 6] == (111 as u8) { if kb[eo + 7] == (99 as u8) { if kb[eo + 8] == (58 as u8) {
                          n = n + 1
                      } } } }
                  }
              }
              e9 = e9 + 1
          }
      }
      s = s + 1
  }
  return n
2481}
2482
2483// ---- PHRASE SUPPORT (2026-07-03, additive): the NXQ1 positions sidecar readers + the evaluator ----
2484// like ss_terms_find but returns the term's SORTED ORDINAL (the NXQ1 entry index) instead of just 1
2485func ss_terms_ordinal(tb: *u8, tsz: i64, term: *u8, outs: *i64) -> i64 {
  if tsz < 8 { return 0 - 2 }
  if tb[0] != (78 as u8) { return 0 - 2 }
  if tb[2] != (84 as u8) { return 0 - 2 }
  let n: i64 = ss_r32(tb, 4)
  let base: i64 = 8 + 4 * n
  let tl0: i64 = ss_len(term)
  var lo: i64 = 0
  var hi: i64 = n - 1
  while lo <= hi {
      let mid: i64 = (lo + hi) / 2
      let eo: i64 = base + ss_r32(tb, 8 + 4 * mid)
      let tl: i64 = ss_r32(tb, eo)
      let c: i64 = ss_kcmp((tb as i64 + eo + 4) as *u8, tl, term, tl0)
      if c == 0 {
          outs[0] = ss_r32(tb, eo + 4 + tl)
          outs[1] = ss_r32(tb, eo + 4 + tl + 4)
          outs[2] = ss_r32(tb, eo + 4 + tl + 8)
          return mid
      }
      if c < 0 { lo = mid + 1 }
      if c > 0 { hi = mid - 1 }
  }
  return 0 - 1
2509}
2510// decode the position run for posting-rank `rank` of term-ordinal `ord` from an NXQ1 blob.
2511// Returns npos decoded into posout (cap maxpos; longer runs are truncated -- adjacency over the first
2512// maxpos occurrences), or -1 malformed/absent.
2513func ss_q_positions(qb: *u8, qsz: i64, ord: i64, rank: i64, posout: *i64, maxpos: i64) -> i64 {
  if qsz < 8 { return 0 - 1 }
  if qb[0] != (78 as u8) { return 0 - 1 }
  if qb[2] != (81 as u8) { return 0 - 1 }
  let nt: i64 = ss_r32(qb, 4)
  if ord < 0 { return 0 - 1 }
  if ord >= nt { return 0 - 1 }
  let qbase: i64 = 8 + 4 * nt
  let pos: *i64 = sys_mmap(16) as *i64
  pos[0] = qbase + ss_r32(qb, 8 + 4 * ord)
  // skip `rank` runs
  var r: i64 = 0
  while r < rank {
      let n0: i64 = ss_vr(qb, pos)
      var k0: i64 = 0
      while k0 < n0 { ss_vr(qb, pos); k0 = k0 + 1 }
      r = r + 1
  }
  let np: i64 = ss_vr(qb, pos)
  var cum: i64 = 0
  var w: i64 = 0
  var k: i64 = 0
  while k < np {
      cum = cum + ss_vr(qb, pos)
      if w < maxpos { posout[w] = cum; w = w + 1 }
      k = k + 1
  }
  return w
2541}
2542// IMPACT-ORDERED TERM SEARCH (2026-07-25, the WAND rung): like ss_term but when the term has more
2543// postings than `max`, the cap keeps the HIGHEST-tf postings across all live segments instead of the
2544// first `max` in (segment, doc-asc) order -- and each hit's tf is returned (tfout) so candidacy needs
2545// zero doc reads. Cost is O(segments * SS_IMP_K), NOT O(total postings): the full-list decode ss_term
2546// pays per query disappears. Requires EVERY live segment to carry .imp: returns -3 when any lacks it
2547// and the caller falls back to ss_term (exact legacy behavior; compaction / nx_seg_imp_build upgrade a
2548// shard in place). -2 = missing .terms (same loud contract as ss_term). Currency semantics identical:
2549// the per-segment live-doc map filters stale versions and tombstones. Ties in tf resolve newest-
2550// segment-first then ascending doc -- deterministic.
2551// satout[0] (1-slot): set to 1 iff the answer is TRUNCATED -- a segment's stored impact list was
2552// build-capped at SS_IMP_K, the cross-segment collect filled, or the emit dropped past `max`. This is
2553// the reader's OWN truncation knowledge: exact by construction, immune to the shadow-inflated
2554// write-time dcount statistic (a re-committed doc inflates dcnt but never this flag).
2555func ss_term_top(prefix: *u8, h: *i64, term: *u8, kpout: *i64, klout: *i64, tfout: *i64, max: i64, satout: *i64) -> i64 {
  satout[0] = 0
  let ns: i64 = h[0]
  var s0: i64 = 0
  while s0 < ns {
      if h[6 + 8 * s0] < 8 { return 0 - 2 }
      s0 = s0 + 1
  }
  if max <= 0 { return 0 }
  let sp2: *i64 = sys_mmap(8) as *i64
  let ns2: i64 = ss_manifest_dyn(prefix, sp2)
  let segs: *i64 = sp2[0] as *i64
  var nseg: i64 = ns
  if ns2 < nseg { nseg = ns2 }
  if nseg <= 0 { return 0 }
  // load every live segment's .imp up front: ANY absent -> -3 (all-or-nothing keeps the ordering
  // semantics whole; a half-upgraded shard serves exactly like a non-upgraded one)
  let ibs: *i64 = sys_mmap(8 * (nseg + 4)) as *i64
  let iszs: *i64 = sys_mmap(8 * (nseg + 4)) as *i64
  let np9: *u8 = sys_mmap(512)
  let szp9: *i64 = sys_mmap(16) as *i64
  var s: i64 = 0
  while s < nseg {
      var o9: i64 = 0
      o9 = ss_cat(np9, o9, prefix)
      o9 = ss_cat(np9, o9, segs[s] as *u8)
      o9 = ss_cat(np9, o9, ".imp" as *u8)
      np9[o9] = 0 as u8
      szp9[0] = 0
      let ib: *u8 = ss_loadfile(np9, szp9, 1)
      var ok9: i64 = 0
      if (ib as i64) != 0 { if szp9[0] >= 8 { if ib[0] == (78 as u8) { if ib[2] == (87 as u8) { ok9 = 1 } } } }
      if ok9 == 0 { return 0 - 3 }
      ibs[s] = ib as i64
      iszs[s] = szp9[0]
      s = s + 1
  }
  // collect live (segment, docidx, tf) from each impact list, newest segment first
  let cap: i64 = nseg * SS_IMP_K + 16
  let colls: *i64 = sys_mmap(8 * cap) as *i64
  let colld: *i64 = sys_mmap(8 * cap) as *i64
  let collt: *i64 = sys_mmap(8 * cap) as *i64
  var n: i64 = 0
  let outs: *i64 = sys_mmap(32) as *i64
  let vp: *i64 = sys_mmap(16) as *i64
  s = nseg - 1
  while s >= 0 {
      let tb: *u8 = h[5 + 8 * s] as *u8
      let lm: *u8 = h[1 + 8 * ns + s] as *u8
      let od: i64 = ss_terms_ordinal(tb, h[6 + 8 * s], term, outs)
      if od >= 0 {
          let ib2: *u8 = ibs[s] as *u8
          let nt9: i64 = ss_r32(ib2, 4)
          if od < nt9 {
              let ibase: i64 = 8 + 4 * nt9
              vp[0] = ibase + ss_r32(ib2, 8 + 4 * od)
              let k9: i64 = ss_vr(ib2, vp)
              if k9 >= SS_IMP_K { satout[0] = 1 }
              var i9: i64 = 0
              while i9 < k9 {
                  if vp[0] > iszs[s] { i9 = k9 } else {
                      let d9: i64 = ss_vr(ib2, vp)
                      let f9: i64 = ss_vr(ib2, vp)
                      if lm[d9] == (1 as u8) {
                          if n < cap { colls[n] = s; colld[n] = d9; collt[n] = f9; n = n + 1 } else { satout[0] = 1 }
                      }
                      i9 = i9 + 1
                  }
              }
          }
      }
      s = s - 1
  }
  if n == 0 { return 0 }
  // STRICT tf-DESCENDING emit via counting sort over the clamped-tf buckets: O(n + 1024), stable
  // within a bucket (collect order = newest segment first, list order within = ascending doc), so
  // ties are deterministic. tf >= 1023 collapses into the top bucket -- ordering granularity above
  // that is irrelevant to candidacy and the STORED tf stays true. A future WAND early-termination
  // reader can rely on this prefix-is-best contract.
  let hist2: *i64 = sys_mmap(8 * SS_MAGIC_1024) as *i64
  var ih: i64 = 0
  while ih < n {
      var cv: i64 = collt[ih]
      if cv > 1023 { cv = 1023 }
      hist2[cv] = hist2[cv] + 1
      ih = ih + 1
  }
  let boff: *i64 = sys_mmap(8 * SS_MAGIC_1024) as *i64
  var acc2: i64 = 0
  var bb: i64 = 1023
  while bb >= 0 {
      boff[bb] = acc2
      acc2 = acc2 + hist2[bb]
      bb = bb - 1
  }
  let ord: *i64 = sys_mmap(8 * (n + 4)) as *i64
  ih = 0
  while ih < n {
      var cv2: i64 = collt[ih]
      if cv2 > 1023 { cv2 = 1023 }
      ord[boff[cv2]] = ih
      boff[cv2] = boff[cv2] + 1
      ih = ih + 1
  }
  var k2: i64 = n
  if k2 > max { k2 = max; satout[0] = 1 }
  var cnt: i64 = 0
  while cnt < k2 {
      let i2: i64 = ord[cnt]
      let sx: i64 = colls[i2]
      let pb: *u8 = h[7 + 8 * sx] as *u8
      let db: i64 = h[3 + 8 * sx]
      let eoff: i64 = ss_r32(pb, 8 + 4 * colld[i2])
      let ep: *u8 = (db + eoff) as *u8
      kpout[cnt] = db + eoff + 5
      klout[cnt] = ss_r32(ep, 1)
      tfout[cnt] = collt[i2]
      cnt = cnt + 1
  }
  return cnt
2675}
2676
2677// THE PHRASE EVALUATOR: docs whose CURRENT text contains terms[0..nterms) as ADJACENT tokens, in order.
2678// Candidates come from the per-segment postings intersect (AND); adjacency is checked in the NXQ1
2679// sidecar. A segment WITHOUT a sidecar (pre-phrase format) contributes its AND matches and clears
2680// exactout[0] -- graceful degrade, never a refusal; compaction upgrades it. -2 = missing .terms (loud,
2681// same contract as ss_term). exactout[0]: 1 = adjacency enforced everywhere, 0 = degraded somewhere.
2682func ss_phrase(prefix: *u8, h: *i64, terms: *i64, nterms: i64, kpout: *i64, klout: *i64, max: i64, exactout: *i64) -> i64 {
  exactout[0] = 1
  if nterms < 2 { return 0 }
  if nterms > 8 { return 0 - 3 }
  let ns: i64 = h[0]
  var s0: i64 = 0
  while s0 < ns {
      if h[6 + 8 * s0] < 8 { return 0 - 2 }
      s0 = s0 + 1
  }
  let sp2: *i64 = sys_mmap(8) as *i64
  let ns2: i64 = ss_manifest_dyn(prefix, sp2)
  let segs: *i64 = sp2[0] as *i64
  var nseg: i64 = ns
  if ns2 < nseg { nseg = ns2 }
  let ords: *i64 = sys_mmap(8 * 8) as *i64
  let outs: *i64 = sys_mmap(32) as *i64
  let poffs: *i64 = sys_mmap(8 * 8) as *i64
  let pdcs: *i64 = sys_mmap(8 * 8) as *i64
  let p1: *i64 = sys_mmap(8 * 520) as *i64
  let p2: *i64 = sys_mmap(8 * 520) as *i64
  let qszp: *i64 = sys_mmap(16) as *i64
  let vpos: *i64 = sys_mmap(16) as *i64
  var cnt: i64 = 0
  var s: i64 = 0
  while s < nseg {
      let tb: *u8 = h[5 + 8 * s] as *u8
      let pb: *u8 = h[7 + 8 * s] as *u8
      let db: i64 = h[3 + 8 * s]
      let lm: *u8 = h[1 + 8 * ns + s] as *u8
      // every phrase term must exist in THIS segment's dict
      var allp: i64 = 1
      var t: i64 = 0
      while t < nterms {
          let od: i64 = ss_terms_ordinal(tb, h[6 + 8 * s], terms[t] as *u8, outs)
          if od < 0 { allp = 0 } else {
              ords[t] = od
              poffs[t] = outs[0]
              pdcs[t] = outs[2]
          }
          t = t + 1
      }
      if allp == 1 {
          // decode each term's posting doc list (ascending)
          let dlist: *i64 = sys_mmap(8 * 8) as *i64
          var t2: i64 = 0
          while t2 < nterms {
              let arr: *i64 = sys_mmap(8 * (pdcs[t2] + 4)) as *i64
              vpos[0] = poffs[t2]
              var prev: i64 = 0
              var k: i64 = 0
              while k < pdcs[t2] {
                  prev = prev + ss_vr(pb, vpos)
                  arr[k] = prev
                  k = k + 1
              }
              dlist[t2] = arr as i64
              t2 = t2 + 1
          }
          // the segment's positions sidecar (absent -> degrade this segment to AND)
          let qp: *u8 = sys_mmap(512)
          var qo2: i64 = 0
          qo2 = ss_cat(qp, qo2, prefix)
          qo2 = ss_cat(qp, qo2, segs[s] as *u8)
          qo2 = ss_cat(qp, qo2, ".pos" as *u8)
          qp[qo2] = 0 as u8
          qszp[0] = 0
          let qb: *u8 = ss_readall(qp, qszp)
          var haveq: i64 = 0
          if (qb as i64) != 0 { if qszp[0] >= 8 { haveq = 1 } }
          if haveq == 0 { exactout[0] = 0 }
          // walk term0's docs; a doc survives iff present in EVERY list (ranks captured for NXQ1)
          let l0: *i64 = dlist[0] as *i64
          var i0: i64 = 0
          while i0 < pdcs[0] {
              let d: i64 = l0[i0]
              var inall: i64 = 1
              let ranks: *i64 = sys_mmap(8 * 8) as *i64
              ranks[0] = i0
              var t3: i64 = 1
              while t3 < nterms {
                  let lt: *i64 = dlist[t3] as *i64
                  var lo2: i64 = 0
                  var hi2: i64 = pdcs[t3] - 1
                  var fnd: i64 = 0 - 1
                  while lo2 <= hi2 {
                      let mid2: i64 = (lo2 + hi2) / 2
                      if lt[mid2] == d { fnd = mid2; lo2 = hi2 + 1 } else {
                          if lt[mid2] < d { lo2 = mid2 + 1 } else { hi2 = mid2 - 1 }
                      }
                  }
                  if fnd < 0 { inall = 0; t3 = nterms } else { ranks[t3] = fnd }
                  t3 = t3 + 1
              }
              if inall == 1 { if lm[d] == (1 as u8) {
                  var matched: i64 = 1
                  if haveq == 1 {
                      // adjacency ladder over the sidecar positions
                      var na: i64 = ss_q_positions(qb, qszp[0], ords[0], ranks[0], p1, 512)
                      var t4: i64 = 1
                      while t4 < nterms {
                          if na <= 0 { t4 = nterms } else {
                              let nb: i64 = ss_q_positions(qb, qszp[0], ords[t4], ranks[t4], p2, 512)
                              // S = { q in positions(t4) : q-1 in S_prev } (two-pointer, both ascending)
                              var wa: i64 = 0
                              var ia: i64 = 0
                              var ib: i64 = 0
                              while ia < na {
                                  if ib >= nb { ia = na } else {
                                      let want: i64 = p1[ia] + 1
                                      if p2[ib] == want { p1[wa] = want; wa = wa + 1; ia = ia + 1; ib = ib + 1 } else {
                                          if p2[ib] < want { ib = ib + 1 } else { ia = ia + 1 }
                                      }
                                  }
                              }
                              na = wa
                              t4 = t4 + 1
                          }
                      }
                      if na <= 0 { matched = 0 }
                  }
                  if matched == 1 {
                      let eoff: i64 = ss_r32(pb, 8 + 4 * d)
                      let ep: *u8 = (db + eoff) as *u8
                      if cnt < max {
                          kpout[cnt] = db + eoff + 5
                          klout[cnt] = ss_r32(ep, 1)
                          cnt = cnt + 1
                      }
                  }
              } }
              i0 = i0 + 1
          }
      }
      s = s + 1
  }
  return cnt
2819}
2820
2821// Indexed get (IM2): newest segment -> oldest, binary search each .keys;
2822// first hit decides (identical semantics to the chronological scan's
2823// last-match -- the gate proves equivalence against the scan as ORACLE).
2824// Any missing/malformed index => honest fallback to the scan path.
2825// SCRATCH ALLOCATED ONCE (2026-07-30, same class as the ss_hget fix above). ss_get_idx allocated FIVE
2826// page-granular scratch buffers PER CALL (sp/vo/vl/path/szp) and never freed them -- ~20 KB per call
2827// across 30 call sites. Statics are safe here for the same reason as ss_hget: these are pure scratch,
2828// written then read with no intervening call that re-enters ss_get_idx (VERIFIED: neither ss_get nor
2829// ss_idx_lookup calls back into it).
2830// ⚠DELIBERATELY NOT CACHED: the `b` buffer below (ss_readall of the whole .docs file) is what ptrout
2831// POINTS INTO, so it is returned data, not scratch -- caching or freeing it is the seq1356
2832// borrowed-pointer question and must not be done casually. Filed, not guessed at.
2833// ⚠ALSO STILL OPEN: this function re-reads the MANIFEST and re-maps a whole segment file on EVERY
2834// call -- the O(rows x segments) amplification seq356 already identified. The real remedy is the one
2835// sts_load adopted: ss_open ONCE + ss_hget per row. These statics only stop the bleeding.
2836static ssg_sp: *i64
2837static ssg_vo: *i64
2838static ssg_vl: *i64
2839func ss_get_idx(prefix: *u8, key: *u8, ptrout: *i64, lenout: *i64) -> i64 {
  if (ssg_sp as i64) == 0 { ssg_sp = sys_mmap(8) as *i64 }
  let sp: *i64 = ssg_sp
  let ns: i64 = ss_manifest_dyn(prefix, sp)
  let segs: *i64 = sp[0] as *i64
  if ns == 0 { return 0 - 1 }
  if (ssg_vo as i64) == 0 { ssg_vo = sys_mmap(16) as *i64 }
  if (ssg_vl as i64) == 0 { ssg_vl = sys_mmap(16) as *i64 }
  let vo: *i64 = ssg_vo
  let vl: *i64 = ssg_vl
  var s: i64 = ns - 1
  while s >= 0 {
      let r: i64 = ss_idx_lookup(prefix, segs[s] as *u8, key, vo, vl)
      if r == (0 - 2) { return ss_get(prefix, key, ptrout, lenout) }
      if r == 2 { return 0 }
      if r == 1 {
          let path: *u8 = sys_mmap(512)
          var o: i64 = 0
          o = ss_cat(path, o, prefix)
          o = ss_cat(path, o, segs[s] as *u8)
          o = ss_cat(path, o, ".docs" as *u8)
          path[o] = 0 as u8
          let szp: *i64 = sys_mmap(16) as *i64
          let b: *u8 = ss_readall(path, szp)
          if szp[0] < vo[0] + vl[0] { return 0 - 2 }
          ptrout[0] = (b as i64) + vo[0]
          lenout[0] = vl[0]
          return 1
      }
      s = s - 1
  }
  return 0 - 1
2871}
2872
2873// latest state of key: 1=found (ptrout[0]/lenout[0] set), 0=tombstoned, -1=absent
2874func ss_get(prefix: *u8, key: *u8, ptrout: *i64, lenout: *i64) -> i64 {
  let kinds: *i64 = sys_mmap(8 * SS_VER_SLOTS) as *i64
  let ptrs: *i64 = sys_mmap(8 * SS_VER_SLOTS) as *i64
  let lens: *i64 = sys_mmap(8 * SS_VER_SLOTS) as *i64
  let n: i64 = ss_scan(prefix, key, kinds, ptrs, lens)
  if n == 0 { return 0 - 1 }
  let last: i64 = n - 1
  if kinds[last] == 2 { return 0 }
  ptrout[0] = ptrs[last]
  lenout[0] = lens[last]
  return 1
2885}
2886
2887// ===== SEQUENTIAL CURSOR (added 2026-07-30) ================================
2888// THE DEFECT THIS KILLS: ss_get is a POINT lookup costing O(WHOLE-STORE BYTES)
2889// every call -- ss_scan -> ss_scan_seglist ss_readall()s the ENTIRE <seg>.docs
2890// of EVERY live segment per call and returns a pointer INTO that fresh mapping
2891// (so it can never be freed while in use). A whole-store pass built from point
2892// lookups is quadratic in time AND unbounded in mapped memory.
2893// MEASURED on the mvault store (37,058 records / 3 segments): 200 lookups
2894// survive, 10,000 DIES (rc=1, zero output). Read-side twin of the eaten
2895// seg-store quadratic WRITE defect.
2896// COST: one mapping per LIVE SEGMENT, not one per RECORD.
2897// CONTRACT: kout/vout point INTO the current mapping and are valid only until
2898// the NEXT ss_cur_next call. Records arrive chronologically, so for a key with
2899// several versions the LAST seen is current -- the same rule ss_get applies.
2900
2901const SS_CUR_SLOTS: i64 = 8
2902
2903func ss_cur_open(prefix: *u8) -> *i64 {
  let st: *i64 = sys_mmap(8 * SS_CUR_SLOTS) as *i64
  let sp: *i64 = sys_mmap(8) as *i64
  let ns: i64 = ss_manifest_dyn(prefix, sp)
  st[0] = sp[0]
  st[1] = ns
  st[2] = 0
  st[3] = 0
  st[4] = 0
  st[5] = 0
  st[6] = 0
  return st
2915}
2916
2917func ss_cur_next(prefix: *u8, st: *i64,
               kout: *i64, klout: *i64, vout: *i64, vlout: *i64) -> i64 {
  var guard: i64 = 0
  while guard < SS_MAGIC_1048576 {
      guard = guard + 1
      if st[3] == 0 {
          if st[2] >= st[1] { return 0 }
          let segs: *i64 = st[0] as *i64
          let path: *u8 = sys_mmap(512)
          var o: i64 = ss_cat(path, 0, prefix)
          o = ss_cat(path, o, segs[st[2]] as *u8)
          o = ss_cat(path, o, ".docs" as *u8)
          path[o] = 0 as u8
          let szp: *i64 = sys_mmap(16) as *i64
          let b: *u8 = ss_readall(path, szp)
          st[4] = szp[0]
          st[5] = 0
          if (b as i64) == 0 { st[4] = 0 }
          if st[4] <= 0 {
              st[3] = 0
              st[2] = st[2] + 1
          } else {
              st[3] = b as i64
          }
      }
      if st[3] != 0 {
          let b: *u8 = st[3] as *u8
          let sz: i64 = st[4]
          let i: i64 = st[5]
          var bad: i64 = 0
          if i + 9 > sz { bad = 1 }
          if bad == 0 {
              let kind: i64 = b[i]
              let kl: i64 = ss_r32(b, i + 1)
              let koff: i64 = i + 5
              if kl < 0 { bad = 1 }
              if koff + kl + 4 > sz { bad = 1 }
              if bad == 0 {
                  let vl: i64 = ss_r32(b, koff + kl)
                  let voff: i64 = koff + kl + 4
                  if vl < 0 { bad = 1 }
                  if voff + vl > sz { bad = 1 }
                  if bad == 0 {
                      st[5] = voff + vl
                      st[6] = kind
                      kout[0] = (b as i64) + koff
                      klout[0] = kl
                      vout[0] = (b as i64) + voff
                      vlout[0] = vl
                      return 1
                  }
              }
          }
          st[3] = 0
          st[2] = st[2] + 1
      }
  }
  return 0
2975}
2976
2977// COMPACTION (IM4): fold all live segments into ONE new segment holding only
2978// the LATEST entry per key (superseded versions dropped; tombstones KEPT so
2979// get() semantics are EXACTLY preserved incl. GONE-vs-ABSENT -- tombstone GC
2980// is a later policy rung).  HISTORY IS NOT DESTROYED: retired segment files
2981// stay on disk and their names are appended to <prefix>manifest-archive.txt
2982// BEFORE the live-manifest swap (crash between the two leaves the old
2983// manifest intact = consistent; the archive only ever gains rows).  The swap
2984// itself is the same atomic temp->rename commit point.
2985// Returns the new segid (>0) or negative on failure.
2986func ss_compact(prefix: *u8, segid: i64) -> i64 {
  let sp: *i64 = sys_mmap(8) as *i64
  let ns: i64 = ss_manifest_dyn(prefix, sp)
  let segs: *i64 = sp[0] as *i64
  if ns <= 0 { return 0 - 1 }
  // read every live segment first; key-table capacity is DATA-DRIVEN from
  // the total bytes (every record >= 9 bytes), never a silent fixed cap
  let bptrs: *i64 = sys_mmap(8 * ns + 64) as *i64
  let bszs: *i64 = sys_mmap(8 * ns + 64) as *i64
  var total: i64 = 0
  var s: i64 = 0
  while s < ns {
      let path: *u8 = sys_mmap(512)
      var o: i64 = 0
      o = ss_cat(path, o, prefix)
      o = ss_cat(path, o, segs[s] as *u8)
      o = ss_cat(path, o, ".docs" as *u8)
      path[o] = 0 as u8
      let szp: *i64 = sys_mmap(16) as *i64
      bptrs[s] = ss_readall(path, szp) as i64
      bszs[s] = szp[0]
      if bszs[s] > 0 { total = total + bszs[s] }
      s = s + 1
  }
  let maxk: i64 = total / 9 + 16
  let tkp: *i64 = sys_mmap(8 * maxk) as *i64
  let tkl: *i64 = sys_mmap(8 * maxk) as *i64
  let tkind: *i64 = sys_mmap(8 * maxk) as *i64
  let tvp: *i64 = sys_mmap(8 * maxk) as *i64
  let tvl: *i64 = sys_mmap(8 * maxk) as *i64
  var nk: i64 = 0
  s = 0
  while s < ns {
      let b: *u8 = bptrs[s] as *u8
      let sz: i64 = bszs[s]
      var i: i64 = 0
      while i + 9 <= sz {
          let kind: i64 = b[i]
          let kl: i64 = ss_r32(b, i + 1)
          let koff: i64 = i + 5
          let vl: i64 = ss_r32(b, koff + kl)
          let voff: i64 = koff + kl + 4
          // find existing key slot (chronological walk => overwrite = last wins)
          var hit: i64 = 0 - 1
          var t: i64 = 0
          while t < nk {
              if hit < 0 {
                  if ss_kcmp(tkp[t] as *u8, tkl[t], (b as i64 + koff) as *u8, kl) == 0 { hit = t }
              }
              t = t + 1
          }
          if hit < 0 {
              if nk >= maxk { return 0 - 7 }
              hit = nk
              nk = nk + 1
              tkp[hit] = (b as i64) + koff
              tkl[hit] = kl
          }
          if hit >= 0 {
              tkp[hit] = (b as i64) + koff
              tkl[hit] = kl
              tkind[hit] = kind
              tvp[hit] = (b as i64) + voff
              tvl[hit] = vl
          }
          i = voff + vl
      }
      s = s + 1
  }
  // merged segment = latest entry per key; writer sized data-driven from the merged total (no fixed cap)
  let w: *i64 = ss_begin_cap(total + SS_MAGIC_65536)
  var t2: i64 = 0
  while t2 < nk {
      if ss_add2(w, tkind[t2], tkp[t2] as *u8, tkl[t2], tvp[t2] as *u8, tvl[t2]) != 0 { return 0 - 2 }
      t2 = t2 + 1
  }
  if ss_write_seg(prefix, w, segid) != 0 { return 0 - 3 }
  // archive the retired segment names (append-only; survives any crash here)
  let ap: *u8 = sys_mmap(512)
  var ao: i64 = 0
  ao = ss_cat(ap, ao, prefix)
  ao = ss_cat(ap, ao, "manifest-archive.txt" as *u8)
  ap[ao] = 0 as u8
  let afd: i64 = sys_openat_append(ap, 0x1a4)
  if afd < 0 { return 0 - 4 }
  s = 0
  while s < ns {
      let nm: *u8 = segs[s] as *u8
      sys_write(afd, nm, ss_len(nm))
      sys_write(afd, "\n" as *u8, 1)
      s = s + 1
  }
  sys_fsync(afd)
  sys_close(afd)
  // atomic live-manifest swap to ONLY the merged segment
  let mf: *u8 = sys_mmap(512)
  let mt: *u8 = sys_mmap(512)
  var o2: i64 = 0
  o2 = ss_cat(mf, o2, prefix)
  o2 = ss_cat(mf, o2, "manifest.txt" as *u8)
  mf[o2] = 0 as u8
  o2 = 0
  o2 = ss_cat(mt, o2, prefix)
  o2 = ss_cat(mt, o2, "manifest.tmp" as *u8)
  mt[o2] = 0 as u8
  let nb: *u8 = sys_mmap(128)
  var no: i64 = 0
  no = ss_cat(nb, no, "seg-" as *u8)
  no = ss_catn(nb, no, segid)
  nb[no] = 10 as u8
  no = no + 1
  if ss_writefile(mt, nb, no) != 0 { return 0 - 5 }
  if sys_renameat(mt, mf) != 0 { return 0 - 6 }
  ss_syncdir(prefix)
  return segid
3101}
3102
3103// author=tutor (LM-028 fix): cap-aware sibling of ss_compact for stores with >256 live segments
3104// (the GALX-PROD-FULL family: galx-prod holds ONE segment per image, so thousands accumulate and
3105// each ss_get/ss_scan re-reads every seg .docs = O(n) per lookup). ss_compact CANNOT fold such a
3106// store: it reads the manifest via ss_manifest (HARD cap 256) AND its ss_begin() writer caps at 1MB,
3107// so on a big store it would merge only the first 256 segs (or overflow the writer) and then swap the
3108// live manifest to that partial segment -- silently dropping ~90% of the corpus. This mirror reads
3109// ss_manifest_cap(cap) and allocates a DATA-DRIVEN writer (>= total input bytes; dedup only shrinks),
3110// so any segment count folds to ONE with NO data loss. ss_compact is left BYTE-IDENTICAL (purely
3111// additive). Every failure path returns BEFORE the atomic manifest swap, so a failure leaves the live
3112// store intact (crash/fail-safe). Returns the new segid (>0) or negative on failure.
3113func ss_compact_cap(prefix: *u8, segid: i64, cap: i64) -> i64 {
  let segs: *i64 = sys_mmap(8 * cap) as *i64
  let ns: i64 = ss_manifest_cap(prefix, segs, cap)
  if ns <= 0 { return 0 - 1 }
  // read every live segment; key-table + writer capacities are DATA-DRIVEN from total bytes
  let bptrs: *i64 = sys_mmap(8 * cap) as *i64
  let bszs: *i64 = sys_mmap(8 * cap) as *i64
  var total: i64 = 0
  var s: i64 = 0
  while s < ns {
      let path: *u8 = sys_mmap(512)
      var o: i64 = 0
      o = ss_cat(path, o, prefix)
      o = ss_cat(path, o, segs[s] as *u8)
      o = ss_cat(path, o, ".docs" as *u8)
      path[o] = 0 as u8
      let szp: *i64 = sys_mmap(16) as *i64
      bptrs[s] = ss_readall(path, szp) as i64
      bszs[s] = szp[0]
      if bszs[s] > 0 { total = total + bszs[s] }
      s = s + 1
  }
  let maxk: i64 = total / 9 + 16
  let tkp: *i64 = sys_mmap(8 * maxk) as *i64
  let tkl: *i64 = sys_mmap(8 * maxk) as *i64
  let tkind: *i64 = sys_mmap(8 * maxk) as *i64
  let tvp: *i64 = sys_mmap(8 * maxk) as *i64
  let tvl: *i64 = sys_mmap(8 * maxk) as *i64
  var nk: i64 = 0
  s = 0
  while s < ns {
      let b: *u8 = bptrs[s] as *u8
      let sz: i64 = bszs[s]
      var i: i64 = 0
      while i + 9 <= sz {
          let kind: i64 = b[i]
          let kl: i64 = ss_r32(b, i + 1)
          let koff: i64 = i + 5
          let vl: i64 = ss_r32(b, koff + kl)
          let voff: i64 = koff + kl + 4
          // chronological walk => last write wins (find existing key slot)
          var hit: i64 = 0 - 1
          var t: i64 = 0
          while t < nk {
              if hit < 0 {
                  if ss_kcmp(tkp[t] as *u8, tkl[t], (b as i64 + koff) as *u8, kl) == 0 { hit = t }
              }
              t = t + 1
          }
          if hit < 0 {
              if nk >= maxk { return 0 - 7 }
              hit = nk
              nk = nk + 1
              tkp[hit] = (b as i64) + koff
              tkl[hit] = kl
          }
          if hit >= 0 {
              tkp[hit] = (b as i64) + koff
              tkl[hit] = kl
              tkind[hit] = kind
              tvp[hit] = (b as i64) + voff
              tvl[hit] = vl
          }
          i = voff + vl
      }
      s = s + 1
  }
  // merged segment = latest entry per key; writer cap is DATA-DRIVEN (merged <= total + slack),
  // NOT the fixed 1MB of ss_begin() -- that is the second half of the cap fix.
  let w: *i64 = sys_mmap(32) as *i64
  let wcap: i64 = total + SS_MAGIC_1048576
  w[0] = sys_mmap(wcap) as i64
  w[1] = 0
  w[2] = wcap
  var t2: i64 = 0
  while t2 < nk {
      if ss_add2(w, tkind[t2], tkp[t2] as *u8, tkl[t2], tvp[t2] as *u8, tvl[t2]) != 0 { return 0 - 2 }
      t2 = t2 + 1
  }
  if ss_write_seg(prefix, w, segid) != 0 { return 0 - 3 }
  // archive the retired segment names (append-only; survives any crash here)
  let ap: *u8 = sys_mmap(512)
  var ao: i64 = 0
  ao = ss_cat(ap, ao, prefix)
  ao = ss_cat(ap, ao, "manifest-archive.txt" as *u8)
  ap[ao] = 0 as u8
  let afd: i64 = sys_openat_append(ap, 0x1a4)
  if afd < 0 { return 0 - 4 }
  s = 0
  while s < ns {
      let nm: *u8 = segs[s] as *u8
      sys_write(afd, nm, ss_len(nm))
      sys_write(afd, "\n" as *u8, 1)
      s = s + 1
  }
  sys_fsync(afd)
  sys_close(afd)
  // atomic live-manifest swap to ONLY the merged segment
  let mf: *u8 = sys_mmap(512)
  let mt: *u8 = sys_mmap(512)
  var o2: i64 = 0
  o2 = ss_cat(mf, o2, prefix)
  o2 = ss_cat(mf, o2, "manifest.txt" as *u8)
  mf[o2] = 0 as u8
  o2 = 0
  o2 = ss_cat(mt, o2, prefix)
  o2 = ss_cat(mt, o2, "manifest.tmp" as *u8)
  mt[o2] = 0 as u8
  let nb: *u8 = sys_mmap(128)
  var no: i64 = 0
  no = ss_cat(nb, no, "seg-" as *u8)
  no = ss_catn(nb, no, segid)
  nb[no] = 10 as u8
  no = no + 1
  if ss_writefile(mt, nb, no) != 0 { return 0 - 5 }
  if sys_renameat(mt, mf) != 0 { return 0 - 6 }
  ss_syncdir(prefix)
  return segid
3231}
nx_seg_store.nx source

`nx_seg_store.nx` source
