[Feature]: Performance Tuning Guide

[Splatcrafter]

Problem / Motivation

While docs/advanced/performance-optimization.md exists with general tips, users migrating large datasets need more detailed guidance:

• Concrete numbers from benchmarks
• Format-specific performance characteristics
• Memory tuning for large migrations
• Batch processing patterns

Proposed Solution

Enhance performance documentation with:

1. Benchmark Results

   • Published baseline numbers from JMH suite
   • Performance comparison across formats
   • Scaling characteristics

2. Memory Optimization

   • Heap sizing recommendations
   • GC tuning for migration workloads
   • Streaming vs. in-memory processing

3. Batch Processing Patterns

   • Rules.batch() usage examples
   • Parallel processing with parallelStream()
   • Chunking strategies for large files

4. Format Selection Guide

   • When to use Gson vs. Jackson
   • YAML vs. JSON trade-offs
   • Binary format considerations

API / Design Sketch (optional)

# Performance Tuning Guide

## Benchmark Baseline (v1.0.0)

|        Operation          | Payload Size |  Gson  | Jackson |        Notes        |
|---------------------------|--------------|--------|---------|---------------------|
| Single fix                | 1 KB         | 15 us  | 12 us   | Jackson ~20% faster |
| Single fix                | 100 KB       | 450 us | 380 us  |                     |
| 10-fix chain              | 1 KB         | 120 us | 95 us   |                     |
| Full migration (100->200) | 10 KB        | 2.1 ms | 1.8 ms  |                     |

## Memory Tuning

For migrations processing > 10,000 records:

java -Xmx4g -XX:+UseG1GC -XX:MaxGCPauseMillis=200 -jar my-app.jar

## Format Selection Guide

|    Format    |              Best For             |       Avoid When       |
|--------------|-----------------------------------|------------------------|
| Gson         | Simple JSON, small payloads       | Large files, streaming |
| Jackson JSON | Large files, performance critical | Minimal dependencies   |
| Jackson YAML | Config files, human-editable      | High-throughput        |
| SnakeYAML    | Native YAML features              | Performance critical   |



// Batch Processing Example
TypeRewriteRule batchRule = Rules.batch(
    Rules.renameField(ops, "oldName", "newName"),
    Rules.addField(ops, "newField", "defaultValue"),
    Rules.removeField(ops, "deprecatedField")
);

Alternatives / Workarounds

• Link to external resources: Generic, not Aether-specific
• No tuning guide: Users left to trial and error

Would this be a breaking change?

no

Priority (reporter estimate)

medium

Related Module

other / unknown

Checklist

• I checked existing issues and discussions for duplicates.
• This request is within the project's scope (not a support question).