v0.1.24: Change default overage policy and cap behavior

[amavashev]

Summary

This release introduces breaking changes to the Cycles Budget Authority API's default overage policy and commit behavior. The default CommitOveragePolicy is changed from REJECT to ALLOW_IF_AVAILABLE, and the ALLOW_IF_AVAILABLE policy now caps charges to available budget instead of rejecting commits.

Key Changes

• BREAKING: Default overage policy changed from REJECT to ALLOW_IF_AVAILABLE

  • Clients relying on implicit REJECT behavior must now explicitly set overage_policy: REJECT

• ALLOW_IF_AVAILABLE commit behavior redesigned

  • Commits now always succeed when actual > reserved (never reject)
  • If remaining budget supports the full overage delta, charge it atomically across all derived scopes
  • If remaining budget is insufficient, cap the delta to available remaining and charge estimate + capped_delta
  • Scopes where the full delta could not be covered are marked with is_over_limit=true, blocking future reservations until reconciled
  • Never creates debt; never rejects a commit

• Extended is_over_limit semantics

  • Now set by ALLOW_IF_AVAILABLE when overage delta is capped, in addition to existing ALLOW_WITH_OVERDRAFT debt scenarios
  • Updated description to clarify both debt and capping scenarios

• Updated CommitResponse.charged documentation

  • Clarified that charged may be less than actual when ALLOW_IF_AVAILABLE caps the overage delta
  • Added explicit description: charged = estimate + capped_delta in capping scenarios

• Updated ApplyEventRequest documentation

  • Aligned event apply behavior with commit semantics for consistency
  • Changed default overage policy to ALLOW_IF_AVAILABLE
  • Updated descriptions to reflect capping behavior instead of rejection

Implementation Details

The changes maintain backward compatibility at the protocol level while introducing a more lenient default behavior. The atomic operation guarantee is preserved for the charge operation itself, but the delta amount may be reduced to fit available budget. The is_over_limit flag now serves as a unified indicator for both overdraft scenarios and budget-capped scenarios, providing a consistent mechanism for blocking future reservations.

https://claude.ai/code/session_01WeUFfwYKWvpCXPUYsZLqUa