slotlock 0.6.2 → 0.7.0

package/rate-limit.js

@@ -10,12 +10,17 @@
 // draft-ietf-httpapi-ratelimit-headers-11 (23 May 2026, read 2026-10-24): `"<policy>";r=<remaining>;
 // t=<seconds>` and `"<policy>";q=<quota>;w=<window seconds>`, or `qu="concurrent-requests"` for a
 // cap on requests at once. Retry-After is never earlier than the end of the effective window (§6).
+// With monthly quotas (quotas.ts), each operation's answer also lists them, `"operations_month"` and
+// `"bookings_month"`, counting down to the stop, and one over its quota is refused `quota_exceeded`
+// with Retry-After at the month's end.
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { createHmac, randomBytes } from 'node:crypto';
+import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
 import { isIP } from 'node:net';
 import { SLOTLOCK_MCP_PROTOCOL_VERSION, SLOTLOCK_MCP_RATE_LIMITED_ERROR_CODE, SlotlockAgentOperationError, slotlockAgentOperationScope, } from './agent-server.js';
 import { slotlockBearerCredential } from './api-keys.js';
 import { SLOTLOCK_APPLICATION_SCOPE } from './application-api.js';
+import { SLOTLOCK_TRUSTED_PROXY_PROOF_FIELD, } from './config.js';
+import { slotlockQuotaFields, slotlockQuotaRefusal } from './quotas.js';
 import { SLOTLOCK_APPLICATION_REST_ROUTES, matchSlotlockRestRoute } from './rest-api.js';
 /** Keys one policy remembers; past this, the least recently used tenth is dropped at once. */
 const MAX_BUCKET_KEYS = 100_000;
@@ -46,6 +51,8 @@ const REFUSAL_LOG_INTERVAL_MS = 60_000;
 const MAX_LOGGED_CLIENTS = 10;
 /** Clients counted between two log lines; past this the rest are counted in the totals only. */
 const MAX_COUNTED_CLIENTS = 1_000;
+/** Distinct per-key rates (RFC 0004 A5) one server keeps buckets for; past this the oldest goes. */
+const MAX_KEY_LIMIT_RATES = 1_000;
 /** The IPv6 /64 of an address, which one client is generally assigned whole; null if not IPv6. */
 function ipv6Prefix(address) {
     let text = address.toLowerCase();
@@ -88,9 +95,23 @@ export function slotlockClientNetwork(key) {
     const prefix = /^([0-9a-f]{1,4}:[0-9a-f]{1,4}:[0-9a-f]{1,4}):[0-9a-f]{1,4}::\/64$/.exec(key);
     return prefix ? `${prefix[1]}::/48` : key;
 }
-/** The client a request is counted as: the trusted field's last address, else the connection's. */
-function clientOf(request, connection, trustedField) {
-    if (trustedField !== undefined) {
+const sha256 = (value) => createHash('sha256').update(value, 'utf8').digest();
+/**
+ * Whether the request carries the proxy's secret. Compared as SHA-256 digests in constant time, so
+ * neither the time taken nor a length tells how much of a guess matched. A repeated field arrives
+ * joined with a comma and so never matches.
+ */
+function provenByProxy(request, secretDigest) {
+    const presented = request.headers.get(SLOTLOCK_TRUSTED_PROXY_PROOF_FIELD);
+    return presented !== null && timingSafeEqual(sha256(presented), secretDigest);
+}
+/**
+ * The client a request is counted as: the trusted field's last address, else the connection's.
+ * With a proxy secret, the field is believed only beside the proof.
+ */
+function clientOf(request, connection, trustedField, secretDigest) {
+    const believed = secretDigest === undefined || provenByProxy(request, secretDigest);
+    if (trustedField !== undefined && believed) {
         // A proxy appends to a list field (X-Forwarded-For), so the last entry is the one it wrote.
         const claimed = request.headers.get(trustedField)?.split(',').at(-1);
         const key = claimed === undefined ? null : slotlockClientKey(claimed);
@@ -169,7 +190,7 @@ function concurrencyFields(name, cap) {
     };
 }
 /** Token buckets of one policy, one per key, refilled lazily. */
-function bucketsFor(rate, now) {
+function bucketsFor(rate) {
     const buckets = new Map();
     const refill = (bucket, at) => {
         bucket.tokens = Math.min(rate.burst, bucket.tokens + ((at - bucket.at) / 1_000) * rate.perSecond);
@@ -211,7 +232,7 @@ export function createSlotlockRateLimiter(rate, now = () => performance.now()) {
     if (!(rate.perSecond > 0) || !(rate.burst >= 1)) {
         throw new Error('Slotlock rate limiter needs a positive rate and a burst of at least 1');
     }
-    const buckets = bucketsFor(rate, now);
+    const buckets = bucketsFor(rate);
     return {
         take(key) {
             const bucket = buckets.get(key, now());
@@ -412,15 +433,31 @@ function slotsFor(operation, input) {
 /** The limits `slotlock serve` puts in front of its agent server and dashboard. */
 export function createSlotlockRequestLimits(options) {
     const now = options.now ?? (() => performance.now());
+    const clock = options.clock ?? Date.now;
     const { rates, caps } = options.limits;
     const policies = new Map();
     for (const [name, rate] of Object.entries(rates)) {
         if (rate !== null)
-            policies.set(name, { policy: { name, rate }, buckets: bucketsFor(rate, now) });
+            policies.set(name, { policy: { name, rate }, buckets: bucketsFor(rate) });
     }
+    // Keys' own rates (RFC 0004 A5), one set of buckets for each rate in use; a key's bucket is keyed
+    // by key and rate, so a changed rate starts a fresh bucket.
+    const keyLimits = new Map();
+    const keyLimitEntry = (perMinute) => {
+        let entry = keyLimits.get(perMinute);
+        if (!entry) {
+            if (keyLimits.size >= MAX_KEY_LIMIT_RATES)
+                keyLimits.delete(keyLimits.keys().next().value);
+            const rate = { perSecond: perMinute / 60, burst: perMinute };
+            entry = { policy: { name: 'key_limit', rate }, buckets: bucketsFor(rate) };
+            keyLimits.set(perMinute, entry);
+        }
+        return entry;
+    };
     const states = new AsyncLocalStorage();
     const looked = new WeakMap();
     const addresses = new WeakMap();
+    const proxySecretDigest = options.trustedProxySecret === undefined ? undefined : sha256(options.trustedProxySecret);
     const gates = {
         series: {
             gate: seriesGate(caps.tenant_series_writes, caps.series_writes),
@@ -452,6 +489,7 @@ export function createSlotlockRequestLimits(options) {
             series_writes_busy: 0,
             maintenance_busy: 0,
             request_too_large: 0,
+            quota_exceeded: 0,
         };
     }
     const count = (reason, address) => {
@@ -492,8 +530,8 @@ export function createSlotlockRequestLimits(options) {
      */
     function charge(checks) {
         const at = now();
-        const found = checks.flatMap(({ name, key }) => {
-            const entry = policies.get(name);
+        const found = checks.flatMap(({ name, key, entry: given }) => {
+            const entry = given ?? policies.get(name);
             return entry ? [{ policy: entry.policy, bucket: entry.buckets.get(key, at) }] : [];
         });
         if (found.length === 0)
@@ -535,15 +573,21 @@ export function createSlotlockRequestLimits(options) {
         const keyOf = `${principal.tenantRef}\0${principal.subject}`;
         const application = state.application &&
             (principal.scopes === undefined || principal.scopes.includes(SLOTLOCK_APPLICATION_SCOPE));
-        const checks = due.flatMap((kind) => [
-            ...(application
-                ? [{ name: `app_${kind}`, key: principal.tenantRef }]
-                : [
-                    { name: `key_${kind}`, key: keyOf },
-                    { name: `tenant_${kind}`, key: principal.tenantRef },
-                ]),
-            { name: `global_${kind}`, key: '' },
-        ]);
+        // A key's own rate (RFC 0004 A5): a minute's requests, reads and writes alike, as a bucket of
+        // its own beside the server's, so it only ever lowers what the key may do.
+        const own = principal.limits?.requestsPerMinute;
+        const keyLimit = own !== undefined && Number.isSafeInteger(own) && own >= 1 && !state.chargedKeyLimit
+            ? [{ name: 'key_limit', key: `${keyOf}\0${own}`, entry: keyLimitEntry(own) }]
+            : [];
+        const checks = [...keyLimit, ...due.flatMap((kind) => [
+                ...(application
+                    ? [{ name: `app_${kind}`, key: principal.tenantRef }]
+                    : [
+                        { name: `key_${kind}`, key: keyOf },
+                        { name: `tenant_${kind}`, key: principal.tenantRef },
+                    ]),
+                { name: `global_${kind}`, key: '' },
+            ])];
         const outcome = charge(checks);
         if (!outcome.ok) {
             state.refusal = {
@@ -577,6 +621,8 @@ export function createSlotlockRequestLimits(options) {
         }
         for (const kind of due)
             state.charged[kind] = true;
+        if (keyLimit.length > 0)
+            state.chargedKeyLimit = true;
         if (outcome.verdict)
             state.tightest = outcome.verdict;
         return true;
@@ -612,17 +658,18 @@ export function createSlotlockRequestLimits(options) {
                 return looked.get(request) ?? null;
             return options.authenticate(request);
         },
-        async consumeRateLimit({ principal, operation }) {
+        async consumeRateLimit({ principal, operation, dryRun }) {
             const state = states.getStore();
             if (!state)
                 return true;
             const classes = [];
             if (operation === 'protocol') {
                 classes.push('read');
-                if (state.write)
+                if (state.write && dryRun !== true)
                     classes.push('write');
             }
-            else if (slotlockAgentOperationScope(operation) === 'write') {
+            else if (slotlockAgentOperationScope(operation) === 'write' && dryRun !== true) {
+                // A dry run writes nothing: the request's read token is its charge (RFC 0004 A3).
                 classes.push('write');
             }
             return chargeRequest(state, principal, classes);
@@ -661,11 +708,38 @@ export function createSlotlockRequestLimits(options) {
             };
             throw new SlotlockAgentOperationError('server_busy', 503);
         },
+        async quota({ principal, operation }) {
+            if (!options.quotas)
+                return;
+            const state = states.getStore();
+            const verdict = await options.quotas.check({ tenantRef: principal.tenantRef, operation });
+            const at = clock();
+            if (verdict.ok) {
+                if (state && verdict.standings.length > 0) {
+                    const { rateLimit, policy } = slotlockQuotaFields(verdict.standings, at);
+                    state.quota = { rateLimit, policy };
+                }
+                return;
+            }
+            const { exceeded } = verdict;
+            const { rateLimit, policy, retryAfter } = slotlockQuotaFields([exceeded], at);
+            if (state) {
+                state.refusal = {
+                    reason: 'quota_exceeded',
+                    fields: {
+                        'Retry-After': String(retryAfter),
+                        RateLimit: rateLimit.join(', '),
+                        'RateLimit-Policy': policy.join(', '),
+                    },
+                };
+            }
+            throw slotlockQuotaRefusal(exceeded);
+        },
         serve(target) {
             const limited = {
                 async fetch(request, connection) {
                     const route = routeOf(request);
-                    const address = clientOf(request, connection, options.trustedProxyHeader);
+                    const address = clientOf(request, connection, options.trustedProxyHeader, proxySecretDigest);
                     addresses.set(request, address);
                     if (options.trustedProxyHeader === undefined && !fieldIgnored) {
                         const field = PROXY_CLIENT_FIELDS.find((name) => request.headers.has(name));
@@ -729,10 +803,19 @@ export function createSlotlockRequestLimits(options) {
                         count('request_too_large', address);
                     if (state.refusal)
                         count(state.refusal.reason, address);
-                    const fields = state.refusal?.fields ??
+                    let fields = state.refusal?.fields ??
                         (state.tightest && (route === 'mcp' || route === 'a2a' || route === 'rest')
                             ? fieldsOf(state.tightest, false)
                             : undefined);
+                    // The tenant's monthly quotas follow the bucket the answer reports, when nothing refused.
+                    if (state.quota && !state.refusal) {
+                        const join = (first, rest) => [...(first ? [first] : []), ...rest].join(', ');
+                        fields = {
+                            ...fields,
+                            RateLimit: join(fields?.RateLimit, state.quota.rateLimit),
+                            'RateLimit-Policy': join(fields?.['RateLimit-Policy'], state.quota.policy),
+                        };
+                    }
                     if (!fields)
                         return response;
                     // A response's own headers may be immutable (Response.redirect): answer with a copy.

package/resource-profile.d.ts

@@ -0,0 +1,135 @@
+/** What a resource is, as a hint for filtering and display; `other` when not said. */
+export declare const SLOTLOCK_RESOURCE_KINDS: readonly ["person", "room", "desk", "space", "vehicle", "machine", "equipment", "service", "other"];
+export type SlotlockResourceKind = (typeof SLOTLOCK_RESOURCE_KINDS)[number];
+/** The profile's bounds, which the database also holds (ddl.ts). */
+export declare const SLOTLOCK_RESOURCE_PROFILE_LIMITS: Readonly<{
+    /** Characters in a name. */
+    name: 200;
+    /** Characters in a description. */
+    description: 2000;
+    /** The most people or seats a resource is said to hold. */
+    capacity: 100000;
+    /** Labels on one resource. */
+    labels: 20;
+    /** Keys in its attributes. */
+    attributes: 50;
+    /** Characters in an attribute's key. */
+    attributeKey: 64;
+    /** Characters in an attribute's text value. */
+    attributeValue: 1000;
+    /** Bytes of its attributes as compact JSON. */
+    attributeBytes: 4096;
+}>;
+/** A label: lower case letters, digits, `.`, `_` and `-`, starting with a letter or digit, 1-64. */
+export declare const SLOTLOCK_RESOURCE_LABEL: RegExp;
+/** What an integrator keeps on a resource and wants back: text, numbers and true or false. */
+export type SlotlockResourceAttributes = Record<string, string | number | boolean>;
+/**
+ * A resource's profile as it is set: a field left out is kept as it is. `null` clears a name, a
+ * description or a capacity; `labels: []` and `attributes: {}` clear those, and `kind: 'other'`
+ * says nothing about what it is.
+ */
+export interface SlotlockResourceProfileInput {
+    name?: string | null;
+    description?: string | null;
+    kind?: SlotlockResourceKind;
+    capacity?: number | null;
+    labels?: readonly string[];
+    attributes?: Readonly<SlotlockResourceAttributes>;
+}
+/** A profile input that passed its checks: names trimmed, labels sorted without repeats. */
+export interface SlotlockResourceProfileChange {
+    name?: string | null;
+    description?: string | null;
+    kind?: SlotlockResourceKind;
+    capacity?: number | null;
+    labels?: string[];
+    attributes?: SlotlockResourceAttributes;
+}
+/** The profile fields, as the feed and the API name them. */
+export declare const SLOTLOCK_RESOURCE_PROFILE_FIELDS: readonly ["name", "description", "kind", "capacity", "labels", "attributes"];
+/**
+ * Check a profile change and put it in the form it is stored in: refused with
+ * `invalid_resource_profile`, naming the field, when a field is outside its bounds.
+ */
+export declare function parseSlotlockResourceProfile(input: SlotlockResourceProfileInput): SlotlockResourceProfileChange;
+/** Whether a resource's labels include every one of `wanted`. */
+export declare function slotlockResourceHasLabels(labels: readonly string[] | undefined, wanted: readonly string[]): boolean;
+/** Locations a tenant may have. */
+export declare const SLOTLOCK_MAX_LOCATIONS = 1000;
+/** Levels a location tree may have: a region, a site, a building, a floor, a zone. */
+export declare const SLOTLOCK_MAX_LOCATION_DEPTH = 5;
+/** Groups a tenant may have. */
+export declare const SLOTLOCK_MAX_RESOURCE_GROUPS = 500;
+/** Groups one resource may be in. */
+export declare const SLOTLOCK_MAX_GROUPS_PER_RESOURCE = 20;
+/** A location's or a group's reference, as a pool's: 1-100 of a-z, 0-9, `.`, `_` and `-`. */
+export declare const SLOTLOCK_GROUPING_REF: RegExp;
+/** A place a tenant's resources are at. */
+export interface SlotlockLocation {
+    ref: string;
+    name: string;
+    /** The location it is in; null at the top. */
+    parentRef: string | null;
+    /** The time zone a resource created here without its own takes; null to take its parent's. */
+    timezone: string | null;
+    /** How many resources are at it (not counting those below it). */
+    resources: number;
+}
+/** A set of a tenant's resources. */
+export interface SlotlockResourceGroup {
+    ref: string;
+    name: string;
+    description: string | null;
+    /** How many resources are in it. */
+    members: number;
+}
+/** Check a location as it is to be stored: refused with `invalid_location`, naming the field. */
+export declare function parseSlotlockLocation(input: {
+    ref: string;
+    name?: string;
+    parentRef?: string | null;
+    timezone?: string | null;
+}): {
+    ref: string;
+    name?: string;
+    parentRef?: string | null;
+    timezone?: string | null;
+};
+/** Check a group as it is to be stored: refused with `invalid_group`, naming the field. */
+export declare function parseSlotlockResourceGroup(input: {
+    ref: string;
+    name: string;
+    description?: string | null;
+}): {
+    ref: string;
+    name: string;
+    description: string | null;
+};
+/** Check a location or group reference given to find one: refused as its own kind's. */
+export declare function slotlockGroupingRef(code: 'invalid_location' | 'invalid_group', value: unknown): string;
+/**
+ * The order a pool booking tries a pool's members in (RFC 0003 G7): `stable`, by id (the default);
+ * `least_booked`, fewest bookings made on each in the last 30 days first, to share them out;
+ * `round_robin`, from the member after the one booked last.
+ */
+export declare const SLOTLOCK_POOL_ORDERS: readonly ["stable", "least_booked", "round_robin"];
+/** Pools a tenant may set an order for (`pool_order_limit_reached` for one more). */
+export declare const SLOTLOCK_MAX_POOL_SETTINGS = 1000;
+/** The parts a composite resource may have (RFC 0003 G8): a hall of its rooms, a court of its halves. */
+export declare const SLOTLOCK_MAX_COMPOSITE_PARTS = 50;
+/**
+ * How far a partner's count of a day may differ from Slotlock's before it is a mismatch, in percent
+ * (RFC 0003 P5: a difference above 0.5% opens an incident on our side).
+ */
+export declare const SLOTLOCK_RECONCILE_TOLERANCE_PERCENT = 0.5;
+export type SlotlockPoolOrder = (typeof SLOTLOCK_POOL_ORDERS)[number];
+/** Locations, and groups, a key limited to part of its tenant may name (RFC 0003 G6), each. */
+export declare const SLOTLOCK_MAX_KEY_SCOPE_REFS = 20;
+/** A key limited to part of its tenant (RFC 0003 G6): the locations and groups it reaches. */
+export interface SlotlockResourceScope {
+    locations: readonly string[];
+    groups: readonly string[];
+}
+/** Whether `value` is a resource scope: location and group references, at least one, each list bounded. */
+export declare function isSlotlockResourceScope(value: unknown): value is SlotlockResourceScope;

package/resource-profile.js

@@ -0,0 +1,263 @@
+// A resource's profile (RFC 0003 G1): how people and agents tell resources apart and find them,
+// whatever they are (a person, a room, a vehicle, a machine). Every field is optional, and none
+// changes how a resource is booked: `kind` is a hint for filtering and `capacity` is informational,
+// as SPEC.md requires ("no semantic rule assumes a particular industry"). Names and descriptions are
+// calendar content: the feed says which profile fields changed, never their values.
+/** What a resource is, as a hint for filtering and display; `other` when not said. */
+export const SLOTLOCK_RESOURCE_KINDS = Object.freeze([
+    'person',
+    'room',
+    'desk',
+    'space',
+    'vehicle',
+    'machine',
+    'equipment',
+    'service',
+    'other',
+]);
+/** The profile's bounds, which the database also holds (ddl.ts). */
+export const SLOTLOCK_RESOURCE_PROFILE_LIMITS = Object.freeze({
+    /** Characters in a name. */
+    name: 200,
+    /** Characters in a description. */
+    description: 2_000,
+    /** The most people or seats a resource is said to hold. */
+    capacity: 100_000,
+    /** Labels on one resource. */
+    labels: 20,
+    /** Keys in its attributes. */
+    attributes: 50,
+    /** Characters in an attribute's key. */
+    attributeKey: 64,
+    /** Characters in an attribute's text value. */
+    attributeValue: 1_000,
+    /** Bytes of its attributes as compact JSON. */
+    attributeBytes: 4_096,
+});
+/** A label: lower case letters, digits, `.`, `_` and `-`, starting with a letter or digit, 1-64. */
+export const SLOTLOCK_RESOURCE_LABEL = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+/** The profile fields, as the feed and the API name them. */
+export const SLOTLOCK_RESOURCE_PROFILE_FIELDS = Object.freeze([
+    'name',
+    'description',
+    'kind',
+    'capacity',
+    'labels',
+    'attributes',
+]);
+function invalid(field, message) {
+    return Object.assign(new Error(`Slotlock resource ${field} ${message}`), {
+        code: 'invalid_resource_profile',
+        field,
+    });
+}
+// C0 and C1 control characters, which no name shows; a description may still break lines.
+const CONTROL = /[\u0000-\u001f\u007f-\u009f]/;
+const CONTROL_BUT_LINES = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/;
+/** Characters as PostgreSQL's char_length counts them: code points, not UTF-16 units. */
+const characters = (value) => [...value].length;
+function text(field, value, max, lines) {
+    if (value === null)
+        return null;
+    if (typeof value !== 'string')
+        throw invalid(field, 'must be text or null');
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        throw invalid(field, 'must not be empty: send null to clear it');
+    if (characters(trimmed) > max)
+        throw invalid(field, `must be at most ${max} characters`);
+    if ((lines ? CONTROL_BUT_LINES : CONTROL).test(trimmed)) {
+        throw invalid(field, 'must not contain control characters');
+    }
+    return trimmed;
+}
+/**
+ * Check a profile change and put it in the form it is stored in: refused with
+ * `invalid_resource_profile`, naming the field, when a field is outside its bounds.
+ */
+export function parseSlotlockResourceProfile(input) {
+    const limits = SLOTLOCK_RESOURCE_PROFILE_LIMITS;
+    const change = {};
+    if (input.name !== undefined)
+        change.name = text('name', input.name, limits.name, false);
+    if (input.description !== undefined) {
+        change.description = text('description', input.description, limits.description, true);
+    }
+    if (input.kind !== undefined) {
+        if (!SLOTLOCK_RESOURCE_KINDS.includes(input.kind)) {
+            throw invalid('kind', `must be one of ${SLOTLOCK_RESOURCE_KINDS.join(', ')}`);
+        }
+        change.kind = input.kind;
+    }
+    if (input.capacity !== undefined) {
+        if (input.capacity !== null &&
+            !(Number.isSafeInteger(input.capacity) && input.capacity >= 1 && input.capacity <= limits.capacity)) {
+            throw invalid('capacity', `must be a whole number from 1 to ${limits.capacity}, or null`);
+        }
+        change.capacity = input.capacity;
+    }
+    if (input.labels !== undefined) {
+        if (!Array.isArray(input.labels))
+            throw invalid('labels', 'must be a list');
+        const labels = [...new Set(input.labels)];
+        if (labels.length > limits.labels)
+            throw invalid('labels', `must be at most ${limits.labels}`);
+        for (const label of labels) {
+            if (typeof label !== 'string' || !SLOTLOCK_RESOURCE_LABEL.test(label)) {
+                throw invalid('labels', 'must each be 1-64 of a-z, 0-9, ".", "_" and "-", starting with a letter or digit');
+            }
+        }
+        change.labels = labels.sort();
+    }
+    if (input.attributes !== undefined) {
+        const given = input.attributes;
+        if (given === null || typeof given !== 'object' || Array.isArray(given)) {
+            throw invalid('attributes', 'must be an object');
+        }
+        const entries = Object.entries(given);
+        if (entries.length > limits.attributes) {
+            throw invalid('attributes', `must have at most ${limits.attributes} keys`);
+        }
+        const attributes = {};
+        for (const [key, value] of entries) {
+            if (key.length === 0 || characters(key) > limits.attributeKey || CONTROL.test(key)) {
+                throw invalid('attributes', `keys must be 1-${limits.attributeKey} characters without control characters`);
+            }
+            if (typeof value === 'string') {
+                if (characters(value) > limits.attributeValue) {
+                    throw invalid('attributes', `text values must be at most ${limits.attributeValue} characters`);
+                }
+            }
+            else if (typeof value === 'number') {
+                if (!Number.isFinite(value))
+                    throw invalid('attributes', 'numbers must be finite');
+            }
+            else if (typeof value !== 'boolean') {
+                throw invalid('attributes', 'values must be text, numbers, or true or false');
+            }
+            attributes[key] = value;
+        }
+        if (Buffer.byteLength(JSON.stringify(attributes), 'utf8') > limits.attributeBytes) {
+            throw invalid('attributes', `must be at most ${limits.attributeBytes} bytes as JSON`);
+        }
+        change.attributes = attributes;
+    }
+    return change;
+}
+/** Whether a resource's labels include every one of `wanted`. */
+export function slotlockResourceHasLabels(labels, wanted) {
+    return wanted.every((label) => labels?.includes(label) === true);
+}
+// Where a resource is, and the sets it is in (RFC 0003 G2, G3): a location is a place in a tree of
+// the tenant's own (one a resource), a group any set the tenant wants (many a resource). Neither
+// changes how a resource is booked; a pool does that.
+/** Locations a tenant may have. */
+export const SLOTLOCK_MAX_LOCATIONS = 1_000;
+/** Levels a location tree may have: a region, a site, a building, a floor, a zone. */
+export const SLOTLOCK_MAX_LOCATION_DEPTH = 5;
+/** Groups a tenant may have. */
+export const SLOTLOCK_MAX_RESOURCE_GROUPS = 500;
+/** Groups one resource may be in. */
+export const SLOTLOCK_MAX_GROUPS_PER_RESOURCE = 20;
+/** A location's or a group's reference, as a pool's: 1-100 of a-z, 0-9, `.`, `_` and `-`. */
+export const SLOTLOCK_GROUPING_REF = /^[a-z0-9][a-z0-9._-]{0,99}$/;
+function invalidGrouping(code, field, message) {
+    return Object.assign(new Error(`Slotlock ${code === 'invalid_location' ? 'location' : 'group'} ${field} ${message}`), {
+        code,
+        field,
+    });
+}
+function groupingRef(code, field, value) {
+    if (typeof value !== 'string' || !SLOTLOCK_GROUPING_REF.test(value)) {
+        throw invalidGrouping(code, field, 'must be 1-100 of a-z, 0-9, ".", "_" and "-", starting with a letter or digit');
+    }
+    return value;
+}
+function groupingName(code, value) {
+    try {
+        const name = text('name', value, SLOTLOCK_RESOURCE_PROFILE_LIMITS.name, false);
+        if (name === null)
+            throw invalid('name', 'must be given');
+        return name;
+    }
+    catch (error) {
+        throw invalidGrouping(code, 'name', error.message.replace(/^Slotlock resource name /, ''));
+    }
+}
+/** Check a location as it is to be stored: refused with `invalid_location`, naming the field. */
+export function parseSlotlockLocation(input) {
+    const location = {
+        ref: groupingRef('invalid_location', 'ref', input.ref),
+    };
+    if (input.name !== undefined)
+        location.name = groupingName('invalid_location', input.name);
+    if (input.parentRef !== undefined) {
+        location.parentRef = input.parentRef === null ? null : groupingRef('invalid_location', 'parent', input.parentRef);
+        if (location.parentRef === location.ref)
+            throw invalidGrouping('invalid_location', 'parent', 'must not be itself');
+    }
+    if (input.timezone !== undefined) {
+        if (input.timezone !== null) {
+            try {
+                if (typeof input.timezone !== 'string' || input.timezone.length > 100)
+                    throw new Error('no');
+                new Intl.DateTimeFormat('en-GB', { timeZone: input.timezone }).format(0);
+            }
+            catch {
+                throw invalidGrouping('invalid_location', 'timezone', 'must be an IANA time zone, or null');
+            }
+        }
+        location.timezone = input.timezone;
+    }
+    return location;
+}
+/** Check a group as it is to be stored: refused with `invalid_group`, naming the field. */
+export function parseSlotlockResourceGroup(input) {
+    let description = null;
+    if (input.description !== undefined && input.description !== null) {
+        try {
+            description = text('description', input.description, SLOTLOCK_RESOURCE_PROFILE_LIMITS.description, true);
+        }
+        catch (error) {
+            throw invalidGrouping('invalid_group', 'description', error.message.replace(/^Slotlock resource description /, ''));
+        }
+    }
+    return {
+        ref: groupingRef('invalid_group', 'ref', input.ref),
+        name: groupingName('invalid_group', input.name),
+        description,
+    };
+}
+/** Check a location or group reference given to find one: refused as its own kind's. */
+export function slotlockGroupingRef(code, value) {
+    return groupingRef(code, 'ref', value);
+}
+/**
+ * The order a pool booking tries a pool's members in (RFC 0003 G7): `stable`, by id (the default);
+ * `least_booked`, fewest bookings made on each in the last 30 days first, to share them out;
+ * `round_robin`, from the member after the one booked last.
+ */
+export const SLOTLOCK_POOL_ORDERS = Object.freeze(['stable', 'least_booked', 'round_robin']);
+/** Pools a tenant may set an order for (`pool_order_limit_reached` for one more). */
+export const SLOTLOCK_MAX_POOL_SETTINGS = 1_000;
+/** The parts a composite resource may have (RFC 0003 G8): a hall of its rooms, a court of its halves. */
+export const SLOTLOCK_MAX_COMPOSITE_PARTS = 50;
+/**
+ * How far a partner's count of a day may differ from Slotlock's before it is a mismatch, in percent
+ * (RFC 0003 P5: a difference above 0.5% opens an incident on our side).
+ */
+export const SLOTLOCK_RECONCILE_TOLERANCE_PERCENT = 0.5;
+/** Locations, and groups, a key limited to part of its tenant may name (RFC 0003 G6), each. */
+export const SLOTLOCK_MAX_KEY_SCOPE_REFS = 20;
+/** Whether `value` is a resource scope: location and group references, at least one, each list bounded. */
+export function isSlotlockResourceScope(value) {
+    const scope = value;
+    const refs = (list) => Array.isArray(list) &&
+        list.length <= SLOTLOCK_MAX_KEY_SCOPE_REFS &&
+        list.every((ref) => typeof ref === 'string' && SLOTLOCK_GROUPING_REF.test(ref));
+    return (typeof scope === 'object' &&
+        scope !== null &&
+        refs(scope.locations) &&
+        refs(scope.groups) &&
+        scope.locations.length + scope.groups.length > 0);
+}