feat(shared): usage alert basis and filter

[charlietlamb]

Layer 1 of 6 (schema). Stack: #3246 → #3247 → #3259 → #3248 → #3249 → #3250.

Usage alerts gain basis (what 100% means) and an optional filter that points a usage_limit alert at the usage limit sharing its feature and filter.

basis	denominator
balance (default, unchanged)	every grant on the feature
included	plan allowance only
recurring	grants that reset
usage_limit	the matching usage limit's cap, measured on its window counter

• filter is only valid with basis: usage_limit.
• Alerts dedup on (feature_id, basis, filter, threshold_type, threshold) on customer, entity and plan controls. Entity usage limits now dedup by filter as customers already did.
• Org config rejects basis: usage_limit (there is no single cap to measure).
• PlanBillingControlsParamsSchema requires a plan's usage_limit alerts to match a usage limit on the same plan.
• basis is stored explicitly with a balance default; existing tests that compare stored alerts by equality add it.

No behaviour change to firing yet; that lands in #3248.

---

Summary by cubic

Usage alerts now support an explicit basis (balance, included, recurring, or usage_limit) and an optional filter that selects a matching usage limit. Previously all alerts used balance implicitly; this adds schema and validation only, so non-balance bases don't change alert firing yet.

Validation

• filter is only valid with basis: "usage_limit", which also requires a feature_id; org alerts reject that basis, and plan alerts must resolve to a usage limit on the same plan.
• Alerts deduplicate by (feature_id, basis, filter, threshold_type, threshold) across customer, entity, and plan controls; usage limits deduplicate by (feature_id, filter).
• Controls that deduplicate only by feature_id skip entries without one.
• Plan creation validates usage-limit alerts against the submitted usage limits; plan updates validate against the merged plan row, so sparse patches that omit existing limits stay valid.
• Existing alerts default to basis: "balance", so no migration is needed.

Known issue

• Distinct valid filters can collide when a property value contains & or =, which can reject valid controls or resolve an alert against the wrong usage limit.

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

Greptile Summary

Adds schema and validation support for selecting how usage-alert percentages are measured and optionally targeting a filtered usage limit.

• API changes: Adds balance, included, recurring, and usage_limit alert bases, with balance as the default.
• API changes, Improvements: Validates filter usage, rejects unsupported organization-level usage-limit alerts, and requires plan alerts to match a plan usage limit.
• Improvements: Extends duplicate detection across usage alerts and filtered usage limits for customer, entity, and plan controls.
• Improvements: Updates shared exports, declarative plan types, and tests for the new stored alert shape.

Confidence Score: 5/5

The PR appears safe to merge because no blocking failure remains within the scope of this follow-up review.

No blocking failure remains.

Important Files Changed

Filename	Overview
shared/models/cusModels/billingControls/usageAlert.ts	Adds alert basis and filter schemas, defaults balance behavior, and validates usage-limit-specific requirements.
shared/api/billingControls/planBillingControls.ts	Adds plan-create validation requiring usage-limit-based alerts to resolve to a matching usage limit.
shared/models/cusModels/billingControls/duplicates/duplicateChecks.ts	Centralizes duplicate validation and includes basis, filter, threshold type, and threshold in usage-alert identity.
shared/utils/billingControlUtils/filterUnresolvableUsageLimitAlerts.ts	Identifies usage-limit-based alerts that lack a matching feature-and-filter limit.
shared/models/orgModels/orgConfig.ts	Rejects usage-limit-based alerts at organization scope, where no single matching cap exists.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Usage alert input] --> B{Select basis}
  B -->|balance, included, recurring| C[Validate alert fields]
  B -->|usage_limit| D[Require feature ID]
  D --> E[Match feature and filter to plan usage limit]
  C --> F[Check duplicate identity]
  E --> F
  F --> G[Store alert with explicit basis]

Loading

_{Reviews (9): Last reviewed commit: "refactor(shared): usage_limit alerts req..." | Re-trigger Greptile}

Context used:

• Knowledge Base — Usage and billing API platform
• Knowledge Base — Catalog and entitlement management

[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

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

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 10 files (changes from recent commits).

<sub>Requires human review: Auto-approval blocked because this review re-detected 1 unresolved issue already reported by Cubic.
Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 19 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 4 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 2 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

1 issue found across 9 files (changes from recent commits).

Confidence score: 5/5

• In shared/api/billingControls/planBillingControls.ts, the comment references a nonexistent handleUsageLimitAlertErrors guard, which could mislead maintainers about where usage-limit alert validation occurs; document only this schema’s create-time validation or remove the reference.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="shared/api/billingControls/planBillingControls.ts">

<violation number="1" location="shared/api/billingControls/planBillingControls.ts:31">
P3: This comment references a nonexistent `handleUsageLimitAlertErrors` guard, so it misleads maintainers about where catalog updates validate usage-limit alerts. Document only this schema's create-time validation, or reference the actual update validation mechanism.</violation>
</file>

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

1 issue found across 21 files (changes from recent commits).

Confidence score: 3/5

• In shared/models/cusModels/billingControls/identity/usageLimitIdentity.ts, accepted filter keys or values containing =, &, or | can produce identical identities for distinct limits, causing deduplication or alerts to use the wrong cap; preserve a reversible shared encoding or reject these delimiters.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="shared/models/cusModels/billingControls/identity/usageLimitIdentity.ts">

<violation number="1" location="shared/models/cusModels/billingControls/identity/usageLimitIdentity.ts:6">
P1: When an accepted filter key or value contains `=`, `&`, or `|`, this identity is not injective. Distinct limits can be deduplicated or an alert can match the wrong cap; preserve a reversible shared encoding or reject delimiter characters before using this key for identity.</violation>
</file>

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>