Module cache 

Disk-backed OAuth usage cache + lock file.

Two storage layers per docs/specs/data-fetching.md §OAuth usage cache stack:

• CacheStore — usage.json holds either the last endpoint response (CachedData) or a tag-only error record (CachedError), stamped with schema_version + cached_at. The orchestrator compares cached_at against usage.cache_duration to decide freshness.
• LockStore — usage.lock holds a blocked_until Unix timestamp that prevents concurrent linesmith processes from stampeding the endpoint under 429 backoff.

Both writes go through atomic_write_json: write to a sibling tempfile, then rename over the target. tempfile::NamedTempFile:: persist is rename-on-Unix and MoveFileEx with MOVEFILE_REPLACE_EXISTING on Windows — atomic at the filesystem level on both platforms.

Structs

CacheStore

Reader/writer for usage.json.

CachedData

Disk-serializable mirror of UsageApiResponse. The wire shape uses #[serde(flatten)] for unknown_buckets so codenamed keys appear at the top level of the endpoint response. The cache nests them under a named unknown_buckets key so the outer CachedUsage wrapper’s fields (schema_version, cached_at, etc.) don’t collide with endpoint-emitted keys like five_hour.

CachedError

On-disk error record. Intentionally lossy — carries only the UsageError::code tag, not the full Rust enum. Live errors from the current process take precedence over cached ones; the cache is just for cross-invocation hints.

CachedUsage

Single cache-file entry. Writers produced via Self::with_data or Self::with_error keep exactly one of data/error null per docs/specs/data-fetching.md §OAuth usage cache stack. Readers tolerate any combination (both null, both populated) and treat anomalies as misses at the orchestrator layer rather than erroring at parse time.

Lock

On-disk lock file shape. blocked_until is a signed Unix timestamp in seconds — i64 wide enough for any plausible Unix time, signed so the mtime + LEGACY_LOCK_TTL_SECS arithmetic used by the legacy path can’t underflow.

LockStore

Reader/writer for usage.lock.

Enums

CacheError

Cache-layer I/O / parse failures. Distinct from [UsageError] because cache-miss variants collapse to Ok(None) in CacheStore::read; CacheError carries only the cases that indicate a real problem (filesystem error on write, inability to create the parent dir).

Constants

CACHE_SCHEMA_VERSION

Cache schema version. Bump when the on-disk shape changes in a way that can’t be read by an older linesmith — readers with a mismatched version treat the file as a miss per docs/specs/data-fetching.md §Schema versioning.

Functions

atomic_write_json

Write a JSON-serializable value to path atomically: serialize into a sibling tempfile, then persist (rename on Unix, MoveFileEx on Windows). The parent directory is created on demand; a concurrent writer will always see either the old file or the new one, never a torn write.

default_root

Locate the linesmith cache root. Returns None in environments that provide neither $XDG_CACHE_HOME nor $HOME. Delegates to xdg::resolve_subdir; the from_process_env factory uses var_os so non-UTF-8 paths (Unix byte-string paths) survive through to the cache reader.