slotlock 0.6.1 → 0.6.3

package/assistant.d.ts

@@ -4,11 +4,10 @@ export type SlotlockAssistantProvider = 'anthropic' | 'openai';
 /** What the assistant does with each agent operation: run it, propose it, or never offer it. */
 export type SlotlockAssistantToolUse = 'read' | 'propose' | 'excluded';
 /**
- * The tools the model is offered, by agent operation. A record over every operation, so one a later
- * release adds does not compile until it is placed here. Reads run when the model calls them;
- * every write is only proposed, and runs when the member approves it. API keys, webhooks, booking
- * rules, pools, erasure and coverage are application operations, never agent ones, so no entry can
- * offer them.
+ * The tools the model is offered, by agent operation. A record over every operation, so a new one
+ * does not compile until placed here. Reads run when called; writes are only proposed and run on
+ * approval. API keys, webhooks, booking rules, pools, erasure and coverage are application
+ * operations, never agent ones, so none can be offered.
  */
 export declare const SLOTLOCK_ASSISTANT_TOOL_USE: Readonly<Record<SlotlockAgentOperation, SlotlockAssistantToolUse>>;
 /** Model calls one message may make before the assistant stops and says so. */
@@ -16,20 +15,15 @@ export declare const SLOTLOCK_ASSISTANT_MAX_STEPS = 8;
 /** Characters of one message from a member. */
 export declare const SLOTLOCK_ASSISTANT_MAX_MESSAGE = 2000;
 /**
- * UTF-8 bytes of the stored conversation as JSON, past which the oldest exchanges go first.
- * PostgreSQL's jsonb text adds at most one space per `:` or `,`, so at most half again: under the
- * table's 262,144-byte CHECK on `messages::text` whatever the text.
+ * UTF-8 bytes of the stored conversation as JSON. jsonb text adds at most one space per `:` or `,`,
+ * so this stays under the table's 262,144-byte CHECK on `messages::text`.
  */
 export declare const SLOTLOCK_ASSISTANT_MAX_STORED_BYTES = 160000;
 /** UTF-8 bytes of one proposed change's arguments as JSON; a larger one is not proposed. */
 export declare const SLOTLOCK_ASSISTANT_MAX_ACTION_BYTES = 16000;
 /** Proposed changes one conversation may have waiting at once (4 of the largest fit the bound). */
 export declare const SLOTLOCK_ASSISTANT_MAX_PENDING = 4;
-/**
- * The Messages API version this sends: the one @anthropic-ai/sdk 1.3.0 (2026-10-23) sends, read
- * from its source on 2026-10-28. Top-level `system`, `tools[].input_schema`, `tool_use` and
- * `tool_result` blocks are as before in it.
- */
+/** The Messages API version @anthropic-ai/sdk 1.3.0 sends (read from its source 2026-10-28). */
 export declare const SLOTLOCK_ANTHROPIC_VERSION = "2026-10-21";
 /** A model as the assistant calls it, with the key opened. */
 export interface SlotlockAssistantModel {
@@ -115,11 +109,10 @@ export declare function sealSlotlockAssistantKey(secret: string, tenantRef: stri
 /** The key a seal holds, or null when it is not one this secret sealed for this tenant. */
 export declare function openSlotlockAssistantKey(secret: string, tenantRef: string, sealed: string): Promise<string | null>;
 /**
- * A provider base URL as stored: https, or http on localhost or 127.0.0.1 (a model on the server's
- * own machine); no credentials, query or fragment; no trailing slash. Unless `privateUrls`, a URL
- * whose host is `localhost` or a loopback, private, link-local, shared (CGNAT), unique-local or
- * metadata address (the webhooks' isPrivateAddress) is refused as `private`; a name that resolves
- * to one is refused when it is resolved (checkSlotlockAssistantHost, and at each connection).
+ * A provider base URL as stored: https, or http on localhost or 127.0.0.1; no credentials, query,
+ * fragment or trailing slash. Unless `privateUrls`, a host that is `localhost` or a private-range
+ * IP literal is refused as `private`; a name resolving to one is refused when resolved
+ * (checkSlotlockAssistantHost, and at each connection).
  */
 export declare function readSlotlockAssistantBaseUrl(value: string, options?: {
     privateUrls?: boolean;
@@ -131,10 +124,9 @@ export declare function readSlotlockAssistantBaseUrl(value: string, options?: {
     reason: 'invalid' | 'private';
 };
 /**
- * Whether a base URL's host resolves only to public addresses: `resolve` lists them (dns.lookup's,
- * on Node.js). True when `privateUrls`, or when the host is an IP literal readSlotlockAssistantBaseUrl
- * already checked; false when any address is private. A name that does not resolve is not refused
- * here: the connection fails later, plainly.
+ * Whether a base URL's host resolves only to public addresses (`resolve`: dns.lookup on Node.js).
+ * True with `privateUrls` or an IP literal already checked; a name that does not resolve is not
+ * refused here: the connection fails later.
  */
 export declare function checkSlotlockAssistantHost(baseUrl: string, options: {
     privateUrls?: boolean;
@@ -239,14 +231,13 @@ export interface SlotlockAssistantTurnResult {
  */
 export declare function runSlotlockAssistantTurn(options: SlotlockAssistantTurnOptions): Promise<SlotlockAssistantTurnResult>;
 /**
- * The conversation within its bounds: at most MAX_ENTRIES entries and MAX_STORED_CHARACTERS, the
- * oldest exchanges dropped whole, so it always starts at a member's message (a tool result is never
- * kept without the call it answers).
+ * The conversation within MAX_ENTRIES and the stored-bytes bound, oldest exchanges dropped whole,
+ * so it always starts at a member's message (a tool result is never kept without its call).
  */
 export declare function boundSlotlockAssistantEntries(entries: readonly SlotlockAssistantEntry[]): SlotlockAssistantEntry[];
 /**
- * The actions a conversation keeps: those its kept entries show, the oldest settled ones dropped
- * first past MAX_ACTIONS_BYTES (a waiting one is kept: SLOTLOCK_ASSISTANT_MAX_PENDING bounds them).
+ * The actions a conversation keeps: those its entries show, oldest settled ones dropped first past
+ * MAX_ACTIONS_BYTES (waiting ones are bounded by SLOTLOCK_ASSISTANT_MAX_PENDING).
  */
 export declare function pruneSlotlockAssistantActions(entries: readonly SlotlockAssistantEntry[], actions: Readonly<Record<string, Record<string, unknown>>>): Record<string, Record<string, unknown>>;
 /** How many of a conversation's actions wait for the member. */

package/assistant.js

@@ -1,27 +1,23 @@
-// The dashboard assistant: an organization connects a model of its own (the Anthropic Messages API,
-// or any OpenAI-compatible chat completions endpoint: OpenAI, OpenRouter, vLLM, Ollama, LM Studio)
-// and its members operate Slotlock by chat. The server runs the tool loop: it calls the model with a
-// fixed list of agent tools, runs reads through the agent operation boundary (schemas, scopes,
-// authorization and limits, as for any agent) and turns every write into an action the member
-// approves on a form before it runs. Nothing the model says changes the list of tools.
+// The dashboard assistant: an organization connects its own model (the Anthropic Messages API, or
+// any OpenAI-compatible chat completions endpoint) and its members operate Slotlock by chat. The
+// server runs the tool loop with a fixed tool list: reads go through the agent operation boundary
+// (schemas, scopes, limits), and every write becomes an action the member approves before it runs.
+// Nothing the model says changes the list of tools.
 //
-// Request formats: the Messages API (POST <base>/v1/messages, x-api-key, anthropic-version; tool_use
-// and tool_result blocks) and Chat Completions (POST <base>/chat/completions, Bearer; tool_calls with
-// JSON-string arguments, role "tool" results), as the vendors' official TypeScript SDKs describe
-// them: @anthropic-ai/sdk 1.3.0 and openai 7.45.1, read from the npm registry 2026-10-28.
+// Request formats as the vendors' official TypeScript SDKs describe them: @anthropic-ai/sdk 1.3.0
+// and openai 7.45.1 (read from the npm registry 2026-10-28).
 //
-// The API key is sealed with AES-256-GCM (WebCrypto, in Node.js and Workers alike) under a key
-// derived by HKDF-SHA-256 from the deployment's SLOTLOCK_ASSISTANT_SECRET, with the tenant as
-// additional data: a sealed key copied to another tenant's row does not open.
+// The API key is sealed with AES-256-GCM (WebCrypto) under a key HKDF-SHA-256-derived from
+// SLOTLOCK_ASSISTANT_SECRET, with the tenant as additional data: a sealed key copied to another
+// tenant's row does not open.
 import { slotlockAgentOperationScope, slotlockAgentTools, } from './agent-server.js';
 import { isIP } from 'node:net';
 import { isPrivateAddress } from './webhooks.js';
 /**
- * The tools the model is offered, by agent operation. A record over every operation, so one a later
- * release adds does not compile until it is placed here. Reads run when the model calls them;
- * every write is only proposed, and runs when the member approves it. API keys, webhooks, booking
- * rules, pools, erasure and coverage are application operations, never agent ones, so no entry can
- * offer them.
+ * The tools the model is offered, by agent operation. A record over every operation, so a new one
+ * does not compile until placed here. Reads run when called; writes are only proposed and run on
+ * approval. API keys, webhooks, booking rules, pools, erasure and coverage are application
+ * operations, never agent ones, so none can be offered.
  */
 export const SLOTLOCK_ASSISTANT_TOOL_USE = Object.freeze({
     slotlock_list_resources: 'read',
@@ -52,9 +48,8 @@ export const SLOTLOCK_ASSISTANT_MAX_MESSAGE = 2_000;
 /** Entries a conversation keeps; the oldest exchanges go first. */
 const MAX_ENTRIES = 60;
 /**
- * UTF-8 bytes of the stored conversation as JSON, past which the oldest exchanges go first.
- * PostgreSQL's jsonb text adds at most one space per `:` or `,`, so at most half again: under the
- * table's 262,144-byte CHECK on `messages::text` whatever the text.
+ * UTF-8 bytes of the stored conversation as JSON. jsonb text adds at most one space per `:` or `,`,
+ * so this stays under the table's 262,144-byte CHECK on `messages::text`.
  */
 export const SLOTLOCK_ASSISTANT_MAX_STORED_BYTES = 160_000;
 /** UTF-8 bytes of the kept actions as JSON: under the 131,072-byte CHECK on `actions::text` as above. */
@@ -72,15 +67,10 @@ const MAX_CALLS_PER_STEP = 8;
 /** Bytes of one provider answer. */
 const MAX_RESPONSE_BYTES = 1_048_576;
 const MAX_OUTPUT_TOKENS = 1_024;
-/**
- * The Messages API version this sends: the one @anthropic-ai/sdk 1.3.0 (2026-10-23) sends, read
- * from its source on 2026-10-28. Top-level `system`, `tools[].input_schema`, `tool_use` and
- * `tool_result` blocks are as before in it.
- */
+/** The Messages API version @anthropic-ai/sdk 1.3.0 sends (read from its source 2026-10-28). */
 export const SLOTLOCK_ANTHROPIC_VERSION = '2026-10-21';
 /** The assistant's records in the store, each in a transaction under the tenant's row-level security. */
 export function createSlotlockAssistantStore(store) {
-    // Every change here is the dashboard's, made by the person signed in (actor) when known.
     const by = (actor) => actor === undefined ? { origin: 'dashboard' } : { origin: 'dashboard', actor };
     return {
         getSettings: (tenantRef) => store.withTenant(tenantRef, (tenant) => tenant.getAssistantSettings({ tenantRef })),
@@ -90,8 +80,8 @@ export function createSlotlockAssistantStore(store) {
             ...(actor !== undefined ? { updatedBy: actor } : {}),
         }), by(actor)),
         deleteSettings: (tenantRef, actor) => store.withTenant(tenantRef, (tenant) => tenant.deleteAssistantSettings({ tenantRef }), by(actor)),
-        // Each read deletes the tenant's expired conversations first, so they go on a deployment whose
-        // maintenance never meets the tenant (a Worker's) too.
+        // Each read deletes the tenant's expired conversations first, for deployments whose maintenance
+        // never meets the tenant (a Worker's).
         getConversation: (tenantRef, memberRef) => store.withTenant(tenantRef, async (tenant) => {
             await tenant.pruneAssistantConversations({ tenantRef, limit: 100 });
             return tenant.getAssistantConversation({ tenantRef, memberRef });
@@ -156,7 +146,7 @@ export function createSlotlockMemoryAssistantStore(now = Date.now) {
         },
         async putConversation(tenantRef, memberRef, conversation, ttlMs) {
             const stored = live(tenantRef, memberRef);
-            // As the store: the stored ones kept as they stand, then the new ones not stored already.
+            // As the store does: stored ones kept as they stand, then new ones not stored already.
             const actions = {};
             for (const id of conversation.keep) {
                 const kept = stored?.actions[id];
@@ -188,7 +178,6 @@ export function createSlotlockMemoryAssistantStore(now = Date.now) {
         },
     };
 }
-// ---- The key, sealed ----
 const SEAL_VERSION = 'v1';
 const encoder = new TextEncoder();
 async function sealingKey(secret) {
@@ -226,7 +215,6 @@ export async function openSlotlockAssistantKey(secret, tenantRef, sealed) {
         return null;
     }
 }
-// ---- Settings ----
 const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]']);
 /** Whether a URL's host names this machine or a private network by itself: `localhost`, or an IP literal isPrivateAddress refuses. */
 function namesPrivateHost(url) {
@@ -236,11 +224,10 @@ function namesPrivateHost(url) {
     return isIP(host) !== 0 && isPrivateAddress(host);
 }
 /**
- * A provider base URL as stored: https, or http on localhost or 127.0.0.1 (a model on the server's
- * own machine); no credentials, query or fragment; no trailing slash. Unless `privateUrls`, a URL
- * whose host is `localhost` or a loopback, private, link-local, shared (CGNAT), unique-local or
- * metadata address (the webhooks' isPrivateAddress) is refused as `private`; a name that resolves
- * to one is refused when it is resolved (checkSlotlockAssistantHost, and at each connection).
+ * A provider base URL as stored: https, or http on localhost or 127.0.0.1; no credentials, query,
+ * fragment or trailing slash. Unless `privateUrls`, a host that is `localhost` or a private-range
+ * IP literal is refused as `private`; a name resolving to one is refused when resolved
+ * (checkSlotlockAssistantHost, and at each connection).
  */
 export function readSlotlockAssistantBaseUrl(value, options = {}) {
     let url;
@@ -263,10 +250,9 @@ export function readSlotlockAssistantBaseUrl(value, options = {}) {
     return { ok: true, url: href };
 }
 /**
- * Whether a base URL's host resolves only to public addresses: `resolve` lists them (dns.lookup's,
- * on Node.js). True when `privateUrls`, or when the host is an IP literal readSlotlockAssistantBaseUrl
- * already checked; false when any address is private. A name that does not resolve is not refused
- * here: the connection fails later, plainly.
+ * Whether a base URL's host resolves only to public addresses (`resolve`: dns.lookup on Node.js).
+ * True with `privateUrls` or an IP literal already checked; a name that does not resolve is not
+ * refused here: the connection fails later.
  */
 export async function checkSlotlockAssistantHost(baseUrl, options) {
     if (options.privateUrls === true || !options.resolve)
@@ -316,7 +302,6 @@ export function slotlockAssistantTools() {
         ];
     });
 }
-// ---- Providers ----
 /** Why a provider call failed, in words safe to show (never the key, never the provider's body). */
 export class SlotlockAssistantProviderError extends Error {
     reason;
@@ -473,7 +458,7 @@ function readOpenai(body) {
         catch {
             input = null;
         }
-        // Some local servers leave the id out; one is needed to pair the result.
+        // Some local servers omit the id; one is needed to pair the result.
         const id = typeof call.id === 'string' && call.id !== '' ? call.id : `call_${index}`;
         calls.push({ id, name: call.function.name, input });
     }
@@ -523,7 +508,7 @@ export async function callSlotlockAssistantModel(request) {
             method: 'POST',
             headers,
             body: JSON.stringify(anthropic ? anthropicBody(request) : openaiBody(request)),
-            // A redirect is not followed: it would carry the key elsewhere.
+            // Never follow a redirect: it would carry the key elsewhere.
             redirect: 'manual',
             signal: request.signal,
         });
@@ -675,24 +660,22 @@ export async function runSlotlockAssistantTurn(options) {
     return { added };
 }
 /**
- * The conversation within its bounds: at most MAX_ENTRIES entries and MAX_STORED_CHARACTERS, the
- * oldest exchanges dropped whole, so it always starts at a member's message (a tool result is never
- * kept without the call it answers).
+ * The conversation within MAX_ENTRIES and the stored-bytes bound, oldest exchanges dropped whole,
+ * so it always starts at a member's message (a tool result is never kept without its call).
  */
 export function boundSlotlockAssistantEntries(entries) {
-    // PostgreSQL's jsonb holds no NUL character: one would fail the write.
+    // jsonb holds no NUL character: one would fail the write.
     let kept = JSON.parse(JSON.stringify(entries, (_key, value) => typeof value === 'string' ? value.replaceAll('\u0000', '') : value));
     const tooBig = () => kept.length > MAX_ENTRIES ||
         Buffer.byteLength(JSON.stringify(kept), 'utf8') > SLOTLOCK_ASSISTANT_MAX_STORED_BYTES;
-    // The oldest exchanges first, whole.
     while (tooBig()) {
         const next = kept.findIndex((entry, index) => index > 0 && entry.role === 'user');
         if (next === -1)
             break;
         kept = kept.slice(next);
     }
-    // One exchange too big alone: its steps (a call and its results) from the oldest, those that
-    // proposed no change first; the member's message and the last answer stay.
+    // An exchange too big alone loses its steps from the oldest, non-proposing ones first; the
+    // member's message and the last answer stay.
     for (const keepProposals of [true, false]) {
         while (tooBig()) {
             const step = kept.findIndex((entry, index) => entry.role === 'assistant' &&
@@ -711,8 +694,8 @@ export function boundSlotlockAssistantEntries(entries) {
     return tooBig() ? [] : kept;
 }
 /**
- * The actions a conversation keeps: those its kept entries show, the oldest settled ones dropped
- * first past MAX_ACTIONS_BYTES (a waiting one is kept: SLOTLOCK_ASSISTANT_MAX_PENDING bounds them).
+ * The actions a conversation keeps: those its entries show, oldest settled ones dropped first past
+ * MAX_ACTIONS_BYTES (waiting ones are bounded by SLOTLOCK_ASSISTANT_MAX_PENDING).
  */
 export function pruneSlotlockAssistantActions(entries, actions) {
     const shown = [];

package/booking-rules.d.ts

@@ -1,8 +1,7 @@
 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.
+ * A resource's booking rules: what a booking made through Slotlock (hold, reservation, agent event)
+ * must satisfy, and what a search offers. All optional. Imported calendar events are not checked.
  */
 export interface SlotlockBookingRules {
     /** A booking starts at least this many minutes after it is made: 0-525,600 (a year). */
@@ -15,35 +14,32 @@ export interface SlotlockBookingRules {
      */
     slotStepMinutes?: number;
     /**
-     * Where the steps fall: this many minutes past each step from local midnight (with a 30-minute
-     * step, 15 starts bookings on :15 and :45): 0 to one less than the step. Without a step it is
-     * kept and does nothing.
+     * Offset of the steps from local midnight (with a 30-minute step, 15 starts bookings on :15 and
+     * :45): 0 to one less than the step. Ignored without a step.
      */
     stepOffsetMinutes?: number;
     /**
-     * Minutes kept free before each booking made under the rule (preparation, travel), as its
-     * leading buffer: the database refuses a booking whose time, or trailing buffer, reaches into
-     * it. 0-1,440. A booking made before the rule, or imported, keeps none.
+     * Minutes kept free before each booking made under the rule, as its leading buffer: 0-1,440.
+     * Bookings made before the rule, or imported, keep none.
      */
     bufferBeforeMinutes?: 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.
+     * Minutes kept free after each booking made under the rule, as its trailing buffer: 0-1,440.
+     * Bookings made before the rule, or imported, keep what they have.
      */
     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.
+     * A booking must be checked in within this many minutes of its start, or maintenance releases it
+     * (and offers it to the waitlist): 1-1,440. Only bookings made after 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.
+     * A booking must lie in time every sync covering the resource read within the last day
+     * (`recordCalendarCoverage`): time a stale or failing sync leaves unproven is refused
+     * (`uncertain`). A resource no sync covers is certain.
      */
     requireCertain?: boolean;
 }
@@ -62,20 +58,18 @@ export declare const SLOTLOCK_BOOKING_RULE_LIMITS: Readonly<{
 /** Booking rules from untrusted input, or a TypeError naming the field that is wrong. */
 export declare function parseBookingRules(value: unknown): SlotlockBookingRules;
 /**
- * The rules that apply to a resource, merged from its own and its pool's and tenant's defaults
- * (each validated when it was set), read leniently: each field is kept when it is valid on its own
- * and dropped (named in `dropped`) when not. No cross-field check: a merge may join a pool's offset
- * to a resource's own shorter step, and the offset then applies modulo the step. A merge never
- * reads as refusing every booking.
+ * The effective rules merged from the resource's own, its pool's and the tenant's (each validated
+ * when set), read leniently: each field is kept if valid alone, else named in `dropped`. A pool's
+ * offset over a resource's shorter step applies modulo the step. A merge never refuses every
+ * booking.
  */
 export declare function parseEffectiveBookingRules(value: unknown): {
     rules: SlotlockBookingRules;
     dropped: string[];
 };
 /**
- * Default booking rules for a tenant or a pool from untrusted input: booking rules without
- * `checkInMinutes`, which only a resource's own rules set (it releases the bookings made after it
- * was set, and that moment is the resource's).
+ * Tenant or pool default rules from untrusted input: no `checkInMinutes`, which only a resource's
+ * own rules set (it applies from the moment it was set on the resource).
  */
 export declare function parseBookingRuleDefaults(value: unknown): SlotlockBookingRules;
 /** The trailing buffer a booking made under the rules keeps: the larger of its own and the rule's. */
@@ -83,15 +77,14 @@ export declare function bookingBufferAfterMs(rules: SlotlockBookingRules | undef
 /** The leading buffer a booking made under the rules keeps. */
 export declare function bookingBufferBeforeMs(rules: SlotlockBookingRules | undefined): number;
 /**
- * The first instant at or after `from` that starts on a step in `timezone`, `offsetMinutes` past
- * each multiple of the step from local midnight (0 to the step less one). 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.
+ * The first instant at or after `from` on a step in `timezone`, `offsetMinutes` past each multiple
+ * of the step from local midnight. A step that does not divide the day restarts at local midnight;
+ * across a clock change it moves forward to the next local step.
  */
 export declare function nextStepStart(from: Date, stepMinutes: number, timezone: string, offsetMinutes?: number): 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.
+ * The rule a booking of `interval` made at `now` breaks, or null. `hours` (the resource's own, or
+ * the default) are read only when enforced.
  */
 export declare function bookingRuleBroken(params: {
     rules: SlotlockBookingRules | undefined;
@@ -113,8 +106,7 @@ export interface SlotlockBookingSearch {
 }
 /**
  * How a search honours the rules: the part of `window` a booking made at `now` may start in, the
- * buffers each slot keeps, and how a candidate start moves to a step. `null` when no start in the
- * window is allowed.
+ * buffers each slot keeps, and how a candidate moves to a step. `null` when no start is allowed.
  */
 export declare function bookingSearch(params: {
     rules: SlotlockBookingRules | undefined;
@@ -123,14 +115,11 @@ export declare function bookingSearch(params: {
     now: Date;
     bufferAfterMs?: number;
 }): SlotlockBookingSearch | null;
-/**
- * The time a search must read as free or busy: its window, widened by the buffers a slot in it
- * keeps (before its first start and after its last end).
- */
+/** The time a search must read as free or busy: its window widened by a slot's buffers. */
 export declare function bookingSearchReach(search: SlotlockBookingSearch): Interval;
 /**
- * Busy time as the slot times it rules out. A slot [s, s + d) keeping buffers occupies
- * [s - before, s + d + after), so it meets busy [b, e) exactly when [s, s + d) meets
- * [b - after, e + before): the database refuses the same booking.
+ * Busy time as the slot times it rules out: a slot [s, s + d) with buffers occupies [s - before, s
+ * + d + after), so it meets busy [b, e) exactly when [s, s + d) meets [b - after, e + before), as
+ * the database decides.
  */
 export declare function bookingSearchBlocked(busy: readonly Interval[], search: SlotlockBookingSearch): Interval[];

package/booking-rules.js

@@ -54,11 +54,10 @@ export function parseBookingRules(value) {
     return rules;
 }
 /**
- * The rules that apply to a resource, merged from its own and its pool's and tenant's defaults
- * (each validated when it was set), read leniently: each field is kept when it is valid on its own
- * and dropped (named in `dropped`) when not. No cross-field check: a merge may join a pool's offset
- * to a resource's own shorter step, and the offset then applies modulo the step. A merge never
- * reads as refusing every booking.
+ * The effective rules merged from the resource's own, its pool's and the tenant's (each validated
+ * when set), read leniently: each field is kept if valid alone, else named in `dropped`. A pool's
+ * offset over a resource's shorter step applies modulo the step. A merge never refuses every
+ * booking.
  */
 export function parseEffectiveBookingRules(value) {
     const rules = {};
@@ -88,9 +87,8 @@ export function parseEffectiveBookingRules(value) {
     return { rules, dropped };
 }
 /**
- * Default booking rules for a tenant or a pool from untrusted input: booking rules without
- * `checkInMinutes`, which only a resource's own rules set (it releases the bookings made after it
- * was set, and that moment is the resource's).
+ * Tenant or pool default rules from untrusted input: no `checkInMinutes`, which only a resource's
+ * own rules set (it applies from the moment it was set on the resource).
  */
 export function parseBookingRuleDefaults(value) {
     const rules = parseBookingRules(value);
@@ -123,10 +121,9 @@ function onStep(instant, stepMinutes, timezone, offset = 0) {
     return Number.isInteger(minutes) && minutes >= offset && (minutes - offset) % stepMinutes === 0;
 }
 /**
- * The first instant at or after `from` that starts on a step in `timezone`, `offsetMinutes` past
- * each multiple of the step from local midnight (0 to the step less one). 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.
+ * The first instant at or after `from` on a step in `timezone`, `offsetMinutes` past each multiple
+ * of the step from local midnight. A step that does not divide the day restarts at local midnight;
+ * across a clock change it moves forward to the next local step.
  */
 export function nextStepStart(from, stepMinutes, timezone, offsetMinutes = 0) {
     const offset = offsetMinutes % stepMinutes;
@@ -142,8 +139,8 @@ export function nextStepStart(from, stepMinutes, timezone, offsetMinutes = 0) {
     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.
+ * The rule a booking of `interval` made at `now` breaks, or null. `hours` (the resource's own, or
+ * the default) are read only when enforced.
  */
 export function bookingRuleBroken(params) {
     const { rules, interval, now } = params;
@@ -178,8 +175,7 @@ export function bookingRuleBroken(params) {
 }
 /**
  * How a search honours the rules: the part of `window` a booking made at `now` may start in, the
- * buffers each slot keeps, and how a candidate start moves to a step. `null` when no start in the
- * window is allowed.
+ * buffers each slot keeps, and how a candidate moves to a step. `null` when no start is allowed.
  */
 export function bookingSearch(params) {
     const { rules, window, now } = params;
@@ -195,7 +191,6 @@ export function bookingSearch(params) {
     const toStep = step === undefined ? undefined : (from) => nextStepStart(from, step, params.timezone, offset);
     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;
@@ -205,7 +200,7 @@ export function bookingSearch(params) {
             bufferBeforeMs,
             align: (from) => {
                 const aligned = toStep ? toStep(from) : from;
-                // Past the latest start, no slot: move it beyond the window so it cannot fit.
+                // Past the latest start: move it beyond the window so it cannot fit.
                 return aligned.getTime() > latestStart ? new Date(end + 1) : aligned;
             },
         };
@@ -216,10 +211,7 @@ export function bookingSearch(params) {
         ? { window: searched, bufferAfterMs, bufferBeforeMs }
         : { window: searched, bufferAfterMs, bufferBeforeMs, align: toStep };
 }
-/**
- * The time a search must read as free or busy: its window, widened by the buffers a slot in it
- * keeps (before its first start and after its last end).
- */
+/** The time a search must read as free or busy: its window widened by a slot's buffers. */
 export function bookingSearchReach(search) {
     return {
         start: new Date(search.window.start.getTime() - search.bufferBeforeMs),
@@ -227,9 +219,9 @@ export function bookingSearchReach(search) {
     };
 }
 /**
- * Busy time as the slot times it rules out. A slot [s, s + d) keeping buffers occupies
- * [s - before, s + d + after), so it meets busy [b, e) exactly when [s, s + d) meets
- * [b - after, e + before): the database refuses the same booking.
+ * Busy time as the slot times it rules out: a slot [s, s + d) with buffers occupies [s - before, s
+ * + d + after), so it meets busy [b, e) exactly when [s, s + d) meets [b - after, e + before), as
+ * the database decides.
  */
 export function bookingSearchBlocked(busy, search) {
     return busy.map((interval) => ({

package/change-watch.d.ts

@@ -45,6 +45,7 @@ export interface SlotlockChangeWatcher {
 export declare const SLOTLOCK_FEED_BUSY_MS = 250;
 /** How often a quiet tenant's feed is read, in ms: the poll backs off to this from the busy rate. */
 export declare const SLOTLOCK_FEED_IDLE_MS = 1000;
+export declare function unref<T>(timer: T): T;
 /**
  * The readers of one server process. `join` adds a watcher to its tenant's reader (starting it) and
  * returns the function that removes it (stopping the reader with its last watcher).

package/change-watch.js

@@ -17,7 +17,7 @@ export const SLOTLOCK_FEED_BUSY_MS = 250;
 export const SLOTLOCK_FEED_IDLE_MS = 1_000;
 /** How often a quiet feed is read while a custom source's `watch` is listening, in ms. */
 const FEED_LISTENING_IDLE_MS = 15_000;
-function unref(timer) {
+export function unref(timer) {
     timer.unref?.();
     return timer;
 }

package/cli.js

@@ -1,6 +1,5 @@
 #!/usr/bin/env node
-// The `slotlock` executable: process wiring only (arguments, environment, output streams, signals
-// and the exit code). The commands and their configuration live in self-host.ts.
+// The `slotlock` executable: process wiring only; the commands live in self-host.ts.
 import { runSlotlockCli } from './self-host.js';
 const shutdown = new AbortController();
 for (const signal of ['SIGINT', 'SIGTERM']) {
@@ -17,6 +16,6 @@ process.exitCode = await runSlotlockCli(process.argv.slice(2), {
     stderr: process.stderr,
     signal: shutdown.signal,
 });
-// Everything is closed by now, so the process ends on its own. Should a stray handle (a socket or
-// timer something else left open) keep it alive, exit anyway rather than hang a container stop.
+// Everything is closed, so the process should end on its own; exit anyway if a stray handle would
+// hang a container stop.
 setTimeout(() => process.exit(), 5_000).unref();

package/config.d.ts

@@ -48,8 +48,14 @@ export interface SlotlockServeDashboardConfig {
     assistantPrivateUrls?: boolean;
 }
 /**
- * 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.
+ * SLOTLOCK_DASHBOARD_USERS: `'*'`, GitHub user ids, or undefined when it is not set. A server whose
+ * dashboard runs elsewhere (a Worker) reads it too, so that removing a person there stops their keys.
+ */
+export declare function readDashboardUsers(env: SlotlockEnv): '*' | string[] | undefined;
+/**
+ * The dashboard's settings, or undefined when none of DASHBOARD_VARIABLES is set. Setting any of
+ * them means serving the dashboard, so the rest, and SLOTLOCK_DASHBOARD_USERS, are then required: a
+ * half-configured sign-in is a startup error.
  */
 export declare function readDashboardConfig(env: SlotlockEnv): SlotlockServeDashboardConfig | undefined;
 /**
@@ -154,4 +160,13 @@ export declare function readLimits(env: SlotlockEnv): SlotlockLimits;
  * only when nothing reaches the server except through that proxy.
  */
 export declare function readTrustedProxyHeader(env: SlotlockEnv): string | undefined;
+/** The request field that carries SLOTLOCK_TRUSTED_PROXY_SECRET; not cf-…, which Cloudflare's rules may not set. */
+export declare const SLOTLOCK_TRUSTED_PROXY_PROOF_FIELD = "x-slotlock-proxy-proof";
+/**
+ * SLOTLOCK_TRUSTED_PROXY_SECRET: a value the proxy in front adds to every request in
+ * SLOTLOCK_TRUSTED_PROXY_PROOF_FIELD, such as a Cloudflare transform rule. With it, the trusted
+ * proxy field is believed only beside that value, so a process that reaches the server without
+ * passing the proxy (another container on its network) cannot choose its own client address.
+ */
+export declare function readTrustedProxySecret(env: SlotlockEnv, trustedProxyHeader: string | undefined): string | undefined;
 export {};