Lending Library: Hold Shelf, Transit and Frozen Holds

Lending Library: Hold Shelf, Transit and Frozen Holds

You've joined the circulation team of a city library system with four branches. The checkout, return, renewal and fine code has been running for years. The next release adds holds: a member queues for a *title* (not a particular copy), and when a copy comes free it is set aside on the hold shelf at the member's chosen pickup branch. Nobody has built the shelf yet, so today a returned book that someone is waiting for just goes back on the open shelf. All money is integer cents; all times are whole days (ts is a day number, and it never decreases from one operation to the next).

Codebase

How your code is run

run(operations: list[list]) -> list executes the operations in order against a fresh library and returns one result per operation. Every operation is [name, ts, ...args]. Errors are returned as "error: <code>" strings, never raised. Wrong argument count or a non-integer ts gives "error: invalid arguments"; an unknown name gives "error: unknown operation". Ids (members, copies, titles) are case-sensitive strings. Wherever ids are ordered, it is plain string comparison. Branches are EAST, MAIN, NORTH, WEST.

The loan, fine and renewal rules already work; config.py, loans.py and fines.py are the reference. In short: the due day is the checkout day plus the kind's loan days; a renewal restarts the period from the renewal day (renew_day + loan_days), is refused after the due day, and is limited to MAX_RENEWALS; a fine is 0 if the item comes back within GRACE_DAYS of the due day, otherwise *every* late day is charged at the kind's daily rate, scaled by the member's tier percentage (adult 100%, senior 50%, youth 0%, rounded half up to a cent), then capped per item. A member owing FINE_BLOCK_CENTS or more cannot check out, place holds or pick up. Hold ids are h-1, h-2, ... in the order holds are successfully placed; that number is the hold's queue order on its title. A member may have at most one open hold per title (open = not yet collected, expired or cancelled). hold_status reports status (queued, suspended, in_transit, ready, collected, expired, cancelled), copy (the copy id while the hold is in_transit or ready, otherwise null), pickup, and last_day (the last day a ready hold can be picked up, otherwise null).

The branch-migration importer also has four bulk operations (they behave exactly like the equivalent run of single operations at the same ts; on a failure the first error is returned and the earlier ones stay applied). Ids are prefix + a zero-padded index: f"{prefix}{i:04d}", for i = 0 .. count-1. Each returns count.

Worked example (works today)

[["join", 0, "ana", "adult"],
 ["add_copy", 0, "c-001", "t-dune", "MAIN", "book"],
 ["checkout", 1, "ana", "c-001"],
 ["renew", 10, "ana", "c-001"],
 ["return", 40, "c-001", "EAST"],
 ["fines", 40, "ana"]]

returns [true, true, 22, 31, 225, 225] (due 31 after the renewal; nine days late at 25 cents).

Part 1 — Fill holds from returns, expire them lazily, protect waiting holds (LIB-212)

Goal: make holds actually work for copies that are already at the member's pickup branch.

Rules

1. A copy *becomes available* when it is returned, added with add_copy, released by a cancelled or expired hold, or (Part 3) when a hold resumes. Whenever a title has a waiting hold and an available copy, the lowest hold number among its waiting holds gets the copy, one pair at a time until either runs out. This also applies when a member places a hold on a title that already has an available copy: the hold is filled at once.
2. Filling sets the copy aside: the hold becomes ready, the copy is on the hold shelf at the pickup branch (in Part 1 it is simply there from the first moment; copies are never in transit), and the hold can be picked up on any day from the fill day through last_day = fill_day + HOLD_SHELF_DAYS - 1. Several available copies: the lowest copy id.
3. pickup turns a ready hold into a loan on that copy (same due-day rule as checkout, same fines block and loan limit checks via check_may_borrow; a failed pickup leaves the hold ready). A hold in any other status gives hold not ready.
4. Time is lazy. Before each operation runs, every event whose day is <= ts is handled, in ascending event day, and same-day events in ascending hold number. The only event in Part 1 is a hold lapsing: a ready hold whose last_day has passed becomes expired on day last_day + 1, its copy becomes available *as of that day*, and it is offered to the next waiting hold, which becomes ready as of that day (not as of the ts that happened to trigger the processing). Chains of lapses between two operations must all play out, each with its own dates.
5. cancel_hold works on any open hold. Cancelling a ready hold makes its copy available on the cancelling day. A collected, expired or cancelled hold gives hold closed. A hold that was cancelled or collected never lapses afterwards.
6. renew is additionally refused with title has holds when the loaned copy's title has any hold waiting for a copy (queued; a hold that already has a copy set aside does not count). Check order: not on loan, overdue, renewal limit, then title has holds.

Example (after the three joins of ana, ben, cy and the add_copy of c-001, all at MAIN)

[["checkout", 1, "ana", "c-001"],
 ["place_hold", 2, "ben", "t-dune", "MAIN"],
 ["place_hold", 3, "cy", "t-dune", "MAIN"],
 ["renew", 4, "ana", "c-001"],
 ["return", 5, "c-001", "MAIN"],
 ["hold_status", 5, "h-1"],
 ["pickup", 12, "ben", "h-1"],
 ["hold_status", 12, "h-1"],
 ["hold_status", 12, "h-2"],
 ["pickup", 14, "cy", "h-2"]]

returns [22, "h-1", "h-2", "error: title has holds", 0, {"status": "ready", "copy": "c-001", "pickup": "MAIN", "last_day": 11}, "error: hold not ready", {"status": "expired", "copy": null, "pickup": "MAIN", "last_day": null}, {"status": "ready", "copy": "c-001", "pickup": "MAIN", "last_day": 18}, 35]. Ben's hold lapsed on day 12, so Cy's became ready on day 12 (not 14).

Part 2 — Copies travel between branches (LIB-231)

Change of requirements. Logistics now runs a courier van, and a copy is no longer teleported. This replaces the "copies are never in transit" simplification of Part 1.

Rules

1. A copy always has a current branch (where it was added or returned, or where its last hold shelved it). When the first waiting hold takes an available copy, travel time is transit_days(copy.branch, hold.pickup) (see catalog.py and the table in config.py; 0 when they are the same branch).
2. With travel time 0 nothing changes from Part 1. Otherwise the hold becomes in_transit (copy shows the copy id, last_day is null) and the copy is not available. On day fill_day + travel it arrives: the copy's branch becomes the pickup branch, the hold becomes ready as of the arrival day, and last_day = arrival_day + HOLD_SHELF_DAYS - 1. The shelf clock starts at arrival, not at fill. An in_transit hold cannot be picked up (hold not ready).
3. When several copies are available for the hold at the head of the queue, choose the one with the smallest travel time to the pickup branch, ties by lowest copy id (this replaces "lowest copy id").
4. Cancelling an in_transit hold does not stop the van: the copy arrives at the hold's pickup branch on the arrival day, becomes available there as of that day, and is offered to the next waiting hold (possibly sending it on again from that branch).
5. Event order within one day is now: arrivals before lapses, then by hold number. An arrival or lapse handled at event day E fills holds as of E.
6. Everything in Part 1 still holds; the Part 1 example is unchanged because all branches there match.

Example (after join of ana and ben, add_copy c-001 t-dune MAIN book)

[["checkout", 1, "ana", "c-001"],
 ["place_hold", 2, "ben", "t-dune", "NORTH"],
 ["return", 5, "c-001", "EAST"],
 ["hold_status", 5, "h-1"],
 ["pickup", 7, "ben", "h-1"],
 ["hold_status", 8, "h-1"],
 ["hold_status", 15, "h-1"]]

returns [22, "h-1", 0, {"status": "in_transit", "copy": "c-001", "pickup": "NORTH", "last_day": null}, "error: hold not ready", {"status": "ready", "copy": "c-001", "pickup": "NORTH", "last_day": 14}, {"status": "expired", "copy": null, "pickup": "NORTH", "last_day": null}] (EAST to NORTH is 3 days, so the copy arrives on day 8).

Part 3 — "Freeze my hold" and long queues (LIB-260)

Goal: members going on vacation can freeze a hold without losing their place in line.

Rules

1. Only queued or suspended holds are *waiting* (otherwise hold not waiting). until is null (frozen until resumed by hand) or an integer greater than ts (else invalid date). Suspending a suspended hold just replaces its until.
2. A suspended hold keeps its hold number, is never offered a copy, and is skipped when filling: the next queued hold on the title gets the copy. Resuming (by hand, or automatically at the start of day until: the hold is queued for any operation at ts >= until) puts it back in its original place in line, and if a copy is available it is filled right away, as of the resume day.
3. A pending automatic resume that no longer applies (the hold was resumed by hand, suspended again with a different until, cancelled) must do nothing.
4. Event order within one day is now: resumes, then arrivals, then lapses, then by hold number. So a hold resuming on the day another hold lapses is back in line before the freed copy is offered.
5. Renewals change: suspended holds no longer block renewals; only queued holds do.
6. hold_position is 1 + the number of queued holds on the same title with a smaller hold number (suspended holds ahead do not count; for a suspended hold this is where it would sit if resumed).
7. Bulk operations (bulk_join, bulk_add_copies, bulk_hold, bulk_suspend, see bulk.py) keep working and now include real suspensions. Hidden tests use them to build queues with tens of thousands of holds, thousands of which are frozen, and then trigger thousands of fills and lapses in one run. The whole suite has a few seconds; rescanning a queue for every fill will not finish.

Example (after joining ana, ben, cy, dee, and add_copy c-001 t-dune MAIN book)

[["checkout", 1, "ana", "c-001"],
 ["place_hold", 2, "ben", "t-dune", "MAIN"],
 ["place_hold", 2, "cy", "t-dune", "MAIN"],
 ["place_hold", 2, "dee", "t-dune", "MAIN"],
 ["suspend_hold", 3, "ben", "h-1", 10],
 ["hold_position", 3, "h-1"],
 ["hold_position", 3, "h-2"],
 ["hold_position", 3, "h-3"],
 ["return", 5, "c-001", "MAIN"],
 ["hold_position", 10, "h-1"],
 ["hold_status", 12, "h-1"]]

returns [22, "h-1", "h-2", "h-3", true, 1, 1, 2, 0, 1, {"status": "ready", "copy": "c-001", "pickup": "MAIN", "last_day": 18}]. The copy went to Cy (Ben was frozen). Ben resumed on day 10 in front of Dee. When Cy's hold lapsed on day 12 the copy went to Ben, not Dee.

Notes

• fines.py, config.py and catalog.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.
• Parts 1-2 are the core result. Part 3 is the stretch.