Recent matchup spacing — formal guarantee

[javaisbetterthanpython]

Summary

Upstream: pickleball-shuffler#22

Formalize, test, and document recent matchup spacing on top of #30. The fork already has back-to-back penalties; this issue makes spacing a guaranteed, documented requirement and adds a tie-breaker among valid #30 options.

Rule (on top of #30)

Among round candidates that satisfy #30 session-wide no-repeat rules, prefer the option that maximizes the minimum "rounds since last seen" across all partner and opponent pairings in that round.

• Applies to partners and opponents equally.
• Fixed pairs exempt from partner spacing (always partnered).
• Fixed-pair players still follow opponent spacing with everyone else.

This is a tie-breaker / optimizer — not a separate hard window. Session-wide no-repeat remains owned by #30.

Deliverables

Automated tests

• Property tests over many seeds (8–28 players, varied courts)
• Assert maximize-minimum spacing among valid Richer session mix + instant next round #30 solutions
• Document mathematically unavoidable exceptions

User-facing docs

• README or in-app "How fairness works" section explaining recent spacing

Validation checklist

• New section in docs/VALIDATION.md with manual verification steps

Acceptance criteria

• Spacing tie-breaker implemented in round selection
• Fixed-pair exemptions consistent with Richer session mix + instant next round #30
• Tests pass in yarn test:ci
• User docs updated
• docs/VALIDATION.md updated
• yarn build passes

Files likely touched

• src/matching/heuristics.ts
• test/heuristics.spec.tsx
• README.md or in-app copy
• docs/VALIDATION.md

Dependencies

• Richer session mix + instant next round #30 (blocked — implement after session-wide no-repeat + pre-gen)

Upstream reference

• Reduce seeing the same person two games in a row if possible panathea/pickleball-shuffler#22