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

↩ module page · 222 lines · 13983 B
1// nx_forkfresh_gate.nx -- THE REFEREE FOR FORK FRESHNESS (nx_forkfresh_lib), 2026-08-31.
2//
3// IN-PROCESS over nx_forkfresh_lib.nx, deliberately. Nothing can import a main(), and a gate that
4// fork/execs the deployed nx_compare_regen.elf reports NOT-REACHED for every mutant -- its GREEN would
5// prove nothing about the code under test. organ_gate.conf carries that reasoning five times over.
6//
7// SCOPE, STATED SO IT CANNOT BE OVER-READ: this proves the DECISION CORE -- path derivation, the digest
8// ruler, the four-state classification and the abstention contract. It does NOT prove the nx_compare_regen
9// emit loop, its watchlist pass or its census; those stay unreferee'd and are the next rung, not a claim
10// being made here.
11//
12// FIXTURES LIVE IN /tmp/nx_forkfresh_gate/ AND NEVER IN knowledge/store/: a gate that shares its fixture
13// with a production beat reports on the fixture, not on the code (measured estate-wide, ratcheted).
14// Setup truncate-writes every fixture it needs on every run, and the two ABSENT fixtures are absent BY
15// CONSTRUCTION -- they are paths this gate never creates -- so the run is idempotent without a teardown.
16// A gate that is not idempotent reports on its first run and lies about every run after.
17// license_tier: ORIGINAL   No hw writes (Rule 26).   expect_exit: 0
18import "nx_gate_verdict.nx"
19import "nx_forkfresh_lib.nx"
20
21const FG_DIR: *u8 = "/tmp/nx_forkfresh_gate"
22const FG_MODE_DIR: i64 = 493             // 0755
23const FG_MODE_FILE: i64 = 420            // 0644
24const FG_BODY_BYTES: i64 = 4096
25const FG_SUBJECTS: i64 = 5               // the five fixture pairs this gate classifies
26const FG_ABC_LEN: i64 = 3
27const FG_FILLER: i64 = 65                // ASCII A -- fixture body filler
28const FG_MUTANT: i64 = 66                // ASCII B -- the ONE byte that differs at equal size
29const FG_MUT_AT: i64 = 2048              // mid-body, so neither a header nor a tail special case
30const FG_SETUP_FILES: i64 = 7
31// Two DISTINCT sizes for the direction teeth. Their only property that matters is SMALL < LARGE, so they
32// are named for the role they play rather than left as bare numbers a reader would have to compare.
33const FG_DIR_SMALL: i64 = 1024
34const FG_DIR_LARGE: i64 = 4096
35
36func fg_write(path: *u8, buf: *u8, n: i64) -> i64 {
  let fd: i64 = sys_openat_wr(path, FG_MODE_FILE)
  if fd < 0 { return 0 }
  var w: i64 = 0
  while w < n {
      let k: i64 = sys_write(fd, ((buf as i64) + w) as *u8, n - w)
      if k <= 0 { w = n } else { w = w + k }
  }
  sys_close(fd)
  return 1
46}
47
48func fg_streq(a: *u8, b: *u8) -> i64 {
  var i: i64 = 0
  while a[i] != (0 as u8) {
      if a[i] != b[i] { return 0 }
      i = i + 1
  }
  if b[i] != (0 as u8) { return 0 }
  return 1
56}
57
58func main(argc: i64, argv: *i64) -> i64 {
  gv_head("nx_forkfresh_gate -- the fork-freshness decision core, in-process" as *u8)
  let ctr: *i64 = gv_ctr()
  gv_subjects("fixture pairs classified" as *u8, FG_SUBJECTS, ctr)
62
  sys_mkdir(FG_DIR, FG_MODE_DIR)
  sys_mkdir("/tmp/nx_forkfresh_gate/_offc" as *u8, FG_MODE_DIR)
65
  let body: *u8 = sys_mmap(FG_BODY_BYTES)
  var i: i64 = 0
  while i < FG_BODY_BYTES { body[i] = FG_FILLER as u8; i = i + 1 }
  let mutant: *u8 = sys_mmap(FG_BODY_BYTES)
  i = 0
  while i < FG_BODY_BYTES { mutant[i] = FG_FILLER as u8; i = i + 1 }
  mutant[FG_MUT_AT] = FG_MUTANT as u8
73
  let f_same: *u8 = "/tmp/nx_forkfresh_gate/_offc/gen_same.elf"
  let r_same: *u8 = "/tmp/nx_forkfresh_gate/gen_same.elf"
  let f_diff: *u8 = "/tmp/nx_forkfresh_gate/_offc/gen_diff.elf"
  let r_diff: *u8 = "/tmp/nx_forkfresh_gate/gen_diff.elf"
  let f_noref: *u8 = "/tmp/nx_forkfresh_gate/_offc/gen_noref.elf"
  let r_noref: *u8 = "/tmp/nx_forkfresh_gate/gen_noref_NEVER_CREATED.elf"
  let f_gone: *u8 = "/tmp/nx_forkfresh_gate/_offc/gen_NEVER_CREATED.elf"
  let f_empty: *u8 = "/tmp/nx_forkfresh_gate/_offc/gen_empty.elf"
  let r_empty: *u8 = "/tmp/nx_forkfresh_gate/gen_empty.elf"
83
  var wrote: i64 = 0
  wrote = wrote + fg_write(f_same, body, FG_BODY_BYTES)
  wrote = wrote + fg_write(r_same, body, FG_BODY_BYTES)
  wrote = wrote + fg_write(f_diff, mutant, FG_BODY_BYTES)
  wrote = wrote + fg_write(r_diff, body, FG_BODY_BYTES)
  wrote = wrote + fg_write(f_noref, body, FG_BODY_BYTES)
  wrote = wrote + fg_write(f_empty, body, 0)
  wrote = wrote + fg_write(r_empty, body, 0)
92
  // ASSERT THE FIXTURE REACHED THE CONDITION BEFORE ASSERTING THE OUTCOME. Every tooth below is a
  // claim about files this run wrote; if setup silently failed, each one would pass or fail for a
  // reason that has nothing to do with the code under test.
  gv_check("fixture-setup-wrote-every-declared-file" as *u8, wrote == FG_SETUP_FILES, ctr)
97
  let fd0: *u8 = sys_mmap(FF_DIGEST_BYTES)
  let rd0: *u8 = sys_mmap(FF_DIGEST_BYTES)
  let sz: *i64 = sys_mmap(FF_SIZES_SLOTS * 8) as *i64
  var classified: i64 = 0
102
  let s_same: i64 = ff_classify(f_same, r_same, fd0, rd0, sz)
  classified = classified + 1
  gv_check("identical-bytes-read-FORK-FRESH" as *u8, s_same == FF_FRESH, ctr)
  gv_check("fresh-reports-both-sizes-measured" as *u8, sz[0] == FG_BODY_BYTES, ctr)
107
  // THE LOAD-BEARING TOOTH: same size, one byte apart -> STALE.
  // A SIZE COMPARISON CANNOT SEE THIS, AND A SIZE COMPARISON IS WHAT THE ESTATE KEPT REACHING FOR.
  // The equal-size assertion runs FIRST and on the SAME classification, so this can never pass by
  // accidentally comparing two differently-sized files.
  let s_diff: i64 = ff_classify(f_diff, r_diff, fd0, rd0, sz)
  classified = classified + 1
  gv_check("fixture-reached-condition-equal-sizes" as *u8, sz[0] == sz[1], ctr)
  gv_check("fixture-reached-condition-sizes-nonzero" as *u8, sz[0] == FG_BODY_BYTES, ctr)
  gv_check("same-size-differing-content-reads-FORK-STALE" as *u8, s_diff == FF_STALE, ctr)
117
  let s_nr: i64 = ff_classify(f_noref, r_noref, fd0, rd0, sz)
  classified = classified + 1
  gv_check("absent-reference-reads-FORK-UNPROVEN" as *u8, s_nr == FF_UNPROVEN, ctr)
  gv_check("neg-control-absent-reference-is-not-STALE" as *u8, s_nr != FF_STALE, ctr)
  gv_check("neg-control-absent-reference-is-not-FRESH" as *u8, s_nr != FF_FRESH, ctr)
  // NEVER PRINT A FABRICATED SIZE BESIDE AN ABSTENTION.
  gv_check("unmeasured-reference-size-stays-minus-one" as *u8, sz[1] == (0 - 1), ctr)
125
  let s_gone: i64 = ff_classify(f_gone, r_same, fd0, rd0, sz)
  classified = classified + 1
  gv_check("absent-fork-target-reads-FORK-ABSENT" as *u8, s_gone == FF_NOFORK, ctr)
  gv_check("neg-control-two-absences-are-distinguishable" as *u8, s_gone != s_nr, ctr)
130
  // Two zero-byte files digest IDENTICALLY. A classifier that trusted the digest alone would call a
  // pair of empty stubs FRESH and clear a build tree that contains nothing at all.
  let s_empty: i64 = ff_classify(f_empty, r_empty, fd0, rd0, sz)
  classified = classified + 1
  gv_check("neg-control-empty-pair-does-not-read-FRESH" as *u8, s_empty != FF_FRESH, ctr)
  gv_check("empty-pair-reads-FORK-ABSENT" as *u8, s_empty == FF_NOFORK, ctr)
137
  // BIND THE AGGREGATE TO ITS DENOMINATOR: a tooth that passes because it examined zero subjects is
  // not a tooth. This asserts the classifier was actually driven FG_SUBJECTS times.
  gv_check("denominator-every-declared-subject-was-classified" as *u8, classified == FG_SUBJECTS, ctr)
141
  gv_check("only-STALE-is-actionable" as *u8, ff_is_actionable(FF_STALE) == 1, ctr)
  gv_check("neg-control-UNPROVEN-is-not-actionable" as *u8, ff_is_actionable(FF_UNPROVEN) == 0, ctr)
  gv_check("neg-control-ABSENT-is-not-actionable" as *u8, ff_is_actionable(FF_NOFORK) == 0, ctr)
  gv_check("neg-control-FRESH-is-not-actionable" as *u8, ff_is_actionable(FF_FRESH) == 0, ctr)
146
  let pbuf: *u8 = sys_mmap(FF_PATH_BYTES)
  ff_promoted_path("_offc/nx_swcompare_matrix.elf" as *u8, pbuf, "../" as *u8)
  gv_check("promoted-path-derives-parent-plus-basename" as *u8, fg_streq(pbuf, "../nx_swcompare_matrix.elf" as *u8), ctr)
  ff_promoted_path("nx_gen.elf" as *u8, pbuf, "../" as *u8)
  gv_check("promoted-path-handles-a-bare-basename" as *u8, fg_streq(pbuf, "../nx_gen.elf" as *u8), ctr)
  ff_promoted_path("a/b/c/deep.elf" as *u8, pbuf, "" as *u8)
  gv_check("promoted-path-flattens-every-segment" as *u8, fg_streq(pbuf, "deep.elf" as *u8), ctr)
  // neg-control: a derivation that simply echoed its input would pass a laxer test than the ones above.
  ff_promoted_path("_offc/nx_swcompare_matrix.elf" as *u8, pbuf, "../" as *u8)
  gv_check("neg-control-derivation-is-not-an-echo" as *u8, fg_streq(pbuf, "_offc/nx_swcompare_matrix.elf" as *u8) == 0, ctr)
157
  // THE RULER ITSELF, against a PUBLISHED external vector (FIPS 180-4 NIST SHA-256 of abc).
  // This is the tooth that makes the digest field cross-checkable: the same value nx_filehash prints.
  let kd: *u8 = sys_mmap(FF_DIGEST_BYTES)
  let kh: *u8 = sys_mmap(FF_HEX_BYTES)
  sha256_digest("abc" as *u8, FG_ABC_LEN, kd)
  ff_hex(kd, kh, FF_DIGEST_BYTES)
  gv_check("sha256-hex-matches-the-published-NIST-abc-vector" as *u8, fg_streq(kh, "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad" as *u8), ctr)
  // neg-control: a renderer that returned a constant would pass the vector tooth above forever.
  let kd2: *u8 = sys_mmap(FF_DIGEST_BYTES)
  let kh2: *u8 = sys_mmap(FF_HEX_BYTES)
  sha256_digest("abd" as *u8, FG_ABC_LEN, kd2)
  ff_hex(kd2, kh2, FF_DIGEST_BYTES)
  gv_check("neg-control-hex-of-a-different-input-differs" as *u8, fg_streq(kh, kh2) == 0, ctr)
  gv_check("hex-renders-full-digest-width" as *u8, ff_hex(kd, kh, FF_DIGEST_BYTES) == (FF_DIGEST_BYTES * 2), ctr)
172
  gv_check("state-words-are-distinct-per-state" as *u8, fg_streq(ff_state_word(FF_FRESH), ff_state_word(FF_STALE)) == 0, ctr)
174
  // ===== THE STALE DIRECTION, AND WHICH REMEDY IT MAKES SAFE =====================================
  // A fork can differ from the promoted artifact in two directions that want OPPOSITE actions, and the
  // consumer printed ONE remedy for both. These teeth pin the direction AND the safety predicate,
  // because the failure that motivated them was not a wrong classification -- it was a CORRECT
  // classification followed by the destructive remedy.
  let dsz: *i64 = sys_mmap(FF_SIZES_SLOTS * 8) as *i64
  dsz[0] = FG_DIR_SMALL; dsz[1] = FG_DIR_LARGE
  gv_check("smaller-fork-reads-FORK-BEHIND" as *u8, ff_direction(FF_STALE, dsz) == FF_DIR_BEHIND, ctr)
  dsz[0] = FG_DIR_LARGE; dsz[1] = FG_DIR_SMALL
  gv_check("larger-fork-reads-FORK-AHEAD" as *u8, ff_direction(FF_STALE, dsz) == FF_DIR_AHEAD, ctr)
  dsz[0] = FG_DIR_LARGE; dsz[1] = FG_DIR_LARGE
  gv_check("equal-sizes-read-FORK-DIVERGED-SAME-SIZE" as *u8, ff_direction(FF_STALE, dsz) == FF_DIR_UNDECIDED, ctr)
187
  // A DIRECTION ONLY EXISTS FOR A PAIR ALREADY PROVEN TO DIFFER. Deriving one for a FRESH pair would
  // invent a remedy for an artifact that needs none, and for an ABSTENTION it would fabricate a finding.
  dsz[0] = FG_DIR_SMALL; dsz[1] = FG_DIR_LARGE
  gv_check("neg-control-a-FRESH-pair-has-no-direction" as *u8, ff_direction(FF_FRESH, dsz) == FF_DIR_NA, ctr)
  gv_check("neg-control-an-UNPROVEN-pair-has-no-direction" as *u8, ff_direction(FF_UNPROVEN, dsz) == FF_DIR_NA, ctr)
  gv_check("neg-control-an-ABSENT-pair-has-no-direction" as *u8, ff_direction(FF_NOFORK, dsz) == FF_DIR_NA, ctr)
194
  // NEVER FABRICATE A DIRECTION FROM AN UNMEASURED SIZE -- the same law the -1 size slots already carry.
  dsz[0] = 0 - 1; dsz[1] = FG_DIR_LARGE
  gv_check("neg-control-unmeasured-fork-size-yields-no-direction" as *u8, ff_direction(FF_STALE, dsz) == FF_DIR_NA, ctr)
  dsz[0] = FG_DIR_LARGE; dsz[1] = 0 - 1
  gv_check("neg-control-unmeasured-promoted-size-yields-no-direction" as *u8, ff_direction(FF_STALE, dsz) == FF_DIR_NA, ctr)
200
  // THE LOAD-BEARING TEETH: restage is safe for exactly ONE direction. The shipped defect answered YES
  // for all of them, so a predicate that returned 1 everywhere would still pass the BEHIND tooth alone --
  // the three refusals below are what make this a test rather than a restatement.
  gv_check("restage-is-safe-for-a-fork-that-is-BEHIND" as *u8, ff_restage_is_safe(FF_DIR_BEHIND) == 1, ctr)
  gv_check("neg-control-restage-is-NOT-safe-for-a-fork-that-is-AHEAD" as *u8, ff_restage_is_safe(FF_DIR_AHEAD) == 0, ctr)
  gv_check("neg-control-restage-is-NOT-safe-when-UNDECIDED" as *u8, ff_restage_is_safe(FF_DIR_UNDECIDED) == 0, ctr)
  gv_check("neg-control-restage-is-NOT-safe-with-no-direction" as *u8, ff_restage_is_safe(FF_DIR_NA) == 0, ctr)
208
  // BIND THE DIRECTION TO THE REAL CLASSIFIER, NOT ONLY TO HAND-BUILT ARRAYS. The equal-size differing
  // pair is the estate's own blind spot; re-classifying it here proves the two functions compose on a
  // REAL measurement rather than on numbers this gate typed for itself.
  let s_dir: i64 = ff_classify(f_diff, r_diff, fd0, rd0, sz)
  gv_check("fixture-reached-condition-real-pair-is-STALE" as *u8, s_dir == FF_STALE, ctr)
  gv_check("fixture-reached-condition-real-pair-sizes-equal" as *u8, sz[0] == sz[1], ctr)
  gv_check("real-same-size-stale-pair-is-UNDECIDED-not-a-guess" as *u8, ff_direction(s_dir, sz) == FF_DIR_UNDECIDED, ctr)
  gv_check("real-same-size-stale-pair-does-NOT-authorise-restage" as *u8, ff_restage_is_safe(ff_direction(s_dir, sz)) == 0, ctr)
217
  gv_check("direction-words-are-distinct-per-direction" as *u8, fg_streq(ff_direction_word(FF_DIR_BEHIND), ff_direction_word(FF_DIR_AHEAD)) == 0, ctr)
  gv_check("neg-control-a-direction-word-is-not-a-state-word" as *u8, fg_streq(ff_direction_word(FF_DIR_AHEAD), ff_state_word(FF_STALE)) == 0, ctr)
220
  return gv_verdict("nx_forkfresh_gate" as *u8, ctr, "in-process over nx_forkfresh_lib: derivation, the digest ruler against a published vector, the four-state classification and the abstention contract" as *u8)
222}
nx_forkfresh_gate.nx source

`nx_forkfresh_gate.nx` source
