# RequestLatencyLab

Лаборатория измерения **client-observed request latency** — задержки торгового запроса со стороны
клиентского терминала — средствами MQL5 (ТЗ §1). Связывает торговый запрос с его событиями,
измеряет локальные интервалы T0–T6, проводит пять экспериментов и сохраняет отчёт, пригодный
для повторного расчёта.

**Статус:** черновик спецификации; реализация кода в этом репозитории. Режим по умолчанию —
`LOCAL_ONLY` (синтетические проверки, без торговли). Торговые режимы — только демо и только
по явному Start оператора.

## Состав

```
RequestLatencyLab.mq5          — основной советник (единственный торговый entrypoint)
RequestLatencyLab.mqproj       — проект MetaEditor (сборка основного советника)
Include/RequestLatencyLab/     — собственные модули лаборатории
  Models.mqh                   — типы, перечисления, LatencySample (10 редакторских полей)
  Configuration.mqh            — проверка входов/среды, правила символа, configuration_id
  TimeSource.mqh               — источник времени; синтетические часы для LOCAL_ONLY
  Statistics.mqh               — качество выборок, summary, гистограммы, знаковые разности
  EventJournal.mqh             — append-only журнал событий с контрольными ёмкостями
  MarketRegime.mqh             — причинное окно, f/r-признаки, классификация QUIET/FAST
  StateReader.mqh              — адресное чтение ордеров/сделок/позиций, снимки
  CompletionPolicy.mqh         — исход операции и условия T6 (таблица ТЗ §6.4)
  RequestTracker.mqh           — реестр записей, корреляция, метрики, маски T0–T6
  ExperimentRunner.mqh         — план 10 блоков, Park–Miller + Fisher–Yates, роли
  CsvStorage.mqh               — сериализация UTF-8/CRLF, экранирование, read-back
  ReportBuilder.mqh            — повторный расчёт отчёта из архивных CSV
  LatencyPanel.mqh             — панель Start/Status (отключена во время MAIN)
  AppController.mqh            — автомат состояний, единая точка отправки, очистка
  Legacy/                      — переиспользуемые модули из статьи 1
    BenchmarkStatistics.mqh    — Min/Max/Avg/Percentile (адаптированные проверяемые версии)
    TradeRequestTools.mqh      — BuildRequest/PreCheck/нормализация (без Inp*/EXT*)
    LifecycleAdapter.mqh       — адаптер над TradeLifecycle.mqh
Include/Dependencies/Article01/ — снимок исходников статьи 1 (в составе репозитория; источник https://forge.mql5.io/dima_s/mql5-execution-microstructure)
Scripts/MarketCalibration.mq5  — калибровка p50/p90 для классификатора рынка (без торговли)
Scripts/LatencyReport.mq5      — повторный расчёт summary из samples.csv (без счёта)
Tests/RequestLatencyTests.mq5  — синтетические проверки (LOCAL_ONLY), пишет checks.csv
Presets/                       — файлы настроек .set
Data/                          — отобранные наборы данных поставки
Docs/                          — ТЗ, DependencyChanges.md
CSV_SCHEMA.md                  — контракт CSV (по ТЗ §8)
dependencies.lock.json         — фиксация зависимостей от статьи 1
```

## Сборка

Проект собирается из своего каталога MetaEditor'ом. Модуль `TradeLifecycle.mqh`
подключается относительным #include из снимка `Include/Dependencies/Article01`;
репозиторий-источник статьи 1: https://forge.mql5.io/dima_s/mql5-execution-microstructure (SHA-256 коммит зафиксирован в dependencies.lock.json)
(относительный #include в `LifecycleAdapter.mqh`); адаптации — в `Include/RequestLatencyLab/Legacy`.

- Основной советник: открыть `RequestLatencyLab.mqproj` → Compile. Выход: `RequestLatencyLab.ex5`.
- Скрипты и тесты собираются независимо: открыть файл → Compile.
  - `Scripts/MarketCalibration.mq5` → `MarketCalibration.ex5`
  - `Scripts/LatencyReport.mq5` → `LatencyReport.ex5`
  - `Tests/RequestLatencyTests.mq5` → `RequestLatencyTests.ex5`

Целевая сборка: 0 ошибок, 0 предупреждений (MetaEditor build 6182, AVX2).

## Запуск

### LOCAL_ONLY (по умолчанию)
1. Установить советник на график с режимом `InpRunMode=LOCAL_ONLY`.
2. Нажать **Start** на панели. Синтетический прогон использует тестовые часы и
   транспорт-счётчик; **реальная торговля не выполняется** (SAFE-01).
3. Отчёт пишется в `MQL5\Files\RequestLatencyLab\<campaign>\<session>\`:
   `manifest.csv`, `samples.csv`, `events.csv`, `schedule.csv`.

### Проверки
Запустить скрипт `Tests/RequestLatencyTests.mq5` на любом графике. Результат —
`MQL5\Files\RequestLatencyLab\tests\checks.csv` и сводка PASS/FAIL в журнале.

### Демо-пилот / основные серии (только DEMO)
1. Выполнить `Scripts/MarketCalibration.mq5` — получить `calibration.csv` (для E3).
2. Выставить `InpRunMode=MARKET_ORDER` или `PENDING_CREATE_DELETE`, заполнить
   обязательные broker-зависимые значения (D, filling, minimum volume).
3. Явный Start оператора на панели. Основное измерение — по плану 10 блоков
   (по 10 A/B на блок, 5 Buy/5 Sell), пауза, очистка, сроки 5000/1000 мс.
4. Анализ: `Scripts/LatencyReport.mq5` пересчитывает summary из архивных CSV
   без обращения к текущему счёту.

## Документация
- `Docs/RequestLatencyLab_TZ_RU.md` — исходное техническое задание (черновик).
- `Docs/DependencyChanges.md` — история адаптации кода статьи 1.
- `CSV_SCHEMA.md` — контракт CSV-отчёта.
- Приёмочные сценарии: `RequestLatencyLab_AcceptanceTests_RU.md`
  (73+ сценария; начальный статус всех — NOT_RUN, выполнение тестов не означает
  проведения экспериментов).

## Ограничения и безопасность
- Реальная торговля — только демонстрационный счёт; никаких сторонних объектов.
- Никаких DLL/Python/сетевых сервисов для повторения эксперимента.
- Один основной запрос в работе; служебные CLEANUP отдельными sequence и request_id.
- Однопрогонный отчёт не является доказательством прибыльности или устойчивости.
- Backtest/пилот не гарантирует будущих результатов; числа из синтетических фикстур
  не переносятся в статью как наблюдения терминала.