Coverage for src/ai_jury/cache.py: 91%

170 statements  

« prev     ^ index     » next       coverage.py v7.16.2, created at 2026-10-20 18:15 +0000

1"""Optional local result cache for repeated jury runs (issue #33). 

2 

3Re-running the jury against an unchanged diff with an unchanged config 

4re-spends time and tokens for an identical result. This module adds an opt-in, 

5on-disk cache keyed by everything that can change the outcome: the diff, the 

6effective config hash, the prompt-template version, the package version, the 

7context policy *and the context text it admits*, and the run seed. 

8 

9Privacy note: a cache entry stores the full structured outcome — including agent 

10review/debate/synthesis text, which is derived from the diff. Treat the cache 

11directory as sensitive (same trust level as the diff itself). The cache is OFF 

12by default and only writes when explicitly enabled with ``--cache``; clear it 

13with ``--clear-cache`` (or ``jury cache clear``). 

14""" 

15 

16from __future__ import annotations 

17 

18import contextlib 

19import hashlib 

20import hmac 

21import json 

22import os 

23import re 

24import secrets 

25import stat 

26import tempfile 

27from dataclasses import asdict 

28from pathlib import Path 

29 

30from . import __version__, prompts 

31from .adapters import AgentResult 

32from .config import JuryConfig, config_hash 

33from .consensus import FindingGroup 

34from .findings import Finding, Verdict 

35from .injection import InjectionHit 

36from .largediff import ChangeIndex 

37from .orchestrator import JuryOutcome 

38 

39#: The record *format* version, bumped when a stored outcome gains a field a 

40#: renderer reads back. 2 (issue #709, round 2): ``AgentResult`` gained 

41#: ``model``, the id the invocation sent, and the ballot reads it to justify 

42#: ``model_source: requested``. An entry written without the field cannot 

43#: support that label — the run that wrote it did not record what it sent — and 

44#: recomputing an id to fill the gap puts a derived value under a token whose 

45#: whole claim is that it came off the wire, which is #709 itself. So such an 

46#: entry is **not read**: a cache exists to be an exact stand-in for a fresh 

47#: run, and where it cannot be, one re-run is the honest price. 

48#: 

49#: The cache *key* does not settle this on its own. It happens to invalidate 

50#: every pre-#709 entry in this release, because ``prompts.PROMPT_VERSION`` went 

51#: 7 → 8 for #710 in the same change — but that is a coincidence of two fixes 

52#: shipping together. Had #709 landed alone the key would have been unchanged 

53#: and every existing entry would have come back a field short. A change to the 

54#: record's format belongs in the field that versions the format. 

55CACHE_SCHEMA = 2 

56_ENV_DIR = "JURY_CACHE_DIR" 

57 

58# Cache files are named `<64-hex sha256>.json` (entries) or 

59# `<64-hex>.json.<rand>.tmp` (in-flight atomic writes). `clear()` only touches 

60# files matching this shape (issue #316/L-3) so it never deletes unrelated files 

61# when JURY_CACHE_DIR points at a shared/populated directory. 

62_CACHE_NAME_RE = re.compile(r"^[0-9a-f]{64}\.json") 

63 

64 

65def default_cache_dir() -> Path: 

66 """Cache directory: ``$JURY_CACHE_DIR`` or ``~/.cache/ai-jury``.""" 

67 override = os.environ.get(_ENV_DIR) 

68 if override: 

69 return Path(override) 

70 base = os.environ.get("XDG_CACHE_HOME") or str(Path.home() / ".cache") 

71 return Path(base) / "ai-jury" 

72 

73 

74def _policy_fingerprint(policy) -> str: 

75 """Stable fingerprint of a review policy for the cache key (issue #122). 

76 

77 Returns "none" for no/empty policy. The policy is maintainer-authored review 

78 guidance injected into the prompts, so it changes the outcome and must be 

79 part of the key. 

80 """ 

81 if policy is None or (hasattr(policy, "is_empty") and policy.is_empty()): 

82 return "none" 

83 from dataclasses import asdict, is_dataclass 

84 

85 data = asdict(policy) if is_dataclass(policy) else policy 

86 return hashlib.sha256(json.dumps(data, sort_keys=True, default=str).encode("utf-8")).hexdigest() 

87 

88 

89def cache_key( 

90 config: JuryConfig, 

91 diff: str, 

92 *, 

93 context: str = "", 

94 hints: str = "", 

95 seed: int | None = None, 

96 mock: bool = False, 

97 policy=None, 

98 mode: str = "code", 

99) -> str: 

100 """Stable cache key for a run. 

101 

102 A pure function of the inputs that determine the outcome. The seed is part of 

103 the key (it changes randomized orchestration), unlike in ``config_hash`` 

104 which describes configuration independent of seed. ``mock`` is included so a 

105 ``--mock`` run (deterministic canned findings) can NEVER be served as a real 

106 review for the same diff+config, and vice versa. ``policy`` (the repository 

107 review policy) is fingerprinted in too, since it is injected into the prompts 

108 and changes the result (issue #122). 

109 

110 ``context`` is the PR context block (issue #738). The *policy* — the mode and 

111 ``redact_secrets`` — was already in the payload, but the text it admits was 

112 not, so under ``--context-mode expanded`` the PR title and body were rendered 

113 into every Round 1 prompt (and read by the injection scanner) while the key 

114 stayed put: editing a PR description, or a third party editing it, changed 

115 what the panel was shown and ``--cache`` replayed the previous outcome. 

116 

117 It is hashed **pre-redaction**, exactly as ``diff`` is: ``run_jury`` redacts 

118 both itself, after this key is computed, so the pre-redaction string is what 

119 every caller has. Two contexts differing only in a secret therefore key 

120 differently even though the panel would see the same redacted text — a 

121 conservative split (one extra run, never a stale hit) and not a leak: what is 

122 stored is a digest, not the text, it never leaves the machine, and a secret 

123 appearing in a PR body is a change to the input this key exists to notice. 

124 ``redact_secrets`` is separately in the payload, so the redaction *policy* 

125 cannot change under a fixed key either. 

126 

127 The digest is present only when the panel will actually be shown context — 

128 ``run_jury`` clears ``context`` under ``diff-only``, the default mode, before 

129 anything reads it. Omitting the field there (rather than hashing ``""``) 

130 keeps the payload byte-identical for every run that sends no context, so no 

131 existing entry is invalidated for a string the panel never saw. Same 

132 precedent as ``[[agent]] adapter`` in ``config_hash`` (#705). 

133 

134 ``hints`` is the static-analysis pre-pass block (issue #745), and it is here 

135 for the reason ``context`` is: it is joined into every Round 1 prompt. The 

136 ``hints`` *flag* was already in ``config_hash`` (#715), but the flag says 

137 only that the linters ran — the block itself is a function of the **working 

138 tree**, not of the diff or the config, so fixing a lint error anywhere in the 

139 tree changed what the panel was shown while every other input to this key 

140 stood still. 

141 

142 Unlike ``context`` it takes no mode filter: ``run_jury`` joins the block into 

143 the Round 1 prompt *after* the ``diff-only`` filter, precisely so the default 

144 context mode cannot discard it (#715), and it is not redacted either. So the 

145 string the caller passes is the string the panel is shown, and hashing it 

146 when it is non-empty — absent otherwise, by the rule above — leaves a run 

147 with ``hints = false``, the default, keyed exactly as it was. 

148 """ 

149 # What ``run_jury`` will hand the panel: nothing under "diff-only". 

150 panel_context = "" if config.context.mode == "diff-only" else context 

151 payload = { 

152 "cache_schema": CACHE_SCHEMA, 

153 "package_version": __version__, 

154 "prompt_version": prompts.PROMPT_VERSION, 

155 "config_hash": config_hash(config), 

156 "diff_sha256": hashlib.sha256(diff.encode("utf-8")).hexdigest(), 

157 "context_mode": config.context.mode, 

158 "redact_secrets": config.context.redact_secrets, 

159 "verify": config.verify, 

160 "seed": seed if seed is not None else config.seed, 

161 "mock": bool(mock), 

162 "policy": _policy_fingerprint(policy), 

163 # Review mode (issue #221): "code" vs "issue" select different prompt 

164 # rubrics, so the same text must never be served across modes. 

165 "mode": mode, 

166 } 

167 if panel_context: 

168 payload["context_sha256"] = hashlib.sha256(panel_context.encode("utf-8")).hexdigest() 

169 if hints: 

170 payload["hints_sha256"] = hashlib.sha256(hints.encode("utf-8")).hexdigest() 

171 blob = json.dumps(payload, sort_keys=True, separators=(",", ":")) 

172 return hashlib.sha256(blob.encode("utf-8")).hexdigest() 

173 

174 

175def _finding(d: dict) -> Finding: 

176 return Finding( 

177 severity=d.get("severity", "info"), 

178 file=d.get("file", ""), 

179 claim=d.get("claim", ""), 

180 line=d.get("line"), 

181 evidence=d.get("evidence", ""), 

182 suggested_fix=d.get("suggested_fix", ""), 

183 confidence=d.get("confidence", "medium"), 

184 reviewer=d.get("reviewer", ""), 

185 origin=d.get("origin", "unclear"), 

186 ) 

187 

188 

189def _verdict(d: dict) -> Verdict: 

190 return Verdict( 

191 file=d.get("file"), 

192 line=d.get("line"), 

193 claim=d.get("claim", ""), 

194 status=d.get("status", "needs_human_decision"), 

195 reasoning=d.get("reasoning", ""), 

196 ) 

197 

198 

199def _agent_result(d: dict | None) -> AgentResult | None: 

200 if d is None: 

201 return None 

202 return AgentResult( 

203 agent=d["agent"], 

204 vendor=d["vendor"], 

205 ok=d["ok"], 

206 output=d["output"], 

207 duration_s=d["duration_s"], 

208 error=d.get("error"), 

209 findings=[_finding(f) for f in d.get("findings", [])], 

210 warnings=list(d.get("warnings", [])), 

211 error_code=d.get("error_code"), 

212 attempts=d.get("attempts", 1), 

213 # The id the invocation sent (#709). Restored so a cached ballot quotes 

214 # the same string a fresh one does — the cache key already pins the 

215 # config, so the id cannot have been anything else. The default is for a 

216 # dict that never came from a cache entry (`jury replay` takes any 

217 # `outcome_to_dict` dump): a stored entry missing the field is refused 

218 # by `CACHE_SCHEMA` before it reaches here, rather than balloting a 

219 # recomputed id under a label that claims it was sent. 

220 model=d.get("model", ""), 

221 ) 

222 

223 

224def _group(d: dict) -> FindingGroup: 

225 return FindingGroup( 

226 representative=_finding(d["representative"]), 

227 reviewers=list(d.get("reviewers", [])), 

228 severity=d.get("severity", "info"), 

229 members=[_finding(m) for m in d.get("members", [])], 

230 bucket=d.get("bucket", "single_reviewer"), 

231 status=d.get("status", ""), 

232 status_reasoning=d.get("status_reasoning", ""), 

233 ) 

234 

235 

236def _hit(d: dict) -> InjectionHit: 

237 return InjectionHit( 

238 kind=d.get("kind", ""), 

239 source=d.get("source", ""), 

240 line=d.get("line"), 

241 snippet=d.get("snippet", ""), 

242 ) 

243 

244 

245def _change_index(d: dict | None) -> ChangeIndex | None: 

246 """Rebuild a :class:`ai_jury.largediff.ChangeIndex`, or None for a legacy entry.""" 

247 if not isinstance(d, dict): 

248 return None 

249 return ChangeIndex( 

250 paths=tuple(d.get("paths") or ()), 

251 symbols=tuple(d.get("symbols") or ()), 

252 ) 

253 

254 

255def outcome_to_dict(outcome: JuryOutcome) -> dict: 

256 """Serialize a JuryOutcome to a JSON-safe dict (dataclasses all the way down).""" 

257 return asdict(outcome) 

258 

259 

260def outcome_from_dict(data: dict) -> JuryOutcome: 

261 """Rebuild a JuryOutcome from :func:`outcome_to_dict` output.""" 

262 return JuryOutcome( 

263 reviews=[_agent_result(r) for r in data.get("reviews", [])], 

264 debate=[_agent_result(r) for r in data.get("debate", [])], 

265 synthesis=_agent_result(data.get("synthesis")), 

266 chair=data.get("chair", ""), 

267 findings=[_finding(f) for f in data.get("findings", [])], 

268 warnings=list(data.get("warnings", [])), 

269 groups=[_group(g) for g in data.get("groups", [])], 

270 verify=_agent_result(data.get("verify")), 

271 verdicts=[_verdict(v) for v in data.get("verdicts", [])], 

272 context_mode=data.get("context_mode", "diff-only"), 

273 redact_secrets=data.get("redact_secrets", True), 

274 redaction_count=data.get("redaction_count", 0), 

275 injection_hits=[_hit(h) for h in data.get("injection_hits", [])], 

276 skipped=[tuple(s) for s in data.get("skipped", [])], 

277 budget_exhausted=data.get("budget_exhausted", False), 

278 rounds_executed=data.get("rounds_executed", 1), 

279 stop_reason=data.get("stop_reason", ""), 

280 from_cache=data.get("from_cache", False), 

281 # What the change contained (#710). The cache key already pins the diff 

282 # by digest, so a restored index describes the same bytes as the run 

283 # that wrote it; a legacy entry has none and the scope rule falls back. 

284 changed=_change_index(data.get("changed")), 

285 # Files kept out of the review (#978). The key hashes the whole diff, binary 

286 # segments included, so an entry always matches the exclusions it stored. 

287 excluded_files=[tuple(e) for e in data.get("excluded_files", [])], 

288 # The routing record rides along like every other field (#714). An 

289 # entry written before this key existed is restored as the standard 

290 # record naming the seats it holds, which is what those runs did: the 

291 # panel was never trimmed. That is truthful without invalidating a 

292 # single cache entry — `routing` and every seat's `tier` are already in 

293 # `config_hash`, so a plan that would route differently has a different 

294 # key and cannot hit an old entry at all. 

295 routing=dict(data["routing"]) 

296 if data.get("routing") 

297 else { 

298 "mode": "standard", 

299 "risk": "", 

300 "panel": [r.get("agent", "") for r in data.get("reviews", [])], 

301 "benched": [], 

302 "anchor": None, 

303 "reason": "standard routing", 

304 "escalated": False, 

305 "escalation_reason": "", 

306 }, 

307 ) 

308 

309 

310_HMAC_KEY_FILE = ".hmac_key" 

311 

312# Upper bound on a cache entry read before MAC verification (issue #303/L-5). A 

313# jury outcome is small (a few KB); reject a multi-MB file so an attacker-planted 

314# giant entry can't be fully parsed into memory before the MAC rejects it. 

315_MAX_CACHE_BYTES = 8 * 1024 * 1024 

316 

317 

318def _dir_is_untrusted(directory: Path) -> bool: 

319 """True when ``directory`` is group/other-writable (issue #295). 

320 

321 A world-/group-writable cache dir lets another local user plant entries (and 

322 even swap the HMAC key file), so we fail closed rather than trust it. POSIX 

323 only — Windows ACLs are not represented in ``st_mode``, so the check is 

324 skipped there. 

325 """ 

326 if os.name == "nt": 326 ↛ 327line 326 didn't jump to line 327 because the condition on line 326 was never true

327 return False 

328 try: 

329 mode = directory.stat().st_mode 

330 except OSError: 

331 return False 

332 return bool(mode & (stat.S_IWGRP | stat.S_IWOTH)) 

333 

334 

335def _hmac_key(directory: Path) -> bytes | None: 

336 """Return the per-user cache MAC secret, creating it 0o600 on first use. 

337 

338 The key lives in ``<cache_dir>/.hmac_key`` readable only by the owner, so a 

339 forged entry can't carry a valid MAC unless the attacker can read the secret 

340 (blocked by 0o600) or replace it (blocked by ``_dir_is_untrusted``). Returns 

341 None if the secret can't be read/created, in which case callers skip MACing. 

342 """ 

343 key_path = directory / _HMAC_KEY_FILE 

344 with contextlib.suppress(OSError): 

345 return key_path.read_bytes() 

346 # Not present (or unreadable) — try to create it atomically, owner-only. 

347 try: 

348 fd = os.open(str(key_path), os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600) 

349 except FileExistsError: 

350 # Lost a race with a concurrent writer; read what they wrote. 

351 try: 

352 return key_path.read_bytes() 

353 except OSError: 

354 return None 

355 except OSError: 

356 return None 

357 try: 

358 key = secrets.token_bytes(32) 

359 with os.fdopen(fd, "wb") as handle: 

360 handle.write(key) 

361 return key 

362 except OSError: 

363 return None 

364 

365 

366def _canonical(entry: dict) -> str: 

367 """Deterministic serialization of an entry (minus its ``mac``) for MACing.""" 

368 return json.dumps( 

369 {k: v for k, v in entry.items() if k != "mac"}, 

370 separators=(",", ":"), 

371 sort_keys=True, 

372 ) 

373 

374 

375def _compute_mac(key: bytes, entry: dict) -> str: 

376 return hmac.new(key, _canonical(entry).encode("utf-8"), hashlib.sha256).hexdigest() 

377 

378 

379class Cache: 

380 """A simple on-disk JSON cache of jury outcomes.""" 

381 

382 def __init__(self, directory: Path | str | None = None): 

383 self.dir = Path(directory) if directory else default_cache_dir() 

384 

385 def _path(self, key: str) -> Path: 

386 return self.dir / f"{key}.json" 

387 

388 def load(self, key: str) -> JuryOutcome | None: 

389 """Return the cached outcome for ``key`` (marked ``from_cache``), or None. 

390 

391 A corrupt or unreadable entry is treated as a miss rather than an error, 

392 so a bad cache file never breaks a run. 

393 """ 

394 path = self._path(key) 

395 if not path.exists(): 

396 return None 

397 # Fail closed: never trust an entry read from a world/group-writable dir 

398 # (issue #295) — an attacker who can write the dir can forge entries. 

399 if _dir_is_untrusted(self.dir): 

400 return None 

401 try: 

402 # Size-cap the READ itself (issue #303/L-5, review): read at most 

403 # _MAX_CACHE_BYTES+1 chars rather than stat-then-read (which is a 

404 # TOCTOU and still reads the whole file). A giant attacker-planted 

405 # entry is rejected without being pulled into memory. 

406 with path.open("r", encoding="utf-8") as fh: 

407 raw = fh.read(_MAX_CACHE_BYTES + 1) 

408 if len(raw) > _MAX_CACHE_BYTES: 

409 return None 

410 data = json.loads(raw) 

411 except (OSError, ValueError, RecursionError): 

412 # RecursionError on deeply nested JSON is not a ValueError; catch it 

413 # so a planted entry can't crash the fail-closed read (audit 

414 # 2026-06-13 r3, mirrors findings.py). 

415 return None 

416 if data.get("cache_schema") != CACHE_SCHEMA: 

417 return None 

418 # Integrity: the entry must name the key it was written for (issue 

419 # #293/F-10). A file dropped at <digest>.json with mismatched content 

420 # (e.g. a forged verdict copied from another key) is treated as a miss. 

421 if data.get("cache_key") != key: 

422 return None 

423 # Integrity: verify the per-user HMAC (issue #295). Fail closed — if the 

424 # key can't be read/created we cannot authenticate the entry, so treat it 

425 # as a miss rather than trusting an unsigned blob. A missing or wrong MAC 

426 # (a forgery, or a legacy pre-MAC entry) is likewise a miss. 

427 mac_key = _hmac_key(self.dir) 

428 if mac_key is None: 

429 return None 

430 stored_mac = data.get("mac") 

431 if not isinstance(stored_mac, str) or not hmac.compare_digest( 

432 stored_mac, _compute_mac(mac_key, data) 

433 ): 

434 return None 

435 outcome = outcome_from_dict(data.get("outcome", {})) 

436 outcome.from_cache = True 

437 return outcome 

438 

439 def store(self, key: str, outcome: JuryOutcome) -> None: 

440 """Persist ``outcome`` under ``key`` (best-effort; ignores write errors).""" 

441 with contextlib.suppress(OSError): 

442 # Owner-only cache dir so another local user cannot plant entries 

443 # (issue #293/F-10); best-effort tighten if it already exists. 

444 self.dir.mkdir(parents=True, exist_ok=True, mode=0o700) 

445 with contextlib.suppress(OSError): 

446 self.dir.chmod(0o700) 

447 # Fail closed (#295): we just tried to tighten the dir to 0700. If it 

448 # is STILL group/other-writable, the chmod failed (we don't own it) — 

449 # an attacker could swap entries or the MAC key, so refuse to write 

450 # rather than trust it (the audit's "don't suppress and continue"). 

451 if _dir_is_untrusted(self.dir): 

452 return 

453 payload = { 

454 "cache_schema": CACHE_SCHEMA, 

455 "cache_key": key, 

456 "outcome": outcome_to_dict(outcome), 

457 } 

458 # Fail closed (#295): if we can't obtain the MAC key, do NOT write an 

459 # unsigned entry — an unsigned blob would be accepted as trusted only 

460 # if MACing were optional, which it is not. Skip caching instead. 

461 mac_key = _hmac_key(self.dir) 

462 if mac_key is None: 

463 return 

464 payload["mac"] = _compute_mac(mac_key, payload) 

465 # Atomic write (issue #303/L-4, hardened in #316/L-4): mkstemp gives a 

466 # UNIQUE name created with O_EXCL and no symlink-follow — safe against 

467 # same-PID/thread concurrency and a pre-planted temp symlink — then an 

468 # atomic replace. A crash mid-write can't leave a truncated entry and 

469 # a reader never sees a partial file. 

470 path = self._path(key) 

471 blob = json.dumps(payload, separators=(",", ":")) + "\n" 

472 fd, tmp_name = tempfile.mkstemp(dir=self.dir, prefix=f"{path.name}.", suffix=".tmp") 

473 tmp = Path(tmp_name) 

474 try: 

475 with os.fdopen(fd, "w", encoding="utf-8") as handle: 

476 handle.write(blob) 

477 tmp.replace(path) 

478 except OSError: 

479 with contextlib.suppress(OSError): 

480 tmp.unlink() 

481 raise # caught by the outer contextlib.suppress(OSError) 

482 

483 def clear(self) -> int: 

484 """Remove all cache entries; return the number deleted. 

485 

486 Also rotates (deletes) the per-user MAC key (issue #303/L-3) so a clear 

487 after a suspected compromise starts fresh; the count covers only the 

488 ``*.json`` entries. 

489 """ 

490 if not self.dir.exists(): 

491 return 0 

492 removed = 0 

493 # Only touch files matching the cache-name shape (#316/L-3) so a clear on 

494 # a shared JURY_CACHE_DIR never deletes unrelated files. Entries 

495 # (`<hex>.json`) count; leftover atomic-write temps (`<hex>.json.*.tmp`) 

496 # are reaped but not counted. 

497 for path in self.dir.glob("*.json"): 

498 if _CACHE_NAME_RE.match(path.name): 

499 with contextlib.suppress(OSError): 

500 path.unlink() 

501 removed += 1 

502 for tmp in self.dir.glob("*.tmp"): 

503 if _CACHE_NAME_RE.match(tmp.name): 503 ↛ 504line 503 didn't jump to line 504 because the condition on line 503 was never true

504 with contextlib.suppress(OSError): 

505 tmp.unlink() 

506 with contextlib.suppress(OSError): 

507 (self.dir / _HMAC_KEY_FILE).unlink() 

508 return removed