scc_context/

lib.rs

//! Context Compiler (EPIC-060, docs/CONTEXT_COMPILER.md).
//!
//! Converts a large System IR into the smallest high-recall context pack for
//! an agent task. Packs are structured text with bounded token budgets,
//! evidence status, and warnings. STALE facts never enter trusted sections.

pub mod atlas;
pub mod budget;
pub mod context_ledger;
pub mod packs;
pub mod pagerank;
pub mod rank;
pub mod relevance;
mod repo_path;
pub mod selector;
pub mod skeleton;
pub mod startup;
pub mod structural_source;
pub mod surface;

// The one authoritative surface service (Wave 15.1): re-exported at the
// crate root so every consumer (CLI, MCP, plugin, benchmark ablations)
// routes through `scc_context::build_surface` without reimplementing
// ranking. The `scc_context::surface` module path works identically.
pub use surface::{
    build_surface, build_surface_staged, SurfaceMode, SurfacePipelineStages, SurfacePolicy,
    SurfaceRequest,
};

use scc_core::estimate_tokens;
use scc_graph::{RealityGraph, TrustedGraphView, TrustPolicy};
use scc_store::Store;
use serde::{Deserialize, Serialize};
use std::collections::BTreeMap;

#[derive(Debug, Clone)]
// trace:exempt reason=internal-detail
// trace:v1 id=impl.scc.context work=WORK-SCC-014 satisfies=REQ-SCC-IR
pub struct ContextSettings {
    pub startup_tokens: usize,
    pub task_tokens: usize,
    pub atlas_tokens: usize,
    /// Hard budget for the on-demand detail packs (component/flow/impact/
    /// verify): standalone agent calls, not fused, so a fixed share of a
    /// default startup total keeps them rich but bounded. Receipt: 6000
    /// ≈ 30% of the 20k default total; every pack render guarantees fit.
    pub detail_tokens: usize,
    pub include_low_confidence_inference: bool,
    /// Salt for the task-pack cache: derived from the active ranker
    /// configuration so enabling/disabling embeddings invalidates cached
    /// packs.
    pub rank_salt: String,
    /// Production default is adaptive-priority dropping. FixedRollover is
    /// the inspectable Ripwire-style allocator; do not switch default
    /// without ablation.
    pub pack_allocator: PackAllocator,
}

/// How task packs spend their token budget.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
// trace:exempt reason=internal-detail
pub enum PackAllocator {
    #[default]
    AdaptivePriority,
    FixedRollover,
}

// trace:exempt reason=internal-detail
impl Default for ContextSettings {
    // trace:exempt reason=internal-detail
    fn default() -> Self {
        ContextSettings {
            startup_tokens: 6000,
            task_tokens: 10000,
            atlas_tokens: 15000,
            detail_tokens: 6000,
            include_low_confidence_inference: false,
            rank_salt: String::new(),
            pack_allocator: PackAllocator::AdaptivePriority,
        }
    }
}

#[derive(Debug, Clone, Serialize, Deserialize, schemars::JsonSchema)]
// trace:exempt reason=internal-detail
pub struct ContextPack {
    pub kind: String,
    pub repository_revision: String,
    pub content: String,
    #[serde(default)]
    pub entity_ids: Vec<String>,
    #[serde(default)]
    pub evidence_summary: BTreeMap<String, usize>,
    #[serde(default)]
    pub warnings: Vec<String>,
    #[serde(default)]
    pub tokens: usize,
    #[serde(default)]
    pub budget: usize,
    /// Token count of the full (untruncated) pack, before budget dropping.
    #[serde(default)]
    pub original_tokens: usize,
    /// Sections dropped for budget, by title (never critical sections).
    #[serde(default)]
    pub dropped_sections: Vec<String>,
    /// Content was cut mid-section (never happens for critical sections).
    #[serde(default)]
    pub hard_truncated: bool,
    /// The minimum safe pack exceeds the soft budget: content was NOT
    /// silently truncated; the pack is complete and over budget.
    #[serde(default)]
    pub exceeded_soft_budget: bool,
    /// True when the delivered content differs from the full pack
    /// (dropped sections, hard truncation, or budget overshoot).
    #[serde(default)]
    pub truncated: bool,
    /// RTK output-compression policy hints (docs/API_AND_INTEGRATIONS.md §11):
    /// what to preserve when compressing shell output for the agent.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub compression_policy: Option<serde_json::Value>,
    /// Compact analyzer-health summary (machine-readable). Absent when the
    /// index has not persisted gauges yet.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub analysis_quality: Option<scc_core::AnalysisQuality>,
}

impl ContextPack {
    fn new(kind: &str, revision: &str) -> Self {
        ContextPack {
            kind: kind.to_string(),
            repository_revision: revision.to_string(),
            content: String::new(),
            entity_ids: Vec::new(),
            evidence_summary: BTreeMap::new(),
            warnings: Vec::new(),
            tokens: 0,
            budget: 0,
            original_tokens: 0,
            dropped_sections: Vec::new(),
            hard_truncated: false,
            exceeded_soft_budget: false,
            truncated: false,
            compression_policy: None,
            analysis_quality: None,
        }
    }
}

// trace:exempt reason=internal-detail
pub struct ContextCompiler<'a> {
    pub store: &'a Store,
    /// Trusted view: the only way this compiler may query the reality graph.
    /// STALE facts are excluded and surfaced as warnings; INFERRED facts
    /// below the confidence floor are excluded unless explicitly allowed.
    pub view: TrustedGraphView<'a>,
    pub settings: ContextSettings,
    /// Repository-relative paths whose content hash no longer matches the
    /// indexed snapshot (mirrored from the view for cache-key hashing).
    pub stale_paths: Vec<String>,
    /// All evidence loaded once (single query) — the pack builders consult
    /// this instead of running one SQLite query per evidence id (the atlas
    /// on a 500k-LOC repo has hundreds of thousands of evidence rows).
    evidence: std::cell::RefCell<Option<std::collections::HashMap<String, scc_core::Evidence>>>,
}

// trace:exempt reason=internal-detail
impl<'a> ContextCompiler<'a> {
    pub fn new(
        store: &'a Store,
        graph: &'a RealityGraph,
        settings: ContextSettings,
        stale_paths: Vec<String>,
    ) -> Self {
        // The inferred-confidence floor is governed by
        // `include_low_confidence_inference`: low-confidence labeled
        // inference is excluded from trusted context by default.
        let floor = if settings.include_low_confidence_inference {
            0.0
        } else {
            0.85
        };
        let view = TrustedGraphView::new(
            graph,
            store,
            &stale_paths,
            TrustPolicy::default().with_inferred_floor(floor),
        );
        ContextCompiler {
            store,
            view,
            settings,
            stale_paths,
            evidence: std::cell::RefCell::new(None),
        }
    }

    /// One-query evidence index (id -> Evidence), built lazily. Returns a
    /// borrow so callers never copy the full map (hundreds of thousands of
    /// rows on large repos).
    pub fn evidence_map(&self) -> std::cell::Ref<'_, std::collections::HashMap<String, scc_core::Evidence>> {
        if self.evidence.borrow().is_none() {
            *self.evidence.borrow_mut() = Some(
                self.store
                    .all_evidence()
                    .ok()
                    .map(|evs| evs.into_iter().map(|e| (e.id.clone(), e)).collect())
                    .unwrap_or_default(),
            );
        }
        std::cell::Ref::map(self.evidence.borrow(), |slot| {
            slot.as_ref().expect("set above")
        })
    }

    pub fn revision(&self) -> String {
        self.store
            .latest_snapshot()
            .ok()
            .flatten()
            .map(|s| s.revision)
            .unwrap_or_else(|| "not-indexed".to_string())
    }

    pub fn is_stale_path(&self, path: &str) -> bool {
        self.stale_paths.iter().any(|p| p == path)
    }

    /// Provenance accounting for a set of entity ids.
    pub fn evidence_summary(&self, entity_ids: &[String]) -> BTreeMap<String, usize> {
        let mut m: BTreeMap<String, usize> = BTreeMap::new();
        let evmap = self.evidence_map();
        for id in entity_ids {
            if let Some(e) = self.view.entity(id) {
                for ev_id in &e.evidence {
                    if let Some(ev) = evmap.get(ev_id) {
                        let path = ev.path.clone().unwrap_or_default();
                        if self.is_stale_path(&path) {
                            *m.entry("STALE".into()).or_insert(0) += 1;
                            continue;
                        }
                        let et = match ev.r#type {
                            scc_core::EvidenceType::Source => "SOURCE",
                            scc_core::EvidenceType::Config => "CONFIG",
                            scc_core::EvidenceType::Runtime => "RUNTIME",
                            scc_core::EvidenceType::Test => "TEST",
                            scc_core::EvidenceType::Intent => "INTENT",
                            scc_core::EvidenceType::History => "HISTORY",
                        };
                        *m.entry(et.to_string()).or_insert(0) += 1;
                    }
                }
            }
        }
        for r in self.view.all_rels() {
            if entity_ids.contains(&r.subject)
                && !r.evidence.is_empty() {
                    let key = r.provenance.as_str().to_string();
                    *m.entry(key).or_insert(0) += 1;
                }
        }
        m
    }

    /// Apply the token budget to a pack (P0 rendering contract): the pack
    /// builder has already dropped lowest-priority sections; this records
    /// honest accounting. Critical content is never hard-truncated — if the
    /// minimum safe pack still exceeds the budget, the pack stays complete
    /// and `exceeded_soft_budget` is set instead of silently cutting facts.
    pub fn apply_budget(&mut self, pack: &mut ContextPack, budget: usize) {
        pack.budget = budget;
        if pack.original_tokens == 0 {
            pack.original_tokens = estimate_tokens(&pack.content);
        }
        pack.tokens = estimate_tokens(&pack.content);
        let over = pack.tokens > budget;
        pack.truncated = pack.hard_truncated || !pack.dropped_sections.is_empty() || over;
        if over && !pack.hard_truncated {
            pack.exceeded_soft_budget = true;
        }
    }

    // ---- top-level operations ----

    pub fn system_overview(&self) -> ContextPack {
        packs::overview(self)
    }

    /// Full System Atlas (Wave 2): the startup architecture artifact.
    /// Cached under the model epoch + stale set like task packs — a stale
    /// atlas is never served. The pack render guarantees fit: dropped and
    /// line-truncated sections are recorded, never silent.
    // trace:exempt reason=internal-detail
    pub fn system_atlas(&self, budget: Option<usize>) -> ContextPack {
        self.system_atlas_scoped(budget, atlas::AtlasScope::Production, false)
    }

    /// [`system_atlas`] with an explicit scope. The scope is part of the
    /// cache key: production and full compilations never share entries.
    // trace:v1 id=impl.scc.context.system-atlas-scoped work=WORK-SI-MMMJA4G6 satisfies=REQ-SI-503JSBGP
    pub fn system_atlas_scoped(
        &self,
        budget: Option<usize>,
        scope: atlas::AtlasScope,
        full: bool,
    ) -> ContextPack {
        let budget = budget.unwrap_or(self.settings.atlas_tokens);
        let epoch = self.store.cache_epoch().unwrap_or_else(|_| "no-epoch".into());
        let key = {
            let mut h = blake3::Hasher::new();
            h.update(b"atlas");
            h.update(budget.to_string().as_bytes());
            h.update(format!("{scope:?}").as_bytes());
            h.update(if full { b"full" } else { b"hard" });
            h.update(self.settings.rank_salt.as_bytes());
            h.update(epoch.as_bytes());
            let mut stale: Vec<&String> = self.stale_paths.iter().collect();
            stale.sort();
            for p in stale {
                h.update(p.as_bytes());
                h.update(b"\0");
            }
            format!("atlas:{}", &h.finalize().to_hex()[..20])
        };
        if let Ok(Some(cached)) = self.store.cache_get(&key, &epoch) {
            if let Ok(pack) = serde_json::from_str::<ContextPack>(&cached) {
                return pack;
            }
        }
        let atlas = atlas::build_atlas_scoped(self, scope);
        let pack = atlas::render_atlas(self, &atlas, budget, full);
        if let Ok(json) = serde_json::to_string(&pack) {
            let _ = self.store.cache_put(&key, &json, &epoch);
        }
        pack
    }

    pub fn task_context(
        &self,
        goal: &str,
        files: &[String],
        symbols: &[String],
        token_budget: Option<usize>,
    ) -> ContextPack {
        self.task_context_with_rankers(goal, files, symbols, token_budget, None, None)
    }

    /// `task_context` with optional semantic scorer and reranker (SCC-071).
    // trace:exempt reason=internal-detail
    pub fn task_context_with_rankers(
        &self,
        goal: &str,
        files: &[String],
        symbols: &[String],
        token_budget: Option<usize>,
        scorer: Option<&dyn crate::rank::SemanticScorer>,
        reranker: Option<&dyn crate::rank::Reranker>,
    ) -> ContextPack {
        let budget = token_budget.unwrap_or(self.settings.task_tokens).max(512);
        // Cache (P0 trust contract): keyed by (goal, inputs, budget,
        // ranker salt) + the model epoch + the stale-path set. A file that
        // changed since indexing makes the key differ even without a
        // re-index, so a previously fresh pack can never be served after
        // its evidence is stale.
        let epoch = self.store.cache_epoch().unwrap_or_else(|_| "no-epoch".into());
        let key = {
            let mut h = blake3::Hasher::new();
            h.update(goal.as_bytes());
            for f in files {
                h.update(f.as_bytes());
            }
            for s in symbols {
                h.update(s.as_bytes());
            }
            h.update(budget.to_string().as_bytes());
            h.update(self.settings.rank_salt.as_bytes());
            h.update(match self.settings.pack_allocator {
                PackAllocator::AdaptivePriority => b"alloc:adaptive",
                PackAllocator::FixedRollover => b"alloc:rollover",
            });
            h.update(epoch.as_bytes());
            let mut stale: Vec<&String> = self.stale_paths.iter().collect();
            stale.sort();
            for p in stale {
                h.update(p.as_bytes());
                h.update(b"\0");
            }
            format!("task:{}", &h.finalize().to_hex()[..20])
        };
        if let Ok(Some(cached)) = self.store.cache_get(&key, &epoch) {
            if let Ok(pack) = serde_json::from_str::<ContextPack>(&cached) {
                return pack;
            }
        }
        let pack =
            packs::task_with_rankers(self, goal, files, symbols, budget, scorer, reranker);
        if let Ok(json) = serde_json::to_string(&pack) {
            let _ = self.store.cache_put(&key, &json, &epoch);
        }
        pack
    }

    // trace:exempt reason=internal-detail
    pub fn component_context_full(&self, id: &str) -> ContextPack {
        packs::component(self, id, self.settings.detail_tokens, true)
    }

// trace:exempt reason=internal-detail
    pub fn component_context(&self, id: &str) -> ContextPack {
        packs::component(self, id, self.settings.detail_tokens, false)
    }

    // trace:exempt reason=internal-detail
    pub fn flow_context_full(&self, id: &str) -> ContextPack {
        packs::flow(self, id, self.settings.detail_tokens, true)
    }

// trace:exempt reason=internal-detail
    pub fn flow_context(&self, id: &str) -> ContextPack {
        packs::flow(self, id, self.settings.detail_tokens, false)
    }

    // trace:exempt reason=internal-detail
    pub fn impact_context(
        &self,
        files: &[String],
        symbols: &[String],
        diff_base: Option<&str>,
    ) -> ContextPack {
        packs::impact(self, files, symbols, diff_base, self.settings.detail_tokens, false)
    }

// trace:exempt reason=internal-detail
    pub fn impact_context_full(
        &self,
        files: &[String],
        symbols: &[String],
        diff_base: Option<&str>,
    ) -> ContextPack {
        packs::impact(self, files, symbols, diff_base, self.settings.detail_tokens, true)
    }

    // trace:exempt reason=internal-detail
    pub fn verify_context_full(&self) -> ContextPack {
        packs::verify(self, self.settings.detail_tokens, true)
    }

// trace:exempt reason=internal-detail
    pub fn verify_context(&self) -> ContextPack {
        packs::verify(self, self.settings.detail_tokens, false)
    }
}