Three positions on Revenue's lock-state API spec; lesson-keyed redirect accepted, no hard Q2 floor, and reserving the right to skip the interim if Platform's SDK arrives first
Why
Revenue's 2026-05-02 reply specified the lock-state API surface for Coaching's interim sync-query reads, redirected the endpoint shape from coach-keyed to lesson-keyed, and asked Coaching for two things: a date floor on when the live API needs to be ready, and confirmation of the lesson-keyed redirect. This memo answers both, plus surfaces a meta-question on the interim shape's value that Revenue's planning posture should account for before committing build cycles. Platform's auth-model confirmation is its own ask and is not answered here.
What
Position 1: lesson-keyed redirect accepted
Revenue's redirect is correct. Coaching's availability composition flow already pulls a lesson catalog as part of resolving (coach, window, service area) into a set of (coach_id, lesson_id) pairs that the eligibility predicate runs over. The lesson_ids fall out of that composition naturally. Asking Revenue to maintain a coach-to-lesson index would put cross-domain mapping on the wrong side and would invert the post-split ownership boundary that ADR-0008 just established (Coach moved to Coaching; lesson_id resolution stays Delivery's, with Coaching reading the lesson catalog at composition time).
The redirect does mean Coaching's contract endpoint implementation does one extra step before calling Revenue: resolve the requested availability window into the lesson_ids whose reservations might affect the slot. That step is local-to-Coaching (or at most a Coaching-to-Delivery read that Coaching needs to do anyway for the eligibility surface). It is not a new cost; it surfaces a step that was always implicit in the composition.
The 1000-id ceiling on lesson_ids[] per call is acceptable for v1. Coaching's typical read profile is per-window (a service area at a time, a few hundred lessons in the worst case); the ceiling has headroom over the typical load. If Coaching's actual usage pushes past it during the instrumentation window Revenue called out, Coaching scopes a POST variant or paginates the lesson_ids client-side; Revenue's offer to scope a POST variant on demand is the right backstop.
The state set (reserved, locked, released, forfeited, consumed) and the response shape (per-reservation rows with credit_reservation_id, lesson_id, person_id, state, funding_sub_state, lesson_starts_at, lesson_ends_at, reserved_credits, state_at, plus the missing_lesson_ids list and as_of timestamp) all read correctly. Coaching's contract endpoint passes through credit_reservation_id to consumers per coach-availability §4.1 as drafted. funding_sub_state is fine to expose even though Coaching does not consume it; other consumers will want it and the cost is zero.
Position 2: no hard Q2 date floor, accept Q3 cadence and the spec-first approach
Coaching does not have a date floor in 2026-05 or 2026-06 that would justify displacing one of Revenue's Q2 rocks (Auth SDK adoption, ledger reconciliation parity, refund flow rebuild, automated reconciliation). The contract is published and Sales has signed off, but no commercial deadline drives stand-up. No enterprise customer is waiting on Coaching as a separately-deployed service; the existing Delivery-internal coach surface continues to serve Sales' offer-construction reads through the dual-state path documented in 2026-05-01-sales-coaching-availability-ack and 2026-05-08-sales-coach-availability-v1-signoff. The cost of Q3 cadence on the API build is that Coaching's stand-up moves to Q3 also; that cost is acceptable.
Revenue's spec-first approach is the right intermediate move: publish the detailed implementation-level spec (request and response schemas as TypeScript types, validation rules, error codes, OpenAPI doc) within the 2026-05-15 window, defer the build to Q3. Coaching commits to scaffolding coaching/app/api/v1/eligibility/by-lesson/route.ts and coaching/app/api/v1/eligibility/by-description/route.ts plus delivery/lib/coaching-client.ts against that spec during the gap, so the integration code is ready when Revenue's API ships. The scaffold uses interfaces that match Revenue's published types; runtime calls hit a stub or feature flag until the API is live.
The Q3 build slot is Revenue's call to scope. Coaching will not push for an earlier slot absent a commercial driver. If a commercial driver appears (an enterprise prospect requiring Coaching as a separately-deployed service, a Q2 marketing commitment that depends on Coaching being live), Coaching files a fresh memo with the driver and the org-level prioritization conversation runs at that point.
Position 3: reserving the right to skip the interim if Platform's SDK arrives first or close to it
Both Platform's dispatcher SDK and Revenue's lock-state API are unscoped builds today. Platform's commitment in 2026-05-01-platform-dispatcher-sdk-gap-and-interim-shape opens an SDK-build planning thread within two weeks (so by 2026-05-15) with a dated commitment. Revenue's commitment in the parent memo is to a Q3 build absent a date floor.
If Platform's SDK ships before or around the same time as Revenue's API, the interim sync-query shape becomes work that gets thrown away. The contract endpoints stay (no change in what consumers see); the endpoint implementation flips from "call Revenue's API" to "read the local projection." The throwaway is the Revenue-side HTTP integration code in Coaching's repo (a few hundred lines of TypeScript) plus whatever request-coalescing or short-cache layer Coaching builds at the contract endpoint to mitigate Revenue's read load. That throwaway is bounded but is real, and asking Revenue to ship the lock-state API specifically to support an interim that may not be needed is a worse outcome than waiting on the SDK.
Coaching's position: Revenue should publish the detailed spec by 2026-05-15 (cheap, and produces a useful artifact regardless), and Revenue should hold the API build itself until Platform's SDK planning thread lands. When Platform's planning thread provides a dated SDK commitment, Coaching and Revenue jointly decide:
If Platform's SDK consumer-readiness milestone is more than 6 weeks past Revenue's earliest API ship date, Revenue ships the API and Coaching does the interim. The interim runs for the gap and Coaching migrates to projection-based reads when the SDK lands.
If Platform's SDK consumer-readiness is within roughly 2 to 6 weeks of Revenue's earliest API ship date, Coaching proposes skipping the interim. Revenue holds the API build (it is still useful for other future consumers, but it is not on the critical path for Coaching's stand-up), and Coaching waits for the SDK and goes straight to projection-based reads.
If Platform's SDK is genuinely Q4 or later, the interim is unambiguously worth building and Revenue ships the API on the Q3 plan.
The 6-week threshold is heuristic. Coaching uses the actual numbers from Platform's planning thread plus Revenue's build estimate to decide. The point of this position is that Revenue should know the build is conditional on Platform's timeline before scoping it as if the interim is definitely needed.
Capacity posture acknowledged
The 5 to 15 second cache TTL recommendation lands as the right shape. Coaching's contract endpoints will implement a request-coalescing plus short-cache layer (TTL 10 seconds proposed, configurable) before the interim goes live. The two trigger thresholds Revenue named (p99 > 200ms sustained, or > 100 RPS per tenant in production) are reasonable and Coaching agrees to instrument both consumers (Sales offer-construction and Delivery coach-day planner) from day one. Numbers go on Platform's SDK planning thread and on a follow-up memo to Revenue if either threshold trips.
Auth model
Coaching's preference (service-to-service bearer token issued by Platform's identity service) and Revenue's specified auth model agree. The condition Revenue named (if Platform's issuer is more than a quarter from production-ready, Revenue takes a temporary shared-secret bridge) is a Platform-facing question; Coaching defers to Platform's reply on the issuer timeline rather than pre-empting it.
Asks
Revenue: confirm or push back on the three positions above. Specifically: (1) accept that the lesson-keyed redirect is settled, (2) accept Q3 cadence on the API build with the spec-first publish by 2026-05-15, (3) accept the conditional-on-Platform-SDK-timeline posture for the build itself. The third is the one that may need pushback; if Revenue would rather size and commit the API build independent of Platform's SDK timeline (because the API has value for future consumers beyond Coaching, or because the dependency makes Q3 planning harder), name that and Coaching defers to the build-anyway path with the timing trade-offs accepted.
Platform: ack the auth-model confirmation Revenue asked for, on the parent dispatcher-SDK thread or on this one. Either thread works; Coaching tracks the response in either location.
Sales: no asks. Sales' production reads-per-offer numbers, if they exist, would calibrate the capacity question once Revenue's API is live. If Sales has them now and they are easy to share, the answer goes on this thread or on a fresh sales-to-revenue memo. If they require pulling, defer until the API is closer to ship.
Soft response 2026-05-15 to align with the parent thread and the dispatcher-SDK thread.
What Delivery does next
Action items 7 and 8 of ADR-0008 stay blocked on the two upstream builds (Platform SDK, Revenue lock-state API). Action item 9 stays N/A. Action item 10 waits.
Coaching scaffolds the contract endpoints (coaching/app/api/v1/availability/route.ts and the two eligibility variants) plus delivery/lib/coaching-client.ts against Revenue's published spec when it lands, with stub or feature-flagged runtime behavior until either upstream build is live. That scaffold is bounded local work (no external dependencies, no other domain blocked on it) and Coaching may pick it up while waiting on the upstream builds rather than letting the workstream sit idle.
If Coaching surfaces during the scaffold work that the published Revenue spec is missing something the contract endpoints actually need (a field that the response should include, a query parameter Coaching needs that Revenue's spec did not name), the discovery lands as a fresh memo on this thread or as an inline question on Revenue's spec PR.
References
- Revenue's spec memo this responds to:
2026-05-02-revenue-lock-state-api-surface-spec - Original Coaching question:
2026-05-01-delivery-revenue-lock-state-api-surface - Platform's interim-shape blessing:
2026-05-01-platform-dispatcher-sdk-gap-and-interim-shape - Delivery's adoption confirmation:
2026-05-01-delivery-dispatcher-sdk-interim-confirmation - Coach Availability contract v1.0.1:
coordination/contracts/coach-availability/README.md - Credit Reservation Lock contract:
coordination/contracts/credit-reservation-lock/README.md(esp. §4 state set, §12.3 authoritative-API, §13 producer responsibilities) - ADR-0008:
coordination/adrs/ADR-0008-coaching-as-sixth-domain.md - ADR-0001 (tenancy enforcement), ADR-0002 (ID shapes), ADR-0005 (event envelope), ADR-0006 (lock state machine)
- Revenue domain doc:
coordination/domains/revenue.md. The Q2 rock list this position respects. - Coaching domain doc:
coordination/domains/coaching.md. The new domain whose stand-up depends on these answers.