audit-third-party-contracts

---
name: audit-third-party-contracts
description: Verify every third-party and sharp-edged JDK API usage against the contract the upstream documentation actually states
context: fork
agent: auditor
disable-model-invocation: true
---

Audit uses of external libraries and sharp-edged JDK APIs against the contract
the upstream documentation actually states — not the contract the call site
assumes. This lens is distinct from the cache-correctness lenses: the bugs are
in the seam between our code and someone else's semantics (dispose-on-error,
merge-less collectors, empty timed buffers, live-view iteration windows).

Scope: `examples/*/src/main/java/`, `simulator/src/main/java/`,
`jcache/src/main/java/`, `guava/src/main/java/`. The core is nearly
dependency-free; include it only for JDK sharp edges.

## Step 1: Enumerate touchpoints

From `gradle/libs.versions.toml` and each module's build file, list the
third-party libraries in scope. Grep each module for their package imports,
plus these JDK sharp edges: Collectors.toMap/groupingBy, CompletableFuture
composition and cancellation, live collection views held across a time window,
ServiceLoader/TCCL-dependent lookups, Object.wait/notify handshakes.

## Step 2: Extract the assumed contract

For each touchpoint, state what the call site implicitly assumes about:

- **Error path**: what happens to the pipeline/subscription/future when user
  code or the library throws? Is the failure surfaced or swallowed?
- **Degenerate input**: duplicate keys, empty batch, null element, zero
  duration, single element
- **Cancellation/disposal**: is it terminal? who observes it? can the
  structure be reused after?
- **Threading**: which thread runs the callback; what ThreadLocal, ordering,
  or reentrancy assumptions ride on that?
- **Resource lifecycle**: close/dispose idempotency, unsubscribe/leak behavior

## Step 3: Verify against the upstream contract

Quote the authoritative source — library javadoc for the version pinned in
`libs.versions.toml`, the reactive-streams specification rule, or JDK javadoc.
WebFetch the docs when unsure; do not rely on recall. A finding must cite the
upstream sentence that contradicts the call site.

High-yield contract families:

- **Reactive streams (RxJava/Reactor)**: onError is terminal and disposes; a
  subscriber without an error handler routes to a global hook and silently
  unsubscribes; timed buffers emit empty lists on every period; a cancelled
  sink rejects all future emissions; a subject with no observers drops
  emissions silently
- **Collectors.toMap** throws IllegalStateException on duplicate keys without
  a merge function
- **CompletableFuture**: exceptions in *Async stages surface only via the
  returned future; cancel() does not interrupt the running task; a throw
  inside whenComplete replaces/suppresses in non-obvious ways
- **Live vs snapshot views**: a live keySet/values passed to another operation
  observes concurrent mutations; removeAll(null) throws NPE
- **ORM/config libraries (Hibernate, Typesafe Config)**: session/entity
  lifecycle and reload semantics the integration assumes

## Step 4: Construct the violating scenario

For each contradiction, produce the concrete input or event sequence and the
observable damage (hung future, silent data loss, permanent pipeline death,
corrupted secondary structure, useless periodic load). Findings without a
constructible scenario are suspicions — label them per the auditor contract.

Classify findings with the `external-contract` category from
`.claude/docs/finding-taxonomy.md`. Also check the module's tests: if the
failing scenario is untestable because tests only exercise happy paths
(distinct keys, no failures, non-empty batches), report the test gap alongside
the bug.

More agent context in ben-manes/caffeine

36 other files this repository gives its agents.