use std::collections::{BTreeMap, HashMap, HashSet};
use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::{Arc, Mutex, OnceLock, Weak};
use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
use serde::{Deserialize, Serialize};
use tracing::{info, warn};
use crate::domain::{
CatalogEntry, CoverageStatus, FileClassification, FileDisposition, HistoryCoverage,
HistoryLimit, LanguageId, ManifestResourceUsage, ProjectId, ProjectStateDir, ReferenceRecord,
RepositoryFingerprint, RepositoryId, RepositoryManifest, SnapshotSourceIdentity, SourceId,
SourceIdentity, SourceLocation, SourceVersion, StatePlacement, SymbolRecord, WorkingTreeState,
};
use crate::index_lifecycle::snapshot::{
RestoreOutcome, SnapshotRefusal, SnapshotSeed, SnapshotStore, seed_digest,
};
use crate::live_index::store::{
CircuitBreakerState, CodeSignalsSnapshot, IndexLoadSource, IndexedFile, LiveIndex, ParseStatus,
SnapshotVerifyCompletion, SnapshotVerifyProgress, SnapshotVerifyReport, SnapshotVerifyState,
normalize_root,
};
use crate::paths;
use crate::domain::ParseDiagnostic;
const CURRENT_VERSION: u32 = 11;
pub const SNAPSHOT_FORMAT_VERSION: u32 = CURRENT_VERSION;
const INDEX_FILENAME: &str = "index.bin";
const INDEX_TMP_FILENAME: &str = "index.bin.tmp";
const INDEX_TMP_PREFIX: &str = "index.bin.tmp.";
pub const SNAPSHOT_RESET_SCOPE_LABEL: &str = ".symforge/index.bin,.symforge/index.bin.tmp";
pub const CHECKPOINT_INTERVAL_ENV: &str = "SYMFORGE_CHECKPOINT_INTERVAL_SECS";
pub const MIN_CHECKPOINT_INTERVAL_SECS: u64 = 30;
pub const MAX_CHECKPOINT_INTERVAL_SECS: u64 = 3600;
type SnapshotPathLocks = HashMap<PathBuf, Weak<Mutex<()>>>;
static SNAPSHOT_PATH_LOCKS: OnceLock<Mutex<SnapshotPathLocks>> = OnceLock::new();
static SNAPSHOT_TMP_COUNTER: AtomicU64 = AtomicU64::new(0);
fn snapshot_path_and_lock(
state_dir: &ProjectStateDir,
) -> anyhow::Result<(PathBuf, Arc<Mutex<()>>)> {
if !state_dir.as_path().is_absolute() {
anyhow::bail!(
"project state directory must be absolute: {}",
state_dir.as_path().display()
);
}
std::fs::create_dir_all(state_dir.as_path()).map_err(|error| {
anyhow::anyhow!(
"creating project state directory {}: {}",
state_dir.as_path().display(),
error
)
})?;
let canonical_dir = std::fs::canonicalize(state_dir.as_path()).map_err(|error| {
anyhow::anyhow!(
"canonicalizing project state directory {}: {}",
state_dir.as_path().display(),
error
)
})?;
let snapshot_path = canonical_dir.join(INDEX_FILENAME);
let registry = SNAPSHOT_PATH_LOCKS.get_or_init(|| Mutex::new(HashMap::new()));
let mut locks = registry
.lock()
.map_err(|_| anyhow::anyhow!("snapshot path-lock registry poisoned"))?;
locks.retain(|_, lock| lock.strong_count() > 0);
if let Some(lock) = locks.get(&snapshot_path).and_then(Weak::upgrade) {
return Ok((snapshot_path, lock));
}
let lock = Arc::new(Mutex::new(()));
locks.insert(snapshot_path.clone(), Arc::downgrade(&lock));
Ok((snapshot_path, lock))
}
fn next_snapshot_temp_path(dir: &Path) -> PathBuf {
let counter = SNAPSHOT_TMP_COUNTER.fetch_add(1, Ordering::Relaxed);
dir.join(format!(
"{INDEX_TMP_PREFIX}{}.{counter}",
std::process::id()
))
}
fn is_unique_snapshot_temp_name(name: &std::ffi::OsStr) -> bool {
let Some(suffix) = name
.to_str()
.and_then(|name| name.strip_prefix(INDEX_TMP_PREFIX))
else {
return false;
};
let mut parts = suffix.split('.');
let (Some(pid), Some(counter), None) = (parts.next(), parts.next(), parts.next()) else {
return false;
};
!pid.is_empty()
&& !counter.is_empty()
&& pid.bytes().all(|byte| byte.is_ascii_digit())
&& counter.bytes().all(|byte| byte.is_ascii_digit())
}
fn cleanup_snapshot_temp(path: &Path) {
match std::fs::remove_file(path) {
Ok(()) => {}
Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
Err(error) => warn!(
path = %path.display(),
"failed to clean snapshot temp file after write error: {error}"
),
}
}
fn persist_named_tmp(tmp_path: &Path, final_path: &Path, bytes: &[u8]) -> std::io::Result<()> {
if let Err(error) = write_tmp_file_synced(tmp_path, bytes) {
cleanup_snapshot_temp(tmp_path);
return Err(error);
}
if let Err(error) = std::fs::rename(tmp_path, final_path) {
cleanup_snapshot_temp(tmp_path);
return Err(error);
}
note_persist_stage("rename");
#[cfg(unix)]
{
let parent = final_path.parent().ok_or_else(|| {
std::io::Error::new(
std::io::ErrorKind::InvalidInput,
format!("path has no parent directory: {}", final_path.display()),
)
})?;
std::fs::File::open(parent)?.sync_all()?;
}
Ok(())
}
fn write_tmp_file_synced(tmp_path: &Path, bytes: &[u8]) -> std::io::Result<()> {
use std::io::Write;
let mut file = std::fs::File::create(tmp_path)?;
file.write_all(bytes)?;
file.flush()?;
#[cfg(test)]
if FAIL_NAMED_TMP_SYNC_ALL.with(std::cell::Cell::get) {
return Err(std::io::Error::other("simulated sync_all failure"));
}
file.sync_all()?;
note_persist_stage("sync_all");
Ok(())
}
fn note_persist_stage(stage: &'static str) {
#[cfg(test)]
SNAPSHOT_PERSIST_STAGES.with(|cell| {
if let Some(stages) = cell.borrow_mut().as_mut() {
stages.push(stage);
}
});
#[cfg(not(test))]
let _ = stage;
}
#[cfg(test)]
thread_local! {
static SNAPSHOT_PERSIST_STAGES: std::cell::RefCell<Option<Vec<&'static str>>> =
const { std::cell::RefCell::new(None) };
static FAIL_NAMED_TMP_SYNC_ALL: std::cell::Cell<bool> = const { std::cell::Cell::new(false) };
}
fn resolved_snapshot_state<'a>(
source_root: &Path,
placement: &'a StatePlacement,
) -> anyhow::Result<(&'a ProjectStateDir, ProjectId)> {
let canonical_root = dunce::canonicalize(source_root).map_err(|error| {
anyhow::anyhow!(
"canonicalizing snapshot source root {}: {}",
source_root.display(),
error
)
})?;
let expected_id = crate::discovery::project_id_for_canonical_root(&canonical_root);
let directory = match placement {
StatePlacement::ProjectLocal { directory } => directory,
StatePlacement::UserLocal {
directory, root_id, ..
} => {
if root_id != &expected_id {
anyhow::bail!(
"project state placement identity mismatch: expected {}, got {}",
expected_id.0,
root_id.0
);
}
directory
}
StatePlacement::MemoryOnly { .. } => {
anyhow::bail!("project state persistence unavailable: memory-only placement")
}
};
if !directory.as_path().is_absolute() {
anyhow::bail!(
"project state directory must be absolute: {}",
directory.as_path().display()
);
}
Ok((directory, expected_id))
}
#[derive(Serialize, Deserialize)]
pub struct IndexSnapshot {
pub version: u32,
pub project_id: ProjectId,
pub source_identity: SnapshotSourceIdentity,
pub files: HashMap<String, IndexedFileSnapshot>,
pub manifest: RepositoryManifest,
pub code_signals: PersistedCodeSignals,
pub trigrams: super::trigram::PersistedTrigramIndex,
pub dismissal_store_digest: String,
pub dismissal_paths: Vec<String>,
}
#[derive(Clone, Serialize, Deserialize)]
pub struct PersistedCodeSignals {
pub temporal: super::git_temporal::GitTemporalIndex,
pub computed_for_content_generation: u64,
pub computed_for_source_version: SourceVersion,
pub coverage: HistoryCoverage,
}
impl PersistedCodeSignals {
fn from_published(code_signals: &CodeSignalsSnapshot) -> Self {
Self {
temporal: code_signals.temporal.as_ref().clone(),
computed_for_content_generation: code_signals.computed_for_content_generation,
computed_for_source_version: code_signals.computed_for_source_version.clone(),
coverage: code_signals.coverage.as_ref().clone(),
}
}
fn into_published(self) -> CodeSignalsSnapshot {
let state = self.temporal.state.clone();
CodeSignalsSnapshot {
state,
temporal: Arc::new(self.temporal),
computed_for_content_generation: self.computed_for_content_generation,
computed_for_source_version: self.computed_for_source_version,
coverage: Arc::new(self.coverage),
}
}
}
#[derive(Serialize, Deserialize, Clone)]
pub struct IndexedFileSnapshot {
pub relative_path: String,
pub language: LanguageId,
pub classification: FileClassification,
pub content: Vec<u8>,
pub symbols: Vec<SymbolRecord>,
pub parse_status: ParseStatus,
pub parse_diagnostic: Option<ParseDiagnostic>,
pub byte_len: u64,
pub content_hash: String,
pub references: Vec<ReferenceRecord>,
pub alias_map: HashMap<String, String>,
pub mtime_secs: u64,
}
pub struct StatCheckResult {
pub changed: Vec<String>,
pub deleted: Vec<String>,
pub new_files: Vec<String>,
pub discovery_error: Option<String>,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SnapshotResetReport {
removed: Vec<PathBuf>,
missing: Vec<PathBuf>,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SnapshotWriteReport {
pub path: PathBuf,
pub bytes: usize,
pub files: usize,
}
impl SnapshotResetReport {
pub fn removed_count(&self) -> usize {
self.removed.len()
}
pub fn missing_count(&self) -> usize {
self.missing.len()
}
}
fn capture_snapshot_build_input(index: &LiveIndex) -> SnapshotBuildInput {
SnapshotBuildInput {
files: index.files.clone(),
manifest_entries: index.manifest_entries.clone(),
manifest: None,
code_signals: None,
trigrams: index.trigram_index.to_persisted(),
}
}
fn indexed_content_digest<'a>(
files: impl Iterator<Item = (&'a str, &'a [u8])>,
) -> anyhow::Result<String> {
let mut rows: Vec<(String, u64, String)> = files
.map(|(path, content)| {
(
path.to_string(),
content.len() as u64,
crate::hash::digest_hex(content),
)
})
.collect();
rows.sort_by(|left, right| left.0.cmp(&right.0));
let mut identity = b"symforge-snapshot-resident-content-v1\0".to_vec();
identity.extend_from_slice(&postcard::to_stdvec(&rows)?);
Ok(crate::hash::digest_hex(&identity))
}
#[cfg(unix)]
fn native_path_identity_bytes(path: &Path) -> Vec<u8> {
use std::os::unix::ffi::OsStrExt;
path.as_os_str().as_bytes().to_vec()
}
#[cfg(windows)]
fn native_path_identity_bytes(path: &Path) -> Vec<u8> {
use std::os::windows::ffi::OsStrExt;
path.as_os_str()
.encode_wide()
.flat_map(u16::to_le_bytes)
.collect()
}
#[cfg(not(any(unix, windows)))]
fn native_path_identity_bytes(path: &Path) -> Vec<u8> {
path.as_os_str().as_encoded_bytes().to_vec()
}
fn digest_identity_parts(domain: &[u8], parts: &[&[u8]]) -> String {
let mut identity = domain.to_vec();
for part in parts {
identity.extend_from_slice(&(part.len() as u64).to_le_bytes());
identity.extend_from_slice(part);
}
crate::hash::digest_hex(&identity)
}
fn safe_git_ref_name(reference: &git2::Reference<'_>) -> String {
reference
.name()
.ok()
.map(ToOwned::to_owned)
.unwrap_or_else(|| format!("bytes:{}", crate::hash::digest_hex(reference.name_bytes())))
}
fn git_working_tree_state(repository: &git2::Repository) -> WorkingTreeState {
if repository.is_bare() {
return WorkingTreeState::NotApplicable;
}
let mut options = git2::StatusOptions::new();
options
.include_untracked(true)
.recurse_untracked_dirs(true)
.include_ignored(false);
let Ok(statuses) = repository.statuses(Some(&mut options)) else {
return WorkingTreeState::Unknown;
};
let dirty = statuses.iter().any(|entry| {
let path = entry.path_bytes();
path != b".symforge" && !path.starts_with(b".symforge/")
});
if dirty {
WorkingTreeState::Dirty
} else {
WorkingTreeState::Clean
}
}
fn reachable_history_fingerprint(
repository: &git2::Repository,
tip: Option<git2::Oid>,
) -> anyhow::Result<String> {
let mut object_ids = Vec::new();
if let Some(tip) = tip {
let mut walk = repository.revwalk()?;
walk.push(tip)?;
for object_id in walk {
object_ids.push(object_id?.to_string());
}
object_ids.sort();
}
let mut identity = b"symforge-git-reachable-history-v1\0".to_vec();
identity.extend_from_slice(&postcard::to_stdvec(&object_ids)?);
Ok(crate::hash::digest_hex(&identity))
}
pub(crate) fn capture_history_coverage(project_root: &Path) -> HistoryCoverage {
let Ok(repository) = git2::Repository::open(project_root) else {
return HistoryCoverage {
complete_to_root: false,
limitations: vec![HistoryLimit::WorkingTreeOnly],
};
};
if repository.is_shallow() {
HistoryCoverage {
complete_to_root: false,
limitations: vec![HistoryLimit::Shallow],
}
} else if repository.head().is_ok() {
HistoryCoverage {
complete_to_root: true,
limitations: Vec::new(),
}
} else {
HistoryCoverage {
complete_to_root: false,
limitations: vec![HistoryLimit::Unavailable],
}
}
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub(crate) struct CapturedRepositorySource {
pub source: SourceIdentity,
pub source_version: SourceVersion,
pub git_fingerprint: Option<RepositoryFingerprint>,
}
pub(crate) fn capture_repository_source(
project_root: &Path,
project_id: &ProjectId,
) -> anyhow::Result<CapturedRepositorySource> {
let canonical_root = dunce::canonicalize(project_root)?;
let Ok(repository) = git2::Repository::open(&canonical_root) else {
let repository_id = RepositoryId::new(project_id.0.clone());
let worktree_id = digest_identity_parts(
b"symforge-non-git-worktree-id-v1\0",
&[repository_id.as_str().as_bytes()],
);
let source_id = SourceId::new(digest_identity_parts(
b"symforge-non-git-source-id-v1\0",
&[repository_id.as_str().as_bytes(), worktree_id.as_bytes()],
));
return Ok(CapturedRepositorySource {
source: SourceIdentity {
repository_id,
source_id,
location: SourceLocation::WorkingTree { worktree_id },
},
source_version: SourceVersion {
branch: None,
commit: None,
working_tree: WorkingTreeState::NotApplicable,
},
git_fingerprint: None,
});
};
let common_dir = dunce::canonicalize(repository.commondir())?;
let repository_id = RepositoryId::new(digest_identity_parts(
b"symforge-git-repository-id-v1\0",
&[&native_path_identity_bytes(&common_dir)],
));
let worktree_id = digest_identity_parts(
b"symforge-git-worktree-id-v1\0",
&[
repository_id.as_str().as_bytes(),
&native_path_identity_bytes(&canonical_root),
],
);
let source_id = SourceId::new(digest_identity_parts(
b"symforge-git-source-id-v1\0",
&[repository_id.as_str().as_bytes(), worktree_id.as_bytes()],
));
let head = repository.head().ok();
let tip = head.as_ref().and_then(git2::Reference::target);
let selected_ref_or_head = head
.as_ref()
.map(safe_git_ref_name)
.unwrap_or_else(|| "HEAD:unborn".to_string());
let branch = head
.as_ref()
.filter(|reference| reference.is_branch())
.map(safe_git_ref_name);
let commit = tip.map(|object_id| object_id.to_string());
let object_format = match commit.as_deref().map(str::len) {
Some(64) => "sha256",
_ => "sha1",
}
.to_string();
Ok(CapturedRepositorySource {
source: SourceIdentity {
repository_id,
source_id,
location: SourceLocation::WorkingTree { worktree_id },
},
source_version: SourceVersion {
branch,
commit: commit.clone(),
working_tree: git_working_tree_state(&repository),
},
git_fingerprint: Some(RepositoryFingerprint::Git {
object_format,
selected_ref_or_head,
tip_object_id: commit.unwrap_or_default(),
reachable_history_fingerprint: reachable_history_fingerprint(&repository, tip)?,
}),
})
}
fn capture_snapshot_source_identity(
project_root: &Path,
project_id: ProjectId,
manifest_digest: String,
indexed_content_digest: String,
) -> anyhow::Result<SnapshotSourceIdentity> {
let captured = capture_repository_source(project_root, &project_id)?;
Ok(snapshot_source_identity_from_captured(
project_id,
captured,
manifest_digest,
indexed_content_digest,
))
}
fn snapshot_source_identity_from_captured(
project_id: ProjectId,
captured: CapturedRepositorySource,
manifest_digest: String,
indexed_content_digest: String,
) -> SnapshotSourceIdentity {
SnapshotSourceIdentity {
project_id,
repository_id: captured.source.repository_id,
source_id: captured.source.source_id,
source_version: captured.source_version,
repository_fingerprint: captured.git_fingerprint.unwrap_or_else(|| {
RepositoryFingerprint::NonGit {
catalog_identity_digest: manifest_digest.clone(),
}
}),
manifest_digest,
indexed_content_digest,
}
}
fn verify_snapshot_content_integrity(snapshot: &IndexSnapshot) -> anyhow::Result<(String, String)> {
if snapshot.source_identity.project_id != snapshot.project_id {
anyhow::bail!("snapshot header project identity disagrees with its placement identity");
}
let rebuilt_manifest = RepositoryManifest::new(
snapshot.manifest.schema_version,
snapshot.manifest.policy_version,
snapshot.manifest.secret_policy_version,
snapshot.manifest.source.clone(),
snapshot.manifest.source_version.clone(),
snapshot.manifest.coverage,
snapshot.manifest.entries.clone(),
snapshot.manifest.issues.clone(),
snapshot.manifest.usage,
)?;
if rebuilt_manifest.digest != snapshot.manifest.digest {
anyhow::bail!("snapshot manifest digest failed canonical reconstruction");
}
let content_digest = indexed_content_digest(
snapshot
.files
.iter()
.map(|(path, file)| (path.as_str(), file.content.as_slice())),
)?;
Ok((snapshot.manifest.digest.clone(), content_digest))
}
fn verify_snapshot_source_identity(
snapshot: &IndexSnapshot,
project_root: &Path,
) -> anyhow::Result<()> {
let (manifest_digest, content_digest) = verify_snapshot_content_integrity(snapshot)?;
let current = capture_snapshot_source_identity(
project_root,
snapshot.project_id.clone(),
manifest_digest,
content_digest,
)?;
if current != snapshot.source_identity {
anyhow::bail!(
"snapshot source identity, source version, or repository fingerprint no longer matches"
);
}
Ok(())
}
fn verify_snapshot_lineage_continuity(
existing: &IndexSnapshot,
current: &SnapshotSourceIdentity,
project_root: &Path,
) -> anyhow::Result<()> {
if existing.source_identity.repository_id != current.repository_id
|| existing.source_identity.source_id != current.source_id
{
anyhow::bail!("snapshot repository or stable source identity changed");
}
match (
&existing.source_identity.repository_fingerprint,
¤t.repository_fingerprint,
) {
(
RepositoryFingerprint::Git {
object_format: existing_format,
tip_object_id,
..
},
RepositoryFingerprint::Git {
object_format: current_format,
..
},
) => {
if existing_format != current_format {
anyhow::bail!("Git object format changed");
}
if tip_object_id.is_empty() {
if matches!(
¤t.repository_fingerprint,
RepositoryFingerprint::Git { tip_object_id, .. } if tip_object_id.is_empty()
) {
return Ok(());
}
anyhow::bail!("unborn Git source changed before snapshot overwrite");
}
let repository = git2::Repository::open(project_root)?;
let anchor = git2::Oid::from_str(tip_object_id)
.map_err(|_| anyhow::anyhow!("stored Git anchor tip is invalid"))?;
repository.find_commit(anchor).map_err(|_| {
anyhow::anyhow!("stored Git anchor tip is absent from the live object database")
})?;
Ok(())
}
(RepositoryFingerprint::NonGit { .. }, RepositoryFingerprint::NonGit { .. }) => Ok(()),
_ => anyhow::bail!("repository kind changed"),
}
}
fn encode_snapshot(snapshot: &IndexSnapshot) -> anyhow::Result<Vec<u8>> {
let mut bytes = postcard::to_stdvec(snapshot)?;
let checksum = crate::hash::digest(&bytes);
bytes.extend_from_slice(&checksum);
Ok(bytes)
}
fn decode_snapshot(bytes: &[u8]) -> anyhow::Result<IndexSnapshot> {
let payload_len = bytes
.len()
.checked_sub(32)
.ok_or_else(|| anyhow::anyhow!("snapshot checksum missing or truncated"))?;
let (payload, checksum) = bytes.split_at(payload_len);
anyhow::ensure!(
crate::hash::digest(payload).as_slice() == checksum,
"snapshot payload checksum mismatch"
);
Ok(postcard::from_bytes(payload)?)
}
fn serialize_captured_snapshot(
snapshot_input: SnapshotBuildInput,
project_root: &Path,
state_placement: &StatePlacement,
) -> anyhow::Result<SnapshotWriteReport> {
let (state_dir, project_id) = resolved_snapshot_state(project_root, state_placement)?;
let snapshot = build_snapshot(snapshot_input, project_root, project_id)?;
write_snapshot(snapshot, state_dir, project_root)
}
pub fn serialize_shared_index(
shared: &crate::live_index::store::SharedIndex,
project_root: &Path,
state_placement: &StatePlacement,
) -> anyhow::Result<()> {
checkpoint_shared_index(shared, project_root, state_placement).map(|_| ())
}
pub fn checkpoint_shared_index(
shared: &crate::live_index::store::SharedIndex,
project_root: &Path,
state_placement: &StatePlacement,
) -> anyhow::Result<SnapshotWriteReport> {
if crate::knowledge::secret_dismissals::held_dismissals(project_root).is_some() {
crate::live_index::single_file::reconcile_secret_dismissals(shared, project_root);
}
let snapshot_input = {
let published = shared.published_generation();
refuse_unverified_seed(&published.live)?;
if published.manifest.is_none() {
anyhow::bail!(
"refusing to checkpoint an unvouched published generation (no manifest); would overwrite a genuine snapshot"
);
}
SnapshotBuildInput {
files: published.live.files.clone(),
manifest_entries: published.live.manifest_entries.clone(),
manifest: published.manifest.as_deref().cloned(),
code_signals: Some(PersistedCodeSignals::from_published(
published.code_signals.as_ref(),
)),
trigrams: published.live.trigram_index.to_persisted(),
}
};
serialize_captured_snapshot(snapshot_input, project_root, state_placement)
}
fn refuse_unverified_seed(live: &LiveIndex) -> anyhow::Result<()> {
if live.load_source() != IndexLoadSource::SnapshotRestore {
return Ok(());
}
let state = match live.snapshot_verify_state {
SnapshotVerifyState::Pending => "pending",
SnapshotVerifyState::Running(_) => "running",
SnapshotVerifyState::Failed(_) => "failed",
SnapshotVerifyState::NotNeeded | SnapshotVerifyState::Completed(_) => return Ok(()),
};
anyhow::bail!(
"refusing to persist a restored snapshot whose verify is {state}: its rows are not \
verified against disk yet. Retry once the verify completes, as status and health \
report, or run index_folder to rebuild from source."
)
}
pub fn checkpoint_interval_from_value(value: Option<&str>) -> Option<Duration> {
let raw = value?.trim();
if raw.is_empty()
|| raw == "0"
|| raw.eq_ignore_ascii_case("false")
|| raw.eq_ignore_ascii_case("off")
|| raw.eq_ignore_ascii_case("disabled")
{
return None;
}
let seconds = raw.parse::<u64>().ok()?;
if seconds == 0 {
return None;
}
Some(Duration::from_secs(seconds.clamp(
MIN_CHECKPOINT_INTERVAL_SECS,
MAX_CHECKPOINT_INTERVAL_SECS,
)))
}
pub fn checkpoint_interval_from_env() -> Option<Duration> {
checkpoint_interval_from_value(std::env::var(CHECKPOINT_INTERVAL_ENV).ok().as_deref())
}
pub fn reset_snapshot_state(
project_root: &Path,
state_placement: &StatePlacement,
) -> anyhow::Result<SnapshotResetReport> {
let (state_dir, expected_project_id) = resolved_snapshot_state(project_root, state_placement)?;
let (snapshot_path, snapshot_lock) = snapshot_path_and_lock(state_dir)?;
let _reset_guard = snapshot_lock
.lock()
.map_err(|_| anyhow::anyhow!("snapshot path lock poisoned"))?;
if let Ok(existing_bytes) = std::fs::read(&snapshot_path) {
let mismatch = if let Some(version) = peeked_prior_format_version(&existing_bytes) {
Some((
"version-mismatch",
format!("snapshot version {version}, expected {CURRENT_VERSION}"),
))
} else {
match decode_snapshot(&existing_bytes) {
Ok(existing) if existing.version != CURRENT_VERSION => Some((
"version-mismatch",
format!(
"snapshot version {}, expected {}",
existing.version, CURRENT_VERSION
),
)),
Ok(existing)
if existing.manifest.secret_policy_version
!= crate::knowledge::SECRET_POLICY_VERSION =>
{
Some((
"secret-policy-mismatch",
format!(
"snapshot secret policy {}, expected {}",
existing.manifest.secret_policy_version,
crate::knowledge::SECRET_POLICY_VERSION
),
))
}
Ok(existing) if existing.project_id != expected_project_id => Some((
"project-id-mismatch",
format!(
"snapshot project {}, expected {}",
existing.project_id.0, expected_project_id.0
),
)),
Ok(existing) => {
let current = capture_snapshot_source_identity(
project_root,
expected_project_id.clone(),
existing.source_identity.manifest_digest.clone(),
existing.source_identity.indexed_content_digest.clone(),
);
match current.and_then(|current| {
verify_snapshot_lineage_continuity(&existing, ¤t, project_root)
}) {
Ok(()) => None,
Err(error) => Some(("source-lineage-mismatch", error.to_string())),
}
}
Err(error) => Some(("deserialize-error", error.to_string())),
}
};
if let Some((reason, detail)) = mismatch {
let quarantine_path = quarantine_bad_snapshot_locked(
state_dir,
&snapshot_path,
&existing_bytes,
reason,
detail,
)?;
anyhow::bail!(
"refusing to reset foreign or invalid snapshot; preserved at {}",
quarantine_path.display()
);
}
}
let dir = snapshot_path
.parent()
.expect("snapshot path must have a parent directory")
.to_path_buf();
let mut targets = vec![snapshot_path, dir.join(INDEX_TMP_FILENAME)];
let entries = std::fs::read_dir(&dir).map_err(|error| {
anyhow::anyhow!(
"listing snapshot reset directory {}: {}",
dir.display(),
error
)
})?;
for entry in entries {
let entry = entry.map_err(|error| {
anyhow::anyhow!(
"reading snapshot reset directory {}: {}",
dir.display(),
error
)
})?;
if is_unique_snapshot_temp_name(&entry.file_name()) {
targets.push(entry.path());
}
}
targets.sort();
targets.dedup();
let mut removed = Vec::new();
let mut missing = Vec::new();
for target in targets {
match std::fs::remove_file(&target) {
Ok(()) => removed.push(target),
Err(error) if error.kind() == std::io::ErrorKind::NotFound => missing.push(target),
Err(error) => {
return Err(anyhow::anyhow!(
"removing snapshot reset target {}: {}",
target.display(),
error
));
}
}
}
Ok(SnapshotResetReport { removed, missing })
}
pub const ARTIFACT_FILENAME: &str = "index.bin.zst";
pub const ARTIFACT_METADATA_FILENAME: &str = "artifact.json";
const ARTIFACT_TMP_FILENAME: &str = "index.bin.zst.tmp";
const ARTIFACT_BEST_ZSTD_LEVEL: i32 = 9;
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ArtifactExportReport {
pub path: PathBuf,
pub metadata_path: PathBuf,
pub files: usize,
pub raw_bytes: usize,
pub compressed_bytes: usize,
pub content_hash: String,
pub git_visibility: ArtifactGitVisibility,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ArtifactGitVisibility {
AlreadyTracked,
UntrackedVisible,
IgnoredForceAddRequired,
GitVisibilityUnavailable,
}
impl ArtifactGitVisibility {
pub const fn as_str(self) -> &'static str {
match self {
Self::AlreadyTracked => "already_tracked",
Self::UntrackedVisible => "untracked_visible",
Self::IgnoredForceAddRequired => "ignored_force_add_required",
Self::GitVisibilityUnavailable => "git_visibility_unavailable",
}
}
}
fn artifact_git_visibility(project_root: &Path) -> ArtifactGitVisibility {
let relative_path = Path::new(".symforge/index.bin.zst");
let Ok(repository) = git2::Repository::open(project_root) else {
return ArtifactGitVisibility::GitVisibilityUnavailable;
};
let Ok(index) = repository.index() else {
return ArtifactGitVisibility::GitVisibilityUnavailable;
};
if index.get_path(relative_path, 0).is_some() {
return ArtifactGitVisibility::AlreadyTracked;
}
match repository.status_should_ignore(relative_path) {
Ok(true) => ArtifactGitVisibility::IgnoredForceAddRequired,
Ok(false) => ArtifactGitVisibility::UntrackedVisible,
Err(_) => ArtifactGitVisibility::GitVisibilityUnavailable,
}
}
pub struct ArtifactRoundTripReport {
pub files: usize,
pub matched: usize,
pub mismatches: Vec<String>,
pub raw_bytes: usize,
pub compressed_bytes: usize,
}
fn build_compressed_snapshot(
index: &LiveIndex,
project_root: &Path,
) -> anyhow::Result<(IndexSnapshot, Vec<u8>, Vec<u8>)> {
let canonical_root = dunce::canonicalize(project_root)?;
let project_id = crate::discovery::project_id_for_canonical_root(&canonical_root);
let snapshot = build_snapshot(
capture_snapshot_build_input(index),
project_root,
project_id,
)?;
let raw = encode_snapshot(&snapshot)?;
let compressed = zstd::encode_all(raw.as_slice(), ARTIFACT_BEST_ZSTD_LEVEL)?;
Ok((snapshot, raw, compressed))
}
pub fn compress_snapshot(index: &LiveIndex, project_root: &Path) -> anyhow::Result<Vec<u8>> {
Ok(build_compressed_snapshot(index, project_root)?.2)
}
pub fn decompress_artifact_bytes(compressed: &[u8]) -> anyhow::Result<Vec<u8>> {
zstd::decode_all(compressed).map_err(|e| anyhow::anyhow!("zstd decode failed: {e}"))
}
pub fn artifact_round_trip_report(
index: &LiveIndex,
project_root: &Path,
) -> anyhow::Result<ArtifactRoundTripReport> {
let (before, raw, compressed) = build_compressed_snapshot(index, project_root)?;
let decompressed = decompress_artifact_bytes(&compressed)?;
let after = decode_snapshot(&decompressed)?;
let mut matched = 0usize;
let mut mismatches = Vec::new();
for (path, bf) in &before.files {
match after.files.get(path) {
Some(af) if af.content_hash == bf.content_hash => matched += 1,
Some(af) => mismatches.push(format!(
"{path}: {} != {}",
bf.content_hash, af.content_hash
)),
None => mismatches.push(format!("{path}: missing after round-trip")),
}
}
Ok(ArtifactRoundTripReport {
files: before.files.len(),
matched,
mismatches,
raw_bytes: raw.len(),
compressed_bytes: compressed.len(),
})
}
pub fn export_artifact(
index: &LiveIndex,
project_root: &Path,
access_mode: crate::domain::SourceAccessMode,
state_placement: &crate::domain::StatePlacement,
capability: &crate::domain::CapabilityStatus,
) -> anyhow::Result<ArtifactExportReport> {
if !project_root.is_absolute() || !project_root.is_dir() {
anyhow::bail!("team_artifact_export_refused: invalid_project_root");
}
if access_mode != crate::domain::SourceAccessMode::NormalProject {
anyhow::bail!("team_artifact_export_refused: explicit_protected_source");
}
let crate::domain::StatePlacement::ProjectLocal { directory } = state_placement else {
anyhow::bail!("team_artifact_export_refused: non_project_local_placement");
};
if directory.as_path() != paths::resolve_symforge_dir(project_root) {
anyhow::bail!("team_artifact_export_refused: project_state_directory_mismatch");
}
refuse_unverified_seed(index)?;
if let crate::domain::CapabilityStatus::Unavailable { reason } = capability {
anyhow::bail!("team_artifact_export_refused: capability_unavailable:{reason:?}");
}
let git_visibility = artifact_git_visibility(project_root);
let (snapshot, raw, compressed) = build_compressed_snapshot(index, project_root)?;
let file_count = snapshot.files.len();
let content_hash = crate::hash::digest_hex(&raw);
let dir = paths::ensure_symforge_dir(project_root)?;
let final_path = dir.join(ARTIFACT_FILENAME);
let tmp_path = dir.join(ARTIFACT_TMP_FILENAME);
persist_named_tmp(&tmp_path, &final_path, &compressed).map_err(|e| {
anyhow::anyhow!("writing team artifact tmp at {}: {}", tmp_path.display(), e)
})?;
let metadata_path = dir.join(ARTIFACT_METADATA_FILENAME);
let metadata = serde_json::json!({
"content_hash": content_hash,
"raw_bytes": raw.len(),
"compressed_bytes": compressed.len(),
"files": file_count,
});
crate::idempotency::write_bytes_atomic(&metadata_path, &serde_json::to_vec_pretty(&metadata)?)
.map_err(|e| {
anyhow::anyhow!(
"writing team artifact metadata at {}: {}",
metadata_path.display(),
e
)
})?;
ensure_gitattributes_merge_hint(project_root)?;
info!(
bytes = compressed.len(),
files = file_count,
path = %final_path.display(),
"team artifact exported"
);
Ok(ArtifactExportReport {
path: final_path,
metadata_path,
files: file_count,
raw_bytes: raw.len(),
compressed_bytes: compressed.len(),
content_hash,
git_visibility,
})
}
fn ensure_gitattributes_merge_hint(project_root: &Path) -> anyhow::Result<()> {
const HINT_LINE: &str = "*.zst merge=ours";
let path = project_root.join(".gitattributes");
let existing = std::fs::read_to_string(&path).unwrap_or_default();
if existing.lines().any(|line| line.trim() == HINT_LINE) {
return Ok(());
}
let mut updated = existing;
if !updated.is_empty() && !updated.ends_with('\n') {
updated.push('\n');
}
updated.push_str(HINT_LINE);
updated.push('\n');
let authority =
crate::live_index::index_lifecycle::activation::project_source_authority(project_root);
let mut write = authority.acquire_write_serialized().map_err(|refusal| {
anyhow::anyhow!("acquiring write authority for .gitattributes: {refusal:?}")
})?;
let receipt = write
.write(Path::new(".gitattributes"), updated.as_bytes())
.map_err(|refusal| {
anyhow::anyhow!("writing .gitattributes at {}: {refusal:?}", path.display())
})?;
write.finish_committed(receipt).map_err(|refusal| {
anyhow::anyhow!(
"committing .gitattributes at {}: {refusal:?}",
path.display()
)
})?;
Ok(())
}
fn read_artifact_content_hash(metadata_path: &Path) -> Option<String> {
let bytes = std::fs::read(metadata_path).ok()?;
let value: serde_json::Value = serde_json::from_slice(&bytes).ok()?;
value.get("content_hash")?.as_str().map(str::to_string)
}
struct VerifiedArtifact {
snapshot: IndexSnapshot,
artifact_path: std::path::PathBuf,
metadata_path: std::path::PathBuf,
compressed: Vec<u8>,
}
fn read_verified_artifact(project_root: &Path) -> Option<VerifiedArtifact> {
let dir = paths::resolve_symforge_dir(project_root);
let artifact_path = dir.join(ARTIFACT_FILENAME);
let metadata_path = dir.join(ARTIFACT_METADATA_FILENAME);
let compressed = std::fs::read(&artifact_path).ok()?;
let raw = match decompress_artifact_bytes(&compressed) {
Ok(raw) => raw,
Err(e) => {
warn!("failed to decompress team artifact (corrupt zst?): {e}");
try_quarantine_bad_artifact(
project_root,
&artifact_path,
&metadata_path,
&compressed,
"zstd-decode-error",
e.to_string(),
);
return None;
}
};
let Some(expected_hash) = read_artifact_content_hash(&metadata_path) else {
warn!(
path = %artifact_path.display(),
metadata_path = %metadata_path.display(),
"team artifact sidecar missing or unparseable — content_hash unverifiable; quarantining and falling back to a full index build"
);
try_quarantine_bad_artifact(
project_root,
&artifact_path,
&metadata_path,
&compressed,
"missing-sidecar",
format!(
"artifact.json missing or unparseable at {}",
metadata_path.display()
),
);
return None;
};
let actual_hash = crate::hash::digest_hex(&raw);
if actual_hash != expected_hash {
warn!(
"team artifact content_hash mismatch (expected {expected_hash}, got {actual_hash}) — quarantining"
);
try_quarantine_bad_artifact(
project_root,
&artifact_path,
&metadata_path,
&compressed,
"content-hash-mismatch",
format!("expected {expected_hash}, got {actual_hash}"),
);
return None;
}
if let Some(version) = peeked_prior_format_version(&raw) {
warn!(
"team artifact snapshot version mismatch: got {version}, expected {CURRENT_VERSION} — will cold re-index"
);
try_quarantine_bad_artifact(
project_root,
&artifact_path,
&metadata_path,
&compressed,
"version-mismatch",
format!("snapshot version {version}, expected {CURRENT_VERSION}"),
);
return None;
}
match decode_snapshot(&raw) {
Ok(snapshot)
if snapshot.version == CURRENT_VERSION
&& snapshot.manifest.secret_policy_version
!= crate::knowledge::SECRET_POLICY_VERSION =>
{
warn!(
"team artifact secret policy mismatch: got {}, expected {} — will cold re-index",
snapshot.manifest.secret_policy_version,
crate::knowledge::SECRET_POLICY_VERSION
);
try_quarantine_bad_artifact(
project_root,
&artifact_path,
&metadata_path,
&compressed,
"secret-policy-mismatch",
format!(
"snapshot secret policy {}, expected {}",
snapshot.manifest.secret_policy_version,
crate::knowledge::SECRET_POLICY_VERSION
),
);
None
}
Ok(snapshot) if snapshot.version == CURRENT_VERSION => Some(VerifiedArtifact {
snapshot,
artifact_path,
metadata_path,
compressed,
}),
Ok(snapshot) => {
warn!(
"team artifact snapshot version mismatch: got {}, expected {} — will cold re-index",
snapshot.version, CURRENT_VERSION
);
try_quarantine_bad_artifact(
project_root,
&artifact_path,
&metadata_path,
&compressed,
"version-mismatch",
format!(
"snapshot version {}, expected {}",
snapshot.version, CURRENT_VERSION
),
);
None
}
Err(e) => {
warn!("failed to deserialize team artifact (corrupt postcard?): {e}");
try_quarantine_bad_artifact(
project_root,
&artifact_path,
&metadata_path,
&compressed,
"postcard-decode-error",
e.to_string(),
);
None
}
}
}
fn import_artifact(project_root: &Path, expected_project_id: &ProjectId) -> Option<IndexSnapshot> {
let VerifiedArtifact {
snapshot,
artifact_path,
metadata_path,
compressed,
} = read_verified_artifact(project_root)?;
let identity_result = if &snapshot.project_id != expected_project_id {
Err(anyhow::anyhow!(
"team artifact project {}, expected {}",
snapshot.project_id.0,
expected_project_id.0
))
} else {
verify_snapshot_source_identity(&snapshot, project_root)
};
if let Err(error) = identity_result {
warn!(
detail = %error,
"team artifact source identity mismatch; quarantining foreign or stale state"
);
try_quarantine_bad_artifact(
project_root,
&artifact_path,
&metadata_path,
&compressed,
"source-identity-mismatch",
error.to_string(),
);
return None;
}
crate::knowledge::secret_dismissals::set_held_dismissals(
project_root,
crate::knowledge::secret_dismissals::HeldDismissals {
digest: snapshot.dismissal_store_digest.clone(),
paths: snapshot.dismissal_paths.iter().cloned().collect(),
},
);
Some(snapshot)
}
#[non_exhaustive]
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum PortableSnapshotProvenance {
HostBakedImageLayer,
}
static PORTABLE_IMPORT_ATTEMPTED: std::sync::atomic::AtomicBool =
std::sync::atomic::AtomicBool::new(false);
#[cfg(test)]
pub(crate) fn reset_portable_import_guard_for_tests() {
PORTABLE_IMPORT_ATTEMPTED.store(false, std::sync::atomic::Ordering::SeqCst);
}
pub fn import_portable_snapshot(
project_root: &Path,
state_placement: &StatePlacement,
provenance: PortableSnapshotProvenance,
) -> Option<IndexSnapshot> {
if PORTABLE_IMPORT_ATTEMPTED.swap(true, std::sync::atomic::Ordering::SeqCst) {
warn!(
"portable snapshot import refused: already attempted once in this process \
(restore-once policy)"
);
return None;
}
let PortableSnapshotProvenance::HostBakedImageLayer = provenance;
let (_state_dir, expected_project_id) =
resolved_snapshot_state(project_root, state_placement).ok()?;
let VerifiedArtifact { mut snapshot, .. } = read_verified_artifact(project_root)?;
let (manifest_digest, content_digest) = match verify_snapshot_content_integrity(&snapshot) {
Ok(digests) => digests,
Err(error) => {
warn!(detail = %error, "portable snapshot failed root-independent integrity; refusing");
return None;
}
};
if snapshot.source_identity.manifest_digest != manifest_digest
|| snapshot.source_identity.indexed_content_digest != content_digest
{
warn!("portable snapshot header digests disagree with recomputation; refusing");
return None;
}
let current = match capture_snapshot_source_identity(
project_root,
expected_project_id.clone(),
manifest_digest,
content_digest,
) {
Ok(current) => current,
Err(error) => {
warn!(detail = %error, "capturing restoring-root identity failed; refusing portable import");
return None;
}
};
match (
&snapshot.source_identity.repository_fingerprint,
¤t.repository_fingerprint,
) {
(
RepositoryFingerprint::Git {
object_format: baked_format,
tip_object_id: baked_tip,
reachable_history_fingerprint: baked_history,
..
},
RepositoryFingerprint::Git {
object_format: current_format,
tip_object_id: current_tip,
reachable_history_fingerprint: current_history,
..
},
) => {
if baked_format != current_format
|| baked_tip != current_tip
|| baked_history != current_history
{
warn!(
"portable snapshot's git fingerprint does not match the restoring \
workspace (stale bake or wrong provisioning); refusing"
);
return None;
}
}
(RepositoryFingerprint::Git { .. }, _) => {
warn!(
"portable snapshot was git-fingerprinted but the restoring root has no \
git repository; refusing"
);
return None;
}
(RepositoryFingerprint::NonGit { .. }, _) => {}
}
snapshot.project_id = expected_project_id;
snapshot.source_identity = current;
Some(snapshot)
}
fn quarantine_bad_artifact(
project_root: &Path,
artifact_path: &Path,
metadata_path: &Path,
compressed_bytes: &[u8],
reason: &str,
detail: String,
) -> anyhow::Result<PathBuf> {
let dir = paths::ensure_artifact_quarantine_dir(project_root)?;
let hash = crate::hash::digest_hex(compressed_bytes);
let now = SystemTime::now()
.duration_since(UNIX_EPOCH)
.unwrap_or_default();
let name = format!(
"{}-{:09}-{}-{}",
now.as_secs(),
now.subsec_nanos(),
&hash[..16],
reason
);
let quarantine_path = dir.join(format!("{name}.zst"));
let metadata_out_path = dir.join(format!("{name}.json"));
std::fs::write(&quarantine_path, compressed_bytes).map_err(|e| {
anyhow::anyhow!(
"writing quarantined team artifact at {}: {}",
quarantine_path.display(),
e
)
})?;
let quarantine_metadata = serde_json::json!({
"source_path": artifact_path.to_string_lossy(),
"quarantine_path": quarantine_path.to_string_lossy(),
"reason": reason,
"detail": detail,
"sha256": hash,
"bytes": compressed_bytes.len(),
"quarantined_at_unix_seconds": now.as_secs(),
"quarantined_at_unix_nanos": now.subsec_nanos(),
});
let metadata_bytes = serde_json::to_vec_pretty(&quarantine_metadata)?;
std::fs::write(&metadata_out_path, metadata_bytes).map_err(|e| {
anyhow::anyhow!(
"writing team artifact quarantine metadata at {}: {}",
metadata_out_path.display(),
e
)
})?;
match std::fs::remove_file(artifact_path) {
Ok(()) => {}
Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
Err(error) => warn!(
path = %artifact_path.display(),
"failed to remove bad team artifact after quarantine: {error}"
),
}
let _ = std::fs::remove_file(metadata_path);
Ok(quarantine_path)
}
fn try_quarantine_bad_artifact(
project_root: &Path,
artifact_path: &Path,
metadata_path: &Path,
compressed_bytes: &[u8],
reason: &str,
detail: String,
) {
match quarantine_bad_artifact(
project_root,
artifact_path,
metadata_path,
compressed_bytes,
reason,
detail,
) {
Ok(quarantine_path) => warn!(
path = %artifact_path.display(),
quarantine_path = %quarantine_path.display(),
reason = reason,
"bad team artifact quarantined"
),
Err(error) => warn!(
path = %artifact_path.display(),
reason = reason,
"failed to quarantine bad team artifact: {error}"
),
}
}
fn write_snapshot(
snapshot: IndexSnapshot,
state_dir: &ProjectStateDir,
project_root: &Path,
) -> anyhow::Result<SnapshotWriteReport> {
let bytes = encode_snapshot(&snapshot)?;
let file_count = snapshot.files.len();
let (final_path, write_lock) = snapshot_path_and_lock(state_dir)?;
let _write_guard = write_lock
.lock()
.map_err(|_| anyhow::anyhow!("snapshot path lock poisoned"))?;
match std::fs::read(&final_path) {
Ok(existing_bytes) => {
let mismatch = if let Some(version) = peeked_prior_format_version(&existing_bytes) {
Some((
"version-mismatch",
format!("snapshot version {version}, expected {CURRENT_VERSION}"),
))
} else {
match decode_snapshot(&existing_bytes) {
Ok(existing) => {
if existing.version != CURRENT_VERSION {
Some((
"version-mismatch",
format!(
"snapshot version {}, expected {}",
existing.version, CURRENT_VERSION
),
))
} else if existing.project_id != snapshot.project_id {
Some((
"project-id-mismatch",
format!(
"snapshot project {}, expected {}",
existing.project_id.0, snapshot.project_id.0
),
))
} else {
verify_snapshot_lineage_continuity(
&existing,
&snapshot.source_identity,
project_root,
)
.err()
.map(|error| ("source-identity-mismatch", error.to_string()))
}
}
Err(error) => Some(("deserialize-error", error.to_string())),
}
};
if let Some((reason, detail)) = mismatch {
let quarantine_path = quarantine_bad_snapshot_locked(
state_dir,
&final_path,
&existing_bytes,
reason,
detail,
)?;
anyhow::bail!(
"refusing to overwrite foreign or invalid snapshot; preserved at {}",
quarantine_path.display()
);
}
}
Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
Err(error) => {
return Err(anyhow::anyhow!(
"reading existing snapshot identity at {}: {}",
final_path.display(),
error
));
}
}
let dir = final_path
.parent()
.expect("snapshot path must have a parent directory");
let tmp_path = next_snapshot_temp_path(dir);
if let Err(error) = persist_named_tmp(&tmp_path, &final_path, &bytes) {
return Err(anyhow::anyhow!(
"writing index snapshot tmp at {}: {}",
tmp_path.display(),
error
));
}
info!(
bytes = bytes.len(),
files = file_count,
trigram_postings = snapshot.trigrams.posting_count(),
path = %final_path.display(),
"index serialized to project data dir"
);
Ok(SnapshotWriteReport {
path: final_path,
bytes: bytes.len(),
files: file_count,
})
}
fn quarantine_bad_snapshot(
state_dir: &ProjectStateDir,
snapshot_path: &Path,
bytes: &[u8],
reason: &str,
detail: String,
) -> anyhow::Result<PathBuf> {
let (_canonical_snapshot_path, write_lock) = snapshot_path_and_lock(state_dir)?;
let _write_guard = write_lock
.lock()
.map_err(|_| anyhow::anyhow!("snapshot path lock poisoned"))?;
quarantine_bad_snapshot_locked(state_dir, snapshot_path, bytes, reason, detail)
}
fn quarantine_bad_snapshot_locked(
state_dir: &ProjectStateDir,
snapshot_path: &Path,
bytes: &[u8],
reason: &str,
detail: String,
) -> anyhow::Result<PathBuf> {
let dir = state_dir
.as_path()
.join("quarantine")
.join("index-snapshots");
std::fs::create_dir_all(&dir).map_err(|error| {
anyhow::anyhow!(
"creating snapshot quarantine directory {}: {}",
dir.display(),
error
)
})?;
let hash = crate::hash::digest_hex(bytes);
let now = SystemTime::now()
.duration_since(UNIX_EPOCH)
.unwrap_or_default();
let name = format!(
"{}-{:09}-{}-{}",
now.as_secs(),
now.subsec_nanos(),
&hash[..16],
reason
);
let quarantine_path = dir.join(format!("{name}.bin"));
let metadata_path = dir.join(format!("{name}.json"));
std::fs::write(&quarantine_path, bytes).map_err(|e| {
anyhow::anyhow!(
"writing quarantined index snapshot at {}: {}",
quarantine_path.display(),
e
)
})?;
let metadata = serde_json::json!({
"source_path": snapshot_path.to_string_lossy(),
"quarantine_path": quarantine_path.to_string_lossy(),
"reason": reason,
"detail": detail,
"sha256": hash,
"bytes": bytes.len(),
"quarantined_at_unix_seconds": now.as_secs(),
"quarantined_at_unix_nanos": now.subsec_nanos(),
});
let metadata_bytes = serde_json::to_vec_pretty(&metadata)?;
std::fs::write(&metadata_path, metadata_bytes).map_err(|e| {
anyhow::anyhow!(
"writing index snapshot quarantine metadata at {}: {}",
metadata_path.display(),
e
)
})?;
match std::fs::read(snapshot_path) {
Ok(current) if crate::hash::digest_hex(¤t) == hash => {
if let Err(error) = std::fs::remove_file(snapshot_path)
&& error.kind() != std::io::ErrorKind::NotFound
{
warn!(
path = %snapshot_path.display(),
quarantine_path = %quarantine_path.display(),
"failed to remove active bad index snapshot after quarantine: {error}"
);
}
}
Ok(_) => warn!(
path = %snapshot_path.display(),
quarantine_path = %quarantine_path.display(),
"active snapshot changed during quarantine; preserved the newer active bytes"
),
Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
Err(error) => warn!(
path = %snapshot_path.display(),
quarantine_path = %quarantine_path.display(),
"failed to re-read active bad snapshot after quarantine: {error}"
),
}
Ok(quarantine_path)
}
fn try_quarantine_v10_seed(
state_dir: &ProjectStateDir,
snapshot_path: &Path,
bytes: &[u8],
detail: String,
) {
let dir = state_dir
.as_path()
.join("v11")
.join("quarantine")
.join("index-snapshots");
if let Err(error) = std::fs::create_dir_all(&dir) {
warn!(
path = %snapshot_path.display(),
"failed to create v11 seed quarantine directory {}: {error}",
dir.display()
);
return;
}
let hash = crate::hash::digest_hex(bytes);
let hash_marker = format!("-{}-", &hash[..16]);
let already_quarantined = std::fs::read_dir(&dir).is_ok_and(|entries| {
entries
.flatten()
.any(|entry| entry.file_name().to_string_lossy().contains(&hash_marker))
});
if already_quarantined {
return;
}
let now = SystemTime::now()
.duration_since(UNIX_EPOCH)
.unwrap_or_default();
let name = format!(
"{}-{:09}-{}-v10-format-seed",
now.as_secs(),
now.subsec_nanos(),
&hash[..16]
);
let quarantine_path = dir.join(format!("{name}.bin"));
let metadata_path = dir.join(format!("{name}.json"));
if let Err(error) = std::fs::write(&quarantine_path, bytes) {
warn!(
path = %snapshot_path.display(),
"failed to write v10 seed quarantine copy at {}: {error}",
quarantine_path.display()
);
return;
}
let metadata = serde_json::json!({
"source_path": snapshot_path.to_string_lossy(),
"quarantine_path": quarantine_path.to_string_lossy(),
"reason": "v10-format-seed",
"detail": detail,
"sha256": hash,
"bytes": bytes.len(),
"original_preserved": true,
"quarantined_at_unix_seconds": now.as_secs(),
"quarantined_at_unix_nanos": now.subsec_nanos(),
});
match serde_json::to_vec_pretty(&metadata) {
Ok(metadata_bytes) => {
if let Err(error) = std::fs::write(&metadata_path, metadata_bytes) {
warn!(
path = %snapshot_path.display(),
"failed to write v10 seed quarantine metadata at {}: {error}",
metadata_path.display()
);
}
}
Err(error) => warn!(
path = %snapshot_path.display(),
"failed to serialize v10 seed quarantine metadata: {error}"
),
}
warn!(
path = %snapshot_path.display(),
quarantine_path = %quarantine_path.display(),
"prior-format V10 snapshot preserved in place and copied to v11 quarantine; rebuilding"
);
}
fn try_quarantine_bad_snapshot(
state_dir: &ProjectStateDir,
snapshot_path: &Path,
bytes: &[u8],
reason: &str,
detail: String,
) {
match quarantine_bad_snapshot(state_dir, snapshot_path, bytes, reason, detail) {
Ok(quarantine_path) => warn!(
path = %snapshot_path.display(),
quarantine_path = %quarantine_path.display(),
reason = reason,
"bad index snapshot quarantined"
),
Err(error) => warn!(
path = %snapshot_path.display(),
reason = reason,
"failed to quarantine bad index snapshot: {error}"
),
}
}
fn peek_snapshot_version(bytes: &[u8]) -> Option<u32> {
let mut value: u64 = 0;
for i in 0..5 {
let byte = *bytes.get(i)?;
value |= u64::from(byte & 0x7F) << (7 * i);
if byte & 0x80 == 0 {
return u32::try_from(value).ok();
}
}
None
}
fn peeked_prior_format_version(bytes: &[u8]) -> Option<u32> {
let version = peek_snapshot_version(bytes)?;
(version < CURRENT_VERSION).then_some(version)
}
pub fn load_snapshot(
project_root: &Path,
state_placement: &StatePlacement,
) -> Option<IndexSnapshot> {
load_snapshot_with_dismissal_digest(project_root, state_placement, || {
Some(crate::knowledge::secret_dismissals::dismissal_store_digest(
project_root,
))
})
}
#[cfg(feature = "server")]
pub(crate) fn load_snapshot_bound(
project_root: &Path,
state_placement: &StatePlacement,
authority: &crate::index_lifecycle::activation::ProjectSourceAuthority,
) -> Result<Option<IndexSnapshot>, BoundRestoreRefusal> {
let dismissal_digest = admitted_dismissal_store_digest(authority)?;
let snapshot = load_snapshot_with_dismissal_digest(project_root, state_placement, || {
Some(dismissal_digest)
});
authority
.verify_physical_root_anchor()
.map_err(|_| BoundRestoreRefusal::SourceMoved)?;
Ok(snapshot)
}
#[cfg(any(feature = "server", feature = "embed"))]
pub(crate) fn admitted_dismissal_store_digest(
authority: &crate::index_lifecycle::activation::ProjectSourceAuthority,
) -> Result<String, BoundRestoreRefusal> {
use crate::index_lifecycle::physical_root::RootRefusal;
use crate::knowledge::secret_dismissals as dismissals;
authority
.with_source_anchor_read(|lease| {
match crate::index_lifecycle::physical_root::read_regular_beneath(
lease,
Path::new(dismissals::DISMISSAL_STORE_REL),
dismissals::DISMISSAL_STORE_MAX_BYTES as usize,
) {
Ok(bytes) => Ok(bytes
.as_deref()
.map(crate::hash::digest_hex)
.unwrap_or_default()),
Err(RootRefusal::LeaseRevoked) => Err(RootRefusal::LeaseRevoked),
Err(_) => Ok("refused".to_string()),
}
})
.map_err(|_| BoundRestoreRefusal::SourceMoved)
}
#[cfg(feature = "embed")]
pub(crate) fn load_snapshot_with_admitted_dismissals(
project_root: &Path,
state_placement: &StatePlacement,
dismissal_digest: &str,
) -> Option<IndexSnapshot> {
load_snapshot_with_dismissal_digest(project_root, state_placement, || {
Some(dismissal_digest.to_owned())
})
}
fn load_snapshot_with_dismissal_digest(
project_root: &Path,
state_placement: &StatePlacement,
dismissal_digest: impl FnOnce() -> Option<String>,
) -> Option<IndexSnapshot> {
let (state_dir, expected_project_id) =
resolved_snapshot_state(project_root, state_placement).ok()?;
let path = state_dir.as_path().join(INDEX_FILENAME);
let bytes = match std::fs::read(&path) {
Ok(b) => b,
Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
let snapshot = match state_placement {
StatePlacement::ProjectLocal { .. } => {
import_artifact(project_root, &expected_project_id)
}
StatePlacement::UserLocal { .. } | StatePlacement::MemoryOnly { .. } => None,
}?;
return Some(snapshot);
}
Err(_) => {
return None;
}
};
if let Some(version) = peeked_prior_format_version(&bytes) {
warn!(
"index snapshot carries prior format {version} (current {CURRENT_VERSION}) — preserved in place, will re-index"
);
try_quarantine_v10_seed(
state_dir,
&path,
&bytes,
format!("snapshot format {version}, current {CURRENT_VERSION}"),
);
return None;
}
let snapshot: IndexSnapshot = match decode_snapshot(&bytes) {
Ok(s) => s,
Err(e) => {
warn!("failed to deserialize index snapshot (corrupt?): {e}");
try_quarantine_bad_snapshot(
state_dir,
&path,
&bytes,
"deserialize-error",
e.to_string(),
);
return None;
}
};
if snapshot.version != CURRENT_VERSION {
if snapshot.version < CURRENT_VERSION {
warn!(
"index snapshot carries prior format {} (current {}) — preserved in place, will re-index",
snapshot.version, CURRENT_VERSION
);
try_quarantine_v10_seed(
state_dir,
&path,
&bytes,
format!(
"snapshot format {}, current {}",
snapshot.version, CURRENT_VERSION
),
);
return None;
}
warn!(
"index snapshot version mismatch: got {}, expected {} — will re-index",
snapshot.version, CURRENT_VERSION
);
try_quarantine_bad_snapshot(
state_dir,
&path,
&bytes,
"version-mismatch",
format!(
"snapshot version {}, expected {}",
snapshot.version, CURRENT_VERSION
),
);
return None;
}
if snapshot.manifest.secret_policy_version != crate::knowledge::SECRET_POLICY_VERSION {
warn!(
"index snapshot secret policy mismatch: got {}, expected {} — will re-scout",
snapshot.manifest.secret_policy_version,
crate::knowledge::SECRET_POLICY_VERSION
);
try_quarantine_bad_snapshot(
state_dir,
&path,
&bytes,
"secret-policy-mismatch",
format!(
"snapshot secret policy {}, expected {}",
snapshot.manifest.secret_policy_version,
crate::knowledge::SECRET_POLICY_VERSION
),
);
return None;
}
if snapshot.project_id != expected_project_id {
warn!(
expected_project_id = %expected_project_id.0,
actual_project_id = %snapshot.project_id.0,
"index snapshot project identity mismatch — refusing foreign state"
);
try_quarantine_bad_snapshot(
state_dir,
&path,
&bytes,
"project-id-mismatch",
format!(
"snapshot project {}, expected {}",
snapshot.project_id.0, expected_project_id.0
),
);
return None;
}
if let Err(error) = verify_snapshot_source_identity(&snapshot, project_root) {
warn!(
detail = %error,
"index snapshot source identity mismatch — refusing foreign or stale state"
);
try_quarantine_bad_snapshot(
state_dir,
&path,
&bytes,
"source-identity-mismatch",
error.to_string(),
);
return None;
}
if Some(snapshot.dismissal_store_digest.as_str()) != dismissal_digest().as_deref() {
warn!("index snapshot secret dismissals changed — will re-scout");
try_quarantine_bad_snapshot(
state_dir,
&path,
&bytes,
"secret-dismissals-mismatch",
"snapshot secret dismissals differ from the repository's".to_string(),
);
return None;
}
crate::knowledge::secret_dismissals::set_held_dismissals(
project_root,
crate::knowledge::secret_dismissals::HeldDismissals {
digest: snapshot.dismissal_store_digest.clone(),
paths: snapshot.dismissal_paths.iter().cloned().collect(),
},
);
Some(snapshot)
}
pub fn project_local_state_placement(project_root: &Path) -> anyhow::Result<StatePlacement> {
let canonical = dunce::canonicalize(project_root).map_err(|error| {
anyhow::anyhow!(
"canonicalizing project root {}: {}",
project_root.display(),
error
)
})?;
Ok(StatePlacement::ProjectLocal {
directory: crate::domain::ProjectStateDir::new(crate::paths::resolve_symforge_dir(
&canonical,
)),
})
}
pub fn load_snapshot_for_root(project_root: &Path) -> Option<IndexSnapshot> {
let placement = project_local_state_placement(project_root).ok()?;
load_snapshot(project_root, &placement)
}
pub fn snapshot_compatible(project_root: &Path) -> bool {
load_snapshot_for_root(project_root).is_some()
}
fn snapshot_entry_source_id(path: &str) -> u64 {
path.as_bytes()
.iter()
.fold(0xcbf2_9ce4_8422_2325_u64, |acc, byte| {
acc.wrapping_mul(0x0100_0000_01b3)
.wrapping_add(u64::from(*byte))
})
}
fn snapshot_entry_stamp(content_hash: &str) -> u64 {
content_hash
.as_bytes()
.iter()
.fold(0xcbf2_9ce4_8422_2325_u64, |acc, byte| {
acc.wrapping_mul(0x0100_0000_01b3)
.wrapping_add(u64::from(*byte))
})
}
fn resolve_snapshot_restore_wire(project_root: &Path) -> Option<Vec<u8>> {
let placement = project_local_state_placement(project_root).ok()?;
let (state_dir, _) = resolved_snapshot_state(project_root, &placement).ok()?;
let path = state_dir.as_path().join(INDEX_FILENAME);
if let Ok(bytes) = std::fs::read(&path) {
return Some(bytes);
}
let verified = read_verified_artifact(project_root)?;
decompress_artifact_bytes(&verified.compressed).ok()
}
fn snapshot_restore_wire_declared_len(wire_bytes: Option<&[u8]>) -> u64 {
wire_bytes.map(|bytes| bytes.len() as u64).unwrap_or(0)
}
fn build_snapshot_seed_from_index(
snapshot: &IndexSnapshot,
declared_len: u64,
) -> (SnapshotSeed, BTreeMap<u64, String>) {
let mut paths: Vec<&String> = snapshot.files.keys().collect();
paths.sort();
let mut entries = Vec::with_capacity(paths.len());
let mut source_to_path = BTreeMap::new();
for path in paths {
let file = &snapshot.files[path.as_str()];
let source = snapshot_entry_source_id(path);
let stamp = snapshot_entry_stamp(&file.content_hash);
source_to_path.insert(source, path.clone());
entries.push((source, stamp));
}
let seed = SnapshotSeed {
version: snapshot.version,
declared_len,
root_digest: seed_digest(&entries),
entries,
opaque_note: Vec::new(),
};
(seed, source_to_path)
}
fn try_quarantine_snapshot_restore_wire(
project_root: &Path,
wire_bytes: &[u8],
reason: &str,
detail: String,
) {
let Ok(placement) = project_local_state_placement(project_root) else {
return;
};
let Ok((state_dir, _)) = resolved_snapshot_state(project_root, &placement) else {
return;
};
let index_path = state_dir.as_path().join(INDEX_FILENAME);
if index_path.exists() {
try_quarantine_bad_snapshot(state_dir, &index_path, wire_bytes, reason, detail.clone());
return;
}
if let Some(VerifiedArtifact {
artifact_path,
metadata_path,
compressed,
..
}) = read_verified_artifact(project_root)
{
try_quarantine_bad_artifact(
project_root,
&artifact_path,
&metadata_path,
&compressed,
reason,
detail,
);
}
}
fn snapshot_restore_decode_capacity(snapshot: &IndexSnapshot, wire_len: u64) -> u64 {
let usage = &snapshot.manifest.usage;
wire_len
.saturating_add(usage.catalog_metadata_bytes)
.saturating_add(snapshot.files.len() as u64 * 16)
.max(wire_len)
}
#[cfg(test)]
fn prove_snapshot_entry_on_disk(
project_root: &Path,
source_to_path: &BTreeMap<u64, String>,
files: &HashMap<String, IndexedFileSnapshot>,
source: u64,
stamp: u64,
) -> bool {
let Some(path) = source_to_path.get(&source) else {
return false;
};
let Some(file) = files.get(path.as_str()) else {
return false;
};
if snapshot_entry_stamp(&file.content_hash) != stamp {
return false;
}
let abs_path = project_root.join(path.replace('/', std::path::MAIN_SEPARATOR_STR));
let Ok(bytes) = std::fs::read(&abs_path) else {
return false;
};
crate::hash::digest_hex(&bytes) == file.content_hash
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub(crate) struct SnapshotRestoreProof {
pub outcome: Result<RestoreOutcome, SnapshotRefusal>,
pub rebuild_required: bool,
}
fn run_snapshot_store_restore_proof(
snapshot: &IndexSnapshot,
project_root: &Path,
wire_bytes: Option<&[u8]>,
) -> SnapshotRestoreProof {
run_snapshot_store_restore_proof_with(snapshot, project_root, wire_bytes, |path, file| {
let abs_path = project_root.join(path.replace('/', std::path::MAIN_SEPARATOR_STR));
std::fs::read(abs_path)
.is_ok_and(|bytes| crate::hash::digest_hex(&bytes) == file.content_hash)
})
}
fn run_snapshot_store_restore_proof_with(
snapshot: &IndexSnapshot,
project_root: &Path,
wire_bytes: Option<&[u8]>,
prove_file: impl Fn(&str, &IndexedFileSnapshot) -> bool,
) -> SnapshotRestoreProof {
let owned_wire_bytes;
let wire_bytes = match wire_bytes {
Some(bytes) => Some(bytes),
None => {
owned_wire_bytes = resolve_snapshot_restore_wire(project_root);
owned_wire_bytes.as_deref()
}
};
if let Err(error) = verify_snapshot_source_identity(snapshot, project_root) {
warn!(
detail = %error,
"snapshot restore proof refused: source identity or indexed content integrity mismatch"
);
if let Some(wire_bytes) = wire_bytes {
try_quarantine_snapshot_restore_wire(
project_root,
wire_bytes,
"snapshot-store-integrity",
error.to_string(),
);
}
let unproven = snapshot.files.len();
return SnapshotRestoreProof {
outcome: Ok(RestoreOutcome::SeedRejected { unproven }),
rebuild_required: unproven > 0,
};
}
let declared_len = snapshot_restore_wire_declared_len(wire_bytes);
let (seed, source_to_path) = build_snapshot_seed_from_index(snapshot, declared_len);
let limit = snapshot_restore_decode_capacity(snapshot, declared_len);
let files = &snapshot.files;
let mut store = SnapshotStore::new();
let outcome = store.restore(
seed,
limit,
|entry| *entry,
|source, stamp| {
let Some(path) = source_to_path.get(&source) else {
return false;
};
let Some(file) = files.get(path.as_str()) else {
return false;
};
snapshot_entry_stamp(&file.content_hash) == stamp && prove_file(path, file)
},
);
let rebuild_required = store.rebuild_required() || outcome.is_err();
for line in store.diagnostics() {
info!("snapshot restore proof: {line}");
}
if let Ok(RestoreOutcome::Quarantined { id }) = &outcome {
warn!(
quarantine_id = id,
"snapshot restore proof quarantined seed integrity failure"
);
if let Some(wire_bytes) = wire_bytes {
try_quarantine_snapshot_restore_wire(
project_root,
wire_bytes,
"snapshot-store-digest-mismatch",
format!("SnapshotStore quarantine id {id}"),
);
}
} else if rebuild_required {
warn!(
outcome = ?outcome,
promoted_sources = store.current().len(),
"snapshot restore proof latched rebuild fallback; hydrated seed kept for background_verify"
);
}
SnapshotRestoreProof {
outcome,
rebuild_required,
}
}
#[cfg(any(feature = "server", feature = "embed"))]
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) enum BoundRestoreRefusal {
SourceMoved,
SourceReadRefused,
}
#[cfg(any(feature = "server", feature = "embed"))]
fn run_snapshot_store_restore_proof_bound(
snapshot: &IndexSnapshot,
project_root: &Path,
authority: &crate::index_lifecycle::activation::ProjectSourceAuthority,
) -> Result<SnapshotRestoreProof, BoundRestoreRefusal> {
authority
.verify_physical_root_anchor()
.map_err(|_| BoundRestoreRefusal::SourceMoved)?;
let read_refused = std::cell::Cell::new(false);
let proof =
run_snapshot_store_restore_proof_with(snapshot, project_root, None, |path, file| {
let max_bytes = file.content.len();
match authority.with_source_anchor_read(|lease| {
crate::index_lifecycle::physical_root::read_regular_beneath(
lease,
Path::new(path),
max_bytes,
)
}) {
Ok(Some(bytes)) => crate::hash::digest_hex(&bytes) == file.content_hash,
Ok(None) => false,
Err(_) => {
read_refused.set(true);
false
}
}
});
authority
.verify_physical_root_anchor()
.map_err(|_| BoundRestoreRefusal::SourceMoved)?;
if read_refused.get() {
return Err(BoundRestoreRefusal::SourceReadRefused);
}
Ok(proof)
}
#[cfg(test)]
pub(crate) fn snapshot_store_restore_proof_for_test(
snapshot: &IndexSnapshot,
project_root: &Path,
wire_bytes: Option<&[u8]>,
) -> SnapshotRestoreProof {
run_snapshot_store_restore_proof(snapshot, project_root, wire_bytes)
}
pub fn snapshot_to_live_index(snapshot: IndexSnapshot, project_root: &Path) -> LiveIndex {
snapshot_to_live_index_with_code_signals(snapshot, project_root).0
}
pub fn snapshot_to_live_index_with_code_signals(
snapshot: IndexSnapshot,
project_root: &Path,
) -> (LiveIndex, CodeSignalsSnapshot) {
let proof = run_snapshot_store_restore_proof(&snapshot, project_root, None);
hydrate_snapshot_with_proof(snapshot, project_root, proof)
}
#[cfg(any(feature = "server", feature = "embed"))]
pub(crate) fn snapshot_to_live_index_with_code_signals_bound(
snapshot: IndexSnapshot,
project_root: &Path,
authority: &crate::index_lifecycle::activation::ProjectSourceAuthority,
) -> Result<(LiveIndex, CodeSignalsSnapshot), BoundRestoreRefusal> {
let proof = run_snapshot_store_restore_proof_bound(&snapshot, project_root, authority)?;
let restored = hydrate_snapshot_with_proof(snapshot, project_root, proof);
authority
.verify_physical_root_anchor()
.map_err(|_| BoundRestoreRefusal::SourceMoved)?;
Ok(restored)
}
fn hydrate_snapshot_with_proof(
snapshot: IndexSnapshot,
project_root: &Path,
proof: SnapshotRestoreProof,
) -> (LiveIndex, CodeSignalsSnapshot) {
if proof.rebuild_required {
debug_assert!(
matches!(
proof.outcome,
Ok(RestoreOutcome::SeedRejected { .. })
| Ok(RestoreOutcome::Quarantined { .. })
| Err(_)
),
"rebuild_required must accompany a rejected, quarantined, or refused restore"
);
} else if let Ok(RestoreOutcome::Promoted { sources }) = &proof.outcome {
debug_assert!(
sources > &0 || snapshot.files.is_empty(),
"Promoted restore must prove every entry via SnapshotStore"
);
}
let IndexSnapshot {
files: snapshot_files,
manifest,
code_signals,
trigrams,
..
} = snapshot;
let manifest_entries = manifest.entries;
let mut files: HashMap<String, Arc<IndexedFile>> = HashMap::with_capacity(snapshot_files.len());
let phase = Instant::now();
for (path, snap_file) in snapshot_files {
let indexed_file = IndexedFile {
relative_path: snap_file.relative_path,
language: snap_file.language,
classification: snap_file.classification,
content: snap_file.content,
symbols: snap_file.symbols,
parse_status: snap_file.parse_status,
parse_diagnostic: snap_file.parse_diagnostic,
byte_len: snap_file.byte_len,
content_hash: snap_file.content_hash,
references: snap_file.references,
alias_map: snap_file.alias_map,
mtime_secs: snap_file.mtime_secs,
};
files.insert(path, Arc::new(indexed_file));
}
tracing::info!(
"warm restore: file map rebuilt ({} files) in {:?}",
files.len(),
phase.elapsed()
);
let phase = Instant::now();
let trigram_index = match super::trigram::TrigramIndex::from_persisted(trigrams) {
Some(index) if index.covers_files(&files) => {
tracing::info!(
"warm restore: trigram index loaded from snapshot ({} postings) in {:?}",
index.posting_count(),
phase.elapsed()
);
index
}
_ => {
tracing::warn!(
"warm restore: persisted trigram index unusable; rebuilding from restored files"
);
let index = super::trigram::TrigramIndex::build_from_files(&files);
tracing::info!("warm restore: trigram index built in {:?}", phase.elapsed());
index
}
};
let mut index = LiveIndex {
files,
loaded_at: Instant::now(),
loaded_at_system: SystemTime::now(),
load_duration: Duration::ZERO,
cb_state: CircuitBreakerState::new(0.20),
is_empty: false,
load_source: IndexLoadSource::SnapshotRestore,
snapshot_verify_state: SnapshotVerifyState::Pending,
reverse_index: HashMap::new(),
files_by_basename: HashMap::new(),
files_by_dir_component: HashMap::new(),
trigram_index,
gitignore: None,
manifest_entries,
coupling_store: None,
local_empty_reason: Arc::new(parking_lot::RwLock::new(None)),
indexed_root: Some(normalize_root(project_root)),
};
let phase = Instant::now();
index.rebuild_reverse_index();
tracing::info!(
"warm restore: reverse index rebuilt in {:?}",
phase.elapsed()
);
let phase = Instant::now();
index.rebuild_path_indices();
tracing::info!(
"warm restore: path indices rebuilt in {:?}",
phase.elapsed()
);
(index, code_signals.into_published())
}
#[cfg(any(test, not(feature = "embed")))]
#[cfg(any(test, not(any(feature = "server", feature = "embed"))))]
fn stat_check_files_from_view(
verify_view: &VerifyIndexView,
snapshot_mtimes: &HashMap<String, u64>,
root: &Path,
stop: &dyn Fn() -> bool,
) -> Option<StatCheckResult> {
stat_check_files_from_view_with(
verify_view,
snapshot_mtimes,
stop,
|relative| {
let absolute = root.join(relative.replace('/', std::path::MAIN_SEPARATOR_STR));
Ok(std::fs::metadata(absolute).ok().map(|metadata| {
let mtime = metadata
.modified()
.ok()
.and_then(|time| time.duration_since(UNIX_EPOCH).ok())
.map(|duration| duration.as_secs())
.unwrap_or(0);
(metadata.len(), mtime)
}))
},
|| {
let discovered = crate::discovery::discover_files(root);
#[cfg(test)]
let discovered = match test_discovery_failure_root().lock().as_deref() {
Some(failing) if failing == root => Err(anyhow::anyhow!(
"injected discovery failure under {}",
root.display()
)),
_ => discovered,
};
discovered
.map(|files| files.into_iter().map(|file| file.relative_path).collect())
.map_err(|error| AnchoredDiscoveryError::Failed(error.to_string()))
},
)
}
enum AnchoredDiscoveryError {
#[cfg(any(feature = "server", feature = "embed"))]
Cancelled,
Failed(String),
}
impl From<String> for AnchoredDiscoveryError {
fn from(error: String) -> Self {
Self::Failed(error)
}
}
fn stat_check_files_from_view_with(
verify_view: &VerifyIndexView,
snapshot_mtimes: &HashMap<String, u64>,
stop: &dyn Fn() -> bool,
mut observe: impl FnMut(&str) -> Result<Option<(u64, u64)>, String>,
mut discover: impl FnMut() -> Result<Vec<String>, AnchoredDiscoveryError>,
) -> Option<StatCheckResult> {
let known_paths: std::collections::HashSet<&str> = verify_view
.files
.iter()
.map(|file| file.relative_path.as_str())
.chain(
verify_view
.terminal_catalog_paths
.iter()
.map(String::as_str),
)
.collect();
let mut changed = Vec::new();
let mut deleted = Vec::new();
let mut observation_error = None;
for (position, file) in verify_view.files.iter().enumerate() {
if position % SNAPSHOT_VERIFY_STOP_EVERY == 0 && stop() {
return None;
}
match observe(&file.relative_path) {
Ok(Some((on_disk_size, on_disk_mtime))) => {
let stored_mtime = snapshot_mtimes
.get(&file.relative_path)
.copied()
.unwrap_or(0);
if on_disk_size != file.byte_len || on_disk_mtime != stored_mtime {
changed.push(file.relative_path.clone());
}
}
Ok(None) => {
deleted.push(file.relative_path.clone());
}
Err(error) => {
changed.push(file.relative_path.clone());
observation_error.get_or_insert(error);
}
}
}
let (new_files, discovery_error) = match discover() {
Ok(discovered) => (
discovered
.into_iter()
.filter(|path| !known_paths.contains(path.as_str()))
.collect(),
observation_error,
),
#[cfg(any(feature = "server", feature = "embed"))]
Err(AnchoredDiscoveryError::Cancelled) => return None,
Err(AnchoredDiscoveryError::Failed(e)) => {
warn!("stat_check_files: discover_files failed: {e}");
(Vec::new(), Some(e))
}
};
if stop() {
return None;
}
Some(StatCheckResult {
changed,
deleted,
new_files,
discovery_error,
})
}
#[cfg(any(feature = "server", feature = "embed"))]
fn discover_files_from_source_anchor(
root: &Path,
index: &crate::live_index::store::SharedIndex,
authority: &crate::index_lifecycle::activation::ProjectSourceAuthority,
stop: &dyn Fn() -> bool,
) -> Result<Vec<String>, AnchoredDiscoveryError> {
use crate::index_lifecycle::physical_root::{AnchoredEntryKind, list_directory_beneath};
use std::collections::VecDeque;
#[cfg(test)]
if test_discovery_failure_root().lock().as_deref() == Some(root) {
return Err(format!("injected discovery failure under {}", root.display()).into());
}
let limits = crate::discovery::DiscoveryLimits::from_env();
let max_entries = usize::try_from(limits.max_files)
.unwrap_or(usize::MAX)
.min(200_000);
let exclusions = index.source_exclusions();
let mut directories = VecDeque::from([PathBuf::from(".")]);
let mut files = Vec::new();
let mut ignore_files = Vec::new();
let mut visited = 0usize;
while let Some(directory) = directories.pop_front() {
if stop() {
return Err(AnchoredDiscoveryError::Cancelled);
}
let entries = authority
.with_source_anchor_read(|lease| list_directory_beneath(lease, &directory, max_entries))
.map_err(|_| "the admitted source directory could not be listed".to_string())?
.ok_or_else(|| "an admitted source directory vanished".to_string())?;
visited = visited.saturating_add(entries.len());
if visited > max_entries {
return Err("admitted source discovery exceeds its file bound"
.to_string()
.into());
}
for entry in entries {
if crate::discovery::path_is_hard_scope_excluded(&entry.relative)
|| exclusions.excludes_relative(&entry.relative)
{
continue;
}
let relative = entry
.relative
.to_str()
.ok_or_else(|| "source path encoding is unsupported".to_string())?
.replace('\\', "/");
if crate::discovery::is_under_repo_root_build_dir(&relative, None) {
continue;
}
match entry.kind {
AnchoredEntryKind::Directory => directories.push_back(entry.relative),
AnchoredEntryKind::Regular => {
if relative.ends_with(".gitignore") || relative.ends_with(".ignore") {
ignore_files.push((relative.clone(), entry.relative.clone()));
}
if crate::domain::LanguageId::from_path(&relative).is_some() {
files.push(relative);
}
}
AnchoredEntryKind::Link | AnchoredEntryKind::Other => {}
}
}
}
let mut builder = ignore::gitignore::GitignoreBuilder::new(root);
for (relative, path) in ignore_files {
let bytes = authority
.with_source_anchor_read(|lease| {
crate::index_lifecycle::physical_root::read_regular_beneath(
lease,
&path,
256 * 1024,
)
})
.map_err(|_| "an admitted ignore file could not be read".to_string())?
.ok_or_else(|| "an admitted ignore file vanished".to_string())?;
let contents = std::str::from_utf8(&bytes)
.map_err(|_| "an admitted ignore file is not UTF-8".to_string())?;
let relative_parent = path.parent().unwrap_or_else(|| Path::new("."));
crate::discovery::add_gitignore_contents(
&mut builder,
relative_parent,
&root.join(relative),
contents,
);
}
let matcher = builder
.build()
.map_err(|_| "admitted ignore rules could not be compiled".to_string())?;
files.retain(|path| !matcher.matched_path_or_any_parents(path, false).is_ignore());
files.sort();
files.dedup();
Ok(files)
}
#[cfg(any(feature = "server", feature = "embed"))]
fn read_dismissals_from_source_anchor(
authority: &crate::index_lifecycle::activation::ProjectSourceAuthority,
) -> Result<
(
crate::knowledge::secret_dismissals::HeldDismissals,
Vec<crate::knowledge::secret_dismissals::DismissalRecord>,
),
String,
> {
use crate::knowledge::secret_dismissals as dismissals;
let bytes = authority
.with_source_anchor_read(|lease| {
crate::index_lifecycle::physical_root::read_regular_beneath(
lease,
Path::new(".symforge/secret-dismissals.json"),
dismissals::DISMISSAL_STORE_MAX_BYTES as usize,
)
})
.map_err(|_| "the admitted dismissal store could not be read".to_string())?;
let Some(bytes) = bytes else {
return Ok((dismissals::HeldDismissals::default(), Vec::new()));
};
let records = dismissals::parse_dismissals_bytes(&bytes)
.map_err(|_| "the admitted dismissal store could not be parsed".to_string())?;
let held = dismissals::HeldDismissals {
digest: crate::hash::digest_hex(&bytes),
paths: records
.iter()
.map(|record| record.path.replace('\\', "/"))
.collect(),
};
Ok((held, records))
}
#[cfg(any(feature = "server", feature = "embed"))]
pub(crate) fn prepare_snapshot_verify_from_source_anchor(
relative: &str,
root: &Path,
authority: &crate::index_lifecycle::activation::ProjectSourceAuthority,
base: Option<&std::sync::Arc<crate::live_index::store::IndexedFile>>,
records: &[crate::knowledge::secret_dismissals::DismissalRecord],
) -> Option<crate::live_index::store::SnapshotVerifiedFile> {
use crate::domain::ScoutDecision;
let path = Path::new(relative);
if !authority
.with_source_anchor_read(|lease| {
crate::index_lifecycle::physical_root::exact_spelling_beneath(lease, path)
})
.ok()?
{
return None;
}
let (metadata, prefix) = authority
.with_source_anchor_read(|lease| {
crate::index_lifecycle::physical_root::probe_regular_beneath(lease, path, 1_048_576)
})
.ok()??;
let absolute = root.join(relative.replace('/', std::path::MAIN_SEPARATOR_STR));
let scouted = crate::discovery::scout_single_path_with_io(
relative,
&absolute,
|_| Ok(metadata.clone()),
|_, limit| Ok(prefix.iter().take(limit).copied().collect()),
)
.ok()?;
let bytes = if matches!(scouted.decision, ScoutDecision::Ingest { .. }) {
let observation = authority
.with_source_anchor_read(|lease| {
crate::index_lifecycle::physical_root::observe_regular_beneath(
lease,
path,
Some(100 * 1024 * 1024),
)
})
.ok()??;
if observation.len != scouted.stamp.size
|| observation.metadata.modified().ok() != scouted.stamp.modified_hint
{
return None;
}
observation.bytes
} else {
None
};
crate::live_index::single_file::prepare_snapshot_verify_from_observation(
relative,
scouted,
bytes,
base,
|targets, bytes| {
crate::knowledge::classify_stable_content_with(
relative,
targets,
bytes,
|path, bytes| {
crate::knowledge::secret_dismissals::scan_with_records(path, bytes, records)
},
)
},
)
}
#[cfg(any(feature = "server", feature = "embed"))]
fn publish_snapshot_verify_from_source_anchor(
index: &crate::live_index::store::SharedIndex,
expected_gen: u64,
removals: &[(String, PathBuf)],
files: Vec<crate::live_index::store::SnapshotVerifiedFile>,
completion: Option<crate::live_index::store::SnapshotVerifyCompletion>,
authority: &crate::index_lifecycle::activation::ProjectSourceAuthority,
) -> Option<crate::live_index::store::SnapshotVerifyBatchReceipt> {
authority.verify_physical_root_anchor().ok()?;
let receipt = index.publish_snapshot_verify_with_observation(
expected_gen,
removals,
files,
completion,
|relative, _| {
if verify_path_excluded(index, relative) {
return true;
}
authority
.with_source_anchor_read(|lease| {
let path = Path::new(relative);
if crate::index_lifecycle::physical_root::exact_spelling_beneath(lease, path)? {
crate::index_lifecycle::physical_root::open_regular_beneath(lease, path)
.map(|opened| opened.is_none())
} else {
Ok(true)
}
})
.unwrap_or(false)
},
|relative, scouted| {
authority
.with_source_anchor_read(|lease| {
if !crate::index_lifecycle::physical_root::exact_spelling_beneath(
lease,
Path::new(relative),
)? {
return Ok(None);
}
crate::index_lifecycle::physical_root::probe_regular_beneath(
lease,
Path::new(relative),
0,
)
})
.ok()
.flatten()
.is_some_and(|(metadata, _)| {
metadata.len() == scouted.stamp.size
&& metadata.modified().ok() == scouted.stamp.modified_hint
})
},
|| authority.verify_physical_root_anchor().is_ok(),
)?;
authority.verify_physical_root_anchor().ok()?;
Some(receipt)
}
#[cfg(test)]
fn test_discovery_failure_root() -> &'static parking_lot::Mutex<Option<PathBuf>> {
static ROOT: parking_lot::Mutex<Option<PathBuf>> = parking_lot::Mutex::new(None);
&ROOT
}
const SNAPSHOT_VERIFY_STOP_EVERY: usize = 1024;
#[cfg(any(test, not(feature = "embed")))]
#[cfg(any(test, not(any(feature = "server", feature = "embed"))))]
fn spot_verify_sample_from_view(
verify_view: &VerifyIndexView,
root: &Path,
sample_pct: f64,
progress: Option<&SnapshotVerifyProgress>,
stop: &dyn Fn() -> bool,
) -> Option<(Vec<String>, Vec<String>)> {
spot_verify_sample_from_view_with(verify_view, sample_pct, progress, stop, |relative| {
let absolute = root.join(relative.replace('/', std::path::MAIN_SEPARATOR_STR));
std::fs::read(absolute).ok()
})
}
fn spot_verify_sample_from_view_with(
verify_view: &VerifyIndexView,
sample_pct: f64,
progress: Option<&SnapshotVerifyProgress>,
stop: &dyn Fn() -> bool,
mut read: impl FnMut(&str) -> Option<Vec<u8>>,
) -> Option<(Vec<String>, Vec<String>)> {
if verify_view.files.is_empty() {
return Some((Vec::new(), Vec::new()));
}
let total = verify_view.files.len();
let sample_size = ((total as f64 * sample_pct).ceil() as usize)
.max(1)
.min(total);
let step = total.checked_div(sample_size).unwrap_or(1);
let step = step.max(1);
if let Some(progress) = progress {
progress.start_spot_check(total.div_ceil(step));
}
let mut mismatches = Vec::new();
let mut unreadable = Vec::new();
for (position, file) in verify_view.files.iter().step_by(step).enumerate() {
if position % SNAPSHOT_VERIFY_STOP_EVERY == 0 && stop() {
return None;
}
if let Some(progress) = progress {
progress.add_processed(1);
}
let bytes = match read(&file.relative_path) {
Some(bytes) => bytes,
None => {
unreadable.push(file.relative_path.clone());
continue;
}
};
let on_disk_hash = crate::hash::digest_hex(&bytes);
if on_disk_hash != file.content_hash {
mismatches.push(file.relative_path.clone());
}
}
Some((mismatches, unreadable))
}
pub fn init_frecency_store(project_root: &Path, project_state: &crate::domain::ProjectStateDir) {
crate::live_index::frecency::ensure_bump_hook_registered();
if crate::live_index::frecency::collection_policy_from_env()
!= crate::capability::FrecencyCollectionPolicy::Persistent
{
return;
}
let db_path = crate::live_index::frecency::frecency_db_path(project_state);
let _ = run_frecency_init(&db_path, project_root);
}
fn run_frecency_init(db_path: &Path, repo_root: &Path) -> Result<(), String> {
let store =
crate::live_index::frecency::FrecencyStore::open(db_path).map_err(|e| e.to_string())?;
store.apply_head_reset_policy(repo_root)
}
#[derive(Clone)]
pub(crate) struct SnapshotBuildInput {
files: HashMap<String, Arc<IndexedFile>>,
manifest_entries: Vec<CatalogEntry>,
manifest: Option<RepositoryManifest>,
code_signals: Option<PersistedCodeSignals>,
trigrams: super::trigram::PersistedTrigramIndex,
}
#[derive(Clone, Debug, PartialEq, Eq)]
struct VerifyFileView {
relative_path: String,
byte_len: u64,
content_hash: String,
}
#[derive(Clone, Debug, PartialEq, Eq)]
struct VerifyIndexView {
files: Vec<VerifyFileView>,
terminal_catalog_paths: Vec<String>,
}
fn capture_verify_view(index: &LiveIndex) -> VerifyIndexView {
let mut files: Vec<VerifyFileView> = index
.files
.iter()
.map(|(path, file)| VerifyFileView {
relative_path: path.clone(),
byte_len: file.byte_len,
content_hash: file.content_hash.clone(),
})
.collect();
files.sort_by(|a, b| a.relative_path.cmp(&b.relative_path));
let mut terminal_catalog_paths: Vec<String> = index
.manifest_entries
.iter()
.filter(|entry| {
matches!(
entry.disposition,
FileDisposition::MetadataOnly { .. } | FileDisposition::HardSkip { .. }
)
})
.map(|entry| {
entry
.path
.normalized_utf8
.as_deref()
.unwrap_or(entry.path.public_id.as_str())
.to_string()
})
.collect();
terminal_catalog_paths.sort();
terminal_catalog_paths.dedup();
VerifyIndexView {
files,
terminal_catalog_paths,
}
}
fn build_snapshot(
snapshot_input: SnapshotBuildInput,
project_root: &Path,
project_id: ProjectId,
) -> anyhow::Result<IndexSnapshot> {
let SnapshotBuildInput {
files,
manifest_entries,
manifest,
code_signals,
trigrams,
} = snapshot_input;
let mut snap_files = HashMap::with_capacity(files.len());
for (path, file) in files {
let abs_path = project_root.join(path.replace('/', std::path::MAIN_SEPARATOR_STR));
let mtime_secs = std::fs::metadata(&abs_path)
.ok()
.and_then(|m| m.modified().ok())
.and_then(|t| t.duration_since(UNIX_EPOCH).ok())
.map(|d| d.as_secs())
.unwrap_or(0);
snap_files.insert(
path.clone(),
IndexedFileSnapshot {
relative_path: file.relative_path.clone(),
language: file.language,
classification: file.classification,
content: file.content.clone(),
symbols: file.symbols.clone(),
parse_status: file.parse_status.clone(),
parse_diagnostic: file.parse_diagnostic.clone(),
byte_len: file.byte_len,
content_hash: file.content_hash.clone(),
references: file.references.clone(),
alias_map: file.alias_map.clone(),
mtime_secs,
},
);
}
let captured_source = capture_repository_source(project_root, &project_id)?;
let manifest = if let Some(manifest) = manifest {
if manifest.entries != manifest_entries {
anyhow::bail!("published manifest entries disagree with the captured live generation");
}
if manifest.source != captured_source.source
|| manifest.source_version != captured_source.source_version
{
anyhow::bail!(
"source identity or version advanced while the published generation was checkpointed"
);
}
let rebuilt = RepositoryManifest::new(
manifest.schema_version,
manifest.policy_version,
manifest.secret_policy_version,
manifest.source.clone(),
manifest.source_version.clone(),
manifest.coverage,
manifest.entries.clone(),
manifest.issues.clone(),
manifest.usage,
)?;
if rebuilt.digest != manifest.digest {
anyhow::bail!("published manifest digest failed canonical reconstruction");
}
manifest
} else {
let coverage = if manifest_entries.iter().any(|entry| {
matches!(
entry.disposition,
FileDisposition::Unreadable { .. }
| FileDisposition::UnstableDuringRead
| FileDisposition::AbortedCircuitBreaker
)
}) {
CoverageStatus::Degraded
} else {
CoverageStatus::Complete
};
let usage = ManifestResourceUsage {
catalog_entries: manifest_entries.len() as u64,
catalog_metadata_bytes: serde_json::to_vec(&manifest_entries)?.len() as u64,
admitted_content_bytes: snap_files.values().map(|file| file.byte_len).sum(),
};
RepositoryManifest::new(
1,
1,
crate::knowledge::SECRET_POLICY_VERSION,
captured_source.source.clone(),
captured_source.source_version.clone(),
coverage,
manifest_entries,
Vec::new(),
usage,
)?
};
let content_digest = indexed_content_digest(
snap_files
.iter()
.map(|(path, file)| (path.as_str(), file.content.as_slice())),
)?;
let source_identity = snapshot_source_identity_from_captured(
project_id.clone(),
captured_source,
manifest.digest.clone(),
content_digest,
);
let held_dismissals = crate::knowledge::secret_dismissals::held_dismissals(project_root)
.unwrap_or_else(|| crate::knowledge::secret_dismissals::observe_dismissals(project_root));
let code_signals = code_signals.unwrap_or_else(|| PersistedCodeSignals {
temporal: super::git_temporal::GitTemporalIndex::pending(),
computed_for_content_generation: 0,
computed_for_source_version: manifest.source_version.clone(),
coverage: capture_history_coverage(project_root),
});
Ok(IndexSnapshot {
version: CURRENT_VERSION,
project_id,
source_identity,
files: snap_files,
manifest,
code_signals,
trigrams,
dismissal_store_digest: held_dismissals.digest,
dismissal_paths: held_dismissals.paths.into_iter().collect(),
})
}
const SNAPSHOT_VERIFY_PREPARE_CHUNK: usize = 256;
const SNAPSHOT_VERIFY_PUBLISH_BYTES: usize = 256 * 1024 * 1024;
pub async fn background_verify(
index: crate::live_index::store::SharedIndex,
root: std::path::PathBuf,
snapshot_mtimes: HashMap<String, u64>,
observer: crate::live_index::index_lifecycle::observer::ObserverId,
) {
background_verify_cancellable(index, root, snapshot_mtimes, observer, || false).await;
}
pub(crate) async fn background_verify_cancellable<C>(
index: crate::live_index::store::SharedIndex,
root: std::path::PathBuf,
snapshot_mtimes: HashMap<String, u64>,
observer: crate::live_index::index_lifecycle::observer::ObserverId,
cancelled: C,
) where
C: Fn() -> bool + Send + 'static,
{
background_verify_with_hook(index, root, snapshot_mtimes, observer, || {}, cancelled).await;
}
#[cfg(feature = "server")]
pub(crate) async fn background_verify_cancellable_bound<C>(
index: crate::live_index::store::SharedIndex,
root: std::path::PathBuf,
snapshot_mtimes: HashMap<String, u64>,
authority: std::sync::Arc<crate::index_lifecycle::activation::ProjectSourceAuthority>,
cancelled: C,
) where
C: Fn() -> bool + Send + 'static,
{
let observer = authority.active_observer();
background_verify_with_hook_authority(
index,
root,
snapshot_mtimes,
authority,
observer,
|| {},
cancelled,
)
.await;
}
#[cfg(test)]
pub(crate) fn block_on_background_verify_for_test(
index: crate::live_index::store::SharedIndex,
root: &Path,
snapshot_mtimes: HashMap<String, u64>,
) {
let observer = crate::live_index::index_lifecycle::activation::project_source_authority(root)
.active_observer();
tokio::runtime::Builder::new_current_thread()
.enable_all()
.build()
.expect("background_verify test runtime")
.block_on(background_verify(
index,
root.to_path_buf(),
snapshot_mtimes,
observer,
));
}
async fn background_verify_with_hook<F, C>(
index: crate::live_index::store::SharedIndex,
root: std::path::PathBuf,
snapshot_mtimes: HashMap<String, u64>,
observer: crate::live_index::index_lifecycle::observer::ObserverId,
after_running: F,
cancelled: C,
) where
F: FnOnce() + Send + 'static,
C: Fn() -> bool + Send + 'static,
{
let authority = crate::live_index::index_lifecycle::activation::project_source_authority(&root);
background_verify_with_hook_authority(
index,
root,
snapshot_mtimes,
authority,
observer,
after_running,
cancelled,
)
.await;
}
async fn background_verify_with_hook_authority<F, C>(
index: crate::live_index::store::SharedIndex,
root: std::path::PathBuf,
snapshot_mtimes: HashMap<String, u64>,
authority: std::sync::Arc<crate::index_lifecycle::activation::ProjectSourceAuthority>,
observer: crate::live_index::index_lifecycle::observer::ObserverId,
after_running: F,
cancelled: C,
) where
F: FnOnce() + Send + 'static,
C: Fn() -> bool + Send + 'static,
{
let expected_gen = index.current_project_generation();
let task_index = index.clone();
let joined = tokio::task::spawn_blocking(move || {
run_background_verify(
&task_index,
&root,
&snapshot_mtimes,
&authority,
observer,
expected_gen,
after_running,
cancelled,
);
})
.await;
if let Err(error) = joined {
tracing::error!(%error, "snapshot verify task failed; every restored row is unverified");
let unverified: Vec<String> = index.read().files.keys().cloned().collect();
let report = SnapshotVerifyReport::from_mismatched_paths(unverified)
.with_reason("the snapshot verify task failed before it finished".to_string());
if !index.mark_snapshot_verify_failed_at_generation(expected_gen, report) {
warn!("snapshot verify task failed after the project was retargeted");
}
}
}
#[cfg(feature = "embed")]
pub(crate) fn background_verify_bound<C>(
index: &crate::live_index::store::SharedIndex,
root: &Path,
snapshot_mtimes: &HashMap<String, u64>,
authority: &std::sync::Arc<crate::index_lifecycle::activation::ProjectSourceAuthority>,
cancelled: C,
) where
C: Fn() -> bool,
{
let observer = authority.active_observer();
let expected_gen = index.current_project_generation();
run_background_verify(
index,
root,
snapshot_mtimes,
authority,
observer,
expected_gen,
|| {},
cancelled,
);
}
#[cfg(any(feature = "server", feature = "embed"))]
fn verify_path_excluded(index: &crate::live_index::store::SharedIndex, relative: &str) -> bool {
let path = Path::new(relative);
crate::discovery::path_is_hard_scope_excluded(path)
|| index.is_source_excluded(path)
|| index.read().is_path_gitignored(relative)
}
#[cfg(any(feature = "server", feature = "embed"))]
fn reverify_through_canonical_seam(
index: &crate::live_index::store::SharedIndex,
root: &Path,
rel_path: &str,
expected_gen: u64,
authority: &crate::live_index::index_lifecycle::activation::ProjectSourceAuthority,
observer: crate::live_index::index_lifecycle::observer::ObserverId,
stop: &dyn Fn() -> bool,
) -> Result<(), String> {
#[cfg(test)]
if crate::live_index::single_file::test_scout_failure_path()
.lock()
.as_deref()
== Some(rel_path)
{
return Err("injected scout failure".to_string());
}
let relative = Path::new(rel_path);
let absolute = root.join(rel_path.replace('/', std::path::MAIN_SEPARATOR_STR));
for _ in 0..3 {
if stop() {
return Err("the admitted re-read was cancelled".to_string());
}
if verify_path_excluded(index, rel_path) {
let removals = vec![(rel_path.to_string(), absolute.clone())];
let receipt = publish_snapshot_verify_from_source_anchor(
index,
expected_gen,
&removals,
Vec::new(),
None,
authority,
)
.ok_or_else(|| "the excluded-path eviction was refused".to_string())?;
if receipt.refused.is_empty() {
return Ok(());
}
continue;
}
let (_, records) = read_dismissals_from_source_anchor(authority)?;
let base = index.read().files.get(rel_path).cloned();
let prepared = prepare_snapshot_verify_from_source_anchor(
rel_path,
root,
authority,
base.as_ref(),
&records,
);
let (removals, files) = if let Some(prepared) = prepared {
(Vec::new(), vec![prepared])
} else {
let absent = authority
.with_source_anchor_read(|lease| {
crate::index_lifecycle::physical_root::open_regular_beneath(lease, relative)
.map(|opened| opened.is_none())
})
.map_err(|_| "the admitted source file could not be read".to_string())?;
if !absent {
continue;
}
(vec![(rel_path.to_string(), absolute.clone())], Vec::new())
};
if stop() {
return Err("the admitted re-read was cancelled".to_string());
}
let receipt = publish_snapshot_verify_from_source_anchor(
index,
expected_gen,
&removals,
files,
None,
authority,
)
.ok_or_else(|| "the admitted source publication was refused".to_string())?;
if receipt.refused.is_empty() {
if !receipt.indexed.is_empty()
&& let Err(active) = authority.observe_admission(observer, rel_path)
{
tracing::debug!(?observer, ?active, %rel_path, "stale verify admission observation refused");
}
return Ok(());
}
}
Err("its admitted re-read could not be published after retries".to_string())
}
fn snapshot_verify_mismatch_reason(
spot_mismatches: usize,
unreadable_not_reparsed: usize,
discovery_failed: bool,
not_reparsed: usize,
) -> String {
let mut parts = Vec::new();
if discovery_failed {
parts.push(
"new files could not be discovered, so files added since the snapshot may be missing"
.to_string(),
);
}
if spot_mismatches > 0 {
parts.push(format!(
"{spot_mismatches} restored files had changed content behind an unchanged size and mtime"
));
}
if unreadable_not_reparsed > 0 {
parts.push(format!(
"{unreadable_not_reparsed} restored files could not be read for the spot check"
));
}
if not_reparsed > 0 {
parts.push(format!(
"{not_reparsed} changed or new files are not re-parsed in this build"
));
}
parts.join("; ")
}
#[allow(clippy::too_many_arguments)]
fn run_background_verify<F, C>(
index: &crate::live_index::store::SharedIndex,
root: &Path,
snapshot_mtimes: &HashMap<String, u64>,
authority: &std::sync::Arc<crate::index_lifecycle::activation::ProjectSourceAuthority>,
observer: crate::live_index::index_lifecycle::observer::ObserverId,
expected_gen: u64,
after_running: F,
cancelled: C,
) where
F: FnOnce(),
C: Fn() -> bool,
{
let observe_admissions = |paths: &[String]| {
for path in paths {
if let Err(active) = authority.observe_admission(observer, path) {
tracing::debug!(
?observer,
?active,
%path,
"stale verify incarnation: admission observation refused"
);
}
}
};
let observe_removals = |paths: &[String]| {
for path in paths {
if let Err(active) = authority.observe_removal(observer, path) {
tracing::debug!(
?observer,
?active,
%path,
"stale verify incarnation: removal observation refused"
);
}
}
};
let abandoned = |stage: &str| {
warn!(
"snapshot verify abandoned at {stage}: the project was retargeted, \
and its replacement owns its own verification state"
);
};
let stopped = |stage: &str| {
if index.current_project_generation() != expected_gen {
abandoned(stage);
return true;
}
if cancelled() {
info!(
"snapshot verify cancelled at {stage}: its project slot stopped, \
nothing more is published"
);
return true;
}
false
};
let progress = SnapshotVerifyProgress::started(SystemTime::now(), index.read().files.len());
if !index.mark_snapshot_verify_started_at_generation(expected_gen, progress.clone()) {
abandoned("start");
return;
}
after_running();
#[cfg(any(feature = "server", feature = "embed"))]
if authority.verify_physical_root_anchor().is_err() {
let unverified: Vec<String> = index.read().files.keys().cloned().collect();
let report = SnapshotVerifyReport::from_mismatched_paths(unverified)
.with_reason("the originally admitted source directory moved".to_string());
index.mark_snapshot_verify_failed_at_generation(expected_gen, report);
return;
}
let base = index.read();
let verify_view = capture_verify_view(&base);
#[cfg(any(feature = "server", feature = "embed"))]
let stat_result = stat_check_files_from_view_with(
&verify_view,
snapshot_mtimes,
&|| stopped("the stat pass"),
|relative| {
authority
.with_source_anchor_read(|lease| {
crate::index_lifecycle::physical_root::entry_metadata_beneath(
lease,
Path::new(relative),
)
})
.map_err(|_| "the admitted source could not be observed".to_string())
.map(|observed| observed.map(|metadata| (metadata.len, metadata.modified_secs)))
},
|| discover_files_from_source_anchor(root, index, authority, &|| stopped("discovery")),
);
#[cfg(not(any(feature = "server", feature = "embed")))]
let stat_result = stat_check_files_from_view(&verify_view, snapshot_mtimes, root, &|| {
stopped("the stat pass")
});
let Some(stat_result) = stat_result else {
return;
};
let changed_count = stat_result.changed.len();
let deleted_count = stat_result.deleted.len();
let new_count = stat_result.new_files.len();
let spot = {
let flagged: HashSet<&str> = stat_result
.changed
.iter()
.chain(&stat_result.deleted)
.map(String::as_str)
.collect();
let cleared = VerifyIndexView {
files: verify_view
.files
.iter()
.filter(|file| !flagged.contains(file.relative_path.as_str()))
.cloned()
.collect(),
terminal_catalog_paths: Vec::new(),
};
#[cfg(any(feature = "server", feature = "embed"))]
let spot = {
let lengths: HashMap<&str, usize> = cleared
.files
.iter()
.map(|file| {
(
file.relative_path.as_str(),
usize::try_from(file.byte_len).unwrap_or(usize::MAX),
)
})
.collect();
spot_verify_sample_from_view_with(
&cleared,
0.10,
Some(&progress),
&|| stopped("the spot check"),
|relative| {
let limit = lengths.get(relative).copied()?;
authority
.with_source_anchor_read(|lease| {
crate::index_lifecycle::physical_root::read_regular_beneath(
lease,
Path::new(relative),
limit,
)
})
.ok()
.flatten()
},
)
};
#[cfg(not(any(feature = "server", feature = "embed")))]
let spot = spot_verify_sample_from_view(&cleared, root, 0.10, Some(&progress), &|| {
stopped("the spot check")
});
spot
};
let Some((spot_mismatches, spot_unreadable)) = spot else {
return;
};
drop(verify_view);
let spot_count = spot_mismatches.len();
#[cfg(any(feature = "server", feature = "embed"))]
let (dismissals_now, dismissal_records) = match read_dismissals_from_source_anchor(authority) {
Ok(observed) => observed,
Err(reason) => {
let unverified: Vec<String> = base.files.keys().cloned().collect();
let report =
SnapshotVerifyReport::from_mismatched_paths(unverified).with_reason(reason);
index.mark_snapshot_verify_failed_at_generation(expected_gen, report);
return;
}
};
#[cfg(not(any(feature = "server", feature = "embed")))]
let dismissals_now = crate::knowledge::secret_dismissals::observe_dismissals(root);
let dismissal_paths: Vec<String> = {
let candidates: std::collections::BTreeSet<String> =
match crate::knowledge::secret_dismissals::held_dismissals(root) {
Some(held) if held.digest == dismissals_now.digest => Default::default(),
Some(held) => held
.paths
.into_iter()
.chain(dismissals_now.paths.iter().cloned())
.collect(),
None => base
.files
.keys()
.cloned()
.chain(dismissals_now.paths.iter().cloned())
.collect(),
};
candidates
.into_iter()
.filter(|path| {
#[cfg(any(feature = "server", feature = "embed"))]
{
let relative = Path::new(path);
relative
.components()
.all(|component| matches!(component, std::path::Component::Normal(_)))
&& !crate::discovery::path_is_hard_scope_excluded(relative)
}
#[cfg(not(any(feature = "server", feature = "embed")))]
{
matches!(crate::discovery::resolve_repo_path(root, path), Ok(Some(_)))
}
})
.collect()
};
#[cfg_attr(any(feature = "server", feature = "embed"), allow(unused_mut))]
let mut reported: Vec<String> = spot_mismatches.clone();
#[cfg(any(feature = "server", feature = "embed"))]
reported.retain(|path| !verify_path_excluded(index, path));
let discovery_error = stat_result.discovery_error.as_deref().map(|error| {
let canonical = std::fs::canonicalize(root).ok();
canonical
.iter()
.map(PathBuf::as_path)
.chain(std::iter::once(root))
.fold(error.to_string(), |error, form| {
error.replace(form.to_string_lossy().as_ref(), "<project root>")
})
});
let mut unreconciled: BTreeMap<String, String> = BTreeMap::new();
#[cfg(any(feature = "server", feature = "embed"))]
let (to_reparse, not_reparsed, unreadable_not_reparsed) = {
let mut to_reparse: Vec<String> = stat_result
.changed
.iter()
.chain(&stat_result.new_files)
.chain(&spot_mismatches)
.chain(&spot_unreadable)
.chain(&dismissal_paths)
.cloned()
.collect();
to_reparse.sort();
to_reparse.dedup();
(to_reparse, 0usize, 0usize)
};
#[cfg(not(any(feature = "server", feature = "embed")))]
let (to_reparse, not_reparsed, unreadable_not_reparsed) = {
let not_reparsed = stat_result.changed.len() + stat_result.new_files.len();
reported.extend(stat_result.changed.iter().cloned());
reported.extend(stat_result.new_files.iter().cloned());
reported.extend(spot_unreadable.iter().cloned());
for path in &dismissal_paths {
unreconciled.insert(
path.clone(),
"it was admitted under another secret-dismissal store, and this build \
does not re-read"
.to_string(),
);
}
(Vec::<String>::new(), not_reparsed, spot_unreadable.len())
};
let base_rows: HashMap<String, Arc<IndexedFile>> = to_reparse
.iter()
.chain(&stat_result.deleted)
.chain(&dismissal_paths)
.filter_map(|path| {
base.files
.get(path)
.map(|row| (path.clone(), Arc::clone(row)))
})
.collect();
drop(base);
progress.start_reverify(to_reparse.len());
#[cfg_attr(not(feature = "server"), allow(unused_mut))]
let mut removals: Vec<(String, PathBuf)> = stat_result
.deleted
.iter()
.map(|path| (path.clone(), root.join(path)))
.collect();
#[cfg_attr(not(feature = "server"), allow(unused_mut))]
let mut prepared: Vec<crate::live_index::store::SnapshotVerifiedFile> = Vec::new();
#[cfg(any(feature = "server", feature = "embed"))]
{
let mut prepared_bytes = 0usize;
for chunk in to_reparse.chunks(SNAPSHOT_VERIFY_PREPARE_CHUNK) {
if stopped("an admitted re-read batch") {
return;
}
for path in chunk {
if verify_path_excluded(index, path) {
removals.push((path.clone(), root.join(path)));
progress.add_processed(1);
continue;
}
let verified = prepare_snapshot_verify_from_source_anchor(
path,
root,
authority,
base_rows.get(path),
&dismissal_records,
);
if let Some(verified) = verified {
prepared_bytes = prepared_bytes.saturating_add(verified.resident_bytes());
prepared.push(verified);
} else {
let absent = authority
.with_source_anchor_read(|lease| {
crate::index_lifecycle::physical_root::open_regular_beneath(
lease,
Path::new(path),
)
.map(|opened| opened.is_none())
})
.unwrap_or(false);
if absent {
if base_rows.contains_key(path) {
removals.push((path.clone(), root.join(path)));
}
} else {
if let Err(reason) = reverify_through_canonical_seam(
index,
root,
path,
expected_gen,
authority,
observer,
&|| stopped("a canonical re-read"),
) {
unreconciled.insert(path.clone(), reason);
}
}
}
progress.add_processed(1);
}
if prepared_bytes >= SNAPSHOT_VERIFY_PUBLISH_BYTES {
let Some(receipt) = publish_snapshot_verify_from_source_anchor(
index,
expected_gen,
&[],
std::mem::take(&mut prepared),
None,
authority,
) else {
let unverified: Vec<String> = index.read().files.keys().cloned().collect();
let report = SnapshotVerifyReport::from_mismatched_paths(unverified)
.with_reason("admitted source publication was refused".to_string());
index.mark_snapshot_verify_failed_at_generation(expected_gen, report);
return;
};
observe_admissions(&receipt.indexed);
for path in receipt.refused {
if let Err(reason) = reverify_through_canonical_seam(
index,
root,
&path,
expected_gen,
authority,
observer,
&|| stopped("a refused-path retry"),
) {
unreconciled.insert(path, reason);
}
}
prepared_bytes = 0;
}
}
}
let completion = |unreconciled: &BTreeMap<String, String>| {
let paths: Vec<String> = reported
.iter()
.cloned()
.chain(unreconciled.keys().cloned())
.collect();
let report = SnapshotVerifyReport::from_mismatched_paths(paths)
.with_reason(snapshot_verify_mismatch_reason(
spot_count,
unreadable_not_reparsed,
discovery_error.is_some(),
not_reparsed,
))
.with_unverified(unreconciled.clone())
.with_discovery_error(discovery_error.clone());
let restored_rows = unreconciled
.keys()
.map(|path| (path.clone(), base_rows.get(path).cloned()))
.collect();
SnapshotVerifyCompletion {
report,
restored_rows,
}
};
if stopped("the publication") {
return;
}
#[cfg(any(feature = "server", feature = "embed"))]
if authority.verify_physical_root_anchor().is_err() {
let unverified: Vec<String> = index.read().files.keys().cloned().collect();
let report = SnapshotVerifyReport::from_mismatched_paths(unverified)
.with_reason("the originally admitted source directory moved".to_string());
index.mark_snapshot_verify_failed_at_generation(expected_gen, report);
return;
}
progress.enter_publish();
let prepared_files = prepared.len();
let publish_started = Instant::now();
#[cfg(any(feature = "server", feature = "embed"))]
let publish = publish_snapshot_verify_from_source_anchor(
index,
expected_gen,
&removals,
prepared,
Some(completion(&unreconciled)),
authority,
);
#[cfg(not(any(feature = "server", feature = "embed")))]
let publish = index.publish_snapshot_verify_at_generation(
expected_gen,
&removals,
prepared,
Some(completion(&unreconciled)),
);
let Some(receipt) = publish else {
abandoned("publication");
return;
};
info!(
"snapshot verify publication: {} prepared files, {} removals, {} superseded by newer writers, {} refused, in {:?}",
prepared_files,
receipt.removed.len(),
receipt.superseded.len(),
receipt.refused.len(),
publish_started.elapsed()
);
observe_removals(&receipt.removed);
observe_admissions(&receipt.indexed);
let final_report = if receipt.completed {
completion(&unreconciled).report
} else {
#[cfg(any(feature = "server", feature = "embed"))]
for path in receipt.refused {
if stopped("a refused-path retry") {
return;
}
if let Err(reason) = reverify_through_canonical_seam(
index,
root,
&path,
expected_gen,
authority,
observer,
&|| stopped("a refused-path retry"),
) {
unreconciled.insert(path, reason);
}
}
#[cfg(not(any(feature = "server", feature = "embed")))]
for path in receipt.refused {
unreconciled.insert(
path,
"it changed again after the verify read it, and this build does not re-read"
.to_string(),
);
}
let completion = completion(&unreconciled);
let final_report = completion.report.clone();
if !index.mark_snapshot_verify_completed_at_generation(expected_gen, completion) {
abandoned("completion");
return;
}
final_report
};
if final_report.has_mismatches() {
warn!(
"background verify reported {} mismatched files: {}; freshness reports \
SnapshotVerificationFailed",
final_report.mismatch_count,
final_report.reason.as_deref().unwrap_or("unknown")
);
}
if cfg!(any(feature = "server", feature = "embed"))
&& dismissal_paths
.iter()
.all(|path| !unreconciled.contains_key(path))
{
crate::knowledge::secret_dismissals::set_held_dismissals(root, dismissals_now);
}
info!(
"background verify complete: {} changed, {} deleted, {} new, {} spot-check mismatches, {} reported mismatches, {} withheld as unverified in {:?}",
changed_count,
deleted_count,
new_count,
spot_count,
final_report.mismatch_count,
unreconciled.len(),
progress.started_at().elapsed().unwrap_or_default()
);
}
#[cfg(test)]
mod tests {
use super::*;
fn verify_observer(root: &Path) -> crate::live_index::index_lifecycle::observer::ObserverId {
crate::live_index::index_lifecycle::activation::project_source_authority(root)
.active_observer()
}
use crate::domain::{
AccessErrorKind, CapabilityStatus, CapabilityUnavailableReason, CatalogEntry, CatalogPath,
FileDisposition, HardSkipReason, IndexTargets, LanguageId, MetadataOnlyReason,
ProjectStateDir, ReferenceKind, ReferenceRecord, RootBinding, RootCandidateSource,
SourceAccessMode, StatePlacement, SymbolKind, SymbolRecord, UserLocalPlacementReason,
};
use crate::live_index::store::{
IndexLoadSource, IndexedFile, ParseStatus, SnapshotVerifyState,
};
use std::collections::HashMap;
use std::sync::Arc;
use std::time::{Duration, Instant, SystemTime};
use tempfile::TempDir;
mod git_test_helpers {
include!(concat!(
env!("CARGO_MANIFEST_DIR"),
"/src/git/test_helpers.rs"
));
}
#[test]
fn gitattributes_merge_hint_routes_through_the_source_mutation_permit() {
let dir = tempfile::TempDir::new().expect("fixture root");
let authority =
crate::live_index::index_lifecycle::activation::project_source_authority(dir.path());
let before = authority.grants_issued();
super::ensure_gitattributes_merge_hint(dir.path()).expect("hint write");
let written = std::fs::read_to_string(dir.path().join(".gitattributes")).expect("read");
assert!(
written
.lines()
.any(|line| line.trim() == "*.zst merge=ours")
);
assert_eq!(
authority.grants_issued(),
before + 1,
"the hint append must obtain a SourceMutationPermit"
);
assert!(authority.is_current());
super::ensure_gitattributes_merge_hint(dir.path()).expect("idempotent");
assert_eq!(authority.grants_issued(), before + 1);
}
#[test]
fn embedder_snapshot_helpers_round_trip() {
let dir = tempfile::TempDir::new().expect("fixture root");
std::fs::write(dir.path().join("lib.rs"), "pub fn seeded() {}\n").expect("seed file");
assert!(!super::snapshot_compatible(dir.path()));
assert!(super::load_snapshot_for_root(dir.path()).is_none());
let placement =
super::project_local_state_placement(dir.path()).expect("placement resolves");
let shared = crate::live_index::LiveIndex::load_for_state_placement(dir.path(), &placement)
.expect("cold load");
super::checkpoint_shared_index(&shared, dir.path(), &placement).expect("checkpoint");
assert!(super::snapshot_compatible(dir.path()));
let snapshot = super::load_snapshot_for_root(dir.path()).expect("snapshot restores");
let live = super::snapshot_to_live_index(snapshot, dir.path());
assert_eq!(live.file_count(), 1);
assert_eq!(live.load_source(), IndexLoadSource::SnapshotRestore);
}
#[test]
fn checkpoint_shared_index_refuses_unvouched_manifest_none_generation() {
let dir = tempfile::TempDir::new().expect("fixture root");
std::fs::write(dir.path().join("lib.rs"), "pub fn seeded() {}\n").expect("seed file");
let placement =
super::project_local_state_placement(dir.path()).expect("placement resolves");
let shared = crate::live_index::LiveIndex::load_for_state_placement(dir.path(), &placement)
.expect("cold load");
assert!(
shared.published_generation().manifest.is_some(),
"rooted load must publish a vouched manifest"
);
super::checkpoint_shared_index(&shared, dir.path(), &placement).expect("rooted checkpoint");
let snapshot_path = dir.path().join(".symforge/index.bin");
let before_bytes = std::fs::read(&snapshot_path).expect("index.bin exists");
let before_hash = crate::hash::digest_hex(&before_bytes);
let placeholder = crate::live_index::LiveIndex::empty();
placeholder.update_file(
"lib.rs".to_string(),
make_indexed_file("lib.rs", b"pub fn seeded() {}\n"),
);
assert!(
placeholder.published_generation().manifest.is_none(),
"bootstrap placeholder must not publish a manifest"
);
let err = super::checkpoint_shared_index(&placeholder, dir.path(), &placement)
.expect_err("must refuse unvouched generation");
assert!(
err.to_string()
.contains("refusing to checkpoint an unvouched published generation"),
"unexpected error: {err}"
);
let after_bytes = std::fs::read(&snapshot_path).expect("index.bin still exists");
assert_eq!(before_hash, crate::hash::digest_hex(&after_bytes));
assert_eq!(before_bytes, after_bytes, "index.bin must be unchanged");
}
fn project_local_placement(project_root: &Path) -> StatePlacement {
StatePlacement::ProjectLocal {
directory: ProjectStateDir::new(project_root.join(".symforge")),
}
}
fn artifact_binding(project_root: &Path, access_mode: SourceAccessMode) -> RootBinding {
let canonical_root = dunce::canonicalize(project_root).expect("canonical project root");
RootBinding {
source: RootCandidateSource::ExplicitIndexFolder,
root_id: crate::discovery::project_id_for_canonical_root(&canonical_root),
canonical_root,
access_mode,
}
}
fn export_artifact_legacy(
index: &LiveIndex,
project_root: &Path,
) -> anyhow::Result<ArtifactExportReport> {
let binding = artifact_binding(project_root, SourceAccessMode::NormalProject);
super::export_artifact(
index,
&binding.canonical_root,
binding.access_mode,
&project_local_placement(&binding.canonical_root),
&CapabilityStatus::Available,
)
}
fn assert_no_team_artifact_mutation(project_root: &Path) {
assert!(!project_root.join(".symforge/index.bin.zst").exists());
assert!(!project_root.join(".symforge/artifact.json").exists());
assert!(!project_root.join(".gitattributes").exists());
}
fn serialize_index_with_placement(
index: &LiveIndex,
project_root: &Path,
state_placement: &StatePlacement,
) -> anyhow::Result<()> {
let snapshot_input = super::capture_snapshot_build_input(index);
super::serialize_captured_snapshot(snapshot_input, project_root, state_placement)
.map(|_| ())
}
fn serialize_index(index: &LiveIndex, project_root: &Path) -> anyhow::Result<()> {
serialize_index_with_placement(index, project_root, &project_local_placement(project_root))
}
fn load_snapshot(project_root: &Path) -> Option<IndexSnapshot> {
super::load_snapshot(project_root, &project_local_placement(project_root))
}
fn reset_snapshot_state(project_root: &Path) -> anyhow::Result<SnapshotResetReport> {
super::reset_snapshot_state(project_root, &project_local_placement(project_root))
}
fn snapshot_path_and_lock(project_root: &Path) -> anyhow::Result<(PathBuf, Arc<Mutex<()>>)> {
super::snapshot_path_and_lock(match &project_local_placement(project_root) {
StatePlacement::ProjectLocal { directory } => directory,
_ => unreachable!(),
})
}
fn quarantine_bad_snapshot(
project_root: &Path,
snapshot_path: &Path,
bytes: &[u8],
reason: &str,
detail: String,
) -> anyhow::Result<PathBuf> {
let placement = project_local_placement(project_root);
let StatePlacement::ProjectLocal { directory } = &placement else {
unreachable!()
};
super::quarantine_bad_snapshot(directory, snapshot_path, bytes, reason, detail)
}
fn build_snapshot(snapshot_input: SnapshotBuildInput, project_root: &Path) -> IndexSnapshot {
let canonical_root = project_root.canonicalize().unwrap();
let project_id = crate::discovery::project_id_for_canonical_root(&canonical_root);
super::build_snapshot(snapshot_input, project_root, project_id).unwrap()
}
fn make_symbol(name: &str) -> SymbolRecord {
let byte_range = (0, 10);
SymbolRecord {
name: name.to_string(),
kind: SymbolKind::Function,
depth: 0,
sort_order: 0,
byte_range,
item_byte_range: Some(byte_range),
line_range: (0, 1),
doc_byte_range: None,
}
}
fn make_reference(name: &str) -> ReferenceRecord {
ReferenceRecord {
name: name.to_string(),
qualified_name: None,
kind: ReferenceKind::Call,
byte_range: (5, 10),
line_range: (0, 0),
enclosing_symbol_index: None,
}
}
fn make_indexed_file(path: &str, content: &[u8]) -> IndexedFile {
let mut alias_map = HashMap::new();
alias_map.insert("Alias".to_string(), "Original".to_string());
IndexedFile {
relative_path: path.to_string(),
language: LanguageId::Rust,
classification: crate::domain::FileClassification::for_code_path(path),
content: content.to_vec(),
symbols: vec![make_symbol("my_func")],
parse_status: ParseStatus::Parsed,
parse_diagnostic: None,
byte_len: content.len() as u64,
content_hash: crate::hash::digest_hex(content),
references: vec![make_reference("other_func")],
alias_map,
mtime_secs: 0,
}
}
fn make_live_index_with_files(files: Vec<(&str, &[u8])>) -> LiveIndex {
let mut file_map: HashMap<String, Arc<IndexedFile>> = HashMap::new();
for (path, content) in files {
file_map.insert(path.to_string(), Arc::new(make_indexed_file(path, content)));
}
let trigram_index = crate::live_index::trigram::TrigramIndex::build_from_files(&file_map);
let mut index = LiveIndex {
files: file_map,
loaded_at: Instant::now(),
loaded_at_system: SystemTime::now(),
load_duration: Duration::ZERO,
cb_state: CircuitBreakerState::new(0.20),
is_empty: false,
load_source: IndexLoadSource::FreshLoad,
snapshot_verify_state: SnapshotVerifyState::NotNeeded,
reverse_index: HashMap::new(),
files_by_basename: HashMap::new(),
files_by_dir_component: HashMap::new(),
trigram_index,
gitignore: None,
manifest_entries: Vec::new(),
coupling_store: None,
local_empty_reason: Arc::new(parking_lot::RwLock::new(None)),
indexed_root: None,
};
index.rebuild_reverse_index();
index.rebuild_path_indices();
index
}
fn user_local_placement(source_root: &Path, directory: &Path) -> StatePlacement {
let canonical_root = dunce::canonicalize(source_root).unwrap();
StatePlacement::UserLocal {
directory: ProjectStateDir::new(directory.to_path_buf()),
root_id: crate::discovery::project_id_for_canonical_root(&canonical_root),
reason: UserLocalPlacementReason::ProjectLocalUnavailable {
safe_reason: AccessErrorKind::PermissionDenied,
},
}
}
fn routed_quarantine_files(state_dir: &Path, extension: &str) -> Vec<PathBuf> {
let directory = state_dir.join("quarantine").join("index-snapshots");
let mut files = std::fs::read_dir(directory)
.into_iter()
.flatten()
.flatten()
.map(|entry| entry.path())
.filter(|path| path.extension().and_then(|value| value.to_str()) == Some(extension))
.collect::<Vec<_>>();
files.sort();
files
}
#[test]
fn global_state_identity_mismatch_is_never_loaded_or_overwritten() {
let source_a = TempDir::new().unwrap();
let source_b = TempDir::new().unwrap();
let global_state = TempDir::new().unwrap();
let shared_state_dir = global_state
.path()
.join("projects")
.join("forced-collision");
std::fs::create_dir_all(&shared_state_dir).unwrap();
let placement_a = user_local_placement(source_a.path(), &shared_state_dir);
let placement_b = user_local_placement(source_b.path(), &shared_state_dir);
let index_a = make_live_index_with_files(vec![("src/a.rs", b"fn a() {}\n")]);
let index_b = make_live_index_with_files(vec![("src/b.rs", b"fn b() {}\n")]);
serialize_index_with_placement(&index_a, source_a.path(), &placement_a).unwrap();
let active_snapshot = shared_state_dir.join(INDEX_FILENAME);
let foreign_bytes = std::fs::read(&active_snapshot).unwrap();
let overwrite = serialize_index_with_placement(&index_b, source_b.path(), &placement_b);
assert!(
overwrite.is_err(),
"a different source identity sharing a user-local placement must not overwrite foreign state"
);
assert!(
!active_snapshot.exists(),
"foreign state must be removed from the active slot after quarantine"
);
assert!(
routed_quarantine_files(&shared_state_dir, "bin")
.iter()
.any(|path| std::fs::read(path).unwrap() == foreign_bytes),
"the refused foreign bytes must be preserved exactly in quarantine"
);
std::fs::write(&active_snapshot, &foreign_bytes).unwrap();
assert!(
super::load_snapshot(source_b.path(), &placement_b).is_none(),
"foreign user-local state must never be loaded"
);
assert!(
!active_snapshot.exists(),
"foreign load candidate must leave the active slot quarantined"
);
assert!(
routed_quarantine_files(&shared_state_dir, "bin")
.iter()
.filter(|path| std::fs::read(path).unwrap() == foreign_bytes)
.count()
>= 2,
"both the refused overwrite and refused load must preserve the foreign bytes"
);
}
#[test]
fn snapshot_lifecycle_uses_resolved_state_placement_without_source_fallback() {
let source = TempDir::new().unwrap();
let global_state = TempDir::new().unwrap();
let state_dir = global_state.path().join("projects").join("project-v1-test");
std::fs::create_dir_all(&state_dir).unwrap();
let placement = user_local_placement(source.path(), &state_dir);
let source_state = source.path().join(".symforge");
std::fs::create_dir_all(&source_state).unwrap();
std::fs::write(source_state.join("sentinel"), b"source-owned\n").unwrap();
std::fs::create_dir_all(source.path().join("src")).unwrap();
std::fs::write(source.path().join("src/lib.rs"), b"pub fn routed() {}\n").unwrap();
let shared =
crate::live_index::LiveIndex::load_for_state_placement(source.path(), &placement)
.expect("rooted load");
assert!(
shared.published_generation().manifest.is_some(),
"rooted load must publish a vouched manifest before checkpoint"
);
super::checkpoint_shared_index(&shared, source.path(), &placement).unwrap();
let routed_snapshot = state_dir.join(INDEX_FILENAME);
assert!(routed_snapshot.is_file());
assert!(!source_state.join(INDEX_FILENAME).exists());
std::fs::write(&routed_snapshot, b"corrupt routed snapshot").unwrap();
assert!(super::load_snapshot(source.path(), &placement).is_none());
assert_eq!(routed_quarantine_files(&state_dir, "bin").len(), 1);
assert!(
!source_state.join("quarantine").exists(),
"quarantine must remain under the selected ProjectStateDir"
);
super::checkpoint_shared_index(&shared, source.path(), &placement).unwrap();
std::fs::write(state_dir.join(INDEX_TMP_FILENAME), b"stale temp").unwrap();
let report = super::reset_snapshot_state(source.path(), &placement).unwrap();
assert!(report.removed_count() >= 2);
assert!(!routed_snapshot.exists());
assert_eq!(
std::fs::read(source_state.join("sentinel")).unwrap(),
b"source-owned\n"
);
assert_eq!(
std::fs::read_dir(&source_state).unwrap().count(),
1,
"snapshot/reset/quarantine/checkpoint must not reconstruct source-local state"
);
}
#[test]
fn snapshot_round_trip_preserves_target_enum_and_catalog_dispositions() {
let tmp = TempDir::new().unwrap();
let content = b"fn main() {}\n";
let mut index = make_live_index_with_files(vec![("src/main.rs", content)]);
let entry = |path: &str, size: u64, disposition: FileDisposition| CatalogEntry {
path: CatalogPath {
public_id: path.to_string(),
normalized_utf8: Some(path.to_string()),
},
size,
language: LanguageId::from_extension(
Path::new(path)
.extension()
.and_then(|extension| extension.to_str())
.unwrap_or_default(),
),
classification: crate::domain::FileClassification::for_code_path(path),
disposition,
content_hash: None,
};
let expected = vec![
entry(
"docs/legacy.txt",
17,
FileDisposition::MetadataOnly {
reason: MetadataOnlyReason::UnsupportedTextEncoding,
},
),
entry(
"fixtures/oversized.bin",
50_000_000,
FileDisposition::HardSkip {
reason: HardSkipReason::PerFileCeiling,
},
),
entry(
"src/main.rs",
content.len() as u64,
FileDisposition::Indexed {
targets: IndexTargets::CodeAndKnowledge,
parse_status: crate::domain::index::ParseStatus::Parsed,
},
),
];
index.manifest_entries = expected.clone();
serialize_index(&index, tmp.path()).expect("serialize should succeed");
let snapshot = load_snapshot(tmp.path()).expect("fresh snapshot should load");
let loaded = snapshot_to_live_index(snapshot, tmp.path());
assert_eq!(loaded.manifest_entries, expected);
}
#[test]
fn test_round_trip_preserves_files_symbols_references_content() {
let tmp = TempDir::new().unwrap();
let content = b"fn my_func() { other_func(); }";
let index =
make_live_index_with_files(vec![("tests/generated/main.generated.rs", content)]);
serialize_index(&index, tmp.path()).expect("serialize should succeed");
let snapshot = load_snapshot(tmp.path()).expect("snapshot should load");
let loaded = snapshot_to_live_index(snapshot, tmp.path());
assert_eq!(loaded.files.len(), 1);
let file = loaded
.files
.get("tests/generated/main.generated.rs")
.expect("file should be present");
assert_eq!(file.content, content);
assert_eq!(file.symbols.len(), 1);
assert_eq!(file.symbols[0].name, "my_func");
assert_eq!(file.references.len(), 1);
assert_eq!(file.references[0].name, "other_func");
assert!(file.classification.is_code());
assert!(file.classification.is_test);
assert!(file.classification.is_generated);
assert_eq!(
file.alias_map.get("Alias").map(|s| s.as_str()),
Some("Original")
);
}
#[test]
fn test_round_trip_preserves_crlf_bytes_and_hash() {
let tmp = TempDir::new().unwrap();
let content = b"fn my_func() {\r\n other_func();\r\n}\r\n";
let index =
make_live_index_with_files(vec![("tests/generated/main.generated.rs", content)]);
serialize_index(&index, tmp.path()).expect("serialize should succeed");
let snapshot = load_snapshot(tmp.path()).expect("snapshot should load");
let loaded = snapshot_to_live_index(snapshot, tmp.path());
let file = loaded
.files
.get("tests/generated/main.generated.rs")
.expect("file should be present");
assert_eq!(file.content, content);
assert_eq!(file.byte_len, content.len() as u64);
assert_eq!(file.content_hash, crate::hash::digest_hex(content));
}
#[test]
fn test_round_trip_empty_index() {
let tmp = TempDir::new().unwrap();
let index = make_live_index_with_files(vec![]);
serialize_index(&index, tmp.path()).expect("serialize empty index should succeed");
let snapshot = load_snapshot(tmp.path()).expect("snapshot should load");
let loaded = snapshot_to_live_index(snapshot, tmp.path());
assert_eq!(loaded.files.len(), 0);
}
#[test]
fn test_snapshot_to_live_index_marks_snapshot_restore_pending_verify() {
let tmp = TempDir::new().unwrap();
let index = make_live_index_with_files(vec![("src/main.rs", b"fn main() {}")]);
serialize_index(&index, tmp.path()).expect("serialize should succeed");
let snapshot = load_snapshot(tmp.path()).expect("snapshot should load");
let loaded = snapshot_to_live_index(snapshot, tmp.path());
assert_eq!(loaded.load_source(), IndexLoadSource::SnapshotRestore);
assert_eq!(loaded.snapshot_verify_state(), SnapshotVerifyState::Pending);
}
#[test]
fn snapshot_store_restore_promotes_when_disk_matches() {
use crate::index_lifecycle::snapshot::RestoreOutcome;
let tmp = TempDir::new().unwrap();
std::fs::create_dir_all(tmp.path().join("src")).unwrap();
std::fs::write(tmp.path().join("src/main.rs"), b"fn main() {}\n").unwrap();
let index = make_live_index_with_files(vec![("src/main.rs", b"fn main() {}\n")]);
serialize_index(&index, tmp.path()).expect("serialize");
let snapshot = load_snapshot(tmp.path()).expect("snapshot");
let wire = std::fs::read(tmp.path().join(".symforge/index.bin")).unwrap();
let proof = snapshot_store_restore_proof_for_test(&snapshot, tmp.path(), Some(&wire));
assert_eq!(proof.outcome, Ok(RestoreOutcome::Promoted { sources: 1 }));
assert!(!proof.rebuild_required);
}
#[test]
fn snapshot_store_restore_latches_rebuild_when_disk_differs_but_hydrates() {
use crate::index_lifecycle::snapshot::RestoreOutcome;
let tmp = TempDir::new().unwrap();
std::fs::create_dir_all(tmp.path().join("src")).unwrap();
std::fs::write(tmp.path().join("src/main.rs"), b"fn main() {}\n").unwrap();
let index = make_live_index_with_files(vec![("src/main.rs", b"fn main() {}\n")]);
serialize_index(&index, tmp.path()).expect("serialize");
let snapshot = load_snapshot(tmp.path()).expect("snapshot");
let wire = std::fs::read(tmp.path().join(".symforge/index.bin")).unwrap();
std::fs::write(tmp.path().join("src/main.rs"), b"fn main() { 99 }\n").unwrap();
let proof = snapshot_store_restore_proof_for_test(&snapshot, tmp.path(), Some(&wire));
assert_eq!(
proof.outcome,
Ok(RestoreOutcome::SeedRejected { unproven: 1 })
);
assert!(proof.rebuild_required);
let loaded = snapshot_to_live_index(snapshot, tmp.path());
assert_eq!(
loaded.files.len(),
1,
"hydrated map kept for background_verify"
);
assert_eq!(
loaded.snapshot_verify_state(),
SnapshotVerifyState::Pending,
"aggregate verify state stays Pending until background_verify"
);
assert!(
loaded.files.contains_key("src/main.rs"),
"background_verify must see snapshot bytes in the hydrated map"
);
}
#[test]
fn snapshot_store_restore_proves_team_artifact_without_index_bin() {
use crate::index_lifecycle::snapshot::RestoreOutcome;
let tmp = TempDir::new().unwrap();
std::fs::create_dir_all(tmp.path().join("src")).unwrap();
std::fs::write(tmp.path().join("src/main.rs"), b"fn main() {}\n").unwrap();
let index = make_live_index_with_files(vec![("src/main.rs", b"fn main() {}\n")]);
export_artifact_legacy(&index, tmp.path()).expect("export artifact");
let index_bin = tmp.path().join(".symforge/index.bin");
if index_bin.exists() {
std::fs::remove_file(&index_bin)
.expect("remove index.bin for team-artifact warm start");
}
assert!(
tmp.path().join(".symforge/index.bin.zst").exists(),
"team artifact must exist without index.bin"
);
let snapshot = load_snapshot(tmp.path()).expect("import team artifact");
let proof = snapshot_store_restore_proof_for_test(&snapshot, tmp.path(), None);
assert_eq!(
proof.outcome,
Ok(RestoreOutcome::Promoted { sources: 1 }),
"Promoted requires SnapshotStore prove, not a missing-wire shortcut"
);
assert!(
!proof.rebuild_required,
"all-proven team-artifact warm start must not latch rebuild"
);
}
#[test]
fn snapshot_store_restore_rejects_source_identity_without_store_quarantine() {
use crate::index_lifecycle::snapshot::RestoreOutcome;
let tmp = TempDir::new().unwrap();
std::fs::create_dir_all(tmp.path().join("src")).unwrap();
std::fs::write(tmp.path().join("src/main.rs"), b"fn main() {}\n").unwrap();
let index = make_live_index_with_files(vec![("src/main.rs", b"fn main() {}\n")]);
serialize_index(&index, tmp.path()).expect("serialize");
let mut snapshot = load_snapshot(tmp.path()).expect("snapshot");
let wire = std::fs::read(tmp.path().join(".symforge/index.bin")).unwrap();
snapshot.source_identity.indexed_content_digest = "deadbeef".to_string();
let proof = snapshot_store_restore_proof_for_test(&snapshot, tmp.path(), Some(&wire));
assert_eq!(
proof.outcome,
Ok(RestoreOutcome::SeedRejected { unproven: 1 }),
"source identity mismatch must reject the seed, not costume-quarantine id 0"
);
assert!(proof.rebuild_required);
}
#[test]
fn snapshot_store_restore_quarantines_seed_digest_mismatch() {
use crate::index_lifecycle::snapshot::{RestoreOutcome, SnapshotStore};
let tmp = TempDir::new().unwrap();
std::fs::create_dir_all(tmp.path().join("src")).unwrap();
std::fs::write(tmp.path().join("src/main.rs"), b"fn main() {}\n").unwrap();
let index = make_live_index_with_files(vec![("src/main.rs", b"fn main() {}\n")]);
serialize_index(&index, tmp.path()).expect("serialize");
let snapshot = load_snapshot(tmp.path()).expect("snapshot");
let wire = std::fs::read(tmp.path().join(".symforge/index.bin")).unwrap();
let (mut seed, source_to_path) =
super::build_snapshot_seed_from_index(&snapshot, wire.len() as u64);
seed.root_digest ^= 1;
let limit = super::snapshot_restore_decode_capacity(&snapshot, wire.len() as u64);
let files = &snapshot.files;
let root = tmp.path().to_path_buf();
let mut store = SnapshotStore::new();
let outcome = store.restore(
seed,
limit,
|entry| *entry,
|source, stamp| {
super::prove_snapshot_entry_on_disk(&root, &source_to_path, files, source, stamp)
},
);
assert!(
matches!(outcome, Ok(RestoreOutcome::Quarantined { id: 0 })),
"digest mismatch must quarantine inside SnapshotStore, got {outcome:?}"
);
assert!(store.rebuild_required());
assert!(store.quarantine_metadata().iter().any(|meta| meta.id == 0));
}
#[test]
fn verifying_snapshot_is_not_query_ready() {
let tmp = TempDir::new().unwrap();
let index = make_live_index_with_files(vec![("src/main.rs", b"fn main() {}\n")]);
serialize_index(&index, tmp.path()).expect("serialize should succeed");
let snapshot = load_snapshot(tmp.path()).expect("snapshot should load");
let shared = crate::live_index::SharedIndexHandle::shared(snapshot_to_live_index(
snapshot,
tmp.path(),
));
assert_eq!(
shared.read().snapshot_verify_state(),
SnapshotVerifyState::Pending
);
assert!(
!shared.read().is_ready(),
"an unverified snapshot candidate must not be query-ready"
);
assert!(
shared.read().get_file("src/main.rs").is_none(),
"an unverified snapshot seed must not answer get_file"
);
assert_ne!(
shared.published_state().status,
crate::live_index::store::PublishedIndexStatus::Ready
);
assert_eq!(
&*shared.freshness_status(),
&crate::domain::FreshnessStatus::Verifying
);
}
#[tokio::test]
async fn test_background_verify_marks_snapshot_verify_completed() {
let tmp = TempDir::new().unwrap();
let file_path = tmp.path().join("src").join("main.rs");
std::fs::create_dir_all(file_path.parent().unwrap()).unwrap();
std::fs::write(&file_path, b"fn main() {}\n").unwrap();
let index = make_live_index_with_files(vec![("src/main.rs", b"fn main() {}\n")]);
serialize_index(&index, tmp.path()).expect("serialize should succeed");
let snapshot = load_snapshot(tmp.path()).expect("snapshot should load");
let snapshot_mtimes = snapshot
.files
.iter()
.map(|(path, file)| (path.clone(), file.mtime_secs))
.collect::<HashMap<_, _>>();
let loaded = snapshot_to_live_index(snapshot, tmp.path());
let shared = crate::live_index::SharedIndexHandle::shared(loaded);
{
let guard = shared.read();
assert_eq!(guard.load_source(), IndexLoadSource::SnapshotRestore);
assert_eq!(guard.snapshot_verify_state(), SnapshotVerifyState::Pending);
}
let before = shared.published_state();
assert_eq!(before.file_count, 1);
assert_eq!(before.partial_parse_count, 0);
assert_eq!(before.failed_count, 0);
background_verify(
shared.clone(),
tmp.path().to_path_buf(),
snapshot_mtimes,
verify_observer(tmp.path()),
)
.await;
let guard = shared.read();
assert_eq!(guard.load_source(), IndexLoadSource::SnapshotRestore);
assert_eq!(
guard.snapshot_verify_state(),
SnapshotVerifyState::completed_without_mismatches()
);
drop(guard);
let published = shared.published_state();
assert_eq!(
published.snapshot_verify_state,
SnapshotVerifyState::completed_without_mismatches()
);
assert!(
published.generation >= 2,
"expected published generation to advance through verify transitions"
);
assert_eq!(published.file_count, before.file_count);
assert_eq!(published.partial_parse_count, before.partial_parse_count);
assert_eq!(published.failed_count, before.failed_count);
}
#[tokio::test]
async fn background_verify_refuses_replaced_original_source_root() {
let tmp = TempDir::new().unwrap();
let root = tmp.path().join("source");
let replacement = tmp.path().join("replacement");
let displaced = tmp.path().join("displaced");
for directory in [&root, &replacement] {
std::fs::create_dir_all(directory.join("src")).unwrap();
std::fs::write(directory.join("src/main.rs"), b"fn main() {}\n").unwrap();
}
let index = make_live_index_with_files(vec![("src/main.rs", b"fn main() {}\n")]);
serialize_index(&index, &root).unwrap();
let snapshot = load_snapshot(&root).unwrap();
let snapshot_mtimes = snapshot
.files
.iter()
.map(|(path, file)| (path.clone(), file.mtime_secs))
.collect::<HashMap<_, _>>();
let shared =
crate::live_index::SharedIndexHandle::shared(snapshot_to_live_index(snapshot, &root));
let observer = verify_observer(&root);
background_verify_with_hook(
shared.clone(),
root.clone(),
snapshot_mtimes,
observer,
move || {
std::fs::rename(&root, &displaced).unwrap();
std::fs::rename(&replacement, &root).unwrap();
},
|| false,
)
.await;
assert!(
!matches!(
shared.read().snapshot_verify_state(),
SnapshotVerifyState::Completed(_)
),
"verification must not certify bytes from a replacement physical root"
);
}
#[test]
fn snapshot_restore_proof_refuses_replaced_original_source_root() {
let tmp = TempDir::new().unwrap();
let root = tmp.path().join("source");
let replacement = tmp.path().join("replacement");
let displaced = tmp.path().join("displaced");
for directory in [&root, &replacement] {
std::fs::create_dir_all(directory.join("src")).unwrap();
std::fs::write(directory.join("src/main.rs"), b"fn main() {}\n").unwrap();
}
let index = make_live_index_with_files(vec![("src/main.rs", b"fn main() {}\n")]);
serialize_index(&index, &root).unwrap();
let snapshot = load_snapshot(&root).unwrap();
let retained_authority =
crate::live_index::index_lifecycle::activation::project_source_authority(&root);
std::fs::rename(&root, &displaced).unwrap();
std::fs::rename(&replacement, &root).unwrap();
let proof = run_snapshot_store_restore_proof_bound(&snapshot, &root, &retained_authority);
assert_eq!(proof, Err(BoundRestoreRefusal::SourceMoved));
}
#[test]
fn admitted_dismissal_digest_refuses_store_not_root() {
let tmp = TempDir::new().unwrap();
let root = tmp.path().join("source");
let replacement = tmp.path().join("replacement");
for directory in [&root, &replacement] {
std::fs::create_dir_all(directory).unwrap();
std::fs::write(directory.join(".symforge"), b"not a directory").unwrap();
}
let authority =
crate::live_index::index_lifecycle::activation::project_source_authority(&root);
assert_eq!(
admitted_dismissal_store_digest(&authority),
Ok("refused".to_string()),
"an unreadable dismissal store must not read as a moved root"
);
std::fs::rename(&root, tmp.path().join("displaced")).unwrap();
std::fs::rename(&replacement, &root).unwrap();
assert_eq!(
admitted_dismissal_store_digest(&authority),
Err(BoundRestoreRefusal::SourceMoved),
"a replaced root must still refuse"
);
}
#[tokio::test(flavor = "current_thread")]
async fn snapshot_restore_rebuilds_current_authority_versions_before_ready() {
let tmp = TempDir::new().unwrap();
std::fs::write(tmp.path().join("README.md"), b"# Restored\nbody\n").unwrap();
let shared = LiveIndex::load(tmp.path()).unwrap();
checkpoint_shared_index(&shared, tmp.path(), &project_local_placement(tmp.path())).unwrap();
let snapshot = load_snapshot(tmp.path()).expect("snapshot should load");
let snapshot_mtimes = snapshot
.files
.iter()
.map(|(path, file)| (path.clone(), file.mtime_secs))
.collect::<HashMap<_, _>>();
let (live, code_signals) = snapshot_to_live_index_with_code_signals(snapshot, tmp.path());
let restored =
crate::live_index::SharedIndexHandle::shared_with_code_signals(live, code_signals);
assert!(!restored.read().is_ready());
let before_ready = restored.published_generation();
assert_eq!(
before_ready.authority.versions.authority_rule_version,
crate::live_index::knowledge_authority::AUTHORITY_RULE_VERSION
);
assert_eq!(
before_ready.authority.versions.policy_version,
crate::live_index::knowledge_authority::KNOWLEDGE_POLICY_VERSION
);
assert_eq!(
before_ready.authority.versions.secret_policy_version,
crate::knowledge::SECRET_POLICY_VERSION
);
assert!(!before_ready.authority.records.is_empty());
background_verify(
restored.clone(),
tmp.path().to_path_buf(),
snapshot_mtimes,
verify_observer(tmp.path()),
)
.await;
assert!(restored.read().is_ready());
let ready = restored.published_generation();
assert_eq!(ready.authority.versions, before_ready.authority.versions);
assert_eq!(ready.authority.records, before_ready.authority.records);
}
#[cfg(feature = "server")]
#[tokio::test]
async fn background_verify_observes_admissions_under_the_carried_incarnation() {
let tmp = TempDir::new().unwrap();
let file_path = tmp.path().join("src").join("fresh.rs");
std::fs::create_dir_all(file_path.parent().unwrap()).unwrap();
std::fs::write(&file_path, b"pub fn fresh() {}\n").unwrap();
let authority =
crate::live_index::index_lifecycle::activation::project_source_authority(tmp.path());
let observer = authority.register_observer();
let before = authority.committed_observations("src/fresh.rs");
let shared =
crate::live_index::SharedIndexHandle::shared(make_live_index_with_files(Vec::new()));
background_verify(
shared.clone(),
tmp.path().to_path_buf(),
HashMap::new(),
observer,
)
.await;
assert!(
shared.read().files.contains_key("src/fresh.rs"),
"the new file must be re-indexed by the verify sweep"
);
assert_eq!(
authority.committed_observations("src/fresh.rs"),
before + 1,
"a verify re-admission must be observed under the carried incarnation"
);
std::fs::write(&file_path, b"pub fn fresh() { let _ = 1; }\n").unwrap();
let _successor = authority.register_observer();
background_verify(
shared.clone(),
tmp.path().to_path_buf(),
HashMap::new(),
observer,
)
.await;
assert!(
shared
.read()
.files
.get("src/fresh.rs")
.is_some_and(|file| file.content == b"pub fn fresh() { let _ = 1; }\n"),
"the stale-incarnation sweep still reconciles the data plane (C4 residual)"
);
assert_eq!(
authority.committed_observations("src/fresh.rs"),
before + 1,
"a stale incarnation must not land observations"
);
}
#[cfg(feature = "server")]
#[tokio::test]
async fn background_verify_uses_shared_admission_for_large_new_file() {
let tmp = TempDir::new().unwrap();
let relative_path = "src/oversized.rs";
let file_path = tmp.path().join("src").join("oversized.rs");
std::fs::create_dir_all(file_path.parent().unwrap()).unwrap();
let file = std::fs::File::create(&file_path).unwrap();
file.set_len(crate::domain::index::METADATA_ONLY_CODE_BYTES + 1)
.unwrap();
drop(file);
let shared =
crate::live_index::SharedIndexHandle::shared(make_live_index_with_files(Vec::new()));
background_verify(
shared.clone(),
tmp.path().to_path_buf(),
HashMap::new(),
verify_observer(tmp.path()),
)
.await;
let guard = shared.read();
assert!(
!guard.files.contains_key(relative_path),
"metadata-terminal files must never enter resident content"
);
let disposition = guard
.manifest_entries
.iter()
.find(|entry| entry.path.normalized_utf8.as_deref() == Some(relative_path))
.map(|entry| &entry.disposition);
assert!(
matches!(
disposition,
Some(FileDisposition::MetadataOnly {
reason: MetadataOnlyReason::OversizedData
})
),
"background verification must publish the shared metadata-first admission outcome"
);
}
#[cfg(feature = "server")]
#[tokio::test]
async fn cold_watch_reconcile_and_background_verify_have_identical_knowledge_units_and_dispositions()
{
let tmp = TempDir::new().unwrap();
std::fs::write(tmp.path().join("README.md"), b"# Root\n## Child\nbody\n").unwrap();
std::fs::write(tmp.path().join("guide.rst"), b"Guide\n=====\nbody\n").unwrap();
std::fs::write(tmp.path().join("settings.toml"), b"enabled = true\n").unwrap();
std::fs::write(tmp.path().join(".env"), b"placeholder=true\n").unwrap();
std::fs::write(tmp.path().join("invalid.txt"), [0xff, 0xfe, b'x']).unwrap();
std::fs::write(
tmp.path().join("pointer.md"),
b"version https://git-lfs.github.com/spec/v1\noid sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef\nsize 42\n",
)
.unwrap();
let detector_payload = format!(
"{}={}\n",
["to", "ken"].concat(),
["runtime", "-", "canary", "-", "parity"].concat()
);
std::fs::write(tmp.path().join(".env.example"), detector_payload.as_bytes()).unwrap();
let source = SourceIdentity {
repository_id: RepositoryId::new("repository-fixture"),
source_id: SourceId::new("source-fixture"),
location: crate::domain::SourceLocation::WorkingTree {
worktree_id: "worktree-fixture".to_string(),
},
};
let make_empty_shared = || {
let mut index = make_live_index_with_files(Vec::new());
index.indexed_root = Some(tmp.path().to_path_buf());
crate::live_index::SharedIndexHandle::shared(index)
};
let capture = |shared: &crate::live_index::store::SharedIndex| {
let index = shared.read();
let mut manifest = index.manifest_entries.clone();
manifest.sort_by_key(|entry| {
entry
.path
.normalized_utf8
.clone()
.unwrap_or_else(|| entry.path.public_id.clone())
});
let mut units = index
.files
.values()
.filter(|file| file.language == LanguageId::Markdown)
.flat_map(|file| {
crate::knowledge::project_markdown_sections(
&source,
&file.relative_path,
&file.content_hash,
&file.symbols,
)
})
.collect::<Vec<_>>();
units.sort_by_key(|unit| (unit.path.clone(), unit.byte_range.start));
let authority = shared.published_generation().authority.clone();
let mut authority_records = authority.records.clone();
for record in &mut authority_records {
record.unit.content_generation = 0;
if let crate::live_index::knowledge_authority::LifecycleEvidence::DeclaredSpan(
anchor,
) = &mut record.lifecycle_evidence
{
anchor.content_generation = 0;
}
match &mut record.authority_domain_evidence {
crate::live_index::knowledge_authority::AuthorityDomainEvidence::DeclaredSpan(
anchor,
)
| crate::live_index::knowledge_authority::AuthorityDomainEvidence::RoleRule {
anchor,
..
} => anchor.content_generation = 0,
_ => {}
}
if let Some(successor) = &mut record.successor {
successor.content_generation = 0;
}
}
(
manifest,
units,
authority_records,
authority.policy_status.clone(),
authority.coverage.clone(),
)
};
let cold = LiveIndex::load(tmp.path()).unwrap();
let watch = make_empty_shared();
let expected_gen = watch.current_project_generation();
for relative_path in [
".env",
".env.example",
"README.md",
"guide.rst",
"invalid.txt",
"pointer.md",
"settings.toml",
] {
let absolute_path = tmp.path().join(relative_path);
let _ = crate::live_index::single_file::admit_and_index_single_path(
relative_path,
&absolute_path,
&watch,
expected_gen,
);
}
let reconcile = make_empty_shared();
crate::watcher::reconcile_stale_files(tmp.path(), &reconcile);
let background = make_empty_shared();
background_verify(
background.clone(),
tmp.path().to_path_buf(),
HashMap::new(),
verify_observer(tmp.path()),
)
.await;
let expected = capture(&cold);
assert_eq!(capture(&watch), expected);
assert_eq!(capture(&reconcile), expected);
assert_eq!(capture(&background), expected);
}
#[tokio::test]
async fn background_verify_cannot_mutate_after_project_retarget() {
let tmp = TempDir::new().unwrap();
let new_file = tmp.path().join("src").join("new.rs");
std::fs::create_dir_all(new_file.parent().unwrap()).unwrap();
std::fs::write(&new_file, b"fn new_project() {}\n").unwrap();
let shared = crate::live_index::SharedIndexHandle::shared(make_live_index_with_files(
vec![("src/old.rs", b"fn old_project() {}\n")],
));
let initial_project_generation = shared.current_project_generation();
let reset_publication_generation = Arc::new(std::sync::atomic::AtomicU64::new(0));
background_verify_with_hook(
shared.clone(),
tmp.path().to_path_buf(),
HashMap::new(),
verify_observer(tmp.path()),
{
let shared = shared.clone();
let reset_publication_generation = reset_publication_generation.clone();
move || {
shared.reset_to_empty();
reset_publication_generation.store(
shared.published_state().generation,
std::sync::atomic::Ordering::SeqCst,
);
}
},
|| false,
)
.await;
assert_eq!(
shared.current_project_generation(),
initial_project_generation + 1
);
let published = shared.published_state();
assert_eq!(
published.generation,
reset_publication_generation.load(std::sync::atomic::Ordering::SeqCst),
"a verifier captured for the prior project must not publish into the replacement"
);
assert_eq!(
published.snapshot_verify_state,
SnapshotVerifyState::NotNeeded,
"the replacement project must retain its own verification state"
);
assert_eq!(published.file_count, 0);
}
fn restore_for_verify(
index: &LiveIndex,
root: &Path,
) -> (crate::live_index::store::SharedIndex, HashMap<String, u64>) {
serialize_index(index, root).expect("serialize should succeed");
let snapshot = load_snapshot(root).expect("snapshot should load");
let snapshot_mtimes = snapshot
.files
.iter()
.map(|(path, file)| (path.clone(), file.mtime_secs))
.collect::<HashMap<_, _>>();
let shared =
crate::live_index::SharedIndexHandle::shared(snapshot_to_live_index(snapshot, root));
(shared, snapshot_mtimes)
}
#[cfg(feature = "server")]
#[tokio::test]
async fn background_verify_racing_watcher_update_rebases_or_aborts() {
const WATCHER_BYTES: &[u8] = b"fn watcher_newer_than_the_verify_read() {}\n";
const REWRITTEN_BYTES: &[u8] = b"fn base_rewritten_after_the_verify_read_it() {}\n";
let tmp = TempDir::new().unwrap();
std::fs::create_dir_all(tmp.path().join("src")).unwrap();
std::fs::write(tmp.path().join("src/base.rs"), b"fn base_on_disk() {}\n").unwrap();
std::fs::write(tmp.path().join("src/watcher.rs"), b"fn watcher_disk() {}\n").unwrap();
let (shared, snapshot_mtimes) = restore_for_verify(
&make_live_index_with_files(vec![("src/base.rs", b"fn base() {}\n")]),
tmp.path(),
);
let base_project_generation = shared.current_project_generation();
let polls = Arc::new(std::sync::atomic::AtomicUsize::new(0));
let watcher_publication = Arc::new(std::sync::atomic::AtomicU64::new(0));
let watcher_content = Arc::new(std::sync::atomic::AtomicU64::new(0));
background_verify_with_hook(
shared.clone(),
tmp.path().to_path_buf(),
snapshot_mtimes,
verify_observer(tmp.path()),
{
let shared = shared.clone();
move || shared.set_freshness_status(crate::domain::FreshnessStatus::Verifying)
},
{
let shared = shared.clone();
let root = tmp.path().to_path_buf();
let polls = polls.clone();
let watcher_publication = watcher_publication.clone();
let watcher_content = watcher_content.clone();
move || {
if polls.fetch_add(1, std::sync::atomic::Ordering::SeqCst) + 1 != 3 {
return false;
}
let mut indexed = make_indexed_file("src/watcher.rs", WATCHER_BYTES);
indexed.mtime_secs = 1;
assert!(shared.update_file_at_generation(
"src/watcher.rs",
indexed,
base_project_generation,
));
let watcher = shared.published_generation();
watcher_publication.store(
watcher.publication_generation,
std::sync::atomic::Ordering::SeqCst,
);
watcher_content.store(
watcher.content_generation,
std::sync::atomic::Ordering::SeqCst,
);
std::fs::write(root.join("src/base.rs"), REWRITTEN_BYTES).unwrap();
false
}
},
)
.await;
let current = shared.published_generation();
assert_eq!(current.project_generation, base_project_generation);
match ¤t.live.snapshot_verify_state {
SnapshotVerifyState::Completed(report) => assert_eq!(
report.mismatch_count, 0,
"both racing writes are reconciled: {report:?}"
),
other => panic!("the racing writes stranded the verify in {other:?}"),
}
assert!(
polls.load(std::sync::atomic::Ordering::SeqCst) >= 4,
"the refused path must have been retried after the publication"
);
assert!(
current.publication_generation
> watcher_publication.load(std::sync::atomic::Ordering::SeqCst),
"the verify must still publish after the watcher's publication"
);
assert!(
current.content_generation > watcher_content.load(std::sync::atomic::Ordering::SeqCst),
"the verify's publication must carry content past the watcher's"
);
assert_eq!(
current.live.files["src/watcher.rs"].content, WATCHER_BYTES,
"a row republished after the verify read it is superseded, not overwritten \
with the older disk bytes the verify read"
);
assert_eq!(
current.live.files["src/base.rs"].content, REWRITTEN_BYTES,
"a file rewritten after the verify read it is refused and re-read from disk"
);
assert!(
!current
.freshness
.as_ref()
.eq(&crate::domain::FreshnessStatus::Verifying),
"freshness must leave Verifying once the verify returns, observed {:?}",
current.freshness
);
}
#[tokio::test]
async fn background_verify_stops_without_publishing_once_its_slot_stops() {
let tmp = TempDir::new().unwrap();
std::fs::create_dir_all(tmp.path().join("src")).unwrap();
std::fs::write(tmp.path().join("src/a.rs"), b"fn changed_on_disk() {}\n").unwrap();
let (shared, snapshot_mtimes) = restore_for_verify(
&make_live_index_with_files(vec![("src/a.rs", b"fn restored() {}\n")]),
tmp.path(),
);
let running_publication = Arc::new(std::sync::atomic::AtomicU64::new(0));
let polls = Arc::new(std::sync::atomic::AtomicUsize::new(0));
background_verify_with_hook(
shared.clone(),
tmp.path().to_path_buf(),
snapshot_mtimes,
verify_observer(tmp.path()),
{
let shared = shared.clone();
let running_publication = running_publication.clone();
move || {
running_publication.store(
shared.published_generation().publication_generation,
std::sync::atomic::Ordering::SeqCst,
);
}
},
{
let polls = polls.clone();
move || polls.fetch_add(1, std::sync::atomic::Ordering::SeqCst) >= 1
},
)
.await;
let current = shared.published_generation();
assert_eq!(
current.publication_generation,
running_publication.load(std::sync::atomic::Ordering::SeqCst),
"a cancelled verify must not publish after its running mark"
);
assert!(matches!(
current.live.snapshot_verify_state,
SnapshotVerifyState::Running(_)
));
assert_eq!(
current.live.files["src/a.rs"].content,
b"fn restored() {}\n"
);
assert_eq!(polls.load(std::sync::atomic::Ordering::SeqCst), 2);
}
#[cfg(feature = "server")]
#[tokio::test]
async fn background_verify_contains_a_panicking_admission_to_its_path() {
const BOOM: &str = "src/snapshot_verify_injected_panic.rs";
struct ClearInjection;
impl Drop for ClearInjection {
fn drop(&mut self) {
*crate::live_index::store::snapshot_verify_test_panic_path().lock() = None;
}
}
let tmp = TempDir::new().unwrap();
std::fs::create_dir_all(tmp.path().join("src")).unwrap();
std::fs::write(tmp.path().join("src/ok.rs"), b"fn ok_on_disk() {}\n").unwrap();
std::fs::write(tmp.path().join(BOOM), b"fn boom_on_disk() {}\n").unwrap();
let (shared, snapshot_mtimes) = restore_for_verify(
&make_live_index_with_files(vec![
("src/ok.rs", b"fn ok() {}\n"),
(BOOM, b"fn boom() {}\n"),
]),
tmp.path(),
);
let _clear = ClearInjection;
*crate::live_index::store::snapshot_verify_test_panic_path().lock() =
Some(BOOM.to_string());
background_verify(
shared.clone(),
tmp.path().to_path_buf(),
snapshot_mtimes,
verify_observer(tmp.path()),
)
.await;
let live = shared.read();
match &live.snapshot_verify_state {
SnapshotVerifyState::Completed(report) => assert_eq!(
report.mismatch_count, 0,
"the panicking path was retried alone and reconciled: {report:?}"
),
other => panic!("one panicking admission must not end the pass: {other:?}"),
}
assert_eq!(live.files["src/ok.rs"].content, b"fn ok_on_disk() {}\n");
assert_eq!(live.files[BOOM].content, b"fn boom_on_disk() {}\n");
assert!(
live.reverse_index
.get("other_func")
.is_none_or(|locations| locations
.iter()
.all(|location| location.file_path != BOOM)),
"a half-applied row must not leave stale reverse-index entries"
);
}
#[tokio::test]
async fn background_verify_that_dies_keeps_the_seed_hidden_and_degraded() {
let tmp = TempDir::new().unwrap();
std::fs::create_dir_all(tmp.path().join("src")).unwrap();
std::fs::write(tmp.path().join("src/a.rs"), b"fn a() {}\n").unwrap();
let (shared, snapshot_mtimes) = restore_for_verify(
&make_live_index_with_files(vec![("src/a.rs", b"fn a() {}\n")]),
tmp.path(),
);
background_verify_with_hook(
shared.clone(),
tmp.path().to_path_buf(),
snapshot_mtimes,
verify_observer(tmp.path()),
|| panic!("injected: the snapshot verify task dies"),
|| false,
)
.await;
let live = shared.read();
match &live.snapshot_verify_state {
SnapshotVerifyState::Failed(report) => assert_eq!(
report.reason.as_deref(),
Some("the snapshot verify task failed before it finished")
),
other => panic!("a dead verify must resolve to Failed, got {other:?}"),
}
assert!(
live.get_file("src/a.rs").is_none(),
"an unverified restored row must stay hidden"
);
match live.index_state() {
crate::live_index::IndexState::CircuitBreakerTripped { summary } => assert!(
summary.contains("snapshot verify failed") && summary.contains("index_folder"),
"the degraded summary must name the failure and the way out: {summary}"
),
other => panic!("a dead verify must degrade the index, got {other:?}"),
}
drop(live);
assert_eq!(
shared.published_state().status,
crate::live_index::store::PublishedIndexStatus::Degraded
);
assert!(matches!(
shared.freshness_status().as_ref(),
crate::domain::FreshnessStatus::Degraded { reason_codes, .. }
if reason_codes.contains(&crate::domain::FreshnessReason::SnapshotVerificationFailed)
));
}
#[cfg(feature = "server")]
#[tokio::test]
async fn background_verify_counts_a_canonical_eviction_as_reconciled() {
let tmp = TempDir::new().unwrap();
std::fs::create_dir_all(tmp.path().join("src")).unwrap();
std::fs::create_dir_all(tmp.path().join(".git")).unwrap();
std::fs::write(tmp.path().join("src/a.rs"), b"fn a() {}\n").unwrap();
std::fs::write(tmp.path().join(".git/leak.rs"), b"fn leak_changed() {}\n").unwrap();
let (shared, snapshot_mtimes) = restore_for_verify(
&make_live_index_with_files(vec![
("src/a.rs", b"fn a() {}\n"),
(".git/leak.rs", b"fn leak() {}\n"),
]),
tmp.path(),
);
background_verify(
shared.clone(),
tmp.path().to_path_buf(),
snapshot_mtimes,
verify_observer(tmp.path()),
)
.await;
let live = shared.read();
match &live.snapshot_verify_state {
SnapshotVerifyState::Completed(report) => assert_eq!(
report.mismatch_count, 0,
"an eviction the seam completed is reconciled: {report:?}"
),
other => panic!("expected a completed verify, got {other:?}"),
}
assert!(!live.files.contains_key(".git/leak.rs"));
}
#[tokio::test]
async fn background_verify_reports_a_spot_check_read_failure() {
let tmp = TempDir::new().unwrap();
let dir = tmp.path().join("src").join("dir.rs");
std::fs::create_dir_all(&dir).unwrap();
let meta = std::fs::metadata(&dir).unwrap();
let content = vec![b' '; meta.len() as usize];
let (shared, mut snapshot_mtimes) = restore_for_verify(
&make_live_index_with_files(vec![("src/dir.rs", content.as_slice())]),
tmp.path(),
);
let dir_mtime = meta
.modified()
.unwrap()
.duration_since(UNIX_EPOCH)
.unwrap()
.as_secs();
snapshot_mtimes.insert("src/dir.rs".to_string(), dir_mtime);
background_verify(
shared.clone(),
tmp.path().to_path_buf(),
snapshot_mtimes,
verify_observer(tmp.path()),
)
.await;
let live = shared.read();
match &live.snapshot_verify_state {
SnapshotVerifyState::Completed(report) => {
assert_eq!(report.mismatched_paths, vec!["src/dir.rs".to_string()]);
#[cfg(any(feature = "server", feature = "embed"))]
{
assert!(
report.unverified.contains_key("src/dir.rs")
&& !live.files.contains_key("src/dir.rs"),
"{report:?}"
);
}
#[cfg(not(any(feature = "server", feature = "embed")))]
assert!(
report.reason.as_deref().is_some_and(
|reason| reason.contains("could not be read for the spot check")
),
"{report:?}"
);
}
other => panic!("expected a completed verify, got {other:?}"),
}
}
fn restored_with_offline_edits(
root: &Path,
files: usize,
edited: usize,
) -> (crate::live_index::store::SharedIndex, HashMap<String, u64>) {
for i in 0..files {
std::fs::write(
root.join(format!("f{i}.rs")),
format!("pub fn f{i}() {{}}\n"),
)
.unwrap();
}
let loaded = LiveIndex::load(root).unwrap();
checkpoint_shared_index(&loaded, root, &project_local_placement(root)).unwrap();
let snapshot = load_snapshot(root).expect("snapshot should load");
let snapshot_mtimes = snapshot
.files
.iter()
.map(|(path, file)| (path.clone(), file.mtime_secs))
.collect::<HashMap<_, _>>();
let restored =
crate::live_index::SharedIndexHandle::shared(snapshot_to_live_index(snapshot, root));
for i in 0..edited {
std::fs::write(
root.join(format!("f{i}.rs")),
format!("pub fn f{i}() {{ let _ = {i}; }}\n"),
)
.unwrap();
}
(restored, snapshot_mtimes)
}
#[cfg(feature = "server")]
#[tokio::test(flavor = "multi_thread")]
async fn fresh_instance_sweep_leaves_restored_rows_to_a_pending_verify_without_waiting() {
let tmp = TempDir::new().unwrap();
let (restored, snapshot_mtimes) = restored_with_offline_edits(tmp.path(), 5, 3);
let generation = restored.current_project_generation();
let started = Instant::now();
let repaired = crate::watcher::reconcile_stale_files_with_stop(
tmp.path(),
&restored,
|| false,
generation,
verify_observer(tmp.path()),
);
let waited = started.elapsed();
assert_eq!(repaired, 0, "the changed rows belong to the pending verify");
assert!(
waited < Duration::from_secs(2),
"the sweep must not wait on the verify, it took {waited:?}"
);
assert_eq!(restored.read().files["f0.rs"].content, b"pub fn f0() {}\n");
background_verify(
restored.clone(),
tmp.path().to_path_buf(),
snapshot_mtimes,
verify_observer(tmp.path()),
)
.await;
for i in 0..3 {
assert_eq!(
restored.read().files[&format!("f{i}.rs")].content,
format!("pub fn f{i}() {{ let _ = {i}; }}\n").into_bytes()
);
}
}
#[cfg(feature = "server")]
#[test]
fn fresh_instance_sweep_stands_down_for_a_failed_verify() {
let tmp = TempDir::new().unwrap();
let (restored, _) = restored_with_offline_edits(tmp.path(), 5, 1);
let generation = restored.current_project_generation();
assert!(restored.mark_snapshot_verify_started_at_generation(
generation,
SnapshotVerifyProgress::started(SystemTime::now(), 5),
));
assert!(restored.mark_snapshot_verify_failed_at_generation(
generation,
SnapshotVerifyReport::from_mismatched_paths(vec!["f0.rs".to_string()]),
));
let repaired = crate::watcher::reconcile_stale_files_with_stop(
tmp.path(),
&restored,
|| false,
generation,
verify_observer(tmp.path()),
);
assert_eq!(
repaired, 0,
"a failed verify's restored rows wait for index_folder"
);
assert_eq!(restored.read().files["f0.rs"].content, b"pub fn f0() {}\n");
assert!(matches!(
restored.read().snapshot_verify_state,
SnapshotVerifyState::Failed(_)
));
}
#[cfg(feature = "server")]
#[tokio::test]
async fn background_verify_withholds_a_scout_error_path_and_refuses_it_honestly() {
const BROKEN: &str = "f1.rs";
struct ClearInjection;
impl Drop for ClearInjection {
fn drop(&mut self) {
*crate::live_index::single_file::test_scout_failure_path().lock() = None;
}
}
let tmp = TempDir::new().unwrap();
let (shared, snapshot_mtimes) = restored_with_offline_edits(tmp.path(), 3, 2);
let _clear = ClearInjection;
*crate::live_index::single_file::test_scout_failure_path().lock() =
Some(BROKEN.to_string());
background_verify(
shared.clone(),
tmp.path().to_path_buf(),
snapshot_mtimes,
verify_observer(tmp.path()),
)
.await;
{
let live = shared.read();
assert_eq!(live.index_state(), crate::live_index::IndexState::Ready);
let reason = live
.unverified_since_restore(BROKEN)
.expect("the unreconciled path is recorded")
.to_string();
assert!(reason.contains("injected scout failure"), "{reason}");
assert!(
!live.files.contains_key(BROKEN),
"its restored row must not be served as current by any lane"
);
assert!(live.get_file(BROKEN).is_none());
assert!(
live.manifest_entries
.iter()
.any(|entry| entry.path.normalized_utf8.as_deref() == Some(BROKEN)),
"the file exists; its catalog entry stays"
);
assert_eq!(live.files["f0.rs"].content, b"pub fn f0() { let _ = 0; }\n");
let refusal = crate::protocol::read_gate::refuse_by_policy(&live, BROKEN)
.expect("a direct request is refused, not answered as absent");
assert!(
refusal.starts_with("Unverified since restore")
&& refusal.contains("injected scout failure")
&& refusal.contains("index_folder"),
"{refusal}"
);
let health = crate::protocol::format::snapshot_verify_status_line(
IndexLoadSource::SnapshotRestore,
&live.snapshot_verify_state,
)
.expect("a restore reports its verify");
assert!(
health.contains("unverified_since_restore=1")
&& health.contains(&format!("{BROKEN}: ")),
"{health}"
);
}
*crate::live_index::single_file::test_scout_failure_path().lock() = None;
let outcome = crate::live_index::single_file::maybe_reindex(
BROKEN,
&tmp.path().join(BROKEN),
&shared,
None::<LanguageId>,
shared.current_project_generation(),
);
assert_eq!(outcome, crate::watcher::ReindexResult::Reindexed);
let live = shared.read();
assert_eq!(live.files[BROKEN].content, b"pub fn f1() { let _ = 1; }\n");
assert!(live.unverified_since_restore(BROKEN).is_none());
assert!(crate::protocol::read_gate::refuse_by_policy(&live, BROKEN).is_none());
let status = crate::protocol::format::snapshot_verify_status_line(
IndexLoadSource::SnapshotRestore,
&live.snapshot_verify_state,
)
.expect("a restore reports its verify");
assert!(
!status.contains("withheld") && !status.contains("unverified_since_restore"),
"status must not report a released path as withheld: {status}"
);
}
#[cfg(feature = "server")]
#[tokio::test]
async fn background_verify_removes_a_file_gone_before_its_reread_in_the_one_publication() {
const GONE: &str = "src/gone_before_reread.rs";
let tmp = TempDir::new().unwrap();
std::fs::create_dir_all(tmp.path().join("src")).unwrap();
std::fs::write(tmp.path().join("src/kept.rs"), b"fn kept_on_disk() {}\n").unwrap();
std::fs::write(tmp.path().join(GONE), b"fn gone_on_disk() {}\n").unwrap();
let (shared, snapshot_mtimes) = restore_for_verify(
&make_live_index_with_files(vec![
("src/kept.rs", b"fn kept() {}\n"),
(GONE, b"fn gone() {}\n"),
]),
tmp.path(),
);
let running_publication = Arc::new(std::sync::atomic::AtomicU64::new(0));
let deleted = Arc::new(std::sync::atomic::AtomicBool::new(false));
background_verify_with_hook(
shared.clone(),
tmp.path().to_path_buf(),
snapshot_mtimes,
verify_observer(tmp.path()),
{
let shared = shared.clone();
let running_publication = running_publication.clone();
move || {
running_publication.store(
shared.published_generation().publication_generation,
std::sync::atomic::Ordering::SeqCst,
);
}
},
{
let shared = shared.clone();
let gone = tmp.path().join(GONE);
let deleted = deleted.clone();
move || {
let reverify = matches!(
&shared.read().snapshot_verify_state,
SnapshotVerifyState::Running(progress)
if progress.describe().starts_with("phase=reverify")
);
if reverify && !deleted.swap(true, std::sync::atomic::Ordering::SeqCst) {
std::fs::remove_file(&gone).unwrap();
}
false
}
},
)
.await;
assert!(deleted.load(std::sync::atomic::Ordering::SeqCst));
let current = shared.published_generation();
assert_eq!(
current.publication_generation
- running_publication.load(std::sync::atomic::Ordering::SeqCst),
1,
"one publication after the running mark, carrying the removal"
);
match ¤t.live.snapshot_verify_state {
SnapshotVerifyState::Completed(report) => assert_eq!(report.mismatch_count, 0),
other => panic!("expected a completed verify, got {other:?}"),
}
assert!(!current.live.files.contains_key(GONE));
assert_eq!(
current.live.files["src/kept.rs"].content,
b"fn kept_on_disk() {}\n"
);
}
#[cfg(feature = "server")]
#[tokio::test]
async fn checkpoint_refuses_an_unverified_restored_seed() {
let tmp = TempDir::new().unwrap();
let (restored, snapshot_mtimes) = restored_with_offline_edits(tmp.path(), 3, 1);
let placement = project_local_placement(tmp.path());
let refused = |state: &str| {
let error = checkpoint_shared_index(&restored, tmp.path(), &placement)
.expect_err("an unverified seed must not be persisted")
.to_string();
assert!(
error.contains(&format!("verify is {state}")) && error.contains("index_folder"),
"{error}"
);
};
refused("pending");
let generation = restored.current_project_generation();
assert!(restored.mark_snapshot_verify_started_at_generation(
generation,
SnapshotVerifyProgress::started(SystemTime::now(), 3),
));
refused("running");
let failed = crate::live_index::SharedIndexHandle::shared(snapshot_to_live_index(
load_snapshot(tmp.path()).expect("snapshot should load"),
tmp.path(),
));
let failed_generation = failed.current_project_generation();
assert!(failed.mark_snapshot_verify_started_at_generation(
failed_generation,
SnapshotVerifyProgress::started(SystemTime::now(), 3),
));
assert!(failed.mark_snapshot_verify_failed_at_generation(
failed_generation,
SnapshotVerifyReport::empty(),
));
let error = checkpoint_shared_index(&failed, tmp.path(), &placement)
.expect_err("a failed verify's seed must not be persisted")
.to_string();
assert!(error.contains("verify is failed"), "{error}");
let resolved = crate::live_index::SharedIndexHandle::shared(snapshot_to_live_index(
load_snapshot(tmp.path()).expect("snapshot should load"),
tmp.path(),
));
background_verify(
resolved.clone(),
tmp.path().to_path_buf(),
snapshot_mtimes,
verify_observer(tmp.path()),
)
.await;
checkpoint_shared_index(&resolved, tmp.path(), &placement)
.expect("a resolved verify's index checkpoints");
}
#[cfg(feature = "server")]
#[test]
fn canonical_seam_hash_skips_a_hidden_restored_row() {
let tmp = TempDir::new().unwrap();
std::fs::create_dir_all(tmp.path().join("src")).unwrap();
std::fs::write(tmp.path().join("src/a.rs"), b"fn a() {}\n").unwrap();
let (shared, _) = restore_for_verify(
&make_live_index_with_files(vec![("src/a.rs", b"fn a() {}\n")]),
tmp.path(),
);
let generation = shared.current_project_generation();
assert!(shared.mark_snapshot_verify_started_at_generation(
generation,
SnapshotVerifyProgress::started(SystemTime::now(), 1),
));
assert!(shared.read().get_file("src/a.rs").is_none());
let outcome = crate::live_index::single_file::maybe_reindex(
"src/a.rs",
&tmp.path().join("src").join("a.rs"),
&shared,
None::<LanguageId>,
generation,
);
assert_eq!(outcome, crate::watcher::ReindexResult::HashSkip);
}
#[test]
fn stat_pass_and_spot_check_stop_at_their_checkpoints() {
let tmp = TempDir::new().unwrap();
let names: Vec<String> = (0..=SNAPSHOT_VERIFY_STOP_EVERY)
.map(|i| format!("f{i}.rs"))
.collect();
let index = make_live_index_with_files(
names
.iter()
.map(|name| (name.as_str(), b"fn f() {}\n".as_slice()))
.collect(),
);
let view = capture_verify_view(&index);
let polls = std::cell::Cell::new(0usize);
let stop_at_second_check = || {
polls.set(polls.get() + 1);
polls.get() >= 2
};
assert!(
stat_check_files_from_view(&view, &HashMap::new(), tmp.path(), &stop_at_second_check)
.is_none()
);
assert_eq!(polls.get(), 2, "the stat pass stops at its in-loop check");
polls.set(0);
assert!(
spot_verify_sample_from_view(&view, tmp.path(), 1.0, None, &stop_at_second_check)
.is_none()
);
assert_eq!(polls.get(), 2, "the spot check stops at its in-loop check");
}
#[test]
fn snapshot_verify_progress_counts_each_phase_separately() {
let progress = SnapshotVerifyProgress::started(SystemTime::now(), 100);
progress.start_spot_check(10);
progress.add_processed(3);
assert!(
progress
.describe()
.starts_with("phase=spot_check processed=3/10 restored_files=100"),
"{}",
progress.describe()
);
progress.start_reverify(5);
assert!(
progress
.describe()
.starts_with("phase=reverify processed=0/5 restored_files=100"),
"{}",
progress.describe()
);
}
#[cfg(feature = "server")]
#[test]
fn fresh_instance_sweep_skips_restored_rows_that_match_disk() {
const FILES: usize = 20;
let tmp = TempDir::new().unwrap();
for i in 0..FILES {
std::fs::write(
tmp.path().join(format!("f{i}.rs")),
format!("pub fn f{i}() {{}}\n"),
)
.unwrap();
}
let loaded = LiveIndex::load(tmp.path()).unwrap();
checkpoint_shared_index(&loaded, tmp.path(), &project_local_placement(tmp.path())).unwrap();
let snapshot = load_snapshot(tmp.path()).expect("snapshot should load");
let restored = crate::live_index::SharedIndexHandle::shared(snapshot_to_live_index(
snapshot,
tmp.path(),
));
assert!(
restored.scout_plan().is_none(),
"precondition: a restored index has no scout plan to diff against"
);
assert!(restored.mark_snapshot_verify_completed_at_generation(
restored.current_project_generation(),
SnapshotVerifyReport::empty(),
));
std::fs::write(tmp.path().join("f3.rs"), "pub fn f3() { let _ = 3; }\n").unwrap();
let observer = verify_observer(tmp.path());
let before = restored.published_generation().publication_generation;
let repaired = crate::watcher::reconcile_stale_files_with_stop(
tmp.path(),
&restored,
|| false,
restored.current_project_generation(),
observer,
);
let publications = restored.published_generation().publication_generation - before;
assert_eq!(repaired, 1, "only the edited file needs re-admission");
assert!(
publications <= 2,
"{FILES} restored rows with one edit cost {publications} publications"
);
assert_eq!(
restored.read().files["f3.rs"].content,
b"pub fn f3() { let _ = 3; }\n"
);
}
#[cfg(feature = "server")]
#[test]
fn sweep_defers_new_files_while_a_verify_runs() {
let tmp = TempDir::new().unwrap();
let (restored, _) = restored_with_offline_edits(tmp.path(), 5, 1);
std::fs::write(tmp.path().join("new.rs"), "pub fn new() {}\n").unwrap();
let generation = restored.current_project_generation();
let progress = SnapshotVerifyProgress::started(SystemTime::now(), 5);
assert!(restored.mark_snapshot_verify_started_at_generation(generation, progress.clone()));
progress.start_reverify(1);
let before = restored.published_generation().publication_generation;
let repaired = crate::watcher::reconcile_stale_files_with_stop(
tmp.path(),
&restored,
|| false,
generation,
verify_observer(tmp.path()),
);
assert_eq!(repaired, 0, "every path belongs to the running verify");
assert_eq!(
restored.published_generation().publication_generation,
before,
"a deferred sweep publishes nothing"
);
assert!(
!restored.read().files.contains_key("new.rs"),
"the sweep must not admit a new file while the verify runs"
);
assert_eq!(restored.read().files["f0.rs"].content, b"pub fn f0() {}\n");
}
#[tokio::test]
async fn background_verify_withholds_a_deleted_path_that_returns_unreadable() {
const BACK: &str = "f2.rs";
struct ClearInjection;
impl Drop for ClearInjection {
fn drop(&mut self) {
*crate::live_index::single_file::test_scout_failure_path().lock() = None;
}
}
let tmp = TempDir::new().unwrap();
let (shared, snapshot_mtimes) = restored_with_offline_edits(tmp.path(), 5, 0);
std::fs::remove_file(tmp.path().join(BACK)).unwrap();
let _clear = ClearInjection;
*crate::live_index::single_file::test_scout_failure_path().lock() = Some(BACK.to_string());
let root = tmp.path().to_path_buf();
let watched = shared.clone();
background_verify_cancellable(
shared.clone(),
root.clone(),
snapshot_mtimes,
verify_observer(tmp.path()),
move || {
let past_stat_pass = matches!(
&watched.read().snapshot_verify_state,
SnapshotVerifyState::Running(progress)
if !progress.describe().starts_with("phase=stat_pass")
);
if past_stat_pass && !root.join(BACK).exists() {
std::fs::write(root.join(BACK), "pub fn f2() { let _ = 2; }\n").unwrap();
}
false
},
)
.await;
let live = shared.read();
assert!(tmp.path().join(BACK).exists(), "the path came back");
assert!(
live.unverified_since_restore(BACK).is_some(),
"the path the verify could not reconcile is recorded: {:?}",
live.snapshot_verify_state
);
assert!(
!live.files.contains_key(BACK),
"its restored seed row must not be served as current"
);
for path in live.withheld_since_restore().keys() {
assert!(
!live.files.contains_key(path),
"{path} is reported withheld but a lane still holds its row"
);
}
}
#[tokio::test]
async fn background_verify_reports_a_discovery_failure_without_a_machine_path() {
struct ClearInjection;
impl Drop for ClearInjection {
fn drop(&mut self) {
*super::test_discovery_failure_root().lock() = None;
}
}
let tmp = TempDir::new().unwrap();
let (shared, snapshot_mtimes) = restored_with_offline_edits(tmp.path(), 3, 0);
let _clear = ClearInjection;
*super::test_discovery_failure_root().lock() = Some(tmp.path().to_path_buf());
background_verify(
shared.clone(),
tmp.path().to_path_buf(),
snapshot_mtimes,
verify_observer(tmp.path()),
)
.await;
let live = shared.read();
let SnapshotVerifyState::Completed(report) = &live.snapshot_verify_state else {
panic!(
"expected a completed verify: {:?}",
live.snapshot_verify_state
);
};
let root = tmp.path().display().to_string();
let error = report
.discovery_error
.as_deref()
.expect("the failure is recorded");
assert!(
error.contains("injected discovery failure under <project root>"),
"{error}"
);
assert!(
report.has_mismatches(),
"the verify could not vouch for new files"
);
assert!(
report
.mismatched_paths
.iter()
.all(|path| !path.contains(&root)),
"{:?}",
report.mismatched_paths
);
#[cfg(feature = "server")]
{
let status = crate::protocol::format::snapshot_verify_status_line(
IndexLoadSource::SnapshotRestore,
&live.snapshot_verify_state,
)
.expect("a restore reports its verify");
assert!(!status.contains(&root), "{status}");
assert!(status.contains("discovery_error="), "{status}");
}
}
#[cfg(feature = "server")]
fn withheld_new_file_without_a_row(root: &Path) -> crate::live_index::store::SharedIndex {
let (shared, snapshot_mtimes) = restored_with_offline_edits(root, 3, 0);
std::fs::write(root.join("n.rs"), "pub fn n() {}\n").unwrap();
*crate::live_index::single_file::test_scout_failure_path().lock() =
Some("n.rs".to_string());
block_on_background_verify_for_test(shared.clone(), root, snapshot_mtimes);
*crate::live_index::single_file::test_scout_failure_path().lock() = None;
{
let live = shared.read();
assert!(live.unverified_since_restore("n.rs").is_some());
assert!(!live.files.contains_key("n.rs"), "it never had a row");
}
shared
}
#[cfg(feature = "server")]
#[test]
fn withheld_path_without_a_row_is_released_when_deleted() {
let tmp = TempDir::new().unwrap();
let shared = withheld_new_file_without_a_row(tmp.path());
std::fs::remove_file(tmp.path().join("n.rs")).unwrap();
crate::live_index::single_file::maybe_reindex(
"n.rs",
&tmp.path().join("n.rs"),
&shared,
None::<LanguageId>,
shared.current_project_generation(),
);
let live = shared.read();
assert!(
live.unverified_since_restore("n.rs").is_none(),
"a deleted withheld path must be released"
);
assert!(crate::protocol::read_gate::refuse_by_policy(&live, "n.rs").is_none());
}
#[cfg(feature = "server")]
#[test]
fn releasing_a_withheld_path_alone_keeps_the_content_generation() {
let tmp = TempDir::new().unwrap();
let shared = withheld_new_file_without_a_row(tmp.path());
std::fs::remove_file(tmp.path().join("n.rs")).unwrap();
let before = shared.published_generation();
assert!(
before
.live
.manifest_entries
.iter()
.all(|entry| entry.path.normalized_utf8.as_deref() != Some("n.rs")),
"the release is the only thing held"
);
assert!(shared.scout_plan().is_none_or(|plan| {
plan.entries
.iter()
.all(|entry| entry.path.normalized_utf8.as_deref() != Some("n.rs"))
}));
let removal = shared.remove_file_if_absent_at_publication_fence_with_receipt(
"n.rs",
&tmp.path().join("n.rs"),
shared.publication_fence(),
);
assert!(matches!(
removal,
crate::live_index::store::FencedRemoval::Removed(_)
));
let after = shared.published_generation();
assert!(after.live.unverified_since_restore("n.rs").is_none());
assert!(after.publication_generation > before.publication_generation);
assert_eq!(after.content_generation, before.content_generation);
assert!(Arc::ptr_eq(&after.bridge, &before.bridge));
}
#[cfg(feature = "server")]
#[test]
fn complete_sweep_releases_a_withheld_path_excluded_by_policy() {
let tmp = TempDir::new().unwrap();
let shared = withheld_new_file_without_a_row(tmp.path());
std::fs::write(tmp.path().join(".ignore"), "n.rs\n").unwrap();
crate::watcher::reconcile_stale_files_with_stop(
tmp.path(),
&shared,
|| false,
shared.current_project_generation(),
verify_observer(tmp.path()),
);
assert!(tmp.path().join("n.rs").exists());
assert!(shared.read().unverified_since_restore("n.rs").is_none());
}
#[cfg(feature = "server")]
#[test]
fn complete_sweep_releases_a_withheld_path_it_no_longer_sees() {
let tmp = TempDir::new().unwrap();
let shared = withheld_new_file_without_a_row(tmp.path());
std::fs::remove_file(tmp.path().join("n.rs")).unwrap();
crate::watcher::reconcile_stale_files_with_stop(
tmp.path(),
&shared,
|| false,
shared.current_project_generation(),
verify_observer(tmp.path()),
);
assert!(shared.read().unverified_since_restore("n.rs").is_none());
}
#[cfg(feature = "server")]
#[tokio::test(flavor = "multi_thread")]
async fn watcher_sweeps_once_when_the_deferred_verify_completes() {
let tmp = TempDir::new().unwrap();
let (restored, _) = restored_with_offline_edits(tmp.path(), 3, 0);
std::fs::write(tmp.path().join("offline.rs"), "pub fn offline() {}\n").unwrap();
let generation = restored.current_project_generation();
assert!(restored.mark_snapshot_verify_started_at_generation(
generation,
SnapshotVerifyProgress::started(SystemTime::now(), 3),
));
let info = Arc::new(parking_lot::Mutex::new(
crate::watcher::WatcherInfo::default(),
));
let stop = Arc::new(std::sync::atomic::AtomicBool::new(false));
let watcher = tokio::spawn(crate::watcher::run_watcher_with_stop(
tmp.path().to_path_buf(),
restored.clone(),
Arc::clone(&info),
Arc::clone(&stop),
));
let wait_for = |what: &str, done: &dyn Fn() -> bool| {
let deadline = Instant::now() + Duration::from_secs(10);
while !done() {
assert!(Instant::now() < deadline, "timed out waiting for {what}");
std::thread::sleep(Duration::from_millis(25));
}
};
wait_for("the watcher to go active", &|| {
info.lock().state == crate::watcher::WatcherState::Active
});
assert!(
info.lock().last_reconcile_at.is_none(),
"a sweep that deferred observed nothing and must not claim a reconcile"
);
assert!(!restored.read().files.contains_key("offline.rs"));
assert!(restored.mark_snapshot_verify_completed_at_generation(
generation,
SnapshotVerifyReport::empty(),
));
wait_for("the post-verify sweep", &|| {
restored.read().files.contains_key("offline.rs")
});
wait_for("the reconcile stamp", &|| {
info.lock().last_reconcile_at.is_some()
});
stop.store(true, std::sync::atomic::Ordering::Release);
tokio::time::timeout(Duration::from_secs(5), watcher)
.await
.expect("the watcher stops")
.expect("the watcher does not panic");
}
#[cfg(feature = "server")]
#[tokio::test(flavor = "multi_thread")]
async fn watcher_sweeps_after_a_verify_that_completes_during_the_fresh_sweep() {
let tmp = TempDir::new().unwrap();
let (restored, _) = restored_with_offline_edits(tmp.path(), 3, 0);
std::fs::write(tmp.path().join("offline.rs"), "pub fn offline() {}\n").unwrap();
let generation = restored.current_project_generation();
assert!(restored.mark_snapshot_verify_started_at_generation(
generation,
SnapshotVerifyProgress::started(SystemTime::now(), 3),
));
let completer = restored.clone();
*crate::watcher::AFTER_FRESH_INSTANCE_SWEEP.lock() = Some(Box::new(move || {
assert!(completer.mark_snapshot_verify_completed_at_generation(
generation,
SnapshotVerifyReport::empty(),
));
}));
let info = Arc::new(parking_lot::Mutex::new(
crate::watcher::WatcherInfo::default(),
));
let stop = Arc::new(std::sync::atomic::AtomicBool::new(false));
let watcher = tokio::spawn(crate::watcher::run_watcher_with_stop(
tmp.path().to_path_buf(),
restored.clone(),
Arc::clone(&info),
Arc::clone(&stop),
));
let deadline = Instant::now() + Duration::from_secs(10);
while !restored.read().files.contains_key("offline.rs") {
assert!(
Instant::now() < deadline,
"timed out waiting for the post-verify sweep"
);
std::thread::sleep(Duration::from_millis(25));
}
stop.store(true, std::sync::atomic::Ordering::Release);
tokio::time::timeout(Duration::from_secs(5), watcher)
.await
.expect("the watcher stops")
.expect("the watcher does not panic");
}
#[cfg(feature = "server")]
#[tokio::test]
async fn background_verify_does_not_follow_a_symlink_swapped_in_offline() {
let tmp = TempDir::new().unwrap();
let outside = TempDir::new().unwrap();
std::fs::write(outside.path().join("secret.rs"), "pub fn leaked() {}\n").unwrap();
let (shared, snapshot_mtimes) = restored_with_offline_edits(tmp.path(), 3, 0);
std::fs::remove_file(tmp.path().join("f1.rs")).unwrap();
#[cfg(unix)]
let linked =
std::os::unix::fs::symlink(outside.path().join("secret.rs"), tmp.path().join("f1.rs"));
#[cfg(windows)]
let linked = std::os::windows::fs::symlink_file(
outside.path().join("secret.rs"),
tmp.path().join("f1.rs"),
);
if let Err(error) = linked {
eprintln!("cannot create a file symlink here ({error}); skipped");
return;
}
background_verify(
shared.clone(),
tmp.path().to_path_buf(),
snapshot_mtimes,
verify_observer(tmp.path()),
)
.await;
let live = shared.read();
assert!(
live.files
.get("f1.rs")
.is_none_or(|file| !String::from_utf8_lossy(&file.content).contains("leaked")),
"the verify published a symlink target's bytes under the in-repo name"
);
}
#[cfg(feature = "server")]
#[test]
fn an_alias_spelling_never_releases_a_withheld_path() {
const BROKEN: &str = "f1.rs";
let tmp = TempDir::new().unwrap();
let (shared, snapshot_mtimes) = restored_with_offline_edits(tmp.path(), 3, 2);
*crate::live_index::single_file::test_scout_failure_path().lock() =
Some(BROKEN.to_string());
block_on_background_verify_for_test(shared.clone(), tmp.path(), snapshot_mtimes);
*crate::live_index::single_file::test_scout_failure_path().lock() = None;
assert!(shared.read().unverified_since_restore(BROKEN).is_some());
let probe = tmp.path().join("case_probe.tmp");
std::fs::write(&probe, b"").unwrap();
let case_insensitive = tmp.path().join("CASE_PROBE.TMP").exists();
std::fs::remove_file(&probe).unwrap();
let mut aliases = vec!["./f1.rs", "f1.rs."];
if case_insensitive {
aliases.push("F1.RS");
}
for alias in aliases {
let before = shared.published_generation().publication_generation;
crate::live_index::single_file::maybe_reindex(
alias,
&tmp.path().join(alias),
&shared,
None::<LanguageId>,
shared.current_project_generation(),
);
let live = shared.read();
assert!(
live.unverified_since_restore(BROKEN).is_some(),
"{alias} released the withheld path"
);
assert!(!live.files.contains_key(alias), "{alias} was published");
assert_eq!(
shared.published_generation().publication_generation,
before,
"{alias} published something"
);
}
crate::live_index::single_file::maybe_reindex(
BROKEN,
&tmp.path().join(BROKEN),
&shared,
None::<LanguageId>,
shared.current_project_generation(),
);
assert!(shared.read().unverified_since_restore(BROKEN).is_none());
}
#[cfg(feature = "server")]
#[test]
fn sweep_retries_a_withheld_path_until_it_reads() {
const BROKEN: &str = "f1.rs";
struct ClearInjection;
impl Drop for ClearInjection {
fn drop(&mut self) {
*crate::live_index::single_file::test_scout_failure_path().lock() = None;
}
}
let tmp = TempDir::new().unwrap();
let (shared, snapshot_mtimes) = restored_with_offline_edits(tmp.path(), 3, 2);
let _clear = ClearInjection;
*crate::live_index::single_file::test_scout_failure_path().lock() =
Some(BROKEN.to_string());
block_on_background_verify_for_test(shared.clone(), tmp.path(), snapshot_mtimes);
assert!(shared.read().unverified_since_restore(BROKEN).is_some());
let sweep = || {
crate::watcher::reconcile_stale_files_with_stop(
tmp.path(),
&shared,
|| false,
shared.current_project_generation(),
verify_observer(tmp.path()),
)
};
sweep();
assert!(shared.read().unverified_since_restore(BROKEN).is_some());
assert!(
shared.scout_plan().is_some(),
"the sweep published its plan"
);
*crate::live_index::single_file::test_scout_failure_path().lock() = None;
sweep();
let live = shared.read();
assert!(live.unverified_since_restore(BROKEN).is_none());
assert_eq!(live.files[BROKEN].content, b"pub fn f1() { let _ = 1; }\n");
}
#[cfg(feature = "server")]
#[tokio::test]
async fn background_verify_publishes_changed_files_in_batches() {
const CHANGED: usize = 600;
let tmp = TempDir::new().unwrap();
std::fs::create_dir_all(tmp.path().join("src")).unwrap();
let paths: Vec<String> = (0..CHANGED).map(|i| format!("src/f{i}.rs")).collect();
let original: Vec<Vec<u8>> = (0..CHANGED)
.map(|i| format!("pub fn f{i}() {{}}\n").into_bytes())
.collect();
for (path, content) in paths.iter().zip(&original) {
std::fs::write(tmp.path().join(path), content).unwrap();
}
let index = make_live_index_with_files(
paths
.iter()
.zip(&original)
.map(|(path, content)| (path.as_str(), content.as_slice()))
.collect(),
);
serialize_index(&index, tmp.path()).expect("serialize should succeed");
let snapshot = load_snapshot(tmp.path()).expect("snapshot should load");
let snapshot_mtimes = snapshot
.files
.iter()
.map(|(path, file)| (path.clone(), file.mtime_secs))
.collect::<HashMap<_, _>>();
for (i, path) in paths.iter().enumerate() {
std::fs::write(
tmp.path().join(path),
format!("pub fn f{i}() {{ let _ = {i}; }}\n"),
)
.unwrap();
}
let shared = crate::live_index::SharedIndexHandle::shared(snapshot_to_live_index(
snapshot,
tmp.path(),
));
let before = shared.published_generation().publication_generation;
background_verify(
shared.clone(),
tmp.path().to_path_buf(),
snapshot_mtimes,
verify_observer(tmp.path()),
)
.await;
let after = shared.published_generation();
assert_eq!(
after.live.snapshot_verify_state,
SnapshotVerifyState::completed_without_mismatches()
);
for (i, path) in paths.iter().enumerate() {
let expected = format!("pub fn f{i}() {{ let _ = {i}; }}\n");
assert_eq!(
after
.live
.files
.get(path)
.map(|file| file.content.as_slice()),
Some(expected.as_bytes()),
"{path} must carry its on-disk bytes after verify"
);
}
let publications = after.publication_generation - before;
let bound = 2;
assert!(
publications <= bound,
"{CHANGED} changed files cost {publications} publications; bound is {bound}"
);
}
#[tokio::test]
async fn test_background_verify_deleted_file_changes_published_counts() {
let tmp = TempDir::new().unwrap();
let file_path = tmp.path().join("src").join("main.rs");
std::fs::create_dir_all(file_path.parent().unwrap()).unwrap();
std::fs::write(&file_path, b"fn main() {}\n").unwrap();
let index = make_live_index_with_files(vec![("src/main.rs", b"fn main() {}\n")]);
serialize_index(&index, tmp.path()).expect("serialize should succeed");
let snapshot = load_snapshot(tmp.path()).expect("snapshot should load");
let snapshot_mtimes = snapshot
.files
.iter()
.map(|(path, file)| (path.clone(), file.mtime_secs))
.collect::<HashMap<_, _>>();
let loaded = snapshot_to_live_index(snapshot, tmp.path());
let shared = crate::live_index::SharedIndexHandle::shared(loaded);
let before = shared.published_state();
assert_eq!(before.file_count, 1);
assert_eq!(before.partial_parse_count, 0);
assert_eq!(before.failed_count, 0);
std::fs::remove_file(&file_path).expect("remove indexed file");
background_verify(
shared.clone(),
tmp.path().to_path_buf(),
snapshot_mtimes,
verify_observer(tmp.path()),
)
.await;
let published = shared.published_state();
assert!(
published.generation >= 2,
"expected published generation to advance through verify transitions"
);
assert_eq!(
published.snapshot_verify_state,
SnapshotVerifyState::completed_without_mismatches()
);
assert_eq!(published.file_count, 0);
assert_eq!(published.parsed_count, 0);
assert_eq!(published.partial_parse_count, 0);
assert_eq!(published.failed_count, 0);
}
#[test]
fn background_verify_deleted_file_removal_refuses_disk_recreation() {
let tmp = TempDir::new().unwrap();
let relative_path = "src/main.rs";
let file_path = tmp.path().join(relative_path);
let shared = crate::live_index::SharedIndexHandle::shared(make_live_index_with_files(
vec![(relative_path, b"fn before() {}\n")],
));
assert!(
!file_path.exists(),
"the verifier's stat observation starts from disk absence"
);
let before = shared.publication_fence();
std::fs::create_dir_all(file_path.parent().unwrap()).unwrap();
std::fs::write(&file_path, b"fn recreated() {}\n").unwrap();
let receipt = shared
.publish_snapshot_verify_at_generation(
before.project_generation,
&[(relative_path.to_string(), file_path.clone())],
Vec::new(),
None,
)
.expect("same project");
assert_eq!(
receipt.refused,
vec![relative_path.to_string()],
"a disk recreation after stat must reject snapshot cleanup"
);
assert!(receipt.removed.is_empty());
assert_eq!(
shared.publication_fence(),
before,
"a refusal must not publish"
);
assert!(
shared.read().get_file(relative_path).is_some(),
"the last-valid indexed entry must survive the rejected removal"
);
}
#[test]
fn background_verify_deleted_file_removal_distinguishes_removed_from_nothing_held() {
let tmp = TempDir::new().unwrap();
let held_path = "src/main.rs";
let shared = crate::live_index::SharedIndexHandle::shared(make_live_index_with_files(
vec![(held_path, b"fn before() {}\n")],
));
let fence = shared.publication_fence();
let receipt = shared
.publish_snapshot_verify_at_generation(
fence.project_generation,
&[(held_path.to_string(), tmp.path().join(held_path))],
Vec::new(),
None,
)
.expect("same project");
assert_eq!(
receipt.removed,
vec![held_path.to_string()],
"a held path confirmed absent must be REMOVED and observed"
);
let after_removal = shared.publication_fence();
assert!(
after_removal != fence,
"an actual removal must publish (the fence must move)"
);
let receipt = shared
.publish_snapshot_verify_at_generation(
fence.project_generation,
&[(
"src/never_held.rs".to_string(),
tmp.path().join("src/never_held.rs"),
)],
Vec::new(),
None,
)
.expect("same project");
assert!(
receipt.removed.is_empty() && receipt.refused.is_empty(),
"a never-held path has nothing to remove — NothingHeld, not Removed"
);
assert_eq!(
shared.publication_fence(),
after_removal,
"a NothingHeld outcome must not publish"
);
}
#[test]
fn snapshot_verify_batch_refuses_a_row_another_writer_moved() {
let tmp = TempDir::new().unwrap();
let relative_path = "src/main.rs";
let file_path = tmp.path().join(relative_path);
std::fs::create_dir_all(file_path.parent().unwrap()).unwrap();
std::fs::write(&file_path, b"fn on_disk() {}\n").unwrap();
let shared = crate::live_index::SharedIndexHandle::shared(make_live_index_with_files(
vec![(relative_path, b"fn before() {}\n")],
));
let generation = shared.current_project_generation();
let base_hash = shared.read().files[relative_path].content_hash.clone();
let scouted = crate::discovery::scout_single_path(relative_path, &file_path).unwrap();
let watcher_row = make_indexed_file(relative_path, b"fn watcher_won() {}\n");
assert!(shared.update_file_at_generation(relative_path, watcher_row, generation));
let before = shared.publication_fence();
let receipt = shared
.publish_snapshot_verify_at_generation(
generation,
&[],
vec![crate::live_index::store::SnapshotVerifiedFile {
path: relative_path.to_string(),
scouted,
admission: crate::live_index::store::SnapshotVerifiedAdmission::Indexed {
file: Box::new(make_indexed_file(relative_path, b"fn on_disk() {}\n")),
targets: crate::domain::IndexTargets::Code,
},
base_hash: Some(base_hash),
}],
None,
)
.expect("same project");
assert_eq!(receipt.superseded, vec![relative_path.to_string()]);
assert!(receipt.indexed.is_empty() && receipt.refused.is_empty());
assert_eq!(shared.publication_fence(), before);
assert_eq!(
shared.read().files[relative_path].content,
b"fn watcher_won() {}\n"
);
}
#[tokio::test]
async fn test_background_verify_records_spot_verify_mismatch_paths() {
let tmp = TempDir::new().unwrap();
let file_path = tmp.path().join("src").join("main.rs");
std::fs::create_dir_all(file_path.parent().unwrap()).unwrap();
std::fs::write(&file_path, b"fn alt1() {}\n").unwrap();
let disk_mtime = std::fs::metadata(&file_path)
.and_then(|meta| meta.modified())
.ok()
.and_then(|time| time.duration_since(std::time::UNIX_EPOCH).ok())
.map(|duration| duration.as_secs())
.unwrap_or(0);
let mut index = make_live_index_with_files(vec![("src/main.rs", b"fn main() {}\n")]);
index.files.insert(
"src/main.rs".to_string(),
Arc::new(make_indexed_file("src/main.rs", b"fn main() {}\n").with_mtime(disk_mtime)),
);
serialize_index(&index, tmp.path()).expect("serialize should succeed");
let snapshot = load_snapshot(tmp.path()).expect("snapshot should load");
let snapshot_mtimes = snapshot
.files
.iter()
.map(|(path, file)| (path.clone(), file.mtime_secs))
.collect::<HashMap<_, _>>();
let loaded = snapshot_to_live_index(snapshot, tmp.path());
let shared = crate::live_index::SharedIndexHandle::shared(loaded);
background_verify(
shared.clone(),
tmp.path().to_path_buf(),
snapshot_mtimes,
verify_observer(tmp.path()),
)
.await;
let published = shared.published_state();
match &published.snapshot_verify_state {
SnapshotVerifyState::Completed(report) => {
assert_eq!(report.mismatch_count, 1);
assert_eq!(report.mismatched_paths, vec!["src/main.rs".to_string()]);
assert_eq!(report.omitted_path_count(), 0);
assert_eq!(
report.reason.as_deref(),
Some("1 restored files had changed content behind an unchanged size and mtime"),
"a verify that leaves mismatches must say why"
);
}
other => panic!("expected completed snapshot verify report, got {other:?}"),
}
assert_ne!(
published.status,
crate::live_index::store::PublishedIndexStatus::Loading,
"an unreconciled verify must not hold the index in Loading"
);
assert!(
matches!(
shared.freshness_status().as_ref(),
crate::domain::FreshnessStatus::Degraded { reason_codes, .. }
if reason_codes.contains(&crate::domain::FreshnessReason::SnapshotVerificationFailed)
),
"an unreconciled verify must degrade freshness, observed {:?}",
shared.freshness_status()
);
}
#[cfg(any(feature = "server", feature = "embed"))]
#[tokio::test]
async fn test_background_verify_rereads_stat_changed_through_the_canonical_seam() {
let tmp = TempDir::new().unwrap();
let file_path = tmp.path().join("src").join("main.rs");
std::fs::create_dir_all(file_path.parent().unwrap()).unwrap();
std::fs::write(&file_path, b"fn main() {}\n").unwrap();
let disk_mtime = std::fs::metadata(&file_path)
.and_then(|meta| meta.modified())
.ok()
.and_then(|time| time.duration_since(std::time::UNIX_EPOCH).ok())
.map(|duration| duration.as_secs())
.unwrap_or(0);
let mut index = make_live_index_with_files(vec![("src/main.rs", b"fn main() {}\n")]);
index.files.insert(
"src/main.rs".to_string(),
Arc::new(make_indexed_file("src/main.rs", b"fn main() {}\n")),
);
serialize_index(&index, tmp.path()).expect("serialize should succeed");
let snapshot = load_snapshot(tmp.path()).expect("snapshot should load");
let mut snapshot_mtimes = snapshot
.files
.iter()
.map(|(path, file)| (path.clone(), file.mtime_secs))
.collect::<HashMap<_, _>>();
snapshot_mtimes.insert("src/main.rs".to_string(), disk_mtime.saturating_sub(1_000));
let loaded = snapshot_to_live_index(snapshot, tmp.path());
let shared = crate::live_index::SharedIndexHandle::shared(loaded);
background_verify(
shared.clone(),
tmp.path().to_path_buf(),
snapshot_mtimes,
verify_observer(tmp.path()),
)
.await;
let published = shared.published_state();
match &published.snapshot_verify_state {
SnapshotVerifyState::Completed(report) => {
assert!(
report.mismatched_paths.is_empty() && report.unverified.is_empty(),
"a stat-changed file the re-read reconciles is not a mismatch: {report:?}"
);
}
other => panic!("expected completed snapshot verify report, got {other:?}"),
}
assert_eq!(
shared
.read()
.files
.get("src/main.rs")
.map(|file| file.content.as_slice()),
Some(b"fn main() {}\n".as_slice()),
"the re-read keeps the reconciled row"
);
assert!(
!matches!(
&*shared.freshness_status(),
crate::domain::FreshnessStatus::Degraded { reason_codes, .. }
if reason_codes
.contains(&crate::domain::FreshnessReason::SnapshotVerificationFailed)
),
"a reconciled verify must not degrade freshness, got {:?}",
shared.freshness_status()
);
}
#[test]
fn test_build_snapshot_resolves_mtime_against_project_root() {
let tmp = TempDir::new().unwrap();
let project_root = tmp.path().join("project");
let file_path = project_root.join("src").join("main.rs");
std::fs::create_dir_all(file_path.parent().unwrap()).unwrap();
std::fs::write(&file_path, b"fn main() {}\n").unwrap();
let index = make_live_index_with_files(vec![("src/main.rs", b"fn main() {}\n")]);
let snapshot = build_snapshot(capture_snapshot_build_input(&index), &project_root);
let expected_mtime = std::fs::metadata(&file_path)
.unwrap()
.modified()
.unwrap()
.duration_since(UNIX_EPOCH)
.unwrap()
.as_secs();
assert_eq!(
snapshot.files.get("src/main.rs").unwrap().mtime_secs,
expected_mtime
);
}
#[test]
fn test_capture_verify_view_sorts_paths() {
let index = make_live_index_with_files(vec![
("src/z.rs", b"fn z() {}\n"),
("src/a.rs", b"fn a() {}\n"),
("src/m.rs", b"fn m() {}\n"),
]);
let view = capture_verify_view(&index);
let paths: Vec<&str> = view
.files
.iter()
.map(|file| file.relative_path.as_str())
.collect();
assert_eq!(paths, vec!["src/a.rs", "src/m.rs", "src/z.rs"]);
}
#[test]
fn test_round_trip_multiple_files() {
let tmp = TempDir::new().unwrap();
let index = make_live_index_with_files(vec![
("a.rs", b"fn alpha() {}"),
("b.rs", b"fn beta() {}"),
("c.py", b"def gamma(): pass"),
]);
serialize_index(&index, tmp.path()).expect("serialize should succeed");
let snapshot = load_snapshot(tmp.path()).expect("snapshot should load");
let loaded = snapshot_to_live_index(snapshot, tmp.path());
assert_eq!(loaded.files.len(), 3);
assert!(loaded.files.contains_key("a.rs"));
assert!(loaded.files.contains_key("b.rs"));
assert!(loaded.files.contains_key("c.py"));
}
#[test]
fn test_round_trip_preserves_parse_status_variants() {
let tmp = TempDir::new().unwrap();
let mut file_map: HashMap<String, Arc<IndexedFile>> = HashMap::new();
let partial_diagnostic = crate::domain::ParseDiagnostic {
parser: "toml_edit".to_string(),
message: "missing closing quote".to_string(),
line: Some(4),
column: Some(17),
byte_span: Some((43, 56)),
fallback_used: true,
};
let failed_diagnostic = crate::domain::ParseDiagnostic {
parser: "toml_edit".to_string(),
message: "invalid table header".to_string(),
line: Some(1),
column: Some(2),
byte_span: Some((0, 8)),
fallback_used: false,
};
file_map.insert(
"ok.rs".to_string(),
Arc::new(IndexedFile {
relative_path: "ok.rs".to_string(),
language: LanguageId::Rust,
classification: crate::domain::FileClassification::for_code_path("ok.rs"),
content: b"fn foo() {}".to_vec(),
symbols: vec![],
parse_status: ParseStatus::Parsed,
parse_diagnostic: None,
byte_len: 11,
content_hash: "hash1".to_string(),
references: vec![],
alias_map: HashMap::new(),
mtime_secs: 0,
}),
);
file_map.insert(
"partial.toml".to_string(),
Arc::new(IndexedFile {
relative_path: "partial.toml".to_string(),
language: LanguageId::Toml,
classification: crate::domain::FileClassification::for_code_path("partial.toml"),
content: b"[package]\nname = \"symforge\"\ninvalid = \"unterminated\n".to_vec(),
symbols: vec![],
parse_status: ParseStatus::PartialParse {
warning: partial_diagnostic.summary(),
},
parse_diagnostic: Some(partial_diagnostic.clone()),
byte_len: 52,
content_hash: "hash2".to_string(),
references: vec![],
alias_map: HashMap::new(),
mtime_secs: 0,
}),
);
file_map.insert(
"fail.toml".to_string(),
Arc::new(IndexedFile {
relative_path: "fail.toml".to_string(),
language: LanguageId::Toml,
classification: crate::domain::FileClassification::for_code_path("fail.toml"),
content: b"[invalid\nno closing".to_vec(),
symbols: vec![],
parse_status: ParseStatus::Failed {
error: failed_diagnostic.summary(),
},
parse_diagnostic: Some(failed_diagnostic.clone()),
byte_len: 19,
content_hash: "hash3".to_string(),
references: vec![],
alias_map: HashMap::new(),
mtime_secs: 0,
}),
);
let trigram_index = crate::live_index::trigram::TrigramIndex::build_from_files(&file_map);
let mut index = LiveIndex {
files: file_map,
loaded_at: Instant::now(),
loaded_at_system: SystemTime::now(),
load_duration: Duration::ZERO,
cb_state: CircuitBreakerState::new(0.20),
is_empty: false,
load_source: IndexLoadSource::FreshLoad,
snapshot_verify_state: SnapshotVerifyState::NotNeeded,
reverse_index: HashMap::new(),
files_by_basename: HashMap::new(),
files_by_dir_component: HashMap::new(),
trigram_index,
gitignore: None,
manifest_entries: Vec::new(),
coupling_store: None,
local_empty_reason: Arc::new(parking_lot::RwLock::new(None)),
indexed_root: None,
};
index.rebuild_reverse_index();
index.rebuild_path_indices();
serialize_index(&index, tmp.path()).expect("serialize should succeed");
let snapshot = load_snapshot(tmp.path()).expect("load should succeed");
let loaded = snapshot_to_live_index(snapshot, tmp.path());
assert_eq!(
loaded.files.get("ok.rs").unwrap().parse_status,
ParseStatus::Parsed
);
let partial = loaded.files.get("partial.toml").unwrap();
assert!(matches!(
partial.parse_status,
ParseStatus::PartialParse { .. }
));
assert_eq!(partial.parse_diagnostic, Some(partial_diagnostic));
let failed = loaded.files.get("fail.toml").unwrap();
assert!(matches!(failed.parse_status, ParseStatus::Failed { .. }));
assert_eq!(failed.parse_diagnostic, Some(failed_diagnostic));
}
#[test]
fn test_persist_format_version_is_pinned() {
assert_eq!(
CURRENT_VERSION, 11,
"persist format version changed — a format bump breaks every existing \
user's .symforge/index.bin and requires orchestrator approval"
);
}
#[test]
fn test_round_trip_preserves_query_equivalence_multilang_xref_partial() {
use crate::domain::{ReferenceKind, SymbolKind};
let tmp = TempDir::new().unwrap();
let rust_content = b"fn my_func() { other_func(); }";
let rust_symbol = SymbolRecord {
name: "my_func".to_string(),
kind: SymbolKind::Function,
depth: 0,
sort_order: 0,
byte_range: (0, 11),
item_byte_range: Some((0, 30)),
line_range: (0, 0),
doc_byte_range: None,
};
let rust_xref = ReferenceRecord {
name: "other_func".to_string(),
qualified_name: None,
kind: ReferenceKind::Call,
byte_range: (15, 25),
line_range: (0, 0),
enclosing_symbol_index: Some(0),
};
let python_content = b"def other_func():\n pass\n";
let python_symbol = SymbolRecord {
name: "other_func".to_string(),
kind: SymbolKind::Function,
depth: 0,
sort_order: 0,
byte_range: (0, 17),
item_byte_range: Some((0, 27)),
line_range: (0, 1),
doc_byte_range: None,
};
let python_diagnostic = crate::domain::ParseDiagnostic {
parser: "tree_sitter_python".to_string(),
message: "unterminated decorator".to_string(),
line: Some(1),
column: Some(0),
byte_span: Some((0, 3)),
fallback_used: true,
};
let ts_content = b"export function render(): void {}";
let ts_symbol = SymbolRecord {
name: "render".to_string(),
kind: SymbolKind::Function,
depth: 0,
sort_order: 0,
byte_range: (7, 29),
item_byte_range: Some((0, 33)),
line_range: (0, 0),
doc_byte_range: None,
};
let mut alias_map = HashMap::new();
alias_map.insert("Map".to_string(), "HashMap".to_string());
let rust_file = IndexedFile {
relative_path: "src/foo.rs".to_string(),
language: LanguageId::Rust,
classification: crate::domain::FileClassification::for_code_path("src/foo.rs"),
content: rust_content.to_vec(),
symbols: vec![rust_symbol],
parse_status: ParseStatus::Parsed,
parse_diagnostic: None,
byte_len: rust_content.len() as u64,
content_hash: crate::hash::digest_hex(rust_content),
references: vec![rust_xref],
alias_map,
mtime_secs: 0,
};
let python_file = IndexedFile {
relative_path: "src/bar.py".to_string(),
language: LanguageId::Python,
classification: crate::domain::FileClassification::for_code_path("src/bar.py"),
content: python_content.to_vec(),
symbols: vec![python_symbol],
parse_status: ParseStatus::PartialParse {
warning: python_diagnostic.summary(),
},
parse_diagnostic: Some(python_diagnostic),
byte_len: python_content.len() as u64,
content_hash: crate::hash::digest_hex(python_content),
references: vec![],
alias_map: HashMap::new(),
mtime_secs: 0,
};
let ts_file = IndexedFile {
relative_path: "src/baz.ts".to_string(),
language: LanguageId::TypeScript,
classification: crate::domain::FileClassification::for_code_path("src/baz.ts"),
content: ts_content.to_vec(),
symbols: vec![ts_symbol],
parse_status: ParseStatus::Parsed,
parse_diagnostic: None,
byte_len: ts_content.len() as u64,
content_hash: crate::hash::digest_hex(ts_content),
references: vec![],
alias_map: HashMap::new(),
mtime_secs: 0,
};
let mut file_map: HashMap<String, Arc<IndexedFile>> = HashMap::new();
file_map.insert("src/foo.rs".to_string(), Arc::new(rust_file));
file_map.insert("src/bar.py".to_string(), Arc::new(python_file));
file_map.insert("src/baz.ts".to_string(), Arc::new(ts_file));
let trigram_index = crate::live_index::trigram::TrigramIndex::build_from_files(&file_map);
let mut before = LiveIndex {
files: file_map,
loaded_at: Instant::now(),
loaded_at_system: SystemTime::now(),
load_duration: Duration::ZERO,
cb_state: CircuitBreakerState::new(0.20),
is_empty: false,
load_source: IndexLoadSource::FreshLoad,
snapshot_verify_state: SnapshotVerifyState::NotNeeded,
reverse_index: HashMap::new(),
files_by_basename: HashMap::new(),
files_by_dir_component: HashMap::new(),
trigram_index,
gitignore: None,
manifest_entries: Vec::new(),
coupling_store: None,
local_empty_reason: Arc::new(parking_lot::RwLock::new(None)),
indexed_root: None,
};
before.rebuild_reverse_index();
before.rebuild_path_indices();
serialize_index(&before, tmp.path()).expect("serialize should succeed");
let raw = std::fs::read(tmp.path().join(".symforge").join("index.bin")).unwrap();
let decoded: IndexSnapshot = decode_snapshot(&raw).expect("persisted snapshot decodes");
assert_eq!(
decoded.version, CURRENT_VERSION,
"serialized snapshot must carry CURRENT_VERSION"
);
let snapshot = load_snapshot(tmp.path()).expect("snapshot should load");
let mut after = snapshot_to_live_index(snapshot, tmp.path());
after.mark_snapshot_verify_completed(Vec::new());
assert_eq!(before.file_count(), after.file_count(), "file_count");
assert_eq!(before.symbol_count(), after.symbol_count(), "symbol_count");
let mut before_all: Vec<(String, IndexedFile)> = before
.all_files()
.map(|(p, f)| (p.clone(), f.clone()))
.collect();
let mut after_all: Vec<(String, IndexedFile)> = after
.all_files()
.map(|(p, f)| (p.clone(), f.clone()))
.collect();
before_all.sort_by(|a, b| a.0.cmp(&b.0));
after_all.sort_by(|a, b| a.0.cmp(&b.0));
assert_eq!(before_all.len(), after_all.len(), "all_files len");
for ((bp, bf), (ap, af)) in before_all.iter().zip(after_all.iter()) {
assert_eq!(bp, ap, "all_files path");
assert_eq!(bf.content, af.content, "content for {bp}");
assert_eq!(bf.content_hash, af.content_hash, "hash for {bp}");
assert_eq!(bf.language, af.language, "language for {bp}");
assert_eq!(bf.symbols, af.symbols, "symbols for {bp}");
assert_eq!(bf.references, af.references, "references for {bp}");
assert_eq!(bf.parse_status, af.parse_status, "parse_status for {bp}");
assert_eq!(
bf.parse_diagnostic, af.parse_diagnostic,
"parse_diagnostic for {bp}"
);
assert_eq!(bf.alias_map, af.alias_map, "alias_map for {bp}");
assert_eq!(
bf.classification, af.classification,
"classification for {bp}"
);
}
for path in ["src/foo.rs", "src/bar.py", "src/baz.ts"] {
let b = before.get_file(path).expect("before file present");
let a = after.get_file(path).expect("after file present");
assert_eq!(b.content, a.content, "get_file content {path}");
assert_eq!(
before.symbols_for_file(path),
after.symbols_for_file(path),
"symbols_for_file {path}"
);
}
for basename in ["foo.rs", "bar.py", "baz.ts"] {
assert_eq!(
before.find_files_by_basename(basename),
after.find_files_by_basename(basename),
"find_files_by_basename {basename}"
);
}
assert_eq!(
before.find_files_by_dir_component("src"),
after.find_files_by_dir_component("src"),
"find_files_by_dir_component src"
);
let before_refs: Vec<(String, ReferenceRecord)> = before
.find_references_for_name("other_func", None, true)
.into_iter()
.map(|(p, r)| (p.to_string(), r.clone()))
.collect();
let after_refs: Vec<(String, ReferenceRecord)> = after
.find_references_for_name("other_func", None, true)
.into_iter()
.map(|(p, r)| (p.to_string(), r.clone()))
.collect();
assert_eq!(before_refs.len(), 1, "one xref before round-trip");
assert_eq!(before_refs, after_refs, "find_references_for_name xref");
let bh = before.health_stats();
let ah = after.health_stats();
assert_eq!(bh.file_count, ah.file_count, "health file_count");
assert_eq!(bh.symbol_count, ah.symbol_count, "health symbol_count");
assert_eq!(bh.parsed_count, ah.parsed_count, "health parsed_count");
assert_eq!(
bh.partial_parse_count, ah.partial_parse_count,
"health partial_parse_count"
);
assert_eq!(bh.failed_count, ah.failed_count, "health failed_count");
assert_eq!(
bh.partial_parse_files, ah.partial_parse_files,
"health partial_parse_files"
);
assert_eq!(bh.failed_files, ah.failed_files, "health failed_files");
assert_eq!(
bh.partial_parse_count, 1,
"test setup must include one partial-parse file"
);
let bo = before.capture_repo_outline_view();
let ao = after.capture_repo_outline_view();
assert_eq!(bo.total_files, ao.total_files, "outline total_files");
assert_eq!(bo.total_symbols, ao.total_symbols, "outline total_symbols");
assert_eq!(bo.files, ao.files, "outline files");
}
fn quarantine_files_with_extension(root: &Path, extension: &str) -> Vec<PathBuf> {
let dir = paths::resolve_index_snapshot_quarantine_dir(root);
let mut files = match std::fs::read_dir(&dir) {
Ok(entries) => entries
.map(|entry| entry.unwrap().path())
.filter(|path| path.extension().and_then(|ext| ext.to_str()) == Some(extension))
.collect::<Vec<_>>(),
Err(_) => Vec::new(),
};
files.sort();
files
}
#[test]
fn warm_restore_uses_persisted_trigrams_instead_of_rebuilding() {
let tmp = TempDir::new().unwrap();
let content = b"fn unique_token_xyzzy() {}\n";
std::fs::write(tmp.path().join("a.rs"), content).unwrap();
let index = make_live_index_with_files(vec![("a.rs", content)]);
serialize_index(&index, tmp.path()).expect("serialize");
let snapshot = load_snapshot(tmp.path()).expect("load");
assert_eq!(
snapshot.trigrams,
index.trigram_index.to_persisted(),
"snapshot must carry the in-memory trigram index"
);
assert_eq!(
super::peek_snapshot_version(
&std::fs::read(tmp.path().join(".symforge").join("index.bin")).unwrap()
),
Some(CURRENT_VERSION)
);
let loaded = snapshot_to_live_index(snapshot, tmp.path());
let mut found = loaded
.trigram_index
.search(b"unique_token_xyzzy", &loaded.files);
found.sort();
assert_eq!(found, vec!["a.rs".to_string()]);
let mut poisoned = load_snapshot(tmp.path()).expect("reload snapshot");
let id = poisoned.trigrams.paths[0].0;
poisoned.trigrams.postings = vec![(0, vec![id])];
let poisoned_index = snapshot_to_live_index(poisoned, tmp.path());
assert!(
poisoned_index
.trigram_index
.search(b"unique_token_xyzzy", &poisoned_index.files)
.is_empty(),
"warm restore must serve persisted trigrams, not rebuild them from file bytes"
);
}
#[test]
fn prior_format_snapshot_is_peeked_and_not_restored() {
let tmp = TempDir::new().unwrap();
let bytes = vec![8u8];
let dir = tmp.path().join(".symforge");
std::fs::create_dir_all(&dir).unwrap();
std::fs::write(dir.join("index.bin"), &bytes).unwrap();
assert!(
load_snapshot(tmp.path()).is_none(),
"a format-8 payload must not restore as format 9"
);
assert_eq!(
std::fs::read(dir.join("index.bin")).unwrap(),
bytes,
"prior-format original must be preserved, not quarantined as corrupt"
);
let v11_quarantine = dir.join("v11").join("quarantine").join("index-snapshots");
let metadata: Vec<PathBuf> = std::fs::read_dir(&v11_quarantine)
.unwrap()
.map(|entry| entry.unwrap().path())
.filter(|path| path.extension().and_then(|ext| ext.to_str()) == Some("json"))
.collect();
assert_eq!(metadata.len(), 1);
let metadata: serde_json::Value =
serde_json::from_slice(&std::fs::read(&metadata[0]).unwrap()).unwrap();
assert_eq!(metadata["reason"], "v10-format-seed");
assert!(
metadata["detail"].as_str().unwrap().contains("format 8"),
"detail should name the peeked version: {}",
metadata["detail"]
);
}
#[test]
fn future_truncated_varint_is_corrupt_not_a_version_mismatch() {
let tmp = TempDir::new().unwrap();
let bytes = vec![0xE7, 0x07];
let dir = tmp.path().join(".symforge");
std::fs::create_dir_all(&dir).unwrap();
std::fs::write(dir.join("index.bin"), &bytes).unwrap();
assert!(load_snapshot(tmp.path()).is_none());
assert!(
!dir.join("index.bin").exists(),
"undecodable bytes are quarantined and removed"
);
let quarantine_metadata = quarantine_files_with_extension(tmp.path(), "json");
assert_eq!(quarantine_metadata.len(), 1);
let metadata: serde_json::Value =
serde_json::from_slice(&std::fs::read(&quarantine_metadata[0]).unwrap()).unwrap();
assert_eq!(metadata["reason"], "deserialize-error");
}
#[test]
fn test_version_mismatch_quarantines_snapshot_and_returns_none() {
let tmp = TempDir::new().unwrap();
let mut snapshot = build_snapshot(
super::capture_snapshot_build_input(&make_live_index_with_files(Vec::new())),
tmp.path(),
);
snapshot.version = 999;
let bytes = encode_snapshot(&snapshot).unwrap();
let dir = tmp.path().join(".symforge");
std::fs::create_dir_all(&dir).unwrap();
std::fs::write(dir.join("index.bin"), &bytes).unwrap();
let result = load_snapshot(tmp.path());
assert!(result.is_none(), "version mismatch must return None");
let quarantine_bins = quarantine_files_with_extension(tmp.path(), "bin");
assert_eq!(
quarantine_bins.len(),
1,
"version mismatch should preserve the snapshot in quarantine"
);
assert_eq!(
std::fs::read(&quarantine_bins[0]).unwrap(),
bytes,
"quarantine must preserve original version-mismatched bytes"
);
assert!(
!dir.join("index.bin").exists(),
"version-mismatched active snapshot should be removed after quarantine"
);
let quarantine_metadata = quarantine_files_with_extension(tmp.path(), "json");
assert_eq!(quarantine_metadata.len(), 1);
let metadata: serde_json::Value =
serde_json::from_slice(&std::fs::read(&quarantine_metadata[0]).unwrap()).unwrap();
assert_eq!(metadata["reason"], "version-mismatch");
assert_eq!(metadata["sha256"], crate::hash::digest_hex(&bytes));
}
#[test]
fn a_v10_format_snapshot_is_a_preserved_seed_never_authority() {
let tmp = TempDir::new().unwrap();
let mut snapshot = build_snapshot(
super::capture_snapshot_build_input(&make_live_index_with_files(Vec::new())),
tmp.path(),
);
snapshot.version = 7;
let bytes = postcard::to_stdvec(&snapshot).unwrap();
let dir = tmp.path().join(".symforge");
std::fs::create_dir_all(&dir).unwrap();
std::fs::write(dir.join("index.bin"), &bytes).unwrap();
let result = load_snapshot(tmp.path());
assert!(
result.is_none(),
"a V10-format snapshot must not restore under V11"
);
assert_eq!(
std::fs::read(dir.join("index.bin")).ok().as_deref(),
Some(bytes.as_slice()),
"the V10 original must be PRESERVED for rollback, not destroyed"
);
let v11_quarantine = dir.join("v11").join("quarantine").join("index-snapshots");
let quarantined: Vec<PathBuf> = std::fs::read_dir(&v11_quarantine)
.map(|entries| {
entries
.map(|entry| entry.unwrap().path())
.filter(|path| path.extension().and_then(|ext| ext.to_str()) == Some("bin"))
.collect()
})
.unwrap_or_default();
assert_eq!(
quarantined.len(),
1,
"the seed must be quarantined (as a copy) under the v11 migration namespace"
);
assert_eq!(
std::fs::read(&quarantined[0]).unwrap(),
bytes,
"the quarantined copy must hold the original seed bytes"
);
assert!(load_snapshot(tmp.path()).is_none());
let after_second: usize = std::fs::read_dir(&v11_quarantine)
.map(|entries| {
entries
.map(|entry| entry.unwrap().path())
.filter(|path| path.extension().and_then(|ext| ext.to_str()) == Some("bin"))
.count()
})
.unwrap_or_default();
assert_eq!(
after_second, 1,
"repeated starts must not accumulate duplicate seed quarantine copies"
);
assert_eq!(
std::fs::read(dir.join("index.bin")).ok().as_deref(),
Some(bytes.as_slice()),
"the original must survive repeated starts"
);
let current = build_snapshot(
super::capture_snapshot_build_input(&make_live_index_with_files(Vec::new())),
tmp.path(),
);
let current_bytes = encode_snapshot(¤t).unwrap();
std::fs::write(dir.join("index.bin"), ¤t_bytes).unwrap();
assert!(
load_snapshot(tmp.path()).is_some(),
"control: a current-format snapshot must restore"
);
}
#[test]
fn secret_policy_mismatch_forces_rescout_before_snapshot_ready() {
let tmp = TempDir::new().unwrap();
let mut snapshot = build_snapshot(
super::capture_snapshot_build_input(&make_live_index_with_files(Vec::new())),
tmp.path(),
);
let mismatched_manifest = RepositoryManifest::new(
snapshot.manifest.schema_version,
snapshot.manifest.policy_version,
crate::knowledge::SECRET_POLICY_VERSION + 1,
snapshot.manifest.source.clone(),
snapshot.manifest.source_version.clone(),
snapshot.manifest.coverage,
snapshot.manifest.entries.clone(),
snapshot.manifest.issues.clone(),
snapshot.manifest.usage,
)
.unwrap();
snapshot.manifest = mismatched_manifest;
snapshot.source_identity = super::capture_snapshot_source_identity(
tmp.path(),
snapshot.project_id.clone(),
snapshot.manifest.digest.clone(),
snapshot.source_identity.indexed_content_digest.clone(),
)
.unwrap();
let bytes = encode_snapshot(&snapshot).unwrap();
let dir = tmp.path().join(".symforge");
std::fs::create_dir_all(&dir).unwrap();
std::fs::write(dir.join("index.bin"), &bytes).unwrap();
assert!(
load_snapshot(tmp.path()).is_none(),
"a changed detector policy must force a cold re-scout"
);
let quarantine_metadata = quarantine_files_with_extension(tmp.path(), "json");
assert_eq!(quarantine_metadata.len(), 1);
let metadata: serde_json::Value =
serde_json::from_slice(&std::fs::read(&quarantine_metadata[0]).unwrap()).unwrap();
assert_eq!(metadata["reason"], "secret-policy-mismatch");
}
#[test]
fn snapshots_written_under_the_previous_secret_policy_are_refused() {
const SUPERSEDED_SECRET_POLICY_VERSION: u32 = 1;
let tmp = TempDir::new().unwrap();
let mut snapshot = build_snapshot(
super::capture_snapshot_build_input(&make_live_index_with_files(Vec::new())),
tmp.path(),
);
snapshot.manifest = RepositoryManifest::new(
snapshot.manifest.schema_version,
snapshot.manifest.policy_version,
SUPERSEDED_SECRET_POLICY_VERSION,
snapshot.manifest.source.clone(),
snapshot.manifest.source_version.clone(),
snapshot.manifest.coverage,
snapshot.manifest.entries.clone(),
snapshot.manifest.issues.clone(),
snapshot.manifest.usage,
)
.unwrap();
snapshot.source_identity = super::capture_snapshot_source_identity(
tmp.path(),
snapshot.project_id.clone(),
snapshot.manifest.digest.clone(),
snapshot.source_identity.indexed_content_digest.clone(),
)
.unwrap();
let bytes = encode_snapshot(&snapshot).unwrap();
let dir = tmp.path().join(".symforge");
std::fs::create_dir_all(&dir).unwrap();
std::fs::write(dir.join("index.bin"), &bytes).unwrap();
assert!(
load_snapshot(tmp.path()).is_none(),
"a snapshot carrying the superseded detector policy must force a \
cold re-scout rather than be trusted"
);
}
#[test]
fn runtime_canary_is_absent_from_serialized_snapshot() {
let tmp = TempDir::new().unwrap();
let canary = ["runtime", "-", "canary", "-", "snapshot"].concat();
let payload = format!("{}={}\n", ["to", "ken"].concat(), canary);
std::fs::write(tmp.path().join("notes.txt"), payload.as_bytes()).unwrap();
let shared = LiveIndex::load(tmp.path()).unwrap();
{
let index = shared.read();
assert!(index.get_file("notes.txt").is_none());
serialize_index(&index, tmp.path()).unwrap();
}
let bytes = std::fs::read(tmp.path().join(".symforge").join("index.bin")).unwrap();
assert!(
!bytes
.windows(canary.len())
.any(|window| window == canary.as_bytes())
);
let snapshot = load_snapshot(tmp.path()).expect("safe snapshot must remain loadable");
assert!(!snapshot.files.contains_key("notes.txt"));
assert!(snapshot.manifest.entries.iter().any(|entry| matches!(
entry.disposition,
FileDisposition::MetadataOnly {
reason: MetadataOnlyReason::SensitiveContent { .. }
}
)));
}
#[test]
fn same_path_repository_replacement_never_inherits_snapshot_or_temporal_state() {
let tmp = TempDir::new().unwrap();
let original_root = init_repo_with_root_commit(tmp.path());
let index = make_live_index_with_files(vec![("src/lib.rs", b"pub fn original() {}\n")]);
serialize_index(&index, tmp.path()).unwrap();
std::fs::remove_dir_all(tmp.path().join(".git")).unwrap();
let replacement = git2::Repository::init(tmp.path()).expect("replacement init");
let sig = git2::Signature::now("t", "t@x").expect("replacement signature");
let tree_id = {
let mut git_index = replacement.index().expect("replacement index");
git_index.write_tree().expect("replacement tree")
};
let tree = replacement
.find_tree(tree_id)
.expect("replacement root tree");
let replacement_root = git_test_helpers::commit_head_with_retry(
&replacement,
&sig,
&sig,
"replacement-root",
&tree,
&[],
)
.to_string();
assert_ne!(
original_root, replacement_root,
"the fixture must replace repository lineage while retaining the same canonical path"
);
assert!(
load_snapshot(tmp.path()).is_none(),
"same-path repository replacement must reject the prior snapshot and its temporal state"
);
}
#[test]
fn same_path_repository_replacement_cannot_overwrite_foreign_snapshot() {
let tmp = TempDir::new().unwrap();
init_repo_with_root_commit(tmp.path());
let original = make_live_index_with_files(vec![("src/original.rs", b"fn original() {}\n")]);
serialize_index(&original, tmp.path()).unwrap();
std::fs::remove_dir_all(tmp.path().join(".git")).unwrap();
let replacement = git2::Repository::init(tmp.path()).expect("replacement init");
let sig = git2::Signature::now("t", "t@x").expect("replacement signature");
let tree_id = {
let mut git_index = replacement.index().expect("replacement index");
git_index.write_tree().expect("replacement tree")
};
let tree = replacement.find_tree(tree_id).expect("replacement tree");
git_test_helpers::commit_head_with_retry(
&replacement,
&sig,
&sig,
"foreign-root",
&tree,
&[],
);
let foreign = make_live_index_with_files(vec![("src/foreign.rs", b"fn foreign() {}\n")]);
let result = serialize_index(&foreign, tmp.path());
assert!(
result.is_err(),
"a replacement repository must not overwrite state owned by the prior lineage"
);
assert_eq!(quarantine_files_with_extension(tmp.path(), "bin").len(), 1);
assert!(
!tmp.path().join(".symforge/index.bin").exists(),
"foreign state must be quarantined before a replacement snapshot may be written"
);
}
#[test]
fn same_path_repository_replacement_cannot_reset_foreign_snapshot() {
let tmp = TempDir::new().unwrap();
init_repo_with_root_commit(tmp.path());
let original = make_live_index_with_files(vec![("src/original.rs", b"fn original() {}\n")]);
serialize_index(&original, tmp.path()).unwrap();
std::fs::remove_dir_all(tmp.path().join(".git")).unwrap();
let replacement = git2::Repository::init(tmp.path()).expect("replacement init");
let sig = git2::Signature::now("t", "t@x").expect("replacement signature");
let tree_id = {
let mut git_index = replacement.index().expect("replacement index");
git_index.write_tree().expect("replacement tree")
};
let tree = replacement.find_tree(tree_id).expect("replacement tree");
git_test_helpers::commit_head_with_retry(
&replacement,
&sig,
&sig,
"foreign-root",
&tree,
&[],
);
let result = reset_snapshot_state(tmp.path());
assert!(
result.is_err(),
"a replacement repository must not delete state owned by the prior lineage"
);
assert_eq!(quarantine_files_with_extension(tmp.path(), "bin").len(), 1);
assert!(
!tmp.path().join(".symforge/index.bin").exists(),
"foreign state must be quarantined instead of reset in place"
);
}
#[test]
fn manifest_publication_snapshot_and_response_envelope_preserve_source_version() {
let tmp = TempDir::new().unwrap();
init_repo_with_root_commit(tmp.path());
std::fs::create_dir_all(tmp.path().join("src")).unwrap();
std::fs::write(
tmp.path().join("src/lib.rs"),
b"pub fn dirty_worktree() {}\n",
)
.unwrap();
let shared = LiveIndex::load(tmp.path()).unwrap();
let published = shared.published_generation();
let manifest = published
.manifest
.as_ref()
.expect("a bound published generation must carry its canonical manifest");
let captured_version = manifest.source_version.clone();
assert_eq!(
captured_version.working_tree,
WorkingTreeState::Dirty,
"the fixture must exercise the closed dirty working-tree state"
);
let envelope = published
.source_response_envelope()
.expect("a bound generation must format one source envelope");
checkpoint_shared_index(&shared, tmp.path(), &project_local_placement(tmp.path())).unwrap();
let snapshot = load_snapshot(tmp.path()).expect("snapshot remains bound to this source");
assert_eq!(manifest.source_version, captured_version);
assert_eq!(snapshot.source_identity.source_version, captured_version);
assert_eq!(envelope.source_version, captured_version);
assert_eq!(snapshot.source_identity.manifest_digest, manifest.digest);
assert_eq!(envelope.manifest_digest, manifest.digest);
}
#[test]
fn all_working_tree_states_round_trip_without_digest_substitution() {
let tmp = TempDir::new().unwrap();
let index = make_live_index_with_files(vec![("src/lib.rs", b"pub fn source() {}\n")]);
for working_tree in [
WorkingTreeState::Clean,
WorkingTreeState::Dirty,
WorkingTreeState::NotApplicable,
WorkingTreeState::Unknown,
] {
let mut snapshot = build_snapshot(capture_snapshot_build_input(&index), tmp.path());
let version = SourceVersion {
branch: Some("fixture-branch".to_string()),
commit: Some("fixture-commit".to_string()),
working_tree,
};
snapshot.manifest.source_version = version.clone();
snapshot.source_identity.source_version = version.clone();
snapshot.code_signals.computed_for_source_version = version.clone();
let manifest_digest = snapshot.manifest.digest.clone();
let header_manifest_digest = snapshot.source_identity.manifest_digest.clone();
let resident_content_digest = snapshot.source_identity.indexed_content_digest.clone();
let bytes = encode_snapshot(&snapshot).unwrap();
let restored = decode_snapshot(&bytes).unwrap();
assert_eq!(restored.manifest.source_version, version);
assert_eq!(restored.source_identity.source_version, version);
assert_eq!(restored.code_signals.computed_for_source_version, version);
assert_eq!(restored.manifest.digest, manifest_digest);
assert_eq!(
restored.source_identity.manifest_digest,
header_manifest_digest
);
assert_eq!(
restored.source_identity.indexed_content_digest,
resident_content_digest
);
}
}
#[test]
fn snapshot_round_trip_restores_code_signals_into_published_generation() {
let tmp = TempDir::new().unwrap();
std::fs::create_dir_all(tmp.path().join("src")).unwrap();
std::fs::write(tmp.path().join("src/lib.rs"), b"pub fn temporal() {}\n").unwrap();
let shared = crate::live_index::LiveIndex::load(tmp.path()).expect("rooted load");
assert!(
shared.published_generation().manifest.is_some(),
"rooted load must publish a vouched manifest before mutation"
);
shared.remove_file("src/lib.rs");
shared.update_git_temporal(
crate::live_index::git_temporal::GitTemporalIndex::unavailable(
"fixture-history-unavailable".to_string(),
),
);
assert!(
shared.published_generation().manifest.is_some(),
"rooted mutations must recapture a vouched manifest before checkpoint"
);
let expected = shared.published_generation().code_signals.clone();
assert!(
expected.computed_for_content_generation > 0,
"the fixture must prove provenance survives rather than coincidentally restoring generation zero"
);
checkpoint_shared_index(&shared, tmp.path(), &project_local_placement(tmp.path())).unwrap();
let snapshot = load_snapshot(tmp.path()).expect("snapshot");
let (live, code_signals) = snapshot_to_live_index_with_code_signals(snapshot, tmp.path());
let restored =
crate::live_index::SharedIndexHandle::shared_with_code_signals(live, code_signals);
assert_eq!(
restored.published_generation().code_signals.state,
crate::live_index::git_temporal::GitTemporalState::Unavailable(
"fixture-history-unavailable".to_string()
)
);
let restored = restored.published_generation();
assert_eq!(
restored.code_signals.computed_for_content_generation,
expected.computed_for_content_generation
);
assert_eq!(
restored.code_signals.computed_for_source_version,
expected.computed_for_source_version
);
assert_eq!(restored.code_signals.coverage, expected.coverage);
}
#[test]
fn test_corrupt_bytes_quarantined_and_returns_none_no_panic() {
let tmp = TempDir::new().unwrap();
let dir = tmp.path().join(".symforge");
std::fs::create_dir_all(&dir).unwrap();
std::fs::write(
dir.join("index.bin"),
b"not valid postcard data xyzzy 12345",
)
.unwrap();
let result = load_snapshot(tmp.path());
assert!(
result.is_none(),
"corrupt bytes must return None, not panic"
);
let quarantine_bins = quarantine_files_with_extension(tmp.path(), "bin");
assert_eq!(
quarantine_bins.len(),
1,
"corrupt bytes should be preserved in quarantine"
);
assert_eq!(
std::fs::read(&quarantine_bins[0]).unwrap(),
b"not valid postcard data xyzzy 12345",
"quarantine must preserve original corrupt bytes"
);
assert!(
!dir.join("index.bin").exists(),
"corrupt active snapshot should be removed after quarantine"
);
let quarantine_metadata = quarantine_files_with_extension(tmp.path(), "json");
assert_eq!(quarantine_metadata.len(), 1);
let metadata: serde_json::Value =
serde_json::from_slice(&std::fs::read(&quarantine_metadata[0]).unwrap()).unwrap();
assert_eq!(metadata["reason"], "deserialize-error");
}
#[test]
fn single_bit_symbol_metadata_corruption_is_quarantined() {
let tmp = TempDir::new().unwrap();
let content = b"fn my_func() { other_func(); }";
std::fs::write(tmp.path().join("main.rs"), content).unwrap();
let index = make_live_index_with_files(vec![("main.rs", content)]);
serialize_index(&index, tmp.path()).unwrap();
let path = tmp.path().join(".symforge").join(INDEX_FILENAME);
let original = std::fs::read(&path).unwrap();
let mut snapshot = load_snapshot(tmp.path()).expect("control: intact snapshot restores");
assert_eq!(snapshot.files["main.rs"].symbols[0].name, "my_func");
snapshot.files.get_mut("main.rs").unwrap().symbols[0].name = "ly_func".to_string();
let mut corrupt = postcard::to_stdvec(&snapshot).unwrap();
let payload_len = corrupt.len();
corrupt.extend_from_slice(&original[payload_len..]);
assert_eq!(original.len(), corrupt.len());
let changed_bits: Vec<u8> = original
.iter()
.zip(&corrupt)
.filter_map(|(before, after)| (before != after).then_some(before ^ after))
.collect();
assert_eq!(changed_bits, vec![1], "fixture changes exactly one bit");
std::fs::write(&path, &corrupt).unwrap();
assert!(
load_snapshot(tmp.path()).is_none(),
"a one-bit symbol metadata corruption must never restore"
);
let quarantined = quarantine_files_with_extension(tmp.path(), "bin");
assert_eq!(quarantined.len(), 1);
assert_eq!(std::fs::read(&quarantined[0]).unwrap(), corrupt);
assert!(!path.exists());
assert_eq!(std::fs::read(tmp.path().join("main.rs")).unwrap(), content);
}
#[test]
fn snapshot_wire_corruption_is_quarantined_before_restore() {
for corruption in ["content", "checksum", "truncated", "missing-checksum"] {
let tmp = TempDir::new().unwrap();
let content = b"fn my_func() { other_func(); }";
let index = make_live_index_with_files(vec![("main.rs", content)]);
serialize_index(&index, tmp.path()).unwrap();
let path = tmp.path().join(".symforge").join(INDEX_FILENAME);
let original = std::fs::read(&path).unwrap();
assert!(load_snapshot(tmp.path()).is_some());
let mut corrupt = original.clone();
match corruption {
"content" => {
let offset = corrupt
.windows(content.len())
.position(|bytes| bytes == content)
.unwrap();
corrupt[offset] ^= 1;
}
"checksum" => *corrupt.last_mut().unwrap() ^= 1,
"truncated" => {
corrupt.pop();
}
"missing-checksum" => corrupt.truncate(corrupt.len() - 32),
_ => unreachable!(),
}
std::fs::write(&path, &corrupt).unwrap();
assert!(
load_snapshot(tmp.path()).is_none(),
"{corruption} must refuse restore"
);
let quarantined = quarantine_files_with_extension(tmp.path(), "bin");
assert_eq!(quarantined.len(), 1, "{corruption}");
assert_eq!(
std::fs::read(&quarantined[0]).unwrap(),
corrupt,
"{corruption}"
);
assert!(!path.exists());
}
}
#[test]
fn corrupt_existing_snapshot_is_preserved_before_write_or_reset() {
for reset in [false, true] {
let tmp = TempDir::new().unwrap();
let index = make_live_index_with_files(vec![("main.rs", b"fn my_func() {}")]);
serialize_index(&index, tmp.path()).unwrap();
let path = tmp.path().join(".symforge").join(INDEX_FILENAME);
let mut corrupt = std::fs::read(&path).unwrap();
*corrupt.last_mut().unwrap() ^= 1;
std::fs::write(&path, &corrupt).unwrap();
let result = if reset {
reset_snapshot_state(tmp.path()).map(|_| ())
} else {
serialize_index(&index, tmp.path())
};
assert!(
result.is_err(),
"invalid existing snapshot must refuse mutation"
);
let quarantined = quarantine_files_with_extension(tmp.path(), "bin");
assert_eq!(quarantined.len(), 1);
assert_eq!(std::fs::read(&quarantined[0]).unwrap(), corrupt);
assert!(!path.exists());
}
}
#[test]
fn format_ten_snapshot_is_preserved_without_checksum() {
let tmp = TempDir::new().unwrap();
let mut snapshot = build_snapshot(
super::capture_snapshot_build_input(&make_live_index_with_files(Vec::new())),
tmp.path(),
);
snapshot.version = 10;
let original = postcard::to_stdvec(&snapshot).unwrap();
let dir = tmp.path().join(".symforge");
std::fs::create_dir_all(&dir).unwrap();
std::fs::write(dir.join(INDEX_FILENAME), &original).unwrap();
assert!(load_snapshot(tmp.path()).is_none());
assert_eq!(std::fs::read(dir.join(INDEX_FILENAME)).unwrap(), original);
let quarantine = dir.join("v11").join("quarantine").join("index-snapshots");
let copies: Vec<_> = std::fs::read_dir(quarantine)
.unwrap()
.map(|entry| entry.unwrap().path())
.filter(|path| path.extension().and_then(|ext| ext.to_str()) == Some("bin"))
.collect();
assert_eq!(copies.len(), 1);
assert_eq!(std::fs::read(&copies[0]).unwrap(), original);
}
#[test]
fn test_truncated_bytes_quarantined_and_returns_none_no_panic() {
let tmp = TempDir::new().unwrap();
let index = make_live_index_with_files(vec![("a.rs", b"fn foo() {}")]);
serialize_index(&index, tmp.path()).expect("serialize should succeed");
let bin_path = tmp.path().join(".symforge").join("index.bin");
let full_bytes = std::fs::read(&bin_path).unwrap();
let truncated = &full_bytes[..full_bytes.len() / 2];
std::fs::write(&bin_path, truncated).unwrap();
let result = load_snapshot(tmp.path());
assert!(
result.is_none(),
"truncated bytes must return None, not panic"
);
let quarantine_bins = quarantine_files_with_extension(tmp.path(), "bin");
assert_eq!(
quarantine_bins.len(),
1,
"truncated bytes should be preserved in quarantine"
);
assert_eq!(std::fs::read(&quarantine_bins[0]).unwrap(), truncated);
}
#[test]
fn test_missing_file_returns_none() {
let tmp = TempDir::new().unwrap();
let result = load_snapshot(tmp.path());
assert!(result.is_none(), "missing file must return None");
assert!(
quarantine_files_with_extension(tmp.path(), "bin").is_empty(),
"missing first-run snapshot should not create quarantine artifacts"
);
}
#[test]
fn test_stat_check_identifies_changed_file_by_size() {
let tmp = TempDir::new().unwrap();
let file_path = tmp.path().join("a.rs");
std::fs::write(&file_path, b"fn foo() {}").unwrap();
let mut file_map: HashMap<String, Arc<IndexedFile>> = HashMap::new();
file_map.insert(
"a.rs".to_string(),
Arc::new(IndexedFile {
relative_path: "a.rs".to_string(),
language: LanguageId::Rust,
classification: crate::domain::FileClassification::for_code_path("a.rs"),
content: b"fn foo() {}".to_vec(),
symbols: vec![],
parse_status: ParseStatus::Parsed,
parse_diagnostic: None,
byte_len: 999, content_hash: "old_hash".to_string(),
references: vec![],
alias_map: HashMap::new(),
mtime_secs: 0,
}),
);
let trigram_index = crate::live_index::trigram::TrigramIndex::build_from_files(&file_map);
let mut index = LiveIndex {
files: file_map,
loaded_at: Instant::now(),
loaded_at_system: SystemTime::now(),
load_duration: Duration::ZERO,
cb_state: CircuitBreakerState::new(0.20),
is_empty: false,
load_source: IndexLoadSource::FreshLoad,
snapshot_verify_state: SnapshotVerifyState::NotNeeded,
reverse_index: HashMap::new(),
files_by_basename: HashMap::new(),
files_by_dir_component: HashMap::new(),
trigram_index,
gitignore: None,
manifest_entries: Vec::new(),
coupling_store: None,
local_empty_reason: Arc::new(parking_lot::RwLock::new(None)),
indexed_root: None,
};
index.rebuild_reverse_index();
index.rebuild_path_indices();
let mtime = std::fs::metadata(&file_path)
.unwrap()
.modified()
.unwrap()
.duration_since(UNIX_EPOCH)
.unwrap()
.as_secs();
let mut mtimes: HashMap<String, u64> = HashMap::new();
mtimes.insert("a.rs".to_string(), mtime);
let result =
stat_check_files_from_view(&capture_verify_view(&index), &mtimes, tmp.path(), &|| {
false
})
.unwrap();
assert!(
result.changed.contains(&"a.rs".to_string()),
"changed by size mismatch"
);
assert!(result.deleted.is_empty());
}
#[test]
fn test_stat_check_identifies_deleted_file() {
let tmp = TempDir::new().unwrap();
let mut file_map: HashMap<String, Arc<IndexedFile>> = HashMap::new();
file_map.insert(
"ghost.rs".to_string(),
Arc::new(IndexedFile {
relative_path: "ghost.rs".to_string(),
language: LanguageId::Rust,
classification: crate::domain::FileClassification::for_code_path("ghost.rs"),
content: b"fn ghost() {}".to_vec(),
symbols: vec![],
parse_status: ParseStatus::Parsed,
parse_diagnostic: None,
byte_len: 13,
content_hash: "hash".to_string(),
references: vec![],
alias_map: HashMap::new(),
mtime_secs: 0,
}),
);
let trigram_index = crate::live_index::trigram::TrigramIndex::build_from_files(&file_map);
let mut index = LiveIndex {
files: file_map,
loaded_at: Instant::now(),
loaded_at_system: SystemTime::now(),
load_duration: Duration::ZERO,
cb_state: CircuitBreakerState::new(0.20),
is_empty: false,
load_source: IndexLoadSource::FreshLoad,
snapshot_verify_state: SnapshotVerifyState::NotNeeded,
reverse_index: HashMap::new(),
files_by_basename: HashMap::new(),
files_by_dir_component: HashMap::new(),
trigram_index,
gitignore: None,
manifest_entries: Vec::new(),
coupling_store: None,
local_empty_reason: Arc::new(parking_lot::RwLock::new(None)),
indexed_root: None,
};
index.rebuild_reverse_index();
index.rebuild_path_indices();
let result = stat_check_files_from_view(
&capture_verify_view(&index),
&HashMap::new(),
tmp.path(),
&|| false,
)
.unwrap();
assert!(
result.deleted.contains(&"ghost.rs".to_string()),
"missing file should be in deleted"
);
}
#[test]
fn test_stat_check_identifies_new_file() {
let tmp = TempDir::new().unwrap();
std::fs::write(tmp.path().join("new.rs"), b"fn new_func() {}").unwrap();
let index = make_live_index_with_files(vec![]);
let result = stat_check_files_from_view(
&capture_verify_view(&index),
&HashMap::new(),
tmp.path(),
&|| false,
)
.unwrap();
assert!(
result.new_files.contains(&"new.rs".to_string()),
"new file should be detected"
);
}
#[test]
fn stat_check_does_not_report_unchanged_terminal_catalog_entries_as_new() {
let tmp = TempDir::new().unwrap();
let meta_bytes = b"not-utf8-\xff-bytes";
let hard_bytes = vec![0u8; 64];
std::fs::write(tmp.path().join("legacy.txt"), meta_bytes).unwrap();
std::fs::write(tmp.path().join("oversized.bin"), &hard_bytes).unwrap();
std::fs::write(tmp.path().join("brand_new.rs"), b"fn fresh() {}").unwrap();
let mut index = make_live_index_with_files(vec![]);
index.manifest_entries = vec![
CatalogEntry {
path: CatalogPath {
public_id: "legacy.txt".to_string(),
normalized_utf8: Some("legacy.txt".to_string()),
},
size: meta_bytes.len() as u64,
language: None,
classification: crate::domain::FileClassification::for_code_path("legacy.txt"),
disposition: FileDisposition::MetadataOnly {
reason: MetadataOnlyReason::UnsupportedTextEncoding,
},
content_hash: None,
},
CatalogEntry {
path: CatalogPath {
public_id: "oversized.bin".to_string(),
normalized_utf8: Some("oversized.bin".to_string()),
},
size: hard_bytes.len() as u64,
language: None,
classification: crate::domain::FileClassification::for_code_path("oversized.bin"),
disposition: FileDisposition::HardSkip {
reason: HardSkipReason::PerFileCeiling,
},
content_hash: None,
},
];
let result = stat_check_files_from_view(
&capture_verify_view(&index),
&HashMap::new(),
tmp.path(),
&|| false,
)
.unwrap();
assert!(
!result
.new_files
.iter()
.any(|p| p == "legacy.txt" || p == "oversized.bin"),
"unchanged terminal catalog paths must not be rediscovered as new: {:?}",
result.new_files
);
assert!(
result.new_files.contains(&"brand_new.rs".to_string()),
"a path absent from both resident rows and the terminal catalog must still be new"
);
assert!(
result.changed.is_empty(),
"unchanged terminals are not changed"
);
assert!(
result.deleted.is_empty(),
"present terminals are not deleted"
);
}
#[test]
fn restore_with_terminal_catalog_reports_zero_new_when_unchanged() {
let tmp = TempDir::new().unwrap();
let content = b"fn main() {}\n";
std::fs::create_dir_all(tmp.path().join("src")).unwrap();
std::fs::write(tmp.path().join("src/main.rs"), content).unwrap();
let meta_bytes = b"latin1-\xe9-text";
let hard_bytes = vec![0u8; 32];
std::fs::write(tmp.path().join("encoding.txt"), meta_bytes).unwrap();
std::fs::write(tmp.path().join("blob.bin"), &hard_bytes).unwrap();
let mut index = make_live_index_with_files(vec![("src/main.rs", content)]);
let mtime_secs = std::fs::metadata(tmp.path().join("src/main.rs"))
.unwrap()
.modified()
.unwrap()
.duration_since(std::time::UNIX_EPOCH)
.unwrap()
.as_secs();
{
let file = Arc::make_mut(index.files.get_mut("src/main.rs").unwrap());
file.mtime_secs = mtime_secs;
}
index.manifest_entries = vec![
CatalogEntry {
path: CatalogPath {
public_id: "blob.bin".to_string(),
normalized_utf8: Some("blob.bin".to_string()),
},
size: hard_bytes.len() as u64,
language: None,
classification: crate::domain::FileClassification::for_code_path("blob.bin"),
disposition: FileDisposition::HardSkip {
reason: HardSkipReason::PerFileCeiling,
},
content_hash: None,
},
CatalogEntry {
path: CatalogPath {
public_id: "encoding.txt".to_string(),
normalized_utf8: Some("encoding.txt".to_string()),
},
size: meta_bytes.len() as u64,
language: None,
classification: crate::domain::FileClassification::for_code_path("encoding.txt"),
disposition: FileDisposition::MetadataOnly {
reason: MetadataOnlyReason::UnsupportedTextEncoding,
},
content_hash: None,
},
CatalogEntry {
path: CatalogPath {
public_id: "src/main.rs".to_string(),
normalized_utf8: Some("src/main.rs".to_string()),
},
size: content.len() as u64,
language: LanguageId::from_extension("rs"),
classification: crate::domain::FileClassification::for_code_path("src/main.rs"),
disposition: FileDisposition::Indexed {
targets: IndexTargets::CodeAndKnowledge,
parse_status: crate::domain::index::ParseStatus::Parsed,
},
content_hash: Some(crate::hash::digest_hex(content)),
},
];
let expected_terminals = index.manifest_entries.clone();
serialize_index(&index, tmp.path()).expect("serialize");
let snapshot = load_snapshot(tmp.path()).expect("load snapshot");
let loaded = snapshot_to_live_index(snapshot, tmp.path());
assert_eq!(
loaded.manifest_entries, expected_terminals,
"terminal catalog entries must survive the snapshot round-trip"
);
let snapshot_mtimes: HashMap<String, u64> = loaded
.files
.iter()
.map(|(path, file)| (path.clone(), file.mtime_secs))
.collect();
let result = stat_check_files_from_view(
&capture_verify_view(&loaded),
&snapshot_mtimes,
tmp.path(),
&|| false,
)
.unwrap();
assert_eq!(
result.new_files,
Vec::<String>::new(),
"second restore over an unchanged tree must report 0 new; got {:?}",
result.new_files
);
assert!(
result.changed.is_empty(),
"unchanged restore must report 0 changed"
);
assert!(
result.deleted.is_empty(),
"unchanged restore must report 0 deleted"
);
}
#[test]
fn test_spot_verify_catches_content_hash_mismatch() {
let tmp = TempDir::new().unwrap();
let file_path = tmp.path().join("a.rs");
std::fs::write(&file_path, b"fn modified() {}").unwrap();
let mut file_map: HashMap<String, Arc<IndexedFile>> = HashMap::new();
file_map.insert(
"a.rs".to_string(),
Arc::new(IndexedFile {
relative_path: "a.rs".to_string(),
language: LanguageId::Rust,
classification: crate::domain::FileClassification::for_code_path("a.rs"),
content: b"fn original() {}".to_vec(), symbols: vec![],
parse_status: ParseStatus::Parsed,
parse_diagnostic: None,
byte_len: 16,
content_hash: crate::hash::digest_hex(b"fn original() {}"), references: vec![],
alias_map: HashMap::new(),
mtime_secs: 0,
}),
);
let trigram_index = crate::live_index::trigram::TrigramIndex::build_from_files(&file_map);
let mut index = LiveIndex {
files: file_map,
loaded_at: Instant::now(),
loaded_at_system: SystemTime::now(),
load_duration: Duration::ZERO,
cb_state: CircuitBreakerState::new(0.20),
is_empty: false,
load_source: IndexLoadSource::FreshLoad,
snapshot_verify_state: SnapshotVerifyState::NotNeeded,
reverse_index: HashMap::new(),
files_by_basename: HashMap::new(),
files_by_dir_component: HashMap::new(),
trigram_index,
gitignore: None,
manifest_entries: Vec::new(),
coupling_store: None,
local_empty_reason: Arc::new(parking_lot::RwLock::new(None)),
indexed_root: None,
};
index.rebuild_reverse_index();
index.rebuild_path_indices();
let (mismatches, _) = spot_verify_sample_from_view(
&capture_verify_view(&index),
tmp.path(),
1.0,
None,
&|| false,
)
.unwrap();
assert!(
mismatches.contains(&"a.rs".to_string()),
"hash mismatch should be detected"
);
}
#[test]
fn test_spot_verify_no_mismatch_when_hashes_match() {
let tmp = TempDir::new().unwrap();
let content = b"fn current() {}";
let file_path = tmp.path().join("a.rs");
std::fs::write(&file_path, content).unwrap();
let hash = crate::hash::digest_hex(content);
let mut file_map: HashMap<String, Arc<IndexedFile>> = HashMap::new();
file_map.insert(
"a.rs".to_string(),
Arc::new(IndexedFile {
relative_path: "a.rs".to_string(),
language: LanguageId::Rust,
classification: crate::domain::FileClassification::for_code_path("a.rs"),
content: content.to_vec(),
symbols: vec![],
parse_status: ParseStatus::Parsed,
parse_diagnostic: None,
byte_len: content.len() as u64,
content_hash: hash,
references: vec![],
alias_map: HashMap::new(),
mtime_secs: 0,
}),
);
let trigram_index = crate::live_index::trigram::TrigramIndex::build_from_files(&file_map);
let mut index = LiveIndex {
files: file_map,
loaded_at: Instant::now(),
loaded_at_system: SystemTime::now(),
load_duration: Duration::ZERO,
cb_state: CircuitBreakerState::new(0.20),
is_empty: false,
load_source: IndexLoadSource::FreshLoad,
snapshot_verify_state: SnapshotVerifyState::NotNeeded,
reverse_index: HashMap::new(),
files_by_basename: HashMap::new(),
files_by_dir_component: HashMap::new(),
trigram_index,
gitignore: None,
manifest_entries: Vec::new(),
coupling_store: None,
local_empty_reason: Arc::new(parking_lot::RwLock::new(None)),
indexed_root: None,
};
index.rebuild_reverse_index();
index.rebuild_path_indices();
let (mismatches, _) = spot_verify_sample_from_view(
&capture_verify_view(&index),
tmp.path(),
1.0,
None,
&|| false,
)
.unwrap();
assert!(mismatches.is_empty(), "no mismatch when hash is current");
}
#[test]
fn test_spot_verify_empty_index_returns_empty() {
let tmp = TempDir::new().unwrap();
let index = make_live_index_with_files(vec![]);
let (mismatches, _) = spot_verify_sample_from_view(
&capture_verify_view(&index),
tmp.path(),
0.10,
None,
&|| false,
)
.unwrap();
assert!(mismatches.is_empty(), "empty index returns empty vec");
}
#[test]
fn test_snapshot_path_locks_isolate_distinct_projects() {
let first = TempDir::new().expect("create first project");
let second = TempDir::new().expect("create second project");
let (_, first_lock) =
snapshot_path_and_lock(first.path()).expect("resolve first snapshot lock");
let (_, same_lock) = snapshot_path_and_lock(&first.path().join("."))
.expect("resolve canonical-equivalent snapshot lock");
let (_, second_lock) =
snapshot_path_and_lock(second.path()).expect("resolve second snapshot lock");
assert!(
Arc::ptr_eq(&first_lock, &same_lock),
"canonical-equivalent snapshot paths must share one lock"
);
assert!(
!Arc::ptr_eq(&first_lock, &second_lock),
"different snapshot paths must not share a lock"
);
let first_guard = first_lock.lock().expect("lock first snapshot path");
assert!(
same_lock.try_lock().is_err(),
"same-path writes must serialize"
);
assert!(
second_lock.try_lock().is_ok(),
"different snapshot paths must not block each other"
);
drop(first_guard);
}
#[test]
fn test_reset_snapshot_state_waits_for_snapshot_path_lock() {
let tmp = TempDir::new().expect("create project");
let symforge_dir = tmp.path().join(".symforge");
std::fs::create_dir_all(&symforge_dir).expect("create .symforge");
let snapshot_path = symforge_dir.join(INDEX_FILENAME);
serialize_index(
&make_live_index_with_files(vec![("src/lib.rs", b"fn source_file() {}\n")]),
tmp.path(),
)
.expect("write valid owned snapshot");
let (_, snapshot_lock) = snapshot_path_and_lock(tmp.path()).expect("resolve snapshot lock");
let write_guard = snapshot_lock.lock().expect("hold snapshot write lock");
let project_root = tmp.path().to_path_buf();
let (started_tx, started_rx) = std::sync::mpsc::channel();
let (done_tx, done_rx) = std::sync::mpsc::channel();
let reset_thread = std::thread::spawn(move || {
started_tx.send(()).expect("signal reset start");
let report = reset_snapshot_state(&project_root);
done_tx.send(report).expect("send reset result");
});
started_rx.recv().expect("reset thread started");
let early_result = done_rx.recv_timeout(Duration::from_millis(200)).ok();
let snapshot_survived_while_locked = snapshot_path.exists();
drop(write_guard);
let completed_early = early_result.is_some();
let report = match early_result {
Some(report) => report,
None => done_rx
.recv_timeout(Duration::from_secs(2))
.expect("reset should finish after releasing lock"),
}
.expect("reset snapshot state");
reset_thread.join().expect("join reset thread");
assert!(
!completed_early,
"reset must block while a snapshot write owns the path lock"
);
assert!(
snapshot_survived_while_locked,
"reset must not delete the published snapshot during a write"
);
assert_eq!(report.removed_count(), 1);
assert!(!snapshot_path.exists());
}
#[test]
fn test_quarantine_waits_for_snapshot_path_lock() {
let tmp = TempDir::new().expect("create project");
let symforge_dir = tmp.path().join(".symforge");
std::fs::create_dir_all(&symforge_dir).expect("create .symforge");
let snapshot_path = symforge_dir.join(INDEX_FILENAME);
std::fs::write(&snapshot_path, b"corrupt snapshot bytes").expect("write snapshot");
let (_, snapshot_lock) = snapshot_path_and_lock(tmp.path()).expect("resolve snapshot lock");
let write_guard = snapshot_lock.lock().expect("hold snapshot write lock");
let project_root = tmp.path().to_path_buf();
let thread_snapshot_path = snapshot_path.clone();
let (started_tx, started_rx) = std::sync::mpsc::channel();
let (done_tx, done_rx) = std::sync::mpsc::channel();
let quarantine_thread = std::thread::spawn(move || {
started_tx.send(()).expect("signal quarantine start");
let result = quarantine_bad_snapshot(
&project_root,
&thread_snapshot_path,
b"corrupt snapshot bytes",
"test-reason",
"test detail".to_string(),
);
done_tx.send(result).expect("send quarantine result");
});
started_rx.recv().expect("quarantine thread started");
let early_result = done_rx.recv_timeout(Duration::from_millis(200)).ok();
let snapshot_survived_while_locked = snapshot_path.exists();
drop(write_guard);
let completed_early = early_result.is_some();
let result = match early_result {
Some(result) => result,
None => done_rx
.recv_timeout(Duration::from_secs(2))
.expect("quarantine should finish after releasing lock"),
}
.expect("quarantine bad snapshot");
quarantine_thread.join().expect("join quarantine thread");
assert!(
!completed_early,
"quarantine must block while a snapshot write owns the path lock"
);
assert!(
snapshot_survived_while_locked,
"quarantine must not delete the published snapshot during a write"
);
assert!(result.exists(), "quarantine artifact written");
assert!(!snapshot_path.exists(), "bad snapshot removed after lock");
}
#[test]
fn test_snapshot_temp_paths_are_unique_and_process_scoped() {
let tmp = TempDir::new().expect("create project");
let symforge_dir = paths::ensure_symforge_dir(tmp.path()).expect("create .symforge");
let first = next_snapshot_temp_path(&symforge_dir);
let second = next_snapshot_temp_path(&symforge_dir);
let process_prefix = format!("{INDEX_TMP_FILENAME}.{}.", std::process::id());
assert_ne!(
first, second,
"each snapshot write needs a unique temp path"
);
for path in [first, second] {
let name = path
.file_name()
.and_then(|name| name.to_str())
.expect("temp path has a UTF-8 file name");
assert!(
name.starts_with(&process_prefix),
"temp name must include the writer PID and counter: {name}"
);
}
}
#[test]
fn test_snapshot_write_error_removes_owned_temp_file() {
let tmp = TempDir::new().expect("create project");
let symforge_dir = paths::ensure_symforge_dir(tmp.path()).expect("create .symforge");
let blocking_final_path = symforge_dir.join(INDEX_FILENAME);
std::fs::create_dir(&blocking_final_path).expect("block snapshot rename with directory");
std::fs::write(
blocking_final_path.join("sentinel"),
b"keep directory non-empty",
)
.expect("write blocking sentinel");
let index = make_live_index_with_files(vec![("src/lib.rs", b"fn lib() {}")]);
serialize_index(&index, tmp.path()).expect_err("snapshot rename should fail");
let leftover_temps: Vec<_> = std::fs::read_dir(&symforge_dir)
.expect("list .symforge")
.map(|entry| entry.expect("read .symforge entry"))
.filter(|entry| is_unique_snapshot_temp_name(&entry.file_name()))
.map(|entry| entry.path())
.collect();
assert!(
leftover_temps.is_empty(),
"failed writes must remove their own temp file: {leftover_temps:?}"
);
}
fn capture_named_tmp_persist_stages<R>(op: impl FnOnce() -> R) -> (R, Vec<&'static str>) {
super::SNAPSHOT_PERSIST_STAGES.with(|cell| {
*cell.borrow_mut() = Some(Vec::new());
});
let result = op();
let stages = super::SNAPSHOT_PERSIST_STAGES
.with(|cell| cell.borrow_mut().take())
.unwrap_or_default();
(result, stages)
}
fn assert_sync_all_before_rename(stages: &[&'static str]) {
let sync_all = stages
.iter()
.position(|stage| *stage == "sync_all")
.expect("persist wrapper must observe File::sync_all");
let rename = stages
.iter()
.position(|stage| *stage == "rename")
.expect("persist wrapper must observe rename");
assert!(
sync_all < rename,
"sync_all must be recorded before rename, got {stages:?}"
);
}
#[test]
fn snapshot_sync_all_is_observed_before_rename() {
let tmp = TempDir::new().expect("create project");
let dest = tmp.path().join("index.bin");
let named_tmp = tmp.path().join("index.bin.tmp.1.0");
std::fs::write(&dest, b"old-bytes").expect("seed previous dest");
let ((), helper_stages) = capture_named_tmp_persist_stages(|| {
super::persist_named_tmp(&named_tmp, &dest, b"new-bytes").expect("helper persist");
});
assert_sync_all_before_rename(&helper_stages);
assert_eq!(
std::fs::read(&dest).expect("read helper dest"),
b"new-bytes",
"completed persist leaves the new bytes"
);
let index = make_live_index_with_files(vec![("src/lib.rs", b"fn lib() {}")]);
let ((), snapshot_stages) = capture_named_tmp_persist_stages(|| {
serialize_index(&index, tmp.path()).expect("write_snapshot persist");
});
assert_sync_all_before_rename(&snapshot_stages);
let snapshot_path = tmp.path().join(".symforge").join(INDEX_FILENAME);
let snapshot_bytes = std::fs::read(&snapshot_path).expect("read snapshot");
let restored = decode_snapshot(&snapshot_bytes)
.expect("completed write_snapshot leaves decodable new bytes");
assert_eq!(restored.files.len(), 1);
let (report, artifact_stages) = capture_named_tmp_persist_stages(|| {
export_artifact_legacy(&index, tmp.path()).expect("export_artifact persist")
});
assert_sync_all_before_rename(&artifact_stages);
let zst = std::fs::read(&report.path).expect("read zst");
assert!(
!zst.is_empty(),
"completed artifact persist leaves zst bytes"
);
let metadata = std::fs::read(&report.metadata_path).expect("read artifact.json");
assert!(
!metadata.is_empty(),
"artifact.json persist leaves the new bytes"
);
}
struct FailNamedTmpSyncAll;
impl Drop for FailNamedTmpSyncAll {
fn drop(&mut self) {
super::FAIL_NAMED_TMP_SYNC_ALL.with(|cell| cell.set(false));
}
}
#[test]
fn snapshot_sync_all_failure_does_not_rename_or_report_success() {
let tmp = TempDir::new().expect("create project");
let dest = tmp.path().join("index.bin");
let named_tmp = tmp.path().join("index.bin.tmp.1.0");
std::fs::write(&dest, b"old-bytes").expect("seed previous dest");
let _fail = FailNamedTmpSyncAll;
super::FAIL_NAMED_TMP_SYNC_ALL.with(|cell| cell.set(true));
let (result, stages) = capture_named_tmp_persist_stages(|| {
super::persist_named_tmp(&named_tmp, &dest, b"new-bytes")
});
assert!(
result.is_err(),
"simulated sync_all failure must not report success"
);
assert!(
!stages.contains(&"rename"),
"sync_all failure must not rename, got {stages:?}"
);
assert_eq!(
std::fs::read(&dest).expect("read dest after failed persist"),
b"old-bytes",
"previous dest bytes stay in place"
);
assert!(
!named_tmp.exists(),
"failed write must remove its tmp: {}",
named_tmp.display()
);
}
#[test]
fn test_serialize_creates_symforge_dir() {
let tmp = TempDir::new().unwrap();
let index = make_live_index_with_files(vec![("src/lib.rs", b"fn lib() {}")]);
serialize_index(&index, tmp.path()).expect("serialize should succeed");
assert!(
tmp.path().join(".symforge").join("index.bin").exists(),
".symforge/index.bin should be created"
);
}
#[test]
fn test_reset_snapshot_state_deletes_only_snapshot_scope() {
let tmp = TempDir::new().unwrap();
let symforge_dir = tmp.path().join(".symforge");
let source_dir = tmp.path().join("src");
std::fs::create_dir_all(&symforge_dir).expect("create .symforge");
std::fs::create_dir_all(&source_dir).expect("create source dir");
std::fs::write(source_dir.join("lib.rs"), "fn source_file() {}\n").expect("write source");
serialize_index(
&make_live_index_with_files(vec![("src/lib.rs", b"fn source_file() {}\n")]),
tmp.path(),
)
.expect("write valid owned snapshot");
std::fs::write(symforge_dir.join("index.bin.tmp"), b"stale tmp").expect("write tmp");
let stale_unique_tmp = symforge_dir.join("index.bin.tmp.4242.7");
let unrelated_similar_name = symforge_dir.join("index.bin.tmp.not-owned");
std::fs::write(&stale_unique_tmp, b"stale unique tmp").expect("write unique tmp");
std::fs::write(&unrelated_similar_name, b"unrelated").expect("write similar sentinel");
std::fs::write(symforge_dir.join("frecency.db"), b"unrelated").expect("write sentinel");
let report = reset_snapshot_state(tmp.path()).expect("reset snapshot state");
assert_eq!(report.removed_count(), 3);
assert!(!symforge_dir.join("index.bin").exists());
assert!(!symforge_dir.join("index.bin.tmp").exists());
assert!(!stale_unique_tmp.exists());
assert!(
unrelated_similar_name.exists(),
"reset must only remove PID-and-counter temp names"
);
assert!(
symforge_dir.join("frecency.db").exists(),
"reset must preserve unrelated .symforge state"
);
assert!(
source_dir.join("lib.rs").exists(),
"reset must never delete source files"
);
}
use crate::live_index::frecency::{FRECENCY_FLAG_ENV, FrecencyStore};
use std::path::PathBuf;
use std::sync::Mutex as StdMutex;
static FRECENCY_ENV_LOCK: StdMutex<()> = StdMutex::new(());
#[allow(unsafe_code)] fn clear_frecency_flag() {
unsafe { std::env::remove_var(FRECENCY_FLAG_ENV) };
}
fn make_commits(root: &Path, count: usize, base_msg: &str) -> String {
let repo = git2::Repository::open(root).expect("open test repo");
let sig = git2::Signature::now("t", "t@x").expect("sig");
let tree_id = {
let mut idx = repo.index().expect("index");
idx.write_tree().expect("write tree")
};
let tree = repo.find_tree(tree_id).expect("find tree");
let mut head = repo
.head()
.expect("head")
.peel_to_commit()
.expect("peel head");
for i in 0..count {
let oid = git_test_helpers::commit_head_with_retry(
&repo,
&sig,
&sig,
&format!("{base_msg} {i}"),
&tree,
&[&head],
);
head = repo.find_commit(oid).expect("find commit");
}
head.id().to_string()
}
fn copy_tree(src: &Path, dst: &Path) {
std::fs::create_dir_all(dst).expect("create dst");
for entry in std::fs::read_dir(src).expect("read src") {
let entry = entry.expect("dir entry");
let target = dst.join(entry.file_name());
if entry.file_type().expect("file type").is_dir() {
copy_tree(&entry.path(), &target);
} else {
std::fs::copy(entry.path(), &target).expect("copy file");
}
}
}
#[test]
fn portable_import_rebinds_nongit_snapshot_across_roots() {
super::reset_portable_import_guard_for_tests();
let host = TempDir::new().expect("host root");
std::fs::write(host.path().join("lib.rs"), "pub fn baked() {}\n").expect("seed");
let shared = LiveIndex::load(host.path()).expect("host cold load");
export_artifact_legacy(&shared.read(), host.path()).expect("host bake");
let guest = TempDir::new().expect("guest root");
copy_tree(host.path(), guest.path());
let placement = project_local_placement(guest.path());
let snapshot = super::import_portable_snapshot(
guest.path(),
&placement,
super::PortableSnapshotProvenance::HostBakedImageLayer,
)
.expect("portable import must accept the moved bake");
let guest_id = crate::discovery::project_id_for_canonical_root(
&dunce::canonicalize(guest.path()).expect("canonical guest"),
);
assert_eq!(snapshot.project_id, guest_id, "identity rebound to guest");
assert_eq!(snapshot.source_identity.project_id, guest_id);
assert_eq!(snapshot.files.len(), 1);
assert!(
super::import_portable_snapshot(
guest.path(),
&placement,
super::PortableSnapshotProvenance::HostBakedImageLayer,
)
.is_none(),
"second portable import must be refused"
);
}
#[test]
fn portable_import_refuses_git_fingerprint_drift() {
super::reset_portable_import_guard_for_tests();
let host = TempDir::new().expect("host root");
init_repo_with_root_commit(host.path());
std::fs::write(host.path().join("lib.rs"), "pub fn baked() {}\n").expect("seed");
let shared = LiveIndex::load(host.path()).expect("host cold load");
export_artifact_legacy(&shared.read(), host.path()).expect("host bake");
let guest_same = TempDir::new().expect("guest same-history");
copy_tree(host.path(), guest_same.path());
assert!(
super::import_portable_snapshot(
guest_same.path(),
&project_local_placement(guest_same.path()),
super::PortableSnapshotProvenance::HostBakedImageLayer,
)
.is_some(),
"same git history at a new root must import"
);
super::reset_portable_import_guard_for_tests();
let guest_drift = TempDir::new().expect("guest drifted");
copy_tree(host.path(), guest_drift.path());
std::fs::remove_dir_all(guest_drift.path().join(".git")).expect("drop copied history");
{
let repo = git2::Repository::init(guest_drift.path()).expect("drift init");
let sig = git2::Signature::new("t", "t@x", &git2::Time::new(946_684_800, 0))
.expect("fixed-epoch sig");
let tree_id = {
let mut idx = repo.index().expect("index");
idx.write_tree().expect("write tree")
};
let tree = repo.find_tree(tree_id).expect("find tree");
git_test_helpers::commit_head_with_retry(&repo, &sig, &sig, "drifted root", &tree, &[]);
}
assert!(
super::import_portable_snapshot(
guest_drift.path(),
&project_local_placement(guest_drift.path()),
super::PortableSnapshotProvenance::HostBakedImageLayer,
)
.is_none(),
"diverged git history must refuse the bake"
);
super::reset_portable_import_guard_for_tests();
let guest_bare = TempDir::new().expect("guest no-git");
copy_tree(host.path(), guest_bare.path());
std::fs::remove_dir_all(guest_bare.path().join(".git")).expect("drop history");
assert!(
super::import_portable_snapshot(
guest_bare.path(),
&project_local_placement(guest_bare.path()),
super::PortableSnapshotProvenance::HostBakedImageLayer,
)
.is_none(),
"git-fingerprinted bake without a workspace repository must refuse"
);
}
fn init_repo_with_root_commit(root: &Path) -> String {
let repo = git2::Repository::init(root).expect("init");
let sig = git2::Signature::now("t", "t@x").expect("sig");
let tree_id = {
let mut idx = repo.index().expect("index");
idx.write_tree().expect("write tree")
};
let tree = repo.find_tree(tree_id).expect("find tree");
let oid = git_test_helpers::commit_head_with_retry(&repo, &sig, &sig, "root", &tree, &[]);
oid.to_string()
}
#[test]
fn init_frecency_store_is_noop_when_flag_unset() {
let _g = FRECENCY_ENV_LOCK.lock().unwrap();
clear_frecency_flag();
let tmp = TempDir::new().unwrap();
let project_state =
crate::domain::ProjectStateDir::new(tmp.path().join(paths::SYMFORGE_DIR_NAME));
init_frecency_store(tmp.path(), &project_state);
assert!(
!crate::live_index::frecency::frecency_db_path(&project_state).exists(),
"init must not create the frecency database when flag is unset"
);
assert!(
!tmp.path().join(paths::SYMFORGE_DIR_NAME).exists(),
"init must not create the .symforge directory when flag is unset"
);
}
#[test]
fn run_frecency_init_is_noop_when_project_root_is_not_a_repo() {
let tmp = TempDir::new().unwrap();
let db_path = tmp.path().join("frecency.db");
run_frecency_init(&db_path, tmp.path()).expect("init returns Ok on missing repo");
let store = FrecencyStore::open(&db_path).unwrap();
assert_eq!(
store.last_head().unwrap(),
None,
"no HEAD should be recorded when the project root is not a git repo"
);
}
#[test]
fn run_frecency_init_records_head_on_first_session() {
let tmp = TempDir::new().unwrap();
let sha = init_repo_with_root_commit(tmp.path());
let db_path = tmp.path().join("frecency.db");
run_frecency_init(&db_path, tmp.path()).expect("init ok");
let store = FrecencyStore::open(&db_path).unwrap();
assert_eq!(store.last_head().unwrap().as_deref(), Some(sha.as_str()));
}
#[test]
fn run_frecency_init_is_noop_when_head_unchanged() {
let tmp = TempDir::new().unwrap();
let sha = init_repo_with_root_commit(tmp.path());
let db_path = tmp.path().join("frecency.db");
{
let store = FrecencyStore::open(&db_path).unwrap();
store.bump(&[PathBuf::from("src/a.rs")], 0).unwrap();
store.bump(&[PathBuf::from("src/a.rs")], 0).unwrap();
store
.reset_or_halve_on_head_change(None, &sha, None)
.unwrap();
}
run_frecency_init(&db_path, tmp.path()).expect("init ok");
let store = FrecencyStore::open(&db_path).unwrap();
assert_eq!(
store.score(Path::new("src/a.rs"), 0).unwrap(),
2.0,
"same-HEAD init must not reset hit counts"
);
assert_eq!(store.last_head().unwrap().as_deref(), Some(sha.as_str()));
}
#[test]
fn run_frecency_init_halves_at_100_commits() {
let tmp = TempDir::new().unwrap();
let first = init_repo_with_root_commit(tmp.path());
let db_path = tmp.path().join("frecency.db");
{
let store = FrecencyStore::open(&db_path).unwrap();
for _ in 0..10 {
store.bump(&[PathBuf::from("src/a.rs")], 0).unwrap();
}
store
.reset_or_halve_on_head_change(None, &first, None)
.unwrap();
}
let _new_head = make_commits(tmp.path(), 100, "advance");
run_frecency_init(&db_path, tmp.path()).expect("init ok");
let store = FrecencyStore::open(&db_path).unwrap();
assert_eq!(
store.score(Path::new("src/a.rs"), 0).unwrap(),
5.0,
"100 commits falls into the 50..=500 band and must halve"
);
}
#[test]
fn run_frecency_init_zeros_above_500_commits() {
let tmp = TempDir::new().unwrap();
let first = init_repo_with_root_commit(tmp.path());
let db_path = tmp.path().join("frecency.db");
{
let store = FrecencyStore::open(&db_path).unwrap();
for _ in 0..10 {
store.bump(&[PathBuf::from("src/a.rs")], 0).unwrap();
}
store
.reset_or_halve_on_head_change(None, &first, None)
.unwrap();
}
let _new_head = make_commits(tmp.path(), 501, "advance");
run_frecency_init(&db_path, tmp.path()).expect("init ok");
let store = FrecencyStore::open(&db_path).unwrap();
assert_eq!(
store.score(Path::new("src/a.rs"), 0).unwrap(),
0.0,
">500 commits must zero hit counts"
);
}
#[allow(unsafe_code)] #[test]
fn init_frecency_store_with_flag_on_wires_boot_policy() {
let _g = FRECENCY_ENV_LOCK.lock().unwrap();
let tmp = TempDir::new().unwrap();
let sha = init_repo_with_root_commit(tmp.path());
unsafe { std::env::set_var(FRECENCY_FLAG_ENV, "1") };
let project_state =
crate::domain::ProjectStateDir::new(tmp.path().join(paths::SYMFORGE_DIR_NAME));
init_frecency_store(tmp.path(), &project_state);
clear_frecency_flag();
let db_path = crate::live_index::frecency::frecency_db_path(&project_state);
assert!(
db_path.exists(),
"flag=1 init must create the frecency database"
);
let store = FrecencyStore::open(&db_path).unwrap();
assert_eq!(
store.last_head().unwrap().as_deref(),
Some(sha.as_str()),
"flag=1 init must record current HEAD"
);
}
#[test]
fn test_serialize_idempotent() {
let tmp = TempDir::new().unwrap();
let index = make_live_index_with_files(vec![("a.rs", b"fn a() {}")]);
serialize_index(&index, tmp.path()).expect("first serialize should succeed");
serialize_index(&index, tmp.path()).expect("second serialize should succeed");
assert!(tmp.path().join(".symforge").join("index.bin").exists());
assert!(!tmp.path().join(".symforge").join("index.bin.tmp").exists());
}
#[test]
fn team_artifact_export_refuses_non_project_local_or_protected_binding() {
let index = make_live_index_with_files(vec![("src/lib.rs", b"pub fn indexed() {}")]);
let available = CapabilityStatus::Available;
let protected = TempDir::new().unwrap();
let protected_binding =
artifact_binding(protected.path(), SourceAccessMode::ExplicitProtected);
export_artifact(
&index,
&protected_binding.canonical_root,
protected_binding.access_mode,
&project_local_placement(&protected_binding.canonical_root),
&available,
)
.expect_err("protected bindings must refuse team-artifact export");
assert_no_team_artifact_mutation(&protected_binding.canonical_root);
let relocated = TempDir::new().unwrap();
let relocated_binding = artifact_binding(relocated.path(), SourceAccessMode::NormalProject);
let global_state = TempDir::new().unwrap();
let relocated_placement = StatePlacement::UserLocal {
directory: ProjectStateDir::new(global_state.path().join("project-state")),
root_id: relocated_binding.root_id.clone(),
reason: UserLocalPlacementReason::ProjectLocalUnavailable {
safe_reason: AccessErrorKind::PermissionDenied,
},
};
export_artifact(
&index,
&relocated_binding.canonical_root,
relocated_binding.access_mode,
&relocated_placement,
&available,
)
.expect_err("non-project-local bindings must refuse team-artifact export");
assert_no_team_artifact_mutation(&relocated_binding.canonical_root);
assert!(!global_state.path().join("project-state").exists());
let read_only = TempDir::new().unwrap();
let read_only_binding = artifact_binding(read_only.path(), SourceAccessMode::NormalProject);
export_artifact(
&index,
&read_only_binding.canonical_root,
read_only_binding.access_mode,
&project_local_placement(&read_only_binding.canonical_root),
&CapabilityStatus::Unavailable {
reason: CapabilityUnavailableReason::SourceReadOnly,
},
)
.expect_err("source-read-only capability must refuse before mutation");
assert_no_team_artifact_mutation(&read_only_binding.canonical_root);
let tracked = TempDir::new().unwrap();
let tracked_repo = git2::Repository::init(tracked.path()).expect("init tracked repo");
std::fs::create_dir_all(tracked.path().join(".symforge")).unwrap();
std::fs::write(tracked.path().join(".symforge/index.bin.zst"), b"tracked").unwrap();
let mut tracked_index = tracked_repo.index().unwrap();
tracked_index
.add_path(Path::new(".symforge/index.bin.zst"))
.unwrap();
tracked_index.write().unwrap();
let tracked_binding = artifact_binding(tracked.path(), SourceAccessMode::NormalProject);
let tracked_report = export_artifact(
&index,
&tracked_binding.canonical_root,
tracked_binding.access_mode,
&project_local_placement(&tracked_binding.canonical_root),
&available,
)
.expect("tracked export");
assert_eq!(tracked_report.git_visibility.as_str(), "already_tracked");
let visible = TempDir::new().unwrap();
git2::Repository::init(visible.path()).expect("init visible repo");
let visible_binding = artifact_binding(visible.path(), SourceAccessMode::NormalProject);
let visible_report = export_artifact(
&index,
&visible_binding.canonical_root,
visible_binding.access_mode,
&project_local_placement(&visible_binding.canonical_root),
&available,
)
.expect("visible export");
assert_eq!(visible_report.git_visibility.as_str(), "untracked_visible");
let ignored = TempDir::new().unwrap();
git2::Repository::init(ignored.path()).expect("init ignored repo");
std::fs::write(ignored.path().join(".gitignore"), "/.symforge/\n").unwrap();
let ignored_binding = artifact_binding(ignored.path(), SourceAccessMode::NormalProject);
let ignored_report = export_artifact(
&index,
&ignored_binding.canonical_root,
ignored_binding.access_mode,
&project_local_placement(&ignored_binding.canonical_root),
&available,
)
.expect("ignored export");
assert_eq!(
ignored_report.git_visibility.as_str(),
"ignored_force_add_required"
);
let unavailable = TempDir::new().unwrap();
let unavailable_binding =
artifact_binding(unavailable.path(), SourceAccessMode::NormalProject);
let unavailable_report = export_artifact(
&index,
&unavailable_binding.canonical_root,
unavailable_binding.access_mode,
&project_local_placement(&unavailable_binding.canonical_root),
&available,
)
.expect("non-Git export remains available with an honest receipt");
assert_eq!(
unavailable_report.git_visibility.as_str(),
"git_visibility_unavailable"
);
}
#[test]
fn test_export_artifact_writes_metadata_and_gitattributes_hint() {
let tmp = TempDir::new().unwrap();
let index =
make_live_index_with_files(vec![("a.rs", b"fn a() {}"), ("b.rs", b"fn b() {}")]);
let report = export_artifact_legacy(&index, tmp.path()).expect("export should succeed");
assert_eq!(report.files, 2);
assert!(report.path.exists(), "index.bin.zst should exist");
assert!(report.metadata_path.exists(), "artifact.json should exist");
assert_eq!(report.path.file_name().unwrap(), ARTIFACT_FILENAME);
let metadata: serde_json::Value =
serde_json::from_slice(&std::fs::read(&report.metadata_path).unwrap()).unwrap();
assert_eq!(metadata["content_hash"], report.content_hash);
assert_eq!(metadata["files"], 2);
let gitattributes = std::fs::read_to_string(tmp.path().join(".gitattributes")).unwrap();
assert!(
gitattributes
.lines()
.any(|line| line.trim() == "*.zst merge=ours"),
"expected *.zst merge=ours hint, got: {gitattributes:?}"
);
export_artifact_legacy(&index, tmp.path()).expect("second export should succeed");
let gitattributes_again =
std::fs::read_to_string(tmp.path().join(".gitattributes")).unwrap();
assert_eq!(
gitattributes_again.matches("merge=ours").count(),
1,
"repeat export must not duplicate the gitattributes hint"
);
}
#[test]
fn test_artifact_round_trip_is_byte_exact_and_preserves_content_hash() {
let tmp = TempDir::new().unwrap();
let index = make_live_index_with_files(vec![
("src/foo.rs", b"fn foo() { bar(); }"),
("src/bar.py", b"def bar():\n pass\n"),
]);
let (before, raw, compressed) =
build_compressed_snapshot(&index, tmp.path()).expect("build compressed snapshot");
let decompressed = decompress_artifact_bytes(&compressed).expect("decompress");
let after: IndexSnapshot = decode_snapshot(&decompressed).expect("decode postcard");
assert_eq!(
decompressed, raw,
"zstd decompress must reproduce the pre-compression postcard bytes exactly"
);
for (path, before_file) in &before.files {
let after_file = after
.files
.get(path)
.expect("file present after round trip");
assert_eq!(after_file.content_hash, before_file.content_hash);
}
}
#[test]
fn test_load_snapshot_imports_artifact_when_bin_missing() {
let tmp = TempDir::new().unwrap();
let index = make_live_index_with_files(vec![("src/main.rs", b"fn main() {}")]);
export_artifact_legacy(&index, tmp.path()).expect("export should succeed");
assert!(
!tmp.path().join(".symforge").join("index.bin").exists(),
"only the .zst artifact should exist for this scenario"
);
let snapshot = load_snapshot(tmp.path()).expect("load_snapshot should import the artifact");
let file = snapshot
.files
.get("src/main.rs")
.expect("imported snapshot should contain the file");
assert_eq!(file.content_hash, crate::hash::digest_hex(b"fn main() {}"));
}
#[test]
fn same_path_repository_replacement_quarantines_foreign_team_artifact() {
let tmp = TempDir::new().unwrap();
init_repo_with_root_commit(tmp.path());
let index = make_live_index_with_files(vec![("src/main.rs", b"fn original() {}")]);
export_artifact_legacy(&index, tmp.path()).expect("export should succeed");
std::fs::remove_dir_all(tmp.path().join(".git")).unwrap();
let replacement = git2::Repository::init(tmp.path()).expect("replacement init");
let sig = git2::Signature::now("t", "t@x").expect("replacement signature");
let tree_id = {
let mut git_index = replacement.index().expect("replacement index");
git_index.write_tree().expect("replacement tree")
};
let tree = replacement.find_tree(tree_id).expect("replacement tree");
git_test_helpers::commit_head_with_retry(
&replacement,
&sig,
&sig,
"foreign-root",
&tree,
&[],
);
assert!(
load_snapshot(tmp.path()).is_none(),
"foreign team artifacts must never hydrate a same-path replacement"
);
let artifact_path = tmp.path().join(".symforge").join(ARTIFACT_FILENAME);
assert!(
!artifact_path.exists(),
"foreign team artifact must leave the active import path"
);
let quarantined: Vec<_> =
std::fs::read_dir(paths::resolve_artifact_quarantine_dir(tmp.path()))
.expect("foreign artifact quarantine must exist")
.filter_map(|entry| entry.ok())
.filter(|entry| {
entry.path().extension().and_then(|ext| ext.to_str()) == Some("zst")
})
.collect();
assert_eq!(quarantined.len(), 1);
}
#[test]
fn test_load_snapshot_quarantines_corrupt_artifact_and_returns_none() {
let tmp = TempDir::new().unwrap();
let index = make_live_index_with_files(vec![("src/main.rs", b"fn main() {}")]);
export_artifact_legacy(&index, tmp.path()).expect("export should succeed");
let artifact_path = tmp.path().join(".symforge").join(ARTIFACT_FILENAME);
let good = std::fs::read(&artifact_path).unwrap();
std::fs::write(&artifact_path, &good[..good.len() / 2]).unwrap();
let result = load_snapshot(tmp.path());
assert!(
result.is_none(),
"corrupt artifact must fall back to a full re-index, not partial-serve"
);
assert!(
!artifact_path.exists(),
"corrupt artifact should be removed from the active path after quarantine"
);
let quarantine_dir = paths::resolve_artifact_quarantine_dir(tmp.path());
let quarantined: Vec<_> = std::fs::read_dir(&quarantine_dir)
.expect("quarantine dir should exist")
.filter_map(|e| e.ok())
.filter(|e| e.path().extension().and_then(|ext| ext.to_str()) == Some("zst"))
.collect();
assert_eq!(
quarantined.len(),
1,
"corrupt artifact should be quarantined under .symforge/quarantine/artifacts/"
);
}
#[test]
fn artifact_checksum_and_prior_format_are_refused_with_valid_sidecar() {
for prior_format in [false, true] {
let tmp = TempDir::new().unwrap();
let index = make_live_index_with_files(vec![("main.rs", b"fn my_func() {}")]);
let report = export_artifact_legacy(&index, tmp.path()).unwrap();
let compressed = std::fs::read(&report.path).unwrap();
let mut raw = decompress_artifact_bytes(&compressed).unwrap();
if prior_format {
let mut snapshot = decode_snapshot(&raw).unwrap();
snapshot.version = 10;
raw = postcard::to_stdvec(&snapshot).unwrap();
} else {
*raw.last_mut().unwrap() ^= 1;
}
let corrupt = zstd::encode_all(raw.as_slice(), ARTIFACT_BEST_ZSTD_LEVEL).unwrap();
std::fs::write(&report.path, &corrupt).unwrap();
let mut metadata: serde_json::Value =
serde_json::from_slice(&std::fs::read(&report.metadata_path).unwrap()).unwrap();
metadata["content_hash"] = crate::hash::digest_hex(&raw).into();
std::fs::write(
&report.metadata_path,
serde_json::to_vec(&metadata).unwrap(),
)
.unwrap();
assert!(load_snapshot(tmp.path()).is_none());
assert!(!report.path.exists());
assert!(!tmp.path().join(".symforge").join(INDEX_FILENAME).exists());
let quarantine = paths::resolve_artifact_quarantine_dir(tmp.path());
let copies: Vec<_> = std::fs::read_dir(quarantine)
.unwrap()
.map(|entry| entry.unwrap().path())
.filter(|path| path.extension().and_then(|ext| ext.to_str()) == Some("zst"))
.collect();
assert_eq!(copies.len(), 1);
assert_eq!(std::fs::read(&copies[0]).unwrap(), corrupt);
}
}
#[test]
fn test_load_snapshot_quarantines_artifact_with_missing_sidecar() {
let tmp = TempDir::new().unwrap();
let index = make_live_index_with_files(vec![("src/main.rs", b"fn main() {}")]);
export_artifact_legacy(&index, tmp.path()).expect("export should succeed");
let artifact_path = tmp.path().join(".symforge").join(ARTIFACT_FILENAME);
let metadata_path = tmp
.path()
.join(".symforge")
.join(ARTIFACT_METADATA_FILENAME);
std::fs::remove_file(&metadata_path).expect("remove sidecar");
assert!(
artifact_path.exists(),
"artifact bytes remain valid — only the sidecar is gone"
);
let result = load_snapshot(tmp.path());
assert!(
result.is_none(),
"a valid artifact with a missing sidecar must NOT be silently trusted; \
content_hash is unverifiable, so import must quarantine and fall back"
);
assert!(
!artifact_path.exists(),
"unverifiable artifact should be removed from the active path after quarantine"
);
let quarantine_dir = paths::resolve_artifact_quarantine_dir(tmp.path());
let quarantined: Vec<_> = std::fs::read_dir(&quarantine_dir)
.expect("quarantine dir should exist")
.filter_map(|e| e.ok())
.filter(|e| e.path().extension().and_then(|ext| ext.to_str()) == Some("zst"))
.collect();
assert_eq!(
quarantined.len(),
1,
"missing-sidecar artifact should be quarantined under .symforge/quarantine/artifacts/"
);
let quarantine_json: Vec<_> = std::fs::read_dir(&quarantine_dir)
.expect("quarantine dir should exist")
.filter_map(|e| e.ok())
.filter(|e| e.path().extension().and_then(|ext| ext.to_str()) == Some("json"))
.collect();
assert_eq!(quarantine_json.len(), 1);
let metadata: serde_json::Value =
serde_json::from_slice(&std::fs::read(quarantine_json[0].path()).unwrap()).unwrap();
assert_eq!(
metadata["reason"], "missing-sidecar",
"quarantine metadata must record the missing-sidecar integrity failure"
);
}
}