Asking Revenue to specify the lock-state API surface Coaching's interim sync-query reads will hit

Why

Platform's 2026-05-01 reply on the dispatcher-SDK thread blessed synchronous queries against Revenue's authoritative lock-state API as the interim contract-compliant read shape for coach-availability v1.0.1 during the dispatcher SDK gap. Delivery's confirmation memo (2026-05-01-delivery-dispatcher-sdk-interim-confirmation) accepted the unblock and surfaced an operational sizing question for Revenue. That memo treated Revenue's lock-state API as known, but in fact Coaching does not have a specification of its surface (endpoint shape, query parameters, response shape, auth, tenancy scoping, capacity posture). The credit-reservation-lock contract names "Revenue's API" as authoritative for lock state in §12.3 but does not pin its surface, because the contract was scoped to events rather than to the synchronous read path.

Coaching cannot implement the interim shape against an unspecified API. This memo asks Revenue to specify what Coaching's reads will hit.

Revenue's leg on the parent Coaching-split thread closed early (2026-05-01-revenue-coaching-split-no-lock-impact) on the substantive grounds that the split did not change Revenue's surface or the lock state machine. The interim shape changes that posture: Revenue is now a synchronous dependency on Coaching's contract reads, which is a new operational relationship that did not exist when Revenue closed its leg. This memo is the formal ask for the surface specification that the new relationship requires.

What

The questions Coaching needs answered to scaffold the interim sync-query path. Eight specific items, framed so Revenue can answer in one pass.

1. Does the lock-state read API exist today

Symmetry with the dispatcher-SDK question Coaching asked Platform. The credit-reservation-lock contract's §12.3 says "Revenue's API as source of truth for lock state itself." Coaching needs to know whether that API is live in production today (and Coaching can integrate against it), or is a paper claim parallel to the dispatcher SDK (and Coaching needs a different unblock).

If the API is live, what is its base URL or service identifier, and what is the access pattern (HTTP REST, gRPC, internal RPC, other). If the API does not exist or is partially implemented, name what shape it is in today; Coaching's interim implementation timeline depends on the answer.

2. Endpoint shape for the read Coaching needs

Coaching's interim contract reads compose availability and eligibility from coach plus coach-profile records (Coaching's own store) plus lock state for the relevant (coach_id, window) slots in the requested service area. The natural read is "give me the active reservations and locks affecting these coaches in this window in this organization."

Three plausible endpoint shapes Revenue can pick or replace:

A bulk read keyed by (organization_id, service_area_id, window_start, window_end) returning all active reservations and locks within the window, with each result carrying coach_id (or whatever scheduling-side reference Revenue's reservation records hold to identify the affected slot). Single round-trip per Coaching read.

A per-coach read keyed by (organization_id, coach_id, window_start, window_end) returning the active reservations and locks for that one coach in the window. N round-trips per Coaching read where N is the number of coaches in the eligibility response.

A per-reservation read keyed by reservation id (crr_*) returning the current state of one reservation. Coaching does not have reservation IDs upfront on a fresh availability read, so this only works if combined with one of the above.

Coaching's preference is the bulk read (shape one). Latency is one Revenue hop per Coaching read regardless of how many coaches and slots are in scope. If Revenue's storage layer cannot support a bulk read efficiently, name that constraint here and Coaching defaults to the per-coach shape with parallelization.

3. Query parameters

Whatever shape lands in question 2, what specific query parameters does the endpoint accept. Are window times ISO 8601 with timezone, or epoch milliseconds, or a different convention. Is service_area_id a hard filter or an advisory hint. Is there a way to ask for "lock states only" versus "all reservation states" (Coaching only needs the four credit.* states that participate in the subtraction rule per coach-availability §4.3.2).

4. Response shape

What does the response look like for the chosen endpoint shape. The fields Coaching needs per result:

• A reference to the affected slot (coach_id plus window start and end, or whatever Revenue's reservation records carry to identify this).
• The current reservation state (reserved, locked, released, forfeited, or whatever value set Revenue exposes; the credit-reservation-lock contract's §4 is the source of truth on the value set).
• A reservation_id (crr_*) and an optional lock_id (lck_* or whatever Revenue uses) for traceability so Coaching can pass these through to consumers per §4.1 of the coach-availability contract.
• A funding sub-state if Revenue exposes it, though Coaching does not consume it for the subtraction rule (credit.funded is not subscribed per §4.3.1 of coach-availability).

If Revenue's existing API returns a different shape, Coaching adapts at the contract endpoint layer rather than asking Revenue to reshape; just name the actual shape so the adapter is correct.

5. Auth model

How does Coaching authenticate to Revenue's API. Three plausible shapes:

A service-to-service bearer token issued by Platform's identity service, with Revenue validating the token and the token carrying the calling domain.

Mutual TLS with Coaching's service certificate registered against Revenue's allowed-callers list.

A shared secret in an environment variable, with Revenue rotating periodically.

Coaching defaults to the first shape (service-to-service bearer token via Platform) unless Revenue specifies otherwise. The decision affects what Coaching's lib/ carries and what env vars coaching/.env.local.example documents.

6. Tenancy scoping

How does Coaching pass tenant_id (per ADR-0001) and organization_id (per ADR-0003), and how does Revenue enforce that the response is scoped to the requesting consumer's tenant. The expectation per ADR-0001 is that every cross-domain API call carries tenant_id resolved from the auth context, and that Revenue rejects mismatched-tenant requests with HTTP 403 or equivalent. If Revenue's API today does not yet enforce tenant routing (single-tenant world to date), name the current behavior and Coaching codes against the production-target shape.

7. Capacity and rate-limit posture

The operational sizing question Coaching surfaced in 2026-05-01-delivery-dispatcher-sdk-interim-confirmation. The interim shape pushes new heavy read traffic onto Revenue's API: every Sales offer-construction read and every Delivery coach-day planner cell hits Revenue. Coaching is in no position to estimate the request volume against Revenue's current API capacity from outside Revenue's deployment.

Specifically: what is Revenue's current rate-limit per consumer (if any), what is the API's current p50 and p99 latency under typical load, and what is the rough headroom for a new consumer making sustained reads at the volumes Coaching's interim implementation will produce. Coaching can respond to a constraint here by adding a request-coalescing layer or a short-cache layer in the contract endpoints (e.g., 5-second TTL on identical reads within Coaching's process) before the interim shape goes live; specify the constraint and Coaching scopes the mitigation.

8. Caching and conditional reads

Does the lock-state API support conditional reads (ETag, If-Modified-Since, If-None-Match) so Coaching can avoid re-fetching unchanged windows on tight successive reads (the planner refresh case). If conditional reads are supported, Coaching's contract endpoints can layer a short cache against ETags. If not, Coaching falls back to time-based caching.

Related: is there a webhook or push-notification path Revenue exposes for "this window's reservations changed" that Coaching could subscribe to, parallel to the dispatcher SDK, to reduce read load without standing up a full event subscriber. Probably not (that would be the SDK), but worth asking.

Asks

Revenue: answer the eight sub-questions above, ideally in one reply memo on this thread. The answers determine the shape of Coaching's interim sync-query implementation in the contract endpoints. If any sub-question's answer is "not decided yet" or "the API does not exist in this shape today," that is also useful; Coaching can either wait for Revenue's surface to land or scope around the gap.

If the interim shape's traffic is genuinely unsizable from Revenue's seat without a load test, name what Revenue would need from Coaching to size it (synthetic load profile, expected request volume estimates, organization-and-coach count ranges) and Coaching produces the inputs.

If Revenue's API surface needs net-new development to support Coaching's interim consumption (a bulk-read endpoint that does not exist today, an auth pattern Revenue does not currently expose), name the team-week scope and Coaching's interim implementation either waits or finds a workaround in coordination with Platform.

Platform and Sales: no asks. Surfaced for awareness because both depend on the interim shape working (Platform blessed it; Sales is the offer-construction consumer). If Platform's view is that Revenue's API is in a different shape than this memo's questions assume (Platform stewards eventing and observability and may know things about Revenue's surface that Coaching does not), push back here.

Soft response date 2026-05-15 to match the response window on the dispatcher-SDK thread, so both Platform's commitments and Revenue's specification land in the same operational window.

References

• Delivery's confirmation of the interim shape: 2026-05-01-delivery-dispatcher-sdk-interim-confirmation
• Platform's reply on the dispatcher SDK gap: 2026-05-01-platform-dispatcher-sdk-gap-and-interim-shape
• Coach Availability contract v1.0.1: coordination/contracts/coach-availability/README.md. §4.3 and §7.1 carry the interim notes that depend on Revenue's API.
• Credit Reservation Lock contract: coordination/contracts/credit-reservation-lock/README.md. §4 is the source of truth on the state set Coaching needs to read; §12.3 names "Revenue's API" without pinning its surface.
• ADR-0006: coordination/adrs/ADR-0006-credit-reservation-lock-state-machine.md. The lock state machine.
• ADR-0008: coordination/adrs/ADR-0008-coaching-as-sixth-domain.md. Action items 7 and 8 are the work this question gates.
• Revenue's earlier closed leg: memos/2026/2026-05-01-revenue-coaching-split-no-lock-impact. Closed before the interim shape changed the operational relationship.
• Revenue domain scope: coordination/domains/revenue.md.