Expand description
Scratch-clone cache for git.digest’s remote-URL mode (ADR-088
Amendment 1).
Clones/fetches into ~/.khive/scratch/git-digest/<cache_key>/, keyed by
canonical URL (crate::source::cache_key). An LRU cap evicts the
least-recently-used clone (by a .khive-last-used marker file’s mtime,
touched on every successful ensure_clone) once the cache exceeds
digest_cache_max_repos entries or digest_cache_max_bytes total size –
eviction is safe because ingest cursors live in the database, not the
clone (ADR-088 Amendment 1 §Remote-URL mode). Eviction only ever removes
entries it can prove it owns (is_owned_entry: a 16-hex cache-key
directory name containing both a .git dir and the .khive-last-used
marker) – a KHIVE_GIT_DIGEST_SCRATCH_ROOT override pointed at a broader
or pre-existing directory must never lose unrelated operator data.
A per-clone size cap (digest_cache_clone_max_bytes) rejects a clone/
fetch that grows past its own budget before it ever enters the
addressable cache slot: ensure_clone clones/fetches into a staging
directory outside the cache root, measures it, and only moves it into
<root>/<cache_key>/ when it is under the cap. A too-large clone is
deleted from staging and never touches evict_lru’s bookkeeping or the
cache slot. This guarantees the cap is enforced before the clone enters
the cache – it does NOT bound the transient disk usage of the clone/
fetch child process itself while it runs in staging (git has no
reliable pre-flight or mid-transfer size check for a partial
--filter=blob:none clone); a single oversized git clone can still
transiently consume disk in the staging directory before this check
rejects and removes it.
Config is env-var driven today (KHIVE_GIT_DIGEST_CACHE_MAX_REPOS,
KHIVE_GIT_DIGEST_CACHE_MAX_BYTES, KHIVE_GIT_DIGEST_CLONE_MAX_BYTES,
KHIVE_GIT_DIGEST_SCRATCH_ROOT) rather than a [git] TOML section –
see the implementation report for why.
Enums§
Constants§
Functions§
- ensure_
clone - Ensure a local clone of
canonical_urlexists and is up to date; returns the repo’s local path.