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

↩ module page · 256 lines · 17503 B
1// nx_replyreserve_gate.nx -- GATE for the reply-reserve calibrator. Composes nx_replyreserve_lib and
2// nx_loadceil_lib IN-PROCESS on PLANTED buffers, so every value is asserted with no real actlog and no
3// forked binary. One real file is written, to a uniquely-named /tmp path this gate alone uses, because the
4// tail-read tooth cannot be proven on a buffer -- it is a claim about lseek and a file.
5//
6// THE LOAD-BEARING TOOTH is not "a number came out". It is the pair that would let the trivial wrong
7// implementation pass: a row on the right lane that carries NO reply_ms must count as MISSING, never as a
8// zero sample. A collector that read an absent key as 0 would flood the distribution with zeros, drive the
9// quantile to 0, and derive the floor -- a confident, wrong, and permanently-stable answer. The fixture
10// carries 25 such rows and the gate asserts both the missing count AND that the minimum is not 0.
11//
12// NEG-CONTROLS: a reply_ms on a DIFFERENT lane must not enter the sample; too few samples must abstain and
13// derive nothing; an empty buffer must be UNREADABLE and not a zero reserve; a reserve that reaches the
14// window or the fraction cap must be REFUSED with the current value kept; a conf with no reserve row must
15// refuse the rewrite rather than append a second row; and the whole-buffer conf reader must be shown to
16// FAIL on the real conf shape, which is why the line-anchored one exists.
17
18import "nx_syscalls.nx"
19import "nx_gate_verdict.nx"
20import "nx_replyreserve_lib.nx"
21
22const VRR_FIX: *u8 = "/tmp/nx_replyreserve_gate_tail.fixture" as *u8
23const VRR_SMALLCAP: i64 = 4096
24// A prime, coprime to both fixture sizes, so (i * stride) % n walks each residue exactly once: the
25// values arrive SHUFFLED while remaining the same SET. Named for its purpose, never for its value.
26const VRR_SHUFFLE_STRIDE: i64 = 7919
27
28// one actlog-shaped row. want_reply<0 emits NO reply_ms field at all.
29func vrr_row(b: *u8, o0: i64, lane: *u8, want_reply: i64) -> i64 {
  var o: i64 = rr_cat(b, o0, "1787665203\tmcp\tnx_compare_rank\tcall\tstarted\ttools/call lane=" as *u8)
  o = rr_cat(b, o, lane)
  o = rr_cat(b, o, " exit=0 bytes=4271 dur_ms=14013 job=1787665200" as *u8)
  if want_reply >= 0 {
      o = rr_cat(b, o, " reply_ms=" as *u8)
      o = rr_catn(b, o, want_reply)
  }
  b[o] = LC_NL as u8
  return o + 1
39}
40// The main fixture: `n` sync-promoted rows whose reply_ms values are a PERMUTATION of base..base+n-1,
41// `decoys` rows on a DIFFERENT lane carrying a huge reply_ms, and `bare` sync-promoted rows carrying no
42// reply_ms at all.
43// THE VALUES ARE DELIBERATELY OUT OF ORDER. 7919 is prime and coprime to both fixture sizes, so
44// (i*7919)%n walks every residue exactly once: the same value SET, arriving shuffled. An ASCENDING
45// fixture is what let a broken insertion sort pass the incumbent's gate for a day -- every quantile above
46// index 0 was still right by luck. A sort test whose input is already sorted is not a sort test.
47func vrr_fixture(b: *u8, base: i64, n: i64, decoys: i64, bare: i64, decoyval: i64) -> i64 {
  var o: i64 = 0
  var i: i64 = 0
  while i < n { o = vrr_row(b, o, "sync-promoted" as *u8, base + ((i * VRR_SHUFFLE_STRIDE) % n)); i = i + 1 }
  i = 0
  while i < decoys { o = vrr_row(b, o, "sync" as *u8, decoyval); i = i + 1 }
  i = 0
  while i < bare { o = vrr_row(b, o, "sync-promoted" as *u8, 0 - 1); i = i + 1 }
  b[o] = 0 as u8
  return o
57}
58// A synthetic edge_window.conf with the real file's hazard: BOTH keys are named in PROSE above their rows.
59func vrr_conf(b: *u8, with_reserve_row: i64) -> i64 {
  var o: i64 = rr_cat(b, 0, "" as *u8)
  o = rr_cline(b, o, "edge_window.conf test fixture" as *u8)
  o = rr_cline(b, o, "the sync lane promotes at (edge_window_ms - reply_reserve_ms), never at the window" as *u8)
  o = rr_cat(b, o, "edge_window_ms 15000" as *u8); b[o] = LC_NL as u8; o = o + 1
  b[o] = LC_NL as u8; o = o + 1
  o = rr_cline(b, o, "STALE-PARAGRAPH-MARKER: reply_reserve_ms=7777 was the old spelling" as *u8)
  o = rr_cline(b, o, "1000 is INHERITED from the compiled pair, not measured" as *u8)
  if with_reserve_row == 1 {
      o = rr_cat(b, o, "reply_reserve_ms 1000" as *u8); b[o] = LC_NL as u8; o = o + 1
  }
  b[o] = 0 as u8
  return o
72}
73
74func main() -> i64 {
  let c: *i64 = gv_ctr()
  gv_head("NX-REPLYRESERVE-GATE -- derive edge_window.conf reply_reserve_ms from measured reply_ms" as *u8)
77
  let buf: *u8 = sys_mmap(1 << 20)
  let out: *i64 = sys_mmap(RR_O_SLOTS * 8) as *i64
80
  // 300 samples 100..399 + 40 other-lane decoys at 99999 + 25 bare sync-promoted rows.
  let n: i64 = vrr_fixture(buf, 100, 300, 40, 25, 99999)
  gv_puts("  fixture bytes=" as *u8); gv_num(n); gv_puts(" (300 sync-promoted 100..399, 40 lane=sync at 99999, 25 sync-promoted with NO reply_ms)\n" as *u8)
  gv_subjects("fixture-bytes" as *u8, n, c)
  gv_check("fixture-reached-the-condition-a-non-empty-planted-log" as *u8, n > 10000, c)
86
  // q=990 minn=200 margin=2000 floor=250 maxpermil=100 window=15000 current=1000
  let v: i64 = rr_derive(buf, n, 990, 200, 2000, 250, 100, 15000, 1000, out)
  gv_puts("  verdict=" as *u8); gv_num(v)
  gv_puts(" samples=" as *u8); gv_num(out[RR_O_N])
  gv_puts(" lines=" as *u8); gv_num(out[RR_O_LINES])
  gv_puts(" missing=" as *u8); gv_num(out[RR_O_MISSING])
  gv_puts(" min=" as *u8); gv_num(out[RR_O_MIN])
  gv_puts(" p50=" as *u8); gv_num(out[RR_O_P50])
  gv_puts(" p99=" as *u8); gv_num(out[RR_O_P99])
  gv_puts(" max=" as *u8); gv_num(out[RR_O_MAX])
  gv_puts(" qval=" as *u8); gv_num(out[RR_O_QVAL])
  gv_puts(" scaled=" as *u8); gv_num(out[RR_O_SCALED])
  gv_puts(" derived=" as *u8); gv_num(out[RR_O_DERIVED])
  gv_puts(" cap=" as *u8); gv_num(out[RR_O_CAPMS]); gv_puts("\n" as *u8)
101
  gv_check("derives-a-ratchet-when-history-is-sufficient" as *u8, v == RR_RATCHET, c)
  gv_check("counts-every-planted-line-300-plus-40-plus-25" as *u8, out[RR_O_LINES] == 365, c)
  gv_check("only-sync-promoted-rows-with-a-reply-ms-enter-the-sample" as *u8, out[RR_O_N] == 300, c)
  // If the other-lane rows leaked in, max would be 99999 rather than 399.
  gv_check("neg-control-a-reply-ms-on-a-different-lane-does-not-enter-the-sample" as *u8, out[RR_O_MAX] == 399, c)
  // ANTI-VACUITY: an absent key must be MISSING, not a zero sample. A collector reading absent-as-zero
  // would report min=0, 25 extra samples, and a quantile dragged toward the floor.
  gv_check("neg-control-a-row-without-reply-ms-counts-as-missing-not-as-a-zero-sample" as *u8,
           out[RR_O_MISSING] == 25 && out[RR_O_MIN] == 100, c)
  // THE PARTITION SUMS, and it is printed: 300 collected + 40 filtered by lane + 25 missing = 365 lines.
  // An unreconciled residual here would mean rows are being silently dropped somewhere in the collector.
  gv_check("the-line-partition-reconciles-collected-plus-filtered-plus-missing-equals-total" as *u8,
           out[RR_O_N] + 40 + out[RR_O_MISSING] == out[RR_O_LINES], c)
  // hand-checked nearest rank: idx = q*(n-1)/1000 = 990*299/1000 = 296 -> 100+296 = 396
  gv_check("quantile-is-the-nearest-rank-value-of-the-hand-checked-array" as *u8, out[RR_O_QVAL] == 396, c)
  gv_check("p50-is-the-hand-checked-median" as *u8, out[RR_O_P50] == 100 + (500 * 299) / 1000, c)
  gv_check("margin-scales-the-quantile-by-the-declared-permil" as *u8, out[RR_O_SCALED] == (396 * 2000) / 1000, c)
  gv_check("derived-is-never-below-the-worst-reply-actually-witnessed" as *u8, out[RR_O_DERIVED] >= out[RR_O_MAX], c)
  gv_check("derived-is-never-below-the-declared-floor" as *u8, out[RR_O_DERIVED] >= out[RR_O_FLOOR], c)
  gv_check("derived-is-the-scaled-quantile-when-that-dominates-both-floors" as *u8, out[RR_O_DERIVED] == 792, c)
  gv_check("derived-stays-within-the-window-fraction-cap" as *u8, out[RR_O_DERIVED] <= out[RR_O_CAPMS], c)
123
  // ---- neg-control: too little history abstains and derives NOTHING ----
  let out2: *i64 = sys_mmap(RR_O_SLOTS * 8) as *i64
  let buf2: *u8 = sys_mmap(1 << 18)
  let n2: i64 = vrr_fixture(buf2, 100, 50, 0, 0, 0)
  let v2: i64 = rr_derive(buf2, n2, 990, 200, 2000, 250, 100, 15000, 1000, out2)
  gv_puts("  small-sample verdict=" as *u8); gv_num(v2); gv_puts(" samples=" as *u8); gv_num(out2[RR_O_N])
  gv_puts(" derived=" as *u8); gv_num(out2[RR_O_DERIVED]); gv_puts("\n" as *u8)
  gv_check("neg-control-below-minimum-samples-abstains-and-derives-nothing" as *u8,
           v2 == RR_INSUFFICIENT && out2[RR_O_N] == 50 && out2[RR_O_DERIVED] == 0, c)
  gv_check("an-abstention-still-reports-its-distribution-so-the-axis-is-not-blind" as *u8,
           out2[RR_O_MAX] == 149 && out2[RR_O_MIN] == 100, c)
135
  // ---- neg-control: empty buffer is UNREADABLE, distinct from abstain ----
  let out3: *i64 = sys_mmap(RR_O_SLOTS * 8) as *i64
  let v3: i64 = rr_derive(buf, 0, 990, 200, 2000, 250, 100, 15000, 1000, out3)
  gv_check("neg-control-empty-buffer-is-unreadable-not-a-zero-reserve" as *u8,
           v3 == RR_UNREADABLE && out3[RR_O_DERIVED] == 0, c)
141
  // ---- neg-control: a reserve that reaches the window is REFUSED, current value kept ----
  let out4: *i64 = sys_mmap(RR_O_SLOTS * 8) as *i64
  let v4: i64 = rr_derive(buf, n, 990, 200, 2000, 20000, 100, 15000, 1000, out4)
  gv_check("neg-control-a-reserve-that-swallows-the-window-is-refused" as *u8, v4 == RR_REFUSED, c)
  gv_check("a-refusal-keeps-the-current-value-rather-than-arming-a-bad-one" as *u8, out4[RR_O_CURRENT] == 1000, c)
147
  // ---- neg-control: above the window-fraction cap is REFUSED even though it is under the window ----
  let out5: *i64 = sys_mmap(RR_O_SLOTS * 8) as *i64
  let v5: i64 = rr_derive(buf, n, 990, 200, 10000, 250, 100, 15000, 1000, out5)
  gv_puts("  cap-test derived=" as *u8); gv_num(out5[RR_O_DERIVED]); gv_puts(" cap=" as *u8); gv_num(out5[RR_O_CAPMS]); gv_puts("\n" as *u8)
  gv_check("neg-control-a-reserve-over-the-window-fraction-cap-is-refused-though-under-the-window" as *u8,
           v5 == RR_REFUSED && out5[RR_O_DERIVED] == 3960 && out5[RR_O_DERIVED] < 15000, c)
154
  // ---- HOLD: the conf already carries the derived value ----
  let out6: *i64 = sys_mmap(RR_O_SLOTS * 8) as *i64
  let v6: i64 = rr_derive(buf, n, 990, 200, 2000, 250, 100, 15000, 792, out6)
  gv_check("holds-without-rewriting-when-the-conf-already-carries-the-measured-value" as *u8, v6 == RR_HOLD, c)
159
  // ================= the conf reader and the conf rewrite =================
  let cf: *u8 = sys_mmap(1 << 16)
  let cn: i64 = vrr_conf(cf, 1)
  gv_check("conf-fixture-reached-the-condition-both-keys-appear-in-prose-above-their-rows" as *u8,
           lc_line_has(cf, 0, cn, "old spelling" as *u8) == 1 && cn > 100, c)
  gv_check("line-anchored-conf-read-takes-the-row-not-the-prose" as *u8,
           lc_conf_line_num(cf, cn, RR_RESERVE_KEY, 0 - 1) == 1000, c)
  gv_check("line-anchored-conf-read-takes-the-edge-window-row" as *u8,
           lc_conf_line_num(cf, cn, RR_WINDOW_KEY, 0 - 1) == 15000, c)
  // THE REASON lc_conf_line_num EXISTS: the incumbent whole-buffer reader locks onto the FIRST occurrence
  // of the key, which is in the comment, finds no digit abutting it, and silently returns the default.
  // This control fires on the real file shape, not a contrived one.
  gv_check("neg-control-the-whole-buffer-conf-reader-silently-returns-the-default-on-this-shape" as *u8,
           lc_conf_num(cf, cn, RR_RESERVE_KEY, 0 - 1) == 0 - 1
           && lc_conf_num(cf, cn, RR_WINDOW_KEY, 0 - 1) == 0 - 1, c)
175
  let ob: *u8 = sys_mmap(1 << 16)
  let nn: i64 = rr_rewrite(cf, cn, ob, 1 << 16, 792, 1000, 300, 396, 990, 1787670000)
  gv_puts("  rewrite bytes=" as *u8); gv_num(nn); gv_puts(" (from " as *u8); gv_num(cn); gv_puts(")\n" as *u8)
  gv_check("rewrite-succeeds-on-a-conf-that-has-the-row" as *u8, nn > 0, c)
  // THE ROUND-TRIP: the rewritten conf is read back through the CONSUMER's own parser contract, so this
  // asserts the daemon would actually see the new number, not merely that bytes changed.
  gv_check("rewritten-row-reads-back-as-the-derived-value-through-the-consumer-parser" as *u8,
           lc_conf_line_num(ob, nn, RR_RESERVE_KEY, 0 - 1) == 792, c)
  gv_check("rewrite-preserves-the-edge-window-row-untouched" as *u8,
           lc_conf_line_num(ob, nn, RR_WINDOW_KEY, 0 - 1) == 15000, c)
  gv_check("rewrite-removes-the-stale-provenance-paragraph" as *u8,
           lc_line_has(ob, 0, nn, "STALE-PARAGRAPH-MARKER" as *u8) == 0, c)
  gv_check("rewrite-writes-the-measured-provenance-with-its-date-and-sample-size" as *u8,
           lc_line_has(ob, 0, nn, "MEASURED 2026-08-25" as *u8) == 1
           && lc_line_has(ob, 0, nn, "300 reply_ms samples" as *u8) == 1, c)
  gv_check("rewrite-emits-exactly-one-reserve-row-so-the-first-match-is-the-only-match" as *u8,
           lc_line_has(ob, 0, nn, "reply_reserve_ms 792" as *u8) == 1
           && lc_line_has(ob, 0, nn, "reply_reserve_ms 1000" as *u8) == 0, c)
  // A conf with no row must be REFUSED, never appended to -- two rows would make the consumer's
  // first-match-wins read a coin flip.
  let cf2: *u8 = sys_mmap(1 << 16)
  let cn2: i64 = vrr_conf(cf2, 0)
  let nn2: i64 = rr_rewrite(cf2, cn2, ob, 1 << 16, 792, 1000, 300, 396, 990, 1787670000)
  gv_check("neg-control-a-conf-with-no-reserve-row-is-refused-not-appended-to" as *u8, nn2 == 0 - 1, c)
200
  // ---- the date arithmetic, against hand-checked epochs ----
  let ymd: *i64 = sys_mmap(8 * 4) as *i64
  rr_civil(1787670000, ymd)
  gv_puts("  civil(1787670000)=" as *u8); gv_num(ymd[0]); gv_puts("-" as *u8); gv_num(ymd[1]); gv_puts("-" as *u8); gv_num(ymd[2]); gv_puts("\n" as *u8)
  gv_check("civil-date-matches-a-hand-checked-epoch" as *u8,
           ymd[0] == 2026 && ymd[1] == 8 && ymd[2] == 25, c)
  rr_civil(0, ymd)
  gv_check("neg-control-civil-date-of-the-epoch-itself-is-1970-01-01" as *u8,
           ymd[0] == 1970 && ymd[1] == 1 && ymd[2] == 1, c)
210
  // ================= the tail read, on a REAL file =================
  // This cannot be proven on a buffer: it is a claim about lseek. Fixture is a uniquely-named /tmp path
  // this gate alone writes, never a production artifact.
  let fb: *u8 = sys_mmap(1 << 20)
  var fo: i64 = 0
  var f: i64 = 0
  while f < 120 { fo = vrr_row(fb, fo, "sync-promoted" as *u8, 0 - 1); f = f + 1 }
  let headonly: i64 = fo
  f = 0
  while f < 300 { fo = vrr_row(fb, fo, "sync-promoted" as *u8, 100 + f); f = f + 1 }
  let fd: i64 = sys_openat_wr(VRR_FIX, MODE_0644)
  var wrote: i64 = 0
  if fd >= 0 { wrote = sys_write(fd, fb, fo); sys_close(fd) }
  gv_puts("  tail fixture bytes=" as *u8); gv_num(fo); gv_puts(" wrote=" as *u8); gv_num(wrote)
  gv_puts(" filler_prefix=" as *u8); gv_num(headonly); gv_puts("\n" as *u8)
  gv_check("tail-fixture-reached-the-condition-filler-prefix-exceeds-the-read-cap" as *u8,
           wrote == fo && headonly > VRR_SMALLCAP, c)
228
  let rb: *u8 = sys_mmap(VRR_SMALLCAP)
  let oh: *i64 = sys_mmap(RR_O_SLOTS * 8) as *i64
  let hn: i64 = lc_read(VRR_FIX, rb, VRR_SMALLCAP)
  rr_derive(rb, hn, 990, 1, 2000, 250, 100, 15000, 1000, oh)
  let meta: *i64 = sys_mmap(LC_M_N * 8) as *i64
  let rb2: *u8 = sys_mmap(VRR_SMALLCAP)
  let ot: *i64 = sys_mmap(RR_O_SLOTS * 8) as *i64
  let tn: i64 = lc_read_tail(VRR_FIX, rb2, VRR_SMALLCAP, meta)
  rr_derive(rb2, tn, 990, 1, 2000, 250, 100, 15000, 1000, ot)
  gv_puts("  head_read bytes=" as *u8); gv_num(hn); gv_puts(" samples=" as *u8); gv_num(oh[RR_O_N])
  gv_puts("  |  tail_read bytes=" as *u8); gv_num(tn); gv_puts(" samples=" as *u8); gv_num(ot[RR_O_N])
  gv_puts(" whole=" as *u8); gv_num(meta[LC_M_WHOLE]); gv_puts(" size=" as *u8); gv_num(meta[LC_M_SIZE])
  gv_puts(" min=" as *u8); gv_num(ot[RR_O_MIN]); gv_puts(" max=" as *u8); gv_num(ot[RR_O_MAX]); gv_puts("\n" as *u8)
  // THE DISCRIMINATING CONTROL for the whole tail-read design: on an append-only log whose samples are
  // all recent, a capped HEAD read finds none and a capped TAIL read finds them. Measured on the real
  // actlog before this was built: 8 of 8 reply_ms rows sat in the last 25 KB of a 30 MB file.
  gv_check("neg-control-a-capped-head-read-of-an-append-only-log-finds-zero-samples" as *u8, oh[RR_O_N] == 0, c)
  gv_check("the-tail-read-finds-the-recent-samples-the-head-read-cannot" as *u8, ot[RR_O_N] > 0, c)
  gv_check("tail-read-reports-that-its-window-was-not-the-whole-file" as *u8,
           meta[LC_M_WHOLE] == 0 && meta[LC_M_SIZE] == fo, c)
  // A tail window starts mid-line. If the partial first row were not dropped, a torn `reply_ms=39` would
  // enter as 39 and sit below the planted floor of 100.
  gv_check("tail-read-drops-the-partial-first-line-so-no-torn-row-enters-the-sample" as *u8,
           ot[RR_O_MIN] >= 100 && ot[RR_O_MAX] <= 399, c)
253
  return gv_verdict("nx_replyreserve_gate" as *u8, c,
      "Reply-reserve calibrator: only lane=sync-promoted rows carrying a reply_ms enter the sample, an absent field is MISSING and never a zero, the derived reserve is floored by the worst witnessed reply and refused outside a declared envelope with the current value kept, the conf rewrite round-trips through the consumer's own line-anchored parser, and a capped head read of an append-only log is shown to find nothing where the tail read finds the samples." as *u8)
256}
nx_replyreserve_gate.nx source

`nx_replyreserve_gate.nx` source
