Defines versioned plan entitlements and usage limits with atomic reservation, explicit overage behavior, upgrade/downgrade timing, reconciliation, and fail-safe handling when metering is unavailable.
Package status: reference context ready for human review. The contract and test scenarios are complete, but no claim is made that an adopting implementation has passed them.
Decision
Resolve entitlements from an immutable plan version plus account overrides, and enforce consumable limits through reservation-commit-release rather than read-then-increment. Declare fail-open or fail-closed policy per capability and risk class.
Scope
- Plan versions, features, quota periods, usage events, reservations, concurrency, overrides, plan changes, grace, UI, reconciliation, and operations.
- Count, storage, token, seat, or rate entitlements linked to subscriptions.
- Risk and test behavior under delayed billing or metering.
Outside this block
- API rate limiting for platform protection.
- Provider invoice calculation or a universal overage business model.
Contract
- Each plan version defines typed entitlements with unit, period, reset timezone, hard/soft behavior, and unlimited representation.
- Usage has a stable event identity and never decreases through deletion; corrections are explicit signed adjustments.
- A reservation atomically verifies available capacity and holds an amount before expensive work.
- Commit converts the reservation to usage; cancellation or expiry releases it exactly once.
- Upgrade, downgrade, cancellation, and payment-grace policies define their effective instant and treatment of existing reservations.
- User-visible remaining usage states measurement timestamp and may lag; enforcement uses authoritative current state.
Implementation guidance
- Keep entitlement resolution and metering APIs separate but version-compatible.
- Partition counters by account, entitlement, and period; reconcile them against the immutable event ledger.
- Use idempotency keys for reserve/commit/release and link to the triggering operation.
- Model admin overrides with reason, owner, expiry, and audit trail.
Failure handling and safeguards
- If metering is unavailable, apply the capability's explicit fail policy and bound any temporary grant.
- If a late event belongs to a closed period, record it there and adjust billing through a separate process rather than current usage.
- If reservation expiry races with commit, one atomic state transition wins and the operation receives a resolvable outcome.
Verification and operations
- Measure denied operations, soft warnings, reservation age, expired holds, ledger/counter delta, override age, metering availability, and usage near limits.
- Test boundary amounts, unlimited, period reset, concurrency, plan changes, delayed events, and partial work.
- Alert on counters below zero, usage without an event, and expired overrides.
The executable-looking examples in this package are fixtures and acceptance contracts. Run
python tools/validate.py from the collection root to check package structure and metadata; then
implement and execute the scenarios in the target repository.
Adoption assumptions
- Names and numeric values in
example.yamlare an adoption profile, not universal defaults. - The adopting team must map actors, data classes, error vocabulary, and ownership to its system.
References
- No external normative source is required; this package defines a project decision.