2 files changed, 128 insertions, 0 deletions
diff --git a/internal/persistence/atomic.go b/internal/persistence/atomic.go
new file mode 100644
index 0000000..a3cc06a
--- /dev/null
+++ b/internal/persistence/atomic.go
@@ -0,0 +1,53 @@
+// Package persistence provides crash-resistant single-file replacement.
+// It does not serialize callers or make multi-file operations transactional.
+package persistence
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+)
+
+// WriteFile writes and syncs a temporary file in the destination directory,
+// atomically renames it over path, then syncs the directory. Existing file
+// permissions are preserved; perm is used for new files. Callers must own the
+// data being serialized and coordinate competing read-modify-write operations.
+// A directory-sync error means replacement occurred but durability is uncertain.
+func WriteFile(path string, data []byte, perm os.FileMode) error {
+	if info, err := os.Stat(path); err == nil {
+		perm = info.Mode().Perm()
+	} else if !os.IsNotExist(err) {
+		return err
+	}
+	dir := filepath.Dir(path)
+	f, err := os.CreateTemp(dir, ".save-*")
+	if err != nil {
+		return err
+	}
+	defer os.Remove(f.Name())
+	defer f.Close()
+	if _, err := f.Write(data); err != nil {
+		return err
+	}
+	if err := f.Chmod(perm); err != nil {
+		return err
+	}
+	if err := f.Sync(); err != nil {
+		return err
+	}
+	if err := f.Close(); err != nil {
+		return err
+	}
+	if err := os.Rename(f.Name(), path); err != nil {
+		return err
+	}
+	d, err := os.Open(dir)
+	if err != nil {
+		return fmt.Errorf("replacement completed; open directory for sync: %w", err)
+	}
+	defer d.Close()
+	if err := d.Sync(); err != nil {
+		return fmt.Errorf("replacement completed; sync directory: %w", err)
+	}
+	return nil
+}
diff --git a/internal/persistence/atomic_test.go b/internal/persistence/atomic_test.go
new file mode 100644
index 0000000..05710f1
--- /dev/null
+++ b/internal/persistence/atomic_test.go
@@ -0,0 +1,75 @@
+package persistence
+
+import (
+	"bytes"
+	"os"
+	"path/filepath"
+	"sync"
+	"testing"
+)
+
+func TestWriteFileReplacesAndPreservesPermissions(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "save.yaml")
+	if err := WriteFile(path, []byte("old"), 0600); err != nil {
+		t.Fatal(err)
+	}
+	if err := WriteFile(path, []byte("new"), 0644); err != nil {
+		t.Fatal(err)
+	}
+	got, err := os.ReadFile(path)
+	if err != nil || string(got) != "new" {
+		t.Fatalf("read: %q, %v", got, err)
+	}
+	info, err := os.Stat(path)
+	if err != nil || info.Mode().Perm() != 0600 {
+		t.Fatalf("permissions: %v, %v", info, err)
+	}
+	entries, err := os.ReadDir(filepath.Dir(path))
+	if err != nil || len(entries) != 1 {
+		t.Fatalf("temporary files left behind: %v, %v", entries, err)
+	}
+}
+
+func TestFailedRenameCleansTempFile(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "destination")
+	if err := os.Mkdir(path, 0755); err != nil {
+		t.Fatal(err)
+	}
+	if err := WriteFile(path, []byte("new"), 0600); err == nil {
+		t.Fatal("expected rename over directory to fail")
+	}
+	entries, err := os.ReadDir(dir)
+	if err != nil || len(entries) != 1 || !entries[0].IsDir() {
+		t.Fatalf("destination damaged or temporary file leaked: %v, %v", entries, err)
+	}
+}
+
+func TestReadersSeeOnlyCompleteSaves(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "save.yaml")
+	a, b := bytes.Repeat([]byte("a"), 8192), bytes.Repeat([]byte("b"), 16384)
+	if err := WriteFile(path, a, 0600); err != nil {
+		t.Fatal(err)
+	}
+	var wg sync.WaitGroup
+	for _, data := range [][]byte{a, b} {
+		wg.Add(1)
+		go func(data []byte) {
+			defer wg.Done()
+			for i := 0; i < 30; i++ {
+				if err := WriteFile(path, data, 0600); err != nil {
+					t.Error(err)
+					return
+				}
+			}
+		}(data)
+	}
+	for i := 0; i < 300; i++ {
+		got, err := os.ReadFile(path)
+		if err != nil || (!bytes.Equal(got, a) && !bytes.Equal(got, b)) {
+			t.Errorf("reader saw partial or missing save: length=%d, err=%v", len(got), err)
+			break
+		}
+	}
+	wg.Wait()
+}