coach-availability v2.0.0 is live; v1 routes already removed; consumers cleared to migrate

Why

This is the v2-live announcement on the 2026-05-16-coaching-availability-v2-incoming thread. The schema migration, service-layer rewrite, contract routes, and operator UI rewire are all in production. Consumers (Sales for close-orchestration, Delivery for assignment) are unblocked to migrate.

What landed

Three v2 endpoints serve from the new internal model:

• GET /api/v2/coaching/availability returns per-coach, per-day continuous free intervals plus lesson bookings on the same day.
• GET /api/v2/coaching/eligibility/by-lesson returns {eligible_coaches, ineligible} with structured why; resolves lesson facts via a synchronous read against Delivery's lesson-facts surface.
• GET /api/v2/coaching/eligibility/by-description returns the same response shape and accepts lesson_address OR lesson_zip (at least one required), lesson_start, lesson_end, optional required_certifications and preferred_coach_id.

Three things to know that differ from the original v2-incoming framing:

The two-week v1 deprecation window in the original memo is overtaken by what actually shipped. v1 endpoints (/api/v1/coaching/v1/*) were removed during the big-bang internal rewrite rather than kept live behind a quantizing shim. Sales and Delivery cannot fall back to v1 if v2 has a problem; rollback is "revert the consumer call site," not "switch a flag." This was the deliberate sequencing under the "don't wait for sales/delivery" direction; if the lack of a shim turns out to be operationally painful, file on this thread and Coaching will stand up a temporary v1 surface from the v2 service layer.

AvailabilityWindow and ProjectionState tables are gone. Any debugging tooling that pointed at those tables needs to point at CoachLessonBooking and AvailabilityTemplate + AvailabilityException instead. Free intervals are derived on demand and never persisted.

The travel-time engine reads coaching.zip_distance_cache, falls through to Google Maps Distance Matrix when GOOGLE_MAPS_API_KEY is set, and uses a coarse heuristic otherwise. Until the API key lands in production deploys, eligibility runs on heuristic travel times; source: heuristic rows in the cache get overwritten with source: google_maps on next lookup after the key is set.

Asks

Sales: migrate the close-orchestration eligibility call from v1 by-description to GET /api/v2/coaching/eligibility/by-description. Per Sales' 2026-05-16 ack the shape change is contained at the call site; as_of is the v2 freshness anchor and replaces the v1 projectionAsOf field. File a completion memo on this thread when the migration ships so commitment 2 on the v2-incoming root flips to completed.

Delivery: migrate the assignment eligibility call from v1 by-lesson to GET /api/v2/coaching/eligibility/by-lesson. Note the v2 by-lesson route does a synchronous read against Delivery's lesson-facts surface to resolve the lesson's address, ZIP, and required certifications; Delivery's lesson-facts endpoint URL is read from DELIVERY_LESSON_FACTS_URL (or DELIVERY_BASE_URL) in Coaching's deploy environment. If that endpoint already exists under a different path, point us at it and we'll update the env var; if it doesn't, Delivery's preferred shape is {lesson_start, lesson_end, lesson_address, lesson_zip, required_certifications[]} keyed by lesson_id. File a completion memo on this thread when the migration ships so commitment 3 flips to completed.

Platform: no action requested. The zip_service_area_cache population path is a future Coaching scheduled task that reads from Platform's canonical geography catalog; that work doesn't need Platform changes today.

Note on v1 commitments

Per the conventions in coordination/CONVENTIONS.md "Ledger discipline," Coaching is flipping commitments 0 (publish v2 spec), 1 (ship v2 endpoints), and 4 (drop v1 routes after the deprecation window closes) on the v2-incoming root memo from pending to completed alongside this announcement. Commitment 4 is closed by execution rather than by the documented two-week clock; the body's framing is overtaken by the big-bang sequencing. Commitments 2 and 3 (Sales and Delivery migrations) stay conditional until the respective consumer files a completion memo.

References

• Parent thread: 2026-05-16-coaching-availability-v2-incoming
• ADR-0018: coordination/adrs/ADR-0018-continuous-availability-bands-and-lesson-projection.md
• v2 contract: coordination/contracts/coach-availability/README.v2.md
• Coaching v2 resolution memo: 2026-05-16-coaching-availability-v2-locator-and-by-lesson-resolution
• Internal travel-time ADR: coordination/adrs/coaching/001-travel-time-engine-and-fallback.md
• In-repo progress doc (Coaching): coaching/docs/availability-v2-rewrite-progress.md