feat(balances): support pooled customer check and track

[johnyeocx]

Summary

• expose aggregate pooled grants through customer, entity, check, and track responses
• apply deductions and rollovers to synthetic pooled customer entitlements
• cover pooled check/track, mixed lifecycle, rollovers, usage windows, spend limits, and usage alerts

Stacked on #2347.

Validation

• bun ts (commit hook)

---

Summary by cubic

Adds pooled balance support to customer check/track, exposes aggregated pooled grants in customer/entity/check/track responses, and completes pooled lifecycle transitions across subscription updates, schedules, Stripe sync, and rollovers. Also ships invoices.insert, writable auto top-up purchase_limit.count, and plan propagation updates.

• New Features

  • Check/Track: use synthetic pooled customer entitlements for selection, deduction, and rollovers; return aggregated pooled grants in customer, entity, check, and track responses; handle lifecycle transitions across attach/update/schedules/Stripe sync.
  • Billing: add POST /v1/invoices.insert to upsert up to 500 historical invoices; available in @useautumn/sdk and autumn_sdk with docs/OpenAPI.
  • Auto top-ups: allow negative thresholds and support purchase_limit.count to set the current window’s consumed top-ups (validated on write; runtime-only).
  • Plans: remove license-link version pin; add update_license_parents to propagate license-plan updates.
  • Constraints: pooled items only on finite metered features, no usage-based pricing, and not linkable in licenses.

• Migration

  • Run DB migrations (consolidated pooled balance schema, linkage fields, index) before deploy. If you pinned a license-plan version, remove it and use update_license_parents; regenerate SDKs.

^{Written for commit c415a44. Summary will update on new commits.}

Greptile Summary

This PR adds pooled customer balances to balance checks, tracking, and customer responses. The main changes are:

• API changes: Expose aggregate pooled grants in customer, entity, check, and track responses.
• Improvements: Use synthetic pooled entitlements during balance selection and calculation.
• Bug fixes: Apply deductions and rollover updates to pooled entitlements.
• Improvements: Add coverage for pooled lifecycle changes, limits, rollovers, and alerts.

Confidence Score: 5/5

This looks safe to merge.

• No blocking issues found in the changed code.

Important Files Changed

Filename	Overview
shared/utils/cusUtils/fullCusUtils/fullCustomerToCustomerEntitlements.ts	Adds aggregate pooled entitlements and removes their underlying source entitlements from customer balance selection.
shared/utils/fullSubjectUtils/fullSubjectToCustomerEntitlements.ts	Uses synthetic pooled entitlements as deduction candidates while preserving feature and entity filters.
shared/utils/cusEntUtils/convertCusEntUtils.ts	Uses the aggregate pooled grant when calculating included usage.
shared/utils/cusEntUtils/balanceUtils.ts	Uses the pooled starting grant when calculating maximum overage.
server/src/internal/balances/utils/deductionV2/applyDeductionUpdateToFullSubject.ts	Applies deduction results to synthetic pooled entitlements in the full subject.
server/src/internal/balances/utils/deductionV2/applyRolloverUpdatesToFullSubject.ts	Applies rollover results to synthetic pooled entitlements in the full subject.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Sources[Entity pooled contributions] --> Pool[Synthetic pooled customer entitlement]
  Pool --> Read[Customer and entity responses]
  Pool --> Check[Balance check]
  Pool --> Track[Balance tracking]
  Track --> Deduct[Apply deduction]
  Track --> Rollover[Apply rollover updates]
  Deduct --> Pool
  Rollover --> Pool

Loading

_{Reviews (1): Last reviewed commit: "feat(balances): 🎸 support pooled custom..." | Re-trigger Greptile}

Context used (4)

• Context used - CLAUDE.md (source)
• Context used - AGENTS.md (source)
• Context used - server/CLAUDE.md (source)
• Context used - When generating the key changes section of the sum... (source)