Subscription Ledger: Credits-First Charges With Backdated Events

You're building a simplified billing ledger for a subscription product. The ledger tracks two running numbers for an account:

• Usage balance: metered usage charges still owed.
• Subscription balance: the recurring subscription fee still owed.

Two kinds of event can hit the ledger:

• A charge event adds its amount to the usage balance.
• A credit event first reduces the usage balance, and only applies any amount left over to the subscription balance.

Part 1 — Single-event handlers

Implement the two per-event handlers below. Each takes the balances before the event and the event's amount, and returns the balances after.

from dataclasses import dataclass

@dataclass
class Balances:
    subscription_balance: int
    usage_balance: int

def apply_credit(balances: Balances, amount: int) -> Balances:
    raise NotImplementedError()

def apply_charge(balances: Balances, amount: int) -> Balances:
    raise NotImplementedError()

Part 2 — A ledger that accepts events out of order

In practice, events don't always arrive in the order they should be applied: a correction can be posted today for something that should have been recorded last week. Each event is (kind, amount, sequence), where kind is "CHARGE" or "CREDIT", and sequence is an integer giving the event's correct position in ledger history (standing in for a posting date).

Implement a Ledger class:

class Ledger:
    def __init__(self, starting_usage_balance: int = 50000, starting_subscription_balance: int = 0):
        ...

    def record(self, kind: str, amount: int, sequence: int) -> None:
        """Insert this event at its correct position in history, and recompute
        every balance that comes after it, without replaying events that
        weren't affected."""

    def current_balances(self) -> Balances:
        """Balances as of the highest sequence number recorded so far."""

Example

ledger = Ledger(starting_usage_balance=1000, starting_subscription_balance=0)
ledger.record("CHARGE", 200, sequence=10)     # usage: 1200
ledger.record("CREDIT", 150, sequence=20)     # usage: 1050
ledger.current_balances()                      # Balances(subscription_balance=0, usage_balance=1050)

# A correction arrives for a charge that should have been posted BEFORE
# the sequence=10 charge above:
ledger.record("CHARGE", 300, sequence=5)
ledger.current_balances()                      # Balances(subscription_balance=0, usage_balance=1350)

Constraints and Clarifications

• Balances and amounts are integers; amounts are always non-negative.
• The starting balances apply as of "before the lowest possible sequence number," i.e. before any recorded event.
• Up to 10^5 calls to record, and current_balances may be called frequently between them.

Clarifying Questions

• If a credit is smaller than the usage balance at that point, does it only reduce usage and leave the subscription balance untouched?
• What should happen if a credit exceeds both balances combined — should the subscription balance go negative, or should the overage be tracked separately?
• Can two events share the same sequence? If so, which is applied first?
• Is record expected to run faster than replaying the full history from scratch every time, given up to 10^5 calls?