@limitry/sdk 1.0.0-rc.7 → 1.0.0-rc.9

package/CHANGELOG.md

@@ -2,6 +2,128 @@
 
 What changed in the Limitry TypeScript SDK (`@limitry/sdk`). Generated from the source on each release; newest first.
 
+## 1.0.0-rc.9 (2026-10-22)
+
+### Added
+
+- `POST /v1/checks` can now answer `503` with the code `busy` when
+  Limitry is deciding too many checks for those subjects at once. Nothing
+  was charged. `guard` and `reserve` (TypeScript and Python) send the
+  check again with the same key, within the same 30 seconds they give
+  `moving`, before the limit's fail mode decides. Each retry of `busy` or
+  `moving` now waits the answer's `Retry-After` plus a random backoff that
+  grows with each try, so clients don't all come back at the same moment.
+  Older SDK versions treat `busy` as Limitry being unreachable after their
+  usual two quick retries, so the fail mode decides; upgrade to retry it.
+
+### Changed
+
+- A very busy workspace's counts are now spread over more of Limitry's
+  servers as its traffic grows. While some of them move, which takes a few
+  seconds, checks, commits and releases on those subjects answer `503`
+  with the new error code `moving` and `Retry-After: 1`; nothing is
+  counted. `guard` and `reserve` (TypeScript and Python) and the CLI send
+  the same request again with the same Idempotency-Key for up to 30
+  seconds, each try with its own time budget, before a limit's fail mode
+  applies, so work is neither run uncounted nor left uncommitted.
+- When `guard` gets no answer to its check in time and the limit fails
+  open (so your work runs), it now sends the same check once more in the
+  background, with the same Idempotency-Key and the header
+  `limitry-finish-only: 1`: Limitry finishes a check it was part way
+  through, and never decides one afresh, so a check that never arrived
+  charges nothing. A limit that fails closed sends nothing more.
+
+  `POST /v1/checks` answers `204` (no body) to such a resend when there was
+  nothing to finish, so `checks.create` is typed to allow no decision; a
+  check sent without `limitry-finish-only` always gets one.
+
+### Fixed
+
+- A reservation (`mode: "reserve"`) now starts a subject's period, as a
+  plain check does: on a `billing_date` limit with no billing date set
+  yet, the first reservation's time becomes the subject's billing date,
+  and on a `first_use` limit it starts the period. Before, reservations
+  made before the subject's first commit could each count in a period of
+  their own, so a monthly limit could let more through than its amount.
+  A reservation you release still starts the period, with nothing used in
+  it.
+- A `503 moving` answer with `Retry-After: 0` is now retried after at least
+  a second, not at once, and still for at most 30 seconds. A client made
+  with `maxRetries: 0` no longer sends the SDK's internal
+  `x-limitry-moving` header to the API.
+
+## 1.0.0-rc.8 (2026-10-21)
+
+### Added
+
+- Limits have `counting`: `fast` answers the instant it decides, and
+  `guaranteed` stores every count safely before answering, so the limit
+  never goes over, even if a server fails. A `total` balance defaults to
+  `guaranteed`, every other window to `fast`. Set it when creating or
+  updating a limit (`counting`, `--counting`), or in `limitry.json`.
+
+### Changed
+
+- - Creating a limit needs only who it is for, the amount and the window:
+    `limits.create({ subject: { kind: "user" }, amount: 100, window: "month" })`
+    (`limitry limits create --subject '{"kind":"user"}' --amount 100 --window month`).
+    `action` defaults to every action (`*`), `unit` to `units`, and `name`
+    to the sentence the limit reads as, such as "100 units per user per
+    month". If a limit already has that name, the API answers `409`: give
+    this one a `name`. `limitry.json` entries still need a `name`.
+  - A limit's input names who it is for as `subject: { kind, id }` (was
+    `subjectKind` and `subjectId`), the same shape the limit itself has.
+  - What a limit counts is fixed once it is created: its subject, action,
+    unit, window, `every`, `start` and `rolling`. Changing one answers
+    `400 invalid_request`: create a new limit and archive the old one (its
+    history stays). Name, amount, fail mode and enabled still change any
+    time. `limitry sync` refuses such a change until you rename the entry.
+  - A limit says when a check last reached it (`lastCheckedAt`), so you can
+    see a limit no check names.
+- One name for each idea, everywhere: the API, both SDKs, the CLI, the MCP
+  tools, `limitry.json` and webhooks. Update your code when you upgrade:
+
+  - `hold()` is `reserve()`: it takes `cost` (was `estimate`), and the block
+    gets a `Reservation` (was `Held`; Python `Reservation` and
+    `AsyncReservation`), with the same `cost()` and `extend()`.
+  - A refusal throws `LimitReached` (was `LimitExceeded`), with `limitId`
+    (Python `limit_id`) and `reason` `limit_reached` or
+    `too_many_reservations`. When Limitry can't be reached and a limit fails
+    closed, you now get a separate `Unavailable` error. "Can't be reached"
+    also covers a `402 plan_limit_reached` and a `429` from Limitry's flood
+    guard, so each limit's fail mode decides instead of your code getting an
+    error.
+  - A check's answer lists its limits in `limits` (was `remaining`): read
+    `decision.limits[0].remaining`. Every answer that names a limit says
+    `limitId`: `reason.limitId`, `limits[].limitId`, `usage.standing`'s
+    `limits[].limitId`, and webhook payloads.
+  - The refusal code is `limit_reached` (was `limit_exceeded`), and the
+    webhook event is `limit.reached` (was `limit.exceeded`): subscribe your
+    endpoints to the new name.
+  - Usage says `refused` (was `denied`); `usage.subjects` no longer has
+    `over` (it is `refused > 0`).
+  - Credits: `limits.credits.create()` and `limits.credits.list()` at
+    `/v1/limits/{limitId}/credits` (were `limits.grants.*` at `…/grants`),
+    ids start `crd_` (were `grt_`), and the approval an agent asks for is
+    `limit.credit` (was `limit.grant`).
+  - A period that starts on the subject's billing date is
+    `start: "billing_date"` (was `"anchor"`), and `subjects.update()` takes
+    `billingDate` (was `anchor`); the subject says `billingDate` too.
+  - `usage.standing()` and `usage.query()` take one `subject`, written
+    `kind:id` (`user:usr_123`), instead of separate kind and id fields
+    (`limitry usage standing --subject user:usr_123`).
+  - A limit's id starts `lmt_` (was `lim_`); keys still start `lim_test_`
+    and `lim_live_`.
+  - `limitry sync --preview` (was `--dry-run`), and the API's `preview`
+    (was `dryRun`), in what you send and what comes back.
+
+### Removed
+
+- Limits no longer have `counting` (Fast or Guaranteed), and the CLI no
+  longer has `--counting`: every count is now saved before Limitry answers,
+  for every limit. Remove `counting` from your code and from
+  `limitry.json`; Limitry ignores it.
+
 ## 1.0.0-rc.7 (2026-10-19)
 
 ### Added

package/README.md

@@ -1,6 +1,6 @@
 # @limitry/sdk
 
-The Limitry TypeScript SDK puts a limit around costly work in one call: `guard` checks before your code runs, and `hold` reserves an estimate, then charges what the work actually cost. Every API operation is a typed method too.
+The Limitry TypeScript SDK puts a limit around costly work in one call: `guard` checks before your code runs, and `reserve` reserves what the work will probably cost, then charges what it actually cost. Every API operation is a typed method too.
 
 Limitry is the limits, credits and budgets layer for your software: give each of your users, teams, tenants, API keys or agents an allowance, and before any costly action one call tells your code whether it may happen.
 
@@ -19,7 +19,7 @@ key (`lim_test_…`) while you build.
 it counts one AI call against a limit such as 100 a day:
 
 ```ts
-import { createClient, LimitExceeded } from "@limitry/sdk";
+import { createClient, LimitReached } from "@limitry/sdk";
 
 const limitry = createClient(); // reads LIMITRY_API_KEY
 
@@ -29,7 +29,7 @@ try {
     () => callModel(prompt),
   );
 } catch (error) {
-  if (error instanceof LimitExceeded) {
+  if (error instanceof LimitReached) {
     console.log(`Try again in ${error.retryAfterSeconds} seconds`);
   }
 }
@@ -38,26 +38,28 @@ try {
 ## Charge what it actually cost
 
 When you only know the cost afterwards, such as an AI reply priced by
-the token, `hold` reserves an estimate (5 cents here), runs your code
-and charges what it used. If your code throws, the hold is released:
+the token, `reserve` reserves what it will probably cost (5 cents here),
+runs your code and charges what it used. If your code throws, the
+reservation is released:
 
 ```ts
 import { createClient } from "@limitry/sdk";
 
 const limitry = createClient();
 
-const answer = await limitry.hold(
-  { subject: { kind: "user", id: "usr_123" }, action: "ai-call", estimate: 5 },
-  async (held) => {
+const answer = await limitry.reserve(
+  { subject: { kind: "user", id: "usr_123" }, action: "ai-call", cost: 5 },
+  async (reservation) => {
     const response = await callModel(prompt);
-    held.cost(priceCents(response.usage)); // your prices, in cents
+    reservation.cost(priceCents(response.usage)); // your prices, in cents
     return response;
   },
 );
 ```
 
-If Limitry can't be reached, each limit's fail mode decides: `open` lets
-the work run, `closed` refuses it.
+A refusal throws `LimitReached`. If Limitry can't be reached, each
+limit's fail mode decides: `open` lets the work run, `closed` throws
+`Unavailable`.
 
 ## Everything else
 
@@ -69,9 +71,9 @@ import { createClient } from "@limitry/sdk";
 
 const limitry = createClient();
 
+// "100 units per user per day for ai-call"
 await limitry.limits.create({
-  name: "AI replies per day",
-  subjectKind: "user",
+  subject: { kind: "user" },
   action: "ai-call",
   amount: 100,
   window: "day",

package/dist/index.d.ts

@@ -76,18 +76,18 @@ declare function createBaseClient(options: ClientOptions): import("openapi-fetch
         create: (input: import("./resources.ts").Input<"/checks", "post">, options?: import("./resources.ts").RequestOptions) => Promise<{
             allowed: boolean;
             id: string;
+            limits: components["schemas"]["CheckLimit"][];
             reason: {
-                code: "limit_exceeded" | "too_many_reservations";
-                limit: string | null;
+                code: "limit_reached" | "too_many_reservations";
+                limitId: string | null;
                 message: string;
             } | null;
-            remaining: components["schemas"]["CheckRemaining"][];
             reservation?: {
                 expiresAt: string;
                 id: string;
             };
             retryAfterSeconds: number | null;
-        }>;
+        } | undefined>;
     };
     limits: {
         archive: (limitId: string | number, options?: import("./resources.ts").RequestOptions) => Promise<undefined>;
@@ -100,15 +100,33 @@ declare function createBaseClient(options: ClientOptions): import("openapi-fetch
             every: number;
             failMode: "open" | "closed";
             id: string;
+            lastCheckedAt: string | null;
             name: string;
             rolling: boolean;
-            start: "calendar" | "anchor" | "first_use";
+            start: "calendar" | "billing_date" | "first_use";
             subject: components["schemas"]["LimitSubject"];
             unit: string;
             updatedAt: string;
             version: number;
             window: "minute" | "hour" | "day" | "week" | "month" | "year" | "total" | "concurrent";
         }>;
+        credits: {
+            create: (limitId: string | number, input: import("./resources.ts").Input<"/limits/{limitId}/credits", "post">, options?: import("./resources.ts").RequestOptions) => Promise<{
+                amount: number;
+                createdAt: string;
+                createdByUserId: string | null;
+                id: string;
+                limitId: string;
+                note: string;
+                subject: {
+                    id: string;
+                    kind: string;
+                };
+            }>;
+            list: (limitId: string | number, options?: import("./resources.ts").RequestOptions) => Promise<{
+                items: components["schemas"]["Credit"][];
+            }>;
+        };
         get: (limitId: string | number, options?: import("./resources.ts").RequestOptions) => Promise<{
             action: string;
             amount: number;
@@ -118,32 +136,16 @@ declare function createBaseClient(options: ClientOptions): import("openapi-fetch
             every: number;
             failMode: "open" | "closed";
             id: string;
+            lastCheckedAt: string | null;
             name: string;
             rolling: boolean;
-            start: "calendar" | "anchor" | "first_use";
+            start: "calendar" | "billing_date" | "first_use";
             subject: components["schemas"]["LimitSubject"];
             unit: string;
             updatedAt: string;
             version: number;
             window: "minute" | "hour" | "day" | "week" | "month" | "year" | "total" | "concurrent";
         }>;
-        grants: {
-            create: (limitId: string | number, input: import("./resources.ts").Input<"/limits/{limitId}/grants", "post">, options?: import("./resources.ts").RequestOptions) => Promise<{
-                amount: number;
-                createdAt: string;
-                createdByUserId: string | null;
-                id: string;
-                limitId: string;
-                note: string;
-                subject: {
-                    id: string;
-                    kind: string;
-                };
-            }>;
-            list: (limitId: string | number, options?: import("./resources.ts").RequestOptions) => Promise<{
-                items: components["schemas"]["LimitGrant"][];
-            }>;
-        };
         list: (input?: import("./resources.ts").Input<"/limits", "get">, options?: import("./resources.ts").RequestOptions) => Promise<{
             items: components["schemas"]["Limit"][];
             nextCursor: string | null;
@@ -157,9 +159,10 @@ declare function createBaseClient(options: ClientOptions): import("openapi-fetch
             every: number;
             failMode: "open" | "closed";
             id: string;
+            lastCheckedAt: string | null;
             name: string;
             rolling: boolean;
-            start: "calendar" | "anchor" | "first_use";
+            start: "calendar" | "billing_date" | "first_use";
             subject: components["schemas"]["LimitSubject"];
             unit: string;
             updatedAt: string;
@@ -169,7 +172,7 @@ declare function createBaseClient(options: ClientOptions): import("openapi-fetch
         sync: (input: import("./resources.ts").Input<"/limits/sync", "post">, options?: import("./resources.ts").RequestOptions) => Promise<{
             archived: string[];
             created: string[];
-            dryRun: boolean;
+            preview: boolean;
             unchanged: string[];
             updated: {
                 changes: {
@@ -190,9 +193,10 @@ declare function createBaseClient(options: ClientOptions): import("openapi-fetch
             every: number;
             failMode: "open" | "closed";
             id: string;
+            lastCheckedAt: string | null;
             name: string;
             rolling: boolean;
-            start: "calendar" | "anchor" | "first_use";
+            start: "calendar" | "billing_date" | "first_use";
             subject: components["schemas"]["LimitSubject"];
             unit: string;
             updatedAt: string;
@@ -225,7 +229,7 @@ declare function createBaseClient(options: ClientOptions): import("openapi-fetch
     };
     subjects: {
         get: (subjectKind: string | number, subjectId: string | number, options?: import("./resources.ts").RequestOptions) => Promise<{
-            anchor: string | null;
+            billingDate: string | null;
             subject: components["schemas"]["SubjectRef"];
         }>;
         reset: (subjectKind: string | number, subjectId: string | number, input?: import("./resources.ts").Input<"/subjects/{subjectKind}/{subjectId}/reset", "post">, options?: import("./resources.ts").RequestOptions) => Promise<{
@@ -233,7 +237,7 @@ declare function createBaseClient(options: ClientOptions): import("openapi-fetch
             subject: components["schemas"]["SubjectRef"];
         }>;
         update: (subjectKind: string | number, subjectId: string | number, input: import("./resources.ts").Input<"/subjects/{subjectKind}/{subjectId}", "patch">, options?: import("./resources.ts").RequestOptions) => Promise<{
-            anchor: string | null;
+            billingDate: string | null;
             subject: components["schemas"]["SubjectRef"];
         }>;
     };
@@ -243,7 +247,7 @@ declare function createBaseClient(options: ClientOptions): import("openapi-fetch
             limitId: string;
             points: {
                 allowed: number;
-                denied: number;
+                refused: number;
                 start: string;
                 used: number;
             }[];
@@ -253,7 +257,7 @@ declare function createBaseClient(options: ClientOptions): import("openapi-fetch
             limits: {
                 action: string;
                 amount: number;
-                limit: string;
+                limitId: string;
                 name: string;
                 remaining: number;
                 resetsAt: string | null;
@@ -274,8 +278,7 @@ declare function createBaseClient(options: ClientOptions): import("openapi-fetch
         }>;
         subjects: (input: import("./resources.ts").Input<"/usage/subjects", "get">, options?: import("./resources.ts").RequestOptions) => Promise<{
             items: {
-                denied: number;
-                over: boolean;
+                refused: number;
                 remaining: number;
                 subject: {
                     id: string;

package/dist/index.js

@@ -3,7 +3,7 @@ import createOpenApiClient from "openapi-fetch";
 import { apiErrorFrom } from "./errors.js";
 import * as product from "./product/index.js";
 import { resources } from "./resources.gen.js";
-import { withRetries } from "./retry.js";
+import { withoutMovingHeader, withRetries } from "./retry.js";
 import { verifyWebhook } from "./webhooks.js";
 export { ApiError, apiErrorFrom } from "./errors.js";
 export { verifyWebhook, WebhookVerificationError, } from "./webhooks.js";
@@ -35,7 +35,7 @@ function createBaseClient(options) {
     const client = createOpenApiClient({
         baseUrl: `${origin}/v1`,
         fetch: options.maxRetries === 0
-            ? send
+            ? withoutMovingHeader(send)
             : withRetries(send, { maxRetries: options.maxRetries }),
     });
     client.use({

package/dist/product/index.d.ts

@@ -1,16 +1,16 @@
 /**
  * PRODUCT-OWNED: Limitry's SDK helpers (fork-owned seam — docs/conventions.md
  * "Fork-owned seams"): re-exported by the SDK entry and published with
- * it. `guard` / `hold` (docs/product/roadmap.md slice 6) sit on the client
+ * it. `guard` / `reserve` (docs/product/roadmap.md slice 6) sit on the client
  * (`limitry.guard(…)`, the SDK's `productMethods` seam); `createLimits(client,
  * options)` gives them with your own timeout or fail mode.
  */
 import type { BaseClient } from "../index.ts";
-export { createLimits, LimitExceeded, type GuardRequest, type Held, type HoldRequest, type Limits, type LimitsOptions, } from "./limits.ts";
-/** Limitry's methods on the client: `limitry.guard(…)`, `limitry.hold(…)`, `limitry.standing(…)`. */
+export { createLimits, LimitReached, Unavailable, type GuardRequest, type Limits, type LimitsOptions, type Reservation, type ReserveRequest, } from "./limits.ts";
+/** Limitry's methods on the client: `limitry.guard(…)`, `limitry.reserve(…)`, `limitry.standing(…)`. */
 export declare const productMethods: (client: BaseClient) => {
     guard: <T>(request: import("./limits.ts").GuardRequest, fn: () => Promise<T>) => Promise<T>;
-    hold: <T>(request: import("./limits.ts").HoldRequest, fn: (held: import("./limits.ts").Held) => Promise<T>) => Promise<T>;
+    reserve: <T>(request: import("./limits.ts").ReserveRequest, fn: (reservation: import("./limits.ts").Reservation) => Promise<T>) => Promise<T>;
     standing: (request: {
         subject: {
             kind: string;

package/dist/product/index.js

@@ -1,7 +1,11 @@
 import { createLimits } from "./limits.js";
-export { createLimits, LimitExceeded, } from "./limits.js";
-/** Limitry's methods on the client: `limitry.guard(…)`, `limitry.hold(…)`, `limitry.standing(…)`. */
+export { createLimits, LimitReached, Unavailable, } from "./limits.js";
+/** Limitry's methods on the client: `limitry.guard(…)`, `limitry.reserve(…)`, `limitry.standing(…)`. */
 export const productMethods = (client) => {
     const limits = createLimits(client);
-    return { guard: limits.guard, hold: limits.hold, standing: limits.standing };
+    return {
+        guard: limits.guard,
+        reserve: limits.reserve,
+        standing: limits.standing,
+    };
 };

package/dist/product/limits.d.ts

@@ -13,33 +13,45 @@ import type { BaseClient, Schemas } from "../index.ts";
  *   );
  *
  *   // Cost known afterwards (an AI reply's cents), or "at most N at
- *   // once": hold an estimate, do the work, commit what it used —
- *   // released on failure.
- *   const answer = await limitry.hold(
- *     { subject: { kind: "user", id: user.id }, action: "ai-call", estimate: 5 },
- *     async (held) => {
+ *   // once": reserve what it will probably cost, do the work, commit
+ *   // what it used — released on failure.
+ *   const answer = await limitry.reserve(
+ *     { subject: { kind: "user", id: user.id }, action: "ai-call", cost: 5 },
+ *     async (reservation) => {
  *       const res = await callModel(prompt);
- *       held.cost(priceCents(res.usage));
+ *       reservation.cost(priceCents(res.usage));
  *       return res;
  *     },
  *   );
  *
- * A refusal throws `LimitExceeded` (with `retryAfterSeconds`). When
- * Limitry cannot be reached (an error, a 5xx, or no answer within
- * `timeoutMs`) — or the workspace is past its plan's allowance (402
- * `plan_limit_reached`) — each limit's fail mode decides: the last decision's
- * `failMode` for this subject and action is remembered in memory, and
- * `closed` refuses (`LimitExceeded` with reason `unavailable`) while
- * `open` — the default, and the answer before any decision was seen —
- * lets the work run unmetered.
+ * A refusal throws `LimitReached` (with `limitId` and
+ * `retryAfterSeconds`). When Limitry cannot be reached — an error, a 5xx,
+ * no answer within `timeoutMs`, the workspace past its plan's allowance
+ * (402 `plan_limit_reached`) or the edge's flood guard (429) — each
+ * limit's fail mode decides: the last decision's `failMode` for this
+ * subject and action is remembered in memory, and `closed` throws
+ * `Unavailable` while `open` — the default, and the answer before any
+ * decision was seen — lets the work run unmetered.
  *
- * Retries are safe (docs/product idempotency): each guard or hold sends
- * one Idempotency-Key, which the client's own retries reuse, so a check
- * counts once however often it is sent. A hold whose check timed out may
- * have been granted all the same: once the work is done, `hold` sends the
- * check again with the same key — a replay, nothing counted twice — and
- * releases the hold it finds, rather than leave it taken until it expires.
- * Commits and releases retry too (settling twice answers the same).
+ * A subject being handed over between Limitry's servers (a split, a few
+ * seconds) answers `503 moving`: Limitry was reached and charged nothing,
+ * so it is not "unreachable" — the check (or commit, or release) is sent
+ * again with the same key for up to 30 s, each attempt with its own
+ * `timeoutMs`, before the fail mode applies. A fail-open product never
+ * runs uncounted through a handover. A limiter with too many checks
+ * inside at once answers `503 busy` the same way (charged nothing; retry
+ * with the same key): both share those 30 s, and each wait is the
+ * answer's Retry-After plus full jitter on a growing backoff, so clients
+ * turned away together don't all come back together.
+ *
+ * Retries are safe (docs/product idempotency): each guard or reserve
+ * sends one Idempotency-Key, which the client's own retries reuse, so a
+ * check counts once however often it is sent. A reservation whose check
+ * timed out may have been made all the same: once the work is done,
+ * `reserve` sends the check again with the same key — a replay, nothing
+ * counted twice — and releases the reservation it finds, rather than
+ * leave it taken until it expires. Commits and releases retry too
+ * (committing or releasing twice answers the same).
  */
 type Decision = Schemas["CheckDecision"];
 type Subject = {
@@ -60,40 +72,55 @@ export type GuardRequest = {
     /** Pools it also draws from (a team's, an org's). */
     shared?: Subject[];
 };
-export type HoldRequest = {
+export type ReserveRequest = {
     subject: Subject;
     action: string;
-    /** What it will probably use — held until you commit the actual cost. Default 1. */
-    estimate?: number;
+    /** What it will probably use — reserved until you commit the actual cost. Default 1. */
+    cost?: number;
     shared?: Subject[];
-    /** How long the hold lasts if never settled (default 300, at most 3600). */
+    /** How long the reservation lasts if never committed or released (default 300, at most 3600). */
     ttlSeconds?: number;
 };
-export type Held = {
+export type Reservation = {
     /**
      * The cost actually used — committed when the work returns. Default: the
-     * estimate. A whole number from 0 to 1,000,000,000, as the API commits:
-     * anything else throws a RangeError here, in your code, rather than a
-     * commit the API refuses after the work (whose usage would go uncounted).
+     * reserved cost. A whole number from 0 to 1,000,000,000, as the API
+     * commits: anything else throws a RangeError here, in your code, rather
+     * than a commit the API refuses after the work (whose usage would go
+     * uncounted).
      */
     cost(units: number): void;
     /**
-     * Keep the hold for longer work: it expires `ttlSeconds` from now
-     * (default 300, 1 to 3600). Throws the API's error, such as for a hold
-     * that already expired.
+     * Keep the reservation for longer work: it expires `ttlSeconds` from now
+     * (default 300, 1 to 3600). Throws the API's error, such as for a
+     * reservation that already expired.
      */
     extend(ttlSeconds?: number): Promise<void>;
 };
-/** Not allowed: a limit is used up — or Limitry is unreachable and a limit fails closed. */
-export declare class LimitExceeded extends Error {
-    readonly reason: "limit_exceeded" | "too_many_reservations" | "unavailable";
-    /** The limit that refused; null when unavailable or too many holds. */
-    readonly limit: string | null;
+/** Refused: a limit is reached, or the subject holds too many open reservations. */
+export declare class LimitReached extends Error {
+    readonly reason: "limit_reached" | "too_many_reservations";
+    /** The limit that refused; null for too many open reservations. */
+    readonly limitId: string | null;
     readonly retryAfterSeconds: number | null;
-    readonly decision: Decision | null;
-    constructor(decision: Decision | null);
+    readonly decision: Decision;
+    constructor(decision: Decision);
+}
+/**
+ * Limitry could not be reached (an error, a 5xx, a timeout, the plan's
+ * allowance used up, or the flood guard's 429) and a limit on this
+ * subject and action fails closed. With `open`, the work runs instead.
+ */
+export declare class Unavailable extends Error {
+    constructor();
 }
-export declare function createLimits(client: BaseClient, options?: LimitsOptions): {
+export type LimitsInternals = {
+    /** Waits (tests pass a fake). */
+    sleep?: (ms: number) => Promise<void>;
+    /** 0 ≤ x < 1 for the jitter (tests pass a fixed one). */
+    random?: () => number;
+};
+export declare function createLimits(client: BaseClient, options?: LimitsOptions, internals?: LimitsInternals): {
     /**
      * Where a subject stands on every limit on it (and on `shared`
      * subjects): used, remaining, resetsAt — for showing an end user. Call
@@ -108,12 +135,12 @@ export declare function createLimits(client: BaseClient, options?: LimitsOptions
     /** Checks `cost`, runs `fn` only if allowed, and returns its result. */
     guard<T>(request: GuardRequest, fn: () => Promise<T>): Promise<T>;
     /**
-     * Holds `estimate`, runs `fn`, then commits the cost it reported
-     * (`held.cost(n)`, default the estimate) — or releases the hold if
-     * `fn` throws, and rethrows. A concurrent limit's slot is held for
-     * exactly as long as `fn` runs.
+     * Reserves `cost`, runs `fn`, then commits the cost it reported
+     * (`reservation.cost(n)`, default the reserved cost) — or releases the
+     * reservation if `fn` throws, and rethrows. A concurrent limit's slot
+     * is taken for exactly as long as `fn` runs.
      */
-    hold<T>(request: HoldRequest, fn: (held: Held) => Promise<T>): Promise<T>;
+    reserve<T>(request: ReserveRequest, fn: (reservation: Reservation) => Promise<T>): Promise<T>;
 };
 export type Limits = ReturnType<typeof createLimits>;
 export {};