slotlock 0.2.0 → 0.3.0

package/api-keys.js

@@ -8,6 +8,7 @@
 // cannot reach another tenant's keys, read a digest, or bring back a revoked, rotated-out or erased
 // key.
 import { createHash, randomBytes } from 'node:crypto';
+import { SlotlockAgentOperationError, } from './agent-server.js';
 import { SLOTLOCK_API_KEY_ACTIVE_LIMIT, SLOTLOCK_API_KEY_RETAINED_LIMIT } from './ddl.js';
 export { SLOTLOCK_API_KEY_ACTIVE_LIMIT, SLOTLOCK_API_KEY_RETAINED_LIMIT };
 /**
@@ -41,6 +42,10 @@ const DAY_MS = 86_400_000;
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const DEFAULT_MAX_CONCURRENT_LOOKUPS = 2;
 const DEFAULT_MAX_WAITING_LOOKUPS = 256;
+/** How long a key that authenticated keeps its place ahead of unknown keys in the lookup queue. */
+const RECENTLY_VALID_MS = 15 * 60_000;
+/** Keys the authenticator remembers as recently valid, by digest; past this the oldest go first. */
+const MAX_RECENTLY_VALID = 10_000;
 function invalid(code, message) {
     return Object.assign(new Error(message), { code });
 }
@@ -230,14 +235,21 @@ export function createSlotlockApiKeyStore(sql) {
         },
     };
 }
+/** What the authenticator throws when its lookup queue is full: retry later, the key may be fine. */
+const LOOKUP_BUSY = 'server_busy';
 /**
  * Bearer authentication by API key: a request carrying an active key is that key's principal,
  * `api_key:<id>` in the key's own tenant with its scopes, which the agent server enforces before
  * `authorize`. A value that is not a well-formed key is anonymous without a lookup.
  *
  * Anyone can make well-formed keys, so lookups are bounded: a flood of made-up keys waits for at
- * most `maxConcurrentLookups` connections and is refused past `maxWaitingLookups`, and the rest of
- * the pool stays free for authenticated work. Rate-limit a public server in front of it as well.
+ * most `maxConcurrentLookups` connections, and past `maxWaitingLookups` a request is refused with a
+ * `SlotlockAgentOperationError` (`server_busy`, 503) rather than answered anonymous, which would
+ * tell a client holding a valid key that its key is bad. A key that authenticated in the last 15
+ * minutes waits in a queue of its own that is served first, so made-up keys, which never
+ * authenticate, cannot keep it waiting. Every request is still looked up, so a revoked key stops
+ * at once. Rate-limit a public server in front of it as well (`slotlock serve` does, per client
+ * address, before any lookup).
  */
 export function createSlotlockApiKeyAuthenticator(keys, options = {}) {
     const maxActive = options.maxConcurrentLookups ?? DEFAULT_MAX_CONCURRENT_LOOKUPS;
@@ -250,26 +262,37 @@ export function createSlotlockApiKeyAuthenticator(keys, options = {}) {
     }
     let active = 0;
     const waiting = [];
+    const waitingKnown = [];
+    /** Digests of keys that recently authenticated, oldest first, with when they stop counting. */
+    const recentlyValid = new Map();
     return async (request) => {
         const presented = slotlockBearerCredential(request);
         if (presented === undefined || !isSlotlockApiKey(presented))
             return null;
+        const digest = slotlockApiKeyDigest(presented).toString('hex');
+        const known = (recentlyValid.get(digest) ?? 0) > Date.now();
+        const queue = known ? waitingKnown : waiting;
         if (active < maxActive) {
             active += 1;
         }
-        else if (waiting.length < maxWaiting) {
+        else if (queue.length < maxWaiting) {
             // A finishing lookup hands its slot straight to the next waiter, so `active` is unchanged.
-            await new Promise((resolve) => waiting.push(resolve));
+            await new Promise((resolve) => queue.push(resolve));
         }
         else {
-            return null;
+            throw new SlotlockAgentOperationError(LOOKUP_BUSY, 503);
         }
         try {
             if (request.signal.aborted)
                 return null;
             const identity = await keys.authenticate(presented);
+            recentlyValid.delete(digest);
             if (!identity)
                 return null;
+            recentlyValid.set(digest, Date.now() + RECENTLY_VALID_MS);
+            if (recentlyValid.size > MAX_RECENTLY_VALID) {
+                recentlyValid.delete(recentlyValid.keys().next().value);
+            }
             return {
                 subject: `api_key:${identity.id}`,
                 tenantRef: identity.tenantRef,
@@ -277,7 +300,7 @@ export function createSlotlockApiKeyAuthenticator(keys, options = {}) {
             };
         }
         finally {
-            const next = waiting.shift();
+            const next = waitingKnown.shift() ?? waiting.shift();
             if (next)
                 next();
             else

package/application-api.d.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import type { SlotlockAgentPrincipal } from './agent-server.js';
 import type { SlotlockTraceContext } from './mcp-modern.js';
-export type SlotlockApplicationOperation = 'slotlock_create_resource' | 'slotlock_get_resource' | 'slotlock_set_resource_availability' | 'slotlock_set_tenant_availability' | 'slotlock_acquire_hold' | 'slotlock_confirm_hold' | 'slotlock_release_hold' | 'slotlock_put_reservation' | 'slotlock_cancel_reservation' | 'slotlock_record_coverage' | 'slotlock_run_maintenance';
+export type SlotlockApplicationOperation = 'slotlock_create_resource' | 'slotlock_get_resource' | 'slotlock_archive_resource' | 'slotlock_restore_resource' | 'slotlock_delete_resource' | 'slotlock_list_busy' | 'slotlock_set_resource_availability' | 'slotlock_set_tenant_availability' | 'slotlock_acquire_hold' | 'slotlock_get_hold' | 'slotlock_list_holds' | 'slotlock_confirm_hold' | 'slotlock_release_hold' | 'slotlock_get_reservation' | 'slotlock_list_reservations' | 'slotlock_put_reservation' | 'slotlock_cancel_reservation' | 'slotlock_record_coverage' | 'slotlock_list_tenant_events' | 'slotlock_get_tenant_event' | 'slotlock_cancel_tenant_event' | 'slotlock_get_tenant' | 'slotlock_erase_tenant' | 'slotlock_run_maintenance';
 /** The scope an application operation needs, whichever operation it is. */
 export declare const SLOTLOCK_APPLICATION_SCOPE = "admin";
 export interface SlotlockApplicationInvocationContext {
@@ -20,14 +20,27 @@ type Handler = (context: SlotlockApplicationInvocationContext, input: Record<str
 export interface SlotlockApplicationBackend {
     createResource: Handler;
     getResource: Handler;
+    archiveResource: Handler;
+    restoreResource: Handler;
+    deleteResource: Handler;
+    listBusy: Handler;
     setResourceAvailability: Handler;
     setTenantAvailability: Handler;
     acquireHold: Handler;
+    getHold: Handler;
+    listHolds: Handler;
     confirmHold: Handler;
     releaseHold: Handler;
+    getReservation: Handler;
+    listReservations: Handler;
     putReservation: Handler;
     cancelReservation: Handler;
     recordCoverage: Handler;
+    listTenantEvents: Handler;
+    getTenantEvent: Handler;
+    cancelTenantEvent: Handler;
+    getTenant: Handler;
+    eraseTenant: Handler;
     runMaintenance: Handler;
 }
 export interface SlotlockApplicationOperationDefinition {

package/application-api.js

@@ -1,6 +1,7 @@
 // The application API: what an application, rather than an agent, does over HTTP that the TypeScript
 // store does in process. It creates resources and sets their bookable hours, holds and reserves time,
-// records how much of an external calendar it has read, and runs maintenance. Any language can call it.
+// records how much of an external calendar it has read, reaches any of the tenant's events whichever
+// key wrote them, erases the tenant when allowed, and runs maintenance. Any language can call it.
 //
 // The agent server serves these operations as REST under /v1, beside the agent tools, when it is
 // given an `application` backend and `rest` is on, and describes them in the same OpenAPI document.
@@ -9,11 +10,14 @@
 // This module holds only the contract (names, schemas, routes); it imports nothing from the agent
 // server at runtime. The store-backed implementation is createSlotlockStoreApplicationBackend.
 import { z } from 'zod';
+import { SLOTLOCK_EVENT_OUTPUT } from './event-schema.js';
+import { SLOTLOCK_CALENDAR_HORIZON_DAYS } from './rules.js';
 /** The scope an application operation needs, whichever operation it is. */
 export const SLOTLOCK_APPLICATION_SCOPE = 'admin';
 const DATE_TIME = z.string().datetime({ offset: true });
 const RESOURCE_ID = z.string().trim().min(1).max(200);
 const HOLD_ID = z.string().trim().min(1).max(200);
+const EVENT_ID = z.string().trim().min(1).max(200);
 /** Matches the store's identities: not blank, at most 500 UTF-8 bytes, no control characters. */
 const IDENTITY = z
     .string()
@@ -38,6 +42,32 @@ const boundedSpan = (value) => {
     return span > 0 && span <= MAX_SPAN_MS;
 };
 const SPAN_MESSAGE = { message: 'end must be after start, by at most 3,660 days' };
+/** The longest window one list or busy read covers: the store's calendar horizon. */
+const MAX_WINDOW_MS = SLOTLOCK_CALENDAR_HORIZON_DAYS * 24 * 60 * 60 * 1_000;
+const boundedWindow = (value) => {
+    const span = Date.parse(value.end) - Date.parse(value.start);
+    return span > 0 && span <= MAX_WINDOW_MS;
+};
+const WINDOW_MESSAGE = {
+    message: `end must be after start, by at most ${SLOTLOCK_CALENDAR_HORIZON_DAYS} days`,
+};
+const PAGE_LIMIT = z.number().int().min(1).max(100).default(50);
+/** The `next_cursor` of the page before; opaque. */
+const CURSOR = z.string().min(1).max(500);
+const NEXT_CURSOR = z.string().max(500).nullable();
+const VISIBILITY = z.enum(['shared', 'private']);
+/**
+ * A retry identity, as the `Idempotency-Key` request header or this field (the same value, if both
+ * are sent): the same key with the same request answers what the first did, and with another
+ * request is 409 idempotency_conflict.
+ */
+const IDEMPOTENCY_KEY = IDENTITY.describe('A retry identity, also accepted as the Idempotency-Key header: the same key with the same request answers what the first did; with another request, 409 idempotency_conflict.');
+/** Minutes after the end kept busy as well, for turnaround: at most 30 days. */
+const BUFFER_AFTER_MINUTES = z
+    .number()
+    .int()
+    .min(0)
+    .max(30 * 24 * 60);
 const AVAILABILITY_RULE = z
     .object({
     rrule: z.string().min(1).max(500),
@@ -53,6 +83,10 @@ const RESOURCE = z
     timezone: TIMEZONE,
     /** The resource's own weekly hours; `null` when it uses the default. */
     availability: AVAILABILITY_RULES.nullable(),
+    /** `private` resources are never shown to agents; fixed when the resource is created. */
+    visibility: VISIBILITY,
+    /** When it was archived; `null` while it is in use. */
+    archived_at: DATE_TIME.nullable(),
 })
     .strict();
 const HOLD = z
@@ -77,8 +111,20 @@ const RESERVATION = z
     source: z.string().max(200).nullable(),
 })
     .strict();
+/**
+ * Any of the tenant's events, whichever key wrote it: `id` is the store's id for it, which the
+ * tenant-event routes take, `event_ref` the id its owner reads it by, and `owner_ref` who that is
+ * (`internal` for the tenant's own code, `agent:<digest>` for an API key).
+ */
+const TENANT_EVENT = SLOTLOCK_EVENT_OUTPUT.extend({
+    event_ref: z.string().max(500),
+    owner_ref: z.string().max(500),
+}).strict();
+const BUSY_INTERVAL = z.object({ start: DATE_TIME, end: DATE_TIME }).strict();
 const EXAMPLE_RESOURCE_ID = '0f8b6c1e-2d4a-4c7e-9b1a-3e5f7a9c2d4b';
 const EXAMPLE_HOLD_ID = '7c9e6679-7425-40de-944b-e07fc1f90ae7';
+const EXAMPLE_EVENT_ID = '3d6f0a2b-8c4e-4f1a-9b7d-5e2c8a1f4b6d';
+const EXAMPLE_WINDOW = { start: '2027-03-01T00:00:00Z', end: '2027-04-01T00:00:00Z' };
 const EXAMPLE_RULES = [
     { rrule: 'FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR', start_minutes: 540, duration_minutes: 480 },
 ];
@@ -86,10 +132,16 @@ export const SLOTLOCK_APPLICATION_OPERATIONS = Object.freeze([
     {
         name: 'slotlock_create_resource',
         title: 'Create or update a resource',
-        description: 'Create the resource with this external reference, or update its time zone if the tenant already has it. Repeating the call changes nothing more.',
+        description: 'Create the resource with this external reference, or update its time zone if the tenant already has it. Repeating the call changes nothing more. visibility is shared (the default: agents list and book it) or private (agents never see it), fixed at creation: naming another for an existing resource answers 409 resource_visibility_conflict.',
         method: 'POST',
         path: '/v1/resources',
-        input: z.object({ external_ref: IDENTITY, timezone: TIMEZONE.default('UTC') }).strict(),
+        input: z
+            .object({
+            external_ref: IDENTITY,
+            timezone: TIMEZONE.default('UTC'),
+            visibility: VISIBILITY.optional(),
+        })
+            .strict(),
         output: z.object({ resource: RESOURCE }).strict(),
         risk: { readOnly: false, destructive: false, idempotent: true },
         invoke: 'createResource',
@@ -98,7 +150,7 @@ export const SLOTLOCK_APPLICATION_OPERATIONS = Object.freeze([
     {
         name: 'slotlock_get_resource',
         title: 'Get a resource',
-        description: 'One resource of the tenant, with its own weekly bookable hours.',
+        description: 'One resource of the tenant, archived or not, with its own weekly bookable hours and its visibility.',
         method: 'GET',
         path: '/v1/resources/{resource_id}',
         input: z.object({ resource_id: RESOURCE_ID }).strict(),
@@ -107,6 +159,57 @@ export const SLOTLOCK_APPLICATION_OPERATIONS = Object.freeze([
         invoke: 'getResource',
         example: { resource_id: EXAMPLE_RESOURCE_ID },
     },
+    {
+        name: 'slotlock_archive_resource',
+        title: 'Archive a resource',
+        description: 'Take a resource out of use: no list shows it and it takes no new booking, hold or event (409 resource_archived), while what is on it stays and can still be cancelled or released. Archiving it again keeps the first time.',
+        method: 'POST',
+        path: '/v1/resources/{resource_id}/archive',
+        input: z.object({ resource_id: RESOURCE_ID }).strict(),
+        output: z.object({ resource: RESOURCE }).strict(),
+        risk: { readOnly: false, destructive: false, idempotent: true },
+        invoke: 'archiveResource',
+        example: { resource_id: EXAMPLE_RESOURCE_ID },
+    },
+    {
+        name: 'slotlock_restore_resource',
+        title: 'Restore a resource',
+        description: 'Put an archived resource back in use. Restoring one in use changes nothing.',
+        method: 'POST',
+        path: '/v1/resources/{resource_id}/restore',
+        input: z.object({ resource_id: RESOURCE_ID }).strict(),
+        output: z.object({ resource: RESOURCE }).strict(),
+        risk: { readOnly: false, destructive: false, idempotent: true },
+        invoke: 'restoreResource',
+        example: { resource_id: EXAMPLE_RESOURCE_ID },
+    },
+    {
+        name: 'slotlock_delete_resource',
+        title: 'Delete a resource',
+        description: "Delete a resource with its history (past bookings, coverage, cancelled events), freeing its place under the tenant's resource limit. Refused with 409 resource_in_use while a booking on it has not ended, a hold on it is live, or a calendar event is on it: cancel or move those first. deleted is false when the tenant has no such resource, deleted already, say.",
+        method: 'DELETE',
+        path: '/v1/resources/{resource_id}',
+        input: z.object({ resource_id: RESOURCE_ID }).strict(),
+        output: z.object({ deleted: z.boolean() }).strict(),
+        risk: { readOnly: false, destructive: true, idempotent: true },
+        invoke: 'deleteResource',
+        example: { resource_id: EXAMPLE_RESOURCE_ID },
+    },
+    {
+        name: 'slotlock_list_busy',
+        title: "List a resource's busy time",
+        description: `The time a resource of the tenant, private ones included, is occupied in a window of at most ${SLOTLOCK_CALENDAR_HORIZON_DAYS} days, by start: bookings with their turnaround, live holds, and calendar events. Adjacent intervals are not merged. More than 10,000 answers 400 calendar_work_limit: narrow the window. Free/busy with coverage, for the resources agents see, is slotlock_get_free_busy.`,
+        method: 'GET',
+        path: '/v1/resources/{resource_id}/busy',
+        input: z
+            .object({ resource_id: RESOURCE_ID, start: DATE_TIME, end: DATE_TIME })
+            .strict()
+            .refine(boundedWindow, WINDOW_MESSAGE),
+        output: z.object({ busy: z.array(BUSY_INTERVAL).max(10_000) }).strict(),
+        risk: { readOnly: true, destructive: false, idempotent: true },
+        invoke: 'listBusy',
+        example: { resource_id: EXAMPLE_RESOURCE_ID, ...EXAMPLE_WINDOW },
+    },
     {
         name: 'slotlock_set_resource_availability',
         title: "Set a resource's bookable hours",
@@ -134,7 +237,7 @@ export const SLOTLOCK_APPLICATION_OPERATIONS = Object.freeze([
     {
         name: 'slotlock_acquire_hold',
         title: 'Hold time',
-        description: 'Occupy a window without booking it, for example while a customer pays. The hold blocks every other booking until it expires (the database clock, ttl_seconds from now), is confirmed, or is released. A taken window answers 409 overlap.',
+        description: 'Occupy a window without booking it, for example while a customer pays. The hold blocks every other booking until it expires (the database clock, ttl_seconds from now), is confirmed, or is released. buffer_after_minutes keeps the time after it busy as well, and a confirmed hold keeps it. A taken window answers 409 overlap. With an idempotency key (the Idempotency-Key header or idempotency_key), a retry answers the hold the first request made, until that hold would have expired, is released or is confirmed; the same key with another request is 409 idempotency_conflict.',
         method: 'POST',
         path: '/v1/holds',
         input: z
@@ -148,6 +251,9 @@ export const SLOTLOCK_APPLICATION_OPERATIONS = Object.freeze([
                 .min(1)
                 .max(7 * 24 * 60 * 60),
             source: SOURCE.optional(),
+            idempotency_key: IDEMPOTENCY_KEY.optional(),
+            // Last: a generated client's 0.2.0 positional arguments keep their places.
+            buffer_after_minutes: BUFFER_AFTER_MINUTES.optional(),
         })
             .strict()
             .refine(boundedSpan, SPAN_MESSAGE),
@@ -160,12 +266,39 @@ export const SLOTLOCK_APPLICATION_OPERATIONS = Object.freeze([
             end: '2027-03-29T10:00:00Z',
             ttl_seconds: 600,
             source: 'checkout',
+            idempotency_key: 'checkout-7f3a9c',
         },
     },
+    {
+        name: 'slotlock_get_hold',
+        title: 'Get a hold',
+        description: 'One of the tenant\'s live holds. An expired, confirmed, released or unknown one answers 404 hold_not_found; a confirmed one is a reservation whose reference is the hold\'s id.',
+        method: 'GET',
+        path: '/v1/holds/{hold_id}',
+        input: z.object({ hold_id: HOLD_ID }).strict(),
+        output: z.object({ hold: HOLD }).strict(),
+        risk: { readOnly: true, destructive: false, idempotent: true },
+        invoke: 'getHold',
+        example: { hold_id: EXAMPLE_HOLD_ID },
+    },
+    {
+        name: 'slotlock_list_holds',
+        title: "List a resource's holds",
+        description: "The live holds on one of the tenant's resources, by start then id, a page at a time: pass next_cursor as cursor for the next page, until it is null.",
+        method: 'GET',
+        path: '/v1/resources/{resource_id}/holds',
+        input: z
+            .object({ resource_id: RESOURCE_ID, limit: PAGE_LIMIT, cursor: CURSOR.optional() })
+            .strict(),
+        output: z.object({ holds: z.array(HOLD).max(100), next_cursor: NEXT_CURSOR }).strict(),
+        risk: { readOnly: true, destructive: false, idempotent: true },
+        invoke: 'listHolds',
+        example: { resource_id: EXAMPLE_RESOURCE_ID, limit: 50 },
+    },
     {
         name: 'slotlock_confirm_hold',
         title: 'Confirm a hold',
-        description: 'Turn an unexpired hold into a confirmed reservation. Confirming it again answers the same reservation, so a retry is safe. An expired hold answers 409 hold_expired; a released or unknown one, 404 hold_not_found.',
+        description: "Turn an unexpired hold into a confirmed reservation, whose reference is the hold's id at revision 1: move or cancel it with the reservation routes by that reference (DELETE /v1/reservations/{hold_id}?revision=2 cancels it). Confirming it again answers the same reservation, so a retry is safe. An expired hold answers 409 hold_expired; a released or unknown one, 404 hold_not_found.",
         method: 'POST',
         path: '/v1/holds/{hold_id}/confirm',
         input: z.object({ hold_id: HOLD_ID }).strict(),
@@ -186,6 +319,41 @@ export const SLOTLOCK_APPLICATION_OPERATIONS = Object.freeze([
         invoke: 'releaseHold',
         example: { hold_id: EXAMPLE_HOLD_ID },
     },
+    {
+        name: 'slotlock_get_reservation',
+        title: 'Get a reservation',
+        description: "The tenant's booking with this reference as it now is, at its current revision: move it at that revision plus 1. A cancelled or unknown reference, or a calendar event's time, answers 404 reservation_not_found.",
+        method: 'GET',
+        path: '/v1/reservations/{reservation_ref}',
+        input: z.object({ reservation_ref: IDENTITY }).strict(),
+        output: z.object({ reservation: RESERVATION }).strict(),
+        risk: { readOnly: true, destructive: false, idempotent: true },
+        invoke: 'getReservation',
+        example: { reservation_ref: 'booking-BK-42' },
+    },
+    {
+        name: 'slotlock_list_reservations',
+        title: "List a resource's reservations",
+        description: `The tenant's bookings on one resource whose time, turnaround included, meets a window of at most ${SLOTLOCK_CALENDAR_HORIZON_DAYS} days, by start then id, a page at a time: pass next_cursor as cursor for the next page, until it is null. Calendar events are not bookings; slotlock_list_tenant_events lists them.`,
+        method: 'GET',
+        path: '/v1/resources/{resource_id}/reservations',
+        input: z
+            .object({
+            resource_id: RESOURCE_ID,
+            start: DATE_TIME,
+            end: DATE_TIME,
+            limit: PAGE_LIMIT,
+            cursor: CURSOR.optional(),
+        })
+            .strict()
+            .refine(boundedWindow, WINDOW_MESSAGE),
+        output: z
+            .object({ reservations: z.array(RESERVATION).max(100), next_cursor: NEXT_CURSOR })
+            .strict(),
+        risk: { readOnly: true, destructive: false, idempotent: true },
+        invoke: 'listReservations',
+        example: { resource_id: EXAMPLE_RESOURCE_ID, ...EXAMPLE_WINDOW, limit: 50 },
+    },
     {
         name: 'slotlock_put_reservation',
         title: 'Book or move a reservation',
@@ -198,12 +366,7 @@ export const SLOTLOCK_APPLICATION_OPERATIONS = Object.freeze([
             resource_id: RESOURCE_ID,
             start: DATE_TIME,
             end: DATE_TIME,
-            buffer_after_minutes: z
-                .number()
-                .int()
-                .min(0)
-                .max(30 * 24 * 60)
-                .default(0),
+            buffer_after_minutes: BUFFER_AFTER_MINUTES.default(0),
             revision: REVISION,
             source: SOURCE.optional(),
         })
@@ -260,6 +423,105 @@ export const SLOTLOCK_APPLICATION_OPERATIONS = Object.freeze([
             revision: 7,
         },
     },
+    {
+        name: 'slotlock_list_tenant_events',
+        title: "List a resource's events, every key's",
+        description: `The calendar events on one of the tenant's resources with an occurrence in a window of at most ${SLOTLOCK_CALENDAR_HORIZON_DAYS} days, whichever key wrote them (a revoked one's included), by start then id, a page at a time: pass next_cursor as cursor for the next page, until it is null.`,
+        method: 'GET',
+        path: '/v1/tenant/events',
+        input: z
+            .object({
+            resource_id: RESOURCE_ID,
+            start: DATE_TIME,
+            end: DATE_TIME,
+            limit: PAGE_LIMIT,
+            cursor: CURSOR.optional(),
+        })
+            .strict()
+            .refine(boundedWindow, WINDOW_MESSAGE),
+        output: z
+            .object({ events: z.array(TENANT_EVENT).max(100), next_cursor: NEXT_CURSOR })
+            .strict(),
+        risk: { readOnly: true, destructive: false, idempotent: true },
+        invoke: 'listTenantEvents',
+        example: { resource_id: EXAMPLE_RESOURCE_ID, ...EXAMPLE_WINDOW, limit: 50 },
+    },
+    {
+        name: 'slotlock_get_tenant_event',
+        title: 'Get any event of the tenant',
+        description: "One of the tenant's events by its id (the id slotlock_list_tenant_events gives), whichever key wrote it. A cancelled or unknown one answers 404 event_not_found.",
+        method: 'GET',
+        path: '/v1/tenant/events/{event_id}',
+        input: z.object({ event_id: EVENT_ID }).strict(),
+        output: z.object({ event: TENANT_EVENT }).strict(),
+        risk: { readOnly: true, destructive: false, idempotent: true },
+        invoke: 'getTenantEvent',
+        example: { event_id: EXAMPLE_EVENT_ID },
+    },
+    {
+        name: 'slotlock_cancel_tenant_event',
+        title: 'Cancel any event of the tenant',
+        description: "Cancel one of the tenant's events by its id, whichever key wrote it (a revoked key's included, without charging its quota), at the revision you last read (expected_revision). Its owner cannot create it again. With expected_resource_id, an event since moved to another resource answers 404 event_not_found. Needs an idempotency key (the Idempotency-Key header or idempotency_key): a retry with it answers the first cancellation (replayed: true).",
+        method: 'DELETE',
+        path: '/v1/tenant/events/{event_id}',
+        input: z
+            .object({
+            event_id: EVENT_ID,
+            expected_revision: REVISION,
+            expected_resource_id: RESOURCE_ID.optional(),
+            // Required, so a client always sends it; the Idempotency-Key header may stand in for
+            // it, since the server reads the header into it before the schema checks the request.
+            idempotency_key: IDEMPOTENCY_KEY,
+        })
+            .strict(),
+        output: z
+            .object({
+            event_id: EVENT_ID,
+            revision: REVISION,
+            cancelled: z.literal(true),
+            replayed: z.boolean(),
+        })
+            .strict(),
+        risk: { readOnly: false, destructive: true, idempotent: true },
+        invoke: 'cancelTenantEvent',
+        example: {
+            event_id: EXAMPLE_EVENT_ID,
+            expected_revision: 2,
+            idempotency_key: 'cancel-3d6f0a2b',
+        },
+    },
+    {
+        name: 'slotlock_get_tenant',
+        title: 'Get the tenant',
+        description: "The key's tenant: its reference, and whether it is suspended. A suspended tenant may read and writes nothing (403 tenant_suspended); only the server's operator suspends a tenant or lifts a suspension (slotlock tenant suspend).",
+        method: 'GET',
+        path: '/v1/tenant',
+        input: z.object({}).strict(),
+        output: z
+            .object({ tenant: z.object({ ref: IDENTITY, suspended: z.boolean() }).strict() })
+            .strict(),
+        risk: { readOnly: true, destructive: false, idempotent: true },
+        invoke: 'getTenant',
+        example: {},
+    },
+    {
+        name: 'slotlock_erase_tenant',
+        title: 'Erase the tenant',
+        description: "Delete everything the key's tenant has, at once and for good: resources, holds, bookings, events, coverage and every API key, this one included. confirm_tenant_ref must be the tenant's reference (slotlock_get_tenant), or it answers 400 invalid_confirmation. Off unless the server allows it (403 tenant_erasure_disabled; slotlock serve does not: its operator runs slotlock tenant erase). A suspended tenant cannot erase itself (403 tenant_suspended). Erasing again deletes nothing.",
+        method: 'POST',
+        path: '/v1/tenant/erase',
+        input: z.object({ confirm_tenant_ref: IDENTITY }).strict(),
+        output: z
+            .object({
+            total: z.number().int().min(0),
+            /** Rows deleted, by table. */
+            rows: z.record(z.string(), z.number().int().min(0)),
+        })
+            .strict(),
+        risk: { readOnly: false, destructive: true, idempotent: true },
+        invoke: 'eraseTenant',
+        example: { confirm_tenant_ref: 'fleet-ops' },
+    },
     {
         name: 'slotlock_run_maintenance',
         title: 'Run maintenance',

package/config.d.ts

@@ -33,3 +33,96 @@ export interface SlotlockServeDashboardConfig {
  * dashboard, so the rest are then required: a half-configured sign-in is a startup error.
  */
 export declare function readDashboardConfig(env: SlotlockEnv): SlotlockServeDashboardConfig | undefined;
+/** A token bucket: `perSecond` tokens come back each second, and it holds at most `burst`. */
+export interface SlotlockRate {
+    perSecond: number;
+    burst: number;
+}
+/** The token buckets `slotlock serve` keeps (SLOTLOCK_LIMITS), each counted per its own key. */
+export declare const SLOTLOCK_RATE_NAMES: readonly ["address", "key_read", "key_write", "tenant_read", "tenant_write", "global_read", "global_write", "app_read", "app_write", "sign_in"];
+export type SlotlockRateName = (typeof SLOTLOCK_RATE_NAMES)[number];
+/** The counts `slotlock serve` caps (SLOTLOCK_LIMITS), with the range each may be set to. */
+declare const CAP_RANGES: Readonly<{
+    readonly tenant_series_writes: readonly [1, 100];
+    readonly series_writes: readonly [1, 100];
+    readonly maintenance_runs: readonly [1, 100];
+    readonly subscriptions: readonly [1, 10000];
+    readonly tenant_subscriptions: readonly [1, 10000];
+    readonly key_subscriptions: readonly [1, 64];
+    readonly key_lookups: readonly [1, 8];
+    readonly key_lookup_queue: readonly [0, 10000];
+    readonly tenant_transactions: readonly [1, 10];
+    readonly tenant_holds: readonly [1, 10000000];
+    readonly tenant_reservations: readonly [1, 10000000];
+    readonly tenant_events: readonly [1, 10000000];
+    readonly tenant_coverage: readonly [1, 10000000];
+}>;
+export type SlotlockCapName = keyof typeof CAP_RANGES;
+export declare const SLOTLOCK_CAP_NAMES: readonly ("key_lookup_queue" | "key_lookups" | "key_subscriptions" | "maintenance_runs" | "series_writes" | "subscriptions" | "tenant_coverage" | "tenant_events" | "tenant_holds" | "tenant_reservations" | "tenant_series_writes" | "tenant_subscriptions" | "tenant_transactions")[];
+export interface SlotlockLimits {
+    /** Each rate, or null where SLOTLOCK_LIMITS turns it off. */
+    rates: Readonly<Record<SlotlockRateName, SlotlockRate | null>>;
+    caps: Readonly<Record<SlotlockCapName, number>>;
+}
+/**
+ * What `slotlock serve` allows unless SLOTLOCK_LIMITS says otherwise, sized for one public server on
+ * one CPU (the 2026-10-24 readiness audit measured the database at about 900 writes a second):
+ * - `address`: every request from one client address, before any credential is looked up.
+ * - `key_*`, `tenant_*`, `global_*`: an authenticated request takes a read token from its key, its
+ *   tenant and the server; a write (a REST method other than GET or HEAD, or a write tool) takes a
+ *   write token from each as well.
+ * - `app_*`: a request to the application API (application-api.ts) from an admin key takes its
+ *   read and write tokens from its tenant's application buckets instead of the key and tenant ones,
+ *   so the application and the tenant's agents cannot use up each other's budget; one from any
+ *   other key takes them from that key's own. `global_*` counts it as well.
+ * - `sign_in`: dashboard sign-ins and their callbacks from one client network: an IPv4 address,
+ *   or an IPv6 client's /48 (slotlockClientNetwork in rate-limit.ts), as the dashboard Worker
+ *   counts them.
+ * - `tenant_series_writes` and `series_writes`: writes that may expand a recurring series (a
+ *   recurring create, any update) running at once in a tenant and in each server process.
+ * - `maintenance_runs`: the application API's maintenance runs at once in each server process, one
+ *   a tenant, in slots of their own. A freed slot of either kind rests for as long as the event
+ *   loop was busy while its write held it, up to a second, then goes to the tenant with the fewest
+ *   writes in flight and, among those, the least use lately. That keeps a tenant sending one write
+ *   at a time from waiting behind tenants with more, not behind many tenants with one each
+ *   (rate-limit.ts).
+ * - `subscriptions`: MCP live-update streams the server holds open. When it is full, a tenant
+ *   holding fewer than the tenant holding most, less one, ends that tenant's oldest stream.
+ * - `tenant_subscriptions`: of those, how many one tenant may hold.
+ * - `key_subscriptions`: of those, how many one key (or the server token) may hold, and always
+ *   fewer than its tenant's, so one key cannot lock the tenant's other keys out
+ *   (slotlockKeySubscriptions).
+ * - `key_lookups` and `key_lookup_queue`: API key lookups running at once and waiting.
+ * - `tenant_transactions`: store transactions one tenant runs at once on the server's pool of 10
+ *   connections; the rest wait their turn in the process, so a tenant's writes waiting on its own
+ *   locks leave the other connections to other tenants and key lookups. A server with one tenant
+ *   can set 10.
+ * - `tenant_holds`, `tenant_reservations`, `tenant_events` and `tenant_coverage`: what one tenant
+ *   may store, counted as the store's tenant limits count it (SlotlockTenantLimits), whichever key,
+ *   agent or application writes it. Every write surface of the server shares them, so no admin
+ *   key can grow the shared database without end; a write past one answers 409 with its
+ *   `*_limit_reached` code.
+ */
+export declare const SLOTLOCK_DEFAULT_LIMITS: SlotlockLimits;
+/**
+ * The live-update streams one key may hold open: `key_subscriptions`, but at least one fewer than
+ * its tenant may (unless the tenant may hold only one), so a key at its own limit leaves its
+ * tenant's other keys a stream however the two caps are set.
+ */
+export declare function slotlockKeySubscriptions(caps: Readonly<Record<SlotlockCapName, number>>): number;
+/** A rate as SLOTLOCK_LIMITS and the `listening` log line write it: `<count>/<s|m|h>:<burst>`. */
+export declare function formatSlotlockRate(rate: SlotlockRate | null): string;
+/**
+ * SLOTLOCK_LIMITS: comma-separated `name=value` overrides of SLOTLOCK_DEFAULT_LIMITS. A rate is
+ * `<count>/<s|m|h>`, optionally `:<burst>` (default: the count), or `off`; a cap is a whole number.
+ * For example `tenant_write=2/s:10,global_write=30/s,address=off`.
+ */
+export declare function readLimits(env: SlotlockEnv): SlotlockLimits;
+/**
+ * SLOTLOCK_TRUSTED_PROXY_HEADER: the request field holding the client's address, set (and
+ * overwritten) by a proxy every request passes through, such as `CF-Connecting-IP` behind
+ * Cloudflare. Unset, the client address is the connection's. A client can send any field, so set it
+ * only when nothing reaches the server except through that proxy.
+ */
+export declare function readTrustedProxyHeader(env: SlotlockEnv): string | undefined;
+export {};