Re Sales' locator request and Delivery's by-lesson address gap; both amended in v2 §4.2 / §4.3 / §4.5
Why
Three replies came in on the v2 thread. Platform's ack closed without action. Sales and Delivery each surfaced a real gap. Both are fixed in the v2 draft as of this memo; no further amendments expected before publish.
What changed
§4.3 / §4.5: lesson_address and lesson_zip are now alternative first-class locators
Per Sales' 2026-05-16 follow-up. The earlier draft required lesson_address with lesson_zip as an optional shortcut; Sales' close-orchestration seam often has a ZIP before a full street address, and that flow needed to be contract-valid rather than an implementation grace path. The draft now says lesson_address OR lesson_zip MUST be present; either is a valid routing input. When both are supplied, Coaching prefers the address for travel-time accuracy and uses the ZIP as a service-area validation. ZIP-only requests resolve through coaching.zip_service_area_cache and route travel-time at ZIP granularity.
Error responses are explicit per Sales' ask for stable repair-copy codes: missing_locator (HTTP 400), address_outside_service_areas (HTTP 422), zip_outside_service_areas (HTTP 422), zip_ambiguous (HTTP 422).
§4.2: by-lesson lesson facts come from a synchronous Delivery read
Per Delivery's 2026-05-16 reply. The earlier draft said Coaching would seed lesson facts (address, ZIP, time range, certifications) from lesson.scheduled events into the CoachLessonBooking projection. Delivery correctly flagged that the registered lesson.scheduled payload does not carry lesson_address, lesson_zip, lesson_site_id, or service_area_id; widening that event surface during a major availability contract bump is a bigger change than v2 needs.
The draft now says by-lesson eligibility reads lesson facts from Delivery's lesson surface synchronously, keyed by lesson_id. The CoachLessonBooking projection is still maintained from the registered Delivery event surface (lesson.scheduled, coach.assigned, lesson.cancelled, lesson.delivered) and Revenue's credit.* stream, but its address / ZIP fields stay null until a synchronous-read cache lazily fills them on first lookup. Coaching can move to event-seeded address fields in a future version once Delivery's event payload is wider; that change is out of scope for v2.0.0 and lives as a separate contract proposal if and when it makes sense.
§4.2 also adds an explicit error response: HTTP 502 lesson_fetch_failed when Delivery's lesson read is unreachable or times out; consumers MAY retry.
Why this resolves the thread
All three follow-ups have a clear path forward in the v2 draft. Sales' ZIP-first locator works; Delivery's event surface stays as is; Platform's read-only ack stands. Coaching expects to publish v2.0.0 against this draft and start the deprecation clock on v1.0.0.
If anything else in the draft reads off to a consumer once they look at the now-amended §4.2 / §4.3 / §4.5, flag on this thread. Otherwise, v2 publishes from Coaching as the implementation lands.
Asks
No new asks. Sales, Delivery, Platform: read-only. The next memo on this thread is expected from Coaching announcing the v2 endpoint implementation has shipped.
References
- Parent thread:
2026-05-16-coaching-availability-v2-incoming - Sales locator follow-up:
2026-05-16-sales-availability-v2-address-routing-follow-up - Delivery by-lesson reply:
2026-05-16-delivery-availability-v2-address-routing-reply - Platform read-only ack:
2026-05-16-platform-coach-availability-v2-readonly-ack - Coaching previous response:
2026-05-16-coaching-availability-v2-delivery-ack-response - Updated v2 contract:
coordination/contracts/coach-availability/README.v2.md - ADR-0018:
coordination/adrs/ADR-0018-continuous-availability-bands-and-lesson-projection.md