Luigit
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(())
}