slotlock 0.3.0 → 0.5.0

package/README.md

@@ -10,8 +10,10 @@ TypeScript library.
 Slotlock 0.2.0 can occupy less time than an event was written with, so another booking can take the
 rest: around daylight-saving changes, in any time zone that has them, and at the end of some series.
 The library and `slotlock serve` are both affected (the last case below is in the library's
-iCalendar readers only); the 0.1 releases are older still and unsupported. 0.3.0 fixes all six
-cases; while you run 0.2.0, do not rely on it alone to refuse bookings in them.
+iCalendar readers only); the 0.1 releases are older still and unsupported. 0.3.0, released on
+2026-10-27, fixes all six cases: upgrade (`npm install slotlock@0.3.0` or
+`ghcr.io/pilotaai/slotlock:0.3.0`, then `slotlock migrate`, as the [changelog](CHANGELOG.md) says).
+While you run 0.2.0, do not rely on it alone to refuse bookings in them.
 
 - A recurring event whose first occurrence spans a daylight-saving change gets that occurrence an
   hour short: in spring, an hour of the written time is free to book.
@@ -75,7 +77,12 @@ docker compose exec slotlock slotlock resource add vehicle-42 --timezone Europe/
 | `http://localhost:8080/a2a` | A2A 1.0, same token; card at `/.well-known/agent-card.json` |
 | `http://localhost:8080/v1/…` | [REST](#rest-and-openapi): the tools, and the [application API](#application-api) for admin keys; described at `/openapi.json` |
 | `http://localhost:8080/healthz` | Readiness, including the database |
+| `http://localhost:8080/metrics` | Prometheus metrics, with `Authorization: Bearer <SLOTLOCK_METRICS_TOKEN>`; off without it |
 
+- Metrics count calls by protocol, operation and outcome (`slotlock_calls_total`, with their
+  duration in `slotlock_call_duration_seconds`), confirmations, subscriptions, refusals, maintenance
+  and webhook deliveries. No label names a tenant, key or client. `createSlotlockMetrics` builds
+  them for a server of your own, from its hooks.
 - The server runs as a role that owns nothing and cannot bypass row-level security; a one-off
   `migrate` service applies the schema as the owner.
 - `SLOTLOCK_AVAILABILITY` sets the default bookable hours. A resource can have its own
@@ -108,6 +115,9 @@ docker compose exec slotlock slotlock resource add vehicle-42 --timezone Europe/
   and the rest wait their turn, so a tenant's writes waiting on its own locks leave the others to
   other tenants and key lookups; a server with one tenant can set `tenant_transactions=10`. A
   request whose transaction waits more than 5 seconds for a lock gets 503 `server_busy`.
+  With more than one server, `SLOTLOCK_SHARED_LIMITS=on` shares the tenant budgets (`tenant_*`,
+  `app_*`) through the database, so N servers allow a tenant its rate once, not N times; each server
+  checks its own buckets first, and goes on with them alone if the database cannot be reached.
   `SLOTLOCK_LIMITS` changes the limits; behind a proxy, set `SLOTLOCK_TRUSTED_PROXY_HEADER` to the field it puts the
   client's address in (`CF-Connecting-IP` behind Cloudflare) before the server takes traffic, or
   every client shares the proxy's budget: the server logs a `client_address_field_ignored` warning
@@ -131,6 +141,37 @@ A rule is `rrule`, `startMinutes` and `durationMinutes` here and in `SLOTLOCK_AV
 REST application API spells every field in snake_case, so there it is `rrule`, `start_minutes` and
 `duration_minutes`. `slotlock --help` lists every setting.
 
+#### Booking rules
+
+A resource can also say what a booking on it must satisfy:
+
+```sh
+slotlock rules set '{"minNoticeMinutes":120,"slotStepMinutes":30,"turnaroundMinutes":30,"enforceHours":true}' --resource vehicle-42
+slotlock rules clear --resource vehicle-42
+```
+
+| Rule | A booking made now |
+| --- | --- |
+| `minNoticeMinutes` | starts at least this far ahead |
+| `maxAdvanceDays` | starts at most this far ahead |
+| `slotStepMinutes` | starts on a step from local midnight in the resource's time zone |
+| `turnaroundMinutes` | keeps this long free after it: its trailing buffer, which the database enforces |
+| `enforceHours` | lies inside the resource's bookable hours |
+| `checkInMinutes` | is claimed (`checkInReservation`) this long after its start, or maintenance releases it |
+| `requireCertain` | lies in time every calendar sync recording coverage for the resource has read within a day |
+
+- Holds, reservations, moves and agents' events are checked when they are made, by the database's
+  clock; a refusal names the rule (`booking_rule_violated` with `rule` in the store,
+  `booking_rule_min_notice`, `_max_advance`, `_slot_step`, `_outside_hours` or `_uncertain` to an
+  agent). Under `requireCertain`, a search (the store's and the tools') needs those syncs' coverage
+  too, read within a day, of the slot and its turnaround, so it offers no slot they leave unproven.
+- A series is judged on its first occurrence for notice and advance, and on every occurrence for
+  step and hours. Imported calendar events are not checked: they happened elsewhere.
+- Searches (`slotlock_find_next_available`, `slotlock_find_available_slots`, `findNextAvailableFor`)
+  offer only slots the rules allow, so an offered slot is one the write accepts.
+- The REST application API sets them with `PUT /v1/resources/{resource_id}/booking-rules`, in
+  snake_case; the store with `setResourceBookingRules`.
+
 ### Without Docker
 
 With Node.js 22.12+ and PostgreSQL 16 or newer, run each command as `npx slotlock` after
@@ -211,10 +252,33 @@ resources, so you can give each person API keys without running `slotlock key cr
 3. Run `slotlock serve` and open `<SLOTLOCK_PUBLIC_URL>/dashboard`. With Compose, set the four in
    `.env` (empty, the default, leaves the dashboard off) and run `docker compose up --detach`.
 
+- Its pages: an Overview with the coming week's bookings, events and live holds across every
+  resource (each in its resource's time zone) and the latest changes agents made, named by key;
+  Resources, each with its own page for bookable hours, booking rules, pool, coming bookings and
+  activity; Waitlist, to see who waits and remove an entry; API keys, with the MCP and A2A
+  endpoints; Webhooks, to add, delete and re-enable endpoints and see which are failing; and
+  Settings.
+  Everything on them is read from the tenant's own data. `SLOTLOCK_DASHBOARD_NAME` sets what the
+  dashboard calls the deployment (Slotlock by default).
 - Each person gets a tenant of their own, `github:<user id>`: the keys, resources and bookings in it
   are theirs alone. Keys made with `slotlock key create` act in `SLOTLOCK_TENANT` instead.
-- Sign-in asks GitHub for no scope, uses `state` and PKCE, and keeps nothing from GitHub but the user
-  id and login: the GitHub token is used once and dropped.
+- **For organizations instead of people**, set `SLOTLOCK_DASHBOARD_ORGS` to the GitHub organization
+  ids the dashboard serves (`gh api orgs/<login> --jq .id`). Each is then one tenant,
+  `github-org:<id>`, that its members share: keys, resources and hours. A person signs in to the
+  served organizations they are an active owner or member of (a billing manager is neither),
+  switching between them when there are several; someone in none of them is refused. Every member
+  has the same power: each can create, rotate and revoke the organization's keys, and the key list
+  says who created each one. Membership is read at each sign-in, so a person who leaves keeps
+  the dashboard until their session ends (12 hours at most), and keys they made work until revoked.
+  Removing an id from the list signs its sessions out and stops its keys at once. An organization
+  that restricts OAuth apps must approve the dashboard's app (its Settings, Third-party access), or
+  GitHub hides the membership. `SLOTLOCK_DASHBOARD_USERS` still says who may sign in at all, and a
+  key records the person who created it (`github:<user id>`): erasing that person's own tenant
+  leaves it on keys they made in an organization, which go with the organization's erasure. Only the
+  first 100 memberships GitHub lists, and the first 20 served organizations by login, are read.
+- Sign-in uses `state` and PKCE, and keeps nothing from GitHub but the user id and login (and, with
+  organizations, the served ones the person belongs to): the GitHub token is used once and dropped.
+  It asks for no scope, or `read:org` with organizations.
 - A session is a signed, HttpOnly cookie that lasts 12 hours. The allowlist is checked on every
   request, dashboard and API alike: removing an id and restarting the server signs that person out
   and stops every key in their tenant at once.
@@ -295,6 +359,9 @@ this one and read its session secret, which signs in as any tenant.
   every client together, and the Worker logs a warning: add the ceiling before lowering that
   binding's limit to one client's. The example configuration also removes query strings (a
   callback's OAuth code) from the URLs Workers Logs keep.
+- With organizations, set `SLOTLOCK_DASHBOARD_ORGS` on both the Worker and the server: the server
+  takes an organization's keys only while its own list names it, whether or not it serves the
+  dashboard.
 - The server checks a dashboard tenant against `SLOTLOCK_DASHBOARD_USERS` only when it serves the
   dashboard itself. With the dashboard on Workers, removing a person from the Worker's list signs
   them out of the dashboard; to stop their keys, revoke them or erase the tenant.
@@ -481,6 +548,25 @@ uses the default, `[]` closes it); `setTenantAvailability({ tenantRef, rules })`
 of a tenant. `createSlotlockStoreAgentBackend` answers from a resource's own hours and calls
 `availabilityRules` only for resources without them.
 
+Waitlists: `joinWaitlist({ tenantRef, resourceId | pool, start, end, holderRef, offerTtlMs })`
+waits for a window that is taken now. When it comes free (a cancel, a released or expired hold, a
+no-show), `offerWaitlist` gives it to the entries in the order they joined: the first whose window
+is free, on its resource or the first free member of its pool, gets a hold for its holder, and the
+feed says so (`waitlist.offered`, with `hold_id`). Confirm the hold to book it; let it go and the next
+is offered. Cancels, releases and moves, whether an agent (MCP, A2A) or the application API makes
+them, offer at once; maintenance offers what lapses on its own (an expired hold, a no-show) and
+expires entries whose window has started (`waitlist.expired`). With `checkInMinutes` in a
+resource's booking rules, maintenance releases a booking made since the rule was set that nobody
+checked in that long after its start, or after it was made for a walk-in (`reservation.no_show`),
+and the waitlist is offered its time. Check-in opens an hour before the start; moving a booking to
+another start clears it. Leaving the waitlist lets an offer not yet confirmed go with it.
+
+Calendar tools speak the standards: `emitVAvailability({ rules, timezone, uid })` writes rules as an
+iCalendar VAVAILABILITY (RFC 7953) and `parseVAvailability(text)` reads one back as
+`{ timezone, rules }`; `toJSCalendarEvent(event)` answers a calendar event as a JSCalendar Event
+(RFC 8984). The API serves them at `/v1/resources/{resource_id}/availability/ical` and
+`/v1/tenant/events/{event_id}/jscalendar`.
+
 Writing rules:
 
 - Create with `expectedRevision: 0`; update with the revision you last read and a new idempotency
@@ -780,6 +866,12 @@ export async function startCalendarServer(config: CalendarServerConfig) {
 | `slotlock_list_resources` | Resources visible to the tenant | read-only |
 | `slotlock_get_free_busy` | Busy intervals plus coverage certainty | read-only |
 | `slotlock_find_next_available` | Earliest *certain* slot across resources | read-only |
+| `slotlock_find_available_slots` | Up to 50 *certain* slots, earliest first, to offer a choice | read-only |
+| `slotlock_hold_slots` | Hold up to 5 candidates for 30-900 seconds while a person chooses | write |
+| `slotlock_release_slots` | Release a hold and the rest of its group | write |
+| `slotlock_book_together` | Book the same time on 2-20 resources, all or none | write |
+| `slotlock_book_pool` | Book any one free member of a pool (a vehicle class, a room type) | write |
+| `slotlock_get_pool_availability` | How many of a pool's members are free across a window | read |
 | `slotlock_list_events` | Events the caller created in a window | read-only |
 | `slotlock_get_event` | One event the caller created | read-only |
 | `slotlock_create_event` | Create an event of up to 3,660 days (idempotent) | write |
@@ -787,7 +879,33 @@ export async function startCalendarServer(config: CalendarServerConfig) {
 | `slotlock_delete_event` | Tombstone at an expected revision | write, destructive |
 
 A query window is at most 367 days. Each caller sees only the events it created, but everyone's
-events count as busy time. The older names `calendar.<verb>` and `calendar_<verb>` still work and
+events count as busy time.
+
+An agent offering a person several times holds them first, so none is taken while the person
+decides: `slotlock_hold_slots` holds each free candidate in one group (and lists the taken ones in
+`refused`), and `slotlock_create_event` with one `hold_id` books that time and releases the rest in
+the same transaction. A hold belongs to the agent that took it: another agent can neither book nor
+release it. One agent may have 20 live holds at once, holding at most 2,160 hours together in
+`slotlock serve` (`SLOTLOCK_LIMITS`: `holder_holds`, `holder_held_hours`; `maxHoldsPerHolder` and
+`maxHeldHoursPerHolder` in `createSlotlockStore`); past either it is refused, `hold_limit_reached` or
+`held_time_limit_reached`. Unbooked holds expire by the database clock.
+Notice was judged when the time was held, so booking the hold does not judge it again.
+
+A booking that needs several resources at once (a van and its driver, a room and its projector)
+uses `slotlock_find_available_slots` with `require_free` (every resource, or any n of them, free
+together, each judged by its own hours and rules) and books with `slotlock_book_together`: one event
+per resource in one transaction, all or none. A refusal names the `resource_id` that refused, on
+MCP and A2A in the error beside its `code`, on REST in the problem. Bundles take their resources
+in one order, so two racing over the same ones end with one booked, never a deadlock.
+
+Rentals sell a class, not a plate. Put interchangeable resources in a pool
+(`PUT /v1/resources/{id}/pool`, `setResourcePool`); agents see each resource's `pool`, list a pool's
+members with `slotlock_list_resources` and `pool`, and book the class with `slotlock_book_pool`,
+which takes the first member that is free and allows the booking, in one transaction: a class of
+five sells exactly five for a time, however many race (`pool_full` after that). To see how many are
+free, `slotlock_get_pool_availability` splits a window where that number changes; to see which,
+search the members with `slotlock_find_available_slots` and `require_free: 1`: each slot names the
+members free in `resource_ids`. `GET /v1/pools` lists the pools with their capacity. The older names `calendar.<verb>` and `calendar_<verb>` still work and
 are no longer advertised.
 
 ### Errors
@@ -923,6 +1041,12 @@ never cached. W3C `traceparent`, `tracestate` and `baggage` reach your backend a
 | `GET /v1/resources` | `slotlock_list_resources` |
 | `GET /v1/free-busy` | `slotlock_get_free_busy` |
 | `GET /v1/next-available` | `slotlock_find_next_available` |
+| `GET /v1/available-slots` | `slotlock_find_available_slots` |
+| `POST /v1/slot-holds` | `slotlock_hold_slots` |
+| `DELETE /v1/slot-holds/{hold_id}` | `slotlock_release_slots` |
+| `POST /v1/bundles` | `slotlock_book_together` |
+| `POST /v1/pool-bookings` | `slotlock_book_pool` |
+| `GET /v1/pool-availability` | `slotlock_get_pool_availability` |
 | `GET /v1/events` | `slotlock_list_events` |
 | `POST /v1/events` | `slotlock_create_event` |
 | `GET /v1/events/{event_id}` | `slotlock_get_event` |
@@ -937,7 +1061,18 @@ curl "http://localhost:8080/v1/resources" -H "Authorization: Bearer $SLOTLOCK_AP
   `resource_ids=a&resource_ids=b`); `POST`, `PUT` and `PATCH` take a JSON body. Ids are in the path;
   percent-encode one that holds `/`.
 - Keys, scopes, `authorize` and the rate limit apply as over MCP. The body is the tool's output, or
-  `{"error":{"code":…}}` with the matching HTTP status.
+  an [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem (`application/problem+json`) with
+  the matching HTTP status: `type` (a tag URI, one per code), `title`, `status`, `code`, and
+  `error.code` as well, the body earlier clients read. An `overlap` names the `resource_id`, `start`
+  and `end` it refused. A `Link: <…>; rel="describedby"` header points at these docs.
+- A write's `idempotency_key` may come as the `Idempotency-Key` header instead
+  ([draft 08](https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/)): a
+  quoted Structured Field String (`Idempotency-Key: "booking-BK-42"`) or the bare key, equal to the
+  argument when both are sent. A write that needs one and gets neither answers
+  `400 idempotency_key_required`; the same key with another request, `422 idempotency_conflict`.
+  An event write's key is kept 30 days (or `SLOTLOCK_RETENTION_DAYS`), then removed by maintenance,
+  after which the key is new; a
+  hold's until the hold would have expired, is released or is confirmed.
 - REST cannot ask a person, so a write listed in `confirmation` answers `428 confirmation_required`.
 - Free/busy and the next-available search read each resource they name once, however often it is
   named, and 10,000 busy intervals in all; the next-available search also expands 100,000 bookable
@@ -999,7 +1134,7 @@ curl -X PUT "http://localhost:8080/v1/reservations/BK-42" \
   `DELETE /v1/reservations/{hold_id}?revision=2`.
 - `POST /v1/holds` and `DELETE /v1/tenant/events/…` take a retry identity as the `Idempotency-Key`
   header or as `idempotency_key`. A retried hold answers the hold the first request made; the same
-  key with another request is `409 idempotency_conflict`. Other routes are safe to retry as they
+  key with another request is `422 idempotency_conflict`. Other routes are safe to retry as they
   are, and refuse the header (`400 idempotency_key_not_supported`).
 - Lists page by `limit` (up to 100) and `cursor`, the `next_cursor` of the page before, and read a
   window of at most 367 days.
@@ -1017,6 +1152,58 @@ curl -X PUT "http://localhost:8080/v1/reservations/BK-42" \
   `{ backend: createSlotlockStoreApplicationBackend(store, { maxTenantResources }), authorize }`.
   A principal with `scopes` needs `admin`; then `authorize` decides.
 
+### Changes and webhooks
+
+Every committed change to a tenant's holds, bookings and calendar events is recorded in the same
+transaction (by a database trigger, so no write path skips it), and nothing is recorded that did
+not commit. A change carries ids, times and states, never titles, descriptions or attendees.
+
+- `GET /v1/changes?cursor=…` lists them oldest first as [CloudEvents 1.0](https://cloudevents.io)
+  (`io.pylota.slotlock.hold.created`, `.reservation.cancelled`, `.event.updated`, …). Follow
+  `next_cursor`, which comes back even when nothing is new: it never skips a change, even one whose
+  transaction commits after a later one's. Changes are kept 30 days (`SLOTLOCK_RETENTION_DAYS`,
+  `retentionDays` in `createSlotlockStore`, 1-3,650, for `serve` and `maintain` alike); a cursor
+  that a pruned change came after, whichever server pruned it, answers `410 cursor_expired`. A change keeps who made
+  it (`actor`) and a booking's or waitlist entry's reference: keep references opaque, not emails,
+  when the feed is kept long. A shorter retention never shortens how long a retried write is
+  answered as the first was: that stays at least 30 days.
+- `POST /v1/webhooks` with an https `url` (and `event_types`, optionally) sends each change from
+  then on as a [Standard Webhooks](https://www.standardwebhooks.com) request: `webhook-id` (the
+  change's id, the same on every retry), `webhook-timestamp` and `webhook-signature`, keyed by the
+  `whsec_` secret the call returns once. Verify it with any Standard Webhooks library, and use
+  `webhook-id` to drop a repeat: delivery is at least once.
+- Changes go to each webhook in order, one at a time, until one fails; that one is retried after
+  5 seconds, 5 minutes, 30 minutes, 2, 5, then every 10 hours. After a day of failures, or a `410`,
+  the webhook is disabled and the feed records `webhook.disabled`; `POST /v1/webhooks/{id}/enable`
+  resumes it where it stopped, or answers `409 changes_pruned` when what it missed is older than the
+  feed keeps (add it again and read what it missed from `/v1/changes`). The feed keeps every change
+  an enabled webhook has still to receive, however old. At most 10 webhooks per tenant.
+- Each request has 15 seconds in all, and a tenant's pass 30 seconds; tenants are delivered 8 at
+  a time, so a slow endpoint holds up only its own tenant.
+- History reads the same record backwards, with who made each change (the API key or agent) and,
+  for a change of an existing booking or event, what it was before:
+  `GET /v1/resources/{id}/history`, `GET /v1/reservations/{reference}/history`,
+  `GET /v1/tenant/events/{id}/history`, newest first, paged by `before`. In the library, pass
+  `actor` to `withTenant` and read `listHistory`. It is kept as long as the feed and erased with
+  the tenant.
+- When time zone rules change (a new tzdata), a booking's instant and the wall time it was made for
+  part: Winnipeg's 09:00 is no longer the instant stored. Slotlock keeps both, and maintenance finds
+  future one-off events whose wall time moved: it reports each once (`event.timezone_shifted`, with
+  the instant it has and the one its wall time now means). The library's `followZoneRules` option
+  to `maintainSlotlockTenant` moves them instead, as a new revision, unless that overlaps another
+  booking (`event.timezone_conflict`; it stays, for a person or an agent to decide). `/healthz`
+  reports the `tzdata` the server runs.
+- Feed health: `GET /v1/resources/{id}/coverage` shows each source's window, when it was last read,
+  its last error (`POST /v1/resources/{id}/coverage/{source}/failure` records one) and whether it is
+  stale (not read for a day, so the time it covers is unproven, never free). A source that goes stale
+  is put on the feed once, as `coverage.stale`, until it is read again. Retire a sync you have
+  disconnected or replaced with `DELETE /v1/resources/{id}/coverage/{source}` (`deleteCoverage`):
+  nothing waits on it after that, `requireCertain` included.
+- `slotlock serve` delivers (`SLOTLOCK_WEBHOOKS`): never to an address on a private network, which
+  it checks when it connects, and following no redirect. `private` allows those, for testing.
+- In the library: `listChanges`, `createWebhookEndpoint` and the rest are store methods, and
+  `startSlotlockWebhookDelivery` with `deliverSlotlockWebhooks` runs delivery in your own process.
+
 ## Connect an agent
 
 MCP and A2A are wire protocols, so an agent in any language connects with its own MCP or A2A client
@@ -1125,7 +1312,7 @@ export async function openLiveCalendar(options: LiveCalendarOptions) {
 
 ```sh
 claude mcp add --transport http slotlock https://calendar.example.com/slotlock/mcp \
-  --header "Authorization: Bearer $SLOTLOCK_TOKEN"
+  --header "Authorization: Bearer $SLOTLOCK_API_KEY"
 ```
 
 **Claude API** (MCP connector, `anthropic-beta: mcp-client-2025-11-20`; the server must be public
@@ -1186,6 +1373,18 @@ Read-only tools link to `ui://slotlock/calendar`, a self-contained calendar view
 supporting MCP Apps (`io.modelcontextprotocol/ui`) render in a sandbox. It makes no network requests
 and never writes.
 
+A person can pick a slot in it. After `slotlock_find_available_slots` or a certain
+`slotlock_find_next_available`, the view shows a strip of days and each day's times by morning,
+afternoon and evening, or the one next available time. Picking a time and pressing *Book this time*
+sends one chat message naming the resource id and the slot's start and end. The agent books it with
+`slotlock_create_event`, through confirmation if `SLOTLOCK_CONFIRM_WRITES` asks for it. The message
+carries nothing else from the result. If the host refuses the message, the view shows the text to
+send instead. Write tools are marked `visibility: ["model"]`, so a host never lets a view call them.
+
+The view takes its look from the host: its light or dark theme and its standard MCP Apps style
+variables (colours, fonts, sizes). It shows times in the person's locale, clock and time zone, with
+a 12h/24h switch.
+
 ## Operations
 
 Every tenant needs maintenance at least daily: it extends recurring events to the rolling horizon
@@ -1232,12 +1431,14 @@ export async function maintainTenant(store: SlotlockStore, tenantRef: string) {
   (provider and sync authority) are kept until you erase the tenant. After the window a retried
   command is evaluated afresh under its expected revision, and a pruned agent identity can be
   created again. `retentionDays` (1-3650) changes the window; keep it longer than any client retries.
-- **Erasure.** Include Slotlock resources, reservations, tombstones, archives, event content,
-  occurrences, commands and coverage rows in your tenant-erasure workflow and delete order, and
-  delete the tenant's API keys with `createSlotlockApiKeyStore(sql).erase({ tenantRef })`. Only
-  their SHA-256 digests stay, with nothing about the tenant, so an erased key is never accepted
-  again. The dashboard's records hold no tenant and expire within 12 hours; a form record carries a
-  SHA-256 digest of the GitHub user id that sent it.
+- **Erasure.** `slotlock tenant erase --confirm <tenant>`, or the store's `eraseTenant({ tenantRef })`,
+  deletes everything the tenant owns in one transaction, waiting for its transactions in flight:
+  resources, holds, bookings, events with their attendees and reminders, cancellations,
+  idempotency records, coverage, API keys, and a personal tenant's dashboard records. Call it from
+  your own erasure workflow; nothing is deleted table by table. Only the API keys' SHA-256 digests
+  stay, with nothing about the tenant, so an erased key is never accepted again. The dashboard's
+  other records hold no tenant and expire within 12 hours; a form record carries a SHA-256 digest
+  of the GitHub user id that sent it, and an accepted write confirmation a digest of its nonce.
 
 ### Production checklist
 
@@ -1254,13 +1455,21 @@ export async function maintainTenant(store: SlotlockStore, tenantRef: string) {
 9. Size live updates: at most `maxTotal` backend reads per `pollIntervalMs`.
 10. Give each agent its own API key with the narrowest scope and an expiry.
 11. After each deployment, check it end to end with a short-lived admin key, then revoke the key:
-    `SLOTLOCK_URL=https://… SLOTLOCK_ADMIN_KEY=… node scripts/smoke-deployment.mjs` checks health,
+    `SLOTLOCK_URL=https://… SLOTLOCK_ADMIN_KEY=… node scripts/smoke-deployment.mjs`, from a clone
+    of the repository, checks health,
     discovery, MCP, A2A, holds and reservations (in a resource named `slotlock-smoke`, 400 days
     ahead, cancelled after) and the 401, 409, 413 and 415 refusals.
 12. Rate-limit every public server. `slotlock serve` does it per client address, key, tenant and
     server (`SLOTLOCK_LIMITS`); behind a proxy, set `SLOTLOCK_TRUSTED_PROXY_HEADER` and firewall
     the server so nothing reaches it except through that proxy. Embedding the
     agent server, give it a `consumeRateLimit`. Watch serve's `refusals` log line for floods.
+13. Bound how long a transaction may run. A store over your own transaction (a savepoint per call)
+    keeps its locks and its snapshot for as long as yours runs, and a hold you confirm inside it is
+    judged by the statement's clock, not the transaction's. On PostgreSQL 17 and later, give the
+    serving role a `transaction_timeout` above your longest legitimate transaction
+    (`ALTER ROLE slotlock_app SET transaction_timeout = '60s'`): PostgreSQL ends one that runs
+    longer, rolling back what it did, and closes its connection (the pool opens another). On 16, set `idle_in_transaction_session_timeout`
+    and `statement_timeout`, which bound idle gaps and single statements but not the whole.
 
 ## Supported versions
 
@@ -1278,8 +1487,8 @@ export async function maintainTenant(store: SlotlockStore, tenantRef: string) {
 Slotlock is availability maths, holds and reservations, events with recurrence, coverage-aware
 free/busy, tenant isolation, iCalendar interchange, MCP and A2A with human confirmation and live
 updates, an MCP Apps view, REST with the application API, scoped API keys, a GitHub sign-in
-dashboard, maintenance, and clients for five languages. [Hosted Slotlock](docs/hosted/README.md)
-runs it for you. Provider sync (Google, Microsoft, CalDAV), notifications to people, and a human
+dashboard, maintenance, and clients for five languages. [Hosted Slotlock](docs/hosted/README.md),
+not open yet, will run it for you. Provider sync (Google, Microsoft, CalDAV), notifications to people, and a human
 calendar app are yours to build around it. What each version promises is in
 [VERSIONING.md](VERSIONING.md).
 

package/agent-server.d.ts

@@ -40,7 +40,7 @@ export declare const SLOTLOCK_A2A_TASK_STATES: readonly ["TASK_STATE_UNSPECIFIED
  * Operation (MCP tool / A2A skill) names. They use only `[a-z_]`, so they are valid tool names for the
  * Claude Messages API (`^[a-zA-Z0-9_-]{1,128}$`), OpenAI function calling and every MCP host.
  */
-export type SlotlockAgentOperation = 'slotlock_list_resources' | 'slotlock_get_free_busy' | 'slotlock_find_next_available' | 'slotlock_create_event' | 'slotlock_get_event' | 'slotlock_list_events' | 'slotlock_update_event' | 'slotlock_delete_event';
+export type SlotlockAgentOperation = 'slotlock_list_resources' | 'slotlock_get_free_busy' | 'slotlock_find_next_available' | 'slotlock_find_available_slots' | 'slotlock_hold_slots' | 'slotlock_release_slots' | 'slotlock_book_together' | 'slotlock_book_pool' | 'slotlock_get_pool_availability' | 'slotlock_create_event' | 'slotlock_get_event' | 'slotlock_list_events' | 'slotlock_update_event' | 'slotlock_delete_event';
 /**
  * Names earlier builds published, which every entry point still accepts and dispatches as the same
  * operation; nothing advertises them. The dotted names came first, before tool names had to be
@@ -79,7 +79,13 @@ export interface SlotlockAgentInvocationContext {
 export declare class SlotlockAgentOperationError extends Error {
     readonly code: string;
     readonly status: number;
-    constructor(code: string, status: number);
+    /**
+     * What the refusal is about, beside its code (the resource a bundle was refused on, say): at most
+     * five snake_case names with text values of up to 200 characters; anything else is dropped. Every
+     * protocol carries them next to `code`.
+     */
+    readonly details?: Readonly<Record<string, string>>;
+    constructor(code: string, status: number, details?: Record<string, string>);
 }
 export interface SlotlockAgentCalendarBackend {
     listResources(context: SlotlockAgentInvocationContext, input: Record<string, unknown>): Promise<Record<string, unknown>>;
@@ -101,6 +107,25 @@ export interface SlotlockAgentCalendarBackend {
         name: string | null;
         timezone: string | null;
     } | null>;
+    /**
+     * Optional. Hold up to five candidate slots for this principal, as alternatives in one group
+     * (`slotlock_hold_slots`); a tool without it answers `holds_unavailable`.
+     */
+    holdSlots?(context: SlotlockAgentInvocationContext, input: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** Optional. Book any one free member of a pool (`slotlock_book_pool`), else `pools_unavailable`. */
+    bookPool?(context: SlotlockAgentInvocationContext, input: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Optional. How many of a pool's members are free across a window
+     * (`slotlock_get_pool_availability`), else `pools_unavailable`.
+     */
+    getPoolAvailability?(context: SlotlockAgentInvocationContext, input: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Optional. Book one interval on several resources in one transaction, all or none
+     * (`slotlock_book_together`); a tool without it answers `bundles_unavailable`.
+     */
+    bookTogether?(context: SlotlockAgentInvocationContext, input: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** Optional. Release one of this principal's holds with its group (`slotlock_release_slots`). */
+    releaseSlots?(context: SlotlockAgentInvocationContext, input: Record<string, unknown>): Promise<Record<string, unknown>>;
 }
 /**
  * OAuth 2.0 discovery for the MCP endpoint (MCP 2025-11-25 authorization, RFC 9728). Slotlock only
@@ -120,7 +145,7 @@ export interface SlotlockAgentServerOAuthOptions {
     resourceDocumentation?: string;
 }
 /** The operations that change a calendar; the only ones a confirmation can guard. */
-export type SlotlockAgentWriteOperation = Extract<SlotlockAgentOperation, 'slotlock_create_event' | 'slotlock_update_event' | 'slotlock_delete_event'>;
+export type SlotlockAgentWriteOperation = Extract<SlotlockAgentOperation, 'slotlock_create_event' | 'slotlock_update_event' | 'slotlock_delete_event' | 'slotlock_book_together' | 'slotlock_book_pool'>;
 /**
  * Human confirmation before a write (MCP 2026-07-28 multi round-trip requests + form elicitation).
  * A listed write first answers `input_required` with a yes/no form describing the change; it runs
@@ -141,6 +166,18 @@ export interface SlotlockAgentConfirmationOptions {
     secrets: readonly (string | Uint8Array)[];
     /** How long a confirmation prompt stays answerable, in seconds: 30-3,600, default 600. */
     ttlSeconds?: number;
+    /**
+     * Optional. Records an accepted confirmation, by the nonce its sealed state carries: true the first
+     * time, false for one already recorded, which the server then refuses (`confirmation_invalid`) so
+     * an acceptance runs its write once. Keep each nonce until `expiresAt`, across every server that
+     * shares the secrets (`createSlotlockAcceptanceRecords` does, in Postgres). Without it an accepted
+     * state can be sent again until it expires; it names the same principal, write and arguments, so
+     * the write's idempotency key or expected revision then decides.
+     */
+    consumeAcceptance?: (acceptance: {
+        nonce: string;
+        expiresAt: Date;
+    }) => Promise<boolean>;
 }
 /**
  * Live calendar updates over MCP 2026-07-28 `subscriptions/listen`. A client subscribes to calendar
@@ -318,6 +355,7 @@ export type SlotlockAgentOperationDispatchResult = {
     ok: false;
     status: number;
     code: string;
+    details?: Readonly<Record<string, string>>;
 };
 /** Runtime type guard for the current operation names (legacy dotted names are not included). */
 export declare function isSlotlockAgentOperation(name: unknown): name is SlotlockAgentOperation;
@@ -376,22 +414,27 @@ export declare function slotlockOpenApi(options?: {
     application?: boolean;
 }): Record<string, unknown>;
 export declare function slotlockAgentTools(): {
-    name: "slotlock_create_event" | "slotlock_delete_event" | "slotlock_find_next_available" | "slotlock_get_event" | "slotlock_get_free_busy" | "slotlock_list_events" | "slotlock_list_resources" | "slotlock_update_event";
-    title: "Create resource event" | "Delete resource event" | "Find next available interval" | "Get free-busy" | "Get resource event" | "List calendar resources" | "List resource events" | "Update resource event";
-    description: "Apply an expected-revision event patch and rematerialize occupancy atomically. With expected_resource_id, the resource you read the event on, an event since moved elsewhere is not found." | "Create an event of up to 3,660 days (a booking, lease or long rental); opaque occurrences use the database overlap arbiter." | "Find the earliest certain interval that satisfies the requested duration (up to the 367-day search window, so a multi-month rental slot can be found)." | "List bounded events intersecting a time window." | "List resources visible to the authenticated tenant principal." | "Read one tenant-scoped event by stable identifier." | "Return privacy-minimized busy intervals and explicit coverage certainty." | "Tombstone an event at an expected revision so stale sync cannot resurrect it.";
+    name: "slotlock_book_pool" | "slotlock_book_together" | "slotlock_create_event" | "slotlock_delete_event" | "slotlock_find_available_slots" | "slotlock_find_next_available" | "slotlock_get_event" | "slotlock_get_free_busy" | "slotlock_get_pool_availability" | "slotlock_hold_slots" | "slotlock_list_events" | "slotlock_list_resources" | "slotlock_release_slots" | "slotlock_update_event";
+    title: "Book from a pool" | "Book resources together" | "Create resource event" | "Delete resource event" | "Find available slots" | "Find next available interval" | "Get free-busy" | "Get pool availability" | "Get resource event" | "Hold candidate slots" | "List calendar resources" | "List resource events" | "Release held slots" | "Update resource event";
+    description: "Apply an expected-revision event patch and rematerialize occupancy atomically. With expected_resource_id, the resource you read the event on, an event since moved elsewhere is not found." | "Book any one member of a pool (a vehicle class, a room type) for a time: members are tried in a fixed order and the first that is free and allows the booking is booked, in one transaction, so a class sells out exactly at its number of members. The event names the member booked. 409 pool_full when none is free; 404 pool_not_found when the pool has no member you may book. A retry with the same idempotency_key answers the same event." | "Book the same time on 2-20 resources at once, all or none: a van with its driver, a room with its projector. If any of them is taken, nothing is booked, and the refusal names that resource_id. Find such a time with slotlock_find_available_slots and require_free. A retry with the same idempotency_key answers the same events." | "Create an event of up to 3,660 days (a booking, lease or long rental); opaque occurrences use the database overlap arbiter." | "Find the earliest certain interval that satisfies the requested duration (up to the 367-day search window, so a multi-month rental slot can be found)." | "Hold up to five candidate slots for a short time (30-900 seconds) while a person chooses, as alternatives in one group: each free one is held, the others are listed with why not. Book one by passing its hold_id to slotlock_create_event, which releases the rest; unbooked holds expire on their own. A hold is yours alone, and you may have 20 live at once." | "How many members of a pool (a vehicle class, a room type) are free across a window, each only where its booking rules let a booking start: the window split where that number changes, each part with how many are free, and coverage certainty. Book one with slotlock_book_pool. 404 pool_not_found when the pool has no member you may book." | "List bounded events intersecting a time window." | "List resources visible to the authenticated tenant principal, with the pool each belongs to (a vehicle class, a room type). With pool, only that pool's members, in the order slotlock_book_pool tries them." | "List up to `limit` certain slots of the requested duration, earliest first across the resources, each one free of busy time and inside the resource's hours, to offer a person a choice. With require_free, only times when at least that many of the resources are free together, each slot naming them in resource_ids: every resource for a booking that needs them all (book it with slotlock_book_together), or any n of them. No slot is listed unless every resource's coverage is certain." | "Read one tenant-scoped event by stable identifier." | "Release one of your holds, and the rest of its group, at once instead of letting them expire. `released` is false when it was already gone." | "Return privacy-minimized busy intervals and explicit coverage certainty." | "Tombstone an event at an expected revision so stale sync cannot resurrect it.";
     inputSchema: Readonly<Record<string, unknown>>;
     outputSchema: Readonly<Record<string, unknown>>;
     annotations: {
-        title: "Create resource event" | "Delete resource event" | "Find next available interval" | "Get free-busy" | "Get resource event" | "List calendar resources" | "List resource events" | "Update resource event";
+        title: "Book from a pool" | "Book resources together" | "Create resource event" | "Delete resource event" | "Find available slots" | "Find next available interval" | "Get free-busy" | "Get pool availability" | "Get resource event" | "Hold candidate slots" | "List calendar resources" | "List resource events" | "Release held slots" | "Update resource event";
         readOnlyHint: boolean;
         destructiveHint: boolean;
         idempotentHint: true;
         openWorldHint: boolean;
     };
-    _meta?: {
+    _meta: {
         ui: {
             resourceUri: string;
             visibility: readonly ["model", "app"];
+        } | {
+            resourceUri: string;
+            visibility: readonly ["model"];
+        } | {
+            visibility: readonly ["model"];
         };
     };
 }[];