clm-kernel 0.0.22

Cubical Logic Model (CLM) sovereign execution engine, CPN-VM, and Cordis spatiotemporal substrate
Documentation
//! Layer 0: The strict scanner for serialized payloads of the profile `clm.spec.v1`
//! Canonical Path: kernel/clm_rust_core/src/layer0/spec_scan.rs
//!
//! `decode_payload` reads serialized text into a value inside the profile, or
//! refuses it with one machine-readable reason. It is pure and reads no store.

use std::collections::BTreeSet;

use serde_json::{Map, Number, Value};

use crate::layer0::spec_profile::{
    descend, is_safe_integer, Refusable, SpecProfileError, MAX_NESTING_DEPTH, REFUSED_DUPLICATE_KEY, REFUSED_FLOAT,
    REFUSED_INTEGER_RANGE, REFUSED_INVALID_STRING, REFUSED_MALFORMED, REFUSED_NON_ASCII_KEY,
};

const SURROGATE_FIRST: u32 = 0xD800;
const LOW_SURROGATE_FIRST: u32 = 0xDC00;
const SURROGATE_LAST: u32 = 0xDFFF;
const ASTRAL_FIRST: u32 = 0x1_0000;
pub(crate) const FIRST_UNESCAPED_BYTE: u8 = 0x20;
const UNICODE_ESCAPE_DIGITS: usize = 4;

/// A string as scanned. A lone surrogate escape has no place in a Rust string, so
/// the bytes hold it in the three-byte form and `is_well_formed` is false.
struct ScannedText {
    bytes: Vec<u8>,
    is_well_formed: bool,
}

impl ScannedText {
    fn into_string(self) -> String {
        match String::from_utf8(self.bytes) {
            Ok(text) => text,
            Err(error) => String::from_utf8_lossy(error.as_bytes()).into_owned(),
        }
    }
}

/// A strict scanner for serialized text.
///
/// A defect of the grammar, a float and a repeated key are refused where the
/// scan meets them. A defect of a scanned value (an integer outside the range, a
/// non-ASCII key, a string with a lone surrogate) is held back, and the first
/// one in document order is reported only when the whole text has scanned.
struct Scanner<'a> {
    bytes: &'a [u8],
    at: usize,
    held_back: Option<SpecProfileError>,
}

impl Scanner<'_> {
    fn byte(&self, at: usize) -> Option<u8> {
        self.bytes.get(at).copied()
    }

    fn peek(&self) -> Option<u8> {
        self.byte(self.at)
    }

    fn starts_with(&self, literal: &[u8]) -> bool {
        self.bytes.get(self.at..).is_some_and(|rest| rest.starts_with(literal))
    }

    fn is_digit(&self, at: usize) -> bool {
        self.byte(at).is_some_and(|byte| byte.is_ascii_digit())
    }

    fn skip_whitespace(&mut self) {
        while matches!(self.peek(), Some(b' ' | b'\t' | b'\n' | b'\r')) {
            self.at += 1;
        }
    }

    fn malformed(&self, what: &str) -> SpecProfileError {
        SpecProfileError::new(REFUSED_MALFORMED, format!("{what} at byte {}", self.at))
    }

    fn hold_back(&mut self, reason: &'static str, detail: String) {
        if self.held_back.is_none() {
            self.held_back = Some(SpecProfileError::new(reason, detail));
        }
    }

    fn consume(&mut self, wanted: u8, what: &str) -> Refusable<()> {
        if self.peek() != Some(wanted) {
            return Err(self.malformed(what));
        }
        self.at += 1;
        Ok(())
    }

    fn value(&mut self, depth: usize) -> Refusable<Value> {
        match self.peek() {
            Some(b'"') => self.string_value(),
            Some(b'{') => self.object(depth),
            Some(b'[') => self.array(depth),
            Some(b'n') => self.literal(b"null", Value::Null),
            Some(b't') => self.literal(b"true", Value::Bool(true)),
            Some(b'f') => self.literal(b"false", Value::Bool(false)),
            Some(b'N') => self.constant("NaN"),
            Some(b'I') => self.constant("Infinity"),
            Some(b'-') if self.starts_with(b"-Infinity") => self.constant("-Infinity"),
            _ => self.number(),
        }
    }

    fn literal(&mut self, literal: &[u8], value: Value) -> Refusable<Value> {
        if !self.starts_with(literal) {
            return Err(self.malformed("expecting a value"));
        }
        self.at += literal.len();
        Ok(value)
    }

    fn constant(&mut self, token: &str) -> Refusable<Value> {
        if !self.starts_with(token.as_bytes()) {
            return Err(self.malformed("expecting a value"));
        }
        Err(SpecProfileError::new(REFUSED_FLOAT, format!("the constant {token} is not allowed")))
    }

    fn number(&mut self) -> Refusable<Value> {
        let start = self.at;
        let mut end = start + usize::from(self.peek() == Some(b'-'));
        match self.byte(end) {
            Some(b'0') => end += 1,
            Some(b'1'..=b'9') => {
                while self.is_digit(end) {
                    end += 1;
                }
            }
            _ => return Err(self.malformed("expecting a value")),
        }
        if self.has_fraction(end) || self.has_exponent(end) {
            return Err(SpecProfileError::new(REFUSED_FLOAT, format!("the number at byte {start} is not an integer")));
        }
        self.at = end;
        let token = self.bytes.get(start..end).and_then(|digits| std::str::from_utf8(digits).ok());
        match token.and_then(|digits| digits.parse::<i64>().ok()) {
            Some(integer) if is_safe_integer(integer) => Ok(Value::Number(Number::from(integer))),
            _ => {
                self.hold_back(REFUSED_INTEGER_RANGE, format!("the integer at byte {start} is outside the safe range"));
                Ok(Value::Null)
            }
        }
    }

    fn has_fraction(&self, at: usize) -> bool {
        self.byte(at) == Some(b'.') && self.is_digit(at + 1)
    }

    fn has_exponent(&self, at: usize) -> bool {
        if !matches!(self.byte(at), Some(b'e' | b'E')) {
            return false;
        }
        let signed = usize::from(matches!(self.byte(at + 1), Some(b'+' | b'-')));
        self.is_digit(at + 1 + signed)
    }

    fn string_value(&mut self) -> Refusable<Value> {
        let start = self.at;
        let scanned = self.string()?;
        if !scanned.is_well_formed {
            self.hold_back(REFUSED_INVALID_STRING, format!("the string at byte {start} is not valid Unicode"));
        }
        Ok(Value::String(scanned.into_string()))
    }

    fn string(&mut self) -> Refusable<ScannedText> {
        self.consume(b'"', "expecting a quoted string")?;
        let mut scanned = ScannedText { bytes: Vec::new(), is_well_formed: true };
        loop {
            match self.peek() {
                None => return Err(self.malformed("unterminated string")),
                Some(b'"') => {
                    self.at += 1;
                    return Ok(scanned);
                }
                Some(b'\\') => {
                    self.at += 1;
                    self.escape(&mut scanned)?;
                }
                Some(control) if control < FIRST_UNESCAPED_BYTE => {
                    return Err(self.malformed("control character in a string"));
                }
                Some(plain) => {
                    scanned.bytes.push(plain);
                    self.at += 1;
                }
            }
        }
    }

    fn escape(&mut self, scanned: &mut ScannedText) -> Refusable<()> {
        let plain = match self.peek() {
            Some(same @ (b'"' | b'\\' | b'/')) => same,
            Some(b'b') => 0x08,
            Some(b'f') => 0x0C,
            Some(b'n') => b'\n',
            Some(b'r') => b'\r',
            Some(b't') => b'\t',
            Some(b'u') => {
                self.at += 1;
                return self.unicode_escape(scanned);
            }
            _ => return Err(self.malformed("invalid escape")),
        };
        scanned.bytes.push(plain);
        self.at += 1;
        Ok(())
    }

    fn hex_unit(&self, at: usize) -> Refusable<u32> {
        let digits = self.bytes.get(at..at + UNICODE_ESCAPE_DIGITS);
        let fold = |unit: u32, digit: &u8| Some(unit * 16 + char::from(*digit).to_digit(16)?);
        let unit = digits.and_then(|digits| digits.iter().try_fold(0_u32, fold));
        unit.ok_or_else(|| self.malformed("invalid \\u escape"))
    }

    /// Reads the four digits after `\u`. A high surrogate joins a low surrogate
    /// escape that follows it directly. Any other surrogate stands alone.
    fn unicode_escape(&mut self, scanned: &mut ScannedText) -> Refusable<()> {
        let mut code = self.hex_unit(self.at)?;
        self.at += UNICODE_ESCAPE_DIGITS;
        if (SURROGATE_FIRST..LOW_SURROGATE_FIRST).contains(&code) && self.starts_with(b"\\u") {
            let low = self.hex_unit(self.at + 2)?;
            if (LOW_SURROGATE_FIRST..=SURROGATE_LAST).contains(&low) {
                code = ASTRAL_FIRST + ((code - SURROGATE_FIRST) << 10) + (low - LOW_SURROGATE_FIRST);
                self.at += 2 + UNICODE_ESCAPE_DIGITS;
            }
        }
        match char::from_u32(code) {
            Some(scalar) => scanned.bytes.extend_from_slice(scalar.encode_utf8(&mut [0; 4]).as_bytes()),
            None => {
                scanned.is_well_formed = false;
                let [_, _, high, low] = code.to_be_bytes();
                let middle = 0x80 | ((high & 0x0F) << 2) | (low >> 6);
                scanned.bytes.extend_from_slice(&[0xE0 | (high >> 4), middle, 0x80 | (low & 0x3F)]);
            }
        }
        Ok(())
    }

    fn array(&mut self, depth: usize) -> Refusable<Value> {
        let depth = descend(depth, MAX_NESTING_DEPTH, "the text")?;
        self.at += 1;
        self.skip_whitespace();
        let mut items = Vec::new();
        if self.peek() == Some(b']') {
            self.at += 1;
            return Ok(Value::Array(items));
        }
        loop {
            items.push(self.value(depth)?);
            self.skip_whitespace();
            if self.peek() == Some(b']') {
                self.at += 1;
                return Ok(Value::Array(items));
            }
            self.consume(b',', "expecting ',' or ']'")?;
            self.skip_whitespace();
        }
    }

    fn object(&mut self, depth: usize) -> Refusable<Value> {
        let depth = descend(depth, MAX_NESTING_DEPTH, "the text")?;
        self.at += 1;
        self.skip_whitespace();
        let mut pairs = Vec::new();
        if self.peek() == Some(b'}') {
            self.at += 1;
            return unique_members(pairs);
        }
        loop {
            pairs.push(self.member(depth)?);
            self.skip_whitespace();
            if self.peek() == Some(b'}') {
                self.at += 1;
                return unique_members(pairs);
            }
            self.consume(b',', "expecting ',' or '}'")?;
            self.skip_whitespace();
        }
    }

    fn member(&mut self, depth: usize) -> Refusable<(ScannedText, Value)> {
        let start = self.at;
        let key = self.string()?;
        if !key.is_well_formed || !key.bytes.is_ascii() {
            self.hold_back(REFUSED_NON_ASCII_KEY, format!("the key at byte {start} is not ASCII"));
        }
        self.skip_whitespace();
        self.consume(b':', "expecting ':'")?;
        self.skip_whitespace();
        Ok((key, self.value(depth)?))
    }
}

/// Builds an object when it closes. Keys are compared as decoded, so an escaped
/// key and its plain form collide.
fn unique_members(pairs: Vec<(ScannedText, Value)>) -> Refusable<Value> {
    let mut seen: BTreeSet<&[u8]> = BTreeSet::new();
    for (key, _) in &pairs {
        if !seen.insert(key.bytes.as_slice()) {
            let shown = String::from_utf8_lossy(&key.bytes);
            return Err(SpecProfileError::new(REFUSED_DUPLICATE_KEY, format!("the key {shown:?} appears twice")));
        }
    }
    Ok(Value::Object(pairs.into_iter().map(|(key, value)| (key.into_string(), value)).collect::<Map<String, Value>>()))
}

/// Strictly parses serialized text. Refuses floats, duplicate keys and malformed input.
pub fn decode_payload(raw: impl AsRef<[u8]>) -> Refusable<Value> {
    let bytes = raw.as_ref();
    if let Err(error) = std::str::from_utf8(bytes) {
        return Err(SpecProfileError::new(REFUSED_MALFORMED, format!("the text is not UTF-8: {error}")));
    }
    let mut scanner = Scanner { bytes, at: 0, held_back: None };
    scanner.skip_whitespace();
    let value = scanner.value(0)?;
    scanner.skip_whitespace();
    if scanner.at != bytes.len() {
        return Err(scanner.malformed("extra data"));
    }
    match scanner.held_back {
        Some(refusal) => Err(refusal),
        None => Ok(value),
    }
}