Hotel PMS: Half-Open Stays, Overbooking, Room Assignment and Out-of-Order Rooms

Harbour & Pine PMS: Stay Inventory, Room Assignment and Out-of-Order Rooms

You've joined the platform team behind the property-management system that runs Harbour & Pine's boutique hotels. Guests book a room type (standard, deluxe, suite) for a range of nights; the actual room is chosen later by the night audit. The front desks have sent in two tickets, and the revenue team has three features queued behind them. Money is in integer cents; there is no floating point anywhere.

Codebase

How your code is run

run(operations: list[list]) -> list executes the operations in order against a fresh, empty property and returns one result per operation. Every operation is [name, ts, *args].

• Time. ts is a non-negative integer number of hours since the start of day 0 and never decreases from one operation to the next. day = ts // 24, hour = ts % 24. Day 0 is a Monday. Day numbers stay below 5,000.
• Nights. A stay [check_in, check_out) is *half-open*: the guest sleeps the nights check_in ... check_out - 1 and leaves on day check_out. A guest leaving on day 7 and a guest arriving on day 7 do not overlap. Check-in time is 15:00 on the arrival day.
• Errors are returned, never raised, as "error: <code>". An unknown operation name returns "error: unknown operation". A ts that is not a non-negative integer (booleans are not integers), or the wrong number of arguments, returns "error: invalid arguments". Within an operation, a wrongly typed or empty argument is also invalid arguments and is checked before any other error.
• Rates (cents per night): standard 10990, deluxe 15990, suite 27990. Friday and Saturday nights (day % 7 is 4 or 5) cost 125% of that, rounded half up to the cent. A stay's price is the sum of its nights. pricing.py and config.py hold the arithmetic and constants. Room numbers are plain strings, compared in string order.
• Reservations get ids rsv-1, rsv-2, ... in booking order (only accepted bookings use a number). A reservation is booked (holds inventory, no room yet), assigned (has a room plan), in_house, cancelled, no_show or walked. Only booked, assigned and in_house reservations hold inventory.

invalid stay means: check_out <= check_in, a check_in before today, or more than 30 nights. cancel works only on booked or assigned reservations. day_sheet lists, ordered by reservation number (numerically), the active reservations arriving and departing on that day. stay.rooms is [[room, first_night, end_night_exclusive], ...]: empty until a room plan exists, and empty again for reservations that were cancelled, no-shows or walked. fee_ledger records every non-zero fee, kind being "cancellation" (or "no_show" from Part 3).

[["add_rooms", 0, "standard", ["101"]],
 ["book", 1, "ann", "standard", 5, 7],
 ["book", 1, "ben", "standard", 7, 9],
 ["book", 1, "cat", "standard", 6, 8],
 ["availability", 1, "standard", 5, 9],
 ["availability", 1, "standard", 9, 11],
 ["quote", 1, "standard", 5, 7]]

returns [true, "rsv-1", "rsv-2", "error: sold out", 0, 1, 24728]: Ann leaves on day 7 as Ben arrives, so one room serves both; Cat overlaps night 6 and 7. Day 5 is a Saturday (13738) and day 6 a Sunday (10990).

Part 1 - Two defects reported by the front desks (FD-2210, FIN-318)

Goal: make inventory and cancellation fees follow the rules above.

• *FD-2210:* "Our one-room test property shows sold out whenever a guest arrives on the day the previous guest leaves, and cancelling a booking sometimes opens up the wrong nights."
• *FIN-318:* "Cancellations around the 3-day and 1-day marks are charged inconsistently; finance cannot reconcile them against the policy."

Rules

1. A reservation holds inventory on exactly its nights [check_in, check_out); the departure day is not held. availability is max(0, min over the nights of (sellable - held)), where for now sellable is the number of rooms of that type; book fails with sold out when that is 0. Cancelling gives back exactly the nights that booking held.
2. The cancellation fee is a share of the first night's price, decided by hours_out = 24 * check_in + 15 - ts (hours before 15:00 on the arrival day; negative after it): hours_out >= 72 costs nothing; 24 <= hours_out < 72 costs 50%; hours_out < 24 costs 100%. A share is rounded half up to the cent.
3. quote and every other price must not change.

Three tests in tests/test_front_desk.py currently fail. Before you change a shared helper, check who else calls it.

Part 2 - Overbooking and room assignment

Goal: sell a little more than we own, then turn type bookings into real rooms - one room per guest if at all possible.

New operations:

Overbooking. sellable(type, night) = rooms * (100 + percent) // 100 (default percent 0). availability, book and the sold out rule use it. Lowering the percentage never cancels anything.

Assignment. assign_arrivals(day) houses every booked reservation whose first night is day (day >= today, otherwise day in the past; nothing to do returns []). It handles them in priority order: higher loyalty tier first (platinum > gold > silver > none, using each guest's tier *at the time of the call*), then lower reservation number. Each one is housed completely before the next is looked at, and rooms taken by earlier assignments (any arrival day) are not available. A guest booked into type *T* may be housed in a room of *T* or of the next type up (standard -> deluxe -> suite; suite has none).

For one guest staying nights [lo, hi):

1. If any room of the booked type is free on every night, take one room. If several qualify, take the tightest fit: smallest gap, ties to the smaller room number. gap is (start of the next stay in that room, or 1,000,000) - (end of the previous stay in that room, or -1,000,000), using the room's own stays outside [lo, hi), including past ones.
2. Otherwise, if any room of the next type up is free on every night, take one (a free upgrade), tightest fit as above.
3. Otherwise use as few rooms as possible: at the first night not yet covered, look at every room of the booked type and of the next type up that is free that night and take the one that stays free the longest (capped at hi); ties go to the booked type, then the smaller room number. That room covers that run; repeat from the night after it.
4. If at some night no such room is free, the guest is walked: status walked, the whole reservation is released (inventory and any rooms), no fee.

A guest's room plan is [[room, first_night, end_night_exclusive], ...]. assign_arrivals returns, in the order the guests were handled, [reservation_id, tag, segments] where tag is "walked" (segments []), "split" (more than one segment), "upgraded" (one segment in the next type up) or "own". Assigned reservations become assigned. Cancelling an assigned reservation also frees its rooms.

night_audit(days_ahead) runs assign_arrivals for days today + 1 ... today + days_ahead (tomorrow first) and returns how many guests ended with each tag over all those days.

[["add_rooms", 0, "standard", ["101", "102", "103"]],
 ["book", 1, "ann", "standard", 12, 16],
 ["book", 1, "zed", "standard", 13, 15],
 ["book", 1, "gus", "standard", 10, 14],
 ["assign_arrivals", 2, 12], ["assign_arrivals", 2, 13], ["assign_arrivals", 2, 10]]

returns [true, "rsv-1", "rsv-2", "rsv-3", [["rsv-1","own",[["101",12,16]]]], [["rsv-2","own",[["102",13,15]]]], [["rsv-3","own",[["103",10,14]]]]]. Room 101 is busy from night 12 and room 102 from night 13, so Gus gets 103 for all four nights instead of drifting between rooms.

Part 3 - Arrivals, check-in and no-shows

Goal: unclaimed rooms must come back to the pool by themselves.

New operations:

1. No-shows. At 22:00 on the arrival day (ts >= 24 * check_in + 22) every reservation of that day that is still booked or assigned becomes no_show: it is charged the first night's price (ledger kind "no_show"), and every night of the stay is released (inventory and rooms). Checked-in guests are never no-shows.
2. Lazy. There is no timer: before the dispatcher handles any accepted operation (valid name, ts, argument count - including ones that then return an error and repeat's inner operations) it calls FrontDesk.advance(ts), which must apply all no-shows that became due. They are applied oldest arrival day first and, within a day, in reservation order; this fixes the order of fee_ledger entries.
3. A booking, quote or availability check whose first night is today is only valid before 22:00 (invalid stay from 22:00 on).
4. check_in needs an assigned reservation and day(ts) >= check_in (any hour of the arrival day); it makes the reservation in_house. In-house reservations cannot be cancelled (not cancellable).
5. check_in_arrivals(skip_every) checks in every assigned reservation arriving today, in reservation order, except those whose number n (from rsv-n) is a multiple of skip_every (0 skips nobody).

[["add_rooms", 0, "standard", ["101"]],
 ["book", 1, "ann", "standard", 10, 12],
 ["assign_arrivals", 2, 10],
 ["availability", 261, "standard", 11, 12],
 ["availability", 262, "standard", 11, 12],
 ["fee_ledger", 262]]

returns [true, "rsv-1", [["rsv-1","own",[["101",10,12]]]], 0, 1, [["rsv-1","no_show",10990]]]: hour 261 is 21:00 on day 10, hour 262 is 22:00, and Ann never showed up.

Part 4 - Rooms out of order, and a whole season

Goal: housekeeping and maintenance can take a room out of service, even one a guest is already assigned to. This reverses an assumption of Part 2 (that an assignment is final), and the system must also stay fast on a full season of reservations.

New operations:

Blocks. out_of_order takes room out of service for nights [first_night, end_night). It is invalid block if end_night <= first_night or first_night is before today; block overlaps if the room already has a block overlapping those nights (touching blocks are fine). Block ids are ooo-1, ooo-2, ... in order of acceptance. A blocked night counts as occupied in that room for every assignment rule (including gap), and sellable now uses the rooms in service that night: (rooms - blocked rooms of the type) * (100 + percent) // 100. return_to_service lifts the block; nobody is moved back.

Displaced guests - assigned or in_house reservations with a stay in that room during the block. Minimal disruption means:

1. Reservations not in the blocked room during the block are never touched.
2. A displaced guest keeps every night before the first night they lose (their first night in that room that is inside the block). Everything from that night to check_out is re-planned with the Part 2 rules (booked type or next type up, one room if possible, tightest fit, else fewest rooms), now that the block exists.
3. All displaced guests give up their lost nights before anyone is re-planned; then they are re-planned one by one in Part 2 priority order. Two displaced guests can therefore compete for the same room.
4. A guest whose remainder cannot be placed is walked: status walked, the whole reservation released.
5. The result is [block_id, ids of the re-housed guests, ids of the walked guests], each in priority order. Re-housed guests keep their status (in_house stays in_house).

Report. report(first_day, end_day) (end_day > first_day) sums over nights [first_day, end_day): demand = held reservation-nights per room type, occupied = nights occupied by reservations' rooms in rooms of each type, blocked = blocked room-nights (a single number). demand and occupied are objects with the keys standard, deluxe and suite.

Load-test helpers (known-good). ["seed_season", 0, seed, count, first_day, last_day] books count pseudo-random stays through the normal book path and returns [booked, rejected] (see season.py). ["repeat", ts, count, step, [[name, *args], ...]] runs the inner operations count times, iteration i at ts + i * step, and returns the result of the last inner operation only. Hidden tests run a season with thousands of reservations and thousands of operations in one run; the whole suite has a few seconds.

[["add_rooms", 0, "standard", ["101", "102", "103"]], ["add_rooms", 0, "deluxe", ["201"]],
 ["book", 1, "ann", "standard", 10, 14], ["book", 1, "ben", "standard", 11, 13], ["book", 1, "cat", "standard", 12, 15],
 ["assign_arrivals", 2, 10], ["assign_arrivals", 2, 11], ["assign_arrivals", 2, 12],
 ["out_of_order", 3, "101", 12, 20], ["stay", 3, "rsv-1"]]

Ann sleeps in 101 on nights 10-11 and loses it from night 12; 102 and 103 are busy then, so she moves to the deluxe room for the rest of her stay: the block returns ["ooo-1", ["rsv-1"], []] and stay.rooms becomes [["101", 10, 12], ["201", 12, 14]].

Notes

• pricing.py, money.py, reservations.py, ledger.py, guests.py, season.py and validation.py are known-good.
• 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 the later features.
• Parts 1-3 are a strong result. Part 4 is a stretch.