slotlock 0.3.0 → 0.5.1

package/package.json

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

package/rate-limit.d.ts

@@ -1,6 +1,6 @@
 import { type SlotlockAgentOperation, type SlotlockAgentPrincipal } from './agent-server.js';
 import { type SlotlockApplicationOperation } from './application-api.js';
-import type { SlotlockLimits } from './config.js';
+import type { SlotlockLimits, SlotlockRate } from './config.js';
 import type { SlotlockNodeServerFetchTarget } from './node-server.js';
 export type SlotlockRefusalReason = 'auth_refused' | 'rate_limited' | 'lookup_overflow' | 'series_writes_busy' | 'maintenance_busy' | 'request_too_large';
 /** One `refusals` log line: counts since the last one, and the most refused clients as pseudonyms. */
@@ -31,6 +31,15 @@ export interface SlotlockRequestLimitsOptions {
     onIgnoredClientField?: (field: string) => void;
     /** Milliseconds, for tests; defaults to `performance.now`. */
     now?: () => number;
+    /**
+     * Budgets shared by every server (`SLOTLOCK_SHARED_LIMITS`): after this process's own buckets
+     * pass, each tenant budget (`tenant_*`, `app_*`) also takes a token from `take`, so N servers
+     * allow a tenant its rate once, not N times. `take` failing (the database away) lets the request
+     * through on this process's buckets alone, which still apply.
+     */
+    shared?: {
+        take(bucket: string, rate: SlotlockRate): Promise<boolean>;
+    };
 }
 export interface SlotlockRequestLimits {
     /** The agent server's `authenticate`: the request's lookup from `fetch`, else a lookup now. */

package/rate-limit.js

@@ -508,7 +508,7 @@ export function createSlotlockRequestLimits(options) {
      * charged its own buckets, so its refused application calls cannot spend the application's.
      * False, with the refusal recorded, when one is short.
      */
-    function chargeRequest(state, principal, classes) {
+    async function chargeRequest(state, principal, classes) {
         const due = classes.filter((kind) => !state.charged[kind]);
         if (due.length === 0)
             return true;
@@ -532,6 +532,29 @@ export function createSlotlockRequestLimits(options) {
             };
             return false;
         }
+        if (options.shared) {
+            for (const check of checks) {
+                if (!check.name.startsWith('tenant_') && !check.name.startsWith('app_'))
+                    continue;
+                const policy = policies.get(check.name)?.policy;
+                if (!policy)
+                    continue;
+                let allowed = true;
+                try {
+                    allowed = await options.shared.take(`${check.name}\0${check.key}`, policy.rate);
+                }
+                catch {
+                    // The shared budget is out of reach: this process's own buckets decided.
+                }
+                if (!allowed) {
+                    state.refusal = {
+                        reason: 'rate_limited',
+                        fields: fieldsOf({ policy, remaining: 0, seconds: Math.max(1, Math.ceil(1 / policy.rate.perSecond)) }, true),
+                    };
+                    return false;
+                }
+            }
+        }
         for (const kind of due)
             state.charged[kind] = true;
         if (outcome.verdict)
@@ -596,7 +619,7 @@ export function createSlotlockRequestLimits(options) {
             // where consumeRateLimit would take it (on /mcp and /a2a a request is charged a read token
             // only): a write over its budget is refused at once, not after holding a place in the queue
             // for a slot it could not use.
-            if (!chargeRequest(state, principal, ['write'])) {
+            if (!(await chargeRequest(state, principal, ['write']))) {
                 throw new SlotlockAgentOperationError('rate_limited', 429);
             }
             const slots = gates[kind];

package/rest-api.d.ts

@@ -5,10 +5,32 @@ export interface SlotlockRestRoute<Operation extends string = SlotlockAgentOpera
     /** Relative to the server's base URL; `{name}` is one path segment. */
     path: string;
     operation: Operation;
+    /**
+     * The store refusals the route can answer besides the ones every route can: 404 for a record
+     * that is missing or another tenant's, 409 for a conflict with what is stored (an overlap, a
+     * stale revision). The OpenAPI document declares them, so a generated client types them.
+     */
+    refusals?: readonly (404 | 409)[];
 }
 export declare const SLOTLOCK_REST_ROUTES: readonly SlotlockRestRoute[];
 /** The application operations' routes, served when the server has an application backend. */
 export declare const SLOTLOCK_APPLICATION_REST_ROUTES: readonly SlotlockRestRoute<SlotlockApplicationOperation>[];
+/** Where every REST refusal's documentation is: the Link header's `describedby` target. */
+export declare const SLOTLOCK_PROBLEM_DOCS = "https://slotlock.pylota.io/docs/api/#errors";
+/** A problem type's identifier: a tag URI (RFC 4151), stable, one per code, not a locator. */
+export declare function slotlockProblemType(code: string): string;
+/**
+ * A REST refusal as RFC 9457 problem details (`application/problem+json`): `type` and `title` name
+ * the problem, `code` is Slotlock's code, and `error.code` repeats it, the body every earlier
+ * client reads. `extensions` add what the refusal is about, such as the interval an overlap refused.
+ */
+export declare function slotlockProblem(status: number, code: string, extensions?: Record<string, unknown>): Record<string, unknown>;
+/**
+ * The Idempotency-Key header's value: a Structured Field String (RFC 9651, as
+ * draft-ietf-httpapi-idempotency-key-header-08 defines it), or the bare token clients sent before.
+ * `null` when it is a quoted string that does not parse.
+ */
+export declare function parseIdempotencyKeyHeader(value: string): string | null;
 /** Where an operation's arguments come from. */
 export declare function restInputFromBody(route: {
     method: string;

package/rest-api.js

@@ -1,13 +1,49 @@
 import { SLOTLOCK_APPLICATION_OPERATIONS, SLOTLOCK_APPLICATION_SCOPE, } from './application-api.js';
 export const SLOTLOCK_REST_ROUTES = Object.freeze([
     { method: 'GET', path: '/v1/resources', operation: 'slotlock_list_resources' },
-    { method: 'GET', path: '/v1/free-busy', operation: 'slotlock_get_free_busy' },
-    { method: 'GET', path: '/v1/next-available', operation: 'slotlock_find_next_available' },
-    { method: 'GET', path: '/v1/events', operation: 'slotlock_list_events' },
-    { method: 'POST', path: '/v1/events', operation: 'slotlock_create_event' },
-    { method: 'GET', path: '/v1/events/{event_id}', operation: 'slotlock_get_event' },
-    { method: 'PATCH', path: '/v1/events/{event_id}', operation: 'slotlock_update_event' },
-    { method: 'DELETE', path: '/v1/events/{event_id}', operation: 'slotlock_delete_event' },
+    { method: 'GET', path: '/v1/free-busy', operation: 'slotlock_get_free_busy', refusals: [404] },
+    {
+        method: 'GET',
+        path: '/v1/next-available',
+        operation: 'slotlock_find_next_available',
+        refusals: [404],
+    },
+    {
+        method: 'GET',
+        path: '/v1/available-slots',
+        operation: 'slotlock_find_available_slots',
+        refusals: [404],
+    },
+    { method: 'POST', path: '/v1/slot-holds', operation: 'slotlock_hold_slots', refusals: [409] },
+    { method: 'POST', path: '/v1/bundles', operation: 'slotlock_book_together', refusals: [404, 409] },
+    { method: 'POST', path: '/v1/pool-bookings', operation: 'slotlock_book_pool', refusals: [404, 409] },
+    {
+        method: 'GET',
+        path: '/v1/pool-availability',
+        operation: 'slotlock_get_pool_availability',
+        refusals: [404, 409],
+    },
+    {
+        method: 'DELETE',
+        path: '/v1/slot-holds/{hold_id}',
+        operation: 'slotlock_release_slots',
+        refusals: [409],
+    },
+    { method: 'GET', path: '/v1/events', operation: 'slotlock_list_events', refusals: [404] },
+    { method: 'POST', path: '/v1/events', operation: 'slotlock_create_event', refusals: [404, 409] },
+    { method: 'GET', path: '/v1/events/{event_id}', operation: 'slotlock_get_event', refusals: [404] },
+    {
+        method: 'PATCH',
+        path: '/v1/events/{event_id}',
+        operation: 'slotlock_update_event',
+        refusals: [404, 409],
+    },
+    {
+        method: 'DELETE',
+        path: '/v1/events/{event_id}',
+        operation: 'slotlock_delete_event',
+        refusals: [404, 409],
+    },
 ]);
 /** The application operations' routes, served when the server has an application backend. */
 export const SLOTLOCK_APPLICATION_REST_ROUTES = Object.freeze(SLOTLOCK_APPLICATION_OPERATIONS.map(({ method, path, name }) => ({
@@ -15,6 +51,86 @@ export const SLOTLOCK_APPLICATION_REST_ROUTES = Object.freeze(SLOTLOCK_APPLICATI
     path,
     operation: name,
 })));
+/** Where every REST refusal's documentation is: the Link header's `describedby` target. */
+export const SLOTLOCK_PROBLEM_DOCS = 'https://slotlock.pylota.io/docs/api/#errors';
+/** A problem type's identifier: a tag URI (RFC 4151), stable, one per code, not a locator. */
+export function slotlockProblemType(code) {
+    return `tag:slotlock.pylota.io,2026:problem:${code}`;
+}
+const PROBLEM_TITLES = Object.freeze({
+    overlap: 'The time is taken',
+    idempotency_conflict: 'Idempotency-Key is already used',
+    idempotency_key_required: 'Idempotency-Key is missing',
+    idempotency_key_not_supported: 'Idempotency-Key is not taken here',
+    revision_conflict: 'The revision is stale',
+    confirmation_required: 'A person must confirm this write',
+    rate_limited: 'Too many requests',
+    authentication_required: 'Authentication required',
+    forbidden: 'Not allowed',
+    invalid_arguments: 'The arguments are not valid',
+});
+const STATUS_TITLES = Object.freeze({
+    400: 'Bad Request',
+    401: 'Unauthorized',
+    403: 'Forbidden',
+    404: 'Not Found',
+    405: 'Method Not Allowed',
+    409: 'Conflict',
+    410: 'Gone',
+    413: 'Content Too Large',
+    415: 'Unsupported Media Type',
+    422: 'Unprocessable Content',
+    428: 'Precondition Required',
+    429: 'Too Many Requests',
+    500: 'Internal Server Error',
+    503: 'Service Unavailable',
+});
+/**
+ * A REST refusal as RFC 9457 problem details (`application/problem+json`): `type` and `title` name
+ * the problem, `code` is Slotlock's code, and `error.code` repeats it, the body every earlier
+ * client reads. `extensions` add what the refusal is about, such as the interval an overlap refused.
+ */
+export function slotlockProblem(status, code, extensions = {}) {
+    return {
+        type: slotlockProblemType(code),
+        title: PROBLEM_TITLES[code] ?? STATUS_TITLES[status] ?? 'Error',
+        status,
+        code,
+        ...extensions,
+        error: { code },
+    };
+}
+/**
+ * The Idempotency-Key header's value: a Structured Field String (RFC 9651, as
+ * draft-ietf-httpapi-idempotency-key-header-08 defines it), or the bare token clients sent before.
+ * `null` when it is a quoted string that does not parse.
+ */
+export function parseIdempotencyKeyHeader(value) {
+    const trimmed = value.trim();
+    if (!trimmed.startsWith('"'))
+        return trimmed;
+    let key = '';
+    for (let index = 1; index < trimmed.length; index++) {
+        const char = trimmed[index];
+        if (char === '\\') {
+            const next = trimmed[index + 1];
+            if (next !== '"' && next !== '\\')
+                return null;
+            key += next;
+            index++;
+        }
+        else if (char === '"') {
+            return index === trimmed.length - 1 ? key : null;
+        }
+        else if (char < ' ' || char > '~') {
+            return null;
+        }
+        else {
+            key += char;
+        }
+    }
+    return null;
+}
 /** Where an operation's arguments come from. */
 export function restInputFromBody(route) {
     return route.method === 'POST' || route.method === 'PUT' || route.method === 'PATCH';
@@ -114,6 +230,12 @@ export function restQueryInput(search, inputSchema) {
     return input;
 }
 const ERROR_RESPONSE = { $ref: '#/components/responses/Error' };
+const IDEMPOTENCY_KEY_HEADER = 'Stands in for idempotency_key: a Structured Field String (`"8e03978e-40d5-43e8-bc93-6894a57f9324"`, ' +
+    'draft-ietf-httpapi-idempotency-key-header-08) or the bare key; when both are sent they must be equal. ' +
+    'A retry with the same key and request answers what the first did; the same key with another request is ' +
+    '422 idempotency_conflict. An event write keeps its key for 30 days (maintenance removes it after that), ' +
+    'a hold until the hold would have expired, is released or is confirmed. Where the key is required and ' +
+    'neither is sent: 400 idempotency_key_required.';
 /** The OpenAPI operation object for one route. */
 function openApiOperation(route, operation, extra) {
     const pathNames = [...route.path.matchAll(/\{(\w+)\}/g)].map((match) => match[1]);
@@ -156,14 +278,15 @@ function openApiOperation(route, operation, extra) {
             parameters.push({ name, in: 'query', required: required.has(name), schema });
         }
     }
-    // An application write that keeps a retry identity also takes it as the Idempotency-Key header.
-    if (extra.tag === 'Application' && fields.idempotency_key !== undefined) {
+    // A write that keeps a retry identity also takes it as the Idempotency-Key header.
+    const keyed = fields.idempotency_key !== undefined;
+    if (keyed) {
         parameters.push({
             name: 'Idempotency-Key',
             in: 'header',
             required: false,
-            description: 'Stands in for idempotency_key, where HTTP clients put a retry identity; when both are sent they must be equal.',
-            schema: { type: 'string', minLength: 1, maxLength: 500 },
+            description: IDEMPOTENCY_KEY_HEADER,
+            schema: { type: 'string', minLength: 1, maxLength: 502 },
         });
     }
     if (parameters.length > 0)
@@ -174,6 +297,7 @@ function openApiOperation(route, operation, extra) {
             content: { 'application/json': { schema: operation.outputSchema } },
         },
         ...extra.responses,
+        ...(keyed ? { '422': ERROR_RESPONSE } : {}),
     };
     return result;
 }
@@ -194,6 +318,7 @@ export function slotlockOpenApiDocument(args) {
                 '400': ERROR_RESPONSE,
                 '401': ERROR_RESPONSE,
                 '403': ERROR_RESPONSE,
+                ...Object.fromEntries((route.refusals ?? []).map((status) => [status, ERROR_RESPONSE])),
                 ...(route.method === 'GET' ? {} : { '428': ERROR_RESPONSE }),
                 '429': ERROR_RESPONSE,
                 default: ERROR_RESPONSE,
@@ -213,6 +338,8 @@ export function slotlockOpenApiDocument(args) {
                 '403': ERROR_RESPONSE,
                 '404': ERROR_RESPONSE,
                 ...(route.method === 'GET' ? {} : { '409': ERROR_RESPONSE }),
+                // A change cursor past the feed's retention.
+                ...(route.operation === 'slotlock_list_changes' ? { '410': ERROR_RESPONSE } : {}),
                 '429': ERROR_RESPONSE,
                 default: ERROR_RESPONSE,
             },
@@ -225,8 +352,10 @@ export function slotlockOpenApiDocument(args) {
             version: args.version,
             description: 'Calendars agents cannot double-book. The "Agent tools" operations are the Slotlock MCP tools; ' +
                 'the "Application" operations (resources, bookable hours, holds, reservations, coverage and ' +
-                'maintenance) need an API key with the admin scope. An error is `{"error":{"code":…}}`, and ' +
-                'a write that waits for a person answers 428 `confirmation_required`.',
+                'maintenance) need an API key with the admin scope. An error is RFC 9457 problem details ' +
+                '(`application/problem+json`) whose `code` names it, also as `{"error":{"code":…}}`; an overlap ' +
+                'names the `resource_id`, `start` and `end` it refused. A write that waits for a person answers 428 ' +
+                '`confirmation_required`.',
         },
         servers: [
             args.publicBaseUrl !== undefined
@@ -265,8 +394,16 @@ export function slotlockOpenApiDocument(args) {
             schemas: {
                 Error: {
                     type: 'object',
-                    required: ['error'],
+                    description: 'RFC 9457 problem details.',
+                    required: ['type', 'title', 'status', 'code', 'error'],
                     properties: {
+                        type: { type: 'string', description: 'The problem type: a tag URI, one per code.' },
+                        title: { type: 'string' },
+                        status: { type: 'integer' },
+                        code: { type: 'string', description: 'Why the operation did not run.' },
+                        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.' },
                         error: {
                             type: 'object',
                             required: ['code'],
@@ -278,7 +415,15 @@ export function slotlockOpenApiDocument(args) {
             responses: {
                 Error: {
                     description: 'The operation did not run; `code` says why.',
-                    content: { 'application/json': { schema: { $ref: '#/components/schemas/Error' } } },
+                    headers: {
+                        Link: {
+                            description: 'Where the error codes are documented (`rel="describedby"`).',
+                            schema: { type: 'string' },
+                        },
+                    },
+                    content: {
+                        'application/problem+json': { schema: { $ref: '#/components/schemas/Error' } },
+                    },
                 },
             },
         },

package/self-host.d.ts

@@ -5,7 +5,7 @@ import { type SlotlockSql, type SlotlockStore } from './store.js';
 import type { WeeklyAvailabilityRule } from './types.js';
 export { SlotlockConfigError, type SlotlockEnv, type SlotlockServeDashboardConfig };
 /** Every variable the commands read. The README, `.env.example` and `server.json` document these. */
-export declare const SLOTLOCK_ENVIRONMENT_VARIABLES: readonly ["DATABASE_URL", "SLOTLOCK_MIGRATE_DATABASE_URL", "SLOTLOCK_AUTH_TOKEN", "SLOTLOCK_CONFIRMATION_SECRET", "SLOTLOCK_CONFIRM_WRITES", "SLOTLOCK_PUBLIC_URL", "SLOTLOCK_TENANT", "SLOTLOCK_AVAILABILITY", "SLOTLOCK_REST_API", "SLOTLOCK_LIMITS", "SLOTLOCK_TRUSTED_PROXY_HEADER", "SLOTLOCK_GITHUB_CLIENT_ID", "SLOTLOCK_GITHUB_CLIENT_SECRET", "SLOTLOCK_SESSION_SECRET", "SLOTLOCK_DASHBOARD_USERS", "HOST", "PORT"];
+export declare const SLOTLOCK_ENVIRONMENT_VARIABLES: readonly ["DATABASE_URL", "SLOTLOCK_MIGRATE_DATABASE_URL", "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"];
 export interface SlotlockDatabaseConfig {
     /** The role `serve` and `resource` connect as. */
     databaseUrl: string;
@@ -15,6 +15,11 @@ export interface SlotlockDatabaseConfig {
      */
     migrateDatabaseUrl?: string;
     tenantRef: string;
+    /**
+     * How long history is kept, in days (SLOTLOCK_RETENTION_DAYS); 30 without it. Every command that
+     * prunes or reads the feed takes it, so `maintain` from cron prunes as `serve` reads.
+     */
+    retentionDays?: number;
 }
 export interface SlotlockServeConfig extends SlotlockDatabaseConfig {
     host: string;
@@ -26,6 +31,8 @@ export interface SlotlockServeConfig extends SlotlockDatabaseConfig {
      * (`slotlock key create`) authenticate whether or not it is set, each as its own tenant and scopes.
      */
     authToken?: string;
+    /** The bearer token `/metrics` answers (SLOTLOCK_METRICS_TOKEN); no metrics without it. */
+    metricsToken?: string;
     /**
      * Writes that wait for a person's confirmation (MCP 2026-07-28) and are refused elsewhere. None
      * unless SLOTLOCK_CONFIRM_WRITES opts in: every authenticated write takes effect at once.
@@ -37,11 +44,20 @@ export interface SlotlockServeConfig extends SlotlockDatabaseConfig {
     availability: readonly WeeklyAvailabilityRule[];
     /** Set exactly when SLOTLOCK_GITHUB_CLIENT_ID is. */
     dashboard?: SlotlockServeDashboardConfig;
+    /**
+     * GitHub organization ids (SLOTLOCK_DASHBOARD_ORGS) whose `github-org:<id>` tenants this server's
+     * keys may act for, whether it serves the dashboard or another server (a Worker) does.
+     */
+    organizations?: string[];
     /**
      * Serve the REST API under /v1, with the application API for admin keys, and its OpenAPI document
      * (SLOTLOCK_REST_API: on unless off).
      */
     restApi: boolean;
+    /** Webhook delivery (SLOTLOCK_WEBHOOKS: on unless off; private also reaches private networks). */
+    webhooks: 'on' | 'off' | 'private';
+    /** Tenant request budgets shared with every server through PostgreSQL (SLOTLOCK_SHARED_LIMITS=on). */
+    sharedLimits: boolean;
     /** Request limits (SLOTLOCK_LIMITS over SLOTLOCK_DEFAULT_LIMITS): the server's only rate limit. */
     limits: SlotlockLimits;
     /** The lower-case request field a trusted proxy sets to the client address; else the socket's. */
@@ -98,10 +114,17 @@ export interface SlotlockRunningServer {
  * 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 declare function createSlotlockServeStore(sql: SlotlockSql, caps: SlotlockLimits['caps']): SlotlockStore;
+export declare function createSlotlockServeStore(sql: SlotlockSql, caps: SlotlockLimits['caps'], availability?: readonly WeeklyAvailabilityRule[], retentionDays?: number): SlotlockStore;
+/**
+ * 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 declare function createSlotlockMaintenanceStore(sql: SlotlockSql, caps: SlotlockLimits['caps'], options?: {
+    retentionDays?: number;
+}): SlotlockStore;
 /** Serve MCP and A2A over HTTP from the Postgres store, as one token-authenticated tenant. */
 export declare function startSlotlockServer(config: SlotlockServeConfig, log: SlotlockLogger): Promise<SlotlockRunningServer>;
-export declare const SLOTLOCK_CLI_HELP = "Usage: slotlock <command> [options]\n\nCommands:\n  migrate                  Apply the schema and row-level security, then grant the serving\n                           role when SLOTLOCK_MIGRATE_DATABASE_URL names another role\n  serve [--migrate]        Serve MCP, A2A and REST over HTTP (--migrate runs migrate first);\n                           maintains each tenant it serves every hour\n  maintain                 Run maintenance for the tenant now: extend recurring events to the\n                           rolling horizon and prune past the retention window (for cron)\n  resource add <ref> [--timezone <IANA zone>]\n                           Create a calendar resource (a car, room, person or machine)\n  resource list            Print the tenant's resources, one JSON object per line\n  resource archive <ref>   Take a resource out of use: no new bookings, holds or events, and\n                           no longer listed; what is on it stays\n  resource restore <ref>   Put an archived resource back in use\n  resource delete <ref>    Delete a resource and its history; refused while a booking, hold\n                           or event on it has not ended\n  hours show [--resource <ref>]\n                           Print each resource's bookable hours (null: the server's)\n  hours set <json> (--resource <ref> | --all)\n                           Give one resource, or every one, weekly hours of its own; [] closes\n  hours clear (--resource <ref> | --all)\n                           Hand one resource, or every one, back to the server's hours\n  key create <name> [--scope read,write,admin] [--expires-in-days <n>]\n                           Create an API key for the tenant (default scope read,write, no\n                           expiry; admin adds the application API) and print it once; only its\n                           SHA-256 is stored\n  key list                 Print the tenant's API keys, one JSON object per line\n  key rotate <id>          Give an active key a new secret and print it once; the old one stops\n                           working at once, and the key keeps its id and what it booked\n  key revoke <id>          Revoke one of the tenant's API keys at once\n  tenant status            Print whether the tenant is suspended\n  tenant suspend [--reason <text>]\n                           Suspend the tenant: it may read, and writes nothing; its keys get\n                           no new secret (as SLOTLOCK_MIGRATE_DATABASE_URL's role when set:\n                           only the schema owner suspends)\n  tenant unsuspend         Lift the tenant's suspension (as the schema owner, likewise)\n  tenant erase --confirm <tenant>\n                           Delete everything the tenant has, its API keys included, for good;\n                           --confirm repeats SLOTLOCK_TENANT\n  healthcheck              Exit 0 when the local server reports ready\n\nOptions:\n  -h, --help               Show this help\n  -v, --version            Print the version\n\nEnvironment:\n  DATABASE_URL                   postgres:// URL of the role Slotlock serves as (required); serve\n                                 refuses a superuser or a role with BYPASSRLS\n  SLOTLOCK_MIGRATE_DATABASE_URL  postgres:// URL of the schema owner, for migrate (optional)\n  SLOTLOCK_AUTH_TOKEN            Optional bearer token for SLOTLOCK_TENANT with read and write\n                                 access (never admin), 32+ random characters (serve); API keys\n                                 work with or without it\n  SLOTLOCK_CONFIRMATION_SECRET   Signs pending write confirmations, 32+ random characters (serve;\n                                 required when SLOTLOCK_CONFIRM_WRITES is not none)\n  SLOTLOCK_CONFIRM_WRITES        none (default), all, or a comma-separated list of write tools\n                                 that wait for a person (MCP 2026-07-28 form elicitation; refused\n                                 with confirmation_required on REST, A2A and older MCP)\n  SLOTLOCK_PUBLIC_URL            URL clients use (default http://localhost:$PORT)\n  SLOTLOCK_TENANT                Tenant of the token, resource and key commands (default \"default\")\n  SLOTLOCK_AVAILABILITY          JSON array of weekly bookable-hours rules (default: none)\n  SLOTLOCK_REST_API              on (default): also serve the tools as a REST API under /v1, and\n                                 the application API for admin keys, described at /openapi.json;\n                                 off: MCP and A2A only\n  SLOTLOCK_LIMITS                Request limits, comma-separated name=value over the defaults:\n                                 rates as <count>/<s|m|h>[:<burst>] or off for address (50/s:100,\n                                 every request per client, before any key lookup), key_read,\n                                 tenant_read (20/s:40), key_write, tenant_write (5/s:20),\n                                 global_read (500/s:1000), global_write (50/s:100), app_read\n                                 (20/s:40) and app_write (5/s:20) per tenant for the\n                                 application API, sign_in (20/m:20); counts for\n                                 tenant_series_writes and series_writes\n                                 (1: writes that may expand a recurring series at once),\n                                 maintenance_runs (1: application API maintenance runs at once),\n                                 subscriptions (256), tenant_subscriptions (16),\n                                 key_subscriptions (4, and fewer than tenant_subscriptions),\n                                 key_lookups (2), key_lookup_queue (256),\n                                 tenant_transactions (2: one tenant's database transactions at\n                                 once, of the pool's 10); what one tenant may store:\n                                 tenant_holds (10000), tenant_reservations, tenant_events and\n                                 tenant_coverage (100000)\n  SLOTLOCK_TRUSTED_PROXY_HEADER  The request field a proxy in front sets to the client address,\n                                 such as CF-Connecting-IP (default: the connection's address);\n                                 set it only when every request comes through that proxy\n  SLOTLOCK_GITHUB_CLIENT_ID      Serve the dashboard at $SLOTLOCK_PUBLIC_URL/dashboard: the Client ID\n                                 of a GitHub OAuth app with callback .../dashboard/callback\n  SLOTLOCK_GITHUB_CLIENT_SECRET  That app's client secret (dashboard)\n  SLOTLOCK_SESSION_SECRET        Signs dashboard sessions, 32+ random characters (dashboard)\n  SLOTLOCK_DASHBOARD_USERS       * or comma-separated GitHub user ids that may sign in (dashboard)\n  HOST                           Listen address (default 127.0.0.1)\n  PORT                           Listen port (default 8080)\n\nGenerate each secret with: openssl rand -hex 32\n";
+export declare const SLOTLOCK_CLI_HELP = "Usage: slotlock <command> [options]\n\nCommands:\n  migrate                  Apply the schema and row-level security, then grant the serving\n                           role when SLOTLOCK_MIGRATE_DATABASE_URL names another role\n  serve [--migrate]        Serve MCP, A2A and REST over HTTP (--migrate runs migrate first);\n                           maintains each tenant it serves every hour\n  maintain                 Run maintenance for the tenant now: extend recurring events to the\n                           rolling horizon and prune past the retention window (for cron)\n  resource add <ref> [--timezone <IANA zone>]\n                           Create a calendar resource (a car, room, person or machine)\n  resource list            Print the tenant's resources, one JSON object per line\n  resource archive <ref>   Take a resource out of use: no new bookings, holds or events, and\n                           no longer listed; what is on it stays\n  resource restore <ref>   Put an archived resource back in use\n  resource delete <ref>    Delete a resource and its history; refused while a booking, hold\n                           or event on it has not ended\n  hours show [--resource <ref>]\n                           Print each resource's bookable hours (null: the server's)\n  hours set <json> (--resource <ref> | --all)\n                           Give one resource, or every one, weekly hours of its own; [] closes\n  hours clear (--resource <ref> | --all)\n                           Hand one resource, or every one, back to the server's hours\n  rules set <json> --resource <ref>\n                           Set what a booking on the resource must satisfy, like\n                           {\"minNoticeMinutes\":120,\"slotStepMinutes\":30,\"turnaroundMinutes\":30,\"enforceHours\":true}\n  rules clear --resource <ref>\n                           Remove the resource's booking rules\n  key create <name> [--scope read,write,admin] [--expires-in-days <n>]\n                           Create an API key for the tenant (default scope read,write, no\n                           expiry; admin adds the application API) and print it once; only its\n                           SHA-256 is stored\n  key list                 Print the tenant's API keys, one JSON object per line\n  key rotate <id>          Give an active key a new secret and print it once; the old one stops\n                           working at once, and the key keeps its id and what it booked\n  key revoke <id>          Revoke one of the tenant's API keys at once\n  tenant status            Print whether the tenant is suspended\n  tenant suspend [--reason <text>]\n                           Suspend the tenant: it may read, and writes nothing; its keys get\n                           no new secret (as SLOTLOCK_MIGRATE_DATABASE_URL's role when set:\n                           only the schema owner suspends)\n  tenant unsuspend         Lift the tenant's suspension (as the schema owner, likewise)\n  tenant erase --confirm <tenant>\n                           Delete everything the tenant has, its API keys included, for good;\n                           --confirm repeats SLOTLOCK_TENANT\n  healthcheck              Exit 0 when the local server reports ready\n\nOptions:\n  -h, --help               Show this help\n  -v, --version            Print the version\n\nEnvironment:\n  DATABASE_URL                   postgres:// URL of the role Slotlock serves as (required); serve\n                                 refuses a superuser or a role with BYPASSRLS\n  SLOTLOCK_MIGRATE_DATABASE_URL  postgres:// URL of the schema owner, for migrate (optional)\n  SLOTLOCK_AUTH_TOKEN            Optional bearer token for SLOTLOCK_TENANT with read and write\n                                 access (never admin), 32+ random characters (serve); API keys\n                                 work with or without it\n  SLOTLOCK_CONFIRMATION_SECRET   Signs pending write confirmations, 32+ random characters (serve;\n                                 required when SLOTLOCK_CONFIRM_WRITES is not none)\n  SLOTLOCK_METRICS_TOKEN         Serves Prometheus metrics at /metrics to this bearer token, 32+\n                                 random characters (serve; off without it)\n  SLOTLOCK_CONFIRM_WRITES        none (default), all, or a comma-separated list of write tools\n                                 that wait for a person (MCP 2026-07-28 form elicitation; refused\n                                 with confirmation_required on REST, A2A and older MCP)\n  SLOTLOCK_PUBLIC_URL            URL clients use (default http://localhost:$PORT)\n  SLOTLOCK_TENANT                Tenant of the token, resource and key commands (default \"default\")\n  SLOTLOCK_AVAILABILITY          JSON array of weekly bookable-hours rules (default: none)\n  SLOTLOCK_REST_API              on (default): also serve the tools as a REST API under /v1, and\n                                 the application API for admin keys, described at /openapi.json;\n                                 off: MCP and A2A only\n  SLOTLOCK_RETENTION_DAYS        Days of history kept: the change feed, ended waitlist entries,\n                                 and retired answers (never under 30) (1-3650, default 30;\n                                 serve and maintain)\n  SLOTLOCK_SHARED_LIMITS         on: tenant request budgets are shared by every server through the\n                                 database, so N servers allow a tenant its rate once; off (default):\n                                 each server keeps its own\n  SLOTLOCK_WEBHOOKS              on (default): deliver each tenant's changes to its webhooks,\n                                 never to a private network address; private: those too, for\n                                 testing; off: keep the change feed, send nothing\n  SLOTLOCK_LIMITS                Request limits, comma-separated name=value over the defaults:\n                                 rates as <count>/<s|m|h>[:<burst>] or off for address (50/s:100,\n                                 every request per client, before any key lookup), key_read,\n                                 tenant_read (20/s:40), key_write, tenant_write (5/s:20),\n                                 global_read (500/s:1000), global_write (50/s:100), app_read\n                                 (20/s:40) and app_write (5/s:20) per tenant for the\n                                 application API, sign_in (20/m:20); counts for\n                                 tenant_series_writes and series_writes\n                                 (1: writes that may expand a recurring series at once),\n                                 maintenance_runs (1: application API maintenance runs at once),\n                                 subscriptions (256), tenant_subscriptions (16),\n                                 key_subscriptions (4, and fewer than tenant_subscriptions),\n                                 key_lookups (2), key_lookup_queue (256),\n                                 tenant_transactions (2: one tenant's database transactions at\n                                 once, of the pool's 10); what one tenant may store:\n                                 tenant_holds (10000), tenant_reservations, tenant_events and\n                                 tenant_coverage (100000), holder_holds (20) and\n                                 holder_held_hours (2160), which maintain keeps too\n  SLOTLOCK_TRUSTED_PROXY_HEADER  The request field a proxy in front sets to the client address,\n                                 such as CF-Connecting-IP (default: the connection's address);\n                                 set it only when every request comes through that proxy\n  SLOTLOCK_GITHUB_CLIENT_ID      Serve the dashboard at $SLOTLOCK_PUBLIC_URL/dashboard: the Client ID\n                                 of a GitHub OAuth app with callback .../dashboard/callback\n  SLOTLOCK_GITHUB_CLIENT_SECRET  That app's client secret (dashboard)\n  SLOTLOCK_SESSION_SECRET        Signs dashboard sessions, 32+ random characters (dashboard)\n  SLOTLOCK_DASHBOARD_USERS       * or comma-separated GitHub user ids that may sign in (dashboard)\n  SLOTLOCK_DASHBOARD_ORGS        comma-separated GitHub organization ids: each is one shared tenant\n  SLOTLOCK_DASHBOARD_NAME        What the dashboard calls this deployment (default Slotlock)\n  HOST                           Listen address (default 127.0.0.1)\n  PORT                           Listen port (default 8080)\n\nGenerate each secret with: openssl rand -hex 32\n";
 /**
  * Run one `slotlock` command and resolve to its exit code: 0 success, 1 failure, 2 a usage or
  * configuration error (nothing was started). `serve` resolves once `io.signal` aborts and it has