nx_etg.nx source
↩ module page · 289 lines · 13633 B
1// nx_etg.nx -- Empirical-Truth Gamification substrate primitive.
2//
3// E1 first stone of NISHI_ETG_ROADMAP.md. Implements the substrate-
4// wide doctrine [[feedback-physical-truth-over-published-docs-silicon-
5// empirical-gamification]]: vendor docs are HYPOTHESES, the silicon
6// is the truth. Every probe outcome records what the silicon
7// actually did, classifies it against what the vendor claimed, and
8// emits a ProvenanceLinked decision attestation.
9//
10// This brick is the TAXONOMY + ACCOUNTING + ATTESTATION layer.
11// Real probes (E3 cpu / E5 gpu / E4 storage / E7 net) compose this.
12//
13// Composes:
14// [[NISHI_ETG_ROADMAP]] E1 (this is the first stone)
15// [[feedback-physical-truth-over-published-docs-silicon-empirical-gamification]]
16// [[NISHI_GRAPHICS_ROADMAP]] G3.5 nx_calibrate_gpu (GPU-tier ETG)
17// [[NISHI_SELF_ASSEMBLY_ROADMAP]] SA-2 nx_calibrate (CPU-tier prior art)
18// [[NISHI_RACING_CREW_ROADMAP]] (Byzantine-verified empirical measurement)
19// [[feedback-no-false-ok-substrate-honesty-audit]] (every outcome
20// deterministically classified; INCONCLUSIVE is the honest verdict
21// when probes disagree, not silent silence)
22// [[feedback-reclamation-doctrine-captain-moroni]] (RECLAIMED outcome
23// is the substrate's accounting record)
24// Cardinal 13 (additive — entries tombstone via outcome=FALSIFIED on
25// re-probe; never deleted)
26//
27// API:
28// Probe outcome sealed enum NX_ETG_OUTCOME_*
29// NxEtgEntry struct (one per probe call)
30// nx_etg_outcome_is_valid(o) -> i64
31// nx_etg_outcome_name(o) -> *u8
32// nx_etg_outcome_implies_reclamation(o) -> i64
33// nx_etg_entry_init(...) (caller-provided struct storage)
34// nx_etg_reclamation_delta(entry) -> i64
35// nx_etg_attestation_hash(entry) -> i64 (FNV-1a 64-bit; E1 scaffolding;
36// upgradeable to SHA-512)
37// nx_etg_attestation_deterministic(e1, e2) -> i64 (same inputs ->
38// same attestation hash; gate
39// for ProvenanceLinked replay)
40
41// nx_safety_envelope:
42// intended_use: "ETG probe outcome taxonomy + reclamation
43// accounting + decision attestation hash;
44// substrate-wide framework; real per-tier
45// probes compose this"
46// sil_target: SIL2
47// evidence: [kat_outcome_enum_complete,
48// kat_reclamation_delta_correct,
49// kat_attestation_determinism]
50// hazard_register: [bug-tape-outcome-class-aliasing,
51// bug-tape-fnv-collision-when-upgrading-to-sha,
52// bug-tape-vendor-lie-misclassified]
53// verdict: NOT_YET_EVALUATED
54
55import "nx_syscalls.nx"
56import "nx_fnv.nx"
57
58// Composes: [[nx_fnv.nx]] -- canonical FNV-1a primitive. Earlier
59// versions of this file hand-rolled FNV-1a inline (NX_ETG_FNV_OFFSET
60// + nx_etg_fnv_step + nx_etg_fnv_i64); refactored 2026-05-20 per
61// [[feedback-no-tool-proliferation-consolidate-or-justify]] cardinal
62// (bit-level extension) -- the substrate had 10 inline FNV
63// implementations; consolidated to compose nx_fnv.
64
65// ===== Probe outcome sealed enum =================================
66//
67// One value per honest verdict the substrate can record about what
68// the silicon did vs what the vendor claimed. Numbers are reserved
69// (no renumbering) so future audits can replay historical attestations.
70
71const NX_ETG_OUTCOME_NONE: i64 = 0
72const NX_ETG_OUTCOME_CONFIRMED: i64 = 1 // doc agrees, silicon agrees
73const NX_ETG_OUTCOME_VENDOR_LIED_OMISSION: i64 = 2 // silicon does MORE than doc claimed
74const NX_ETG_OUTCOME_VENDOR_LIED_MISDIRECTION: i64 = 3 // silicon does DIFFERENT than doc claimed
75const NX_ETG_OUTCOME_FALSIFIED: i64 = 4 // doc claim failed
76const NX_ETG_OUTCOME_PAYWALLED_BUT_RESPONSIVE: i64 = 5 // gated feature responds to direct register
77const NX_ETG_OUTCOME_RECLAIMED: i64 = 6 // capability added to cost model after probe
78const NX_ETG_OUTCOME_INCONCLUSIVE: i64 = 7 // N-of-M probes disagree
79const NX_ETG_OUTCOME_THROTTLED: i64 = 8 // silicon stable above vendor max
80const NX_ETG_OUTCOME_FUSED_OFF: i64 = 9 // silicon refuses (vendor disabled at fuse)
81const NX_ETG_OUTCOME_UNDOCUMENTED_CAPABILITY: i64 = 10 // works but no spec coverage
82const NX_ETG_OUTCOME_N: i64 = 11
83
84func nx_etg_outcome_is_valid(o: i64) -> i64 {
85 if o < 0 { return 0 }
86 if o >= NX_ETG_OUTCOME_N { return 0 }
87 return 1
88}
89
90func nx_etg_outcome_name(o: i64) -> *u8 {
91 if o == NX_ETG_OUTCOME_NONE { return "NONE" }
92 if o == NX_ETG_OUTCOME_CONFIRMED { return "CONFIRMED" }
93 if o == NX_ETG_OUTCOME_VENDOR_LIED_OMISSION { return "VENDOR_LIED_OMISSION" }
94 if o == NX_ETG_OUTCOME_VENDOR_LIED_MISDIRECTION { return "VENDOR_LIED_MISDIRECTION" }
95 if o == NX_ETG_OUTCOME_FALSIFIED { return "FALSIFIED" }
96 if o == NX_ETG_OUTCOME_PAYWALLED_BUT_RESPONSIVE { return "PAYWALLED_BUT_RESPONSIVE" }
97 if o == NX_ETG_OUTCOME_RECLAIMED { return "RECLAIMED" }
98 if o == NX_ETG_OUTCOME_INCONCLUSIVE { return "INCONCLUSIVE" }
99 if o == NX_ETG_OUTCOME_THROTTLED { return "THROTTLED" }
100 if o == NX_ETG_OUTCOME_FUSED_OFF { return "FUSED_OFF" }
101 if o == NX_ETG_OUTCOME_UNDOCUMENTED_CAPABILITY { return "UNDOCUMENTED_CAPABILITY" }
102 return "UNKNOWN"
103}
104
105// An outcome implies reclamation iff the substrate gains a new
106// capability or improved bound by recording it. RECLAIMED is the
107// explicit case; VENDOR_LIED_OMISSION / PAYWALLED_BUT_RESPONSIVE /
108// THROTTLED / UNDOCUMENTED_CAPABILITY all transitively imply
109// reclamation because they each surface a capability above what
110// the vendor advertised. CONFIRMED / FALSIFIED / FUSED_OFF /
111// INCONCLUSIVE / NONE do NOT imply reclamation (CONFIRMED is the
112// no-delta case; FALSIFIED and FUSED_OFF are silicon refusing;
113// INCONCLUSIVE needs re-probe; NONE is the unfired entry).
114func nx_etg_outcome_implies_reclamation(o: i64) -> i64 {
115 if o == NX_ETG_OUTCOME_VENDOR_LIED_OMISSION { return 1 }
116 if o == NX_ETG_OUTCOME_PAYWALLED_BUT_RESPONSIVE { return 1 }
117 if o == NX_ETG_OUTCOME_RECLAIMED { return 1 }
118 if o == NX_ETG_OUTCOME_THROTTLED { return 1 }
119 if o == NX_ETG_OUTCOME_UNDOCUMENTED_CAPABILITY { return 1 }
120 return 0
121}
122
123// ===== Probe-kind sealed enum ====================================
124//
125// Identifies which tier + family a probe belongs to. Mirrors the
126// per-tier catalog in NISHI_ETG_ROADMAP.md Section 4.
127
128const NX_ETG_PROBE_NONE: i64 = 0
129const NX_ETG_PROBE_CPU_ISA: i64 = 1
130const NX_ETG_PROBE_CPU_CLOCK: i64 = 2
131const NX_ETG_PROBE_CPU_CACHE: i64 = 3
132const NX_ETG_PROBE_CPU_SYSCALL: i64 = 4
133const NX_ETG_PROBE_CPU_POWER: i64 = 5
134const NX_ETG_PROBE_GPU_CU: i64 = 6
135const NX_ETG_PROBE_GPU_TENSOR: i64 = 7
136const NX_ETG_PROBE_GPU_CLOCK: i64 = 8
137const NX_ETG_PROBE_GPU_DMA: i64 = 9
138const NX_ETG_PROBE_GPU_THERMAL: i64 = 10
139const NX_ETG_PROBE_GPU_ISA: i64 = 11
140const NX_ETG_PROBE_STORAGE_NVME: i64 = 12
141const NX_ETG_PROBE_STORAGE_RAM: i64 = 13
142const NX_ETG_PROBE_NET_LINK: i64 = 14
143const NX_ETG_PROBE_NET_TLS: i64 = 15
144const NX_ETG_PROBE_NPU: i64 = 16
145const NX_ETG_PROBE_DSP: i64 = 17
146// Substrate-self probes (the substrate measuring its OWN state via
147// audit primitives). Added 2026-05-20 per
148// [[feedback-audits-are-ecosystem-citizens-not-islands]].
149const NX_ETG_PROBE_AUDIT_TOOL_GENEALOGY: i64 = 18 // nx_tool_census
150const NX_ETG_PROBE_AUDIT_BIT_LEVEL: i64 = 19 // nx_bit_level_census
151const NX_ETG_PROBE_AUDIT_GENEALOGY_MAP: i64 = 20 // nx_genealogy_map
152const NX_ETG_PROBE_AUDIT_CROSS_ARCH: i64 = 21 // cross-arch parity
153const NX_ETG_PROBE_N: i64 = 22
154
155func nx_etg_probe_is_valid(p: i64) -> i64 {
156 if p < 0 { return 0 }
157 if p >= NX_ETG_PROBE_N { return 0 }
158 return 1
159}
160
161// ===== Claim source sealed enum ==================================
162//
163// Where did the claim being tested come from? Substrate-honest
164// audit trail: every claim has a SOURCE, and the outcome records
165// whether that source told the truth.
166
167const NX_ETG_CLAIM_NONE: i64 = 0
168const NX_ETG_CLAIM_CPUID: i64 = 1
169const NX_ETG_CLAIM_HWCAP: i64 = 2
170const NX_ETG_CLAIM_VENDOR_DOC: i64 = 3
171const NX_ETG_CLAIM_DRIVER_ICD: i64 = 4
172const NX_ETG_CLAIM_KMD: i64 = 5
173const NX_ETG_CLAIM_LEVEL_ZERO: i64 = 6
174const NX_ETG_CLAIM_KFD: i64 = 7
175const NX_ETG_CLAIM_BAR_ENUM: i64 = 8
176const NX_ETG_CLAIM_MARKETING_SLICK: i64 = 9
177const NX_ETG_CLAIM_LICENSE_SERVER: i64 = 10
178const NX_ETG_CLAIM_SPORE_HINT: i64 = 11 // hint from prior device's calibration
179const NX_ETG_CLAIM_PRIOR_CALIBRATION: i64 = 12 // this device's earlier probe
180const NX_ETG_CLAIM_N: i64 = 13
181
182func nx_etg_claim_is_valid(c: i64) -> i64 {
183 if c < 0 { return 0 }
184 if c >= NX_ETG_CLAIM_N { return 0 }
185 return 1
186}
187
188// ===== NxEtgEntry struct =========================================
189//
190// One record per probe call. Aggregated into a per-silicon-serial
191// append-only journal (ProvenanceLinked) for replay, Byzantine
192// N-of-M comparison, and spore-hint extraction.
193
194struct NxEtgEntry {
195 silicon_serial_hash: i64, // per-die identity
196 probe_kind: i64, // NX_ETG_PROBE_*
197 claim_source: i64, // NX_ETG_CLAIM_*
198 claim_value: i64, // what the source said (integer; capability id, clock, count, etc.)
199 measurement_value: i64, // what the silicon actually did
200 outcome: i64, // NX_ETG_OUTCOME_*
201 reclamation_delta: i64, // capabilities added to cost model this attestation
202 selector_version: i64, // substrate's selector version
203 timestamp_q14: i64, // Q14 seconds since epoch
204 attestation_hash: i64, // FNV-1a 64-bit of the above fields
205}
206
207// ===== Attestation hash ===========================================
208//
209// Composes [[nx_fnv.nx]] for FNV-1a 64-bit. Pack the 9 substantive
210// i64 fields little-endian into a 72-byte buffer + hash via the
211// canonical fnv1a() primitive. Same inputs always produce the same
212// hash (deterministic replay gate). LE byte order is portable:
213// RV64 + x86_64 + AArch64 + RV32 + ppc64le + loongarch64 are all
214// LE-by-spec so the i64-to-byte reinterpret produces identical
215// bytes across every backend.
216//
217// Previously this file hand-rolled FNV-1a inline (the offset basis +
218// FNV step + per-i64 unpacker). Refactored 2026-05-20 per the
219// bit-level extension of [[feedback-no-tool-proliferation-consolidate-
220// or-justify]] -- the substrate had 10 inline FNV implementations;
221// consolidated here to compose nx_fnv.
222
223func nx_etg_attestation_hash(e: *NxEtgEntry) -> i64 {
224 let buf: *u8 = sys_mmap(72)
225 let cells: *i64 = buf as *i64
226 cells[0] = e.silicon_serial_hash
227 cells[1] = e.probe_kind
228 cells[2] = e.claim_source
229 cells[3] = e.claim_value
230 cells[4] = e.measurement_value
231 cells[5] = e.outcome
232 cells[6] = e.reclamation_delta
233 cells[7] = e.selector_version
234 cells[8] = e.timestamp_q14
235 return fnv1a(buf, 72)
236}
237
238// Determinism gate: two entries with identical substantive fields
239// produce identical attestation hashes. Used by Byzantine N-of-M
240// agreement primitive (E2) to detect attestation forgery.
241func nx_etg_attestation_deterministic(a: *NxEtgEntry, b: *NxEtgEntry) -> i64 {
242 let ha: i64 = nx_etg_attestation_hash(a)
243 let hb: i64 = nx_etg_attestation_hash(b)
244 if ha != hb { return 0 }
245 return 1
246}
247
248// Initialize an entry in caller-provided storage. Returns 0 on
249// success, negative on invalid arguments (substrate-honest: never
250// silently writes bad records).
251func nx_etg_entry_init(
252 e: *NxEtgEntry,
253 silicon_serial_hash: i64,
254 probe_kind: i64,
255 claim_source: i64,
256 claim_value: i64,
257 measurement_value: i64,
258 outcome: i64,
259 selector_version: i64,
260 timestamp_q14: i64
261) -> i64 {
262 if nx_etg_probe_is_valid(probe_kind) != 1 { return -1 }
263 if nx_etg_claim_is_valid(claim_source) != 1 { return -2 }
264 if nx_etg_outcome_is_valid(outcome) != 1 { return -3 }
265 e.silicon_serial_hash = silicon_serial_hash
266 e.probe_kind = probe_kind
267 e.claim_source = claim_source
268 e.claim_value = claim_value
269 e.measurement_value = measurement_value
270 e.outcome = outcome
271 e.selector_version = selector_version
272 e.timestamp_q14 = timestamp_q14
273 // Reclamation delta: 1 if outcome implies reclamation, else 0.
274 // Future E3+ probes can override with capability-bit-count deltas
275 // (e.g., reclaiming AVX-512 may add multiple capability bits).
276 e.reclamation_delta = nx_etg_outcome_implies_reclamation(outcome)
277 e.attestation_hash = nx_etg_attestation_hash(e)
278 return 0
279}
280
281// ===== Reclamation accounting =====================================
282
283// Per-entry reclamation delta accessor. Aggregation across a journal
284// of entries lands at E2 once struct-array indexing semantics are
285// proven; for E1 the substrate records the delta per entry and the
286// caller (or future E2 aggregator) sums them.
287func nx_etg_entry_reclamation_delta(e: *NxEtgEntry) -> i64 {
288 return e.reclamation_delta
289}