nx_swarm_arbitrate.nx source
↩ module page · 119 lines · 6835 B
1// nx_swarm_arbitrate.nx -- SWARM FABRIC cross-workstream RESOURCE ARBITRATION (SF-ARB): the layer that
2// keeps COMPETING workstreams (a gen job, LLM inference, model training) sharing the ONE heterogeneous
3// pool FAIRLY -- no workstream monopolizes, none starves, high-priority preempts low. This is the
4// orchestration north-star's R-ORCH-4 (competing-workstream arbitration) for RESOURCES, and it FEEDS
5// nx_resource_arbiter (which already models VRAM/RAM/CPU/GPU allocation with max-share fairness +
6// priority + preemption but was "fed by nothing").
7//
8// COMPOSES (check-before-build 2026-07-15): nx_resource_arbiter (nx_ra_new / set_budget / set_max_share /
9// request / preempt / total_held) -- verified compiles+gates today. This organ is the FEED (pool budgets
10// from fleet totals = the beacon telemetry) + the workstream-request driver + the fairness gate. It does
11// NOT reimplement allocation -- that's the arbiter's job (rule 15 DRY / rule 9 single-responsibility:
12// pack places chunks on participants; THIS shares the pool across workstreams; the arbiter allocates).
13//
14// ★★THE LIAR-KILLERS: (1) NO-MONOPOLY -- a workstream requesting > max-share of a resource is DENIED_MAX_
15// SHARE (can't take the whole pool). (2) NO-STARVATION -- after the greedy high-demand workstream is
16// capped, a lower one still gets a (partial) grant, never zero-by-design. (3) BUDGET-HONEST -- total
17// granted never exceeds the pool. (4) PRIORITY-PREEMPTION -- a higher-priority workstream reclaims from a
18// lower one. (5) determinism.
19// nx_swarm_arbitrate -- self-gate: the competing-workstream fairness scenario
20// license_tier: ORIGINAL expect_exit:0
21import "nx_resource_arbiter.nx"
22const K_MAGIC_1000000: i64 = 1000000
23const K_MAGIC_20000: i64 = 20000
24const K_MAGIC_15000: i64 = 15000
25const K_MAGIC_10000: i64 = 10000
26const K_MAGIC_8000: i64 = 8000
27const K_MAGIC_5000: i64 = 5000
28const K_MAGIC_2000: i64 = 2000
29const K_MAGIC_3000: i64 = 3000
30
31func sa_puts(s: *u8) -> i64 { var n: i64 = 0; while s[n] != (0 as u8) { n = n + 1 } sys_write(1, s, n); return 0 }
32func sa_putn(v: i64) -> i64 {
33 let b: *u8 = sys_mmap(28)
34 var m: i64 = v
35 if m < 0 { sys_write(1, "-" as *u8, 1); m = 0 - m }
36 let t: *u8 = sys_mmap(28)
37 var k: i64 = 0
38 if m == 0 { t[0] = 48 as u8; k = 1 }
39 while m > 0 { t[k] = (48 + (m % 10)) as u8; m = m / 10; k = k + 1 }
40 var i: i64 = 0
41 while i < k { b[i] = t[k-1-i]; i = i + 1 }
42 sys_write(1, b, k)
43 return 0
44}
45func sa_report(name: *u8, v: i64, granted: i64) -> i64 {
46 sa_puts(" " as *u8); sa_puts(name); sa_puts(" verdict=" as *u8); sa_putn(v)
47 sa_puts(" granted=" as *u8); sa_putn(granted); sa_puts("\n" as *u8)
48 return 0
49}
50
51func main() -> i64 {
52 var pass: i64 = 0
53 var total: i64 = 0
54 let now: nx_size = K_MAGIC_1000000
55 let out: *i64 = sys_mmap(8) as *i64
56
57 let a: *NxResourceArbiter = nx_ra_new(64)
58 // FEED the pool budgets from fleet totals (the beacon-telemetry feed): VRAM 20GB, CPU 15000 milli-cores.
59 nx_ra_set_budget(a, NX_RA_KIND_VRAM_BYTES, K_MAGIC_20000)
60 nx_ra_set_budget(a, NX_RA_KIND_CPU_MICROSECONDS, K_MAGIC_15000)
61 // fairness caps: no workstream gets > 50% of any resource in an epoch (512/1024).
62 nx_ra_set_max_share(a, NX_RA_KIND_VRAM_BYTES, 512)
63 nx_ra_set_max_share(a, NX_RA_KIND_CPU_MICROSECONDS, 512)
64 sa_puts("--- cross-workstream arbitration: gen(pri3) llm(pri2) train(pri1) over VRAM 20000 / CPU 15000, cap 50% ---\n" as *u8)
65
66 // T1 NO-MONOPOLY: gen (pri3) wants 15000 VRAM (>50% of 20000=10000) -> DENIED_MAX_SHARE
67 total = total + 1
68 let v1: i64 = nx_ra_request(a, 1, NX_RA_KIND_VRAM_BYTES, K_MAGIC_15000, 3, 0, out, now)
69 sa_report("gen VRAM 15000 (greedy)" as *u8, v1, out[0])
70 if v1 == NX_RA_V_DENIED_MAX_SHARE { pass = pass + 1; sa_puts("T1 no-monopoly (greedy DENIED) OK\n" as *u8) }
71
72 // T2 gen re-requests WITHIN the fair cap (10000) -> GRANTED_FULL
73 total = total + 1
74 let v2: i64 = nx_ra_request(a, 1, NX_RA_KIND_VRAM_BYTES, K_MAGIC_10000, 3, 0, out, now)
75 sa_report("gen VRAM 10000 (at cap)" as *u8, v2, out[0])
76 if v2 == NX_RA_V_GRANTED_FULL { if out[0] == K_MAGIC_10000 { pass = pass + 1; sa_puts("T2 gen-capped-grant OK\n" as *u8) } }
77
78 // T3 llm (pri2) requests 8000 VRAM -> 10000 free, 8000<cap -> GRANTED_FULL (gen did NOT starve it)
79 total = total + 1
80 let v3: i64 = nx_ra_request(a, 2, NX_RA_KIND_VRAM_BYTES, K_MAGIC_8000, 2, 0, out, now)
81 sa_report("llm VRAM 8000" as *u8, v3, out[0])
82 if v3 == NX_RA_V_GRANTED_FULL { pass = pass + 1; sa_puts("T3 llm-fair-share OK\n" as *u8) }
83
84 // T4 NO-STARVATION: train (pri1) requests 5000 -> only 2000 free -> PARTIAL 2000 (a real slice, not zero)
85 total = total + 1
86 let v4: i64 = nx_ra_request(a, 3, NX_RA_KIND_VRAM_BYTES, K_MAGIC_5000, 1, 0, out, now)
87 sa_report("train VRAM 5000" as *u8, v4, out[0])
88 if v4 == NX_RA_V_GRANTED_PARTIAL { if out[0] == K_MAGIC_2000 { pass = pass + 1; sa_puts("T4 no-starvation (train partial) OK\n" as *u8) } }
89
90 // T5 BUDGET-HONEST: total held == budget, never over
91 total = total + 1
92 let held: i64 = nx_ra_total_held(a, NX_RA_KIND_VRAM_BYTES)
93 if held == K_MAGIC_20000 { pass = pass + 1; sa_puts("T5 budget-honest (held=20000, no over-alloc) OK\n" as *u8) }
94
95 // T6 MULTI-RESOURCE: the SAME pool arbitrates CPU independently -- gen gets CPU too (5000<50% of 15000)
96 total = total + 1
97 let vc: i64 = nx_ra_request(a, 1, NX_RA_KIND_CPU_MICROSECONDS, K_MAGIC_5000, 3, 0, out, now)
98 sa_report("gen CPU 5000" as *u8, vc, out[0])
99 if vc == NX_RA_V_GRANTED_FULL { pass = pass + 1; sa_puts("T6 multi-resource (VRAM+CPU) OK\n" as *u8) }
100
101 // T7 PRIORITY-PREEMPTION: an urgent workstream (pri4) needs VRAM; pool is full -> preempt lower-pri holders
102 total = total + 1
103 let reclaimed: i64 = nx_ra_preempt(a, NX_RA_KIND_VRAM_BYTES, 4, K_MAGIC_3000)
104 sa_puts(" urgent(pri4) preempt VRAM 3000 -> reclaimed=" as *u8); sa_putn(reclaimed); sa_puts("\n" as *u8)
105 if reclaimed >= K_MAGIC_3000 { pass = pass + 1; sa_puts("T7 priority-preemption OK\n" as *u8) }
106
107 // T8 DETERMINISM: a fresh arbiter with the same setup + greedy request -> same DENIED_MAX_SHARE
108 total = total + 1
109 let b: *NxResourceArbiter = nx_ra_new(64)
110 nx_ra_set_budget(b, NX_RA_KIND_VRAM_BYTES, K_MAGIC_20000)
111 nx_ra_set_max_share(b, NX_RA_KIND_VRAM_BYTES, 512)
112 let vd: i64 = nx_ra_request(b, 1, NX_RA_KIND_VRAM_BYTES, K_MAGIC_15000, 3, 0, out, now)
113 if vd == v1 { if vd == NX_RA_V_DENIED_MAX_SHARE { pass = pass + 1; sa_puts("T8 deterministic OK\n" as *u8) } }
114
115 sa_puts("SWARMARBITRATEGATE " as *u8); sa_putn(pass); sa_puts("/" as *u8); sa_putn(total)
116 if pass == total { sa_puts(" verdict=GREEN\n" as *u8) } else { sa_puts(" verdict=RED\n" as *u8) }
117 if pass == total { return 0 }
118 return 1
119}