repositories / smith
smith
There are many coding harnesses - but this one is fast
owned by admin
smith-core/src/context.rs
Raw//! SMH-SPEC-SPEC0001: Sessions, Context edits and Effective request context.
//!
//! Projection borrows immutable entry bytes; replacements own bounded text.
//! Prototype schema 2 intentionally replaces schema 1 without migration.
//! Operations: 0 omit, 1 text, 2 assistant prose, 3 call-ID-bound result output.
use crate::content_codec::{BlockView, EntryContentView, MessageView};
use crate::session::{Entry, EntryContent, EntryContentRef, EntryKind, Session};
use smith::error::{Result, SessionCode, SmithError};
use smith::id::{EntryId, ToolCallId};
use smith::message::{ContentBlock, Message, Role};
/// Maximum operations in one atomic batch.
pub const CONTEXT_EDIT_ITEMS_MAX: usize = 64;
/// Maximum encoded batch bytes, including tags and lengths.
pub const CONTEXT_EDIT_BYTES_MAX: usize = 64 * 1024;
pub use smith::lifecycle::{ContextEdit, ContextReplacement};
pub(crate) fn invalid(message: &str) -> SmithError {
SmithError::Session {
code: SessionCode::SessionIncompleteContext,
message: message.into(),
}
}
/// Validated borrowed typed edit payload, without the entry content tag.
#[derive(Clone, Copy, Debug)]
pub struct ContextBatchView<'a>(&'a [u8]);
fn take<'a>(bytes: &mut &'a [u8], count: usize) -> Result<&'a [u8]> {
let (head, tail) = bytes
.split_at_checked(count)
.ok_or_else(|| invalid("truncated context edit"))?;
*bytes = tail;
Ok(head)
}
#[derive(Clone, Copy)]
enum ReplacementView<'a> {
Text(&'a str),
AssistantText(&'a str),
ToolResultOutput {
call_id: ToolCallId,
output: &'a str,
},
}
impl<'a> From<&'a ContextReplacement> for ReplacementView<'a> {
fn from(value: &'a ContextReplacement) -> Self {
match value {
ContextReplacement::Text(text) => Self::Text(text),
ContextReplacement::AssistantText(text) => Self::AssistantText(text),
ContextReplacement::ToolResultOutput { call_id, output } => Self::ToolResultOutput {
call_id: *call_id,
output,
},
}
}
}
impl<'a> ReplacementView<'a> {
const fn text(self) -> &'a str {
match self {
Self::Text(text) | Self::AssistantText(text) => text,
Self::ToolResultOutput { output, .. } => output,
}
}
fn owned(self) -> ContextReplacement {
match self {
Self::Text(text) => ContextReplacement::Text(text.into()),
Self::AssistantText(text) => ContextReplacement::AssistantText(text.into()),
Self::ToolResultOutput { call_id, output } => ContextReplacement::ToolResultOutput {
call_id,
output: output.into(),
},
}
}
}
fn operation<'a>(bytes: &mut &'a [u8]) -> Result<(EntryId, Option<ReplacementView<'a>>)> {
let target = EntryId::from_u128(u128::from_le_bytes(
take(bytes, 16)?
.try_into()
.map_err(|_| invalid("edit identity"))?,
));
let tag = take(bytes, 1)?[0];
if tag == 0 {
return Ok((target, None));
}
let call_id = if tag == 3 {
Some(ToolCallId::from_u128(u128::from_le_bytes(
take(bytes, 16)?
.try_into()
.map_err(|_| invalid("edit call identity"))?,
)))
} else {
None
};
let length = u32::from_le_bytes(
take(bytes, 4)?
.try_into()
.map_err(|_| invalid("edit length"))?,
) as usize;
let text =
std::str::from_utf8(take(bytes, length)?).map_err(|_| invalid("edit text is not UTF-8"))?;
let replacement = match (tag, call_id) {
(1, _) => ReplacementView::Text(text),
(2, _) => ReplacementView::AssistantText(text),
(3, Some(call_id)) => ReplacementView::ToolResultOutput {
call_id,
output: text,
},
_ => return Err(invalid("unsupported required context edit operation")),
};
Ok((target, Some(replacement)))
}
impl<'a> ContextBatchView<'a> {
/// Validate schema version, item/byte bounds and all spans before borrowing.
///
/// # Errors
/// Rejects unknown semantics, malformed spans and exceeded bounds.
pub fn decode(bytes: &'a [u8]) -> Result<Self> {
if bytes.len() > CONTEXT_EDIT_BYTES_MAX || bytes.len() < 3 || bytes[0] != 2 {
return Err(invalid(
"unsupported or oversized required context edit schema",
));
}
let count = u16::from_le_bytes([bytes[1], bytes[2]]) as usize;
if count == 0 || count > CONTEXT_EDIT_ITEMS_MAX {
return Err(invalid("context edit batch must contain 1..=64 operations"));
}
let mut rest = &bytes[3..];
for _ in 0..count {
operation(&mut rest)?;
}
if !rest.is_empty() {
return Err(invalid("trailing context edit bytes"));
}
Ok(Self(bytes))
}
fn visit(
self,
mut visit: impl FnMut(EntryId, Option<ReplacementView<'a>>) -> Result<()>,
) -> Result<()> {
let mut rest = &self.0[3..];
while !rest.is_empty() {
let (target, replacement) = operation(&mut rest)?;
visit(target, replacement)?;
}
Ok(())
}
/// Materialize at an API boundary, never as another authoritative history.
///
/// # Errors
/// Returns an error for malformed typed operations.
pub fn materialize(self) -> Result<Vec<ContextEdit>> {
let mut edits = Vec::with_capacity(u16::from_le_bytes([self.0[1], self.0[2]]) as usize);
self.visit(|target, replacement| {
edits.push(ContextEdit {
target,
replacement: replacement.map(ReplacementView::owned),
});
Ok(())
})?;
Ok(edits)
}
/// Search replacement text without copying it.
#[must_use]
pub fn contains(self, pattern: &str) -> bool {
let mut found = false;
let _validated = self.visit(|_, replacement| {
found |= replacement.is_some_and(|value| value.text().contains(pattern));
Ok(())
});
found
}
}
fn encoded_length(edits: &[ContextEdit]) -> Result<usize> {
if edits.is_empty() || edits.len() > CONTEXT_EDIT_ITEMS_MAX {
return Err(invalid("context edit batch must contain 1..=64 operations"));
}
let mut length = 3usize;
for edit in edits {
length = length
.checked_add(
17 + edit.replacement.as_ref().map_or(0, |replacement| {
4 + ReplacementView::from(replacement).text().len()
+ if matches!(replacement, ContextReplacement::ToolResultOutput { .. }) {
16
} else {
0
}
}),
)
.ok_or_else(|| invalid("context edit byte count overflow"))?;
if length > CONTEXT_EDIT_BYTES_MAX {
return Err(invalid("context edit batch exceeds 65536 bytes"));
}
}
Ok(length)
}
pub(crate) fn encode(edits: &[ContextEdit], out: &mut Vec<u8>) -> Result<()> {
let length = encoded_length(edits)?;
out.try_reserve_exact(length)
.map_err(|_| invalid("context edit allocation failed"))?;
out.push(2);
out.extend_from_slice(
&u16::try_from(edits.len())
.map_err(|_| invalid("edit count exceeds u16"))?
.to_le_bytes(),
);
for edit in edits {
out.extend_from_slice(&edit.target.as_u128().to_le_bytes());
match &edit.replacement {
None => out.push(0),
Some(replacement) => {
let value = ReplacementView::from(replacement);
match value {
ReplacementView::Text(_) => out.push(1),
ReplacementView::AssistantText(_) => out.push(2),
ReplacementView::ToolResultOutput { call_id, .. } => {
out.push(3);
out.extend_from_slice(&call_id.as_u128().to_le_bytes());
}
}
let text = value.text();
out.extend_from_slice(
&u32::try_from(text.len())
.map_err(|_| invalid("edit text exceeds u32"))?
.to_le_bytes(),
);
out.extend_from_slice(text.as_bytes());
}
}
}
Ok(())
}
enum AppliedEdit<'a> {
Unchanged,
Omit,
Replace(ReplacementView<'a>),
}
impl<'a> From<Option<ReplacementView<'a>>> for AppliedEdit<'a> {
fn from(text: Option<ReplacementView<'a>>) -> Self {
text.map_or(Self::Omit, Self::Replace)
}
}
impl Session {
fn retained_entries(&self) -> &[Entry] {
let entries = self.active_branch().selected_entries();
let start = self
.compaction_boundary()
.and_then(|id| entries.iter().position(|entry| entry.id == id))
.map_or(0, |index| index + 1);
&entries[start..]
}
// Prepare the resident edit suffix once; ordinary metadata is not an edit payload.
pub(crate) fn context_edit_entries(&self) -> &[Entry] {
if self.source_edits().is_some() {
return &[];
}
let entries = self.retained_entries();
entries
.iter()
.position(|entry| {
matches!(entry.kind, EntryKind::Meta { compaction: false })
&& self.bytes(entry).first() == Some(&4)
})
.map_or(&[], |first| &entries[first..])
}
fn replacement<'a>(
&'a self,
target: EntryId,
pending: &'a [ContextEdit],
edit_entries: &'a [Entry],
) -> Result<AppliedEdit<'a>> {
if let Some(edit) = pending.iter().find(|edit| edit.target == target) {
return Ok(AppliedEdit::from(
edit.replacement.as_ref().map(ReplacementView::from),
));
}
if let Some(edits) = self.source_edits() {
return Ok(edits
.iter()
.find(|edit| edit.target == target)
.map_or(AppliedEdit::Unchanged, |edit| {
AppliedEdit::from(edit.replacement.as_ref().map(ReplacementView::from))
}));
}
for entry in edit_entries.iter().rev() {
if !matches!(entry.kind, EntryKind::Meta { compaction: false })
|| self.bytes(entry).first() != Some(&4)
{
continue;
}
if let EntryContentView::ContextEdit(batch) =
Self::decode_content(entry, self.bytes(entry))?
{
let mut found = None;
batch.visit(|id, replacement| {
if id == target {
found = Some(AppliedEdit::from(replacement));
}
Ok(())
})?;
if let Some(found) = found {
return Ok(found);
}
}
}
Ok(AppliedEdit::Unchanged)
}
pub(crate) fn context_omits(&self, target: EntryId, edit_entries: &[Entry]) -> Result<bool> {
Ok(matches!(
self.replacement(target, &[], edit_entries)?,
AppliedEdit::Omit
))
}
/// Ordered effective messages, distinct from raw content inspection.
///
/// # Errors
/// Rejects unsupported required semantics or invalid tool pairing.
pub fn projected_messages(&self) -> Result<Vec<Message>> {
self.map_projected_messages(|_| Ok(()))
}
/// Transform each request-local message before retaining the next one.
pub(crate) fn map_projected_messages(
&self,
mut transform: impl FnMut(&mut Message) -> Result<()>,
) -> Result<Vec<Message>> {
let edit_entries = self.context_edit_entries();
let has_edits =
!edit_entries.is_empty() || self.source_edits().is_some_and(|edits| !edits.is_empty());
let mut pairing_validated = false;
let mut messages = Vec::new();
for entry in self.retained_entries() {
if !matches!(entry.kind, EntryKind::Message { .. }) {
continue;
}
let replacement = if has_edits {
self.replacement(entry.id, &[], edit_entries)?
} else {
AppliedEdit::Unchanged
};
let mut message = match replacement {
AppliedEdit::Omit => continue,
AppliedEdit::Unchanged => {
let EntryContent::Message(message) = self.content(entry)? else {
return Err(invalid("context target is not a message"));
};
message
}
AppliedEdit::Replace(replacement) => {
let bytes = self.raw_bytes(entry)?;
let EntryContentView::Message(message) = Self::decode_content(entry, &bytes)?
else {
return Err(invalid("context target is not a message"));
};
replace_message(&message, &replacement)?
}
};
// Pairing is vacuous without tool-role messages or tool blocks.
if !pairing_validated
&& (message.role == Role::Tool
|| message.blocks.iter().any(|block| {
matches!(
block,
ContentBlock::ToolUse { .. } | ContentBlock::ToolResult { .. }
)
}))
{
self.validate_projection(&[])?;
pairing_validated = true;
}
transform(&mut message)?;
messages.push(message);
}
Ok(messages)
}
// Replacements preserve tool blocks, so pairing can traverse borrowed raw blocks.
fn validate_projection(&self, pending_edits: &[ContextEdit]) -> Result<()> {
let edit_entries = self.context_edit_entries();
let mut seen = Vec::new();
let mut pending = Vec::new();
for entry in self.retained_entries() {
if !matches!(entry.kind, EntryKind::Message { .. }) {
continue;
}
let replacement = self.replacement(entry.id, pending_edits, edit_entries)?;
if matches!(replacement, AppliedEdit::Omit) {
continue;
}
let bytes = self.raw_bytes(entry)?;
let EntryContentView::Message(message) = Self::decode_content(entry, &bytes)? else {
return Err(invalid("context target is not a message"));
};
if let AppliedEdit::Replace(value) = replacement {
validate_replacement(&message, &value)?;
}
if message.role == Role::Tool
&& !message
.blocks()
.any(|block| matches!(block, BlockView::ToolResult { .. }))
{
return Err(invalid("tool-role context message lacks result schema"));
}
if !pending.is_empty() && message.role != Role::Tool {
return Err(invalid("context interrupts pending tool results"));
}
for block in message.blocks() {
match block {
BlockView::ToolUse { call_id, .. } => {
if message.role != Role::Assistant
|| seen.contains(&call_id)
|| seen.len() == crate::session::PROVIDER_CALL_IDENTITIES_MAX
{
return Err(invalid("invalid or duplicate context tool call"));
}
seen.push(call_id);
pending.push(call_id);
}
BlockView::ToolResult { call_id, .. } => {
if message.role != Role::Tool {
return Err(invalid("tool result has invalid role"));
}
let index = pending
.iter()
.position(|id| *id == call_id)
.ok_or_else(|| invalid("context tool result lacks preceding call"))?;
pending.remove(index);
}
_ => {}
}
}
}
if !pending.is_empty() {
return Err(invalid("context has unmatched tool calls"));
}
Ok(())
}
/// Validate an entire bounded batch, persist once, then publish its entry.
/// The callback must acknowledge durable persistence before returning Ok.
///
/// # Errors
/// Invalid targets, pairing, bounds or persistence leave the session unchanged.
pub fn edit_context_with(
&mut self,
edits: &[ContextEdit],
persist: impl FnOnce(&Entry, &[u8]) -> Result<()>,
) -> Result<EntryId> {
self.append_with(EntryContentRef::ContextEdit(edits), persist)
.map(|entry| entry.id)
}
pub(crate) fn validate_context_edits(&self, edits: &[ContextEdit]) -> Result<()> {
encoded_length(edits)?;
let entries = self.retained_entries();
for (index, edit) in edits.iter().enumerate() {
if edits[..index]
.iter()
.any(|prior| prior.target == edit.target)
{
return Err(invalid("duplicate context edit target"));
}
if !entries.iter().any(|entry| {
entry.id == edit.target && matches!(entry.kind, EntryKind::Message { .. })
}) {
return Err(invalid(
"context edit target is unknown, off-branch or not retained message content",
));
}
}
self.validate_projection(edits)?;
Ok(())
}
}
fn replace_message(
message: &MessageView<'_>,
replacement: &ReplacementView<'_>,
) -> Result<Message> {
validate_replacement(message, replacement)?;
let blocks = if let ReplacementView::Text(text) = replacement {
vec![ContentBlock::Text((*text).into())]
} else {
let mut blocks = Vec::with_capacity(
message.blocks().len()
+ usize::from(matches!(replacement, ReplacementView::AssistantText(_))),
);
if let ReplacementView::AssistantText(text) = replacement {
blocks.push(ContentBlock::Text((*text).into()));
}
for mut block in message.blocks() {
match (replacement, &block) {
(ReplacementView::AssistantText(_), BlockView::Text(_)) => continue,
(
ReplacementView::ToolResultOutput { call_id, output },
BlockView::ToolResult {
call_id: id, ok, ..
},
) if id == call_id => {
block = BlockView::ToolResult {
call_id: *id,
ok: *ok,
output,
};
}
_ => {}
}
block.materialize_into(&mut blocks)?;
}
blocks
};
Ok(Message {
id: message.id,
role: message.role,
timestamp_ms: message.timestamp_ms,
blocks,
})
}
fn validate_replacement(
message: &MessageView<'_>,
replacement: &ReplacementView<'_>,
) -> Result<()> {
let valid = match *replacement {
ReplacementView::Text(_) => message.blocks().all(|block| matches!(block, BlockView::Text(_) | BlockView::Thinking(_))),
ReplacementView::AssistantText(_) => message.role == Role::Assistant,
ReplacementView::ToolResultOutput { call_id, .. } => message.role == Role::Tool && message.blocks().filter(|block| matches!(block, BlockView::ToolResult { call_id: id, .. } if *id == call_id)).count() == 1,
};
if !valid {
return Err(invalid(
"replacement must preserve target role and tool-call/result schema",
));
}
Ok(())
}