nx_fsops.nx

nx_fsops.nx -- CLI half of the consolidated filesystem tool (MCP name: nx_fs, tool #4 of the 15). (Source named nx_fsops because nx_fs.nx is the file-I/O STDLIB.) READ-ONLY increment: read <path> [maxbytes] [offset] -> bytes to stdout (truncation MARKED); DENY-LIST refuses secrets lines <path> <start> [count] -> LINE-ADDRESSED window + declared envelope; composes with grep's file:LINE output (the pair that byte-offset reads could not do) tail <path> [count] -> the LAST <count> lines, answered from the file's own END in one call, with a declared envelope (total_bytes, window_lines, last_line_terminated). Built 2026-09-03 after a `lines` window chosen by hand was published as the end of a log while its envelope said next=212. A WINDOW READ IS NOT A TAIL READ. outline <path> -> ~2KB STRUCTURAL map (declaration/section lines) instead of dumping a 50KB file; pair with `lines <path> <L> <count>` to pull the exact body size <path> -> EXACT byte size in ONE call. This is the tail primitive: size, then read <path> <n> <size-n>. Without it a caller hunting the end of a log binary-searches offsets blind -- measured 2026-08-14, eight wasted calls on a 2,508,190-byte log whose size this verb returns immediately. mtime <path> -> mtime_sec/mtime_ns/now_sec/age_sec in ONE line (FUTURE-STAMPED if age<0); implemented since 2026-08-07 and absent from this header until 2026-09-03 -- the exact dark-verb class the paragraph below warns about ls <dir> [skip] -> "<t> <name>" per entry (d/f/l/o); skip makes a dir past FSX_LS_CAP reachable job <id> -> THE CLAIM-OR-OUT VERB (ES26, 2026-09-06): ONE call reads the job's terminal marker (_jobs/job_<id>.claim) and, only when it says DONE, the output (.out). States NAMED: NOSUCH (exit 3) / RUNNING (exit 8) / DONE / DONE-EMPTY / UNPARSED (exit 0) / REFUSED (exit 2, the id must be digits). The estate's most common two-step ritual -- marker then output, 120,106 adjacent pairs measured by nx_actlog steps -- made one step. exit: 0 ok | 3 absent | 5 DENIED | 2 usage | 8 job RUNNING (codes surface in MCP _meta.exit_code) ⚠THIS HEADER IS THE PUBLISHED CONTRACT. nx_toolgrammar harvests these lines verbatim into knowledge/tool_grammar.conf, which nx_tools_api serves as the MCP call grammar -- so a verb missing HERE is invisible to every caller even though the code implements it. `outline` and `size` were exactly that: implemented, printed by the runtime usage string below, and absent from this header, so tools/list advertised 3 of 5 verbs. ★A CAPABILITY THAT ITS OWN PUBLISHED GRAMMAR OMITS DOES NOT EXIST TO ANY CALLER. Add the verb to BOTH this header and the usage line, or it ships dark. license_tier: ORIGINAL