slotlock 0.6.2 → 0.7.0

package/rest-api.d.ts

@@ -6,9 +6,8 @@ export interface SlotlockRestRoute<Operation extends string = SlotlockAgentOpera
     path: string;
     operation: Operation;
     /**
-     * The store refusals the route can answer besides the ones every route can: 404 for a record
-     * that is missing or another tenant's, 409 for a conflict with what is stored (an overlap, a
-     * stale revision). The OpenAPI document declares them, so a generated client types them.
+     * Store refusals the route can answer beyond the common ones: 404 (missing or another tenant's)
+     * and 409 (a conflict with what is stored). Declared in OpenAPI so generated clients type them.
      */
     refusals?: readonly (404 | 409)[];
 }
@@ -20,15 +19,15 @@ export declare const SLOTLOCK_PROBLEM_DOCS = "https://slotlock.pylota.io/docs/ap
 /** A problem type's identifier: a tag URI (RFC 4151), stable, one per code, not a locator. */
 export declare function slotlockProblemType(code: string): string;
 /**
- * A REST refusal as RFC 9457 problem details (`application/problem+json`): `type` and `title` name
- * the problem, `code` is Slotlock's code, and `error.code` repeats it, the body every earlier
- * client reads. `extensions` add what the refusal is about, such as the interval an overlap refused.
+ * A REST refusal as RFC 9457 problem details: `type` and `title` name the problem, `code` is
+ * Slotlock's code, and `error.code` repeats it for older clients. `extensions` add context, such as
+ * the interval an overlap refused.
  */
 export declare function slotlockProblem(status: number, code: string, extensions?: Record<string, unknown>): Record<string, unknown>;
 /**
- * The Idempotency-Key header's value: a Structured Field String (RFC 9651, as
- * draft-ietf-httpapi-idempotency-key-header-08 defines it), or the bare token clients sent before.
- * `null` when it is a quoted string that does not parse.
+ * The Idempotency-Key header's value: a Structured Field String (RFC 9651, per
+ * draft-ietf-httpapi-idempotency-key-header-08), or a bare token as older clients send. `null` for
+ * a quoted string that does not parse.
  */
 export declare function parseIdempotencyKeyHeader(value: string): string | null;
 /** Where an operation's arguments come from. */
@@ -44,15 +43,15 @@ export type SlotlockRestMatch<Operation extends string = SlotlockAgentOperation>
     invalid: true;
 } | null;
 /**
- * The route for a method and path, the methods the path does have, or nothing. The first route in
- * `routes` that fits wins; no two of Slotlock's routes fit the same path and method (a test checks).
+ * The route for a method and path, the methods the path does have, or nothing. First fit wins; a
+ * test checks no two routes fit the same path and method.
  */
 export declare function matchSlotlockRestRoute<Operation extends string = SlotlockAgentOperation>(method: string, path: string, routes?: readonly SlotlockRestRoute<Operation>[]): SlotlockRestMatch<Operation>;
 type JsonSchema = Record<string, unknown>;
 /**
- * An operation's input from a query string: an array parameter repeats (`resource_ids=a&resource_ids=b`,
- * OpenAPI's default form style), every other parameter appears once. A parameter the operation does
- * not have, or a repeated one, is passed on as it is, so the operation's strict schema refuses it.
+ * An operation's input from a query string: array parameters repeat (OpenAPI's default form style),
+ * others appear once. Unknown or repeated parameters pass through so the strict schema refuses
+ * them.
  */
 export declare function restQueryInput(search: URLSearchParams, inputSchema: JsonSchema): Record<string, unknown>;
 /** One operation, as the OpenAPI document needs it. */
@@ -62,6 +61,8 @@ export interface SlotlockOpenApiOperation {
     description: string;
     inputSchema: JsonSchema;
     outputSchema: JsonSchema;
+    /** An operation's own scope: a tool's, or the partner API's (else the application scope). */
+    scope?: string;
 }
 /** The OpenAPI 3.1 document for the REST routes, from the operations' own schemas. */
 export declare function slotlockOpenApiDocument(args: {

package/rest-api.js

@@ -29,6 +29,12 @@ export const SLOTLOCK_REST_ROUTES = Object.freeze([
         operation: 'slotlock_release_slots',
         refusals: [409],
     },
+    {
+        method: 'POST',
+        path: '/v1/slot-holds/{hold_id}/confirm',
+        operation: 'slotlock_confirm_slot',
+        refusals: [404, 409],
+    },
     { method: 'GET', path: '/v1/events', operation: 'slotlock_list_events', refusals: [404] },
     { method: 'POST', path: '/v1/events', operation: 'slotlock_create_event', refusals: [404, 409] },
     { method: 'GET', path: '/v1/events/{event_id}', operation: 'slotlock_get_event', refusals: [404] },
@@ -44,6 +50,18 @@ export const SLOTLOCK_REST_ROUTES = Object.freeze([
         operation: 'slotlock_delete_event',
         refusals: [404, 409],
     },
+    {
+        method: 'POST',
+        path: '/v1/events/{event_id}/reschedule',
+        operation: 'slotlock_reschedule',
+        refusals: [404, 409],
+    },
+    {
+        method: 'POST',
+        path: '/v1/events/{event_id}/cancel',
+        operation: 'slotlock_cancel',
+        refusals: [404, 409],
+    },
 ]);
 /** The application operations' routes, served when the server has an application backend. */
 export const SLOTLOCK_APPLICATION_REST_ROUTES = Object.freeze(SLOTLOCK_APPLICATION_OPERATIONS.map(({ method, path, name }) => ({
@@ -65,6 +83,7 @@ const PROBLEM_TITLES = Object.freeze({
     revision_conflict: 'The revision is stale',
     confirmation_required: 'A person must confirm this write',
     rate_limited: 'Too many requests',
+    quota_exceeded: 'The monthly quota is used up',
     authentication_required: 'Authentication required',
     forbidden: 'Not allowed',
     invalid_arguments: 'The arguments are not valid',
@@ -86,9 +105,9 @@ const STATUS_TITLES = Object.freeze({
     503: 'Service Unavailable',
 });
 /**
- * A REST refusal as RFC 9457 problem details (`application/problem+json`): `type` and `title` name
- * the problem, `code` is Slotlock's code, and `error.code` repeats it, the body every earlier
- * client reads. `extensions` add what the refusal is about, such as the interval an overlap refused.
+ * A REST refusal as RFC 9457 problem details: `type` and `title` name the problem, `code` is
+ * Slotlock's code, and `error.code` repeats it for older clients. `extensions` add context, such as
+ * the interval an overlap refused.
  */
 export function slotlockProblem(status, code, extensions = {}) {
     return {
@@ -101,9 +120,9 @@ export function slotlockProblem(status, code, extensions = {}) {
     };
 }
 /**
- * The Idempotency-Key header's value: a Structured Field String (RFC 9651, as
- * draft-ietf-httpapi-idempotency-key-header-08 defines it), or the bare token clients sent before.
- * `null` when it is a quoted string that does not parse.
+ * The Idempotency-Key header's value: a Structured Field String (RFC 9651, per
+ * draft-ietf-httpapi-idempotency-key-header-08), or a bare token as older clients send. `null` for
+ * a quoted string that does not parse.
  */
 export function parseIdempotencyKeyHeader(value) {
     const trimmed = value.trim();
@@ -158,8 +177,8 @@ function matchPath(pattern, segments) {
     return params;
 }
 /**
- * The route for a method and path, the methods the path does have, or nothing. The first route in
- * `routes` that fits wins; no two of Slotlock's routes fit the same path and method (a test checks).
+ * The route for a method and path, the methods the path does have, or nothing. First fit wins; a
+ * test checks no two routes fit the same path and method.
  */
 export function matchSlotlockRestRoute(method, path, routes = SLOTLOCK_REST_ROUTES) {
     const segments = path.split('/');
@@ -209,9 +228,9 @@ function queryValue(value, schema) {
     return value;
 }
 /**
- * An operation's input from a query string: an array parameter repeats (`resource_ids=a&resource_ids=b`,
- * OpenAPI's default form style), every other parameter appears once. A parameter the operation does
- * not have, or a repeated one, is passed on as it is, so the operation's strict schema refuses it.
+ * An operation's input from a query string: array parameters repeat (OpenAPI's default form style),
+ * others appear once. Unknown or repeated parameters pass through so the strict schema refuses
+ * them.
  */
 export function restQueryInput(search, inputSchema) {
     const input = {};
@@ -330,15 +349,14 @@ export function slotlockOpenApiDocument(args) {
         if (!operation)
             throw new Error(`Slotlock REST route ${route.path} names no operation`);
         add(route, openApiOperation(route, operation, {
-            tag: 'Application',
-            scope: SLOTLOCK_APPLICATION_SCOPE,
+            tag: operation.scope === 'partner' ? 'Partner' : 'Application',
+            scope: operation.scope === 'partner' ? 'partner' : SLOTLOCK_APPLICATION_SCOPE,
             responses: {
                 '400': ERROR_RESPONSE,
                 '401': ERROR_RESPONSE,
                 '403': ERROR_RESPONSE,
                 '404': ERROR_RESPONSE,
                 ...(route.method === 'GET' ? {} : { '409': ERROR_RESPONSE }),
-                // A change cursor past the feed's retention.
                 ...(route.operation === 'slotlock_list_changes' ? { '410': ERROR_RESPONSE } : {}),
                 '429': ERROR_RESPONSE,
                 default: ERROR_RESPONSE,
@@ -379,6 +397,10 @@ export function slotlockOpenApiDocument(args) {
                         name: 'Application',
                         description: 'What the application around the agents does. Needs the admin scope; never offered to agents.',
                     },
+                    {
+                        name: 'Partner',
+                        description: "What a partner reselling Slotlock does for its own users' accounts. Needs a partner key (`slk_partner_…`), whose `partner` scope reaches nothing else.",
+                    },
                 ]
                 : []),
         ],
@@ -388,7 +410,7 @@ export function slotlockOpenApiDocument(args) {
                 bearer: {
                     type: 'http',
                     scheme: 'bearer',
-                    description: 'A Slotlock API key (`slk_…`) or the server token. `x-slotlock-scope` on each operation names the scope it needs.',
+                    description: 'A Slotlock API key (`slk_…`, or `slk_test_…` for a test environment), a partner key (`slk_partner_…`; with a `Slotlock-Account` field naming one of its accounts, where its contract allows, it acts as that account) or the server token. `x-slotlock-scope` on each operation names the scope it needs.',
                 },
             },
             schemas: {
@@ -404,6 +426,48 @@ export function slotlockOpenApiDocument(args) {
                         resource_id: { type: 'string', description: 'An overlap: the resource it refused.' },
                         start: { type: 'string', description: 'An overlap: the start it refused.' },
                         end: { type: 'string', description: 'An overlap: the end it refused.' },
+                        busy_start: {
+                            type: 'string',
+                            description: 'An overlap: when the booking in the way makes the time busy, from (buffers included).',
+                        },
+                        busy_end: { type: 'string', description: 'An overlap: until when that booking makes it busy.' },
+                        conflicting_hold_id: {
+                            type: 'string',
+                            description: 'An overlap with a hold of your own: its id, to book or release it.',
+                        },
+                        conflicting_event_id: {
+                            type: 'string',
+                            description: 'An overlap with an event of your own: its id, to move or cancel it.',
+                        },
+                        approval_id: {
+                            type: 'string',
+                            description: 'approval_pending, approval_declined or approval_expired: the approval a policy made of the booking. Retry with the same idempotency_key to learn how it was decided.',
+                        },
+                        policy_ref: { type: 'string', description: 'An approval refusal: the policy that applies.' },
+                        expires_at: {
+                            type: 'string',
+                            description: 'approval_pending or approval_required: until when a person may decide (the time is held until then).',
+                        },
+                        reason: { type: 'string', description: 'approval_declined: what the person who declined it said, if anything.' },
+                        alternatives: {
+                            type: 'array',
+                            maxItems: 3,
+                            description: 'A refusal another time can answer (overlap, pool_full, a booking rule): the earliest free times of the same length, within 7 days of the time asked for, checked as slotlock_find_available_slots checks them. Suggestions, not holds. Empty when none was found.',
+                            items: {
+                                type: 'object',
+                                required: ['resource_id', 'start', 'end'],
+                                properties: {
+                                    resource_id: { type: 'string' },
+                                    start: { type: 'string', format: 'date-time' },
+                                    end: { type: 'string', format: 'date-time' },
+                                    resource_ids: {
+                                        type: 'array',
+                                        items: { type: 'string' },
+                                        description: 'A bundle or pool booking: the resources free together then.',
+                                    },
+                                },
+                            },
+                        },
                         issues: {
                             type: 'array',
                             description: '`invalid_arguments` from argument validation: each field it refused (at most 20), by its path in the arguments, outermost first; `[]` is the arguments as a whole.',

package/rules.d.ts

@@ -13,15 +13,14 @@ export declare function invalidWindowError(message?: string): Error & {
     code: 'invalid_window';
 };
 /**
- * Refuse (`invalid_window`) a search window longer than SLOTLOCK_CALENDAR_HORIZON_DAYS. Expansion
- * is synchronous: fifty daily rules over a century are close to two million windows.
+ * Refuse (`invalid_window`) a search window longer than SLOTLOCK_CALENDAR_HORIZON_DAYS: expansion
+ * is synchronous and grows with the window.
  */
 export declare function assertBoundedSearchWindow(window: Interval): void;
 /**
- * Expand availability rules to concrete, merged, sorted UTC windows clipped to `searchWindow`.
- * Unsupported or unparseable rules contribute nothing rather than throwing: one bad rule must not
- * blank the whole calendar — and must never manufacture availability the rule doesn't mean.
- * Callers should validate rules at write time; this read-path skip remains the fail-closed backstop.
- * A search window longer than SLOTLOCK_CALENDAR_HORIZON_DAYS is refused (`invalid_window`).
+ * Expand availability rules to merged, sorted UTC windows clipped to `searchWindow`. Unsupported or
+ * unparseable rules contribute nothing rather than throwing: one bad rule must neither blank the
+ * calendar nor manufacture availability. Validate at write time; this is the fail-closed backstop.
+ * A window over SLOTLOCK_CALENDAR_HORIZON_DAYS is refused (`invalid_window`).
  */
 export declare function expandRules(rules: WeeklyAvailabilityRule[], searchWindow: Interval, timezone?: string): Interval[];

package/rules.js

@@ -21,15 +21,14 @@ export function invalidWindowError(message = 'Slotlock window must contain two f
     return Object.assign(new Error(message), { code: 'invalid_window' });
 }
 /**
- * Refuse (`invalid_window`) a search window longer than SLOTLOCK_CALENDAR_HORIZON_DAYS. Expansion
- * is synchronous: fifty daily rules over a century are close to two million windows.
+ * Refuse (`invalid_window`) a search window longer than SLOTLOCK_CALENDAR_HORIZON_DAYS: expansion
+ * is synchronous and grows with the window.
  */
 export function assertBoundedSearchWindow(window) {
     if (window.end.getTime() - window.start.getTime() > MAX_SEARCH_WINDOW_MS) {
         throw invalidWindowError(`Slotlock searches a window of at most ${SLOTLOCK_CALENDAR_HORIZON_DAYS} days at once`);
     }
 }
-/** UTC midnight of the day containing `d`. */
 function utcDayFloor(d) {
     return new Date(Math.floor(d.getTime() / DAY_MS) * DAY_MS);
 }
@@ -38,15 +37,15 @@ const WEEKDAY = /^(?:MO|TU|WE|TH|FR|SA|SU)$/;
 const ABSOLUTE_UNTIL = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z$/;
 /**
  * Whether `until` is an absolute UNTIL naming a real instant. rrule reads it with Date.UTC, which
- * carries an overflowing field into the next unit: 31 February became 3 March, and the rule stayed
- * bookable after the day it was written to end. A leap second (60) is real (RFC 5545 3.3.12).
+ * carries overflow into the next unit (31 February becomes 3 March). A leap second (60) is real
+ * (RFC 5545 3.3.12).
  */
 function isRealUntil(until) {
     const match = ABSOLUTE_UNTIL.exec(until);
     if (!match)
         return false;
     const [, year, month, day, hour, minute, second] = match;
-    // Set without overflow checks, the date reads back differently when any part overflowed.
+    // Set without overflow checks: the date reads back differently when any part overflowed.
     const date = new Date(0);
     date.setUTCFullYear(Number(year), Number(month) - 1, Number(day));
     return (date.toISOString().startsWith(`${year}-${month}-${day}T`) &&
@@ -55,10 +54,10 @@ function isRealUntil(until) {
         Number(second) <= 60);
 }
 /**
- * Whether `rrule` is written in SPEC.md's subset: `FREQ=WEEKLY`, a `BYDAY` of plain weekdays,
- * optionally `INTERVAL=1` and an absolute `UNTIL`, each once, in any order, and nothing else.
- * Checked before rrule parses it: rrule honours a DTSTART's TZID (Monday came out as Sunday) and
- * the first BYDAY of two, and BYHOUR/BYMINUTE/BYSECOND multiply occurrences (one rule took 0.7 s).
+ * Whether `rrule` is in SPEC.md's subset: `FREQ=WEEKLY`, a `BYDAY` of plain weekdays, optionally
+ * `INTERVAL=1` and an absolute `UNTIL`, each once, in any order. Checked before rrule parses it:
+ * rrule honours a DTSTART's TZID, takes the first of two BYDAYs, and lets BYHOUR/BYMINUTE/BYSECOND
+ * multiply occurrences.
  */
 function isWeeklySubset(rrule) {
     const parts = new Map();
@@ -76,14 +75,12 @@ function isWeeklySubset(rrule) {
         (until === undefined || isRealUntil(until)));
 }
 /**
- * The spike honours exactly the weekly-cadence subset it can answer DETERMINISTICALLY. Anything
- * else is refused (skipped = fails closed to "not bookable"), never guessed:
- * - freq must be WEEKLY — a freq-less-but-parseable string ('', 'COUNT=5') otherwise becomes a
- *   default-YEARLY rule anchored at the query date: phantom availability at every search start.
- * - COUNT is unanswerable without an authored DTSTART — re-anchoring makes "first N occurrences"
- *   restart on every query.
- * - INTERVAL>1 parity depends on the anchor — re-anchoring makes biweekly availability flip with
- *   the query date. (UNTIL is absolute and expands correctly, so it stays allowed.)
+ * Only the weekly subset that can be answered deterministically; anything else fails closed to not
+ * bookable:
+ * - freq must be WEEKLY: a freq-less string otherwise becomes a YEARLY rule anchored at the query
+ *   date;
+ * - COUNT needs an authored DTSTART: re-anchoring restarts it on every query;
+ * - INTERVAL>1 parity depends on the anchor. UNTIL is absolute and stays allowed.
  */
 function isSupportedRule(parsed) {
     if (parsed.freq !== RRule.WEEKLY)
@@ -92,8 +89,8 @@ function isSupportedRule(parsed) {
         return false;
     if (parsed.interval !== undefined && parsed.interval !== 1)
         return false;
-    // BYDAY-less WEEKLY inherits its weekday from the re-anchored DTSTART — the answer wobbles
-    // with the query date (and, before this gate, flipped between the UTC and zoned paths).
+    // BYDAY-less WEEKLY would take its weekday from the re-anchored DTSTART, varying with the query
+    // date.
     const byweekday = parsed.byweekday;
     if (byweekday === undefined || byweekday === null)
         return false;
@@ -102,16 +99,14 @@ function isSupportedRule(parsed) {
     return true;
 }
 /**
- * Expand availability rules to concrete, merged, sorted UTC windows clipped to `searchWindow`.
- * Unsupported or unparseable rules contribute nothing rather than throwing: one bad rule must not
- * blank the whole calendar — and must never manufacture availability the rule doesn't mean.
- * Callers should validate rules at write time; this read-path skip remains the fail-closed backstop.
- * A search window longer than SLOTLOCK_CALENDAR_HORIZON_DAYS is refused (`invalid_window`).
+ * Expand availability rules to merged, sorted UTC windows clipped to `searchWindow`. Unsupported or
+ * unparseable rules contribute nothing rather than throwing: one bad rule must neither blank the
+ * calendar nor manufacture availability. Validate at write time; this is the fail-closed backstop.
+ * A window over SLOTLOCK_CALENDAR_HORIZON_DAYS is refused (`invalid_window`).
  */
 export function expandRules(rules, searchWindow, timezone) {
     assertBoundedSearchWindow(searchWindow);
-    // Validate ONCE, loudly: a typo'd zone must never silently fall back to UTC math — that
-    // would manufacture availability shifted by the zone offset. 'UTC'/omitted = spike path.
+    // Validate once: a typo'd zone must never silently fall back to UTC and shift availability.
     const converter = timezone !== undefined ? createTimeZoneConverter(timezone) : null;
     const windows = [];
     for (const rule of rules) {
@@ -125,9 +120,8 @@ export function expandRules(rules, searchWindow, timezone) {
         }
         let rrule;
         let absoluteUntil = null;
-        // A window can START days before the search window and still reach into it — scan the
-        // recurrence back far enough for the longest window this rule can produce (multi-day
-        // windows like "Mon 00:00 + 3 days" are legal; a fixed one-day margin silently lost them).
+        // A window can start days before the search window and still reach into it: scan back as far as
+        // the longest window this rule can produce.
         const backScanDays = Math.ceil((rule.startMinutes + rule.durationMinutes) / (24 * 60));
         const scanStart = utcDayFloor(new Date(searchWindow.start.getTime() - backScanDays * DAY_MS));
         if (typeof rule.rrule !== 'string' || !isWeeklySubset(rule.rrule))
@@ -136,10 +130,8 @@ export function expandRules(rules, searchWindow, timezone) {
             const parsed = RRule.parseString(rule.rrule);
             if (!isSupportedRule(parsed))
                 continue;
-            // rrule's stamps are days, not window starts: a UTC midnight, or under a zone a LOCAL date
-            // read as UTC. Left to rrule, UNTIL would keep a window that starts after it on its own day,
-            // and under a zone east of UTC drop one that starts before it. Each window's real start is
-            // compared with UNTIL instead (below), with or without a zone, so the two paths agree.
+            // rrule's stamps are days, not window starts, so its UNTIL handling is wrong at both ends;
+            // each window's real start is compared with UNTIL below instead.
             if (parsed.until) {
                 absoluteUntil = parsed.until;
                 parsed.until = null;
@@ -150,19 +142,16 @@ export function expandRules(rules, searchWindow, timezone) {
         catch {
             continue;
         }
-        // Under a zone, a LOCAL day whose UTC stamp lies past the window end can still start
-        // before it (east zones read a stamp's wall date up to 14h earlier) — scan one day over
-        // and let clipping discard the overshoot.
+        // Under a zone a local day whose UTC stamp is past the window end can still start before it
+        // (east zones are up to 14h ahead): scan one day over and let clipping discard the overshoot.
         const scanEnd = converter ? new Date(searchWindow.end.getTime() + DAY_MS) : searchWindow.end;
         const days = rrule.between(scanStart, scanEnd, true);
         for (const day of days) {
             let start;
             let end;
             if (converter) {
-                // The stamp's Y/M/D is the LOCAL calendar date; start and end are both wall-clock. An
-                // edge the clocks skip stands where the skipped hour ends: moved on by the gap, as RFC 5545
-                // reads a time, [02:30, 03:30) gave nothing although 03:00-03:30 exists, and [02:00,
-                // 02:30) gave 03:00-03:30, which it never names.
+                // The stamp's Y/M/D is the local date; start and end are wall-clock. An edge the clocks
+                // skip stands where the skipped hour ends, so the window holds only wall times that exist.
                 const wallDay = Date.UTC(day.getUTCFullYear(), day.getUTCMonth(), day.getUTCDate());
                 start = converter.wallFrameToUtc(wallDay + rule.startMinutes * MINUTE_MS, { gap: 'end' });
                 end = converter.wallFrameToUtc(wallDay + (rule.startMinutes + rule.durationMinutes) * MINUTE_MS, { gap: 'end' });
@@ -176,7 +165,6 @@ export function expandRules(rules, searchWindow, timezone) {
             }
             if (absoluteUntil && start.getTime() > absoluteUntil.getTime())
                 continue;
-            // Clip to the search window; drop windows that miss it entirely.
             const clippedStart = start.getTime() < searchWindow.start.getTime() ? searchWindow.start : start;
             const clippedEnd = end.getTime() > searchWindow.end.getTime() ? searchWindow.end : end;
             if (clippedStart.getTime() < clippedEnd.getTime()) {

package/sandbox.d.ts

@@ -0,0 +1,70 @@
+import { type SlotlockAgentCalendarBackend } from './agent-server.js';
+import { type SlotlockMaintenanceResult } from './maintenance.js';
+import type { SlotlockStore } from './store.js';
+export declare const SLOTLOCK_SANDBOX_SCENARIOS: readonly ["car-rental", "clinic", "desks"];
+export type SlotlockSandboxScenario = (typeof SLOTLOCK_SANDBOX_SCENARIOS)[number];
+/** Agents one race runs at most, so a race stays a test of the server and not a load on it. */
+export declare const SLOTLOCK_SANDBOX_MAX_RACERS = 200;
+/** Refused outside a test environment. */
+export declare class SlotlockSandboxError extends Error {
+    readonly code: 'sandbox_test_only' | 'sandbox_not_empty';
+    constructor(code: 'sandbox_test_only' | 'sandbox_not_empty', message: string);
+}
+export interface SlotlockSandboxSeedResult {
+    scenario: SlotlockSandboxScenario;
+    resources: number;
+    locations: number;
+    groups: number;
+    pools: number;
+    bookings: number;
+}
+/**
+ * Fill an empty test environment with a scenario, in one transaction: its locations, groups,
+ * resources (with profiles, pools and a composite where it has one), their hours and booking
+ * rules, and a few bookings tomorrow. Refused (`sandbox_not_empty`) where it has resources already:
+ * reset it first.
+ */
+export declare function seedSlotlockSandbox(store: SlotlockStore, tenantRef: string, scenario: SlotlockSandboxScenario, options?: {
+    now?: Date;
+}): Promise<SlotlockSandboxSeedResult>;
+/** Empty a test environment: what seeding made, and every booking since. Keys, webhooks and plan stay. */
+export declare function resetSlotlockSandbox(store: SlotlockStore, tenantRef: string): Promise<Record<string, number>>;
+export interface SlotlockSandboxFastForwardResult {
+    minutes: number;
+    /** Holds (a waitlist offer's and an approval's among them) and approvals that lapsed now. */
+    holds: number;
+    approvals: number;
+    /** The maintenance pass that then reaped them, as it would have. */
+    maintenance: SlotlockMaintenanceResult;
+}
+/**
+ * Move a test environment's waiting forward: what would lapse within `minutes` lapses now, then a
+ * maintenance pass reaps it as it would have (holds released, waitlist offers passed on, approvals
+ * expired). Bookings and events keep their times; no-shows and series rolls follow the real clock.
+ */
+export declare function fastForwardSlotlockSandbox(store: SlotlockStore, tenantRef: string, minutes: number): Promise<SlotlockSandboxFastForwardResult>;
+export interface SlotlockSandboxRaceResult {
+    agents: number;
+    booked: number;
+    /** Refusals by code. */
+    refused: Record<string, number>;
+    /** Refusals that came with alternatives. */
+    withAlternatives: number;
+    serverErrors: number;
+    p50Ms: number;
+    p99Ms: number;
+    maxMs: number;
+}
+/**
+ * Race `agents` agents (2-200), each its own principal, for one time on one resource of a test
+ * environment, through the same operation boundary MCP, A2A and REST use: who booked, who was
+ * refused and why, and how long each answer took.
+ */
+export declare function raceSlotlockSandbox(params: {
+    backend: SlotlockAgentCalendarBackend;
+    tenantRef: string;
+    resourceId: string;
+    start: Date;
+    end: Date;
+    agents?: number;
+}): Promise<SlotlockSandboxRaceResult>;