code wiki / (root) / nx_survey_engine.nx
`nx_survey_engine.nx` source

↩ module page · 818 lines · 36817 B
1// nx_survey_engine.nx -- the GENERAL survey/poll engine (operator 2026-07-10: "census capability to get
2// feedback from customers and also employees ... generalized ... surveying lds members on how their welfare
3// needs are doing ... simple one question poll or a deeper survey").
4// COMPOSES the existing substrate, no new silo: nx_survey.nx (R0 situation-management intake lib: sv_get/
5// sv_answer/sv_triage/sv_band stay the scoring layer) + nx_seg_store (additive, tombstone-not-delete) +
6// nx_canon_cid/nx_uxf_decode (canonical records). A POLL is just a 1-question survey -- same engine.
7//
8// DATA MODEL (everything is DATA, rule 11/25 -- a new survey is a spec file, never code):
9//   spec text  = "@survey <id>" "@title .." "@anon 0|1" "@kmin N" "@results pub|admin" "@audience .."
10//                "@maxtext N" + one "Q|<qid>|C|<prompt>|opt1|opt2.." / "Q|<qid>|S|<min>|<max>|<prompt>"
11//                / "Q|<qid>|T|<prompt>" line per question.
12//   store keys = "svy:<id>" (meta; close = a NEW version with status=closed -- latest wins, history kept)
13//                "qst:<id>:<n>" (question n, 1-based)
14//                "rsp:<id>:<token>" (ballot; a REVOTE is a NEW VERSION of the SAME key -> the seg_store's
15//                per-key latest-wins IS revote-replace: one respondent = one effective ballot, the count
16//                can never inflate, and every prior answer stays readable (additive law). The in-memory
17//                incumbent NEG-CONTROL for this lives in nx_connect_polls; here it is BY CONSTRUCTION.)
18// PRIVACY: anon surveys never surface tokens; k-floor (kmin) withholds aggregates below quorum (the
19// banner-survey cardinal's k-anonymity floor, here as spec DATA); text answers are admin-report-only.
20// No floats, no hardware writes. license_tier: ORIGINAL
21import "nx_syscalls.nx"
22import "nx_survey.nx"
23const SE_MAGIC_1024: i64 = 1024
24const SE_MAGIC_16384: i64 = 16384
25const SE_MAGIC_65536: i64 = 65536
26const SE_MAGIC_4096: i64 = 4096
27
28const SE_MAXSEG: i64 = 4096      // manifest walk bound; tally goes LOUD -1 at the bound, never silent
29// se_walk_latest ring (2026-08-19). The walk's key pool + hash table used to be fresh own-VMA
30// mappings PER CALL (~86 KB at cap 512) that could never be freed -- the returned keys alias the
31// pool -- so every home/results render leaked them. They are now a ROTATING RING of static slots.
32// WHY A RING AND NOT ONE STATIC: sv2_home iterates the surveys walk WHILE calling the ballots walk
33// per row, so TWO walks' results are live at once (measured nesting depth 2 across every call site);
34// SE_WALK_RING = 4 is twice that depth. THE CONTRACT A NEW CALLER MUST KEEP: results of at most
35// SE_WALK_RING walks are retained; a 5th concurrent walk recycles the oldest slot.
36// SE_WALK_CAPMAX = the largest cap any caller passes (SV2_MAXB=512 is the fleet max); a larger cap
37// REFUSES loud -- the slot is sized once and an overrun would corrupt where a refusal diagnoses.
38const SE_WALK_CAPMAX: i64 = 512
39const SE_WALK_RING: i64 = 4
40const SE_WALK_KEYB: i64 = 160          // per-key pool bytes (key <=150 + NUL, headroom named)
41const SE_WALK_KBSCR: i64 = 176         // per-key hash/compare scratch
42static se_wk_pool_g: *u8               // SE_WALK_RING x (SE_WALK_CAPMAX*SE_WALK_KEYB + SE_MAGIC_4096)
43static se_wk_ht_g: *i64                // SE_WALK_RING x 8*(2*SE_WALK_CAPMAX rounded to pow2 = 1024)
44static se_wk_kb_g: *u8                 // SE_WALK_RING x SE_WALK_KBSCR
45static se_wk_slot_g: i64
46const SE_MAXQ: i64 = 24          // questions per survey (protocol bound, refused LOUD at load)
47const SE_MAXOPT: i64 = 12        // options per choice question
48const SE_DEF_MAXTEXT: i64 = 2000 // text-answer protocol cap; spec @maxtext may lower it
49
50func se_slen(s: *u8) -> i64 { var n: i64 = 0; while s[n] != (0 as u8) { n = n + 1 } return n }
51func se_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 }
52func se_catc(dst: *u8, off: i64, code: i64) -> i64 { dst[off] = code as u8; return off + 1 }
53func se_catn(dst: *u8, off: i64, v: i64) -> i64 {
  var o: i64 = off
  var m: i64 = v
  if m < 0 { dst[o] = 45 as u8; o = o + 1; m = 0 - m }
  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
64}
65func se_seq(a: *u8, b: *u8) -> i64 {
  var i: i64 = 0
  while a[i] != (0 as u8) { if a[i] != b[i] { return 0 } i = i + 1 }
  if b[i] != (0 as u8) { return 0 }
  return 1
70}
71func se_starts(s: *u8, pfx: *u8) -> i64 { var i: i64 = 0; while pfx[i] != (0 as u8) { if s[i] != pfx[i] { return 0 } i = i + 1 } return 1 }
72// all decimal digits, at least one
73func se_digits(s: *u8) -> i64 {
  var i: i64 = 0
  while s[i] != (0 as u8) {
      let c: i64 = s[i] as i64
      if c < 48 { return 0 }
      if c > 57 { return 0 }
      i = i + 1
  }
  if i == 0 { return 0 }
  return 1
83}
84// survey id: a-z 0-9 dash, 1..40 (the of_name_ok discipline)
85func se_id_ok(s: *u8) -> i64 {
  var i: i64 = 0
  while s[i] != (0 as u8) {
      let c: i64 = s[i] as i64
      var ok: i64 = 0
      if c >= 97 { if c <= 122 { ok = 1 } }
      if c >= 48 { if c <= 57 { ok = 1 } }
      if c == 45 { ok = 1 }
      if ok == 0 { return 0 }
      i = i + 1
  }
  if i < 1 { return 0 }
  if i > 40 { return 0 }
  return 1
99}
100// respondent token: a-z 0-9 dash, 4..64
101func se_tok_ok(s: *u8) -> i64 {
  var i: i64 = 0
  while s[i] != (0 as u8) {
      let c: i64 = s[i] as i64
      var ok: i64 = 0
      if c >= 97 { if c <= 122 { ok = 1 } }
      if c >= 48 { if c <= 57 { ok = 1 } }
      if c == 45 { ok = 1 }
      if ok == 0 { return 0 }
      i = i + 1
  }
  if i < 4 { return 0 }
  if i > 64 { return 0 }
  return 1
115}
116// question id: a-z 0-9 dash underscore, 1..24
117func se_qid_ok(s: *u8) -> i64 {
  var i: i64 = 0
  while s[i] != (0 as u8) {
      let c: i64 = s[i] as i64
      var ok: i64 = 0
      if c >= 97 { if c <= 122 { ok = 1 } }
      if c >= 48 { if c <= 57 { ok = 1 } }
      if c == 45 { ok = 1 }
      if c == 95 { ok = 1 }
      if ok == 0 { return 0 }
      i = i + 1
  }
  if i < 1 { return 0 }
  if i > 24 { return 0 }
  return 1
132}
133func se_key_svy(id: *u8, out: *u8) -> i64 { var o: i64 = se_cat(out, 0, "svy:" as *u8); o = se_cat(out, o, id); out[o] = 0 as u8; return o }
134func se_key_qst(id: *u8, n: i64, out: *u8) -> i64 {
  var o: i64 = se_cat(out, 0, "qst:" as *u8)
  o = se_cat(out, o, id)
  o = se_catc(out, o, 58)
  o = se_catn(out, o, n)
  out[o] = 0 as u8
  return o
141}
142func se_key_rsp(id: *u8, tok: *u8, out: *u8) -> i64 {
  var o: i64 = se_cat(out, 0, "rsp:" as *u8)
  o = se_cat(out, o, id)
  o = se_catc(out, o, 58)
  o = se_cat(out, o, tok)
  out[o] = 0 as u8
  return o
149}
150
151// latest version of key -> canon-decoded fields. returns nfields, or -1 absent/tombstoned/malformed.
152// CACHED HANDLE, NOT ss_get_cap (2026-08-19, the resmon-trend patient): ss_get_cap ss_readall()s
153// EVERY live segment's whole .docs PER LOOKUP and its result pointer aliases into those fresh
154// mappings, so they can never be freed -- and every ballot commits a segment, so the cost GROWS with
155// the store. MEASURED as ~1.6 MB/beat of daemon VmSize creep. ss_open_cached maps the store ONCE PER
156// GENERATION (manifest-signature invalidation; superseded handles retire and the daemon reaps them at
157// its accept-loop top). ss_hget preserves the exact semantics the old call had: newest segment wins,
158// a tombstone returns 0, and both land here as the same -1 the callers already handle. canon_decode
159// COPIES every field out before return, so nothing outlives the handle. The old 256-segment-window
160// hazard this comment used to warn about is gone with the windowed reader itself: ss_open_cached
161// opens the WHOLE manifest.
162func se_get_dec(prefix: *u8, key: *u8, ks: *i64, vs: *i64, maxf: i64) -> i64 {
  let pp: *i64 = sys_mmap(16) as *i64
  let ll: *i64 = sys_mmap(16) as *i64
  let h: *i64 = ss_open_cached(prefix)
  if (h as i64) == 0 { return 0 - 1 }
  if ss_hget(h, key, pp, ll) != 1 { return 0 - 1 }
  let nf: i64 = canon_decode(pp[0] as *u8, ll[0], ks, vs, maxf)
  if nf < 0 { return 0 - 1 }
  return nf
171}
172// survey meta fields ("svy:<id>"); -1 when the survey does not exist
173func se_meta(prefix: *u8, id: *u8, ks: *i64, vs: *i64, maxf: i64) -> i64 {
  let key: *u8 = sys_mmap(96)
  se_key_svy(id, key)
  return se_get_dec(prefix, key, ks, vs, maxf)
177}
178// question n fields ("qst:<id>:<n>")
179func se_qst(prefix: *u8, id: *u8, n: i64, ks: *i64, vs: *i64, maxf: i64) -> i64 {
  let key: *u8 = sys_mmap(128)
  se_key_qst(id, n, key)
  return se_get_dec(prefix, key, ks, vs, maxf)
183}
184// integer meta/question field with default when absent (thresholds live in the RECORD = data-driven)
185func se_field_n(ks: *i64, vs: *i64, nf: i64, key: *u8, dflt: i64) -> i64 {
  let v: *u8 = sv_get(ks, vs, nf, key)
  if (v as i64) == 0 { return dflt }
  return sv_atoi(v)
189}
190
191// count pipe-separated options in an opts string ("Mon|Tue|Wed" -> 3; empty -> 0)
192func se_nopts(opts: *u8) -> i64 {
  if opts[0] == (0 as u8) { return 0 }
  var n: i64 = 1
  var i: i64 = 0
  while opts[i] != (0 as u8) { if opts[i] == (124 as u8) { n = n + 1 } i = i + 1 }
  return n
198}
199// copy option k (0-based) of a pipe-separated opts string into out; returns len or -1
200func se_opt(opts: *u8, k: i64, out: *u8, cap: i64) -> i64 {
  var idx: i64 = 0
  var i: i64 = 0
  var t: i64 = 0
  while 1 == 1 {
      let c: i64 = opts[i] as i64
      if c == 0 {
          if idx == k { out[t] = 0 as u8; return t }
          return 0 - 1
      }
      if c == 124 {
          if idx == k { out[t] = 0 as u8; return t }
          idx = idx + 1
          t = 0
      } else {
          if idx == k { if t < cap - 1 { out[t] = opts[i]; t = t + 1 } }
      }
      i = i + 1
  }
  return 0 - 1
220}
221
222// ---- spec parsing ----
223// field idx (0-based) of a '|'-separated line [ls,le) into out; returns len or -1 when absent
224func se_lfield(b: *u8, ls: i64, le: i64, idx: i64, out: *u8, cap: i64) -> i64 {
  var cur: i64 = 0
  var i: i64 = ls
  var t: i64 = 0
  var found: i64 = 0
  if idx == 0 { found = 1 }
  while i < le {
      let c: i64 = b[i] as i64
      if c == 124 {
          if cur == idx { out[t] = 0 as u8; return t }
          cur = cur + 1
          if cur == idx { found = 1 }
          t = 0
      } else {
          if cur == idx { if t < cap - 1 { out[t] = b[i]; t = t + 1 } }
      }
      i = i + 1
  }
  if cur == idx { if found == 1 { out[t] = 0 as u8; return t } }
  if cur > idx { return 0 - 1 }
  if found == 1 { out[t] = 0 as u8; return t }
  return 0 - 1
246}
247// rest-of-line after "@word " prefix into out
248func se_meta_val(b: *u8, ls: i64, le: i64, pfxlen: i64, out: *u8, cap: i64) -> i64 {
  var i: i64 = ls + pfxlen
  var t: i64 = 0
  while i < le { if t < cap - 1 { out[t] = b[i]; t = t + 1 } i = i + 1 }
  out[t] = 0 as u8
  return t
254}
255// does line [ls,le) start with pfx?
256func se_line_starts(b: *u8, ls: i64, le: i64, pfx: *u8) -> i64 {
  let pl: i64 = se_slen(pfx)
  if le - ls < pl { return 0 }
  var i: i64 = 0
  while i < pl { if b[ls + i] != pfx[i] { return 0 } i = i + 1 }
  return 1
262}
263
264// LOAD a survey spec into the store (svy: + qst: records, ONE commit).
265// Returns nq (>=1) and copies the id into idout, or LOUD negative:
266// -1 bad/missing @survey id  -2 bad question line  -3 too many questions  -4 store fail  -5 no questions
267func se_load(prefix: *u8, spec: *u8, slen: i64, idout: *u8, idcap: i64) -> i64 {
  let id: *u8 = sys_mmap(64)
  let title: *u8 = sys_mmap(256)
  let audience: *u8 = sys_mmap(64)
  let results: *u8 = sys_mmap(16)
  id[0] = 0 as u8
  title[0] = 0 as u8
  var ao: i64 = se_cat(audience, 0, "general" as *u8)
  audience[ao] = 0 as u8
  var ro: i64 = se_cat(results, 0, "pub" as *u8)
  results[ro] = 0 as u8
  var anon: i64 = 1
  var kmin: i64 = 0
  var maxtext: i64 = SE_DEF_MAXTEXT
  // @quota <N>: cap DISTINCT respondents at N. A revote by an existing respondent is always
  // allowed (it re-states their one ballot, never inflates the count); only a NEW token past
  // the cap is refused (se_respond -8). 0 = unlimited. Data-driven: the cap lives in the record.
  var quota: i64 = 0
  // attention-check (instructed-response) items: "@check <qid> <expected>" accumulates "qid:val," pairs.
  // The gold-standard C/IER guard -- a respondent whose answer to an @check question != expected is flagged
  // careless by the quality analyzer (nx_survey_quality). Stored as one meta field; data-driven, any survey.
  let checks: *u8 = sys_mmap(512)
  checks[0] = 0 as u8
  var chko: i64 = 0
  // question accumulators
  let qkind: *i64 = sys_mmap(8 * SE_MAXQ) as *i64
  let qidp: *i64 = sys_mmap(8 * SE_MAXQ) as *i64
  let qprompt: *i64 = sys_mmap(8 * SE_MAXQ) as *i64
  let qopts: *i64 = sys_mmap(8 * SE_MAXQ) as *i64
  let qmin: *i64 = sys_mmap(8 * SE_MAXQ) as *i64
  let qmax: *i64 = sys_mmap(8 * SE_MAXQ) as *i64
  var nq: i64 = 0
  let fb: *u8 = sys_mmap(512)
  var ls: i64 = 0
  while ls < slen {
      var le: i64 = ls
      while le < slen { if spec[le] == (10 as u8) { break } le = le + 1 }
      // trim trailing CR
      var lee: i64 = le
      if lee > ls { if spec[lee - 1] == (13 as u8) { lee = lee - 1 } }
      if lee > ls {
          if se_line_starts(spec, ls, lee, "@survey " as *u8) == 1 {
              se_meta_val(spec, ls, lee, 8, id, 64)
          } else { if se_line_starts(spec, ls, lee, "@title " as *u8) == 1 {
              se_meta_val(spec, ls, lee, 7, title, 256)
          } else { if se_line_starts(spec, ls, lee, "@anon " as *u8) == 1 {
              se_meta_val(spec, ls, lee, 6, fb, 512)
              anon = sv_atoi(fb)
          } else { if se_line_starts(spec, ls, lee, "@kmin " as *u8) == 1 {
              se_meta_val(spec, ls, lee, 6, fb, 512)
              kmin = sv_atoi(fb)
          } else { if se_line_starts(spec, ls, lee, "@maxtext " as *u8) == 1 {
              se_meta_val(spec, ls, lee, 9, fb, 512)
              let mt: i64 = sv_atoi(fb)
              if mt > 0 { if mt < SE_DEF_MAXTEXT { maxtext = mt } }
          } else { if se_line_starts(spec, ls, lee, "@quota " as *u8) == 1 {
              se_meta_val(spec, ls, lee, 7, fb, 512)
              let qv: i64 = sv_atoi(fb)
              if qv > 0 { quota = qv }
          } else { if se_line_starts(spec, ls, lee, "@audience " as *u8) == 1 {
              se_meta_val(spec, ls, lee, 10, audience, 64)
          } else { if se_line_starts(spec, ls, lee, "@results " as *u8) == 1 {
              se_meta_val(spec, ls, lee, 9, results, 16)
          } else { if se_line_starts(spec, ls, lee, "@check " as *u8) == 1 {
              // "@check <qid> <expected>" -> append "qid:expected," to checks (fb = "<qid> <expected>")
              se_meta_val(spec, ls, lee, 7, fb, 512)
              var csp: i64 = 0
              while fb[csp] != (0 as u8) { if fb[csp] == (32 as u8) { break } csp = csp + 1 }
              if fb[csp] == (32 as u8) {
                  var cci: i64 = 0
                  while cci < csp { checks[chko] = fb[cci]; chko = chko + 1; cci = cci + 1 }
                  checks[chko] = 58 as u8; chko = chko + 1
                  var cvi: i64 = csp + 1
                  while fb[cvi] != (0 as u8) { if fb[cvi] != (32 as u8) { checks[chko] = fb[cvi]; chko = chko + 1 } cvi = cvi + 1 }
                  checks[chko] = 44 as u8; chko = chko + 1
                  checks[chko] = 0 as u8
              }
          } else { if se_line_starts(spec, ls, lee, "Q|" as *u8) == 1 {
              if nq >= SE_MAXQ { return 0 - 3 }
              let qid: *u8 = sys_mmap(32)
              let kb: *u8 = sys_mmap(8)
              if se_lfield(spec, ls, lee, 1, qid, 32) <= 0 { return 0 - 2 }
              if se_qid_ok(qid) == 0 { return 0 - 2 }
              if se_lfield(spec, ls, lee, 2, kb, 8) != 1 { return 0 - 2 }
              let kc: i64 = kb[0] as i64
              let prompt: *u8 = sys_mmap(512)
              let opts: *u8 = sys_mmap(SE_MAGIC_1024)
              opts[0] = 0 as u8
              var lo: i64 = 0
              var hi: i64 = 0
              if kc == 67 {   // C|prompt|opt1|opt2...
                  if se_lfield(spec, ls, lee, 3, prompt, 512) <= 0 { return 0 - 2 }
                  // options = fields 4.. joined back with '|'
                  let ob: *u8 = sys_mmap(64)
                  var k: i64 = 4
                  var oo: i64 = 0
                  var more: i64 = 1
                  while more == 1 {
                      let fl: i64 = se_lfield(spec, ls, lee, k, ob, 64)
                      if fl < 0 { more = 0 } else {
                          if fl == 0 { more = 0 } else {
                              if k - 4 >= SE_MAXOPT { return 0 - 2 }
                              if oo > 0 { oo = se_catc(opts, oo, 124) }
                              oo = se_cat(opts, oo, ob)
                              k = k + 1
                          }
                      }
                  }
                  opts[oo] = 0 as u8
                  let no: i64 = se_nopts(opts)
                  if no < 2 { return 0 - 2 }
                  if no > SE_MAXOPT { return 0 - 2 }
              } else { if kc == 83 {   // S|min|max|prompt
                  if se_lfield(spec, ls, lee, 3, fb, 512) <= 0 { return 0 - 2 }
                  if se_digits(fb) == 0 { return 0 - 2 }
                  lo = sv_atoi(fb)
                  if se_lfield(spec, ls, lee, 4, fb, 512) <= 0 { return 0 - 2 }
                  if se_digits(fb) == 0 { return 0 - 2 }
                  hi = sv_atoi(fb)
                  if hi <= lo { return 0 - 2 }
                  if hi - lo > 20 { return 0 - 2 }
                  if se_lfield(spec, ls, lee, 5, prompt, 512) <= 0 { return 0 - 2 }
              } else { if kc == 84 {   // T|prompt
                  if se_lfield(spec, ls, lee, 3, prompt, 512) <= 0 { return 0 - 2 }
              } else { return 0 - 2 } } }
              qkind[nq] = kc
              qidp[nq] = qid as i64
              qprompt[nq] = prompt as i64
              qopts[nq] = opts as i64
              qmin[nq] = lo
              qmax[nq] = hi
              nq = nq + 1
          } } } } } } } } } }
      }
      ls = le + 1
  }
  if se_id_ok(id) == 0 { return 0 - 1 }
  if nq < 1 { return 0 - 5 }
  if title[0] == (0 as u8) { var to: i64 = se_cat(title, 0, id); title[to] = 0 as u8 }
  // ---- commit: svy meta + one qst record per question, ONE segment ----
  let now: i64 = sys_now_us()
  let nowb: *u8 = sys_mmap(32)
  se_catn(nowb, 0, now)
  let anonb: *u8 = sys_mmap(8)
  se_catn(anonb, 0, anon)
  let kminb: *u8 = sys_mmap(16)
  se_catn(kminb, 0, kmin)
  let mtb: *u8 = sys_mmap(16)
  se_catn(mtb, 0, maxtext)
  let quotab: *u8 = sys_mmap(16)
  se_catn(quotab, 0, quota)
  let nqb: *u8 = sys_mmap(16)
  se_catn(nqb, 0, nq)
  let ks: *i64 = sys_mmap(8 * 20) as *i64
  let vs: *i64 = sys_mmap(8 * 20) as *i64
  var nf: i64 = 0
  ks[nf] = "type" as *u8 as i64;     vs[nf] = "svy" as *u8 as i64;      nf = nf + 1
  ks[nf] = "id" as *u8 as i64;       vs[nf] = id as i64;                nf = nf + 1
  ks[nf] = "title" as *u8 as i64;    vs[nf] = title as i64;             nf = nf + 1
  ks[nf] = "anon" as *u8 as i64;     vs[nf] = anonb as i64;             nf = nf + 1
  ks[nf] = "kmin" as *u8 as i64;     vs[nf] = kminb as i64;             nf = nf + 1
  ks[nf] = "maxtext" as *u8 as i64;  vs[nf] = mtb as i64;               nf = nf + 1
  ks[nf] = "quota" as *u8 as i64;    vs[nf] = quotab as i64;            nf = nf + 1
  ks[nf] = "audience" as *u8 as i64; vs[nf] = audience as i64;          nf = nf + 1
  ks[nf] = "results" as *u8 as i64;  vs[nf] = results as i64;           nf = nf + 1
  ks[nf] = "status" as *u8 as i64;   vs[nf] = "open" as *u8 as i64;     nf = nf + 1
  ks[nf] = "nq" as *u8 as i64;       vs[nf] = nqb as i64;               nf = nf + 1
  ks[nf] = "checks" as *u8 as i64;   vs[nf] = checks as i64;            nf = nf + 1
  ks[nf] = "usec" as *u8 as i64;     vs[nf] = nowb as i64;              nf = nf + 1
  let rec: *u8 = sys_mmap(SE_MAGIC_16384)
  let rl: i64 = canon_encode(ks, vs, nf, rec)
  let w: *i64 = ss_begin()
  let key: *u8 = sys_mmap(128)
  se_key_svy(id, key)
  if ss_add(w, 1, key, rec, rl) != 0 { return 0 - 4 }
  var qi: i64 = 0
  while qi < nq {
      let kb2: *u8 = sys_mmap(8)
      kb2[0] = qkind[qi] as u8
      kb2[1] = 0 as u8
      let lob: *u8 = sys_mmap(16)
      se_catn(lob, 0, qmin[qi])
      let hib: *u8 = sys_mmap(16)
      se_catn(hib, 0, qmax[qi])
      let ixb: *u8 = sys_mmap(16)
      se_catn(ixb, 0, qi + 1)
      let ks2: *i64 = sys_mmap(8 * 16) as *i64
      let vs2: *i64 = sys_mmap(8 * 16) as *i64
      var nf2: i64 = 0
      ks2[nf2] = "type" as *u8 as i64;   vs2[nf2] = "svyq" as *u8 as i64;  nf2 = nf2 + 1
      ks2[nf2] = "survey" as *u8 as i64; vs2[nf2] = id as i64;             nf2 = nf2 + 1
      ks2[nf2] = "qid" as *u8 as i64;    vs2[nf2] = qidp[qi];              nf2 = nf2 + 1
      ks2[nf2] = "kind" as *u8 as i64;   vs2[nf2] = kb2 as i64;            nf2 = nf2 + 1
      ks2[nf2] = "prompt" as *u8 as i64; vs2[nf2] = qprompt[qi];           nf2 = nf2 + 1
      ks2[nf2] = "opts" as *u8 as i64;   vs2[nf2] = qopts[qi];             nf2 = nf2 + 1
      ks2[nf2] = "min" as *u8 as i64;    vs2[nf2] = lob as i64;            nf2 = nf2 + 1
      ks2[nf2] = "max" as *u8 as i64;    vs2[nf2] = hib as i64;            nf2 = nf2 + 1
      ks2[nf2] = "idx" as *u8 as i64;    vs2[nf2] = ixb as i64;            nf2 = nf2 + 1
      let rec2: *u8 = sys_mmap(SE_MAGIC_16384)
      let rl2: i64 = canon_encode(ks2, vs2, nf2, rec2)
      let key2: *u8 = sys_mmap(128)
      se_key_qst(id, qi + 1, key2)
      if ss_add(w, 1, key2, rec2, rl2) != 0 { return 0 - 4 }
      qi = qi + 1
  }
  if ss_commit(prefix, w, now) != 0 { return 0 - 4 }
  var io: i64 = 0
  while id[io] != (0 as u8) { if io < idcap - 1 { idout[io] = id[io] } io = io + 1 }
  if io > idcap - 1 { io = idcap - 1 }
  idout[io] = 0 as u8
  return nq
478}
479
480// CLOSE a survey: re-state the meta record with status=closed (new version, same key -- history kept).
481// Returns 0, or -1 when the survey does not exist.
482func se_close(prefix: *u8, id: *u8) -> i64 {
  let ks: *i64 = sys_mmap(8 * 32) as *i64
  let vs: *i64 = sys_mmap(8 * 32) as *i64
  let nf: i64 = se_meta(prefix, id, ks, vs, 32)
  if nf < 0 { return 0 - 1 }
  let nowb: *u8 = sys_mmap(32)
  se_catn(nowb, 0, sys_now_us())
  var i: i64 = 0
  while i < nf {
      let k: *u8 = ks[i] as *u8
      if se_seq(k, "status" as *u8) == 1 { vs[i] = "closed" as *u8 as i64 }
      if se_seq(k, "usec" as *u8) == 1 { vs[i] = nowb as i64 }
      i = i + 1
  }
  let rec: *u8 = sys_mmap(SE_MAGIC_16384)
  let rl: i64 = canon_encode(ks, vs, nf, rec)
  let w: *i64 = ss_begin()
  let key: *u8 = sys_mmap(128)
  se_key_svy(id, key)
  if ss_add(w, 1, key, rec, rl) != 0 { return 0 - 2 }
  if ss_commit(prefix, w, sys_now_us()) != 0 { return 0 - 2 }
  return 0
504}
505
506// RESPOND: validate against the survey's own question records, then commit ONE ballot record keyed
507// "rsp:<id>:<tok>" (a revote re-states the key -> latest wins, count never inflates, history additive).
508// aq/av = parallel arrays of answered qid ptrs / decoded value-string ptrs.
509// Returns 1 recorded; -1 no such survey; -2 closed; -3 missing/invalid answer; -4 store fail;
510// -5 bad token; -6 an answered qid is not in the survey; -7 bad id; -8 quota reached (poll full).
511func se_respond(prefix: *u8, id: *u8, tok: *u8, aq: *i64, av: *i64, na: i64) -> i64 {
  if se_id_ok(id) == 0 { return 0 - 7 }
  if se_tok_ok(tok) == 0 { return 0 - 5 }
  let mks: *i64 = sys_mmap(8 * 32) as *i64
  let mvs: *i64 = sys_mmap(8 * 32) as *i64
  let mnf: i64 = se_meta(prefix, id, mks, mvs, 32)
  if mnf < 0 { return 0 - 1 }
  let st: *u8 = sv_get(mks, mvs, mnf, "status" as *u8)
  if (st as i64) == 0 { return 0 - 1 }
  if se_seq(st, "open" as *u8) == 0 { return 0 - 2 }
  let nq: i64 = se_field_n(mks, mvs, mnf, "nq" as *u8, 0)
  let maxtext: i64 = se_field_n(mks, mvs, mnf, "maxtext" as *u8, SE_DEF_MAXTEXT)
  if nq < 1 { return 0 - 1 }
  // quota gate: cap DISTINCT respondents. A revote (this token already has a ballot) is exempt --
  // it re-states one key, never inflating the tally. Only a NEW token past the cap is refused (-8).
  // se_ballots returning -1 means the effective count overflowed a quota-sized buffer, i.e. we are
  // already AT/OVER quota -> fail closed (refuse the new respondent), never silently admit.
  let quota: i64 = se_field_n(mks, mvs, mnf, "quota" as *u8, 0)
  if quota > 0 {
      let rk: *u8 = sys_mmap(160)
      se_key_rsp(id, tok, rk)
      let tks: *i64 = sys_mmap(8 * 40) as *i64
      let tvs: *i64 = sys_mmap(8 * 40) as *i64
      let existing: i64 = se_get_dec(prefix, rk, tks, tvs, 40)
      if existing < 0 {
          let qcap: i64 = quota + 16
          let bk: *i64 = sys_mmap(8 * qcap) as *i64
          let bv: *i64 = sys_mmap(8 * qcap) as *i64
          let bl: *i64 = sys_mmap(8 * qcap) as *i64
          let nb: i64 = se_ballots(prefix, id, bk, bv, bl, qcap)
          if nb < 0 { return 0 - 8 }
          if nb >= quota { return 0 - 8 }
      }
  }
  // every answered qid must belong to the survey; every C/S question must be answered validly
  let seen: *i64 = sys_mmap(8 * (na + 4)) as *i64
  var si: i64 = 0
  while si < na { seen[si] = 0; si = si + 1 }
  var q: i64 = 1
  while q <= nq {
      let qks: *i64 = sys_mmap(8 * 32) as *i64
      let qvs: *i64 = sys_mmap(8 * 32) as *i64
      let qnf: i64 = se_qst(prefix, id, q, qks, qvs, 32)
      if qnf < 0 { return 0 - 1 }
      let qid: *u8 = sv_get(qks, qvs, qnf, "qid" as *u8)
      let kind: *u8 = sv_get(qks, qvs, qnf, "kind" as *u8)
      if (qid as i64) == 0 { return 0 - 1 }
      if (kind as i64) == 0 { return 0 - 1 }
      let kc: i64 = kind[0] as i64
      // find the answer for this qid
      var vp: *u8 = 0 as *u8
      var ai: i64 = 0
      while ai < na {
          if se_seq(aq[ai] as *u8, qid) == 1 { vp = av[ai] as *u8; seen[ai] = 1; ai = na } else { ai = ai + 1 }
      }
      if kc == 67 {
          if (vp as i64) == 0 { return 0 - 3 }
          if se_digits(vp) == 0 { return 0 - 3 }
          let v: i64 = sv_atoi(vp)
          let opts: *u8 = sv_get(qks, qvs, qnf, "opts" as *u8)
          if (opts as i64) == 0 { return 0 - 3 }
          if v < 0 { return 0 - 3 }
          if v >= se_nopts(opts) { return 0 - 3 }
      } else { if kc == 83 {
          if (vp as i64) == 0 { return 0 - 3 }
          if se_digits(vp) == 0 { return 0 - 3 }
          let v: i64 = sv_atoi(vp)
          let lo: i64 = se_field_n(qks, qvs, qnf, "min" as *u8, 0)
          let hi: i64 = se_field_n(qks, qvs, qnf, "max" as *u8, 10)
          if v < lo { return 0 - 3 }
          if v > hi { return 0 - 3 }
      } else {
          // T: optional, but when present must respect maxtext
          if (vp as i64) != 0 { if se_slen(vp) > maxtext { return 0 - 3 } }
      } }
      q = q + 1
  }
  // any answered qid that never matched a question -> refuse (fail-closed boundary)
  si = 0
  while si < na {
      if seen[si] == 0 { return 0 - 6 }
      si = si + 1
  }
  // build the ballot record
  let nowb: *u8 = sys_mmap(32)
  se_catn(nowb, 0, sys_now_us())
  let ks: *i64 = sys_mmap(8 * (na + 8)) as *i64
  let vs: *i64 = sys_mmap(8 * (na + 8)) as *i64
  var nf: i64 = 0
  ks[nf] = "type" as *u8 as i64;   vs[nf] = "rsp" as *u8 as i64; nf = nf + 1
  ks[nf] = "survey" as *u8 as i64; vs[nf] = id as i64;           nf = nf + 1
  ks[nf] = "resp" as *u8 as i64;   vs[nf] = tok as i64;          nf = nf + 1
  ks[nf] = "usec" as *u8 as i64;   vs[nf] = nowb as i64;         nf = nf + 1
  var ai2: i64 = 0
  while ai2 < na {
      let fk: *u8 = sys_mmap(40)
      var fo: i64 = se_cat(fk, 0, "a_" as *u8)
      fo = se_cat(fk, fo, aq[ai2] as *u8)
      fk[fo] = 0 as u8
      ks[nf] = fk as i64
      vs[nf] = av[ai2]
      nf = nf + 1
      ai2 = ai2 + 1
  }
  let rec: *u8 = sys_mmap(SE_MAGIC_65536)
  let rl: i64 = canon_encode(ks, vs, nf, rec)
  let w: *i64 = ss_begin()
  let key: *u8 = sys_mmap(160)
  se_key_rsp(id, tok, key)
  if ss_add(w, 1, key, rec, rl) != 0 { return 0 - 4 }
  if ss_commit(prefix, w, sys_now_us()) != 0 { return 0 - 4 }
  return 1
623}
624
625// walk the WHOLE store; for every key starting with keypfx keep the LATEST version (chronological
626// replace = the store's own last-wins semantics; tombstone clears). kout/vout/lout sized cap.
627// Returns unique-key count, or LOUD -1 when the manifest or the key table hits its bound
628// (never a silently-partial tally -- compaction is the named rung past the bound).
629func se_walk_latest(prefix: *u8, keypfx: *u8, kout: *i64, vout: *i64, lout: *i64, cap: i64) -> i64 {
  // CACHED HANDLE (2026-08-19): the handle ALREADY holds every segment's .docs mapped
  // (h[3+8s]/h[4+8s], manifest order = chronological, so the last-wins walk below is
  // byte-identical) -- re-readall-ing fresh copies of the whole store per tally was the walk's
  // share of the daemon's measured creep. vout pointers alias the CACHED mapping, which lives
  // until the store's next generation; every caller renders within the same request, and the
  // daemon reaps superseded handles only at its accept-loop top, so no pointer outlives its bytes.
  if cap > SE_WALK_CAPMAX { return 0 - 1 }   // slot sized once; overrun would corrupt, refusal diagnoses
  let h9: *i64 = ss_open_cached(prefix)
  if (h9 as i64) == 0 { return 0 - 1 }
  let ns: i64 = h9[0]
  var hts: i64 = 16
  while hts < SE_WALK_CAPMAX * 2 { hts = hts * 2 }
  // RING SLOT (see the SE_WALK_* block above): static storage, rotated per call.
  let poolsz: i64 = SE_WALK_CAPMAX * SE_WALK_KEYB + SE_MAGIC_4096
  if (se_wk_pool_g as i64) == 0 {
      se_wk_pool_g = sys_mmap(SE_WALK_RING * poolsz)
      se_wk_ht_g = sys_mmap(SE_WALK_RING * 8 * hts) as *i64
      se_wk_kb_g = sys_mmap(SE_WALK_RING * SE_WALK_KBSCR)
  }
  let slot: i64 = se_wk_slot_g % SE_WALK_RING
  se_wk_slot_g = se_wk_slot_g + 1
  let ht: *i64 = ((se_wk_ht_g as i64) + slot * 8 * hts) as *i64
  let pool: *u8 = ((se_wk_pool_g as i64) + slot * poolsz) as *u8
  let kb: *u8 = ((se_wk_kb_g as i64) + slot * SE_WALK_KBSCR) as *u8
  // the slot is REUSED, so clear the hash table (the pool needs no clear: entries are re-written)
  var hz: i64 = 0
  while hz < hts { ht[hz] = 0; hz = hz + 1 }
  var pooloff: i64 = 0
  let pfl: i64 = se_slen(keypfx)
  var cnt: i64 = 0
  var s: i64 = 0
  while s < ns {
      let b: *u8 = h9[3 + 8 * s] as *u8
      let sz: i64 = h9[4 + 8 * s]
      var i: i64 = 0
      while i + 9 <= sz {
          let kind: i64 = b[i] as i64
          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
          // prefix match on the raw key bytes
          var pm: i64 = 1
          if kl < pfl { pm = 0 }
          var t: i64 = 0
          while t < pfl { if pm == 1 { if b[koff + t] != keypfx[t] { pm = 0 } } t = t + 1 }
          if pm == 1 { if kl < 150 {
              // null-terminated key copy in the hoisted scratch for hashing/compare
              var x: i64 = 0
              while x < kl { kb[x] = b[koff + x]; x = x + 1 }
              kb[kl] = 0 as u8
              var slot: i64 = ss_fnv(kb) % hts
              var idx: i64 = 0 - 1
              var probe: i64 = 1
              while probe == 1 {
                  if ht[slot] == 0 { probe = 0 } else {
                      let cand: i64 = ht[slot] - 1
                      if se_seq(kout[cand] as *u8, kb) == 1 { idx = cand; probe = 0 } else {
                          slot = slot + 1
                          if slot >= hts { slot = 0 }
                      }
                  }
              }
              if idx < 0 {
                  if cnt >= cap { return 0 - 1 }
                  let kp: *u8 = (pool as i64 + pooloff) as *u8
                  var x2: i64 = 0
                  while x2 <= kl { kp[x2] = kb[x2]; x2 = x2 + 1 }
                  pooloff = pooloff + kl + 1
                  kout[cnt] = kp as i64
                  idx = cnt
                  cnt = cnt + 1
                  ht[slot] = idx + 1
              }
              if kind == 2 { vout[idx] = 0; lout[idx] = 0 } else {
                  vout[idx] = (b as i64) + voff
                  lout[idx] = vl
              }
          } }
          i = voff + vl
      }
      s = s + 1
  }
  return cnt
714}
715
716// effective ballots of a survey (latest per respondent, tombstones excluded).
717// Returns count or LOUD -1 (walk bound).
718func se_ballots(prefix: *u8, id: *u8, kout: *i64, vout: *i64, lout: *i64, cap: i64) -> i64 {
  let pfx: *u8 = sys_mmap(96)
  var o: i64 = se_cat(pfx, 0, "rsp:" as *u8)
  o = se_cat(pfx, o, id)
  o = se_catc(pfx, o, 58)
  pfx[o] = 0 as u8
  let n: i64 = se_walk_latest(prefix, pfx, kout, vout, lout, cap)
  if n < 0 { return 0 - 1 }
  // squeeze out tombstoned slots
  var m: i64 = 0
  var i: i64 = 0
  while i < n {
      if vout[i] != 0 {
          kout[m] = kout[i]
          vout[m] = vout[i]
          lout[m] = lout[i]
          m = m + 1
      }
      i = i + 1
  }
  return m
739}
740
741// decode ballot #i's answer to qid into out (empty when absent). returns len (0 when absent) or -1 malformed.
742func se_answer_of(vp: *u8, vl: i64, qid: *u8, out: *u8, cap: i64) -> i64 {
  let ks: *i64 = sys_mmap(8 * 40) as *i64
  let vs: *i64 = sys_mmap(8 * 40) as *i64
  let nf: i64 = canon_decode(vp, vl, ks, vs, 40)
  if nf < 0 { return 0 - 1 }
  let fk: *u8 = sys_mmap(40)
  var fo: i64 = se_cat(fk, 0, "a_" as *u8)
  fo = se_cat(fk, fo, qid)
  fk[fo] = 0 as u8
  let v: *u8 = sv_get(ks, vs, nf, fk)
  if (v as i64) == 0 { out[0] = 0 as u8; return 0 }
  var i: i64 = 0
  while v[i] != (0 as u8) { if i < cap - 1 { out[i] = v[i] } i = i + 1 }
  if i > cap - 1 { i = cap - 1 }
  out[i] = 0 as u8
  return i
758}
759// count effective ballots whose answer to qid equals `want` exactly
760func se_count_eq(vout: *i64, lout: *i64, nb: i64, qid: *u8, want: *u8) -> i64 {
  let ab: *u8 = sys_mmap(SE_MAGIC_4096)
  var c: i64 = 0
  var i: i64 = 0
  while i < nb {
      if se_answer_of(vout[i] as *u8, lout[i], qid, ab, SE_MAGIC_4096) > 0 {
          if se_seq(ab, want) == 1 { c = c + 1 }
      }
      i = i + 1
  }
  return c
771}
772// numeric stats for a scale question: outs[0]=n outs[1]=sum. returns n.
773func se_num_stats(vout: *i64, lout: *i64, nb: i64, qid: *u8, outs: *i64) -> i64 {
  let ab: *u8 = sys_mmap(64)
  var n: i64 = 0
  var sum: i64 = 0
  var i: i64 = 0
  while i < nb {
      if se_answer_of(vout[i] as *u8, lout[i], qid, ab, 64) > 0 {
          if se_digits(ab) == 1 {
              n = n + 1
              sum = sum + sv_atoi(ab)
          }
      }
      i = i + 1
  }
  outs[0] = n
  outs[1] = sum
  return n
790}
791// count ballots with a nonempty text answer for qid
792func se_text_count(vout: *i64, lout: *i64, nb: i64, qid: *u8) -> i64 {
  let ab: *u8 = sys_mmap(SE_MAGIC_4096)
  var c: i64 = 0
  var i: i64 = 0
  while i < nb {
      if se_answer_of(vout[i] as *u8, lout[i], qid, ab, SE_MAGIC_4096) > 0 { c = c + 1 }
      i = i + 1
  }
  return c
801}
802// list surveys: latest svy: record per id. kout=key ptrs ("svy:<id>"), vout/lout = record bytes.
803func se_surveys(prefix: *u8, kout: *i64, vout: *i64, lout: *i64, cap: i64) -> i64 {
  let n: i64 = se_walk_latest(prefix, "svy:" as *u8, kout, vout, lout, cap)
  if n < 0 { return 0 - 1 }
  var m: i64 = 0
  var i: i64 = 0
  while i < n {
      if vout[i] != 0 {
          kout[m] = kout[i]
          vout[m] = vout[i]
          lout[m] = lout[i]
          m = m + 1
      }
      i = i + 1
  }
  return m
818}
nx_survey_engine.nx source

`nx_survey_engine.nx` source
