/sota-jvm

name: sota-jvm
description: >-
  State-of-the-art JVM engineering rules (2026 baseline) for Java and Kotlin
  that Claude applies when writing or auditing JVM code. Baseline Java 25 LTS
  (virtual threads final since 21; structured concurrency still preview),
  Kotlin 2.x. Covers modern idioms (records, sealed types, pattern matching,
  Kotlin null-safety/coroutines), API/null/immutability design, concurrency
  (virtual threads, JMM, java.util.concurrent, coroutines), security
  (deserialization/gadget chains, XXE, JNDI/Log4Shell-class, injection, JCA
  crypto; SEI CERT Oracle Java + OWASP), performance (G1/ZGC, JFR, GraalVM),
  and build/tooling/CI (Maven/Gradle, dependency-check, Error Prone/NullAway,
  SpotBugs, ktlint/detekt). Trigger keywords - Java, Kotlin, JVM, JDK,
  Spring, record, sealed, virtual thread, Loom, coroutine, suspend,
  ObjectInputStream, deserialization, XXE, JNDI, Log4Shell, Maven, Gradle,
  G1, ZGC, GraalVM, JMH, Optional, null-safety. Use for BOTH building JVM
  services/libraries and reviewing or auditing them.

SOTA JVM — Java & Kotlin (2026)

Expert-level rules for producing and auditing production JVM code. The JVM is memory-safe (no buffer overflows/UAF), so the risk shifts to **deserialization and injection RCE, concurrency correctness, and dependency supply chain**. Baseline: **Java 25 LTS** (records, sealed types, pattern matching, virtual threads finalized in 21 via JEP 444; scoped values finalized in 25 via JEP 506; structured concurrency is still *preview* — JEP 505 in 25 — don't present it as final), **Kotlin 2.x**. Per-language idioms differ; shared concerns (the JMM, the JCA, the build/ supply-chain story) are unified here. Every rule states the *why*; every rules file ends with an audit checklist of grep/analyzer patterns.

Purpose

Two consumers, one source of truth:

• **BUILD mode** — generating Java/Kotlin: follow the rules as defaults. Prefer

immutability, null-safety, and the standard concurrency primitives. Deviate only with a comment justifying it.

• **AUDIT mode** — reviewing existing code: hunt violations with the audit

checklists, classify by severity, report in the finding format below. Deserialization of untrusted data and string-built queries are presumed exploitable.

BUILD mode

1. Before writing, read the rules files relevant to the task (see index). A web service handling untrusted input + threads + a DB needs `02`, `03`, `04`. 2. Apply the **top-10 non-negotiables** (below) unconditionally. 3. New projects: target the current LTS (Java 25), Maven or Gradle with a lockfile, Error Prone + NullAway (Java) or detekt + ktlint (Kotlin), SpotBugs/Find-Sec-Bugs, OWASP dependency-check/OSV-Scanner, and CI running all of it from day one (`rules/06`). 4. Prefer immutability (records, `final`, Kotlin `val`/`data class`, unmodifiable collections) and the type system (sealed hierarchies, no raw types, `Optional`/Kotlin nullable types) over runtime checks. 5. Never let untrusted bytes reach a deserializer, an XML parser with DTDs on, a JNDI lookup, or a string-built query/EL expression (`rules/04`). 6. When you must use a sharp tool (reflection, `ObjectInputStream`, `Unsafe`, a `@SuppressWarnings`), leave a `// NOTE(sota):` comment explaining why and what bounds it.

AUDIT mode

Work each relevant rules file's audit checklist against the target. Run the greps and analyzers (SpotBugs/Find-Sec-Bugs, Error Prone, detekt); confirm hits manually. Check the dependency tree against known-CVE databases.

Severity conventions

| Severity | Meaning | Examples | |---|---|---| | **CRITICAL** | Exploitable on reachable input | `ObjectInputStream.readObject` on untrusted data, JNDI lookup of attacker URL (Log4Shell), SpEL/OGNL/`ScriptEngine` eval of input, SQL via string concat, XXE with DTD enabled | | **HIGH** | Likely incident or security weakness | `Runtime.exec`/`ProcessBuilder` with a shell + interpolation, missing TLS verification, `MessageDigest` MD5/SHA-1 or `Cipher` ECB/`DES` for security, `SecureRandom` seeded predictably, `synchronized`+blocking pinning a carrier thread under load (JDK 21–23 only; fixed in 24+ via JEP 491) | | **MEDIUM** | Correctness/maintainability hazard | Data race on shared mutable state, `equals` without `hashCode`, mutable static state, swallowed exceptions, Kotlin platform-type NPE, resource not in try-with-resources/`use` | | **LOW** | Idiom/perf debt | Mutable collections returned from APIs, raw types, `Optional` fields/params, needless boxing on hot path, `synchronized` where `j.u.c` fits | | **INFO** | Style/doc/hygiene | Formatting, naming, missing `@Override`/`@Nullable` annotations |

Finding format

[SEVERITY] File.java:LINE — short title
  Rule: rules/NN-name.md § section
  Evidence: the offending line(s), verbatim
  Impact: one sentence — what executes/leaks/races, under what input
  Fix: concrete replacement code or action
  Effort: trivial | small | medium | large

Group findings by severity, CRITICAL first. End with: counts per severity, the three highest-leverage fixes, and which checklists/analyzers were run.

Rules index

| File | Read this when... | |---|---| | `rules/01-idioms.md` | Writing/reviewing any Java/Kotlin: records, sealed types, pattern matching, switch expressions, text blocks, `var`; Kotlin null-safety, `data`/`value` classes, `when`, scope functions, immutability, Java↔Kotlin interop, error handling | | `rules/02-design-api.md` | Designing types/APIs: nullability discipline (`Optional`, `OptionalInt`, `@Nullable`, Kotlin types, platform types), **in-band sentinels (absence encoded as `-1`/`0`/`""`)** and the JDK's documented `-1`, immutability, `equals`/`hashCode`/`toString`, exceptions (checked vs unchecked, Kotlin), `AutoCloseable`/try-with-resources/`use`, JPMS/package layout, DI | | `rules/03-concurrency.md` | Anything with threads, executors, or shared state: virtual threads and pinning, structured concurrency