Updates

.claude/CLAUDE.md

@@ -0,0 +1,161 @@
+# Caffeine
+
+High-performance, near-optimal caching library for Java 11+.
+
+## Build & Test
+
+```bash
+./gradlew :caffeine:build                                    # Full build
+./gradlew :caffeine:test --tests 'ClassName'                 # Single test class
+./gradlew :caffeine:test --tests 'ClassName.methodName'      # Single method
+./gradlew :caffeine:compileTestJava                          # Compile tests only
+```
+
+Run individual tests, not the full suite — it's slow and sharded across 40 CI workers.
+
+### Test Filtering
+
+```bash
+./gradlew :caffeine:test -Pimplementation=caffeine  # Cache type (caffeine/guava)
+./gradlew :caffeine:test -Pkeys=strong              # Key reference (strong/weak)
+./gradlew :caffeine:test -Pvalues=strong            # Value reference (strong/weak/soft)
+./gradlew :caffeine:test -Pcompute=sync             # Compute mode (sync/async)
+./gradlew :caffeine:test -Pstats=enabled            # Stats recording (enabled/disabled)
+```
+
+### Specialized Test Suites
+
+```bash
+./gradlew :caffeine:frayTest         # Fray concurrency interleaving
+./gradlew :caffeine:lincheckTest     # LinCheck linearizability
+./gradlew :caffeine:fuzzTest         # Fuzzing (Jazzer)
+./gradlew :caffeine:jcstress         # JCStress concurrency stress tests
+./gradlew :caffeine:googleTest       # Guava collections tests
+./gradlew :caffeine:apacheTest       # Apache Commons collections tests
+./gradlew :caffeine:eclipseTest      # Eclipse Collections' collections tests
+./gradlew :caffeine:jctoolsTest      # JCTools collections tests
+./gradlew :caffeine:jsr166Test       # JSR-166 collections tests
+./gradlew :caffeine:openjdkTest      # OpenJDK collections tests
+./gradlew :caffeine:moduleTest       # Java module system tests
+./gradlew :caffeine:osgiTest         # OSGi bundle tests
+```
+
+Tests cannot be `@Disabled` or skipped — the build fails on any skipped test.
+
+### Static Analysis
+
+```bash
+./gradlew :caffeine:build -Pspotbugs  # SpotBugs
+./gradlew :caffeine:build -Ppmd       # PMD
+.github/scripts/analyze.sh            # all
+```
+
+ErrorProne + NullAway run on every build. Fix warnings, don't suppress them.
+
+### Benchmarks & Analysis
+
+```bash
+./gradlew jmh -PincludePattern=GetPutBenchmark               # JMH microbenchmarks
+./gradlew :caffeine:memoryOverhead                           # JOL object layout analysis
+./gradlew :caffeine:stress --workload read --duration PT30S  # Stress testing (read, write, refresh)
+```
+
+## Style
+
+Google Java Style. Contributors must sign a CLA.
+
+## Guidelines
+
+- Before suggesting dependency versions, Semgrep rulesets, or tool integrations, verify they exist (check Maven Central, registries, JDK release notes). Never recommend unverified tools. Use latest versions.
+- Stay focused on the specific task requested. Don't produce unsolicited broad recommendation plans or premature "ready for engineer follow-up" conclusions.
+- Lossy/best-effort semantics (read buffer drops, approximate frequency counts, eventual consistency) are intentional design trade-offs in the cache — not defects. Read `.claude/docs/design-decisions.md` before flagging these.
+- When fixing a bug or making a design change, update or create `.claude/` files (docs, rules, skills, agents) to keep them in sync with the change.
+- Don't blindly suggest committing after writing code. Actually run the tests and verify the output before proposing to commit.
+
+## Architecture
+
+Core: `caffeine/src/main/java/com/github/benmanes/caffeine/cache/`
+
+| File | Purpose |
+|------|---------|
+| `BoundedLocalCache.java` | Main cache logic: eviction, expiration, compute |
+| `FrequencySketch.java` | TinyLFU admission frequency counters |
+| `BoundedBuffer.java` | Striped ring buffer for read recording |
+| `MpscGrowableArrayQueue.java` | Write buffer (multi-producer single-consumer) |
+| `TimerWheel.java` | Hierarchical timer wheel for variable expiration |
+| `Node.java` | Node interface (implementations are code-generated) |
+
+Tests: `caffeine/src/test/java/com/github/benmanes/caffeine/cache/`
+
+## Code Generation
+
+Node classes (PS, PW, PSAWMW, etc.) are **generated by javaPoet**. Never edit files
+in `build/generated/`. Edit the generators in `caffeine/src/javaPoet/java/` instead.
+
+```bash
+./gradlew :caffeine:generateNodes :caffeine:generateLocalCaches
+```
+
+Node naming: P=strong key, F=weak key, S=strong value, W=weak value, D=soft value.
+Suffixes: A=access-time, W=write-time, R=refresh, MS=unweighted eviction, MW=weighted eviction.
+
+## Project Structure
+
+```
+caffeine/    — Core cache library
+guava/       — Guava compatibility adapter
+jcache/      — JSR-107 JCache adapter
+simulator/   — Cache policy simulator
+```
+
+## Reference Docs
+
+For deep dives, read these on demand (not auto-loaded to save context):
+
+- `.claude/docs/design-decisions.md` — why non-obvious choices are intentional, not bugs
+- `.claude/docs/synchronization.md` — lock hierarchy, access modes, callback invocation points
+- `.claude/docs/testing.md` — CacheSpec parameterization, Truth subjects, test utilities
+- `.claude/docs/research-foundations.md` — papers mapped to implementation (TinyLFU, BP-Wrapper, etc.)
+- `.claude/docs/finding-taxonomy.md` — standard severity/category schema for audit and review findings
+
+When to read which doc:
+- Concurrency or thread-safety work → `synchronization.md`
+- Auditing or reviewing code → `design-decisions.md` first (prevents false positives)
+- Writing or modifying tests → `testing.md`
+- Understanding algorithm choices → `research-foundations.md`
+- Interpreting or writing audit findings → `finding-taxonomy.md`
+
+## Claude Code Extensions
+
+- **Rules** (`.claude/rules/`): project conventions, loaded automatically when relevant
+- **Skills** (`/review-change`): multi-layer parallel code review with blind + design-aware + regression pattern matching
+- **Skills** (`/audit-*`): 19 deep analysis skills for concurrency, correctness, and performance
+- **Skills** (`/audit-adversarial`): hostile full-codebase review with NO design context — finds bugs domain familiarity masks
+- **Skills** (`/sim-*`): simulator workflow automation — `/sim-compare` for policy comparison charts, `/sim-analyze` for trace characterization
+- **Auditor agent** (`.claude/agents/`): multi-pass — analysis → reflection → evaluator challenge → targeted re-audit
+
+### Audit Selection Guide
+
+| If concerned about... | Run |
+|---|---|
+| Thread-safety of a specific change | `/audit-jmm` |
+| API contract ordering under concurrency | `/audit-linearizability` |
+| Feature interactions (eviction+expiry+refresh) | `/audit-feature-interaction` |
+| Exception paths leaving inconsistent state | `/audit-exception-safety` |
+| Memory leaks after removal/eviction | `/audit-memory-retention` |
+| Arithmetic edge cases (overflow, off-by-one) | `/audit-arithmetic` |
+| Shutdown/close/GC races | `/audit-lifecycle` |
+| Fresh-eyes adversarial sweep (no domain context) | `/audit-adversarial` |
+| Full correctness proof of public methods | `/audit-correctness-proof` |
+| Map/ConcurrentMap contract compliance | `/audit-map-contract` |
+| Re-entrancy from user callbacks | `/audit-reentrancy` |
+| Concurrent iteration and view consistency | `/audit-iteration` |
+| Performance inefficiencies on hot paths | `/audit-performance` |
+| Serialization proxy completeness and safety | `/audit-serialization` |
+| Behavior under extreme/adversarial API inputs | `/audit-adversarial-input` |
+| Progress and termination guarantees | `/audit-liveness` |
+| Test coverage gaps and missing edge cases | `/audit-coverage-gaps` |
+| Per-subsystem concurrency correctness | `/audit-subsystem-safety` |
+| Build/CI configuration correctness | `/audit-build-ci` |
+
+**Review vs Audit**: `/review-change` is for pre-commit code review — reads design docs and filters known-intentional patterns. `/audit-*` skills are for correctness doubts — independent, no design context filtering. Use review for routine changes, audit when you need fresh-eyes analysis.