Contention: Waiting Room and Bookings

Two tools for a resource you cannot have right now: the waiting room queues you until the current holder is done; a booking reserves a future time window. They behave differently enough that picking the wrong one is the main lease mistake.

Joining the waiting room

By default a contended acquire fails with 409 resource_unavailable. Opt into queueing instead:

snug lease acquire baubzZduHFaJUnXbcPSh --duration 10m \
  --on-conflict join-waiting-room --priority 5

{
  "mode": "exclusive",
  "resource_id": "baubzZduHFaJUnXbcPSh",
  "status": "pending",
  "waiting_position": 1
}

waiting_position is 1-indexed. Ordering is priority first (higher wins), then join time: a priority-5 caller who joined second was placed ahead of a default-priority (0) caller who joined first, and was the one admitted on release.

Admission does not grant the lease

When the holder releases (or the reclamation worker sweeps an expired lease), the next fresh waiter is popped and named in the release response:

{
  "admitted_waiter": "docs4-third",
  "lease_id": "lse_ZBQyTVMpthrX",
  "message": "Lease lse_ZBQyTVMpthrX released",
  "resource_id": "baubzZduHFaJUnXbcPSh"
}

Admission removes the waiter from the queue - it does not create a lease for them. The waiting client's job is to keep re-polling the same acquire call until it comes back active:

snug lease acquire baubzZduHFaJUnXbcPSh --duration 10m --on-conflict join-waiting-room

Re-joining is how a waiter stays alive: the original join time is preserved (position is kept), while last_seen refreshes on every call. An entry not refreshed within LEASE_WAITER_TTL_SECONDS (300 by default) is pruned as abandoned, so poll more often than that. Note there is no reservation between admission and the next poll - a third party that acquires in that gap wins the resource.

Listing the queue is admin-only (403 insufficient_permissions otherwise):

snug lease waiting-room baubzZduHFaJUnXbcPSh   # requires a platform admin token

{
  "count": 1,
  "resource_id": "baubzZduHFaJUnXbcPSh",
  "waiters": [
    {
      "holder_id": "docs4-other",
      "joined_at": "2026-08-28T06:29:48.014676Z",
      "last_seen": "2026-08-28T06:29:48.014676Z",
      "mode": "exclusive",
      "priority": 0.0
    }
  ]
}

Bookings

A booking reserves a future window on the resource:

snug lease bookings create baubzZduHFaJUnXbcPSh \
  --starts-at 2026-08-28T08:00:00Z --duration 1h
snug lease bookings list baubzZduHFaJUnXbcPSh
snug lease bookings cancel baubzZduHFaJUnXbcPSh --booking book_sEvjCAxUbZcR

Overlapping windows are rejected - a second booking crossing an existing scheduled one fails 409 booking_conflict, naming the conflicting booking id. Cancellation is restricted to the booking holder or an admin (403 insufficient_permissions otherwise).

Two things a booking does not do today:

• It does not auto-acquire at start time. There is no fulfillment worker; the fulfilled status exists in the model but nothing sets it. The booking holder must call acquire themselves when the window opens.
• It does not block acquisition during its window. Overlap detection applies to other bookings, not to acquire - a walk-up caller can lease the resource across your booked window.

Treat bookings as a coordination calendar with conflict detection, not an enforced reservation.