---
name: audit-contract-drift
description: Find places where documented API contracts and the implementation diverge
context: fork
agent: auditor
disable-model-invocation: true
---

Most audits read code; this one reads documentation first and then traces each
promise to every implementation path that should honor it. The bugs caught here
are not concurrency or arithmetic defects — they are quiet contradictions
between what the javadoc promises and what the code does.

Build a list of behavioral promises from public API docs, then trace each one
to every code path that should honor it.

Sources of contracts to enumerate:

- `Caffeine.java` — every `<b>Note:</b>` and `<b>Warning:</b>` block in a
  builder method's javadoc. Pay particular attention to:
  - `weakKeys`, `weakValues`, `softValues` — equality semantics flip to
    identity (`==`) for the configured strength
  - `expireAfter*`, `refreshAfterWrite` — duration constraints, what
    "expired" means at boundaries
  - `maximumSize`, `maximumWeight` — eviction triggering and amortization
  - `removalListener`, `evictionListener` — when and how notifications fire
- `Cache.java`, `LoadingCache.java`, `AsyncCache.java`, `AsyncLoadingCache.java`
  — javadoc of every method, especially "must", "will", "guarantees",
  "for any reason" language.
- `Policy.java` — every method's documented behavior.
- `Weigher.java`, `Expiry.java`, `RemovalListener.java`, `RemovalCause.java`
  — user-facing contracts referenced by the cache.
- **Internal obligations** — "callers must" contracts stated in
  `.claude/rules/*.md` and in internal-class javadoc across all modules (e.g.
  jcache's EventDispatcher requires every publishing thread to drain via
  awaitSynchronous/ignoreSynchronous; async operations must register with the
  in-flight set). Enumerate each obligation, then verify every call site honors
  it — including executor-thread and refresh paths that don't flow through the
  obvious entry points.

For each contract, record the exact wording, the configurations that activate
it, and the set of operations affected.

Then trace each promise through every code path that should honor it:

- Direct API calls on `Cache` / `LoadingCache` / `AsyncCache`
- `asMap()` view methods (`size`, `isEmpty`, `containsKey`, `containsValue`,
  `get`, `put`, `remove(k)`, `remove(k,v)`, `replace`, `compute*`, `merge`,
  `equals`, `hashCode`)
- `asMap().keySet()` / `values()` / `entrySet()` — `contains`, `remove`,
  `removeAll`, `retainAll`, `removeIf`, `iterator`, `spliterator`
- Bulk operations (`putAll`, `getAll`, `getAllPresent`, `invalidateAll`)
- `AsyncCache.synchronous()` round-trip — does the sync view honor the same
  contract as the async cache?
- Serialization round-trip — does the deserialized cache honor the same
  promises about expiration durations, loader presence, etc.?

A path that uses a different equivalence, ordering, or visibility from what
the contract promises is a **contract drift** finding. So is a path that
silently downgrades a configuration on round-trip.

Common drift patterns to check explicitly:

- **Identity vs. equals on weak/soft caches**: `weakKeys`/`weakValues`/
  `softValues` promise identity, but view collections that use
  `o.equals(value)` or `Collection.contains(value)` may apply the user's
  equality semantics instead.
- **Cardinality vs. presence asymmetry**: methods documented as treating
  in-flight async values as absent must align with `size`, `isEmpty`,
  `equals`, `hashCode`, and iterators on the same view.
- **Notification "for any reason"**: `removalListener` documented to fire
  for any cause, but async paths may drop notifications for null or
  exceptional completions.
- **Cross-version serialization**: serialized fields renamed or defaulted
  differently across versions can silently lose configuration or throw
  on round-trip.
- **Same-instance return semantics**: e.g., `compute(k, (k,v) -> v)` is
  documented one way but updates timestamps/weight regardless.
- **`size()` documented as estimate**: this is an explicit out — verify it
  is actually documented as an estimate everywhere it diverges from logical
  presence.
- **Synchronous vs. asynchronous view divergence**: the `synchronous()`
  view's `asMap()` may treat in-flight entries inconsistently across query,
  mutation, and cardinality methods.

Each finding should anchor both sides of the drift — the source of the
contract (file + javadoc snippet) and the divergent implementation (file +
method) — and include a minimal user-observable scenario where the docs and
the code disagree.