Care Calendar: Recurring Appointments, Exceptions and Availability

Care Calendar: Recurring Appointments, Exceptions and Availability

You've joined the platform team at Riverside Family Clinic. carecal is the small service behind the front-desk booking screen and the shared staff calendar: clinicians, rooms and equipment each have a calendar, and an *event* books one or more of them. Last month the clinic moved off its old scheduling tool and the front desk has been flagging gaps ever since:

> "Our daily vaccine-fridge check shows up for every day except the last one. The biweekly

> diabetes group and the monthly 'last weekday' audit just say *not supported*, so we are retyping

> them by hand. And once those work, we need to cancel or move a single session without touching

> the rest, and then 'edit this and all following'."

The scheduling assistant (free/busy, conflicts, "find us a slot") is queued right behind. Everything is floating local time: a date plus a time of day on one wall clock. There are no time zones and no daylight-saving shifts.

Codebase

How your code is run

run(operations: list[list]) -> list executes the operations in order against a fresh calendar and returns one result per operation. Every operation is [name, *args]. Failures are returned as "error: <code>", never raised. An operation that is not a non-empty list starting with a string returns "error: invalid arguments"; an unknown name returns "error: unknown operation" (checked before argument counts); a wrong number of arguments returns "error: invalid arguments".

Formats. Dates are YYYY-MM-DD and must lie in 1900-01-01 .. 2200-12-31. Clock times are HH:MM (00:00-23:59). Times in results are YYYY-MM-DDTHH:MM. An event's end is start + minutes and may fall on a later day. *Stamps* in the code are absolute minute numbers; intervals are half-open [start, end), so two intervals that merely touch do not overlap.

Event object (create; unknown keys are rejected):

An *instance* is one concrete occurrence. Its id is "<event id>@<original date>", where the original date is the date the recurrence rule generated; that id never changes, even if the occurrence is later moved.

Part 1 — Recurrence rules (FD-318, FD-327)

Goal: make create and occurrences honour the supported subset of iCalendar RRULEs. Today only DAILY is implemented and its UNTIL day is missing; WEEKLY and MONTHLY answer not supported.

occurrences lists the instances whose start date lies in [from_date, to_date] (both inclusive), ordered by start, then end, then instance id. from_date > to_date, a non-string or empty id or a malformed date is invalid arguments.

Rule text is KEY=VALUE pieces joined by ; in any order (FREQ=WEEKLY;INTERVAL=2;BYDAY=TU,TH;COUNT=10). Syntax and validation are already implemented in rrule.parse_rule — read its docstring. Defaults it fills in: WEEKLY without BYDAY uses DTSTART's weekday; MONTHLY with neither BYDAY nor BYMONTHDAY uses DTSTART's day of the month. UNTIL is a plain date, like DTSTART.

What a rule generates (this is the part to implement):

1. DAILY: DTSTART, then every INTERVAL days.
2. WEEKLY: weeks run Monday to Sunday. Week 0 is the week containing DTSTART; the rule is active in weeks 0, INTERVAL, 2·INTERVAL, ... and in an active week generates that week's BYDAY weekdays. Days earlier than DTSTART are never generated.
3. MONTHLY: the rule is active in DTSTART's month and every INTERVAL months after it, and in an active month generates at most one date:

• BYMONTHDAY=n: the n-th, if the month has one. A month without that day is skipped (it is not moved to the last day). BYMONTHDAY=31 therefore hits only Jan, Mar, May, Jul, Aug, Oct, Dec.
• BYDAY=...;BYSETPOS=p: collect every date of the month whose weekday is in BYDAY, ascending; take the p-th (1 is the first, -1 the last, -2 the second to last). If the month has fewer than |p| such dates it is skipped. BYDAY=MO,TU,WE,TH,FR;BYSETPOS=-1 is "last weekday of the month".

1. DTSTART is not automatically an occurrence: only dates the rule generates count, so a weekly rule BYDAY=FR anchored on a Wednesday starts that Friday, and BYMONTHDAY=15 anchored on the 20th starts next month's 15th (or the 15th INTERVAL months on).
2. COUNT=n keeps the first n dates of that sequence. UNTIL keeps dates on or before it (inclusive). With neither, the rule repeats until 2200-12-31, and nothing is ever generated after that.
3. A one-off event (no rule) has exactly one occurrence, on date.

Example

[["create", {"id": "dm-group", "title": "Diabetes group", "date": "2025-01-08", "start": "09:00", "minutes": 30,
             "attendees": ["room-2"], "rule": "FREQ=WEEKLY;INTERVAL=2;BYDAY=MO,WE;COUNT=6"}],
 ["create", {"id": "fridge", "date": "2025-01-31", "start": "07:30", "minutes": 15,
             "attendees": ["nurse-pat"], "rule": "FREQ=MONTHLY"}],
 ["occurrences", "dm-group", "2025-01-01", "2025-03-01"],
 ["occurrences", "fridge", "2025-01-01", "2025-06-30"]]

returns

[true, true,
 [["dm-group@2025-01-08", "2025-01-08T09:00", "2025-01-08T09:30", "Diabetes group"],
  ["dm-group@2025-01-20", "2025-01-20T09:00", "2025-01-20T09:30", "Diabetes group"],
  ["dm-group@2025-01-22", "2025-01-22T09:00", "2025-01-22T09:30", "Diabetes group"],
  ["dm-group@2025-02-03", "2025-02-03T09:00", "2025-02-03T09:30", "Diabetes group"],
  ["dm-group@2025-02-05", "2025-02-05T09:00", "2025-02-05T09:30", "Diabetes group"],
  ["dm-group@2025-02-17", "2025-02-17T09:00", "2025-02-17T09:30", "Diabetes group"]],
 [["fridge@2025-01-31", "2025-01-31T07:30", "2025-01-31T07:45", ""],
  ["fridge@2025-03-31", "2025-03-31T07:30", "2025-03-31T07:45", ""],
  ["fridge@2025-05-31", "2025-05-31T07:30", "2025-05-31T07:45", ""]]]

The group starts on a Wednesday: Monday 6 January is before DTSTART, so week 0 only contributes the Wednesday; the next active week is two weeks later.

Part 2 — Cancel or move a single occurrence (FD-341)

Goal: exceptions that change one occurrence without touching the rule.

date is the occurrence's original date, the one in its instance id (iCalendar's RECURRENCE-ID).

Rules

1. date must be a date the event's rule currently generates (for a one-off, its date); otherwise no such occurrence. An excluded or moved occurrence still has its original date.
2. exclude removes that occurrence. Excluding it again is fine (true). It also discards any override of it.
3. override changes one occurrence. changes is a non-empty object whose keys are among title, date, start, minutes, attendees, validated like create (an empty or unknown-key object is invalid arguments). The occurrence keeps its id; date moves it to a new start date (any valid date, even before DTSTART or the same day as another occurrence). Overriding an excluded occurrence is occurrence excluded.
4. Overrides on the same occurrence merge: a later key replaces the earlier value, other keys are kept.
5. Exceptions never change which dates exist: COUNT still counts every date the rule generates, excluded or moved ones included, and UNTIL is unaffected.
6. occurrences uses an instance's actual start date: a moved instance appears in the window containing its new date, not the one containing its original date.

Example

[["create", {"id": "standup", "title": "Standup", "date": "2025-03-03", "start": "09:00", "minutes": 30,
             "attendees": ["team"], "rule": "FREQ=DAILY;COUNT=5"}],
 ["exclude", "standup", "2025-03-04"],
 ["override", "standup", "2025-03-05", {"date": "2025-03-06", "start": "14:00"}],
 ["occurrences", "standup", "2025-03-03", "2025-03-07"]]

returns

[true, true, true,
 [["standup@2025-03-03", "2025-03-03T09:00", "2025-03-03T09:30", "Standup"],
  ["standup@2025-03-06", "2025-03-06T09:00", "2025-03-06T09:30", "Standup"],
  ["standup@2025-03-05", "2025-03-06T14:00", "2025-03-06T14:30", "Standup"],
  ["standup@2025-03-07", "2025-03-07T09:00", "2025-03-07T09:30", "Standup"]]]

Part 3 — Free/busy, conflicts and "find a slot" (FD-352)

Goal: the scheduling assistant's three questions, answered from the attendee lists. A person is busy whenever an instance they attend (as it actually stands, after exceptions) is happening. People are just names in attendees; an unknown name is simply free. All three take a whole-day window [from_date 00:00, to_date + 1 day 00:00) and an instance counts for the window when its interval overlaps it, including one that started the day before and runs past midnight.

1. busy: the person's instance intervals, clipped to the window, merged into disjoint intervals in ascending order. Intervals that overlap or touch are merged (09:00-09:30 and 09:30-10:00 give 09:00-10:00).
2. conflicts: among the person's instances that overlap the window (not clipped), every pair whose intervals overlap by at least one minute (touching is not a conflict). Sort instances by start, then end, then id; list each pair once as [earlier, later] in that order, pairs ordered by earlier then later.
3. find_slot: attendees is a non-empty list of distinct names, minutes >= 1, and day_start < day_end are clock times. For each day from from_date to to_date, the day offers the window [day_start, day_end]. Return the earliest [start, end] (end = start + minutes) lying entirely inside one day's window during which none of the attendees is busy; touching a busy interval is fine, and the start may be any minute. Days are tried in order; null if nothing fits.
4. invalid arguments covers a bad person/name list, bad dates or from_date > to_date, non-integer or non-positive minutes, and day_start >= day_end.

Example (all times on Monday 2025-03-03 unless stated)

[["create", {"id": "huddle", "title": "Huddle", "date": "2025-03-03", "start": "08:30", "minutes": 30,
             "attendees": ["ng", "ortiz"], "rule": "FREQ=WEEKLY;BYDAY=MO,WE"}],
 ["create", {"id": "consult", "date": "2025-03-03", "start": "08:45", "minutes": 60, "attendees": ["ng"]}],
 ["create", {"id": "clinic", "date": "2025-03-03", "start": "10:00", "minutes": 120, "attendees": ["ortiz"]}],
 ["busy", "ng", "2025-03-03", "2025-03-05"],
 ["conflicts", "ng", "2025-03-03", "2025-03-05"],
 ["find_slot", ["ng", "ortiz"], 30, "2025-03-03", "2025-03-04", "08:00", "12:00"],
 ["find_slot", ["ng", "ortiz"], 60, "2025-03-03", "2025-03-04", "08:00", "12:00"]]

returns

[true, true, true,
 [["2025-03-03T08:30", "2025-03-03T09:45"], ["2025-03-05T08:30", "2025-03-05T09:00"]],
 [["huddle@2025-03-03", "consult@2025-03-03"]],
 ["2025-03-03T08:00", "2025-03-03T08:30"],
 ["2025-03-04T08:00", "2025-03-04T09:00"]]

Part 4 — "Edit this and all following" (FD-366, requirements change)

Until now an event was one record: one rule, one start time, one attendee list. The front desk now needs to change a series from one occurrence onwards (new time, new room, new rule) while the past stays exactly as it was. The event id must keep naming the whole series, so exclusions, overrides and every query keep working on it unchanged.

changes is an object (possibly empty) with keys among title, start, minutes, attendees and rule (rule is a string or null), validated like create; anything else is invalid arguments.

Rules

1. from_date must be an original date the series currently generates (no such occurrence) and must not be excluded (occurrence excluded). Split first, parse the new rule last: a bad rule string is invalid rule and changes nothing.
2. Before from_date nothing changes: same dates, times, titles, attendees, and the same exceptions. That includes an occurrence with an earlier original date that was *moved* to or past from_date: it stays as it is.
3. From from_date on the series is replaced by a new tail anchored at from_date (its DTSTART). Fields not in changes are inherited from the part of the series that contained from_date. Exceptions (exclusions and overrides) whose original date is from_date or later are discarded, and so is every part of the series that came after from_date (from earlier splits).
4. The tail's rule: if changes has a rule string it replaces the rule entirely and is parsed with from_date as DTSTART (same syntax rules as create, same defaults); "rule": null makes the tail a one-off on from_date. Otherwise the tail repeats the same rule with the same cadence (from_date is an occurrence, so interval and weekday patterns line up), and a COUNT is reduced by the number of dates the part before from_date generated, counting excluded and moved ones. An UNTIL stays as it was. A COUNT is per part: it limits the part that carries it.
5. If from_date is the first date of the part being split, nothing remains of that part; earlier parts (if any) are untouched and the tail follows them.
6. Instance ids remain "<event id>@<original date>", using the dates the part that owns them generated.
7. Parts 1-3 behave exactly as before, per part: exclude and override address an original date in whichever part generated it; busy, conflicts and find_slot see each part's own attendees, times and durations.

Example

[["create", {"id": "yoga", "title": "Yoga", "date": "2025-03-03", "start": "17:00", "minutes": 60,
             "attendees": ["room-1"], "rule": "FREQ=WEEKLY;BYDAY=MO;COUNT=6"}],
 ["exclude", "yoga", "2025-03-10"],
 ["split", "yoga", "2025-03-17", {"start": "18:00", "title": "Evening yoga"}],
 ["occurrences", "yoga", "2025-03-01", "2025-05-01"]]

returns

[true, true, true,
 [["yoga@2025-03-03", "2025-03-03T17:00", "2025-03-03T18:00", "Yoga"],
  ["yoga@2025-03-17", "2025-03-17T18:00", "2025-03-17T19:00", "Evening yoga"],
  ["yoga@2025-03-24", "2025-03-24T18:00", "2025-03-24T19:00", "Evening yoga"],
  ["yoga@2025-03-31", "2025-03-31T18:00", "2025-03-31T19:00", "Evening yoga"],
  ["yoga@2025-04-07", "2025-04-07T18:00", "2025-04-07T19:00", "Evening yoga"]]]

The old part kept two dates (3 March and the excluded 10 March), so the tail inherits COUNT=4.

Part 5 — Decades of standing appointments (FD-371, stretch)

The clinic's oldest standing bookings (daily fridge checks, weekly rooms) were back-filled from 1900, and the assistant now runs hundreds of window queries against them, often decades after DTSTART.

Goal: ["count", event_id, from_date, to_date] returns how many instances occurrences would list for the same arguments (an integer; same errors and check order), and every operation must stay fast when a window is far from DTSTART. Hidden tests use series anchored in 1900 with windows in the 2100s, century-wide count windows, COUNT rules with thousands of dates, many such events, and hundreds of queries in one run; the whole suite has a few seconds. Walking a rule forward from DTSTART for every query is too slow, and so is building a century of instances just to count them.

Notes

• dates.py, intervals.py, fields.py and rrule.py are known-good. dates.add_months is *billing* month arithmetic; read its docstring before reusing it.
• You may use the AI assistant freely; you are expected to verify what it produces.
• Later Parts must not break earlier ones; hidden tests re-check earlier behaviour after exceptions and splits.
• Parts 1-4 is a strong result. Part 5 is a stretch.