Group Scheduling API Concurrency: Stop Calendar Races Before the Event Write

Build a compare-and-commit booking path in eight steps

Use one sixty-minute cross-company kickoff with four required people, one optional observer, Google and Microsoft calendars, and one required participant who supplies availability without connecting a calendar. Generate a valid proposal, change a required calendar before approval, deliver approval twice, and time out the first event-write response.

1. 1

   Freeze an authorized meeting-intent revision

   Store meeting_request_id, revision, authenticated organizer, purpose, duration, bounded date window, deadline, IANA time zone, required and optional people, approved substitutes, working-hour rules, preferences, outreach policy, approval mode, organizer calendar, and allowed event actions. Every availability read, reply, proposal, and booking command must point to this revision.
   • Required attendance, consent, and date boundaries cannot change through a slot approval.
   • Preferences are scored only after hard constraints pass.
   • Booking, rescheduling, and cancellation authority remain separate.
2. 2

   Build a versioned availability evidence set

   Read approved Google and Microsoft free/busy for connected calendars. Store provider, account, retrieval time, requested interval, source cursor or change marker when available, response error, IANA zone, and a hash or internal version for the normalized busy set. Do not copy event titles, descriptions, or unrelated attendees into the scheduling record.
   • Missing access and provider errors are unknown, not free.
   • Every required participant has evidence with an explicit freshness rule.
   • The same normalized input produces the same evidence version.
3. 3

   Join conversational availability without pretending it is live sync

   For an unconnected participant, send a consent-safe request with purpose, duration, bounded date range, local-time wording, response deadline, reminder cap, and opt-out path. Parse bounded windows, corrections, decline, and zone into typed evidence tied to sender, channel message ID, meeting revision, received time, and declared expiry.
   • A duplicate reply is suppressed by message and request identity.
   • Ambiguous dates or zones produce one narrow clarification instead of a guess.
   • A correction invalidates every proposal derived from the superseded windows.
4. 4

   Issue proposals as expiring evidence leases

   Intersect all required people, then rank optional attendance and preferences. Create a proposal_id containing meeting revision, exact slot, attendee roles, evidence versions, generated time, expiry, approval requirement, and status. The proposal is a claim that the evidence supported the slot at generation time. It is not a calendar hold and not a booking.
   • The approval surface shows proposal expiry and the source meeting revision.
   • A later calendar change or participant correction can revoke the lease.
   • No-overlap returns the smallest duration, date, attendee, or preference decision.
5. 5

   Re-read required availability at the commit boundary

   After approval and immediately before side effects, fetch current required free/busy and check reply evidence expiry. Compare the normalized evidence versions with those behind the proposal. If the proposed interval is still free and policy permits freshness-only changes elsewhere, continue. If the interval or any hard rule changed, invalidate the proposal and recompute.
   • An approval never overrides a new required conflict.
   • Optional changes follow declared policy and stay visible in the final attendee decision.
   • The preflight result and comparison reason are persisted with the booking attempt.
6. 6

   Acquire one commit right and write idempotently

   Use a short meeting-level commit lease or transactional state transition so only one worker can move the approved proposal into booking_in_progress. Send one stable idempotency key derived from meeting request, revision, and proposal. Persist provider request correlation before the call and provider event identifiers as soon as they are known.
   • Repeated approval, queue delivery, or tool invocation returns the same operation.
   • A lock expiry cannot authorize a second write while the first outcome is unknown.
   • The event body is rebuilt from authorized durable state, not model memory.
7. 7

   Reconcile uncertainty before retrying

   A timeout means unknown, not failed. Search by stored provider correlation, organizer calendar, idempotency marker, attendee set, and bounded time. If the event exists, attach it to the operation and continue verification. If absence is proven, retry under the same key. If provider state is conflicting, stop with a bounded recovery task instead of creating another event.
   • Transport errors and provider rejections have different reason codes.
   • Retries preserve meeting revision, actor, approval, and side-effect history.
   • An operator can resolve uncertain state without reading private event content.
8. 8

   Verify invitations and emit the concurrency trace

   Read back the canonical event and verify final URL-independent provider identity, slot, IANA zone, organizer, every required participant, optional-attendee decision, and invitation state. Trace evidence reads, version comparison, proposal expiry, approval, lock owner, write attempt, timeout, reconciliation, duplicate suppression, and completion. Finish only with one verified booking or a bounded exception.
   • A successful HTTP response alone is not booking proof.
   • The final result explains whether a proposal changed because of freshness, policy, or provider state.
   • The calling agent receives one terminal outcome it can act on safely.

Compare booking approaches at the race window

The critical moment sits between ‘this slot works’ and ‘everyone is invited.’ Compare which method owns freshness, concurrency, uncertain writes, and final proof.