Module cache 

Available on crate feature vcs-git only.

Persistent change-history cache, keyed by HEAD SHA and repo identity (issue #334).

Re-walking the in-window history on every bca vcs invocation is the dominant cost on large repositories, and CI re-runs differ only by the commits pushed since the last run. This module persists the raw, pre-finalize event log of a walk so a later run can replay it (the replay module) instead of re-walking, and extend it by walking only the new commits.

Why an event log rather than the finished HistoryIndex

Stats is the collapsed, now-relative output of Accumulator::finalize: the time windows are already applied and the per-commit detail is gone. It therefore cannot be merged with newer commits, nor re-windowed when wall-clock now advances. The cache instead stores one CommitEvent per in-window commit — the same data the walk folds — so replay reconstructs the index at the current now (correct windowing, no staleness) and incremental update is a plain splice of newer events onto cached ones.

Author privacy

Authors are stored only as their unkeyed SHA-256 hashed digests, never plaintext: the cache must not write raw author emails to disk. Replay reconstructs identities with AuthorId::from_digest, which preserves author counts, ownership, and the emitted hashes bit-for-bit (distinct emails yield distinct digests). The digest is a stable pseudonym, not anonymization — it is recoverable against a candidate email set; see hashed for the threat model.

The opt-in --author-hash-key hardening (issue #956) keys the emitted digest only, applied at finalization (like --emit-author-details), so it never changes what the cache stores: the cache holds the unkeyed inner digest and replaying it under any key reproduces a fresh walk’s keyed output. The on-disk digest is therefore deliberately unkeyed; it is local-only and never published. See AuthorId::emit_hashed.

Invalidation

A cached entry is honoured only when its CACHE_SCHEMA_VERSION, VCS_SCHEMA_VERSION, RISK_SCORE_VERSION, the fingerprint of the walk-affecting options, and the shallow state under which it was walked all match the current run; otherwise it is ignored and the history recomputed. Window changes alter the fingerprint, so they force a fresh walk, as the issue specifies. A shallow clone that is later deepened (git fetch --unshallow) leaves HEAD unmoved, so the entry key is unchanged; the shallow-state match in HistoryCache::is_compatible is what forces a re-walk to replace the truncated counts (issue #810). A corrupt or unreadable entry is silently ignored, never fatal.

Structs

CacheConfig

Front-end control over the persistent cache for one build.

Constants

CACHE_SCHEMA_VERSION

On-disk format version for the cache. Bump on any change to the HistoryCache / CommitEvent shape; an older entry is then ignored rather than mis-parsed.