mql5-execution-microstructure-02-request-latency/CSV_SCHEMA.md

CSV-контракт RequestLatencyLab

Статус: черновик. Не утверждено. Без номера версии.

Приложение к Docs/RequestLatencyLab_TZ_RU.md (раздел 8). Имена файлов и формат — проектные предложения спецификации RequestLatencyLab_Specification_RU.md. Содержательно: один файл отчёта — одна ответственность; таблицы задают полный порядок колонок; поля LatencySample сохраняются под исходными именами.

Общие правила

• UTF-8 без BOM при записи; один BOM допускается при чтении (реализация CsvStorage.mqh: запись — UTF-8 без BOM, чтение допускает BOM).
• Разделитель — запятая ,; десятичная точка; окончания строк CRLF.
• Поля с запятой/кавычкой/переводом строки заключаются в кавычки; кавычка удваивается.
• Содержательная пустая строка пишется как ""; отсутствующее значение — пустое поле. Парсер сохраняет это различие (CCsv::ParseRow).
• uint32/uint64/int32/int64 — точные десятичные целые без преобразования через double.
• Bool — 0/1. Double — конечное число, не менее 16 значащих цифр для вычисляемых показателей; NaN/Inf не допускаются.
• Неизвестное значение не подменяется нулём; причина — код статуса/presence.
• JSON-ячейки экранируются целиком как CSV-ячейка.

Основные файлы

manifest.csv

Паспорт запуска. Ключи (полный реестр): project_name, document_status, campaign_id, session_id, experiment_id, series_id, configuration_id, protocol_fingerprint, schema_fingerprint, schema_version, application_identifier, source_commit, source_dirty, source_package_sha256, dependencies_lock_sha256, schedule_sha256, data_origin, terminal_build, compiler_build, server_name, account_alias, account_margin_mode, symbol, point_size, price_tick_size, price_digits, volume_min, volume_max, volume_step, market_filling, pending_filling, deviation_points, pending_distance_ticks, magic, count_per_condition, warmup_per_condition, outcome_timeout_ms, late_grace_ms, pause_ms, timer_requested_ms, feature_window_sec, feature_max_age_ms, quote_max_age_ms, calibration_id, collection_windows, calendar_time_source, calendar_time_scale, start_calendar, end_calendar, generator_name, seed, cleanup_mode, cleanup_logging, cleanup_max_attempts, sample_capacity, event_capacity, error_reserve_capacity, volume_units_tolerance, address_read_budget, history_scan_budget, run_status, stop_reason, n_main_dispatched, n_warmup_dispatched, n_cleanup_dispatched, n_pilot_dispatched, n_dispatch_uncertain, records_attempted, records_accepted, records_persisted, records_lost, buffer_high_watermark, outstanding_objects, last_checkpoint_event_sequence, ping_before_run_us, ping_after_run_us, input_files, output_files. Реализация: CCsvReport::BuildManifest (подмножество реестра текущей версии).

schedule.csv

session_id,row_id,row_kind,slot_id,experiment_id,series_id,condition_id,block_id,role, operation,side,mode,logging_mode,planned_order,sequence,parent_sequence,status, reason_code.

samples.csv

Первые 10 полей — LatencySample в исходном порядке: request_id, sequence, send_start_us, send_return_us, request_event_us, order_event_us, first_deal_us, final_event_us, retcode, completed. Далее: campaign_id, experiment_id, series_id, session_id, configuration_id, condition_id, slot_id, parent_sequence, cleanup_attempt, role, is_warmup, operation, mode, logging_mode, symbol, side, correlation_status, correlation_method, order_ticket, position_ticket, position_identifier, last_deal_us, deal_count, executed_volume, callback_volume, history_volume, deal_coverage_complete, present_mask, recovered, conflict, measurement_interrupted, scenario_deviation, outcome, outcome_at_final, final_source, trading_state_known, confirmation_invalidated, confirmation_record_id, current_confirmation_record_id, observation_deadline_us, collection_deadline_us, collection_close_us, collection_closed, deadline_exceeded, market_regime, calibration_id, bid_at_send, ask_at_send, spread_at_send, tick_time_msc, actual_type, actual_filling, deviation_points, comment, request_price, callback_coverage_complete, market_window_id, market_window_seq.

Аудит-4 (R4-B8): отсутствующее значение timestamps/retcode/объёмов пишется ПУСТЫМ полем (а не 0); actual_type/actual_filling/deviation_points/comment/request_price фиксируют фактический контракт запроса (для cleanup — контракт закрытия/удаления).

Аудит-5 (R5-S2): actual_type/actual_filling — допустимые нулевые коды (ORDER_TYPE_BUY=0, ORDER_FILLING_FOK=0) записываются как 0; пустое поле означает, что фактический контракт не зафиксирован (actual_known=false). configuration_id всегда заполняется после Preflight и попадает в manifest/samples.

Аудит-8 (R8-S2): формат расширен до 68 колонок — market_window_id/market_window_seq (связь строки с исходным окном E3, соответствие market_windows.csv по sequence; market_window_seq=0/пустой id — запись без E3-контекста или до режима).

Аудит-5 (R5-B4): callback_coverage_complete — отдельный признак полноты ЛОКАЛЬНЫХ callback-меток сделок (1 = все сделки ордера наблюдались через DEAL_ADD; сделка, найденная только в истории, не даёт полного T5). deal_coverage_complete — признак торгового результата (сумма объёмов равна запрошенному). T5-метрика использует callback_coverage_complete.

events.csv

Append-only: session_id,event_sequence,record_kind,local_time_us,origin_sequence, target_sequence,ref_event_sequence,transaction_type,request_id,order_ticket,deal_ticket, position_ticket,handler_enter_us,handler_exit_us,payload_json,quality_code.

deals.csv

session_id,account_alias,deal_ticket,order_ticket,owner_sequence,symbol,deal_type,entry, reason,magic,position_ticket,position_identifier,callback_first_us,callback_event_id, has_callback,callback_volume,history_volume,history_price,deal_time_msc, history_read_event_id,recovered,correction_count,deleted,quality_codes.

summary.csv

experiment_id,condition_id,series_id,metric_id,outcome_group,population,observation_unit, segment_key,source_set_id,unit,n_attempted,n_applicable,n_not_applicable, n_applicability_unknown,n_valid,n_missing,n_late,n_conflict,n_interrupted,n_used,minimum, mean,median,p90,p95,p99,p999,maximum,stddev,percentile_method,method_fingerprint, p95_tail_expected_n,p99_tail_expected_n,p999_tail_expected_n,tail_warning_codes, n_deadline_exceeded,deadline_denominator,deadline_rate,n_timestamp_missing_at_deadline, missing_timestamp_rate,conditional_distribution.

histogram.csv

experiment_id,condition_id,series_id,metric_id,outcome_group,population,segment_key, bin_index,lower_us,upper_us,count,denominator,share. Только неотрицательные интервалы ([0,1),[1,2),[2,4),[4,8),[8,16),[16,32),[32,64),[64,128),[128,256),[256,+∞) мс). Знаковая метрика T2−T4 в histogram НЕ включается (отдельный offset_signs.csv); в summary группа исходов outcome_group = ALL | SUCCESS | REJECTED (SUCCESS — базовые успешные исходы: не REJECTED и не UNKNOWN; ALL включает отказы); CLEANUP-роль и warmup из summary/histogram исключаются; статистики считаются при n_valid>=1 (min/mean/median/квантили), stddev при n_valid<2 остаётся пустым (выборочное n-1 неприменимо). Категория LATE в online и offline определяется по фактическому КОНЦУ метрики относительно observation_deadline_us, а не по флагу deadline_exceeded (R5-B3): ранние точки остаются VALID даже при позднем T6.

market_windows.csv, checks.csv, experiment_manifest.csv

market_windows.csv — сохраняемые окна E3 (не более 4096): session_id,dataset_id,window_id,sequence,calibration_id,symbol,from_msc,to_msc, anchor_tick_msc,n_returned,n_valid_info,quote_frequency_hz,mid_range_ticks,regime,valid, quality_codes,ticks_checksum. Аудит-8 (R8-S2): ticks_checksum — FNV-1a 64 по (time_msc,bid,ask) валидных INFO-тиков окна; контрольная сумма используется как ПРОВЕРКА при повторном чтении (CopyTicksRange(from_msc,to_msc) того же диапазона), а НЕ как источник данных. Аудит-9 (R9-S3): сырые тики окна удерживаются В ПАМЯТИ (ComputeWindowRawTicks) и выгружаются в market_ticks.csv в safe-фазе ПОСЛЕ закрытия окна измерения и в ExportRun; аудит-10 R10-B4: файл имеет ЗАГОЛОВОК session_id,window_id,window_seq,time_msc,bid,ask,flags,volume, строки завершаются НАСТОЯЩИМ CRLF (не литеральным \r\n), bid/ask - точность %.17g (полный round-trip double); заголовок пишется при создании/пустом файле; для сессии файл с заголовком гарантируется (EnsureMarketTicksFile) синхронная файловая запись внутри измерительной фазы запрещена (аудит-8 R8-B3), поэтому выгрузка перенесена на post-close/export.

Зарезервированы контрактом: признаки/калибровка, результаты проверок, связь пяти экспериментов (E4 — ссылки на E1, reuse=1, без копирования samples).

Дополнительные файлы

comparisons.csv (A_vs_B: n/mean/median/p95 для A и B, delta = B−A и относительное изменение (B−A)/A по каждой метрике — ТЗ §7, стр. 419; sign дельты: B медленнее A — положительная), offset_signs.csv (NEGATIVE/ZERO/POSITIVE для T2−T4, вне latency-гистограммы), market_ticks.csv market_ticks.csv (аудит-9 R9-S3: сырые тики окон E3, append-only; строки: session_id,window_id,window_seq,time_msc,bid,ask,flags,volume; выгрузка из памяти в safe-фазе после закрытия окна и в ExportRun; порядок одинаковых миллисекунд (R10-B4: заголовок 8 имён, реальный CRLF, %.17g) сохраняется; сбой выгрузки — fail-closed, новые отправки блокируются), calibration.csv (реестр порогов; trading_session_count = число отдельных календарных дат валидных окон, генератор считает реальные сессии и loader требует

=5; аудит-5: генератор НЕ сохраняет набор с <5 сессиями или <1000 окон — явный INSUFFICIENT_DATA; добавлены ключи period_from_msc/period_to_msc), <calibration_id>_windows.csv (исходные окна калибровки: minute_start_msc,quote_frequency_hz,mid_range_ticks — для независимой проверки отсутствия пересечения калибровки и эксперимента и пересчёта порогов), summary_rebuilt.csv/histogram_rebuilt.csv/offset_signs_rebuilt.csv/ comparisons_rebuilt.csv (offline-пересчёт: summary_rebuilt.csv использует ЕДИНУЮ 41-колоночную схему онлайн-summary; число строк контрольного чтения — от реально созданной таблицы с уникальными ключами; повреждённый/усечённый samples.csv отвергается, а не пересчитывается молча; группы ALL|SUCCESS|REJECTED, категории LATE по концу метрики, T5 по callback_coverage_complete), intents.csv (устойчивый журнал намерений: строки session_id,sequence,kind, local_time_us; INTENT пишется ДО T0; INTENT без SEND_RETURN после сбоя/перезапуска учитывается как n_dispatch_uncertain в manifest — восстановление неопределённых попыток. Аудит-7 R7-S1/B1: запись — ровно n-1 полезный байт с начала без терминального NUL (FileWriteArray(handle,array, start,count)); cleanup-отправки пишутся в тот же журнал; синхронная запись SEND_RETURN перенесена ВНЕ измеряемой фазы T0..T1; при нечитаемости/повреждении журнала n_dispatch_uncertain принимает sentinel ULONG_MAX (неопределённость не сужается до нуля; ветвь недоступности различима и НЕ преобразуется в обычный счётчик), повреждённая строка — +1 неопределённость. Аудит-10 R10-B2: INTENT_CANCELLED снимает неопределённость РОВНО с одной попытки того же sequence (хронологическая пара): повторный INTENT после отмены без SEND_RETURN остаётся неопределённым. Аудит-8 R8-B3: SEND_RETURN НЕ дописывается синхронно между T1 и обработкой callbacks (один поток исполнения советника): факт возврата буферизуется в памяти и дописывается в safe-фазе после закрытия окна (FlushPendingSendReturns); при аварии до этого попытка честно остаётся DISPATCH_UNCERTAIN. Аудит-8 R8-B4: подтверждённые ключи (sequence) набираются динамически без предела 256 — полностью парный запуск 5x100+очистки даёт 0 неопределённых, а не ложные INTENT-без-возврата; короткое чтение FileReadArray != FileSize также даёт sentinel), checkpoint.marker (маркер согласованности завершённого checkpoint-набора samples/events; пишется последним и содержит ПОКОЛЕНИЕ экспорта gen=<N>; старый marker удаляется ДО перезаписи — при сбое между фазами остаётся отсутствующий marker, а не устаревший «успех»; checkpoint выполняется только в безопасной фазе CanCheckpoint и его ошибка блокирует новые отправки) — summary_rebuilt_e4.csv (E4: pooled статистика из 500 первичных ASYNC-записей ПЯТИ РАЗНЫХ завершённых E1-серий + per-series строки со ссылками на исходные session_id; без копирования samples и без усреднения серийных медиан; аудит-5: проверяются 5 разных каталогов, уникальные session_id, ровно expected_main MAIN B-ASYNC записей на серию (по умолчанию 100), единый символ серий. Аудит-6: manifest.csv источника ОБЯЗАТЕЛЕН (отсутствие = отказ), допускается только run_status=FINISHED с n_main_dispatched>=expected_main; нормализованная конфигурация (configuration_id) и символ совпадают МЕЖДУ всеми пятью сериями; каждая строка принадлежит сессии серии; последовательности (sequence) уникальны внутри файла; pooled/per-series статистика считаются той же метрической семантикой валидности, что и остальные отчёты (R6-B2/B7). Аудит-7 (R7-B6): обычный E4 принимает только допустимое происхождение data_origin (по умолчанию DEMO; SYNTHETIC-серии отвергаются code 41 вне отдельного синтетического режима); configuration_id СТРОК сверяется с manifest серии (code 42); столбец data_origin присутствует во всех строках; добавлены показатели полноты n_attempted, n_applicable, n_not_applicable, n_applicability_unknown, n_missing, n_late, n_conflict, n_interrupted, n_deadline_exceeded, deadline_denominator, deadline_rate по сериям и pooled (числа нельзя вывести из одного n после фильтрации VALID).

Порядок и контроль

• Порядок строк — по первичному ключу; дубликат ключа — ошибка.
• Чтение samples.csv (rebuild-путь, аудит-6 R6-S1, аудит-7 R7-B4, аудит-8 R8-S1): полная проверка заголовка (все 68 имён по порядку, перестановка колонок — отказ), числовая валидация полей времени/масок (нечисловой токен — отказ), дубликаты sequence — отказ. Деление файла на ЛОГИЧЕСКИЕ записи CSV: перевод строки внутри кавычек — данные, а не разделитель; терминатор \r записи снимается один раз (CR внутри данных не вырезается); пустые числовые ячейки сверяются с present_mask (бит есть, ячейка пуста — отказ; бита нет, значение есть — отказ), т.е. несогласованный файл не заменяется нулями и не пропускается. Ёмкость capacity — число НАБЛЮДЕНИЙ; заголовок её НЕ расходует (головка + ровно capacity строк допустимы). Контрольное чтение (ReadBackVerifyFile) считает те же ЛОГИЧЕСКИЕ записи, что и reader (встроенный перевод строки в кавычках — данные), поэтому валидный multiline-экспорт не отвергается собственной проверкой.
• Единая семантика online/offline (R6-B2): offline-путь восстанавливает запись в RequestMetadata и считает категории/применимость/срок той же статической CRequestTracker::EvaluateMetric; WARMUP-роль исключается одинаково во всех путях; deadline-счётчики summary совпадают с онлайн-экспортом.
• Хеши наборов — SHA-256 по отсортированному списку путей (реализация — CryptEncode(CRYPT_HASH_SHA256) в контрольных точках).
• Генерационное время не участвует в числовом сравнении; пересчёт одних исходных байтов даёт точные целые поля и double в допуске max(1e-9, 1e-12*|x|).
• Повторный расчёт — только из архивных CSV (без обращения к текущему счёту).