Fix decision handling and add idempotency keys to Cycles client

[amavashev]

Summary

This PR corrects the Cycles client documentation and examples to align with the actual API behavior, and adds idempotency key support to all write operations as required by the protocol.

Key Changes

Decision Handling Corrections

• Removed incorrect DENY decision checks: The code was checking for decision=DENY in 2xx responses for non-dry-run reservations. Per the API spec, insufficient budget returns a 409 error response instead. The decision=DENY only occurs in 2xx responses when dry_run=true.
• Updated test expectations: Changed mock responses from 201 to 200 for successful reservations, and updated budget denial test to expect 409 error response instead of 200 with DENY decision.

Idempotency Key Implementation

• Added idempotency keys to all write operations:
  • CommitRequest.builder() now includes .idempotencyKey("commit-" + UUID.randomUUID())
  • ReleaseRequest.builder() now includes .idempotencyKey("release-" + UUID.randomUUID())
  • DecisionRequest.builder() now includes .idempotencyKey("decide-" + UUID.randomUUID())
• These changes ensure all write operations comply with the idempotency requirement scoped per (effective tenant, endpoint, idempotency_key).

Documentation Fixes

• Corrected scope derivation examples to include the workspace scope (which is always derived even when not explicitly provided)
• Fixed monetary amount examples (corrected decimal place conversions from microcents)
• Clarified enforcement terminology: changed "allow / downgrade / deny" to "ALLOW / ALLOW_WITH_CAPS / DENY"
• Updated idempotency scoping description to reference "effective tenant"

Notable Implementation Details

• Idempotency keys use UUID.randomUUID() for uniqueness and are prefixed with the operation type for clarity
• The removal of decision checks simplifies error handling by relying on HTTP status codes (2xx vs 409) rather than response body inspection
• All changes maintain backward compatibility while improving correctness and protocol compliance

https://claude.ai/code/session_01V4QiiG3XgZ9ALnf3gCaBUw