Crate kache_store 

Local artifact storage, independent of compiler parsing and remote transports.

Modules

atomic

config

eviction

Eviction selection, decoupled from the removal mechanism (kunobi-ninja/kache#595).

file_hash

Persistent file fingerprints and opaque compiler memo records.

filesystem

Filesystem identity and physical reclamation.

link

markers

Cross-process advisory and activity markers.

opcounts

Bytes materialized by the store and its consumers.

sharing

Cache reporting policy over shared filesystem measurements.

Structs

ArtifactStore

The local content-addressed store.

BlobIndexDrift

Difference between the derived SQLite blob index and committed entry metadata, which is the store’s authoritative reference graph (#819).

BlobRefcountDrift

Disagreement between the two derived blob tables, read without touching meta.json and without the write lock.

BlobStats

Content-dedup statistics.

CachedFile

CrateHistoryEntry

One prior build of a crate on this machine, from the local store’s index (kunobi-ninja/kache#617). Replaces a bare (key, crate, dir) tuple so the planner can rank by rebuild cost and size.

EntryInfo

EntryMeta

Metadata stored alongside cached artifacts.

EvictionEvidenceCohort

One observation per key: latest live eviction or first shadow-only sweep.

EvictionHorizonEvidence

GcStats

Statistics returned by GC operations.

HousekeepingStats

Counts from [Store::sweep_housekeeping], recorded with the GC run so growth in either structure shows up without a shell on the host.

KeyLockSweepStats

What one [Store::sweep_stale_key_locks] pass saw and did.

MigrationStats

Statistics from a blob migration run.

OrphanSweepStats

Statistics returned by ArtifactStore::sweep_orphan_blobs.

PolicyCost

Evictions one policy made, and the compile time later spent rebuilding the ones the build asked for again (kunobi-ninja/kache#594).

QuarantinedIndexFile

One retained corrupt index file, including WAL/SHM sidecars.

RebuildStats

Outcome of ArtifactStore::rebuild_index_from_store.

RemovalReclaim

Registered blob bytes and blob rows an entry removal released — blobs whose last reference went away, not the entry’s logical size (kunobi-ninja/kache#608). Denominated in blobs TABLE bytes, the same unit as ArtifactStore::physical_size, so eviction’s running budget stays consistent with its trigger; the file unlink itself is best-effort (Windows can defer it), so this is not a guarantee about the disk.

ShadowCounterfactual

The live policy against the value-density shadow over the same sweeps: see [Store::shadow_counterfactual].

ShadowDemandSplit

Post-eviction demand, split by whether the shadow policy agreed with the live one about each evicted entry (kunobi-ninja/kache#594).

StoreLock

Cross-process advisory lock held through an open file handle.

StorePutResult

TrackedTargetRoot

VerifiedRestoredEntry

An entry whose remote bytes and declared artifact hashes were verified in the same pass that extracted them. Construction stays inside the remote transport boundary; the store still re-checks metadata, paths and lengths, but deliberately does not read every artifact a second time.

Enums

BuildClaim

Result of claiming responsibility for a cache miss.

GuardedRemoval

Outcome of removing an entry while holding its compile lock.

SweepOrigin

Who started a sweep. Automatic sweeps (after an upload, on a size hint, the daemon’s timer, the detached worker) keep recent imports; a sweep the user asked for does not, so kache gc can always get back under budget.

VerifyRestores

How aggressively a local cache hit re-hashes its blobs against their content address before serving them, to catch silent on-disk corruption / bit rot / a memo collision before it reaches the compiler as a wrong artifact (kunobi-ninja/kache#332).

Constants

EVICTION_IDLE_GRACE

How recently an entry must have been accessed for eviction to treat it as “pinned by a live build” and skip it (kunobi-ninja/kache#326, #182).

EVICTION_WRITE_PAUSE

How long an eviction sweep stands off the write lock after each EVICTION_WRITE_SLICE, or after it lost the lock to another writer. Longer than the busy handler’s 100 ms poll interval, so every waiting writer polls at least once while the lock is free.

EVICTION_WRITE_SLICE

Write-lock time an eviction sweep may spend on removals before it pauses.

HIT_STAMP_INTERVAL

A hit re-stamps last_accessed only when the previous stamp is at least this old: well inside EVICTION_IDLE_GRACE, so a restore in flight is still pinned, and rare enough that concurrent hits stop contending for the index’s write lock.

IMPORT_PIN

How long an automatic sweep keeps an entry the remote delivered, used or not (kunobi-ninja/kache#1008). A CI job imports a warm set, then runs several cargo commands; an upload between them used to evict whatever the job had not touched for EVICTION_IDLE_GRACE, and the next command downloaded it again or missed. Six hours covers the longest GitHub-hosted job, and bounds how long a long-lived daemon keeps imports nobody used.

KEY_LOCK_SWEEP_CAP

Most key lock files one sweep unlinks. Each costs an open, a lock, two stats and an unlink under gc.lock, tens of microseconds on Linux and a few hundred on macOS and Windows, so a full batch stays within seconds. A store with 84k stale locks converges in five sweeps.

KEY_LOCK_SWEEP_GRACE

How long a key lock file must sit unused before the sweep may unlink it. Every acquisition rewrites the file, so its mtime is the last claim of the key. Holding a key lock spans one compile and BUILD_LOCK_TIMEOUT is ten minutes; an hour, the staging and orphan-blob grace, leaves any claim that is still in flight far behind, and a key untouched that long is not being contended. The sweep also takes the lock before unlinking, so the grace only decides how eagerly idle files go, never whether a holder is safe.

STAGING_SWEEP_GRACE

How long a staging snapshot must sit untouched before a sweep may reclaim it. A snapshot belonging to a put running in another process is indistinguishable from a crash leftover, and unlinking one fails that put at publish time — so the grace has to outlast any plausible in-flight put. Shared by the daemon’s GC sweep and doctor --repair so neither can undercut the other.

TOMBSTONE_RETENTION_DAYS

How long a post-eviction demand record is kept (kunobi-ninja/kache#594).

Traits

ArtifactPolicy

Compiler-owned rules applied when publishing an entry. Implementations must permit shared inodes only for outputs that remain immutable after publication.

Functions

blob_path_in_store_dir

blob_refcount_drift

The probe for any connection to the index, including read-only ones.

is_sqlite_busy_snapshot

is_sqlite_contention

Whether err carries SQLite write contention (SQLITE_BUSY or SQLITE_LOCKED) anywhere in its cause chain. Bad data and I/O errors are not contention; GC counts the two apart.

lock_poll_interval

How long a waiter sleeps before its next try_lock: 1 ms, doubling up to [BUILD_LOCK_POLL_INTERVAL]. A fixed 100 ms poll cost every waiter half of that on each hand-off; in a six-job cold cell that was 350 s of sleep per cell, more than the compiles being waited for.

open_index_db

open_index_db_readonly

Open the index database read-only. No schema work, no WAL/synchronous pragma churn — query_only hard-refuses any accidental write, and the short busy timeout lets a caller skip a figure the index is too busy to answer instead of waiting for it.

open_index_db_reporting_recovery

Like open_index_db, but also reports whether the index had to be recreated from scratch.

quarantined_index_files

List forensic copies without opening or modifying the index. Ordinary GC leaves these copies intact; an explicit full cache clear removes them.

verify_restores_mode

Parse the restore-verification mode from KACHE_VERIFY_RESTORES. Read per call (cheap, off the hot path) so tests can toggle it. Back-compatible: the old boolean 1/true maps to Always, unset/0/false/off to Off.

Type Aliases

GcLock

Lock guard for store-wide GC. Dropping it releases the OS lock.

KeyLock

Lock guard for a cache key. Dropping it releases the OS lock.