code wiki / (root) / nx_fsops_lib_t77.nx

nx_fsops_lib_t77.nx

buildroot/runtime/nx_fsops_lib_t77.nx

56532 B1162 linesdepth 6pulls 10 transitivereach 3 importersview sourcekind librarytopic fsops
docsdependenciesstructsconstsfunctions

about

nx_fsops_lib.nx -- CONSOLIDATED filesystem tool (MCP name: nx_fs, tool #4 of the 15), LIBRARY half. (Source is named nx_fsops because nx_fs.nx is the safety-enveloped file-I/O STDLIB -- a different thing.) READ-ONLY first increment: `read` (bounded file read) + `ls` (typed dir listing). Retires ssh-cat for remote reads per rule 27 (api-first, no shell plumbing). BOUNDARY DEFENSE (rule 12 -- MCP callers are EXTERNAL input): `read` REFUSES any path that matches the secret DENY-LIST: compiled-in default needles (secret/key/token/passw/.pem, matched case-insensitively against the WHOLE path) plus data-driven extras from fs_read_deny.conf (one lowercase needle per line, CWD-relative -- rule 11: policy in data, not code). The tools-api runs where key material lives; an arbitrary-read tool that could return opaque_keys.bin or tools_cap_secret.key would convert a read-cap into a key-theft primitive. Over-blocking is the SAFE failure direction for v1. WRITE/EDIT increment (2026-07-16): fsx_write (ATOMIC tmp+fsync+rename) + fsx_edit (exact-string replace with the Claude-Edit UNIQUENESS contract). Exposed as the SEPARATE tools-api name `nx_fs_write` (its own cap class per knowledge/mcp/exposure_policy.txt: read=broad, write=cap) -- the `nx_fs` name stays read-only. The write DENY is a superset of the read deny (never clobber key material) PLUS the OS device/kernel/ firmware namespace via the nx_os_fs seam (rule 26 never-brick BY CONSTRUCTION -- not config-disableable) PLUS the tool-registry escalation surface ("allowlist") PLUS data-driven extras (fs_write_deny.conf). license_tier: ORIGINAL

dependencies 6 imports · 3 importers

nx_syscalls.nx nx_srcfresh.nx nx_itoa_lib.nx nx_vsz_watchdog_core.nx nx_os_fs.nx nx_os_proc.nx nx_fsops_lib_t77.nx nx_fsops_conditional_gate_t77.nx nx_fsops_outline_t77.nx nx_fsops_t77.nx

imports: nx_syscalls.nxnx_srcfresh.nxnx_itoa_lib.nxnx_vsz_watchdog_core.nxnx_os_fs.nxnx_os_proc.nx

imported by: nx_fsops_conditional_gate_t77.nxnx_fsops_outline_t77.nxnx_fsops_t77.nx

structs

none

consts

25const FSX_MAGIC_4095: i64 = 4095
27const FSX_READ_CAP: i64 = 1048576 // max bytes returned by `read` (truncation is MARKED, never silent)
28const FSX_DENY_CAP: i64 = 8192 // fs_read_deny.conf read cap
29const FSX_PATH_CAP: i64 = 1024 // lowercased path work buffer
30const FSX_DENT_BUF: i64 = 65536 // getdents64 batch buffer (matches the proven vsz/heal sizing)
31const FSX_LS_CAP: i64 = 200 // scale-law: max ls entries EMITTED; true total ALWAYS declared (65KB-dump fix)
32const FSX_RC_ABSENT: i64 = 3 // exit: path absent/unreadable (mirrors nx_fileop's exists convention)
33const FSX_RC_DENIED: i64 = 5 // exit: deny-list refused the read
34const FSX_UPPER_A: i64 = 65 // 'A' (ASCII lowercasing)
35const FSX_UPPER_Z: i64 = 90 // 'Z'
36const FSX_CASE_OFF: i64 = 32 // 'a' - 'A'
37const FSX_ASCII_0: i64 = 48 // '0' (decimal print)
122const FSX_SNIFF_CAP: i64 = 4096
271const FSX_SEEK_END: i64 = 2 // lseek whence: EOF offset = size, WITHOUT reading a single byte
358const FSX_LINES_SCAN: i64 = 1048576 // line-addressing scan window (matches the proven read cap)
359const FSX_LINES_MAXOUT: i64 = 262144 // max bytes emitted by one `lines` call (transport-friendly)
360const FSX_LINES_DEFN: i64 = 40 // default line count when the caller omits it
361const FSX_LINES_MAXN: i64 = 400 // max lines per call
431const FSX_MODE_RW: i64 = MODE_0644 // 0644 -- the ecosystem's file-create mode idiom
432const FSX_DEC: i64 = 10 // decimal base (pid rendering in the tmp suffix)
433const FSX_EDIT_OUT: i64 = 2097152 // edit output buffer (2x read cap: bounded replacement growth)
434const FSX_TMP_ROOM: i64 = 32 // reserved room for ".nxw" + pid digits + NUL in the tmp name
435const FSX_RC_IO: i64 = 4 // exit: io failure (open/short-write/rename)
436const FSX_RC_NOMATCH: i64 = 6 // exit: edit found 0 occurrences (file UNCHANGED)
437const FSX_RC_AMBIG: i64 = 7 // exit: edit found >1 occurrences without `all` (file UNCHANGED)
550const FSX_NL: i64 = 10 // '\n' -- the row terminator this verb requires and heals
551const FSX_APP_EMPTY: i64 = 0 - 4 // append refused: nothing to append
552const FSX_APP_NONL: i64 = 0 - 5 // append refused: body does not end in a newline
553const FSX_SEEK_SET: i64 = 0 // lseek whence: absolute offset (the tail probe)
819const FSX_JOB_DIR: *u8 = "_jobs/"
820const FSX_JOB_PFX: *u8 = "job_"
821const FSX_JOB_CLAIM: *u8 = ".claim"
822const FSX_JOB_OUT: *u8 = ".out"
823const FSX_JOB_IDMAX: i64 = 24 // a job id is an epoch-shaped integer; longer than this is not an id
824const FSX_JOB_NOSUCH: i64 = 1 // no marker: the id was never claimed (unknown id, or the lane has not claimed it yet)
825const FSX_JOB_RUNNING: i64 = 2 // marker reads state=CLAIMED
826const FSX_JOB_DONE: i64 = 3 // marker reads state=DONE with bytes>0: the output was printed
827const FSX_JOB_DONE_EMPTY: i64 = 4 // marker reads state=DONE with bytes=0: the tool produced NOTHING
828const FSX_JOB_UNPARSED: i64 = 5 // marker present, no state token this reader knows: printed verbatim
829const FSX_JOB_REFUSED: i64 = 6 // id is not digits-only
830const FSX_JOB_OUT_ABSENT: i64 = 7 // marker says DONE with bytes>0 but the output file is unreadable
831const FSX_RC_JOB_RUNNING: i64 = 8 // CLI exit for RUNNING, distinct from every other fs exit code
832const FSX_ASCII_9: i64 = 57 // '9' (decimal parse upper bound)
940const FSX_CREAD_MAX: i64 = 32768
941const FSX_CREAD_META: i64 = 80
942const FSX_CREAD_SIZE: i64 = 0
943const FSX_CREAD_SCANNED: i64 = 1
944const FSX_CREAD_KEPT: i64 = 2
945const FSX_CREAD_OFFSET: i64 = 3
946const FSX_CREAD_BUDGET: i64 = 4
947const FSX_CREAD_ERROR: i64 = 5
948const FSX_CREAD_CALLS: i64 = 6
949const FSX_CREAD_CHANGED: i64 = 2
950const FSX_CREAD_SAME: i64 = 1
951const FSX_CREAD_ARGUMENT: i64 = 0 - 3
952const FSX_CREAD_IO: i64 = 0 - 4
953const FSX_CREAD_MOVED: i64 = 0 - 5
954const FSX_CREAD_DECIMAL: i64 = 10
955const FSX_CREAD_HEX: i64 = 64
956const FSX_CREAD_DIGEST: i64 = 32
957const FSX_CREAD_HEXBUF: i64 = 80
1034const FSX_CREAD_EINTR:i64=4
1035const FSX_CREAD_WRITTEN:i64=7
1036const FSX_CREAD_WRITE_ERROR:i64=8
1037const FSX_CREAD_WRITE_CALLS:i64=9

functions

39func 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 }
called by 16: fsx_failfsx_sizefsx_readfsx_read_atfsx_read_linesfsx_tail+10 calls 1: sys_write
44func fsx_putn(v: i64) -> i64 { nxi_out(v); return 0 }
called by 10: fsx_failfsx_sizefsx_readfsx_read_atfsx_read_linesfsx_tail+4 calls 1: nxi_out
46func fsx_lower(s: *u8, out: *u8, cap: i64) -> i64
called by 2: fsx_deniedfsx_write_denied
59func 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 }
called by 5: cg_scanfsx_cas_okfsx_ls_fromfsx_cmappedmain
70func fsx_cas_val(tok: *u8) -> *u8
called by 1: fsx_cas_ok
78func fsx_cas_ok(cur: i64, tok: *u8) -> i64
calls 2: fsx_cas_valfsx_seq
94func fsx_deny_hit(lp: *u8, ln: i64, needle: *u8) -> i64
called by 3: fsx_conf_denyfsx_deniedfsx_write_denied
101func fsx_conf_deny(lp: *u8, ln: i64, conf: *u8) -> i64
called by 2: fsx_deniedfsx_write_denied calls 2: sys_mmapfsx_deny_hit
124func fsx_isalnum(c: i64) -> i64
called by 1: fsx_word_has
131func fsx_ends_with(lp: *u8, ln: i64, suf: *u8) -> i64
called by 2: fsx_basename_isfsx_denied
143func fsx_basename_is(lp: *u8, ln: i64, name: *u8) -> i64
called by 1: fsx_denied calls 1: fsx_ends_with
157func fsx_word_has(lp: *u8, ln: i64, w: *u8) -> i64
calls 1: fsx_isalnum
182func fsx_content_secret(path: *u8) -> i64
called by 1: fsx_denied calls 4: sys_openat_rdsys_mmapsys_readsys_close
214func fsx_denied(path: *u8) -> i64
called by 9: fsx_sizefsx_readfsx_read_atfsx_read_linesfsx_tailfsx_write_denied+3 calls 7: sys_mmapfsx_lowerfsx_ends_withfsx_basename_isfsx_deny_hitfsx_content_secret+1
258func fsx_fail(path: *u8, rc: i64) -> i64
called by 5: fsx_readfsx_read_atfsx_read_linesfsx_tailfsx_ls_from calls 3: sys_closefsx_putsfsx_putn
286func fsx_size(path: *u8) -> i64
called by 1: main calls 6: fsx_deniedfsx_putssys_openat_rdsys_lseeksys_closefsx_putn
310func fsx_read(path: *u8, cap: i64) -> i64
called by 2: fsx_job_atmain calls 7: fsx_deniedfsx_putssys_mmapfsx_failsys_openat_rdsys_write+1
332func fsx_read_at(path: *u8, cap: i64, off: i64) -> i64
called by 1: main calls 10: fsx_deniedfsx_putssys_openat_rdfsx_failsys_lseeksys_close+4
369func fsx_read_lines(path: *u8, start: i64, count: i64) -> i64
called by 1: main calls 7: fsx_deniedfsx_putssys_mmapfsx_failsys_openat_rdfsx_putn+1
450func fsx_tail(path: *u8, count: i64) -> i64
called by 1: main calls 10: fsx_deniedfsx_putssys_openat_rdfsx_failsys_lseeksys_close+4
530func fsx_write_denied(path: *u8) -> i64
called by 3: fsx_appendfsx_writefsx_edit calls 6: fsx_deniedosf_write_forbiddensys_mmapfsx_lowerfsx_deny_hitfsx_conf_deny
555func fsx_tail_unterminated(path: *u8) -> i64
called by 1: fsx_append calls 5: sys_openat_rdsys_lseeksys_mmapsys_readsys_close
569func fsx_append(path: *u8, body: *u8, blen: i64) -> i64
calls 9: fsx_write_deniedfsx_putsfsx_tail_unterminatedsys_openat_appendsys_flocksys_mmap+3
600func fsx_write(path: *u8, body: *u8, blen: i64) -> i64
called by 1: fsx_edit calls 12: fsx_write_deniedfsx_putssys_mmaposp_selfpidsys_openat_wrsys_write+6
656func fsx_count_occ(hay: *u8, hn: i64, nee: *u8, nl: i64) -> i64
called by 2: fsx_editfsx_edit_self_anchored
669func fsx_replace(hay: *u8, hn: i64, nee: *u8, nl: i64, rep: *u8, rl: i64, out: *u8, ocap: i64, allf: i64) -> i64
called by 1: fsx_edit
703func fsx_edit(path: *u8, olds: *u8, news: *u8, allf: i64) -> i64
calls 6: fsx_write_deniedfsx_putssys_mmapfsx_count_occfsx_replacefsx_write
742func fsx_edit_self_anchored(olds: *u8, news: *u8) -> i64
calls 1: fsx_count_occ
757func fsx_ls(dir: *u8) -> i64 { return fsx_ls_from(dir, 0) }
calls 1: fsx_ls_from
759func fsx_ls_from(dir: *u8, skip: i64) -> i64
called by 2: fsx_lsmain calls 11: sys_openat_rdfsx_failsys_mmapsys_getdents64dirent_reclendirent_name+5
834func fsx_find(buf: *u8, n: i64, needle: *u8) -> i64
called by 2: fsx_kv_intfsx_job_at
849func fsx_kv_int(buf: *u8, n: i64, key: *u8) -> i64
called by 1: fsx_job_at calls 1: fsx_find
867func fsx_job_id_ok(id: *u8) -> i64
called by 1: fsx_job_at
880func fsx_job_path(dir: *u8, id: *u8, sfx: *u8, out: *u8) -> i64
called by 1: fsx_job_at
896func fsx_job_at(dir: *u8, id: *u8) -> i64
called by 1: fsx_job calls 8: fsx_job_id_okfsx_putssys_mmapfsx_job_pathsys_writefsx_find+2
936func fsx_job(id: *u8) -> i64 { return fsx_job_at(FSX_JOB_DIR, id) }
called by 1: main calls 1: fsx_job_at
959func fsx_cdecimal(s:*u8)->i64
called by 2: mainmain
971func fsx_chex_ok(s:*u8)->i64
called by 1: fsx_read_if_changed
985func fsx_cpath_ok(s:*u8)->i64
called by 1: fsx_read_if_changed
991func fsx_cpath_hex(s:*u8)->i64
called by 1: fsx_cmapped calls 1: sys_write
1003func fsx_cscan(fd:i64,m:*i64,block:*u8,preview:*u8,digest:*u8,c:*Sha256)->i64
called by 2: cg_scanfsx_cmapped calls 1: sys_read
1039func fsx_cwrite(fd:i64,buf:*u8,n:i64,m:*i64)->i64
called by 2: cg_outputfsx_cmapped calls 1: sys_write
1050func fsx_cworkspace_bytes(budget:i64)->i64
called by 3: cg_scanfsx_cmappedfsx_read_if_changed
1054func fsx_cmapped(path:*u8,expected:*u8,budget:i64,offset:i64,mapping:i64)->i64
called by 2: mainfsx_read_if_changed calls 15: fsx_putsfsx_cworkspace_bytessys_munmapsys_fstatatsys_openat_rdsys_lseek+9
1151func fsx_read_if_changed(path:*u8,expected:*u8,budget:i64,offset:i64)->i64
called by 2: mainmain calls 7: fsx_cpath_okfsx_chex_okfsx_putsfsx_deniedsys_mmap_sharedfsx_cworkspace_bytes+1