slotlock 0.1.1 → 0.2.0

package/node-server.js

@@ -1,12 +1,14 @@
 // Kept in the emitted node-server.d.ts: this entry point's types import `node:http`.
 /// <reference types="node" preserve="true" />
 import { createServer } from 'node:http';
-import { Readable } from 'node:stream';
+import { Readable, finished } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 const DEFAULT_HANDLER_TIMEOUT_MS = 30_000;
 const DEFAULT_HEADERS_TIMEOUT_MS = 10_000;
 const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
 const DEFAULT_KEEP_ALIVE_TIMEOUT_MS = 5_000;
+/** How often Node checks its connections against headersTimeout and requestTimeout, at most. */
+const DEFAULT_CONNECTIONS_CHECKING_INTERVAL_MS = 1_000;
 const DEFAULT_SHUTDOWN_GRACE_MS = 10_000;
 const DEFAULT_MAX_HEADER_BYTES = 16_384;
 const DEFAULT_MAX_REQUESTS_PER_SOCKET = 100;
@@ -72,11 +74,73 @@ function appendIncomingHeaders(request) {
     }
     return headers;
 }
+/**
+ * The request body as a web stream that a target may cancel, as it does a body over its size limit.
+ * Cancelling a `Readable.toWeb` stream destroys the IncomingMessage: Node emits 'aborted', read
+ * here as the client leaving, and the unread rest stays on the connection, which then holds
+ * `close()` until it is forced. Cancelling this one only stops delivery; once the response is
+ * written the rest is discarded as it arrives, as Node discards a body no handler reads, within
+ * `requestTimeout`.
+ */
+function requestBody(request) {
+    let controller;
+    // Once the stream is closed, errored or cancelled, what arrives is dropped.
+    let settled = false;
+    const stream = new ReadableStream({
+        start(started) {
+            controller = started;
+            request.pause();
+            request.on('data', (chunk) => {
+                if (settled)
+                    return;
+                started.enqueue(new Uint8Array(chunk));
+                if ((started.desiredSize ?? 0) <= 0)
+                    request.pause();
+            });
+            finished(request, (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (error)
+                    started.error(error);
+                else
+                    started.close();
+            });
+        },
+        pull() {
+            if (!settled)
+                request.resume();
+        },
+        cancel() {
+            // Held until the response is written, so the client is not read from while it waits.
+            settled = true;
+            request.pause();
+        },
+    }, { highWaterMark: request.readableHighWaterMark, size: (chunk) => chunk.byteLength });
+    return {
+        stream,
+        discard() {
+            // A target still reading a body it has already answered gets an error, not a read that
+            // never settles.
+            if (!settled) {
+                settled = true;
+                controller?.error(abortReason('request_body_discarded'));
+            }
+            request.resume();
+        },
+    };
+}
 function toWebRequest(request, requestOrigin, signal) {
     const target = request.url ?? '';
     if (!target.startsWith('/') || target.startsWith('//')) {
         throw new Error('invalid_request_target');
     }
+    // URL parsing resolves dot segments, `%2E` spellings included: `/v1/resources/%2E%2E/availability`
+    // would reach the target as `/v1/availability`, a path parameter of `..` naming another route.
+    const path = target.split(/[?#]/, 1)[0] ?? '';
+    if (path.split('/').some((segment) => /^(?:\.|%2e){1,2}$/i.test(segment))) {
+        throw new Error('invalid_request_target');
+    }
     const url = new URL(target, requestOrigin);
     if (url.origin !== requestOrigin)
         throw new Error('invalid_request_target');
@@ -88,11 +152,20 @@ function toWebRequest(request, requestOrigin, signal) {
         headers: appendIncomingHeaders(request),
         signal,
     };
+    let body;
     if (init.method !== 'GET' && init.method !== 'HEAD') {
-        init.body = Readable.toWeb(request);
+        body = requestBody(request);
+        init.body = body.stream;
         init.duplex = 'half';
     }
-    return new Request(url, init);
+    try {
+        return { request: new Request(url, init), ...(body ? { body } : {}) };
+    }
+    catch (error) {
+        // A method the Fetch API forbids, say: nothing will read the body, so drop it as it arrives.
+        body?.discard();
+        throw error;
+    }
 }
 const HOP_BY_HOP_RESPONSE_HEADERS = new Set([
     'connection',
@@ -161,10 +234,15 @@ export function createSlotlockNodeServer(target, options) {
     // opening check, but `close()` can change the state while the handler awaits.
     const closing = () => state === 'closing';
     let removeLifecycleAbort;
+    /** Rejects a listen() still starting with `listen_aborted`; set while one is. */
+    let cancelStartup;
     let closePromise;
     const server = createServer({
         headersTimeout: headersTimeoutMs,
         requestTimeout: requestTimeoutMs,
+        // Node enforces both only when it checks its connections (every 30 s by default), so a body
+        // trickled after its answer could outlast requestTimeout by that much.
+        connectionsCheckingInterval: Math.min(DEFAULT_CONNECTIONS_CHECKING_INTERVAL_MS, headersTimeoutMs, requestTimeoutMs),
         keepAliveTimeout: boundedInteger('keepAliveTimeoutMs', options.keepAliveTimeoutMs ?? DEFAULT_KEEP_ALIVE_TIMEOUT_MS, 1, MAX_TIMEOUT_MS),
         maxHeaderSize: boundedInteger('maxHeaderBytes', options.maxHeaderBytes ?? DEFAULT_MAX_HEADER_BYTES, 1_024, MAX_HEADER_BYTES),
         insecureHTTPParser: false,
@@ -187,8 +265,9 @@ export function createSlotlockNodeServer(target, options) {
                 abortForClient();
         });
         let webRequest;
+        let body;
         try {
-            webRequest = toWebRequest(request, config.requestOrigin, controller.signal);
+            ({ request: webRequest, body } = toWebRequest(request, config.requestOrigin, controller.signal));
         }
         catch {
             activeRequests.delete(controller);
@@ -223,6 +302,18 @@ export function createSlotlockNodeServer(target, options) {
             if (timeout)
                 clearTimeout(timeout);
             activeRequests.delete(controller);
+            // The answer is written: what is left of a body the target did not read (one it refused as
+            // too large, say) is discarded as it arrives rather than held.
+            if (!request.complete) {
+                body?.discard();
+                // The connection is idle only once that rest has arrived: close it then if shutting down.
+                request.once('end', () => {
+                    setImmediate(() => {
+                        if (closing())
+                            server.closeIdleConnections();
+                    });
+                });
+            }
             // A keep-alive connection whose response finished during shutdown would otherwise hold
             // `server.close()` open until its idle timeout; Node closed only the idle ones at the start.
             if (closing())
@@ -244,6 +335,16 @@ export function createSlotlockNodeServer(target, options) {
         closePromise = (async () => {
             removeLifecycleAbort?.();
             removeLifecycleAbort = undefined;
+            if (state === 'starting') {
+                // Closed before it was listening. Node abandons a listen whose server closes first, with
+                // neither 'listening' nor 'error', so the pending listen() is rejected here, as an aborted
+                // signal rejects it.
+                state = 'closing';
+                cancelStartup?.();
+                await new Promise((resolve) => server.close(() => resolve()));
+                state = 'closed';
+                return { forced: false };
+            }
             if (state === 'new' || state === 'closed') {
                 state = 'closed';
                 return { forced: false };
@@ -305,24 +406,33 @@ export function createSlotlockNodeServer(target, options) {
             state = 'starting';
             return new Promise((resolve, reject) => {
                 let abortRequested = false;
+                let cancelled = false;
                 const onAbort = () => {
                     abortRequested = true;
                     if (state === 'listening')
                         void close();
                 };
                 const cleanupStartup = () => {
+                    cancelStartup = undefined;
                     server.off('error', onListenError);
                     server.off('listening', onListening);
                 };
                 const onListenError = (error) => {
                     cleanupStartup();
                     listenOptions.signal?.removeEventListener('abort', onAbort);
-                    state = 'closed';
                     safeReport(config.onError, error, 'listen');
+                    if (cancelled)
+                        return;
+                    state = 'closed';
                     reject(error);
                 };
                 const onListening = () => {
                     cleanupStartup();
+                    if (cancelled) {
+                        // close() came first; a listener that bound all the same goes with it.
+                        server.close();
+                        return;
+                    }
                     const address = server.address();
                     if (!address || typeof address === 'string') {
                         state = 'closing';
@@ -344,6 +454,12 @@ export function createSlotlockNodeServer(target, options) {
                         origin: formatListenerOrigin(address.address, address.port),
                     });
                 };
+                cancelStartup = () => {
+                    cancelled = true;
+                    cancelStartup = undefined;
+                    listenOptions.signal?.removeEventListener('abort', onAbort);
+                    reject(abortReason('listen_aborted'));
+                };
                 listenOptions.signal?.addEventListener('abort', onAbort, { once: true });
                 server.once('error', onListenError);
                 server.once('listening', onListening);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slotlock",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "type": "module",
   "description": "Resource-first, deterministic calendar and availability engine for AI agents.",
   "license": "Apache-2.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,142 @@ 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 });
+        }
+    }
+    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;
             }