slotlock 0.5.2 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slotlock",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "type": "module",
   "description": "Resource-first, deterministic calendar and availability engine for AI agents.",
   "license": "Apache-2.0",

package/rest-api.js

@@ -404,6 +404,18 @@ export function slotlockOpenApiDocument(args) {
                         resource_id: { type: 'string', description: 'An overlap: the resource it refused.' },
                         start: { type: 'string', description: 'An overlap: the start it refused.' },
                         end: { type: 'string', description: 'An overlap: the end it refused.' },
+                        issues: {
+                            type: 'array',
+                            description: '`invalid_arguments` from argument validation: each field it refused (at most 20), by its path in the arguments, outermost first; `[]` is the arguments as a whole.',
+                            items: {
+                                type: 'object',
+                                required: ['path', 'message'],
+                                properties: {
+                                    path: { type: 'array', items: { type: ['string', 'integer'] } },
+                                    message: { type: 'string' },
+                                },
+                            },
+                        },
                         error: {
                             type: 'object',
                             required: ['code'],

package/self-host.js

@@ -8,7 +8,7 @@ import { createHash, timingSafeEqual } from 'node:crypto';
 import { parseArgs } from 'node:util';
 import postgres from 'postgres';
 import { createSlotlockAgentServer, slotlockAgentOperationScope, } from './agent-server.js';
-import { createSlotlockStoreAgentBackend, createSlotlockStoreApplicationBackend, } from './agent-store-backend.js';
+import { createSlotlockStoreAgentBackend, createSlotlockStoreApplicationBackend, createSlotlockStoreChangeSource, } from './agent-store-backend.js';
 import { SLOTLOCK_API_KEY_DEFAULT_SCOPES, SLOTLOCK_API_KEY_MAX_LIFETIME_DAYS, SLOTLOCK_API_KEY_SCOPES, createSlotlockApiKeyAuthenticator, createSlotlockApiKeyStore, slotlockBearerCredential, } from './api-keys.js';
 import { createSlotlockDashboard, createSlotlockDashboardResources, createSlotlockAcceptanceRecords, createSlotlockDashboardState, } from './dashboard.js';
 import { SECRET_HINT, SlotlockConfigError, formatSlotlockRate, optional, readAvailability, readDashboardConfig, readDashboardOrganizations, readLimits, readSecret, readServerUrl, readTrustedProxyHeader, slotlockKeySubscriptions, } from './config.js';
@@ -390,8 +390,13 @@ export async function migrateSlotlock(config, log) {
     const owner = connect(config.migrateDatabaseUrl ?? config.databaseUrl, 1);
     try {
         const store = createSlotlockStore(owner);
-        await store.applySchema();
-        await store.applyTenantRls();
+        try {
+            await store.applySchema();
+            await store.applyTenantRls();
+        }
+        catch (error) {
+            throw await migrateRefusal(owner, config, error);
+        }
         log.info('schema_applied');
         if (config.migrateDatabaseUrl === undefined)
             return;
@@ -412,6 +417,36 @@ export async function migrateSlotlock(config, log) {
         await owner.end({ timeout: 5 });
     }
 }
+/**
+ * Migrate run as the serving role, with no SLOTLOCK_MIGRATE_DATABASE_URL, is refused: as
+ * `unsafe_slotlock_schema`, with one reason per object the role does not own, when a role that is
+ * not a superuser owns the schema, and with a permission error (42501) when a superuser does. Lead
+ * with the fix, and keep the code, the reasons and the database's message after it.
+ */
+async function migrateRefusal(sql, config, error) {
+    const code = error?.code;
+    if (config.migrateDatabaseUrl !== undefined ||
+        !(error instanceof Error) ||
+        (code !== 'unsafe_slotlock_schema' && code !== '42501')) {
+        return error;
+    }
+    let found;
+    try {
+        [found] = await sql `
+      SELECT current_user AS role, pg_catalog.pg_get_userbyid(ns.nspowner) AS owner
+        FROM pg_catalog.pg_namespace ns
+       WHERE ns.nspname = 'slotlock'`;
+    }
+    catch {
+        return error;
+    }
+    if (!found || found.role === found.owner)
+        return error;
+    return Object.assign(new Error(`set SLOTLOCK_MIGRATE_DATABASE_URL to the schema owner's URL: migrate connected as ${found.role} (DATABASE_URL), but ${found.owner} owns the slotlock schema, and only its owner can migrate it. DATABASE_URL stays the serving role's.\n${error.message}`, { cause: error }), {
+        code,
+        ...('reasons' in error ? { reasons: error.reasons } : {}),
+    });
+}
 async function databaseReachable(sql) {
     let timeout;
     try {
@@ -533,6 +568,19 @@ export async function startSlotlockServer(config, log) {
         if (!schema?.present) {
             throw Object.assign(new Error('The slotlock schema is missing: run `slotlock migrate` or `slotlock serve --migrate`'), { code: 'schema_missing' });
         }
+        // Serving as the schema owner is allowed (one role can migrate and serve), but the owner can
+        // lift forced row-level security, drop the exclusion constraints and read any table that does
+        // not force it: say so once, at startup, rather than refuse.
+        const [owning] = await sql `
+      SELECT pg_catalog.pg_has_role(current_user, ns.nspowner, 'MEMBER') AS owns
+        FROM pg_catalog.pg_namespace ns
+       WHERE ns.nspname = 'slotlock'`;
+        if (owning?.owns) {
+            log.warn('serving_as_schema_owner', {
+                role: serving?.role,
+                message: "DATABASE_URL connects as the role that owns the slotlock schema. Row-level security does not confine its owner on tables that do not force it, and the owner can lift it: serve as a role that owns nothing (CREATE ROLE slotlock_app LOGIN PASSWORD '…' NOSUPERUSER NOBYPASSRLS) and set SLOTLOCK_MIGRATE_DATABASE_URL to the schema owner's URL so migrate grants it what it needs",
+            });
+        }
         // Migrated by another release: an older schema needs this release's migrate first, and a newer
         // one has tables and rules this release's code does not know.
         await assertSlotlockSchemaCurrent(sql);
@@ -657,6 +705,8 @@ export async function startSlotlockServer(config, log) {
                 return true;
             },
             subscriptions: {
+                // Live updates poll each tenant's change feed (one reader per tenant).
+                changes: createSlotlockStoreChangeSource(store, sql),
                 maxTotal: caps.subscriptions,
                 maxPerTenant: caps.tenant_subscriptions,
                 maxPerPrincipal: slotlockKeySubscriptions(caps),
@@ -789,7 +839,9 @@ export async function startSlotlockServer(config, log) {
                     send,
                     feed: {
                         claimWebhookDeliveries: (params) => deliveryStore.withTenant(tenantRef, (tenant) => tenant.claimWebhookDeliveries(params)),
-                        settleWebhookDelivery: (params) => deliveryStore.withTenant(tenantRef, (tenant) => tenant.settleWebhookDelivery(params)),
+                        settleWebhookDelivery: (params) => deliveryStore.withTenant(tenantRef, (tenant) => tenant.settleWebhookDelivery(params), {
+                            origin: 'maintenance',
+                        }),
                     },
                 }),
                 // Counts only, never the tenant or a URL.
@@ -1551,7 +1603,7 @@ export async function runSlotlockCli(argv, io) {
             }
             case 'key rotate': {
                 const config = readSlotlockDatabaseConfig(io.env);
-                const rotated = await withApiKeys(config, (keys) => keys.rotate({ tenantRef: config.tenantRef, id: operands[1] }));
+                const rotated = await withApiKeys(config, (keys) => keys.rotate({ tenantRef: config.tenantRef, id: operands[1], actor: CLI_KEY_CREATOR }));
                 if (!rotated) {
                     io.stderr.write('slotlock: no active API key with that id in this tenant\n');
                     return 1;
@@ -1562,7 +1614,7 @@ export async function runSlotlockCli(argv, io) {
             }
             case 'key revoke': {
                 const config = readSlotlockDatabaseConfig(io.env);
-                const revoked = await withApiKeys(config, (keys) => keys.revoke({ tenantRef: config.tenantRef, id: operands[1] }));
+                const revoked = await withApiKeys(config, (keys) => keys.revoke({ tenantRef: config.tenantRef, id: operands[1], actor: CLI_KEY_CREATOR }));
                 if (!revoked) {
                     io.stderr.write('slotlock: no API key with that id in this tenant\n');
                     return 1;

package/slotlock.manifest.json

@@ -3,7 +3,7 @@
   "schemaVersion": "1.0",
   "name": "Slotlock",
   "package": "slotlock",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Resource-first, deterministic calendar and availability engine for AI agents.",
   "intervalSemantics": {
     "boundary": "[)",

package/store.d.ts

@@ -1,8 +1,8 @@
-import { type SlotlockEventFeed } from './event-feed.js';
+import { type SlotlockChangeOrigin, type SlotlockEventFeed } from './event-feed.js';
 import { type SlotlockBookingRules } from './booking-rules.js';
 import type { Sql, TransactionSql } from 'postgres';
 import { SLOTLOCK_CALENDAR_HORIZON_DAYS } from './rules.js';
-import type { AcquireHoldResult, CalendarCoverageCommand, CalendarCoverageResult, CalendarEventContent, CalendarEventRetentionResult, BookingRetentionResult, SlotlockTenantErasure, CalendarFreeBusy, CalendarHorizonRollCursor, CalendarHorizonRollResult, CancelCalendarEventResult, CancelExternalReservationResult, ConfirmHoldResult, CreateReservationResult, DeleteResourceResult, ExternalReservationCommand, ExternalReservationResult, Interval, SlotlockCalendarEvent, SlotlockAgendaEntry, SlotlockHold, SlotlockReservation, SlotlockResource, PutCalendarEventCommand, PutCalendarEventResult, ReleaseHoldResult, WeeklyAvailabilityRule } from './types.js';
+import type { AcquireHoldResult, CalendarCoverageCommand, CalendarCoverageResult, CalendarEventContent, CalendarEventRetentionResult, BookingRetentionResult, SlotlockTenantErasure, SlotlockBookingRuleDefaults, CalendarFreeBusy, CalendarHorizonRollCursor, CalendarHorizonRollResult, CancelCalendarEventResult, CancelExternalReservationResult, ConfirmHoldResult, CreateReservationResult, DeleteResourceResult, ExternalReservationCommand, ExternalReservationResult, Interval, SlotlockCalendarEvent, SlotlockAgendaEntry, SlotlockHold, SlotlockReservation, SlotlockResource, PutCalendarEventCommand, PutCalendarEventResult, ReleaseHoldResult, WeeklyAvailabilityRule } from './types.js';
 export { SLOTLOCK_CALENDAR_HORIZON_DAYS };
 /**
  * Longest one-off event the store accepts (ten years and some leap days): long enough for any lease
@@ -90,6 +90,8 @@ export declare function legacyPutCommandHash(params: Parameters<typeof putComman
 }): string;
 /** Members a pool booking or search considers at most, in id order. */
 export declare const SLOTLOCK_MAX_POOL_MEMBERS = 100;
+/** The most pools of one tenant that may have default booking rules (`setBookingRuleDefaults`). */
+export declare const SLOTLOCK_MAX_POOL_RULE_DEFAULTS = 1000;
 export declare function isPoolName(value: unknown): value is string;
 export interface SlotlockStore extends SlotlockEventFeed {
     /**
@@ -148,6 +150,13 @@ export interface SlotlockStore extends SlotlockEventFeed {
          * without control characters: the history (listHistory) records it with each change.
          */
         actor?: string;
+        /**
+         * Where the changes come from (SLOTLOCK_CHANGE_ORIGINS: `mcp`, `rest`, `dashboard`, ...),
+         * recorded with each beside the actor. Unset, the enclosing withTenant's, else `library`.
+         */
+        origin?: SlotlockChangeOrigin;
+        /** The id (a UUID) of the API key making these changes, recorded with each. */
+        keyId?: string;
     }): Promise<T>;
     /**
      * INVARIANT (erasure completeness): a tenant integration must use a stable, erasable business
@@ -228,6 +237,24 @@ export interface SlotlockStore extends SlotlockEventFeed {
         id: string;
         rules: SlotlockBookingRules | null;
     }): Promise<SlotlockResource | null>;
+    /**
+     * Set (or clear, with `null`) the tenant's default booking rules, or one pool's (`pool`): a
+     * resource's rules as they apply (`effectiveBookingRules`) are the tenant's, overlaid by its
+     * pool's, overlaid by its own, a field set at a narrower level winning. They apply to bookings made
+     * from then on. `checkInMinutes` is only a resource's own (`invalid_booking_rules`, as for rules
+     * outside their bounds); `pool` is a pool name (`invalid_pool`). At most
+     * SLOTLOCK_MAX_POOL_RULE_DEFAULTS pools a tenant have them (`pool_rules_limit_reached` for one
+     * more). Returns the rules stored.
+     */
+    setBookingRuleDefaults(params: {
+        tenantRef: string;
+        pool: string | null;
+        rules: SlotlockBookingRules | null;
+    }): Promise<SlotlockBookingRules | null>;
+    /** The tenant's default booking rules, and each pool's that has them, by pool name. */
+    getBookingRuleDefaults(params: {
+        tenantRef: string;
+    }): Promise<SlotlockBookingRuleDefaults>;
     /**
      * Put one resource in a pool, or take it out (`null`): `pool` is 1-100 characters of a-z, 0-9,
      * `.`, `_` and `-`, starting with a letter or digit (`invalid_pool` otherwise). A resource is in
@@ -870,6 +897,11 @@ export type CheckInReservationResult = {
 /** One source's coverage of a resource, with its health (listCoverage). */
 export interface SlotlockCoverageHealth {
     source: string;
+    /**
+     * How the change feed names the source, never the source itself: `src_` and 32 random hex
+     * digits, made when the source is first recorded for the resource and kept until it is deleted.
+     */
+    sourceId: string;
     start: Date;
     end: Date;
     revision: number;
@@ -974,4 +1006,4 @@ export declare function createSlotlockStore(sql: StoreSql, options?: SlotlockSto
  * Every store method that writes for a tenant: what a suspended tenant's withTenant store refuses.
  * Maintenance (rolling series, pruning, purging) and erasure are not among them.
  */
-export declare const SLOTLOCK_TENANT_WRITE_METHODS: readonly ["createResource", "archiveResource", "restoreResource", "deleteResource", "setResourceAvailability", "setResourceBookingRules", "setResourcePool", "setTenantAvailability", "createReservation", "createExternalReservation", "rescheduleExternalReservation", "cancelExternalReservation", "acquireHold", "confirmHold", "releaseHold", "putCalendarEvent", "cancelCalendarEvent", "cancelCalendarEventById", "recordCalendarCoverage", "createWebhookEndpoint", "deleteWebhookEndpoint", "enableWebhookEndpoint", "recordCoverageFailure", "deleteCoverage", "checkInReservation", "joinWaitlist", "leaveWaitlist", "putAssistantSettings", "deleteAssistantSettings", "putAssistantConversation", "settleAssistantAction", "deleteAssistantConversation"];
+export declare const SLOTLOCK_TENANT_WRITE_METHODS: readonly ["createResource", "archiveResource", "restoreResource", "deleteResource", "setResourceAvailability", "setResourceBookingRules", "setBookingRuleDefaults", "setResourcePool", "setTenantAvailability", "createReservation", "createExternalReservation", "rescheduleExternalReservation", "cancelExternalReservation", "acquireHold", "confirmHold", "releaseHold", "putCalendarEvent", "cancelCalendarEvent", "cancelCalendarEventById", "recordCalendarCoverage", "createWebhookEndpoint", "deleteWebhookEndpoint", "enableWebhookEndpoint", "recordCoverageFailure", "deleteCoverage", "checkInReservation", "joinWaitlist", "leaveWaitlist", "putAssistantSettings", "deleteAssistantSettings", "putAssistantConversation", "settleAssistantAction", "deleteAssistantConversation"];