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

↩ module page · 361 lines · 18388 B
1// nx_board_idref_gate.nx -- THE COMPARE BOARD'S REFERENTIAL INTEGRITY REFEREE (2026-09-04).
2//
3// WHY THIS EXISTS, AND WHY IT IS A MECHANISM RATHER THAN ANOTHER LAW. On 2026-09-03 a seat appended a rung
4// as LN37 and four log rows as LN36 and BOTH ids were already taken by another lane the same day. It
5// journaled the finding, renumbered to LN41/LN42 after grepping for free ids, and wrote the durable remedy
6// in its own words: "the durable fix is a uniqueness tooth in the compare referee rather than a habit."
7// By 2026-09-04 LN41 AND LN42 had each collided AGAIN -- the renumbering itself landed on ids a third lane
8// had taken while it worked. That is the whole argument for this file: GREP-BEFORE-APPEND IS A HABIT, AND
9// A HABIT LOSES TO CONCURRENCY EVERY TIME. Only something in the path can hold this invariant.
10//
11// WHAT IT JUDGES. A .plan is a board, and a board's ids are its addresses. Three ways an address goes bad:
12//   DUPID   two rung rows share an id, so the ranker, a watch flip and a done-rule all attach to whichever
13//           the reader matches first. Measured live: lang carried one LANDED and one OPEN rung under LN42,
14//           which is the dangerous shape -- the board can report the open work as finished.
15//   DANGLOG a log row is journaled against a rung id no rung row declares, so the worked plan a crashed
16//           session is supposed to inherit points at nothing.
17//   DANGMS  a milestone lists a member rung that does not exist, so its cumulative estimate is over a set
18//           the board cannot enumerate.
19//
20// IT RATCHETS RATHER THAN DEMANDING ZERO, AND THAT IS DELIBERATE. Real offenders already exist that belong
21// to other lanes, and a detector that is permanently RED is one everyone learns to ignore. The bar is
22// knowledge/status/board_idref.baseline; the gate goes RED only when the count RISES, and it TIGHTENS the
23// baseline when the count falls so a fix cannot be undone silently. EVERY OFFENDER IS NAMED IN THE OUTPUT
24// whatever the verdict, because a count without a worklist is not actionable.
25//
26// COMPOSES nx_rowparse_lib for pipe-delimited column extraction rather than hand-rolling a fourth copy of
27// that arithmetic, and gk_* for directory and file access.
28// license_tier: ORIGINAL. Reads the compare trees, writes only its own baseline. No hw writes (Rule 26).
29import "nx_syscalls.nx"
30import "nx_gate_verdict.nx"
31import "nx_gatekit_lib.nx"
32import "nx_rowparse_lib.nx"
33
34// A .plan is prose-heavy: the largest measured is ~131 KB, so 4 MB is thirty times the largest real board.
35// A file over this is REFUSED BY NAME and forces coverage_complete to 0 rather than being read in part --
36// a partial board would under-report both duplicates and dangling references.
37const BI_FILECAP: i64 = 4194304
38const BI_NAMES: i64 = 262144
39const BI_NAMESTRIDE: i64 = 256
40const BI_MAXFILES: i64 = 512
41const BI_IDCAP: i64 = 32
42const BI_MAXIDS: i64 = 1024
43const BI_PATH: i64 = 1024
44const BI_OUT: i64 = 262144
45const BI_SPAN: i64 = 8
46const BI_BASEMAX: i64 = 64
47const BI_DIR_PRIMARY: *u8 = "buildroot/knowledge/compare/"
48const BI_DIR_SECONDARY: *u8 = "knowledge/compare/"
49const BI_BASELINE: *u8 = "knowledge/status/board_idref.baseline"
50const BI_FLD_KIND: i64 = 0
51const BI_FLD_RUNGID: i64 = 1
52const BI_FLD_LOGID: i64 = 2
53const BI_FLD_MSMEMBERS: i64 = 4
54const BI_COMMA: i64 = 44
55const BI_SPACE: i64 = 32
56const BI_CR: i64 = 13
57
58// store id `s` (len l) into slot table at index n; returns new n (silently refuses to overflow, and the
59// caller checks the cap so a full table becomes a NAMED refusal rather than a quiet undercount)
60func bi_put_id(tab: *u8, n: i64, b: *u8, s: i64, l: i64) -> i64 {
  if n >= BI_MAXIDS { return n }
  var len: i64 = l
  if len > BI_IDCAP - 1 { len = BI_IDCAP - 1 }
  var i: i64 = 0
  while i < len { tab[n * BI_IDCAP + i] = b[s + i]; i = i + 1 }
  tab[n * BI_IDCAP + len] = 0 as u8
  return n + 1
68}
69func bi_id_at(tab: *u8, i: i64) -> *u8 { return (tab as i64 + i * BI_IDCAP) as *u8 }
70// TRIM A TRAILING CR OR SPACE FROM AN EXTRACTED ID. The compare tree has MIXED LINE ENDINGS -- measured
71// 2026-09-04, failmodes.plan is CRLF while performance.plan and enginelab.plan are LF -- and rp_le stops at
72// the newline, so on a CRLF board the carriage return rides along on whatever field ends the line. That made
73// the LAST member of every milestone on a CRLF board unresolvable and reported three declared rungs as
74// missing. The tell was that the offenders were FM5, FM8 and FM9: the last member of M1, M2 and M3 exactly.
75func bi_trim(b: *u8) -> i64 {
  var n: i64 = 0
  while b[n] != (0 as u8) { n = n + 1 }
  while n > 0 {
      let ch: i64 = b[n - 1] as i64
      if ch == BI_CR { n = n - 1 } else {
          if ch == BI_SPACE { n = n - 1 } else { b[n] = 0 as u8; return n }
      }
  }
  b[0] = 0 as u8
  return 0
86}
87// how many times does the id at slot `k` appear in the first `n` slots?
88func bi_count(tab: *u8, n: i64, k: i64) -> i64 {
  var c: i64 = 0
  var i: i64 = 0
  while i < n {
      if gk_streq(bi_id_at(tab, i), bi_id_at(tab, k)) == 1 { c = c + 1 }
      i = i + 1
  }
  return c
96}
97func bi_has_id(tab: *u8, n: i64, want: *u8) -> i64 {
  var i: i64 = 0
  while i < n {
      if gk_streq(bi_id_at(tab, i), want) == 1 { return 1 }
      i = i + 1
  }
  return 0
104}
105// is this the FIRST slot holding this id? Used so a duplicate is reported ONCE per id, not once per copy.
106func bi_first(tab: *u8, k: i64) -> i64 {
  var i: i64 = 0
  while i < k {
      if gk_streq(bi_id_at(tab, i), bi_id_at(tab, k)) == 1 { return 0 }
      i = i + 1
  }
  return 1
113}
114
115func main(argc: i64, argv: **u8) -> i64 {
  let ctr: *i64 = gv_ctr()
  gv_head("NX-BOARD-IDREF-GATE" as *u8)
118
  let names: *u8 = sys_mmap(BI_NAMES)
  let fbuf: *u8 = sys_mmap(BI_FILECAP)
  let rungs: *u8 = sys_mmap(BI_IDCAP * BI_MAXIDS)
  let path: *u8 = sys_mmap(BI_PATH)
  let idbuf: *u8 = sys_mmap(BI_IDCAP)
  let out: *u8 = sys_mmap(BI_OUT)
  let c: *i64 = sys_mmap(BI_SPAN * 2) as *i64
  var o: i64 = 0
127
  // BOTH compare trees are scanned, as SEPARATE roots rather than as an overlay. gk_dirscan's shadowdir
  // argument means "skip a basename that also exists there", which is the right rule for resolving WHICH
  // SOURCE COMPILES and exactly the wrong one here: a board present in both trees is two boards, and each
  // one's ids must be judged on their own. Measured 2026-08-31: .plan is buildroot-owned and .gates is
  // knowledge-owned, so neither root may be assumed to be the whole subject.
  var nf: i64 = gk_dirscan_ext(BI_DIR_PRIMARY, 0 as *u8, names, BI_NAMESTRIDE, BI_MAXFILES, 0, ".plan" as *u8)
  if nf < 0 { nf = 0 }
  let nf2: i64 = gk_dirscan_ext(BI_DIR_SECONDARY, 0 as *u8, names, BI_NAMESTRIDE, BI_MAXFILES, nf, ".plan" as *u8)
  if nf2 > nf { nf = nf2 }
  var domains: i64 = 0
  var rungrows: i64 = 0
  var logrows: i64 = 0
  var msrows: i64 = 0
  var dupid: i64 = 0
  var danglog: i64 = 0
  var dangms: i64 = 0
  var unread: i64 = 0
  var oversize: i64 = 0
  // HIGH-WATER MARK OF THE PER-FILE TABLE. The saturation control must compare the table against the
  // largest SINGLE board, never against the fleet total: the table is refilled per board, so testing the
  // sum makes the control fire as soon as the fleet is bigger than one board's capacity -- which it always
  // is. Measured 2026-09-04: 1443 fleet rung rows against a 1024-slot per-board table produced exactly that
  // false RED on the first live run.
  var maxids: i64 = 0
152
  var fi: i64 = 0
  while fi < nf {
      let nm: *u8 = (names as i64 + fi * BI_NAMESTRIDE) as *u8
      // .plan only. gk_dirscan yields every entry, so the extension test is what scopes the subject.
      if gk_ext_is(nm, ".plan" as *u8) == 1 {
          // gk_dirscan_ext yields the FULL path already; joining a root onto it again would produce a
          // doubled path that opens nothing and reports every board as unreadable.
          rp_cstr(path, nm, 0, rp_slen(nm))
          let sz: i64 = gk_size(path)
          if sz > BI_FILECAP {
              oversize = oversize + 1
              o = rp_put(out, o, "OVERSIZE ")
              o = rp_put(out, o, nm)
              o = rp_put(out, o, "  <== NOT READ, so this board is UNJUDGED rather than clean\n")
          } else {
              let n: i64 = gk_read(path, fbuf, BI_FILECAP)
              if n <= 0 {
                  unread = unread + 1
              } else {
                  domains = domains + 1
                  // ---- PASS 1: every rung id declared by this board.
                  var nr: i64 = 0
                  var ls: i64 = 0
                  while ls < n {
                      let le: i64 = rp_le(fbuf, ls, n)
                      if le > ls {
                          if rp_col_pipe(fbuf, ls, le, BI_FLD_KIND, c) == 1 {
                              if rp_lit_eq(fbuf, c[0], c[1], "rung" as *u8) == 1 {
                                  if rp_col_pipe(fbuf, ls, le, BI_FLD_RUNGID, c) == 1 {
                                      nr = bi_put_id(rungs, nr, fbuf, c[0], c[1])
                                      rungrows = rungrows + 1
                                  }
                              }
                          }
                      }
                      ls = le + 1
                  }
                  if nr > maxids { maxids = nr }
                  // ---- DUPID, reported once per id rather than once per copy.
                  var k: i64 = 0
                  while k < nr {
                      if bi_first(rungs, k) == 1 {
                          let cnt: i64 = bi_count(rungs, nr, k)
                          if cnt > 1 {
                              dupid = dupid + 1
                              o = rp_put(out, o, "DUPID    ")
                              o = rp_put(out, o, nm)
                              o = rp_put(out, o, " id=")
                              o = rp_put(out, o, bi_id_at(rungs, k))
                              o = rp_put(out, o, " copies=")
                              o = rp_putn(out, o, cnt)
                              o = rp_put(out, o, "  <== the ranker, a watch flip and a done-rule attach to whichever copy is matched first\n")
                          }
                      }
                      k = k + 1
                  }
                  // ---- PASS 2: every reference must resolve to a declared rung id.
                  ls = 0
                  while ls < n {
                      let le: i64 = rp_le(fbuf, ls, n)
                      if le > ls {
                          if rp_col_pipe(fbuf, ls, le, BI_FLD_KIND, c) == 1 {
                              if rp_lit_eq(fbuf, c[0], c[1], "log" as *u8) == 1 {
                                  logrows = logrows + 1
                                  if rp_col_pipe(fbuf, ls, le, BI_FLD_LOGID, c) == 1 {
                                      rp_cstr(idbuf, fbuf, c[0], c[1])
                                      bi_trim(idbuf)
                                      if bi_has_id(rungs, nr, idbuf) == 0 {
                                          danglog = danglog + 1
                                          o = rp_put(out, o, "DANGLOG  ")
                                          o = rp_put(out, o, nm)
                                          o = rp_put(out, o, " -> ")
                                          o = rp_put(out, o, idbuf)
                                          o = rp_put(out, o, "  <== a journalled measurement addressed to a rung this board does not declare\n")
                                      }
                                  }
                              }
                              if rp_lit_eq(fbuf, c[0], c[1], "ms" as *u8) == 1 {
                                  msrows = msrows + 1
                                  if rp_col_pipe(fbuf, ls, le, BI_FLD_MSMEMBERS, c) == 1 {
                                      // members are a comma list inside one field
                                      var ms: i64 = c[0]
                                      let me: i64 = c[0] + c[1]
                                      while ms < me {
                                          // MEMBERS ARE SEPARATED BY A COMMA *OR* A SPACE, AND BOTH ARE IN
                                          // LIVE USE. Measured 2026-09-04: lang writes LN4,LN5,LN6 while
                                          // performance writes PF2 PF11 and enginelab writes EL1 EL2. A
                                          // comma-only split read every space-separated list as ONE token,
                                          // which matched no rung and reported 17 dangling members on five
                                          // boards whose rungs were all declared. That was a false-positive
                                          // class in this detector, not a defect in those boards.
                                          var mt: i64 = ms
                                          while mt < me {
                                              if (fbuf[mt] as i64) == BI_COMMA { break }
                                              if (fbuf[mt] as i64) == BI_SPACE { break }
                                              mt = mt + 1
                                          }
                                          if mt > ms {
                                              rp_cstr(idbuf, fbuf, ms, mt - ms)
                                              bi_trim(idbuf)
                                              if bi_has_id(rungs, nr, idbuf) == 0 {
                                                  dangms = dangms + 1
                                                  o = rp_put(out, o, "DANGMS   ")
                                                  o = rp_put(out, o, nm)
                                                  o = rp_put(out, o, " -> ")
                                                  o = rp_put(out, o, idbuf)
                                                  o = rp_put(out, o, "  <== a milestone counts a member rung the board does not declare\n")
                                              }
                                          }
                                          ms = mt + 1
                                      }
                                  }
                              }
                          }
                      }
                      ls = le + 1
                  }
              }
          }
      }
      fi = fi + 1
  }
275
  let offenders: i64 = dupid + danglog + dangms
  o = rp_put(out, o, "ENVELOPE domains=")
  o = rp_putn(out, o, domains)
  o = rp_put(out, o, " rung_rows=")
  o = rp_putn(out, o, rungrows)
  o = rp_put(out, o, " log_rows=")
  o = rp_putn(out, o, logrows)
  o = rp_put(out, o, " ms_rows=")
  o = rp_putn(out, o, msrows)
  o = rp_put(out, o, " dupid=")
  o = rp_putn(out, o, dupid)
  o = rp_put(out, o, " danglog=")
  o = rp_putn(out, o, danglog)
  o = rp_put(out, o, " dangms=")
  o = rp_putn(out, o, dangms)
  o = rp_put(out, o, " offenders=")
  o = rp_putn(out, o, offenders)
  o = rp_put(out, o, " unreadable=")
  o = rp_putn(out, o, unread)
  o = rp_put(out, o, " oversize=")
  o = rp_putn(out, o, oversize)
  var complete: i64 = 1
  if unread > 0 { complete = 0 }
  if oversize > 0 { complete = 0 }
  o = rp_put(out, o, " coverage_complete=")
  o = rp_putn(out, o, complete)
  o = rp_put(out, o, "\n")
  sys_write(1, out, o)
304
  // ---- THE RATCHET. Baseline absent means FIRST SIGHT: adopt the current count so the gate is
  // non-breaking by construction, and say so, rather than going RED on every board at once.
  let bb: *u8 = sys_mmap(BI_BASEMAX)
  let bn: i64 = gk_read(BI_BASELINE, bb, BI_BASEMAX - 1)
  var baseline: i64 = 0 - 1
  if bn > 0 {
      bb[bn] = 0 as u8
      baseline = rp_num(bb, 0, bn)
  }
  var seeded: i64 = 0
  if baseline < 0 { baseline = offenders; seeded = 1 }
316
  gv_check("subject-population-non-empty" as *u8, (domains > 0) as i64, ctr)
  gv_check("coverage-complete-no-unreadable-or-oversize-board" as *u8, complete, ctr)
  gv_check_eq("offenders-did-not-rise-above-the-ratchet" as *u8,
              (offenders > baseline) as i64, 0, ctr)
  // NEG-CONTROL: the id table must not have silently filled, or a board's later rungs would be invisible
  // and every reference to them would read as dangling -- a false positive that looks like a finding.
  gv_check("neg-control-rung-id-table-did-not-saturate-on-the-largest-board" as *u8,
           (maxids < BI_MAXIDS) as i64, ctr)
325
  gv_values_head()
  gv_kv("domains" as *u8, domains)
  gv_kv("rung_rows" as *u8, rungrows)
  gv_kv("log_rows" as *u8, logrows)
  gv_kv("ms_rows" as *u8, msrows)
  gv_kv("dupid" as *u8, dupid)
  gv_kv("danglog" as *u8, danglog)
  gv_kv("dangms" as *u8, dangms)
  gv_kv("offenders" as *u8, offenders)
  gv_kv("max_rungs_on_one_board" as *u8, maxids)
  gv_kv("id_table_slots" as *u8, BI_MAXIDS)
  gv_kv("baseline" as *u8, baseline)
  gv_kv("baseline_seeded_this_run" as *u8, seeded)
339
  // TIGHTEN ON A FALL, and only on a fall. A ratchet that rewrites its baseline on a RISE launders itself
  // green, which is the defect this estate has bitten three times.
  if offenders < baseline {
      var t: i64 = 0
      let tb: *u8 = sys_mmap(BI_BASEMAX)
      t = rp_putn(tb, 0, offenders)
      tb[t] = 10 as u8
      tb[t + 1] = 0 as u8
      gk_write(BI_BASELINE, tb)
  }
  if seeded == 1 {
      var t2: i64 = 0
      let tb2: *u8 = sys_mmap(BI_BASEMAX)
      t2 = rp_putn(tb2, 0, offenders)
      tb2[t2] = 10 as u8
      tb2[t2 + 1] = 0 as u8
      gk_write(BI_BASELINE, tb2)
  }
358
  return gv_verdict("BOARD-IDREF-GATE" as *u8, ctr,
      "every rung id on every compare board is unique within its board, and every log row and milestone member resolves to a rung that board declares; the offender count is ratcheted so a rise is RED and a fall tightens the bar, and every offender is named above whatever the verdict")
361}
nx_board_idref_gate.nx source

`nx_board_idref_gate.nx` source
