feat(lit-payments): auto-send the monthly enterprise invoice

[clawdbot-glitch003]

Context

The July 2026 Uneven Labs invoice run surfaced a Stripe key permission gap (fixed out-of-band); once unblocked, the draft + review-email flow worked end-to-end. We're now comfortable dropping the human-in-the-loop send step, which the code was already built for: enterprise_accounts.auto_send existed (default false, "flip to true to finalize+send automatically (future)") and finalize_and_send was sitting unused in lit-billing-core.

Changes

• billing.rs: after the draft-invoice and buffer-regrant steps, auto_send accounts get finalize_and_send (Stripe finalizes and emails the invoice to the customer, net-30) followed by an FYI email to notify_email, and the row is marked sent. Manual accounts keep the existing draft + review-email path.
  • The finalize call uses idempotency key ent_send:{account}:{period} and the same 23h retry-age guard as the create/regrant steps: past the window it refuses and surfaces for a human instead of guessing whether the customer was already emailed.
  • Anomaly hold: a 0-unit cycle (metering identity suspect — external credit or usage stopped) is always held as a draft for review, even with auto_send on. The review email says so explicitly.
• email.rs: the review email and new sent-FYI email share one breakdown body; only the subject, lead line, and CTA differ. Review copy is unchanged.
• db.rs: set_invoice_sent (status sent + notified_at); sent was already a valid status in the check constraint.
• migration: flips Uneven Labs to auto_send = true.
• Doc updates in lit-billing-core/invoice.rs and types.rs to stop calling this "future".

Behavior notes

• Failure ordering is unchanged: any step failing leaves the row pending and the hourly tick resumes it, with each Stripe side effect deduped inside the idempotency window and refused past it.
• If the FYI email fails after finalize succeeds, the next tick replays finalize (deduped) and retries the email — worst case is a duplicate internal FYI, same as the existing draft-flow behavior.
• Rows already in draft (e.g. July 2026) stay terminal — they still need a manual send in the dashboard.

Testing

• cargo clippy --all-targets: no warnings in touched files.
• cargo test (lit-payments): 120 passed.
• First live exercise will be the 2026-08-17 anchor tick.

🤖 Generated with Claude Code

Adversarial review fixes (2nd commit)

A Codex adversarial review flagged 6 issues; 4 were addressed here (the other 2 — duplicate internal FYI emails under multi-instance overlap, and the by-design past-window human hand-off — are accepted as low-risk/pre-existing):

1. Finalize ≠ send: finalize_and_send now explicitly POSTs invoices/{id}/send after finalize (separate idempotency keys). Finalization alone only emails the customer if the Stripe dashboard's "email finalized invoices" setting is on — otherwise the DB would say sent while the customer never received the invoice.
2. Drained-buffer hold: auto-send is also held when consumed >= target_credit_cents (calc::hold_for_review, unit-tested). Since consumed = target + balance, that reading means the payer balance went zero/positive mid-cycle and the overage figure is unreliable — previously this exact case was logged as "verify before the invoice is sent" but would have been auto-sent anyway. The review email explains the hold.
3. Durable finalize marker: new finalized_at column, written after Stripe confirms finalize+send and before the FYI email. A crash between them now resumes at the email step instead of replaying Stripe calls (whose idempotency keys expire after ~24h).
4. Stricter missed-cycle guard: the previous period's row must be in a resolved status (draft/sent/paid/manual), not merely exist — an error/pending prior cycle now blocks auto-billing the next one.

Note on the migration-flips-in-flight-rows concern: verified in prod that the only existing rows are terminal (manual, draft), so the flag flip resumes nothing retroactively.