organize

Multi-user slot coordination: spread a crowd across candidate slots.

Coordinates per-user notification scheduling so a crowd capturing one target spreads across the candidate slots instead of all piling onto the same one.

The system is three layers, from the bottom up:

1. Scope is where coordination state lives between requests: a namespaced key/value store of JSON-native values. The scheduling library only sees this protocol — the server backs it durably, tests use the in-memory DictScope — and every consumer stamps its scope with ensure_format so state written in an outdated shape is discarded and rebuilt rather than misread.

2. Reservation books consume a Scope and hand out slots as leases: distinct per user, stable while held (a user polling repeatedly gets the same answer), released when fulfilled, and expiring on their own when abandoned — so no user can pin a slot forever.

3. Slot selection happens elsewhere and beforehand: void-and-cluster picks which times or places are worth offering, and the book only allocates that ready-made list among the users who ask.

The two books differ only in what a slot is and what fulfills it:

• Reservations hands out times. Fulfilled by the clock or a capture: a reservation lapses grace past its time, or once any capture lands within grace of it (that moment's conditions were just sampled).
• CoverageReservations hands out places from a batch. Fulfilled by proximity: a capture within threshold of a place retires it for everyone (the spot is covered); a lease that lapses without one returns the place to the batch so someone else is sent there.

import capturegraph.scheduling as cgsh

book = cgsh.Reservations(state.scope("schedule"), grace=timedelta(minutes=30))
slot = book.reserve(user_id, among=candidate_slots, captured=last_capture)