[Backend] — Market Settlement State Machine Validation

[Olowodarey]

Problem
markets settlement transitions aren't guarded, so a market can move to an invalid settlement state.

Requirements

• Enforce allowed settlement transitions (open → closed → resolving → settled/cancelled).
• Reject illegal transitions with a descriptive error.
• Tests: each valid transition allowed; illegal ones rejected.

Acceptance Criteria

• Market settlement follows a validated lifecycle. Covered by tests.

Files

• backend/src/markets/markets.service.ts
• backend/src/markets/entities
• backend/src/migrations/1776700000000-AddMarketSettlementState.ts

[bilhokista]

I have opened #1791 for this issue.

Two things worth raising before review:

On the state names. The issue describes the lifecycle as open → closed → resolving → settled/cancelled, but the enum in the codebase (MarketSettlementState) is pending → proposed → settling → settled, with proposed → challenged → settled when a challenge is raised. I implemented the lifecycle that exists, since renaming the states would mean a migration and a breaking API change rather than the guard the issue asks for. If the names in the issue were the intended target rather than shorthand, I am glad to redo the PR against them.

On what was missing. The transitions were in fact already guarded, but in four separate hand-written places: three settlement_state !== X checks in markets.service.ts and a fourth as an inline eligibility predicate in market-settlement.scheduler.ts. Each was correct, but nothing tied them together and no test stated the rules. The PR introduces a single transition table that all four now consult, with a rejection message that names both states and lists what would have been allowed instead.

Exception types are unchanged so the existing service specs still hold; only the message text is richer. Tests cover all 25 state pairs — the 6 valid transitions and the 19 illegal ones — plus a check that every enum member has a table entry, so a new state cannot be silently forgotten.

Happy to adjust the scope or the naming to your preference.