feat(products): add rate overrides on rate phases

[rsempe]

Context

A phase can replace the card's active rate with its own pricing: the rate override.

Description

• RateOverrides::CreateService — creates the override with the same model/item/timing compatibility matrix as catalog rates; spend floors stay arrears-only; structural card fields (currency, billing timing, proration, …) are rejected with not_overridable instead of being silently dropped.
• Overrides attach through phase authoring: nested in whole-sequence replace, and per-phase create/update over REST and GraphQL (rate_override input; explicit null clears).
• Override lifecycle is transactional: replacing or clearing discards the superseded record, destroying a phase discards its override.
• REST and GraphQL expose rate_override on phases, preloaded/dataloaded.

[lago-claude-ai-agent]

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

HOLD — the new phase APIs bypass feature gating and leave rate-override lifecycle gaps.

• Add RequiresProductCatalog to all three GraphQL rate-phase mutations and cover disabled organizations; every sibling catalog mutation is gated, while these currently mutate catalog data without the flag.
• Make override replacement/clearing and phase deletion soft-discard the detached RateOverride in the same transaction (historical Fee associations already use with_discarded), and cover replacement, clearing, destroy, and failed-save rollback; UpdateService can also persist a new orphan override if rate_phase.save! fails.
• Distinguish omitted rate_phases from an explicitly empty array in PlanRateCards::CreateService; the current .present? path silently creates default and bypasses ReplaceService's mandatory-sequence validation. Add REST/GraphQL/service coverage for rate_phases: [].

[lago-claude-ai-agent]

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

HOLD — the new rate-phase APIs have feature-guard, sequence-integrity, override-lifecycle, and query-loading gaps.

• Add RequiresProductCatalog to all three GraphQL mutations and cover the disabled-catalog case; the REST endpoint and sibling catalog mutations are guarded, but these mutations remain callable.
• Normalize/cast billing_interval_cycle_count before validating phase order. REST can send "", which the current nil-only create/update checks accept before Active Record casts it to nil, allowing a non-terminal indefinite phase; add create and update coverage for this input.
• Make override replacement/removal atomic and discard superseded overrides. Update currently persists a new override before saving the phase, leaks it if the phase save fails, and leaves the previous override kept; destroy also leaves its phase's override kept. Cover replace, clear, delete, and rollback paths.
• Batch/preload rate_phases and rate_override for both transports. The REST index serializer and GraphQL collection fields currently issue per-record association queries despite the existing dataloader pattern.

[lago-claude-ai-agent]

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

HOLD — the new REST update path can silently remove pricing or return a 500 for malformed input.

• RatePhases::UpdateService#build_override treats an empty override hash as nil, so rate_override: {} (including a hash emptied by strong params) clears and discards an existing override. Only explicit null should clear it; distinguish the cases and add a regression spec.
• RatePhasesController#phase_params calls include? on params[:rate_phase] before requiring it, so a missing root parameter raises NoMethodError instead of producing the normal bad-request response. Require the parameter first and cover this case.

[lago-claude-ai-agent]

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

HOLD — several explicit REST inputs currently succeed with unintended results.

• Treat only an explicit null override as a clear: RatePhases::UpdateService#build_override conflates {} with null, so an empty REST object silently discards the existing override instead of validating its required fields. Add service/request coverage.
• Preserve the empty-sequence validation when creating an applied rate card: rate_phases: [] is treated as omitted by present? and silently creates the default phase, bypassing ReplaceService's mandatory-value failure. Cover both REST and GraphQL entry points.
• Require the rate_phase wrapper before inspecting it in phase_params; a missing wrapper currently calls include? on nil and returns a 500 instead of the normal parameter-missing response. Add request coverage.

[lago-claude-ai-agent]

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

PASS — The rate-phase REST and GraphQL paths are organization-scoped, preserve sequence invariants transactionally, roll back invalid nested overrides, and have focused service/request/mutation coverage. Generated GraphQL schemas match the new API surface, with no unrelated semantic changes or secrets found.

[lago-claude-ai-agent]

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

HOLD — malformed override input can raise, and concurrent phase edits can break sequence invariants.

• RateOverrides::CreateService forwards rate_model without enum validation before RateOverride#validate_properties calls to_sym; REST permits numeric scalar input, so rate_model: 1 raises instead of returning a validation error. Empty properties for graduated_percentage also reach the shared validator's nil.map. Validate the enum/property shape before model validation and add regression coverage.
• RatePhases::{Create,Update,Destroy}Service reads and validates siblings before entering an unlocked transaction. Concurrent edits can both pass the last/terminal checks, remove every phase or leave an indefinite nonterminal phase; concurrent inserts can instead raise RecordNotUnique. Lock the parent across the complete read/check/write sequence and cover the invariant.

[lago-claude-ai-agent]

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

Phase mutations are unsafe under concurrent requests.

• Lock the parent and reload phase/sibling state before validation and mutation in the create, update, and destroy services. As written, concurrent inserts/deletes can raise an unhandled unique-position error or use stale terminal state, while concurrent override replacements can leave an orphaned override. Add focused regression coverage for the serialized behavior.

[lago-claude-ai-agent]

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

PASS — The REST and GraphQL rate-phase operations are organization-scoped, preserve sequence and override lifecycle invariants transactionally, and have focused service, request, and mutation coverage.

[lago-claude-ai-agent]

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

HOLD — Creating a graduated_percentage override with missing ranges raises instead of returning a validation error.

• RateOverrides::CreateService accepts this rate model and calls save!, but Charges::Validators::GraduatedPercentageService#ranges calls .map on nil for {rate_model: "graduated_percentage", rate_properties: {}}, an input reachable through both new API surfaces. Make this return a validation failure and add regression coverage.

[lago-claude-ai-agent]

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

HOLD — RatePhases::UpdateService does not participate in the parent locking used by the other sequence mutations.

• Wrap the lock check, terminal-phase check, and write in parent.with_lock, with a regression spec. As written, an update that makes the current tail indefinite can race a concurrent insert and persist an indefinite non-terminal phase, violating the sequence invariant.

[lago-claude-ai-agent]

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

PASS — Rate override creation, replacement, clearing, validation, and serialization are consistently wired across REST, GraphQL, and phase lifecycle services. Focused specs cover nested creation, validation failures, rollback, and soft deletion of superseded overrides.

[lago-claude-ai-agent]

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

HOLD — an invalid graduated-percentage override can raise a 500 instead of returning validation errors.

• RateOverride#validate_properties invokes Charges::Validators::GraduatedPercentageService, whose range parsing calls .map on a missing graduated_percentage_ranges; both REST and GraphQL accept rate_properties: {}. Make this path return a validation failure and add a regression spec through the new override surface.

[lago-claude-ai-agent]

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

HOLD — concurrent override replacements can leave a kept, unattached override.

• RatePhases::UpdateService locks the parent but keeps using the phase loaded before that lock. If two requests loaded the same original override, the second update replaces the first but tries to discard only the already-discarded original. Reload the phase inside the lock before reading rate_override_id, and add a stale-instance regression test covering two serialized replacements.