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

1// nx_arbiter_gate.nx -- proves the arbitration primitive (nx_arbiter): a kernel-enforced exclusive lock
2// serializes concurrent writers on a shared resource. Asserts: acquire succeeds; while held, a second
3// independent try is DENIED (mutual exclusion); after release the lock is free again; the lock file lives under
4// the stable shared LOCKDIR (not /tmp). Uses a PER-WORKSTREAM test resource (via NISHI_WSID) so concurrent
5// sibling gate runs in the 21-workstream fleet don't contend on the same test lock. GREEN iff all 5 pass. license_tier: ORIGINAL
6import "nx_syscalls.nx"
7import "nx_arbiter.nx"
8import "nx_runpath.nx"
9import "nx_gate_verdict.nx"   // D001: inherit the verdict contract instead of re-emitting its strings
10import "nx_lease.nx"          // ls_pid(): make the test resource unique per RUN, not just per workstream
11
12func g_w(s: *u8) -> i64 { var n: i64=0; while s[n]!=(0 as u8){n=n+1} sys_write(1,s,n); return 0 }
13func g_starts(a: *u8, b: *u8) -> i64 { var i: i64=0; while b[i]!=(0 as u8){ if a[i]!=b[i]{return 0} i=i+1 } return 1 }
14func g_row(id: *u8, ok: i64, pass: *i64) -> i64 { g_w(" "); g_w(id); g_w(": "); if ok==1 { g_w("OK\n"); pass[0]=pass[0]+1 } else { g_w("FAIL\n") } return 0 }
15
16func main() -> i64 {
  let pass: *i64 = sys_mmap(8) as *i64; pass[0] = 0
  g_w("=== NX-ARBITER GATE (kernel-enforced arbitration on shared sinks) ===\n")
19
  // per-workstream test resource: "nxarb_test_<wsid>"
  let wsid: *u8 = sys_mmap(64); rp_wsid(wsid)
  let res: *u8 = sys_mmap(128); var o: i64 = 0; var i: i64 = 0
  let pfx: *u8 = "nxarb_test_"; while pfx[i]!=(0 as u8){ res[o]=pfx[i]; o=o+1; i=i+1 }
  i=0; while wsid[i]!=(0 as u8){ res[o]=wsid[i]; o=o+1; i=i+1 }
  // ---- PER-PROCESS, NOT JUST PER-WORKSTREAM (2026-08-01) ----
  // The wsid suffix above was added so sibling gate runs across the 21-workstream fleet would not
  // contend on one test lock. It does not cover TWO RUNS IN THE SAME WORKSTREAM, and that case is not
  // hypothetical: the mutation probe runs this gate repeatedly, and a hand run alongside it scored 4/6
  // -- the two rows that must ACQUIRE the lock failed while exclusion and bounded-wait still passed.
  // Those failures were a RACE ARTIFACT, not a defect in nx_arbiter, and they are indistinguishable
  // from a real regression in the log. A gate whose result depends on who else is running is not a
  // measurement.
  // LAW: A GATE THAT TESTS EXCLUSION MUST OWN A RESOURCE NOBODY ELSE CAN CLAIM -- otherwise it tests
  // the scheduler, not the primitive. Appending the pid makes the resource unique per RUN, which is
  // what hermetic means here. Cross-run contention was never this gate's subject.
  res[o]=45 as u8; o=o+1                       // '-'
  var pidv: i64 = ls_pid()
  let pdt: *u8 = sys_mmap(24); var pk: i64 = 0
  if pidv==0 { pdt[0]=48 as u8; pk=1 }
  while pidv>0 { pdt[pk]=(48+(pidv%10)) as u8; pidv=pidv/10; pk=pk+1 }
  var pz: i64 = 0
  while pz<pk { res[o]=pdt[pk-1-pz]; o=o+1; pz=pz+1 }
  res[o]=0 as u8
44
  let fd1: i64 = fl_acquire(res, 10, 50)
  g_row("acquire the lock (bounded wait)" as *u8, (fd1 >= 0) as i64, pass)
47
  // while held, an independent try MUST be denied -> mutual exclusion
  let fd2: i64 = fl_try(res)
  g_row("MUTUAL EXCLUSION: second try denied while held" as *u8, (fd2 == (0 - 1)) as i64, pass)
51
  // ---- MUTATION-DERIVED TOOTH: THE BOUNDED-WAIT RETRY PATH (2026-08-01, debt 1785604588) ----
  // nx_gate_mutation_probe scored this pair 3/4 with a survivor at nx_arbiter.nx:54 -- the ` + ` in
  // `i = i + 1`, the RETRY COUNTER of fl_acquire's bounded-wait loop. It survived because every call
  // above acquires an UNCONTENDED lock: fl_try succeeds on the first iteration and returns, so the
  // loop body never executes and the counter is never used. The timeout path -- the entire reason
  // fl_acquire exists rather than fl_try -- was untested.
  // Running it against a HELD lock is the only way to reach that code: fl_try must fail `tries` times
  // and the loop must then EXIT. With the counter mutated the loop cannot terminate (i decrements, so
  // `i < tries` stays true forever) and the gate hangs instead of returning -- which the probe's run
  // deadline converts into a non-zero rc. Either way the mutant dies; only correct code returns -1.
  // LAW: A BOUNDED-WAIT LOOP IS ONLY TESTED UNDER CONTENTION. Acquiring a free lock exercises the
  // fast path and nothing else, so a retry/backoff/timeout bug ships invisibly.
  // tries=3 nap=10ms keeps this under ~30ms; the deliberate cost is that the gate now blocks briefly.
  let fd_to: i64 = fl_acquire(res, 3, 10)
  g_row("BOUNDED WAIT: acquire against a HELD lock exhausts its retries and TIMES OUT" as *u8, (fd_to == (0 - 1)) as i64, pass)
  if fd_to >= 0 { fl_release(fd_to) }
68
  fl_release(fd1)
70
  // after release, the lock is free again
  let fd3: i64 = fl_try(res)
  g_row("lock is free again after release" as *u8, (fd3 >= 0) as i64, pass)
  fl_release(fd3)
75
  // lock file is under the stable shared LOCKDIR, not /tmp
  let lp: *u8 = sys_mmap(512); fl_path(res, lp)
  g_row("lock under /home/.../.nishi/locks (stable, shared)" as *u8, g_starts(lp, "/home/elderwesto/.nishi/locks/" as *u8), pass)
  g_row("LIAR-KILL: lock is NOT under /tmp" as *u8, (g_starts(lp, "/tmp" as *u8) == 0) as i64, pass)
80
  // rows 5 -> 6 in LOCKSTEP with the tooth added above. Adding a row without moving this total is the
  // half-landed-pair defect: every row would pass and the gate would still report RED.
  // D001 MIGRATE-ON-TOUCH, BY HAND. nx_gate_dry_apply SKIPPED this gate: its counter is
  // POINTER-INDEXED (`pass[0] == 6`, from an mmap'd slot) and shape F's operand scanner reads bare
  // identifiers, so `pass[0]` does not match. Widening that scanner to accept bracket subscripts for
  // ONE file would trade a known-safe bound for an unknown one across ~200 other gates -- the same
  // call made for nx_singleness_gate. The bound stays; the author migrates his own gate.
  let ctr: *i64 = gv_ctr()
  ctr[0] = pass[0]
  ctr[1] = 6
  let rc: i64 = gv_verdict("ARBITER-GATE" as *u8, ctr, "kernel-enforced arbitration: exclusion, bounded-wait timeout, release, stable lockdir" as *u8)
  sys_exit(rc)
  return rc
94}
nx_arbiter_gate.nx source

`nx_arbiter_gate.nx` source
