nx_mediapath.nx source
↩ module page · 124 lines · 5303 B
1// nx_mediapath.nx -- self-healing BEST-MEDIA-PATH selection: the unifier.
2// Generalizes the proven self-heal decision pattern (nx_netscope_heal:
3// KEEP/SWITCH/GIVEUP + anti-flap hysteresis) from "best DNS resolver" to
4// "best media path/relay", ranking candidates by MEASURED link quality
5// (nx_linkqual lq_score) instead of reachability. So a game match or a
6// video call given N candidate paths auto-migrates to the best-quality one
7// when the current path degrades -- WITHOUT flapping on noise.
8//
9// Pure/deterministic (decide over a frozen set of LinkFlows) -> KAT-able.
10// Integer-only, imports only nx_linkqual (-> nx_syscalls); sovereign, no
11// new deps. Concepts: Happy-Eyeballs best-of-N + hysteresis (already
12// researched for the resolver case); quality = the link-quality score.
13//
14// license_tier: ORIGINAL
15
16import "nx_linkqual.nx"
17
18const MP_KEEP: i64 = 0
19const MP_SWITCH: i64 = 1
20const MP_GIVEUP: i64 = 2
21
22const MP_R_HEALTHY: i64 = 0 // incumbent still best -> stay
23const MP_R_DEGRADED: i64 = 1 // incumbent dropped below usable -> move to best
24const MP_R_BETTER: i64 = 2 // a meaningfully better path appeared
25const MP_R_NONE: i64 = 3 // no usable path (stuck on least-bad / no candidates)
26
27// usable-quality floor + switch hysteresis margin (score points).
28// Bootstrap defaults -> svc-config (CLAUDE.md 11).
29const MP_QUALITY_FLOOR: i64 = 40 // below = FAIR/POOR boundary = unusable
30const MP_SWITCH_MARGIN: i64 = 15 // only switch a usable path for >=15 pts gain
31
32struct MediaDecision { action: i64, target_idx: i64, target_score: i64, reason: i64 }
33const MP_DECISION_BYTES: i64 = 32
34
35// flows = array of *LinkFlow (i64 pointer values), n candidates.
36// Returns index of the HIGHEST lq_score path (deterministic: ties -> lowest index).
37func mp_select_best(flows: *i64, n: i64) -> i64 {
38 var best: i64 = 0 - 1
39 var best_score: i64 = 0 - 1
40 var i: i64 = 0
41 while i < n {
42 let fl: *LinkFlow = (flows[i]) as *LinkFlow
43 let sc: i64 = lq_score(fl)
44 if sc > best_score { best_score = sc; best = i }
45 i = i + 1
46 }
47 return best
48}
49
50func mp_decide(flows: *i64, n: i64, incumbent_idx: i64, out: *MediaDecision) -> i64 {
51 out.action = MP_GIVEUP
52 out.target_idx = 0 - 1
53 out.target_score = 0
54 out.reason = MP_R_NONE
55 if n <= 0 { return MP_GIVEUP }
56
57 let best: i64 = mp_select_best(flows, n)
58 let bfl: *LinkFlow = (flows[best]) as *LinkFlow
59 let bscore: i64 = lq_score(bfl)
60
61 var inc_valid: i64 = 0
62 var inc_score: i64 = 0
63 if incumbent_idx >= 0 {
64 if incumbent_idx < n {
65 let ifl: *LinkFlow = (flows[incumbent_idx]) as *LinkFlow
66 inc_score = lq_score(ifl)
67 inc_valid = 1
68 }
69 }
70
71 if inc_valid == 0 {
72 // no current path set -> adopt the best
73 out.action = MP_SWITCH; out.target_idx = best; out.target_score = bscore; out.reason = MP_R_DEGRADED
74 return MP_SWITCH
75 }
76 if inc_score < MP_QUALITY_FLOOR {
77 // current path degraded below usable
78 if best != incumbent_idx {
79 out.action = MP_SWITCH; out.target_idx = best; out.target_score = bscore; out.reason = MP_R_DEGRADED
80 return MP_SWITCH
81 }
82 // incumbent IS the least-bad and it's still below the floor: nothing better to do
83 out.action = MP_KEEP; out.target_idx = incumbent_idx; out.target_score = inc_score; out.reason = MP_R_NONE
84 return MP_KEEP
85 }
86 // incumbent usable: switch only for a MEANINGFUL gain (anti-flap)
87 if best != incumbent_idx {
88 if (bscore - inc_score) >= MP_SWITCH_MARGIN {
89 out.action = MP_SWITCH; out.target_idx = best; out.target_score = bscore; out.reason = MP_R_BETTER
90 return MP_SWITCH
91 }
92 }
93 out.action = MP_KEEP; out.target_idx = incumbent_idx; out.target_score = inc_score; out.reason = MP_R_HEALTHY
94 return MP_KEEP
95}
96
97// easy-for-anyone media-path action line.
98func mp_render(out: *MediaDecision) -> i64 {
99 sys_write(1, " media path: ", 14)
100 if out.action == MP_KEEP {
101 if out.reason == MP_R_NONE {
102 sys_write(1, "[!!] all paths poor -- staying on the least-bad (path ", 53); lq_dec(out.target_idx)
103 sys_write(1, ", ", 2); lq_band_word(lq_verdict_band(out.target_score)); sys_write(1, ")\n", 2)
104 return 0
105 }
106 sys_write(1, "[OK] staying on path ", 21); lq_dec(out.target_idx)
107 sys_write(1, " (", 2); lq_band_word(lq_verdict_band(out.target_score)); sys_write(1, ", ", 2)
108 lq_dec(out.target_score); sys_write(1, "/100)\n", 6)
109 return 0
110 }
111 if out.action == MP_SWITCH {
112 if out.reason == MP_R_DEGRADED {
113 sys_write(1, "[!!] your path was degrading -- switched to path ", 49); lq_dec(out.target_idx)
114 sys_write(1, " (", 2); lq_band_word(lq_verdict_band(out.target_score)); sys_write(1, "). Quality restored.\n", 21)
115 return 0
116 }
117 sys_write(1, "[OK] found a better path -- moved to path ", 42); lq_dec(out.target_idx)
118 sys_write(1, " (", 2); lq_band_word(lq_verdict_band(out.target_score)); sys_write(1, ", ", 2)
119 lq_dec(out.target_score); sys_write(1, "/100)\n", 6)
120 return 0
121 }
122 sys_write(1, "[XX] no media path available.\n", 30)
123 return 0
124}