slotlock 0.2.0 → 0.5.0

package/SECURITY.md

@@ -22,6 +22,20 @@ Do not include real customer, credential, calendar, or booking data. We will ack
 within three business days and coordinate disclosure after a fix is available. Fixed vulnerabilities
 are published as advisories at <https://github.com/PILOTAAI/slotlock/security/advisories>.
 
+## Testing hosted Slotlock
+
+Hosted Slotlock (`slotlock-api.pylota.io` and `app.slotlock.pylota.io`, run by TREFT LTD) is in scope,
+under these rules, which its [Terms of Service](TERMS.md) and
+[Acceptable Use Policy](ACCEPTABLE-USE.md) refer to:
+
+- Test only against an account of your own, signed in with your own GitHub account.
+- Never read, change or keep another account's data. If a test reaches any, stop and report it at
+  once, and delete what you saw.
+- Run no denial of service, load test or automated scanning that sends more than the published
+  limits ([hosted service page](docs/hosted/README.md#limits)); run Slotlock yourself for that.
+- Report through private vulnerability reporting as above, and give us the time to fix it before
+  you disclose anything.
+
 ## Security model
 
 Slotlock treats all external calendar content as untrusted. The parser has explicit size, component,
@@ -108,7 +122,20 @@ protected-resource metadata, when configured, only tells clients where to obtain
 embedder's `authenticate` must verify every token, including its audience. Embedders must provide
 bearer-token verification, per-principal authorization, distributed rate limiting, TLS termination,
 and a readiness check. Do not place provider credentials or raw calendar content in authentication,
-authorization, rate-limit, or health callbacks.
+authorization, rate-limit, or health callbacks. `slotlock serve`, its own embedder, limits requests
+per client address before any credential is looked up, then per key, per tenant and for the whole
+server, caps writes that expand a recurring series, maintenance runs and live-update streams per
+tenant, answers a full key-lookup queue as busy rather than unauthenticated, and logs counts of
+refusals with each client as a pseudonym (`SLOTLOCK_LIMITS`, `SLOTLOCK_TRUSTED_PROXY_HEADER`). A
+key that authenticated in the last 15 minutes waits in a lookup queue of its own, served first; a
+valid key that has not authenticated in the last 15 minutes (any key, after a restart) waits with
+made-up keys and may be answered busy (503 with `Retry-After`) while a flood of them lasts, never
+401. Its counts are one process's: several instances each limit alone.
+
+Write confirmation (MCP 2026-07-28 form elicitation) seals the pending write to the caller, the tool
+and its exact arguments, but the answer comes from the client: Slotlock relies on the MCP client to
+ask its person, and a key holder's own client can answer yes. It keeps an agent from writing unasked;
+it is not an authorization boundary. Scopes and `authorize` decide who may write.
 
 ## API keys and the application API
 
@@ -118,7 +145,9 @@ bits) and a 6-character checksum, and the database keeps only its SHA-256. A slo
 238 random bits, so a fast hash
 loses nothing and lets every request look a key up by its digest in one indexed read. Code scanners
 that treat every secret as a password report this as weak hashing (CodeQL
-`js/insufficient-password-hash`); it is the design, as for GitHub's and Stripe's tokens.
+`js/insufficient-password-hash`); it is the design, as for GitHub's and Stripe's tokens. The
+repository's CodeQL configuration (`.github/codeql/codeql-config.yml`) drops that one query with
+this reason beside it, rather than dismissing its alerts one by one.
 
 A key acts only in the tenant it was created for. `read` and `write` cover the agent tools; `admin`
 covers the application API (resources, hours, holds, reservations, coverage, maintenance), which is

package/SPEC.md

@@ -1,7 +1,8 @@
 # Slotlock agent-calendar specification 1.0
 
-This document defines the interoperable scheduling semantics of Slotlock 0.1. Implementations may use
-different transports or persistence layers, but must preserve these rules when claiming compatibility.
+This document defines the interoperable scheduling semantics of Slotlock 0.2 and later.
+Implementations may use different transports or persistence layers, but must preserve these rules
+when claiming compatibility. Which of them may change between releases is in VERSIONING.md.
 
 ## Resource model
 
@@ -15,8 +16,71 @@ rule assumes a particular industry.
 - Availability rules use local wall time in the resource's IANA timezone.
 - Every interval is half-open `[start, end)`. `end` must be strictly after `start`.
 - Adjacent intervals do not conflict. Overlapping or touching availability windows may be merged.
-- Daylight-saving gaps move a nonexistent wall time forward by the gap. Ambiguous fall-back wall
-  times resolve to the first occurrence.
+- An event's time zone is an IANA name, kept in its canonical spelling (`europe/london` is stored
+  as `Europe/London`). A UTC offset such as `+05:00` is not a zone, and an event in one is refused.
+- An event time in an hour the clocks skip moves forward by the gap, and one in an hour they repeat
+  is its first instant (RFC 5545 §3.3.5), except where "Daylight-saving time" below says otherwise.
+- An availability window's edge in an hour the clocks skip stands where that hour ends, so a window
+  holds only the wall times it names that exist: in New York on 2027-03-14, [02:30, 03:30) is
+  03:00-03:30 EDT and [02:00, 02:30) is nothing. An edge in a repeated hour is its first instant.
+
+## Daylight-saving time
+
+An occurrence of a timed recurring event starts at its wall time read as above, and ends at the
+later of two readings:
+
+- its exact end: its start plus the series' exact length, DTEND − DTSTART as instants (RFC 5545
+  §3.8.5.3), or its DURATION, whose days and weeks are calendar days and whose hours, minutes and
+  seconds are exact (§3.3.6);
+- its wall-clock end: DTEND's wall time as written, carried to the occurrence's date (one written
+  in an hour the clocks skip is carried as written), the later instant where the clocks repeat
+  that hour. A stored series keeps its first occurrence as instants, and reads this end from its
+  end instant.
+
+It occupies `[start, later end)`, so whichever way people read an occurrence that the clocks
+change inside, none of the time they hold is offered as free. A stored series' first occurrence
+starts at the instant stored, which may be the second pass of a repeated hour. One-off events,
+overrides (moved occurrences) and PERIOD RDATEs occupy exactly the times they give. Display and
+export keep each event as written. Feeds, the trusted importer and the store read events this way
+in every zone, including zones whose rules changed in the past and zones a feed defines only by
+its VTIMEZONE.
+
+A series' occurrences never overlap each other. Where one ends after the next starts (24 exact
+hours from midnight run to 01:00 the night the clocks go forward, or an occurrence is longer than
+the series' period), it ends where the next starts, and the next ends at the later of the two ends.
+Together they hold the same time, and the store, which keeps each occurrence as a reservation
+under one EXCLUDE constraint, can hold them. Two that start at the same instant are left as they
+are. An all-day series occupies whole local days, from one local midnight to the next (a midnight
+the clocks skip moves forward).
+
+| Case | Example | Occupies |
+| --- | --- | --- |
+| The clocks go forward inside an occurrence | London, daily 00:00-06:00, 2027-03-28 | six exact hours, 00:00Z-06:00Z |
+| The clocks go back inside an occurrence | London, daily 00:00-06:00, 2026-10-25 | seven wall-clock hours, 2026-10-24 23:00Z-06:00Z |
+| The clocks go back, southern hemisphere | Santiago, daily 22:00-04:00, night of 2027-04-03 | seven hours, 2027-04-04 01:00Z-08:00Z |
+| The clocks go forward, southern hemisphere | Auckland, daily 00:00-06:00, 2027-09-26 | six hours, 2027-09-25 12:00Z-18:00Z |
+| A day long, the clocks go forward | London, daily 00:00-00:00 from 2027-03-26 | on 2027-03-28, 00:00Z-23:00Z, where the next day starts |
+| A week long, the clocks go forward | New York, weekly 00:00 for 168 hours from 2027-03-07 | the second week 2027-03-14 05:00Z to 03-21 04:00Z |
+| An all-day series | Santiago, daily from 2027-09-03 | on 2027-09-05, 04:00Z (01:00, midnight being skipped) to 09-06 03:00Z |
+| An occurrence starts in the skipped hour | Berlin, daily 02:30 for 75 minutes, 2027-03-28 | 75 exact minutes from 01:30Z (03:30 CEST) |
+| A half-hour change | Lord Howe, daily 02:00-02:45, 2027-10-03 | 45 minutes from 2027-10-02 15:30Z |
+| DTEND falls in the repeated hour | New York, daily 23:00-01:30 from 2026-10-31 | 2026-11-01 03:00Z to the later 01:30, 06:30Z |
+| DTEND falls in the skipped hour | New York, daily 01:00-02:30 from 2027-03-14 | the first 06:00Z-07:30Z, as written; later days 90 minutes, to the written 02:30 |
+| The first instance spans the change | Berlin, weekly 01:00-04:00 from 2027-03-28 | as written, 00:00Z-02:00Z; later weeks three hours |
+| An occurrence starts in the repeated hour | London, daily 01:15-01:45 from 2026-10-20 | on 2026-10-25, its first 01:15 (00:15Z) to the later 01:45 (01:45Z) |
+| A stored first occurrence in the repeated hour | London, stored from 2026-10-25 01:15Z | the second 01:15, as stored |
+| A length the clocks reduce to nothing | DTSTART and DTEND both in one skipped hour, the end at its close | refused |
+
+A series whose DTSTART the clocks skip is read from a feed (from the offset before the gap) but is
+not stored: no instant reads back as its wall time. The same holds for an all-day series whose
+first day's midnight the clocks skip (Santiago and Havana go forward at midnight). The trusted
+importer stores an all-day series as a timed one from local midnight to local midnight, which the
+union rule holds to its exact length too: where the clocks go forward on one of its days, or at the
+midnight its first occurrence ends, it may also hold the hour after a midnight that the feed's days
+do not, never less. The trusted importer does not store a timed series whose DTEND the clocks skip, or
+whose DURATION counts days or weeks outside UTC: kept as its first occurrence's instants, the first
+would hold an hour the feed does not on every later day, and the second on each day it spans that
+the clocks go forward.
 
 ## Availability
 
@@ -24,7 +88,7 @@ Availability is the intersection of explicit bookable windows and the complement
 No rule means no availability. Unsupported or invalid rules contribute no availability. A next-slot
 answer must fit wholly inside the resulting free set for the requested positive duration.
 
-Slotlock 0.1 supports weekly RRULE cadence with explicit `BYDAY`, interval 1, optional absolute
+Weekly availability supports RRULE cadence with explicit `BYDAY`, interval 1, optional absolute
 `UNTIL`, a local start minute, and a positive duration. Rules requiring an authored recurrence anchor
 such as `COUNT` or interval greater than 1 fail closed.
 
@@ -33,7 +97,9 @@ such as `COUNT` or interval greater than 1 fail closed.
 - The persistence layer is the final conflict arbiter; an application pre-check is not authority.
 - A live hold occupies the same range as a confirmed reservation until its database-clock expiry.
 - Confirm and release operations are atomic and idempotent for their expected retry cases.
-- A trailing buffer extends occupied time without changing the customer-visible end instant.
+- A hold lasts at most 7 days from its creation.
+- A trailing buffer extends occupied time without changing the customer-visible end instant. It is
+  at most 30 days, and holds and reservations alike respect it.
 - External commands use `(tenantRef, externalRef)` as stable identity and a strictly increasing
   positive revision. A replay with the same revision and payload is idempotent; drift is rejected.
 - Cancellation leaves a revisioned tombstone so delayed delivery cannot resurrect the identity.
@@ -58,6 +124,13 @@ the provider, map a connection to one resource, normalize status/transparency/re
 durable cursor and coverage window, and reconcile deletions. iCalendar parsing must remain bounded by
 input size, components, exceptions, occurrences, work, and expansion horizon.
 
+A feed's overrides occupy what the provider shows: one without DTEND or DURATION lasts its series'
+length, and one whose RECURRENCE-ID names no occurrence, or whose occurrence the series also
+EXDATEs, occupies its own time. The instances of a CalDAV-expanded series are each read, the first
+with or without a RECURRENCE-ID. An event with both DTEND and DURATION is refused (RFC 5545
+§3.6.1). A reader that can name refused series refuses one series at a time and reads the rest of
+the feed; one that cannot refuses the feed, so a refused series is never read as free time.
+
 Content not required for conflict decisions should be discarded before reaching an agent. Outbound
 iCalendar updates retain stable UID and monotonic sequence; cancellation is explicit.
 
@@ -71,12 +144,37 @@ the key with drift fails. Cancellation atomically removes derived occupation and
 tombstone; delayed create delivery cannot resurrect the UID.
 
 Events may carry organizer, attendees, roles, participation status, RSVP requests, display/email
-relative reminders, one RFC 5545 RRULE, and bounded recurrence exceptions. A materialization window is
-mandatory for recurring events, must not exceed 367 days, and may produce at most 2,000 occurrences
-under one 4,000-step work budget. Opaque occurrences are reservations under the same PostgreSQL EXCLUDE
-constraint as bookings and holds. Transparent occurrences remain queryable but occupy no resource.
-An event update replaces its materialized set transactionally, so an overlap rolls the entire mutation
-back and preserves the prior event.
+relative reminders, one RFC 5545 RRULE, and bounded recurrence exceptions. A materialization window
+is mandatory for recurring events, must not exceed 367 days, and may produce at most 2,000
+occurrences. Expansion is bounded by a count of work, never a clock, so an input is accepted or
+refused the same way however loaded the machine: each series may pass 4,000 occurrences from its
+start, and an expansion may take 50,000 steps for an event as it is written and 500,000 for a feed
+or a stored series as maintenance rolls it. A step of ical.js's search costs three, a weekday it
+compares one, a day it walks a fifth, a year it scans three and an eighth for each day that scan
+lists, and a weekday of a year it lists half. Each occurrence passed costs one, each conversion of a
+time in an IANA zone half (one and a half in a zone only a feed defines), and each instant Intl is
+asked for to read a zone's offsets five, charged the first time the expansion reads that day of the
+zone whatever was read before it. Each change listed when a feed's own zone is expanded costs four
+tenths. A zone written the way Outlook writes them, from 1601, costs about 6,000.
+
+A stored rule is daily or less frequent, follows RFC 5545 §3.3.10's grammar (every part known and
+given once, `COUNT` at least 1, never `COUNT` with `UNTIL`), and is of a shape the expander reads
+as RFC 5545 does: `BYWEEKNO`, a two-digit `BYDAY` ordinal, `BYSETPOS` other than with
+`FREQ=MONTHLY` and `BYDAY` alone, `BYMONTH` with `FREQ=MONTHLY`, a negative `BYMONTHDAY` other
+than with `FREQ=MONTHLY` and no `BYDAY`, `FREQ=YEARLY` with `BYMONTHDAY` but no `BYMONTH` or with a
+day none of its months has, with `COUNT` or `BYDAY` and a day one of its months can lack, with
+`BYYEARDAY` and `BYMONTH` or `BYMONTHDAY`, or with a numbered `BYDAY` and `BYMONTHDAY`, and time
+parts with `FREQ=MONTHLY` or `YEARLY` are refused, with a reason. A yearly day some years lack (29
+February, or a 31st with April) occurs only in the years that have it (RFC 5545 §3.3.10), so its
+rule must be its series' only source of occurrences, with no RDATE or second RRULE. A DATE `UNTIL`
+on a timed series includes its whole day on the series' clock.
+
+A recurrence exception names the occurrence it changes by that occurrence's instant, exported as a
+UTC `RECURRENCE-ID`; one that names no occurrence is refused. Opaque occurrences are reservations
+under the same PostgreSQL EXCLUDE constraint as bookings and holds. Transparent occurrences remain
+queryable but occupy no resource. An event update replaces its materialized set transactionally,
+so an overlap rolls the entire mutation back and preserves the prior event. An exported calendar
+holds a VTIMEZONE (RFC 5545 §3.6.5) for the zone its times name, written from the IANA rules.
 
 Full event content is accepted only by the explicit trusted parser. The provider-normalization parser's
 return type contains only identity, recurrence identity, interval, deletion, busy, and revision. A
@@ -89,7 +187,8 @@ contains the entire window. Any missing, stale, or partial source is returned by
 silently treated as free time.
 
 An event has a finite, positive duration. A one-off event may last up to 3,660 days and its
-occupation matches the event exactly; a recurring event's occurrences are materialized as above. An
+occupation matches the event exactly; a recurring event's occurrences are materialized as above,
+each occupying what "Daylight-saving time" says. An
 all-day (`VALUE=DATE`) iCalendar event covers whole local days of the calendar's timezone, from local
 midnight to local midnight, taken from the caller's calendar timezone, else the feed's
 `X-WR-TIMEZONE`; with neither the input is refused, never read in the server's zone. An all-day
@@ -205,8 +304,10 @@ that span changed, so the passage of time alone announces nothing. It ends a
 subscription gracefully, with the listen request's result, at its maximum duration, on shutdown, or
 when a re-read is refused as unauthenticated, unauthorized or not found; it closes the stream without
 a result after three consecutive failed re-reads or when the reader leaves more than 256 events
-unread. Open subscriptions, counted from the moment they start opening, are capped per principal and
-per server. A subscription that honors nothing ends right after its acknowledgment.
+unread. Open subscriptions, counted from the moment they start opening, are capped per principal,
+per tenant and per server. When the server is full, a listen from a tenant holding fewer than the
+tenant holding most, less one, ends that tenant's oldest open stream gracefully, as at shutdown,
+rather than being refused. A subscription that honors nothing ends right after its acknowledgment.
 
 ### Discovery and authorization
 
@@ -220,6 +321,32 @@ so each must be a canonical URL without credentials, query or fragment: `https`,
 when `allowInsecureLocalhost` is set. Publishing metadata grants nothing: the embedder's
 `authenticate` verifies every token, including its audience.
 
+### Scopes, API keys and the application API
+
+Every authenticated principal carries a tenant and scopes from `read`, `write` and `admin`. A read
+operation needs `read`; an event write needs `write`. The application API (resources, weekly hours,
+holds, reservations, coverage, every key's events, the tenant itself and maintenance, as REST under
+`/v1` beside the tools) needs `admin`. It is never an MCP tool or an A2A skill and never waits for a
+confirmation. Through it a tenant may cancel any of its events, whichever key wrote it, and, only
+where the server allows it and with its own reference as confirmation, erase itself; it never
+suspends itself or lifts a suspension, which only the deployment role does.
+
+An API key is a random secret, stored only as its SHA-256 digest and reached only through
+`SECURITY DEFINER` functions. It acts in the tenant it was created in, with the scopes it was given
+(`read` and `write` by default), until it expires (at most 3,650 days) or is revoked. A tenant holds
+at most 100 active keys and 1,000 in all. The digest of a rotated or erased key is kept, so that key
+is never valid again. A server's own bearer token is never `admin`.
+
+A dashboard signs a person in with GitHub, asking for no scope, to the tenant `github:<user id>`,
+and manages that tenant's keys, resources (at most 100) and weekly hours.
+
+### Maintenance
+
+Recurring events are materialized up to the rolling horizon. Maintenance extends each series to it
+and deletes commands and tombstones past the retention window, in bounded batches; a run that
+reaches its batch limit says so, and the next run continues. `slotlock serve` maintains each tenant
+it serves every hour; `slotlock maintain` and the application API run it on demand.
+
 ### Principal-scoped events, quotas and retention
 
 `createSlotlockStoreAgentBackend` is the canonical binding to the PostgreSQL kernel. It derives an

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,13 +145,16 @@ 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
  * only when the client retries with the person's explicit acceptance and the sealed state it was
  * given. Where no confirmation is possible — the 2025 MCP revisions and A2A — a listed write fails
- * with `confirmation_required`, never silently runs.
+ * with `confirmation_required`, never silently runs. The acceptance comes from the client, which a
+ * key holder controls: confirmation keeps an agent from writing unasked, and is not an
+ * authorization boundary (scopes and `authorize` are). Off unless set; `slotlock serve` sets it only
+ * when SLOTLOCK_CONFIRM_WRITES opts in.
  */
 export interface SlotlockAgentConfirmationOptions {
     operations: readonly SlotlockAgentWriteOperation[];
@@ -138,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
@@ -155,6 +195,12 @@ export interface SlotlockAgentSubscriptionOptions {
     keepAliveMs?: number;
     /** Open subscriptions one principal may hold: 1-64, default 4. */
     maxPerPrincipal?: number;
+    /**
+     * Open subscriptions one tenant may hold across all its principals: 1-10,000, default `maxTotal`.
+     * Set it below `maxTotal` on a multi-tenant server, so a tenant with many keys cannot hold every
+     * slot.
+     */
+    maxPerTenant?: number;
     /** Open subscriptions across the server: 1-10,000, default 256. */
     maxTotal?: number;
 }
@@ -193,7 +239,7 @@ export type SlotlockAgentServerEvent = {
     type: 'subscription';
     outcome: 'opened' | 'closed';
     /** Why a subscription closed. */
-    reason?: 'client' | 'duration' | 'shutdown' | 'revoked' | 'failed' | 'empty';
+    reason?: 'client' | 'duration' | 'shutdown' | 'revoked' | 'failed' | 'empty' | 'preempted';
     /** How many calendar resources it watched. */
     resources: number;
 };
@@ -309,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;
@@ -367,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." | "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"];
         };
     };
 }[];