Module checkpoint 

§2 module 20 checkpoint (COMPOSABLE-HARNESS-DESIGN.md line 470): file checkpointing / shadow-git; D4-adjacent revert; D3 turn-diff tracking. Line 1504: “restores FILES, not context — pairs with, never replaces, the reduction sidecar.”

Not to be confused with crate::Agent::checkpoint/crate::Agent::rewind_to (an in-memory CONVERSATION-position marker, an unrelated pre-existing facility) or crate::session_tree (module 21, tree-addressable sessions). This module only ever touches files on disk.

The write-path interception seam (D-5, shared with formatters/P5-11)

crate::tools::WriteObserver (defined in crate::tools, the seam’s natural owner since crate::tools::ToolContext carries it) is called by write_file/edit_file/apply_patch around their mutation. CheckpointObserver is this module’s implementation: before_write captures a pre-image; after_write is a no-op (reserved for formatters).

Storage — never the user’s real git

CheckpointStore is a content-addressed, per-project shadow store at a caller-supplied root (the same dependency-injection shape as crate::store::SessionStore::open) — blobs keyed by crate::reduce::content_hash under <root>/objects/, one JSON manifest per checkpoint under <root>/checkpoints/<id>.json. This module never shells out to git and never touches the project’s own .git — there is no GIT_DIR to get wrong because none is ever used.

C8 (design line 1819) compliance

A CheckpointId is an opaque String — the ONLY thing a caller (session record, CLI) ever threads around. It is never the file contents, and it never reaches the model’s context window: restoring files is a disk operation, never a conversation-history mutation.

Structs

CheckpointFileEntry

One file’s entry in a CheckpointManifest — the turn-diff (D3) is simply this manifest’s files list.

CheckpointManifest

A checkpoint’s full manifest — one JSON file per checkpoint.

CheckpointMeta

Lightweight listing entry (CheckpointStore::list) — the manifest without the (potentially long) file list.

CheckpointObserver

WriteObserver implementation backing [capabilities.checkpoint]. One instance per crate::Agent (installed on its crate::tools::ToolContext AND held directly so crate::Agent::run_loop can call Self::begin_turn once per user turn — see that method’s call site’s doc comment).

CheckpointStore

A directory-backed, content-addressed shadow store rooted at root — see the module doc comment. Never touches anything outside root except (during Self::restore) the project files a manifest names, which are re-validated against project_root independently of how the manifest was produced.

RestoreReport

The outcome of a CheckpointStore::restore call.

Constants

DEFAULT_RETAIN

Default number of checkpoints retained per project before the oldest are pruned (bounded-disk requirement) — overridable via [capabilities.checkpoint].retain.

Functions

observer_for_config

Build the CheckpointObserver a fresh crate::Agent should install, given a resolved crate::Config — called once, from crate::agent::build_tool_context. Config::checkpoint_enabled is the ONE gate: false (the default) returns None WITHOUT touching the filesystem at all (no CheckpointStore::open, no directory created) — the default-off byte-identity guarantee. true opens (creating if needed) the shadow store at Config::checkpoint_dir, or default_shadow_root when that’s unset; an I/O failure (unwritable state dir) is reported via a one-time eprintln! warning and returns None — graceful degrade, never a crash, never a blocked Agent::new.

Type Aliases

CheckpointId

An opaque, lexically-sortable (ascending = chronological, since it’s zero-padded-millis-prefixed) checkpoint identifier. This is ALL a session record ever carries for C8 — never file contents.