RotaDesk: Shift Swaps, Approvals and Three-Way Cycles

RotaDesk: Shift Swaps at Memorial General

You've joined the team that builds RotaDesk, the nurse scheduling app at Memorial General Hospital. Nurses can put a shift on the swap marketplace; a colleague answers by either *taking* it (a giveaway) or *offering one of their own shifts in return* (a trade). Whether a swap is allowed depends on qualifications, rest, weekly hours and overlaps. The unit's charge nurses have complained that RotaDesk's "is this swap OK?" check lets through swaps that leave nurses with 7 hours between shifts, and blocks swaps that are fine. Three tickets are queued: fix the check, add the charge-nurse approval workflow, then support three-way swap cycles.

Codebase

How your code is run

run(operations: list[list]) -> list executes the operations in order against a fresh hospital and returns one result per operation. Every operation is [name, *args]. Errors in looking things up or in permissions are returned as "error: <code>" strings, never raised. Rule violations found while validating a swap are different: they are returned as {"errors": [message, ...]} (see below). Times are written "YYYY-MM-DD HH:MM", hospital-local wall-clock time (no time zones, no daylight saving). A shift ends on the later day when it crosses midnight.

• A malformed argument (wrong count, wrong type, empty id, a time that doesn't parse, count < 1, count > 50000, every_days < 1) returns "error: invalid arguments" before anything else is checked. An unknown operation name returns "error: unknown operation".
• quals is a list of qualification names, charge a boolean. Valid units and the qualifications each requires are in rota/config.py. A nurse must hold all of a unit's qualifications.
• invalid times: end is not after start, or the shift is longer than 16 hours (exactly 16:00 is fine). add_pattern creates shifts <prefix>-1 ... <prefix>-<count> (all-or-nothing), the first at start/end and each next one every_days days later. A shift added with a null nurse is unassigned and can't be posted.
• post answers not owner when the shift isn't currently the nurse's. A shift can have only one open listing at a time. A rejected post does not use up a listing id.
• A nurse can't answer their own listing (own listing). For a trade, offered_shift_id must be currently owned by the nurse answering.

Worked example. Ben isn't TRIAGE-qualified, and his own shift s2 starts 9 h 59 min after s1 ends.

[["add_nurse", "ana", ["ACLS", "TRIAGE"], false],
 ["add_nurse", "ben", ["ACLS"], false],
 ["add_shift", "s1", "ER", "2025-03-03 07:00", "2025-03-03 19:00", "ana"],
 ["add_shift", "s2", "ER", "2025-03-04 04:59", "2025-03-04 13:00", "ben"],
 ["post", "ana", "s1"],
 ["preview_take", "L-1", "ben"]]

returns

[true, true, true, true, "L-1",
 {"errors": ["ben: missing qualification TRIAGE for s1",
             "ben: only 9:59 rest between s1 and s2"]}]

Part 1: Fix the swap check (INC-2210, INC-2237)

Goal: preview_take and preview_trade must report exactly the violations a swap would cause. A swap is valid when, after it has happened, every nurse who *receives* a shift satisfies the rules below with respect to that shift. Reports from the floor: a nurse with exactly 10 hours between two shifts was refused; a nurse was cleared for a Sunday-night shift and ended up over the weekly cap; two colleagues could not trade shifts that happen at the same time even though each leaves the slot they hold; and previewing the same swap twice gave two different answers.

Rules

1. Qualifications: the receiver must hold every qualification of the shift's unit.
2. Overlap: the received shift must not intersect any other shift the receiver works. Two shifts intersect only if each starts strictly before the other ends; shifts that merely touch don't overlap.
3. Rest: between the received shift and every other shift the receiver works, the gap (start of the later minus end of the earlier) must be at least 10 hours. Exactly 10:00 is fine, 9:59 is not, and touching shifts (gap 0:00) are a rest violation, not an overlap. Overlapping pairs are reported only as overlaps.
4. Weekly hours: weeks run from Monday 00:00 to the next Monday 00:00. A shift's minutes count toward the week they fall in, so a shift from Sunday 19:00 to Monday 07:00 counts 5:00 toward the week that ends and 7:00 toward the next one. For each week in which the received shift has at least one minute (a shift ending exactly at Monday 00:00 belongs only to the week before), the receiver's total minutes in that week (including the received shift) may be at most 48:00; 48:00 is fine, 48:01 is not.
5. After the swap: shifts the receiver gives away in the same swap don't count for rules 2-4. A trade is judged this way, and so is any swap in which a nurse both gives and receives.
6. Only pairs and weeks that involve the received shift are examined. Violations that already exist elsewhere in a nurse's roster are not the swap's problem.
7. A preview never changes anything: asking twice gives the same answer and roster is unaffected.

Messages and order. {"errors": [...]} lists every violation. Nurses are reported in the order of the moves; a giveaway has one receiver, and for a trade the poster (who receives the offered shift) comes first and the taker second. For each nurse, in this order:

{H:MM} is hours without padding and minutes with two digits (9:59, 0:00, 49:00). The week date is that week's Monday. In the rest message {earlier} and {later} are the two shift ids in chronological order, whichever one is the received shift.

tests/ contains failing tests for the first and last reports. The weekly-cap and trade reports are covered only by the hidden suite.

Part 2: Charge-nurse approval (INC-2301)

Goal: a swap no longer happens just because it is valid. take and trade now *propose* a swap that a charge nurse must approve; nothing moves until then. The previews from Part 1 stay exactly as they are.

Rules

1. take and trade validate exactly like the previews. If there are violations, return {"errors": [...]} and create nothing (no swap id is used). Otherwise the swap is filed as pending with the next id (sw-1, sw-2, ... one counter shared by every kind of swap).
2. Pending swaps reserve nothing. Shifts stay with their owners, the listing stays open, and validation always uses the real current schedule. Any number of pending swaps can involve the same shift or answer the same listing.
3. approve: the approver must be a nurse with charge = true who is not the giver or the receiver of any move in the swap. Then the swap is validated again against the schedule as it is now (other swaps may have been approved since it was proposed):

• if there are violations, the swap becomes void with those messages as its errors, nothing moves, and approve returns {"errors": [...]};
• otherwise every shift in the swap moves to its receiver, the swap becomes approved, and approve returns "ok".

1. When a swap is approved, (a) the open listing of every shift that moved is closed (answering it gives listing closed; the shift's new owner may post it again) and (b) every other pending swap that involves any of the moved shifts becomes void with the single error shift {id} was reassigned by {swap_id}, where {id} is the lowest shift id (plain string order) that the two swaps share. Pending swaps that share no shift are not touched, but rule 3 will re-validate them when they are approved.
2. reject runs the same checks as approve and then marks the swap rejected. Nothing moves and the listing stays open.
3. swap_status returns the status (pending, approved, rejected or void); errors is empty except for a void swap, where it holds the messages from rule 3 or 4.
4. A queue can hold thousands of pending swaps, and nurses' histories can span years. Approvals and proposals must stay fast on long rosters.

Example (after add_nurse for ana, ben, cy with ["ACLS","TRIAGE"] and kim with the same qualifications and charge = true; s1 is an ER shift of Ana's on 2025-03-03 07:00-19:00)

[["post", "ana", "s1"],
 ["take", "L-1", "ben"],
 ["take", "L-1", "cy"],
 ["approve", "sw-1", "kim"],
 ["swap_status", "sw-2"],
 ["take", "L-1", "cy"],
 ["roster", "ben"]]

returns

["L-1", "sw-1", "sw-2", "ok",
 {"status": "void", "errors": ["shift s1 was reassigned by sw-1"]},
 "error: listing closed", ["s1"]]

Part 3: Three-way swap cycles (INC-2388)

Goal: three nurses who want to rotate shifts (Ana's goes to Ben, Ben's to Cy, Cy's to Ana) can't do it with giveaways and trades, so RotaDesk gets a cycle operation. The cycle is proposed as one unit and is all-or-nothing: it is valid only if the schedule *after every shift has moved* is valid for everyone.

Rules

1. legs is a list of [nurse_id, shift_id] pairs. Each listed nurse gives the shift in her pair to the next nurse in the list, and the last nurse gives hers to the first. So [["ana","s1"],["ben","s2"],["cy","s3"]] sends s1 to Ben, s2 to Cy and s3 to Ana.
2. invalid cycle if legs is not a list of 3 to 6 pairs of non-empty strings, or a nurse or a shift appears twice. After that, nurse not found (first missing nurse in list order), then shift not found (first in list order), then not owner (first leg whose nurse doesn't own her shift). A wrong number of top-level arguments is invalid arguments.
3. Shifts need not be posted, and listings are not used.
4. Validation uses the Part 1 rules with all moves applied at once: for every nurse, the shift she gives away is gone and the shift she receives is in. Do not check legs one after another against the current schedule: a nurse may receive a shift that overlaps the one she is giving up. Violations are reported by receiving nurse in the order of legs (the first nurse receives the last leg's shift), each nurse's messages in the Part 1 order. If there are any, return {"errors": [...]} and create nothing.
5. Otherwise the cycle is filed as a pending swap (shared sw-N counter) and from there on behaves like any other swap: Part 2's approval, re-validation, closing of listings, voiding of other swaps and swap_status apply unchanged. The approver may not be any of the cycle's nurses. On approval all shifts move together.

Example (Ana, Ben and Cy all work 07:00-19:00 that Monday in the ER; kim is a charge nurse)

[["cycle", [["ana", "s1"], ["ben", "s2"], ["cy", "s3"]]],
 ["approve", "sw-1", "kim"],
 ["roster", "ana"], ["roster", "ben"], ["roster", "cy"]]

returns ["sw-1", "ok", ["s3"], ["s1"], ["s2"]]. Each nurse's new shift overlaps the one she gives up, which is fine because that one is gone.