Recurring credit allowances: one grant per tenant, entitlement, plan version and billing period, with a capped rollover and a bounded catch-up after downtime.

A plan declares the policy with AuroraMeter.Plans.recurring_credits/2; a plan that declares none grants nothing, which is what "recurring grants default to disabled" means. run/1 is the operation: call it from Oban (AuroraMeter.Oban.RecurringGrants), from Quantum, from a Kubernetes CronJob or from iex. It is not a process and holds no state between runs.

AuroraMeter.Credits.Recurrences.run(limit: 5_000)

What a run does

It walks entitled subscriptions in keyset order, resolves each tenant's plan, skips it immediately when the plan declares no allowance, and works out which periods each allowance still owes. Each period is its own transaction under the wallet's balance row lock, so a twelve-period catch-up is twelve short transactions and a concurrent debit interleaves between them.

Size the run so it can visit every entitled tenant at least once per period: limit: 5_000 on an hourly schedule visits 120,000 tenants a day.

Once per period, whatever the scheduler does

The guarantee is not that the job runs once. Two guards, both evaluated inside the balance row lock, make a second run a no-op:

• aurora_meter_credit_recurrences is UNIQUE (tenant_key, key), and the period's row is inserted with ON CONFLICT DO NOTHING. Zero rows back means another node has this period.
• the grant carries the period's reference, and aurora_meter_credit_transactions is UNIQUE (kind, reference).

The two are deliberately redundant because this is money. Neither is a lease and neither is a duration, so neither can be inverted by a clock that steps backwards (AuroraMeter.Clock).

Two clocks

Choosing a period is a wall-clock question ("what period is it now"), so the walk takes AuroraMeter.Clock.now/0. Every decision inside a transaction compares against a column this database stamped, so those take AuroraMeter.Clock.db_now/0. Ordering never takes a clock at all: periods are ordered by period_start, which is a boundary the period source computed, not a reading of any clock.

Rollover

rollover: n carries at most n micro-dollars of one period's unused allowance into the next, as a new lot with its own reference and its own allocation trail. Unused means what that period's lots did not spend, whether or not the expiry sweep has already destroyed it: available + expired is the same number either way, which is what makes the carry independent of whether the sweep or this engine reached the lot first.

It does not accumulate. Two idle periods with a cap of 1,000,000 leave the third holding its own allowance plus 1,000,000, never 2,000,000, because the cap applies to the whole of the previous period rather than to each of its lots.

The cap comes from the previous period's stored policy, never from the compiled plan. Raising a plan's cap does not retroactively raise what an already-issued period may carry out of itself.

Catch-up, and why a missed period is not fresh money

A tenant whose job has not run for three periods gets those three periods in chronological order, each granted and expired in the same transaction and recorded issued_and_expired, then its live period. The history is complete and nothing that was owed months ago arrives spendable today.

A tenant seen for the first time gets its current period only. Aurora Meter does not invent history it never recorded, so there is no back-pay for periods before a tenant's first recurrence row, and adopting an allowance mid-period grants the whole of that period rather than a pro-rated part of it.

Requirements and limits

• The wallet must be on the lot engine (lots_enabled_at set). A wallet the allocator does not own is skipped with reason: :lots_disabled: the allowance, the cap and the catch-up are all defined over lots, and a second, weaker implementation over the legacy projection is not one this package will carry. See docs/upgrading-to-lots.md.

  A tenant with no wallet at all is not skipped: since 0.5.0 the grant that pays the allowance is what creates the wallet, and a wallet created now is born on the allocator. This is the ordinary case for a customer who has just subscribed, and an allowance is usually the first credit a wallet ever sees.

• The storage adapter must implement AuroraMeter.Storage.list_subscriptions/2. A run that cannot list subscriptions returns {:error, {:unsupported, :list_subscriptions}}; drive it with explicit :tenant values instead.

Pausing

AuroraMeter.Operations.pause("credits_recurrences:global")

A paused run returns {:ok, %{paused: true}} and writes nothing. The pause is read before every batch, so it takes effect within one batch rather than one run.