routes: define the API versioning and deprecation policy

[joelpeace48-cell]

Problem

The prefix /api/v1 is configurable via API_PREFIX and there is no policy
behind it. Once gateways integrate, every change becomes a compatibility
question with no agreed answer, and the natural instinct — change it and tell
people — destroys the trust the product is selling.

What to do

• Write down what counts as breaking: removing a field, narrowing a type,
  changing an error code, tightening validation. Adding an optional field does
  not.
• Commit to a deprecation window with a concrete duration, and to Deprecation
  and Sunset response headers.
• Decide whether versions run in parallel, and for how long.
• Publish a changelog for the API specifically, separate from repo commits.
• Track per-version usage so a sunset decision is based on who is actually
  still calling it.

Acceptance criteria

• Breaking-change definition published
• Deprecation window committed with headers implemented
• API changelog published
• Per-version usage tracked

Notes

Usage tracking is what makes deprecation safe. Sunsetting a version because the
calendar says so, while a pilot partner is still on it, is an avoidable
self-inflicted incident.