Auction House: Proxy Bidding, Soft Close and Settlement

Auction House: Proxy Bidding, Soft Close and Settlement

You've joined the marketplace team at Gavel & Co., which runs online auctions for collectibles and charity galas. The auction engine is a small in-memory service. This week support escalated an incident (AUC-412: "the price is wrong"), and the roadmap has three pieces of work queued behind it. All money is integer cents, all times are integer seconds.

Codebase

catalog.py, money.py and errors.py are known-good. config.py is the single source of truth for every table and constant quoted below: if this README and the code disagree about a *number*, the README is the specification and config.py is where it lives.

How your code is run

run(operations: list[list]) -> list executes the operations in order against a fresh auction house and returns one result per operation. Every operation is [name, ts, ...args]; ts is an integer and never decreases from one operation to the next. Errors are returned as "error: <code>" strings, never raised.

• An unknown name returns "error: unknown operation". A wrong number of arguments, a ts that is not an integer (true/false are not integers), or an operation that is not a list returns "error: invalid arguments". So does a bidder, or the lot id given to list, that is not a non-empty string; these shape errors are reported before any error in the "Errors" columns below. Looking up any other lot id that does not exist is lot not found.
• An amount is a genuine integer (true and 12.5 are not amounts).
• Lot ids and bidder names are case-sensitive.

Operations (Part 1)

• reserve and buy_now are an integer or null (none). list is valid when start_price > 0, reserve is null or >= start_price, buy_now is null or >= start_price and >= reserve (any violation is invalid price), and ends_at > ts (else invalid end).
• Lot view: [status, leader, price, reserve_met, ends_at]. status is "open", "sold" or "passed". While open, leader is the bidder currently winning (or null) and price is the *visible price* defined below (or null). A sold lot shows its buyer and its sale price with reserve_met true. A passed lot shows ["passed", null, null, false, ends_at].

The proxy-bidding rules

A bidder submits a maximum. A bidder's *standing bid* on a lot is their most recent active bid; a bid is accepted only if it is a raise, so a bidder's maximum only ever goes up. Every accepted bid gets the next value of a sequence number seq (1, 2, 3, ... across the whole house, never reused). A lot's state is a pure function of its standing bids:

1. Leader: the highest maximum. Equal maximums go to the lower seq (the earlier bid). A raise is a new bid and gets a new, higher seq.
2. Runner-up: the standing bid ranked second by the same ordering (so against a tie, the loser of the tie).
3. Base price: the start price when only one bidder has a standing bid. Otherwise min(leader_max, runner_up_max + increment_for(runner_up_max)), where the increment depends on the band of the price being beaten, i.e. the runner-up's maximum:

Band lower bounds are inclusive: a price of exactly $25.00(2,500)isinthe$1.00 band.

1. Reserve met: leader_max >= reserve. A lot with no reserve is met as soon as it has a bid.
2. Working price: the base price; if the reserve is met and the lot has a reserve, at least the reserve (max(base, reserve)). Because of this "reserve lift", a leader who raises their own maximum from under the reserve to at or over it moves the price to the reserve.
3. Visible price: the working price if the reserve is met, otherwise null. Bidders never see a price below the reserve. A lot with no bids has leader null, price null, reserve_met false.

A leader raising their own maximum changes the price only if the base price was capped by their old maximum (the runner-up was close) or the reserve lift now applies; otherwise the price is unchanged.

Accepting a bid. After the error checks in the table above: not a raise if the bidder already has a standing bid with max <= that bid's maximum. bid too low if max < start_price, or if the bidder is not the current leader, the lot has a leader, and max < working_price + increment_for(working_price). (The leader's own raise has no such floor.) A tie with the leader is therefore possible only when the challenger's maximum clears that floor.

Closing is lazy. There is no timer. Before it handles every operation, the dispatcher closes every open lot whose ends_at <= ts: sold to the leader at the working price if the reserve is met, otherwise passed. An operation at exactly ends_at therefore already sees a closed lot (bid -> lot closed).

Worked example

[["list", 0, "vase", 1000, null, null, 100000],
 ["bid", 1, "vase", "ana", 9000],
 ["bid", 2, "vase", "ben", 4000],
 ["bid", 3, "vase", "ana", 20000]]

returns

[true, ["open","ana",1000,true,100000], ["open","ana",4100,true,100000], ["open","ana",4100,true,100000]]

Ben's $40.00maximumsitsinthe$1.00 band, so the price is $41.00;Anaraisingherownmaximumto$200.00 does not move it. And with a $50.00 reserve:

[["list", 0, "coin", 1000, 5000, null, 100000], ["bid", 1, "coin", "ana", 3000], ["bid", 2, "coin", "ana", 8000]]

returns [true, ["open","ana",null,false,100000], ["open","ana",5000,true,100000]].

Part 1 - Incident AUC-412: the price is wrong

Goal: make list, bid and lot follow every rule above. Support has collected these reports:

1. "A $99.00bidderwasoutbidbya$300.00 maximum and the price showed $\mathrm{104.00.}Theincrementat$99.00 is $1.00,soitshouldbe$100.00." / "A bid of exactly $25.00 gets the wrong increment."
2. "I raised my own maximum and the displayed price shot up to my maximum." (Sellers were furious: they think the price is higher than anyone has paid.)
3. "Two of us bid the same maximum and the later bidder won."
4. "The price of a charity lot with a $500reservewasvisibleat$12 before the reserve was met," and "my $500 maximum met the reserve but the lot never showed a price."
5. "I bid exactly the amount the site told me was enough and it said *bid too low*" (after the reserve lift, the minimum next bid must be measured from the lifted price).

tests/test_pricing.py shows how to drive the engine; two of its tests currently fail. Existing callers rely on the wire format above staying exactly as it is.

Part 2 - Retractions and buy-it-now (AUC-431)

Two new operations:

Retraction rules

1. retract withdraws the bidder's most recent active bid on the lot. If the bidder had an earlier active bid on that lot, it becomes their standing bid again with its original seq. The lot's leader, price and reserve status are then recomputed from the standing bids that remain; the price can go down, and the leader can change.
2. retraction window closed when ends_at - ts < 3600 (exactly 3,600 s left is still allowed).
3. A bidder may retract at most 2 bids per lot. Once they have used both, further attempts return retraction limit (a refused attempt never counts).
4. After a retraction the bidder can bid again on the lot; it is an ordinary bid.
5. Retracting does not change ends_at and cannot reopen a lot.

Buy-it-now rules

1. buy_now sells the lot immediately to bidder at the lot's buy_now price; it returns ["sold", bidder, buy_now, true, ends_at]. Any standing bids are ignored.
2. It returns buy now unavailable if the lot has no buy_now price, or if the reserve is currently met (for a lot with no reserve, that means it currently has any standing bid). A leader who is still below the reserve does not block it.
3. After a sale the lot is sold: later bid, retract and buy_now calls return lot closed.

Example (lot vase, no reserve, ends at 100000)

[["bid",1,"vase","ana",9000], ["bid",2,"vase","ben",4000], ["bid",3,"vase","cat",6000],
 ["retract",4,"vase","cat"], ["retract",5,"vase","ben"], ["retract",6,"vase","ben"]]

returns [["open","ana",1000,true,100000], ["open","ana",4100,true,100000], ["open","ana",6100,true,100000], ["open","ana",4100,true,100000], ["open","ana",1000,true,100000], "error: no active bid"].

Part 3 - Soft close and settlement (AUC-455)

Soft close (anti-sniping). An accepted bid placed at time ts on an open lot with ends_at - ts < 120 (strictly fewer than 120 seconds left) moves the end to ts + 120, provided the lot has been extended fewer than 5 times so far; that counts as one extension. A bid with exactly 120 seconds left does not extend. Rejected bids never extend; retractions and buy-it-now never extend. The lot view returns the new ends_at, and the lazy closing rule uses the current end time, so an extended lot stays open past its original end.

Requirement change: buy-it-now becomes permanent-off. Sellers were using retractions to reopen their own buy-it-now. From now on, once the reserve has been met by an accepted bid (for a lot without a reserve: once it has received its first accepted bid), buy_now on that lot returns buy now unavailable for the rest of the auction, even if retractions later bring the lot back under its reserve. This replaces rule 2 of the buy-it-now rules in Part 2 for that case; everything else in Part 2 is unchanged.

Settlement. ["settle", ts, bidder] produces one invoice for all the lots bidder has won that have not been invoiced yet (sold lots, including buy-it-now sales; passed lots are never invoiced) and marks them invoiced. Errors: invalid arguments (bidder not a non-empty string), nothing to settle (nothing uninvoiced, which does not use up an invoice number). Because of lazy closing, settle first closes every lot that is due at its ts.

The invoice is {"invoice": "INV-0001", "buyer": ..., "lines": [{"lot", "hammer", "premium"}, ...], "shipping": ..., "total": ...}:

• Invoice numbers are INV- plus a 4-digit zero-padded counter shared by all buyers, in the order the settle calls succeed.
• Lines are in the order the lots closed: by ends_at at the moment of closing, ties by listing order; a buy-it-now sale closes at the moment of the purchase, after any lots that were already due.
• hammer is the lot's sale price. Premium is computed per line (never on the invoice total) and is marginal: 22.50% (2,250 basis points) of the part of the hammer price up to $1,000.00 (100,000) plus 15.50% (1,550 bp) of the part above it, rounded once per line, to the nearest cent with exact halves rounding up: div_half_up(part1 * 2250 + part2 * 1550, 10000). Examples: hammer 1060 -> 238.5 -> 239; hammer 20 -> 4.5 -> 5; hammer 123456 -> 26,135.68 -> 26136. Python's round() is banker's rounding and is wrong here.
• shipping is a flat 1,250 per invoice, 0 when the sum of the invoice's hammer prices is at least 100,000 (inclusive).
• total is the sum of hammers, premiums and shipping.

Example

[["list",0,"vase",1000,null,null,1000],
 ["bid",800,"vase","ana",2000], ["bid",900,"vase","ben",2500], ["bid",1019,"vase","ana",3000],
 ["lot",1138,"vase"], ["lot",1139,"vase"]]

returns [true, ["open","ana",1000,true,1000], ["open","ben",2050,true,1020], ["open","ana",2600,true,1139], ["open","ana",2600,true,1139], ["sold","ana",2600,true,1139]]. Ana's bid at 800 had 200 s left (no extension); Ben's at 900 had 100 s left (end -> 1020); Ana's at 1019 had 1 s left (end -> 1139).

Part 4 - Bidder dashboards and bulk tools at scale (stretch)

The mobile team is shipping a "My lots" screen, and the catalog team imports whole collections at once.

• my_lots: leading covers the bidder's open lots where they are the leader and the reserve is met: count of them, exposure = the sum of their current working prices, and lots = the ids of the first limit of them in plain ascending string order. won covers sold lots whose buyer is the bidder (buy-it-now sales included, invoiced or not): count, spent = sum of sale prices, and lots as above. limit must be an integer >= 1; the bidder must be a non-empty string. An unknown bidder returns zeros and empty lists.
• bulk_list lists count >= 1 lots with ids f"{prefix}-{i:04d}" for i = 0 .. count-1 (so z-0000, z-0001, ...; later digits just get longer past 9999). All lots share start_price and reserve (an integer or null) and have no buy-it-now price; lot i ends at ts + duration + (i % stagger) (just ts + duration when stagger = 0). duration >= 1, stagger >= 0. It is atomic: if any id already exists nothing is listed.
• bid_run places one bid per lot f"{prefix}-{i:04d}", i = 0 .. count-1, for bidder, with maximum first_max + i * step; bid i happens at time ts + i * gap (gap >= 0). The clock advances with the run: before each bid, lots due at that bid's time are closed exactly as for a normal operation, and the bid obeys every normal rule (soft close included). A bid that would return an error is counted in rejected and does nothing else. The next operation's ts is never earlier than the last bid's time.
• bid_war has bidders f"{prefix}{i}" (i = 0 .. count-1) bid first_max + i * step on one lot, in that order, all at ts; the lot may be missing (then every bid is rejected). Same counting.
• Bulk argument checks: ids/prefixes are non-empty strings, count >= 1, all other numbers are genuine integers.

Example

[["bulk_list",0,"z",3,1000,null,5000,0], ["bid_run",1,"ana","z",3,2000,500,0],
 ["bid_war",2,"z-0001","q",2,3000,1000], ["my_lots",3,"ana",5], ["lot",3,"z-0001"]]

returns [3, [3,0], [2,0], {"leading":{"count":2,"exposure":2000,"lots":["z-0000","z-0002"]}, "won":{"count":0,"spent":0,"lots":[]}}, ["open","q1",3100,true,5000]].

Scale. Hidden tests list tens of thousands of lots, place tens of thousands of bids (one hot lot has thousands of bidders, retractions included) and call my_lots repeatedly while time moves through the end times. The whole suite has a few seconds. A solution that rescans the catalog per bid or per query, or re-sorts every bid of a hot lot on each new bid, will time out.

Notes

• You may use the AI assistant freely; you are expected to verify what it produces.
• Later Parts must not break earlier ones (except where a Part says it replaces a rule); hidden tests re-check earlier behaviour after the later features exist.
• Everything observable is specified above or visible in the code; when this document says "as for a normal operation", read api.py and closing.py to see what that means.
• Parts 1-3 is a strong result. Part 4 is a stretch.