Centaur_Quant_Architecture/MQL5/Include/Network/CSDPEncoder.mqh

//+------------------------------------------------------------------+
//|                                                     CSDPEncoder.mqh |
//|                 Centaur Quant Architecture — Network Module        |
//|            Standardized Data Protocol (SDP) JSON Serializer        |
//+------------------------------------------------------------------+
//|  PURPOSE                                                          |
//|  Single source of truth for formatting every outgoing JSON        |
//|  payload from the MT5 EA. Enforces the SDP envelope schema,       |
//|  dot-decimal number formatting, JSON string escaping, and         |
//|  ISO-8601 UTC timestamps. Raw JSON building is FORBIDDEN          |
//|  anywhere else in the MQL5 codebase.                              |
//+------------------------------------------------------------------+
#property strict

#ifndef CSDPENCODER_MQH
#define CSDPENCODER_MQH

//--- SDP action types. Wire names are stable contracts for the Python router. ---
enum ENUM_SDP_ACTION
  {
   SDP_ACTION_HEARTBEAT      = 0, // Heartbeat
   SDP_ACTION_TICK_HARVEST   = 1, // Tick_Harvest
   SDP_ACTION_SETUP_DETECTED = 2, // Setup_Detected
   SDP_ACTION_TRADE_OPENED   = 3, // Trade_Opened
   SDP_ACTION_TRADE_CLOSED   = 4  // Trade_Closed
  };

//+------------------------------------------------------------------+
//|                                                                  |
//+------------------------------------------------------------------+
class CSDPEncoder
  {
private:
   string            m_sdp_version;   // wire SDP protocol version carried by every envelope

   //--- wire name of an action (single source of truth for the enum) ---
   string            ActionToString(const ENUM_SDP_ACTION action);

   //--- ISO-8601 UTC "2026-08-12T09:20:00.000Z" from any datetime ---
   string            IsoTimestamp(const datetime t);
   string            IsoTimestampUTC();   // convenience: uses TimeGMT()

   //--- JSON-safe string escaping (" \ \n \r \t + control chars) ---
   string            EscapeJson(const string value);

   //--- dot-decimal number formatting; never locale-dependent ---
   string            FormatDouble(const double value, const int digits);

   //--- wire name of an ENUM_TIMEFRAMES value (e.g., PERIOD_M15 -> "M15") ---
   string            PeriodName(const ENUM_TIMEFRAMES period);

   //--- resolve empty timeframe to the current chart period ---
   string            ResolveTimeframe(const string timeframe);

   //--- live digits of a symbol; 8 as a neutral formatting fallback ---
   int               SymbolDigits(const string symbol);

   //--- clamp confidence into [0.0, 100.0]; logs on out-of-range/NaN ---
   double            ClampConfidence(const double confidence);

   //--- assemble the full SDP envelope around a prebuilt payload object ---
   string            BuildEnvelope(const ENUM_SDP_ACTION action,
                        const string symbol,
                        const string timeframe,
                        const double confidence,
                        const string payload_json,
                        const string historical_context_json = "");

public:
                     CSDPEncoder();

   //--- SDP protocol version embedded in every envelope ---
   string            Version() const { return m_sdp_version; }

   //--- action-specific serializers; each returns "" on invalid input ---
   string            EncodeHeartbeat(const string symbol, const string timeframe);

   string            EncodeTickHarvest(const string symbol, const string timeframe,
                            const double bid, const double ask,
                            const datetime tick_time, const long tick_volume);

   string            EncodeSetup(const string symbol, const string timeframe,
                      const string setup_type,
                      const double entry, const double sl, const double tp,
                      const double confidence,
                      const string historical_context_json = "");

   string            EncodeTradeOpened(const string symbol, const string timeframe,
                            const ulong ticket, const ENUM_POSITION_TYPE side,
                            const double lot, const double entry_price,
                            const double sl, const double tp,
                            const double confidence,
                            const string historical_context_json = "");

   string            EncodeTradeClosed(const string symbol, const ulong ticket,
                            const double profit, const double r_multiple,
                            const double initial_ai_score,
                            const string timeframe = "");

   //--- charter-required historical context array serializer ---
   string            BuildHistoricalContext(const string symbol,
                                 const double &swing_high[],
                                 const double &swing_low[],
                                 const datetime &swing_time[]);
  };
//+------------------------------------------------------------------+
//| Constructor — fix the ratified wire version of the SDP protocol.  |
//+------------------------------------------------------------------+
CSDPEncoder::CSDPEncoder()
   : m_sdp_version("1.0.0")
  {
  }
//+------------------------------------------------------------------+
//| ActionToString — maps the enum to its stable wire string.         |
//+------------------------------------------------------------------+
string CSDPEncoder::ActionToString(const ENUM_SDP_ACTION action)
  {
   switch(action)
     {
      case SDP_ACTION_HEARTBEAT:
         return "Heartbeat";
      case SDP_ACTION_TICK_HARVEST:
         return "Tick_Harvest";
      case SDP_ACTION_SETUP_DETECTED:
         return "Setup_Detected";
      case SDP_ACTION_TRADE_OPENED:
         return "Trade_Opened";
      case SDP_ACTION_TRADE_CLOSED:
         return "Trade_Closed";
      default:
         PrintFormat("[CSDPEncoder] ERROR: unknown action %d. Using 'Unknown'.", (int)action);
         return "Unknown";
     }
  }
//+------------------------------------------------------------------+
//| IsoTimestamp — ISO-8601 UTC with millisecond precision.           |
//| datetime has 1-second resolution, so the ms field is literal.     |
//+------------------------------------------------------------------+
string CSDPEncoder::IsoTimestamp(const datetime t)
  {
   datetime ts = t;
   if(ts <= 0)
     {
      PrintFormat("[CSDPEncoder] WARNING: invalid timestamp value; using TimeGMT().");
      ts = TimeGMT();
     }
   string stamp = TimeToString(ts, TIME_DATE | TIME_SECONDS);
   StringReplace(stamp, ".", "-");   // 2026-08-12 09:20:00
   StringReplace(stamp, " ", "T");   // 2026-08-12T09:20:00
   return stamp + ".000Z";           // ISO-8601 UTC, millisecond field
  }
//+------------------------------------------------------------------+
//| IsoTimestampUTC — current GMT wall clock as an ISO-8601 string.   |
//+------------------------------------------------------------------+
string CSDPEncoder::IsoTimestampUTC()
  {
   return IsoTimestamp(TimeGMT());
  }
//+------------------------------------------------------------------+
//| EscapeJson — escapes every character that would break JSON:       |
//| quotes, backslashes, control codes, and all bytes < 0x20          |
//| (\\b, \\f, \\v etc. are emitted as valid \\uXXXX escapes).        |
//+------------------------------------------------------------------+
string CSDPEncoder::EscapeJson(const string value)
  {
   string result = "";
   const int len = StringLen(value);
   for(int i = 0; i < len; i++)
     {
      const ushort c = StringGetCharacter(value, i);
      switch(c)
        {
         case '"':
            result += "\\\"";
            break;
         case '\\':
            result += "\\\\";
            break;
         case '\n':
            result += "\\n";
            break;
         case '\r':
            result += "\\r";
            break;
         case '\t':
            result += "\\t";
            break;
         default:
            if(c < 0x20)
               result += StringFormat("\\u%04x", c);   // backspace, form feed, etc.
            else
               result += ShortToString(c);
            break;
        }
     }
   return result;
  }
//+------------------------------------------------------------------+
//| PeriodName — wire name of a timeframe value.                      |
//| PERIOD_CURRENT resolves to the actual chart period.               |
//+------------------------------------------------------------------+
string CSDPEncoder::PeriodName(const ENUM_TIMEFRAMES period)
  {
   ENUM_TIMEFRAMES p = period;
   if(p == PERIOD_CURRENT)
      p = (ENUM_TIMEFRAMES)_Period;
   string name = EnumToString(p);       // e.g. "PERIOD_M15"
   StringReplace(name, "PERIOD_", "");  //      "M15"
   return name;
  }
//+------------------------------------------------------------------+
//| FormatDouble — dot-decimal string. DoubleToString already emits a |
//| dot; the replace is a defensive guard against any locale quirk.   |
//+------------------------------------------------------------------+
string CSDPEncoder::FormatDouble(const double value, const int digits)
  {
   string s = DoubleToString(value, digits);
   StringReplace(s, ",", ".");
   return s;
  }
//+------------------------------------------------------------------+
//| ResolveTimeframe — trims the input; empty falls back to the       |
//| current chart period so the envelope's timeframe key is never     |
//| blank (the schema mandates it for every action).                  |
//+------------------------------------------------------------------+
string CSDPEncoder::ResolveTimeframe(const string timeframe)
  {
   string tf = timeframe;
   StringTrimLeft(tf);
   StringTrimRight(tf);
   if(StringLen(tf) == 0)
     {
      tf = PeriodName((ENUM_TIMEFRAMES)_Period);
      PrintFormat("[CSDPEncoder] WARNING: empty timeframe; falling back to current chart '%s'.", tf);
     }
   return tf;
  }
//+------------------------------------------------------------------+
//| SymbolDigits — live SYMBOL_DIGITS for price formatting. 8 is a    |
//| neutral fallback only (covers crypto-style precision); it is not  |
//| a per-symbol point buffer.                                        |
//+------------------------------------------------------------------+
int CSDPEncoder::SymbolDigits(const string symbol)
  {
   int digits = (int)SymbolInfoInteger(symbol, SYMBOL_DIGITS);
   if(digits <= 0)
     {
      PrintFormat("[CSDPEncoder] WARNING: SYMBOL_DIGITS unavailable for %s; using 8.", symbol);
      digits = 8;
     }
   return digits;
  }
//+------------------------------------------------------------------+
//| ClampConfidence — enforces the SDP contract 0.0 <= score <= 100.0.|
//+------------------------------------------------------------------+
double CSDPEncoder::ClampConfidence(const double confidence)
  {
   if(!MathIsValidNumber(confidence))
     {
      PrintFormat("[CSDPEncoder] ERROR: confidence is NaN/Inf; using 0.0.");
      return 0.0;
     }
   if(confidence < 0.0 || confidence > 100.0)
     {
      PrintFormat("[CSDPEncoder] WARNING: confidence %G outside [0,100]; clamped.", confidence);
      return MathMax(0.0, MathMin(confidence, 100.0));
     }
   return confidence;
  }
//+------------------------------------------------------------------+
//| BuildEnvelope — assembles the mandatory SDP envelope around a     |
//| prebuilt payload object. Adds the charter-mandated                |
//| "historical_context" key only when a non-empty array is supplied. |
//+------------------------------------------------------------------+
string CSDPEncoder::BuildEnvelope(const ENUM_SDP_ACTION action,
                                  const string symbol,
                                  const string timeframe,
                                  const double confidence,
                                  const string payload_json,
                                  const string historical_context_json)
  {
   const string tf = ResolveTimeframe(timeframe);
   if(StringLen(symbol) == 0)
     {
      PrintFormat("[CSDPEncoder] ERROR: empty symbol for action %s. Envelope not built.",
                  ActionToString(action));
      return "";
     }
   if(StringLen(payload_json) == 0 || StringGetCharacter(payload_json, 0) != '{')
     {
      PrintFormat("[CSDPEncoder] ERROR: invalid payload object for action %s. Envelope not built.",
                  ActionToString(action));
      return "";
     }
   string env = "{";
   env += "\"sdp_version\":"                 + "\"" + m_sdp_version + "\",";
   env += "\"timestamp\":\""                 + IsoTimestampUTC() + "\",";
   env += "\"symbol\":\""                    + EscapeJson(symbol) + "\",";
   env += "\"timeframe\":\""                 + EscapeJson(tf) + "\",";
   env += "\"action_type\":\""               + ActionToString(action) + "\",";
   env += "\"algorithmic_confidence_score\":" + FormatDouble(ClampConfidence(confidence), 2);
// Charter: recent swing context MUST ride Setup_Detected / Trade_* actions.
   if(StringLen(historical_context_json) > 0)
      env += ",\"historical_context\":" + historical_context_json;
   env += ",\"payload\":" + payload_json;
   env += "}";
   return env;
  }
//+------------------------------------------------------------------+
//| EncodeHeartbeat — lightweight liveness signal. Confidence is not  |
//| applicable for heartbeats, so the envelope carries 0.0.           |
//+------------------------------------------------------------------+
string CSDPEncoder::EncodeHeartbeat(const string symbol, const string timeframe)
  {
   const string payload = "{\"status\":\"alive\"}";
   return BuildEnvelope(SDP_ACTION_HEARTBEAT, symbol, timeframe, 0.0, payload);
  }
//+------------------------------------------------------------------+
//| EncodeTickHarvest — one tick for the Data Harvest Core. Raw bid/  |
//| ask in price terms plus spread in points and tick volume.         |
//+------------------------------------------------------------------+
string CSDPEncoder::EncodeTickHarvest(const string symbol, const string timeframe,
                                      const double bid, const double ask,
                                      const datetime tick_time, const long tick_volume)
  {
   if(!MathIsValidNumber(bid) || !MathIsValidNumber(ask) || bid <= 0.0 || ask <= 0.0)
     {
      PrintFormat("[CSDPEncoder] ERROR: invalid bid/ask (%G / %G) for %s. Tick_Harvest dropped.",
                  bid, ask, symbol);
      return "";
     }
   if(ask < bid)
     {
      PrintFormat("[CSDPEncoder] WARNING: ask %G < bid %G for %s; values forwarded as-is.",
                  ask, bid, symbol);
     }
   const int digits = SymbolDigits(symbol);
   const double point = SymbolInfoDouble(symbol, SYMBOL_POINT);
   const long spread_points = (point > 0.0) ? (long)MathRound((ask - bid) / point) : 0;
   string payload = "{";
   payload += "\"bid\":"           + FormatDouble(bid, digits) + ",";
   payload += "\"ask\":"           + FormatDouble(ask, digits) + ",";
   payload += "\"spread_points\":" + IntegerToString(spread_points) + ",";
   payload += "\"tick_time\":\""   + IsoTimestamp(tick_time) + "\",";
   payload += "\"tick_volume\":"   + IntegerToString(tick_volume);
   payload += "}";
   return BuildEnvelope(SDP_ACTION_TICK_HARVEST, symbol, timeframe, 0.0, payload);
  }
//+------------------------------------------------------------------+
//| EncodeSetup — a detected setup proposal. Carries prices, the      |
//| setup label, and a computed |R:R| for the Python side.            |
//+------------------------------------------------------------------+
string CSDPEncoder::EncodeSetup(const string symbol, const string timeframe,
                                const string setup_type,
                                const double entry, const double sl, const double tp,
                                const double confidence,
                                const string historical_context_json)
  {
   if(StringLen(setup_type) == 0)
     {
      PrintFormat("[CSDPEncoder] ERROR: empty setup_type for %s. Setup_Detected dropped.", symbol);
      return "";
     }
   if(!MathIsValidNumber(entry) || !MathIsValidNumber(sl) || !MathIsValidNumber(tp) ||
      entry <= 0.0 || sl <= 0.0 || tp <= 0.0)
     {
      PrintFormat("[CSDPEncoder] ERROR: invalid prices (entry=%G sl=%G tp=%G) for %s. Setup_Detected dropped.",
                  entry, sl, tp, symbol);
      return "";
     }
   const int digits = SymbolDigits(symbol);
   double rr = 0.0;
   const double risk = entry - sl;
   if(risk != 0.0)
      rr = MathAbs((tp - entry) / risk);
   string payload = "{";
   payload += "\"setup_type\":\"" + EscapeJson(setup_type) + "\",";
   payload += "\"entry\":"        + FormatDouble(entry, digits) + ",";
   payload += "\"sl\":"           + FormatDouble(sl, digits) + ",";
   payload += "\"tp\":"           + FormatDouble(tp, digits) + ",";
   payload += "\"risk_reward\":"  + FormatDouble(rr, 2);
   payload += "}";
   return BuildEnvelope(SDP_ACTION_SETUP_DETECTED, symbol, timeframe, confidence,
                        payload, historical_context_json);
  }
//+------------------------------------------------------------------+
//| EncodeTradeOpened — actual execution record: ticket, direction,   |
//| lot, and the live levels. Confidence reflects the score at open.  |
//+------------------------------------------------------------------+
string CSDPEncoder::EncodeTradeOpened(const string symbol, const string timeframe,
                                      const ulong ticket, const ENUM_POSITION_TYPE side,
                                      const double lot, const double entry_price,
                                      const double sl, const double tp,
                                      const double confidence,
                                      const string historical_context_json)
  {
   string side_str = "";
   if(side == POSITION_TYPE_BUY)
      side_str = "buy";
   else
      if(side == POSITION_TYPE_SELL)
         side_str = "sell";
      else
        {
         PrintFormat("[CSDPEncoder] ERROR: invalid position side %d for %s. Trade_Opened dropped.",
                     (int)side, symbol);
         return "";
        }
   if(ticket == 0)
     {
      PrintFormat("[CSDPEncoder] ERROR: zero ticket for %s. Trade_Opened dropped.", symbol);
      return "";
     }
   if(!MathIsValidNumber(lot) || lot <= 0.0 ||
      !MathIsValidNumber(entry_price) || entry_price <= 0.0 ||
      !MathIsValidNumber(sl) || sl <= 0.0 ||
      !MathIsValidNumber(tp) || tp <= 0.0)
     {
      PrintFormat("[CSDPEncoder] ERROR: invalid trade fields (lot=%G entry=%G sl=%G tp=%G) for %s. Trade_Opened dropped.",
                  lot, entry_price, sl, tp, symbol);
      return "";
     }
   const int digits = SymbolDigits(symbol);
   string payload = "{";
   payload += "\"ticket\":"       + IntegerToString(ticket) + ",";
   payload += "\"direction\":\""  + side_str + "\",";
   payload += "\"lot\":"          + FormatDouble(lot, 2) + ",";
   payload += "\"entry_price\":"  + FormatDouble(entry_price, digits) + ",";
   payload += "\"sl\":"           + FormatDouble(sl, digits) + ",";
   payload += "\"tp\":"           + FormatDouble(tp, digits);
   payload += "}";
   return BuildEnvelope(SDP_ACTION_TRADE_OPENED, symbol, timeframe, confidence,
                        payload, historical_context_json);
  }
//+------------------------------------------------------------------+
//| EncodeTradeClosed — closes the feedback loop: final PnL and       |
//| R-multiple linked to the original AI score. Envelope confidence   |
//| carries that original score (schema mandates the field).          |
//+------------------------------------------------------------------+
string CSDPEncoder::EncodeTradeClosed(const string symbol, const ulong ticket,
                                      const double profit, const double r_multiple,
                                      const double initial_ai_score,
                                      const string timeframe)
  {
   if(StringLen(symbol) == 0 || ticket == 0)
     {
      PrintFormat("[CSDPEncoder] ERROR: invalid symbol/ticket ('%s', %I64u). Trade_Closed dropped.",
                  symbol, ticket);
      return "";
     }
   if(!MathIsValidNumber(profit) || !MathIsValidNumber(r_multiple))
     {
      PrintFormat("[CSDPEncoder] ERROR: invalid profit/R-multiple (%G / %G) for ticket %I64u. Trade_Closed dropped.",
                  profit, r_multiple, ticket);
      return "";
     }
   string payload = "{";
   payload += "\"ticket\":"           + IntegerToString(ticket) + ",";
   payload += "\"profit\":"           + FormatDouble(profit, 2) + ",";
   payload += "\"r_multiple\":"       + FormatDouble(r_multiple, 2) + ",";
   payload += "\"initial_ai_score\":" + FormatDouble(ClampConfidence(initial_ai_score), 2);
   payload += "}";
   return BuildEnvelope(SDP_ACTION_TRADE_CLOSED, symbol, timeframe, initial_ai_score, payload);
  }
//+------------------------------------------------------------------+
//| BuildHistoricalContext — serializes recent swing structure into a |
//| JSON array for the charter-mandated "historical_context" key.     |
//| Arrays must be equal-length and non-empty; "" returned otherwise. |
//+------------------------------------------------------------------+
string CSDPEncoder::BuildHistoricalContext(const string symbol,
      const double &swing_high[],
      const double &swing_low[],
      const datetime &swing_time[])
  {
   const int n_high = ArraySize(swing_high);
   const int n_low  = ArraySize(swing_low);
   const int n_time = ArraySize(swing_time);
   if(n_high == 0 || n_high != n_low || n_high != n_time)
     {
      PrintFormat("[CSDPEncoder] ERROR: historical context arrays mismatch (%d/%d/%d). Empty array returned.",
                  n_high, n_low, n_time);
      return "";
     }
   const int digits = SymbolDigits(symbol);
   string arr = "[";
   for(int i = 0; i < n_high; i++)
     {
      if(i > 0)
         arr += ",";
      arr += "{\"swing_high\":" + FormatDouble(swing_high[i], digits) + ",";
      arr += "\"swing_low\":"   + FormatDouble(swing_low[i], digits) + ",";
      arr += "\"time\":\""      + IsoTimestamp(swing_time[i]) + "\"}";
     }
   arr += "]";
   return arr;
  }

#endif // CSDPENCODER_MQH