Problem
The current documentation doesn't clearly explain how lease.adjust() works internally. A reader could reasonably assume that adjust() immediately writes to DynamoDB, or that the commit on context exit is non-atomic. In reality:
adjust() accumulates deltas in memory only (no DynamoDB calls)
_commit_adjustments() writes a single atomic UpdateItem per entity on successful context exit
_rollback() refunds initial consumption via compensating writes on exception
This two-phase model is a key correctness property that should be prominently documented.
Suggested Content
Add a "Lease Lifecycle" section to the getting-started or API docs:
## Lease Lifecycle
1. `acquire()` → initial tokens consumed (written to DynamoDB)
2. `adjust()` → deltas accumulated in memory (NO DynamoDB calls)
3. Context exit (success) → `_commit_adjustments()` writes one
atomic UpdateItem per entity
4. Context exit (exception) → `_rollback()` refunds initial
consumption via compensating writes
Note: If `_rollback()` itself fails (e.g., DynamoDB unavailable),
the failure is logged but does not mask the original exception.
A sequence diagram showing the DynamoDB operations at each phase would also help.
Why This Matters
Without this documentation, users integrating zae-limiter into latency-sensitive pipelines (e.g., LLM proxies) may incorrectly assume adjust() adds network round-trips, or may not trust the atomicity guarantees and add unnecessary defensive code.
Problem
The current documentation doesn't clearly explain how
lease.adjust()works internally. A reader could reasonably assume thatadjust()immediately writes to DynamoDB, or that the commit on context exit is non-atomic. In reality:adjust()accumulates deltas in memory only (no DynamoDB calls)_commit_adjustments()writes a single atomicUpdateItemper entity on successful context exit_rollback()refunds initial consumption via compensating writes on exceptionThis two-phase model is a key correctness property that should be prominently documented.
Suggested Content
Add a "Lease Lifecycle" section to the getting-started or API docs:
A sequence diagram showing the DynamoDB operations at each phase would also help.
Why This Matters
Without this documentation, users integrating zae-limiter into latency-sensitive pipelines (e.g., LLM proxies) may incorrectly assume
adjust()adds network round-trips, or may not trust the atomicity guarantees and add unnecessary defensive code.