Module cache 

Sidecar narrative cache for the advisory enrichment layer.

A generated narrative is expensive (a model round-trip) and deterministic in its inputs, so each one is persisted next to the fact-store cache as a small JSON sidecar. The cache key is the SHA-256 of the fact-sheet text joined with the schema version, the prompt version, and the model id: change any of them and the key changes, so the cached narrative text is never stale for new evidence, a re-worded prompt, or a different model. Its stored groundedness verdict is a separate matter — a warm read recomputes it from the cached narrative (see engine::narrate), so an improved citation checker reaches warm caches without a regeneration.

The key is rendered as plain lowercase hex — no sha256: prefix — because it becomes a filename, and a : is not a legal path component on Windows. The cache is strictly best-effort: a missing entry is an ordinary miss, a corrupt entry is logged and treated as a miss, and a failed write is logged and swallowed. Nothing here can fail a run.

Structs

CachedNarrative

A cached advisory narrative plus the provenance a caller needs to decide whether it still describes the current evidence.

Functions

cache_key

The cache key for a narrative: lowercase-hex SHA-256 of "{fact_sheet_text}|{SCHEMA_VERSION}|{PROMPT_VERSION}|{model}".

cache_path

The on-disk path for the narrative keyed by key: repo_cache_dir(cache_root, repo_path)/enrichment/<key>.json.

latest_for_subject

The newest cached narrative for subject in this repo by created_at, or None when no readable entry describes that subject.

read

Read the cached narrative at key, or None when it is absent or corrupt.

write

Write entry to the sidecar for key, creating the enrichment cache directory if needed.