nx_race_timing.nx source
↩ module page · 153 lines · 6636 B
1// nx_race_timing.nx -- sealed-enum race timing mode + helpers.
2//
3// User directive 2026-05-16:
4// "i want visualization with a manual and scheduled and automatic
5// capbility flag so we can race when we want and do all three
6// aka manual event driven scheduled and whatever other is s class
7// timing"
8//
9// Four-pillar discipline for the racing crew's HOW-IT-FIRES question:
10//
11// HAVE -- every race today fires manually via bench/*.sh
12// FIX -- this file: sealed-enum 8 timing modes
13// PREVENTION -- .race_telemetry.tsv gains timing_mode column;
14// nx_race_visualizer.nx surfaces unused modes
15// ADDITIVE -- MANUAL stays the default; 7 other modes ADD
16// options without removing manual
17//
18// The eight S-class racing-timing modes:
19//
20// MANUAL -- user invokes via CLI; ad-hoc, on-demand
21// EVENT -- filesystem watch, git commit hook, IPC signal
22// (reactive to external state change)
23// SCHEDULED -- cron-style time trigger; runs at named clock
24// positions (e.g., daily at 02:00)
25// CONTINUOUS -- every tick of a fixed period (e.g., every 60s)
26// -- the "always-on" streaming mode
27// IDLE -- fires when system is otherwise idle; lowest
28// priority; never preempts user work
29// THRESHOLD -- fires when a metric crosses a configured bound
30// (latency p99 > X, error rate > Y, ...)
31// PROBABILISTIC -- samples a fraction of race-opportunities; used
32// when full-rate races would be too expensive
33// QUORUM -- fires only when N out of M graders agree a
34// race is currently warranted; used to dampen
35// thrash from any single grader
36//
37// Each mode is a distinct discipline. This file enumerates them
38// as a SEALED ENUM (NX_RACE_TIMING_N is the count). Callers
39// (bench scripts, daemons, the ICL) pick a mode + record it in
40// .race_telemetry.tsv so the visualizer can show which modes are
41// well-exercised vs starved.
42//
43// Per cardinal user-owns-every-bit: substrate carries the SEALED
44// ENUM (8 modes + helpers). Which modes are actually ENABLED on
45// a given hardware is a caller decision (a 16 KB MCU might run
46// only MANUAL + EVENT; a 64-core server might run all 8).
47//
48// nx_capability_claims:
49// needs: [sealed_enum, integer_compare]
50// provides: [race_timing_enum, race_timing_name, race_timing_valid]
51// safety: [no_unchecked_deref, no_floating_point, no_syscall,
52// bit_equal_reproducible, target_agnostic, kind_isolated]
53// verdict: [sealed_enum_8_state, no_silent_failure]
54// license: ORIGINAL
55// kind: racing_crew_specialist
56// sss: [S0, S6, S7]
57
58// ---- Sealed enum: race timing mode ---------------------------------
59
60const NX_RACE_MANUAL: i64 = 0
61const NX_RACE_EVENT: i64 = 1
62const NX_RACE_SCHEDULED: i64 = 2
63const NX_RACE_CONTINUOUS: i64 = 3
64const NX_RACE_IDLE: i64 = 4
65const NX_RACE_THRESHOLD: i64 = 5
66const NX_RACE_PROBABILISTIC: i64 = 6
67const NX_RACE_QUORUM: i64 = 7
68const NX_RACE_TIMING_N: i64 = 8
69
70func nx_race_timing_is_valid(t: i64) -> i64 {
71 if t < 0 { return 0 }
72 if t >= NX_RACE_TIMING_N { return 0 }
73 return 1
74}
75
76// Returns a static *u8 name for a timing mode, or "INVALID" if not
77// a valid mode. Caller does NOT free the returned pointer.
78func nx_race_timing_name(t: i64) -> *u8 {
79 if t == NX_RACE_MANUAL { return "MANUAL" as *u8 }
80 if t == NX_RACE_EVENT { return "EVENT" as *u8 }
81 if t == NX_RACE_SCHEDULED { return "SCHEDULED" as *u8 }
82 if t == NX_RACE_CONTINUOUS { return "CONTINUOUS" as *u8 }
83 if t == NX_RACE_IDLE { return "IDLE" as *u8 }
84 if t == NX_RACE_THRESHOLD { return "THRESHOLD" as *u8 }
85 if t == NX_RACE_PROBABILISTIC { return "PROBABILISTIC" as *u8 }
86 if t == NX_RACE_QUORUM { return "QUORUM" as *u8 }
87 return "INVALID" as *u8
88}
89
90// Length of the returned name string (so visualizer can column-align).
91func nx_race_timing_name_len(t: i64) -> i64 {
92 if t == NX_RACE_MANUAL { return 6 }
93 if t == NX_RACE_EVENT { return 5 }
94 if t == NX_RACE_SCHEDULED { return 9 }
95 if t == NX_RACE_CONTINUOUS { return 10 }
96 if t == NX_RACE_IDLE { return 4 }
97 if t == NX_RACE_THRESHOLD { return 9 }
98 if t == NX_RACE_PROBABILISTIC { return 13 }
99 if t == NX_RACE_QUORUM { return 6 }
100 return 7 // "INVALID"
101}
102
103// Parse a single timing-mode name back to its enum value. Returns
104// NX_RACE_TIMING_N (invalid sentinel) if the buffer doesn't match
105// any known mode. buf must be NUL-or-bound-terminated within n.
106func nx_race_timing_parse(buf: *u8, n: i64) -> i64 {
107 if buf == (0 as *u8) { return NX_RACE_TIMING_N }
108 if n <= 0 { return NX_RACE_TIMING_N }
109 var i: i64 = 0
110 while i < NX_RACE_TIMING_N {
111 let name: *u8 = nx_race_timing_name(i)
112 let name_len: i64 = nx_race_timing_name_len(i)
113 if name_len == n {
114 var j: i64 = 0
115 var eq: i64 = 1
116 while j < n {
117 if buf[j] != name[j] { eq = 0; j = n }
118 j = j + 1
119 }
120 if eq == 1 { return i }
121 }
122 i = i + 1
123 }
124 return NX_RACE_TIMING_N
125}
126
127// Cardinality predicate: returns 1 if the timing mode is in the
128// "reactive" family (EVENT, IDLE, THRESHOLD, QUORUM) -- modes that
129// fire in response to external state. Returns 0 for the "scheduled"
130// family (MANUAL, SCHEDULED, CONTINUOUS, PROBABILISTIC) -- modes
131// that fire on a clock or user choice. Useful for bench scripts
132// that want to enable/disable a whole class.
133func nx_race_timing_is_reactive(t: i64) -> i64 {
134 if t == NX_RACE_EVENT { return 1 }
135 if t == NX_RACE_IDLE { return 1 }
136 if t == NX_RACE_THRESHOLD { return 1 }
137 if t == NX_RACE_QUORUM { return 1 }
138 return 0
139}
140
141// Returns 1 if the timing mode requires CONFIGURATION beyond the
142// enum value itself (CONTINUOUS needs a period, SCHEDULED needs a
143// cron spec, THRESHOLD needs a bound, PROBABILISTIC needs a rate,
144// QUORUM needs N+M). MANUAL/EVENT/IDLE need only the enum.
145// Visualizer uses this to mark which entries are mis-configured.
146func nx_race_timing_needs_config(t: i64) -> i64 {
147 if t == NX_RACE_SCHEDULED { return 1 }
148 if t == NX_RACE_CONTINUOUS { return 1 }
149 if t == NX_RACE_THRESHOLD { return 1 }
150 if t == NX_RACE_PROBABILISTIC { return 1 }
151 if t == NX_RACE_QUORUM { return 1 }
152 return 0
153}