governance: calendar alignment applies from the next period

[akshaydeo]

Summary

Enabling calendar alignment on an existing budget previously promised to snap last_reset to the current period start and zero out CurrentUsage. This never actually happened: UpdateBudget and UpdateRateLimit carry both values forward from the stored row on every config write, so the snap was silently discarded one layer below the handler. Rather than making the snap work (which would move last_reset backwards, conflicting with the forward-only guard that keeps cluster nodes in agreement), the dead snap code is removed entirely. Calendar alignment now takes effect from the next period boundary, leaving the current window and its accumulated usage untouched.

Changes

• Removed the calendarAlignmentJustEnabled snap blocks from updateTeam, updateCustomer, and updateProviderGovernance. These blocks wrote LastReset and CurrentUsage to UpdateBudget/UpdateRateLimit, but the real store always copies those fields back from the stored row, making the writes no-ops in production.
• Updated the calendar_aligned field description in the OpenAPI schema and governance YAML to reflect the new behaviour: alignment takes effect from the next period; the current window keeps its start and accumulated usage.
• Updated the docs to clarify that toggling alignment on an existing budget does not re-anchor the current window, and that setting alignment at create time is the way to start aligned from the beginning.
• Fixed the mockCustomerStore.UpdateBudget mock to carry CurrentUsage and LastReset forward from the stored row, matching the real store's contract. Without this, handler-level tests could assert on values the real store would discard.
• Replaced TestUpdateCustomer_CalendarAligned_SnapsExistingBudget with TestUpdateCustomer_CalendarAligned_DoesNotTouchBudgets, which asserts the correct behaviour.
• Added integration tests TestTeamBudgetCalendarAlignmentAppliesFromNextPeriod, TestTeamRateLimitCalendarAlignmentAppliesFromNextPeriod, and TestCustomerBudgetCalendarAlignmentAppliesFromNextPeriod that verify last_reset is not moved when alignment is enabled on an existing resource.
• Extended CreateTeamRequest, CreateCustomerRequest, and UpdateCustomerRequest test structs to carry RateLimit and CalendarAligned fields needed by the new integration tests.

Type of change

• Bug fix
• Feature
• Refactor
• Documentation
• Chore/CI

Affected areas

• Core (Go)
• Transports (HTTP)
• Providers/Integrations
• Plugins
• UI (React)
• Docs

How to test

go test ./transports/bifrost-http/handlers/... -run TestUpdateCustomer_CalendarAligned
go test ./tests/governance/... -run TestTeamBudgetCalendarAlignmentAppliesFromNextPeriod
go test ./tests/governance/... -run TestTeamRateLimitCalendarAlignmentAppliesFromNextPeriod
go test ./tests/governance/... -run TestCustomerBudgetCalendarAlignmentAppliesFromNextPeriod

Create a team or customer with a monthly budget, then enable calendar_aligned via PUT. Confirm that last_reset and current usage are unchanged immediately after the update. Confirm that the budget resets to the aligned boundary at the next period tick.

Breaking changes

• Yes
• No

Enabling calendar_aligned on an existing budget no longer resets usage to zero or moves last_reset to the period start. Callers who relied on the toggle as a way to force an immediate reset must instead delete and recreate the budget, or wait for the next natural period boundary.

Related issues

Security considerations

None. No auth, secrets, or PII are involved.

Checklist

• I read docs/contributing/README.md and followed the guidelines
• I added/updated tests where appropriate
• I updated documentation where needed
• I verified builds succeed (Go and UI)
• I verified the CI pipeline passes locally if applicable

[akshaydeo]

• governance: enabling calendar alignment preserves the open window #6013
• governance: extend reset_budget_usage to teams, customers, model limits and provider governance #6004
• governance: calendar alignment applies from the next period #6003 👈 (View in Graphite)
• adds reset budget honor flow #6002
• docs: document quarterly budgets and fiscal quarter configuration #6000
• ui: quarterly budget period with fiscal-quarter advanced settings #5999
• governance: quarterly budget windows with configurable fiscal start #5997
• quarterly budget #5996
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 40 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 75541af7-2e85-433c-a727-fe10abc8d580

📥 Commits

Reviewing files that changed from the base of the PR and between d9d2e2b and 02ed8c2.

📒 Files selected for processing (2)

• docs/features/governance/budget-and-limits.mdx
• plugins/governance/budgetcycle_test.go

📝 Walkthrough

Summary by CodeRabbit

• Bug Fixes

  • Enabling calendar-aligned budget and rate-limit resets preserves the current period’s start time and accumulated usage.
  • Calendar alignment takes effect at the next applicable period boundary instead of resetting immediately.
  • Overdue windows reset during the next processing cycle and may clear usage shortly after alignment is enabled.
  • Alignment operates independently by window and supports sub-day durations without affecting rolling schedules.
  • Behavior applies across customer, team, virtual-key, and provider configuration settings.

• Documentation

  • Updated API and feature documentation with the revised behavior and considerations.

• Tests

  • Added coverage for budgets and rate limits across supported governance settings.

Walkthrough

Calendar alignment updates preserve existing budget and rate-limit usage and reset timestamps. Budget-cycle logic handles overdue windows, independent durations, and rolling sub-day windows. Tests and API documentation describe the updated behavior.

Changes

Calendar alignment behavior

Layer / File(s)	Summary
Preserve existing governance windows transports/bifrost-http/handlers/governance.go	Team, customer, and provider updates retain existing usage and reset timestamps when alignment is enabled.
Validate preserved state and boundary resets tests/governance/..., transports/bifrost-http/handlers/governance_test.go, plugins/governance/budgetcycle_test.go	Tests verify preserved runtime fields, deferred boundary resets, independent duration boundaries, rolling sub-day windows, and sub-day persistence.
Update behavior documentation docs/features/governance/budget-and-limits.mdx, docs/openapi/schemas/management/governance.yaml, docs/openapi/openapi.json	Documentation describes owner-level alignment, preserved current windows, deferred resets, and sub-day duration behavior.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• maximhq/bifrost#6000: Modifies related calendar-aligned governance update handling and state preservation.
• maximhq/bifrost#6004: Modifies related governance handlers and tests for preserved usage and reset windows.
• maximhq/bifrost#5997: Modifies related calendar-aligned reset logic and budget-cycle tests.

Suggested reviewers: impoiler, pratham-mishra04, roroghost17

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly summarizes that calendar alignment now takes effect from the next period.
Description check	✅ Passed	The description covers the purpose, changes, testing steps, affected areas, breaking behavior, security, and checklist status.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch calendar-align-from-next-period

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

transports/bifrost-http/handlers/governance.go (1)

3027-3027: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add handler-level regression tests for customer and provider governance rate limits.

When enabling calendar_aligned, assert both token/request usage counters and reset timestamps. Existing alignment tests cover customer budgets and only the team token_last_reset field.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@transports/bifrost-http/handlers/governance.go` at line 3027, Add
handler-level regression tests for customer and provider governance rate limits
in the governance handlers, covering the calendar_aligned configuration. Assert
both token and request usage counters and their reset timestamps, extending
existing alignment coverage beyond customer budgets and the team
token_last_reset field.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/features/governance/budget-and-limits.mdx`:
- Around line 176-178: Update the calendar alignment documentation to specify
the request-body location for each supported PUT endpoint: customer, team, and
provider-governance updates receive calendar_aligned at the owner request-body
level, while virtual-key updates use the budget field location. Replace the
ambiguous “on the budget” wording and verify the documented locations match the
implementation and schemas.

In `@tests/governance/customerbudget_test.go`:
- Around line 397-402: Replace the unchecked response-field assertions with
validated type assertions that call t.Fatalf on malformed data. In
tests/governance/customerbudget_test.go:397-402 and
tests/governance/teambudget_test.go:242-247, validate the first budget object
and its last_reset string; in tests/governance/teambudget_test.go:312-320,
validate the rate-limit object and its token_last_reset string, preserving the
existing parsing and assertions for valid responses.

---

Nitpick comments:
In `@transports/bifrost-http/handlers/governance.go`:
- Line 3027: Add handler-level regression tests for customer and provider
governance rate limits in the governance handlers, covering the calendar_aligned
configuration. Assert both token and request usage counters and their reset
timestamps, extending existing alignment coverage beyond customer budgets and
the team token_last_reset field.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: b7857d37-21fc-4477-949e-ee2e408439fc

📥 Commits

Reviewing files that changed from the base of the PR and between c148a5f and ce56c83.

📒 Files selected for processing (8)

• docs/features/governance/budget-and-limits.mdx
• docs/openapi/openapi.json
• docs/openapi/schemas/management/governance.yaml
• tests/governance/customerbudget_test.go
• tests/governance/teambudget_test.go
• tests/governance/test_utils.go
• transports/bifrost-http/handlers/governance.go
• transports/bifrost-http/handlers/governance_test.go

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/features/governance/budget-and-limits.mdx (1)

159-168: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Reject 1Q for rate limits or update the documentation and schema to support it. Runtime parsing and calendar reset handling accept 1Q, but no rate-limit validator or schema constraint rejects it. This conflicts with the budget-only documentation.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/features/governance/budget-and-limits.mdx` around lines 159 - 168, Align
rate-limit validation and schema constraints with the documented budget-only
behavior by rejecting the 1Q duration for rate limits, while preserving 1Q
support for budgets. Update the runtime validator and relevant schema
definitions so quarterly rate-limit values cannot be accepted.

Source: Path instructions

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/features/governance/budget-and-limits.mdx`:
- Line 178: Update the budget reset logic around Budget.WindowStart and
LastReset so changing alignment from false to true records the activation time
and skips the current calendar boundary, preserving usage until the next
boundary; apply the same transition rule to rate limits. Then verify the
documented behavior matches the implementation, config.schema.json, and provider
behavior.

---

Outside diff comments:
In `@docs/features/governance/budget-and-limits.mdx`:
- Around line 159-168: Align rate-limit validation and schema constraints with
the documented budget-only behavior by rejecting the 1Q duration for rate
limits, while preserving 1Q support for budgets. Update the runtime validator
and relevant schema definitions so quarterly rate-limit values cannot be
accepted.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 6972db23-5738-4c10-a2d5-4e6e84529892

📥 Commits

Reviewing files that changed from the base of the PR and between ce56c83 and 9f91c19.

📒 Files selected for processing (3)

• docs/features/governance/budget-and-limits.mdx
• tests/governance/customerbudget_test.go
• tests/governance/teambudget_test.go

🚧 Files skipped from review as they are similar to previous changes (2)

• tests/governance/teambudget_test.go
• tests/governance/customerbudget_test.go

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/features/governance/budget-and-limits.mdx`:
- Around line 176-185: Update the calendar-alignment section to explicitly
include associated rate limits wherever it currently describes budgets,
including preserved last_reset values, usage, deferred resets, and switch-over
behavior. Clarify that owner-level calendar alignment applies to both budget and
rate-limit reset windows, while retaining the existing create/update request
guidance and warning.

In `@plugins/governance/budgetcycle_test.go`:
- Around line 845-892: Replace
TestEnablingCalendarAlignmentCanResetAtTheBoundaryAlreadyPassed with
table-driven cases that create an unaligned budget and enable alignment through
the update path. Verify LastReset and CurrentUsage remain unchanged at 42,
budgetResetTarget returns no reset before the next boundary (March 1), and cover
both windows opened before and after the February boundary.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: c870786b-4a9e-4997-94ce-a9d3dbe8aada

📥 Commits

Reviewing files that changed from the base of the PR and between 9f91c19 and 9c813ec.

📒 Files selected for processing (2)

• docs/features/governance/budget-and-limits.mdx
• plugins/governance/budgetcycle_test.go

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/features/governance/budget-and-limits.mdx`:
- Line 178: Update the owner-level reset-alignment documentation around the
statements that describe budgets and rate limits so it explicitly states that
each resource aligns to its own reset_duration calendar boundary rather than a
shared reset instant. Clarify preservation guidance by referring to the
corresponding budget or rate-limit boundary, or recommend enabling alignment at
creation time when all existing windows must be preserved.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 558ae13a-5671-4121-a731-718b1c299889

📥 Commits

Reviewing files that changed from the base of the PR and between 9c813ec and bb014fd.

📒 Files selected for processing (2)

• docs/features/governance/budget-and-limits.mdx
• plugins/governance/budgetcycle_test.go

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/features/governance/budget-and-limits.mdx`:
- Around line 186-189: The budget alignment documentation should cover both
reset sweeps and request-time evaluation via BumpBudgetUsage. Update the
“already due” window description to state that it resets and clears usage at the
next reset evaluation, including either trigger explicitly or using wording that
encompasses both, while preserving the existing behavior details.

In `@plugins/governance/budgetcycle_test.go`:
- Around line 971-979: Extend the persistence assertions in the sub-day aligned
budget test after configStore.GetBudget to verify stored.IsCalendarAligned is
true, alongside the existing ResetDuration assertion. Keep the test’s current
setup and save behavior unchanged.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: d984a882-a1e2-4e7c-9ff6-12de649d5229

📥 Commits

Reviewing files that changed from the base of the PR and between bb014fd and d9d2e2b.

📒 Files selected for processing (2)

• docs/features/governance/budget-and-limits.mdx
• plugins/governance/budgetcycle_test.go

[akshaydeo]

Merge activity

• Aug 10, 9:42 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• Aug 10, 9:59 PM UTC: Graphite rebased this pull request as part of a merge.
• Aug 10, 10:00 PM UTC: @akshaydeo merged this pull request with Graphite.

The base branch was changed.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
bifrost	🟡 Building	–	Aug 10, 2026, 9:58 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.