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

↩ module page · 345 lines · 18419 B
1// nx_compare_cite.nx -- CITE A /compare ROW IN ONE PUBLISH: the ref row AND its inline mark, or neither.
2//
3// WHY (operator, 2026-09-02: "this should be capabilities that the nishi team and estate and ecosystem
4// have"). A citation on a /compare board is TWO writes in TWO files -- a `ref|key|...` row in <dom>.refs
5// and a `[@key]` mark inside one matrix row's note -- and nx_compare_refs_gate refuses the board when
6// either half is missing (UNCITED when the row lands without its mark, UNRESOLVED-MARK when the mark
7// lands without its row). Measured the day this was written: fifteen refs landed as one edit and five
8// marks then had to be placed by five sequential compare-and-swap edits, each a separate transport
9// round-trip, each a chance to half-land. The estate had a GATE for citations (nx_compare_refs_gate),
10// a FORMAT PRECHECK (nx_atlas_cite) and a VERIFIER (nx_cite_lib) -- and no WRITER. This is the writer.
11//
12// WHAT IT REFUSES BY CONSTRUCTION (the fabrication class the refs law names):
13//   * the pin is COMPUTED from the mirror file, never typed -- a reference whose mirror is absent cannot
14//     be cited at all (REFUSED-MIRROR-ABSENT), so "a reference you did not fetch" cannot enter a register.
15//   * the target row is named by its LABEL PREFIX and must match EXACTLY ONE matrix row (0 -> ROW-NOT-FOUND,
16//     2+ -> ROW-AMBIGUOUS with the count), so a mark can never land on the wrong row.
17//   * a pipe inside any prose field is refused (the row grammar has exactly 9 fields).
18//   * both files are re-written whole under nx_atomic_publish's compare-and-swap with the sha256 THIS run
19//     read (composed: forked, never re-implemented), so a concurrent editor is refused, never clobbered.
20//   * ORDER: refs first, then the mark. A ref without its mark is the gate's UNCITED class (named, and
21//     this organ is idempotent so a re-run adds the missing half); a mark without its ref would DANGLE.
22//   * IDEMPOTENT: key present AND mark present -> ALREADY-CITED, exit 0, nothing written.
23//
24// TREE RESOLUTION is composed from nx_comparetree_lib in PUBLISHED order (buildroot first, the tree the
25// page renders from; the authored tree second), the same order the referee reads .matrix and .refs.
26//
27// usage: nx_compare_cite <domain> <key> <row-label-prefix> <cite> <url> <mirror> <class> <grounds>
28//        nx_compare_cite @<specfile>     (8 lines in the same order -- the argv-mangling-safe form the
29//                                          memory rail already uses; CRLF tolerated)
30// receipt (last line, positional): CITED | ALREADY-CITED | REFUSED-<reason> | PARTIAL-refs-published-mark-refused
31// exit: 0 cited or already | 2 usage | 3 field refused (pipe, empty, non-http url) | 4 mirror absent
32//       5 refs or matrix file unresolvable | 6 row not found or ambiguous | 7 refs publish refused
33//       8 mark publish refused after the ref landed (re-run: idempotent, it adds only the mark)
34// license_tier: ORIGINAL   No hw writes (Rule 26).   expect_exit: 0
35import "nx_syscalls.nx"
36import "nx_sha256.nx"
37import "nx_comparetree_lib.nx"
38import "nx_tool_run.nx"
39
40const CC_PUBLISH_ELF: *u8 = "/volume1/homes/elderwesto/nishihost/nx_atomic_publish.elf"
41const CC_TMP_SUFFIX: *u8 = ".cite.tmp"
42const CC_SUF_REFS: *u8 = ".refs"
43const CC_SUF_MATRIX: *u8 = ".matrix"
44const CC_MODE: i64 = 420              // 0644, the mode every compare data file already carries
45const CC_PATHCAP: i64 = 1024
46const CC_ROWCAP: i64 = 16384         // one ref row: 9 fields of prose; a longer row is refused, not cut
47const CC_CAPCAP: i64 = 65536          // captured stdout of one nx_atomic_publish fork (announced if it fills)
48const CC_HEX: i64 = 64
49const CC_SPEC_FIELDS: i64 = 8
50const CC_PIPE: i64 = 124
51const CC_NL: i64 = 10
52const CC_CR: i64 = 13
53const CC_AT: i64 = 64
54const CC_HASH: i64 = 35
55const CC_ATSIGN: i64 = 64
56const CC_DAYSECS: i64 = 86400
57const CC_EX_USAGE: i64 = 2
58const CC_EX_FIELD: i64 = 3
59const CC_EX_MIRROR: i64 = 4
60const CC_EX_TREE: i64 = 5
61const CC_EX_ROW: i64 = 6
62const CC_EX_PUB_REFS: i64 = 7
63const CC_EX_PUB_MARK: i64 = 8
64
65func cc_len(s: *u8) -> i64 { var n: i64 = 0; while s[n] != (0 as u8) { n = n + 1 } return n }
66func cc_puts(s: *u8) -> i64 { sys_write(1, s, cc_len(s)); return 0 }
67func cc_putn(v: i64) -> i64 {
  let t: *u8 = sys_mmap(32)
  var m: i64 = v
  if m < 0 { sys_write(1, "-" as *u8, 1); m = 0 - m }
  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 }
  let b: *u8 = sys_mmap(32)
  var i: i64 = 0
  while i < k { b[i] = t[k - 1 - i]; i = i + 1 }
  sys_write(1, b, k)
  sys_munmap(t, 32)
  sys_munmap(b, 32)
  return 0
81}
82func cc_cat(d: *u8, o: i64, s: *u8) -> i64 { var i: i64 = 0; var p: i64 = o; while s[i] != (0 as u8) { d[p] = s[i]; p = p + 1; i = i + 1 } d[p] = 0 as u8; return p }
83func cc_catb(d: *u8, o: i64, s: *u8, n: i64) -> i64 { var i: i64 = 0; var p: i64 = o; while i < n { d[p] = s[i]; p = p + 1; i = i + 1 } d[p] = 0 as u8; return p }
84func cc_has_pipe(s: *u8) -> i64 { var i: i64 = 0; while s[i] != (0 as u8) { if s[i] == (CC_PIPE as u8) { return 1 } i = i + 1 } return 0 }
85func cc_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 }
86// first offset of needle inside buf[0..n) or -1
87func cc_find(buf: *u8, n: i64, needle: *u8) -> i64 {
  let m: i64 = cc_len(needle)
  if m == 0 { return 0 - 1 }
  var i: i64 = 0
  while i + m <= n {
      var k: i64 = 0
      var same: i64 = 1
      while k < m { if buf[i + k] != needle[k] { same = 0; k = m } else { k = k + 1 } }
      if same == 1 { return i }
      i = i + 1
  }
  return 0 - 1
99}
100// 2-digit zero-padded decimal into d at o
101func cc_pad2(d: *u8, o: i64, v: i64) -> i64 { d[o] = (48 + (v / 10) % 10) as u8; d[o + 1] = (48 + v % 10) as u8; return o + 2 }
102// epoch seconds -> "YYYY-MM-DD" (proleptic Gregorian, days-from-civil inverted; integer-only)
103func cc_civil_date(epoch: i64, out: *u8) -> i64 {
  let z: i64 = epoch / CC_DAYSECS + 719468
  let era: i64 = z / 146097
  let doe: i64 = z - era * 146097
  let yoe: i64 = (doe - doe / 1460 + doe / 36524 - doe / 146096) / 365
  var y: i64 = yoe + era * 400
  let doy: i64 = doe - (365 * yoe + yoe / 4 - yoe / 100)
  let mp: i64 = (5 * doy + 2) / 153
  let dd: i64 = doy - (153 * mp + 2) / 5 + 1
  var mm: i64 = mp + 3
  if mp >= 10 { mm = mp - 9 }
  if mm <= 2 { y = y + 1 }
  var o: i64 = 0
  o = cc_pad2(out, o, y / 100)
  o = cc_pad2(out, o, y % 100)
  out[o] = 45 as u8
  o = cc_pad2(out, o + 1, mm)
  out[o] = 45 as u8
  o = cc_pad2(out, o + 1, dd)
  out[o] = 0 as u8
  return o
124}
125func cc_hex(dig: *u8, out: *u8) -> i64 {
  let d: *u8 = "0123456789abcdef" as *u8
  var i: i64 = 0
  while i < 32 { let v: i64 = dig[i] as i64; out[i * 2] = d[(v / 16) % 16]; out[i * 2 + 1] = d[v % 16]; i = i + 1 }
  out[CC_HEX] = 0 as u8
  return CC_HEX
131}
132// resolve <dom><suf> in PUBLISHED order; returns bytes read (whole file, sys_read_file sizes it), fills path + buf pointer
133func cc_resolve(dom: *u8, suf: *u8, path: *u8, bufp: *i64) -> i64 {
  let szp: *i64 = sys_mmap(16) as *i64
  ct_build_path(ct_first_published(), dom, suf, path)
  var b: *u8 = sys_read_file(path, szp)
  if (b as i64) != 0 { if szp[0] > 0 { bufp[0] = b as i64; return szp[0] } }
  ct_build_path(ct_second_published(), dom, suf, path)
  b = sys_read_file(path, szp)
  if (b as i64) != 0 { if szp[0] > 0 { bufp[0] = b as i64; return szp[0] } }
  bufp[0] = 0
  return 0 - 1
143}
144// write buf[0..n) to <target>.cite.tmp then fork nx_atomic_publish <tmp> <target> <expect-hex>; returns the child's exit code
145func cc_publish(target: *u8, buf: *u8, n: i64, expect_hex: *u8, cap: *u8, capn: *i64) -> i64 {
  let tmp: *u8 = sys_mmap(CC_PATHCAP)
  var o: i64 = cc_cat(tmp, 0, target)
  o = cc_cat(tmp, o, CC_TMP_SUFFIX)
  let fd: i64 = sys_openat_wr(tmp, CC_MODE)
  if fd < 0 { return 0 - 1 }
  let w: i64 = sys_write(fd, buf, n)
  sys_close(fd)
  if w != n { return 0 - 2 }
  let argv: *i64 = sys_mmap(8 * 5) as *i64
  argv[0] = CC_PUBLISH_ELF as i64
  argv[1] = tmp as i64
  argv[2] = target as i64
  argv[3] = expect_hex as i64
  argv[4] = 0
  return tr_run_capture(CC_PUBLISH_ELF, argv, cap, CC_CAPCAP - 1, capn)
161}
162// load 8 fields from a spec file (one per line, CRLF tolerated) into slots[0..8)
163func cc_load_spec(path: *u8, slots: *i64) -> i64 {
  let szp: *i64 = sys_mmap(16) as *i64
  let b: *u8 = sys_read_file(path, szp)
  if (b as i64) == 0 { return 0 }
  let n: i64 = szp[0]
  var f: i64 = 0
  var i: i64 = 0
  var start: i64 = 0
  while i <= n { if f < CC_SPEC_FIELDS {
      var eol: i64 = 0
      if i == n { eol = 1 } else { if b[i] == (CC_NL as u8) { eol = 1 } }
      if eol == 1 {
          var e: i64 = i
          if e > start { if b[e - 1] == (CC_CR as u8) { e = e - 1 } }
          b[e] = 0 as u8
          slots[f] = ((b as i64) + start)
          f = f + 1
          start = i + 1
      }
  } i = i + 1 }
  return f
184}
185
186func main(argc: i64, argv: *i64) -> i64 {
  let slots: *i64 = sys_mmap(8 * CC_SPEC_FIELDS) as *i64
  var nf: i64 = 0
  if argc == 2 {
      let a1: *u8 = argv[1] as *u8
      if a1[0] == (CC_AT as u8) { nf = cc_load_spec(((a1 as i64) + 1) as *u8, slots) }
  }
  if argc >= 9 { var k: i64 = 0; while k < CC_SPEC_FIELDS { slots[k] = argv[k + 1]; k = k + 1 } nf = CC_SPEC_FIELDS }
  if nf != CC_SPEC_FIELDS {
      cc_puts("usage: nx_compare_cite <domain> <key> <row-label-prefix> <cite> <url> <mirror> <class> <grounds> | nx_compare_cite @<specfile> (8 lines)\nREFUSED-USAGE fields=" as *u8); cc_putn(nf); cc_puts("\n" as *u8)
      return CC_EX_USAGE
  }
  let dom: *u8 = slots[0] as *u8
  let key: *u8 = slots[1] as *u8
  let label: *u8 = slots[2] as *u8
  let cite: *u8 = slots[3] as *u8
  let url: *u8 = slots[4] as *u8
  let mirror: *u8 = slots[5] as *u8
  let cls: *u8 = slots[6] as *u8
  let grounds: *u8 = slots[7] as *u8
  // ---- field refusals, each named ------------------------------------------------------------
  var k2: i64 = 0
  while k2 < CC_SPEC_FIELDS { if cc_len(slots[k2] as *u8) == 0 { cc_puts("REFUSED-EMPTY-FIELD index=" as *u8); cc_putn(k2); cc_puts("\n" as *u8); return CC_EX_FIELD } k2 = k2 + 1 }
  k2 = 0
  while k2 < CC_SPEC_FIELDS { if cc_has_pipe(slots[k2] as *u8) == 1 { cc_puts("REFUSED-PIPE-IN-FIELD index=" as *u8); cc_putn(k2); cc_puts(" (the ref row has exactly 9 fields; a pipe in prose corrupts every reader)\n" as *u8); return CC_EX_FIELD } k2 = k2 + 1 }
  if cc_starts(url, "http" as *u8) == 0 { cc_puts("REFUSED-URL-NOT-HTTP\n" as *u8); return CC_EX_FIELD }
  // ---- the pin is COMPUTED from the mirror: absent mirror -> no citation ---------------------
  let mszp: *i64 = sys_mmap(16) as *i64
  let mb: *u8 = sys_read_file(mirror, mszp)
  if (mb as i64) == 0 { cc_puts("REFUSED-MIRROR-ABSENT mirror=" as *u8); cc_puts(mirror); cc_puts(" (fetch it with nx_research_fetch first -- a reference you did not fetch is a fabrication)\n" as *u8); return CC_EX_MIRROR }
  if mszp[0] <= 0 { cc_puts("REFUSED-MIRROR-EMPTY mirror=" as *u8); cc_puts(mirror); cc_puts("\n" as *u8); return CC_EX_MIRROR }
  let dig: *u8 = sys_mmap(32)
  sha256_digest(mb, mszp[0], dig)
  let pin: *u8 = sys_mmap(CC_HEX + 2)
  pin[0] = 104 as u8
  cc_hex(dig, ((pin as i64) + 1) as *u8)
  // ---- resolve both files in PUBLISHED order --------------------------------------------------
  let rpath: *u8 = sys_mmap(CC_PATHCAP)
  let rbp: *i64 = sys_mmap(16) as *i64
  let rn: i64 = cc_resolve(dom, CC_SUF_REFS, rpath, rbp)
  if rn < 0 { cc_puts("REFUSED-NO-REFS-FILE domain=" as *u8); cc_puts(dom); cc_puts(" (neither tree holds <dom>.refs)\n" as *u8); return CC_EX_TREE }
  let mpath: *u8 = sys_mmap(CC_PATHCAP)
  let mbp: *i64 = sys_mmap(16) as *i64
  let mn: i64 = cc_resolve(dom, CC_SUF_MATRIX, mpath, mbp)
  if mn < 0 { cc_puts("REFUSED-NO-MATRIX-FILE domain=" as *u8); cc_puts(dom); cc_puts("\n" as *u8); return CC_EX_TREE }
  let rbuf: *u8 = rbp[0] as *u8
  let mbuf: *u8 = mbp[0] as *u8
  // ---- is the key already declared? ----------------------------------------------------------
  let keypat: *u8 = sys_mmap(CC_ROWCAP)
  var ko: i64 = cc_cat(keypat, 0, "\nref|" as *u8)
  ko = cc_cat(keypat, ko, key)
  ko = cc_cat(keypat, ko, "|" as *u8)
  var key_present: i64 = 0
  if cc_find(rbuf, rn, keypat) >= 0 { key_present = 1 }
  if cc_starts(rbuf, ((keypat as i64) + 1) as *u8) == 1 { key_present = 1 }
  // ---- find EXACTLY ONE matrix row by label prefix --------------------------------------------
  let markpat: *u8 = sys_mmap(CC_ROWCAP)
  var mo: i64 = cc_cat(markpat, 0, "[@" as *u8)
  mo = cc_cat(markpat, mo, key)
  mo = cc_cat(markpat, mo, "]" as *u8)
  var matches: i64 = 0
  var row_start: i64 = 0 - 1
  var row_end: i64 = 0 - 1
  var mark_present: i64 = 0
  var i: i64 = 0
  while i < mn {
      var e: i64 = i
      var eol: i64 = 0
      while eol == 0 { if e >= mn { eol = 1 } else { if mbuf[e] == (CC_NL as u8) { eol = 1 } else { e = e + 1 } } }
      var isrow: i64 = 1
      if mbuf[i] == (CC_HASH as u8) { isrow = 0 }
      if mbuf[i] == (CC_ATSIGN as u8) { isrow = 0 }
      if e == i { isrow = 0 }
      if isrow == 1 {
          let saved: u8 = mbuf[e]
          mbuf[e] = 0 as u8
          if cc_starts(((mbuf as i64) + i) as *u8, label) == 1 {
              matches = matches + 1
              row_start = i
              row_end = e
              if cc_find(((mbuf as i64) + i) as *u8, e - i, markpat) >= 0 { mark_present = 1 }
          }
          mbuf[e] = saved
      }
      i = e + 1
  }
  if matches == 0 { cc_puts("REFUSED-ROW-NOT-FOUND label-prefix=" as *u8); cc_puts(label); cc_puts(" matrix=" as *u8); cc_puts(mpath); cc_puts("\n" as *u8); return CC_EX_ROW }
  if matches > 1 { cc_puts("REFUSED-ROW-AMBIGUOUS label-prefix=" as *u8); cc_puts(label); cc_puts(" matches=" as *u8); cc_putn(matches); cc_puts(" (lengthen the prefix until exactly one row answers)\n" as *u8); return CC_EX_ROW }
  if key_present == 1 { if mark_present == 1 {
      cc_puts("ALREADY-CITED domain=" as *u8); cc_puts(dom); cc_puts(" key=" as *u8); cc_puts(key); cc_puts(" (ref row present, mark present, nothing written)\n" as *u8)
      return 0
  } }
  // ---- hashes of what THIS run read = the compare-and-swap tokens ----------------------------
  let rhex: *u8 = sys_mmap(CC_HEX + 2)
  sha256_digest(rbuf, rn, dig)
  cc_hex(dig, rhex)
  let mhex: *u8 = sys_mmap(CC_HEX + 2)
  sha256_digest(mbuf, mn, dig)
  cc_hex(dig, mhex)
  let cap: *u8 = sys_mmap(CC_CAPCAP)
  let capn: *i64 = sys_mmap(16) as *i64
  let today: *u8 = sys_mmap(16)
  cc_civil_date(sys_now_realtime_sec(), today)
  var rc_refs: i64 = 0
  var newrn: i64 = rn
  if key_present == 0 {
      let row: *u8 = sys_mmap(CC_ROWCAP)
      var ro: i64 = cc_cat(row, 0, "ref|" as *u8)
      ro = cc_cat(row, ro, key); ro = cc_cat(row, ro, "|" as *u8)
      ro = cc_cat(row, ro, cite); ro = cc_cat(row, ro, "|" as *u8)
      ro = cc_cat(row, ro, url); ro = cc_cat(row, ro, "|" as *u8)
      ro = cc_cat(row, ro, mirror); ro = cc_cat(row, ro, "|" as *u8)
      ro = cc_cat(row, ro, pin); ro = cc_cat(row, ro, "|" as *u8)
      ro = cc_cat(row, ro, today); ro = cc_cat(row, ro, "|" as *u8)
      ro = cc_cat(row, ro, cls); ro = cc_cat(row, ro, "|" as *u8)
      ro = cc_cat(row, ro, grounds)
      row[ro] = CC_NL as u8
      ro = ro + 1
      if ro >= CC_ROWCAP - 2 { cc_puts("REFUSED-ROW-TOO-LONG bytes=" as *u8); cc_putn(ro); cc_puts("\n" as *u8); return CC_EX_FIELD }
      let nr: *u8 = sys_mmap(rn + ro + 2)
      var no: i64 = cc_catb(nr, 0, rbuf, rn)
      if rbuf[rn - 1] != (CC_NL as u8) { nr[no] = CC_NL as u8; no = no + 1 }
      no = cc_catb(nr, no, row, ro)
      newrn = no
      rc_refs = cc_publish(rpath, nr, no, rhex, cap, capn)
      if rc_refs != 0 {
          cc_puts("publish-refs rc=" as *u8); cc_putn(rc_refs); cc_puts(" capture=" as *u8); sys_write(1, cap, capn[0]); cc_puts("\nREFUSED-PUBLISH-REFS (nothing written: the compare-and-swap on " as *u8); cc_puts(rpath); cc_puts(" refused -- re-read and re-run)\n" as *u8)
          return CC_EX_PUB_REFS
      }
  }
  var rc_mark: i64 = 0
  var newmn: i64 = mn
  if mark_present == 0 {
      let markins: *u8 = sys_mmap(CC_ROWCAP)
      var mi: i64 = cc_cat(markins, 0, " " as *u8)
      mi = cc_cat(markins, mi, markpat)
      var cut: i64 = row_end
      if cut > row_start { if mbuf[cut - 1] == (CC_CR as u8) { cut = cut - 1 } }
      let nm: *u8 = sys_mmap(mn + mi + 2)
      var mo2: i64 = cc_catb(nm, 0, mbuf, cut)
      mo2 = cc_catb(nm, mo2, markins, mi)
      mo2 = cc_catb(nm, mo2, ((mbuf as i64) + cut) as *u8, mn - cut)
      newmn = mo2
      rc_mark = cc_publish(mpath, nm, mo2, mhex, cap, capn)
      if rc_mark != 0 {
          cc_puts("publish-mark rc=" as *u8); cc_putn(rc_mark); cc_puts(" capture=" as *u8); sys_write(1, cap, capn[0]); cc_puts("\n" as *u8)
          if key_present == 0 { cc_puts("PARTIAL-refs-published-mark-refused domain=" as *u8); cc_puts(dom); cc_puts(" key=" as *u8); cc_puts(key); cc_puts(" (the ref row landed; the gate will name it UNCITED until a re-run adds the mark -- re-run with the same arguments, this organ is idempotent)\n" as *u8) }
          else { cc_puts("REFUSED-PUBLISH-MARK domain=" as *u8); cc_puts(dom); cc_puts(" key=" as *u8); cc_puts(key); cc_puts("\n" as *u8) }
          return CC_EX_PUB_MARK
      }
  }
  cc_puts("CITED domain=" as *u8); cc_puts(dom); cc_puts(" key=" as *u8); cc_puts(key)
  cc_puts(" row=" as *u8); cc_puts(label)
  cc_puts(" pin=" as *u8); cc_puts(pin)
  cc_puts(" date=" as *u8); cc_puts(today)
  cc_puts(" refs=" as *u8); cc_puts(rpath); cc_puts(" refs_bytes=" as *u8); cc_putn(rn); cc_puts("->" as *u8); cc_putn(newrn); cc_puts(" ref_added=" as *u8); cc_putn(1 - key_present)
  cc_puts(" matrix=" as *u8); cc_puts(mpath); cc_puts(" matrix_bytes=" as *u8); cc_putn(mn); cc_puts("->" as *u8); cc_putn(newmn); cc_puts(" mark_added=" as *u8); cc_putn(1 - mark_present)
  cc_puts(" publish=nx_atomic_publish-cas\n" as *u8)
  return 0
345}
nx_compare_cite.nx source

`nx_compare_cite.nx` source
