Struct FileCheckpointStore 

pub struct FileCheckpointStore { /* private fields */ }

Durable checkpoint store that persists one checkpoint per JSON file.

Checkpoints are written atomically, so a failed save never leaves a partial or zero-length live file behind. Checkpoint IDs are validated before file access and therefore must not contain path separators, .., :, or ASCII control characters.

Retention is unbounded by default. Use with_max_checkpoints to prune older checkpoints after each save.

All filesystem work runs on Tokio’s blocking pool via tokio::task::spawn_blocking, so the returned futures never stall an async worker thread and must be polled inside a Tokio runtime.

Implementations

impl FileCheckpointStore

pub const DEFAULT_MAX_CHECKPOINTS: usize = 20

Recommended bound for callers that want capped checkpoint retention.

New stores are unbounded by default for backwards compatibility with the public checkpoint policy contract.

pub fn new(checkpoints_dir: PathBuf) -> Result<Self>

Create a new store rooted at the given directory.

Creates the directory (and parents) if it does not already exist.

The store keeps every checkpoint by default; see Self::with_max_checkpoints to opt into bounded retention.

pub fn default_dir() -> Option<PathBuf>

Default checkpoints directory: <config_dir>/swink-agent/checkpoints.

pub fn with_max_checkpoints(self, n: usize) -> Self

Keep at most n checkpoints, pruning the oldest (by created_at) after each save.

The checkpoint just saved counts toward the limit, so n should be at least 1. Self::DEFAULT_MAX_CHECKPOINTS is a reasonable preset for callers that do not need every historical checkpoint.

Pruning only considers files in the store directory that parse as checkpoints; foreign or malformed files are never deleted. Pruning is best-effort: failures are logged at warn level and never fail the save that triggered them.

pub fn unbounded(self) -> Self

Disable retention pruning and keep every checkpoint.

This is the default for new stores. It is also useful after a builder chain has temporarily selected a bound. Disk usage then grows without bound: a per-turn checkpoint policy leaves one growing file per turn, so an N-turn session stores O(N²) bytes. Prefer a bound unless every historical checkpoint is needed.

Trait Implementations

impl CheckpointStore for FileCheckpointStore

fn save_checkpoint(&self, checkpoint: Checkpoint) -> CheckpointFuture<'_, ()>

Save a checkpoint. Overwrites any existing checkpoint with the same ID.

fn load_checkpoint(&self, id: &str) -> CheckpointFuture<'_, Option<Checkpoint>>

Load a checkpoint by ID.

fn list_checkpoints(&self) -> CheckpointFuture<'_, Vec<String>>

List all checkpoint IDs, most recent first.

fn delete_checkpoint(&self, id: &str) -> CheckpointFuture<'_, ()>

Delete a checkpoint by ID.