nx_craft_lit_fit_expanded_t181.nx source
↩ module page · 5411 lines · 262144 B
1// nx_game_page_emit.nx -- the SOVEREIGN game-page emitter. Until now the browser page for a wasm
2// game was assembled by printf blocks in _ops/nx_emit_game.sh -- real emission logic living in
3// SHELL, against the doctrine (shell only LAUNCHES sovereign ELFs). This organ owns it: reads the
4// .wasm, base64-encodes it (composes nx_base64 -- one encoder, not a coreutils dependency), and
5// emits the complete self-contained page (marker, shim, input forwarding, persistence bytes-mover).
6// usage: nx_game_page_emit <wasm> <out.html> <title> <native-client-name> <controls-html>
7//
8// RECOVERED 2026-08-02 from buildroot/_build/nx_craft_emit.s (the 14:07 build's data section)
9// after a failed in-place rewrite TRUNCATED this file to 0 bytes and the damage was copied to
10// both trees. Every emitted chunk below is the exact byte sequence that build shipped, so the
11// recovered emitter is byte-equivalent to the last one that passed both gates.
12// license_tier: ORIGINAL
13// syscalls.nx -- thin __syscall wrappers used across modules.
14//
15// Sovereign path: no libc. Every memory allocation, file op, and
16// clock read in the rest of the runtime routes through one of these
17// helpers. Numbers match Linux RV64; NishiOS uses the same set.
18//
19// Extracted from runtime.nx and ir.nx's copy-pasted helpers so the
20// module-import build doesn't produce duplicate symbols.
21
22// Tier aliases (nx_size / nx_idx / nx_fd / ...) ride along with the
23// syscall shelf: 141 runtime files use `as nx_size` etc. and only
24// compiled historically because the old parser silently void-cast
25// unknown type names (T#nx-int-alias-size-0 closed that hole LOUDLY,
26// which exposed the missing import). nx_tier.nx is pure type
27// aliases (0 funcs); prepass_register_aliases skips duplicates, so
28// modules that also import it directly stay fine.
29// nx_tier.nx -- substrate-wide tier configuration.
30//
31// Single point of edit for scale-agnostic substrate. Per user
32// directive 2026-05-13: "with the i64 it looks hardcoded everywhere
33// if we really want this dynamic dont we want that to be a changeable
34// value everywhere so it can switch to i128 and i256 etc."
35//
36// Per cardinals:
37// - feedback-numeric-tier-ladder.md (N0..N9 swap)
38// - feedback-scale-agnostic-substrate.md (MCU..HPC swap)
39// - feedback-substrate-additive-not-restrictive.md (declare cost)
40//
41// SEMANTIC ALIASES (not all should swap simultaneously):
42//
43// nx_int -- DEFAULT ARITHMETIC integer. Swappable across the
44// numeric tier ladder. Swap this to i128 to make the
45// entire substrate compute in 128-bit integers.
46//
47// nx_size -- MEMORY-SIZE integer. Always platform-pointer-width.
48// Used for buffer sizes, mmap byte counts, struct
49// sizes. Does NOT swap with nx_int -- changing this
50// would break pointer arithmetic. Stays i64 on RV64.
51//
52// nx_idx -- ARRAY-INDEX integer. Same width as nx_size on
53// flat-memory targets. Distinct alias so future
54// GPU/distributed targets can change indexing without
55// touching arithmetic.
56//
57// nx_byte -- The byte type. Stays u8. Distinct alias so MCU
58// targets that emulate u16-byte memory could rebind.
59//
60// HARDWARE-TIER BUFFER SIZES (declare cost, don't restrict):
61//
62// NX_BUF_TINY -- 64 B (MCU-friendly; stack-safe)
63// NX_BUF_SMALL -- 256 B (MCU heap-friendly)
64// NX_BUF_MEDIUM -- 4096 B (page-size; workstation default)
65// NX_BUF_LARGE -- 64 KiB (server-friendly)
66// NX_BUF_HUGE -- 1 MiB (HPC; assumes virtual memory)
67//
68// Use these instead of `sys_mmap(4096)` etc. so the substrate
69// announces its memory footprint and tier-incompatible code can
70// be flagged by audit.
71//
72// HARDWARE TIER (informational; downstream code may branch):
73//
74// NX_TIER_MCU = 0 -- microcontroller, kilobytes RAM
75// NX_TIER_SOVEREIGN_CHIP = 1 -- custom silicon, ~MB RAM
76// NX_TIER_FAMILY_DEVICE = 2 -- phone/router, ~GB RAM
77// NX_TIER_WORKSTATION = 3 -- laptop/desktop, ~10-100 GB RAM
78// NX_TIER_SERVER = 4 -- server-class, ~TB RAM
79// NX_TIER_HPC = 5 -- cluster, distributed
80//
81// COMPILE-TIME SWAP for nx_int (uncomment exactly one line):
82
83// THIS FILE IS THE SINGLE DEFINITION SITE for substrate-wide types.
84// Per user directive 2026-05-13: only this file (and platform-ABI
85// definition files like nx_syscalls.nx) should declare bare i64.
86// Every other substrate module uses the aliases below.
87
88// ===== arithmetic-tier aliases (swappable per nx_int tier ladder) =====
89
90type nx_int = i64 // N1 -- default; 9 quintillion, fits all physical scales
91// type nx_int = i32 // N0 -- MCU / embedded
92// type nx_int = i128 // N2 -- queued; needs nx_i128 backend ops
93// type nx_int = i256 // N3 -- shipped (nx_i256.nx); cosmology / crypto
94
95// ===== platform-width aliases (stay at pointer width) =================
96
97type nx_size = i64 // memory-size / byte-count
98type nx_idx = i64 // array-index
99type nx_byte = u8 // single-byte unit
100
101// ===== POSIX/Linux platform-ABI aliases (mandated 64-bit on RV64) ====
102//
103// Each is a 64-bit integer by Linux RV64 ABI. Renamed here so substrate
104// code never writes bare `i64` for these semantic types.
105
106type nx_fd = i64 // file descriptor (kernel-mandated width)
107type nx_exit = i64 // exit / status code (main() return)
108type nx_pid = i64 // process id
109type nx_uid = i64 // user id
110type nx_gid = i64 // group id
111type nx_syscall_num = i64 // Linux syscall number
112type nx_off = i64 // file offset (off_t)
113type nx_errno = i64 // errno (negative on syscall failure)
114
115// ===== SEMANTIC TYPE GENEALOGY (added 2026-05-20) ======================
116//
117// Per cardinal [[feedback-type-genealogy-math-cardinal-not-script]]
118// AND its immediate refinement (same session): every alias collapsing
119// to i64 is "y2k incestuous" -- relabeling, not genealogy. Real
120// semantic types pick the APPROPRIATE underlying width based on
121// the physics of the values they represent:
122//
123// - Small sealed enums (15 outcomes, 18 probe kinds) -> u8
124// - Display pixel coords (~32M max realistic) -> i32
125// - Q10 / Q14 fixed-point (values * 1024 / 16384) -> i32
126// - 32-bit color packs (RGBA8888) -> u32
127// - Q20 fixed-point (values * 1048576) -> i64
128// - Wide color packs (RGBA16161616, PRESERVE_ALL) -> u64
129// - Timestamps (ns / us / ms / cycles) -> i64 (2038 Y2K38)
130// - 64-bit hash digests -> u64
131// - Cryptographic hashes (SHA-256, SHA-512) -> STRUCT (multi-word; queued)
132// - Virtual addresses on 64-bit ISA -> u64
133//
134// Each type is a child of its PHYSICALLY-APPROPRIATE parent
135// (i8/u8/i32/u32/i64/u64), not blanket-i64. This breaks the
136// y2k-incestuous trap where renaming i64 N ways pretends to be
137// type discipline while every value silently shares one width.
138
139// ----- TIME family (all i64; ns/us/ms/cycles legitimately need it) -----
140// 2038 Y2K38 lurks for 32-bit time_t; i64 is the substrate-honest
141// choice. ms/us/ns + cycles all i64. s_q14 needs only i32 range
142// (val*16384 fits comfortably in i32 for typical second scales) but
143// we stay at i64 to compose cleanly with the i64 time arithmetic
144// across the substrate.
145type nx_ns = i64 // nanoseconds (since boot, monotonic)
146type nx_us = i64 // microseconds (since boot, monotonic)
147type nx_ms = i64 // milliseconds (since epoch, wall)
148type nx_s_q14 = i64 // seconds in Q14 fixed-point
149type nx_cycles = i64 // CPU cycle count
150
151// ----- HASH family (non-cryptographic 64-bit; crypto = STRUCT) -----
152// FNV-1a / xxhash digest is u64 by spec. SHA-256 / SHA-512 / BLAKE
153// hashes are MULTI-WORD; they're declared as structs in
154// nx_sha256.nx / nx_sha512.nx / nx_blake2b.nx (each carries its own
155// fixed-size byte array; NOT i64).
156type nx_hash64 = u64 // FNV-1a / xxhash / truncated SHA -- 64-bit digest
157
158// ----- ETG family (sealed enums; small value space -> u8) -----
159// nx_outcome_id sealed enum has 11 values; u8 fits 256
160// nx_probe_kind sealed enum has 18 values; u8 fits 256
161// nx_claim_source sealed enum has 13 values; u8 fits 256
162// nx_silicon_serial is a content-addressed identity HASH; u64.
163type nx_outcome_id = u8 // NX_ETG_OUTCOME_* (11 values; u8 fits)
164type nx_probe_kind = u8 // NX_ETG_PROBE_* (18 values; u8 fits)
165type nx_claim_source = u8 // NX_ETG_CLAIM_* (13 values; u8 fits)
166type nx_silicon_serial = u64 // per-die identity hash (cryptographic-strength width)
167
168// ----- PERF family (sealed enums) -----
169type nx_pathology_id = u8 // NX_PERF_PATH_* (15 values; u8 fits)
170type nx_flow_state_id = u8 // NX_FLOW_STATE_* (6 values; u8 fits)
171
172// ----- FIXED-POINT family (width chosen by precision*range) -----
173// Q10: value * 1024. Typical seed values are 0..255 so q10 max is
174// ~261K; i32 holds up to ~2.1B -> plenty of headroom.
175// Q14: value * 16384. Typical max around 16K of seed -> q14 ~ 2.6e8;
176// i32 holds up to 2.1e9 -> headroom for a few decimal seconds.
177// Q20: value * 1048576. Wider precision; needs i64 to avoid wrap.
178type nx_q10 = i32 // val * 1024; ~0.001 precision
179type nx_q14 = i32 // val * 16384; ~6e-5 precision
180type nx_q20 = i64 // val * 1048576; ~1e-6 precision
181
182// ----- GRAPHICS family (display coords + color packs at real widths) -----
183// Modern displays are well within 32-bit pixel addressing.
184// 8K display = 7680x4320 pixels. i32 holds 2.1B -> plenty.
185// nx_color_rgba8 = 32-bit packed RGBA (the common case)
186// nx_color_rgba16 = 64-bit packed RGBA16161616 (HDR / wide gamut)
187type nx_pixel_x = i32 // screen X in pixels
188type nx_pixel_y = i32 // screen Y in pixels
189type nx_color_rgba8 = u32 // RGBA8888 packed
190type nx_color_rgba16 = u64 // RGBA16161616 packed (HDR / preserve-all)
191
192// ----- PERCEPTUAL family (sealed enum; small value space) -----
193// nx_perceptual_profile has ~40 declared values up through
194// NX_PERCEPT_PRESERVE_ALL = 9999. Sentinel value 9999 needs i16,
195// not u8. i16 fits -32768..32767 with room for sentinels.
196type nx_perceptual_profile = i16 // NX_PERCEPT_* (~40 values + 9999 sentinel)
197
198// ----- ADDRESS family (virtual addresses on 64-bit ISA) -----
199// Pointer-width is u64 on all our supported 64-bit targets
200// (RV64 / x86_64 / AArch64 / ppc64le / loongarch64 / mips64 /
201// s390x / RV32 uses u32 -- TODO: tier-conditional).
202type nx_addr = u64 // raw virtual address (caller casts to *u8)
203
204// nx_capability_manifest:
205// variant_class: tier_config
206// variant_id: tier_config_v1_global
207// requires_isa: [rv32i, rv32imac, rv64imac, rv64imacv, x86_64, aarch64, armv7a, cortex_m, avr, xtensa, wasm32]
208// requires_syscalls: []
209// requires_ram_min_b: 0 // pure-const + typedef module, no runtime cost
210// tier_floor: NX_TIER_MCU
211// tier_ceiling: NX_TIER_HPC
212// cost_model:
213// flops_per_n: 0.0
214// bytes_per_n: 0.0
215// syscalls_per_n: 0.0
216// adversary_class: THREAT_OPPORTUNISTIC
217//
218// Note: This file is the substrate's TIER ENUM SOURCE OF TRUTH. It
219// has no variants by design (it IS the variant_class taxonomy that
220// other primitives' tier_floor / tier_ceiling reference). Manifest
221// declared for hygiene completeness; selector will skip it.
222
223// ---- buffer-size constants (use instead of bare numbers) -------
224
225const NX_BUF_TINY: nx_size = 64
226const NX_BUF_SMALL: nx_size = 256
227const NX_BUF_MEDIUM: nx_size = 4096
228const NX_BUF_LARGE: nx_size = 65536
229const NX_BUF_HUGE: nx_size = 1048576
230
231// ---- hardware tier sentinels -----------------------------------
232
233const NX_TIER_MCU: nx_int = 0
234const NX_TIER_SOVEREIGN_CHIP: nx_int = 1
235const NX_TIER_FAMILY_DEVICE: nx_int = 2
236const NX_TIER_WORKSTATION: nx_int = 3
237const NX_TIER_SERVER: nx_int = 4
238const NX_TIER_HPC: nx_int = 5
239
240// ---- numeric tier sentinels (informational) --------------------
241
242const NX_NUM_N0_I32: nx_int = 0
243const NX_NUM_N1_I64: nx_int = 1
244const NX_NUM_N2_I128: nx_int = 2
245const NX_NUM_N3_I256: nx_int = 3
246const NX_NUM_N4_I512: nx_int = 4
247const NX_NUM_N5_BIGINT: nx_int = 5
248
249// ---- byte-width of substrate types (replace bare `8` / `4`) ----
250//
251// Use these wherever you need the byte count of a substrate type --
252// e.g., sys_mmap(N * NX_SIZEOF_NX_SIZE) to allocate N nx_size slots.
253// Swap nx_int's underlying type and ONLY this constant changes.
254
255const NX_SIZEOF_NX_INT: nx_size = 8 // nx_int currently i64 -> 8 bytes
256const NX_SIZEOF_NX_SIZE: nx_size = 8 // nx_size always pointer-width
257const NX_SIZEOF_NX_IDX: nx_size = 8 // nx_idx alias of nx_size
258
259// ---- POSIX stdio file descriptors (replace bare 0/1/2) ---------
260
261const NX_FD_STDIN: nx_fd = 0
262const NX_FD_STDOUT: nx_fd = 1
263const NX_FD_STDERR: nx_fd = 2
264
265const SYS_MAGIC_1024: i64 = 1024
266const SYS_MAGIC_1000000: i64 = 1000000
267const SYS_MAGIC_4294967296: i64 = 4294967296
268// first read window for a size-UNKNOWABLE file (lseek END <= 0); doubles while it fills -- see sys_read_file
269const SYS_READ_GROW_INIT: i64 = 65536
270const SYS_MAGIC_100000: i64 = 100000
271
272// ---- syscall numbers (per-target) ----
273//
274// Cross-target via the macro processor (cardinal landed 2026-05-20:
275// feedback-hardware-agnostic-is-robustness -- the substrate must
276// compile + run on every silicon we point it at). Default path
277// (TARGET_X86_64 not defined) carries Linux RV64 numbers used by
278// qemu-RV64 + NishiOS. When nxc2 is invoked with --target x86_64
279// main.c pre-defines @macro TARGET_X86_64 1 so this file resolves
280// to x86_64 Linux ABI numbers.
281//
282// nx_syscalls_x86_64.nx remains the dedicated x86_64-only mirror
283// for files that want explicit single-target imports (e.g., bench
284// smokes built only for x86_64). This block makes nx_syscalls.nx
285// itself dual-target so substrate primitives compile portably.
286
287@ifdef TARGET_X86_64
288const SYS_READ: i64 = 0
289const SYS_WRITE: i64 = 1
290const SYS_CLOSE: i64 = 3
291const SYS_LSEEK: i64 = 8
292const SYS_OPENAT: i64 = 257
293const SYS_EXIT: i64 = 60
294const SYS_MMAP: i64 = 9
295const SYS_CLOCK_GETTIME: i64 = 228
296const SYS_IOCTL: i64 = 16
297const SYS_CLOCK_NANOSLEEP: i64 = 230
298// Namespace/container family, x86 branch (debt 1785528831). Moved here from
299// nx_syscalls_x86_64.nx so ONE module owns the wrapper set -- a TU reaching both
300// modules used to hold every wrapper TWICE, resolved silently by definition ORDER.
301const SYS_CHROOT: i64 = 161
302const SYS_MOUNT: i64 = 165
303const SYS_UNSHARE: i64 = 272
304const SYS_GETUID: i64 = 102
305const SYS_GETGID: i64 = 104
306const SYS_POLL: i64 = 7
307@endif
308
309@ifndef TARGET_X86_64
310const SYS_READ: i64 = 63
311const SYS_WRITE: i64 = 64
312const SYS_CLOSE: i64 = 57
313const SYS_LSEEK: i64 = 62
314const SYS_OPENAT: i64 = 56
315const SYS_EXIT: i64 = 93
316const SYS_MMAP: i64 = 222
317const SYS_CLOCK_GETTIME: i64 = 113
318const SYS_IOCTL: i64 = 29
319const SYS_CLOCK_NANOSLEEP: i64 = 115
320// Namespace/container family, RV64 branch (debt 1785528831). This is the branch actually
321// KEPT (TARGET_X86_64 is hard-pinned undefined), so these are the numbers the x86 backend
322// translates at emit: 51->161 chroot, 40->165 mount, 97->272 unshare, 174->102 getuid,
323// 176->104 getgid. The 40 and 51 rows were added to x86ctx_rv64_to_x86_64_syscall and
324// shipped FIRST -- without them both would pass through to the WRONG x86 syscall
325// (sendfile / getsockname), silently, because that translator's default is `return num`.
326const SYS_CHROOT: i64 = 51
327const SYS_MOUNT: i64 = 40
328const SYS_UNSHARE: i64 = 97
329const SYS_GETUID: i64 = 174
330const SYS_GETGID: i64 = 176
331const SYS_POLL: i64 = 73
332@endif
333
334func sys_ioctl(fd: i64, request: i64, arg: i64) -> i64 {
335 return __syscall(SYS_IOCTL, fd, request, arg, 0, 0, 0)
336}
337
338// poll(2): wait for events on fds. fds points to an array of `nfds`
339// struct pollfd { i32 fd; i16 events; i16 revents } (8 bytes each).
340// timeout_ms < 0 = block forever, 0 = return immediately. Returns the
341// count of ready fds (>0), 0 on timeout, or -errno. Used by the
342// substrate's own network diagnostics (bounded non-blocking connect)
343// instead of reaching for external tools. (rv64 const = ppoll; this
344// wrapper only runs on the x86_64 target.)
345func sys_poll(fds: *u8, nfds: i64, timeout_ms: i64) -> i64 {
346 return __syscall(SYS_POLL, fds, nfds, timeout_ms, 0, 0, 0)
347}
348
349// ---- core wrappers ----
350
351func sys_write(fd: i64, buf: *u8, count: i64) -> i64 {
352 return __syscall(SYS_WRITE, fd, buf, count, 0, 0, 0)
353}
354
355func sys_read(fd: i64, buf: *u8, count: i64) -> i64 {
356 return __syscall(SYS_READ, fd, buf, count, 0, 0, 0)
357}
358
359func sys_close(fd: i64) -> i64 {
360 return __syscall(SYS_CLOSE, fd, 0, 0, 0, 0, 0)
361}
362
363// chdir. The compiler only rv64->x86 translates CONSTANT syscall numbers (x86ctx_emit_syscall:
364// VK_CONST_INT); chdir is absent from that table, so a constant 49 falls through to x86_64 bind and a
365// constant 80 is mapped to fstat -- BOTH gave EBADF (PROBE-PROVEN by test_chdir). The documented escape
366// (nx_x86_64_ctx.nx:1004 "Runtime-computed syscall number -- load as-is") is to make op0 RUNTIME: a memory
367// load can't be folded to VK_CONST_INT, so the raw x86_64 number 80 passes through untranslated = real
368// chdir. Used by the supervisor to set a spawned daemon's CWD before execve. 0 on success, -errno on fail.
369func sys_chdir(path: *u8) -> i64 {
370 let nbox: *i64 = sys_mmap(16) as *i64
371 nbox[0] = 80 // x86_64 chdir, forced runtime so the rv64->x86 xlate is skipped
372 return __syscall(nbox[0], path as i64, 0, 0, 0, 0, 0)
373}
374
375// getcwd -- SAME runtime-number escape as sys_chdir directly above, for the same documented reason: the
376// rv64->x86 translator only rewrites CONSTANT syscall numbers, and getcwd is absent from that table, so a
377// constant would be mangled exactly as chdir's was. A memory load cannot be folded to VK_CONST_INT, so the
378// raw x86_64 number passes through untranslated.
379// WHY THIS EXISTS (2026-08-14): the shim had sys_chdir but NOTHING to ask where we are. Every organ that
380// resolves a path against the CWD could therefore only print a RELATIVE path -- a claim whose truth depends
381// on invisible state. Three separate working-directory faults in one session stayed invisible until they
382// bit, and in each the reader could not tell "the file is missing" from "I am standing somewhere else".
383// ★★★AN ORGAN THAT CANNOT REPORT WHERE IT IS CANNOT WRITE AN HONEST PATH.
384// Returns the byte length written INCLUDING the terminator, or -errno (notably -ERANGE if cap is short).
385// SYS_PATH_MAX is exported so a caller never hand-writes the size: the FIRST consumer of sys_getcwd (this
386// author, minutes after adding it) wrote `sys_mmap(4096)` and `sys_getcwd(buf, 4096)` on consecutive
387// lines -- a bare literal AND a duplicate-authored pair, the exact shape being removed elsewhere the same
388// day. ★★A NEW PRIMITIVE THAT DOES NOT EXPORT ITS OWN SIZE INVITES EVERY CALLER TO INVENT ONE.
389const SYS_PATH_MAX: i64 = 4096 // Linux PATH_MAX; getcwd returns -ERANGE below it
390// The DIRECTORY sibling of MODE_0644, added on the same evidence: `0x1ed` appears at 569 sites in
391// buildroot/runtime (nx_shelltool, corpus_complete=1), i.e. the estate scatters TWO file-mode constants,
392// not one. Named here so the pair lives together and a reader meets both at the same place.
393const MODE_0755: i64 = 0x1ed // rwxr-xr-x : default mode for a created directory
394func sys_getcwd(buf: *u8, cap: i64) -> i64 {
395 let nbox: *i64 = sys_mmap(16) as *i64
396 nbox[0] = 79 // x86_64 getcwd, forced runtime so the rv64->x86 xlate is skipped
397 return __syscall(nbox[0], buf as i64, cap, 0, 0, 0, 0)
398}
399
400// ⚠AT_FDCWD MOVED UP 2026-07-20 -- IT WAS A LIVE MISCOMPILE. This const was declared ~60 lines BELOW
401// (in the openat block) while sys_unlinkat and sys_fchmodat immediately below REFERENCE it. A module
402// const referenced ABOVE its declaration does not resolve, and nx_cc silently substituted CONSTANT 0
403// -- so both wrappers passed dirfd=0 (stdin) instead of -100. Absolute paths survive that (openat
404// ignores dirfd when the path is absolute), RELATIVE paths do not, which is exactly why unlinkat was
405// long recorded as flaky and "passing only by luck". Surfaced by the new unknown-identifier
406// diagnostic, which turned a silent 0 into a compile error. LAW (already banked, now enforced):
407// module-wide consts/statics go ABOVE every possible reader.
408const AT_FDCWD: i64 = -100
409
410// unlinkat(AT_FDCWD, path, 0) -- delete a file. x86_64 263 is a PROVEN pass-through (not an rv64 key),
411// but this is THE canonical home: 5+ organs hand-rolled `__syscall(263,...)` before this landed (DRY,
412// 2026-07-20). 0 on success, -errno on fail.
413func sys_unlinkat(path: *u8) -> i64 {
414 return __syscall(263, AT_FDCWD, path as i64, 0, 0, 0, 0)
415}
416
417// fchmodat(AT_FDCWD, path, mode) -- chmod by path. ⚠a CONSTANT 268 gets rv64->x86 TRANSLATED to the
418// wrong syscall (silent no-op chmod -- cost a vacuous-permission-test debug cycle, 2026-07-20), so the
419// number is forced RUNTIME via the sys_chdir nbox pattern. 0 on success, -errno on fail.
420func sys_fchmodat(path: *u8, mode: i64) -> i64 {
421 let nbox: *i64 = sys_mmap(16) as *i64
422 nbox[0] = 268 // x86_64 fchmodat, forced runtime so the xlate is skipped
423 return __syscall(nbox[0], AT_FDCWD, path as i64, mode, 0, 0, 0)
424}
425
426// exit_group(2) -- terminate ALL tasks in the thread group. Raw x86_64 231
427// (231 is NOT an rv64 key in the compiler's swap table, so it passes through
428// untranslated -- the munmap-11 precedent). THE explicit program-exit call
429// once a process holds live nx_thread_pool workers: CLONE_VM tasks are
430// separate PIDs, so plain sys_exit (93 -> x86 60, single task) leaves them
431// running, holding stdout open and wedging any pipeline that waits for EOF
432// (found 2026-07-07: the shared-pool matmul dispatcher hung the build lane
433// this way). Return-from-main already exit_groups via the _start trampoline;
434// use THIS for explicit early program exit. Per-THREAD exit stays sys_exit
435// (see nx_thread_exit).
436func sys_exit_group(code: i64) -> i64 {
437 return __syscall(231, code, 0, 0, 0, 0, 0)
438}
439
440// setpriority(PRIO_PROCESS=0, who=0 -> SELF, prio) -- x86_64 syscall 141.
441// Lower priority = larger nice value; 19 is the maximum yield.
442// WHY A WRAPPER AND NOT AN OPERATOR STEP (measured 2026-07-30): a bulk media
443// migration walk saturated the NAS; every forked organ queued behind its I/O so
444// EVERY agent MCP call 503'd for minutes -- the control plane went blind while a
445// background job did exactly what it was told. `renice 19` on the running pid
446// restored interactive service at once.
447// LAW: a long-running BULK job must yield to the interactive control plane BY
448// CONSTRUCTION at its own launch, not when an operator notices. Bind it to the
449// one act every bulk job performs (its startup) and nothing has to remember it.
450// WARN: `ionice` does NOT exist on the Synology busybox, so the I/O-class lever
451// is unavailable; CPU nice sufficed because the walk is SHA-256-bound over
452// cached reads (state R, not D, once niced).
453func sys_setpriority(prio: i64) -> i64 {
454 return __syscall(141, 0, 0, prio, 0, 0, 0)
455}
456
457// ADDITIVE TWIN 2026-08-04 (nx_resgov): re-nice ANOTHER process by pid. The incumbent above pins
458// who=0 = "me", so it cannot deprioritise a runaway -- and a governor that can only slow ITSELF has
459// no graceful rung between "observe" and "kill". PRIO_PROCESS=0, who=pid. Existing callers untouched
460// (rule 19: add the new entry point, never re-shape the one in service).
461func sys_setpriority_of(pid: i64, prio: i64) -> i64 {
462 return __syscall(141, 0, pid, prio, 0, 0, 0)
463}
464
465// munmap -- free a region from sys_mmap. x86_64 munmap = 11; 11 is NOT an rv64 number in the compiler's
466// swap table, so the literal passes through untranslated = real munmap (unlike chdir, where rv64 80=fstat
467// intercepted it). CRITICAL for long-running loops: the supervisor's per-poll proc_* scans mmap 64KB+ each;
468// unfreed, the leak hits DSM's RLIMIT_AS -> mmap returns -12 -> the code writes through it -> SEGFAULT
469// (dmesg-proven: nx_hostctl segfault at 0xfffffffffffffff4). Free scan buffers to keep the supervisor alive.
470// ===== SMALL-ALLOCATION BUMP ARENA (2026-08-06, debt 1785516350 / 1786055008) =====================
471// MEASURED FIRST, THEN BUILT. nx_arena_probe: 20,000 x sys_mmap(32) -> VmSize 80,172 kB,
472// VmRSS 80,024 kB. 640 KB of requested data cost 78 MB of RESIDENT memory -- 4096 bytes per 32-byte
473// request, exactly one page and one kernel VMA each. Across the corpus nx_mmapbal deep counts 17,157
474// functions / 43,498 sites that allocate and never return, so this multiplier is the actual shape of
475// the leak: the call sites are not individually wrong so much as individually EXPENSIVE.
476//
477// One VMA per call is also a HARD CORRECTNESS CEILING, not just a memory cost: vm.max_map_count
478// defaults to 65530, after which mmap returns -ENOMEM and callers write through the failed pointer.
479// That is precisely the dmesg-proven nx_hostctl SEGFAULT at 0xfffffffffffffff4 described below.
480//
481// SO: requests <= NXA_SMALL_MAX are bump-allocated out of a 256 KiB chunk (one VMA per ~5,400 small
482// allocations instead of one per allocation). Larger requests take the ORIGINAL path untouched --
483// they are the ones plausibly relying on page alignment, and they are not where the leak lives.
484//
485// THE ZEROING CONTRACT IS LOAD-BEARING AND IS PRESERVED BY NEVER RECYCLING. Callers rely on mmap
486// returning zeroed memory (nx_mmapbal: "mmap zeroes, so an untouched slot reads empty with no init
487// loop"). Bytes handed out here come from a freshly mmapped chunk and are NEVER handed out twice, so
488// every region is zero-filled exactly as before. LIFO give-back on munmap was deliberately REJECTED:
489// it would recover memory but hand back dirty bytes, silently breaking every caller that trusts the
490// zero -- a correctness regression traded for a memory win, which is the wrong trade.
491//
492// KNOWN TRADE-OFF, stated rather than hidden: small allocations are now ADJACENT within a chunk
493// instead of isolated in their own pages. An overrun that today walks off the end of a page and
494// SIGSEGVs loudly may instead corrupt a neighbouring allocation quietly. NXA_GAP puts slack between
495// allocations and NXA_SMALL_MAX is kept deliberately low to bound the exposure, but the risk is real
496// and is the reason this starts at 256 rather than a page.
497// ---- MEMORY ORDERING, THE ONE DEFINITION -------------------------------------------------------
498// Moved here from nx_atom.nx on 2026-08-25 and DELETED from its two other copies
499// (nx_atomic_intrinsic_test, nx_simd_i32x8_test). Measured before the move, corpus_complete=1:
500// THREE files each declared NX_MO_SEQ_CST = 5 independently. A constant written in three places is
501// three rulers that agree until one of them does not.
502//
503// They live at THIS layer because the arena allocator below needs an ordering value for its own
504// lock, and this file cannot import nx_atom.nx -- nx_atom imports THIS file, so that direction is a
505// cycle. Everything that had these constants still has them: nx_atom.nx imports this file, and so
506// does every consumer of nx_atom.
507//
508// The __atomic_* forms these feed are COMPILER INTRINSICS, not library calls, so this file can use
509// them with no import at all. Verified in nx_x86_64_ctx rather than assumed: __atomic_cas_i64 emits
510// `lock cmpxchgq`, __atomic_faa_i64 emits `lock xaddq`, __atomic_fence emits `mfence`. On x86-64 the
511// ordering operand is not consulted by the emitter because those instructions are full barriers
512// regardless; it is carried for the RV64A backend, where it selects the aq/rl bits.
513const NX_MO_RELAXED: i64 = 0
514const NX_MO_CONSUME: i64 = 1
515const NX_MO_ACQUIRE: i64 = 2
516const NX_MO_RELEASE: i64 = 3
517const NX_MO_ACQ_REL: i64 = 4
518const NX_MO_SEQ_CST: i64 = 5
519
520const NXA_SMALL_MAX: i64 = 256
521const NXA_CHUNK: i64 = 262144
522const NXA_ALIGN: i64 = 16
523const NXA_GAP: i64 = 16
524const NXA_STATE: i64 = 4096
525// RING CANARY (temporary diagnostic): the single-slot canary checked only the immediately
526// previous allocation and reported ZERO overruns -- but the bisection proved the write is
527// DELAYED, landing after later allocations have been served. Track the last NXA_RING
528// allocations and re-verify every one of them on each call. Lives at i64 slot NXA_RBASE in
529// the state page; the reporter borrows bytes 64/128, so 512 is clear of it.
530const NXA_RING: i64 = 128
531const NXA_RBASE: i64 = 64
532// ---- ARENA MARK/RESET (2026-08-12, additive; the durable fix for bump-without-reset). The arena
533// abandons a full chunk on rollover, so a long-running accept loop accumulates chunks into one giant
534// coalesced VMA (hub_gw MEASURED 3.4GB over 64k requests). A daemon marks the arena AFTER startup and
535// resets at its accept-loop's quiescent point; reset munmaps every chunk allocated since the mark and
536// zeroes the marked chunk's reclaimed tail, so per-request small allocations reuse a bounded slab.
537// State slots (state page is 512 i64): [3]=chunk_count [4]=mark_valid [5]=mark_bump [6]=mark_chunk_end
538// [7]=mark_chunk_count; the chunk-base list lives at slots NXA_CHUNKBASE..+NXA_CHUNKMAX (clear of the
539// ring at 64..320 and the reporter scratch below 64). CONTRACT: the caller guarantees NO arena
540// allocation made after the mark is still referenced at reset (the accept-loop top, where the previous
541// request's frames have all returned -- the same quiescent point ss_cache_reap already uses). LARGE
542// (>NXA_SMALL_MAX) allocations take their own VMA and are NOT tracked here; a per-request large mmap
543// still needs its own munmap. Untracked-overflow (>NXA_CHUNKMAX chunks between resets) degrades to the
544// old leak for the excess, never corrupts.
545// ---- ARENA MUTUAL EXCLUSION (2026-08-25) -------------------------------------------------------
546// THE DEFECT: the bump-pointer advance below was a plain read-modify-write --
547// let p: i64 = nxa_st[0]
548// nxa_st[0] = p + need
549// -- so two threads that read nxa_st[0] before either wrote it BOTH RECEIVE THE SAME POINTER and
550// then write over each other. The chunk refill, the ring-canary scan and the nxa_st[2] counter have
551// the same shape. MEASURED while shipping structured concurrency: eight pool workers calling a
552// helper that allocates a 16-byte timespec raced this cursor and produced ARENA-OVERRUN
553// prev_alloc_size=16 followed by SIGSEGV. It generalises to EVERY small allocation from more than
554// one thread, which is why the scoped-spawn child body was written to allocate nothing at all.
555//
556// WHY A LOCK AND NOT A LOCK-FREE BUMP. A fetch-and-add on the cursor fixes only the fast path; two
557// threads can still both observe the chunk exhausted and both refill, and the canary ring and the
558// counter would still race. One lock over the whole mutable region is correct by inspection, which
559// on the allocator that every organ in the estate calls is worth more than a clever fast path.
560// THE COST IS NOT THE DOMINANT COST HERE: this function ALREADY walks all NXA_RING canary slots on
561// every allocation, so one uncontended `lock cmpxchgq` is far below the noise of work already done.
562//
563// SLOT 4 IS FREE BY THE LAYOUT ABOVE: [0] cursor, [1] limit, [2] ring counter, [3] chunk count, and
564// the ring starts at NXA_RBASE=64. It is also clear of the byte-64 and byte-128 scratch that
565// nxa_report_overrun formats digits into (slots 8 and 16), which slot 4 (bytes 32-39) does not touch.
566const NXA_LOCK: i64 = 4
567// A BOUND ON AN UNKNOWABLE WAIT, DERIVED RATHER THAN PICKED, AND ITS EXHAUSTION ANNOUNCES. The
568// longest thing the critical section can do is the NXA_RING canary scan plus one mmap, so a spin far
569// beyond that is not contention -- it is a holder that is never coming back. Eight times the ring
570// gives an order of magnitude of headroom over the longest legitimate hold; on reaching it the
571// allocator SAYS SO on stderr once and keeps waiting, because hanging visibly is recoverable and
572// corrupting silently is not, and dying inside the allocator would take down a process that may be
573// merely slow.
574const NXA_LOCK_WARN: i64 = NXA_RING * 8
575// Slot 5: "the contention hint has already been printed by this process". Also free by the layout
576// above and clear of every scratch region. It is a FLAG, not a counter, and it is set through a CAS
577// so the once-ness is itself race-free rather than depending on the lock it reports about.
578const NXA_LOCK_WARNED: i64 = 5
579
580const NXA_CHUNKBASE: i64 = 320
581const NXA_CHUNKMAX: i64 = 192
582
583// [0] = next free byte, [1] = one past the end of the current chunk. A static POINTER to a real
584// mmapped page rather than scalar statics, matching the idiom the corpus already proves; the state
585// page is taken through __syscall directly so this can never recurse into itself.
586static nxa_st: *i64
587
588// munmap -- free a region from sys_mmap. x86_64 munmap = 11; 11 is NOT an rv64 number in the compiler's
589// swap table, so the literal passes through untranslated = real munmap (unlike chdir, where rv64 80=fstat
590// intercepted it). CRITICAL for long-running loops: the supervisor's per-poll proc_* scans mmap 64KB+ each;
591// unfreed, the leak hits DSM's RLIMIT_AS -> mmap returns -12 -> the code writes through it -> SEGFAULT
592// (dmesg-proven: nx_hostctl segfault at 0xfffffffffffffff4). Free scan buffers to keep the supervisor alive.
593//
594// A small len means the region came from the bump arena above, because sys_mmap routes by the SAME
595// threshold. Unmapping an interior pointer would tear a hole in a chunk still holding other callers'
596// live allocations, so it is a no-op here. Balanced small callers therefore no longer return memory --
597// but they now cost ~48 bytes instead of 4096, so the arena wins by two orders of magnitude even
598// against code that was already correct.
599// Matching release for sys_mmap_try and other whole kernel mappings.
600// Never pass an arena allocation from sys_mmap: its small pointers may be interior.
601// Preserve the requested mapping length; the kernel applies its page rounding.
602const NXA_MAP_INVALID:i64=0-22 // Linux EINVAL, a protocol value rather than a resource budget.
603func sys_munmap_direct(addr:*u8,len:i64)->i64{
604 if (addr as i64)<=0||len<=0{return NXA_MAP_INVALID}
605 return __syscall(11,addr as i64,len,0,0,0,0)
606}
607
608func sys_munmap(addr: *u8, len: i64) -> i64 {
609 if len <= NXA_SMALL_MAX { return 0 }
610 return __syscall(11, addr as i64, len, 0, 0, 0, 0)
611}
612
613// Seek within a file. whence: 0=SEEK_SET, 1=SEEK_CUR, 2=SEEK_END.
614// Returns new file offset on success, -errno on failure.
615func sys_lseek(fd: i64, offset: i64, whence: i64) -> i64 {
616 return __syscall(SYS_LSEEK, fd, offset, whence, 0, 0, 0)
617}
618
619// ---- FILESYSTEM SPACE: THE AXIS THE ESTATE DID NOT HAVE (2026-08-28) -----------------------------
620// WHY THIS IS HERE AND NOT LEFT WHERE IT WAS. On 2026-08-28 a 100%-FULL DISK truncated a sibling seat's
621// MEMORY.md to 0 bytes -- open(path,"w") truncates before it writes, so a full volume does not refuse a
622// write, it DESTROYS the file. Nothing in the estate saw it coming: nx_resmon is "the resource axis
623// nx_health lacks" for MEMORY and SWAP, and a search for the disk primitive returned matches=0 for BOTH
624// sys_statfs and statvfs with corpus_complete=1. nx_res_census records the same absence in its own header.
625// The capability was not missing, it was DARK: nx_system_triage.tr_free_gb has read filesystem space since
626// 2026-06-10, in an _hdl_build organ that is NOT REGISTERED (nx_job_run refuses it as "not an unpinned
627// GREEN tool"), so the one instrument that could have warned was unreachable by any caller.
628// A CAPABILITY THAT EXISTS IN ONE UNREACHABLE ORGAN IS INDISTINGUISHABLE FROM ONE NOBODY BUILT.
629//
630// WHY THE RAW 137 AND NOT A SYS_ CONST. This file's dual-arch blocks are gated on TARGET_X86_64, which is
631// HARD-PINNED UNDEFINED, so the RV64 branch is what compiles and the x86 backend translates each number at
632// emit through x86ctx_rv64_to_x86_64_syscall -- whose default is `return num`. There is NO row for RV64 43
633// (statfs), so a SYS_STATFS=43 const would pass through unmapped to x86_64 43 = ACCEPT: a different
634// syscall, silently, on a path pointer. That is not a hypothesis -- nx_system_triage PROBE-PROVED it on
635// 2026-06-10: "rv64 43 returns -9 through the translation table; 137 raw matches df exactly." So 137 is
636// the MEASURED-CORRECT number for the target we actually emit, and it is named here ONCE instead of
637// sitting as a bare literal at each call site.
638// ⚠NAMED FOLLOW-UP, conflict-checked and deliberately NOT taken here: adding `if num == 43 { return 137 }`
639// to x86ctx_rv64_to_x86_64_syscall would make the arch-correct const work too. Nothing passes 43 as an x86
640// number (43 appears only as a translation TARGET, from RV64 202 accept), so the row is safe -- but it is a
641// COMPILER change that activates only on the next nx_cc self-host rebuild, and the working path needs none.
642//
643// struct statfs (x86_64) as i64 slots: 0 f_type, 1 f_bsize, 2 f_blocks, 3 f_bfree, 4 f_bavail, 5 f_files.
644// f_bavail (not f_bfree) is the honest number for "will my write succeed": it excludes the root reserve, so
645// it reports FULLER than root would see. Wrong in the safe direction, and said out loud rather than implied.
646// ⚠THE IMPRECISION, MEASURED AND NAMED SO NOBODY LATER "FIXES" IT INTO AGREEING WITH df: this permil is
647// NOT df's Use%. df computes Used/(Used+Available), which EXCLUDES the root-reserved blocks from its
648// denominator; this computes (blocks-bavail)/blocks, which counts the reserve as used. VERIFIED against df
649// on 2026-08-28: avail_bytes came back 958449582080, which is EXACTLY df's Available of 935985920 KiB, while
650// the same volume read 113 permil here and 7% there -- both correct, measuring different things. Both reach
651// their maximum at the SAME event (bavail = 0), so a threshold calibrated against THIS metric alarms at the
652// same moment a writer actually hits the wall; it simply sits higher below that. Calibrate thresholds to
653// this definition, and do not import a df-derived number as if it were the same quantity.
654const SYS_STATFS_X86_MEASURED: i64 = 137
655const STATFS_BUF_BYTES: i64 = 144
656const STATFS_I_BSIZE: i64 = 1
657const STATFS_I_BLOCKS: i64 = 2
658const STATFS_I_BAVAIL: i64 = 4
659const STATFS_PERMIL: i64 = 1000
660const STATFS_ERR: i64 = 0 - 1
661
662// raw statfs into a caller-supplied 144-byte buffer. 0 = ok, non-zero = the kernel's negative errno.
663func sys_statfs(path: *u8, buf: *i64) -> i64 {
664 return __syscall(SYS_STATFS_X86_MEASURED, path, buf, 0, 0, 0, 0)
665}
666
667// bytes available to a non-root writer on the filesystem holding `path`; STATFS_ERR if statfs failed.
668func sys_fs_avail_bytes(path: *u8) -> i64 {
669 let buf: *i64 = sys_mmap(STATFS_BUF_BYTES) as *i64
670 if sys_statfs(path, buf) != 0 { return STATFS_ERR }
671 return buf[STATFS_I_BSIZE] * buf[STATFS_I_BAVAIL]
672}
673
674// USED per-mille of the filesystem holding `path`, counted against what a non-root writer can reach:
675// (blocks - bavail) * 1000 / blocks. STATFS_ERR if statfs failed or the volume reports zero blocks --
676// an UNMEASURABLE volume must never read as 0 permil used, which is the most flattering possible lie.
677func sys_fs_used_permil(path: *u8) -> i64 {
678 let buf: *i64 = sys_mmap(STATFS_BUF_BYTES) as *i64
679 if sys_statfs(path, buf) != 0 { return STATFS_ERR }
680 let blocks: i64 = buf[STATFS_I_BLOCKS]
681 if blocks <= 0 { return STATFS_ERR }
682 let avail: i64 = buf[STATFS_I_BAVAIL]
683 return ((blocks - avail) * STATFS_PERMIL) / blocks
684}
685
686func sys_exit(code: i64) -> i64 {
687 return __syscall(SYS_EXIT, code, 0, 0, 0, 0, 0)
688}
689
690// mmap anonymous R/W memory; returns raw bytes. Fixed flags:
691// PROT_READ|PROT_WRITE = 3, MAP_PRIVATE|MAP_ANONYMOUS = 0x22, fd=-1.
692// FAIL-CLOSED ON A REFUSED MAPPING (2026-08-07). MEASURED: the corpus has 90,817 sys_mmap call sites
693// and SIX of them check the result -- all six in test probes whose response is sys_exit anyway. So
694// 90,811 sites take whatever this returns and write through it. When the kernel refuses, that value is
695// -errno, and the write lands at 0xfffffffffffffff4 (-12, ENOMEM). That is not a hypothetical: dmesg
696// on this host recorded it hourly in nx_web_shard_compact, and 18 times in nx_web_crawl_step.
697// Returning a poisoned pointer to 90,811 unguarded callers is the defect. Dying here is strictly safer
698// than dying there: the process ends either way, but this way there is no memory corruption first and
699// the failure is NAMED instead of arriving as a bare segfault address an operator has to decode.
700// This is the never-brick shape -- fail-safe BY CONSTRUCTION, not by every caller remembering.
701// KNOWN COST, stated: nx_mmap_probe / test_munmap deliberately provoke a refusal to observe it. They
702// now exit here with code 12 rather than printing their own verdict. Six probes lose a diagnostic;
703// 90,811 sites stop corrupting memory.
704// ===== TEMPORARY DIAGNOSTIC -- ARENA OVERRUN CANARY (2026-08-07) =====================================
705// ⛔DO NOT BLESS A COMPILER BUILT WITH THIS. The canary writes 0xC7 into the NXA_GAP slack that a
706// caller could otherwise legitimately read as zeros, so it changes observable behaviour for any code
707// that reads past its declared size -- which is precisely the code being hunted.
708// PURPOSE: at NXA_SMALL_MAX=256 the compiler produces 14 SPURIOUS type diagnostics (it reports
709// `arg 2 is an INTEGER but the parameter is a POINTER` against a parameter DECLARED `j: *u8`), i.e.
710// something writes past its allocation and corrupts the parser's type table. At threshold 64 the same
711// requests each get a 4096-byte page whose slack absorbs it. Reading the source found nothing: the
712// two obvious suspects (nx_ir.nx:70 sys_mmap(104), nx_parse.nx:868 sys_mmap(256)) are both correctly
713// sized and bounded. So stop reading and MEASURE: stamp each small allocation's gap, verify the
714// PREVIOUS one on the next call, and print the size of whichever allocation was overrun.
715// Writes to fd 2 without allocating -- it borrows scratch inside the arena state page, because a
716// reporter that called sys_mmap would recurse into the thing it is instrumenting.
717// Dump n bytes at src to fd 2, unprintables as '.', using scratch at state+256 (the ring starts at
718// state+512 and the decimal scratch sits at +64/+128, so this cannot collide with either). n is
719// capped by callers at 48 so the buffer stays clear of the ring.
720func nxa_dump_printable(src: i64, n: i64) -> i64 {
721 let o: *u8 = ((nxa_st as i64) + 256) as *u8
722 var i: i64 = 0
723 while i < n {
724 let sp: *u8 = (src + i) as *u8
725 var c: i64 = sp[0] as i64
726 if c < 32 { c = 46 }
727 if c > 126 { c = 46 }
728 o[i] = c as u8
729 i = i + 1
730 }
731 o[n] = 10 as u8
732 sys_write(2, o, n + 1)
733 return 0
734}
735
736// FINGERPRINT (2026-08-12): the size alone + all-zeros byte dump never named the site. The ring already
737// records each allocation's REQUESTED size in counter order, so the recent size SEQUENCE fingerprints the
738// code path that was running when the overrun landed (a distinctive run of sizes is near-unique to a
739// function). Writes to fd 2 borrowing state-page scratch at bytes 320/340 (clear of the ring at byte 512,
740// the reporter decimals at 64/128, and the byte-dump at 256). No allocation -- must not recurse into sys_mmap.
741func nxa_dump_sizes() -> i64 {
742 sys_write(2, " ring_sizes(old->recent): " as *u8, 27)
743 let scr: *u8 = ((nxa_st as i64) + 320) as *u8
744 let out2: *u8 = ((nxa_st as i64) + 340) as *u8
745 let cnt: i64 = nxa_st[2]
746 var start: i64 = cnt - 32
747 if start < 0 { start = 0 }
748 var idx: i64 = start
749 while idx < cnt {
750 let slot: i64 = idx % NXA_RING
751 let szv: i64 = nxa_st[NXA_RBASE + slot * 2 + 1]
752 var m: i64 = szv
753 var k: i64 = 0
754 if m == 0 { scr[0] = 48 as u8; k = 1 }
755 while m > 0 { scr[k] = (48 + (m % 10)) as u8; m = m / 10; k = k + 1 }
756 var j: i64 = 0
757 while j < k { out2[j] = scr[k - 1 - j]; j = j + 1 }
758 out2[k] = 44 as u8
759 sys_write(2, out2, k + 1)
760 idx = idx + 1
761 }
762 sys_write(2, "\n" as *u8, 1)
763 return 0
764}
765
766func nxa_report_overrun(sz: i64, gs: i64) -> i64 {
767 let msg: *u8 = "ARENA-OVERRUN prev_alloc_size=" as *u8
768 var n: i64 = 0
769 while msg[n] != (0 as u8) { n = n + 1 }
770 sys_write(2, msg, n)
771 let b: *u8 = ((nxa_st as i64) + 64) as *u8
772 let o: *u8 = ((nxa_st as i64) + 128) as *u8
773 var m: i64 = sz
774 var k: i64 = 0
775 if m == 0 { b[0] = 48 as u8; k = 1 }
776 while m > 0 { b[k] = (48 + (m % 10)) as u8; m = m / 10; k = k + 1 }
777 var i: i64 = 0
778 while i < k { o[i] = b[k - 1 - i]; i = i + 1 }
779 o[k] = 10 as u8
780 sys_write(2, o, k + 1)
781 // The SIZE alone did not name the site (four 80-byte victims, and the two unbounded 80-byte
782 // buffers in nx_parse.nx were sized from their inputs with no effect). So show the DATA: the
783 // victim's own bytes identify the buffer, and the bytes written past its end identify the WRITER.
784 let algn: i64 = (sz + NXA_ALIGN - 1) / NXA_ALIGN * NXA_ALIGN
785 let base: i64 = gs - algn
786 var dn: i64 = sz
787 if dn > 48 { dn = 48 }
788 sys_write(2, " own : " as *u8, 8)
789 nxa_dump_printable(base, dn)
790 sys_write(2, " over: " as *u8, 8)
791 nxa_dump_printable(gs, 16)
792 nxa_dump_sizes()
793 return 0
794}
795
796func nxa_die(msg: *u8) -> i64 {
797 var n: i64 = 0
798 while msg[n] != (0 as u8) { n = n + 1 }
799 sys_write(2, msg, n)
800 sys_exit(12)
801 return 0
802}
803
804// Address of the arena lock word. Valid only once nxa_st exists; every caller below has already
805// ensured that, and the state-page creation itself is discussed at the take site.
806func nxa_lock_addr() -> *i64 {
807 return ((nxa_st as i64) + NXA_LOCK * 8) as *i64
808}
809
810// __atomic_cas_i64 returns 1 when it wrote and 0 when it did not, so the spin condition is == 0.
811// It is a COMPILER INTRINSIC, not a call into nx_atom -- that module imports THIS file, so importing
812// it back would be a cycle. Verified in nx_x86_64_ctx rather than assumed: it lowers to a genuine
813// `lock cmpxchgq` followed by sete, which is a full barrier on x86-64 whatever ordering is passed.
814func nxa_lock_take() -> i64 {
815 var spins: i64 = 0
816 while __atomic_cas_i64(nxa_lock_addr(), 0, 1, NX_MO_ACQUIRE) == 0 {
817 spins = spins + 1
818 // Fires EXACTLY ONCE, on equality rather than on exceeding, so a genuinely long wait reports
819 // itself without turning the allocator into a log generator.
820 if spins == NXA_LOCK_WARN {
821 // ONCE PER PROCESS, not once per acquisition. MEASURED 2026-08-25 and this is a
822 // correction to the first cut of this very function: it fired on equality per CALL, and
823 // eight workers contending LEGITIMATELY produced hundreds of identical lines in a single
824 // gate run. A DIAGNOSTIC THAT FIRES CONSTANTLY IS ONE EVERY READER LEARNS TO IGNORE, and
825 // this one writes to the stderr of every organ in the estate.
826 // The threshold was derived from the longest the critical section can run, which bounds
827 // ONE hold and says nothing about QUEUE DEPTH: with N threads waiting, a legitimate wait
828 // is N holds and can exceed any per-section derivation. So this is a NOISE FLOOR for a
829 // hint, never a correctness bound -- it never fails, never delays, and never repeats.
830 // The flag is set through a CAS so the once-ness cannot itself race.
831 let wflag: *i64 = ((nxa_st as i64) + NXA_LOCK_WARNED * 8) as *i64
832 if __atomic_cas_i64(wflag, 0, 1, NX_MO_ACQ_REL) == 1 {
833 let m: *u8 = "ARENA-LOCK: sustained allocator contention seen (reported once per process; a hint, not an error -- allocation proceeds normally).\n" as *u8
834 var mn: i64 = 0
835 while m[mn] != (0 as u8) { mn = mn + 1 }
836 sys_write(2, m, mn)
837 }
838 }
839 }
840 return 0
841}
842
843func nxa_lock_give() -> i64 {
844 // nx_cc refuses a bare intrinsic statement ("computes a value and never uses it") and an atomic
845 // store has no result worth using, so it is bound and discarded -- the same shape nx_atom uses
846 // for exactly this reason. The contract is unchanged: this returns 0 either way.
847 let discarded: i64 = __atomic_store_i64(nxa_lock_addr(), 0, NX_MO_RELEASE)
848 if discarded != 0 { return 0 }
849 return 0
850}
851
852// Optional mapping for request boundaries that must report allocation refusal.
853// Unlike sys_mmap, this never aborts the process and never consumes arena storage.
854// Release successful mappings with sys_munmap_direct, not the arena-aware sys_munmap.
855// A successful reservation can still fail on later physical-memory pressure; callers
856// must not describe virtual address admission as guaranteed resident RAM.
857func sys_mmap_try(size:i64)->*u8 {
858 if size<=0 { return 0 as *u8 }
859 let mapped:i64=__syscall(SYS_MMAP,0,size,3,0x22,-1,0)
860 if mapped<=0 { return 0 as *u8 }
861 return mapped as *u8
862}
863
864func sys_mmap(size: i64) -> *u8 {
865 // Large requests keep the EXACT original behaviour, byte for byte: page-aligned, own VMA. Any
866 // caller that depends on page alignment is allocating at least a page, so the arena cannot reach
867 // it. Every failure path below also falls back to this same call, so an exhausted arena degrades
868 // to the old allocator rather than returning a bad pointer.
869 if size > NXA_SMALL_MAX {
870 let big: i64 = __syscall(SYS_MMAP, 0, size, 3, 0x22, -1, 0)
871 if big <= 0 { nxa_die("FATAL sys_mmap: kernel refused a large mapping (ENOMEM). Refusing to return a poisoned pointer -- a write through it would corrupt memory.\n" as *u8) }
872 return big as *u8
873 }
874 if (nxa_st as i64) == 0 {
875 let s: i64 = __syscall(SYS_MMAP, 0, NXA_STATE, 3, 0x22, -1, 0)
876 if s <= 0 {
877 // arena state page refused -- degrade to the plain allocator, and only die if THAT fails too
878 let f1: i64 = __syscall(SYS_MMAP, 0, size, 3, 0x22, -1, 0)
879 if f1 <= 0 { nxa_die("FATAL sys_mmap: kernel refused the arena state page AND the fallback mapping (ENOMEM).\n" as *u8) }
880 return f1 as *u8
881 }
882 nxa_st = s as *i64
883 }
884 // EVERYTHING FROM HERE TO THE RETURN TOUCHES SHARED STATE: the cursor, the limit, the chunk
885 // table, the canary ring and the ring counter. It is ONE critical section because the refill
886 // decision and the bump that depends on it cannot be separated without reintroducing the race.
887 // The state page itself is created ABOVE this point, unlocked: two threads arriving there
888 // together would each map a page and one would win the static, leaking the other's 4 KiB but
889 // corrupting nothing, and in practice the arena is warm long before any thread is spawned
890 // because spawning one allocates. That residual is NAMED here rather than papered over.
891 nxa_lock_take()
892 var need: i64 = size
893 if need <= 0 { need = 1 }
894 need = (need + NXA_ALIGN - 1) / NXA_ALIGN * NXA_ALIGN + NXA_GAP
895 if nxa_st[0] + need > nxa_st[1] {
896 let c: i64 = __syscall(SYS_MMAP, 0, NXA_CHUNK, 3, 0x22, -1, 0)
897 if c <= 0 {
898 // chunk refused -- degrade to the plain allocator, and only die if THAT fails too.
899 // RELEASE FIRST: this is the one path that leaves the critical section early, and a lock
900 // held across a degraded return would wedge every other allocator in the process.
901 nxa_lock_give()
902 let f2: i64 = __syscall(SYS_MMAP, 0, size, 3, 0x22, -1, 0)
903 if f2 <= 0 { nxa_die("FATAL sys_mmap: kernel refused an arena chunk AND the fallback mapping (ENOMEM).\n" as *u8) }
904 return f2 as *u8
905 }
906 nxa_st[0] = c
907 nxa_st[1] = c + NXA_CHUNK
908 // track the chunk base so arena_reset can munmap post-mark chunks (additive; guarded at cap).
909 if nxa_st[3] < NXA_CHUNKMAX { nxa_st[NXA_CHUNKBASE + nxa_st[3]] = c; nxa_st[3] = nxa_st[3] + 1 }
910 }
911 // ---- RING CANARY (temporary diagnostic) ----
912 var rk: i64 = 0
913 while rk < NXA_RING {
914 let gs0: i64 = nxa_st[NXA_RBASE + rk * 2]
915 if gs0 != 0 {
916 var bi: i64 = 0
917 var bad: i64 = 0
918 while bi < 8 {
919 let bp: *u8 = (gs0 + bi) as *u8
920 if bp[0] != (199 as u8) { bad = 1; bi = 8 } else { bi = bi + 1 }
921 }
922 if bad == 1 {
923 nxa_report_overrun(nxa_st[NXA_RBASE + rk * 2 + 1], gs0)
924 nxa_st[NXA_RBASE + rk * 2] = 0
925 }
926 }
927 rk = rk + 1
928 }
929 let p: i64 = nxa_st[0]
930 nxa_st[0] = p + need
931 let gs: i64 = p + need - NXA_GAP
932 var gj: i64 = 0
933 while gj < NXA_GAP { let q: *u8 = (gs + gj) as *u8; q[0] = 199 as u8; gj = gj + 1 }
934 let slot: i64 = nxa_st[2] % NXA_RING
935 nxa_st[NXA_RBASE + slot * 2] = gs
936 nxa_st[NXA_RBASE + slot * 2 + 1] = size
937 nxa_st[2] = nxa_st[2] + 1
938 // The ONLY other exit from the critical section is the degraded chunk-refill path above, which
939 // releases before it returns. Every shared write is now behind this pair.
940 nxa_lock_give()
941 return p as *u8
942}
943
944// arena_mark: force the arena warm (so a first chunk + state page exist), then record the current
945// position as the reset barrier. Returns 1. A daemon calls this ONCE after startup, before its loop.
946func sys_arena_mark() -> i64 {
947 let warm: *u8 = sys_mmap(1) // ensures nxa_st + chunk[0] exist; the 1 byte is itself arena scratch
948 if (warm as i64) == 0 { return 0 }
949 nxa_st[4] = 1
950 nxa_st[5] = nxa_st[0]
951 nxa_st[6] = nxa_st[1]
952 nxa_st[7] = nxa_st[3]
953 return 1
954}
955
956// arena_reset: reclaim everything allocated since the mark. munmap post-mark chunks, restore the bump
957// to the mark, ZERO the marked chunk's reclaimed tail (preserves the mmap-returns-zeroed contract for
958// recycled bytes), and CLEAR the ring canary (its stamps may point into a just-munmap'd chunk, and a
959// stale deref on the next alloc would SEGV). Returns 1 on reset, 0 if no mark was set.
960func sys_arena_reset() -> i64 {
961 if (nxa_st as i64) == 0 { return 0 }
962 if nxa_st[4] != 1 { return 0 }
963 var i: i64 = nxa_st[7]
964 while i < nxa_st[3] {
965 let cb: i64 = nxa_st[NXA_CHUNKBASE + i]
966 if cb != 0 { __syscall(11, cb, NXA_CHUNK, 0, 0, 0, 0); nxa_st[NXA_CHUNKBASE + i] = 0 }
967 i = i + 1
968 }
969 nxa_st[3] = nxa_st[7]
970 nxa_st[0] = nxa_st[5]
971 nxa_st[1] = nxa_st[6]
972 var z: i64 = nxa_st[0]
973 while z < nxa_st[1] { let q: *u8 = z as *u8; q[0] = 0 as u8; z = z + 1 }
974 var r: i64 = 0
975 while r < NXA_RING * 2 { nxa_st[NXA_RBASE + r] = 0; r = r + 1 }
976 nxa_st[2] = 0
977 return 1
978}
979
980// mmap anonymous SHARED R/W memory -- ONE region that survives fork() so all
981// children see each other's writes (MAP_SHARED|MAP_ANONYMOUS = 0x21). Allocate
982// in the PARENT before fork. Foundation for the fork-per-connection video relay
983// (peers in separate children share the per-room frame table).
984func sys_mmap_shared(size: i64) -> *u8 {
985 let r: i64 = __syscall(SYS_MMAP, 0, size, 3, 0x21, -1, 0)
986 return r as *u8
987}
988
989// madvise(2) -- prefetch/advice hints for mapped ranges. MADV_WILLNEED=3 batches page-ins so a
990// serial fault loop over a cold file-backed mmap becomes parallel disk readahead (the dp-web-pub
991// stage-2 p95 fix, 2026-08-12). RAW x86_64 NUMBER 28 ON PURPOSE (sys_exit_group's raw-231 pattern):
992// the portable rv64/asm-generic number is 233 and x86ctx_rv64_to_x86_64_syscall has no 233 row in
993// the DEPLOYED compiler, so a portable const would emit x86_64 233 = epoll_ctl (the wrong-syscall-
994// not-an-error class; see the setpgid/flock rows). The 233->28 row is staged in nx_x86_64_ctx.nx and
995// activates on the next nx_cc self-host rebuild; flip this to the portable const AFTER that lands.
996// Signature bite-proven by nx_madvise_probe (0 / -12 ENOMEM / -22 EINVAL). Advisory contract: callers
997// may ignore the return value -- a failed hint costs nothing but the cold-read behaviour it hints away.
998func sys_madvise(addr: *u8, len: i64, advice: i64) -> i64 {
999 return __syscall(28, addr, len, advice, 0, 0, 0)
1000}
1001
1002// openat flavors used by the compiler driver. AT_FDCWD = -100 (declared ABOVE, next to its first
1003// reader -- see the miscompile note there; do NOT move it back down).
1004// O_RDONLY = 0; O_CREAT|O_WRONLY|O_TRUNC = 0x241 on Linux RV64.
1005const O_RDONLY: i64 = 0
1006const O_WRONLY_CT: i64 = 0x241 // O_CREAT | O_WRONLY | O_TRUNC
1007const O_WRONLY_CA: i64 = 0x441 // O_CREAT | O_WRONLY | O_APPEND
1008
1009func sys_openat_rd(path: *u8) -> i64 {
1010 return __syscall(SYS_OPENAT, AT_FDCWD, path, O_RDONLY, 0, 0, 0)
1011}
1012
1013// O_RDWR|O_CREAT (NO truncate) -- for offset-addressed persistent files like the metrics ring TSDB
1014// (create if missing, then lseek+read/write records in place, never truncating existing history).
1015const O_RDWR_CREATE: i64 = 0x42
1016func sys_openat_rdwr(path: *u8, mode: i64) -> i64 {
1017 return __syscall(SYS_OPENAT, AT_FDCWD, path, O_RDWR_CREATE, mode, 0, 0)
1018}
1019
1020// ★★★THE FILE MODE IS THE HALF OF THIS INTERFACE THAT WAS NEVER NAMED. The O_ flags above are named
1021// consts in hex WITH a decoding comment; the mode passed beside them is a bare literal at every call
1022// site. MEASURED 2026-08-14 (coverage_complete=1 corpus_complete=1 over 23,053 files):
1023// - 29 organs passed the mode as a bare DECIMAL literal, which no reader decodes as rw-r--r--
1024// without stopping to convert it. ⚠THE FIRST COUNT PUBLISHED HERE WAS 26: the scan was scoped to
1025// runtime/_hdl_build/ and the SUBDIRECTORY's count was published as the estate figure -- three
1026// more (nx_forge_rag, nx_gpu_export, nx_bvhfk) sat one level up in runtime/.
1027// ★A COUNT INHERITS THE SCOPE OF ITS SCAN, AND THE SCOPE IS THE PART NOBODY PRINTS BESIDE IT.
1028// ⚠The offending call is deliberately NOT spelled out literally in this comment: prose is source
1029// bytes, so writing the pattern here would make every future grep for it match this note;
1030// - 10 MORE each define their OWN private 0644 const (IP_ VR_ VP_ LIVE_ FD_ FP_ WL_ PUB_ REG_ HFF_),
1031// nine written 0x1a4 and one written 420 -- THE SAME CONSTANT IN TWO DIFFERENT BASES.
1032// Ten seats each solved this privately and none put the answer where the next one would look. That is
1033// the duplicate-ruler defect precisely: changing the estate's default artifact mode today means finding
1034// 39 sites in two notations and hoping none was missed. One name, in the shim every organ already
1035// imports, is the entire fix -- and it belongs HERE, beside the flags, not in a 40th private copy.
1036const MODE_0644: i64 = 0x1a4 // rw-r--r-- : default mode for a generated artifact
1037// rwxr-xr-x : default mode for a created DIRECTORY. A directory without the execute bit cannot be
1038// traversed, so MODE_0644 is not merely stricter here -- it is wrong, and the failure surfaces later
1039// as an unopenable path rather than as a refused mkdir. Named beside its sibling so the choice is a
1040// lookup rather than a recollection; the estate otherwise spells this as a raw 0x1ed at every site.
1041const MODE_0755: i64 = 0x1ed
1042// Seconds of ZERO PROGRESS on one socket operation before an accepted connection is abandoned.
1043// A single-threaded accept-loop daemon that loop-reads to Content-Length can be starved FOREVER by one
1044// peer that declares a body it never finishes sending -- a one-request DoS, hostile OR merely buggy.
1045// nx_dos_timeout_scan supervises the class and named 16 daemons carrying no timeout at all; the cure is
1046// sys_set_socket_timeout(cfd, ACCEPT_TMO_S) folded in right after accept.
1047// WHY 30 AND NOT THE 5 THE LOGIN DAEMONS USE: this bound must be wrong in the direction of SERVING, not
1048// of dropping. The attack is an UNBOUNDED wait, so ANY finite bound closes it; a short one additionally
1049// risks aborting a legitimate slow client. 30s of zero progress on a single recv/send is pathological
1050// for every daemon in the class -- including the streaming ones, where data is flowing and the timer
1051// never approaches its bound -- while still converting an infinite starvation into a bounded one.
1052// It is the calibration nx_galx_bridge already uses for an accepted cfd; named here rather than copied
1053// into a 16th private literal, exactly as MODE_0644 above.
1054const ACCEPT_TMO_S: i64 = 30
1055func sys_openat_wr(path: *u8, mode: i64) -> i64 {
1056 return __syscall(SYS_OPENAT, AT_FDCWD, path, O_WRONLY_CT, mode, 0, 0)
1057}
1058
1059// Linux O_WRONLY | O_CREAT | O_EXCL. An existing final component, including
1060// a symlink, is a conflict; callers acquire ownership only on success.
1061const O_WRONLY_CREATE_EXCLUSIVE: i64 = 0x1 | 0x40 | 0x80
1062func sys_openat_exclusive(path: *u8, mode: i64) -> i64 {
1063 return __syscall(SYS_OPENAT, AT_FDCWD, path, O_WRONLY_CREATE_EXCLUSIVE, mode, 0, 0)
1064}
1065
1066// Linux O_DIRECTORY: require a directory, rather than merely an openable node.
1067const O_DIRECTORY: i64 = 0x10000
1068func sys_openat_directory(path: *u8) -> i64 {
1069 return __syscall(SYS_OPENAT, AT_FDCWD, path, O_RDONLY | O_DIRECTORY, 0, 0, 0)
1070}
1071
1072// Open path for append (create if missing). Used by append-only
1073// journals such as .race_telemetry.tsv. RV64 syscall numbers; the
1074// x86_64 mirror lives in nx_syscalls_x86_64.nx.
1075func sys_openat_append(path: *u8, mode: i64) -> i64 {
1076 return __syscall(SYS_OPENAT, AT_FDCWD, path, O_WRONLY_CA, mode, 0, 0)
1077}
1078
1079// Linux open ABI flags: acquire close-on-exec atomically and refuse a final
1080// symlink. Nonblocking also prevents an unexpected FIFO from stalling admission.
1081const O_CLOEXEC: i64 = 0x80000
1082const O_NOFOLLOW: i64 = 0x20000
1083const O_NONBLOCK: i64 = 0x800
1084const MODE_0600: i64 = 0x180
1085func sys_openat_lock(path: *u8) -> i64 {
1086 return __syscall(SYS_OPENAT, AT_FDCWD, path, O_WRONLY_CA | O_CLOEXEC | O_NOFOLLOW | O_NONBLOCK, MODE_0600, 0, 0)
1087}
1088
1089// symlinkat(target, AT_FDCWD, linkpath) -- raw x86_64 266 forced RUNTIME (the chdir escape, same as
1090// readlinkat below). THE atomic-repoint primitive for release management: create releases/current.new ->
1091// sys_renameat over releases/current = an atomic symlink swap (golive/rollback are instant + crash-safe).
1092// 0 on success, -errno (notably -EEXIST=-17 if linkpath exists -- create the .new name, then rename).
1093func sys_symlinkat(target: *u8, linkpath: *u8) -> i64 {
1094 let nbox: *i64 = sys_mmap(16) as *i64
1095 nbox[0] = 266
1096 let r: i64 = __syscall(nbox[0], target as i64, AT_FDCWD, linkpath as i64, 0, 0, 0)
1097 sys_munmap(nbox as *u8, 16)
1098 return r
1099}
1100
1101// readlinkat(AT_FDCWD, path, buf, cap) -- raw x86_64 267 forced RUNTIME (the chdir escape: keep the
1102// number out of the rv64->x86 constant-translate path). Returns link length (NO NUL appended), -errno
1103// on fail. nbox is munmap'd before return: the daemon supervisor calls this hundreds of times PER CYCLE
1104// (exe-identity sweeps), and a leaked page per call is exactly the VSZ-balloon class that broke fork.
1105func sys_readlinkat(path: *u8, buf: *u8, cap: i64) -> i64 {
1106 let nbox: *i64 = sys_mmap(16) as *i64
1107 nbox[0] = 267
1108 let r: i64 = __syscall(nbox[0], AT_FDCWD, path as i64, buf as i64, cap, 0, 0)
1109 sys_munmap(nbox as *u8, 16)
1110 return r
1111}
1112
1113// Atomically replace newpath with oldpath (rename(2) on one filesystem: a concurrent reader sees the
1114// whole old file or the whole new file, never a torn read). The S-class content-publish primitive:
1115// write the new page to a temp file, then sys_renameat(tmp, live) -> hot-swap, NO rm+ln race.
1116// renameat2: rv64=276, x86_64=316, flags=0. The known-good compiler translates most rv64 syscall
1117// numbers to the x86_64 target but its table MISSES 276 -- verified 2026-06-14 via nx_rename_probe:
1118// raw 276 -> -EINVAL (lands on x86_64 `tee`), raw 316 -> renames OK. That silently broke every
1119// cst_write_atomic publish (page.html.new written, never swapped in). Try the x86_64 number first
1120// (works on every x86_64 build incl. known-good); fall back to the rv64 number for native-rv64 or
1121// translating compilers that do map it. flags=0 so renameat2 == renameat semantics.
1122func sys_renameat(oldpath: *u8, newpath: *u8) -> i64 {
1123 let r: i64 = __syscall(316, AT_FDCWD, oldpath, AT_FDCWD, newpath, 0, 0)
1124 if r == 0 { return 0 }
1125 return __syscall(276, AT_FDCWD, oldpath, AT_FDCWD, newpath, 0, 0)
1126}
1127
1128// fsync(2): flush file (or directory) data+metadata to stable storage.
1129// PROBE-PROVEN 2026-06-10 (_fsync_probe): rv64 82 is NOT in the compiler's
1130// translation table (lands on x86 rename -> -EFAULT both ways); direct
1131// x86_64 74 passes through raw (the unlinkat-263 precedent) and behaves as
1132// fsync (0 on a valid fd, -9 EBADF on a bad one). Storage commit points
1133// fsync the data files AND their directory around rename(2) so a committed
1134// segment survives power loss, not just process death.
1135func sys_fsync(fd: i64) -> i64 {
1136 return __syscall(74, fd, 0, 0, 0, 0, 0)
1137}
1138
1139// flock(2): BSD-style whole-file ADVISORY lock. rv64 32 -> x86_64 73 via the compiler's
1140// x86ctx_rv64_to_x86_64_syscall table (nx_x86_64_ctx.nx:961, PROVEN LIVE in flock_deploy.log).
1141// op: SYS_LOCK_SH=1 / SYS_LOCK_EX=2 / SYS_LOCK_NB=4 (OR) / SYS_LOCK_UN=8. Returns 0 on success,
1142// -errno on failure. Used by the framed-append durability floor to serialize the write-until-
1143// complete loop so a partial/short write under contention can NEVER misalign a concurrent appender
1144// (O_APPEND single-write atomicity is necessary but not sufficient on every fs -- the lock makes
1145// the whole framed record write atomic against other lockers). Additive: no existing caller in
1146// this file changes. NOTE: nx_flock.nx is a separate organ importing the LEGACY "syscalls.nx"
1147// name; this wrapper lives HERE so organs already on nx_syscalls.nx (e.g. nx_framed_append) get
1148// flock without a second import (double-import rc=6 trap).
1149const SYS_LOCK_SH: i64 = 1
1150const SYS_LOCK_EX: i64 = 2
1151const SYS_LOCK_NB: i64 = 4
1152const SYS_LOCK_UN: i64 = 8
1153func sys_flock(fd: i64, op: i64) -> i64 {
1154 return __syscall(32, fd, op, 0, 0, 0, 0)
1155}
1156
1157// newfstatat(2): stat `path` into a 144-byte x86-64 struct stat at `statbuf`. x86_64 nr 262 is passed
1158// DIRECTLY (the unlinkat-263 / fsync-74 precedent: stat-family rv64 numbers aren't in the compiler's
1159// translation table, so a raw x86_64 number passes through untranslated). Returns 0 on success, <0
1160// (e.g. -2 ENOENT) on error. st_mtim.tv_sec @ offset 88, st_mtim.tv_nsec @ 96 (the freshness channel).
1161func sys_fstatat(path: *u8, statbuf: *u8) -> i64 {
1162 return __syscall(262, AT_FDCWD, path, statbuf, 0, 0, 0)
1163}
1164
1165// utimensat(2): set `path` atime+mtime from `times` (a struct timespec[2] = [atime.sec,atime.nsec,
1166// mtime.sec,mtime.nsec]). x86_64 nr 280 passed DIRECTLY. A sovereign `touch`; also makes freshness
1167// tests deterministic. Returns 0 on success, <0 on error.
1168func sys_utimensat(path: *u8, times: *i64) -> i64 {
1169 return __syscall(280, AT_FDCWD, path, times as i64, 0, 0, 0)
1170}
1171
1172// ---- sovereign host control-plane syscalls (x86_64; single unconditional consts,
1173// per the known-good-compiler @ifdef finding). The Nishi supervisor uses these to
1174// manage the daemon lifecycle WITHOUT any shell (no pkill / mkdir / chmod glue). ----
1175
1176// COMPILER NOTE: the known-good compiler BAKES whole function bodies by NAME for some syscalls
1177// (proven via emitted .s: a function literally named sys_kill emits number 8, sys_chmod emits 155
1178// -- both wrong, regardless of the const referenced). So these wrappers use NON-baked names
1179// (nx_kill / nx_chmod). sys_mkdir / sys_renameat are not baked, so those keep the sys_ name.
1180
1181// DESIGN: __syscall takes the RV64/generic number; the compiler's x86ctx_rv64_to_x86_64_syscall table
1182// (nx_x86_64_ctx.nx) translates it to the build target. So pass the RV64 number. These four were added
1183// to that sovereign table 2026-06-06 (kill 129->62, mkdirat 34->258, fchmodat 53->268, renameat2
1184// 276->316); x86 kill(62) had collided with rv64 lseek(62), x86 fchmodat(268) with rv64 pivot_root(268).
1185
1186// kill(pid, sig) -- rv64 129 -> x86_64 62. SIGTERM=15 / SIGKILL=9. Host control plane.
1187func nx_kill(pid: i64, sig: i64) -> i64 { return __syscall(129, pid, sig, 0, 0, 0, 0) }
1188
1189// setpgid(pid, pgid) -- put a process in its own PROCESS GROUP so a killer can reach its whole
1190// subtree. nx_kill(0 - pgid, sig) signals every member, not just the one process you forked.
1191// A BOUND THAT ONLY REACHES THE PROCESS YOU FORKED IS NOT A BOUND ON THE WORK IT STARTED.
1192// Per-target const, NOT a bare generic number: x86ctx_rv64_to_x86_64_syscall translates only the
1193// numbers it knows and FALLS THROUGH for the rest. MEASURED on the laptop lane 2026-08-10: a bare
1194// generic 154 reached x86_64 as 154 and returned -38 (ENOSYS), silently -- and a fix built on it
1195// reproduced the original bug exactly. Callers must treat setpgid as BEST-EFFORT.
1196@ifdef TARGET_X86_64
1197const SYS_SETPGID: i64 = 109
1198@endif
1199@ifndef TARGET_X86_64
1200const SYS_SETPGID: i64 = 154
1201@endif
1202func sys_setpgid(pid: i64, pgid: i64) -> i64 { return __syscall(SYS_SETPGID, pid, pgid, 0, 0, 0, 0) }
1203
1204// prlimit64(pid, resource, new_limit, old_limit) -- the Linux RESOURCE-LIMIT primitive =
1205// the Job-Object ActiveProcessLimit / memory-limit analog for the sovereign supervisor (M5).
1206// x86_64 prlimit64 = 302 (PASSED DIRECTLY, the unlinkat-263 / fsync-74 / fstatat-262
1207// precedent: a raw x86_64 number not in the compiler's rv64->x86 swap table passes through
1208// untranslated). NOTE: rv64 prlimit64 IS 261 but x86_64 261 = futimesat -- so the naive
1209// "261 is the same on both" is WRONG (PROBE-PROVEN: 261 returned EFAULT/EINVAL because it
1210// hit futimesat); the build target here is x86_64, so we emit 302 directly. pid=0 => the
1211// calling process (a forked child caps ITSELF before running its payload). new_limit /
1212// old_limit each point at a struct rlimit64 { rlim_cur: i64, rlim_max: i64 } (16 bytes);
1213// pass 0 for old_limit to skip read-back. Returns 0 on success, -errno (e.g. -1 EPERM if
1214// raising a hard limit unprivileged) on failure. NON-baked name (the compiler bakes some
1215// sys_* bodies by name; the nx_ prefix avoids that trap).
1216func nx_prlimit(pid: i64, resource: i64, new_limit: *u8, old_limit: *u8) -> i64 {
1217 return __syscall(302, pid, resource, new_limit as i64, old_limit as i64, 0, 0)
1218}
1219
1220// RLIMIT resource ids (Linux generic; identical rv64/x86_64). RLIMIT_AS = address-space
1221// (virtual memory) cap -- the cleanest userspace-settable "memory budget" for a supervised
1222// job. RLIMIT_CPU = CPU-seconds cap. WNOHANG=1 = wait4 non-blocking liveness poll option.
1223const RLIMIT_CPU: i64 = 0
1224const RLIMIT_AS: i64 = 9
1225const WNOHANG: i64 = 1
1226
1227// mkdirat -- rv64 34 -> x86_64 258. Create a doc-root directory. mode e.g. 0x1ed (0755).
1228func sys_mkdir(path: *u8, mode: i64) -> i64 { return __syscall(34, AT_FDCWD, path, mode, 0, 0, 0) }
1229
1230// fchmodat -- rv64 53 -> x86_64 268. +x a freshly-deployed daemon binary (mode 0x1ed). flags=0.
1231func nx_chmod(path: *u8, mode: i64) -> i64 { return __syscall(53, AT_FDCWD, path, mode, 0, 0, 0) }
1232
1233// setsid -- x86_64 = 112 (not in the rv64->x86 table, so the literal passes through). Detach a forked
1234// process into a NEW session so it survives the SSH/parent close -- sovereign daemonization (no shell setsid).
1235func nx_setsid() -> i64 { return __syscall(112, 0, 0, 0, 0, 0, 0) }
1236
1237// CLOCK_MONOTONIC = 1. ts is 16 bytes {sec: i64, nsec: i64}.
1238// Returns 0 / -errno.
1239func sys_clock_gettime_mono(ts: *i64) -> i64 {
1240 return __syscall(SYS_CLOCK_GETTIME, 1, ts, 0, 0, 0, 0)
1241}
1242
1243// CLOCK_REALTIME = 0 -- wall-clock seconds since the Unix epoch. Use
1244// this (NOT monotonic) for anything that must match calendar time:
1245// X.509 notBefore/notAfter, logs, TLS timestamps. Monotonic returns
1246// time-since-boot, which encodes as ~1970 when (mis)used as an epoch.
1247func sys_clock_gettime_real(ts: *i64) -> i64 {
1248 return __syscall(SYS_CLOCK_GETTIME, 0, ts, 0, 0, 0, 0)
1249}
1250
1251// Wall-clock seconds since the Unix epoch.
1252func sys_now_realtime_sec() -> i64 {
1253 let ts: *i64 = sys_mmap(16) as *i64
1254 sys_clock_gettime_real(ts)
1255 return ts[0]
1256}
1257
1258// Wall-clock milliseconds since the Unix epoch.
1259func sys_now_realtime_ms() -> i64 {
1260 let ts: *i64 = sys_mmap(16) as *i64
1261 sys_clock_gettime_real(ts)
1262 return ts[0] * 1000 + ts[1] / SYS_MAGIC_1000000
1263}
1264
1265// Wall-clock MICROSECONDS since the Unix epoch -- the CROSS-MACHINE stamp.
1266// ★ Use this, never sys_now_us(), for any value one machine writes and ANOTHER machine judges
1267// (fleet beats, lease expiry, telemetry rows). Monotonic counts from each machine's OWN boot, so
1268// subtracting one node's monotonic stamp from another's monotonic now yields the difference of two
1269// unrelated boot epochs -- the remote row then reads as ancient (or future-forged) and a freshness
1270// guard rejects every honest remote node while looking like it is working.
1271func sys_now_realtime_us() -> i64 {
1272 let ts: *i64 = sys_mmap(16) as *i64
1273 sys_clock_gettime_real(ts)
1274 return ts[0] * SYS_MAGIC_1000000 + ts[1] / 1000
1275}
1276
1277// Convenience: monotonic time in milliseconds. Caller does not own
1278// the timespec buffer -- it is mmap'd once per call (cheap; the
1279// underlying syscall already costs more than the page fault).
1280func sys_now_ms() -> i64 {
1281 let ts: *i64 = sys_mmap(16) as *i64
1282 sys_clock_gettime_mono(ts)
1283 let sec_part: i64 = ts[0] * 1000
1284 let nsec_part: i64 = ts[1] / SYS_MAGIC_1000000
1285 return sec_part + nsec_part
1286}
1287
1288// Convenience: monotonic time in microseconds. Used by per-request
1289// elapsed-time tracking in search engines + benches where ms is too
1290// coarse. Same caller-ownership rules as sys_now_ms.
1291func sys_now_us() -> i64 {
1292 let ts: *i64 = sys_mmap(16) as *i64
1293 sys_clock_gettime_mono(ts)
1294 let sec_part: i64 = ts[0] * SYS_MAGIC_1000000
1295 let nsec_part: i64 = ts[1] / 1000
1296 return sec_part + nsec_part
1297}
1298
1299// Alias used by nx_search_onsite_engine etc. Matches `_us` naming
1300// convention. Substrate-canonical name is sys_now_us; this alias
1301// preserves existing call sites without churn.
1302func sys_clock_now_us() -> i64 {
1303 return sys_now_us()
1304}
1305
1306// Read the entire file at `path` into a fresh mmap'd buffer. Returns
1307// a null-terminated *u8 plus writes the byte count to *out_len. On
1308// error (open failure, oversize) returns null and leaves out_len = 0.
1309// Uses a fixed 1 MiB buffer for the first pass; larger sources need a
1310// growth loop.
1311// ---- process control (Linux RV64) ----------------------------
1312//
1313// Lets NishiLang programs spawn other processes -- prerequisite
1314// for replacing shell scripts (f6_gate.sh) with .nx equivalents.
1315// NishiOS will expose a different process model (capability-based);
1316// these wrappers are the Linux-host compatibility layer.
1317
1318@ifdef TARGET_X86_64
1319const SYS_CLONE: i64 = 56
1320const SYS_EXECVE: i64 = 59
1321const SYS_WAIT4: i64 = 61
1322const SYS_PIPE2: i64 = 293
1323const SYS_DUP3: i64 = 292
1324@endif
1325
1326@ifndef TARGET_X86_64
1327const SYS_CLONE: i64 = 220
1328const SYS_EXECVE: i64 = 221
1329const SYS_WAIT4: i64 = 260
1330const SYS_PIPE2: i64 = 59
1331const SYS_DUP3: i64 = 24
1332@endif
1333
1334// Clone flags (subset). CLONE_VFORK blocks parent until child
1335// exec's or exits, matching fork() semantics closely enough for
1336// our spawn-then-wait patterns.
1337const CLONE_VM: i64 = 0x00000100
1338const CLONE_VFORK: i64 = 0x00004000
1339const SIGCHLD: i64 = 17
1340
1341// Create a child process via Linux clone(). Returns:
1342// > 0 in the parent: child PID
1343// == 0 in the child: child should exec or exit
1344// < 0 on error: -errno
1345// Uses SIGCHLD as the signal that parent receives on child exit
1346// (the libc fork() default); no shared memory or thread flags.
1347// ---- namespace / container family (debt 1785528831) ----------------
1348// Moved here from nx_syscalls_x86_64.nx so ONE module owns the wrapper set. Their
1349// absence here is why nx_container.nx had to import that module as a SECOND syscall
1350// layer, which put every wrapper in the TU twice and let definition ORDER pick the
1351// winner, silently, until the duplicate-definition guard made it fail closed.
1352func sys_unshare(flags: i64) -> i64 {
1353 return __syscall(SYS_UNSHARE, flags, 0, 0, 0, 0, 0)
1354}
1355func sys_mount(source: *u8, target: *u8, fs_type: *u8, mountflags: i64, data: *u8) -> i64 {
1356 return __syscall(SYS_MOUNT, source, target, fs_type, mountflags, data, 0)
1357}
1358func sys_chroot(path: *u8) -> i64 {
1359 return __syscall(SYS_CHROOT, path, 0, 0, 0, 0, 0)
1360}
1361func sys_getuid() -> i64 {
1362 return __syscall(SYS_GETUID, 0, 0, 0, 0, 0, 0)
1363}
1364func sys_getgid() -> i64 {
1365 return __syscall(SYS_GETGID, 0, 0, 0, 0, 0, 0)
1366}
1367
1368func sys_fork() -> i64 {
1369 return __syscall(SYS_CLONE, SIGCHLD, 0, 0, 0, 0, 0)
1370}
1371
1372// Replace the current process image. `path` is the executable
1373// (absolute or in $PATH if the child first does a fresh clone).
1374// `argv` is a null-terminated array of *u8 (already-marshalled).
1375// `envp` same shape, or null for "inherit parent's env".
1376// Only returns on failure (-errno).
1377// EXEC WITH A CLEAN FD TABLE (seq1785451144). A child inherits every fd its parent held, INCLUDING
1378// listen sockets, across fork AND execve. That is how nx_opaque_login came to hold mgmt s :18098
1379// alongside mgmt itself -- two listeners on one port, connections split between them, a VALID route
1380// answering 404 on some requests. There is no error anywhere in that state, which is why it was
1381// filed as a transport flake for months.
1382// ADDITIVE ON PURPOSE: sys_execve is left byte-identical (910 call sites across 719 files -- a
1383// global change there is unverifiable in one session). Spawners opt in by calling THIS instead.
1384// AUDIT THAT MAKES IT SAFE: zero call sites in the tree dup3 to a target fd above 2, so no exec d
1385// child is deliberately handed a high fd; 0/1/2 are preserved untouched.
1386// Linux child lifetime binding: call in the freshly forked child, before exec.
1387// The expected parent PID is captured before fork, closing the pre-arm death race.
1388// Kernel semantics bind to the creating thread; privileged exec can clear this.
1389const NX_SYS_PRCTL: i64 = 167
1390const NX_PR_SET_PDEATHSIG: i64 = 1
1391const NX_PR_SET_CHILD_SUBREAPER: i64 = 36
1392func sys_prctl(option: i64, arg: i64) -> i64 {
1393 return __syscall(NX_SYS_PRCTL,option,arg,0,0,0,0)
1394}
1395func sys_bind_parent_lifetime(expected_parent: i64, signal: i64) -> i64 {
1396 if expected_parent <= 0 || signal <= 0 { return 0-22 }
1397 let armed: i64=sys_prctl(NX_PR_SET_PDEATHSIG,signal)
1398 if armed < 0 { return armed }
1399 let parent: i64=__syscall(173,0,0,0,0,0,0)
1400 if parent != expected_parent { return 0-10 }
1401 return 0
1402}
1403
1404// Linux waitid observes termination without releasing the child's PID when WNOWAIT is set.
1405// Portable syscall 95 requires the matching x86 backend translation to 247.
1406const SYS_WAITID_PORTABLE: i64 = 95
1407const NX_WAIT_P_PID: i64 = 1
1408const NX_WAIT_EXITED: i64 = 4
1409const NX_WAIT_NOWAIT: i64 = 0x01000000
1410const NX_WAIT_SIGINFO_BYTES: i64 = 128
1411func sys_waitid(idtype: i64, id: i64, info: *u8, options: i64) -> i64 {
1412 return __syscall(SYS_WAITID_PORTABLE,idtype,id,info as i64,options,0,0)
1413}
1414
1415// Post-fork only: the child owns its descriptor table. The buffer bounds a
1416// getdents batch, never the descriptor numbers or number of open handles.
1417const NX_FD_DENT_BUFFER: i64 = 4096
1418const NX_SYS_CLOSE_RANGE: i64 = 436 // Linux x86_64 and asm-generic ABI
1419const NX_FD_UINT_MAX: i64 = 4294967295
1420func sys_close_inherited_proc(first: i64) -> i64 {
1421 let directory: i64=sys_openat_rd("/proc/self/fd")
1422 if directory < 0 { return directory }
1423 let buf: *u8=sys_mmap(NX_FD_DENT_BUFFER)
1424 var result: i64=0
1425 var running: i64=1
1426 while running == 1 {
1427 let n: i64=sys_getdents64(directory,buf,NX_FD_DENT_BUFFER)
1428 if n == (0-4) { continue }
1429 if n <= 0 { result=n; break }
1430 var off: i64=0
1431 while off < n {
1432 if n-off < 20 { result=0-5; running=0; break }
1433 let rec: *u8=buf+off
1434 let size: i64=dirent_reclen(rec)
1435 if size < 20 || size > n-off { result=0-5; running=0; break }
1436 var i: i64=19
1437 var fd: i64=0
1438 var valid: i64=1
1439 while i < size {
1440 let c: i64=rec[i] as i64
1441 if c == 0 { break }
1442 if c < 48 || c > 57 { valid=0; break }
1443 if fd > (2147483647-(c-48))/10 { valid=0; break }
1444 fd=fd*10+c-48; i=i+1
1445 }
1446 if i == 19 || i == size { valid=0 }
1447 if valid == 1 && fd >= first && fd != directory {
1448 // Linux releases the descriptor even when close reports a late
1449 // I/O error; never retry close and risk a reused descriptor.
1450 let closed: i64=sys_close(fd)
1451 if closed < 0 && closed != (0-9) { result=closed; running=0; break }
1452 }
1453 off=off+size
1454 }
1455 }
1456 let closedir: i64=sys_close(directory)
1457 sys_munmap(buf,NX_FD_DENT_BUFFER)
1458 if result == 0 && closedir < 0 { result=closedir }
1459 return result
1460}
1461func sys_close_inherited(first: i64) -> i64 {
1462 if first < 0 { return 0-22 }
1463 let rc: i64=__syscall(NX_SYS_CLOSE_RANGE,first,NX_FD_UINT_MAX,0,0,0,0)
1464 if rc == (0-38) { return sys_close_inherited_proc(first) }
1465 return rc
1466}
1467func sys_execve_clean(path: *u8, argv: *i64, envp: *i64) -> i64 {
1468 let rc: i64=sys_close_inherited(3)
1469 if rc < 0 { return rc }
1470 return sys_execve(path,argv,envp)
1471}
1472
1473func sys_execve(path: *u8, argv: *i64, envp: *i64) -> i64 {
1474 return __syscall(SYS_EXECVE, path, argv, envp, 0, 0, 0)
1475}
1476
1477// Wait for a child to exit. `pid` = -1 waits for ANY child,
1478// otherwise waits for that specific PID. `status` is a caller-
1479// mmapped i64 slot: on exit the low 16 bits carry Linux's w* status
1480// flags (WIFEXITED / WEXITSTATUS). Returns the reaped child's PID
1481// or -errno.
1482func sys_wait4(pid: i64, status: *i64, options: i64) -> i64 {
1483 return __syscall(SYS_WAIT4, pid, status, options, 0, 0, 0)
1484}
1485
1486// Extract exit code from a wait4 status word. Matches the glibc
1487// WEXITSTATUS macro: bits 8-15 of the low 16.
1488func wait_exit_code(status: i64) -> i64 {
1489 return (status >> 8) & 0xFF
1490}
1491
1492// Terminating signal from a wait4 status (0 when the child exited normally). Sibling of
1493// wait_exit_code; RESTORED 2026-07-30 after a stale whole-tree push erased both it and
1494// sys_ignore_sigpipe below, while three files still CALLED them (nx_http_server, nx_sigpipe_gate,
1495// nx_tools_api_serve) -- so the tree could not build until they came back.
1496func wait_term_signal(status: i64) -> i64 {
1497 return status & 0x7f
1498}
1499
1500// THE ONE RULER for "what result code did this process actually produce". Use this, not
1501// wait_exit_code, anywhere the answer becomes a VERDICT.
1502//
1503// WHY IT EXISTS, MEASURED 2026-08-25. wait_exit_code is WEXITSTATUS and is correctly named:
1504// bits 8-15 of the status word. But a child KILLED BY A SIGNAL has no exit status at all, and
1505// those bits are ZERO -- so a SEGFAULTING process is indistinguishable from a clean exit 0 to
1506// every caller that reads only wait_exit_code. Measured live: a gate that SIGSEGV'd mid-run was
1507// served by /api/gate_run as exit_code 0, verdict GREEN. A CRASHED GATE WORE A PASS.
1508//
1509// This is not a new discovery in this estate -- and that is the point. nx_gatekit_lib's
1510// gk_wait_code already carried exactly this rule, with its own measurement recorded (two gates
1511// the 60 s watchdog KILLED journaled `GREEN exit=0 ms=60443`). It was fixed THERE in August and
1512// left unfixed in nx_tool_run, which is the shared exec primitive sitting behind /api/gate_run,
1513// /api/build and 51 other consumers. A LAW APPLIED IN ONE ORGAN AND NOT ITS SIBLING IS HALF A
1514// LAW, AND THE HALF LEFT UNDONE IS THE ONE ON THE PRODUCTION PATH. So the rule now lives HERE,
1515// beside the two accessors it is composed of, and gk_wait_code delegates to it: one ruler.
1516//
1517// Shell convention 128+signal (137 SIGKILL, 139 SIGSEGV) is deliberate: it makes the death both
1518// VISIBLE and NON-ZERO, so every existing caller that branches on rc != 0 sees it with no change.
1519// wait_exit_code is left EXACTLY as it was -- 85 call sites across the corpus (corpus_complete=1)
1520// read it, and silently redefining WEXITSTATUS under them would be the cure being worse.
1521func wait_status_rc(status: i64) -> i64 {
1522 let sig: i64 = wait_term_signal(status)
1523 if sig != 0 { return 128 + sig }
1524 return wait_exit_code(status)
1525}
1526
1527// Ignore SIGPIPE process-wide, so writing to a socket the peer already closed returns -EPIPE
1528// instead of KILLING the process. SIGPIPE default action is TERMINATE, which for a daemon means
1529// every client that walks away mid-response is an outage -- this one call at the listen primitive
1530// is inherited by all 52 consumers of nx_http_server_listen.
1531// rt_sigaction(SIGPIPE, {handler=SIG_IGN}, NULL, 8): syscall 13 on x86-64, which happens to equal
1532// the signal number. SA_RESTORER is deliberately NOT set -- the kernel consults it only when it
1533// DELIVERS a handler frame, and SIG_IGN never delivers one.
1534// PROVEN, not asserted: nx_sigpipe_gate forks a child that writes to a closed pipe and demands
1535// death-by-signal-13 WITHOUT this call and a clean -EPIPE WITH it.
1536// Restore a signal to its DEFAULT disposition. THE INVERSE OF sys_ignore_sigpipe, and it exists
1537// because SIG_IGN is inherited across BOTH fork and execve: a daemon that ignores SIGPIPE hands
1538// that ignore to every child it spawns, FOREVER. That silently corrupted verification -- the
1539// sigpipe gate reported 4/5 RED under /api/gate_run and 5/5 GREEN under a shell, same binary,
1540// same minute, because its DISEASE control (writing to a closed peer must KILL) could not be
1541// observed inside an environment where the kill was already disabled (seq1463). A harness must
1542// not change the state it is verifying; where it must, it has to hand back a clean slate.
1543// ⚠the same inheritance can also produce a FALSE GREEN, which is the far more dangerous half.
1544func sys_default_signal(sig: i64) -> i64 {
1545 let act: *i64 = sys_mmap(64) as *i64
1546 act[0] = 0
1547 act[1] = 0
1548 act[2] = 0
1549 act[3] = 0
1550 return __syscall(13, sig, act as i64, 0, 8, 0, 0)
1551}
1552
1553func sys_ignore_sigpipe() -> i64 {
1554 let act: *i64 = sys_mmap(64) as *i64
1555 act[0] = 1
1556 act[1] = 0
1557 act[2] = 0
1558 act[3] = 0
1559 return __syscall(13, 13, act as i64, 0, 8, 0, 0)
1560}
1561
1562// Create a pipe. `fds` must point at 8+ writable bytes; the kernel
1563// packs BOTH int32 fds into fds[0]: read end = low 32 bits, write end
1564// = HIGH 32 bits (fds[1] is never written -- the old comment claiming
1565// fds[1]=write-end caused a false-pass KAT + a hung gate, 2026-07-16).
1566// Extract: rfd = fds[0] & 0xffffffff; wfd = (fds[0] / 4294967296) &
1567// 0xffffffff. Returns 0 on success, -errno on failure.
1568func sys_pipe2(fds: *i64, flags: i64) -> i64 {
1569 return __syscall(SYS_PIPE2, fds, flags, 0, 0, 0, 0)
1570}
1571
1572// Duplicate `oldfd` onto `newfd`, closing `newfd` first if open.
1573// Used to wire child stdout to a pipe: dup3(pipe_write_end, 1).
1574func sys_dup3(oldfd: i64, newfd: i64, flags: i64) -> i64 {
1575 return __syscall(SYS_DUP3, oldfd, newfd, flags, 0, 0, 0)
1576}
1577
1578// ---- directory listing (Linux RV64 getdents64) ---------------
1579//
1580// Foundation for ls / glob / dir-walk helpers. Linux returns
1581// linux_dirent64 records:
1582// u64 d_ino (inode, ignored here)
1583// s64 d_off (next-record offset)
1584// u16 d_reclen (this record's byte length)
1585// u8 d_type (file type; DT_DIR=4, DT_REG=8, DT_LNK=10)
1586// char d_name[] (null-terminated name, padded so d_reclen
1587// carries us to the next record boundary)
1588// Total struct header: 19 bytes, then name up to d_reclen - 19.
1589
1590@ifdef TARGET_X86_64
1591const SYS_GETDENTS64: i64 = 217
1592@endif
1593@ifndef TARGET_X86_64
1594const SYS_GETDENTS64: i64 = 61
1595@endif
1596
1597const DT_UNKNOWN: i64 = 0
1598const DT_FIFO: i64 = 1
1599const DT_CHR: i64 = 2
1600const DT_DIR: i64 = 4
1601const DT_BLK: i64 = 6
1602const DT_REG: i64 = 8
1603const DT_LNK: i64 = 10
1604const DT_SOCK: i64 = 12
1605
1606// Raw syscall. Returns bytes written on success (0 = end-of-dir),
1607// or -errno on failure.
1608func sys_getdents64(fd: i64, buf: *u8, buf_len: i64) -> i64 {
1609 return __syscall(SYS_GETDENTS64, fd, buf, buf_len, 0, 0, 0)
1610}
1611
1612// Extract fields from a linux_dirent64 record. `rec` points at
1613// the start of the record; fields are at fixed offsets.
1614func dirent_reclen(rec: *u8) -> i64 {
1615 // d_reclen is u16 at offset 16. Read as two bytes little-endian.
1616 let lo: i64 = rec[16]
1617 let hi: i64 = rec[17]
1618 return lo | (hi << 8)
1619}
1620
1621func dirent_type(rec: *u8) -> i64 {
1622 return rec[18]
1623}
1624
1625// Pointer to the null-terminated name inside the record.
1626func dirent_name(rec: *u8) -> *u8 {
1627 let base: i64 = rec as i64
1628 return (base + 19) as *u8
1629}
1630
1631// ---- content-addressed file reader ---------------------------
1632
1633func sys_read_file(path: *u8, out_len: *i64) -> *u8 {
1634 let fd: i64 = sys_openat_rd(path)
1635 if fd < 0 {
1636 *out_len = 0
1637 return 0 as *u8
1638 }
1639 // DEBT-EATEN 2026-07-15: the old fixed 4 GiB cap SILENTLY TRUNCATED bigger files (a 9 GB gguf would
1640 // short-read into plausible-garbage tensors -- the worst failure class). Now the buffer is sized from
1641 // the file itself (lseek END), so ANY size reads fully. Physical pages still allocate on-demand. For
1642 // zero-copy any-size READ-ONLY access prefer sys_map_file (below).
1643 // DEBT-EATEN 2026-08-19 (1787076780): when the size is UNKNOWABLE (lseek END <= 0: /proc files, pipes
1644 // -- AND every empty regular file, which reports 0 just the same) this used to reserve
1645 // SYS_MAGIC_4294967296 of address space per call. Untouched pages were never resident, but the
1646 // mapping WAS: a daemon that read an empty registry every sweep ballooned its VmSize by 4 GiB per
1647 // read (measured: smoke instances at a 4.2 GB base), the leak screens flagged it, and sys_free_file
1648 // could only release what was read. The size-unknowable path now GROWS: start at SYS_READ_GROW_INIT,
1649 // double while the window fills, and hand back an EXACT mapping (total + 16) so sys_free_file
1650 // releases all of it. An empty file costs one small read and a 16-byte arena cell; /proc/stat fits
1651 // the first window; a pipe of any length still reads whole. The known-size path is unchanged.
1652 let fsz: i64 = sys_lseek(fd, 0, 2)
1653 sys_lseek(fd, 0, 0)
1654 var cap: i64 = SYS_READ_GROW_INIT
1655 var grow: i64 = 1
1656 if fsz > 0 { cap = fsz; grow = 0 }
1657 var buf: *u8 = sys_mmap(cap + 16)
1658 var total: i64 = 0
1659 var go: i64 = 1
1660 while go == 1 {
1661 let base: i64 = buf as i64
1662 let tail: *u8 = (base + total) as *u8
1663 let n: i64 = sys_read(fd, tail, cap - total)
1664 if n <= 0 { go = 0 }
1665 if n > 0 { total = total + n }
1666 if total >= cap {
1667 if grow == 0 { go = 0 } else {
1668 // the window filled and the size is unknown: double it, copy, release the old mapping
1669 let ncap: i64 = cap * 2
1670 let nb: *u8 = sys_mmap(ncap + 16)
1671 var ci: i64 = 0
1672 let obase: i64 = buf as i64
1673 let nbase: i64 = nb as i64
1674 while ci < total { let src: *u8 = (obase + ci) as *u8; let dst: *u8 = (nbase + ci) as *u8; dst[0] = src[0]; ci = ci + 1 }
1675 sys_munmap(buf, cap + 16)
1676 buf = nb
1677 cap = ncap
1678 }
1679 }
1680 }
1681 sys_close(fd)
1682 if grow == 1 {
1683 // hand back an EXACT mapping so the paired free releases everything (the doubled window would
1684 // otherwise leave its slack mapped forever -- the address-space leak this change exists to end)
1685 let xb: *u8 = sys_mmap(total + 16)
1686 var xi: i64 = 0
1687 let gbase: i64 = buf as i64
1688 let xbase: i64 = xb as i64
1689 while xi < total { let gsrc: *u8 = (gbase + xi) as *u8; let xdst: *u8 = (xbase + xi) as *u8; xdst[0] = gsrc[0]; xi = xi + 1 }
1690 sys_munmap(buf, cap + 16)
1691 buf = xb
1692 }
1693 // Null-terminate for the lexer.
1694 let bbase: i64 = buf as i64
1695 let term: *u8 = (bbase + total) as *u8
1696 term[0] = 0
1697 *out_len = total
1698 return buf
1699}
1700
1701// PAIRED FREE FOR sys_read_file (2026-08-17). sys_read_file mmaps `cap + 16` where cap is the FILE SIZE
1702// and returns only the pointer -- so any caller that frees it must know the padding, and a caller that
1703// unmaps `len` alone leaks the tail page whenever the file size sits just under a page boundary.
1704// ★A CALLER FORCED TO KNOW ITS ALLOCATOR'S PADDING IS A COUPLING THAT WILL DRIFT -- so the +16 lives
1705// HERE, beside the +16 it mirrors, instead of being retyped at every call site.
1706// Pass the length sys_read_file reported through out_len; this re-derives the mapping from it.
1707// Null-safe by construction: sys_read_file returns 0 on failure, so callers need no extra guard --
1708// ★A FREE THAT REFUSES NULL IS A FREE NOBODY HAS TO WRAP IN AN IF.
1709// EXACT for every path since 2026-08-19: the size-unknowable fallback (lseek <= 0: /proc, pipes, empty
1710// regular files) now returns a mapping of exactly total + 16, so this releases ALL of it. (It used to
1711// map SYS_MAGIC_4294967296 of address space and release only what was read -- stated then, ended now.)
1712// WHY IT EXISTS: nx_sites_daemon serves /wiki/roadmap by calling sys_read_file PER REQUEST inside a loop
1713// that runs up to NX_SD_MAX_REQ_PER_CONN (64) times per connection and never released it -- an 8,408 B
1714// file became 3 fresh pages and a fresh kernel VMA on every hit, held until the child exited.
1715func sys_free_file(buf: *u8, len: i64) -> i64 {
1716 if (buf as i64) == 0 { return 0 }
1717 if len < 0 { return 0 }
1718 return sys_munmap(buf, len + 16)
1719}
1720
1721// Read-only FILE-BACKED map of the whole file (PROT_READ=1, MAP_PRIVATE=2): any size, zero-copy -- only
1722// touched pages become resident (the lazy-MoE shape: a 9 GB model serves in ~active-set RSS, and load
1723// time is ~0 because nothing is copied). NO NUL pad (a file mapping cannot be extended) -- BINARY
1724// consumers only; text/lexer callers keep sys_read_file. Returns 0 on failure; *out_len = file size.
1725// Read-only by construction (PROT_READ; writes fault -- Rule 26-friendly).
1726func sys_map_file(path: *u8, out_len: *i64) -> *u8 {
1727 *out_len = 0
1728 let fd: i64 = sys_openat_rd(path)
1729 if fd < 0 { return 0 as *u8 }
1730 let fsz: i64 = sys_lseek(fd, 0, 2)
1731 if fsz <= 0 { sys_close(fd); return 0 as *u8 }
1732 let r: i64 = __syscall(SYS_MMAP, 0, fsz, 1, 2, fd, 0)
1733 sys_close(fd)
1734 if r <= 0 { return 0 as *u8 }
1735 *out_len = fsz
1736 return r as *u8
1737}
1738
1739// Sleep for `ms` milliseconds against CLOCK_MONOTONIC (relative).
1740// Returns 0 on success, negative errno on failure. Caller-supplied
1741// budget: ms <= 0 is a no-op; very large values are accepted as-is
1742// (the kernel will saturate to its own clamp). Defined at the bottom
1743// of this file so sys_mmap is in scope (single-pass parser).
1744func sys_sleep_ms(ms: i64) -> i64 {
1745 if ms <= 0 { return 0 }
1746 // struct timespec { sec: i64, nsec: i64 } -- 16 bytes RV64.
1747 let req: *u8 = sys_mmap(16)
1748 let rem: *u8 = sys_mmap(16)
1749 let secs: i64 = ms / 1000
1750 let nsec: i64 = (ms - secs * 1000) * SYS_MAGIC_1000000 // remainder ms -> ns
1751 let req_sec: *i64 = req as *i64
1752 let req_nsec: *i64 = ((req as i64) + 8) as *i64
1753 req_sec[0] = secs
1754 req_nsec[0] = nsec
1755 // clock_nanosleep(CLOCK_MONOTONIC=1, flags=0, req, rem). On EINTR (-4) a signal (e.g. SIGCHLD from a
1756 // reaped child) cut the sleep short and wrote the leftover into rem -- RESUME it, otherwise a caller
1757 // that uses the sleep as a timer (the torrent pool's 2s tick) gets spun into a busy loop by child
1758 // deaths and any tick-based budget collapses to milliseconds. A sleep must sleep its full duration.
1759 var r: i64 = __syscall(SYS_CLOCK_NANOSLEEP, 1, 0, req as i64, rem as i64, 0, 0)
1760 var guard: i64 = 0
1761 while r == (0 - 4) {
1762 if guard > SYS_MAGIC_100000 { r = 0 } else {
1763 let rs: *i64 = rem as *i64
1764 let rn: *i64 = ((rem as i64) + 8) as *i64
1765 req_sec[0] = rs[0]
1766 req_nsec[0] = rn[0]
1767 r = __syscall(SYS_CLOCK_NANOSLEEP, 1, 0, req as i64, rem as i64, 0, 0)
1768 guard = guard + 1
1769 }
1770 }
1771 sys_munmap(req, 16); sys_munmap(rem, 16) // FREE the timespec pages -- every call mmap'd 2 pages; in a
1772 // long-running poll loop (the supervisor's 15s tick) that leaked ~8KB/iter until mmap -> -12 -> SEGFAULT.
1773 return r
1774}
1775
1776// ---- sockets (RV64 generic syscall numbers) ----------------------
1777//
1778// Source uses RV64 numbers; the x86_64 backend's
1779// x86ctx_rv64_to_x86_64_syscall table translates at codegen time.
1780// Numbers from arch/arm64/include/asm/unistd.h (RV64 inherits the
1781// generic ABI).
1782
1783// Socket-family syscall numbers via @ifdef macro -- mirrors the
1784// pattern already used for SYS_READ/WRITE/MMAP/etc. above. Without
1785// this gate, --target x86_64 compiled the RV64 numbers as literals
1786// into the `syscall` instruction (e.g. 198 = sched_setaffinity on
1787// x86_64, not socket) and any daemon using sys_socket() died with
1788// ENOSYS before printing its banner -- caught by the nx_signaling
1789// stone S2 deploy on 2026-05-20 (see [[project-cross-isa-syscall-
1790// unification-gap-2026-05-20]]).
1791@ifdef TARGET_X86_64
1792const SYS_SOCKET: i64 = 41
1793const SYS_BIND: i64 = 49
1794const SYS_LISTEN: i64 = 50
1795const SYS_ACCEPT: i64 = 43
1796const SYS_CONNECT: i64 = 42
1797const SYS_SETSOCKOPT: i64 = 54
1798const SYS_SENDTO: i64 = 44
1799const SYS_RECVFROM: i64 = 45
1800const SYS_SHUTDOWN: i64 = 48
1801@endif
1802
1803@ifndef TARGET_X86_64
1804const SYS_SOCKET: i64 = 198
1805const SYS_BIND: i64 = 200
1806const SYS_LISTEN: i64 = 201
1807const SYS_ACCEPT: i64 = 202
1808const SYS_CONNECT: i64 = 203
1809const SYS_SETSOCKOPT: i64 = 208
1810const SYS_SENDTO: i64 = 206
1811const SYS_RECVFROM: i64 = 207
1812const SYS_SHUTDOWN: i64 = 210
1813@endif
1814
1815// Socket-option constants used by nx_http_server / nx_https_server.
1816const SOL_SOCKET: i64 = 1
1817const SO_REUSEADDR: i64 = 2
1818// Receive/send timeouts (Linux x86_64). optval is a struct timeval
1819// {tv_sec: i64, tv_usec: i64} (16 bytes). Essential on PUBLIC sockets:
1820// without them, a single silent/slow client hangs a blocking read
1821// forever -> trivial DoS on a single-threaded accept loop.
1822const SO_SNDTIMEO: i64 = 21
1823const SO_RCVTIMEO: i64 = 20
1824
1825// setsockopt(2) -- set a socket option. Defined BEFORE its first caller
1826// (sys_set_socket_timeout, below): NishiLang forbids forward references,
1827// so the definition must precede every use.
1828func sys_setsockopt(fd: i64, level: i64, optname: i64,
1829 optval: *u8, optlen: i64) -> i64 {
1830 return __syscall(SYS_SETSOCKOPT, fd, level, optname, optval, optlen, 0)
1831}
1832
1833// Set a receive+send timeout (in whole seconds) on a socket fd.
1834// tv is munmap'd before return (LEAK FIXED 2026-07-16): this is called once per PROBE by the daemon
1835// supervisor (35/cycle forever -> ~800MB VSZ/day) and once per CONNECTION by fork-per-connection daemons.
1836// The unfreed page-per-call ballooned VSZ until heuristic overcommit made fork() return -ENOMEM (the
1837// proven pid=-12 failure class) -- likely the historical VSZ pressure behind the vsz_watchdog.
1838func sys_set_socket_timeout(fd: i64, secs: i64) -> i64 {
1839 let tv: *i64 = (sys_mmap(16)) as *i64
1840 tv[0] = secs // tv_sec
1841 tv[1] = 0 // tv_usec
1842 sys_setsockopt(fd, SOL_SOCKET, SO_RCVTIMEO, tv as *u8, 16)
1843 sys_setsockopt(fd, SOL_SOCKET, SO_SNDTIMEO, tv as *u8, 16)
1844 sys_munmap(tv as *u8, 16)
1845 return 0
1846}
1847
1848// alarm(2): deliver SIGALRM after `secs` seconds (0 cancels a pending alarm). No SIGALRM handler is installed, so
1849// the default action TERMINATES the process. Used as a per-request watchdog inside a forked request-child: a
1850// pathologically-slow page can then never hang the child forever (which would leak its buffers + pile up procs).
1851const SYS_ALARM: i64 = 37
1852func sys_alarm(secs: i64) -> i64 { return __syscall(SYS_ALARM, secs, 0, 0, 0, 0, 0) }
1853
1854const AF_INET: i64 = 2
1855const SOCK_STREAM: i64 = 1
1856const SOCK_DGRAM: i64 = 2
1857
1858func sys_socket(domain: i64, sock_type: i64, protocol: i64) -> i64 {
1859 return __syscall(SYS_SOCKET, domain, sock_type, protocol, 0, 0, 0)
1860}
1861// Pack an AF_INET any-address sockaddr_in (16 bytes) for `port` at `addr`.
1862// RESTORED INTO THE OWNER 2026-08-19: this lived in the old full nx_syscalls_x86_64.nx and was the
1863// one wrapper WITH LIVE CALLERS (nx_nishipages_serve, nx_udp) that the 2026-07-31 alias-stub
1864// consolidation dropped -- both lanes sat NAS-unbuildable ("I do not know the name") until the
1865// rebuild-drain surfaced them. Body verbatim from the old file, including its documented
1866// workaround: NO `as u8` casts on the byte stores -- the array-element-store already truncates
1867// when the lvalue is *u8, and casts on this path once tripped a codegen defect.
1868// (The old file's other two uncalled orphans, sys_pivot_root/sys_umount2, were left dead on a
1869// zero-caller full-tree grep -- restoring an uncalled wrapper is inventory, not capability.)
1870func sockaddr_in_init(addr: *u8, port: i64) -> i64 {
1871 addr[0] = 2 // AF_INET low byte
1872 addr[1] = 0
1873 // Port in network byte order (big-endian).
1874 let hi: i64 = (port >> 8) & 0xFF
1875 let lo: i64 = port & 0xFF
1876 addr[2] = hi
1877 addr[3] = lo
1878 addr[4] = 0
1879 addr[5] = 0
1880 addr[6] = 0
1881 addr[7] = 0
1882 addr[8] = 0
1883 addr[9] = 0
1884 addr[10] = 0
1885 addr[11] = 0
1886 addr[12] = 0
1887 addr[13] = 0
1888 addr[14] = 0
1889 addr[15] = 0
1890 return 0
1891}
1892
1893func sys_bind(fd: i64, addr: *u8, addr_len: i64) -> i64 {
1894 return __syscall(SYS_BIND, fd, addr, addr_len, 0, 0, 0)
1895}
1896func sys_listen(fd: i64, backlog: i64) -> i64 {
1897 return __syscall(SYS_LISTEN, fd, backlog, 0, 0, 0, 0)
1898}
1899// accept(2) -- accept the next pending connection on a listening socket.
1900// Single-arg form (kernel ignores NULL addr/addr_len writes). Existing
1901// nx_http_server callers use this signature; the 3-arg form is provided
1902// as sys_accept_with_addr for outliers needing peer address.
1903func sys_accept(fd: i64) -> i64 {
1904 return __syscall(SYS_ACCEPT, fd, 0, 0, 0, 0, 0)
1905}
1906func sys_accept_with_addr(fd: i64, addr: *u8, addr_len: *i64) -> i64 {
1907 return __syscall(SYS_ACCEPT, fd, addr, addr_len, 0, 0, 0)
1908}
1909// shutdown(2) -- half-close a socket. how: 0=RD, 1=WR, 2=RDWR.
1910func sys_shutdown(fd: i64, how: i64) -> i64 {
1911 return __syscall(SYS_SHUTDOWN, fd, how, 0, 0, 0, 0)
1912}
1913func sys_connect(fd: i64, addr: *u8, addr_len: i64) -> i64 {
1914 return __syscall(SYS_CONNECT, fd, addr, addr_len, 0, 0, 0)
1915}
1916func sys_sendto(fd: i64, buf: *u8, n: i64, flags: i64,
1917 dest_addr: *u8, addr_len: i64) -> i64 {
1918 return __syscall(SYS_SENDTO, fd, buf, n, flags, dest_addr, addr_len)
1919}
1920func sys_recvfrom(fd: i64, buf: *u8, n: i64, flags: i64,
1921 src_addr: *u8, addr_len: *i64) -> i64 {
1922 return __syscall(SYS_RECVFROM, fd, buf, n, flags, src_addr, addr_len)
1923}
1924
1925// ---- SCM_RIGHTS DESCRIPTOR PASSING (sendmsg/recvmsg over AF_UNIX) -----------------------------
1926// ADDED 2026-08-21 for /compare/trafficsafety TS1. Until now sys_sendmsg was ABSENT-PROVEN from the
1927// whole tree (corpus_complete=1), so the mechanism nginx, HAProxy and Envoy all use for hitless
1928// replacement -- MOVING the listening descriptor rather than re-binding it -- could not be written
1929// at all. SO_REUSEPORT co-binding is an ACCEPT-DISTRIBUTION primitive, NOT a handoff primitive:
1930// LWN documents that changing the set of listening sockets on a port drops connections during the
1931// three-way handshake, so co-binding proves two binders and can never prove zero drops.
1932//
1933// EVERY OFFSET BELOW IS MEASURED, NOT RECALLED. They were read out of the platform's own headers
1934// with offsetof/sizeof/CMSG_LEN compiled for x86_64:
1935// msghdr 56 = name 0 | namelen 8 (u32) | iov 16 | iovlen 24 | control 32 | controllen 40 | flags 48 (u32)
1936// iovec 16 = base 0 | len 8
1937// cmsghdr 16 = len 0 (u64) | level 8 (u32) | type 12 (u32), data at 16
1938// CMSG_LEN(4)=20 CMSG_SPACE(4)=24 sendmsg=46 recvmsg=47 socketpair=53
1939// AF_UNIX=1 SOL_SOCKET=1 SCM_RIGHTS=1 MSG_CMSG_CLOEXEC=1073741824
1940// A WRONG LAYOUT HERE DOES NOT FAIL LOUD. The syscall still returns a positive byte count and
1941// simply transfers no descriptor, which is why the gate for this proves the property by passing a
1942// REAL descriptor between two REAL processes and then USING it, never by reading a return code.
1943// x86_64 Linux numbers, DELIBERATELY UNGUARDED, and the reason is a measurement rather than a
1944// preference. The first draft of this block wrapped these three in the same
1945// @ifdef TARGET_X86_64 / @ifndef pair every other syscall number in this file uses. On an x86 build
1946// that made every call ENOSYS, and the probe that caught it printed why:
1947// CONSTS SYS_SENDMSG=211 SYS_RECVMSG=212 SYS_SOCKETPAIR=199 SYS_WRITE=64
1948// N sendmsg PLAIN via the CONST rc=-38 (211 is unassigned on x86_64)
1949// N2 sendmsg PLAIN via the LITERAL rc=1
1950// SYS_WRITE reading 64 is the tell and it is NOT MINE: the file's own original guarded block
1951// resolves to its RV64 branch when the constant is referenced, on a build whose sys_write plainly
1952// works. So a constant inside these guards is not reliably the value the guard appears to select.
1953// !! A GUARD THAT SILENTLY SELECTS THE OTHER TARGET'S NUMBER IS WORSE THAN NO GUARD: the call still
1954// compiles, still returns, and dispatches a DIFFERENT SYSCALL. Syscall 199 on x86_64 is
1955// fremovexattr, which is why socketpair appeared to answer EFAULT for every input including a NULL
1956// vector and an unsupported domain -- varying the ARGUMENTS can never reveal that the NUMBER is
1957// wrong, because every variant was equally wrong.
1958// => RV64 support for these three is an OPEN, NAMED requirement, blocked on that toolchain
1959// behaviour. It is left undone and stated rather than papered over with a guard measured not to
1960// work. The estate already keeps nx_syscalls_x86_64.nx as the explicit single-target mirror for
1961// exactly this class of problem.
1962const SYS_SENDMSG: i64 = 46
1963const SYS_RECVMSG: i64 = 47
1964const SYS_SOCKETPAIR: i64 = 53
1965const SCM_AF_UNIX: i64 = 1
1966const SCM_SOL_SOCKET: i64 = 1
1967const SCM_RIGHTS_TYPE: i64 = 1
1968const SCM_MSG_CMSG_CLOEXEC: i64 = 1073741824
1969const SCM_MSGHDR_BYTES: i64 = 56
1970const SCM_MSGHDR_OFF_IOV: i64 = 16
1971const SCM_MSGHDR_OFF_IOVLEN: i64 = 24
1972const SCM_MSGHDR_OFF_CTRL: i64 = 32
1973const SCM_MSGHDR_OFF_CTRLLEN: i64 = 40
1974const SCM_IOVEC_BYTES: i64 = 16
1975const SCM_IOVEC_OFF_BASE: i64 = 0
1976const SCM_IOVEC_OFF_LEN: i64 = 8
1977const SCM_CMSG_OFF_LEN: i64 = 0
1978const SCM_CMSG_OFF_LEVEL: i64 = 8
1979const SCM_CMSG_OFF_TYPE: i64 = 12
1980const SCM_CMSG_OFF_DATA: i64 = 16
1981const SCM_CMSG_LEN_1FD: i64 = 20
1982const SCM_CMSG_SPACE_1FD: i64 = 24
1983const SCM_IOV_COUNT_ONE: i64 = 1
1984const SCM_U32_BYTES: i64 = 4
1985const SCM_BYTE_RADIX: i64 = 256
1986const SCM_FDPAIR_BYTES: i64 = 8
1987// One real data byte travels with the ancillary data ON PURPOSE: a sendmsg carrying SCM_RIGHTS and
1988// NO ordinary payload is the classic silent no-transfer, and it returns 0 rather than an error.
1989const SCM_PAYLOAD_BYTES: i64 = 1
1990const SCM_PAYLOAD_BYTE: i64 = 70
1991// Distinguishable refusals, each naming WHICH conjunct failed -- a compound assertion that will not
1992// name its failing conjunct is a false-alarm generator. All are negative and all sit far outside the
1993// errno range, so no caller can confuse one with a kernel error or with a valid descriptor.
1994const SCM_ERR_NO_CMSG: i64 = 0 - 901
1995const SCM_ERR_CMSG_LEN: i64 = 0 - 902
1996const SCM_ERR_CMSG_LEVEL: i64 = 0 - 903
1997const SCM_ERR_CMSG_TYPE: i64 = 0 - 904
1998
1999func scm_zero(base: *u8, n: i64) -> i64 { var i: i64 = 0; while i < n { base[i] = 0; i = i + 1 } return 0 }
2000func scm_put_i64(base: *u8, off: i64, v: i64) -> i64 {
2001 let p: *i64 = ((base as i64) + off) as *i64
2002 p[0] = v
2003 return 0
2004}
2005func scm_get_i64(base: *u8, off: i64) -> i64 {
2006 let p: *i64 = ((base as i64) + off) as *i64
2007 return p[0]
2008}
2009// The two cmsg header fields and the descriptor slot itself are 4-byte ints, so they are packed and
2010// unpacked byte by byte in little-endian order. Radix arithmetic rather than bit shifts, matching
2011// sockaddr_in_init's documented style on this exact path.
2012func scm_put_u32(base: *u8, off: i64, v: i64) -> i64 {
2013 var i: i64 = 0
2014 var m: i64 = v
2015 while i < SCM_U32_BYTES {
2016 base[off + i] = m % SCM_BYTE_RADIX
2017 m = m / SCM_BYTE_RADIX
2018 i = i + 1
2019 }
2020 return 0
2021}
2022func scm_get_u32(base: *u8, off: i64) -> i64 {
2023 var v: i64 = 0
2024 var mult: i64 = 1
2025 var i: i64 = 0
2026 while i < SCM_U32_BYTES {
2027 v = v + (base[off + i] as i64) * mult
2028 mult = mult * SCM_BYTE_RADIX
2029 i = i + 1
2030 }
2031 return v
2032}
2033
2034func sys_sendmsg(fd: i64, msg: *u8, flags: i64) -> i64 {
2035 return __syscall(SYS_SENDMSG, fd, msg, flags, 0, 0, 0)
2036}
2037func sys_recvmsg(fd: i64, msg: *u8, flags: i64) -> i64 {
2038 return __syscall(SYS_RECVMSG, fd, msg, flags, 0, 0, 0)
2039}
2040// socketpair(2). sv receives TWO 4-byte descriptors, so it is a *u8 read with scm_get_u32 -- a
2041// single *i64 read would splice both descriptors into one number and the second would vanish.
2042// !! THIS NUMBER IS NOT REACHING socketpair, AND THE FIRST DIAGNOSIS OF THAT WAS WRONG.
2043// Measured 2026-08-21: every call returns -14 (EFAULT) -- with a valid pointer, with a NULL vector,
2044// and with an UNSUPPORTED DOMAIN alike. The first reading of that evidence was "the host refuses
2045// this call for every input", and it was REFUTED by measuring the emitted constants instead of the
2046// arguments. TARGET_X86_64 is hard-pinned UNDEFINED in this toolchain (see nx_syscalls_x86_64.nx
2047// and nx_tokenizer.nx), so the @ifndef branch is what compiles and the x86 backend TRANSLATES RV64
2048// syscall numbers at emit time. Under that translation 53 is RV64 fchmodat, whose SECOND argument
2049// is a path pointer -- and SOCK_STREAM==1 as a path pointer is exactly EFAULT, every time,
2050// regardless of the other arguments.
2051// * VARYING THE ARGUMENTS CAN NEVER REVEAL THAT THE SYSCALL NUMBER IS WRONG: every variant is
2052// equally wrong, so a set of controls that all agree reads as a confident finding about the host.
2053// The control that actually discriminated was PRINTING THE CONSTANT the binary emits.
2054// => The likely correct value here is the RV64 number 199, exactly as sendmsg/recvmsg above needed
2055// their own numbers rather than the guarded pair. That is NOT asserted: it is UNTESTED, and this
2056// comment says so rather than shipping a plausible number with a confident sentence.
2057// => NOTHING DEPENDS ON IT. The descriptor-passing lane uses a NAMED AF_UNIX rendezvous
2058// (sys_unix_listen + sys_unix_connect_fd below), which is proven end to end by nx_scm_rights_gate
2059// and is also what nginx, HAProxy and systemd actually use to move a listener between processes.
2060// socketpair was only ever the convenience.
2061func sys_socketpair(domain: i64, sock_type: i64, protocol: i64, sv: *u8) -> i64 {
2062 return __syscall(SYS_SOCKETPAIR, domain, sock_type, protocol, sv, 0, 0)
2063}
2064
2065// Bind+listen a NAMED AF_UNIX stream socket -- the accepting half of the rendezvous whose
2066// connecting half is nx_unix_connect. Returns the listening fd, or a negative errno.
2067// The caller owns the path: unlink it first (a stale node makes bind return EADDRINUSE) and unlink
2068// it after, because an AF_UNIX bind leaves a filesystem entry that outlives the process.
2069const SCM_SUN_PATH_OFF: i64 = 2 // sockaddr_un = [sa_family: u16][sun_path: 108]
2070const SCM_SUN_BYTES: i64 = 110
2071const SCM_SUN_PATH_MAX: i64 = 107
2072func sys_unix_listen(path: *u8, backlog: i64) -> i64 {
2073 let fd: i64 = sys_socket(SCM_AF_UNIX, SOCK_STREAM, 0)
2074 if fd < 0 { return fd }
2075 let sa: *u8 = sys_mmap(SCM_SUN_BYTES)
2076 var i: i64 = 0
2077 while i < SCM_SUN_BYTES { sa[i] = 0; i = i + 1 }
2078 sa[0] = SCM_AF_UNIX
2079 sa[1] = 0
2080 var p: i64 = 0
2081 while path[p] != (0 as u8) {
2082 if p >= SCM_SUN_PATH_MAX { sys_close(fd); return 0 - 36 }
2083 sa[SCM_SUN_PATH_OFF + p] = path[p]
2084 p = p + 1
2085 }
2086 let br: i64 = sys_bind(fd, sa, SCM_SUN_PATH_OFF + p + 1)
2087 if br < 0 { sys_close(fd); return br }
2088 let lr: i64 = sys_listen(fd, backlog)
2089 if lr < 0 { sys_close(fd); return lr }
2090 return fd
2091}
2092
2093// The CONNECTING half of the same rendezvous. Returns the connected fd or a negative errno.
2094// RESIDUAL NAMED RATHER THAN LEFT SILENT: nx_unix_socket.nx already carries an nx_unix_connect with
2095// this exact body. It is not composed here because that file also defines a main(), so importing it
2096// would inject a second main into every one of the 52 daemons that reach nx_http_server -- a
2097// resolution-by-definition-order hazard this tree has already been bitten by. The primitive belongs
2098// in the shim; the older standalone file should be reduced to a caller of this one, and that is a
2099// separate change to a file with its own consumers rather than something to fold in silently here.
2100func sys_unix_connect_fd(path: *u8) -> i64 {
2101 let fd: i64 = sys_socket(SCM_AF_UNIX, SOCK_STREAM, 0)
2102 if fd < 0 { return fd }
2103 let sa: *u8 = sys_mmap(SCM_SUN_BYTES)
2104 var i: i64 = 0
2105 while i < SCM_SUN_BYTES { sa[i] = 0; i = i + 1 }
2106 sa[0] = SCM_AF_UNIX
2107 sa[1] = 0
2108 var p: i64 = 0
2109 while path[p] != (0 as u8) {
2110 if p >= SCM_SUN_PATH_MAX { sys_close(fd); return 0 - 36 }
2111 sa[SCM_SUN_PATH_OFF + p] = path[p]
2112 p = p + 1
2113 }
2114 let cr: i64 = sys_connect(fd, sa, SCM_SUN_PATH_OFF + p + 1)
2115 if cr < 0 { sys_close(fd); return cr }
2116 return fd
2117}
2118
2119// Send ONE open descriptor over a connected AF_UNIX socket. Returns the sendmsg result: the number
2120// of ordinary data bytes sent (SCM_PAYLOAD_BYTES on success) or a negative errno. The descriptor
2121// itself is NOT closed here -- both ends legitimately hold it until the sender chooses to let go,
2122// and that overlap is the entire point: there must be no instant at which zero processes hold the
2123// listening socket.
2124func sys_send_fd(sock: i64, fd: i64) -> i64 {
2125 let msg: *u8 = sys_mmap(SCM_MSGHDR_BYTES)
2126 let iov: *u8 = sys_mmap(SCM_IOVEC_BYTES)
2127 let cbuf: *u8 = sys_mmap(SCM_CMSG_SPACE_1FD)
2128 let data: *u8 = sys_mmap(SCM_PAYLOAD_BYTES)
2129 scm_zero(msg, SCM_MSGHDR_BYTES)
2130 scm_zero(cbuf, SCM_CMSG_SPACE_1FD)
2131 data[0] = SCM_PAYLOAD_BYTE
2132 scm_put_i64(iov, SCM_IOVEC_OFF_BASE, data as i64)
2133 scm_put_i64(iov, SCM_IOVEC_OFF_LEN, SCM_PAYLOAD_BYTES)
2134 scm_put_i64(msg, SCM_MSGHDR_OFF_IOV, iov as i64)
2135 scm_put_i64(msg, SCM_MSGHDR_OFF_IOVLEN, SCM_IOV_COUNT_ONE)
2136 scm_put_i64(msg, SCM_MSGHDR_OFF_CTRL, cbuf as i64)
2137 scm_put_i64(msg, SCM_MSGHDR_OFF_CTRLLEN, SCM_CMSG_SPACE_1FD)
2138 scm_put_i64(cbuf, SCM_CMSG_OFF_LEN, SCM_CMSG_LEN_1FD)
2139 scm_put_u32(cbuf, SCM_CMSG_OFF_LEVEL, SCM_SOL_SOCKET)
2140 scm_put_u32(cbuf, SCM_CMSG_OFF_TYPE, SCM_RIGHTS_TYPE)
2141 scm_put_u32(cbuf, SCM_CMSG_OFF_DATA, fd)
2142 let r: i64 = sys_sendmsg(sock, msg, 0)
2143 sys_munmap(msg, SCM_MSGHDR_BYTES)
2144 sys_munmap(iov, SCM_IOVEC_BYTES)
2145 sys_munmap(cbuf, SCM_CMSG_SPACE_1FD)
2146 sys_munmap(data, SCM_PAYLOAD_BYTES)
2147 return r
2148}
2149
2150// Receive ONE descriptor from a connected AF_UNIX socket. Returns the NEW descriptor number in this
2151// process (>= 0), a negative errno from recvmsg, or one of the SCM_ERR_* codes above.
2152// flags: 0, or SCM_MSG_CMSG_CLOEXEC so the arriving descriptor is not leaked into grandchildren --
2153// the estate has already lost a port for six days to exactly that inheritance (nx_cloexec_gate).
2154// THE VALIDATION IS THE WHOLE POINT. recvmsg happily returns a positive byte count having delivered
2155// no ancillary data at all, so the kernel's REWRITTEN msg_controllen is read back rather than the
2156// value we asked for, and each of the three cmsg header fields is checked separately so a failure
2157// says which one.
2158func sys_recv_fd(sock: i64, flags: i64) -> i64 {
2159 let msg: *u8 = sys_mmap(SCM_MSGHDR_BYTES)
2160 let iov: *u8 = sys_mmap(SCM_IOVEC_BYTES)
2161 let cbuf: *u8 = sys_mmap(SCM_CMSG_SPACE_1FD)
2162 let data: *u8 = sys_mmap(SCM_PAYLOAD_BYTES)
2163 scm_zero(msg, SCM_MSGHDR_BYTES)
2164 scm_zero(cbuf, SCM_CMSG_SPACE_1FD)
2165 scm_put_i64(iov, SCM_IOVEC_OFF_BASE, data as i64)
2166 scm_put_i64(iov, SCM_IOVEC_OFF_LEN, SCM_PAYLOAD_BYTES)
2167 scm_put_i64(msg, SCM_MSGHDR_OFF_IOV, iov as i64)
2168 scm_put_i64(msg, SCM_MSGHDR_OFF_IOVLEN, SCM_IOV_COUNT_ONE)
2169 scm_put_i64(msg, SCM_MSGHDR_OFF_CTRL, cbuf as i64)
2170 scm_put_i64(msg, SCM_MSGHDR_OFF_CTRLLEN, SCM_CMSG_SPACE_1FD)
2171 let r: i64 = sys_recvmsg(sock, msg, flags)
2172 var out: i64 = r
2173 if r >= 0 {
2174 out = SCM_ERR_NO_CMSG
2175 if scm_get_i64(msg, SCM_MSGHDR_OFF_CTRLLEN) >= SCM_CMSG_LEN_1FD {
2176 out = SCM_ERR_CMSG_LEN
2177 if scm_get_i64(cbuf, SCM_CMSG_OFF_LEN) == SCM_CMSG_LEN_1FD {
2178 out = SCM_ERR_CMSG_LEVEL
2179 if scm_get_u32(cbuf, SCM_CMSG_OFF_LEVEL) == SCM_SOL_SOCKET {
2180 out = SCM_ERR_CMSG_TYPE
2181 if scm_get_u32(cbuf, SCM_CMSG_OFF_TYPE) == SCM_RIGHTS_TYPE {
2182 out = scm_get_u32(cbuf, SCM_CMSG_OFF_DATA)
2183 }
2184 }
2185 }
2186 }
2187 }
2188 sys_munmap(msg, SCM_MSGHDR_BYTES)
2189 sys_munmap(iov, SCM_IOVEC_BYTES)
2190 sys_munmap(cbuf, SCM_CMSG_SPACE_1FD)
2191 sys_munmap(data, SCM_PAYLOAD_BYTES)
2192 return out
2193}
2194
2195// Ordinary permission bits only. Special privilege bits are never copied by staging.
2196const NX_FILE_PERMISSION_MASK:i64=511
2197const NX_FILE_DESCRIPTOR_INVALID:i64=0-22
2198func sys_fchmod_fd(fd:i64,mode:i64)->i64{
2199 if fd<0 || mode<0 || mode>NX_FILE_PERMISSION_MASK {return NX_FILE_DESCRIPTOR_INVALID}
2200 return __syscall(52,fd,mode,0,0,0,0)
2201}
2202// Portable descriptor syscall; consumers below use the x86-64 stat ABI layout.
2203const NX_STAT_X64_BYTES:i64=144
2204const NX_STAT_X64_MODE_OFFSET:i64=24
2205const NX_STAT_X64_BLOCK_OFFSET:i64=56
2206const NX_STAT_X64_SIZE_OFFSET:i64=48
2207const NX_STAT_X64_DEVICE_OFFSET:i64=0
2208const NX_STAT_X64_INODE_OFFSET:i64=8
2209const NX_STAT_TYPE_MASK:i64=61440
2210const NX_STAT_REGULAR_FILE:i64=32768
2211func sys_fstat_fd(fd:i64,stat:*u8)->i64{
2212 if fd<0 || (stat as i64)==0{return NX_FILE_DESCRIPTOR_INVALID}
2213 return __syscall(80,fd,stat,0,0,0,0)
2214}
2215func sys_stat_permissions(stat:*u8)->i64{
2216 let mode:i64=(stat[NX_STAT_X64_MODE_OFFSET] as i64)+((stat[NX_STAT_X64_MODE_OFFSET+1] as i64)<<8)
2217 return mode & NX_FILE_PERMISSION_MASK
2218}
2219
2220// base64.nx -- RFC 4648 base64 encoder + decoder.
2221//
2222// Canonical: this is the substrate-wide canonical Base64 (RFC 4648
2223// §4 standard alphabet) per [[feedback-no-tool-proliferation-bit-
2224// level]]. Variants that need URL-safe alphabet (RFC 4648 §5) are
2225// candidates for ONE distinct sibling primitive nx_base64_url.nx
2226// (queued) that imports THIS file's encode/decode skeleton; all
2227// other consumers compose THIS file's encode/decode primitives.
2228// Re-implementing the Base64 alphabet or quantum-loop inline is
2229// refused.
2230//
2231// Used for:
2232// - PEM decoding of X.509 certs (thin ASCII wrapper around DER)
2233// - TLS 1.3 pre-shared key encoding
2234// - HTTP Basic auth, OAuth tokens, JWT
2235// - Web content (data: URIs, JSON-embedded bytes)
2236//
2237// Standard alphabet (RFC 4648 §4):
2238// 0-25 : A-Z
2239// 26-51 : a-z
2240// 52-61 : 0-9
2241// 62 : +
2242// 63 : /
2243// pad : =
2244//
2245// URL-safe alphabet variant (§5) swaps +/ for -_; provided as
2246// b64url_encode / b64url_decode.
2247//
2248// Invariants:
2249// B1 Input/output lengths are predictable:
2250// encode(n bytes) -> 4 * ceil(n / 3) chars
2251// decode(n chars) -> 3 * (n / 4) - padding bytes
2252// B2 Decoder rejects invalid input (non-alphabet chars) by
2253// returning a negative length. No silent skip.
2254// B3 Decoder is tolerant of missing padding (RFC 4648 §3.2
2255// permits this as "unpadded" variant).
2256// B4 Encoder is deterministic; same input -> same output. No
2257// trailing whitespace, no line breaks inserted. Callers
2258// that want MIME-style 76-char wrap do it outside.
2259//
2260// license_tier: INDEPENDENT_REDERIVE
2261// genealogy_id: international-research-sources/ietf/rfc_8446
2262//
2263
2264// nx_safety_envelope:
2265// intended_use: AUTO_APPLIED -- primitive-specific tuning queued
2266// sil_target: SIL1
2267// evidence: [bulk_applied_2026-05-16, see-file-comment-for-detail]
2268// verdict: NOT_YET_EVALUATED
2269//
2270// F-meta-4 refactor 2026-05-17: removed `import "nx_syscalls.nx"`.
2271// This file is pure -- all functions operate on caller-provided
2272// buffers + stack-local counters. Composing with any syscall layer
2273// (nx_syscalls.nx OR nx_syscalls_x86_64.nx) no longer hits the
2274// duplicate-symbol bug class. Unblocks crypto chain (nx_jwt ->
2275// nx_jose / jwk / acme / csr) for x86_64 native runtime testing.
2276
2277const B64_PAD: i64 = 0x3D // '='
2278
2279// Encode one 6-bit index to an ASCII char. Standard alphabet.
2280func b64_enc_char(n: i64) -> i64 {
2281 let v: i64 = n & 0x3F
2282 if v < 26 { return 0x41 + v } // 'A'..'Z'
2283 if v < 52 { return 0x61 + (v - 26) } // 'a'..'z'
2284 if v < 62 { return 0x30 + (v - 52) } // '0'..'9'
2285 if v == 62 { return 0x2B } // '+'
2286 return 0x2F // '/'
2287}
2288
2289// URL-safe variant: replace + / with - _
2290func b64url_enc_char(n: i64) -> i64 {
2291 let v: i64 = n & 0x3F
2292 if v < 26 { return 0x41 + v }
2293 if v < 52 { return 0x61 + (v - 26) }
2294 if v < 62 { return 0x30 + (v - 52) }
2295 if v == 62 { return 0x2D } // '-'
2296 return 0x5F // '_'
2297}
2298
2299// Decode one ASCII char to 6-bit value; returns -1 if invalid.
2300// Accepts either standard (+,/) or URL-safe (-,_) variants.
2301func b64_dec_char(c: i64) -> i64 {
2302 if c >= 0x41 { if c <= 0x5A { return c - 0x41 } } // A-Z
2303 if c >= 0x61 { if c <= 0x7A { return c - 0x61 + 26 } } // a-z
2304 if c >= 0x30 { if c <= 0x39 { return c - 0x30 + 52 } } // 0-9
2305 if c == 0x2B { return 62 } // +
2306 if c == 0x2F { return 63 } // /
2307 if c == 0x2D { return 62 } // - (URL-safe)
2308 if c == 0x5F { return 63 } // _ (URL-safe)
2309 return -1
2310}
2311
2312// Encode `n` bytes from `in_bytes` to `out`; returns written length.
2313// Output size: 4 * ceil(n / 3) chars. Pads with '=' to full groups.
2314func b64_encode(in_bytes: *u8, n: i64, out: *u8) -> i64 {
2315 var pos: i64 = 0
2316 var out_pos: i64 = 0
2317 while pos + 3 <= n {
2318 let b0: i64 = in_bytes[pos]
2319 let b1: i64 = in_bytes[pos + 1]
2320 let b2: i64 = in_bytes[pos + 2]
2321 out[out_pos + 0] = b64_enc_char((b0 >> 2) & 0x3F)
2322 out[out_pos + 1] = b64_enc_char(((b0 << 4) | (b1 >> 4)) & 0x3F)
2323 out[out_pos + 2] = b64_enc_char(((b1 << 2) | (b2 >> 6)) & 0x3F)
2324 out[out_pos + 3] = b64_enc_char(b2 & 0x3F)
2325 pos = pos + 3
2326 out_pos = out_pos + 4
2327 }
2328 let remain: i64 = n - pos
2329 if remain == 1 {
2330 let b0: i64 = in_bytes[pos]
2331 out[out_pos + 0] = b64_enc_char((b0 >> 2) & 0x3F)
2332 out[out_pos + 1] = b64_enc_char((b0 << 4) & 0x3F)
2333 out[out_pos + 2] = B64_PAD
2334 out[out_pos + 3] = B64_PAD
2335 out_pos = out_pos + 4
2336 }
2337 if remain == 2 {
2338 let b0: i64 = in_bytes[pos]
2339 let b1: i64 = in_bytes[pos + 1]
2340 out[out_pos + 0] = b64_enc_char((b0 >> 2) & 0x3F)
2341 out[out_pos + 1] = b64_enc_char(((b0 << 4) | (b1 >> 4)) & 0x3F)
2342 out[out_pos + 2] = b64_enc_char((b1 << 2) & 0x3F)
2343 out[out_pos + 3] = B64_PAD
2344 out_pos = out_pos + 4
2345 }
2346 return out_pos
2347}
2348
2349// Grab one sextet: return 0..63 on valid, -1 on '=' or end-of-input,
2350// -2 on any other invalid char. Advances *pos on success.
2351func b64_grab(in_chars: *u8, n: i64, pos: *i64) -> i64 {
2352 let p: i64 = *pos
2353 if p >= n { return -1 }
2354 let c: i64 = in_chars[p]
2355 if c == B64_PAD {
2356 *pos = n + 1
2357 return -1
2358 }
2359 let v: i64 = b64_dec_char(c)
2360 if v < 0 { return -2 }
2361 *pos = p + 1
2362 return v
2363}
2364
2365// Decode `n` base64 chars into raw bytes. Returns bytes written on
2366// success or -1 on invalid input. Tolerant of missing padding (B3).
2367// Whitespace is NOT skipped.
2368//
2369// F-meta-4 refactor: position counter is a stack-local; no sys_mmap.
2370func b64_decode(in_chars: *u8, n: i64, out: *u8) -> i64 {
2371 var pos: i64 = 0
2372 var out_pos: i64 = 0
2373 while pos < n {
2374 let s0: i64 = b64_grab(in_chars, n, &pos)
2375 if s0 == -2 { return -1 }
2376 if s0 < 0 { return out_pos }
2377 let s1: i64 = b64_grab(in_chars, n, &pos)
2378 if s1 == -2 { return -1 }
2379 if s1 < 0 { return -1 } // single lonely char invalid
2380 out[out_pos] = ((s0 << 2) | (s1 >> 4)) & 0xFF
2381 out_pos = out_pos + 1
2382 let s2: i64 = b64_grab(in_chars, n, &pos)
2383 if s2 == -2 { return -1 }
2384 if s2 < 0 { return out_pos }
2385 out[out_pos] = ((s1 << 4) | (s2 >> 2)) & 0xFF
2386 out_pos = out_pos + 1
2387 let s3: i64 = b64_grab(in_chars, n, &pos)
2388 if s3 == -2 { return -1 }
2389 if s3 < 0 { return out_pos }
2390 out[out_pos] = ((s2 << 6) | s3) & 0xFF
2391 out_pos = out_pos + 1
2392 }
2393 return out_pos
2394}
2395
2396// Self-test main() removed by F-meta-4 refactor (used sys_mmap; this
2397// file is now syscall-free). Round-trip smoke lives in a separate
2398// nx_base64_test.nx that imports a caller-chosen syscall layer.
2399
2400// Native packaging by artifact reference; no publication or engine-acceptance claim.
2401// nx_fsops_lib.nx -- CONSOLIDATED filesystem tool (MCP name: nx_fs, tool #4 of the 15), LIBRARY half.
2402// (Source is named nx_fsops because nx_fs.nx is the safety-enveloped file-I/O STDLIB -- a different thing.)
2403// READ-ONLY first increment: `read` (bounded file read) + `ls` (typed dir listing). Retires ssh-cat for
2404// remote reads per rule 27 (api-first, no shell plumbing).
2405//
2406// BOUNDARY DEFENSE (rule 12 -- MCP callers are EXTERNAL input): `read` REFUSES any path that matches the
2407// secret DENY-LIST: compiled-in default needles (secret/key/token/passw/.pem, matched case-insensitively
2408// against the WHOLE path) plus data-driven extras from fs_read_deny.conf (one lowercase needle per line,
2409// CWD-relative -- rule 11: policy in data, not code). The tools-api runs where key material lives; an
2410// arbitrary-read tool that could return opaque_keys.bin or tools_cap_secret.key would convert a read-cap
2411// into a key-theft primitive. Over-blocking is the SAFE failure direction for v1.
2412// WRITE/EDIT increment (2026-07-16): fsx_write (ATOMIC tmp+fsync+rename) + fsx_edit (exact-string replace
2413// with the Claude-Edit UNIQUENESS contract). Exposed as the SEPARATE tools-api name `nx_fs_write` (its own
2414// cap class per knowledge/mcp/exposure_policy.txt: read=broad, write=cap) -- the `nx_fs` name stays read-only.
2415// The write DENY is a superset of the read deny (never clobber key material) PLUS the OS device/kernel/
2416// firmware namespace via the nx_os_fs seam (rule 26 never-brick BY CONSTRUCTION -- not config-disableable)
2417// PLUS the tool-registry escalation surface ("allowlist") PLUS data-driven extras (fs_write_deny.conf).
2418// license_tier: ORIGINAL
2419
2420// nx_fio.nx -- canonical sovereign file operations: unlink (delete) + existence check. Importable (no main).
2421// Retires Remove-Item / rm. rename is already canonical (sys_renameat in nx_syscalls). unlinkat x86_64=263 is passed
2422// DIRECTLY (the fsync-74 / fstatat-262 / unlinkat-263 precedent: a raw x86_64 number not in the rv64->x86 swap table
2423// passes through untranslated). AT_FDCWD=-100, flags=0. Returns 0 on success, -errno on failure. license_tier: ORIGINAL
2424
2425// sha256.nx -- SHA-256 in pure NishiLang (Phase G9, FIPS 180-4).
2426//
2427// Canonical: this is the substrate-wide canonical SHA-256
2428// implementation per [[feedback-no-tool-proliferation-bit-level]].
2429// HMAC-SHA256 / HKDF-SHA256 / DRBG-SHA256 etc. compose THIS file's
2430// sha256 primitive; they're distinct primitives (different specs:
2431// FIPS 198-1 HMAC, RFC 5869 HKDF, NIST SP 800-90A DRBG) but all
2432// share THIS sha256 as their SHA-256 backbone. Re-implementing
2433// the SHA-256 K-table or round function inline is refused.
2434//
2435// license_tier: INDEPENDENT_REDERIVE
2436// genealogy_id: international-research-sources/nist/fips_180_4
2437//
2438// Used for: content-addressed build artifacts (F6), session tokens
2439// (rand.nx + sha256 = HMAC), TLS 1.3 handshake (G15), Git-style
2440// object addressing, reproducible-build attestation.
2441//
2442// Implementation follows FIPS 180-4 section 6.2 exactly -- no
2443// precomputed tables beyond the standard K[0..63] round constants.
2444// Pure i64 arithmetic; all 32-bit ops masked with 0xFFFFFFFF.
2445//
2446// API:
2447// sha256_init(*ctx) — reset a fresh Sha256 context
2448// sha256_update(*ctx, *u8 bytes, len) — feed input chunks
2449// sha256_final(*ctx, *u8 out32) — write 32-byte digest
2450// sha256_digest(*u8 bytes, len, *u8 out32) — one-shot convenience
2451//
2452// The context is ~128 bytes: 8 words of hash state + 64-byte partial
2453// block buffer + 8-byte length counter + an index. Caller allocates
2454// (stack or heap) and passes pointer.
2455//
2456// nx_safety_envelope: (schema: nishi-library/seeds/safety-critical-standards.toml)
2457// intended_use: "SHA-256 cryptographic hash -- HMAC + HKDF
2458// + content-addressed storage + digital
2459// signatures + Wheeler-DDC integrity chain"
2460// sil_target: SIL3 (integrity primitive; collision or
2461// preimage attack = signature forgery)
2462// asil_target: QM
2463// dal_target: DAL B
2464// iec_62304_class: B
2465// evidence: [no_floating_point, no_table_lookup,
2466// bit_equal_reproducible,
2467// FIPS_180-4_Sec_5_3_3_init_vector,
2468// NIST_CAVP_test_vectors_VERIFIED,
2469// constant_time_by_construction,
2470// license_tier_INDEPENDENT_REDERIVE]
2471// hazard_register: [bug-tape-length-extension-attack,
2472// bug-tape-implementation-skipping-final-block,
2473// bug-tape-state-not-cleared-after-use]
2474// residual_risk: "Length-extension attack applies to raw
2475// SHA-256. Callers MUST use HMAC-SHA-256
2476// (nx_hmac) for keyed scenarios; never raw
2477// SHA-256(key || msg). Substrate cannot
2478// enforce this from the hash primitive's
2479// boundary; it's a composition responsibility."
2480// verdict: NOT_YET_EVALUATED
2481
2482
2483// nx_bits.nx -- bit-manipulation primitives, dispatching to hardware
2484// intrinsics on supported backends with portable software fallbacks.
2485//
2486// Inspired by Hacker's Delight (Henry S. Warren Jr.) -- the canonical
2487// reference for bit-twiddling. Every soft path is BRANCHLESS or
2488// minimally-branched, FIXED-CYCLE, and CROSS-ARCH PORTABLE.
2489//
2490// Dispatch model:
2491// nx_bits_popcount64 / nx_bits_clz32 / nx_bits_ctz32 -> backend
2492// intrinsic on x86_64 (popcntq/bsrl+xor/bsfl) and rv64 with Zbb
2493// (cpop/clzw/ctzw). One machine instruction. Used by hot paths
2494// (sketches, hashing, bitmap iteration).
2495//
2496// nx_bits_popcount64_soft / nx_bits_clz32_soft / nx_bits_ctz32_soft
2497// -- pure-NishiLang SWAR + binary-search variants. Cross-arch
2498// portable to backends without bit-count opcodes. Used by paired
2499// correctness oracles and any caller targeting an exotic ISA.
2500//
2501// Substrate "get off C" trajectory: this module is pure NishiLang.
2502
2503// syscalls.nx -- alias stub.
2504//
2505// nx_syscalls.nx is the canonical syscall surface: same 15 funcs
2506// this file used to define (sys_write/read/mmap/openat/close/exit/
2507// brk/lseek/getpid/kill/fork/execve/wait4/clone/ioctl) plus 9
2508// additions for sockets and time (sys_socket/bind/listen/accept/
2509// connect/clock_gettime_mono/now_ms/sleep_ms/openat_append).
2510//
2511// Consumers using `import "syscalls.nx"` resolve via NishiLang's
2512// textual import splicing with path-dedup (runtime/import.nx I1):
2513// this stub splices nx_syscalls.nx once, and any other file that
2514// also imports "nx_syscalls.nx" directly gets deduped to the same
2515// canonical splice. No duplicate symbols. This fixed the
2516// nxasm_main.nx duplicate-symbol error on first link 2026-05-19.
2517//
2518// Deprecation: when every "syscalls.nx" consumer migrates to the
2519// nx_-prefixed name, delete this stub. bench/nx_import_closure.sh
2520// will catch any straggler before the build ships.
2521
2522
2523
2524
2525// === popcount FAST: dispatches to backend intrinsic ==============
2526
2527func nx_bits_popcount64(x: i64) -> i64 {
2528 return __popcnt64(x)
2529}
2530
2531func nx_bits_popcount32(x: i64) -> i64 {
2532 return __popcnt64(x & 0xFFFFFFFF)
2533}
2534
2535// === clz32 / ctz32 FAST: backend intrinsic =======================
2536// __clz32(0) and __ctz32(0) both return 32 on both backends (x86
2537// uses a tested fallback to set the result; rv64 Zbb returns 32 by
2538// spec) so the wrapper is a thin pass-through.
2539
2540func nx_bits_clz32(x: i64) -> i64 {
2541 return __clz32(x)
2542}
2543
2544func nx_bits_ctz32(x: i64) -> i64 {
2545 return __ctz32(x)
2546}
2547
2548// 64-bit clz / ctz: composed from two 32-bit intrinsics. Until the
2549// backend grows OP_CLZ64 / OP_CTZ64 these are still ~3-instruction
2550// hot paths vs the legacy 64-iteration loops, so they replace those
2551// substrate-wide. clz(0) = 64; ctz(0) = 64.
2552
2553func nx_bits_clz64(x: i64) -> i64 {
2554 let hi: i64 = (x >> 32) & 0xFFFFFFFF
2555 if hi != 0 { return __clz32(hi) }
2556 return 32 + __clz32(x & 0xFFFFFFFF)
2557}
2558
2559func nx_bits_ctz64(x: i64) -> i64 {
2560 let lo: i64 = x & 0xFFFFFFFF
2561 if lo != 0 { return __ctz32(lo) }
2562 if x == 0 { return 64 }
2563 return 32 + __ctz32((x >> 32) & 0xFFFFFFFF)
2564}
2565
2566// === rotate left / right FAST: backend intrinsic ================
2567// Hardware native via rolq/rorq (x86_64, 1985) and rol/ror (rv64
2568// Zbb). Mask the count to 0..63 so the substrate exposes
2569// "rotate-mod-64" semantics on both ISAs (x86_64 already masks; rv64
2570// behaviour is identical with the explicit mask).
2571
2572func nx_bits_rotl64(x: i64, n: i64) -> i64 {
2573 return __rotl64(x, n & 63)
2574}
2575
2576func nx_bits_rotr64(x: i64, n: i64) -> i64 {
2577 return __rotr64(x, n & 63)
2578}
2579
2580// 32-bit rotate (no native intrinsic emitted; we pre-mask the value
2581// to its low 32 bits so the i64 arithmetic shift right doesn't
2582// contaminate with sign bits, then mask the result back to 32 bits).
2583// ~3 ops vs 5-7 in inline rotr32/rotl32 callsites scattered across
2584// crypto modules (SHA-256, ChaCha20, MurmurHash, etc.).
2585
2586func nx_bits_rotl32(x: i64, n: i64) -> i64 {
2587 let v: i64 = x & 0xFFFFFFFF
2588 let nn: i64 = n & 31
2589 if nn == 0 { return v }
2590 return ((v << nn) | (v >> (32 - nn))) & 0xFFFFFFFF
2591}
2592
2593func nx_bits_rotr32(x: i64, n: i64) -> i64 {
2594 let v: i64 = x & 0xFFFFFFFF
2595 let nn: i64 = n & 31
2596 if nn == 0 { return v }
2597 return ((v >> nn) | (v << (32 - nn))) & 0xFFFFFFFF
2598}
2599
2600// === byte-reverse FAST: backend intrinsic =========================
2601// bswapq (x86_64, i486 1989+, universal) and rev8 (rv64 Zbb). 1
2602// cycle vs the 13-op SWAR phrasing. Used by every endian flip,
2603// every network/header parse, SHA-256 big-endian word loads.
2604
2605func nx_bits_bswap64(x: i64) -> i64 {
2606 return __bswap64(x)
2607}
2608
2609// 32-bit byte-reverse: mask to low 32 (zero-extends the i64), bswap
2610// the whole register -- the four low bytes get reversed into the top
2611// half -- then shift down to recover them. Mask after shift to
2612// discard the sign extension on inputs where bit 31 of the bswapped
2613// low half is set (which becomes bit 63 of the 64-bit register).
2614func nx_bits_bswap32(x: i64) -> i64 {
2615 return (__bswap64(x & 0xFFFFFFFF) >> 32) & 0xFFFFFFFF
2616}
2617
2618// === SOFT fallbacks: pure NishiLang, cross-arch portable =========
2619
2620func nx_bits_popcount64_soft(x: i64) -> i64 {
2621 var v: i64 = x
2622 v = v - ((v >> 1) & 0x5555555555555555)
2623 v = (v & 0x3333333333333333) + ((v >> 2) & 0x3333333333333333)
2624 v = (v + (v >> 4)) & 0x0F0F0F0F0F0F0F0F
2625 return ((v * 0x0101010101010101) >> 56) & 0xFF
2626}
2627
2628func nx_bits_popcount32_soft(x: i64) -> i64 {
2629 var v: i64 = x & 0xFFFFFFFF
2630 v = v - ((v >> 1) & 0x55555555)
2631 v = (v & 0x33333333) + ((v >> 2) & 0x33333333)
2632 v = (v + (v >> 4)) & 0x0F0F0F0F
2633 return ((v * 0x01010101) >> 24) & 0xFF
2634}
2635
2636func nx_bits_clz32_soft(x: i64) -> i64 {
2637 let lo: i64 = x & 0xFFFFFFFF
2638 if lo == 0 { return 32 }
2639 var t: i64 = lo
2640 var n: i64 = 0
2641 if (t & 0xFFFF0000) == 0 { n = n + 16; t = t << 16; t = t & 0xFFFFFFFF }
2642 if (t & 0xFF000000) == 0 { n = n + 8; t = t << 8; t = t & 0xFFFFFFFF }
2643 if (t & 0xF0000000) == 0 { n = n + 4; t = t << 4; t = t & 0xFFFFFFFF }
2644 if (t & 0xC0000000) == 0 { n = n + 2; t = t << 2; t = t & 0xFFFFFFFF }
2645 if (t & 0x80000000) == 0 { n = n + 1 }
2646 return n
2647}
2648
2649// 64-bit rotate soft fallback (pure NishiLang -- shift+or, ~5 ops).
2650// Used by paired correctness oracle and by backends without rotate
2651// opcodes. Note: shifting by 0 is the identity; explicit branch
2652// avoids the undefined-behaviour case of `x >> 64` on some ISAs.
2653
2654// The signed >> arithmetic-shifts sign bits in for negative x, so the
2655// shifted-right half must be masked to the actual m / (64-m) low bits
2656// to discard the sign extension.
2657
2658func nx_bits_rotl64_soft(x: i64, n: i64) -> i64 {
2659 let m: i64 = n & 63
2660 if m == 0 { return x }
2661 let top: i64 = (x >> (64 - m)) & ((1 << m) - 1)
2662 return (x << m) | top
2663}
2664
2665func nx_bits_rotr64_soft(x: i64, n: i64) -> i64 {
2666 let m: i64 = n & 63
2667 if m == 0 { return x }
2668 let low: i64 = (x >> m) & ((1 << (64 - m)) - 1)
2669 return low | (x << (64 - m))
2670}
2671
2672// bswap SOFT (Hacker's Delight 7-1, 13-op SWAR). Used by paired
2673// oracle and exotic backends.
2674
2675func nx_bits_bswap64_soft(x: i64) -> i64 {
2676 var v: i64 = x
2677 v = ((v & 0x00FF00FF00FF00FF) << 8) | ((v >> 8) & 0x00FF00FF00FF00FF)
2678 v = ((v & 0x0000FFFF0000FFFF) << 16) | ((v >> 16) & 0x0000FFFF0000FFFF)
2679 v = ((v & 0x00000000FFFFFFFF) << 32) | ((v >> 32) & 0x00000000FFFFFFFF)
2680 return v
2681}
2682
2683func nx_bits_bswap32_soft(x: i64) -> i64 {
2684 let v: i64 = x & 0xFFFFFFFF
2685 let b0: i64 = (v >> 24) & 0xFF
2686 let b1: i64 = (v >> 16) & 0xFF
2687 let b2: i64 = (v >> 8) & 0xFF
2688 let b3: i64 = (v ) & 0xFF
2689 return (b3 << 24) | (b2 << 16) | (b1 << 8) | b0
2690}
2691
2692// 32-bit rotate SOFT (identical body to FAST; no separate intrinsic
2693// path) -- kept as the named-soft for the consolidation paired-oracle
2694// convention.
2695func nx_bits_rotl32_soft(x: i64, n: i64) -> i64 {
2696 return nx_bits_rotl32(x, n)
2697}
2698func nx_bits_rotr32_soft(x: i64, n: i64) -> i64 {
2699 return nx_bits_rotr32(x, n)
2700}
2701
2702// 64-bit soft fallbacks (Knuth TAOCP 4A linear-scan). O(64) iterations
2703// in the worst case; used by the paired oracle and by exotic backends.
2704
2705func nx_bits_clz64_soft(x: i64) -> i64 {
2706 if x == 0 { return 64 }
2707 var v: i64 = x
2708 var n: i64 = 0
2709 var mask: i64 = 0x8000000000000000
2710 var done: i64 = 0
2711 while done == 0 {
2712 if (v & mask) != 0 { done = 1 }
2713 if done == 0 {
2714 n = n + 1
2715 mask = mask >> 1
2716 if mask == 0 { done = 1 }
2717 }
2718 }
2719 return n
2720}
2721
2722func nx_bits_ctz64_soft(x: i64) -> i64 {
2723 if x == 0 { return 64 }
2724 var v: i64 = x
2725 var n: i64 = 0
2726 var done: i64 = 0
2727 while done == 0 {
2728 if (v & 1) != 0 { done = 1 }
2729 if done == 0 {
2730 n = n + 1
2731 v = v >> 1
2732 if n >= 64 { done = 1 }
2733 }
2734 }
2735 return n
2736}
2737
2738func nx_bits_ctz32_soft(x: i64) -> i64 {
2739 let lo: i64 = x & 0xFFFFFFFF
2740 if lo == 0 { return 32 }
2741 var t: i64 = lo
2742 var n: i64 = 0
2743 if (t & 0x0000FFFF) == 0 { n = n + 16; t = t >> 16 }
2744 if (t & 0x000000FF) == 0 { n = n + 8; t = t >> 8 }
2745 if (t & 0x0000000F) == 0 { n = n + 4; t = t >> 4 }
2746 if (t & 0x00000003) == 0 { n = n + 2; t = t >> 2 }
2747 if (t & 0x00000001) == 0 { n = n + 1 }
2748 return n
2749}
2750
2751// === isolate lowest set bit (Hacker's Delight 2-1) ================
2752//
2753// x & -x selects only the lowest 1-bit of x. Useful for iterating
2754// set bits in a bitmap (faster than testing each bit).
2755// for bitmap != 0:
2756// bit = nx_bits_lowest(bitmap)
2757// // process bit
2758// bitmap = bitmap ^ bit // clear it
2759
2760func nx_bits_lowest(x: i64) -> i64 {
2761 return x & (0 - x)
2762}
2763
2764// === reset lowest set bit (Hacker's Delight 2-1) ==================
2765//
2766// x & (x-1) clears the lowest 1-bit. When combined with popcount,
2767// gives O(popcount) bit-traversal loops -- faster than O(width)
2768// when the bitmap is sparse.
2769
2770func nx_bits_clear_lowest(x: i64) -> i64 {
2771 return x & (x - 1)
2772}
2773
2774// === is power of 2 (Hacker's Delight 2-1) =========================
2775//
2776// x > 0 AND (x & (x-1)) == 0. One subtract + one and + one compare.
2777
2778func nx_bits_is_pow2(x: i64) -> i64 {
2779 if x <= 0 { return 0 }
2780 if (x & (x - 1)) == 0 { return 1 }
2781 return 0
2782}
2783
2784// === next power of 2 (Hacker's Delight 3-2) =======================
2785//
2786// Round up to next power of 2. For x already pow2, returns x.
2787// For x = 0, returns 1. Standard "smear high bit" pattern.
2788
2789func nx_bits_next_pow2_32(x: i64) -> i64 {
2790 if x <= 1 { return 1 }
2791 var v: i64 = (x - 1) & 0xFFFFFFFF
2792 v = v | (v >> 1)
2793 v = v | (v >> 2)
2794 v = v | (v >> 4)
2795 v = v | (v >> 8)
2796 v = v | (v >> 16)
2797 return (v + 1) & 0xFFFFFFFF
2798}
2799
2800// === parity (Hacker's Delight 5-1) ================================
2801//
2802// Returns 1 if odd number of set bits, 0 if even. Two-and-XOR
2803// reduction, branchless.
2804
2805func nx_bits_parity64(x: i64) -> i64 {
2806 var v: i64 = x
2807 v = v ^ (v >> 32)
2808 v = v ^ (v >> 16)
2809 v = v ^ (v >> 8)
2810 v = v ^ (v >> 4)
2811 return (0x6996 >> (v & 15)) & 1
2812}
2813
2814// === floor(log2(x)) ===============================================
2815//
2816// Equivalent to (31 - clz(x)) for x > 0. Returns -1 for x <= 0.
2817
2818func nx_bits_floor_log2(x: i64) -> i64 {
2819 if x <= 0 { return -1 }
2820 if x <= 0xFFFFFFFF {
2821 return 31 - nx_bits_clz32(x)
2822 }
2823 // High 32 bits set: 32 + log2(x >> 32)
2824 return 63 - nx_bits_clz32(x >> 32)
2825}
2826
2827// === bit-field extract (BMI BEXTR semantics) ======================
2828//
2829// Extract `len` bits starting at `start` from x.
2830// Equivalent to (x >> start) & ((1 << len) - 1).
2831
2832func nx_bits_bextr(x: i64, start: i64, len: i64) -> i64 {
2833 if len <= 0 { return 0 }
2834 if len >= 64 { return x >> start }
2835 let mask: i64 = (1 << len) - 1
2836 return (x >> start) & mask
2837}
2838
2839const K_MAGIC_536870912: i64 = 536870912
2840
2841struct Sha256 {
2842 // Hash state H[0..7] as i64 (low 32 bits used).
2843 h0: i64, h1: i64, h2: i64, h3: i64,
2844 h4: i64, h5: i64, h6: i64, h7: i64,
2845
2846 // Legacy byte-packed block fields (retained for struct-size
2847 // compatibility; no longer the active buffer -- see bufptr below).
2848 b0: i64, b1: i64, b2: i64, b3: i64,
2849 b4: i64, b5: i64, b6: i64, b7: i64,
2850
2851 // Byte index into the 64-byte block (0..63) and total bits
2852 // processed (for final padding).
2853 idx: i64,
2854 bit_len: i64,
2855
2856 // Scratch buffers allocated ONCE per context in sha256_init (the perf rewrite,
2857 // 2026-06-10: kills the per-block mmap syscall + the per-round K if-chain +
2858 // the linear-scan byte access). ALL three are indexed only by PUBLIC counters
2859 // (byte position / round number 0..63 / schedule index) -- never by secret data --
2860 // so constant_time_by_construction is preserved (no secret-indexed table access).
2861 bufptr: i64, // -> 64-byte contiguous block buffer (O(1) byte access)
2862 kptr: i64, // -> 64 round constants, materialized once from sha256_k()
2863 wptr: i64, // -> 64-word message schedule, reused every block
2864
2865 // Hardware SHA-NI scratch (the perf path, 2026-07-02). Allocated once per ctx.
2866 // k32ptr -> 64 CONTIGUOUS i32 round constants (the SHA-NI intrinsic wants packed 32-bit
2867 // K, whereas kptr above is 64 i64 for the software loop). st8ptr -> 8 CONTIGUOUS i32
2868 // working state a..h, marshalled from h0..h7 around each __sha256_ni_block call. ni_ok
2869 // caches the CPUID SHA-feature probe (1=use hardware, 0=software fallback) so cpuid runs
2870 // once per hash, not once per block. All three are indexed only by PUBLIC counters ->
2871 // constant_time_by_construction is preserved.
2872 k32ptr: i64, // -> 64 i32 round constants (packed), for the SHA-NI intrinsic
2873 st8ptr: i64, // -> 8 i32 working state a..h, marshalled around __sha256_ni_block
2874 ni_ok: i64, // 1 = CPU has SHA-NI (cpuid(7,0):EBX bit-29) -> hardware compress; 0 = software
2875}
2876
2877// Mask utilities.
2878const M32: i64 = 0xFFFFFFFF
2879
2880// Delegated to nx_bits_rotr32. SHA-256 round does 6 rotates per
2881// word * 64 rounds = 384 rotates per block.
2882func rotr32(x: i64, n: i64) -> i64 {
2883 return nx_bits_rotr32(x, n)
2884}
2885
2886func shr32(x: i64, n: i64) -> i64 {
2887 return (x >> n) & M32
2888}
2889
2890// SHA-256 round constants K[0..63]. Standard cube-roots-of-primes.
2891// We encode as a simple index -> constant lookup; each returns the
2892// i64 with the 32-bit constant in the low bits.
2893func sha256_k(i: i64) -> i64 {
2894 if i == 0 { return 0x428a2f98 }
2895 if i == 1 { return 0x71374491 }
2896 if i == 2 { return 0xb5c0fbcf }
2897 if i == 3 { return 0xe9b5dba5 }
2898 if i == 4 { return 0x3956c25b }
2899 if i == 5 { return 0x59f111f1 }
2900 if i == 6 { return 0x923f82a4 }
2901 if i == 7 { return 0xab1c5ed5 }
2902 if i == 8 { return 0xd807aa98 }
2903 if i == 9 { return 0x12835b01 }
2904 if i == 10 { return 0x243185be }
2905 if i == 11 { return 0x550c7dc3 }
2906 if i == 12 { return 0x72be5d74 }
2907 if i == 13 { return 0x80deb1fe }
2908 if i == 14 { return 0x9bdc06a7 }
2909 if i == 15 { return 0xc19bf174 }
2910 if i == 16 { return 0xe49b69c1 }
2911 if i == 17 { return 0xefbe4786 }
2912 if i == 18 { return 0x0fc19dc6 }
2913 if i == 19 { return 0x240ca1cc }
2914 if i == 20 { return 0x2de92c6f }
2915 if i == 21 { return 0x4a7484aa }
2916 if i == 22 { return 0x5cb0a9dc }
2917 if i == 23 { return 0x76f988da }
2918 if i == 24 { return 0x983e5152 }
2919 if i == 25 { return 0xa831c66d }
2920 if i == 26 { return 0xb00327c8 }
2921 if i == 27 { return 0xbf597fc7 }
2922 if i == 28 { return 0xc6e00bf3 }
2923 if i == 29 { return 0xd5a79147 }
2924 if i == 30 { return 0x06ca6351 }
2925 if i == 31 { return 0x14292967 }
2926 if i == 32 { return 0x27b70a85 }
2927 if i == 33 { return 0x2e1b2138 }
2928 if i == 34 { return 0x4d2c6dfc }
2929 if i == 35 { return 0x53380d13 }
2930 if i == 36 { return 0x650a7354 }
2931 if i == 37 { return 0x766a0abb }
2932 if i == 38 { return 0x81c2c92e }
2933 if i == 39 { return 0x92722c85 }
2934 if i == 40 { return 0xa2bfe8a1 }
2935 if i == 41 { return 0xa81a664b }
2936 if i == 42 { return 0xc24b8b70 }
2937 if i == 43 { return 0xc76c51a3 }
2938 if i == 44 { return 0xd192e819 }
2939 if i == 45 { return 0xd6990624 }
2940 if i == 46 { return 0xf40e3585 }
2941 if i == 47 { return 0x106aa070 }
2942 if i == 48 { return 0x19a4c116 }
2943 if i == 49 { return 0x1e376c08 }
2944 if i == 50 { return 0x2748774c }
2945 if i == 51 { return 0x34b0bcb5 }
2946 if i == 52 { return 0x391c0cb3 }
2947 if i == 53 { return 0x4ed8aa4a }
2948 if i == 54 { return 0x5b9cca4f }
2949 if i == 55 { return 0x682e6ff3 }
2950 if i == 56 { return 0x748f82ee }
2951 if i == 57 { return 0x78a5636f }
2952 if i == 58 { return 0x84c87814 }
2953 if i == 59 { return 0x8cc70208 }
2954 if i == 60 { return 0x90befffa }
2955 if i == 61 { return 0xa4506ceb }
2956 if i == 62 { return 0xbef9a3f7 }
2957 if i == 63 { return 0xc67178f2 }
2958 return 0
2959}
2960
2961// Access byte n (0..63) of the current block buffer. O(1) -- the buffer is contiguous
2962// (was a linear scan over 8 byte-packed fields per access; n is a public position).
2963func blk_byte(c: *Sha256, n: i64) -> i64 {
2964 let p: *u8 = c.bufptr as *u8
2965 return p[n] as i64
2966}
2967
2968// Set byte n (0..63) of the current block buffer. O(1) contiguous store.
2969func blk_set_byte(c: *Sha256, n: i64, v: i64) -> i64 {
2970 let p: *u8 = c.bufptr as *u8
2971 p[n] = (v & 0xFF) as u8
2972 return 0
2973}
2974
2975// Pack bytes [4*i .. 4*i+4) of the current block into a 32-bit
2976// big-endian word (SHA-256 spec is big-endian).
2977func blk_word(c: *Sha256, i: i64) -> i64 {
2978 let off: i64 = i * 4
2979 let b0: i64 = blk_byte(c, off + 0)
2980 let b1: i64 = blk_byte(c, off + 1)
2981 let b2: i64 = blk_byte(c, off + 2)
2982 let b3: i64 = blk_byte(c, off + 3)
2983 return ((b0 << 24) | (b1 << 16) | (b2 << 8) | b3) & M32
2984}
2985
2986// Hardware SHA-NI block compression: marshal the working state h0..h7 into the 8-word i32
2987// buffer, run one full SHA-256 block via the fused __sha256_ni_block intrinsic (which reads
2988// the 64 raw big-endian bytes at bufptr and the packed i32 K table), marshal the updated
2989// state back. Bit-identical to sha256_compress_sw (validated by nx_shani_block_probe against
2990// the software oracle for many blocks + the NIST KAT). ~hardware speed vs the ~40 MB/s soft path.
2991func sha256_compress_ni(c: *Sha256) -> i64 {
2992 let st: *i32 = c.st8ptr as *i32
2993 st[0] = (c.h0 & M32) as i32; st[1] = (c.h1 & M32) as i32
2994 st[2] = (c.h2 & M32) as i32; st[3] = (c.h3 & M32) as i32
2995 st[4] = (c.h4 & M32) as i32; st[5] = (c.h5 & M32) as i32
2996 st[6] = (c.h6 & M32) as i32; st[7] = (c.h7 & M32) as i32
2997 let _r: i64 = __sha256_ni_block(c.st8ptr as *u8, c.bufptr as *u8, c.k32ptr as *u8)
2998 c.h0 = (st[0] as i64) & M32; c.h1 = (st[1] as i64) & M32
2999 c.h2 = (st[2] as i64) & M32; c.h3 = (st[3] as i64) & M32
3000 c.h4 = (st[4] as i64) & M32; c.h5 = (st[5] as i64) & M32
3001 c.h6 = (st[6] as i64) & M32; c.h7 = (st[7] as i64) & M32
3002 return 0
3003}
3004
3005// MULTI-BLOCK SHA-NI (2026-07-02, organ-level, NO new intrinsic): marshal state -> i32 buffer ONCE,
3006// run __sha256_ni_block over `nblk` consecutive 64-byte blocks read DIRECTLY from `blocks` (state
3007// stays resident in st8ptr between calls), marshal back ONCE. Eliminates the per-block marshal AND
3008// the per-byte blk_set_byte buffering of the byte-at-a-time path -> the SHA-NI GB/s lever. Each
3009// __sha256_ni_block is the identical proven compression -> bit-identical to N separate compresses.
3010func sha256_compress_ni_blocks(c: *Sha256, blocks: i64, nblk: i64) -> i64 {
3011 let st: *i32 = c.st8ptr as *i32
3012 st[0] = (c.h0 & M32) as i32; st[1] = (c.h1 & M32) as i32
3013 st[2] = (c.h2 & M32) as i32; st[3] = (c.h3 & M32) as i32
3014 st[4] = (c.h4 & M32) as i32; st[5] = (c.h5 & M32) as i32
3015 st[6] = (c.h6 & M32) as i32; st[7] = (c.h7 & M32) as i32
3016 var b: i64 = 0
3017 while b < nblk {
3018 let blkp: i64 = blocks + b * 64
3019 let _r: i64 = __sha256_ni_block(c.st8ptr as *u8, blkp as *u8, c.k32ptr as *u8)
3020 b = b + 1
3021 }
3022 c.h0 = (st[0] as i64) & M32; c.h1 = (st[1] as i64) & M32
3023 c.h2 = (st[2] as i64) & M32; c.h3 = (st[3] as i64) & M32
3024 c.h4 = (st[4] as i64) & M32; c.h5 = (st[5] as i64) & M32
3025 c.h6 = (st[6] as i64) & M32; c.h7 = (st[7] as i64) & M32
3026 return 0
3027}
3028
3029// One compression function call: process the 64 bytes currently in the block buffer.
3030// Mutates c.h0..c.h7. Routes to hardware SHA-NI when the CPU supports it (probed once in
3031// sha256_init -> c.ni_ok); the pure-integer software path below stays the ORACLE/fallback.
3032func sha256_compress(c: *Sha256) -> i64 {
3033 if c.ni_ok == 1 { return sha256_compress_ni(c) }
3034 // Message schedule W[0..63] + round constants K[0..63] -- both per-ctx scratch
3035 // (allocated once in sha256_init), so no per-block mmap syscall and no K if-chain.
3036 let w: *i64 = c.wptr as *i64
3037 let k: *i64 = c.kptr as *i64
3038 var i: i64 = 0
3039 while i < 16 {
3040 w[i] = blk_word(c, i)
3041 i = i + 1
3042 }
3043 i = 16
3044 while i < 64 {
3045 let x15: i64 = w[i - 15]
3046 let x2: i64 = w[i - 2]
3047 // sigma0/sigma1 with the rotates inlined (was 4 rotr32 calls/iter -> pure arithmetic)
3048 let s0: i64 = (((x15 >> 7) | (x15 << 25)) ^ ((x15 >> 18) | (x15 << 14)) ^ (x15 >> 3)) & M32
3049 let s1: i64 = (((x2 >> 17) | (x2 << 15)) ^ ((x2 >> 19) | (x2 << 13)) ^ (x2 >> 10)) & M32
3050 w[i] = (w[i - 16] + s0 + w[i - 7] + s1) & M32
3051 i = i + 1
3052 }
3053 var a: i64 = c.h0
3054 var b: i64 = c.h1
3055 var cc: i64 = c.h2
3056 var d: i64 = c.h3
3057 var e: i64 = c.h4
3058 var ff: i64 = c.h5
3059 var g: i64 = c.h6
3060 var h: i64 = c.h7
3061 i = 0
3062 while i < 64 {
3063 // Sigma1(e), Sigma0(a) with rotates inlined (was 6 rotr32 calls/round)
3064 let S1: i64 = (((e >> 6) | (e << 26)) ^ ((e >> 11) | (e << 21)) ^ ((e >> 25) | (e << 7))) & M32
3065 let ch: i64 = ((e & ff) ^ ((e ^ M32) & g)) & M32
3066 let t1: i64 = (h + S1 + ch + k[i] + w[i]) & M32
3067 let S0: i64 = (((a >> 2) | (a << 30)) ^ ((a >> 13) | (a << 19)) ^ ((a >> 22) | (a << 10))) & M32
3068 let mj: i64 = ((a & b) ^ (a & cc) ^ (b & cc)) & M32
3069 let t2: i64 = (S0 + mj) & M32
3070 h = g
3071 g = ff
3072 ff = e
3073 e = (d + t1) & M32
3074 d = cc
3075 cc = b
3076 b = a
3077 a = (t1 + t2) & M32
3078 i = i + 1
3079 }
3080 c.h0 = (c.h0 + a) & M32
3081 c.h1 = (c.h1 + b) & M32
3082 c.h2 = (c.h2 + cc) & M32
3083 c.h3 = (c.h3 + d) & M32
3084 c.h4 = (c.h4 + e) & M32
3085 c.h5 = (c.h5 + ff) & M32
3086 c.h6 = (c.h6 + g) & M32
3087 c.h7 = (c.h7 + h) & M32
3088 return 0
3089}
3090
3091// Initialise state. H[0..7] values from FIPS 180-4 section 5.3.3
3092// (first 32 bits of fractional parts of square roots of first 8
3093// primes).
3094// Shared allocation-free initializer: all five scratch pointers are supplied by the owning path.
3095func sha256_seed_allocated(c: *Sha256) -> i64 {
3096 c.h0 = 0x6a09e667; c.h1 = 0xbb67ae85; c.h2 = 0x3c6ef372; c.h3 = 0xa54ff53a
3097 c.h4 = 0x510e527f; c.h5 = 0x9b05688c; c.h6 = 0x1f83d9ab; c.h7 = 0x5be0cd19
3098 // Per-ctx scratch, allocated once (amortized over every block of this hash):
3099 // Materialize the canonical K table once (sha256_k stays the single source of the
3100 // constants -- DRY; the if-chain now runs 64x per HASH, not 64x per BLOCK).
3101 let kp: *i64 = c.kptr as *i64
3102 var i: i64 = 0
3103 while i < 64 { kp[i] = sha256_k(i); i = i + 1 }
3104 let bp: *u8 = c.bufptr as *u8
3105 i = 0
3106 while i < 64 { bp[i] = 0 as u8; i = i + 1 }
3107 c.idx = 0
3108 c.bit_len = 0
3109
3110 // ---- Hardware SHA-NI setup (additive; software path is the oracle/fallback) ----
3111 // Packed i32 K table for the intrinsic + an 8-word i32 state marshalling buffer.
3112 let k32: *i32 = c.k32ptr as *i32
3113 i = 0
3114 while i < 64 { k32[i] = (sha256_k(i) & M32) as i32; i = i + 1 }
3115 // Probe CPU SHA support ONCE per context: cpuid(leaf=7, subleaf=0):EBX bit-29 = SHA.
3116 // 1<<29 = 0x20000000 = 536870912. Gate the compress path on this; a CPU without SHA-NI
3117 // transparently uses the software compression (byte-identical result, just slower).
3118 if (__cpuid_ebx(7, 0) & K_MAGIC_536870912) != 0 { c.ni_ok = 1 } else { c.ni_ok = 0 }
3119 return 0
3120}
3121
3122func sha256_init(c: *Sha256) -> i64 {
3123 c.bufptr = sys_mmap(64) as i64
3124 c.kptr = sys_mmap(64 * 8) as i64
3125 c.wptr = sys_mmap(64 * 8) as i64
3126 c.k32ptr = sys_mmap(64 * 4) as i64
3127 c.st8ptr = sys_mmap(8 * 4) as i64
3128 return sha256_seed_allocated(c)
3129}
3130
3131// Feed `n` bytes. Buffers partial blocks; compresses full blocks
3132// as soon as they fill.
3133func sha256_update(c: *Sha256, bytes: *u8, n: i64) -> i64 {
3134 var i: i64 = 0
3135 // BULK FAST PATH: when block-aligned (idx==0) and SHA-NI is available, process all full 64-byte
3136 // blocks straight from the input via the resident-state multi-block compress -- skipping both the
3137 // byte-at-a-time blk_set_byte buffering and the per-block state marshalling. Bit-identical.
3138 if c.idx == 0 {
3139 if c.ni_ok == 1 {
3140 let nblk: i64 = n / 64
3141 if nblk > 0 {
3142 sha256_compress_ni_blocks(c, (bytes as i64) + i, nblk)
3143 c.bit_len = c.bit_len + nblk * 512
3144 i = i + nblk * 64
3145 }
3146 }
3147 }
3148 while i < n {
3149 blk_set_byte(c, c.idx, bytes[i])
3150 c.idx = c.idx + 1
3151 c.bit_len = c.bit_len + 8
3152 if c.idx == 64 {
3153 sha256_compress(c)
3154 c.idx = 0
3155 }
3156 i = i + 1
3157 }
3158 return 0
3159}
3160
3161// Finalise: append 0x80, pad with zeros, append 8-byte bit length,
3162// then do one or two final compressions. Writes 32 bytes to `out`.
3163func sha256_final(c: *Sha256, out: *u8) -> i64 {
3164 // Remember total bit length before padding.
3165 let total_bits: i64 = c.bit_len
3166 // Append 0x80.
3167 blk_set_byte(c, c.idx, 0x80)
3168 c.idx = c.idx + 1
3169 // If not enough room for 8-byte length in this block, pad rest
3170 // with zeros + compress.
3171 if c.idx > 56 {
3172 while c.idx < 64 {
3173 blk_set_byte(c, c.idx, 0)
3174 c.idx = c.idx + 1
3175 }
3176 sha256_compress(c)
3177 c.idx = 0
3178 }
3179 // Pad zeros up to byte 56.
3180 while c.idx < 56 {
3181 blk_set_byte(c, c.idx, 0)
3182 c.idx = c.idx + 1
3183 }
3184 // Write 64-bit big-endian length in bytes 56..63.
3185 blk_set_byte(c, 56, (total_bits >> 56) & 0xFF)
3186 blk_set_byte(c, 57, (total_bits >> 48) & 0xFF)
3187 blk_set_byte(c, 58, (total_bits >> 40) & 0xFF)
3188 blk_set_byte(c, 59, (total_bits >> 32) & 0xFF)
3189 blk_set_byte(c, 60, (total_bits >> 24) & 0xFF)
3190 blk_set_byte(c, 61, (total_bits >> 16) & 0xFF)
3191 blk_set_byte(c, 62, (total_bits >> 8) & 0xFF)
3192 blk_set_byte(c, 63, total_bits & 0xFF)
3193 sha256_compress(c)
3194 // Emit H[0..7] as big-endian 4-byte words.
3195 out[0] = (c.h0 >> 24) & 0xFF
3196 out[1] = (c.h0 >> 16) & 0xFF
3197 out[2] = (c.h0 >> 8) & 0xFF
3198 out[3] = c.h0 & 0xFF
3199 out[4] = (c.h1 >> 24) & 0xFF
3200 out[5] = (c.h1 >> 16) & 0xFF
3201 out[6] = (c.h1 >> 8) & 0xFF
3202 out[7] = c.h1 & 0xFF
3203 out[8] = (c.h2 >> 24) & 0xFF
3204 out[9] = (c.h2 >> 16) & 0xFF
3205 out[10] = (c.h2 >> 8) & 0xFF
3206 out[11] = c.h2 & 0xFF
3207 out[12] = (c.h3 >> 24) & 0xFF
3208 out[13] = (c.h3 >> 16) & 0xFF
3209 out[14] = (c.h3 >> 8) & 0xFF
3210 out[15] = c.h3 & 0xFF
3211 out[16] = (c.h4 >> 24) & 0xFF
3212 out[17] = (c.h4 >> 16) & 0xFF
3213 out[18] = (c.h4 >> 8) & 0xFF
3214 out[19] = c.h4 & 0xFF
3215 out[20] = (c.h5 >> 24) & 0xFF
3216 out[21] = (c.h5 >> 16) & 0xFF
3217 out[22] = (c.h5 >> 8) & 0xFF
3218 out[23] = c.h5 & 0xFF
3219 out[24] = (c.h6 >> 24) & 0xFF
3220 out[25] = (c.h6 >> 16) & 0xFF
3221 out[26] = (c.h6 >> 8) & 0xFF
3222 out[27] = c.h6 & 0xFF
3223 out[28] = (c.h7 >> 24) & 0xFF
3224 out[29] = (c.h7 >> 16) & 0xFF
3225 out[30] = (c.h7 >> 8) & 0xFF
3226 out[31] = c.h7 & 0xFF
3227 return 0
3228}
3229
3230// One-shot: hash `n` bytes, write 32-byte digest to `out`.
3231// Release only scratch owned by this initialized context; the caller owns c.
3232// Reset pointers so explicit cleanup is safe to repeat after completion/failure.
3233func sha256_destroy(c: *Sha256) -> i64 {
3234 if c.bufptr!=0 { sys_munmap(c.bufptr as *u8,64);c.bufptr=0 }
3235 if c.kptr!=0 { sys_munmap(c.kptr as *u8,64*8);c.kptr=0 }
3236 if c.wptr!=0 { sys_munmap(c.wptr as *u8,64*8);c.wptr=0 }
3237 if c.k32ptr!=0 { sys_munmap(c.k32ptr as *u8,64*4);c.k32ptr=0 }
3238 if c.st8ptr!=0 { sys_munmap(c.st8ptr as *u8,8*4);c.st8ptr=0 }
3239 return 0
3240}
3241
3242func sha256_digest(bytes: *u8, n: i64, out: *u8) -> i64 {
3243 let ctx_raw: *u8 = sys_mmap(__size_of(Sha256))
3244 let ctx: *Sha256 = ctx_raw as *Sha256
3245 sha256_init(ctx)
3246 sha256_update(ctx, bytes, n)
3247 sha256_final(ctx, out)
3248 sha256_destroy(ctx)
3249 sys_munmap(ctx_raw,__size_of(Sha256))
3250 return 0
3251}
3252
3253// Native Linux x86-64 checked observation path using the existing shared allocator owner.
3254// No cross-backend portability claim: sys_munmap currently uses the native x86-64 release ABI.
3255// Synchronous caller-owned scratch: do not publish it or pass it to forked children.
3256const SHA256_WORD_ALIGN: i64 = 8
3257const SHA256_BLOCK_BYTES: i64 = 64
3258const SHA256_ROUND_WORDS: i64 = 64
3259const SHA256_WIDE_WORD: i64 = 8
3260const SHA256_PACKED_WORD: i64 = 4
3261const SHA256_STATE_WORDS: i64 = 8
3262const SHA256_DIGEST_BYTES: i64 = 32
3263const SHA256_SIGNED_MAX: i64 = 9223372036854775807
3264const SHA256_BITS_PER_BYTE: i64 = 8
3265const SHA256_E_INPUT: i64 = 0-1
3266const SHA256_E_WORKSPACE: i64 = 0-2
3267const SHA256_E_MAPPING: i64 = 0-3
3268const SHA256_E_RELEASE: i64 = 0-4
3269
3270func sha256_context_aligned_bytes() -> i64 {
3271 return ((__size_of(Sha256)+SHA256_WORD_ALIGN-1)/SHA256_WORD_ALIGN)*SHA256_WORD_ALIGN
3272}
3273func sha256_workspace_bytes() -> i64 {
3274 return sha256_context_aligned_bytes()+SHA256_BLOCK_BYTES+2*SHA256_ROUND_WORDS*SHA256_WIDE_WORD+SHA256_ROUND_WORDS*SHA256_PACKED_WORD+SHA256_STATE_WORDS*SHA256_PACKED_WORD
3275}
3276func sha256_checked_input(bytes: *u8, n: i64, out: *u8) -> i64 {
3277 if n < 0 || n > SHA256_SIGNED_MAX/SHA256_BITS_PER_BYTE { return 0 }
3278 let source: i64=bytes as i64; let target: i64=out as i64
3279 if source < 0 || (n > 0 && source == 0) || source > SHA256_SIGNED_MAX-n { return 0 }
3280 if target <= 0 || target > SHA256_SIGNED_MAX-SHA256_DIGEST_BYTES { return 0 }
3281 return 1
3282}
3283func sha256_ranges_overlap(a: i64, an: i64, b: i64, bn: i64) -> i64 {
3284 if an == 0 || bn == 0 { return 0 }; return a < b+bn && b < a+an
3285}
3286// Borrowed scratch. Never call sha256_destroy: the buffers share one allocation.
3287// No allocation/release occurs here. Refused boundary inputs leave output unchanged.
3288// Initialize caller-owned scratch for incremental update/final; never call destroy on it.
3289func sha256_init_workspace(workspace: *u8, capacity: i64) -> i64 {
3290 let base: i64=workspace as i64; let needed: i64=sha256_workspace_bytes()
3291 if base <= 0 || capacity < needed || base > SHA256_SIGNED_MAX-needed || base%SHA256_WORD_ALIGN != 0 { return SHA256_E_WORKSPACE }
3292 let ctx: *Sha256=workspace as *Sha256; var p: i64=base+sha256_context_aligned_bytes()
3293 ctx.bufptr=p; p=p+SHA256_BLOCK_BYTES
3294 ctx.kptr=p; p=p+SHA256_ROUND_WORDS*SHA256_WIDE_WORD
3295 ctx.wptr=p; p=p+SHA256_ROUND_WORDS*SHA256_WIDE_WORD
3296 ctx.k32ptr=p; p=p+SHA256_ROUND_WORDS*SHA256_PACKED_WORD
3297 ctx.st8ptr=p
3298 return sha256_seed_allocated(ctx)
3299}
3300func sha256_digest_workspace(bytes: *u8, n: i64, out: *u8, workspace: *u8, capacity: i64) -> i64 {
3301 if sha256_checked_input(bytes,n,out) != 1 { return SHA256_E_INPUT }
3302 let base: i64=workspace as i64; let needed: i64=sha256_workspace_bytes()
3303 if base <= 0 || capacity < needed || base > SHA256_SIGNED_MAX-needed || base%SHA256_WORD_ALIGN != 0 { return SHA256_E_WORKSPACE }
3304 if sha256_ranges_overlap(base,needed,bytes as i64,n) == 1 || sha256_ranges_overlap(base,needed,out as i64,SHA256_DIGEST_BYTES) == 1 { return SHA256_E_WORKSPACE }
3305 let initialized:i64=sha256_init_workspace(workspace,capacity)
3306 if initialized != 0 { return initialized }
3307 let ctx:*Sha256=workspace as *Sha256
3308 sha256_update(ctx,bytes,n); sha256_final(ctx,out)
3309 return 0
3310}
3311// Takes ownership of an actual whole sys_mmap_shared(workspace_bytes()) result.
3312// A failed mapping leaves output unchanged. A release failure may follow computed output;
3313// callers must accept output only on0. Never supply an arena pointer or undersized mapping.
3314func sha256_digest_mapping_native(bytes: *u8, n: i64, out: *u8, mapping: i64) -> i64 {
3315 if mapping <= 0 { return SHA256_E_MAPPING }
3316 let size: i64=sha256_workspace_bytes()
3317 let result: i64=sha256_digest_workspace(bytes,n,out,mapping as *u8,size)
3318 let released: i64=sys_munmap(mapping as *u8,size)
3319 if result != 0 { return result }
3320 if released != 0 { return SHA256_E_RELEASE }
3321 return 0
3322}
3323func sha256_digest_checked_native(bytes: *u8, n: i64, out: *u8) -> i64 {
3324 if sha256_checked_input(bytes,n,out) != 1 { return SHA256_E_INPUT }
3325 // The existing shared wrapper returns errno; sys_mmap's failure policy is fatal.
3326 let mapping: i64=sys_mmap_shared(sha256_workspace_bytes()) as i64
3327 return sha256_digest_mapping_native(bytes,n,out,mapping)
3328}
3329
3330
3331// Linux syscall ABI results, not admission or retry policy.
3332const FIO_EINTR: i64 = 0 - 4
3333const FIO_EIO: i64 = 0 - 5
3334const FIO_EINVAL: i64 = 0 - 22
3335const FIO_EEXIST: i64 = 0 - 17
3336const FIO_EBADMSG: i64 = 0 - 74 // Linux ABI: artifact digest mismatch.
3337
3338struct NxFileWriteResult {
3339 stage: *u8,
3340 code: i64,
3341 written: i64,
3342 close_code: i64
3343}
3344
3345// Owns fd until close. Preserve the first failure and the independent close
3346// result; never retry close because Linux may already have released the fd.
3347func fio_write_sync_fd(fd: i64, body: *u8, n: i64, result: *NxFileWriteResult) -> i64 {
3348 result.stage = "write" as *u8
3349 result.code = 0
3350 result.written = 0
3351 result.close_code = 0
3352 if n < 0 || ((body as i64) == 0 && n > 0) {
3353 result.stage = "input" as *u8
3354 result.code = FIO_EINVAL
3355 }
3356 while result.code == 0 && result.written < n {
3357 let w: i64 = sys_write(fd, body + result.written, n - result.written)
3358 if w == FIO_EINTR { continue }
3359 if w < 0 { result.code = w; break }
3360 if w == 0 { result.code = FIO_EIO; break }
3361 result.written = result.written + w
3362 }
3363 if result.code == 0 {
3364 result.stage = "fsync" as *u8
3365 var synced: i64 = sys_fsync(fd)
3366 while synced == FIO_EINTR { synced = sys_fsync(fd) }
3367 result.code = synced
3368 }
3369 result.close_code = sys_close(fd)
3370 if result.code == 0 {
3371 result.stage = "close" as *u8
3372 result.code = result.close_code
3373 }
3374 if result.code == 0 { result.stage = "complete" as *u8 }
3375 return result.code
3376}
3377
3378// Persist the directory entry after rename. A failure here occurs after the
3379// visible update: the caller must retain that publication state in its receipt.
3380func fio_sync_parent(path: *u8, result: *NxFileWriteResult) -> i64 {
3381 var length: i64=0
3382 var slash: i64=0-1
3383 while path[length]!=(0 as u8) { if path[length]==(47 as u8) { slash=length }; length=length+1 }
3384 let parent: *u8=sys_mmap(length+2)
3385 if slash<0 { parent[0]=46 as u8; parent[1]=0 as u8 }
3386 else {
3387 var end: i64=slash
3388 if end==0 { end=1 }
3389 var i: i64=0
3390 while i<end { parent[i]=path[i]; i=i+1 }
3391 parent[end]=0 as u8
3392 }
3393 result.stage="directory-open" as *u8
3394 result.close_code=0
3395 let fd: i64=sys_openat_directory(parent)
3396 sys_munmap(parent,length+2)
3397 if fd<0 { result.code=fd; return fd }
3398 result.stage="directory-fsync" as *u8
3399 var synced: i64=sys_fsync(fd)
3400 while synced==FIO_EINTR { synced=sys_fsync(fd) }
3401 result.close_code=sys_close(fd)
3402 result.code=synced
3403 if synced==0 { result.stage="directory-close" as *u8; result.code=result.close_code }
3404 if result.code==0 { result.stage="complete" as *u8 }
3405 return result.code
3406}
3407
3408// delete a file (unlinkat). Returns 0 on success.
3409func fio_unlink(path: *u8) -> i64 { return __syscall(263, 0 - 100, path as i64, 0, 0, 0, 0) }
3410
3411// 1 if `path` exists (fstatat succeeds), else 0.
3412func fio_exists(path: *u8) -> i64 {
3413 let st: *u8 = sys_mmap(160)
3414 if sys_fstatat(path, st) == 0 { return 1 }
3415 return 0
3416}
3417
3418// A caller-owned, single-use read session. Initialize once before open; never
3419// reinitialize an open session. Atomic pathname replacement does not change its fd.
3420struct NxFileReadRegion {
3421 fd: i64,
3422 total: i64,
3423 start: i64,
3424 length: i64,
3425 read_bytes: i64,
3426 last_read: i64,
3427 stage: *u8,
3428 code: i64,
3429 close_code: i64,
3430}
3431func fio_region_init(r: *NxFileReadRegion) -> i64 {
3432 r.fd=0-1;r.total=0;r.start=0;r.length=0;r.read_bytes=0;r.last_read=0
3433 r.stage="initialized";r.code=0;r.close_code=0
3434 return 0
3435}
3436// Linux close consumes ownership even when it reports an error; do not retry it.
3437func fio_region_close(r: *NxFileReadRegion) -> i64 {
3438 if r.fd>=0 {
3439 let fd: i64=r.fd;r.fd=0-1
3440 r.close_code=sys_close(fd)
3441 if r.code==0 && r.close_code<0 { r.code=r.close_code;r.stage="close" }
3442 }
3443 return r.code
3444}
3445func fio_region_fail(r: *NxFileReadRegion,stage: *u8,code: i64) -> i64 {
3446 r.stage=stage;r.code=code
3447 fio_region_close(r)
3448 return code
3449}
3450func fio_region_open(path: *u8,r: *NxFileReadRegion) -> i64 {
3451 if r.fd>=0 { return FIO_EEXIST }
3452 fio_region_init(r)
3453 if (path as i64)==0 { return fio_region_fail(r,"path",FIO_EINVAL) }
3454 if path[0]==(0 as u8) { return fio_region_fail(r,"path",FIO_EINVAL) }
3455 r.stage="open";r.fd=sys_openat_rd(path)
3456 if r.fd<0 { r.code=r.fd;return r.code }
3457 // SEEK_END/SEEK_SET are platform ABI selectors, not transfer-size policy.
3458 let size: i64=sys_lseek(r.fd,0,2)
3459 if size<0 { return fio_region_fail(r,"size-seek",size) }
3460 r.total=size;r.length=size
3461 let back: i64=sys_lseek(r.fd,0,0)
3462 if back!=0 { if back<0 { return fio_region_fail(r,"initial-seek",back) };return fio_region_fail(r,"initial-seek",FIO_EIO) }
3463 r.stage="ready";return 0
3464}
3465// Bounds use subtraction, so start+length can never wrap before validation.
3466func fio_region_select(r: *NxFileReadRegion,start: i64,length: i64) -> i64 {
3467 if r.fd<0 || r.code!=0 || r.read_bytes!=0 { return FIO_EINVAL }
3468 if start<0 || length<0 || start>r.total { return FIO_EINVAL }
3469 if length>r.total-start { return FIO_EINVAL }
3470 let at: i64=sys_lseek(r.fd,start,0)
3471 if at!=start { if at<0 { return fio_region_fail(r,"region-seek",at) };return fio_region_fail(r,"region-seek",FIO_EIO) }
3472 r.start=start;r.length=length;r.stage="ready";return 0
3473}
3474// The caller supplies its reusable transport buffer. No allocation depends on
3475// file size; each read is at most min(buffer capacity, remaining region bytes).
3476func fio_region_next(r: *NxFileReadRegion,out: *u8,cap: i64) -> i64 {
3477 r.last_read=0
3478 if r.code!=0 { return r.code }
3479 if r.fd<0 { if r.read_bytes==r.length { return 0 };return FIO_EINVAL }
3480 if cap<=0 || (out as i64)==0 { return FIO_EINVAL }
3481 let remaining: i64=r.length-r.read_bytes
3482 if remaining==0 { r.stage="complete";return fio_region_close(r) }
3483 var want: i64=remaining;if want>cap { want=cap }
3484 r.stage="read"
3485 while r.last_read<want {
3486 let got: i64=sys_read(r.fd,out+r.last_read,want-r.last_read)
3487 if got==FIO_EINTR { continue }
3488 if got<0 { return fio_region_fail(r,"read",got) }
3489 if got==0 { return fio_region_fail(r,"read-premature-eof",FIO_EIO) }
3490 r.last_read=r.last_read+got;r.read_bytes=r.read_bytes+got
3491 }
3492 if r.read_bytes==r.length {
3493 r.stage="complete"
3494 if fio_region_close(r)<0 { return r.code }
3495 } else { r.stage="ready" }
3496 return r.last_read
3497}
3498
3499
3500// Preparation never replaces a pathname. The caller owns an exclusive candidate
3501// path and keeps it for diagnosis on failure; publication is a separate operation.
3502struct NxFilePrepareResult {
3503 stage: *u8,
3504 code: i64,
3505 copied: i64,
3506 created: i64,
3507 source_close: i64,
3508 destination_close: i64,
3509 durable: i64,
3510}
3511func fio_prepare_copy(source: *u8,candidate: *u8,mode: i64,buffer: *u8,capacity: i64,out: *NxFilePrepareResult) -> i64 {
3512 out.stage="input";out.code=FIO_EINVAL;out.copied=0;out.created=0
3513 out.source_close=0;out.destination_close=0;out.durable=0
3514 if (source as i64)==0 || (candidate as i64)==0 || (buffer as i64)==0 || capacity<=0 { return out.code }
3515 if source[0]==(0 as u8) || candidate[0]==(0 as u8) || mode<0 || mode>0x1ff { return out.code }
3516 let input: *NxFileReadRegion=sys_mmap(__size_of(NxFileReadRegion)) as *NxFileReadRegion
3517 fio_region_init(input)
3518 out.code=fio_region_open(source,input);out.stage="source-open"
3519 var fd: i64=0-1
3520 if out.code==0 {
3521 out.stage="candidate-create"
3522 fd=sys_openat_exclusive(candidate,mode)
3523 if fd<0 { out.code=fd } else { out.created=1 }
3524 }
3525 while out.code==0 && input.read_bytes<input.length {
3526 let n: i64=fio_region_next(input,buffer,capacity)
3527 if n<0 { out.stage="source-read";out.code=n;break }
3528 var sent: i64=0
3529 out.stage="candidate-write"
3530 while sent<n {
3531 let w: i64=sys_write(fd,buffer+sent,n-sent)
3532 if w==FIO_EINTR { continue }
3533 if w<0 { out.code=w;break }
3534 if w==0 { out.code=FIO_EIO;break }
3535 sent=sent+w;out.copied=out.copied+w
3536 }
3537 }
3538 fio_region_close(input);out.source_close=input.close_code
3539 if out.code==0 && input.code!=0 { out.code=input.code;out.stage="source-close" }
3540 sys_munmap(input as *u8,__size_of(NxFileReadRegion))
3541 if out.code==0 {
3542 out.stage="candidate-mode"
3543 out.code=nx_chmod(candidate,mode)
3544 }
3545 if out.code==0 {
3546 out.stage="candidate-fsync";out.code=sys_fsync(fd)
3547 while out.code==FIO_EINTR { out.code=sys_fsync(fd) }
3548 }
3549 if fd>=0 {
3550 out.destination_close=sys_close(fd)
3551 if out.code==0 && out.destination_close!=0 { out.code=out.destination_close;out.stage="candidate-close" }
3552 }
3553 if out.code==0 {
3554 let sync: *NxFileWriteResult=sys_mmap(__size_of(NxFileWriteResult)) as *NxFileWriteResult
3555 out.code=fio_sync_parent(candidate,sync)
3556 if out.code!=0 { out.stage=sync.stage }
3557 sys_munmap(sync as *u8,__size_of(NxFileWriteResult))
3558 }
3559 if out.code==0 { out.stage="prepared";out.durable=1 }
3560 return out.code
3561}
3562
3563
3564struct NxFilePublishResult {
3565 stage: *u8,
3566 code: i64,
3567 visible: i64,
3568 durable: i64,
3569}
3570// Caller owns the prepared candidate and target's mutation lock. Rename failure
3571// leaves live intact; sync failure AFTER rename must retain visible=1.
3572func fio_publish_candidate(candidate: *u8,live: *u8,out: *NxFilePublishResult) -> i64 {
3573 out.stage="publish-input";out.code=FIO_EINVAL;out.visible=0;out.durable=0
3574 if (candidate as i64)==0 || (live as i64)==0 { return out.code }
3575 if candidate[0]==(0 as u8) || live[0]==(0 as u8) { return out.code }
3576 out.stage="publish-rename";out.code=sys_renameat(candidate,live)
3577 if out.code!=0 { return out.code }
3578 out.visible=1
3579 let sync: *NxFileWriteResult=sys_mmap(__size_of(NxFileWriteResult)) as *NxFileWriteResult
3580 out.stage="live-directory-sync";out.code=fio_sync_parent(live,sync)
3581 // Both directory entries change if preparation used another directory.
3582 if out.code==0 { out.stage="candidate-directory-sync";out.code=fio_sync_parent(candidate,sync) }
3583 sys_munmap(sync as *u8,__size_of(NxFileWriteResult))
3584 if out.code==0 { out.stage="published";out.durable=1 }
3585 return out.code
3586}
3587
3588
3589// Stable lock inode: never unlink the lockfile. All cooperating callers must use
3590// the same canonical live pathname in an estate-owned directory. This excludes
3591// arbitrary writers and pathname aliases from the guarantee.
3592struct NxFileTargetLock {
3593 fd: i64,
3594 stage: *u8,
3595 code: i64,
3596 unlock_code: i64,
3597 close_code: i64,
3598}
3599func fio_target_lock_init(lock: *NxFileTargetLock) -> i64 {
3600 lock.fd=0-1;lock.stage="not-started";lock.code=0;lock.unlock_code=0;lock.close_code=0
3601 return 0
3602}
3603func fio_target_lock_release(lock: *NxFileTargetLock) -> i64 {
3604 if lock.fd>=0 {
3605 let fd: i64=lock.fd;lock.fd=0-1
3606 lock.unlock_code=sys_flock(fd,SYS_LOCK_UN)
3607 lock.close_code=sys_close(fd)
3608 if lock.code==0 && lock.unlock_code!=0 { lock.code=lock.unlock_code;lock.stage="target-unlock" }
3609 if lock.code==0 && lock.close_code!=0 { lock.code=lock.close_code;lock.stage="target-lock-close" }
3610 if lock.code==0 { lock.stage="released" }
3611 }
3612 return lock.code
3613}
3614func fio_target_lock_acquire(live: *u8,lock: *NxFileTargetLock) -> i64 {
3615 if lock.fd>=0 { return FIO_EEXIST }
3616 fio_target_lock_init(lock)
3617 lock.stage="target-lock-input";lock.code=FIO_EINVAL
3618 if (live as i64)==0 { return lock.code }
3619 var n: i64=0;while live[n]!=(0 as u8) { n=n+1 }
3620 if n==0 { return lock.code }
3621 let suffix: *u8=".install.lock"
3622 var extra: i64=0;while suffix[extra]!=(0 as u8) { extra=extra+1 }
3623 let bytes: i64=n+extra+1
3624 if bytes<=n { return lock.code }
3625 let path: *u8=sys_mmap(bytes)
3626 if (path as i64)<0 { lock.stage="target-lock-allocation";lock.code=path as i64;return lock.code }
3627 var i: i64=0;while i<n { path[i]=live[i];i=i+1 }
3628 i=0;while i<extra { path[n+i]=suffix[i];i=i+1 };path[n+extra]=0 as u8
3629 lock.stage="target-lock-open";lock.fd=sys_openat_lock(path)
3630 sys_munmap(path,bytes)
3631 if lock.fd<0 { lock.code=lock.fd;return lock.code }
3632 lock.stage="target-lock-acquire";lock.code=sys_flock(lock.fd,SYS_LOCK_EX | SYS_LOCK_NB)
3633 if lock.code!=0 {
3634 let fd: i64=lock.fd;lock.fd=0-1;lock.close_code=sys_close(fd)
3635 return lock.code
3636 }
3637 lock.stage="held";return 0
3638}
3639struct NxFileReplaceResult {
3640 stage: *u8,
3641 code: i64,
3642 candidate: NxFilePrepareResult,
3643 backup: NxFilePrepareResult,
3644 publication: NxFilePublishResult,
3645 lock: NxFileTargetLock,
3646}
3647// Internal locked body. Source remains an immutable artifact; history paths
3648// are exclusive. The public replacement entry points acquire the target lock.
3649func fio_replace_owned(source: *u8,live: *u8,candidate: *u8,backup: *u8,mode: i64,buffer: *u8,capacity: i64,expected_candidate: *u8,expected_live: *u8,out: *NxFileReplaceResult) -> i64 {
3650 out.stage="prepare-candidate"
3651 out.backup.created=0;out.backup.durable=0;out.backup.copied=0;out.backup.code=0
3652 out.backup.stage="not-started";out.backup.source_close=0;out.backup.destination_close=0
3653 out.publication.stage="not-started";out.publication.code=0;out.publication.visible=0;out.publication.durable=0
3654 out.code=fio_prepare_copy(source,candidate,mode,buffer,capacity,&out.candidate)
3655 if out.code!=0 { return out.code }
3656 if (expected_candidate as i64)!=0 {
3657 out.stage="candidate-identity"
3658 out.code=fio_verify_sha256(candidate,expected_candidate,buffer,capacity)
3659 if out.code!=0 { return out.code }
3660 }
3661 out.stage="prepare-backup"
3662 out.code=fio_prepare_copy(live,backup,mode,buffer,capacity,&out.backup)
3663 if out.code!=0 { return out.code }
3664 if (expected_live as i64)!=0 {
3665 out.stage="live-identity"
3666 out.code=fio_verify_sha256(backup,expected_live,buffer,capacity)
3667 if out.code!=0 { return out.code }
3668 }
3669 out.stage="publish"
3670 out.code=fio_publish_candidate(candidate,live,&out.publication)
3671 if out.code==0 { out.stage="complete" }
3672 return out.code
3673}
3674
3675func fio_replace_init(out: *NxFileReplaceResult) -> i64 {
3676 let raw: *u8=out as *u8;var i: i64=0
3677 while i<__size_of(NxFileReplaceResult) { raw[i]=0 as u8;i=i+1 }
3678 out.stage="not-started";out.candidate.stage="not-started"
3679 out.backup.stage="not-started";out.publication.stage="not-started"
3680 fio_target_lock_init(&out.lock);return 0
3681}
3682func fio_replace_core(source: *u8,live: *u8,candidate: *u8,backup: *u8,mode: i64,buffer: *u8,capacity: i64,expected_candidate: *u8,expected_live: *u8,out: *NxFileReplaceResult) -> i64 {
3683 fio_replace_init(out)
3684 out.code=fio_target_lock_acquire(live,&out.lock)
3685 if out.code!=0 { out.stage=out.lock.stage;return out.code }
3686 fio_replace_owned(source,live,candidate,backup,mode,buffer,capacity,expected_candidate,expected_live,out)
3687 let released: i64=fio_target_lock_release(&out.lock)
3688 if out.code==0 && released!=0 { out.code=released;out.stage=out.lock.stage }
3689 return out.code
3690}
3691func fio_replace_with_backup(source: *u8,live: *u8,candidate: *u8,backup: *u8,mode: i64,buffer: *u8,capacity: i64,out: *NxFileReplaceResult) -> i64 {
3692 return fio_replace_core(source,live,candidate,backup,mode,buffer,capacity,0 as *u8,0 as *u8,out)
3693}
3694
3695func fio_replace_verified(source: *u8,live: *u8,candidate: *u8,backup: *u8,mode: i64,buffer: *u8,capacity: i64,expected_candidate: *u8,expected_live: *u8,out: *NxFileReplaceResult) -> i64 {
3696 if (expected_candidate as i64)==0 || (expected_live as i64)==0 {
3697 fio_replace_init(out)
3698 out.stage="identity-input";out.code=FIO_EINVAL
3699 out.candidate.stage="not-started";out.backup.stage="not-started";out.publication.stage="not-started"
3700 return out.code
3701 }
3702 return fio_replace_core(source,live,candidate,backup,mode,buffer,capacity,expected_candidate,expected_live,out)
3703}
3704
3705
3706// Digest comparison is over the prepared bytes, before any live replacement.
3707// Expected points to a SHA-256 digest (32 bytes), not a filename or size.
3708func fio_verify_sha256(path: *u8,expected: *u8,buffer: *u8,capacity: i64) -> i64 {
3709 if (expected as i64)==0 || (buffer as i64)==0 || capacity<=0 { return FIO_EINVAL }
3710 let input: *NxFileReadRegion=sys_mmap(__size_of(NxFileReadRegion)) as *NxFileReadRegion
3711 fio_region_init(input)
3712 var rc: i64=fio_region_open(path,input)
3713 let ctx: *Sha256=sys_mmap(__size_of(Sha256)) as *Sha256
3714 sha256_init(ctx)
3715 while rc==0 && input.read_bytes<input.length {
3716 let n: i64=fio_region_next(input,buffer,capacity)
3717 if n<0 { rc=n;break }
3718 sha256_update(ctx,buffer,n)
3719 }
3720 fio_region_close(input)
3721 if rc==0 { rc=input.code }
3722 if rc==0 {
3723 let actual: *u8=sys_mmap(32)
3724 sha256_final(ctx,actual)
3725 var i: i64=0;var differs: i64=0
3726 while i<32 { differs=differs | ((actual[i] as i64) ^ (expected[i] as i64));i=i+1 }
3727 if differs!=0 { rc=FIO_EBADMSG }
3728 sys_munmap(actual,32)
3729 }
3730 sha256_destroy(ctx);sys_munmap(ctx as *u8,__size_of(Sha256))
3731 sys_munmap(input as *u8,__size_of(NxFileReadRegion))
3732 return rc
3733}
3734
3735// nx_itoa_lib.nx -- THE shared integer->decimal emitter. ONE copy, so the corpus stops retyping it.
3736//
3737// LIFTED, NEVER COPIED (2026-07-31, debt 1785557603). ccz_cat_num was already correct, already
3738// MSB-first, already zero-allocation, and already had 10+ callers -- it was simply IMPRISONED inside
3739// nx_crashresume_census_core.nx, a crash-resume census organ. Seven files imported an entire census
3740// just to print an integer. That import cost, NOT ignorance of the primitive, is why ~87 sites
3741// hand-rolled their own. LAW: WHEN A CORRECT PRIMITIVE IS RETYPED, MEASURE ITS IMPORT COST BEFORE
3742// BLAMING DISCOVERABILITY -- people do not retype what is CHEAP to reach.
3743//
3744// THE LEAK WAS NEVER IN THE PRIMITIVE, IT WAS IN THE MISSING WRAPPER. ccz_cat_num allocates nothing.
3745// What every clone hand-rolled was the fd shim around it, e.g. nx_lock_reap_gate.g_putn:
3746// let b: *u8 = sys_mmap(32); let e: i64 = ccz_cat_num(b, 0, v); sys_write(1, b, e); return 0
3747// -- one mmap per call, never freed. nxi_fd below is that shim, written ONCE and always freeing.
3748//
3749// The census now imports THIS file; NishiLang import is transitive (verified: nx_lock_reap_gate
3750// imports only nx_syscalls + nx_lock_reap_core, and resolves ccz_cat_num through the core), so all
3751// existing callers keep resolving with no edit.
3752//
3753// LAYERING: lives in runtime/ so BOTH runtime/ and _hdl_build/ can import it.
3754// license_tier: ORIGINAL No hw writes (Rule 26).
3755
3756// MSB-FIRST (2026-07-31, debt 1785516350): the previous body built digits LEAST-significant first,
3757// which comes out BACKWARDS and therefore needed a sys_mmap(32) scratch buffer to reverse through --
3758// and never freed it, leaking a page per call across 12+ importers. Emitting MOST-significant first
3759// needs no buffer at all, so this now ALLOCATES NOTHING. Output bytes and the NUL-terminate contract
3760// are unchanged; this is a rewrite of the algorithm, not a sprinkled munmap (rule 3).
3761const CCZ_ASCII_0: i64 = 48
3762const CCZ_MINUS: i64 = 45
3763const CCZ_DEC: i64 = 10
3764func ccz_cat_num(buf: *u8, off: i64, v: i64) -> i64 {
3765 var o: i64 = off
3766 var m: i64 = v
3767 if m == 0 { buf[o] = CCZ_ASCII_0 as u8; o = o + 1; buf[o] = 0 as u8; return o }
3768 if m < 0 { buf[o] = CCZ_MINUS as u8; o = o + 1; m = 0 - m }
3769 // i64 MIN negates to itself and stays negative; clamp rather than loop forever on the digit walk.
3770 if m < 0 { m = 0 }
3771 var pw: i64 = 1
3772 while m / pw >= CCZ_DEC { pw = pw * CCZ_DEC }
3773 while pw > 0 {
3774 buf[o] = (CCZ_ASCII_0 + ((m / pw) % CCZ_DEC)) as u8
3775 o = o + 1
3776 pw = pw / CCZ_DEC
3777 }
3778 buf[o] = 0 as u8
3779 return o
3780}
3781
3782// max i64 is 19 digits + sign + the NUL ccz_cat_num writes; 24 leaves slack, well under one page.
3783const NXI_BUF: i64 = 24
3784const NXI_STDOUT: i64 = 1
3785const NXI_STDERR: i64 = 2
3786
3787// Write v as decimal to fd. ONE buffer, ALWAYS freed -- the balanced shape nx_mmapbal certifies.
3788// This is the drop-in for every hand-rolled putn/gn/wn/pn clone. Returns bytes written.
3789func nxi_fd(fd: i64, v: i64) -> i64 {
3790 let b: *u8 = sys_mmap(NXI_BUF)
3791 let n: i64 = ccz_cat_num(b, 0, v)
3792 sys_write(fd, b, n)
3793 sys_munmap(b, NXI_BUF)
3794 return n
3795}
3796
3797func nxi_out(v: i64) -> i64 { return nxi_fd(NXI_STDOUT, v) }
3798func nxi_err(v: i64) -> i64 { return nxi_fd(NXI_STDERR, v) }
3799
3800// NUL-FREE buffer form (2026-07-31). ccz_cat_num NUL-terminates -- it writes dst[ret]=0 -- which is
3801// right for its own callers but WRONG as a drop-in for the large clone family whose contract is
3802// "append digits, touch nothing else, return the new offset". Pointing those at ccz_cat_num would
3803// write one byte past the returned offset, and a clone that patches a number into the MIDDLE of an
3804// already-built buffer would have the next byte clobbered. nx_office_serve.of_catn alone has 60
3805// call sites, none of them audited for that.
3806// So the lib carries BOTH contracts explicitly rather than making every migrator guess:
3807// ccz_cat_num -> digits + NUL, returns the offset BEFORE the NUL
3808// nxi_buf -> digits only, returns the offset AFTER them, ZERO bytes touched beyond
3809// Both are MSB-first and allocate NOTHING. Constants are the CCZ_ ones lifted with ccz_cat_num.
3810func nxi_buf(dst: *u8, off: i64, v: i64) -> i64 {
3811 var p: i64 = off
3812 var m: i64 = v
3813 if m < 0 {
3814 dst[p] = CCZ_MINUS as u8
3815 p = p + 1
3816 m = 0 - m
3817 }
3818 // i64 MIN negates to ITSELF and stays negative. Clamp to 0 rather than looping forever or
3819 // emitting garbage -- a documented bound, never a silent wrong number.
3820 if m < 0 { m = 0 }
3821 var pw: i64 = 1
3822 while m / pw >= CCZ_DEC { pw = pw * CCZ_DEC }
3823 while pw > 0 {
3824 dst[p] = (CCZ_ASCII_0 + ((m / pw) % CCZ_DEC)) as u8
3825 p = p + 1
3826 pw = pw / CCZ_DEC
3827 }
3828 return p
3829}
3830
3831// nx_vsz_watchdog_core.nx -- importable CORE of the VSZ watchdog (the permanent fix for outage MODE 2:
3832// mmap-per-request daemons never munmap -> VSZ balloons (mgmt hit ~160GB) -> fork() fails -> child-exec
3833// SILENTLY EMPTY while /api/health stays 200; see reference-mgmt-api-outage-tmp-log-rootcause-2026-07-12).
3834// The watchdog DECIDES DEATH ONLY: it kills a conf-listed daemon whose VSZ crossed its threshold; RESPAWN
3835// stays 100% the nx_hostctl guard's job (single responsibility, no dueling supervisors). FAIL-SAFE BY
3836// CONSTRUCTION: no conf file -> INERT; unreadable /proc -> skip; cooldown suppresses kill-storms; pid<=300
3837// and self are never killed. Pure decision funcs here (gate-locked); the /proc walk + kill live in the CLI.
3838// license_tier: ORIGINAL
3839
3840
3841const VW_PROC_PATH_CAP: i64 = 256 // /proc/<pid>/status path buffer
3842const VW_STATUS_BUF: i64 = 8192 // /proc status read buffer
3843const VW_PTR_CELL: i64 = 16 // 2-i64 scratch cell (vw_num_at end-pointer out-param)
3844
3845func vw_slen(s: *u8) -> i64 { var n: i64 = 0; while s[n] != (0 as u8) { n = n + 1 } return n }
3846
3847// substring containment (hostctl's hc_contains idiom; needle has no NUL so cmdline NUL separators are safe).
3848func vw_contains(hay: *u8, hn: i64, needle: *u8, nn: i64) -> i64 {
3849 if nn == 0 { return 0 }
3850 var i: i64 = 0
3851 while i + nn <= hn {
3852 var k: i64 = 0
3853 var ok: i64 = 1
3854 while k < nn { if hay[i+k] != needle[k] { ok = 0; k = nn } k = k + 1 }
3855 if ok == 1 { return 1 }
3856 i = i + 1
3857 }
3858 return 0
3859}
3860
3861// parse leading unsigned decimal from s[off..n): value, or -1 if no digit at off. end offset in endp[0].
3862func vw_num_at(s: *u8, n: i64, off: i64, endp: *i64) -> i64 {
3863 var v: i64 = 0
3864 var any: i64 = 0
3865 var i: i64 = off
3866 var go: i64 = 1
3867 while go == 1 {
3868 go = 0
3869 if i < n { let c: i64 = s[i] as i64; if c >= 48 { if c <= 57 { v = v*10 + (c-48); any = 1; i = i + 1; go = 1 } } }
3870 }
3871 endp[0] = i
3872 if any == 0 { return 0 - 1 }
3873 return v
3874}
3875
3876// parse one conf line buf[ls..le): "<needle> <max_gb>". Writes NUL after the needle IN PLACE, returns gb
3877// (>=1) with needle start in outp[0], or -1 for comment/blank/malformed (row dropped, fail-safe).
3878func vw_parse_row(buf: *u8, ls: i64, le: i64, outp: *i64) -> i64 {
3879 var i: i64 = ls
3880 var go: i64 = 1
3881 while go == 1 { go = 0; if i < le { let c: i64 = buf[i] as i64; if c == 32 { i = i + 1; go = 1 } else { if c == 9 { i = i + 1; go = 1 } } } }
3882 if i >= le { return 0 - 1 }
3883 if buf[i] == (35 as u8) { return 0 - 1 } // '#' comment
3884 let nstart: i64 = i
3885 go = 1
3886 while go == 1 { go = 0; if i < le { let c: i64 = buf[i] as i64; if c != 32 { if c != 9 { i = i + 1; go = 1 } } } }
3887 if i >= le { return 0 - 1 } // no separator -> malformed
3888 let nend: i64 = i
3889 let ep: *i64 = sys_mmap(VW_PTR_CELL) as *i64
3890 var j: i64 = i
3891 go = 1
3892 while go == 1 { go = 0; if j < le { let c: i64 = buf[j] as i64; if c == 32 { j = j + 1; go = 1 } else { if c == 9 { j = j + 1; go = 1 } } } }
3893 let gb: i64 = vw_num_at(buf, le, j, ep)
3894 sys_munmap(ep as *u8, VW_PTR_CELL) // leak-free: ep (the end-ptr out-param) was leaked per row (the ep-out-param class my leak-checker flagged)
3895 if gb < 1 { return 0 - 1 } // gb<1 -> inert row (never a 0-threshold kill-everything)
3896 buf[nend] = 0 as u8 // NUL-terminate the needle in place
3897 outp[0] = nstart
3898 return gb
3899}
3900
3901// parse the kB value of an arbitrary "<Label>:" row out of a /proc status text. -1 absent/unreadable.
3902// Generalized so VmSize (address space) and VmRSS (resident -- the heap-leak meter VSZ can hide) share ONE
3903// parser (DRY; NEVER kill on parse failure).
3904func vw_status_kb(buf: *u8, n: i64, pat: *u8) -> i64 {
3905 let pl: i64 = vw_slen(pat)
3906 var i: i64 = 0
3907 while i + pl <= n {
3908 var k: i64 = 0
3909 var ok: i64 = 1
3910 while k < pl { if buf[i+k] != pat[k] { ok = 0; k = pl } k = k + 1 }
3911 if ok == 1 {
3912 var j: i64 = i + pl
3913 var go: i64 = 1
3914 while go == 1 { go = 0; if j < n { let c: i64 = buf[j] as i64; if c == 32 { j = j + 1; go = 1 } else { if c == 9 { j = j + 1; go = 1 } } } }
3915 let ep: *i64 = sys_mmap(VW_PTR_CELL) as *i64
3916 let r: i64 = vw_num_at(buf, n, j, ep)
3917 sys_munmap(ep as *u8, VW_PTR_CELL) // leak-free: ep was mmap'd-and-leaked per call (the ep-out-param leak class)
3918 return r
3919 }
3920 i = i + 1
3921 }
3922 return 0 - 1
3923}
3924
3925// THE kill decision. 1 only when: threshold sane (gb>=1) AND vsz known (kb>0) AND over threshold AND the
3926// per-row cooldown expired. Everything else -> 0 (fail-safe).
3927func vw_should_kill(vsz_kb: i64, max_gb: i64, last_kill_s: i64, now_s: i64, cooldown_s: i64) -> i64 {
3928 if max_gb < 1 { return 0 }
3929 if vsz_kb <= 0 { return 0 }
3930 if vsz_kb <= max_gb * 1048576 { return 0 }
3931 if now_s - last_kill_s < cooldown_s { return 0 }
3932 return 1
3933}
3934
3935// bounded whole-file read. -1 absent.
3936func vw_read(path: *u8, buf: *u8, cap: i64) -> i64 {
3937 let fd: i64 = sys_openat_rd(path)
3938 if fd < 0 { return 0 - 1 }
3939 var tot: i64 = 0
3940 var n: i64 = sys_read(fd, buf, cap)
3941 while n > 0 { tot = tot + n; if tot >= cap { n = 0 } else { n = sys_read(fd, (buf as i64 + tot) as *u8, cap - tot) } }
3942 sys_close(fd)
3943 return tot
3944}
3945
3946// monotonic seconds (persists across one-shot runs within a boot -- exactly the cooldown scope we want).
3947func vw_now_s() -> i64 { let ts: *i64 = sys_mmap(16) as *i64; sys_clock_gettime_mono(ts); return ts[0] }
3948
3949// self pid via /proc/self/stat leading digits (no getpid syscall-number risk).
3950func vw_selfpid() -> i64 {
3951 let b: *u8 = sys_mmap(VW_PROC_PATH_CAP)
3952 let n: i64 = vw_read("/proc/self/stat" as *u8, b, VW_PROC_PATH_CAP - 1)
3953 if n <= 0 { sys_munmap(b, VW_PROC_PATH_CAP); return 0 - 1 }
3954 let ep: *i64 = sys_mmap(VW_PTR_CELL) as *i64
3955 let r: i64 = vw_num_at(b, n, 0, ep)
3956 sys_munmap(b, VW_PROC_PATH_CAP); sys_munmap(ep, VW_PTR_CELL) // leak-free (b + ep were leaked per call)
3957 return r
3958}
3959
3960// back-compat: the VmSize row (a sibling gate + vw_status_kb_of call this by name)
3961func vw_vmsize_parse(buf: *u8, n: i64) -> i64 { return vw_status_kb(buf, n, "VmSize:" as *u8) }
3962// kB of an arbitrary "<label>:" status row for a /proc entry named by DIRECTORY STRING (pid or "self").
3963// -1 unreadable. LEAK-FREE (munmaps path+b on every return). Generalized so VmSize (address space) and
3964// VmRSS (resident heap -- the leak class an arena hides from VSZ) share ONE reader.
3965func vw_status_kb_of(dirname: *u8, label: *u8) -> i64 {
3966 let path: *u8 = sys_mmap(VW_PROC_PATH_CAP)
3967 var o: i64 = 0
3968 let pre: *u8 = "/proc/" as *u8
3969 var a: i64 = 0
3970 while pre[a] != (0 as u8) { path[o] = pre[a]; o = o + 1; a = a + 1 }
3971 a = 0
3972 while dirname[a] != (0 as u8) { path[o] = dirname[a]; o = o + 1; a = a + 1 }
3973 let suf: *u8 = "/status" as *u8
3974 a = 0
3975 while suf[a] != (0 as u8) { path[o] = suf[a]; o = o + 1; a = a + 1 }
3976 path[o] = 0 as u8
3977 let b: *u8 = sys_mmap(VW_STATUS_BUF)
3978 let n: i64 = vw_read(path, b, VW_STATUS_BUF - 1)
3979 if n <= 0 { sys_munmap(path, VW_PROC_PATH_CAP); sys_munmap(b, VW_STATUS_BUF); return 0 - 1 }
3980 let r: i64 = vw_status_kb(b, n, label)
3981 sys_munmap(path, VW_PROC_PATH_CAP)
3982 sys_munmap(b, VW_STATUS_BUF)
3983 return r
3984}
3985// VmSize kB (back-compat; leak_check's memory meter). -1 unreadable.
3986func vw_vmsize_kb_of(dirname: *u8) -> i64 { return vw_status_kb_of(dirname, "VmSize:" as *u8) }
3987// VmRSS kB (resident set -- the heap-leak meter VmSize can hide in an arena).
3988func vw_rss_kb_of(dirname: *u8) -> i64 { return vw_status_kb_of(dirname, "VmRSS:" as *u8) }
3989
3990// nx_os_fs.nx -- OS FILESYSTEM-NAMESPACE SEAM (the write-safety half; sibling of nx_os_proc.nx).
3991// Answers ONE question for the IO layer: is this path in the OS's device/kernel/firmware namespace,
3992// where a file write could touch hardware or kernel state? Rule 26 (never-brick) demands the answer
3993// be BY CONSTRUCTION -- compiled in, not config-disableable -- so the deny lives here, in code, and
3994// callers cannot toggle it off with a conf line.
3995//
3996// LINUX BACKEND (current): the kernel exposes devices/firmware knobs as FILES under /dev, /sys, /proc
3997// (e.g. /sys/firmware/efi/efivars -- an errant write there can brick a board; /dev/sda -- raw disk).
3998// A path is write-forbidden iff it IS or is UNDER one of those roots.
3999//
4000// NISHIOS-NATIVE (target): NishiOS has no ambient device files -- device access is capability-routed
4001// through typed channels, so the ambient-namespace hazard class does not exist; the native backend
4002// returns forbid only for its reserved kernel-object namespace. This file is the SOURCE-SWAP seam
4003// (same contract, swapped backend), exactly like nx_os_proc.nx. license_tier: ORIGINAL
4004
4005
4006const OSF_SLASH: i64 = 47 // '/' -- path separator (namespace-boundary test)
4007
4008// is path EXACTLY root or UNDER root/ ? (blocks "/dev" and "/dev/null", not "/devdata")
4009func osf_under(path: *u8, root: *u8) -> i64 {
4010 var i: i64 = 0
4011 while root[i] != (0 as u8) {
4012 if path[i] != root[i] { return 0 }
4013 i = i + 1
4014 }
4015 if path[i] == (0 as u8) { return 1 } // exactly the root
4016 if path[i] == (OSF_SLASH as u8) { return 1 } // inside the root
4017 return 0
4018}
4019// WRITE-FORBIDDEN check: 1 = the OS device/kernel/firmware namespace, never writable through the IO layer.
4020func osf_write_forbidden(path: *u8) -> i64 {
4021 if osf_under(path, "/dev" as *u8) == 1 { return 1 }
4022 if osf_under(path, "/sys" as *u8) == 1 { return 1 }
4023 if osf_under(path, "/proc" as *u8) == 1 { return 1 }
4024 return 0
4025}
4026
4027// nx_os_proc.nx -- OS PROCESS-INTROSPECTION abstraction (the PORTABILITY SEAM). THE ONE place OS-specific
4028// process access lives, so every tool above it (nx_heal, ...) stays OS-AGNOSTIC + portable. Interop by
4029// construction: ONE source compiles to BOTH backends via the @ifdef target guard --
4030// LINUX backend = procfs (/proc/<pid>/{stat,cmdline}, getdents on /proc) [current NAS deploy]
4031// NISHIOS backend = native process table (@ifdef TARGET_NISHI seam) -- superior: a direct kernel
4032// query, NO text-parsing of /proc, NO USER_HZ guesswork. FAILS LOUD until wired,
4033// so a NishiOS build never silently inherits Linux assumptions.
4034// LAW (portability): NEVER scatter raw /proc, /sys, /dev, or hardcoded syscall numbers through the LOGIC
4035// layer -- put OS-specifics behind an nx_os_* seam like this one. The sovereign core (seg_store, tool
4036// logic) already only touches nx_syscalls (ABI-abstracted); this extends the same discipline to OS features.
4037// license_tier: ORIGINAL
4038
4039
4040const OSP_HZ_LINUX: i64 = 100 // Linux USER_HZ: /proc/<pid>/stat starttime ticks/sec
4041const OSP_PATH_CAP: i64 = 256
4042const OSP_RD_CAP: i64 = 4096
4043const OSP_STAT_CAP: i64 = 262144 // /proc/stat whole-file read cap (btime scan)
4044const OSP_DENT_BUF: i64 = 65536 // getdents64 batch buffer (proven sizing)
4045const OSP_F_PPID: i64 = 2 // /proc/<pid>/stat field after ')': state=1 ppid=2 ... utime=12 stime=13 ... starttime=20
4046const OSP_F_START: i64 = 20
4047const OSP_F_UTIME: i64 = 12 // user-mode CPU ticks (cumulative)
4048const OSP_F_STIME: i64 = 13 // kernel-mode CPU ticks (cumulative)
4049const OSP_ASCII_0: i64 = 48
4050const OSP_ASCII_9: i64 = 57
4051const OSP_SP: i64 = 32
4052const OSP_NL: i64 = 10
4053const OSP_RP: i64 = 41 // ')'
4054const OSP_SLASH: i64 = 47
4055const OSP_NUL: i64 = 0
4056const OSP_SENTINEL: i64 = 0 - 1 // "not available on this OS backend"
4057
4058func osp_slen(s: *u8) -> i64 { var n: i64 = 0; while s[n] != (OSP_NUL as u8) { n = n + 1 } return n }
4059// pid integer -> decimal string in out; return len
4060func osp_itoa(v: i64, out: *u8) -> i64 {
4061 if v == 0 { out[0] = OSP_ASCII_0 as u8; out[1] = 0 as u8; return 1 }
4062 let t: *u8 = sys_mmap(24); var m: i64 = v; var k: i64 = 0
4063 while m > 0 { t[k] = (OSP_ASCII_0 + (m % 10)) as u8; m = m / 10; k = k + 1 }
4064 var i: i64 = 0
4065 while i < k { out[i] = t[k-1-i]; i = i + 1 }
4066 out[k] = 0 as u8
4067 return k
4068}
4069// parse leading integer at buf[off..]; endp[0] = position of the FIRST non-digit (NOT n) so a caller
4070// walking fields can resume there. BUG-FIX 2026-07-16: the old `i = n` break jumped to end-of-buffer,
4071// so osp_stat_field skipped every field after the first non-numeric one (the state char) and never
4072// reached starttime (field 20) -- diagnose then dropped every real process.
4073func osp_num(buf: *u8, n: i64, off: i64, endp: *i64) -> i64 {
4074 var v: i64 = 0; var i: i64 = off; var any: i64 = 0; var go: i64 = 1
4075 while go == 1 {
4076 go = 0
4077 if i < n { let c: i64 = buf[i] as i64; if c >= OSP_ASCII_0 { if c <= OSP_ASCII_9 { v = v*(10 as i64)+(c-OSP_ASCII_0); any = 1; i = i + 1; go = 1 } } }
4078 }
4079 endp[0] = i
4080 if any == 0 { return OSP_SENTINEL }
4081 return v
4082}
4083// basename (after last '/') of NUL-terminated s
4084func osp_basename(s: *u8) -> *u8 {
4085 var i: i64 = 0; var last: i64 = 0
4086 while s[i] != (OSP_NUL as u8) { if s[i] == (OSP_SLASH as u8) { last = i + 1 } i = i + 1 }
4087 return (s as i64 + last) as *u8
4088}
4089
4090// ============================ LINUX BACKEND (procfs) ============================
4091// NOTE: the OS-target guard is currently a SOURCE-SWAP seam, not a compile-time @ifdef -- nx_cc's
4092// preprocessor is arch-guard-only today (TARGET_X86_64); a custom TARGET_NISHI compiled BOTH branches
4093// and the stub won (proven 2026-07-16). When nx_cc gains OS-target guards, wrap this in @ifdef
4094// TARGET_LINUX and the NishiOS backend (spec at bottom) in @ifdef TARGET_NISHI. The portability WIN
4095// stands regardless: every raw /proc lives HERE and nowhere else, so swapping the backend is a
4096// single-file change with the whole LOGIC layer (nx_heal) untouched.
4097// bounded read of a whole (small) proc/file into buf; returns len (0 on empty/absent)
4098func osp_bread(path: *u8, buf: *u8, cap: i64) -> i64 {
4099 let fd: i64 = sys_openat_rd(path)
4100 if fd < 0 { return 0 }
4101 var got: i64 = 0; var go: i64 = 1
4102 while go == 1 { let r: i64 = sys_read(fd, (buf as i64 + got) as *u8, cap - got); if r > 0 { got = got + r; if got >= cap { go = 0 } } else { go = 0 } }
4103 sys_close(fd)
4104 return got
4105}
4106// build "/proc/<pid><leaf>" (leaf NUL-terminated, e.g. "/stat") into out
4107func osp_ppath(out: *u8, pid: i64, leaf: *u8) -> i64 {
4108 var o: i64 = 0
4109 let pre: *u8 = "/proc/" as *u8
4110 var i: i64 = 0
4111 while pre[i] != (OSP_NUL as u8) { out[o] = pre[i]; o = o + 1; i = i + 1 }
4112 o = o + osp_itoa(pid, (out as i64 + o) as *u8)
4113 i = 0
4114 while leaf[i] != (OSP_NUL as u8) { out[o] = leaf[i]; o = o + 1; i = i + 1 }
4115 out[o] = 0 as u8
4116 return o
4117}
4118// enumerate live pids into pids[0..cap); returns count
4119func osp_list_pids(pids: *i64, cap: i64) -> i64 {
4120 let fd: i64 = sys_openat_rd("/proc" as *u8)
4121 if fd < 0 { return 0 }
4122 let dbuf: *u8 = sys_mmap(OSP_DENT_BUF)
4123 let ep: *i64 = sys_mmap(16) as *i64
4124 var cnt: i64 = 0; var run: i64 = 1
4125 while run == 1 {
4126 let n: i64 = sys_getdents64(fd, dbuf, OSP_DENT_BUF)
4127 if n <= 0 { run = 0 } else {
4128 var off: i64 = 0
4129 while off < n {
4130 let rec: *u8 = ((dbuf as i64 + off) as *u8)
4131 let reclen: i64 = dirent_reclen(rec)
4132 if reclen <= 0 { off = n } else {
4133 let name: *u8 = dirent_name(rec)
4134 if name[0] >= (OSP_ASCII_0 as u8) { if name[0] <= (OSP_ASCII_9 as u8) {
4135 if cnt < cap { let pid: i64 = osp_num(name, osp_slen(name), 0, ep); if pid > 0 { pids[cnt] = pid; cnt = cnt + 1 } }
4136 } }
4137 off = off + reclen
4138 }
4139 }
4140 }
4141 }
4142 sys_close(fd)
4143 return cnt
4144}
4145// count OPEN FILE DESCRIPTORS of pid = numeric entries in /proc/<pid>/fd. -1 if unreadable (gone/no perm).
4146// The fd METER for anomaly detection: a socket/file-descriptor leak trends up HERE while VmSize can stay
4147// flat (the fd table is not the address space) -- a leak shows in whatever resource disappears. Leak-free.
4148func osp_fd_count_from_fd_result(fd: i64, cause: *i64) -> i64 {
4149 if (cause as i64) != 0 { cause[0]=0 }
4150 let dbuf: *u8=sys_mmap(OSP_DENT_BUF)
4151 var count: i64=0
4152 var running: i64=1
4153 var failure: i64=0
4154 while running == 1 {
4155 let n: i64=sys_getdents64(fd,dbuf,OSP_DENT_BUF)
4156 if n < 0 { failure=n; running=0 } else {
4157 if n == 0 { running=0 } else {
4158 var off: i64=0
4159 while off < n {
4160 let rec: *u8=((dbuf as i64)+off) as *u8
4161 let reclen: i64=dirent_reclen(rec)
4162 if reclen <= 0 { failure=OSP_SENTINEL; running=0; break }
4163 let name: *u8=dirent_name(rec)
4164 if name[0] >= OSP_ASCII_0 as u8 && name[0] <= OSP_ASCII_9 as u8 { count=count+1 }
4165 off=off+reclen
4166 }
4167 }
4168 }
4169 }
4170 sys_munmap(dbuf,OSP_DENT_BUF)
4171 if failure < 0 { if (cause as i64) != 0 { cause[0]=failure }; return OSP_SENTINEL }
4172 return count
4173}
4174func osp_fd_count_from_fd(fd: i64) -> i64 {
4175 return osp_fd_count_from_fd_result(fd,0 as *i64)
4176}
4177func osp_fd_count(pid: i64) -> i64 {
4178 let path: *u8=sys_mmap(OSP_PATH_CAP)
4179 osp_ppath(path,pid,"/fd")
4180 let fd: i64=sys_openat_rd(path)
4181 sys_munmap(path,OSP_PATH_CAP)
4182 if fd < 0 { return OSP_SENTINEL }
4183 let count: i64=osp_fd_count_from_fd(fd)
4184 sys_close(fd)
4185 return count
4186}
4187
4188// field after the last ')' in /proc/<pid>/stat: OSP_F_PPID or OSP_F_START; SENTINEL on fail
4189func osp_stat_field(pid: i64, fidx: i64) -> i64 {
4190 let p: *u8 = sys_mmap(OSP_PATH_CAP)
4191 osp_ppath(p, pid, "/stat" as *u8)
4192 let b: *u8 = sys_mmap(OSP_RD_CAP)
4193 let n: i64 = osp_bread(p, b, OSP_RD_CAP - 1)
4194 if n <= 0 { return OSP_SENTINEL }
4195 var rp: i64 = 0 - 1; var i: i64 = 0
4196 while i < n { if b[i] == (OSP_RP as u8) { rp = i } i = i + 1 }
4197 if rp < 0 { return OSP_SENTINEL }
4198 var f: i64 = 0; i = rp + 1
4199 let ep: *i64 = sys_mmap(16) as *i64
4200 while i < n {
4201 if b[i] == (OSP_SP as u8) { i = i + 1 } else {
4202 f = f + 1
4203 let v: i64 = osp_num(b, n, i, ep)
4204 if f == fidx { return v }
4205 i = ep[0]
4206 var go: i64 = 1
4207 while go == 1 { go = 0; if i < n { if b[i] != (OSP_SP as u8) { i = i + 1; go = 1 } } }
4208 }
4209 }
4210 return OSP_SENTINEL
4211}
4212func osp_ppid(pid: i64) -> i64 { return osp_stat_field(pid, OSP_F_PPID) }
4213func osp_starttime_ticks(pid: i64) -> i64 { return osp_stat_field(pid, OSP_F_START) }
4214// cumulative CPU ticks consumed by pid = utime + stime. The CPU METER for anomaly detection: sampled over
4215// time, its RATE (Theil-Sen slope of the per-interval deltas) = the burn = "power disappearing" (a busy-loop
4216// pegs a core). SENTINEL if unreadable. HZ ticks/sec via osp_hz().
4217func osp_cpu_ticks(pid: i64) -> i64 {
4218 let u: i64 = osp_stat_field(pid, OSP_F_UTIME)
4219 let s: i64 = osp_stat_field(pid, OSP_F_STIME)
4220 if u == OSP_SENTINEL { return OSP_SENTINEL }
4221 if s == OSP_SENTINEL { return OSP_SENTINEL }
4222 return u + s
4223}
4224// argv0 basename of /proc/<pid>/cmdline into out; return len (0 if none)
4225func osp_cmd_argv0(pid: i64, out: *u8, cap: i64) -> i64 {
4226 let p: *u8 = sys_mmap(OSP_PATH_CAP)
4227 osp_ppath(p, pid, "/cmdline" as *u8)
4228 let cl: *u8 = sys_mmap(cap + 1)
4229 let n: i64 = osp_bread(p, cl, cap)
4230 if n <= 0 { out[0] = 0 as u8; return 0 }
4231 cl[n] = 0 as u8 // argv0 = bytes up to the first NUL (already there)
4232 let bn: *u8 = osp_basename(cl)
4233 var o: i64 = 0
4234 while bn[o] != (OSP_NUL as u8) { out[o] = bn[o]; o = o + 1 }
4235 out[o] = 0 as u8
4236 return o
4237}
4238func osp_hz() -> i64 { return OSP_HZ_LINUX }
4239// where the HOST SUPERVISOR writes its log -- a deployment/OS question, so it lives in the seam.
4240// Linux/NAS deploy: /tmp/supervisor.log (nx_hostctl supervise). NishiOS: its native supervisor journal.
4241func osp_supervisor_log() -> *u8 { return "/tmp/supervisor.log" as *u8 }
4242func osp_uptime_s() -> i64 { let ts: *i64 = sys_mmap(16) as *i64; sys_clock_gettime_mono(ts); return ts[0] }
4243func osp_selfpid() -> i64 {
4244 let b: *u8 = sys_mmap(OSP_RD_CAP)
4245 let n: i64 = osp_bread("/proc/self/stat" as *u8, b, OSP_RD_CAP - 1)
4246 if n <= 0 { return OSP_SENTINEL }
4247 let ep: *i64 = sys_mmap(16) as *i64
4248 return osp_num(b, n, 0, ep)
4249}
4250// wallclock epoch = /proc/stat btime + monotonic-since-boot
4251func osp_boot_epoch() -> i64 {
4252 let b: *u8 = sys_mmap(OSP_STAT_CAP)
4253 let n: i64 = osp_bread("/proc/stat" as *u8, b, OSP_STAT_CAP - 1)
4254 if n <= 0 { return 0 }
4255 let needle: *u8 = "btime " as *u8
4256 var i: i64 = 0
4257 let ep: *i64 = sys_mmap(16) as *i64
4258 while i < n {
4259 var m: i64 = 1; var k: i64 = 0
4260 while needle[k] != (OSP_NUL as u8) { if i+k >= n { m = 0 } else { if b[i+k] != needle[k] { m = 0 } } k = k + 1 }
4261 if m == 1 { return osp_num(b, n, i + k, ep) }
4262 i = i + 1
4263 }
4264 return 0
4265}
4266
4267// ======================= NISHIOS BACKEND SPEC (the swap-in seam) =======================
4268// When NishiOS's native process API lands, REPLACE the Linux backend above (or @ifdef-branch it once
4269// nx_cc has OS-target guards) with these ~8 functions over NishiOS's DIRECT kernel process table --
4270// superior to procfs: no /proc text-parsing, no USER_HZ, a real syscall query. The interface the LOGIC
4271// layer depends on (and ALL it depends on) is exactly:
4272// osp_list_pids(pids,cap)->count nishi_proc_enumerate (live pids)
4273// osp_ppid(pid)->ppid nishi_proc_parent
4274// osp_starttime_ticks(pid)->ticks nishi_proc_starttime (osp_hz() ticks/sec)
4275// osp_cmd_argv0(pid,out,cap)->len nishi_proc_argv0 (basename of argv0)
4276// osp_hz()->ticks_per_sec native rate (not the Linux-100 assumption)
4277// osp_uptime_s()->secs sys_clock_gettime_mono (already OS-neutral)
4278// osp_selfpid()->pid nishi_getpid
4279// osp_boot_epoch()->epoch nishi_boot_epoch
4280// Interop: NishiOS ships the superior backend; Linux stays supported for the current NAS deploy; the
4281// LOGIC (nx_heal) compiles unchanged on both. THAT is the point of this file.
4282
4283// Direct-child enumeration does not depend on CONFIG_CHECKPOINT_RESTORE's
4284// optional /proc/<pid>/task/<pid>/children file. The caller owns the output
4285// capacity; overflow is an error, never a plausible partial child set.
4286const OSP_DIRENT_NAME_OFFSET: i64 = 19 // Linux linux_dirent64 ABI
4287func osp_stat_parent(buf: *u8, n: i64) -> i64 {
4288 var last: i64=0-1;var i: i64=0
4289 while i < n { if buf[i] == OSP_RP as u8 { last=i };i=i+1 }
4290 if last < 0 { return 0-5 }
4291 i=last+1
4292 while i < n && buf[i] == OSP_SP as u8 { i=i+1 }
4293 while i < n && buf[i] != OSP_SP as u8 { i=i+1 }
4294 while i < n && buf[i] == OSP_SP as u8 { i=i+1 }
4295 let first: i64=i;var parent: i64=0
4296 while i < n && buf[i] >= OSP_ASCII_0 as u8 && buf[i] <= OSP_ASCII_9 as u8 {
4297 parent=parent*10+(buf[i] as i64)-OSP_ASCII_0;i=i+1
4298 }
4299 if i == first || i == n || buf[i] != OSP_SP as u8 { return 0-5 }
4300 return parent
4301}
4302func osp_children(parent: i64, children: *i64, capacity: i64) -> i64 {
4303 if parent <= 0 || capacity < 0 { return 0-22 }
4304 let directory: i64=sys_openat_directory("/proc")
4305 if directory < 0 { return directory }
4306 let batch: *u8=sys_mmap(OSP_DENT_BUF)
4307 let path: *u8=sys_mmap(OSP_PATH_CAP)
4308 let stat: *u8=sys_mmap(OSP_RD_CAP)
4309 var count: i64=0;var failure: i64=0;var running: i64=1
4310 while running == 1 {
4311 let n: i64=sys_getdents64(directory,batch,OSP_DENT_BUF)
4312 if n == (0-4) { continue }
4313 if n <= 0 { failure=n;break }
4314 var off: i64=0
4315 while off < n {
4316 if n-off <= OSP_DIRENT_NAME_OFFSET { failure=0-5;running=0;break }
4317 let rec: *u8=batch+off
4318 let size: i64=dirent_reclen(rec)
4319 if size <= OSP_DIRENT_NAME_OFFSET || size > n-off { failure=0-5;running=0;break }
4320 var i: i64=OSP_DIRENT_NAME_OFFSET;var pid: i64=0
4321 while i < size && rec[i] >= OSP_ASCII_0 as u8 && rec[i] <= OSP_ASCII_9 as u8 {
4322 pid=pid*10+(rec[i] as i64)-OSP_ASCII_0;i=i+1
4323 }
4324 if pid > 0 && i < size && rec[i] == OSP_NUL as u8 {
4325 osp_ppath(path,pid,"/stat")
4326 let fd: i64=sys_openat_rd(path)
4327 // A process may disappear during enumeration; other failures
4328 // make completeness unproven and must propagate.
4329 if fd < 0 && fd != (0-2) { failure=fd;running=0;break }
4330 if fd >= 0 {
4331 var used: i64=0;var readrc: i64=1
4332 while readrc > 0 && used < OSP_RD_CAP {
4333 readrc=sys_read(fd,stat+used,OSP_RD_CAP-used)
4334 if readrc == (0-4) { readrc=1;continue }
4335 if readrc > 0 { used=used+readrc }
4336 }
4337 let closed: i64=sys_close(fd)
4338 if readrc < 0 && readrc != (0-3) { failure=readrc;running=0;break }
4339 if closed < 0 { failure=closed;running=0;break }
4340 if used == OSP_RD_CAP { failure=0-75;running=0;break }
4341 if used > 0 {
4342 let observed: i64=osp_stat_parent(stat,used)
4343 if observed < 0 { failure=observed;running=0;break }
4344 if observed == parent {
4345 if count >= capacity { failure=0-28;running=0;break }
4346 children[count]=pid;count=count+1
4347 }
4348 }
4349 }
4350 }
4351 off=off+size
4352 }
4353 }
4354 let closed: i64=sys_close(directory)
4355 sys_munmap(batch,OSP_DENT_BUF);sys_munmap(path,OSP_PATH_CAP);sys_munmap(stat,OSP_RD_CAP)
4356 if failure < 0 { return failure }
4357 if closed < 0 { return closed }
4358 return count
4359}
4360
4361const FSX_MAGIC_4095: i64 = 4095
4362
4363const FSX_READ_CAP: i64 = 1048576 // max bytes returned by `read` (truncation is MARKED, never silent)
4364const FSX_DENY_CAP: i64 = 8192 // fs_read_deny.conf read cap
4365const FSX_PATH_CAP: i64 = 1024 // lowercased path work buffer
4366const FSX_DENT_BUF: i64 = 65536 // getdents64 batch buffer (matches the proven vsz/heal sizing)
4367const FSX_LS_CAP: i64 = 200 // scale-law: max ls entries EMITTED; true total ALWAYS declared (65KB-dump fix)
4368const FSX_RC_ABSENT: i64 = 3 // exit: path absent/unreadable (mirrors nx_fileop's exists convention)
4369const FSX_RC_DENIED: i64 = 5 // exit: deny-list refused the read
4370const FSX_UPPER_A: i64 = 65 // 'A' (ASCII lowercasing)
4371const FSX_UPPER_Z: i64 = 90 // 'Z'
4372const FSX_CASE_OFF: i64 = 32 // 'a' - 'A'
4373const FSX_ASCII_0: i64 = 48 // '0' (decimal print)
4374
4375func fsx_puts(s: *u8) -> i64 { var n: i64 = 0; while s[n] != (0 as u8) { n = n + 1 } sys_write(1, s, n); return 0 }
4376// MIGRATED to the shared emitter (debt 1785563586). The old body mmapped a scratch buffer
4377// per call and never freed it. At PAGE granularity that is 4096B leaked PER CALL -- the
4378// defect that took 28.5GB of a 36GB host in nx_ts_lumadiff (2MB input, ~3.66M calls).
4379// nxi_* is MSB-first, allocates NOTHING, and emits identical bytes including the sign.
4380func fsx_putn(v: i64) -> i64 { nxi_out(v); return 0 }
4381// lowercase copy of s into out (bounded), returns length
4382func fsx_lower(s: *u8, out: *u8, cap: i64) -> i64 {
4383 var i: i64 = 0
4384 while s[i] != (0 as u8) {
4385 if i >= cap - 1 { out[i] = 0 as u8; return i }
4386 var c: i64 = s[i] as i64
4387 if c >= FSX_UPPER_A { if c <= FSX_UPPER_Z { c = c + FSX_CASE_OFF } }
4388 out[i] = c as u8
4389 i = i + 1
4390 }
4391 out[i] = 0 as u8
4392 return i
4393}
4394// exact NUL-terminated string equality
4395func fsx_seq(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 }
4396// is `needle` (NUL-terminated, lowercase) contained in lowercase path lp[0..ln)?
4397// ---------- compare-and-swap decision (seq1422/seq1456) ----------
4398//
4399// PURE, and in the LIB on purpose: the decision used to live inside the CLI's
4400// main(), where a gate cannot reach it -- which is exactly how it shipped
4401// refusing every correct expectation (seq1422). A rule nothing can drive is a
4402// rule nothing can prove.
4403//
4404// tok is the raw argv token (`expect=<n>` / `expect=any` / a bare number);
4405// cur is the file's real size. Returns 1 = ALLOW, 0 = REFUSE.
4406func fsx_cas_val(tok: *u8) -> *u8 {
4407 var i: i64 = 0
4408 while tok[i] != (0 as u8) {
4409 if tok[i] == (61 as u8) { return ((tok as i64) + i + 1) as *u8 }
4410 i = i + 1
4411 }
4412 return tok
4413}
4414func fsx_cas_ok(cur: i64, tok: *u8) -> i64 {
4415 let v: *u8 = fsx_cas_val(tok)
4416 if fsx_seq(v, "any" as *u8) == 1 { return 1 }
4417 var n: i64 = 0
4418 var i: i64 = 0
4419 var got: i64 = 0
4420 while v[i] != (0 as u8) {
4421 let c: i64 = v[i] as i64
4422 if c >= 48 { if c <= 57 { n = n * 10 + (c - 48); got = 1 } }
4423 i = i + 1
4424 }
4425 if got == 0 { return 0 }
4426 if n == cur { return 1 }
4427 return 0
4428}
4429
4430func fsx_deny_hit(lp: *u8, ln: i64, needle: *u8) -> i64 {
4431 let nl: i64 = vw_slen(needle)
4432 if nl == 0 { return 0 }
4433 return vw_contains(lp, ln, needle, nl)
4434}
4435// data-driven deny extras: one lowercase needle per line in `conf`; 1 = some line matches the path.
4436// Factored out so the read deny (fs_read_deny.conf) and write deny (fs_write_deny.conf) share ONE scanner.
4437func fsx_conf_deny(lp: *u8, ln: i64, conf: *u8) -> i64 {
4438 let cb: *u8 = sys_mmap(FSX_DENY_CAP)
4439 let cn: i64 = vw_read(conf, cb, FSX_DENY_CAP - 1)
4440 if cn > 0 {
4441 var ls: i64 = 0
4442 var i: i64 = 0
4443 while i <= cn {
4444 var eol: i64 = 0
4445 if i == cn { eol = 1 } else { if cb[i] == (10 as u8) { eol = 1 } }
4446 if eol == 1 {
4447 if i > ls {
4448 cb[i] = 0 as u8 // terminate the line in place
4449 if fsx_deny_hit(lp, ln, (cb as i64 + ls) as *u8) == 1 { return 1 }
4450 }
4451 ls = i + 1
4452 }
4453 i = i + 1
4454 }
4455 }
4456 return 0
4457}
4458const FSX_SNIFF_CAP: i64 = 4096
4459
4460func fsx_isalnum(c: i64) -> i64 {
4461 if c >= 48 { if c <= 57 { return 1 } }
4462 if c >= 97 { if c <= 122 { return 1 } }
4463 if c >= 65 { if c <= 90 { return 1 } }
4464 return 0
4465}
4466
4467func fsx_ends_with(lp: *u8, ln: i64, suf: *u8) -> i64 {
4468 let sl: i64 = vw_slen(suf)
4469 if sl == 0 { return 0 }
4470 if sl > ln { return 0 }
4471 var i: i64 = 0
4472 while i < sl {
4473 if lp[ln - sl + i] != suf[i] { return 0 }
4474 i = i + 1
4475 }
4476 return 1
4477}
4478
4479func fsx_basename_is(lp: *u8, ln: i64, name: *u8) -> i64 {
4480 let nl: i64 = vw_slen(name)
4481 if nl == 0 { return 0 }
4482 if nl > ln { return 0 }
4483 if fsx_ends_with(lp, ln, name) == 0 { return 0 }
4484 if nl == ln { return 1 }
4485 let c: i64 = lp[ln - nl - 1] as i64
4486 if c == 47 { return 1 }
4487 if c == 92 { return 1 }
4488 return 0
4489}
4490
4491// Whole-word containment: bounded by non-alphanumeric on BOTH sides, so `api_secret.txt` is denied and
4492// `secretary_notes.md` is not.
4493func fsx_word_has(lp: *u8, ln: i64, w: *u8) -> i64 {
4494 let wl: i64 = vw_slen(w)
4495 if wl == 0 { return 0 }
4496 if wl > ln { return 0 }
4497 var i: i64 = 0
4498 while i + wl <= ln {
4499 var eq: i64 = 1
4500 var k: i64 = 0
4501 while k < wl { if lp[i + k] != w[k] { eq = 0; k = wl } else { k = k + 1 } }
4502 if eq == 1 {
4503 var lb: i64 = 1
4504 if i > 0 { if fsx_isalnum(lp[i - 1] as i64) == 1 { lb = 0 } }
4505 var rb: i64 = 1
4506 if i + wl < ln { if fsx_isalnum(lp[i + wl] as i64) == 1 { rb = 0 } }
4507 if lb == 1 { if rb == 1 { return 1 } }
4508 }
4509 i = i + 1
4510 }
4511 return 0
4512}
4513
4514// CONTENT LEG: sniff the leading bytes for what a secret actually IS. This is the half a name-only list
4515// can never do -- it denies a private key no matter what it is called, including `notes.txt`.
4516// A CERTIFICATE is deliberately NOT denied: certs are public by definition, and denying them is the same
4517// category error as denying the tokenizer.
4518func fsx_content_secret(path: *u8) -> i64 {
4519 let fd: i64 = sys_openat_rd(path)
4520 if fd < 0 { return 0 }
4521 let b: *u8 = sys_mmap(FSX_SNIFF_CAP)
4522 let n: i64 = sys_read(fd, b, FSX_SNIFF_CAP - 1)
4523 sys_close(fd)
4524 if n <= 0 { return 0 }
4525 if vw_contains(b, n, "PRIVATE KEY-----" as *u8, 16) == 1 { return 1 }
4526 if vw_contains(b, n, "OPENSSH PRIVATE KEY" as *u8, 19) == 1 { return 1 }
4527 if vw_contains(b, n, "PGP PRIVATE KEY BLOCK" as *u8, 21) == 1 { return 1 }
4528 if vw_contains(b, n, "PuTTY-User-Key-File" as *u8, 19) == 1 { return 1 }
4529 return 0
4530}
4531
4532// DENY check: 1 = refuse this path. SOTA-2026 REWRITE (2026-07-31).
4533//
4534// THE OLD RULE WAS WRONG IN BOTH DIRECTIONS, measured on real paths:
4535// OVER-BLOCKED substring "token" denied runtime/nx_tokenizer.nx -- the compiler's own tokenizer, which
4536// contains no secret -- and blocked BOTH nx_fs read AND nx_fs_write on it, while
4537// nx_shelltool grep returned the same bytes freely. It cost real work and bought nothing.
4538// substring "key" likewise denies monkey / keyword / keyboard.
4539// UNDER-BLOCKED `id_rsa`, the canonical SSH private key filename, contains NONE of
4540// secret/key/token/passw/.pem and sailed straight through.
4541// A denylist that blocks source and passes private keys is not a security control -- it is a rename away
4542// from useless in one direction and a permanent nuisance in the other.
4543//
4544// REPLACEMENT -- two INDEPENDENT legs, either one denies:
4545// (1) PATH leg: real secret-bearing EXTENSIONS and exact BASENAMES, matched at a true suffix/segment
4546// boundary, plus whole-word `secret`/`password`. No substring-anywhere matching survives.
4547// (2) CONTENT leg: PEM/OpenSSH/PGP/PuTTY private-key armour, which catches a secret regardless of name.
4548// Net effect: strictly MORE secrets denied (id_rsa, a renamed key, a key with no extension) and strictly
4549// FEWER ordinary sources blocked.
4550func fsx_denied(path: *u8) -> i64 {
4551 let lp: *u8 = sys_mmap(FSX_PATH_CAP)
4552 let ln: i64 = fsx_lower(path, lp, FSX_PATH_CAP)
4553
4554 if fsx_ends_with(lp, ln, ".pem" as *u8) == 1 { return 1 }
4555 if fsx_ends_with(lp, ln, ".key" as *u8) == 1 { return 1 }
4556 if fsx_ends_with(lp, ln, ".cap" as *u8) == 1 { return 1 }
4557 if fsx_ends_with(lp, ln, ".p12" as *u8) == 1 { return 1 }
4558 if fsx_ends_with(lp, ln, ".pfx" as *u8) == 1 { return 1 }
4559 if fsx_ends_with(lp, ln, ".jks" as *u8) == 1 { return 1 }
4560 if fsx_ends_with(lp, ln, ".ppk" as *u8) == 1 { return 1 }
4561 if fsx_ends_with(lp, ln, "_rsa" as *u8) == 1 { return 1 }
4562 if fsx_ends_with(lp, ln, "_dsa" as *u8) == 1 { return 1 }
4563 if fsx_ends_with(lp, ln, "_ecdsa" as *u8) == 1 { return 1 }
4564 if fsx_ends_with(lp, ln, "_ed25519" as *u8) == 1 { return 1 }
4565
4566 if fsx_basename_is(lp, ln, ".env" as *u8) == 1 { return 1 }
4567 if fsx_basename_is(lp, ln, "credentials" as *u8) == 1 { return 1 }
4568 if fsx_basename_is(lp, ln, "shadow" as *u8) == 1 { return 1 }
4569 if fsx_basename_is(lp, ln, "opaque_keys.bin" as *u8) == 1 { return 1 }
4570
4571 // CALIBRATED BY WORD FREQUENCY, not by one uniform rule -- the gate proved a uniform rule wrong in
4572 // BOTH directions within minutes. `secret` and `passw` are high-signal and essentially absent from
4573 // ordinary source, so SUBSTRING matching is correct for them and catches mysecret_key.bin. `key` and
4574 // `token` are common English fragments (tokenizer, monkey, keyword, keyboard) and must NEVER be
4575 // substring-matched -- that is what denied the compiler's own tokenizer. They are covered instead by
4576 // the extension/suffix rules above and by the content leg below.
4577 if fsx_deny_hit(lp, ln, "secret" as *u8) == 1 { return 1 }
4578 if fsx_deny_hit(lp, ln, "passw" as *u8) == 1 { return 1 }
4579 if fsx_deny_hit(lp, ln, "credential" as *u8) == 1 { return 1 }
4580
4581 if fsx_content_secret(path) == 1 { return 1 }
4582
4583 return fsx_conf_deny(lp, ln, "fs_read_deny.conf" as *u8)
4584}
4585// read: emit up to `cap` bytes of path to stdout. Returns bytes emitted; -1 absent; -2 DENIED.
4586// deniedp/absent are ALSO visible in the CLI exit code. Truncation is marked with a trailing banner.
4587// Failure reporter that KEEPS THE ERRNO. sys_openat_rd returns -errno, and the old message printed
4588// "ABSENT" for every negative -- so EACCES (-13, EXISTS but unopenable) read as "missing", which are
4589// OPPOSITE remedies. Cost a real hour on 2026-08-01: knowledge/foundation existed with mode 0100 and
4590// every instrument in the stack called it absent (the mkdirp read-back that printed the errno cracked
4591// the case in one call). rc>=0 means a probe re-open SUCCEEDED: the earlier read failed for a
4592// non-open reason (an empty file), so say THAT. Always returns -1 (callers' contract unchanged;
4593// the -2 DENIED sentinel stays distinct).
4594func fsx_fail(path: *u8, rc: i64) -> i64 {
4595 if rc >= 0 { sys_close(rc); fsx_puts("NX-FS EMPTY: 0 bytes: " as *u8); fsx_puts(path); fsx_puts("\n" as *u8); return 0 - 1 }
4596 if rc == 0 - 13 {
4597 fsx_puts("NX-FS PERMISSION (EACCES): exists but this process may not open it: " as *u8)
4598 fsx_puts(path); fsx_puts("\n" as *u8)
4599 return 0 - 1
4600 }
4601 if rc == 0 - 2 { fsx_puts("NX-FS ABSENT: " as *u8); fsx_puts(path); fsx_puts("\n" as *u8); return 0 - 1 }
4602 fsx_puts("NX-FS ERROR rc=" as *u8); fsx_putn(rc)
4603 fsx_puts(": " as *u8); fsx_puts(path); fsx_puts("\n" as *u8)
4604 return 0 - 1
4605}
4606
4607const FSX_SEEK_END: i64 = 2 // lseek whence: EOF offset = size, WITHOUT reading a single byte
4608
4609// TRUE SIZE -- the one thing no other read verb in this lib can give you (2026-08-07, debt 1786054029).
4610// read/lines/outline all report BYTES THEY READ against FSX_READ_CAP/FSX_LINES_SCAN, and they DO honestly
4611// declare the cap -- but an honest floor is still not a measurement: "bytes=1048576 (covers first 1048576
4612// bytes only)" is the IDENTICAL answer for a 1.05MB file and a 30MB one.
4613// MEASURED COST OF NOT HAVING IT: bounding ONE 1.38MB journal took TWELVE probe reads at hand-chosen
4614// offsets, because the only way to learn a big file size was to binary-search EOF by hand.
4615// lseek(SEEK_END) reads ZERO bytes, so the answer is exact at ANY size for one syscall.
4616// Deny-list still applies: consistency with every other verb beats a special case for a metadata read.
4617// CONTRACT DIFFERS FROM fsx_read ON PURPOSE: an EMPTY file returns 0, never -1. Size is the one caller for
4618// which "absent" and "zero bytes" are DIFFERENT FACTS, so fsx_fail -- which folds both to -1 -- is not used
4619// here. (Same distinction lt_read_tail needed: -1 ABSENT vs 0 EMPTY. A reader that conflates them cannot
4620// tell a lane that never wrote from a lane whose file vanished.)
4621// A DECLARED FLOOR IS HONEST BUT IT IS NOT A MEASUREMENT -- IF THE NUMBER IS CHEAP, EMIT THE NUMBER.
4622func fsx_size(path: *u8) -> i64 {
4623 if fsx_denied(path) == 1 {
4624 fsx_puts("NX-FS-SIZE DENIED: path matches the secret deny-list. WHY: this tool never returns key material.\n" as *u8)
4625 return 0 - (2 as i64)
4626 }
4627 let fd: i64 = sys_openat_rd(path)
4628 if fd < 0 {
4629 fsx_puts("NX-FS-SIZE ABSENT: cannot open " as *u8); fsx_puts(path)
4630 fsx_puts(" . FIX: confirm the path with `nx_fs ls <dir>`.\n" as *u8)
4631 return 0 - 1
4632 }
4633 let sz: i64 = sys_lseek(fd, 0, FSX_SEEK_END)
4634 sys_close(fd)
4635 if sz < 0 {
4636 fsx_puts("NX-FS-SIZE UNSEEKABLE: " as *u8); fsx_puts(path)
4637 fsx_puts(" (a pipe/char device has no size; this is NOT a zero-byte file)\n" as *u8)
4638 return 0 - 1
4639 }
4640 fsx_puts("NX-FS-SIZE " as *u8); fsx_puts(path)
4641 fsx_puts(" bytes=" as *u8); fsx_putn(sz)
4642 fsx_puts(" exact=1 read_bytes=0\n" as *u8)
4643 return sz
4644}
4645
4646func fsx_read(path: *u8, cap: i64) -> i64 {
4647 if fsx_denied(path) == 1 {
4648 fsx_puts("NX-FS DENIED: path matches the secret deny-list (defaults + fs_read_deny.conf)\n" as *u8)
4649 return 0 - (2 as i64) // DENIED sentinel (distinct from -1 absent)
4650 }
4651 var want: i64 = cap
4652 if want <= 0 { want = FSX_READ_CAP }
4653 if want > FSX_READ_CAP { want = FSX_READ_CAP }
4654 let buf: *u8 = sys_mmap(want + 1)
4655 let n: i64 = vw_read(path, buf, want)
4656 // vw_read flattens the errno (-1 for every failure); re-probe the open ONLY on the failure path
4657 // so the message can distinguish absent / permission / empty. Zero cost on success.
4658 if n <= 0 { return fsx_fail(path, sys_openat_rd(path)) }
4659 sys_write(1, buf, n)
4660 if n == want {
4661 fsx_puts("\n[NX-FS TRUNCATED at " as *u8); fsx_putn(n); fsx_puts(" bytes]\n" as *u8)
4662 }
4663 return n
4664}
4665// WINDOWED read (eats debt seq222: the tools-call transport caps ~64KB, so files past the cap were
4666// unreadable over MCP): emit up to `cap` bytes starting at byte `off`. Same deny-list as fsx_read.
4667// A separate function (NOT an fsx_read arity change) so every existing caller keeps its exact contract.
4668func fsx_read_at(path: *u8, cap: i64, off: i64) -> i64 {
4669 if fsx_denied(path) == 1 {
4670 fsx_puts("NX-FS DENIED: path matches the secret deny-list (defaults + fs_read_deny.conf)\n" as *u8)
4671 return 0 - (2 as i64)
4672 }
4673 var want: i64 = cap
4674 if want <= 0 { want = FSX_READ_CAP }
4675 if want > FSX_READ_CAP { want = FSX_READ_CAP }
4676 let fd: i64 = sys_openat_rd(path)
4677 if fd < 0 { return fsx_fail(path, fd) }
4678 if off > 0 { if sys_lseek(fd, off, 0) < 0 { sys_close(fd); fsx_puts("NX-FS ABSENT: seek failed " as *u8); fsx_puts(path); fsx_puts("\n" as *u8); return 0 - 1 } }
4679 let buf: *u8 = sys_mmap(want + 1)
4680 var got: i64 = 0
4681 var sc: i64 = 1
4682 while sc == 1 {
4683 let r: i64 = sys_read(fd, ((buf as i64 + got) as *u8), want - got)
4684 if r <= 0 { sc = 0 } else { got = got + r; if got >= want { sc = 0 } }
4685 }
4686 sys_close(fd)
4687 if got <= 0 { fsx_puts("NX-FS EOF: no bytes at offset " as *u8); fsx_putn(off); fsx_puts(" in " as *u8); fsx_puts(path); fsx_puts("\n" as *u8); return 0 - 1 }
4688 sys_write(1, buf, got)
4689 if got == want {
4690 fsx_puts("\n[NX-FS WINDOW off=" as *u8); fsx_putn(off); fsx_puts(" n=" as *u8); fsx_putn(got); fsx_puts(" -- more remains]\n" as *u8)
4691 }
4692 return got
4693}
4694const FSX_LINES_SCAN: i64 = 1048576 // line-addressing scan window (matches the proven read cap)
4695const FSX_LINES_MAXOUT: i64 = 262144 // max bytes emitted by one `lines` call (transport-friendly)
4696const FSX_LINES_DEFN: i64 = 40 // default line count when the caller omits it
4697const FSX_LINES_MAXN: i64 = 400 // max lines per call
4698
4699// LINE-ADDRESSED read -- THE MISSING PRIMITIVE (measured 2026-07-20): `grep` reports file:LINE but `read`
4700// takes BYTES, so the two did NOT compose -- locating one function in a remote file meant hand
4701// binary-searching byte offsets (cost one subagent 70K tokens + 22 calls for a single extraction).
4702// Emits lines [start, start+count) 1-based, then a DECLARED envelope banner (scale-law: a caller can
4703// NEVER be silently windowed -- scanned bytes, scan cap, over-window and clip flags are all stated).
4704// Same deny-list as fsx_read. Returns bytes emitted; -1 absent; -2 DENIED.
4705func fsx_read_lines(path: *u8, start: i64, count: i64) -> i64 {
4706 if fsx_denied(path) == 1 {
4707 fsx_puts("NX-FS DENIED: path matches the secret deny-list (defaults + fs_read_deny.conf)\n" as *u8)
4708 return 0 - (2 as i64)
4709 }
4710 var s: i64 = start
4711 if s < 1 { s = 1 }
4712 var c: i64 = count
4713 if c <= 0 { c = FSX_LINES_DEFN }
4714 if c > FSX_LINES_MAXN { c = FSX_LINES_MAXN }
4715 let buf: *u8 = sys_mmap(FSX_LINES_SCAN + 1)
4716 let n: i64 = vw_read(path, buf, FSX_LINES_SCAN)
4717 if n <= 0 { return fsx_fail(path, sys_openat_rd(path)) }
4718 // walk to the first byte of line `s`; cur > s afterwards means we ran off the end (fail-loud, not empty)
4719 var i: i64 = 0
4720 var cur: i64 = 1
4721 while cur < s {
4722 if i >= n { cur = s + 1 } else {
4723 if buf[i] == (10 as u8) { cur = cur + 1 }
4724 i = i + 1
4725 }
4726 }
4727 if cur > s {
4728 fsx_puts("NX-FS LINES: start line " as *u8); fsx_putn(s)
4729 fsx_puts(" is beyond EOF (scanned " as *u8); fsx_putn(n); fsx_puts(" bytes)\n" as *u8)
4730 return 0
4731 }
4732 let from: i64 = i
4733 var lines_out: i64 = 0
4734 var j: i64 = i
4735 var go: i64 = 1
4736 while go == 1 {
4737 if j >= n { go = 0 } else {
4738 if buf[j] == (10 as u8) {
4739 lines_out = lines_out + 1
4740 j = j + 1
4741 if lines_out >= c { go = 0 }
4742 } else { j = j + 1 }
4743 }
4744 }
4745 var outn: i64 = j - from
4746 var clipped: i64 = 0
4747 if outn > FSX_LINES_MAXOUT { outn = FSX_LINES_MAXOUT; clipped = 1 }
4748 if outn > 0 { sys_write(1, ((buf as i64 + from) as *u8), outn) }
4749 fsx_puts("\n[NX-FS LINES start=" as *u8); fsx_putn(s)
4750 fsx_puts(" lines=" as *u8); fsx_putn(lines_out)
4751 fsx_puts(" next=" as *u8); fsx_putn(s + lines_out)
4752 fsx_puts(" bytes=" as *u8); fsx_putn(outn)
4753 fsx_puts(" scanned=" as *u8); fsx_putn(n)
4754 fsx_puts(" scan_cap=" as *u8); fsx_putn(FSX_LINES_SCAN)
4755 if n >= FSX_LINES_SCAN { fsx_puts(" FILE-EXCEEDS-SCAN-WINDOW" as *u8) }
4756 if clipped == 1 { fsx_puts(" BYTE-CLIPPED" as *u8) }
4757 fsx_puts("]\n" as *u8)
4758 return outn
4759}
4760// ==== WRITE/EDIT half (cap class: write; tools-api name nx_fs_write) =========================
4761// ★ONE DEFINITION, TWO NAMES: this const KEEPS its name so no caller changes, but its VALUE now comes
4762// from the shim's MODE_0644 instead of a second literal. This line already called itself "the ecosystem's
4763// file-create mode idiom" -- and it was right, which is why adding MODE_0644 to nx_syscalls without
4764// finding it created a 64th copy rather than a single ruler.
4765// ★★★SEARCHING BY NAME FINDS ONLY WHAT SHARES YOUR NAMING CONVENTION. TO FIND A DUPLICATE CONSTANT YOU
4766// MUST SEARCH BY VALUE: a grep for `_MODE_0644` returned 10, a grep for `= 0x1a4` returned 66.
4767const FSX_MODE_RW: i64 = MODE_0644 // 0644 -- the ecosystem's file-create mode idiom
4768const FSX_DEC: i64 = 10 // decimal base (pid rendering in the tmp suffix)
4769const FSX_EDIT_OUT: i64 = 2097152 // edit output buffer (2x read cap: bounded replacement growth)
4770const FSX_TMP_ROOM: i64 = 32 // reserved room for ".nxw" + pid digits + NUL in the tmp name
4771const FSX_RC_IO: i64 = 4 // exit: io failure (open/short-write/rename)
4772const FSX_RC_NOMATCH: i64 = 6 // exit: edit found 0 occurrences (file UNCHANGED)
4773const FSX_RC_AMBIG: i64 = 7 // exit: edit found >1 occurrences without `all` (file UNCHANGED)
4774
4775// write-DENY: read deny (never clobber key material) + OS device/firmware namespace (rule 26, seam,
4776// BY CONSTRUCTION) + registry-escalation needle + fs_write_deny.conf extras (data-driven).
4777// TAIL -- the "WHERE DOES THIS FILE END" primitive, answered from the file's own end in ONE call.
4778// The documented recipe was `size`, then `read <path> <n> <size-n>`: two calls and an offset the caller
4779// carries by hand. What actually happened (measured 2026-09-03): a caller chose a `lines` start from an
4780// EARLIER run's size, read a window that landed mid-file, and published the window's last line as the
4781// file's last line -- while the envelope on that very read said next=212. Two false mechanisms and a
4782// false scope claim followed. ★A WINDOW READ IS NOT A TAIL READ. This verb cannot be pointed at the
4783// middle: it seeks to the end, walks BACKWARD for the last `count` line starts, and declares its window.
4784// Same deny-list as every read verb. Returns bytes emitted; 0 for an empty file (banner, never silence);
4785// -1 absent/unseekable; -2 DENIED.
4786func fsx_tail(path: *u8, count: i64) -> i64 {
4787 if fsx_denied(path) == 1 {
4788 fsx_puts("NX-FS DENIED: path matches the secret deny-list (defaults + fs_read_deny.conf)\n" as *u8)
4789 return 0 - (2 as i64)
4790 }
4791 var c: i64 = count
4792 if c <= 0 { c = FSX_LINES_DEFN }
4793 if c > FSX_LINES_MAXN { c = FSX_LINES_MAXN }
4794 let fd: i64 = sys_openat_rd(path)
4795 if fd < 0 { return fsx_fail(path, fd) }
4796 let sz: i64 = sys_lseek(fd, 0, FSX_SEEK_END)
4797 if sz < 0 {
4798 sys_close(fd)
4799 fsx_puts("NX-FS TAIL UNSEEKABLE: " as *u8); fsx_puts(path)
4800 fsx_puts(" (a pipe/char device has no end to seek to)\n" as *u8)
4801 return 0 - 1
4802 }
4803 if sz == 0 {
4804 sys_close(fd)
4805 fsx_puts("[NX-FS TAIL lines=0 total_bytes=0 window_off=0 scanned=0 EMPTY-FILE]\n" as *u8)
4806 return 0
4807 }
4808 // read the LAST scan-window of the file, never the first: a log past the window still yields its end
4809 var off: i64 = 0
4810 if sz > FSX_LINES_SCAN { off = sz - FSX_LINES_SCAN }
4811 if sys_lseek(fd, off, 0) < 0 {
4812 sys_close(fd)
4813 fsx_puts("NX-FS ABSENT: seek failed " as *u8); fsx_puts(path); fsx_puts("\n" as *u8)
4814 return 0 - 1
4815 }
4816 let buf: *u8 = sys_mmap(FSX_LINES_SCAN + 1)
4817 var n: i64 = 0
4818 var sc: i64 = 1
4819 while sc == 1 {
4820 let r: i64 = sys_read(fd, ((buf as i64 + n) as *u8), FSX_LINES_SCAN - n)
4821 if r <= 0 { sc = 0 } else { n = n + r; if n >= FSX_LINES_SCAN { sc = 0 } }
4822 }
4823 sys_close(fd)
4824 if n <= 0 { return fsx_fail(path, 0 - 1) }
4825 // a single trailing newline terminates the last line; it is not an empty extra line
4826 var lim: i64 = n
4827 var terminated: i64 = 0
4828 if buf[n - 1] == (10 as u8) { lim = n - 1; terminated = 1 }
4829 // walk backward for `c` line starts
4830 var p: i64 = lim
4831 var seen: i64 = 0
4832 var start: i64 = 0
4833 var go: i64 = 1
4834 while go == 1 {
4835 if p <= 0 { start = 0; go = 0 } else {
4836 p = p - 1
4837 if buf[p] == (10 as u8) {
4838 seen = seen + 1
4839 if seen >= c { start = p + 1; go = 0 }
4840 }
4841 }
4842 }
4843 var lines_out: i64 = seen + 1
4844 if seen >= c { lines_out = c }
4845 // count the window's lines once so a caller can address the whole file with `lines` afterwards
4846 var wl: i64 = 0
4847 var q: i64 = 0
4848 while q < lim { if buf[q] == (10 as u8) { wl = wl + 1 } q = q + 1 }
4849 wl = wl + 1
4850 let outn: i64 = n - start
4851 if outn > 0 { sys_write(1, ((buf as i64 + start) as *u8), outn) }
4852 if terminated == 0 { fsx_puts("\n" as *u8) }
4853 fsx_puts("[NX-FS TAIL lines=" as *u8); fsx_putn(lines_out)
4854 fsx_puts(" bytes=" as *u8); fsx_putn(outn)
4855 fsx_puts(" total_bytes=" as *u8); fsx_putn(sz)
4856 fsx_puts(" window_off=" as *u8); fsx_putn(off)
4857 fsx_puts(" scanned=" as *u8); fsx_putn(n)
4858 fsx_puts(" window_lines=" as *u8); fsx_putn(wl)
4859 fsx_puts(" last_line_terminated=" as *u8); fsx_putn(terminated)
4860 if off > 0 { fsx_puts(" WINDOW-IS-TAIL-OF-FILE" as *u8) }
4861 if off > 0 { if start == 0 { fsx_puts(" FIRST-LINE-MAY-BE-PARTIAL" as *u8) } }
4862 fsx_puts("]\n" as *u8)
4863 return outn
4864}
4865
4866func fsx_write_denied(path: *u8) -> i64 {
4867 if fsx_denied(path) == 1 { return 1 }
4868 if osf_write_forbidden(path) == 1 { return 1 }
4869 let lp: *u8 = sys_mmap(FSX_PATH_CAP)
4870 let ln: i64 = fsx_lower(path, lp, FSX_PATH_CAP)
4871 if fsx_deny_hit(lp, ln, "allowlist" as *u8) == 1 { return 1 }
4872 return fsx_conf_deny(lp, ln, "fs_write_deny.conf" as *u8)
4873}
4874// ---------- APPEND-ONLY write for journals and boards (2026-09-02) ----------
4875// ONE O_APPEND write under an exclusive flock: the row lands whole and AFTER every row already there, and
4876// there is no read-modify-write window for a sibling seat to lose it in. MEASURED the same day: a `log|`
4877// row appended to lang.plan by anchored CAS edit (receipt OK bytes=51180) was gone minutes later -- a
4878// sibling's whole-file write had rebuilt the file from its own stale read. A BOARD IS A JOURNAL; JOURNALS
4879// ARE APPENDED, NEVER REWRITTEN. The write deny-list applies unchanged (a new write path must never become
4880// a way into the secret or device namespace).
4881// CONTRACT: body must end in '\n' (a row that does not terminate glues itself to the next seat's row ->
4882// FSX_APP_NONL, file unchanged); an empty body is refused (FSX_APP_EMPTY); when the file's LAST byte is not
4883// a newline (a rewrite left an unterminated tail) one newline is prepended INSIDE the same locked write, so
4884// the caller sees bytes-written == blen + 1 and can announce the heal. Returns bytes written; -2 DENIED;
4885// -3 io (open/lock/short write).
4886const FSX_NL: i64 = 10 // '\n' -- the row terminator this verb requires and heals
4887const FSX_APP_EMPTY: i64 = 0 - 4 // append refused: nothing to append
4888const FSX_APP_NONL: i64 = 0 - 5 // append refused: body does not end in a newline
4889const FSX_SEEK_SET: i64 = 0 // lseek whence: absolute offset (the tail probe)
4890// 1 = the file exists, is non-empty and its last byte is NOT a newline (an unterminated tail); else 0.
4891func fsx_tail_unterminated(path: *u8) -> i64 {
4892 let fd: i64 = sys_openat_rd(path)
4893 if fd < 0 { return 0 }
4894 let sz: i64 = sys_lseek(fd, 0, FSX_SEEK_END)
4895 var unterminated: i64 = 0
4896 if sz > 0 {
4897 if sys_lseek(fd, sz - 1, FSX_SEEK_SET) == sz - 1 {
4898 let lb: *u8 = sys_mmap(16)
4899 if sys_read(fd, lb, 1) == 1 { if lb[0] != (FSX_NL as u8) { unterminated = 1 } }
4900 }
4901 }
4902 sys_close(fd)
4903 return unterminated
4904}
4905func fsx_append(path: *u8, body: *u8, blen: i64) -> i64 {
4906 if fsx_write_denied(path) == 1 {
4907 fsx_puts("NX-FS DENIED: append refused (secret/device-namespace/allowlist deny)\n" as *u8)
4908 return 0 - (2 as i64)
4909 }
4910 if blen <= 0 { return FSX_APP_EMPTY }
4911 if body[blen - 1] != (FSX_NL as u8) { return FSX_APP_NONL }
4912 let heal: i64 = fsx_tail_unterminated(path)
4913 let fd: i64 = sys_openat_append(path, FSX_MODE_RW)
4914 if fd < 0 { return 0 - (3 as i64) }
4915 sys_flock(fd, SYS_LOCK_EX)
4916 let total: i64 = blen + heal
4917 let buf: *u8 = sys_mmap(total + 1)
4918 var i: i64 = 0
4919 if heal == 1 { buf[0] = FSX_NL as u8; i = 1 }
4920 var j: i64 = 0
4921 while j < blen { buf[i] = body[j]; i = i + 1; j = j + 1 }
4922 var off: i64 = 0
4923 while off < total {
4924 let w: i64 = sys_write(fd, ((buf as i64 + off) as *u8), total - off)
4925 if w <= 0 { sys_flock(fd, SYS_LOCK_UN); sys_close(fd); return 0 - (3 as i64) }
4926 off = off + w
4927 }
4928 sys_fsync(fd)
4929 sys_flock(fd, SYS_LOCK_UN)
4930 sys_close(fd)
4931 return total
4932}
4933// ATOMIC full-file write: content lands via <path>.nxw<pid> + fsync + rename, so a reader NEVER sees a
4934// torn file and concurrent writers each land whole (last rename wins; pid suffix = no shared tmp).
4935// Returns bytes written; -2 DENIED; -3 io error (path too long / open / short write / rename).
4936func fsx_write(path: *u8, body: *u8, blen: i64) -> i64 {
4937 if fsx_write_denied(path) == 1 {
4938 fsx_puts("NX-FS DENIED: write refused (secret/device-namespace/allowlist deny)\n" as *u8)
4939 return 0 - (2 as i64)
4940 }
4941 let plen: i64 = vw_slen(path)
4942 if plen + FSX_TMP_ROOM >= FSX_PATH_CAP { return 0 - (3 as i64) }
4943 let tmp: *u8 = sys_mmap(FSX_PATH_CAP)
4944 var i: i64 = 0
4945 while i < plen { tmp[i] = path[i]; i = i + 1 }
4946 let suf: *u8 = ".nxw" as *u8
4947 var s: i64 = 0
4948 while suf[s] != (0 as u8) { tmp[i] = suf[s]; i = i + 1; s = s + 1 }
4949 var pid: i64 = osp_selfpid()
4950 if pid < 0 { pid = 0 }
4951 if pid == 0 { tmp[i] = FSX_ASCII_0 as u8; i = i + 1 } else {
4952 let ds: *u8 = sys_mmap(FSX_TMP_ROOM)
4953 var k: i64 = 0
4954 while pid > 0 { ds[k] = (FSX_ASCII_0 + (pid % FSX_DEC)) as u8; pid = pid / FSX_DEC; k = k + 1 }
4955 while k > 0 { tmp[i] = ds[k-1]; i = i + 1; k = k - 1 }
4956 }
4957 tmp[i] = 0 as u8
4958 let fd: i64 = sys_openat_wr(tmp, FSX_MODE_RW)
4959 if fd < 0 { return 0 - (3 as i64) }
4960 let saved: *NxFileWriteResult = sys_mmap(__size_of(NxFileWriteResult)) as *NxFileWriteResult
4961 if (saved as i64) < 0 { sys_close(fd); sys_unlinkat(tmp); return 0 - (3 as i64) }
4962 let write_rc: i64 = fio_write_sync_fd(fd, body, blen, saved)
4963 if write_rc < 0 {
4964 fsx_puts("NX-FS WRITE-FAILED stage="); fsx_puts(saved.stage)
4965 fsx_puts(" code="); fsx_putn(saved.code)
4966 fsx_puts(" written="); fsx_putn(saved.written)
4967 fsx_puts(" close_code="); fsx_putn(saved.close_code)
4968 fsx_puts(" path="); fsx_puts(path)
4969 fsx_puts(" publication=not-attempted\n")
4970 sys_munmap(saved as *u8, __size_of(NxFileWriteResult))
4971 sys_unlinkat(tmp)
4972 return 0 - (3 as i64)
4973 }
4974 sys_munmap(saved as *u8, __size_of(NxFileWriteResult))
4975 // PRESERVE the original file's mode across tmp+rename (debt eaten 2026-07-18: an edit of an
4976 // executable script used to land 0644 -- the exec bit vanished and the cron runner broke with
4977 // rc=126). st_mode = u32 at stat offset 24; keep the permission bits (low 12) only.
4978 let sb: *u8 = sys_mmap(160)
4979 if sys_fstatat(path, sb) == 0 {
4980 let m0: i64 = sb[24] as i64
4981 let m1: i64 = sb[25] as i64
4982 let om: i64 = (m0 + (m1 * 256)) & FSX_MAGIC_4095
4983 if om != FSX_MODE_RW { nx_chmod(tmp, om) }
4984 }
4985 // The same law at the last possible failure: if the rename cannot complete, the tmp is not a
4986 // partial result anyone wants -- it is litter wearing the shape of a real file. Take it with us.
4987 if sys_renameat(tmp, path) < 0 { sys_unlinkat(tmp); return 0 - (3 as i64) }
4988 return blen
4989}
4990// count non-overlapping occurrences of nee[0..nl) in hay[0..hn)
4991func fsx_count_occ(hay: *u8, hn: i64, nee: *u8, nl: i64) -> i64 {
4992 if nl <= 0 { return 0 }
4993 var c: i64 = 0
4994 var i: i64 = 0
4995 while i + nl <= hn {
4996 var m: i64 = 1
4997 var j: i64 = 0
4998 while j < nl { if hay[i+j] != nee[j] { m = 0; j = nl } else { j = j + 1 } }
4999 if m == 1 { c = c + 1; i = i + nl } else { i = i + 1 }
5000 }
5001 return c
5002}
5003// replace occurrences of nee with rep into out (allf=0: first only; 1: all). Returns new length; -1 overflow.
5004func fsx_replace(hay: *u8, hn: i64, nee: *u8, nl: i64, rep: *u8, rl: i64, out: *u8, ocap: i64, allf: i64) -> i64 {
5005 var o: i64 = 0
5006 var i: i64 = 0
5007 var used: i64 = 0
5008 while i < hn {
5009 var m: i64 = 0
5010 if i + nl <= hn { if nl > 0 {
5011 var ok: i64 = 1
5012 if allf == 0 { if used == 1 { ok = 0 } }
5013 if ok == 1 {
5014 m = 1
5015 var j: i64 = 0
5016 while j < nl { if hay[i+j] != nee[j] { m = 0; j = nl } else { j = j + 1 } }
5017 }
5018 } }
5019 if m == 1 {
5020 if o + rl > ocap { return 0 - 1 }
5021 var k: i64 = 0
5022 while k < rl { out[o] = rep[k]; o = o + 1; k = k + 1 }
5023 i = i + nl
5024 used = 1
5025 } else {
5026 if o + 1 > ocap { return 0 - 1 }
5027 out[o] = hay[i]
5028 o = o + 1
5029 i = i + 1
5030 }
5031 }
5032 return o
5033}
5034// EDIT: exact-string replace with the UNIQUENESS contract (the Claude-Edit SOTA semantic):
5035// 0 matches -> -6 NOMATCH (file untouched); >1 without allf -> -7 AMBIGUOUS (file untouched);
5036// otherwise replace (allf=1: every occurrence) and land ATOMICALLY via fsx_write.
5037// Returns new byte length; -1 absent; -2 DENIED; -3 io/overflow; -6 nomatch; -7 ambiguous.
5038func fsx_edit(path: *u8, olds: *u8, news: *u8, allf: i64) -> i64 {
5039 if fsx_write_denied(path) == 1 {
5040 fsx_puts("NX-FS DENIED: edit refused (secret/device-namespace/allowlist deny)\n" as *u8)
5041 return 0 - 2
5042 }
5043 let region: *NxFileReadRegion = sys_mmap(__size_of(NxFileReadRegion)) as *NxFileReadRegion
5044 if (region as i64) <= 0 { return 0 - 3 }
5045 fio_region_init(region)
5046 if fio_region_open(path, region) != 0 {
5047 sys_munmap(region as *u8, __size_of(NxFileReadRegion))
5048 return 0 - 1
5049 }
5050 let n: i64 = region.total
5051 if n <= 0 {
5052 fio_region_close(region)
5053 sys_munmap(region as *u8, __size_of(NxFileReadRegion))
5054 return 0 - 1
5055 }
5056 let buf: *u8 = sys_mmap(n)
5057 if (buf as i64) <= 0 {
5058 fio_region_close(region)
5059 sys_munmap(region as *u8, __size_of(NxFileReadRegion))
5060 return 0 - 3
5061 }
5062 let readn: i64 = fio_region_next(region, buf, n)
5063 sys_munmap(region as *u8, __size_of(NxFileReadRegion))
5064 if readn != n { sys_munmap(buf,n); return 0 - 3 }
5065 let ol: i64 = vw_slen(olds)
5066 let rl: i64 = vw_slen(news)
5067 let cnt: i64 = fsx_count_occ(buf,n,olds,ol)
5068 if cnt == 0 { sys_munmap(buf,n); return 0 - FSX_RC_NOMATCH }
5069 if cnt > 1 && allf == 0 { sys_munmap(buf,n); return 0 - FSX_RC_AMBIG }
5070 // Derive exact output extent from measured input and replacement count.
5071 // The numeric bound is the signed length representation, not a file-size policy.
5072 let delta: i64 = rl - ol
5073 if delta > 0 {
5074 if cnt > (9223372036854775807 - n) / delta {
5075 sys_munmap(buf,n); return 0 - 3
5076 }
5077 }
5078 let expected: i64 = n + cnt * delta
5079 var capacity: i64 = expected
5080 if capacity == 0 { capacity = 1 }
5081 let out: *u8 = sys_mmap(capacity)
5082 if (out as i64) <= 0 { sys_munmap(buf,n); return 0 - 3 }
5083 let nn: i64 = fsx_replace(buf,n,olds,ol,news,rl,out,capacity,allf)
5084 var result: i64 = 0 - 3
5085 if nn == expected { result = fsx_write(path,out,nn) }
5086 sys_munmap(out,capacity)
5087 sys_munmap(buf,n)
5088 return result
5089}
5090
5091// SELF-ANCHORED EDIT PREDICATE (pure, no I/O). Does the replacement CONTAIN its own anchor?
5092// UNIQUENESS IS TESTED AGAINST THE PRE-IMAGE; THE RETRY GUARANTEE IS A CLAIM ABOUT THE POST-IMAGE.
5093// They coincide ONLY when the replacement destroys its anchor. When `news` contains `olds` the anchor
5094// SURVIVES the apply and is STILL UNIQUE, so a retry returns OK whether or not the first call landed --
5095// the three-state table (OK=had-not-landed / NOMATCH=had-landed) collapses to ONE state and OK carries
5096// ZERO discriminating information.
5097// MEASURED 2026-09-04 over 12,806 edit calls in this laptop's transcripts: 8,308 true replaces, 4,343
5098// self-anchored (339 permil), 155 identity, sum reconciles. Seats re-issue the unsafe shape at 95 permil
5099// against a 99 permil control on the safe shape -- i.e. the retry doctrine is applied UNIFORMLY AND
5100// BLINDLY because nothing in the tool discriminated by shape. Three double-applies are confirmed in the
5101// record, plus the 2026-09-04 incident that produced two definitions of ba_confirmed and broke the gate
5102// that admits every build on this estate.
5103// The law was already banked on 2026-08-20 in nx_atomic_publish as CALLER advice keyed on a SELF-DECLARED
5104// kind=. A caller can get that declaration wrong, and one did. The primitive holds BOTH strings, so the
5105// kind is DERIVABLE rather than declarable -- and deriving it here is what makes writer and reader unable
5106// to disagree, instead of asking them to agree by discipline.
5107// Returns 1 self-anchored (retry UNSAFE) | 0 true replace (retry exact-safe).
5108// An empty anchor is NOT self-anchored: fsx_edit never reaches the apply with ol==0.
5109func fsx_edit_self_anchored(olds: *u8, news: *u8) -> i64 {
5110 let ol: i64 = vw_slen(olds)
5111 if ol == 0 { return 0 }
5112 if fsx_count_occ(news, vw_slen(news), olds, ol) > 0 { return 1 }
5113 return 0
5114}
5115
5116// ls (declared below the self-anchored-edit predicate): one entry per line "<t> <name>" (t: d=dir f=file l=link o=other; . and .. skipped).
5117// Returns entry count; -1 if the dir cannot be opened.
5118// PAGING (2026-08-05). The cap was always honest -- it declared total= and truncated=1 -- but an
5119// honest refusal is not access: knowledge/status/ holds 1027 entries, so 827 of them were simply
5120// UNREACHABLE through this tool, and a worker that listed it reported "queue empty" over a job that
5121// was sitting right there. u2605u2605u2605u2605u2605DECLARING A TRUNCATION IS NOT THE SAME AS OFFERING A WAY PAST IT --
5122// a loud cap with no next page is still a wall. `skip` is that way past.
5123// Contract preserved exactly (rule 19): fsx_ls(dir) keeps its old signature and behaviour.
5124func fsx_ls(dir: *u8) -> i64 { return fsx_ls_from(dir, 0) }
5125
5126func fsx_ls_from(dir: *u8, skip: i64) -> i64 {
5127 let fd: i64 = sys_openat_rd(dir)
5128 if fd < 0 { return fsx_fail(dir, fd) }
5129 let dbuf: *u8 = sys_mmap(FSX_DENT_BUF)
5130 var cnt: i64 = 0
5131 var shown: i64 = 0
5132 var run: i64 = 1
5133 while run == 1 {
5134 let n: i64 = sys_getdents64(fd, dbuf, FSX_DENT_BUF)
5135 if n <= 0 { run = 0 } else {
5136 var off: i64 = 0
5137 while off < n {
5138 let rec: *u8 = ((dbuf as i64 + off) as *u8)
5139 let reclen: i64 = dirent_reclen(rec)
5140 if reclen <= 0 { off = n } else {
5141 let name: *u8 = dirent_name(rec)
5142 // skip "." and ".."
5143 var isdot: i64 = 0
5144 if fsx_seq(name, "." as *u8) == 1 { isdot = 1 }
5145 if fsx_seq(name, ".." as *u8) == 1 { isdot = 1 }
5146 if isdot == 0 {
5147 if cnt >= skip { if shown < FSX_LS_CAP {
5148 let t: i64 = dirent_type(rec)
5149 if t == DT_DIR { fsx_puts("d " as *u8) } else {
5150 if t == DT_REG { fsx_puts("f " as *u8) } else {
5151 if t == DT_LNK { fsx_puts("l " as *u8) } else { fsx_puts("o " as *u8) } } }
5152 fsx_puts(name)
5153 fsx_puts("\n" as *u8)
5154 shown = shown + 1
5155 } }
5156 cnt = cnt + 1
5157 }
5158 off = off + reclen
5159 }
5160 }
5161 }
5162 }
5163 sys_close(fd)
5164 // SCALE-LAW: cap the emitted list but ALWAYS declare the true total; truncation is LOUD not silent
5165 fsx_puts("NX-FS-LS skip=" as *u8)
5166 fsx_putn(skip)
5167 fsx_puts(" shown=" as *u8)
5168 fsx_putn(shown)
5169 fsx_puts(" total=" as *u8)
5170 fsx_putn(cnt)
5171 // u26a0THE OLD PREDICATE (cnt > shown) BECOMES A LIE THE MOMENT skip EXISTS: the LAST page would
5172 // still report truncated=1 forever, so a caller paging until truncated=0 would never stop.
5173 // What actually remains is everything past the window just emitted.
5174 if cnt > skip + shown { fsx_puts(" truncated=1 (more remain -- next page: ls <dir> " as *u8); fsx_putn(skip + shown); fsx_puts(")\n" as *u8) } else { fsx_puts(" truncated=0\n" as *u8) }
5175 return cnt
5176}
5177
5178// ==== THE CLAIM-OR-OUT VERB (ES26, 2026-09-06) ====
5179// The most common ritual in the estate's action journal is two reads of the job lane -- the terminal marker
5180// (.claim) and then the output (.out): 120,106 adjacent pairs and 87,785 triples measured by nx_actlog steps.
5181// ONE call answers both. The marker decides the state and only a DONE marker earns the read of the output, so a
5182// running job never reads as dead, a never-claimed id never reads as running, and an empty output never reads as
5183// still working. States are NAMED, never guessed: a marker with no state token this reader knows is UNPARSED and
5184// printed verbatim as data. The id is digits only, so the verb cannot be aimed outside the directory it is given.
5185// fsx_job_at takes the directory so the gate drives it on a /tmp fixture; fsx_job is the production binding.
5186const FSX_JOB_DIR: *u8 = "_jobs/"
5187const FSX_JOB_PFX: *u8 = "job_"
5188const FSX_JOB_CLAIM: *u8 = ".claim"
5189const FSX_JOB_OUT: *u8 = ".out"
5190const FSX_JOB_IDMAX: i64 = 24 // a job id is an epoch-shaped integer; longer than this is not an id
5191const FSX_JOB_NOSUCH: i64 = 1 // no marker: the id was never claimed (unknown id, or the lane has not claimed it yet)
5192const FSX_JOB_RUNNING: i64 = 2 // marker reads state=CLAIMED
5193const FSX_JOB_DONE: i64 = 3 // marker reads state=DONE with bytes>0: the output was printed
5194const FSX_JOB_DONE_EMPTY: i64 = 4 // marker reads state=DONE with bytes=0: the tool produced NOTHING
5195const FSX_JOB_UNPARSED: i64 = 5 // marker present, no state token this reader knows: printed verbatim
5196const FSX_JOB_REFUSED: i64 = 6 // id is not digits-only
5197const FSX_JOB_OUT_ABSENT: i64 = 7 // marker says DONE with bytes>0 but the output file is unreadable
5198const FSX_RC_JOB_RUNNING: i64 = 8 // CLI exit for RUNNING, distinct from every other fs exit code
5199const FSX_ASCII_9: i64 = 57 // '9' (decimal parse upper bound)
5200// first offset of needle in buf[0..n), -1 when absent (flag-terminated compare, the cursor is never the sentinel)
5201func fsx_find(buf: *u8, n: i64, needle: *u8) -> i64 {
5202 var m: i64 = 0
5203 while needle[m] != (0 as u8) { m = m + 1 }
5204 if m == 0 { return 0 - 1 }
5205 var i: i64 = 0
5206 while i + m <= n {
5207 var j: i64 = 0
5208 var same: i64 = 1
5209 while j < m { if buf[i + j] != needle[j] { same = 0 } j = j + 1 }
5210 if same == 1 { return i }
5211 i = i + 1
5212 }
5213 return 0 - 1
5214}
5215// the integer right after `key` in buf[0..n); -1 when the key is absent or carries no digits
5216func fsx_kv_int(buf: *u8, n: i64, key: *u8) -> i64 {
5217 let at: i64 = fsx_find(buf, n, key)
5218 if at < 0 { return 0 - 1 }
5219 var kl: i64 = 0
5220 while key[kl] != (0 as u8) { kl = kl + 1 }
5221 var f: i64 = at + kl
5222 var v: i64 = 0
5223 var nd: i64 = 0
5224 var scan: i64 = 1
5225 while scan == 1 {
5226 if f >= n { scan = 0 } else {
5227 let c: i64 = buf[f] as i64
5228 if c < FSX_ASCII_0 { scan = 0 } else { if c > FSX_ASCII_9 { scan = 0 } else { v = v * (10 as i64) + (c - FSX_ASCII_0); nd = nd + 1; f = f + 1 } }
5229 }
5230 }
5231 if nd == 0 { return 0 - 1 }
5232 return v
5233}
5234func fsx_job_id_ok(id: *u8) -> i64 {
5235 var i: i64 = 0
5236 while id[i] != (0 as u8) {
5237 let c: i64 = id[i] as i64
5238 if c < FSX_ASCII_0 { return 0 }
5239 if c > FSX_ASCII_9 { return 0 }
5240 i = i + 1
5241 }
5242 if i == 0 { return 0 }
5243 if i > FSX_JOB_IDMAX { return 0 }
5244 return 1
5245}
5246// <dir><pfx><id><sfx> into out; returns the length
5247func fsx_job_path(dir: *u8, id: *u8, sfx: *u8, out: *u8) -> i64 {
5248 let pfx: *u8 = FSX_JOB_PFX
5249 var o: i64 = 0
5250 var i: i64 = 0
5251 while dir[i] != (0 as u8) { out[o] = dir[i]; o = o + 1; i = i + 1 }
5252 i = 0
5253 while pfx[i] != (0 as u8) { out[o] = pfx[i]; o = o + 1; i = i + 1 }
5254 i = 0
5255 while id[i] != (0 as u8) { out[o] = id[i]; o = o + 1; i = i + 1 }
5256 i = 0
5257 while sfx[i] != (0 as u8) { out[o] = sfx[i]; o = o + 1; i = i + 1 }
5258 out[o] = 0 as u8
5259 return o
5260}
5261// returns the FSX_JOB_* state; prints the marker verbatim and, on DONE with bytes>0, the output through fsx_read
5262// (truncation marked, deny-list inherited)
5263func fsx_job_at(dir: *u8, id: *u8) -> i64 {
5264 if fsx_job_id_ok(id) == 0 {
5265 fsx_puts("NX-FS-JOB REFUSED: the id must be digits only (a job number), got: " as *u8); fsx_puts(id); fsx_puts("\n" as *u8)
5266 return FSX_JOB_REFUSED
5267 }
5268 let cp: *u8 = sys_mmap(FSX_PATH_CAP)
5269 let op: *u8 = sys_mmap(FSX_PATH_CAP)
5270 fsx_job_path(dir, id, FSX_JOB_CLAIM, cp)
5271 fsx_job_path(dir, id, FSX_JOB_OUT, op)
5272 let cb: *u8 = sys_mmap(FSX_MAGIC_4095 + 1)
5273 let cn: i64 = vw_read(cp, cb, FSX_MAGIC_4095)
5274 fsx_puts("NX-FS-JOB id=" as *u8); fsx_puts(id)
5275 if cn <= 0 {
5276 fsx_puts(" NOSUCH: no marker at " as *u8); fsx_puts(cp)
5277 fsx_puts(" -- the id was never claimed by the lane (unknown id, or not claimed yet); a claimed job carries state=CLAIMED\n" as *u8)
5278 return FSX_JOB_NOSUCH
5279 }
5280 fsx_puts(" marker=" as *u8)
5281 var cl: i64 = cn
5282 var strip: i64 = 1
5283 while strip == 1 { if cl <= 0 { strip = 0 } else { if cb[cl - 1] == (FSX_NL as u8) { cl = cl - 1 } else { strip = 0 } } }
5284 sys_write(1, cb, cl)
5285 if fsx_find(cb, cn, "state=DONE" as *u8) >= 0 {
5286 let b: i64 = fsx_kv_int(cb, cn, "bytes=" as *u8)
5287 if b == 0 {
5288 fsx_puts(" DONE-EMPTY: the tool produced NOTHING (bytes=0); it is not still working\n" as *u8)
5289 return FSX_JOB_DONE_EMPTY
5290 }
5291 fsx_puts(" DONE: output follows\n" as *u8)
5292 let r: i64 = fsx_read(op, 0)
5293 if r > 0 { return FSX_JOB_DONE }
5294 return FSX_JOB_OUT_ABSENT
5295 }
5296 if fsx_find(cb, cn, "state=CLAIMED" as *u8) >= 0 {
5297 fsx_puts(" RUNNING: claimed, no terminal state yet -- the lane rewrites this marker atomically when the job ends\n" as *u8)
5298 return FSX_JOB_RUNNING
5299 }
5300 fsx_puts(" UNPARSED: no state token this reader knows -- the marker above is data, decide from it\n" as *u8)
5301 return FSX_JOB_UNPARSED
5302}
5303func fsx_job(id: *u8) -> i64 { return fsx_job_at(FSX_JOB_DIR, id) }
5304
5305// Exclusive artifact creation for the current Linux x86-64 host backend.
5306// Complete bytes are fsynced before RENAME_NOREPLACE. Unsupported filesystems fail closed.
5307// This is not a portable-ISA claim; the rename ABI matches the existing host syscall seam.
5308
5309const FXC_OPEN_EXCLUSIVE: i64 = 0xc1 // O_WRONLY | O_CREAT | O_EXCL
5310const FXC_RENAMEAT2_X86: i64 = 316
5311const FXC_RENAME_NOREPLACE: i64 = 1
5312const FXC_EXISTS: i64 = 0 - 17
5313const FXC_IO: i64 = 0 - 3
5314func fxc_create(path: *u8, body: *u8, n: i64) -> i64 {
5315 if fsx_write_denied(path) == 1 { return 0 - 2 }
5316 let plen: i64 = vw_slen(path)
5317 if plen + FSX_TMP_ROOM >= FSX_PATH_CAP { return FXC_IO }
5318 let tmp: *u8 = sys_mmap(FSX_PATH_CAP)
5319 var i: i64 = 0
5320 while i < plen { tmp[i] = path[i]; i = i + 1 }
5321 let suffix: *u8 = ".nxc" as *u8
5322 var j: i64 = 0
5323 while j < 4 { tmp[i] = suffix[j]; i = i+1; j = j+1 }
5324 i = nxi_buf(tmp,i,osp_selfpid()); tmp[i] = 0 as u8
5325 let fd: i64 = __syscall(SYS_OPENAT,AT_FDCWD,tmp,FXC_OPEN_EXCLUSIVE,MODE_0644,0,0)
5326 if fd < 0 { return FXC_IO }
5327 var off: i64 = 0
5328 while off < n {
5329 let w: i64 = sys_write(fd,((body as i64)+off) as *u8,n-off)
5330 if w <= 0 { sys_close(fd);sys_unlinkat(tmp);return FXC_IO }
5331 off = off+w
5332 }
5333 let sync: i64 = sys_fsync(fd)
5334 sys_close(fd)
5335 if sync < 0 { sys_unlinkat(tmp);return FXC_IO }
5336 let installed: i64 = __syscall(FXC_RENAMEAT2_X86,AT_FDCWD,tmp,AT_FDCWD,path,FXC_RENAME_NOREPLACE,0)
5337 if installed != 0 {
5338 // This process created tmp with O_EXCL; only its own uncommitted scratch is removed.
5339 sys_unlinkat(tmp)
5340 return installed
5341 }
5342 return n
5343}
5344
5345
5346
5347
5348const GPA_HEADER_BYTES: i64 = 8
5349
5350struct GpaWasmCursor {
5351 data: *u8,
5352 size: i64,
5353 pos: i64,
5354}
5355struct GpaMemory {
5356 minimum: i64,
5357 maximum: i64,
5358 count: i64,
5359}
5360// WebAssembly u32 LEB128: at most five bytes, with only four payload bits in the last.
5361func gpa_u32(c: *GpaWasmCursor) -> i64 {
5362 var value: i64 = 0
5363 var shift: i64 = 0
5364 while shift < 35 {
5365 if c.pos >= c.size { return -1 }
5366 let b: i64 = c.data[c.pos] as i64
5367 c.pos = c.pos+1
5368 if shift == 28 { if b > 15 { return -1 } }
5369 value = value | ((b & 127) << shift)
5370 if (b & 128) == 0 { return value }
5371 shift = shift+7
5372 }
5373 return -1
5374}
5375func gpa_wasm_header(data: *u8,n: i64) -> i64 {
5376 if n < GPA_HEADER_BYTES { return 0 }
5377 let header: *u8 = "\x00asm\x01\x00\x00\x00" as *u8
5378 return gpa_same(data,GPA_HEADER_BYTES,header,GPA_HEADER_BYTES)
5379}
5380func gpa_wasm_name(c: *GpaWasmCursor,name: *u8) -> i64 {
5381 let n: i64 = gpa_u32(c)
5382 if n < 0 || n > c.size-c.pos { return 0 }
5383 let ok: i64 = gpa_same((c.data as i64+c.pos) as *u8,n,name,vw_slen(name))
5384 c.pos = c.pos+n
5385 return ok
5386}
5387// This packager supports the compiler's one-memory, no-other-import twin contract.
5388// Other valid Wasm layouts require a separate supported contract, never silent guessing.
5389func gpa_memory_section(data: *u8,n: i64,shared: i64,m: *GpaMemory) -> i64 {
5390 let c: *GpaWasmCursor = sys_mmap(__size_of(GpaWasmCursor)) as *GpaWasmCursor
5391 c.data=data; c.size=n; c.pos=0
5392 var ok: i64 = 1
5393 if gpa_u32(c) != 1 { ok=0 }
5394 if shared == 1 {
5395 if gpa_wasm_name(c,"env") != 1 { ok=0 }
5396 if gpa_wasm_name(c,"memory") != 1 { ok=0 }
5397 if gpa_u32(c) != 2 { ok=0 }
5398 }
5399 let flags: i64 = gpa_u32(c)
5400 if shared == 1 { if flags != 3 { ok=0 } } else { if flags != 0 && flags != 1 { ok=0 } }
5401 let minimum: i64 = gpa_u32(c)
5402 var maximum: i64 = minimum
5403 if (flags & 1) == 1 { maximum=gpa_u32(c) }
5404 // 2^16 pages is the wasm32 address-space ceiling, not a workload budget.
5405 if minimum <= 0 || maximum < minimum || maximum > 65536 { ok=0 }
5406 if c.pos != n { ok=0 }
5407 if m.count != 0 { ok=0 }
5408 if ok == 1 { m.minimum=minimum; m.maximum=maximum; m.count=1 }
5409 sys_munmap(c as *u8,__size_of(GpaWasmCursor))
5410 return ok
5411}
5412func gpa_body_section(c: *GpaWa