docs(billing): document meter service as calc-agnostic

[PierreBrisorgueil]

Why

billing.meter.service.js has no downstream product knowledge by design — it only converts a USD cost map to meter units via config ratios. But this boundary was invisible, so downstream patches (per-run infra base, product floors/caps) kept landing inside the service copy on downstream repos, then getting silently wiped on the next /update-stack sync.

Root incident: a tier0 run-base floor added inside billing.meter.service.js in Trawl was lost on the next stack sync → metering zeroed for free-tier scrapes (trawl #1293 → #1316).

What

6-line note added at the top of modules/billing/README.md:

• Explains what the service does (USD cost map → units via ratios/knobs)
• Explicitly states downstream cost semantics stay in the downstream's own cost module + config
• Documents the wipe mechanism and the safe alternative (default-off config knob upstream)

Scope

Doc-only. No code change.

Summary by CodeRabbit

• Documentation
  • Clarified billing module documentation regarding module boundaries and cost configuration organization. Added detailed guidance on proper placement of cost-specific business logic within downstream systems, configuration management practices, explicit warnings about custom modifications being overwritten during platform updates, and best practices for extending functionality through configurable knobs rather than hardcoded customizations.

[coderabbitai]

Warning

Review limit reached

@PierreBrisorgueil, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 48 minutes and 15 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 47e286e0-96c3-4052-851b-62d1bf57f672

📥 Commits

Reviewing files that changed from the base of the PR and between 627d14e and 9dac4f5.

📒 Files selected for processing (1)

• modules/billing/README.md

Walkthrough

Documentation update to modules/billing/README.md clarifying that billing.meter.service.js handles unit conversion only and is cost-logic-agnostic. Added section warns that downstream-specific cost semantics belong in downstream modules, inline patches will be wiped on stack updates, and behaviors must be added as default-off config knobs.

Changes

Service Responsibility Clarification

Layer / File(s)

Summary

Service responsibility clarification modules/billing/README.md

Added "module boundary" explanation documenting that billing.meter.service.js converts feature-keyed USD costs to meter units using configuration but is intentionally cost-logic-agnostic. Downstream cost semantics (scrap/op costs, infra base, product-specific floors/caps) belong in downstream modules. Warns inline downstream patches will be removed by /update-stack and guidance to use default-off config knobs for required service-side behaviors.

🎯 1 (Trivial) | ⏱️ ~3 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically summarizes the main change: documentation of the meter service's calc-agnostic design, which aligns with the 6-line clarification added to the README.
Description check	✅ Passed	The description comprehensively covers the template requirements: explains why the change was needed (root incident from Trawl), what was added (6-line note clarifying service boundaries), and scope (doc-only). It provides clear context and purpose.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/billing-meter-calc-agnostic

---

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 and usage tips.}

[Copilot]

Pull request overview

Documents the intended module boundary for billing metering by clarifying that billing.meter.service.js is calculation-agnostic (USD cost map → meter units via config ratios/knobs), and that downstream product-specific cost semantics should live downstream rather than being patched into the upstream service (to avoid being overwritten by /update-stack).

Changes:

• Adds a short “module boundary” note to modules/billing/README.md explaining what billing.meter.service.js does and does not do.
• Explicitly documents the downstream-safe location for cost semantics and the /update-stack overwrite mechanism.
• Recommends using default-off config knobs upstream instead of hardcoded downstream rules inside the service.