nx_etg_tournament.nx source
↩ module page · 136 lines · 5330 B
1// nx_etg_tournament.nx -- multivariate tournament selector.
2//
3// E2 first stone of NISHI_ETG_ROADMAP.md. Implements the selection
4// logic that consumes pre-computed variant results (correctness +
5// perf_metric per variant) and picks the empirical winner. Composes
6// E1 nx_etg.nx attestation primitive to emit a ProvenanceLinked
7// decision record per selection.
8//
9// This brick is the SELECTION LAYER. The DISPATCH layer (actually
10// running N kernel variants on calibration corpus + measuring their
11// outcomes) is E2.5; first real per-tier probes (E3+) wire dispatch
12// + selection + attestation into per-probe pipelines.
13//
14// Why pre-computed results: separates correctness/perf measurement
15// (which differs per probe family, per silicon) from the SELECTION
16// algorithm (which is universal: correctness gate + argmin perf +
17// deterministic tie-break + no-winner detection). The selection
18// logic ships now + KAT-verified; dispatch lands per-probe.
19//
20// Composes:
21// [[NISHI_ETG_ROADMAP]] E2 (this is the first stone)
22// nx_etg.nx (NxEtgEntry attestation; E1 SHIPPED)
23// [[feedback-no-false-ok-substrate-honesty-audit]] (no-winner
24// returns NX_ETG_TVAL_NO_WINNER deterministically; never
25// silently picks a failed variant)
26// [[NISHI_SELF_ASSEMBLY_ROADMAP]] Section 2.1 Petabricks
27// choice-grammar (the variant manifest shape this implements)
28// Cardinal 13 (tournament selections are ProvenanceLinked + tombstone
29// on re-selection; never overwrite prior decisions)
30//
31// API:
32// nx_etg_tournament_select(variant_ids, correctness, perf_metric, n) -> i64
33// Returns winning variant_id (>= 0) or NX_ETG_TVAL_NO_WINNER.
34//
35// nx_etg_tournament_attest(entry, silicon_serial, variants_tested,
36// winning_variant, probe_kind, selector_version,
37// timestamp_q14) -> i64
38// Emits an NxEtgEntry recording the selection. Composes
39// nx_etg_entry_init with outcome = RECLAIMED (the substrate
40// selected the empirical winner over any vendor-marketed default).
41
42// nx_safety_envelope:
43// intended_use: "tournament selection logic for E2; takes
44// pre-computed per-variant results, returns
45// empirical winner; never silent on no-winner
46// case; ProvenanceLinked attestation via E1"
47// sil_target: SIL2
48// evidence: [kat_correctness_gate,
49// kat_perf_argmin,
50// kat_tie_break_first_deterministic,
51// kat_no_winner_returns_sentinel,
52// kat_attestation_via_e1_entry_init]
53// hazard_register: [bug-tape-tie-break-nondeterministic,
54// bug-tape-failed-variant-silently-selected,
55// bug-tape-empty-variant-set]
56// verdict: NOT_YET_EVALUATED
57
58import "nx_syscalls.nx"
59import "nx_etg.nx"
60
61// ===== Sentinel + correctness constants ============================
62
63const NX_ETG_TVAL_NO_WINNER: i64 = -1
64const NX_ETG_TVAL_PASS: i64 = 1
65const NX_ETG_TVAL_FAIL: i64 = 0
66
67// ===== Tournament selector ========================================
68//
69// Walks N variants; among those with correctness == PASS, returns
70// the variant_id with the minimum perf_metric (smaller = better;
71// e.g., ns/op, cycles/byte, μs latency).
72//
73// Tie-break convention: on equal perf_metric, the variant earlier
74// in the input array wins (deterministic + ProvenanceLinked-replayable).
75//
76// Empty array (n <= 0) or all-failed-correctness returns
77// NX_ETG_TVAL_NO_WINNER. Never silently picks a failed variant.
78func nx_etg_tournament_select(
79 variant_ids: *i64,
80 correctness: *i64,
81 perf_metric: *i64,
82 n: i64
83) -> i64 {
84 if n <= 0 { return NX_ETG_TVAL_NO_WINNER }
85 var i: i64 = 0
86 var winner_id: i64 = NX_ETG_TVAL_NO_WINNER
87 var winner_perf: i64 = 0
88 var have_winner: i64 = 0
89 while i < n {
90 if correctness[i] == NX_ETG_TVAL_PASS {
91 if have_winner == 0 {
92 winner_id = variant_ids[i]
93 winner_perf = perf_metric[i]
94 have_winner = 1
95 } else {
96 if perf_metric[i] < winner_perf {
97 winner_id = variant_ids[i]
98 winner_perf = perf_metric[i]
99 }
100 }
101 }
102 i = i + 1
103 }
104 return winner_id
105}
106
107// ===== Tournament attestation =====================================
108//
109// Emits an NxEtgEntry for the selection. Caller provides struct
110// storage + selection inputs. outcome = RECLAIMED because the
111// substrate just selected an empirical winner -- by definition,
112// reclamation of "which variant the silicon actually runs best."
113//
114// Returns 0 on success, negative on invalid args (propagated from
115// nx_etg_entry_init).
116func nx_etg_tournament_attest(
117 entry: *NxEtgEntry,
118 silicon_serial: i64,
119 variants_tested: i64,
120 winning_variant: i64,
121 probe_kind: i64,
122 selector_version: i64,
123 timestamp_q14: i64
124) -> i64 {
125 return nx_etg_entry_init(
126 entry,
127 silicon_serial,
128 probe_kind,
129 NX_ETG_CLAIM_PRIOR_CALIBRATION,
130 variants_tested,
131 winning_variant,
132 NX_ETG_OUTCOME_RECLAIMED,
133 selector_version,
134 timestamp_q14
135 )
136}