Struct CommitHistory 

pub struct CommitHistory<X: Executor = TokioExecutor> { /* private fields */ }

Append-only Merkle history of commit hashes for one branch.

Two construction modes:

1. CommitHistory::open — purely in-memory. Useful for tests and for callers that don’t want any disk side-effects. Lost on drop.
2. CommitHistory::open_at — on-disk journaled MMR under <mkit_dir>/history/<branch>/. Survives process exit.

Each call to a sync method (append, root, prove) on the journaled flavour drives an async operation on the underlying commonware-storage::journaled::Mmr via the caller-supplied Executor.

Implementations

impl CommitHistory<TokioExecutor>

pub fn open() -> Self

Open a fresh empty in-memory history (Phase 1 shape).

Lost on drop. Useful for unit tests and for callers that just need a proof bundle without committing any state to disk.

impl<X: Executor + 'static> CommitHistory<X>

pub fn open_at( executor: Arc<X>, mkit_dir: &Path, branch: &str, ) -> Result<Self, HistoryError>

Open a persisted history under <mkit_dir>/history/<branch>/.

The on-disk layout is commonware-storage’s native journaled MMR shape — see HISTORY_DIR and SPEC-HISTORY-PROOF §4. If the underlying journal does not yet exist, it is created empty (subsequent CommitHistory::append calls populate it).

Crash recovery is delegated to commonware: its Journaled::init detects a half-written trailing leaf, rewinds the journal to the last valid size, and re-derives the in-memory state. See SPEC-HISTORY-PROOF §4.4 for the contract surfaced to mkit callers.

Errors

• HistoryError::InvalidBranch — branch failed validate_ref_name.
• HistoryError::RuntimeBootstrap — could not start the commonware tokio Runner used to construct the underlying storage Context.
• HistoryError::Corrupted — commonware refused to recover the journal (a deeper-than-trailing-leaf corruption).
• HistoryError::Io — failed to create the history dir.

pub fn mkit_dir(&self) -> Option<&Path>

Borrow the mkit_dir this history was opened against. None for the mem-only flavour. Used by crate::refs::update_ref_with_history to take a RepoLock around the ref-write + MMR-append critical section.

pub fn branch(&self) -> Option<&str>

Borrow the branch name this history was opened against. None for the mem-only flavour.

pub fn append(&mut self, commit_hash: &Hash) -> Result<Position, HistoryError>

Append a commit hash. Returns its leaf Position.

Positions are dense: the n-th append returns Position(n). For the journaled flavour, the underlying MMR is sync’d to disk before returning — survives a SIGKILL immediately after.

pub fn root(&self) -> Hash

Current MMR root digest. 32-byte BLAKE3 (mkit Hash shape).

Defined for an empty history — commonware returns a deterministic empty-MMR root (see SPEC-HISTORY-PROOF §2.3).

Panics

Never panics in practice. Internally calls commonware’s root(&hasher, 0), which only returns an error for a non-zero inactive-peak count; mkit always requests 0 inactive peaks (its proofs are self-contained over the full leaf set), so the Result is always Ok.

pub fn len(&self) -> u64

Number of leaves (commits) appended so far.

pub fn is_empty(&self) -> bool

true if no commits have been appended.

pub fn prove(&self, position: Position) -> Result<InclusionProof, HistoryError>

Build an inclusion proof for the commit at position.

Trait Implementations

impl<X: Executor> Debug for CommitHistory<X>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for CommitHistory<TokioExecutor>

fn default() -> Self

Returns the “default value” for a type.