kshana 0.37.0

// SPDX-License-Identifier: AGPL-3.0-only
//! String-in, string-out entry points for the 0.35 capabilities, shared by the Python
//! bindings, the WebAssembly build and the Model Context Protocol (MCP) server.
//!
//! The feature modules own their methods and expose in-memory functions
//! ([`crate::receiver_trust::assess`], [`crate::interference_map::api`],
//! [`crate::nmea_synth::generate_from_toml`], [`crate::evidence`]); this layer adds what a
//! surface needs on top and nothing else: a size cap on every text input, the refusal of a
//! `path` source where the caller must not read the host's files, JSON shaping, and the
//! assembly of an evidence pack from a receiver-trust run (which the command line does from
//! files). It adds no method of its own: every threshold, the privacy rule and the output
//! schemas are the feature modules', called unchanged.
//!
//! Every input is capped by [`MAX_INPUT_BYTES`] unless the caller passes a tighter cap, so a
//! surface that accepts uploads cannot be made to allocate without bound.

use crate::evidence::{
    build_receiver_trust_pack, generate_seed, public_key_hex, verify_bundle, Files, PackRequest,
    VerifyOptions,
};
use crate::interference_map::api::{self, DatasetSpec, DEFAULT_CELL_DEG};
use crate::receiver_trust::assess::{self, ExcerptAssessment};
use crate::receiver_trust::live::parse_live_scenario;
use crate::receiver_trust::scenario::{self, ReceiverTrustScenario, TrustOutput};
use serde_json::{json, Value};

/// Largest single text input any function here accepts (64 MiB).
pub const MAX_INPUT_BYTES: usize = 64 * 1024 * 1024;

/// Which source an interference map is built from.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum MapSource {
    /// Aircraft reports (`adsb-lol` preset or `custom`).
    Adsb,
    /// Ship reports (`noaa-marinecadastre`, `kystverket` or `custom`).
    Ais,
}

impl MapSource {
    /// Parse `"adsb"` or `"ais"`.
    pub fn parse(s: &str) -> Result<Self, String> {
        match s {
            "adsb" => Ok(Self::Adsb),
            "ais" => Ok(Self::Ais),
            o => Err(format!("unknown source `{o}`: use `adsb` or `ais`")),
        }
    }
}

/// The licence fields a `custom` dataset must state.
#[derive(Clone, Debug, Default)]
pub struct CustomDataset {
    /// Licence name.
    pub licence: String,
    /// Licence URL.
    pub licence_url: String,
    /// Attribution text.
    pub attribution: String,
}

/// One published day of an interference map.
#[derive(Clone, Debug)]
pub struct MapDay {
    /// Suggested file name (one file per source per UTC day).
    pub file_name: String,
    /// UTC date, `YYYY-MM-DD`.
    pub date: String,
    /// Cells published (at least five distinct aircraft or vessels each).
    pub cells_published: usize,
    /// Cells flagged degraded or anomalous.
    pub cells_flagged: usize,
    /// The `kshana-interference-map/v1` GeoJSON document, pretty-printed.
    pub geojson: String,
}

fn cap(what: &str, text: &str, max: usize) -> Result<(), String> {
    cap_len(what, text.len(), max)
}

fn cap_len(what: &str, len: usize, max: usize) -> Result<(), String> {
    let limit = max.min(MAX_INPUT_BYTES);
    if len > limit {
        return Err(format!(
            "{what} is {len} bytes, over the {limit}-byte limit"
        ));
    }
    Ok(())
}

// The inline-only boundary has one implementation, `crate::inline_only`; the surfaces use it
// through this module. `tests/scenario_file_sources_guard.rs` pins the field list.
pub use crate::inline_only::{reject_file_sources, FILE_SOURCE_KEYS, FILE_SOURCE_KEYS_BY_KIND};

/// Assess a receiver log from a `receiver-trust` scenario whose log and navigation bytes are
/// **inline** (`text` or `base64`). A scenario that names a `path` is refused, so a caller
/// that takes the TOML from an untrusted party (a network service, an AI agent) cannot read
/// the host's files. `max_bytes` caps the TOML, and therefore the inline log.
pub fn assess_receiver_log_inline(toml: &str, max_bytes: usize) -> Result<TrustOutput, String> {
    reject_file_sources(toml, max_bytes)?;
    let scn: ReceiverTrustScenario =
        toml::from_str(toml).map_err(|e| format!("invalid receiver-trust scenario: {e}"))?;
    if scn.log.source.path.is_some() || scn.log.nav.as_ref().is_some_and(|n| n.path.is_some()) {
        return Err(
            "`path` sources are not accepted here: give the log inline as `text` or `base64`"
                .into(),
        );
    }
    scenario::run_scenario(&scn)
}

/// Assess a vessel's NMEA 0183 log: the session TOML (`[platform] kind = "vessel"`; no `[log]`
/// needed) and the log's bytes, scored as a batch run. Returns the result document as JSON,
/// the same as `kshana receiver-trust <session.toml>` writes to `result.json`.
pub fn assess_vessel_log_json(
    session_toml: &str,
    log: &[u8],
    max_bytes: usize,
) -> Result<String, String> {
    cap("session", session_toml, max_bytes)?;
    cap_len("log", log.len(), max_bytes)?;
    let r = assess::assess_vessel_log(session_toml, log)?;
    serde_json::to_string_pretty(&r).map_err(|e| e.to_string())
}

/// Score a bounded excerpt of a vessel's NMEA 0183 stream the way live mode scores it:
/// per-epoch trust state and 0-100 score with reasons (live JSON-lines schema 1.3, with an `advisory` field and the satellite `geometry` on every epoch and a `class` on every deduction), the last
/// `$PKSHT` sentence and a summary. The excerpt must hold the calibration window. Bounded to
/// 2 MiB and 20,000 epochs by the engine, and to `max_bytes` here. The gate, sockets and
/// the long-running process are command-line only.
pub fn assess_vessel_excerpt(
    session_toml: &str,
    excerpt: &[u8],
    max_bytes: usize,
) -> Result<ExcerptAssessment, String> {
    cap("session", session_toml, max_bytes)?;
    cap_len("excerpt", excerpt.len(), max_bytes)?;
    assess::assess_stream_excerpt(session_toml, excerpt)
}

fn dataset_spec<'a>(
    key: &'a str,
    custom: Option<&'a CustomDataset>,
) -> Result<DatasetSpec<'a>, String> {
    if key == "custom" {
        let c = custom.ok_or("dataset `custom` needs licence, licence_url and attribution")?;
        if c.licence.is_empty() || c.licence_url.is_empty() || c.attribution.is_empty() {
            return Err("dataset `custom` needs licence, licence_url and attribution".into());
        }
        Ok(DatasetSpec::Custom {
            licence: &c.licence,
            licence_url: &c.licence_url,
            attribution: &c.attribution,
        })
    } else {
        Ok(DatasetSpec::Preset(key))
    }
}

/// Build an interference map from CSV text (the formats of `docs/INTERFERENCE-MAP.md`).
/// `land_geojson` (AIS only) is an optional land-polygon file for the inland detector.
/// Identifiers are hashed in memory and never returned; cells below the publication
/// minimum are withheld. A degraded cell does not name interference as the cause.
pub fn interference_map(
    source: MapSource,
    csv: &str,
    dataset: &str,
    cell_deg: Option<f64>,
    custom: Option<&CustomDataset>,
    land_geojson: Option<&str>,
    max_bytes: usize,
) -> Result<Vec<MapDay>, String> {
    cap("input", csv, max_bytes)?;
    if let Some(l) = land_geojson {
        cap("land file", l, max_bytes)?;
    }
    let spec = dataset_spec(dataset, custom)?;
    let cell = cell_deg.unwrap_or(DEFAULT_CELL_DEG);
    let days = match source {
        MapSource::Adsb => api::adsb_maps_from_csv(csv, &spec, cell),
        MapSource::Ais => api::ais_maps_from_csv(csv, &spec, cell, land_geojson),
    }
    .map_err(|e| e.to_string())?;
    days.into_iter()
        .map(|d| {
            let features = d.geojson["features"]
                .as_array()
                .map_or(&[][..], Vec::as_slice);
            let flagged = features
                .iter()
                .filter(|f| f["properties"]["degraded"] == Value::Bool(true))
                .count();
            Ok(MapDay {
                file_name: d.file_name,
                date: d.date,
                cells_published: features.len(),
                cells_flagged: flagged,
                geojson: serde_json::to_string_pretty(&d.geojson).map_err(|e| e.to_string())?,
            })
        })
        .collect()
}

/// Share of a route through degraded cells, for each map in `maps` (GeoJSON text from
/// [`interference_map`] or `kshana interference-map`) inside the optional `from`/`to`
/// dates (`YYYY-MM-DD`). Returns the `kshana-route-exposure/v1` report as JSON. Cells not
/// observed are not evidence of a clear route, and the report is not a forecast.
pub fn route_exposure(
    route_text: &str,
    maps: &[&str],
    from: Option<&str>,
    to: Option<&str>,
    max_bytes: usize,
) -> Result<String, String> {
    cap("route", route_text, max_bytes)?;
    if maps.is_empty() {
        return Err("at least one map is required".into());
    }
    for (i, m) in maps.iter().enumerate() {
        cap(&format!("map {}", i + 1), m, max_bytes)?;
    }
    let v = api::route_exposure(route_text, maps, from, to).map_err(|e| e.to_string())?;
    serde_json::to_string_pretty(&v).map_err(|e| e.to_string())
}

/// Result of a training-scenario run: text only, nothing is transmitted.
#[derive(Clone, Debug)]
pub struct NmeaTraining {
    /// The synthetic bridge NMEA 0183 stream, CRLF line ends, with the training marker.
    pub nmea: String,
    /// Instructor log as JSON (`kshana-nmea-training/1`): what was injected when, true track.
    pub log_json: String,
    /// Instructor log as text.
    pub log_text: String,
}

/// Generate synthetic training NMEA from a `nmea-scenario` TOML. Text only: for crew
/// training and tests, never for a vessel's live navigation systems.
pub fn nmea_training(
    toml: &str,
    seed: Option<u64>,
    max_bytes: usize,
) -> Result<NmeaTraining, String> {
    cap("scenario", toml, max_bytes)?;
    let g = crate::nmea_synth::generate_from_toml(toml, seed)?;
    Ok(NmeaTraining {
        nmea: g.nmea_text(),
        log_json: g.log.to_json(),
        log_text: g.log.to_text(),
    })
}

/// What a test-bench export is and is not, carried with every export.
pub const BENCH_NOTICE: &str =
    "Vehicle motion and labelled event intervals only. Nothing exported \
    here is, models or drives a radio-frequency or baseband signal, and an event is a time \
    interval, not a recipe for producing interference. The laboratory simulator and its operator \
    supply the signals and are responsible for running them only where that is authorised \
    (conducted or shielded, per the simulator's own safety instructions). Kshana publishes no \
    results from such runs.";

/// A test-bench export held in memory.
#[derive(Clone, Debug)]
pub struct BenchExport {
    /// Each file as `(suffix, text)`, in the fixed order the command line writes them. Every
    /// file is UTF-8 text (CSV, JSON, NMEA, waypoint text, TOML).
    pub files: Vec<(String, String)>,
    /// Why any file was left out (today only the waypoint text, which needs a
    /// millisecond-regular sample grid).
    pub notes: Vec<String>,
}

/// Export a scenario's vehicle motion and events for a laboratory GNSS simulator
/// (`kshana bench-export`, `docs/TEST-BENCH.md`), in memory: nothing is written to disk.
/// `epoch` is the UTC instant of motion time zero, `YYYY-MM-DDTHH:MM:SS` with an optional
/// trailing `Z` (default 2024-01-01T00:00:00Z). The output is byte-identical for the same
/// scenario and epoch. [`BENCH_NOTICE`] belongs with it wherever it is shown.
pub fn bench_export(
    toml: &str,
    epoch: Option<&str>,
    max_bytes: usize,
) -> Result<BenchExport, String> {
    cap("scenario", toml, max_bytes)?;
    let epoch = epoch
        .map(crate::interop::UtcEpoch::parse_iso)
        .transpose()
        .map_err(|e| format!("epoch: {e}"))?;
    let (files, notes) =
        crate::interop::testbench::export_with_notes(toml, epoch).map_err(|e| e.to_string())?;
    let files = files
        .into_iter()
        .map(|f| {
            String::from_utf8(f.bytes)
                .map(|t| (f.suffix.clone(), t))
                .map_err(|_| format!("{}: not UTF-8", f.suffix))
        })
        .collect::<Result<Vec<_>, _>>()?;
    Ok(BenchExport { files, notes })
}

/// Abbreviations whose full stop does not end a sentence in a scenario header.
const ABBREVIATIONS: [&str; 5] = ["et al", "e.g", "i.e", "vs", "cf"];

/// The first sentence of a scenario file's header comment: what the example shows.
///
/// The header is the first block of `#` lines in the file, which one bundled scenario
/// carries below its `kind` line rather than above it. A full stop that closes one of the
/// abbreviations does not end the sentence, so "Liu et al. 2025" stays whole.
pub fn first_comment_sentence(toml: &str) -> String {
    let paragraph = toml
        .lines()
        .skip_while(|l| !l.starts_with('#'))
        .map_while(|l| l.strip_prefix('#'))
        .map(str::trim)
        .take_while(|l| !l.is_empty())
        .collect::<Vec<_>>()
        .join(" ");
    let mut from = 0;
    while let Some(i) = paragraph[from..].find(". ") {
        let stop = from + i;
        let before = &paragraph[..stop];
        let abbreviated = ABBREVIATIONS.iter().any(|a| {
            before
                .strip_suffix(a)
                .is_some_and(|head| !head.ends_with(|c: char| c.is_alphanumeric()))
        });
        if !abbreviated {
            return paragraph[..=stop].to_string();
        }
        from = stop + 2;
    }
    paragraph
}

/// The detected kind of a scenario, as the name the kind listing uses.
pub fn scenario_kind_name(toml: &str) -> &'static str {
    crate::api::ScenarioKind::classify(toml)
        .map(|k| k.as_str())
        .unwrap_or("clock")
}

/// The bundled reference scenarios as JSON: `count` and `scenarios`, each `name`, `kind` and
/// `about` (the first sentence of the file's header). `kind` limits the list to one kind.
#[cfg(feature = "bundled-scenarios")]
pub fn list_examples(kind: Option<&str>) -> Result<Value, String> {
    let wanted = kind.map(str::trim).filter(|k| !k.is_empty());
    if let Some(k) = wanted {
        if !crate::api::list_scenario_kinds()
            .iter()
            .any(|m| m.name == k)
        {
            return Err(format!(
                "unknown scenario kind `{k}`; the kind list names every kind"
            ));
        }
    }
    let scenarios: Vec<Value> = crate::bundled_scenarios::BUNDLED
        .iter()
        .map(|(name, toml)| (*name, scenario_kind_name(toml), *toml))
        .filter(|(_, k, _)| wanted.is_none_or(|w| w == *k))
        .map(|(name, k, toml)| {
            json!({"name": name, "kind": k, "about": first_comment_sentence(toml)})
        })
        .collect();
    Ok(json!({"count": scenarios.len(), "scenarios": scenarios}))
}

/// The TOML text of one bundled reference scenario, byte for byte the file the repository
/// ships. A scenario that exists in the repository but is not bundled is refused with the
/// reason.
#[cfg(feature = "bundled-scenarios")]
pub fn get_example(name: &str) -> Result<&'static str, String> {
    let name = name.trim();
    if let Some(toml) = crate::bundled_scenarios::get(name) {
        return Ok(toml);
    }
    Err(match crate::bundled_scenarios::repo_only_reason(name) {
        Some(why) => format!("`{name}` is not bundled: it {why}"),
        None => format!(
            "no bundled scenario named `{name}`; the example list names the {} that are",
            crate::bundled_scenarios::BUNDLED.len()
        ),
    })
}

/// Which interoperability formats apply to a scenario, without running it: one entry per
/// format with `format`, `applies`, `reason` (when it does not) and `spec_url`.
pub fn export_formats(toml: &str, max_bytes: usize) -> Result<Value, String> {
    cap("scenario", toml, max_bytes)?;
    if let Err(e) = toml::from_str::<toml::Value>(toml) {
        return Err(format!("invalid TOML: {e}"));
    }
    Ok(Value::Array(
        crate::interop::plan(toml)
            .into_iter()
            .map(|(format, outcome)| {
                json!({
                    "format": format.as_str(),
                    "applies": outcome.is_ok(),
                    "reason": outcome.err(),
                    "spec_url": format.spec_url(),
                })
            })
            .collect(),
    ))
}

/// One exported file: its suffix, size, SHA-256, encoding (`utf-8` or `base64`) and content.
#[derive(Clone, Debug)]
pub struct ExportedFile {
    /// What the command line appends to the output name (for example `.czml`, `.G01.e`).
    pub suffix: String,
    /// Size of the file in bytes (before any base64 encoding).
    pub bytes: usize,
    /// SHA-256 of the file's bytes, hex.
    pub sha256: String,
    /// `"utf-8"` (the content is the text) or `"base64"` (a binary file).
    pub encoding: &'static str,
    /// The content.
    pub content: String,
}

/// An interoperability export held in memory.
#[derive(Clone, Debug)]
pub struct ScenarioExport {
    /// The format exported (`czml`, `kml`, `geojson`, `stk` or `sigmf`).
    pub format: &'static str,
    /// The published specification the writer follows.
    pub spec_url: &'static str,
    /// The files, in the order the command line writes them.
    pub files: Vec<ExportedFile>,
}

impl ScenarioExport {
    /// The export as JSON: `format`, `spec_url` and `files` (each with its `content`).
    pub fn to_json(&self) -> Value {
        json!({
            "format": self.format,
            "spec_url": self.spec_url,
            "files": self.files.iter().map(|f| json!({
                "suffix": f.suffix, "bytes": f.bytes, "sha256": f.sha256,
                "encoding": f.encoding, "content": f.content,
            })).collect::<Vec<_>>(),
        })
    }
}

/// Export a scenario in one interoperability format (`czml`, `kml`, `geojson`, `stk`,
/// `sigmf`), in memory: nothing is written. Times are UTC and the same scenario gives
/// byte-identical files. A format that does not apply is refused with the reason.
pub fn export_scenario(
    toml: &str,
    format: &str,
    max_bytes: usize,
) -> Result<ScenarioExport, String> {
    cap("scenario", toml, max_bytes)?;
    let fmt = crate::interop::Format::parse(format.trim()).map_err(|_| {
        format!(
            "unknown export format `{}`; expected one of czml, kml, geojson, stk or sigmf",
            format.trim()
        )
    })?;
    let files = crate::interop::export(toml, fmt).map_err(|e| format!("{}: {e}", fmt.as_str()))?;
    Ok(ScenarioExport {
        format: fmt.as_str(),
        spec_url: fmt.spec_url(),
        files: files
            .into_iter()
            .map(|f| {
                let sha256 = crate::advanced_report::sha256_hex(&f.bytes);
                let bytes = f.bytes.len();
                let (encoding, content) = match String::from_utf8(f.bytes) {
                    Ok(t) => ("utf-8", t),
                    Err(e) => ("base64", crate::permalink::base64_encode(e.as_bytes())),
                };
                ExportedFile {
                    suffix: f.suffix,
                    bytes,
                    sha256,
                    encoding,
                    content,
                }
            })
            .collect(),
    })
}

/// Write a GeoJSON route (a `LineString`, or a `Feature` or `FeatureCollection` holding one)
/// into a scenario of a kind that flies a waypoint track, and return the new TOML.
pub fn import_route(toml: &str, geojson: &str, max_bytes: usize) -> Result<String, String> {
    cap("scenario", toml, max_bytes)?;
    cap("route", geojson, max_bytes)?;
    crate::interop::geojson::apply_route(toml, geojson)
}

/// Most frames a surface returns in one animation.
pub const MAX_ANIMATION_FRAMES: usize = 120;

/// An animation held in memory: a summary of what was drawn and the files.
#[derive(Clone, Debug)]
pub struct AnimationOut {
    /// What was drawn: time range and unit, chart titles, phases and events, series left out,
    /// and the file names.
    pub summary: Value,
    /// The files as `(name, text)`: one for SVG or HTML; frames plus `manifest.json` otherwise.
    pub files: Vec<(String, String)>,
}

/// Run a scenario and return its time series as an animation: `svg` (one animated SVG, no
/// script), `html` (one self-contained player page) or `frames` (numbered static SVG frames
/// and `manifest.json`, at most [`MAX_ANIMATION_FRAMES`]). Defaults: 12 fps, 8 s, 960 px.
/// A kind whose result has no sampled time axis is refused. Pure text; nothing is written.
pub fn animate_scenario(
    toml: &str,
    format: Option<&str>,
    fps: Option<u32>,
    duration_s: Option<f64>,
    width: Option<u32>,
    max_bytes: usize,
) -> Result<AnimationOut, String> {
    use crate::animation::{animate_result, animation_meta, AnimationFormat, AnimationOptions};
    cap("scenario", toml, max_bytes)?;
    let format = AnimationFormat::parse(format.unwrap_or("svg"))?;
    let mut opts = AnimationOptions::default();
    if let Some(n) = fps {
        opts.fps = n;
    }
    if let Some(d) = duration_s {
        opts.duration_s = d;
    }
    if let Some(w) = width {
        opts.width = w;
    }
    opts.validate()?;
    if format == AnimationFormat::Frames && opts.frame_count() > MAX_ANIMATION_FRAMES {
        return Err(format!(
            "duration_s x fps gives {} frames and at most {MAX_ANIMATION_FRAMES} are returned; \
             lower fps or duration_s, or write a longer sequence with the command line",
            opts.frame_count()
        ));
    }
    let kind = scenario_kind_name(toml);
    let out = crate::api::run_toml(toml).map_err(|e| format!("scenario run failed: {e}"))?;
    let anim = animate_result(&out.json, Some(kind), format, &opts).map_err(|e| e.to_string())?;
    let names: Vec<String> = anim.files.iter().map(|f| f.name.clone()).collect();
    let summary = animation_meta(&out.json, Some(kind), &[format], &opts, &names)
        .map_err(|e| e.to_string())?;
    Ok(AnimationOut {
        summary,
        files: anim
            .files
            .into_iter()
            .map(|f| (f.name, f.content))
            .collect(),
    })
}

/// Run an `iq-labfit` scenario with its logs inline: the loop-model fit to lab runs, in memory.
/// A run whose `log` (or its `nav`) names a `path` is refused: logs travel as `text` or
/// `base64`. A scenario whose `[input]` names a `campaign` folder is refused too: campaigns
/// are read only by the CLI, Python, or the MCP labfit tool inside its work directory.
/// Returns the parsed `report` and the `residuals_csv`, `predictions_csv` and `markdown`
/// renderings.
pub fn iq_labfit_inline(toml_text: &str, max_bytes: usize) -> Result<Value, String> {
    cap("scenario", toml_text, max_bytes)?;
    let v: toml::Value =
        toml::from_str(toml_text).map_err(|e| format!("iq-labfit scenario: {e}"))?;
    if v.get("input").and_then(|i| i.get("campaign")).is_some() {
        return Err(
            "[input] campaign names a campaign folder, and this surface reads no files; \
             campaigns are read only by the CLI (`kshana iq labfit`), Python \
             (`kshana.iq_labfit`), or the MCP labfit tool inside its IQ work directory"
                .into(),
        );
    }
    if let Some(runs) = v.get("runs").and_then(toml::Value::as_array) {
        for (i, r) in runs.iter().enumerate() {
            let log = r.get("log");
            let named = log.and_then(|l| l.get("path")).is_some()
                || log
                    .and_then(|l| l.get("nav"))
                    .and_then(|n| n.get("path"))
                    .is_some();
            if named {
                return Err(format!(
                    "runs[{i}].log names a file `path`; give the log as `text` or `base64` \
                     (this surface reads no files)"
                ));
            }
        }
    }
    let out = crate::iq::labfit::run_toml(toml_text)?;
    let report: Value = serde_json::from_str(&out.json).map_err(|e| e.to_string())?;
    Ok(json!({
        "report": report,
        "residuals_csv": out.residuals_csv,
        "predictions_csv": out.predictions_csv,
        "markdown": out.markdown,
    }))
}

/// Validate a lab test-condition file (`kshana.test-conditions/1`, TOML or JSON) given as
/// text, in memory: the resolved conditions with their `hash`. Nothing is read from disk (a
/// recording path the file names is not opened).
#[cfg(not(target_arch = "wasm32"))]
pub fn iq_test_conditions_inline(text: &str, max_bytes: usize) -> Result<Value, String> {
    cap("test conditions", text, max_bytes)?;
    let tc = crate::iq::campaign::TestConditions::parse(text)?;
    let mut v = serde_json::to_value(&tc).map_err(|e| e.to_string())?;
    if let Some(m) = v.as_object_mut() {
        m.insert("hash".into(), tc.hash().into());
    }
    Ok(v)
}

/// Most runs a surface accepts in one compliance report.
pub const MAX_COMPLIANCE_RUNS: usize = 64;

/// One run offered to [`compliance_report`]: the result JSON as text, the name to show for
/// it, and the scenario TOML that produced it when there is one (it names the scenario
/// kind, which a result does not).
#[derive(Clone, Debug, Default)]
pub struct ComplianceRunText {
    /// Name shown in the report (usually the result's file name).
    pub label: String,
    /// The result JSON text.
    pub result_json: String,
    /// The scenario TOML text, when there is one.
    pub scenario_toml: Option<String>,
}

/// The filled public-framework mapping, as JSON and as Markdown.
#[derive(Clone, Debug)]
pub struct ComplianceOutput {
    /// The report as JSON: `statement`, `engine_version`, `runs`, `unrecognised`,
    /// `capabilities`, `receiver_trust` and one entry per framework row.
    pub report: Value,
    /// The same report as Markdown.
    pub markdown: String,
}

/// Fill the public-framework mapping (`docs/compliance/`) from result documents given as
/// text: which framework rows the runs support evidence for, which they do not, and the gap
/// each row keeps. Nothing is read from disk. A result that cannot be used is listed in
/// `unrecognised` and counts for nothing. The report carries
/// [`crate::compliance::STATEMENT`] verbatim; a status never says a framework is met.
pub fn compliance_report(
    runs: &[ComplianceRunText],
    max_bytes: usize,
) -> Result<ComplianceOutput, String> {
    if runs.len() > MAX_COMPLIANCE_RUNS {
        return Err(format!(
            "{} runs given; at most {MAX_COMPLIANCE_RUNS} per report",
            runs.len()
        ));
    }
    let mut total = 0usize;
    for r in runs {
        cap("result", &r.result_json, max_bytes)?;
        total += r.result_json.len();
        if let Some(t) = &r.scenario_toml {
            cap("scenario", t, max_bytes)?;
            total += t.len();
        }
    }
    if total > max_bytes {
        return Err(format!(
            "the runs total {total} bytes; the limit for one report is {max_bytes}"
        ));
    }
    let inputs: Vec<crate::compliance::RunInput<'_>> = runs
        .iter()
        .map(|r| crate::compliance::RunInput {
            label: &r.label,
            result_json: &r.result_json,
            scenario_toml: r.scenario_toml.as_deref(),
        })
        .collect();
    let rep = crate::compliance::assess_texts(&inputs);
    Ok(ComplianceOutput {
        report: json!(rep),
        markdown: rep.to_markdown(),
    })
}

/// The static mapping tables (`sources = false`) or the source documents they cite
/// (`sources = true`), as Markdown, led by [`crate::compliance::STATEMENT`].
pub fn compliance_mapping(sources: bool) -> String {
    use crate::compliance::mapping::{framework_table_md, sources_md, Framework};
    let mut s = format!("> {}\n\n", crate::compliance::STATEMENT);
    for fw in Framework::ALL {
        let body = if sources {
            sources_md(fw)
        } else {
            framework_table_md(fw)
        };
        s.push_str(&format!("## {}\n\n{}\n", fw.title(), body));
    }
    s
}

/// Output of [`trust_telemetry`].
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum TelemetryFormat {
    /// Prometheus text exposition of the final state.
    Prometheus,
    /// One CEF line per syslog event, inside an RFC 5424 envelope.
    Cef,
    /// One LEEF 2.0 line per syslog event, inside an RFC 5424 envelope.
    Leef,
    /// The OTLP/HTTP JSON metrics payload of the final state (needs the `otlp` feature).
    Otlp,
}

impl TelemetryFormat {
    /// Parse `"prometheus"`, `"cef"`, `"leef"` or `"otlp"`.
    pub fn parse(s: &str) -> Result<Self, String> {
        match s {
            "prometheus" => Ok(Self::Prometheus),
            "cef" => Ok(Self::Cef),
            "leef" => Ok(Self::Leef),
            "otlp" => Ok(Self::Otlp),
            o => Err(format!(
                "unknown format `{o}`: use `prometheus`, `cef`, `leef` or `otlp`"
            )),
        }
    }
}

/// What the input of [`trust_telemetry`] is.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum TelemetryInput {
    /// A batch `receiver-trust` result document (`--result`).
    Result,
    /// The live per-epoch stream, one JSON object per line.
    Jsonl,
}

impl TelemetryInput {
    /// Parse `"result"` or `"jsonl"`.
    pub fn parse(s: &str) -> Result<Self, String> {
        match s {
            "result" => Ok(Self::Result),
            "jsonl" => Ok(Self::Jsonl),
            o => Err(format!("unknown input_kind `{o}`: use `result` or `jsonl`")),
        }
    }
}

/// The `trust-telemetry` options that change the text, as the command line has them.
#[derive(Clone, Copy, Debug, Default, PartialEq)]
pub struct TelemetryOptions {
    /// `--expose-position`: add the receiver-reported position to the metrics (off by default).
    pub expose_position: bool,
    /// `--syslog-all`: one event per epoch instead of one per band change.
    pub syslog_all: bool,
    /// Time of export for the OTLP payload, in Unix nanoseconds (no clock is read here; 0 if unknown).
    pub unix_nano: u64,
}

/// Render a trust stream or a batch result in one of the telemetry formats, with the same
/// encoders `kshana trust-telemetry` uses and no process, socket or clock. Syslog lines carry
/// no timestamp (RFC 5424 nil value) because no wall clock is read; a `jsonl` line that does
/// not parse is skipped and counted in `kshana_trust_input_errors_total` (Prometheus output).
/// An input that yields no epoch is an error.
pub fn trust_telemetry(
    input: &str,
    format: TelemetryFormat,
    host: &str,
    input_kind: TelemetryInput,
    opts: TelemetryOptions,
    max_bytes: usize,
) -> Result<String, String> {
    use crate::telemetry::{prometheus::Registry, sample, syslog};
    cap("input", input, max_bytes)?;
    syslog::check_host(host)?;
    let version = env!("CARGO_PKG_VERSION");
    let host = if host.is_empty() { "kshana" } else { host };
    let mut reg = Registry::new(version);
    reg.set_expose_position(opts.expose_position);
    let mut samples: Vec<sample::TrustSample> = Vec::new();
    match input_kind {
        TelemetryInput::Result => samples = sample::from_result_json(input)?,
        TelemetryInput::Jsonl => {
            for line in input.lines().filter(|l| !l.trim().is_empty()) {
                match sample::parse_live_line(line) {
                    Ok(s) => samples.push(s),
                    Err(_) => reg.observe_input_error(),
                }
            }
        }
    }
    if samples.is_empty() {
        return Err("the input holds no trust epoch".into());
    }
    let mut out = String::new();
    let mut prev = None;
    for s in &samples {
        reg.observe(s, None);
        if matches!(format, TelemetryFormat::Cef | TelemetryFormat::Leef)
            && (opts.syslog_all || prev != Some(s.band))
        {
            let payload = if format == TelemetryFormat::Cef {
                syslog::cef(s, prev, host, version)
            } else {
                syslog::leef(s, prev, host, version)
            };
            out.push_str(&syslog::rfc5424(s.band, None, host, &payload));
            out.push('\n');
            // CEF and LEEF fan one input line out to one event per epoch: bound the reply too.
            if out.len() > max_bytes.min(MAX_INPUT_BYTES) {
                return Err(format!(
                    "the reply is over the {}-byte limit; send fewer epochs or leave `syslog_all` off",
                    max_bytes.min(MAX_INPUT_BYTES)
                ));
            }
        }
        prev = Some(s.band);
    }
    match format {
        TelemetryFormat::Cef | TelemetryFormat::Leef => Ok(out),
        TelemetryFormat::Prometheus => Ok(reg.render()),
        #[cfg(feature = "otlp")]
        TelemetryFormat::Otlp => {
            Ok(crate::telemetry::otlp::build_payload(&reg, opts.unix_nano).to_string())
        }
        #[cfg(not(feature = "otlp"))]
        TelemetryFormat::Otlp => Err("otlp needs a build with the `otlp` feature".into()),
    }
}

/// Check Galileo OSNMA authentication of I/NAV pages held in memory, with the verifier
/// `kshana osnma verify` runs, and return the JSON report `--json` prints (its `advisory` field
/// carries [`crate::osnma::ADVISORY`]). `format` is `pages`, `vector-csv` or `ubx` (empty to pick
/// by content); `start_gst` is a vector CSV's start in GST seconds (there is no file name to read
/// it from); `merkle_root_hex` is the trusted Merkle root (64 hex digits, empty for none);
/// `public_keys` are trusted keys as `ID:TYPE:HEX`; `reference_time` is the present time in GST
/// seconds from an independent source and `max_time_error` the widest distance of a sub-frame
/// from it, below 30 (needs a reference time, as on the command line). Without a reference time
/// freshness is not enforced and the report says so. Nothing is read from or written to disk.
#[allow(clippy::too_many_arguments)]
pub fn osnma_verify(
    input: &[u8],
    format: &str,
    start_gst: Option<u32>,
    merkle_root_hex: &str,
    public_keys: &[String],
    reference_time: Option<u32>,
    max_time_error: Option<u32>,
    max_bytes: usize,
) -> Result<String, String> {
    use crate::osnma::cli::{parse_public_key, verify_report, VerifyParams};
    use crate::osnma::verifier::Config;
    cap_len("input", input.len(), max_bytes)?;
    let merkle_root = match merkle_root_hex.trim() {
        "" => None,
        h => {
            let b = hex::decode(h).map_err(|_| "bad Merkle root hex".to_string())?;
            Some(
                <[u8; 32]>::try_from(b.as_slice())
                    .map_err(|_| "Merkle root must be 32 bytes".to_string())?,
            )
        }
    };
    let keys = public_keys
        .iter()
        .map(|k| parse_public_key(k.trim()))
        .collect::<Result<Vec<_>, _>>()?;
    if max_time_error.is_some() && reference_time.is_none() {
        return Err("--max-time-error has no effect without --reference-time".into());
    }
    Config {
        max_time_error_s: max_time_error,
        ..Config::default()
    }
    .validate()?;
    let format = match format.trim() {
        "" => None,
        f => Some(f),
    };
    let params = VerifyParams {
        label: "(in memory)",
        format,
        start_gst,
        merkle_root,
        keys,
        reference: reference_time,
        max_err: max_time_error,
    };
    let (report, _failed) = verify_report(input.to_vec(), &params)?;
    Ok(report.to_string())
}

/// A signed evidence pack built in memory, and the key that signed it.
#[derive(Clone, Debug)]
pub struct EvidencePack {
    /// The pack's files by name (`log-slice.bin`, `config.json`, `epochs.json`,
    /// `summary.html`, `manifest.json`, `manifest.sig`).
    pub files: Files,
    /// The signer's public key, 64 lower-case hex digits.
    pub public_key: String,
    /// The Ed25519 signing-key seed that was used. A caller that generated it must keep or
    /// discard it deliberately; a service must never return or log it.
    pub seed: [u8; 32],
    /// Epochs of the log inside the window.
    pub epochs_in_window: usize,
    /// The log byte range bundled, or `None` when the whole log is (the log gives no range).
    pub slice: Option<(usize, usize)>,
}

/// A pack with a timestamp token bound to it.
#[derive(Clone, Debug)]
pub struct TimestampedPack {
    /// The pack's files, now including `timestamp.tsr`.
    pub files: Files,
    /// What the verification of the pack with the token noted (for example, that the signer
    /// is not pinned).
    pub notes: Vec<String>,
}

/// Bind an RFC 3161 timestamp token (the raw DER bytes of a `.tsr`) to a pack, in memory
/// (`kshana evidence attach-timestamp`). The token is stored beside the signed manifest, not
/// inside it, and must be a timestamp over that manifest; the pack with the token must still
/// verify or nothing is attached. An existing token is kept unless `replace` is set. This does
/// NOT verify the timestamp authority's signature or certificate chain: do that with
/// `openssl ts -verify`. Verify later with `require_timestamp` to insist the token is present.
pub fn evidence_attach_timestamp(
    files: &Files,
    token: &[u8],
    replace: bool,
    max_bytes: usize,
) -> Result<TimestampedPack, String> {
    let total: usize = files.values().map(Vec::len).sum::<usize>() + token.len();
    if total > max_bytes {
        return Err(format!(
            "the pack and token total {total} bytes; the limit is {max_bytes}"
        ));
    }
    if token.is_empty() {
        return Err("the timestamp token is empty".into());
    }
    let mut files = files.clone();
    let notes = crate::evidence::attach_timestamp(&mut files, token, replace)?;
    Ok(TimestampedPack { files, notes })
}

/// A fresh Ed25519 signing key for evidence packs.
#[derive(Clone, Debug)]
pub struct EvidenceKey {
    /// The private signing-key seed, 64 lower-case hex digits. Secret: keep it out of logs,
    /// conversations and version control.
    pub seed_hex: String,
    /// The public key, 64 lower-case hex digits: give verifiers this, by a route they trust.
    pub public_key: String,
    /// The fingerprint of the public key (32 hex digits) that a manifest states.
    pub fingerprint: String,
}

/// Generate a signing key (`kshana evidence keygen`), in memory. The seed is returned to the
/// caller and kept nowhere else; offered on the Python surface only, because a private key
/// should not pass through a web page or an agent conversation.
pub fn evidence_keygen() -> EvidenceKey {
    let seed = zeroize::Zeroizing::new(generate_seed());
    let public_key = public_key_hex(&seed);
    let fingerprint =
        crate::evidence::bundle::fingerprint(&hex::decode(&public_key).unwrap_or_default());
    EvidenceKey {
        seed_hex: hex::encode(*seed),
        public_key,
        fingerprint,
    }
}

/// Parse a 64-hex-digit Ed25519 key or seed.
pub fn hex32(what: &str, s: &str) -> Result<[u8; 32], String> {
    let s = s.trim();
    if s.len() != 64 || !s.bytes().all(|b| matches!(b, b'0'..=b'9' | b'a'..=b'f')) {
        return Err(format!("{what} must be 64 lower-case hex digits"));
    }
    let v = hex::decode(s).map_err(|e| format!("{what}: {e}"))?;
    <[u8; 32]>::try_from(v.as_slice()).map_err(|_| format!("{what} must be 32 bytes"))
}

/// The current UTC time as RFC 3339, for a pack's creation time.
pub fn now_rfc3339_utc() -> String {
    let secs = std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .map_or(0, |d| d.as_secs()) as i64;
    let (y, m, d) = crate::interference_map::time::civil_from_days(secs.div_euclid(86_400));
    let r = secs.rem_euclid(86_400);
    format!(
        "{y:04}-{m:02}-{d:02}T{:02}:{:02}:{:02}Z",
        r / 3600,
        r % 3600 / 60,
        r % 60
    )
}

/// Build a signed evidence pack for a window of a vessel's NMEA log, in memory.
///
/// `session_toml` is a receiver-trust session (`[platform]`, `[monitors]`, `[score]`; no
/// `[log]` needed) and `log` the receiver log's bytes. The window is `from_s`..`to_s` in
/// seconds since the log's first epoch. `seed` is the signer's key seed; `None` generates
/// one from the operating system's randomness (returned in [`EvidencePack::seed`]).
/// `created_utc` is the creation time, RFC 3339 UTC, or `None` to leave it out (which makes
/// the pack reproducible). A pack is a technical record of what the engine computed from a
/// log; it is not a legal opinion, a finding of fact or a certification.
#[allow(clippy::too_many_arguments)]
pub fn evidence_create(
    session_toml: &str,
    log: &[u8],
    from_s: f64,
    to_s: f64,
    title: Option<&str>,
    created_utc: Option<&str>,
    seed: Option<[u8; 32]>,
    max_bytes: usize,
) -> Result<EvidencePack, String> {
    cap("session", session_toml, max_bytes)?;
    cap_len("log", log.len(), max_bytes)?;
    let scn = parse_live_scenario(session_toml)?;
    let seed = seed.unwrap_or_else(generate_seed);
    let (from, to) = (from_s.to_string(), to_s.to_string());
    let summary = build_receiver_trust_pack(
        &PackRequest {
            scenario: &scn,
            log_bytes: log,
            nav_bytes: None,
            log_file_name: "inline",
            from: &from,
            to: &to,
            title: title.unwrap_or("GNSS trust evidence pack"),
            created_utc,
        },
        &seed,
        None,
    )?;
    Ok(EvidencePack {
        public_key: public_key_hex(&seed),
        seed,
        epochs_in_window: summary.epochs_in_window,
        slice: summary.slice,
        files: summary.files,
    })
}

/// Verify an evidence pack held in memory: every hash, the chain, the signature, and with
/// `public_key` (hex, obtained from the signer by another route) that the signer is the one
/// you expect, with `full_log` that the log you hold is the one recorded, and with
/// `require_timestamp` that the pack carries a timestamp token.
///
/// Returns the report as JSON with two added fields that say plainly what a pass means:
/// `verdict` is `"verified"` (everything checks and the signer is the pinned key),
/// `"intact-signer-not-pinned"` (everything checks, but with no trusted public key the
/// signature proves only that the pack is intact against the key it names itself, which
/// anyone can generate) or `"failed"`; `message` is the sentence to show a person.
pub fn evidence_verify(
    files: &Files,
    public_key: Option<&str>,
    full_log: Option<&[u8]>,
    require_timestamp: bool,
) -> Result<Value, String> {
    let expected = public_key.map(|k| hex32("public key", k)).transpose()?;
    let r = verify_bundle(
        files,
        &VerifyOptions {
            expected_public_key: expected,
            full_log,
            require_timestamp,
            tsa_anchors: None,
        },
    );
    let fp = r.signer_fingerprint.clone().unwrap_or_default();
    let (verdict, message) = if !r.ok {
        (
            "failed",
            "NOT VERIFIED: at least one check failed; see `failures`.".to_string(),
        )
    } else if r.signer_pinned {
        (
            "verified",
            format!("VERIFIED against the public key you supplied (signer fingerprint {fp})."),
        )
    } else {
        (
            "intact-signer-not-pinned",
            format!(
                "INTACT, BUT THE SIGNER IS NOT PINNED: the hashes and signature are consistent with key {fp}, which the pack names itself. Supply the signer's public key, obtained from the signer by another route, to establish who signed it."
            ),
        )
    };
    let mut v = serde_json::to_value(&r).map_err(|e| e.to_string())?;
    v["verdict"] = verdict.into();
    v["message"] = message.into();
    Ok(v)
}

/// A pack's files as JSON, for surfaces that carry text: each file is `{"utf8": text}`, or
/// `{"base64": bytes}` when it is not valid UTF-8.
pub fn files_to_json(files: &Files) -> Value {
    Value::Object(
        files
            .iter()
            .map(|(k, v)| {
                let body = match std::str::from_utf8(v) {
                    Ok(t) => json!({"utf8": t}),
                    Err(_) => json!({"base64": crate::permalink::base64_encode(v)}),
                };
                (k.clone(), body)
            })
            .collect(),
    )
}

/// The inverse of [`files_to_json`]; a bare string is taken as UTF-8 text. At most 64 files.
pub fn files_from_json(v: &Value) -> Result<Files, String> {
    let o = v
        .as_object()
        .ok_or("files must be a JSON object of name to content")?;
    if o.len() > 64 {
        return Err("a pack has at most 64 files".into());
    }
    o.iter()
        .map(|(k, c)| {
            if k.contains(['/', '\\']) || k.is_empty() {
                return Err(format!("file name `{k}` must be a plain name"));
            }
            let bytes = if let Some(t) = c.as_str().or_else(|| c["utf8"].as_str()) {
                t.as_bytes().to_vec()
            } else if let Some(b) = c["base64"].as_str() {
                crate::permalink::base64_decode(b)
                    .ok_or_else(|| format!("{k}: `base64` is not valid standard base64"))?
            } else {
                return Err(format!(
                    "{k}: give a string, {{\"utf8\": ...}} or {{\"base64\": ...}}"
                ));
            };
            Ok((k.clone(), bytes))
        })
        .collect()
}

/// `sky_geometry` ([`crate::geometry::sky_geometry`]) on a request given as JSON or TOML text:
/// the satellites a site sees under a skyline, their DOP, the ENU cofactor and covariance and
/// the horizontal error ellipse, as JSON. MODELLED; the result carries its label, statement and
/// the advisory.
pub fn sky_geometry(request: &str, max_bytes: usize) -> Result<String, String> {
    cap("sky request", request, max_bytes)?;
    crate::geometry::sky_geometry_json(request)
}

/// `sky_monte_carlo` ([`crate::geometry::sky_monte_carlo`]): `n` (at most
/// [`crate::geometry::MAX_MC_SAMPLES`]) seeded least-squares errors on the visible set of the
/// request, with their empirical covariance, RMS and 95 % containment, as JSON.
pub fn sky_monte_carlo(
    request: &str,
    seed: u64,
    n: usize,
    max_bytes: usize,
) -> Result<String, String> {
    cap("sky request", request, max_bytes)?;
    crate::geometry::sky_monte_carlo_json(request, seed, n)
}

/// `skyline_presets` ([`crate::geometry::skyline_presets`]): the named presets with their
/// REPRESENTATIVE label, provenance and 360-entry tables, as JSON.
pub fn skyline_presets() -> String {
    crate::geometry::skyline_presets_json()
}

/// `skyline_profile` ([`crate::geometry::skyline_profile`]): a skyline section given as JSON or
/// TOML reduced to the normalised 360-entry table the engine uses, as JSON.
pub fn skyline_profile(skyline: &str, max_bytes: usize) -> Result<String, String> {
    cap("skyline", skyline, max_bytes)?;
    crate::geometry::skyline_profile_json(skyline)
}

/// `skyplot_svg` ([`crate::geometry::skyplot_svg`]): the request's skyplot as static SVG.
pub fn skyplot_svg(request: &str, max_bytes: usize) -> Result<String, String> {
    cap("sky request", request, max_bytes)?;
    crate::geometry::skyplot_svg_text(request)
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::evidence::public_key_hex;

    const ADSB: &str = include_str!("../examples/interference-map/input/adsb.csv");
    const AIS: &str = include_str!("../examples/interference-map/input/ais.csv");
    const LAND: &str = include_str!("../examples/interference-map/input/land.geojson");
    const NMEA: &str = include_str!("../examples/maritime-trust/tallinn-helsinki.nmea");
    const SESSION: &str = include_str!("../examples/maritime-trust/session.toml");
    const TRAINING: &str = include_str!("../scenarios/training/open-sea-jamming.toml");

    fn custom() -> CustomDataset {
        CustomDataset {
            licence: "CC0-1.0".into(),
            licence_url: "https://creativecommons.org/publicdomain/zero/1.0/".into(),
            attribution:
                "Synthetic data generated for Kshana documentation. Not real observations.".into(),
        }
    }

    #[test]
    fn adsb_and_ais_maps_match_the_cli_samples() {
        for (src, csv, land, sample) in [
            (
                MapSource::Adsb,
                ADSB,
                None,
                include_str!("../examples/interference-map/output/adsb-custom-2026-03-01.geojson"),
            ),
            (
                MapSource::Ais,
                AIS,
                Some(LAND),
                include_str!("../examples/interference-map/output/ais-custom-2026-03-01.geojson"),
            ),
        ] {
            let days = interference_map(
                src,
                csv,
                "custom",
                None,
                Some(&custom()),
                land,
                MAX_INPUT_BYTES,
            )
            .unwrap();
            assert_eq!(days.len(), 1);
            let (mut a, mut b): (serde_json::Value, serde_json::Value) = (
                serde_json::from_str(&days[0].geojson).unwrap(),
                serde_json::from_str(sample).unwrap(),
            );
            for v in [&mut a, &mut b] {
                v["kshana_interference_map"]["kshana_version"] = "X".into();
            }
            assert_eq!(a, b);
            assert_eq!(
                a["kshana_interference_map"]["schema"],
                "kshana-interference-map/v1"
            );
            assert!(days[0].cells_published > 0);
        }
    }

    #[test]
    fn route_exposure_runs_on_an_in_memory_map() {
        let day = interference_map(
            MapSource::Adsb,
            ADSB,
            "custom",
            None,
            Some(&custom()),
            None,
            MAX_INPUT_BYTES,
        )
        .unwrap();
        let route = r#"{"type":"LineString","coordinates":[[-10.0,35.0],[10.0,55.0]]}"#;
        let rep = route_exposure(route, &[&day[0].geojson], None, None, MAX_INPUT_BYTES).unwrap();
        let v: serde_json::Value = serde_json::from_str(&rep).unwrap();
        assert!(v.is_object());
        assert!(route_exposure(route, &[], None, None, MAX_INPUT_BYTES).is_err());
        assert!(route_exposure(
            route,
            &[&day[0].geojson],
            Some("2030-01-01"),
            None,
            MAX_INPUT_BYTES
        )
        .unwrap_err()
        .contains("no map"));
    }

    #[test]
    fn inputs_are_capped_and_datasets_are_checked() {
        assert!(interference_map(
            MapSource::Adsb,
            ADSB,
            "custom",
            None,
            None,
            None,
            MAX_INPUT_BYTES
        )
        .is_err());
        assert!(interference_map(
            MapSource::Adsb,
            ADSB,
            "custom",
            None,
            Some(&custom()),
            None,
            100
        )
        .unwrap_err()
        .contains("limit"));
        assert!(interference_map(
            MapSource::Ais,
            AIS,
            "adsb-lol",
            None,
            None,
            None,
            MAX_INPUT_BYTES
        )
        .unwrap_err()
        .contains("data"));
        assert!(MapSource::parse("radar").is_err());
    }

    #[test]
    fn inline_receiver_assessment_refuses_paths_and_runs_inline_logs() {
        let e = assess_receiver_log_inline(SESSION, MAX_INPUT_BYTES).unwrap_err();
        assert!(e.contains("path"), "{e}");
        let mut v: toml::Value = toml::from_str(SESSION).unwrap();
        let log = v["log"].as_table_mut().unwrap();
        log.remove("path");
        log.insert("text".into(), toml::Value::String(NMEA.to_string()));
        let inline = toml::to_string(&v).unwrap();
        let out = assess_receiver_log_inline(&inline, MAX_INPUT_BYTES).unwrap();
        assert!(!out.summary.is_empty());
        assert!(out.json.contains("score"));
        assert!(assess_receiver_log_inline(&inline, 1000)
            .unwrap_err()
            .contains("limit"));
    }

    /// Seconds 1400 to 1800 of the synthetic 3000-second ferry log (the drag-off starts at
    /// 1500 s) and a session with a 60 s calibration window: the same engine, in a fraction
    /// of the debug-build runtime.
    fn excerpt() -> (String, &'static str) {
        let at = |t: usize| NMEA[..NMEA.len() * t / 3000].rfind('\n').unwrap() + 1;
        let session = SESSION
            .replace("path = \"tallinn-helsinki.nmea\"", "")
            .replace("calibration_s = 300.0", "calibration_s = 60.0");
        (session, &NMEA[at(1400)..at(1800)])
    }

    #[test]
    fn vessel_excerpt_scores_the_synthetic_drag_off_and_is_bounded() {
        let (session, nmea) = excerpt();
        let r = assess_vessel_excerpt(&session, nmea.as_bytes(), MAX_INPUT_BYTES).unwrap();
        assert!(r.summary.epochs > 300 && r.summary.calibrating > 0 && r.summary.nominal > 0);
        assert!(
            r.summary.untrusted > 0,
            "the drag-off must be flagged: {:?}",
            r.summary
        );
        assert!(r.summary.lowest_score.unwrap() < 55.0);
        assert!(assess_vessel_excerpt(&session, nmea.as_bytes(), 1000).is_err());
        let static_session = "[platform]\nkind = \"static\"";
        assert!(assess_vessel_excerpt(static_session, nmea.as_bytes(), MAX_INPUT_BYTES).is_err());
    }

    #[test]
    fn vessel_log_batch_matches_the_excerpt_json_shape() {
        let (session, nmea) = excerpt();
        let j = assess_vessel_log_json(&session, nmea.as_bytes(), MAX_INPUT_BYTES).unwrap();
        let v: Value = serde_json::from_str(&j).unwrap();
        assert!(v["epochs"].as_array().unwrap().len() > 300);
        assert!(assess_vessel_log_json(&session, nmea.as_bytes(), 1000).is_err());
    }

    #[test]
    fn evidence_pack_round_trips_and_detects_tampering() {
        let (session, nmea) = excerpt();
        let seed = [7u8; 32];
        let p = evidence_create(
            &session,
            nmea.as_bytes(),
            100.0,
            300.0,
            Some("test pack"),
            None,
            Some(seed),
            MAX_INPUT_BYTES,
        )
        .unwrap();
        assert!(p.epochs_in_window > 100 && p.slice.is_some());
        for f in [
            "manifest.json",
            "manifest.sig",
            "epochs.json",
            "summary.html",
            "log-slice.bin",
        ] {
            assert!(p.files.contains_key(f), "{f}");
        }
        // Reproducible: no creation time, same seed, same bytes.
        let again = evidence_create(
            &session,
            nmea.as_bytes(),
            100.0,
            300.0,
            Some("test pack"),
            None,
            Some(seed),
            MAX_INPUT_BYTES,
        )
        .unwrap();
        assert_eq!(p.files, again.files);

        let ok =
            evidence_verify(&p.files, Some(&p.public_key), Some(nmea.as_bytes()), false).unwrap();
        assert_eq!(ok["ok"], true, "{}", ok["failures"]);
        assert_eq!(ok["verdict"], "verified");
        assert_eq!(ok["signer_pinned"], true);
        // Through JSON and back (how the browser and MCP surfaces carry it).
        let back = files_from_json(&files_to_json(&p.files)).unwrap();
        assert_eq!(back, p.files);
        // One changed byte fails; a different trusted key fails; the wrong log fails.
        let verdict = |files: &Files, key: Option<&str>, log: Option<&[u8]>| {
            evidence_verify(files, key, log, false).unwrap()["verdict"].clone()
        };
        let mut bad = p.files.clone();
        bad.get_mut("epochs.json").unwrap()[10] ^= 1;
        assert_eq!(verdict(&bad, Some(&p.public_key), None), "failed");
        let other = public_key_hex(&[9u8; 32]);
        assert_eq!(verdict(&p.files, Some(&other), None), "failed");
        assert_eq!(verdict(&p.files, None, Some(b"not the log")), "failed");
        // Without a trusted key an intact pack is reported as intact with the signer NOT
        // pinned, never as plainly verified.
        let unpinned = evidence_verify(&p.files, None, None, false).unwrap();
        assert_eq!(unpinned["verdict"], "intact-signer-not-pinned");
        assert_eq!(unpinned["signer_pinned"], false);
        assert!(unpinned["message"].as_str().unwrap().contains("NOT PINNED"));
        // A timestamp can be demanded; this pack has none.
        assert_eq!(
            evidence_verify(&p.files, Some(&p.public_key), None, true).unwrap()["verdict"],
            "failed"
        );
        assert!(evidence_verify(&p.files, Some("zz"), None, false).is_err());
        // A timestamp token over the manifest binds, is then required and found, a second
        // one is refused unless replaced, and one over something else is refused.
        let digest = <sha2::Sha256 as sha2::Digest>::digest(&p.files["manifest.json"]);
        let tsr = crate::evidence::tsr::test_token::token(&digest, "20260102030405Z", true);
        let stamped = evidence_attach_timestamp(&p.files, &tsr, false, MAX_INPUT_BYTES).unwrap();
        assert!(stamped.files.contains_key("timestamp.tsr"));
        assert_eq!(
            evidence_verify(&stamped.files, Some(&p.public_key), None, true).unwrap()["verdict"],
            "verified"
        );
        assert!(evidence_attach_timestamp(&stamped.files, &tsr, false, MAX_INPUT_BYTES).is_err());
        assert!(evidence_attach_timestamp(&stamped.files, &tsr, true, MAX_INPUT_BYTES).is_ok());
        let wrong = crate::evidence::tsr::test_token::token(&[0u8; 32], "20260102030405Z", true);
        assert!(evidence_attach_timestamp(&p.files, &wrong, false, MAX_INPUT_BYTES).is_err());
        assert!(evidence_attach_timestamp(&p.files, b"", false, MAX_INPUT_BYTES).is_err());
        assert!(evidence_attach_timestamp(&p.files, &tsr, false, 100).is_err());
        // Key generation: distinct keys, and the public key matches the seed.
        let (k1, k2) = (evidence_keygen(), evidence_keygen());
        assert_ne!(k1.seed_hex, k2.seed_hex);
        assert_eq!(
            k1.public_key,
            public_key_hex(&hex32("seed", &k1.seed_hex).unwrap())
        );
        assert_eq!(k1.fingerprint.len(), 32);
        // An empty window is refused; the seed is not part of the files.
        assert!(evidence_create(
            &session,
            nmea.as_bytes(),
            9000.0,
            9100.0,
            None,
            None,
            None,
            MAX_INPUT_BYTES
        )
        .is_err());
        let hex_seed = hex::encode(seed);
        assert!(p
            .files
            .values()
            .all(|b| !String::from_utf8_lossy(b).contains(&hex_seed)));
    }

    #[test]
    fn scenarios_naming_files_are_refused_and_bundled_ones_pass() {
        let refused = |t: &str| reject_file_sources(t, MAX_INPUT_BYTES).unwrap_err();
        assert!(refused("kind = \"telecom-timing\"\ncsv_path = \"x.csv\"").contains("csv_path"));
        assert!(
            refused("kind = \"spectrum\"\n[recording]\nmeta_path = \"a.sigmf-meta\"")
                .contains("meta_path")
        );
        assert!(
            refused("kind = \"realtime-frame-eop\"\neop_finals2000a = \"/etc/x\"")
                .contains("eop_finals2000a")
        );
        assert!(
            refused("kind = \"receiver-trust\"\n[log]\nformat = \"nmea\"\npath = \"x\"")
                .contains("path")
        );
        assert!(refused("[log.nav]\npath = \"x\"").contains("path"));
        // Nested in a campaign member.
        assert!(refused(
            "kind = \"campaign\"\n[[phases]]\n[phases.scenario]\nplanetary_kernel_path = \"k.bsp\""
        )
        .contains("planetary_kernel_path"));
        // Inline bodies and result paths are fine.
        reject_file_sources(
            "kind = \"ephemeris\"\neop_finals2000a = \"inline body\"",
            MAX_INPUT_BYTES,
        )
        .unwrap();
        reject_file_sources(
            "kind = \"campaign\"\n[[metrics]]\nname = \"a\"\npath = \"quantum.fom.x\"",
            MAX_INPUT_BYTES,
        )
        .unwrap();
        // Not TOML: left to the engine's own message. Over the cap: refused.
        reject_file_sources("not toml {{", MAX_INPUT_BYTES).unwrap();
        assert!(reject_file_sources("x = 1", 2)
            .unwrap_err()
            .contains("limit"));
    }

    #[test]
    fn files_json_refuses_paths_and_junk() {
        assert!(files_from_json(&json!({"../x": "a"})).is_err());
        assert!(files_from_json(&json!({"a": 5})).is_err());
        assert!(files_from_json(&json!({"a": {"base64": "!!"}})).is_err());
        assert!(files_from_json(&json!([1])).is_err());
        assert_eq!(files_from_json(&json!({"a": "hi"})).unwrap()["a"], b"hi");
    }

    #[test]
    fn training_nmea_is_deterministic_per_seed() {
        let a = nmea_training(TRAINING, None, MAX_INPUT_BYTES).unwrap();
        assert_eq!(
            a.nmea,
            nmea_training(TRAINING, None, MAX_INPUT_BYTES).unwrap().nmea
        );
        assert_ne!(
            a.nmea,
            nmea_training(TRAINING, Some(7), MAX_INPUT_BYTES)
                .unwrap()
                .nmea
        );
        assert!(a.nmea.contains("\r\n") && a.log_json.contains("kshana-nmea-training/1"));
        assert!(!a.log_text.is_empty());
        assert!(nmea_training("[scenario]", None, MAX_INPUT_BYTES).is_err());
    }

    #[test]
    fn compliance_report_fills_the_mapping_from_text() {
        let result = r#"{"scenario_hash":"0123456789abcdef0123","log":{"format":"nmea","epochs":10},
            "monitors_run":["cn0"],"events_evaluable":2,"events_detected":2,
            "predictions_evaluable":1,"predictions_agreeing":1}"#;
        let out = compliance_report(
            &[
                ComplianceRunText {
                    label: "trust.result.json".into(),
                    result_json: result.into(),
                    scenario_toml: None,
                },
                ComplianceRunText {
                    label: "bad.json".into(),
                    result_json: "not json".into(),
                    scenario_toml: None,
                },
            ],
            MAX_INPUT_BYTES,
        )
        .unwrap();
        assert_eq!(out.report["statement"], crate::compliance::STATEMENT);
        assert!(out.markdown.contains(crate::compliance::STATEMENT));
        assert_eq!(out.report["runs"].as_array().unwrap().len(), 1);
        assert_eq!(out.report["unrecognised"].as_array().unwrap().len(), 1);
        assert!(!out.report["rows"].as_array().unwrap().is_empty());
        // Over the cap is refused, and so is a pile of runs.
        assert!(compliance_report(
            &[ComplianceRunText {
                label: "x".into(),
                result_json: result.into(),
                scenario_toml: None
            }],
            10
        )
        .is_err());
        let many = vec![ComplianceRunText::default(); MAX_COMPLIANCE_RUNS + 1];
        assert!(compliance_report(&many, MAX_INPUT_BYTES).is_err());
        // The static tables and the sources both lead with the statement.
        for sources in [false, true] {
            let m = compliance_mapping(sources);
            assert!(m.starts_with(&format!("> {}", crate::compliance::STATEMENT)));
            // The one proper noun (the framework's own title and URL) holds a banned stem.
            let low = m
                .to_lowercase()
                .replace("conformance framework", "")
                .replace("conformance_framework", "");
            for banned in ["certif", "complies", "compliant", "conform"] {
                assert!(!low.contains(banned), "{banned}");
            }
        }
    }

    #[test]
    fn bench_export_is_in_memory_deterministic_and_checks_its_epoch() {
        let toml = std::fs::read_to_string(
            std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("scenarios/gnss-ins.toml"),
        )
        .or_else(|_| {
            std::fs::read_to_string(
                std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
                    .join("scenarios/automotive-urban-canyon.toml"),
            )
        })
        .unwrap();
        let a = bench_export(&toml, Some("2025-03-01T10:00:00Z"), MAX_INPUT_BYTES).unwrap();
        let b = bench_export(&toml, Some("2025-03-01T10:00:00"), MAX_INPUT_BYTES).unwrap();
        assert_eq!(a.files, b.files);
        let suffixes: Vec<&str> = a.files.iter().map(|f| f.0.as_str()).collect();
        assert!(suffixes.contains(&".motion.csv") && suffixes.contains(&".events.toml"));
        assert!(a.files[0].1.contains("2025-03-01"));
        assert!(bench_export(&toml, Some("2025-13-01T00:00:00"), MAX_INPUT_BYTES).is_err());
        assert!(bench_export(&toml, None, 10).is_err());
        assert!(bench_export("kind = \"orbit\"\n", None, MAX_INPUT_BYTES).is_err());
        let low = BENCH_NOTICE.to_lowercase();
        for banned in ["certif", "complies", "compliant", "conform"] {
            assert!(!low.contains(banned));
        }
    }

    #[cfg(feature = "bundled-scenarios")]
    #[test]
    fn scenario_tools_work_in_memory() {
        // Examples.
        let all = list_examples(None).unwrap();
        assert!(all["count"].as_u64().unwrap() > 50);
        let orbit = list_examples(Some("orbit")).unwrap();
        assert!(orbit["scenarios"]
            .as_array()
            .unwrap()
            .iter()
            .all(|e| e["kind"] == "orbit"));
        assert!(list_examples(Some("no-such-kind")).is_err());
        let clock = get_example("clock-holdover").unwrap();
        assert!(get_example("no-such-example").is_err());
        // Exports.
        let plan = export_formats(clock, MAX_INPUT_BYTES).unwrap();
        assert_eq!(plan.as_array().unwrap().len(), 5);
        let orbit_toml = get_example("orbit-multignss").unwrap();
        let czml = export_scenario(orbit_toml, "czml", MAX_INPUT_BYTES).unwrap();
        assert_eq!(czml.format, "czml");
        assert_eq!(czml.files[0].encoding, "utf-8");
        assert_eq!(
            czml.files[0].sha256,
            crate::advanced_report::sha256_hex(czml.files[0].content.as_bytes())
        );
        assert_eq!(
            czml.to_json(),
            export_scenario(orbit_toml, "czml", MAX_INPUT_BYTES)
                .unwrap()
                .to_json()
        );
        assert!(export_scenario(clock, "czml", MAX_INPUT_BYTES).is_err());
        assert!(export_scenario(orbit_toml, "nope", MAX_INPUT_BYTES).is_err());
        assert!(export_scenario(orbit_toml, "czml", 10).is_err());
        // Route import: a clock scenario takes no route; a track kind does.
        let route = r#"{"type":"LineString","coordinates":[[10.0,50.0],[10.5,50.0]]}"#;
        assert!(import_route(clock, route, MAX_INPUT_BYTES).is_err());
        let moved =
            import_route(get_example("terrain-nav").unwrap(), route, MAX_INPUT_BYTES).unwrap();
        assert!(moved.contains("start_lat_deg = 50"));
        // Animation.
        let a = animate_scenario(clock, Some("svg"), None, None, None, MAX_INPUT_BYTES).unwrap();
        assert_eq!(a.files.len(), 1);
        assert!(a.files[0].1.starts_with("<svg") || a.files[0].1.contains("<svg"));
        let f = animate_scenario(
            clock,
            Some("frames"),
            Some(10),
            Some(3.0),
            None,
            MAX_INPUT_BYTES,
        )
        .unwrap();
        assert!(f.files.iter().any(|x| x.0 == "manifest.json"));
        assert!(animate_scenario(
            clock,
            Some("frames"),
            Some(60),
            Some(600.0),
            None,
            MAX_INPUT_BYTES
        )
        .is_err());
        assert!(animate_scenario(clock, Some("gif"), None, None, None, MAX_INPUT_BYTES).is_err());
    }
}