slotlock 0.1.1 → 0.2.0

package/dashboard.js

@@ -14,6 +14,7 @@
 // is held in the database too.
 import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
 import { SLOTLOCK_DASHBOARD_FORM_LIMIT } from './ddl.js';
+import { ignoreRejection } from './hooks.js';
 import { WEEKDAYS, WEEKDAY_NAMES as DAY_NAMES, rulesToWeeklyHours, weeklyHoursToRules, } from './weekly-hours.js';
 /** Resources one dashboard tenant may hold. */
 export const SLOTLOCK_DASHBOARD_MAX_RESOURCES = 100;
@@ -54,6 +55,7 @@ const DAY_MS = 86_400_000;
 const KEY_ACCESS = Object.freeze({
     read: ['read'],
     read_write: ['read', 'write'],
+    full: ['read', 'write', 'admin'],
 });
 const KEY_EXPIRY_DAYS = Object.freeze({
     never: null,
@@ -432,7 +434,7 @@ export function createSlotlockDashboard(options) {
     let signInsInFlight = 0;
     function report(message) {
         try {
-            options.onError?.(new Error(message));
+            ignoreRejection(options.onError?.(new Error(message)));
         }
         catch {
             // A failing reporter must not change the response.
@@ -559,7 +561,7 @@ ${notice ? html `<p class="notice" role="alert">${notice}</p>` : html ``}
             return html `<tr>
 <td data-label="Name">${key.name}</td>
 <td data-label="Key"><code>${key.prefix}…</code></td>
-<td data-label="Access">${key.scopes.includes('write') ? 'Read and write' : 'Read only'}</td>
+<td data-label="Access">${key.scopes.includes('admin') ? 'Full' : key.scopes.includes('write') ? 'Read and write' : 'Read only'}</td>
 <td data-label="Created">${formatDate(key.createdAt)}</td>
 <td data-label="Last used">${key.lastUsedAt ? formatDate(key.lastUsedAt) : 'Never'}</td>
 <td data-label="Expires">${key.expiresAt ? formatDate(key.expiresAt) : 'Never'}</td>
@@ -588,7 +590,7 @@ ${notice ? html `<p class="notice" role="alert">${notice}</p>` : html ``}
 <input type="hidden" name="csrf" value="${token}">
 <input type="hidden" name="once" value="${formNonce(session)}">
 <label>Name<input name="name" required maxlength="100" placeholder="Booking agent"></label>
-<label>Access<select name="access"><option value="read_write">Read and write</option><option value="read">Read only</option></select></label>
+<label>Access<select name="access"><option value="read_write">Read and write</option><option value="read">Read only</option><option value="full">Full, with the application API</option></select></label>
 <label>Expires<select name="expires"><option value="90">In 90 days</option><option value="30">In 30 days</option><option value="365">In a year</option><option value="never">Never</option></select></label>
 <button class="primary" type="submit">Create key</button>
 </form>
@@ -1089,7 +1091,7 @@ ${state.unshown
             }
             catch (error) {
                 try {
-                    options.onError?.(error);
+                    ignoreRejection(options.onError?.(error));
                 }
                 catch {
                     // A failing reporter must not change the response.

package/ddl.d.ts

@@ -31,7 +31,8 @@ export declare const SLOTLOCK_CORE_DDL: string;
 export declare const SLOTLOCK_TENANT_CONTEXT_SETTING = "slotlock.tenant_ref";
 /**
  * Every table the store reads or writes at runtime, each under forced tenant RLS.
- * `slotlock.rls_policy_contracts` is deployment-only and deliberately absent.
+ * `slotlock.rls_policy_contracts` and `slotlock.deployment_lifted_row_security` are
+ * deployment-only and deliberately absent.
  */
 export declare const SLOTLOCK_TENANT_TABLES: readonly ["resources", "reservations", "reservation_tombstones", "reservation_conflict_archive", "calendar_events", "calendar_event_attendees", "calendar_event_reminders", "calendar_event_exceptions", "calendar_event_occurrences", "calendar_event_tombstones", "calendar_event_commands", "calendar_coverage"];
 /**

package/ddl.js

@@ -18,6 +18,58 @@ SELECT pg_catalog.set_config('search_path', 'pg_catalog, pg_temp', true);
 `;
 const DEPLOYMENT_SEARCH_PATH_RESTORE = `SELECT pg_catalog.set_config('search_path', pg_catalog.current_setting('${CALLER_SEARCH_PATH_SETTING}'), true);
 `;
+// applyTenantRls forces row-level security, which binds the table owner too, and the deployment
+// sets no tenant: its data steps (reaping holds and listing conflicts before the overlap
+// constraint, merging duplicate resources, binding archives, backfilling event children) would see
+// no rows, skip what they repair and leave a constraint to meet rows its own check never saw. The
+// deployment lifts FORCE from the tables that have it before its first data step and puts it back
+// after its last, on those tables only. applySchema runs both in one transaction, which holds the
+// tables locked in between; a failure rolls the lift back with everything else. Run statement by
+// statement, the lift commits on its own and a refused data step stops the run before the restore,
+// so the tables lifted are recorded in a table, not the session: the next deployment, from any
+// session or connection, puts FORCE back on every table recorded, and `slotlock serve` refuses to
+// start while a tenant table is left without it.
+const DEPLOYMENT_LIFT_FORCED_ROW_SECURITY = `CREATE TABLE IF NOT EXISTS slotlock.deployment_lifted_row_security (
+  table_name text PRIMARY KEY
+);
+REVOKE ALL ON slotlock.deployment_lifted_row_security FROM PUBLIC;
+DO $slotlock_lift_forced_row_security$
+DECLARE
+  forced_table text;
+BEGIN
+  INSERT INTO slotlock.deployment_lifted_row_security (table_name)
+  SELECT rel.relname::text
+    FROM pg_catalog.pg_class rel
+    JOIN pg_catalog.pg_namespace ns ON ns.oid = rel.relnamespace
+   WHERE ns.nspname = 'slotlock' AND rel.relkind IN ('r', 'p') AND rel.relforcerowsecurity
+  ON CONFLICT (table_name) DO NOTHING;
+  FOR forced_table IN
+    SELECT rel.relname::text
+      FROM pg_catalog.pg_class rel
+      JOIN pg_catalog.pg_namespace ns ON ns.oid = rel.relnamespace
+     WHERE ns.nspname = 'slotlock' AND rel.relkind IN ('r', 'p') AND rel.relforcerowsecurity
+     ORDER BY rel.relname
+  LOOP
+    EXECUTE pg_catalog.format('ALTER TABLE slotlock.%I NO FORCE ROW LEVEL SECURITY', forced_table);
+  END LOOP;
+END
+$slotlock_lift_forced_row_security$;
+`;
+const DEPLOYMENT_RESTORE_FORCED_ROW_SECURITY = `DO $slotlock_restore_forced_row_security$
+DECLARE
+  forced_table text;
+BEGIN
+  FOR forced_table IN
+    SELECT table_name FROM slotlock.deployment_lifted_row_security ORDER BY table_name
+  LOOP
+    IF pg_catalog.to_regclass(pg_catalog.format('slotlock.%I', forced_table)) IS NOT NULL THEN
+      EXECUTE pg_catalog.format('ALTER TABLE slotlock.%I FORCE ROW LEVEL SECURITY', forced_table);
+    END IF;
+  END LOOP;
+  DELETE FROM slotlock.deployment_lifted_row_security;
+END
+$slotlock_restore_forced_row_security$;
+`;
 /** The start of the message with which the deployment DDL refuses a `slotlock` schema. */
 export const SLOTLOCK_SCHEMA_CONTROL_REFUSAL = 'Slotlock will not deploy into schema slotlock';
 // Every slotlock.<name> the deployment uses resolves in that schema, and the deployment writes rows
@@ -191,8 +243,13 @@ CREATE TABLE IF NOT EXISTS slotlock.api_keys (
   CONSTRAINT slotlock_api_keys_name_valid
     CHECK (char_length(name) BETWEEN 1 AND 100 AND name !~ '[[:cntrl:]]'),
   CONSTRAINT slotlock_api_keys_prefix_valid CHECK (prefix ~ '^slk_[0-9A-Za-z]{8}$'),
-  CONSTRAINT slotlock_api_keys_scopes_valid
-    CHECK (scopes IN (ARRAY['read']::text[], ARRAY['write']::text[], ARRAY['read', 'write']::text[])),
+  -- A non-empty list of read, write and admin, each once, in that order (api-keys.ts).
+  CONSTRAINT slotlock_api_keys_scopes_known
+    CHECK (scopes IN (
+      ARRAY['read']::text[], ARRAY['write']::text[], ARRAY['admin']::text[],
+      ARRAY['read', 'write']::text[], ARRAY['read', 'admin']::text[], ARRAY['write', 'admin']::text[],
+      ARRAY['read', 'write', 'admin']::text[]
+    )),
   CONSTRAINT slotlock_api_keys_created_by_valid
     CHECK (created_by IS NULL OR (octet_length(created_by) BETWEEN 1 AND 200
                                   AND created_by !~ '[[:cntrl:]]')),
@@ -204,6 +261,27 @@ CREATE TABLE IF NOT EXISTS slotlock.api_keys (
 CREATE INDEX IF NOT EXISTS slotlock_api_keys_tenant_idx
   ON slotlock.api_keys (tenant_ref, created_at DESC, id DESC);
 ALTER TABLE slotlock.api_keys ENABLE ROW LEVEL SECURITY;
+
+-- Schemas from 0.1 allow only read and write. The CHECK with admin admits every row the old one
+-- did, so it is added NOT VALID (no table scan under the lock) and the old one dropped in the same
+-- transaction.
+DO $slotlock_api_key_scopes$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint
+     WHERE conname = 'slotlock_api_keys_scopes_known'
+       AND conrelid = 'slotlock.api_keys'::regclass
+  ) THEN
+    ALTER TABLE slotlock.api_keys
+      ADD CONSTRAINT slotlock_api_keys_scopes_known CHECK (scopes IN (
+      ARRAY['read']::text[], ARRAY['write']::text[], ARRAY['admin']::text[],
+      ARRAY['read', 'write']::text[], ARRAY['read', 'admin']::text[], ARRAY['write', 'admin']::text[],
+      ARRAY['read', 'write', 'admin']::text[]
+    )) NOT VALID;
+  END IF;
+  ALTER TABLE slotlock.api_keys DROP CONSTRAINT IF EXISTS slotlock_api_keys_scopes_valid;
+END
+$slotlock_api_key_scopes$;
 REVOKE ALL ON slotlock.api_keys FROM PUBLIC;
 
 CREATE TABLE IF NOT EXISTS slotlock.api_key_retired_digests (
@@ -496,7 +574,7 @@ REVOKE ALL ON FUNCTION ${SLOTLOCK_DASHBOARD_FUNCTIONS[1]} FROM PUBLIC;
 export const SLOTLOCK_CORE_DDL = `
 ${DEPLOYMENT_SEARCH_PATH_PIN}CREATE SCHEMA IF NOT EXISTS slotlock;
 ${SLOTLOCK_SCHEMA_CONTROL_CHECK}CREATE EXTENSION IF NOT EXISTS btree_gist SCHEMA slotlock;
-
+${DEPLOYMENT_LIFT_FORCED_ROW_SECURITY}
 -- Records the exact catalog representation installed for each owned RLS policy. Health checks
 -- compare live policy fingerprints with this contract so ALTER POLICY drift cannot hide behind a
 -- retained name/comment. This table contains configuration only, never tenant or calendar data.
@@ -552,7 +630,7 @@ CREATE TABLE IF NOT EXISTS slotlock.reservations (
   ),
   CONSTRAINT slotlock_reservations_no_overlap EXCLUDE USING gist (
     resource_id WITH =,
-    tstzrange(starts_at, ends_at, '[)') WITH &&
+    tstzrange(starts_at, COALESCE(occupied_ends_at, ends_at), '[)') WITH &&
   )
 );
 
@@ -749,10 +827,6 @@ CREATE UNIQUE INDEX IF NOT EXISTS slotlock_resources_legacy_external_ref_key
   ON slotlock.resources (external_ref)
   WHERE tenant_ref IS NULL AND external_ref IS NOT NULL;
 
-CREATE UNIQUE INDEX IF NOT EXISTS slotlock_reservations_tenant_external_ref_key
-  ON slotlock.reservations (tenant_ref, external_ref)
-  WHERE tenant_ref IS NOT NULL AND external_ref IS NOT NULL;
-
 DO $$
 BEGIN
   IF NOT EXISTS (
@@ -855,18 +929,62 @@ BEGIN
         buffer_after_ms >= 0 AND buffer_after_ms <= 2592000000
       ) NOT VALID;
   END IF;
+END $$;
+
+-- Every row occupies from its start to its occupied end: its end plus its turnaround buffer. Up to
+-- 0.1 the buffer bound only tenant-owned bookings to each other (slotlock_reservations_buffered_no_overlap),
+-- so a hold could take a booking's buffer and a buffered booking could cover a hold. The upgrade
+-- reaps expired holds in the way, as the next writer would, then refuses to go on while a live row
+-- is in the way: a constraint is never made to fit by deleting a booking or a live hold. Rows from
+-- before the occupied-end trigger may lack occupied_ends_at; their end is where they stop.
+DO $slotlock_occupied_overlap$
+DECLARE
+  conflicts bigint;
+  examples text;
+BEGIN
   IF NOT EXISTS (
     SELECT 1 FROM pg_constraint
-     WHERE conname = 'slotlock_reservations_buffered_no_overlap'
+     WHERE conname = 'slotlock_reservations_no_overlap'
        AND conrelid = 'slotlock.reservations'::regclass
+       AND pg_catalog.pg_get_constraintdef(oid) LIKE '%occupied_ends_at%'
   ) THEN
+    DELETE FROM slotlock.reservations hold
+     USING slotlock.reservations buffered
+     WHERE hold.status = 'held'
+       AND hold.expires_at <= now()
+       AND buffered.resource_id = hold.resource_id
+       AND buffered.id <> hold.id
+       AND buffered.buffer_after_ms > 0
+       AND tstzrange(buffered.starts_at, COALESCE(buffered.occupied_ends_at, buffered.ends_at), '[)')
+           && tstzrange(hold.starts_at, hold.ends_at, '[)');
+    SELECT count(*),
+           string_agg(buffered.id::text || ' and ' || other.id::text, ', ' ORDER BY buffered.id, other.id)
+      INTO conflicts, examples
+      FROM slotlock.reservations buffered
+      JOIN slotlock.reservations other
+        ON other.resource_id = buffered.resource_id
+       AND other.id <> buffered.id
+       AND tstzrange(buffered.starts_at, COALESCE(buffered.occupied_ends_at, buffered.ends_at), '[)')
+           && tstzrange(other.starts_at, COALESCE(other.occupied_ends_at, other.ends_at), '[)')
+     WHERE buffered.buffer_after_ms > 0
+       -- A pair of buffered rows counts once.
+       AND (other.buffer_after_ms = 0 OR buffered.id < other.id);
+    IF conflicts > 0 THEN
+      RAISE EXCEPTION 'Slotlock cannot upgrade: % reservations or holds overlap another''s turnaround buffer', conflicts
+        USING ERRCODE = '23P01',
+              DETAIL = 'Reservation ids, in pairs: ' || left(examples, 2000),
+              HINT = 'Move, cancel or release one of each pair (slotlock.reservations), then migrate again.';
+    END IF;
+    ALTER TABLE slotlock.reservations DROP CONSTRAINT IF EXISTS slotlock_reservations_no_overlap;
     ALTER TABLE slotlock.reservations
-      ADD CONSTRAINT slotlock_reservations_buffered_no_overlap EXCLUDE USING gist (
+      ADD CONSTRAINT slotlock_reservations_no_overlap EXCLUDE USING gist (
         resource_id WITH =,
-        tstzrange(starts_at, occupied_ends_at, '[)') WITH &&
-      ) WHERE (tenant_ref IS NOT NULL);
+        tstzrange(starts_at, COALESCE(occupied_ends_at, ends_at), '[)') WITH &&
+      );
   END IF;
-END $$;
+  ALTER TABLE slotlock.reservations DROP CONSTRAINT IF EXISTS slotlock_reservations_buffered_no_overlap;
+END
+$slotlock_occupied_overlap$;
 
 CREATE INDEX IF NOT EXISTS slotlock_reservations_resource_time_idx
   ON slotlock.reservations (resource_id, starts_at, ends_at);
@@ -1279,6 +1397,15 @@ BEGIN
   END IF;
 END $$;
 
+-- A booking's reference is unique in its tenant. The rows a calendar event occupies carry a
+-- reference derived from the event in the same columns, but they are not bookings and are left out:
+-- a booking with the same reference neither collides with one nor answers for it. Up to 0.1 one
+-- index covered both; every row it admitted, this one admits.
+CREATE UNIQUE INDEX IF NOT EXISTS slotlock_reservations_booking_external_ref_key
+  ON slotlock.reservations (tenant_ref, external_ref)
+  WHERE tenant_ref IS NOT NULL AND external_ref IS NOT NULL AND calendar_event_id IS NULL;
+DROP INDEX IF EXISTS slotlock.slotlock_reservations_tenant_external_ref_key;
+
 -- Materialized occurrences point at reservations created under the SAME exclusion arbiter as
 -- bookings and holds. Transparent events retain occurrence visibility with a NULL reservation.
 CREATE TABLE IF NOT EXISTS slotlock.calendar_event_occurrences (
@@ -1454,11 +1581,12 @@ CREATE INDEX IF NOT EXISTS slotlock_calendar_event_occurrences_resource_time_idx
   ON slotlock.calendar_event_occurrences (tenant_ref, starts_at, ends_at);
 CREATE INDEX IF NOT EXISTS slotlock_reservations_calendar_event_idx
   ON slotlock.reservations (calendar_event_id) WHERE calendar_event_id IS NOT NULL;
-${SLOTLOCK_API_KEYS_DDL}${SLOTLOCK_DASHBOARD_DDL}${DEPLOYMENT_SEARCH_PATH_RESTORE}`;
+${SLOTLOCK_API_KEYS_DDL}${SLOTLOCK_DASHBOARD_DDL}${DEPLOYMENT_RESTORE_FORCED_ROW_SECURITY}${DEPLOYMENT_SEARCH_PATH_RESTORE}`;
 export const SLOTLOCK_TENANT_CONTEXT_SETTING = 'slotlock.tenant_ref';
 /**
  * Every table the store reads or writes at runtime, each under forced tenant RLS.
- * `slotlock.rls_policy_contracts` is deployment-only and deliberately absent.
+ * `slotlock.rls_policy_contracts` and `slotlock.deployment_lifted_row_security` are
+ * deployment-only and deliberately absent.
  */
 export const SLOTLOCK_TENANT_TABLES = Object.freeze([
     'resources',

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/index.d.ts

@@ -5,12 +5,16 @@ 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';
@@ -20,5 +24,5 @@ export type { ICalendarWorkerPool, ICalendarWorkerPoolOptions } from './ical-wor
 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 { 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 SlotlockHoldTenantOptions, 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';

package/index.js

@@ -7,9 +7,11 @@ 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';

package/maintenance.d.ts

@@ -0,0 +1,57 @@
+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; they keep their old coverage. */
+    refused: number;
+    /** Idempotency commands and tombstones deleted. */
+    pruned: number;
+    /** More was left than one pass does: run another. */
+    capped: boolean;
+}
+/**
+ * One maintenance pass for a tenant: roll its recurring events to the rolling horizon, then prune
+ * 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,181 @@
+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 prune
+ * 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;
+    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;
+        }
+    }
+    let pruned = 0;
+    let pruneCapped = true;
+    for (let batch = 0; batch < batches; batch++) {
+        options.signal?.throwIfAborted();
+        const prune = await store.withTenant(tenantRef, (tenant) => tenant.pruneCalendarEventRetention({ tenantRef }));
+        pruned += prune.commandsDeleted + prune.tombstonesDeleted;
+        if (!prune.hasMore) {
+            pruneCapped = false;
+            break;
+        }
+    }
+    return { extended, conflicts, refused, pruned, capped: rollCapped || pruneCapped };
+}
+/** 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; one that only met series it
+                        // cannot extend waits for the next interval rather than examine them again and again.
+                        again = result.capped && result.extended + result.pruned > 0;
+                    }
+                }
+                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)
+                served.delete(served.keys().next().value);
+            if (due(tenantRef))
+                enqueue(tenantRef);
+        },
+        async close() {
+            clearInterval(timer);
+            controller.abort(new Error('Slotlock maintenance stopped'));
+            queue.length = 0;
+            queued.clear();
+            await working;
+        },
+    };
+}