Skip to content

store

diapason.learning.spec_search.checkpoint.store

Git-backed checkpoint store for spec-search config rollback.

A thin wrapper over a local git repository at <diapason_home>/.git. The repo tracks config.toml, agents/, and tools/ so that the diff between two commits captures the harness state at any point in time. The repo does NOT track learning/ (sessions are append-only artifacts, not config state).

The wrapper shells out to git via subprocess rather than depending on a third-party library — keeps the dependency surface zero.

See spec §7.4 and §7.6.

CheckpointStore

Thin git wrapper for the spec-search checkpoint repo.

Parameters

root : The directory that contains the checkpoint repo (the repo's .git lives at root / ".git"). For production use this is ~/.diapason/ (or $DIAPASON_HOME); for tests it's a tmp_path subdirectory.

begin_stage(edit_id)

Capture HEAD sha and assert the working tree is clean.

Raises

DirtyWorkingTreeError If there are uncommitted changes to tracked files. The orchestrator should never start a stage on a dirty tree — it indicates the user has manual edits in progress.

commit_stage(handle, *, message, session_id, risk_tier)

Stage all tracked-path changes and create a commit.

The commit message has the form::

<message>

Edit-ID: <handle.edit_id>
Session-ID: <session_id>
Risk-Tier: <risk_tier>

Returns the new commit sha (abbreviated).

current_sha()

Return the abbreviated sha of HEAD.

discard_stage(handle)

Restore the working tree to handle.pre_stage_sha.

init()

Initialize the checkpoint repo if it doesn't exist.

Refuses to initialize if self.root is inside the Diapason source tree — this is the same defense-in-depth check as resolve_spec_search_root: we never want a stray git repo writing config snapshots into the working copy.

Idempotent: if .git already exists and contains a baseline commit, does nothing.

revert_session(session_id)

Revert all commits tagged Session-ID: <session_id>.

Reverts are applied in reverse chronological order (newest first), each producing a new commit so history is preserved (no rewriting). Returns the list of new revert commit shas.

DirtyWorkingTreeError

Bases: RuntimeError

Raised when begin_stage is called on a working tree with uncommitted changes.

StageHandle dataclass

Snapshot of repo state captured at the start of a staging operation.