Campus Dining: Meal Swipes, Guest Passes and Block Plans

Campus Dining: Meal Swipes, Guest Passes and Block Plans

You've joined the small team that runs the university dining card system. Students swipe their ID at three dining halls, spend dining dollars at retail counters, and bring guests. The Registrar's office has filed three bug reports against the swipe rules, and the dining director has two changes queued behind them. All money is integer cents.

Codebase

How your code is run

run(operations: list[list]) -> list executes the operations in order against a fresh system and returns one result per operation. Every operation is [name, ts, ...args], where ts is a local campus time string "YYYY-MM-DD HH:MM" (24-hour clock). Timestamps never decrease. Errors are returned as "error: <code>" strings, never raised. Use datetime for everything calendar-related.

An unknown operation name returns "error: unknown operation". A wrong argument count, a malformed or impossible timestamp ("2026-10-19 7:00", "2026-02-30 12:00", a non-string) or a non-list operation returns "error: invalid arguments". A valid amount is an integer (not true/false): > 0 for buy, >= 0 for the starting dollars in enroll.

Time rules

• A week runs from Sunday 00:00 to Saturday 23:59. Weekly allowances are refilled lazily by StudentRegistry.roll_week the first time a student is touched in a new week.
• Meal periods (start inclusive, end exclusive; outside them the halls are closed): breakfast 07:00-10:30, lunch 11:00-15:00, dinner 17:00-21:00, late-night 21:00-24:00.
• Halls are north, south, west. Retail locations are cafe, market, grill.

Plans and swipes

• swipe spends one plan swipe. A student may swipe once per meal period per hall per day; a second swipe in the same (day, period, hall) is already swiped, but another hall, another period or another day is fine.
• Automatic fallback: when the student has no plan swipes left, swipe is paid with dining dollars at the period's swipe value (breakfast 800, lunch 1200, dinner 1500, late-night 1000 cents) as long as dollars >= value. Otherwise no swipes or dining dollars.
• Unused swipes do not roll over. Each new week starts at exactly the plan's weekly swipes.
• guest_swipe spends one guest swipe (a semester allowance, never refilled weekly). Guest swipes do not use plan swipes or dining dollars and are not limited by the once-per-period rule.
• Swipe ids are sw-1, sw-2, ... in the order swipes (own or guest) succeed; a rejected swipe does not use an id. A receipt is {"id", "period", "paid", "cents"} where paid is "swipe", "dollars" or "guest", and cents is what was charged in dining dollars (0 unless paid is "dollars").
• balance first brings the student's week up to date, then reports.

Worked example

[["enroll", "2026-10-17 09:00", "ana", "w7", 5000],
 ["swipe", "2026-10-17 12:00", "ana", "north"],
 ["swipe", "2026-10-17 12:30", "ana", "north"],
 ["swipe", "2026-10-17 12:40", "ana", "south"],
 ["guest_swipe", "2026-10-17 18:00", "ana", "west"],
 ["balance", "2026-10-17 23:59", "ana"],
 ["balance", "2026-10-18 00:00", "ana"]]

returns

[true,
 {"id": "sw-1", "period": "lunch", "paid": "swipe", "cents": 0},
 "error: already swiped",
 {"id": "sw-2", "period": "lunch", "paid": "swipe", "cents": 0},
 {"id": "sw-3", "period": "dinner", "paid": "guest", "cents": 0},
 {"plan": "w7", "swipes_left": 5, "guests_left": 3, "dollars": 5000},
 {"plan": "w7", "swipes_left": 7, "guests_left": 3, "dollars": 5000}]

(2026-10-17 is a Saturday, 2026-10-18 a Sunday.)

Part 1: Fix the swipe rules (DINE-418)

Goal: make the system behave as described above. Reports from the field: "My swipes didn't refill on Sunday." "I skipped a week and now I have more than 7 swipes." "I couldn't swipe at the second hall for lunch."

Rules

1. Weeks start on Sunday 00:00 (see the Time rules). Saturday 23:59 belongs to the old week.
2. A new week resets the student to the plan's weekly swipes, whatever was left over, however many weeks were skipped.
3. The once-per-period rule is per (day, period, hall).

tests/test_swipes.py has two failing tests that show the symptoms. Everything else in the table and rules above already works and must keep working.

Part 2: Guest-swipe transfers and refunds (DINE-433)

Goal: students can give guest swipes to each other, and the front desk can refund a swipe that was charged in error. Both operations replace the "not supported" stubs in dining/refunds.py.

Rules

1. count must be an integer > 0 (not a boolean). A student may hold at most 10 guest swipes: a transfer that would take the receiver above 10 is over guest cap. Nothing changes on any error.
2. A refund of a guest swipe gives the guest swipe back to the student who was charged ("credited": "guest_swipe", "amount": 1), even if they hold more than 10 afterwards.
3. A refund of a swipe paid with dining dollars gives back exactly the cents charged, in any week ("credited": "dollars", "amount": <cents>).
4. A refund of a plan swipe charged earlier in the *current* week restores one plan swipe ("credited": "week_swipe", "amount": 1). A plan swipe charged in an earlier, finished week cannot come back as a swipe (that would be a rollover); it is paid back in dining dollars at the swipe value of its meal period ("credited": "dollars").
5. Refunding a student's own swipe (plan or dollars) frees its (day, period, hall) slot so the student may swipe there again. Guest swipes never held a slot, so refunding one frees nothing.
6. A swipe can be refunded once. Refunded swipes keep their ids; the next new swipe still gets the next number.

Example (after enrolling ana and bo, both w7, with 5000 dollars and 0)

[["transfer_guest", "2026-10-19 10:00", "ana", "bo", 3],
 ["swipe", "2026-10-19 12:00", "ana", "north"],
 ["guest_swipe", "2026-10-19 12:05", "ana", "north"],
 ["refund", "2026-10-19 12:30", "sw-2"],
 ["swipe", "2026-10-19 12:40", "ana", "north"]]

returns [{"from": 1, "to": 7}, {sw-1}, {sw-2, "paid": "guest"}, {"swipe": "sw-2", "credited": "guest_swipe", "amount": 1}, "error: already swiped"]. Refunding sw-1 instead would have freed the slot.

Part 3: Block plans and mid-semester conversion (DINE-471)

Goal: the director is introducing block plans: one pool of swipes for the whole semester instead of a weekly allowance. Existing weekly students may convert mid-semester, and their remaining allowance is prorated. This changes what swipes_left means for these students, so earlier rules need to be revisited.

Rules

1. enroll accepts block plans; enrolling directly gets the full block, whatever the date.
2. A block plan never refills: no weekly reset, nothing expires. balance reports the remaining block as swipes_left. Swipes, the once-per-period rule, guest swipes, transfers and the dining-dollar fallback work as before (when the block reaches 0, further swipes are paid with dining dollars).
3. The semester starts Sunday 2026-08-30 and has 15 weeks (week 0 is the week starting 2026-08-30; week_index in clock.py computes it). convert_plan outside weeks 0-14 (before 08-30 00:00 or from 2026-12-13 00:00) is outside semester.
4. Conversion of a weekly student at ts: first bring their week up to date. Let used be the plan swipes already spent this week (the plan's weekly swipes minus what is left now; dining-dollar and guest swipes do not count). Let weeks_left be 15 - week_index (the current week counts). The new balance is max(0, block_total * weeks_left // 15 - used), rounded down, never negative. Guest swipes and dining dollars are unchanged; the old weekly allowance is gone.
5. Refunds (Part 2) now depend on where the swipe came from. A refunded block swipe always goes back to the block ("credited": "block_swipe"). A weekly plan swipe still counts as current only if its week is the current week: then it restores one swipe to whichever pool the student has *now* ("week_swipe" for a weekly plan, "block_swipe" after converting); otherwise it pays dining dollars at the period's swipe value, exactly as in Part 2. Dollar and guest refunds are unchanged.

Example

[["enroll", "2026-10-17 09:00", "ana", "w7", 4000],
 ["swipe", "2026-10-21 12:00", "ana", "north"],
 ["swipe", "2026-10-21 17:30", "ana", "north"],
 ["guest_swipe", "2026-10-21 18:00", "ana", "north"],
 ["convert_plan", "2026-10-21 19:00", "ana", "b150"],
 ["convert_plan", "2026-10-21 19:01", "ana", "b100"]]

returns [true, {sw-1}, {sw-2}, {sw-3, "paid": "guest"}, {"plan": "b150", "swipes_left": 78}, "error: already on block plan"]. Wednesday 2026-10-21 is in week 7, so 8 weeks remain: 150 * 8 // 15 = 80, minus 2 plan swipes already used this week (the guest swipe is not one).

Earlier Parts must keep behaving exactly as specified for weekly plans.