Skip to main content

vibe/bytecode/
codec.rs

1//! Binary codec for `vibe-bc-0.1` chunks.
2//!
3//! Serializes a `Chunk` to/from a compact binary format suitable for
4//! storage, transmission, or caching. The format is:
5//!
6//! ```text
7//! ┌──────────────────────────────────────────────────────────────┐
8//! │ Header                                                       │
9//! │  magic         4 bytes   "VBC1"                              │
10//! │  version       2 bytes   u16 LE                               │
11//! │  top_locals    2 bytes   u16 LE                               │
12//! │  const_count   2 bytes   u16 LE                               │
13//! │  func_count    2 bytes   u16 LE                               │
14//! │  code_len      2 bytes   u16 LE                               │
15//! ├──────────────────────────────────────────────────────────────┤
16//! │ Constants                                                    │
17//! │  For each constant:                                          │
18//! │    tag       1 byte    0=String, 1=Iri                        │
19//! │    len       2 bytes   u16 LE (byte length, UTF-8)            │
20//! │    data      len bytes  UTF-8 string                          │
21//! ├──────────────────────────────────────────────────────────────┤
22//! │ Functions                                                    │
23//! │  For each function:                                          │
24//! │    name_len   1 byte                                         │
25//! │    name       name_len bytes                                 │
26//! │    param_ct   1 byte                                         │
27//! │    local_ct   2 bytes   u16 LE                                │
28//! │    code_off   2 bytes   u16 LE                                │
29//! │    budget     8 bytes   u64 LE                                │
30//! ├──────────────────────────────────────────────────────────────┤
31//! │ Code                                                         │
32//! │  raw bytes   code_len bytes                                  │
33//! └──────────────────────────────────────────────────────────────┘
34//! ```
35
36use crate::bytecode::op::{
37    Chunk, Const, FuncMeta, MAGIC, MAX_CODE, MAX_CONSTANTS, MAX_FUNCTIONS, VERSION,
38};
39
40/// Codec error.
41#[derive(Debug, Clone, PartialEq)]
42pub enum ChunkDecodeError {
43    /// Data too short for even the header.
44    TooShort,
45    /// Magic bytes don't match.
46    BadMagic([u8; 4]),
47    /// Version mismatch.
48    BadVersion(u16),
49    /// Truncated data (declared length exceeds remaining bytes).
50    Truncated,
51    /// Invalid constant tag.
52    InvalidConstTag(u8),
53    /// Too many constants.
54    TooManyConstants,
55    /// Too many functions.
56    TooManyFunctions,
57    /// Code segment too large.
58    CodeTooLarge,
59    /// Invalid string length.
60    InvalidStringLength(u16),
61    /// Invalid function name length.
62    InvalidNameLength(u8),
63}
64
65impl std::fmt::Display for ChunkDecodeError {
66    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
67        match self {
68            Self::TooShort => write!(f, "chunk: data too short for header"),
69            Self::BadMagic(m) => write!(
70                f,
71                "chunk: bad magic {:02X}{:02X}{:02X}{:02X}",
72                m[0], m[1], m[2], m[3]
73            ),
74            Self::BadVersion(v) => write!(f, "chunk: unsupported version {v}"),
75            Self::Truncated => write!(f, "chunk: truncated data"),
76            Self::InvalidConstTag(t) => write!(f, "chunk: invalid constant tag {t}"),
77            Self::TooManyConstants => write!(f, "chunk: too many constants"),
78            Self::TooManyFunctions => write!(f, "chunk: too many functions"),
79            Self::CodeTooLarge => write!(f, "chunk: code segment too large"),
80            Self::InvalidStringLength(n) => write!(f, "chunk: invalid string length {n}"),
81            Self::InvalidNameLength(n) => write!(f, "chunk: invalid function name length {n}"),
82        }
83    }
84}
85
86impl std::error::Error for ChunkDecodeError {}
87
88/// Encode a `Chunk` into binary bytes.
89pub fn encode_chunk(chunk: &Chunk) -> Vec<u8> {
90    let mut buf = Vec::with_capacity(64 + chunk.code.len());
91
92    // Header
93    buf.extend_from_slice(&MAGIC);
94    buf.extend_from_slice(&VERSION.to_le_bytes());
95    buf.extend_from_slice(&chunk.top_locals.to_le_bytes());
96    buf.extend_from_slice(&(chunk.constants.len() as u16).to_le_bytes());
97    buf.extend_from_slice(&(chunk.functions.len() as u16).to_le_bytes());
98    buf.extend_from_slice(&(chunk.code.len() as u16).to_le_bytes());
99
100    // Constants
101    for c in &chunk.constants {
102        match c {
103            Const::String(s) => {
104                buf.push(0);
105                let bytes = s.as_bytes();
106                buf.extend_from_slice(&(bytes.len() as u16).to_le_bytes());
107                buf.extend_from_slice(bytes);
108            }
109            Const::Iri(s) => {
110                buf.push(1);
111                let bytes = s.as_bytes();
112                buf.extend_from_slice(&(bytes.len() as u16).to_le_bytes());
113                buf.extend_from_slice(bytes);
114            }
115        }
116    }
117
118    // Functions
119    for f in &chunk.functions {
120        let name_bytes = f.name.as_bytes();
121        buf.push(name_bytes.len() as u8);
122        buf.extend_from_slice(name_bytes);
123        buf.push(f.param_count);
124        buf.extend_from_slice(&f.local_count.to_le_bytes());
125        buf.extend_from_slice(&f.code_offset.to_le_bytes());
126        buf.extend_from_slice(&f.budget_steps.to_le_bytes());
127    }
128
129    // Code
130    buf.extend_from_slice(&chunk.code);
131
132    buf
133}
134
135/// Decode a `Chunk` from binary bytes.
136pub fn decode_chunk(data: &[u8]) -> Result<Chunk, ChunkDecodeError> {
137    let mut pos = 0;
138
139    // Header
140    if data.len() < 14 {
141        return Err(ChunkDecodeError::TooShort);
142    }
143
144    let mut magic = [0u8; 4];
145    magic.copy_from_slice(&data[pos..pos + 4]);
146    pos += 4;
147    if magic != MAGIC {
148        return Err(ChunkDecodeError::BadMagic(magic));
149    }
150
151    let version = u16::from_le_bytes([data[pos], data[pos + 1]]);
152    pos += 2;
153    if version != VERSION {
154        return Err(ChunkDecodeError::BadVersion(version));
155    }
156
157    let top_locals = u16::from_le_bytes([data[pos], data[pos + 1]]);
158    pos += 2;
159
160    let const_count = u16::from_le_bytes([data[pos], data[pos + 1]]) as usize;
161    pos += 2;
162    if const_count > MAX_CONSTANTS {
163        return Err(ChunkDecodeError::TooManyConstants);
164    }
165
166    let func_count = u16::from_le_bytes([data[pos], data[pos + 1]]) as usize;
167    pos += 2;
168    if func_count > MAX_FUNCTIONS {
169        return Err(ChunkDecodeError::TooManyFunctions);
170    }
171
172    let code_len = u16::from_le_bytes([data[pos], data[pos + 1]]) as usize;
173    pos += 2;
174    if code_len > MAX_CODE {
175        return Err(ChunkDecodeError::CodeTooLarge);
176    }
177
178    // Constants
179    let mut constants = Vec::with_capacity(const_count);
180    for _ in 0..const_count {
181        if pos >= data.len() {
182            return Err(ChunkDecodeError::Truncated);
183        }
184        let tag = data[pos];
185        pos += 1;
186        if pos + 2 > data.len() {
187            return Err(ChunkDecodeError::Truncated);
188        }
189        let len = u16::from_le_bytes([data[pos], data[pos + 1]]) as usize;
190        pos += 2;
191        if pos + len > data.len() {
192            return Err(ChunkDecodeError::Truncated);
193        }
194        let s = std::str::from_utf8(&data[pos..pos + len])
195            .map_err(|_| ChunkDecodeError::InvalidStringLength(len as u16))?
196            .to_string();
197        pos += len;
198        constants.push(match tag {
199            0 => Const::String(s),
200            1 => Const::Iri(s),
201            _ => return Err(ChunkDecodeError::InvalidConstTag(tag)),
202        });
203    }
204
205    // Functions
206    let mut functions = Vec::with_capacity(func_count);
207    for _ in 0..func_count {
208        if pos >= data.len() {
209            return Err(ChunkDecodeError::Truncated);
210        }
211        let name_len = data[pos] as usize;
212        pos += 1;
213        if name_len == 0 {
214            return Err(ChunkDecodeError::InvalidNameLength(0));
215        }
216        if pos + name_len > data.len() {
217            return Err(ChunkDecodeError::Truncated);
218        }
219        let name = std::str::from_utf8(&data[pos..pos + name_len])
220            .map_err(|_| ChunkDecodeError::InvalidNameLength(name_len as u8))?
221            .to_string();
222        pos += name_len;
223
224        if pos + 13 > data.len() {
225            return Err(ChunkDecodeError::Truncated);
226        }
227        let param_count = data[pos];
228        pos += 1;
229        let local_count = u16::from_le_bytes([data[pos], data[pos + 1]]);
230        pos += 2;
231        let code_offset = u16::from_le_bytes([data[pos], data[pos + 1]]);
232        pos += 2;
233        let budget_steps = u64::from_le_bytes([
234            data[pos],
235            data[pos + 1],
236            data[pos + 2],
237            data[pos + 3],
238            data[pos + 4],
239            data[pos + 5],
240            data[pos + 6],
241            data[pos + 7],
242        ]);
243        pos += 8;
244
245        functions.push(FuncMeta {
246            name,
247            param_count,
248            local_count,
249            code_offset,
250            budget_steps,
251        });
252    }
253
254    // Code
255    if pos + code_len > data.len() {
256        return Err(ChunkDecodeError::Truncated);
257    }
258    let code = data[pos..pos + code_len].to_vec();
259
260    Ok(Chunk {
261        constants,
262        code,
263        functions,
264        top_locals,
265    })
266}
267
268#[cfg(test)]
269mod tests {
270    use super::*;
271    use crate::bind::LocalHost;
272    use crate::budget::Budget;
273    use crate::bytecode::compiler::compile_expr;
274    use crate::bytecode::vm::Vm;
275    use crate::parse::parse_cell;
276
277    #[test]
278    fn encode_decode_roundtrip_simple() {
279        let expr = parse_cell("= 1 + 2 * 3").expect("parse");
280        let chunk = compile_expr(&expr).expect("compile");
281        let bytes = encode_chunk(&chunk);
282        let decoded = decode_chunk(&bytes).expect("decode");
283        assert_eq!(chunk, decoded);
284    }
285
286    #[test]
287    fn encode_decode_roundtrip_strings() {
288        let expr = parse_cell(r#"= "hello world""#).expect("parse");
289        let chunk = compile_expr(&expr).expect("compile");
290        let bytes = encode_chunk(&chunk);
291        let decoded = decode_chunk(&bytes).expect("decode");
292        assert_eq!(chunk, decoded);
293    }
294
295    #[test]
296    fn encode_decode_roundtrip_list() {
297        let expr = parse_cell("= [1, 2, 3, 4, 5]").expect("parse");
298        let chunk = compile_expr(&expr).expect("compile");
299        let bytes = encode_chunk(&chunk);
300        let decoded = decode_chunk(&bytes).expect("decode");
301        assert_eq!(chunk, decoded);
302    }
303
304    #[test]
305    fn encode_decode_roundtrip_record() {
306        let expr = parse_cell("= { x: 1, y: 2, z: 3 }").expect("parse");
307        let chunk = compile_expr(&expr).expect("compile");
308        let bytes = encode_chunk(&chunk);
309        let decoded = decode_chunk(&bytes).expect("decode");
310        assert_eq!(chunk, decoded);
311    }
312
313    #[test]
314    fn encode_decode_roundtrip_functions() {
315        use crate::bytecode::compiler::compile;
316        use crate::parse::parse_program;
317        let src =
318            "fn double(x: i64) -> i64 { return x + x; } fn main() -> i64 { return double(21); }";
319        let prog = parse_program(src).expect("parse");
320        let chunk = compile(&prog).expect("compile");
321        let bytes = encode_chunk(&chunk);
322        let decoded = decode_chunk(&bytes).expect("decode");
323        assert_eq!(chunk, decoded);
324    }
325
326    #[test]
327    fn decode_bad_magic() {
328        let mut bad = vec![0u8; 14];
329        bad[0] = b'X';
330        let err = decode_chunk(&bad).expect_err("should fail");
331        assert!(matches!(err, ChunkDecodeError::BadMagic(_)));
332    }
333
334    #[test]
335    fn decode_bad_version() {
336        let mut buf = Vec::new();
337        buf.extend_from_slice(&MAGIC);
338        buf.extend_from_slice(&999u16.to_le_bytes()); // bad version
339        buf.extend_from_slice(&0u16.to_le_bytes()); // top_locals
340        buf.extend_from_slice(&0u16.to_le_bytes()); // const_count
341        buf.extend_from_slice(&0u16.to_le_bytes()); // func_count
342        buf.extend_from_slice(&0u16.to_le_bytes()); // code_len
343        let err = decode_chunk(&buf).expect_err("should fail");
344        assert!(matches!(err, ChunkDecodeError::BadVersion(999)));
345    }
346
347    #[test]
348    fn decode_too_short() {
349        let err = decode_chunk(&[0u8; 3]).expect_err("should fail");
350        assert!(matches!(err, ChunkDecodeError::TooShort));
351    }
352
353    #[test]
354    fn decode_truncated() {
355        let expr = parse_cell("= 1 + 2").expect("parse");
356        let chunk = compile_expr(&expr).expect("compile");
357        let mut bytes = encode_chunk(&chunk);
358        bytes.truncate(bytes.len() - 1); // truncate last byte
359        let err = decode_chunk(&bytes).expect_err("should fail");
360        assert!(matches!(err, ChunkDecodeError::Truncated));
361    }
362
363    #[test]
364    fn vm_executes_decoded_chunk() {
365        // Compile, encode, decode, then execute — verifying the full pipeline.
366        let expr = parse_cell("= 6 * 7").expect("parse");
367        let chunk = compile_expr(&expr).expect("compile");
368        let bytes = encode_chunk(&chunk);
369        let decoded = decode_chunk(&bytes).expect("decode");
370
371        let mut host = LocalHost::default();
372        let mut vm = Vm::new(&decoded, &mut host, Budget::default());
373        let result = vm.run().expect("vm run");
374        assert_eq!(result, crate::value::Value::I64(42));
375    }
376
377    #[test]
378    fn vm_executes_decoded_function() {
379        use crate::bytecode::compiler::compile;
380        use crate::parse::parse_program;
381        use crate::value::Value;
382
383        // Note: recursion is not supported in the 0.1 VM (no self-call).
384        // Use iterative version instead.
385        let src = "fn fact(n: i64) budget(steps: 10000) -> i64 { let r = 1; let i = 1; while i <= n { r = r * i; i = i + 1; } return r; }";
386        let prog = parse_program(src).expect("parse");
387        let chunk = compile(&prog).expect("compile");
388        let bytes = encode_chunk(&chunk);
389        let decoded = decode_chunk(&bytes).expect("decode");
390
391        let mut host = LocalHost::default();
392        let mut vm = Vm::new(&decoded, &mut host, Budget::default());
393        vm.run().expect("preamble");
394
395        let idx = decoded.find_function("fact").expect("fact exists");
396        let result = vm.call_function(idx, &[Value::I64(5)]).expect("call");
397        assert_eq!(result, Value::I64(120)); // 5! = 120
398    }
399}