Sales-scheduling-surface contract v1.0.0 drafted; asking Sales to confirm the close-orchestration shape fits

Why

Sales' close orchestration today reaches into Delivery's lesson surface through ad-hoc paths that vary by environment and bypass the lock state machine in some flows. The Delivery migration and Sales scheduling surface integration initiative (2026-05-07-delivery-migration-initiative-scope) names a canonical Sales-facing surface as the lever that makes the migration not just a relocation. This memo announces the v1.0.0 draft of that surface so Sales can confirm the shape fits before consumer-side integration work begins, and so Revenue and Coaching can flag any cross-contract concerns now rather than at v1.1.

The surface is read-and-write: Sales creates a lesson hold against an existing credit reservation, inspects holds, and cancels holds. The lock state machine itself is unchanged from ADR-0006; this contract is an additional Sales-facing entry point that drives the existing transitions through a single Delivery-owned, transactional code path. Every Sales-originated booking now travels the same canonical sequence: eligibility-read against Coaching, reservation-request against Revenue, hold-create against this surface in one transaction that schedules the lesson, assigns the coach, attaches the lesson site, and advances the lock from requested to held.

What landed

coordination/contracts/sales-scheduling-surface/README.md

A new contract under Delivery's ownership, status v1.0.0, dated 2026-05-07. The bold-header block names Delivery as owner (scheduling and reservation-lock service), Sales as the primary consumer (close orchestration), Revenue as a secondary subscriber (delivery.lesson-hold.* events for ledger reconciliation observability). Related ADRs are 0001 (tenant ID shape), 0003 (Person canonical with role records, amended 2026-05-01), 0005 (event envelope), 0006 (credit reservation lock state machine; this surface is Sales-facing entry over the state machine ADR-0006 specifies), 0008 (Coaching as sixth domain; eligibility upstream), and 0009 (dispatcher producer-transactional-guarantee for the new delivery.lesson-hold.* events).

The README carries the full surface in v1.0.0; sub-specs are not required at this size. Two validation files document the consumer shape and the lock-state-machine conformance gate.

Surface

Four endpoints under /delivery/v1/lesson-holds. Hold-create (POST) creates the Lesson row, attaches the coach and lesson site, advances the reservation lock from requested to held, and emits delivery.lesson-hold.created in one Prisma transaction per ADR-0009. Hold-inspect (GET /{lesson_id}) returns the Lesson plus current lock state, funding sub-state, and the optimistic-concurrency lock_version token. Hold-list (GET) returns paginated holds with optional filters by coach, participant, lock state, and window. Hold-cancel (POST /{lesson_id}:cancel) advances the lock to released and emits delivery.lesson-hold.cancelled in one transaction, using lock_version for optimistic concurrency and a closed reason_code enum.

Confirmed-to-released cancellations are deliberately out of scope in v1.0.0: the lock has cleared funding, money has moved, and Revenue's refund-flow contract owns the cancellation path. §4.4.1 of the contract describes the constraint and §9.2 outlines the v1.1 path for letting Sales originate confirmed-to-released cancellations through this surface once Revenue exposes a Sales-callable refund initiation path that meets ADR-0006's joint-write discipline.

Events

Two events on the delivery.lesson-hold. namespace per ADR-0009: delivery.lesson-hold.created and delivery.lesson-hold.cancelled. Both ride the standard event envelope per ADR-0005. The originator field is sales for traffic that originates from this surface; Delivery has internal flows (operator corrections, no-show reconciliation) that emit the same event types from non-Sales origins, so consumers can filter on originator to scope to Sales-originated traffic.

The lock-state transitions that fire as part of these writes also produce credit.* events on Revenue's credit-reservation-lock surface per the existing credit-reservation-lock contract §9. This contract does not duplicate or replace those producers; consumers that already subscribe to credit.* events MUST NOT subscribe to delivery.lesson-hold.* to learn the same facts.

Producer guarantees

Every write rides a single Prisma transaction composing the storage write, the lock-state advance, and the event emit per ADR-0009's producer-transactional-guarantee. Lock-state-machine conformance is gated by validation/lock-state-machine-conformance.md; the producer SHALL run /scripts/audit-locks.mjs on a continuous schedule and treat any nonzero lock-to-ledger reconciliation drift as a P1 incident jointly with Revenue per the Delivery quality bar. Eligibility re-check at write time closes the read-write race the consumer's pre-write Coaching read leaves open.

Consumer responsibilities

Every read and write carries organization_id for tenancy scoping. Every write carries an Idempotency-Key header scoped per organization. Cancellation echoes the lock_version token from a recent inspect for optimistic concurrency. Sales calls Coaching's coach-availability eligibility surface (§4.2.2 of that contract) before calling hold-create; the producer's eligibility re-check is the gate, but the consumer-side read drives offer construction.

Asks

Sales: please confirm the close-orchestration shape in §6.6 of the contract README matches Sales' current and near-term planning shape for the close path. Specifically: does the canonical sequence (Coaching eligibility-read, Revenue reservation-request, Delivery hold-create) fit the operator-tooling flow Sales is building against, and does the HTTP 409 retry pattern in §6.6 (release the reservation and reserve fresh on slot conflict) match how Sales' close orchestration handles concurrent-operator races today? If a different retry pattern fits better, name it on the thread and Delivery will fold the adjustment into v1.0.1 before any Sales-side integration work scaffolds against the surface.

Revenue: please confirm there is no cross-contract concern between the delivery.lesson-hold.* event surface in §4.5 and Revenue's existing credit.* subscriber audience. The intent of the split is to keep Revenue's ledger consumers on credit.* for lock-state and funding facts, and to offer scheduling-side facts (coach, site, window, lesson type, originator) on the new namespace for consumers that need scheduling-side detail without subscribing to lock-state events. If a Revenue-internal consumer would benefit from subscribing to delivery.lesson-hold.* instead of building yet another credit.* subscriber, name it on the thread.

Coaching: please confirm the eligibility re-check at write time in §7.7 is consistent with the freshness and idempotency expectations on the coach-availability projection. The producer-side re-check fires on every POST /delivery/v1/lesson-holds request and reads through the existing eligibility-by-description endpoint (§4.2.2 of coach-availability); under sustained Sales-side hold-create volume this is a steady incremental load on Coaching's surface. If Coaching wants the re-check to use a different read shape (eligibility-by-coach-and-window with a tighter scope, for instance) as a v1.1 minor bump, flag it now so Delivery can scope the change before Sales integrates.

No dated commitments. The contract is at v1.0.0 today; the lockstep deprecation discipline applies forward (a v2.0.0 would carry a two-week deprecation window for v1). Sales-side integration work is tracked as a trailing indicator on the initiative scope memo (sales-scheduling-surface-availability), not as a ledger commitment, per the no-rocks no-dates discipline filed in 2026-05-23-platform-sunset-directive-superseded.

What does not change

ADR-0006 stays as written. The lock state machine has the same five states and the same transitions; this surface is an additional Sales-facing entry point, not a redesign. Any change to the lock state machine itself remains an ADR-0006 amendment with Revenue sign-off and the standard two-week deprecation window for downstream lock-state consumers per the Delivery domain memo's lock-contract change rule.

The credit-reservation-lock contract stays at its current version. The Sales-scheduling-surface contract references it without proposing a version bump.

The coach-availability contract stays at v1.0.1. Coaching's eligibility surface is an upstream read for this contract, not a co-version target.

The Sales lead-lifecycle contract stays at v1.0.0. Lead pipeline state remains Sales-owned; this surface picks up only after the lead has reached the close path and a credit reservation has been requested.

References

• Contract README: coordination/contracts/sales-scheduling-surface/README.md.
• Initiative scope memo: 2026-05-07-delivery-migration-initiative-scope.
• Initiative records (operations DB): Oahu sister cmovoacin0001voudyf1zqmls, Dallas sister cmovoc7t20004voudgr1s7q7i.
• Delivery domain memo: coordination/domains/delivery.md.
• Credit-reservation-lock contract (load-bearing upstream): coordination/contracts/credit-reservation-lock/README.md.
• Coach-availability contract (eligibility upstream): coordination/contracts/coach-availability/README.md.
• Event-envelope contract: coordination/contracts/event-envelope/README.md.
• ADR-0006 (lock state machine): coordination/adrs/ADR-0006-credit-reservation-lock-state-machine.md.
• ADR-0009 (dispatcher producer-transactional-guarantee): coordination/adrs/ADR-0009-dispatcher-cross-process-transport.md.
• No-rocks no-dates discipline: 2026-05-23-platform-sunset-directive-superseded.
• Audit gate: /scripts/audit-locks.mjs in the Delivery repo.