cellstate_pcp/

lib.rs

// Copyright 2024-2026 CELLSTATE Contributors
// SPDX-License-Identifier: Apache-2.0

//! CELLSTATE PCP - Persistent Context Protocol
//!
//! Provides validation, checkpointing, and harm reduction for AI agent memory.
//! Implements the PCP protocol for context integrity, contradiction detection,
//! and recovery mechanisms.

use cellstate_core::{
    AbstractionLevel, AgentId, Artifact, ArtifactId, CellstateConfig, CellstateError,
    CellstateResult, ConflictResolution, EntityIdType, NoteId, RawContent, Scope, ScopeId,
    SummarizationPolicy, SummarizationPolicyId, SummarizationTrigger, Timestamp, TrajectoryId,
    ValidationError,
};
use chrono::Utc;
use regex::Regex;
use serde::{Deserialize, Serialize};
use std::collections::HashMap;
use std::sync::OnceLock;
use uuid::Uuid;

// ============================================================================
// MEMORY COMMIT (Task 8.1)
// ============================================================================

/// Memory commit - versioned record of an interaction.
/// Enables: "Last time we decided X because Y"
/// Every interaction creates a versioned commit for recall, rollback, audit, and rehydration.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct MemoryCommit {
    /// Unique identifier for this commit
    pub commit_id: Uuid,
    /// Trajectory this commit belongs to
    pub trajectory_id: TrajectoryId,
    /// Scope this commit belongs to
    pub scope_id: ScopeId,
    /// Agent that created this commit (if multi-agent)
    pub agent_id: Option<AgentId>,

    /// The user's query/input
    pub query: String,
    /// The system's response
    pub response: String,

    /// Mode of interaction (e.g., "standard", "deep_work", "super_think")
    pub mode: String,
    /// Reasoning trace (if available)
    pub reasoning_trace: Option<serde_json::Value>,

    /// Whether RAG contributed to this response
    pub rag_contributed: bool,
    /// Artifacts referenced in this interaction
    pub artifacts_referenced: Vec<ArtifactId>,
    /// Notes referenced in this interaction
    pub notes_referenced: Vec<NoteId>,

    /// Tools invoked during this interaction
    pub tools_invoked: Vec<String>,

    /// Input token count
    pub tokens_input: i64,
    /// Output token count
    pub tokens_output: i64,
    /// Estimated cost (if available)
    pub estimated_cost: Option<f64>,

    /// When this commit was created
    pub created_at: Timestamp,
}

impl MemoryCommit {
    /// Create a new memory commit.
    #[tracing::instrument(skip_all)]
    pub fn new(
        trajectory_id: TrajectoryId,
        scope_id: ScopeId,
        query: String,
        response: String,
        mode: String,
    ) -> Self {
        Self {
            commit_id: Uuid::now_v7(),
            trajectory_id,
            scope_id,
            agent_id: None,
            query,
            response,
            mode,
            reasoning_trace: None,
            rag_contributed: false,
            artifacts_referenced: Vec::new(),
            notes_referenced: Vec::new(),
            tools_invoked: Vec::new(),
            tokens_input: 0,
            tokens_output: 0,
            estimated_cost: None,
            created_at: Utc::now(),
        }
    }

    /// Set the agent ID.
    #[tracing::instrument(skip_all)]
    pub fn with_agent_id(mut self, agent_id: AgentId) -> Self {
        self.agent_id = Some(agent_id);
        self
    }

    /// Set the reasoning trace.
    #[tracing::instrument(skip_all)]
    pub fn with_reasoning_trace(mut self, trace: serde_json::Value) -> Self {
        self.reasoning_trace = Some(trace);
        self
    }

    /// Set RAG contribution flag.
    #[tracing::instrument(skip_all)]
    pub fn with_rag_contributed(mut self, contributed: bool) -> Self {
        self.rag_contributed = contributed;
        self
    }

    /// Set referenced artifacts.
    #[tracing::instrument(skip_all)]
    pub fn with_artifacts_referenced(mut self, artifacts: Vec<ArtifactId>) -> Self {
        self.artifacts_referenced = artifacts;
        self
    }

    /// Set referenced notes.
    #[tracing::instrument(skip_all)]
    pub fn with_notes_referenced(mut self, notes: Vec<NoteId>) -> Self {
        self.notes_referenced = notes;
        self
    }

    /// Set tools invoked.
    #[tracing::instrument(skip_all)]
    pub fn with_tools_invoked(mut self, tools: Vec<String>) -> Self {
        self.tools_invoked = tools;
        self
    }

    /// Set token counts.
    #[tracing::instrument(skip_all)]
    pub fn with_tokens(mut self, input: i64, output: i64) -> Self {
        self.tokens_input = input;
        self.tokens_output = output;
        self
    }

    /// Set estimated cost.
    #[tracing::instrument(skip_all)]
    pub fn with_estimated_cost(mut self, cost: f64) -> Self {
        self.estimated_cost = Some(cost);
        self
    }

    /// Get total tokens (input + output).
    #[tracing::instrument(skip_all)]
    pub fn total_tokens(&self) -> i64 {
        self.tokens_input + self.tokens_output
    }
}

// ============================================================================
// RECALL SERVICE (Task 8.2)
// ============================================================================

/// Recall of a decision from past interactions.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct DecisionRecall {
    /// Commit ID this decision came from
    pub commit_id: Uuid,
    /// Original query
    pub query: String,
    /// Extracted decision summary
    pub decision_summary: String,
    /// Mode of the interaction
    pub mode: String,
    /// When the decision was made
    pub created_at: Timestamp,
}

/// History of a scope's interactions.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ScopeHistory {
    /// Scope ID
    pub scope_id: ScopeId,
    /// Number of interactions in this scope
    pub interaction_count: i32,
    /// Total tokens used in this scope
    pub total_tokens: i64,
    /// Total cost for this scope
    pub total_cost: f64,
    /// All commits in this scope
    pub commits: Vec<MemoryCommit>,
}

/// Memory statistics for analytics.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct MemoryStats {
    /// Total number of interactions
    pub total_interactions: i64,
    /// Total tokens used
    pub total_tokens: i64,
    /// Total cost
    pub total_cost: f64,
    /// Number of unique scopes
    pub unique_scopes: i64,
    /// Interactions by mode
    pub by_mode: HashMap<String, i64>,
    /// Average tokens per interaction
    pub avg_tokens_per_interaction: i64,
}

impl Default for MemoryStats {
    fn default() -> Self {
        Self {
            total_interactions: 0,
            total_tokens: 0,
            total_cost: 0.0,
            unique_scopes: 0,
            by_mode: HashMap::new(),
            avg_tokens_per_interaction: 0,
        }
    }
}

/// Service for recalling past interactions and decisions.
/// Provides query methods for memory commits.
#[derive(Debug, Clone)]
pub struct RecallService {
    config: CellstateConfig,
    /// In-memory storage for commits (in production, this would be backed by storage)
    commits: Vec<MemoryCommit>,
}

impl RecallService {
    /// Create a new recall service with the given configuration.
    #[tracing::instrument(skip_all)]
    pub fn new(config: CellstateConfig) -> CellstateResult<Self> {
        config.validate()?;
        Ok(Self {
            config,
            commits: Vec::new(),
        })
    }

    /// Get the configuration.
    #[tracing::instrument(skip_all)]
    pub fn config(&self) -> &CellstateConfig {
        &self.config
    }

    /// Add a commit to the service.
    #[tracing::instrument(skip_all)]
    pub fn add_commit(&mut self, commit: MemoryCommit) {
        self.commits.push(commit);
    }

    /// Recall previous interactions for context.
    /// "Last time we decided X because Y"
    ///
    /// # Arguments
    /// * `trajectory_id` - Filter by trajectory (optional)
    /// * `scope_id` - Filter by scope (optional)
    /// * `limit` - Maximum number of commits to return
    ///
    /// # Returns
    /// Vector of memory commits matching the criteria
    #[tracing::instrument(skip_all)]
    pub fn recall_previous(
        &self,
        trajectory_id: Option<TrajectoryId>,
        scope_id: Option<ScopeId>,
        limit: i32,
    ) -> CellstateResult<Vec<MemoryCommit>> {
        let mut results: Vec<MemoryCommit> = self
            .commits
            .iter()
            .filter(|c| {
                let traj_match = trajectory_id.is_none_or(|t| c.trajectory_id == t);
                let scope_match = scope_id.is_none_or(|s| c.scope_id == s);
                traj_match && scope_match
            })
            .cloned()
            .collect();

        // Sort by created_at descending (most recent first)
        results.sort_by_key(|commit| std::cmp::Reverse(commit.created_at));

        // Apply limit
        results.truncate(limit as usize);

        Ok(results)
    }

    /// Search interactions by content.
    ///
    /// # Arguments
    /// * `search_text` - Text to search for in query or response
    /// * `limit` - Maximum number of commits to return
    ///
    /// # Returns
    /// Vector of memory commits containing the search text
    #[tracing::instrument(skip_all)]
    pub fn search_interactions(
        &self,
        search_text: &str,
        limit: i32,
    ) -> CellstateResult<Vec<MemoryCommit>> {
        let search_lower = search_text.to_lowercase();

        let mut results: Vec<MemoryCommit> = self
            .commits
            .iter()
            .filter(|c| {
                c.query.to_lowercase().contains(&search_lower)
                    || c.response.to_lowercase().contains(&search_lower)
            })
            .cloned()
            .collect();

        // Sort by created_at descending
        results.sort_by_key(|commit| std::cmp::Reverse(commit.created_at));

        // Apply limit
        results.truncate(limit as usize);

        Ok(results)
    }

    /// Recall decisions made in past interactions.
    /// Filters for decision-support interactions.
    ///
    /// # Arguments
    /// * `topic` - Filter by topic in query (optional)
    /// * `limit` - Maximum number of decisions to return
    ///
    /// # Returns
    /// Vector of decision recalls
    #[tracing::instrument(skip_all)]
    pub fn recall_decisions(
        &self,
        topic: Option<&str>,
        limit: i32,
    ) -> CellstateResult<Vec<DecisionRecall>> {
        let mut results: Vec<DecisionRecall> = self
            .commits
            .iter()
            .filter(|c| {
                // Filter by mode (deep_work or super_think) OR response contains decision keywords
                let mode_match = c.mode == "deep_work" || c.mode == "super_think";
                let has_decision = contains_decision_keywords(&c.response);

                // Filter by topic if provided
                let topic_match =
                    topic.is_none_or(|t| c.query.to_lowercase().contains(&t.to_lowercase()));

                (mode_match || has_decision) && topic_match
            })
            .map(|c| DecisionRecall {
                commit_id: c.commit_id,
                query: c.query.clone(),
                decision_summary: extract_decision(&c.response),
                mode: c.mode.clone(),
                created_at: c.created_at,
            })
            .collect();

        // Sort by created_at descending
        results.sort_by_key(|commit| std::cmp::Reverse(commit.created_at));

        // Apply limit
        results.truncate(limit as usize);

        Ok(results)
    }

    /// Get session/scope history.
    ///
    /// # Arguments
    /// * `scope_id` - The scope to get history for
    ///
    /// # Returns
    /// Scope history with all commits
    #[tracing::instrument(skip_all)]
    pub fn get_scope_history(&self, scope_id: ScopeId) -> CellstateResult<ScopeHistory> {
        let commits: Vec<MemoryCommit> = self
            .commits
            .iter()
            .filter(|c| c.scope_id == scope_id)
            .cloned()
            .collect();

        let total_tokens: i64 = commits.iter().map(|c| c.total_tokens()).sum();
        let total_cost: f64 = commits.iter().filter_map(|c| c.estimated_cost).sum();

        Ok(ScopeHistory {
            scope_id,
            interaction_count: commits.len() as i32,
            total_tokens,
            total_cost,
            commits,
        })
    }

    /// Get memory stats for analytics.
    ///
    /// # Arguments
    /// * `trajectory_id` - Filter by trajectory (optional)
    ///
    /// # Returns
    /// Memory statistics
    #[tracing::instrument(skip_all)]
    pub fn get_memory_stats(
        &self,
        trajectory_id: Option<TrajectoryId>,
    ) -> CellstateResult<MemoryStats> {
        let filtered: Vec<&MemoryCommit> = self
            .commits
            .iter()
            .filter(|c| trajectory_id.is_none_or(|t| c.trajectory_id == t))
            .collect();

        if filtered.is_empty() {
            return Ok(MemoryStats::default());
        }

        let total_interactions = filtered.len() as i64;
        let total_tokens: i64 = filtered.iter().map(|c| c.total_tokens()).sum();
        let total_cost: f64 = filtered.iter().filter_map(|c| c.estimated_cost).sum();

        // Count unique scopes
        let mut unique_scope_ids: Vec<ScopeId> = filtered.iter().map(|c| c.scope_id).collect();
        unique_scope_ids.sort_by_key(|id| id.as_uuid());
        unique_scope_ids.dedup();
        let unique_scopes = unique_scope_ids.len() as i64;

        // Count by mode
        let mut by_mode: HashMap<String, i64> = HashMap::new();
        for commit in &filtered {
            *by_mode.entry(commit.mode.clone()).or_insert(0) += 1;
        }

        let avg_tokens_per_interaction = if total_interactions > 0 {
            total_tokens / total_interactions
        } else {
            0
        };

        Ok(MemoryStats {
            total_interactions,
            total_tokens,
            total_cost,
            unique_scopes,
            by_mode,
            avg_tokens_per_interaction,
        })
    }
}

// ============================================================================
// DECISION EXTRACTION (Task 8.3)
// ============================================================================

/// Decision keywords to look for in responses.
const DECISION_KEYWORDS: &[&str] = &[
    "recommend",
    "should",
    "decision",
    "conclude",
    "suggest",
    "advise",
    "propose",
    "determine",
    "choose",
    "select",
];

/// Check if a response contains decision keywords.
fn contains_decision_keywords(response: &str) -> bool {
    let response_lower = response.to_lowercase();
    DECISION_KEYWORDS
        .iter()
        .any(|kw| response_lower.contains(kw))
}

/// Extract decision summary from response.
/// Looks for recommendation patterns.
///
/// # Arguments
/// * `response` - The response text to extract from
///
/// # Returns
/// Extracted decision summary
#[tracing::instrument(skip_all)]
pub fn extract_decision(response: &str) -> String {
    // Patterns to look for (case-insensitive)
    let patterns = [
        r"(?i)I recommend[^\n.]*[.]",
        r"(?i)I suggest[^\n.]*[.]",
        r"(?i)you should[^\n.]*[.]",
        r"(?i)we should[^\n.]*[.]",
        r"(?i)the decision[^\n.]*[.]",
        r"(?i)I conclude[^\n.]*[.]",
        r"(?i)my recommendation[^\n.]*[.]",
        r"(?i)I advise[^\n.]*[.]",
        r"(?i)I propose[^\n.]*[.]",
        r"(?i)the best approach[^\n.]*[.]",
        r"(?i)the recommended[^\n.]*[.]",
    ];

    for pattern in patterns {
        if let Ok(re) = Regex::new(pattern) {
            if let Some(m) = re.find(response) {
                return m.as_str().trim().to_string();
            }
        }
    }

    // Fall back to first sentence
    extract_first_sentence(response)
}

/// Extract the first sentence from text (Unicode-safe).
fn extract_first_sentence(text: &str) -> String {
    // Find the first sentence-ending punctuation
    let end_chars = ['.', '!', '?'];
    let max_chars = 200;

    let mut char_count = 0;
    let mut last_valid_pos = 0;

    for (i, c) in text.char_indices() {
        if end_chars.contains(&c) {
            // Include the punctuation - use byte position after the char
            return text[..i + c.len_utf8()].trim().to_string();
        }

        char_count += 1;
        last_valid_pos = i + c.len_utf8();

        if char_count >= max_chars {
            break;
        }
    }

    // No sentence ending found within limit
    if char_count >= max_chars {
        format!("{}...", text[..last_valid_pos].trim())
    } else {
        text.to_string()
    }
}

// ============================================================================
// PCP CONFIG (Task 8.4)
// ============================================================================

/// Strategy for pruning context DAG.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum PruneStrategy {
    /// Remove oldest entries first
    OldestFirst,
    /// Remove lowest relevance entries first
    LowestRelevance,
    /// Hybrid approach combining age and relevance
    Hybrid,
}

/// Frequency for recovery checkpoints.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum RecoveryFrequency {
    /// Create checkpoint when scope closes
    OnScopeClose,
    /// Create checkpoint on every mutation
    OnMutation,
    /// Manual checkpoint creation only
    Manual,
}

/// Configuration for context DAG management.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ContextDagConfig {
    /// Maximum depth of the context DAG
    pub max_depth: i32,
    /// Strategy for pruning when limits are exceeded
    pub prune_strategy: PruneStrategy,
}

/// Configuration for recovery and checkpointing.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct RecoveryConfig {
    /// Whether recovery is enabled
    pub enabled: bool,
    /// How often to create checkpoints
    pub frequency: RecoveryFrequency,
    /// Maximum number of checkpoints to retain
    pub max_checkpoints: i32,
}

/// Configuration for dosage limits (harm reduction).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct DosageConfig {
    /// Maximum tokens per scope
    pub max_tokens_per_scope: i32,
    /// Maximum artifacts per scope
    pub max_artifacts_per_scope: i32,
    /// Maximum notes per trajectory
    pub max_notes_per_trajectory: i32,
}

/// Configuration for anti-sprawl measures.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct AntiSprawlConfig {
    /// Maximum trajectory depth (nested trajectories)
    pub max_trajectory_depth: i32,
    /// Maximum concurrent scopes
    pub max_concurrent_scopes: i32,
}

/// Configuration for grounding and fact-checking.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct GroundingConfig {
    /// Whether to require artifact backing for facts
    pub require_artifact_backing: bool,
    /// Threshold for contradiction detection (0.0-1.0)
    pub contradiction_threshold: f32,
    /// How to resolve conflicts
    pub conflict_resolution: ConflictResolution,
}

/// Configuration for artifact linting.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct LintingConfig {
    /// Maximum artifact content size in bytes
    pub max_artifact_size: usize,
    /// Minimum confidence threshold for artifacts (0.0-1.0)
    pub min_confidence_threshold: f32,
}

/// Configuration for staleness detection.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct StalenessConfig {
    /// Number of hours after which a scope is considered stale
    pub stale_hours: i64,
}

/// Master PCP configuration.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PCPConfig {
    /// Context DAG configuration
    pub context_dag: ContextDagConfig,
    /// Recovery configuration
    pub recovery: RecoveryConfig,
    /// Dosage limits configuration
    pub dosage: DosageConfig,
    /// Anti-sprawl configuration
    pub anti_sprawl: AntiSprawlConfig,
    /// Grounding configuration
    pub grounding: GroundingConfig,
    /// Linting configuration
    pub linting: LintingConfig,
    /// Staleness configuration
    pub staleness: StalenessConfig,
}

impl PCPConfig {
    /// Validate the PCP configuration.
    #[tracing::instrument(skip_all)]
    pub fn validate(&self) -> CellstateResult<()> {
        // Validate context DAG config
        if self.context_dag.max_depth <= 0 {
            return Err(CellstateError::Validation(ValidationError::InvalidValue {
                field: "context_dag.max_depth".to_string(),
                reason: "must be positive".to_string(),
            }));
        }

        // Validate recovery config
        if self.recovery.max_checkpoints < 0 {
            return Err(CellstateError::Validation(ValidationError::InvalidValue {
                field: "recovery.max_checkpoints".to_string(),
                reason: "must be non-negative".to_string(),
            }));
        }

        // Validate dosage config
        if self.dosage.max_tokens_per_scope <= 0 {
            return Err(CellstateError::Validation(ValidationError::InvalidValue {
                field: "dosage.max_tokens_per_scope".to_string(),
                reason: "must be positive".to_string(),
            }));
        }
        if self.dosage.max_artifacts_per_scope <= 0 {
            return Err(CellstateError::Validation(ValidationError::InvalidValue {
                field: "dosage.max_artifacts_per_scope".to_string(),
                reason: "must be positive".to_string(),
            }));
        }
        if self.dosage.max_notes_per_trajectory <= 0 {
            return Err(CellstateError::Validation(ValidationError::InvalidValue {
                field: "dosage.max_notes_per_trajectory".to_string(),
                reason: "must be positive".to_string(),
            }));
        }

        // Validate anti-sprawl config
        if self.anti_sprawl.max_trajectory_depth <= 0 {
            return Err(CellstateError::Validation(ValidationError::InvalidValue {
                field: "anti_sprawl.max_trajectory_depth".to_string(),
                reason: "must be positive".to_string(),
            }));
        }
        if self.anti_sprawl.max_concurrent_scopes <= 0 {
            return Err(CellstateError::Validation(ValidationError::InvalidValue {
                field: "anti_sprawl.max_concurrent_scopes".to_string(),
                reason: "must be positive".to_string(),
            }));
        }

        // Validate grounding config
        if self.grounding.contradiction_threshold < 0.0
            || self.grounding.contradiction_threshold > 1.0
        {
            return Err(CellstateError::Validation(ValidationError::InvalidValue {
                field: "grounding.contradiction_threshold".to_string(),
                reason: "must be between 0.0 and 1.0".to_string(),
            }));
        }

        // Validate linting config
        if self.linting.max_artifact_size == 0 {
            return Err(CellstateError::Validation(ValidationError::InvalidValue {
                field: "linting.max_artifact_size".to_string(),
                reason: "must be positive".to_string(),
            }));
        }
        if self.linting.min_confidence_threshold < 0.0
            || self.linting.min_confidence_threshold > 1.0
        {
            return Err(CellstateError::Validation(ValidationError::InvalidValue {
                field: "linting.min_confidence_threshold".to_string(),
                reason: "must be between 0.0 and 1.0".to_string(),
            }));
        }

        // Validate staleness config
        if self.staleness.stale_hours <= 0 {
            return Err(CellstateError::Validation(ValidationError::InvalidValue {
                field: "staleness.stale_hours".to_string(),
                reason: "must be positive".to_string(),
            }));
        }

        Ok(())
    }
}

// NOTE: Default impl intentionally removed per REQ-6 (PCP Configuration Without Defaults)
// All PCPConfig values must be explicitly provided by the user.
// This follows the CELLSTATE philosophy: "NOTHING HARD-CODED. This is a FRAMEWORK, not a product."

// ============================================================================
// VALIDATION TYPES (Task 8.5, 8.6)
// ============================================================================

/// Severity of a validation issue.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Severity {
    /// Warning - operation can proceed
    Warning,
    /// Error - operation should not proceed
    Error,
    /// Critical - immediate attention required
    Critical,
}

/// Type of validation issue.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum IssueType {
    /// Data is stale (older than threshold)
    StaleData,
    /// Contradiction detected between artifacts
    Contradiction,
    /// Missing reference to required entity
    MissingReference,
    /// Dosage limit exceeded
    DosageExceeded,
    /// Circular dependency detected
    CircularDependency,
}

/// A validation issue found during context validation.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ValidationIssue {
    /// Severity of the issue
    pub severity: Severity,
    /// Type of issue
    pub issue_type: IssueType,
    /// Human-readable message
    pub message: String,
    /// Entity ID related to this issue (if applicable)
    pub entity_id: Option<Uuid>,
}

/// Result of context validation.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ValidationResult {
    /// Whether validation passed (no errors or critical issues)
    pub valid: bool,
    /// List of issues found
    pub issues: Vec<ValidationIssue>,
}

impl ValidationResult {
    /// Create a valid result with no issues.
    #[tracing::instrument(skip_all)]
    pub fn valid() -> Self {
        Self {
            valid: true,
            issues: Vec::new(),
        }
    }

    /// Create an invalid result with issues.
    #[tracing::instrument(skip_all)]
    pub fn invalid(issues: Vec<ValidationIssue>) -> Self {
        Self {
            valid: false,
            issues,
        }
    }

    /// Add an issue to the result.
    #[tracing::instrument(skip_all)]
    pub fn add_issue(&mut self, issue: ValidationIssue) {
        // If we add an error or critical issue, mark as invalid
        if issue.severity == Severity::Error || issue.severity == Severity::Critical {
            self.valid = false;
        }
        self.issues.push(issue);
    }

    /// Check if there are any critical issues.
    #[tracing::instrument(skip_all)]
    pub fn has_critical(&self) -> bool {
        self.issues.iter().any(|i| i.severity == Severity::Critical)
    }

    /// Check if there are any errors.
    #[tracing::instrument(skip_all)]
    pub fn has_errors(&self) -> bool {
        self.issues
            .iter()
            .any(|i| i.severity == Severity::Error || i.severity == Severity::Critical)
    }

    /// Get all issues of a specific type.
    #[tracing::instrument(skip_all)]
    pub fn issues_of_type(&self, issue_type: IssueType) -> Vec<&ValidationIssue> {
        self.issues
            .iter()
            .filter(|i| i.issue_type == issue_type)
            .collect()
    }
}

/// Type of lint issue for artifacts.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum LintIssueType {
    /// Artifact is too large
    TooLarge,
    /// Duplicate artifact detected
    Duplicate,
    /// Missing embedding
    MissingEmbedding,
    /// Low confidence score
    LowConfidence,
    /// Syntax-level markdown/content issue detected
    SyntaxError,
    /// Reserved character sequence leaked into context (e.g. unescaped @mention)
    ReservedCharacterLeak,
}

/// A lint issue found during artifact linting.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct LintIssue {
    /// Type of lint issue
    pub issue_type: LintIssueType,
    /// Human-readable message
    pub message: String,
    /// Artifact ID this issue relates to
    pub artifact_id: ArtifactId,
}

/// Semantic lint issue for markdown/text content.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct MarkdownSemanticIssue {
    /// Type of lint issue
    pub issue_type: LintIssueType,
    /// 1-based line number where the issue was detected
    pub line: usize,
    /// Human-readable message
    pub message: String,
}

fn reserved_at_regex() -> &'static Regex {
    static RE: OnceLock<Regex> = OnceLock::new();
    RE.get_or_init(|| {
        Regex::new(r"(^|[^\w\\])@([A-Za-z0-9_./-]+)")
            .expect("reserved @ mention regex must compile")
    })
}

fn markdown_table_separator_regex() -> &'static Regex {
    static RE: OnceLock<Regex> = OnceLock::new();
    RE.get_or_init(|| {
        Regex::new(r"^:?-{3,}:?$").expect("markdown table separator regex must compile")
    })
}

fn markdown_table_column_count(line: &str) -> usize {
    let trimmed = line.trim();
    if !trimmed.contains('|') {
        return 0;
    }
    let core = trimmed.trim_matches('|').trim();
    if core.is_empty() {
        return 0;
    }
    core.split('|').count()
}

fn is_markdown_separator_row(line: &str) -> bool {
    let core = line.trim().trim_matches('|').trim();
    if core.is_empty() {
        return false;
    }
    core.split('|')
        .map(str::trim)
        .all(|seg| markdown_table_separator_regex().is_match(seg))
}

/// Lint markdown/text for semantic hazards that commonly break context tooling.
///
/// This is intentionally lightweight and deterministic:
/// - rejects unescaped mention-like `@` tokens (`@foo`, `@path/to/file`)
/// - flags unterminated fenced code blocks
/// - flags malformed markdown table rows with inconsistent column counts
pub fn lint_markdown_semantics(content: &str) -> Vec<MarkdownSemanticIssue> {
    let mut issues = Vec::new();
    let lines: Vec<&str> = content.lines().collect();

    // Reserved `@` leak detection (mention-like tokens, not emails).
    for (idx, line) in lines.iter().enumerate() {
        if reserved_at_regex().is_match(line) {
            issues.push(MarkdownSemanticIssue {
                issue_type: LintIssueType::ReservedCharacterLeak,
                line: idx + 1,
                message: "unescaped '@' token detected; escape as '\\@' to avoid agent import side-effects".to_string(),
            });
        }
    }

    // Unterminated fenced block detection.
    let mut open_fence_line: Option<usize> = None;
    for (idx, line) in lines.iter().enumerate() {
        if line.trim_start().starts_with("```") {
            if open_fence_line.is_some() {
                open_fence_line = None;
            } else {
                open_fence_line = Some(idx + 1);
            }
        }
    }
    if let Some(line) = open_fence_line {
        issues.push(MarkdownSemanticIssue {
            issue_type: LintIssueType::SyntaxError,
            line,
            message: format!("unterminated fenced code block opened at line {}", line),
        });
    }

    // Markdown table shape validation.
    let mut i = 0usize;
    while i + 1 < lines.len() {
        if !lines[i].contains('|') || !is_markdown_separator_row(lines[i + 1]) {
            i += 1;
            continue;
        }

        let expected_cols = markdown_table_column_count(lines[i]);
        if expected_cols == 0 {
            i += 1;
            continue;
        }

        let mut j = i + 2;
        while j < lines.len() && lines[j].contains('|') {
            let cols = markdown_table_column_count(lines[j]);
            if cols != expected_cols {
                issues.push(MarkdownSemanticIssue {
                    issue_type: LintIssueType::SyntaxError,
                    line: j + 1,
                    message: format!(
                        "malformed markdown table row: expected {} columns, found {}",
                        expected_cols, cols
                    ),
                });
                break;
            }
            j += 1;
        }

        i = j;
    }

    issues
}

/// Result of artifact linting.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct LintResult {
    /// Whether linting passed
    pub passed: bool,
    /// List of issues found
    pub issues: Vec<LintIssue>,
}

impl LintResult {
    /// Create a passing lint result.
    #[tracing::instrument(skip_all)]
    pub fn passed() -> Self {
        Self {
            passed: true,
            issues: Vec::new(),
        }
    }

    /// Create a failing lint result.
    #[tracing::instrument(skip_all)]
    pub fn failed(issues: Vec<LintIssue>) -> Self {
        Self {
            passed: false,
            issues,
        }
    }

    /// Add an issue to the result.
    #[tracing::instrument(skip_all)]
    pub fn add_issue(&mut self, issue: LintIssue) {
        self.passed = false;
        self.issues.push(issue);
    }
}

/// State captured in a checkpoint.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct CheckpointState {
    /// Serialized context snapshot
    pub context_snapshot: RawContent,
    /// Artifact IDs at checkpoint time
    pub artifact_ids: Vec<ArtifactId>,
    /// Note IDs at checkpoint time
    pub note_ids: Vec<NoteId>,
}

/// A PCP checkpoint for recovery.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PCPCheckpoint {
    /// Unique identifier for this checkpoint
    pub checkpoint_id: Uuid,
    /// Scope this checkpoint belongs to
    pub scope_id: ScopeId,
    /// State captured in this checkpoint
    pub state: CheckpointState,
    /// When this checkpoint was created
    pub created_at: Timestamp,
}

/// Result of recovery operation.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct RecoveryResult {
    /// Whether recovery succeeded
    pub success: bool,
    /// Recovered scope (if successful)
    pub recovered_scope: Option<Scope>,
    /// Errors encountered during recovery
    pub errors: Vec<String>,
}

impl RecoveryResult {
    /// Create a successful recovery result.
    #[tracing::instrument(skip_all)]
    pub fn success(scope: Scope) -> Self {
        Self {
            success: true,
            recovered_scope: Some(scope),
            errors: Vec::new(),
        }
    }

    /// Create a failed recovery result.
    #[tracing::instrument(skip_all)]
    pub fn failure(errors: Vec<String>) -> Self {
        Self {
            success: false,
            recovered_scope: None,
            errors,
        }
    }
}

/// Detected contradiction between artifacts.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Contradiction {
    /// First artifact in the contradiction
    pub artifact_a: ArtifactId,
    /// Second artifact in the contradiction
    pub artifact_b: ArtifactId,
    /// Similarity score that triggered detection
    pub similarity_score: f32,
    /// Description of the contradiction
    pub description: String,
}

/// PCP Runtime - the main validation and checkpoint engine.
#[derive(Debug, Clone)]
pub struct PCPRuntime {
    /// PCP configuration
    config: PCPConfig,
    /// Checkpoints stored in memory (in production, backed by storage)
    checkpoints: Vec<PCPCheckpoint>,
}

impl PCPRuntime {
    /// Create a new PCP runtime with the given configuration.
    #[tracing::instrument(skip_all)]
    pub fn new(config: PCPConfig) -> CellstateResult<Self> {
        config.validate()?;
        Ok(Self {
            config,
            checkpoints: Vec::new(),
        })
    }

    /// Get the configuration.
    #[tracing::instrument(skip_all)]
    pub fn config(&self) -> &PCPConfig {
        &self.config
    }
}

// ============================================================================
// VALIDATION IMPLEMENTATION (Task 8.6)
// ============================================================================

impl PCPRuntime {
    /// Validate context integrity.
    /// Checks for stale data, missing references, and dosage limits.
    ///
    /// # Arguments
    /// * `scope` - The scope to validate
    /// * `artifacts` - Artifacts in the scope
    /// * `current_tokens` - Current token count in the scope
    ///
    /// # Returns
    /// ValidationResult with any issues found
    #[tracing::instrument(skip_all)]
    pub fn validate_context_integrity(
        &self,
        scope: &Scope,
        artifacts: &[Artifact],
        current_tokens: i32,
    ) -> CellstateResult<ValidationResult> {
        let mut result = ValidationResult::valid();

        // Check dosage limits
        self.check_dosage_limits(&mut result, artifacts.len() as i32, current_tokens);

        // Check for stale scope
        self.check_stale_scope(&mut result, scope);

        // Check artifact integrity
        for artifact in artifacts {
            self.check_artifact_integrity(&mut result, artifact);
        }

        Ok(result)
    }

    /// Check dosage limits.
    fn check_dosage_limits(
        &self,
        result: &mut ValidationResult,
        artifact_count: i32,
        token_count: i32,
    ) {
        // Check token limit
        if token_count > self.config.dosage.max_tokens_per_scope {
            result.add_issue(ValidationIssue {
                severity: Severity::Warning,
                issue_type: IssueType::DosageExceeded,
                message: format!(
                    "Token count ({}) exceeds limit ({})",
                    token_count, self.config.dosage.max_tokens_per_scope
                ),
                entity_id: None,
            });
        }

        // Check artifact limit
        if artifact_count > self.config.dosage.max_artifacts_per_scope {
            result.add_issue(ValidationIssue {
                severity: Severity::Warning,
                issue_type: IssueType::DosageExceeded,
                message: format!(
                    "Artifact count ({}) exceeds limit ({})",
                    artifact_count, self.config.dosage.max_artifacts_per_scope
                ),
                entity_id: None,
            });
        }
    }

    /// Check if scope is stale.
    fn check_stale_scope(&self, result: &mut ValidationResult, scope: &Scope) {
        let now = Utc::now();
        let age = now.signed_duration_since(scope.created_at);

        // Use configured staleness threshold
        if age.num_hours() > self.config.staleness.stale_hours && scope.is_active {
            result.add_issue(ValidationIssue {
                severity: Severity::Warning,
                issue_type: IssueType::StaleData,
                message: format!(
                    "Scope {} is {} hours old and still active (threshold: {} hours)",
                    scope.scope_id,
                    age.num_hours(),
                    self.config.staleness.stale_hours
                ),
                entity_id: Some(scope.scope_id.as_uuid()),
            });
        }
    }

    /// Check artifact integrity.
    fn check_artifact_integrity(&self, result: &mut ValidationResult, artifact: &Artifact) {
        // Check for missing embedding if grounding requires it
        if self.config.grounding.require_artifact_backing && artifact.embedding.is_none() {
            result.add_issue(ValidationIssue {
                severity: Severity::Warning,
                issue_type: IssueType::MissingReference,
                message: format!(
                    "Artifact {} is missing embedding (required for grounding)",
                    artifact.artifact_id
                ),
                entity_id: Some(artifact.artifact_id.as_uuid()),
            });
        }

        // Check for low confidence
        if let Some(confidence) = artifact.provenance.confidence {
            if confidence < self.config.linting.min_confidence_threshold {
                result.add_issue(ValidationIssue {
                    severity: Severity::Warning,
                    issue_type: IssueType::MissingReference,
                    message: format!(
                        "Artifact {} has low confidence ({})",
                        artifact.artifact_id, confidence
                    ),
                    entity_id: Some(artifact.artifact_id.as_uuid()),
                });
            }
        }
    }
}

// ============================================================================
// CONTRADICTION DETECTION (Task 8.7)
// ============================================================================

impl PCPRuntime {
    /// Detect contradictions between artifacts using embedding similarity.
    /// Two artifacts are considered potentially contradictory if:
    /// 1. They have high embedding similarity (similar topic)
    /// 2. Their content differs significantly
    ///
    /// # Arguments
    /// * `artifacts` - Artifacts to check for contradictions
    ///
    /// # Returns
    /// Vector of detected contradictions
    #[tracing::instrument(skip_all)]
    pub fn detect_contradictions(
        &self,
        artifacts: &[Artifact],
    ) -> CellstateResult<Vec<Contradiction>> {
        let mut contradictions = Vec::new();

        // Compare each pair of artifacts
        for i in 0..artifacts.len() {
            for j in (i + 1)..artifacts.len() {
                let artifact_a = &artifacts[i];
                let artifact_b = &artifacts[j];

                // Skip if either artifact lacks an embedding
                let (embedding_a, embedding_b) =
                    match (&artifact_a.embedding, &artifact_b.embedding) {
                        (Some(a), Some(b)) => (a, b),
                        _ => continue,
                    };

                // Calculate similarity
                let similarity = match embedding_a.cosine_similarity(embedding_b) {
                    Ok(s) => s,
                    Err(_) => continue, // Skip if dimension mismatch
                };

                // Check if similarity exceeds threshold
                if similarity >= self.config.grounding.contradiction_threshold {
                    // High similarity - check if content differs
                    if artifact_a.content != artifact_b.content {
                        // Same topic, different content - potential contradiction
                        contradictions.push(Contradiction {
                            artifact_a: artifact_a.artifact_id,
                            artifact_b: artifact_b.artifact_id,
                            similarity_score: similarity,
                            description: format!(
                                "Artifacts have high similarity ({:.2}) but different content",
                                similarity
                            ),
                        });
                    }
                }
            }
        }

        Ok(contradictions)
    }
}

// ============================================================================
// DOSAGE LIMITS (Task 8.8)
// ============================================================================

/// Result of applying dosage limits.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct DosageResult {
    /// Whether limits were exceeded
    pub exceeded: bool,
    /// Artifacts that were pruned (if any)
    pub pruned_artifacts: Vec<ArtifactId>,
    /// Tokens that were trimmed
    pub tokens_trimmed: i32,
    /// Warning messages
    pub warnings: Vec<String>,
}

impl DosageResult {
    /// Create a result indicating no limits were exceeded.
    #[tracing::instrument(skip_all)]
    pub fn within_limits() -> Self {
        Self {
            exceeded: false,
            pruned_artifacts: Vec::new(),
            tokens_trimmed: 0,
            warnings: Vec::new(),
        }
    }

    /// Create a result indicating limits were exceeded.
    #[tracing::instrument(skip_all)]
    pub fn exceeded_limits() -> Self {
        Self {
            exceeded: true,
            pruned_artifacts: Vec::new(),
            tokens_trimmed: 0,
            warnings: Vec::new(),
        }
    }

    /// Add a pruned artifact.
    #[tracing::instrument(skip_all)]
    pub fn add_pruned(&mut self, artifact_id: ArtifactId) {
        self.pruned_artifacts.push(artifact_id);
    }

    /// Add a warning.
    #[tracing::instrument(skip_all)]
    pub fn add_warning(&mut self, warning: String) {
        self.warnings.push(warning);
    }
}

impl PCPRuntime {
    /// Apply dosage limits to artifacts and tokens.
    /// Returns which artifacts should be pruned to stay within limits.
    ///
    /// # Arguments
    /// * `artifacts` - Current artifacts (sorted by priority/recency)
    /// * `current_tokens` - Current token count
    ///
    /// # Returns
    /// DosageResult indicating what needs to be pruned
    #[tracing::instrument(skip_all)]
    pub fn apply_dosage_limits(
        &self,
        artifacts: &[Artifact],
        current_tokens: i32,
    ) -> CellstateResult<DosageResult> {
        let mut result = DosageResult::within_limits();

        // Check token limit
        if current_tokens > self.config.dosage.max_tokens_per_scope {
            result.exceeded = true;
            result.tokens_trimmed = current_tokens - self.config.dosage.max_tokens_per_scope;
            result.add_warning(format!(
                "Token limit exceeded: {} > {}. Need to trim {} tokens.",
                current_tokens, self.config.dosage.max_tokens_per_scope, result.tokens_trimmed
            ));
        }

        // Check artifact limit
        let artifact_count = artifacts.len() as i32;
        if artifact_count > self.config.dosage.max_artifacts_per_scope {
            result.exceeded = true;
            let excess = artifact_count - self.config.dosage.max_artifacts_per_scope;

            // Mark excess artifacts for pruning (from the end, assuming sorted by priority)
            let start_prune = artifacts.len() - excess as usize;
            for artifact in &artifacts[start_prune..] {
                result.add_pruned(artifact.artifact_id);
            }

            result.add_warning(format!(
                "Artifact limit exceeded: {} > {}. Pruning {} artifacts.",
                artifact_count, self.config.dosage.max_artifacts_per_scope, excess
            ));
        }

        Ok(result)
    }

    /// Check if adding more content would exceed dosage limits.
    ///
    /// # Arguments
    /// * `current_artifacts` - Current artifact count
    /// * `current_tokens` - Current token count
    /// * `additional_artifacts` - Artifacts to add
    /// * `additional_tokens` - Tokens to add
    ///
    /// # Returns
    /// true if adding would exceed limits
    #[tracing::instrument(skip_all)]
    pub fn would_exceed_limits(
        &self,
        current_artifacts: i32,
        current_tokens: i32,
        additional_artifacts: i32,
        additional_tokens: i32,
    ) -> bool {
        let new_artifacts = current_artifacts + additional_artifacts;
        let new_tokens = current_tokens + additional_tokens;

        new_artifacts > self.config.dosage.max_artifacts_per_scope
            || new_tokens > self.config.dosage.max_tokens_per_scope
    }
}

// ============================================================================
// ARTIFACT LINTING (Task 8.9)
// ============================================================================

// NOTE: MAX_ARTIFACT_SIZE and MIN_CONFIDENCE_THRESHOLD removed per REQ-6.
// These values must come from PCPConfig - no hard-coded defaults.

impl PCPRuntime {
    /// Lint an artifact for quality issues.
    /// Checks for size, duplicates, missing embeddings, and low confidence.
    ///
    /// # Arguments
    /// * `artifact` - The artifact to lint
    /// * `existing_artifacts` - Existing artifacts to check for duplicates
    ///
    /// # Returns
    /// LintResult with any issues found
    #[tracing::instrument(skip_all)]
    pub fn lint_artifact(
        &self,
        artifact: &Artifact,
        existing_artifacts: &[Artifact],
    ) -> CellstateResult<LintResult> {
        let mut result = LintResult::passed();

        // Check size
        self.check_artifact_size(&mut result, artifact);

        // Check for duplicates
        self.check_artifact_duplicates(&mut result, artifact, existing_artifacts);

        // Check for missing embedding
        self.check_artifact_embedding(&mut result, artifact);

        // Check confidence
        self.check_artifact_confidence(&mut result, artifact);

        // Check semantic markdown/context hazards
        self.check_artifact_semantics(&mut result, artifact);

        Ok(result)
    }

    /// Check if artifact content is too large.
    fn check_artifact_size(&self, result: &mut LintResult, artifact: &Artifact) {
        let max_size = self.config.linting.max_artifact_size;
        if artifact.content.len() > max_size {
            result.add_issue(LintIssue {
                issue_type: LintIssueType::TooLarge,
                message: format!(
                    "Artifact content size ({} bytes) exceeds maximum ({} bytes)",
                    artifact.content.len(),
                    max_size
                ),
                artifact_id: artifact.artifact_id,
            });
        }
    }

    /// Check for duplicate artifacts by content hash.
    fn check_artifact_duplicates(
        &self,
        result: &mut LintResult,
        artifact: &Artifact,
        existing_artifacts: &[Artifact],
    ) {
        for existing in existing_artifacts {
            // Skip self-comparison
            if existing.artifact_id == artifact.artifact_id {
                continue;
            }

            // Check content hash for exact duplicates
            if existing.content_hash == artifact.content_hash {
                result.add_issue(LintIssue {
                    issue_type: LintIssueType::Duplicate,
                    message: format!(
                        "Artifact is a duplicate of existing artifact {}",
                        existing.artifact_id
                    ),
                    artifact_id: artifact.artifact_id,
                });
                break; // Only report first duplicate
            }
        }
    }

    /// Check if artifact is missing embedding.
    fn check_artifact_embedding(&self, result: &mut LintResult, artifact: &Artifact) {
        if self.config.grounding.require_artifact_backing && artifact.embedding.is_none() {
            result.add_issue(LintIssue {
                issue_type: LintIssueType::MissingEmbedding,
                message: "Artifact is missing embedding (required for grounding)".to_string(),
                artifact_id: artifact.artifact_id,
            });
        }
    }

    /// Check artifact confidence score.
    fn check_artifact_confidence(&self, result: &mut LintResult, artifact: &Artifact) {
        let min_threshold = self.config.linting.min_confidence_threshold;
        if let Some(confidence) = artifact.provenance.confidence {
            if confidence < min_threshold {
                result.add_issue(LintIssue {
                    issue_type: LintIssueType::LowConfidence,
                    message: format!(
                        "Artifact confidence ({:.2}) is below threshold ({:.2})",
                        confidence, min_threshold
                    ),
                    artifact_id: artifact.artifact_id,
                });
            }
        }
    }

    /// Check semantic markdown/context hazards inside artifact content.
    fn check_artifact_semantics(&self, result: &mut LintResult, artifact: &Artifact) {
        for issue in lint_markdown_semantics(&artifact.content) {
            result.add_issue(LintIssue {
                issue_type: issue.issue_type,
                message: format!("line {}: {}", issue.line, issue.message),
                artifact_id: artifact.artifact_id,
            });
        }
    }

    /// Lint multiple artifacts at once.
    ///
    /// # Arguments
    /// * `artifacts` - Artifacts to lint
    ///
    /// # Returns
    /// Combined LintResult for all artifacts
    #[tracing::instrument(skip_all)]
    pub fn lint_artifacts(&self, artifacts: &[Artifact]) -> CellstateResult<LintResult> {
        let mut combined_result = LintResult::passed();

        for artifact in artifacts {
            let result = self.lint_artifact(artifact, artifacts)?;
            for issue in result.issues {
                combined_result.add_issue(issue);
            }
        }

        Ok(combined_result)
    }
}

// ============================================================================
// CHECKPOINT CREATION AND RECOVERY (Task 8.10)
// ============================================================================

impl PCPRuntime {
    /// Create a checkpoint for a scope.
    /// Captures the current state for potential recovery.
    ///
    /// # Arguments
    /// * `scope` - The scope to checkpoint
    /// * `artifacts` - Current artifacts in the scope
    /// * `note_ids` - Current note IDs referenced by the scope
    ///
    /// # Returns
    /// The created checkpoint
    #[tracing::instrument(skip_all)]
    pub fn create_checkpoint(
        &mut self,
        scope: &Scope,
        artifacts: &[Artifact],
        note_ids: &[NoteId],
    ) -> CellstateResult<PCPCheckpoint> {
        // Check if recovery is enabled
        if !self.config.recovery.enabled {
            return Err(CellstateError::Validation(
                ValidationError::ConstraintViolation {
                    constraint: "recovery.enabled".to_string(),
                    reason: "Recovery is disabled in configuration".to_string(),
                },
            ));
        }

        // Serialize the scope state
        let context_snapshot = serde_json::to_vec(scope).map_err(|e| {
            CellstateError::Validation(ValidationError::InvalidValue {
                field: "scope".to_string(),
                reason: format!("Failed to serialize scope: {}", e),
            })
        })?;

        // Collect artifact IDs
        let artifact_ids: Vec<ArtifactId> = artifacts.iter().map(|a| a.artifact_id).collect();

        // Create checkpoint state
        let state = CheckpointState {
            context_snapshot,
            artifact_ids,
            note_ids: note_ids.to_vec(),
        };

        // Create the checkpoint
        let checkpoint = PCPCheckpoint {
            checkpoint_id: Uuid::now_v7(),
            scope_id: scope.scope_id,
            state,
            created_at: Utc::now(),
        };

        // Store the checkpoint
        self.checkpoints.push(checkpoint.clone());

        // Enforce max checkpoints limit
        self.enforce_checkpoint_limit();

        Ok(checkpoint)
    }

    /// Enforce the maximum checkpoint limit by removing oldest checkpoints.
    fn enforce_checkpoint_limit(&mut self) {
        let max = self.config.recovery.max_checkpoints as usize;
        if self.checkpoints.len() > max {
            // Sort by created_at ascending (oldest first)
            self.checkpoints
                .sort_by_key(|checkpoint| checkpoint.created_at);

            // Remove oldest checkpoints
            let excess = self.checkpoints.len() - max;
            self.checkpoints.drain(0..excess);
        }
    }

    /// Recover a scope from a checkpoint.
    ///
    /// # Arguments
    /// * `checkpoint` - The checkpoint to recover from
    ///
    /// # Returns
    /// RecoveryResult with the recovered scope
    #[tracing::instrument(skip_all)]
    pub fn recover_from_checkpoint(
        &self,
        checkpoint: &PCPCheckpoint,
    ) -> CellstateResult<RecoveryResult> {
        // Check if recovery is enabled
        if !self.config.recovery.enabled {
            return Ok(RecoveryResult::failure(vec![
                "Recovery is disabled in configuration".to_string(),
            ]));
        }

        // Deserialize the scope
        let scope: Scope = match serde_json::from_slice(&checkpoint.state.context_snapshot) {
            Ok(s) => s,
            Err(e) => {
                return Ok(RecoveryResult::failure(vec![format!(
                    "Failed to deserialize scope: {}",
                    e
                )]));
            }
        };

        Ok(RecoveryResult::success(scope))
    }

    /// Get the latest checkpoint for a scope.
    ///
    /// # Arguments
    /// * `scope_id` - The scope to get checkpoint for
    ///
    /// # Returns
    /// The latest checkpoint if found
    #[tracing::instrument(skip_all)]
    pub fn get_latest_checkpoint(&self, scope_id: ScopeId) -> Option<&PCPCheckpoint> {
        self.checkpoints
            .iter()
            .filter(|c| c.scope_id == scope_id)
            .max_by_key(|c| c.created_at)
    }

    /// Get all checkpoints for a scope.
    ///
    /// # Arguments
    /// * `scope_id` - The scope to get checkpoints for
    ///
    /// # Returns
    /// Vector of checkpoints for the scope
    #[tracing::instrument(skip_all)]
    pub fn get_checkpoints_for_scope(&self, scope_id: ScopeId) -> Vec<&PCPCheckpoint> {
        self.checkpoints
            .iter()
            .filter(|c| c.scope_id == scope_id)
            .collect()
    }

    /// Delete a checkpoint.
    ///
    /// # Arguments
    /// * `checkpoint_id` - The checkpoint to delete
    ///
    /// # Returns
    /// true if checkpoint was deleted
    #[tracing::instrument(skip_all)]
    pub fn delete_checkpoint(&mut self, checkpoint_id: Uuid) -> bool {
        let initial_len = self.checkpoints.len();
        self.checkpoints
            .retain(|c| c.checkpoint_id != checkpoint_id);
        self.checkpoints.len() < initial_len
    }

    /// Clear all checkpoints for a scope.
    ///
    /// # Arguments
    /// * `scope_id` - The scope to clear checkpoints for
    ///
    /// # Returns
    /// Number of checkpoints deleted
    #[tracing::instrument(skip_all)]
    pub fn clear_checkpoints_for_scope(&mut self, scope_id: ScopeId) -> usize {
        let initial_len = self.checkpoints.len();
        self.checkpoints.retain(|c| c.scope_id != scope_id);
        initial_len - self.checkpoints.len()
    }
}

// ============================================================================
// BATTLE INTEL FEATURE 4: SUMMARIZATION TRIGGER CHECKING
// ============================================================================

impl PCPRuntime {
    /// Check which summarization triggers should fire based on current scope state.
    ///
    /// This method evaluates all provided summarization policies against the
    /// current state of a scope and returns which triggers should activate.
    /// Inspired by EVOLVE-MEM's self-improvement engine.
    ///
    /// # Arguments
    /// * `scope` - The scope to evaluate triggers for
    /// * `turn_count` - Number of turns in the scope
    /// * `artifact_count` - Number of artifacts in the scope
    /// * `policies` - Summarization policies to check
    ///
    /// # Returns
    /// Vector of (summarization_policy_id, triggered_trigger) pairs for policies that should fire
    ///
    /// # Example
    /// ```ignore
    /// let triggered = runtime.check_summarization_triggers(
    ///     &scope,
    ///     turns.len() as i32,
    ///     artifacts.len() as i32,
    ///     &policies,
    /// )?;
    ///
    /// for (summarization_policy_id, trigger) in triggered {
    ///     // Execute summarization for this policy
    /// }
    /// ```
    #[tracing::instrument(skip_all)]
    pub fn check_summarization_triggers(
        &self,
        scope: &Scope,
        turn_count: i32,
        artifact_count: i32,
        policies: &[SummarizationPolicy],
    ) -> CellstateResult<Vec<(SummarizationPolicyId, SummarizationTrigger)>> {
        let mut triggered = Vec::new();

        // Calculate current token usage percentage
        let token_usage_percent = if scope.token_budget > 0 {
            ((scope.tokens_used as f32 / scope.token_budget as f32) * 100.0) as u8
        } else {
            0
        };

        for policy in policies {
            for trigger in &policy.triggers {
                let should_fire = match trigger {
                    SummarizationTrigger::DosageThreshold { percent } => {
                        token_usage_percent >= *percent
                    }
                    SummarizationTrigger::ScopeClose => {
                        // Fires when scope is no longer active
                        !scope.is_active
                    }
                    SummarizationTrigger::TurnCount { count } => {
                        // Fires when turn count reaches threshold
                        turn_count >= *count && turn_count % *count == 0
                    }
                    SummarizationTrigger::ArtifactCount { count } => {
                        // Fires when artifact count reaches threshold
                        artifact_count >= *count && artifact_count % *count == 0
                    }
                    SummarizationTrigger::Manual => {
                        // Manual triggers never auto-fire
                        false
                    }
                };

                if should_fire {
                    triggered.push((policy.summarization_policy_id, *trigger));
                }
            }
        }

        Ok(triggered)
    }

    /// Calculate what abstraction level transition should occur for a policy.
    ///
    /// # Arguments
    /// * `policy` - The policy defining source->target transition
    ///
    /// # Returns
    /// Tuple of (source_level, target_level) for the summarization operation
    #[tracing::instrument(skip_all)]
    pub fn get_abstraction_transition(
        &self,
        policy: &SummarizationPolicy,
    ) -> (AbstractionLevel, AbstractionLevel) {
        (policy.source_level, policy.target_level)
    }

    /// Validate an abstraction level transition.
    ///
    /// Valid transitions are:
    /// - Raw -> Summary (L0 -> L1)
    /// - Summary -> Principle (L1 -> L2)
    /// - Raw -> Principle (L0 -> L2, skipping L1)
    ///
    /// Invalid transitions:
    /// - Summary -> Raw (downgrade)
    /// - Principle -> Summary/Raw (downgrade)
    /// - Same level to same level
    ///
    /// # Arguments
    /// * `source` - Source abstraction level
    /// * `target` - Target abstraction level
    ///
    /// # Returns
    /// true if the transition is valid
    #[tracing::instrument(skip_all)]
    pub fn validate_abstraction_transition(
        &self,
        source: AbstractionLevel,
        target: AbstractionLevel,
    ) -> bool {
        match (source, target) {
            // Valid upward transitions
            (AbstractionLevel::Raw, AbstractionLevel::Summary) => true,
            (AbstractionLevel::Raw, AbstractionLevel::Principle) => true,
            (AbstractionLevel::Summary, AbstractionLevel::Principle) => true,
            // Invalid: same level or downgrade
            _ => false,
        }
    }
}

// ============================================================================
// TESTS
// ============================================================================

#[cfg(test)]
mod tests {
    use super::*;
    use cellstate_core::{
        ArtifactType, ContextPersistence, ExtractionMethod, Provenance, RetryConfig,
        SectionPriorities, ValidationMode, TTL,
    };
    use std::time::Duration;

    pub(crate) fn make_test_cellstate_config() -> CellstateConfig {
        CellstateConfig {
            token_budget: 8000,
            section_priorities: SectionPriorities {
                user: 100,
                system: 90,
                persona: 85,
                artifacts: 80,
                notes: 70,
                history: 60,
                custom: vec![],
            },
            checkpoint_retention: 10,
            stale_threshold: Duration::from_secs(3600),
            contradiction_threshold: 0.8,
            context_window_persistence: ContextPersistence::Ephemeral,
            validation_mode: ValidationMode::OnMutation,
            embedding_provider: None,
            summarization_provider: None,
            llm_retry_config: RetryConfig {
                max_retries: 3,
                initial_backoff: Duration::from_millis(100),
                max_backoff: Duration::from_secs(10),
                backoff_multiplier: 2.0,
            },
            lock_timeout: Duration::from_secs(30),
            message_retention: Duration::from_secs(86400),
            delegation_timeout: Duration::from_secs(300),
        }
    }

    fn make_test_pcp_config() -> PCPConfig {
        PCPConfig {
            context_dag: ContextDagConfig {
                max_depth: 10,
                prune_strategy: PruneStrategy::OldestFirst,
            },
            recovery: RecoveryConfig {
                enabled: true,
                frequency: RecoveryFrequency::OnScopeClose,
                max_checkpoints: 5,
            },
            dosage: DosageConfig {
                max_tokens_per_scope: 8000,
                max_artifacts_per_scope: 100,
                max_notes_per_trajectory: 500,
            },
            anti_sprawl: AntiSprawlConfig {
                max_trajectory_depth: 5,
                max_concurrent_scopes: 10,
            },
            grounding: GroundingConfig {
                require_artifact_backing: false,
                contradiction_threshold: 0.85,
                conflict_resolution: ConflictResolution::LastWriteWins,
            },
            linting: LintingConfig {
                max_artifact_size: 1024 * 1024, // 1MB
                min_confidence_threshold: 0.3,
            },
            staleness: StalenessConfig {
                stale_hours: 24 * 30, // 30 days
            },
        }
    }

    fn make_test_scope() -> Scope {
        Scope {
            scope_id: ScopeId::now_v7(),
            trajectory_id: TrajectoryId::now_v7(),
            parent_scope_id: None,
            name: "Test Scope".to_string(),
            purpose: Some("Testing".to_string()),
            is_active: true,
            created_at: Utc::now(),
            closed_at: None,
            checkpoint: None,
            token_budget: 8000,
            tokens_used: 0,
            metadata: None,
        }
    }

    fn make_test_artifact(content: &str) -> Artifact {
        Artifact {
            artifact_id: ArtifactId::now_v7(),
            trajectory_id: TrajectoryId::now_v7(),
            scope_id: ScopeId::now_v7(),
            artifact_type: ArtifactType::Fact,
            name: "Test Artifact".to_string(),
            content: content.to_string(),
            content_hash: cellstate_core::compute_content_hash(content.as_bytes()),
            embedding: None,
            provenance: Provenance {
                source_turn: 1,
                extraction_method: ExtractionMethod::Explicit,
                confidence: Some(0.9),
            },
            ttl: TTL::Persistent,
            created_at: Utc::now(),
            updated_at: Utc::now(),
            superseded_by: None,
            metadata: None,
        }
    }

    // ========================================================================
    // MemoryCommit Tests
    // ========================================================================

    #[test]
    fn test_memory_commit_new() {
        let traj_id = TrajectoryId::now_v7();
        let scope_id = ScopeId::now_v7();
        let commit = MemoryCommit::new(
            traj_id,
            scope_id,
            "What is the weather?".to_string(),
            "The weather is sunny.".to_string(),
            "standard".to_string(),
        );

        assert_eq!(commit.trajectory_id, traj_id);
        assert_eq!(commit.scope_id, scope_id);
        assert_eq!(commit.query, "What is the weather?");
        assert_eq!(commit.response, "The weather is sunny.");
        assert_eq!(commit.mode, "standard");
        assert!(commit.agent_id.is_none());
    }

    #[test]
    fn test_memory_commit_with_tokens() {
        let commit = MemoryCommit::new(
            TrajectoryId::now_v7(),
            ScopeId::now_v7(),
            "query".to_string(),
            "response".to_string(),
            "standard".to_string(),
        )
        .with_tokens(100, 200);

        assert_eq!(commit.tokens_input, 100);
        assert_eq!(commit.tokens_output, 200);
        assert_eq!(commit.total_tokens(), 300);
    }

    // ========================================================================
    // RecallService Tests
    // ========================================================================

    #[test]
    fn test_recall_service_add_and_recall() {
        let config = make_test_cellstate_config();
        let mut service =
            RecallService::new(config).expect("RecallService creation should succeed");

        let traj_id = TrajectoryId::now_v7();
        let scope_id = ScopeId::now_v7();

        let commit = MemoryCommit::new(
            traj_id,
            scope_id,
            "query".to_string(),
            "response".to_string(),
            "standard".to_string(),
        );

        service.add_commit(commit);

        let results = service
            .recall_previous(Some(traj_id), None, 10)
            .expect("recall_previous should succeed");
        assert_eq!(results.len(), 1);
        assert_eq!(results[0].query, "query");
    }

    #[test]
    fn test_recall_service_search() {
        let config = make_test_cellstate_config();
        let mut service =
            RecallService::new(config).expect("RecallService creation should succeed");

        service.add_commit(MemoryCommit::new(
            TrajectoryId::now_v7(),
            ScopeId::now_v7(),
            "weather query".to_string(),
            "sunny response".to_string(),
            "standard".to_string(),
        ));

        service.add_commit(MemoryCommit::new(
            TrajectoryId::now_v7(),
            ScopeId::now_v7(),
            "code query".to_string(),
            "code response".to_string(),
            "standard".to_string(),
        ));

        let results = service
            .search_interactions("weather", 10)
            .expect("search_interactions should succeed");
        assert_eq!(results.len(), 1);
        assert!(results[0].query.contains("weather"));
    }

    // ========================================================================
    // Decision Extraction Tests
    // ========================================================================

    #[test]
    fn test_extract_decision_recommend() {
        let response = "Based on the analysis, I recommend using Rust for this project.";
        let decision = extract_decision(response);
        assert!(decision.contains("recommend"));
    }

    #[test]
    fn test_extract_decision_should() {
        let response = "You should consider using a database for persistence.";
        let decision = extract_decision(response);
        assert!(decision.contains("should"));
    }

    #[test]
    fn test_extract_decision_fallback() {
        let response = "This is a simple response without decision keywords";
        let decision = extract_decision(response);
        // Should fall back to first sentence
        assert!(!decision.is_empty());
    }

    // ========================================================================
    // PCPConfig Tests
    // ========================================================================

    #[test]
    fn test_pcp_config_valid() {
        let config = make_test_pcp_config();
        assert!(config.validate().is_ok());
    }

    #[test]
    fn test_pcp_config_invalid_max_depth() {
        let mut config = make_test_pcp_config();
        config.context_dag.max_depth = 0;
        assert!(config.validate().is_err());
    }

    #[test]
    fn test_pcp_config_invalid_threshold() {
        let mut config = make_test_pcp_config();
        config.grounding.contradiction_threshold = 1.5;
        assert!(config.validate().is_err());
    }

    // ========================================================================
    // PCPRuntime Tests
    // ========================================================================

    #[test]
    fn test_pcp_runtime_new() {
        let config = make_test_pcp_config();
        let runtime = PCPRuntime::new(config).expect("PCPRuntime creation should succeed");
        assert!(runtime.config().recovery.enabled);
    }

    #[test]
    fn test_validate_context_integrity() {
        let config = make_test_pcp_config();
        let runtime = PCPRuntime::new(config).expect("PCPRuntime creation should succeed");

        let scope = make_test_scope();
        let artifacts = vec![make_test_artifact("test content")];

        let result = runtime
            .validate_context_integrity(&scope, &artifacts, 1000)
            .expect("validate_context_integrity should succeed");
        assert!(result.valid);
    }

    #[test]
    fn test_validate_context_dosage_exceeded() {
        let mut config = make_test_pcp_config();
        config.dosage.max_tokens_per_scope = 100;
        let runtime = PCPRuntime::new(config).expect("PCPRuntime creation should succeed");

        let scope = make_test_scope();
        let artifacts = vec![];

        let result = runtime
            .validate_context_integrity(&scope, &artifacts, 1000)
            .expect("validate_context_integrity should succeed");
        // Should have a warning about dosage
        assert!(result
            .issues
            .iter()
            .any(|i| i.issue_type == IssueType::DosageExceeded));
    }

    // ========================================================================
    // Checkpoint Tests
    // ========================================================================

    #[test]
    fn test_create_checkpoint() {
        let config = make_test_pcp_config();
        let mut runtime = PCPRuntime::new(config).expect("PCPRuntime creation should succeed");

        let scope = make_test_scope();
        let artifacts = vec![make_test_artifact("test")];
        let note_ids = vec![NoteId::now_v7()];

        let checkpoint = runtime
            .create_checkpoint(&scope, &artifacts, &note_ids)
            .expect("create_checkpoint should succeed");

        assert_eq!(checkpoint.scope_id, scope.scope_id);
        assert_eq!(checkpoint.state.artifact_ids.len(), 1);
        assert_eq!(checkpoint.state.note_ids.len(), 1);
    }

    #[test]
    fn test_recover_from_checkpoint() {
        let config = make_test_pcp_config();
        let mut runtime = PCPRuntime::new(config).expect("PCPRuntime creation should succeed");

        let scope = make_test_scope();
        let checkpoint = runtime
            .create_checkpoint(&scope, &[], &[])
            .expect("create_checkpoint should succeed");

        let result = runtime
            .recover_from_checkpoint(&checkpoint)
            .expect("recover_from_checkpoint should succeed");
        assert!(result.success);
        assert!(result.recovered_scope.is_some());
        assert_eq!(
            result
                .recovered_scope
                .expect("recovered_scope should be present")
                .scope_id,
            scope.scope_id
        );
    }

    // ========================================================================
    // Lint Tests
    // ========================================================================

    #[test]
    fn test_lint_artifact_passes() {
        let config = make_test_pcp_config();
        let runtime = PCPRuntime::new(config).expect("PCPRuntime creation should succeed");

        let artifact = make_test_artifact("test content");
        let result = runtime
            .lint_artifact(&artifact, &[])
            .expect("lint_artifact should succeed");
        assert!(result.passed);
    }

    #[test]
    fn test_lint_artifact_duplicate() {
        let config = make_test_pcp_config();
        let runtime = PCPRuntime::new(config).expect("PCPRuntime creation should succeed");

        let artifact1 = make_test_artifact("same content");
        let mut artifact2 = make_test_artifact("same content");
        artifact2.artifact_id = ArtifactId::now_v7(); // Different ID, same content

        let result = runtime
            .lint_artifact(&artifact2, &[artifact1])
            .expect("lint_artifact should succeed");
        assert!(!result.passed);
        assert!(result
            .issues
            .iter()
            .any(|i| i.issue_type == LintIssueType::Duplicate));
    }

    #[test]
    fn test_lint_artifact_reserved_character_leak() {
        let config = make_test_pcp_config();
        let runtime = PCPRuntime::new(config).expect("PCPRuntime creation should succeed");

        let artifact = make_test_artifact("Please import @my_skill before execution.");
        let result = runtime
            .lint_artifact(&artifact, &[])
            .expect("lint_artifact should succeed");

        assert!(!result.passed);
        assert!(result
            .issues
            .iter()
            .any(|i| i.issue_type == LintIssueType::ReservedCharacterLeak));
    }

    #[test]
    fn test_lint_artifact_unterminated_fence() {
        let config = make_test_pcp_config();
        let runtime = PCPRuntime::new(config).expect("PCPRuntime creation should succeed");

        let artifact = make_test_artifact("```markdown\n# title\nstill open");
        let result = runtime
            .lint_artifact(&artifact, &[])
            .expect("lint_artifact should succeed");

        assert!(!result.passed);
        assert!(result
            .issues
            .iter()
            .any(|i| i.issue_type == LintIssueType::SyntaxError));
    }

    #[test]
    fn test_lint_markdown_semantics_detects_table_shape_mismatch() {
        let content = r#"
| a | b |
| --- | --- |
| 1 | 2 | 3 |
"#;
        let issues = lint_markdown_semantics(content);
        assert!(issues
            .iter()
            .any(|i| i.issue_type == LintIssueType::SyntaxError));
    }

    // ========================================================================
    // MemoryCommit builder chain tests
    // ========================================================================

    #[test]
    fn test_memory_commit_with_agent_id() {
        let agent_id = AgentId::now_v7();
        let commit = MemoryCommit::new(
            TrajectoryId::now_v7(),
            ScopeId::now_v7(),
            "q".into(),
            "r".into(),
            "standard".into(),
        )
        .with_agent_id(agent_id);
        assert_eq!(commit.agent_id, Some(agent_id));
    }

    #[test]
    fn test_memory_commit_with_reasoning_trace() {
        let trace = serde_json::json!({"step": 1});
        let commit = MemoryCommit::new(
            TrajectoryId::now_v7(),
            ScopeId::now_v7(),
            "q".into(),
            "r".into(),
            "standard".into(),
        )
        .with_reasoning_trace(trace.clone());
        assert_eq!(commit.reasoning_trace, Some(trace));
    }

    #[test]
    fn test_memory_commit_with_rag_contributed() {
        let commit = MemoryCommit::new(
            TrajectoryId::now_v7(),
            ScopeId::now_v7(),
            "q".into(),
            "r".into(),
            "standard".into(),
        )
        .with_rag_contributed(true);
        assert!(commit.rag_contributed);
    }

    #[test]
    fn test_memory_commit_with_artifacts_referenced() {
        let ids = vec![ArtifactId::now_v7(), ArtifactId::now_v7()];
        let commit = MemoryCommit::new(
            TrajectoryId::now_v7(),
            ScopeId::now_v7(),
            "q".into(),
            "r".into(),
            "standard".into(),
        )
        .with_artifacts_referenced(ids.clone());
        assert_eq!(commit.artifacts_referenced.len(), 2);
    }

    #[test]
    fn test_memory_commit_with_notes_referenced() {
        let ids = vec![NoteId::now_v7()];
        let commit = MemoryCommit::new(
            TrajectoryId::now_v7(),
            ScopeId::now_v7(),
            "q".into(),
            "r".into(),
            "standard".into(),
        )
        .with_notes_referenced(ids);
        assert_eq!(commit.notes_referenced.len(), 1);
    }

    #[test]
    fn test_memory_commit_with_tools_invoked() {
        let commit = MemoryCommit::new(
            TrajectoryId::now_v7(),
            ScopeId::now_v7(),
            "q".into(),
            "r".into(),
            "standard".into(),
        )
        .with_tools_invoked(vec!["search".into(), "write".into()]);
        assert_eq!(commit.tools_invoked.len(), 2);
    }

    #[test]
    fn test_memory_commit_with_estimated_cost() {
        let commit = MemoryCommit::new(
            TrajectoryId::now_v7(),
            ScopeId::now_v7(),
            "q".into(),
            "r".into(),
            "standard".into(),
        )
        .with_estimated_cost(0.05);
        assert_eq!(commit.estimated_cost, Some(0.05));
    }

    #[test]
    fn test_memory_commit_serde_roundtrip() {
        let commit = MemoryCommit::new(
            TrajectoryId::now_v7(),
            ScopeId::now_v7(),
            "query".into(),
            "response".into(),
            "standard".into(),
        )
        .with_tokens(100, 200)
        .with_estimated_cost(0.01);
        let json = serde_json::to_string(&commit).unwrap();
        let d: MemoryCommit = serde_json::from_str(&json).unwrap();
        assert_eq!(d.query, "query");
        assert_eq!(d.total_tokens(), 300);
    }

    // ========================================================================
    // MemoryStats tests
    // ========================================================================

    #[test]
    fn test_memory_stats_default() {
        let stats = MemoryStats::default();
        assert_eq!(stats.total_interactions, 0);
        assert_eq!(stats.total_tokens, 0);
        assert_eq!(stats.total_cost, 0.0);
        assert_eq!(stats.unique_scopes, 0);
        assert!(stats.by_mode.is_empty());
        assert_eq!(stats.avg_tokens_per_interaction, 0);
    }

    // ========================================================================
    // RecallService: recall_decisions, get_scope_history, get_memory_stats
    // ========================================================================

    #[test]
    fn test_recall_decisions_deep_work_mode() {
        let config = make_test_cellstate_config();
        let mut service = RecallService::new(config).unwrap();
        service.add_commit(MemoryCommit::new(
            TrajectoryId::now_v7(),
            ScopeId::now_v7(),
            "architecture".into(),
            "plain response".into(),
            "deep_work".into(),
        ));
        let decisions = service.recall_decisions(None, 10).unwrap();
        assert_eq!(decisions.len(), 1);
        assert_eq!(decisions[0].mode, "deep_work");
    }

    #[test]
    fn test_recall_decisions_keyword_filter() {
        let config = make_test_cellstate_config();
        let mut service = RecallService::new(config).unwrap();
        service.add_commit(MemoryCommit::new(
            TrajectoryId::now_v7(),
            ScopeId::now_v7(),
            "database choice".into(),
            "I recommend PostgreSQL.".into(),
            "standard".into(),
        ));
        let decisions = service.recall_decisions(Some("database"), 10).unwrap();
        assert_eq!(decisions.len(), 1);
        assert!(decisions[0].decision_summary.contains("recommend"));
    }

    #[test]
    fn test_recall_decisions_topic_filter_excludes() {
        let config = make_test_cellstate_config();
        let mut service = RecallService::new(config).unwrap();
        service.add_commit(MemoryCommit::new(
            TrajectoryId::now_v7(),
            ScopeId::now_v7(),
            "database choice".into(),
            "I recommend PostgreSQL.".into(),
            "standard".into(),
        ));
        let decisions = service.recall_decisions(Some("weather"), 10).unwrap();
        assert!(decisions.is_empty());
    }

    #[test]
    fn test_get_scope_history_empty() {
        let config = make_test_cellstate_config();
        let service = RecallService::new(config).unwrap();
        let history = service.get_scope_history(ScopeId::now_v7()).unwrap();
        assert_eq!(history.interaction_count, 0);
        assert_eq!(history.total_tokens, 0);
    }

    #[test]
    fn test_get_scope_history_aggregates() {
        let config = make_test_cellstate_config();
        let mut service = RecallService::new(config).unwrap();
        let scope_id = ScopeId::now_v7();
        for _ in 0..3 {
            service.add_commit(
                MemoryCommit::new(
                    TrajectoryId::now_v7(),
                    scope_id,
                    "q".into(),
                    "r".into(),
                    "standard".into(),
                )
                .with_tokens(50, 100)
                .with_estimated_cost(0.01),
            );
        }
        let history = service.get_scope_history(scope_id).unwrap();
        assert_eq!(history.interaction_count, 3);
        assert_eq!(history.total_tokens, 450);
        assert!((history.total_cost - 0.03).abs() < 1e-10);
    }

    #[test]
    fn test_get_memory_stats_empty() {
        let config = make_test_cellstate_config();
        let service = RecallService::new(config).unwrap();
        let stats = service.get_memory_stats(None).unwrap();
        assert_eq!(stats.total_interactions, 0);
    }

    #[test]
    fn test_get_memory_stats_with_data() {
        let config = make_test_cellstate_config();
        let mut service = RecallService::new(config).unwrap();
        let traj_id = TrajectoryId::now_v7();
        service.add_commit(
            MemoryCommit::new(
                traj_id,
                ScopeId::now_v7(),
                "q".into(),
                "r".into(),
                "standard".into(),
            )
            .with_tokens(100, 200),
        );
        service.add_commit(
            MemoryCommit::new(
                traj_id,
                ScopeId::now_v7(),
                "q2".into(),
                "r2".into(),
                "deep_work".into(),
            )
            .with_tokens(200, 300),
        );
        let stats = service.get_memory_stats(Some(traj_id)).unwrap();
        assert_eq!(stats.total_interactions, 2);
        assert_eq!(stats.total_tokens, 800);
        assert_eq!(stats.unique_scopes, 2);
        assert_eq!(*stats.by_mode.get("standard").unwrap(), 1);
        assert_eq!(*stats.by_mode.get("deep_work").unwrap(), 1);
        assert_eq!(stats.avg_tokens_per_interaction, 400);
    }

    // ========================================================================
    // ValidationResult tests
    // ========================================================================

    #[test]
    fn test_validation_result_valid() {
        let result = ValidationResult::valid();
        assert!(result.valid);
        assert!(result.issues.is_empty());
        assert!(!result.has_critical());
        assert!(!result.has_errors());
    }

    #[test]
    fn test_validation_result_invalid() {
        let result = ValidationResult::invalid(vec![ValidationIssue {
            severity: Severity::Error,
            issue_type: IssueType::StaleData,
            message: "stale".into(),
            entity_id: None,
        }]);
        assert!(!result.valid);
        assert_eq!(result.issues.len(), 1);
        assert!(result.has_errors());
    }

    #[test]
    fn test_validation_result_add_warning_stays_valid() {
        let mut result = ValidationResult::valid();
        result.add_issue(ValidationIssue {
            severity: Severity::Warning,
            issue_type: IssueType::StaleData,
            message: "warning".into(),
            entity_id: None,
        });
        assert!(result.valid); // warnings don't invalidate
        assert_eq!(result.issues.len(), 1);
    }

    #[test]
    fn test_validation_result_add_error_invalidates() {
        let mut result = ValidationResult::valid();
        result.add_issue(ValidationIssue {
            severity: Severity::Error,
            issue_type: IssueType::Contradiction,
            message: "error".into(),
            entity_id: None,
        });
        assert!(!result.valid);
    }

    #[test]
    fn test_validation_result_add_critical_invalidates() {
        let mut result = ValidationResult::valid();
        result.add_issue(ValidationIssue {
            severity: Severity::Critical,
            issue_type: IssueType::CircularDependency,
            message: "critical".into(),
            entity_id: Some(Uuid::now_v7()),
        });
        assert!(!result.valid);
        assert!(result.has_critical());
    }

    #[test]
    fn test_validation_result_issues_of_type() {
        let mut result = ValidationResult::valid();
        result.add_issue(ValidationIssue {
            severity: Severity::Warning,
            issue_type: IssueType::StaleData,
            message: "stale1".into(),
            entity_id: None,
        });
        result.add_issue(ValidationIssue {
            severity: Severity::Warning,
            issue_type: IssueType::MissingReference,
            message: "missing".into(),
            entity_id: None,
        });
        result.add_issue(ValidationIssue {
            severity: Severity::Warning,
            issue_type: IssueType::StaleData,
            message: "stale2".into(),
            entity_id: None,
        });
        let stale = result.issues_of_type(IssueType::StaleData);
        assert_eq!(stale.len(), 2);
    }

    // ========================================================================
    // LintResult tests
    // ========================================================================

    #[test]
    fn test_lint_result_passed() {
        let result = LintResult::passed();
        assert!(result.passed);
        assert!(result.issues.is_empty());
    }

    #[test]
    fn test_lint_result_failed() {
        let result = LintResult::failed(vec![LintIssue {
            issue_type: LintIssueType::TooLarge,
            message: "too big".into(),
            artifact_id: ArtifactId::now_v7(),
        }]);
        assert!(!result.passed);
        assert_eq!(result.issues.len(), 1);
    }

    #[test]
    fn test_lint_result_add_issue() {
        let mut result = LintResult::passed();
        assert!(result.passed);
        result.add_issue(LintIssue {
            issue_type: LintIssueType::LowConfidence,
            message: "low".into(),
            artifact_id: ArtifactId::now_v7(),
        });
        assert!(!result.passed);
        assert_eq!(result.issues.len(), 1);
    }

    // ========================================================================
    // RecoveryResult tests
    // ========================================================================

    #[test]
    fn test_recovery_result_success() {
        let scope = make_test_scope();
        let result = RecoveryResult::success(scope.clone());
        assert!(result.success);
        assert_eq!(result.recovered_scope.unwrap().scope_id, scope.scope_id);
        assert!(result.errors.is_empty());
    }

    #[test]
    fn test_recovery_result_failure() {
        let result = RecoveryResult::failure(vec!["disk full".into()]);
        assert!(!result.success);
        assert!(result.recovered_scope.is_none());
        assert_eq!(result.errors.len(), 1);
    }

    // ========================================================================
    // DosageResult tests
    // ========================================================================

    #[test]
    fn test_dosage_result_within_limits() {
        let result = DosageResult::within_limits();
        assert!(!result.exceeded);
        assert!(result.pruned_artifacts.is_empty());
        assert!(result.warnings.is_empty());
    }

    #[test]
    fn test_dosage_result_exceeded() {
        let mut result = DosageResult::exceeded_limits();
        assert!(result.exceeded);
        let id = ArtifactId::now_v7();
        result.add_pruned(id);
        result.add_warning("over budget".into());
        assert_eq!(result.pruned_artifacts.len(), 1);
        assert_eq!(result.warnings.len(), 1);
    }

    // ========================================================================
    // PCPConfig validation edge cases
    // ========================================================================

    #[test]
    fn test_pcp_config_invalid_negative_checkpoints() {
        let mut config = make_test_pcp_config();
        config.recovery.max_checkpoints = -1;
        assert!(config.validate().is_err());
    }

    #[test]
    fn test_pcp_config_invalid_zero_tokens() {
        let mut config = make_test_pcp_config();
        config.dosage.max_tokens_per_scope = 0;
        assert!(config.validate().is_err());
    }

    #[test]
    fn test_pcp_config_invalid_zero_artifacts() {
        let mut config = make_test_pcp_config();
        config.dosage.max_artifacts_per_scope = 0;
        assert!(config.validate().is_err());
    }

    #[test]
    fn test_pcp_config_invalid_zero_notes() {
        let mut config = make_test_pcp_config();
        config.dosage.max_notes_per_trajectory = 0;
        assert!(config.validate().is_err());
    }

    #[test]
    fn test_pcp_config_invalid_zero_trajectory_depth() {
        let mut config = make_test_pcp_config();
        config.anti_sprawl.max_trajectory_depth = 0;
        assert!(config.validate().is_err());
    }

    #[test]
    fn test_pcp_config_invalid_zero_concurrent_scopes() {
        let mut config = make_test_pcp_config();
        config.anti_sprawl.max_concurrent_scopes = 0;
        assert!(config.validate().is_err());
    }

    #[test]
    fn test_pcp_config_invalid_negative_threshold() {
        let mut config = make_test_pcp_config();
        config.grounding.contradiction_threshold = -0.1;
        assert!(config.validate().is_err());
    }

    #[test]
    fn test_pcp_config_invalid_zero_artifact_size() {
        let mut config = make_test_pcp_config();
        config.linting.max_artifact_size = 0;
        assert!(config.validate().is_err());
    }

    #[test]
    fn test_pcp_config_invalid_confidence_threshold() {
        let mut config = make_test_pcp_config();
        config.linting.min_confidence_threshold = 1.5;
        assert!(config.validate().is_err());
    }

    #[test]
    fn test_pcp_config_invalid_zero_stale_hours() {
        let mut config = make_test_pcp_config();
        config.staleness.stale_hours = 0;
        assert!(config.validate().is_err());
    }

    // ========================================================================
    // Enum serde roundtrips
    // ========================================================================

    #[test]
    fn test_prune_strategy_serde() {
        for s in [
            PruneStrategy::OldestFirst,
            PruneStrategy::LowestRelevance,
            PruneStrategy::Hybrid,
        ] {
            let json = serde_json::to_string(&s).unwrap();
            let d: PruneStrategy = serde_json::from_str(&json).unwrap();
            assert_eq!(d, s);
        }
    }

    #[test]
    fn test_recovery_frequency_serde() {
        for f in [
            RecoveryFrequency::OnScopeClose,
            RecoveryFrequency::OnMutation,
            RecoveryFrequency::Manual,
        ] {
            let json = serde_json::to_string(&f).unwrap();
            let d: RecoveryFrequency = serde_json::from_str(&json).unwrap();
            assert_eq!(d, f);
        }
    }

    #[test]
    fn test_severity_serde() {
        for s in [Severity::Warning, Severity::Error, Severity::Critical] {
            let json = serde_json::to_string(&s).unwrap();
            let d: Severity = serde_json::from_str(&json).unwrap();
            assert_eq!(d, s);
        }
    }

    #[test]
    fn test_issue_type_serde() {
        for t in [
            IssueType::StaleData,
            IssueType::Contradiction,
            IssueType::MissingReference,
            IssueType::DosageExceeded,
            IssueType::CircularDependency,
        ] {
            let json = serde_json::to_string(&t).unwrap();
            let d: IssueType = serde_json::from_str(&json).unwrap();
            assert_eq!(d, t);
        }
    }

    #[test]
    fn test_lint_issue_type_serde() {
        for t in [
            LintIssueType::TooLarge,
            LintIssueType::Duplicate,
            LintIssueType::MissingEmbedding,
            LintIssueType::LowConfidence,
            LintIssueType::SyntaxError,
            LintIssueType::ReservedCharacterLeak,
        ] {
            let json = serde_json::to_string(&t).unwrap();
            let d: LintIssueType = serde_json::from_str(&json).unwrap();
            assert_eq!(d, t);
        }
    }

    // ========================================================================
    // Decision extraction edge cases
    // ========================================================================

    #[test]
    fn test_extract_decision_advise() {
        let response = "I advise caution when deploying.";
        let decision = extract_decision(response);
        assert!(decision.contains("advise"));
    }

    #[test]
    fn test_extract_decision_propose() {
        let response = "I propose we use microservices.";
        let decision = extract_decision(response);
        assert!(decision.contains("propose"));
    }

    #[test]
    fn test_extract_decision_best_approach() {
        let response = "The best approach is to refactor first.";
        let decision = extract_decision(response);
        assert!(decision.contains("best approach"));
    }

    #[test]
    fn test_extract_first_sentence_simple() {
        let text = "First sentence. Second sentence.";
        let result = extract_first_sentence(text);
        assert_eq!(result, "First sentence.");
    }

    #[test]
    fn test_extract_first_sentence_exclamation() {
        let text = "Wow! That's great.";
        let result = extract_first_sentence(text);
        assert_eq!(result, "Wow!");
    }

    #[test]
    fn test_extract_first_sentence_question() {
        let text = "Is this right? Yes.";
        let result = extract_first_sentence(text);
        assert_eq!(result, "Is this right?");
    }

    #[test]
    fn test_extract_first_sentence_long_truncates() {
        let long_text = "a ".repeat(200);
        let result = extract_first_sentence(&long_text);
        assert!(result.ends_with("..."));
    }

    #[test]
    fn test_contains_decision_keywords_true() {
        assert!(contains_decision_keywords("I recommend this"));
        assert!(contains_decision_keywords("You should try"));
        assert!(contains_decision_keywords("The decision was made"));
    }

    #[test]
    fn test_contains_decision_keywords_false() {
        assert!(!contains_decision_keywords("Hello world"));
        assert!(!contains_decision_keywords("The weather is nice"));
    }

    // ========================================================================
    // Markdown semantic lint edge cases
    // ========================================================================

    #[test]
    fn test_lint_markdown_semantics_clean() {
        let issues = lint_markdown_semantics("# Hello\n\nSome text.");
        assert!(issues.is_empty());
    }

    #[test]
    fn test_lint_markdown_semantics_unterminated_fence() {
        let content = "```rust\nfn main() {}\n";
        let issues = lint_markdown_semantics(content);
        assert!(issues
            .iter()
            .any(|i| i.issue_type == LintIssueType::SyntaxError));
    }

    #[test]
    fn test_lint_markdown_semantics_reserved_at_mention() {
        let content = "Please use @my_tool for this.";
        let issues = lint_markdown_semantics(content);
        assert!(issues
            .iter()
            .any(|i| i.issue_type == LintIssueType::ReservedCharacterLeak));
    }

    // ========================================================================
    // Contradiction serde
    // ========================================================================

    #[test]
    fn test_contradiction_serde() {
        let c = Contradiction {
            artifact_a: ArtifactId::now_v7(),
            artifact_b: ArtifactId::now_v7(),
            similarity_score: 0.95,
            description: "Contradictory".into(),
        };
        let json = serde_json::to_string(&c).unwrap();
        let d: Contradiction = serde_json::from_str(&json).unwrap();
        assert_eq!(d.similarity_score, 0.95);
    }

    // ========================================================================
    // CheckpointState / PCPCheckpoint serde
    // ========================================================================

    #[test]
    fn test_checkpoint_state_serde() {
        let state = CheckpointState {
            context_snapshot: b"snapshot".to_vec(),
            artifact_ids: vec![ArtifactId::now_v7()],
            note_ids: vec![NoteId::now_v7()],
        };
        let json = serde_json::to_string(&state).unwrap();
        let d: CheckpointState = serde_json::from_str(&json).unwrap();
        assert_eq!(d.artifact_ids.len(), 1);
        assert_eq!(d.note_ids.len(), 1);
    }

    // ========================================================================
    // PCPRuntime: checkpoint management
    // ========================================================================

    #[test]
    fn test_get_latest_checkpoint_none() {
        let config = make_test_pcp_config();
        let runtime = PCPRuntime::new(config).unwrap();
        assert!(runtime.get_latest_checkpoint(ScopeId::now_v7()).is_none());
    }

    #[test]
    fn test_get_checkpoints_for_scope_empty() {
        let config = make_test_pcp_config();
        let runtime = PCPRuntime::new(config).unwrap();
        assert!(runtime
            .get_checkpoints_for_scope(ScopeId::now_v7())
            .is_empty());
    }

    #[test]
    fn test_delete_checkpoint() {
        let config = make_test_pcp_config();
        let mut runtime = PCPRuntime::new(config).unwrap();
        let scope = make_test_scope();
        let cp = runtime.create_checkpoint(&scope, &[], &[]).unwrap();
        assert!(runtime.delete_checkpoint(cp.checkpoint_id));
        assert!(!runtime.delete_checkpoint(cp.checkpoint_id)); // already deleted
    }

    #[test]
    fn test_clear_checkpoints_for_scope() {
        let config = make_test_pcp_config();
        let mut runtime = PCPRuntime::new(config).unwrap();
        let scope = make_test_scope();
        runtime.create_checkpoint(&scope, &[], &[]).unwrap();
        runtime.create_checkpoint(&scope, &[], &[]).unwrap();
        let cleared = runtime.clear_checkpoints_for_scope(scope.scope_id);
        assert_eq!(cleared, 2);
        assert!(runtime.get_checkpoints_for_scope(scope.scope_id).is_empty());
    }

    #[test]
    fn test_checkpoint_limit_enforcement() {
        let mut config = make_test_pcp_config();
        config.recovery.max_checkpoints = 2;
        let mut runtime = PCPRuntime::new(config).unwrap();
        let scope = make_test_scope();
        runtime.create_checkpoint(&scope, &[], &[]).unwrap();
        runtime.create_checkpoint(&scope, &[], &[]).unwrap();
        runtime.create_checkpoint(&scope, &[], &[]).unwrap();
        // Should have pruned to max_checkpoints
        let cps = runtime.get_checkpoints_for_scope(scope.scope_id);
        assert!(cps.len() <= 2);
    }

    // ========================================================================
    // DecisionRecall / ScopeHistory serde
    // ========================================================================

    #[test]
    fn test_decision_recall_serde() {
        let dr = DecisionRecall {
            commit_id: Uuid::now_v7(),
            query: "q".into(),
            decision_summary: "I recommend X.".into(),
            mode: "standard".into(),
            created_at: Utc::now(),
        };
        let json = serde_json::to_string(&dr).unwrap();
        let d: DecisionRecall = serde_json::from_str(&json).unwrap();
        assert_eq!(d.query, "q");
    }

    #[test]
    fn test_scope_history_serde() {
        let sh = ScopeHistory {
            scope_id: ScopeId::now_v7(),
            interaction_count: 5,
            total_tokens: 1000,
            total_cost: 0.05,
            commits: vec![],
        };
        let json = serde_json::to_string(&sh).unwrap();
        let d: ScopeHistory = serde_json::from_str(&json).unwrap();
        assert_eq!(d.interaction_count, 5);
    }

    #[test]
    fn test_memory_stats_serde() {
        let stats = MemoryStats {
            total_interactions: 10,
            total_tokens: 5000,
            total_cost: 0.50,
            unique_scopes: 3,
            by_mode: HashMap::from([("standard".into(), 7), ("deep_work".into(), 3)]),
            avg_tokens_per_interaction: 500,
        };
        let json = serde_json::to_string(&stats).unwrap();
        let d: MemoryStats = serde_json::from_str(&json).unwrap();
        assert_eq!(d.total_interactions, 10);
        assert_eq!(d.by_mode.len(), 2);
    }

    // -----------------------------------------------------------------------
    // Moved from integration test: battle_intel_e2e.rs
    // -----------------------------------------------------------------------

    fn battle_intel_pcp_config() -> PCPConfig {
        PCPConfig {
            context_dag: ContextDagConfig {
                max_depth: 10,
                prune_strategy: PruneStrategy::OldestFirst,
            },
            recovery: RecoveryConfig {
                enabled: true,
                frequency: RecoveryFrequency::OnScopeClose,
                max_checkpoints: 5,
            },
            dosage: DosageConfig {
                max_tokens_per_scope: 8000,
                max_artifacts_per_scope: 100,
                max_notes_per_trajectory: 500,
            },
            anti_sprawl: AntiSprawlConfig {
                max_trajectory_depth: 5,
                max_concurrent_scopes: 10,
            },
            grounding: GroundingConfig {
                require_artifact_backing: false,
                contradiction_threshold: 0.85,
                conflict_resolution: ConflictResolution::LastWriteWins,
            },
            linting: LintingConfig {
                max_artifact_size: 1024 * 1024,
                min_confidence_threshold: 0.3,
            },
            staleness: StalenessConfig {
                stale_hours: 24 * 30,
            },
        }
    }

    fn battle_intel_runtime() -> PCPRuntime {
        PCPRuntime::new(battle_intel_pcp_config()).expect("PCP runtime creation should succeed")
    }

    fn battle_intel_scope(token_budget: i32, tokens_used: i32, is_active: bool) -> Scope {
        let now = Utc::now();
        Scope {
            scope_id: ScopeId::now_v7(),
            trajectory_id: TrajectoryId::now_v7(),
            parent_scope_id: None,
            name: "test-scope".to_string(),
            purpose: Some("Battle Intel testing".to_string()),
            is_active,
            created_at: now,
            closed_at: if is_active { None } else { Some(now) },
            checkpoint: None,
            token_budget,
            tokens_used,
            metadata: None,
        }
    }

    fn battle_intel_policy(
        name: &str,
        triggers: Vec<SummarizationTrigger>,
        source_level: AbstractionLevel,
        target_level: AbstractionLevel,
    ) -> SummarizationPolicy {
        SummarizationPolicy {
            summarization_policy_id: SummarizationPolicyId::now_v7(),
            name: name.to_string(),
            triggers,
            source_level,
            target_level,
            max_sources: 10,
            create_edges: true,
            created_at: Utc::now(),
            metadata: None,
        }
    }

    #[test]
    fn battle_intel_trigger_turn_count() {
        let runtime = battle_intel_runtime();
        let scope = battle_intel_scope(8000, 1000, true);

        let policy = battle_intel_policy(
            "turn-count-5",
            vec![SummarizationTrigger::TurnCount { count: 5 }],
            AbstractionLevel::Raw,
            AbstractionLevel::Summary,
        );

        let triggered = runtime
            .check_summarization_triggers(&scope, 3, 0, std::slice::from_ref(&policy))
            .expect("trigger check should succeed");
        assert!(triggered.is_empty());

        let triggered = runtime
            .check_summarization_triggers(&scope, 5, 0, std::slice::from_ref(&policy))
            .expect("trigger check should succeed");
        assert_eq!(triggered.len(), 1);
        assert_eq!(triggered[0].0, policy.summarization_policy_id);
        assert_eq!(triggered[0].1, SummarizationTrigger::TurnCount { count: 5 });

        let triggered = runtime
            .check_summarization_triggers(&scope, 7, 0, std::slice::from_ref(&policy))
            .expect("trigger check should succeed");
        assert!(triggered.is_empty());

        let triggered = runtime
            .check_summarization_triggers(&scope, 10, 0, std::slice::from_ref(&policy))
            .expect("trigger check should succeed");
        assert_eq!(triggered.len(), 1);

        let triggered = runtime
            .check_summarization_triggers(&scope, 0, 0, std::slice::from_ref(&policy))
            .expect("trigger check should succeed");
        assert!(triggered.is_empty());
    }

    #[test]
    fn battle_intel_trigger_scope_close() {
        let runtime = battle_intel_runtime();

        let policy = battle_intel_policy(
            "scope-close",
            vec![SummarizationTrigger::ScopeClose],
            AbstractionLevel::Raw,
            AbstractionLevel::Summary,
        );

        let active_scope = battle_intel_scope(8000, 1000, true);
        let triggered = runtime
            .check_summarization_triggers(&active_scope, 5, 2, std::slice::from_ref(&policy))
            .expect("trigger check should succeed");
        assert!(triggered.is_empty());

        let closed_scope = battle_intel_scope(8000, 1000, false);
        let triggered = runtime
            .check_summarization_triggers(&closed_scope, 5, 2, std::slice::from_ref(&policy))
            .expect("trigger check should succeed");
        assert_eq!(triggered.len(), 1);
        assert_eq!(triggered[0].1, SummarizationTrigger::ScopeClose);
    }

    #[test]
    fn battle_intel_trigger_dosage_threshold() {
        let runtime = battle_intel_runtime();

        let policy = battle_intel_policy(
            "dosage-80",
            vec![SummarizationTrigger::DosageThreshold { percent: 80 }],
            AbstractionLevel::Raw,
            AbstractionLevel::Summary,
        );

        let scope_50 = battle_intel_scope(8000, 4000, true);
        let triggered = runtime
            .check_summarization_triggers(&scope_50, 10, 5, std::slice::from_ref(&policy))
            .expect("trigger check should succeed");
        assert!(triggered.is_empty());

        let scope_79 = battle_intel_scope(8000, 6320, true);
        let triggered = runtime
            .check_summarization_triggers(&scope_79, 10, 5, std::slice::from_ref(&policy))
            .expect("trigger check should succeed");
        assert!(triggered.is_empty());

        let scope_80 = battle_intel_scope(8000, 6400, true);
        let triggered = runtime
            .check_summarization_triggers(&scope_80, 10, 5, std::slice::from_ref(&policy))
            .expect("trigger check should succeed");
        assert_eq!(triggered.len(), 1);
        assert_eq!(
            triggered[0].1,
            SummarizationTrigger::DosageThreshold { percent: 80 }
        );

        let scope_100 = battle_intel_scope(8000, 8000, true);
        let triggered = runtime
            .check_summarization_triggers(&scope_100, 10, 5, std::slice::from_ref(&policy))
            .expect("trigger check should succeed");
        assert_eq!(triggered.len(), 1);

        let scope_zero = battle_intel_scope(0, 0, true);
        let triggered = runtime
            .check_summarization_triggers(&scope_zero, 10, 5, std::slice::from_ref(&policy))
            .expect("trigger check should succeed");
        assert!(triggered.is_empty());
    }

    #[test]
    fn battle_intel_manual_never_auto_fires() {
        let runtime = battle_intel_runtime();

        let policy = battle_intel_policy(
            "manual-only",
            vec![SummarizationTrigger::Manual],
            AbstractionLevel::Raw,
            AbstractionLevel::Summary,
        );

        let scenarios: Vec<(Scope, i32, i32, &str)> = vec![
            (
                battle_intel_scope(8000, 0, true),
                0,
                0,
                "empty active scope",
            ),
            (
                battle_intel_scope(8000, 7000, true),
                100,
                50,
                "heavily used active scope",
            ),
            (
                battle_intel_scope(8000, 8000, false),
                200,
                100,
                "maxed out closed scope",
            ),
            (
                battle_intel_scope(0, 0, false),
                0,
                0,
                "zero budget closed scope",
            ),
        ];

        for (scope, turn_count, artifact_count, desc) in scenarios {
            let triggered = runtime
                .check_summarization_triggers(
                    &scope,
                    turn_count,
                    artifact_count,
                    std::slice::from_ref(&policy),
                )
                .expect("trigger check should succeed");
            assert!(
                triggered.is_empty(),
                "Manual trigger should never auto-fire. Scenario: {}",
                desc
            );
        }
    }

    #[test]
    fn battle_intel_abstraction_level_transitions() {
        let runtime = battle_intel_runtime();

        assert!(runtime
            .validate_abstraction_transition(AbstractionLevel::Raw, AbstractionLevel::Summary));
        assert!(runtime.validate_abstraction_transition(
            AbstractionLevel::Summary,
            AbstractionLevel::Principle
        ));
        assert!(runtime
            .validate_abstraction_transition(AbstractionLevel::Raw, AbstractionLevel::Principle));

        assert!(!runtime
            .validate_abstraction_transition(AbstractionLevel::Summary, AbstractionLevel::Raw));
        assert!(!runtime
            .validate_abstraction_transition(AbstractionLevel::Principle, AbstractionLevel::Raw));
        assert!(!runtime.validate_abstraction_transition(
            AbstractionLevel::Principle,
            AbstractionLevel::Summary
        ));

        assert!(
            !runtime.validate_abstraction_transition(AbstractionLevel::Raw, AbstractionLevel::Raw)
        );
        assert!(!runtime
            .validate_abstraction_transition(AbstractionLevel::Summary, AbstractionLevel::Summary));
        assert!(!runtime.validate_abstraction_transition(
            AbstractionLevel::Principle,
            AbstractionLevel::Principle
        ));
    }

    #[test]
    fn battle_intel_multiple_policies_different_triggers() {
        let runtime = battle_intel_runtime();

        let policy_a = battle_intel_policy(
            "turn-count-10",
            vec![SummarizationTrigger::TurnCount { count: 10 }],
            AbstractionLevel::Raw,
            AbstractionLevel::Summary,
        );

        let policy_b = battle_intel_policy(
            "scope-close",
            vec![SummarizationTrigger::ScopeClose],
            AbstractionLevel::Raw,
            AbstractionLevel::Summary,
        );

        let policy_c = battle_intel_policy(
            "dosage-90",
            vec![SummarizationTrigger::DosageThreshold { percent: 90 }],
            AbstractionLevel::Summary,
            AbstractionLevel::Principle,
        );

        let all_policies = vec![policy_a.clone(), policy_b.clone(), policy_c.clone()];

        // Scenario 1: Active scope, turn_count=10, 50% usage -> only Policy A
        let scope_1 = battle_intel_scope(8000, 4000, true);
        let triggered = runtime
            .check_summarization_triggers(&scope_1, 10, 5, &all_policies)
            .expect("trigger check should succeed");
        assert_eq!(triggered.len(), 1);
        assert_eq!(triggered[0].0, policy_a.summarization_policy_id);

        // Scenario 2: Closed scope, turn_count=3, 50% usage -> only Policy B
        let scope_2 = battle_intel_scope(8000, 4000, false);
        let triggered = runtime
            .check_summarization_triggers(&scope_2, 3, 5, &all_policies)
            .expect("trigger check should succeed");
        assert_eq!(triggered.len(), 1);
        assert_eq!(triggered[0].0, policy_b.summarization_policy_id);

        // Scenario 3: Closed scope, turn_count=10, 95% usage -> all three
        let scope_3 = battle_intel_scope(8000, 7600, false);
        let triggered = runtime
            .check_summarization_triggers(&scope_3, 10, 5, &all_policies)
            .expect("trigger check should succeed");
        assert_eq!(triggered.len(), 3);

        let fired_ids: Vec<SummarizationPolicyId> = triggered.iter().map(|(id, _)| *id).collect();
        assert!(fired_ids.contains(&policy_a.summarization_policy_id));
        assert!(fired_ids.contains(&policy_b.summarization_policy_id));
        assert!(fired_ids.contains(&policy_c.summarization_policy_id));

        // Scenario 4: Active scope, turn_count=3, 50% usage -> none
        let scope_4 = battle_intel_scope(8000, 4000, true);
        let triggered = runtime
            .check_summarization_triggers(&scope_4, 3, 5, &all_policies)
            .expect("trigger check should succeed");
        assert!(triggered.is_empty());
    }

    #[test]
    fn battle_intel_prompt_building() {
        let runtime = battle_intel_runtime();

        assert!(runtime
            .validate_abstraction_transition(AbstractionLevel::Raw, AbstractionLevel::Summary));
        assert!(runtime.validate_abstraction_transition(
            AbstractionLevel::Summary,
            AbstractionLevel::Principle
        ));
        assert!(runtime
            .validate_abstraction_transition(AbstractionLevel::Raw, AbstractionLevel::Principle));
    }

    #[test]
    fn battle_intel_trigger_artifact_count() {
        let runtime = battle_intel_runtime();
        let scope = battle_intel_scope(8000, 1000, true);

        let policy = battle_intel_policy(
            "artifact-count-5",
            vec![SummarizationTrigger::ArtifactCount { count: 5 }],
            AbstractionLevel::Raw,
            AbstractionLevel::Summary,
        );

        let triggered = runtime
            .check_summarization_triggers(&scope, 10, 3, std::slice::from_ref(&policy))
            .expect("trigger check should succeed");
        assert!(triggered.is_empty());

        let triggered = runtime
            .check_summarization_triggers(&scope, 10, 5, std::slice::from_ref(&policy))
            .expect("trigger check should succeed");
        assert_eq!(triggered.len(), 1);

        let triggered = runtime
            .check_summarization_triggers(&scope, 10, 10, std::slice::from_ref(&policy))
            .expect("trigger check should succeed");
        assert_eq!(triggered.len(), 1);

        let triggered = runtime
            .check_summarization_triggers(&scope, 10, 6, std::slice::from_ref(&policy))
            .expect("trigger check should succeed");
        assert!(triggered.is_empty());
    }

    #[test]
    fn battle_intel_get_abstraction_transition_from_policy() {
        let runtime = battle_intel_runtime();

        let policy = battle_intel_policy(
            "raw-to-summary",
            vec![SummarizationTrigger::Manual],
            AbstractionLevel::Raw,
            AbstractionLevel::Summary,
        );

        let (source, target) = runtime.get_abstraction_transition(&policy);
        assert_eq!(source, AbstractionLevel::Raw);
        assert_eq!(target, AbstractionLevel::Summary);
    }
}

// ============================================================================
// PROPERTY-BASED TESTS (Task 8.11)
// ============================================================================

#[cfg(test)]
mod prop_tests {
    use super::*;
    use proptest::prelude::*;

    fn make_test_cellstate_config() -> CellstateConfig {
        super::tests::make_test_cellstate_config()
    }

    // Strategy for generating arbitrary queries
    fn arb_query() -> impl Strategy<Value = String> {
        "[a-zA-Z0-9 ]{1,100}".prop_map(|s| s.trim().to_string())
    }

    // Strategy for generating arbitrary responses
    fn arb_response() -> impl Strategy<Value = String> {
        "[a-zA-Z0-9 .,!?]{1,500}".prop_map(|s| s.trim().to_string())
    }

    // Strategy for generating arbitrary modes
    fn arb_mode() -> impl Strategy<Value = String> {
        prop_oneof![
            Just("standard".to_string()),
            Just("deep_work".to_string()),
            Just("super_think".to_string()),
        ]
    }

    // ========================================================================
    // Property 14: Memory commit preserves query/response
    // Feature: cellstate-core-implementation, Property 14: Memory commit preserves query/response
    // Validates: Requirements 10.1, 10.2
    // ========================================================================

    proptest! {
        #![proptest_config(ProptestConfig::with_cases(100))]

        /// Property 14: For any MemoryCommit created with query Q and response R,
        /// recall SHALL return the same Q and R
        #[test]
        fn prop_memory_commit_preserves_query_response(
            query in arb_query(),
            response in arb_response(),
            mode in arb_mode()
        ) {
            let config = make_test_cellstate_config();
            let mut service = RecallService::new(config).expect("RecallService creation should succeed");

            let traj_id = TrajectoryId::now_v7();
            let scope_id = ScopeId::now_v7();

            // Create and add commit
            let commit = MemoryCommit::new(
                traj_id,
                scope_id,
                query.clone(),
                response.clone(),
                mode.clone(),
            );

            service.add_commit(commit);

            // Recall the commit
            let results = service.recall_previous(Some(traj_id), Some(scope_id), 10).expect("recall_previous should succeed");

            // Verify query and response are preserved
            prop_assert!(!results.is_empty(), "Should have at least one result");
            prop_assert_eq!(&results[0].query, &query, "Query should be preserved");
            prop_assert_eq!(&results[0].response, &response, "Response should be preserved");
            prop_assert_eq!(&results[0].mode, &mode, "Mode should be preserved");
        }
    }

    // ========================================================================
    // Property 15: Recall decisions filters correctly
    // Feature: cellstate-core-implementation, Property 15: Recall decisions filters correctly
    // Validates: Requirements 10.1, 10.2
    // ========================================================================

    proptest! {
        #![proptest_config(ProptestConfig::with_cases(100))]

        /// Property 15: For any set of MemoryCommits, recall_decisions() SHALL only return
        /// commits where mode is "deep_work" or "super_think" OR response contains decision keywords
        #[test]
        fn prop_recall_decisions_filters_correctly(
            query in arb_query(),
            mode in arb_mode()
        ) {
            let config = make_test_cellstate_config();
            let mut service = RecallService::new(config).expect("RecallService creation should succeed");

            // Create commits with different modes
            let traj_id = TrajectoryId::now_v7();

            // Add a standard mode commit without decision keywords
            let standard_commit = MemoryCommit::new(
                traj_id,
                ScopeId::now_v7(),
                "simple query".to_string(),
                "simple response without any decision words".to_string(),
                "standard".to_string(),
            );
            service.add_commit(standard_commit);

            // Add a commit with the test mode
            let test_commit = MemoryCommit::new(
                traj_id,
                ScopeId::now_v7(),
                query.clone(),
                "I recommend this approach for the solution.".to_string(),
                mode.clone(),
            );
            service.add_commit(test_commit);

            // Recall decisions
            let decisions = service.recall_decisions(None, 100).expect("recall_decisions should succeed");

            // Verify filtering
            for decision in &decisions {
                let is_decision_mode = decision.mode == "deep_work" || decision.mode == "super_think";
                let has_decision_keywords = contains_decision_keywords(&decision.decision_summary)
                    || contains_decision_keywords(&decision.query);

                // Each returned decision should either be from a decision mode
                // or contain decision keywords
                prop_assert!(
                    is_decision_mode || has_decision_keywords,
                    "Decision should be from decision mode or contain decision keywords. Mode: {}, Summary: {}",
                    decision.mode,
                    decision.decision_summary
                );
            }

            // The key property is: if a commit IS in the results, it must satisfy the filter criteria.
        }
    }

    // ========================================================================
    // Additional Property Tests
    // ========================================================================

    proptest! {
        #![proptest_config(ProptestConfig::with_cases(100))]

        /// Property: Token counts are always non-negative and sum correctly
        #[test]
        fn prop_token_counts_sum_correctly(
            input_tokens in 0i64..1000000,
            output_tokens in 0i64..1000000
        ) {
            let commit = MemoryCommit::new(
                TrajectoryId::now_v7(),
                ScopeId::now_v7(),
                "query".to_string(),
                "response".to_string(),
                "standard".to_string(),
            )
            .with_tokens(input_tokens, output_tokens);

            prop_assert_eq!(commit.total_tokens(), input_tokens + output_tokens);
            prop_assert!(commit.total_tokens() >= 0);
        }

        /// Property: Scope history correctly aggregates commits
        #[test]
        fn prop_scope_history_aggregates_correctly(
            num_commits in 1usize..10
        ) {
            let config = make_test_cellstate_config();
            let mut service = RecallService::new(config).expect("RecallService creation should succeed");

            let scope_id = ScopeId::now_v7();
            let traj_id = TrajectoryId::now_v7();

            // Add commits
            for i in 0..num_commits {
                let commit = MemoryCommit::new(
                    traj_id,
                    scope_id,
                    format!("query {}", i),
                    format!("response {}", i),
                    "standard".to_string(),
                )
                .with_tokens(100, 200);

                service.add_commit(commit);
            }

            // Get scope history
            let history = service.get_scope_history(scope_id).expect("get_scope_history should succeed");

            prop_assert_eq!(history.interaction_count as usize, num_commits);
            prop_assert_eq!(history.total_tokens, (num_commits as i64) * 300);
            prop_assert_eq!(history.commits.len(), num_commits);
        }
    }
}