slotlock 0.8.0 → 0.9.0

package/package.json

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

package/ranges.d.ts

@@ -0,0 +1,28 @@
+import { type SlotlockBookingRules } from './booking-rules.js';
+import { type SlotlockRankedException } from './hours.js';
+import type { Interval, WeeklyAvailabilityRule } from './types.js';
+/** Candidates one resource's search judges before it gives up. */
+export declare const SLOTLOCK_MAX_RANGE_CANDIDATES = 5000;
+export interface SlotlockRangeSearch {
+    /** Occupied time on the resource (other bookings with their buffers). */
+    busy: readonly Interval[];
+    rules: SlotlockBookingRules | undefined;
+    timezone: string;
+    hours: readonly WeeklyAvailabilityRule[];
+    exceptions?: readonly SlotlockRankedException[];
+    now: Date;
+    /** The start lies from `pickup.start` to `pickup.end`, both included. */
+    pickup: Interval;
+    /** The end lies from `return.start` to `return.end`, both included (or give `days`). */
+    return?: Interval;
+    /** The end is the start's local time this many days later. */
+    days?: number;
+}
+/** The instant `days` local days after `instant`, at the same wall time (a clock change moves it). */
+export declare function sameTimeDaysLater(instant: Date, days: number, timezone: string): Date;
+/**
+ * The earliest range the search allows, or null. Search honours hours always, as slot search does:
+ * a range from one local day to another starts and ends inside the hours, one within a day lies
+ * inside them. Bounded by SLOTLOCK_MAX_RANGE_CANDIDATES judged candidates.
+ */
+export declare function findEarliestRange(search: SlotlockRangeSearch): Interval | null;

package/ranges.js

@@ -0,0 +1,135 @@
+// Hires across days (RFC 0004 B3): the earliest range on one resource that starts in a pick-up
+// window and ends a number of local days later, or in a return window, free throughout with its
+// buffers and allowed by the resource's booking rules. Pure: the caller reads the busy time, the
+// hours and the exceptions; the booking rules' own judge decides each candidate.
+import { bookingBufferAfterMs, bookingBufferBeforeMs, bookingRuleBroken, hoursApplyOf, isMultiDay, nextStepStart, withinDayWindows, } from './booking-rules.js';
+import { mergeIntervals } from './engine.js';
+import { openWindows } from './hours.js';
+import { createTimeZoneConverter, zonedOffsetMinutes } from './timezone.js';
+const MINUTE_MS = 60_000;
+const DAY_MS = 86_400_000;
+/** Candidates one resource's search judges before it gives up. */
+export const SLOTLOCK_MAX_RANGE_CANDIDATES = 5_000;
+/** The instant `days` local days after `instant`, at the same wall time (a clock change moves it). */
+export function sameTimeDaysLater(instant, days, timezone) {
+    const offset = zonedOffsetMinutes(instant, timezone) * MINUTE_MS;
+    return createTimeZoneConverter(timezone).wallFrameToUtc(instant.getTime() + offset + days * DAY_MS);
+}
+/**
+ * The earliest range the search allows, or null. Search honours hours always, as slot search does:
+ * a range from one local day to another starts and ends inside the hours, one within a day lies
+ * inside them. Bounded by SLOTLOCK_MAX_RANGE_CANDIDATES judged candidates.
+ */
+export function findEarliestRange(search) {
+    const { timezone, now } = search;
+    // Judged as a write is, inside the hours always: as the write is held to them where it is
+    // (enforceHours), else at a hire's start and end, what a hire needs.
+    const rules = {
+        ...(search.rules ?? {}),
+        enforceHours: true,
+        hoursApply: search.rules?.hoursApply ?? (search.rules?.enforceHours === true ? hoursApplyOf(search.rules) : 'ends'),
+    };
+    const before = bookingBufferBeforeMs(rules);
+    const after = bookingBufferAfterMs(rules);
+    const busy = mergeIntervals([...search.busy]);
+    const lastEnd = search.return
+        ? search.return.end.getTime()
+        : sameTimeDaysLater(search.pickup.end, search.days ?? 1, timezone).getTime() + DAY_MS;
+    const open = openWindows({
+        hours: search.hours,
+        ...(search.exceptions ? { exceptions: search.exceptions } : {}),
+        timezone,
+        window: { start: new Date(search.pickup.start.getTime() - DAY_MS), end: new Date(lastEnd + DAY_MS) },
+    });
+    const isOpen = (instant, closed = false) => open.some((part) => part.start.getTime() <= instant && (closed ? instant <= part.end.getTime() : instant < part.end.getTime()));
+    const nextOpen = (instant) => open.find((part) => part.end.getTime() > instant)?.start.getTime() ?? null;
+    const step = rules.slotStepMinutes;
+    const offset = step === undefined ? 0 : (rules.stepOffsetMinutes ?? 0) % step;
+    const align = (instant) => step === undefined
+        ? Math.ceil(instant / MINUTE_MS) * MINUTE_MS
+        : nextStepStart(new Date(instant), step, timezone, offset).getTime();
+    const earliest = Math.max(search.pickup.start.getTime(), now.getTime() + (rules.minNoticeMinutes ?? 0) * MINUTE_MS);
+    const latest = Math.min(search.pickup.end.getTime(), rules.maxAdvanceDays === undefined ? Number.POSITIVE_INFINITY : now.getTime() + rules.maxAdvanceDays * DAY_MS);
+    const blocker = (start, end) => busy.find((taken) => taken.start.getTime() < end + after && taken.end.getTime() > start - before);
+    /** The earliest end in the return window a range from `start` may have, or null. */
+    const endFor = (start) => {
+        if (search.days !== undefined)
+            return sameTimeDaysLater(new Date(start), search.days, timezone).getTime();
+        const window = search.return;
+        const lengths = rules.allowedDurations;
+        if (lengths) {
+            for (const minutes of lengths) {
+                const end = start + minutes * MINUTE_MS;
+                if (end >= window.start.getTime() && end <= window.end.getTime() && returnable(start, end))
+                    return end;
+            }
+            return null;
+        }
+        let end = Math.max(window.start.getTime(), start + Math.max(1, rules.minDurationMinutes ?? 1) * MINUTE_MS);
+        end = Math.ceil(end / MINUTE_MS) * MINUTE_MS;
+        for (let tries = 0; end <= window.end.getTime() && tries < 3 * 1_440; tries++) {
+            if (rules.maxDurationMinutes !== undefined && end - start > rules.maxDurationMinutes * MINUTE_MS)
+                return null;
+            if (returnable(start, end))
+                return end;
+            // On to the next return time or opening, else the next minute.
+            const reopening = isOpen(end, true) ? null : nextOpen(end);
+            end = reopening !== null && reopening > end ? reopening : end + MINUTE_MS;
+        }
+        return null;
+    };
+    /** Whether a range may end at `end`: inside the hours at its end, and in a return time for a hire. */
+    const returnable = (start, end) => isOpen(end, true) &&
+        (!rules.returnTimes ||
+            !isMultiDay({ start: new Date(start), end: new Date(end) }, timezone) ||
+            withinDayWindows(new Date(end), rules.returnTimes, timezone, true));
+    /** The next start of a pick-up time at or after `instant`, by the local clock. */
+    const nextPickup = (instant) => {
+        const windows = rules.pickupTimes ?? [];
+        const local = ((((instant + zonedOffsetMinutes(new Date(instant), timezone) * MINUTE_MS) / MINUTE_MS) % 1_440) + 1_440) % 1_440;
+        const ahead = Math.min(...windows.map((window) => (((window.startMinutes - local) % 1_440) + 1_440) % 1_440));
+        return instant + Math.max(1, Math.round(ahead)) * MINUTE_MS;
+    };
+    let candidate = align(earliest);
+    for (let judged = 0; candidate <= latest && judged < SLOTLOCK_MAX_RANGE_CANDIDATES; judged++) {
+        // Start inside the hours, and inside a pick-up time.
+        if (!isOpen(candidate)) {
+            const reopening = nextOpen(candidate);
+            if (reopening === null)
+                return null;
+            candidate = align(Math.max(reopening, candidate + 1));
+            continue;
+        }
+        const end = endFor(candidate);
+        if (end !== null &&
+            rules.pickupTimes &&
+            isMultiDay({ start: new Date(candidate), end: new Date(end) }, timezone) &&
+            !withinDayWindows(new Date(candidate), rules.pickupTimes, timezone)) {
+            candidate = align(nextPickup(candidate));
+            continue;
+        }
+        if (end !== null && end > candidate) {
+            const taken = blocker(candidate, end);
+            if (taken) {
+                candidate = align(Math.max(taken.end.getTime() + before, candidate + 1));
+                continue;
+            }
+            const range = { start: new Date(candidate), end: new Date(end) };
+            if (bookingRuleBroken({
+                rules,
+                timezone,
+                hours: search.hours,
+                ...(search.exceptions ? { exceptions: search.exceptions } : {}),
+                interval: range,
+                now,
+            }) === null) {
+                return range;
+            }
+        }
+        else if (search.return && candidate + (rules.minDurationMinutes ?? 0) * MINUTE_MS > search.return.end.getTime()) {
+            return null;
+        }
+        candidate = align(candidate + MINUTE_MS);
+    }
+    return null;
+}

package/resource-search.d.ts

@@ -0,0 +1,19 @@
+import type { SlotlockResource } from './types.js';
+/** The longest search, and the most words one may have once read. */
+export declare const SLOTLOCK_RESOURCE_SEARCH_MAX = 200;
+/** What a search looks at: a resource as listResources gives it. */
+export type SlotlockSearchableResource = Pick<SlotlockResource, 'id' | 'externalRef' | 'name' | 'description' | 'kind' | 'labels' | 'locationName' | 'location'>;
+/**
+ * A search's words, or `invalid_query` when it is empty, longer than 200 characters or more than 12
+ * words. Filler ("the", "my") is dropped when other words remain.
+ */
+export declare function slotlockResourceSearchWords(query: string): string[];
+/**
+ * The resources that match a search's words, best first, each with its score (0 to 1). A resource is
+ * kept when at least half of the words find it somewhere; one that every word names exactly scores 1.
+ * Ties keep the order the resources were given in.
+ */
+export declare function slotlockSearchResources<T extends SlotlockSearchableResource>(resources: readonly T[], words: readonly string[]): {
+    resource: T;
+    score: number;
+}[];

package/resource-search.js

@@ -0,0 +1,153 @@
+/** The longest search, and the most words one may have once read. */
+export const SLOTLOCK_RESOURCE_SEARCH_MAX = 200;
+const MAX_WORDS = 12;
+/** Words that say nothing about which resource is meant, when others do. */
+const FILLER = new Set(['the', 'a', 'an', 'my', 'our', 'your', 'of', 'for', 'at', 'in', 'on', 'to', 'and', 'with']);
+/** Lower case, accents and other marks taken off: "Zürich" reads as "zurich". */
+const fold = (text) => text.normalize('NFKD').replace(/\p{M}+/gu, '').toLowerCase();
+const wordsOf = (text) => fold(text).split(/[^\p{L}\p{N}]+/u).filter((word) => word !== '');
+/**
+ * A search's words, or `invalid_query` when it is empty, longer than 200 characters or more than 12
+ * words. Filler ("the", "my") is dropped when other words remain.
+ */
+export function slotlockResourceSearchWords(query) {
+    const trimmed = typeof query === 'string' ? query.trim() : '';
+    if (trimmed === '' || [...trimmed].length > SLOTLOCK_RESOURCE_SEARCH_MAX)
+        throw invalidQuery();
+    // Counted as written: repeating a word does not make room for more.
+    const written = wordsOf(trimmed);
+    if (written.length > MAX_WORDS)
+        throw invalidQuery();
+    const words = [...new Set(written)];
+    const meaningful = words.filter((word) => !FILLER.has(word));
+    // Only symbols ("%", "#"): looked for as written.
+    if (words.length === 0)
+        return [fold(trimmed)];
+    return meaningful.length > 0 ? meaningful : words;
+}
+function invalidQuery() {
+    return Object.assign(new Error(`Slotlock resource search must be 1-${String(SLOTLOCK_RESOURCE_SEARCH_MAX)} characters of at most ${String(MAX_WORDS)} words`), { code: 'invalid_query' });
+}
+/** Edits between two words (a swap of neighbours is one), or more than `most` once past it. */
+function distance(a, b, most) {
+    if (Math.abs(a.length - b.length) > most)
+        return most + 1;
+    let before = [];
+    let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+    for (let i = 1; i <= a.length; i += 1) {
+        const current = [i];
+        let smallest = i;
+        for (let j = 1; j <= b.length; j += 1) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            let value = Math.min(previous[j] + 1, current[j - 1] + 1, previous[j - 1] + cost);
+            if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+                value = Math.min(value, before[j - 2] + 1);
+            }
+            current[j] = value;
+            smallest = Math.min(smallest, value);
+        }
+        if (smallest > most)
+            return most + 1;
+        before = previous;
+        previous = current;
+    }
+    return previous[b.length];
+}
+const DIGITS = /^\p{N}+$/u;
+/**
+ * The most edit distances one search computes: past it, matching is exact, by prefix and by words
+ * run together only. A tenant's resources (up to 5,000, each with a long description) cannot make
+ * one search cost seconds.
+ */
+const FUZZY_BUDGET = 20_000;
+/** A description is looked through by its first words only. */
+const DESCRIPTION_WORDS = 60;
+/**
+ * How well one word of a search names a field (0 to 1), given the field's words and those run
+ * together. Typos are forgiven only where `fuzzy`, and only while `budget` lasts.
+ */
+function wordScore(word, field, fuzzy, budget) {
+    let best = 0;
+    for (const candidate of field.words) {
+        if (candidate === word)
+            return 1;
+        if (word.length >= 2 && candidate.startsWith(word))
+            best = Math.max(best, 0.85);
+    }
+    // "mercedesbenz" for "Mercedes-Benz", "car17" for "car-17".
+    if (word.length >= 3 && field.joined.includes(word))
+        best = Math.max(best, 0.75);
+    if (fuzzy && best < 0.7 && !DIGITS.test(word) && word.length >= 4 && word.length <= 24) {
+        const most = word.length >= 8 ? 2 : 1;
+        for (const candidate of field.words) {
+            if (DIGITS.test(candidate) || candidate.length > 32)
+                continue;
+            if (budget.left <= 0)
+                break;
+            budget.left -= 2;
+            const edits = distance(word, candidate, most);
+            if (edits <= most)
+                best = Math.max(best, edits === 1 ? 0.7 : 0.6);
+            // A typo in a word cut short: "merced" for "mercedes" is a prefix; "mercad" is one edit off one.
+            if (candidate.length > word.length && distance(word, candidate.slice(0, word.length), 1) <= 1) {
+                best = Math.max(best, 0.6);
+            }
+        }
+    }
+    return best;
+}
+/** How much a match in each field counts (a name most, a description least), and whether typos are forgiven there. */
+const FIELDS = [
+    ['name', 1, true],
+    ['ref', 0.95, true],
+    ['labels', 0.7, true],
+    ['kind', 0.6, true],
+    ['location', 0.6, true],
+    ['description', 0.4, false],
+];
+const indexed = (text, most = Number.POSITIVE_INFINITY) => {
+    const words = text ? wordsOf(text).slice(0, most) : [];
+    return { words, joined: words.join('') };
+};
+/**
+ * The resources that match a search's words, best first, each with its score (0 to 1). A resource is
+ * kept when at least half of the words find it somewhere; one that every word names exactly scores 1.
+ * Ties keep the order the resources were given in.
+ */
+export function slotlockSearchResources(resources, words) {
+    if (words.length === 0)
+        return [];
+    const budget = { left: FUZZY_BUDGET };
+    const scored = [];
+    resources.forEach((resource, at) => {
+        const fields = {
+            name: indexed(resource.name),
+            ref: indexed(resource.externalRef),
+            labels: indexed(resource.labels?.join(' ')),
+            kind: indexed(resource.kind),
+            location: indexed(resource.locationName ?? resource.location),
+            description: indexed(resource.description, DESCRIPTION_WORDS),
+        };
+        let total = 0;
+        let found = 0;
+        for (const word of words) {
+            let best = 0;
+            for (const [field, weight, fuzzy] of FIELDS)
+                best = Math.max(best, weight * wordScore(word, fields[field], fuzzy, budget));
+            // A search of symbols only ("%"): looked for as written in the name and reference.
+            if (best === 0 && !/[\p{L}\p{N}]/u.test(word)) {
+                if (fold(`${resource.name ?? ''} ${resource.externalRef ?? ''}`).includes(word))
+                    best = 1;
+            }
+            total += best;
+            if (best >= 0.3)
+                found += 1;
+        }
+        const score = total / words.length;
+        if (found * 2 >= words.length && score >= 0.3)
+            scored.push({ resource, score, at });
+    });
+    return scored
+        .sort((a, b) => b.score - a.score || a.at - b.at)
+        .map(({ resource, score }) => ({ resource, score: Math.round(score * 100) / 100 }));
+}

package/rest-api.js

@@ -14,7 +14,14 @@ export const SLOTLOCK_REST_ROUTES = Object.freeze([
         operation: 'slotlock_find_available_slots',
         refusals: [404],
     },
+    {
+        method: 'GET',
+        path: '/v1/available-ranges',
+        operation: 'slotlock_find_available_ranges',
+        refusals: [404, 409],
+    },
     { method: 'POST', path: '/v1/slot-holds', operation: 'slotlock_hold_slots', refusals: [409] },
+    { method: 'POST', path: '/v1/slot-holds/together', operation: 'slotlock_hold_together', refusals: [404, 409] },
     { method: 'POST', path: '/v1/bundles', operation: 'slotlock_book_together', refusals: [404, 409] },
     { method: 'POST', path: '/v1/pool-bookings', operation: 'slotlock_book_pool', refusals: [404, 409] },
     {

package/rules.d.ts

@@ -9,6 +9,8 @@ export declare const SLOTLOCK_CALENDAR_HORIZON_DAYS = 367;
  * many days as a rule lasts, so a longer one is skipped, as the hours validator refuses it.
  */
 export declare const SLOTLOCK_MAX_RULE_DURATION_MINUTES = 10080;
+/** The most busy intervals one calendar source may report for one window (RFC 0004 C1). */
+export declare const SLOTLOCK_SOURCE_BUSY_MAX = 5000;
 export declare function invalidWindowError(message?: string): Error & {
     code: 'invalid_window';
 };

package/rules.js

@@ -17,6 +17,8 @@ const MAX_SEARCH_WINDOW_MS = SLOTLOCK_CALENDAR_HORIZON_DAYS * DAY_MS;
  * many days as a rule lasts, so a longer one is skipped, as the hours validator refuses it.
  */
 export const SLOTLOCK_MAX_RULE_DURATION_MINUTES = 10_080;
+/** The most busy intervals one calendar source may report for one window (RFC 0004 C1). */
+export const SLOTLOCK_SOURCE_BUSY_MAX = 5_000;
 export function invalidWindowError(message = 'Slotlock window must contain two finite dates with end > start') {
     return Object.assign(new Error(message), { code: 'invalid_window' });
 }

package/self-host.d.ts

@@ -166,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 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";
+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: its own (null when none) and\n                           what it inherits from its location or the tenant\n  hours set <json> (--resource <ref> | --location <ref> | --all [--override | --matching])\n                           Give one resource, one location or the tenant weekly hours; a\n                           resource without its own inherits its location's, then the\n                           tenant's, then the server's; --override also clears resources'\n                           own hours, --matching only those the same as the tenant's were\n                           or as these (copies 0.8.0 made); [] closes\n  hours clear (--resource <ref> | --location <ref> | --all)\n                           Clear those hours, so they inherit from further up\n  closures list            Print the tenant's closures and special days from yesterday on\n  closures add <first-day> [<last-day>] --label <text> [--open HH:MM-HH:MM]\n               [--resource <ref> | --location <ref>]\n                           Close whole days (YYYY-MM-DD), or with --open give them those hours\n                           instead, everywhere or for one location or resource\n  closures delete <id>     Remove a closure\n  closures import <file> [--resource <ref> | --location <ref>] [--label <calendar name>]\n                           Close the days an iCalendar file of holidays names (each all-day\n                           event, for the next two years); importing the calendar again (by its\n                           name: --label, else its own) updates them and removes those it dropped\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