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

↩ module page · 236 lines · 14645 B
1// nx_docstage_gate.nx -- THE REFEREE for nx_docstage (DM8, devmgmt rung).
2// END-TO-END: forks the DEPLOYED nx_docstage elf, so it grades the artifact callers run.
3//
4// The accept rule, verbatim from devmgmt.plan: "the stage reports DOCUMENTED or UNDOCUMENTED per ship
5// with ZERO false DOCUMENTED, measured against the symbols a session actually shipped."
6//
7// ZERO FALSE DOCUMENTED IS THE ONLY BAR THAT MATTERS HERE, so the fixture is built around the one way
8// this check goes wrong: a SUBSTRING match. `nx_dora_page` contains `nx_dora`, and a scanner that does
9// not test token boundaries reports the shipped symbol as written-down because a DIFFERENT symbol is
10// mentioned somewhere. That failure is invisible -- it produces a green, plausible, wrong answer -- so
11// the fixture carries all four boundary traps at once (`nx_dora_page`, `xnx_dora`, `_nx_dora`,
12// `nx_dorax`) with NO real token, and demands UNDOCUMENTED. The positive control sits in the same
13// gate: the same symbol, as a real token, must come back DOCUMENTED. A detector that answers
14// "documented" for everything fails the first; one that answers "undocumented" for everything fails
15// the second. Neither alone proves discrimination.
16//
17// The third state is tested too, because "I could not look" and "it is not written down" demand
18// opposite actions and only one of them is ever safe to act on.
19// Fixtures under /tmp/nx_docstage_gate/, rewritten O_TRUNC each run (idempotent).
20// license_tier: ORIGINAL  Read-only outside /tmp. No hw writes (Rule 26).
21import "nx_syscalls.nx"
22import "nx_sovjson_lib.nx"
23import "nx_gate_verdict.nx"
24import "nx_tool_run.nx"
25
26const DG_MODE_644: i64 = 420
27const DG_MODE_755: i64 = 493
28const DG_PATH: i64 = 512
29const DG_FIX: i64 = 65536
30const DG_OUT: i64 = 1048576
31const DG_EXIT_SKIP: i64 = 3
32const DG_RC_DOC: i64 = 0
33const DG_RC_UNDOC: i64 = 1
34const DG_RC_UNMEASURED: i64 = 3
35const DG_RC_USAGE: i64 = 2
36const DG_MANY: i64 = 30          // token occurrences planted to exceed the printed-list bound
37
38func dg_wr(path: *u8, buf: *u8, n: i64) -> i64 {
  let fd: i64 = sys_openat_wr(path, DG_MODE_644)
  if fd < 0 { return 0 - 1 }
  sys_write(fd, buf, n)
  sys_close(fd)
  return n
44}
45func dg_run(subj: *u8, a1: *u8, a2: *u8, out: *u8, cl: *i64) -> i64 {
  let av: *i64 = sys_mmap(64) as *i64
  av[0] = subj as i64
  av[1] = a1 as i64
  av[2] = a2 as i64
  av[3] = 0
  return tr_run_capture(subj, av, out, DG_OUT - 8, cl)
52}
53
54func main(argc: i64, argv: *i64) -> i64 {
  let ctr: *i64 = gv_ctr()
  gv_head("nx_docstage_gate -- a substring is not a symbol, and 'I could not look' is not 'not written down'" as *u8)
57
  let subj: *u8 = sys_mmap(DG_PATH)
  var have: i64 = 0
  if argc >= 2 { var z: i64 = sj_cat(subj, 0, argv[1] as *u8); subj[z] = 0 as u8; have = 1 }
  if have == 0 { if sj_allow_path("nx_docstage" as *u8, subj) == 1 { have = 1 } }
  if have == 0 { var z2: i64 = sj_cat(subj, 0, "./nx_docstage.elf" as *u8); subj[z2] = 0 as u8; have = 1 }
63
  let root: *u8 = "/tmp/nx_docstage_gate" as *u8
  let ddocs: *u8 = "/tmp/nx_docstage_gate/docs" as *u8
  let dsub: *u8 = "/tmp/nx_docstage_gate/docs/sub" as *u8
  let dtraps: *u8 = "/tmp/nx_docstage_gate/traps" as *u8
  let dmany: *u8 = "/tmp/nx_docstage_gate/many" as *u8
  let fa: *u8 = "/tmp/nx_docstage_gate/docs/a.matrix" as *u8
  let fb: *u8 = "/tmp/nx_docstage_gate/docs/sub/b.plan" as *u8
  let fc: *u8 = "/tmp/nx_docstage_gate/docs/c.txt" as *u8
  let ft: *u8 = "/tmp/nx_docstage_gate/traps/only_traps.matrix" as *u8
  let fm: *u8 = "/tmp/nx_docstage_gate/many/m.txt" as *u8
  let cgood: *u8 = "/tmp/nx_docstage_gate/roots.conf" as *u8
  let ctraps: *u8 = "/tmp/nx_docstage_gate/traps.conf" as *u8
  let cbad: *u8 = "/tmp/nx_docstage_gate/badroot.conf" as *u8
  let cmany: *u8 = "/tmp/nx_docstage_gate/many.conf" as *u8
  let cabsent: *u8 = "/tmp/nx_docstage_gate/there-is-no-conf-here.conf" as *u8
  let dbig: *u8 = "/tmp/nx_docstage_gate/big" as *u8
  let dbig2: *u8 = "/tmp/nx_docstage_gate/big2" as *u8
  let fbig: *u8 = "/tmp/nx_docstage_gate/big/over_budget.txt" as *u8
  let fbig2: *u8 = "/tmp/nx_docstage_gate/big2/over_budget.txt" as *u8
  let ftiny: *u8 = "/tmp/nx_docstage_gate/big2/under_budget.txt" as *u8
  let cbig: *u8 = "/tmp/nx_docstage_gate/big.conf" as *u8
  let cbig2: *u8 = "/tmp/nx_docstage_gate/big2.conf" as *u8
  let bsym: *u8 = "zz_big" as *u8
  let sym: *u8 = "nx_dora" as *u8
  let msym: *u8 = "zz_many" as *u8
  let empty: *u8 = "" as *u8
  sys_mkdir(root, DG_MODE_755)
  sys_mkdir(ddocs, DG_MODE_755)
  sys_mkdir(dsub, DG_MODE_755)
  sys_mkdir(dtraps, DG_MODE_755)
  sys_mkdir(dmany, DG_MODE_755)
95
  let b: *u8 = sys_mmap(DG_FIX)
  // the substring trap, alone in its file: a longer symbol that CONTAINS the queried one
  var o: i64 = sj_cat(b, 0, "row|organ|nx_dora_page|0|1|the page emitter, a DIFFERENT symbol\n" as *u8)
  let w1: i64 = dg_wr(fa, b, o)
  // the ONLY real token in the whole good-root tree, and it sits in a SUBDIRECTORY
  o = sj_cat(b, 0, "rung|D1|DORA on ship receipts|nx_dora|Organ|1|-\n" as *u8)
  let w2: i64 = dg_wr(fb, b, o)
  // the three boundary traps that are not the substring trap
  o = sj_cat(b, 0, "xnx_dora and _nx_dora and nx_dorax are all NOT the symbol\n" as *u8)
  let w3: i64 = dg_wr(fc, b, o)
  // a root that contains EVERY trap and no real token
  o = sj_cat(b, 0, "row|organ|nx_dora_page|0|1\nxnx_dora _nx_dora nx_dorax nx_dora_page\n" as *u8)
  let w4: i64 = dg_wr(ft, b, o)
  // more real tokens than the printed list can hold, so the prefix declaration has to fire
  o = 0
  var mi: i64 = 0
  while mi < DG_MANY { o = sj_cat(b, o, "zz_many\n" as *u8); mi = mi + 1 }
  let w5: i64 = dg_wr(fm, b, o)
  // confs: comments and blank lines must be ignored, not read as roots
  o = sj_cat(b, 0, "# doc roots for the gate fixture\n\n   \n/tmp/nx_docstage_gate/docs\n" as *u8)
  let w6: i64 = dg_wr(cgood, b, o)
  o = sj_cat(b, 0, "/tmp/nx_docstage_gate/traps\n" as *u8)
  let w7: i64 = dg_wr(ctraps, b, o)
  o = sj_cat(b, 0, "/tmp/nx_docstage_gate/this-root-does-not-exist\n" as *u8)
  let w8: i64 = dg_wr(cbad, b, o)
  o = sj_cat(b, 0, "/tmp/nx_docstage_gate/many\n" as *u8)
  let w9: i64 = dg_wr(cmany, b, o)
  // the work-budget fixture: a file OVER the declared budget that DOES carry a real token, so a
  // scanner that ignores the budget finds it and a scanner that honours it must say it could not look
  sys_mkdir(dbig, DG_MODE_755)
  sys_mkdir(dbig2, DG_MODE_755)
  o = sj_cat(b, 0, "zz_big is a real token in a file that exceeds the declared budget\n" as *u8)
  var pad: i64 = 0
  while pad < DG_MANY { o = sj_cat(b, o, "padpadpadpadpadpadpadpadpadpadpadpadpadpadpadpadpadpadpadpadpadpadpadpadpadpadpadpad\n" as *u8); pad = pad + 1 }
  let wA: i64 = dg_wr(fbig, b, o)
  let wB: i64 = dg_wr(fbig2, b, o)
  o = sj_cat(b, 0, "zz_big also appears here, under budget\n" as *u8)
  let wC: i64 = dg_wr(ftiny, b, o)
  o = sj_cat(b, 0, "# a corpus of prose needs a different budget from a corpus of media\nmax_file_bytes=1024\n/tmp/nx_docstage_gate/big\n" as *u8)
  let wD: i64 = dg_wr(cbig, b, o)
  o = sj_cat(b, 0, "max_file_bytes=1024\n/tmp/nx_docstage_gate/big2\n" as *u8)
  let wE: i64 = dg_wr(cbig2, b, o)
  sys_unlinkat(cabsent)
139
  var fixok: i64 = 0
  if w1 > 0 { if w2 > 0 { if w3 > 0 { if w4 > 0 { if w5 > 0 { if w6 > 0 { if w7 > 0 { if w8 > 0 { if w9 > 0 { if wA > 0 { if wB > 0 { if wC > 0 { if wD > 0 { if wE > 0 { fixok = 1 } } } } } } } } } } } } } }
  gv_check("fixture-written-all-nine (assert the fixture reached the condition before the outcome)" as *u8, fixok, ctr)
143
  let out: *u8 = sys_mmap(DG_OUT)
  let cl: *i64 = sys_mmap(16) as *i64
146
  // ---- positive control: the symbol IS a real token, in a subdirectory ----
  let rc1: i64 = dg_run(subj, sym, cgood, out, cl)
  let n1: i64 = cl[0]
  if n1 <= 0 {
      gv_puts("SKIP subject produced no output -- build/deploy nx_docstage, then re-run: " as *u8)
      gv_puts(subj)
      gv_puts("\n" as *u8)
      sys_exit(DG_EXIT_SKIP)
      return DG_EXIT_SKIP
  }
  gv_check("subject-examined-a-nonzero-population (a zero-file scan cannot judge documentation)" as *u8, tr_contains(out, n1, "files_scanned=3" as *u8), ctr)
  gv_check("pos-control-a-real-token-reports-DOCUMENTED" as *u8, tr_contains(out, n1, "verdict=DOCUMENTED hits=1 files_with_hits=1" as *u8), ctr)
  gv_check("pos-control-carries-exit-code-0-so-a-caller-can-branch" as *u8, 1 - rc1, ctr)
  gv_check("the-hit-is-NAMED-with-its-file-and-line-not-just-counted" as *u8, tr_contains(out, n1, "DOC-HIT /tmp/nx_docstage_gate/docs/sub/b.plan line=1" as *u8), ctr)
  gv_check("recursion-reached-the-subdirectory-that-holds-the-only-real-token" as *u8, tr_contains(out, n1, "docs/sub/b.plan" as *u8), ctr)
  gv_check("the-three-non-substring-boundary-traps-in-the-same-tree-are-NOT-counted" as *u8, tr_contains(out, n1, "hits=1 " as *u8), ctr)
  gv_check("coverage-is-declared-complete-on-a-fully-walked-tree" as *u8, tr_contains(out, n1, "coverage_complete=1 match=exact-token" as *u8), ctr)
  // EVERY assertion about a run lives BEFORE the next run: `out` is one reused buffer, so a tooth
  // written further down silently grades a LATER run's bytes under an earlier run's name. This gate
  // failed exactly that way on its first execution -- the tooth was correct and the subject was
  // correct, and the RED was mine.
  gv_check("conf-comments-and-blank-lines-are-not-read-as-roots" as *u8, tr_contains(out, n1, "roots_declared=1 roots_walked=1 roots_source=conf" as *u8), ctr)
169
  // ---- THE BAR: a root of nothing but look-alikes must NOT report DOCUMENTED ----
  let rc2: i64 = dg_run(subj, sym, ctraps, out, cl)
  let n2: i64 = cl[0]
  gv_check("ACCEPT-zero-false-DOCUMENTED-a-root-of-only-look-alikes-reports-UNDOCUMENTED" as *u8, tr_contains(out, n2, "verdict=UNDOCUMENTED hits=0" as *u8), ctr)
  var nfp: i64 = 1
  if tr_contains(out, n2, "DOC-HIT" as *u8) == 1 { nfp = 0 }
  gv_check("neg-control-no-hit-row-is-emitted-for-any-look-alike" as *u8, nfp, ctr)
  var rcok2: i64 = 0
  if rc2 == DG_RC_UNDOC { rcok2 = 1 }
  gv_check("UNDOCUMENTED-carries-its-own-exit-code-1-distinct-from-cannot-look" as *u8, rcok2, ctr)
  gv_check("UNDOCUMENTED-is-only-claimed-with-complete-coverage-behind-it" as *u8, tr_contains(out, n2, "verdict=UNDOCUMENTED hits=0 files_with_hits=0 files_scanned=1 coverage_complete=1" as *u8), ctr)
181
  // ---- the third state: cannot look is not an acquittal and not a conviction ----
  let rc3: i64 = dg_run(subj, sym, cbad, out, cl)
  let n3: i64 = cl[0]
  gv_check("neg-control-an-unwalkable-root-reports-UNMEASURED-never-UNDOCUMENTED" as *u8, tr_contains(out, n3, "verdict=UNMEASURED" as *u8), ctr)
  var rcok3: i64 = 0
  if rc3 == DG_RC_UNMEASURED { rcok3 = 1 }
  gv_check("UNMEASURED-carries-exit-3-so-a-caller-cannot-mistake-it-for-a-finding" as *u8, rcok3, ctr)
  gv_check("the-unwalkable-root-is-COUNTED-roots_declared-1-roots_walked-0" as *u8, tr_contains(out, n3, "roots_declared=1 roots_walked=0" as *u8), ctr)
190
  // ---- a capped LIST beside an uncapped COUNT must say so ----
  let rc4: i64 = dg_run(subj, msym, cmany, out, cl)
  let n4: i64 = cl[0]
  gv_check("the-full-count-is-reported-even-though-the-printed-list-is-bounded" as *u8, tr_contains(out, n4, "verdict=DOCUMENTED hits=30" as *u8), ctr)
  gv_check("and-the-bounded-list-DECLARES-itself-a-prefix-of-that-count" as *u8, tr_contains(out, n4, "PREFIX of its own count: shown=24 of hits=30" as *u8), ctr)
196
  // ---- config hierarchy: the code default is the lowest rung and it announces itself ----
  let rc5: i64 = dg_run(subj, sym, cabsent, out, cl)
  gv_check("an-absent-conf-falls-back-to-the-builtin-default-and-SAYS-SO" as *u8, tr_contains(out, cl[0], "roots_source=builtin-default" as *u8), ctr)
200
  // ---- the work budget: an unbounded scan of a real doc root NEVER RETURNED (measured on
  // knowledge/library, 7,627+ entries incl. mirrored video, zero bytes out, indistinguishable from a
  // crash). A bound is only legitimate if it ANNOUNCES, and if it costs the run its completeness. ----
  let rcA: i64 = dg_run(subj, bsym, cbig, out, cl)
  let nA: i64 = cl[0]
  gv_check("an-over-budget-file-is-SKIPPED-and-COUNTED-not-silently-read" as *u8, tr_contains(out, nA, "files_skipped_oversize=1" as *u8), ctr)
  gv_check("the-budget-and-WHERE-IT-CAME-FROM-are-printed-in-every-report" as *u8, tr_contains(out, nA, "max_file_bytes=1024 budget_source=conf" as *u8), ctr)
  gv_check("a-skipped-file-costs-the-run-its-completeness-claim" as *u8, tr_contains(out, nA, "coverage_complete=0" as *u8), ctr)
  gv_check("ACCEPT-partial-coverage-with-no-witness-is-UNMEASURED-never-UNDOCUMENTED" as *u8, tr_contains(out, nA, "verdict=UNMEASURED hits=0" as *u8), ctr)
  var rcokA: i64 = 0
  if rcA == DG_RC_UNMEASURED { rcokA = 1 }
  gv_check("and-it-exits-3-so-a-caller-cannot-read-a-skipped-corpus-as-a-finding" as *u8, rcokA, ctr)
  let rcB: i64 = dg_run(subj, bsym, cbig2, out, cl)
  let nB: i64 = cl[0]
  gv_check("ONE-WITNESS-IS-ENOUGH-a-hit-under-budget-yields-DOCUMENTED-despite-partial-coverage" as *u8, tr_contains(out, nB, "verdict=DOCUMENTED hits=1" as *u8), ctr)
  gv_check("and-that-DOCUMENTED-still-publishes-coverage_complete-0-rather-than-hiding-it" as *u8, tr_contains(out, nB, "files_skipped_oversize=1" as *u8), ctr)
  var rcokB: i64 = 0
  if rcB == DG_RC_DOC { rcokB = 1 }
  gv_check("presence-and-absence-do-not-need-the-same-evidence-and-the-exit-code-says-so" as *u8, rcokB, ctr)
220
  // ---- an empty needle matches every boundary: it must be refused, not answered ----
  let rc6: i64 = dg_run(subj, empty, cgood, out, cl)
  var rcok6: i64 = 0
  if rc6 == DG_RC_USAGE { if tr_contains(out, cl[0], "REFUSED empty symbol" as *u8) == 1 { rcok6 = 1 } }
  gv_check("neg-control-an-empty-symbol-is-REFUSED-not-reported-DOCUMENTED" as *u8, rcok6, ctr)
226
  // ---- idempotence ----
  let rc7: i64 = dg_run(subj, sym, cgood, out, cl)
  var idem: i64 = 0
  if rc7 == DG_RC_DOC { if tr_contains(out, cl[0], "verdict=DOCUMENTED hits=1 files_with_hits=1" as *u8) == 1 { idem = 1 } }
  gv_check("idempotent-a-second-run-on-the-same-fixture-grades-identically" as *u8, idem, ctr)
232
  let v: i64 = gv_verdict("DOCSTAGE-GATE" as *u8, ctr, "documentation is judged on exact tokens, absence is claimed only with complete coverage, and cannot-look is its own third state" as *u8)
  sys_exit(v)
  return v
236}
nx_docstage_gate.nx source

`nx_docstage_gate.nx` source
