billing: payment-failure dunning + 7d grace + auto-cancel (with NR dashboard + alerts)

[mastermanas805]

Summary

• What: wires the dunning state machine on the api side. Razorpay subscription.charged_failed opens a 7-day grace row; subscription.charged during grace flips it to recovered. Four new audit kinds (payment.grace_started, payment.grace_reminder, payment.grace_recovered, payment.grace_terminated) feed the Brevo email forwarder.
• Why: today's billing flow assumes the happy path. There's no in-between for a card that declines while the customer is otherwise in good standing — they discover their account is gone only when they next visit the dashboard. This PR is the trigger half of the standard SaaS dunning pattern (NOT customer-initiated cancel, which remains support-only per project rules).
• Migration 027 adds payment_grace_periods with a partial-unique index on team_id WHERE status='active'. Razorpay webhook redeliveries hit the constraint and silently no-op so customers don't get duplicate reminder emails.

What ships in this PR (api side)

• internal/db/migrations/027_payment_dunning.sql — table + two indexes (status/expires_at for worker sweeps, partial-unique team_id WHERE active for idempotency).
• internal/models/payment_grace_periods.go — Create (returns ErrPaymentGraceAlreadyActive on duplicate-active), GetActive, MarkRecovered, MarkTerminated. State transitions enforced by the application; the partial-unique index is the concurrency guard.
• internal/handlers/billing.go — extended Razorpay webhook switch: new case for subscription.charged_failed, recovery path tacked onto subscription.charged. All audit emits fail-open.
• internal/models/audit_kinds.go — 4 new constants with full docstrings.
• internal/handlers/openapi.go — webhook description updated.
• internal/testhelpers/testhelpers.go — table mirror so handler tests work without depending on the SQL-migration step.

What ships in a separate follow-up PR (worker side)

• payment_grace_reminder River job — every-30-min sweep that finds active grace rows with last_reminder_at < now() - interval '6 hours', emits payment.grace_reminder audit row (Brevo forwarder picks it up), bumps reminders_sent + last_reminder_at. Up to 28 reminders over the 7-day window.
• payment_grace_terminator River job — hourly sweep over status='active' AND expires_at < now(). Calls Razorpay subscription cancel (best-effort, log+audit on failure), soft-deletes all team resources (transactionally), emits payment.grace_terminated. This is the destructive half — kept out of api per brief.

Pushback / confirmation: the worker-side jobs are flagged as follow-ups as the brief required. Iron rule honoured — this PR only ships the trigger + grace state + recovery + reminder-emit-via-audit-kind, no destructive work.

Audit kinds + Brevo templates

Audit kind	Brevo template	Fires when
payment.grace_started	instanode-payment-grace-started-v1	api handles subscription.charged_failed
payment.grace_reminder	instanode-payment-grace-reminder-v1	worker reminder job (follow-up PR) every 6h
payment.grace_recovered	instanode-payment-grace-recovered-v1	api handles subscription.charged during active grace
payment.grace_terminated	instanode-payment-grace-terminated-v1	worker terminator job (follow-up PR) at expires_at

NR observability (same PR per memory rule)

infra/newrelic/ lives in this repo, so dashboards + alerts ship here:

• dashboards/billing-dunning.json — customers in active grace, reminders/day, recovery-rate billboard, auto-terminations/week, webhook p95 latency.
• alerts/payment-failure-spike.json — critical if >10 grace_started in 1h (Razorpay outage or webhook double-fire).
• alerts/dunning-recovery-rate-low.json — critical if 7d rolling recovery rate < 30% (unhealthy dunning UX).

bake_test.sh updated to include the new files — 42/42 schema-shape assertions green.

Test plan

• make test-unit green across all 20 packages
• 12 model tests pass (happy path, duplicate-active rejection, after-recovered-allows-new, cross-team isolation, transition immutability, redelivery idempotency)
• 6 webhook tests pass (charge_failed opens grace + emits audit, redelivery is no-op, charged-during-grace flips to recovered, charged-without-grace emits no recovery audit, cross-team isolation, fail-open audit-miss does not roll back grace row)
• TestAgentActionContract green
• bake_test.sh 42/42 NR schema assertions pass
• Worker-side reminder + terminator jobs ship in a separate follow-up PR (flagged above)

🤖 Generated with Claude Code