slotlock 0.5.2 → 0.6.0

package/event-feed.d.ts

@@ -1,8 +1,47 @@
 import type { Sql, TransactionSql } from 'postgres';
 type SlotlockSql = Sql | TransactionSql;
 /** What a change can be, as the feed and a webhook's `event_types` name it. */
-export declare const SLOTLOCK_CHANGE_TYPES: readonly ["hold.created", "hold.updated", "hold.confirmed", "hold.released", "hold.expired", "reservation.created", "reservation.updated", "reservation.cancelled", "reservation.checked_in", "reservation.no_show", "event.created", "event.updated", "event.cancelled", "event.timezone_shifted", "event.timezone_conflict", "coverage.stale", "waitlist.offered", "waitlist.expired", "webhook.disabled"];
+export declare const SLOTLOCK_CHANGE_TYPES: readonly ["hold.created", "hold.updated", "hold.confirmed", "hold.released", "hold.expired", "reservation.created", "reservation.updated", "reservation.cancelled", "reservation.checked_in", "reservation.no_show", "event.created", "event.updated", "event.cancelled", "event.timezone_shifted", "event.timezone_conflict", "coverage.stale", "waitlist.offered", "waitlist.expired", "webhook.disabled", "resource.created", "resource.updated", "resource.archived", "resource.restored", "resource.deleted", "coverage.recorded", "coverage.deleted", "webhook.created", "webhook.enabled", "webhook.deleted", "key.created", "key.rotated", "key.revoked"];
 export type SlotlockChangeType = (typeof SLOTLOCK_CHANGE_TYPES)[number];
+/**
+ * Where a change came from, as the history and the feed record it (withTenant's `origin`): an agent
+ * protocol (`mcp`, `a2a`), the REST API's agent routes (`rest`) or its application operations
+ * (`application`), the dashboard, a member's dashboard assistant, maintenance, or code calling the
+ * store itself (`library`). Never an address or anything else about a person.
+ */
+export declare const SLOTLOCK_CHANGE_ORIGINS: readonly ["mcp", "a2a", "rest", "application", "dashboard", "dashboard-assistant", "maintenance", "library"];
+export type SlotlockChangeOrigin = (typeof SLOTLOCK_CHANGE_ORIGINS)[number];
+/** Whether `value` is one of SLOTLOCK_CHANGE_ORIGINS. */
+export declare function isSlotlockChangeOrigin(value: unknown): value is SlotlockChangeOrigin;
+/**
+ * The digest 0.5.3 named a coverage source by on the feed: `src_` and the first 24 hex digits of
+ * sha256(tenant, newline, source). Unkeyed, so anyone who knows the tenant could confirm a guessed
+ * source against it; 0.6 names a source by a random id instead (`calendar_coverage.source_id`), and
+ * the upgrade uses this only to find the changes 0.5.3 wrote and rename them. `tenant` and `source`
+ * are SQL expressions.
+ */
+export declare function legacyCoverageSourceDigestSql(tenant: string, source: string): string;
+/**
+ * 0.5.3 worked out a source's id here: an unkeyed digest of the tenant and the source, which let
+ * anyone who saw a change confirm a guessed source. Since 0.6 a source's `source_id` is random and
+ * only the database knows it, so this throws (`coverage_source_id_unavailable`) rather than give a
+ * digest nothing carries any more.
+ *
+ * @deprecated Read `sourceId` from `listCoverage` (`source_id` of `slotlock_get_coverage`). It may
+ * be removed in 0.7.0.
+ */
+export declare function slotlockCoverageSourceId(_tenantRef: string, _source: string): never;
+/**
+ * A change's subject and data as the feed serves them. A `coverage.*` change never carries its
+ * source (`source`) or the error read from it (`last_error`, which can quote it), and is named by a
+ * `source_id` of this release or `src_redacted`: an earlier release wrote both, and the upgrade
+ * renames those rows in batches after it commits, so a row it has not reached yet, or one an
+ * earlier release's server writes during a rolling upgrade, is served redacted.
+ */
+export declare function slotlockServedChange(type: string, subject: string, data: Record<string, unknown>): {
+    subject: string;
+    data: Record<string, unknown>;
+};
 /** How long the feed keeps a change, and so how far back a cursor may reach. */
 export declare const SLOTLOCK_CHANGE_RETENTION_DAYS = 30;
 /** Webhook endpoints one tenant may have. */
@@ -20,6 +59,10 @@ export interface SlotlockChange {
     occurredAt: Date;
     /** Who made it (withTenant's `actor`: an API key, an agent), or null when unrecorded. */
     actor: string | null;
+    /** Where it came from (withTenant's `origin`), or null when unrecorded (before 0.6, say). */
+    origin: SlotlockChangeOrigin | null;
+    /** The API key that made it (withTenant's `keyId`), or null when no key did. */
+    keyId: string | null;
     /** Pass as `after` to read what follows this change. */
     position: string;
 }
@@ -150,9 +193,10 @@ export interface SlotlockEventFeed {
         };
     }): Promise<void>;
     /**
-     * History: the changes to one resource (`resourceId`) or one record (`subject`: a booking's
-     * reference, an event's or hold's id), newest first, `limit` (1-100) at a time, each with who
-     * made it and, for a change of an existing record, what it was before. Pass the last one's
+     * History: the changes to one resource (`resourceId`: its bookings and events, and its own
+     * configuration) or one record (`subject`: a booking's reference, an event's, hold's, webhook's or
+     * API key's id), newest first, `limit` (1-100) at a time, each with who made it (`actor`, `keyId`),
+     * where from (`origin`) and, for a change of an existing record, what it was before. Pass the last one's
      * `id` as `before` for the page after. Kept as long as the feed keeps changes.
      */
     listHistory(params: {
@@ -175,4 +219,10 @@ export declare function isWebhookUrl(value: unknown): value is string;
  * `retentionDays` (default SLOTLOCK_CHANGE_RETENTION_DAYS), and a cursor reaches back as far.
  */
 export declare function slotlockEventFeedMethods(sql: SlotlockSql, retentionDays?: number): SlotlockEventFeed;
+/**
+ * A position at or before every change that has not ended yet, so a reader that starts from it and
+ * follows `next` misses none still to come (it may read again some that ended just before). Live
+ * updates start here (agent-store-backend.ts, createSlotlockStoreChangeSource).
+ */
+export declare function slotlockChangeFeedHead(sql: SlotlockSql): Promise<string>;
 export {};

package/event-feed.js

@@ -28,7 +28,86 @@ export const SLOTLOCK_CHANGE_TYPES = Object.freeze([
     'waitlist.offered',
     'waitlist.expired',
     'webhook.disabled',
+    // Configuration: what a resource is and how it books, the sources it is read from, where the
+    // feed is delivered and the keys that reach the tenant. Ids and states, never a secret or a URL.
+    'resource.created',
+    'resource.updated',
+    'resource.archived',
+    'resource.restored',
+    'resource.deleted',
+    'coverage.recorded',
+    'coverage.deleted',
+    'webhook.created',
+    'webhook.enabled',
+    'webhook.deleted',
+    'key.created',
+    'key.rotated',
+    'key.revoked',
 ]);
+/**
+ * Where a change came from, as the history and the feed record it (withTenant's `origin`): an agent
+ * protocol (`mcp`, `a2a`), the REST API's agent routes (`rest`) or its application operations
+ * (`application`), the dashboard, a member's dashboard assistant, maintenance, or code calling the
+ * store itself (`library`). Never an address or anything else about a person.
+ */
+export const SLOTLOCK_CHANGE_ORIGINS = Object.freeze([
+    'mcp',
+    'a2a',
+    'rest',
+    'application',
+    'dashboard',
+    'dashboard-assistant',
+    'maintenance',
+    'library',
+]);
+/** Whether `value` is one of SLOTLOCK_CHANGE_ORIGINS. */
+export function isSlotlockChangeOrigin(value) {
+    return typeof value === 'string' && SLOTLOCK_CHANGE_ORIGINS.includes(value);
+}
+/**
+ * The digest 0.5.3 named a coverage source by on the feed: `src_` and the first 24 hex digits of
+ * sha256(tenant, newline, source). Unkeyed, so anyone who knows the tenant could confirm a guessed
+ * source against it; 0.6 names a source by a random id instead (`calendar_coverage.source_id`), and
+ * the upgrade uses this only to find the changes 0.5.3 wrote and rename them. `tenant` and `source`
+ * are SQL expressions.
+ */
+export function legacyCoverageSourceDigestSql(tenant, source) {
+    return `'src_' || pg_catalog.left(pg_catalog.encode(pg_catalog.sha256(pg_catalog.convert_to(${tenant} || E'\\n' || ${source}, 'UTF8')), 'hex'), 24)`;
+}
+/**
+ * 0.5.3 worked out a source's id here: an unkeyed digest of the tenant and the source, which let
+ * anyone who saw a change confirm a guessed source. Since 0.6 a source's `source_id` is random and
+ * only the database knows it, so this throws (`coverage_source_id_unavailable`) rather than give a
+ * digest nothing carries any more.
+ *
+ * @deprecated Read `sourceId` from `listCoverage` (`source_id` of `slotlock_get_coverage`). It may
+ * be removed in 0.7.0.
+ */
+export function slotlockCoverageSourceId(_tenantRef, _source) {
+    throw Object.assign(new Error("slotlockCoverageSourceId cannot work out a source's id since 0.6: it is random. Read sourceId from listCoverage (source_id of slotlock_get_coverage)"), { code: 'coverage_source_id_unavailable' });
+}
+/** What a coverage source's `source_id` is: `src_` and 32 random hex digits. */
+const SLOTLOCK_COVERAGE_SOURCE_ID = /^src_[0-9a-f]{32}$/;
+/**
+ * The `source_id` of a `coverage.*` change whose source could not be named any more: one an
+ * earlier release recorded by the source itself (or by its 0.5.3 digest) after the source was
+ * deleted, or one not yet renamed when it is read.
+ */
+const SLOTLOCK_REDACTED_SOURCE_ID = 'src_redacted';
+/**
+ * A change's subject and data as the feed serves them. A `coverage.*` change never carries its
+ * source (`source`) or the error read from it (`last_error`, which can quote it), and is named by a
+ * `source_id` of this release or `src_redacted`: an earlier release wrote both, and the upgrade
+ * renames those rows in batches after it commits, so a row it has not reached yet, or one an
+ * earlier release's server writes during a rolling upgrade, is served redacted.
+ */
+export function slotlockServedChange(type, subject, data) {
+    if (!type.startsWith('coverage.'))
+        return { subject, data };
+    const { source: _source, last_error: _lastError, ...rest } = data;
+    const sourceId = SLOTLOCK_COVERAGE_SOURCE_ID.test(subject) ? subject : SLOTLOCK_REDACTED_SOURCE_ID;
+    return { subject: sourceId, data: { ...rest, source_id: sourceId } };
+}
 /** How long the feed keeps a change, and so how far back a cursor may reach. */
 export const SLOTLOCK_CHANGE_RETENTION_DAYS = 30;
 /** Webhook endpoints one tenant may have. */
@@ -54,10 +133,12 @@ function toChange(row) {
         id: `msg_${row.id}`,
         type: row.type,
         resourceId: row.resource_id,
-        subject: row.subject,
-        data: row.data,
+        ...slotlockServedChange(row.type, row.subject, row.data),
         occurredAt: row.occurred_at,
         actor: row.actor,
+        // One a later release added, read by this one: unknown here, so unrecorded, not a failed page.
+        origin: isSlotlockChangeOrigin(row.origin) ? row.origin : null,
+        keyId: row.key_id,
         position: encodePosition({ txid: row.txid, id: row.id, at: row.occurred_at.getTime() }),
     };
 }
@@ -127,7 +208,7 @@ export function slotlockEventFeedMethods(sql, retentionDays = SLOTLOCK_CHANGE_RE
         SELECT mark.txid::text AS pruned_txid, mark.id::text AS pruned_id,
                pg_snapshot_xmin(pg_current_snapshot())::text AS horizon,
                page.id::text, page.txid::text, page.type, page.resource_id, page.subject,
-               page.data, page.occurred_at, page.actor
+               page.data, page.occurred_at, page.actor, page.origin, page.key_id::text
           FROM (SELECT 1) here
           LEFT JOIN slotlock.outbox_pruned mark ON mark.tenant_ref = ${params.tenantRef}
           LEFT JOIN LATERAL (
@@ -179,7 +260,8 @@ export function slotlockEventFeedMethods(sql, retentionDays = SLOTLOCK_CHANGE_RE
                 });
             }
             const rows = await sql `
-        SELECT id::text, txid::text, type, resource_id, subject, data, occurred_at, actor
+        SELECT id::text, txid::text, type, resource_id, subject, data, occurred_at, actor, origin,
+               key_id::text
           FROM slotlock.outbox
          WHERE tenant_ref = ${params.tenantRef}
          ORDER BY txid DESC, id DESC
@@ -194,7 +276,6 @@ export function slotlockEventFeedMethods(sql, retentionDays = SLOTLOCK_CHANGE_RE
             const types = params.eventTypes === undefined ? null : [...new Set(params.eventTypes)];
             if (types !== null &&
                 (types.length === 0 ||
-                    types.length > 20 ||
                     !types.every((type) => SLOTLOCK_CHANGE_TYPES.includes(type)))) {
                 return { ok: false, code: 'invalid_event_types' };
             }
@@ -300,7 +381,8 @@ export function slotlockEventFeedMethods(sql, retentionDays = SLOTLOCK_CHANGE_RE
             const claims = [];
             for (const endpoint of endpoints) {
                 const rows = await sql `
-          SELECT id::text, txid::text, type, resource_id, subject, data, occurred_at, actor
+          SELECT id::text, txid::text, type, resource_id, subject, data, occurred_at, actor, origin,
+               key_id::text
             FROM slotlock.outbox
            WHERE tenant_ref = ${params.tenantRef}
              AND txid < pg_snapshot_xmin(pg_current_snapshot())
@@ -393,11 +475,16 @@ export function slotlockEventFeedMethods(sql, retentionDays = SLOTLOCK_CHANGE_RE
             if (before === undefined)
                 return [];
             const rows = await sql `
-        SELECT id::text, txid::text, type, resource_id, subject, data, occurred_at, actor
+        SELECT id::text, txid::text, type, resource_id, subject, data, occurred_at, actor, origin,
+               key_id::text
           FROM slotlock.outbox
          WHERE tenant_ref = ${params.tenantRef}
            AND (${params.resourceId ?? null}::uuid IS NULL OR resource_id = ${params.resourceId ?? null}::uuid)
-           AND (${params.subject ?? null}::text IS NULL OR subject = ${params.subject ?? null})
+           AND (${params.subject ?? null}::text IS NULL OR (
+                 subject = ${params.subject ?? null}
+                 -- A coverage change matches only by the name it is served under: one not renamed
+                 -- yet may still hold its source, and a guess must not find it.
+                 AND (type NOT LIKE 'coverage.%' OR subject ~ '^src_([0-9a-f]{32}|redacted)$')))
            AND (${before}::bigint IS NULL OR id < ${before}::bigint)
          ORDER BY id DESC
          LIMIT ${limit}`;
@@ -445,3 +532,15 @@ export function slotlockEventFeedMethods(sql, retentionDays = SLOTLOCK_CHANGE_RE
         },
     };
 }
+/**
+ * A position at or before every change that has not ended yet, so a reader that starts from it and
+ * follows `next` misses none still to come (it may read again some that ended just before). Live
+ * updates start here (agent-store-backend.ts, createSlotlockStoreChangeSource).
+ */
+export async function slotlockChangeFeedHead(sql) {
+    const [row] = await sql `
+    SELECT pg_snapshot_xmin(pg_current_snapshot())::text AS horizon`;
+    if (!row)
+        throw new Error('slotlock: change feed head returned no row');
+    return encodePosition({ txid: row.horizon, id: '0', at: Date.now() });
+}

package/index.d.ts

@@ -1,7 +1,7 @@
 /// <reference types="node" preserve="true" />
 export { findNextAvailable, mergeIntervals, subtractBusy } from './engine.js';
-export { type SlotlockBookingRule, type SlotlockBookingRules, bookingRuleBroken, bookingSearch, nextStepStart, parseBookingRules, } from './booking-rules.js';
-export { type CreateWebhookEndpointResult, type ListChangesResult, SLOTLOCK_CHANGE_RETENTION_DAYS, SLOTLOCK_CHANGE_TYPES, SLOTLOCK_MAX_WEBHOOK_ENDPOINTS, SLOTLOCK_WEBHOOK_FAILING_LIMIT_MS, type SlotlockChange, type SlotlockChangeType, type SlotlockEventFeed, type SlotlockWebhookClaim, type SlotlockWebhookEndpoint, } from './event-feed.js';
+export { type SlotlockBookingRule, type SlotlockBookingRules, type SlotlockBookingSearch, bookingRuleBroken, bookingSearch, bookingSearchBlocked, bookingSearchReach, nextStepStart, parseBookingRuleDefaults, parseBookingRules, } from './booking-rules.js';
+export { type CreateWebhookEndpointResult, type ListChangesResult, SLOTLOCK_CHANGE_ORIGINS, SLOTLOCK_CHANGE_RETENTION_DAYS, SLOTLOCK_CHANGE_TYPES, SLOTLOCK_MAX_WEBHOOK_ENDPOINTS, SLOTLOCK_WEBHOOK_FAILING_LIMIT_MS, slotlockChangeFeedHead, type SlotlockChange, type SlotlockChangeOrigin, type SlotlockChangeType, type SlotlockEventFeed, type SlotlockWebhookClaim, type SlotlockWebhookEndpoint, slotlockCoverageSourceId, } from './event-feed.js';
 export { type SlotlockCloudEvent, type SlotlockWebhookPassResult, type SlotlockWebhookResponse, type SlotlockWebhookScheduler, type SlotlockWebhookSender, createSlotlockGuardedFetch, createSlotlockWebhookSender, deliverSlotlockWebhooks, isPrivateAddress, signSlotlockWebhook, slotlockCloudEvent, slotlockWebhookRetryDelayMs, startSlotlockWebhookDelivery, } from './webhooks.js';
 export { type SlotlockMetrics, createSlotlockMetrics } from './metrics.js';
 export { expandRules } from './rules.js';
@@ -11,11 +11,12 @@ export { emitVAvailability, parseVAvailability, recurrenceRuleFromRRule, SLOTLOC
 export type { EmitVAvailabilityOptions, JSCalendarAlert, JSCalendarEvent, JSCalendarParticipant, JSCalendarRecurrenceRule, ParsedVAvailability, } from './interop.js';
 export { createTimeZoneConverter, zonedCalendarDate, zonedDateTimeToUtc, zonedWallTime, } from './timezone.js';
 export type { LocalDateTime, TimeZoneConverter, ZonedCalendarDate, ZonedWallTime, } from './timezone.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 { createSlotlockAgentServer, clientSupportsSlotlockMcpApp, invokeSlotlockAgentOperation, isSlotlockAgentOperation, slotlockAgentTools, slotlockApplicationOperations, slotlockOpenApi, slotlockCalendarResourceUri, slotlockMcpToolResult, parseSlotlockA2ATimestamp, resolveSlotlockAgentOperation, slotlockAgentOperationScope, SLOTLOCK_A2A_PROTOCOL_VERSION, SLOTLOCK_A2A_TASK_PAGE_SIZE, SLOTLOCK_A2A_WATCH_SKILL, 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, SlotlockArgumentIssue, 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, createSlotlockStoreApplicationBackend, projectSlotlockCalendarEvent, } from './agent-store-backend.js';
+export { createSlotlockStoreAgentBackend, createSlotlockStoreApplicationBackend, createSlotlockStoreChangeSource, projectSlotlockCalendarEvent, } from './agent-store-backend.js';
+export { SLOTLOCK_FEED_BUSY_MS, SLOTLOCK_FEED_IDLE_MS, type SlotlockAgentChange, type SlotlockAgentChangeSource, } from './change-watch.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';
@@ -26,11 +27,11 @@ export { createSlotlockDashboard, createSlotlockDashboardResources, createSlotlo
 export type { SlotlockDashboard, SlotlockDashboardAssistantOptions, SlotlockDashboardOptions, SlotlockDashboardResources, SlotlockDashboardState, } from './dashboard.js';
 export { createSlotlockAssistantStore, createSlotlockMemoryAssistantStore, SLOTLOCK_ASSISTANT_TOOL_USE, } from './assistant.js';
 export type { SlotlockAssistantStore } from './assistant.js';
-export type { CreateSlotlockApiKeyInput, SlotlockApiKey, SlotlockApiKeyAuthenticatorOptions, SlotlockApiKeyIdentity, SlotlockApiKeyScope, SlotlockApiKeyStore, } from './api-keys.js';
+export type { CreateSlotlockApiKeyInput, SlotlockApiKey, SlotlockApiKeyAuthenticatorOptions, SlotlockApiKeyChange, 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, 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, SlotlockAgendaEntry, SlotlockHold, SlotlockCalendarEvent, SlotlockReservation, SlotlockResource, SlotlockTenantErasure, PutCalendarEventCommand, PutCalendarEventResult, ReleaseHoldResult, TrustedICalendarEvent, WeeklyAvailabilityRule, } from './types.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, SlotlockAgendaEntry, SlotlockHold, SlotlockCalendarEvent, SlotlockReservation, SlotlockResource, SlotlockTenantErasure, SlotlockBookingRuleDefaults, PutCalendarEventCommand, PutCalendarEventResult, ReleaseHoldResult, TrustedICalendarEvent, WeeklyAvailabilityRule, } from './types.js';

package/index.js

@@ -4,17 +4,18 @@
 // TypeScript 6 default) still loads @types/node.
 /// <reference types="node" preserve="true" />
 export { findNextAvailable, mergeIntervals, subtractBusy } from './engine.js';
-export { bookingRuleBroken, bookingSearch, nextStepStart, parseBookingRules, } from './booking-rules.js';
-export { SLOTLOCK_CHANGE_RETENTION_DAYS, SLOTLOCK_CHANGE_TYPES, SLOTLOCK_MAX_WEBHOOK_ENDPOINTS, SLOTLOCK_WEBHOOK_FAILING_LIMIT_MS, } from './event-feed.js';
+export { bookingRuleBroken, bookingSearch, bookingSearchBlocked, bookingSearchReach, nextStepStart, parseBookingRuleDefaults, parseBookingRules, } from './booking-rules.js';
+export { SLOTLOCK_CHANGE_ORIGINS, SLOTLOCK_CHANGE_RETENTION_DAYS, SLOTLOCK_CHANGE_TYPES, SLOTLOCK_MAX_WEBHOOK_ENDPOINTS, SLOTLOCK_WEBHOOK_FAILING_LIMIT_MS, slotlockChangeFeedHead, slotlockCoverageSourceId, } from './event-feed.js';
 export { createSlotlockGuardedFetch, createSlotlockWebhookSender, deliverSlotlockWebhooks, isPrivateAddress, signSlotlockWebhook, slotlockCloudEvent, slotlockWebhookRetryDelayMs, startSlotlockWebhookDelivery, } from './webhooks.js';
 export { createSlotlockMetrics } from './metrics.js';
 export { expandRules } from './rules.js';
 export { availabilityRuleProblem, parseAvailabilityRules, rulesToWeeklyHours, SLOTLOCK_MAX_AVAILABILITY_RULES, weeklyHoursToRules, } from './weekly-hours.js';
 export { emitVAvailability, parseVAvailability, recurrenceRuleFromRRule, SLOTLOCK_MAX_VAVAILABILITY_CHARACTERS, toJSCalendarEvent, } from './interop.js';
 export { createTimeZoneConverter, zonedCalendarDate, zonedDateTimeToUtc, zonedWallTime, } from './timezone.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 { createSlotlockAgentServer, clientSupportsSlotlockMcpApp, invokeSlotlockAgentOperation, isSlotlockAgentOperation, slotlockAgentTools, slotlockApplicationOperations, slotlockOpenApi, slotlockCalendarResourceUri, slotlockMcpToolResult, parseSlotlockA2ATimestamp, resolveSlotlockAgentOperation, slotlockAgentOperationScope, SLOTLOCK_A2A_PROTOCOL_VERSION, SLOTLOCK_A2A_TASK_PAGE_SIZE, SLOTLOCK_A2A_WATCH_SKILL, 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, createSlotlockStoreApplicationBackend, projectSlotlockCalendarEvent, } from './agent-store-backend.js';
+export { createSlotlockStoreAgentBackend, createSlotlockStoreApplicationBackend, createSlotlockStoreChangeSource, projectSlotlockCalendarEvent, } from './agent-store-backend.js';
+export { SLOTLOCK_FEED_BUSY_MS, SLOTLOCK_FEED_IDLE_MS, } from './change-watch.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';

package/maintenance.js

@@ -1,5 +1,5 @@
 import { ignoreRejection } from './hooks.js';
-import { SLOTLOCK_MAX_WAITLIST_PER_TENANT, calendarEventRollingHorizon } from './store.js';
+import { SLOTLOCK_MAX_WAITLIST_PER_TENANT, 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
@@ -11,6 +11,8 @@ export async function maintainSlotlockTenant(store, tenantRef, options = {}) {
     if (!(Number.isSafeInteger(batches) && batches >= 1 && batches <= 100)) {
         throw new RangeError('batches must be a whole number from 1 to 100');
     }
+    // What a pass changes (a no-show released, a waitlist offer) is recorded as maintenance's.
+    const withTenant = (callback) => store.withTenant(tenantRef, callback, { origin: 'maintenance' });
     const window = calendarEventRollingHorizon();
     let extended = 0;
     let conflicts = 0;
@@ -24,7 +26,7 @@ export async function maintainSlotlockTenant(store, tenantRef, options = {}) {
         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 } : {}) }));
+            const roll = await withTenant((tenant) => tenant.rollCalendarEventHorizon({ tenantRef, window, ...(from ? { after: from } : {}) }));
             extended += roll.extended;
             conflicts += roll.conflicts;
             refused += roll.refused;
@@ -47,17 +49,17 @@ export async function maintainSlotlockTenant(store, tenantRef, options = {}) {
     for (let batch = 0; batch < batches && (eventsLeft || bookingsLeft || changesLeft); batch++) {
         options.signal?.throwIfAborted();
         if (eventsLeft) {
-            const prune = await store.withTenant(tenantRef, (tenant) => tenant.pruneCalendarEventRetention({ tenantRef }));
+            const prune = await withTenant((tenant) => tenant.pruneCalendarEventRetention({ tenantRef }));
             pruned += prune.commandsDeleted + prune.tombstonesDeleted;
             eventsLeft = prune.hasMore;
         }
         if (bookingsLeft) {
-            const prune = await store.withTenant(tenantRef, (tenant) => tenant.pruneBookingRetention({ tenantRef }));
+            const prune = await withTenant((tenant) => tenant.pruneBookingRetention({ tenantRef }));
             pruned += prune.expiredHoldsDeleted + prune.holdCommandsDeleted + prune.tombstonesDeleted;
             bookingsLeft = prune.hasMore;
         }
         if (changesLeft) {
-            const deleted = await store.withTenant(tenantRef, (tenant) => tenant.pruneChanges({ tenantRef, limit: CHANGE_PRUNE_BATCH }));
+            const deleted = await withTenant((tenant) => tenant.pruneChanges({ tenantRef, limit: CHANGE_PRUNE_BATCH }));
             pruned += deleted;
             changesLeft = deleted === CHANGE_PRUNE_BATCH;
         }
@@ -65,11 +67,11 @@ export async function maintainSlotlockTenant(store, tenantRef, options = {}) {
     options.signal?.throwIfAborted();
     // Conversations last 2 hours after their last message (dashboard.ts): an expired one is
     // unreadable already, and deleted here.
-    pruned += await store.withTenant(tenantRef, (tenant) => tenant.pruneAssistantConversations({ tenantRef }));
-    const zones = await store.withTenant(tenantRef, (tenant) => tenant.followZoneRules({ tenantRef, move: options.followZoneRules === true }));
-    const staleSources = await store.withTenant(tenantRef, (tenant) => tenant.reportStaleCoverage({ tenantRef }));
+    pruned += await withTenant((tenant) => tenant.pruneAssistantConversations({ tenantRef }));
+    const zones = await withTenant((tenant) => tenant.followZoneRules({ tenantRef, move: options.followZoneRules === true }));
+    const staleSources = await withTenant((tenant) => tenant.reportStaleCoverage({ tenantRef }));
     // No-shows first: the time they free is offered to the waitlist in the same pass.
-    const noShows = await store.withTenant(tenantRef, (tenant) => tenant.releaseNoShows({ tenantRef }));
+    const noShows = await withTenant((tenant) => tenant.releaseNoShows({ tenantRef }));
     // The whole waitlist, in join order, a page at a time and each page its own transaction, so a
     // later entry whose window is free is offered however many wait before it.
     let waitlistOffers = 0;
@@ -77,7 +79,7 @@ export async function maintainSlotlockTenant(store, tenantRef, options = {}) {
     for (let pages = 0; pages < WAITLIST_PAGES; pages++) {
         options.signal?.throwIfAborted();
         const from = page;
-        const offers = await store.withTenant(tenantRef, (tenant) => tenant.offerWaitlist({ tenantRef, ...(from ? { after: from } : {}) }));
+        const offers = await withTenant((tenant) => tenant.offerWaitlist({ tenantRef, ...(from ? { after: from } : {}) }));
         waitlistOffers += offers.offered;
         page = offers.next;
         if (!page)