Отчёты о прогонах

Каждый запуск интерфейса командной строки (CLI) записывает рядом с результатом отчёт: печатную страницу на языке гипертекстовой разметки (HTML) <scenario>.report.html и машиночитаемый документ в формате JavaScript Object Notation (JSON) <scenario>.report.json с тем же содержимым. Отчёт работает для любого вида сценария и для кампаний.

kshana scenarios/clock-holdover.toml
# wrote scenarios/clock-holdover.result.json, scenarios/clock-holdover.chart.svg,
#   scenarios/clock-holdover.report.html, and scenarios/clock-holdover.report.json

Документ результата отвечает на вопрос что вычислил движок. Отчёт добавляет то, что нужно читателю, прежде чем действовать: что было на входе, на чём держатся числа, что было опущено и как получить те же байты снова. Он ничего из этого не выдумывает. Каждый раздел читается из источника, который движок уже хранит, и называет источник рядом с тем, что цитирует.

Построитель — kshana::advanced_report (src/advanced_report.rs). Это чистая функция от выходных данных запуска, байтов файла сценария и командной строки: он не читает ни часов, ни файлов, ни сети и собирается для WebAssembly.

Разделы#

Раздел, в котором нечего перечислять, объясняет причину одним предложением (например, «No timed event: the scenario scripts no window or onset time and the result reports no event»). Ни один раздел не бывает пустым и молчаливым.

Что означает метка в отчёте#

Метка верификации оценивает возможность, названную в строке матрицы, в том виде, как её фиксирует матрица. Она не оценивает конфигурацию сценария, и строка VALIDATED не делает входные данные запуска измеренными. Строка PARTNER — это дисциплина, на которую запуск опирается и которую Kshana не обеспечивает (антенное оборудование для радиочастотных видов, квантовая полезная нагрузка для квантовых видов, служебная платформа космического аппарата для бюджета ориентации); отчёт показывает её как используется, не обеспечивается.

Таблица соответствия «вид — строки» состоит из строк requirement матрицы. Метка, оракул и свидетельства считываются из матрицы при построении отчёта, поэтому перенос строки между VALIDATED и MODELLED переносит вместе с ней каждый отчёт. Кампания несёт строку своего режима (цепочка, перебор или Монте-Карло, композиция) плюс каждую строку каждого вида-члена, который она запускала; sweep-nd несёт строки перебираемого вида. Каждый запуск также несёт строку «Reproducibility & software assurance», на которой держится запись о воспроизводимости.

Строка, оценивающая только один путь ввода вида, указывается лишь тогда, когда запуск пошёл по этому пути (advanced_report::PATH_GATED_CAPABILITIES): orbit и ephemeris несут строку «Orbit propagation & determination» только при наличии tle (путь Simplified General Perturbations 4 (SGP4); аналитическая орбита — это двухтельное распространение), а slot-timing несёт строку измеренной записи только при oscillator.record. Та же таблица ограничивает строку многодиапазонности spectrum запуском, рисующим [[panels]], и строки видов низкой околоземной орбиты (LEO) путём, по которому пошёл каждый запуск: строка дождя, проникновения в здание, малой энергии или спуфера для leo-pass или leo-pnt-chain — только если сценарий задаёт этот член, строка мерцаний — если сценарий не отключает его, строка точного абсолютного позиционирования для leo-navmsg, leo-pvt или цепочки — только для анализа или режима, который несёт результат, а строка предустановки системы LEO — только при использовании именованной предустановки. Строка считывателя Shuttle Radar Topography Mission (SRTM) не несётся ни одним видом: terrain-nav и terrain-slam работают на синтетической цифровой модели высот (DEM), и ни одно поле сценария не читает тайл SRTM. Строка VALIDATED, которой запуск не касался, иначе заявляла бы свидетельства, которых у запуска нет.

Воспроизведение прогона по его отчёту#

report.json → reproducibility содержит всё необходимое:

"command": "kshana clock-holdover.toml",
"argv": ["kshana", "clock-holdover.toml"],
"scenario_sha256": "430c364d…",
"result_sha256": "ee5ebb0a…",
"seed": 42,

1. Сверьте файл сценария с scenario_sha256, а любой файл из input_files (файл ориентации Земли --eop) — с его контрольной суммой.
2. Запустите command из каталога, в котором был начат исходный прогон. Путь к сценарию и любой относительный путь к данным внутри сценария разрешаются относительно него.
3. У нового result.json SHA-256 совпадает со значением в result_sha256, а новые report.json и report.html побайтово совпадают со старыми.

tests/advanced_report_cli.rs делает ровно это для сценария часов, составной кампании со связкой прогонов, кампании с перебором параметров и прогона орбиты с файлом --eop: тест считывает команду из отчёта, запускает её в чистом каталоге, где лежат только записанные входные файлы, и сравнивает байты.

scenario_sha256 — это контрольная сумма точных байтов файла. Собственный scenario_hash результата — другое: отпечаток сценария, который вычисляет данный вид сценария (часто по каноническому виду), и отчёт выводит оба значения с подписями.

Начальное значение (seed). Это seed сценария, а если его нет, то значение, которое указано в результате. Для вида сценария, который не принимает seed, отчёт сообщает об этом и о том, что результат определяют только файл сценария и сборка движка.

Исходный коммит. Движок записывает коммит, только если он собран с заданной переменной окружения KSHANA_GIT_COMMIT, которая считывается при компиляции:

KSHANA_GIT_COMMIT=$(git rev-parse HEAD) cargo build --release

Если сборка выполнена без неё, отчёт указывает, что коммит не записан, а выпуск определяется версией движка. Ничего не угадывается.

Платформа. Операционная система, архитектура и семейство сборки. На одной платформе результаты совпадают побайтово; на разных платформах результаты с плавающей запятой могут отличаться в последних разрядах (см. REPRODUCIBILITY.md).

Детерминированность и единственная отметка времени#

Одни и те же байты сценария, seed и сборка движка дают побайтово идентичные report.json и report.html. В отчёте нет отметки времени. Единственное обращение к часам во всём крейте — то, которое выполняет --study-name: оно записывает meta.generated_utc в документ результата; затем отчёт показывает эту отметку и сообщает, что это единственное поле, которое при воспроизведении не совпадёт. Чтобы избежать этого, запускайте без --study-name. tests/advanced_report.rs дважды строит отчёт для каждого файла сценария в scenarios/ (кроме манифеста набора) и повторно запускает шесть сценариев (среди них по одной кампании в режимах chain, sweep и compose), чтобы проверить это от начала до конца.

Печать в PDF#

Движок не записывает файлы Portable Document Format (PDF). Модуль записи PDF, отрисовывающий графики, потребовал бы новой тяжёлой зависимости, поэтому параметра --report pdf нет. Вместо этого report.html содержит таблицу стилей для печати: откройте файл в браузере, выберите печать и укажите «Сохранить как PDF».

Таблица стилей рассчитана как на A4, так и на US Letter. Она не задаёт размер бумаги (действует выбор в диалоге печати), сохраняет поля 15 мм / 14 мм, подходящие для обоих форматов, переключается на чёрное на белом, повторяет заголовки таблиц на каждой странице, не разрывает строки таблиц, рисунки и карточки между страницами, держит заголовки вместе со следующим за ними текстом и начинает разделы входных данных, результатов, меток верификации и воспроизводимости с новой страницы. Панель навигации при печати скрыта.

Документ JSON#

В report.json есть report_schema = "kshana-report" и report_schema_version = "1.0", затем kind и title и по одному ключу на раздел: executive_summary, inputs, results, aggregation (только для кампаний и переборов), events, capabilities, not_modelled, companions (раздел 3b: animation, exports и export_command) и reproducibility. У раздела-списка есть items, omitted (строки, не поместившиеся из-за ограничения страницы; документ результата содержит все значения) и, когда items пуст, statement с объяснением причины. Значение сохраняет исходный вид JSON в value, а текст, который показывает страница, — в display; отсутствующее значение — это null в value и «no value» в display.

Ограничения, изложенные прямо#

• Единицы. Если единицу не задаёт ни схема единиц полей, ни имя поля, отчёт пишет «not stated», а не угадывает. Входные данные внутри сценариев-участников кампании разрешаются только по собственному блоку единиц кампании и суффиксу имени поля, поэтому у них «not stated» встречается чаще, чем в автономном прогоне.
• Суждение о сопоставлении. Какие строки матрицы затрагивает данный вид сценария, определяет составленная вручную таблица; тест проверяет, что каждая запись называет ровно одну существующую строку и что таблица охватывает все встроенные виды. Верно ли каждое сопоставление — это суждение человека, как и выбор оракула в самой матрице.
• Ограничения. Страница перечисляет не более 400 входных данных, 150 скалярных результатов, 60 числовых столбцов и 200 событий; omitted считает остальные. Таблица из более чем 24 строк внутри сценария (загруженный ряд) сводится по столбцам.
• Suites. kshana --study <suite.toml> хранит собственные <suite>.study.json и <suite>.study.html; этот отчёт он не записывает.
• Привязки. Привязки Python и WebAssembly сохраняют RunOutput::html_report() — одностраничную сводную карточку; загружаемый отчёт песочницы — это отдельная страница (web/studio/lib/report.mjs). Этот отчёт записывает CLI, а вызывающий код на Rust может построить его с помощью kshana::advanced_report::build. Сервер Model Context Protocol (MCP) возвращает его из своего инструмента report_scenario в виде JSON или HTML-страницы; имя файла сценария в команде воспроизведения — то, которое передаёт вызывающая сторона (по умолчанию scenario.toml), и сервер не перечисляет сопутствующих файлов, поскольку не записывает их.