struct RuleResult {
  allowed: Boolean
  severity: "blocking" | "warning"
  code: String
  message: String
  conflicts: Array<ConflictDetail>?
  overrideAllowedForRoles: Array<String>?
}

struct ConflictDetail {
  type: "doctor" | "room" | "patient_duplicate"
  appointmentId: String
  startTime: String (ISO 8601)
  endTime: String (ISO 8601)
  patientName: String?
}

struct AppointmentContext {
  clinicId: String
  doctorId: String?
  patientId: String?
  appointmentDate: String (YYYY-MM-DD)
  appointmentTime: String (HH:MM, 24-hour)
  durationMinutes: Integer
  operatory: String?
  roomId: String?
  requestingRole: String
  existingAppointmentId: String? (for updates; used to exclude from conflict detection)
  bufferMinutes: Integer? (default: from clinic settings)
}

struct DoctorSchedule {
  doctorId: String
  dayOfWeek: String ("monday" | "tuesday" | ... | "sunday")
  startTime: String (HH:MM)
  endTime: String (HH:MM)
  isOff: Boolean (true = doctor off all day)
}

struct ClinicOperatingHours {
  dayOfWeek: String ("monday" | "tuesday" | ... | "sunday")
  startTime: String (HH:MM)
  endTime: String (HH:MM)
  isClosed: Boolean (true = clinic closed all day)
}

STATES:
  - requested
  - scheduled
  - confirmed
  - in_progress
  - completed
  - cancelled
  - no_show

TRANSITION RULES:
  from: "requested"   → to: ["scheduled", "confirmed", "cancelled", "completed"]
  from: "scheduled"   → to: ["confirmed", "cancelled", "in_progress", "completed"]
  from: "confirmed"   → to: ["in_progress", "cancelled", "no_show", "scheduled", "completed"]
  from: "in_progress" → to: ["completed", "cancelled", "no_show", "confirmed"]
  from: "completed"   → to: ["in_progress", "confirmed"]
  from: "cancelled"   → to: ["scheduled", "no_show", "confirmed"]
  from: "no_show"     → to: ["scheduled", "cancelled", "confirmed"]

NOTE: Backward transitions are allowed for data correction (e.g., marking a wrong no_show as confirmed)

function isValidTransition(currentStatus: String, newStatus: String) → Boolean {
  // Check if newStatus exists in the allowed transitions for currentStatus
}

function isFinalState(status: String) → Boolean {
  // Returns true if status is "completed" or "cancelled"
}

Condition: appointmentDate + appointmentTime < current_datetime
Result: 
  allowed: false
  code: "PAST_DATE"
  message: "Cannot schedule appointments in the past"
  severity: "blocking"

Condition: 
  - Clinic is marked closed for appointmentDate
  OR
  - appointmentTime is outside clinic's operating hours for that day
Result:
  allowed: false
  code: "CLINIC_CLOSED" | "OUTSIDE_CLINIC_HOURS"
  message: "Clinic is not open at that time"
  severity: "blocking"

Condition:
  - doctorId provided
  - Doctor's schedule for appointmentDate has isOff = true
Result:
  allowed: false
  code: "DOCTOR_OFF"
  message: "Doctor is not available on {appointmentDate}"
  severity: "blocking"

Condition:
  - doctorId provided
  - appointmentTime falls outside doctor's schedule for appointmentDate
Result:
  allowed: false
  code: "OUTSIDE_DOCTOR_HOURS"
  message: "Doctor is not working at {appointmentTime}"
  severity: "blocking"

LOGIC:
  Get doctor's schedule for day_of_week(appointmentDate)
  If no schedule found: doctor available all clinic hours
  If schedule found:
    Appointment must fall within [startTime, endTime]
    Appointment start + duration must not exceed endTime

Condition:
  - Query appointments table for:
    * patientId = context.patientId
    * appointmentDate = context.appointmentDate
    * status != "cancelled"
Result (if found):
  allowed: false
  code: "PATIENT_DUPLICATE"
  message: "Patient already has an appointment on {appointmentDate}"
  severity: "blocking"

Condition:
  - Query appointments table for overlapping time slots with buffer
  
LOGIC:
  effectiveStart = appointmentTime - bufferMinutes (in minutes)
  effectiveEnd = appointmentTime + durationMinutes + bufferMinutes
  
  Find appointments where:
    * appointmentDate = context.appointmentDate
    * status != "cancelled"
    * doctorId = context.doctorId (if specified)
    * operatory = context.operatory (if specified)
    * appointment.startTime < effectiveEnd
    * appointment.endTime > effectiveStart
  
  If any appointments found:
    Result:
      allowed: false
      code: "CONFLICT"
      message: "Doctor/Room is already booked at that time"
      severity: "blocking"
      conflicts: [array of ConflictDetail objects]
  
  Include ALL overlapping appointments in conflicts array

If ANY rule fails → return that rule's result
If ALL rules pass → 
  Result:
    allowed: true
    code: "OK"
    message: "Appointment can be created"

Condition:
  - requestingRole = "patient"
  - patientId in request != appointment.patientId
Result:
  allowed: false
  code: "NOT_OWN_APPOINTMENT"
  message: "Patients can only cancel their own appointments"
  severity: "blocking"

Condition:
  - requestingRole = "patient"
  - appointmentDateTime < NOW + 48 hours

LOGIC:
  if (appointmentDateTime - NOW) < 48 hours {
    // Cancellation not allowed
  }

Result (if window violated):
  allowed: false
  code: "CANCELLATION_WINDOW"
  message: "Cancellations must be made 48+ hours in advance"
  severity: "blocking"

Condition:
  - requestingRole in ["superadmin", "admin", "receptionist", "doctor"]
  - No time restrictions apply
Result:
  allowed: true
  code: "OK"

Condition:
  - Use Status State Machine (above) to check if transition is allowed
Result (if invalid):
  allowed: false
  code: "INVALID_TRANSITION"
  message: "Cannot change from {currentStatus} to {newStatus}"
  severity: "blocking"

Condition:
  - newStatus in ["in_progress", "completed", "no_show"]
  - appointmentDateTime > NOW (in the future)
Result:
  allowed: false
  code: "FUTURE_APPOINTMENT"
  message: "Cannot mark {newStatus} before appointment time"
  severity: "blocking"

LOGIC:
  Cannot transition to these statuses until the appointment time has arrived

Condition:
  - currentStatus = "scheduled" | "confirmed" | "in_progress"
  - newStatus = "cancelled"
  - appointmentDateTime < NOW (appointment is in the past)
Result:
  allowed: false
  code: "PAST_APPOINTMENT_CANCEL"
  message: "Cannot cancel past appointments; mark as no_show instead"
  severity: "blocking"

LOGIC:
  For appointments that have already occurred, use "no_show" instead of "cancelled"

Condition:
  - Check if requestingRole has permission to set newStatus

PERMISSION MATRIX:
  superadmin:   ALL statuses ["requested", "scheduled", "confirmed", "in_progress", "completed", "cancelled", "no_show"]
  admin:        ALL statuses ["requested", "scheduled", "confirmed", "in_progress", "completed", "cancelled", "no_show"]
  receptionist: ["scheduled", "confirmed", "cancelled", "no_show", "completed"]
  doctor:       ["confirmed", "in_progress", "completed", "no_show"]
  patient:      ["cancelled"]

Result (if role not permitted):
  allowed: false
  code: "ROLE_PERMISSION"
  message: "{requestingRole} cannot set status to {newStatus}"
  severity: "blocking"

Check rules in order: 4.1 → 4.2 → 4.3 → 4.4

If ANY rule fails → return that rule's result
If ALL rules pass →
  Result:
    allowed: true
    code: "OK"
    message: "Status can be changed"

function calculateAvailableSlots(clinicId, date, doctorId?) {
  // Step 1: Get clinic operating hours for day_of_week(date)
  clinicHours = getClinicOperatingHours(clinicId, dayOfWeek)
  if (clinicHours.isClosed) {
    return {
      slots: [],
      clinicClosed: true,
      doctorOff: false,
      clinicPhone: clinic.phone
    }
  }
  
  // Step 2: Resolve time range
  startHour = clinicHours.startTime
  endHour = clinicHours.endTime
  
  // Step 3: If doctorId provided, intersect with doctor's hours
  if (doctorId) {
    doctorSchedule = getDoctorSchedule(doctorId, dayOfWeek)
    if (doctorSchedule.isOff) {
      return {
        slots: [],
        clinicClosed: false,
        doctorOff: true,
        clinicPhone: null
      }
    }
    // Intersect clinic and doctor hours
    startHour = max(clinicHours.startTime, doctorSchedule.startTime)
    endHour = min(clinicHours.endTime, doctorSchedule.endTime)
  }
  
  // Step 4: Generate 30-minute slots
  slots = []
  current = startHour
  while (current + 30min <= endHour) {
    slots.push(current)
    current += 30 minutes
  }
  
  // Step 5: Filter out booked slots
  bookedAppointments = query appointments where:
    * appointmentDate = date
    * status != "cancelled"
    * if doctorId provided: doctorId = context.doctorId
  
  for each bookedAppointment {
    remove from slots: [bookedAppointment.startTime, bookedAppointment.startTime + 30min)
  }
  
  // Step 6: Remove past slots if date = TODAY
  if (date == TODAY) {
    now = current time
    slots = filter(slots where slot time > now)
  }
  
  return {
    slots: slots,
    clinicClosed: false,
    doctorOff: false,
    clinicPhone: null
  }
}

Condition:
  - newStatus = "completed"
  - No invoice record exists for this appointment
  - No invoice included in current request
Result:
  allowed: false
  code: "INVOICE_REQUIRED"
  message: "Appointment must have an invoice before completion"
  severity: "blocking"

LOGIC:
  If completing an appointment:
    1. Check if invoice already exists in database
    2. Check if invoice is being created in this request
    If neither: return error

Condition:
  - requestingRole = "patient"
  - attempting to modify appointment fields (not just status)
Result:
  allowed: false
  code: "PATIENT_WRITE"
  message: "Patients cannot modify appointment details; use cancellation to reschedule"
  severity: "blocking"

NOTE: Patients CAN:
  - Cancel their own appointments
  - View their own appointments
  
Patients CANNOT:
  - Change appointment time/date/doctor/operatory
  - Create appointments for others
  - Delete appointment records