Luigit
repositories / smith

smith

There are many coding harnesses - but this one is fast

owned by admin

smith-core/src/frame/payload.rs

Raw
//! Same-ledger immutable nested payload chunks (`SMH-SPEC-SPEC0001`).
//! Wire: root/call/effect (16 bytes each), effect index (u16), phase (u8),
//! ordinal (u16), then 1..=64 KiB bytes; integers are little endian.
//! Each phase is contiguous: full chunks followed by at most one short chunk.
//! Logical length comes from its publishing marker; count derives by ceiling division.
use super::{FRAME_PREFIX_LEN, Frame, fault, schema, seal};
use crate::metadata::{NESTED_CHUNK_BYTES_MAX, NESTED_CHUNKS_MAX};
use smith::error::{FrameFault, Result};
use smith::id::{EntryId, ToolCallId};

const CHUNK_HEADER_LEN: usize = 3 * 16 + 2 + 1 + 2;

/// Which canonical value the chunks precede.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum NestedPayloadPhase {
    /// Must become durable before the intent acknowledgement and effect dispatch.
    Input,
    /// Must become durable before the atomic completion acknowledgement.
    Output,
}

/// One CRC-protected immutable chunk; never a conversation/history member.
/// Owned for one frame only, not copied into the resident session arena.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct NestedPayloadChunk {
    /// Admitted root.
    pub submission_id: EntryId,
    /// Outer call.
    pub call_id: ToolCallId,
    /// Stable nested intent entry identity, shared by both phases.
    pub effect_id: EntryId,
    /// Nested effect ordinal.
    pub index: u16,
    /// Canonical value being stored.
    pub phase: NestedPayloadPhase,
    /// Zero-based contiguous chunk ordinal.
    pub ordinal: u16,
    /// Exact bytes, possibly split within a UTF-8 scalar.
    pub bytes: Vec<u8>,
}

impl NestedPayloadChunk {
    pub(crate) fn validate(&self) -> std::result::Result<(), FrameFault> {
        if self.submission_id.as_u128() == 0
            || self.call_id.as_u128() == 0
            || self.effect_id.as_u128() == 0
            || self.index >= crate::metadata::NESTED_EFFECTS_MAX
            || usize::from(self.ordinal) >= NESTED_CHUNKS_MAX
            || self.bytes.is_empty()
            || self.bytes.len() > NESTED_CHUNK_BYTES_MAX
        {
            return Err(schema("invalid nested payload chunk"));
        }
        Ok(())
    }
}

pub(super) fn encode(chunk: &NestedPayloadChunk, limit: usize) -> Result<Vec<u8>> {
    chunk.validate().map_err(fault)?;
    let mut out = Vec::with_capacity(FRAME_PREFIX_LEN + CHUNK_HEADER_LEN + chunk.bytes.len() + 4);
    out.resize(FRAME_PREFIX_LEN, 0);
    out.extend_from_slice(&chunk.submission_id.as_u128().to_le_bytes());
    out.extend_from_slice(&chunk.call_id.as_u128().to_le_bytes());
    out.extend_from_slice(&chunk.effect_id.as_u128().to_le_bytes());
    out.extend_from_slice(&chunk.index.to_le_bytes());
    out.push(match chunk.phase {
        NestedPayloadPhase::Input => 0,
        NestedPayloadPhase::Output => 1,
    });
    out.extend_from_slice(&chunk.ordinal.to_le_bytes());
    out.extend_from_slice(&chunk.bytes);
    seal(super::KIND_NESTED_PAYLOAD, 1, out, limit)
}

pub(super) fn decode(payload: &[u8]) -> std::result::Result<Frame, FrameFault> {
    if payload.len() <= CHUNK_HEADER_LEN
        || payload.len() > CHUNK_HEADER_LEN + NESTED_CHUNK_BYTES_MAX
    {
        return Err(schema("invalid nested chunk length"));
    }
    let chunk = NestedPayloadChunk {
        submission_id: EntryId::from_u128(u128::from_le_bytes(
            payload[..16].try_into().map_err(|_| schema("chunk root"))?,
        )),
        call_id: ToolCallId::from_u128(u128::from_le_bytes(
            payload[16..32]
                .try_into()
                .map_err(|_| schema("chunk call"))?,
        )),
        effect_id: EntryId::from_u128(u128::from_le_bytes(
            payload[32..48]
                .try_into()
                .map_err(|_| schema("chunk effect"))?,
        )),
        index: u16::from_le_bytes([payload[48], payload[49]]),
        phase: match payload[50] {
            0 => NestedPayloadPhase::Input,
            1 => NestedPayloadPhase::Output,
            _ => return Err(schema("chunk phase")),
        },
        ordinal: u16::from_le_bytes([payload[51], payload[52]]),
        bytes: payload[CHUNK_HEADER_LEN..].to_vec(),
    };
    chunk.validate()?;
    Ok(Frame::NestedPayload {
        chunk: Box::new(chunk),
    })
}

#[cfg(test)]
mod tests {
    use super::*;
    use proptest::prelude::*;

    proptest! {
        #[test]
        fn chunk_codec_roundtrips_exact_bytes(bytes in prop::collection::vec(any::<u8>(), 1..=4096), ordinal in 0u16..512, output in any::<bool>()) {
            let frame = Frame::NestedPayload { chunk: Box::new(NestedPayloadChunk {
                submission_id: EntryId::from_u128(1), call_id: ToolCallId::from_u128(2), effect_id: EntryId::from_u128(3),
                index: 0, phase: if output { NestedPayloadPhase::Output } else { NestedPayloadPhase::Input }, ordinal, bytes,
            }) };
            let encoded = frame.encode(8192).unwrap();
            prop_assert_eq!(super::super::read_frames(&mut encoded.as_slice(), 8192).unwrap().frames, vec![frame]);
        }
    }
}