Informes de ejecución
Cada ejecución de la interfaz de línea de comandos (CLI) escribe un informe junto a su resultado: una página imprimible en HyperText Markup Language (HTML), <scenario>.report.html, y un documento legible por máquina en JavaScript Object Notation (JSON), <scenario>.report.json, con el mismo contenido. El informe sirve para cualquier tipo de escenario y para campañas.
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.jsonEl documento de resultado responde qué calculó el motor. El informe añade lo que un lector necesita antes de actuar a partir de él: qué entró, en qué se apoyan las cifras, qué se dejó fuera y cómo obtener de nuevo los mismos bytes. No inventa nada de eso. Cada sección se lee de una fuente que el motor ya conserva y nombra la fuente junto a lo que cita.
El constructor es kshana::advanced_report (src/advanced_report.rs). Es una función pura de la salida de la ejecución, de los bytes del archivo de escenario y de la línea de comandos: no lee ningún reloj, ningún archivo ni la red, y se compila para WebAssembly.
Secciones#
| # | Sección | Qué contiene | Se lee de |
|---|---|---|---|
| 1 | Resumen ejecutivo | qué hace el tipo de escenario, el resumen de una línea de la ejecución, las cifras principales, la etiqueta de honestidad de la ejecución, el recuento de capacidades VALIDATED / MODELLED / PARTNER usadas | el catálogo de tipos de escenario (kshana kinds --json), el label del resultado, su bloque figure_tiers o de cifras de mérito, los percentiles de una campaña Monte Carlo |
| 2 | Entradas | cada campo que fija el archivo de escenario, aplanado hasta su ruta, con su unidad y de dónde procede la unidad | el archivo de escenario; unidades del bloque units del resultado (el esquema de unidades de campo, docs/field-units-schema.json), o, si no, del sufijo del nombre del campo (_s, _ns, _m, _deg, _dbw, …); una unidad que ninguno indica se imprime como no indicada |
| 3 | Resultados | el gráfico de la ejecución, cada escalar del documento de resultado con su unidad y un resumen de recuento / mínimo / máximo / primero / último de cada columna numérica | el documento de resultado y su bloque units |
| 3a | Agregación (campañas y barridos) | la tabla de nodos de un barrido; la media, la desviación típica, los percentiles 5 / 50 / 95 y el intervalo de confianza del 95 % de la media de una ejecución Monte Carlo, con un histograma por métrica; la tabla de fases de una cadena; las condiciones compartidas, los miembros y el resumen combinado de una composición | la sección sweep, monte_carlo, timeline o compose del resultado de la campaña; la cuadrícula de un resultado sweep o sweep-nd |
| 3b | Animación y exportaciones | el dibujo animado de la ejecución (la salida --animate svg) incrustado como imagen inerte, o por qué no lo hay; enlaces a los archivos de animación e interoperabilidad que el mismo comando escribió junto al informe; cada formato de exportación con indicación de si se aplica al escenario, por qué no, y su especificación |
el exportador de animación (src/animation.rs), interop::plan y los archivos que escribió la línea de comandos (--animate, --export) |
| 4 | Cronología de eventos | ventanas temporizadas y eventos puntuales, dibujados y tabulados sobre el eje de tiempo de la ejecución | tablas de escenario con t0/t1, on_s/off_s, start_s/end_s o un instante de inicio; el intervalo de la ejecución time.duration_s; cualquier matriz events del resultado; las fases y los traspasos de una campaña |
| 5 | Etiquetas de verificación | cada fila de la matriz de verificación que ejercitan los tipos de escenario de la ejecución, con su etiqueta, su referencia independiente y su evidencia de pruebas, y los niveles por cifra que indica el resultado | la matriz de verificación (src/verification.rs, docs/VERIFICATION-MATRIX.md), a través de la correspondencia de tipo de escenario a fila advanced_report::KIND_CAPABILITIES |
| 6 | Lo no modelado y las hipótesis | cada limitación, citada | los bloques not_modelled, not_implemented y honesty del resultado; las cláusulas MODELLED del catálogo de tipos de escenario; los comentarios de escenario y los textos de entrada que dicen «not modelled»; el motivo de la matriz por el que cada fila MODELLED sigue siendo modelada (docs/MODELLED-RATIONALE.md) |
| 7 | Registro de reproducibilidad | versión del motor, commit de origen, resúmenes del Secure Hash Algorithm de 256 bits (SHA-256) del archivo de escenario y del documento de resultado, semilla, plataforma, el comando exacto, la regla del directorio de trabajo, el resumen de cada archivo de entrada adicional | la compilación, los archivos, la línea de comandos |
Una sección sin nada que enumerar dice por qué en una frase (por ejemplo, «No timed event: the scenario scripts no window or onset time and the result reports no event»). Ninguna sección queda nunca vacía y en silencio.
Qué significa una etiqueta en el informe#
Una etiqueta de verificación califica la capacidad nombrada en una fila de la matriz, tal como la registra la matriz. No califica la configuración del escenario, y una fila VALIDATED no hace que las entradas de una ejecución sean medidas. Una fila PARTNER es una disciplina en la que se apoya la ejecución y que Kshana no proporciona (el hardware de antena para los tipos de escenario de radiofrecuencia, la carga útil cuántica para los tipos de escenario cuánticos, el bus de la nave para el presupuesto de actitud); el informe la muestra como se confía en ella, no se proporciona.
La correspondencia de tipo de escenario a filas es una tabla de cadenas requirement de la matriz. La etiqueta, la referencia independiente y la evidencia se vuelven a leer de la matriz al construir el informe, de modo que mover una fila entre VALIDATED y MODELLED mueve consigo todos los informes. Una campaña lleva la fila de su modo (cadena, barrido o Monte Carlo, composición) más cada fila de cada tipo de escenario miembro que ejecutó; sweep-nd lleva las filas del tipo de escenario que barrió. Toda ejecución lleva además la fila «Reproducibility & software assurance», en la que se apoya el registro de reproducibilidad.
Una fila que califica solo una ruta de entrada de un tipo de escenario figura únicamente cuando la ejecución siguió esa ruta (advanced_report::PATH_GATED_CAPABILITIES): orbit y ephemeris llevan la fila «Orbit propagation & determination» solo con un tle (la ruta de Simplified General Perturbations 4 (SGP4); una órbita analítica es una propagación de dos cuerpos), y slot-timing lleva la fila de registro medido solo con un oscillator.record. La misma tabla condiciona la fila multibanda de spectrum a que la ejecución dibuje [[panels]], y las filas de los tipos de escenario de órbita terrestre baja (LEO) a la ruta que siguió cada ejecución: una fila de lluvia, entrada en edificios, baja energía o spoofer de leo-pass o leo-pnt-chain solo cuando el escenario fija ese término, la fila de centelleo salvo que el escenario la desactive, una fila de posicionamiento puntual preciso de leo-navmsg, leo-pvt o de cadena solo para el análisis o el modo que lleva el resultado, y la fila de preajuste de sistema LEO solo cuando se usa un preajuste con nombre. La fila del lector de la Shuttle Radar Topography Mission (SRTM) no la lleva ningún tipo de escenario: terrain-nav y terrain-slam se ejecutan sobre un modelo digital de elevación (DEM) sintético, y ningún campo de escenario lee una tesela SRTM. Una fila VALIDATED que la ejecución no tocó afirmaría, de otro modo, una evidencia que la ejecución no tiene.
Reproducir una ejecución a partir de su informe#
report.json → reproducibility contiene todo lo necesario:
"command": "kshana clock-holdover.toml",
"argv": ["kshana", "clock-holdover.toml"],
"scenario_sha256": "430c364d…",
"result_sha256": "ee5ebb0a…",
"seed": 42,- Compruebe el archivo de escenario frente a
scenario_sha256, y cualquier archivo deinput_files(un archivo de orientación terrestre--eop) frente a su resumen. - Ejecute
commanddesde el directorio en el que se inició la ejecución original. La ruta del escenario y cualquier ruta de datos relativa dentro del escenario se resuelven respecto a él. - El nuevo
result.jsontiene el SHA-256 deresult_sha256, y los nuevosreport.jsonyreport.htmlson idénticos byte a byte a los antiguos.
tests/advanced_report_cli.rs hace exactamente esto para un escenario de reloj, una campaña encadenada, una campaña de barrido y una ejecución de órbita con un archivo --eop: lee el comando del informe, lo ejecuta en un directorio nuevo que contiene solo las entradas registradas y compara bytes.
scenario_sha256 es el resumen de los bytes exactos del archivo. El scenario_hash propio del resultado es otra cosa: la huella del tipo de escenario para el escenario (a menudo de una forma canónica), y el informe imprime ambos, etiquetados.
Semilla. La semilla es el seed del escenario o, en su defecto, la que indica el resultado. Para un tipo de escenario que no admite semilla, el informe lo dice y señala que el archivo de escenario y la compilación del motor bastan por sí solos para fijar el resultado.
Commit de origen. El motor registra el commit solo si se compiló con la variable de entorno KSHANA_GIT_COMMIT definida, leída en tiempo de compilación:
KSHANA_GIT_COMMIT=$(git rev-parse HEAD) cargo build --releaseUna compilación sin ella informa del commit como no registrado, y la versión del motor identifica la versión publicada. No se adivina nada.
Plataforma. Sistema operativo, arquitectura y familia de la compilación. Los resultados son idénticos byte a byte en una misma plataforma; entre plataformas, los resultados en coma flotante pueden diferir en las últimas cifras (véase REPRODUCIBILITY.md).
Determinismo y la única marca de tiempo#
Los mismos bytes de escenario, la misma semilla y la misma compilación del motor dan un report.json y un report.html idénticos byte a byte. El informe no lleva ninguna marca de tiempo. La única lectura de reloj en todo el crate es la que hace --study-name, que estampa meta.generated_utc en el documento de resultado; el informe muestra entonces esa marca y dice que es el único campo que una reproducción no igualará. Para evitarlo, ejecute sin --study-name. tests/advanced_report.rs construye dos veces el informe de cada archivo de escenario de scenarios/ (salvo el manifiesto de la suite) y vuelve a ejecutar seis escenarios (entre ellos una campaña de cada uno de los modos de cadena, barrido y composición) para comprobarlo de extremo a extremo.
Impresión a PDF#
El motor no escribe archivos Portable Document Format (PDF). Un escritor de PDF que renderizara los gráficos supondría una dependencia nueva y pesada, de modo que no existe la opción --report pdf. En su lugar, report.html incluye una hoja de estilos de impresión: ábralo en un navegador, imprima y elija «Guardar como PDF».
La hoja de estilos está escrita para A4 y para US Letter. No fija tamaño de papel (se aplica la elección del cuadro de impresión), mantiene márgenes de 15 mm / 14 mm que caben en ambas hojas, pasa a negro sobre blanco, repite los encabezados de tabla en cada página, impide que filas de tabla, figuras y tarjetas se partan entre páginas, mantiene los encabezados con el texto que les sigue y empieza en página nueva las secciones de entradas, resultados, etiquetas de verificación y reproducibilidad. La barra de navegación se oculta al imprimir.
El documento JSON#
report.json tiene report_schema = "kshana-report" y report_schema_version = "1.0", luego kind y title y una clave por sección: executive_summary, inputs, results, aggregation (solo campañas y barridos), events, capabilities, not_modelled, companions (sección 3b: animation, exports y export_command) y reproducibility. Una sección de lista tiene items, omitted (las filas que el límite de la página dejó fuera; el documento de resultado lleva todos los valores) y, cuando items está vacío, un statement que dice por qué. Un valor conserva su forma JSON sin procesar en value y el texto que muestra la página en display; un valor ausente es null en value y «no value» en display.
Límites, declarados con claridad#
- Unidades. Cuando ni el esquema de unidades de campo ni el nombre del campo dan una unidad, el informe dice «not stated» en lugar de adivinar. Las entradas anidadas dentro de los escenarios miembros de una campaña se resuelven solo con el bloque de unidades propio de la campaña y el sufijo del nombre del campo, de modo que más de ellas figuran como «not stated» que en una ejecución independiente.
- Criterio de correspondencia. Qué filas de la matriz ejercita un tipo de escenario es una tabla curada, comprobada por una prueba para que nombre exactamente una fila existente por entrada y cubra todos los tipos de escenario integrados. Que cada correspondencia sea la correcta es un juicio humano, como la propia elección de referencia independiente de la matriz.
- Límites. La página enumera como máximo 400 entradas, 150 resultados escalares, 60 columnas numéricas y 200 eventos;
omittedcuenta el resto. Una tabla de más de 24 filas dentro de un escenario (una serie ingerida) se resume por columna. - Suites.
kshana --study <suite.toml>conserva sus propios<suite>.study.jsony<suite>.study.html; no escribe este informe. - Bindings. Los bindings de Python y WebAssembly conservan
RunOutput::html_report(), la tarjeta de puntuación de una página; el informe descargable del entorno de pruebas es su propia página (web/studio/lib/report.mjs). Este informe lo escribe la CLI, y quienes llaman desde Rust pueden construirlo conkshana::advanced_report::build. El servidor del Model Context Protocol (MCP) lo devuelve desde su herramientareport_scenario, como JSON o como página HTML; el nombre del archivo de escenario en su comando de reproducción es el que pasa quien llama (por defectoscenario.toml), y no enumera ningún archivo complementario, ya que el servidor no escribe ninguno.