slotlock 0.2.0 → 0.3.0

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

@@ -126,7 +126,10 @@ export type SlotlockAgentWriteOperation = Extract<SlotlockAgentOperation, 'slotl
  * 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[];
@@ -155,6 +158,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 +202,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;
 };
@@ -369,7 +378,7 @@ export declare function slotlockOpenApi(options?: {
 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.";
+    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.";
     inputSchema: Readonly<Record<string, unknown>>;
     outputSchema: Readonly<Record<string, unknown>>;
     annotations: {

package/agent-server.js

@@ -3,6 +3,7 @@ import { z } from 'zod';
 import { SLOTLOCK_MCP_APPS_EXTENSION, SLOTLOCK_MCP_APP_HTML, SLOTLOCK_MCP_APP_MIME_TYPE, SLOTLOCK_MCP_APP_RESOURCE, SLOTLOCK_MCP_APP_RESOURCE_URI, clientSupportsSlotlockMcpApp, } from './mcp-app.js';
 import { MCP_META_PROTOCOL_VERSION, MCP_META_SERVER_INFO, MCP_META_SUBSCRIPTION_ID, MCP_MISSING_REQUIRED_CLIENT_CAPABILITY, canonicalJson, checkModernMcpRequest, isRecord, openMcpEventStream, openRequestState, principalTag, sealRequestState, sha256Hex, stateSecrets, traceContextFrom, } from './mcp-modern.js';
 import { SLOTLOCK_APPLICATION_OPERATIONS, SLOTLOCK_APPLICATION_SCOPE, isSlotlockApplicationOperation, slotlockApplicationOperation, } from './application-api.js';
+import { SLOTLOCK_EVENT_OUTPUT as EVENT } from './event-schema.js';
 import { ignoreRejection } from './hooks.js';
 import { slotlockPackageVersion } from './package-version.js';
 import { SLOTLOCK_APPLICATION_REST_ROUTES, SLOTLOCK_REST_ROUTES, matchSlotlockRestRoute, restInputFromBody, restQueryInput, slotlockOpenApiDocument, } from './rest-api.js';
@@ -61,14 +62,6 @@ const RESOURCE_ID = z.string().trim().min(1).max(200);
 const EVENT_ID = z.string().trim().min(1).max(500);
 const IDEMPOTENCY_KEY = z.string().trim().min(1).max(200);
 const REVISION = z.number().int().positive();
-// Output bounds mirror the trusted store's byte ceilings. A value admitted by a UTF-8 byte
-// ceiling can never exceed that many UTF-16 code units, so every valid stored/provider event is
-// serializable without truncating recurrence semantics or calendar identities.
-const TRUSTED_SUMMARY_OUTPUT_MAX = 4_096;
-const TRUSTED_TEXT_OUTPUT_MAX = 16_384;
-const TRUSTED_PERSON_NAME_OUTPUT_MAX = 1_024;
-const TRUSTED_RECURRENCE_EXCEPTION_OUTPUT_MAX = 1_000;
-const TRUSTED_REMINDER_MINUTES_OUTPUT_MAX = 366 * 24 * 60;
 const MAX_AGENT_WINDOW_MS = SLOTLOCK_CALENDAR_HORIZON_DAYS * 24 * 60 * 60 * 1_000;
 /** The longest slot `slotlock_find_next_available` can look for: the whole search window. */
 const MAX_SLOT_MINUTES = SLOTLOCK_CALENDAR_HORIZON_DAYS * 24 * 60;
@@ -95,41 +88,6 @@ const COVERAGE = z
     reason: z.string().max(100).nullable(),
 })
     .strict();
-const ORGANIZER = z
-    .object({
-    address: z.string().email().max(320),
-    name: z.string().trim().max(TRUSTED_PERSON_NAME_OUTPUT_MAX).nullable(),
-})
-    .strict();
-const ATTENDEE = z
-    .object({
-    address: z.string().email().max(320),
-    name: z.string().trim().max(TRUSTED_PERSON_NAME_OUTPUT_MAX).nullable(),
-    role: z.enum(['chair', 'required', 'optional', 'non_participant']),
-    participation_status: z.enum([
-        'needs_action',
-        'accepted',
-        'declined',
-        'tentative',
-        'delegated',
-    ]),
-    rsvp: z.boolean(),
-})
-    .strict();
-const REMINDER = z
-    .object({
-    minutes_before: z.number().int().min(0).max(TRUSTED_REMINDER_MINUTES_OUTPUT_MAX),
-    channel: z.enum(['display', 'email']),
-})
-    .strict();
-const RECURRENCE_EXCEPTION = z
-    .object({
-    recurrence_id: DATE_TIME,
-    cancelled: z.boolean(),
-    starts_at: DATE_TIME.nullable(),
-    ends_at: DATE_TIME.nullable(),
-})
-    .strict();
 const ORGANIZER_INPUT = z
     .object({
     address: z.string().email().max(320),
@@ -187,30 +145,6 @@ const MCP_INITIALIZE_PARAMS = z
     _meta: z.record(z.string(), z.unknown()).optional(),
 })
     .passthrough();
-const EVENT = z
-    .object({
-    id: EVENT_ID,
-    resource_id: RESOURCE_ID,
-    starts_at: DATE_TIME,
-    ends_at: DATE_TIME,
-    timezone: z.string().min(1).max(100),
-    title: z.string().max(TRUSTED_SUMMARY_OUTPUT_MAX).nullable(),
-    description: z.string().max(TRUSTED_TEXT_OUTPUT_MAX).nullable(),
-    location: z.string().max(TRUSTED_TEXT_OUTPUT_MAX).nullable(),
-    organizer: ORGANIZER.nullable(),
-    attendees: z.array(ATTENDEE).max(100),
-    reminders: z.array(REMINDER).max(20),
-    status: z.enum(['tentative', 'confirmed', 'cancelled']),
-    transparency: z.enum(['opaque', 'transparent']),
-    sequence: z.number().int().nonnegative(),
-    revision: REVISION,
-    recurrence_rule: z.string().max(TRUSTED_SUMMARY_OUTPUT_MAX).nullable(),
-    recurrence_exceptions: z
-        .array(RECURRENCE_EXCEPTION)
-        .max(TRUSTED_RECURRENCE_EXCEPTION_OUTPUT_MAX),
-    recurrence_id: DATE_TIME.nullable(),
-})
-    .strict();
 /**
  * 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
@@ -427,7 +361,7 @@ const OPERATION_DEFINITIONS = [
     {
         name: 'slotlock_update_event',
         title: 'Update resource event',
-        description: 'Apply an expected-revision event patch and rematerialize occupancy atomically.',
+        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.',
         input: z
             .object({
             event_id: EVENT_ID,
@@ -447,6 +381,8 @@ const OPERATION_DEFINITIONS = [
             recurrence_rule: RECURRENCE_RULE.nullable().optional(),
             recurrence_exceptions: z.array(RECURRENCE_EXCEPTION_INPUT).max(500).optional(),
             idempotency_key: IDEMPOTENCY_KEY,
+            // Last, so the generated clients that take optional arguments by position keep their order.
+            expected_resource_id: RESOURCE_ID.optional(),
         })
             .strict()
             .refine((value) => value.starts_at !== undefined ||
@@ -1152,12 +1088,14 @@ function validateSubscriptions(value) {
         }
         return setting;
     };
+    const maxTotal = bounded('maxTotal', 1, 10_000, 256);
     return {
         pollIntervalMs: bounded('pollIntervalMs', 1_000, 300_000, 10_000),
         maxDurationMs: bounded('maxDurationMs', 60_000, 86_400_000, 900_000),
         keepAliveMs: bounded('keepAliveMs', 1_000, 60_000, 15_000),
         maxPerPrincipal: bounded('maxPerPrincipal', 1, 64, 4),
-        maxTotal: bounded('maxTotal', 1, 10_000, 256),
+        maxPerTenant: bounded('maxPerTenant', 1, 10_000, maxTotal),
+        maxTotal,
     };
 }
 /**
@@ -1451,10 +1389,14 @@ function promptSeries(series, zone) {
         const booked = expandCalendarEventOccurrences(content, horizon);
         beyond = promptSeriesEnd(series.rule, booked.length, horizon.end);
         const length = end.getTime() - start.getTime();
+        // Moved: by an exception, to another time or length. One the clocks change inside, or that
+        // the store ends where the next starts, is where its rule puts it.
+        const excepted = new Set(exceptions.flatMap((exception) => exception.cancelled !== true && exception.start ? [exception.recurrenceId.getTime()] : []));
         moved = promptMoved(booked.flatMap((occurrence) => {
             const from = new Date(occurrence.recurrenceId);
-            const shifted = occurrence.start.getTime() !== from.getTime() ||
-                occurrence.end.getTime() - occurrence.start.getTime() !== length;
+            const shifted = excepted.has(from.getTime()) &&
+                (occurrence.start.getTime() !== from.getTime() ||
+                    occurrence.end.getTime() - occurrence.start.getTime() !== length);
             return shifted && Number.isFinite(from.getTime())
                 ? [{ from, start: occurrence.start, end: occurrence.end }]
                 : [];
@@ -1673,8 +1615,18 @@ async function confirmationMessage(operation, input, lookup) {
         changes.push('no longer repeats');
     }
     else if (typeof rule === 'string' && reshaped && seriesStart && seriesEnd) {
-        const seriesZone = input.timezone ?? event?.timezone ?? 'UTC';
-        changes.push(`so it books ${promptSeries({ start: seriesStart, end: seriesEnd, timezone: seriesZone, rule, exceptions }, zone)}`);
+        const seriesZone = input.timezone ?? event?.timezone;
+        if (seriesZone === undefined) {
+            // An unread event and no new zone: the store expands in the event's own, which the question
+            // cannot know, so it states no dates.
+            changes.push(`repeats ${promptRule(rule)}, on dates that follow the event's existing time zone`);
+            if (input.recurrence_exceptions !== undefined) {
+                changes.push(`exceptions to ${promptRequestedExceptions(input.recurrence_exceptions, zone)}`);
+            }
+        }
+        else {
+            changes.push(`so it books ${promptSeries({ start: seriesStart, end: seriesEnd, timezone: seriesZone, rule, exceptions }, zone)}`);
+        }
     }
     else {
         if (typeof input.recurrence_rule === 'string') {
@@ -1771,6 +1723,22 @@ function a2aError(id, code, message, info) {
         },
     });
 }
+/**
+ * The request's principal, or the error when `authenticate` throws a 503
+ * `SlotlockAgentOperationError`, as createSlotlockApiKeyAuthenticator does when its lookup queue is
+ * full: no answer about the credential, so the client is told to retry rather than that it is
+ * anonymous.
+ */
+async function principalOrBusy(authenticate, request) {
+    try {
+        return await authenticate(request);
+    }
+    catch (error) {
+        if (error instanceof SlotlockAgentOperationError && error.status === 503)
+            return error;
+        throw error;
+    }
+}
 /** Map a request path onto the server's base path; `null` when it lies outside it. */
 function routePath(pathname, basePath) {
     if (basePath === '')
@@ -2185,15 +2153,48 @@ export function createSlotlockAgentServer(options) {
             return modernError(503, id, -32603, 'Server is shutting down');
         const principalKey = `${principal.tenantRef}\0${principal.subject}`;
         let held = 0;
-        for (const open of openSubscriptions)
+        let heldByTenant = 0;
+        for (const open of openSubscriptions) {
             if (open.principalKey === principalKey)
                 held += 1;
+            if (open.tenantRef === principal.tenantRef)
+                heldByTenant += 1;
+        }
+        if (openSubscriptions.size >= subscriptionPolicy.maxTotal &&
+            held < subscriptionPolicy.maxPerPrincipal &&
+            heldByTenant < subscriptionPolicy.maxPerTenant) {
+            // A full server is shared out: a tenant holding fewer than the one holding most, less one,
+            // ends that tenant's oldest stream, so many tenants within their share cannot keep another
+            // from holding any. A slot still opening has nothing to end yet.
+            const streamsOf = new Map();
+            for (const open of openSubscriptions) {
+                if (!open.streaming)
+                    continue;
+                const streams = streamsOf.get(open.tenantRef);
+                if (streams)
+                    streams.push(open);
+                else
+                    streamsOf.set(open.tenantRef, [open]);
+            }
+            let most = [];
+            for (const streams of streamsOf.values())
+                if (streams.length > most.length)
+                    most = streams;
+            if (most.length > heldByTenant + 1)
+                most[0]?.end('preempted');
+        }
         if (openSubscriptions.size >= subscriptionPolicy.maxTotal ||
-            held >= subscriptionPolicy.maxPerPrincipal) {
+            held >= subscriptionPolicy.maxPerPrincipal ||
+            heldByTenant >= subscriptionPolicy.maxPerTenant) {
             return modernError(429, id, SLOTLOCK_MCP_RATE_LIMITED_ERROR_CODE, 'Too many subscriptions');
         }
         // The slot is held while access is checked, so concurrent opens cannot overshoot the caps.
-        const slot = { principalKey, end: (_reason) => { } };
+        const slot = {
+            principalKey,
+            tenantRef: principal.tenantRef,
+            streaming: false,
+            end: () => { },
+        };
         openSubscriptions.add(slot);
         let streaming = false;
         try {
@@ -2257,6 +2258,7 @@ export function createSlotlockAgentServer(options) {
             });
         }
         slot.end = end;
+        slot.streaming = true;
         stream.send({
             jsonrpc: '2.0',
             method: 'notifications/subscriptions/acknowledged',
@@ -2463,7 +2465,10 @@ export function createSlotlockAgentServer(options) {
                 return refuse(403, 'origin_not_allowed');
             }
         }
-        const principal = await options.authenticate(request);
+        const principal = await principalOrBusy(options.authenticate, request);
+        if (principal instanceof SlotlockAgentOperationError) {
+            return refuse(503, principal.code, { 'Retry-After': '1' });
+        }
         if (!principal ||
             !isCanonicalPrincipalIdentity(principal.subject) ||
             !isCanonicalPrincipalIdentity(principal.tenantRef)) {
@@ -2516,6 +2521,21 @@ export function createSlotlockAgentServer(options) {
         if (Object.keys(params).some((name) => Object.hasOwn(given, name))) {
             return refuseCall(400, 'invalid_arguments');
         }
+        // An application write's retry identity may come as the Idempotency-Key header, where HTTP
+        // clients put it, as well as its `idempotency_key` argument. On an operation that keeps none it
+        // is refused rather than ignored: a key that was dropped would promise a replay it never gives.
+        // The agent tools take theirs as an argument alone, as they always have.
+        const idempotencyHeader = request.headers.get('idempotency-key');
+        if (idempotencyHeader !== null && isSlotlockApplicationOperation(route.operation)) {
+            const fields = (restInputSchemas.get(route.operation)?.properties ?? {});
+            if (!Object.hasOwn(fields, 'idempotency_key')) {
+                return refuseCall(400, 'idempotency_key_not_supported');
+            }
+            if (Object.hasOwn(given, 'idempotency_key') && given.idempotency_key !== idempotencyHeader) {
+                return refuseCall(400, 'invalid_arguments');
+            }
+            given = { ...given, idempotency_key: idempotencyHeader };
+        }
         const outcome = isSlotlockApplicationOperation(route.operation)
             ? await invokeApplicationOperation(slotlockApplicationOperation(route.operation), principal, { ...given, ...params }, request, trace)
             : await invokeSlotlockAgentOperation({
@@ -2607,7 +2627,17 @@ export function createSlotlockAgentServer(options) {
                     return json(403, rpcError(null, -32600, 'Origin not allowed'));
                 }
             }
-            const principal = await options.authenticate(request);
+            const principal = await principalOrBusy(options.authenticate, request);
+            if (principal instanceof SlotlockAgentOperationError) {
+                // As `slotlock serve` answers it: A2A names the reason in an ErrorInfo, as for a rate limit.
+                const error = { code: -32603, message: 'Server is busy' };
+                const info = {
+                    '@type': 'type.googleapis.com/google.rpc.ErrorInfo',
+                    reason: 'SERVER_BUSY',
+                    domain: 'slotlock',
+                };
+                return json(503, { jsonrpc: '2.0', id: null, error: path === '/a2a' ? { ...error, data: [info] } : error }, { 'Retry-After': '1' });
+            }
             if (!principal ||
                 !isCanonicalPrincipalIdentity(principal.subject) ||
                 !isCanonicalPrincipalIdentity(principal.tenantRef)) {

package/agent-store-backend.d.ts

@@ -27,6 +27,12 @@ export interface SlotlockStoreApplicationBackendOptions {
     maxTenantResources?: number;
     /** Batches of each maintenance task one `slotlock_run_maintenance` call runs, 1-100 (default 10). */
     maintenanceBatches?: number;
+    /**
+     * Let an admin key erase its own tenant (`slotlock_erase_tenant`), everything it has and every
+     * key it holds, with its tenant reference as confirmation. Off unless true: erasure cannot be
+     * undone, and an operator may owe a tenant's data a retention or review first.
+     */
+    tenantErasure?: boolean;
 }
 /**
  * Serve the application API (application-api.ts) from the production store, in the principal's