Validate a selection and decide the completion path

Checks a customer's chosen Product Versions and answers whether they can be submitted and by which path. This is the authoritative Checkout-vs-Handoff decision: the automated-switch signal lives in the catalogue, so it cannot be derived client-side.

A selection that breaks a rule is a valid answer, not a bad request — it returns 200 with valid: false and every reason under issues. A 4xx means the request itself was malformed.

A Product Version is published for one month, so the catalogue month is read off the ids you send rather than asked for — there is no month parameter, and no way for it to disagree with the selection. That is what keeps this endpoint aligned with POST /v1/comparisons: the versions validated here are the ones the customer was shown, including in the first days of a month before the catalogue is refreshed.

Judged against the catalogue month Vwala is currently serving, not against today's date. Refreshing every product for a new month takes days, so for much of the first week of a month the catalogue being served is still the previous one — and that is the catalogue the customer is choosing from.

Two things can make a selection too old, both reported per fuel so a client knows which half to re-run. PRODUCT_VERSION_SUPERSEDED means a newer version of that product is now being served: the price on screen has moved, and the customer should compare again rather than switch at it. A newer version that exists but is not yet being served supersedes nothing — nobody is being shown it. COMPARISON_MONTH_OUT_OF_RANGE means the version is more than a month away from the served catalogue with nothing newer behind it, which in practice means a discontinued product.

What is not an error: fuels sitting in different months, and a version that is simply the newest one there is. The refresh does not land for all fuels at once, so this month's electricity beside last month's gas is exactly what a customer may have been shown — and next month's prices, often loaded before the month turns over, do not supersede today's.