Skip to main content

qualia_core_db/modalities/
p64_cartridge.rs

1//! `.p64` Neural Extension Cartridge binary packer, unpacker, and recurrent-state/KV seed bridge.
2//!
3//! A `.p64` neural extension cartridge attaches to any non-`.p64` mechanical CAD assembly or `.10d`
4//! flora/fauna asset and carries two tiers in a single deterministic binary container:
5//! - **Tier 0 (Vendor-Agnostic Universal Payload):** compact CBOR-LD `PredicateTriggerRule` table
6//!   and `NQuin` guardrails that any model (`Qwen`, `Gemma`, `Gemini`, etc.) can consume.
7//! - **Tier 1 (Vendor/Model-Keyed Neural Slots):** zero-copy aligned byte ranges containing
8//!   pre-warmed `Qwen3.5` `GatedDeltaNet` recurrent state seeds (`f32`), KV prefix snapshots,
9//!   `Gemma 4` PLE tables, or LoRA deltas.
10
11use 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/// Parsed header of a `.p64` neural extension cartridge.
31#[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
57/// Encode `PredicateTriggerRule`s into the compact 60-byte-per-rule CBOR-LD binary frame (zero-heap).
58pub 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
86/// Pack a `.p64` neural extension cartridge (Tier-0 CBOR-LD rules + `NQuin` guardrails + Tier-1
87/// vendor/model slot directory and f32 recurrent-state/KV payloads) into caller-supplied `out_bytes`.
88pub 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
162/// Unpack a `.p64` neural extension cartridge into caller-supplied Tier-0 and Tier-1 buffers (zero-heap).
163pub 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
251/// Extract the `f32` recurrent-state or KV seed payload for a matched `P64ExtensionSlot` into `out_floats` (zero-heap).
252pub 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/// Mount a `.p64` neural extension cartridge onto a `QTensorEngine` when a matching Tier-1
274/// recurrent-state seed slot exists for `(preferred_model_id, architecture_id)`.
275/// Even when no Tier-1 vendor slot matches (e.g., running on a cloud or different vendor LLM),
276/// the Tier-0 `PredicateTriggerRule`s and `NQuin` guardrails are unpacked and returned.
277#[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        // Simulate an allocated 8-float recurrent state on the engine
361        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}