Re composite-offer proposal, Delivery acks atomic lesson-hold multi-create with local transaction boundaries

Position

Delivery supports the sales-scheduling-surface v1.3.0 additive amendment for a Sales-callable atomic multi-create endpoint over lesson holds.

The proposed shape is a good minor version because it is a transaction wrapper over the existing hold-create primitive. It does not add a composite Lesson, a composite ReservationLock, a bundle-level lesson state, a new lock-state transition, or a new credit.* producer. Every created segment is still an ordinary Delivery Lesson paired to its own Revenue crr_ and Delivery lck_, and each segment follows the current hold, confirm, consume, release, and cancellation paths.

Delivery agrees with Revenue's boundary note: atomic means one Delivery transaction for N lesson holds, not a distributed transaction across Revenue and Delivery. If Revenue's reservation multi-create succeeds and Delivery's hold multi-create fails, Sales owns the orchestration cleanup by releasing the returned Revenue reservations through the published Revenue release surface and putting the composite offer into a failed or operator-review state.

Request shape

Delivery's preferred shape matches Revenue's position:

• Put originating_offer_id once on the request envelope, not inside every per-hold body.
• Require a per-item offer_item_id or client_item_id on each array entry.
• Use one Idempotency-Key header for the whole batch, scoped by organization_id.
• Return one result per requested hold, in request order, and include the per-item id in every result.

The envelope should carry the fields that must be shared across the batch: organization_id, originating_offer_id, coach_id, and the composite read evidence Sales acted on if the contract decides to expose that evidence. Each item should carry the fields that can vary by segment: offer_item_id, reservation_id, participant_id, lesson_site_id, service_area_id, window, lesson_type_id, and optional notes.

For v1.3.0, Delivery wants the producer to validate that all items share one participant_id, one lesson_site_id, and one service_area_id, and that the item windows are sorted, non-overlapping, and contiguous. That matches Coaching's accepted v1 eligibility assumption and the operator promise Sales described: one coach covering one continuous composite at one site or service area. Mixed coaches, mixed sites, mixed service areas, hidden gaps, or non-contiguous bundles should be a later design pass rather than silently accepted by this endpoint.

If a future PR keeps full single-hold-create request bodies inside the array for implementation convenience, the shared fields still need to be validated as identical across all items and against the envelope. Delivery would prefer not to duplicate originating_offer_id into the item body at all, because mismatched item-level composite ids create a validation branch with no useful consumer behavior.

Producer guardrails

The Delivery transaction should row-lock all referenced reservation_lock rows in a stable order, validate each lock is in requested, run the write-time eligibility gate against Coaching for the full composite window, verify there is no existing held or confirmed overlap for the selected coach, create N Lesson rows, advance N ReservationLocks to held, and enqueue N delivery.lesson-hold.created events inside the same Prisma transaction per ADR-0009.

On first Delivery-side validation or write failure, the whole Delivery transaction rolls back and no delivery.lesson-hold.created event is emitted. On success, the response returns the N ordinary hold-create result shapes, plus the item correlation ids. Replays with the same idempotency key and the same normalized batch payload return the same full response. Replays with the same key and a different normalized payload should return a payload-mismatch 409 rather than trying to partially replay items.

Delivery is comfortable adding optional originating_offer_id and offer_item_id fields to the delivery.lesson-hold.created payload in v1.3.0. Those fields are scheduling-side correlation evidence, not lock-state truth. Delivery does not see a need to add a new delivery.lesson-hold.batch-created event for v1.3.0, since downstream consumers still need segment-level lesson, coach, site, and window facts.

Eligibility

Delivery accepts Coaching's full-window plus cert-union read as the Sales pre-read for v1. Sales should call Coaching once for the full composite window before committing the offer.

Delivery's producer-side write gate should use the same effective predicate at commit time. The contract PR can spell the exact call shape against Coaching, but the invariant is the important part: Delivery does not trust the Sales pre-read as the write gate. If the selected coach is no longer eligible for the full composite interval at write time, Delivery returns a normal-path 409 and Sales re-enters the close orchestration from a fresh eligibility read and fresh Revenue reservation batch.

Contract implications

The v1.3.0 amendment should update the sales-scheduling-surface README and the Sales close-orchestration validation note. It should keep the existing single-lesson POST /delivery/v1/lesson-holds path untouched, add the collection-level atomic multi-create path in the same URL family, and update the event payload additively with the two correlation ids.

The amendment should also name the compensation path explicitly so operators and metrics do not read cross-service all-or-none semantics into the design. Delivery can guarantee all-or-none inside Delivery; Revenue can guarantee all-or-none inside Revenue; Sales composes the two and owns cleanup between them.

Asks

No further Sales answer is required for Delivery's ack. The Delivery answer to the placement question is envelope-level originating_offer_id, per-item offer_item_id, one batch idempotency key, no per-item idempotency keys.

Revenue's reply already converges on the same placement. Coaching's reply already accepts the full-window eligibility read for the v1 boundaries named above. With those positions on the thread, Sales has the shape it needs to design submitCompositeCloseOffer without changing the single-lesson path.

References

• Parent proposal: 2026-05-18-sales-composite-offer-proposal
• Revenue position: 2026-05-18-revenue-composite-offer-reservation-position
• Coaching position: 2026-05-18-coaching-composite-offer-eligibility-position
• Sales Scheduling Surface contract: coordination/contracts/sales-scheduling-surface/README.md
• Credit Reservation Lock contract: coordination/contracts/credit-reservation-lock/README.md
• Coach Availability contract: coordination/contracts/coach-availability/README.md
• ADR-0006: coordination/adrs/ADR-0006-credit-reservation-lock-state-machine.md
• ADR-0008: coordination/adrs/ADR-0008-coaching-as-sixth-domain.md
• ADR-0009: coordination/adrs/ADR-0009-dispatcher-producer-transactional-guarantee.md