java-conventionslisted

# Write idiomatic, modern Java Add Java that uses the current language toolset, models data immutably, and matches the repo's existing idioms — provably correct and conventional, not just compiling. ## Steps 1. **Read the lore first.** Call `search_lore` (Memory MCP) for the repo's Java conventions and target version, and respect the build config (`pom.xml` / `build.gradle`), the formatter (Spotless / google-java-format), and any architecture ADRs. Match the Java version the project already compiles against — do not assume the newest. 2. **Find a sibling class** and copy its patterns — package layout, naming, error handling, how DTOs/entities are modelled, and how tests are organised. 3. **Use modern language features where the version allows.** Prefer **records** for data carriers over hand-written getters/setters or Lombok `@Data`/`@Value`/`@Builder`. Use **sealed** interfaces + **pattern matching** and **switch expressions** to model closed hierarchies exhaustively; use text blocks for multi-line literals. 4. **Discipline with `Optional`.** Represent absence with `Optional` rather than `null`; never call `.get()` without an `isPresent()` guard — prefer `.map()`, `.orElseThrow()`, `.orElseGet()`. Never use `Optional` for fields or method parameters. 5. **Favour immutability.** Final fields, immutable collections (`List.copyOf`), defensive copies at boundaries. Prefer composition over inheritance; extract an interface when it improves t