feat(api): add the /api/v2 namespace and pricing-engine guards

[rsempe]

Context

An organization is either on the product catalog or on legacy v1 pricing, never both. The engine is an organization-level property, so it must not be a per-plan payload choice.

Description

The rule is enforced where it cannot be bypassed, as payload shape rather than blanket endpoint blocks:

• Plans::CreateService and UpdateService reject the legacy pricing fields (interval, amount_cents, pay_in_advance, charges, fixed_charges) for catalog organizations and plans with legacy_billing_disabled; everything else (name, description, currency…) stays editable, and catalog plans stay deletable.
• Charge and FixedCharge validate that their plan is not a catalog plan — the deepest layer, closing internal paths such as subscription plan overrides that no endpoint gate can see.
• The ForbidsLegacyBilling door-level 403 remains only on the pure-legacy charge, fixed-charge and charge-filter endpoints and mutations, where every action is illegal for a catalog org.
• RequiresProductCatalog gates the catalog surface on both APIs: v2 REST endpoints, catalog GraphQL mutations and resolvers (403 feature_unavailable without the flag).
• Each engine keeps its own strict GraphQL write shape, mirroring the REST v1/v2 split: CreatePlanInput/UpdatePlanInput stay unchanged for legacy, and catalog organizations get dedicated createCatalogPlan/updateCatalogPlan mutations with a catalog-only payload exposing the plan currency as currency. destroyPlan is shared. Rate cards attach to catalog plans only (legacy_plan otherwise).
• Add the /api/v2 namespace, falling back to v1 for every path it does not define, kept exhaustive by a routing parity spec, plus a v2 plans endpoint with the same catalog-only payload.
• Derive Plan#pricing_type from the organization flag and remove it from the v1 payload.

Defaulting new organizations to the catalog moves to #5871, alongside the v2 subscription surface: enabling it here would let a fresh organization create catalog plans while its subscriptions still go through the ungated v1 endpoint into a runtime that cannot bill them.

[lago-claude-ai-agent]

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

HOLD — the REST billing split is not enforced by the sibling GraphQL API.

• Neither new GraphQL guard is included by any production mutation or resolver; only synthetic concern specs use them. Catalog organizations can still execute legacy plan/charge/fixed-charge/filter/subscription mutations, while non-catalog organizations can still read and mutate catalog resources. Wire the guards into all corresponding GraphQL call sites and add real-schema coverage for both directions.

[lago-claude-ai-agent]

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

HOLD — the route set cannot load, and the billing-mode boundary still has write-path bypasses.

• Remove or rename the overlapping v2 plan fallback routes: config/routes.rb defines named v2 plan routes, then draw(:shared_api) defines api_v2_plans/api_v2_plan again, which Rails rejects as duplicate route names.
• Apply ForbidsLegacyBilling to the omitted legacy GraphQL writes (ChargeFilters::{Create,Update,Destroy} and the subscription charge, fixed-charge, and charge-filter override mutations) and cover those real mutation paths.
• Restrict v2/GraphQL plan and applied-rate-card operations to product_catalog plans; their current unscoped plan lookups allow a catalog-enabled organization to update a pre-migration legacy plan or attach rate cards to it, and the existing request setup even exercises a default legacy plan.

[lago-claude-ai-agent]

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

HOLD — legacy billing still has an unguarded GraphQL path, and false-valued legacy input bypasses catalog-plan validation.

• Apply the legacy-billing guard to the subscription-specific charge/filter GraphQL mutations (create/update/destroy filter, update charge, and update fixed charge) and cover them; their REST siblings are guarded but these remain callable.
• Detect explicitly supplied legacy plan fields by key in Plans::CreateService; pay_in_advance: false currently passes the .present? check and is stored on a product-catalog plan. Add regression coverage for this case.

[lago-claude-ai-agent]

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

HOLD — the catalog boundary is still bypassable and the v2 fallback misroutes nested plan endpoints.

• Add ForbidsLegacyBilling to the five subscription-side GraphQL pricing mutations (create/update/destroy charge filter, update charge, and update fixed charge) and cover them; unlike their REST siblings, they still mutate legacy subscription pricing for catalog-enabled organizations.
• Make native v2 plan member routes unambiguous and add nested recognition/request coverage: because :code uses /.*/ and those routes precede the fallback, paths such as GET /api/v2/plans/foo/charges and PUT /api/v2/plans/foo/charges/bar are swallowed by Api::V2::PlansController instead of reaching the v1 controllers.
• Detect supplied legacy fields by key on catalog plan creation: present? lets pay_in_advance: false through, persisting a legacy pricing value on a catalog plan. Add a regression example for this false-value case.

[lago-claude-ai-agent]

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

HOLD — legacy pricing still has a sibling write path through subscription plan overrides.

• Gate Plans::OverrideService and the units-only plan_overrides branches in subscription create/update: they bypass the new concerns and plan create/update checks, allowing legacy repricing after catalog enablement and even amount_cents on a product_catalog child plan. Add service and API regression coverage.
• Restrict the new REST and GraphQL catalog-plan show/update lookups to product-catalog plans. They currently accept a migrated organization's pre-existing legacy plans and expose/update them through the catalog surface; cover legacy IDs/codes.

[lago-claude-ai-agent]

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

PASS — The product-catalog and legacy-billing gates are consistently applied across REST, GraphQL, services, and model backstops, with focused coverage for routing parity, field translation, and attachment cleanup.

Non-blocking: the new charge and fixed-charge validation examples should follow the project's consolidated model-validation spec structure.