code wiki / _hdl_build / nx_toolflags.nx
`nx_toolflags.nx` source

↩ module page · 358 lines · 18485 B
1// nx_toolflags.nx -- SAFETY-FLAG DERIVER (2026-08-06). Emits knowledge/tool_flags.conf so tools/list can
2// stop publishing a FABRICATED safety profile for tools whose flags were never looked up.
3//
4// THE DEFECT, MEASURED on the live tools/list: 694 of 869 tools (79.9%) carry the identical quad
5// ro=0 destr=1 idem=0 open=1. That is not a measurement -- it is a hardcoded constant written by
6// ma_schema_append_row at registration time. It does not merely omit, it LIES: nx_pm_board, a READ-ONLY
7// dashboard, is published destructiveHint=true, so an agent that honours annotations refuses a safe read.
8// (The constant errs CONSERVATIVE, so this is an INFORMATION defect, not an unsafe one -- but a fabricated
9// value ends the enquiry where a blank would have invited a lookup.)
10//
11// MATCHES THE KNOWN GOOD: the marker sets and the conservatism below are nx_schema_backfill's
12// sb_derive_flags (shipped 2026-08-06) COPIED DELIBERATELY, not reinvented -- same syscalls, same
13// "DESTRUCTIVE is narrower than writes" split, same refusal to claim `idempotent` (nothing in the source
14// declares it, so it stays 0, the conservative direction). Two consumers is not yet a shared lib (rule 15
15// says three); if a third appears, extract sb_derive_flags to a lib and delete this copy.
16//
17// THE TWEAK, AND WHY IT IS A SAFETY FIX: sb_derive_flags scans ONE FILE. An organ that writes through an
18// imported helper reaches sys_openat_wr in the LIB, not in its own source, so a single-file scan calls it
19// READ-ONLY -- wrong in the UNSAFE direction. This organ scans the organ's own source AND one level of its
20// `import "x.nx"` closure, and REPORTS `depth0_readonly` vs `depth1_readonly`: the difference IS the count
21// of tools the single-file scan would have mislabelled read-only. The number is published either way, so
22// the tweak can never be claimed without evidence.
23//
24// HONEST: no source, or a read that FILLED the buffer (so a marker past the cap may have been missed),
25// => NOT DERIVED, conservative default kept, and COUNTED. Blank beats bad.
26//   nx_toolflags        -> writes knowledge/tool_flags.conf, prints a JSON census on stdout
27// license_tier: ORIGINAL   No hw writes (Rule 26).   expect_exit: 0
28import "nx_mgmt_api.nx"
29import "nx_syscalls.nx"
30
31const TF_ALCAP: i64 = 1 << 18
32const TF_SRCCAP: i64 = 262144
33const TF_NAMECAP: i64 = 128
34const TF_PATHCAP: i64 = 512
35// declared: at most this many imports per organ are followed (one level, no recursion)
36const TF_MAXIMP: i64 = 32
37const TF_OUT: *u8 = "knowledge/tool_flags.conf" as *u8
38
39static TF_D0RO: i64 = 0
40static TF_D1RO: i64 = 0
41
42func tfw(s: *u8) -> i64 { var n: i64 = 0; while s[n] != (0 as u8) { n = n + 1 } sys_write(1, s, n); return 0 }
43func tfn(v: i64) -> i64 {
  let b: *u8 = sys_mmap(32)
  var x: i64 = v
  var i: i64 = 31
  if x == 0 { b[i] = 48 as u8; i = i - 1 }
  while x > 0 { b[i] = ((48 + (x - ((x / 10) * 10))) as u8); x = x / 10; i = i - 1 }
  sys_write(1, ((b as i64) + i + 1) as *u8, 31 - i)
  return 0
51}
52func tf_ends(s: *u8, sl: i64, suf: *u8, fl: i64) -> i64 {
  if sl < fl { return 0 }
  var i: i64 = 0
  while i < fl { if s[sl-fl+i] != suf[i] { return 0 } i = i + 1 }
  return 1
57}
58// A CALL, not a DEFINITION. This distinction is the whole ballgame for the import closure: EVERY organ
59// imports nx_syscalls.nx, which DEFINES `func sys_openat_wr(...)`, `func sys_unlink...` and the rest. A
60// naive substring scan therefore marks the entire estate a writer the moment imports are folded in --
61// MEASURED: depth-1 read-only collapsed to 114 of 844 and the derived quad converged right back onto the
62// cautious constant it was supposed to replace, so the derivation bought nothing.
63// â˜… A DEFINITION AND A CALL ARE THE SAME BYTES; ONLY THEIR LEFT CONTEXT TELLS THEM APART.
64// Occurrences immediately preceded by "func " are declarations and are SKIPPED. No filename is special-
65// cased -- the rule is structural, so it holds for any future syscall-shim library too.
66func tf_has(buf: *u8, n: i64, needle: *u8) -> i64 {
  var m: i64 = 0
  while needle[m] != (0 as u8) { m = m + 1 }
  if m == 0 { return 0 }
  var i: i64 = 0
  while i + m <= n {
      var j: i64 = 0
      var hit: i64 = 1
      while j < m { if buf[i+j] != needle[j] { hit = 0; j = m } else { j = j + 1 } }
      if hit == 1 {
          var pfx: i64 = 0
          if i >= 5 {
              if (buf[i-5] as i64) == 102 { pfx = pfx + 1 }
              if (buf[i-4] as i64) == 117 { pfx = pfx + 1 }
              if (buf[i-3] as i64) == 110 { pfx = pfx + 1 }
              if (buf[i-2] as i64) == 99 { pfx = pfx + 1 }
              if (buf[i-1] as i64) == 32 { pfx = pfx + 1 }
          }
          if pfx < 5 { return 1 }
      }
      i = i + 1
  }
  return 0
89}
90func tf_wflag(fd: i64, v: i64) -> i64 { if v == 1 { ma_write_str(fd, "1" as *u8) } else { ma_write_str(fd, "0" as *u8) } return 0 }
91
92// Scan ONE file's bytes for the marker sets. box[0]=writes box[1]=destr box[2]=net ; returns 1 scanned
93// conclusively, 0 = unreadable or buffer-filled (inconclusive -> caller must NOT claim derived).
94// STRIP // COMMENTS BEFORE SCANNING (2026-08-07). THE precision defect, diagnosed from ONE concrete
95// case rather than guessed at: nx_capsearch only READS two confs and writes stdout, yet came out ro=0.
96// Its ONLY import is nx_syscalls.nx -- and EVERY write/destructive/network marker in that file sits
97// inside a COMMENT ("sys_mkdir / sys_renameat are not baked...", "sys_unlinkat ... REFERENCE it",
98// "Socket-option constants used by nx_http_server / nx_https_server"). Essentially every organ imports
99// the syscall shim, so the depth-1 closure was inheriting "writer" FROM PROSE. That is also why making
100// the scan definition-aware moved read-only by exactly ZERO: those occurrences were never definitions,
101// they were commentary.
102// ★★★★★★ A SCANNER THAT DOES NOT SKIP COMMENTS MEASURES THE DOCUMENTATION, NOT THE CODE.
103// Declared limitation, deliberately not fixed here: a marker inside a STRING LITERAL still counts. That
104// is rare and errs conservative (over-warns); comments were both common and systematic.
105func tf_strip_comments(src: *u8, n: i64, out: *u8) -> i64 {
  var o: i64 = 0
  var i: i64 = 0
  var incmt: i64 = 0
  while i < n {
      let c: i64 = src[i] as i64
      if incmt == 1 {
          if c == 10 { incmt = 0; out[o] = 10 as u8; o = o + 1 }
      } else {
          var starts: i64 = 0
          if c == 47 { if i + 1 < n { if src[i+1] == (47 as u8) { starts = 1 } } }
          if starts == 1 { incmt = 1; i = i + 1 } else { out[o] = src[i]; o = o + 1 }
      }
      i = i + 1
  }
  return o
121}
122
123func tf_scan_one(path: *u8, box: *i64) -> i64 {
  let fd: i64 = sys_openat_rd(path)
  if fd < 0 { return 0 }
  let raw: *u8 = sys_mmap(TF_SRCCAP)
  let rn: i64 = sys_read(fd, raw, TF_SRCCAP - 1)
  sys_close(fd)
  if rn <= 0 { return 0 }
  if rn >= TF_SRCCAP - 1 { return 0 }
  let sb: *u8 = sys_mmap(TF_SRCCAP)
  let sn: i64 = tf_strip_comments(raw, rn, sb)
  if tf_has(sb, sn, "sys_openat_wr" as *u8) == 1 { box[0] = 1 }
  if tf_has(sb, sn, "sys_openat_append" as *u8) == 1 { box[0] = 1 }
  if tf_has(sb, sn, "sys_mkdir" as *u8) == 1 { box[0] = 1 }
  if tf_has(sb, sn, "sts_put" as *u8) == 1 { box[0] = 1 }
  if tf_has(sb, sn, "ss_append" as *u8) == 1 { box[0] = 1 }
  // DESTRUCTIVE is NARROWER than "writes": appending a row is not unlinking a file.
  if tf_has(sb, sn, "sys_unlink" as *u8) == 1 { box[1] = 1 }
  if tf_has(sb, sn, "sys_rename" as *u8) == 1 { box[1] = 1 }
  if tf_has(sb, sn, "sys_rmdir" as *u8) == 1 { box[1] = 1 }
  if tf_has(sb, sn, "sys_ftruncate" as *u8) == 1 { box[1] = 1 }
  if tf_has(sb, sn, "sys_socket" as *u8) == 1 { box[2] = 1 }
  if tf_has(sb, sn, "sys_connect" as *u8) == 1 { box[2] = 1 }
  if tf_has(sb, sn, "nx_https_" as *u8) == 1 { box[2] = 1 }
  if tf_has(sb, sn, "nx_tls" as *u8) == 1 { box[2] = 1 }
  if tf_has(sb, sn, "hf_fetch" as *u8) == 1 { box[2] = 1 }
  return 1
149}
150
151// Collect up to TF_MAXIMP `import "x.nx"` names from path into imps (TF_PATHCAP-strided). Returns count.
152func tf_imports(path: *u8, imps: *u8) -> i64 {
  let fd: i64 = sys_openat_rd(path)
  if fd < 0 { return 0 }
  let sb: *u8 = sys_mmap(TF_SRCCAP)
  let sn: i64 = sys_read(fd, sb, TF_SRCCAP - 1)
  sys_close(fd)
  if sn <= 0 { return 0 }
  var cnt: i64 = 0
  var i: i64 = 0
  while i + 8 < sn {
      var m: i64 = 1
      if sb[i] != (105 as u8) { m = 0 }
      if m == 1 { if sb[i+1] != (109 as u8) { m = 0 } }
      if m == 1 { if sb[i+2] != (112 as u8) { m = 0 } }
      if m == 1 { if sb[i+3] != (111 as u8) { m = 0 } }
      if m == 1 { if sb[i+4] != (114 as u8) { m = 0 } }
      if m == 1 { if sb[i+5] != (116 as u8) { m = 0 } }
      if m == 1 { if sb[i+6] != (32 as u8) { m = 0 } }
      if m == 1 { if sb[i+7] != (34 as u8) { m = 0 } }
      if m == 1 {
          var p: i64 = i + 8
          var o: i64 = 0
          var go: i64 = 1
          while go == 1 {
              if p >= sn { go = 0 } else {
                  if sb[p] == (34 as u8) { go = 0 } else {
                      if cnt < TF_MAXIMP { if o < TF_PATHCAP - 1 { imps[cnt*TF_PATHCAP + o] = sb[p]; o = o + 1 } }
                      p = p + 1
                  }
              }
          }
          if o > 0 { if cnt < TF_MAXIMP { imps[cnt*TF_PATHCAP + o] = 0 as u8; cnt = cnt + 1 } }
          i = p
      }
      i = i + 1
  }
  return cnt
189}
190
191// Resolve <stem>.nx under _hdl_build then runtime; 1 if a readable path landed in out.
192func tf_resolve(stem: *u8, stl: i64, out: *u8) -> i64 {
  var o: i64 = sd_cat(out, 0, "buildroot/runtime/_hdl_build/" as *u8)
  var c: i64 = 0
  while c < stl { out[o] = stem[c]; o = o + 1; c = c + 1 }
  out[o] = 0 as u8
  var fd: i64 = sys_openat_rd(out)
  if fd >= 0 { sys_close(fd); return 1 }
  o = sd_cat(out, 0, "buildroot/runtime/" as *u8)
  c = 0
  while c < stl { out[o] = stem[c]; o = o + 1; c = c + 1 }
  out[o] = 0 as u8
  fd = sys_openat_rd(out)
  if fd >= 0 { sys_close(fd); return 1 }
  return 0
206}
207
208func main() -> i64 {
  let al: *u8 = sys_mmap(TF_ALCAP)
  let fd: i64 = sys_openat_rd("tool_allowlist.conf" as *u8)
  if fd < 0 { tfw("{\"organ\":\"nx_toolflags\",\"refused\":\"tool_allowlist.conf unreadable\"}\n" as *u8); sys_exit(2); return 2 }
  let n: i64 = sys_read(fd, al, TF_ALCAP - 1)
  sys_close(fd)
  if n <= 0 { tfw("{\"organ\":\"nx_toolflags\",\"refused\":\"tool_allowlist.conf empty\"}\n" as *u8); sys_exit(2); return 2 }
  if n >= TF_ALCAP - 1 { tfw("{\"organ\":\"nx_toolflags\",\"refused\":\"allowlist read filled the buffer -- refusing a partial census\"}\n" as *u8); sys_exit(2); return 2 }
  al[n] = 0 as u8
217
  sys_unlinkat(TF_OUT)
  let of: i64 = sys_openat_append(TF_OUT, 420)
  if of < 0 { tfw("{\"organ\":\"nx_toolflags\",\"refused\":\"cannot create knowledge/tool_flags.conf\"}\n" as *u8); sys_exit(2); return 2 }
  ma_write_str(of, "# tool_flags.conf -- DERIVED MCP safety annotations, emitted by nx_toolflags from each organ's own\n" as *u8)
  ma_write_str(of, "# source AND one level of its import closure (a writer reached through a lib is NOT read-only).\n" as *u8)
  ma_write_str(of, "# Read by nx_tools_api ONLY for rows whose schema output-desc marks them registration-synthesized,\n" as *u8)
  ma_write_str(of, "# i.e. whose flags were the hardcoded constant and never a measurement. idempotent stays UNDECLARED.\n" as *u8)
  ma_write_str(of, "# TAB: <name>\\t<readOnly>\\t<destructive>\\t<idempotent>\\t<openWorld>\n" as *u8)
226
  var scanned: i64 = 0
  var derived: i64 = 0
  var nosrc: i64 = 0
  let nm: *u8 = sys_mmap(TF_NAMECAP)
  let elf: *u8 = sys_mmap(TF_PATHCAP)
  let pth: *u8 = sys_mmap(TF_PATHCAP)
  let ipth: *u8 = sys_mmap(TF_PATHCAP)
  let imps: *u8 = sys_mmap(TF_MAXIMP * TF_PATHCAP)
  let b0: *i64 = sys_mmap(64) as *i64
  let b1: *i64 = sys_mmap(64) as *i64
  var i: i64 = 0
  while i < n {
      var le: i64 = i
      var sc: i64 = 1
      while sc == 1 { if le >= n { sc = 0 } else { if al[le] == (10 as u8) { sc = 0 } else { le = le + 1 } } }
      var ok: i64 = 1
      if le <= i { ok = 0 }
      if ok == 1 { if al[i] == (35 as u8) { ok = 0 } }
      if ok == 1 {
          var nmn: i64 = 0
          var p: i64 = i
          var s2: i64 = 1
          while s2 == 1 {
              if p >= le { s2 = 0; ok = 0 } else {
                  if al[p] == (9 as u8) { s2 = 0 } else {
                      if nmn < TF_NAMECAP - 1 { nm[nmn] = al[p]; nmn = nmn + 1 }
                      p = p + 1
                  }
              }
          }
          nm[nmn] = 0 as u8
          var en: i64 = 0
          if ok == 1 {
              p = p + 1
              var s3: i64 = 1
              while s3 == 1 {
                  if p >= le { s3 = 0 } else {
                      if al[p] == (9 as u8) { s3 = 0 } else {
                          if en < TF_PATHCAP - 1 { elf[en] = al[p]; en = en + 1 }
                          p = p + 1
                      }
                  }
              }
          }
          elf[en] = 0 as u8
          if nmn == 0 { ok = 0 }
          if en == 0 { ok = 0 }
          if ok == 1 {
              scanned = scanned + 1
              var bs: i64 = 0
              var k: i64 = 0
              while elf[k] != (0 as u8) { if elf[k] == (47 as u8) { bs = k + 1 } k = k + 1 }
              var stl: i64 = k - bs
              let base: *u8 = ((elf as i64) + bs) as *u8
              if tf_ends(base, stl, ".sov.elf.new" as *u8, 12) == 1 { stl = stl - 12 } else {
                  if tf_ends(base, stl, ".elf.new" as *u8, 8) == 1 { stl = stl - 8 } else {
                      if tf_ends(base, stl, ".sov.elf" as *u8, 8) == 1 { stl = stl - 8 } else {
                          if tf_ends(base, stl, ".elf" as *u8, 4) == 1 { stl = stl - 4 } else {
                              if tf_ends(base, stl, ".new" as *u8, 4) == 1 { stl = stl - 4 }
                          }
                      }
                  }
              }
              let stem: *u8 = sys_mmap(TF_PATHCAP)
              var c3: i64 = 0
              while c3 < stl { stem[c3] = base[c3]; c3 = c3 + 1 }
              stem[stl] = 46 as u8
              stem[stl+1] = 110 as u8
              stem[stl+2] = 120 as u8
              stem[stl+3] = 0 as u8
              var got: i64 = 0
              if stl > 0 { got = tf_resolve(stem, stl + 3, pth) }
              if got == 0 { nosrc = nosrc + 1 } else {
                  b0[0] = 0; b0[1] = 0; b0[2] = 0
                  let conc: i64 = tf_scan_one(pth, b0)
                  if conc == 0 { nosrc = nosrc + 1 } else {
                      // depth-0 verdict (what the single-file known good would say)
                      var ro0: i64 = 0
                      if b0[0] == 0 { ro0 = 1 }
                      if ro0 == 1 { TF_D0RO = TF_D0RO + 1 }
                      // depth-1: fold in one level of the import closure
                      b1[0] = b0[0]; b1[1] = b0[1]; b1[2] = b0[2]
                      let nimp: i64 = tf_imports(pth, imps)
                      var q: i64 = 0
                      while q < nimp {
                          let iname: *u8 = ((imps as i64) + q * TF_PATHCAP) as *u8
                          var il: i64 = 0
                          while iname[il] != (0 as u8) { il = il + 1 }
                          if tf_resolve(iname, il, ipth) == 1 { tf_scan_one(ipth, b1) }
                          q = q + 1
                      }
                      var ro1: i64 = 0
                      if b1[0] == 0 { ro1 = 1 }
                      if ro1 == 1 { TF_D1RO = TF_D1RO + 1 }
                      // MIXED DEPTH, CHOSEN BY WHICH DIRECTION THE ERROR HURTS -- not by taste.
                      //   readOnly  <- DEPTH-1 (import closure). Claiming read-only wrongly is the UNSAFE
                      //     error: an agent calls a writer freely. Stay conservative even though it costs
                      //     information (measured: 522 -> 114 read-only).
                      //   destructive/openWorld <- DEPTH-0 (the organ's OWN source). Depth-1 marked nearly
                      //     everything destructive because fat libs (nx_mgmt_api.nx et al) contain unlink
                      //     somewhere and are imported for one unrelated helper -- that is the INFORMATION
                      //     destroyer, and it is exactly the fabricated-constant failure we came to fix:
                      //     a warning that fires on everything carries no signal. Under-warning here is
                      //     bounded because readOnly stays conservative, so a tool not marked read-only is
                      //     ALREADY "may write" -- destructive only adds "and may unlink/rename".
                      // â˜… PICK THE CONSERVATIVE SIDE PER FLAG, NOT PER SCAN: one depth for all four fields
                      //   forces a choice between a lie and a blindfold.
                      ma_write_str(of, nm)
                      ma_write_str(of, "\t" as *u8); tf_wflag(of, ro1)
                      ma_write_str(of, "\t" as *u8); tf_wflag(of, b0[1])
                      ma_write_str(of, "\t0" as *u8)
                      ma_write_str(of, "\t" as *u8); tf_wflag(of, b0[2])
                      ma_write_str(of, "\n" as *u8)
                      derived = derived + 1
                  }
              }
          }
      }
      i = le + 1
  }
  sys_close(of)
348
  tfw("{\"organ\":\"nx_toolflags\",\"out\":\"knowledge/tool_flags.conf\",\"scanned\":" as *u8); tfn(scanned)
  tfw(",\"derived\":" as *u8); tfn(derived)
  tfw(",\"skipped_inconclusive\":" as *u8); tfn(nosrc)
  tfw(",\"depth0_readonly\":" as *u8); tfn(TF_D0RO)
  tfw(",\"depth1_readonly\":" as *u8); tfn(TF_D1RO)
  tfw(",\"mislabelled_readonly_by_single_file_scan\":" as *u8); tfn(TF_D0RO - TF_D1RO)
  tfw(",\"note\":\"depth1 folds one level of the import closure: the difference IS the count the known-good single-file scan would have called read-only in the UNSAFE direction. idempotent is UNDECLARED (0), never guessed.\"}\n" as *u8)
  sys_exit(0)
  return 0
358}
nx_toolflags.nx source

`nx_toolflags.nx` source
