navcore_signalk/

delta.rs

//! Reading a Signal K delta, in the units the rest of this workspace uses.
//!
//! The wire is SI and the rest of this workspace is not: Signal K carries
//! courses and headings in **radians** and speeds in **metres per
//! second**, while everything above `nav-math` works in degrees and
//! knots. Position is the exception -- it is already degrees. That
//! conversion happens here, once, rather than in every consumer, and it
//! is the main thing this module is for.
//!
//! Anything unrecognised is skipped rather than refused. A Signal K server
//! sends dozens of paths a caller may have no use for and will send more
//! after the next update; a reader that failed on the first unknown one
//! would stop working the day the boat gained a sensor.

use nav_math::Position;

/// Radians to degrees, and metres per second to knots. Written out because
/// getting either backwards produces numbers that look plausible on screen.
pub(crate) const KNOTS_PER_METRE_PER_SECOND: f64 = 3600.0 / nav_math::METRES_PER_NM;

/// Whose data a delta is about.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Context {
    /// This vessel.
    SelfVessel,
    /// Somebody else -- an AIS target, or another boat the server knows
    /// about. Kept rather than dropped so the caller can decide; feeding
    /// another vessel's position into own-ship display is the kind of
    /// mistake that only shows up at sea.
    Other(String),
}

/// One value from one source.
#[derive(Debug, Clone, PartialEq)]
pub struct Reading {
    /// The Signal K source label, `$source` or `source.label`. This is what
    /// tells the boat's own GPS apart from the cockpit's, so it is not
    /// optional as far as this crate is concerned -- a reading whose origin
    /// is unknown gets the label `"unknown"` rather than being dropped.
    pub source: String,
    /// The sender's own timestamp, verbatim and unparsed.
    ///
    /// Deliberately not turned into an instant to compute age from. Age is
    /// measured against the receiving clock (see [`fix::Sources`]),
    /// because two computers on a boat disagree about the time far more
    /// often than anyone expects, and an age computed across that
    /// disagreement can come out negative.
    pub timestamp: Option<String>,
    /// What was measured.
    pub measurement: Measurement,
}

/// What a sounding is measured from.
///
/// An echo sounder measures from its own face and knows nothing else. Every
/// other reference is that measurement plus a distance somebody stated about
/// the vessel, and the difference between them is not decoration: a keel
/// offset is typically 0.3 to 1.5 m, which is the whole margin a boat has
/// when it matters.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Sounding {
    /// From the transducer face. What the instrument actually measured, and
    /// what NMEA's `DBT` carries with no offset at all.
    BelowTransducer,
    /// From the bottom of the keel. What a mariner means by "how much water
    /// is under me".
    BelowKeel,
    /// From the water surface. What a chart means by a depth.
    BelowSurface,
}

/// A sounding, and what it was measured from.
///
/// The reference travels with the number so that nothing downstream has to
/// assume one. This is the same discipline a Raymarine, B&G or Garmin
/// display keeps: the offset is stated once, the value is labelled, and an
/// unconfigured installation reads out depth below the transducer rather
/// than quietly claiming to be depth below the keel.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct Depth {
    /// Metres. Signal K is already metric here, so nothing is converted.
    pub metres: f64,
    /// What it is measured from.
    pub reference: Sounding,
}

/// The vessel's sounder geometry, as far as it is known.
///
/// Both are distances Signal K states positive downwards, and both are
/// properties of the installation rather than of the water. They arrive on
/// the wire like anything else when the server has been told them, and stay
/// `None` when it has not.
#[derive(Debug, Clone, Copy, Default, PartialEq)]
pub struct Offsets {
    /// Transducer face down to the bottom of the keel.
    pub transducer_to_keel: Option<f64>,
    /// Water surface down to the transducer face.
    pub surface_to_transducer: Option<f64>,
}

impl Depth {
    /// The same sounding measured from somewhere else, if the geometry to
    /// get there is known.
    ///
    /// `None` when it is not, and that is the whole point of the type.
    /// Guessing an offset -- or worse, leaving it at zero and calling the
    /// result depth below the keel -- reports **more water than there is**,
    /// by exactly the amount nobody stated. A depth display that does that
    /// is wrong in the one direction it must never be wrong in.
    ///
    /// A negative result is not an error and is not clamped: it means the
    /// keel is already in the bottom, which is worth showing.
    #[must_use]
    pub fn to(self, wanted: Sounding, offsets: Offsets) -> Option<Self> {
        // Everything goes via the transducer, because that is the only
        // reference the instrument actually measured.
        let below_transducer = match self.reference {
            Sounding::BelowTransducer => self.metres,
            Sounding::BelowKeel => self.metres + offsets.transducer_to_keel?,
            Sounding::BelowSurface => self.metres - offsets.surface_to_transducer?,
        };
        let metres = match wanted {
            Sounding::BelowTransducer => below_transducer,
            Sounding::BelowKeel => below_transducer - offsets.transducer_to_keel?,
            Sounding::BelowSurface => below_transducer + offsets.surface_to_transducer?,
        };
        Some(Self {
            metres,
            reference: wanted,
        })
    }
}

/// The tracking status a target-tracking plugin publishes per target on
/// `sensors.ais.status` -- confirmed live against `sk-ais-status-plugin`
/// (not a Signal K specification path, a third-party convention). Its
/// own README recommends the following treatment:
///
/// - `Unconfirmed`: shown, but de-emphasised -- not yet enough reports
///   to trust as more than a suspect decode.
/// - `Confirmed`: shown normally.
/// - `Lost`: shown faded, with its age -- gone quiet longer than its
///   own class's own patience allows.
/// - `Remove`: dropped outright, the same as this crate's own fallback
///   timeout for a server with no such plugin.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AisTargetStatus {
    /// A position has arrived, but not yet enough reports to trust it.
    Unconfirmed,
    /// Enough consistent reports have arrived to treat this normally.
    Confirmed,
    /// Gone quiet longer than its own class's own patience allows.
    Lost,
    /// Gone quiet long enough a display should drop it outright.
    Remove,
}

impl AisTargetStatus {
    /// The variant a wire string names, or `None` for anything this
    /// crate does not recognise -- skipped, not refused, the same
    /// "unknown paths and values are simply not readings" discipline
    /// this module's own doc states for everything else.
    fn from_wire(value: &str) -> Option<Self> {
        match value {
            "unconfirmed" => Some(Self::Unconfirmed),
            "confirmed" => Some(Self::Confirmed),
            "lost" => Some(Self::Lost),
            "remove" => Some(Self::Remove),
            _ => None,
        }
    }
}

/// Which kind of AIS transponder a target carries, `sensors.ais.class`.
///
/// Worth showing because it says what to expect of the rest: a Class B
/// unit reports less often, and sends no heading, destination or draught
/// worth reading.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AisClass {
    /// Class A: ships obliged to carry AIS.
    A,
    /// Class B: the lighter unit most pleasure craft carry.
    B,
}

impl AisClass {
    fn from_wire(value: &str) -> Option<Self> {
        match value {
            "A" => Some(Self::A),
            "B" => Some(Self::B),
            _ => None,
        }
    }
}

/// A Signal K notification's own severity -- the schema's `alarmState`
/// enum, read off a notification's `state` field. Five of its six defined
/// values are modelled here (`nominal` is left out: the schema defines it,
/// but no producer this crate has actually been read against -- neither
/// `signalk-derived-data` nor `signalk-ais-target-prioritizer`'s own CPA
/// alarms, both confirmed live -- ever emits it, and the same
/// skip-unrecognised discipline this module keeps everywhere else means
/// an unmodelled value is simply not a reading rather than a parse
/// failure).
///
/// `Ord`ered least to most severe, the same order the schema itself lists
/// them in, so a caller can ask "at least `Alarm`" with a plain
/// comparison rather than a match.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum NotificationSeverity {
    /// Nothing wrong.
    Normal,
    /// Worth a mariner's attention eventually.
    Alert,
    /// Worth a mariner's attention soon.
    Warn,
    /// Worth a mariner's attention now.
    Alarm,
    /// The most severe level the schema defines.
    Emergency,
}

impl NotificationSeverity {
    /// The variant a wire string names, or `None` for anything this
    /// crate does not recognise.
    fn from_wire(value: &str) -> Option<Self> {
        match value {
            "normal" => Some(Self::Normal),
            "alert" => Some(Self::Alert),
            "warn" => Some(Self::Warn),
            "alarm" => Some(Self::Alarm),
            "emergency" => Some(Self::Emergency),
            _ => None,
        }
    }
}

/// The values a caller has a use for. Everything else on the wire is
/// skipped.
///
/// `Clone`, not `Copy`: most variants are a plain number or [`Position`],
/// cheap to duplicate either way, but
/// [`CourseActiveRouteHref`](Measurement::CourseActiveRouteHref) carries
/// an owned `String`, which `Copy` cannot hold -- a caller matching the
/// same reading against several consumers in turn clones it explicitly.
#[derive(Debug, Clone, PartialEq)]
pub enum Measurement {
    /// Where the vessel is.
    Position(Position),
    /// Course over ground, degrees true -- converted from Signal K's
    /// radians.
    CourseOverGround(f64),
    /// Speed over ground in knots, converted from metres per second.
    SpeedOverGround(f64),
    /// Heading, degrees true, converted from radians.
    Heading(f64),
    /// A vessel's own name, from the bare `name` path -- the same path
    /// on any context, self or otherwise, which is what makes this
    /// useful for an AIS target: a position with no name attached is
    /// just a dot on the chart.
    VesselName(String),
    /// An AIS (or other) target's own tracking status, `sensors.ais.status`
    /// -- confirmed live against `sk-ais-status-plugin`, not a Signal K
    /// specification path, but a real, already-observed convention worth
    /// reading passively the same as anything else this crate did not
    /// invent. See [`AisTargetStatus`]'s own doc.
    AisTargetStatus(AisTargetStatus),
    /// A CPA/TCPA collision alarm's own severity, from
    /// `notifications.navigation.closestApproach` -- not a Signal K
    /// specification path (`notifications.collision.*` is the schema's
    /// own "Well Known Name" for this; no CPA plugin surveyed while this
    /// was built actually uses it), but a real, already-observed
    /// convention: both `signalk-derived-data` and
    /// `signalk-ais-target-prioritizer` publish their own computed
    /// CPA/TCPA alarm here, confirmed live against the latter (the one
    /// a first client was built against -- see [`NotificationSeverity`]'s
    /// own doc). Read passively, the same "worth reading, not worth
    /// depending on being there" treatment [`Measurement::AisTargetStatus`]
    /// already gets: a server with no such plugin simply never produces
    /// this reading, and nothing downstream requires it.
    ClosestApproachAlarm(NotificationSeverity),
    /// The transponder class, from `sensors.ais.class`.
    AisClass(AisClass),
    /// What kind of vessel it says it is, `design.aisShipType`'s own
    /// `name` -- "Cargo ship", "Sailing vessel". Only the name is kept;
    /// the numeric id is the same fact in a code nobody reads.
    AisShipType(String),
    /// The VHF call sign, `communication.callsignVhf` -- read off that
    /// flat path, or nested in a vessel-root update the way AIS static
    /// data actually sends it; see [`Context`]'s own module and this
    /// enum's `measurement_of` for which is which.
    Callsign(String),
    /// `signalk-ais-target-prioritizer`'s own closest-point-of-approach
    /// figures for a target, from `navigation.closestApproach` -- the
    /// numbers behind the alarm [`Measurement::ClosestApproachAlarm`]
    /// carries only the severity of. Confirmed live: the plugin publishes
    /// this object for every target it tracks, and **leaves `distance` and
    /// `timeTo` out** of it whenever there is no approach to speak of (a
    /// target moving away, or further than its own ceilings), so both are
    /// `None` then and a reader must let that overwrite what it held, not
    /// keep the last figure. Nothing here computes a CPA: this reads the
    /// plugin's answer, as a client reads its alarm.
    ClosestApproach {
        /// Distance at closest approach, metres.
        cpa_m: Option<f64>,
        /// Seconds until it, when it lies ahead.
        tcpa_s: Option<f64>,
    },
    /// A sounding, carrying what it was measured from.
    Depth(Depth),
    /// Transducer face to the bottom of the keel, metres. Configuration
    /// rather than a measurement, but it arrives the same way.
    TransducerToKeel(f64),
    /// Water surface to the transducer face, metres. Likewise.
    SurfaceToTransducer(f64),
    /// The vessel's own maximum draft, metres. Static hull data rather than
    /// a live reading, but Signal K sends it the same way -- once, on
    /// `design.draft`, as part of the burst a server hands a client on
    /// first subscribing to itself.
    MaximumDraft(f64),
    /// The vessel's own length overall, metres, from `design.length`'s own
    /// `overall` field -- static hull data, same delivery as
    /// [`Measurement::MaximumDraft`] and for the same reason.
    DesignLength(f64),
    /// The vessel's own beam (maximum width), metres, from `design.beam`.
    /// Unlike [`Measurement::MaximumDraft`]/[`Measurement::DesignLength`],
    /// the schema gives beam no sibling fields to choose among -- it is
    /// already the one number this is.
    DesignBeam(f64),
    /// Apparent wind angle, degrees off the bow, positive to starboard --
    /// converted from Signal K's radians, which already carry the same
    /// convention the other way round ("negative to port").
    WindAngleApparent(f64),
    /// Apparent wind speed in knots, converted from metres per second.
    WindSpeedApparent(f64),
    /// True wind direction, degrees true -- an absolute bearing relative
    /// to true north, not an angle off the bow, converted from Signal K's
    /// radians. Published only by a server whose own instruments (or a
    /// calculation plugin) have already done the wind-triangle work; see
    /// [`WindAngleApparent`](Measurement::WindAngleApparent) for the raw
    /// reading every installation has instead.
    WindDirectionTrue(f64),
    /// True wind speed in knots, converted from metres per second.
    WindSpeedTrue(f64),
    /// The anchor watch's own position, `navigation.anchor.position` --
    /// `None` when the path is explicitly nulled, which is how
    /// `signalk-anchoralarm-plugin` (and, per the Signal K convention it
    /// follows, any other implementation of this path) reports the
    /// anchor raised, confirmed live against a running server. Distinct
    /// from every other `Measurement` here in that a `None` is itself
    /// meaningful and must overwrite whatever a reader kept from before
    /// -- there is no staleness to lean on the way there is for a fix
    /// that simply stops arriving.
    AnchorPosition(Option<Position>),
    /// The anchor watch's own swing radius, `navigation.anchor.maxRadius`,
    /// metres. `None` on the same explicit-null convention as
    /// [`AnchorPosition`](Measurement::AnchorPosition), which a real
    /// server nulls at the same time as the position.
    AnchorMaxRadius(Option<f64>),
    /// Where the vessel is navigating towards right now,
    /// `navigation.course.nextPoint`'s own `position` -- Signal K's
    /// Course API, confirmed live against the reference implementation
    /// bundled with `signalk-server`. `None` when the whole `nextPoint`
    /// is explicitly nulled, the same convention
    /// [`AnchorPosition`](Measurement::AnchorPosition) uses: the server
    /// sends exactly that the moment nothing is being followed any more
    /// (course cleared, or never set), and that null is itself the
    /// answer to "is a route currently active", not merely a value gone
    /// stale.
    CourseNextPoint(Option<Position>),
    /// Where the vessel started navigating from, for whichever leg
    /// [`CourseNextPoint`](Measurement::CourseNextPoint) is the far end
    /// of -- `navigation.course.previousPoint`'s own `position`. A fixed
    /// point once following begins (confirmed live: the server reports
    /// the vessel's own position *at that moment*, `type:
    /// "VesselPosition"`, not a continuously-updated "where I am now"),
    /// which is what makes it usable as the `from` end of a cross-track
    /// calculation at all -- a leg that moved with the vessel would
    /// always measure zero off itself. `None` on the same explicit-null
    /// convention [`CourseNextPoint`](Measurement::CourseNextPoint)
    /// itself uses.
    CoursePreviousPoint(Option<Position>),
    /// The `href` of whatever route is actively being followed,
    /// `navigation.course.activeRoute`'s own `href` field -- confirmed
    /// live, the whole `activeRoute` object (`href`, `name`, `reverse`,
    /// `pointIndex`, `pointTotal`) arrives as one delta at this path, not
    /// nested the way [`CourseNextPoint`](Measurement::CourseNextPoint)'s
    /// own `position` is. Only `href` is kept -- the rest names how far
    /// along the route the vessel already is, which
    /// [`CourseNextPoint`](Measurement::CourseNextPoint)/
    /// [`CoursePreviousPoint`](Measurement::CoursePreviousPoint) already
    /// answer more directly -- and it exists so a caller can fetch the
    /// route's own full geometry to draw, the one thing following a
    /// route cannot otherwise show: which waypoints lie ahead, past the
    /// leg actually underway. `None` on the same explicit-null
    /// convention as the other two: a real server nulls the whole
    /// `activeRoute` object, not just this field, the moment nothing is
    /// being followed.
    CourseActiveRouteHref(Option<String>),
    /// Something was created, updated, or deleted at
    /// `resources.<resource_type>.<id>` -- confirmed live against the
    /// server's own `buildDeltaMsg` (`dist/api/resources/index.js`):
    /// broadcast on every `POST`/`PUT`/`DELETE` through the Resources
    /// API, with no `context` field at all (resources are not
    /// per-vessel the way navigation data is), which the `None` arm of
    /// this module's own context handling already treats as self -- see
    /// [`parse`]'s own doc.
    ///
    /// Carries no more than "something changed here", not the
    /// resource's own new value: that arrives as arbitrary JSON this
    /// crate has no business parsing -- `signalk` sits below
    /// `tracks`/`routes`/`waypoints` in this workspace's own one-way
    /// dependency order (see this module's own top doc), so it cannot
    /// know their shapes, only that a path matching this pattern
    /// exists. A caller reacts by asking again through the REST API it
    /// already has working (the same request a mariner's own Refresh
    /// button already makes) rather than a second, parallel path
    /// parsing this JSON that could drift from the first.
    ResourceChanged {
        /// `"tracks"`, `"routes"`, `"waypoints"`, or any other resource
        /// type collection name -- free text, since a server's own
        /// custom collections are not a fixed enum either (see
        /// `@signalk/resources-provider`'s own "custom" config).
        resource_type: String,
        /// The uuid of the specific resource that changed. Not read by
        /// any caller yet -- every one so far reacts by refreshing its
        /// whole list rather than one entry -- carried anyway since the
        /// delta already has it for free, for a future caller that
        /// wants to react to just the one.
        id: String,
    },
}

/// One delta message, read.
#[derive(Debug, Clone, PartialEq)]
pub struct Delta {
    /// Whose it is.
    pub context: Context,
    /// What it carried that this crate understands.
    pub readings: Vec<Reading>,
    /// A `performance.activePolarData` update, verbatim, when this
    /// delta's own values included one.
    ///
    /// Kept apart from `readings`/[`Measurement`] entirely rather than
    /// as another variant of that enum: a polar is a nested table's
    /// worth of JSON, not the small `Copy` scalar every other
    /// [`Measurement`] carries, and folding it in would cost that enum
    /// its `Copy` -- and every existing match site the ergonomics that
    /// comes with -- for the one path nothing else needs it for.
    /// [`crate::polar::parse`] turns this into a usable
    /// [`crate::polar::PolarResource`]; this crate only carries it as
    /// far as the wire shape, the same distance it keeps from every
    /// other value here.
    pub active_polar: Option<serde_json::Value>,
}

impl Delta {
    /// Whether this is about own ship.
    #[must_use]
    pub fn is_self(&self) -> bool {
        self.context == Context::SelfVessel
    }
}

/// Reads one delta message.
///
/// Returns `None` only when the text is not a Signal K delta at all -- not
/// when it carries nothing useful, which is an ordinary and frequent state
/// of affairs.
#[must_use]
pub fn parse(message: &str, self_id: Option<&str>) -> Option<Delta> {
    let value: serde_json::Value = serde_json::from_str(message).ok()?;
    let updates = value.get("updates")?.as_array()?;

    let context = match value.get("context").and_then(serde_json::Value::as_str) {
        // A server talking about the boat it runs on says "vessels.self",
        // or names it in full. Both mean own ship, and a client that only
        // understood one of them would work on one server and not the next.
        None | Some("vessels.self") => Context::SelfVessel,
        Some(context) => match self_id {
            Some(id) if context == id || context == format!("vessels.{id}") => Context::SelfVessel,
            _ => Context::Other(context.to_owned()),
        },
    };

    let mut readings = Vec::new();
    let mut active_polar = None;
    for update in updates {
        let source = source_of(update);
        let timestamp = update
            .get("timestamp")
            .and_then(serde_json::Value::as_str)
            .map(str::to_owned);

        let Some(values) = update.get("values").and_then(serde_json::Value::as_array) else {
            continue;
        };
        for entry in values {
            let Some(path) = entry.get("path").and_then(serde_json::Value::as_str) else {
                continue;
            };
            let Some(value) = entry.get("value") else {
                continue;
            };
            if path == "performance.activePolarData" {
                active_polar = Some(value.clone());
                continue;
            }
            if let Some(measurement) = measurement_of(path, value) {
                readings.push(Reading {
                    source: source.clone(),
                    timestamp: timestamp.clone(),
                    measurement,
                });
            }
        }
    }

    Some(Delta { context, readings, active_polar })
}

/// The label of whatever produced an update.
fn source_of(update: &serde_json::Value) -> String {
    if let Some(source) = update.get("$source").and_then(serde_json::Value::as_str) {
        return source.to_owned();
    }
    update
        .get("source")
        .and_then(|source| source.get("label"))
        .and_then(serde_json::Value::as_str)
        .unwrap_or("unknown")
        .to_owned()
}

/// One path and value, in this workspace's units.
fn measurement_of(path: &str, value: &serde_json::Value) -> Option<Measurement> {
    if let Some(reading) = resource_changed(path) {
        return Some(reading);
    }
    match path {
        "navigation.position" => {
            let lat = value.get("latitude")?.as_f64()?;
            let lon = value.get("longitude")?.as_f64()?;
            let position = Position::new(lat, lon);
            // A position off the earth is a broken sensor, not a fix. Let
            // it through and it lands on the chart as a vessel somewhere
            // impossible, which is harder to diagnose than nothing at all.
            position
                .is_valid()
                .then_some(Measurement::Position(position))
        }
        "navigation.courseOverGroundTrue" => Some(Measurement::CourseOverGround(
            nav_math::angle::norm_360(value.as_f64()?.to_degrees()),
        )),
        "navigation.headingTrue" => Some(Measurement::Heading(nav_math::angle::norm_360(
            value.as_f64()?.to_degrees(),
        ))),
        "navigation.speedOverGround" => Some(Measurement::SpeedOverGround(
            value.as_f64()? * KNOTS_PER_METRE_PER_SECOND,
        )),
        "name" => value.as_str().map(|name| Measurement::VesselName(name.to_owned())),
        // What a real server sends for an AIS target's static data: an
        // update on the vessel's *root*, an empty path with an object as
        // the value -- `{"path":"","value":{"name":"MSC AURORA"}}`, or,
        // in its own separate fragment, a call sign nested the identical
        // way -- `{"path":"","value":{"communication":{"callsignVhf":
        // "IBQY"}}}` -- and separately `{"mmsi":"..."}`, which is nothing
        // to read here. Confirmed live against signalk-server decoding
        // real `!AIVDM` type 5 and 24A/24B messages. The bare `name` and
        // `communication.callsignVhf` paths below are what a plugin or a
        // data-model write produce, not what AIS does -- a fragment ever
        // carries one of these keys, never several, so trying `name`
        // first and falling back costs nothing on a fragment that turns
        // out to carry the other.
        "" => value
            .get("name")
            .and_then(serde_json::Value::as_str)
            .map(|name| Measurement::VesselName(name.to_owned()))
            .or_else(|| {
                value
                    .get("communication")
                    .and_then(|communication| communication.get("callsignVhf"))
                    .and_then(serde_json::Value::as_str)
                    .map(|sign| Measurement::Callsign(sign.to_owned()))
            }),
        "sensors.ais.status" => value
            .as_str()
            .and_then(AisTargetStatus::from_wire)
            .map(Measurement::AisTargetStatus),
        "sensors.ais.class" => value.as_str().and_then(AisClass::from_wire).map(Measurement::AisClass),
        "design.aisShipType" => value
            .get("name")
            .and_then(serde_json::Value::as_str)
            .map(|name| Measurement::AisShipType(name.to_owned())),
        "communication.callsignVhf" => value.as_str().map(|sign| Measurement::Callsign(sign.to_owned())),
        "navigation.closestApproach" if value.is_object() => Some(Measurement::ClosestApproach {
            cpa_m: value.get("distance").and_then(serde_json::Value::as_f64),
            tcpa_s: value.get("timeTo").and_then(serde_json::Value::as_f64),
        }),
        // The standard Notification shape (`{state, method, message,
        // ...}`) -- only `state` has a use here, see
        // Measurement::ClosestApproachAlarm's own doc for the path.
        "notifications.navigation.closestApproach" => value
            .get("state")
            .and_then(serde_json::Value::as_str)
            .and_then(NotificationSeverity::from_wire)
            .map(Measurement::ClosestApproachAlarm),
        // All three are read, each keeping the reference it arrived with.
        // A server sends whichever its instruments produce: `DBT` becomes
        // `belowTransducer` and nothing else, and that is the common case on
        // a boat with older sounders.
        "environment.depth.belowTransducer" => Some(Measurement::Depth(Depth {
            metres: value.as_f64()?,
            reference: Sounding::BelowTransducer,
        })),
        "environment.depth.belowKeel" => Some(Measurement::Depth(Depth {
            metres: value.as_f64()?,
            reference: Sounding::BelowKeel,
        })),
        "environment.depth.belowSurface" => Some(Measurement::Depth(Depth {
            metres: value.as_f64()?,
            reference: Sounding::BelowSurface,
        })),
        "environment.depth.transducerToKeel" => {
            Some(Measurement::TransducerToKeel(value.as_f64()?))
        }
        "environment.depth.surfaceToTransducer" => {
            Some(Measurement::SurfaceToTransducer(value.as_f64()?))
        }
        // An object, not a bare number -- the schema also defines minimum,
        // current and canoe draft, none of which any server seen so far has
        // ever actually populated. Reading only maximum is a deliberate
        // choice, not an oversight: it is the one number that answers "how
        // deep does this vessel sit at its worst", which is what a safety
        // margin has to be measured against.
        "design.draft" => value
            .get("maximum")
            .and_then(serde_json::Value::as_f64)
            .map(Measurement::MaximumDraft),
        // Same shape as design.draft just above, reading only `overall`
        // out of the schema's own length/hull/waterline trio -- length
        // overall is the one figure a hull outline on the chart needs.
        "design.length" => value
            .get("overall")
            .and_then(serde_json::Value::as_f64)
            .map(Measurement::DesignLength),
        "design.beam" => value.as_f64().map(Measurement::DesignBeam),
        // The two ends of the wind triangle a client can actually rely on
        // seeing: apparent wind, which every instrument that measures wind
        // at all reports, and true wind direction, which only a server that
        // has already done the triangle itself (its own instrument, or a
        // calculation plugin) publishes. Both matter here rather than only
        // the derived one, because a caller with no true wind on the wire
        // still has apparent to compute it from -- see `nav_math::wind`.
        "environment.wind.angleApparent" => Some(Measurement::WindAngleApparent(
            nav_math::angle::norm_180(value.as_f64()?.to_degrees()),
        )),
        "environment.wind.speedApparent" => Some(Measurement::WindSpeedApparent(
            value.as_f64()? * KNOTS_PER_METRE_PER_SECOND,
        )),
        "environment.wind.directionTrue" => Some(Measurement::WindDirectionTrue(
            nav_math::angle::norm_360(value.as_f64()?.to_degrees()),
        )),
        "environment.wind.speedTrue" => Some(Measurement::WindSpeedTrue(
            value.as_f64()? * KNOTS_PER_METRE_PER_SECOND,
        )),
        // Explicit `null` clears (see AnchorPosition's own doc); anything
        // else has to parse as a real position or this reading is
        // dropped like any other malformed one, not read as a clear.
        "navigation.anchor.position" => {
            if value.is_null() {
                return Some(Measurement::AnchorPosition(None));
            }
            let lat = value.get("latitude")?.as_f64()?;
            let lon = value.get("longitude")?.as_f64()?;
            let position = Position::new(lat, lon);
            position
                .is_valid()
                .then_some(Measurement::AnchorPosition(Some(position)))
        }
        "navigation.anchor.maxRadius" => {
            if value.is_null() {
                return Some(Measurement::AnchorMaxRadius(None));
            }
            value.as_f64().map(|radius| Measurement::AnchorMaxRadius(Some(radius)))
        }
        // Explicit `null` clears (see CourseNextPoint's own doc). Unlike
        // `navigation.anchor.position`, the position a real value carries
        // sits nested one level down -- the Course API's own
        // `NextPreviousPoint` object has `href`/`type`/`position`/`name`
        // fields, and `position` is the only one this crate has a use
        // for so far.
        "navigation.course.nextPoint" => {
            if value.is_null() {
                return Some(Measurement::CourseNextPoint(None));
            }
            let point = value.get("position")?;
            let lat = point.get("latitude")?.as_f64()?;
            let lon = point.get("longitude")?.as_f64()?;
            let position = Position::new(lat, lon);
            position
                .is_valid()
                .then_some(Measurement::CourseNextPoint(Some(position)))
        }
        "navigation.course.previousPoint" => {
            if value.is_null() {
                return Some(Measurement::CoursePreviousPoint(None));
            }
            let point = value.get("position")?;
            let lat = point.get("latitude")?.as_f64()?;
            let lon = point.get("longitude")?.as_f64()?;
            let position = Position::new(lat, lon);
            position
                .is_valid()
                .then_some(Measurement::CoursePreviousPoint(Some(position)))
        }
        "navigation.course.activeRoute" => {
            if value.is_null() {
                return Some(Measurement::CourseActiveRouteHref(None));
            }
            let href = value.get("href")?.as_str()?;
            (!href.is_empty()).then(|| Measurement::CourseActiveRouteHref(Some(href.to_owned())))
        }
        _ => None,
    }
}

/// `resources.<resource_type>.<id>`, or `None` for anything else --
/// see [`Measurement::ResourceChanged`]'s own doc for why this is a
/// prefix match, not one more literal arm in [`measurement_of`]'s own
/// `match`: the resource type and id are both part of the path itself,
/// not a fixed string this crate could enumerate.
fn resource_changed(path: &str) -> Option<Measurement> {
    let rest = path.strip_prefix("resources.")?;
    let (resource_type, id) = rest.split_once('.')?;
    (!resource_type.is_empty() && !id.is_empty())
        .then(|| Measurement::ResourceChanged { resource_type: resource_type.to_owned(), id: id.to_owned() })
}

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

    fn one_value(path: &str, value: &str) -> String {
        format!(
            r#"{{"context":"vessels.self","updates":[{{"$source":"n2k.1",
               "timestamp":"2026-09-13T09:00:00Z",
               "values":[{{"path":"{path}","value":{value}}}]}}]}}"#
        )
    }

    #[test]
    fn a_course_arrives_in_radians_and_is_read_in_degrees() {
        // Half pi on the wire is due east. Read as degrees it would be 1.57
        // degrees -- almost due north, and plausible enough to go unnoticed.
        let delta = parse(
            &one_value("navigation.courseOverGroundTrue", "1.5707963268"),
            None,
        )
        .expect("a delta");
        let Measurement::CourseOverGround(deg) = delta.readings[0].measurement else {
            panic!("not a course: {:?}", delta.readings[0]);
        };
        assert!((deg - 90.0).abs() < 1e-6, "got {deg}");
    }

    #[test]
    fn a_speed_arrives_in_metres_per_second_and_is_read_in_knots() {
        let delta =
            parse(&one_value("navigation.speedOverGround", "5.144444"), None).expect("a delta");
        let Measurement::SpeedOverGround(knots) = delta.readings[0].measurement else {
            panic!("not a speed");
        };
        assert!((knots - 10.0).abs() < 1e-4, "got {knots}");
    }

    #[test]
    fn a_position_arrives_in_degrees_and_stays_in_degrees() {
        let delta = parse(
            &one_value(
                "navigation.position",
                r#"{"latitude":45.55,"longitude":13.73}"#,
            ),
            None,
        )
        .expect("a delta");
        assert_eq!(
            delta.readings[0].measurement,
            Measurement::Position(Position::new(45.55, 13.73))
        );
    }

    #[test]
    fn a_heading_wraps_into_the_bearing_range() {
        // Signal K permits values outside 0..2pi; a bearing of -10 degrees
        // is not a bearing anything else in this workspace accepts.
        let delta =
            parse(&one_value("navigation.headingTrue", "-0.1745329"), None).expect("a delta");
        let Measurement::Heading(deg) = delta.readings[0].measurement else {
            panic!("not a heading");
        };
        assert!((deg - 350.0).abs() < 1e-4, "got {deg}");
    }

    #[test]
    fn an_anchor_position_arrives_the_same_way_a_fix_does() {
        let delta = parse(
            &one_value(
                "navigation.anchor.position",
                r#"{"latitude":45.55,"longitude":13.73}"#,
            ),
            None,
        )
        .expect("a delta");
        assert_eq!(
            delta.readings[0].measurement,
            Measurement::AnchorPosition(Some(Position::new(45.55, 13.73)))
        );
    }

    #[test]
    fn an_explicitly_nulled_anchor_position_is_read_as_raised_not_dropped() {
        // Confirmed live against a real signalk-anchoralarm-plugin: raising
        // the anchor nulls navigation.anchor.position rather than simply
        // going quiet, and that null has to survive as far as Measurement
        // -- unlike an unparseable value, which is dropped instead.
        let delta = parse(&one_value("navigation.anchor.position", "null"), None).expect("a delta");
        assert_eq!(delta.readings[0].measurement, Measurement::AnchorPosition(None));
    }

    #[test]
    fn an_anchor_max_radius_arrives_in_metres() {
        let delta = parse(&one_value("navigation.anchor.maxRadius", "30"), None).expect("a delta");
        assert_eq!(delta.readings[0].measurement, Measurement::AnchorMaxRadius(Some(30.0)));
    }

    #[test]
    fn an_explicitly_nulled_anchor_max_radius_is_read_as_raised_not_dropped() {
        let delta = parse(&one_value("navigation.anchor.maxRadius", "null"), None).expect("a delta");
        assert_eq!(delta.readings[0].measurement, Measurement::AnchorMaxRadius(None));
    }

    #[test]
    fn a_course_next_point_reads_the_position_nested_inside_it() {
        // Confirmed live against signalk-server's own Course API: the whole
        // NextPreviousPoint object arrives on one path
        // (navigation.course.nextPoint), position nested one level down
        // alongside href/type/name -- unlike navigation.anchor.position,
        // which is the bare coordinate object itself.
        let delta = parse(
            &one_value(
                "navigation.course.nextPoint",
                r#"{"type":"RoutePoint","position":{"latitude":45.55,"longitude":13.73}}"#,
            ),
            None,
        )
        .expect("a delta");
        assert_eq!(
            delta.readings[0].measurement,
            Measurement::CourseNextPoint(Some(Position::new(45.55, 13.73)))
        );
    }

    #[test]
    fn an_explicitly_nulled_course_next_point_is_read_as_not_following_not_dropped() {
        // The server sends exactly this the moment a route is cleared or
        // never set -- the one signal this crate has for "nothing is
        // currently being followed".
        let delta = parse(&one_value("navigation.course.nextPoint", "null"), None).expect("a delta");
        assert_eq!(delta.readings[0].measurement, Measurement::CourseNextPoint(None));
    }

    #[test]
    fn a_course_previous_point_reads_the_position_nested_inside_it() {
        // Confirmed live: the server reports the vessel's own position at
        // the moment following began, type "VesselPosition" -- a fixed
        // point, not a running "here I am now".
        let delta = parse(
            &one_value(
                "navigation.course.previousPoint",
                r#"{"type":"VesselPosition","position":{"latitude":45.79,"longitude":13.56}}"#,
            ),
            None,
        )
        .expect("a delta");
        assert_eq!(
            delta.readings[0].measurement,
            Measurement::CoursePreviousPoint(Some(Position::new(45.79, 13.56)))
        );
    }

    #[test]
    fn an_explicitly_nulled_course_previous_point_is_read_as_not_following_not_dropped() {
        let delta = parse(&one_value("navigation.course.previousPoint", "null"), None).expect("a delta");
        assert_eq!(delta.readings[0].measurement, Measurement::CoursePreviousPoint(None));
    }

    #[test]
    fn an_active_route_reads_the_href_out_of_the_whole_object() {
        // Confirmed live: the whole activeRoute object (href, name,
        // reverse, pointIndex, pointTotal) arrives as one delta here, not
        // nested the way nextPoint/previousPoint's own position is.
        let delta = parse(
            &one_value(
                "navigation.course.activeRoute",
                r#"{"href":"/resources/routes/b6ba1e44-169e-4324-b685-9ed2a38175f8","name":"Test","reverse":false,"pointIndex":0,"pointTotal":2}"#,
            ),
            None,
        )
        .expect("a delta");
        assert_eq!(
            delta.readings[0].measurement,
            Measurement::CourseActiveRouteHref(Some(
                "/resources/routes/b6ba1e44-169e-4324-b685-9ed2a38175f8".to_owned()
            ))
        );
    }

    #[test]
    fn an_explicitly_nulled_active_route_is_read_as_not_following_not_dropped() {
        let delta = parse(&one_value("navigation.course.activeRoute", "null"), None).expect("a delta");
        assert_eq!(delta.readings[0].measurement, Measurement::CourseActiveRouteHref(None));
    }

    #[test]
    fn a_resource_change_reads_the_type_and_id_out_of_the_path_itself() {
        // The server's own buildDeltaMsg sends the resource's whole new
        // value here too -- deliberately ignored, see
        // Measurement::ResourceChanged's own doc.
        let delta = parse(
            &one_value(
                "resources.tracks.94052456-65fa-48ce-a85d-41b78a9d2111",
                r#"{"name":"Passage to Piran"}"#,
            ),
            None,
        )
        .expect("a delta");
        assert_eq!(
            delta.readings[0].measurement,
            Measurement::ResourceChanged {
                resource_type: "tracks".to_owned(),
                id: "94052456-65fa-48ce-a85d-41b78a9d2111".to_owned(),
            }
        );
    }

    #[test]
    fn a_resource_deletion_is_read_the_same_way_a_change_is() {
        // The server's own convention for "this was deleted": the same
        // path, value null -- deliberately not distinguished from a
        // create/update here, see ResourceChanged's own doc for why a
        // caller reacts identically either way (asking again).
        let delta = parse(&one_value("resources.tracks.94052456-65fa-48ce-a85d-41b78a9d2111", "null"), None)
            .expect("a delta");
        assert_eq!(
            delta.readings[0].measurement,
            Measurement::ResourceChanged {
                resource_type: "tracks".to_owned(),
                id: "94052456-65fa-48ce-a85d-41b78a9d2111".to_owned(),
            }
        );
    }

    #[test]
    fn a_resources_path_with_nothing_after_the_type_is_not_a_resource_change() {
        assert!(resource_changed("resources.tracks").is_none());
        assert!(resource_changed("resources.tracks.").is_none());
    }

    #[test]
    fn a_position_off_the_earth_is_not_a_fix() {
        let delta = parse(
            &one_value(
                "navigation.position",
                r#"{"latitude":91.0,"longitude":13.0}"#,
            ),
            None,
        )
        .expect("a delta");
        assert!(delta.readings.is_empty(), "{:?}", delta.readings);
    }

    #[test]
    fn paths_this_crate_has_no_use_for_are_skipped_and_not_refused() {
        // A real server sends dozens of these. Failing on the first unknown
        // one would break every consumer the day the boat gains a sensor.
        let delta = parse(
            &one_value("electrical.batteries.house.voltage", "12.6"),
            None,
        )
        .expect("still a delta");
        assert!(delta.readings.is_empty());
    }

    #[test]
    fn which_vessel_a_delta_is_about_is_never_guessed() {
        // AIS targets arrive on the same socket as own ship. Reading one as
        // the other puts another boat's position under the own-ship symbol.
        let ais = parse(
            r#"{"context":"vessels.urn:mrn:imo:mmsi:238123456","updates":[
               {"$source":"ais.0","values":[
               {"path":"navigation.position","value":{"latitude":45.5,"longitude":13.6}}]}]}"#,
            Some("urn:mrn:signalk:uuid:self"),
        )
        .expect("a delta");
        assert!(!ais.is_self());
        assert_eq!(
            ais.context,
            Context::Other("vessels.urn:mrn:imo:mmsi:238123456".to_owned())
        );
    }

    #[test]
    fn own_ship_is_recognised_by_either_name_the_servers_use() {
        let shorthand =
            parse(&one_value("navigation.speedOverGround", "1.0"), None).expect("a delta");
        assert!(shorthand.is_self());

        let in_full = parse(
            r#"{"context":"vessels.urn:mrn:signalk:uuid:aaa","updates":[
               {"$source":"n2k.1","values":[
               {"path":"navigation.speedOverGround","value":1.0}]}]}"#,
            Some("urn:mrn:signalk:uuid:aaa"),
        )
        .expect("a delta");
        assert!(in_full.is_self());
    }

    #[test]
    fn the_source_label_survives_in_both_the_forms_servers_send_it() {
        let short = parse(&one_value("navigation.speedOverGround", "1.0"), None).expect("a delta");
        assert_eq!(short.readings[0].source, "n2k.1");

        let long = parse(
            r#"{"context":"vessels.self","updates":[
               {"source":{"label":"cockpit-gps","type":"NMEA0183"},"values":[
               {"path":"navigation.speedOverGround","value":1.0}]}]}"#,
            None,
        )
        .expect("a delta");
        assert_eq!(long.readings[0].source, "cockpit-gps");
    }

    #[test]
    fn a_reading_of_unknown_origin_is_labelled_rather_than_dropped() {
        let delta = parse(
            r#"{"context":"vessels.self","updates":[{"values":[
               {"path":"navigation.speedOverGround","value":1.0}]}]}"#,
            None,
        )
        .expect("a delta");
        assert_eq!(delta.readings[0].source, "unknown");
    }

    #[test]
    fn several_values_in_one_update_all_arrive() {
        let delta = parse(
            r#"{"context":"vessels.self","updates":[{"$source":"n2k.1","values":[
               {"path":"navigation.position","value":{"latitude":45.5,"longitude":13.6}},
               {"path":"navigation.speedOverGround","value":3.0},
               {"path":"environment.depth.belowKeel","value":4.2}]}]}"#,
            None,
        )
        .expect("a delta");
        assert_eq!(delta.readings.len(), 3);
    }

    #[test]
    fn an_active_polar_update_is_carried_apart_from_the_ordinary_readings() {
        let delta = parse(
            &one_value(
                "performance.activePolarData",
                r#"{"id":"x","name":"x","windData":[]}"#,
            ),
            None,
        )
        .expect("a delta");
        assert!(delta.readings.is_empty(), "not folded into an ordinary Measurement");
        assert_eq!(
            delta.active_polar,
            Some(serde_json::json!({"id": "x", "name": "x", "windData": []}))
        );
    }

    #[test]
    fn no_active_polar_update_leaves_it_none() {
        let delta = parse(&one_value("navigation.speedOverGround", "1.0"), None).expect("a delta");
        assert_eq!(delta.active_polar, None);
    }

    #[test]
    fn something_that_is_not_a_delta_is_not_read_as_an_empty_one() {
        // A subscription acknowledgement or a hello message must not look
        // like a delta that happened to carry nothing.
        assert!(parse("{\"name\":\"signalk-server\",\"version\":\"2.0\"}", None).is_none());
        assert!(parse("not json", None).is_none());
    }

    #[test]
    fn a_sounding_keeps_the_reference_it_arrived_with() {
        // The common case on a boat with older sounders: NMEA `DBT` has no
        // offset field, so the server can only ever say belowTransducer.
        let delta = parse(
            &one_value("environment.depth.belowTransducer", "10.44"),
            None,
        )
        .expect("a delta");
        assert_eq!(
            delta.readings[0].measurement,
            Measurement::Depth(Depth {
                metres: 10.44,
                reference: Sounding::BelowTransducer,
            })
        );
    }

    #[test]
    fn transducer_depth_does_not_become_keel_depth_without_the_geometry() {
        // The whole point. Nothing is known about where the transducer sits,
        // so there is no answer -- rather than the answer "10.44 m under the
        // keel", which would be over-reporting the water by the length of an
        // unstated offset.
        let sounding = Depth {
            metres: 10.44,
            reference: Sounding::BelowTransducer,
        };
        assert!(
            sounding
                .to(Sounding::BelowKeel, Offsets::default())
                .is_none()
        );
    }

    #[test]
    fn a_stated_offset_is_applied_once_and_in_the_safe_direction() {
        // 0.8 m from the transducer down to the keel: less water under the
        // keel than under the transducer, never more.
        let offsets = Offsets {
            transducer_to_keel: Some(0.8),
            surface_to_transducer: Some(0.4),
        };
        let sounding = Depth {
            metres: 10.44,
            reference: Sounding::BelowTransducer,
        };

        let keel = sounding.to(Sounding::BelowKeel, offsets).expect("geometry");
        assert!((keel.metres - 9.64).abs() < 1e-9);
        assert_eq!(keel.reference, Sounding::BelowKeel);

        // And from the surface there is more water than the instrument saw,
        // by however deep the transducer is.
        let surface = sounding
            .to(Sounding::BelowSurface, offsets)
            .expect("geometry");
        assert!((surface.metres - 10.84).abs() < 1e-9);
    }

    #[test]
    fn converting_back_and_forth_does_not_apply_the_offset_twice() {
        // Applying it twice is the classic installation fault -- the sounder
        // already corrected and the display corrects again. Round-tripping
        // has to land back on the measured number.
        let offsets = Offsets {
            transducer_to_keel: Some(0.8),
            surface_to_transducer: Some(0.4),
        };
        let measured = Depth {
            metres: 10.44,
            reference: Sounding::BelowTransducer,
        };
        let there_and_back = measured
            .to(Sounding::BelowKeel, offsets)
            .expect("geometry")
            .to(Sounding::BelowTransducer, offsets)
            .expect("geometry");
        assert!((there_and_back.metres - measured.metres).abs() < 1e-9);
    }

    #[test]
    fn a_keel_already_in_the_bottom_is_reported_rather_than_hidden() {
        // Clamping this to zero would turn "you are aground" into "you have
        // no water", which reads like a sensor fault instead of a fact.
        let offsets = Offsets {
            transducer_to_keel: Some(0.8),
            surface_to_transducer: None,
        };
        let keel = Depth {
            metres: 0.5,
            reference: Sounding::BelowTransducer,
        }
        .to(Sounding::BelowKeel, offsets)
        .expect("geometry");
        assert!(keel.metres < 0.0);
    }

    #[test]
    fn the_sounder_geometry_is_read_off_the_wire_too() {
        // A server that has been told the installation sends it, and then
        // nothing has to be configured twice.
        let delta = parse(
            &one_value("environment.depth.transducerToKeel", "0.8"),
            None,
        )
        .expect("a delta");
        assert_eq!(
            delta.readings[0].measurement,
            Measurement::TransducerToKeel(0.8)
        );
    }

    #[test]
    fn the_vessels_maximum_draft_is_read_off_the_wire() {
        // Captured verbatim from a real server's answer to `PUT
        // /skserver/vessel`: an object, not a bare number, and only
        // `maximum` populated -- current, minimum and canoe are all in the
        // schema and none of them ever arrive in practice.
        let delta = parse(&one_value("design.draft", r#"{"maximum":2}"#), None)
            .expect("a delta");
        assert_eq!(delta.readings[0].measurement, Measurement::MaximumDraft(2.0));
    }

    #[test]
    fn the_vessels_length_overall_is_read_off_the_wire() {
        let delta = parse(&one_value("design.length", r#"{"overall":10.5,"hull":10.2}"#), None)
            .expect("a delta");
        assert_eq!(delta.readings[0].measurement, Measurement::DesignLength(10.5));
    }

    #[test]
    fn a_length_object_with_no_overall_is_not_a_measurement() {
        let delta = parse(&one_value("design.length", r#"{"hull":10.2}"#), None).expect("a delta");
        assert!(delta.readings.is_empty());
    }

    #[test]
    fn the_vessels_beam_is_read_off_the_wire() {
        // A bare number, unlike design.draft/design.length -- the schema
        // gives beam no sibling fields at all.
        let delta = parse(&one_value("design.beam", "3.6"), None).expect("a delta");
        assert_eq!(delta.readings[0].measurement, Measurement::DesignBeam(3.6));
    }

    #[test]
    fn an_ais_targets_class_type_and_call_sign_are_read() {
        let delta = parse(
            r#"{"context":"vessels.urn:mrn:imo:mmsi:247111000","updates":[
               {"$source":"ais.0","values":[
               {"path":"sensors.ais.class","value":"B"},
               {"path":"design.aisShipType","value":{"id":70,"name":"Cargo ship"}},
               {"path":"communication.callsignVhf","value":"IABC"},
               {"path":"sensors.ais.class","value":"C"}]}]}"#,
            None,
        )
        .expect("a delta");
        let readings: Vec<_> = delta.readings.into_iter().map(|r| r.measurement).collect();
        assert_eq!(
            readings,
            [
                Measurement::AisClass(AisClass::B),
                Measurement::AisShipType("Cargo ship".to_owned()),
                Measurement::Callsign("IABC".to_owned()),
            ],
            "an unknown class is skipped, not an error"
        );
    }

    #[test]
    fn closest_approach_figures_are_read_and_may_both_be_absent() {
        // As the prioritizer publishes it: figures only when there is an
        // approach, the object still there when there is not.
        let approaching = parse(
            r#"{"context":"vessels.urn:mrn:imo:mmsi:1","updates":[{"$source":"p","values":[
               {"path":"navigation.closestApproach","value":
                {"distance":370.4,"timeTo":600,"range":2000,"bearing":90,
                 "collisionAlarmType":null,"collisionAlarmState":null}}]}]}"#,
            None,
        )
        .expect("a delta");
        assert_eq!(
            approaching.readings[0].measurement,
            Measurement::ClosestApproach { cpa_m: Some(370.4), tcpa_s: Some(600.0) }
        );

        let receding = parse(
            r#"{"context":"vessels.urn:mrn:imo:mmsi:1","updates":[{"$source":"p","values":[
               {"path":"navigation.closestApproach","value":{"range":2000,"bearing":90}}]}]}"#,
            None,
        )
        .expect("a delta");
        assert_eq!(
            receding.readings[0].measurement,
            Measurement::ClosestApproach { cpa_m: None, tcpa_s: None }
        );
    }

    #[test]
    fn an_ais_targets_name_is_read_off_a_vessel_root_update() {
        // Exactly as signalk-server sends it for an AIS static-data
        // message: empty path, object value. The MMSI arrives the same
        // way, in an update of its own, and is not a name.
        let named = parse(
            r#"{"context":"vessels.urn:mrn:imo:mmsi:247111000","updates":[
               {"$source":"ais-faker.AI","values":[
               {"path":"","value":{"name":"MSC AURORA"}}]}]}"#,
            Some("urn:mrn:signalk:uuid:self"),
        )
        .expect("a delta");
        assert_eq!(named.readings[0].measurement, Measurement::VesselName("MSC AURORA".to_owned()));

        let mmsi_only = parse(
            r#"{"context":"vessels.urn:mrn:imo:mmsi:247111000","updates":[
               {"$source":"ais-faker.AI","values":[
               {"path":"","value":{"mmsi":"247111000"}}]}]}"#,
            Some("urn:mrn:signalk:uuid:self"),
        )
        .expect("a delta");
        assert!(mmsi_only.readings.is_empty());
    }

    #[test]
    fn an_ais_targets_call_sign_is_read_off_a_vessel_root_update_too() {
        // Confirmed live against a real signalk-server decoding an
        // `!AIVDM` type 5 message: the call sign arrives nested under the
        // same empty-path vessel-root update as the name, in its own
        // fragment -- `{"communication":{"callsignVhf":"IBQY"}}`, not the
        // flat `communication.callsignVhf` path a plugin or a data-model
        // write would use (see the test below this one). Getting this
        // wrong the first time -- modelling only the flat path, never
        // checked against a live decode -- was exactly the mistake this
        // module's own name handling had already been caught making once.
        let delta = parse(
            r#"{"context":"vessels.urn:mrn:imo:mmsi:247111000","updates":[
               {"$source":"ais-faker.AI","values":[
               {"path":"","value":{"communication":{"callsignVhf":"IBQY"}}}]}]}"#,
            Some("urn:mrn:signalk:uuid:self"),
        )
        .expect("a delta");
        assert_eq!(delta.readings[0].measurement, Measurement::Callsign("IBQY".to_owned()));
    }

    #[test]
    fn a_vessels_name_is_read_off_the_wire_on_any_context() {
        // Same bare `name` path Self and an AIS target both carry --
        // measurement_of does not know or care which context a delta is
        // for, only the caller does.
        let delta = parse(
            r#"{"context":"vessels.urn:mrn:imo:mmsi:238123456","updates":[
               {"$source":"ais.0","values":[
               {"path":"name","value":"Windward"}]}]}"#,
            Some("urn:mrn:signalk:uuid:self"),
        )
        .expect("a delta");
        assert_eq!(delta.readings[0].measurement, Measurement::VesselName("Windward".to_owned()));
    }

    #[test]
    fn an_ais_targets_tracking_status_is_read_off_the_wire() {
        // sk-ais-status-plugin's own path, confirmed live -- not a Signal
        // K specification path.
        let delta = parse(
            r#"{"context":"vessels.urn:mrn:imo:mmsi:238123456","updates":[
               {"$source":"sk-ais-status","values":[
               {"path":"sensors.ais.status","value":"confirmed"}]}]}"#,
            Some("urn:mrn:signalk:uuid:self"),
        )
        .expect("a delta");
        assert_eq!(
            delta.readings[0].measurement,
            Measurement::AisTargetStatus(AisTargetStatus::Confirmed)
        );
    }

    #[test]
    fn an_unrecognised_ais_status_value_is_not_a_measurement() {
        // The plugin only ever sends four values today; a fifth some
        // future version might add must be skipped, not guessed at.
        let delta = parse(
            r#"{"context":"vessels.urn:mrn:imo:mmsi:238123456","updates":[
               {"$source":"sk-ais-status","values":[
               {"path":"sensors.ais.status","value":"suspicious"}]}]}"#,
            Some("urn:mrn:signalk:uuid:self"),
        )
        .expect("a delta");
        assert!(delta.readings.is_empty());
    }

    #[test]
    fn a_closest_approach_alarms_severity_is_read_off_the_wire() {
        // signalk-ais-target-prioritizer's own path, confirmed live --
        // not a Signal K specification path (notifications.collision.*
        // is the schema's own name for this).
        let delta = parse(
            r#"{"context":"vessels.urn:mrn:imo:mmsi:238123456","updates":[
               {"$source":"signalk-ais-target-prioritizer","values":[
               {"path":"notifications.navigation.closestApproach","value":
               {"state":"alarm","method":["visual","sound"],"message":"CPA ALARM"}}]}]}"#,
            Some("urn:mrn:signalk:uuid:self"),
        )
        .expect("a delta");
        assert_eq!(
            delta.readings[0].measurement,
            Measurement::ClosestApproachAlarm(NotificationSeverity::Alarm)
        );
    }

    #[test]
    fn an_unrecognised_closest_approach_severity_is_not_a_measurement() {
        let delta = parse(
            r#"{"context":"vessels.urn:mrn:imo:mmsi:238123456","updates":[
               {"$source":"signalk-ais-target-prioritizer","values":[
               {"path":"notifications.navigation.closestApproach","value":
               {"state":"nominal"}}]}]}"#,
            Some("urn:mrn:signalk:uuid:self"),
        )
        .expect("a delta");
        assert!(delta.readings.is_empty());
    }

    #[test]
    fn notification_severity_orders_least_to_most_severe() {
        assert!(NotificationSeverity::Normal < NotificationSeverity::Alert);
        assert!(NotificationSeverity::Alert < NotificationSeverity::Warn);
        assert!(NotificationSeverity::Warn < NotificationSeverity::Alarm);
        assert!(NotificationSeverity::Alarm < NotificationSeverity::Emergency);
    }

    #[test]
    fn apparent_wind_angle_keeps_its_own_sign_convention() {
        // Signal K already states "negative to port" for this path -- the
        // same convention nav_math::wind::Wind uses, so this is a unit
        // conversion only, never a sign flip. A quarter turn to port on
        // the wire must come out negative, not wrapped into 0..360 the way
        // directionTrue is.
        let delta = parse(&one_value("environment.wind.angleApparent", "-1.0471975512"), None)
            .expect("a delta");
        let Measurement::WindAngleApparent(deg) = delta.readings[0].measurement else {
            panic!("not an apparent wind angle: {:?}", delta.readings[0]);
        };
        assert!((deg - -60.0).abs() < 1e-6, "got {deg}");
    }

    #[test]
    fn apparent_wind_speed_arrives_in_metres_per_second_and_is_read_in_knots() {
        let delta = parse(&one_value("environment.wind.speedApparent", "5.144444"), None)
            .expect("a delta");
        let Measurement::WindSpeedApparent(knots) = delta.readings[0].measurement else {
            panic!("not an apparent wind speed");
        };
        assert!((knots - 10.0).abs() < 1e-4, "got {knots}");
    }

    #[test]
    fn true_wind_direction_is_an_absolute_bearing_not_a_relative_angle() {
        // Unlike angleApparent, this is a compass direction -- it wraps
        // into 0..360, the same convention every other bearing in this
        // workspace uses, not -180..180.
        let delta = parse(&one_value("environment.wind.directionTrue", "-0.1745329"), None)
            .expect("a delta");
        let Measurement::WindDirectionTrue(deg) = delta.readings[0].measurement else {
            panic!("not a true wind direction");
        };
        assert!((deg - 350.0).abs() < 1e-4, "got {deg}");
    }

    #[test]
    fn true_wind_speed_arrives_in_metres_per_second_and_is_read_in_knots() {
        let delta =
            parse(&one_value("environment.wind.speedTrue", "5.144444"), None).expect("a delta");
        let Measurement::WindSpeedTrue(knots) = delta.readings[0].measurement else {
            panic!("not a true wind speed");
        };
        assert!((knots - 10.0).abs() < 1e-4, "got {knots}");
    }

    #[test]
    fn a_draft_object_with_no_maximum_is_not_a_measurement() {
        // Only minimum/current/canoe set, or an empty object: none of them
        // answer "how deep does this vessel sit at its worst", so none of
        // them should be read as if they did. Unrecognised, not an error --
        // the delta still parses, it just carries no readings.
        let with_current = parse(&one_value("design.draft", r#"{"current":1.5}"#), None)
            .expect("a delta");
        assert!(with_current.readings.is_empty());

        let empty = parse(&one_value("design.draft", "{}"), None).expect("a delta");
        assert!(empty.readings.is_empty());
    }
}