feat: prior run values

[turip]

Overview

This PR refactors usage-based charge rating around explicit run snapshot semantics. Detailed rating now treats ServicePeriodTo as the current run boundary and lets the rating layer decide which realization runs are prior runs. A realization is considered prior only when its ServicePeriodTo is before the requested rating boundary, so callers no longer need to mutate the charge by removing the current run before rating.

The usage snapshot query model is now clearer: metered quantity is calculated from the charge intent service-period start up to the requested ServicePeriodTo, capped by StoredAtLT using an exclusive stored_at < StoredAtLT filter. RateableIntent now carries the concrete service period being rated so generated detailed lines and commitment logic operate on the same period boundary as the run.

Minimum commitment handling is aligned with the run lifecycle. Detailed rating suppresses minimum commitment for interim snapshots and includes it only for final-period rating. Realtime/current totals also ignore minimum commitment before the charge service period ends and include it at or after the service-period end.

The PR also lays groundwork for late-event support by collecting prior run period snapshots in the rating flow. The actual late-event delta rating is intentionally left as a TODO, with the current implementation preserving existing rating behavior while making the future extension point explicit.

Testing

Added usage-based rating tests backed by the mock streaming connector to cover:

• ServicePeriodTo as the exclusive event-time upper bound.
• StoredAtLT as the exclusive stored-at cutoff.
• Current-run filtering when the current run is already present on the charge.
• Minimum commitment inclusion/exclusion in GetTotalsForUsage using the real billing rating service.

Summary by CodeRabbit

• Refactor

  • Restructured usage-based billing calculations to improve clarity around how service periods and minimum commitments are handled during rating operations.

• Tests

  • Enhanced test coverage for quantity snapshots, service period handling, and minimum commitment inclusion/exclusion scenarios in billing computations.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR refactors the usage-based rating API by introducing GetDetailedRatingForUsage (replacing GetDetailedLinesForUsage), adds a ServicePeriod field to RateableIntent, and refines minimum commitment handling based on service period boundaries. Multiple service callers are updated to use the new API with explicit control over minimum commitment logic.

Changes

Cohort / File(s)	Summary
Documentation & Guidance .agents/skills/charges/SKILL.md	Clarifies usage-based rating semantics, minimum-commitment handling across service periods, and testing guidance for production end-to-end behavior.
Core Rating API & Types openmeter/billing/charges/usagebased/rating.go, openmeter/billing/charges/usagebased/service/rating/service.go, openmeter/billing/charges/usagebased/service/rating/totals.go	Adds ServicePeriod field to RateableIntent; renames/updates GetDetailedLinesForUsage → GetDetailedRatingForUsage interface; extends GetTotalsForUsageInput with IgnoreMinimumCommitment flag.
Detailed Rating Implementation openmeter/billing/charges/usagebased/service/rating/details.go, openmeter/billing/charges/usagebased/service/rating/quantitysnapshot.go	Refactors GetDetailedLinesForUsage → GetDetailedRatingForUsage with revised input validation, prior-run filtering based on service period, capped quantity computation, and conditional minimum-commitment suppression; adds new getQuantityForUsage helper with typed input validation.
Service Callers Updated openmeter/billing/charges/usagebased/service/get.go, openmeter/billing/charges/usagebased/service/currenttotals.go, openmeter/billing/charges/usagebased/service/creditsonly.go, openmeter/billing/charges/usagebased/service/creditheninvoice.go	Updates callers to use new rating APIs and pass IgnoreMinimumCommitment conditionally; switches from GetDetailedLinesForUsage to GetDetailedRatingForUsage where detailed lines are needed; adjusts input construction to remove PriorRuns-derived parameters.
Run Processing openmeter/billing/charges/usagebased/service/run/create.go, openmeter/billing/charges/usagebased/service/run/detailedline.go	Removes IgnoreMinimumCommitment from CreateRatedRunInput; updates result type from GetRatingForUsageResult → GetDetailedRatingForUsageResult; simplifies adapter update payload to only set ID and Totals.
Tests openmeter/billing/charges/usagebased/service/rating/service_test.go, openmeter/billing/charges/usagebased/service/creditheninvoice_test.go, openmeter/billing/charges/usagebased/service/run/detailedline_test.go	Updates test fixtures and assertions to target GetDetailedRatingForUsage API; adds coverage for filtering, minimum-commitment inclusion/exclusion, and quantity verification; removes obsolete minimum-commitment-flag test.
Utilities pkg/timeutil/closedperiod.go	Adds ContainsPeriodInclusive() method for testing full containment of one period within another.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• chore: split rating service #4199 — Performs the same core refactor of the usage-based rating API, splitting totals vs. detailed-lines rating and updating multiple callers.
• chore: rework run snapshotting #4226 — Makes overlapping changes to the same files with same refactoring of GetDetailedLinesForUsage → GetDetailedRatingForUsage.
• feat(usagebased-charge): ignore minimum commitment on partial runs #4219 — Modifies how the minimum-commitment flag is passed into detailed-rating and controls ignore-minimum-commitment behavior across run creation and rating option propagation.

Suggested labels

release-note/feature

Suggested reviewers

• tothandras
• GAlexIHU

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat: prior run values' directly reflects the core refactoring: enabling the rating layer to autonomously identify prior runs based on ServicePeriodTo boundaries rather than requiring callers to pre-filter them.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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 feat/prior-run-values

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@openmeter/billing/charges/usagebased/service/rating/details.go`:
- Around line 126-159: Loop currently calls snapshotQuantity for every
eligibleRealizations entry even though rateWithLateEvents only consumes values
starting at CurrentPeriod; this is causing unnecessary O(n) meter queries. Fix
by deferring snapshotQuantity until actually needed: replace the eager
priorPeriodQty call with a lazy accessor (e.g., closure or thunk) that captures
snapshotQuantity(ctx, snapshotQuantityInput{...}) and only invokes it on first
use, and pass that accessor into the code that calls rateWithLateEvents (or call
snapshotQuantity conditionally right before any logic that consumes prior-period
quantities). Keep function names intact (eligibleRealizations, snapshotQuantity,
rateWithLateEvents, GetDetailedRatingForUsageResult) so reviewers can find and
verify the change. Ensure errors from the lazy call are propagated the same way
as before.

🪄 Autofix (Beta)

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

Run ID: ef4b5142-fd21-4136-ae34-bd817e97ec30

📥 Commits

Reviewing files that changed from the base of the PR and between 33fd73b and f20fe83.

📒 Files selected for processing (16)

• .agents/skills/charges/SKILL.md
• openmeter/billing/charges/usagebased/rating.go
• openmeter/billing/charges/usagebased/service/creditheninvoice.go
• openmeter/billing/charges/usagebased/service/creditheninvoice_test.go
• openmeter/billing/charges/usagebased/service/creditsonly.go
• openmeter/billing/charges/usagebased/service/currenttotals.go
• openmeter/billing/charges/usagebased/service/get.go
• openmeter/billing/charges/usagebased/service/rating/details.go
• openmeter/billing/charges/usagebased/service/rating/quantitysnapshot.go
• openmeter/billing/charges/usagebased/service/rating/service.go
• openmeter/billing/charges/usagebased/service/rating/service_test.go
• openmeter/billing/charges/usagebased/service/rating/totals.go
• openmeter/billing/charges/usagebased/service/run/create.go
• openmeter/billing/charges/usagebased/service/run/detailedline.go
• openmeter/billing/charges/usagebased/service/run/detailedline_test.go
• pkg/timeutil/closedperiod.go

💤 Files with no reviewable changes (1)

• openmeter/billing/charges/usagebased/service/creditheninvoice_test.go