slotlock 0.5.2 → 0.6.0

package/agent-store-backend.d.ts

@@ -1,3 +1,5 @@
+import type { Sql } from 'postgres';
+import type { SlotlockAgentChangeSource } from './change-watch.js';
 import { type SlotlockAgentCalendarBackend, type SlotlockAgentInvocationContext } from './agent-server.js';
 import type { SlotlockApplicationBackend } from './application-api.js';
 import { type SlotlockStore } from './store.js';
@@ -23,6 +25,13 @@ export declare function projectSlotlockCalendarEvent(event: SlotlockCalendarEven
  * stored 409. rest-api.ts declares the 404 and 409 each route can answer from this.
  */
 export declare function slotlockAgentErrorStatus(code: string): 400 | 404 | 409 | 429;
+/**
+ * The store's change feed for live updates (`subscriptions.changes`): each tenant's changes read
+ * under its row-level security, one indexed query per read. Readers poll it (change-watch.ts:
+ * every `SLOTLOCK_FEED_BUSY_MS` after a read that found changes, backing off to
+ * `SLOTLOCK_FEED_IDLE_MS`); `sql` is the store's client, used for the feed's head.
+ */
+export declare function createSlotlockStoreChangeSource(store: SlotlockStore, sql: Sql): SlotlockAgentChangeSource;
 /** Bind the protocol server to the production store without giving a request control of tenancy. */
 export declare function createSlotlockStoreAgentBackend(store: SlotlockStore, options: SlotlockStoreAgentBackendOptions): SlotlockAgentCalendarBackend;
 export interface SlotlockStoreApplicationBackendOptions {

package/agent-store-backend.js

@@ -1,7 +1,8 @@
+import { slotlockChangeFeedHead } from './event-feed.js';
 import { slotlockCloudEvent } from './webhooks.js';
 import { createHash } from 'node:crypto';
 import { SlotlockAgentOperationError, } from './agent-server.js';
-import { bookingSearch } from './booking-rules.js';
+import { bookingSearch, bookingSearchBlocked, bookingSearchReach, } from './booking-rules.js';
 import { findNextAvailable, mergeIntervals } from './engine.js';
 import { expandRules } from './rules.js';
 import { emitVAvailability, parseVAvailability, toJSCalendarEvent } from './interop.js';
@@ -14,6 +15,9 @@ import { parseAvailabilityRules } from './weekly-hours.js';
  * and refuses it otherwise.
  */
 const WRITE = { isolation: 'read committed' };
+// The UUIDs withTenant takes as a keyId (versions 1-5, as Slotlock's keys are): any other a custom
+// authenticator's principal carries is left out, not refused.
+const KEY_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 /** Who a call's changes are recorded as in the history: the principal's subject, kept short. */
 function actorOf(context) {
     const subject = context.principal.subject;
@@ -31,10 +35,14 @@ async function withTenant(store, context, callback, options) {
     let value;
     try {
         const actor = actorOf(context);
+        const keyId = context.principal.keyId;
         value = await store.withTenant(context.principal.tenantRef, callback, {
             ...options,
             signal: context.signal,
             ...(actor !== undefined ? { actor } : {}),
+            ...(context.origin !== undefined ? { origin: context.origin } : {}),
+            // An authenticator's own principal may carry something else there: then it is left out.
+            ...(typeof keyId === 'string' && KEY_ID.test(keyId) ? { keyId } : {}),
         });
     }
     catch (error) {
@@ -315,6 +323,21 @@ async function requireResource(tenantStore, tenantRef, resourceId, visibility) {
 function requireAgentResource(tenantStore, tenantRef, resourceId) {
     return requireResource(tenantStore, tenantRef, resourceId, 'shared');
 }
+/**
+ * The store's change feed for live updates (`subscriptions.changes`): each tenant's changes read
+ * under its row-level security, one indexed query per read. Readers poll it (change-watch.ts:
+ * every `SLOTLOCK_FEED_BUSY_MS` after a read that found changes, backing off to
+ * `SLOTLOCK_FEED_IDLE_MS`); `sql` is the store's client, used for the feed's head.
+ */
+export function createSlotlockStoreChangeSource(store, sql) {
+    return {
+        head: () => slotlockChangeFeedHead(sql),
+        async listChanges(params) {
+            const page = await store.withTenant(params.tenantRef, (tenant) => tenant.listChanges(params));
+            return page.ok ? { ok: true, changes: page.changes, next: page.next } : page;
+        },
+    };
+}
 /** Bind the protocol server to the production store without giving a request control of tenancy. */
 export function createSlotlockStoreAgentBackend(store, options) {
     return {
@@ -457,7 +480,7 @@ export function createSlotlockStoreAgentBackend(store, options) {
                     // Not free either where its booking rules refuse a booking: before its notice, past how
                     // far ahead it books, and, when it enforces them, outside its bookable hours. Its slot
                     // step is not counted: it moves when a booking may start, not whether the member is free.
-                    const rules = member.bookingRules;
+                    const rules = member.effectiveBookingRules;
                     const search = bookingSearch({ rules, timezone: member.timezone, window, now });
                     const latestStart = rules?.maxAdvanceDays !== undefined
                         ? now.getTime() + rules.maxAdvanceDays * 86_400_000
@@ -682,7 +705,7 @@ export function createSlotlockStoreAgentBackend(store, options) {
                     // Only what a booking made now may take: the resource's booking rules bound the search,
                     // as they bound the write that follows it.
                     const search = bookingSearch({
-                        rules: resource.bookingRules,
+                        rules: resource.effectiveBookingRules,
                         timezone: resource.timezone,
                         window,
                         now: new Date(),
@@ -691,11 +714,8 @@ export function createSlotlockStoreAgentBackend(store, options) {
                     const freeBusy = await readFreeBusy(tenantStore, {
                         tenantRef: context.principal.tenantRef,
                         resourceId,
-                        // A slot's turnaround may run past the window: what it reaches must be free too.
-                        window: {
-                            start: window.start,
-                            end: new Date(window.end.getTime() + (search?.bufferAfterMs ?? 0)),
-                        },
+                        // A slot's buffers may run past the window: what they reach must be free too.
+                        window: search ? bookingSearchReach({ ...search, window }) : window,
                         requiredSources: [...sources],
                         ...(options.coverageMaxAgeMs !== undefined
                             ? { coverageMaxAgeMs: options.coverageMaxAgeMs }
@@ -713,12 +733,8 @@ export function createSlotlockStoreAgentBackend(store, options) {
                     windowsLeft -= windows.length;
                     if (windowsLeft < 0)
                         throw new SlotlockAgentOperationError('calendar_work_limit', 400);
-                    // A slot [s, s + d) with its turnaround meets busy [b, e) when [s, s + d) meets [b - t, e).
                     const candidate = findNextAvailable({
-                        busy: freeBusy.busy.map((busy) => ({
-                            start: new Date(busy.start.getTime() - search.bufferAfterMs),
-                            end: busy.end,
-                        })),
+                        busy: bookingSearchBlocked(freeBusy.busy, search),
                         windows,
                         durationMs,
                         ...(search.align ? { align: search.align } : {}),
@@ -979,7 +995,9 @@ function storeRefusal(error) {
     const code = error?.code;
     if (typeof code !== 'string')
         return error;
-    if (code === 'resource_limit_reached' || code === 'resource_visibility_conflict') {
+    if (code === 'resource_limit_reached' ||
+        code === 'resource_visibility_conflict' ||
+        code === 'pool_rules_limit_reached') {
         return new SlotlockAgentOperationError(code, 409);
     }
     if (code.startsWith('invalid_') && code !== 'invalid_transaction_isolation') {
@@ -1021,7 +1039,9 @@ function waitlistOutput(entry) {
  */
 async function offerFreedTime(store, tenantRef) {
     try {
-        await store.withTenant(tenantRef, (tenant) => tenant.offerWaitlist({ tenantRef, limit: 20 }));
+        await store.withTenant(tenantRef, (tenant) => tenant.offerWaitlist({ tenantRef, limit: 20 }), {
+            origin: 'maintenance',
+        });
     }
     catch {
         // Left to maintenance.
@@ -1073,6 +1093,8 @@ function bookingRulesOutput(rules) {
         ...(rules.minNoticeMinutes !== undefined ? { min_notice_minutes: rules.minNoticeMinutes } : {}),
         ...(rules.maxAdvanceDays !== undefined ? { max_advance_days: rules.maxAdvanceDays } : {}),
         ...(rules.slotStepMinutes !== undefined ? { slot_step_minutes: rules.slotStepMinutes } : {}),
+        ...(rules.stepOffsetMinutes !== undefined ? { step_offset_minutes: rules.stepOffsetMinutes } : {}),
+        ...(rules.bufferBeforeMinutes !== undefined ? { buffer_before_minutes: rules.bufferBeforeMinutes } : {}),
         ...(rules.turnaroundMinutes !== undefined ? { turnaround_minutes: rules.turnaroundMinutes } : {}),
         ...(rules.enforceHours !== undefined ? { enforce_hours: rules.enforceHours } : {}),
         ...(rules.checkInMinutes !== undefined ? { check_in_minutes: rules.checkInMinutes } : {}),
@@ -1090,6 +1112,11 @@ function bookingRulesInput(value) {
         rules.maxAdvanceDays = input.max_advance_days;
     if (input.slot_step_minutes !== undefined)
         rules.slotStepMinutes = input.slot_step_minutes;
+    if (input.step_offset_minutes !== undefined)
+        rules.stepOffsetMinutes = input.step_offset_minutes;
+    if (input.buffer_before_minutes !== undefined) {
+        rules.bufferBeforeMinutes = input.buffer_before_minutes;
+    }
     if (input.turnaround_minutes !== undefined)
         rules.turnaroundMinutes = input.turnaround_minutes;
     if (input.enforce_hours !== undefined)
@@ -1107,6 +1134,7 @@ function resourceOutput(resource) {
         timezone: resource.timezone,
         availability: rulesOutput(resource.availabilityRules),
         booking_rules: bookingRulesOutput(resource.bookingRules),
+        effective_booking_rules: bookingRulesOutput(resource.effectiveBookingRules),
         visibility: resource.visibility ?? 'shared',
         archived_at: resource.archivedAt?.toISOString() ?? null,
         pool: resource.pool ?? null,
@@ -1203,6 +1231,8 @@ export function createSlotlockStoreApplicationBackend(store, options = {}) {
                     type: entry.type,
                     time: entry.occurredAt.toISOString(),
                     actor: entry.actor,
+                    origin: entry.origin,
+                    key_id: entry.keyId,
                     data: entry.data,
                 })),
                 next_before: entries.length === limit ? (entries.at(-1)?.id ?? null) : null,
@@ -1405,6 +1435,43 @@ export function createSlotlockStoreApplicationBackend(store, options = {}) {
                 pools: await tenant.listPools({ tenantRef: tenantOf(context) }),
             }));
         },
+        async getBookingRuleDefaults(context) {
+            return withTenant(store, context, async (tenant) => {
+                const defaults = await tenant.getBookingRuleDefaults({ tenantRef: tenantOf(context) });
+                return {
+                    tenant: bookingRulesOutput(defaults.tenant ?? undefined),
+                    pools: Object.entries(defaults.pools).map(([pool, rules]) => ({
+                        pool,
+                        rules: bookingRulesOutput(rules) ?? {},
+                    })),
+                };
+            });
+        },
+        async setTenantBookingRules(context, input) {
+            const rules = bookingRulesInput(input.rules);
+            return withTenant(store, context, async (tenant) => {
+                try {
+                    const stored = await tenant.setBookingRuleDefaults({ tenantRef: tenantOf(context), pool: null, rules });
+                    return { rules: bookingRulesOutput(stored ?? undefined) };
+                }
+                catch (error) {
+                    throw storeRefusal(error);
+                }
+            }, WRITE);
+        },
+        async setPoolBookingRules(context, input) {
+            const rules = bookingRulesInput(input.rules);
+            const pool = input.pool;
+            return withTenant(store, context, async (tenant) => {
+                try {
+                    const stored = await tenant.setBookingRuleDefaults({ tenantRef: tenantOf(context), pool, rules });
+                    return { pool, rules: bookingRulesOutput(stored ?? undefined) };
+                }
+                catch (error) {
+                    throw storeRefusal(error);
+                }
+            }, WRITE);
+        },
         async setTenantAvailability(context, input) {
             const rules = rulesInput(input.rules);
             return withTenant(store, context, async (tenant) => {
@@ -1616,6 +1683,7 @@ export function createSlotlockStoreApplicationBackend(store, options = {}) {
                 return {
                     sources: sources.map((source) => ({
                         source: source.source,
+                        source_id: source.sourceId,
                         start: source.start.toISOString(),
                         end: source.end.toISOString(),
                         revision: source.revision,

package/api-keys.d.ts

@@ -1,5 +1,6 @@
 import { type SlotlockAgentPrincipal } from './agent-server.js';
 import { SLOTLOCK_API_KEY_ACTIVE_LIMIT, SLOTLOCK_API_KEY_RETAINED_LIMIT } from './ddl.js';
+import { type SlotlockChangeOrigin } from './event-feed.js';
 import type { SlotlockSql } from './store.js';
 export { SLOTLOCK_API_KEY_ACTIVE_LIMIT, SLOTLOCK_API_KEY_RETAINED_LIMIT };
 /**
@@ -46,6 +47,15 @@ export interface CreateSlotlockApiKeyInput {
     /** Omit for a key that lives until it is revoked. At most ten years ahead. */
     expiresAt?: Date;
     createdBy?: string;
+    /** Who is creating it, for the feed's `key.created` (and withTenant's actor); else `createdBy`. */
+    actor?: string;
+    /** Where from, for the feed (`dashboard`, say); else the enclosing withTenant's, or `library`. */
+    origin?: SlotlockChangeOrigin;
+}
+/** Who rotates or revokes a key and from where, recorded on the feed as `create`'s are. */
+export interface SlotlockApiKeyChange {
+    actor?: string;
+    origin?: SlotlockChangeOrigin;
 }
 export interface SlotlockApiKeyStore {
     /**
@@ -71,7 +81,7 @@ export interface SlotlockApiKeyStore {
     rotate(input: {
         tenantRef: string;
         id: string;
-    }): Promise<{
+    } & SlotlockApiKeyChange): Promise<{
         key: string;
         apiKey: SlotlockApiKey;
     } | null>;
@@ -82,7 +92,7 @@ export interface SlotlockApiKeyStore {
     revoke(input: {
         tenantRef: string;
         id: string;
-    }): Promise<SlotlockApiKey | null>;
+    } & SlotlockApiKeyChange): Promise<SlotlockApiKey | null>;
     /** Resolve a presented key to its tenant and scopes; null unless it is active. */
     authenticate(key: string): Promise<SlotlockApiKeyIdentity | null>;
     /**

package/api-keys.js

@@ -10,6 +10,7 @@
 import { createHash, randomBytes } from 'node:crypto';
 import { SlotlockAgentOperationError, } from './agent-server.js';
 import { SLOTLOCK_API_KEY_ACTIVE_LIMIT, SLOTLOCK_API_KEY_RETAINED_LIMIT } from './ddl.js';
+import { isSlotlockChangeOrigin } from './event-feed.js';
 export { SLOTLOCK_API_KEY_ACTIVE_LIMIT, SLOTLOCK_API_KEY_RETAINED_LIMIT };
 /**
  * `read` covers the agent operations that only look; `write` the ones that change a calendar; `admin`
@@ -144,6 +145,33 @@ async function readCommitted(sql, query) {
     }
     return query(sql);
 }
+/**
+ * Run a key change with who made it and from where set for the row the database appends to the
+ * tenant's feed, in a READ COMMITTED transaction (or the caller's), and the caller's values put back.
+ */
+async function asChange(sql, change, query) {
+    if (change.actor !== undefined && !/^[^\u0000-\u001f\u007f]{1,200}$/u.test(change.actor)) {
+        throw invalid('invalid_identity', 'Slotlock actor must be 1-200 characters without control characters');
+    }
+    if (change.origin !== undefined && !isSlotlockChangeOrigin(change.origin)) {
+        throw invalid('invalid_identity', 'Slotlock origin is not one of SLOTLOCK_CHANGE_ORIGINS');
+    }
+    return readCommitted(sql, async (tx) => {
+        const [previous] = await tx `
+      SELECT current_setting('slotlock.actor', true) AS actor,
+             current_setting('slotlock.origin', true) AS origin`;
+        await tx `
+      SELECT set_config('slotlock.actor', COALESCE(${change.actor ?? null}::text, ${previous?.actor ?? ''}), true),
+             set_config('slotlock.origin', COALESCE(${change.origin ?? null}::text,
+               NULLIF(${previous?.origin ?? ''}, ''), 'library'), true)`;
+        const result = await query(tx);
+        // Only after success: a failed query has aborted the transaction, which takes the values with it.
+        await tx `
+      SELECT set_config('slotlock.actor', ${previous?.actor ?? ''}, true),
+             set_config('slotlock.origin', ${previous?.origin ?? ''}, true)`;
+        return result;
+    });
+}
 /**
  * API keys in the `slotlock` schema, through the connection's role. Every input is checked here
  * before a query runs; the functions and the table's constraints check the same rules again.
@@ -178,7 +206,7 @@ export function createSlotlockApiKeyStore(sql) {
             const { key, prefix, digest } = generateSlotlockApiKey();
             // Scopes travel as one string: postgres.js binds `sql.array` as text[] only once the pool
             // has fetched the server's array types, which the first query on a new pool precedes.
-            const [row] = await readCommitted(sql, (tx) => tx `
+            const [row] = await asChange(sql, { ...(input.actor !== undefined ? { actor: input.actor } : {}), ...(input.origin ? { origin: input.origin } : {}) }, (tx) => tx `
           SELECT * FROM slotlock.create_api_key(
             ${input.tenantRef}::text,
             ${name}::text,
@@ -199,23 +227,23 @@ export function createSlotlockApiKeyStore(sql) {
         SELECT * FROM slotlock.list_api_keys(${tenantRef}::text)`;
             return rows.map(apiKeyFrom);
         },
-        async rotate({ tenantRef, id }) {
+        async rotate({ tenantRef, id, ...change }) {
             assertTenantRef(tenantRef);
             if (typeof id !== 'string' || !UUID_PATTERN.test(id))
                 return null;
             const { key, prefix, digest } = generateSlotlockApiKey();
-            const [row] = await sql `
+            const [row] = await asChange(sql, change, (tx) => tx `
         SELECT * FROM slotlock.rotate_api_key(
           ${tenantRef}::text, ${id}::uuid, ${prefix}::text, ${digest}::bytea
-        )`;
+        )`);
             return row ? { key, apiKey: apiKeyFrom(row) } : null;
         },
-        async revoke({ tenantRef, id }) {
+        async revoke({ tenantRef, id, ...change }) {
             assertTenantRef(tenantRef);
             if (typeof id !== 'string' || !UUID_PATTERN.test(id))
                 return null;
-            const [row] = await sql `
-        SELECT * FROM slotlock.revoke_api_key(${tenantRef}::text, ${id}::uuid)`;
+            const [row] = await asChange(sql, change, (tx) => tx `
+        SELECT * FROM slotlock.revoke_api_key(${tenantRef}::text, ${id}::uuid)`);
             return row ? apiKeyFrom(row) : null;
         },
         async authenticate(key) {
@@ -297,6 +325,7 @@ export function createSlotlockApiKeyAuthenticator(keys, options = {}) {
                 subject: `api_key:${identity.id}`,
                 tenantRef: identity.tenantRef,
                 scopes: identity.scopes,
+                keyId: identity.id,
             };
         }
         finally {

package/application-api.d.ts

@@ -1,7 +1,8 @@
+import { type SlotlockChangeOrigin } from './event-feed.js';
 import { z } from 'zod';
 import type { SlotlockAgentPrincipal } from './agent-server.js';
 import type { SlotlockTraceContext } from './mcp-modern.js';
-export type SlotlockApplicationOperation = 'slotlock_create_resource' | 'slotlock_get_resource' | 'slotlock_archive_resource' | 'slotlock_restore_resource' | 'slotlock_delete_resource' | 'slotlock_list_busy' | 'slotlock_set_resource_availability' | 'slotlock_set_tenant_availability' | 'slotlock_export_resource_availability' | 'slotlock_import_resource_availability' | 'slotlock_set_resource_booking_rules' | 'slotlock_set_resource_pool' | 'slotlock_list_pools' | 'slotlock_get_resource_history' | 'slotlock_get_coverage' | 'slotlock_record_coverage_failure' | 'slotlock_delete_coverage' | 'slotlock_get_reservation_history' | 'slotlock_get_tenant_event_history' | 'slotlock_acquire_hold' | 'slotlock_get_hold' | 'slotlock_list_holds' | 'slotlock_confirm_hold' | 'slotlock_release_hold' | 'slotlock_get_reservation' | 'slotlock_list_reservations' | 'slotlock_put_reservation' | 'slotlock_cancel_reservation' | 'slotlock_check_in_reservation' | 'slotlock_join_waitlist' | 'slotlock_list_waitlist' | 'slotlock_leave_waitlist' | 'slotlock_record_coverage' | 'slotlock_list_tenant_events' | 'slotlock_get_tenant_event' | 'slotlock_export_tenant_event' | 'slotlock_cancel_tenant_event' | 'slotlock_get_tenant' | 'slotlock_erase_tenant' | 'slotlock_run_maintenance' | 'slotlock_list_changes' | 'slotlock_create_webhook' | 'slotlock_list_webhooks' | 'slotlock_delete_webhook' | 'slotlock_enable_webhook';
+export type SlotlockApplicationOperation = 'slotlock_create_resource' | 'slotlock_get_resource' | 'slotlock_archive_resource' | 'slotlock_restore_resource' | 'slotlock_delete_resource' | 'slotlock_list_busy' | 'slotlock_set_resource_availability' | 'slotlock_set_tenant_availability' | 'slotlock_export_resource_availability' | 'slotlock_import_resource_availability' | 'slotlock_set_resource_booking_rules' | 'slotlock_set_resource_pool' | 'slotlock_list_pools' | 'slotlock_get_booking_rule_defaults' | 'slotlock_set_tenant_booking_rules' | 'slotlock_set_pool_booking_rules' | 'slotlock_get_resource_history' | 'slotlock_get_coverage' | 'slotlock_record_coverage_failure' | 'slotlock_delete_coverage' | 'slotlock_get_reservation_history' | 'slotlock_get_tenant_event_history' | 'slotlock_acquire_hold' | 'slotlock_get_hold' | 'slotlock_list_holds' | 'slotlock_confirm_hold' | 'slotlock_release_hold' | 'slotlock_get_reservation' | 'slotlock_list_reservations' | 'slotlock_put_reservation' | 'slotlock_cancel_reservation' | 'slotlock_check_in_reservation' | 'slotlock_join_waitlist' | 'slotlock_list_waitlist' | 'slotlock_leave_waitlist' | 'slotlock_record_coverage' | 'slotlock_list_tenant_events' | 'slotlock_get_tenant_event' | 'slotlock_export_tenant_event' | 'slotlock_cancel_tenant_event' | 'slotlock_get_tenant' | 'slotlock_erase_tenant' | 'slotlock_run_maintenance' | 'slotlock_list_changes' | 'slotlock_create_webhook' | 'slotlock_list_webhooks' | 'slotlock_delete_webhook' | 'slotlock_enable_webhook';
 /** The scope an application operation needs, whichever operation it is. */
 export declare const SLOTLOCK_APPLICATION_SCOPE = "admin";
 export interface SlotlockApplicationInvocationContext {
@@ -10,6 +11,8 @@ export interface SlotlockApplicationInvocationContext {
     signal: AbortSignal;
     /** W3C trace context the caller sent, already validated. */
     trace?: SlotlockTraceContext;
+    /** The surface the call came through: `application` when the agent server dispatches it. */
+    origin?: SlotlockChangeOrigin;
 }
 type Handler = (context: SlotlockApplicationInvocationContext, input: Record<string, unknown>) => Promise<Record<string, unknown>>;
 /**
@@ -31,6 +34,9 @@ export interface SlotlockApplicationBackend {
     setResourceBookingRules: Handler;
     setResourcePool: Handler;
     listPools: Handler;
+    getBookingRuleDefaults: Handler;
+    setTenantBookingRules: Handler;
+    setPoolBookingRules: Handler;
     getResourceHistory: Handler;
     getCoverage: Handler;
     recordCoverageFailure: Handler;

package/application-api.js

@@ -9,7 +9,7 @@
 //
 // This module holds only the contract (names, schemas, routes); it imports nothing from the agent
 // server at runtime. The store-backed implementation is createSlotlockStoreApplicationBackend.
-import { SLOTLOCK_CHANGE_TYPES } from './event-feed.js';
+import { SLOTLOCK_CHANGE_ORIGINS, SLOTLOCK_CHANGE_TYPES } from './event-feed.js';
 import { z } from 'zod';
 import { SLOTLOCK_EVENT_OUTPUT } from './event-schema.js';
 import { SLOTLOCK_CALENDAR_HORIZON_DAYS } from './rules.js';
@@ -83,12 +83,16 @@ const BOOKING_RULES = z
     min_notice_minutes: z.number().int().min(0).max(525_600).optional(),
     max_advance_days: z.number().int().min(1).max(3_660).optional(),
     slot_step_minutes: z.number().int().min(1).max(1_440).optional(),
+    step_offset_minutes: z.number().int().min(0).max(1_439).optional(),
+    buffer_before_minutes: z.number().int().min(0).max(1_440).optional(),
     turnaround_minutes: z.number().int().min(0).max(1_440).optional(),
     enforce_hours: z.boolean().optional(),
     check_in_minutes: z.number().int().min(1).max(1_440).optional(),
     require_certain: z.boolean().optional(),
 })
     .strict();
+/** Default booking rules for the tenant or a pool: a resource's own rules but check-in. */
+const DEFAULT_BOOKING_RULES = BOOKING_RULES.omit({ check_in_minutes: true }).strict();
 const POOL = z.string().regex(/^[a-z0-9][a-z0-9._-]{0,99}$/);
 const RESOURCE = z
     .object({
@@ -97,8 +101,13 @@ const RESOURCE = z
     timezone: TIMEZONE,
     /** The resource's own weekly hours; `null` when it uses the default. */
     availability: AVAILABILITY_RULES.nullable(),
-    /** What a booking on it must satisfy; `null` when it has no rules. */
+    /** Its own booking rules; `null` when it has none. */
     booking_rules: BOOKING_RULES.nullable(),
+    /**
+     * What a booking on it must satisfy: the tenant's default rules, overlaid by its pool's,
+     * overlaid by its own; `null` when no rule applies.
+     */
+    effective_booking_rules: BOOKING_RULES.nullable(),
     /** `private` resources are never shown to agents; fixed when the resource is created. */
     visibility: VISIBILITY,
     /** When it was archived; `null` while it is in use. */
@@ -114,6 +123,10 @@ const HISTORY_ENTRY = z
     time: DATE_TIME,
     /** Who made it: an API key, an agent's subject; `null` when not recorded. */
     actor: z.string().max(200).nullable(),
+    /** Where it came from (mcp, a2a, rest, application, dashboard, ...); `null` when not recorded. */
+    origin: z.enum(SLOTLOCK_CHANGE_ORIGINS).nullable(),
+    /** The API key that made it, by id; `null` when no key did. */
+    key_id: z.string().uuid().nullable(),
     /** The record as the change left it, with `before` for a change of an existing one. */
     data: z.record(z.string(), z.unknown()),
 })
@@ -134,6 +147,10 @@ const CHANGE = z
     subject: z.string().max(500),
     time: DATE_TIME,
     datacontenttype: z.literal('application/json'),
+    /** Extension attribute: where the change came from, when recorded (mcp, rest, dashboard, ...). */
+    slotlockorigin: z.enum(SLOTLOCK_CHANGE_ORIGINS).optional(),
+    /** Extension attribute: the id of the API key that made it, when one did. */
+    slotlockkeyid: z.string().uuid().optional(),
     data: z.record(z.string(), z.unknown()),
 })
     .strict();
@@ -349,7 +366,7 @@ export const SLOTLOCK_APPLICATION_OPERATIONS = Object.freeze([
     {
         name: 'slotlock_set_resource_booking_rules',
         title: "Set a resource's booking rules",
-        description: "Set what a booking on one resource must satisfy from now on: minimum notice, how far ahead, the step starts fall on (from local midnight in the resource's time zone), the turnaround kept free after each booking, and whether bookings must lie inside its hours. `null` clears them. Holds, reservations, moves and agents' events are refused with the rule they break; searches offer only what they allow.",
+        description: "Set what a booking on one resource must satisfy from now on: minimum notice, how far ahead, the step starts fall on (from local midnight in the resource's time zone, offset by step_offset_minutes), the time kept free before and after each booking, and whether bookings must lie inside its hours. `null` clears them. A rule it does not set comes from its pool's or the tenant's defaults (slotlock_set_pool_booking_rules, slotlock_set_tenant_booking_rules). Holds, reservations, moves and agents' events are refused with the rule they break; searches offer only what they allow.",
         method: 'PUT',
         path: '/v1/resources/{resource_id}/booking-rules',
         input: z.object({ resource_id: RESOURCE_ID, rules: BOOKING_RULES.nullable() }).strict(),
@@ -387,10 +404,51 @@ export const SLOTLOCK_APPLICATION_OPERATIONS = Object.freeze([
         invoke: 'listPools',
         example: {},
     },
+    {
+        name: 'slotlock_get_booking_rule_defaults',
+        title: 'Get default booking rules',
+        description: "The tenant's default booking rules, and each pool's that has them. A resource's rules as they apply (effective_booking_rules) are the tenant's defaults, overlaid by its pool's, overlaid by its own: a rule set at a narrower level wins.",
+        method: 'GET',
+        path: '/v1/booking-rules',
+        input: z.object({}).strict(),
+        output: z
+            .object({
+            tenant: DEFAULT_BOOKING_RULES.nullable(),
+            pools: z.array(z.object({ pool: POOL, rules: DEFAULT_BOOKING_RULES }).strict()).max(1000),
+        })
+            .strict(),
+        risk: { readOnly: true, destructive: false, idempotent: true },
+        invoke: 'getBookingRuleDefaults',
+        example: {},
+    },
+    {
+        name: 'slotlock_set_tenant_booking_rules',
+        title: 'Set default booking rules',
+        description: "Set the booking rules every resource of the tenant has unless its pool or its own rules set the same rule, from now on; `null` clears them. They take any resource rule but check_in_minutes, which only a resource sets.",
+        method: 'PUT',
+        path: '/v1/booking-rules',
+        input: z.object({ rules: DEFAULT_BOOKING_RULES.nullable() }).strict(),
+        output: z.object({ rules: DEFAULT_BOOKING_RULES.nullable() }).strict(),
+        risk: { readOnly: false, destructive: false, idempotent: true },
+        invoke: 'setTenantBookingRules',
+        example: { rules: { min_notice_minutes: 120, buffer_before_minutes: 15, turnaround_minutes: 15 } },
+    },
+    {
+        name: 'slotlock_set_pool_booking_rules',
+        title: "Set a pool's booking rules",
+        description: "Set the booking rules every member of one pool has unless its own rules set the same rule, over the tenant's defaults, from now on; `null` clears them. They take any resource rule but check_in_minutes. At most 1,000 pools have them: one more is 409 pool_rules_limit_reached.",
+        method: 'PUT',
+        path: '/v1/pools/{pool}/booking-rules',
+        input: z.object({ pool: POOL, rules: DEFAULT_BOOKING_RULES.nullable() }).strict(),
+        output: z.object({ pool: POOL, rules: DEFAULT_BOOKING_RULES.nullable() }).strict(),
+        risk: { readOnly: false, destructive: false, idempotent: true },
+        invoke: 'setPoolBookingRules',
+        example: { pool: 'van', rules: { slot_step_minutes: 30, step_offset_minutes: 15 } },
+    },
     {
         name: 'slotlock_get_resource_history',
         title: "A resource's history",
-        description: "What happened on one of the tenant's resources, newest first: each hold, booking and event made, moved, confirmed, released or cancelled, when, by whom (the API key or agent), and for a change what it was before. Kept 30 days. Pass next_before as before for older entries.",
+        description: "What happened on one of the tenant's resources, newest first: each hold, booking and event made, moved, confirmed, released or cancelled, and each change to the resource itself (created, rules, pool or hours changed, archived, restored, coverage recorded or deleted), when, by whom (the actor and API key), from where (origin), and for a change what it was before. Kept 30 days. Pass next_before as before for older entries.",
         method: 'GET',
         path: '/v1/resources/{resource_id}/history',
         input: z.object({ resource_id: RESOURCE_ID, ...HISTORY_PAGE }).strict(),
@@ -699,7 +757,7 @@ export const SLOTLOCK_APPLICATION_OPERATIONS = Object.freeze([
     {
         name: 'slotlock_get_coverage',
         title: "A resource's coverage and its health",
-        description: "Each external calendar (source) that records coverage of a resource: the window it covers, when it was last read, its last error, and whether it is stale (not read for a day, so the time it covers is unproven, not free). A source that goes stale is also put on the change feed once, as coverage.stale, until it is read again.",
+        description: "Each external calendar (source) that records coverage of a resource: the window it covers, when it was last read, its last error, and whether it is stale (not read for a day, so the time it covers is unproven, not free). A source that goes stale is also put on the change feed once, as coverage.stale, until it is read again. The feed names a source by its source_id (random, made when the source is first recorded for the resource and kept until it is deleted), never the source itself.",
         method: 'GET',
         path: '/v1/resources/{resource_id}/coverage',
         input: z.object({ resource_id: RESOURCE_ID }).strict(),
@@ -709,6 +767,11 @@ export const SLOTLOCK_APPLICATION_OPERATIONS = Object.freeze([
                 .array(z
                 .object({
                 source: SOURCE,
+                /**
+                 * How the change feed names the source (coverage.recorded, .deleted, .stale): random,
+                 * made when it is first recorded for the resource, kept until it is deleted.
+                 */
+                source_id: z.string().regex(/^src_[0-9a-f]{32}$/),
                 start: DATE_TIME,
                 end: DATE_TIME,
                 revision: REVISION,
@@ -887,7 +950,7 @@ export const SLOTLOCK_APPLICATION_OPERATIONS = Object.freeze([
     {
         name: 'slotlock_list_changes',
         title: 'List changes',
-        description: "What changed in the tenant, oldest first, as CloudEvents: holds made, confirmed, released or expired; bookings made, moved or cancelled; calendar events created, changed or cancelled (ids, times and states, never titles or attendees). Pass next_cursor as cursor to read on; it is returned even when nothing is new, so poll with it. Only changes of transactions that have ended are listed, so following the cursor never skips one. Changes are kept 30 days: an older cursor answers 410 cursor_expired, so start again without one.",
+        description: "What changed in the tenant, oldest first, as CloudEvents: holds made, confirmed, released or expired; bookings made, moved or cancelled; calendar events created, changed or cancelled; resources created, changed (rules, pool, hours), archived, restored or deleted; coverage sources recorded or deleted; webhooks added, enabled or deleted; API keys created, rotated or revoked (ids, times and states, never titles, attendees, URLs or secrets). Each names where it came from (slotlockorigin) and the API key that made it (slotlockkeyid) when recorded. Pass next_cursor as cursor to read on; it is returned even when nothing is new, so poll with it. Only changes of transactions that have ended are listed, so following the cursor never skips one. Changes are kept 30 days: an older cursor answers 410 cursor_expired, so start again without one.",
         method: 'GET',
         path: '/v1/changes',
         input: z
@@ -907,7 +970,7 @@ export const SLOTLOCK_APPLICATION_OPERATIONS = Object.freeze([
         input: z
             .object({
             url: z.string().url().max(2048),
-            event_types: z.array(z.enum(SLOTLOCK_CHANGE_TYPES)).min(1).max(20).optional(),
+            event_types: z.array(z.enum(SLOTLOCK_CHANGE_TYPES)).min(1).max(SLOTLOCK_CHANGE_TYPES.length).optional(),
         })
             .strict(),
         output: z.object({ webhook: WEBHOOK, secret: z.string().regex(/^whsec_/) }).strict(),

package/assistant.js

@@ -80,7 +80,8 @@ const MAX_OUTPUT_TOKENS = 1_024;
 export const SLOTLOCK_ANTHROPIC_VERSION = '2026-10-21';
 /** The assistant's records in the store, each in a transaction under the tenant's row-level security. */
 export function createSlotlockAssistantStore(store) {
-    const by = (actor) => (actor === undefined ? {} : { actor });
+    // Every change here is the dashboard's, made by the person signed in (actor) when known.
+    const by = (actor) => actor === undefined ? { origin: 'dashboard' } : { origin: 'dashboard', actor };
     return {
         getSettings: (tenantRef) => store.withTenant(tenantRef, (tenant) => tenant.getAssistantSettings({ tenantRef })),
         putSettings: (tenantRef, settings, actor) => store.withTenant(tenantRef, (tenant) => tenant.putAssistantSettings({