nx_attention_class.nx source

1// nx_attention_class.nx -- sealed enum: cell attention class. 2// 3// Per cardinal: cooperative-resource-arbitration. The attention class 4// is the cell's declared priority intent. Foreground game holds 5// concurrent VRAM and CPU against background inference; idle work 6// runs only when nothing else is asking. 7// 8// Distinct from nx_attention.nx (ML scaled-dot-product attention). 9// The semantic collision is at the name prefix only; this primitive 10// concerns OS-level resource arbitration, not transformer kernels. 11// 12// Composes: 13// nx_budget -- budget grant decisions honor class priority 14// nx_yield -- yield request from lower class is auto-granted 15// when higher class is contending 16// nx_evict_journal -- evictions log displacing class for forensics 17// nx_homeostasis -- migration tropism preferences vary by class 18// (foreground stays local; idle is offload-OK) 19// 20// V1 ships seven classes per cardinal. Priority order is FIXED here so 21// substrate-wide behavior remains reproducible across hardware tiers. 22// 23// Gap list (V1 honest perf verdict): 24// - no nested classes (cell has exactly one class at a time) 25// - no temporary boost (priority does not change on key-press; 26// callers must re-instantiate cell with new class) 27// - no fairness within same class (FIFO on contention, not weighted) 28// 29// genealogy_id: nishi_cardinal_2026-05-17_cooperative_resource_arbitration 30// lineage_id: substrate_attention_class_v1 31// 32// nx_safety_envelope: 33// intended_use: "Declared cell priority class for resource 34// arbitration; honored by budget + yield layers" 35// sil_target: SIL1 36// evidence: [enum_sealed, priority_total_order] 37// verdict: NOT_YET_EVALUATED 38 39import "nx_syscalls.nx" 40import "nx_tier.nx" 41const NX_MAGIC_16000: i64 = 16000 42const NX_MAGIC_8000: i64 = 8000 43const NX_MAGIC_4000: i64 = 4000 44const NX_MAGIC_2000: i64 = 2000 45 46// ===== Sealed enum: NxAttentionClass =============================== 47// 48// Order matters: each constant value IS its priority rank. Lower 49// numeric value = higher arbitration priority. Inserting new classes 50// requires re-balancing this table; do not add ad-hoc values. 51 52const NX_AC_INTERACTIVE_FOREGROUND_GAME: nx_int = 0 53const NX_AC_VIDEO_CALL: nx_int = 1 54const NX_AC_DEV: nx_int = 2 55const NX_AC_BACKGROUND_INFERENCE: nx_int = 3 56const NX_AC_BACKGROUND_BUILD: nx_int = 4 57const NX_AC_BACKGROUND_HEALTH: nx_int = 5 58const NX_AC_IDLE_OPPORTUNISTIC: nx_int = 6 59const NX_AC_N_CLASSES: nx_int = 7 60 61// ===== nx_ac_is_valid =========================================== 62 63func nx_ac_is_valid(c: nx_int) -> nx_int { 64 if c < 0 { return 0 } 65 if c >= NX_AC_N_CLASSES { return 0 } 66 return 1 67} 68 69// ===== nx_ac_is_foreground ====================================== 70// 71// Foreground classes block on user-perception deadlines and must 72// never yield to background. Used by nx_yield to short-circuit 73// background-cell requests during foreground activity. 74 75func nx_ac_is_foreground(c: nx_int) -> nx_int { 76 if c == NX_AC_INTERACTIVE_FOREGROUND_GAME { return 1 } 77 if c == NX_AC_VIDEO_CALL { return 1 } 78 return 0 79} 80 81// ===== nx_ac_is_background ====================================== 82 83func nx_ac_is_background(c: nx_int) -> nx_int { 84 if c == NX_AC_BACKGROUND_INFERENCE { return 1 } 85 if c == NX_AC_BACKGROUND_BUILD { return 1 } 86 if c == NX_AC_BACKGROUND_HEALTH { return 1 } 87 if c == NX_AC_IDLE_OPPORTUNISTIC { return 1 } 88 return 0 89} 90 91// ===== nx_ac_priority =========================================== 92// 93// Lower returned value = higher arbitration priority. Identical to 94// the enum constant value by construction, but exposed as a function 95// so callers do not bake the enum-as-rank assumption into their code. 96 97func nx_ac_priority(c: nx_int) -> nx_int { 98 if nx_ac_is_valid(c) == 0 { return NX_AC_N_CLASSES } 99 return c 100} 101 102// ===== nx_ac_higher_priority ==================================== 103// 104// Returns 1 if class a should arbitrate over class b on contention. 105// Tie-breaking goes to a (FIFO at the call site is the caller's job). 106 107func nx_ac_higher_priority(a: nx_int, b: nx_int) -> nx_int { 108 if nx_ac_priority(a) <= nx_ac_priority(b) { return 1 } 109 return 0 110} 111 112// ===== nx_ac_yield_quantum_us =================================== 113// 114// Returns the maximum quantum a cell of class c may hold a contested 115// resource before voluntarily yielding, in microseconds. Foreground 116// game gets the largest quantum to preserve frame budget; idle gets 117// the smallest so it backs off cheaply when anything else asks. 118 119func nx_ac_yield_quantum_us(c: nx_int) -> nx_size { 120 if c == NX_AC_INTERACTIVE_FOREGROUND_GAME { return NX_MAGIC_16000 } 121 if c == NX_AC_VIDEO_CALL { return NX_MAGIC_8000 } 122 if c == NX_AC_DEV { return NX_MAGIC_4000 } 123 if c == NX_AC_BACKGROUND_INFERENCE { return NX_MAGIC_2000 } 124 if c == NX_AC_BACKGROUND_BUILD { return NX_MAGIC_2000 } 125 if c == NX_AC_BACKGROUND_HEALTH { return 1000 } 126 if c == NX_AC_IDLE_OPPORTUNISTIC { return 500 } 127 return 0 128}