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]
}