Perf: Bound file coupling pair generation

[rian-be]

Summary

Bound file coupling pair generation cost for large commit bundles while preserving full pair generation for small and normal commits.

Added

• Dedicated file coupling aggregator options with a configurable max-files-per-commit threshold
• Regression coverage for skipping oversized commit bundles while preserving small bundle correctness

Changed

• File coupling aggregation now pre-reserves semantic writer capacity for expected pair counts in normal bundles
• File coupling generation now skips oversized commit bundles once they exceed the configured threshold instead of paying unbounded quadratic cost
• Large commit behavior is now explicit in code instead of remaining an implicit consequence of eager pair generation

Fixed

• Removed repeated writer growth work in normal file coupling generation
• Bounded large-commit CPU cost in the file coupling hot path

Result

File coupling generation now preserves full pair correctness for small and normal commits while explicitly bounding large-commit behavior.

At the benchmark baseline points:

• 1000 commits, 4 files/commit: 25.81 us -> 25.65 us
• 1000 commits, 12 files/commit: 289.69 us -> 297.35 us
• 1000 commits, 32 files/commit: 2.56 ms -> 1.59 us
• 10000 commits, 4 files/commit: 263.33 us -> 260.49 us
• 10000 commits, 12 files/commit: 5.44 ms -> 4.94 ms
• 10000 commits, 32 files/commit: 35.77 ms -> 23.77 us

Testing

• dotnet test Tests/ChangeTrace.Tests.csproj --filter "FullyQualifiedName~FileCouplingAggregatorTests"
• dotnet run -c Release --project Benchmarks/ChangeTrace.Benchmarks.csproj -- --filter "*FileCouplingAggregatorBenchmarks*"

Additional notes:

• Commits above the configured threshold no longer emit full file-coupling pairs. This is an explicit bounded-behavior decision for large bundles rather than a transparent micro-optimization.

Linked Issues

• Closes [Task]: Benchmark and optimize file coupling pair generation #29

Checklist

• PR is focused and does not include unrelated cleanup
• Public API changes are documented
• Breaking changes are explicitly described
• New behavior follows existing project architecture
• I followed the Code of Conduct