Deletes the operational rows that are genuinely disposable, and nothing else.

Aurora Meter keeps financial history for ever. Events, event totals, the credit ledger, subscriptions and the cursors every sweep resumes from are never deleted by anything in this package, at any age, under any option. What grows without bound and is genuinely disposable is a much shorter list, and this module is that list plus the proof that each entry is safe to remove.

AuroraMeter.Retention.plan([])
#=> {:ok, %{flush_receipts: 4_182_000, replay_checkpoints: 3}}

AuroraMeter.Retention.prune([])
#=> {:ok, %{flush_receipts: 50_000, replay_checkpoints: 3}}

plan/1 is a dry run: it runs the prune's own predicate with count(*) instead of a DELETE and writes nothing at all.

The allow list is closed, and it is compile time

There is no option, no configuration key and no argument that adds a table to it. :only narrows the list; it can never widen it, which is why it is named :only rather than :tables. A name that is not an allow-list key raises ArgumentError and the message lists the two that are.

Age alone never authorises a deletion. Every entry has an age predicate and a state predicate, because "this row is old" and "this row can no longer affect anything" are different statements and only the second is a reason to delete.

Why a flush receipt is the dangerous one

AuroraMeter.Storage.Ecto.flush_batch/3 inserts the batch's receipt with on_conflict: :nothing and applies the counter deltas only when that insert reported one new row. That single inserted == 1 is the whole of invariant I01. Delete a receipt while a node still holds the batch in ETS, let that node retry, and the deltas are added a second time: a double count of real usage, in money.

So a receipt is deleted only when age and a cluster-wide liveness proof agree. Every node's AuroraMeter.Flusher writes a "flush:<node>" row into aurora_meter_checkpoints: "idle" after a batch commits, "pending" with the batch's snapshot_at after one fails, and "idle" on a throttled tick when there is nothing to send. prune/1 refuses to touch receipts unless every one of those rows says either "idle, and I said so after the cutoff" or "pending, with a batch taken after the cutoff".

Three refusals are deliberately stricter than "check the rows that are there":

• no rows at all refuses, when there is a receipt older than the cutoff. A fleet that has not yet been upgraded writes no heartbeats, and "nobody is reporting" is not evidence that nobody is holding a batch.
• a missing aurora_meter_checkpoints table refuses, for the same reason: it is a database below core schema version 7 and it has receipts.
• an unparseable pending_since refuses rather than being ignored.

A node that is genuinely gone is cleared with forget_node/1, deliberately and one node at a time. That is the only override, and it overrides the rule for one node rather than removing the rule.

Clocks, and the bound this module relies on

AuroraMeter.Checkpoints' documentation says the heartbeat is not a lease and that nothing in this package subtracts it from anything, because open-findings.md X100 measured clock_timestamp() stepping backwards nine times in 300 seconds, worst 439 ms. This module does subtract it from something, so the distinction has to be exact rather than implied.

That rule is about exclusion at seconds scale: deciding that a runner is gone so that its work may be taken. No N a person would pick survives a 439 ms step there, and the sound mechanism has no clock in it at all (AuroraMeter.Checkpoints.claim/3).

This decision is a different one. The smallest window it will act on is one day, refused below that at boot (AuroraMeter.Config), which is about 200,000 times the measured backwards step of the shared clock and about 30,000 times the worst measured step of a node's own (2.6472 s, X59). For the answer to flip, a row would have to sit within a few seconds of a cutoff a day or more wide, and the row that then loses its protection is one whose node was reporting idle at almost exactly the cutoff instant, so the batch it could retry is itself within seconds of the cutoff. The durations rule in architecture-map.md section 3 says exactly this: unsafe at seconds, safe at minutes and hours. A day is neither of the cases it warns about.

One of the three stamps is the database's own: aurora_meter_checkpoints' updated_at is written with clock_timestamp() in the statement, so the staleness half of the receipt rule compares two readings of one clock and the 439 ms figure is the whole of its error.

The other two are a node's wall clock, and they are named rather than glossed. aurora_meter_flush_receipts.inserted_at is stamped by the node that flushed (AuroraMeter.Storage.Ecto.flush_batch/3, which says why it is not the database's), and the heartbeat's pending_since is when a node took a batch out of its own ETS, which has no database in it by design and must not acquire one on the flush path. For either of those to produce a wrong answer, a node's clock would have to disagree with the database's by more than the whole window, which at the one day floor is 288 times the largest disagreement anything else in this system tolerates: events_future_tolerance refuses an event 300 seconds ahead, and Stripe's webhook signature window is the same 300 seconds. A fleet whose clocks are a day apart has already stopped being able to record events or accept webhooks. That is the bound, and it is stated rather than assumed.

Sizing, and what to do before the first prune

A node under continuous traffic writes one receipt per flush_interval, which at the 5,000 ms default is 17,280 rows per node per day. See Retention for the measured table and index sizes, the archive guidance, and the order to do an upgrade in: deploy, let every node write a heartbeat, confirm them with status/0, and only then schedule the worker.

Running it

AuroraMeter.Oban.Retention is the optional worker. Nothing runs without a host scheduling it, and a host that schedules nothing keeps every row for ever, which is what task 03.09 means by "retained indefinitely".