nx_doc_dashboard.nx source
↩ module page · 279 lines · 8587 B
1// nx_doc_dashboard.nx -- D23 dashboard composite.
2//
3// Orchestrates V5 doc-renderer primitives into a single dashboard
4// surface:
5// - nx_doc_render_mermaid (D10) for substrate-graph diagrams
6// - nx_doc_decision (D20) for ADR reasoning chains
7// - nx_doc_incumbent (D21+D22) for multi-incumbent tables
8//
9// Closes the V5 dashboard arc cardinal -- substrate's first
10// integrated rendering surface matching modern docs/dashboard
11// pattern (composes Mermaid + ADRs + benchmark tables in one
12// document like Honeycomb/Databox/ChartExpo references).
13//
14// Per [[feedback-substrate-knowledge-system-s-class-reasoning-
15// provenance-dashboard]] cardinal.
16//
17// **Quadrant:** REFERENCE (Diátaxis)
18// **Topic Type:** REFERENCE (DITA)
19// **Status:** DRAFT (D23 first stone)
20// **Trust State:** WRITTEN_UNTESTED
21// **Competitive State:** UNCLASSIFIED (no benchmark vs Databox/Grafana yet)
22
23import "nx_syscalls.nx"
24import "nx_string_ops.nx"
25import "nx_doc_decision.nx"
26import "nx_doc_incumbent.nx"
27
28// ===== Section emitters ==========================================
29
30// Top-of-dashboard header.
31// Format:
32// # <title>
33//
34// **Generated:** <timestamp_q14>
35// **Substrate primitives surveyed:** <n_primitives>
36//
37// ---
38func nx_doc_dashboard_emit_header(
39 title: *u8, n_title: i64,
40 timestamp_q14: i64,
41 n_primitives: i64
42) -> i64 {
43 if n_title <= 0 { return -1 }
44 sys_write(1, "# ", 2)
45 sys_write(1, title, n_title)
46 sys_write(1, "\n\n", 2)
47
48 sys_write(1, "**Generated:** ", 15)
49 let ts_buf: *u8 = sys_mmap(32)
50 let n_ts: i64 = nx_str_format_int(timestamp_q14, ts_buf, 32)
51 sys_write(1, ts_buf, n_ts)
52 sys_write(1, "\n", 1)
53
54 sys_write(1, "**Substrate primitives surveyed:** ", 35)
55 let np_buf: *u8 = sys_mmap(32)
56 let n_np: i64 = nx_str_format_int(n_primitives, np_buf, 32)
57 sys_write(1, np_buf, n_np)
58 sys_write(1, "\n\n---\n\n", 7)
59 return 0
60}
61
62// Section header. Format:
63// ## <label>
64//
65func nx_doc_dashboard_emit_section(label: *u8, n_label: i64) -> i64 {
66 if n_label <= 0 { return -1 }
67 sys_write(1, "## ", 3)
68 sys_write(1, label, n_label)
69 sys_write(1, "\n\n", 2)
70 return 0
71}
72
73// Substrate-state summary block. Surfaces aggregate audit metrics
74// from substrate's other audit primitives (nx_doc_census V2
75// compliance %, nx_doc_xref link rot %, cross-arch parity, etc.).
76// Caller passes the values; substrate-honest about provenance.
77//
78// Format:
79// ### Substrate-state summary
80//
81// - V2 doc compliance: <pct>%
82// - Link-rot rate: <pct>%
83// - Cross-arch parity: <n>/<m>
84// - Primitives at trust >= SUBOPTIMAL: <n>
85// - Primitives at competitive >= PARITY: <n>
86//
87func nx_doc_dashboard_emit_substrate_state(
88 v2_compliance_pct: i64,
89 link_rot_pct: i64,
90 cross_arch_passing: i64,
91 cross_arch_total: i64,
92 n_primitives_trust_ok: i64,
93 n_primitives_competitive_ok: i64
94) {
95 sys_write(1, "### Substrate-state summary\n\n", 30)
96
97 let buf: *u8 = sys_mmap(32)
98 var n: i64 = 0
99
100 sys_write(1, "- V2 doc compliance: ", 21)
101 n = nx_str_format_int(v2_compliance_pct, buf, 32)
102 sys_write(1, buf, n)
103 sys_write(1, "%\n", 2)
104
105 sys_write(1, "- Link-rot rate: ", 21)
106 n = nx_str_format_int(link_rot_pct, buf, 32)
107 sys_write(1, buf, n)
108 sys_write(1, "%\n", 2)
109
110 sys_write(1, "- Cross-arch parity: ", 21)
111 n = nx_str_format_int(cross_arch_passing, buf, 32)
112 sys_write(1, buf, n)
113 sys_write(1, "/", 1)
114 n = nx_str_format_int(cross_arch_total, buf, 32)
115 sys_write(1, buf, n)
116 sys_write(1, "\n", 1)
117
118 sys_write(1, "- Primitives at trust >= SUBOPTIMAL: ", 37)
119 n = nx_str_format_int(n_primitives_trust_ok, buf, 32)
120 sys_write(1, buf, n)
121 sys_write(1, "\n", 1)
122
123 sys_write(1, "- Primitives at competitive >= PARITY: ", 39)
124 n = nx_str_format_int(n_primitives_competitive_ok, buf, 32)
125 sys_write(1, buf, n)
126 sys_write(1, "\n\n", 2)
127}
128
129// Footer: timestamp + cardinal reference. Format:
130// ---
131//
132// *Dashboard generated by nx_doc_dashboard (D23, V5 doctrine).*
133// *Per [[feedback-substrate-knowledge-system-s-class-...]]*
134//
135func nx_doc_dashboard_emit_footer() {
136 sys_write(1, "---\n\n", 5)
137 sys_write(1, "*Dashboard generated by `nx_doc_dashboard` (D23, V5 doctrine).*\n", 64)
138 sys_write(1, "*Composes nx_doc_decision (D20) + nx_doc_incumbent (D21+D22).*\n", 63)
139}
140
141// ===== Orchestrator ==============================================
142//
143// Renders a complete dashboard document. Takes:
144// - title + timestamp + primitive count
145// - substrate-state metrics (V2 compliance, link rot, etc.)
146// - array of decisions (NxDecisionRecord)
147// - array of incumbent tables (NxIncumbentTable)
148//
149// Emits in order: header -> substrate state -> decisions section ->
150// incumbent tables section -> footer.
151
152func nx_doc_dashboard_compose(
153 title: *u8, n_title: i64,
154 timestamp_q14: i64,
155 n_primitives: i64,
156 v2_compliance_pct: i64,
157 link_rot_pct: i64,
158 cross_arch_passing: i64,
159 cross_arch_total: i64,
160 n_primitives_trust_ok: i64,
161 n_primitives_competitive_ok: i64,
162 decisions: *NxDecisionRecord,
163 n_decisions: i64,
164 tables: *NxIncumbentTable,
165 n_tables: i64
166) -> i64 {
167 if nx_doc_dashboard_emit_header(title, n_title, timestamp_q14, n_primitives) != 0 {
168 return -1
169 }
170
171 // Section 1: Substrate-state summary
172 nx_doc_dashboard_emit_substrate_state(
173 v2_compliance_pct, link_rot_pct,
174 cross_arch_passing, cross_arch_total,
175 n_primitives_trust_ok, n_primitives_competitive_ok
176 )
177
178 // Section 2: Decisions
179 if n_decisions > 0 {
180 sys_write(1, "---\n\n", 5)
181 nx_doc_dashboard_emit_section("Decisions (ADR chain)", 21)
182 var i: i64 = 0
183 while i < n_decisions {
184 let dr: *NxDecisionRecord = ((decisions as *u8) + (i * 128)) as *NxDecisionRecord
185 nx_decision_record_emit(dr)
186 i = i + 1
187 }
188 }
189
190 // Section 3: Incumbent tables
191 if n_tables > 0 {
192 sys_write(1, "---\n\n", 5)
193 nx_doc_dashboard_emit_section("Multi-incumbent comparisons", 27)
194 var j: i64 = 0
195 while j < n_tables {
196 let tr: *NxIncumbentTable = ((tables as *u8) + (j * 64)) as *NxIncumbentTable
197 nx_incumbent_table_emit(tr)
198 j = j + 1
199 }
200 }
201
202 nx_doc_dashboard_emit_footer()
203 return 0
204}
205
206// ===== File-output variant =======================================
207//
208// Opens `path` for writing (O_WRONLY|O_CREAT|O_TRUNC, mode 0o644),
209// redirects fd 1 (stdout) to the file via sys_dup3, calls
210// nx_doc_dashboard_compose, then restores stdout.
211//
212// This is what gives substrate's dashboard PERSISTENT VALUE -- it
213// writes to a known file the user can open in any markdown viewer
214// (VS Code preview / GitHub render / Obsidian / etc.). Without
215// this, dashboards exist only on stdout during a single qemu run.
216//
217// Substrate-honest: nests sys_dup3 carefully so partial-failure
218// states still restore stdout before returning.
219//
220// Return codes:
221// 0 success
222// -100 open failed
223// -101 first dup3 (save stdout) failed
224// -102 second dup3 (redirect stdout) failed
225// other compose's return code
226
227func nx_doc_dashboard_compose_to_file(
228 path: *u8,
229 title: *u8, n_title: i64,
230 timestamp_q14: i64,
231 n_primitives: i64,
232 v2_compliance_pct: i64,
233 link_rot_pct: i64,
234 cross_arch_passing: i64,
235 cross_arch_total: i64,
236 n_primitives_trust_ok: i64,
237 n_primitives_competitive_ok: i64,
238 decisions: *NxDecisionRecord,
239 n_decisions: i64,
240 tables: *NxIncumbentTable,
241 n_tables: i64
242) -> i64 {
243 // mode 420 = 0o644 (rw-r--r--)
244 let fd: i64 = sys_openat_wr(path, 420)
245 if fd < 0 { return -100 }
246
247 // Save original stdout to fd 100
248 let save_rc: i64 = sys_dup3(1, 100, 0)
249 if save_rc < 0 {
250 sys_close(fd)
251 return -101
252 }
253
254 // Redirect stdout (fd 1) to the file
255 let redir_rc: i64 = sys_dup3(fd, 1, 0)
256 if redir_rc < 0 {
257 sys_dup3(100, 1, 0)
258 sys_close(100)
259 sys_close(fd)
260 return -102
261 }
262
263 // Render the dashboard -- now writes to the file
264 let rc: i64 = nx_doc_dashboard_compose(
265 title, n_title, timestamp_q14, n_primitives,
266 v2_compliance_pct, link_rot_pct,
267 cross_arch_passing, cross_arch_total,
268 n_primitives_trust_ok, n_primitives_competitive_ok,
269 decisions, n_decisions,
270 tables, n_tables
271 )
272
273 // Restore stdout from fd 100
274 sys_dup3(100, 1, 0)
275 sys_close(100)
276 sys_close(fd)
277
278 return rc
279}