slotlock 0.6.1 → 0.6.3

package/timezone.d.ts

@@ -8,9 +8,8 @@ export interface LocalDateTime {
     millisecond?: number;
 }
 /**
- * Which instant a wall time names where the clocks change. RFC 5545 §3.3.5 reads a time in a fold
- * (an hour the clocks repeat) as its first instant, and a time in a gap (an hour they skip) with the
- * offset in force before the gap, which moves it forward by the gap: the defaults.
+ * Which instant a wall time names where the clocks change. RFC 5545 §3.3.5 defaults: a fold
+ * (repeated hour) reads as its first instant, a gap (skipped hour) is moved forward by the gap.
  */
 export interface WallTimeChoice {
     /** In a fold: the earlier instant (default), or the later one. */
@@ -20,45 +19,41 @@ export interface WallTimeChoice {
 }
 export interface TimeZoneConverter {
     /**
-     * Convert UTC-framed wall-clock fields to the instant that reads as those fields in this zone.
-     * By default the first instant for a fold, and shifted forward by the gap for a hole.
+     * UTC-framed wall-clock fields to the instant that reads as them in this zone (WallTimeChoice
+     * defaults).
      */
     wallFrameToUtc(wallFrameMs: number, choice?: WallTimeChoice): Date;
 }
 /**
- * The instant, in ms, that reads as `wallFrameMs` (wall-clock fields framed as UTC) in a zone whose
- * offset at an instant `offsetAt` gives, in ms. The offsets in force within fourteen hours either
- * side are the candidates (no zone is further than that from UTC, so they include both sides of any
- * change the wall time is near); one that maps back to the wall time names it. Two do in a fold,
- * none in a gap, where the offset before the gap is the smaller one.
+ * The instant (ms) that reads as `wallFrameMs` (wall-clock fields framed as UTC) in a zone with
+ * offsets from `offsetAt`. Candidates are the offsets within fourteen hours either side (no zone is
+ * further from UTC); one that maps back names it. Two do in a fold, none in a gap.
  */
 export declare function wallFrameToInstant(wallFrameMs: number, offsetAt: (utcMs: number) => number, choice?: WallTimeChoice): number;
 /**
- * Date.UTC remaps years 0..99 to 1900..1999. Slotlock accepts ISO calendar years down to 1,
- * so construct UTC frames through setUTCFullYear instead of inheriting that legacy quirk.
+ * Date.UTC remaps years 0..99 to 1900..1999 and Slotlock accepts years down to 1, so frames are
+ * built with setUTCFullYear.
  */
 export declare function utcFrame(year: number, month: number, day: number, hour: number, minute: number, second: number, millisecond: number): Date;
 /** The UTC day an instant falls in, as ZoneOffsets reads a zone's offsets: days since 1970. */
 export declare function zoneOffsetDay(utcMs: number): number;
 /**
- * How far either side of a wall time converting it to its instant reads the zone's offsets: no zone
- * is further than this from UTC. The days from one end to the other hold every offset it reads.
+ * How far either side of a wall time its conversion reads offsets: no zone is further than this
+ * from UTC.
  */
 export declare const ZONE_OFFSET_REACH_MS: number;
 /**
- * How many instants reading `timezone`'s offsets on UTC day `day` asks Intl for with none of them
- * kept, beyond the day's two midnights (one each): about twenty to find each change between them.
- * A caller that must charge the same for an input however much the process has kept charges each
- * midnight and this the first time it reads them.
+ * How many Intl reads finding the changes on UTC day `day` takes beyond its two midnights (about
+ * twenty per change). Callers that must charge the same whatever the process has cached charge this
+ * on first read.
  */
 export declare function zoneOffsetChangeReads(timezone: string, day: number): number;
 export declare function createTimeZoneConverter(timezone: string): TimeZoneConverter;
 /**
- * The spelling Slotlock keeps of an IANA zone name: Intl's, when Intl reads the name as itself in
- * another case (`europe/london` is `Europe/London`); otherwise the name as given (`US/Eastern` stays,
- * although this Node's ICU may call it `America/New_York`, so a stored name never depends on the
- * ICU version that wrote it). A UTC offset (`+05:00`, which Intl accepts as a zone) is not an IANA
- * name and is refused, as is anything Intl does not know: both with `code: 'invalid_timezone'`.
+ * The spelling Slotlock keeps of an IANA zone: Intl's when it reads the name as itself in another
+ * case (`europe/london` is `Europe/London`), else the name as given (`US/Eastern` stays, so a
+ * stored name never depends on the ICU version). A UTC offset such as `+05:00` and unknown names
+ * are refused with `code: 'invalid_timezone'`.
  */
 export declare function canonicalTimeZoneName(timezone: string): string;
 export interface ZonedCalendarDate {
@@ -68,9 +63,8 @@ export interface ZonedCalendarDate {
     isoWeekday: number;
 }
 /**
- * The civil date and ISO weekday an instant falls on in `timezone` — the inverse direction of
- * {@link zonedDateTimeToUtc}. Pricing reads "which day is this night" through here so a pickup at
- * 00:30 BST on a Friday is a Friday, not the Thursday its UTC timestamp reads as.
+ * The civil date and ISO weekday an instant falls on in `timezone` (the inverse of {@link
+ * zonedDateTimeToUtc}): a pickup at 00:30 BST on a Friday is a Friday, whatever UTC says.
  */
 export declare function zonedCalendarDate(instant: Date, timezone: string): ZonedCalendarDate;
 export interface ZonedWallTime {
@@ -80,9 +74,8 @@ export interface ZonedWallTime {
     time: string;
 }
 /**
- * The civil date and wall-clock time an instant reads as in `timezone`. Agreements and receipts
- * state a booking's start and end as a date and a time on the resource's own clock, not the
- * server's and not UTC.
+ * The civil date and wall-clock time an instant reads as in `timezone`, as agreements and receipts
+ * state a booking: on the resource's own clock.
  */
 export declare function zonedWallTime(instant: Date, timezone: string): ZonedWallTime;
 /** How far `timezone` is ahead of UTC at `instant`, in whole minutes (negative west of UTC). */
@@ -98,7 +91,7 @@ export interface ZonedDateTimeFields {
 }
 /**
  * The wall-clock fields an instant reads as in `timezone`, to the second: what a calendar writes
- * beside a TZID. Reads through the cached formatters, as every conversion here does.
+ * beside a TZID.
  */
 export declare function zonedDateTimeFields(instant: Date, timezone: string): ZonedDateTimeFields;
 export declare function zonedDateTimeToUtc(value: LocalDateTime, timezone: string, choice?: WallTimeChoice): Date;
@@ -111,8 +104,7 @@ export interface ZoneTransition {
     after: number;
 }
 /**
- * Every change of `timezone`'s offset from `fromMs` to `toMs`, as Intl reads the zone, from its
- * offsets a day at a time (ZoneOffsets): Gaza's clocks go forward on 20 October 2040 and back six
- * days later, which a search a week at a time missed.
+ * Every change of `timezone`'s offset from `fromMs` to `toMs`, read a day at a time (ZoneOffsets):
+ * a weekly search misses short-lived changes such as Gaza's six-day one in October 2040.
  */
 export declare function zoneTransitions(timezone: string, fromMs: number, toMs: number): ZoneTransition[];

package/timezone.js

@@ -1,10 +1,8 @@
 const FOURTEEN_HOURS_MS = 14 * 60 * 60 * 1000;
 /**
- * The instant, in ms, that reads as `wallFrameMs` (wall-clock fields framed as UTC) in a zone whose
- * offset at an instant `offsetAt` gives, in ms. The offsets in force within fourteen hours either
- * side are the candidates (no zone is further than that from UTC, so they include both sides of any
- * change the wall time is near); one that maps back to the wall time names it. Two do in a fold,
- * none in a gap, where the offset before the gap is the smaller one.
+ * The instant (ms) that reads as `wallFrameMs` (wall-clock fields framed as UTC) in a zone with
+ * offsets from `offsetAt`. Candidates are the offsets within fourteen hours either side (no zone is
+ * further from UTC); one that maps back names it. Two do in a fold, none in a gap.
  */
 export function wallFrameToInstant(wallFrameMs, offsetAt, choice = {}) {
     const offsets = new Set([
@@ -25,8 +23,8 @@ export function wallFrameToInstant(wallFrameMs, offsetAt, choice = {}) {
     const shifted = wallFrameMs - Math.min(...offsets);
     if (choice.gap !== 'end')
         return shifted;
-    // The gap ends at the change: the first whole second after the instant read with the offset
-    // after the gap (which is still before it) whose offset differs from that one's.
+    // The gap ends at the change: the first whole second after the instant read with the after-gap
+    // offset whose offset differs from it.
     let before = wallFrameMs - Math.max(...offsets);
     const offsetBefore = offsetAt(before);
     let after = shifted;
@@ -40,8 +38,8 @@ export function wallFrameToInstant(wallFrameMs, offsetAt, choice = {}) {
     return after;
 }
 /**
- * Date.UTC remaps years 0..99 to 1900..1999. Slotlock accepts ISO calendar years down to 1,
- * so construct UTC frames through setUTCFullYear instead of inheriting that legacy quirk.
+ * Date.UTC remaps years 0..99 to 1900..1999 and Slotlock accepts years down to 1, so frames are
+ * built with setUTCFullYear.
  */
 export function utcFrame(year, month, day, hour, minute, second, millisecond) {
     const frame = new Date(0);
@@ -50,10 +48,8 @@ export function utcFrame(year, month, day, hour, minute, second, millisecond) {
     return frame;
 }
 /**
- * Formatters already built, by zone name. Building one costs far more than using it, and every
- * conversion needs one: a recurring series reads about three times an occurrence. A formatter never
- * changes, so one per zone serves every caller. Intl accepts every capitalisation of each zone's
- * name, so the map is emptied when it fills rather than growing with whatever names arrive.
+ * Formatters by zone name: building one costs far more than using it. Intl accepts any
+ * capitalisation of a name, so the map is emptied when full rather than growing.
  */
 const formatters = new Map();
 const MAX_CACHED_FORMATTERS = 256;
@@ -75,21 +71,19 @@ export function zoneOffsetDay(utcMs) {
     return Math.floor(utcMs / DAY_MS);
 }
 /**
- * How far either side of a wall time converting it to its instant reads the zone's offsets: no zone
- * is further than this from UTC. The days from one end to the other hold every offset it reads.
+ * How far either side of a wall time its conversion reads offsets: no zone is further than this
+ * from UTC.
  */
 export const ZONE_OFFSET_REACH_MS = FOURTEEN_HOURS_MS;
 /** How many midnights one block of a zone's offsets holds. */
 const BLOCK_DAYS = 512;
 const NO_CHANGES = [];
 /**
- * A zone's offsets, read from Intl a UTC day at a time and kept. Intl's formatToParts takes about
- * two microseconds and a conversion asks for four to six offsets, so a series that converts a time
- * at each of thousands of occurrences spent most of its time there (forty daily London series from
- * 2016, 35 seconds). Each UTC midnight's offset is read once; a day whose two midnights agree has
- * that offset throughout, and one whose midnights differ has each change in it narrowed to the
- * second (scanTransitions). A change and its reversal within one day would be missed; the tests
- * compare the zones whose clocks change most with an hourly search.
+ * A zone's offsets, read from Intl a UTC day at a time and kept: formatToParts costs about two
+ * microseconds and a conversion needs four to six offsets. Each midnight is read once; a day whose
+ * midnights agree has that offset throughout, and a day whose midnights differ has each change
+ * narrowed to the second (scanTransitions). A change and its reversal within one day would be
+ * missed; tests check the most volatile zones against an hourly search.
  */
 class ZoneOffsets {
     /** The offset at each UTC midnight read (NaN where none is), BLOCK_DAYS days to a block. */
@@ -102,7 +96,7 @@ class ZoneOffsets {
     }
     offsetAt(utcMs) {
         const day = zoneOffsetDay(utcMs);
-        // Not a time value: Intl refuses it, as it always has.
+        // Not a time value: let Intl refuse it.
         if (!Number.isFinite(day))
             return offsetAt(utcMs, this.formatter);
         let offset = this.midnight(day);
@@ -170,10 +164,8 @@ function dayStart(day) {
     return Math.min(Math.max(day * DAY_MS, -MAX_TIME_MS), MAX_TIME_MS);
 }
 /**
- * Each zone's offsets, by name, as createFormatter keeps formatters. A block of midnights takes 4
- * KB; once there are this many (16 MB, about 57 zone-centuries), every zone's are emptied, and so
- * are the days with changes once there are this many of those (zones change twice a year at most
- * but for a few).
+ * Each zone's offsets by name. A block of midnights is 4 KB; past this many blocks (16 MB) every
+ * zone's are emptied, and likewise for days with changes.
  */
 const zoneOffsetTables = new Map();
 const MAX_CACHED_BLOCKS = 4_096;
@@ -194,10 +186,9 @@ function zoneOffsets(timezone) {
     return offsets;
 }
 /**
- * How many instants reading `timezone`'s offsets on UTC day `day` asks Intl for with none of them
- * kept, beyond the day's two midnights (one each): about twenty to find each change between them.
- * A caller that must charge the same for an input however much the process has kept charges each
- * midnight and this the first time it reads them.
+ * How many Intl reads finding the changes on UTC day `day` takes beyond its two midnights (about
+ * twenty per change). Callers that must charge the same whatever the process has cached charge this
+ * on first read.
  */
 export function zoneOffsetChangeReads(timezone, day) {
     if (timezone === 'UTC')
@@ -222,8 +213,8 @@ function buildFormatter(timezone) {
     }
 }
 function offsetAt(utcMs, formatter) {
-    // Intl parts expose seconds but not milliseconds. Compute the zone offset against the same
-    // whole-second instant so sub-second input does not leak into the offset and get rounded away.
+    // Intl parts expose seconds, not milliseconds: compute the offset at the whole second so
+    // sub-second input is not rounded into it.
     const wholeSecondMs = Math.floor(utcMs / 1000) * 1000;
     const values = {};
     for (const part of formatter.formatToParts(new Date(wholeSecondMs))) {
@@ -246,11 +237,10 @@ export function createTimeZoneConverter(timezone) {
     };
 }
 /**
- * The spelling Slotlock keeps of an IANA zone name: Intl's, when Intl reads the name as itself in
- * another case (`europe/london` is `Europe/London`); otherwise the name as given (`US/Eastern` stays,
- * although this Node's ICU may call it `America/New_York`, so a stored name never depends on the
- * ICU version that wrote it). A UTC offset (`+05:00`, which Intl accepts as a zone) is not an IANA
- * name and is refused, as is anything Intl does not know: both with `code: 'invalid_timezone'`.
+ * The spelling Slotlock keeps of an IANA zone: Intl's when it reads the name as itself in another
+ * case (`europe/london` is `Europe/London`), else the name as given (`US/Eastern` stays, so a
+ * stored name never depends on the ICU version). A UTC offset such as `+05:00` and unknown names
+ * are refused with `code: 'invalid_timezone'`.
  */
 export function canonicalTimeZoneName(timezone) {
     const name = timezone.trim();
@@ -269,9 +259,8 @@ export function canonicalTimeZoneName(timezone) {
     return resolved.toLowerCase() === name.toLowerCase() ? resolved : name;
 }
 /**
- * The civil date and ISO weekday an instant falls on in `timezone` — the inverse direction of
- * {@link zonedDateTimeToUtc}. Pricing reads "which day is this night" through here so a pickup at
- * 00:30 BST on a Friday is a Friday, not the Thursday its UTC timestamp reads as.
+ * The civil date and ISO weekday an instant falls on in `timezone` (the inverse of {@link
+ * zonedDateTimeToUtc}): a pickup at 00:30 BST on a Friday is a Friday, whatever UTC says.
  */
 export function zonedCalendarDate(instant, timezone) {
     const wall = wallFrame(instant, timezone);
@@ -279,9 +268,8 @@ export function zonedCalendarDate(instant, timezone) {
     return { date: civilDate(wall), isoWeekday: weekday === 0 ? 7 : weekday };
 }
 /**
- * The civil date and wall-clock time an instant reads as in `timezone`. Agreements and receipts
- * state a booking's start and end as a date and a time on the resource's own clock, not the
- * server's and not UTC.
+ * The civil date and wall-clock time an instant reads as in `timezone`, as agreements and receipts
+ * state a booking: on the resource's own clock.
  */
 export function zonedWallTime(instant, timezone) {
     const wall = wallFrame(instant, timezone);
@@ -295,7 +283,7 @@ export function zonedOffsetMinutes(instant, timezone) {
 }
 /**
  * The wall-clock fields an instant reads as in `timezone`, to the second: what a calendar writes
- * beside a TZID. Reads through the cached formatters, as every conversion here does.
+ * beside a TZID.
  */
 export function zonedDateTimeFields(instant, timezone) {
     const wall = wallFrame(instant, timezone);
@@ -356,9 +344,8 @@ export function zonedDateTimeToUtc(value, timezone, choice) {
     return createTimeZoneConverter(timezone).wallFrameToUtc(wallFrame, choice);
 }
 /**
- * Every change of `timezone`'s offset from `fromMs` to `toMs`, as Intl reads the zone, from its
- * offsets a day at a time (ZoneOffsets): Gaza's clocks go forward on 20 October 2040 and back six
- * days later, which a search a week at a time missed.
+ * Every change of `timezone`'s offset from `fromMs` to `toMs`, read a day at a time (ZoneOffsets):
+ * a weekly search misses short-lived changes such as Gaza's six-day one in October 2040.
  */
 export function zoneTransitions(timezone, fromMs, toMs) {
     if (timezone === 'UTC')
@@ -366,9 +353,8 @@ export function zoneTransitions(timezone, fromMs, toMs) {
     return zoneOffsets(timezone).transitions(Math.floor(fromMs / 1000) * 1000, Math.ceil(toMs / 1000) * 1000);
 }
 /**
- * The changes of the offset `offsetIn` reads from `fromMs` to `toMs`, found by comparing offsets
- * `stepMs` apart and narrowing each change to the second: a change and its reversal both within
- * one step are missed.
+ * Offset changes found by comparing `offsetIn` `stepMs` apart and narrowing each to the second; a
+ * change and its reversal within one step are missed.
  */
 function scanTransitions(offsetIn, fromMs, toMs, stepMs) {
     const found = [];
@@ -380,7 +366,6 @@ function scanTransitions(offsetIn, fromMs, toMs, stepMs) {
             at = next;
             continue;
         }
-        // The last whole second at `offset` and the first at another.
         let low = at;
         let high = next;
         while (high - low > 1000) {

package/types.d.ts

@@ -11,10 +11,9 @@ export interface SlotlockResource {
     /** Null only for legacy/parity-shadow resources created before authority primitives existed. */
     tenantRef: string | null;
     /**
-     * IANA timezone the resource's availability rules are authored in. expandRules evaluates
-     * BYDAY/startMinutes as LOCAL wall-clock in this zone (DST-correct, wall-clock ends);
-     * findNextAvailableFor reads it from the stored resource. Formerly the documented
-     * Rules remain stable across daylight-saving changes because wall time is resolved in this zone.
+     * IANA timezone the availability rules are authored in: expandRules evaluates BYDAY and
+     * startMinutes as local wall-clock time in this zone, so rules stay stable across daylight-saving
+     * changes.
      */
     timezone: string;
     /**
@@ -23,9 +22,8 @@ export interface SlotlockResource {
      */
     availabilityRules?: WeeklyAvailabilityRule[];
     /**
-     * `shared` resources are listed to agents and booked through them; `private` ones are invisible
-     * to agents and reached only by the tenant's own code. Fixed when the resource is created. The
-     * store always says which; a resource built elsewhere without it is shared.
+     * `shared` resources are listed to and booked by agents; `private` ones are invisible to agents.
+     * Fixed at creation; absent means shared.
      */
     visibility?: 'shared' | 'private';
     /** When the tenant archived it: no longer listed or booked, its history kept. Absent in use. */
@@ -33,14 +31,13 @@ export interface SlotlockResource {
     /** Its own booking rules (`SlotlockBookingRules`). Absent when it has none. */
     bookingRules?: SlotlockBookingRules;
     /**
-     * What a booking on it must satisfy: the tenant's default rules, overlaid by its pool's, overlaid
-     * by its own (`setBookingRuleDefaults`), a field set at a narrower level winning. Absent when no
-     * rule applies.
+     * What a booking on it must satisfy: tenant defaults, overlaid by its pool's, overlaid by its own
+     * (`setBookingRuleDefaults`). Absent when no rule applies.
      */
     effectiveBookingRules?: SlotlockBookingRules;
     /**
-     * The pool it belongs to: interchangeable resources sharing a name, such as a vehicle class or a
-     * room type, booked by the class (`slotlock_book_pool`). Absent when it is in none.
+     * Its pool: interchangeable resources (a vehicle class, a room type) booked by the class
+     * (`slotlock_book_pool`).
      */
     pool?: string;
 }
@@ -48,10 +45,7 @@ export interface SlotlockResource {
 export interface SlotlockReservation {
     id: string;
     resourceId: string;
-    /**
-     * Null only for live holds, rows on a resource that has no tenant (legacy), and parity-shadow rows.
-     * A booking made by confirming a hold, or by createReservation, on a tenant's resource has one.
-     */
+    /** Null only for live holds, rows on a tenantless (legacy) resource, and parity-shadow rows. */
     tenantRef: string | null;
     /**
      * Stable booking identity inside tenantRef; null exactly when tenantRef is. A confirmed hold, and
@@ -170,17 +164,15 @@ export type CancelExternalReservationResult = {
     limit: number;
 };
 /**
- * VAVAILABILITY-style bookable window (RFC 7953 semantics, weekly subset): a weekly-cadence RRULE
- * picks the days; the window on each matching day runs `[startMinutes, startMinutes+durationMinutes)`
- * after that day's local midnight in the evaluation timezone (`expandRules`' `timezone`, the
- * resource's stored zone for `findNextAvailableFor`, UTC when none is given).
+ * VAVAILABILITY-style bookable window (RFC 7953, weekly subset): a weekly RRULE picks the days, and
+ * each day's window is `[startMinutes, startMinutes+durationMinutes)` after local midnight in the
+ * evaluation timezone (UTC when none is given).
  */
 export interface WeeklyAvailabilityRule {
     /** RRULE content line without the `RRULE:` prefix, e.g. `FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR`. */
     rrule: string;
-    /** Window start, minutes after midnight in the evaluation timezone (UTC when none is given) of each matching day (0..1439). */
+    /** Window start, minutes after local midnight (0..1439). */
     startMinutes: number;
-    /** Window length in minutes (> 0). */
     durationMinutes: number;
 }
 export type CreateReservationResult = {
@@ -243,7 +235,6 @@ export interface SlotlockAgendaEntry {
     resourceId: string;
     start: Date;
     end: Date;
-    /** A booking, a calendar event's occurrence, or a live hold. */
     kind: 'booking' | 'event' | 'hold';
     /** The booking's reference; null for an event's occurrence and a hold. */
     reference: string | null;
@@ -447,18 +438,17 @@ export interface PutCalendarEventCommand extends CalendarEventContent {
     materializationWindow?: Interval;
     source?: string;
     /**
-     * Judge the event as a booking made now against the resource's booking rules (its first
-     * occurrence for notice and advance, every occurrence for step and hours), and keep the
-     * resource's turnaround after each occurrence. Off by default: an imported event is what happened
-     * elsewhere. The agent tools set it.
+     * Judge the event as a booking made now against the resource's booking rules (first occurrence
+     * for notice and advance, every occurrence for step and hours), and keep the resource's
+     * turnaround. Off by default, since an imported event already happened elsewhere; the agent tools
+     * set it.
      */
     enforceBookingRules?: boolean;
     /**
-     * Book the time a live hold keeps: the hold must be `holderRef`'s (`acquireHold`'s
-     * `principalRef`), on this resource, and cover the event, a single occurrence. In one transaction
-     * the hold and the rest of its group are released and the event takes the time, so no rival can
-     * come between. Its notice and advance were judged when it was held; step and hours are judged
-     * again.
+     * Book the time a live hold keeps: the hold must be `holderRef`'s, on this resource, and cover
+     * the event (a single occurrence). The hold's group is released and the event takes the time in
+     * one transaction, so no rival can come between. Notice and advance were judged at hold time;
+     * step and hours are judged again.
      */
     fromHold?: {
         holdId: string;
@@ -581,14 +571,11 @@ export type CancelCalendarEventResult = {
     code: 'revision_conflict';
     currentRevision: number;
 };
-/**
- * A place in the roll's order of due masters: the last one a batch examined. The roll takes the
- * masters it has never put back first, then those it has, longest waiting first.
- */
+/** A place in the roll's order of due masters: the last one a batch examined. */
 export interface CalendarHorizonRollCursor {
     /**
-     * When the master was due to be examined again, if the roll had put it back; null (or, from a
-     * cursor of an earlier release, missing) when it had not.
+     * When the master was due again, if the roll had deferred it; null (or missing, from an older
+     * cursor) when not.
      */
     rollRetryAt?: Date | null;
     materializedEndsAt: Date;
@@ -596,34 +583,27 @@ export interface CalendarHorizonRollCursor {
 }
 /** Content-minimized outcome of one bounded recurring-event horizon maintenance batch. */
 export interface CalendarHorizonRollResult {
-    /** Due recurring masters examined in deterministic order. */
     examined: number;
     /**
-     * Masters atomically rematerialized from the requested window's start through the later of their
-     * stored end and the window's: a roll never moves a series' end back.
+     * Masters rematerialized through the later of their stored end and the window's: a roll never
+     * moves a series' end back.
      */
     extended: number;
-    /**
-     * Masters whose new occurrence collided; their previous coverage remains intact, and they wait an
-     * hour before a roll examines them again, behind every master it has not put back.
-     */
+    /** Masters whose new occurrence collided: their coverage stays, and they are deferred an hour. */
     conflicts: number;
     /** The ids of those masters: what blocks each is a booking or hold on its new occurrences. */
     conflictEventIds: string[];
     /**
-     * Masters whose rule takes more than the expansion budget to reach the window (one that never
-     * occurs again, or almost never), or whose roll failed for any other reason; their previous
-     * coverage remains intact, and they wait an hour
-     * before a roll examines them again, behind every master it has not put back.
+     * Masters over the expansion budget, or whose roll failed otherwise: their coverage stays, and
+     * they are deferred an hour.
      */
     refused: number;
-    /** The ids of those masters, to find and fix them. */
     refusedEventIds: string[];
     /** True when more due masters remain beyond this bounded batch. */
     hasMore: boolean;
     /**
-     * Pass as `after` for the next batch of this pass, so the masters this batch examined are not
-     * examined again by every later batch. `null` when none remain.
+     * Pass as `after` for the next batch, so this batch's masters are not examined again. `null` when
+     * none remain.
      */
     next: CalendarHorizonRollCursor | null;
 }
@@ -635,7 +615,6 @@ export interface CalendarEventRetentionResult {
     /** True when either class filled its batch, so more rows may already be eligible. */
     hasMore: boolean;
 }
-/** What erasing a tenant deleted. */
 /** A tenant's default booking rules (`SlotlockStore.getBookingRuleDefaults`). */
 export interface SlotlockBookingRuleDefaults {
     /** The tenant's own defaults, under every pool's; null when it has none. */
@@ -650,13 +629,13 @@ export interface SlotlockTenantErasure {
     total: number;
 }
 export interface BookingRetentionResult {
-    /** Holds past their expiry: they occupy nothing, and only a rival's write would reap them. */
+    /** Holds past their expiry: they occupy nothing, but only a rival's write would reap them. */
     expiredHoldsDeleted: number;
     /** Keyed hold answers whose hold has expired: a retry with that key makes a new hold. */
     holdCommandsDeleted: number;
     /**
-     * References a cancel retired with no booking, older than the window: a create with one makes a
-     * new booking. A cancelled booking's reference stays retired.
+     * References a cancel retired with no booking, older than the window. A cancelled booking's
+     * reference stays retired.
      */
     tombstonesDeleted: number;
     /** True when any class filled its batch, so more rows may already be eligible. */

package/webhooks.d.ts

@@ -17,13 +17,13 @@ export interface SlotlockCloudEvent {
 }
 /**
  * A change as CloudEvents 1.0 (structured mode): `type` is `io.pylota.slotlock.<change type>`, with
- * the extension attributes `slotlockorigin` and `slotlockkeyid` when the change records them. A
- * `coverage.*` change is redacted as the feed serves it (slotlockServedChange), whoever built it.
+ * `slotlockorigin` and `slotlockkeyid` when recorded. A `coverage.*` change is redacted as the feed
+ * serves it (slotlockServedChange).
  */
 export declare function slotlockCloudEvent(change: SlotlockChange): SlotlockCloudEvent;
 /**
- * The Standard Webhooks signature of one attempt: `v1,` and the base64 HMAC-SHA256, keyed by the
- * secret's bytes, of `id.timestamp.body`.
+ * The Standard Webhooks signature: `v1,` and the base64 HMAC-SHA256 of `id.timestamp.body`, keyed
+ * by the secret's bytes.
  */
 export declare function signSlotlockWebhook(params: {
     secret: string;
@@ -32,9 +32,8 @@ export declare function signSlotlockWebhook(params: {
     body: string;
 }): string;
 /**
- * When to try a failed endpoint again, by how many attempts have failed in a row: the Standard
- * Webhooks example schedule (5 s, 5 min, 30 min, 2 h, 5 h, then 10 h), with ±10% jitter, and never
- * sooner than the endpoint's Retry-After (capped at a day).
+ * Retry delay by consecutive failures: the Standard Webhooks example schedule (5 s, 5 min, 30 min,
+ * 2 h, 5 h, then 10 h) with ±10% jitter, never sooner than Retry-After (capped at a day).
  */
 export declare function slotlockWebhookRetryDelayMs(attempts: number, retryAfterMs?: number, random?: () => number): number;
 /** Whether `address` is one a webhook may not reach: loopback, private, link-local, and the like. */
@@ -50,19 +49,18 @@ export type SlotlockWebhookSender = (request: {
     body: string;
 }) => Promise<SlotlockWebhookResponse>;
 /**
- * POST with Node's http client: no redirect is followed, the answer's body is never read beyond
- * 64 KiB, and every address the host resolves to is checked when the socket connects, so a name
- * that resolves to a private network (or is rebound to one) is refused unless `allowPrivateNetworks`.
+ * POST with Node's http client: no redirect is followed, at most 64 KiB of body is read, and every
+ * resolved address is checked at connect time, so a name resolving (or rebound) to a private
+ * network is refused unless `allowPrivateNetworks`.
  */
 export declare function createSlotlockWebhookSender(options?: {
     timeoutMs?: number;
     allowPrivateNetworks?: boolean;
 }): SlotlockWebhookSender;
 /**
- * A `dns.lookup` that answers every address a name resolves to, and refuses (an error with `code`)
- * a name with any private one unless `allowPrivateNetworks`. Given to a socket's connect, it checks
- * the addresses the connection will use, so a name rebound to a private address after an earlier
- * check is still refused. `resolve` stands in for `dns.lookup` (tests).
+ * A `dns.lookup` that returns every address and refuses (with `code`) a name with any private one
+ * unless `allowPrivateNetworks`. Used at socket connect, so a rebound name is still refused.
+ * `resolve` stands in for `dns.lookup` in tests.
  */
 export declare function slotlockPrivateAddressLookup(options: {
     allowPrivateNetworks: boolean;
@@ -71,11 +69,10 @@ export declare function slotlockPrivateAddressLookup(options: {
     resolve?: typeof dnsLookup;
 }): typeof dnsLookup;
 /**
- * A `fetch` for a server reaching a URL a tenant chose (the dashboard assistant's model): Node's
- * http client with the webhooks' address check. A URL naming a private address, or a host that
- * resolves to one when the socket connects, is refused with an error whose `code` is
- * `private_address`, unless `allowPrivateNetworks`. No redirect is followed (the answer is
- * returned as is) and no proxy from the environment is used. Takes a string body only.
+ * A `fetch` for URLs a tenant chose (the assistant's model), with the webhooks' address check: a
+ * private address or a host resolving to one at connect time is refused with `code`
+ * `private_address` unless `allowPrivateNetworks`. No redirects, no environment proxy, string
+ * bodies only.
  */
 export declare function createSlotlockGuardedFetch(options?: {
     allowPrivateNetworks?: boolean;
@@ -88,9 +85,9 @@ export interface SlotlockWebhookPassResult {
     failed: number;
 }
 /**
- * One delivery pass for a tenant: claim each endpoint with changes due, send them in order until
- * one fails, and record how far each got. A 2xx is delivered; 410 disables the endpoint; anything
- * else, or no answer, is retried on the schedule. The send happens outside any transaction.
+ * One delivery pass for a tenant: claim each endpoint with changes due, send in order until one
+ * fails, and record progress. 2xx is delivered; 410 disables the endpoint; anything else is retried
+ * on the schedule. Sending happens outside any transaction.
  */
 export declare function deliverSlotlockWebhooks(params: {
     feed: Pick<SlotlockEventFeed, 'claimWebhookDeliveries' | 'settleWebhookDelivery'>;
@@ -108,9 +105,9 @@ export interface SlotlockWebhookScheduler {
     close(): Promise<void>;
 }
 /**
- * Delivery passes every `intervalMs` (250-60,000, default 2,000) for the tenants `tenants()` lists
- * (the store's webhook_tenants(), say) and those touched, one tenant at a time. A pass that fails
- * is reported and the next one runs as usual.
+ * Delivery passes every `intervalMs` (250-60,000, default 2,000) for `tenants()` (the store's
+ * webhook_tenants(), say) and touched tenants. A failed pass is reported and the next runs as
+ * usual.
  */
 export declare function startSlotlockWebhookDelivery(options: {
     tenants: () => Promise<readonly string[]>;