Skip to main content

qualia_core_db/net/
sonic_token.rs

1//! 64-bit Sonic Token — symbolic audio events (U0/U1 → U3 AcousticPlane).
2//!
3//! Hot path: `Pod` packed `u64`; no heap. MIDI export is a cold-path serializer.
4
5use bytemuck::{Pod, Zeroable};
6
7pub const SONIC_MAGIC: u8 = 0x53; // 'S'
8
9/// Packed sonic event (8 bytes).
10#[repr(C)]
11#[derive(Debug, Clone, Copy, PartialEq, Eq, Pod, Zeroable)]
12pub struct SonicToken {
13    pub raw: u64,
14}
15
16#[repr(u8)]
17#[derive(Debug, Clone, Copy, PartialEq, Eq)]
18pub enum SonicEventType {
19    NoteOn = 0,
20    NoteOff = 1,
21    ControlChange = 2,
22    Parametric = 3,
23}
24
25impl SonicToken {
26    #[inline]
27    /// Empty token.
28    pub const fn empty() -> Self {
29        Self { raw: 0 }
30    }
31
32    #[inline]
33    /// Packs fields into a token.
34    pub fn pack(
35        delta_time: u8,
36        event_type: SonicEventType,
37        channel: u8,
38        note: u8,
39        velocity: u8,
40        tensor_index: u32,
41        flags: u16,
42    ) -> Self {
43        let et = event_type as u64;
44        let raw = (delta_time as u64)
45            | ((et & 0x0f) << 8)
46            | ((channel as u64 & 0x0f) << 12)
47            | ((note as u64) << 16)
48            | ((velocity as u64) << 24)
49            | ((tensor_index as u64 & 0xffff) << 32)
50            | ((flags as u64 & 0xffff) << 48);
51        Self { raw }
52    }
53
54    #[inline]
55    /// Delta time.
56    pub fn delta_time(self) -> u8 {
57        self.raw as u8
58    }
59
60    #[inline]
61    /// Event type.
62    pub fn event_type(self) -> SonicEventType {
63        match (self.raw >> 8) & 0x0f {
64            1 => SonicEventType::NoteOff,
65            2 => SonicEventType::ControlChange,
66            3 => SonicEventType::Parametric,
67            _ => SonicEventType::NoteOn,
68        }
69    }
70
71    #[inline]
72    /// MIDI channel.
73    pub fn channel(self) -> u8 {
74        ((self.raw >> 12) & 0x0f) as u8
75    }
76
77    #[inline]
78    /// Note number.
79    pub fn note(self) -> u8 {
80        ((self.raw >> 16) & 0xff) as u8
81    }
82
83    #[inline]
84    /// Velocity.
85    pub fn velocity(self) -> u8 {
86        ((self.raw >> 24) & 0xff) as u8
87    }
88
89    #[inline]
90    /// Tensor index.
91    pub fn tensor_index(self) -> u32 {
92        ((self.raw >> 32) & 0xffff) as u32
93    }
94
95    #[inline]
96    /// Flags.
97    pub fn flags(self) -> u16 {
98        (self.raw >> 48) as u16
99    }
100
101    /// Map manifold `w` + epistemic `q` to a MIDI note (0–127).
102    #[inline]
103    pub fn pitch_from_tensor(w: f32, q: f32, sigma: f32) -> u8 {
104        let base = 48.0 + w * 12.0 + sigma.fract() * 24.0;
105        let jitter = q * 6.0;
106        (base + jitter).clamp(0.0, 127.0) as u8
107    }
108
109    /// Build NoteOn from a tensor node index and pitch/velocity.
110    #[inline]
111    pub fn note_on(tensor_index: u32, note: u8, velocity: u8, channel: u8) -> Self {
112        Self::pack(
113            0,
114            SonicEventType::NoteOn,
115            channel,
116            note,
117            velocity,
118            tensor_index,
119            SONIC_MAGIC as u16,
120        )
121    }
122
123    #[inline]
124    /// Builds a parametric-pulse token.
125    pub fn parametric_pulse(tensor_index: u32, velocity: u8) -> Self {
126        Self::pack(
127            0,
128            SonicEventType::Parametric,
129            0,
130            0,
131            velocity,
132            tensor_index,
133            SONIC_MAGIC as u16,
134        )
135    }
136}
137
138#[cfg(test)]
139mod tests {
140    use super::*;
141
142    #[test]
143    fn pack_roundtrip() {
144        let t = SonicToken::pack(3, SonicEventType::NoteOn, 2, 60, 100, 42, 0x0053);
145        assert_eq!(t.delta_time(), 3);
146        assert_eq!(t.event_type(), SonicEventType::NoteOn);
147        assert_eq!(t.channel(), 2);
148        assert_eq!(t.note(), 60);
149        assert_eq!(t.velocity(), 100);
150        assert_eq!(t.tensor_index(), 42);
151        assert_eq!(t.flags(), 0x0053);
152        assert_eq!(std::mem::size_of::<SonicToken>(), 8);
153    }
154
155    #[test]
156    fn pitch_from_tensor_in_range() {
157        let n = SonicToken::pitch_from_tensor(2.0, 0.5, 3.7);
158        assert!(n <= 127);
159    }
160}