Meeting Scheduling API: Rank Hard Constraints Before Preferences

Build the two-stage slot engine in eight steps

Use one sixty-minute implementation review across two companies. Three people are required, one executive is optional, two calendars are connected through Google and Microsoft, one required customer will reply without connecting, and the organizer prefers mornings. The engine must explain why each slot is valid before it explains why one valid slot ranks first.

1. 1

   Compile the instruction into typed meeting intent

   Store meeting_request_id, revision, authenticated organizer, purpose, duration, bounded date window, deadline, meeting IANA time zone, location, required and optional participants, approved substitutes, working-hour policy, buffers, preferences, outreach consent, approval mode, and allowed calendar actions. Preserve the source instruction but run matching against the typed revision.
   • Reject missing organizer, duration, bounded window, deadline, or required participant.
   • Separate hard constraints, soft preferences, and facts that still need clarification.
   • Every availability record, proposal, approval, and booking points to the current revision.
2. 2

   Write the hard-constraint contract first

   Treat required attendance, authorized substitutes, duration, date bounds, explicit blackouts, minimum notice, mandatory buffers, location limits, consent, and valid time-zone interpretation as pass-or-fail rules. Decide whether working hours are hard or soft for each participant. Keep optional attendance and organizer preference out of validity.
   • The engine cannot drop a required person to manufacture a slot.
   • An optional decline never turns a valid slot invalid.
   • Only an authorized organizer revision can relax a hard rule.
3. 3

   Collect availability with source and consent

   Read approved Google and Microsoft free/busy for connected calendars. For an unconnected participant, send an approved request for bounded windows, parse the reply into the participant’s local zone, and record consent, message ID, reply time, source, and freshness. A calendar connection reduces work; it is not a condition for joining the meeting.
   • Possessing an address does not grant outreach permission.
   • Missing provider access or participant silence is missing evidence, not open time.
   • Private event titles, descriptions, and unrelated attendees never enter the slot record.
4. 4

   Normalize intervals without erasing meaning

   Convert provider busy ranges and participant windows into canonical half-open intervals while preserving original local input, IANA zone, account, provider, retrieval or reply time, freshness policy, consent state, and typed error. Expand recurring and daylight-saving cases against the meeting window rather than freezing a current UTC offset.
   • Ambiguous date or zone language triggers one narrow clarification.
   • A numeric offset alone is not a durable participant time zone.
   • Corrections supersede old intervals and mark derived proposals stale.
5. 5

   Generate the valid set from required overlap

   Subtract every required participant’s busy intervals, explicit blackouts, buffers, and notice rules from the bounded search window. Intersect the remaining windows and cut them into duration-sized candidates. Attach the exact required evidence versions and constraint decisions to each survivor. Do not score anything that failed validity.
   • Provider error for one required person blocks validity until recovered or decided.
   • Each candidate can prove every required participant is covered.
   • A no-overlap result names the smallest authorized decision that could change the set.
6. 6

   Rank survivors with an explicit scorecard

   Score valid slots for optional attendance, organizer preference, participant working-hour comfort, time-zone fairness, notice, travel or focus buffers, and other declared soft rules. Use named weights or ordered tie-breaks, not hidden model taste. Return both total order and a reason breakdown that an organizer can inspect.
   • A soft score can never rescue an invalid slot.
   • Optional people improve rank without changing required quorum.
   • Tie-breaking is deterministic for the same intent and evidence versions.
7. 7

   Approve, revalidate, and commit once

   Bind approval to the meeting revision, proposal ID, attendee set, score explanation, organizer calendar, and event wording. Re-read fresh required availability immediately before the write. Use a booking idempotency key, persist provider correlation and event IDs, reconcile uncertain timeouts before retry, and invalidate approval when a hard constraint changes.
   • A repeated MCP tool or REST command returns the original result.
   • A stale top-ranked slot returns to matching rather than booking on old evidence.
   • Partial provider writes move to reconciliation with one safe operator action.
8. 8

   Verify completion and trace every decision

   Read back one canonical event and verify start, end, zone, organizer, required attendees, optional-attendee decision, and invitation dispatch. Emit meeting-level events for intent revision, availability source, constraint rejection, score components, approval, retries, reconciliation, and terminal status. Completion is a verified booking or a bounded exception, not a list of suggested times.
   • Operators can reproduce a proposal from stored intent and evidence versions.
   • Healthy participant wait is separate from stuck processing or provider failure.
   • Every terminal exception names current evidence, one owner, and one allowed next action.

Compare slot ranking by the meeting outcome it owns

The fastest ranking function is not the shortest path to a booking if the application still has to collect missing evidence, enforce authority, repair stale proposals, and verify invitations.