Engagement date changes (Start Date / trial end) and billing

Audience: AMs / SuperAdmins. Since: #894 (Start Date), #2411 (billing realign).

An org's billing start is MAX(activation, start_date), with the trial end stacked on top (MAX(work start, trial_end_date)). Every change to start_date or trial_end_date — via the client detail PATCH, the setup-wizard invite, or finish-without-invite — is recorded in org_engagement_date_history (who, when, old → new) and triggers an automatic billing realign.

What realigns automatically

• Provider subscription not started yet (pending in Lago): moved in place.
• Provider subscription started but has never issued an invoice: terminated without an invoice and recreated at the new billing start. Fully automatic, retry-safe (sync_failed / op realign in /ops/billing if a step fails — use Retry sync).

What does NOT realign automatically — manual Lago adjustment required

• The subscription has already issued invoices, or the date moved backward (back-billing). The change is still recorded in the history table and the realign logs realign skipped … already issued invoices, but no money moves.

Manual procedure (Lago UI):

1. Confirm the change in org_engagement_date_history (old/new dates, who, why).
2. Date moved later (org was billed for days it shouldn't have been): issue a credit note on the affected invoice(s) for the overlap days (days × monthly_rate / days-in-month, the platform's calendar-day proration).
3. Date moved earlier (back-billing owed): issue a one-off invoice for the uncovered days at the same proration.
4. The subscription itself stays as-is — Lago keeps billing on the existing anchor.

This split is deliberate (#2411 decision 4, re-ratified for #894): retroactive money movement is always an explicit human act, never automated.