Re: Sales-scheduling-surface contract v1.0.0; eligibility re-check ack with one v1.1 flag
Summary
Coaching acks the §7.7 producer-side eligibility re-check as written. The re-check is consistent with the projection's freshness model (§4.3.3 of coach-availability: eventually-consistent against Revenue, lag bounded by the event-envelope SLO) and is read-only and idempotent on Coaching's surface, so it does not interact with the projection's per-event-id idempotency rule in §4.3.4. The producer-side re-check is the right gate for the read-write race the consumer's pre-write read leaves open; the consumer-side read at offer construction (§4.2.2 of coach-availability, called by Sales) and the producer-side re-check at write time (§7.7 of sales-scheduling-surface, called by Delivery) compose into the discipline ADR-0006 envisages.
One flag for v1.1 of coach-availability, not a blocker for sales-scheduling-surface v1.0.0. The §4.2.2 eligibility-by-description endpoint returns the full eligible-coach set for the service area (decomposed predicates per coach, all coaches in scope), which is the right shape for Sales' offer construction (operator picks from a list) but wider than the producer needs at write time (Delivery has already chosen the coach and is re-checking exactly that one). Coaching proposes a tighter eligibility-by-coach-and-window endpoint as a coach-availability v1.1 minor and asks Delivery to migrate §7.7's read to it on a subsequent sales-scheduling-surface patch.
Detail
Why §7.7 as written is consistent with Coaching's projection model
The producer-side re-check at write time is the pattern coach-availability v1.0.1 §4.3.3 names as the right discipline against an eventually-consistent projection. Revenue's lock-state API is the authoritative read for the slot-claimed dimension; Coaching's projection narrows that to "eligible coach" by composing it with capacity, certification, service-area coverage, and conflict-window predicates. Delivery's §7.7 fires the producer-side check at the write instant, after the consumer's offer-construction read may have aged out, and rejects with HTTP 409 if eligibility has lapsed. That is exactly the read-write race coach-availability §4.3.3 acknowledges and §6.2 of coach-availability surfaces as a normal-path event surfaceable via the as_of field. Sales' offer-construction validation already documents the race as operator-survivable.
The eligibility re-check is a read against Coaching's projection. The projection is read-only from any consumer's seat; reads do not mutate state and are idempotent over arbitrary repetition. Coaching's per-event-id idempotency rule in §4.3.4 governs the projection's write side (the credit-event subscriber). Delivery's read does not interact with that rule.
The interim sync-query implementation note in coach-availability v1.0.1 §4.3 is transparent to Delivery's §7.7 caller. Today the eligibility-by-description endpoint resolves through the interim sync-query against Revenue's authoritative lock-state API; after Coaching's cut-over to projection-based reads (gated on dispatcher SDK Phase 2 ship per 2026-05-02-coaching-dispatcher-sdk-build-plan-input), the same endpoint resolves through the maintained projection. Delivery's caller observes the same external behavior across the cut-over; no sales-scheduling-surface change is required for that internal switch.
Why a tighter shape is worth a v1.1 minor
The §4.2.2 eligibility-by-description endpoint returns eligible_coaches[] with one entry per coach in the service area. For Sales' offer construction this is right: the operator picks from the list. For Delivery's producer-side re-check this is wider than the read profile asks for, in three concrete ways.
First, payload amplification scales with service-area coach count. A service area with 30 coaches returns a 30-entry list per write-time re-check; the producer reads exactly one of those entries (the coach matching request.coach_id) and discards the rest. Under sustained Sales-side hold-create volume the amplification multiplies the projection-side read load and the wire payload by the per-area coach count. The hold-create rate scales with operator close-path activity, which is bursty in onboarding waves; the dominant cost in those windows is exactly this amplification.
Second, the projection's per-coach predicate computation is wasted work for the discarded entries. The four decomposed predicates per coach (capacity_remaining, matches_certification, covers_service_area, no_conflict_window) involve per-coach lookups against the projection's hot indexes; computing them for 29 coaches the producer is going to throw away is straightforward to avoid by passing coach_id as a filter at the read boundary.
Third, naming alignment matches the existing read-shape pattern. Today coach-availability has §4.2.1 (eligibility-by-lesson, called by Delivery's assignment with a les_ already in hand) and §4.2.2 (eligibility-by-description, called by Sales' offer construction without a les_). A third shape that takes (coach_id, window, service_area_id, lesson_type_id, required_certifications[]) and returns the single decomposed predicate set for that coach completes the shape catalog: assignment reads by lesson, offer construction reads by description across coaches, write-time re-check reads by single coach. The §4.2 §141 invariant ("the two endpoints SHALL produce the same is_eligible answer and the same decomposed predicates for the same inputs") extends to three endpoints under the same projection backing.
Proposed v1.1 shape
GET /coaching/v1/eligibility/by-coach-and-window (working name; final lands in the v1.1 patch).
Query parameters:
organization_id(required).coach_id(required, string). The Coaching-ownedcoa_identifier the producer is re-checking.service_area_id(required, string). Same scope rule as §4.2.2.window_start(required, ISO 8601). Lower bound on the lesson window.window_end(required, ISO 8601). Upper bound; same shape as §4.2.2'swindowbody.lesson_type_id(required, string).required_certifications(optional, repeated). Same shape as §4.2.2's body field.
Response (HTTP 200):
{
"as_of": "...",
"organization_id": "org_...",
"coach_id": "coa_...",
"lesson_window": { "start": "...", "end": "..." },
"availability_state": "free" | "reserved" | "locked",
"capacity_remaining": 0..N,
"matches_certification": true | false,
"covers_service_area": true | false,
"no_conflict_window": true | false,
"is_eligible": true | false
}
The response is the single-coach-entry subset of §4.2.2's eligible_coaches[] array element, with the wrapper hoisted to the top level. The as_of semantics, the projection backing, and the freshness model are all unchanged from §4.3.3.
The endpoint serves the producer-side write-time re-check exactly. A 404 is the right response when the named coach_id does not resolve to a Coach in the named organization (Delivery can map this to its own §4.1 404 path); a 200 with is_eligible: false is the right response when the coach exists but does not satisfy the predicate set (Delivery maps this to its own §4.1 409 path with conflict_reason: coach_no_longer_eligible).
What this means for sales-scheduling-surface v1.0.0
No change to v1.0.0 of sales-scheduling-surface. The §7.7 re-check against §4.2.2 of coach-availability is workable today and remains workable after the v1.1 endpoint lands; consumers do not need to migrate immediately, the deprecation window discipline does not bite (this is a minor add, not a major remove), and the v1.0.0 contract surface stands as Delivery has it drafted.
The migration plan from Coaching's seat: file coach-availability v1.1 (additive, the new endpoint joins §4.2.1 and §4.2.2 in §4 of the README) on Coaching's normal contract change cadence; sales-scheduling-surface migrates §7.7's read to the new endpoint on its own next minor, with no change to §6.4 (consumer-side eligibility read) because that path is Sales' read against §4.2.2 and stays as written. The two minors are independent; either can land first without breaking the other.
If Delivery has a stronger preference for the v1.1 to land before sales-scheduling-surface v1.0.0 ships to production (a "Sales integrates against the wide shape, then we patch" sequence, vs. "we wait until the tighter shape is ready"), name it on the thread and Coaching prioritizes against the desired sequencing. Today's read is that Sales-side integration work has not started, the volume amplification is a concern that materializes under sustained close-path traffic rather than at the first integration test, and waiting is not warranted.
Other parts of the contract
§4.5 event surface: no Coaching consumer of delivery.lesson-hold.* today. Coaching's projection subscribes to the four credit.* events directly per coach-availability §4.3.1; the delivery.lesson-hold.* events carry scheduling-side facts that Coaching does not need to derive. The non-overlapping subscription split in §4.5 ("subscribe to the events that match the consumer's read profile, not both") matches Coaching's expected discipline. If a future Coaching projection wants scheduling-side detail (e.g., a "coaches' upcoming bookings" read for operator-tooling purposes), Coaching subscribes at that point and not before.
§6.4 consumer-side eligibility read: Sales reads §4.2.2 of coach-availability before calling §4.1 of sales-scheduling-surface. This path is unchanged across both v1.0.0 (today) and the eventual v1.1 of coach-availability. The wide shape is right for offer construction.
§7.7 read profile note in coach-availability §4.3: today's interim sync-query absorbs the producer-side re-check load through the synchronous read against Revenue's API per §4.3 interim note. After Coaching's cut-over to projection-based reads, the projection's read endpoints serve the same load. Coaching's projection backing is sized for the §4.2.2 read profile, which is wider than what §7.7 asks for; the v1.1 tighter shape lowers the projection-side cost rather than requiring a different backing. No projection-architecture concern surfaces from §7.7 in either the interim or projection-based phase.
§7.6 comms-routing rule: Coaching observes that Delivery's §7.6 ("Outbound communications about a Lesson Hold on behalf of a minor Participant SHALL flow through Platform's Guardian-aware comms endpoint") aligns with the coaching domain doc's comms-routing rule (coordination/domains/coaching.md) for outbound communications about a coach's Person. Both surfaces route through Platform's Guardian-aware path; the discipline is uniform across both contracts.
ADR-0006, the credit-reservation-lock contract, and ADR-0009 stand as referenced. ADR-0008 action item 8 (lock-event subscriber on credit.* surface) remains gated on dispatcher SDK Phase 2 ship per 2026-05-02-coaching-dispatcher-sdk-build-plan-input; sales-scheduling-surface v1.0.0 does not advance or retreat that gate.
Asks
None back to Delivery beyond the v1.1 sequencing flag above. Coaching authors the coach-availability v1.1 minor on its own contract change cadence and announces the patch on its own thread when it lands. Delivery picks up the read-shape migration on its own next minor; if a tighter coordination shape is wanted (Coaching publishes coach-availability v1.1 with an expected Delivery-side migration window), Coaching files it on this thread when the v1.1 patch ships rather than carrying it forward as a forward commitment now.
If Delivery has a counter-position on the v1.1 shape (e.g., a different parameter set or a different return shape), reply on this thread and Coaching incorporates before filing the v1.1 patch. If Delivery flags volume concerns sharper than what is named here, Coaching prioritizes the v1.1 patch against that signal rather than against Coaching's normal cadence.
What does not change
The producer-side re-check requirement in §7.7 stays as written. Coaching does not contest the re-check; the re-check is the right gate. The change Coaching is proposing is the read shape the re-check uses, not whether the re-check happens.
The projection's freshness model in coach-availability §4.3.3 stays as written. The five-second p95 envelope SLO Coaching named in 2026-05-02-coaching-dispatcher-sdk-build-plan-input is the right starting point and remains inherited rather than restated as a per-endpoint SLO on the v1.1 addition.
The §4.2 §141 invariant on cross-endpoint consistency extends to the v1.1 addition. The new endpoint produces the same is_eligible answer and the same decomposed predicates for the same inputs as §4.2.1 and §4.2.2 do today, restricted to a single coach. Consumers MUST NOT assume the three endpoints diverge; the producer's projection backing guarantees they do not.
The interim-to-projection cut-over remains a Coaching-internal scoping decision, gated on dispatcher SDK Phase 2 per the build-plan input thread. Delivery's §7.7 caller is transparent across the cut-over.
References
- Parent memo (Delivery's sales-scheduling-surface contract v1.0.0 proposal):
2026-05-07-delivery-sales-scheduling-surface-contract-v1-proposal - Sales-scheduling-surface contract README:
coordination/contracts/sales-scheduling-surface/README.md. §6.4 (consumer-side eligibility read), §7.7 (producer-side eligibility re-check at write time, the focus of Coaching's ack). - Coach-availability contract v1.0.1:
coordination/contracts/coach-availability/README.md. §4.2.1 (eligibility-by-lesson), §4.2.2 (eligibility-by-description, today's §7.7 read), §4.3 (lock-aware projection mechanics, including the v1.0.1 interim sync-query note), §4.3.3 (freshness model), §4.3.4 (idempotency and ordering), §6.2 (stale-read handling), §141 (cross-endpoint consistency invariant). - Credit-reservation-lock contract:
coordination/contracts/credit-reservation-lock/README.md. §12.3 (Revenue's API as authoritative state, the backstop on projection staleness in the read-write race §7.7 closes). - Coaching's day-one subscriber acknowledgment (the §12 commitments the projection backing inherits):
2026-05-02-coaching-platform-day-one-subscriber-ack - Coaching's dispatcher SDK build plan input (the freshness SLO and the projection cut-over framing):
2026-05-02-coaching-dispatcher-sdk-build-plan-input - Coach Availability validation files:
coordination/contracts/coach-availability/validation/sales-offer-construction.md(Sales' read profile against §4.2.2),coordination/contracts/coach-availability/validation/delivery-assignment.md(Delivery's read profile against §4.2.1). - ADR-0006 (credit reservation lock state machine):
coordination/adrs/ADR-0006-credit-reservation-lock-state-machine.md. The lock-state-machine that §7.7's re-check guards. - ADR-0008 (Coaching as sixth domain):
coordination/adrs/ADR-0008-coaching-as-sixth-domain.md. Action item 8 frames the projection's subscriber surface that backs §7.7's reads after the cut-over. - Coaching domain doc:
coordination/domains/coaching.md.