@meri-imperiumi/signalk-dead-reckoning 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -7,6 +7,104 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-09-10
+
+### Added
+- **Derived-current tier (SPEC §6.2 tier 2)**: an exponentially-weighted
+  mean of the boat's own GPS-vs-water-track residual, sampled every
+  tick while GPS is trusted and the water track is usable (STW floor,
+  interval, glitch/outlier bounds), carried forward with exponential
+  decay when GPS degrades and TTL-bounded (24 h) so the resolver falls
+  through to the model tiers after. Zero-configuration: it outranks
+  the Weather API and pilot charts as soon as ~10 samples exist (the
+  first minutes of a passage), `environment.current` and `/status`
+  surface it as source `derived`, and the uncertainty cone uses a
+  tighter per-tier residual (0.2 kn). Sea-trial replay
+  (Aitutaki→Niue 2026-08-30→09-05): final DR error 10.9 nm over 622 nm
+  vs 47.3 nm for the live tier-3 configuration and 85.2 nm for the
+  zero vector — landfall-visible DR on a trade-wind passage.
+
+### Fixed
+- **The weather-current client calls the Weather API in-process**
+  (`app.weatherApi.getForecasts()`, the same instance the REST routes
+  wrap — mirrors signalk-energy-predictor) instead of an HTTP loopback
+  that defaulted to `localhost:3000` — a port Grafana answers on this
+  install, so every poll 404ed and tier 3 never resolved
+  ("Weather current fetch failed: weather API returned 404 — using
+  zero current"). No base URL, ports or auth tokens involved; the
+  `weatherCurrent.baseUrl` config option is gone.
+- **The celestial sight plausibility gate measures the distance from
+  the DR origin, not from the sight's assumed position** (sea trial
+  2026-08-31 root-cause follow-up): a small intercept at a wrong
+  assumed position drew the LOP an ocean away and the gate never saw
+  it. Non-noon sights now gate on the perpendicular distance from the
+  DR origin to the LOP (floored by the intercept magnitude), mirroring
+  the `/fix/lop` bearing gate; noon sights gate on the origin-vs-
+  reduction latitude difference.
+- **The fix-confirm sanity cap now grows with DR time-since-origin**
+  instead of being a flat 100 NM: legitimate fixes after days GPS-less
+  (DR drifts ~0.5–1 NM/h; the trials measured 47 NM in 4.5 days with a
+  current tier, 85 NM cold) were being rejected, training crews to
+  habitually force-confirm — defeating the guard for the teleport
+  case it exists for. The cap is now `max(100 NM, 1.5 kn × hours since
+  origin)`, mirrored in `/fix/resolve`'s `gross` preview flag.
+- **Training Mode is suspended while the resolved current is tier 5
+  (zero vector — current unknown)** (SPEC §6.1/§6.2): training with an
+  unknown current bakes it into the leeway/speed bins as fake
+  corrections and over-applies them later (Huahine→Aitutaki backtest:
+  72 vs 65 nm cold; both trials' regressions). With the new tier-2
+  derived current self-bootstrapping in the first minutes of a
+  passage, a current-resolved matrix train no longer requires a
+  weather provider. The replay tool's learning variants accordingly
+  run with the derived current ("training with zero current" is no
+  longer a reachable live configuration), and a new `derived` variant
+  (cold + tier 2, no training) isolates the tier's contribution in
+  backtests.
+- **Logbook write-through no longer floods the server when
+  authentication cannot be obtained** (reported 2026-09-11 on
+  lille-oe-pi: a continuous ~10 req/s stream of
+  `POST /plugins/signalk-logbook/logs` 401s at anchor; the 91-byte
+  bodies identified the server's plugin-route admin gate answering a
+  tokenless "open server" probe). The access-request client read
+  *any* non-OK response (403 disallowed device requests, 429 rate
+  limit, 400 duplicate, 503, …) as "no access-request flow", built a
+  tokenless client, ate the admin gate's 401, and re-ran the whole
+  cycle forever. The client now distinguishes: 403 → "forbidden"
+  (park; the plugin status names the two ways out — allow device
+  access requests on the server, or paste a token); 404/501 → a
+  single tokenless probe, terminal on rejection; everything else →
+  "unreachable", retried on an exponential backoff (30 s doubling to
+  a 16 min cap, configurable via `logbook.retryBackoffMs`) — never an
+  open-server assumption, never a loop. A rejected config token or
+  tokenless probe parks instead of resurrecting the same credentials
+  in a loop. A pending access request is persisted and resumed across
+  restarts instead of re-filed (the server rejects duplicates), and an
+  approval granted while the plugin was down is picked up on the
+  first poll. Queued entries are never dropped by any of this.
+- **The "paddlewheel appears fouled" alert no longer fires on breeze
+  over a moored boat** while `navigation.state` hasn't landed in the
+  delta cache yet (or on installs without an autostate source): a live
+  SOG reading below the moving threshold is now an outright "not
+  making way" verdict, and wind only corroborates fouling when GPS is
+  silent.
+
+### Added
+- **Polar speed fallback now also works without
+  signalk-polar-performance-plugin**: when its `performance.polarSpeed`
+  feed is absent, DR computes the speed in-process from the active
+  `polars` resource (the signalk-polar-management contract — the
+  `polars.activePolar` pointer and `polars.performanceFactor` derating
+  multiplier) interpolated from water-referenced true wind
+  (`environment.wind.speedTrue` / `angleTrueWater`). The resource path
+  shares the existing running-average window and staleness cutoff, is
+  zero-configuration (engages when an active polar is selected, stays
+  dormant otherwise), and a live `performance.polarSpeed` feed still
+  outranks it. The DR state's `speedSource` distinguishes `polar`
+  (delta feed) from `polar-resource`, the sensor-health alert names the
+  active resource id, and GET /status mirrors the loaded polar. A dead
+  wind instrument ages the average out to the honest idle branch
+  instead of integrating a frozen wind at a frozen speed.
+
 ## [0.8.0] - 2026-09-09
 
 ### Fixed

package/SPEC.md

@@ -269,7 +269,7 @@ Worker Thread (DR Physics)
 
 ### 6.1 Training Mode vs. Inference Mode
 
-**Training Mode** — active when `isGpsReliable = true` AND `propulsion.main.state = stopped` AND paddlewheel not fouled (§6.3):
+**Training Mode** — active when `isGpsReliable = true` AND `propulsion.main.state = stopped` AND paddlewheel not fouled (§6.3) AND the resolved current is not the zero vector (§6.2 tier < 5 — training with an unknown current bakes it into the leeway/speed bins as fake corrections):
 - Computes error vectors: GPS SOG/COG vs. sensor STW/heading, minus the resolved current vector (§6.2), updated into matching `dr_matrix_bins` via EMA, learning rate modulated by effective `hit_count`.
 
 **Inference Mode** — active when `isGpsReliable = false` OR OVERRIDE is manually engaged:
@@ -286,8 +286,8 @@ The paddlewheel-failure fallback is a distinct branch from the "GPS unreliable"
 ### 6.2 Current Hierarchy of Truth
 
 1. Manual Override — watchstander input with valid TTL (`environment.current`).
-2. Live High-Res — Starlink-cached coastal NetCDF vectors.
-3. Sparse Forecast — bilinear/temporal-interpolated radio GRIB vectors.
+2. Derived Residual — exponentially-weighted mean of the boat's own GPS-vs-water-track residual (`derived-current.js`), sampled while GPS is trusted and the water track is usable; carried forward with exponential decay when GPS degrades, TTL-bounded. The boat's own observation outranks model products (sea trial 2026-08-30→09-05, Aitutaki→Niue: ~11 nm DR error over 622 nm vs 47 nm for tier 3, 85 nm for tier 5).
+3. Sparse Forecast — bilinear/temporal-interpolated radio GRIB vectors (Signal K Weather API).
 4. Offline Pilot Charts — static SQLite monthly historical averages (`offline_pilot_currents`).
 5. Zero Vector — pure inertial water track (U: 0, V: 0).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meri-imperiumi/signalk-dead-reckoning",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Offline-first dead reckoning and sensor fusion engine for Signal K",
   "main": "plugin/index.js",
   "scripts": {
@@ -34,7 +34,8 @@
     "recommends": [
       "@meri-imperiumi/signalk-autostate",
       "@meri-imperiumi/signalk-logbook",
-      "signalk-polar-performance-plugin"
+      "signalk-polar-performance-plugin",
+      "signalk-polar-management"
     ],
     "screenshots": [
       "./doc/dr-map.png",

package/plugin/current.js

@@ -7,7 +7,11 @@
  *  1. **Manual override** — watchstander input with a valid TTL
  *     (`environment.current`). Not yet wired to an input path; the
  *     resolver accepts it so the precedence is explicit and testable.
- *  2. Live high-res NetCDF (Starlink-cached coastal) — future.
+ *  2. **Derived residual** — EWMA of the boat's own GPS-vs-water-track
+ *     residual (`derived-current.js`), learned while GPS is trusted and
+ *     carried forward with decay when GPS degrades. The boat's own
+ *     observation outranks model products (sea trial 2026-08-30→09-05:
+ *     ~11 nm DR error over 622 nm vs 47 nm for tier 3).
  *  3. **Signal K Weather API** (`/signalk/v2/api/weather/forecasts/point`)
  *     — a provider (e.g. a GRIB another process already downloaded)
  *     serves point forecasts carrying `current: {set (rad), drift (m/s)}`.
@@ -102,13 +106,17 @@ function parseWeatherCurrent(points, nowMs) {
  * @param {object} [input]
  * @param {{setTrue: number, drift: number, validUntilMs: number}|null} [input.manual]
  *   tier 1: watchstander override, honored while its TTL lasts
+ * @param {{setTrue: number, drift: number, validUntilMs: number}|null} [input.derived]
+ *   tier 2: EWMA of the boat's own GPS-vs-water-track residual
+ *   (`derived-current.js`), TTL-bounded and decayed while GPS is
+ *   degraded — the boat's own observation outranks model products
  * @param {{setTrue: number, drift: number, validUntilMs: number}|null} [input.weather]
  *   tier 3: Weather API cache entry from `WeatherCurrentClient.currentAt`
  * @param {((ctx: object) => ({setTrue: number, drift: number}|null))|null} [input.pilotLookup]
  *   tier 4: (month,lat,lon)→vector lookup into `offline_pilot_currents`
  * @param {object} [input.pilotCtx] - context for the pilot lookup
  * @param {number} [input.nowMs] - epoch ms; defaults to Date.now()
- * @returns {{setTrue: number, drift: number, tier: 1|3|4|5, source: string}}
+ * @returns {{setTrue: number, drift: number, tier: 1|2|3|4|5, source: string}}
  *   drift in knots, setTrue in deg true (direction the current flows toward)
  */
 function resolveCurrent(input = {}) {
@@ -125,6 +133,15 @@ function resolveCurrent(input = {}) {
       source: "manual",
     };
   }
+  // Tier 2: derived residual — the boat's own GPS-vs-water-track EWMA.
+  if (valid(input.derived)) {
+    return {
+      setTrue: normalizeDeg360(input.derived.setTrue ?? 0),
+      drift: input.derived.drift,
+      tier: 2,
+      source: "derived",
+    };
+  }
   // Tier 3: Weather API (sparse forecast GRIB via a weather provider).
   if (valid(input.weather)) {
     return {
@@ -157,34 +174,40 @@ function resolveCurrent(input = {}) {
  * 30 min) with a hard timeout, failures keep the previous cache until
  * its TTL lapses, and `currentAt` is a synchronous cache read.
  *
+ * The call is **in-process** (mirrors signalk-energy-predictor): the
+ * plugin always talks to the Signal K server it runs inside —
+ * `app.weatherApi.getForecasts()` is the same WeatherApi instance the
+ * `/signalk/v2/api/weather` REST routes wrap — so weather providers
+ * (e.g. a GRIB provider) registered by other plugins answer without
+ * HTTP, auth tokens or port guessing. The old HTTP loopback defaulted
+ * to `localhost:3000`, which on this install is Grafana and 404s every
+ * `/signalk/...` path. On servers without the Weather API the client
+ * stays idle and the §6.2 resolver never sees tier 3.
+ *
  * The response is a WeatherDataModel array; `current.set` is radians
  * and `current.drift` m/s (converted here to deg/kn).
  */
 class WeatherCurrentClient {
   /**
    * @param {object} [opts]
-   * @param {string} [opts.baseUrl] - server base URL (no trailing slash)
+   * @param {object} [opts.weatherApi] - the server's `app.weatherApi`
+   *   (needs a `getForecasts` function)
    * @param {number} [opts.intervalMs=1800000] - poll interval
    * @param {number} [opts.count=6] - forecast entries to request
-   * @param {number} [opts.timeoutMs=10000] - per-fetch abort timeout
+   * @param {number} [opts.timeoutMs=10000] - per-fetch timeout
    * @param {number} [opts.validityFactor=4] - cache TTL = interval × this
    * @param {() => ({latitude: number, longitude: number}|null)} [opts.getPosition]
    * @param {(message: string) => void} [opts.onStatus]
-   * @param {typeof fetch} [opts.fetchFn=globalThis.fetch]
    * @param {() => number} [opts.now=Date.now]
    */
   constructor(opts = {}) {
-    this.baseUrl = (opts.baseUrl ?? "http://localhost:3000").replace(
-      /\/+$/,
-      "",
-    );
+    this.weatherApi = opts.weatherApi ?? null;
     this.intervalMs = opts.intervalMs ?? 30 * 60 * 1000;
     this.count = opts.count ?? 6;
     this.timeoutMs = opts.timeoutMs ?? 10000;
     this.validityFactor = opts.validityFactor ?? 4;
     this.getPosition = opts.getPosition ?? (() => null);
     this.onStatus = opts.onStatus ?? null;
-    this.fetchFn = opts.fetchFn ?? globalThis.fetch?.bind(globalThis);
     this.now = opts.now ?? (() => Date.now());
     /** @type {{setTrue: number, drift: number, fetchedAt: number, validUntilMs: number}|null} */
     this.cache = null;
@@ -226,48 +249,51 @@ class WeatherCurrentClient {
    * @returns {Promise<void>}
    */
   async poll() {
-    if (this.fetching || !this.fetchFn) return;
+    if (this.fetching) return;
+    if (
+      !this.weatherApi ||
+      typeof this.weatherApi.getForecasts !== "function"
+    ) {
+      return; // server has no Weather API — tier 3 simply never resolves
+    }
     const pos = this.getPosition();
     if (!pos) return; // no position yet — retry on the next interval
     this.fetching = true;
     try {
-      const url = new URL(
-        `${this.baseUrl}/signalk/v2/api/weather/forecasts/point`,
-      );
-      url.searchParams.set("lat", String(pos.latitude));
-      url.searchParams.set("lon", String(pos.longitude));
-      url.searchParams.set("count", String(this.count));
-
-      const controller = new AbortController();
-      const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
-      try {
-        const res = await this.fetchFn(url.toString(), {
-          signal: controller.signal,
-        });
-        if (!res.ok) {
-          throw new Error(`weather API returned ${res.status}`);
-        }
-        const data = await res.json();
-        if (!Array.isArray(data)) {
-          throw new Error("weather API response is not an array");
-        }
-        const parsed = parseWeatherCurrent(data, this.now());
-        if (!parsed) {
-          throw new Error("forecast carries no current data");
-        }
-        const now = this.now();
-        this.cache = {
-          setTrue: parsed.setTrue,
-          drift: parsed.drift,
-          fetchedAt: now,
-          validUntilMs: now + this.intervalMs * this.validityFactor,
-        };
-        this.onStatus?.(
-          `Weather current: set ${parsed.setTrue.toFixed(0)}° true, drift ${parsed.drift.toFixed(2)} kn`,
-        );
-      } finally {
-        clearTimeout(timeoutId);
+      // In-process (same object the REST routes wrap): providers
+      // registered by other plugins answer directly. The timeout guards
+      // a provider doing its own network fetch under the hood.
+      let timeoutId;
+      const data = await Promise.race([
+        this.weatherApi.getForecasts(
+          { latitude: pos.latitude, longitude: pos.longitude },
+          "point",
+          { maxCount: this.count },
+        ),
+        new Promise((_resolve, reject) => {
+          timeoutId = setTimeout(
+            () => reject(new Error("weather API timed out")),
+            this.timeoutMs,
+          );
+        }),
+      ]).finally(() => clearTimeout(timeoutId));
+      if (!Array.isArray(data)) {
+        throw new Error("weather API response is not an array");
+      }
+      const parsed = parseWeatherCurrent(data, this.now());
+      if (!parsed) {
+        throw new Error("forecast carries no current data");
       }
+      const now = this.now();
+      this.cache = {
+        setTrue: parsed.setTrue,
+        drift: parsed.drift,
+        fetchedAt: now,
+        validUntilMs: now + this.intervalMs * this.validityFactor,
+      };
+      this.onStatus?.(
+        `Weather current: set ${parsed.setTrue.toFixed(0)}° true, drift ${parsed.drift.toFixed(2)} kn`,
+      );
     } catch (err) {
       // Keep any previous cache; the TTL decides when it stops being
       // trusted. Surface the failure once per poll cycle.

package/plugin/derived-current.js

@@ -0,0 +1,180 @@
+/**
+ * Derived current from the boat's own GPS-vs-water-track residual
+ * (SPEC §6.2 tier 2).
+ *
+ * While GPS is trusted, every position fix minus the water-track
+ * displacement is a direct observation of the current vector. An
+ * exponentially-weighted mean of these residuals — updated whenever a
+ * GPS fix and a usable water track coexist — tracks the real ocean
+ * current far better than the model products (sea trial
+ * 2026-08-30→09-05, Aitutaki→Niue: EWMA tier held DR within ~11 nm
+ * over 622 nm vs 47 nm for the tier-3 weather API and 85 nm for the
+ * zero vector).
+ *
+ * When GPS degrades (jamming, spoofing, the Red Sea case) the state
+ * carries forward with exponential decay until its TTL lapses, at
+ * which point the §6.2 resolver falls through to the model tiers. The
+ * update gates are deliberately conservative: only sample when the
+ * water track carries direction (STW above the usability floor), only
+ * accept residuals within ocean-current bounds (a 3+ kn "current" is a
+ * GPS glitch or a lagoon transit, not an observation to learn from).
+ *
+ * Pure logic over an explicit state object — unit-testable without
+ * Signal K plumbing. The plugin entry point samples it once per tick
+ * with the latest GPS fix and water track, and reads a snapshot for
+ * the resolver.
+ *
+ * @file derived-current.js
+ */
+
+/** Minimum seconds between GPS fixes used for ground-vector sampling. */
+const MIN_GPS_INTERVAL_S = 5;
+
+/** STW (kn) above which the water track carries usable direction. */
+const MIN_STW_KN = 1.0;
+
+/** Residual magnitude (kn) above which a sample is discarded as a glitch. */
+const MAX_RESIDUAL_KN = 3.0;
+
+/** SOG (kn) above which a GPS displacement is a glitch, not sailing. */
+const MAX_SOG_KN = 60;
+
+/** EWMA time constant (s) for residual samples (sea-trial-validated 6 h). */
+const TAU_S = 6 * 3600;
+
+/** Carry decay time constant (s) once GPS sampling stops. */
+const CARRY_TAU_S = 24 * 3600;
+
+/** How long (ms) after the last sample the snapshot stays valid. */
+const MAX_AGE_MS = 24 * 3600 * 1000;
+
+/** Samples required before the snapshot resolves (below: not a current). */
+const MIN_SAMPLES = 10;
+
+/**
+ * Creates the derived-current state.
+ *
+ * @returns {{lastGps: {latitude:number, longitude:number, tMs:number}|null,
+ *   uKn: number, vKn: number, lastSampleMs: number, sampleCount: number}}
+ */
+function createDerivedCurrentState() {
+  return {
+    lastGps: null,
+    uKn: 0,
+    vKn: 0,
+    lastSampleMs: 0,
+    sampleCount: 0,
+  };
+}
+
+/**
+ * Feeds one tick's sensors into the EWMA. The ground vector comes from
+ * consecutive GPS fixes (position-differential SOG/COG — the ground
+ * truth, per the calibration report §7); the water vector from STW and
+ * true heading. Both must be present and sane for a sample; the stored
+ * fix refreshes either way so the next differential starts here.
+ *
+ * @param {object} st - state from {@link createDerivedCurrentState}
+ * @param {object} s - per-tick snapshot
+ * @param {number} s.tMs - epoch ms of this tick
+ * @param {{latitude:number, longitude:number}|null} s.gps - latest GPS fix
+ * @param {number|null} s.stwKn - speed through water (kn)
+ * @param {number|null} s.headingTrueDeg - true heading (deg [0,360))
+ * @returns {{sampled: boolean, reason: string|null}} why no sample was
+ *   taken, when it wasn't
+ */
+function updateDerivedCurrent(st, s) {
+  if (!s.gps) return { sampled: false, reason: "no-gps" };
+  const dtS = (s.tMs - (st.lastGps?.tMs ?? 0)) / 1000;
+  const prev = st.lastGps;
+  st.lastGps = {
+    latitude: s.gps.latitude,
+    longitude: s.gps.longitude,
+    tMs: s.tMs,
+  };
+  if (!prev || dtS < MIN_GPS_INTERVAL_S) {
+    return { sampled: false, reason: "interval" };
+  }
+  if (s.stwKn == null || s.stwKn < MIN_STW_KN) {
+    return { sampled: false, reason: "stw" };
+  }
+  if (s.headingTrueDeg == null || !Number.isFinite(s.headingTrueDeg)) {
+    return { sampled: false, reason: "heading" };
+  }
+
+  const rad = Math.PI / 180;
+  const latAvg = ((prev.latitude + s.gps.latitude) / 2) * rad;
+  const meanLatNm = (s.gps.latitude - prev.latitude) * 60;
+  const eastNm = (s.gps.longitude - prev.longitude) * 60 * Math.cos(latAvg);
+  const distNm = Math.hypot(meanLatNm, eastNm);
+  const sogKn = distNm / (dtS / 3600);
+  if (sogKn > MAX_SOG_KN) {
+    return { sampled: false, reason: "gps-glitch" };
+  }
+  const cogDeg =
+    distNm > 1e-9 ? (Math.atan2(eastNm, meanLatNm) * 180) / Math.PI : 0;
+
+  // Residual = ground velocity − water velocity, in kn components
+  // (u = east, v = north).
+  const u =
+    sogKn * Math.sin(cogDeg * rad) - s.stwKn * Math.sin(s.headingTrueDeg * rad);
+  const v =
+    sogKn * Math.cos(cogDeg * rad) - s.stwKn * Math.cos(s.headingTrueDeg * rad);
+  if (Math.hypot(u, v) > MAX_RESIDUAL_KN) {
+    return { sampled: false, reason: "residual-outlier" };
+  }
+
+  if (st.sampleCount === 0) {
+    st.uKn = u;
+    st.vKn = v;
+  } else {
+    // Continuous-time first-order filter: alpha from the sample gap.
+    const alpha = 1 - Math.exp(-dtS / TAU_S);
+    st.uKn += (u - st.uKn) * alpha;
+    st.vKn += (v - st.vKn) * alpha;
+  }
+  st.sampleCount += 1;
+  st.lastSampleMs = s.tMs;
+  return { sampled: true, reason: null };
+}
+
+/**
+ * Snapshot for the §6.2 resolver. The drift magnitude decays with the
+ * age of the last sample (current persistence is hours, not days); the
+ * TTL bounds it outright, after which the resolver falls through to the
+ * model tiers.
+ *
+ * @param {object} st - state from {@link createDerivedCurrentState}
+ * @param {number} nowMs - epoch ms
+ * @returns {{setTrue: number, drift: number, validUntilMs: number}|null}
+ *   setTrue in deg true (direction the current flows toward), drift in
+ *   kn; null when there is no usable derived current yet
+ */
+function derivedCurrentSnapshot(st, nowMs) {
+  if (st.sampleCount < MIN_SAMPLES) return null;
+  const ageMs = nowMs - st.lastSampleMs;
+  if (ageMs < 0 || ageMs > MAX_AGE_MS) return null;
+  const drift =
+    Math.hypot(st.uKn, st.vKn) * Math.exp(-ageMs / (CARRY_TAU_S * 1000));
+  if (!Number.isFinite(drift) || drift < 1e-6) {
+    return { setTrue: 0, drift: 0, validUntilMs: st.lastSampleMs + MAX_AGE_MS };
+  }
+  const setTrue =
+    ((((Math.atan2(st.uKn, st.vKn) * 180) / Math.PI) % 360) + 360) % 360;
+  return { setTrue, drift, validUntilMs: st.lastSampleMs + MAX_AGE_MS };
+}
+
+module.exports = {
+  createDerivedCurrentState,
+  updateDerivedCurrent,
+  derivedCurrentSnapshot,
+  // tunables exported for tests
+  MIN_GPS_INTERVAL_S,
+  MIN_STW_KN,
+  MAX_RESIDUAL_KN,
+  MAX_SOG_KN,
+  TAU_S,
+  CARRY_TAU_S,
+  MAX_AGE_MS,
+  MIN_SAMPLES,
+};

package/plugin/fix-pipeline.js

@@ -256,6 +256,28 @@ function advanceToLatest(observations, advance) {
   return { observations: out, advancements };
 }
 
+/**
+ * Gross-displacement sanity cap for fix confirmation (sea trial
+ * 2026-08-31): a candidate a whole ocean away from the DR origin is a
+ * bad sight or bad input, not navigation — 69°S implied ~140 kn. But
+ * legitimate DR drift accumulates ~0.5–1 nm/h (sea trials measured
+ * 47 nm in 4.5 days with a current tier, 85 nm cold), so the cap must
+ * grow with the hours since the origin was set — a flat cap trains
+ * crews to force-confirm, defeating the guard for the teleport case
+ * it exists for.
+ *
+ * @param {number} maxDisplacementNm - configured flat cap (nm)
+ * @param {number} elapsedSinceOriginS - seconds since the origin was
+ *        set (integration time)
+ * @returns {number} cap in nm
+ */
+function fixSanityCapNm(maxDisplacementNm, elapsedSinceOriginS) {
+  const hours = Number.isFinite(elapsedSinceOriginS)
+    ? Math.max(0, elapsedSinceOriginS) / 3600
+    : 0;
+  return Math.max(maxDisplacementNm, 1.5 * hours);
+}
+
 function resolveCandidateFix(input) {
   const sourceType = input.source_type;
   const lopIds = input.observationIds?.lopIds ?? [];
@@ -542,6 +564,7 @@ module.exports = {
   advanceToLatest,
   defaultOriginErrorNm,
   evaluateObservationPlausibility,
+  fixSanityCapNm,
   MAX_IMPLIED_SPEED_KN,
   MIN_GATE_DISPLACEMENT_NM,
 };