//! 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, 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> { 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 { 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 { let header = remaining .get(..HEADER_LEN) .ok_or_else(|| schema("short completion member"))?; let word = |range: std::ops::Range| -> std::result::Result { 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] }