harn-hostlib 0.10.143

//! Persistent on-disk snapshot of the workspace index.
//!
//! v2 uses a single JSON file at `.burin/index/snapshot.json` and includes
//! the typed symbol graph. A v1 snapshot cannot safely answer graph queries,
//! so it is rebuilt rather than restored with a measured zero graph.
//!
//! The snapshot is the recovery primitive. On daemon startup, the
//! embedder restores from the snapshot if one exists, then calls
//! [`super::IndexState::reap_after_recovery`] to drop stale agent
//! records and locks before serving any traffic.

use std::collections::HashMap;
use std::io::{self, BufReader, BufWriter, Write};
use std::path::{Path, PathBuf};

use serde::{Deserialize, Serialize};

use super::agents::{AgentRegistry, RegistryConfig, SerializedRegistry};
use super::file_table::{FileId, IndexedFile, IndexedSymbol};
use super::graph::DepGraph;
use super::symbol_graph::{GraphSnapshot, SymbolGraph};
use super::trigram::TrigramIndex;
use super::versions::VersionLog;
use super::words::WordIndex;
use super::IndexState;

/// Current format version. Bumped whenever the snapshot layout changes
/// in a non-additive way.
pub const SNAPSHOT_FORMAT_VERSION: u32 = 2;

/// On-disk metadata header. Small and cheap to read so embedders can
/// peek at a snapshot without parsing the whole thing.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SnapshotMeta {
    /// Format version. Must equal [`SNAPSHOT_FORMAT_VERSION`] for now;
    /// older snapshots are dropped.
    pub format_version: u32,
    /// Workspace root the snapshot was captured against.
    pub workspace_root: String,
    /// `HEAD` SHA of the workspace at snapshot time, when known.
    pub git_head: Option<String>,
    /// Wall-clock ms since the Unix epoch when the snapshot was written.
    pub indexed_at_ms: i64,
    /// Total number of files captured.
    pub file_count: usize,
}

/// Serialised form of one outline symbol. Mirrors [`IndexedSymbol`].
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SnapshotSymbol {
    /// Symbol name.
    pub name: String,
    /// Language-specific kind tag.
    pub kind: String,
    /// Normalized declaration access level when known.
    #[serde(default)]
    pub access_level: Option<String>,
    /// 1-based start line.
    pub start_line: u32,
    /// 1-based inclusive end line.
    pub end_line: u32,
    /// Single-line preview of the declaration.
    pub signature: String,
}

/// Serialised form of one file row. Mirrors [`IndexedFile`].
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SnapshotFile {
    /// Stable file identifier.
    pub id: FileId,
    /// Workspace-relative path with `/` separators.
    pub relative_path: String,
    /// Best-effort language tag.
    pub language: String,
    /// Size in bytes.
    pub size_bytes: u64,
    /// Newline-delimited line count.
    pub line_count: u32,
    /// FNV-1a 64-bit content hash.
    pub content_hash: u64,
    /// Last-modified time (ms since epoch).
    pub mtime_ms: i64,
    /// Outline symbols.
    pub symbols: Vec<SnapshotSymbol>,
    /// Raw import statement strings.
    pub imports: Vec<String>,
}

/// One trigram posting entry: `trigram → list of file ids`.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct TrigramPosting {
    /// Packed trigram key.
    pub trigram: u32,
    /// Files containing this trigram.
    pub files: Vec<FileId>,
}

/// One word posting entry: `word → list of (file, line) pairs`.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct WordPosting {
    /// Identifier-shaped token.
    pub word: String,
    /// All occurrences as `(file_id, line)` pairs.
    pub hits: Vec<(FileId, u32)>,
}

/// One dep-graph row: `file → resolved imports + unresolved raw strings`.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DepRow {
    /// Source file id.
    pub from: FileId,
    /// Resolved target file ids.
    pub to: Vec<FileId>,
    /// Raw import strings the resolver couldn't map back to a file.
    #[serde(default)]
    pub unresolved: Vec<String>,
}

/// Persistent on-disk form of the entire workspace index.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CodeIndexSnapshot {
    /// Snapshot header.
    pub meta: SnapshotMeta,
    /// Next file id to hand out — preserved so reused ids don't collide
    /// with historical version-log entries.
    pub next_file_id: FileId,
    /// File table.
    pub files: Vec<SnapshotFile>,
    /// Trigram postings.
    pub trigrams: Vec<TrigramPosting>,
    /// Word postings.
    pub words: Vec<WordPosting>,
    /// Dep graph rows.
    pub deps: Vec<DepRow>,
    /// Append-only version log.
    pub versions: VersionLog,
    /// Live agents at snapshot time.
    pub agents: SerializedRegistry,
    /// The typed graph. Missing in v1, which must be rebuilt before graph
    /// queries can be served.
    #[serde(default)]
    pub(super) symbols: Option<GraphSnapshot>,
}

impl CodeIndexSnapshot {
    /// Path the snapshot lives at, relative to the workspace root.
    pub fn path_for(workspace_root: &Path) -> PathBuf {
        workspace_root
            .join(".burin")
            .join("index")
            .join("snapshot.json")
    }

    /// Stream to a unique sibling temporary file and atomically replace the
    /// snapshot. Large symbol graphs must not be buffered as another full
    /// serialized copy in process memory, and concurrent writers must not
    /// share one fixed `.tmp` path.
    pub fn save(&self, workspace_root: &Path) -> std::io::Result<()> {
        let path = Self::path_for(workspace_root);
        let parent = path.parent().expect("snapshot path has a parent");
        std::fs::create_dir_all(parent)?;
        let mut tmp = tempfile::NamedTempFile::new_in(parent)?;
        {
            let mut writer = BufWriter::new(tmp.as_file_mut());
            serde_json::to_writer(&mut writer, self).map_err(io::Error::other)?;
            writer.flush()?;
        }
        tmp.persist(&path).map_err(|error| error.error)?;
        Ok(())
    }

    /// Try to load the snapshot from `workspace_root/.burin/index/snapshot.json`.
    /// Returns `Ok(None)` when no snapshot exists yet, the format is
    /// unrecognised, or the snapshot does not describe `workspace_root`
    /// (different checkout or missing graph). Returns `Err` when one
    /// exists but couldn't be parsed (caller is expected to fall back
    /// to `build_from_root`).
    pub fn load(workspace_root: &Path) -> std::io::Result<Option<Self>> {
        let path = Self::path_for(workspace_root);
        if !path.exists() {
            return Ok(None);
        }
        let reader = BufReader::new(std::fs::File::open(&path)?);
        let snap: CodeIndexSnapshot = serde_json::from_reader(reader).map_err(io::Error::other)?;
        if snap.meta.format_version != SNAPSHOT_FORMAT_VERSION {
            tracing::debug!(
                target: "harn_hostlib::code_index",
                path = %path.display(),
                format_version = snap.meta.format_version,
                expected = SNAPSHOT_FORMAT_VERSION,
                "code-index snapshot format mismatch; ignoring",
            );
            return Ok(None);
        }
        if snap.symbols.is_none() || !snapshot_matches_workspace(&snap, workspace_root) {
            return Ok(None);
        }
        Ok(Some(snap))
    }
}

fn snapshot_matches_workspace(snap: &CodeIndexSnapshot, workspace_root: &Path) -> bool {
    let requested = super::state::canonicalize(workspace_root);
    let stored = super::state::canonicalize(Path::new(&snap.meta.workspace_root));
    if stored != requested {
        tracing::info!(
            target: "harn_hostlib::code_index",
            requested = %requested.display(),
            stored = %stored.display(),
            "code-index snapshot workspace root mismatch; ignoring",
        );
        return false;
    }
    // A changed HEAD is a reason to verify file contents, not to discard
    // every unchanged file and rebuild the whole graph. The owning refresh
    // reconciles the snapshot before it can be served.
    true
}

impl IndexState {
    /// Capture the current state as a [`CodeIndexSnapshot`].
    pub fn snapshot(&self) -> CodeIndexSnapshot {
        let files: Vec<SnapshotFile> = self
            .files
            .values()
            .map(|f| SnapshotFile {
                id: f.id,
                relative_path: f.relative_path.clone(),
                language: f.language.clone(),
                size_bytes: f.size_bytes,
                line_count: f.line_count,
                content_hash: f.content_hash,
                mtime_ms: f.mtime_ms,
                symbols: f
                    .symbols
                    .iter()
                    .map(|s| SnapshotSymbol {
                        name: s.name.clone(),
                        kind: s.kind.clone(),
                        access_level: s.access_level.clone(),
                        start_line: s.start_line,
                        end_line: s.end_line,
                        signature: s.signature.clone(),
                    })
                    .collect(),
                imports: f.imports.clone(),
            })
            .collect();

        let trigrams = self.trigrams.snapshot_postings();
        let words = self.words.snapshot_postings();
        let deps = self.deps.snapshot_rows();

        CodeIndexSnapshot {
            meta: SnapshotMeta {
                format_version: SNAPSHOT_FORMAT_VERSION,
                workspace_root: self.root.to_string_lossy().into_owned(),
                git_head: self.git_head.clone(),
                indexed_at_ms: self.last_built_unix_ms,
                file_count: self.files.len(),
            },
            next_file_id: self.next_file_id_internal(),
            files,
            trigrams,
            words,
            deps,
            versions: self.versions.clone(),
            agents: self.agents.snapshot(),
            symbols: Some(self.symbols.snapshot()),
        }
    }

    /// Restore an [`IndexState`] from a snapshot. Callers that loaded the
    /// snapshot for a specific checkout should overwrite [`Self::root`]
    /// with that checkout's canonical path so a stored path string cannot
    /// redirect later persists.
    pub fn from_snapshot(snap: CodeIndexSnapshot) -> io::Result<Self> {
        let root = PathBuf::from(snap.meta.workspace_root);
        let graph =
            SymbolGraph::from_snapshot(snap.symbols.ok_or_else(|| {
                io::Error::new(io::ErrorKind::InvalidData, "missing symbol graph")
            })?)
            .map_err(|message| io::Error::new(io::ErrorKind::InvalidData, message))?;
        let mut files: HashMap<FileId, IndexedFile> = HashMap::with_capacity(snap.files.len());
        let mut path_to_id: HashMap<String, FileId> = HashMap::with_capacity(snap.files.len());
        for f in snap.files {
            let indexed = IndexedFile {
                id: f.id,
                relative_path: f.relative_path.clone(),
                language: f.language,
                size_bytes: f.size_bytes,
                line_count: f.line_count,
                content_hash: f.content_hash,
                mtime_ms: f.mtime_ms,
                symbols: f
                    .symbols
                    .into_iter()
                    .map(|s| IndexedSymbol {
                        name: s.name,
                        kind: s.kind,
                        access_level: s.access_level,
                        start_line: s.start_line,
                        end_line: s.end_line,
                        signature: s.signature,
                    })
                    .collect(),
                imports: f.imports,
            };
            path_to_id.insert(f.relative_path, f.id);
            files.insert(f.id, indexed);
        }
        let trigrams = TrigramIndex::from_postings(snap.trigrams);
        let words = WordIndex::from_postings(snap.words);
        let deps = DepGraph::from_rows(snap.deps);
        let agents = AgentRegistry::from_snapshot(RegistryConfig::default(), snap.agents);

        if graph.file_ids().iter().any(|id| !files.contains_key(id)) {
            return Err(io::Error::new(
                io::ErrorKind::InvalidData,
                "symbol graph names an absent file",
            ));
        }

        let mut state = Self::empty(root);
        state.files = files;
        state.path_to_id = path_to_id;
        state.trigrams = trigrams;
        state.words = words;
        state.deps = deps;
        state.versions = snap.versions;
        state.agents = agents;
        state.symbols = graph;
        state.last_built_unix_ms = snap.meta.indexed_at_ms;
        state.git_head = snap.meta.git_head;
        state.set_next_file_id(snap.next_file_id);
        // Module membership is derived from the path table, not stored:
        // a snapshot that predates a resolver would otherwise restore a
        // stale answer that no refresh with an unchanged path set fixes.
        state.rebuild_module_index();
        Ok(state)
    }

    /// Drop stale agent records and release any locks held by agents
    /// whose `last_seen_ms` is older than the configured timeout. Called
    /// at startup after restoring from a snapshot.
    pub fn reap_after_recovery(&mut self, now_ms: i64) {
        self.agents.reap(now_ms);
    }
}

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

    fn fixture_tree() -> tempfile::TempDir {
        let dir = tempfile::tempdir().expect("tempdir");
        fs::create_dir_all(dir.path().join("src")).unwrap();
        fs::write(
            dir.path().join("src/alpha.rs"),
            "pub fn alpha() -> i32 { 1 }\n",
        )
        .unwrap();
        dir
    }

    fn snapshot_for(dir: &Path) -> CodeIndexSnapshot {
        let (state, _) = IndexState::build_from_root(dir);
        state.snapshot()
    }

    #[test]
    fn load_rejects_snapshot_for_a_different_workspace_root() {
        let dir = fixture_tree();
        let mut snap = snapshot_for(dir.path());
        snap.meta.workspace_root = "/some/other/checkout".to_string();
        snap.save(dir.path()).unwrap();
        assert!(
            CodeIndexSnapshot::load(dir.path()).unwrap().is_none(),
            "a snapshot copied from another checkout must be a miss, not adopted"
        );
    }

    #[test]
    fn load_reconciles_snapshot_when_git_head_does_not_match() {
        let dir = fixture_tree();
        let mut snap = snapshot_for(dir.path());
        snap.meta.git_head = Some("ffffffffffffffff".to_string());
        snap.save(dir.path()).unwrap();
        assert!(
            CodeIndexSnapshot::load(dir.path()).unwrap().is_some(),
            "a changed HEAD requires reconciliation, not a cold rebuild"
        );
    }

    #[test]
    fn load_rejects_a_graphless_v1_snapshot() {
        let dir = fixture_tree();
        let mut snap = snapshot_for(dir.path());
        snap.meta.format_version = 1;
        snap.symbols = None;
        snap.save(dir.path()).unwrap();
        assert!(
            CodeIndexSnapshot::load(dir.path()).unwrap().is_none(),
            "v1 cannot be served with an empty graph"
        );
    }

    #[test]
    fn load_rejects_a_graphless_current_snapshot() {
        let dir = fixture_tree();
        let mut snap = snapshot_for(dir.path());
        snap.symbols = None;
        snap.save(dir.path()).unwrap();
        assert!(CodeIndexSnapshot::load(dir.path()).unwrap().is_none());
    }

    #[test]
    fn restore_refuses_duplicate_graph_node_ids() {
        let dir = fixture_tree();
        let mut snap = snapshot_for(dir.path());
        let graph = snap.symbols.as_mut().unwrap();
        graph.nodes.push(graph.nodes[0].clone());
        let error = IndexState::from_snapshot(snap)
            .err()
            .expect("invalid graph");
        assert_eq!(error.kind(), io::ErrorKind::InvalidData);
    }

    #[test]
    fn load_accepts_snapshot_for_the_same_tree() {
        let dir = fixture_tree();
        let snap = snapshot_for(dir.path());
        snap.save(dir.path()).unwrap();
        let loaded = CodeIndexSnapshot::load(dir.path())
            .unwrap()
            .expect("matching snapshot should restore");
        assert_eq!(loaded.meta.file_count, 1);
    }
}