governance: enabling calendar alignment preserves the open window

[akshaydeo]

Summary

Switching calendar alignment on for an owner with accumulated usage was destructive: the reset sweep treats a window as due whenever its most recent calendar boundary is later than LastReset, so any window that opened before that boundary was immediately overdue and its usage was cleared on the next tick. For a monthly budget switched mid-month, that meant losing most of the month's accumulated spend with no warning.

This PR introduces a forward-only adoption step that runs on the false → true transition. Instead of resetting, each open window's LastReset is moved forward to the boundary it now follows, making the window current rather than overdue. Usage is never touched. The first real reset then happens at the next boundary, exactly as if alignment had been set at creation time.

Changes

• TableBudget.AdoptCalendarAlignment — moves LastReset forward to WindowStart(now) when the window is overdue under the new rule. Returns false and changes nothing for unaligned budgets, sub-day durations (no calendar boundary to adopt), and windows that are already current.
• TableRateLimit.AdoptCalendarAlignment — mirrors the budget logic for token and request counters independently, since they carry separate durations and LastReset values.
• LocalGovernanceStore.AdoptCalendarAlignmentInMemory / AdoptRateLimitCalendarAlignmentInMemory — CAS-loop wrappers that apply adoption to the live in-memory store. The loop carries whatever usage it observes at swap time, so a concurrent spend bump is never silently dropped.
• GovernanceHandler.adoptCalendarAlignment — called after the in-memory reload in updateVirtualKey, updateTeam, updateCustomer, and updateProviderGovernance, but only when calendar_aligned transitions from false to true. For virtual keys, adoption also covers every model config that inherits the flag.
• BifrostHTTPServer.AdoptCalendarAlignmentInMemory — server-level entry point that resolves the governance store and dispatches to the per-budget and per-rate-limit adoption methods. Missing entries are not treated as errors.
• GovernanceManager / ServerCallbacks interfaces — extended with AdoptCalendarAlignmentInMemory so enterprise can broadcast the adoption to cluster peers the same way usage resets are broadcast.
• Documentation — the calendar alignment section is rewritten to describe the adoption contract: the boundary moves forward, usage is preserved, sub-day windows stay rolling, and the forward-only rule is what keeps cluster nodes in agreement.

Notable design decisions:

• Adoption is forward-only. Rewinding LastReset would re-open a window the cluster already agreed was spent, breaking cluster consistency.
• Adoption runs after the in-memory reload, for the same reason the usage reset does: the reload carries cached values forward and would overwrite the change if adoption ran first.
• Sub-day windows (e.g. 1h) are explicitly excluded because they have no calendar boundary to adopt; they remain on their rolling schedule regardless of the owner's alignment flag.

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 ./framework/configstore/tables/... ./plugins/governance/... ./transports/bifrost-http/handlers/...

Key scenarios to verify:

1. Mid-month switch-on: create a monthly budget with usage accumulated since before the 1st, enable calendar_aligned, confirm LastReset moves to the 1st and CurrentUsage is unchanged.
2. Already-current window: a window opened after the most recent boundary should report no adoption and keep its original LastReset.
3. Sub-day window: an hourly counter beside a monthly budget should keep its rolling anchor after the switch.
4. Concurrent spend: usage bumped concurrently with adoption must survive; the CAS loop must not drop any increment.
5. Already-aligned owner: a second write with calendar_aligned: true on an already-aligned owner must not call adoption, which would keep pushing the boundary forward and prevent the window from ever resetting.

Breaking changes

• No

Security considerations

None. The change only affects how reset boundaries are computed in memory; no authentication, 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

[coderabbitai]

📝 Walkthrough

Summary by CodeRabbit

• Bug Fixes
  • Enabling calendar alignment now preserves existing budget and rate-limit usage.
  • Existing windows are re-anchored to the next applicable calendar boundary, moving forward only.
  • Token and request limits update independently while retaining current usage.
  • Rolling, sub-day, unaligned, and already-current windows remain unchanged.
  • Calendar alignment now applies consistently across supported governance configurations.

Walkthrough

Calendar alignment now preserves usage while advancing eligible budget and rate-limit windows to current calendar boundaries. Governance handlers detect newly enabled alignment and invoke in-memory adoption for affected governance entities.

Changes

Calendar alignment adoption

Layer / File(s)	Summary
Window adoption rules and coverage framework/configstore/tables/budget.go, framework/configstore/tables/ratelimit.go, framework/configstore/tables/budgetwindow_test.go, docs/features/governance/budget-and-limits.mdx, plugins/governance/budgetcycle_test.go	Eligible overdue windows advance to newer calendar boundaries. Sub-day, unaligned, current, and backward cases remain unchanged. Usage remains preserved.
Atomic in-memory adoption plugins/governance/store.go, plugins/governance/storeconcurrency_test.go	Governance store adoption uses CAS retry loops for budgets and rate limits. Concurrent budget usage remains preserved.
Governance update wiring transports/bifrost-http/handlers/governance.go, transports/bifrost-http/server/server.go, transports/bifrost-http/handlers/governance_test.go, transports/bifrost-http/handlers/pricing_override_test.go	Governance updates detect transitions from rolling to calendar alignment, reload affected entities, and invoke in-memory adoption. Server callbacks resolve the governance plugin and report failures. Tests verify adoption, no-op behavior, and reconciled budget selection.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant GovernanceUpdate
  participant GovernanceManager
  participant BifrostHTTPServer
  participant GovernanceStore
  GovernanceUpdate->>GovernanceManager: request adoption for changed owners
  GovernanceManager->>BifrostHTTPServer: AdoptCalendarAlignmentInMemory
  BifrostHTTPServer->>GovernanceStore: adopt budget and rate-limit windows
  GovernanceStore-->>BifrostHTTPServer: adoption result
  BifrostHTTPServer-->>GovernanceManager: success or error

Loading

Possibly related PRs

• maximhq/bifrost#5997: Introduces quarterly boundary and fiscal-start handling used by calendar alignment.
• maximhq/bifrost#6000: Modifies calendar-aligned budget behavior and related tests.
• maximhq/bifrost#6003: Modifies calendar alignment behavior across governance handlers, budgets, and rate limits.

Suggested reviewers: pratham-mishra04, roroghost17, danpiths

🚥 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 and concisely describes the main behavior change: preserving the open window when calendar alignment is enabled.
Description check	✅ Passed	The description covers the purpose, implementation, tests, affected areas, risks, and checklist, with only the related issues section omitted.

✨ 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 preserve-usage-when-enabling-calendar-alignment

---

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

[akshaydeo]

• governance: enabling calendar alignment preserves the open window #6013 👈 (View in Graphite)
• governance: extend reset_budget_usage to teams, customers, model limits and provider governance #6004
• governance: calendar alignment applies from the next period #6003
• 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]

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 `@transports/bifrost-http/handlers/governance.go`:
- Around line 4201-4208: Update the provider governance flow around the reload
result near the existing model-config update logic, capturing it in a variable
accessible to the adoption block. In the call to adoptCalendarAlignment, pass
the reloaded model config’s Budgets and RateLimitID, falling back to the
in-handler mc when the reload returns no entity, matching the updateTeam and
updateCustomer patterns.

🪄 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: c8fb3370-1232-4e72-9beb-3d8b6bd2bbb6

📥 Commits

Reviewing files that changed from the base of the PR and between 7cea97e and f9894d4.

📒 Files selected for processing (11)

• docs/features/governance/budget-and-limits.mdx
• framework/configstore/tables/budget.go
• framework/configstore/tables/budgetwindow_test.go
• framework/configstore/tables/ratelimit.go
• plugins/governance/budgetcycle_test.go
• plugins/governance/store.go
• plugins/governance/storeconcurrency_test.go
• transports/bifrost-http/handlers/governance.go
• transports/bifrost-http/handlers/governance_test.go
• transports/bifrost-http/handlers/pricing_override_test.go
• transports/bifrost-http/server/server.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, 10:06 PM UTC: Graphite rebased this pull request as part of a merge.
• Aug 10, 10:07 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, 10:06 PM

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