Skip to content

[MBA-3829] Waitlist auto-offer: offer a freed seat to the next waitlisted candidate - #99

Merged
devin-ai-integration[bot] merged 4 commits into
estate/legacy-baselinefrom
devin/mba-3829-waitlist-auto-offer-v2
Nov 11, 2026
Merged

devin-ai-integration[bot] merged 4 commits into
estate/legacy-baselinefrom
devin/mba-3829-waitlist-auto-offer-v2

Conversation

@devin-ai-integration

@devin-ai-integration devin-ai-integration Bot commented Nov 11, 2026 •

Copy link
Copy Markdown

Summary

Implements MBA-3829: a seat freed in an OPEN session is offered automatically to the next eligible waitlisted candidate. This is a deliberate change from legacy, where usp_CancelBooking promotes nobody (HB-06, MR-12, ADR 0002 ODD-09). The new behaviour is recorded in ADR 0005 (docs/adr/0005-waitlist-auto-offer.md; renumbered because M5 #97 took 0004). Scheduling-service has been the single writer since M4, so legacy readers get the result through the existing outbox relay. There is also a minimal routing-gateway change so the new offer write paths go through the existing modern write guard (see below).

seat frees (cancel BOOKED | reschedule out | capacity up | offer declined/expired/withdrawn)
  -> same tx, same exam_session UPDLOCK
  -> WaitlistOfferPolicy.offerFreedSeats(session)
       WaitlistOfferRules.select(status, seats, unofferedWaitlist)   // OPEN only, position order,
                                                                     // ET25/ET50 skipped (kept in place) w/o free acc seat
       insert seat_offer(PENDING, expires_at = now + scheduling.waitlist.offer-ttl [PT24H])
       outbox SeatOffered
POST /api/v2/offers/{id}/accept   -> booking BOOKED, waitlist entry removed, later positions -1, outbox SeatOfferAccepted
POST /api/v2/offers/{id}/decline  -> booking CANCELLED, positions shift, outbox SeatOfferDeclined, offer next entry
WaitlistOfferExpiryJob (expiry-poll PT1M) -> same as decline with SeatOfferExpired
cancel/reschedule of an offered booking, capacity decrease -> SeatOfferWithdrawn, seat passed on / released
  • Seat hold: SessionCapacity has new heldSeats / accommodationHeld fields (pending offers). seatsAvailable = capacity - occupied - held, so a held seat cannot be booked (new bookings are waitlisted) and seatsAvailable stays 0. The hold exists only in Scheduling. In legacy the offered booking stays WAITLISTED and SeatsAvailable stays Capacity - (BOOKED+ATTENDED) (the formula db/checks/seat-drift.sql checks), so reconciliation remains at 0 throughout an offer cycle. The relay needed no code change because every event carries the full resulting state.
  • No double offers: the unique filtered index uq_seat_offer_pending_booking (booking_id) WHERE status='PENDING' plus the existing session lock. Concurrent ITs cover cancel+cancel and cancel+capacity-increase.
  • Flyway V3__waitlist_offers.sql: seat_offer table, plus ck_outbox_event_type extended with SeatOffered, SeatOfferAccepted, SeatOfferDeclined, SeatOfferExpired and SeatOfferWithdrawn.
  • API (spec regenerated, baseline untouched): GET /api/v2/offers/{offerId}, POST .../accept and POST .../decline (tag Offers, 404/409 as a separate OfferError schema so the published ApiError enum does not change). Additive fields: SessionDto.heldSeats, plus nullable offerId, offerStatus and offerExpiresAt on BookingDto and WaitlistEntryDto.
  • UI: My bookings shows a "seat is being held" panel with Accept seat / Decline. The [REDACTED SECRET] waitlist table has an Offer column, and the session page shows the count of offered seats. The cancel modal text no longer says nobody is promoted.
  • Unchanged: cancelling a waitlisted booking that has no offer still deletes its entry without renumbering (ODD-09). Only accept, decline and expiry renumber, as the ticket requires.
  • Gateway write guard (services/routing-gateway, write-guard code only): ApiRoutes.matchV2Write now matches POST /api/v2/offers/{id}/accept|decline as V2Op.OFFER. ModernApiWriteGuard resolves offer -> session -> centre via the new Lookup.Kind.OFFER_ID, which calls GET /api/v2/internal/routing/resolve?offerId= (new parameter in scheduling-service InternalController). It refuses with 403 CENTER_NOT_MODERN when that centre is not on routing.modern-centers or the lookup fails (fail closed), the same as cancel/reschedule.
  • Config: scheduling.waitlist.offer-ttl (PT24H), expiry-enabled (true, false in tests) and expiry-poll (PT1M). The runbook has a new "Waitlist offers" scenario.

Review focus

  • SchedulingService.cancel / reschedule / changeCapacity hooks and closeOffer: each one emits the original event and then the offer event in the same transaction.
  • Accept/decline have no candidate authentication, which matches the existing /api/v2 candidate writes (cancel, reschedule). This is by design for now: the slice has no candidate login (MR-16), see ADR 0005 Consequences.

Tests

The re-run results are on head 6bf1778, which includes the merge of estate/legacy-baseline @ 192a423 (M5 #97); that merge was clean. The original offer work was verified on 6562610.

Command (in services/scheduling-service) Result
./mvnw -B verify -Dskip.frontend=true -Dtest=NONE -Dsurefire.failIfNoSpecifiedTests=false -Dit.test=OpenApiSpecIT,WaitlistOfferIT -Dopenapi.write=true (spec regen; the SPA is skipped because its contract check needs the new spec first) BUILD SUCCESS, api/openapi.yaml regenerated, baseline untouched
./mvnw -B verify (clean run with the SPA build and contract typecheck), on 6bf1778 65 unit / 54 IT, 0 failures, BUILD SUCCESS
services/routing-gateway: ./mvnw -B verify, on the merged head 30 tests, 0 failures, BUILD SUCCESS (includes the new GatewayIntegrationTest.offerAcceptAndDeclineAreGuardedByTheOffersCentre: allowed centre 200, refused centre 403, unresolvable offer 403; plus the RouteDeciderTest offer matcher)

New tests:

  • WaitlistOfferRulesTest (8): position order, held seats, ET skip (used and held accommodation seat), only OPEN sessions, held seats reduce availability.
  • WaitlistOfferIT (15, Testcontainers SQL Server): cancel creates a PENDING offer with 24h TTL and holds the seat (new booking gets WAITLISTED, seatsAvailable 0, heldSeats 1); accept gives BOOKED, positions 2-3 become 1-2, SeatOfferAccepted payload includes the shifted bookings, second accept gets 409 OFFER_NOT_PENDING, unknown id gets 404 OFFER_NOT_FOUND; decline offers to the next entry; expiry offers to the next entry and the last expiry releases the seat for ordinary booking; ET25/ET50 skipped and kept in place; capacity increase makes 2 offers in order and a decrease withdraws the newest; reschedule-out; cancelling an offered booking passes the seat on; CLOSED session makes no offer; concurrent cancel+cancel and cancel+capacity-up (each repeated 3x) give exactly 2 offers and no duplicates.
  • RelayIT#waitlistOfferCycleReachesLegacyAndReconcilesToZero (real AssessmentDelivery, relay as ad_sched_relay): offer, accept, decline, expire. After each step legacy dbo.Booking/dbo.Waitlist match, reconcile reports 0 mismatches, seat-drift returns 0 rows, and every event replayed twice is a no-op.
  • SchedulingApiIT updated for the intended change: Flyway history is 3, and raising capacity now offers seats to the waitlist instead of promoting nobody (ODD-09).

Live gateway check through :8000 (merged head 6bf1778, live estate + relay)

Allowed centre (routing.modern-centers=*). Cancelling a booking in full DEN01 session 156 creates offer 4:

$ curl -i -X POST localhost:8000/api/v2/offers/4/accept
HTTP/1.1 200 OK
X-Route: modern
{"offer":{"offerId":4,"sessionId":156,"bookingId":1634,...,"status":"ACCEPTED",...},"booking":{...,"centerCode":"DEN01",...,"status":"BOOKED",...

Refused centre. Cancelling a booking in AKL01 session 325 creates offer 5; then routing.modern-centers is temporarily narrowed to BOS01:

$ curl -i -X POST localhost:8000/api/v2/offers/5/accept      (same for /decline)
HTTP/1.1 403 Forbidden
X-Route: modern
{"error":"CENTER_NOT_MODERN","message":"Centre AKL01 is not on routing.modern-centers; its seat inventory is still owned by legacy"}
$ curl -i -X POST localhost:8000/api/v2/offers/99999/accept  (lookup fails -> fail closed)
HTTP/1.1 403 Forbidden
{"error":"CENTER_NOT_MODERN","message":"The centre for this write could not be resolved; refused until it can be checked against routing.modern-centers"}
$ curl -s localhost:8090/api/v2/offers/5        -> "status":"PENDING" (untouched)

After restoring routing.modern-centers=*, POST /api/v2/offers/5/accept returns 200 ACCEPTED. M5's redirect still works: GET :8000/Booking/MyBookings returns 302 to /app/my-bookings. Reconciliation afterwards: 462 sessions and 3,587 bookings compared, 0 session mismatches, 0 booking mismatches, 0 seat-drift rows.

Browser verification (testing agent, live estate)

Setup: scripts/run-legacy.sh and scripts/run-scheduling-service.sh (relay on), seed session 153 (full, waitlist 1-3), UI at :8090/app.

  1. NW00000001 cancels booking #1602. Position 1 (#1603) gets the offer; seats available stays 0 and heldSeats is 1.
  2. NW00000410 sees the held-seat panel in My bookings and clicks Accept seat. #1603 becomes BOOKED and #1604/#1605 shift to positions 1/2.
  3. Capacity 22 to 23 offers #1604. Decline cancels #1604 and passes the seat to #1605.
  4. Legacy dbo.Booking #1603 is BOOKED and has no dbo.Waitlist row. GET /internal/reconciliation: 462 sessions and 3,587 bookings compared, 0 session mismatches, 0 booking mismatches, 0 seat drift.
Before accept After accept
held seat panel accepted
[REDACTED SECRET]: full session, waitlist 1-3 [REDACTED SECRET]: waitlist renumbered

Admin offer column: held offer
Decline hands the seat on: decline
Reconciliation: reconcile 0/0/0

Recording (animated):
offer flow recording

Not covered in the browser (covered by ITs instead): reschedule-out, expiry, ET skip, concurrency.

Devin Review

  • Security "gateway write guard does not cover offer paths": fixed in this PR (gateway write guard above), and the thread is resolved.
  • Security "no candidate ownership check on accept/decline": by design for now, per the coordinator. It is consistent with cancel/reschedule, and the slice has no candidate login (MR-16). Recorded in ADR 0005, and the thread is resolved.
  • Flag "earlier waitlist gaps survive": by design. Gaps from waitlisted cancels are legacy behaviour (HB-06, ODD-09), and accept/decline/expire shift only the entries after the resolved position, the same as legacy renumbering would.
  • Flag "held ET seat blocks ET waitlisting": consistent with the A5 rule that hasSeatFor is checked before full. A held accommodation seat counts as used, the same as a BOOKED ET25.

Devin-Org: engineering

Link to Devin session: https://devin-gtm.devinenterprise.com/sessions/1887a2fe45044035a28ca9ce9e836c7d
Open in Devin Desktop: https://devin-gtm.devinenterprise.com/desktop/session/1887a2fe45044035a28ca9ce9e836c7d?variant=devin
Requested by: @mbatchelor81


Note

Devin errored when opening this Pull Request as mbatchelor81.
As a fallback, Devin opened this PR as itself.


🟢 Devin Review found nothing to fix · View findings · Follow Devin's work

Devin Review

…sted candidate

WaitlistOfferPolicy offers seats freed by cancel, reschedule-out, capacity increase, decline,
expiry and withdrawal to the lowest-position eligible waitlist entry (ET25/ET50 skipped while
no accommodation seat is free). Pending offers hold the seat. Accept/decline endpoints under
/api/v2/offers, expiry job, seat_offer table (V3), SeatOffered/Accepted/Declined/Expired/Withdrawn
outbox events, UI in My bookings and the admin waitlist. ADR 0004.

Co-Authored-By: Mason <masonbatchelor81@gmail.com>
@devin-ai-integration

Copy link
Copy Markdown
Author

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

  • Disable automatic comment, CI, and merge conflict monitoring

devin-ai-integration[bot]

This comment was marked as resolved.

devin-ai-integration Bot and others added 3 commits November 11, 2026 22:28
…session -> centre)

Co-Authored-By: Mason <masonbatchelor81@gmail.com>
… 0004)

Co-Authored-By: Mason <masonbatchelor81@gmail.com>

@devin-ai-integration devin-ai-integration Bot left a comment •

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

Devin Review

@devin-ai-integration
devin-ai-integration Bot merged commit 8cc35d8 into estate/legacy-baseline Nov 11, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

0 participants