qualia_core_db/modalities/
p64_cartridge.rs1use crate::modalities::holographic_scene::{
12 decode_trigger_rules_cbor_ld_into, P64ExtensionSlot, PredicateTriggerRule, SceneGraphError,
13 CBOR_LD_SCENE_MAGIC,
14};
15#[cfg(any(not(target_arch = "wasm32"), feature = "gpu-runtime"))]
16use crate::modalities::holographic_scene::select_p64_vendor_slot;
17use crate::NQuin;
18
19pub const P64_EXT_CARTRIDGE_MAGIC: [u8; 8] = *b"P64EXT01";
20const HEADER_BYTES: usize = 32;
21const SLOT_RECORD_BYTES: usize = 32;
22const RULE_BYTES: usize = 60;
23const QUIN_BYTES: usize = 48;
24
25const FLAG_RECURRENT_SEED: u8 = 1 << 0;
26const FLAG_KV_PREFIX: u8 = 1 << 1;
27const FLAG_PLE_TABLE: u8 = 1 << 2;
28const FLAG_LORA_WEIGHTS: u8 = 1 << 3;
29
30#[repr(C)]
32#[derive(Clone, Copy, Debug, PartialEq, Eq)]
33pub struct P64ExtensionHeader {
34 pub asset_did_hash: u64,
35 pub tier0_rule_count: u16,
36 pub tier0_quin_count: u16,
37 pub tier1_slot_count: u16,
38 pub flags: u16,
39 pub tier0_offset: u32,
40 pub tier1_dir_offset: u32,
41}
42
43#[inline]
44fn temporal_op_code(op: crate::modalities::spatio_temporal::TemporalOp) -> u8 {
45 use crate::modalities::spatio_temporal::TemporalOp;
46 match op {
47 TemporalOp::Before => 1,
48 TemporalOp::Meets => 2,
49 TemporalOp::Overlaps => 3,
50 TemporalOp::Starts => 4,
51 TemporalOp::During => 5,
52 TemporalOp::Finishes => 6,
53 TemporalOp::Equals => 7,
54 }
55}
56
57pub fn encode_trigger_rules_cbor_ld_into(
59 rules: &[PredicateTriggerRule],
60 out_bytes: &mut [u8],
61) -> Result<usize, SceneGraphError> {
62 let needed = 8 + rules.len() * RULE_BYTES;
63 if out_bytes.len() < needed {
64 return Err(SceneGraphError::OutputBufferTooSmall);
65 }
66 out_bytes[0..4].copy_from_slice(&CBOR_LD_SCENE_MAGIC);
67 out_bytes[4..8].copy_from_slice(&(rules.len() as u32).to_le_bytes());
68 let mut off = 8usize;
69 for r in rules {
70 out_bytes[off..off + 8].copy_from_slice(&r.trigger_event_hash.to_le_bytes());
71 out_bytes[off + 8..off + 16].copy_from_slice(&r.target_class_hash.to_le_bytes());
72 out_bytes[off + 16..off + 24].copy_from_slice(&r.target_topic_hash.to_le_bytes());
73 out_bytes[off + 24..off + 32].copy_from_slice(&r.target_subpart_hash.to_le_bytes());
74 out_bytes[off + 32..off + 40].copy_from_slice(&r.preset_hash.to_le_bytes());
75 out_bytes[off + 40..off + 48].copy_from_slice(&r.follow_up_preset_hash.to_le_bytes());
76 out_bytes[off + 48..off + 52].copy_from_slice(&r.max_radius_m.to_le_bytes());
77 out_bytes[off + 52..off + 56].copy_from_slice(&r.propagation_speed_mps.to_le_bytes());
78 out_bytes[off + 56..off + 58].copy_from_slice(&r.duration_ms.to_le_bytes());
79 out_bytes[off + 58] = r.blend_in_ms;
80 out_bytes[off + 59] = temporal_op_code(r.temporal_op);
81 off += RULE_BYTES;
82 }
83 Ok(off)
84}
85
86pub fn pack_p64_extension_cartridge_into(
89 asset_did_hash: u64,
90 tier0_rules: &[PredicateTriggerRule],
91 tier0_quins: &[NQuin],
92 tier1_slots: &[(P64ExtensionSlot, &[f32])],
93 out_bytes: &mut [u8],
94) -> Result<usize, SceneGraphError> {
95 let tier0_rules_bytes = 8 + tier0_rules.len() * RULE_BYTES;
96 let tier0_quins_bytes = tier0_quins.len() * QUIN_BYTES;
97 let tier1_dir_offset = (HEADER_BYTES + tier0_rules_bytes + tier0_quins_bytes + 7) & !7;
98 let payload_start = tier1_dir_offset + tier1_slots.len() * SLOT_RECORD_BYTES;
99 let total_payload_bytes: usize = tier1_slots.iter().map(|(_, s)| s.len() * 4).sum();
100 let total_needed = payload_start + total_payload_bytes;
101 if out_bytes.len() < total_needed {
102 return Err(SceneGraphError::OutputBufferTooSmall);
103 }
104 out_bytes[..total_needed].fill(0);
105 out_bytes[0..8].copy_from_slice(&P64_EXT_CARTRIDGE_MAGIC);
106 out_bytes[8..16].copy_from_slice(&asset_did_hash.to_le_bytes());
107 out_bytes[16..18].copy_from_slice(&(tier0_rules.len() as u16).to_le_bytes());
108 out_bytes[18..20].copy_from_slice(&(tier0_quins.len() as u16).to_le_bytes());
109 out_bytes[20..22].copy_from_slice(&(tier1_slots.len() as u16).to_le_bytes());
110 out_bytes[22..24].copy_from_slice(&0u16.to_le_bytes());
111 out_bytes[24..28].copy_from_slice(&(HEADER_BYTES as u32).to_le_bytes());
112 out_bytes[28..32].copy_from_slice(&(tier1_dir_offset as u32).to_le_bytes());
113
114 let written_rules = encode_trigger_rules_cbor_ld_into(
115 tier0_rules,
116 &mut out_bytes[HEADER_BYTES..HEADER_BYTES + tier0_rules_bytes],
117 )?;
118 let mut q_off = HEADER_BYTES + written_rules;
119 for q in tier0_quins {
120 out_bytes[q_off..q_off + 8].copy_from_slice(&q.subject.to_le_bytes());
121 out_bytes[q_off + 8..q_off + 16].copy_from_slice(&q.predicate.to_le_bytes());
122 out_bytes[q_off + 16..q_off + 24].copy_from_slice(&q.object.to_le_bytes());
123 out_bytes[q_off + 24..q_off + 32].copy_from_slice(&q.context.to_le_bytes());
124 out_bytes[q_off + 32..q_off + 40].copy_from_slice(&q.metadata.to_le_bytes());
125 out_bytes[q_off + 40..q_off + 48].copy_from_slice(&q.parity.to_le_bytes());
126 q_off += QUIN_BYTES;
127 }
128
129 let mut cur_payload_off = payload_start;
130 for (idx, (slot, floats)) in tier1_slots.iter().enumerate() {
131 let dir_off = tier1_dir_offset + idx * SLOT_RECORD_BYTES;
132 let byte_len = floats.len() * 4;
133 let mut flags = 0u8;
134 if slot.has_recurrent_state_seed {
135 flags |= FLAG_RECURRENT_SEED;
136 }
137 if slot.has_kv_prefix {
138 flags |= FLAG_KV_PREFIX;
139 }
140 if slot.has_ple_table {
141 flags |= FLAG_PLE_TABLE;
142 }
143 if slot.has_lora_weights {
144 flags |= FLAG_LORA_WEIGHTS;
145 }
146 out_bytes[dir_off..dir_off + 8].copy_from_slice(&slot.vendor_model_hash.to_le_bytes());
147 out_bytes[dir_off + 8..dir_off + 12].copy_from_slice(&slot.architecture_id.to_le_bytes());
148 out_bytes[dir_off + 12] = flags;
149 out_bytes[dir_off + 16..dir_off + 24]
150 .copy_from_slice(&(cur_payload_off as u64).to_le_bytes());
151 out_bytes[dir_off + 24..dir_off + 32].copy_from_slice(&(byte_len as u64).to_le_bytes());
152
153 for (i, &val) in floats.iter().enumerate() {
154 let fo = cur_payload_off + i * 4;
155 out_bytes[fo..fo + 4].copy_from_slice(&val.to_le_bytes());
156 }
157 cur_payload_off += byte_len;
158 }
159 Ok(cur_payload_off)
160}
161
162pub fn unpack_p64_extension_cartridge_into(
164 cartridge_bytes: &[u8],
165 out_rules: &mut [PredicateTriggerRule],
166 out_quins: &mut [NQuin],
167 out_slots: &mut [P64ExtensionSlot],
168) -> Result<P64ExtensionHeader, SceneGraphError> {
169 if cartridge_bytes.len() < HEADER_BYTES || cartridge_bytes[0..8] != P64_EXT_CARTRIDGE_MAGIC {
170 return Err(SceneGraphError::InvalidCborLdHeader);
171 }
172 let asset_did_hash = u64::from_le_bytes(cartridge_bytes[8..16].try_into().unwrap());
173 let tier0_rule_count = u16::from_le_bytes(cartridge_bytes[16..18].try_into().unwrap());
174 let tier0_quin_count = u16::from_le_bytes(cartridge_bytes[18..20].try_into().unwrap());
175 let tier1_slot_count = u16::from_le_bytes(cartridge_bytes[20..22].try_into().unwrap());
176 let flags = u16::from_le_bytes(cartridge_bytes[22..24].try_into().unwrap());
177 let tier0_offset = u32::from_le_bytes(cartridge_bytes[24..28].try_into().unwrap());
178 let tier1_dir_offset = u32::from_le_bytes(cartridge_bytes[28..32].try_into().unwrap());
179
180 if (tier0_rule_count as usize) > out_rules.len()
181 || (tier0_quin_count as usize) > out_quins.len()
182 || (tier1_slot_count as usize) > out_slots.len()
183 {
184 return Err(SceneGraphError::OutputBufferTooSmall);
185 }
186
187 let t0_off = tier0_offset as usize;
188 let rules_len_bytes = 8 + (tier0_rule_count as usize) * RULE_BYTES;
189 let quins_len_bytes = (tier0_quin_count as usize) * QUIN_BYTES;
190 if t0_off + rules_len_bytes + quins_len_bytes > cartridge_bytes.len() {
191 return Err(SceneGraphError::TruncatedCborLdPayload);
192 }
193 decode_trigger_rules_cbor_ld_into(
194 &cartridge_bytes[t0_off..t0_off + rules_len_bytes],
195 &mut out_rules[..tier0_rule_count as usize],
196 )?;
197
198 let q_start = t0_off + rules_len_bytes;
199 for i in 0..tier0_quin_count as usize {
200 let bo = q_start + i * QUIN_BYTES;
201 let u64_at = |o: usize| {
202 u64::from_le_bytes(cartridge_bytes[bo + o..bo + o + 8].try_into().unwrap())
203 };
204 out_quins[i] = NQuin {
205 subject: u64_at(0),
206 predicate: u64_at(8),
207 object: u64_at(16),
208 context: u64_at(24),
209 metadata: u64_at(32),
210 parity: u64_at(40),
211 };
212 }
213
214 let t1_off = tier1_dir_offset as usize;
215 if t1_off + (tier1_slot_count as usize) * SLOT_RECORD_BYTES > cartridge_bytes.len() {
216 return Err(SceneGraphError::TruncatedCborLdPayload);
217 }
218 for i in 0..tier1_slot_count as usize {
219 let so = t1_off + i * SLOT_RECORD_BYTES;
220 let vendor_model_hash =
221 u64::from_le_bytes(cartridge_bytes[so..so + 8].try_into().unwrap());
222 let architecture_id =
223 u32::from_le_bytes(cartridge_bytes[so + 8..so + 12].try_into().unwrap());
224 let sflags = cartridge_bytes[so + 12];
225 let byte_offset =
226 u64::from_le_bytes(cartridge_bytes[so + 16..so + 24].try_into().unwrap());
227 let byte_len = u64::from_le_bytes(cartridge_bytes[so + 24..so + 32].try_into().unwrap());
228 out_slots[i] = P64ExtensionSlot {
229 vendor_model_hash,
230 architecture_id,
231 has_recurrent_state_seed: (sflags & FLAG_RECURRENT_SEED) != 0,
232 has_kv_prefix: (sflags & FLAG_KV_PREFIX) != 0,
233 has_ple_table: (sflags & FLAG_PLE_TABLE) != 0,
234 has_lora_weights: (sflags & FLAG_LORA_WEIGHTS) != 0,
235 byte_offset,
236 byte_len,
237 };
238 }
239
240 Ok(P64ExtensionHeader {
241 asset_did_hash,
242 tier0_rule_count,
243 tier0_quin_count,
244 tier1_slot_count,
245 flags,
246 tier0_offset,
247 tier1_dir_offset,
248 })
249}
250
251pub fn load_p64_slot_f32_seed_into(
253 cartridge_bytes: &[u8],
254 slot: &P64ExtensionSlot,
255 out_floats: &mut [f32],
256) -> Result<usize, SceneGraphError> {
257 let off = slot.byte_offset as usize;
258 let len = slot.byte_len as usize;
259 if off + len > cartridge_bytes.len() || len % 4 != 0 {
260 return Err(SceneGraphError::TruncatedCborLdPayload);
261 }
262 let count = len / 4;
263 if out_floats.len() < count {
264 return Err(SceneGraphError::OutputBufferTooSmall);
265 }
266 for i in 0..count {
267 let bo = off + i * 4;
268 out_floats[i] = f32::from_le_bytes(cartridge_bytes[bo..bo + 4].try_into().unwrap());
269 }
270 Ok(count)
271}
272
273#[cfg(any(not(target_arch = "wasm32"), feature = "gpu-runtime"))]
278pub fn mount_p64_cartridge_onto_engine(
279 cartridge_bytes: &[u8],
280 preferred_model_id: &str,
281 architecture_id: u32,
282 engine: &mut crate::gguf_bridge::QTensorEngine,
283 out_rules: &mut [PredicateTriggerRule],
284 out_quins: &mut [NQuin],
285 out_slots: &mut [P64ExtensionSlot],
286 scratch_seed: &mut [f32],
287) -> Result<(P64ExtensionHeader, bool), SceneGraphError> {
288 let header = unpack_p64_extension_cartridge_into(
289 cartridge_bytes,
290 out_rules,
291 out_quins,
292 out_slots,
293 )?;
294 let valid_slots = &out_slots[..header.tier1_slot_count as usize];
295 if let Some(matched) = select_p64_vendor_slot(valid_slots, preferred_model_id, architecture_id)
296 {
297 if matched.has_recurrent_state_seed {
298 let n = load_p64_slot_f32_seed_into(cartridge_bytes, matched, scratch_seed)?;
299 let restored = engine.restore_recurrent_state_from_slice(&scratch_seed[..n]);
300 return Ok((header, restored));
301 }
302 }
303 Ok((header, false))
304}
305
306#[cfg(all(test, any(not(target_arch = "wasm32"), feature = "gpu-runtime")))]
307mod tests {
308 use super::*;
309 use crate::modalities::holographic_scene::pack_preset_defeater_quin;
310 use crate::modalities::spatio_temporal::TemporalOp;
311 use crate::q_hash;
312
313 #[test]
314 fn pack_unpack_and_mount_p64_extension_cartridge_zero_heap() {
315 let asset_did = q_hash("did:q42:mechanical_windmill_01");
316 let rule = PredicateTriggerRule {
317 trigger_event_hash: q_hash("event:gust_front_arrival"),
318 target_class_hash: q_hash("CAD:WindTurbineAssembly"),
319 target_topic_hash: q_hash("topic:aerodynamic_load"),
320 target_subpart_hash: q_hash("subpart:rotor_hub_pitch"),
321 preset_hash: q_hash("preset:feather_blades_30deg"),
322 follow_up_preset_hash: q_hash("preset:engage_yaw_brake"),
323 temporal_op: TemporalOp::Meets,
324 max_radius_m: 120.0,
325 propagation_speed_mps: 25.0,
326 duration_ms: 6000,
327 blend_in_ms: 200,
328 amplitude_u8: 220,
329 };
330 let guardrail = pack_preset_defeater_quin(
331 asset_did,
332 q_hash("preset:overspeed_spin"),
333 q_hash("scene:outback_station"),
334 1,
335 );
336 let qwen_seed = [0.25f32, -0.5, 0.75, 1.25, -0.125, 0.5, 0.875, -0.25];
337 let qwen_slot = P64ExtensionSlot {
338 vendor_model_hash: q_hash("qwen3.5:0.8b"),
339 architecture_id: 10,
340 has_recurrent_state_seed: true,
341 has_kv_prefix: false,
342 has_ple_table: false,
343 has_lora_weights: false,
344 byte_offset: 0,
345 byte_len: 0,
346 };
347
348 let mut buf = [0u8; 512];
349 let total_bytes = pack_p64_extension_cartridge_into(
350 asset_did,
351 &[rule],
352 &[guardrail],
353 &[(qwen_slot, &qwen_seed)],
354 &mut buf,
355 )
356 .unwrap();
357 assert!(total_bytes <= buf.len());
358
359 let mut engine = crate::gguf_bridge::QTensorEngine::new();
360 let mut out_rules = [rule; 2];
362 let mut out_quins = [NQuin::default(); 2];
363 let mut out_slots = [qwen_slot; 2];
364 let mut scratch = [0.0f32; 16];
365
366 let (hdr, tier1_mounted) = mount_p64_cartridge_onto_engine(
367 &buf[..total_bytes],
368 "gemini:2.5-flash",
369 99,
370 &mut engine,
371 &mut out_rules,
372 &mut out_quins,
373 &mut out_slots,
374 &mut scratch,
375 )
376 .unwrap();
377 assert_eq!(hdr.tier0_rule_count, 1);
378 assert_eq!(hdr.tier0_quin_count, 1);
379 assert!(!tier1_mounted, "Unmatched vendor should fall back cleanly to Tier-0");
380 assert_eq!(out_rules[0].preset_hash, rule.preset_hash);
381 assert_eq!(out_quins[0].parity, guardrail.parity);
382 }
383}