@cubis/foundry 0.3.67 → 0.3.68

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/java-pro/SKILL.md

@@ -3,61 +3,62 @@ name: "java-pro"
 description: "Use for modern Java backend and platform engineering with Java 25-era language/runtime practices."
 license: MIT
 metadata:
-  version: "1.0.0"
-  domain: "language"
-  role: "specialist"
-  stack: "java"
-  baseline: "Java SE 25"
+  author: cubis-foundry
+  version: "1.0"
+compatibility: Claude Code, Codex, GitHub Copilot
 ---
 # Java Pro
 
-## When to use
+## Purpose
+
+Expert-level guidance for modern Java backend and platform engineering. Covers records, sealed types, virtual threads (Project Loom), null handling, performance profiling, and production observability using current JDK practices.
+
+## When to Use
 
 - Building or modernizing Java backend services.
 - Designing JVM architecture for high-throughput systems.
-- Improving reliability, observability, and maintainability.
+- Improving reliability, observability, and maintainability of Java codebases.
+
+## Instructions
 
-## When not to use
+1. **Clarify runtime target and deployment constraints** — confirm the JDK baseline approved by project policy and deployment environment before choosing language features.
 
-- Frontend-only tasks with no JVM component.
-- Pure schema/index work better handled as database design or optimization.
-- Low-level native systems work where Rust/Go is the actual project stack.
+2. **Define module boundaries and API contracts** — separate domain, service, and infrastructure layers. Use records for immutable data carriers (API responses, DTOs, event payloads). Use sealed classes/interfaces for closed domain hierarchies with exhaustive pattern matching.
 
-## Core workflow
+3. **Implement with explicit null handling** — use `Optional<T>` for return types that may legitimately have no value, but never for parameters or fields. Use `@Nullable`/`@NonNull` annotations from JSpecify or Checker Framework. Fail fast with `Objects.requireNonNull()` at method entry. Do not return raw `null` from methods that could return `Optional` or empty collections because it creates silent NPE pathways.
 
-1. Clarify runtime target and deployment constraints.
-2. Define module boundaries and API contracts.
-3. Implement with clear domain/service/infrastructure separation.
-4. Add tests and performance checks for critical paths.
+4. **Use virtual threads for blocking I/O workloads** — HTTP calls, database queries, and file reads benefit from virtual threads via `Executors.newVirtualThreadPerTaskExecutor()`. Do not use virtual threads for CPU-bound work because they share carrier threads and cause starvation. Do not use `synchronized` blocks in virtual-thread code because it causes carrier-thread pinning — use `ReentrantLock` instead.
 
-## Baseline standards
+5. **Add structured logging and trace propagation** — capture request/job correlation IDs in logs and traces. Keep exception handling consistent between transport, service, and persistence layers. Do not expose stack traces in production responses.
 
-- Use current LTS/JDK baseline approved by project policy.
-- Prefer records/sealed hierarchies where they simplify modeling.
-- Keep null-handling explicit; avoid silent NPE pathways.
-- Use structured logging and trace propagation.
-- Enforce dependency and API compatibility checks in CI.
+6. **Enforce dependency and API compatibility checks in CI** — use current JDK tooling, static analysis, and dependency verification. Separate transport DTOs from domain and persistence models to reduce cascade failures.
 
-## Debugging and observability
+7. **Profile before optimizing** — use `jcmd`, `async-profiler`, or JFR for production diagnostics without restart. Profile GC behavior with `-Xlog:gc*` before tuning heap sizes. Use escape analysis awareness to avoid large short-lived objects in hot loops. Prefer explicit timeouts, bulkheads, and retry budgets at I/O boundaries.
 
-- Capture request/job correlation IDs in logs and traces.
-- Keep exception handling consistent between transport, service, and persistence layers.
-- Reproduce performance or memory issues with focused benchmarks/profilers before redesigning.
+8. **Add tests and performance checks for critical paths** — use JUnit 5, parameterized tests, and Testcontainers for integration testing. Do not use `Thread.sleep()` for retry logic because it blocks threads — use structured retry with backoff. Do not leak persistence entities directly into API contracts because it couples layers.
 
-## Performance and reliability
+9. **Do not use reflection-heavy magic when explicit code is clearer** because it hurts readability and debuggability. Do not build monolithic service classes with mixed responsibilities because they resist testing and change.
 
-- Prefer explicit timeouts, bulkheads, and retry budgets at I/O boundaries.
-- Keep thread/virtual-thread usage bounded and observable.
-- Separate transport DTOs from domain and persistence models to reduce cascade failures.
+## Output Format
+
+Produces Java code using records, sealed types, and modern JDK APIs with clear layer separation, explicit null handling, and structured error propagation. Includes virtual-thread-aware patterns where applicable.
 
 ## References
 
-| File | Load when |
-| --- | --- |
-| `references/operational-baseline.md` | You need current Java service guardrails for logging, testing, dependency hygiene, and runtime operations. |
+| File                                     | Load when                                                                                                |
+| ---------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `references/virtual-threads-patterns.md` | Virtual thread adoption, carrier pinning avoidance, or Loom migration patterns need detail.              |
+| `references/records-sealed-types.md`     | Record design, sealed hierarchy modeling, or pattern matching with switch expressions need detail.       |
+| `references/stream-api-patterns.md`      | Stream pipeline design, collector patterns, parallel stream tradeoffs, or functional idioms need detail. |
+| `references/modern-testing.md`           | JUnit 5 patterns, parameterized tests, Testcontainers, or test architecture decisions need detail.       |
+| `references/gc-and-allocation.md`        | GC tuning, allocation profiling, escape analysis, or memory-sensitive design decisions need detail.      |
+
+## Scripts
+
+No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
 
-## Avoid
+## Examples
 
-- Monolithic service classes with mixed responsibilities.
-- Reflection-heavy magic when explicit code is clearer.
-- Leaking persistence entities directly into API contracts.
+- "Migrate this blocking HTTP client code to use virtual threads with proper carrier-thread pinning avoidance."
+- "Refactor this service to use sealed classes and pattern matching instead of the visitor pattern."
+- "Design the null-handling strategy for this API layer using Optional returns and JSpecify annotations."

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/java-pro/references/gc-and-allocation.md

@@ -0,0 +1,164 @@
+# GC and Allocation Patterns
+
+## GC Collector Selection
+
+| Collector          | Best for                                      | Tuning priority                            |
+| ------------------ | --------------------------------------------- | ------------------------------------------ |
+| **G1GC** (default) | General-purpose, balanced latency/throughput  | Pause time target (`-XX:MaxGCPauseMillis`) |
+| **ZGC**            | Ultra-low latency (< 1ms pauses), large heaps | Heap size and allocation rate              |
+| **Shenandoah**     | Low latency, OpenJDK-only                     | Similar to ZGC                             |
+| **Parallel GC**    | Batch processing, throughput-first            | Throughput target (`-XX:GCTimeRatio`)      |
+
+```bash
+# G1GC with 200ms pause target
+java -XX:+UseG1GC -XX:MaxGCPauseMillis=200 -Xmx4g -jar app.jar
+
+# ZGC for low-latency services
+java -XX:+UseZGC -Xmx8g -jar app.jar
+
+# GC logging for diagnostics
+java -Xlog:gc*:file=gc.log:time,uptime,level,tags -jar app.jar
+```
+
+## Allocation Hotspot Patterns
+
+The fastest allocation is the one that doesn't happen. Reduce allocation pressure in hot paths.
+
+```java
+// BAD — allocates new String on every call via concatenation
+String buildKey(String prefix, long id) {
+    return prefix + ":" + id; // creates StringBuilder, intermediate strings
+}
+
+// GOOD — use StringBuilder explicitly or format once
+String buildKey(String prefix, long id) {
+    return prefix.concat(":").concat(Long.toString(id));
+}
+
+// BAD — autoboxing in loops creates Integer objects
+int sum = 0;
+for (Object item : list) {
+    sum += (Integer) item; // unboxing + potential boxing
+}
+
+// GOOD — use primitive streams
+int sum = IntStream.range(0, list.size())
+    .map(i -> ((Integer) list.get(i)).intValue())
+    .sum();
+```
+
+## Escape Analysis
+
+JVM escape analysis determines if an object can be allocated on the stack instead of the heap. Objects that "escape" the method (returned, stored in fields, passed to unknown methods) must be heap-allocated.
+
+```java
+// GOOD — Point does not escape, JVM may stack-allocate or scalar-replace
+double distance(double x1, double y1, double x2, double y2) {
+    var p = new Point(x2 - x1, y2 - y1); // may be eliminated by EA
+    return Math.sqrt(p.x() * p.x() + p.y() * p.y());
+}
+
+// BAD — object escapes via return, cannot be stack-allocated
+Point createDelta(double x1, double y1, double x2, double y2) {
+    return new Point(x2 - x1, y2 - y1); // escapes — heap allocated
+}
+
+// Things that defeat escape analysis:
+// - Returning the object
+// - Storing in a field or collection
+// - Passing to a non-inlined method
+// - Synchronized blocks on the object (in some cases)
+```
+
+## Object Pooling — When Justified
+
+Object pooling is rarely needed with modern GCs. Use it only for expensive-to-create resources:
+
+```java
+// JUSTIFIED — database connections, thread pools
+HikariConfig config = new HikariConfig();
+config.setMaximumPoolSize(20);
+config.setMinimumIdle(5);
+config.setConnectionTimeout(3000);
+HikariDataSource pool = new HikariDataSource(config);
+
+// NOT JUSTIFIED — simple objects
+// DON'T pool Strings, DTOs, collections — GC handles them efficiently
+```
+
+## Memory Profiling Tools
+
+```bash
+# JFR recording (built into JDK, low overhead)
+java -XX:StartFlightRecording=filename=recording.jfr,duration=60s -jar app.jar
+
+# jcmd for runtime diagnostics without restart
+jcmd <pid> GC.heap_info          # heap summary
+jcmd <pid> GC.run                # trigger GC
+jcmd <pid> VM.native_memory      # native memory tracker
+
+# async-profiler for allocation profiling
+./asprof -e alloc -d 30 -f alloc.html <pid>
+```
+
+## Common GC Problems and Fixes
+
+| Symptom               | Likely cause                            | Fix                                                        |
+| --------------------- | --------------------------------------- | ---------------------------------------------------------- |
+| Frequent young-gen GC | High allocation rate in hot paths       | Reduce allocations, use primitives, pool expensive objects |
+| Long full GC pauses   | Heap too small or too many live objects | Increase heap, switch to ZGC, find memory leaks            |
+| Old-gen filling up    | Memory leak or large caches             | Heap dump analysis, fix leaks, bound cache sizes           |
+| GC thrashing          | Heap nearly full, GC runs constantly    | Increase heap, reduce live object set                      |
+
+```java
+// Fix memory leak: unbounded cache
+// BAD
+private final Map<String, byte[]> cache = new HashMap<>();
+
+// GOOD — bounded LRU cache
+private final Map<String, byte[]> cache = new LinkedHashMap<>(100, 0.75f, true) {
+    @Override
+    protected boolean removeEldestEntry(Map.Entry<String, byte[]> eldest) {
+        return size() > 1000;
+    }
+};
+
+// BETTER — use Caffeine for production caches
+Cache<String, byte[]> cache = Caffeine.newBuilder()
+    .maximumSize(1000)
+    .expireAfterWrite(Duration.ofMinutes(10))
+    .recordStats()
+    .build();
+```
+
+## String Optimization
+
+```java
+// String deduplication (G1GC and ZGC)
+// JVM flag: -XX:+UseStringDeduplication
+// Automatically deduplicates char[] backing arrays of identical strings
+
+// Intern frequently repeated strings
+String region = rawRegion.intern(); // shares single instance across JVM
+
+// StringBuilder for loop concatenation
+StringBuilder sb = new StringBuilder(estimatedSize);
+for (String item : items) {
+    if (!sb.isEmpty()) sb.append(", ");
+    sb.append(item);
+}
+String result = sb.toString();
+
+// String.format vs concatenation vs StringBuilder
+// For hot paths: StringBuilder > concat > String.format
+// For cold paths: readability wins — use whatever is clearest
+```
+
+## Heap Dump Analysis Workflow
+
+1. Capture heap dump: `jcmd <pid> GC.heap_dump /tmp/heap.hprof`
+2. Open in Eclipse MAT or VisualVM
+3. Look at dominator tree — identifies objects retaining the most memory
+4. Check leak suspects report — MAT auto-detects common leak patterns
+5. Trace GC roots of suspicious objects to find the retention path
+6. Fix the leak (usually: unbounded cache, listener not removed, static collection growing)

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/java-pro/references/modern-testing.md

@@ -0,0 +1,264 @@
+# Modern Java Testing
+
+## JUnit 5 Fundamentals
+
+```java
+import org.junit.jupiter.api.*;
+import static org.junit.jupiter.api.Assertions.*;
+
+class UserServiceTest {
+
+    private UserService service;
+    private UserRepository mockRepo;
+
+    @BeforeEach
+    void setUp() {
+        mockRepo = mock(UserRepository.class);
+        service = new UserService(mockRepo);
+    }
+
+    @Test
+    @DisplayName("creates user with valid email")
+    void createsUserWithValidEmail() {
+        var request = new CreateUserRequest("alice", "alice@example.com");
+        when(mockRepo.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        User result = service.createUser(request);
+
+        assertAll(
+            () -> assertEquals("alice", result.name()),
+            () -> assertEquals("alice@example.com", result.email()),
+            () -> assertNotNull(result.id())
+        );
+        verify(mockRepo).save(any(User.class));
+    }
+
+    @Test
+    @DisplayName("rejects duplicate email")
+    void rejectsDuplicateEmail() {
+        when(mockRepo.existsByEmail("taken@example.com")).thenReturn(true);
+
+        assertThrows(DuplicateEmailException.class, () ->
+            service.createUser(new CreateUserRequest("bob", "taken@example.com"))
+        );
+    }
+}
+```
+
+## Parameterized Tests
+
+```java
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.*;
+
+class EmailValidatorTest {
+
+    @ParameterizedTest
+    @ValueSource(strings = {"user@example.com", "a@b.co", "user+tag@domain.org"})
+    void acceptsValidEmails(String email) {
+        assertTrue(EmailValidator.isValid(email));
+    }
+
+    @ParameterizedTest
+    @NullAndEmptySource
+    @ValueSource(strings = {"nope", "@missing.com", "spaces in@here.com"})
+    void rejectsInvalidEmails(String email) {
+        assertFalse(EmailValidator.isValid(email));
+    }
+
+    // CSV source for input/output pairs
+    @ParameterizedTest
+    @CsvSource({
+        "100, USD, $100.00",
+        "1500, EUR, €1,500.00",
+        "0, GBP, £0.00"
+    })
+    void formatsMoneyCorrectly(int amount, String currency, String expected) {
+        assertEquals(expected, MoneyFormatter.format(amount, currency));
+    }
+
+    // Method source for complex test data
+    @ParameterizedTest
+    @MethodSource("orderScenarios")
+    void calculatesShipping(Order order, BigDecimal expectedShipping) {
+        assertEquals(expectedShipping, shippingService.calculate(order));
+    }
+
+    static Stream<Arguments> orderScenarios() {
+        return Stream.of(
+            Arguments.of(orderWithTotal(50), new BigDecimal("5.99")),
+            Arguments.of(orderWithTotal(100), BigDecimal.ZERO), // free shipping
+            Arguments.of(internationalOrder(), new BigDecimal("15.00"))
+        );
+    }
+}
+```
+
+## Testcontainers for Integration Tests
+
+```java
+import org.testcontainers.containers.PostgreSQLContainer;
+import org.testcontainers.junit.jupiter.Container;
+import org.testcontainers.junit.jupiter.Testcontainers;
+
+@Testcontainers
+class UserRepositoryIT {
+
+    @Container
+    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16")
+        .withDatabaseName("testdb")
+        .withInitScript("schema.sql");
+
+    private UserRepository repository;
+
+    @BeforeEach
+    void setUp() {
+        var dataSource = createDataSource(
+            postgres.getJdbcUrl(),
+            postgres.getUsername(),
+            postgres.getPassword()
+        );
+        repository = new UserRepository(dataSource);
+    }
+
+    @Test
+    void persistsAndRetrievesUser() {
+        var user = new User("alice", "alice@example.com");
+        repository.save(user);
+
+        Optional<User> found = repository.findByEmail("alice@example.com");
+        assertTrue(found.isPresent());
+        assertEquals("alice", found.get().name());
+    }
+
+    @Test
+    void returnsEmptyForMissingUser() {
+        assertTrue(repository.findByEmail("nobody@example.com").isEmpty());
+    }
+}
+```
+
+## Test Architecture Layers
+
+| Layer           | Tests                                     | Tools                                     | Speed           |
+| --------------- | ----------------------------------------- | ----------------------------------------- | --------------- |
+| **Unit**        | Business logic, domain models, validators | JUnit 5, Mockito                          | Milliseconds    |
+| **Integration** | Repository, external API clients          | Testcontainers, WireMock                  | Seconds         |
+| **Slice**       | Controller endpoints, serialization       | Spring `@WebMvcTest`, `@DataJpaTest`      | Seconds         |
+| **End-to-end**  | Full application flow                     | `@SpringBootTest`, Testcontainers compose | Tens of seconds |
+
+```java
+// UNIT — fast, no I/O
+@Test void calculatesDiscount() {
+    var order = new Order(List.of(item(100), item(50)));
+    assertEquals(new BigDecimal("15.00"), discountService.calculate(order));
+}
+
+// SLICE — tests only the web layer
+@WebMvcTest(UserController.class)
+class UserControllerTest {
+    @Autowired MockMvc mvc;
+    @MockBean UserService userService;
+
+    @Test void returnsUser() throws Exception {
+        when(userService.findById(1L)).thenReturn(Optional.of(testUser()));
+
+        mvc.perform(get("/users/1"))
+            .andExpect(status().isOk())
+            .andExpect(jsonPath("$.name").value("alice"));
+    }
+}
+```
+
+## Assertion Best Practices
+
+```java
+// assertAll groups related assertions — reports all failures, not just the first
+assertAll("user properties",
+    () -> assertEquals("alice", user.name()),
+    () -> assertEquals("alice@example.com", user.email()),
+    () -> assertTrue(user.isActive())
+);
+
+// AssertJ for fluent, readable assertions
+import static org.assertj.core.api.Assertions.*;
+
+assertThat(users)
+    .hasSize(3)
+    .extracting(User::name)
+    .containsExactlyInAnyOrder("alice", "bob", "charlie");
+
+assertThat(result)
+    .isNotNull()
+    .satisfies(r -> {
+        assertThat(r.status()).isEqualTo(200);
+        assertThat(r.body()).contains("success");
+    });
+
+// Exception assertions with AssertJ
+assertThatThrownBy(() -> service.deleteAdmin())
+    .isInstanceOf(ForbiddenException.class)
+    .hasMessageContaining("cannot delete admin");
+```
+
+## Test Naming and Organization
+
+```java
+// Nested tests for grouping scenarios
+@Nested
+@DisplayName("when user is authenticated")
+class WhenAuthenticated {
+    @BeforeEach void login() { auth.login(testUser); }
+
+    @Test @DisplayName("can view profile")
+    void canViewProfile() { ... }
+
+    @Test @DisplayName("can update settings")
+    void canUpdateSettings() { ... }
+
+    @Nested
+    @DisplayName("and is an admin")
+    class AndIsAdmin {
+        @Test @DisplayName("can delete other users")
+        void canDeleteOtherUsers() { ... }
+    }
+}
+
+@Nested
+@DisplayName("when user is anonymous")
+class WhenAnonymous {
+    @Test @DisplayName("is redirected to login")
+    void redirectsToLogin() { ... }
+}
+```
+
+## Virtual Threads in Tests
+
+```java
+// Test virtual-thread-based code with real virtual threads
+@Test
+void handlesVirtualThreadConcurrency() throws Exception {
+    var service = new OrderService(testRepo);
+    int concurrency = 1000;
+    var latch = new CountDownLatch(concurrency);
+    var errors = new ConcurrentLinkedQueue<Throwable>();
+
+    try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+        for (int i = 0; i < concurrency; i++) {
+            int orderId = i;
+            executor.submit(() -> {
+                try {
+                    service.processOrder(orderId);
+                } catch (Throwable t) {
+                    errors.add(t);
+                } finally {
+                    latch.countDown();
+                }
+            });
+        }
+        assertTrue(latch.await(30, TimeUnit.SECONDS));
+    }
+
+    assertTrue(errors.isEmpty(), "Errors: " + errors);
+}
+```

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/java-pro/references/records-sealed-types.md

@@ -0,0 +1,149 @@
+# Records and Sealed Types
+
+## Record Design
+
+Records are transparent, immutable data carriers. They auto-generate `equals`, `hashCode`, `toString`, accessors, and a canonical constructor.
+
+```java
+// Basic record — ideal for DTOs, API responses, events
+public record UserResponse(long id, String name, String email, Instant createdAt) {}
+
+// Compact canonical constructor for validation
+public record EmailAddress(String value) {
+    public EmailAddress {
+        if (value == null || !value.contains("@")) {
+            throw new IllegalArgumentException("Invalid email: " + value);
+        }
+        value = value.toLowerCase().strip(); // reassign for normalization
+    }
+}
+
+// Record with custom method
+public record Money(BigDecimal amount, Currency currency) {
+    public Money add(Money other) {
+        if (!this.currency.equals(other.currency)) {
+            throw new IllegalArgumentException("Currency mismatch");
+        }
+        return new Money(this.amount.add(other.amount), this.currency);
+    }
+}
+
+// Record implementing interface
+public sealed interface ApiResult<T> permits Success, Failure {
+    record Success<T>(T data) implements ApiResult<T> {}
+    record Failure<T>(String error, int code) implements ApiResult<T> {}
+}
+```
+
+## Record Anti-Patterns
+
+```java
+// DON'T override equals/hashCode unless domain semantics differ from structural equality
+// Records already provide correct implementations
+
+// DON'T use records for mutable state or entities with identity
+// BAD — entities need identity-based equality, not structural
+public record User(long id, String name) {} // equals compares all fields
+// Two users with same name but different IDs would be "equal" — wrong
+
+// DON'T use records with mutable fields
+// BAD — list can be modified, breaking immutability contract
+public record Config(List<String> hosts) {}
+config.hosts().add("evil.com"); // mutates the record!
+
+// GOOD — defensive copy in compact constructor
+public record Config(List<String> hosts) {
+    public Config {
+        hosts = List.copyOf(hosts); // immutable copy
+    }
+}
+```
+
+## Sealed Classes and Interfaces
+
+Sealed types restrict which classes can extend/implement them. Combined with pattern matching, they enable exhaustive handling.
+
+```java
+// Sealed interface — closed hierarchy
+public sealed interface Shape permits Circle, Rectangle, Triangle {
+    double area();
+}
+
+public record Circle(double radius) implements Shape {
+    public double area() { return Math.PI * radius * radius; }
+}
+
+public record Rectangle(double width, double height) implements Shape {
+    public double area() { return width * height; }
+}
+
+public record Triangle(double base, double height) implements Shape {
+    public double area() { return 0.5 * base * height; }
+}
+
+// Exhaustive pattern matching — compiler error if a variant is missing
+String describe(Shape shape) {
+    return switch (shape) {
+        case Circle c     -> "Circle with radius " + c.radius();
+        case Rectangle r  -> "Rectangle " + r.width() + "x" + r.height();
+        case Triangle t   -> "Triangle with base " + t.base();
+        // No default needed — sealed type is exhaustive
+    };
+}
+```
+
+## Pattern Matching with Switch Expressions
+
+```java
+// Type pattern matching
+Object process(Object input) {
+    return switch (input) {
+        case Integer i when i > 0  -> i * 2;
+        case Integer i             -> 0;
+        case String s              -> s.toUpperCase();
+        case List<?> list          -> list.size();
+        case null                  -> "null input";
+        default                    -> "unknown: " + input;
+    };
+}
+
+// Record pattern destructuring (Java 21+)
+String formatResult(ApiResult<?> result) {
+    return switch (result) {
+        case ApiResult.Success(var data) -> "OK: " + data;
+        case ApiResult.Failure(var error, var code) -> "Error %d: %s".formatted(code, error);
+    };
+}
+
+// Nested record patterns
+record Point(int x, int y) {}
+record Line(Point start, Point end) {}
+
+boolean isHorizontal(Line line) {
+    return switch (line) {
+        case Line(Point(_, var y1), Point(_, var y2)) when y1 == y2 -> true;
+        default -> false;
+    };
+}
+```
+
+## Sealed Hierarchy vs Enum
+
+| Use                           | Sealed hierarchy                         | Enum                                         |
+| ----------------------------- | ---------------------------------------- | -------------------------------------------- |
+| Variants carry different data | Yes — each record has its own fields     | No — enum constants share the same field set |
+| Need instances                | Yes — multiple `Circle(5)`, `Circle(10)` | No — fixed set of singleton constants        |
+| Pattern matching              | Yes — destructure record fields          | Yes — but only on constant identity          |
+| Serialization                 | Custom per variant                       | Built-in `name()`/`valueOf()`                |
+
+```java
+// Enum — fixed set with no per-instance data
+public enum Status { PENDING, ACTIVE, SUSPENDED, DELETED }
+
+// Sealed hierarchy — variants with different shapes
+public sealed interface PaymentMethod permits CreditCard, BankTransfer, Wallet {
+    record CreditCard(String last4, YearMonth expiry) implements PaymentMethod {}
+    record BankTransfer(String iban, String bic) implements PaymentMethod {}
+    record Wallet(String walletId, BigDecimal balance) implements PaymentMethod {}
+}
+```