# health.appointment-slots

Lists the appointment slots that can still be booked. It takes clinic sessions
(a date with a start and end time), a slot length, breaks and the bookings
already made. It is pure scheduling arithmetic on wall-clock times: no time
zones, no clock reads, and the same input always gives the same list.

## How the slots are laid out

- **Breaks reshape a session.** A break (lunch, a team meeting) splits the
  session into free segments. Slots are laid back to back from the start of
  each segment, so after a 12:30-13:30 lunch the first slot is at 13:30, not
  wherever the morning's grid would have landed. A break with a null date
  applies to every session day. A break with a date applies to that day only.
- **Leftovers are dropped.** A slot must fit wholly inside its segment. With
  20-minute slots, 09:00-12:30 gives ten slots ending at 12:20, and the last
  10 minutes are not offered.
- **Bookings only take slots away.** A slot that overlaps any booking on the
  same date is removed, but the grid does not move. Bookings are made into
  slots, so a 5-minute booking at 09:05 removes the 09:00 slot and leaves
  09:20 where it was. A booking across two slots removes both.
- **Touching is not overlapping.** Intervals are half-open (start included,
  end excluded), so a booking ending at 09:15 leaves the 09:15 slot free.

Sessions may be given in any order. The result is sorted by date, then start
time.

## Errors

The function refuses, rather than guessing, when:

- a time is not `HH:MM` from 00:00 to 23:59 (`9:00` and `24:00` are refused)
- a date is not a real ISO date
- a session, break or booking does not end after it starts
- two sessions on the same date overlap
- `slotMinutes` is not a whole number from 1 to 480

A session cannot cross midnight. Split an overnight clinic into two sessions,
one on each date.

## What it does not do

It does not handle clinicians, rooms or appointment types. Call it once per
clinician or resource. It does not handle double-booking capacity (more than
one patient per slot) or daylight-saving changes. It does not keep slots in
the past out of the list, because it never reads the clock: pass only the
sessions still to come.