fix: use atomic write-then-rename for state files

.changes/unreleased/library-Fixed-20260413-112959.yaml

@@ -0,0 +1,7 @@
+component: library
+kind: Fixed
+body: |-
+    Use atomic write-then-rename for state files to prevent corruption
+
+    State file writes previously used a non-atomic truncate-then-write pattern, which could leave corrupted or empty files if the process was interrupted mid-write. State files are now written to a temporary file in the same directory and atomically renamed into place using tempfile::NamedTempFile.
+time: 2026-04-13T11:29:59.721696000-07:00

Cargo.toml

@@ -64,12 +64,12 @@ similar = "2.7.0"
 indicatif = "0.18.4"
 ctrlc = "3.5.2"
 glob = "0.3.3"
+tempfile = "3"
 
 [build-dependencies]
 vergen = { version = "9", features = ["build"] }
 
 [dev-dependencies]
-tempfile = "3"
 assert_cmd = "2.2"
 insta = "1"
 predicates = "3"

src/state.rs

@@ -11,7 +11,9 @@ use serde::{Deserialize, Serialize};
 use std::collections::hash_map::DefaultHasher;
 use std::fs;
 use std::hash::{Hash, Hasher};
+use std::io::Write;
 use std::path::{Path, PathBuf};
+use tempfile::NamedTempFile;
 
 use crate::overlay_name::OverlayName;
 
@@ -557,6 +559,22 @@ pub(crate) fn external_state_dir_for_target(target: &Path) -> Result<PathBuf> {
     Ok(base.join(target_hash))
 }
 
+/// Write content to a file atomically using write-then-rename.
+///
+/// Creates a temporary file in the same directory as the target path,
+/// writes the content, then atomically renames it into place. This
+/// prevents corruption if the process is interrupted mid-write.
+fn atomic_write(path: &Path, content: &str) -> Result<()> {
+    let dir = path
+        .parent()
+        .context("State file has no parent directory")?;
+    let mut tmp = NamedTempFile::new_in(dir)?;
+    tmp.write_all(content.as_bytes())?;
+    tmp.persist(path)
+        .context("Failed to atomically persist state file")?;
+    Ok(())
+}
+
 /// Save overlay state to the external backup location.
 pub(crate) fn save_external_state(
     target: &Path,
@@ -575,7 +593,7 @@ pub(crate) fn save_external_state(
 
     let state_file = dir.join(format!("{overlay_name}.ccl"));
     let content = sickle::to_string(state).context("Failed to serialize state to CCL")?;
-    fs::write(&state_file, content)?;
+    atomic_write(&state_file, &content)?;
 
     Ok(())
 }
@@ -597,7 +615,7 @@ pub(crate) fn remove_external_state(target: &Path, overlay_name: &str) -> Result
                 state.removed_at = Some(Utc::now());
                 let updated_content =
                     sickle::to_string(&state).context("Failed to serialize state")?;
-                fs::write(&state_file, updated_content)?;
+                atomic_write(&state_file, &updated_content)?;
             }
             Err(e) => {
                 warn!(
@@ -791,7 +809,7 @@ pub(crate) fn save_overlay_state(target: &Path, state: &OverlayState) -> Result<
     let state_file = overlays_dir.join(format!("{normalized_name}.ccl"));
 
     let content = sickle::to_string(state).context("Failed to serialize overlay state")?;
-    fs::write(&state_file, content)?;
+    atomic_write(&state_file, &content)?;
 
     Ok(())
 }