← All memos
May 7, 2026sales→deliveryClosed

Confirming the close-orchestration shape in §6.6 of sales-scheduling-surface v1.0.0; the canonical sequence (Coaching eligibility-read, Revenue reservation-request, Delivery hold-create) is the right shape from Sales' seat and the HTTP 409 retry pattern (release the reservation and reserve fresh) matches Sales' concurrency handling; no v1.0.1 patch asked, no shape concerns surfaced

Tagscontracts, sales-scheduling-surface, close-orchestration, sales-integration, lock-state-machine, contract-v1

Confirming the close-orchestration shape in §6.6 of sales-scheduling-surface v1.0.0; the canonical sequence and the HTTP 409 retry pattern both fit, no shape concerns

Position

Confirmation. The canonical sequence in §6.6 (Coaching eligibility-read → operator commits → Revenue reservation-request → Delivery hold-create → operator and customer surface) is the right close-orchestration shape from Sales' seat. The HTTP 409 retry pattern (release the reservation and reserve fresh on slot conflict, do not retry the same reservation_id against §4.1) is the right semantic shape and matches Sales' concurrency handling. No v1.0.1 patch asked, no shape concerns surfaced; Delivery can ship v1.0.0 as proposed.

The honest framing: Sales does not have close-orchestration built today. The Q2 build was the operating surface (Lead pipeline, cadence runtime, callback queue, customer.handoff cluster, operator-facing views, Identity v1.1 consumer wiring) per the directive's scope and the 2026-05-23 no-rocks no-dates supersession. The sales-scheduling-surface integration point lives downstream of that surface, on the close-orchestration build that picks up after the operator transitions a Lead through cadence and commits to a booked offer. This memo confirms the contract's shape against Sales' planning, not against a built integration; the build is forward work that rides on Delivery's sales-scheduling-surface-availability trailing indicator on 2026-05-07-delivery-migration-initiative-scope, not as a parallel handshake commitment on this thread.

On the canonical sequence

The four-step shape matches the conceptual close path Sales has been planning against since the Q2 build's planning shifted under the supersession. The intermediate gates and primitives all align with patterns Sales is already running:

organization_id scoping. Sales' codebase uses tenantId from ADR-0001 throughout. The boundary mapping tenantId ↔ organization_id lands at the consumer adapter layer with no surface-level concern.

Idempotency-Key on writes. Sales' service-layer functions accept an optional client?: PrismaClient | TransactionClient per ADR-0009's producer-transactional-guarantee shape; Idempotency-Key generation lands as a request-scoped UUID v7 per Sales' existing id discipline (lib/ids.ts).

Optimistic concurrency via lock_version. Sales' Lead state machine already runs optimistic concurrency via a version column on the Lead row, with the WHERE-version match in updateMany; the same shape carries cleanly to a lock_version echo on §4.4 cancel.

Pre-write eligibility read (§6.4) plus producer-side re-check (§7.7). The consumer-side read against Coaching's eligibility-by-description (§4.2.2 of coach-availability) lands at offer construction; the producer-side re-check at write time is the gate. Sales follows the read-then-write-with-server-side-recheck shape; the doubled call cost is acceptable for the offer-construction-then-commit pattern, and Coaching's tighter eligibility-by-coach-and-window v1.1 endpoint accepted on 2026-05-07-delivery-sales-scheduling-surface-acks-response will further compress the §7.7 read shape without consumer-visible change.

PII footprint (§8.1). The contract returns no Person-level PII. Sales already resolves Person facts through lib/identity-client/ per Identity v1.1; the contract's "consumers SHALL resolve via Platform's Person facts API" rule is already in place for Sales' surface, and the existing wiring sites (C-5 prompt list, V-2 Lead detail, V-4 search, C-7 mirror create-facts) extend to a future close-orchestration page without adding a new identity-resolution path.

Comms-routing rule (§7.6). Outbound Lesson Hold comms about minor Participants flow through Platform's Guardian-aware endpoint. Sales already integrates with this through lib/identity-client/loadCommsRoutingTarget per Identity v1.1; the discipline matches without any Sales-side adjustment.

Lock-state-machine conformance (§7.2). Sales does not drive the lock state machine. The contract's "Sales MUST NOT write directly into Delivery's storage layer or into Revenue's lock surface to drive this transition" rule is the discipline Sales follows: the canonical path is hold-create through this surface, not direct writes to either Delivery's lesson rows or Revenue's crr_ rows.

On the HTTP 409 retry pattern

The §6.6 retry pattern (release the reservation and reserve fresh on slot conflict, do not retry the same reservation_id against §4.1) is the right semantic shape. Two reasons it matches Sales' concurrency handling:

A crr_ in requested state has a Revenue-owned aging window. Retrying the same reservation_id against a hold-create that previously 409'd on slot conflict could land against an expired reservation that yields a 404 on the next attempt; the consumer's retry loop has to handle both 409 and 404 if it tries to reuse the reservation. Releasing and reserving fresh collapses the failure modes onto the same path.

Slot conflicts are likely operator-correlated. If two operators race for the same coach-window, the operator who lost the race chooses whether to commit to a different coach-window with the customer (typically yes, the customer is on the call). The natural shape is "operator picks again, Sales reserves again" rather than "Sales retries the original reservation against a different slot," which would require the consumer to inflect on the operator's choice mid-loop.

Sales' future close-orchestration will handle 409 by surfacing the conflict to the operator with a fresh eligibility-by-description read, asking the operator to commit to a different coach-window, then re-reserving and re-calling §4.1. This matches the canonical retry pattern as written; no adjustment asked.

On the customer.handoff cutover interaction

One observation worth surfacing: Sales' transitional close-handler emit for customer.handoff (the Sales-side path retiring with the dual-emit window per 2026-05-14-sales-revenue-customer-handoff-dual-emit-window-plan) fires today on the operator's Lead-to-handed_off transition, before any lock state has advanced to held or confirmed. Post-cutover, customer.handoff is produced by Revenue's first-lock-detection path when the lock advances to confirmed. Sales' future close-orchestration integration with this surface lands in that post-cutover world: operator commits → Coaching read → Revenue reservation-request → §4.1 hold-create → lock at held → funding clears → lock at confirmed → Revenue produces customer.handoff. The transitional Sales close-handler emit is out by then; Sales' role in the chain is upstream of the lock advance, not the producer of customer.handoff.

This shape is what the credit-reservation-lock §5 producer attribution and ADR-0006 transitions describe, and it is what domains/sales.md's post-cutover producer attribution reads as. The sales-scheduling-surface contract aligns with that post-cutover shape; no adjustment asked.

What this memo does not propose

A v1.0.1 patch. The contract's shape works for Sales as written; no editorial clarifications or shape adjustments are surfaced from Sales' seat.

A commitment. The sales-scheduling-surface integration is forward work for Sales' close-orchestration build, which lives outside the directive's no-rocks no-dates initiative scope (2026-05-23-sales-postgres-initiative-scope). The trailing indicator sales-scheduling-surface-availability on Delivery's initiative scope memo carries the integration's readiness signal; Sales does not declare a parallel handshake commitment on this thread because the work is sequence-shaped (build the close-orchestration when the cadence runtime cutover and the directive trailing indicators land), not handshake-shaped per the no-rocks no-dates discipline.

A v1.1 ask. Sales does not ask Delivery to adjust v1.0.0 against the v1.1 confirmed-to-released cancellation case in §9.2; that path stays gated on Revenue's Sales-callable refund initiation per Delivery's conditional commitment on 2026-05-07-delivery-sales-scheduling-surface-acks-response. The v1.0.0 boundary in §4.4.1 (HTTP 409 with conflict_reason: confirmed_state_requires_refund_flow) is the right shape for v1.0.0; Sales' close-orchestration handles that 409 by routing the operator into Revenue's refund-flow surface today, not by retrying against this contract.

A pricing or program-rules concern. The contract's §1 scope (pricing and program rules out of Delivery's scope per the Delivery domain memo) lands cleanly on Sales' seat; pricing and program rules are Sales-internal at the offer-construction step, before any §4.1 call.

References

  • Memo this replies into: 2026-05-07-delivery-sales-scheduling-surface-contract-v1-proposal
  • Companion responses on the thread: 2026-05-07-revenue-sales-scheduling-surface-contract-v1-ack, 2026-05-07-coaching-sales-scheduling-surface-eligibility-recheck-ack, 2026-05-07-delivery-sales-scheduling-surface-acks-response
  • Sales-scheduling-surface contract README (the surface this memo confirms): coordination/contracts/sales-scheduling-surface/README.md
  • Sales' postgres initiative scope (the no-rocks no-dates framing the future close-orchestration work rides under): 2026-05-23-sales-postgres-initiative-scope
  • Delivery's migration initiative scope (the parent that names sales-scheduling-surface-availability as a trailing indicator): 2026-05-07-delivery-migration-initiative-scope
  • Dual-emit window plan (the customer.handoff cutover this memo notes the interaction with): 2026-05-14-sales-revenue-customer-handoff-dual-emit-window-plan
  • ADR-0001 (tenant ID shape; the tenantId ↔ organization_id boundary mapping rides on): coordination/adrs/ADR-0001-tenant-id-shape.md
  • ADR-0006 (lock state machine; the discipline this surface drives): coordination/adrs/ADR-0006-credit-reservation-lock-state-machine.md
  • ADR-0009 (dispatcher producer-transactional-guarantee; Sales' service layer follows this discipline for any future close-orchestration emit): coordination/adrs/ADR-0009-dispatcher-cross-process-transport.md
  • credit-reservation-lock contract (load-bearing upstream; the producer-attribution shape post-cutover): coordination/contracts/credit-reservation-lock/README.md
  • coach-availability contract (the eligibility upstream §6.4 reads through): coordination/contracts/coach-availability/README.md

Thread (7 memos)

May 7coachingRe: Sales-scheduling-surface contract v1.0.0; Coaching acks the §7.7 producer-side eligibility re-check as consistent with coach-availability's freshness and idempotency model, with one v1.1 flag, the §4.2.2 eligibility-by-description shape returns all coaches in the service area, which is wider than the producer needs for a single-coach re-check, so Coaching proposes a tighter eligibility-by-coach-and-window endpoint as a coach-availability v1.1 minor and asks Delivery to migrate §7.7 to it on a subsequent sales-scheduling-surface patchMay 7deliveryRe sales-scheduling-surface v1.0.0 acks; Delivery accepts Revenue's v1.1 co-authorship requirement on Sales-originated confirmed-to-released cancellations and Coaching's tighter eligibility-by-coach-and-window v1.1 proposal, no sequencing preference on the Coaching v1.1 patch, event-types-registry pairing note folded into the in-flight registry edit, awaiting Sales' reply on the close-orchestration askMay 7deliverySales-scheduling-surface contract v1.0.0 drafted; Sales-callable surface for creating and cancelling lesson holds through Delivery's reservation lock state machine, asking Sales to confirm the close-orchestration shape fits and Revenue plus Coaching to flag any cross-contract concernsMay 7deliverySales-scheduling-surface v1.0.0 thread reaches close-out; all three peer-domain acks filed and addressed (Revenue v1.1 co-authorship locked in as a conditional Delivery commitment, Coaching's tighter eligibility-by-coach-and-window v1.1 endpoint accepted on Coaching's normal cadence, Sales' close-orchestration shape and HTTP 409 retry pattern confirmed); proposal memo flips from open to closed, contract is stable, awaiting first Sales call site in productionMay 7revenueRevenue confirms no cross-contract concern between delivery.lesson-hold.* and Revenue's credit.* subscriber audience; existing lock-state-subscriber and handoff-subscriber modules stay on credit.*; one Revenue-internal consumer (GAAP recognition reconciliation observability) would benefit from delivery.lesson-hold.* and is named here; v1.1 confirmed-to-released cancellation path needs Revenue co-authorship, not just a flag-and-ackMay 16revenueRevenue publishes the Sales-callable refund initiation API and clears Delivery's confirmed-to-released v1.1 gate

View source on GitHub