Result schema — reading a Kshana *.result.json

Every run writes a versioned, self-describing JSON (JavaScript Object Notation) artifact next to the scenario. This page is the hand-written reader's guide to the interchange envelope and to the clock and orbit result shapes: each field's unit, where it is computed in the source, and how to read it. The canonical type is RunResult in src/report.rs; the figures of merit are FoMScores in src/fom.rs.

It is not the complete field reference. The engine dispatches over far more kinds than these two, and each emits its own pack. The complete reference — unit, provenance class and definition for every numeric field of every built-in kind — is generated, not hand-written: see Units and provenance, per field, for every kind below.

Interchange envelope (KIF, the Kshana Interchange Format) — recognising and version-checking an artifact#

Kshana artifacts can be wrapped in a neutral, self-describing interchange envelope so a third-party tool can recognise the file and decide whether it can read it before it commits to a payload schema. The canonical type is Envelope in src/interchange.rs.

Compatibility contract. Versions are MAJOR.MINOR. New fields are added with #[serde(default)] (the additive discipline), so a reader can parse any artifact of the same major and an equal-or-older minor (Compatible). A strictly newer minor (ForwardIncompatible) may carry fields this reader cannot honour, and a different major (MajorIncompatible) is a structural break — both are refused by Envelope::parse, which validates the format tag and version on the boundary rather than silently mis-parsing foreign input.

Determinism. The envelope carries no timestamp — Kshana's reproducibility promise (scenario + seed + engine_version reproduces a run) requires it. Provenance lives in engine_version and the payload's own scenario_hash.

A typed read-back (Envelope::payload_as::<T>()) works for any payload that implements Deserialize (e.g. Scenario). Result artifacts are serialize-only by design and are read as the raw payload JSON value.

Top level (clock and orbit packs)#

ClockRun (each of quantum / classical)#

FoMScores (the fom object)#

What "good" looks like#

• A quieter clock (lower adev_curve) gives a longer holdover_s and a higher security detectability bound — that is the quantum-vs-classical contrast.
• availability near 1.0 means the system stayed in spec almost the whole run; during a long outage it drops for the noisier clock.
• integrity near 1.0 means the filter's own uncertainty bound was honest about its error — a self-consistency statement, not a safety-of-life guarantee.

Other scenario kinds#

Every other kind emits its own result shape. A few of the common ones:

• inertial: position-domain figures of merit in metres (pos_rms_m, pos_p95_m) — single-axis (1-DOF (DOF: degree of freedom)), single-seed (see CAPABILITY.md).
• hybrid / fusion: timing_spec_ns and position_spec_m at the top level, and per side the timing and position figures of one sensor suite (position_p95_m, position_holdover_s, and pnt_holdover_s, the time until either spec breaches), with a figure_tiers block like the clock pack's in which the position figures are listed as untiered.
• spoof: per-step spoof offset vs the clock's detection bound, plus whether the spoof reached the spec before detection (src/spoof.rs).

For the precise field set of any kind, read its entry in field-units-schema.json (below), the kind's section of SCENARIOS.md, or the corresponding *Result struct in src/.

Other files a run writes#

Beside <scenario>.result.json the CLI (command-line interface) writes <scenario>.chart.svg, a printable <scenario>.report.html and the same report as <scenario>.report.json, whose reproducibility block records the engine version, the SHA-256 of the scenario file, the seed, the platform and the exact command (see REPORTS.md and REPRODUCIBILITY.md). Kinds that publish a reproducibility table also write <scenario>.table.csv (CSV: comma-separated values). --export writes exchange files (see INTEROP.md) and --animate an animation (see ANIMATION.md).

Units and provenance, per field, for every kind#

This page is hand-written and covers the clock and orbit packs. The machine-readable counterpart covers every built-in kind:

• In the result itself. Each scenario's result document carries a top-level units object mapping an emitted field's path to {"unit", "provenance", "note"}. The path grammar (an array contributes one []-suffixed segment shared by its rows; * is a single-segment wildcard for data-keyed objects) and the closed provenance vocabulary are defined in src/field_schema.rs.
• As one file. field-units-schema.json is the harvested union: for every kind, every numeric field it emits at a stated source, with its unit, provenance class, evidence tier and definition — and, named rather than omitted, every field that does not have one yet. Its coverage block carries the counts.

Both are enforced by tests/field_units_global.rs, which runs every registered kind and fails if an emitted numeric field lacks a unit and a provenance class. Kinds not yet covered are named individually in that file's UNCOVERED_KINDS with the reason each is open, and the count is pinned so the list can only shrink.

Regenerate the JSON after any change to a report's shape or to a units block:

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