code wiki / (root) / nx_fsops_write.nx

nx_fsops_write.nx

buildroot/runtime/nx_fsops_write.nx

36676 B605 linesdepth 7pulls 12 transitivereach 2 importersview sourcekind tooltopic fsops
docsdependenciesstructsconstsfunctions

about

nx_fsops_write.nx -- WRITE-CLASS CLI of the consolidated fs tool (tools-api name: nx_fs_write). 2026-07-30: `write` is now COMPARE-AND-SWAP gated (seq1379) -- see the block above fsw_usage. Deliberately a SEPARATE binary from the read-only `nx_fs`: the exposure policy (knowledge/mcp/ exposure_policy.txt) grades reads broad and writes cap-gated, so the two live under different capability grants. One shared library (nx_fsops_lib) -- no logic duplicated. write <path> <content> -> ATOMIC full-file write (tmp+fsync+rename) edit <path> <old> <new> [all] -> exact-string replace, UNIQUENESS contract (Claude-Edit semantic) append <path> <row> -> APPEND-ONLY (one O_APPEND write under flock; row must end in '\n'): the journal/board verb -- no anchor, no expect token, nothing rewritten exit: 0 ok | 2 usage | 3 absent | 4 io | 5 DENIED | 6 NOMATCH | 7 AMBIGUOUS (surfaced in MCP _meta) DENY BY CONSTRUCTION (rule 26 + 12): secret material, OS device/firmware namespace (nx_os_fs seam), the tool allowlist, + fs_write_deny.conf extras. license_tier: ORIGINAL

dependencies 2 imports · 2 importers

nx_fsops_lib.nx nx_apistack_idempotency.nx nx_fsops_write.nx nx_writer_bound_run_t293.nx nx_writer_payload_gate_t293.nx

imports: nx_fsops_lib.nxnx_apistack_idempotency.nx

imported by: nx_writer_bound_run_t293.nxnx_writer_payload_gate_t293.nx

call flow from main pre-order; caps 40 nodes / depth 6 declared; ↻ = already shown

main fsw_usage fsx_puts sys_write fsx_seq fsw_dispatch fsw_usage ↻ fsx_seq ↻ fsw_keyarg fsw_prefix fsw_execute fsw_usage ↻ fsx_seq ↻ fsw_prefix ↻ fsw_argval fsw_cur_size fsw_expect_val fsw_hex_val fsw_content_hash fsw_atoi fsx_puts ↻ fsx_putn nxi_out nxi_fd sys_mmap ccz_cat_num sys_write ↻ sys_munmap fsw_print_hash fsw_hex_of fsw_content_hash ↻ fsx_puts ↻ fsw_mkparents fsx_write_denied fsx_denied sys_mmap ↻ fsx_lower fsx_ends_with fsx_basename_is fsx_deny_hit

structs

none

consts

16const FSW_USAGE_RC: i64 = 2
17const FSW_ARG_VERB: i64 = 1 // argv slot of the verb
18const FSW_ARG_PATH: i64 = 2 // argv slot of the path
19const FSW_ARG_A: i64 = 3 // write: content | edit: old-string
20const FSW_ARG_B: i64 = 4 // edit: new-string
21const FSW_ARG_ALL: i64 = 5 // edit: optional literal "all"
22const FSW_ARGC_WRITE: i64 = 4 // write path content
23const FSW_ARGC_EDIT: i64 = 5 // edit path old new
24const FSW_ARGC_EDITALL: i64 = 6 // edit path old new all
36const FSW_RC_CLOBBER: i64 = 8 // distinct from ABSENT/DENIED/IO/NOMATCH/AMBIG so callers can branch on it
37const FSW_ARG_EXPECT: i64 = 4 // write: optional expect token
38const FSW_ARGC_WRITE_EXPECT: i64 = 5
81const FSW_FNV_OFF: i64 = 0xcbf29ce484222325
82const FSW_FNV_PRIME: i64 = 0x100000001b3
151const FSW_IDEM_LEDGER: *u8 = "knowledge/status/fswrite_idem.jrnl" as *u8 // CWD-relative like every status file
152const FSW_IDEM_RESULT_CAP: i64 = 1024
153const FSW_KEY_MIN_CH: i64 = 33 // printable ASCII, no space: a key with a TAB or newline would corrupt the ledger row
154const FSW_KEY_MAX_CH: i64 = 126
192const FSW_REQUEST_FIELDS:i64=8
193const FSW_LENGTH_BYTES:i64=8
194const FSW_REQUEST_HASH_BYTES:i64=32
195const FSW_REQUEST_HEX_BYTES:i64=64
196const FSW_RECONCILE_RC:i64=9
197const FSW_RECEIPT_RC:i64=10
320const FSW_DIR_MODE: i64 = 0x1ed // 0755 on any parent this creates -- same mode the rest of the tree uses
321const FSW_RC_DENIED_SENTINEL: i64 = 2 // fsx_write's DENIED return; it prints its own reason, we must not double-report

functions

54func fsw_argval(s: *u8) -> *u8
called by 2: fsw_request_hashfsw_execute
64func fsw_cur_size(path: *u8) -> i64
called by 2: fsw_record_boundfsw_execute
83func fsw_content_hash(path: *u8) -> i64
called by 3: fsw_print_hashfsw_expect_valfsw_record_bound
93func fsw_hex_of(v: i64, out: *u8) -> i64
called by 2: fsw_print_hashfsw_record_bound
100func fsw_hex_val(s: *u8) -> i64
called by 1: fsw_expect_val
120func fsw_print_hash(path: *u8) -> i64
called by 1: fsw_execute calls 3: fsw_hex_offsw_content_hashfsx_puts
126func fsw_expect_val(ex: *u8, path: *u8, cur: i64) -> i64
called by 1: fsw_execute calls 3: fsw_hex_valfsw_content_hashfsw_atoi
133func fsw_atoi(s: *u8) -> i64
called by 1: fsw_expect_val
155func fsw_prefix(s: *u8, p: *u8) -> i64 { var i: i64 = 0; while p[i] != (0 as u8) { if s[i] != p[i] { return 0 } i = i + 1 } return 1 }
called by 3: fsw_keyargfsw_request_hashfsw_execute
156func fsw_cat(d: *u8, o: i64, s: *u8) -> i64 { var i: i64 = 0; var oo: i64 = o; while s[i] != (0 as u8) { d[oo] = s[i]; oo = oo + 1; i = i + 1 } d[oo] = 0 as u8; return oo }
called by 1: fsw_record_bound
157func fsw_catn(d: *u8, o: i64, v: i64) -> i64
170func fsw_keyarg(argc: i64, argv: *i64, from: i64) -> *u8
called by 1: fsw_dispatch calls 1: fsw_prefix
179func fsw_key_ok(key: *u8) -> i64
called by 1: fsw_dispatch
198func fsw_request_hash(argc:i64,argv:*i64,hex:*u8)->i64
called by 1: fsw_dispatch calls 3: fsx_seqfsw_argvalfsw_prefix
245func fsw_evidence_decide(key:*u8,hex:*u8)->i64
called by 1: fsw_dispatch calls 3: id_read_evidencefsx_putsid_evidence_close
272func fsw_record_bound(key:*u8,hex:*u8,verb:*u8,path:*u8)->i64
called by 1: fsw_dispatch calls 5: fsw_catfsw_cur_sizefsw_hex_offsw_content_hashid_record
288func fsw_dispatch(argc:i64,argv:*i64)->i64
called by 1: main calls 9: fsw_usagefsx_seqfsw_keyargfsw_executefsw_key_okfsx_puts+3
315func fsw_usage() -> i64
called by 3: fsw_dispatchmainfsw_execute calls 1: fsx_puts
333func fsw_mkparents(path: *u8) -> i64
called by 1: fsw_execute calls 1: fsx_write_denied
358func fsw_rc(r: i64) -> i64
called by 1: fsw_execute
371func fsw_payload_failure(path: *u8, stage: *u8, raw: i64, code: i64, next: *u8, status: *i64) -> *u8
called by 2: fsw_load_textfsw_load_region_text calls 2: fsx_putsfsx_putn
381func fsw_load_text(path:*u8,status:*i64)->*u8
called by 1: main calls 3: fsx_deniedfsw_payload_failurefsw_load_region_text
396func fsw_load_region_text(path:*u8,region:*NxFileReadRegion,status:*i64)->*u8
called by 1: fsw_load_text calls 1: fsw_payload_failure
433func main(argc:i64,argv:*i64)->i64
calls 5: fsw_usagefsx_seqfsw_dispatchfsx_putsfsw_load_text
463func fsw_execute(argc: i64, argv: *i64) -> i64
called by 1: fsw_dispatch calls 15: fsw_usagefsx_seqfsw_prefixfsw_argvalfsw_cur_sizefsw_expect_val+9