code wiki / _hdl_build / nx_plane_append.nx

nx_plane_append.nx

buildroot/runtime/_hdl_build/nx_plane_append.nx

16073 B344 linesdepth 5pulls 7 transitivereach 0 importersview sourcekind tooltopic plane
docsdependenciesstructsconstsfunctions

about

nx_plane_append.nx -- SAFE APPEND OF ONE ROW TO A SOVEREIGN SEG-STORE PLANE. WHY THIS EXISTS (proved by experiment 2026-07-26, debt seq1067). `sts_seed` REPLACES a plane; it does not append. Seeding the same 2-row fixture twice into a throwaway prefix left 2 rows, not 4. So the obvious way to "add one row" to a shared catalog -- call the seeder with your row -- DESTROYS every row already there. Adding one row to knowledge/store/commontask- that way would have turned its 42 rows into 1. Two unrelated pieces of work were blocked on this single missing primitive: registering an organ in the capability catalog, and adding the additive KIND column the atlas measure-gap axis needs (seq1046). It was never a catalog problem. It was a WRITE-API problem. FAIL-SAFE BY CONSTRUCTION, not by promise (Rule 13 / Rule 26 spirit): * the ORIGINAL bytes are held in memory for the whole operation, so a restore is always possible; * an absent or empty plane is REFUSED, never silently created -- a typo in a prefix must not conjure a new plane that later reads as authoritative; * the new buffer must be strictly LONGER than the old one AND must still start with the old bytes, checked before the commit -- an append that does not preserve its input is not an append; * after the commit the plane is RE-LOADED and the row count verified; on any mismatch the original buffer is written back and the tool reports RED rather than leaving a mangled registry. HONEST LIMIT, stated because it matters: the lock serialises appends made THROUGH THIS ORGAN. Any other writer calling sts_seed directly bypasses it. This is the one correct path, not a guarantee about every path, and it cannot become one until the other writers route through here. nx_plane_append <prefix> <row> nx_plane_append selftest expect_exit: 0 license_tier: ORIGINAL No hw writes (Rule 26).

dependencies 4 imports · 0 importers

nx_syscalls.nx nx_itoa_lib.nx nx_store_seed_lib.nx nx_seg_store.nx nx_plane_append.nx

imports: nx_syscalls.nxnx_itoa_lib.nxnx_store_seed_lib.nxnx_seg_store.nx

imported by: nobody (leaf or entry point)

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

main pa_w sys_write sys_exit pa_streq pa_selftest sts_mm sys_mmap sts_werr sys_write ↻ sys_exit ↻ ss_cat sts_seed ss_begin_cap sys_mmap ↻ sts_mm ↻ sts_rowkey ss_catn sys_mmap ↻ ss_add ss_add2 ss_w32 ss_len ss_catn ↻ ss_commit ss_segid_ok sys_mmap ↻ ss_cat ↻ ss_catn ↻ sys_write ↻ ss_write_seg ss_segid_ok ↻ sys_mmap ↻ ss_cat ↻ ss_catn ↻ sys_write ↻ ss_segname ss_cat ↻ ss_catn ↻ ss_writefile

structs

none

consts

31const PA_MAGIC_65536: i64 = 65536
32const PA_MAGIC_4096: i64 = 4096
34const PA_CAP: i64 = 4194304
35const PA_LOCK_MODE: i64 = 420
36const PA_NL: i64 = 10
37const PA_OUTFD: i64 = 1
38const PA_EXIT_OK: i64 = 0
39const PA_EXIT_USAGE: i64 = 2
40const PA_EXIT_REFUSED: i64 = 3
41const PA_EXIT_IO: i64 = 4
42const PA_EXIT_CORRUPT: i64 = 5

functions

44func pa_w(s: *u8) -> i64 { var n: i64 = 0; while s[n] != (0 as u8) { n = n + 1 } sys_write(PA_OUTFD, s, n); return 0 }
49func pa_n(v: i64) -> i64 { nxi_out(v); return 0 }
50func pa_streq(a: *u8, b: *u8) -> i64
called by 1: main
56func pa_slen(s: *u8) -> i64 { var n: i64 = 0; while s[n] != (0 as u8) { n = n + 1 } return n }
59func pa_rows(buf: *u8, n: i64) -> i64
69func pa_prefix_ok(oldb: *u8, oldn: i64, newb: *u8, newn: i64) -> i64
88func pa_lock(prefix: *u8) -> i64
called by 2: pa_appendpa_append_fast calls 1: sts_lock
92func pa_unlock(fd: i64) -> i64
called by 2: pa_appendpa_append_fast calls 1: sts_unlock
97func pa_append(prefix: *u8, row: *u8, quiet: i64) -> i64
172func pa_selftest() -> i64
269func pa_append_fast(prefix: *u8, row: *u8, quiet: i64) -> i64
315func main(argc: i64, argv: *i64) -> i64