--- name: audit-sibling-divergence description: Differential audit comparing matched code paths that should behave identically. Spawns one auditor per sibling pair (sync/async, bounded/unbounded, view consistency, bulk vs single, generated node variants, read fast vs slow, adapter conformance) and requires a concrete witness scenario where the two paths diverge observably. context: fork disable-model-invocation: true allowed-tools: Read, Grep, Glob, Bash, Agent, Write --- # Audit: Sibling Divergence The existing snapshot audits look at one code path and ask "is it correct?" This audit looks at TWO paths that should produce the same observable result and asks "do they actually agree?" Divergence between matched paths is a confirmed historical bug pattern in Caffeine (refresh+expiration sync/async asymmetry, weak/strong publication differences, fast-path/slow-path disagreement under contention). ## When to run - After significant changes to BoundedLocalCache, LocalAsyncCache, or any generator under `caffeine/src/javaPoet/java/`. - After changes to the user-facing adapters (`jcache/src/main`, `guava/src/main`): their write/expiry/exception-translation paths are sibling families with each other AND with the external spec/reference they claim to match (Group G). This is where the audit's highest-yield gap was — adapters are user-facing yet were never in any audit's scope. - Before a major release as a defense against silent sync/async drift. - Once per quarter as a baseline audit. Heavyweight (4-6h of agent time). Token-intensive. Do not run for routine pre-commit review (use `/review-change` for that). ## Step 1: Inventory matched pairs The priority matched pairs are listed below. Before launching, glance at the codebase to confirm each pair is still present and add any new pairs (e.g., a new view, a new feature with sync+async variants): **Group A — sync vs async cache** (highest historical bug yield) - A1: `Cache.get(k, Function)` vs `AsyncCache.get(k, BiFunction)` — load semantics, listener delivery, refresh hand-off - A2: `LoadingCache.refresh(k)` vs `AsyncLoadingCache.refresh(k)` — completion, exception, stale-detection - A3: `Cache.asMap().compute*` vs `AsyncCache.asMap().compute*` — atomicity, listener cause, weight delta - A4: `Cache.invalidate*` vs `AsyncCache.synchronous().invalidate*` — listener cause, in-flight value handling **Group B — storage variants** - B1: BoundedLocalCache vs UnboundedLocalCache for shared map operations (most ops are inherited; check overridden ones and the inherited ones that reference eviction-only fields) - B2: Generated Node variants (`PS`, `FS`, `PW`, `FW`, `PSAW`, `PSWMS`, etc.) — for each method declared in `Node.java` that has multiple subclass implementations, verify all subclasses use consistent access modes, lifecycle transitions, and weight discipline **Group C — view consistency** - C1: `keySet().contains(k)` vs `containsKey(k)` vs `asMap().get(k) != null` - C2: `values().contains(v)` vs `containsValue(v)` - C3: `entrySet()` iteration vs `forEach()` vs `keySet()` + `get(k)` per key - C4: `size()` vs `entrySet().size()` vs counting via iterator - C5: `keySet().remove(k)` / `entrySet().remove(entry)` vs the corresponding map removal — mapping outcome, blocking, and pending-load disposition, accounting for different return contracts **Group D — bulk vs single-key** - D1: `getAllPresent(keys)` vs N×`getIfPresent(k)` - D2: `getAll(keys, loader)` vs N×`get(k, loader)` - D3: `putAll(m)` vs N×`put(k, v)` - D4: `invalidateAll(keys)` vs N×`invalidate(k)` - D5: `invalidateAll()` vs `invalidateAll(allKeys())` **Group E — equivalent-by-construction** - E1: `LoadingCache.get(k)` vs `Cache.get(k, cacheLoader::load)` - E2: `getOrDefault(k, d)` vs `(get(k) == null ? d : get(k))` (ignoring atomicity) - E3: `putIfAbsent(k, v)` vs `compute(k, (key, val) -> val == null ? v : val)` - E4: `AsyncCache.synchronous()` view vs an equivalent sync `Cache` built with the same configuration **Group F — internal paths to the same outcome** - F1: Read fast path (`getIfPresent` optimistic) vs slow path (under `synchronized(node)`) — same key, same logical time, must agree on present-ness and value identity - F2: Eviction listener (sync) vs Removal listener (async) for an evicted entry — both should fire, with consistent key/value/cause and the same set of entries - F3: Maintenance task variants (`AddTask`, `UpdateTask`, `RemovalTask`, `RemovedTask`) — weight delta sign convention, telescoping sum preservation across task orderings **Group G — adapter conformance** (user-facing: `jcache/`, `guava/`) - G1: JCache write-path family — every path that builds an `Expirable` and gates on `ExpiryPolicy` must agree on the create/update guard, the put statistic, and the CREATED/UPDATED/EXPIRED events: `put`/`putAll` (`putNoCopyOrAwait`), `putIfAbsent` (`putIfAbsentNoAwait`), `getAndPut`, `replace`, and the `EntryProcessor` `postProcess` CREATED/UPDATED/LOADED cases. (A zero-creation-expiry guard present in the put helpers but missing from `postProcess` was a real bug — a phantom CREATED event + put stat.) - G2: JCache adapter vs reference — for each spec-ambiguous edge the TCK does NOT pin (zero/eternal/null creation & update expiry, loader-exception wrapping, read-through statistics), compare the adapter's observable outcome against the JSR-107 RI and ≥3 ecosystem impls (Ehcache3, Infinispan, Hazelcast, Coherence, cache2k). The spec is the contract; the RI + majority resolve ambiguity. A green TCK is necessary, not sufficient — it is silent on exactly the paths that drift. - G3: Guava facade vs underlying Caffeine — each `CaffeinatedGuavaCache` / facade-view method vs the Caffeine method it delegates to: null-query tolerance, exception translation (`InvalidCacheLoadException` / `ExecutionException` / `UncheckedExecutionException` / `ExecutionError` by checked-ness), bulk partial results. - G4: Guava facade vs real Guava — the executable oracle for G3: run the SAME guava-testlib suite (matched feature flags) and operation sequences against the facade and a real Guava `CacheBuilder` cache; adjudicate differences against Guava's contract and the accepted facade limits. If a new feature has a sync and async variant not listed above, add it as group H before launching. When auditing the simulator, add reader-vs-sibling-reader (shared binary/text formats, e.g. the libCacheSim family) and climber-vs-climber (shared gradient/timestep convention) port pairs as a group — lower priority, since simulator divergence yields misleading benchmark numbers rather than user-facing bugs. Sim-internal pairs only: the production `WindowClimber` deliberately has NO faithful simulator reference (`product.Caffeine`, the real cache, is the arbiter) — do not flag sim-reference-vs-production divergence as a finding. ## Step 2: Spawn parallel differential auditors Launch one subagent per group (seven groups → seven parallel agents). Each agent gets the prompt below, adapted to its group. Run them in a single message so they execute in parallel. Tell each subagent to write its report to a group-suffixed path (`.local/audits//audit-sibling-divergence-group.md`), never to the canonical `audit-sibling-divergence.md` — that path is reserved for the orchestrator's consolidated report (Step 5), and parallel groups writing it clobber each other. If a group returns its report inline instead, persist it to the group-suffixed path before launching that group's evaluator. ``` You are auditing the Caffeine cache for sibling divergence: cases where two code paths that should produce identical observable behavior do not. YOUR GROUP: The Caffeine source code is at: - Core: caffeine/src/main/java/com/github/benmanes/caffeine/cache/ - Generated: caffeine/build/generated/sources/ (run `./gradlew :caffeine:generateNodes :caffeine:generateLocalCaches` if empty) - Generators: caffeine/src/javaPoet/java/com/github/benmanes/caffeine/cache/ - Adapters (Group G): guava/src/main/java/com/github/benmanes/caffeine/guava/ and jcache/src/main/java/com/github/benmanes/caffeine/jcache/. For G2/G4 the reference contract is external — the JSR-107 1.1.1 spec/TCK and a real Guava `CacheBuilder` cache; construct the witness as a differential test (run both sides), not a read alone. To read Guava's actual behavior (no clone needed), WebFetch a specific method from `https://raw.githubusercontent.com/google/guava/master/guava/src/com/google/common/cache/LocalCache.java` — the source-level complement to G4's executable oracle; the executable side must use the pinned Guava version (`libs.versions.toml`), not master. # Phase 0: Plan For each pair in your group: - State the contract the two paths jointly promise (what does an observer see when they call A vs B?). - Predict the 2-3 most likely categories of divergence (different access mode, different listener cause, different exception handling, ordering of notifications, in-flight value visibility, weight accounting, etc.). - For blocking differences, identify which thread completes the awaited work. If executor capacity affects progress, compare one explicitly sized executor with a spare-worker control; distinguish application dependency cycles from a violated cache progress guarantee. # Phase 1: Trace each side For each pair: 1. Locate both implementations. Read each end to end (not just the diff). 2. Build a side-by-side table of the observable steps each path takes: field reads/writes (with access mode), lock acquisitions, listener invocations, exceptions thrown, return values. 3. Identify every step where the two paths differ. For each difference: - Is the difference observable to a caller? - Is it explained by an intentional design decision? (read .claude/docs/design-decisions.md and .claude/rules/design-decisions.md ONLY AFTER you have recorded the difference — design context causes premature dismissal) - If observable and unexplained, this is a candidate finding. # Phase 2: Construct a witness For each candidate finding, construct a CONCRETE WITNESS: - Cache configuration (size, weigher, listener, expiry, ...) - Exact sequence of method calls - Expected observation if the paths agreed - Actual observation given the divergence - Strong enough that a developer could write a failing unit test from it without further investigation. A finding without a concrete witness is NOT acceptable — drop it. # Phase 3: Self-challenge For each finding, attempt to refute it by re-reading the source. If you can construct a path through the code that resolves the divergence (e.g., the second path also fires the listener through a different route you missed), drop the finding. Be ruthless — the user wants high-precision findings, not volume. For differing guards, compare reachable callers and preconditions on both paths. One path may establish the condition elsewhere or never reach the guarded state; its safety does not make the other path's guard redundant, and the difference need not imply a bug on either side. # Phase 4: Output For each surviving finding, output: - PAIR: - PATH-A: file:method - PATH-B: file:method - DIVERGENCE: - WITNESS: - OBSERVABLE: - DESIGN-MATCH: - SEVERITY: critical | high | medium | low - CONFIDENCE: high | medium If a group has zero findings, output a coverage summary listing every pair inspected, every method traced, and every difference dismissed (with the reason for dismissal). Zero findings with thorough coverage is acceptable. Zero findings with shallow coverage is not — keep looking. DO NOT report: - Performance differences (covered by /audit-performance) - Style differences - Comment/javadoc differences unless they constitute the contract drift - Differences explicitly documented as intentional in design-decisions.md (note them in the "explained" section instead) ``` ## Step 3: Evaluator challenge For each agent that returned findings OR a zero-findings coverage proof, spawn ONE evaluator subagent (general-purpose). The evaluator sees ONLY the reviewer's report — no source code. ``` You are challenging a differential audit report. Your job is to find what the auditor MISSED. For each finding: 1. Is the witness scenario actually reproducible? Identify any unstated precondition (specific config, timing, prior state) that the witness does not enumerate but requires. 2. Is the divergence actually observable to a caller? Or is it an internal difference that produces the same external result? 3. Is the auditor's "joint contract" the actual contract, or did they assume a stronger contract than the documentation promises? For each zero-findings claim: 4. Given the auditor's stated coverage, what categories of divergence might they have under-weighted? (E.g., focused on synchronous control flow, missed exception paths; focused on happy path, missed in-flight transitions.) Output: prioritized list of challenges. Be specific about which finding and which gap. ``` Have the original reviewer address each challenge by re-reading source. Drop findings the reviewer cannot defend with concrete evidence. Add new findings the reviewer confirms. ## Step 4: Adjudicate against design docs Read `.claude/docs/design-decisions.md` and `.claude/rules/design-decisions.md`. For each surviving finding, classify: - **confirmed-divergence** — a concrete supported witness violates the stated joint contract or invariant; an unexplained difference alone is insufficient - **intentional-divergence** — documented design decision (e.g., async listener delivery is intentionally different from sync; weight=0 entries are pinned across all paths); keep in the report under "explained" - **documentation-gap** — intentional behavior with a useful, supported wording clarification; check existing guidance and respect prior decisions declining that same disclosure or wording When several explained differences affect the same entry lifetime, check at most one concrete sequence combining them per group. Compare its observable outcome with the joint contract and the ruling's mechanism, consequence, trigger, and scope. Combining accepted behavior does not itself reopen a ruling. If reachability or the contract remains unresolved, retain the precise question under Residual risk rather than forcing a bug or documentation-gap label. ## Step 5: Triage and report Triage confirmed findings by severity per `.claude/docs/finding-taxonomy.md`. Tag each confirmed finding with the divergence axis: - **sync-async** — the two paths represent the sync and async variants - **storage-variant** — bounded vs unbounded or generated node variant - **view-consistency** — view methods disagreeing with each other - **bulk-vs-single** — aggregate operation diverging from per-element - **equivalent-by-construction** — two APIs that should be interchangeable - **internal-path** — fast vs slow path or maintenance task variants - **adapter-conformance** — an adapter path diverging from a sibling adapter path, the underlying Caffeine method it delegates to, or the external spec/reference it claims to match Write the full report to `.local/audits//audit-sibling-divergence.md` (see `.claude/docs/audit-output.md`). Format: ``` # Sibling Divergence Audit [N] differential auditors compared [M] sibling pairs across [G] groups. [K] findings survived self-challenge and evaluator challenge. ## Confirmed divergences (likely bugs) #1 [severity] [axis] PAIR — one-line summary - PATH-A: file:method - PATH-B: file:method - DIVERGENCE: ... - WITNESS: ... - OBSERVABLE: ... ## Intentional divergences (documented) - [pair] — link to design doc that explains the difference ## Documentation clarifications - [pair] — the useful clarification and the existing guidance or prior wording decision checked ## Coverage summary - Group A: [pairs inspected, methods traced, dismissals] - Group B: ... - ... ## Evaluator challenges - [N] challenges received across [M] groups; [K] led to new findings; [J] confirmed the original conclusion with additional evidence. ## Residual risk What was not inspected and why. ``` ## Notes - The auditor agent's 4-phase methodology applies here too, but per-pair rather than per-method. Each subagent runs Phase 0 through Phase 3 for its assigned pairs. - Generator pairs (B2) are special: read both the generator and the generated output. A divergence might be in the generator's emit logic (one feature combination emits the wrong access mode) or in a missing generator case (a feature combination emits no method at all). - The synchronous() view of an async cache (E4) is the highest-yield pair in group E because it goes through the async code path internally but promises sync semantics. Historical bugs here include `synchronous()` exposing in-flight CompletableFuture state in unexpected ways.