[monetization] Track durable usage-based billing and plan consistency

[kang-heewon]

Priority

P0 umbrella — establish the trusted monetization path before adding a Croco-owned rating engine, credit ledger, or additional billing providers.

Context

This plan is based on trunk at 2a6e12c5c214eaa817046ebcf6b477796131609f.

Croco already has strong local domain building blocks:

• @croco/metering-core records usage, enforces quota, and supports idempotency;
• @croco/billing-core owns checkout, subscription lifecycle, plan lookup, proration seams, and invoice types;
• @croco/entitlements-core enforces feature and metered quota access;
• @croco/billing-polar owns the current production billing provider boundary;
• the SaaS preset and admin surfaces already connect or display parts of this state.

The missing path is the boundary between locally observed usage and provider-accepted billable usage. Today a usage record can be persisted and a UsageRecordedEvent can be published, but the framework does not define a durable provider-delivery contract, provider usage capability, immutable plan-version binding, or a build-time consistency check tying meters, plan pricing, subscriptions, and entitlements together.

Goal

A Croco application should be able to:

1. define a typed meter once;
2. record billable usage with a stable logical event identity;
3. durably deliver that usage to a billing provider without silent loss or duplicate charging;
4. pin each subscription to an immutable plan version;
5. ensure the same plan version owns provider product mappings and entitlement/quota rules;
6. detect unsupported or incomplete monetization wiring before deployment;
7. prove the full path through conformance and generated SaaS evidence.

Design principles

• Local usage, durable billable intent, and provider-accepted usage are separate states.
• Request handlers must not synchronously depend on a remote billing provider.
• Provider retries must be idempotent; duplicate acknowledgement is success, not failure.
• Provider capabilities must be explicit and inspectable, not optional methods with permissive fallbacks.
• Published plan versions are immutable and subscriptions remain pinned until explicitly migrated.
• Entitlement and provider pricing mappings must resolve from the same plan version.
• Reuse ContractGraph, Problem Registry, events/transaction boundaries, diagnostics, provider certification, and generated-app smoke rather than adding another control plane.
• Keep provider-rated billing as the first supported path. A Croco-owned rating engine is deferred until provider limitations justify a second source of truth.

Delivery order

Foundation

• Typed billable meter definitions and usage envelopes
• Durable billable usage journal and delivery state
• Explicit usage-billing provider capabilities
• Idempotent Polar usage event delivery

Product consistency

• Immutable plan versions pinned to subscriptions
• Plan-version-bound entitlement sets
• Monetization edges and diagnostics in ContractGraph

Executable evidence

• Usage-billing provider conformance suite
• Generated SaaS metered-overage golden path

Child issue links will be added after creation.

Foundation exit gate

Do not add a public internal rating engine until all of the following are true:

• A billable usage event survives process/provider failure after local commit.
• Replaying the same logical event cannot increase provider usage twice.
• Permanent provider rejection is visible and cannot be reported as successful delivery.
• A subscription resolves one immutable plan version and its provider mappings.
• Entitlement quota and overage policy resolve from that same version.
• An unbound billable meter or unsupported provider capability fails verification.
• The generated SaaS scenario proves provider outage, replay, duplicate acknowledgement, and final usage consistency without live credentials by default.

Explicit non-goals

• Building a general billing control plane or hosted billing service.
• Replacing Polar invoice calculation, tax, payment collection, or dunning.
• Supporting arbitrary JavaScript pricing callbacks.
• Implementing a local promotional credit ledger in this phase.
• Reopening completed admin panel or generic SaaS smoke work; this initiative should extend those existing surfaces when its read models are available.

Existing related work

• [create-croco-app] Harden the SaaS golden path into a provider-backed smoke contract #824 completed the provider-backed SaaS smoke baseline and billing-to-entitlement sync seam.
• [admin-react] Billing/entitlement admin panel을 제공한다 #1001 completed the reusable billing/entitlement admin panel baseline.

This initiative must build on those outcomes rather than duplicate them.

[kang-heewon]

Child issues and dependency order

Foundation

• [metering-core] Define typed billable meters and usage envelopes #1515 — Define typed billable meters and usage envelopes
• [metering-core] Add a durable journal for billable usage delivery #1518 — Add a durable journal for billable usage delivery
• [billing-core] Model explicit usage-billing provider capabilities #1520 — Model explicit usage-billing provider capabilities
• [billing-polar] Deliver billable usage events idempotently #1522 — Deliver billable usage events idempotently through Polar

Product consistency

• [billing-core] Pin subscriptions to immutable plan versions #1524 — Pin subscriptions to immutable plan versions
• [entitlements-core] Bind entitlement sets to billing plan versions #1525 — Bind entitlement sets to billing plan versions
• [protocols-core] Verify monetization bindings in ContractGraph #1526 — Verify monetization bindings in ContractGraph

Executable evidence

• [testing] Add usage-billing provider conformance coverage #1527 — Add usage-billing provider conformance coverage
• [create-croco-app] Prove metered overage in the SaaS golden path #1528 — Prove metered overage in the SaaS golden path

Dependency graph

#1515 typed meters
├─ #1518 durable journal
├─ #1520 provider capabilities
└─ #1524 plan versions (independent domain path)

#1518 + #1520 → #1522 Polar delivery
#1515 + #1524 → #1525 versioned entitlements
#1515 + #1520 + #1524 + #1525 → #1526 ContractGraph verification
#1518 + #1520 → #1527 provider conformance
#1518 + #1522 + #1524 + #1525 + #1526 + #1527 → #1528 generated SaaS exit evidence

The implementation should begin with #1515. #1524 can proceed in parallel once its compatibility/migration strategy is agreed. A Croco-owned rating engine remains deferred until the exit gate in this umbrella issue is satisfied.