AI Scheduling API Transactional Outbox: Never Lose a Participant Update

Build the scheduling outbox from intent to verified completion

Use one hard meeting with three required people, two optional people, Google and Microsoft calendars, one unconnected participant, two IANA time zones, a duplicate worker delivery, a process crash after commit, an event-write timeout, and one permanently invalid attendee address.

1. 1

   Persist one typed meeting intent and durable participant model

   Create the meeting, revision, authenticated organizer, purpose, duration, bounded date window, booking deadline, IANA meeting zone, required and optional participant entities, approved substitutes, connected-calendar references, outreach authority, disclosure policy, approval mode, and terminal proof contract before any side effect. Keep the original instruction as provenance; run the workflow from typed state.
   • Required people cannot become optional because a worker restarts or a reply is late.
   • Every participant carries identity, role, evidence source, consent, state, and revision.
   • A missing zone, authority, or required identity enters a bounded exception instead of a guessed default.
2. 2

   Name every transition that requires work outside the transaction

   List the commit gaps explicitly: participant-created to outreach-send, calendar-connected to free/busy-read, reply-normalized to overlap-recompute, proposal-approved to event-write, provider-write-uncertain to reconciliation-read, event-created to provider-read-back, and completion-verified to client notification. Each transition needs a typed action, not an in-process callback that can disappear.
   • The domain transition can commit only with its corresponding work intent.
   • The action records the meeting and participant revisions it was authorized to observe.
   • No model transcript, memory queue, or best-effort publish is the only copy of pending work.
3. 3

   Commit domain state and one outbox envelope atomically

   Inside one local database transaction, update the meeting or participant row and insert an outbox row containing action ID, aggregate ID, meeting revision, participant revision when relevant, action type, policy version, payload reference, consent reference, created time, not-before time, sequence, trace context, and status. Commit both or neither. Keep provider credentials and private calendar detail out of the envelope.
   • A crash after commit leaves visible pending work for another dispatcher.
   • A rollback leaves neither a false state transition nor an orphan side effect.
   • A unique action identity prevents two rows for the same logical transition.
4. 4

   Dispatch participant outreach and availability work idempotently

   Claim pending rows with a lease, then re-read current meeting, participant, consent, and evidence revisions. For connected participants, issue bounded Google free/busy or Microsoft getSchedule reads through provider adapters. For optional-sync fallback, send one purpose-limited conversational request. Supply the logical action identity to adapters and record transport correlation without treating provider acceptance as human delivery or usable availability.
   • A duplicate dispatch resolves to the same logical outreach or availability read.
   • Revoked consent, a superseded revision, or newly connected evidence cancels stale work before contact.
   • Provider denial, throttling, missing access, silence, and an empty busy set remain different outcomes.
5. 5

   Normalize evidence, time zones, and the next durable action

   Store connected busy intervals or conversational windows with participant identity, source, retrieval or reply time, IANA zone, freshness, expiry, and typed errors. When the evidence changes, update participant state and insert the next recompute action in the same transaction. Intersect every required person first; rank optional attendance and preferences only after required overlap exists.
   • A phrase such as ‘Tuesday afternoon’ without a known zone creates clarification work, not a slot.
   • Daylight-saving conversion comes from the named zone and meeting date, not a fixed UTC offset.
   • Stale or incomplete evidence remains unknown rather than becoming free time.
6. 6

   Bind approval and enqueue one calendar-write command

   Persist the approved proposal ID, meeting revision, evidence versions, exact start and end, IANA zone, organizer calendar, required participant IDs and addresses, approved optional decisions, conferencing or location policy, disclosure, and approver authority. In that same transaction, insert one calendar-write outbox row. The write action is immutable; a changed person, slot, zone, or calendar requires a new revision and authority check.
   • Fresh required free/busy is checked again before the external write.
   • The operation identity is stable across dispatcher, network, and provider retries.
   • Booking, rescheduling, and cancellation remain different authorized action types.
7. 7

   Reconcile uncertain writes before any retry

   A provider can create the event and lose the response before the dispatcher records success. Mark that row outcome-unknown, retain organizer calendar and correlation data, and enqueue a reconciliation read. Query provider state before another insert. Microsoft Graph documents an optional transactionId intended to reduce unnecessary retries; provider features still sit beneath the application’s durable operation identity and reconciliation policy.
   • A timeout never means the event is absent.
   • The dispatcher can run twice without expanding attendees, disclosure, time, or calendar scope.
   • A discovered duplicate enters repair instead of allowing a second success result.
8. 8

   Budget retries and route exhausted work to recovery

   Classify failures as transient, uncertain, stale, consent-blocked, validation, permission, or terminal. Apply bounded exponential backoff with jitter to eligible transport or provider failures. Keep attempt count, next attempt, last safe checkpoint, redacted error code, and lease history. Move exhausted or non-automatic work to a dead-letter state that preserves the action and names a repair owner; never delete it to make a queue look healthy.
   • Participant reminders follow human cadence and caps, not provider retry timing.
   • An invalid attendee or revoked permission cannot spin forever.
   • Operator replay uses the same action identity unless a human authorizes a new meeting revision.
9. 9

   Read back provider truth and commit completion

   After a write resolves, fetch the canonical organizer event and verify provider and calendar identity, start, end, zone, status, every required attendee, approved optional attendees, and conferencing or location where exposed. Commit the verification evidence, meeting completion state, and any client-notification outbox row together. Return confirmed only when the completion contract passes; otherwise persist a precise repair state.
   • A provider create response alone cannot mark the hard meeting booked.
   • One trace joins instruction, participant evidence, outbox actions, attempts, provider calls, read-back, repair, and terminal result.
   • Metrics cover pending age, claim latency, attempts, dead letters, uncertain writes, repair time, and end-to-end completion.

Compare scheduling architectures at the commit gap

The deciding test is simple: after business state commits, can the process die indefinitely without losing the participant or calendar action that must follow?