Replays a legacy wallet's ledger into lots and allocations, and cuts that wallet over to the allocator.

This is schema-migration step S5: a data step against the tables core schema version 9 created. It adds no DDL. Run it with mix aurora_meter.credits.migrate_lots, or call run/1 from a remote console on a release that has no Mix.

AuroraMeter.Credits.LotMigration.run(shadow: true)
AuroraMeter.Credits.LotMigration.status()

What it does, per wallet

1. Snapshot, holding no lock: read the wallet's ledger rows and fold them into a book of lots.
2. Lock: take the balance row FOR UPDATE, re-read lots_enabled_at, read any rows committed since the snapshot and fold them in.
3. Verify: compare the folded book's projection with the locked balance row's balance, held and promotional. Any mismatch, and any ambiguity the fold raised, blocks the wallet.
4. Write: insert the lots and allocations, backfill hold_transaction_id on the settle and release rows, set debt, expired and lots_enabled_at, and run the allocator's conservation check as the last statement before commit.
5. Report: one aurora_meter_checkpoints row per wallet, plus the run's own cursor row. A shadow run and a real run keep separate cursor rows, so a rehearsal can never tell the real migration that it has already covered ground it has not touched (open-findings.md X427).

Steps 2 to 5 are one transaction, so a wallet is either entirely migrated or entirely untouched. Step 1 holds no lock, so a wallet with a long history costs the live path one short lock rather than a minutes-long stall.

The balance row is the oracle

The fold reproduces the arithmetic the legacy ledger performed, and then checks itself against numbers that ledger wrote: every row's balance_after, held_after and promotional_after, and finally the balance row itself. Those figures were computed by legacy arithmetic that knew nothing about lots, so they are an independent statement of the same facts rather than the fold's own arithmetic run twice. A wallet whose replay does not reproduce them exactly is never migrated, and is never adjusted to fit.

What it never does

It never writes balance, held, promotional, currency or low_balance_threshold; it never changes any historical column except hold_transaction_id, which was null; it deletes nothing; it contacts no provider and sends no mail. With shadow: true, which is the default, the only rows it writes at all are checkpoint rows, and the only cursor it writes is its own: a shadow run cannot change where the real migration starts.

Reading a run that migrated nothing

Two opposite situations used to print the same summary of zeros. The summary now separates them, and run/1 reports both figures:

• resumed_from is the cursor the scan started after, nil if it started at the beginning of the table;
• unexamined counts wallets still on the legacy writer that this run did not look at and that no run of this mode has recorded a verdict for. It is nil when the caller named tenants explicitly.

A run with wallets: 0 and unexamined: 0 had nothing to do. A run with wallets: 0 and unexamined above zero skipped wallets that still need migrating, reports state: "skipped_by_cursor", and the Mix task exits non-zero for it.

Cutting a wallet over

A real cutover was refused while there was no lot-aware refund path: a paid refund on a cut-over wallet would have gone through reverse/4, consumed promotional lots in spend order and written nothing into reversed (open-findings.md X250). AuroraMeter.Credits.reverse_lot/4 is that path and is the gate's own condition, so from the release that carries it shadow: false is permitted and cutover_blocked/0 answers nil.

A host that still wants the refusal keeps shadow: true, which remains the default: allow_cutover: true has to be asked for explicitly on every run that writes.

Both refund paths are lot aware from repair unit R1, and that is the correction this paragraph used to need. Opening the gate on reverse_lot/4 alone left reverse/4 planning a reversal as a debit, so a host that had no payment provenance, or an aurora_meter_pro fallback that could not match one, still took promotional credit first. reverse/4 now takes the wallet's non-promotional lots in spend order and writes reversed, so a cut-over wallet is safe on either call. reverse_lot/4 remains the right one to use where the payment is known, because only it is capped by that payment's own lots.

Ordering

A row written before schema version 9 has no sound order. inserted_at comes from a wall clock that steps backwards, and seq was assigned by version 9's table rewrite in physical order rather than insertion order. So the fold trusts neither: it folds in (inserted_at, id) order and checks the result against every row's own balance_after and held_after, which form an exact chain in true commit order. If that chain does not hold it folds again in seq order. If neither reproduces the chain, the wallet's history cannot be ordered from what it carries, and the wallet is blocked.