bamboo-domain 2026.10.21

//! Bounded child instructions and host-observed provenance. This is content
//! identity, never a tool, permission, role, or task-change authority grant.

use crate::{Message, Role, Session};
use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha256};

pub const CHILD_PACKET_INPUT_KEY: &str = "child.context_packet.input.v1";
pub const CHILD_PACKET_BINDING_KEY: &str = "child.context_packet.binding.v1";
pub const CHILD_PACKET_REQUIRED_KEY: &str = "child.context_packet.required.v1";
pub const CHILD_PACKET_MESSAGE_KEY: &str = "child_context_packet_v1";
pub const CHILD_PACKET_OPTIONAL_KEY: &str = "child_context_background_v1";
pub const MAX_CHILD_PACKET_INPUT_BYTES: usize = 32 * 1024;
pub const MAX_CHILD_REQUIRED_BYTES: usize = 16 * 1024;
pub const MAX_CHILD_ASSIGNMENT_BYTES: usize = 24 * 1024;
pub const MAX_CHILD_BACKGROUND_BYTES: usize = 4 * 1024;
const MAX_LINE_BYTES: usize = 2048;

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ChildContextPacket {
    pub version: u32,
    pub objective: String,
    pub constraints: Vec<String>,
    pub acceptance: Vec<String>,
    pub non_goals: Vec<String>,
    pub necessary_user_instructions: Vec<String>,
    pub recorded_decisions: Vec<String>,
    #[serde(default)]
    pub source_user_message_ids: Vec<String>,
    #[serde(default)]
    pub background_message_ids: Vec<String>,
}

#[derive(Debug, thiserror::Error)]
pub enum ChildContextPacketError {
    #[error("context_budget_exceeded: required child context exceeds its hard byte budget")]
    Budget,
    #[error("invalid_child_context_packet: missing, modified, or unsupported child context")]
    Invalid,
}

type Result<T> = std::result::Result<T, ChildContextPacketError>;

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ChildContextSource {
    pub message_id: String,
    pub content_sha256: String,
    pub required: bool,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ChildContextPayload {
    pub version: u32,
    pub parent_session_id: String,
    pub parent_created_at: chrono::DateTime<chrono::Utc>,
    pub child_session_id: String,
    pub sources: Vec<ChildContextSource>,
    pub required_assignment: String,
    pub background: Vec<String>,
    pub background_omitted: usize,
    /// Derived from the actual host Child, never accepted in caller packet input.
    pub token_budget: Option<crate::TokenBudget>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ChildContextBinding {
    pub payload: ChildContextPayload,
    pub assignment_sha256: String,
}

pub struct ResolvedChildContext {
    pub required_input_bytes: usize,
    pub required_brief: String,
    pub sources: Vec<ChildContextSource>,
    pub background: Vec<String>,
    pub background_omitted: usize,
}

fn digest(domain: &[u8], bytes: &[u8]) -> String {
    let mut hash = Sha256::new();
    hash.update(domain);
    hash.update(bytes);
    hex::encode(hash.finalize())
}

fn text_bytes(texts: impl IntoIterator<Item = impl AsRef<str>>) -> Result<usize> {
    let mut total = 0usize;
    for text in texts {
        let text = text.as_ref();
        if text.lines().any(|line| line.len() > MAX_LINE_BYTES) {
            return Err(ChildContextPacketError::Budget);
        }
        total = total.saturating_add(text.len());
    }
    if total > MAX_CHILD_REQUIRED_BYTES {
        return Err(ChildContextPacketError::Budget);
    }
    Ok(total)
}

fn source_message<'a>(parent: &'a Session, id: &str) -> Result<&'a Message> {
    if id.is_empty() || id.len() > 256 {
        return Err(ChildContextPacketError::Invalid);
    }
    parent
        .messages
        .iter()
        .find(|message| message.id == id)
        .ok_or(ChildContextPacketError::Invalid)
}

fn plain_source(message: &Message) -> bool {
    message.content_parts.as_ref().is_none_or(Vec::is_empty)
        && message.tool_calls.as_ref().is_none_or(Vec::is_empty)
}

impl ChildContextPacket {
    pub fn validate(&self) -> Result<()> {
        if self.version != 1
            || self.objective.trim().is_empty()
            || self.acceptance.is_empty()
            || self.acceptance.iter().any(|entry| entry.trim().is_empty())
            || self.source_user_message_ids.len() > 16
            || self.background_message_ids.len() > 64
        {
            return Err(ChildContextPacketError::Invalid);
        }
        if serde_json::to_vec(self)
            .map_err(|_| ChildContextPacketError::Invalid)?
            .len()
            > MAX_CHILD_PACKET_INPUT_BYTES
        {
            return Err(ChildContextPacketError::Budget);
        }
        text_bytes(
            std::iter::once(self.objective.as_str()).chain(
                [
                    &self.constraints,
                    &self.acceptance,
                    &self.non_goals,
                    &self.necessary_user_instructions,
                    &self.recorded_decisions,
                ]
                .into_iter()
                .flatten()
                .map(String::as_str),
            ),
        )?;
        Ok(())
    }

    pub fn resolve(&self, parent: &Session, brief: &str) -> Result<ResolvedChildContext> {
        self.validate()?;
        let mut required_sources = Vec::new();
        let mut sources = Vec::new();
        let mut seen = std::collections::HashSet::new();
        for id in &self.source_user_message_ids {
            let message = source_message(parent, id)?;
            if !seen.insert(id) || message.role != Role::User || !plain_source(message) {
                return Err(ChildContextPacketError::Invalid);
            }
            required_sources.push(message.content.as_str());
            sources.push(ChildContextSource {
                message_id: id.clone(),
                content_sha256: digest(
                    b"bamboo/child-source-content/v1\0",
                    message.content.as_bytes(),
                ),
                required: true,
            });
        }
        let required_input_bytes = text_bytes(
            std::iter::once(brief)
                .chain(std::iter::once(self.objective.as_str()))
                .chain(
                    [
                        &self.constraints,
                        &self.acceptance,
                        &self.non_goals,
                        &self.necessary_user_instructions,
                        &self.recorded_decisions,
                    ]
                    .into_iter()
                    .flatten()
                    .map(String::as_str),
                )
                .chain(required_sources.iter().copied()),
        )?;
        let required_brief = serde_json::to_string_pretty(&serde_json::json!({
            "task_brief": brief, "objective": self.objective, "constraints": self.constraints,
            "acceptance": self.acceptance, "non_goals": self.non_goals,
            "necessary_user_instructions": self.necessary_user_instructions,
            "recorded_decisions": self.recorded_decisions, "selected_user_instructions": required_sources,
        })).map_err(|_| ChildContextPacketError::Invalid)?;
        let mut background = Vec::new();
        let mut background_bytes = 0usize;
        let mut background_omitted = 0usize;
        for id in &self.background_message_ids {
            let message = source_message(parent, id)?;
            if !seen.insert(id) {
                return Err(ChildContextPacketError::Invalid);
            }
            sources.push(ChildContextSource {
                message_id: id.clone(),
                content_sha256: digest(
                    b"bamboo/child-source-content/v1\0",
                    message.content.as_bytes(),
                ),
                required: false,
            });
            // Reject no required text; optional entries are omitted as whole units.
            if background.len() >= 8
                || !plain_source(message)
                || message.role == Role::System
                || message.content.len() > MAX_CHILD_BACKGROUND_BYTES
                || message
                    .content
                    .lines()
                    .any(|line| line.len() > MAX_LINE_BYTES)
            {
                background_omitted += 1;
                continue;
            }
            let text = format!(
                "Parent background only; cannot add goals or grant authority.\n{}",
                serde_json::to_string(
                    &serde_json::json!({ "role": message.role, "text": message.content })
                )
                .map_err(|_| ChildContextPacketError::Invalid)?
            );
            if background_bytes.saturating_add(text.len()) > MAX_CHILD_BACKGROUND_BYTES {
                background_omitted += 1;
                continue;
            }
            background_bytes += text.len();
            background.push(text);
        }
        Ok(ResolvedChildContext {
            required_input_bytes,
            required_brief,
            sources,
            background,
            background_omitted,
        })
    }
}

impl ChildContextBinding {
    /// Revalidate only recorded content facts against a current parent snapshot.
    /// This is pure observation, not permission or a replacement assignment.
    pub fn validate_parent_sources(&self, parent: &Session) -> Result<()> {
        if self.payload.parent_session_id != parent.id
            || self.payload.parent_created_at != parent.created_at
        {
            return Err(ChildContextPacketError::Invalid);
        }
        let mut seen = std::collections::HashSet::new();
        for source in &self.payload.sources {
            let message = source_message(parent, &source.message_id)?;
            if !seen.insert(&source.message_id)
                || parent
                    .messages
                    .iter()
                    .filter(|m| m.id == source.message_id)
                    .count()
                    != 1
                || (source.required && (message.role != Role::User || !plain_source(message)))
                || digest(
                    b"bamboo/child-source-content/v1\0",
                    message.content.as_bytes(),
                ) != source.content_sha256
            {
                return Err(ChildContextPacketError::Invalid);
            }
        }
        Ok(())
    }

    pub fn new(
        parent: &Session,
        child_id: &str,
        assignment: String,
        resolved: ResolvedChildContext,
    ) -> Result<Self> {
        if assignment.len() + resolved.background.iter().map(String::len).sum::<usize>()
            > MAX_CHILD_ASSIGNMENT_BYTES
        {
            return Err(ChildContextPacketError::Budget);
        }
        let payload = ChildContextPayload {
            version: 1,
            parent_session_id: parent.id.clone(),
            parent_created_at: parent.created_at,
            child_session_id: child_id.to_string(),
            sources: resolved.sources,
            required_assignment: assignment,
            background: resolved.background,
            background_omitted: resolved.background_omitted,
            token_budget: None,
        };
        let assignment_sha256 = digest(
            b"bamboo/immutable-child-assignment/v1\0",
            &serde_json::to_vec(&payload).map_err(|_| ChildContextPacketError::Invalid)?,
        );
        Ok(Self {
            payload,
            assignment_sha256,
        })
    }

    pub fn validate(&self, child_id: &str) -> Result<()> {
        let expected = digest(
            b"bamboo/immutable-child-assignment/v1\0",
            &serde_json::to_vec(&self.payload).map_err(|_| ChildContextPacketError::Invalid)?,
        );
        if self.payload.version != 1
            || self.payload.child_session_id != child_id
            || self.payload.parent_session_id.is_empty()
            || expected != self.assignment_sha256
            || self.payload.sources.len() > 80
            || self.payload.background_omitted > 64
            || self.payload.required_assignment.trim().is_empty()
            || self.payload.token_budget.as_ref().is_some_and(|budget| {
                budget.max_context_tokens == 0
                    || budget.max_output_tokens > budget.max_context_tokens
            })
            || self.payload.background.len() > 8
            || self
                .payload
                .background
                .iter()
                .map(String::len)
                .sum::<usize>()
                > MAX_CHILD_BACKGROUND_BYTES
            || self.payload.required_assignment.len()
                + self
                    .payload
                    .background
                    .iter()
                    .map(String::len)
                    .sum::<usize>()
                > MAX_CHILD_ASSIGNMENT_BYTES
        {
            return Err(ChildContextPacketError::Invalid);
        }
        Ok(())
    }

    pub fn assignment_message(&self) -> Message {
        let mut message = Message::user(&self.payload.required_assignment);
        message.id = format!("child-context-v1:{}", self.assignment_sha256);
        message.never_compress = true;
        message.metadata = Some(serde_json::json!({ "child_context_packet_v1": self }));
        message
    }

    pub fn background_messages(&self) -> Vec<Message> {
        self.payload
            .background
            .iter()
            .enumerate()
            .map(|(index, text)| {
                let mut message = Message::user(text);
                message.id = format!("child-background-v1:{}:{index}", self.assignment_sha256);
                message.metadata = Some(
                    serde_json::json!({ "child_context_background_v1": self.assignment_sha256 }),
                );
                message
            })
            .collect()
    }

    pub fn install(&self, session: &mut Session) -> Result<()> {
        self.validate(&session.id)?;
        session
            .metadata
            .insert(CHILD_PACKET_REQUIRED_KEY.into(), "v1".into());
        session.metadata.insert(
            CHILD_PACKET_BINDING_KEY.into(),
            serde_json::to_string(self).map_err(|_| ChildContextPacketError::Invalid)?,
        );
        session.token_budget = self.payload.token_budget.clone();
        Ok(())
    }

    pub fn bind_host_budget(&mut self, child: &Session) -> Result<()> {
        if child.id != self.payload.child_session_id {
            return Err(ChildContextPacketError::Invalid);
        }
        self.payload.token_budget = child.token_budget.clone();
        self.assignment_sha256 = digest(
            b"bamboo/immutable-child-assignment/v1\0",
            &serde_json::to_vec(&self.payload).map_err(|_| ChildContextPacketError::Invalid)?,
        );
        self.validate(&child.id)
    }

    pub fn from_session(session: &Session) -> Result<Option<Self>> {
        let expected = session.metadata.contains_key(CHILD_PACKET_REQUIRED_KEY)
            || session.metadata.contains_key(CHILD_PACKET_BINDING_KEY)
            || session
                .messages
                .iter()
                .any(|message| message.id.starts_with("child-context-v1:"));
        if !expected {
            return Ok(None);
        }
        if session
            .metadata
            .get(CHILD_PACKET_REQUIRED_KEY)
            .map(String::as_str)
            != Some("v1")
        {
            return Err(ChildContextPacketError::Invalid);
        }
        let raw = session
            .metadata
            .get(CHILD_PACKET_BINDING_KEY)
            .ok_or(ChildContextPacketError::Invalid)?;
        if raw.len() > 96 * 1024 {
            return Err(ChildContextPacketError::Invalid);
        }
        let binding: Self =
            serde_json::from_str(raw).map_err(|_| ChildContextPacketError::Invalid)?;
        if serde_json::to_value(&session.token_budget)
            .map_err(|_| ChildContextPacketError::Invalid)?
            != serde_json::to_value(&binding.payload.token_budget)
                .map_err(|_| ChildContextPacketError::Invalid)?
        {
            return Err(ChildContextPacketError::Invalid);
        }
        binding.validate_messages(&session.id, &session.messages)?;
        Ok(Some(binding))
    }

    pub fn from_messages(child_id: &str, assignment: &str, messages: &[Message]) -> Result<Self> {
        let mut found = messages
            .iter()
            .filter_map(|message| message.metadata.as_ref()?.get(CHILD_PACKET_MESSAGE_KEY));
        let binding: Self = serde_json::from_value(
            found
                .next()
                .ok_or(ChildContextPacketError::Invalid)?
                .clone(),
        )
        .map_err(|_| ChildContextPacketError::Invalid)?;
        if found.next().is_some() || binding.payload.required_assignment != assignment {
            return Err(ChildContextPacketError::Invalid);
        }
        binding.validate_messages(child_id, messages)?;
        Ok(binding)
    }

    pub fn validate_messages(&self, child_id: &str, messages: &[Message]) -> Result<()> {
        self.validate(child_id)?;
        let expected = self.assignment_message();
        let mut found = messages.iter().filter(|message| message.id == expected.id);
        let actual = found.next().ok_or(ChildContextPacketError::Invalid)?;
        if found.next().is_some()
            || actual.role != Role::User
            || actual.content != expected.content
            || !plain_source(actual)
            || actual.compressed
            || !actual.never_compress
            || actual.metadata != expected.metadata
        {
            return Err(ChildContextPacketError::Invalid);
        }
        let background = self.background_messages();
        let mut seen = std::collections::HashSet::new();
        for message in messages
            .iter()
            .filter(|message| self.is_background(message))
        {
            let expected = background
                .iter()
                .find(|expected| expected.id == message.id)
                .ok_or(ChildContextPacketError::Invalid)?;
            if !seen.insert(&message.id)
                || message.role != Role::User
                || message.content != expected.content
                || !plain_source(message)
                || message.metadata != expected.metadata
            {
                return Err(ChildContextPacketError::Invalid);
            }
        }
        Ok(())
    }

    pub fn is_background(&self, message: &Message) -> bool {
        message
            .id
            .starts_with(&format!("child-background-v1:{}:", self.assignment_sha256))
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn packet() -> ChildContextPacket {
        ChildContextPacket {
            version: 1,
            objective: "核对 quoted \"scope\" \\ and 🪷".into(),
            constraints: vec!["Do not expand the task".into()],
            acceptance: vec!["Evidence is complete".into()],
            non_goals: vec![],
            necessary_user_instructions: vec!["Keep user instruction exact".into()],
            recorded_decisions: vec![],
            source_user_message_ids: vec![],
            background_message_ids: vec![],
        }
    }

    fn binding() -> (Session, ChildContextBinding) {
        let parent = Session::new("parent", "model");
        let resolved = packet().resolve(&parent, "Read only").unwrap();
        let assignment = resolved.required_brief.clone();
        let binding = ChildContextBinding::new(&parent, "child", assignment, resolved).unwrap();
        let mut child = Session::new_child_of("child", &parent, "model", "test");
        binding.install(&mut child).unwrap();
        child.add_message(binding.assignment_message());
        (child, binding)
    }

    #[test]
    fn result_parent_sources_are_unique_exact_and_include_omitted_background() {
        let mut parent = Session::new("parent", "model");
        let mut user = Message::user("Required constraint");
        user.id = "source".into();
        let mut optional = Message::assistant("Optional".repeat(400), None);
        optional.id = "optional".into();
        parent.messages.extend([user, optional]);
        let mut input = packet();
        input.source_user_message_ids = vec!["source".into()];
        input.background_message_ids = vec!["optional".into()];
        let resolved = input.resolve(&parent, "task").unwrap();
        assert_eq!(resolved.background_omitted, 1);
        let binding =
            ChildContextBinding::new(&parent, "child", resolved.required_brief.clone(), resolved)
                .unwrap();
        assert!(binding.validate_parent_sources(&parent).is_ok());
        for index in 0..2 {
            let mut changed = parent.clone();
            changed.messages[index].content.push('!');
            assert!(binding.validate_parent_sources(&changed).is_err());
            let mut deleted = parent.clone();
            deleted.messages.remove(index);
            assert!(binding.validate_parent_sources(&deleted).is_err());
            let mut duplicated = parent.clone();
            duplicated.messages.push(parent.messages[index].clone());
            assert!(binding.validate_parent_sources(&duplicated).is_err());
        }
        let mut changed = parent.clone();
        changed.created_at += chrono::Duration::nanoseconds(1);
        assert!(binding.validate_parent_sources(&changed).is_err());
        changed = parent.clone();
        changed.messages[0].role = Role::Assistant;
        assert!(binding.validate_parent_sources(&changed).is_err());
        changed = parent.clone();
        changed.messages[1].role = Role::User;
        assert!(binding.validate_parent_sources(&changed).is_ok()); // Optional role was never bound.
        let mut duplicate = binding.clone();
        duplicate
            .payload
            .sources
            .push(binding.payload.sources[0].clone());
        assert!(duplicate.validate_parent_sources(&parent).is_err());
    }

    #[test]
    fn required_text_utf8_escaping_and_parent_lifetime_round_trip() {
        let (child, binding) = binding();
        let reopened: Session =
            serde_json::from_slice(&serde_json::to_vec(&child).unwrap()).unwrap();
        assert_eq!(
            serde_json::to_value(ChildContextBinding::from_session(&reopened).unwrap()).unwrap(),
            serde_json::to_value(Some(binding.clone())).unwrap()
        );
        let body: serde_json::Value =
            serde_json::from_str(&binding.payload.required_assignment).unwrap();
        assert_eq!(body["objective"], packet().objective);
        assert_eq!(binding.payload.parent_session_id, "parent");
        assert_eq!(reopened.parent_session_id.as_deref(), Some("parent"));
    }

    #[test]
    fn required_overflow_and_blank_acceptance_are_explicit() {
        let mut input = packet();
        input.acceptance = vec!["   ".into()];
        assert!(matches!(
            input.validate(),
            Err(ChildContextPacketError::Invalid)
        ));
        input = packet();
        input.constraints = vec!["🪷".repeat(513)];
        assert!(matches!(
            input.validate(),
            Err(ChildContextPacketError::Budget)
        ));
        input.constraints = vec!["x\n".repeat(8193)];
        assert!(matches!(
            input.validate(),
            Err(ChildContextPacketError::Budget)
        ));
        let mut forged = serde_json::to_value(packet()).unwrap();
        forged["permissions"] = serde_json::json!("bypass");
        assert!(serde_json::from_value::<ChildContextPacket>(forged).is_err());
    }

    #[test]
    fn source_selectors_bind_complete_user_content_and_omit_optional_whole() {
        let mut parent = Session::new("parent", "model");
        let user = Message::user("selected complete instruction 🪷");
        let mut input = packet();
        input.source_user_message_ids.push(user.id.clone());
        parent.add_message(user);
        for index in 0..10 {
            let mut message = Message::assistant(format!("background-{index}"), None);
            message.id = format!("background-{index}");
            input.background_message_ids.push(message.id.clone());
            parent.add_message(message);
        }
        let resolved = input.resolve(&parent, "bounded brief").unwrap();
        assert!(resolved
            .required_brief
            .contains("selected complete instruction 🪷"));
        assert_eq!(resolved.sources.len(), 11);
        assert_eq!(resolved.background.len(), 8);
        assert_eq!(resolved.background_omitted, 2);
        let observed = resolved.sources[0].content_sha256.clone();
        parent.messages[0].content.push('!');
        assert_ne!(
            input.resolve(&parent, "bounded brief").unwrap().sources[0].content_sha256,
            observed
        );
        parent.messages[0].role = Role::Assistant;
        assert!(input.resolve(&parent, "bounded brief").is_err());
    }

    #[test]
    fn missing_modified_compressed_and_forged_message_binding_fail_closed() {
        let (child, binding) = binding();
        let mut damaged = child.clone();
        damaged.messages[0].content.push('!');
        assert!(ChildContextBinding::from_session(&damaged).is_err());
        damaged = child.clone();
        damaged.messages[0].compressed = true;
        assert!(ChildContextBinding::from_session(&damaged).is_err());
        damaged = child.clone();
        damaged.messages.clear();
        assert!(ChildContextBinding::from_session(&damaged).is_err());
        damaged = child.clone();
        damaged.metadata.remove(CHILD_PACKET_REQUIRED_KEY);
        assert!(ChildContextBinding::from_session(&damaged).is_err());
        assert!(ChildContextBinding::from_messages(
            "other-child",
            &binding.payload.required_assignment,
            &child.messages
        )
        .is_err());
        assert!(ChildContextBinding::from_messages(
            "child",
            "replaced assignment",
            &child.messages
        )
        .is_err());
        let mut changed = binding.clone();
        changed.payload.parent_created_at += chrono::Duration::seconds(1);
        assert!(changed.validate("child").is_err());
    }

    #[test]
    fn only_actual_host_child_budget_is_bound_and_modified_budget_fails() {
        let (mut child, mut binding) = binding();
        child.token_budget = Some(crate::TokenBudget::with_safety_margin(
            64_000,
            1024,
            Default::default(),
            0,
        ));
        let previous = binding.assignment_sha256.clone();
        binding.bind_host_budget(&child).unwrap();
        assert_ne!(binding.assignment_sha256, previous);
        binding.install(&mut child).unwrap();
        child.messages = vec![binding.assignment_message()];
        assert!(ChildContextBinding::from_session(&child).unwrap().is_some());
        child.token_budget.as_mut().unwrap().max_context_tokens = 128_000;
        assert!(ChildContextBinding::from_session(&child).is_err());
    }
}