code wiki / _hdl_build / nx_routeguard_lib.nx
nx_routeguard_lib.nx
buildroot/runtime/_hdl_build/nx_routeguard_lib.nx
about
nx_routeguard_lib.nx -- DEPLOY CONTRACT GUARD: does the candidate binary still serve every route
the live one does?
THE DEFECT THIS EXISTS FOR (measured 2026-07-30, FIVE occurrences, one of them mine):
nx_mgmt_api has now lost /api/gate_run + /api/proc_kill from the LIVE binary five separate times
(21 routes -> 19). Mine happened because I built mgmt from a backdated tree and deployed a 528323-byte
artifact over a 575195-byte one -- a 47KB DECREASE that was visible at the time and that I did not
check. Every occurrence had the same shape: the source was fine, the BINARY silently lost surface,
and the deploy reported success. nx_route_diff already prints "route(s) vanished = deploy contract
regression" but is not wired into the deploy path, so nothing ever consulted it.
WHY THIS GATE AND NOT LOAD-ADMISSION (self-correction, id=1785450386): my first instinct was to gate
deploys on host load the way /api/build is gated. That is WRONG and would deadlock the ecosystem --
the repair for a saturated host IS a deploy, so a load-gated deploy refuses the fix BY THE CONDITION
IT REPAIRS. Route loss, by contrast, is ALWAYS wrong regardless of load, so this guard can never
block a repair. That property is the whole reason this is the right guard.
DERIVED, NOT DECLARED: the expected route set is EXTRACTED FROM THE LIVE BINARY, never hardcoded.
A baked list would be the same declared-denominator defect already filed (id=1785446417) -- it would
go stale the moment a route is legitimately added, and it would fail OPEN.
ASYMMETRIC BY DESIGN: candidate ADDING routes is fine (that is a normal feature deploy). Only
DISAPPEARANCE is a defect. So this is a SUPERSET check, not an equality check.
license_tier: ORIGINAL Read-only. No hw writes (Rule 26).
dependencies 1 imports · 3 importers
imports: nx_syscalls.nx
imported by: nx_mgmt_api.nxnx_routeguard.nxnx_routeguard_gate.nx
structs
| none |
consts
| 27 | const RG_BUF: i64 = 4194304 // per-binary read cap |
| 28 | const RG_MAXR: i64 = 128 // max distinct routes tracked |
| 29 | const RG_NAMEMAX: i64 = 64 |
| 30 | const RG_NEEDLE: i64 = 5 // strlen("/api/") |
functions
| 32 | func rg_isroute_ch(c: i64) -> i64 |
| 43 | func rg_read(path: *u8, buf: *u8, cap: i64) -> i64 |
| 66 | func rg_contains(buf: *u8, n: i64, needle: *u8, nl: i64) -> i64 |
| 86 | func rg_seen(names: *u8, lens: *i64, cnt: i64, p: *u8, l: i64) -> i64 called by 1: rg_extract |
| 103 | func rg_extract(buf: *u8, n: i64, names: *u8, lens: *i64, trunc: *i64) -> i64 |
| 144 | func rg_missing(lnames: *u8, llens: *i64, lcnt: i64, cbuf: *u8, cn: i64, miss: *i64, misscap: i64) -> i64 |