Schéma des résultats — lire un `*.result.json` de Kshana

Chaque exécution écrit, à côté du scénario, un artefact JSON (JavaScript Object Notation) versionné et auto-descriptif. Cette page est le guide du lecteur, rédigé à la main, de l'enveloppe d'échange et des structures de résultats d'horloge et d'orbite : l'unité de chaque champ, l'endroit du code source où il est calculé et la manière de le lire. Le type de référence est RunResult dans src/report.rs ; les indicateurs de performance sont FoMScores dans src/fom.rs.

Ce n'est pas la référence complète des champs. Le moteur aiguille l'exécution sur beaucoup plus de types que ces deux-là, et chacun produit son propre paquet. La référence complète — unité, classe de provenance et définition de chaque champ numérique de chaque type intégré — est générée, non rédigée à la main : voir Unités et provenance, par champ, pour chaque type ci-dessous.

Enveloppe d'échange (KIF, le Kshana Interchange Format) — reconnaître un artefact et en vérifier la version#

Les artefacts Kshana peuvent être encapsulés dans une enveloppe d'échange neutre et auto-descriptive, afin qu'un outil tiers puisse reconnaître le fichier et décider s'il sait le lire avant de s'engager sur un schéma de charge utile. Le type de référence est Envelope dans src/interchange.rs.

Clé	Type	Signification
`format`	chaîne	Toujours `"kshana-interchange"` (`FORMAT_TAG`) — c'est ainsi qu'un outil étranger reconnaît un artefact Kshana.
`schema_version`	chaîne	La version de schéma `MAJOR.MINOR` (`SCHEMA_VERSION`, la source de vérité unique pour toute la crate).
`kind`	chaîne	Type d'artefact, p. ex. `"scenario"`, `"run-result"`, `"trade-study"` — permet à un consommateur d'aiguiller sans analyser le corps.
`engine_version`	chaîne	Version de la crate (`Cargo.toml`) qui a produit la charge utile.
`payload`	objet	L'artefact encapsulé, en JSON canonique (un `Scenario`, un `RunResult`, …).

Contrat de compatibilité. Les versions sont de la forme MAJOR.MINOR. Les nouveaux champs sont ajoutés avec #[serde(default)] (la discipline additive), si bien qu'un lecteur peut analyser tout artefact de la même version majeure et d'une version mineure égale ou plus ancienne (Compatible). Une version mineure strictement plus récente (ForwardIncompatible) peut porter des champs que ce lecteur ne peut pas honorer, et une version majeure différente (MajorIncompatible) constitue une rupture structurelle — les deux sont refusées par Envelope::parse, qui valide l'étiquette de format et la version à la frontière au lieu d'analyser de travers, sans le signaler, une entrée étrangère.

Déterminisme. L'enveloppe ne contient aucun horodatage — la promesse de reproductibilité de Kshana (scenario + seed + engine_version reproduit une exécution) l'exige. La provenance se trouve dans engine_version et dans le scenario_hash propre à la charge utile.

Une relecture typée (Envelope::payload_as::<T>()) fonctionne pour toute charge utile qui implémente Deserialize (p. ex. Scenario). Les artefacts de résultats sont en sérialisation seule par conception et se lisent comme la valeur JSON brute de payload.

Niveau supérieur (paquets d'horloge et d'orbite)#

Clé	Type / unité	Signification	Source
`schema_version`	chaîne	Version du schéma de résultats (indépendante de la version du moteur).	`report.rs`
`engine_version`	chaîne	Version de la crate (`Cargo.toml`) qui a produit le fichier.	`report.rs`
`scenario_hash`	chaîne hexadécimale	SHA-256 (SHA : Secure Hash Algorithm) du JSON canonique du scénario — l'exécution est reproductible à partir de `scenario + seed + engine_version`.	`report.rs:hash_scenario`
`seed`	u64	Graine du RNG (générateur de nombres aléatoires) pour l'exécution quantique (l'exécution classique utilise `seed + 0x9e3779b97f4a7c15`).	`run.rs`
`threshold_ns`	nanosecondes	La spécification de synchronisation temporelle : une erreur comprise dans ±`threshold_ns` est « dans la spécification ».	scénario
`quantum`	objet (`ClockRun`)	L'exécution du capteur quantique (voir ci-dessous).	`report.rs`
`classical`	objet (`ClockRun`)	L'exécution du capteur classique, à titre de comparaison.	`report.rs`
`units`	objet	Table des unités et de la provenance par champ pour ce document, indexée par chemin de champ. Voir §Unités et provenance ci-dessous.	`field_schema.rs:units_block`
`evidence`	objet	(0,40) L'étiquette de preuve de l'exécution : `tier` (`VALIDATED`, `MODELLED` ou `PARTNER` : le statut le plus faible parmi les lignes, de sorte qu'elle ne prétend jamais à plus que sa ligne la plus faible), `matrix` (`docs/VERIFICATION-MATRIX.md`), `id_rule` et `rows`, un par ligne de la matrice de vérification que l'exécution a mise en jeu (les lignes que liste son rapport avancé, issues de `advanced_report::KIND_CAPABILITIES`) : `id` (`VM-` et les 8 premiers chiffres hexadécimaux du SHA-256 du texte d'exigence de la ligne), `requirement` et `status`, tous lus dans la matrice, aucun saisi à la main. Ajoutée par `api::run_toml` au résultat de chaque type, avant le bloc `figure_tiers` final lorsqu'il y en a un (ce bloc reste la dernière clé) ; `evidence_label::strip_json` la retire octet pour octet. Le SVG du graphique et le tableau CSV de la même exécution portent la même étiquette (`<metadata id="kshana-evidence">` et une ligne visible sous le graphique ; lignes de commentaire `# evidence:` en tête du CSV). Les membres de campagne intégrés au résultat d'un autre type n'en portent aucune : le document externe en porte une. Ne porte aucun nombre.	`evidence_label.rs`
`figure_tiers`	objet	Le niveau de vérification de chaque indicateur de performance rapporté, et toujours la dernière clé du document. `figures` liste une entrée par indicateur présent : `path` (p. ex. `quantum.fom.timing_p95_ns`), `tier` (`VALIDATED` = vérifié par rapport à une référence indépendante externe, `MODELLED` = issu des premiers principes, testé en interne), `requirement` (la ligne de la matrice de vérification dont le niveau est tiré) et `applicable`. `applicable` vaut `false`, avec un `reason`, pour `security` dans tout scénario sans attaque configurée : la borne reste dans `fom.security`, mais elle ne répond à aucune question posée par le scénario. `untiered` liste tout indicateur qu'aucune ligne de la matrice ne possède (les indicateurs de position `hybrid` et `fusion`), au lieu de lui attribuer un niveau. Émis par les types `clock` (exécution unique et ensemble Monte Carlo), `orbit`, `hybrid` et `fusion`, qui le construisent pendant leur exécution, et (0,36, RM-04) par tous les autres types pour leurs indicateurs principaux, ajouté après l'exécution à partir de la table par type `fom_label::kind_figures` ; `api::without_figure_tiers` le retire pour retrouver, octet pour octet, le document sans niveaux. Non émis par `lunar-station-coverage`, dont le résultat est une prédiction figée et préenregistrée (`docs/predictions/lunar-reference-station.md`) : ce type n'a pas de `figure_tiers` tant qu'une nouvelle prédiction datée ne remplace pas la précédente. Également non émis par `leo-ppp`, `solar-system`, `optical-atmosphere` (0,37 ; tableaux par site), `sweep` et `sweep-nd`, qui n'ont aucun indicateur principal scalaire, ni par `lunar-attack-surface`, dont le document est du JSON compact (`fom_label::KINDS_EXCLUDED_FROM_FIGURE_TIERS` donne chaque raison), ni par les documents de membres intégrés d'une campagne. Ne contient aucun nombre.	`fom_label.rs:figure_tiers`, `fom_label.rs:kind_figure_tiers`
`geometry`	objet, facultatif	Résumé de géométrie du paquet d'orbite : `samples_total`, `samples_with_fix`, `sigma_uere_m` (m, le budget d'erreur de distance par satellite, issu du modèle), `best_pdop` / `median_pdop` (sans dimension) et `best_position_sigma_m` / `median_position_sigma_m` (m, PDOP (dilution de précision en position) × `sigma_uere_m`). Paquet d'orbite uniquement.	`orbit.rs`
`eci_track`	tableau de `[x, y, z]` km, facultatif	Trace inertielle géocentrique propagée du véhicule spatial de l'utilisateur, une entrée par instant échantillonné. Paquet d'orbite uniquement ; omise sinon. Sortie seule — non hachée.	`report.rs`
`meta`	objet (`StudyMeta`), facultatif	Métadonnées additives du rapport (titre de l'étude, horodatage de génération, auteur, avertissement). Omises en leur absence, de sorte qu'une exécution sans métadonnées est identique octet pour octet à la sortie historique. Sortie seule — non hachée.	`report.rs`

`ClockRun` (pour chacun de `quantum` / `classical`)#

Clé	Type / unité	Signification
`spec.id`	chaîne	Identifiant du capteur (p. ex. `optical-sr-lattice`).
`spec.kind`	chaîne	Type de modèle (p. ex. `clock`).
`spec.provenance`	chaîne	Citation ou source des paramètres du capteur.
`spec.params`	objet	Les paramètres bruts du modèle utilisés.
`series`	tableau de `{t, error_ns, gnss}`	Série temporelle par pas : `t` secondes, `error_ns` l'erreur de synchronisation temporelle en nanosecondes, `gnss` l'un de `nominal`/`degraded`/`denied`.
`fom`	objet (`FoMScores`)	Les indicateurs de performance évalués (ci-dessous).
`adev_curve`	tableau de `{tau_s, adev, n_samples, noise, edf, ci_lo, ci_hi}`	Écart-type d'Allan avec recouvrement : `tau_s` le temps de moyennage (s), `adev` la stabilité fractionnaire de fréquence σ_y(τ), sans dimension, `n_samples` le nombre de recouvrements derrière ce point, `noise` le type de loi de puissance identifié à partir de la pente du MDEV (écart-type d'Allan modifié) (p. ex. `WhiteFm`), `edf` le nombre de degrés de liberté effectifs propre au type de bruit, et `ci_lo`/`ci_hi` la bande de confiance à 95 % fondée sur le χ² pour `adev` à ce τ. Calculé dans `allan.rs:overlapping_adev_curve`.
`filter_health`	objet, facultatif	Évaluation de la cohérence du filtre de Kalman (NIS/NEES (NIS : carré normalisé de l'innovation ; NEES : carré normalisé de l'erreur d'estimation) par rapport à leurs bandes du χ²), calculée dans `filter_health.rs` ; omise pour les exécutions qui ne l'évaluent pas.

`FoMScores` (l'objet `fom`)#

Champ	Unité	Signification	Source	Réserve
`timing_rms_ns`	ns	Erreur de phase d'horloge (synchronisation temporelle) en valeur quadratique moyenne (RMS) sur la durée de la coupure.	`fom.rs:score`	une métrique de synchronisation temporelle, et non de position
`timing_p95_ns`	ns	Erreur de synchronisation temporelle au 95e centile sur la durée de la coupure.	`fom.rs:score`
`holdover_s`	s	Marche libre dans la spécification, au pire cas (la plus courte), parmi les segments de coupure.	`fom.rs:worst_case_holdover`	borné par la grille — une borne inférieure à la résolution du pas de temps
`resilience_slope_ns_per_s`	ns/s	Taux de croissance de \|erreur\| pendant la coupure, au sens des moindres carrés.	`fom.rs:score`
`availability`	fraction [0 1]	Fraction de l'exécution entière disposant d'une solution dans la spécification.	`fom.rs:score`
`integrity`	fraction [0 1] ou null	Auto-cohérence du filtre : fraction des échantillons de la coupure dont l'erreur réelle reste à l'intérieur de la borne k-σ de Kalman.	`run.rs`	PAS de l'intégrité HPL/VPL/RAIM (HPL : niveau de protection horizontal ; VPL : niveau de protection vertical ; RAIM : surveillance autonome de l'intégrité par le récepteur) — voir `INTEGRITY.md`
`security`	fraction [0 1] ou null	Borne analytique de détectabilité du leurrage fondée sur la stabilité de l'horloge.	`run.rs` + `security.rs`	n'a de sens qu'avec une attaque configurée ; les paquets d'horloge et d'orbite (qui n'en configurent aucune) la marquent donc `applicable: false` dans `figure_tiers` et l'impriment comme `n/a (no attack)` dans le résumé ; pas un détecteur RAIM multisatellite

À quoi ressemble un « bon » résultat#

Une horloge plus stable (adev_curve plus bas) donne un holdover_s plus long et une borne de détectabilité security plus élevée — c'est le contraste entre quantique et classique.
availability proche de 1,0 signifie que le système est resté dans la spécification presque toute l'exécution ; pendant une longue coupure, elle baisse pour l'horloge la plus bruitée.
integrity proche de 1,0 signifie que la borne d'incertitude propre au filtre était honnête quant à son erreur — une affirmation d'auto-cohérence, et non une garantie de sauvegarde de la vie humaine.

Autres types de scénario#

Chaque autre type émet sa propre structure de résultats. Quelques-uns des plus courants :

inertial : indicateurs de performance dans le domaine de la position, en mètres (pos_rms_m, pos_p95_m) — à un seul axe (1-DOF (DOF : degré de liberté)), à une seule graine (voir CAPABILITY.md).
hybrid / fusion : timing_spec_ns et position_spec_m au niveau supérieur, et, pour chaque côté, les indicateurs de synchronisation temporelle et de position d'une suite de capteurs (position_p95_m, position_holdover_s et pnt_holdover_s, la durée jusqu'à ce que l'une ou l'autre spécification soit dépassée), avec un bloc figure_tiers comme celui du paquet d'horloge, dans lequel les indicateurs de position sont listés comme untiered.
spoof : décalage de leurrage à chaque pas par rapport à la borne de détection de l'horloge, et indication de si le leurrage a atteint la spécification avant d'être détecté (src/spoof.rs).
skyline (orbit et integrity avec user_site, gnss-sim, jamming, leo-pvt, leo-pass ; présent seulement lorsque le scénario comporte une section [skyline], de sorte qu'un scénario sans elle reste inchangé) : un objet skyline au niveau supérieur avec source (chaîne : preset:<name>, preset:<name>+overrides ou custom), open_fraction (fraction [0 1] de l'angle solide de l'hémisphère supérieur au-dessus de max(mask_deg, skyline)) et provenance (chaîne) ; par échantillon, masked_by_skyline (nombre de satellites au-dessus du masque mais derrière la ligne d'horizon : epochs[] de integrity et jamming, gnss_measurements[] de gnss-sim, joint.epochs[] de leo-pvt) ; et, pour leo-pass, satellites[].pass.epochs_masked_by_skyline (nombre d'époques). Leurs unités et classes de provenance figurent dans le bloc units (src/skyline.rs UNITS ; SKYLINE.md).

Pour l'ensemble précis des champs d'un type, lisez son entrée dans field-units-schema.json (ci-dessous), la section de ce type dans SCENARIOS.md, ou la structure *Result correspondante dans src/.

Autres fichiers écrits par une exécution#

En plus de <scenario>.result.json, la CLI (interface en ligne de commande) écrit <scenario>.chart.svg, un <scenario>.report.html imprimable et le même rapport sous la forme <scenario>.report.json, dont le bloc reproducibility consigne la version du moteur, le SHA-256 du fichier de scénario, la graine, la plateforme et la commande exacte (voir REPORTS.md et REPRODUCIBILITY.md). Les types qui publient une table de reproductibilité écrivent aussi <scenario>.table.csv (CSV : valeurs séparées par des virgules). --export écrit des fichiers d'échange (voir INTEROP.md) et --animate une animation (voir ANIMATION.md).

Unités et provenance, par champ, pour chaque type#

Cette page est rédigée à la main et couvre les paquets d'horloge et d'orbite. Son pendant lisible par machine couvre chaque type intégré :

Dans le résultat lui-même. Le document de résultats de chaque scénario porte un objet units de niveau supérieur qui associe le chemin d'un champ émis à {"unit", "provenance", "note"}. La grammaire des chemins (un tableau contribue un seul segment suffixé par [], partagé par ses lignes ; * est un joker d'un seul segment pour les objets dont les clés sont des données) et le vocabulaire fermé de provenance sont définis dans src/field_schema.rs.
En un seul fichier. field-units-schema.json est l'union recueillie : pour chaque type, chaque champ numérique qu'il émet à une source indiquée, avec son unité, sa classe de provenance, son niveau de preuve et sa définition — et, nommé plutôt qu'omis, chaque champ qui n'en a pas encore. Son bloc coverage porte les décomptes.

Les deux sont imposés par tests/field_units_global.rs, qui exécute chaque type enregistré et échoue si un champ numérique émis n'a pas d'unité et de classe de provenance. Les types pas encore couverts sont nommés un à un dans UNCOVERED_KINDS de ce fichier, avec la raison pour laquelle chacun reste ouvert, et leur nombre est figé afin que la liste ne puisse que diminuer.

Régénérez le JSON après tout changement de la forme d'un rapport ou d'un bloc units :

cargo test --test field_units_global zzz_emit_field_units_schema -- --ignored