slotlock 0.6.2 → 0.7.0

package/types.d.ts

@@ -1,4 +1,5 @@
 import type { SlotlockBookingRule, SlotlockBookingRules } from './booking-rules.js';
+import type { SlotlockResourceAttributes, SlotlockResourceKind } from './resource-profile.js';
 /** Half-open time interval `[start, end)`. */
 export interface Interval {
     start: Date;
@@ -11,10 +12,9 @@ export interface SlotlockResource {
     /** Null only for legacy/parity-shadow resources created before authority primitives existed. */
     tenantRef: string | null;
     /**
-     * IANA timezone the resource's availability rules are authored in. expandRules evaluates
-     * BYDAY/startMinutes as LOCAL wall-clock in this zone (DST-correct, wall-clock ends);
-     * findNextAvailableFor reads it from the stored resource. Formerly the documented
-     * Rules remain stable across daylight-saving changes because wall time is resolved in this zone.
+     * IANA timezone the availability rules are authored in: expandRules evaluates BYDAY and
+     * startMinutes as local wall-clock time in this zone, so rules stay stable across daylight-saving
+     * changes.
      */
     timezone: string;
     /**
@@ -23,9 +23,8 @@ export interface SlotlockResource {
      */
     availabilityRules?: WeeklyAvailabilityRule[];
     /**
-     * `shared` resources are listed to agents and booked through them; `private` ones are invisible
-     * to agents and reached only by the tenant's own code. Fixed when the resource is created. The
-     * store always says which; a resource built elsewhere without it is shared.
+     * `shared` resources are listed to and booked by agents; `private` ones are invisible to agents.
+     * Fixed at creation; absent means shared.
      */
     visibility?: 'shared' | 'private';
     /** When the tenant archived it: no longer listed or booked, its history kept. Absent in use. */
@@ -33,25 +32,109 @@ export interface SlotlockResource {
     /** Its own booking rules (`SlotlockBookingRules`). Absent when it has none. */
     bookingRules?: SlotlockBookingRules;
     /**
-     * What a booking on it must satisfy: the tenant's default rules, overlaid by its pool's, overlaid
-     * by its own (`setBookingRuleDefaults`), a field set at a narrower level winning. Absent when no
-     * rule applies.
+     * What a booking on it must satisfy: tenant defaults, overlaid by its pool's, overlaid by its own
+     * (`setBookingRuleDefaults`). Absent when no rule applies.
      */
     effectiveBookingRules?: SlotlockBookingRules;
     /**
-     * The pool it belongs to: interchangeable resources sharing a name, such as a vehicle class or a
-     * room type, booked by the class (`slotlock_book_pool`). Absent when it is in none.
+     * Its pool: interchangeable resources (a vehicle class, a room type) booked by the class
+     * (`slotlock_book_pool`).
      */
     pool?: string;
+    /**
+     * The composite it is a part of (RFC 0003 G8), and its place there: a booking of the whole
+     * conflicts with every part. Absent when it is no part.
+     */
+    parentId?: string;
+    partIndex?: number;
+    /** Its name, shown instead of `externalRef` (resource-profile.ts). Absent when it has none. */
+    name?: string;
+    /** What it is, in a sentence or a paragraph. Absent when it has none. */
+    description?: string;
+    /** What kind of thing it is, a hint for filtering that changes no booking. Absent: `other`. */
+    kind?: SlotlockResourceKind;
+    /** How many people or seats it holds, said for people to read; never enforced. Absent: not said. */
+    capacity?: number;
+    /** Labels to find it by, sorted. Absent when it has none. */
+    labels?: string[];
+    /** What the integrator keeps on it. Absent when it has none. */
+    attributes?: SlotlockResourceAttributes;
+    /** The reference of the location it is at (resource-profile.ts). Absent when not said. */
+    location?: string;
+    /** That location's name. */
+    locationName?: string;
+    /** The references of the groups it is in, sorted. Absent when it is in none. */
+    groups?: string[];
+}
+/** Which writes an approval policy covers (RFC 0004 A4); none named is every write it applies to. */
+export type SlotlockApprovalKind = 'single' | 'pool' | 'bundle' | 'move';
+/** A tenant's approval policy (RFC 0004 A4). */
+export interface SlotlockApprovalPolicy {
+    ref: string;
+    name: string;
+    /** The resources it applies to; every one when all are empty. */
+    appliesTo: {
+        resourceIds?: string[];
+        pools?: string[];
+        locations?: string[];
+        groups?: string[];
+    };
+    /** What makes a write need it; a write meets it when it meets every condition given. */
+    conditions: {
+        longerThanMinutes?: number;
+        outsideHours?: boolean;
+        kinds?: SlotlockApprovalKind[];
+    };
+    outcome: 'require_approval' | 'refuse';
+    /** How long a person has to decide, before the booking's start less `leadMinutes`. */
+    approvalTtlMinutes: number;
+    leadMinutes: number;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/** A write waiting for a person, or decided (RFC 0004 A4). */
+export interface SlotlockApproval {
+    id: string;
+    policyRef: string;
+    status: 'pending' | 'granted' | 'declined' | 'expired';
+    /** The agent operation it runs when granted, and its arguments. */
+    operation: 'slotlock_create_event' | 'slotlock_book_together' | 'slotlock_update_event';
+    request: Record<string, unknown>;
+    /** Who asked, as the history names an actor (the principal's subject, at most 200 characters). */
+    requestedBy: string | null;
+    /** The resources and time it holds while it waits. */
+    holdIds: string[];
+    resourceIds: string[];
+    start: Date;
+    end: Date;
+    expiresAt: Date;
+    decidedBy: string | null;
+    decidedAt: Date | null;
+    reason: string | null;
+    createdAt: Date;
+}
+/**
+ * A booking, hold or event occurrence as a refusal can name it (`describeBooking`): the time it
+ * occupies, buffers included, and whose it is, so a caller is told only what it may see.
+ */
+export interface SlotlockBookingDescription {
+    id: string;
+    resourceId: string;
+    status: 'held' | 'confirmed';
+    /** The holder of a hold, as the store was given it; null otherwise. */
+    holderRef: string | null;
+    /** The calendar event this is an occurrence of (its id and reference), and its owner; null for a booking. */
+    eventId: string | null;
+    eventRef: string | null;
+    eventOwnerRef: string | null;
+    start: Date;
+    end: Date;
 }
 /** A confirmed occupation of a resource. The DB EXCLUDE constraint is the overlap arbiter. */
 export interface SlotlockReservation {
     id: string;
     resourceId: string;
-    /**
-     * Null only for live holds, rows on a resource that has no tenant (legacy), and parity-shadow rows.
-     * A booking made by confirming a hold, or by createReservation, on a tenant's resource has one.
-     */
+    /** Null only for live holds, rows on a tenantless (legacy) resource, and parity-shadow rows. */
     tenantRef: string | null;
     /**
      * Stable booking identity inside tenantRef; null exactly when tenantRef is. A confirmed hold, and
@@ -170,17 +253,15 @@ export type CancelExternalReservationResult = {
     limit: number;
 };
 /**
- * VAVAILABILITY-style bookable window (RFC 7953 semantics, weekly subset): a weekly-cadence RRULE
- * picks the days; the window on each matching day runs `[startMinutes, startMinutes+durationMinutes)`
- * after that day's local midnight in the evaluation timezone (`expandRules`' `timezone`, the
- * resource's stored zone for `findNextAvailableFor`, UTC when none is given).
+ * VAVAILABILITY-style bookable window (RFC 7953, weekly subset): a weekly RRULE picks the days, and
+ * each day's window is `[startMinutes, startMinutes+durationMinutes)` after local midnight in the
+ * evaluation timezone (UTC when none is given).
  */
 export interface WeeklyAvailabilityRule {
     /** RRULE content line without the `RRULE:` prefix, e.g. `FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR`. */
     rrule: string;
-    /** Window start, minutes after midnight in the evaluation timezone (UTC when none is given) of each matching day (0..1439). */
+    /** Window start, minutes after local midnight (0..1439). */
     startMinutes: number;
-    /** Window length in minutes (> 0). */
     durationMinutes: number;
 }
 export type CreateReservationResult = {
@@ -243,7 +324,6 @@ export interface SlotlockAgendaEntry {
     resourceId: string;
     start: Date;
     end: Date;
-    /** A booking, a calendar event's occurrence, or a live hold. */
     kind: 'booking' | 'event' | 'hold';
     /** The booking's reference; null for an event's occurrence and a hold. */
     reference: string | null;
@@ -447,18 +527,17 @@ export interface PutCalendarEventCommand extends CalendarEventContent {
     materializationWindow?: Interval;
     source?: string;
     /**
-     * Judge the event as a booking made now against the resource's booking rules (its first
-     * occurrence for notice and advance, every occurrence for step and hours), and keep the
-     * resource's turnaround after each occurrence. Off by default: an imported event is what happened
-     * elsewhere. The agent tools set it.
+     * Judge the event as a booking made now against the resource's booking rules (first occurrence
+     * for notice and advance, every occurrence for step and hours), and keep the resource's
+     * turnaround. Off by default, since an imported event already happened elsewhere; the agent tools
+     * set it.
      */
     enforceBookingRules?: boolean;
     /**
-     * Book the time a live hold keeps: the hold must be `holderRef`'s (`acquireHold`'s
-     * `principalRef`), on this resource, and cover the event, a single occurrence. In one transaction
-     * the hold and the rest of its group are released and the event takes the time, so no rival can
-     * come between. Its notice and advance were judged when it was held; step and hours are judged
-     * again.
+     * Book the time a live hold keeps: the hold must be `holderRef`'s, on this resource, and cover
+     * the event (a single occurrence). The hold's group is released and the event takes the time in
+     * one transaction, so no rival can come between. Notice and advance were judged at hold time;
+     * step and hours are judged again.
      */
     fromHold?: {
         holdId: string;
@@ -515,11 +594,16 @@ export type PutCalendarEventResult = {
     code: 'revision_conflict';
     currentRevision: number;
 }
-/** `fromHold` names no live hold of that holder's: released, booked, expired, or another's. */
+/** `fromHold` names no hold of that holder's: released, booked, reaped, or another's. */
  | {
     ok: false;
     code: 'hold_not_found';
 }
+/** `fromHold`'s hold is the holder's, but it lapsed before it was booked. */
+ | {
+    ok: false;
+    code: 'hold_expired';
+}
 /** `fromHold`'s hold is on another resource, or does not cover the event. */
  | {
     ok: false;
@@ -581,14 +665,11 @@ export type CancelCalendarEventResult = {
     code: 'revision_conflict';
     currentRevision: number;
 };
-/**
- * A place in the roll's order of due masters: the last one a batch examined. The roll takes the
- * masters it has never put back first, then those it has, longest waiting first.
- */
+/** A place in the roll's order of due masters: the last one a batch examined. */
 export interface CalendarHorizonRollCursor {
     /**
-     * When the master was due to be examined again, if the roll had put it back; null (or, from a
-     * cursor of an earlier release, missing) when it had not.
+     * When the master was due again, if the roll had deferred it; null (or missing, from an older
+     * cursor) when not.
      */
     rollRetryAt?: Date | null;
     materializedEndsAt: Date;
@@ -596,34 +677,27 @@ export interface CalendarHorizonRollCursor {
 }
 /** Content-minimized outcome of one bounded recurring-event horizon maintenance batch. */
 export interface CalendarHorizonRollResult {
-    /** Due recurring masters examined in deterministic order. */
     examined: number;
     /**
-     * Masters atomically rematerialized from the requested window's start through the later of their
-     * stored end and the window's: a roll never moves a series' end back.
+     * Masters rematerialized through the later of their stored end and the window's: a roll never
+     * moves a series' end back.
      */
     extended: number;
-    /**
-     * Masters whose new occurrence collided; their previous coverage remains intact, and they wait an
-     * hour before a roll examines them again, behind every master it has not put back.
-     */
+    /** Masters whose new occurrence collided: their coverage stays, and they are deferred an hour. */
     conflicts: number;
     /** The ids of those masters: what blocks each is a booking or hold on its new occurrences. */
     conflictEventIds: string[];
     /**
-     * Masters whose rule takes more than the expansion budget to reach the window (one that never
-     * occurs again, or almost never), or whose roll failed for any other reason; their previous
-     * coverage remains intact, and they wait an hour
-     * before a roll examines them again, behind every master it has not put back.
+     * Masters over the expansion budget, or whose roll failed otherwise: their coverage stays, and
+     * they are deferred an hour.
      */
     refused: number;
-    /** The ids of those masters, to find and fix them. */
     refusedEventIds: string[];
     /** True when more due masters remain beyond this bounded batch. */
     hasMore: boolean;
     /**
-     * Pass as `after` for the next batch of this pass, so the masters this batch examined are not
-     * examined again by every later batch. `null` when none remain.
+     * Pass as `after` for the next batch, so this batch's masters are not examined again. `null` when
+     * none remain.
      */
     next: CalendarHorizonRollCursor | null;
 }
@@ -635,7 +709,6 @@ export interface CalendarEventRetentionResult {
     /** True when either class filled its batch, so more rows may already be eligible. */
     hasMore: boolean;
 }
-/** What erasing a tenant deleted. */
 /** A tenant's default booking rules (`SlotlockStore.getBookingRuleDefaults`). */
 export interface SlotlockBookingRuleDefaults {
     /** The tenant's own defaults, under every pool's; null when it has none. */
@@ -650,13 +723,13 @@ export interface SlotlockTenantErasure {
     total: number;
 }
 export interface BookingRetentionResult {
-    /** Holds past their expiry: they occupy nothing, and only a rival's write would reap them. */
+    /** Holds past their expiry: they occupy nothing, but only a rival's write would reap them. */
     expiredHoldsDeleted: number;
     /** Keyed hold answers whose hold has expired: a retry with that key makes a new hold. */
     holdCommandsDeleted: number;
     /**
-     * References a cancel retired with no booking, older than the window: a create with one makes a
-     * new booking. A cancelled booking's reference stays retired.
+     * References a cancel retired with no booking, older than the window. A cancelled booking's
+     * reference stays retired.
      */
     tombstonesDeleted: number;
     /** True when any class filled its batch, so more rows may already be eligible. */

package/usage.d.ts

@@ -0,0 +1,106 @@
+import type { SlotlockAgentUsage } from './agent-server.js';
+import { SLOTLOCK_RECORDED_USAGE_METRICS, SLOTLOCK_USAGE_METRICS, SLOTLOCK_USAGE_RETENTION_DAYS } from './ddl.js';
+import type { SlotlockSql } from './store.js';
+export type SlotlockUsageMetric = (typeof SLOTLOCK_USAGE_METRICS)[number];
+/** What a server counts and records itself; bookings, holds and resources the database counts. */
+export type SlotlockRecordedUsageMetric = (typeof SLOTLOCK_RECORDED_USAGE_METRICS)[number];
+export { SLOTLOCK_RECORDED_USAGE_METRICS, SLOTLOCK_USAGE_METRICS, SLOTLOCK_USAGE_RETENTION_DAYS };
+/** One counted row: a tenant's count of one metric on one UTC day, by key ('' for none) and surface. */
+export interface SlotlockUsageCount {
+    tenantRef: string;
+    /** The UTC day, `YYYY-MM-DD`. */
+    day: string;
+    metric: SlotlockRecordedUsageMetric;
+    keyId: string;
+    origin: string;
+    count: number;
+}
+export interface SlotlockUsageMeterOptions {
+    /** Records one batch once per `flushId`: true when added, false when it was added before. */
+    record(flushId: string, rows: readonly SlotlockUsageCount[]): Promise<boolean>;
+    /** How often counts are recorded, in milliseconds (default 15,000). 0: only on `flush`. */
+    intervalMs?: number;
+    now?: () => number;
+    /** A batch the database refused (kept for the next flush), or one dropped after too many. */
+    onError?: (error: unknown) => void;
+}
+export interface SlotlockUsageMeter {
+    /** Count one operation (the agent server's `onUsage`). Never throws, never waits. */
+    count(usage: SlotlockAgentUsage): void;
+    /**
+     * Count something else a server sees: webhook deliveries an endpoint accepted, messages to the
+     * assistant. Never throws, never waits; a count below 1 is ignored.
+     */
+    add(usage: {
+        tenantRef: string;
+        metric: Exclude<SlotlockRecordedUsageMetric, 'operations'>;
+        origin: string;
+        count?: number;
+        keyId?: string;
+    }): void;
+    /**
+     * Record what has been counted. A batch the database refuses is kept, with its id, and sent again
+     * first next time, so a batch whose answer was lost is never added twice.
+     */
+    flush(): Promise<void>;
+    /** Stop the timer and record what is left. */
+    close(): Promise<void>;
+    /** Rows counted and not yet recorded, held batches included. */
+    pending(): number;
+    /**
+     * What this meter has counted of a tenant's metric on `fromDay` (`YYYY-MM-DD`) or later and not
+     * yet recorded, batches held or being sent included, and how much of it it has counted since it
+     * started: quotas.ts adds them to what the database holds.
+     */
+    local(tenantRef: string, metric: SlotlockRecordedUsageMetric, fromDay: string): {
+        unrecorded: number;
+        counted: number;
+    };
+}
+/** The UTC day of an instant, `YYYY-MM-DD`. */
+export declare function slotlockUsageDay(at: number): string;
+export declare function createSlotlockUsageMeter(options: SlotlockUsageMeterOptions): SlotlockUsageMeter;
+/** `slotlock.record_usage`: one batch of counts, once per flush id. */
+export declare function recordSlotlockUsage(sql: SlotlockSql, flushId: string, rows: readonly SlotlockUsageCount[]): Promise<boolean>;
+/** One stored row of a tenant's usage. */
+export interface SlotlockUsageRow {
+    day: string;
+    metric: SlotlockUsageMetric;
+    keyId: string;
+    origin: string;
+    count: number;
+}
+/** The tenant's usage from `from` to `to`, UTC days inclusive (at most SLOTLOCK_USAGE_RETENTION_DAYS apart). */
+export declare function readSlotlockTenantUsage(sql: SlotlockSql, tenantRef: string, from: string, to: string): Promise<SlotlockUsageRow[]>;
+/**
+ * Each metric's total over some rows: every metric present, 0 when unused. Resources are a count
+ * each day, not something used up, so theirs is the latest day's.
+ */
+export declare function totalSlotlockUsage(rows: readonly SlotlockUsageRow[]): Record<SlotlockUsageMetric, number>;
+/** Operations, bookings and holds together: one line of a usage summary. */
+export type SlotlockUsageTotals = Record<SlotlockUsageMetric, number>;
+/** A tenant's usage over a range, as `GET /v1/usage` and the Plan page show it. */
+export interface SlotlockUsageSummary {
+    totals: SlotlockUsageTotals;
+    /** Each UTC day with any use, in order. */
+    days: Array<{
+        day: string;
+    } & SlotlockUsageTotals>;
+    /** Each API key with any use (`keyId` null: no key, such as the assistant), most operations first; no resources. */
+    keys: Array<{
+        keyId: string | null;
+    } & SlotlockUsageTotals>;
+    /** Each surface with any use (mcp, a2a, rest, application, dashboard-assistant, webhooks), most first; no resources. */
+    surfaces: Array<{
+        origin: string;
+    } & SlotlockUsageTotals>;
+}
+/** Totals, by day, by key and by surface, from stored rows: bounded however many rows there are. */
+export declare function summarizeSlotlockUsage(rows: readonly SlotlockUsageRow[]): SlotlockUsageSummary;
+/** The range `GET /v1/usage` reads when given none: the first of this UTC month to today. */
+export declare function slotlockUsageMonthToDate(at: number): {
+    from: string;
+    to: string;
+};
+/** Days from `from` to `to`, both `YYYY-MM-DD`: 0 for the same day, negative when `to` is earlier. */
+export declare function slotlockUsageSpanDays(from: string, to: string): number;

package/usage.js

@@ -0,0 +1,238 @@
+// Usage metering (RFC 0003 part 3): how much each tenant uses the service, by UTC day, API key and
+// surface. Operations are counted by the server that runs them (`createSlotlockUsageMeter`, fed by
+// the agent server's `onUsage`) and recorded in batches; bookings and holds are rolled up from the
+// tenant's feed by maintenance, so a write that rolled back is never counted. Counts only, never
+// arguments or results. Off unless the deployment asks for it (SLOTLOCK_USAGE=on).
+import { randomUUID } from 'node:crypto';
+import { SLOTLOCK_RECORDED_USAGE_METRICS, SLOTLOCK_USAGE_METRICS, SLOTLOCK_USAGE_RETENTION_DAYS, } from './ddl.js';
+export { SLOTLOCK_RECORDED_USAGE_METRICS, SLOTLOCK_USAGE_METRICS, SLOTLOCK_USAGE_RETENTION_DAYS };
+/** Rows one `slotlock.record_usage` call takes. */
+const MAX_BATCH_ROWS = 10_000;
+/** Batches kept for another try while the database refuses them; older ones are dropped, and said so. */
+const MAX_HELD_BATCHES = 100;
+/** PostgreSQL's invalid_parameter_value: record_usage refusing a batch it will never take. */
+const REFUSED_FOR_GOOD = '22023';
+/** Tenants whose running totals one meter keeps (`local`); past this they start again from 0. */
+const MAX_TOTALS = 100_000;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+/** The UTC day of an instant, `YYYY-MM-DD`. */
+export function slotlockUsageDay(at) {
+    return new Date(at).toISOString().slice(0, 10);
+}
+export function createSlotlockUsageMeter(options) {
+    const now = options.now ?? Date.now;
+    let counted = new Map();
+    const held = [];
+    // Rows taken from `counted` for the flush under way, until each batch is recorded or held.
+    let sending = [];
+    // Everything counted since the meter started, by tenant and metric.
+    let totals = new Map();
+    let running = Promise.resolve();
+    const report = (error) => {
+        try {
+            options.onError?.(error);
+        }
+        catch {
+            // A reporter's failure changes nothing.
+        }
+    };
+    const dropped = (rows, why) => report(Object.assign(new Error(`Slotlock usage: ${String(rows)} counts dropped ${why}`), {
+        code: 'usage_dropped',
+    }));
+    // True when recorded, or when the database refused the batch for good (record_usage's
+    // invalid_parameter_value: a day it no longer takes, after an outage past the next day), which is
+    // then dropped rather than held in front of every batch after it. False to try again.
+    async function send(batch) {
+        try {
+            await options.record(batch.flushId, batch.rows);
+            return true;
+        }
+        catch (error) {
+            report(error);
+            if (error?.code === REFUSED_FOR_GOOD) {
+                dropped(batch.rows.length, 'that the database will not take');
+                return true;
+            }
+            return false;
+        }
+    }
+    async function flushOnce() {
+        // Batches refused before go first, under their own ids.
+        while (held.length > 0) {
+            if (!(await send(held[0])))
+                return;
+            held.shift();
+        }
+        if (counted.size === 0)
+            return;
+        const rows = [...counted.values()];
+        counted = new Map();
+        sending = rows;
+        try {
+            for (let start = 0; start < rows.length; start += MAX_BATCH_ROWS) {
+                const batch = { flushId: randomUUID(), rows: rows.slice(start, start + MAX_BATCH_ROWS) };
+                if (held.length > 0 || !(await send(batch)))
+                    held.push(batch);
+                sending = rows.slice(start + MAX_BATCH_ROWS);
+            }
+        }
+        finally {
+            sending = [];
+        }
+        while (held.length > MAX_HELD_BATCHES) {
+            const oldest = held.shift();
+            dropped(oldest?.rows.length ?? 0, `after the database refused them ${String(MAX_HELD_BATCHES)} times`);
+        }
+    }
+    const flush = () => {
+        running = running.then(flushOnce, flushOnce);
+        return running;
+    };
+    const interval = options.intervalMs ?? 15_000;
+    const timer = interval > 0 ? setInterval(() => void flush(), interval) : null;
+    timer?.unref?.();
+    function tally(tenantRef, metric, keyIdGiven, origin, count) {
+        try {
+            if (typeof tenantRef !== 'string' || tenantRef.length === 0)
+                return;
+            if (!Number.isSafeInteger(count) || count < 1)
+                return;
+            const keyId = typeof keyIdGiven === 'string' && UUID.test(keyIdGiven) ? keyIdGiven : '';
+            const day = slotlockUsageDay(now());
+            const key = `${tenantRef}\0${day}\0${metric}\0${keyId}\0${origin}`;
+            const found = counted.get(key);
+            if (found)
+                found.count += count;
+            else
+                counted.set(key, { tenantRef, day, metric, keyId, origin, count });
+            const total = `${tenantRef}\0${metric}`;
+            if (!totals.has(total) && totals.size >= MAX_TOTALS)
+                totals = new Map();
+            totals.set(total, (totals.get(total) ?? 0) + count);
+        }
+        catch {
+            // Metering never changes a call.
+        }
+    }
+    return {
+        count({ principal, origin }) {
+            tally(principal.tenantRef, 'operations', principal.keyId, origin, 1);
+        },
+        add({ tenantRef, metric, origin, count = 1, keyId }) {
+            tally(tenantRef, metric, keyId, origin, count);
+        },
+        flush,
+        async close() {
+            if (timer)
+                clearInterval(timer);
+            await flush();
+        },
+        pending() {
+            return [...counted.values()].length + held.reduce((sum, batch) => sum + batch.rows.length, 0);
+        },
+        local(tenantRef, metric, fromDay) {
+            let unrecorded = 0;
+            const add = (row) => {
+                if (row.tenantRef === tenantRef && row.metric === metric && row.day >= fromDay) {
+                    unrecorded += row.count;
+                }
+            };
+            for (const row of counted.values())
+                add(row);
+            for (const row of sending)
+                add(row);
+            for (const batch of held)
+                for (const row of batch.rows)
+                    add(row);
+            return { unrecorded, counted: totals.get(`${tenantRef}\0${metric}`) ?? 0 };
+        },
+    };
+}
+/** `slotlock.record_usage`: one batch of counts, once per flush id. */
+export async function recordSlotlockUsage(sql, flushId, rows) {
+    const payload = rows.map((row) => ({
+        tenant_ref: row.tenantRef,
+        day: row.day,
+        metric: row.metric,
+        key_id: row.keyId,
+        origin: row.origin,
+        count: row.count,
+    }));
+    const [result] = await sql `
+    SELECT slotlock.record_usage(${flushId}::uuid, ${JSON.stringify(payload)}::text::jsonb) AS added`;
+    return result?.added === true;
+}
+/** The tenant's usage from `from` to `to`, UTC days inclusive (at most SLOTLOCK_USAGE_RETENTION_DAYS apart). */
+export async function readSlotlockTenantUsage(sql, tenantRef, from, to) {
+    const rows = await sql `SELECT * FROM slotlock.tenant_usage(${tenantRef}::text, ${from}::date, ${to}::date)`;
+    return rows.map((row) => ({
+        day: typeof row.day === 'string' ? row.day.slice(0, 10) : slotlockUsageDay(row.day.getTime()),
+        metric: row.metric,
+        keyId: row.key_id,
+        origin: row.origin,
+        count: Number(row.count),
+    }));
+}
+/**
+ * Each metric's total over some rows: every metric present, 0 when unused. Resources are a count
+ * each day, not something used up, so theirs is the latest day's.
+ */
+export function totalSlotlockUsage(rows) {
+    const totals = Object.fromEntries(SLOTLOCK_USAGE_METRICS.map((metric) => [metric, 0]));
+    let resourcesDay = '';
+    for (const row of rows) {
+        if (row.metric !== 'resources')
+            totals[row.metric] += row.count;
+        else if (row.day > resourcesDay) {
+            resourcesDay = row.day;
+            totals.resources = row.count;
+        }
+        else if (row.day === resourcesDay)
+            totals.resources += row.count;
+    }
+    return totals;
+}
+/** Totals, by day, by key and by surface, from stored rows: bounded however many rows there are. */
+export function summarizeSlotlockUsage(rows) {
+    const zero = () => totalSlotlockUsage([]);
+    const days = new Map();
+    const keys = new Map();
+    const surfaces = new Map();
+    const add = (map, name, row) => {
+        const found = map.get(name) ?? zero();
+        found[row.metric] += row.count;
+        map.set(name, found);
+    };
+    for (const row of rows) {
+        add(days, row.day, row);
+        // A day's resource count belongs to no key or surface.
+        if (row.metric === 'resources')
+            continue;
+        add(keys, row.keyId, row);
+        add(surfaces, row.origin, row);
+    }
+    const byUse = (a, b) => b.operations - a.operations ||
+        b.bookings - a.bookings ||
+        b.holds - a.holds ||
+        b.webhook_deliveries - a.webhook_deliveries ||
+        b.assistant_messages - a.assistant_messages;
+    return {
+        totals: totalSlotlockUsage(rows),
+        days: [...days].sort(([a], [b]) => a.localeCompare(b)).map(([day, totals]) => ({ day, ...totals })),
+        keys: [...keys]
+            .sort(([a, x], [b, y]) => byUse(x, y) || a.localeCompare(b))
+            .map(([keyId, totals]) => ({ keyId: keyId === '' ? null : keyId, ...totals })),
+        surfaces: [...surfaces]
+            .sort(([a, x], [b, y]) => byUse(x, y) || a.localeCompare(b))
+            .map(([origin, totals]) => ({ origin, ...totals })),
+    };
+}
+/** The range `GET /v1/usage` reads when given none: the first of this UTC month to today. */
+export function slotlockUsageMonthToDate(at) {
+    const to = slotlockUsageDay(at);
+    return { from: `${to.slice(0, 8)}01`, to };
+}
+/** Days from `from` to `to`, both `YYYY-MM-DD`: 0 for the same day, negative when `to` is earlier. */
+export function slotlockUsageSpanDays(from, to) {
+    return Math.round((Date.parse(`${to}T00:00:00Z`) - Date.parse(`${from}T00:00:00Z`)) / 86_400_000);
+}