slotlock 0.2.0 → 0.5.0

package/booking-rules.d.ts

@@ -0,0 +1,84 @@
+import type { Interval, WeeklyAvailabilityRule } from './types.js';
+/**
+ * A resource's booking rules: what a booking made through Slotlock (a hold, a reservation, an
+ * agent's event) must satisfy, and what a search offers. Each is optional; none set is no rule.
+ * Imported calendar events are what happened elsewhere and are not checked.
+ */
+export interface SlotlockBookingRules {
+    /** A booking starts at least this many minutes after it is made: 0-525,600 (a year). */
+    minNoticeMinutes?: number;
+    /** A booking starts at most this many days after it is made: 1-3,660. */
+    maxAdvanceDays?: number;
+    /**
+     * Bookings start on a step of this many minutes from local midnight, in the resource's time zone
+     * (15: on the quarter hour): 1-1,440.
+     */
+    slotStepMinutes?: number;
+    /**
+     * Minutes kept free after each booking made under the rule (cleaning, handover, travel), as its
+     * trailing buffer, so the database refuses a booking that would start inside it: 0-1,440. A
+     * booking made before the rule, or imported, keeps the buffer it has.
+     */
+    turnaroundMinutes?: number;
+    /** A booking lies inside the resource's bookable hours. */
+    enforceHours?: boolean;
+    /**
+     * A booking is claimed (checked in) within this many minutes of its start, or maintenance
+     * releases it for others (and offers it to the waitlist): 1-1,440. Only bookings made once the
+     * rule is set are released.
+     */
+    checkInMinutes?: number;
+    /**
+     * A booking lies in time every calendar sync recording coverage for the resource has read within
+     * the last day (`recordCalendarCoverage`): time a stale or failing sync leaves unproven is
+     * refused (`uncertain`), not booked over what it may hide. A resource no sync covers is certain.
+     */
+    requireCertain?: boolean;
+}
+/** Which rule a write broke, as its refusal names it. */
+export type SlotlockBookingRule = 'min_notice' | 'max_advance' | 'slot_step' | 'outside_hours' | 'uncertain';
+/** Each numeric rule's least and greatest value. */
+export declare const SLOTLOCK_BOOKING_RULE_LIMITS: Readonly<{
+    readonly minNoticeMinutes: readonly [0, 525600];
+    readonly maxAdvanceDays: readonly [1, 3660];
+    readonly slotStepMinutes: readonly [1, number];
+    readonly turnaroundMinutes: readonly [0, number];
+    readonly checkInMinutes: readonly [1, number];
+}>;
+/** Booking rules from untrusted input, or a TypeError naming the field that is wrong. */
+export declare function parseBookingRules(value: unknown): SlotlockBookingRules;
+/** The trailing buffer a booking made under the rules keeps: the larger of its own and the rule's. */
+export declare function bookingBufferAfterMs(rules: SlotlockBookingRules | undefined, ownMs?: number): number;
+/**
+ * The first instant at or after `from` that starts on a step in `timezone`. A step that does not
+ * divide the day starts again at local midnight. Across a clock change it moves forward until the
+ * local time is on a step.
+ */
+export declare function nextStepStart(from: Date, stepMinutes: number, timezone: string): Date;
+/**
+ * The rule a booking of `interval` made at `now` breaks, or null. `hours` are the resource's
+ * bookable hours (its own, or the default), read only when the rules enforce them.
+ */
+export declare function bookingRuleBroken(params: {
+    rules: SlotlockBookingRules | undefined;
+    timezone: string;
+    hours: readonly WeeklyAvailabilityRule[];
+    interval: Interval;
+    now: Date;
+}): SlotlockBookingRule | null;
+/**
+ * How a search honours the rules: the part of `window` a booking made at `now` may start in, the
+ * trailing buffer each slot keeps, and how a candidate start moves to a step. `null` when no start
+ * in the window is allowed.
+ */
+export declare function bookingSearch(params: {
+    rules: SlotlockBookingRules | undefined;
+    timezone: string;
+    window: Interval;
+    now: Date;
+    bufferAfterMs?: number;
+}): {
+    window: Interval;
+    bufferAfterMs: number;
+    align?: (start: Date) => Date;
+} | null;

package/booking-rules.js

@@ -0,0 +1,149 @@
+import { expandRules } from './rules.js';
+import { zonedOffsetMinutes } from './timezone.js';
+const MINUTE_MS = 60_000;
+const DAY_MINUTES = 24 * 60;
+/** Each numeric rule's least and greatest value. */
+export const SLOTLOCK_BOOKING_RULE_LIMITS = Object.freeze({
+    minNoticeMinutes: [0, 525_600],
+    maxAdvanceDays: [1, 3_660],
+    slotStepMinutes: [1, DAY_MINUTES],
+    turnaroundMinutes: [0, DAY_MINUTES],
+    checkInMinutes: [1, DAY_MINUTES],
+});
+const LIMITS = SLOTLOCK_BOOKING_RULE_LIMITS;
+/** Booking rules from untrusted input, or a TypeError naming the field that is wrong. */
+export function parseBookingRules(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new TypeError('Slotlock booking rules must be an object');
+    }
+    const input = value;
+    const rules = {};
+    for (const key of Object.keys(input)) {
+        if (!(key in LIMITS) && key !== 'enforceHours' && key !== 'requireCertain') {
+            throw new TypeError(`Slotlock booking rules have no ${key}`);
+        }
+    }
+    for (const [key, [min, max]] of Object.entries(LIMITS)) {
+        const field = input[key];
+        if (field === undefined)
+            continue;
+        if (typeof field !== 'number' || !Number.isSafeInteger(field) || field < min || field > max) {
+            throw new TypeError(`Slotlock booking rule ${key} must be a whole ${min}-${max}`);
+        }
+        rules[key] = field;
+    }
+    if (input.enforceHours !== undefined) {
+        if (typeof input.enforceHours !== 'boolean') {
+            throw new TypeError('Slotlock booking rule enforceHours must be true or false');
+        }
+        rules.enforceHours = input.enforceHours;
+    }
+    if (input.requireCertain !== undefined) {
+        if (typeof input.requireCertain !== 'boolean') {
+            throw new TypeError('Slotlock booking rule requireCertain must be true or false');
+        }
+        rules.requireCertain = input.requireCertain;
+    }
+    return rules;
+}
+/** The trailing buffer a booking made under the rules keeps: the larger of its own and the rule's. */
+export function bookingBufferAfterMs(rules, ownMs = 0) {
+    return Math.max(ownMs, (rules?.turnaroundMinutes ?? 0) * MINUTE_MS);
+}
+/** Minutes past local midnight in `timezone`, with the fraction. */
+function localMinutes(instant, timezone) {
+    const local = instant.getTime() + zonedOffsetMinutes(instant, timezone) * MINUTE_MS;
+    return (((local / MINUTE_MS) % DAY_MINUTES) + DAY_MINUTES) % DAY_MINUTES;
+}
+function onStep(instant, stepMinutes, timezone) {
+    const minutes = localMinutes(instant, timezone);
+    return Number.isInteger(minutes) && minutes % stepMinutes === 0;
+}
+/**
+ * The first instant at or after `from` that starts on a step in `timezone`. A step that does not
+ * divide the day starts again at local midnight. Across a clock change it moves forward until the
+ * local time is on a step.
+ */
+export function nextStepStart(from, stepMinutes, timezone) {
+    let candidate = from;
+    for (let attempt = 0; attempt < 4; attempt++) {
+        if (onStep(candidate, stepMinutes, timezone))
+            return candidate;
+        const minutes = localMinutes(candidate, timezone);
+        const next = Math.min(Math.ceil(minutes / stepMinutes + 1e-9) * stepMinutes, DAY_MINUTES);
+        const ahead = Math.max(next - minutes, 1 / 60_000);
+        candidate = new Date(Math.ceil(candidate.getTime() + ahead * MINUTE_MS));
+    }
+    return candidate;
+}
+/**
+ * The rule a booking of `interval` made at `now` breaks, or null. `hours` are the resource's
+ * bookable hours (its own, or the default), read only when the rules enforce them.
+ */
+export function bookingRuleBroken(params) {
+    const { rules, interval, now } = params;
+    if (!rules)
+        return null;
+    const start = interval.start.getTime();
+    if (rules.minNoticeMinutes !== undefined && start < now.getTime() + rules.minNoticeMinutes * MINUTE_MS) {
+        return 'min_notice';
+    }
+    if (rules.maxAdvanceDays !== undefined &&
+        start > now.getTime() + rules.maxAdvanceDays * DAY_MINUTES * MINUTE_MS) {
+        return 'max_advance';
+    }
+    if (rules.slotStepMinutes !== undefined && !onStep(interval.start, rules.slotStepMinutes, params.timezone)) {
+        return 'slot_step';
+    }
+    if (rules.enforceHours === true) {
+        const open = expandRules([...params.hours], interval, params.timezone);
+        let covered = interval.start.getTime();
+        for (const window of open.sort((a, b) => a.start.getTime() - b.start.getTime())) {
+            if (window.start.getTime() > covered)
+                break;
+            covered = Math.max(covered, window.end.getTime());
+            if (covered >= interval.end.getTime())
+                break;
+        }
+        if (covered < interval.end.getTime())
+            return 'outside_hours';
+    }
+    return null;
+}
+/**
+ * How a search honours the rules: the part of `window` a booking made at `now` may start in, the
+ * trailing buffer each slot keeps, and how a candidate start moves to a step. `null` when no start
+ * in the window is allowed.
+ */
+export function bookingSearch(params) {
+    const { rules, window, now } = params;
+    let start = window.start.getTime();
+    let end = window.end.getTime();
+    if (rules?.minNoticeMinutes !== undefined) {
+        start = Math.max(start, now.getTime() + rules.minNoticeMinutes * MINUTE_MS);
+    }
+    const bufferAfterMs = bookingBufferAfterMs(rules, params.bufferAfterMs ?? 0);
+    const step = rules?.slotStepMinutes;
+    const searched = { start: new Date(start), end: new Date(end) };
+    if (rules?.maxAdvanceDays !== undefined) {
+        // The latest allowed start bounds where a slot may start; it may still end after it.
+        const latestStart = now.getTime() + rules.maxAdvanceDays * DAY_MINUTES * MINUTE_MS;
+        if (latestStart < start || end <= start)
+            return null;
+        const align = step === undefined ? undefined : (from) => nextStepStart(from, step, params.timezone);
+        return {
+            window: searched,
+            bufferAfterMs,
+            align: (from) => {
+                const aligned = align ? align(from) : from;
+                // Past the latest start, no slot: move it beyond the window so it cannot fit.
+                return aligned.getTime() > latestStart ? new Date(end + 1) : aligned;
+            },
+        };
+    }
+    if (end <= start)
+        return null;
+    return step === undefined
+        ? { window: searched, bufferAfterMs }
+        : { window: searched, bufferAfterMs, align: (from) => nextStepStart(from, step, params.timezone) };
+}

package/config.d.ts

@@ -20,6 +20,11 @@ export declare function readServerUrl(env: SlotlockEnv, name: string, fallback?:
  * an absolute UNTIL) is a startup error instead of silently making every resource unbookable.
  */
 export declare function readAvailability(env: SlotlockEnv): WeeklyAvailabilityRule[];
+/**
+ * A dashboard name (SLOTLOCK_DASHBOARD_NAME): 1-60 characters, none of them a control, format
+ * (bidi, zero-width) or line separator character, `<` or `>`.
+ */
+export declare const SLOTLOCK_DASHBOARD_NAME_PATTERN: RegExp;
 /** The GitHub sign-in dashboard (dashboard.ts), served at `<publicUrl>/dashboard` when configured. */
 export interface SlotlockServeDashboardConfig {
     githubClientId: string;
@@ -27,9 +32,116 @@ export interface SlotlockServeDashboardConfig {
     sessionSecret: string;
     /** GitHub user ids that may sign in, or `'*'` for every GitHub account. */
     allowedUsers: '*' | string[];
+    /** GitHub organization ids whose members share a tenant each (SLOTLOCK_DASHBOARD_ORGS). */
+    organizations?: string[];
+    /** What the deployment is called in the dashboard (SLOTLOCK_DASHBOARD_NAME). */
+    name?: string;
 }
 /**
  * The dashboard's settings, or undefined when none is set. Setting any of them means serving the
  * dashboard, so the rest are then required: a half-configured sign-in is a startup error.
  */
 export declare function readDashboardConfig(env: SlotlockEnv): SlotlockServeDashboardConfig | undefined;
+/**
+ * The GitHub organization ids of SLOTLOCK_DASHBOARD_ORGS, or undefined when unset. Read on its own as
+ * well: a server whose dashboard runs elsewhere (on Cloudflare Workers) still takes those
+ * organizations' keys, and only theirs.
+ */
+export declare function readDashboardOrganizations(env: SlotlockEnv): string[] | undefined;
+/** A token bucket: `perSecond` tokens come back each second, and it holds at most `burst`. */
+export interface SlotlockRate {
+    perSecond: number;
+    burst: number;
+}
+/** The token buckets `slotlock serve` keeps (SLOTLOCK_LIMITS), each counted per its own key. */
+export declare const SLOTLOCK_RATE_NAMES: readonly ["address", "key_read", "key_write", "tenant_read", "tenant_write", "global_read", "global_write", "app_read", "app_write", "sign_in"];
+export type SlotlockRateName = (typeof SLOTLOCK_RATE_NAMES)[number];
+/** The counts `slotlock serve` caps (SLOTLOCK_LIMITS), with the range each may be set to. */
+declare const CAP_RANGES: Readonly<{
+    readonly tenant_series_writes: readonly [1, 100];
+    readonly series_writes: readonly [1, 100];
+    readonly maintenance_runs: readonly [1, 100];
+    readonly subscriptions: readonly [1, 10000];
+    readonly tenant_subscriptions: readonly [1, 10000];
+    readonly key_subscriptions: readonly [1, 64];
+    readonly key_lookups: readonly [1, 8];
+    readonly key_lookup_queue: readonly [0, 10000];
+    readonly tenant_transactions: readonly [1, 10];
+    readonly tenant_holds: readonly [1, 10000000];
+    readonly tenant_reservations: readonly [1, 10000000];
+    readonly tenant_events: readonly [1, 10000000];
+    readonly tenant_coverage: readonly [1, 10000000];
+    readonly holder_holds: readonly [1, 10000];
+    readonly holder_held_hours: readonly [1, 876000];
+}>;
+export type SlotlockCapName = keyof typeof CAP_RANGES;
+export declare const SLOTLOCK_CAP_NAMES: readonly ("holder_held_hours" | "holder_holds" | "key_lookup_queue" | "key_lookups" | "key_subscriptions" | "maintenance_runs" | "series_writes" | "subscriptions" | "tenant_coverage" | "tenant_events" | "tenant_holds" | "tenant_reservations" | "tenant_series_writes" | "tenant_subscriptions" | "tenant_transactions")[];
+export interface SlotlockLimits {
+    /** Each rate, or null where SLOTLOCK_LIMITS turns it off. */
+    rates: Readonly<Record<SlotlockRateName, SlotlockRate | null>>;
+    caps: Readonly<Record<SlotlockCapName, number>>;
+}
+/**
+ * What `slotlock serve` allows unless SLOTLOCK_LIMITS says otherwise, sized for one public server on
+ * one CPU (the 2026-10-24 readiness audit measured the database at about 900 writes a second):
+ * - `address`: every request from one client address, before any credential is looked up.
+ * - `key_*`, `tenant_*`, `global_*`: an authenticated request takes a read token from its key, its
+ *   tenant and the server; a write (a REST method other than GET or HEAD, or a write tool) takes a
+ *   write token from each as well.
+ * - `app_*`: a request to the application API (application-api.ts) from an admin key takes its
+ *   read and write tokens from its tenant's application buckets instead of the key and tenant ones,
+ *   so the application and the tenant's agents cannot use up each other's budget; one from any
+ *   other key takes them from that key's own. `global_*` counts it as well.
+ * - `sign_in`: dashboard sign-ins and their callbacks from one client network: an IPv4 address,
+ *   or an IPv6 client's /48 (slotlockClientNetwork in rate-limit.ts), as the dashboard Worker
+ *   counts them.
+ * - `tenant_series_writes` and `series_writes`: writes that may expand a recurring series (a
+ *   recurring create, any update) running at once in a tenant and in each server process.
+ * - `maintenance_runs`: the application API's maintenance runs at once in each server process, one
+ *   a tenant, in slots of their own. A freed slot of either kind rests for as long as the event
+ *   loop was busy while its write held it, up to a second, then goes to the tenant with the fewest
+ *   writes in flight and, among those, the least use lately. That keeps a tenant sending one write
+ *   at a time from waiting behind tenants with more, not behind many tenants with one each
+ *   (rate-limit.ts).
+ * - `subscriptions`: MCP live-update streams the server holds open. When it is full, a tenant
+ *   holding fewer than the tenant holding most, less one, ends that tenant's oldest stream.
+ * - `tenant_subscriptions`: of those, how many one tenant may hold.
+ * - `key_subscriptions`: of those, how many one key (or the server token) may hold, and always
+ *   fewer than its tenant's, so one key cannot lock the tenant's other keys out
+ *   (slotlockKeySubscriptions).
+ * - `key_lookups` and `key_lookup_queue`: API key lookups running at once and waiting.
+ * - `tenant_transactions`: store transactions one tenant runs at once on the server's pool of 10
+ *   connections; the rest wait their turn in the process, so a tenant's writes waiting on its own
+ *   locks leave the other connections to other tenants and key lookups. A server with one tenant
+ *   can set 10.
+ * - `tenant_holds`, `tenant_reservations`, `tenant_events` and `tenant_coverage`: what one tenant
+ *   may store, counted as the store's tenant limits count it (SlotlockTenantLimits), whichever key,
+ *   agent or application writes it. Every write surface of the server shares them, so no admin
+ *   key can grow the shared database without end; a write past one answers 409 with its
+ *   `*_limit_reached` code.
+ * - `holder_holds` and `holder_held_hours`: one holder's (an agent's) live holds, how many and how
+ *   many hours they hold together (`hold_limit_reached`, `held_time_limit_reached`).
+ */
+export declare const SLOTLOCK_DEFAULT_LIMITS: SlotlockLimits;
+/**
+ * The live-update streams one key may hold open: `key_subscriptions`, but at least one fewer than
+ * its tenant may (unless the tenant may hold only one), so a key at its own limit leaves its
+ * tenant's other keys a stream however the two caps are set.
+ */
+export declare function slotlockKeySubscriptions(caps: Readonly<Record<SlotlockCapName, number>>): number;
+/** A rate as SLOTLOCK_LIMITS and the `listening` log line write it: `<count>/<s|m|h>:<burst>`. */
+export declare function formatSlotlockRate(rate: SlotlockRate | null): string;
+/**
+ * SLOTLOCK_LIMITS: comma-separated `name=value` overrides of SLOTLOCK_DEFAULT_LIMITS. A rate is
+ * `<count>/<s|m|h>`, optionally `:<burst>` (default: the count), or `off`; a cap is a whole number.
+ * For example `tenant_write=2/s:10,global_write=30/s,address=off`.
+ */
+export declare function readLimits(env: SlotlockEnv): SlotlockLimits;
+/**
+ * SLOTLOCK_TRUSTED_PROXY_HEADER: the request field holding the client's address, set (and
+ * overwritten) by a proxy every request passes through, such as `CF-Connecting-IP` behind
+ * Cloudflare. Unset, the client address is the connection's. A client can send any field, so set it
+ * only when nothing reaches the server except through that proxy.
+ */
+export declare function readTrustedProxyHeader(env: SlotlockEnv): string | undefined;
+export {};

package/config.js

@@ -92,6 +92,11 @@ export function readAvailability(env) {
         };
     });
 }
+/**
+ * A dashboard name (SLOTLOCK_DASHBOARD_NAME): 1-60 characters, none of them a control, format
+ * (bidi, zero-width) or line separator character, `<` or `>`.
+ */
+export const SLOTLOCK_DASHBOARD_NAME_PATTERN = /^[^\p{Cc}\p{Cf}\p{Zl}\p{Zp}<>]{1,60}$/u;
 const DASHBOARD_VARIABLES = [
     'SLOTLOCK_GITHUB_CLIENT_ID',
     'SLOTLOCK_GITHUB_CLIENT_SECRET',
@@ -129,10 +134,230 @@ export function readDashboardConfig(env) {
     if (users === undefined || (users !== '*' && !/^[1-9]\d{0,19}(,[1-9]\d{0,19})*$/.test(users))) {
         throw new SlotlockConfigError('SLOTLOCK_DASHBOARD_USERS is required to serve the dashboard: * for every GitHub account, or a comma-separated list of GitHub user ids (gh api users/<login> --jq .id)');
     }
+    const orgs = readDashboardOrganizations(env);
+    const name = optional(env, 'SLOTLOCK_DASHBOARD_NAME')?.trim();
+    if (name !== undefined && name !== '' && !SLOTLOCK_DASHBOARD_NAME_PATTERN.test(name)) {
+        throw new SlotlockConfigError('SLOTLOCK_DASHBOARD_NAME must be 1-60 characters, without <, > or control or invisible characters');
+    }
     return {
         githubClientId,
         githubClientSecret,
         sessionSecret,
         allowedUsers: users === '*' ? '*' : [...new Set(users.split(','))],
+        ...(orgs !== undefined ? { organizations: orgs } : {}),
+        ...(name !== undefined && name !== '' ? { name } : {}),
     };
 }
+/**
+ * The GitHub organization ids of SLOTLOCK_DASHBOARD_ORGS, or undefined when unset. Read on its own as
+ * well: a server whose dashboard runs elsewhere (on Cloudflare Workers) still takes those
+ * organizations' keys, and only theirs.
+ */
+export function readDashboardOrganizations(env) {
+    const orgs = optional(env, 'SLOTLOCK_DASHBOARD_ORGS')?.replaceAll(' ', '');
+    if (orgs === undefined)
+        return undefined;
+    if (!/^[1-9]\d{0,19}(,[1-9]\d{0,19})*$/.test(orgs)) {
+        throw new SlotlockConfigError('SLOTLOCK_DASHBOARD_ORGS must be a comma-separated list of GitHub organization ids (gh api orgs/<login> --jq .id)');
+    }
+    return [...new Set(orgs.split(','))];
+}
+/** The token buckets `slotlock serve` keeps (SLOTLOCK_LIMITS), each counted per its own key. */
+export const SLOTLOCK_RATE_NAMES = Object.freeze([
+    'address',
+    'key_read',
+    'key_write',
+    'tenant_read',
+    'tenant_write',
+    'global_read',
+    'global_write',
+    'app_read',
+    'app_write',
+    'sign_in',
+]);
+/** The counts `slotlock serve` caps (SLOTLOCK_LIMITS), with the range each may be set to. */
+const CAP_RANGES = Object.freeze({
+    tenant_series_writes: [1, 100],
+    series_writes: [1, 100],
+    maintenance_runs: [1, 100],
+    subscriptions: [1, 10_000],
+    tenant_subscriptions: [1, 10_000],
+    key_subscriptions: [1, 64],
+    key_lookups: [1, 8],
+    key_lookup_queue: [0, 10_000],
+    // serve's pool has 10 connections: more than that bounds nothing.
+    tenant_transactions: [1, 10],
+    tenant_holds: [1, 10_000_000],
+    tenant_reservations: [1, 10_000_000],
+    tenant_events: [1, 10_000_000],
+    tenant_coverage: [1, 10_000_000],
+    holder_holds: [1, 10_000],
+    holder_held_hours: [1, 876_000],
+});
+export const SLOTLOCK_CAP_NAMES = Object.freeze(Object.keys(CAP_RANGES));
+/**
+ * What `slotlock serve` allows unless SLOTLOCK_LIMITS says otherwise, sized for one public server on
+ * one CPU (the 2026-10-24 readiness audit measured the database at about 900 writes a second):
+ * - `address`: every request from one client address, before any credential is looked up.
+ * - `key_*`, `tenant_*`, `global_*`: an authenticated request takes a read token from its key, its
+ *   tenant and the server; a write (a REST method other than GET or HEAD, or a write tool) takes a
+ *   write token from each as well.
+ * - `app_*`: a request to the application API (application-api.ts) from an admin key takes its
+ *   read and write tokens from its tenant's application buckets instead of the key and tenant ones,
+ *   so the application and the tenant's agents cannot use up each other's budget; one from any
+ *   other key takes them from that key's own. `global_*` counts it as well.
+ * - `sign_in`: dashboard sign-ins and their callbacks from one client network: an IPv4 address,
+ *   or an IPv6 client's /48 (slotlockClientNetwork in rate-limit.ts), as the dashboard Worker
+ *   counts them.
+ * - `tenant_series_writes` and `series_writes`: writes that may expand a recurring series (a
+ *   recurring create, any update) running at once in a tenant and in each server process.
+ * - `maintenance_runs`: the application API's maintenance runs at once in each server process, one
+ *   a tenant, in slots of their own. A freed slot of either kind rests for as long as the event
+ *   loop was busy while its write held it, up to a second, then goes to the tenant with the fewest
+ *   writes in flight and, among those, the least use lately. That keeps a tenant sending one write
+ *   at a time from waiting behind tenants with more, not behind many tenants with one each
+ *   (rate-limit.ts).
+ * - `subscriptions`: MCP live-update streams the server holds open. When it is full, a tenant
+ *   holding fewer than the tenant holding most, less one, ends that tenant's oldest stream.
+ * - `tenant_subscriptions`: of those, how many one tenant may hold.
+ * - `key_subscriptions`: of those, how many one key (or the server token) may hold, and always
+ *   fewer than its tenant's, so one key cannot lock the tenant's other keys out
+ *   (slotlockKeySubscriptions).
+ * - `key_lookups` and `key_lookup_queue`: API key lookups running at once and waiting.
+ * - `tenant_transactions`: store transactions one tenant runs at once on the server's pool of 10
+ *   connections; the rest wait their turn in the process, so a tenant's writes waiting on its own
+ *   locks leave the other connections to other tenants and key lookups. A server with one tenant
+ *   can set 10.
+ * - `tenant_holds`, `tenant_reservations`, `tenant_events` and `tenant_coverage`: what one tenant
+ *   may store, counted as the store's tenant limits count it (SlotlockTenantLimits), whichever key,
+ *   agent or application writes it. Every write surface of the server shares them, so no admin
+ *   key can grow the shared database without end; a write past one answers 409 with its
+ *   `*_limit_reached` code.
+ * - `holder_holds` and `holder_held_hours`: one holder's (an agent's) live holds, how many and how
+ *   many hours they hold together (`hold_limit_reached`, `held_time_limit_reached`).
+ */
+export const SLOTLOCK_DEFAULT_LIMITS = Object.freeze({
+    rates: Object.freeze({
+        address: { perSecond: 50, burst: 100 },
+        key_read: { perSecond: 20, burst: 40 },
+        key_write: { perSecond: 5, burst: 20 },
+        tenant_read: { perSecond: 20, burst: 40 },
+        tenant_write: { perSecond: 5, burst: 20 },
+        global_read: { perSecond: 500, burst: 1_000 },
+        global_write: { perSecond: 50, burst: 100 },
+        app_read: { perSecond: 20, burst: 40 },
+        app_write: { perSecond: 5, burst: 20 },
+        sign_in: { perSecond: 20 / 60, burst: 20 },
+    }),
+    caps: Object.freeze({
+        tenant_series_writes: 1,
+        series_writes: 1,
+        maintenance_runs: 1,
+        subscriptions: 256,
+        tenant_subscriptions: 16,
+        key_subscriptions: 4,
+        key_lookups: 2,
+        key_lookup_queue: 256,
+        tenant_transactions: 2,
+        // Sized for the server's 10,000 resources a tenant: a live hold for every one, ten bookings and
+        // ten events a resource, and coverage from ten calendars a resource.
+        tenant_holds: 10_000,
+        tenant_reservations: 100_000,
+        tenant_events: 100_000,
+        tenant_coverage: 100_000,
+        // One agent's live holds: 20 at once (candidates for a few bookings), holding 90 days in all.
+        holder_holds: 20,
+        holder_held_hours: 2_160,
+    }),
+});
+/**
+ * The live-update streams one key may hold open: `key_subscriptions`, but at least one fewer than
+ * its tenant may (unless the tenant may hold only one), so a key at its own limit leaves its
+ * tenant's other keys a stream however the two caps are set.
+ */
+export function slotlockKeySubscriptions(caps) {
+    return Math.max(1, Math.min(caps.key_subscriptions, caps.tenant_subscriptions - 1));
+}
+const RATE_PERIOD_SECONDS = { s: 1, m: 60, h: 3_600 };
+const MAX_RATE_COUNT = 1_000_000;
+/** A rate as SLOTLOCK_LIMITS and the `listening` log line write it: `<count>/<s|m|h>:<burst>`. */
+export function formatSlotlockRate(rate) {
+    if (rate === null)
+        return 'off';
+    // The smallest unit in which the count is whole: 50/s rather than 180000/h.
+    for (const [unit, seconds] of Object.entries(RATE_PERIOD_SECONDS)) {
+        const count = rate.perSecond * seconds;
+        if (Number.isInteger(Math.round(count * 1e9) / 1e9) && count >= 1) {
+            return `${Math.round(count)}/${unit}:${rate.burst}`;
+        }
+    }
+    return `${rate.perSecond}/s:${rate.burst}`;
+}
+/**
+ * SLOTLOCK_LIMITS: comma-separated `name=value` overrides of SLOTLOCK_DEFAULT_LIMITS. A rate is
+ * `<count>/<s|m|h>`, optionally `:<burst>` (default: the count), or `off`; a cap is a whole number.
+ * For example `tenant_write=2/s:10,global_write=30/s,address=off`.
+ */
+export function readLimits(env) {
+    const rates = { ...SLOTLOCK_DEFAULT_LIMITS.rates };
+    const caps = { ...SLOTLOCK_DEFAULT_LIMITS.caps };
+    const value = optional(env, 'SLOTLOCK_LIMITS');
+    if (value === undefined)
+        return { rates, caps };
+    const invalid = (detail) => new SlotlockConfigError(`SLOTLOCK_LIMITS must be comma-separated name=value settings, rates as <count>/<s|m|h>[:<burst>] or off (${SLOTLOCK_RATE_NAMES.join(', ')}) and caps as whole numbers (${SLOTLOCK_CAP_NAMES.join(', ')}): ${detail}`);
+    const seen = new Set();
+    for (const entry of value.split(',').map((part) => part.trim())) {
+        const match = /^([a-z_]+)=(\S+)$/.exec(entry);
+        if (!match)
+            throw invalid(`"${entry.slice(0, 40)}" is not name=value`);
+        const [, name, setting] = match;
+        if (seen.has(name))
+            throw invalid(`${name} is set twice`);
+        seen.add(name);
+        if (SLOTLOCK_RATE_NAMES.includes(name)) {
+            if (setting === 'off') {
+                rates[name] = null;
+                continue;
+            }
+            const rate = /^(\d{1,7})\/([smh])(?::(\d{1,7}))?$/.exec(setting);
+            const count = Number(rate?.[1]);
+            const burst = rate?.[3] === undefined ? count : Number(rate[3]);
+            if (!rate || count < 1 || count > MAX_RATE_COUNT || burst < 1 || burst > MAX_RATE_COUNT) {
+                throw invalid(`${name} must be <count>/<s|m|h>[:<burst>] with each 1-${MAX_RATE_COUNT}, or off`);
+            }
+            rates[name] = {
+                perSecond: count / RATE_PERIOD_SECONDS[rate[2]],
+                burst,
+            };
+        }
+        else if (Object.hasOwn(CAP_RANGES, name)) {
+            const [minimum, maximum] = CAP_RANGES[name];
+            const cap = /^\d{1,8}$/.test(setting) ? Number(setting) : Number.NaN;
+            if (!(cap >= minimum && cap <= maximum)) {
+                throw invalid(`${name} must be a whole number from ${minimum} to ${maximum}`);
+            }
+            caps[name] = cap;
+        }
+        else {
+            throw invalid(`${name.slice(0, 40)} is not a limit`);
+        }
+    }
+    return { rates, caps };
+}
+/** Fields a proxy cannot be trusted to set, because the client sends them to every server. */
+const UNTRUSTABLE_FIELDS = new Set(['authorization', 'cookie', 'host', 'origin', 'content-type']);
+/**
+ * SLOTLOCK_TRUSTED_PROXY_HEADER: the request field holding the client's address, set (and
+ * overwritten) by a proxy every request passes through, such as `CF-Connecting-IP` behind
+ * Cloudflare. Unset, the client address is the connection's. A client can send any field, so set it
+ * only when nothing reaches the server except through that proxy.
+ */
+export function readTrustedProxyHeader(env) {
+    const value = optional(env, 'SLOTLOCK_TRUSTED_PROXY_HEADER');
+    if (value === undefined)
+        return undefined;
+    if (!/^[A-Za-z0-9-]{1,64}$/.test(value) || UNTRUSTABLE_FIELDS.has(value.toLowerCase())) {
+        throw new SlotlockConfigError('SLOTLOCK_TRUSTED_PROXY_HEADER must be the name of a request field your proxy sets to the client address, such as CF-Connecting-IP');
+    }
+    return value.toLowerCase();
+}