feat: optional result cache (off by default, never persists keys) — closes #6

[ernestprovo23]

Summary

Implements issue #6 / PDD §9 #4: an opt-in result cache keyed on (prompt, council, mode, model ids) so repeated and eval runs are cheap. Off by default. Never persists API keys.

Behavior

• Off by default. No caching unless explicitly opted in (config cache: true or --cache).
• Opt-in two ways, mirroring existing config+CLI wiring:
  • config field cache: bool = False on ConclaveConfig
  • CLI flag --cache/--no-cache (default unset → defers to config)
  • Council(..., cache: bool | None = None) — explicit arg overrides config
• Cache hit returns the prior CouncilResult with new field cached=True and does not call the providers.
• Wired into ask (synthesize/raw), debate, and adversarial.

Cache key

SHA-256 over a canonical JSON document of only output-affecting, secret-free identity:
normalized prompt · mode · ordered (friendly_name, resolved_model_id) member pairs · synthesizer/judge name + resolved id · temperature · rounds (debate) · proposer (adversarial).

Member order is preserved, not sorted: for synthesize/raw order is irrelevant, but debate assigns letter labels by position and adversarial defaults the proposer to the first member — so preserving order is the conservative, always-correct choice.

Storage

One JSON file per entry under $XDG_CACHE_HOME/conclave (else ~/.cache/conclave), written atomically (temp + replace). Payload is CouncilResult.model_dump(mode="json") — no secrets. A corrupt/unreadable entry is a miss (logged), never a crash; write failures degrade to a live run. call_model's never-raises invariant and the BYO-keys posture are untouched.

Security

The only os.environ access in cache.py is XDG_CACHE_HOME (a path). No key value or env-var name reaches the cache key or the stored payload. A dedicated test sets a fake key and asserts it appears in neither the key string nor the on-disk artifact.

Tests

• Off by default → both identical runs execute, no file written
• On → first miss populates, second identical run is a hit with zero new provider calls (call-counter on the patched path)
• Key sensitivity → changing prompt / council membership / mode / resolved model id all miss
• Security → fake key absent from key + persisted payload + filename
• Corrupt entry → miss, run completes, no crash, entry rewritten
• Write/path failure → degrades to live run
• CLI --cache / --no-cache end-to-end
• Direct make_key unit checks (determinism, order-sensitivity, whitespace normalization)

142 tests pass (126 before → +16), ruff check clean, ruff format --check clean.

Files

src/conclave/cache.py (new), src/conclave/{models,config,council,cli}.py, tests/test_cache.py (new), tests/test_cli.py, README.md, config.example.yml.

Do not merge — orchestrator reviews and merges.