slotlock 0.1.1 → 0.3.0

package/rest-api.d.ts

@@ -1,23 +1,31 @@
 import type { SlotlockAgentOperation } from './agent-server.js';
-export interface SlotlockRestRoute {
-    method: 'GET' | 'POST' | 'PATCH' | 'DELETE';
-    /** Relative to the server's base URL; `{event_id}` is one path segment. */
+import { type SlotlockApplicationOperation } from './application-api.js';
+export interface SlotlockRestRoute<Operation extends string = SlotlockAgentOperation> {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /** Relative to the server's base URL; `{name}` is one path segment. */
     path: string;
-    operation: SlotlockAgentOperation;
+    operation: Operation;
 }
 export declare const SLOTLOCK_REST_ROUTES: readonly SlotlockRestRoute[];
+/** The application operations' routes, served when the server has an application backend. */
+export declare const SLOTLOCK_APPLICATION_REST_ROUTES: readonly SlotlockRestRoute<SlotlockApplicationOperation>[];
 /** Where an operation's arguments come from. */
-export declare function restInputFromBody(route: SlotlockRestRoute): boolean;
-export type SlotlockRestMatch = {
-    route: SlotlockRestRoute;
+export declare function restInputFromBody(route: {
+    method: string;
+}): boolean;
+export type SlotlockRestMatch<Operation extends string = SlotlockAgentOperation> = {
+    route: SlotlockRestRoute<Operation>;
     params: Record<string, string>;
 } | {
     allow: readonly string[];
 } | {
     invalid: true;
 } | null;
-/** The route for a method and path, the methods the path does have, or nothing. */
-export declare function matchSlotlockRestRoute(method: string, path: string): SlotlockRestMatch;
+/**
+ * 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).
+ */
+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`,
@@ -25,16 +33,23 @@ type JsonSchema = Record<string, unknown>;
  * not have, or a repeated one, is passed on as it is, so the operation's strict schema refuses it.
  */
 export declare function restQueryInput(search: URLSearchParams, inputSchema: JsonSchema): Record<string, unknown>;
-/** The OpenAPI 3.1 document for the REST routes, from the tools' own schemas. */
+/** One operation, as the OpenAPI document needs it. */
+export interface SlotlockOpenApiOperation {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: JsonSchema;
+    outputSchema: JsonSchema;
+}
+/** The OpenAPI 3.1 document for the REST routes, from the operations' own schemas. */
 export declare function slotlockOpenApiDocument(args: {
-    publicBaseUrl: string;
+    /** Where the server is; without it, the `{baseUrl}` server variable. */
+    publicBaseUrl?: string;
     version: string;
-    tools: readonly {
-        name: string;
-        title: string;
-        description: string;
-        inputSchema: JsonSchema;
-        outputSchema: JsonSchema;
-    }[];
+    tools: readonly (SlotlockOpenApiOperation & {
+        scope?: string;
+    })[];
+    /** The application operations, when the server serves them. */
+    application?: readonly SlotlockOpenApiOperation[];
 }): Record<string, unknown>;
 export {};

package/rest-api.js

@@ -1,3 +1,4 @@
+import { SLOTLOCK_APPLICATION_OPERATIONS, SLOTLOCK_APPLICATION_SCOPE, } from './application-api.js';
 export const SLOTLOCK_REST_ROUTES = Object.freeze([
     { method: 'GET', path: '/v1/resources', operation: 'slotlock_list_resources' },
     { method: 'GET', path: '/v1/free-busy', operation: 'slotlock_get_free_busy' },
@@ -8,9 +9,15 @@ export const SLOTLOCK_REST_ROUTES = Object.freeze([
     { method: 'PATCH', path: '/v1/events/{event_id}', operation: 'slotlock_update_event' },
     { method: 'DELETE', path: '/v1/events/{event_id}', operation: 'slotlock_delete_event' },
 ]);
+/** 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 }) => ({
+    method,
+    path,
+    operation: name,
+})));
 /** Where an operation's arguments come from. */
 export function restInputFromBody(route) {
-    return route.method === 'POST' || route.method === 'PATCH';
+    return route.method === 'POST' || route.method === 'PUT' || route.method === 'PATCH';
 }
 /** The path's parameters when it fits `pattern`, else `null`. */
 function matchPath(pattern, segments) {
@@ -34,17 +41,21 @@ function matchPath(pattern, segments) {
     }
     return params;
 }
-/** The route for a method and path, the methods the path does have, or nothing. */
-export function matchSlotlockRestRoute(method, path) {
+/**
+ * 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).
+ */
+export function matchSlotlockRestRoute(method, path, routes = SLOTLOCK_REST_ROUTES) {
     const segments = path.split('/');
     const allow = [];
     let hit = null;
-    for (const route of SLOTLOCK_REST_ROUTES) {
+    for (const route of routes) {
         const params = matchPath(route.path, segments);
         if (!params)
             continue;
-        allow.push(route.method);
-        if (route.method === method)
+        if (!allow.includes(route.method))
+            allow.push(route.method);
+        if (route.method === method && !hit)
             hit = { route, params };
     }
     if (!hit)
@@ -103,85 +114,152 @@ export function restQueryInput(search, inputSchema) {
     return input;
 }
 const ERROR_RESPONSE = { $ref: '#/components/responses/Error' };
-/** The OpenAPI 3.1 document for the REST routes, from the tools' own schemas. */
+/** The OpenAPI operation object for one route. */
+function openApiOperation(route, operation, extra) {
+    const pathNames = [...route.path.matchAll(/\{(\w+)\}/g)].map((match) => match[1]);
+    const fields = properties(operation.inputSchema);
+    const required = new Set((operation.inputSchema.required ?? []));
+    const parameters = pathNames.map((name) => ({
+        name,
+        in: 'path',
+        required: true,
+        schema: fields[name] ?? { type: 'string' },
+    }));
+    const result = {
+        operationId: operation.name,
+        summary: operation.title,
+        description: operation.description,
+        tags: [extra.tag],
+        'x-slotlock-scope': extra.scope,
+    };
+    if (restInputFromBody(route)) {
+        const bodyFields = Object.fromEntries(Object.entries(fields).filter(([name]) => !pathNames.includes(name)));
+        result.requestBody = {
+            required: true,
+            content: {
+                'application/json': {
+                    schema: pathNames.length === 0
+                        ? operation.inputSchema
+                        : {
+                            ...operation.inputSchema,
+                            properties: bodyFields,
+                            required: [...required].filter((name) => !pathNames.includes(name)),
+                        },
+                },
+            },
+        };
+    }
+    else {
+        for (const [name, schema] of Object.entries(fields)) {
+            if (pathNames.includes(name))
+                continue;
+            parameters.push({ name, in: 'query', required: required.has(name), schema });
+        }
+    }
+    // An application write that keeps a retry identity also takes it as the Idempotency-Key header.
+    if (extra.tag === 'Application' && fields.idempotency_key !== undefined) {
+        parameters.push({
+            name: 'Idempotency-Key',
+            in: 'header',
+            required: false,
+            description: 'Stands in for idempotency_key, where HTTP clients put a retry identity; when both are sent they must be equal.',
+            schema: { type: 'string', minLength: 1, maxLength: 500 },
+        });
+    }
+    if (parameters.length > 0)
+        result.parameters = parameters;
+    result.responses = {
+        '200': {
+            description: 'The operation ran.',
+            content: { 'application/json': { schema: operation.outputSchema } },
+        },
+        ...extra.responses,
+    };
+    return result;
+}
+/** The OpenAPI 3.1 document for the REST routes, from the operations' own schemas. */
 export function slotlockOpenApiDocument(args) {
     const paths = {};
+    const add = (route, operation) => {
+        paths[route.path] = { ...paths[route.path], [route.method.toLowerCase()]: operation };
+    };
     for (const route of SLOTLOCK_REST_ROUTES) {
         const tool = args.tools.find((candidate) => candidate.name === route.operation);
         if (!tool)
             throw new Error(`Slotlock REST route ${route.path} names no tool`);
-        const pathNames = [...route.path.matchAll(/\{(\w+)\}/g)].map((match) => match[1]);
-        const fields = properties(tool.inputSchema);
-        const required = new Set((tool.inputSchema.required ?? []));
-        const parameters = pathNames.map((name) => ({
-            name,
-            in: 'path',
-            required: true,
-            schema: fields[name] ?? { type: 'string' },
+        add(route, openApiOperation(route, tool, {
+            tag: 'Agent tools',
+            scope: tool.scope ?? (route.method === 'GET' ? 'read' : 'write'),
+            responses: {
+                '400': ERROR_RESPONSE,
+                '401': ERROR_RESPONSE,
+                '403': ERROR_RESPONSE,
+                ...(route.method === 'GET' ? {} : { '428': ERROR_RESPONSE }),
+                '429': ERROR_RESPONSE,
+                default: ERROR_RESPONSE,
+            },
         }));
-        const operation = {
-            operationId: tool.name,
-            summary: tool.title,
-            description: tool.description,
-        };
-        if (restInputFromBody(route)) {
-            const bodyFields = Object.fromEntries(Object.entries(fields).filter(([name]) => !pathNames.includes(name)));
-            operation.requestBody = {
-                required: true,
-                content: {
-                    'application/json': {
-                        schema: pathNames.length === 0
-                            ? tool.inputSchema
-                            : {
-                                ...tool.inputSchema,
-                                properties: bodyFields,
-                                required: [...required].filter((name) => !pathNames.includes(name)),
-                            },
-                    },
-                },
-            };
-        }
-        else {
-            for (const [name, schema] of Object.entries(fields)) {
-                if (pathNames.includes(name))
-                    continue;
-                parameters.push({ name, in: 'query', required: required.has(name), schema });
-            }
-        }
-        if (parameters.length > 0)
-            operation.parameters = parameters;
-        operation.responses = {
-            '200': {
-                description: 'The operation ran.',
-                content: { 'application/json': { schema: tool.outputSchema } },
+    }
+    for (const route of args.application ? SLOTLOCK_APPLICATION_REST_ROUTES : []) {
+        const operation = args.application?.find((candidate) => candidate.name === route.operation);
+        if (!operation)
+            throw new Error(`Slotlock REST route ${route.path} names no operation`);
+        add(route, openApiOperation(route, operation, {
+            tag: 'Application',
+            scope: SLOTLOCK_APPLICATION_SCOPE,
+            responses: {
+                '400': ERROR_RESPONSE,
+                '401': ERROR_RESPONSE,
+                '403': ERROR_RESPONSE,
+                '404': ERROR_RESPONSE,
+                ...(route.method === 'GET' ? {} : { '409': ERROR_RESPONSE }),
+                '429': ERROR_RESPONSE,
+                default: ERROR_RESPONSE,
             },
-            '400': ERROR_RESPONSE,
-            '401': ERROR_RESPONSE,
-            '403': ERROR_RESPONSE,
-            ...(route.method === 'GET' ? {} : { '428': ERROR_RESPONSE }),
-            '429': ERROR_RESPONSE,
-            default: ERROR_RESPONSE,
-        };
-        paths[route.path] = { ...paths[route.path], [route.method.toLowerCase()]: operation };
+        }));
     }
     return {
         openapi: '3.1.0',
         info: {
             title: 'Slotlock',
             version: args.version,
-            description: 'Calendars agents cannot double-book. Each operation is one of the Slotlock MCP tools; ' +
-                'an error is `{"error":{"code":…}}`, and a write that waits for a person answers 428 ' +
-                '`confirmation_required`.',
+            description: 'Calendars agents cannot double-book. The "Agent tools" operations are the Slotlock MCP tools; ' +
+                'the "Application" operations (resources, bookable hours, holds, reservations, coverage and ' +
+                'maintenance) need an API key with the admin scope. An error is `{"error":{"code":…}}`, and ' +
+                'a write that waits for a person answers 428 `confirmation_required`.',
         },
-        servers: [{ url: args.publicBaseUrl }],
+        servers: [
+            args.publicBaseUrl !== undefined
+                ? { url: args.publicBaseUrl }
+                : {
+                    url: '{baseUrl}',
+                    variables: {
+                        baseUrl: {
+                            default: 'http://localhost:8080',
+                            description: "The server's public URL (SLOTLOCK_PUBLIC_URL), without a trailing slash.",
+                        },
+                    },
+                },
+        ],
         security: [{ bearer: [] }],
+        tags: [
+            { name: 'Agent tools', description: 'What an agent does: the MCP tools and A2A skills.' },
+            ...(args.application
+                ? [
+                    {
+                        name: 'Application',
+                        description: 'What the application around the agents does. Needs the admin scope; never offered to agents.',
+                    },
+                ]
+                : []),
+        ],
         paths,
         components: {
             securitySchemes: {
                 bearer: {
                     type: 'http',
                     scheme: 'bearer',
-                    description: 'A Slotlock API key (`slk_…`) or the server token.',
+                    description: 'A Slotlock API key (`slk_…`) or the server token. `x-slotlock-scope` on each operation names the scope it needs.',
                 },
             },
             schemas: {

package/rules.d.ts

@@ -1,8 +1,27 @@
 import type { Interval, WeeklyAvailabilityRule } from './types.js';
+/**
+ * The longest window Slotlock reads or searches at once, in days: free/busy, the rolling event
+ * horizon, a recurring event's materialization and a search for the next slot all stop here.
+ */
+export declare const SLOTLOCK_CALENDAR_HORIZON_DAYS = 367;
+/**
+ * The longest window one availability rule may open, in minutes: a week. Expansion scans back as
+ * many days as a rule lasts, so a longer one is skipped, as the hours validator refuses it.
+ */
+export declare const SLOTLOCK_MAX_RULE_DURATION_MINUTES = 10080;
+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.
+ */
+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`).
  */
 export declare function expandRules(rules: WeeklyAvailabilityRule[], searchWindow: Interval, timezone?: string): Interval[];

package/rules.js

@@ -6,6 +6,29 @@ import { mergeIntervals } from './engine.js';
 import { createTimeZoneConverter } from './timezone.js';
 const DAY_MS = 24 * 60 * 60 * 1000;
 const MINUTE_MS = 60 * 1000;
+/**
+ * The longest window Slotlock reads or searches at once, in days: free/busy, the rolling event
+ * horizon, a recurring event's materialization and a search for the next slot all stop here.
+ */
+export const SLOTLOCK_CALENDAR_HORIZON_DAYS = 367;
+const MAX_SEARCH_WINDOW_MS = SLOTLOCK_CALENDAR_HORIZON_DAYS * DAY_MS;
+/**
+ * The longest window one availability rule may open, in minutes: a week. Expansion scans back as
+ * many days as a rule lasts, so a longer one is skipped, as the hours validator refuses it.
+ */
+export const SLOTLOCK_MAX_RULE_DURATION_MINUTES = 10_080;
+export function invalidWindowError(message = 'Slotlock window must contain two finite dates with end > start') {
+    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.
+ */
+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);
@@ -83,8 +106,10 @@ function isSupportedRule(parsed) {
  * 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`).
  */
 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.
     const converter = timezone !== undefined ? createTimeZoneConverter(timezone) : null;
@@ -94,7 +119,8 @@ export function expandRules(rules, searchWindow, timezone) {
             rule.startMinutes < 0 ||
             rule.startMinutes > 1439 ||
             !Number.isInteger(rule.durationMinutes) ||
-            rule.durationMinutes <= 0) {
+            rule.durationMinutes <= 0 ||
+            rule.durationMinutes > SLOTLOCK_MAX_RULE_DURATION_MINUTES) {
             continue;
         }
         let rrule;
@@ -110,9 +136,11 @@ export function expandRules(rules, searchWindow, timezone) {
             const parsed = RRule.parseString(rule.rrule);
             if (!isSupportedRule(parsed))
                 continue;
-            // rrule operates on pseudo-UTC local-date stamps. In zoned mode its UNTIL comparison must
-            // happen after wall time becomes a real instant or east-of-UTC occurrences disappear early.
-            if (converter && parsed.until) {
+            // 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.
+            if (parsed.until) {
                 absoluteUntil = parsed.until;
                 parsed.until = null;
             }
@@ -131,10 +159,13 @@ export function expandRules(rules, searchWindow, timezone) {
             let start;
             let end;
             if (converter) {
-                // The stamp's Y/M/D is the LOCAL calendar date; start and end are both wall-clock.
+                // 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.
                 const wallDay = Date.UTC(day.getUTCFullYear(), day.getUTCMonth(), day.getUTCDate());
-                start = converter.wallFrameToUtc(wallDay + rule.startMinutes * MINUTE_MS);
-                end = converter.wallFrameToUtc(wallDay + (rule.startMinutes + rule.durationMinutes) * MINUTE_MS);
+                start = converter.wallFrameToUtc(wallDay + rule.startMinutes * MINUTE_MS, { gap: 'end' });
+                end = converter.wallFrameToUtc(wallDay + (rule.startMinutes + rule.durationMinutes) * MINUTE_MS, { gap: 'end' });
                 if (end.getTime() <= start.getTime())
                     continue;
             }

package/self-host.d.ts

@@ -1,10 +1,11 @@
 import { type SlotlockAgentOperation, type SlotlockAgentPrincipal, type SlotlockAgentWriteOperation } from './agent-server.js';
-import { SlotlockConfigError, type SlotlockEnv, type SlotlockServeDashboardConfig } from './config.js';
+import { SlotlockConfigError, type SlotlockEnv, type SlotlockLimits, type SlotlockServeDashboardConfig } from './config.js';
 import { type SlotlockNodeServerAddress, type SlotlockNodeServerCloseResult } from './node-server.js';
+import { type SlotlockSql, type SlotlockStore } from './store.js';
 import type { WeeklyAvailabilityRule } from './types.js';
 export { SlotlockConfigError, type SlotlockEnv, type SlotlockServeDashboardConfig };
 /** Every variable the commands read. The README, `.env.example` and `server.json` document these. */
-export declare const SLOTLOCK_ENVIRONMENT_VARIABLES: readonly ["DATABASE_URL", "SLOTLOCK_MIGRATE_DATABASE_URL", "SLOTLOCK_AUTH_TOKEN", "SLOTLOCK_CONFIRMATION_SECRET", "SLOTLOCK_CONFIRM_WRITES", "SLOTLOCK_PUBLIC_URL", "SLOTLOCK_TENANT", "SLOTLOCK_AVAILABILITY", "SLOTLOCK_REST_API", "SLOTLOCK_GITHUB_CLIENT_ID", "SLOTLOCK_GITHUB_CLIENT_SECRET", "SLOTLOCK_SESSION_SECRET", "SLOTLOCK_DASHBOARD_USERS", "HOST", "PORT"];
+export declare const SLOTLOCK_ENVIRONMENT_VARIABLES: readonly ["DATABASE_URL", "SLOTLOCK_MIGRATE_DATABASE_URL", "SLOTLOCK_AUTH_TOKEN", "SLOTLOCK_CONFIRMATION_SECRET", "SLOTLOCK_CONFIRM_WRITES", "SLOTLOCK_PUBLIC_URL", "SLOTLOCK_TENANT", "SLOTLOCK_AVAILABILITY", "SLOTLOCK_REST_API", "SLOTLOCK_LIMITS", "SLOTLOCK_TRUSTED_PROXY_HEADER", "SLOTLOCK_GITHUB_CLIENT_ID", "SLOTLOCK_GITHUB_CLIENT_SECRET", "SLOTLOCK_SESSION_SECRET", "SLOTLOCK_DASHBOARD_USERS", "HOST", "PORT"];
 export interface SlotlockDatabaseConfig {
     /** The role `serve` and `resource` connect as. */
     databaseUrl: string;
@@ -21,11 +22,14 @@ export interface SlotlockServeConfig extends SlotlockDatabaseConfig {
     /** Where clients reach the server; Slotlock publishes its endpoints under this URL. */
     publicUrl: string;
     /**
-     * A bearer token for SLOTLOCK_TENANT with every scope. Optional: API keys (`slotlock key create`)
-     * authenticate whether or not it is set, each as its own tenant and scopes.
+     * A bearer token for SLOTLOCK_TENANT with read and write, never admin. Optional: API keys
+     * (`slotlock key create`) authenticate whether or not it is set, each as its own tenant and scopes.
      */
     authToken?: string;
-    /** Writes that wait for a person's confirmation (MCP 2026-07-28) and are refused elsewhere. */
+    /**
+     * Writes that wait for a person's confirmation (MCP 2026-07-28) and are refused elsewhere. None
+     * unless SLOTLOCK_CONFIRM_WRITES opts in: every authenticated write takes effect at once.
+     */
     confirmWrites: readonly SlotlockAgentWriteOperation[];
     /** Set exactly when `confirmWrites` is not empty. */
     confirmationSecret?: string;
@@ -33,8 +37,15 @@ export interface SlotlockServeConfig extends SlotlockDatabaseConfig {
     availability: readonly WeeklyAvailabilityRule[];
     /** Set exactly when SLOTLOCK_GITHUB_CLIENT_ID is. */
     dashboard?: SlotlockServeDashboardConfig;
-    /** Serve the REST API under /v1 and its OpenAPI document (SLOTLOCK_REST_API=on). */
+    /**
+     * Serve the REST API under /v1, with the application API for admin keys, and its OpenAPI document
+     * (SLOTLOCK_REST_API: on unless off).
+     */
     restApi: boolean;
+    /** Request limits (SLOTLOCK_LIMITS over SLOTLOCK_DEFAULT_LIMITS): the server's only rate limit. */
+    limits: SlotlockLimits;
+    /** The lower-case request field a trusted proxy sets to the client address; else the socket's. */
+    trustedProxyHeader?: string;
 }
 export declare function readSlotlockDatabaseConfig(env: SlotlockEnv): SlotlockDatabaseConfig;
 export declare function readSlotlockServeConfig(env: SlotlockEnv): SlotlockServeConfig;
@@ -51,8 +62,8 @@ export declare function slotlockHealthcheckUrl(env: SlotlockEnv): string;
 export declare function createSlotlockTokenAuthenticator(token: string, principal: SlotlockAgentPrincipal): (request: Request) => Promise<SlotlockAgentPrincipal | null>;
 /**
  * What `serve` lets a principal call: a served operation its scopes cover. The server token's
- * principal carries every scope; a principal without scopes is refused everything here, though the
- * agent server alone would leave it to this function.
+ * principal carries read and write, never admin; a principal without scopes is refused everything
+ * here, though the agent server alone would leave it to this function.
  */
 export declare function authorizeSlotlockServeOperation(args: {
     principal: SlotlockAgentPrincipal;
@@ -70,6 +81,7 @@ export interface SlotlockCliIo {
 }
 export interface SlotlockLogger {
     info(event: string, fields?: Record<string, unknown>): void;
+    warn(event: string, fields?: Record<string, unknown>): void;
     error(event: string, fields?: Record<string, unknown>): void;
 }
 /**
@@ -82,9 +94,14 @@ export interface SlotlockRunningServer {
     /** End open subscriptions, drain in-flight requests, then close the database pool. */
     close(): Promise<SlotlockNodeServerCloseResult>;
 }
+/**
+ * The store `serve` answers requests from. Every surface writes through it, so its tenant limits
+ * bound what any key can add, and its transaction limits what one tenant holds of the shared pool.
+ */
+export declare function createSlotlockServeStore(sql: SlotlockSql, caps: SlotlockLimits['caps']): SlotlockStore;
 /** Serve MCP and A2A over HTTP from the Postgres store, as one token-authenticated tenant. */
 export declare function startSlotlockServer(config: SlotlockServeConfig, log: SlotlockLogger): Promise<SlotlockRunningServer>;
-export declare const SLOTLOCK_CLI_HELP = "Usage: slotlock <command> [options]\n\nCommands:\n  migrate                  Apply the schema and row-level security, then grant the serving\n                           role when SLOTLOCK_MIGRATE_DATABASE_URL names another role\n  serve [--migrate]        Serve MCP and A2A over HTTP (--migrate runs migrate first)\n  resource add <ref> [--timezone <IANA zone>]\n                           Create a calendar resource (a car, room, person or machine)\n  resource list            Print the tenant's resources, one JSON object per line\n  hours show [--resource <ref>]\n                           Print each resource's bookable hours (null: the server's)\n  hours set <json> (--resource <ref> | --all)\n                           Give one resource, or every one, weekly hours of its own; [] closes\n  hours clear (--resource <ref> | --all)\n                           Hand one resource, or every one, back to the server's hours\n  key create <name> [--scope read|write|read,write] [--expires-in-days <n>]\n                           Create an API key for the tenant (default scope read,write, no\n                           expiry) and print it once; only its SHA-256 is stored\n  key list                 Print the tenant's API keys, one JSON object per line\n  key rotate <id>          Give an active key a new secret and print it once; the old one stops\n                           working at once, and the key keeps its id and what it booked\n  key revoke <id>          Revoke one of the tenant's API keys at once\n  healthcheck              Exit 0 when the local server reports ready\n\nOptions:\n  -h, --help               Show this help\n  -v, --version            Print the version\n\nEnvironment:\n  DATABASE_URL                   postgres:// URL of the role Slotlock serves as (required); serve\n                                 refuses a superuser or a role with BYPASSRLS\n  SLOTLOCK_MIGRATE_DATABASE_URL  postgres:// URL of the schema owner, for migrate (optional)\n  SLOTLOCK_AUTH_TOKEN            Optional bearer token for SLOTLOCK_TENANT with every scope,\n                                 32+ random characters (serve); API keys work with or without it\n  SLOTLOCK_CONFIRMATION_SECRET   Signs pending write confirmations, 32+ random characters (serve)\n  SLOTLOCK_CONFIRM_WRITES        all (default), none, or a comma-separated list of write tools\n  SLOTLOCK_PUBLIC_URL            URL clients use (default http://localhost:$PORT)\n  SLOTLOCK_TENANT                Tenant of the token, resource and key commands (default \"default\")\n  SLOTLOCK_AVAILABILITY          JSON array of weekly bookable-hours rules (default: none)\n  SLOTLOCK_REST_API              on: also serve the tools as a REST API under /v1, described at\n                                 /openapi.json, with the same keys and confirmation (default off)\n  SLOTLOCK_GITHUB_CLIENT_ID      Serve the dashboard at $SLOTLOCK_PUBLIC_URL/dashboard: the Client ID\n                                 of a GitHub OAuth app with callback .../dashboard/callback\n  SLOTLOCK_GITHUB_CLIENT_SECRET  That app's client secret (dashboard)\n  SLOTLOCK_SESSION_SECRET        Signs dashboard sessions, 32+ random characters (dashboard)\n  SLOTLOCK_DASHBOARD_USERS       * or comma-separated GitHub user ids that may sign in (dashboard)\n  HOST                           Listen address (default 127.0.0.1)\n  PORT                           Listen port (default 8080)\n\nGenerate each secret with: openssl rand -hex 32\n";
+export declare const SLOTLOCK_CLI_HELP = "Usage: slotlock <command> [options]\n\nCommands:\n  migrate                  Apply the schema and row-level security, then grant the serving\n                           role when SLOTLOCK_MIGRATE_DATABASE_URL names another role\n  serve [--migrate]        Serve MCP, A2A and REST over HTTP (--migrate runs migrate first);\n                           maintains each tenant it serves every hour\n  maintain                 Run maintenance for the tenant now: extend recurring events to the\n                           rolling horizon and prune past the retention window (for cron)\n  resource add <ref> [--timezone <IANA zone>]\n                           Create a calendar resource (a car, room, person or machine)\n  resource list            Print the tenant's resources, one JSON object per line\n  resource archive <ref>   Take a resource out of use: no new bookings, holds or events, and\n                           no longer listed; what is on it stays\n  resource restore <ref>   Put an archived resource back in use\n  resource delete <ref>    Delete a resource and its history; refused while a booking, hold\n                           or event on it has not ended\n  hours show [--resource <ref>]\n                           Print each resource's bookable hours (null: the server's)\n  hours set <json> (--resource <ref> | --all)\n                           Give one resource, or every one, weekly hours of its own; [] closes\n  hours clear (--resource <ref> | --all)\n                           Hand one resource, or every one, back to the server's hours\n  key create <name> [--scope read,write,admin] [--expires-in-days <n>]\n                           Create an API key for the tenant (default scope read,write, no\n                           expiry; admin adds the application API) and print it once; only its\n                           SHA-256 is stored\n  key list                 Print the tenant's API keys, one JSON object per line\n  key rotate <id>          Give an active key a new secret and print it once; the old one stops\n                           working at once, and the key keeps its id and what it booked\n  key revoke <id>          Revoke one of the tenant's API keys at once\n  tenant status            Print whether the tenant is suspended\n  tenant suspend [--reason <text>]\n                           Suspend the tenant: it may read, and writes nothing; its keys get\n                           no new secret (as SLOTLOCK_MIGRATE_DATABASE_URL's role when set:\n                           only the schema owner suspends)\n  tenant unsuspend         Lift the tenant's suspension (as the schema owner, likewise)\n  tenant erase --confirm <tenant>\n                           Delete everything the tenant has, its API keys included, for good;\n                           --confirm repeats SLOTLOCK_TENANT\n  healthcheck              Exit 0 when the local server reports ready\n\nOptions:\n  -h, --help               Show this help\n  -v, --version            Print the version\n\nEnvironment:\n  DATABASE_URL                   postgres:// URL of the role Slotlock serves as (required); serve\n                                 refuses a superuser or a role with BYPASSRLS\n  SLOTLOCK_MIGRATE_DATABASE_URL  postgres:// URL of the schema owner, for migrate (optional)\n  SLOTLOCK_AUTH_TOKEN            Optional bearer token for SLOTLOCK_TENANT with read and write\n                                 access (never admin), 32+ random characters (serve); API keys\n                                 work with or without it\n  SLOTLOCK_CONFIRMATION_SECRET   Signs pending write confirmations, 32+ random characters (serve;\n                                 required when SLOTLOCK_CONFIRM_WRITES is not none)\n  SLOTLOCK_CONFIRM_WRITES        none (default), all, or a comma-separated list of write tools\n                                 that wait for a person (MCP 2026-07-28 form elicitation; refused\n                                 with confirmation_required on REST, A2A and older MCP)\n  SLOTLOCK_PUBLIC_URL            URL clients use (default http://localhost:$PORT)\n  SLOTLOCK_TENANT                Tenant of the token, resource and key commands (default \"default\")\n  SLOTLOCK_AVAILABILITY          JSON array of weekly bookable-hours rules (default: none)\n  SLOTLOCK_REST_API              on (default): also serve the tools as a REST API under /v1, and\n                                 the application API for admin keys, described at /openapi.json;\n                                 off: MCP and A2A only\n  SLOTLOCK_LIMITS                Request limits, comma-separated name=value over the defaults:\n                                 rates as <count>/<s|m|h>[:<burst>] or off for address (50/s:100,\n                                 every request per client, before any key lookup), key_read,\n                                 tenant_read (20/s:40), key_write, tenant_write (5/s:20),\n                                 global_read (500/s:1000), global_write (50/s:100), app_read\n                                 (20/s:40) and app_write (5/s:20) per tenant for the\n                                 application API, sign_in (20/m:20); counts for\n                                 tenant_series_writes and series_writes\n                                 (1: writes that may expand a recurring series at once),\n                                 maintenance_runs (1: application API maintenance runs at once),\n                                 subscriptions (256), tenant_subscriptions (16),\n                                 key_subscriptions (4, and fewer than tenant_subscriptions),\n                                 key_lookups (2), key_lookup_queue (256),\n                                 tenant_transactions (2: one tenant's database transactions at\n                                 once, of the pool's 10); what one tenant may store:\n                                 tenant_holds (10000), tenant_reservations, tenant_events and\n                                 tenant_coverage (100000)\n  SLOTLOCK_TRUSTED_PROXY_HEADER  The request field a proxy in front sets to the client address,\n                                 such as CF-Connecting-IP (default: the connection's address);\n                                 set it only when every request comes through that proxy\n  SLOTLOCK_GITHUB_CLIENT_ID      Serve the dashboard at $SLOTLOCK_PUBLIC_URL/dashboard: the Client ID\n                                 of a GitHub OAuth app with callback .../dashboard/callback\n  SLOTLOCK_GITHUB_CLIENT_SECRET  That app's client secret (dashboard)\n  SLOTLOCK_SESSION_SECRET        Signs dashboard sessions, 32+ random characters (dashboard)\n  SLOTLOCK_DASHBOARD_USERS       * or comma-separated GitHub user ids that may sign in (dashboard)\n  HOST                           Listen address (default 127.0.0.1)\n  PORT                           Listen port (default 8080)\n\nGenerate each secret with: openssl rand -hex 32\n";
 /**
  * Run one `slotlock` command and resolve to its exit code: 0 success, 1 failure, 2 a usage or
  * configuration error (nothing was started). `serve` resolves once `io.signal` aborts and it has