feat(credit): add usage snapshot schema

[GAlexIHU]

What

• expose the complete usage-period snapshot type
• add an optional usage_snapshot JSONB field to balance snapshots
• include the generated Ent changes and migration

Why

This is the schema-first half of the entitlement balance snapshot fix in #4846. Landing and deploying the additive persistence shape first keeps the follow-up runtime change zero-downtime and leaves room for a snapshot warmup job if needed.

Impact

Additive and inert: this PR does not read, write, or select the new field at runtime.

Validation

• generated schema and migration are unchanged from the previously validated fix(entitlement): preserve grant usage across balance snapshots #4846 stack
• git diff --check
• follow-up credit engine and balance tests pass on the stacked branch

Summary by CodeRabbit

• New Features

  • Added usage snapshot information to balance snapshots, including cumulative period usage and total grant usage.
  • Usage snapshot data is optional when complete usage-period details are unavailable.
  • Added database support for storing usage snapshots in balance records.

• Migration

  • Added upgrade and rollback support for the new usage snapshot data.

Greptile Summary

This PR introduces the persistence shape needed for complete usage-period snapshots while leaving runtime behavior unchanged.

• Adds the exported UsageSnapshot domain type and an optional pointer on balance snapshots.
• Adds the nullable immutable usage_snapshot JSONB field to the Ent schema and generated client.
• Adds the corresponding additive PostgreSQL migration and Atlas checksum.

Confidence Score: 5/5

The PR appears safe to merge as an additive schema-first change with no active runtime behavior.

The nullable column, generated Ent artifacts, positional schema references, and migration are internally consistent, while existing rows remain compatible through a nil usage snapshot.

Important Files Changed

Filename	Overview
openmeter/credit/balance/balance.go	Adds the complete usage-period snapshot shape as an optional, backward-compatible domain field.
openmeter/ent/schema/balance_snapshot.go	Declares a nullable, immutable JSONB field consistent with the schema-first rollout.
openmeter/ent/db/migrate/schema.go	Updates generated migration metadata with correctly shifted field, foreign-key, and index positions.
openmeter/ent/db/balancesnapshot.go	Adds generated scanning, unmarshalling, and model support for nullable usage snapshots.
tools/migrate/migrations/20260803135655_add_balance_snapshot_usage_snapshot.up.sql	Applies an additive nullable JSONB column without rewriting existing snapshot data.
tools/migrate/migrations/20260803135655_add_balance_snapshot_usage_snapshot.down.sql	Removes the newly introduced column when rolling back the migration.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Domain[balance.UsageSnapshot] --> Ent[Ent usage_snapshot field]
  Ent --> DB[(balance_snapshots.usage_snapshot JSONB)]
  Runtime[Follow-up runtime integration] -. deferred .-> Domain

Loading

_{Reviews (1): Last reviewed commit: "feat(credit): add usage snapshot schema" | Re-trigger Greptile}

Context used:

• Knowledge Base — Credit Grants, Balances, and Entitlements
• Knowledge Base — Data layer: ent schema, migrations, and generated client

[coderabbitai]

📝 Walkthrough

Walkthrough

The change adds an optional UsageSnapshot to balance snapshots and persists it in a nullable PostgreSQL jsonb column. The existing usage field is documented as a legacy migration representation.

Changes

Usage snapshot persistence

Layer / File(s)	Summary
Usage snapshot contract openmeter/credit/balance/balance.go	Adds UsageSnapshot with cumulative usage and total grant usage. Adds an optional UsageSnapshot field to Snapshot.
Balance snapshot storage openmeter/ent/schema/balance_snapshot.go, tools/migrate/migrations/*balance_snapshot_usage_snapshot*	Adds the immutable optional usage_snapshot JSONB field and reversible migrations. Documents usage as the legacy representation.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• openmeterio/openmeter#4846: Uses the new UsageSnapshot model and persistence field.

Suggested reviewers: turip

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the addition of the usage snapshot schema, which is the primary change in the pull request.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

✨ 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 codex/usage-snapshot-schema

---

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.}

[coderabbitai]

🧹 Nitpick comments (1)

openmeter/ent/schema/balance_snapshot.go (1)

40-42: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Add a lifecycle comment on usage_snapshot to match its sibling field.

The usage field comment (Lines 35-36) explains that it is the legacy representation during the rolling migration. The new usage_snapshot field is the destination of that migration, but it has no comment stating this role, unlike usage and unit_config. A short comment here would help future readers understand why the field is nullable now and what fills it in later.

📝 Suggested comment addition

+		// usage_snapshot stores the complete usage-period snapshot that will
+		// replace the legacy `usage` field once the rolling migration
+		// completes. Nil until populated by the resume/warmup path.
 		field.JSON("usage_snapshot", &balance.UsageSnapshot{}).Immutable().Optional().SchemaType(map[string]string{
 			dialect.Postgres: "jsonb",
 		}),

As per coding guidelines, "Comments and docstrings should explain non-obvious intent, domain constraints, lifecycle state, and failure consequences."

🤖 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 `@openmeter/ent/schema/balance_snapshot.go` around lines 40 - 42, Add a concise
lifecycle comment immediately before the usage_snapshot field declaration,
explaining that it is the destination of the rolling migration from the legacy
usage representation, is nullable during migration, and will be populated later.
Keep the field definition and its existing schema configuration unchanged.

Source: Coding guidelines

🤖 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.

Nitpick comments:
In `@openmeter/ent/schema/balance_snapshot.go`:
- Around line 40-42: Add a concise lifecycle comment immediately before the
usage_snapshot field declaration, explaining that it is the destination of the
rolling migration from the legacy usage representation, is nullable during
migration, and will be populated later. Keep the field definition and its
existing schema configuration unchanged.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 7a856668-8051-45b7-b28c-1ad4a0e151ee

📥 Commits

Reviewing files that changed from the base of the PR and between 0ba1299 and b78b4ad.

⛔ Files ignored due to path filters (9)

• openmeter/ent/db/balancesnapshot.go is excluded by !**/ent/db/**
• openmeter/ent/db/balancesnapshot/balancesnapshot.go is excluded by !**/ent/db/**
• openmeter/ent/db/balancesnapshot/where.go is excluded by !**/ent/db/**
• openmeter/ent/db/balancesnapshot_create.go is excluded by !**/ent/db/**
• openmeter/ent/db/balancesnapshot_update.go is excluded by !**/ent/db/**
• openmeter/ent/db/migrate/schema.go is excluded by !**/ent/db/**
• openmeter/ent/db/mutation.go is excluded by !**/ent/db/**
• openmeter/ent/db/runtime.go is excluded by !**/ent/db/**
• tools/migrate/migrations/atlas.sum is excluded by !**/*.sum, !**/*.sum

📒 Files selected for processing (4)

• openmeter/credit/balance/balance.go
• openmeter/ent/schema/balance_snapshot.go
• tools/migrate/migrations/20260803135655_add_balance_snapshot_usage_snapshot.down.sql
• tools/migrate/migrations/20260803135655_add_balance_snapshot_usage_snapshot.up.sql