nx_modality_router.nx source
↩ module page · 448 lines · 17099 B
1// nx_modality_router.nx -- H10 multi-modal model sharing (bits-up).
2//
3// Per NISHI_ELDER_AI_OFF_DOCKER_2026_05_20.md ยง2.1 H10: one shared
4// backbone trunk serves multiple modality-specific heads
5// concurrently -- text response, image prompt conditioning,
6// audio embed, vision token embed. Stable Diffusion shares one
7// UNet across N LoRA + ControlNet adaptations; Llava + Flamingo
8// share one LLM trunk across text + vision modalities; the
9// operator's "multiused the llm for response and image gen"
10// cardinal IS this pattern.
11//
12// V1 mechanics: two registries -- backbones (one trunk weight
13// reference each) + modality heads (small per-modality projection
14// layers that attach to a backbone). Registering a head ACQUIRES
15// the named backbone (bumps refcount); unregistering RELEASES it.
16// A backbone with refcount > 0 cannot be evicted. resolve_backbone_
17// for_modality() walks the modality -> backbone link in one call.
18//
19// Composition path:
20// - register_backbone(id, weights_data, hidden_dim, n_layers)
21// ONCE per loaded base model
22// - register_modality(id, backbone_id, head_data, kind) per
23// modality the consumer wants to serve; this acquires the
24// backbone
25// - resolve_backbone_for_modality(modality_id) at request-time
26// gives the consumer the backbone pointer + the head pointer
27// in one call, so the forward-pass kernel can run trunk +
28// head in sequence without a second lookup
29// - unregister_modality on shutdown releases the backbone;
30// evict_backbone only succeeds when no modality references it
31//
32// Pure substrate logic. No Linux features. Composes with shipped
33// H9 nx_lora_pool (modality head's "head_data" pointer can itself
34// be an adapter_id resolved through the LoRA pool, letting one
35// backbone serve N modalities each with M fine-tuned adapter
36// variants).
37//
38// V1 honest scope:
39// - Sealed-enum modality kinds: TEXT, IMAGE, AUDIO, EMBED. A V2
40// could add VIDEO + PROPRIOCEPT etc.; the sealed-enum is
41// extension-safe because new kinds get a new const + a new
42// entry in nx_modality_kind_is_valid()
43// - Fixed pool sizes (NX_MODALITY_MAX_BACKBONES = 16,
44// NX_MODALITY_MAX_HEADS = 64) -- Elder AI's named killer
45// pattern is "one LLM, several modalities," not "thousands"
46// - Head + backbone weight data are OPAQUE *i64 pointers --
47// consumer that runs the forward pass owns shape
48// interpretation (matches H9 nx_lora_pool design)
49//
50// genealogy_id: stable_diffusion_unet_share_2022 +
51// llava_modality_share_2023 +
52// flamingo_perceiver_2022 +
53// cardinal_2026-05-20_elder_ai_off_docker +
54// cardinal_2026-05-20_bits_up_nishi_not_linux
55// lineage_id: substrate_modality_router_v1
56//
57// nx_capability_manifest:
58// variant_class: modality_router
59// variant_id: modality_router_v1_static_pool
60// requires_isa: [rv32i, rv64imac, x86_64, cortex_m, armv7a, aarch64, wasm32]
61// requires_syscalls: [mmap]
62// requires_ram_min_b: 8192
63// tier_floor: NX_TIER_INF_MOBILE
64// tier_ceiling: NX_TIER_INF_HPC
65// cost_model:
66// flops_per_n: 1.0 // O(n_modalities) lookup
67// bytes_per_n: 96.0 // head + backbone records
68// syscalls_per_n: 0.0
69// adversary_class: THREAT_AI_ADVERSARY
70//
71// nx_safety_envelope:
72// intended_use: "Multi-modal model-sharing router for shared
73// backbone + per-modality head dispatch; bits-up;
74// composes with nx_lora_pool"
75// sil_target: SIL2
76// evidence: [canary_bracketed, kind_sealed_enum,
77// refusal_on_in_use_evict, backbone_refcount_invariant]
78// verdict: NOT_YET_EVALUATED
79
80import "nx_syscalls.nx"
81
82// ===== Constants =================================================
83const NX_MODALITY_MAX_BACKBONES: i64 = 16
84const NX_MODALITY_MAX_HEADS: i64 = 64
85
86// Modality kinds (sealed).
87const NX_MODALITY_TEXT: i64 = 0
88const NX_MODALITY_IMAGE: i64 = 1
89const NX_MODALITY_AUDIO: i64 = 2
90const NX_MODALITY_EMBED: i64 = 3
91const NX_MODALITY_N_KINDS: i64 = 4
92
93func nx_modality_kind_is_valid(k: i64) -> i64 {
94 if k < 0 { return 0 }
95 if k >= NX_MODALITY_N_KINDS { return 0 }
96 return 1
97}
98
99// Verdicts.
100const NX_MOD_OK: i64 = 0
101const NX_MOD_BAD_INPUT: i64 = 1
102const NX_MOD_NOT_FOUND: i64 = 2
103const NX_MOD_DUPLICATE: i64 = 3
104const NX_MOD_FULL: i64 = 4
105const NX_MOD_IN_USE: i64 = 5
106const NX_MOD_BAD_KIND: i64 = 6
107const NX_MOD_BACKBONE_NOT_FOUND: i64 = 7
108const NX_MOD_TAMPER: i64 = 8
109const NX_MOD_N_VERDICTS: i64 = 9
110
111func nx_mod_verdict_is_valid(v: i64) -> i64 {
112 if v < 0 { return 0 }
113 if v >= NX_MOD_N_VERDICTS { return 0 }
114 return 1
115}
116
117// Canary magic.
118const NX_BACKBONE_CANARY_PRE: i64 = 0x4261636B626F6E65 // "Backbone"
119const NX_BACKBONE_CANARY_POST: i64 = 0x426F6E654531446F // "BoneE1Do"
120const NX_MOD_HEAD_CANARY_PRE: i64 = 0x4D6F6448656164A1 // "MoHHead!"
121const NX_MOD_HEAD_CANARY_POST: i64 = 0x4865616445314432 // "HeadE1D2"
122const NX_MOD_ROUTER_CANARY_PRE: i64 = 0x4D6F64526F75740A // "ModRout."
123const NX_MOD_ROUTER_CANARY_POST:i64 = 0x526F75744531443B // "RoutE1D;"
124
125// ===== Structs ====================================================
126struct NxBackbone {
127 canary_pre: i64,
128 backbone_id: i64,
129 weights_data: *i64,
130 weights_size: i64,
131 hidden_dim: i64,
132 n_layers: i64,
133 refcount: i64,
134 canary_post: i64,
135}
136
137struct NxModalityHead {
138 canary_pre: i64,
139 modality_id: i64,
140 backbone_id: i64,
141 head_data: *i64,
142 head_size: i64,
143 kind: i64,
144 canary_post: i64,
145}
146
147struct NxModalityRouter {
148 canary_pre: i64,
149 max_backbones: i64,
150 n_backbones: i64,
151 backbones: *i64, // *i64 array of *NxBackbone pointers (as i64)
152 max_heads: i64,
153 n_heads: i64,
154 heads: *i64, // *i64 array of *NxModalityHead pointers (as i64)
155 canary_post: i64,
156}
157
158// ===== Validity =================================================
159func nx_backbone_is_valid(b: *NxBackbone) -> i64 {
160 if (b as i64) == 0 { return 0 }
161 if b.canary_pre != NX_BACKBONE_CANARY_PRE { return 0 }
162 if b.canary_post != NX_BACKBONE_CANARY_POST { return 0 }
163 if b.hidden_dim <= 0 { return 0 }
164 if b.n_layers <= 0 { return 0 }
165 if b.weights_size <= 0 { return 0 }
166 if b.refcount < 0 { return 0 }
167 return 1
168}
169
170func nx_modality_head_is_valid(h: *NxModalityHead) -> i64 {
171 if (h as i64) == 0 { return 0 }
172 if h.canary_pre != NX_MOD_HEAD_CANARY_PRE { return 0 }
173 if h.canary_post != NX_MOD_HEAD_CANARY_POST { return 0 }
174 if nx_modality_kind_is_valid(h.kind) != 1 { return 0 }
175 if h.head_size <= 0 { return 0 }
176 return 1
177}
178
179func nx_modality_router_is_valid(r: *NxModalityRouter) -> i64 {
180 if (r as i64) == 0 { return 0 }
181 if r.canary_pre != NX_MOD_ROUTER_CANARY_PRE { return 0 }
182 if r.canary_post != NX_MOD_ROUTER_CANARY_POST { return 0 }
183 if r.max_backbones <= 0 { return 0 }
184 if r.max_backbones > NX_MODALITY_MAX_BACKBONES { return 0 }
185 if r.max_heads <= 0 { return 0 }
186 if r.max_heads > NX_MODALITY_MAX_HEADS { return 0 }
187 if r.n_backbones < 0 { return 0 }
188 if r.n_backbones > r.max_backbones { return 0 }
189 if r.n_heads < 0 { return 0 }
190 if r.n_heads > r.max_heads { return 0 }
191 return 1
192}
193
194// ===== Constructor =================================================
195func nx_modality_router_new(max_backbones: i64, max_heads: i64) -> *NxModalityRouter {
196 if max_backbones <= 0 { return (0 as i64) as *NxModalityRouter }
197 if max_backbones > NX_MODALITY_MAX_BACKBONES { return (0 as i64) as *NxModalityRouter }
198 if max_heads <= 0 { return (0 as i64) as *NxModalityRouter }
199 if max_heads > NX_MODALITY_MAX_HEADS { return (0 as i64) as *NxModalityRouter }
200
201 let r: *NxModalityRouter = (sys_mmap(64)) as *NxModalityRouter
202 r.canary_pre = NX_MOD_ROUTER_CANARY_PRE
203 r.max_backbones = max_backbones
204 r.n_backbones = 0
205 r.backbones = (sys_mmap(max_backbones * 8)) as *i64
206 r.max_heads = max_heads
207 r.n_heads = 0
208 r.heads = (sys_mmap(max_heads * 8)) as *i64
209 r.canary_post = NX_MOD_ROUTER_CANARY_POST
210
211 var i: i64 = 0
212 while i < max_backbones {
213 r.backbones[i] = 0
214 i = i + 1
215 }
216 var j: i64 = 0
217 while j < max_heads {
218 r.heads[j] = 0
219 j = j + 1
220 }
221 return r
222}
223
224// ===== Internal helpers =================================================
225func nx_mod__find_backbone(r: *NxModalityRouter, backbone_id: i64) -> i64 {
226 var i: i64 = 0
227 while i < r.n_backbones {
228 let p: i64 = r.backbones[i]
229 if p != 0 {
230 let b: *NxBackbone = p as *NxBackbone
231 if b.backbone_id == backbone_id { return i }
232 }
233 i = i + 1
234 }
235 return 0 - 1
236}
237
238func nx_mod__find_head(r: *NxModalityRouter, modality_id: i64) -> i64 {
239 var i: i64 = 0
240 while i < r.n_heads {
241 let p: i64 = r.heads[i]
242 if p != 0 {
243 let h: *NxModalityHead = p as *NxModalityHead
244 if h.modality_id == modality_id { return i }
245 }
246 i = i + 1
247 }
248 return 0 - 1
249}
250
251// ===== Register backbone =================================================
252func nx_modality_register_backbone(r: *NxModalityRouter, backbone_id: i64, weights_data: *i64, weights_size: i64, hidden_dim: i64, n_layers: i64) -> i64 {
253 if nx_modality_router_is_valid(r) != 1 { return 0 - NX_MOD_TAMPER }
254 if (weights_data as i64) == 0 { return 0 - NX_MOD_BAD_INPUT }
255 if weights_size <= 0 { return 0 - NX_MOD_BAD_INPUT }
256 if hidden_dim <= 0 { return 0 - NX_MOD_BAD_INPUT }
257 if n_layers <= 0 { return 0 - NX_MOD_BAD_INPUT }
258
259 if nx_mod__find_backbone(r, backbone_id) >= 0 { return 0 - NX_MOD_DUPLICATE }
260 if r.n_backbones >= r.max_backbones { return 0 - NX_MOD_FULL }
261
262 let b: *NxBackbone = (sys_mmap(64)) as *NxBackbone
263 b.canary_pre = NX_BACKBONE_CANARY_PRE
264 b.backbone_id = backbone_id
265 b.weights_data = weights_data
266 b.weights_size = weights_size
267 b.hidden_dim = hidden_dim
268 b.n_layers = n_layers
269 b.refcount = 0
270 b.canary_post = NX_BACKBONE_CANARY_POST
271
272 let slot: i64 = r.n_backbones
273 r.backbones[slot] = b as i64
274 r.n_backbones = r.n_backbones + 1
275 return slot
276}
277
278// ===== Register modality head =================================================
279// Acquires the named backbone (bumps refcount).
280func nx_modality_register_head(r: *NxModalityRouter, modality_id: i64, backbone_id: i64, head_data: *i64, head_size: i64, kind: i64) -> i64 {
281 if nx_modality_router_is_valid(r) != 1 { return 0 - NX_MOD_TAMPER }
282 if nx_modality_kind_is_valid(kind) != 1 { return 0 - NX_MOD_BAD_KIND }
283 if (head_data as i64) == 0 { return 0 - NX_MOD_BAD_INPUT }
284 if head_size <= 0 { return 0 - NX_MOD_BAD_INPUT }
285
286 let bbone_slot: i64 = nx_mod__find_backbone(r, backbone_id)
287 if bbone_slot < 0 { return 0 - NX_MOD_BACKBONE_NOT_FOUND }
288
289 if nx_mod__find_head(r, modality_id) >= 0 { return 0 - NX_MOD_DUPLICATE }
290 if r.n_heads >= r.max_heads { return 0 - NX_MOD_FULL }
291
292 let b: *NxBackbone = (r.backbones[bbone_slot]) as *NxBackbone
293 if nx_backbone_is_valid(b) != 1 { return 0 - NX_MOD_TAMPER }
294
295 let h: *NxModalityHead = (sys_mmap(56)) as *NxModalityHead
296 h.canary_pre = NX_MOD_HEAD_CANARY_PRE
297 h.modality_id = modality_id
298 h.backbone_id = backbone_id
299 h.head_data = head_data
300 h.head_size = head_size
301 h.kind = kind
302 h.canary_post = NX_MOD_HEAD_CANARY_POST
303
304 let slot: i64 = r.n_heads
305 r.heads[slot] = h as i64
306 r.n_heads = r.n_heads + 1
307
308 b.refcount = b.refcount + 1
309 return slot
310}
311
312// ===== Lookups =================================================
313func nx_modality_lookup_backbone(r: *NxModalityRouter, backbone_id: i64) -> *NxBackbone {
314 if nx_modality_router_is_valid(r) != 1 { return (0 as i64) as *NxBackbone }
315 let slot: i64 = nx_mod__find_backbone(r, backbone_id)
316 if slot < 0 { return (0 as i64) as *NxBackbone }
317 return (r.backbones[slot]) as *NxBackbone
318}
319
320func nx_modality_lookup_head(r: *NxModalityRouter, modality_id: i64) -> *NxModalityHead {
321 if nx_modality_router_is_valid(r) != 1 { return (0 as i64) as *NxModalityHead }
322 let slot: i64 = nx_mod__find_head(r, modality_id)
323 if slot < 0 { return (0 as i64) as *NxModalityHead }
324 return (r.heads[slot]) as *NxModalityHead
325}
326
327// One-call resolve: modality_id -> backbone pointer the consumer
328// needs for the forward pass. Returns null if the modality isn't
329// registered OR its backbone link is stale.
330func nx_modality_resolve_backbone(r: *NxModalityRouter, modality_id: i64) -> *NxBackbone {
331 if nx_modality_router_is_valid(r) != 1 { return (0 as i64) as *NxBackbone }
332 let h_slot: i64 = nx_mod__find_head(r, modality_id)
333 if h_slot < 0 { return (0 as i64) as *NxBackbone }
334 let h: *NxModalityHead = (r.heads[h_slot]) as *NxModalityHead
335 if nx_modality_head_is_valid(h) != 1 { return (0 as i64) as *NxBackbone }
336 let b_slot: i64 = nx_mod__find_backbone(r, h.backbone_id)
337 if b_slot < 0 { return (0 as i64) as *NxBackbone }
338 return (r.backbones[b_slot]) as *NxBackbone
339}
340
341// ===== Unregister modality (releases backbone) =================================================
342func nx_modality_unregister_head(r: *NxModalityRouter, modality_id: i64) -> i64 {
343 if nx_modality_router_is_valid(r) != 1 { return 0 - NX_MOD_TAMPER }
344 let slot: i64 = nx_mod__find_head(r, modality_id)
345 if slot < 0 { return 0 - NX_MOD_NOT_FOUND }
346
347 let h: *NxModalityHead = (r.heads[slot]) as *NxModalityHead
348 if nx_modality_head_is_valid(h) != 1 { return 0 - NX_MOD_TAMPER }
349
350 let bbone_slot: i64 = nx_mod__find_backbone(r, h.backbone_id)
351 if bbone_slot >= 0 {
352 let b: *NxBackbone = (r.backbones[bbone_slot]) as *NxBackbone
353 if nx_backbone_is_valid(b) == 1 {
354 if b.refcount > 0 { b.refcount = b.refcount - 1 }
355 }
356 }
357
358 // Tail-swap compaction.
359 let tail: i64 = r.n_heads - 1
360 if slot != tail {
361 r.heads[slot] = r.heads[tail]
362 }
363 r.heads[tail] = 0
364 r.n_heads = r.n_heads - 1
365 return NX_MOD_OK
366}
367
368// ===== Evict backbone (requires zero refcount) =================================================
369func nx_modality_evict_backbone(r: *NxModalityRouter, backbone_id: i64) -> i64 {
370 if nx_modality_router_is_valid(r) != 1 { return 0 - NX_MOD_TAMPER }
371 let slot: i64 = nx_mod__find_backbone(r, backbone_id)
372 if slot < 0 { return 0 - NX_MOD_NOT_FOUND }
373
374 let b: *NxBackbone = (r.backbones[slot]) as *NxBackbone
375 if nx_backbone_is_valid(b) != 1 { return 0 - NX_MOD_TAMPER }
376 if b.refcount > 0 { return 0 - NX_MOD_IN_USE }
377
378 let tail: i64 = r.n_backbones - 1
379 if slot != tail {
380 r.backbones[slot] = r.backbones[tail]
381 }
382 r.backbones[tail] = 0
383 r.n_backbones = r.n_backbones - 1
384 return NX_MOD_OK
385}
386
387// ===== Accessors =================================================
388func nx_modality_n_backbones(r: *NxModalityRouter) -> i64 {
389 if nx_modality_router_is_valid(r) != 1 { return 0 - 1 }
390 return r.n_backbones
391}
392
393func nx_modality_n_heads(r: *NxModalityRouter) -> i64 {
394 if nx_modality_router_is_valid(r) != 1 { return 0 - 1 }
395 return r.n_heads
396}
397
398func nx_modality_backbone_refcount(r: *NxModalityRouter, backbone_id: i64) -> i64 {
399 if nx_modality_router_is_valid(r) != 1 { return 0 - 1 }
400 let slot: i64 = nx_mod__find_backbone(r, backbone_id)
401 if slot < 0 { return 0 - 1 }
402 let b: *NxBackbone = (r.backbones[slot]) as *NxBackbone
403 if nx_backbone_is_valid(b) != 1 { return 0 - 1 }
404 return b.refcount
405}
406
407// Count modalities currently attached to a given backbone.
408// (This MUST equal backbone.refcount when no tamper has occurred --
409// useful invariant for downstream auditors.)
410func nx_modality_count_heads_for_backbone(r: *NxModalityRouter, backbone_id: i64) -> i64 {
411 if nx_modality_router_is_valid(r) != 1 { return 0 - 1 }
412 var count: i64 = 0
413 var i: i64 = 0
414 while i < r.n_heads {
415 let p: i64 = r.heads[i]
416 if p != 0 {
417 let h: *NxModalityHead = p as *NxModalityHead
418 if h.backbone_id == backbone_id { count = count + 1 }
419 }
420 i = i + 1
421 }
422 return count
423}
424
425func nx_modality_head_kind(h: *NxModalityHead) -> i64 {
426 if nx_modality_head_is_valid(h) != 1 { return 0 - 1 }
427 return h.kind
428}
429
430func nx_modality_head_backbone_id(h: *NxModalityHead) -> i64 {
431 if nx_modality_head_is_valid(h) != 1 { return 0 - 1 }
432 return h.backbone_id
433}
434
435func nx_modality_backbone_id(b: *NxBackbone) -> i64 {
436 if nx_backbone_is_valid(b) != 1 { return 0 - 1 }
437 return b.backbone_id
438}
439
440func nx_modality_backbone_hidden_dim(b: *NxBackbone) -> i64 {
441 if nx_backbone_is_valid(b) != 1 { return 0 - 1 }
442 return b.hidden_dim
443}
444
445func nx_modality_backbone_n_layers(b: *NxBackbone) -> i64 {
446 if nx_backbone_is_valid(b) != 1 { return 0 - 1 }
447 return b.n_layers
448}