Design a Subscription Manager

Design the object model and core APIs for a subscription-billing manager that handles plans, recurring billing cycles, mid-cycle plan changes with proration, trials, and cancellation.

Operating context. A single in-process billing engine for a software product. A plan has a name, a price, and an interval (monthly or annual); a customer holds a subscription to one plan. At each cycle boundary the engine generates a charge and hands it to an injected payment port. Customers can start on a trial, upgrade or downgrade mid-cycle (which computes a prorated credit or charge for the unused remainder), pause and resume, and cancel either immediately or at period end. A failed charge enters a dunning retry schedule before the subscription is marked past due or canceled.

Out of scope. The real payment gateway (it sits behind a port interface), tax computation, a persistence layer, dunning email delivery, multi-currency FX, and usage-metered billing.

What to produce. The class hierarchy (Plan, Subscription, BillingCycle, Charge, proration and dunning policies, a Clock, and the payment port), the public APIs each exposes, the proration math for a mid-cycle change, and the subscription state machine (trialing, active, past due, paused, canceled). Be explicit about how cycle advancement is driven by an injected clock, how charge generation stays idempotent per cycle, and how illegal state jumps are made unrepresentable.