slotlock 0.6.3 → 0.8.0

package/quotas.d.ts

@@ -0,0 +1,108 @@
+import { type SlotlockAgentOperation, SlotlockAgentOperationError } from './agent-server.js';
+import type { SlotlockApplicationOperation } from './application-api.js';
+import { SLOTLOCK_QUOTA_METRICS, SLOTLOCK_QUOTA_NOTICE_PERCENTS } from './ddl.js';
+import type { SlotlockPlanQuotas } from './plans.js';
+import type { SlotlockSql } from './store.js';
+import type { SlotlockRecordedUsageMetric } from './usage.js';
+export { SLOTLOCK_QUOTA_METRICS, SLOTLOCK_QUOTA_NOTICE_PERCENTS };
+export type SlotlockQuotaMetric = (typeof SLOTLOCK_QUOTA_METRICS)[number];
+/**
+ * The operations that can make a booking (a reservation, an event, a confirmed hold) or hold a slot
+ * for one: refused once the bookings quota is used up. Everything else, reads and cancellations
+ * included, runs until the operations quota is.
+ */
+export declare const SLOTLOCK_BOOKING_OPERATIONS: readonly (SlotlockAgentOperation | SlotlockApplicationOperation)[];
+/**
+ * Operations a quota never refuses, though each still counts: reading the month's usage, so a
+ * tenant can always see where it stands, and erasing the tenant, which no allowance may hold up.
+ */
+export declare const SLOTLOCK_QUOTA_EXEMPT_OPERATIONS: readonly SlotlockApplicationOperation[];
+/** A tenant's operations and bookings so far this month, as the database holds them. */
+export interface SlotlockQuotaUse {
+    operations: number;
+    bookings: number;
+}
+/** One quota of a tenant this month. */
+export interface SlotlockQuotaStanding {
+    metric: SlotlockQuotaMetric;
+    /** The plan's quota. */
+    quota: number;
+    /** Where use is refused: the quota, or past it on a plan that allows a margin (Developer 110%). */
+    stop: number;
+    used: number;
+    /** The month's first day, `YYYY-MM-DD` (UTC). */
+    periodStart: string;
+    /** When the month ends and the counts start again (the next month's first instant, UTC). */
+    resetsAt: Date;
+}
+export type SlotlockQuotaCheck = 
+/** `standings` is empty for a tenant with no plan, which no quota binds. */
+{
+    ok: true;
+    standings: SlotlockQuotaStanding[];
+} | {
+    ok: false;
+    exceeded: SlotlockQuotaStanding;
+    standings: SlotlockQuotaStanding[];
+};
+/** A share of a quota the tenant reached, to note once (slotlock.note_usage_threshold). */
+export interface SlotlockQuotaNotice {
+    tenantRef: string;
+    metric: SlotlockQuotaMetric;
+    percent: (typeof SLOTLOCK_QUOTA_NOTICE_PERCENTS)[number];
+    used: number;
+    quota: number;
+    /** The month's first day, `YYYY-MM-DD`. */
+    periodStart: string;
+}
+export interface SlotlockQuotasOptions {
+    /**
+     * The quotas the tenant's plan gives it (plans.ts readSlotlockTenantQuotas: a partner account's
+     * own, else its plan's), or null when it has none: then no quota binds it.
+     */
+    plan(tenantRef: string): Promise<SlotlockPlanQuotas | null>;
+    /** The tenant's operations and bookings from `fromDay` (`YYYY-MM-DD`) until now. */
+    used(tenantRef: string, fromDay: string): Promise<SlotlockQuotaUse>;
+    /**
+     * What this server counted and has not recorded yet (the usage meter's `local`). Without it, only
+     * what the database holds is counted.
+     */
+    local?(tenantRef: string, metric: SlotlockRecordedUsageMetric, fromDay: string): {
+        unrecorded: number;
+        counted: number;
+    };
+    /** Note a share reached; the database sends each once. Not awaited; a failure is tried again. */
+    notice?(notice: SlotlockQuotaNotice): Promise<unknown>;
+    /** A plan or count that could not be read (the check then lets the operation run), or a notice. */
+    onError?(error: unknown): void;
+    /** Milliseconds since the epoch, for tests; defaults to `Date.now`. */
+    now?: () => number;
+}
+export interface SlotlockQuotas {
+    /**
+     * Where the tenant stands against its quotas, and whether `operation` may run. Never throws: a
+     * plan or count it cannot read lets the operation run, on the last counts it read if any.
+     */
+    check(args: {
+        tenantRef: string;
+        operation: SlotlockAgentOperation | SlotlockApplicationOperation;
+    }): Promise<SlotlockQuotaCheck>;
+}
+/** The month an instant falls in: its first day and the next month's first instant, UTC. */
+export declare function slotlockQuotaPeriod(at: number): {
+    periodStart: string;
+    resetsAt: Date;
+};
+export declare function createSlotlockQuotas(options: SlotlockQuotasOptions): SlotlockQuotas;
+/** `slotlock.tenant_quota_usage`: the tenant's operations and bookings from `fromDay` until now. */
+export declare function readSlotlockQuotaUse(sql: SlotlockSql, tenantRef: string, fromDay: string): Promise<SlotlockQuotaUse>;
+/** `slotlock.note_usage_threshold`: true when this was the first notice of that share this month. */
+export declare function noteSlotlockQuotaThreshold(sql: SlotlockSql, notice: SlotlockQuotaNotice): Promise<boolean>;
+/** The refusal of an operation over a quota: `quota_exceeded` (429), naming the quota and its reset. */
+export declare function slotlockQuotaRefusal(exceeded: SlotlockQuotaStanding): SlotlockAgentOperationError;
+/** The answer's fields for a tenant's quotas: RateLimit list members, and Retry-After when refused. */
+export declare function slotlockQuotaFields(standings: readonly SlotlockQuotaStanding[], at: number): {
+    rateLimit: string[];
+    policy: string[];
+    retryAfter: number;
+};

package/quotas.js

@@ -0,0 +1,258 @@
+// Monthly quotas (RFC 0003 part 3): each hosted plan allows so many operations and bookings a UTC
+// calendar month (plans.ts SLOTLOCK_PLAN_QUOTAS). The server checks each operation against them as
+// it is authorized: past the operations quota every operation is refused, past the bookings quota
+// only those that can make a booking, so a tenant can still read and cancel. A refusal is
+// `quota_exceeded` (429) with Retry-After at the month's end (rate-limit.ts renders it), and at 80%
+// and 100% of each quota the tenant's feed records `usage.threshold_reached` once.
+//
+// What a check counts: the database's month so far (slotlock.tenant_quota_usage: the usage recorded,
+// and the bookings in the feed not yet rolled up), read at most every 30 seconds, and every 2 near
+// the stop; plus this server's operations the database does not hold yet (the usage meter's), and
+// the booking operations it ran since the read. Other servers' operations of the last 15 seconds or
+// so are not seen, so a busy tenant can go a little past its stop; never by more than that.
+// Off unless the deployment asks for it (SLOTLOCK_QUOTAS=on, with SLOTLOCK_USAGE=on).
+import { SlotlockAgentOperationError } from './agent-server.js';
+import { SLOTLOCK_QUOTA_METRICS, SLOTLOCK_QUOTA_NOTICE_PERCENTS } from './ddl.js';
+export { SLOTLOCK_QUOTA_METRICS, SLOTLOCK_QUOTA_NOTICE_PERCENTS };
+/**
+ * The operations that can make a booking (a reservation, an event, a confirmed hold) or hold a slot
+ * for one: refused once the bookings quota is used up. Everything else, reads and cancellations
+ * included, runs until the operations quota is.
+ */
+export const SLOTLOCK_BOOKING_OPERATIONS = Object.freeze([
+    'slotlock_hold_slots',
+    'slotlock_book_together',
+    'slotlock_book_pool',
+    'slotlock_create_event',
+    'slotlock_acquire_hold',
+    'slotlock_confirm_hold',
+    'slotlock_put_reservation',
+]);
+/**
+ * Operations a quota never refuses, though each still counts: reading the month's usage, so a
+ * tenant can always see where it stands, and erasing the tenant, which no allowance may hold up.
+ */
+export const SLOTLOCK_QUOTA_EXEMPT_OPERATIONS = Object.freeze([
+    'slotlock_get_usage',
+    'slotlock_erase_tenant',
+]);
+/** How long a tenant's plan and counts are trusted, and how long near its stop. */
+const REFRESH_MS = 30_000;
+const NEAR_STOP_REFRESH_MS = 2_000;
+/** The share of a stop past which counts are read again at NEAR_STOP_REFRESH_MS. */
+const NEAR_STOP = 0.9;
+/** Tenants one server remembers; past this the least recently checked tenth is dropped. */
+const MAX_TENANTS = 50_000;
+/** The month an instant falls in: its first day and the next month's first instant, UTC. */
+export function slotlockQuotaPeriod(at) {
+    const date = new Date(at);
+    const year = date.getUTCFullYear();
+    const month = date.getUTCMonth();
+    return {
+        periodStart: new Date(Date.UTC(year, month, 1)).toISOString().slice(0, 10),
+        resetsAt: new Date(Date.UTC(year, month + 1, 1)),
+    };
+}
+export function createSlotlockQuotas(options) {
+    const now = options.now ?? Date.now;
+    const entries = new Map();
+    const reading = new Map();
+    const noted = new Set();
+    const report = (error) => {
+        try {
+            options.onError?.(error);
+        }
+        catch {
+            // A reporter's failure changes nothing.
+        }
+    };
+    async function read(tenantRef, periodStart) {
+        const at = now();
+        const local = options.local?.(tenantRef, 'operations', periodStart) ?? { unrecorded: 0, counted: 0 };
+        try {
+            const plan = await options.plan(tenantRef);
+            const used = plan ? await options.used(tenantRef, periodStart) : { operations: 0, bookings: 0 };
+            const entry = {
+                plan,
+                periodStart,
+                at,
+                used: { operations: Number(used.operations) || 0, bookings: Number(used.bookings) || 0 },
+                unrecorded: local.unrecorded,
+                countedAtRead: local.counted,
+                bookingsSinceRead: 0,
+            };
+            if (!entries.has(tenantRef) && entries.size >= MAX_TENANTS) {
+                for (const key of [...entries.keys()].slice(0, Math.ceil(MAX_TENANTS / 10)))
+                    entries.delete(key);
+            }
+            entries.delete(tenantRef);
+            entries.set(tenantRef, entry);
+            return entry;
+        }
+        catch (error) {
+            report(error);
+            return null;
+        }
+    }
+    function standingsOf(tenantRef, entry, resetsAt) {
+        if (!entry.plan)
+            return [];
+        const quotas = entry.plan;
+        const local = options.local?.(tenantRef, 'operations', entry.periodStart);
+        // The read's unrecorded operations, and every one this meter counted since. A running total
+        // below the one at the read means the meter started its totals again: all of it is new.
+        const counted = local?.counted ?? entry.countedAtRead;
+        const operations = entry.used.operations + entry.unrecorded + (counted >= entry.countedAtRead ? counted - entry.countedAtRead : counted);
+        const bookings = entry.used.bookings + entry.bookingsSinceRead;
+        const standing = (metric, used) => ({
+            metric,
+            quota: quotas[metric],
+            stop: Math.floor((quotas[metric] * quotas.stopPercent) / 100),
+            used,
+            periodStart: entry.periodStart,
+            resetsAt,
+        });
+        return [standing('operations', operations), standing('bookings', bookings)];
+    }
+    function notify(tenantRef, standings) {
+        if (!options.notice)
+            return;
+        for (const standing of standings) {
+            for (const percent of SLOTLOCK_QUOTA_NOTICE_PERCENTS) {
+                if (standing.used * 100 < standing.quota * percent)
+                    continue;
+                const key = `${tenantRef}\0${standing.periodStart}\0${standing.metric}\0${percent}`;
+                if (noted.has(key))
+                    continue;
+                if (noted.size >= MAX_TENANTS)
+                    noted.clear();
+                noted.add(key);
+                try {
+                    options
+                        .notice({
+                        tenantRef,
+                        metric: standing.metric,
+                        percent,
+                        used: standing.used,
+                        quota: standing.quota,
+                        periodStart: standing.periodStart,
+                    })
+                        .catch((error) => {
+                        // Tried again at the next check that finds the share reached.
+                        noted.delete(key);
+                        report(error);
+                    });
+                }
+                catch (error) {
+                    noted.delete(key);
+                    report(error);
+                }
+            }
+        }
+    }
+    return {
+        async check({ tenantRef, operation }) {
+            const at = now();
+            const { periodStart, resetsAt } = slotlockQuotaPeriod(at);
+            let entry = entries.get(tenantRef);
+            const fresh = (found) => {
+                if (found.periodStart !== periodStart)
+                    return false;
+                const age = at - found.at;
+                if (age < 0 || age >= REFRESH_MS)
+                    return false;
+                if (age < NEAR_STOP_REFRESH_MS)
+                    return true;
+                // Near a stop, the counts are read again sooner: the estimate since the read is rougher.
+                return !standingsOf(tenantRef, found, resetsAt).some((standing) => standing.used >= standing.stop * NEAR_STOP);
+            };
+            if (!entry || !fresh(entry)) {
+                let pending = reading.get(tenantRef);
+                if (!pending) {
+                    pending = read(tenantRef, periodStart).finally(() => reading.delete(tenantRef));
+                    reading.set(tenantRef, pending);
+                }
+                const read_ = await pending;
+                // A read that failed keeps the last counts of this month, if any; else nothing binds.
+                if (read_)
+                    entry = read_;
+                else if (entry?.periodStart !== periodStart)
+                    return { ok: true, standings: [] };
+            }
+            if (!entry)
+                return { ok: true, standings: [] };
+            let standings = standingsOf(tenantRef, entry, resetsAt);
+            // Booking operations let run since the read are attempts, and some were refused or failed:
+            // before refusing one on that estimate, read the database's count again.
+            const booking = SLOTLOCK_BOOKING_OPERATIONS.includes(operation);
+            const bookingStanding = standings[1];
+            if (booking && entry.bookingsSinceRead > 0 && bookingStanding && bookingStanding.used >= bookingStanding.stop) {
+                let pending = reading.get(tenantRef);
+                if (!pending) {
+                    pending = read(tenantRef, periodStart).finally(() => reading.delete(tenantRef));
+                    reading.set(tenantRef, pending);
+                }
+                const again = await pending;
+                if (again) {
+                    entry = again;
+                    standings = standingsOf(tenantRef, entry, resetsAt);
+                }
+            }
+            const current = entry;
+            // Bookings are noticed as the database last counted them, never on the estimate since.
+            notify(tenantRef, standings.map((standing) => standing.metric === 'bookings' ? { ...standing, used: current.used.bookings } : standing));
+            if (SLOTLOCK_QUOTA_EXEMPT_OPERATIONS.includes(operation)) {
+                return { ok: true, standings };
+            }
+            const [operations, bookings] = standings;
+            if (operations && operations.used >= operations.stop) {
+                return { ok: false, exceeded: operations, standings };
+            }
+            if (booking && bookings && bookings.used >= bookings.stop) {
+                return { ok: false, exceeded: bookings, standings };
+            }
+            if (booking && current.plan)
+                current.bookingsSinceRead += 1;
+            return { ok: true, standings };
+        },
+    };
+}
+/** `slotlock.tenant_quota_usage`: the tenant's operations and bookings from `fromDay` until now. */
+export async function readSlotlockQuotaUse(sql, tenantRef, fromDay) {
+    const [row] = await sql `
+    SELECT operations, bookings FROM slotlock.tenant_quota_usage(${tenantRef}::text, ${fromDay}::date)`;
+    return { operations: Number(row?.operations ?? 0), bookings: Number(row?.bookings ?? 0) };
+}
+/** `slotlock.note_usage_threshold`: true when this was the first notice of that share this month. */
+export async function noteSlotlockQuotaThreshold(sql, notice) {
+    const [row] = await sql `
+    SELECT slotlock.note_usage_threshold(
+      ${notice.tenantRef}::text, ${notice.periodStart}::date, ${notice.metric}::text,
+      ${notice.percent}::integer, ${notice.used}::bigint, ${notice.quota}::bigint) AS noted`;
+    return row?.noted === true;
+}
+/** The refusal of an operation over a quota: `quota_exceeded` (429), naming the quota and its reset. */
+export function slotlockQuotaRefusal(exceeded) {
+    return new SlotlockAgentOperationError('quota_exceeded', 429, {
+        metric: exceeded.metric,
+        quota: String(exceeded.quota),
+        stop: String(exceeded.stop),
+        used: String(exceeded.used),
+        resets_at: exceeded.resetsAt.toISOString(),
+    });
+}
+/** The answer's fields for a tenant's quotas: RateLimit list members, and Retry-After when refused. */
+export function slotlockQuotaFields(standings, at) {
+    const rateLimit = [];
+    const policy = [];
+    let retryAfter = 1;
+    for (const standing of standings) {
+        const name = `${standing.metric}_month`;
+        const seconds = Math.max(1, Math.ceil((standing.resetsAt.getTime() - at) / 1_000));
+        const window = Math.round((standing.resetsAt.getTime() - Date.parse(`${standing.periodStart}T00:00:00Z`)) / 1_000);
+        rateLimit.push(`"${name}";r=${Math.max(0, standing.stop - standing.used)};t=${seconds}`);
+        policy.push(`"${name}";q=${standing.stop};w=${window}`);
+        retryAfter = Math.max(retryAfter, seconds);
+    }
+    return { rateLimit, policy, retryAfter };
+}

package/rate-limit.d.ts

@@ -2,7 +2,8 @@ import { type SlotlockAgentOperation, type SlotlockAgentPrincipal } from './agen
 import { type SlotlockApplicationOperation } from './application-api.js';
 import { type SlotlockLimits, type SlotlockRate } from './config.js';
 import type { SlotlockNodeServerFetchTarget } from './node-server.js';
-export type SlotlockRefusalReason = 'auth_refused' | 'rate_limited' | 'lookup_overflow' | 'series_writes_busy' | 'maintenance_busy' | 'request_too_large';
+import { type SlotlockQuotas } from './quotas.js';
+export type SlotlockRefusalReason = 'auth_refused' | 'rate_limited' | 'lookup_overflow' | 'series_writes_busy' | 'maintenance_busy' | 'request_too_large' | 'quota_exceeded';
 /** One `refusals` log line: counts since the last one, and the most refused clients as pseudonyms. */
 export interface SlotlockRefusalCounts extends Record<SlotlockRefusalReason, number> {
     window_seconds: number;
@@ -45,6 +46,14 @@ export interface SlotlockRequestLimitsOptions {
     shared?: {
         take(bucket: string, rate: SlotlockRate): Promise<boolean>;
     };
+    /**
+     * Monthly quotas (quotas.ts, SLOTLOCK_QUOTAS=on), checked by `quota`: an operation over its
+     * tenant's quota is refused `quota_exceeded` (429), with Retry-After at the month's end, and
+     * every operation's answer lists the tenant's quotas in its RateLimit fields.
+     */
+    quotas?: SlotlockQuotas;
+    /** Milliseconds since the epoch, for the quotas' reset; defaults to `Date.now`. */
+    clock?: () => number;
 }
 export interface SlotlockRequestLimits {
     /** The agent server's `authenticate`: the request's lookup from `fetch`, else a lookup now. */
@@ -53,6 +62,8 @@ export interface SlotlockRequestLimits {
     consumeRateLimit(args: {
         principal: SlotlockAgentPrincipal;
         operation: SlotlockAgentOperation | 'protocol';
+        /** A dry run of a write, charged as a read. */
+        dryRun?: boolean;
     }): Promise<boolean>;
     /**
      * For `authorize`: when the operation may expand a recurring series, or runs maintenance, take its
@@ -65,6 +76,15 @@ export interface SlotlockRequestLimits {
         operation: SlotlockAgentOperation | SlotlockApplicationOperation;
         input: Record<string, unknown>;
     }): Promise<void>;
+    /**
+     * For `authorize`: with `quotas`, refuse an operation over its tenant's monthly quota, throwing a
+     * `SlotlockAgentOperationError` (`quota_exceeded`, 429) that names the metric, the quota, the stop
+     * and when the month resets. Without `quotas`, or for a tenant on no plan, nothing.
+     */
+    quota(args: {
+        principal: SlotlockAgentPrincipal;
+        operation: SlotlockAgentOperation | SlotlockApplicationOperation;
+    }): Promise<void>;
     /** Put the limits in front of `target`: the listener's fetch target. */
     serve(target: SlotlockNodeServerFetchTarget): SlotlockNodeServerFetchTarget;
     /** The client address a request reaching `serve`'s target was counted as (the dashboard's). */

package/rate-limit.js

@@ -10,6 +10,9 @@
 // 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 { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
 import { isIP } from 'node:net';
@@ -17,6 +20,7 @@ import { SLOTLOCK_MCP_PROTOCOL_VERSION, SLOTLOCK_MCP_RATE_LIMITED_ERROR_CODE, Sl
 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;
@@ -47,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();
@@ -427,12 +433,27 @@ 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) });
     }
+    // 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();
@@ -468,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) => {
@@ -508,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)
@@ -551,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 = {
@@ -593,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;
@@ -628,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);
@@ -677,6 +708,33 @@ 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) {
@@ -745,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.