fix(billing): clamp meter quota headroom so overflow is not double-counted (#3931)

[PierreBrisorgueil]

Problem

The meter exhaustion gate computed remaining = (meterQuota - meterUsed) + extrasBalance with no clamp on the plan-quota term. meterUsed is $inc'd uncapped past quota and the same overflow is also debited from extras, so once meterUsed > meterQuota the overflow is subtracted twice → an org is denied 402 METER_EXHAUSTED while still holding a positive extras balance (free plans block at half a pack).

Fix

Clamp the plan headroom at 0 (same clamp the reconcile service already uses): Math.max(0, meterQuota - meterUsed) + extrasBalance. Applied at both call sites — the gate (billing.quota.service.js) and the X-Meter-Remaining header (billing.attachUsageContext.js). Identical to the old formula whenever meterUsed <= meterQuota (no normal-path regression).

Test

Added the previously-uncovered case meterUsed > meterQuota && extrasBalance > 0 on both surfaces — asserts no 402 and remaining == extrasBalance.

Closes #3931

https://claude.ai/code/session_01V1mhCDsSUnn3WGtevd3YFX

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 4643f03a-5e15-4698-9da9-840d7b10c8c4

📥 Commits

Reviewing files that changed from the base of the PR and between 7916876 and b59a8e6.

📒 Files selected for processing (4)

• modules/billing/middlewares/billing.attachUsageContext.js
• modules/billing/services/billing.quota.service.js
• modules/billing/tests/billing.attachUsageContext.unit.tests.js
• modules/billing/tests/billing.quota.service.unit.tests.js

👮 Files not reviewed due to content moderation or server errors (4)

• modules/billing/services/billing.quota.service.js
• modules/billing/tests/billing.attachUsageContext.unit.tests.js
• modules/billing/tests/billing.quota.service.unit.tests.js
• modules/billing/middlewares/billing.attachUsageContext.js

---

Warning

Walkthrough skipped

File diffs could not be summarized.

✨ 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 fix/billing-meter-quota-clamp

---

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.67%. Comparing base (7916876) to head (b59a8e6).

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #3934   +/-   ##
=======================================
  Coverage   92.67%   92.67%           
=======================================
  Files         169      169           
  Lines        5546     5546           
  Branches     1782     1783    +1     
=======================================
  Hits         5140     5140           
  Misses        326      326           
  Partials       80       80           

Flag	Coverage Δ
integration	61.07% <50.00%> (ø)
unit	74.28% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

---

Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 7916876...b59a8e6. Read the comment docs.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.