Evaluate OpenMeter Entitlements as an alternative to Subscription Discounts for trial credits

Nobody has claimed this yet.

## Summary

The current bootstrap (see #25, delivered by PR #39 / PR #53) gives new users a free trial of the service using an OpenMeter **Subscription Discount** applied to the default pay-per-use plan. This issue tracks evaluating whether **Entitlements** should be used instead (or in addition), and documenting the benefits/tradeoffs of each approach so we can make a deliberate choice.

**This is out of scope for the current milestone/project** — it is filed to track the decision, not to block delivery. Subscription Discounts remain the chosen approach for the trial.

## Background: OpenMeter has three distinct "Credit" concepts

1. **Subscription Discounts** — a discount toward a plan that recurs monthly. This is what the bootstrap uses today to give users a free trial.
2. **Grant Credits** — real money applied to an account that can be used to settle an invoice (tracked separately in #68).
3. **Entitlements** — an advanced feature of Plans, used for dynamic pricing or rate limiting.

The initial bootstrap scripts merged via #25 only cover **Subscription Discounts**, which is the proper approach for a simple free trial. Entitlements could alternatively be used, but that is a larger design change and out of scope for now.

## Benefits / tradeoffs to evaluate

| Dimension | Subscription Discount (current) | Entitlements (proposed alternative) |
|---|---|---|
| Primary purpose | Reduce the invoice amount for a plan | Grant/limit access to a metered feature (allowance, rate limit) |
| Trial modeling | "First $X (or N%) off, recurring monthly" | "N units of feature X per period", resets per grant/period |
| Recurrence | Recurs monthly with the subscription | Per-grant / per-entitlement period; supports rollover, reset, priority |
| Rate limiting | Not supported | Supported (can gate/limit usage in real time) |
| Dynamic pricing | Limited | Supported (feature-based) |
| Balance/consumption visibility | Discount applied at invoice time | Real-time balance API (`grantUserAllowance`, balance queries) — fits a live balance gate |
| Idempotency | Per subscription | Per user/reason grant (easier to make idempotent per first-auth) |
| Complexity to bootstrap | Low (already implemented) | Higher (features + entitlements + grants per customer) |
| Fit with current flow | Trial visible only on invoice | Aligns with the identity-webhook balance gate (`insufficient_balance` / `483`, `trial_credits_exhausted`) |

## Tasks

- [ ] Document the concrete OpenMeter/Konnect API differences between Subscription Discounts and Entitlements for trial modeling.
- [ ] Prototype granting a trial allowance via Entitlements (`grantUserAllowance`) and compare against the current subscription-discount trial.
- [ ] Assess how each approach interacts with the identity-webhook balance gate (`483 insufficient_balance`, `trial_credits_exhausted`) and the collector's metered usage.
- [ ] Recommend an approach (keep Subscription Discounts, switch to Entitlements, or combine) with rationale.

## Acceptance

- A written comparison of Subscription Discounts vs Entitlements for the trial-credit use case, with a clear recommendation.

## References

- #25 — Port OpenMeter/Konnect meter bootstrap scripts (delivered by PR #39, PR #53)
- `openmeter-collector/provision/catalog.json`, `openmeter-collector/provision/bootstrap.sh`
- SDK README "Allowances (OpenMeter)"

Start with openmeter-collector/provision/catalog.json and bootstrap.sh, then read the SDK README section “Allowances (OpenMeter)” and the referenced identity-webhook behavior. Compare Subscription Discounts with an Entitlements prototype using grantUserAllowance, including collector usage and the 483/trial_credits_exhausted gate. Done means a written comparison with a clear recommendation.

Written by the indexing model from the issue text.