nx_provenance_chain.nx
buildroot/runtime/nx_provenance_chain.nx
about
nx_provenance_chain.nx -- typed transform chain (bit-traceability).
Per [[feedback-end-to-end-bit-traceability-architecture]]:
"Every transformation of any signal emits a (prev_hash, transform_id,
params, output_hash, timestamp) ProvenanceLink to a local trace log
so any bit's journey reconstructable end-to-end."
THIS IS THE BIT-TRACE FOUNDATION. Every transform in the substrate
(capture, preprocess, encode, packetize, encrypt, NIC send, NIC
recv, decrypt, decode, render) creates a ProvenanceLink that chains
to the prior link by prev_hash. The full chain is a Merkle DAG of
what happened to a bit from generation to endpoint.
Per user 2026-05-17: "id love for our system to be so sss class
world class whatever that the bit is followed from generated signal
to endpoint so we can see degradation both on silicon across the
world so that its the circuitboard is the whole system itself."
Composes:
nx_methyl -- each link methyl-marked so chain authenticity
survives even when some links are sent across
cells / hosts / wire
nx_xenocell -- signed observations are provenance links too
nx_evict_journal -- significant events surface as journal entries
while detail lives in the trace chain
nx_pollinate -- federated trace fragments (peer-mesh of chains)
V1 ships:
- struct NxProvenanceLink with prev_hash, transform_id, params_hash,
output_hash, timestamp, originator_id
- struct NxProvenanceChain as ordered ring of links
- append(): new link references the previous chain head
- verify_continuity(): walk chain and check each prev_hash
matches the prior link's output_hash
- find_by_output_hash(): locate any link by its output hash
(forensic query: "what produced this byte?")
Gap list (V1 honest perf verdict):
- links are in-memory ring; on-disk JSONL persistence is queued
- merkle-tree summary of chain not built (V2: nx_trace_merkle)
dependencies 3 imports · 5 importers
imports: nx_syscalls.nxnx_tier.nxnx_methyl.nx
imported by: nx_failover_compose_test.nxnx_provenance_chain_test.nxnx_session_audit_compose_test.nxnx_trace_log.nxnx_trace_log_test.nx
structs
| 100 | struct NxProvenanceLink |
| 112 | struct NxProvenanceChain |
consts
| 70 | const NX_TX_NONE: nx_int = 0 |
| 71 | const NX_TX_CAPTURE: nx_int = 1 |
| 72 | const NX_TX_PREPROCESS: nx_int = 2 |
| 73 | const NX_TX_ENCODE: nx_int = 3 |
| 74 | const NX_TX_PACKETIZE: nx_int = 4 |
| 75 | const NX_TX_ENCRYPT: nx_int = 5 |
| 76 | const NX_TX_NIC_SEND: nx_int = 6 |
| 77 | const NX_TX_NIC_RECV: nx_int = 7 |
| 78 | const NX_TX_DECRYPT: nx_int = 8 |
| 79 | const NX_TX_JITTER: nx_int = 9 |
| 80 | const NX_TX_DECODE: nx_int = 10 |
| 81 | const NX_TX_RENDER: nx_int = 11 |
| 82 | const NX_TX_DAC: nx_int = 12 // future-silicon DAC |
| 83 | const NX_TX_N_KINDS: nx_int = 13 |
| 87 | const NX_PV_OK: nx_int = 0 |
| 88 | const NX_PV_ERR_CHAIN_FULL: nx_int = 1 |
| 89 | const NX_PV_ERR_BROKEN: nx_int = 2 // continuity check failed |
| 90 | const NX_PV_ERR_BAD_LINK: nx_int = 3 |
| 91 | const NX_PV_ERR_NOT_FOUND: nx_int = 4 |
| 120 | const NX_PV_LINK_BYTES: nx_size = 56 |
functions
| 128 | func nx_tx_is_canonical(t: nx_int) -> nx_int called by 1: main |
| 136 | func nx_provenance_chain_new(capacity: nx_size) -> *NxProvenanceChain |
| 149 | func _pv_at(c: *NxProvenanceChain, idx: nx_size) -> *NxProvenanceLink |
| 159 | func nx_provenance_append(c: *NxProvenanceChain, |
| 186 | func nx_provenance_link_at(c: *NxProvenanceChain, idx: nx_size) -> *NxProvenanceLink |
| 198 | func nx_provenance_verify_continuity(c: *NxProvenanceChain) -> nx_int |
| 218 | func nx_provenance_find_by_output_hash(c: *NxProvenanceChain, |
| 233 | func nx_provenance_count_by_transform(c: *NxProvenanceChain, |
| 249 | func nx_provenance_last_hash(c: *NxProvenanceChain) -> nx_size |