# 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.

## Before you rely on this

**Not professional advice.** This capability calculates health figures from published rules. It is a software component for developers, not medical advice. Rules change and every rate here has an effective date. Check that the dates cover your case. Verify results against the official sources listed above, and have a clinician review how you use it, before anyone relies on the output. Provided "as is" under its licence, without warranty.

**Not a medical device.** It is not intended to diagnose, treat or support clinical decisions about any individual. Anyone building it into clinical software is responsible for that software's regulatory status, and must validate it under their own clinical governance.

**Unreviewed.** This capability's implementations agree in every language and pass its published test vectors, which were worked out from the official sources cited. But no qualified clinician has yet checked those vectors, or confirmed that the capability covers the cases it claims. Treat it as a draft. Do not use it for real people, money or decisions without your own expert review. Once a qualified reviewer signs off, this notice is replaced with their name, qualification and the date. Each new version needs fresh sign-off.

1.0.1 marks it unreviewed. The code and the tests are unchanged.