Luigit
repositories / smith

smith

There are many coding harnesses - but this one is fast

owned by admin

smith-core/src/frame/commit.rs

Raw
//! SMH-SPEC-SPEC0001: bounded atomic tool completion, not a task engine.
use super::{
    BODY_PREFIX_LEN, ENTRY_METADATA_LEN, FRAME_PREFIX_LEN, Frame, HEADER_LEN, KIND_COMMIT,
    KIND_ENTRY, VERSION_ENTRY, decode_body, encode_entry_fields, entry_payload_length, fault,
    schema, seal, too_large,
};
use crate::content_codec::{BlockView, EntryContentView};
use crate::session::{EntryFrame, TOOL_MUTATION_KIND};
use serde::Deserialize;
use smith::error::{FrameFault, Result};
use smith::id::{EntryId, ToolCallId};
use smith::message::Role;
use smith::structured::{Kind, StructuredValue};

/// Root progress after one tool's complete result has become durable.
/// Session lifetime; two fixed identities, no independently authoritative state.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct ToolCompletionCheckpoint {
    /// Original admitted root input.
    pub submission_id: EntryId,
    /// Tool intent whose completion belongs to this change.
    pub call_id: ToolCallId,
}

/// Validate ordered completion members without allocating.
pub fn validate(
    checkpoint: &ToolCompletionCheckpoint,
    entries: &[EntryFrame; 3],
) -> std::result::Result<(), FrameFault> {
    if checkpoint.submission_id.as_u128() == 0 || checkpoint.call_id.as_u128() == 0 {
        return Err(schema("completion identities must be nonzero"));
    }
    for (index, entry) in entries.iter().enumerate() {
        if entry.id.as_u128() == 0
            || entry.id == checkpoint.submission_id
            || entries[..index].iter().any(|prior| prior.id == entry.id)
            || entry.parent.is_none()
            || (index > 0 && entry.parent != Some(entries[index - 1].id))
        {
            return Err(schema("completion member identity or order"));
        }
    }
    let EntryContentView::ToolResult {
        call_id,
        ok,
        output,
    } = member_content(&entries[0])?
    else {
        return Err(schema("completion requires result first"));
    };
    if call_id != checkpoint.call_id {
        return Err(schema("completion result identity mismatch"));
    }
    let EntryContentView::Meta { kind, detail } = member_content(&entries[1])? else {
        return Err(schema("completion requires mutation evidence second"));
    };
    if kind != TOOL_MUTATION_KIND {
        return Err(schema("completion mutation evidence kind"));
    }
    let field = detail
        .field("call_id")
        .map_err(|_| schema("completion mutation identity"))?
        .ok_or_else(|| schema("missing completion mutation identity"))?;
    let Kind::String(identity) = field
        .kind()
        .map_err(|_| schema("completion mutation identity"))?
    else {
        return Err(schema("completion mutation identity is not text"));
    };
    let identity = ToolCallId::deserialize(serde::de::value::StrDeserializer::<
        serde::de::value::Error,
    >::new(identity))
    .map_err(|_| schema("completion mutation identity shape"))?;
    if identity != call_id {
        return Err(schema("completion mutation identity mismatch"));
    }
    let EntryContentView::Message(message) = member_content(&entries[2])? else {
        return Err(schema("completion requires conversation result third"));
    };
    if message.role != Role::Tool
        || message.blocks().len() != 1
        || !matches!(message.blocks().next(), Some(BlockView::ToolResult {
            call_id: paired, ok: success, output: text,
        }) if paired == call_id && success == ok && text == output)
    {
        return Err(schema(
            "completion conversation must contain exactly the paired result",
        ));
    }
    Ok(())
}

fn member_content(entry: &EntryFrame) -> std::result::Result<EntryContentView<'_>, FrameFault> {
    let content = EntryContentView::decode(&entry.content)
        .map_err(|_| schema("invalid completion member content"))?;
    if content.kind() != entry.kind {
        return Err(schema("completion member kind mismatch"));
    }
    Ok(content)
}

pub(super) fn encode(
    checkpoint: &ToolCompletionCheckpoint,
    entries: &[EntryFrame; 3],
    limit: usize,
) -> Result<Vec<u8>> {
    validate(checkpoint, entries).map_err(fault)?;
    let length = entries.iter().try_fold(32usize, |length, entry| {
        let member_length = entry_payload_length(&entry.content, limit)?;
        length
            .checked_add(HEADER_LEN + BODY_PREFIX_LEN + member_length)
            .ok_or_else(|| too_large(limit, usize::MAX))
    })?;
    if length > limit {
        return Err(too_large(limit, length));
    }
    let mut out = Vec::with_capacity(FRAME_PREFIX_LEN + length + 4);
    out.resize(FRAME_PREFIX_LEN, 0);
    out.extend_from_slice(&checkpoint.submission_id.as_u128().to_le_bytes());
    out.extend_from_slice(&checkpoint.call_id.as_u128().to_le_bytes());
    for entry in entries {
        out.extend(encode_entry_fields(
            entry.id,
            entry.parent,
            entry.timestamp_ms,
            entry.kind,
            &entry.content,
            limit,
        )?);
    }
    seal(KIND_COMMIT, 1, out, limit)
}

pub(super) fn decode(payload: &[u8]) -> std::result::Result<Frame, FrameFault> {
    let checkpoint = ToolCompletionCheckpoint {
        submission_id: EntryId::from_u128(u128::from_le_bytes(
            payload
                .get(..16)
                .ok_or_else(|| schema("short completion root"))?
                .try_into()
                .map_err(|_| schema("completion root"))?,
        )),
        call_id: ToolCallId::from_u128(u128::from_le_bytes(
            payload
                .get(16..32)
                .ok_or_else(|| schema("short completion call"))?
                .try_into()
                .map_err(|_| schema("completion call"))?,
        )),
    };
    let mut remaining = &payload[32..];
    let entries = Box::new([
        member(&mut remaining)?,
        member(&mut remaining)?,
        member(&mut remaining)?,
    ]);
    if !remaining.is_empty() {
        return Err(schema("completion has excess members or trailing bytes"));
    }
    validate(&checkpoint, &entries)?;
    Ok(Frame::Commit {
        checkpoint,
        entries,
    })
}

pub(super) fn member(remaining: &mut &[u8]) -> std::result::Result<EntryFrame, FrameFault> {
    let header = remaining
        .get(..HEADER_LEN)
        .ok_or_else(|| schema("short completion member"))?;
    let word = |range: std::ops::Range<usize>| -> std::result::Result<u32, FrameFault> {
        Ok(u32::from_le_bytes(
            header[range]
                .try_into()
                .map_err(|_| schema("member header"))?,
        ))
    };
    if word(8..12)? != crc32fast::hash(&header[..8])
        || header[4..6] != KIND_ENTRY.to_le_bytes()
        || header[6..8] != VERSION_ENTRY.to_le_bytes()
    {
        return Err(schema("completion member must be an intact typed entry"));
    }
    let end = HEADER_LEN
        .checked_add(word(0..4)? as usize)
        .ok_or_else(|| schema("completion member overflow"))?;
    let body = remaining
        .get(HEADER_LEN..end)
        .ok_or_else(|| schema("short completion member body"))?;
    let Frame::Known { entry } = decode_body(KIND_ENTRY, VERSION_ENTRY, body)? else {
        return Err(schema("completion member is not an entry"));
    };
    *remaining = &remaining[end..];
    Ok(entry)
}

/// Validated member boundaries inside the containing checksum envelope.
/// Only readers which already validated the entire envelope may use these offsets.
pub const fn member_offsets(at: u64, entries: &[EntryFrame; 3]) -> [u64; 3] {
    let first = at + FRAME_PREFIX_LEN as u64 + 32;
    let second = first
        + (HEADER_LEN + BODY_PREFIX_LEN + ENTRY_METADATA_LEN + entries[0].content.len()) as u64;
    let third = second
        + (HEADER_LEN + BODY_PREFIX_LEN + ENTRY_METADATA_LEN + entries[1].content.len()) as u64;
    [first, second, third]
}