//! 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>)> { 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 { 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>) -> 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> { 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 { 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) -> 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>> for AppliedEdit<'a> { fn from(text: Option>) -> 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> { 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 { 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> { 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> { 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 { 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 { 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(()) }