♻️ refactor(models): remove redundant burst field from Limit model (#408)

## Summary
- Remove the redundant `burst` field from `Limit` and `burst_milli` from
`BucketState` — `capacity` now serves as the bucket ceiling (max
tokens), which is what `burst` was actually doing in all bucket math
- Drop `bx` attribute from DynamoDB writes (bucket and config records);
read path uses `max(cp, bx)` fallback for backward compatibility with
existing records
- Update `refill_bucket()` parameter naming (`burst_milli` →
`capacity_milli`), aggregator processor, CLI display, exception
serialization, migration logic, examples, and all documentation
- Add inline period suffix support to CLI `-l` flag:
`name:rate[/period][:burst]` where period is `/[N]sec`, `/[N]min`
(default), `/[N]hour`, or `/[N]day` — fully backward compatible

## Test plan
- [x] `uv run pytest tests/unit/` — all unit tests pass with updated
assertions (models, bucket, limiter, repository, CLI, exceptions,
migrations, processor)
- [x] `uv run pytest tests/integration/` — integration tests pass with
LocalStack
- [ ] `uv run pytest tests/e2e/` — end-to-end workflows pass
- [x] `hatch run generate-sync` output matches committed sync files
- [x] `pre-commit run --all-files` passes (lint, type check, sync
verification)

Closes #406
Closes #410

🤖 Generated with [Claude Code](https://claude.ai/code)

Author: sodre

CLAUDE.md

@@ -536,7 +536,7 @@ Primary mitigation: cascade defaults to `False`.
 ### Token Bucket Algorithm
 - Buckets can go **negative** for post-hoc reconciliation
 - Refill is calculated lazily on each access
-- `burst >= capacity` allows controlled bursting
+- `capacity` is the bucket ceiling; factory methods accept `burst` to set `capacity > refill_amount`
 
 ### DynamoDB Single Table Design
 - All entities, buckets, limits, usage in one table
@@ -826,12 +826,12 @@ Limit configs use composite items (v0.8.0+, ADR-114 for configs). All limits for
 
 | Level | PK | SK | Attributes |
 |-------|----|----|------------|
-| System | `{ns}/SYSTEM#` | `#CONFIG` | `on_unavailable`, `l_rpm_cp`, `l_rpm_bx`, `l_rpm_ra`, `l_rpm_rp`, ... |
+| System | `{ns}/SYSTEM#` | `#CONFIG` | `on_unavailable`, `l_rpm_cp`, `l_rpm_ra`, `l_rpm_rp`, ... |
 | Resource | `{ns}/RESOURCE#{res}` | `#CONFIG` | `resource`, `l_rpm_cp`, ... |
 | Entity | `{ns}/ENTITY#{id}` | `#CONFIG#{resource}` | `entity_id`, `resource`, `l_rpm_cp`, ... |
 
 **Limit attribute format:** `l_{limit_name}_{field}` where field is one of:
-- `cp` (capacity), `bx` (burst), `ra` (refill_amount), `rp` (refill_period_seconds)
+- `cp` (capacity), `ra` (refill_amount), `rp` (refill_period_seconds)
 
 **Config fields:**
 - `config_version` (int): Atomic counter for cache invalidation

README.md

@@ -41,8 +41,7 @@ sync_limiter = SyncRateLimiter(repository=sync_repo)
 # Define default limits (can be overridden per-entity)
 default_limits = [
     Limit.per_minute("rpm", 100),
-    # Token bucket with burst capacity
-    Limit.per_minute("tpm", 10_000, burst=50_000),
+    Limit.per_minute("tpm", 10_000),
 ]
 
 async with limiter.acquire(

docs/adr/114-composite-bucket-items.md

@@ -26,7 +26,7 @@ already skips META reads on cache hits.
 All limits for an entity+resource must be stored in a single composite DynamoDB
 item with SK `#BUCKET#{resource}`. Per-limit attributes must use the prefix
 `b_{limit_name}_{field}` with short field names: `tk` (tokens), `cp` (capacity),
-`bx` (burst), `ra` (refill amount), `rp` (refill period), `tc` (total consumed).
+`ra` (refill amount), `rp` (refill period), `tc` (total consumed).
 GSI2SK must be per-entity (`BUCKET#{entity_id}`), not per-limit.
 
 ## Consequences

docs/adr/115-add-based-writes-lazy-refill.md

@@ -26,7 +26,7 @@ limits simultaneously.
 
 Writers must use DynamoDB ADD to atomically decrement token balances and increment
 consumption counters. Refill must not be stored in `tk`; instead, effective tokens
-must be computed at read time as `min(stored_tk + elapsed * rate, burst)`. A single
+must be computed at read time as `min(stored_tk + elapsed * rate, capacity)`. A single
 shared `rf` attribute must serve as both the refill baseline and the optimistic
 lock. The repository must implement four write paths: Create (PutItem with
 `attribute_not_exists`), Normal (ADD with refill+consumption, condition `rf =

docs/api/exceptions.md

@@ -207,7 +207,6 @@ The `as_dict()` method returns a dictionary suitable for API responses:
             "resource": "api",
             "limit_name": "rpm",
             "capacity": 100,
-            "burst": 100,
             "available": -5,
             "requested": 10,
             "exceeded": True,
@@ -218,7 +217,6 @@ The `as_dict()` method returns a dictionary suitable for API responses:
             "resource": "api",
             "limit_name": "tpm",
             "capacity": 10000,
-            "burst": 10000,
             "available": 8500,
             "requested": 500,
             "exceeded": False,

docs/contributing/architecture.md

@@ -165,7 +165,6 @@ See: [Issue #168](https://github.com/zeroae/zae-limiter/issues/168)
     "SK": "#CONFIG",                   # or #CONFIG#{resource} for entity level
     "resource": "gpt-4",
     "l_tpm_cp": 100000,               # capacity for tpm limit
-    "l_tpm_bx": 100000,               # burst for tpm limit
     "l_tpm_ra": 100000,               # refill_amount for tpm limit
     "l_tpm_rp": 60,                   # refill_period_seconds for tpm limit
     "config_version": 1               # Atomic counter for cache invalidation
@@ -304,18 +303,6 @@ new_tokens_milli = refill.new_tokens_milli - (amount * 1000)
 
 The debt is repaid as tokens refill over time. A bucket at -1500 millitokens needs 1.5 minutes to reach 0 (at 1000 tokens/minute).
 
-### Burst Capacity
-
-Burst allows temporary exceeding of sustained rate:
-
-```python
-# Sustained: 10k tokens/minute
-# Burst: 15k tokens (one-time)
-Limit.per_minute("tpm", 10_000, burst=15_000)
-```
-
-When `burst > capacity`, users can consume up to `burst` tokens immediately, then sustain at `capacity` rate.
-
 ### Design Decisions
 
 | Decision | Rationale |
@@ -461,7 +448,7 @@ The aggregator processes DynamoDB Stream records in each batch to:
 ```
 Aggregator refill flow (per composite bucket):
 1. Aggregate tc deltas + last NewImage across stream batch
-2. For each limit: refill_bucket(tk, rf, now, bx, ra, rp)
+2. For each limit: refill_bucket(tk, rf, now, cp, ra, rp)
    +- refill_delta = new_tk - current_tk
    +- projected = new_tk after refill
    +- consumption_estimate = max(0, accumulated tc_delta)

docs/getting-started.md

@@ -275,10 +275,10 @@ Limit.custom("requests", capacity=50, refill_amount=50, refill_period_seconds=30
 | Parameter | Description |
 |-----------|-------------|
 | `name` | Unique identifier (e.g., "rpm", "tpm") |
-| `capacity` | Tokens that refill per period (sustained rate) |
-| `burst` | Maximum bucket size (defaults to capacity) |
+| `rate` | Sustained tokens per period (positional) |
+| `burst` | Optional burst ceiling (defaults to `rate`) |
 
-See [Token Bucket Algorithm](guide/token-bucket.md) for details on how capacity, burst, and refill work together.
+See [Token Bucket Algorithm](guide/token-bucket.md) for details on how rate, burst, and refill work together.
 
 ## Handling Rate Limit Errors
 

docs/guide/basic-usage.md

@@ -66,7 +66,7 @@ When using stored config, configure multiple limits at setup time:
 
 ## Burst Capacity
 
-Allow temporary bursts above the sustained rate:
+Allow temporary bursts above the sustained rate by setting `burst` higher than the rate:
 
 ```python
 # Sustain 10k tokens/minute, but allow bursts up to 15k
@@ -75,7 +75,7 @@ limits = [
 ]
 ```
 
-The bucket starts full at `burst` capacity and refills at `capacity` tokens per period. See [Token Bucket Algorithm](token-bucket.md#capacity-and-burst) for details on how burst and capacity interact.
+The bucket starts full at `burst` capacity and refills at `rate` tokens per period. See [Token Bucket Algorithm](token-bucket.md#capacity-and-burst) for details on how burst and rate interact.
 
 ## Adjusting Consumption
 

docs/guide/token-bucket.md

@@ -23,7 +23,7 @@ flowchart LR
     Check -->|No| Reject[Reject + retry_after]
 ```
 
-This creates a natural rate limit: requests can burst up to the bucket's capacity, but sustained traffic is limited by the refill rate.
+This creates a natural rate limit: requests can consume up to the bucket's capacity, but sustained traffic is limited by the refill rate.
 
 ## How zae-limiter Implements It
 
@@ -46,14 +46,14 @@ These modifications enable:
 
 ### Capacity and Burst
 
-Every limit has two key parameters:
-
-- **Capacity**: The sustained rate (tokens that refill per period)
-- **Burst**: The maximum bucket size (can be larger than capacity)
+Every limit has a **rate** (sustained throughput) and an optional **burst** (the bucket ceiling):
 
 ```python
-# 10,000 tokens/minute sustained, 15,000 burst
-Limit.per_minute("tpm", capacity=10_000, burst=15_000)
+# 10,000 tokens/minute sustained, bucket holds up to 10k
+Limit.per_minute("tpm", 10_000)
+
+# 10,000 tokens/minute sustained, but allow bursts up to 15k
+Limit.per_minute("tpm", 10_000, burst=15_000)
 ```
 
 ```mermaid
@@ -71,9 +71,9 @@ graph TD
     style E fill:#87CEEB
 ```
 
-**Key insight**: The bucket is larger (15k) but refills at the same rate (10k/minute). After fully depleting the burst, it takes **1.5 minutes** to return to full capacity—not 1 minute.
+**Key insight**: When `burst` is set, the bucket is larger than the refill rate. After fully depleting a 15k burst bucket that refills at 10k/minute, it takes **1.5 minutes** to return to full capacity. Without `burst`, the bucket ceiling equals the rate.
 
-**When to use burst > capacity:**
+**When to use burst:**
 
 - **Startup surge**: Handle initial traffic before steady state
 - **Bursty workloads**: Allow temporary spikes followed by quiet periods
@@ -192,9 +192,9 @@ except RateLimitExceeded as e:
 
 ### Choosing the right limits
 
-| Scenario | Capacity | Burst | Rationale |
-|----------|----------|-------|-----------|
-| Steady API traffic | 100 rpm | 100 | No bursting needed |
+| Scenario | Rate | Burst | Rationale |
+|----------|------|-------|-----------|
+| Steady API traffic | 100 rpm | -- | No bursting needed |
 | Bursty batch jobs | 100 rpm | 500 | Allow 5x burst, then sustain |
 | LLM tokens | 10k tpm | 15k | Handle variable response sizes |
 | Database queries | 1k rows/min | 5k | Allow large result sets occasionally |

docs/index.md

@@ -28,7 +28,7 @@ A rate limiting library backed by DynamoDB using the token bucket algorithm.
 
 ## Features
 
-- **Token Bucket Algorithm** - Precise rate limiting with configurable burst capacity
+- **Token Bucket Algorithm** - Precise rate limiting with configurable capacity and refill rates
 - **Multiple Limits** - Track requests per minute, tokens per minute, etc. in a single call
 - **Hierarchical Entities** - Two-level hierarchy (project → API keys) with cascade mode
 - **Atomic Transactions** - Multi-key updates via DynamoDB TransactWriteItems
@@ -51,7 +51,7 @@ limiter = RateLimiter(repository=repo)
 # Define default limits (can be overridden per-entity)
 default_limits = [
     Limit.per_minute("rpm", 100),
-    Limit.per_minute("tpm", 10_000, burst=50_000),  # Token bucket with burst
+    Limit.per_minute("tpm", 10_000),
 ]
 
 async with limiter.acquire(