nx_doc_incumbent.nx source
↩ module page · 263 lines · 9841 B
1// nx_doc_incumbent.nx -- D21 provenance tier + D22 multi-incumbent
2// comparison table. Operationalizes the V5 'benchmark against ALL
3// known activities' cardinal.
4//
5// Substrate names FULL incumbent field per primitive class + emits
6// a markdown comparison table with substrate's value + each
7// incumbent's value + provenance tier + percent gap.
8//
9// Per [[feedback-substrate-knowledge-system-s-class-reasoning-
10// provenance-dashboard]] cardinal. Composes with nx_doc_decision
11// (D20) for full decision context: ADR explains WHY this class,
12// incumbent table shows HOW WE STACK UP.
13//
14// **Quadrant:** REFERENCE (Diátaxis)
15// **Topic Type:** REFERENCE (DITA)
16// **Status:** DRAFT (D21 + D22 first stones)
17// **Trust State:** WRITTEN_UNTESTED
18// **Competitive State:** UNCLASSIFIED
19
20import "nx_syscalls.nx"
21import "nx_string_ops.nx"
22
23// ===== D21 Provenance tier sealed enum ===========================
24//
25// Distinguishes measurement SOURCE. Orthogonal to trust state
26// (robustness) + competitive state (performance position).
27
28const NX_PROVENANCE_INDUSTRY_STATED: i64 = 0 // vendor claim; not measured
29const NX_PROVENANCE_PERSONALLY_MEASURED: i64 = 1 // substrate measured one silicon
30const NX_PROVENANCE_CROSS_VALIDATED: i64 = 2 // ≥2 silicon classes
31const NX_PROVENANCE_HARSH_VALIDATED: i64 = 3 // harsh conditions
32const NX_PROVENANCE_TIME_PROVEN: i64 = 4 // measured + non-stale + N months prod
33const NX_PROVENANCE_N: i64 = 5
34
35func nx_provenance_is_valid(p: i64) -> i64 {
36 if p < 0 { return 0 }
37 if p >= NX_PROVENANCE_N { return 0 }
38 return 1
39}
40
41func nx_provenance_name(p: i64) -> *u8 {
42 if p == NX_PROVENANCE_INDUSTRY_STATED { return "INDUSTRY_STATED" }
43 if p == NX_PROVENANCE_PERSONALLY_MEASURED { return "PERSONALLY_MEASURED" }
44 if p == NX_PROVENANCE_CROSS_VALIDATED { return "CROSS_VALIDATED" }
45 if p == NX_PROVENANCE_HARSH_VALIDATED { return "HARSH_VALIDATED" }
46 if p == NX_PROVENANCE_TIME_PROVEN { return "TIME_PROVEN" }
47 return "UNKNOWN"
48}
49
50// Returns 1 if the provenance tier implies the measurement is
51// substrate-confidence (PERSONALLY_MEASURED or above). Industry-
52// stated values are claim-only.
53func nx_provenance_is_substrate_measured(p: i64) -> i64 {
54 if p >= NX_PROVENANCE_PERSONALLY_MEASURED { return 1 }
55 return 0
56}
57
58// ===== Primitive class sealed enum ===============================
59//
60// Identifies which substrate-primitive class a benchmark targets.
61// Reserved space; expand as substrate grows.
62
63const NX_PCLASS_PATTERN_MATCHING: i64 = 0 // ripgrep / Hyperscan / RE2 / Wu-Manber
64const NX_PCLASS_SORT: i64 = 1 // pdqsort / Timsort / ips4o
65const NX_PCLASS_CARDINALITY: i64 = 2 // Apache DataSketches HLL / HLL++ / Theta
66const NX_PCLASS_QUANTILE: i64 = 3 // DataSketches KLL / REQ / T-Digest / DDSketch
67const NX_PCLASS_HASH_NONCRYPTO: i64 = 4 // xxHash / CityHash / MurmurHash3 / FNV
68const NX_PCLASS_TLS: i64 = 5 // OpenSSL / BoringSSL / rustls / s2n-tls / WolfSSL
69const NX_PCLASS_COMPRESSION: i64 = 6 // zstd / lz4 / snappy / brotli / zlib
70const NX_PCLASS_DOCS: i64 = 7 // JavaDoc / Rustdoc / Doxygen / Sphinx / Mermaid / Obsidian
71const NX_PCLASS_FLOATING_POINT: i64 = 8 // SoftFloat / Muller Handbook / Cody-Waite
72const NX_PCLASS_GPU_COMPUTE: i64 = 9 // CUDA / ROCm-HIP / oneAPI / Metal / Vulkan
73const NX_PCLASS_SHELL: i64 = 10 // bash / zsh / fish / PowerShell / Nushell / Oils
74const NX_PCLASS_N: i64 = 11
75
76func nx_pclass_is_valid(c: i64) -> i64 {
77 if c < 0 { return 0 }
78 if c >= NX_PCLASS_N { return 0 }
79 return 1
80}
81
82func nx_pclass_name(c: i64) -> *u8 {
83 if c == NX_PCLASS_PATTERN_MATCHING { return "PATTERN_MATCHING" }
84 if c == NX_PCLASS_SORT { return "SORT" }
85 if c == NX_PCLASS_CARDINALITY { return "CARDINALITY" }
86 if c == NX_PCLASS_QUANTILE { return "QUANTILE" }
87 if c == NX_PCLASS_HASH_NONCRYPTO { return "HASH_NONCRYPTO" }
88 if c == NX_PCLASS_TLS { return "TLS" }
89 if c == NX_PCLASS_COMPRESSION { return "COMPRESSION" }
90 if c == NX_PCLASS_DOCS { return "DOCS" }
91 if c == NX_PCLASS_FLOATING_POINT { return "FLOATING_POINT" }
92 if c == NX_PCLASS_GPU_COMPUTE { return "GPU_COMPUTE" }
93 if c == NX_PCLASS_SHELL { return "SHELL" }
94 return "UNKNOWN"
95}
96
97// ===== D22 Incumbent row + table =================================
98
99struct NxIncumbentRow {
100 name_ptr: *u8,
101 name_len: i64,
102 version_ptr: *u8,
103 version_len: i64,
104 measured_value_q14: i64, // Q14 fixed-point; value depends on metric semantics
105 provenance_tier: i64, // NX_PROVENANCE_*
106}
107
108func nx_incumbent_row_init(
109 r: *NxIncumbentRow,
110 name: *u8, n_name: i64,
111 version: *u8, n_version: i64,
112 measured_value_q14: i64,
113 provenance_tier: i64
114) -> i64 {
115 if nx_provenance_is_valid(provenance_tier) != 1 { return -1 }
116 r.name_ptr = name
117 r.name_len = n_name
118 r.version_ptr = version
119 r.version_len = n_version
120 r.measured_value_q14 = measured_value_q14
121 r.provenance_tier = provenance_tier
122 return 0
123}
124
125struct NxIncumbentTable {
126 primitive_class: i64, // NX_PCLASS_*
127 workload_ptr: *u8, // free-text description
128 workload_len: i64,
129 metric_ptr: *u8, // free-text metric name (e.g., 'ops/sec')
130 metric_len: i64,
131 substrate_value_q14: i64,
132 substrate_provenance_tier: i64,
133 rows_ptr: *NxIncumbentRow, // caller-owned array
134 n_rows: i64,
135}
136
137func nx_incumbent_table_init(
138 t: *NxIncumbentTable,
139 primitive_class: i64,
140 workload: *u8, n_workload: i64,
141 metric: *u8, n_metric: i64,
142 substrate_value_q14: i64,
143 substrate_provenance_tier: i64
144) -> i64 {
145 if nx_pclass_is_valid(primitive_class) != 1 { return -1 }
146 if nx_provenance_is_valid(substrate_provenance_tier) != 1 { return -2 }
147 t.primitive_class = primitive_class
148 t.workload_ptr = workload
149 t.workload_len = n_workload
150 t.metric_ptr = metric
151 t.metric_len = n_metric
152 t.substrate_value_q14 = substrate_value_q14
153 t.substrate_provenance_tier = substrate_provenance_tier
154 t.rows_ptr = 0 as *NxIncumbentRow
155 t.n_rows = 0
156 return 0
157}
158
159func nx_incumbent_table_set_rows(
160 t: *NxIncumbentTable,
161 rows: *NxIncumbentRow,
162 n_rows: i64
163) {
164 t.rows_ptr = rows
165 t.n_rows = n_rows
166}
167
168// Gap of substrate value vs incumbent value, expressed in Q14
169// percentage delta. Positive = substrate exceeds; negative =
170// substrate trails. Returns substrate_pct_delta in Q14 (e.g.,
171// +1638 = +10%).
172//
173// Formula: ((sub - inc) / inc) * 100 in Q14 ≈ ((sub*100*Q14 - inc*100*Q14) / inc)
174// To avoid overflow on large values, we approximate:
175// delta_q14 = ((sub - inc) * 100 * 16384) / inc ... careful with i64 width.
176//
177// Substrate-honest: returns 0 if inc == 0 (no division-by-zero).
178
179func nx_incumbent_gap_pct_q14(
180 substrate_value_q14: i64,
181 incumbent_value_q14: i64
182) -> i64 {
183 if incumbent_value_q14 == 0 { return 0 }
184 let diff: i64 = substrate_value_q14 - incumbent_value_q14
185 let scaled: i64 = diff * 100 * 16384
186 return scaled / incumbent_value_q14
187}
188
189// ===== Markdown emitter ==========================================
190//
191// Outputs:
192// ## Incumbent table — <pclass name>
193//
194// **Workload:** <workload>
195// **Metric:** <metric>
196// **Substrate value:** <Q14> (<provenance>)
197//
198// | Incumbent | Version | Value | Provenance | Gap |
199// |---|---|---|---|---|
200// | <name> | <ver> | <val> | <prov> | <gap pct Q14> |
201// ...
202
203func _docincu_write_int(v: i64) {
204 let buf: *u8 = sys_mmap(32)
205 let n: i64 = nx_str_format_int(v, buf, 32)
206 sys_write(1, buf, n)
207}
208
209func nx_incumbent_table_emit(t: *NxIncumbentTable) -> i64 {
210 if nx_pclass_is_valid(t.primitive_class) != 1 { return -1 }
211
212 // Header
213 sys_write(1, "## Incumbent table — ", 23)
214 let class_name: *u8 = nx_pclass_name(t.primitive_class)
215 sys_write(1, class_name, nx_str_len(class_name))
216 sys_write(1, "\n\n", 2)
217
218 // Workload + metric
219 if t.workload_len > 0 {
220 sys_write(1, "**Workload:** ", 14)
221 sys_write(1, t.workload_ptr, t.workload_len)
222 sys_write(1, "\n", 1)
223 }
224 if t.metric_len > 0 {
225 sys_write(1, "**Metric:** ", 12)
226 sys_write(1, t.metric_ptr, t.metric_len)
227 sys_write(1, "\n", 1)
228 }
229
230 // Substrate value line
231 sys_write(1, "**Substrate value (Q14):** ", 27)
232 _docincu_write_int(t.substrate_value_q14)
233 sys_write(1, " (", 2)
234 let prov_name: *u8 = nx_provenance_name(t.substrate_provenance_tier)
235 sys_write(1, prov_name, nx_str_len(prov_name))
236 sys_write(1, ")\n\n", 3)
237
238 // Table header
239 sys_write(1, "| Incumbent | Version | Value (Q14) | Provenance | Gap (Q14 pct) |\n", 67)
240 sys_write(1, "|---|---|---|---|---|\n", 22)
241
242 // Rows
243 var i: i64 = 0
244 while i < t.n_rows {
245 let row: *NxIncumbentRow = ((t.rows_ptr as *u8) + (i * 48)) as *NxIncumbentRow
246 sys_write(1, "| ", 2)
247 sys_write(1, row.name_ptr, row.name_len)
248 sys_write(1, " | ", 3)
249 sys_write(1, row.version_ptr, row.version_len)
250 sys_write(1, " | ", 3)
251 _docincu_write_int(row.measured_value_q14)
252 sys_write(1, " | ", 3)
253 let p_name: *u8 = nx_provenance_name(row.provenance_tier)
254 sys_write(1, p_name, nx_str_len(p_name))
255 sys_write(1, " | ", 3)
256 let gap: i64 = nx_incumbent_gap_pct_q14(t.substrate_value_q14, row.measured_value_q14)
257 _docincu_write_int(gap)
258 sys_write(1, " |\n", 3)
259 i = i + 1
260 }
261 sys_write(1, "\n", 1)
262 return 0
263}