slotlock 0.6.2 → 0.6.3

package/store.js

@@ -1,6 +1,4 @@
-// DB mechanics for the Slotlock core — explicit `postgres` client in, structured results out.
-// Domain policy (who may reserve, pricing, holds) belongs to future callers; this layer owns the
-// reliable how: idempotent schema apply, EXCLUDE-arbitrated inserts with a structured conflict.
+// DB mechanics for the Slotlock core: explicit `postgres` client in, structured results out.
 import { SLOTLOCK_CHANGE_ORIGINS, SLOTLOCK_CHANGE_RETENTION_DAYS, isSlotlockChangeOrigin, slotlockEventFeedMethods, } from './event-feed.js';
 import { bookingBufferBeforeMs, bookingSearchBlocked, bookingSearchReach, parseBookingRuleDefaults, parseEffectiveBookingRules, bookingBufferAfterMs, bookingRuleBroken, bookingSearch, parseBookingRules, } from './booking-rules.js';
 import { createHash, randomUUID } from 'node:crypto';
@@ -10,44 +8,36 @@ import { findNextAvailable, mergeIntervals } from './engine.js';
 import { SLOTLOCK_CALENDAR_HORIZON_DAYS, assertBoundedSearchWindow, expandRules, invalidWindowError, } from './rules.js';
 import { CalendarContractError, CalendarExpansionLimitError, expandCalendarEventSeries, normalizeCalendarEventContent, } from './sync.js';
 import { parseAvailabilityRules } from './weekly-hours.js';
-/** Postgres exclusion_violation — the EXCLUDE constraint fired. */
 const EXCLUSION_VIOLATION = '23P01';
 /**
- * Concurrent inserts checking the same EXCLUDE range can deadlock inside the constraint check
- * itself (probed at ~30-40% under two-way contention — intrinsic to Postgres EXCLUDE, present
- * for raw inserts too). A 40P01 victim's transaction is fully rolled back, so one retry either
- * wins cleanly or loses with a proper 23P01 — both structured. Never surfaced raw.
+ * Concurrent inserts on the same EXCLUDE range can deadlock inside the constraint check itself
+ * (intrinsic to Postgres EXCLUDE). The victim is fully rolled back, so one retry either wins or
+ * loses with a structured 23P01.
  */
 const DEADLOCK_DETECTED = '40P01';
 const SERIALIZATION_FAILURE = '40001';
-/** Holds are negotiation-scoped; a week is already generous. Beyond it is a caller bug. */
+/** Holds are negotiation-scoped; a week is already generous. */
 const MAX_HOLD_TTL_MS = 7 * 24 * 60 * 60 * 1000;
-/** Turnaround cannot occupy a resource indefinitely because of a caller/unit error. */
+/** Guards against a caller unit error occupying a resource indefinitely. */
 const MAX_BUFFER_AFTER_MS = 30 * 24 * 60 * 60 * 1000;
-/**
- * The longest leading buffer a row keeps (a day, as bufferBeforeMinutes allows): a row's occupied
- * time starts at most this long before its start, so a read by start can still use the index.
- */
+/** A day, as bufferBeforeMinutes allows: a read by start can then still use the index. */
 const MAX_BUFFER_BEFORE_MS = 24 * 60 * 60 * 1000;
 export { SLOTLOCK_CALENDAR_HORIZON_DAYS };
 /**
- * Longest one-off event the store accepts (ten years and some leap days): long enough for any lease
- * or long-term rental, short enough that a unit error cannot occupy a resource for ever. A recurring
- * series is bounded by its 367-day materialization window instead.
+ * Longest one-off event (ten years and some leap days); a recurring series is bounded by its
+ * materialization window instead.
  */
 export const SLOTLOCK_MAX_EVENT_DURATION_DAYS = 3_660;
 const DAY_MS = 24 * 60 * 60 * 1000;
 const MAX_CALENDAR_WINDOW_MS = SLOTLOCK_CALENDAR_HORIZON_DAYS * DAY_MS;
 /**
- * Longest window a recurring series is stored (materialized) for: the 367-day search window plus
- * two days. The rolling horizon starts a day before the current UTC day and must reach 367 days
- * past its end, so that a search of the full 367 days from any moment of the day is complete.
+ * The 367-day search window plus two days: the rolling horizon starts a day before the current UTC
+ * day and must reach 367 days past its end.
  */
 export const SLOTLOCK_MATERIALIZATION_WINDOW_DAYS = SLOTLOCK_CALENDAR_HORIZON_DAYS + 2;
 const MAX_MATERIALIZATION_WINDOW_MS = SLOTLOCK_MATERIALIZATION_WINDOW_DAYS * DAY_MS;
 const MAX_EVENT_DURATION_MS = SLOTLOCK_MAX_EVENT_DURATION_DAYS * DAY_MS;
 const MAX_RESOURCE_LIST_LIMIT = 1_000;
-/** Highest per-tenant resource cap `createResource` accepts. */
 const MAX_TENANT_RESOURCE_LIMIT = 100_000;
 const MAX_CALENDAR_LIST_LIMIT = 1_000;
 const MAX_FREE_BUSY_INTERVALS = 10_000;
@@ -66,7 +56,7 @@ const MAX_WAITLIST_WINDOW_MS = 31 * 24 * 60 * 60 * 1000;
 const DEFAULT_OFFER_TTL_MS = 15 * 60 * 1000;
 /** How long before its start a booking may be checked in. */
 export const SLOTLOCK_CHECK_IN_OPENS_MINUTES = 60;
-/** Free-looking resources one entry tries before the next entry: a race can take one first. */
+/** Free-looking resources one entry tries before the next: a race can take one first. */
 const OFFER_CANDIDATES = 3;
 /** Default hard ceiling for retained active + tombstoned identities per agent principal. */
 export const SLOTLOCK_AGENT_OWNER_EVENT_QUOTA = 1_000;
@@ -86,8 +76,8 @@ const AGENT_EVENT_OWNER_PATTERN = /^agent:[0-9a-f]{64}$/;
 /** Store-owned coverage source for bounded, locally materialized recurring events. */
 export const SLOTLOCK_LOCAL_RECURRENCE_COVERAGE_SOURCE = 'slotlock:local-recurrence-materialization';
 /**
- * Stable daily target shared by the event writer, maintenance worker, and readiness proof: from a
- * day before the current UTC day to 367 days past its end (SLOTLOCK_MATERIALIZATION_WINDOW_DAYS).
+ * From a day before the current UTC day to SLOTLOCK_MATERIALIZATION_WINDOW_DAYS past its end;
+ * shared by the writer, maintenance and readiness.
  */
 export function calendarEventRollingHorizon(now = new Date()) {
     if (!Number.isFinite(now.getTime()))
@@ -97,8 +87,8 @@ export function calendarEventRollingHorizon(now = new Date()) {
     return { start, end: new Date(start.getTime() + MAX_MATERIALIZATION_WINDOW_MS) };
 }
 /**
- * A stored series expanded from the cursor its last expansion left, or `null` when there is none it
- * can use or the expansion from it is refused: the write's own search from the start was refused.
+ * A stored series expanded from its last cursor, or `null` when there is no usable cursor or the
+ * expansion is refused.
  */
 function resumeStoredSeries(event, window, found) {
     if (!found?.recurrence_cursor)
@@ -116,15 +106,13 @@ function resumeStoredSeries(event, window, found) {
         throw error;
     }
 }
-/** A series cursor as the jsonb column takes it. */
 function seriesCursorJson(tx, cursor) {
     return cursor === null ? null : tx.json(cursor);
 }
 /**
- * The window a roll to `horizon` gives a series stored for `stored`: from the horizon's start to
- * the later of the two ends, so its end never moves back. `null` keeps the stored window: it covers
- * the horizon already, or it ends so far past it that no window from the horizon's start to its end
- * fits the 367-day cap (it rolls once the horizon is close enough).
+ * From the horizon's start to the later of the two ends, so the end never moves back. `null` keeps
+ * the stored window: it already covers the horizon, or no window from the horizon's start fits the
+ * 367-day cap yet.
  */
 function rolledWindow(stored, horizon) {
     if (stored.start <= horizon.start && stored.end >= horizon.end)
@@ -134,21 +122,18 @@ function rolledWindow(stored, horizon) {
     return { start: horizon.start, end: stored.end > horizon.end ? stored.end : horizon.end };
 }
 /**
- * How far past a rule's UNTIL, read as UTC, an occurrence can still end, beyond the series' own
- * length. UNTIL bounds an occurrence's start (RFC 5545 §3.3.10), but a floating or date-only UNTIL
- * is a wall time in a zone from UTC-12 to UTC+14, or a whole day; a start in an hour the clocks skip
- * moves forward; and an occurrence's wall-clock end can pass its exact length by a clock change, a
- * whole day where a zone moved across the date line. Three days covers them together.
+ * How far past a rule's UNTIL, read as UTC, an occurrence can still end. UNTIL bounds starts (RFC
+ * 5545 §3.3.10), but a floating or date-only UNTIL is a wall time in any zone (UTC-12 to UTC+14),
+ * skipped hours move starts forward, and clock changes stretch ends: three days covers them
+ * together.
  */
 const SERIES_UNTIL_SLACK_MS = 3 * DAY_MS;
 /** Stored-series windows a COUNT rule is followed through, from its start, to find its end. */
 const SERIES_COUNT_SEARCH_WINDOWS = 30;
 /**
- * A time by which every occurrence of a recurring series ends, moved ones included, or `null` when
- * it may go on: its rule has neither UNTIL nor COUNT as ical.js reads it (as the expansion does),
- * or its COUNT occurrences are not all found within SERIES_COUNT_SEARCH_WINDOWS windows from its
- * start, or that search is over its budget. A COUNT series ends a day after its last occurrence as
- * the expansion reads it today, so a later reading of its end may be longer.
+ * A time by which every occurrence of a series ends, or `null` when it may go on: no UNTIL or COUNT
+ * as ical.js reads it, or the COUNT occurrences are not all found within
+ * SERIES_COUNT_SEARCH_WINDOWS windows or the search budget.
  */
 function seriesEndsBy(event) {
     const recurrence = event.recurrence;
@@ -185,10 +170,8 @@ function seriesEndsBy(event) {
     return Number.isFinite(ends.getTime()) ? ends : null;
 }
 /**
- * The latest end among a COUNT series' occurrences, expanded window by window from its start with
- * exceptions left out (so a cancelled or moved one is still found in its own place), or `null` when
- * fewer than `count` turn up. ical.js yields at most COUNT occurrences, so once `count` are found
- * there are no more. An occurrence is counted in the window its start falls in.
+ * The latest end among a COUNT series' occurrences, expanded window by window with exceptions left
+ * out (so a moved one is found in its own place), or `null` when fewer than `count` turn up.
  */
 function lastCountedOccurrenceEnd(event, count) {
     const rrule = event.recurrence?.rrule;
@@ -225,16 +208,15 @@ function lastCountedOccurrenceEnd(event, count) {
     return null;
 }
 /**
- * The recurrence_ends_by column for an event, as text: NULL for a one-off, 'infinity' for no known
- * end. Bind it as text (`::text::timestamptz`): postgres.js serializes a timestamptz parameter
- * through Date, which cannot hold 'infinity'.
+ * recurrence_ends_by as text: NULL for a one-off, 'infinity' for no known end. Bind it as text
+ * (`::text::timestamptz`): postgres.js serializes timestamptz through Date, which cannot hold
+ * 'infinity'.
  */
 function recurrenceEndsByColumn(event) {
     if (!event.recurrence)
         return null;
     return seriesEndsBy(event)?.toISOString() ?? 'infinity';
 }
-/** The roll's `after`, checked, or `undefined` for a pass's first batch. */
 function rollCursor(after) {
     if (after === undefined)
         return undefined;
@@ -250,8 +232,8 @@ function rollCursor(after) {
     return after;
 }
 /**
- * Run `callback` in a transaction: a new one on a client (READ COMMITTED when asked, else the role's
- * default), or a savepoint inside the caller's, whose isolation cannot change.
+ * A new transaction on a client (READ COMMITTED when asked), or a savepoint inside the caller's,
+ * whose isolation cannot change.
  */
 async function inTransaction(executor, callback, isolation) {
     if ('begin' in executor) {
@@ -272,12 +254,9 @@ async function assertReadCommitted(tx) {
         throw invalidIsolationError();
 }
 /**
- * Run deployment SQL resolving names only in pg_catalog, then the session's temporary schema. The
- * deployment role owns every table, so a function or operator it found through a schema another
- * role can create objects in ("$user", public) would run with that ownership. The DDL strings pin
- * themselves as well; this covers the statements the store sends around them. Every name read
- * before the pin is schema-qualified. The caller's search_path is restored afterwards; a failure
- * aborts the transaction, which reverts the pin as well.
+ * Run deployment SQL with names resolved only in pg_catalog and pg_temp. The deployment role owns
+ * every table, so a function found in a schema another role can write to ("$user", public) would
+ * run with that ownership. The caller's search_path is restored afterwards.
  */
 async function withPinnedSearchPath(tx, operation) {
     const [caller] = await tx `
@@ -288,10 +267,8 @@ async function withPinnedSearchPath(tx, operation) {
     return result;
 }
 /**
- * The deployment DDL refuses a `slotlock` schema that another role controls with SQLSTATE 42501 and
- * its findings as a JSON array in DETAIL. Surface that as `unsafe_slotlock_schema` with `reasons`,
- * keeping the database's error (and its HINT) as `cause`. It refuses a schema a newer release
- * migrated with SQLSTATE 55000: surface that as `schema_newer`. Any other failure passes through.
+ * Map the DDL's refusals: SQLSTATE 42501 (another role controls the schema; findings as JSON in
+ * DETAIL) to `unsafe_slotlock_schema`, and 55000 to `schema_newer`. Anything else passes through.
  */
 function schemaControlRefusal(error) {
     const failure = error;
@@ -322,7 +299,6 @@ function schemaControlRefusal(error) {
         reasons,
     });
 }
-/** PostgreSQL lock_not_available: a lock wait passed lock_timeout. */
 const LOCK_NOT_AVAILABLE = '55P03';
 const DEFAULT_MIGRATION_LOCK_TIMEOUT_MS = 1_000;
 const DEFAULT_MIGRATION_STATEMENT_TIMEOUT_MS = 15 * 60 * 1000;
@@ -341,10 +317,10 @@ function migrationSettings(options) {
     return { lockTimeoutMs, statementTimeoutMs, attempts };
 }
 /**
- * Run one migration step: in a transaction (or a savepoint of the caller's), with names resolved
- * in pg_catalog only, serialized with every other migration of this database, and with the lock and
- * statement timeouts set. A step that waits past its lock timeout, or is ended as a deadlock's
- * victim, is rolled back and tried again after a pause, up to `attempts` times. The caller's own timeouts are put back afterwards.
+ * One migration step: in a transaction (or savepoint), names pinned to pg_catalog, serialized with
+ * every other migration, under the lock and statement timeouts. A lock timeout or deadlock is
+ * rolled back and retried up to `attempts` times. The caller's own timeouts are restored
+ * afterwards.
  */
 async function inMigration(executor, options, step) {
     const settings = migrationSettings(options);
@@ -367,9 +343,8 @@ async function inMigration(executor, options, step) {
             }));
         }
         catch (error) {
-            // A deadlock's victim (DEADLOCK_DETECTED: a caller's transaction took the outbox, then a
-            // coverage row, while a rename batch took them in the other order, say) lost its locks with
-            // it, so it is tried again like a step that timed out waiting.
+            // A deadlock victim (a writer took outbox then coverage, a rename batch the other order) lost
+            // its locks, so it retries like a lock timeout.
             const code = pgCode(error);
             if (code !== LOCK_NOT_AVAILABLE && code !== DEADLOCK_DETECTED)
                 throw error;
@@ -381,12 +356,10 @@ async function inMigration(executor, options, step) {
     }
 }
 /**
- * A digest of what the migration defines in the `slotlock` schema: its tables and columns,
- * constraints (and whether each is validated), indexes, triggers and functions, and whether PUBLIC
- * holds any right on them. Grants to other roles, ownership and row-level security are left out:
- * applyTenantRls and grantApplicationRole change those after applySchema has recorded the digest.
- * Objects of an extension are left out too. Deparsed definitions depend on search_path, so this runs
- * with it pinned, as the migration does.
+ * A digest of what the migration defines in the `slotlock` schema: tables, columns, constraints
+ * (and whether validated), indexes, triggers, functions and PUBLIC grants. Grants to other roles,
+ * ownership and RLS are left out: applyTenantRls and grantApplicationRole change those later. Runs
+ * with search_path pinned, as deparsed definitions depend on it.
  */
 async function slotlockCatalogDigest(tx) {
     const [row] = await tx `
@@ -446,10 +419,9 @@ async function slotlockCatalogDigest(tx) {
     return row?.digest ?? '';
 }
 /**
- * Whether the schema is exactly what this release's applySchema last left: the same version, DDL
- * and catalog digest, and no table left without FORCE by an interrupted migration. Reading needs
- * the right to (the deployment role owns the table); without it the full migration runs and refuses
- * what it must.
+ * Whether the schema is exactly what this release's applySchema last left: same version, DDL and
+ * catalog digest, and no table left unforced by an interrupted migration. Without the right to read
+ * it, the full migration runs instead.
  */
 async function slotlockSchemaUpToDate(tx) {
     const [present] = await tx `
@@ -476,29 +448,21 @@ async function slotlockSchemaUpToDate(tx) {
 }
 /**
  * Rename the coverage changes an earlier release wrote (ddl.ts, slotlockCoverageChangeRenameSql),
- * in batches of SLOTLOCK_COVERAGE_CHANGE_RENAME_BATCH outbox ids, each a transaction of its own,
- * from where the last pass stopped (`schema_version.coverage_changes_renamed_through`, saved with
- * each batch) up to the last change when this pass starts. The first pass is the 0.6 upgrade's; an
- * earlier release's server still running then can write more, so every later migration runs a pass
- * too, until one finds nothing to rename: that marks the rename done and no migration reads the
- * outbox for it again.
+ * in batches of SLOTLOCK_COVERAGE_CHANGE_RENAME_BATCH outbox ids, resuming from
+ * `schema_version.coverage_changes_renamed_through`. An older server still running can write more,
+ * so every migration runs a pass until one finds nothing.
  *
- * The head is read only once every transaction already writing to the outbox has ended, so no
- * change at or below it can commit after the pass has read past it. Forced RLS would hide every
- * tenant's rows from the deployment role, so a role it binds lifts FORCE from calendar_coverage and
- * outbox for each batch and puts it back before the batch commits: each batch holds ACCESS
- * EXCLUSIVE on both, taken in the order writers take them (a source, then its change), for one
- * primary-key range of the outbox. A table an operator left unforced stays so. A superuser or
- * BYPASSRLS role reads every row as it is: it holds SHARE ROW EXCLUSIVE on the outbox (which waits
- * for the writes in flight and holds off new ones, but no read) only for the short transaction that
- * reads the head. Changes an earlier release's server writes after the upgrade are put in shape as
- * they are inserted (ddl.ts, slotlock.outbox_coverage_in_shape); the passes are for those before.
+ * The head is read once every transaction already writing to the outbox has ended, so nothing at or
+ * below it commits later. Forced RLS would hide other tenants' rows, so each batch lifts FORCE from
+ * calendar_coverage and outbox under ACCESS EXCLUSIVE (in writer lock order) and restores it before
+ * committing. A superuser or BYPASSRLS role instead holds SHARE ROW EXCLUSIVE on the outbox only
+ * while reading the head.
  */
 async function renameEarlierCoverageChanges(executor, options) {
     /**
-     * Run `work` able to read every tenant's outbox and coverage rows: as it is for a superuser or a
-     * BYPASSRLS role, else with FORCE lifted from the tables that have it, under ACCESS EXCLUSIVE
-     * (calendar_coverage, then outbox: the order every writer locks them in), and put back after.
+     * Run `work` able to read every tenant's rows: as is for a superuser or BYPASSRLS role, else with
+     * FORCE lifted under ACCESS EXCLUSIVE (calendar_coverage, then outbox: writer lock order) and put
+     * back after.
      */
     const everyTenant = async (tx, bypass, work) => {
         const forced = bypass
@@ -521,8 +485,8 @@ async function renameEarlierCoverageChanges(executor, options) {
             await tx.unsafe(`ALTER TABLE ${table} FORCE ROW LEVEL SECURITY`);
         return result;
     };
-    // The pass's head, in a short transaction of its own: once the writes in flight have ended (each
-    // holds ROW EXCLUSIVE from before it took its id), none at or below it can commit later.
+    // The head, in its own short transaction: writes in flight hold ROW EXCLUSIVE from before they
+    // took their id, so none at or below it commits later.
     const start = await inMigration(executor, options, async (tx) => {
         const [state] = await tx `
       SELECT version.coverage_changes_renamed AS renamed,
@@ -554,7 +518,6 @@ async function renameEarlierCoverageChanges(executor, options) {
             ]));
             const read = row?.last ?? null;
             renamedTotal += row?.renamed ?? 0;
-            // Saved with the batch, so a pass stopped part way goes on from here.
             await tx `
         UPDATE slotlock.schema_version
            SET coverage_changes_renamed_through = ${read ?? head}::bigint,
@@ -567,7 +530,6 @@ async function renameEarlierCoverageChanges(executor, options) {
         after = String(last);
     }
 }
-/** Whether the rename of coverage changes earlier releases wrote still has a pass to run. */
 async function coverageChangesRenamePending(tx) {
     const [row] = await tx `
     SELECT coverage_changes_renamed AS renamed FROM slotlock.schema_version WHERE singleton`;
@@ -586,8 +548,8 @@ async function slotlockConstraintUnvalidated(tx) {
     return row?.unvalidated === true;
 }
 /**
- * Whether every tenant table has forced RLS and only its tenant policy, bound to `setting`, whose
- * live fingerprint (computed as the RLS DDL computes it) matches the contract the DDL recorded.
+ * Whether every tenant table has forced RLS and only its tenant policy bound to `setting`, matching
+ * the fingerprint the DDL recorded.
  */
 async function tenantRlsUpToDate(tx, setting) {
     const [present] = await tx `
@@ -622,9 +584,8 @@ async function tenantRlsUpToDate(tx, setting) {
     return state?.current === true && state.matched === tables.length;
 }
 /**
- * The schema version recorded by the last migration, or `null` when there is none this role can
- * read: no schema, a schema from 0.2 or earlier, or a role not yet granted the function (run
- * `slotlock migrate`, which grants it).
+ * The recorded schema version, or `null` when this role cannot read one: no schema, 0.2 or earlier,
+ * or the function not yet granted (`slotlock migrate` grants it).
  */
 export async function readSlotlockSchemaVersion(sql) {
     const [readable] = await sql `
@@ -638,9 +599,8 @@ export async function readSlotlockSchemaVersion(sql) {
     return row?.version ?? null;
 }
 /**
- * Refuse to serve a schema another release migrated: `schema_outdated` when it is older than this
- * release (or unversioned), so `slotlock migrate` must run first; `schema_newer` when a newer release
- * migrated it, whose schema this release's code does not know. Both carry `installed` and `expected`.
+ * Refuse a schema another release migrated: `schema_outdated` (older or unversioned: run `slotlock
+ * migrate`) or `schema_newer`. Both carry `installed` and `expected`.
  */
 export async function assertSlotlockSchemaCurrent(sql) {
     const installed = await readSlotlockSchemaVersion(sql);
@@ -747,7 +707,6 @@ function toHold(row) {
         ...(row.hold_group_id ? { groupId: row.hold_group_id } : {}),
     };
 }
-/** A keyset cursor `{ start, id }` from the last row of a previous page, checked. */
 function pageCursor(after) {
     if (after !== undefined &&
         (!(after.start instanceof Date) ||
@@ -1012,7 +971,6 @@ async function replaceCalendarEventOccurrences(tx, params) {
       )`;
     }
 }
-/** A recurring series' materialization window: finite, forward, and at most 369 days. */
 function seriesWindow(window) {
     if (!isFiniteWindow(window) ||
         window.end.getTime() - window.start.getTime() > MAX_MATERIALIZATION_WINDOW_MS) {
@@ -1028,9 +986,9 @@ function calendarWindow(window) {
     return { start: new Date(window.start), end: new Date(window.end) };
 }
 /**
- * A one-off event's materialization window must contain the event. It defaults to the event's own
- * interval and may exceed the 367-day recurrence cap only by being exactly that interval, which is
- * what the `slotlock_calendar_events_materialization_window_bounded` CHECK admits.
+ * A one-off event's window must contain the event. It may exceed the 367-day cap only by being
+ * exactly the event's interval, as the `slotlock_calendar_events_materialization_window_bounded`
+ * CHECK admits.
  */
 function oneOffEventWindow(event, requested) {
     const duration = event.end.getTime() - event.start.getTime();
@@ -1049,17 +1007,15 @@ function calendarCommandHash(value) {
     return createHash('sha256').update(JSON.stringify(value)).digest('hex');
 }
 /**
- * What makes a put the same request: its identity and the event it asks for. Not the window its
- * occurrences are stored over, which for a series is the rolling horizon from the current UTC
- * midnight: with it in the hash, a retry after midnight was refused as a different request.
+ * A put's identity and the event it asks for, not its storage window: a series' window moves with
+ * the UTC day, so a retry after midnight must still match.
  */
 function putCommandHash(params) {
     return calendarCommandHash(putCommandValue(params));
 }
 /**
- * The hash 0.3.0 and earlier stored, with the window in it, so a command stored before the upgrade
- * still replays: always for a one-off event, whose window is its own span, and on the same UTC day
- * for a series. Remove once no stored command can be that old (commands are pruned after 30 days).
+ * The hash 0.3.0 and earlier stored (window included), so an older stored command still replays.
+ * Remove once no stored command can be that old (pruned after 30 days).
  */
 export function legacyPutCommandHash(params) {
     return calendarCommandHash({
@@ -1079,7 +1035,7 @@ function putCommandValue(params) {
         expectedRevision: params.command.expectedRevision,
         resourceId: params.command.resourceId,
         source: params.command.source ?? null,
-        // Only when present, so a create without a hold keeps the hash it always had.
+        // Only when present, so a create without a hold keeps its hash.
         ...(params.command.fromHold ? { fromHold: params.command.fromHold.holdId } : {}),
         event: {
             ...params.event,
@@ -1138,8 +1094,7 @@ async function calendarOwnerCommandCount(tx, tenantRef, ownerRef) {
 }
 /**
  * The end of every event cancellation, under the event's identity and row locks: remove the event
- * (when there is one) and its occupation, leave the identity's tombstone at `revision`, and record
- * the command in `commandOwnerRef`'s namespace for replay.
+ * and its occupation, leave the tombstone at `revision`, and record the command for replay.
  */
 async function finishCalendarCancel(tx, params) {
     const eventId = params.eventId ?? randomUUID();
@@ -1179,8 +1134,8 @@ async function finishCalendarCancel(tx, params) {
     };
 }
 /**
- * The row an event write lost to. The write was rolled back, so the event's own rows from before
- * it are still there and are left out: they were to be replaced, and never block the event.
+ * The row an event write lost to. The write was rolled back, so the event's own previous rows are
+ * excluded: they were to be replaced.
  */
 async function findCalendarOverlap(sql, resourceId, occurrences, eventId, buffers = { bufferBeforeMs: 0, bufferAfterMs: 0 }) {
     for (const occurrence of occurrences) {
@@ -1191,10 +1146,9 @@ async function findCalendarOverlap(sql, resourceId, occurrences, eventId, buffer
     return { ok: false, code: 'overlap', conflictingReservationId: null };
 }
 /**
- * What the resource's booking rules (as they apply: its own over its pool's and tenant's defaults)
- * say about a booking of `interval` made now (by the database's clock, at this statement): the rule
- * it breaks, if any, and the buffers it must keep before and after it. A resource without its own
- * hours is judged against `defaultHours`.
+ * What the resource's effective booking rules say about booking `interval` now (database clock):
+ * the rule broken, if any, and the buffers to keep. A resource without its own hours is judged
+ * against `defaultHours`.
  */
 async function bookingRuling(tx, resourceId, interval, defaultHours) {
     const judge = await bookingJudge(tx, resourceId, defaultHours);
@@ -1207,8 +1161,8 @@ async function bookingRuling(tx, resourceId, interval, defaultHours) {
 /** How recently a sync must have read a resource whose booking rules require certainty. */
 const CERTAIN_COVERAGE_MAX_AGE_MS = 24 * 60 * 60 * 1000;
 /**
- * The resource's booking rules as they apply, read once, as a check of any interval booked now (by
- * the database's clock at this statement) and the buffers a booking keeps.
+ * The resource's effective booking rules, read once, as a check of any interval booked now
+ * (database clock) and the buffers to keep.
  */
 async function bookingJudge(tx, resourceId, defaultHours) {
     const [row] = await tx `
@@ -1231,7 +1185,6 @@ async function bookingJudge(tx, resourceId, defaultHours) {
         effective_booking_rules: row.effective_booking_rules,
     });
     const hours = availabilityRules ?? defaultHours;
-    // Every sync covering the resource, and whether it was read within a day, by the same clock.
     const coverage = rules?.requireCertain === true
         ? await tx `
           SELECT starts_at, ends_at,
@@ -1241,12 +1194,11 @@ async function bookingJudge(tx, resourceId, defaultHours) {
         : [];
     const turnaroundMs = bookingBufferAfterMs(rules);
     const bufferBeforeMs = bookingBufferBeforeMs(rules);
-    // The booking and the buffers it keeps, as a search judges the slot.
     const uncertain = (interval) => coverage.some((source) => !source.fresh ||
         source.starts_at.getTime() > interval.start.getTime() - bufferBeforeMs ||
         source.ends_at.getTime() < interval.end.getTime() + turnaroundMs);
-    // A later occurrence of a series is judged on its step and hours only: notice and advance are
-    // about when the booking was made, which its first occurrence answers.
+    // Later occurrences are judged on step and hours only: notice and advance concern when the
+    // booking was made.
     const later = rules === undefined
         ? undefined
         : {
@@ -1271,19 +1223,17 @@ function sameExternalPayload(row, params, turnaroundMs = 0) {
     return (row.resource_id === params.resourceId &&
         row.starts_at.getTime() === params.start.getTime() &&
         row.ends_at.getTime() === params.end.getTime() &&
-        // As asked, or raised to the resource's turnaround when it was stored.
         (buffer === params.bufferAfterMs || buffer === Math.max(params.bufferAfterMs, turnaroundMs)) &&
         Number(row.revision) === params.revision &&
         row.source === (params.source ?? null));
 }
 async function lockExternalIdentity(tx, tenantRef, externalRef) {
-    // JSON encoding is unambiguous for this pair and contains no NUL byte (Postgres text rejects
-    // U+0000). The database hashes it to one transaction-scoped lock key.
+    // JSON is unambiguous for this pair and has no NUL byte (Postgres text rejects U+0000).
     await tx `SELECT pg_advisory_xact_lock(hashtextextended(${JSON.stringify([tenantRef, externalRef])}, 0))`;
 }
 /**
- * Whether the resource is the tenant's (`missing` when not), and whether it is archived. The row is
- * share-locked to the end of the transaction, so it is neither archived nor deleted meanwhile.
+ * Whether the resource is the tenant's (`missing` when not), and whether it is archived.
+ * Share-locked to the end of the transaction, so it is neither archived nor deleted meanwhile.
  */
 async function tenantResourceState(tx, resourceId, tenantRef) {
     const [row] = await tx `
@@ -1333,9 +1283,9 @@ function invalidPoolError() {
     });
 }
 /**
- * A resource row's booking rules as they apply (jsonb; NULL for none): the tenant's defaults,
- * overlaid by its pool's, overlaid by its own, field by field, so one set at a narrower level wins.
- * Read from a row of slotlock.resources named `resources` (no alias).
+ * A resource row's effective booking rules (jsonb; NULL for none): tenant defaults, overlaid by its
+ * pool's, overlaid by its own, field by field. Reads from a row of slotlock.resources named
+ * `resources` (no alias).
  */
 const EFFECTIVE_BOOKING_RULES = `NULLIF(
   COALESCE((SELECT defaults.rules FROM slotlock.booking_rule_defaults defaults
@@ -1347,7 +1297,7 @@ const EFFECTIVE_BOOKING_RULES = `NULLIF(
   '{}'::jsonb) AS effective_booking_rules`;
 /** What rules Slotlock did not write read as: no booking passes them. */
 const REFUSE_EVERY_BOOKING = Object.freeze({ maxAdvanceDays: 1, minNoticeMinutes: 525_600 });
-/** Rules read back from storage: written validated, so anything else refuses every booking. */
+/** Rules written validated, so anything else read back refuses every booking. */
 function storedBookingRules(value) {
     try {
         return parseBookingRules(value);
@@ -1369,7 +1319,7 @@ function toResource(row) {
     if (row.pool_ref !== null && row.pool_ref !== undefined)
         resource.pool = row.pool_ref;
     if (row.availability_rules !== null && row.availability_rules !== undefined) {
-        // Written through setResourceAvailability, which validates; anything else reads as closed.
+        // Written validated; anything else reads as closed.
         try {
             resource.availabilityRules = parseAvailabilityRules(row.availability_rules);
         }
@@ -1378,14 +1328,12 @@ function toResource(row) {
         }
     }
     if (row.booking_rules !== null && row.booking_rules !== undefined) {
-        // Written through setResourceBookingRules, which validates; anything else reads as refusing
-        // every booking, never as no rule.
+        // Written validated; anything else refuses every booking, never as no rule.
         resource.bookingRules = storedBookingRules(row.booking_rules);
     }
     if (row.effective_booking_rules !== null && row.effective_booking_rules !== undefined) {
-        // Merged from levels each validated alone, so only their combination can disagree (an offset
-        // from one level over a shorter step from another): that one is read modulo the step. A field
-        // invalid in itself was not written by Slotlock, and refuses every booking, as stored rules do.
+        // Levels are validated alone, so only their combination can disagree (an offset over a shorter
+        // step): that one is read modulo the step. A field invalid in itself refuses every booking.
         const { rules, dropped } = parseEffectiveBookingRules(row.effective_booking_rules);
         if (dropped.length > 0) {
             console.warn(JSON.stringify({ message: 'slotlock refused invalid booking rules', resource: row.id, dropped }));
@@ -1397,7 +1345,6 @@ function toResource(row) {
     }
     return resource;
 }
-/** Validated rules as a jsonb parameter, or null for "use the default". */
 function availabilityParameter(sql, rules) {
     // sql.json, not JSON.stringify: a string bound to jsonb is stored as a JSON string.
     if (rules === null)
@@ -1412,8 +1359,8 @@ async function upsertResource(executor, params) {
     const visibility = params.visibility ?? 'shared';
     const asked = params.visibility ?? null;
     let rows;
-    // An existing identity keeps the visibility it has: creating it again with none named returns it
-    // as it is, and with another one is refused, so a private one is never made shared that way.
+    // An existing identity keeps its visibility: re-creating with another is refused, so a private
+    // one is never made shared.
     if (params.tenantRef !== undefined && params.externalRef !== undefined) {
         rows = await executor `
       INSERT INTO slotlock.resources (external_ref, tenant_ref, timezone, visibility)
@@ -1449,11 +1396,9 @@ async function upsertResource(executor, params) {
     return toResource(row);
 }
 /**
- * Rematerialize one stored recurring master over the window a roll to `horizon` gives it
- * (rolledWindow): from where its last expansion stopped when that can be trusted, else its start.
- * False when there is no such master or nothing to roll. A collision throws the database's 23P01,
- * and a rule over the expansion budget CalendarExpansionLimitError; run it in a savepoint, which
- * either rolls back whole.
+ * Rematerialize one stored recurring master over rolledWindow: from its last expansion's cursor
+ * when trustworthy, else its start. False when there is nothing to roll. A collision throws 23P01
+ * and an over-budget rule CalendarExpansionLimitError; run it in a savepoint.
  */
 async function rollStoredSeries(tx, tenantRef, eventId, horizon) {
     const [row] = await tx `
@@ -1499,8 +1444,8 @@ async function rollStoredSeries(tx, tenantRef, eventId, horizon) {
     return true;
 }
 /**
- * Work out and store when a series stored before 0.3 ends (recurrence_ends_by), as its next roll
- * would; its stored occurrences are left as they are.
+ * Work out and store when a series stored before 0.3 ends, as its next roll would; its occurrences
+ * are left as they are.
  */
 async function learnSeriesEnd(tx, tenantRef, eventId) {
     const [row] = await tx `
@@ -1522,7 +1467,6 @@ async function learnSeriesEnd(tx, tenantRef, eventId) {
        SET recurrence_ends_by = ${recurrenceEndsByColumn(event)}::text::timestamptz
      WHERE id = ${row.id} AND tenant_ref = ${tenantRef} AND recurrence_ends_by IS NULL`;
 }
-/** Put a master the roll could not extend behind the others for an hour. */
 async function deferRoll(executor, tenantRef, eventId) {
     await executor `
     UPDATE slotlock.calendar_events
@@ -1531,24 +1475,19 @@ async function deferRoll(executor, tenantRef, eventId) {
 }
 /**
  * Whether every opaque recurring series on the resource (but `exceptEventId`) is stored over the
- * part of [start, end) that a roll can ever reach: from the later of `start` and the rolling
- * horizon's start. A write there must not land where such a series is not stored, or the series'
- * next roll would collide with it and stop. A series known to end before that part
- * (recurrence_ends_by) cannot meet the write and is left out, as is one stored through its end. A
- * series behind is first rolled to the horizon, in a savepoint of the write's transaction, so the
- * write meets its occurrences under the exclusion arbiter; false when one cannot be (it goes on
- * past the horizon and so does the write, it collides, or its rule is over the budget). Series are
- * rolled in id order; an event's update holds its own row while it rolls the others, so it and a
- * write rolling the same series in that order can deadlock, which the database breaks (the writer
- * retries once, then answers an overlap).
+ * part of [start, end) a roll can reach. A write must not land where a series is not stored yet, or
+ * the series' next roll would collide with it. A series behind is first rolled to the horizon in a
+ * savepoint, so the write meets its occurrences under the exclusion arbiter; false when one cannot
+ * be. Series roll in id order; a deadlock with a concurrent writer is broken by the database
+ * (retried once, then an overlap).
  */
 async function recurrenceCoversWrite(tx, params) {
     const horizon = calendarEventRollingHorizon();
     if (params.end <= horizon.start)
         return true;
     const from = params.start > horizon.start ? params.start : horizon.start;
-    // LEAST and GREATEST ignore a NULL argument (PostgreSQL 16, Conditional Expressions): a series
-    // with no known end is behind wherever it is stored short of the write's end.
+    // LEAST and GREATEST ignore NULL arguments (PostgreSQL 16): a series with no known end is behind
+    // wherever it is stored short of the write's end.
     const behind = () => tx `
     SELECT event.id, event.recurrence_ends_by IS NULL AS ends_by_unknown,
            COALESCE(event.recurrence_ends_by <= ${horizon.end}::timestamptz, false)
@@ -1578,8 +1517,8 @@ async function recurrenceCoversWrite(tx, params) {
     if (due.length === 0)
         return true;
     if (params.end > horizon.end) {
-        // A series stored before 0.3 has not worked out when it ends; it does so now, and is left out
-        // if it ends before the write or is stored through its end.
+        // A series stored before 0.3 works out its end now, and is left out if it ends before the write
+        // or is stored through its end.
         if (due.some((row) => row.ends_by_unknown)) {
             for (const { id, ends_by_unknown } of due) {
                 if (ends_by_unknown)
@@ -1589,7 +1528,6 @@ async function recurrenceCoversWrite(tx, params) {
             if (due.length === 0)
                 return true;
         }
-        // No roll stores a series past the horizon: one going on past it stays behind such a write.
         if (due.some((row) => !row.ends_in_horizon))
             return false;
     }
@@ -1607,9 +1545,8 @@ async function recurrenceCoversWrite(tx, params) {
     return (await behind()).length === 0;
 }
 /**
- * Whether an event already occupies, on the resource, all the time `occurrences` would: such a
- * write (a rename, a new description) takes no time a series could later need, so it is not held
- * to where the series on the resource are stored.
+ * Whether an event already occupies all the time `occurrences` would: such a write (a rename) takes
+ * no time a series could later need.
  */
 async function holdsEveryOccurrence(tx, eventId, resourceId, occurrences) {
     const held = await tx `
@@ -1620,7 +1557,6 @@ async function holdsEveryOccurrence(tx, eventId, resourceId, occurrences) {
        AND reservation.resource_id = ${resourceId}`;
     return occurrences.every((occurrence) => held.some(({ start, end }) => start <= occurrence.start && occurrence.end <= end));
 }
-/** From the earliest start to the latest end of an event's occurrences, or null for none. */
 function occurrenceSpan(occurrences) {
     const [first] = occurrences;
     if (!first)
@@ -1636,10 +1572,9 @@ function occurrenceSpan(occurrences) {
     return { start, end };
 }
 /**
- * After a write lost to the exclusion arbiter: roll, in a transaction of its own, the series on the
- * resource the write's transaction rolled with it (and lost), so they stay extended and the loss
- * can name the occurrence that blocked it. A resource with no tenant has no series. Upkeep only: if
- * it fails, the series are left to maintenance and the write is still answered as a loss.
+ * After a write lost to the exclusion arbiter: roll, in a transaction of its own, the series the
+ * write's transaction rolled and lost, so the loss can name the blocking occurrence. Upkeep only:
+ * on failure, maintenance rolls them later.
  */
 async function rollSeriesBehind(executor, resourceId, start, end, exceptEventId) {
     try {
@@ -1677,35 +1612,30 @@ function tenantLimitsOption(limits) {
     return valid;
 }
 /**
- * Serialize one tenant's writes that add rows of one limited kind, so each counts what every
- * earlier one committed. Taken before any row lock, after the write's identity locks.
+ * Serialize a tenant's writes adding rows of one limited kind, so each counts what earlier ones
+ * committed. Taken after the identity locks, before any row lock.
  */
 async function lockTenantLimit(tx, tenantRef, kind) {
     // An object, so the key never equals a [tenantRef, externalRef] identity lock's.
     await tx `SELECT pg_advisory_xact_lock(hashtextextended(${JSON.stringify({ tenantLimit: kind, tenantRef })}, 0))`;
 }
 /**
- * Rows a tenant added within this many days count against its limits whatever time they hold, so
- * bookings and events dated in the past, and cancellations, add at most the limit in any such
- * window. Ended history is not pruned: over a longer time it can still grow. Maintenance keeps
- * event idempotency records and stray retirements at least as long (the store's `retentionDays`).
+ * Rows added within this many days count whatever time they hold, so back-dated bookings and
+ * cancellations add at most the limit per window. Maintenance keeps idempotency records and stray
+ * retirements at least this long.
  */
 const TENANT_LIMIT_RECENT_DAYS = SLOTLOCK_EVENT_COMMAND_RETENTION_DAYS;
 /**
- * The rows a tenant has that its limit of `kind` counts: what is still to come, and what it added
- * in the last TENANT_LIMIT_RECENT_DAYS days; what ended before then is history and does not count.
- * Each part stops at `limit` rows, read through an index, so a count costs no more than the limit
- * however much history the tenant keeps; the total is at least `limit` exactly when the tenant is
- * at it.
+ * The rows a tenant's `kind` limit counts: what is still to come plus what it added in the last
+ * TENANT_LIMIT_RECENT_DAYS days. Each part stops at `limit` rows read through an index, so a count
+ * costs at most the limit.
  */
 async function tenantLimitCount(tx, tenantRef, kind, limit) {
     let rows;
     switch (kind) {
         case 'holds':
-            // Every held row, expired or not, until it is deleted: an expired hold no rival writes over
-            // stays stored until maintenance or a hold at the limit deletes it. And the answer kept for
-            // each keyed hold no longer held (released or confirmed, or its expired row deleted) until it
-            // is forgotten. An answer whose hold is still a held row is left out: that row counts.
+            // Every held row until deleted (expired ones too), plus each keyed hold's kept answer once
+            // its row is gone.
             rows = await tx `
         SELECT (
           (SELECT count(*) FROM (
@@ -1725,9 +1655,8 @@ async function tenantLimitCount(tx, tenantRef, kind, limit) {
         )::int AS count`;
             break;
         case 'reservations':
-            // Bookings still to come; bookings that have ended and cancellations, made recently; and
-            // references retired with no booking, until maintenance prunes them. A cancelled booking's
-            // tombstone is kept for good, and stops counting once it is no longer recent.
+            // Bookings still to come; ended bookings and cancellations made recently; and stray
+            // retirements until pruned.
             rows = await tx `
         WITH recent AS (
           SELECT now() - ${TENANT_LIMIT_RECENT_DAYS}::int * interval '1 day' AS since
@@ -1755,9 +1684,9 @@ async function tenantLimitCount(tx, tenantRef, kind, limit) {
         )::int AS count`;
             break;
         case 'events':
-            // One-off events still to come and series not known to have ended; events that have ended
-            // and cancellations of any owner, made recently; and agent cancellations until maintenance
-            // prunes them. The owner identity CHECK makes every owner but 'internal' an 'agent:' one.
+            // One-off events still to come and series not known to have ended; recent ended events and
+            // cancellations; and agent cancellations until pruned. The owner CHECK makes every owner but
+            // 'internal' an 'agent:' one.
             rows = await tx `
         WITH recent AS (
           SELECT now() - ${TENANT_LIMIT_RECENT_DAYS}::int * interval '1 day' AS since
@@ -1802,9 +1731,8 @@ async function tenantLimitCount(tx, tenantRef, kind, limit) {
     return count;
 }
 /**
- * Delete up to `limit` of a tenant's holds that have expired, oldest first; the number deleted. A
- * writer reaping or confirming a hold locks it: such a row is skipped, and the delete repeats the
- * predicate on the row as it now is.
+ * Delete up to `limit` of a tenant's expired holds, oldest first. Rows a reaper or confirmer has
+ * locked are skipped, and the delete rechecks the predicate.
  */
 async function deleteExpiredHolds(tx, tenantRef, limit) {
     const [row] = await tx `
@@ -1828,8 +1756,8 @@ async function deleteExpiredHolds(tx, tenantRef, limit) {
     return Number(row?.deleted ?? 0);
 }
 /**
- * Delete up to `limit` of a tenant's keyed hold answers whose hold has expired, so a retry with one
- * of their keys makes a new hold; answers another transaction holds are skipped. The number deleted.
+ * Delete up to `limit` keyed hold answers whose hold has expired, so a retry makes a new hold;
+ * locked answers are skipped.
  */
 async function forgetExpiredHoldAnswers(tx, tenantRef, limit) {
     const [row] = await tx `
@@ -1852,8 +1780,8 @@ async function forgetExpiredHoldAnswers(tx, tenantRef, limit) {
     return Number(row?.deleted ?? 0);
 }
 /**
- * The time a booking of [start, end) keeping these buffers occupies, as the exclusion constraint
- * reads it: from its start less its leading buffer to its end plus its trailing one.
+ * A booking's occupied time as the exclusion constraint reads it: start less its leading buffer to
+ * end plus its trailing one.
  */
 function occupiedTime(params) {
     return {
@@ -1862,8 +1790,8 @@ function occupiedTime(params) {
     };
 }
 /**
- * A row's occupied time starts before `end`: a condition on its occupied start that still reads the
- * (resource_id, starts_at, ends_at) index, since no row starts more than a day after it.
+ * Occupied start before `end`, written so the (resource_id, starts_at, ends_at) index still
+ * applies: no row starts more than a day after its occupied start.
  */
 function occupiedStartsBefore(executor, end, alias) {
     const column = (name) => executor.unsafe(alias === undefined ? name : `${alias}.${name}`);
@@ -1871,12 +1799,9 @@ function occupiedStartsBefore(executor, end, alias) {
                    AND COALESCE(${column('occupied_starts_at')}, ${column('starts_at')}) < ${end})`;
 }
 /**
- * Delete expired held rows whose occupied time (buffers included, as the EXCLUDE constraint reads
- * it) overlaps the requested window, whose `start` and `end` are its own occupied start and end
- * (`occupiedTime`), in deterministic id
- * order under FOR UPDATE — two concurrent reapers lock the same rows in the same order (no
- * deadlock), the loser simply finds them gone. Runs inside the caller's transaction, immediately
- * before its INSERT, so the EXCLUDE arbiter only ever sees LIVE occupation.
+ * Delete expired held rows whose occupied time overlaps the window, in id order under FOR UPDATE:
+ * concurrent reapers lock in the same order (no deadlock) and the loser finds them gone. Runs right
+ * before the caller's INSERT, so the EXCLUDE arbiter only sees live occupation.
  */
 async function reapExpiredHolds(tx, resourceId, start, end) {
     await tx `
@@ -1893,10 +1818,9 @@ async function reapExpiredHolds(tx, resourceId, start, end) {
      )`;
 }
 /**
- * Structured answer after losing to the EXCLUDE arbiter: name the (live) winner.
- * conflictingReservationId can be null in one narrow race: the blocker expired between the
- * loser's transaction start (constraint saw it) and this lookup (live filter hides it) — an
- * immediate retry reaps it and wins.
+ * Structured answer after losing to the EXCLUDE arbiter: name the live winner.
+ * conflictingReservationId is null in one narrow race (the blocker expired between the constraint
+ * check and this lookup); an immediate retry reaps it and wins.
  */
 async function overlapLoss(sql, resourceId, start, end, bufferAfterMs = 0, excludeReservationId, excludeCalendarEventId, bufferBeforeMs = 0) {
     const winners = await sql `
@@ -1967,7 +1891,7 @@ export function createTenantSlots(max) {
             if (released)
                 return;
             released = true;
-            // Handed straight to the next in line, so the count stays as it is.
+            // Handed straight to the next in line, so the count is unchanged.
             const next = slots.waiting.shift();
             if (next) {
                 next();
@@ -2033,9 +1957,8 @@ function staleSuspensionCheckError() {
     return Object.assign(new Error('Slotlock writes for a tenant only in a READ COMMITTED transaction, whose suspension check sees every suspension committed before the tenant lock'), { code: 'invalid_transaction_isolation' });
 }
 /**
- * Reading a tenant's suspension needs EXECUTE on slotlock.tenant_suspended(text), which PUBLIC does
- * not hold (SQLSTATE 42501 without it), and a schema this release migrated (42883 before then).
- * Name the remedy for each; any other failure passes through.
+ * Reading a suspension needs EXECUTE on slotlock.tenant_suspended(text) (42501 without it) and a
+ * schema this release migrated (42883 before). Name the remedy for each.
  */
 function suspensionCheckRefusal(error) {
     const code = pgCode(error);
@@ -2048,8 +1971,8 @@ function suspensionCheckRefusal(error) {
     return error;
 }
 /**
- * A store on `sql`. With `refusal`, every method in SLOTLOCK_TENANT_WRITE_METHODS throws what it
- * returns before any query (a suspended tenant, or a suspension check that could be stale).
+ * A store on `sql`. With `refusal`, every SLOTLOCK_TENANT_WRITE_METHODS method throws it before any
+ * query.
  */
 function buildSlotlockStore(sql, options, refusal) {
     const configuredTenantSetting = options.tenantContextSetting ?? SLOTLOCK_TENANT_CONTEXT_SETTING;
@@ -2096,7 +2019,7 @@ function buildSlotlockStore(sql, options, refusal) {
         ? createTenantSlots(maxTenantTransactions)
         : undefined;
     const lockTimeout = ownTransactions && tenantLockTimeoutMs !== undefined ? `${tenantLockTimeoutMs}ms` : undefined;
-    createSlotlockTenantRlsDdl(configuredTenantSetting); // Validate once before any scoped query.
+    createSlotlockTenantRlsDdl(configuredTenantSetting);
     const storeOptions = {
         tenantContextSetting: configuredTenantSetting,
         agentOwnerEventQuota: configuredAgentOwnerEventQuota,
@@ -2107,9 +2030,8 @@ function buildSlotlockStore(sql, options, refusal) {
         ...(maxHeldHoursPerHolder !== undefined ? { maxHeldHoursPerHolder } : {}),
     };
     /**
-     * Under the tenant's lock for `kind`: the limit when the tenant is at it, else null. No limit for
-     * `kind`, or no tenant, takes no lock. Writes that only lower the count take no lock, so a count
-     * read early stays an upper bound for the rest of the transaction.
+     * Under the tenant's lock for `kind`: the limit when the tenant is at it, else null. Writes that
+     * only lower the count take no lock, so an early count stays an upper bound.
      */
     async function tenantLimitReached(tx, tenantRef, kind) {
         const limit = configuredTenantLimits[kind];
@@ -2119,10 +2041,8 @@ function buildSlotlockStore(sql, options, refusal) {
         await lockTenantLimit(tx, tenantRef, kind);
         if ((await tenantLimitCount(tx, tenantRef, kind, limit)) < limit)
             return null;
-        // A hold, and a keyed hold's answer, keep their place only until the hold expires; at the
-        // limit, the expired holds and their answers are deleted, as maintenance would, and the count
-        // is read again. Counting expired rows until then keeps what a tenant stores within the limit
-        // between maintenance passes, however short its holds.
+        // At the limit, expired holds and their answers are deleted, as maintenance would, and the
+        // count is read again.
         if (kind !== 'holds' ||
             (await deleteExpiredHolds(tx, tenantRef, limit)) +
                 (await forgetExpiredHoldAnswers(tx, tenantRef, limit)) ===
@@ -2133,7 +2053,7 @@ function buildSlotlockStore(sql, options, refusal) {
     }
     /**
      * The tenant whose limit a write on the resource counts against: the caller's, else the
-     * resource's (a resource never changes tenant, so it is read before any lock). Null with no limit.
+     * resource's (never changes, so read before any lock). Null with no limit.
      */
     async function limitTenant(tx, kind, resourceId, tenantRef) {
         if (configuredTenantLimits[kind] === undefined)
@@ -2147,12 +2067,9 @@ function buildSlotlockStore(sql, options, refusal) {
     const store = {
         ...slotlockEventFeedMethods(sql, retentionDays),
         async applySchema(migrationOptions) {
-            // PostgreSQL's IF NOT EXISTS DDL is idempotent after commit but not race-free: two fresh
-            // application instances can still collide on pg_namespace/pg_extension unique indexes.
-            // inMigration serializes bootstrap per database and the transaction releases the lock on
-            // crashes. A schema this release already left as it is changes nothing and locks no table,
-            // unless old rows kept one of its constraints NOT VALID (then only the validation runs again)
-            // or the rename of earlier coverage changes is not done (then only a pass of it runs).
+            // IF NOT EXISTS DDL is idempotent but not race-free: two fresh instances can collide on
+            // pg_namespace/pg_extension indexes, so inMigration serializes bootstrap. An unchanged schema
+            // locks no table unless a constraint is still NOT VALID or the coverage rename is unfinished.
             const next = await inMigration(sql, migrationOptions, async (tx) => {
                 await tx.unsafe(SLOTLOCK_DEPLOYMENT_CHECKS).catch((error) => {
                     throw schemaControlRefusal(error);
@@ -2168,18 +2085,15 @@ function buildSlotlockStore(sql, options, refusal) {
                 });
                 return { validate: true, rename: await coverageChangesRenamePending(tx) };
             });
-            // Changes an earlier release wrote are renamed in short batches once the structure commits,
-            // never under its locks, by this migration and the next ones until a pass finds none
-            // (renameEarlierCoverageChanges); the feed serves any not renamed yet redacted (event-feed.ts,
-            // slotlockServedChange).
+            // Renamed in short batches after the structure commits, never under its locks; the feed
+            // redacts any not yet renamed (event-feed.ts, slotlockServedChange).
             if (next.rename)
                 await renameEarlierCoverageChanges(sql, migrationOptions);
             if (!next.validate)
                 return;
-            // Once the DDL has committed, its ACCESS EXCLUSIVE locks are gone: validating holds none that
-            // a serving query waits for (ddl.ts, DEPLOYMENT_VALIDATE_CONSTRAINTS). Inside a caller's
-            // transaction both steps share it, and its locks, until it ends. The digests go last, so a
-            // migration stopped before them runs whole again.
+            // After the DDL commits its ACCESS EXCLUSIVE locks are gone, so validation blocks no serving
+            // query (ddl.ts, DEPLOYMENT_VALIDATE_CONSTRAINTS). Digests go last, so a migration stopped
+            // earlier runs whole again.
             await inMigration(sql, migrationOptions, async (tx) => {
                 await tx.unsafe(SLOTLOCK_VALIDATION_DDL);
                 await tx `
@@ -2349,8 +2263,8 @@ function buildSlotlockStore(sql, options, refusal) {
                 throw Object.assign(new Error('Slotlock key id must be a UUID'), { code: 'invalid_identity' });
             }
             const release = await tenantSlots?.(tenantRef, options?.signal);
-            // A lock wait that timed out leaves the transaction unusable, so the reset below fails with
-            // another error in its place: noted here as it happens.
+            // A lock timeout leaves the transaction unusable, so the reset below would fail with another
+            // error: noted here.
             let timedOut = false;
             return inTransaction(sql, async (tx) => {
                 if (lockTimeout !== undefined) {
@@ -2358,9 +2272,8 @@ function buildSlotlockStore(sql, options, refusal) {
                 }
                 if (isolation !== undefined)
                     await assertReadCommitted(tx);
-                // Held shared until the transaction ends: suspension and erasure, which take it
-                // exclusively, wait for this transaction, and one that starts after them reads them below
-                // (READ COMMITTED: a statement after the lock sees what committed before it was granted).
+                // Held shared until the transaction ends: suspension and erasure take it exclusively, so
+                // they wait for this transaction, and one starting after them sees them (READ COMMITTED).
                 const previous = await tx `
             SELECT current_setting(${configuredTenantSetting}, true) AS value,
                    current_setting('slotlock.actor', true) AS actor,
@@ -2379,9 +2292,8 @@ function buildSlotlockStore(sql, options, refusal) {
                    slotlock.tenant_suspended(${tenantRef}) AS suspended`.catch((error) => {
                     throw suspensionCheckRefusal(error);
                 });
-                // A caller's REPEATABLE READ or SERIALIZABLE snapshot was taken before the lock was
-                // granted, so it may not show a suspension that committed while this transaction waited:
-                // its writes are refused, and it may read.
+                // A caller's REPEATABLE READ or SERIALIZABLE snapshot predates the lock, so it may miss a
+                // suspension: its writes are refused, reads allowed.
                 const refusal = context?.suspended === true
                     ? tenantSuspendedError
                     : previous[0]?.isolation !== 'read committed'
@@ -2436,7 +2348,7 @@ function buildSlotlockStore(sql, options, refusal) {
                 // An object, so the key never equals a [tenantRef, externalRef] identity lock's.
                 await tx `SELECT pg_advisory_xact_lock(hashtextextended(${JSON.stringify({ resourceCount: tenantRef })}, 0))`;
                 // READ COMMITTED: each statement below sees every create committed before the lock.
-                // Re-creating a resource the tenant has (by its reference) adds none.
+                // Re-creating a known reference adds none.
                 const known = externalRef === null
                     ? []
                     : await tx `
@@ -2539,8 +2451,8 @@ function buildSlotlockStore(sql, options, refusal) {
             const tenantRef = params.tenantRef;
             return inTransaction(sql, async (tx) => {
                 if (pool !== '') {
-                    // Counted under the tenant's lock, so racing writes stop at the cap.
-                    // The count after the lock sees every committed row only under READ COMMITTED.
+                    // Counted under the tenant's lock, which only READ COMMITTED makes see every committed
+                    // row.
                     await assertReadCommitted(tx);
                     await tx `SELECT pg_advisory_xact_lock(hashtextextended(${`slotlock:rule-defaults:${tenantRef}`}, 0))`;
                     const [counted] = await tx `
@@ -2668,8 +2580,8 @@ function buildSlotlockStore(sql, options, refusal) {
             if (!isValidIdentity(params.tenantRef) || !isValidResourceId(params.id)) {
                 throw invalidIdentityError('Slotlock resource identity is invalid');
             }
-            // Its clock time, not the transaction's start: a booking that committed holding the row's
-            // share lock went in before this.
+            // Clock time, not transaction start: a booking that committed holding the row's share lock
+            // went in before this.
             const [row] = await sql `
         UPDATE slotlock.resources
            SET archived_at = COALESCE(archived_at, clock_timestamp())
@@ -2715,8 +2627,8 @@ function buildSlotlockStore(sql, options, refusal) {
                  ) AS live`;
                 if (live?.live)
                     return { ok: false, code: 'resource_in_use' };
-                // Its rows go with it: reservations, events and their children, coverage and hold answers
-                // all cascade from the resource.
+                // Reservations, events and their children, coverage and hold answers all cascade from the
+                // resource.
                 await tx `DELETE FROM slotlock.resources WHERE id = ${params.id}`;
                 return { ok: true, deleted: true };
             });
@@ -2730,10 +2642,9 @@ function buildSlotlockStore(sql, options, refusal) {
             if (params.tenantRef !== undefined && !isValidIdentity(params.tenantRef)) {
                 return { ok: false, code: 'resource_not_found' };
             }
-            // A booking on a tenant's resource takes the tenant and its own id as reference, so it can be
-            // cancelled and moved like any other; one on a resource with no tenant stays tenantless.
+            // A booking on a tenant's resource takes the tenant and its own id as reference; one on a
+            // tenantless resource stays tenantless.
             const id = randomUUID();
-            // The buffers written, for the overlap answer if the write loses.
             let bufferBeforeMs = 0;
             let bufferAfterMs = 0;
             for (let attempt = 1;; attempt++) {
@@ -2788,15 +2699,15 @@ function buildSlotlockStore(sql, options, refusal) {
                 catch (err) {
                     const code = pgCode(err);
                     if ((code === DEADLOCK_DETECTED || code === SERIALIZATION_FAILURE) && attempt === 1) {
-                        continue; // fully rolled back — one retry wins cleanly or loses with a clean 23P01
+                        continue; // fully rolled back: one retry wins or loses with a clean 23P01
                     }
                     if (code !== EXCLUSION_VIOLATION &&
                         code !== DEADLOCK_DETECTED &&
                         code !== SERIALIZATION_FAILURE) {
                         throw err;
                     }
-                    // A SECOND contention abort is treated as a loss too (structured, possibly with a null
-                    // winner if both rivals rolled back) — symmetric with 40P01, never a raw throw.
+                    // A second contention abort is a structured loss too (possibly with a null winner), never
+                    // a raw throw.
                     const occupied = occupiedTime({ ...params, bufferBeforeMs, bufferAfterMs });
                     await rollSeriesBehind(sql, params.resourceId, occupied.start, occupied.end);
                     return overlapLoss(sql, params.resourceId, params.start, params.end, bufferAfterMs, undefined, undefined, bufferBeforeMs);
@@ -2821,8 +2732,8 @@ function buildSlotlockStore(sql, options, refusal) {
                         if (cancelled[0])
                             return { ok: false, code: 'reservation_cancelled' };
                         // A calendar event's occupation carries a reference in this namespace too, but it is
-                        // not a booking: create, reschedule and cancel never read, replay, move or free it,
-                        // and answer as for a reference no booking holds. Bookings have their own unique index.
+                        // not a booking: create, reschedule and cancel treat it as a reference no booking
+                        // holds.
                         const existing = await tx `
               SELECT id, resource_id, tenant_ref, external_ref, starts_at, ends_at,
                      buffer_after_ms, revision, source
@@ -2833,7 +2744,7 @@ function buildSlotlockStore(sql, options, refusal) {
                         const found = existing[0];
                         const ruling = await bookingRuling(tx, params.resourceId, params, defaultHours);
                         if (found) {
-                            // The booking has moved on since: a delayed create is stale, as a delayed move is.
+                            // Moved on since: a delayed create is stale, as a delayed move is.
                             if (params.revision < Number(found.revision)) {
                                 return { ok: false, code: 'stale_revision' };
                             }
@@ -3034,8 +2945,8 @@ function buildSlotlockStore(sql, options, refusal) {
                     }
                 }
                 if (!found) {
-                    // A calendar event's occupation row carries this reference: it is the event's, not a
-                    // booking's. Nothing is cancelled, and nothing retired: a tombstone would only grow.
+                    // This reference is a calendar event's occupation, not a booking: nothing to cancel or
+                    // retire.
                     const [occupation] = await tx `
             SELECT id FROM slotlock.reservations
              WHERE tenant_ref = ${params.tenantRef} AND external_ref = ${params.externalRef}
@@ -3049,7 +2960,7 @@ function buildSlotlockStore(sql, options, refusal) {
                         return { ok: false, code: 'reservation_limit_reached', limit };
                 }
                 // A reference no booking holds yet is retired too, so a create delivered after its cancel
-                // cannot bring the booking back. Only such a stray retirement is pruned past retention.
+                // cannot bring it back.
                 await tx `
           INSERT INTO slotlock.reservation_tombstones (tenant_ref, external_ref, revision, stray)
           VALUES (${params.tenantRef}, ${params.externalRef}, ${params.revision}, ${!found})`;
@@ -3064,9 +2975,8 @@ function buildSlotlockStore(sql, options, refusal) {
             if (!isFiniteWindow({ start: params.start, end: params.end })) {
                 return { ok: false, code: 'invalid_window' };
             }
-            // Finiteness + cap: NaN/Infinity would raise raw 22008 in make_interval, and an absurd
-            // ttl mints an effectively-eternal hold whose expiry can even exceed the JS Date range
-            // (Invalid Date back to the caller). All refused pre-table.
+            // NaN/Infinity would raise a raw 22008 in make_interval, and a huge ttl could exceed the JS
+            // Date range.
             if (!Number.isFinite(params.ttlMs) || params.ttlMs <= 0 || params.ttlMs > MAX_HOLD_TTL_MS) {
                 return { ok: false, code: 'invalid_ttl' };
             }
@@ -3106,8 +3016,7 @@ function buildSlotlockStore(sql, options, refusal) {
                 ...(holderRef !== undefined ? { holderRef } : {}),
             });
             const ttlSeconds = params.ttlMs / 1000;
-            // The buffers written: the one asked for, raised to the resource's turnaround, and its rule's
-            // leading buffer.
+            // The buffer asked for, raised to the resource's turnaround, and its rule's leading buffer.
             let written = bufferAfterMs;
             let writtenBefore = 0;
             for (let attempt = 1;; attempt++) {
@@ -3145,11 +3054,10 @@ function buildSlotlockStore(sql, options, refusal) {
                             return { ok: false, code: 'resource_archived' };
                         if (holdLimit !== null)
                             return { ok: false, code: 'hold_limit_reached', limit: holdLimit };
-                        // Seconds the holder already holds, turnaround included, when its time is capped.
                         let heldSeconds = null;
                         if (holderRef !== undefined) {
-                            // One holder's live holds, counted under a lock on the holder so racing holds stop
-                            // at the cap: an agent cannot hold a resource's whole week.
+                            // Counted under a lock on the holder, so racing holds stop at the cap: an agent
+                            // cannot hold a resource's whole week.
                             await tx `SELECT pg_advisory_xact_lock(hashtextextended(${JSON.stringify([
                                 'slotlock-holder',
                                 tenantRef,
@@ -3229,8 +3137,8 @@ function buildSlotlockStore(sql, options, refusal) {
                         code !== SERIALIZATION_FAILURE) {
                         throw err;
                     }
-                    // A SECOND contention abort is treated as a loss too (structured, possibly with a null
-                    // winner if both rivals rolled back) — symmetric with 40P01, never a raw throw.
+                    // A second contention abort is a structured loss too (possibly with a null winner), never
+                    // a raw throw.
                     const occupied = occupiedTime({ ...params, bufferBeforeMs: writtenBefore, bufferAfterMs: written });
                     await rollSeriesBehind(sql, params.resourceId, occupied.start, occupied.end);
                     return overlapLoss(sql, params.resourceId, params.start, params.end, written, undefined, undefined, writtenBefore);
@@ -3344,13 +3252,12 @@ function buildSlotlockStore(sql, options, refusal) {
         },
         async confirmHold(holdId, options = {}) {
             const tenantRef = holdTenantRef(options);
-            // Not an id the store issues: it names no hold (and would be a raw 22P02 in the query).
+            // Not an id the store issues (and a raw 22P02 in the query).
             if (!isValidResourceId(holdId))
                 return { ok: false, code: 'hold_not_found' };
             return inTransaction(sql, async (tx) => {
-                // The tenant whose booking the hold becomes is its resource's; a hold never changes
-                // resource, so it is read before the identity lock, which is taken before the row lock as
-                // every booking write takes them.
+                // A hold never changes resource, so the owner is read before the identity lock, taken
+                // before the row lock as every booking write does.
                 const [owner] = await tx `
           SELECT hold.resource_id, resource.tenant_ref AS resource_tenant
             FROM slotlock.reservations hold
@@ -3364,7 +3271,7 @@ function buildSlotlockStore(sql, options, refusal) {
                     await lockExternalIdentity(tx, bookingTenant, holdId);
                 const bookingLimit = await tenantLimitReached(tx, bookingTenant, 'reservations');
                 // The resource's share lock, as every booking write takes it: an archive waits for this
-                // confirmation, and one that committed first is read here.
+                // confirmation.
                 const [resource] = await tx `
           SELECT archived_at IS NOT NULL AS archived FROM slotlock.resources
            WHERE id = ${owner.resource_id}
@@ -3376,16 +3283,13 @@ function buildSlotlockStore(sql, options, refusal) {
            WHERE id = ${holdId}
            FOR UPDATE`;
                 if (!row) {
-                    // NOTE: a hold reaped mid-flight by a rival (expired while this confirm waited on the
-                    // reaper's lock) reads as hold_not_found: the row is gone and the space was legitimately
-                    // taken; both refusal codes are terminal for the caller.
+                    // A hold reaped by a rival while this confirm waited reads as hold_not_found; both
+                    // refusals are terminal for the caller.
                     return { ok: false, code: 'hold_not_found' };
                 }
                 if (row.status === 'confirmed') {
-                    // Idempotent confirm: a retried confirm (network replay) of an already-confirmed hold is
-                    // SUCCESS, the booking as it now is; reporting failure would make callers double-book
-                    // elsewhere. A confirmed hold's reference is its own id (none without a tenant); a
-                    // booking with another reference was never this hold.
+                    // A retried confirm of an already-confirmed hold is success: reporting failure would make
+                    // callers double-book elsewhere. A booking with another reference was never this hold.
                     if (row.external_ref !== null && row.external_ref !== row.id) {
                         return { ok: false, code: 'hold_not_found' };
                     }
@@ -3393,7 +3297,6 @@ function buildSlotlockStore(sql, options, refusal) {
                 }
                 if (!row.live)
                     return { ok: false, code: 'hold_expired' };
-                // Archived since the hold was taken: a confirmation would be a new booking on it.
                 if (resource?.archived !== false)
                     return { ok: false, code: 'resource_archived' };
                 if (bookingTenant !== null) {
@@ -3412,8 +3315,8 @@ function buildSlotlockStore(sql, options, refusal) {
                 if (bookingLimit !== null) {
                     return { ok: false, code: 'reservation_limit_reached', limit: bookingLimit };
                 }
-                // The occupied end is already the end plus the hold's buffer (the trigger set it); the
-                // tenant and reference make the hold a booking that cancel and reschedule reach.
+                // The trigger already set the occupied end; the tenant and reference make the hold a
+                // booking cancel and reschedule reach.
                 const [confirmed] = await tx `
           UPDATE slotlock.reservations
              SET status = 'confirmed', expires_at = NULL,
@@ -3482,8 +3385,8 @@ function buildSlotlockStore(sql, options, refusal) {
                     });
                 }
             }
-            // Expired holds are dead occupation: excluded here so findNextAvailable can offer their
-            // space (the acquiring transaction reaps the row itself when it takes the window).
+            // Expired holds are excluded so findNextAvailable can offer their space; the acquiring
+            // transaction reaps the row itself.
             const rows = await sql `
         SELECT COALESCE(occupied_starts_at, starts_at) AS occupied_starts_at,
                COALESCE(occupied_ends_at, ends_at) AS occupied_ends_at
@@ -3532,8 +3435,8 @@ function buildSlotlockStore(sql, options, refusal) {
                     });
                 }
                 catch (error) {
-                    // A long-running series can take more than a write searches from its start. If it is
-                    // stored, it is expanded again below from where its last expansion stopped.
+                    // A long-running series can outgrow the write's search budget from its start; a stored
+                    // one is expanded below from its last cursor.
                     if (!(error instanceof CalendarExpansionLimitError) || !event.recurrence)
                         throw error;
                 }
@@ -3552,7 +3455,6 @@ function buildSlotlockStore(sql, options, refusal) {
             });
             const recurrenceEndsBy = recurrenceEndsByColumn(event);
             let attempted = expanded?.occurrences ?? [];
-            // The buffers the attempt kept, for the overlap answer if it loses.
             let attemptedBuffers = { bufferBeforeMs: 0, bufferAfterMs: 0 };
             let storedEventId;
             for (let attempt = 1;; attempt++) {
@@ -3580,8 +3482,8 @@ function buildSlotlockStore(sql, options, refusal) {
                         if (ownerRef !== SLOTLOCK_INTERNAL_EVENT_OWNER_REF) {
                             await lockCalendarOwnerQuota(tx, params.tenantRef, ownerRef);
                             const commandCount = await calendarOwnerCommandCount(tx, params.tenantRef, ownerRef);
-                            // Preserve one guaranteed cancellation slot for every possible live identity. This
-                            // prevents update churn from making a principal unable to release calendar space.
+                            // Reserve one cancellation slot for every possible live identity, so update churn
+                            // cannot leave a principal unable to release calendar space.
                             const putCommandLimit = configuredAgentOwnerCommandQuota - configuredAgentOwnerEventQuota;
                             if (commandCount >= putCommandLimit) {
                                 return {
@@ -3682,7 +3584,6 @@ function buildSlotlockStore(sql, options, refusal) {
                                 only.end > hold.ends_at) {
                                 return { ok: false, code: 'hold_mismatch' };
                             }
-                            // The hold and its alternatives give way to the event in this transaction.
                             await tx `
                 DELETE FROM slotlock.reservations
                  WHERE status = 'held' AND holder_ref = ${holderRef}
@@ -3773,8 +3674,8 @@ function buildSlotlockStore(sql, options, refusal) {
                   ${revision}, ${params.source ?? null}, ${turnaroundMs}, ${bufferBeforeMs}
                 )`;
                         }
-                        // The normalized children are the queryable/canonical representation. The JSON
-                        // columns above remain a migration-compatibility mirror until older readers retire.
+                        // The normalized children are canonical; the JSON columns above are a compatibility
+                        // mirror until older readers retire.
                         await replaceCalendarEventChildren(tx, params.tenantRef, eventId, event);
                         await replaceCalendarEventOccurrences(tx, {
                             tenantRef: params.tenantRef,
@@ -3945,11 +3846,8 @@ function buildSlotlockStore(sql, options, refusal) {
                 });
             }
             const after = rollCursor(params.after);
-            // Due: the masters rolledWindow rolls, which do not cover the window and end within the cap
-            // of its start. Those it has never put back come first, then those it has, longest waiting
-            // first: however many it cannot extend, they never stand in front of one it has not tried,
-            // so every pass that is not capped by such new ones reaches the healthy series, and the ones
-            // put back take turns.
+            // Due masters, never-deferred ones first, then deferred ones longest-waiting first: masters
+            // it cannot extend never starve healthy ones, and deferred ones take turns.
             const candidates = await sql `
         SELECT id, materialized_ends_at, roll_retry_at
           FROM slotlock.calendar_events
@@ -3986,10 +3884,8 @@ function buildSlotlockStore(sql, options, refusal) {
                     }
                     catch (error) {
                         if (error instanceof CalendarExpansionLimitError) {
-                            // It takes more than Slotlock expands: a rule that never occurs again, one with no
-                            // cursor to resume from whose search from its start has outgrown the budget, or one an
-                            // earlier Slotlock stored that this one refuses. Nothing was written; its old coverage
-                            // stays, and the masters after it still roll.
+                            // Over the expansion budget (or a rule this release refuses): nothing written, old
+                            // coverage kept, later masters still roll.
                             refused += 1;
                             refusedEventIds.push(candidate.id);
                             await deferRoll(sql, params.tenantRef, candidate.id);
@@ -4002,16 +3898,15 @@ function buildSlotlockStore(sql, options, refusal) {
                         if (code === EXCLUSION_VIOLATION ||
                             code === DEADLOCK_DETECTED ||
                             code === SERIALIZATION_FAILURE) {
-                            // The savepoint rolled every delete/insert back, so the previous materialized
-                            // coverage remains truthful and callers will fail closed beyond it.
+                            // The savepoint rolled everything back, so old coverage stays truthful and callers
+                            // fail closed beyond it.
                             conflicts += 1;
                             conflictEventIds.push(candidate.id);
                             await deferRoll(sql, params.tenantRef, candidate.id);
                             break;
                         }
-                        // Anything else this one series meets (a row no Slotlock would write, a constraint it
-                        // trips) was rolled back with its savepoint too: it is put back like one over the
-                        // budget, so no single row stops the tenant's roll.
+                        // Any other failure was rolled back with its savepoint too: defer it like an
+                        // over-budget one, so no single row stops the tenant's roll.
                         refused += 1;
                         refusedEventIds.push(candidate.id);
                         await deferRoll(sql, params.tenantRef, candidate.id);
@@ -4178,8 +4073,8 @@ function buildSlotlockStore(sql, options, refusal) {
                         idempotent: true,
                     };
                 }
-                // An event's owner and reference never change, so they are read before its identity lock,
-                // which is taken before its row lock as every event write takes them.
+                // Owner and reference never change, so they are read before the identity lock, taken before
+                // the row lock as every event write does.
                 const [identity] = await tx `
           SELECT owner_ref, external_ref FROM slotlock.calendar_events
            WHERE tenant_ref = ${params.tenantRef} AND id = ${params.eventId}`;
@@ -4190,7 +4085,6 @@ function buildSlotlockStore(sql, options, refusal) {
           SELECT id, resource_id, revision FROM slotlock.calendar_events
            WHERE tenant_ref = ${params.tenantRef} AND id = ${params.eventId}
            FOR UPDATE`;
-                // Cancelled while this waited on its lock.
                 if (!found)
                     return { ok: false, code: 'event_not_found' };
                 if (params.expectedResourceId !== undefined &&
@@ -4290,7 +4184,6 @@ function buildSlotlockStore(sql, options, refusal) {
                 catch (error) {
                     if (pgCode(error) !== EXCLUSION_VIOLATION)
                         throw error;
-                    // It stays where it was; whoever owns it decides.
                     await report(event, 'event.timezone_conflict');
                     conflicts++;
                 }
@@ -4307,8 +4200,8 @@ function buildSlotlockStore(sql, options, refusal) {
                     code: 'invalid_limit',
                 });
             }
-            // Never under the default: a shorter retention trims the feed, not how long a retried write
-            // is answered as the first was.
+            // Never under the default: a shorter retention trims the feed, not how long a retry is
+            // answered as the first was.
             const keepDays = params.retentionDays ?? Math.max(retentionDays, SLOTLOCK_EVENT_COMMAND_RETENTION_DAYS);
             if (!Number.isSafeInteger(keepDays) ||
                 keepDays < 1 ||
@@ -4318,11 +4211,10 @@ function buildSlotlockStore(sql, options, refusal) {
                 });
             }
             return inTransaction(sql, async (tx) => {
-                // A 0.2 server still serving after the migration wrote its confirmed holds (and
-                // createReservation bookings) on the tenant's resources without the tenant or a reference,
-                // so no cancel or move reaches them; the migration gives those it finds the tenant and
-                // their own id, and this gives later ones the same. Each takes its reference's identity lock
-                // first, as every booking write does; a tombstone of its id retired nothing and goes.
+                // A 0.2 server still running after the migration wrote confirmed holds and
+                // createReservation bookings without the tenant or a reference; give them both, as the
+                // migration does. Each takes its reference's identity lock first, and a tombstone of its id
+                // goes.
                 const legacy = await tx `
           SELECT booking.id
             FROM slotlock.reservations booking
@@ -4402,8 +4294,8 @@ function buildSlotlockStore(sql, options, refusal) {
                     code: 'invalid_limit',
                 });
             }
-            // Never under the default: a shorter retention trims the feed, not how long a retried write
-            // is answered as the first was.
+            // Never under the default: a shorter retention trims the feed, not how long a retry is
+            // answered as the first was.
             const keepDays = params.retentionDays ?? Math.max(retentionDays, SLOTLOCK_EVENT_COMMAND_RETENTION_DAYS);
             if (!Number.isSafeInteger(keepDays) ||
                 keepDays < 1 ||
@@ -4413,8 +4305,8 @@ function buildSlotlockStore(sql, options, refusal) {
                 });
             }
             return inTransaction(sql, async (tx) => {
-                // Commands are exact-replay evidence, never resurrection authority: after the window every
-                // owner's are eligible, and the active event or tombstone stays canonical where present.
+                // Commands are replay evidence, never resurrection authority: after the window every
+                // owner's go.
                 const commands = await tx `
           WITH candidates AS MATERIALIZED (
             SELECT command.owner_ref, command.idempotency_key
@@ -4434,9 +4326,8 @@ function buildSlotlockStore(sql, options, refusal) {
             RETURNING 1
           )
           SELECT count(*)::int AS deleted FROM deleted`;
-                // Once every command of an agent-owned cancelled identity is gone its tombstone may follow;
-                // internal tombstones are provider/sync authority and stay. Event writers lock the tombstone
-                // row, so a row they hold is skipped and the delete repeats the selection predicate.
+                // An agent-owned tombstone may follow once all its commands are gone; internal ones are
+                // provider/sync authority and stay. Locked rows are skipped and the predicate rechecked.
                 const tombstones = await tx `
           WITH candidates AS MATERIALIZED (
             SELECT tombstone.owner_ref, tombstone.external_ref
@@ -4532,7 +4423,6 @@ function buildSlotlockStore(sql, options, refusal) {
                     if (params.revision !== currentRevision + 1) {
                         return { ok: false, code: 'revision_conflict' };
                     }
-                    // A fresh read ends a staleness: the next one is reported again.
                     await tx `
             UPDATE slotlock.calendar_coverage
                SET starts_at = ${window.start}, ends_at = ${window.end},
@@ -4686,7 +4576,7 @@ function buildSlotlockStore(sql, options, refusal) {
             if (refusal)
                 return 0;
             const tenantRef = params.tenantRef;
-            // The same test twice: to find them, then under each reference's lock, as a cancel takes it.
+            // The same test twice: to find them, then under each reference's lock.
             const due = (tx, externalRef) => tx `
         SELECT reservation.id, reservation.external_ref, reservation.revision, reservation.resource_id,
                (resource.booking_rules->>'checkInMinutes')::int AS minutes
@@ -4771,7 +4661,8 @@ function buildSlotlockStore(sql, options, refusal) {
                     if (!member)
                         return { ok: false, code: 'pool_not_found' };
                 }
-                // Counted under the tenant's waitlist lock, which offers take too, so racing joins stop at the cap.
+                // Counted under the tenant's waitlist lock, which offers take too, so racing joins stop at
+                // the cap.
                 await tx `SELECT pg_advisory_xact_lock(hashtextextended(${JSON.stringify(['slotlock-waitlist', tenantRef])}, 0))`;
                 const [counts] = await tx `
           SELECT count(*)::int AS tenant, count(*) FILTER (WHERE holder_ref = ${holderRef})::int AS holder
@@ -4812,7 +4703,6 @@ function buildSlotlockStore(sql, options, refusal) {
             if (!isValidIdentity(params.tenantRef) || !isValidResourceId(params.id))
                 return false;
             return inTransaction(sql, async (tx) => {
-                // Waits for an offer pass that has this entry locked, so it leaves what that pass decided.
                 const [left] = await tx `
           DELETE FROM slotlock.waitlist_entries
            WHERE tenant_ref = ${params.tenantRef} AND id = ${params.id}
@@ -4820,8 +4710,7 @@ function buildSlotlockStore(sql, options, refusal) {
           RETURNING hold_id`;
                 if (!left)
                     return false;
-                // An offer not yet taken goes too, freeing the time for the next who waits; a confirmed
-                // one is a booking now and stays.
+                // An untaken offer's hold goes too; a confirmed one is a booking now and stays.
                 if (left.hold_id) {
                     await buildSlotlockStore(tx, options, null).releaseHold(left.hold_id, { tenantRef: params.tenantRef });
                 }
@@ -5020,7 +4909,6 @@ function buildSlotlockStore(sql, options, refusal) {
              WHERE tenant_ref = ${tenantRef} AND status <> 'waiting'
                AND ends_at < statement_timestamp() - make_interval(days => ${retentionDays})`;
                 }
-                // One page in join order; the caller passes `next` back for the rest.
                 const waiting = await tx `
           SELECT ${tx.unsafe(WAITLIST_COLUMNS)} FROM slotlock.waitlist_entries
            WHERE tenant_ref = ${tenantRef} AND status = 'waiting'
@@ -5028,19 +4916,16 @@ function buildSlotlockStore(sql, options, refusal) {
                   OR (created_at, id) > (${after?.createdAt ?? null}::timestamptz, ${after?.id ?? null}::uuid))
            ORDER BY created_at, id
            LIMIT ${limit}`;
-                // Holds made through a store on this transaction, each in a savepoint of its own.
                 const inner = buildSlotlockStore(tx, options, null);
                 let offered = 0;
                 for (const entry of waiting) {
-                    // Locked so a leave waits for this offer, and skipped if it left first.
                     const [still] = await tx `
             SELECT 1 FROM slotlock.waitlist_entries
              WHERE id = ${entry.id} AND status = 'waiting' FOR UPDATE`;
                     if (!still)
                         continue;
-                    // Only resources whose window looks free are tried: a hold refused keeps its locks
-                    // until the transaction ends, so trying every member of a full pool would pile them up.
-                    // A hold there keeps the resource's buffers (its rules as they apply), so they must be free too.
+                    // Only resources that look free (buffers included) are tried: a refused hold keeps its
+                    // locks until the transaction ends.
                     const candidates = await tx `
             SELECT resources.id
               FROM slotlock.resources,
@@ -5136,7 +5021,6 @@ function buildSlotlockStore(sql, options, refusal) {
                     code: 'resource_tenant_mismatch',
                 });
             }
-            // Each row's occupied time: its buffers are as busy as the booking.
             const busyRows = await sql `
         SELECT COALESCE(reservation.occupied_starts_at, reservation.starts_at) AS starts_at,
                COALESCE(reservation.occupied_ends_at, reservation.ends_at) AS occupied_ends_at
@@ -5187,8 +5071,8 @@ function buildSlotlockStore(sql, options, refusal) {
           FROM recurring_sources
          WHERE earliest_possible_at < ${window.end}`;
             const localRecurrenceRequired = Number(localRecurrenceCoverage?.source_count ?? 0) > 0;
-            // A resource that requires certainty requires every sync recording coverage of it, as its
-            // writes do (bookingJudge), and judges them by the same day.
+            // Requiring certainty means every sync covering the resource, judged by the same day, as
+            // writes do (bookingJudge).
             const requireCertain = owner[0].require_certain;
             const recordedSources = requireCertain
                 ? (await sql `
@@ -5223,8 +5107,8 @@ function buildSlotlockStore(sql, options, refusal) {
             let hasFreshOverlap = coverageRows.some((coverage) => coverage.fresh && coverage.starts_at < window.end && coverage.ends_at > window.start);
             if (localRecurrenceRequired) {
                 if (localRecurrenceCoverage?.complete !== true) {
-                    // Put the intrinsic source first: it is the boundary the caller can repair by rolling
-                    // the event horizon, independently of any provider snapshot repair.
+                    // The intrinsic source first: the caller can repair it by rolling the horizon,
+                    // independent of providers.
                     missingSources.unshift(SLOTLOCK_LOCAL_RECURRENCE_COVERAGE_SOURCE);
                 }
                 hasFreshOverlap ||= localRecurrenceCoverage?.overlaps === true;
@@ -5273,8 +5157,6 @@ function buildSlotlockStore(sql, options, refusal) {
                 return null;
             const resource = toResource(row);
             const rules = params.rules ?? resource.availabilityRules ?? [];
-            // Only what a booking made now may take: the resource's booking rules (as they apply) bound
-            // the search.
             const search = bookingSearch({
                 rules: resource.effectiveBookingRules,
                 timezone: resource.timezone,
@@ -5285,11 +5167,11 @@ function buildSlotlockStore(sql, options, refusal) {
             if (!search)
                 return null;
             const { window } = search;
-            // A slot's buffers may run past the window: the time they can reach must be proven free too.
+            // A slot's buffers may run past the window: that reach must be proven free too.
             const reach = bookingSearchReach(search);
             let busy;
             if (tenantRef === null) {
-                // No event, coverage or series can belong to a resource with no tenant: only its rows.
+                // A tenantless resource has no events, coverage or series: only its rows.
                 busy = await this.listBusy(params.resourceId, reach);
             }
             else {
@@ -5311,7 +5193,7 @@ function buildSlotlockStore(sql, options, refusal) {
                             ? { coverageMaxAgeMs: params.coverageMaxAgeMs }
                             : {}),
                     });
-                    // Absence is never treated as free time: what cannot be proven gives no slot.
+                    // Absence is never free time.
                     if (freeBusy.coverage.state !== 'complete')
                         return null;
                     busy.push(...freeBusy.busy);
@@ -5394,7 +5276,7 @@ function buildSlotlockStore(sql, options, refusal) {
     };
     return Object.assign(store, Object.fromEntries(SLOTLOCK_TENANT_WRITE_METHODS.map((name) => [name, refuse])));
 }
-/** The deployment role alone may suspend: another role is refused EXECUTE on the functions. */
+/** The deployment role alone may suspend: others are refused EXECUTE on the functions. */
 function suspensionRefusal(error) {
     if (pgCode(error) !== '42501')
         return error;