Lab059: establish limits of preamble-only carrier estimation

docs/LABS_INDEX.md

@@ -495,3 +495,26 @@
   [JSON](../data/processed/lab058/summary.json),
   [CSV](../data/processed/lab058/segment_metrics.csv),
   [H(f)](../data/processed/lab058/channel_transfer.png). STOP; push не выполнялся.
+
+## Lab059 — пределы carrier recovery по одной преамбуле
+
+- **Запись 053; только сохранённые IQ, RF TX=0.** P0 baseline записан до P1–P3
+  и численно воспроизвёл Lab057/Lab058. Активный P0 использует два блока BPSK²
+  по512 символов; ошибки B1/B2 +4,7307/+4,7608Гц дают SER52,4169%.
+- **Лучший реальный результат P3:** после ограничения RAW-обработки только
+  преамбулой ошибки −0,1249/+0,3917Гц, средняя SER B 3,6170% против
+  whole-burst diagnostic3,4959%. A не ухудшена.
+- **Предел устойчивости:** на synthetic500K/EVM0,84535 P1 имеет лучший RMSE
+  3,728Гц, а P3 попадает в ±0,5Гц лишь в9,61% из5100 испытаний. AWGN CRLB
+  sanity check3,598Гц. Две реальные реализации недостаточны для устойчивого PASS.
+- **Контроли:** Lab04736/36 у P0–P3; Lab0540/16 HEADER/FEC/CRC/packet у всех,
+  исторический `NOT_A, 0/16` сохранён. Независимо найденная RAW/DC-утечка
+  P1–P3 исправлена и закрыта регрессионным тестом; исходные IQ не изменились.
+- **Вердикт:** `PREAMBLE_ONLY_INSUFFICIENT`. Следующий один кандидат — полностью
+  офлайн decision-directed carrier tracking через burst без payload truth и
+  изменения packet format. Физический предел B около3,50% SER остаётся.
+- [Постановка](lab059_current_state.md), [отчёт](lab059_offline_result.md),
+  [JSON](../data/processed/lab059/summary.json),
+  [real CSV](../data/processed/lab059/real_results.csv),
+  [synthetic CSV](../data/processed/lab059/synthetic_results.csv). STOP;
+  Lab059 не коммитировалась, push не выполнялся, Lab060 не создана.

docs/lab059_current_state.md

@@ -0,0 +1,78 @@
+# Lab059 — границы и заранее зафиксированный план
+
+## Цель
+
+Lab059 проверяет только по сохранённым данным, достаточно ли 1280-символьной
+преамбулы для оценки остаточного частотного сдвига на весь burst длительностью
+около 0,2048 с. Штатный приёмник, формат пакета, преамбула, RRC, FEC и CRC не
+изменяются. Оборудование не опрашивается, аппаратные команды не выполняются,
+RF TX = 0.
+
+Исходный HEAD после отдельной фиксации Lab058:
+`82f17499ace5e655991240348401b9700c7c3349`.
+
+## Зафиксированные методы
+
+- **P0 CURRENT.** Дословно воспроизводится активная ветвь штатного приёмника:
+  первые 1024 символа возводятся в квадрат, делятся на два блока по 512,
+  частота определяется по разности фаз центров блоков с делением на `4*pi`.
+  Последние 256 символов преамбулы в оценке частоты не участвуют.
+- **P1 FULL PREAMBLE PHASE SLOPE.** Известные BPSK-знаки удаляются на всей
+  преамбуле. Фазы когерентных 20-символьных блоков аппроксимируются линейной
+  моделью с заранее заданными Huber-весами.
+- **P2 SPLIT PREAMBLE.** TRAIN заранее фиксирован как индексы 32…607,
+  VALIDATION — 672…1247. Между ними оставлен разрыв 64 символа; по 32 символа
+  у начала и конца преамбулы не используются. Частота и фаза оцениваются только
+  по TRAIN, а VALIDATION проверяет экстраполяцию без переоценки.
+- **P3 SQUARED FULL PREAMBLE.** Все 1280 символов возводятся в квадрат,
+  фаза 20-символьных блоков аппроксимируется той же устойчивой моделью,
+  частотный наклон делится на два из-за удвоения фазы BPSK.
+
+P0 сохраняет точную активную ветвь, включая штатное удаление среднего DC по
+всему переданному в неё фрагменту: это часть воспроизводимого baseline, а не
+новое решение. Для P1 и P3 удаление DC и RRC-фильтрация ограничены RAW-опорой
+полной преамбулы; для P2 — RAW-опорой только TRAIN. Поэтому полезная часть RAW
+не влияет на вход новых оценивателей. Все методы получают Fs, Rs, RRC,
+номинальную несущую и уже найденное начало кандидата. Для изоляции carrier
+recovery timing остаётся штатным P0 и не подбирается отдельно по методу.
+Начальная фаза относится к `t=0`; центр символа `k` расположен в
+`(k+0.5)/Rs`.
+
+Header, payload, magic, FEC и CRC не участвуют в оценке. Известные переданные
+биты подключаются только после заморозки параметров для подсчёта ошибок, EVM и
+matched/residual. Диагностическая оценка по всему burst служит только внешней
+справочной величиной после расчёта preamble-only оценки.
+
+## Baseline и реальные данные
+
+До сравнения P1–P3 программа отдельно сохраняет P0 baseline для Lab056
+A1/B1/A2/B2, 16 кадров Lab054 и 36 ранее принятых кадров Lab047. Lab047 служит
+положительным контролем. Исторический результат Lab054 остаётся `NOT_A, 0/16`.
+Сохранённые raw-файлы открываются только для чтения; их SHA-256 проверяются до и
+после расчёта.
+
+## Synthetic Monte Carlo
+
+Фиксированные частоты: `0, ±0.25, ±0.5, ±1, ±2, ±5, ±10, ±20, ±100 Гц`.
+Проверяются 20 и 500 ксимв/с, Fs = 8 Мвыб/с, действующие RRC и преамбула 1280
+символов. Чистые точки решения формируются реальным TX/RX RRC-трактом, после
+чего добавляется воспроизводимый комплексный гауссов шум на символьном выходе.
+Уровни EVM заранее фиксированы: 0,317390 (качество A Lab058), 0,55 и 0,845350
+(среднее физическое качество B Lab058). Последний уровень не подгоняется по
+исходу оценивателя.
+
+Для каждой комбинации используются 300 реализаций и фиксированная схема seed.
+Катастрофическая ошибка заранее определена как `|frequency error| > 1/(2T)`,
+то есть фазовый уход более 180° за `T = 0,2048 с`; порог равен 2,44140625 Гц.
+Публикуются bias, RMSE, median/P95/P99 абсолютной ошибки, катастрофическая доля
+и вероятности ошибки не более 0,25/0,5/1,0 Гц.
+
+## Критерий вывода
+
+`PREAMBLE_ONLY_SUFFICIENT` требует одновременно приблизить Lab056 B к
+диагностическому результату, устойчиво пройти Monte Carlo, не ухудшить Lab056 A
+и сохранить положительный контроль Lab047. Нестабильная субгерцовая точность
+даёт `PREAMBLE_ONLY_MARGINAL`; принципиально недостаточная стабильность на
+качестве B даёт `PREAMBLE_ONLY_INSUFFICIENT`.
+
+Lab059 не коммитируется. Push не выполняется. Lab060 автоматически не создаётся.

docs/lab059_offline_result.md

@@ -0,0 +1,187 @@
+# Lab059 — пределы восстановления несущей только по преамбуле
+
+## Что произошло простыми словами
+
+У штатного приёмника есть только 2,56 мс известной преамбулы, чтобы предсказать
+фазу несущей на весь burst длительностью около 204,8 мс. Для ограничения ухода
+фазы 30 градусами ошибка частоты должна быть не больше 0,4069 Гц. Штатная
+двухблочная оценка на B1/B2 ошиблась примерно на +4,73/+4,76 Гц и поэтому
+повернула решения почти на полный оборот к концу burst.
+
+Один из новых диагностических методов, P3, оказался очень удачным именно на
+двух сохранённых B-сегментах: ошибки составили −0,125 и +0,392 Гц, а средняя
+доля ошибочных символов упала с 52,4169% до 3,6170%. Это почти совпало с
+диагностически достижимыми 3,4959% Lab058. Однако это две реализации, и они не
+доказывают устойчивость. В 5100 синтетических испытаниях качества B P3 попадал
+в ±0,5 Гц только в 9,61% случаев; лучший по RMSE метод P1 имел RMSE 3,728 Гц и
+попадал в ±0,5 Гц в 10,47% случаев.
+
+Следовательно, текущая реализация P0 действительно слаба, и P3 может дать
+хорошую начальную оценку. Одновременно 1280 символов при 500 ксимв/с и
+наблюдаемом качестве B не дают надёжной субгерцовой точности сами по себе.
+Для устойчивого результата требуется сопровождать фазу или частоту в ходе
+самого пакета. Это задаёт следующий программный эксперимент. Физический предел B,
+установленный Lab058 — около 3,50% ошибочных символов даже при диагностическом
+выравнивании — остаётся отдельной задачей.
+
+## Границы и целостность
+
+Lab059 выполнялась только офлайн. HackRF Plus не опрашивался, аппаратные команды
+и передачи не запускались, RF TX = 0. Прочитаны сохранённые Lab056, Lab054 и
+Lab047. Размеры и SHA-256 пяти исходных IQ-файлов проверены до и после расчёта;
+совпадение полное. Исторический результат Lab054 не изменён: `NOT_A, 0/16`.
+
+P0 baseline физически записан в `baseline_p0.json` до вычисления P1–P3. Он
+воспроизвёл Lab057 для Lab054: максимальное расхождение CFO равно
+`1,42e-13 Гц`, ошибки преамбулы `7767/7767`, HEADER/CRC `0/0`. Для четырёх
+сегментов Lab056 различия P0 с Lab058 по CFO, BER и EVM находятся на уровне
+округления floating point.
+
+Независимая проверка обнаружила, что первая реализация P1–P3 удаляла DC по
+всему burst до выделения преамбулы. Из-за этого RAW полезной части менял вход
+оценивателя, хотя правильные payload-биты ему не передавались. Исправленный
+вариант ограничивает DC и FIR-опору P1/P3 полной преамбулой, а P2 — только
+TRAIN. Отдельный тест изменяет RAW после преамбулы и подтверждает неизменность
+P1–P3. P0 намеренно оставлен точным baseline со штатной глобальной обработкой.
+
+## Требуемая точность
+
+Использовано `delta_f_max = phase_limit / (360*T)`, где `T = 0,2048 с`.
+
+| Допустимый уход фазы | Максимальная ошибка частоты |
+|---:|---:|
+| 15° | 0,203451 Гц |
+| 30° | 0,406901 Гц |
+| 45° | 0,610352 Гц |
+| 60° | 0,813802 Гц |
+| 90° | 1,220703 Гц |
+
+Порог 0,4069 Гц — инженерная цель для 30°, а не новый обязательный порог
+протокола. Катастрофическая ошибка Monte Carlo заранее определена как больше
+2,441406 Гц, что соответствует уходу более 180° за burst.
+
+## Аудит штатной математики P0
+
+Активный код получает точки после номинального переноса 50 кГц, RRC-фильтра и
+штатного timing. Он возводит BPSK в квадрат, усредняет символы `[0,512)` и
+`[512,1024)`, затем берёт разность фаз. Центры находятся в моментах `256/Rs` и
+`768/Rs`, расстояние равно `512/Rs`. Формула имеет вид
+`delta_phase / (4*pi*(512/Rs))`; `4*pi` правильно учитывает удвоение фазы после
+BPSK². Компенсация использует отрицательный знак, gain относится к `t=0`, центр
+символа k — к `(k+0.5)/Rs`. Повторной компенсации не обнаружено.
+
+Для 500 ксимв/с однозначный диапазон P0 равен ±244,140625 Гц, поэтому +4,7 Гц
+не является алиасом. Главный практический недостаток — две фазовые точки без
+избыточности; последние 256 символов преамбулы не участвуют в частотной оценке.
+Для 20 ксимв/с диапазон P0 всего ±9,765625 Гц, поэтому synthetic ±20 и ±100 Гц
+преднамеренно показывают алиас и увеличивают сводный RMSE P0.
+
+## Методы
+
+| Метод | Использованные символы | Оценка | Проверка |
+|---|---:|---|---|
+| P0 CURRENT | 1024 | два блока BPSK² по 512 | P2 VALIDATION только как диагностика |
+| P1 FULL PHASE SLOPE | 1280 | Huber-fit фаз 64 despread-блоков по 20 | фиксированная преамбула |
+| P2 SPLIT | 576 TRAIN | Huber-fit 36 despread-блоков по 16 | 576 VALIDATION без переоценки |
+| P3 SQUARED FULL | 1280 | Huber-fit фаз 64 BPSK²-блоков по 20, наклон /2 | фиксированная преамбула |
+
+P2 использует TRAIN 32…607 и VALIDATION 672…1247; разбиение зафиксировано до
+результата. Timing одинаков для P0–P3, чтобы эксперимент изолировал carrier
+recovery. P1/P3 получают RAW-опору только полной преамбулы, P2 — только TRAIN.
+Ни один новый оцениватель не получает header, magic, payload, JPEG, FEC или CRC.
+
+## Lab056 A/B
+
+Ошибки частоты ниже считаются относительно whole-burst diagnostic reference
+Lab058, подключённого только после заморозки preamble-only оценки.
+
+| Метод | B1 ошибка CFO | B2 ошибка CFO | Средняя \|ошибка\| | B1 SER | B2 SER | Средняя SER B |
+|---|---:|---:|---:|---:|---:|---:|
+| P0 | +4,730655 Гц | +4,760847 Гц | 4,745751 Гц | 52,5218% | 52,3121% | 52,4169% |
+| P1 | −3,318571 Гц | +2,179939 Гц | 2,749255 Гц | 61,2846% | 42,1677% | 51,7262% |
+| P2 | −19,977856 Гц | +46,721234 Гц | 33,349545 Гц | 49,7775% | 50,2294% | 50,0035% |
+| P3 | −0,124881 Гц | +0,391708 Гц | 0,258294 Гц | 3,3089% | 3,9250% | 3,6170% |
+
+P3 дал средние EVM 0,84378 и matched/residual +1,4944 дБ, практически совпав
+с физической диагностикой Lab058 (0,84535 и +1,46485 дБ). Разница его средней
+SER с нижней диагностической ссылкой составляет +0,1211 процентного пункта.
+
+Для A1/A2 все методы сохранили среднюю SER 0,01776%. P3 дал EVM 0,31283/0,32516
+и ошибки CFO −0,0171/+0,0935 Гц относительно diagnostic reference. P2 сильнее
+ухудшил EVM A2 до 0,41255, что дополнительно показывает слабость короткого TRAIN.
+
+![Ошибка CFO](../data/processed/lab059/frequency_error_by_method.png)
+
+![Фазовый уход](../data/processed/lab059/burst_phase_drift.png)
+
+![Ошибки символов B](../data/processed/lab059/lab056_b_symbol_errors.png)
+
+## Synthetic Monte Carlo
+
+Чистая преамбула получена действующим TX/RX RRC-трактом при Fs 8 Мвыб/с:
+400 отсчётов/символ и 4001 tap для 20 ксимв/с, 16 отсчётов/символ и 161 tap для
+500 ксимв/с. После этого на выходе выбора символов добавлен комплексный AWGN с
+заранее заданным EVM 0,317390, 0,55 или 0,845350. Поэтому тест учитывает реальный
+RRC и дискретизацию в чистой форме, но не моделирует цветной или
+частотно-селективный остаток реального OTA-тракта.
+
+Для каждой из 17 частот, каждого качества и каждой скорости выполнено 300
+реализаций. В строке качества B для 500 ксимв/с каждый метод имеет 5100 оценок.
+
+| Метод | Bias | RMSE | Median abs | P95 abs | P99 abs | Катастрофические | P(≤0,25 Гц) | P(≤0,5 Гц) | P(≤1 Гц) |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|
+| P0 | −0,018 Гц | 6,808 Гц | 4,643 Гц | 13,265 Гц | 17,805 Гц | 72,08% | 3,06% | 5,86% | 11,61% |
+| P1 | +0,050 Гц | 3,728 Гц | 2,498 Гц | 7,437 Гц | 9,895 Гц | 50,98% | 5,24% | 10,47% | 21,27% |
+| P2 | +0,078 Гц | 12,264 Гц | 8,256 Гц | 23,709 Гц | 31,583 Гц | 83,12% | 1,65% | 3,67% | 7,20% |
+| P3 | +0,049 Гц | 7,089 Гц | 2,935 Гц | 8,528 Гц | 11,383 Гц | 57,94% | 4,90% | 9,61% | 18,25% |
+
+Модельная граница Крамера—Рао для известных символов, неизвестной постоянной
+фазы и комплексного AWGN равна
+`sqrt(6*EVM²*Rs² / ((2*pi)²*N*(N²−1)))`. При N=1280, Rs=500000 и
+EVM=0,845350 она даёт СКО не меньше примерно 3,598 Гц. P1 с RMSE 3,728 Гц
+близок к этому масштабу. Это model-dependent sanity check, а не утверждение,
+что реальный OTA-остаток является AWGN.
+
+При 20 ксимв/с P1 на том же EVM получил RMSE 0,1465 Гц и 99,92% попаданий в
+±0,5 Гц; длительность преамбулы там 64 мс. Разница показывает, что ограничение
+500 ксимв/с связано прежде всего с 25-кратно более коротким временем наблюдения,
+а не с ошибкой единиц или знака.
+
+![Распределение synthetic 500K](../data/processed/lab059/synthetic_500k_error_distribution.png)
+
+## Lab047 и Lab054
+
+Положительный контроль Lab047 не ухудшился: P0, P1, P2 и P3 каждый получили
+36/36 HEADER_ACCEPTED, 36/36 FEC_STARTED, 36/36 CRC_PASS и 36/36 PACKET_OUTPUT.
+Во всех методах суммарно осталось две ошибки преамбулы и ноль ошибок заголовка.
+
+Lab054 осталась отрицательной для всех методов:
+
+| Метод | Ошибки преамбулы, сумма | Raw header errors | Voted header errors | HEADER_ACCEPTED | FEC_STARTED | CRC_PASS | PACKET_OUTPUT |
+|---|---:|---:|---:|---:|---:|---:|---:|
+| P0 | 7767 | 946 | 283 | 0/16 | 0/16 | 0/16 | 0/16 |
+| P1 | 8264 | 1000 | 313 | 0/16 | 0/16 | 0/16 | 0/16 |
+| P2 | 8871 | 1085 | 348 | 0/16 | 0/16 | 0/16 | 0/16 |
+| P3 | 9020 | 1140 | 373 | 0/16 | 0/16 | 0/16 | 0/16 |
+
+Эти данные не превращают Lab054 в новый опыт и не меняют его исторический
+вердикт. Плохое физическое качество Lab054 не исправляется заменой одной
+оценки частоты.
+
+![Lab054](../data/processed/lab059/lab054_result_by_method.png)
+
+## Инженерный вывод
+
+`PREAMBLE_ONLY_INSUFFICIENT`.
+
+P3 показывает, что штатный P0 можно существенно улучшить на конкретной записи,
+но ни один preamble-only метод не обеспечивает устойчивую ошибку менее 0,5 Гц
+при качестве B. Следующий один шаг — полностью офлайн проверить
+decision-directed carrier tracking на протяжении burst, используя решения BPSK
+без знания правильного payload. Это сохраняет текущий формат пакета и позволяет
+использовать P3 как начальную оценку. Costas loop остаётся разумной альтернативой,
+но потребует отдельной настройки динамики петли. Periodic pilots дают явную опору,
+однако меняют формат и добавляют overhead, поэтому их логично рассматривать позже.
+
+Lab058 commit: `82f17499ace5e655991240348401b9700c7c3349`.
+Lab059 не коммитировалась. Push не выполнялся. RF TX = 0. Lab060 не создавалась.