slotlock 0.6.2 → 0.7.0

package/sandbox.js

@@ -0,0 +1,295 @@
+// The sandbox (RFC 0004 A6): a test environment (a tenant ending ~test) filled with a scenario an
+// agent can be tried against, emptied again, moved forward so what would lapse lapses, and raced.
+// None of it touches a live tenant: each refuses one (`sandbox_test_only`), and the database's
+// reset does too.
+import { randomUUID } from 'node:crypto';
+import { invokeSlotlockAgentOperation, } from './agent-server.js';
+import { SLOTLOCK_TEST_TENANT_SUFFIX } from './api-keys.js';
+import { maintainSlotlockTenant } from './maintenance.js';
+export const SLOTLOCK_SANDBOX_SCENARIOS = Object.freeze(['car-rental', 'clinic', 'desks']);
+/** Agents one race runs at most, so a race stays a test of the server and not a load on it. */
+export const SLOTLOCK_SANDBOX_MAX_RACERS = 200;
+/** Refused outside a test environment. */
+export class SlotlockSandboxError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+function assertTestTenant(tenantRef) {
+    if (!tenantRef.endsWith(SLOTLOCK_TEST_TENANT_SUFFIX)) {
+        throw new SlotlockSandboxError('sandbox_test_only', `Slotlock's sandbox works only in a test environment (a tenant ending ${SLOTLOCK_TEST_TENANT_SUFFIX})`);
+    }
+}
+const EVERY_DAY = 'FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR,SA,SU';
+const WEEKDAYS = 'FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR';
+const hours = (rrule, from, to) => [
+    { rrule, startMinutes: from * 60, durationMinutes: (to - from) * 60 },
+];
+const SCENARIOS = {
+    // A rental desk at two branches: cars and vans in pools, booked by the day or the hour, with
+    // time to clean each between hires.
+    'car-rental': {
+        timezone: 'Europe/London',
+        locations: [
+            { ref: 'airport', name: 'Airport branch' },
+            { ref: 'city', name: 'City branch' },
+        ],
+        groups: [{ ref: 'electric', name: 'Electric' }],
+        resources: [
+            { ref: 'car-1', name: 'Compact 1', kind: 'vehicle', capacity: 5, location: 'airport', pool: 'compact', labels: ['automatic'] },
+            { ref: 'car-2', name: 'Compact 2', kind: 'vehicle', capacity: 5, location: 'airport', pool: 'compact' },
+            { ref: 'car-3', name: 'Compact 3 (EV)', kind: 'vehicle', capacity: 5, location: 'city', pool: 'compact', groups: ['electric'] },
+            { ref: 'van-1', name: 'Van 1', kind: 'vehicle', capacity: 3, location: 'city', pool: 'van' },
+            { ref: 'van-2', name: 'Van 2 (EV)', kind: 'vehicle', capacity: 3, location: 'airport', pool: 'van', groups: ['electric'] },
+        ],
+        hours: hours(EVERY_DAY, 7, 21),
+        rules: { minNoticeMinutes: 60, turnaroundMinutes: 30, slotStepMinutes: 30 },
+        bookings: [
+            { resource: 'car-1', hour: 9, length: 4 },
+            { resource: 'car-2', hour: 10, length: 2 },
+            { resource: 'van-1', hour: 8, length: 9 },
+        ],
+    },
+    // A physiotherapy clinic: practitioners and treatment rooms on weekdays, half-hour slots.
+    clinic: {
+        timezone: 'America/New_York',
+        locations: [{ ref: 'main-street', name: 'Main Street clinic' }],
+        groups: [{ ref: 'physio', name: 'Physiotherapists' }],
+        resources: [
+            { ref: 'dr-adams', name: 'Dr Adams', kind: 'person', location: 'main-street', groups: ['physio'] },
+            { ref: 'dr-baker', name: 'Dr Baker', kind: 'person', location: 'main-street', groups: ['physio'] },
+            { ref: 'room-1', name: 'Treatment room 1', kind: 'room', capacity: 2, location: 'main-street', pool: 'treatment-room' },
+            { ref: 'room-2', name: 'Treatment room 2', kind: 'room', capacity: 2, location: 'main-street', pool: 'treatment-room' },
+        ],
+        hours: hours(WEEKDAYS, 9, 17),
+        rules: { slotStepMinutes: 30, minNoticeMinutes: 120 },
+        bookings: [
+            { resource: 'dr-adams', hour: 9, length: 1 },
+            { resource: 'dr-baker', hour: 11, length: 1 },
+            { resource: 'room-1', hour: 9, length: 1 },
+        ],
+    },
+    // An office: desks on two floors, booked by the day, and a hall that splits into two rooms.
+    desks: {
+        timezone: 'Europe/Berlin',
+        locations: [
+            { ref: 'hq', name: 'Headquarters' },
+            { ref: 'floor-1', name: 'Floor 1', parent: 'hq' },
+            { ref: 'floor-2', name: 'Floor 2', parent: 'hq' },
+        ],
+        groups: [{ ref: 'standing', name: 'Standing desks' }],
+        resources: [
+            ...Array.from({ length: 6 }, (_, index) => ({
+                ref: `desk-${index + 1}`,
+                name: `Desk ${index + 1}`,
+                kind: 'desk',
+                location: index < 3 ? 'floor-1' : 'floor-2',
+                pool: 'desk',
+                ...(index % 3 === 0 ? { groups: ['standing'] } : {}),
+            })),
+            { ref: 'hall', name: 'Event hall', kind: 'room', capacity: 80, location: 'floor-1' },
+            { ref: 'hall-east', name: 'Event hall, east', kind: 'room', capacity: 40, location: 'floor-1', parent: 'hall' },
+            { ref: 'hall-west', name: 'Event hall, west', kind: 'room', capacity: 40, location: 'floor-1', parent: 'hall' },
+        ],
+        hours: hours(WEEKDAYS, 8, 18),
+        bookings: [
+            { resource: 'desk-1', hour: 8, length: 10 },
+            { resource: 'desk-4', hour: 8, length: 10 },
+            { resource: 'hall-east', hour: 14, length: 2 },
+        ],
+    },
+};
+/** The time `hour` o'clock local time falls on tomorrow, in `timezone`, as UTC. */
+function tomorrowAt(now, timezone, hour) {
+    const parts = Object.fromEntries(new Intl.DateTimeFormat('en-US', { timeZone: timezone, year: 'numeric', month: '2-digit', day: '2-digit' })
+        .formatToParts(new Date(now.getTime() + 86_400_000))
+        .filter(({ type }) => type !== 'literal')
+        .map(({ type, value }) => [type, Number(value)]));
+    // The zone's offset at that wall time, found by asking what the guess reads as there.
+    const guess = Date.UTC(parts.year, parts.month - 1, parts.day, hour);
+    const local = Object.fromEntries(new Intl.DateTimeFormat('en-US', {
+        timeZone: timezone,
+        hourCycle: 'h23',
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+    })
+        .formatToParts(new Date(guess))
+        .filter(({ type }) => type !== 'literal')
+        .map(({ type, value }) => [type, Number(value)]));
+    const shown = Date.UTC(local.year, local.month - 1, local.day, local.hour, local.minute);
+    return new Date(guess - (shown - guess));
+}
+/**
+ * Fill an empty test environment with a scenario, in one transaction: its locations, groups,
+ * resources (with profiles, pools and a composite where it has one), their hours and booking
+ * rules, and a few bookings tomorrow. Refused (`sandbox_not_empty`) where it has resources already:
+ * reset it first.
+ */
+export async function seedSlotlockSandbox(store, tenantRef, scenario, options = {}) {
+    assertTestTenant(tenantRef);
+    const plan = SCENARIOS[scenario];
+    if (!plan)
+        throw new RangeError(`Slotlock knows the scenarios ${SLOTLOCK_SANDBOX_SCENARIOS.join(', ')}`);
+    const now = options.now ?? new Date();
+    return store.withTenant(tenantRef, async (tenant) => {
+        if ((await tenant.countResources({ tenantRef })) > 0) {
+            throw new SlotlockSandboxError('sandbox_not_empty', 'Slotlock seeds an empty test environment: reset it first');
+        }
+        for (const location of plan.locations) {
+            await tenant.putLocation({
+                tenantRef,
+                ref: location.ref,
+                name: location.name,
+                ...(location.parent ? { parentRef: location.parent } : { timezone: plan.timezone }),
+            });
+        }
+        for (const group of plan.groups)
+            await tenant.putGroup({ tenantRef, ref: group.ref, name: group.name });
+        const ids = new Map();
+        for (const resource of plan.resources) {
+            const created = await tenant.createResource({
+                tenantRef,
+                externalRef: resource.ref,
+                timezone: plan.timezone,
+                profile: {
+                    name: resource.name,
+                    kind: resource.kind,
+                    ...(resource.capacity !== undefined ? { capacity: resource.capacity } : {}),
+                    ...(resource.labels ? { labels: resource.labels } : {}),
+                },
+                ...(resource.location ? { location: resource.location } : {}),
+            });
+            ids.set(resource.ref, created.id);
+            await tenant.setResourceAvailability({ tenantRef, id: created.id, rules: plan.hours });
+            if (plan.rules)
+                await tenant.setResourceBookingRules({ tenantRef, id: created.id, rules: plan.rules });
+            if (resource.pool)
+                await tenant.setResourcePool({ tenantRef, id: created.id, pool: resource.pool });
+            for (const group of resource.groups ?? []) {
+                await tenant.addGroupMember({ tenantRef, group, resourceId: created.id });
+            }
+        }
+        for (const resource of plan.resources) {
+            if (resource.parent) {
+                await tenant.setResourceParent({
+                    tenantRef,
+                    id: ids.get(resource.ref),
+                    parentId: ids.get(resource.parent),
+                });
+            }
+        }
+        let bookings = 0;
+        for (const [index, booking] of plan.bookings.entries()) {
+            const start = tomorrowAt(now, plan.timezone, booking.hour);
+            const made = await tenant.createExternalReservation({
+                tenantRef,
+                externalRef: `sandbox-${scenario}-${index + 1}`,
+                resourceId: ids.get(booking.resource),
+                start,
+                end: new Date(start.getTime() + booking.length * 3_600_000),
+                bufferAfterMs: 0,
+                revision: 1,
+                source: 'sandbox',
+            });
+            if (made.ok)
+                bookings += 1;
+        }
+        return {
+            scenario,
+            resources: plan.resources.length,
+            locations: plan.locations.length,
+            groups: plan.groups.length,
+            pools: new Set(plan.resources.flatMap((resource) => (resource.pool ? [resource.pool] : []))).size,
+            bookings,
+        };
+    }, { origin: 'maintenance', actor: 'slotlock:sandbox', isolation: 'read committed' });
+}
+/** Empty a test environment: what seeding made, and every booking since. Keys, webhooks and plan stay. */
+export async function resetSlotlockSandbox(store, tenantRef) {
+    assertTestTenant(tenantRef);
+    return store.withTenant(tenantRef, (tenant) => tenant.resetTestTenant({ tenantRef }), {
+        origin: 'maintenance',
+        actor: 'slotlock:sandbox',
+    });
+}
+/**
+ * Move a test environment's waiting forward: what would lapse within `minutes` lapses now, then a
+ * maintenance pass reaps it as it would have (holds released, waitlist offers passed on, approvals
+ * expired). Bookings and events keep their times; no-shows and series rolls follow the real clock.
+ */
+export async function fastForwardSlotlockSandbox(store, tenantRef, minutes) {
+    assertTestTenant(tenantRef);
+    const lapsed = await store.withTenant(tenantRef, (tenant) => tenant.fastForwardTestTenant({ tenantRef, minutes }), {
+        origin: 'maintenance',
+        actor: 'slotlock:sandbox',
+    });
+    const maintenance = await maintainSlotlockTenant(store, tenantRef);
+    return { minutes, ...lapsed, maintenance };
+}
+/**
+ * Race `agents` agents (2-200), each its own principal, for one time on one resource of a test
+ * environment, through the same operation boundary MCP, A2A and REST use: who booked, who was
+ * refused and why, and how long each answer took.
+ */
+export async function raceSlotlockSandbox(params) {
+    assertTestTenant(params.tenantRef);
+    const agents = params.agents ?? 100;
+    if (!Number.isSafeInteger(agents) || agents < 2 || agents > SLOTLOCK_SANDBOX_MAX_RACERS) {
+        throw new RangeError(`A sandbox race runs 2 to ${SLOTLOCK_SANDBOX_MAX_RACERS} agents`);
+    }
+    const race = randomUUID().slice(0, 8);
+    const answers = await Promise.all(Array.from({ length: agents }, async (_, index) => {
+        const started = performance.now();
+        const answer = await invokeSlotlockAgentOperation({
+            operation: 'slotlock_create_event',
+            input: {
+                resource_id: params.resourceId,
+                starts_at: params.start.toISOString(),
+                ends_at: params.end.toISOString(),
+                timezone: 'UTC',
+                title: `Sandbox racer ${index + 1}`,
+                idempotency_key: `sandbox-race-${race}-${index}`,
+            },
+            request: new Request('https://sandbox.slotlock.invalid/race'),
+            options: {
+                backend: params.backend,
+                authenticate: async () => ({
+                    subject: `sandbox-racer-${race}-${index + 1}`,
+                    tenantRef: params.tenantRef,
+                    scopes: ['read', 'write'],
+                }),
+                authorize: async () => true,
+            },
+        });
+        return { answer, ms: performance.now() - started };
+    }));
+    const refused = {};
+    let withAlternatives = 0;
+    let serverErrors = 0;
+    for (const { answer } of answers) {
+        if (answer.ok)
+            continue;
+        if (answer.status >= 500)
+            serverErrors += 1;
+        refused[answer.code] = (refused[answer.code] ?? 0) + 1;
+        if (answer.alternatives?.length)
+            withAlternatives += 1;
+    }
+    const times = answers.map(({ ms }) => ms).sort((a, b) => a - b);
+    const at = (share) => Math.round(times[Math.min(times.length - 1, Math.ceil(times.length * share) - 1)]);
+    return {
+        agents,
+        booked: answers.filter(({ answer }) => answer.ok).length,
+        refused,
+        withAlternatives,
+        serverErrors,
+        p50Ms: at(0.5),
+        p99Ms: at(0.99),
+        maxMs: Math.round(times.at(-1)),
+    };
+}

package/self-host.d.ts

@@ -1,11 +1,16 @@
 import { type SlotlockAgentOperation, type SlotlockAgentPrincipal, type SlotlockAgentWriteOperation } from './agent-server.js';
 import { SlotlockConfigError, type SlotlockEnv, type SlotlockLimits, type SlotlockServeDashboardConfig } from './config.js';
+import { type SlotlockOtlpConfig } from './otel.js';
 import { type SlotlockNodeServerAddress, type SlotlockNodeServerCloseResult } from './node-server.js';
 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_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_ASSISTANT_SECRET", "SLOTLOCK_ASSISTANT_PRIVATE_URLS", "SLOTLOCK_DASHBOARD_USERS", "SLOTLOCK_DASHBOARD_ORGS", "SLOTLOCK_DASHBOARD_NAME", "HOST", "PORT"];
+/**
+ * Every variable the commands read. `slotlock --help`, `.env.example`, `server.json` and the docs
+ * (site/docs-src/self-host.md) document these. Not STRIPE_SECRET_KEY, which only the owner's
+ * `partner close` reads, to bill partners.
+ */
+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_USAGE", "SLOTLOCK_QUOTAS", "SLOTLOCK_OVERAGE", "SLOTLOCK_LIMITS", "SLOTLOCK_TRUSTED_PROXY_HEADER", "SLOTLOCK_TRUSTED_PROXY_SECRET", "SLOTLOCK_KNOWN_CLIENTS", "OTEL_EXPORTER_OTLP_ENDPOINT", "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT", "OTEL_EXPORTER_OTLP_METRICS_ENDPOINT", "OTEL_EXPORTER_OTLP_HEADERS", "OTEL_SERVICE_NAME", "SLOTLOCK_GITHUB_CLIENT_ID", "SLOTLOCK_GITHUB_CLIENT_SECRET", "SLOTLOCK_GOOGLE_CLIENT_ID", "SLOTLOCK_GOOGLE_CLIENT_SECRET", "SLOTLOCK_SESSION_SECRET", "SLOTLOCK_ASSISTANT_SECRET", "SLOTLOCK_ASSISTANT_PREVIOUS_SECRETS", "SLOTLOCK_ASSISTANT_PRIVATE_URLS", "SLOTLOCK_DASHBOARD_USERS", "SLOTLOCK_DASHBOARD_ORGS", "SLOTLOCK_DASHBOARD_NAME", "SLOTLOCK_DASHBOARD_TERMS_URL", "SLOTLOCK_DASHBOARD_PRIVACY_URL", "HOST", "PORT"];
 export interface SlotlockDatabaseConfig {
     /** The role `serve` and `resource` connect as. */
     databaseUrl: string;
@@ -46,9 +51,15 @@ export interface SlotlockServeConfig extends SlotlockDatabaseConfig {
     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; or
+     * `'enabled'`, those an owner turned on from the dashboard (teams.ts), checked in the database.
+     */
+    organizations?: string[] | 'enabled';
+    /**
+     * GitHub user ids (SLOTLOCK_DASHBOARD_USERS), or `'*'`, whose `github:<id>` tenants this server's
      * keys may act for, whether it serves the dashboard or another server (a Worker) does.
      */
-    organizations?: string[];
+    allowedUsers?: '*' | string[];
     /**
      * Serve the REST API under /v1, with the application API for admin keys, and its OpenAPI document
      * (SLOTLOCK_REST_API: on unless off).
@@ -58,10 +69,34 @@ export interface SlotlockServeConfig extends SlotlockDatabaseConfig {
     webhooks: 'on' | 'off' | 'private';
     /** Tenant request budgets shared with every server through PostgreSQL (SLOTLOCK_SHARED_LIMITS=on). */
     sharedLimits: boolean;
+    /**
+     * Usage metering (SLOTLOCK_USAGE=on; off by default): each tenant's operations, bookings and
+     * holds counted by day, key and surface in slotlock.usage_daily (usage.ts).
+     */
+    usage: boolean;
+    /**
+     * Monthly quotas (SLOTLOCK_QUOTAS=on, which needs SLOTLOCK_USAGE=on; off by default): a tenant on
+     * a plan is refused `quota_exceeded` past its plan's operations or bookings this month (quotas.ts).
+     */
+    quotas: boolean;
+    /**
+     * Metered overage (SLOTLOCK_OVERAGE: off, or the percent of its quota a paying Developer tenant
+     * is refused at, 111-1000; needs SLOTLOCK_QUOTAS=on). Off by default: overage.ts.
+     */
+    overageStopPercent?: number;
     /** 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. */
     trustedProxyHeader?: string;
+    /**
+     * Integrators metrics count by name from the `Slotlock-Client` field (SLOTLOCK_KNOWN_CLIENTS,
+     * RFC 0003 P5); any other is `other`. Empty: every named client is `other`.
+     */
+    knownClients?: readonly string[];
+    /** OpenTelemetry trace export (OTEL_EXPORTER_OTLP_ENDPOINT and the other OTEL_* variables). */
+    otlp?: SlotlockOtlpConfig;
+    /** The value that must accompany trustedProxyHeader in x-slotlock-proxy-proof; else the socket's. */
+    trustedProxySecret?: string;
 }
 export declare function readSlotlockDatabaseConfig(env: SlotlockEnv): SlotlockDatabaseConfig;
 export declare function readSlotlockServeConfig(env: SlotlockEnv): SlotlockServeConfig;
@@ -110,6 +145,13 @@ export interface SlotlockRunningServer {
     /** End open subscriptions, drain in-flight requests, then close the database pool. */
     close(): Promise<SlotlockNodeServerCloseResult>;
 }
+/**
+ * Whether the dashboard's allowlists let a tenant act, wherever the dashboard runs: a
+ * `github-org:<id>` tenant only while SLOTLOCK_DASHBOARD_ORGS lists that organization; a
+ * `github:<id>` tenant only while SLOTLOCK_DASHBOARD_USERS is `*` or lists that id; every tenant when
+ * SLOTLOCK_DASHBOARD_USERS is not set, and every other tenant.
+ */
+export declare function slotlockServeAllowsTenant(config: Pick<SlotlockServeConfig, 'organizations' | 'allowedUsers'>, tenantRef: string): boolean;
 /**
  * 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.
@@ -124,7 +166,7 @@ export declare function createSlotlockMaintenanceStore(sql: SlotlockSql, caps: S
 }): 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  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_ASSISTANT_SECRET      Turns on the dashboard assistant and seals each organization's\n                                 model API key with it, 32+ random characters (dashboard; off\n                                 without it)\n  SLOTLOCK_ASSISTANT_PRIVATE_URLS off (default): refuse an assistant model URL whose host is, or\n                                 resolves to, a loopback, private, link-local, CGNAT, unique-local\n                                 or metadata address; on: allow them, for a self-hosted model\n                                 (Ollama, vLLM) on this machine or network\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";
+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 every tenant with data 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 parent <ref> (<parent-ref> | none)\n                           Make a resource a part of a composite (a room of a hall): booking\n                           the whole then takes every part, and a part's booking keeps the\n                           whole from being booked; none makes it no part\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             [--locations <ref,...>] [--groups <ref,...>]\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. With --locations or --groups, the key reaches\n                           only the resources there (each location with those in it), read and\n                           write only\n             [--max-holds <n>] [--max-held-hours <n>] [--requests-per-minute <n>]\n             [--requires-approval]\n                           ... and hold the key below the server's limits: its live holds, the\n                           hours they hold, its requests a minute, and every booking it makes\n                           waiting for a person (the dashboard's Approvals)\n  key limits <id> [--max-holds <n>] [--max-held-hours <n>] [--requests-per-minute <n>]\n             [--requires-approval]\n                           Replace an active key's limits; none at all gives it the server's\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  sandbox seed <car-rental|clinic|desks>\n                           Fill an empty test environment (SLOTLOCK_TENANT=<tenant>~test) with a\n                           scenario: locations, groups, resources, hours, rules and bookings\n  sandbox reset            Empty the test environment; its keys, webhooks and plan stay\n  sandbox fast-forward <minutes>\n                           Make what would lapse in the test environment within that time lapse\n                           now (holds, offers, approvals), then run maintenance\n  sandbox race <resource-ref> [--agents <n>] [--start <date-time>]\n                           Race agents (default 100) for one hour on a test resource and print who\n                           booked, who was refused and why, and how long the answers took\n  partner create <id> <name> --contract <json | @file>\n                           Create a partner reselling Slotlock, or change its name and contract:\n                           its plans (limits and quotas), its accounts' key scopes and its prices\n                           (as the schema owner, SLOTLOCK_MIGRATE_DATABASE_URL)\n  partner list             Print the partners, one JSON object per line\n  partner suspend <id>     Suspend a partner: every account with it, and its keys stop\n  partner unsuspend <id>   Make a suspended partner active again\n  partner key <id> <name>  Create a partner key (slk_partner_\u2026) and print it once\n  partner revoke-key <id> <key-id>\n                           Revoke one of a partner's keys at once\n  partner customer <id> <cus_\u2026>\n                           The Stripe customer its monthly invoice goes to\n  partner webhook <id> <https-url>\n                           Where usage.period_closed goes; prints its signing secret once\n  billing daily            Once a day (cron), as the schema owner: close last month for every\n                           active partner once it has been over for 6 hours, report overage\n                           when SLOTLOCK_OVERAGE is on (with STRIPE_SECRET_KEY), and list the\n                           partners' reconciliation mismatches of the last 7 days; exits 1 when\n                           anything waits or differs. Safe to run again\n  overage report [--month <YYYY-MM>] [--event <name>]\n                           With SLOTLOCK_OVERAGE: send Stripe each paying Developer tenant's\n                           operations above its quota this month (or --month) not yet sent, as\n                           Billing Meter events (--event, default slotlock_operations), once\n                           (as the schema owner, with STRIPE_SECRET_KEY)\n  partner close <id> [--month <YYYY-MM>]\n                           Close an ended month (default: last month): price its accounts' use\n                           with the contract, record the lines once, send usage.period_closed,\n                           and with STRIPE_SECRET_KEY add the lines to the partner's next Stripe\n                           invoice; safe to run again\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; refused while its hosted plan is\n                           paid for (cancel the subscription first)\n  plan status              Print the deployment's default plan and the tenant's own (hosted)\n  plan default (free | developer | none) [--from <date>]\n                           Put every tenant without a plan of its own on this one from --from\n                           (an ISO date or time; default now), or none for no default; a new\n                           tenant gets it at once (as the schema owner, like tenant suspend)\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_USAGE                 on: count each tenant's operations, bookings and holds by day, API\n                                 key and surface (slotlock.usage_daily, kept 400 days); off\n                                 (default): record nothing\n  SLOTLOCK_QUOTAS                on (needs SLOTLOCK_USAGE=on): refuse a tenant on a plan past its\n                                 operations or bookings this month (quota_exceeded, 429); off\n                                 (default): no quota\n  SLOTLOCK_OVERAGE               off (default), or on (300) or a percent (111-1000): a paying\n                                 Developer tenant is refused only past that share of its\n                                 operations, and the rest above its quota is billed (overage\n                                 report); needs SLOTLOCK_QUOTAS=on\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_TRUSTED_PROXY_SECRET  A secret the proxy adds to every request in x-slotlock-proxy-proof,\n                                 32+ random characters: without it there, the field above is\n                                 ignored and the connection's address counts\n  SLOTLOCK_KNOWN_CLIENTS         Comma-separated integrator names /metrics counts requests by, from\n                                 their Slotlock-Client field (any other: other; none sent: none)\n  OTEL_EXPORTER_OTLP_ENDPOINT    An OpenTelemetry collector (OTLP over HTTP, JSON): a span per\n                                 call is sent to <endpoint>/v1/traces (off without it)\n  OTEL_EXPORTER_OTLP_TRACES_ENDPOINT The full traces URL instead of <endpoint>/v1/traces\n  OTEL_EXPORTER_OTLP_METRICS_ENDPOINT The full metrics URL instead of <endpoint>/v1/metrics (sent each minute)\n  OTEL_EXPORTER_OTLP_HEADERS     name=value pairs sent with each export, such as an API key\n  OTEL_SERVICE_NAME              service.name of the spans (default slotlock)\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_ASSISTANT_SECRET      Turns on the dashboard assistant and seals each organization's\n                                 model API key with it, 32+ random characters (dashboard; off\n                                 without it)\n  SLOTLOCK_ASSISTANT_PREVIOUS_SECRETS Up to three earlier SLOTLOCK_ASSISTANT_SECRET values,\n                                 comma-separated, newest first: keys sealed under one still open\n                                 and are sealed again under the current secret when next used\n  SLOTLOCK_ASSISTANT_PRIVATE_URLS off (default): refuse an assistant model URL whose host is, or\n                                 resolves to, a loopback, private, link-local, CGNAT, unique-local\n                                 or metadata address; on: allow them, for a self-hosted model\n                                 (Ollama, vLLM) on this machine or network\n  SLOTLOCK_GOOGLE_CLIENT_ID      Sign-in with Google too: the client id of a Google OAuth client with\n                                 redirect URI .../dashboard/callback (not with organization ids)\n  SLOTLOCK_GOOGLE_CLIENT_SECRET  Its client secret\n  SLOTLOCK_DASHBOARD_USERS       * or comma-separated GitHub user ids (and google:<subject>) that may sign in and whose keys work\n  SLOTLOCK_DASHBOARD_ORGS        comma-separated GitHub organization ids: each is one shared tenant;\n                                 or enabled: each person's own tenant, plus the organizations an\n                                 owner turns on from the dashboard's Teams page\n  SLOTLOCK_DASHBOARD_NAME        What the dashboard calls this deployment (default Slotlock)\n  SLOTLOCK_DASHBOARD_TERMS_URL   https URL of the terms people accept by signing in, linked on the\n                                 sign-in page (none named without it)\n  SLOTLOCK_DASHBOARD_PRIVACY_URL https URL of the privacy notice the sign-in page links\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