slotlock 0.1.1 → 0.3.0

package/agent-store-backend.js

@@ -3,16 +3,78 @@ import { SlotlockAgentOperationError, } from './agent-server.js';
 import { findNextAvailable } from './engine.js';
 import { expandRules } from './rules.js';
 import { calendarEventRollingHorizon } from './store.js';
+import { maintainSlotlockTenant } from './maintenance.js';
+import { parseAvailabilityRules } from './weekly-hours.js';
+/**
+ * A write runs under READ COMMITTED whatever the role's default: a store given tenant limits (as
+ * `slotlock serve`'s is) counts it against them under the tenant's lock, which needs that level,
+ * and refuses it otherwise.
+ */
+const WRITE = { isolation: 'read committed' };
 function assertActive(context) {
     if (context.signal.aborted)
         throw new SlotlockAgentOperationError('request_aborted', 503);
 }
-async function withTenant(store, context, callback) {
+async function withTenant(store, context, callback, options) {
     assertActive(context);
-    const value = await store.withTenant(context.principal.tenantRef, callback);
+    let value;
+    try {
+        value = await store.withTenant(context.principal.tenantRef, callback, {
+            ...options,
+            signal: context.signal,
+        });
+    }
+    catch (error) {
+        const code = error?.code;
+        // A suspended tenant may read; a write it asks for is forbidden, not a server failure.
+        if (code === 'tenant_suspended')
+            throw new SlotlockAgentOperationError('tenant_suspended', 403);
+        // Waited past the store's lock timeout behind the tenant's own writes: retry later.
+        if (code === 'lock_timeout')
+            throw new SlotlockAgentOperationError('server_busy', 503);
+        assertActive(context);
+        throw error;
+    }
     assertActive(context);
     return value;
 }
+/**
+ * Busy intervals one free/busy read or search may gather across all the resources it names: as many
+ * as the store reads for one resource. Without it, a request naming 100 resources at that limit, or
+ * one resource 100 times, did 100 times the work of one.
+ */
+const MAX_REQUEST_BUSY_INTERVALS = 10_000;
+/**
+ * Bookable windows one search may expand from its resources' availability rules in all: five
+ * resources of 50 daily rules over a year, or a hundred of two. Without it, a search of 100 such
+ * resources over a year expanded 1.8 million windows and held the process for seven seconds.
+ */
+const MAX_REQUEST_RULE_WINDOWS = 100_000;
+/** The resources a request names, each once, in the order first named. */
+function distinctResourceIds(input) {
+    return [...new Set(input.resource_ids)];
+}
+/** Counts a request's busy intervals against MAX_REQUEST_BUSY_INTERVALS, refusing past it. */
+function busyBudget() {
+    let left = MAX_REQUEST_BUSY_INTERVALS;
+    return (intervals) => {
+        left -= intervals;
+        if (left < 0)
+            throw new SlotlockAgentOperationError('calendar_work_limit', 400);
+    };
+}
+/** The store's free/busy read, its refusal to read past its limit answered as the caller's to narrow. */
+async function readFreeBusy(tenantStore, params) {
+    try {
+        return await tenantStore.getFreeBusy(params);
+    }
+    catch (error) {
+        if (error?.code === 'calendar_work_limit') {
+            throw new SlotlockAgentOperationError('calendar_work_limit', 400);
+        }
+        throw error;
+    }
+}
 function interval(input) {
     return { start: new Date(input.start), end: new Date(input.end) };
 }
@@ -177,25 +239,41 @@ function parseEventCursor(value) {
         throw new SlotlockAgentOperationError('invalid_cursor', 400);
     }
 }
-function encodeEventCursor(event) {
-    return Buffer.from(JSON.stringify({ start: event.start.toISOString(), id: event.id }), 'utf8').toString('base64url');
+/** The cursor after one row of a page ordered by start then id: an event, a hold or a booking. */
+function encodeEventCursor(row) {
+    return Buffer.from(JSON.stringify({ start: row.start.toISOString(), id: row.id }), 'utf8').toString('base64url');
+}
+/** One page of rows read with one more than `limit`, and the cursor to the next when there is one. */
+function page(rows, limit) {
+    const shown = rows.slice(0, limit);
+    const last = shown.at(-1);
+    return { shown, next: rows.length > limit && last ? encodeEventCursor(last) : null };
 }
 /**
  * The caller's resource with this id, or `resource_not_found`. The tools accept any id an agent may
  * send (an external reference such as `vehicle-42`, the nil UUID, a version 7 UUID). The store
  * issues version 4 UUIDs (gen_random_uuid) and refuses an id that is not a version 1 to 5 UUID as an
  * invalid identity, so such an id names no resource: it is not found, like a well-formed id that
- * names nothing or another tenant's resource.
+ * names nothing or another tenant's resource. With `visibility`, a resource of the other is not
+ * found either: agents ask for `shared`, so a private resource is invisible to them.
  */
-async function requireResource(tenantStore, tenantRef, resourceId) {
+async function requireResource(tenantStore, tenantRef, resourceId, visibility) {
     if (!STORE_ID_PATTERN.test(resourceId)) {
         throw new SlotlockAgentOperationError('resource_not_found', 404);
     }
-    const resource = await tenantStore.getResource({ tenantRef, id: resourceId });
+    const resource = await tenantStore.getResource({
+        tenantRef,
+        id: resourceId,
+        ...(visibility !== undefined ? { visibility } : {}),
+    });
     if (!resource)
         throw new SlotlockAgentOperationError('resource_not_found', 404);
     return resource;
 }
+/** The caller's shared resource with this id: what an agent may see and book. */
+function requireAgentResource(tenantStore, tenantRef, resourceId) {
+    return requireResource(tenantStore, tenantRef, resourceId, 'shared');
+}
 /** Bind the protocol server to the production store without giving a request control of tenancy. */
 export function createSlotlockStoreAgentBackend(store, options) {
     return {
@@ -206,6 +284,7 @@ export function createSlotlockStoreAgentBackend(store, options) {
                 const resource = await tenantStore.getResource({
                     tenantRef: context.principal.tenantRef,
                     id: resourceId,
+                    visibility: 'shared',
                 });
                 return resource
                     ? { name: resource.externalRef ?? null, timezone: resource.timezone }
@@ -218,6 +297,7 @@ export function createSlotlockStoreAgentBackend(store, options) {
                 const limit = input.limit;
                 const resources = await tenantStore.listResources({
                     tenantRef: context.principal.tenantRef,
+                    visibility: 'shared',
                     limit: limit + 1,
                     ...(cursor !== undefined ? { after: cursor } : {}),
                 });
@@ -234,13 +314,14 @@ export function createSlotlockStoreAgentBackend(store, options) {
         },
         async getFreeBusy(context, input) {
             const window = interval(input);
-            const resourceIds = input.resource_ids;
+            const resourceIds = distinctResourceIds(input);
+            const charge = busyBudget();
             return withTenant(store, context, async (tenantStore) => {
                 const resources = [];
                 for (const resourceId of resourceIds) {
-                    const resource = await requireResource(tenantStore, context.principal.tenantRef, resourceId);
+                    const resource = await requireAgentResource(tenantStore, context.principal.tenantRef, resourceId);
                     const sources = await requiredSources(options, context, resource);
-                    const result = await tenantStore.getFreeBusy({
+                    const result = await readFreeBusy(tenantStore, {
                         tenantRef: context.principal.tenantRef,
                         resourceId,
                         window,
@@ -249,6 +330,7 @@ export function createSlotlockStoreAgentBackend(store, options) {
                             ? { coverageMaxAgeMs: options.coverageMaxAgeMs }
                             : {}),
                     });
+                    charge(result.busy.length);
                     resources.push({
                         resource_id: resourceId,
                         busy: result.busy.map((busy) => ({
@@ -263,15 +345,17 @@ export function createSlotlockStoreAgentBackend(store, options) {
         },
         async findNextAvailable(context, input) {
             const window = interval(input);
-            const resourceIds = input.resource_ids;
+            const resourceIds = distinctResourceIds(input);
             const durationMs = input.duration_minutes * 60_000;
+            const charge = busyBudget();
+            let windowsLeft = MAX_REQUEST_RULE_WINDOWS;
             return withTenant(store, context, async (tenantStore) => {
                 let best = null;
                 let incomplete = false;
                 for (const resourceId of resourceIds) {
-                    const resource = await requireResource(tenantStore, context.principal.tenantRef, resourceId);
+                    const resource = await requireAgentResource(tenantStore, context.principal.tenantRef, resourceId);
                     const sources = await requiredSources(options, context, resource);
-                    const freeBusy = await tenantStore.getFreeBusy({
+                    const freeBusy = await readFreeBusy(tenantStore, {
                         tenantRef: context.principal.tenantRef,
                         resourceId,
                         window,
@@ -280,16 +364,17 @@ export function createSlotlockStoreAgentBackend(store, options) {
                             ? { coverageMaxAgeMs: options.coverageMaxAgeMs }
                             : {}),
                     });
+                    charge(freeBusy.busy.length);
                     if (freeBusy.coverage.state !== 'complete') {
                         incomplete = true;
                         continue;
                     }
                     const rules = resource.availabilityRules ?? (await options.availabilityRules(context, resource));
-                    const candidate = findNextAvailable({
-                        busy: freeBusy.busy,
-                        windows: expandRules(rules, window, resource.timezone),
-                        durationMs,
-                    });
+                    const windows = expandRules(rules, window, resource.timezone);
+                    windowsLeft -= windows.length;
+                    if (windowsLeft < 0)
+                        throw new SlotlockAgentOperationError('calendar_work_limit', 400);
+                    const candidate = findNextAvailable({ busy: freeBusy.busy, windows, durationMs });
                     if (candidate &&
                         (!best ||
                             candidate.start.getTime() < best.interval.start.getTime() ||
@@ -313,7 +398,7 @@ export function createSlotlockStoreAgentBackend(store, options) {
         async createEvent(context, rawInput) {
             const input = rawInput;
             return withTenant(store, context, async (tenantStore) => {
-                await requireResource(tenantStore, context.principal.tenantRef, input.resource_id);
+                await requireAgentResource(tenantStore, context.principal.tenantRef, input.resource_id);
                 const recurrence = recurrenceFromInput(input.recurrence_rule, input.recurrence_exceptions);
                 const content = {
                     start: new Date(input.starts_at),
@@ -357,7 +442,7 @@ export function createSlotlockStoreAgentBackend(store, options) {
                 if (!created)
                     throw new SlotlockAgentOperationError('store_inconsistent', 503);
                 return { event: projectSlotlockCalendarEvent(created), replayed: result.idempotent };
-            });
+            }, WRITE);
         },
         async getEvent(context, input) {
             return withTenant(store, context, async (tenantStore) => {
@@ -373,13 +458,13 @@ export function createSlotlockStoreAgentBackend(store, options) {
         },
         async listEvents(context, input) {
             const window = interval(input);
-            const resourceIds = input.resource_ids;
+            const resourceIds = distinctResourceIds(input);
             const limit = input.limit;
             const after = parseEventCursor(input.cursor);
             return withTenant(store, context, async (tenantStore) => {
                 const combined = [];
                 for (const resourceId of resourceIds) {
-                    await requireResource(tenantStore, context.principal.tenantRef, resourceId);
+                    await requireAgentResource(tenantStore, context.principal.tenantRef, resourceId);
                     combined.push(...(await tenantStore.listCalendarEvents({
                         tenantRef: context.principal.tenantRef,
                         ownerRef: agentOwnerRef(context),
@@ -400,6 +485,11 @@ export function createSlotlockStoreAgentBackend(store, options) {
         },
         async updateEvent(context, rawInput) {
             const input = rawInput;
+            // No event is on a resource the store never issued (an external reference, say).
+            if (input.expected_resource_id !== undefined &&
+                !STORE_ID_PATTERN.test(input.expected_resource_id)) {
+                throw new SlotlockAgentOperationError('event_not_found', 404);
+            }
             return withTenant(store, context, async (tenantStore) => {
                 const current = await tenantStore.getCalendarEvent({
                     tenantRef: context.principal.tenantRef,
@@ -410,7 +500,7 @@ export function createSlotlockStoreAgentBackend(store, options) {
                     throw new SlotlockAgentOperationError('event_not_found', 404);
                 const resourceId = input.resource_id ?? current.resourceId;
                 if (resourceId !== current.resourceId) {
-                    await requireResource(tenantStore, context.principal.tenantRef, resourceId);
+                    await requireAgentResource(tenantStore, context.principal.tenantRef, resourceId);
                 }
                 const recurrence = input.recurrence_rule === null
                     ? undefined
@@ -469,6 +559,9 @@ export function createSlotlockStoreAgentBackend(store, options) {
                     tenantRef: context.principal.tenantRef,
                     ownerRef: agentOwnerRef(context),
                     externalRef: current.externalRef,
+                    // The caller's fence when it sent one, checked under the event's lock; otherwise the
+                    // resource just read, so a move between that read and the write is not overwritten.
+                    expectedResourceId: input.expected_resource_id ?? current.resourceId,
                     resourceId,
                     expectedRevision: input.expected_revision,
                     idempotencyKey: agentCommandIdempotencyKey(context, input.idempotency_key),
@@ -486,7 +579,7 @@ export function createSlotlockStoreAgentBackend(store, options) {
                 if (!updated)
                     throw new SlotlockAgentOperationError('store_inconsistent', 503);
                 return { event: projectSlotlockCalendarEvent(updated), replayed: result.idempotent };
-            });
+            }, WRITE);
         },
         async deleteEvent(context, input) {
             return withTenant(store, context, async (tenantStore) => {
@@ -502,6 +595,7 @@ export function createSlotlockStoreAgentBackend(store, options) {
                     tenantRef: context.principal.tenantRef,
                     ownerRef: agentOwnerRef(context),
                     externalRef,
+                    expectedResourceId: current.resourceId,
                     idempotencyKey: agentCommandIdempotencyKey(context, input.idempotency_key),
                     expectedRevision: input.expected_revision,
                 });
@@ -513,7 +607,487 @@ export function createSlotlockStoreAgentBackend(store, options) {
                     deleted: true,
                     replayed: result.idempotent,
                 };
+            }, WRITE);
+        },
+    };
+}
+/** A store failure thrown with a `code` the caller may see, or the error itself to report. */
+function storeRefusal(error) {
+    const code = error?.code;
+    if (typeof code !== 'string')
+        return error;
+    if (code === 'resource_limit_reached' || code === 'resource_visibility_conflict') {
+        return new SlotlockAgentOperationError(code, 409);
+    }
+    if (code.startsWith('invalid_') && code !== 'invalid_transaction_isolation') {
+        return new SlotlockAgentOperationError(code, 400);
+    }
+    return error;
+}
+/** The status an application refusal answers with; the resource of another tenant is not found. */
+function applicationRefusal(code) {
+    if (code === 'resource_tenant_mismatch') {
+        return new SlotlockAgentOperationError('resource_not_found', 404);
+    }
+    if (code.endsWith('_not_found'))
+        return new SlotlockAgentOperationError(code, 404);
+    if (code.startsWith('invalid_'))
+        return new SlotlockAgentOperationError(code, 400);
+    return new SlotlockAgentOperationError(code, 409);
+}
+function rulesOutput(rules) {
+    if (!rules)
+        return null;
+    return rules.map((rule) => ({
+        rrule: rule.rrule,
+        start_minutes: rule.startMinutes,
+        duration_minutes: rule.durationMinutes,
+    }));
+}
+function rulesInput(value) {
+    if (value === null)
+        return null;
+    const rules = value.map((rule) => ({
+        rrule: rule.rrule,
+        startMinutes: rule.start_minutes,
+        durationMinutes: rule.duration_minutes,
+    }));
+    try {
+        return parseAvailabilityRules(rules);
+    }
+    catch (error) {
+        throw storeRefusal(error);
+    }
+}
+function resourceOutput(resource) {
+    return {
+        id: resource.id,
+        external_ref: resource.externalRef,
+        timezone: resource.timezone,
+        availability: rulesOutput(resource.availabilityRules),
+        visibility: resource.visibility ?? 'shared',
+        archived_at: resource.archivedAt?.toISOString() ?? null,
+    };
+}
+/** Any of a tenant's events: the store's id, which the tenant-event routes take, and its owner's. */
+function tenantEventOutput(event) {
+    return {
+        ...projectSlotlockCalendarEvent(event),
+        id: event.id,
+        event_ref: event.externalRef,
+        owner_ref: event.ownerRef,
+    };
+}
+function holdOutput(hold) {
+    return {
+        id: hold.id,
+        resource_id: hold.resourceId,
+        start: hold.start.toISOString(),
+        end: hold.end.toISOString(),
+        expires_at: hold.expiresAt.toISOString(),
+        source: hold.source,
+    };
+}
+function reservationOutput(reservation) {
+    return {
+        id: reservation.id,
+        resource_id: reservation.resourceId,
+        reservation_ref: reservation.externalRef,
+        start: reservation.start.toISOString(),
+        end: reservation.end.toISOString(),
+        // The store keeps milliseconds; a buffer set in seconds through the library still shows as busy.
+        buffer_after_minutes: Math.ceil(reservation.bufferAfterMs / 60_000),
+        revision: reservation.revision,
+        source: reservation.source,
+    };
+}
+/**
+ * The namespace an application caller's idempotency keys live in: a digest of its tenant and
+ * subject, so the authenticated subject never lands in a durable row.
+ */
+function applicationPrincipalRef(context) {
+    return `application:${createHash('sha256')
+        .update(`${context.principal.tenantRef}\0${context.principal.subject}`)
+        .digest('hex')}`;
+}
+/**
+ * An application caller's event command key: its tenant, subject and own key, digested, so one
+ * caller's key never replays another's command and neither the subject nor the raw key is stored.
+ */
+function applicationCommandKey(context, idempotencyKey) {
+    return `application-command:${createHash('sha256')
+        .update(`${context.principal.tenantRef}\0${context.principal.subject}\0${idempotencyKey}`)
+        .digest('hex')}`;
+}
+/** The most busy intervals one slotlock_list_busy answers, as one free/busy request reads. */
+const MAX_LISTED_BUSY = MAX_REQUEST_BUSY_INTERVALS;
+/**
+ * Serve the application API (application-api.ts) from the production store, in the principal's
+ * tenant. Every resource an operation names must be the tenant's, or it is not found; holds are
+ * reservations under the tenant's row-level security, so another tenant's hold is not found either.
+ */
+export function createSlotlockStoreApplicationBackend(store, options = {}) {
+    const max = options.maxTenantResources;
+    if (max !== undefined && !(Number.isSafeInteger(max) && max >= 1 && max <= 100_000)) {
+        throw new RangeError('maxTenantResources must be a whole number from 1 to 100,000');
+    }
+    const batches = options.maintenanceBatches ?? 10;
+    if (!(Number.isSafeInteger(batches) && batches >= 1 && batches <= 100)) {
+        throw new RangeError('maintenanceBatches must be a whole number from 1 to 100');
+    }
+    const tenantErasure = options.tenantErasure === true;
+    const tenantOf = (context) => context.principal.tenantRef;
+    return {
+        async createResource(context, input) {
+            // A capped create counts under READ COMMITTED; withTenant opens it for the call.
+            return withTenant(store, context, async (tenant) => {
+                try {
+                    const resource = await tenant.createResource({
+                        tenantRef: tenantOf(context),
+                        externalRef: input.external_ref,
+                        timezone: input.timezone,
+                        ...(input.visibility !== undefined
+                            ? { visibility: input.visibility }
+                            : {}),
+                        ...(max !== undefined ? { maxTenantResources: max } : {}),
+                    });
+                    return { resource: resourceOutput(resource) };
+                }
+                catch (error) {
+                    throw storeRefusal(error);
+                }
+            }, max !== undefined ? { isolation: 'read committed' } : undefined);
+        },
+        async getResource(context, input) {
+            return withTenant(store, context, async (tenant) => ({
+                resource: resourceOutput(await requireResource(tenant, tenantOf(context), input.resource_id)),
+            }));
+        },
+        async archiveResource(context, input) {
+            const id = input.resource_id;
+            if (!STORE_ID_PATTERN.test(id))
+                throw new SlotlockAgentOperationError('resource_not_found', 404);
+            return withTenant(store, context, async (tenant) => {
+                const resource = await tenant.archiveResource({ tenantRef: tenantOf(context), id });
+                if (!resource)
+                    throw new SlotlockAgentOperationError('resource_not_found', 404);
+                return { resource: resourceOutput(resource) };
+            }, WRITE);
+        },
+        async restoreResource(context, input) {
+            const id = input.resource_id;
+            if (!STORE_ID_PATTERN.test(id))
+                throw new SlotlockAgentOperationError('resource_not_found', 404);
+            return withTenant(store, context, async (tenant) => {
+                const resource = await tenant.restoreResource({ tenantRef: tenantOf(context), id });
+                if (!resource)
+                    throw new SlotlockAgentOperationError('resource_not_found', 404);
+                return { resource: resourceOutput(resource) };
+            }, WRITE);
+        },
+        async deleteResource(context, input) {
+            const id = input.resource_id;
+            // An id the store never issues names no resource: there is nothing to delete.
+            if (!STORE_ID_PATTERN.test(id))
+                return { deleted: false };
+            return withTenant(store, context, async (tenant) => {
+                const result = await tenant.deleteResource({ tenantRef: tenantOf(context), id });
+                if (!result.ok)
+                    throw applicationRefusal(result.code);
+                return { deleted: result.deleted };
+            }, WRITE);
+        },
+        async listBusy(context, input) {
+            return withTenant(store, context, async (tenant) => {
+                const resource = await requireResource(tenant, tenantOf(context), input.resource_id);
+                // One row past the cap is enough to refuse: the rest is never read.
+                const busy = await tenant.listBusy(resource.id, interval(input), {
+                    tenantRef: tenantOf(context),
+                    limit: MAX_LISTED_BUSY + 1,
+                });
+                if (busy.length > MAX_LISTED_BUSY) {
+                    throw new SlotlockAgentOperationError('calendar_work_limit', 400);
+                }
+                return {
+                    busy: busy.map((occupied) => ({
+                        start: occupied.start.toISOString(),
+                        end: occupied.end.toISOString(),
+                    })),
+                };
             });
         },
+        async setResourceAvailability(context, input) {
+            const rules = rulesInput(input.rules);
+            const id = input.resource_id;
+            if (!STORE_ID_PATTERN.test(id))
+                throw new SlotlockAgentOperationError('resource_not_found', 404);
+            return withTenant(store, context, async (tenant) => {
+                let resource;
+                try {
+                    resource = await tenant.setResourceAvailability({ tenantRef: tenantOf(context), id, rules });
+                }
+                catch (error) {
+                    throw storeRefusal(error);
+                }
+                if (!resource)
+                    throw new SlotlockAgentOperationError('resource_not_found', 404);
+                return { resource: resourceOutput(resource) };
+            });
+        },
+        async setTenantAvailability(context, input) {
+            const rules = rulesInput(input.rules);
+            return withTenant(store, context, async (tenant) => {
+                try {
+                    return {
+                        resources_updated: await tenant.setTenantAvailability({
+                            tenantRef: tenantOf(context),
+                            rules,
+                        }),
+                    };
+                }
+                catch (error) {
+                    throw storeRefusal(error);
+                }
+            });
+        },
+        async acquireHold(context, input) {
+            return withTenant(store, context, async (tenant) => {
+                const resource = await requireResource(tenant, tenantOf(context), input.resource_id);
+                const result = await tenant.acquireHold({
+                    tenantRef: tenantOf(context),
+                    resourceId: resource.id,
+                    start: new Date(input.start),
+                    end: new Date(input.end),
+                    ttlMs: input.ttl_seconds * 1_000,
+                    ...(input.source !== undefined ? { source: input.source } : {}),
+                    ...(input.buffer_after_minutes !== undefined
+                        ? { bufferAfterMs: input.buffer_after_minutes * 60_000 }
+                        : {}),
+                    // A retried request with the caller's key answers the hold the first one made.
+                    ...(input.idempotency_key !== undefined
+                        ? {
+                            idempotencyKey: input.idempotency_key,
+                            principalRef: applicationPrincipalRef(context),
+                        }
+                        : {}),
+                });
+                if (!result.ok)
+                    throw applicationRefusal(result.code);
+                return { hold: holdOutput(result.hold) };
+            }, WRITE);
+        },
+        async getHold(context, input) {
+            const id = input.hold_id;
+            if (!STORE_ID_PATTERN.test(id))
+                throw new SlotlockAgentOperationError('hold_not_found', 404);
+            return withTenant(store, context, async (tenant) => {
+                const hold = await tenant.getHold({ tenantRef: tenantOf(context), holdId: id });
+                if (!hold)
+                    throw new SlotlockAgentOperationError('hold_not_found', 404);
+                return { hold: holdOutput(hold) };
+            });
+        },
+        async listHolds(context, input) {
+            const limit = input.limit;
+            const after = parseEventCursor(input.cursor);
+            return withTenant(store, context, async (tenant) => {
+                const resource = await requireResource(tenant, tenantOf(context), input.resource_id);
+                const { shown, next } = page(await tenant.listHolds({
+                    tenantRef: tenantOf(context),
+                    resourceId: resource.id,
+                    limit: limit + 1,
+                    ...(after ? { after } : {}),
+                }), limit);
+                return { holds: shown.map(holdOutput), next_cursor: next };
+            });
+        },
+        async confirmHold(context, input) {
+            const id = input.hold_id;
+            if (!STORE_ID_PATTERN.test(id))
+                throw new SlotlockAgentOperationError('hold_not_found', 404);
+            return withTenant(store, context, async (tenant) => {
+                const result = await tenant.confirmHold(id, { tenantRef: tenantOf(context) });
+                if (!result.ok)
+                    throw applicationRefusal(result.code);
+                return { reservation: reservationOutput(result.reservation) };
+            }, WRITE);
+        },
+        async releaseHold(context, input) {
+            const id = input.hold_id;
+            // An id that is not one the store issues names no hold: there is nothing to release.
+            if (!STORE_ID_PATTERN.test(id))
+                return { released: false };
+            return withTenant(store, context, async (tenant) => ({
+                released: (await tenant.releaseHold(id, { tenantRef: tenantOf(context) })).released,
+            }));
+        },
+        async getReservation(context, input) {
+            return withTenant(store, context, async (tenant) => {
+                const reservation = await tenant.getReservation({
+                    tenantRef: tenantOf(context),
+                    externalRef: input.reservation_ref,
+                });
+                if (!reservation)
+                    throw new SlotlockAgentOperationError('reservation_not_found', 404);
+                return { reservation: reservationOutput(reservation) };
+            });
+        },
+        async listReservations(context, input) {
+            const limit = input.limit;
+            const after = parseEventCursor(input.cursor);
+            return withTenant(store, context, async (tenant) => {
+                const resource = await requireResource(tenant, tenantOf(context), input.resource_id);
+                const { shown, next } = page(await tenant.listReservations({
+                    tenantRef: tenantOf(context),
+                    resourceId: resource.id,
+                    window: interval(input),
+                    limit: limit + 1,
+                    ...(after ? { after } : {}),
+                }), limit);
+                return { reservations: shown.map(reservationOutput), next_cursor: next };
+            });
+        },
+        async putReservation(context, input) {
+            return withTenant(store, context, async (tenant) => {
+                const resource = await requireResource(tenant, tenantOf(context), input.resource_id);
+                const command = {
+                    tenantRef: tenantOf(context),
+                    externalRef: input.reservation_ref,
+                    resourceId: resource.id,
+                    start: new Date(input.start),
+                    end: new Date(input.end),
+                    bufferAfterMs: input.buffer_after_minutes * 60_000,
+                    revision: input.revision,
+                    ...(input.source !== undefined ? { source: input.source } : {}),
+                };
+                const result = command.revision === 1
+                    ? await tenant.createExternalReservation(command)
+                    : await tenant.rescheduleExternalReservation(command);
+                if (!result.ok)
+                    throw applicationRefusal(result.code);
+                return { reservation: reservationOutput(result.reservation), replayed: result.idempotent };
+            }, WRITE);
+        },
+        async cancelReservation(context, input) {
+            return withTenant(store, context, async (tenant) => {
+                const result = await tenant.cancelExternalReservation({
+                    tenantRef: tenantOf(context),
+                    externalRef: input.reservation_ref,
+                    revision: input.revision,
+                });
+                if (!result.ok)
+                    throw applicationRefusal(result.code);
+                return { cancelled: result.cancelled, revision: result.revision };
+            }, WRITE);
+        },
+        async recordCoverage(context, input) {
+            return withTenant(store, context, async (tenant) => {
+                const resource = await requireResource(tenant, tenantOf(context), input.resource_id);
+                const result = await tenant.recordCalendarCoverage({
+                    tenantRef: tenantOf(context),
+                    resourceId: resource.id,
+                    source: input.source,
+                    window: interval(input),
+                    revision: input.revision,
+                });
+                if (!result.ok)
+                    throw applicationRefusal(result.code);
+                return { revision: result.revision, replayed: result.idempotent };
+            }, WRITE);
+        },
+        async listTenantEvents(context, input) {
+            const limit = input.limit;
+            const after = parseEventCursor(input.cursor);
+            return withTenant(store, context, async (tenant) => {
+                const resource = await requireResource(tenant, tenantOf(context), input.resource_id);
+                const { shown, next } = page(await tenant.listCalendarEvents({
+                    tenantRef: tenantOf(context),
+                    allOwners: true,
+                    resourceId: resource.id,
+                    window: interval(input),
+                    limit: limit + 1,
+                    ...(after ? { after } : {}),
+                }), limit);
+                return { events: shown.map(tenantEventOutput), next_cursor: next };
+            });
+        },
+        async getTenantEvent(context, input) {
+            const id = input.event_id;
+            if (!STORE_ID_PATTERN.test(id))
+                throw new SlotlockAgentOperationError('event_not_found', 404);
+            return withTenant(store, context, async (tenant) => {
+                const event = await tenant.getCalendarEventById({ tenantRef: tenantOf(context), eventId: id });
+                if (!event)
+                    throw new SlotlockAgentOperationError('event_not_found', 404);
+                return { event: tenantEventOutput(event) };
+            });
+        },
+        async cancelTenantEvent(context, input) {
+            const id = input.event_id;
+            const expectedResourceId = input.expected_resource_id;
+            // An id the store never issues names no event, and no event is on a resource it never issued.
+            if (!STORE_ID_PATTERN.test(id) ||
+                (expectedResourceId !== undefined && !STORE_ID_PATTERN.test(expectedResourceId))) {
+                throw new SlotlockAgentOperationError('event_not_found', 404);
+            }
+            return withTenant(store, context, async (tenant) => {
+                const result = await tenant.cancelCalendarEventById({
+                    tenantRef: tenantOf(context),
+                    eventId: id,
+                    idempotencyKey: applicationCommandKey(context, input.idempotency_key),
+                    expectedRevision: input.expected_revision,
+                    ...(expectedResourceId !== undefined ? { expectedResourceId } : {}),
+                });
+                if (!result.ok)
+                    throw applicationRefusal(result.code);
+                return {
+                    event_id: result.eventId,
+                    revision: result.revision,
+                    cancelled: true,
+                    replayed: result.idempotent,
+                };
+            }, WRITE);
+        },
+        async getTenant(context) {
+            return withTenant(store, context, async (tenant) => ({
+                tenant: {
+                    ref: tenantOf(context),
+                    suspended: await tenant.isTenantSuspended({ tenantRef: tenantOf(context) }),
+                },
+            }));
+        },
+        async eraseTenant(context, input) {
+            if (!tenantErasure)
+                throw new SlotlockAgentOperationError('tenant_erasure_disabled', 403);
+            // The reference, not a yes: a key of another tenant than the caller believes cannot erase it.
+            if (input.confirm_tenant_ref !== tenantOf(context)) {
+                throw new SlotlockAgentOperationError('invalid_confirmation', 400);
+            }
+            return withTenant(store, context, async (tenant) => {
+                // Read under the tenant's lock, which a suspension waits for: a suspended tenant's data is
+                // kept for its operator, who erases it (slotlock tenant erase) when they decide to.
+                if (await tenant.isTenantSuspended({ tenantRef: tenantOf(context) })) {
+                    throw new SlotlockAgentOperationError('tenant_suspended', 403);
+                }
+                const erased = await tenant.eraseTenant({ tenantRef: tenantOf(context) });
+                return { total: erased.total, rows: erased.rows };
+            }, WRITE);
+        },
+        async runMaintenance(context) {
+            assertActive(context);
+            try {
+                // A caller goes round again while `capped`; when to do so at once is the scheduler's.
+                const { rollPending: _, ...result } = await maintainSlotlockTenant(store, tenantOf(context), {
+                    batches,
+                    signal: context.signal,
+                });
+                return result;
+            }
+            catch (error) {
+                if (context.signal.aborted)
+                    throw new SlotlockAgentOperationError('request_aborted', 503);
+                throw error;
+            }
+        },
     };
 }