nx_genealogy.nx source

1// nx_genealogy.nx -- substrate-primitive genealogy ledger. 2// 3// Cardinal: feedback-systemic-injection-everything-zero-runtime-overhead. 4// 5// Distinct from nx_bit_provenance: that ledger tracks OUTPUT BITS. 6// This one tracks the PRIMITIVES THEMSELVES -- who authored each 7// `func`, what parent primitive(s) it derives from, when (session 8// id), and the one-line intent (WHY). 9// 10// Use cases: 11// - "What's the lineage of nx_matmul_traced?" -> nx_bit_provenance 12// -> nx_blas_i64 -> nx_tensor + nx_syscalls -> Linux RV64 ABI 13// - "Was this primitive built in a session that's since been 14// rolled back?" -> session_id check 15// - "Which agent authored this brick?" -> author tag 16// 17// API: 18// nx_geneal_record(prim_tag, parent_a_tag, parent_b_tag, parent_c_tag, 19// author_tag, session_id, intent_hash) -> i64 20// nx_geneal_lookup(prim_tag) -> i64 (record-slot index, -1 if missing) 21// nx_geneal_n_records() -> i64 22// 23// Storage: same mmap-backed append-only ring as the other meta-pattern 24// ledgers. 56-byte records (7 i64 fields). 25 26import "syscalls.nx" 27const NX_MAGIC_2026: i64 = 2026 28const NX_MAGIC_20260517: i64 = 20260517 29const NX_MAGIC_20260516: i64 = 20260516 30 31static NX_GENEAL_ACTIVE: i64 32static NX_GENEAL_LEDGER_PTR: i64 33static NX_GENEAL_N_RECORDS: i64 34static NX_GENEAL_CAPACITY: i64 35 36const NX_GENEAL_REC_SIZE: i64 = 56 // 7 i64 fields 37const NX_GENEAL_CHUNK_BYTES: i64 = 32768 // 585 records 38 39func nx_geneal_init() -> i64 { 40 if NX_GENEAL_LEDGER_PTR != 0 { return 0 } 41 let raw: *u8 = sys_mmap(NX_GENEAL_CHUNK_BYTES) 42 if (raw as i64) == 0 { return 1 } 43 if (raw as i64) == 0 - 1 { return 2 } 44 NX_GENEAL_LEDGER_PTR = raw as i64 45 NX_GENEAL_N_RECORDS = 0 46 NX_GENEAL_CAPACITY = NX_GENEAL_CHUNK_BYTES / NX_GENEAL_REC_SIZE 47 NX_GENEAL_ACTIVE = 1 48 return 0 49} 50 51func nx_geneal_enable() -> i64 { NX_GENEAL_ACTIVE = 1; return 0 } 52func nx_geneal_disable() -> i64 { NX_GENEAL_ACTIVE = 0; return 0 } 53func nx_geneal_is_active() -> i64 { return NX_GENEAL_ACTIVE } 54 55// Record a primitive's genealogy. Returns 0 OK, non-zero if the 56// ledger is full or telemetry is disabled (in which case the 57// record is silently dropped). 58func nx_geneal_record(prim_tag: i64, parent_a: i64, parent_b: i64, 59 parent_c: i64, author_tag: i64, session_id: i64, 60 intent_hash: i64) -> i64 { 61 if NX_GENEAL_ACTIVE == 0 { return 0 } 62 nx_geneal_init() 63 if NX_GENEAL_LEDGER_PTR == 0 { return 0 } 64 if NX_GENEAL_N_RECORDS >= NX_GENEAL_CAPACITY { return 3 } 65 let base: i64 = NX_GENEAL_LEDGER_PTR + (NX_GENEAL_N_RECORDS * NX_GENEAL_REC_SIZE) 66 let rec: *i64 = base as *i64 67 rec[0] = prim_tag 68 rec[1] = parent_a 69 rec[2] = parent_b 70 rec[3] = parent_c 71 rec[4] = author_tag 72 rec[5] = session_id 73 rec[6] = intent_hash 74 NX_GENEAL_N_RECORDS = NX_GENEAL_N_RECORDS + 1 75 return 0 76} 77 78// Find the slot index for a given primitive tag. Returns -1 if 79// the primitive has no genealogy record yet. 80func nx_geneal_lookup(prim_tag: i64) -> i64 { 81 nx_geneal_init() 82 var i: i64 = 0 83 while i < NX_GENEAL_N_RECORDS { 84 let base: i64 = NX_GENEAL_LEDGER_PTR + (i * NX_GENEAL_REC_SIZE) 85 let rec: *i64 = base as *i64 86 if rec[0] == prim_tag { return i } 87 i = i + 1 88 } 89 return 0 - 1 90} 91 92// Read a record field by (slot, field_index 0..6). Returns the 93// raw i64 value or -1 if slot is out of range. 94func nx_geneal_field(slot: i64, field: i64) -> i64 { 95 nx_geneal_init() 96 if slot < 0 { return 0 - 1 } 97 if slot >= NX_GENEAL_N_RECORDS { return 0 - 1 } 98 if field < 0 { return 0 - 1 } 99 if field > 6 { return 0 - 1 } 100 let base: i64 = NX_GENEAL_LEDGER_PTR + (slot * NX_GENEAL_REC_SIZE) 101 let rec: *i64 = base as *i64 102 return rec[field] 103} 104 105func nx_geneal_n_records() -> i64 { 106 nx_geneal_init() 107 return NX_GENEAL_N_RECORDS 108} 109 110// ---- self-test --------------------------------------------------- 111// expect_exit: 0 112 113func main() -> i64 { 114 if nx_geneal_init() != 0 { return 1 } 115 116 // Disabled-mode short-circuit. 117 nx_geneal_disable() 118 nx_geneal_record(100, 0, 0, 0, 1, NX_MAGIC_2026, 0xABCD) 119 if nx_geneal_n_records() != 0 { return 10 } 120 121 // Enable + record 3 substrate primitives' genealogies. 122 nx_geneal_enable() 123 124 // nx_matmul_traced derives from nx_bit_provenance + nx_blas_i64 125 // (parents). Author = claude (tag 1), session = 20260517, 126 // intent = FNV("matmul with bit lineage"). 127 if nx_geneal_record(0xCAFE0001, 0xCAFE0002, 0xCAFE0003, 0, 128 1, NX_MAGIC_20260517, 0x11111111) != 0 { return 20 } 129 130 // nx_bit_provenance is a root primitive (no parents). 131 if nx_geneal_record(0xCAFE0002, 0, 0, 0, 132 1, NX_MAGIC_20260517, 0x22222222) != 0 { return 21 } 133 134 // nx_blas_i64 derives from nx_tensor + nx_syscalls. 135 if nx_geneal_record(0xCAFE0003, 0xCAFE0004, 0xCAFE0005, 0, 136 1, NX_MAGIC_20260516, 0x33333333) != 0 { return 22 } 137 138 if nx_geneal_n_records() != 3 { return 30 } 139 140 // Lookup nx_matmul_traced. 141 let slot: i64 = nx_geneal_lookup(0xCAFE0001) 142 if slot < 0 { return 40 } 143 if nx_geneal_field(slot, 0) != 0xCAFE0001 { return 41 } // self tag 144 if nx_geneal_field(slot, 1) != 0xCAFE0002 { return 42 } // parent A 145 if nx_geneal_field(slot, 2) != 0xCAFE0003 { return 43 } // parent B 146 if nx_geneal_field(slot, 5) != NX_MAGIC_20260517 { return 44 } // session 147 148 // Lookup root primitive (parents all zero). 149 let root_slot: i64 = nx_geneal_lookup(0xCAFE0002) 150 if root_slot < 0 { return 50 } 151 if nx_geneal_field(root_slot, 1) != 0 { return 51 } 152 if nx_geneal_field(root_slot, 2) != 0 { return 52 } 153 154 // Lookup missing primitive returns -1. 155 if nx_geneal_lookup(0xDEAD9999) != 0 - 1 { return 60 } 156 157 // Out-of-range slot returns -1 from field. 158 if nx_geneal_field(99, 0) != 0 - 1 { return 70 } 159 if nx_geneal_field(0, 99) != 0 - 1 { return 71 } 160 161 // Disabled-mode re-test. 162 nx_geneal_disable() 163 nx_geneal_record(0xDEAD, 0, 0, 0, 0, 0, 0) 164 if nx_geneal_n_records() != 3 { return 80 } 165 166 return 0 167}