slotlock 0.3.0 → 0.5.1

package/self-host.js

@@ -3,18 +3,21 @@
 // supplies it the same way and nothing is read from a file or a request. A missing or weak secret
 // stops a command before it connects anywhere, and no secret is written to a log line or an error.
 // The one exception is the API key `key create` prints: that output is the key's only copy.
+import { createSlotlockWebhookSender, deliverSlotlockWebhooks, startSlotlockWebhookDelivery, } from './webhooks.js';
 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 { 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, createSlotlockDashboardState, } from './dashboard.js';
-import { SECRET_HINT, SlotlockConfigError, formatSlotlockRate, optional, readAvailability, readDashboardConfig, readLimits, readSecret, readServerUrl, readTrustedProxyHeader, slotlockKeySubscriptions, } from './config.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';
+import { parseBookingRules } from './booking-rules.js';
 import { SLOTLOCK_APPLICATION_SCOPE } from './application-api.js';
 import { SLOTLOCK_DASHBOARD_FUNCTIONS, SLOTLOCK_TENANT_TABLES } from './ddl.js';
 import { maintainSlotlockTenant, startSlotlockMaintenance, withSlotlockMaintenanceLock, } from './maintenance.js';
 import { createSlotlockNodeServer, } from './node-server.js';
+import { createSlotlockMetrics } from './metrics.js';
 import { slotlockPackageVersion } from './package-version.js';
 import { createSlotlockRequestLimits } from './rate-limit.js';
 import { assertSlotlockSchemaCurrent, createSlotlockStore, } from './store.js';
@@ -27,16 +30,22 @@ export const SLOTLOCK_ENVIRONMENT_VARIABLES = Object.freeze([
     'SLOTLOCK_AUTH_TOKEN',
     'SLOTLOCK_CONFIRMATION_SECRET',
     'SLOTLOCK_CONFIRM_WRITES',
+    'SLOTLOCK_METRICS_TOKEN',
     'SLOTLOCK_PUBLIC_URL',
     'SLOTLOCK_TENANT',
     'SLOTLOCK_AVAILABILITY',
     'SLOTLOCK_REST_API',
+    'SLOTLOCK_RETENTION_DAYS',
+    'SLOTLOCK_WEBHOOKS',
+    'SLOTLOCK_SHARED_LIMITS',
     'SLOTLOCK_LIMITS',
     'SLOTLOCK_TRUSTED_PROXY_HEADER',
     'SLOTLOCK_GITHUB_CLIENT_ID',
     'SLOTLOCK_GITHUB_CLIENT_SECRET',
     'SLOTLOCK_SESSION_SECRET',
     'SLOTLOCK_DASHBOARD_USERS',
+    'SLOTLOCK_DASHBOARD_ORGS',
+    'SLOTLOCK_DASHBOARD_NAME',
     'HOST',
     'PORT',
 ]);
@@ -59,6 +68,8 @@ const SERVE_MAINTENANCE_INTERVAL_MS = 60 * 60 * 1_000;
 const MAINTAIN_MAX_PASSES = 100;
 const WRITE_OPERATIONS = [
     'slotlock_create_event',
+    'slotlock_book_together',
+    'slotlock_book_pool',
     'slotlock_update_event',
     'slotlock_delete_event',
 ];
@@ -70,6 +81,12 @@ const SERVED_OPERATIONS = new Set([
     'slotlock_list_resources',
     'slotlock_get_free_busy',
     'slotlock_find_next_available',
+    'slotlock_find_available_slots',
+    'slotlock_hold_slots',
+    'slotlock_release_slots',
+    'slotlock_book_together',
+    'slotlock_book_pool',
+    'slotlock_get_pool_availability',
     'slotlock_create_event',
     'slotlock_get_event',
     'slotlock_list_events',
@@ -151,11 +168,38 @@ export function readSlotlockDatabaseConfig(env) {
         throw new SlotlockConfigError('DATABASE_URL is required: the postgres:// URL of the role Slotlock serves as');
     }
     const config = { databaseUrl, tenantRef: readTenant(env) };
+    const retentionDays = readRetentionDays(env);
+    if (retentionDays !== undefined)
+        config.retentionDays = retentionDays;
     const migrateDatabaseUrl = readDatabaseUrl(env, 'SLOTLOCK_MIGRATE_DATABASE_URL');
     if (migrateDatabaseUrl !== undefined)
         config.migrateDatabaseUrl = migrateDatabaseUrl;
     return config;
 }
+function readWebhooks(env) {
+    const value = optional(env, 'SLOTLOCK_WEBHOOKS') ?? 'on';
+    if (value !== 'on' && value !== 'off' && value !== 'private') {
+        throw new SlotlockConfigError('SLOTLOCK_WEBHOOKS must be on, off or private');
+    }
+    return value;
+}
+/** SLOTLOCK_RETENTION_DAYS: how long history is kept, in days (createSlotlockStore's `retentionDays`). */
+function readRetentionDays(env) {
+    const value = optional(env, 'SLOTLOCK_RETENTION_DAYS');
+    if (value === undefined)
+        return undefined;
+    if (!/^[1-9]\d{0,3}$/.test(value) || Number(value) > 3_650) {
+        throw new SlotlockConfigError('SLOTLOCK_RETENTION_DAYS must be a whole number of days from 1 to 3650');
+    }
+    return Number(value);
+}
+function readSharedLimits(env) {
+    const value = optional(env, 'SLOTLOCK_SHARED_LIMITS') ?? 'off';
+    if (value !== 'on' && value !== 'off') {
+        throw new SlotlockConfigError('SLOTLOCK_SHARED_LIMITS must be on or off');
+    }
+    return value === 'on';
+}
 function readRestApi(env) {
     const value = optional(env, 'SLOTLOCK_REST_API') ?? 'on';
     if (value !== 'on' && value !== 'off') {
@@ -185,6 +229,8 @@ export function readSlotlockServeConfig(env) {
         confirmWrites,
         availability: readAvailability(env),
         restApi: readRestApi(env),
+        webhooks: readWebhooks(env),
+        sharedLimits: readSharedLimits(env),
         limits: readLimits(env),
     };
     const trustedProxyHeader = readTrustedProxyHeader(env);
@@ -192,9 +238,25 @@ export function readSlotlockServeConfig(env) {
         config.trustedProxyHeader = trustedProxyHeader;
     if (authToken !== undefined)
         config.authToken = authToken;
+    const metricsToken = readSecret(env, 'SLOTLOCK_METRICS_TOKEN');
+    if (metricsToken !== undefined) {
+        const others = [
+            authToken,
+            confirmationSecret,
+            env.SLOTLOCK_SESSION_SECRET?.trim(),
+            env.SLOTLOCK_GITHUB_CLIENT_SECRET?.trim(),
+        ];
+        if (others.includes(metricsToken)) {
+            throw new SlotlockConfigError('SLOTLOCK_METRICS_TOKEN must differ from every other secret');
+        }
+        config.metricsToken = metricsToken;
+    }
     const dashboard = readDashboardConfig(env);
     if (dashboard !== undefined)
         config.dashboard = dashboard;
+    const organizations = readDashboardOrganizations(env);
+    if (organizations !== undefined)
+        config.organizations = organizations;
     if (confirmWrites.length > 0 && confirmationSecret !== undefined) {
         config.confirmationSecret = confirmationSecret;
     }
@@ -246,6 +308,7 @@ function secretsIn(env) {
         'SLOTLOCK_CONFIRMATION_SECRET',
         'SLOTLOCK_GITHUB_CLIENT_SECRET',
         'SLOTLOCK_SESSION_SECRET',
+        'SLOTLOCK_METRICS_TOKEN',
     ]) {
         const value = env[name]?.trim();
         if (value)
@@ -364,10 +427,48 @@ async function databaseReachable(sql) {
     }
 }
 /**
- * Whether the dashboard's allowlist lets a tenant act: every tenant when there is no dashboard or it
- * allows everyone, and a `github:<id>` tenant only while that id is listed.
+ * `GET <path>` answers the metrics to `Authorization: Bearer <token>`, before the request limits:
+ * a scrape is in memory and names no tenant. Anything else goes on to `target`.
+ */
+function serveMetrics(target, metrics, path, token) {
+    const expected = createHash('sha256').update(token).digest();
+    return {
+        fetch(request, connection) {
+            if (new URL(request.url).pathname !== path)
+                return target.fetch(request, connection);
+            // The scheme is case-insensitive (RFC 9110); the token is compared as digests, in constant time.
+            const presented = /^bearer +(\S+) *$/i.exec(request.headers.get('authorization') ?? '')?.[1] ?? '';
+            const given = createHash('sha256').update(presented).digest();
+            if (!timingSafeEqual(given, expected)) {
+                metrics.refusedScrape();
+                return Promise.resolve(new Response('Unauthorized\n', {
+                    status: 401,
+                    headers: { 'Content-Type': 'text/plain; charset=utf-8', 'WWW-Authenticate': 'Bearer' },
+                }));
+            }
+            if (request.method !== 'GET' && request.method !== 'HEAD') {
+                return Promise.resolve(new Response(null, { status: 405, headers: { Allow: 'GET, HEAD' } }));
+            }
+            return Promise.resolve(new Response(request.method === 'HEAD' ? null : metrics.render(), {
+                headers: {
+                    'Content-Type': 'text/plain; version=0.0.4; charset=utf-8',
+                    'Cache-Control': 'no-store',
+                },
+            }));
+        },
+        ...(target.shutdown ? { shutdown: () => target.shutdown?.() } : {}),
+    };
+}
+/**
+ * Whether the dashboard's allowlists let a tenant act: a `github-org:<id>` tenant only while
+ * SLOTLOCK_DASHBOARD_ORGS lists that organization, wherever the dashboard runs; otherwise every
+ * tenant when there is no dashboard or it allows everyone, and a `github:<id>` tenant only while
+ * that id is listed.
  */
 function dashboardAllows(config, tenantRef) {
+    const orgId = /^github-org:(\d+)$/.exec(tenantRef)?.[1];
+    if (orgId !== undefined)
+        return config.organizations?.includes(orgId) === true;
     const users = config.dashboard?.allowedUsers;
     if (users === undefined || users === '*')
         return true;
@@ -387,13 +488,29 @@ function serveTenantLimits(caps) {
  * The store `serve` answers requests from. Every surface writes through it, so its tenant limits
  * bound what any key can add, and its transaction limits what one tenant holds of the shared pool.
  */
-export function createSlotlockServeStore(sql, caps) {
+export function createSlotlockServeStore(sql, caps, availability = [], retentionDays) {
     return createSlotlockStore(sql, {
+        ...(retentionDays !== undefined ? { retentionDays } : {}),
+        defaultAvailabilityRules: availability,
         tenantLimits: serveTenantLimits(caps),
         maxTenantTransactions: caps.tenant_transactions,
+        maxHoldsPerHolder: caps.holder_holds,
+        maxHeldHoursPerHolder: caps.holder_held_hours,
         tenantLockTimeoutMs: SERVE_LOCK_TIMEOUT_MS,
     });
 }
+/**
+ * The store maintenance writes through, `serve`'s and `maintain`'s: the same tenant and per-holder
+ * limits as requests, so a waitlist offer is a hold like any other.
+ */
+export function createSlotlockMaintenanceStore(sql, caps, options = {}) {
+    return createSlotlockStore(sql, {
+        ...options,
+        tenantLimits: serveTenantLimits(caps),
+        maxHoldsPerHolder: caps.holder_holds,
+        maxHeldHoursPerHolder: caps.holder_held_hours,
+    });
+}
 /** Serve MCP and A2A over HTTP from the Postgres store, as one token-authenticated tenant. */
 export async function startSlotlockServer(config, log) {
     const sql = connect(config.databaseUrl, POOL_SIZE);
@@ -439,8 +556,22 @@ export async function startSlotlockServer(config, log) {
                 }
             }
         }
+        if (config.confirmationSecret !== undefined) {
+            // Accepted confirmations are recorded once each (0.3.1); an older schema cannot hold them.
+            const [recordable] = await sql `
+        SELECT EXISTS (
+          SELECT 1 FROM pg_catalog.pg_constraint
+           WHERE conname = 'slotlock_dashboard_tokens_kind_valid'
+             AND conrelid = to_regclass('slotlock.dashboard_tokens')
+             AND pg_catalog.pg_get_constraintdef(oid) LIKE '%confirmation%'
+        ) AND has_function_privilege(to_regprocedure(${SLOTLOCK_DASHBOARD_FUNCTIONS[0]}), 'EXECUTE') AS ready`;
+            if (!recordable?.ready) {
+                throw Object.assign(new Error('SLOTLOCK_CONFIRM_WRITES records each accepted confirmation, which this schema cannot: run `slotlock migrate` (or `slotlock serve --migrate`) with this release'), { code: 'schema_outdated' });
+            }
+        }
         const { caps } = config.limits;
-        const store = createSlotlockServeStore(sql, caps);
+        const store = createSlotlockServeStore(sql, caps, config.availability, config.retentionDays);
+        const retention = config.retentionDays !== undefined ? { retentionDays: config.retentionDays } : {};
         const publicUrl = new URL(config.publicUrl);
         const authenticateKey = createSlotlockApiKeyAuthenticator(createSlotlockApiKeyStore(sql), {
             maxConcurrentLookups: caps.key_lookups,
@@ -457,9 +588,29 @@ export async function startSlotlockServer(config, log) {
                 });
         // Set once the listener is up; the authenticator tells it which tenants this server serves.
         let maintenance;
+        let webhooks;
         const basePath = publicUrl.pathname.replace(/\/$/, '');
+        const metrics = config.metricsToken === undefined
+            ? undefined
+            : createSlotlockMetrics({
+                version: slotlockPackageVersion(),
+                ...(process.versions.tz ? { tzdata: process.versions.tz } : {}),
+            });
         const limits = createSlotlockRequestLimits({
             limits: config.limits,
+            ...(config.sharedLimits
+                ? {
+                    shared: {
+                        // Keyed by a digest: the table keeps no tenant name.
+                        take: async (bucket, rate) => {
+                            const digest = createHash('sha256').update(bucket).digest('hex');
+                            const [row] = await sql `
+                  SELECT slotlock.take_rate_token(${digest}, ${rate.perSecond}, ${rate.burst}) AS taken`;
+                            return row?.taken === true;
+                        },
+                    },
+                }
+                : {}),
             ...(config.trustedProxyHeader !== undefined
                 ? { trustedProxyHeader: config.trustedProxyHeader }
                 : {}),
@@ -475,7 +626,10 @@ export async function startSlotlockServer(config, log) {
                 return principal;
             },
             // Counts and pseudonyms only: never an address, a credential or a tenant.
-            onRefusals: (counts) => log.info('refusals', { ...counts }),
+            onRefusals: (counts) => {
+                metrics?.refusals(counts);
+                log.info('refusals', { ...counts });
+            },
             // Behind a proxy without the setting, every client shares the proxy's address budget.
             onIgnoredClientField: (field) => log.warn('client_address_field_ignored', { field, setting: 'SLOTLOCK_TRUSTED_PROXY_HEADER' }),
         });
@@ -511,7 +665,11 @@ export async function startSlotlockServer(config, log) {
                     : { ready: false, checks: ['database_unreachable'] };
             },
             // Outcomes and counts only: the server never reports arguments or identities.
-            onEvent: ({ type, ...fields }) => log.info(type, snakeCaseKeys(fields)),
+            onEvent: (event) => {
+                metrics?.event(event);
+                const { type, ...fields } = event;
+                log.info(type, snakeCaseKeys(fields));
+            },
             // What an agent sees only as internal_error: the operation and the error's message and code,
             // never the arguments or the request, with every configured secret redacted.
             onError: (error, { operation }) => log.error('agent_error', { operation, ...describeError(error) }),
@@ -537,6 +695,7 @@ export async function startSlotlockServer(config, log) {
                     confirmation: {
                         operations: config.confirmWrites,
                         secrets: [config.confirmationSecret],
+                        consumeAcceptance: createSlotlockAcceptanceRecords(sql),
                     },
                 }
                 : {}),
@@ -551,6 +710,10 @@ export async function startSlotlockServer(config, log) {
                 },
                 sessionSecret: config.dashboard.sessionSecret,
                 allowedUsers: config.dashboard.allowedUsers,
+                ...(config.dashboard.name ? { name: config.dashboard.name } : {}),
+                ...(config.dashboard.organizations
+                    ? { organizations: config.dashboard.organizations }
+                    : {}),
                 keys: createSlotlockApiKeyStore(sql),
                 resources: createSlotlockDashboardResources(store),
                 state: createSlotlockDashboardState(sql),
@@ -564,21 +727,58 @@ export async function startSlotlockServer(config, log) {
                 shutdown: () => agentServer.shutdown(),
             }
             : agentServer);
-        const listener = createSlotlockNodeServer(target, {
+        const served = metrics && config.metricsToken !== undefined
+            ? serveMetrics(target, metrics, `${basePath}/metrics`, config.metricsToken)
+            : target;
+        const listener = createSlotlockNodeServer(served, {
             requestOrigin: publicUrl.origin,
             onError: (error, phase) => log.error('http_error', { phase, ...describeError(error) }),
         });
         const address = await listener.listen({ host: config.host, port: config.port });
         maintenance = startSlotlockMaintenance({
             // One tenant at a time, and its long passes may wait on a request's locks for longer.
-            store: createSlotlockStore(sql, { tenantLimits: serveTenantLimits(caps) }),
+            store: createSlotlockMaintenanceStore(sql, caps, retention),
             sql,
             tenants: [config.tenantRef],
             intervalMs: SERVE_MAINTENANCE_INTERVAL_MS,
             // Counts only, never the tenant.
-            onPass: (result) => log.info('maintenance', { ...result }),
+            onPass: (result) => {
+                metrics?.maintenance(result);
+                log.info('maintenance', { ...result });
+            },
             onError: (error) => log.error('maintenance_failed', describeError(error)),
         });
+        if (config.webhooks !== 'off') {
+            const deliveryStore = createSlotlockStore(sql, retention);
+            const send = createSlotlockWebhookSender({ allowPrivateNetworks: config.webhooks === 'private' });
+            webhooks = startSlotlockWebhookDelivery({
+                // The tenants with a webhook, from the database: a restarted server finds them all.
+                tenants: async () => {
+                    const tenants = [];
+                    for (;;) {
+                        const page = await sql `
+              SELECT slotlock.webhook_tenants(${tenants.at(-1) ?? null}::text) AS tenant`;
+                        tenants.push(...page.map(({ tenant }) => tenant));
+                        if (page.length < 1_000)
+                            return tenants;
+                    }
+                },
+                deliver: (tenantRef) => deliverSlotlockWebhooks({
+                    tenantRef,
+                    send,
+                    feed: {
+                        claimWebhookDeliveries: (params) => deliveryStore.withTenant(tenantRef, (tenant) => tenant.claimWebhookDeliveries(params)),
+                        settleWebhookDelivery: (params) => deliveryStore.withTenant(tenantRef, (tenant) => tenant.settleWebhookDelivery(params)),
+                    },
+                }),
+                // Counts only, never the tenant or a URL.
+                onPass: (_tenant, result) => {
+                    metrics?.webhooks(result);
+                    log.info('webhooks', { ...result });
+                },
+                onError: (error) => log.error('webhooks_failed', describeError(error)),
+            });
+        }
         log.info('listening', {
             address: address.origin,
             mcp: `${config.publicUrl}/mcp`,
@@ -589,6 +789,9 @@ export async function startSlotlockServer(config, log) {
             confirm_writes: config.confirmWrites,
             availability_rules: config.availability.length,
             rest: config.restApi ? `${config.publicUrl}/openapi.json` : null,
+            webhooks: config.webhooks,
+            shared_limits: config.sharedLimits,
+            tzdata: process.versions.tz ?? null,
             maintenance_interval_minutes: SERVE_MAINTENANCE_INTERVAL_MS / 60_000,
             limits: {
                 ...Object.fromEntries(Object.entries(config.limits.rates).map(([name, rate]) => [name, formatSlotlockRate(rate)])),
@@ -604,6 +807,7 @@ export async function startSlotlockServer(config, log) {
                 const result = await listener.close();
                 limits.close();
                 await maintenance?.close();
+                await webhooks?.close();
                 await sql.end({ timeout: 5 });
                 return result;
             },
@@ -718,6 +922,34 @@ async function runHours(config, out, target, rules) {
         await sql.end({ timeout: 5 });
     }
 }
+/**
+ * `rules set|clear`: set or clear (`null`) the booking rules of the tenant's resource named by id,
+ * else by reference, and print it. Returns false when no resource has that name.
+ */
+async function runRules(config, out, name, rules) {
+    const sql = connect(config.databaseUrl, 1);
+    try {
+        const store = createSlotlockStore(sql);
+        const tenantRef = config.tenantRef;
+        const resources = await tenantResources(store, tenantRef);
+        const named = resources.find((resource) => resource.id === name) ??
+            resources.find((resource) => resource.externalRef === name);
+        if (!named)
+            return false;
+        const updated = await store.withTenant(tenantRef, (tenant) => tenant.setResourceBookingRules({ tenantRef, id: named.id, rules }));
+        if (!updated)
+            return false;
+        out.write(`${JSON.stringify({
+            id: updated.id,
+            external_ref: updated.externalRef,
+            booking_rules: updated.bookingRules ?? null,
+        })}\n`);
+        return true;
+    }
+    finally {
+        await sql.end({ timeout: 5 });
+    }
+}
 /** A resource as `resource archive` and `resource restore` print it. */
 function resourceStateLine(resource) {
     return `${JSON.stringify({
@@ -832,12 +1064,23 @@ function parseKeyScopes(value) {
  * `maintain`: maintenance passes for the tenant until nothing is left, under the tenant's lock, so
  * it never repeats what a server is doing. Null when another server holds the lock.
  */
-async function maintainTenant(config) {
+async function maintainTenant(config, caps) {
     const sql = connect(config.databaseUrl, 2);
     try {
-        const store = createSlotlockStore(sql);
+        const store = createSlotlockMaintenanceStore(sql, caps, config.retentionDays !== undefined ? { retentionDays: config.retentionDays } : {});
         const total = await withSlotlockMaintenanceLock(sql, config.tenantRef, async () => {
-            const sum = { extended: 0, conflicts: 0, refused: 0, pruned: 0, capped: true, passes: 0 };
+            const sum = {
+                extended: 0,
+                conflicts: 0,
+                refused: 0,
+                pruned: 0,
+                zoneShifts: 0,
+                staleSources: 0,
+                noShows: 0,
+                waitlistOffers: 0,
+                capped: true,
+                passes: 0,
+            };
             while (sum.capped && sum.passes < MAINTAIN_MAX_PASSES) {
                 const pass = await maintainSlotlockTenant(store, config.tenantRef);
                 sum.passes += 1;
@@ -845,6 +1088,10 @@ async function maintainTenant(config) {
                 sum.conflicts += pass.conflicts;
                 sum.refused += pass.refused;
                 sum.pruned += pass.pruned;
+                sum.zoneShifts += pass.zoneShifts;
+                sum.staleSources += pass.staleSources;
+                sum.noShows += pass.noShows;
+                sum.waitlistOffers += pass.waitlistOffers;
                 // A capped pass that got nowhere met only series it cannot extend. While its roll stopped
                 // before the series it had put back, the next pass meets new ones (and perhaps a healthy
                 // one); once it reached them, another pass would meet them again.
@@ -920,6 +1167,11 @@ Commands:
                            Give one resource, or every one, weekly hours of its own; [] closes
   hours clear (--resource <ref> | --all)
                            Hand one resource, or every one, back to the server's hours
+  rules set <json> --resource <ref>
+                           Set what a booking on the resource must satisfy, like
+                           {"minNoticeMinutes":120,"slotStepMinutes":30,"turnaroundMinutes":30,"enforceHours":true}
+  rules clear --resource <ref>
+                           Remove the resource's booking rules
   key create <name> [--scope read,write,admin] [--expires-in-days <n>]
                            Create an API key for the tenant (default scope read,write, no
                            expiry; admin adds the application API) and print it once; only its
@@ -952,6 +1204,8 @@ Environment:
                                  work with or without it
   SLOTLOCK_CONFIRMATION_SECRET   Signs pending write confirmations, 32+ random characters (serve;
                                  required when SLOTLOCK_CONFIRM_WRITES is not none)
+  SLOTLOCK_METRICS_TOKEN         Serves Prometheus metrics at /metrics to this bearer token, 32+
+                                 random characters (serve; off without it)
   SLOTLOCK_CONFIRM_WRITES        none (default), all, or a comma-separated list of write tools
                                  that wait for a person (MCP 2026-07-28 form elicitation; refused
                                  with confirmation_required on REST, A2A and older MCP)
@@ -961,6 +1215,15 @@ Environment:
   SLOTLOCK_REST_API              on (default): also serve the tools as a REST API under /v1, and
                                  the application API for admin keys, described at /openapi.json;
                                  off: MCP and A2A only
+  SLOTLOCK_RETENTION_DAYS        Days of history kept: the change feed, ended waitlist entries,
+                                 and retired answers (never under 30) (1-3650, default 30;
+                                 serve and maintain)
+  SLOTLOCK_SHARED_LIMITS         on: tenant request budgets are shared by every server through the
+                                 database, so N servers allow a tenant its rate once; off (default):
+                                 each server keeps its own
+  SLOTLOCK_WEBHOOKS              on (default): deliver each tenant's changes to its webhooks,
+                                 never to a private network address; private: those too, for
+                                 testing; off: keep the change feed, send nothing
   SLOTLOCK_LIMITS                Request limits, comma-separated name=value over the defaults:
                                  rates as <count>/<s|m|h>[:<burst>] or off for address (50/s:100,
                                  every request per client, before any key lookup), key_read,
@@ -977,7 +1240,8 @@ Environment:
                                  tenant_transactions (2: one tenant's database transactions at
                                  once, of the pool's 10); what one tenant may store:
                                  tenant_holds (10000), tenant_reservations, tenant_events and
-                                 tenant_coverage (100000)
+                                 tenant_coverage (100000), holder_holds (20) and
+                                 holder_held_hours (2160), which maintain keeps too
   SLOTLOCK_TRUSTED_PROXY_HEADER  The request field a proxy in front sets to the client address,
                                  such as CF-Connecting-IP (default: the connection's address);
                                  set it only when every request comes through that proxy
@@ -986,6 +1250,8 @@ Environment:
   SLOTLOCK_GITHUB_CLIENT_SECRET  That app's client secret (dashboard)
   SLOTLOCK_SESSION_SECRET        Signs dashboard sessions, 32+ random characters (dashboard)
   SLOTLOCK_DASHBOARD_USERS       * or comma-separated GitHub user ids that may sign in (dashboard)
+  SLOTLOCK_DASHBOARD_ORGS        comma-separated GitHub organization ids: each is one shared tenant
+  SLOTLOCK_DASHBOARD_NAME        What the dashboard calls this deployment (default Slotlock)
   HOST                           Listen address (default 127.0.0.1)
   PORT                           Listen port (default 8080)
 
@@ -1022,7 +1288,11 @@ export async function runSlotlockCli(argv, io) {
         io.stderr.write(SLOTLOCK_CLI_HELP);
         return 2;
     }
-    const subcommand = command === 'resource' || command === 'key' || command === 'hours' || command === 'tenant'
+    const subcommand = command === 'resource' ||
+        command === 'key' ||
+        command === 'hours' ||
+        command === 'rules' ||
+        command === 'tenant'
         ? `${command} ${operands[0] ?? ''}`.trim()
         : command;
     const expectedOperands = {
@@ -1046,6 +1316,8 @@ export async function runSlotlockCli(argv, io) {
         'hours show': 1,
         'hours set': 2,
         'hours clear': 1,
+        'rules set': 2,
+        'rules clear': 1,
     };
     const expected = expectedOperands[subcommand];
     if (expected === undefined)
@@ -1074,8 +1346,24 @@ export async function runSlotlockCli(argv, io) {
     if (values.all && subcommand !== 'hours set' && subcommand !== 'hours clear') {
         return usage('--all applies only to hours set and hours clear');
     }
-    if (values.resource !== undefined && !subcommand.startsWith('hours ')) {
-        return usage('--resource applies only to hours commands');
+    if (values.resource !== undefined &&
+        !subcommand.startsWith('hours ') &&
+        !subcommand.startsWith('rules ')) {
+        return usage('--resource applies only to hours and rules commands');
+    }
+    if (subcommand.startsWith('rules ') && values.resource === undefined) {
+        return usage(`${subcommand} needs --resource <ref>`);
+    }
+    let bookingRules = null;
+    if (subcommand === 'rules set') {
+        try {
+            bookingRules = parseBookingRules(JSON.parse(operands[1]));
+        }
+        catch (error) {
+            return usage(error instanceof SyntaxError
+                ? 'rules must be a JSON object like {"minNoticeMinutes":120,"slotStepMinutes":30}'
+                : error.message);
+        }
     }
     if ((subcommand === 'hours set' || subcommand === 'hours clear') &&
         (values.resource === undefined) === (values.all !== true)) {
@@ -1128,7 +1416,7 @@ export async function runSlotlockCli(argv, io) {
                 return 0;
             }
             case 'maintain': {
-                const result = await maintainTenant(readSlotlockDatabaseConfig(io.env));
+                const result = await maintainTenant(readSlotlockDatabaseConfig(io.env), readLimits(io.env).caps);
                 if (!result) {
                     io.stderr.write('slotlock: another server is maintaining this tenant now; nothing to do\n');
                     return 0;
@@ -1199,6 +1487,15 @@ export async function runSlotlockCli(argv, io) {
                 }
                 return 0;
             }
+            case 'rules set':
+            case 'rules clear': {
+                const found = await runRules(readSlotlockDatabaseConfig(io.env), io.stdout, values.resource, bookingRules);
+                if (!found) {
+                    io.stderr.write('slotlock: no resource with that reference or id in this tenant\n');
+                    return 1;
+                }
+                return 0;
+            }
             case 'key create': {
                 const config = readSlotlockDatabaseConfig(io.env);
                 const created = await withApiKeys(config, (keys) => keys.create({

package/slotlock-manifest.schema.json

@@ -43,6 +43,7 @@
         "enum": [
           "availability-rules",
           "find-next-available",
+          "find-available-slots",
           "atomic-holds",
           "conflict-safe-reservations",
           "revisioned-external-commands",

package/slotlock.manifest.json

@@ -3,7 +3,7 @@
   "schemaVersion": "1.0",
   "name": "Slotlock",
   "package": "slotlock",
-  "version": "0.3.0",
+  "version": "0.5.1",
   "description": "Resource-first, deterministic calendar and availability engine for AI agents.",
   "intervalSemantics": {
     "boundary": "[)",
@@ -13,6 +13,7 @@
   "capabilities": [
     "availability-rules",
     "find-next-available",
+    "find-available-slots",
     "atomic-holds",
     "conflict-safe-reservations",
     "revisioned-external-commands",