fix(past-usage): include free-tier units

[toommz]

Context

Past usage excluded unbilled free-tier units from regrouped advance-charge periods. This caused historical usage to under-report consumption even though the units were correctly retained on the subscription and did not affect invoice amounts.

Description

Update past usage queries to include eligible unbilled free advance fees from the matching billing period, while preventing duplicate counting across regrouped and regular invoices. Preserve billable metric, subscription, organization, charge, timestamp, and pagination filtering behavior.

[lago-claude-ai-agent]

Automated pre-review (advisory, not a required check) — verdict: HOLD · CI green

HOLD — the new lookup adds an unconditional query fan-out to every past-usage request.

• Batch the free-fee and owner-period resolution. free_usage_period? performs one query per returned invoice subscription and the winning record performs another free_fees query even when no qualifying fee exists; a default 100-row page can therefore add about 200 queries, while each JSON-boundary lookup repeatedly filters the subscription’s accumulated unbilled fees.

[lago-claude-ai-agent]

Automated pre-review (advisory, not a required check) — verdict: HOLD · CI green

HOLD — free_usage_period_ids can assign standalone free fees to the voided invoice after regeneration: regenerated invoice subscriptions copy the same reason and boundaries, while oldest-first ordering selects the superseded row. Exclude superseded invoice subscriptions (regenerated_invoice_id: nil) and add regeneration coverage proving the active regenerated period receives the free usage.

[lago-claude-ai-agent]

Automated pre-review (advisory, not a required check) — verdict: HOLD · CI green

HOLD: Free-tier units are still lost when paid advance fees are regrouped after their usage period.

• PastUsageQuery#free_fees matches standalone fees to InvoiceSubscription boundaries, but AdvanceChargesService intentionally puts late-paid fees from older periods on an invoice stamped with the current period (covered by advance_charges_dates_spec.rb). In that supported flow, the paid and free fees never reunite. Handle delayed regrouping and add a regression proving the complete units are returned together.

[lago-claude-ai-agent]

Automated pre-review (advisory, not a required check) — verdict: PASS · CI green

PASS — The standalone free-fee lookup is narrowly scoped, preserves invoice totals, and assigns usage consistently across regular, advance, regenerated, terminated, filtered, and paginated periods. Focused query specs and end-to-end request scenarios cover the new behavior and key exclusion cases.