Skip to content

Standardize Cycles scope terminology and clarify protocol behavior#2

Merged
amavashev merged 2 commits intomainfrom
claude/review-posts-docs-W88zD
Mar 11, 2026
Merged

Standardize Cycles scope terminology and clarify protocol behavior#2
amavashev merged 2 commits intomainfrom
claude/review-posts-docs-W88zD

Conversation

@amavashev
Copy link
Copy Markdown
Contributor

Summary

This PR updates documentation across multiple guides to standardize terminology for Cycles budget scopes and clarify the reserve/commit/release protocol behavior. The changes reflect a more consistent naming convention and better explain automatic vs. explicit release semantics.

Key Changes

Scope Terminology Updates:

  • Replaced "application" with "app" throughout
  • Replaced "environment" with "workspace"
  • Replaced "run" as a built-in scope with guidance to use dimensions field for run-level tracking
  • Replaced "tool" with "toolset"
  • Reordered scope hierarchy to: tenant → workspace → app → workflow → agent → toolset

Protocol Behavior Clarification:

  • Clarified that unused remainder is released automatically when actual usage is committed (not a separate step)
  • Separated explicit release behavior: only needed when work is canceled or fails before producing usage
  • Updated step descriptions to reflect automatic release as part of commit operation
  • Simplified example flows to show automatic remainder handling

Documentation Improvements:

  • Added explicit note in "how-to-model-tenant-workflow-and-run-budgets" explaining run-level budgets use dimensions field
  • Clarified shadow mode behavior with dry_run: true protocol parameter
  • Updated policy examples to reference "per-workspace limits" instead of "per-environment"
  • Refined language around when explicit release is necessary vs. automatic

Notable Details

  • The changes maintain backward compatibility in concept while improving clarity
  • Run budgets are now modeled as a dimension rather than a built-in scope, providing more flexibility
  • The reserve/commit/release pattern is now more precisely documented: reserve → execute → commit (auto-releases unused) → release only if canceled

https://claude.ai/code/session_01KLGxrhRub1DLcL9ZXZZ9wG

claude added 2 commits March 11, 2026 11:08
- Fix commit/release lifecycle: clarify that commit auto-releases unused
  remainder per spec, and explicit release is for cancellation only
- Align scope hierarchy field names with actual Subject schema:
  environment→workspace, application→app, tool→toolset
- Clarify that "run" is not a built-in subject field; run-level budgets
  are modeled via the dimensions field
- Fix scope path examples to use actual field values (not path-prefixed)
- Connect shadow mode concept to the dry_run API parameter

https://claude.ai/code/session_01KLGxrhRub1DLcL9ZXZZ9wG
New posts:
- Events: direct debit without reservation (POST /v1/events)
- Decide: preflight budget checks without reservation (POST /v1/decide)
- Caps and the three-way decision model (ALLOW/ALLOW_WITH_CAPS/DENY)
- Debt, overdraft, and the over-limit model
- Commit overage policies (REJECT/ALLOW_IF_AVAILABLE/ALLOW_WITH_OVERDRAFT)
- Reservation TTL, grace period, and extend (heartbeat pattern)
- Scope derivation: how subject fields become budget hierarchies
- Units: USD_MICROCENTS, TOKENS, CREDITS, RISK_POINTS
- Getting started with the @cycles Spring Boot Starter
- Error codes and error handling (all 12 error codes)
- Querying balances: understanding budget state

Also updates VitePress sidebar with new "Protocol Reference" section
and reorganizes existing posts.

https://claude.ai/code/session_01KLGxrhRub1DLcL9ZXZZ9wG
@amavashev amavashev merged commit 948ffae into main Mar 11, 2026
amavashev added a commit that referenced this pull request May 8, 2026
…ction-kind

Round 1 reviewer fixes:
- Intro restructured: DENY payoff (`409 BUDGET_EXCEEDED` on external send,
  draft kept for review, side effect blocked) now appears in the lede
  instead of the receipts section.
- Action-kind clarification: `send-email`/`send-email-approved` are
  toolset names; the canonical action kind in the v0.1.26 registry is
  `message.email.send`. Avoids spec confusion.
- "What broke" #2 reframed from "budget mutation broken" to
  "admin-plane mutation hardening" — runtime path (reserve, commit,
  release, deny) worked; mutation paths are the hardening item.
- "What happened in the first live runs" compressed: cut 18-artifact
  table and standalone triage table; queue counts moved to prose.
- Keywords block tightened to reviewer's focused set.

Skipped: title alts (current 51 chars vs 67-char alternative), date
shift (explicit author choice), description rewrite (reviewer's
version was over the 150-160 char SEO limit).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants