Carpool Rota: Fair Drivers, Swaps and Two Daily Runs

Carpool Rota: Fair Drivers, Swaps and Two Daily Runs

You've been asked to help the parents' committee at a primary school whose volunteers wrote a small carpool rota. Each school day the rota picks which families drive so that every child who is riding has a seat, and it tries to be fair about whose turn it is. Parents have started to complain about the rota's choices, and two features are queued behind the fixes. A "school day" is a Monday-to-Friday date written YYYY-MM-DD; holidays are not modelled.

Codebase

How your code is run

run(operations: list[list]) -> list executes the operations in order against a fresh rota and returns exactly one result per operation. Each operation is [name, *args]. Errors are returned as "error: <code>" strings, never raised, and a failed operation changes nothing.

• An unknown operation name returns "error: unknown operation". A wrong number of arguments, an operation that is not a list, or a bad family value returns "error: invalid arguments". family_id must be a non-empty string; seats and kids must be integers >= 0 (true/false are not integers).
• seats is how many children the family's car can carry, not counting the driver. A family with seats = 0 has no car and never drives. kids is how many children it has.
• invalid date means the text is not a real YYYY-MM-DD date (including 2025-02-30, 2025-3-3, extra spaces, or a non-string). not a school day means a real date on a Saturday or Sunday.
• absent sets how many of a family's kids are away on that date; a later absent for the same family and date replaces the earlier number. count must be an integer from 0 to the family's kids, otherwise invalid count.
• unavailable marks a family as unable to drive on that date. Repeating it is harmless; there is no way to undo it.
• Days can be planned in any order. Families may still be added after some days are planned; they take part in days planned afterwards.

Part 1: Fix the driver selection (RIDE-198, RIDE-203, RIDE-207)

Goal: make plan pick drivers by the rules below. Three complaints came in:

1. "Our 2-seat car matched the two kids riding exactly, yet a second family got drafted too."
2. "The rota keeps favouring whoever signed up first, even when everyone has driven equally."
3. "A day the rota said it couldn't cover still counted against us."

Rules for plan

1. Riders on a day = the sum over all families of kids - absent for that day.
2. Candidates are families with seats > 0 that have not marked that day unavailable.
3. Candidates are ordered by fewest drives so far, ties broken by family id, ascending (plain string comparison: "F10" < "F9", uppercase before lowercase).
4. Take candidates from the front of that order, one at a time, only while the seats chosen so far are fewer than the riders. The chosen families' seats then cover the riders (seats >= riders is enough). The result lists the chosen ids in the order they were taken.
5. A day with zero riders needs no driver: the result is [] and nobody's count changes, but the day is planned.
6. If all candidates together still cannot seat the riders, return error: cannot cover: no counts change and the day is not marked as planned. Each chosen driver's drives count rises by one only when the plan succeeds. Planning an already planned date returns already planned.

Worked example

[["family", "ng", 4, 2], ["family", "ortiz", 4, 3], ["family", "patel", 2, 2],
 ["unavailable", "ortiz", "2025-03-03"],
 ["absent", "patel", "2025-03-03", 1],
 ["plan", "2025-03-03"], ["plan", "2025-03-04"], ["drives", "ng"]]

returns [true, true, true, true, true, ["ng", "patel"], ["ortiz", "ng"], 2]. On 03-03 six kids ride; ng (4 seats) and patel (2) seat exactly six. On 03-04 seven ride; ortiz has no drives yet, and ng beats patel on id.

tests/test_rota.py has tests for these complaints; some currently fail.

Part 2: Swaps and cover requests (RIDE-212)

Goal: after the rota is published, families ask to trade drives or hand a drive to a neighbour. Implement swap and cover in carpool/swaps.py (the dispatcher already routes to them).

Rules (checks run in this order; the first that fails is the error, and a failure changes nothing)

1. unknown family (for swap: family_a first, then family_b; for cover: from_family, then to_family), then the usual date errors (invalid date, not a school day, for swap date_a first).
2. same family if both families are the same; for swap, same slot if both dates are the same date.
3. not planned if either day has no plan (date_a first).
4. not driving if the giving family is not on that day's roster (for swap: family_a on date_a, and family_b on date_b).
5. already driving if the receiving family is already on the roster it would join.
6. unavailable if the receiving family cannot drive that day: it marked the day unavailable or has no car (seats = 0).
7. cannot cover if, after the change, a day's drivers have fewer seats than the riders. The riders of a day are fixed at the moment it was planned; later absent calls do not change them.
8. On success the new driver takes the old driver's position in the roster, and fairness counts follow: the family that gave up a drive loses one count, the one that took it gains one. (A swap therefore nets to zero until Part 3.)

The result of every earlier operation is a snapshot: a later swap or cover never changes a list that plan or roster already returned.

Worked example

[["family", "a", 3, 2], ["family", "b", 3, 1], ["family", "c", 2, 1],
 ["plan", "2025-03-03"], ["plan", "2025-03-04"],
 ["swap", "2025-03-03", "b", "2025-03-04", "c"],
 ["cover", "2025-03-04", "a", "c"],
 ["cover", "2025-03-04", "b", "c"],
 ["roster", "2025-03-03"], ["roster", "2025-03-04"], ["drives", "a"], ["drives", "c"]]

returns [true, true, true, ["a","b"], ["c","a"], true, true, "error: already driving", ["a","c"], ["b","c"], 1, 2]. Four kids ride each day. After the swap the rosters are ["a","c"] and ["b","a"]; the cover then replaces a with c on 03-04, giving ["b","c"]. The last cover fails because c already drives that day.

Part 3: Morning and afternoon runs (RIDE-231)

Goal: the school now runs a morning run (am) and an afternoon run (pm) with their own rosters. Parents are available for one but not the other, and a family that did all the mornings should still be in line for afternoons. Every earlier rule keeps working for a single run; the differences are:

1. A slot is a date plus a run: "2025-03-03:pm". A bare date such as "2025-03-03" means "2025-03-03:am" for plan, roster, swap and cover. An unknown run (including "PM", an empty run, "2025-03-03:") gives error: invalid run, checked after the date itself.
2. Each slot has its own plan, rider count and roster. plan on "d" and on "d:pm" are different days' work and either can come first; already planned is per slot.
3. For unavailable and absent a bare date applies to both runs of that day, while "d:am" or "d:pm" applies only to that run. A bare-date absent replaces both runs' figures; a later run-specific call replaces just that run.
4. Fairness is per run type. Rule 3 of Part 1 now compares drives done in the run being planned (an am plan compares morning drives; ties still go to the smaller id). A family's pm drives do not count for an am plan, and vice versa.
5. drives family_id still returns the family's total over both runs; drives family_id run ("am" or "pm") returns just that run (invalid run for anything else, checked after unknown family).
6. swap and cover take slots. Availability and the no-car rule apply to the slot the receiver moves into. Counts move per run: in a swap between an am and a pm slot, family_a loses an am drive and gains a pm drive, family_b the opposite. For swap the date errors become slot errors (invalid date, not a school day, invalid run; slot a first), and same slot now compares the full slots ("d" and "d:am" are the same slot).

Worked example

[["family", "a", 3, 2], ["family", "b", 3, 1], ["family", "c", 2, 1], ["family", "d", 3, 0],
 ["plan", "2025-03-03"], ["plan", "2025-03-03:pm"], ["plan", "2025-03-04:pm"],
 ["swap", "2025-03-03", "a", "2025-03-04:pm", "c"],
 ["plan", "2025-03-04"],
 ["drives", "a"], ["drives", "a", "am"], ["drives", "a", "pm"], ["drives", "c"]]

returns [true, true, true, true, ["a","b"], ["a","b"], ["c","d"], true, ["a","d"], 3, 1, 2, 1]. Both 03-03 runs go to a and b (no one has driven either run yet). On 03-04:pm a and b have a pm drive each, so c and d drive. The swap makes the 03-03 morning ["c","b"] and the 03-04 afternoon ["a","d"]; a's counts become am 0, pm 2, c's am 1, pm 0. Planning 03-04 (morning) then looks at morning counts only (a 0, d 0, b 1, c 1) and picks a, then d.