slotlock 0.1.1 → 0.3.0

package/engine.js

@@ -47,13 +47,27 @@ export function findNextAvailable(params) {
     const { busy, windows, durationMs } = params;
     if (!Number.isFinite(durationMs) || durationMs <= 0)
         return null;
-    const orderedWindows = mergeIntervals(windows);
-    for (const window of orderedWindows) {
-        for (const free of subtractBusy(window, busy)) {
-            if (free.end.getTime() - free.start.getTime() >= durationMs) {
-                return { start: free.start, end: new Date(free.start.getTime() + durationMs) };
-            }
+    const slotAt = (start) => ({ start, end: new Date(start.getTime() + durationMs) });
+    // One walk of the merged busy list alongside the merged windows, both by start: a busy interval
+    // ending by a window's start ends before every later one too.
+    const merged = mergeIntervals(busy);
+    let next = 0;
+    for (const window of mergeIntervals(windows)) {
+        while (next < merged.length && merged[next].end.getTime() <= window.start.getTime()) {
+            next += 1;
         }
+        let cursor = window.start;
+        for (let index = next; index < merged.length; index++) {
+            const taken = merged[index];
+            if (taken.start.getTime() >= window.end.getTime())
+                break;
+            if (taken.start.getTime() - cursor.getTime() >= durationMs)
+                return slotAt(cursor);
+            if (taken.end.getTime() > cursor.getTime())
+                cursor = taken.end;
+        }
+        if (window.end.getTime() - cursor.getTime() >= durationMs)
+            return slotAt(cursor);
     }
     return null;
 }

package/event-schema.d.ts

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+export declare const SLOTLOCK_EVENT_OUTPUT: z.ZodObject<{
+    id: z.ZodString;
+    resource_id: z.ZodString;
+    starts_at: z.ZodString;
+    ends_at: z.ZodString;
+    timezone: z.ZodString;
+    title: z.ZodNullable<z.ZodString>;
+    description: z.ZodNullable<z.ZodString>;
+    location: z.ZodNullable<z.ZodString>;
+    organizer: z.ZodNullable<z.ZodObject<{
+        address: z.ZodString;
+        name: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+    attendees: z.ZodArray<z.ZodObject<{
+        address: z.ZodString;
+        name: z.ZodNullable<z.ZodString>;
+        role: z.ZodEnum<{
+            chair: "chair";
+            non_participant: "non_participant";
+            optional: "optional";
+            required: "required";
+        }>;
+        participation_status: z.ZodEnum<{
+            accepted: "accepted";
+            declined: "declined";
+            delegated: "delegated";
+            needs_action: "needs_action";
+            tentative: "tentative";
+        }>;
+        rsvp: z.ZodBoolean;
+    }, z.core.$strict>>;
+    reminders: z.ZodArray<z.ZodObject<{
+        minutes_before: z.ZodNumber;
+        channel: z.ZodEnum<{
+            display: "display";
+            email: "email";
+        }>;
+    }, z.core.$strict>>;
+    status: z.ZodEnum<{
+        cancelled: "cancelled";
+        confirmed: "confirmed";
+        tentative: "tentative";
+    }>;
+    transparency: z.ZodEnum<{
+        opaque: "opaque";
+        transparent: "transparent";
+    }>;
+    sequence: z.ZodNumber;
+    revision: z.ZodNumber;
+    recurrence_rule: z.ZodNullable<z.ZodString>;
+    recurrence_exceptions: z.ZodArray<z.ZodObject<{
+        recurrence_id: z.ZodString;
+        cancelled: z.ZodBoolean;
+        starts_at: z.ZodNullable<z.ZodString>;
+        ends_at: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+    recurrence_id: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;

package/event-schema.js

@@ -0,0 +1,85 @@
+// A calendar event as the event tools return it, and as the application API returns any of a
+// tenant's events. Its own module because both the agent server and the application API describe
+// events with it, and the application API imports nothing from the agent server at runtime (the
+// agent server imports it, so the reverse would be a cycle).
+import { z } from 'zod';
+const DATE_TIME = z.string().datetime({ offset: true });
+const RESOURCE_ID = z.string().trim().min(1).max(200);
+const EVENT_ID = z.string().trim().min(1).max(500);
+const REVISION = z.number().int().positive();
+// Output bounds mirror the trusted store's byte ceilings. A value admitted by a UTF-8 byte
+// ceiling can never exceed that many UTF-16 code units, so every valid stored/provider event is
+// serializable without truncating recurrence semantics or calendar identities.
+const TRUSTED_SUMMARY_OUTPUT_MAX = 4_096;
+const TRUSTED_TEXT_OUTPUT_MAX = 16_384;
+const TRUSTED_PERSON_NAME_OUTPUT_MAX = 1_024;
+const TRUSTED_RECURRENCE_EXCEPTION_OUTPUT_MAX = 1_000;
+const TRUSTED_REMINDER_MINUTES_OUTPUT_MAX = 366 * 24 * 60;
+// The grammar the store keeps an address in (normalizeEmail in sync.ts), so every stored one can be
+// returned: an address from an imported feed need not be one z.email() takes (ops@localhost).
+const STORED_ADDRESS = z
+    .string()
+    .min(3)
+    .max(320)
+    .refine((value) => /^[^\s@]+@[^\s@]+$/.test(value), {
+    message: 'must be one @ between characters other than spaces',
+});
+const ORGANIZER = z
+    .object({
+    address: STORED_ADDRESS,
+    name: z.string().trim().max(TRUSTED_PERSON_NAME_OUTPUT_MAX).nullable(),
+})
+    .strict();
+const ATTENDEE = z
+    .object({
+    address: STORED_ADDRESS,
+    name: z.string().trim().max(TRUSTED_PERSON_NAME_OUTPUT_MAX).nullable(),
+    role: z.enum(['chair', 'required', 'optional', 'non_participant']),
+    participation_status: z.enum([
+        'needs_action',
+        'accepted',
+        'declined',
+        'tentative',
+        'delegated',
+    ]),
+    rsvp: z.boolean(),
+})
+    .strict();
+const REMINDER = z
+    .object({
+    minutes_before: z.number().int().min(0).max(TRUSTED_REMINDER_MINUTES_OUTPUT_MAX),
+    channel: z.enum(['display', 'email']),
+})
+    .strict();
+const RECURRENCE_EXCEPTION = z
+    .object({
+    recurrence_id: DATE_TIME,
+    cancelled: z.boolean(),
+    starts_at: DATE_TIME.nullable(),
+    ends_at: DATE_TIME.nullable(),
+})
+    .strict();
+export const SLOTLOCK_EVENT_OUTPUT = z
+    .object({
+    id: EVENT_ID,
+    resource_id: RESOURCE_ID,
+    starts_at: DATE_TIME,
+    ends_at: DATE_TIME,
+    timezone: z.string().min(1).max(100),
+    title: z.string().max(TRUSTED_SUMMARY_OUTPUT_MAX).nullable(),
+    description: z.string().max(TRUSTED_TEXT_OUTPUT_MAX).nullable(),
+    location: z.string().max(TRUSTED_TEXT_OUTPUT_MAX).nullable(),
+    organizer: ORGANIZER.nullable(),
+    attendees: z.array(ATTENDEE).max(100),
+    reminders: z.array(REMINDER).max(20),
+    status: z.enum(['tentative', 'confirmed', 'cancelled']),
+    transparency: z.enum(['opaque', 'transparent']),
+    sequence: z.number().int().nonnegative(),
+    revision: REVISION,
+    recurrence_rule: z.string().max(TRUSTED_SUMMARY_OUTPUT_MAX).nullable(),
+    recurrence_exceptions: z
+        .array(RECURRENCE_EXCEPTION)
+        .max(TRUSTED_RECURRENCE_EXCEPTION_OUTPUT_MAX),
+    recurrence_id: DATE_TIME.nullable(),
+})
+    .strict();

package/hooks.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Let a hook's promise fail unseen. `onEvent` and `onError` are typed as returning nothing, but an
+ * async one returns a promise, and its rejection, left alone, is an unhandled rejection: Node ends
+ * the process on one by default. A hook that throws is caught where it is called; this is the same
+ * for one that rejects.
+ */
+export declare function ignoreRejection(result: unknown): void;

package/hooks.js

@@ -0,0 +1,13 @@
+/**
+ * Let a hook's promise fail unseen. `onEvent` and `onError` are typed as returning nothing, but an
+ * async one returns a promise, and its rejection, left alone, is an unhandled rejection: Node ends
+ * the process on one by default. A hook that throws is caught where it is called; this is the same
+ * for one that rejects.
+ */
+export function ignoreRejection(result) {
+    if ((typeof result === 'object' || typeof result === 'function') &&
+        result !== null &&
+        typeof result.then === 'function') {
+        Promise.resolve(result).catch(() => undefined);
+    }
+}

package/ical-worker-thread.js

@@ -1,7 +1,7 @@
 // One worker of createICalendarWorkerPool: reads the feeds it is sent with the ordinary parsers and
 // posts back what they return, or the code of the CalendarContractError they throw.
 import { parentPort } from 'node:worker_threads';
-import { CalendarContractError, CalendarExpansionLimitError, parseICalendarChanges, parseTrustedICalendarEvents, } from './sync.js';
+import { CalendarContractError, CalendarExpansionLimitError, parseICalendarChanges, parseICalendarFeed, parseTrustedICalendarEvents, } from './sync.js';
 const port = parentPort;
 if (!port)
     throw new Error('slotlock: ical-worker-thread runs only as a worker thread');
@@ -10,7 +10,9 @@ port.on('message', (request) => {
     try {
         const value = request.op === 'changes'
             ? parseICalendarChanges(request.input, request.calendarTimezone, request.window)
-            : parseTrustedICalendarEvents(request.input, request.calendarTimezone);
+            : request.op === 'feed'
+                ? parseICalendarFeed(request.input, request.calendarTimezone, request.window)
+                : parseTrustedICalendarEvents(request.input, request.calendarTimezone);
         reply = { id: request.id, ok: true, value };
     }
     catch (error) {

package/ical-worker.d.ts

@@ -1,9 +1,9 @@
-import { CalendarContractError, type ExternalCalendarChange, type ICalendarExpansionWindow } from './sync.js';
+import { CalendarContractError, type ExternalCalendarChange, type ICalendarExpansionWindow, type ICalendarFeedRead } from './sync.js';
 import type { TrustedICalendarEvent } from './types.js';
 /** What the pool posts to a worker. */
 export type ICalendarWorkerRequest = {
     id: number;
-    op: 'changes';
+    op: 'changes' | 'feed';
     input: string;
     calendarTimezone: string | undefined;
     window: ICalendarExpansionWindow | undefined;
@@ -29,8 +29,8 @@ export interface ICalendarWorkerPoolOptions {
     size?: number;
     /**
      * How long one parse may run on its worker, in ms, before the worker is stopped and the feed
-     * refused (CalendarExpansionLimitError), 100-60,000. Defaults to 3,000: three times the parser's
-     * own limit, with room for a new worker to start.
+     * refused (CalendarExpansionLimitError), 100-60,000. Defaults to 3,000: several times what the
+     * parser's step budget takes, with room for a new worker to start.
      */
     deadlineMs?: number;
     /** Parses that may wait for a worker, 0-10,000; more are refused at once. Defaults to 64. */
@@ -46,6 +46,8 @@ export interface ICalendarWorkerPoolOptions {
 export interface ICalendarWorkerPool {
     /** `parseICalendarChanges`, run on a worker. */
     parseICalendarChanges(input: string, calendarTimezone?: string, expansionWindow?: ICalendarExpansionWindow): Promise<ExternalCalendarChange[]>;
+    /** `parseICalendarFeed`, run on a worker. */
+    parseICalendarFeed(input: string, calendarTimezone?: string, expansionWindow?: ICalendarExpansionWindow): Promise<ICalendarFeedRead>;
     /** `parseTrustedICalendarEvents`, run on a worker. */
     parseTrustedICalendarEvents(input: string, calendarTimezone?: string): Promise<TrustedICalendarEvent[]>;
     /** Refuse waiting parses and stop every worker. */
@@ -63,7 +65,8 @@ export declare class ICalendarWorkerPoolClosedError extends Error {
 }
 /**
  * A pool of worker threads that read untrusted iCalendar for the calling thread. Results and
- * errors are those of `parseICalendarChanges` and `parseTrustedICalendarEvents` (the same
+ * errors are those of `parseICalendarChanges`, `parseICalendarFeed` and
+ * `parseTrustedICalendarEvents` (the same
  * `CalendarContractError` codes), plus CalendarExpansionLimitError when a worker passes its
  * deadline or its heap, ICalendarWorkerBusyError when the queue is full, and
  * ICalendarWorkerPoolClosedError after `close()`. Idle workers do not keep the process alive.

package/ical-worker.js

@@ -31,7 +31,8 @@ function workerFailure(error) {
 }
 /**
  * A pool of worker threads that read untrusted iCalendar for the calling thread. Results and
- * errors are those of `parseICalendarChanges` and `parseTrustedICalendarEvents` (the same
+ * errors are those of `parseICalendarChanges`, `parseICalendarFeed` and
+ * `parseTrustedICalendarEvents` (the same
  * `CalendarContractError` codes), plus CalendarExpansionLimitError when a worker passes its
  * deadline or its heap, ICalendarWorkerBusyError when the queue is full, and
  * ICalendarWorkerPoolClosedError after `close()`. Idle workers do not keep the process alive.
@@ -134,7 +135,7 @@ export function createICalendarWorkerPool(options = {}) {
         if (request.calendarTimezone !== undefined && typeof request.calendarTimezone !== 'string') {
             throw new CalendarContractError('invalid_icalendar');
         }
-        if (request.op === 'changes' &&
+        if (request.op !== 'trusted' &&
             request.window !== undefined &&
             !(request.window?.start instanceof Date && request.window.end instanceof Date)) {
             throw new CalendarContractError('invalid_icalendar');
@@ -172,6 +173,12 @@ export function createICalendarWorkerPool(options = {}) {
                 window,
             }));
         },
+        async parseICalendarFeed(input, calendarTimezone, expansionWindow) {
+            const window = expansionWindow
+                ? { start: expansionWindow.start, end: expansionWindow.end }
+                : undefined;
+            return (await run({ op: 'feed', input, calendarTimezone, window }));
+        },
         async parseTrustedICalendarEvents(input, calendarTimezone) {
             return (await run({ op: 'trusted', input, calendarTimezone }));
         },

package/index.d.ts

@@ -5,20 +5,24 @@ export { availabilityRuleProblem, parseAvailabilityRules, rulesToWeeklyHours, SL
 export type { HoursWindow, Weekday, WeeklyHours } from './weekly-hours.js';
 export { createTimeZoneConverter, zonedCalendarDate, zonedDateTimeToUtc, zonedWallTime, } from './timezone.js';
 export type { LocalDateTime, TimeZoneConverter, ZonedCalendarDate, ZonedWallTime, } from './timezone.js';
-export { createSlotlockAgentServer, clientSupportsSlotlockMcpApp, invokeSlotlockAgentOperation, isSlotlockAgentOperation, slotlockAgentTools, slotlockCalendarResourceUri, slotlockMcpToolResult, parseSlotlockA2ATimestamp, resolveSlotlockAgentOperation, slotlockAgentOperationScope, SLOTLOCK_A2A_PROTOCOL_VERSION, SLOTLOCK_A2A_TASK_PAGE_SIZE, SLOTLOCK_A2A_TASK_STATES, SLOTLOCK_AGENT_OPERATION_LEGACY_NAMES, SLOTLOCK_AGENT_SERVER_VERSION, SLOTLOCK_MCP_LEGACY_PROTOCOL_VERSION, SLOTLOCK_MCP_PROTOCOL_VERSION, SLOTLOCK_MCP_RATE_LIMITED_ERROR_CODE, SLOTLOCK_MCP_RESOURCE_URI_TEMPLATE, SLOTLOCK_MCP_SUPPORTED_PROTOCOL_VERSIONS, SLOTLOCK_MCP_APP_HTML, SLOTLOCK_MCP_APP_MIME_TYPE, SLOTLOCK_MCP_APP_RESOURCE, SLOTLOCK_MCP_APP_RESOURCE_URI, SLOTLOCK_MCP_APPS_EXTENSION, SlotlockAgentOperationError, } from './agent-server.js';
+export { createSlotlockAgentServer, clientSupportsSlotlockMcpApp, invokeSlotlockAgentOperation, isSlotlockAgentOperation, slotlockAgentTools, slotlockApplicationOperations, slotlockOpenApi, slotlockCalendarResourceUri, slotlockMcpToolResult, parseSlotlockA2ATimestamp, resolveSlotlockAgentOperation, slotlockAgentOperationScope, SLOTLOCK_A2A_PROTOCOL_VERSION, SLOTLOCK_A2A_TASK_PAGE_SIZE, SLOTLOCK_A2A_TASK_STATES, SLOTLOCK_AGENT_OPERATION_LEGACY_NAMES, SLOTLOCK_AGENT_SERVER_VERSION, SLOTLOCK_MCP_LEGACY_PROTOCOL_VERSION, SLOTLOCK_MCP_PROTOCOL_VERSION, SLOTLOCK_MCP_RATE_LIMITED_ERROR_CODE, SLOTLOCK_MCP_RESOURCE_URI_TEMPLATE, SLOTLOCK_MCP_SUPPORTED_PROTOCOL_VERSIONS, SLOTLOCK_MCP_APP_HTML, SLOTLOCK_MCP_APP_MIME_TYPE, SLOTLOCK_MCP_APP_RESOURCE, SLOTLOCK_MCP_APP_RESOURCE_URI, SLOTLOCK_MCP_APPS_EXTENSION, SlotlockAgentOperationError, } from './agent-server.js';
 export type { SlotlockAgentCalendarBackend, SlotlockAgentConfirmationOptions, SlotlockAgentErrorContext, SlotlockAgentInvocationContext, SlotlockAgentOperation, SlotlockAgentOperationDispatchOptions, SlotlockAgentOperationDispatchResult, SlotlockAgentPrincipal, SlotlockAgentScope, SlotlockAgentServerEvent, SlotlockAgentServerOAuthOptions, SlotlockAgentServerOptions, SlotlockAgentSubscriptionOptions, SlotlockAgentWriteOperation, SlotlockMcpToolResult, SlotlockTraceContext, } from './agent-server.js';
 export { createSlotlockNodeServer } from './node-server.js';
 export type { SlotlockNodeListenOptions, SlotlockNodeServer, SlotlockNodeServerAddress, SlotlockNodeServerCloseResult, SlotlockNodeServerErrorPhase, SlotlockNodeServerFetchTarget, SlotlockNodeServerOptions, } from './node-server.js';
-export { createSlotlockStoreAgentBackend, projectSlotlockCalendarEvent } from './agent-store-backend.js';
-export type { SlotlockStoreAgentBackendOptions } from './agent-store-backend.js';
+export { createSlotlockStoreAgentBackend, createSlotlockStoreApplicationBackend, projectSlotlockCalendarEvent, } from './agent-store-backend.js';
+export type { SlotlockStoreAgentBackendOptions, SlotlockStoreApplicationBackendOptions, } from './agent-store-backend.js';
+export { SLOTLOCK_APPLICATION_OPERATIONS, SLOTLOCK_APPLICATION_SCOPE, isSlotlockApplicationOperation, } from './application-api.js';
+export type { SlotlockApplicationBackend, SlotlockApplicationInvocationContext, SlotlockApplicationOperation, SlotlockApplicationOperationDefinition, } from './application-api.js';
+export { maintainSlotlockTenant, startSlotlockMaintenance, withSlotlockMaintenanceLock, } from './maintenance.js';
+export type { SlotlockMaintenanceResult, SlotlockMaintenanceScheduler, SlotlockMaintenanceSchedulerOptions, } from './maintenance.js';
 export { createSlotlockApiKeyAuthenticator, createSlotlockApiKeyStore, generateSlotlockApiKey, isSlotlockApiKey, slotlockApiKeyDigest, SLOTLOCK_API_KEY_ACTIVE_LIMIT, SLOTLOCK_API_KEY_MAX_LIFETIME_DAYS, SLOTLOCK_API_KEY_PREFIX, SLOTLOCK_API_KEY_RETAINED_LIMIT, SLOTLOCK_API_KEY_SCOPES, } from './api-keys.js';
 export { createSlotlockDashboard, createSlotlockDashboardResources, createSlotlockDashboardState, createSlotlockMemoryDashboardState, SLOTLOCK_DASHBOARD_MAX_RESOURCES, } from './dashboard.js';
 export type { SlotlockDashboard, SlotlockDashboardOptions, SlotlockDashboardResources, SlotlockDashboardState, } from './dashboard.js';
 export type { CreateSlotlockApiKeyInput, SlotlockApiKey, SlotlockApiKeyAuthenticatorOptions, SlotlockApiKeyIdentity, SlotlockApiKeyScope, SlotlockApiKeyStore, } from './api-keys.js';
 export { ICalendarWorkerBusyError, ICalendarWorkerPoolClosedError, createICalendarWorkerPool, } from './ical-worker.js';
 export type { ICalendarWorkerPool, ICalendarWorkerPoolOptions } from './ical-worker.js';
-export { CalendarContractError, CalendarExpansionLimitError, emitICalendar, emitITipCalendar, expandCalendarEventOccurrences, normalizeCalendarEventContent, normalizeExternalCalendarChange, parseICalendarChanges, parseTrustedICalendarEvents, } from './sync.js';
-export type { ExternalCalendarChange, ExternalCalendarChangeInput, ExternalCalendarStatus, ICalendarEvent, ICalendarExpansionWindow, ITipMethod, } from './sync.js';
-export { createSlotlockApplicationRoleGrantsDdl, createSlotlockTenantRlsDdl, SLOTLOCK_API_KEY_FUNCTIONS, SLOTLOCK_API_KEY_TABLES, SLOTLOCK_CORE_DDL, SLOTLOCK_DASHBOARD_FUNCTIONS, SLOTLOCK_DASHBOARD_TABLES, SLOTLOCK_DEFINER_FUNCTIONS, SLOTLOCK_DEFINER_TABLES, SLOTLOCK_TENANT_CONTEXT_SETTING, SLOTLOCK_TENANT_RLS_DDL, SLOTLOCK_TENANT_TABLES, } from './ddl.js';
-export { calendarEventRollingHorizon, createSlotlockStore, SLOTLOCK_AGENT_OWNER_COMMAND_QUOTA, SLOTLOCK_AGENT_OWNER_EVENT_QUOTA, SLOTLOCK_CALENDAR_HORIZON_DAYS, SLOTLOCK_EVENT_COMMAND_RETENTION_DAYS, SLOTLOCK_INTERNAL_EVENT_OWNER_REF, SLOTLOCK_LOCAL_RECURRENCE_COVERAGE_SOURCE, SLOTLOCK_MAX_EVENT_DURATION_DAYS, type SlotlockSql, type SlotlockStore, type SlotlockStoreOptions, type SlotlockTenantStore, } from './store.js';
-export type { AcquireHoldResult, CalendarAttendee, CalendarAttendeeRole, CalendarCoverageAssessment, CalendarCoverageCommand, CalendarCoverageResult, CalendarEventContent, CalendarEventOccurrence, CalendarEventRetentionResult, CalendarEventStatus, CalendarFreeBusy, CalendarHorizonRollCursor, CalendarHorizonRollResult, CalendarOrganizer, CalendarParticipationStatus, CalendarRecurrence, CalendarRecurrenceException, CalendarReminder, CalendarTransparency, ConfirmHoldResult, CancelCalendarEventResult, CancelExternalReservationResult, CreateReservationResult, ExternalReservationCommand, ExternalReservationResult, Interval, SlotlockHold, SlotlockCalendarEvent, SlotlockReservation, SlotlockResource, PutCalendarEventCommand, PutCalendarEventResult, ReleaseHoldResult, TrustedICalendarEvent, WeeklyAvailabilityRule, } from './types.js';
+export { CalendarContractError, CalendarExpansionLimitError, emitICalendar, emitITipCalendar, expandCalendarEventOccurrences, normalizeCalendarEventContent, normalizeExternalCalendarChange, parseICalendarChanges, parseICalendarFeed, parseTrustedICalendarEvents, recurrenceRuleProblem, storedCalendarEventProblem, } from './sync.js';
+export type { ExternalCalendarChange, ExternalCalendarChangeInput, ExternalCalendarStatus, ICalendarEvent, ICalendarExpansionWindow, ICalendarFeedRead, ICalendarSeriesRefusal, ITipMethod, } from './sync.js';
+export { createSlotlockApplicationRoleGrantsDdl, createSlotlockTenantRlsDdl, SLOTLOCK_API_KEY_FUNCTIONS, SLOTLOCK_API_KEY_TABLES, SLOTLOCK_CORE_DDL, SLOTLOCK_DASHBOARD_FUNCTIONS, SLOTLOCK_DASHBOARD_TABLES, SLOTLOCK_DEFINER_FUNCTIONS, SLOTLOCK_DEFINER_TABLES, SLOTLOCK_OPERATOR_FUNCTIONS, SLOTLOCK_SCHEMA_FUNCTIONS, SLOTLOCK_SCHEMA_TABLES, SLOTLOCK_SCHEMA_VERSION, SLOTLOCK_TENANT_ADMIN_FUNCTIONS, SLOTLOCK_TENANT_ADMIN_TABLES, SLOTLOCK_TENANT_CONTEXT_SETTING, SLOTLOCK_TENANT_RLS_DDL, SLOTLOCK_TENANT_TABLES, } from './ddl.js';
+export { assertSlotlockSchemaCurrent, calendarEventRollingHorizon, createSlotlockStore, readSlotlockSchemaVersion, SLOTLOCK_AGENT_OWNER_COMMAND_QUOTA, SLOTLOCK_AGENT_OWNER_EVENT_QUOTA, SLOTLOCK_CALENDAR_HORIZON_DAYS, SLOTLOCK_EVENT_COMMAND_RETENTION_DAYS, SLOTLOCK_INTERNAL_EVENT_OWNER_REF, SLOTLOCK_LOCAL_RECURRENCE_COVERAGE_SOURCE, SLOTLOCK_MATERIALIZATION_WINDOW_DAYS, SLOTLOCK_MAX_EVENT_DURATION_DAYS, SLOTLOCK_TENANT_WRITE_METHODS, type SlotlockHoldTenantOptions, type SlotlockMigrationOptions, type SlotlockSql, type SlotlockStore, type SlotlockStoreOptions, type SlotlockTenantLimits, type SlotlockTenantStore, } from './store.js';
+export type { AcquireHoldResult, BookingRetentionResult, CalendarAttendee, CalendarAttendeeRole, CalendarCoverageAssessment, CalendarCoverageCommand, CalendarCoverageResult, CalendarEventContent, CalendarEventOccurrence, CalendarEventRetentionResult, CalendarEventStatus, CalendarFreeBusy, CalendarHorizonRollCursor, CalendarHorizonRollResult, CalendarOrganizer, CalendarParticipationStatus, CalendarRecurrence, CalendarRecurrenceException, CalendarReminder, CalendarTransparency, ConfirmHoldResult, CancelCalendarEventResult, CancelExternalReservationResult, CreateReservationResult, DeleteResourceResult, ExternalReservationCommand, ExternalReservationResult, Interval, SlotlockHold, SlotlockCalendarEvent, SlotlockReservation, SlotlockResource, SlotlockTenantErasure, PutCalendarEventCommand, PutCalendarEventResult, ReleaseHoldResult, TrustedICalendarEvent, WeeklyAvailabilityRule, } from './types.js';

package/index.js

@@ -7,12 +7,14 @@ export { findNextAvailable, mergeIntervals, subtractBusy } from './engine.js';
 export { expandRules } from './rules.js';
 export { availabilityRuleProblem, parseAvailabilityRules, rulesToWeeklyHours, SLOTLOCK_MAX_AVAILABILITY_RULES, weeklyHoursToRules, } from './weekly-hours.js';
 export { createTimeZoneConverter, zonedCalendarDate, zonedDateTimeToUtc, zonedWallTime, } from './timezone.js';
-export { createSlotlockAgentServer, clientSupportsSlotlockMcpApp, invokeSlotlockAgentOperation, isSlotlockAgentOperation, slotlockAgentTools, slotlockCalendarResourceUri, slotlockMcpToolResult, parseSlotlockA2ATimestamp, resolveSlotlockAgentOperation, slotlockAgentOperationScope, SLOTLOCK_A2A_PROTOCOL_VERSION, SLOTLOCK_A2A_TASK_PAGE_SIZE, SLOTLOCK_A2A_TASK_STATES, SLOTLOCK_AGENT_OPERATION_LEGACY_NAMES, SLOTLOCK_AGENT_SERVER_VERSION, SLOTLOCK_MCP_LEGACY_PROTOCOL_VERSION, SLOTLOCK_MCP_PROTOCOL_VERSION, SLOTLOCK_MCP_RATE_LIMITED_ERROR_CODE, SLOTLOCK_MCP_RESOURCE_URI_TEMPLATE, SLOTLOCK_MCP_SUPPORTED_PROTOCOL_VERSIONS, SLOTLOCK_MCP_APP_HTML, SLOTLOCK_MCP_APP_MIME_TYPE, SLOTLOCK_MCP_APP_RESOURCE, SLOTLOCK_MCP_APP_RESOURCE_URI, SLOTLOCK_MCP_APPS_EXTENSION, SlotlockAgentOperationError, } from './agent-server.js';
+export { createSlotlockAgentServer, clientSupportsSlotlockMcpApp, invokeSlotlockAgentOperation, isSlotlockAgentOperation, slotlockAgentTools, slotlockApplicationOperations, slotlockOpenApi, slotlockCalendarResourceUri, slotlockMcpToolResult, parseSlotlockA2ATimestamp, resolveSlotlockAgentOperation, slotlockAgentOperationScope, SLOTLOCK_A2A_PROTOCOL_VERSION, SLOTLOCK_A2A_TASK_PAGE_SIZE, SLOTLOCK_A2A_TASK_STATES, SLOTLOCK_AGENT_OPERATION_LEGACY_NAMES, SLOTLOCK_AGENT_SERVER_VERSION, SLOTLOCK_MCP_LEGACY_PROTOCOL_VERSION, SLOTLOCK_MCP_PROTOCOL_VERSION, SLOTLOCK_MCP_RATE_LIMITED_ERROR_CODE, SLOTLOCK_MCP_RESOURCE_URI_TEMPLATE, SLOTLOCK_MCP_SUPPORTED_PROTOCOL_VERSIONS, SLOTLOCK_MCP_APP_HTML, SLOTLOCK_MCP_APP_MIME_TYPE, SLOTLOCK_MCP_APP_RESOURCE, SLOTLOCK_MCP_APP_RESOURCE_URI, SLOTLOCK_MCP_APPS_EXTENSION, SlotlockAgentOperationError, } from './agent-server.js';
 export { createSlotlockNodeServer } from './node-server.js';
-export { createSlotlockStoreAgentBackend, projectSlotlockCalendarEvent } from './agent-store-backend.js';
+export { createSlotlockStoreAgentBackend, createSlotlockStoreApplicationBackend, projectSlotlockCalendarEvent, } from './agent-store-backend.js';
+export { SLOTLOCK_APPLICATION_OPERATIONS, SLOTLOCK_APPLICATION_SCOPE, isSlotlockApplicationOperation, } from './application-api.js';
+export { maintainSlotlockTenant, startSlotlockMaintenance, withSlotlockMaintenanceLock, } from './maintenance.js';
 export { createSlotlockApiKeyAuthenticator, createSlotlockApiKeyStore, generateSlotlockApiKey, isSlotlockApiKey, slotlockApiKeyDigest, SLOTLOCK_API_KEY_ACTIVE_LIMIT, SLOTLOCK_API_KEY_MAX_LIFETIME_DAYS, SLOTLOCK_API_KEY_PREFIX, SLOTLOCK_API_KEY_RETAINED_LIMIT, SLOTLOCK_API_KEY_SCOPES, } from './api-keys.js';
 export { createSlotlockDashboard, createSlotlockDashboardResources, createSlotlockDashboardState, createSlotlockMemoryDashboardState, SLOTLOCK_DASHBOARD_MAX_RESOURCES, } from './dashboard.js';
 export { ICalendarWorkerBusyError, ICalendarWorkerPoolClosedError, createICalendarWorkerPool, } from './ical-worker.js';
-export { CalendarContractError, CalendarExpansionLimitError, emitICalendar, emitITipCalendar, expandCalendarEventOccurrences, normalizeCalendarEventContent, normalizeExternalCalendarChange, parseICalendarChanges, parseTrustedICalendarEvents, } from './sync.js';
-export { createSlotlockApplicationRoleGrantsDdl, createSlotlockTenantRlsDdl, SLOTLOCK_API_KEY_FUNCTIONS, SLOTLOCK_API_KEY_TABLES, SLOTLOCK_CORE_DDL, SLOTLOCK_DASHBOARD_FUNCTIONS, SLOTLOCK_DASHBOARD_TABLES, SLOTLOCK_DEFINER_FUNCTIONS, SLOTLOCK_DEFINER_TABLES, SLOTLOCK_TENANT_CONTEXT_SETTING, SLOTLOCK_TENANT_RLS_DDL, SLOTLOCK_TENANT_TABLES, } from './ddl.js';
-export { calendarEventRollingHorizon, createSlotlockStore, SLOTLOCK_AGENT_OWNER_COMMAND_QUOTA, SLOTLOCK_AGENT_OWNER_EVENT_QUOTA, SLOTLOCK_CALENDAR_HORIZON_DAYS, SLOTLOCK_EVENT_COMMAND_RETENTION_DAYS, SLOTLOCK_INTERNAL_EVENT_OWNER_REF, SLOTLOCK_LOCAL_RECURRENCE_COVERAGE_SOURCE, SLOTLOCK_MAX_EVENT_DURATION_DAYS, } from './store.js';
+export { CalendarContractError, CalendarExpansionLimitError, emitICalendar, emitITipCalendar, expandCalendarEventOccurrences, normalizeCalendarEventContent, normalizeExternalCalendarChange, parseICalendarChanges, parseICalendarFeed, parseTrustedICalendarEvents, recurrenceRuleProblem, storedCalendarEventProblem, } from './sync.js';
+export { createSlotlockApplicationRoleGrantsDdl, createSlotlockTenantRlsDdl, SLOTLOCK_API_KEY_FUNCTIONS, SLOTLOCK_API_KEY_TABLES, SLOTLOCK_CORE_DDL, SLOTLOCK_DASHBOARD_FUNCTIONS, SLOTLOCK_DASHBOARD_TABLES, SLOTLOCK_DEFINER_FUNCTIONS, SLOTLOCK_DEFINER_TABLES, SLOTLOCK_OPERATOR_FUNCTIONS, SLOTLOCK_SCHEMA_FUNCTIONS, SLOTLOCK_SCHEMA_TABLES, SLOTLOCK_SCHEMA_VERSION, SLOTLOCK_TENANT_ADMIN_FUNCTIONS, SLOTLOCK_TENANT_ADMIN_TABLES, SLOTLOCK_TENANT_CONTEXT_SETTING, SLOTLOCK_TENANT_RLS_DDL, SLOTLOCK_TENANT_TABLES, } from './ddl.js';
+export { assertSlotlockSchemaCurrent, calendarEventRollingHorizon, createSlotlockStore, readSlotlockSchemaVersion, SLOTLOCK_AGENT_OWNER_COMMAND_QUOTA, SLOTLOCK_AGENT_OWNER_EVENT_QUOTA, SLOTLOCK_CALENDAR_HORIZON_DAYS, SLOTLOCK_EVENT_COMMAND_RETENTION_DAYS, SLOTLOCK_INTERNAL_EVENT_OWNER_REF, SLOTLOCK_LOCAL_RECURRENCE_COVERAGE_SOURCE, SLOTLOCK_MATERIALIZATION_WINDOW_DAYS, SLOTLOCK_MAX_EVENT_DURATION_DAYS, SLOTLOCK_TENANT_WRITE_METHODS, } from './store.js';

package/maintenance.d.ts

@@ -0,0 +1,67 @@
+import type { Sql } from 'postgres';
+import { type SlotlockStore } from './store.js';
+export interface SlotlockMaintenanceResult {
+    /** Recurring events whose stored occurrences now reach the horizon. */
+    extended: number;
+    /** Series that could not extend because an occurrence would overlap a booking. */
+    conflicts: number;
+    /** Series over the expansion budget, or whose roll failed otherwise; they keep their old coverage. */
+    refused: number;
+    /**
+     * Expired holds and the answers kept for keyed ones, and past the retention window event
+     * idempotency answers, agents' event cancellations and booking references retired with no
+     * booking, deleted. A cancelled booking's tombstone stays.
+     */
+    pruned: number;
+    /** More was left than one pass does: run another. */
+    capped: boolean;
+    /**
+     * The roll stopped before the series it had put back: series it has not tried since may still
+     * extend, so another pass should follow at once.
+     */
+    rollPending: boolean;
+}
+/**
+ * One maintenance pass for a tenant: roll its recurring events to the rolling horizon, then purge
+ * its expired holds with their answers and prune its events' and bookings' bookkeeping past the
+ * retention window, each in at most `batches` batches (1-100, default 10), every batch its own
+ * transaction. Aborting `signal` stops it between batches with the signal's reason.
+ */
+export declare function maintainSlotlockTenant(store: SlotlockStore, tenantRef: string, options?: {
+    batches?: number;
+    signal?: AbortSignal;
+}): Promise<SlotlockMaintenanceResult>;
+/**
+ * Run `work` holding the tenant's maintenance lock on a connection of its own, or return
+ * `undefined` without running it when another server holds the lock.
+ */
+export declare function withSlotlockMaintenanceLock<T>(sql: Sql, tenantRef: string, work: () => Promise<T>): Promise<T | undefined>;
+export interface SlotlockMaintenanceScheduler {
+    /**
+     * A tenant the server just served. Unless it was maintained within the interval, it is queued
+     * now, and from then on maintained every interval with the others.
+     */
+    touch(tenantRef: string): void;
+    /** Stop: no new pass starts, and the one running finishes first. */
+    close(): Promise<void>;
+}
+export interface SlotlockMaintenanceSchedulerOptions {
+    store: SlotlockStore;
+    sql: Sql;
+    /** Tenants maintained from the start, whether or not a key of theirs calls. */
+    tenants: readonly string[];
+    /** How often each tenant is maintained, at most a day. */
+    intervalMs: number;
+    /** Tenants remembered; the one served longest ago is forgotten first. Default 10,000. */
+    maxTenants?: number;
+    /** Batches of each task per pass (maintainSlotlockTenant). */
+    batches?: number;
+    /** A pass that ran: counts only, never the tenant. Not awaited; what it throws is ignored. */
+    onPass?: (result: SlotlockMaintenanceResult) => void;
+    /**
+     * A pass that failed. The scheduler carries on with the next tenant. Not awaited; what it throws,
+     * or its promise rejects with, is ignored.
+     */
+    onError?: (error: unknown) => void;
+}
+export declare function startSlotlockMaintenance(options: SlotlockMaintenanceSchedulerOptions): SlotlockMaintenanceScheduler;

package/maintenance.js

@@ -0,0 +1,213 @@
+import { ignoreRejection } from './hooks.js';
+import { calendarEventRollingHorizon } from './store.js';
+/**
+ * One maintenance pass for a tenant: roll its recurring events to the rolling horizon, then purge
+ * its expired holds with their answers and prune its events' and bookings' bookkeeping past the
+ * retention window, each in at most `batches` batches (1-100, default 10), every batch its own
+ * transaction. Aborting `signal` stops it between batches with the signal's reason.
+ */
+export async function maintainSlotlockTenant(store, tenantRef, options = {}) {
+    const batches = options.batches ?? 10;
+    if (!(Number.isSafeInteger(batches) && batches >= 1 && batches <= 100)) {
+        throw new RangeError('batches must be a whole number from 1 to 100');
+    }
+    const window = calendarEventRollingHorizon();
+    let extended = 0;
+    let conflicts = 0;
+    let refused = 0;
+    let rollCapped = true;
+    let after = null;
+    // A roll that fails does not stop the pruning: expired holds are purged all the same, and the
+    // roll's error is thrown after.
+    let rollFailure = null;
+    try {
+        for (let batch = 0; batch < batches; batch++) {
+            options.signal?.throwIfAborted();
+            const from = after;
+            const roll = await store.withTenant(tenantRef, (tenant) => tenant.rollCalendarEventHorizon({ tenantRef, window, ...(from ? { after: from } : {}) }));
+            extended += roll.extended;
+            conflicts += roll.conflicts;
+            refused += roll.refused;
+            after = roll.next;
+            if (!after) {
+                rollCapped = false;
+                break;
+            }
+        }
+    }
+    catch (error) {
+        if (options.signal?.aborted)
+            throw error;
+        rollFailure = { error };
+    }
+    let pruned = 0;
+    let eventsLeft = true;
+    let bookingsLeft = true;
+    for (let batch = 0; batch < batches && (eventsLeft || bookingsLeft); batch++) {
+        options.signal?.throwIfAborted();
+        if (eventsLeft) {
+            const prune = await store.withTenant(tenantRef, (tenant) => tenant.pruneCalendarEventRetention({ tenantRef }));
+            pruned += prune.commandsDeleted + prune.tombstonesDeleted;
+            eventsLeft = prune.hasMore;
+        }
+        if (bookingsLeft) {
+            const prune = await store.withTenant(tenantRef, (tenant) => tenant.pruneBookingRetention({ tenantRef }));
+            pruned += prune.expiredHoldsDeleted + prune.holdCommandsDeleted + prune.tombstonesDeleted;
+            bookingsLeft = prune.hasMore;
+        }
+    }
+    if (rollFailure)
+        throw rollFailure.error;
+    return {
+        extended,
+        conflicts,
+        refused,
+        pruned,
+        capped: rollCapped || eventsLeft || bookingsLeft,
+        rollPending: rollCapped && after !== null && (after.rollRetryAt ?? null) === null,
+    };
+}
+/** The advisory lock key for one tenant's maintenance (64-bit, from the tenant reference). */
+const LOCK_NAMESPACE = 'slotlock.maintenance:';
+/**
+ * Run `work` holding the tenant's maintenance lock on a connection of its own, or return
+ * `undefined` without running it when another server holds the lock.
+ */
+export async function withSlotlockMaintenanceLock(sql, tenantRef, work) {
+    const reserved = await sql.reserve();
+    try {
+        const key = `${LOCK_NAMESPACE}${tenantRef}`;
+        const [row] = await reserved `
+      SELECT pg_catalog.pg_try_advisory_lock(pg_catalog.hashtextextended(${key}, 0)) AS locked`;
+        if (!row?.locked)
+            return undefined;
+        try {
+            return await work();
+        }
+        finally {
+            await reserved `SELECT pg_catalog.pg_advisory_unlock(pg_catalog.hashtextextended(${key}, 0))`;
+        }
+    }
+    finally {
+        reserved.release();
+    }
+}
+const DAY_MS = 86_400_000;
+export function startSlotlockMaintenance(options) {
+    const { intervalMs } = options;
+    if (!(Number.isSafeInteger(intervalMs) && intervalMs >= 1_000 && intervalMs <= DAY_MS)) {
+        throw new RangeError('intervalMs must be from one second to one day');
+    }
+    const maxTenants = options.maxTenants ?? 10_000;
+    /** Configured tenants, never forgotten: tenant reference to when its last pass finished (0: never). */
+    const pinned = new Map(options.tenants.map((tenantRef) => [tenantRef, 0]));
+    /** Served tenants, in the order last served; the oldest is forgotten past `maxTenants`. */
+    const served = new Map();
+    const queue = [];
+    /** Tenants waiting or in a pass: a tenant served during its own pass is not queued again. */
+    const queued = new Set();
+    const controller = new AbortController();
+    let working = null;
+    const lastPass = (tenantRef) => pinned.get(tenantRef) ?? served.get(tenantRef);
+    const recordPass = (tenantRef, finishedAt) => {
+        if (pinned.has(tenantRef))
+            pinned.set(tenantRef, finishedAt);
+        else if (served.has(tenantRef))
+            served.set(tenantRef, finishedAt);
+    };
+    const due = (tenantRef) => Date.now() - (lastPass(tenantRef) ?? 0) >= intervalMs;
+    const enqueue = (tenantRef) => {
+        if (controller.signal.aborted || queued.has(tenantRef))
+            return;
+        queued.add(tenantRef);
+        queue.push(tenantRef);
+        if (!working)
+            working = drain();
+    };
+    const drain = async () => {
+        try {
+            for (;;) {
+                const tenantRef = queue.shift();
+                if (tenantRef === undefined || controller.signal.aborted)
+                    return;
+                let again = false;
+                try {
+                    const result = await withSlotlockMaintenanceLock(options.sql, tenantRef, () => maintainSlotlockTenant(options.store, tenantRef, {
+                        ...(options.batches !== undefined ? { batches: options.batches } : {}),
+                        signal: controller.signal,
+                    }));
+                    recordPass(tenantRef, Date.now());
+                    if (result) {
+                        try {
+                            ignoreRejection(options.onPass?.(result));
+                        }
+                        catch {
+                            // Reporting must never stop maintenance, or make a pass that ran look failed.
+                        }
+                        // A capped pass that got somewhere goes round again at once, as does one whose roll
+                        // stopped before the series it had put back: each series it could not extend is now
+                        // behind every one it has not tried (the store puts it there), so the next pass meets
+                        // new ones, and however many are stuck, each is met once before a healthy one is
+                        // reached. A pass that reached the series put back waits for the next interval: they
+                        // take turns there, and the next pass reaches anything new before them.
+                        const progressed = result.extended + result.pruned > 0;
+                        again = result.capped && (progressed || result.rollPending);
+                    }
+                }
+                catch (error) {
+                    if (controller.signal.aborted)
+                        return;
+                    recordPass(tenantRef, Date.now());
+                    try {
+                        ignoreRejection(options.onError?.(error));
+                    }
+                    catch {
+                        // Reporting must never stop maintenance.
+                    }
+                }
+                finally {
+                    queued.delete(tenantRef);
+                }
+                if (again)
+                    enqueue(tenantRef);
+            }
+        }
+        finally {
+            working = null;
+        }
+    };
+    const tick = () => {
+        for (const tenantRef of [...pinned.keys(), ...served.keys()]) {
+            if (due(tenantRef))
+                enqueue(tenantRef);
+        }
+    };
+    const timer = setInterval(tick, Math.min(intervalMs, 60_000));
+    timer.unref();
+    tick();
+    return {
+        touch(tenantRef) {
+            if (controller.signal.aborted || pinned.has(tenantRef)) {
+                if (pinned.has(tenantRef) && due(tenantRef))
+                    enqueue(tenantRef);
+                return;
+            }
+            const previous = served.get(tenantRef);
+            served.delete(tenantRef);
+            served.set(tenantRef, previous ?? 0);
+            while (served.size > maxTenants) {
+                const forgotten = served.keys().next().value;
+                served.delete(forgotten);
+            }
+            if (due(tenantRef))
+                enqueue(tenantRef);
+        },
+        async close() {
+            clearInterval(timer);
+            controller.abort(new Error('Slotlock maintenance stopped'));
+            queue.length = 0;
+            queued.clear();
+            await working;
+        },
+    };
+}