slotlock 0.6.3 → 0.8.0

package/self-host.js

@@ -4,26 +4,41 @@
 // 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 { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
 import { parseArgs } from 'node:util';
 import postgres from 'postgres';
 import { createSlotlockAgentServer, slotlockAgentOperationScope, } from './agent-server.js';
 import { createSlotlockStoreAgentBackend, createSlotlockStoreApplicationBackend, createSlotlockStoreChangeSource, } from './agent-store-backend.js';
-import { SLOTLOCK_API_KEY_DEFAULT_SCOPES, SLOTLOCK_API_KEY_MAX_LIFETIME_DAYS, SLOTLOCK_API_KEY_SCOPES, createSlotlockApiKeyAuthenticator, createSlotlockApiKeyStore, slotlockBearerCredential, } from './api-keys.js';
+import { SLOTLOCK_API_KEY_DEFAULT_SCOPES, SLOTLOCK_API_KEY_MAX_LIFETIME_DAYS, SLOTLOCK_API_KEY_SCOPES, createSlotlockApiKeyAuthenticator, createSlotlockApiKeyStore, SLOTLOCK_TEST_TENANT_SUFFIX, slotlockBearerCredential, slotlockLiveTenant, } from './api-keys.js';
+import { SLOTLOCK_SANDBOX_MAX_RACERS, SLOTLOCK_SANDBOX_SCENARIOS, fastForwardSlotlockSandbox, raceSlotlockSandbox, resetSlotlockSandbox, seedSlotlockSandbox, } from './sandbox.js';
 import { createSlotlockDashboard, createSlotlockDashboardResources, createSlotlockAcceptanceRecords, createSlotlockDashboardState, } from './dashboard.js';
 import { SECRET_HINT, SlotlockConfigError, formatSlotlockRate, optional, readAvailability, readDashboardConfig, readDashboardOrganizations, readDashboardUsers, readLimits, readSecret, readServerUrl, readTrustedProxyHeader, readTrustedProxySecret, 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 { slotlockApplicationOperation, slotlockApplicationScope, } from './application-api.js';
+import { SLOTLOCK_ACCOUNT_FIELD, createSlotlockPartnerKey, createSlotlockPartnerKeyAuthenticator, createSlotlockPartnerStore, listSlotlockPartners, putSlotlockPartner, revokeSlotlockPartnerKey, setSlotlockPartnerBilling, setSlotlockPartnerStatus, slotlockPartnerContractJson, } from './partners.js';
+import { closeSlotlockPartnerMonth, slotlockClientLabel, slotlockPreviousMonth } from './partner-billing.js';
+import { createSlotlockDashboardTeams, createSlotlockOrganizationCheck } from './teams.js';
+import { SLOTLOCK_DEFAULT_OVERAGE_STOP_PERCENT, reportSlotlockOverage, slotlockMonthOf } from './overage.js';
+import { createSlotlockOtlpExporter, createSlotlockOtlpMetricsExporter, readSlotlockOtlpConfig, } from './otel.js';
+import { readFile } from 'node:fs/promises';
+import { SLOTLOCK_DASHBOARD_FUNCTIONS, SLOTLOCK_QUOTA_FUNCTIONS, SLOTLOCK_TENANT_TABLES, SLOTLOCK_USAGE_FUNCTIONS, } 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 { readSlotlockPlanDefault, readSlotlockTenantPlan, readSlotlockTenantQuotas, setSlotlockPlanDefault, } from './plans.js';
+import { isSlotlockResourceScope } from './resource-profile.js';
+import { createSlotlockQuotas, noteSlotlockQuotaThreshold, readSlotlockQuotaUse } from './quotas.js';
 import { createSlotlockRequestLimits } from './rate-limit.js';
+import { createSlotlockUsageMeter, recordSlotlockUsage } from './usage.js';
 import { assertSlotlockSchemaCurrent, createSlotlockStore, } from './store.js';
 import { parseAvailabilityRules } from './weekly-hours.js';
 export { SlotlockConfigError };
-/** Every variable the commands read. The README, `.env.example` and `server.json` document these. */
+/**
+ * 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 const SLOTLOCK_ENVIRONMENT_VARIABLES = Object.freeze([
     'DATABASE_URL',
     'SLOTLOCK_MIGRATE_DATABASE_URL',
@@ -38,17 +53,31 @@ export const SLOTLOCK_ENVIRONMENT_VARIABLES = Object.freeze([
     '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',
 ]);
@@ -65,7 +94,7 @@ const DAY_MS = 86_400_000;
  * every GitHub user gives each a tenant, so the cap keeps one from filling the database.
  */
 const SERVE_MAX_TENANT_RESOURCES = 10_000;
-/** How often `serve` maintains each tenant with data (README, Operations: at least daily). */
+/** How often `serve` maintains each tenant with data (docs, Operations: at least daily). */
 const SERVE_MAINTENANCE_INTERVAL_MS = 60 * 60 * 1_000;
 /** Passes `slotlock maintain` runs at most, each as big as `serve`'s, until nothing is left. */
 const MAINTAIN_MAX_PASSES = 100;
@@ -95,6 +124,9 @@ const SERVED_OPERATIONS = new Set([
     'slotlock_list_events',
     'slotlock_update_event',
     'slotlock_delete_event',
+    'slotlock_confirm_slot',
+    'slotlock_reschedule',
+    'slotlock_cancel',
 ]);
 const HEALTH_QUERY_TIMEOUT_MS = 2_000;
 /** How long one database check answers /healthz, so a flood of health checks is not one of queries. */
@@ -203,6 +235,39 @@ function readSharedLimits(env) {
     }
     return value === 'on';
 }
+/** SLOTLOCK_USAGE: on to meter each tenant's use (usage.ts); off, the default, records nothing. */
+function readUsageMetering(env) {
+    const value = optional(env, 'SLOTLOCK_USAGE') ?? 'off';
+    if (value !== 'on' && value !== 'off') {
+        throw new SlotlockConfigError('SLOTLOCK_USAGE must be on or off');
+    }
+    return value === 'on';
+}
+/** SLOTLOCK_QUOTAS: on to hold each tenant on a plan to its monthly quotas; it counts with usage. */
+function readQuotas(env, usage) {
+    const value = optional(env, 'SLOTLOCK_QUOTAS') ?? 'off';
+    if (value !== 'on' && value !== 'off') {
+        throw new SlotlockConfigError('SLOTLOCK_QUOTAS must be on or off');
+    }
+    if (value === 'on' && !usage) {
+        throw new SlotlockConfigError('SLOTLOCK_QUOTAS=on needs SLOTLOCK_USAGE=on: a quota is held against the usage it counts');
+    }
+    return value === 'on';
+}
+/**
+ * SLOTLOCK_KNOWN_CLIENTS: the integrators metrics name (comma-separated, lower-case names like
+ * stackapi or n8n), at most 50, so a scrape stays bounded and names only those the deployment chose.
+ */
+function readKnownClients(env) {
+    const value = optional(env, 'SLOTLOCK_KNOWN_CLIENTS');
+    if (value === undefined)
+        return [];
+    const names = value.split(',').map((name) => name.trim());
+    if (names.length > 50 || names.some((name) => !/^[a-z][a-z0-9_.-]{0,39}$/.test(name) || name === 'other' || name === 'none')) {
+        throw new SlotlockConfigError('SLOTLOCK_KNOWN_CLIENTS must be up to 50 comma-separated lower-case names (letters, digits, _ . -), not other or none');
+    }
+    return [...new Set(names)];
+}
 function readRestApi(env) {
     const value = optional(env, 'SLOTLOCK_REST_API') ?? 'on';
     if (value !== 'on' && value !== 'off') {
@@ -234,14 +299,39 @@ export function readSlotlockServeConfig(env) {
         restApi: readRestApi(env),
         webhooks: readWebhooks(env),
         sharedLimits: readSharedLimits(env),
+        usage: readUsageMetering(env),
+        quotas: false,
         limits: readLimits(env),
     };
+    config.quotas = readQuotas(env, config.usage);
+    const overage = optional(env, 'SLOTLOCK_OVERAGE') ?? 'off';
+    if (overage !== 'off') {
+        const percent = overage === 'on' ? SLOTLOCK_DEFAULT_OVERAGE_STOP_PERCENT : Number(overage);
+        if (!Number.isSafeInteger(percent) || percent < 111 || percent > 1_000) {
+            throw new SlotlockConfigError('SLOTLOCK_OVERAGE must be off, on, or the percent of its quota a paying Developer tenant is refused at (111-1000)');
+        }
+        if (!config.quotas)
+            throw new SlotlockConfigError('SLOTLOCK_OVERAGE needs SLOTLOCK_QUOTAS=on: overage is what is used past a quota');
+        config.overageStopPercent = percent;
+    }
     const trustedProxyHeader = readTrustedProxyHeader(env);
     if (trustedProxyHeader !== undefined)
         config.trustedProxyHeader = trustedProxyHeader;
     const trustedProxySecret = readTrustedProxySecret(env, trustedProxyHeader);
     if (trustedProxySecret !== undefined)
         config.trustedProxySecret = trustedProxySecret;
+    const knownClients = readKnownClients(env);
+    if (knownClients.length > 0)
+        config.knownClients = knownClients;
+    let otlp;
+    try {
+        otlp = readSlotlockOtlpConfig(env);
+    }
+    catch (error) {
+        throw new SlotlockConfigError(error.message);
+    }
+    if (otlp !== undefined)
+        config.otlp = otlp;
     if (authToken !== undefined)
         config.authToken = authToken;
     const metricsToken = readSecret(env, 'SLOTLOCK_METRICS_TOKEN');
@@ -252,6 +342,7 @@ export function readSlotlockServeConfig(env) {
             env.SLOTLOCK_SESSION_SECRET?.trim(),
             env.SLOTLOCK_GITHUB_CLIENT_SECRET?.trim(),
             env.SLOTLOCK_ASSISTANT_SECRET?.trim(),
+            ...(env.SLOTLOCK_ASSISTANT_PREVIOUS_SECRETS?.split(',').map((part) => part.trim()) ?? []),
         ];
         if (others.includes(metricsToken)) {
             throw new SlotlockConfigError('SLOTLOCK_METRICS_TOKEN must differ from every other secret');
@@ -326,6 +417,14 @@ function secretsIn(env) {
         if (value)
             secrets.push(value);
     }
+    // A list: each secret in it, as well as the whole.
+    const previous = env.SLOTLOCK_ASSISTANT_PREVIOUS_SECRETS?.trim();
+    if (previous) {
+        secrets.push(previous);
+        for (const part of previous.split(','))
+            if (part.trim())
+                secrets.push(part.trim());
+    }
     for (const name of ['DATABASE_URL', 'SLOTLOCK_MIGRATE_DATABASE_URL']) {
         const value = env[name]?.trim();
         if (!value)
@@ -513,13 +612,19 @@ function serveMetrics(target, metrics, path, token) {
  * SLOTLOCK_DASHBOARD_USERS is not set, and every other tenant.
  */
 export function slotlockServeAllowsTenant(config, tenantRef) {
-    const orgId = /^github-org:(\d+)$/.exec(tenantRef)?.[1];
+    // A test environment (RFC 0003 G9) is let through exactly as its live tenant.
+    const live = slotlockLiveTenant(tenantRef);
+    const orgId = /^github-org:(\d+)$/.exec(live)?.[1];
+    // With `enabled`, the database decides, as serve's authenticate asks (createSlotlockOrganizationCheck).
     if (orgId !== undefined)
-        return config.organizations?.includes(orgId) === true;
+        return config.organizations === 'enabled' || config.organizations?.includes(orgId) === true;
     const users = config.allowedUsers;
     if (users === undefined || users === '*')
         return true;
-    const githubId = /^github:(\d+)$/.exec(tenantRef)?.[1];
+    // A Google person (google:<subject>) only while the list names them so.
+    if (live.startsWith('google:'))
+        return users.includes(live);
+    const githubId = /^github:(\d+)$/.exec(live)?.[1];
     return githubId === undefined || users.includes(githubId);
 }
 function serveTenantLimits(caps) {
@@ -639,10 +744,41 @@ export async function startSlotlockServer(config, log) {
                 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' });
             }
         }
+        if (config.usage) {
+            for (const signature of [...SLOTLOCK_USAGE_FUNCTIONS, ...(config.quotas ? SLOTLOCK_QUOTA_FUNCTIONS : [])]) {
+                const [granted] = await sql `
+          SELECT CASE WHEN to_regprocedure(${signature}) IS NULL THEN false
+                      ELSE has_function_privilege(to_regprocedure(${signature}), 'EXECUTE') END AS ready`;
+                if (!granted?.ready) {
+                    throw Object.assign(new Error(`${SLOTLOCK_USAGE_FUNCTIONS.includes(signature) ? 'SLOTLOCK_USAGE' : 'SLOTLOCK_QUOTAS'} needs ${signature}, which this database role cannot run: run \`slotlock migrate\` (or \`slotlock serve --migrate\`) with this release`), { code: 'schema_outdated' });
+                }
+            }
+        }
+        // Each tenant's operations, recorded every 15 seconds and when the server stops (usage.ts).
+        const usage = config.usage
+            ? createSlotlockUsageMeter({
+                record: (flushId, rows) => recordSlotlockUsage(sql, flushId, rows),
+                onError: (error) => log.error('usage_record_failed', {
+                    error: error instanceof Error ? error.message : 'unknown',
+                }),
+            })
+            : undefined;
+        // Each tenant on a plan held to its monthly quotas, counted with the meter (quotas.ts).
+        const quotas = config.quotas && usage
+            ? createSlotlockQuotas({
+                plan: (tenantRef) => readSlotlockTenantQuotas(sql, tenantRef, config.overageStopPercent !== undefined ? { overageStopPercent: config.overageStopPercent } : {}),
+                used: (tenantRef, fromDay) => readSlotlockQuotaUse(sql, tenantRef, fromDay),
+                local: (tenantRef, metric, fromDay) => usage.local(tenantRef, metric, fromDay),
+                notice: (notice) => noteSlotlockQuotaThreshold(sql, notice),
+                onError: (error) => log.error('quota_failed', { error: error instanceof Error ? error.message : 'unknown' }),
+            })
+            : undefined;
         const { caps } = config.limits;
         const store = createSlotlockServeStore(sql, caps, config.availability, config.retentionDays);
         const retention = config.retentionDays !== undefined ? { retentionDays: config.retentionDays } : {};
         const publicUrl = new URL(config.publicUrl);
+        // Partner keys (`slk_partner_…`, RFC 0003 P1): the partner API, for the partner's accounts only.
+        const authenticatePartner = createSlotlockPartnerKeyAuthenticator(sql);
         const authenticateKey = createSlotlockApiKeyAuthenticator(createSlotlockApiKeyStore(sql), {
             maxConcurrentLookups: caps.key_lookups,
             maxWaitingLookups: caps.key_lookup_queue,
@@ -660,12 +796,28 @@ export async function startSlotlockServer(config, log) {
         let maintenance;
         let webhooks;
         const basePath = publicUrl.pathname.replace(/\/$/, '');
-        const metrics = config.metricsToken === undefined
+        // Counted for the scrape (SLOTLOCK_METRICS_TOKEN), an OpenTelemetry collector, or both.
+        const metrics = config.metricsToken === undefined && config.otlp?.metricsUrl === undefined
             ? undefined
             : createSlotlockMetrics({
                 version: slotlockPackageVersion(),
                 ...(process.versions.tz ? { tzdata: process.versions.tz } : {}),
             });
+        const knownClients = new Set(config.knownClients ?? []);
+        // The same counters to an OpenTelemetry collector each minute, when one is configured.
+        const metricsExport = metrics && config.otlp?.metricsUrl
+            ? createSlotlockOtlpMetricsExporter({ ...config.otlp, metricsUrl: config.otlp.metricsUrl }, metrics, {
+                onError: (reason) => log.warn('metrics_export_failed', { reason }),
+            })
+            : undefined;
+        // A span per call to an OpenTelemetry collector, when one is configured.
+        const tracer = config.otlp?.tracesUrl
+            ? createSlotlockOtlpExporter(config.otlp, {
+                onError: (reason) => log.warn('trace_export_failed', { reason }),
+            })
+            : undefined;
+        // Teams on Cloud: an organization's keys work while an owner has it turned on.
+        const organizationEnabled = config.organizations === 'enabled' ? createSlotlockOrganizationCheck(sql) : null;
         const limits = createSlotlockRequestLimits({
             limits: config.limits,
             ...(config.sharedLimits
@@ -688,14 +840,27 @@ export async function startSlotlockServer(config, log) {
                 ? { trustedProxySecret: config.trustedProxySecret }
                 : {}),
             basePath,
+            ...(quotas ? { quotas } : {}),
             signInPaths: config.dashboard ? ['/dashboard/sign-in', '/dashboard/callback'] : [],
             // The token is compared in constant time first; only then is a key looked up. A person the
             // dashboard no longer allows loses their keys with their session.
             authenticate: async (request) => {
-                const principal = (await authenticateToken?.(request)) ?? (await authenticateKey(request));
+                const principal = (await authenticateToken?.(request)) ??
+                    (await authenticatePartner(request)) ??
+                    (await authenticateKey(request));
                 if (!principal || !slotlockServeAllowsTenant(config, principal.tenantRef))
                     return null;
-                maintenance?.touch(principal.tenantRef);
+                const orgId = organizationEnabled ? /^github-org:(\d+)$/.exec(slotlockLiveTenant(principal.tenantRef))?.[1] : undefined;
+                if (orgId !== undefined && !(await organizationEnabled?.(orgId)))
+                    return null;
+                // Slotlock-Account is a partner key's alone (RFC 0003 P3): with any other credential, or one
+                // that could not act for that account, the request is refused rather than run elsewhere.
+                if (request.headers.has(SLOTLOCK_ACCOUNT_FIELD) && principal.onBehalfOf === undefined)
+                    return null;
+                // A partner key's own tenant holds nothing to maintain; its accounts' keys are as any key.
+                if (principal.partnerId === undefined)
+                    maintenance?.touch(principal.tenantRef);
+                metrics?.client(slotlockClientLabel(request.headers.get('slotlock-client'), knownClients));
                 return principal;
             },
             // Counts and pseudonyms only: never an address, a credential or a tenant.
@@ -711,6 +876,7 @@ export async function startSlotlockServer(config, log) {
             availabilityRules: async () => config.availability.map((rule) => ({ ...rule })),
         });
         const agentServer = createSlotlockAgentServer({
+            ...(usage ? { onUsage: usage.count } : {}),
             publicBaseUrl: config.publicUrl,
             // readPublicUrl admits plain HTTP only on a loopback host, which is all this permits anyway.
             allowInsecureLocalhost: publicUrl.protocol === 'http:',
@@ -722,6 +888,7 @@ export async function startSlotlockServer(config, log) {
             authorize: async ({ principal, operation, input }) => {
                 if (!authorizeSlotlockServeOperation({ principal, operation }))
                     return false;
+                await limits.quota({ principal, operation });
                 await limits.admit({ principal, operation, input });
                 return true;
             },
@@ -740,9 +907,13 @@ export async function startSlotlockServer(config, log) {
                     ? { ready: true, checks: ['database'] }
                     : { ready: false, checks: ['database_unreachable'] };
             },
+            ...(tracer ? { onCallTrace: (event, trace) => tracer.record(event, trace.parentSpanId) } : {}),
             // Outcomes and counts only: the server never reports arguments or identities.
             onEvent: (event) => {
                 metrics?.event(event);
+                // A traced call's span is made from onCallTrace, as a child of the caller's.
+                if (!('traceId' in event && event.traceId !== undefined))
+                    tracer?.record(event);
                 const { type, ...fields } = event;
                 log.info(type, snakeCaseKeys(fields));
             },
@@ -756,10 +927,19 @@ export async function startSlotlockServer(config, log) {
                     application: {
                         backend: createSlotlockStoreApplicationBackend(store, {
                             maxTenantResources: SERVE_MAX_TENANT_RESOURCES,
+                            // A granted approval's booking is made as an agent's would be (RFC 0004 A4).
+                            agentBackend,
+                            partners: createSlotlockPartnerStore(sql, {
+                                keys: createSlotlockApiKeyStore(sql),
+                                eraseTenant: (tenantRef) => store.eraseTenant({ tenantRef }),
+                            }),
                         }),
                         authorize: async ({ principal, operation, input }) => {
-                            if (principal.scopes?.includes(SLOTLOCK_APPLICATION_SCOPE) !== true)
+                            // admin, or a partner key's partner scope for the partner API: never either for the other.
+                            const needed = slotlockApplicationScope(slotlockApplicationOperation(operation));
+                            if (principal.scopes?.includes(needed) !== true)
                                 return false;
+                            await limits.quota({ principal, operation });
                             await limits.admit({ principal, operation, input });
                             return true;
                         },
@@ -786,27 +966,46 @@ export async function startSlotlockServer(config, log) {
                 },
                 sessionSecret: config.dashboard.sessionSecret,
                 allowedUsers: config.dashboard.allowedUsers,
+                ...(config.dashboard.google ? { google: config.dashboard.google } : {}),
                 ...(config.dashboard.name ? { name: config.dashboard.name } : {}),
+                ...(config.dashboard.termsUrl ? { termsUrl: config.dashboard.termsUrl } : {}),
+                ...(config.dashboard.privacyUrl ? { privacyUrl: config.dashboard.privacyUrl } : {}),
                 ...(config.dashboard.organizations
                     ? { organizations: config.dashboard.organizations }
                     : {}),
+                ...(config.dashboard.organizations === 'enabled' ? { teams: createSlotlockDashboardTeams(sql) } : {}),
                 keys: createSlotlockApiKeyStore(sql),
-                resources: createSlotlockDashboardResources(store),
+                resources: createSlotlockDashboardResources(store, { agentBackend }),
                 state: createSlotlockDashboardState(sql),
                 availability: config.availability,
+                ...(config.usage ? { usage: true } : {}),
+                ...(config.quotas ? { quotas: true } : {}),
                 ...(config.dashboard.assistantSecret !== undefined
                     ? {
                         // The assistant's reads and approved writes are agent calls: the same backend,
                         // operations, rate limits and series-write slots as an API key's.
                         assistant: {
                             secret: config.dashboard.assistantSecret,
+                            ...(usage
+                                ? {
+                                    onUsage: usage.count,
+                                    onMessage: (tenantRef) => usage.add({ tenantRef, metric: 'assistant_messages', origin: 'dashboard-assistant' }),
+                                }
+                                : {}),
+                            ...(config.dashboard.assistantPreviousSecrets
+                                ? { previousSecrets: config.dashboard.assistantPreviousSecrets }
+                                : {}),
                             ...(config.dashboard.assistantPrivateUrls ? { privateUrls: true } : {}),
                             backend: agentBackend,
                             consumeRateLimit: limits.consumeRateLimit,
                             // Checks only: a proposal holds nothing. The series-write slot and the write
                             // token are taken when an approved change runs (admit, consumeRateLimit).
                             authorize: async ({ principal, operation }) => authorizeSlotlockServeOperation({ principal, operation }),
-                            admit: (args) => limits.admit(args),
+                            // A read, or an approved write, over the tenant's monthly quota is refused.
+                            admit: async (args) => {
+                                await limits.quota(args);
+                                await limits.admit(args);
+                            },
                         },
                     }
                     : {}),
@@ -837,6 +1036,7 @@ export async function startSlotlockServer(config, log) {
             discover: () => pageTenants((after) => sql `
           SELECT slotlock.maintenance_tenants(${after}::text) AS tenant`),
             intervalMs: SERVE_MAINTENANCE_INTERVAL_MS,
+            ...(config.usage ? { usage: true } : {}),
             // Counts only, never the tenant.
             onPass: (result) => {
                 metrics?.maintenance(result);
@@ -861,10 +1061,11 @@ export async function startSlotlockServer(config, log) {
                         }),
                     },
                 }),
-                // Counts only, never the tenant or a URL.
-                onPass: (_tenant, result) => {
+                // Counts only, never the tenant or a URL; the tenant's own count goes to its usage.
+                onPass: (tenantRef, result) => {
                     metrics?.webhooks(result);
                     log.info('webhooks', { ...result });
+                    usage?.add({ tenantRef, metric: 'webhook_deliveries', origin: 'webhooks', count: result.delivered });
                 },
                 onError: (error) => log.error('webhooks_failed', describeError(error)),
             });
@@ -881,6 +1082,8 @@ export async function startSlotlockServer(config, log) {
             rest: config.restApi ? `${config.publicUrl}/openapi.json` : null,
             webhooks: config.webhooks,
             shared_limits: config.sharedLimits,
+            usage: config.usage,
+            quotas: config.quotas,
             tzdata: process.versions.tz ?? null,
             maintenance_interval_minutes: SERVE_MAINTENANCE_INTERVAL_MS / 60_000,
             limits: {
@@ -897,6 +1100,10 @@ export async function startSlotlockServer(config, log) {
             async close() {
                 const result = await listener.close();
                 limits.close();
+                // What the last requests counted is recorded before the pool closes.
+                await usage?.close();
+                await tracer?.shutdown();
+                await metricsExport?.shutdown();
                 await maintenance?.close();
                 await webhooks?.close();
                 await sql.end({ timeout: 5 });
@@ -917,6 +1124,94 @@ function resourceLine(resource) {
     })}\n`;
 }
 /** `resource add`: create (or, for an existing reference, re-zone) one resource in the tenant. */
+/**
+ * `slotlock sandbox …` (RFC 0004 A6), in the tenant SLOTLOCK_TENANT names, which must be a test
+ * environment (`<tenant>~test`): seed a scenario, reset, fast-forward, or race agents for one slot.
+ */
+async function runSandboxCommand(subcommand, operands, values, io) {
+    const config = readSlotlockDatabaseConfig(io.env);
+    if (!config.tenantRef.endsWith(SLOTLOCK_TEST_TENANT_SUFFIX)) {
+        io.stderr.write(`slotlock: the sandbox works only in a test environment: SLOTLOCK_TENANT=${config.tenantRef}${SLOTLOCK_TEST_TENANT_SUFFIX}\n`);
+        return 2;
+    }
+    const line = (value) => io.stdout.write(`${JSON.stringify(value)}\n`);
+    const sql = connect(config.databaseUrl, subcommand === 'sandbox race' ? 20 : 1);
+    const store = createSlotlockStore(sql);
+    try {
+        if (subcommand === 'sandbox seed') {
+            const scenario = operands[1];
+            if (!SLOTLOCK_SANDBOX_SCENARIOS.includes(scenario)) {
+                io.stderr.write(`slotlock: the scenarios are ${SLOTLOCK_SANDBOX_SCENARIOS.join(', ')}\n`);
+                return 2;
+            }
+            line(await seedSlotlockSandbox(store, config.tenantRef, scenario));
+            return 0;
+        }
+        if (subcommand === 'sandbox reset') {
+            line({ removed: await resetSlotlockSandbox(store, config.tenantRef) });
+            return 0;
+        }
+        if (subcommand === 'sandbox fast-forward') {
+            const minutes = /^[1-9][0-9]{0,5}$/.test(operands[1] ?? '') ? Number(operands[1]) : Number.NaN;
+            if (!(minutes >= 1 && minutes <= 525_600)) {
+                io.stderr.write('slotlock: fast-forward takes whole minutes, 1 to 525,600\n');
+                return 2;
+            }
+            const forward = await fastForwardSlotlockSandbox(store, config.tenantRef, minutes);
+            line({ minutes, holds: forward.holds, approvals: forward.approvals, pruned: forward.maintenance.pruned, approvals_expired: forward.maintenance.approvalsExpired });
+            return 0;
+        }
+        // A race: on the resource named, from --start (an hour from tomorrow's 10:00 UTC by default).
+        const agents = values.agents === undefined ? 100 : /^[0-9]{1,3}$/.test(values.agents) ? Number(values.agents) : Number.NaN;
+        if (!(agents >= 2 && agents <= SLOTLOCK_SANDBOX_MAX_RACERS)) {
+            io.stderr.write(`slotlock: --agents must be 2 to ${SLOTLOCK_SANDBOX_MAX_RACERS}\n`);
+            return 2;
+        }
+        const tomorrow = new Date(Date.now() + 86_400_000);
+        const start = values.start !== undefined
+            ? new Date(values.start)
+            : new Date(Date.UTC(tomorrow.getUTCFullYear(), tomorrow.getUTCMonth(), tomorrow.getUTCDate(), 10));
+        if (!Number.isFinite(start.getTime())) {
+            io.stderr.write('slotlock: --start must be a date and time, like 2027-03-02T10:00:00Z\n');
+            return 2;
+        }
+        const resource = (await store.withTenant(config.tenantRef, (tenant) => tenant.listResources({ tenantRef: config.tenantRef, limit: 1000 }))).find((candidate) => candidate.externalRef === operands[1] || candidate.id === operands[1]);
+        if (!resource) {
+            io.stderr.write('slotlock: no resource with that reference in the test environment\n');
+            return 1;
+        }
+        const raced = await raceSlotlockSandbox({
+            backend: createSlotlockStoreAgentBackend(store, { availabilityRules: async () => [...readAvailability(io.env)] }),
+            tenantRef: config.tenantRef,
+            resourceId: resource.id,
+            start,
+            end: new Date(start.getTime() + 3_600_000),
+            agents,
+        });
+        line({
+            agents: raced.agents,
+            booked: raced.booked,
+            refused: raced.refused,
+            with_alternatives: raced.withAlternatives,
+            server_errors: raced.serverErrors,
+            p50_ms: raced.p50Ms,
+            p99_ms: raced.p99Ms,
+            max_ms: raced.maxMs,
+        });
+        return raced.booked === 1 && raced.serverErrors === 0 ? 0 : 1;
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code === 'sandbox_not_empty') {
+            io.stderr.write('slotlock: the test environment has resources already; run slotlock sandbox reset first\n');
+            return 1;
+        }
+        throw error;
+    }
+    finally {
+        await sql.end({ timeout: 5 });
+    }
+}
 async function addResource(config, externalRef, timezone) {
     const sql = connect(config.databaseUrl, 1);
     try {
@@ -1089,6 +1384,229 @@ async function changeResource(config, out, name, action) {
         await sql.end({ timeout: 5 });
     }
 }
+/**
+ * `billing daily`: everything billing needs once a day, idempotent, for a cron job. Last month is
+ * closed for each active partner only once it has been over for BILLING_GRACE_MS, as late counts
+ * (bookings roll up hourly) settle first; overage goes for last month and this one; and each
+ * partner's reconciliation mismatches of the last week are listed. Exit 1 when anything waits or
+ * differs, so the cron job's failure is the incident.
+ */
+async function runBillingDaily(owner, io, options) {
+    const line = (value) => io.stdout.write(`${JSON.stringify(value)}\n`);
+    let attention = false;
+    const month = slotlockPreviousMonth(options.now);
+    const today = new Date(options.now);
+    const monthBegan = Date.UTC(today.getUTCFullYear(), today.getUTCMonth(), 1);
+    if (options.now - monthBegan < BILLING_GRACE_MS) {
+        line({ job: 'partner_close', month, waiting_until: new Date(monthBegan + BILLING_GRACE_MS).toISOString() });
+    }
+    else {
+        for (const partner of await listSlotlockPartners(owner)) {
+            if (partner.status !== 'active')
+                continue;
+            const closed = await closeSlotlockPartnerMonth(owner, {
+                partnerId: partner.id,
+                month,
+                now: options.now,
+                ...(options.stripeSecretKey ? { stripe: { secretKey: options.stripeSecretKey } } : {}),
+            });
+            line({ job: 'partner_close', partner: partner.id, month, webhook: closed.webhook, invoiced: closed.invoiced, pending: closed.pending });
+            if (closed.webhook === 'failed' || closed.pending > 0)
+                attention = true;
+        }
+    }
+    if (options.overage) {
+        if (!options.stripeSecretKey) {
+            line({ job: 'overage', skipped: 'no STRIPE_SECRET_KEY' });
+            attention = true;
+        }
+        else {
+            for (const reported of [month, slotlockMonthOf(options.now)]) {
+                const report = await reportSlotlockOverage(owner, {
+                    month: reported,
+                    now: options.now,
+                    stripe: { secretKey: options.stripeSecretKey, eventName: 'slotlock_operations' },
+                });
+                line({ job: 'overage', month: reported, sent: report.sent, failed: report.failed });
+                if (report.failed > 0)
+                    attention = true;
+            }
+        }
+    }
+    const mismatches = await owner `
+    SELECT partner_id, day::text, mismatched, worst_percent::float AS worst
+      FROM slotlock.partner_reconciliations
+     WHERE mismatched > 0 AND day >= current_date - 7
+     ORDER BY day, partner_id`;
+    for (const mismatch of mismatches) {
+        line({ job: 'reconciliation', partner: mismatch.partner_id, day: mismatch.day, mismatched: mismatch.mismatched, worst_percent: mismatch.worst });
+        attention = true;
+    }
+    line({ job: 'done', month, attention });
+    if (attention)
+        io.stderr.write('slotlock: billing needs attention: see the lines above; run billing daily again once it is resolved\n');
+    return attention ? 1 : 0;
+}
+/** How long after a month ends billing daily waits to close it: late counts settle first. */
+const BILLING_GRACE_MS = 6 * 3_600_000;
+/**
+ * `resource parent <ref> <parent-ref | none>` (RFC 0003 G8): make a resource a part of a composite,
+ * or no part. The refusal's code when the database refuses it, false for no such resource.
+ */
+async function setResourceParent(config, out, name, parentName) {
+    const sql = connect(config.databaseUrl, 1);
+    try {
+        const store = createSlotlockStore(sql);
+        const tenantRef = config.tenantRef;
+        const resources = await tenantResources(store, tenantRef, true);
+        const find = (wanted) => resources.find((resource) => resource.id === wanted) ?? resources.find((resource) => resource.externalRef === wanted);
+        const named = find(name);
+        if (!named)
+            return false;
+        const parent = parentName === 'none' ? null : find(parentName);
+        if (parent === undefined)
+            return 'parent_not_found';
+        try {
+            const changed = await store.withTenant(tenantRef, (tenant) => tenant.setResourceParent({ tenantRef, id: named.id, parentId: parent?.id ?? null }));
+            if (!changed)
+                return false;
+            out.write(`${JSON.stringify({ id: changed.id, external_ref: changed.externalRef, parent_id: changed.parentId ?? null, part_index: changed.partIndex ?? null })}\n`);
+            return true;
+        }
+        catch (error) {
+            const code = error?.code;
+            if (typeof code === 'string' && (code.startsWith('composite_') || code === 'parent_not_found'))
+                return code;
+            throw error;
+        }
+    }
+    finally {
+        await sql.end({ timeout: 5 });
+    }
+}
+/**
+ * `partner …` (RFC 0003 part 4), as the schema owner (SLOTLOCK_MIGRATE_DATABASE_URL when set): make
+ * a partner with its contract, list them, suspend one (every account with it) or make it active,
+ * make or revoke its keys (shown once), and set its Stripe customer and its webhook (whose secret
+ * is made here and shown once).
+ */
+async function runPartnerCommand(config, io, action, operands, contractGiven, close = { month: undefined, stripeSecretKey: undefined }) {
+    const owner = connect(config.migrateDatabaseUrl ?? config.databaseUrl, 1);
+    const [id = '', second = ''] = operands;
+    const line = (value) => io.stdout.write(`${JSON.stringify(value)}\n`);
+    try {
+        switch (action) {
+            case 'create': {
+                const text = contractGiven?.startsWith('@')
+                    ? await readFile(contractGiven.slice(1), 'utf8')
+                    : (contractGiven ?? '');
+                let contract;
+                try {
+                    contract = JSON.parse(text);
+                }
+                catch {
+                    throw Object.assign(new Error('Slotlock partner contract: --contract is not JSON'), { code: 'invalid_partner_contract' });
+                }
+                const partner = await putSlotlockPartner(owner, { id, name: second, contract });
+                line({ id: partner.id, name: partner.name, status: partner.status, contract: slotlockPartnerContractJson(partner.contract) });
+                return 0;
+            }
+            case 'list':
+                for (const partner of await listSlotlockPartners(owner)) {
+                    line({
+                        id: partner.id,
+                        name: partner.name,
+                        status: partner.status,
+                        stripe_customer: partner.stripeCustomer,
+                        webhook_url: partner.webhookUrl,
+                        plans: Object.keys(partner.contract.plans),
+                    });
+                }
+                return 0;
+            case 'suspend':
+            case 'unsuspend': {
+                const changed = await setSlotlockPartnerStatus(owner, id, action === 'suspend' ? 'suspended' : 'active');
+                if (!changed) {
+                    io.stderr.write('slotlock: no partner with that id\n');
+                    return 1;
+                }
+                line({ id, status: action === 'suspend' ? 'suspended' : 'active' });
+                return 0;
+            }
+            case 'key': {
+                const created = await createSlotlockPartnerKey(owner, id, second);
+                line({ partner: id, id: created.id, prefix: created.prefix, key: created.key });
+                io.stderr.write('slotlock: the partner key is shown once and only its SHA-256 is stored; send it to the partner securely\n');
+                return 0;
+            }
+            case 'revoke-key': {
+                if (!(await revokeSlotlockPartnerKey(owner, id, second))) {
+                    io.stderr.write('slotlock: no key with that id for that partner\n');
+                    return 1;
+                }
+                line({ partner: id, id: second, revoked: true });
+                return 0;
+            }
+            case 'customer': {
+                if (!(await setSlotlockPartnerBilling(owner, id, { stripeCustomer: second }))) {
+                    io.stderr.write('slotlock: no partner with that id\n');
+                    return 1;
+                }
+                line({ id, stripe_customer: second });
+                return 0;
+            }
+            case 'webhook': {
+                const secret = `whsec_${randomBytes(32).toString('base64')}`;
+                if (!(await setSlotlockPartnerBilling(owner, id, { webhookUrl: second, webhookSecret: secret }))) {
+                    io.stderr.write('slotlock: no partner with that id\n');
+                    return 1;
+                }
+                line({ id, webhook_url: second, webhook_secret: secret });
+                io.stderr.write('slotlock: the webhook secret is shown once; the partner verifies usage.period_closed with it\n');
+                return 0;
+            }
+            case 'close': {
+                const closed = await closeSlotlockPartnerMonth(owner, {
+                    partnerId: id,
+                    month: close.month ?? slotlockPreviousMonth(Date.now()),
+                    ...(close.stripeSecretKey ? { stripe: { secretKey: close.stripeSecretKey } } : {}),
+                });
+                line({
+                    partner: closed.partner,
+                    month: closed.month,
+                    accounts: closed.accounts.length,
+                    lines: closed.lines.map((entry) => ({
+                        line: entry.line,
+                        quantity: entry.quantity,
+                        amount: entry.amount,
+                        currency: entry.currency,
+                        stripe_item: entry.stripeItem,
+                    })),
+                    checksum: closed.checksum,
+                    closed_now: closed.closedNow,
+                    webhook: closed.webhook,
+                    ...(closed.webhookStatus !== undefined ? { webhook_status: closed.webhookStatus } : {}),
+                    invoiced: closed.invoiced,
+                    pending: closed.pending,
+                });
+                if (closed.webhook === 'failed') {
+                    io.stderr.write('slotlock: the partner\'s endpoint did not take usage.period_closed; run partner close again for the same month\n');
+                }
+                if (closed.pending > 0) {
+                    io.stderr.write(close.stripeSecretKey
+                        ? 'slotlock: some lines did not reach Stripe; run partner close again for the same month\n'
+                        : 'slotlock: lines recorded, not invoiced: set STRIPE_SECRET_KEY (and partner customer) and run it again\n');
+                }
+                return closed.pending > 0 || closed.webhook === 'failed' ? 1 : 0;
+            }
+            default:
+                return 2;
+        }
+    }
+    finally {
+        await owner.end({ timeout: 5 });
+    }
+}
 /**
  * `tenant status|suspend|unsuspend|erase` for SLOTLOCK_TENANT. Suspending and lifting a suspension
  * are the deployment role's alone, so they connect as SLOTLOCK_MIGRATE_DATABASE_URL when it is set;
@@ -1125,6 +1643,52 @@ async function runTenantCommand(config, out, action, reason) {
         await sql.end({ timeout: 5 });
     }
 }
+/**
+ * `plan status` prints the default plan and SLOTLOCK_TENANT's own; `plan default` sets or removes
+ * the default, as the deployment role (SLOTLOCK_MIGRATE_DATABASE_URL when set), and then prints both.
+ */
+async function runPlanCommand(config, out, planDefault, set) {
+    if (set) {
+        const owner = connect(config.migrateDatabaseUrl ?? config.databaseUrl, 1);
+        try {
+            await setSlotlockPlanDefault(owner, planDefault);
+        }
+        finally {
+            await owner.end({ timeout: 5 });
+        }
+    }
+    const sql = connect(config.databaseUrl, 1);
+    try {
+        const fallback = await readSlotlockPlanDefault(sql);
+        const own = await readSlotlockTenantPlan(sql, config.tenantRef);
+        out.write(`${JSON.stringify({
+            default: fallback
+                ? {
+                    plan: fallback.plan,
+                    applies_from: fallback.appliesFrom.toISOString(),
+                    resources: fallback.limits.resources,
+                    api_keys: fallback.limits.apiKeys,
+                    webhook_endpoints: fallback.limits.webhookEndpoints,
+                }
+                : null,
+            tenant: config.tenantRef,
+            plan: own
+                ? {
+                    plan: own.plan,
+                    status: own.status,
+                    resources: own.limits.resources,
+                    api_keys: own.limits.apiKeys,
+                    webhook_endpoints: own.limits.webhookEndpoints,
+                    paid: own.stripeSubscription !== null,
+                    current_period_end: own.currentPeriodEnd?.toISOString() ?? null,
+                }
+                : null,
+        })}\n`);
+    }
+    finally {
+        await sql.end({ timeout: 5 });
+    }
+}
 /** One key as `key create`, `key list` and `key revoke` print it: never the digest. */
 function apiKeyLine(apiKey, key) {
     return `${JSON.stringify({
@@ -1137,9 +1701,55 @@ function apiKeyLine(apiKey, key) {
         expires_at: apiKey.expiresAt?.toISOString() ?? null,
         last_used_at: apiKey.lastUsedAt?.toISOString() ?? null,
         revoked_at: apiKey.revokedAt?.toISOString() ?? null,
+        ...(apiKey.resourceScope ? { resource_scope: apiKey.resourceScope } : {}),
+        ...(apiKey.limits ? { limits: apiKeyLimitsJson(apiKey.limits) } : {}),
         ...(key !== undefined ? { key } : {}),
     })}\n`;
 }
+/** A key's limits as the CLI prints them: snake_case, as the API names them. */
+function apiKeyLimitsJson(limits) {
+    return {
+        ...(limits.maxHolds !== undefined ? { max_holds: limits.maxHolds } : {}),
+        ...(limits.maxHeldHours !== undefined ? { max_held_hours: limits.maxHeldHours } : {}),
+        ...(limits.requestsPerMinute !== undefined ? { requests_per_minute: limits.requestsPerMinute } : {}),
+        ...(limits.requiresApproval ? { requires_approval: true } : {}),
+    };
+}
+/** `--max-holds`, `--max-held-hours`, `--requests-per-minute`, `--requires-approval` (RFC 0004 A5). */
+function parseKeyLimits(values) {
+    const whole = (option, value, most) => {
+        if (value === undefined)
+            return undefined;
+        const parsed = /^[0-9]{1,7}$/.test(value) ? Number(value) : Number.NaN;
+        if (!Number.isSafeInteger(parsed) || parsed < 1 || parsed > most) {
+            throw new Error(`--${option} must be a whole number from 1 to ${most.toLocaleString('en-US')}`);
+        }
+        return parsed;
+    };
+    const maxHolds = whole('max-holds', values['max-holds'], 10_000);
+    const maxHeldHours = whole('max-held-hours', values['max-held-hours'], 876_000);
+    const requestsPerMinute = whole('requests-per-minute', values['requests-per-minute'], 100_000);
+    return {
+        ...(maxHolds !== undefined ? { maxHolds } : {}),
+        ...(maxHeldHours !== undefined ? { maxHeldHours } : {}),
+        ...(requestsPerMinute !== undefined ? { requestsPerMinute } : {}),
+        ...(values['requires-approval'] === true ? { requiresApproval: true } : {}),
+    };
+}
+/** `--locations` and `--groups`: references, comma-separated; neither for a key of the whole tenant. */
+function parseKeyResourceScope(locations, groups) {
+    if (locations === undefined && groups === undefined)
+        return undefined;
+    const list = (value) => (value ?? '')
+        .split(',')
+        .map((ref) => ref.trim())
+        .filter((ref) => ref !== '');
+    const scope = { locations: list(locations), groups: list(groups) };
+    if (!isSlotlockResourceScope(scope)) {
+        throw new Error('--locations and --groups take up to 20 location or group references each, at least one in all');
+    }
+    return scope;
+}
 /** `--scope`: read, write and admin, comma-separated; read,write unless given. */
 function parseKeyScopes(value) {
     if (value === undefined)
@@ -1169,6 +1779,7 @@ async function maintainTenant(config, caps) {
                 staleSources: 0,
                 noShows: 0,
                 waitlistOffers: 0,
+                approvalsExpired: 0,
                 capped: true,
                 passes: 0,
             };
@@ -1183,6 +1794,7 @@ async function maintainTenant(config, caps) {
                 sum.staleSources += pass.staleSources;
                 sum.noShows += pass.noShows;
                 sum.waitlistOffers += pass.waitlistOffers;
+                sum.approvalsExpired += pass.approvalsExpired;
                 // 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.
@@ -1253,6 +1865,10 @@ Commands:
   resource archive <ref>   Take a resource out of use: no new bookings, holds or events, and
                            no longer listed; what is on it stays
   resource restore <ref>   Put an archived resource back in use
+  resource parent <ref> (<parent-ref> | none)
+                           Make a resource a part of a composite (a room of a hall): booking
+                           the whole then takes every part, and a part's booking keeps the
+                           whole from being booked; none makes it no part
   resource delete <ref>    Delete a resource and its history; refused while a booking, hold
                            or event on it has not ended
   hours show [--resource <ref>]
@@ -1267,13 +1883,63 @@ Commands:
   rules clear --resource <ref>
                            Remove the resource's booking rules
   key create <name> [--scope read,write,admin] [--expires-in-days <n>]
+             [--locations <ref,...>] [--groups <ref,...>]
                            Create an API key for the tenant (default scope read,write, no
                            expiry; admin adds the application API) and print it once; only its
-                           SHA-256 is stored
+                           SHA-256 is stored. With --locations or --groups, the key reaches
+                           only the resources there (each location with those in it), read and
+                           write only
+             [--max-holds <n>] [--max-held-hours <n>] [--requests-per-minute <n>]
+             [--requires-approval]
+                           ... and hold the key below the server's limits: its live holds, the
+                           hours they hold, its requests a minute, and every booking it makes
+                           waiting for a person (the dashboard's Approvals)
+  key limits <id> [--max-holds <n>] [--max-held-hours <n>] [--requests-per-minute <n>]
+             [--requires-approval]
+                           Replace an active key's limits; none at all gives it the server's
   key list                 Print the tenant's API keys, one JSON object per line
   key rotate <id>          Give an active key a new secret and print it once; the old one stops
                            working at once, and the key keeps its id and what it booked
   key revoke <id>          Revoke one of the tenant's API keys at once
+  sandbox seed <car-rental|clinic|desks>
+                           Fill an empty test environment (SLOTLOCK_TENANT=<tenant>~test) with a
+                           scenario: locations, groups, resources, hours, rules and bookings
+  sandbox reset            Empty the test environment; its keys, webhooks and plan stay
+  sandbox fast-forward <minutes>
+                           Make what would lapse in the test environment within that time lapse
+                           now (holds, offers, approvals), then run maintenance
+  sandbox race <resource-ref> [--agents <n>] [--start <date-time>]
+                           Race agents (default 100) for one hour on a test resource and print who
+                           booked, who was refused and why, and how long the answers took
+  partner create <id> <name> --contract <json | @file>
+                           Create a partner reselling Slotlock, or change its name and contract:
+                           its plans (limits and quotas), its accounts' key scopes and its prices
+                           (as the schema owner, SLOTLOCK_MIGRATE_DATABASE_URL)
+  partner list             Print the partners, one JSON object per line
+  partner suspend <id>     Suspend a partner: every account with it, and its keys stop
+  partner unsuspend <id>   Make a suspended partner active again
+  partner key <id> <name>  Create a partner key (slk_partner_…) and print it once
+  partner revoke-key <id> <key-id>
+                           Revoke one of a partner's keys at once
+  partner customer <id> <cus_…>
+                           The Stripe customer its monthly invoice goes to
+  partner webhook <id> <https-url>
+                           Where usage.period_closed goes; prints its signing secret once
+  billing daily            Once a day (cron), as the schema owner: close last month for every
+                           active partner once it has been over for 6 hours, report overage
+                           when SLOTLOCK_OVERAGE is on (with STRIPE_SECRET_KEY), and list the
+                           partners' reconciliation mismatches of the last 7 days; exits 1 when
+                           anything waits or differs. Safe to run again
+  overage report [--month <YYYY-MM>] [--event <name>]
+                           With SLOTLOCK_OVERAGE: send Stripe each paying Developer tenant's
+                           operations above its quota this month (or --month) not yet sent, as
+                           Billing Meter events (--event, default slotlock_operations), once
+                           (as the schema owner, with STRIPE_SECRET_KEY)
+  partner close <id> [--month <YYYY-MM>]
+                           Close an ended month (default: last month): price its accounts' use
+                           with the contract, record the lines once, send usage.period_closed,
+                           and with STRIPE_SECRET_KEY add the lines to the partner's next Stripe
+                           invoice; safe to run again
   tenant status            Print whether the tenant is suspended
   tenant suspend [--reason <text>]
                            Suspend the tenant: it may read, and writes nothing; its keys get
@@ -1282,7 +1948,13 @@ Commands:
   tenant unsuspend         Lift the tenant's suspension (as the schema owner, likewise)
   tenant erase --confirm <tenant>
                            Delete everything the tenant has, its API keys included, for good;
-                           --confirm repeats SLOTLOCK_TENANT
+                           --confirm repeats SLOTLOCK_TENANT; refused while its hosted plan is
+                           paid for (cancel the subscription first)
+  plan status              Print the deployment's default plan and the tenant's own (hosted)
+  plan default (free | developer | none) [--from <date>]
+                           Put every tenant without a plan of its own on this one from --from
+                           (an ISO date or time; default now), or none for no default; a new
+                           tenant gets it at once (as the schema owner, like tenant suspend)
   healthcheck              Exit 0 when the local server reports ready
 
 Options:
@@ -1312,6 +1984,16 @@ Environment:
   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_USAGE                 on: count each tenant's operations, bookings and holds by day, API
+                                 key and surface (slotlock.usage_daily, kept 400 days); off
+                                 (default): record nothing
+  SLOTLOCK_QUOTAS                on (needs SLOTLOCK_USAGE=on): refuse a tenant on a plan past its
+                                 operations or bookings this month (quota_exceeded, 429); off
+                                 (default): no quota
+  SLOTLOCK_OVERAGE               off (default), or on (300) or a percent (111-1000): a paying
+                                 Developer tenant is refused only past that share of its
+                                 operations, and the rest above its quota is billed (overage
+                                 report); needs SLOTLOCK_QUOTAS=on
   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
@@ -1342,6 +2024,14 @@ Environment:
   SLOTLOCK_TRUSTED_PROXY_SECRET  A secret the proxy adds to every request in x-slotlock-proxy-proof,
                                  32+ random characters: without it there, the field above is
                                  ignored and the connection's address counts
+  SLOTLOCK_KNOWN_CLIENTS         Comma-separated integrator names /metrics counts requests by, from
+                                 their Slotlock-Client field (any other: other; none sent: none)
+  OTEL_EXPORTER_OTLP_ENDPOINT    An OpenTelemetry collector (OTLP over HTTP, JSON): a span per
+                                 call is sent to <endpoint>/v1/traces (off without it)
+  OTEL_EXPORTER_OTLP_TRACES_ENDPOINT The full traces URL instead of <endpoint>/v1/traces
+  OTEL_EXPORTER_OTLP_METRICS_ENDPOINT The full metrics URL instead of <endpoint>/v1/metrics (sent each minute)
+  OTEL_EXPORTER_OTLP_HEADERS     name=value pairs sent with each export, such as an API key
+  OTEL_SERVICE_NAME              service.name of the spans (default slotlock)
   SLOTLOCK_GITHUB_CLIENT_ID      Serve the dashboard at $SLOTLOCK_PUBLIC_URL/dashboard: the Client ID
                                  of a GitHub OAuth app with callback .../dashboard/callback
   SLOTLOCK_GITHUB_CLIENT_SECRET  That app's client secret (dashboard)
@@ -1349,13 +2039,24 @@ Environment:
   SLOTLOCK_ASSISTANT_SECRET      Turns on the dashboard assistant and seals each organization's
                                  model API key with it, 32+ random characters (dashboard; off
                                  without it)
+  SLOTLOCK_ASSISTANT_PREVIOUS_SECRETS Up to three earlier SLOTLOCK_ASSISTANT_SECRET values,
+                                 comma-separated, newest first: keys sealed under one still open
+                                 and are sealed again under the current secret when next used
   SLOTLOCK_ASSISTANT_PRIVATE_URLS off (default): refuse an assistant model URL whose host is, or
                                  resolves to, a loopback, private, link-local, CGNAT, unique-local
                                  or metadata address; on: allow them, for a self-hosted model
                                  (Ollama, vLLM) on this machine or network
-  SLOTLOCK_DASHBOARD_USERS       * or comma-separated GitHub user ids that may sign in and whose keys work
-  SLOTLOCK_DASHBOARD_ORGS        comma-separated GitHub organization ids: each is one shared tenant
+  SLOTLOCK_GOOGLE_CLIENT_ID      Sign-in with Google too: the client id of a Google OAuth client with
+                                 redirect URI .../dashboard/callback (not with organization ids)
+  SLOTLOCK_GOOGLE_CLIENT_SECRET  Its client secret
+  SLOTLOCK_DASHBOARD_USERS       * or comma-separated GitHub user ids (and google:<subject>) that may sign in and whose keys work
+  SLOTLOCK_DASHBOARD_ORGS        comma-separated GitHub organization ids: each is one shared tenant;
+                                 or enabled: each person's own tenant, plus the organizations an
+                                 owner turns on from the dashboard's Teams page
   SLOTLOCK_DASHBOARD_NAME        What the dashboard calls this deployment (default Slotlock)
+  SLOTLOCK_DASHBOARD_TERMS_URL   https URL of the terms people accept by signing in, linked on the
+                                 sign-in page (none named without it)
+  SLOTLOCK_DASHBOARD_PRIVACY_URL https URL of the privacy notice the sign-in page links
   HOST                           Listen address (default 127.0.0.1)
   PORT                           Listen port (default 8080)
 
@@ -1396,7 +2097,12 @@ export async function runSlotlockCli(argv, io) {
         command === 'key' ||
         command === 'hours' ||
         command === 'rules' ||
-        command === 'tenant'
+        command === 'tenant' ||
+        command === 'plan' ||
+        command === 'partner' ||
+        command === 'overage' ||
+        command === 'billing' ||
+        command === 'sandbox'
         ? `${command} ${operands[0] ?? ''}`.trim()
         : command;
     const expectedOperands = {
@@ -1407,21 +2113,40 @@ export async function runSlotlockCli(argv, io) {
         'resource add': 2,
         'resource list': 1,
         'resource archive': 2,
+        'resource parent': 3,
         'resource restore': 2,
         'resource delete': 2,
         'tenant status': 1,
         'tenant suspend': 1,
         'tenant unsuspend': 1,
         'tenant erase': 1,
+        'plan status': 1,
+        'plan default': 2,
         'key create': 2,
         'key list': 1,
         'key rotate': 2,
         'key revoke': 2,
+        'key limits': 2,
+        'sandbox seed': 2,
+        'sandbox reset': 1,
+        'sandbox fast-forward': 2,
+        'sandbox race': 2,
         'hours show': 1,
         'hours set': 2,
         'hours clear': 1,
         'rules set': 2,
         'rules clear': 1,
+        'partner create': 3,
+        'partner list': 1,
+        'partner suspend': 2,
+        'partner unsuspend': 2,
+        'partner key': 3,
+        'partner revoke-key': 3,
+        'partner customer': 3,
+        'partner webhook': 3,
+        'partner close': 2,
+        'overage report': 1,
+        'billing daily': 1,
     };
     const expected = expectedOperands[subcommand];
     if (expected === undefined)
@@ -1438,12 +2163,45 @@ export async function runSlotlockCli(argv, io) {
             return usage(`--${option} applies only to key create`);
         }
     }
+    if (values.month !== undefined && subcommand !== 'partner close' && subcommand !== 'overage report') {
+        return usage('--month applies only to partner close and overage report');
+    }
+    if (values.event !== undefined && subcommand !== 'overage report') {
+        return usage('--event applies only to overage report');
+    }
+    if (values.month !== undefined && !/^\d{4}-(0[1-9]|1[0-2])$/.test(values.month)) {
+        return usage('--month must be a month, like 2026-10');
+    }
+    if (values.contract !== undefined && subcommand !== 'partner create') {
+        return usage('--contract applies only to partner create');
+    }
+    if (subcommand === 'partner create' && values.contract === undefined) {
+        return usage('partner create needs --contract <json>, or --contract @<file>');
+    }
     if (values.reason !== undefined && subcommand !== 'tenant suspend') {
         return usage('--reason applies only to tenant suspend');
     }
     if (values.confirm !== undefined && subcommand !== 'tenant erase') {
         return usage('--confirm applies only to tenant erase');
     }
+    if (values.from !== undefined && subcommand !== 'plan default') {
+        return usage('--from applies only to plan default');
+    }
+    let planDefault = null;
+    if (subcommand === 'plan default') {
+        const named = operands[1];
+        if (named !== 'free' && named !== 'developer' && named !== 'none') {
+            return usage('plan default takes free, developer or none');
+        }
+        if (named === 'none' && values.from !== undefined)
+            return usage('--from applies only to a plan');
+        const appliesFrom = values.from === undefined ? new Date() : new Date(values.from);
+        if (Number.isNaN(appliesFrom.getTime()) || !/^\d{4}-\d{2}-\d{2}/.test(values.from ?? '2000-01-01')) {
+            return usage('--from must be an ISO date or time, like 2026-12-09 or 2026-12-09T00:00:00Z');
+        }
+        if (named !== 'none')
+            planDefault = { plan: named, appliesFrom };
+    }
     if (subcommand === 'tenant erase' && values.confirm === undefined) {
         return usage('tenant erase needs --confirm <tenant>, the tenant it erases (SLOTLOCK_TENANT)');
     }
@@ -1491,15 +2249,36 @@ export async function runSlotlockCli(argv, io) {
     }
     let keyScopes = [];
     let keyLifetimeDays;
+    let keyResourceScope;
+    let keyLimits = {};
     if (subcommand === 'key create') {
         try {
             keyScopes = parseKeyScopes(values.scope);
             keyLifetimeDays = parseKeyLifetime(values['expires-in-days']);
+            keyResourceScope = parseKeyResourceScope(values.locations, values.groups);
+        }
+        catch (error) {
+            return usage(error.message);
+        }
+    }
+    else if (values.locations !== undefined || values.groups !== undefined) {
+        return usage('--locations and --groups are for key create');
+    }
+    if ((values.agents !== undefined || values.start !== undefined) && subcommand !== 'sandbox race') {
+        return usage('--agents and --start apply only to sandbox race');
+    }
+    const limitOptions = ['max-holds', 'max-held-hours', 'requests-per-minute', 'requires-approval'];
+    if (subcommand === 'key create' || subcommand === 'key limits') {
+        try {
+            keyLimits = parseKeyLimits(values);
         }
         catch (error) {
             return usage(error.message);
         }
     }
+    else if (limitOptions.some((option) => values[option] !== undefined)) {
+        return usage('--max-holds, --max-held-hours, --requests-per-minute and --requires-approval are for key create and key limits');
+    }
     const log = createLogger(io);
     try {
         switch (subcommand) {
@@ -1528,6 +2307,11 @@ export async function runSlotlockCli(argv, io) {
                 io.stdout.write(`${JSON.stringify(result)}\n`);
                 return 0;
             }
+            case 'sandbox seed':
+            case 'sandbox reset':
+            case 'sandbox fast-forward':
+            case 'sandbox race':
+                return await runSandboxCommand(subcommand, operands, values, io);
             case 'resource add': {
                 const config = readSlotlockDatabaseConfig(io.env);
                 const resource = await addResource(config, operands[1], values.timezone ?? 'UTC');
@@ -1537,6 +2321,78 @@ export async function runSlotlockCli(argv, io) {
             case 'resource list':
                 await listResources(readSlotlockDatabaseConfig(io.env), io.stdout);
                 return 0;
+            case 'billing daily': {
+                const database = readSlotlockDatabaseConfig(io.env);
+                const owner = connect(database.migrateDatabaseUrl ?? database.databaseUrl, 1);
+                try {
+                    return await runBillingDaily(owner, io, {
+                        now: Date.now(),
+                        stripeSecretKey: io.env.STRIPE_SECRET_KEY?.trim() || undefined,
+                        overage: (io.env.SLOTLOCK_OVERAGE?.trim() || 'off') !== 'off',
+                    });
+                }
+                catch (error) {
+                    if (error?.code === '42501') {
+                        io.stderr.write('slotlock: only the schema owner runs billing; set SLOTLOCK_MIGRATE_DATABASE_URL to its URL\n');
+                        return 1;
+                    }
+                    throw error;
+                }
+                finally {
+                    await owner.end({ timeout: 5 });
+                }
+            }
+            case 'overage report': {
+                const secretKey = io.env.STRIPE_SECRET_KEY?.trim();
+                if (!secretKey) {
+                    io.stderr.write('slotlock: overage report needs STRIPE_SECRET_KEY, with write access to meter events\n');
+                    return 1;
+                }
+                const database = readSlotlockDatabaseConfig(io.env);
+                const owner = connect(database.migrateDatabaseUrl ?? database.databaseUrl, 1);
+                try {
+                    const report = await reportSlotlockOverage(owner, {
+                        month: values.month ?? slotlockMonthOf(Date.now()),
+                        stripe: { secretKey, eventName: values.event ?? 'slotlock_operations' },
+                    });
+                    io.stdout.write(`${JSON.stringify({ month: report.month, tenants: report.tenants.length, sent: report.sent, failed: report.failed })}\n`);
+                    if (report.failed > 0) {
+                        io.stderr.write('slotlock: Stripe did not take some events; run overage report again\n');
+                        return 1;
+                    }
+                    return 0;
+                }
+                catch (error) {
+                    const code = error?.code;
+                    if (code === 'invalid_meter_event' || code === 'invalid_month') {
+                        io.stderr.write(`slotlock: ${error.message}\n`);
+                        return 2;
+                    }
+                    if (code === '42501') {
+                        io.stderr.write('slotlock: only the schema owner reports overage; set SLOTLOCK_MIGRATE_DATABASE_URL to its URL\n');
+                        return 1;
+                    }
+                    throw error;
+                }
+                finally {
+                    await owner.end({ timeout: 5 });
+                }
+            }
+            case 'resource parent': {
+                const changed = await setResourceParent(readSlotlockDatabaseConfig(io.env), io.stdout, operands[1], operands[2]);
+                if (changed === true)
+                    return 0;
+                io.stderr.write(`slotlock: ${changed === false
+                    ? 'no resource with that reference or id in this tenant'
+                    : changed === 'parent_not_found'
+                        ? 'no parent resource with that reference or id in this tenant'
+                        : changed === 'composite_busy'
+                            ? 'one side has a booking or live hold still to come; a composite changes only while neither does'
+                            : changed === 'composite_too_deep'
+                                ? 'composites are one level deep: a part has no parts, and a parent is no part'
+                                : 'a composite has at most 50 parts'}\n`);
+                return 1;
+            }
             case 'resource archive':
             case 'resource restore':
             case 'resource delete': {
@@ -1572,6 +2428,53 @@ export async function runSlotlockCli(argv, io) {
                     if (code === 'invalid_suspension_reason') {
                         return usage('--reason must be 1-500 characters without control characters');
                     }
+                    if (code === 'billing_active') {
+                        io.stderr.write('slotlock: the tenant has a live subscription; cancel it in Stripe first (its webhook moves the tenant to Free), then erase\n');
+                        return 1;
+                    }
+                    throw error;
+                }
+                return 0;
+            }
+            case 'partner create':
+            case 'partner list':
+            case 'partner suspend':
+            case 'partner unsuspend':
+            case 'partner key':
+            case 'partner revoke-key':
+            case 'partner customer':
+            case 'partner webhook':
+            case 'partner close': {
+                try {
+                    return await runPartnerCommand(readSlotlockDatabaseConfig(io.env), io, subcommand.slice('partner '.length), operands.slice(1), values.contract, { month: values.month, stripeSecretKey: io.env.STRIPE_SECRET_KEY?.trim() || undefined });
+                }
+                catch (error) {
+                    const code = error?.code;
+                    if (code === 'partner_not_found') {
+                        io.stderr.write('slotlock: no partner with that id\n');
+                        return 1;
+                    }
+                    if (code === 'invalid_partner_contract' || code === 'invalid_partner' || code === 'month_not_ended' || code === 'invalid_month') {
+                        io.stderr.write(`slotlock: ${error.message}\n`);
+                        return 2;
+                    }
+                    if (code === '42501') {
+                        io.stderr.write('slotlock: only the schema owner runs partner commands; set SLOTLOCK_MIGRATE_DATABASE_URL to its URL\n');
+                        return 1;
+                    }
+                    throw error;
+                }
+            }
+            case 'plan status':
+            case 'plan default': {
+                try {
+                    await runPlanCommand(readSlotlockDatabaseConfig(io.env), io.stdout, planDefault, subcommand === 'plan default');
+                }
+                catch (error) {
+                    if (error?.code === 'plan_default_not_permitted') {
+                        io.stderr.write('slotlock: only the schema owner sets the default plan; set SLOTLOCK_MIGRATE_DATABASE_URL to its URL\n');
+                        return 1;
+                    }
                     throw error;
                 }
                 return 0;
@@ -1607,6 +2510,8 @@ export async function runSlotlockCli(argv, io) {
                     name: operands[1],
                     scopes: keyScopes,
                     createdBy: CLI_KEY_CREATOR,
+                    ...(keyResourceScope ? { resourceScope: keyResourceScope } : {}),
+                    ...(Object.keys(keyLimits).length > 0 ? { limits: keyLimits } : {}),
                     ...(keyLifetimeDays !== undefined
                         ? { expiresAt: new Date(Date.now() + keyLifetimeDays * DAY_MS) }
                         : {}),
@@ -1633,6 +2538,17 @@ export async function runSlotlockCli(argv, io) {
                 io.stderr.write('slotlock: the new key is shown once and the old one no longer works; keep it in a secret manager\n');
                 return 0;
             }
+            case 'key limits': {
+                const config = readSlotlockDatabaseConfig(io.env);
+                const id = operands[1];
+                const set = await withApiKeys(config, (keys) => keys.setLimits({ tenantRef: config.tenantRef, id, limits: keyLimits }));
+                if (!set) {
+                    io.stderr.write('slotlock: no active API key with that id in this tenant\n');
+                    return 1;
+                }
+                io.stdout.write(`${JSON.stringify({ id, limits: apiKeyLimitsJson(keyLimits) })}\n`);
+                return 0;
+            }
             case 'key revoke': {
                 const config = readSlotlockDatabaseConfig(io.env);
                 const revoked = await withApiKeys(config, (keys) => keys.revoke({ tenantRef: config.tenantRef, id: operands[1], actor: CLI_KEY_CREATOR }));
@@ -1666,10 +2582,22 @@ function parseCliArguments(argv) {
             timezone: { type: 'string' },
             scope: { type: 'string' },
             'expires-in-days': { type: 'string' },
+            locations: { type: 'string' },
+            groups: { type: 'string' },
+            'max-holds': { type: 'string' },
+            'max-held-hours': { type: 'string' },
+            'requests-per-minute': { type: 'string' },
+            'requires-approval': { type: 'boolean' },
+            agents: { type: 'string' },
+            start: { type: 'string' },
+            contract: { type: 'string' },
+            month: { type: 'string' },
+            event: { type: 'string' },
             resource: { type: 'string' },
             all: { type: 'boolean' },
             reason: { type: 'string' },
             confirm: { type: 'string' },
+            from: { type: 'string' },
             help: { type: 'boolean', short: 'h' },
             version: { type: 'boolean', short: 'v' },
         },