`nx_room_abr.nx` source

↩ module page · 155 lines · 7412 B
1// nx_room_abr.nx -- X-ROOM ABR (GEN-ROOM-room-adaptive-bitrate): sovereign
2// DETERMINISTIC INTEGER adaptive-bitrate controller for the video room.
3//
4// EXCEED axis vs Zoom/LiveKit/WebRTC heuristic+ML ABR: every layer decision is a
5// REPRODUCIBLE integer verdict (audit-replayable -- replay the same link trace, get
6// the same layers), and the anti-oscillation HYSTERESIS is a deterministic rule, not
7// a tuned black box. Discipline = CLIMB-SLOW / DROP-FAST (the safe-ABR invariant):
8// ramp up one layer only on SUSTAINED headroom, drop immediately on loss/congestion.
9//
10// MODEL (all bitrates in kbps, loss in per-mille):
11//   ladder[]  = quality layers low->high, bitrate each (DATA, rule 25 -- improve rows, never strip)
12//   state[3]  = [ est_bw(EWMA), layer(index), up_count(sustained-headroom ticks) ]
13//   per tick  : measured throughput meas_bw + loss_pm
14//   est_bw    = (3*est_bw + meas_bw)/4   (integer EWMA; smooths jitter)
15//   safe_bw   = est_bw * ABR_SAFE_PCT/100  (climb only into headroom, never to the edge)
16//   DROP (fast): loss_pm>ABR_LOSS_PM OR ladder[layer]>est_bw  -> layer-1, up_count=0
17//   UP (slow)  : highest layer that fits safe_bw is above current -> up_count++,
18//                step up ONE layer only when up_count>=hyst_up (use_hyst=0 disables = the control)
19//
20// main() is the SELF-VALIDATING GATE: A climb-to-top, B collapse-drops-fast,
21// C oscillation flaps LESS with hysteresis than without (the anti-oscillation exceed),
22// tamper a ladder rung -> outcome diverges. Evidence -> knowledge/status/room_abr.log.
23// license_tier: ORIGINAL
24import "nx_syscalls.nx"
25const ABR_MAGIC_1500: i64 = 1500
26const ABR_MAGIC_3000: i64 = 3000
27const ABR_MAGIC_4000: i64 = 4000
28const ABR_MAGIC_999999: i64 = 999999
29
30const ABR_LOG:      *u8 = "knowledge/status/room_abr.log"
31const ABR_SAFE_PCT: i64 = 85    // climb only into 85% of the estimate (headroom)
32const ABR_LOSS_PM:  i64 = 50    // > 5% loss = congestion -> drop now
33
34func aw(fd: i64, s: *u8) -> i64 { var n: i64 = 0; while s[n] != (0 as u8) { n = n + 1 } sys_write(fd, s, n); return 0 }
35func awn(fd: i64, v: i64) -> i64 { let bb: *u8 = sys_mmap(28); var m: i64=v; if m<0 {m=0-m; sys_write(fd,"-" as *u8,1)}; let t: *u8 = sys_mmap(28); var k: i64=0; if m==0 {t[0]=48;k=1}; while m>0 {t[k]=(48+(m%10)) as u8; m=m/10; k=k+1}; var i: i64=0; while i<k {bb[i]=t[k-1-i]; i=i+1}; sys_write(fd, bb, k); return 0 }
36
37// highest ladder layer whose bitrate <= cap (layer 0 is the lowest, always fits).
38func abr_top_layer(ladder: *i64, n: i64, cap: i64) -> i64 {
39    var L: i64 = 0
40    var i: i64 = 0
41    while i < n { if ladder[i] <= cap { L = i } i = i + 1 }
42    return L
43}
44
45// one control tick; mutates state in place; returns the new layer.
46func abr_step(ladder: *i64, n: i64, state: *i64, meas_bw: i64, loss_pm: i64, hyst_up: i64, use_hyst: i64) -> i64 {
47    let est: i64 = (state[0] * 3 + meas_bw) / 4
48    state[0] = est
49    var layer: i64 = state[1]
50    var upc: i64 = state[2]
51    let safe: i64 = est * ABR_SAFE_PCT / 100
52    if loss_pm > ABR_LOSS_PM {
53        if layer > 0 { layer = layer - 1 }
54        upc = 0
55    } else {
56        if ladder[layer] > est {
57            if layer > 0 { layer = layer - 1 }
58            upc = 0
59        } else {
60            let top: i64 = abr_top_layer(ladder, n, safe)
61            if top > layer {
62                upc = upc + 1
63                if use_hyst == 0 {
64                    layer = layer + 1
65                    upc = 0
66                } else {
67                    if upc >= hyst_up { layer = layer + 1; upc = 0 }
68                }
69            } else {
70                upc = 0
71            }
72        }
73    }
74    state[1] = layer
75    state[2] = upc
76    return layer
77}
78
79// run a meas[]/loss[] trace of length T; out[0]=final layer, out[1]=#layer-changes.
80func abr_run(ladder: *i64, n: i64, T: i64, meas: *i64, loss: *i64, hyst_up: i64, use_hyst: i64, init_layer: i64, init_bw: i64, out: *i64) -> i64 {
81    let state: *i64 = sys_mmap(8 * 3) as *i64
82    state[0] = init_bw; state[1] = init_layer; state[2] = 0
83    var prev: i64 = init_layer
84    var changes: i64 = 0
85    var t: i64 = 0
86    while t < T {
87        let L: i64 = abr_step(ladder, n, state, meas[t], loss[t], hyst_up, use_hyst)
88        if L != prev { changes = changes + 1; prev = L }
89        t = t + 1
90    }
91    out[0] = state[1]
92    out[1] = changes
93    return 0
94}
95
96func main() -> i64 {
97    let ladder: *i64 = sys_mmap(8 * 5) as *i64
98    ladder[0]=64; ladder[1]=256; ladder[2]=700; ladder[3]=ABR_MAGIC_1500; ladder[4]=ABR_MAGIC_3000
99    let meas: *i64 = sys_mmap(8 * 32) as *i64
100    let loss: *i64 = sys_mmap(8 * 32) as *i64
101    let out:  *i64 = sys_mmap(8 * 4) as *i64
102    var ok: i64 = 1
103
104    // --- A: sustained high bw -> climb to the top layer, GRADUALLY (one rung/sustained-headroom) ---
105    var i: i64 = 0
106    while i < 16 { meas[i]=ABR_MAGIC_4000; loss[i]=0; i=i+1 }
107    abr_run(ladder, 5, 16, meas, loss, 2, 1, 0, 64, out)
108    let aL: i64 = out[0]; let aC: i64 = out[1]
109    if aL != 4 { ok = 0 }      // reaches top
110    if aC < 4 { ok = 0 }       // climbed rung-by-rung (>=4 transitions 0->4), not one jump
111
112    // --- B: start at top, bw COLLAPSES -> drop fast toward the floor ---
113    i = 0
114    while i < 14 { meas[i]=80; loss[i]=0; i=i+1 }
115    abr_run(ladder, 5, 14, meas, loss, 2, 1, 4, ABR_MAGIC_3000, out)
116    let bL: i64 = out[0]
117    if bL > 1 { ok = 0 }       // collapsed from 4 to the bottom rung(s)
118
119    // --- C: bw OSCILLATES in 2-tick high/low blocks across the layer-3 boundary; hysteresis
120    //        (needs 3 sustained headroom ticks) must NOT climb on a 2-tick spike, so it flaps
121    //        LESS than the no-hysteresis control that climbs on every spike ---
122    i = 0
123    while i < 16 { if (i % 4) < 2 { meas[i]=ABR_MAGIC_4000 } else { meas[i]=300 } loss[i]=0; i=i+1 }
124    abr_run(ladder, 5, 16, meas, loss, 3, 1, 2, 1000, out)   // hysteresis ON (3 sustained to climb)
125    let cHyst: i64 = out[1]
126    abr_run(ladder, 5, 16, meas, loss, 3, 0, 2, 1000, out)   // neg-control: hysteresis OFF (climbs instantly)
127    let cNo: i64 = out[1]
128    if cHyst >= cNo { ok = 0 } // the anti-oscillation EXCEED: hysteresis strictly reduces flapping
129
130    // --- tamper: corrupt a ladder rung -> the climb outcome MUST diverge from A (no constant output) ---
131    ladder[3] = ABR_MAGIC_999999
132    i = 0
133    while i < 16 { meas[i]=ABR_MAGIC_4000; loss[i]=0; i=i+1 }
134    abr_run(ladder, 5, 16, meas, loss, 2, 1, 0, 64, out)
135    let tL: i64 = out[0]
136    if tL == aL { ok = 0 }
137
138    aw(1, "ROOMABRGATE A_final=" as *u8); awn(1, aL); aw(1, " A_changes=" as *u8); awn(1, aC)
139    aw(1, " B_final=" as *u8); awn(1, bL)
140    aw(1, " C_hyst_flaps=" as *u8); awn(1, cHyst); aw(1, " C_nohyst_flaps=" as *u8); awn(1, cNo)
141    aw(1, " tamper_final=" as *u8); awn(1, tL)
142    if ok == 1 { aw(1, " verdict=GREEN\n" as *u8) } else { aw(1, " verdict=RED\n" as *u8) }
143
144    let lf: i64 = sys_openat_append(ABR_LOG, 420)
145    if lf >= 0 {
146        aw(lf, "ROOMABRGATE A_final=" as *u8); awn(lf, aL); aw(lf, " A_changes=" as *u8); awn(lf, aC)
147        aw(lf, " B_final=" as *u8); awn(lf, bL)
148        aw(lf, " C_hyst_flaps=" as *u8); awn(lf, cHyst); aw(lf, " C_nohyst_flaps=" as *u8); awn(lf, cNo)
149        aw(lf, " tamper_final=" as *u8); awn(lf, tL)
150        if ok == 1 { aw(lf, " verdict=GREEN\n" as *u8) } else { aw(lf, " verdict=RED\n" as *u8) }
151        sys_close(lf)
152    }
153    if ok == 1 { sys_exit(0) } else { sys_exit(1) }
154    return 0
155}
nx_room_abr.nx source

`nx_room_abr.nx` source
