/sota-jvm

name: sota-jvm
description: >-
  State-of-the-art JVM engineering rules for Java and Kotlin
  that Claude applies when writing or auditing JVM code. Java LTS releases
  (virtual threads final since 21; structured concurrency still preview),
  modern Kotlin. 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**. Written for **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`, `08` (plus `07` if it parses XML). 2. Apply the **top-10 non-negotiables** (below) unconditionally. 3. New projects: target the latest LTS (verify at the Oracle Java SE support roadmap), 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`](rules/06-build-tooling-ci.md)). 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`](rules/04-security.md); XML parsers: [`rules/07`](rules/07-xml.md)). 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

**Coverage:** every `rules/` file's Audit checklist applies in AUDIT mode. Mark one *not applicable* only with its reason in the report — never skip a file because the thing it checks for is absent, since that absence may be the finding.

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

Expands the router's canonical row (`file:line | rule | severity | effort | fix`, which wins on a cross-domain roll-up); evidence block and report order: [`sota` rules/03](../sota/rules/03-audit-findings.md) §2 and §5.

[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`](rules/01-idioms.md) | Writing/reviewing any Java/Kotlin: records, sealed types, pattern matching, switch expressions, text blocks, `var`; Kotl