feat: bill contracts from billing segments

[brunomiguelpinto]

Context

#6348 produces billing segments, but nothing consumes them. BillingSegments::ProcessService has been on main for a while with no trigger: a card that comes due writes its row and stops there, and the only way to turn that row into an invoice is a console call.

Mike also lost the two endpoints he runs product-catalog QA with. /cycles and /bill only ever existed for subscriptions, on the miguel-billing-date-engine branch, and were never ported when subscriptions became contracts — so there is no way to preview what a contract will bill, or to fast-forward one, from the API.

Stacked on #6348.

Description

The consumer runs on the clock. Clock::ProcessBillingSegmentsJob fans out one BillingSegments::ProcessJob per customer holding a pending segment, mirroring the producer's shape. It is a tick of its own rather than a continuation of the producer's, because a segment is also written outside the clock and the customers who owe an invoice are not the customers whose cards came due. It runs five minutes behind the producer, so a card that comes due is invoiced in the same hour. Neither end filters by billing_at, so a segment cannot sit unread because two queries disagree on what "ready" means.

GET /api/v2/contracts/segments previews what the calendar would produce over a window without writing anything, per contract or for several through external_ids. It answers from the schedule alone: a contract that has already billed previews exactly like one that has not. That is what the new Schedule#segments_overlapping is for — unlike segments_due_by it does not resume from the stored high-water mark, because a preview must answer for the window it was asked about.

The rows are segments, not cycles: each one carries cycle_index inside it, and after a rate change a single cycle yields two rows. Naming them cycles would hide the distinction the engine is built on. It is also not billing_segments, which is reserved for the stored rows if we ever expose them.

POST /api/v2/contracts/bill runs the producer and the consumer in sequence up to end_on and returns the invoices. There is no start date: each card resumes from its own clock, so the only question a caller can answer is how far forward to go.

Billing is customer-grained, not contract-grained — the consumer groups a customer's segments into as few invoices as their contracts allow. The contracts asked for select the customers, so a customer's other contracts bill in the same run, exactly as they would on the clock. A spec pins that. Anything narrower would be a path production never takes.

ContractRateCard.due_for_billing keeps its behaviour but now sits on a new .schedulable scope — live, priced, and with a window to bill in. Being due adds the clock and the contract's status on top; the preview asks only for the first part.

Known gaps

Invoices come back without their fee lines. V1::FeeSerializer reads the fee's subscription and a v2 fee hangs off a billing segment instead, so including them raises. That is BIL-457.

A mid-cycle rate change on an advance card still splits the cycle and bills each half a whole period. The rule was settled this week — advance does not split, what is paid stays paid — but the fix is a separate change in Schedule and is not in here. This is the first PR that puts that behaviour in front of QA, so expect it to be found.

🤖 Generated with Claude Code

[lago-claude-ai-agent]

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

HOLD — three correctness gaps need fixing:

• Contracts::BillService returns the stale invoice instances created before ProcessService re-queries and finalizes them, so the new endpoint can serialize status: "generating" for a finalized or closed invoice. Reload the returned invoices and cover the response status.
• ProcessBillingSegmentsJob selects advance-metered pending segments that ProcessService deliberately excludes; those rows remain pending and cause a useless job every hour. Align the fan-out scope with the consumer and add coverage.
• PreviewService#cards uses schedulable(to), which drops a card ending during the requested window even though its earlier segments overlap the window. Select cards by window overlap and add an ended-card regression test.

[lago-claude-ai-agent]

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

HOLD — the production fan-out and preview endpoint disagree with the lifecycle rules of the code they call.

• Clock::ProcessBillingSegmentsJob#pending_customer_ids must exclude advance-metered segments just as ProcessService#pending_segments does, and cover that case. Those rows intentionally remain pending, so the current hourly scan re-enqueues their customers forever without processing anything.
• PreviewService#cards must select cards whose lifetimes overlap the full from...to window, with a regression test for an ended/replaced card. Calling schedulable(to) applies current_and_scheduled(to), which omits an ended card even when its segments overlap the requested window.
• Validate start_on/end_on before calling to_date and reject malformed or reversed windows with an API error. The current controller raises on malformed public input, and these failure paths have no coverage.