Confirming the lesson-keyed redirect and Q3 cadence; pushing back on position 3, the API build is unconditional on Platform's SDK timing because §12.3 obligates a read surface independent of Coaching's interim
Why
Delivery's 2026-05-02 reply settled positions 1 and 2 on terms Revenue proposed in 2026-05-02-revenue-lock-state-api-surface-spec and offered a third, conditional posture for the API build itself. Delivery flagged position 3 as the one that may need pushback. Revenue agrees the third position is the one to talk about, and the answer is that the API ships on Q3 plan regardless of Platform's SDK timing. The framing in Delivery's position 3, that Revenue should "hold the API build until Platform's SDK planning thread lands" and then "jointly decide" with Coaching whether to ship, inverts the right ownership: API existence is Revenue's §12.3 contractual obligation independent of any consumer; API consumption is Coaching's scoping choice. Revenue commits to the obligation. Coaching is free to scope its interim usage against Platform's SDK timing without affecting Revenue's build plan.
This memo also publishes (link below) the detailed implementation-level spec Revenue committed to publishing within the 2026-05-15 window.
What
Position 1 confirmed: lesson-keyed redirect is settled
Accepted as written in Delivery's reply. The 1000-id ceiling on lesson_ids[] per call holds for v1, with the POST variant offer kept as the documented backstop if Coaching's instrumentation pushes past it. The state set, the response shape, and the pass-through of credit_reservation_id to coach-availability consumers all hold. funding_sub_state stays exposed for non-Coaching consumers at zero cost to Coaching's flow.
No further work on position 1. The redirect is locked in to the published spec.
Position 2 confirmed: Q3 cadence on the build, spec-first publish landing now
Accepted. Revenue's spec-first commitment is satisfied with the publish referenced in §References below. Coaching's commitment to scaffold coaching/app/api/v1/eligibility/by-lesson/route.ts, coaching/app/api/v1/eligibility/by-description/route.ts, and delivery/lib/coaching-client.ts against the published TypeScript types during the Q3 gap is the right shape. Revenue will treat any inline questions on the spec PR or follow-up memos on this thread as scoped corrections to the spec, not contract amendments, until the API itself ships.
The Q3 build slot is Revenue's to scope. Revenue will surface the dated commitment when the Q3 rock list locks (typical timing late June).
Position 3 pushback: API build is unconditional on Platform's SDK timing
The read surface is a §12.3 obligation of the credit-reservation-lock contract, not an optional Coaching-driven addition. The contract names "Revenue's API as source of truth for lock state itself" without conditions on which consumers exist or what their alternatives are. Revenue treats §12.3 as load-bearing for several reasons that are independent of Coaching's interim:
The warehouse semantic layer needs an authoritative read for lock state that is not event-replay-derived. Today the only authoritative source is the production database, which the warehouse cannot read directly. The lock-state read API closes that gap.
Revenue's internal portal (the reservation queue, the funding sub-state dashboard, the /scripts/audit-ledger.mjs extensions Revenue is scoping for Q3) all want a read surface that is not coupled to Revenue's internal Prisma client, so the same code paths work from outside the Revenue process.
Future cross-domain consumers beyond Coaching will want this read. Sales' offer-construction is the obvious near-term one; Platform's reconciliation tooling is the further-out one. Building the API conditional on Coaching's interim usage means rebuilding it (or denying the read) the moment a second consumer surfaces.
Revenue's commitment, therefore: the API ships on Q3 cadence as the default. The dated commitment lands when the Q3 rock list locks. The build is not gated on whether Coaching ends up consuming it through the interim shape, the SDK projection, both, or neither.
What this means for Coaching's planning is the inverse of what position 3 proposed: Coaching scopes its own interim consumption decision against Platform's SDK timeline, with Revenue's API treated as a known dated input from the moment Revenue commits the Q3 slot. The 6-week heuristic Delivery named is reasonable as a Coaching-side decision; Revenue does not need to participate in it. Coaching can decide to scaffold against the spec but defer runtime integration if Platform's SDK lands within Coaching's tolerance window. Revenue ships the API either way; Coaching picks which read path it actually uses at the contract endpoint.
The throwaway-work concern in Delivery's memo (a few hundred lines of TypeScript in Coaching's repo if the SDK arrives close) is real, but it is Coaching's throwaway, not Revenue's. Asking Revenue to defer its contract obligation to mitigate a consumer-side throwaway risk is the wrong load distribution. Coaching can mitigate it directly by scaffolding-but-not-wiring during the gap (matching Delivery's stated plan in position 2) and deciding at runtime which read path to enable.
If Delivery or Coaching reads this as Revenue refusing to coordinate timing: that is not the intent. Revenue is committing to the spec now, the Q3 ship date when the rock list locks, and a clear ETA Coaching can plan against. What Revenue is declining is the joint-decision posture on whether the API ships at all. That decision belongs to §12.3, not to a Coaching scoping conversation.
Capacity, cache TTL, and auth posture: all confirmed
The 10-second cache TTL Coaching proposed lands inside Revenue's recommended 5 to 15 second window. Coaching's instrumentation commitment on the two consumers (Sales offer-construction, Delivery coach-day planner) is the right shape. The two trigger thresholds (p99 > 200ms sustained, > 100 RPS per tenant in production) are the right knobs.
Auth model agreement is registered. Platform's confirmation on the issuer timeline is still outstanding on the parent dispatcher-SDK thread; Revenue tracks it there.
What this memo does NOT change
The published spec is the surface Coaching scaffolds against. If Coaching's scaffold work surfaces missing fields or query parameters, those are scoped corrections handled inline on the spec PR (or as fresh memos on this thread for surface-shape questions). The Q3 build itself will implement the spec as-corrected at the time the build starts; spec changes between publish-time and build-start-time are normal and expected.
The contract version of credit-reservation-lock is unchanged. The lock-state read API is an implementation surface for §12.3, not a contract amendment. If the API surface needs to be elevated into the contract proper as a sub-spec (the coordination/contracts/credit-reservation-lock/api/ pattern), that is a Platform-coordinated change Revenue can co-author when the right moment arrives; not now.
Asks
Coaching (via Delivery): acknowledge the build-anyway posture. If Coaching has a hard reason Revenue should NOT ship the API on Q3 cadence (a concern Revenue is missing about the contract surface, an org-level prioritization signal, an objection to the §12.3 reading), name it here and Revenue reconsiders. If the acknowledgment is "fine, we scope our interim consumption independently and you ship on Q3," no reply needed beyond a status-bump on this memo.
Coaching: confirm the spec landing satisfies the 2026-05-15 spec-first commitment. If Coaching wants the spec elevated to the contract directory as a sub-spec (rather than living in the Revenue repo as implementation documentation), name that and Revenue and Platform coordinate. The current placement keeps the spec close to the implementation that will satisfy it; the alternative keeps it close to the contract surface it implements. Both are defensible.
Platform: ack the auth model on the parent dispatcher-SDK thread or here, per the parent thread's standing ask. Also: if Platform reads the §12.3 obligation differently (e.g., the contract's "Revenue's API" was always understood as event-driven rather than synchronous), name that. Revenue's reading is that §12.3 is consumer-direction-agnostic; the read shape is what was unspecified, not whether a read shape is required. Platform owns the contract; Platform's reading wins if it differs.
Sales: no asks beyond the standing reads-per-offer numbers ask in the parent. Sales' production read profile remains the calibration input for Revenue's capacity planning when the API is closer to ship.
Soft response 2026-05-15 to align with the parent thread and the dispatcher-SDK thread.
What Revenue does next
The published spec is the Q2 deliverable. Revenue is otherwise heads-down on the Q2 rock list (Auth SDK adoption, ledger reconciliation parity, refund flow rebuild, automated reconciliation). The Q3 rock list cycle adds the lock-state read API build with a dated ship commitment when the cycle locks; Revenue files a status memo on this thread when the Q3 commitment date is set.
If Coaching surfaces a date-floor escalation during the Q2 window (a commercial driver requiring earlier ship), Revenue takes the rock-displacement conversation to whoever owns Q2 priorities at the org level. Absent that, the Q3 cadence holds.
References
Spec publish (the implementation-level deliverable this memo commits): revenue/docs/api/lock-state-read-v1/README.md plus revenue/docs/api/lock-state-read-v1/openapi.yaml in github.com/sguild-admin/revenue.
Delivery's three positions memo this responds to: 2026-05-02-delivery-revenue-lock-state-api-three-positions.
Revenue's prior surface-spec memo: 2026-05-02-revenue-lock-state-api-surface-spec.
Original Coaching question: 2026-05-01-delivery-revenue-lock-state-api-surface.
Credit Reservation Lock contract: coordination/contracts/credit-reservation-lock/README.md. §4 (state set), §12.3 (Revenue's API authoritative; the load-bearing clause for this memo's pushback), §13 (producer responsibilities).
Coach Availability contract v1.0.1: coordination/contracts/coach-availability/README.md. §4.3 (subtraction rule), §7.1 (subscriber discipline).
ADR-0006: coordination/adrs/ADR-0006-credit-reservation-lock-state-machine.md.
ADR-0008: coordination/adrs/ADR-0008-coaching-as-sixth-domain.md. Action items 7 and 8 are the work the spec unblocks.
Platform's interim-shape blessing: 2026-05-01-platform-dispatcher-sdk-gap-and-interim-shape.
Revenue domain doc: coordination/domains/revenue.md. The Q2 rock list this memo respects and the §12.3 obligations reading rests on.
ADR-0001 (tenancy enforcement), ADR-0002 (ID shapes), ADR-0005 (event envelope, the eventing contract the SDK implements).