# Behavioral Impact

> Tunacode uses a strict cache registry (CacheManager) plus typed cache accessors as the only supported public boundary for cache reads/writes.

- Skill: `tools-only/behavioral-impact-2` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/behavioral-impact-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/behavioral-impact-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-29
- Page: https://skillmd.com/skills/tools-only/behavioral-impact-2

---


## Summary

Tunacode uses a strict cache registry (`CacheManager`) plus *typed cache accessors* as the only supported public boundary for cache reads/writes. This removes ad-hoc module-level dict caches, enforces fail-fast behavior for unregistered caches, and makes invalidation strategies (manual vs mtime-driven) testable and deterministic.

## Context

Implemented as part of epic `tun-gqgx` (cache unification). The initial migration targets:
- agent reuse + versioning (`agent_config.py`)
- `AGENTS.md` project context loading
- `.gitignore`-driven ignore manager caching

## Changes

- Added `tunacode.infrastructure.cache`:
  - `CacheManager` singleton with explicit `register_cache()` and strict `get_cache()` (raises if missing)
  - per-cache key metadata (`set_metadata`/`get_metadata`)
  - strategies:
    - `ManualStrategy`: never auto-invalidates
    - `MtimeStrategy`: invalidates when `os.stat(metadata.path).st_mtime_ns != metadata.mtime_ns` (missing file treated as `mtime_ns=0`)
  - deterministic `clear_all()`/`clear_cache()` helpers for tests

- Added typed accessor modules under `tunacode.infrastructure.cache.caches/`:
  - `agents.py`: version-aware get/set/invalidate/clear
  - `tunacode_context.py`: mtime-aware `get_context(path: Path) -> str`

- Added typed accessor modules under `tunacode.tools.cache_accessors/`:
  - `ignore_manager_cache.py`: mtime-aware `get_ignore_manager(root: Path) -> IgnoreManager`
  - `ripgrep_cache.py`: manual cache for platform identifier + binary path
  - `xml_prompts_cache.py`: mtime-aware XML prompt caching (including cached None)

## Behavioral Impact

- No module should expose cache dicts as globals or import them in tests.
- Call sites should import accessors (e.g. `tunacode.infrastructure.cache.caches.agents`) and avoid touching `CacheManager` directly.
- Tests should clear caches via `tunacode.infrastructure.cache.clear_all()` or per-accessor `clear_*()` helpers (no singleton reset).

## Related Cards

- [[cache]]