rsc-universal 0.1.1

package/skills/java/SKILL.md

@@ -0,0 +1,341 @@
+---
+name: java
+description: "Use when writing, reviewing, or refactoring modern Java (21+, Java 25 LTS) - records and sealed interfaces as algebraic data types, exhaustive pattern-matching switch over instanceof+cast ladders, virtual-thread (Project Loom) concurrency one-task-per-thread, structured concurrency and ScopedValue replacing ThreadLocal, Stream/Optional/Collector pipelines, compact-constructor validation, parametrized JDBC, and the Maven 3.9 / Gradle 9 build surface against a current JDK. Triggers: \"write a Java service\", \"is this idiomatic Java\", \"refactor this instanceof ladder\", \"fetch 500 URLs concurrently\", \"model this domain with records\", .java files, pom.xml, build.gradle, the non-obvious \"my ThreadLocal context disappears inside the tasks I submit\" (that is ScopedValue), \"modela este dominio de pagos con tipos inmutables\", \"refactoritza aquest switch\". NOT Spring framework wiring (that is spring-boot)."
+tags: [java, jvm, records, virtual-threads, sealed-types]
+recommends: [spring-boot, secure-coding, deployment]
+origin: risco
+---
+
+# Modern Java (21+)
+
+Write, review, and refactor Java the way the language is shaped today, not the way it
+was in 2014.
+
+Targets **Java 21+ with Java 25 as the current LTS** (released 2025-09-16, supported to
+2033; Java 26 is the current non-LTS, 2026-03-17). "Modern" here means: records and sealed
+interfaces instead of JavaBeans and type hierarchies, exhaustive pattern-matching `switch`
+instead of `instanceof`+cast ladders, virtual threads instead of hand-tuned pools, and
+`ScopedValue` instead of `ThreadLocal`. If you are reaching for a telescoping constructor,
+a getter/setter bean, or a manual `ExecutorService` sized to a core count, stop.
+
+## When to use / When NOT to use
+
+**Use when:**
+
+- Authoring, reviewing, or refactoring any `.java` file.
+- Modeling a domain: record vs class, sealed hierarchy vs enum, where immutability belongs.
+- Replacing `instanceof`+cast chains or visitor boilerplate with a pattern-matching `switch`.
+- Concurrency that blocks on I/O at scale: migrating thread pools / reactive chains to
+  virtual threads, fan-out with structured concurrency, `ThreadLocal` -> `ScopedValue`.
+- Stream / Optional / Collector pipelines, and deciding when a plain loop beats a stream.
+- Setting up or fixing a `pom.xml` / `build.gradle(.kts)` for a current JDK (toolchain,
+  `--release`, preview flags, JUnit 5).
+
+**When NOT to use (delegate):**
+
+- **Spring** controllers, beans, starters, autoconfiguration, `@Transactional` -> `spring-boot`.
+  This skill is the plain-JDK layer underneath; framework wiring is out of scope by topic.
+- **Kotlin** on the JVM (Android or server) -> `kotlin-android`. Java and Kotlin interop but
+  are different languages; coroutines and Kotlin null-safety belong there.
+- **Language-agnostic threat modeling / OWASP / authz** -> `secure-coding`. This skill keeps
+  only Java-specific controls (parametrized JDBC, compact-constructor validation, sane deser).
+- **Containerfile / CI pipeline / shipping** -> `deployment`. This skill keeps only a
+  jlink/jpackage note and the JDK base-image choice.
+- **PostgreSQL schema / index / query tuning** -> `postgresdb`. This skill covers JDBC
+  parametrization from the Java side only.
+- Recording per-project conventions in a workspace wiki -> `harness` (see "Project grounding").
+
+Records/sealed/pattern-matching design, virtual-thread concurrency, and the build surface
+live **here** — there is no separate "java-concurrency" or "java-build" skill.
+
+## Decision rules
+
+Apply these on every Java edit:
+
+1. **Record by default for data.** If a type just carries values, make it a `record`; it
+   gets `equals`/`hashCode`/`toString` and is immutable for free. Class only when you need
+   mutable identity or inheritance.
+2. **Sealed + exhaustive `switch` over `instanceof` ladders.** A closed set of cases is a
+   `sealed interface`; the compiler then proves your `switch` is total. An `instanceof`+cast
+   ladder is an unchecked manual version of this.
+3. **Immutable and `final` by default.** Fields `final`, collections wrapped/copied; mutate
+   only where you have measured a reason. Shared mutable state is the bug you debug at 3am.
+4. **`Optional` is a return type, never a field or parameter.** It signals "maybe absent" to a
+   caller; an `Optional` field just adds a null-of-null. For absent collections, return empty.
+5. **Virtual threads for blocking I/O, platform threads for CPU work.** Loom wins when threads
+   spend their life parked on sockets/JDBC; it does nothing for a tight CPU loop.
+6. **One virtual thread per task. Never pool them.** They are cheap (millions are fine);
+   pooling them re-introduces the limit they exist to remove.
+7. **Validate in the compact constructor.** A `record`'s invariants belong in its compact
+   constructor so an invalid instance cannot exist — not in a separate `validate()` you can forget.
+8. **Parametrize every JDBC query.** `PreparedStatement` with `?`, bind values; never
+   concatenate user input into SQL.
+9. **Stream for transforms, loop for side-effects.** A `map`/`filter`/`collect` pipeline is
+   clear; a `forEach` that mutates external state is a loop wearing a costume — write the loop.
+10. **Treat compiler warnings as failures.** Build with `-Xlint:all -Werror`; an ignored
+    `unchecked` or `deprecation` warning is a deferred bug.
+
+## Data modeling
+
+A `record` is the default data carrier — immutable, no setters, validated in its compact
+constructor.
+
+```java
+// Good: invalid Money cannot exist; value semantics for free.
+public record Money(long cents, Currency currency) {
+    public Money {                                   // compact constructor
+        if (cents < 0) throw new IllegalArgumentException("cents < 0: " + cents);
+        Objects.requireNonNull(currency, "currency");
+    }
+    public Money plus(Money other) {
+        if (!currency.equals(other.currency)) throw new IllegalArgumentException("currency mismatch");
+        return new Money(cents + other.cents, currency);
+    }
+}
+```
+
+```java
+// Bad: telescoping constructors, mutable identity, hand-written equals you will get wrong.
+public final class Money {
+    private long cents; private Currency currency;
+    public Money() {}
+    public Money(long cents) { this.cents = cents; }
+    public Money(long cents, Currency currency) { this.cents = cents; this.currency = currency; }
+    public void setCents(long c) { this.cents = c; }   // now any caller can break invariants
+    public long getCents() { return cents; }
+    // ... 40 lines of getters/setters/equals/hashCode ...
+}
+```
+
+A **sealed interface + record cases is an algebraic data type** — a closed set the compiler
+knows about:
+
+```java
+public sealed interface PaymentResult permits Captured, Declined, Pending {}
+public record Captured(String id, Money amount)        implements PaymentResult {}
+public record Declined(String reason, int code)        implements PaymentResult {}
+public record Pending(String id, Instant retryAfter)   implements PaymentResult {}
+```
+
+**Enum vs sealed:** use an `enum` when cases are a fixed set of *constants with no per-case
+data* (`Status.ACTIVE`); use a sealed interface when each case *carries different fields*
+(above). Reaching for an enum plus a parallel "payload" map means you wanted a sealed type.
+
+## Pattern matching
+
+`instanceof` binds the pattern variable directly — no cast:
+
+```java
+if (event instanceof Captured c) {       // Good: c is in scope, already typed
+    ledger.record(c.id(), c.amount());
+}
+```
+
+An exhaustive `switch` over a sealed type with **record deconstruction** and `when` guards
+replaces the whole ladder — and **omit `default` when the sealed set is covered** so adding a
+new case becomes a compile error you must handle:
+
+```java
+// Good: total over the sealed type; deconstruction patterns; guard; null branch.
+String describe(PaymentResult r) {
+    return switch (r) {
+        case Captured(var id, var amt) when amt.cents() == 0 -> "free capture " + id;
+        case Captured(var id, var amt)                       -> "captured " + amt.cents() + "c " + id;
+        case Declined(var reason, var code)                  -> "declined(" + code + "): " + reason;
+        case Pending(var id, var __)                         -> "pending " + id;
+        case null                                            -> "no result";
+        // no default: compiler proves exhaustiveness; a new permits-case won't compile until handled
+    };
+}
+```
+
+```java
+// Bad: instanceof + cast ladder. No exhaustiveness check; a new case silently falls through.
+String describe(PaymentResult r) {
+    if (r instanceof Captured) { Captured c = (Captured) r; return "captured " + c.amount(); }
+    else if (r instanceof Declined) { Declined d = (Declined) r; return "declined " + d.reason(); }
+    else return "?";   // silently wrong when Pending is added
+}
+```
+
+Java 25 adds **primitive type patterns** in `instanceof` and `switch` (e.g. `case int i`),
+extending exhaustiveness to primitives.
+
+## Concurrency: virtual threads
+
+For blocking I/O, run **one virtual thread per task** inside a per-task executor closed with
+try-with-resources (the close call blocks until every submitted task finishes):
+
+```java
+// Good: 500 blocking fetches, one virtual thread each. No pool sizing, no reactive ceremony.
+List<String> fetchAll(List<URI> urls, HttpClient http) throws InterruptedException {
+    try (var exec = Executors.newVirtualThreadPerTaskExecutor()) {
+        var futures = urls.stream()
+            .map(u -> exec.submit(() -> http.send(
+                HttpRequest.newBuilder(u).build(), BodyHandlers.ofString()).body()))
+            .toList();
+        return futures.stream().map(f -> {
+            try { return f.get(); } catch (Exception e) { throw new CompletionException(e); }
+        }).toList();
+    } // close() joins all tasks
+}
+```
+
+```java
+// Bad: a fixed platform-thread pool caps you at N concurrent blocking calls and starves.
+var exec = Executors.newFixedThreadPool(16);   // 484 of 500 fetches wait on a thread
+```
+
+**JEP 491 (JDK 24) removed `synchronized` pinning** — a virtual thread inside a `synchronized`
+block no longer pins its carrier, so legacy `synchronized` code is safe on Loom now. For *long*
+holds prefer `ReentrantLock` anyway (fairness, tryLock, interruptibility).
+
+**Structured concurrency** (`StructuredTaskScope`) ties subtasks to a scope so one failure
+cancels the siblings — but it is **still preview in Java 25 (JEP 505, 5th preview)**, so it
+needs `--enable-preview`. **`ScopedValue` is FINAL in Java 25 (JEP 506)** and is the immutable
+replacement for `ThreadLocal` when sharing context across virtual threads:
+
+```java
+// Good: immutable, explicitly scoped, propagates into child tasks; nothing to clean up.
+private static final ScopedValue<String> REQUEST_ID = ScopedValue.newInstance();
+ScopedValue.where(REQUEST_ID, id).run(() -> handle(req));   // REQUEST_ID.get() inside
+```
+
+A `ThreadLocal` set on the caller does **not** appear in the tasks you submit to an executor,
+and on millions of virtual threads its mutable per-thread copies leak memory — that symptom is
+exactly what `ScopedValue` fixes. Deep dive (scopes, joiners, pinning diagnosis, when platform
+threads still win) -> `references/concurrency.md`.
+
+## Streams, Optional, Collectors (essentials)
+
+Use `stream().toList()` (Java 16+, immutable) for the common case; `Collectors.groupingBy`
+and `teeing` cover most aggregation:
+
+```java
+Map<Currency, Long> totalByCcy = payments.stream()
+    .collect(Collectors.groupingBy(Payment::currency,
+             Collectors.summingLong(p -> p.amount().cents())));
+```
+
+`Optional` discipline: chain `map`/`filter`/`orElseGet`/`orElseThrow`; never `.get()` without a
+prior `isPresent`, never an `Optional` field. Do **not** stream when a loop is clearer — a
+`forEach` with side-effects, an early `break`/`return`, or index-coupled logic is a loop.
+Full Collector catalog, custom collectors, `mapMulti`, Gatherers (Java 24+), and parallel-stream
+caveats -> `references/streams.md`.
+
+## Builds
+
+Pin the language level with the compiler plugin's `<release>`, run JUnit 5 via Surefire.
+**Maven 4 is not yet GA (4.0.0-rc-5, Nov 2025) — use Maven 3.9.x for production**:
+
+```xml
+<properties><maven.compiler.release>25</maven.compiler.release></properties>
+<build><plugins>
+  <plugin>
+    <groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId>
+    <version>3.13.0</version>
+    <configuration><release>25</release>
+      <compilerArgs><arg>-Xlint:all</arg><arg>-Werror</arg></compilerArgs></configuration>
+  </plugin>
+  <plugin>
+    <groupId>org.apache.maven.plugins</groupId><artifactId>maven-surefire-plugin</artifactId>
+    <version>3.5.2</version>
+  </plugin>
+</plugins></build>
+```
+
+Gradle 9.x (current 9.5.1, requires Java 17+ to run, prefers the configuration cache) uses a
+**toolchain block** so the build picks the right JDK regardless of the runner's default:
+
+```kotlin
+plugins { java }
+java { toolchain { languageVersion = JavaLanguageVersion.of(25) } }
+tasks.test { useJUnitPlatform() }
+```
+
+Full `pom.xml` / `build.gradle.kts` skeletons, multi-module, preview-flag wiring, JUnit 5 +
+AssertJ + Mockito, jlink/jpackage -> `references/builds.md`.
+
+## Errors & null
+
+- **Never return `null`.** Return `Optional<T>` for a maybe-value, an empty collection for "none".
+- **try-with-resources** for anything `AutoCloseable`; do not write a `finally { close() }` by hand.
+- **Chain exceptions** — `throw new ServiceException("loading user " + id, cause)` — so the
+  stack trace keeps the root. Swallowing (`catch (Exception e) {}`) destroys the evidence.
+- **Checked vs unchecked:** checked (`extends Exception`) for recoverable, expected conditions
+  the caller must handle; unchecked (`extends RuntimeException`) for programming bugs / invariant
+  violations. Do not wrap everything in a checked exception "to be safe" — it just gets rethrown.
+
+## Anti-patterns / rationalizations -> STOP
+
+| Rationalization | Reality / Do instead |
+| --- | --- |
+| "I'll add setters to the record for convenience" | Then it isn't immutable. Build a new instance; validate in the compact constructor. |
+| "instanceof+cast is fine, it's only three cases" | No exhaustiveness; case four silently falls through. Sealed + `switch`. |
+| "pool the virtual threads to be safe" | Pooling re-adds the limit Loom removes. One virtual thread per task. |
+| "ThreadLocal carries my request context" | It doesn't cross submit() and leaks on millions of vthreads. `ScopedValue`. |
+| "Optional field so callers handle absence" | Optional is a return type. A field is null-of-null; use the value or a default. |
+| "raw `List` is shorter than `List<Payment>`" | Raw types disable generics checks. Always parametrize. |
+| "catch and ignore, it can't happen here" | Then assert it; a swallowed exception erases the bug. Log + rethrow or handle. |
+| "fmt the id into the SQL string, it's trusted" | Trust nothing at the boundary. `PreparedStatement` with `?`. |
+| "wrap it in a checked exception to force handling" | Most callers just rethrow. Unchecked for bugs; checked only when recovery is real. |
+| "`new Thread(r).start()` per request" | On platform threads that's a few thousand max. Virtual-thread-per-task executor. |
+| "default branch keeps the switch safe" | A default hides the new case. Omit it on a sealed type so it won't compile. |
+| "warnings are just noise" | `unchecked`/`deprecation` are deferred bugs. `-Xlint:all -Werror`. |
+
+## Quick reference
+
+| Task | Idiom / command |
+| --- | --- |
+| Build + test (Maven) | `./mvnw -q verify` (or `mvn -q verify`) |
+| Build + test (Gradle) | `./gradlew check` |
+| Data carrier | `record Money(long cents, Currency ccy) { Money { ... } }` |
+| Closed case set | `sealed interface R permits A, B {}` + `record A(...) implements R {}` |
+| Exhaustive match | `switch (r) { case A(var x) -> ...; case B b -> ...; }` (no `default`) |
+| Concurrent blocking I/O | `try (var e = Executors.newVirtualThreadPerTaskExecutor()) { ... }` |
+| Context across threads | `ScopedValue.where(KEY, val).run(() -> ...)` |
+| Run a single source file | `java App.java` (compact source + instance `main`, JEP 512, final in 25) |
+| Local gate | `./scripts/verify.sh` (run in your project root) |
+
+## Project grounding (02-DOCS + CLAUDE.md)
+
+When this skill runs in a project with a `02-DOCS/` layer (the
+[`harness`](../harness/SKILL.md) Karpathy wiki), record this project's Java decisions there
+and index them from the root `CLAUDE.md`, so the next agent inherits them instead of re-deriving.
+
+1. **Find the article** `02-DOCS/wiki/stack/java.md`, linked from a `## Knowledge map` section
+   in the root `CLAUDE.md`.
+2. **If missing or stale**, create/update it with the project's real choices — JDK/LTS target,
+   Maven vs Gradle, the domain-modeling conventions (records/sealed), the concurrency model
+   (virtual threads, structured-concurrency preview on/off), and the error/null conventions —
+   then add/refresh the `CLAUDE.md` link (create the `## Knowledge map` section and `CLAUDE.md`
+   itself if absent).
+3. **Read it first on every use** and stay consistent; when a convention changes, update the
+   article (bump its `Updated` date) in the same change.
+
+No `02-DOCS/` layer? Skip silently (optionally suggest `harness`). Technical conventions are
+*recorded, not gated* — never block the task on this.
+
+## See Also
+
+Sibling skills (link only those present under `skills/`):
+
+- `spring-boot` - the Spring framework surface (controllers, beans, autoconfiguration); this
+  skill is the plain-JDK/language layer underneath it.
+- [`secure-coding`](../secure-coding/SKILL.md) - threat modeling and language-agnostic
+  authz/abuse/OWASP review (this skill keeps the Java-specific controls).
+- [`deployment`](../deployment/SKILL.md) - Docker, CI, and shipping (this skill keeps only the
+  jlink/jpackage note and base-image choice).
+- [`postgresdb`](../postgresdb/SKILL.md) - SQL schema/index/query tuning (this skill covers JDBC
+  parametrization from the Java side only).
+- [`harness`](../harness/SKILL.md) - the `02-DOCS/` workspace wiki where per-project Java
+  conventions are recorded (see "Project grounding").
+
+Local references (read when):
+
+- `references/concurrency.md` - virtual-thread internals, structured concurrency, ScopedValue,
+  pinning diagnosis, when platform threads still win.
+- `references/streams.md` - full Collectors catalog, custom collectors, Gatherers, parallel-stream
+  caveats, Stream-vs-loop decision table.
+- `references/builds.md` - full pom.xml + build.gradle.kts skeletons, multi-module, preview flags,
+  JUnit 5 + AssertJ + Mockito, jlink/jpackage, dependency hygiene.

package/skills/java/evals/README.md

@@ -0,0 +1,23 @@
+# Eval harness — `java` skill
+
+These are routing/trigger fixtures plus one capability rubric, not an automated CI harness.
+`cases.yaml` is the fixture; this file is how to run it by hand or with a grader-agent.
+
+**Triggering.** Load the full skill catalog so the routing layer sees every sibling
+(spring-boot, kotlin-android, secure-coding, deployment, postgresdb, go, python, harness, …).
+Feed each `should_trigger.prompt` in a fresh session and confirm the agent invokes the `java`
+skill; feed each `should_not_trigger.prompt` and confirm it does NOT fire `java` and instead
+routes to the stated `route_to` sibling. LLM routing is non-deterministic, so run 3–5 trials
+per prompt and pass on the majority; aim for ≥90% trigger accuracy. Watch the non-obvious case
+("ThreadLocal disappears inside submitted tasks") — it should still fire `java` and land on
+ScopedValue, and the Spanish case ("modela este dominio de pagos") should fire too.
+
+**Capability.** Run the `capability.scenario` once without the skill body and once with
+`java/SKILL.md` (plus `references/`) loaded, and grade each answer against the `must_include`
+rubric (fraction of points present and correct). The skill earns its place only if the
+with-skill answer clearly beats the baseline — chiefly: sealed interface + record cases (no
+JavaBean), compact-constructor validation, an exhaustive `switch` with deconstruction and no
+`default`, no instanceof ladder, a virtual-thread-per-task executor (not a pool), no `null`
+returns, and a `pom.xml` pinned to `<release>25</release>`. Grading is judgment-based; a human
+or grader-agent reads each rubric point against the output. Keep `cases.yaml` faithful to the
+SKILL's "When to use / When NOT to use" — update both in the same change when scope shifts.

package/skills/java/evals/cases.yaml

@@ -0,0 +1,43 @@
+skill: java
+
+should_trigger:
+  - prompt: "Write a service that fetches 500 URLs concurrently and aggregates the response bodies."
+    why: "Virtual-thread fan-out for blocking I/O is the core concurrency use case; the user never names Java or Loom but the shape (concurrent blocking fetches) is exactly what one-vthread-per-task owns here."
+  - prompt: "Refactor this instanceof + cast ladder over a Shape type into something cleaner and exhaustive."
+    why: "Replacing instanceof+cast ladders with a sealed type + exhaustive pattern-matching switch is explicitly owned by this skill."
+  - prompt: "Is this idiomatic modern Java? class User { private String name; private int age; with all the getters and setters and a no-arg constructor }"
+    why: "Idiom review of a JavaBean; the skill should push it to a record. 'Is this idiomatic Java' is a named trigger."
+  - prompt: "modela este dominio de pagos con tipos inmutables y casos exhaustivos (capturado, rechazado, pendiente)"
+    why: "Spanish phrasing for sealed-interface-plus-record ADT modeling with exhaustive handling — records and sealed types are owned here."
+  - prompt: "My ThreadLocal request context disappears inside the tasks I submit to the executor, and we're running on millions of virtual threads now. What should I use instead?"
+    why: "Non-obvious: the user describes the symptom (ThreadLocal not crossing submit, leaking on vthreads) without naming ScopedValue, which is exactly the fix this skill prescribes."
+  - prompt: "Set up a pom.xml that compiles against Java 25 and runs JUnit 5 tests, with warnings treated as errors."
+    why: "The Maven/Gradle build surface (compiler-plugin release, surefire + JUnit 5, -Xlint -Werror) is owned by this skill."
+
+should_not_trigger:
+  - prompt: "Add a @RestController with @GetMapping(\"/users/{id}\") and inject a @Service bean for the lookup."
+    route_to: "spring-boot"
+    why: "Spring framework wiring (controllers, beans, annotations, autoconfiguration) is delegated to spring-boot; this skill is only the plain-JDK layer underneath."
+  - prompt: "Write a Kotlin coroutine-based repository with a Flow for my Android app."
+    route_to: "kotlin-android"
+    why: "Kotlin language and Android belong to kotlin-android; Java and Kotlin interop but are different languages."
+  - prompt: "Do an OWASP-style authorization review and threat model of my multi-tenant API's permission boundaries."
+    route_to: "secure-coding"
+    why: "Language-agnostic threat modeling / authz / OWASP review is delegated to secure-coding; only Java-specific controls (JDBC params, compact-constructor validation) stay here."
+  - prompt: "Write a multi-stage Dockerfile and a GitHub Actions pipeline to build and ship my jar."
+    route_to: "deployment"
+    why: "Containerfile / CI / shipping is delegated to deployment; this skill keeps only the jlink/jpackage note and base-image choice."
+  - prompt: "Tune the indexes and rewrite this slow query for a Postgres users table with a composite lookup."
+    route_to: "postgresdb"
+    why: "SQL schema/index/query tuning is a database concern; this skill covers only JDBC parametrization from the Java side."
+
+capability:
+  - scenario: "Model a payment domain as a sealed interface with record cases (Captured, Declined, Pending), write an exhaustive switch that maps each case to an HTTP-ish result, validate a Money amount in a compact constructor, and fan out N payment validations concurrently. Provide a Maven build targeting Java 25."
+    must_include:
+      - "Payment outcome modeled as a sealed interface with record cases (sealed interface ... permits ...; record Captured/Declined/Pending implements it) — NOT a JavaBean with getters/setters or a class hierarchy"
+      - "Money (or the amount type) is a record that validates its invariant in a compact constructor (e.g. throws on negative cents / null currency) so an invalid instance cannot be constructed"
+      - "An exhaustive switch over the sealed type using record deconstruction patterns (case Captured(var id, var amt) -> ...) with NO default branch, relying on the compiler's exhaustiveness check"
+      - "No instanceof + cast ladder anywhere in the mapping logic"
+      - "Concurrency uses Executors.newVirtualThreadPerTaskExecutor() inside try-with-resources, one task per virtual thread (NOT a fixed-size pool, NOT new Thread per request, NOT pooled virtual threads)"
+      - "Returns Optional or an empty collection rather than null for absent results"
+      - "pom.xml configures maven-compiler-plugin with <release>25</release> (and ideally -Xlint:all/-Werror) and JUnit 5 via surefire"

package/skills/java/references/builds.md

@@ -0,0 +1,133 @@
+# Build surface: Maven 3.9 & Gradle 9 (deep)
+
+Versions as of 2026-06: **Maven 3.9.x is current stable** (Maven 4 is 4.0.0-rc-5, not GA —
+prefer 3.9.x for production, watch for 4 GA). **Gradle 9.5.1** is current, requires Java 17+ to
+run, and prefers the configuration cache. JDK target here is **Java 25 LTS** via `<release>` /
+toolchain — adjust to 21 if you must run on the prior LTS.
+
+## Maven: full pom.xml skeleton
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <groupId>com.example</groupId>
+  <artifactId>payments</artifactId>
+  <version>1.0.0</version>
+  <packaging>jar</packaging>
+
+  <properties>
+    <maven.compiler.release>25</maven.compiler.release>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    <junit.version>5.11.4</junit.version>
+    <assertj.version>3.27.0</assertj.version>
+    <mockito.version>5.15.2</mockito.version>
+  </properties>
+
+  <dependencies>
+    <dependency><groupId>org.junit.jupiter</groupId><artifactId>junit-jupiter</artifactId>
+      <version>${junit.version}</version><scope>test</scope></dependency>
+    <dependency><groupId>org.assertj</groupId><artifactId>assertj-core</artifactId>
+      <version>${assertj.version}</version><scope>test</scope></dependency>
+    <dependency><groupId>org.mockito</groupId><artifactId>mockito-core</artifactId>
+      <version>${mockito.version}</version><scope>test</scope></dependency>
+  </dependencies>
+
+  <build><plugins>
+    <plugin>
+      <groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId>
+      <version>3.13.0</version>
+      <configuration>
+        <release>25</release>
+        <compilerArgs><arg>-Xlint:all</arg><arg>-Werror</arg></compilerArgs>
+      </configuration>
+    </plugin>
+    <plugin>
+      <groupId>org.apache.maven.plugins</groupId><artifactId>maven-surefire-plugin</artifactId>
+      <version>3.5.2</version>
+    </plugin>
+  </plugins></build>
+</project>
+```
+
+Build and test: `./mvnw -q verify` (commit the wrapper via `mvn wrapper:wrapper`). The wrapper
+pins the Maven version per project; do not rely on a globally installed `mvn`.
+
+### Preview flags (Maven)
+
+For preview features (e.g. `StructuredTaskScope`, JEP 505 in 25), pass `--enable-preview` to
+compiler, surefire, and the run command — all three or it fails at the next stage:
+
+```xml
+<configuration>
+  <release>25</release>
+  <compilerArgs><arg>--enable-preview</arg></compilerArgs>
+</configuration>
+<!-- surefire: -->
+<configuration><argLine>--enable-preview</argLine></configuration>
+```
+
+```bash
+java --enable-preview -jar target/payments-1.0.0.jar
+```
+
+### Toolchains (decouple build JDK from runtime JDK)
+
+`~/.m2/toolchains.xml` plus `maven-toolchains-plugin` lets the build select a specific JDK
+regardless of `JAVA_HOME`, so CI and laptops compile against the same version.
+
+## Gradle: full build.gradle.kts
+
+```kotlin
+plugins {
+    java
+    application
+}
+
+group = "com.example"
+version = "1.0.0"
+
+java {
+    toolchain { languageVersion = JavaLanguageVersion.of(25) }   // Gradle provisions/selects JDK 25
+}
+
+repositories { mavenCentral() }
+
+dependencies {
+    testImplementation("org.junit.jupiter:junit-jupiter:5.11.4")
+    testImplementation("org.assertj:assertj-core:3.27.0")
+    testImplementation("org.mockito:mockito-core:5.15.2")
+    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
+}
+
+tasks.withType<JavaCompile> { options.compilerArgs.addAll(listOf("-Xlint:all", "-Werror")) }
+tasks.test { useJUnitPlatform() }
+application { mainClass = "com.example.App" }
+```
+
+Build and test: `./gradlew check` (compile + test). Gradle 9 prefers the configuration cache —
+enable with `org.gradle.configuration-cache=true` in `gradle.properties`. For preview features:
+`options.compilerArgs.add("--enable-preview")` plus `tasks.test { jvmArgs("--enable-preview") }`
+plus `application { applicationDefaultJvmArgs = listOf("--enable-preview") }`.
+
+## Multi-module
+
+- **Maven**: a parent `pom.xml` with `<packaging>pom</packaging>` and `<modules>`; share
+  versions via `<dependencyManagement>` / a BOM so every module agrees on a version.
+- **Gradle**: `settings.gradle.kts` with `include("api", "core")`; a `buildSrc` or version
+  catalog (`gradle/libs.versions.toml`) centralizes versions.
+
+## Dependency hygiene
+
+- Pin versions; use a BOM (`<dependencyManagement>` / Gradle platform) so transitive versions
+  agree.
+- Check for updates: `mvn versions:display-dependency-updates` or the Gradle versions plugin.
+- Scan for vulnerable dependencies in CI (OWASP dependency-check / your SCA tool).
+
+## jlink / jpackage (note only — shipping lives in `deployment`)
+
+`jlink` builds a minimal custom runtime image containing only the modules your app uses (small
+container base); `jpackage` wraps it into a native installer (.dmg/.msi/.deb). For Dockerfiles,
+CI, and release wiring see the `deployment` skill — this skill only points at the tools.

package/skills/java/references/concurrency.md

@@ -0,0 +1,108 @@
+# Virtual threads & structured concurrency (deep)
+
+Targets Java 21+ (virtual threads standard), Java 25 LTS for `ScopedValue` (JEP 506, final)
+and `StructuredTaskScope` (JEP 505, still **preview** — needs `--enable-preview`).
+
+## Why virtual threads change the model
+
+A virtual thread is an ordinary `java.lang.Thread` scheduled by the JVM onto a small pool of
+platform "carrier" threads. When it blocks on I/O, the JVM unmounts it and frees the carrier.
+Millions can exist. The consequence: **the thread-per-request model is fast again** — you no
+longer need reactive callbacks or hand-tuned pools to scale blocking I/O.
+
+The rules:
+
+- **One task, one virtual thread.** Submit each unit of work; do not pool virtual threads.
+- **Never size them to cores.** Cores matter for CPU work, which stays on platform threads.
+- **Use them for blocking calls** (JDBC, HTTP, file, RPC) — not for tight CPU loops.
+
+## Executor wiring
+
+```java
+try (var exec = Executors.newVirtualThreadPerTaskExecutor()) {
+    for (var task : tasks) exec.submit(task);
+} // close() blocks until every submitted task completes
+```
+
+A single `Thread.ofVirtual().start(r)` is fine for a one-off; the executor is for fan-out.
+`Thread.ofVirtual().name("worker-", 0).factory()` gives a named factory for diagnostics.
+
+## Pinning: the JEP 491 change
+
+Before JDK 24, a virtual thread inside a `synchronized` block **pinned** its carrier — it could
+not unmount, so heavy `synchronized` I/O code starved the carrier pool. **JEP 491 (JDK 24)
+removed this**: virtual threads no longer pin on `synchronized`. Two consequences:
+
+- Legacy `synchronized` code runs correctly on Loom now without rewriting to locks.
+- For **long** holds still prefer `ReentrantLock` — it offers `tryLock`, fairness, and
+  interruptible acquisition that `synchronized` does not.
+
+Diagnose remaining pinning (native frames, some JNI):
+
+```bash
+# JFR event jdk.VirtualThreadPinned fires on every pin; record and inspect.
+java -XX:StartFlightRecording=filename=app.jfr,settings=profile -jar app.jar
+jfr print --events jdk.VirtualThreadPinned app.jfr
+```
+
+## Structured concurrency (preview in 25)
+
+`StructuredTaskScope` binds subtasks to a lexical scope: fork children, join, then the scope
+guarantees all children finish or are cancelled before it closes. One failure cancels siblings.
+
+```java
+// Requires --enable-preview on Java 25 (JEP 505).
+// Joiner.awaitAllSuccessfulOrThrow(): all must succeed, else the first failure cancels the rest.
+import java.util.concurrent.StructuredTaskScope;
+
+UserPage load(String id) throws Exception {
+    try (var scope = StructuredTaskScope.open()) {           // 25-era API
+        var user  = scope.fork(() -> fetchUser(id));
+        var orders= scope.fork(() -> fetchOrders(id));
+        scope.join();                                        // wait for both
+        return new UserPage(user.get(), orders.get());
+    }
+}
+```
+
+The two canonical policies:
+
+- **All-success-or-fail** (fan-out where you need every result): first failure cancels siblings.
+- **Any-success** (race / hedged requests): first success cancels the slower siblings.
+
+Note: the exact joiner/factory names have shifted across the five previews. When you write this,
+confirm against the JDK you target (`java --enable-preview`) rather than trusting a fixed name.
+If you cannot enable preview, `ExecutorService` + `invokeAll`/`Future` on virtual threads gives
+most of the value without the lifecycle guarantees.
+
+## ScopedValue (final in 25) replaces ThreadLocal
+
+`ThreadLocal` is mutable, must be cleaned up (`remove()`), and its per-thread copies leak across
+millions of virtual threads. `ScopedValue` is **immutable** and bound only for the dynamic extent
+of a `run`/`call`, so it auto-unbinds and propagates into forked subtasks.
+
+```java
+private static final ScopedValue<RequestCtx> CTX = ScopedValue.newInstance();
+
+ScopedValue.where(CTX, ctx).run(() -> handle(req));   // CTX.get() anywhere in the call tree
+// Rebind for a nested extent:
+ScopedValue.where(CTX, child).run(() -> deeper());    // outer binding restored on return
+```
+
+Migration: a `ThreadLocal<T>` field set at the top of a request becomes a `ScopedValue<T>` bound
+once around the request body; every `tl.get()` becomes `sv.get()`; delete every `tl.remove()`.
+
+## CompletableFuture vs structured
+
+`CompletableFuture` composes async stages (`thenApply`, `thenCompose`) but has no scope: a leaked
+stage runs on. Prefer structured concurrency (or a virtual-thread executor with try-with-resources)
+for request-scoped fan-out so cancellation and lifetime are guaranteed. Keep `CompletableFuture`
+for pipeline-style composition where you genuinely want detached, chained stages.
+
+## When platform threads still win
+
+- **CPU-bound** work (parsing, compression, math): a `newFixedThreadPool(cores)` is correct;
+  virtual threads add no parallelism for compute.
+- **Throttling a scarce resource**: cap concurrency with a `Semaphore` acquired inside each
+  virtual task, not by shrinking a pool.
+- **FFI / JNI** that pins for long stretches: measure; keep it on a bounded platform pool.