use std::collections::{HashMap, HashSet};
use std::path::PathBuf;
use std::sync::{Arc, Mutex};
use async_trait::async_trait;
use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};
use crate::error::{Result, RustyError};
use crate::record::{CheckpointHeader, JournalRef};
use crate::state::State;
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Checkpoint {
pub id: String,
pub thread_id: String,
pub step: usize,
pub state: State,
pub next_nodes: Vec<String>,
pub created_at: DateTime<Utc>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub base: Option<String>,
#[serde(default)]
pub header: CheckpointHeader,
#[serde(default)]
pub journal_ref: Option<JournalRef>,
}
impl Checkpoint {
pub fn new(
thread_id: impl Into<String>,
step: usize,
state: State,
next_nodes: Vec<String>,
) -> Self {
Self {
id: uuid::Uuid::new_v4().to_string(),
thread_id: thread_id.into(),
step,
state,
next_nodes,
created_at: Utc::now(),
header: CheckpointHeader::default(),
journal_ref: None,
base: None,
}
}
}
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct DeltaPolicy {
pub max_chain_len: usize,
pub max_byte_ratio: f64,
}
impl Default for DeltaPolicy {
fn default() -> Self {
Self {
max_chain_len: 32,
max_byte_ratio: 0.8,
}
}
}
impl DeltaPolicy {
pub fn full_only() -> Self {
Self {
max_chain_len: 0,
max_byte_ratio: 0.0,
}
}
fn deltas_enabled(&self) -> bool {
self.max_chain_len > 0
}
}
#[derive(Debug, Clone)]
pub struct DeltaHead {
pub checkpoint: Checkpoint,
pub chain_len: usize,
}
#[derive(Debug, Clone)]
pub struct DeltaEncoding {
pub checkpoint: Checkpoint,
pub chain_len: usize,
}
impl DeltaEncoding {
pub(crate) fn full(checkpoint: &Checkpoint) -> Self {
Self {
checkpoint: Checkpoint {
base: None,
..checkpoint.clone()
},
chain_len: 0,
}
}
}
fn state_bytes(state: &State) -> usize {
serde_json::to_vec(state)
.expect("a State always serializes")
.len()
}
pub fn encode_delta(
checkpoint: &Checkpoint,
head: Option<&DeltaHead>,
policy: &DeltaPolicy,
) -> DeltaEncoding {
let Some(head) = head.filter(|_| policy.deltas_enabled()) else {
return DeltaEncoding::full(checkpoint);
};
if head.chain_len >= policy.max_chain_len {
return DeltaEncoding::full(checkpoint);
}
let delta = State::from_shared_channels(
checkpoint
.state
.channels_changed_since(&head.checkpoint.state),
);
let delta_bytes = state_bytes(&delta);
let full_bytes = state_bytes(&checkpoint.state);
if (delta_bytes as f64) >= policy.max_byte_ratio * (full_bytes as f64) {
return DeltaEncoding::full(checkpoint);
}
DeltaEncoding {
checkpoint: Checkpoint {
base: Some(head.checkpoint.id.clone()),
state: delta,
..checkpoint.clone()
},
chain_len: head.chain_len + 1,
}
}
pub fn fold_delta(base: &Checkpoint, delta: &Checkpoint) -> Checkpoint {
let mut state = base.state.clone();
for (channel, value) in delta.state.shared_channels() {
state.insert_shared(channel.to_owned(), value.clone());
}
Checkpoint {
id: delta.id.clone(),
thread_id: delta.thread_id.clone(),
step: delta.step,
state,
next_nodes: delta.next_nodes.clone(),
created_at: delta.created_at,
header: delta.header.clone(),
journal_ref: delta.journal_ref.clone(),
base: None,
}
}
pub fn fold_chain(chain: &[Checkpoint]) -> Result<Checkpoint> {
let Some((root, links)) = chain.split_first() else {
return Err(RustyError::Checkpoint(
"cannot fold an empty checkpoint chain".into(),
));
};
if let Some(base) = &root.base {
return Err(RustyError::Checkpoint(format!(
"checkpoint chain root `{}` is itself a delta against `{base}`; \
the chain is broken",
root.id
)));
}
let mut tip = root.clone();
for link in links {
if link.base.as_deref() != Some(tip.id.as_str()) {
return Err(RustyError::Checkpoint(format!(
"checkpoint `{}` claims base `{:?}` but follows `{}`; the chain is broken",
link.id, link.base, tip.id
)));
}
tip = fold_delta(&tip, link);
}
Ok(tip)
}
pub(crate) fn materialize_all(raw: Vec<Checkpoint>) -> Vec<Checkpoint> {
let by_id: HashMap<String, Checkpoint> = raw.into_iter().map(|c| (c.id.clone(), c)).collect();
let mut memo: HashMap<String, Checkpoint> = HashMap::new();
let mut out = Vec::with_capacity(by_id.len());
'starts: for start_id in by_id.keys() {
if let Some(materialized) = memo.get(start_id) {
out.push(materialized.clone());
continue;
}
let mut links: Vec<&Checkpoint> = Vec::new();
let mut visiting: HashSet<&str> = HashSet::new();
let mut cursor = by_id.get(start_id);
let mut folded: Option<Checkpoint> = None;
while let Some(current) = cursor {
if !visiting.insert(current.id.as_str()) {
tracing::warn!(
checkpoint_id = %start_id,
"checkpoint delta chain has a cycle; skipping"
);
continue 'starts;
}
if let Some(materialized) = memo.get(¤t.id) {
folded = Some(materialized.clone());
break;
}
match ¤t.base {
None => {
folded = Some(current.clone());
break;
}
Some(base_id) => {
links.push(current);
match by_id.get(base_id) {
Some(base) => cursor = Some(base),
None => {
tracing::warn!(
checkpoint_id = %current.id,
base = %base_id,
"checkpoint delta base is missing; skipping chain"
);
continue 'starts;
}
}
}
}
}
let Some(mut tip) = folded else {
continue;
};
for link in links.iter().rev() {
tip = fold_delta(&tip, link);
memo.insert(link.id.clone(), tip.clone());
}
out.push(tip);
}
out
}
#[async_trait]
pub trait Checkpointer: Send + Sync {
async fn put(&self, checkpoint: Checkpoint) -> Result<()>;
async fn get_latest(&self, thread_id: &str) -> Result<Option<Checkpoint>>;
async fn list(&self, thread_id: &str) -> Result<Vec<Checkpoint>>;
async fn get_by_id(&self, thread_id: &str, checkpoint_id: &str) -> Result<Option<Checkpoint>> {
let all = self.list(thread_id).await?;
Ok(all.into_iter().find(|c| c.id == checkpoint_id))
}
async fn fork_thread(
&self,
src_thread: &str,
dst_thread: &str,
at_checkpoint_id: Option<&str>,
) -> Result<usize> {
if src_thread == dst_thread {
return Err(RustyError::Checkpoint(format!(
"cannot fork thread `{src_thread}` onto itself: checkpoint ids would collide"
)));
}
let all = self.list(src_thread).await?;
if all.is_empty() {
return Err(RustyError::Checkpoint(format!(
"cannot fork thread `{src_thread}`: no checkpoints found"
)));
}
let selected: Vec<Checkpoint> = match at_checkpoint_id {
None => all,
Some(id) => {
let pos = all.iter().position(|c| c.id == id).ok_or_else(|| {
RustyError::Checkpoint(format!(
"cannot fork thread `{src_thread}`: unknown checkpoint id `{id}`"
))
})?;
all[..=pos].to_vec()
}
};
let copied = selected.len();
for mut checkpoint in selected {
checkpoint.thread_id = dst_thread.to_string();
self.put(checkpoint).await?;
}
tracing::info!(
src_thread = %src_thread,
dst_thread = %dst_thread,
copied = copied,
"thread history forked"
);
Ok(copied)
}
}
#[derive(Debug, Default, Clone)]
pub struct InMemoryCheckpointer {
inner: Arc<Mutex<HashMap<String, Vec<Checkpoint>>>>,
}
impl InMemoryCheckpointer {
pub fn new() -> Self {
Self::default()
}
fn lock(&self) -> Result<std::sync::MutexGuard<'_, HashMap<String, Vec<Checkpoint>>>> {
self.inner
.lock()
.map_err(|_| RustyError::Checkpoint("in-memory checkpointer lock poisoned".into()))
}
}
#[async_trait]
impl Checkpointer for InMemoryCheckpointer {
async fn put(&self, checkpoint: Checkpoint) -> Result<()> {
let mut guard = self.lock()?;
let entry = guard.entry(checkpoint.thread_id.clone()).or_default();
if entry.iter().any(|c| c.id == checkpoint.id) {
return Err(RustyError::Checkpoint(format!(
"checkpoint id `{}` already exists for thread `{}`",
checkpoint.id, checkpoint.thread_id
)));
}
tracing::debug!(
thread_id = %checkpoint.thread_id,
checkpoint_id = %checkpoint.id,
step = checkpoint.step,
"checkpoint stored (in-memory)"
);
entry.push(checkpoint);
Ok(())
}
async fn get_latest(&self, thread_id: &str) -> Result<Option<Checkpoint>> {
let guard = self.lock()?;
Ok(guard.get(thread_id).and_then(|v| v.last()).cloned())
}
async fn list(&self, thread_id: &str) -> Result<Vec<Checkpoint>> {
let guard = self.lock()?;
let mut all = guard.get(thread_id).cloned().unwrap_or_default();
all.sort_by(|a, b| {
a.step
.cmp(&b.step)
.then(a.created_at.cmp(&b.created_at))
.then(a.id.cmp(&b.id))
});
Ok(all)
}
}
#[derive(Debug, Clone)]
pub struct JsonFileCheckpointer {
dir: PathBuf,
put_locks: Arc<Mutex<HashMap<String, Arc<tokio::sync::Mutex<()>>>>>,
heads: Arc<Mutex<HashMap<String, DeltaHead>>>,
policy: DeltaPolicy,
}
impl JsonFileCheckpointer {
pub fn new(dir: impl Into<PathBuf>) -> Self {
Self::with_delta_policy(dir, DeltaPolicy::default())
}
pub fn with_delta_policy(dir: impl Into<PathBuf>, policy: DeltaPolicy) -> Self {
Self {
dir: dir.into(),
put_locks: Arc::new(Mutex::new(HashMap::new())),
heads: Arc::new(Mutex::new(HashMap::new())),
policy,
}
}
pub fn delta_policy(&self) -> DeltaPolicy {
self.policy
}
pub fn dir(&self) -> &std::path::Path {
&self.dir
}
fn put_lock(&self, thread_id: &str) -> Result<Arc<tokio::sync::Mutex<()>>> {
let mut map = self
.put_locks
.lock()
.map_err(|_| RustyError::Checkpoint("put-lock map poisoned".into()))?;
Ok(map
.entry(thread_id.to_owned())
.or_insert_with(|| Arc::new(tokio::sync::Mutex::new(())))
.clone())
}
fn thread_dir(&self, thread_id: &str) -> PathBuf {
self.dir.join(thread_id)
}
fn checkpoint_path(&self, thread_id: &str, checkpoint_id: &str) -> PathBuf {
self.thread_dir(thread_id)
.join(format!("{checkpoint_id}.json"))
}
fn latest_path(&self, thread_id: &str) -> PathBuf {
self.thread_dir(thread_id).join("latest")
}
pub(crate) async fn atomic_write(path: &PathBuf, bytes: &[u8]) -> Result<()> {
let tmp = path.with_file_name(format!(
".{}.tmp-{}",
path.file_name()
.map(|n| n.to_string_lossy().into_owned())
.unwrap_or_else(|| "checkpoint".into()),
uuid::Uuid::new_v4()
));
if let Err(e) = tokio::fs::write(&tmp, bytes).await {
let _ = tokio::fs::remove_file(&tmp).await;
return Err(RustyError::Checkpoint(format!(
"failed to write temp file `{}`: {e}",
tmp.display()
)));
}
if let Err(e) = tokio::fs::rename(&tmp, path).await {
let _ = tokio::fs::remove_file(&tmp).await;
return Err(RustyError::Checkpoint(format!(
"failed to rename `{}` -> `{}`: {e}",
tmp.display(),
path.display()
)));
}
Ok(())
}
async fn read_checkpoint(path: &PathBuf) -> Result<Checkpoint> {
let bytes = tokio::fs::read(path).await.map_err(|e| {
RustyError::Checkpoint(format!(
"failed to read checkpoint file `{}`: {e}",
path.display()
))
})?;
serde_json::from_slice(&bytes).map_err(|e| {
RustyError::Checkpoint(format!("corrupt checkpoint file `{}`: {e}", path.display()))
})
}
async fn scan_thread_raw(&self, thread_id: &str) -> Result<Vec<Checkpoint>> {
let dir = self.thread_dir(thread_id);
let mut entries = match tokio::fs::read_dir(&dir).await {
Ok(entries) => entries,
Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(Vec::new()),
Err(e) => {
return Err(RustyError::Checkpoint(format!(
"failed to read thread directory `{}`: {e}",
dir.display()
)))
}
};
let mut checkpoints = Vec::new();
loop {
let entry = match entries.next_entry().await {
Ok(Some(entry)) => entry,
Ok(None) => break,
Err(e) => {
return Err(RustyError::Checkpoint(format!(
"failed to iterate thread directory `{}`: {e}",
dir.display()
)))
}
};
let path = entry.path();
let is_json = path.extension().is_some_and(|ext| ext == "json");
if !is_json {
continue;
}
match Self::read_checkpoint(&path).await {
Ok(cp) => checkpoints.push(cp),
Err(e) => {
tracing::warn!(
thread_id = %thread_id,
path = %path.display(),
error = %e,
"skipping corrupt checkpoint file during scan"
);
continue;
}
}
}
Ok(checkpoints)
}
async fn read_latest_raw(&self, thread_id: &str) -> Result<Option<Checkpoint>> {
let latest_path = self.latest_path(thread_id);
if let Ok(id_bytes) = tokio::fs::read(&latest_path).await {
if let Ok(id) = std::str::from_utf8(&id_bytes) {
let id = id.trim();
if !id.is_empty() {
let path = self.checkpoint_path(thread_id, id);
match Self::read_checkpoint(&path).await {
Ok(cp) => return Ok(Some(cp)),
Err(e) => tracing::warn!(
thread_id = %thread_id,
path = %path.display(),
error = %e,
"latest pointer target unreadable; falling back to directory scan"
),
}
}
}
}
Ok(self
.scan_thread_raw(thread_id)
.await?
.into_iter()
.max_by(|a, b| a.created_at.cmp(&b.created_at).then(a.id.cmp(&b.id))))
}
async fn load_chain(&self, thread_id: &str, tip: Checkpoint) -> Result<Vec<Checkpoint>> {
let fold_bound = self.policy.max_chain_len.saturating_mul(4).max(128);
let mut chain = vec![tip];
let mut visited = HashSet::new();
while let Some(base_id) = chain.last().expect("chain starts non-empty").base.clone() {
if !visited.insert(base_id.clone()) {
return Err(RustyError::Checkpoint(format!(
"checkpoint delta chain in thread `{thread_id}` has a cycle at `{base_id}`"
)));
}
if chain.len() > fold_bound {
return Err(RustyError::Checkpoint(format!(
"checkpoint delta chain in thread `{thread_id}` exceeds {fold_bound} links; \
refusing to fold (write bound is {})",
self.policy.max_chain_len
)));
}
let path = self.checkpoint_path(thread_id, &base_id);
chain.push(Self::read_checkpoint(&path).await?);
}
chain.reverse();
Ok(chain)
}
async fn head_of(&self, thread_id: &str) -> Result<Option<DeltaHead>> {
if let Some(head) = self.lock_heads()?.get(thread_id) {
return Ok(Some(head.clone()));
}
let Some(raw) = self.read_latest_raw(thread_id).await? else {
return Ok(None);
};
let chain = self.load_chain(thread_id, raw).await?;
let head = DeltaHead {
chain_len: chain.len() - 1,
checkpoint: fold_chain(&chain)?,
};
self.lock_heads()?
.insert(thread_id.to_owned(), head.clone());
Ok(Some(head))
}
fn lock_heads(&self) -> Result<std::sync::MutexGuard<'_, HashMap<String, DeltaHead>>> {
self.heads
.lock()
.map_err(|_| RustyError::Checkpoint("delta-head cache poisoned".into()))
}
async fn put_internal(&self, checkpoint: Checkpoint, force_full: bool) -> Result<()> {
let lock = self.put_lock(&checkpoint.thread_id)?;
let _put_guard = lock.lock().await;
let thread_dir = self.thread_dir(&checkpoint.thread_id);
tokio::fs::create_dir_all(&thread_dir).await.map_err(|e| {
RustyError::Checkpoint(format!(
"failed to create thread directory `{}`: {e}",
thread_dir.display()
))
})?;
let path = self.checkpoint_path(&checkpoint.thread_id, &checkpoint.id);
if tokio::fs::try_exists(&path).await.map_err(|e| {
RustyError::Checkpoint(format!(
"failed to stat checkpoint file `{}`: {e}",
path.display()
))
})? {
return Err(RustyError::Checkpoint(format!(
"checkpoint id `{}` already exists for thread `{}`",
checkpoint.id, checkpoint.thread_id
)));
}
let encoding = if force_full {
DeltaEncoding::full(&checkpoint)
} else {
let head = self.head_of(&checkpoint.thread_id).await?;
encode_delta(&checkpoint, head.as_ref(), &self.policy)
};
let bytes = serde_json::to_vec_pretty(&encoding.checkpoint)?;
Self::atomic_write(&path, &bytes).await?;
Self::atomic_write(
&self.latest_path(&checkpoint.thread_id),
checkpoint.id.as_bytes(),
)
.await?;
tracing::debug!(
thread_id = %checkpoint.thread_id,
checkpoint_id = %checkpoint.id,
step = checkpoint.step,
delta = encoding.checkpoint.base.is_some(),
path = %path.display(),
"checkpoint persisted (json file)"
);
self.lock_heads()?.insert(
checkpoint.thread_id.clone(),
DeltaHead {
checkpoint,
chain_len: encoding.chain_len,
},
);
Ok(())
}
}
#[async_trait]
impl Checkpointer for JsonFileCheckpointer {
async fn put(&self, checkpoint: Checkpoint) -> Result<()> {
self.put_internal(checkpoint, false).await
}
async fn get_latest(&self, thread_id: &str) -> Result<Option<Checkpoint>> {
let Some(raw) = self.read_latest_raw(thread_id).await? else {
return Ok(None);
};
if raw.base.is_none() {
return Ok(Some(raw));
}
let chain = self.load_chain(thread_id, raw).await?;
fold_chain(&chain).map(Some)
}
async fn list(&self, thread_id: &str) -> Result<Vec<Checkpoint>> {
let mut all = materialize_all(self.scan_thread_raw(thread_id).await?);
all.sort_by(|a, b| {
a.step
.cmp(&b.step)
.then(a.created_at.cmp(&b.created_at))
.then(a.id.cmp(&b.id))
});
Ok(all)
}
async fn fork_thread(
&self,
src_thread: &str,
dst_thread: &str,
at_checkpoint_id: Option<&str>,
) -> Result<usize> {
if src_thread == dst_thread {
return Err(RustyError::Checkpoint(format!(
"cannot fork thread `{src_thread}` onto itself: checkpoint ids would collide"
)));
}
let all = self.list(src_thread).await?;
if all.is_empty() {
return Err(RustyError::Checkpoint(format!(
"cannot fork thread `{src_thread}`: no checkpoints found"
)));
}
let selected: Vec<Checkpoint> = match at_checkpoint_id {
None => all,
Some(id) => {
let pos = all.iter().position(|c| c.id == id).ok_or_else(|| {
RustyError::Checkpoint(format!(
"cannot fork thread `{src_thread}`: unknown checkpoint id `{id}`"
))
})?;
all[..=pos].to_vec()
}
};
let copied = selected.len();
for mut checkpoint in selected {
checkpoint.thread_id = dst_thread.to_string();
checkpoint.base = None;
self.put_internal(checkpoint, true).await?;
}
tracing::info!(
src_thread = %src_thread,
dst_thread = %dst_thread,
copied = copied,
"thread history forked"
);
Ok(copied)
}
}
#[cfg(test)]
mod tests {
use super::*;
fn cp(thread: &str, step: usize) -> Checkpoint {
Checkpoint::new(thread, step, State::new(), vec!["next".into()])
}
#[tokio::test]
async fn in_memory_roundtrip() {
let store = InMemoryCheckpointer::new();
assert!(store.get_latest("t1").await.unwrap().is_none());
assert!(store.list("t1").await.unwrap().is_empty());
store.put(cp("t1", 0)).await.unwrap();
store.put(cp("t1", 1)).await.unwrap();
store.put(cp("t2", 0)).await.unwrap();
let latest = store.get_latest("t1").await.unwrap().unwrap();
assert_eq!(latest.step, 1);
assert_eq!(latest.next_nodes, vec!["next".to_string()]);
let all = store.list("t1").await.unwrap();
assert_eq!(all.len(), 2);
assert_eq!(all[0].step, 0);
assert_eq!(all[1].step, 1);
assert_eq!(store.list("t2").await.unwrap().len(), 1);
}
#[tokio::test]
async fn in_memory_rejects_duplicate_id() {
let store = InMemoryCheckpointer::new();
let checkpoint = cp("t1", 0);
store.put(checkpoint.clone()).await.unwrap();
let err = store.put(checkpoint).await.unwrap_err();
assert!(matches!(err, RustyError::Checkpoint(_)));
}
#[tokio::test]
async fn checkpoint_serializes() {
let checkpoint = cp("t1", 2);
let json = serde_json::to_string(&checkpoint).unwrap();
let back: Checkpoint = serde_json::from_str(&json).unwrap();
assert_eq!(back.id, checkpoint.id);
assert_eq!(back.step, 2);
}
struct TestDir(PathBuf);
impl TestDir {
fn new() -> Self {
Self(
std::env::temp_dir()
.join(format!("rusty-checkpoint-test-{}", uuid::Uuid::new_v4())),
)
}
}
impl Drop for TestDir {
fn drop(&mut self) {
let _ = std::fs::remove_dir_all(&self.0);
}
}
#[tokio::test]
async fn json_file_roundtrip() {
let tmp = TestDir::new();
let store = JsonFileCheckpointer::new(tmp.0.clone());
assert!(store.get_latest("t1").await.unwrap().is_none());
assert!(store.list("t1").await.unwrap().is_empty());
let mut state = State::new();
state.insert("answer", serde_json::json!(42));
let cp0 = Checkpoint::new("t1", 0, state.clone(), vec!["node_b".into()]);
let id0 = cp0.id.clone();
store.put(cp0).await.unwrap();
assert!(tmp.0.join("t1").join(format!("{id0}.json")).exists());
let back = store.get_latest("t1").await.unwrap().unwrap();
assert_eq!(back.id, id0);
assert_eq!(back.thread_id, "t1");
assert_eq!(back.step, 0);
assert_eq!(back.state, state);
assert_eq!(back.next_nodes, vec!["node_b".to_string()]);
assert!(store.get_latest("t2").await.unwrap().is_none());
}
#[tokio::test]
async fn json_file_latest_pointer_tracks_most_recent_put() {
let tmp = TestDir::new();
let store = JsonFileCheckpointer::new(tmp.0.clone());
store.put(cp("t1", 0)).await.unwrap();
let cp1 = cp("t1", 1);
let id1 = cp1.id.clone();
store.put(cp1).await.unwrap();
let pointer = std::fs::read_to_string(tmp.0.join("t1").join("latest")).unwrap();
assert_eq!(pointer, id1);
let latest = store.get_latest("t1").await.unwrap().unwrap();
assert_eq!(latest.id, id1);
assert_eq!(latest.step, 1);
}
#[tokio::test]
async fn json_file_list_sorted_by_step_regardless_of_put_order() {
let tmp = TestDir::new();
let store = JsonFileCheckpointer::new(tmp.0.clone());
store.put(cp("t1", 2)).await.unwrap();
store.put(cp("t1", 0)).await.unwrap();
store.put(cp("t1", 1)).await.unwrap();
let all = store.list("t1").await.unwrap();
assert_eq!(all.len(), 3);
assert_eq!(all[0].step, 0);
assert_eq!(all[1].step, 1);
assert_eq!(all[2].step, 2);
let latest = store.get_latest("t1").await.unwrap().unwrap();
assert_eq!(latest.step, 1);
}
#[tokio::test]
async fn recency_and_list_order_agree_across_backends() {
let tmp = TestDir::new();
let memory = InMemoryCheckpointer::new();
let json_file = JsonFileCheckpointer::new(tmp.0.clone());
let steps = [2usize, 0, 1];
for step in steps {
memory.put(cp("t1", step)).await.unwrap();
json_file.put(cp("t1", step)).await.unwrap();
}
let stores: [&dyn Checkpointer; 2] = [&memory, &json_file];
for store in stores {
let latest = store.get_latest("t1").await.unwrap().unwrap();
assert_eq!(latest.step, 1, "backend disagrees on recency");
let listed: Vec<usize> = store
.list("t1")
.await
.unwrap()
.iter()
.map(|c| c.step)
.collect();
assert_eq!(listed, [0, 1, 2], "backend disagrees on list order");
}
}
#[tokio::test]
async fn json_file_missing_thread_returns_none_and_empty() {
let tmp = TestDir::new();
let store = JsonFileCheckpointer::new(tmp.0.clone());
assert!(store.get_latest("never-seen").await.unwrap().is_none());
assert!(store.list("never-seen").await.unwrap().is_empty());
}
#[tokio::test]
async fn json_file_rejects_duplicate_id() {
let tmp = TestDir::new();
let store = JsonFileCheckpointer::new(tmp.0.clone());
let checkpoint = cp("t1", 0);
store.put(checkpoint.clone()).await.unwrap();
let err = store.put(checkpoint).await.unwrap_err();
assert!(matches!(err, RustyError::Checkpoint(_)));
}
#[tokio::test]
async fn json_file_durable_across_instances() {
let tmp = TestDir::new();
let cp0 = cp("t1", 0);
let id0 = cp0.id.clone();
JsonFileCheckpointer::new(tmp.0.clone())
.put(cp0)
.await
.unwrap();
let reopened = JsonFileCheckpointer::new(tmp.0.clone());
let latest = reopened.get_latest("t1").await.unwrap().unwrap();
assert_eq!(latest.id, id0);
assert_eq!(reopened.list("t1").await.unwrap().len(), 1);
}
#[tokio::test]
async fn json_file_corrupt_files_are_handled_gracefully() {
let tmp = TestDir::new();
let store = JsonFileCheckpointer::new(tmp.0.clone());
let good = cp("t1", 0);
let good_id = good.id.clone();
store.put(good).await.unwrap();
std::fs::write(tmp.0.join("t1").join("garbage.json"), b"{not json!!").unwrap();
let all = store.list("t1").await.unwrap();
assert_eq!(all.len(), 1);
assert_eq!(all[0].id, good_id);
std::fs::write(tmp.0.join("t1").join("latest"), b"no-such-checkpoint-id").unwrap();
let latest = store.get_latest("t1").await.unwrap().unwrap();
assert_eq!(latest.id, good_id);
std::fs::write(tmp.0.join("t1").join("latest"), [0xff, 0xfe, 0x00]).unwrap();
let latest = store.get_latest("t1").await.unwrap().unwrap();
assert_eq!(latest.id, good_id);
}
#[tokio::test]
async fn get_by_id_hit_and_miss() {
let store = InMemoryCheckpointer::new();
let cp0 = cp("t1", 0);
let id0 = cp0.id.clone();
store.put(cp0).await.unwrap();
store.put(cp("t1", 1)).await.unwrap();
store.put(cp("t2", 0)).await.unwrap();
let hit = store.get_by_id("t1", &id0).await.unwrap().unwrap();
assert_eq!(hit.id, id0);
assert_eq!(hit.step, 0);
assert_eq!(hit.thread_id, "t1");
assert!(store.get_by_id("t1", "no-such-id").await.unwrap().is_none());
assert!(store.get_by_id("t2", &id0).await.unwrap().is_none());
assert!(store.get_by_id("never-seen", &id0).await.unwrap().is_none());
}
#[tokio::test]
async fn fork_full_history_copies_all_checkpoints() {
let store = InMemoryCheckpointer::new();
let mut src = Vec::new();
for step in 0..3 {
let mut state = State::new();
state.insert("n", serde_json::json!(step));
let checkpoint = Checkpoint::new("src", step, state, vec!["next".into()]);
src.push(checkpoint.clone());
store.put(checkpoint).await.unwrap();
}
let copied = store.fork_thread("src", "dst", None).await.unwrap();
assert_eq!(copied, 3);
let dst = store.list("dst").await.unwrap();
assert_eq!(dst.len(), 3);
for (forked, original) in dst.iter().zip(src.iter()) {
assert_eq!(forked.id, original.id);
assert_eq!(forked.step, original.step);
assert_eq!(forked.state, original.state);
assert_eq!(forked.next_nodes, original.next_nodes);
assert_eq!(forked.created_at, original.created_at);
assert_eq!(forked.thread_id, "dst");
}
assert_eq!(store.get_latest("dst").await.unwrap().unwrap().step, 2);
assert_eq!(store.list("src").await.unwrap().len(), 3);
}
#[tokio::test]
async fn fork_at_mid_checkpoint_truncates_history() {
let store = InMemoryCheckpointer::new();
let mut ids = Vec::new();
for step in 0..4 {
let checkpoint = cp("src", step);
ids.push(checkpoint.id.clone());
store.put(checkpoint).await.unwrap();
}
let copied = store
.fork_thread("src", "dst", Some(&ids[1]))
.await
.unwrap();
assert_eq!(copied, 2);
let dst = store.list("dst").await.unwrap();
assert_eq!(dst.len(), 2);
assert_eq!(dst[0].id, ids[0]);
assert_eq!(dst[1].id, ids[1]);
assert_eq!(dst[0].step, 0);
assert_eq!(dst[1].step, 1);
assert_eq!(store.get_latest("dst").await.unwrap().unwrap().id, ids[1]);
}
#[tokio::test]
async fn fork_errors_on_empty_src_unknown_id_and_self_fork() {
let store = InMemoryCheckpointer::new();
let checkpoint = cp("src", 0);
let id0 = checkpoint.id.clone();
store.put(checkpoint).await.unwrap();
let err = store.fork_thread("empty", "dst", None).await.unwrap_err();
assert!(matches!(err, RustyError::Checkpoint(_)));
let err = store
.fork_thread("src", "dst", Some("no-such-id"))
.await
.unwrap_err();
assert!(matches!(err, RustyError::Checkpoint(_)));
let err = store
.fork_thread("src", "src", Some(&id0))
.await
.unwrap_err();
assert!(matches!(err, RustyError::Checkpoint(_)));
assert!(store.list("dst").await.unwrap().is_empty());
}
#[tokio::test]
async fn json_file_fork_across_threads_persists_correctly() {
let tmp = TestDir::new();
let store = JsonFileCheckpointer::new(tmp.0.clone());
let mut ids = Vec::new();
for step in 0..3 {
let mut state = State::new();
state.insert("n", serde_json::json!(step));
let checkpoint = Checkpoint::new("src", step, state, vec!["next".into()]);
ids.push(checkpoint.id.clone());
store.put(checkpoint).await.unwrap();
}
let copied = store
.fork_thread("src", "dst", Some(&ids[1]))
.await
.unwrap();
assert_eq!(copied, 2);
assert!(tmp.0.join("dst").join(format!("{}.json", ids[0])).exists());
assert!(tmp.0.join("dst").join(format!("{}.json", ids[1])).exists());
assert!(!tmp.0.join("dst").join(format!("{}.json", ids[2])).exists());
let latest = store.get_latest("dst").await.unwrap().unwrap();
assert_eq!(latest.id, ids[1]);
assert_eq!(latest.thread_id, "dst");
assert_eq!(latest.step, 1);
let reopened = JsonFileCheckpointer::new(tmp.0.clone());
let dst = reopened.list("dst").await.unwrap();
assert_eq!(dst.len(), 2);
assert_eq!(dst[0].id, ids[0]);
assert_eq!(dst[1].id, ids[1]);
assert!(dst.iter().all(|c| c.thread_id == "dst"));
assert_eq!(reopened.list("src").await.unwrap().len(), 3);
assert_eq!(
reopened.get_latest("src").await.unwrap().unwrap().id,
ids[2]
);
}
fn evolving_state(step: usize, blob: &str) -> State {
let mut state = State::new();
state.insert("blob", serde_json::json!(blob));
state.insert("step", serde_json::json!(step));
state
}
fn file_json(tmp: &TestDir, thread: &str, id: &str) -> serde_json::Value {
let text = std::fs::read_to_string(tmp.0.join(thread).join(format!("{id}.json"))).unwrap();
serde_json::from_str(&text).unwrap()
}
#[tokio::test]
async fn delta_chain_roundtrips_through_read_paths() {
let tmp = TestDir::new();
let store = JsonFileCheckpointer::new(tmp.0.clone());
let blob = "x".repeat(1024);
let mut ids = Vec::new();
for step in 0..5 {
let cp = Checkpoint::new("t1", step, evolving_state(step, &blob), vec!["next".into()]);
ids.push(cp.id.clone());
store.put(cp).await.unwrap();
}
let on_disk = file_json(&tmp, "t1", &ids[2]);
assert_eq!(on_disk["base"], serde_json::json!(ids[1]));
assert_eq!(
on_disk["state"],
serde_json::json!({"step": 2}),
"delta file must carry only changed channels"
);
let latest = store.get_latest("t1").await.unwrap().unwrap();
assert_eq!(latest.base, None, "read methods never return a delta");
assert_eq!(latest.state, evolving_state(4, &blob));
let all = store.list("t1").await.unwrap();
assert_eq!(all.len(), 5);
for (step, cp) in all.iter().enumerate() {
assert_eq!(cp.state, evolving_state(step, &blob));
assert_eq!(cp.base, None);
}
let mid = store.get_by_id("t1", &ids[1]).await.unwrap().unwrap();
assert_eq!(mid.state, evolving_state(1, &blob));
}
#[tokio::test]
async fn delta_chain_is_bounded_by_policy() {
let tmp = TestDir::new();
let policy = DeltaPolicy {
max_chain_len: 3,
..DeltaPolicy::default()
};
let store = JsonFileCheckpointer::with_delta_policy(tmp.0.clone(), policy);
let mut ids = Vec::new();
for step in 0..7 {
let cp = Checkpoint::new("t1", step, evolving_state(step, "b"), vec![]);
ids.push(cp.id.clone());
store.put(cp).await.unwrap();
}
let expect_full = [true, false, false, false, true, false, false];
for (i, id) in ids.iter().enumerate() {
let on_disk = file_json(&tmp, "t1", id);
assert_eq!(
on_disk.get("base").is_some(),
!expect_full[i],
"checkpoint {i} full/delta mismatch: {on_disk}"
);
}
let all = store.list("t1").await.unwrap();
for (step, cp) in all.iter().enumerate() {
assert_eq!(cp.state, evolving_state(step, "b"));
}
}
#[tokio::test]
async fn delta_byte_ratio_forces_full_when_delta_stops_paying() {
let tmp = TestDir::new();
let policy = DeltaPolicy {
max_chain_len: 32,
max_byte_ratio: 0.5,
};
let store = JsonFileCheckpointer::with_delta_policy(tmp.0.clone(), policy);
let base_state = State::from_value(serde_json::json!({"a": "AAAA", "b": "BBBB"})).unwrap();
let cp0 = Checkpoint::new("t1", 0, base_state, vec![]);
let id0 = cp0.id.clone();
store.put(cp0).await.unwrap();
let changed = State::from_value(serde_json::json!({"a": "CCCC", "b": "DDDD"})).unwrap();
let cp1 = Checkpoint::new("t1", 1, changed, vec![]);
let id1 = cp1.id.clone();
store.put(cp1).await.unwrap();
assert!(file_json(&tmp, "t1", &id0).get("base").is_none());
assert!(
file_json(&tmp, "t1", &id1).get("base").is_none(),
"a delta worth ~full must reset the chain"
);
assert_eq!(
store.get_latest("t1").await.unwrap().unwrap().state,
State::from_value(serde_json::json!({"a": "CCCC", "b": "DDDD"})).unwrap()
);
}
#[tokio::test]
async fn delta_dedupes_equal_content_without_pointer_sharing() {
let tmp = TestDir::new();
let store = JsonFileCheckpointer::new(tmp.0.clone());
store
.put(Checkpoint::new(
"t1",
0,
State::from_value(serde_json::json!({"k": "v"})).unwrap(),
vec![],
))
.await
.unwrap();
let cp1 = Checkpoint::new(
"t1",
1,
State::from_value(serde_json::json!({"k": "v"})).unwrap(),
vec![],
);
let id1 = cp1.id.clone();
store.put(cp1).await.unwrap();
let on_disk = file_json(&tmp, "t1", &id1);
assert!(on_disk.get("base").is_some());
assert_eq!(
on_disk["state"],
serde_json::json!({}),
"identical content must produce an empty delta"
);
assert_eq!(
store.get_latest("t1").await.unwrap().unwrap().state,
State::from_value(serde_json::json!({"k": "v"})).unwrap()
);
}
#[tokio::test]
async fn reopened_store_rebuilds_the_head_and_keeps_differencing() {
let tmp = TestDir::new();
let blob = "y".repeat(512);
let id0;
{
let store = JsonFileCheckpointer::new(tmp.0.clone());
let cp = Checkpoint::new("t1", 0, evolving_state(0, &blob), vec![]);
id0 = cp.id.clone();
store.put(cp).await.unwrap();
}
let reopened = JsonFileCheckpointer::new(tmp.0.clone());
let cp1 = Checkpoint::new("t1", 1, evolving_state(1, &blob), vec![]);
let id1 = cp1.id.clone();
reopened.put(cp1).await.unwrap();
let on_disk = file_json(&tmp, "t1", &id1);
assert_eq!(on_disk["base"], serde_json::json!(id0));
assert_eq!(on_disk["state"], serde_json::json!({"step": 1}));
assert_eq!(
reopened.get_latest("t1").await.unwrap().unwrap().state,
evolving_state(1, &blob)
);
}
#[tokio::test]
async fn pre_delta_checkpoints_load_unchanged() {
let tmp = TestDir::new();
let store = JsonFileCheckpointer::new(tmp.0.clone());
let cp = Checkpoint::new("t1", 0, evolving_state(3, "legacy"), vec!["next".into()]);
let id = cp.id.clone();
let dir = tmp.0.join("t1");
std::fs::create_dir_all(&dir).unwrap();
let mut json: serde_json::Value =
serde_json::from_str(&serde_json::to_string_pretty(&cp).unwrap()).unwrap();
json.as_object_mut().unwrap().remove("base");
let text = serde_json::to_string_pretty(&json).unwrap();
assert!(!text.contains("\"base\""));
std::fs::write(dir.join(format!("{id}.json")), &text).unwrap();
std::fs::write(dir.join("latest"), &id).unwrap();
let latest = store.get_latest("t1").await.unwrap().unwrap();
assert_eq!(latest.id, id);
assert_eq!(latest.state, evolving_state(3, "legacy"));
assert_eq!(latest.next_nodes, vec!["next".to_string()]);
assert_eq!(latest.base, None);
let cp1 = Checkpoint::new("t1", 1, evolving_state(4, "legacy"), vec![]);
let id1 = cp1.id.clone();
store.put(cp1).await.unwrap();
assert_eq!(file_json(&tmp, "t1", &id1)["base"], serde_json::json!(id));
}
#[tokio::test]
async fn fork_compacts_to_full_snapshots() {
let tmp = TestDir::new();
let store = JsonFileCheckpointer::new(tmp.0.clone());
let mut ids = Vec::new();
for step in 0..4 {
let cp = Checkpoint::new("src", step, evolving_state(step, "f"), vec![]);
ids.push(cp.id.clone());
store.put(cp).await.unwrap();
}
let copied = store
.fork_thread("src", "dst", Some(&ids[2]))
.await
.unwrap();
assert_eq!(copied, 3);
for id in &ids[..3] {
let on_disk = file_json(&tmp, "dst", id);
assert!(
on_disk.get("base").is_none(),
"forked checkpoint must be a full snapshot: {on_disk}"
);
}
assert_eq!(
store.get_latest("dst").await.unwrap().unwrap().state,
evolving_state(2, "f")
);
assert_eq!(
store.get_latest("src").await.unwrap().unwrap().state,
evolving_state(3, "f")
);
}
#[tokio::test]
async fn full_only_policy_restores_pre_w4_writes() {
let tmp = TestDir::new();
let store =
JsonFileCheckpointer::with_delta_policy(tmp.0.clone(), DeltaPolicy::full_only());
let mut ids = Vec::new();
for step in 0..3 {
let cp = Checkpoint::new("t1", step, evolving_state(step, "z"), vec![]);
ids.push(cp.id.clone());
store.put(cp).await.unwrap();
}
for id in &ids {
assert!(file_json(&tmp, "t1", id).get("base").is_none());
}
assert_eq!(store.list("t1").await.unwrap().len(), 3);
}
#[test]
fn encode_delta_decides_full_delta_and_bounds() {
let head_state = evolving_state(0, "blob");
let head_cp = Checkpoint::new("t", 0, head_state.clone(), vec![]);
let head = DeltaHead {
checkpoint: head_cp.clone(),
chain_len: 0,
};
let policy = DeltaPolicy::default();
let next = Checkpoint::new("t", 1, evolving_state(1, "blob"), vec![]);
let encoding = encode_delta(&next, Some(&head), &policy);
assert_eq!(encoding.checkpoint.base, Some(head_cp.id.clone()));
assert_eq!(
encoding.checkpoint.state,
State::from_value(serde_json::json!({"step": 1})).unwrap()
);
assert_eq!(encoding.chain_len, 1);
let at_bound = DeltaHead {
chain_len: policy.max_chain_len,
..head.clone()
};
let encoding = encode_delta(&next, Some(&at_bound), &policy);
assert_eq!(encoding.checkpoint.base, None);
assert_eq!(encoding.chain_len, 0);
assert!(encode_delta(&next, None, &policy).checkpoint.base.is_none());
assert!(encode_delta(&next, Some(&head), &DeltaPolicy::full_only())
.checkpoint
.base
.is_none());
let mut with_base = next.clone();
with_base.base = Some("caller-lie".into());
let encoding = encode_delta(&with_base, Some(&at_bound), &policy);
assert_eq!(encoding.checkpoint.base, None);
}
#[test]
fn fold_chain_materializes_and_rejects_broken_chains() {
let blob = "q".repeat(64);
let mut chain: Vec<Checkpoint> = Vec::new();
let mut head: Option<DeltaHead> = None;
for step in 0..4 {
let full = Checkpoint::new("t", step, evolving_state(step, &blob), vec![]);
let encoding = encode_delta(&full, head.as_ref(), &DeltaPolicy::default());
chain.push(encoding.checkpoint);
head = Some(DeltaHead {
checkpoint: full,
chain_len: encoding.chain_len,
});
}
let tip = fold_chain(&chain).unwrap();
assert_eq!(tip.state, evolving_state(3, &blob));
assert_eq!(tip.base, None);
let err = fold_chain(&chain[1..]).unwrap_err();
assert!(matches!(err, RustyError::Checkpoint(_)));
let mut broken = chain.clone();
broken[2].base = Some("not-the-parent".into());
assert!(fold_chain(&broken).is_err());
}
#[test]
fn materialize_all_folds_memoized_and_skips_corruption() {
let full = Checkpoint::new("t", 0, evolving_state(0, "m"), vec![]);
let mut link = Checkpoint::new("t", 1, evolving_state(1, "m"), vec![]);
link.base = Some(full.id.clone());
link.state = State::from_value(serde_json::json!({"step": 1})).unwrap();
let mut dangling = Checkpoint::new("t", 2, State::new(), vec![]);
dangling.base = Some("missing-base".into());
let mut cyclic = Checkpoint::new("t", 3, State::new(), vec![]);
cyclic.base = Some(cyclic.id.clone());
let materialized = materialize_all(vec![link.clone(), dangling, cyclic, full.clone()]);
assert_eq!(materialized.len(), 2);
let by_step: HashMap<usize, &Checkpoint> =
materialized.iter().map(|c| (c.step, c)).collect();
assert_eq!(by_step[&0].state, evolving_state(0, "m"));
assert_eq!(by_step[&1].state, evolving_state(1, "m"));
assert!(materialized.iter().all(|c| c.base.is_none()));
}
}