Trade Status State Machine

The trade status is the operational state of a trade at a given moment. It answers the question: what state is this trade in right now?

Status drives:

• Whether a trade is included in risk and P&L calculations (only live trades).
• What operations are permissible on the trade.
• Reporting and reconciliation filters.

The activity type classifies the event that created or changed a trade record. It answers the question: why does this trade record exist, and what kind of change does it represent?

Activity type drives:

• P&L attribution: which P&L bucket did this change fall into?
• Trade activity reporting: how is the day's activity broken down?
• Confirmation workflow: does this activity require a new legal confirmation?
• Audit and reconciliation.

Activity types are grouped into four categories: New Activity, Life-Cycle Event, Misbooking, and Valuation Change.

     ┌─────────────────────────────────────────────────────┐
     │              TRADE STATUS STATE MACHINE              │
     └─────────────────────────────────────────────────────┘

             (initial)
                 │
             Book│
                 ▼
          ┌─────────────┐
          │     NEW      │  ◀──── New Activity events
          │  (initial)   │         (require confirmation)
          └──────┬──────┘
   Cancel │      │ Confirm
          │      ▼
     ┌────▼   ┌─────────────┐
     │        │    LIVE      │  ◀──── Life-Cycle Events
     │        │  (active)    │         (in-terms changes)
     │        └──────┬──────┘
     │  Cancel/      │ Expire/
     │  Terminate    │ Mature/
     │               │ Exercise
     ▼               ▼
┌──────────┐  ┌──────────────┐
│CANCELLED │  │   EXPIRED    │
│(terminal)│  │  (terminal)  │
└──────────┘  └──────────────┘

When a trade's terms are amended (e.g. Restructure, Novation, Upsize), ORE Studio does not create a new trade record. Instead, it uses temporal versioning:

• The existing trade row's valid_to is set to the current timestamp.
• A new row is inserted with the same id, valid_from set to now, and valid_to set to infinity.
• The new temporal version carries status new, pending re-confirmation of the amended terms.
• On confirmation, the status transitions to live.

This preserves the full amendment history of the trade under a single id.

trade_id = X
─────────────────────────────────────────────────────────────────
 valid_from    valid_to       status   terms
─────────────────────────────────────────────────────────────────
 2026-01-10    2026-03-01     live     notional=10M
 2026-03-01    ∞              new      notional=15M   ◀ upsize
─────────────────────────────────────────────────────────────────

The successor_trade_id field is used exclusively for cancel and rebook scenarios, where a trade is cancelled and an entirely new trade is created to replace it. This is distinct from a normal amendment:

• The original trade is moved to cancelled status.
• A new trade with a fresh id is created (entering new status).
• The new trade's successor_trade_id is set to the original trade's id for traceability.

Use cases: Misbooking correction, administrative re-booking.

A misbooking creates a correction trade with successor_trade_id pointing to the erroneous original:

1. Original erroneous trade: status → cancelled.
2. Correction trade created: fresh id, successor_trade_id = original id.
3. Correction trade status begins at new; moves to live on confirmation.

New Activity events require legal confirmation. They produce a trade record in new status that must transition to live via confirmation.

Life-Cycle Events are changes to the value of the trade specific to the terms of the original contract. No legal confirmation is required.

A misbooking is a change to a trade due to an error in the booking terms of the original contract.

Valuation Changes are changes to the value of a trade that are not specific to the terms of the contract. They represent changes in analytics, models, or static data inputs. No confirmation is required. These are treated as amendments — they do not change the trade's operational status.

The trade status machine is seeded in ores_dq_fsm_machines_tbl under the name trade_status with four states and five transitions as described above.

The ores_trading_trades_tbl carries a status_id column (soft foreign key to ores_dq_fsm_states_tbl) representing the trade's current status.

The full set of activity types is stored in ores_trading_activity_types_tbl (replaces the narrower ores_trading_lifecycle_events_tbl). Each activity type record includes:

• code: unique identifier (e.g. novation, rate_reset).
• category: one of new_activity, lifecycle_event, misbooking, valuation_change, cancellation.
• requires_confirmation: boolean.
• fsm_transition_id: optional reference to the triggered FSM transition (null for no-status-change activities).
• description: human-readable description.

Before a trade status transition is applied, the server validates it against the ores_dq_fsm_transitions_tbl to confirm the (from_state, to_state) pair is legal for the trade_status machine. Invalid transitions are rejected with an error response.