Merge pull request #18 from runcycles/claude/analyze-spring-issue-29-vBIY9

Claude/analyze spring issue 29 v biy9

Author: amavashev

README.md

@@ -59,6 +59,24 @@ result = call_llm("Hello", tokens=100)
 > ```
 > The key (e.g. `cyc_live_abc123...`) is shown only once — save it immediately. For key rotation and lifecycle details, see [API Key Management](https://runcycles.io/how-to/api-key-management-in-cycles).
 
+### Budget lifecycle
+
+The `@cycles` decorator wraps your function in a reserve → execute → commit/release lifecycle:
+
+| Scenario | Outcome | Detail |
+|---|---|---|
+| Reservation denied | **Neither** | `BudgetExceededError`, `OverdraftLimitExceededError`, or `DebtOutstandingError` raised; function never executes |
+| `dry_run=True`, any decision | **Neither** | Returns `DryRunResult` or raises; no real reservation created |
+| Function returns successfully | **Commit** | Actual amount charged; unused remainder auto-released |
+| Function raises any exception | **Release** | Full reserved amount returned to budget; exception re-raised |
+| Commit fails (5xx / network) | **Retry** | Exponential backoff with configurable attempts |
+| Commit fails (non-retryable 4xx) | **Release** | Reservation released after non-retryable client error |
+| Commit gets RESERVATION_EXPIRED | **Neither** | Server already reclaimed budget on TTL expiry |
+| Commit gets RESERVATION_FINALIZED | **Neither** | Already committed or released (idempotent replay) |
+| Commit gets IDEMPOTENCY_MISMATCH | **Neither** | Previous commit already processed; no release attempted |
+
+All raised exceptions from the guarded function trigger release. See [How Reserve-Commit Works](https://runcycles.io/protocol/how-reserve-commit-works-in-cycles) for the full protocol-level explanation.
+
 ### Programmatic client
 
 ```python