Relatórios de execução

Toda execução da interface de linha de comando (CLI) grava um relatório ao lado de seu resultado: uma página HyperText Markup Language (HTML) imprimível, <scenario>.report.html, e um documento JavaScript Object Notation (JSON) legível por máquina, <scenario>.report.json, com o mesmo conteúdo. O relatório funciona para qualquer tipo de cenário e para campanhas.

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

O documento de resultado responde a o que o motor calculou. O relatório acrescenta o que um leitor precisa antes de agir com base nele: o que entrou, em que os números se apoiam, o que foi deixado de fora e como obter os mesmos bytes de novo. Ele não inventa nada disso. Cada seção é lida de uma fonte que o motor já mantém e nomeia a fonte ao lado do que cita.

O construtor é kshana::advanced_report (src/advanced_report.rs). É uma função pura da saída da execução, dos bytes do arquivo de cenário e da linha de comando: não lê relógio, arquivo nem rede, e compila para WebAssembly.

Seções#

Uma seção sem nada a listar diz o motivo em uma frase (por exemplo, "Nenhum evento temporizado: o cenário não programa nenhuma janela ou tempo de início e o resultado não informa nenhum evento"). Nenhuma seção fica vazia e em silêncio.

O que significa um rótulo no relatório#

Um rótulo de verificação avalia a capacidade nomeada em uma linha da matriz, tal como a matriz a registra. Ele não avalia a configuração do cenário, e uma linha VALIDATED não faz com que as entradas de uma execução sejam medidas. Uma linha PARTNER é uma disciplina em que a execução se apoia e que o Kshana não fornece (hardware de antena para os tipos de cenário de radiofrequência, a carga útil quântica para os tipos de cenário quânticos, o barramento da espaçonave para o orçamento de atitude); o relatório a mostra como dependida, não fornecida.

A correspondência entre tipo de cenário e linhas é uma tabela de strings requirement da matriz. O rótulo, a referência independente e a evidência são relidos da matriz quando o relatório é construído, de modo que mover uma linha entre VALIDATED e MODELLED move com ela todo relatório. Uma campanha traz a linha de seu modo (cadeia, varredura ou Monte Carlo, composição) mais toda linha de cada tipo de cenário membro que executou; sweep-nd traz as linhas do tipo de cenário que varreu. Toda execução também traz a linha "Reproducibility & software assurance", em que o registro de reprodutibilidade se apoia.

Uma linha que avalia apenas um caminho de entrada de um tipo de cenário só é listada quando a execução seguiu esse caminho (advanced_report::PATH_GATED_CAPABILITIES): orbit e ephemeris trazem a linha "Orbit propagation & determination" apenas com um tle (o caminho Simplified General Perturbations 4 (SGP4); uma órbita analítica é uma propagação de dois corpos), e slot-timing traz a linha de registro medido apenas com um oscillator.record. A mesma tabela condiciona a linha multibanda de spectrum a que a execução desenhe [[panels]], e as linhas dos tipos de cenário de órbita terrestre baixa (LEO) ao caminho que cada execução seguiu: uma linha de chuva, de entrada em edifício, de baixa energia ou de spoofer em leo-pass ou leo-pnt-chain apenas quando o cenário define esse termo, a linha de cintilação a menos que o cenário a desligue, uma linha de posicionamento por ponto preciso em leo-navmsg, leo-pvt ou em cadeia apenas para a análise ou o modo que o resultado traz, e a linha de predefinição de sistema LEO apenas quando uma predefinição nomeada é usada. A linha do leitor da Shuttle Radar Topography Mission (SRTM) não é trazida por nenhum tipo de cenário: terrain-nav e terrain-slam rodam em um modelo digital de elevação (DEM) sintético, e nenhum campo de cenário lê um ladrilho SRTM. Uma linha VALIDATED que a execução nunca tocou alegaria, de outro modo, uma evidência que a execução não tem.

Reproduzir uma execução a partir de seu relatório#

report.json → reproducibility contém tudo o que é necessário:

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

1. Verifique o arquivo de cenário em relação a scenario_sha256, e qualquer arquivo em input_files (um arquivo de orientação da Terra --eop) em relação ao seu resumo.
2. Execute command a partir do diretório em que a execução original foi iniciada. O caminho do cenário e qualquer caminho relativo de dados dentro do cenário são resolvidos em relação a ele.
3. O novo result.json tem o SHA-256 de result_sha256, e o novo report.json e o novo report.html são idênticos byte a byte aos antigos.

tests/advanced_report_cli.rs faz exatamente isso para um cenário de relógio, uma campanha em cadeia, uma campanha de varredura e uma execução de órbita com um arquivo --eop: lê o comando do relatório, executa-o em um diretório novo que contém apenas as entradas registradas e compara os bytes.

scenario_sha256 é o resumo dos bytes exatos do arquivo. O scenario_hash do próprio resultado é outra coisa: a impressão digital do tipo de cenário para o cenário (muitas vezes de uma forma canônica), e o relatório imprime ambos, rotulados.

Semente. A semente é o seed do cenário, senão a que o resultado declara. Para um tipo de cenário que não usa semente, o relatório diz isso, e diz que apenas o arquivo de cenário e a compilação do motor fixam o resultado.

Commit de origem. O motor registra o commit apenas se foi compilado com a variável de ambiente KSHANA_GIT_COMMIT definida, lida em tempo de compilação:

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

Uma compilação sem ela informa o commit como não registrado, e a versão do motor identifica a versão publicada. Nada é adivinhado.

Plataforma. Sistema operacional, arquitetura e família da compilação. Os resultados são idênticos byte a byte em uma mesma plataforma; entre plataformas, os resultados em ponto flutuante podem diferir nos últimos dígitos (veja REPRODUCIBILITY.md).

Determinismo e o único carimbo de tempo#

O mesmo conteúdo de cenário, a mesma semente e a mesma compilação do motor dão report.json e report.html idênticos byte a byte. O relatório não traz carimbo de tempo. A única leitura de relógio em todo o crate é a que --study-name faz, que grava meta.generated_utc no documento de resultado; o relatório então mostra esse carimbo e diz que é o único campo que uma reprodução não vai igualar. Para evitá-lo, execute sem --study-name. tests/advanced_report.rs constrói o relatório de todo arquivo de cenário em scenarios/ (exceto o manifesto da suíte) duas vezes e reexecuta seis cenários (entre eles uma campanha de cada um dos modos cadeia, varredura e composição) para verificar isso de ponta a ponta.

Impressão em PDF#

O motor não grava arquivos Portable Document Format (PDF). Um gerador de PDF que renderizasse os gráficos exigiria uma dependência nova e pesada, de modo que não há opção --report pdf. Em vez disso, report.html traz uma folha de estilo de impressão: abra-o em um navegador, imprima e escolha "Salvar como PDF".

A folha de estilo é escrita para A4 e para US Letter. Ela não define tamanho de papel (vale a escolha da caixa de diálogo de impressão), mantém margens de 15 mm / 14 mm que servem em qualquer das folhas, muda para preto sobre branco, repete os cabeçalhos de tabela em cada página, impede que linhas de tabela, figuras e cartões sejam divididos entre páginas, mantém os títulos junto ao texto que os segue e começa as seções de entradas, resultados, rótulos de verificação e reprodutibilidade em uma nova página. A barra de navegação fica oculta na impressão.

O documento JSON#

report.json tem report_schema = "kshana-report" e report_schema_version = "1.0", depois kind e title e uma chave por seção: executive_summary, inputs, results, aggregation (apenas campanhas e varreduras), events, capabilities, not_modelled, companions (seção 3b: animation, exports e export_command) e reproducibility. Uma seção de lista tem items, omitted (as linhas que o limite da página deixou de fora; o documento de resultado traz todos os valores) e, quando items está vazio, uma statement dizendo o motivo. Um valor mantém sua forma JSON bruta em value e o texto que a página mostra em display; um valor ausente é null em value e "sem valor" em display.

Limites, declarados com clareza#

• Unidades. Onde nem o esquema de unidades de campo nem o nome do campo dão uma unidade, o relatório diz "não declarada" em vez de adivinhar. As entradas aninhadas nos cenários membros de uma campanha são resolvidas apenas em relação ao bloco de unidades da própria campanha e ao sufixo do nome do campo, de modo que mais delas aparecem como "não declarada" do que em uma execução isolada.
• Julgamento da correspondência. Quais linhas da matriz um tipo de cenário exercita é uma tabela curada, verificada por um teste para nomear exatamente uma linha existente por entrada e para cobrir todo tipo de cenário embutido. Se cada mapeamento é o correto é um julgamento humano, como a própria escolha da referência independente da matriz.
• Limites. A página lista no máximo 400 entradas, 150 resultados escalares, 60 colunas numéricas e 200 eventos; omitted conta o restante. Uma tabela com mais de 24 linhas dentro de um cenário (uma série ingerida) é resumida por coluna.
• Suites. kshana --study <suite.toml> mantém seus próprios <suite>.study.json e <suite>.study.html; não grava este relatório.
• Bindings. Os bindings de Python e WebAssembly mantêm RunOutput::html_report(), o painel de resultados de uma página; o relatório baixável do playground é sua própria página (web/studio/lib/report.mjs). Este relatório é gravado pela CLI, e chamadores em Rust podem construí-lo com kshana::advanced_report::build. O servidor do Model Context Protocol (MCP) o devolve a partir de sua ferramenta report_scenario, como JSON ou como página HTML; o nome do arquivo de cenário em seu comando de reprodução é o que o chamador passa (padrão scenario.toml), e ele não lista nenhum arquivo acompanhante, já que o servidor não grava nenhum.