Module cache 

LiveCache — the M1 cache surface that the MCP server consumes.

Keying philosophy: every cache entry is keyed by a deterministic blake3 hash of the tool’s inputs, where “inputs” includes any file content the tool’s output is a function of. The store payload is the exact formatted bytes the MCP tool fed back to the model on the first execution. A subsequent identical call hits when (a) the input hash matches AND (b) every recorded file root revalidates clean against the current filesystem. If either fails, the entry is treated as invalid and the registered metadata is removed so a stale entry does not linger. M1 keeps the registry in memory; M2 will persist it.

The cache surface is deliberately tool-agnostic: callers compute the input bytes (we provide canonicalization helpers in key), invoke lookup or lookup_revalidate, and on miss they execute the real tool and call persist. The cache does not run tools itself; that lives one layer up in verdant-mcp.

Structs

FileRoot

One file dependency of a cache entry. The tool computed its output as a function of (path, contents at expected_hash). On every green hit we re-blake3 the file and require the hash to still match; if it does not, the entry is invalidated.

LiveCache

Enums

CacheError

FileHash

Outcome of fingerprinting a file for cache keying.

LookupOutcome

Constants

STAT_PREFIX

Functions

fingerprint_file

Fingerprint a read-set file: content-hash it if it is at or below content_max (sound), otherwise fall back to a size+mtime fingerprint so a huge stable input does not block caching or cost a full re-read on every validation. The returned string is what revalidate_file_roots recomputes and compares; its form (bare hex vs stat: prefix) tells revalidation which mode to use.

hash_file

blake3 hex digest of the file at path, streamed so memory stays bounded regardless of file size. Always content-hashes; callers that must not cache oversized files use hash_file_with_limit instead.

hash_file_with_limit

Fingerprint path for cache keying. A file at or below max bytes is content-hashed; a larger file is reported Oversized so the caller declines to cache rather than keying on a collision-prone fingerprint.

hash_max_bytes

The content-hash ceiling, read from $VERDANT_HASH_MAX_BYTES if set and parseable, otherwise HASH_MAX_BYTES.

stat_fingerprint

A cheap size+mtime fingerprint for a file, used for large/stable inputs (compilers, system libraries) that would be prohibitively expensive to content-hash on every cache validation. Soundness assumption: identical (size, nanosecond mtime) implies identical content, the same assumption build tools already make for their own incrementality.

tool_result_key

Content-addressed identity of a tool result. The MCP tool layer registers a node under this key carrying the file roots the result depended on, and the proxy records the same key as an upstream edge of any LLM call whose prompt embedded that result, so editing one of those files cascades file -> this node -> the dependent completions. Both layers must hash identically, so the function lives here in the shared runtime crate.