Audit Map Contract

Audit compliance with java.util.concurrent.ConcurrentMap and java.util.Map contracts, and Caffeine's alignment with the Java Collections Framework.

Cross-reference the latest OpenJDK source — do NOT reason from JavaDoc memory

The JavaDoc is silent or ambiguous on the behaviors that actually bite (null inside a bulk collection arg, containsAll(self), equals across map types, the optional NPE points, default-method bodies). WebFetch the real source and read the method body before asserting a contract. Track master (latest) — we stay pragmatically current, not pinned to a JDK version. Fetch the raw form (raw.githubusercontent.com/openjdk/jdk/master/src/ java.base/share/classes/…), not the blob page. These files are large (CHM ~6500 lines) and WebFetch answers a prompt over the content with a small model, so a generic "dump the file" truncates — prompt for the specific method ("quote the exact body of CollectionView.containsAll"), one method per fetch:

• ConcurrentHashMap — the primary reference; asMap() is a ConcurrentMap and closest to CHM: https://raw.githubusercontent.com/openjdk/jdk/master/src/java.base/share/classes/java/util/concurrent/ConcurrentHashMap.java
• ConcurrentSkipListMap — the other JDK ConcurrentMap; the tie-breaker on whether a divergence from CHM is legal (e.g. it also throws UOE on entrySet().add, where CHM's put-through is a nonstandard v8-rewrite addition): https://raw.githubusercontent.com/openjdk/jdk/master/src/java.base/share/classes/java/util/concurrent/ConcurrentSkipListMap.java
• ConcurrentMap — interface + default methods (getOrDefault, compute*, merge, replaceAll): https://raw.githubusercontent.com/openjdk/jdk/master/src/java.base/share/classes/java/util/concurrent/ConcurrentMap.java
• Map — base contract + interface default methods: https://raw.githubusercontent.com/openjdk/jdk/master/src/java.base/share/classes/java/util/Map.java
• AbstractMap — the default-method bodies the views inherit (AbstractMap.equals, and via AbstractCollection/AbstractSet the containsAll/removeAll/retainAll loops): https://raw.githubusercontent.com/openjdk/jdk/master/src/java.base/share/classes/java/util/AbstractMap.java
• HashMap — the most common equals/hashCode comparison target: https://raw.githubusercontent.com/openjdk/jdk/master/src/java.base/share/classes/java/util/HashMap.java
• IdentityHashMap — identity-semantics edge, relevant to weak-key identity and the async future-keyed raw view: https://raw.githubusercontent.com/openjdk/jdk/master/src/java.base/share/classes/java/util/IdentityHashMap.java
• WeakHashMap — relevant to weak keys with automatic removal: https://raw.githubusercontent.com/openjdk/jdk/master/src/java.base/share/classes/java/util/WeakHashMap.java
• Guava LocalCache — the reference for Caffeine's Guava-compat behavior (the CaffeinatedGuava facade + the uniform null-leniency the philosophy below cites; its asMap() views, removal causes, loader/exception translation): https://raw.githubusercontent.com/google/guava/master/guava/src/com/google/common/cache/LocalCache.java

Alignment philosophy — close to CHM, diverge when better

Be pragmatically close to CHM, but Caffeine may diverge where its behavior is better — and when it does, the divergence must be coherent and recorded (design-decisions.md / the cross-model ledger). Do not treat "differs from CHM" as a bug by itself:

• CHM is internally inconsistent. e.g. removeAll([null]) throws NPE while containsAll([null]) returns false — an artifact of which methods happened to get an explicit null-guard, not a contract. Don't chase CHM's inconsistencies.
• Caffeine's own coherent principles are the target, not any one JDK map's quirks: null-hostile on direct single-element ops (put/get/containsKey/contains(null) → NPE — nulls are rejected), but null-tolerant of a null element in a bulk collection arg (containsAll/removeAll skip it — a null is trivially absent); weakly-consistent views; size() is an estimate; expired/collected entries filtered from queries and iteration. The CaffeinatedGuava facade is the deliberate exception — uniformly null-lenient (Guava-compat), overriding native null-hostility only where Guava diverges.
• A contract-optional behavior (permitted NPE, ordering, equals across types) has a legal spread — check several impls (CHM / CSLM / HashMap / Guava), not one, and note that the collections testlibs usually tolerate both legal choices (e.g. guava-testlib testContainsAll_nullNotAllowed does assertFalse(...) with catch (NPE tolerated)). Flag a divergence only when Caffeine is the incoherent one, or diverges from both CHM and Guava with no better rationale.