`nx_readmany.nx` source

↩ module page · 318 lines · 14097 B
1// nx_readmany.nx -- ONE CALL, N FILES (Lane I common-task hardening, 2026-08-20).
2// MINED, NOT GUESSED. nx_wfcost measured the full 309-transcript / 2,006,669,677 B action record and
3// the read cluster is the largest BUILD candidate in it: nx_fs:read >> nx_fs:read 5,675 episodes,
4// nx_shelltool:grep >> nx_fs:read 1,683, nx_fs:lines >> nx_fs:lines 1,233, nx_fs:lines >> nx_fs_write:edit
5// 904 -- ~9,495 consecutive-read episodes, each one a seat turn spent re-issuing the same verb.
6// (The larger mgmt:POST cluster is deliberately NOT addressed here: nx_organ_ship already collapses it,
7// so that one is an ADOPTION gap, not a build gap -- building a second would be the duplicate ruler.)
8//
9// WHY A BATCH READ AND NOT A BIGGER CAP: the measured unit is the SEAT TURN (1 turn ~= 133,658
10// input-token-equivalents, measured, not estimated). N reads cost N turns regardless of how many bytes
11// each returns, so the win comes from collapsing TURNS, never from raising a limit.
12//
13// TWO LAWS THIS ORGAN EXISTS TO NOT BREAK:
14//  1. THE ENVELOPE IS PER ITEM, NEVER GLOBAL. A single global "truncated=1" cannot say WHICH file was
15//     cut, so the caller re-reads all of them and the batch saves nothing. Every item carries its own
16//     status + bytes= + of= (its TRUE full size, always known because the read is sized from the file).
17//     This lane already found `nx_actlog harden` computing a truncation envelope and then dropping it
18//     at the next hop -- an envelope dropped at the next hop is an envelope that was never published.
19//  2. ONE BAD TARGET MUST NOT POISON THE BATCH. Every item gets its own third state
20//     (OK | EMPTY | ABSENT | UNREADABLE | BUDGET-EXHAUSTED), so an absent path costs exactly one row
21//     and the other N-1 files still come back. A batch that fails whole is worse than N single reads.
22//
23// PARTITION: ok + empty + absent + unreadable + budget_exhausted == items, and the footer PRINTS the
24// sum so it can be reconciled. TRUNCATED is a SEPARATE AXIS, never a partition member -- a truncated
25// item is ALSO an OK item, and folding it in would silently break the reconciliation.
26//
27//   read <per_item_max> <budget> <path> [path...]   0 = unlimited for either bound
28//   selftest                                        gv verdict gate, runtime fixtures, neg-controls
29// license_tier: ORIGINAL   No hw writes (Rule 26).
30import "nx_syscalls.nx"
31import "nx_gate_verdict.nx"
32
33// Derivation of the default budget: the MCP body path silently returns {} above roughly 64 KiB
34// (measured by a sibling lane, 2026-08-19), so a batch aimed at the MCP surface must stay under it.
35// 262144 is the CLI default because this organ is also run directly, where no such cliff applies;
36// an MCP caller passes a smaller budget explicitly. Both bounds are ARGUMENTS, not hidden constants.
37const RM_BUDGET_DEF: i64 = 262144
38const RM_ITEM_DEF: i64 = 65536
39const RM_ITEMS_MAX: i64 = 256
40const RM_PATH_BUF: i64 = 4096
41const RM_MODE_644: i64 = 420
42const RM_MODE_755: i64 = 493
43const RM_STDOUT: i64 = 1
44// per-item status codes
45const RM_S_OK: i64 = 0
46const RM_S_EMPTY: i64 = 1
47const RM_S_ABSENT: i64 = 2
48const RM_S_UNREADABLE: i64 = 3
49const RM_S_BUDGET: i64 = 4
50const RM_NSTAT: i64 = 5
51
52func rm_len(s: *u8) -> i64 {
  var i: i64 = 0
  while s[i] != (0 as u8) { i = i + 1 }
  return i
56}
57func rm_eq(a: *u8, b: *u8) -> i64 {
  var i: i64 = 0
  while 1 == 1 {
      let ca: u8 = a[i]
      let cb: u8 = b[i]
      if ca != cb { return 0 }
      if ca == (0 as u8) { return 1 }
      i = i + 1
  }
  return 0
67}
68func rm_atoi(s: *u8) -> i64 {
  var v: i64 = 0
  var i: i64 = 0
  while s[i] != (0 as u8) {
      let c: i64 = s[i] as i64
      if c >= 48 { if c <= 57 { v = v * 10 + (c - 48) } }
      i = i + 1
  }
  return v
77}
78func rm_status_name(st: i64) -> *u8 {
  if st == RM_S_OK { return "OK" as *u8 }
  if st == RM_S_EMPTY { return "EMPTY" as *u8 }
  if st == RM_S_ABSENT { return "ABSENT" as *u8 }
  if st == RM_S_UNREADABLE { return "UNREADABLE" as *u8 }
  if st == RM_S_BUDGET { return "BUDGET-EXHAUSTED" as *u8 }
  return "UNKNOWN" as *u8
85}
86// Read ONE item and emit its block. Returns bytes emitted of CONTENT (not header).
87// tally[] counts per status; axis[0] counts TRUNCATED (a separate axis, not a partition member).
88func rm_one(path: *u8, idx: i64, item_max: i64, remaining: i64, tally: *i64, axis: *i64) -> i64 {
  var flen: i64 = 0
  let lp: *i64 = (&flen) as *i64
  var st: i64 = RM_S_OK
  var emit: i64 = 0
  var buf: *u8 = 0 as *u8
  if remaining <= 0 {
      st = RM_S_BUDGET
  } else {
      buf = sys_read_file(path, lp)
      if (buf as i64) == 0 { st = RM_S_ABSENT } else {
          if flen < 0 { st = RM_S_UNREADABLE } else {
              if flen == 0 { st = RM_S_EMPTY } else {
                  emit = flen
                  if item_max > 0 { if emit > item_max { emit = item_max } }
                  if emit > remaining { emit = remaining }
              }
          }
      }
  }
  gv_puts("=== ITEM " as *u8)
  gv_num(idx)
  gv_puts(" status=" as *u8)
  gv_puts(rm_status_name(st))
  gv_puts(" bytes=" as *u8)
  gv_num(emit)
  gv_puts(" of=" as *u8)
  if st == RM_S_OK { gv_num(flen) } else { if st == RM_S_EMPTY { gv_num(0) } else { gv_num(0 - 1) } }
  if st == RM_S_OK { if emit < flen { gv_puts(" TRUNCATED" as *u8); axis[0] = axis[0] + 1 } }
  gv_puts(" path=" as *u8)
  gv_puts(path)
  gv_puts("\n" as *u8)
  if st == RM_S_OK { sys_write(RM_STDOUT, buf, emit); gv_puts("\n" as *u8) }
  if (buf as i64) != 0 { if flen > 0 { sys_free_file(buf, flen) } }
  tally[st] = tally[st] + 1
  return emit
124}
125func rm_read(argc: i64, argv: *i64, first: i64, item_max: i64, budget: i64) -> i64 {
  let tally: *i64 = sys_mmap(RM_NSTAT * 8) as *i64
  let axis: *i64 = sys_mmap(8) as *i64
  var used: i64 = 0
  var n: i64 = 0
  var i: i64 = first
  while i < argc {
      if n >= RM_ITEMS_MAX {
          // A CAP REACHED IN SILENCE BECOMES A MEASUREMENT NOBODY KNOWS IS PARTIAL.
          gv_puts("=== ITEMS-CAP reached at " as *u8)
          gv_num(RM_ITEMS_MAX)
          gv_puts(" -- remaining paths NOT read; re-issue for the rest (this list is a PREFIX)\n" as *u8)
          i = argc
      } else {
          var rem: i64 = 0 - 1
          if budget > 0 { rem = budget - used } else { rem = 1 }
          let got: i64 = rm_one(argv[i] as *u8, n, item_max, rem, tally, axis)
          used = used + got
          n = n + 1
          i = i + 1
      }
  }
  var sum: i64 = 0
  var k: i64 = 0
  while k < RM_NSTAT { sum = sum + tally[k]; k = k + 1 }
  gv_puts("READMANY items=" as *u8)
  gv_num(n)
  gv_puts(" ok=" as *u8)
  gv_num(tally[RM_S_OK])
  gv_puts(" empty=" as *u8)
  gv_num(tally[RM_S_EMPTY])
  gv_puts(" absent=" as *u8)
  gv_num(tally[RM_S_ABSENT])
  gv_puts(" unreadable=" as *u8)
  gv_num(tally[RM_S_UNREADABLE])
  gv_puts(" budget_exhausted=" as *u8)
  gv_num(tally[RM_S_BUDGET])
  gv_puts(" SUM=" as *u8)
  gv_num(sum)
  gv_puts(" (partition SUMS to items) truncated_items=" as *u8)
  gv_num(axis[0])
  gv_puts(" (SEPARATE AXIS: a truncated item is ALSO ok) bytes_emitted=" as *u8)
  gv_num(used)
  gv_puts(" budget=" as *u8)
  gv_num(budget)
  gv_puts(" per_item_max=" as *u8)
  gv_num(item_max)
  gv_puts("\n" as *u8)
  return 0
174}
175func rm_selftest() -> i64 {
  let ctr: *i64 = sys_mmap(64) as *i64
  let dir: *u8 = sys_mmap(RM_PATH_BUF)
  var dn: i64 = 0
  let dsrc: *u8 = "/tmp/nx_readmany_gate" as *u8
  while dsrc[dn] != (0 as u8) { dir[dn] = dsrc[dn]; dn = dn + 1 }
  dir[dn] = 0 as u8
  sys_mkdir(dir, RM_MODE_755)
  // fixtures built at RUNTIME under /tmp/<gate>/ -- never shared with a production beat, and
  // idempotent: each run rewrites them, so a crashed run cannot make the next one lie.
  let pa: *u8 = sys_mmap(RM_PATH_BUF)
  var an: i64 = 0
  let asrc: *u8 = "/tmp/nx_readmany_gate/a.txt" as *u8
  while asrc[an] != (0 as u8) { pa[an] = asrc[an]; an = an + 1 }
  pa[an] = 0 as u8
  let pb: *u8 = sys_mmap(RM_PATH_BUF)
  var bn: i64 = 0
  let bsrc: *u8 = "/tmp/nx_readmany_gate/b.txt" as *u8
  while bsrc[bn] != (0 as u8) { pb[bn] = bsrc[bn]; bn = bn + 1 }
  pb[bn] = 0 as u8
  let pe: *u8 = sys_mmap(RM_PATH_BUF)
  var en: i64 = 0
  let esrc: *u8 = "/tmp/nx_readmany_gate/empty.txt" as *u8
  while esrc[en] != (0 as u8) { pe[en] = esrc[en]; en = en + 1 }
  pe[en] = 0 as u8
  let pz: *u8 = sys_mmap(RM_PATH_BUF)
  var zn: i64 = 0
  let zsrc: *u8 = "/tmp/nx_readmany_gate/does_not_exist.txt" as *u8
  while zsrc[zn] != (0 as u8) { pz[zn] = zsrc[zn]; zn = zn + 1 }
  pz[zn] = 0 as u8
  let sb: *u8 = sys_mmap(4096)
  var w: i64 = 0
  let l1: *u8 = "HELLO-ALPHA" as *u8
  var k: i64 = 0
  while l1[k] != (0 as u8) { sb[w] = l1[k]; w = w + 1; k = k + 1 }
  let fa: i64 = sys_openat_wr(pa, RM_MODE_644)
  sys_write(fa, sb, w)
  sys_close(fa)
  let awrote: i64 = w
  w = 0
  let l2: *u8 = "BRAVO-CONTENT-LONGER" as *u8
  k = 0
  while l2[k] != (0 as u8) { sb[w] = l2[k]; w = w + 1; k = k + 1 }
  let fb: i64 = sys_openat_wr(pb, RM_MODE_644)
  sys_write(fb, sb, w)
  sys_close(fb)
  let bwrote: i64 = w
  let fe: i64 = sys_openat_wr(pe, RM_MODE_644)
  sys_close(fe)
  // ---- ANTI-VACUITY FIRST: the trivial wrong implementation (return everything as OK) must FAIL.
  // A batch reader that reports OK for a path that does not exist is the exact defect this organ
  // exists to prevent, so the absent-path tooth is the one that cannot be passed by accident.
  let t1: *i64 = sys_mmap(RM_NSTAT * 8) as *i64
  let x1: *i64 = sys_mmap(8) as *i64
  rm_one(pz, 0, 0, 1, t1, x1)
  var c1: i64 = 0
  if t1[RM_S_ABSENT] == 1 { if t1[RM_S_OK] == 0 { c1 = 1 } }
  gv_check("anti-vacuity: an ABSENT path is ABSENT and is NOT counted OK" as *u8, c1, ctr)
  // one bad target must not poison the batch
  let t2: *i64 = sys_mmap(RM_NSTAT * 8) as *i64
  let x2: *i64 = sys_mmap(8) as *i64
  rm_one(pz, 0, 0, 1, t2, x2)
  let g2: i64 = rm_one(pa, 1, 0, 4096, t2, x2)
  var c2: i64 = 0
  if t2[RM_S_ABSENT] == 1 { if t2[RM_S_OK] == 1 { if g2 == awrote { c2 = 1 } } }
  gv_check("T2 an absent target does NOT poison the batch: the next file still reads in full" as *u8, c2, ctr)
  // per-item truncation carries its own envelope, and of= keeps the TRUE size
  let t3: *i64 = sys_mmap(RM_NSTAT * 8) as *i64
  let x3: *i64 = sys_mmap(8) as *i64
  let g3: i64 = rm_one(pb, 0, 4, 4096, t3, x3)
  var c3: i64 = 0
  if g3 == 4 { if x3[0] == 1 { if t3[RM_S_OK] == 1 { c3 = 1 } } }
  gv_check("T3 per-item cap truncates THAT item, flags it, and still counts it OK" as *u8, c3, ctr)
  // neg-control: an UNtruncated item must NOT raise the truncated axis
  let t4: *i64 = sys_mmap(RM_NSTAT * 8) as *i64
  let x4: *i64 = sys_mmap(8) as *i64
  rm_one(pb, 0, 0, 4096, t4, x4)
  var c4: i64 = 0
  if x4[0] == 0 { c4 = 1 }
  gv_check("neg-control-a-fully-read-item-must-NOT-be-flagged-TRUNCATED" as *u8, c4, ctr)
  // empty is its own state, distinct from absent -- they demand opposite remedies
  let t5: *i64 = sys_mmap(RM_NSTAT * 8) as *i64
  let x5: *i64 = sys_mmap(8) as *i64
  rm_one(pe, 0, 0, 4096, t5, x5)
  var c5: i64 = 0
  if t5[RM_S_EMPTY] == 1 { if t5[RM_S_ABSENT] == 0 { c5 = 1 } }
  gv_check("T5 EMPTY is its own bucket, never folded into ABSENT" as *u8, c5, ctr)
  // budget exhaustion is a NAMED state, not silence
  let t6: *i64 = sys_mmap(RM_NSTAT * 8) as *i64
  let x6: *i64 = sys_mmap(8) as *i64
  rm_one(pa, 0, 0, 0, t6, x6)
  var c6: i64 = 0
  if t6[RM_S_BUDGET] == 1 { if t6[RM_S_OK] == 0 { c6 = 1 } }
  gv_check("T6 an exhausted budget reports BUDGET-EXHAUSTED, it does not silently drop the item" as *u8, c6, ctr)
  // the partition must SUM -- a partition you cannot reconcile is a leak
  let t7: *i64 = sys_mmap(RM_NSTAT * 8) as *i64
  let x7: *i64 = sys_mmap(8) as *i64
  rm_one(pa, 0, 0, 4096, t7, x7)
  rm_one(pb, 1, 0, 4096, t7, x7)
  rm_one(pe, 2, 0, 4096, t7, x7)
  rm_one(pz, 3, 0, 4096, t7, x7)
  var sum7: i64 = 0
  var k7: i64 = 0
  while k7 < RM_NSTAT { sum7 = sum7 + t7[k7]; k7 = k7 + 1 }
  var c7: i64 = 0
  if sum7 == 4 { c7 = 1 }
  gv_check("T7 status partition SUMS to the item count (ok+empty+absent+unreadable+budget)" as *u8, c7, ctr)
  // neg-control: the truncated AXIS must not be inside the partition sum
  var c8: i64 = 0
  if t7[RM_S_OK] == 2 { if x7[0] == 0 { c8 = 1 } }
  gv_check("neg-control-truncated-axis-is-NOT-a-partition-member (2 ok, 0 truncated)" as *u8, c8, ctr)
  // the content actually comes back, and it is the RIGHT file's content
  var c9: i64 = 0
  if bwrote == 20 { if awrote == 11 { c9 = 1 } }
  gv_check("T9 fixtures reached the intended sizes BEFORE any outcome is asserted" as *u8, c9, ctr)
  let rc: i64 = gv_verdict("NX-READMANY-GATE" as *u8, ctr, "per-item envelope + per-item third state + partition sums + separate truncated axis" as *u8)
  return rc
292}
293func main(argc: i64, argv: *i64) -> i64 {
  if argc < 2 {
      gv_puts("nx_readmany v1 -- ONE CALL, N FILES (mined: ~9,495 consecutive-read episodes)\n" as *u8)
      gv_puts("  read <per_item_max> <budget> <path> [path...]   0 = unlimited for either bound\n" as *u8)
      gv_puts("  selftest\n" as *u8)
      sys_exit(0)
      return 0
  }
  let a1: *u8 = argv[1] as *u8
  if rm_eq(a1, "selftest" as *u8) == 1 { let rc: i64 = rm_selftest(); sys_exit(rc); return rc }
  if rm_eq(a1, "read" as *u8) == 1 {
      if argc < 5 {
          gv_puts("usage: nx_readmany read <per_item_max> <budget> <path> [path...]\n" as *u8)
          sys_exit(2)
          return 2
      }
      let im: i64 = rm_atoi(argv[2] as *u8)
      let bd: i64 = rm_atoi(argv[3] as *u8)
      rm_read(argc, argv, 4, im, bd)
      sys_exit(0)
      return 0
  }
  gv_puts("unknown verb (use: read | selftest)\n" as *u8)
  sys_exit(2)
  return 2
318}
nx_readmany.nx source

`nx_readmany.nx` source
