@meri-imperiumi/signalk-dead-reckoning 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -5,6 +5,68 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2026-08-27
+
+### Fixed
+- **Dockside false positives while moored/anchored** — three alerts
+  that misfire on a tied-up boat are now suppressed in the moored/
+  anchored regime (consistent with the divergence monitor's existing
+  §7.1–2 suppression):
+  - *Divergence advisory* no longer raises on GPS wander at the dock:
+    the uncertainty radius previously collapsed to exactly 0.0 nm at
+    zero distance run, so a few metres of marina multipath "exceeded
+    expected uncertainty × 1.5" and sustained for 30 s raised
+    `DR-GPS divergence 0.00 nm exceeds expected 0.00 nm`. The radius
+    now floors at `MIN_RADIUS_NM` (0.02 nm ≈ 37 m, GNSS noise scale)
+    — DR error can never honestly be smaller than the GPS it was
+    seeded from.
+  - *Phantom "paddlewheel fouled" alert* — the fouling detector saw
+    STW≈0 (a moored paddlewheel's honest reading) plus wind on the
+    mast or GPS jitter and concluded the boat was making way. The
+    detector (and the whole training/matrix path, incl. auto tack
+    logging) is skipped while moored/anchored, and any earlier verdict
+    is withdrawn.
+  - *Sticky advisories* — a divergence advisory raised just before
+    mooring could never clear (the monitor isn't fed while suppressed).
+    It is now withdrawn with a `DR monitoring suspended while
+    moored/anchored` notification, and the divergence readout publishes
+    an explicit `null` while suppressed so the UI drops the stale
+    figure instead of showing a frozen `0.00 nm / 306°`.
+- **Sensor-health alerts no longer flap** — the fouling and
+  idle-but-making-way verdicts are raw per-tick threshold comparisons
+  (STW vs 0.3 kn, wind vs 3 kn, SOG vs 1 kn); a sensor hovering at a
+  threshold toggled the alert on and off every tick. Both now pass
+  through a reusable symmetric hysteresis
+  (`plugin/hysteresis.js`, `sensorHealth.sustainS`/`clearS`, default
+  10 s/10 s): a real fault still surfaces after the sustain window,
+  threshold hover raises nothing.
+- **Water-track log survives restart** — `navigation.deadReckoning.log`
+  and the trip log were persisted every flush but never restored at
+  start, resetting the headline to 0.00 nm on every server restart
+  mid-passage. Both are now restored from the `dr_state_store`.
+- **Map layers control usable again** — the divergence chip overlay sat
+  at the top-right corner on top of Leaflet's layers control (equal
+  z-index, later sibling wins), covering its toggle: broken-looking
+  styling and swallowed clicks meant selecting a chart provider did
+  nothing. The chip now lives at the bottom-right (attribution is off,
+  so the corner is free).
+- The DR vs GPS headline no longer shows a bearing below display
+  resolution (`0.00 nm / 306°` → `0.00 nm`): the bearing of a
+  zero-length noise vector is meaningless.
+
+### Changed
+- When the server has no charts configured, the online OpenStreetMap
+  fallback layer is offered in the layers control but no longer
+  auto-added to the map (it was documented as opt-in; the tile-less
+  offline-first plot is the default again until selected).
+
+### Added
+- `plugin/hysteresis.js` — generic symmetric sustain/clear debounce for
+  boolean conditions, extracted from the divergence advisory's shape
+  and unit-tested; also used for the sensor-health alerts.
+- Work doc #17 on the rngit board tracks this batch (dockside false
+  positives: divergence advisory, fouled paddlewheel, layers control).
+
 ## [0.1.0] - 2026-08-27
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meri-imperiumi/signalk-dead-reckoning",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Offline-first dead reckoning and sensor fusion engine for Signal K",
   "main": "plugin/index.js",
   "scripts": {

package/plugin/hysteresis.js

@@ -0,0 +1,82 @@
+/**
+ * Generic symmetric hysteresis for a boolean condition (sustained raise,
+ * sustained clear), extracted from the divergence advisory monitor's
+ * debounce shape so other watchkeeper alerts (§6.3 paddlewheel fouling,
+ * idle-but-making-way) can't flap when a sensor hovers at a threshold.
+ *
+ * The condition must persist for `sustainS` before the debounced flag
+ * goes true, and stay false for `clearS` before it drops — a single
+ * jittery tick neither raises nor clears.
+ *
+ * Pure logic over an explicit state object — unit-testable without
+ * Signal K plumbing.
+ *
+ * @file hysteresis.js
+ */
+
+/**
+ * Default windows (seconds) for sensor-health style flags. Slower than
+ * the divergence advisory's 30 s — fouling and idle transitions are
+ * mechanical conditions that don't change meaningfully in a second, but
+ * fast enough that a real fault surfaces within a watch check.
+ */
+const DEFAULT_SUSTAIN_S = 10;
+const DEFAULT_CLEAR_S = 10;
+
+/**
+ * Creates a fresh debounce state.
+ *
+ * @returns {{active: boolean, exceedS: number, insideS: number}}
+ */
+function createFlagState() {
+  return {
+    /** debounced flag currently raised */
+    active: false,
+    /** sustained seconds of the raw condition accumulated */
+    exceedS: 0,
+    /** sustained seconds of the raw condition being absent */
+    insideS: 0,
+  };
+}
+
+/**
+ * Advances the debounce one tick.
+ *
+ * @param {object} state - from createFlagState(), mutated
+ * @param {boolean} raw - the undebounced per-tick condition
+ * @param {number} dtS - tick interval in seconds
+ * @param {object} [opts]
+ * @param {number} [opts.sustainS=DEFAULT_SUSTAIN_S]
+ * @param {number} [opts.clearS=DEFAULT_CLEAR_S]
+ * @returns {{active: boolean, transition: "raise"|"clear"|null}}
+ */
+function flagTick(state, raw, dtS, opts = {}) {
+  const sustainS = opts.sustainS ?? DEFAULT_SUSTAIN_S;
+  const clearS = opts.clearS ?? DEFAULT_CLEAR_S;
+  let transition = null;
+
+  if (raw) {
+    state.insideS = 0;
+    state.exceedS += dtS;
+    if (!state.active && state.exceedS >= sustainS) {
+      state.active = true;
+      transition = "raise";
+    }
+  } else {
+    state.exceedS = 0;
+    state.insideS += dtS;
+    if (state.active && state.insideS >= clearS) {
+      state.active = false;
+      transition = "clear";
+    }
+  }
+
+  return { active: state.active, transition };
+}
+
+module.exports = {
+  DEFAULT_SUSTAIN_S,
+  DEFAULT_CLEAR_S,
+  createFlagState,
+  flagTick,
+};

package/plugin/index.js

@@ -70,6 +70,7 @@ const {
   createDivergenceState,
   divergenceTick,
 } = require("./divergence.js");
+const { createFlagState, flagTick } = require("./hysteresis.js");
 const {
   composeFixEntry,
   composeTackEntry,
@@ -220,6 +221,17 @@ const DEFAULT_CONFIG = {
     sustainS: DEFAULT_SUSTAIN_S,
     clearS: DEFAULT_CLEAR_S,
   },
+  /**
+   * Sensor-health alert hysteresis (§6.3 fouling, idle-moving): the raw
+   * per-tick verdicts compare live sensors against fixed thresholds, so
+   * a gust or GPS wander hovering at a threshold would flap the alert
+   * on every tick. Both windows are symmetric — a real fault surfaces
+   * after sustainS, withdraws after clearS.
+   */
+  sensorHealth: {
+    sustainS: 10,
+    clearS: 10,
+  },
   logbook: {
     enabled: false,
     url: "http://localhost:3000/plugins/signalk-logbook/logs",
@@ -257,6 +269,8 @@ const deps = {
   computeRadius,
   createDivergenceState,
   divergenceTick,
+  createFlagState,
+  flagTick,
   composeFixEntry,
   composeTackEntry,
   composeObservationEntry,
@@ -383,6 +397,17 @@ module.exports = (app) => {
   /** @type {ReturnType<typeof createDivergenceState>|null} §7.3 divergence monitor */
   let divergence = null;
 
+  /**
+   * §6.3 sensor-health alert hysteresis: raw fouling / idle-moving
+   * verdicts debounce through these so threshold-hovering sensors
+   * can't flap notifications on every tick.
+   * @type {ReturnType<typeof createFlagState>|null}
+   */
+  let fouledFlag = null;
+
+  /** @type {ReturnType<typeof createFlagState>|null} */
+  let movingFlag = null;
+
   /** @type {object|null} §9.5 logbook write-through client */
   let logbook = null;
 
@@ -476,6 +501,10 @@ module.exports = (app) => {
         ...DEFAULT_CONFIG.divergence,
         ...(options?.divergence ?? {}),
       };
+      config.sensorHealth = {
+        ...DEFAULT_CONFIG.sensorHealth,
+        ...(options?.sensorHealth ?? {}),
+      };
       config.logbook = {
         ...DEFAULT_CONFIG.logbook,
         ...(options?.logbook ?? {}),
@@ -492,7 +521,15 @@ module.exports = (app) => {
       dbPath = join(app.getDataDirPath(), "dead-reckoning.sqlite");
       db = deps.openDatabase(dbPath);
       matrix = new deps.MatrixStore(db);
-      engine = new deps.DeadReckoningEngine();
+      // Restart survival: the cumulative water-track logs are persisted
+      // every flush — restore them so the headline log doesn't reset to
+      // 0.00 on every server restart mid-passage.
+      const savedLogNm = Number(deps.getState(db, "dr_log_nm"));
+      const savedTripNm = Number(deps.getState(db, "dr_trip_log_nm"));
+      engine = new deps.DeadReckoningEngine({
+        logNm: Number.isFinite(savedLogNm) ? savedLogNm : 0,
+        tripLogNm: Number.isFinite(savedTripNm) ? savedTripNm : 0,
+      });
       groundTrack = new deps.GroundTrack({
         capacity: Math.max(
           60,
@@ -541,6 +578,8 @@ module.exports = (app) => {
         settleSustainS: config.training.settleSustainS,
       });
       divergence = deps.createDivergenceState();
+      fouledFlag = deps.createFlagState();
+      movingFlag = deps.createFlagState();
       clockS = 0;
 
       // Seed the engine origin from the last known good position, if any.
@@ -663,6 +702,8 @@ module.exports = (app) => {
         });
       }
       divergence = null;
+      fouledFlag = null;
+      movingFlag = null;
       if (sensorHealthIssue) {
         publishNotification(PATHS.sensorHealth, {
           state: "normal",
@@ -784,6 +825,12 @@ module.exports = (app) => {
     const aws = unwrapNumber(deltaState.get("environment.wind.speedApparent"));
     const heel = unwrapHeel(deltaState.get("navigation.attitude"));
     const gps = unwrapPosition(deltaState.get("navigation.position"));
+    // One underway verdict for the whole tick (§7.1–2: moored/anchored is
+    // a different regime — divergence advisories, fouling suspicion and
+    // training are all suppressed there). Unknown state is treated as
+    // underway: not every install runs an autostate source.
+    const navState = deltaState.get("navigation.state");
+    const underway = navState !== "anchored" && navState !== "moored";
 
     // GPS-derived motion (independent of the water-track sensors):
     // updated every tick, used to detect "idle but making way" below.
@@ -801,7 +848,6 @@ module.exports = (app) => {
       // Publish why DR is idle so the UI (SPEC §14.1) can explain the empty
       // readout instead of leaving the user to guess. The vessel isn't
       // necessarily broken — moored/anchored with no STW/heading is normal.
-      const navState = deltaState.get("navigation.state");
       let reason;
       if (navState === "moored" || navState === "anchored") {
         reason = navState;
@@ -819,12 +865,25 @@ module.exports = (app) => {
       // polygon must keep growing — by the ground distance travelled with
       // no water track — or it falsely advertises confidence. GPS stays
       // authoritative until proven faulty or OVERRIDE (§7), so the
-      // watchkeeper is alerted, not left guessing.
-      const moving =
-        gpsMotion.speedKn != null && gpsMotion.speedKn > SOG_MOVING_KN;
+      // watchkeeper is alerted, not left guessing. Moored/anchored is the
+      // honest-stopped regime — dockside GPS wander is not "making way".
+      // The alert itself is debounced (config.sensorHealth): GPS wander
+      // hovering at the threshold must not flap it on and off.
+      const movingRaw =
+        underway &&
+        gpsMotion.speedKn != null &&
+        gpsMotion.speedKn > SOG_MOVING_KN;
+      const moving = deps.flagTick(
+        movingFlag,
+        movingRaw,
+        config.tickIntervalMs / 1000,
+        config.sensorHealth,
+      ).active;
+      if (movingRaw) {
+        idleRunNm += (gpsMotion.speedKn * config.tickIntervalMs) / 3600000;
+      }
       let uncertaintyValue = null;
       if (moving) {
-        idleRunNm += (gpsMotion.speedKn * config.tickIntervalMs) / 3600000;
         const u = deps.computeRadius({
           elapsedDistanceNm: engine.logNmSinceOrigin + idleRunNm,
           effectiveHitCount: 0, // unknown bin while idle — fallback growth
@@ -900,40 +959,57 @@ module.exports = (app) => {
     // When GPS is reliable and we're sailing (not motoring, paddlewheel
     // not fouled, not in a tack/gybe transient), compute the error vector
     // vs. GPS ground truth and EMA-merge it into the matching bin.
-    const tr = deps.trainingTick(training, {
-      timestampS: clockS,
-      gps,
-      stwKn: rawStw,
-      headingTrueDeg,
-      awaDeg,
-      awsKn: aws,
-      heelDeg: heel ?? 0,
-      propulsionState: deltaState.get("propulsion.main.state"),
-      current,
-      lookupLeewayDeg: corrections.leeway_angle,
-      lookupSpeedLoss: corrections.speed_loss,
-    });
-    if (tr.observation) {
-      matrix.update(
-        {
-          sail_state: sailState,
-          sea_state: seaState,
-          stwKn: rawStw,
-          awaDeg,
-          heelDeg: heel ?? 0,
-        },
-        tr.observation,
-        { source: "live" },
-      );
+    // Moored/anchored is excluded entirely (§7.1–2 different regime):
+    // a tied-up boat has STW≈0 by design while wind blows on the mast
+    // and GPS wanders at the dock — running the trainer there would
+    // flag a phantom fouled paddlewheel, write GPS-jitter observations
+    // into the matrix, and log mooring-yaw wind shifts as fake tacks.
+    let tr = { transient: false, fouled: false };
+    if (underway) {
+      tr = deps.trainingTick(training, {
+        timestampS: clockS,
+        gps,
+        stwKn: rawStw,
+        headingTrueDeg,
+        awaDeg,
+        awsKn: aws,
+        heelDeg: heel ?? 0,
+        propulsionState: deltaState.get("propulsion.main.state"),
+        current,
+        lookupLeewayDeg: corrections.leeway_angle,
+        lookupSpeedLoss: corrections.speed_loss,
+      });
+      if (tr.observation) {
+        matrix.update(
+          {
+            sail_state: sailState,
+            sea_state: seaState,
+            stwKn: rawStw,
+            awaDeg,
+            heelDeg: heel ?? 0,
+          },
+          tr.observation,
+          { source: "live" },
+        );
+      }
     }
 
     // §6.3: the fouling detector's verdict (STW≈0 while SOG/wind say
     // the boat moves) is surfaced, not just used to gate training — a
     // fouled paddlewheel silently integrating 0 speed is the classic
-    // way DR freezes while the vessel sails on.
+    // way DR freezes while the vessel sails on. While moored/anchored
+    // the detector doesn't run, so any earlier verdict is withdrawn.
+    // Debounced through config.sensorHealth: a paddlewheel or gust
+    // hovering at a threshold must not flap the alert on and off.
+    const fouled = deps.flagTick(
+      fouledFlag,
+      Boolean(tr.fouled),
+      config.tickIntervalMs / 1000,
+      config.sensorHealth,
+    ).active;
     setSensorHealth(
-      tr.fouled ? "fouled" : null,
-      tr.fouled
+      fouled ? "fouled" : null,
+      fouled
         ? "Paddlewheel appears fouled — STW≈0 while the vessel makes way. DR is integrating near-zero speed; verify position by other means"
         : null,
     );
@@ -942,10 +1018,12 @@ module.exports = (app) => {
     // edge is a completed maneuver; classify from the AWA change across
     // the window. Debounced so a beat's rapid back-to-back maneuvers
     // (or a botched tack immediately redone) log as one event.
-    const maneuver = deps.detectManeuver(training, {
-      awaDeg,
-      headingDeg: headingTrueDeg,
-    });
+    const maneuver = underway
+      ? deps.detectManeuver(training, {
+          awaDeg,
+          headingDeg: headingTrueDeg,
+        })
+      : null;
     if (maneuver) {
       const now = Date.now();
       const debounceMs = (config.logbook?.tackDebounceS ?? 120) * 1000;
@@ -984,9 +1062,11 @@ module.exports = (app) => {
       // expected growth (§8), with sustained-interval hysteresis so a
       // single jittery fix neither raises nor flaps the advisory.
       // §14.1's live divergence readout (distance + bearing) is published
-      // alongside. Suppressed at anchor/moored (different regime, §7.1–2).
-      const navState = deltaState.get("navigation.state");
-      const underway = navState !== "anchored" && navState !== "moored";
+      // alongside. Suppressed at anchor/moored (different regime, §7.1–2):
+      // while suppressed the monitor is not fed, an advisory raised just
+      // before the transition is withdrawn (it can never clear on its own
+      // otherwise), and the readout is nulled so the UI doesn't show a
+      // stale figure from the last underway tick.
       let dvg = null;
       if (gps && underway) {
         const distNm = deps.distanceNm(pos, gps);
@@ -1012,6 +1092,12 @@ module.exports = (app) => {
             message: `DR-GPS divergence back within expected uncertainty (${d.divergenceNm.toFixed(2)} nm)`,
           });
         }
+      } else if (divergence.active) {
+        divergence = deps.createDivergenceState();
+        publishNotification(PATHS.divergenceAdvisory, {
+          state: "normal",
+          message: "DR monitoring suspended while moored/anchored",
+        });
       }
 
       publish({
@@ -1033,10 +1119,12 @@ module.exports = (app) => {
         [PATHS.state]: {
           status: "underway",
           transient: tr.transient,
-          fouled: tr.fouled,
+          fouled,
         },
         [PATHS.elapsedSinceFix]: engine.elapsedSinceOriginS,
-        ...(dvg ? { [PATHS.divergence]: dvg } : {}),
+        // Always published: null while suppressed (moored/anchored or no
+        // GPS) so consumers drop any stale underway figure.
+        [PATHS.divergence]: dvg,
       });
     }
   }

package/plugin/uncertainty.js

@@ -33,6 +33,16 @@
  * @file uncertainty.js
  */
 
+/**
+ * Minimum published radius (nm) ≈ 37 m: GNSS position noise at the
+ * dock. With zero distance run the model would otherwise report a
+ * point-exact DR position (radius 0), and any GPS wander — however
+ * small — then "exceeds expected uncertainty", firing the divergence
+ * advisory on a moored boat. DR error can never honestly be smaller
+ * than the GPS it was seeded from.
+ */
+const MIN_RADIUS_NM = 0.02;
+
 /**
  * Conservative angular-error margin (degrees of DR error per nautical
  * mile run) used by the fallback regime. ~1° over a mile is a deliberately
@@ -166,7 +176,7 @@ function computeRadius(input) {
 
   const w = blendWeight(hits);
   const rate = w * empiricalRate + (1 - w) * fallbackRate;
-  const radius_nm = rate * elapsed;
+  const radius_nm = Math.max(rate * elapsed, MIN_RADIUS_NM);
 
   let method;
   if (w <= 0) method = "fallback";
@@ -185,6 +195,7 @@ function computeRadius(input) {
 
 module.exports = {
   FALLBACK_DEG_PER_NM,
+  MIN_RADIUS_NM,
   MIN_HITS_FOR_EMPIRICAL,
   EWMA_N,
   EWMA_ALPHA,

package/public/dr-map-view.js

@@ -41,10 +41,15 @@ class DrMapView extends HTMLElement {
       .map-host { position: relative; width: 100%; height: 100%; }
       .map-wrap { width: 100%; height: 100%; background: var(--bg-base, #080a0c); }
       /* Floating overlays: semi-transparent dark panels with sharp 1px
-         borders so they stay legible over any tileset (UI spec §7). */
+         borders so they stay legible over any tileset (UI spec §7).
+         Bottom-right: the top-right corner belongs to Leaflet's layers
+         control — stacking the chip there covered the control's toggle
+         (same z-index, later sibling wins), which both looked broken and
+         swallowed the clicks that were meant to switch chart providers.
+         The bottom-right corner is free here: attribution is off. */
       .dr-chip {
         position: absolute;
-        top: 8px;
+        bottom: 8px;
         right: 8px;
         z-index: 1000;
         display: flex;
@@ -216,17 +221,19 @@ class DrMapView extends HTMLElement {
     );
 
     // Basemap: Signal K configured charts (offline MBTiles / tile proxies)
-    // when available, falling back to online OSM when the server has none
-    // configured (route 404s or returns empty). The first available layer
-    // is added to the map so the plot has context immediately; the rest
-    // are registered in the layers control for switching.
+    // when available. The first *configured* chart is added to the map so
+    // the plot has context immediately; the rest are registered in the
+    // layers control for switching. When the server has no charts the
+    // online OSM fallback is offered in the control but NEVER auto-added
+    // (offline-first: the DR plot stays tile-less until the watchkeeper
+    // opts in — vm.DEFAULT_OSM_LAYER's documented contract).
     fetch("/signalk/v1/api/resources/charts")
       .then((r) => (r.ok ? r.json() : null))
       .then((resource) => {
-        const charts = vm.chartLayersWithFallback(resource);
-        if (charts.length === 0) return;
+        const configured = vm.parseChartLayers(resource);
+        const charts =
+          configured.length > 0 ? configured : [vm.DEFAULT_OSM_LAYER];
         const bases = {};
-        let first = null;
         for (const c of charts) {
           const layer = L.tileLayer(c.url, {
             minZoom: c.minZoom,
@@ -235,10 +242,12 @@ class DrMapView extends HTMLElement {
           });
           this.tileLayers[c.identifier] = layer;
           bases[c.name] = layer;
-          if (!first) first = layer;
         }
-        first.addTo(this.map);
-        if (Object.keys(bases).length > 1) {
+        if (configured.length > 0) {
+          // Auto-select only a real configured chart, never the fallback.
+          Object.values(bases)[0].addTo(this.map);
+        }
+        if (Object.keys(bases).length > 1 || configured.length === 0) {
           L.control.layers(bases, {}, { collapsed: true }).addTo(this.map);
         }
       })

package/public/dr-viewmodel.js

@@ -396,6 +396,9 @@ export class Sparkline {
  */
 export function divergenceText(d) {
   if (!d || !Number.isFinite(d.distance_nm)) return "— nm";
+  // Below display resolution the bearing is the direction of noise on a
+  // zero-length vector — meaningless, don't show it.
+  if (d.distance_nm < 0.005) return `${d.distance_nm.toFixed(2)} nm`;
   const brg = String(Math.round(d.bearing_true)).padStart(3, "0");
   return `${d.distance_nm.toFixed(2)} nm / ${brg}°`;
 }

package/tests/dr-viewmodel.test.js

@@ -183,6 +183,20 @@ test("divergenceText: formats distance and zero-padded bearing", async () => {
   assert.strictEqual(vm.divergenceText(null), "— nm");
 });
 
+test("divergenceText: no bearing below display resolution — it is the direction of noise", async () => {
+  const vm = await loadVm();
+  // A few metres of DR-GPS offset: bearing is meaningless, distance is
+  // honest at "0.00 nm".
+  assert.strictEqual(
+    vm.divergenceText({ distance_nm: 0.004, bearing_true: 248 }),
+    "0.00 nm",
+  );
+  assert.strictEqual(
+    vm.divergenceText({ distance_nm: 0.006, bearing_true: 97 }),
+    "0.01 nm / 097°",
+  );
+});
+
 test("uncertaintySpec: passes radius/method with DR center", async () => {
   const vm = await loadVm();
   const u = vm.uncertaintySpec([60, 24], {

package/tests/hysteresis.test.js

@@ -0,0 +1,62 @@
+/**
+ * Tests for the generic flag hysteresis (sensor-health alert debouncing).
+ * @file hysteresis.test.js
+ */
+
+const test = require("node:test");
+const assert = require("node:assert/strict");
+
+const { createFlagState, flagTick } = require("../plugin/hysteresis.js");
+
+test("flagTick: raw condition must persist sustainS before raising", () => {
+  const st = createFlagState();
+  const opts = { sustainS: 10, clearS: 10 };
+  // 9 seconds of raw true — not yet.
+  for (let i = 0; i < 9; i++) {
+    assert.strictEqual(flagTick(st, true, 1, opts).transition, null);
+    assert.strictEqual(st.active, false);
+  }
+  // 10th second — raises.
+  const out = flagTick(st, true, 1, opts);
+  assert.strictEqual(out.transition, "raise");
+  assert.strictEqual(out.active, true);
+});
+
+test("flagTick: condition must stay false clearS before clearing", () => {
+  const st = createFlagState();
+  const opts = { sustainS: 1, clearS: 3 };
+  assert.strictEqual(flagTick(st, true, 1, opts).transition, "raise");
+  // 2 seconds of raw false — still active.
+  assert.strictEqual(flagTick(st, false, 1, opts).transition, null);
+  assert.strictEqual(st.active, true);
+  assert.strictEqual(flagTick(st, false, 1, opts).transition, null);
+  // 3rd second — clears.
+  const out = flagTick(st, false, 1, opts);
+  assert.strictEqual(out.transition, "clear");
+  assert.strictEqual(out.active, false);
+});
+
+test("flagTick: a jittery tick neither raises nor clears (no flapping)", () => {
+  const st = createFlagState();
+  const opts = { sustainS: 3, clearS: 3 };
+  // Raise first.
+  for (let i = 0; i < 3; i++) flagTick(st, true, 1, opts);
+  assert.strictEqual(st.active, true);
+  // Alternating raw true/false around a threshold: timers reset each
+  // side, so no clear transition ever fires and no re-raise flaps.
+  for (let i = 0; i < 20; i++) {
+    const out = flagTick(st, i % 2 === 0, 1, opts);
+    assert.strictEqual(out.transition, null);
+  }
+  assert.strictEqual(st.active, true);
+});
+
+test("flagTick: sub-second ticks accumulate fractionally", () => {
+  const st = createFlagState();
+  const opts = { sustainS: 0.3, clearS: 0.3 };
+  const a = flagTick(st, true, 0.1, opts);
+  const b = flagTick(st, true, 0.1, opts);
+  assert.strictEqual(a.transition, null);
+  assert.strictEqual(b.transition, null);
+  assert.strictEqual(flagTick(st, true, 0.1, opts).transition, "raise");
+});

package/tests/plugin.test.js

@@ -993,6 +993,21 @@ test("uncertainty polygon publishes fallback method with no correction history",
 test("uncertainty polygon radius grows monotonically with distance run", async () => {
   // Isolated DB so no leftover dr_corrections push it into empirical mode.
   const dir = await mkdtemp(join(tmpdir(), "dr-unc-grow-"));
+  // Pre-seed the restored per-excursion distance well above the GNSS
+  // noise floor (0.02 nm) so both samples measure growth, not the floor.
+  const seedDb = require("../plugin/db.js").openDatabase(
+    join(dir, "dead-reckoning.sqlite"),
+  );
+  const { setState } = require("../plugin/db.js");
+  setState(seedDb, "dr_log_since_origin", "5");
+  // Seed the origin too, or the first GPS delta snaps to it and resets
+  // the excursion distance back to zero.
+  setState(
+    seedDb,
+    "last_known_good_fix",
+    JSON.stringify({ latitude: 60, longitude: 24 }),
+  );
+  seedDb.close();
   const app = new FakeSignalKApp();
   app.dataPath = dir;
   const plugin = makePlugin(app);
@@ -1024,12 +1039,21 @@ test("uncertainty polygon radius grows monotonically with distance run", async (
     r2.radius_nm > r1.radius_nm,
     `radius should grow: r1=${r1.radius_nm} r2=${r2.radius_nm}`,
   );
+  assert.ok(r1.radius_nm > 0.02, "seeded run should exceed the floor");
   plugin.stop();
   await rm(dir, { recursive: true, force: true });
 });
 
 test("uncertainty polygon tightens toward empirical after corrections + bin hits", async () => {
   const dir = await mkdtemp(join(tmpdir(), "dr-unc-emp-"));
+  // Seed the restored per-excursion distance so both regimes measure
+  // rates, not the GNSS-noise floor.
+  const seedDb = require("../plugin/db.js").openDatabase(
+    join(dir, "dead-reckoning.sqlite"),
+  );
+  const { setState } = require("../plugin/db.js");
+  setState(seedDb, "dr_log_since_origin", "5");
+  seedDb.close();
   const app = new FakeSignalKApp();
   app.dataPath = dir;
   const plugin = makePlugin(app);
@@ -1091,7 +1115,7 @@ test("uncertainty polygon tightens toward empirical after corrections + bin hits
   // radius at the same distance (the tightening signal).
   const { computeRadius } = require("../plugin/uncertainty.js");
   const fallbackOnly = computeRadius({
-    elapsedDistanceNm: 5 / 3600,
+    elapsedDistanceNm: 5,
     effectiveHitCount: 0,
     deviationRows: [],
     stwKn: 5,
@@ -1106,6 +1130,20 @@ test("uncertainty polygon tightens toward empirical after corrections + bin hits
 
 test("uncertainty polygon radius drops after a snap-to-fix resets the excursion", async () => {
   const dir = await mkdtemp(join(tmpdir(), "dr-unc-snap-"));
+  // Seed the restored per-excursion distance so `before` is well above
+  // the GNSS-noise floor; after the snap it must drop to the floor.
+  const seedDb = require("../plugin/db.js").openDatabase(
+    join(dir, "dead-reckoning.sqlite"),
+  );
+  const { setState } = require("../plugin/db.js");
+  setState(seedDb, "dr_log_since_origin", "10");
+  // Seed the origin so the first GPS delta doesn't reset the excursion.
+  setState(
+    seedDb,
+    "last_known_good_fix",
+    JSON.stringify({ latitude: 60, longitude: 24 }),
+  );
+  seedDb.close();
   const app = new FakeSignalKApp();
   app.dataPath = dir;
   const plugin = makePlugin(app);
@@ -1174,8 +1212,10 @@ test("divergence advisory raises on sustained DR-GPS divergence and publishes th
   });
   const router = new FakeRouter();
   plugin.registerWithRouter(router);
-  // GPS held fixed at (60, 24) while the boat sails north at 6 kn from it
-  // — divergence grows far faster than the fallback polygon radius.
+  // GPS held fixed at (60, 24) while the boat sails north at a
+  // synthetic 120 kn from it — divergence must outrun the GNSS-noise
+  // radius floor (0.02 nm) within the fast-hysteresis window; a real
+  // 6 kn would take ~20 s to cross it.
   app.emitDelta({
     context: "vessels.self",
     updates: [
@@ -1185,13 +1225,13 @@ test("divergence advisory raises on sustained DR-GPS divergence and publishes th
             path: "navigation.position",
             value: { latitude: 60, longitude: 24 },
           },
-          { path: "navigation.speedThroughWater", value: 6 },
+          { path: "navigation.speedThroughWater", value: 120 },
           { path: "navigation.headingTrue", value: 0 },
         ],
       },
     ],
   });
-  await new Promise((r) => setTimeout(r, 1000));
+  await new Promise((r) => setTimeout(r, 2000));
   // Divergence readout published and growing.
   const dvg = latestDivergence(app);
   assert.ok(dvg.distance_nm > 0, "divergence readout should be non-zero");
@@ -1228,13 +1268,13 @@ test("divergence advisory clears after a confirmed fix snaps DR back to GPS", as
             path: "navigation.position",
             value: { latitude: 60, longitude: 24 },
           },
-          { path: "navigation.speedThroughWater", value: 6 },
+          { path: "navigation.speedThroughWater", value: 120 },
           { path: "navigation.headingTrue", value: 0 },
         ],
       },
     ],
   });
-  await new Promise((r) => setTimeout(r, 900));
+  await new Promise((r) => setTimeout(r, 2000));
   const raised = latestNotification(
     app,
     "notifications.navigation.deadReckoning.divergenceAdvisory",
@@ -1292,27 +1332,264 @@ test("divergence monitor is suppressed at anchor", async () => {
     ],
   });
   await new Promise((r) => setTimeout(r, 900));
+  // Suppression now means an explicit null readout (so connected UIs drop
+  // any stale underway figure), not silence.
   const vals = app.handledMessages
     .flatMap((m) => m.message?.updates ?? [])
     .flatMap((u) => u.values ?? [])
     .filter((v) => v.path === "navigation.deadReckoning.divergence");
+  assert.ok(vals.length > 0, "null divergence readout should be published");
   assert.strictEqual(
-    vals.length,
-    0,
-    "divergence readout should be suppressed at anchor",
+    vals[vals.length - 1].value,
+    null,
+    "divergence readout should be null at anchor",
   );
   const notif = app.handledMessages
     .flatMap((m) => m.message?.updates ?? [])
     .flatMap((u) => u.values ?? [])
     .find(
       (v) =>
-        v.path === "notifications.navigation.deadReckoning.divergenceAdvisory",
+        v.path ===
+          "notifications.navigation.deadReckoning.divergenceAdvisory" &&
+        v.value.state === "alert",
     );
   assert.ok(!notif, "advisory should not fire at anchor");
   plugin.stop();
   await rm(dir, { recursive: true, force: true });
 });
 
+test("moored with wind: no fouled paddlewheel alert, advisory withdrawn, null divergence", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "dr-moored-fouled-"));
+  const app = new FakeSignalKApp();
+  app.dataPath = dir;
+  const plugin = makePlugin(app);
+  plugin.start({
+    tickIntervalMs: 100,
+    divergence: { sustainS: 0.3, clearS: 0.3 },
+  });
+  const router = new FakeRouter();
+  plugin.registerWithRouter(router);
+
+  // Phase 1 — underway, sailing away from a fixed GPS at a synthetic
+  // 120 kn (divergence outruns the 0.02 nm radius floor quickly):
+  // advisory raises.
+  app.emitDelta({
+    context: "vessels.self",
+    updates: [
+      {
+        values: [
+          {
+            path: "navigation.position",
+            value: { latitude: 60, longitude: 24 },
+          },
+          { path: "navigation.speedThroughWater", value: 120 },
+          { path: "navigation.headingTrue", value: 0 },
+        ],
+      },
+    ],
+  });
+  await new Promise((r) => setTimeout(r, 2000));
+  assert.strictEqual(
+    latestNotification(
+      app,
+      "notifications.navigation.deadReckoning.divergenceAdvisory",
+    ).state,
+    "alert",
+  );
+
+  // Phase 2 — tie up: STW reads 0 (a moored paddlewheel's honest value),
+  // wind blows 12 kn on the mast, GPS wanders a few metres. The old
+  // behaviour: phantom "paddlewheel fouled" alert + stuck advisory.
+  app.emitDelta({
+    context: "vessels.self",
+    updates: [
+      {
+        values: [
+          { path: "navigation.state", value: "moored" },
+          { path: "navigation.speedThroughWater", value: 0 },
+          { path: "environment.wind.speedApparent", value: 12 },
+          {
+            path: "navigation.position",
+            value: { latitude: 60.0005, longitude: 24.0005 },
+          },
+        ],
+      },
+    ],
+  });
+  await new Promise((r) => setTimeout(r, 900));
+
+  // The advisory raised just before mooring is withdrawn, not stuck.
+  const notif = latestNotification(
+    app,
+    "notifications.navigation.deadReckoning.divergenceAdvisory",
+  );
+  assert.strictEqual(notif.state, "normal");
+  assert.ok(/suspended while moored/.test(notif.message));
+
+  // Divergence readout is an explicit null — no stale underway figure.
+  assert.strictEqual(latestDivergence(app), null);
+
+  // No phantom fouled paddlewheel: wind on a tied-up boat is not making way.
+  const health = latestNotification(
+    app,
+    "notifications.navigation.deadReckoning.status",
+  );
+  assert.ok(health?.state !== "alert", `got ${health?.message}`);
+  plugin.stop();
+  await rm(dir, { recursive: true, force: true });
+});
+
+test("moored from the start: DR state clean (no fouled, no transient), fouled detector idle", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "dr-moored-clean-"));
+  const app = new FakeSignalKApp();
+  app.dataPath = dir;
+  const plugin = makePlugin(app);
+  plugin.start({ tickIntervalMs: 100 });
+  app.emitDelta({
+    context: "vessels.self",
+    updates: [
+      {
+        values: [
+          { path: "navigation.state", value: "moored" },
+          {
+            path: "navigation.position",
+            value: { latitude: 60, longitude: 24 },
+          },
+          { path: "navigation.speedThroughWater", value: 0 },
+          { path: "navigation.headingTrue", value: 10 },
+          { path: "environment.wind.speedApparent", value: 15 },
+          { path: "environment.wind.angleApparent", value: 1.2 },
+        ],
+      },
+    ],
+  });
+  await new Promise((r) => setTimeout(r, 500));
+  const stateDeltas = app.handledMessages
+    .flatMap((m) => m.message?.updates ?? [])
+    .flatMap((u) => u.values ?? [])
+    .filter((v) => v.path === "navigation.deadReckoning.state");
+  assert.ok(stateDeltas.length > 0, "no DR state delta published");
+  const last = stateDeltas[stateDeltas.length - 1].value;
+  assert.strictEqual(last.fouled, false);
+  assert.strictEqual(last.transient, false);
+  const health = app.handledMessages
+    .flatMap((m) => m.message?.updates ?? [])
+    .flatMap((u) => u.values ?? [])
+    .find(
+      (v) =>
+        v.path === "notifications.navigation.deadReckoning.status" &&
+        v.value.state === "alert",
+    );
+  assert.ok(!health, "no sensor-health alert while moored");
+  plugin.stop();
+  await rm(dir, { recursive: true, force: true });
+});
+
+test("fouling alert is debounced: threshold-hovering STW doesn't flap, sustained fouling raises", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "dr-fouled-debounce-"));
+  const app = new FakeSignalKApp();
+  app.dataPath = dir;
+  const plugin = makePlugin(app);
+  plugin.start({
+    tickIntervalMs: 100,
+    sensorHealth: { sustainS: 1, clearS: 1 },
+  });
+  app.emitDelta({
+    context: "vessels.self",
+    updates: [
+      {
+        values: [
+          {
+            path: "navigation.position",
+            value: { latitude: 60, longitude: 24 },
+          },
+          { path: "navigation.headingTrue", value: 0 },
+          { path: "environment.wind.speedApparent", value: 12 },
+        ],
+      },
+    ],
+  });
+
+  // STW hovers at the detector's stop threshold, strictly alternating
+  // every 37 ms (incommensurate with the 100 ms tick so consecutive
+  // ticks never sample a stable parity — paddlewheel spinner
+  // sticking/slipping): raw verdict flips far faster than the 1 s
+  // sustain window, so the alert must not raise.
+  let flip = 0;
+  const flap = setInterval(() => {
+    app.emitDelta({
+      context: "vessels.self",
+      updates: [
+        {
+          values: [
+            {
+              path: "navigation.speedThroughWater",
+              value: flip++ % 2 === 0 ? 0 : 0.4,
+            },
+          ],
+        },
+      ],
+    });
+  }, 37);
+  await new Promise((r) => setTimeout(r, 1500));
+  clearInterval(flap);
+  const healthAlerts = () =>
+    app.handledMessages
+      .flatMap((m) => m.message?.updates ?? [])
+      .flatMap((u) => u.values ?? [])
+      .filter(
+        (v) =>
+          v.path === "notifications.navigation.deadReckoning.status" &&
+          v.value.state === "alert",
+      );
+  assert.strictEqual(
+    healthAlerts().length,
+    0,
+    "fouling alert flapped during threshold hover",
+  );
+
+  // A real fault — STW pinned at 0 while wind says 12 kn — must still
+  // surface after the sustain window.
+  app.emitDelta({
+    context: "vessels.self",
+    updates: [
+      {
+        values: [{ path: "navigation.speedThroughWater", value: 0 }],
+      },
+    ],
+  });
+  await new Promise((r) => setTimeout(r, 1600));
+  const alerts = healthAlerts();
+  assert.strictEqual(alerts.length, 1, "sustained fouling did not raise");
+  assert.ok(/fouled/.test(alerts[0].value.message));
+  plugin.stop();
+  await rm(dir, { recursive: true, force: true });
+});
+
+test("water-track log survives restart via dr_log_nm state", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "dr-log-restore-"));
+  // Pre-seed the persisted state a previous run's flush would have left.
+  const db = require("../plugin/db.js").openDatabase(
+    join(dir, "dead-reckoning.sqlite"),
+  );
+  const { setState } = require("../plugin/db.js");
+  setState(db, "dr_log_nm", "12.5");
+  setState(db, "dr_trip_log_nm", "3.25");
+  db.close();
+
+  const app = new FakeSignalKApp();
+  app.dataPath = dir;
+  const plugin = makePlugin(app);
+  plugin.start({});
+  const router = new FakeRouter();
+  plugin.registerWithRouter(router);
+  const { body } = router.invoke("get", "/status");
+  assert.strictEqual(body.logNm, 12.5);
+  assert.strictEqual(body.tripLogNm, 3.25);
+  plugin.stop();
+  await rm(dir, { recursive: true, force: true });
+});
+
 /** Returns the latest published divergence readout, or throws. */
 function latestDivergence(app) {
   const vals = app.handledMessages
@@ -2331,13 +2608,31 @@ function lastValues(app, path) {
 
 test("idle while making way: uncertainty grows, state carries moving, alert raised", async () => {
   const dir = await mkdtemp(join(tmpdir(), "dr-idle-moving-"));
+  // Seed the restored per-excursion distance above the GNSS-noise floor
+  // so idle-run growth is observable above it within the test window.
+  const seedDb = require("../plugin/db.js").openDatabase(
+    join(dir, "dead-reckoning.sqlite"),
+  );
+  const { setState } = require("../plugin/db.js");
+  setState(seedDb, "dr_log_since_origin", "1.5");
+  // Seed the origin so the first GPS delta doesn't reset the excursion.
+  setState(
+    seedDb,
+    "last_known_good_fix",
+    JSON.stringify({ latitude: 60, longitude: 24 }),
+  );
+  seedDb.close();
   const app = new FakeSignalKApp();
   app.dataPath = dir;
   const plugin = makePlugin(app);
-  plugin.start({ tickIntervalMs: 20, saveIntervalMs: 60000 });
+  plugin.start({
+    tickIntervalMs: 20,
+    saveIntervalMs: 60000,
+    sensorHealth: { sustainS: 0.1, clearS: 0.1 },
+  });
   try {
-    // No STW/heading (idle), but GPS shows ~6 kn over ground.
-    await emitMovingGps(app, 6, 6);
+    // No STW/heading (idle), but GPS shows ~60 kn over ground.
+    await emitMovingGps(app, 60, 20);
 
     const states = lastValues(app, "navigation.deadReckoning.state");
     assert.ok(states.length > 0, "no state deltas");
@@ -2414,7 +2709,11 @@ test("fouled paddlewheel: STW 0 while making way raises fouling alert + state fl
   const app = new FakeSignalKApp();
   app.dataPath = dir;
   const plugin = makePlugin(app);
-  plugin.start({ tickIntervalMs: 20, saveIntervalMs: 60000 });
+  plugin.start({
+    tickIntervalMs: 20,
+    saveIntervalMs: 60000,
+    sensorHealth: { sustainS: 0.1, clearS: 0.1 },
+  });
   try {
     // STW reads 0, heading present → underway branch; GPS moving ~6 kn.
     app.emitDelta({

package/tests/uncertainty.test.js

@@ -130,14 +130,37 @@ test("computeRadius: radius scales with elapsed distance, not time", () => {
   assert.ok(Math.abs(b.radius_nm - 2 * a.radius_nm) < 1e-9);
 });
 
-test("computeRadius: radius is 0 at excursion start (no distance run)", () => {
+test("computeRadius: radius floors at GNSS noise at excursion start (no distance run)", () => {
+  // Zero distance run must not report a point-exact DR position: the
+  // radius can never honestly be smaller than the GPS noise the origin
+  // was seeded from, or any dockside GPS wander "exceeds expected
+  // uncertainty" and trips the divergence advisory on a moored boat.
   const out = u.computeRadius({
     elapsedDistanceNm: 0,
     effectiveHitCount: 100,
     deviationRows: [{ deviation_nm: 1, dr_elapsed_seconds: 1000 }],
     stwKn: 5,
   });
-  assert.strictEqual(out.radius_nm, 0);
+  assert.strictEqual(out.radius_nm, u.MIN_RADIUS_NM);
+  assert.ok(u.MIN_RADIUS_NM >= 0.02, "floor below GNSS noise scale");
+});
+
+test("computeRadius: floor only applies below it — growth is unchanged above", () => {
+  const far = u.computeRadius({
+    elapsedDistanceNm: 10,
+    effectiveHitCount: 0,
+    deviationRows: [],
+    stwKn: 5,
+  });
+  assert.ok(Math.abs(far.radius_nm - u.fallbackRateNmPerNm() * 10) < 1e-9);
+  const near = u.computeRadius({
+    elapsedDistanceNm: 0.01,
+    effectiveHitCount: 0,
+    deviationRows: [],
+    stwKn: 5,
+  });
+  // 0.01 nm run × 0.01745 ≈ 0.00017 nm — below floor → floored.
+  assert.strictEqual(near.radius_nm, u.MIN_RADIUS_NM);
 });
 
 test("computeRadius: blend regime between fallback and empirical", () => {