feat(balances): describe the blocking cap on limit_reached

[charlietlamb]

Layer 5 of 6 (limit_reached). Base: #3248.

balances.limit_reached carries a usage_limit block (limit, interval, anchor, usage, remaining, window bounds) when a usage limit blocked the event, resolved from the FullSubject through the same window-limit helper the alerts use. The schema also declares the filter field the payload was already sending.

Test: limit-reached-usage-limit-block.test.ts, green locally.

Greptile Summary

The PR expands balances.limit_reached so FullSubject-backed usage-limit events describe the blocking cap and its live window.

• [Improvements, Bug fixes] Selects the tracked feature’s exhausted usage limit with the least remaining headroom and sources the filter from that same cap.
• [API changes] Adds the optional filter and usage_limit fields to the shared webhook schema.
• [Improvements] Adds integration coverage for unfiltered caps, filtered caps, and included-allowance events.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
server/src/internal/balances/trackWebhooks/checkLimitReached.ts	Connects FullSubject-backed blocking-limit resolution to the limit-reached webhook and emits the selected cap and filter together.
server/src/internal/balances/trackWebhooks/limitReached/findBlockingUsageLimit.ts	Resolves matching tracked-feature window limits, measures their current usage, and selects the exhausted cap with the least headroom.
shared/api/webhooks/balances/balancesLimitReached.ts	Declares the previously emitted filter and the new optional usage-limit details in the shared webhook contract.
server/tests/integration/balances/track/limit-reached/limit-reached-usage-limit-block.test.ts	Covers usage-limit window details, filtered-cap metadata, and omission for included-allowance events.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Track usage] --> B[Evaluate updated subject]
  B --> C{Usage limit blocked?}
  C -- No --> D[Emit limit event without usage_limit]
  C -- Yes --> E[Resolve tracked-feature window limits]
  E --> F[Select exhausted cap with least headroom]
  F --> G[Emit matching filter and usage_limit block]

Loading

_{Reviews (17): Last reviewed commit: "fix(balances): limit_reached filter alwa..." | Re-trigger Greptile}

Context used:

• Knowledge Base — Usage and billing API platform
• Knowledge Base — Webhook contracts and delivery events

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

2 Skipped Deployments

Project	Deployment	Actions	Updated
checkout	Ignored		Sep 3, 2026 5:38pm UTC
landing-page	Ignored		Sep 3, 2026 5:38pm UTC

[cubic-dev-ai]

All reported issues were addressed across 4 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>