# GsignalX Velocity Premium — Cloud Connector Plan (Private)

**Status:** Contract-aligned with ProTrading Go/OpenAPI (2026-10) · soak Phase 6  
**Control plane:** `https://trade-api.gsignalx.cloud`  
**Sibling:** Free Velocity `docs/plans/CLOUD_CONNECTOR_PLAN.md` · Trading system `docs/plans/2026-10-toolkit-cloud-connector.md`  
**Hardening:** [RELIABILITY_PERF_PLAN.md](RELIABILITY_PERF_PLAN.md)

## Goal

Premium toolkit is the **canonical** MQL5 cloud worker. Users enroll with email + control-plane URL + dashboard mint token. No Go/Python connector required for single-terminal desks. Dual-track + OF/VP signal uplink remain Premium-only.

**Product rule:** STOP/PLAY/dual-track/stand-down trigger semantics are **identical** with or without cloud. Cloud adds only account-plane pieces (mint, token, claim-session, snapshot, command queue, signal uplink).

## With / without cloud

| Mode | Behavior |
|------|----------|
| `InpCloudEnable=false`, no panel file | Pure local Trade Center / Service — no cloud gates |
| `InpCloudEnable=false`, Go writes `control_panel.json` | File bridge gates only (VPS / Go desk) |
| `InpCloudEnable=true` | Service HTTPS owns panel + commands; writes clean v1 to file for Core/chart |

**Single authority:** do not co-run Go command poller with toolkit HTTPS on the same account.

## Relationship to Phase-3 file bridge

`GsxCloudControl.mqh` reads `control_panel.json`. Toolkit HTTPS polls `control_panel` and writes **unwrapped v1 only** to that file. When `connector_runtime=velocity_premium`, HTTPS is SoT.

## Contract (must match OpenAPI)

| Item | Spec |
|------|------|
| Commands | `command_type` + `payload`; ack `{status, result}` |
| Snapshot | `{positions:[], summary:{}}` |
| Trades | Closed deals → `/trades` |
| `close_partial` | `ticket` + `percent` |
| Cadence | HB ~30s; online window 120s |
| Agent | `GSX_AGENT_VERSION` (`velocity_premium-2.18`) |

## Inputs

| Input | Default | Notes |
|-------|---------|--------|
| `InpCloudEnable` | false | Local-first; enable for HTTPS worker |
| `InpCloudPushSignals` | true | Push join dirs to `/velocity/signals` |
| `InpCloudRuntimeTag` | `velocity_premium` | Sent on register/heartbeat |
| `InpCloudAllowRemoteCloses` | false | Scouter owns exits unless enabled |

## Modules (canonical)

```
Include/GSignalX/Cloud/
  CloudHttp.mqh      — WebRequest (Config timeout; no Sleep)
  CloudAuth.mqh      — register, persist, rotate, 401 invalidate
  CloudLoop.mqh      — HB/claim/snapshot/trades/commands/signals + breaker
  CloudExec.mqh      — place_order / close_* / close_partial / modify + ack envelope
  CloudControl.mqh   — HTTPS control_panel unwrap → clean v1 file + fleet RUN
```

State: `GSignalX/cloud/v1/worker.json` under FILE_COMMON.

Wire: `GsignalX_Service.mq5` primary; Desk/chart file panel only.

## Sync to trading system

After soak, copy public-safe Cloud* (no OF/VP push hooks) to:

`G-SignalXProTradingSystem/mql5/velocity-cloud-worker/`

## Acceptance

- [x] Contract shapes: `command_type`, ack envelope, snapshot/trades, `close_partial` percent
- [x] Config cadences + circuit breaker + 401 re-auth path
- [x] Signal uplink wired (`GsxCloudQueueSignals` / push)
- [x] Enroll + claim-session path (needs live mint soak)
- [ ] Phase 6 live soak checklist green (below)

## Soak (Phase 6)

1. Mint → Service enroll → claim → snapshot  
2. control_panel STOP blocks new opens (cloud/hybrid)  
3. place_order + close_partial + close_all (flag on)  
4. Token rotation via heartbeat  
5. `InpCloudEnable=false` still trades locally  
6. No double entry when HTTPS owns panel (no Go poller)