Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

fix(restore): accept the GNU-sparse SQLite entry that backup produces (#718)

AkitaOnRails80743a42eb8f
diff --git a/CHANGELOG.md b/CHANGELOG.md
index bc93e329..c720bd9f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -25,6 +25,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
a missed window now spools instead of dropping (above). The handoff GET keeps
its 1 s: it is fed synchronously to the agent's context, and truncating an
almost-ready handoff costs more than it saves (#719).
+- `ai-memory restore` no longer rejects the GNU-sparse SQLite entry that
+ `ai-memory backup` itself produces. `tar::Builder`'s default sparse
+ detection archives `db/memory.sqlite` as a GNU-sparse entry (header type
+ `S`) whenever the SQLite snapshot has real holes on disk, which
+ `validate_restore_entry`'s `is_file()`/`is_dir()` check rejected as an
+ "unsupported entry type" — a verified, valid backup could not be restored,
+ with no recovery path but hand-editing the archive. `tar` already expands
+ GNU-sparse blocks to their full logical content while iterating entries, so
+ restore now accepts the type and unpacks it exactly like a regular file
+ (#718).
## [2.2.0] - 2026-09-12
diff --git a/crates/ai-memory-cli/src/commands/restore.rs b/crates/ai-memory-cli/src/commands/restore.rs
index 4f3b04a9..0aecf1f2 100644
--- a/crates/ai-memory-cli/src/commands/restore.rs
+++ b/crates/ai-memory-cli/src/commands/restore.rs
@@ -97,6 +97,17 @@ fn unpack_checked_archive<R: std::io::Read>(
Ok(())
}
+/// The backup writes `db/memory.sqlite` via `tar::Builder`'s default sparse
+/// detection: on a sparse SQLite snapshot the entry type is GNU-sparse
+/// (header byte `S`), not plain `Regular` — `tar::EntryType::is_file()` is
+/// `false` for it even though it is a hole-encoded regular file. `tar`
+/// already expands the sparse blocks to their full logical content while
+/// iterating entries (see `Archive::parse_sparse_header`), so `unpack_in`
+/// on such an entry writes byte-identical content to a non-sparse one.
+fn is_regular_file(entry_type: tar::EntryType) -> bool {
+ entry_type.is_file() || entry_type == tar::EntryType::GNUSparse
+}
+
fn validate_restore_entry(path: &Path, entry_type: tar::EntryType) -> Result<()> {
if !path.components().all(|c| matches!(c, Component::Normal(_))) {
bail!("backup contains unsafe path: {}", path.display());
@@ -104,7 +115,7 @@ fn validate_restore_entry(path: &Path, entry_type: tar::EntryType) -> Result<()>
if entry_type.is_symlink() || entry_type.is_hard_link() {
bail!("backup contains unsupported link entry: {}", path.display());
}
- if !(entry_type.is_file() || entry_type.is_dir()) {
+ if !(is_regular_file(entry_type) || entry_type.is_dir()) {
bail!("backup contains unsupported entry type: {}", path.display());
}
let path_str = path.to_string_lossy();
@@ -191,6 +202,22 @@ mod tests {
}
}
+ #[test]
+ fn validate_restore_entry_accepts_gnu_sparse_for_the_sqlite_path() {
+ validate_restore_entry(Path::new("db/memory.sqlite"), tar::EntryType::GNUSparse)
+ .expect("a GNU-sparse db/memory.sqlite entry is a regular file, just hole-encoded");
+ }
+
+ #[test]
+ fn validate_restore_entry_still_rejects_gnu_sparse_at_an_unexpected_path() {
+ let err =
+ validate_restore_entry(Path::new("secret.txt"), tar::EntryType::GNUSparse).unwrap_err();
+ assert!(
+ err.to_string().contains("unexpected path"),
+ "unexpected error: {err}"
+ );
+ }
+
#[test]
fn restore_rejects_unexpected_or_unsafe_paths() {
for path in ["../config.toml", "/tmp/x"] {
@@ -211,4 +238,118 @@ mod tests {
"unexpected error for {path}: {err}"
);
}
+
+ fn sha256_hex(bytes: &[u8]) -> String {
+ use sha2::{Digest, Sha256};
+ let mut hasher = Sha256::new();
+ hasher.update(bytes);
+ format!("{:x}", hasher.finalize())
+ }
+
+ /// Whether the `tar` on PATH is GNU tar with sparse support, so the
+ /// real-fixture test below can be skipped everywhere else (musl/BSD
+ /// `tar`, or no `tar` at all) without breaking those environments.
+ fn gnu_tar_with_sparse_available() -> bool {
+ std::process::Command::new("tar")
+ .arg("--version")
+ .output()
+ .is_ok_and(|out| String::from_utf8_lossy(&out.stdout).contains("GNU tar"))
+ }
+
+ /// Reproduces #718: the backup command's `tar::Builder` (default
+ /// `sparse: true`) writes `db/memory.sqlite` as a GNU-sparse entry
+ /// whenever the SQLite snapshot has real holes on disk. This builds an
+ /// actual sparse file, archives it with real GNU tar (never a hand-built
+ /// header — that would prove nothing about whether unpacking works), and
+ /// asserts the restored file is byte-identical to the original logical
+ /// content.
+ #[cfg(target_os = "linux")]
+ #[test]
+ fn restore_round_trips_a_real_gnu_sparse_sqlite_snapshot() {
+ if !gnu_tar_with_sparse_available() {
+ eprintln!(
+ "skipping restore_round_trips_a_real_gnu_sparse_sqlite_snapshot: \
+ GNU tar with --sparse not available on PATH"
+ );
+ return;
+ }
+
+ use std::io::{Seek, SeekFrom, Write};
+
+ let src = tempfile::TempDir::new().unwrap();
+ std::fs::create_dir_all(src.path().join("wiki/default/project/notes")).unwrap();
+ std::fs::write(src.path().join("wiki/default/project/notes/a.md"), b"body").unwrap();
+ std::fs::write(src.path().join("config.toml"), b"# cfg\n").unwrap();
+ std::fs::create_dir_all(src.path().join("db")).unwrap();
+ let sqlite_path = src.path().join("db/memory.sqlite");
+ {
+ let mut f = std::fs::File::create(&sqlite_path).unwrap();
+ f.write_all(&[0xAB; 8192]).unwrap();
+ // Seek far past the last write without writing the gap: on a
+ // filesystem that supports holes (tmpfs, ext4, xfs, btrfs) this
+ // leaves a real hole rather than allocated zero pages.
+ f.seek(SeekFrom::Start(8 * 1024 * 1024)).unwrap();
+ f.write_all(&[0xCD; 8192]).unwrap();
+ }
+ let expected_hash = sha256_hex(&std::fs::read(&sqlite_path).unwrap());
+
+ let archive_dir = tempfile::TempDir::new().unwrap();
+ let archive_path = archive_dir.path().join("backup.tar.gz");
+ let status = std::process::Command::new("tar")
+ .arg("--sparse")
+ .arg("-czf")
+ .arg(&archive_path)
+ .arg("-C")
+ .arg(src.path())
+ .arg("config.toml")
+ .arg("wiki")
+ .arg("db/memory.sqlite")
+ .status()
+ .unwrap();
+ assert!(
+ status.success(),
+ "GNU tar failed to build the fixture archive"
+ );
+
+ // Confirm the fixture actually reproduces the bug before trusting the
+ // restore result: db/memory.sqlite must be a GNU-sparse entry, not a
+ // plain regular file (which would exercise nothing new).
+ {
+ let file = std::fs::File::open(&archive_path).unwrap();
+ let dec = GzDecoder::new(file);
+ let mut ar = tar::Archive::new(dec);
+ let mut found_sparse = false;
+ for entry in ar.entries().unwrap() {
+ let entry = entry.unwrap();
+ if entry.path().unwrap().as_ref() == Path::new("db/memory.sqlite") {
+ found_sparse = entry.header().entry_type() == tar::EntryType::GNUSparse;
+ }
+ }
+ assert!(
+ found_sparse,
+ "fixture archive did not encode db/memory.sqlite as GNU-sparse; \
+ test does not exercise #718"
+ );
+ }
+
+ let restore_dir = tempfile::TempDir::new().unwrap();
+ let file = std::fs::File::open(&archive_path).unwrap();
+ let dec = GzDecoder::new(file);
+ let mut ar = tar::Archive::new(dec);
+ unpack_checked_archive(&mut ar, restore_dir.path()).unwrap();
+
+ let restored = std::fs::read(restore_dir.path().join("db/memory.sqlite")).unwrap();
+ assert_eq!(
+ sha256_hex(&restored),
+ expected_hash,
+ "restored SQLite content must byte-match the original logical content"
+ );
+ assert!(restore_dir.path().join("config.toml").is_file());
+ assert!(
+ restore_dir
+ .path()
+ .join("wiki/default/project/notes/a.md")
+ .is_file()
+ );
+ }
}