Module cache 

Persistent fact-store cache: key derivation + XDG path resolution.

Cache path layout: $XDG_CACHE_HOME/codelore/<repo_hash_8>/<cache_key_16>.duckdb

Cache key covers: canonical_repo_path, HEAD SHA, crate version, options thresholds, cache epoch. Excludes: rows_limit, repo_path (repository identity is established by the canonical path hashed as the key’s first component, so the raw spelling must not enter the options hash), cosmetic flags.

Constants

CACHE_EPOCH

Cache-invalidation epoch — a manual cache-buster folded into the cache key. Bump on any correctness fix that should orphan existing cache files, whether or not the DuckDB schema shape changed. This is deliberately independent of facts::schema::CURRENT_SCHEMA_VERSION (the on-disk schema version): a non-schema correctness fix bumps this without touching the schema version, and the historical schema_v prefix on the value is retained so older cache files stay invalidated.

GLOBAL_CACHE_MAX_BYTES

Ceiling on total .duckdb bytes across every repository’s cache. Companion .wal files and the JSON sidecars are outside this total — only the fact stores are counted and evicted.

MAX_REPO_CACHE_ENTRIES

Cache entries kept per repository before the oldest are evicted. Named so the eviction bound and the number codelore profile reports to the user come from one place.

Functions

cache_key

Compute a 32-byte SHA-256 cache key from: canonical_repo_path || NUL || head_sha || NUL || CARGO_PKG_VERSION || NUL || opts_hash(opts) || NUL || CACHE_EPOCH

cache_path

Resolve the on-disk path for a cache entry: <cache_root>/codelore/<repo_hash_8>/<cache_key_16>.duckdb

cache_path_with_root

Same as cache_path but with an explicit root (for --cache-dir override).

cached_bytes

Total bytes of cached fact stores under root, on the same basis prune_global_cache evicts against, so a reported size and the cap it is reported against always measure the same thing.

cleanup_stale_tmp_files

Remove .tmp.<pid> and .tmp.<pid>.wal artifacts in dir that are older than [STALE_TMP_AGE_SECS]. These are left behind by crashed ingest runs (the normal-path rename + drop sequence cleans them up).

default_cache_root

Return dirs::cache_dir() or fall back to a user-namespaced subdir of /tmp when the XDG dirs are unavailable (headless CI, containers, etc.).

prune_global_cache

Walk root/codelore/ and delete .duckdb files (oldest first) until the total directory size falls below max_bytes. Also sweeps stale .tmp.<pid> artifacts across the global cache tree.

prune_repo_cache

Remove .duckdb files from repo_dir beyond max_entries, deleting the oldest (by mtime) first. Also sweeps stale .tmp.<pid> and .tmp.<pid>.wal artifacts left behind by crashed runs.

repo_cache_dir

Compute the per-repo cache subdirectory: <cache_root>/codelore/<repo_hash_8>/