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

package/CHANGELOG.md

@@ -7,6 +7,108 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-09-17
+
+### Fixed
+- **The derived-current EWMA can now sample on a healthy GPS feed — and
+  only ever pairs fixes from one receiver.** The sampler refreshed its
+  differential baseline on every tick, so with GPS fixes arriving faster
+  than the 5 s minimum interval the ≥5 s differential could only form
+  across `navigation.position` null gaps — and those gap-spanning samples
+  routinely paired fixes from *different* receivers. On the
+  2026-09-11…14 Niue→Vava'u trial that produced a phantom "current" of
+  1.1 kn @ ~131° for 55 h (a quasi-fixed ~140 m offset between two
+  position providers ÷ the multi-minute sampling gap — heading-
+  independent, which is why it didn't look like leeway), dragging DR to
+  34.7 nm of error at arrival while the real current was 0.6 kn @ 006°.
+  Replaying the same passage with the sampler working ends at 8.7 nm.
+  The baseline now holds across cadence-rejected ticks (samples form at
+  the 5 s minimum instead of only across null gaps), differentials use
+  the fix's own timestamp (a paused feed can no longer fabricate
+  zero-ground "currents" from a running tick clock), fixes carry their
+  `$source` so a differential never spans two receivers, and the tick
+  path feeds the sampler (and training's ground truth) the server's
+  priority-filtered tree position instead of the last-writer-wins raw
+  delta — on multi-GPS installs the raw subscription stream flits
+  between every provider of the path (this one: ZG100, Orca, WIDELINK
+  AIS, YDNR, Cerbo, the RUTX11's indoor GNSS, and the own-boat
+  meshtastic node's LoRa-recycled position), several of which sit
+  100 m+ from the truth. Verified by capturing the live subscription
+  stream: ranked-below sources still deliver; priorities only gate the
+  merged tree.
+- **A bearing to a known object is now a ray constraint in the fix
+  resolver, not an infinite line.** On the same trial a running fix
+  against a bearing to AIS vessel MATILDA (115.5° true, 4.1 nm)
+  projected the advanced fix onto the far side of the line: a "fix"
+  2.7 nm past the vessel from which the vessel bore the reciprocal of
+  the sighted bearing. The resolver now rejects points past the
+  object's anchor — in single-observation running fixes, bearing×
+  bearing intersections, bearing×range circle picks and the
+  parallel-bearings midline — with an error explaining that the run and
+  the bearing disagree (celestial intercept LOPs stay full lines; a
+  100 m along-ray slack keeps close-range sights with ordinary compass
+  slop from hard-rejecting). The
+  `lop_type` threads from the persisted row through running-fix
+  advancement into the resolver, and REST resolve/confirm surface the
+  rejection as the 400 message.
+
+### Changed
+- **Training Mode no longer runs on model currents (tier 3/4), only on
+  observed ones (manual tier 1, derived tier 2).** A wrong current —
+  model *or* phantom — gets compensated by the trainer as physically
+  impossible leeway: the Niue→Vava'u trial's phantom tier-2 current was
+  absorbed as 15–18° of leeway on broad reaches (thousands of live
+  hits), which then mis-rotate the water track whenever the current
+  resolves correctly. Same failure shape as the previous trial's tier-5
+  zero-current poisoning, now gated for the model tiers too. A write-time
+  plausibility bound rejects observations implying |leeway| > 15° (input
+  disagreement, not hydrodynamics), and schema v3 ships a one-time data
+  migration removing bins with |leeway| > 10° accumulated during the two
+  poisoned trials — no manual SQL on the boat.
+
+### Changed
+- **The DR output is no longer published to the bus on every
+  integration tick.** Each published delta costs the Signal K server
+  fanout — delta-cache routing plus serialization to every websocket
+  client and logging plugin subscribed to the context — and most of
+  the DR output (log, trip log, current vector, uncertainty radius,
+  elapsed-since-fix) is slow-moving data nobody needs at 1 Hz. The
+  tick still integrates every `tickIntervalMs`; the published set is
+  batched to every `publish.everyTicks`-th tick (new setting, default
+  2 → one delta every 2 s at the default 1 s tick; 1 restores
+  per-tick publishing). Notable transitions publish immediately,
+  within the tick that observed them: method/state/active flips, paths
+  appearing or disappearing (e.g. the STW echo dropping when the
+  polar fallback takes over), and values crossing to/from null (e.g.
+  the divergence readout clearing at anchor). The shadow vessel's
+  synthetic target follows the same cadence.
+
+### Fixed
+- **The logbook access-request flow now targets the logbook URL's own
+  host and port.** It previously used a separate `logbook.baseUrl`
+  setting that wasn't even exposed in the plugin settings UI and
+  defaulted to `http://localhost:3000` — on installs where that port
+  isn't the Signal K server (Grafana there), its 404 read as "open
+  server", the tokenless probe then hit the real server's auth gate,
+  and logbook writes parked with "Logbook writes need authentication
+  this plugin cannot obtain" even though the server's access-request
+  flow was fully available. The `logbook.baseUrl` config option is
+  gone: the origin is derived from the configured `logbook.url`. An
+  unparseable URL parks the flow with a message naming the fix instead
+  of crashing the write path.
+- **The uncertainty cone no longer grows while anchored or moored.**
+  The current-knowledge term scaled with wall-clock time since the
+  last fix, so a week on the hook painted a 100+ NM circle around a
+  boat the ground was holding perfectly still. The engine now tracks
+  a separate under-way clock (`underwaySinceOriginS`, gated by
+  `navigation.state` anchored/moored, persisted across restarts) and
+  the cone grows only on that axis; wall-clock `since last fix` still
+  counts anchor time (published unchanged). The same axis now also
+  drives the fix sanity cap (the boat can't have traveled while
+  anchored — a far fix is more suspect, not less) and the learned
+  `dr_corrections` deviation rate (anchor time between fixes no
+  longer deflates it).
+
 ## [0.9.0] - 2026-09-10
 
 ### Added

package/SPEC.md

@@ -91,6 +91,7 @@ CREATE TABLE IF NOT EXISTS dr_matrix_bins (
 - `stw_bin`/`awa_bin`/`heel_bin` must be populated via an explicit quantization function (round to nearest bin width) before insert/lookup — storing raw continuous values as the primary key would prevent `hit_count` from ever accumulating meaningfully.
 - `live_hit_count` and `historical_hit_count` are tracked separately so a season of live sailing can outweigh years of backfilled data in the effective confidence/learning-rate calculation — each live sample should count as several times a historical sample by default (tunable), and each historical sample's weight further depends on `historical_confidence_tier` (a bin trained against reanalysis current data is more trustworthy than one that only had climatological pilot-chart current available).
 - `sail_state = motoring` (or any interval where `propulsion.main.state = started`) is **excluded** from writes to this table entirely — the underlying physics (prop walk, wake, rudder-induced yaw) differs from sail-driven leeway and would corrupt the model if blended. A separate under-power calibration table is out of scope for v1 (see §12).
+- **Plausibility bound:** observations implying |leeway| > 15° are rejected at write time — real leeway for this hull is ≈0° on a run and ≈10–13° close-hauled in a gale; anything beyond is input disagreement (wrong current tier, flappy sensor sources), not hydrodynamics. Both 2026 sea trials poisoned bins this way (10–32° on broad reaches); schema v3 ships a one-time data migration removing bins with |leeway| > 10° accumulated before the bound existed.
 - Historical bins written during backfill should apply a mild recency-decay weight, and/or respect configured "epoch boundaries" (known re-rig / instrument-replacement dates) so pre- and post-change data isn't blended across a known discontinuity.
 
 ### 4.2 Persistent DR State & Checkpoints
@@ -174,6 +175,8 @@ CREATE TABLE IF NOT EXISTS circular_position_lines (
 - Circle × Circle → **two** candidate intersections; default to the one nearest current DR position, but surface both to the watchkeeper rather than silently discarding one.
 - A single, unresolved LOP or CPL may still be **advanced** along the DR track to combine with a later observation (classic running fix), reusing the DR engine's integrated track over the elapsed interval.
 
+**Bearing ray constraint:** a bearing to a *known object* (charted feature, AIS target) is a ray, not a full line — the bearing itself says which side of the object the observer is on (the reciprocal side). A resolved point past the object's anchor would place the vessel where the object bears the *opposite* of the sighted bearing — geometrically on the line, navigationally wrong (2026-09-13, AIS vessel MATILDA: the running-fix projection landed 2.7 nm beyond the target and "reversed" the bearing). The resolver enforces the observer's ray for `lop_type = 'bearing'` in the point-projection (running fix), Line × Line, Line × Circle and parallel-midline branches — a candidate past the object beyond a 100 m along-ray slack (close-range compass/run slop) is rejected with an explanatory error. Celestial intercept LOPs remain full lines: any point on the line is equally valid.
+
 **Non-intersecting / contradictory inputs (residual fallback):** measurement error means an exact geometric intersection is the exception rather than the rule — three or more LOPs/CPLs will almost never cross at a single point (the classical "cocked hat" case), and even a two-input combination can fail to intersect cleanly if one observation was mistimed or misread. The resolver must not fail silently or force a nearest-point snap when inputs disagree beyond expected measurement tolerance. Instead:
 - With ≥3 inputs, resolve via least-squares residual minimization (best-fit point minimizing summed distance to each line/circle constraint) rather than requiring exact intersection.
 - With exactly 2 inputs that don't intersect within tolerance, present the closest-approach point and the residual gap explicitly, rather than silently picking a point on one of the two constraints.
@@ -269,8 +272,9 @@ 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) 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):
+**Training Mode** — active when `isGpsReliable = true` AND `propulsion.main.state = stopped` AND paddlewheel not fouled (§6.3) AND the resolved current is an *observed* vector (§6.2 tier ≤ 2 — manual or derived; training with an unknown *or modelled* current bakes its error into the leeway/speed bins as fake corrections: the zero vector did this on the 2026-08-30→09-05 trial, a wrong tier-2 phantom on 2026-09-11…14):
 - 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`.
+- Observations implying |leeway| > 15° are rejected outright as input disagreement, not hydrodynamics (§4.1 plausibility bound).
 
 **Inference Mode** — active when `isGpsReliable = false` OR OVERRIDE is manually engaged:
 - Freezes matrix learning. Reads raw sensors, looks up matching bins, applies corrections, integrates the resolved current vector, publishes `navigation.deadReckoning.position` as authoritative (`navigation.deadReckoning.active = true`).
@@ -286,7 +290,7 @@ 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. 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).
+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). Sampling discipline (2026-09-11…14 trial): differentials pair only fixes from the same `$source` (multi-receiver buses flit between antennas at 1 Hz each — a cross-receiver differential is antenna separation measured as current), span the fixes' own timestamps at a ≥5 s minimum cadence, and the tick path reads the server's priority-filtered tree position rather than the raw last-writer-wins subscription stream.
 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.9.0",
+  "version": "0.10.0",
   "description": "Offline-first dead reckoning and sensor fusion engine for Signal K",
   "main": "plugin/index.js",
   "scripts": {

package/plugin/db.js

@@ -20,7 +20,7 @@ const { mkdirSync } = require("node:fs");
 /** Schema version, bumped when a migration is needed. Persisted in dr_state_store.
  * v2: `fixes.derived_from_fix_id` — provenance for single-observation
  * running fixes advanced from a previous confirmed fix. */
-const SCHEMA_VERSION = 2;
+const SCHEMA_VERSION = 3;
 
 /**
  * DDL for every table in SPEC §4. Statements run in order; all are
@@ -202,6 +202,7 @@ function openDatabase(dbPath) {
     db.exec(stmt);
   }
   migrate(db);
+  migrateData(db);
   // Record schema version so future migrations can branch on it.
   setState(db, "schema_version", String(SCHEMA_VERSION));
   return db;
@@ -283,6 +284,47 @@ function migrate(db) {
   }
 }
 
+/**
+ * One-time, version-gated *data* migrations. Unlike the column steps
+ * above (idempotent by construction, safe on every open), these are
+ * gated on the stored `schema_version` so each runs exactly once per
+ * database. Bumping SCHEMA_VERSION and adding an entry here upgrades
+ * an existing install on its first open.
+ *
+ * v3 — poisoned-leeway cleanup (sea trials 2026-08-30…09-05 and
+ * 2026-09-11…14): both trials trained while the resolved current was
+ * wrong (zero vector, then the phantom cross-receiver tier-2 vector),
+ * and the trainer absorbed the current error as leeway — bins carrying
+ * 10–32° of leeway on broad reaches, physically impossible for this
+ * hull (real leeway on a run is ≈0°, close-hauled in a gale ≈10–13°).
+ * Those bins mis-rotate the water track on every later passage until
+ * retrained, so they are removed outright: the EMA would blend them
+ * out only over many more hours than a clean restart. The current-tier
+ * training gate (§6.1) and the computeObservation plausibility bound
+ * prevent new poison of this shape.
+ */
+const DATA_MIGRATIONS = [
+  {
+    version: 3,
+    run: (db) => {
+      db.exec("DELETE FROM dr_matrix_bins WHERE ABS(leeway_angle) > 10");
+    },
+  },
+];
+
+/**
+ * Applies pending data migrations, gated on the stored schema version.
+ *
+ * @param {import("node:sqlite").DatabaseSync} db
+ * @returns {void}
+ */
+function migrateData(db) {
+  const stored = Number(getState(db, "schema_version") ?? 0);
+  for (const step of DATA_MIGRATIONS) {
+    if (stored < step.version) step.run(db);
+  }
+}
+
 /**
  * Reads a scalar value from `dr_state_store`.
  *

package/plugin/derived-current.js

@@ -51,6 +51,14 @@ const MAX_AGE_MS = 24 * 3600 * 1000;
 /** Samples required before the snapshot resolves (below: not a current). */
 const MIN_SAMPLES = 10;
 
+/**
+ * How long (ms) a source-mismatched fix is ignored before the sampler
+ * gives up on the baseline's source and adopts the new one (the old
+ * receiver went silent — better to restart the differential on the
+ * surviving antenna than to never sample again).
+ */
+const MAX_BASELINE_STALE_MS = 60 * 1000;
+
 /**
  * Creates the derived-current state.
  *
@@ -68,16 +76,32 @@ function createDerivedCurrentState() {
 }
 
 /**
- * Feeds one tick's sensors into the EWMA. The ground vector comes from
+ * Feeds one GPS fix 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.
+ * fix refreshes only when a sample is actually taken (or the baseline
+ * is first adopted) so the ≥ MIN_GPS_INTERVAL_S differential can form
+ * across a healthy 1 Hz fix stream — refreshing the baseline on every
+ * cadence-rejected tick meant the EWMA could only sample across
+ * position-null gaps — and those paired fixes from different receivers,
+ * producing a phantom 1.1 kn @ ~131° "current" for 55 h on the
+ * 2026-09-11…14 Niue→Vava'u trial (see the sampler rules below).
+ *
+ * Fixes are attributed to their `$source` when the caller supplies one
+ * (multi-GPS installs flit between antennas metres apart at 1 Hz each —
+ * a cross-source differential is antenna separation, not current), and
+ * timestamps come from the fix itself (`fixTimeMs`) rather than the
+ * tick clock, so a paused feed never yields a zero-displacement
+ * "sample" against a refreshed clock.
  *
  * @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.fixTimeMs] - epoch ms of the fix itself; falls
+ *   back to s.tMs when the caller has no fix timestamp
+ * @param {string|null} [s.source] - `$source` of the fix delta, when known
  * @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
@@ -85,16 +109,44 @@ function createDerivedCurrentState() {
  */
 function updateDerivedCurrent(st, s) {
   if (!s.gps) return { sampled: false, reason: "no-gps" };
-  const dtS = (s.tMs - (st.lastGps?.tMs ?? 0)) / 1000;
+  const fixTMs = Number.isFinite(s.fixTimeMs) ? s.fixTimeMs : s.tMs;
+  const source = typeof s.source === "string" && s.source ? s.source : null;
+
+  // Antenna flapping: a differential between two different receivers is
+  // antenna separation measured as speed, not current. Hold the baseline
+  // (it belongs to the source that is still streaming) and ignore the
+  // interloper — unless the baseline's own source has gone quiet for so
+  // long that adopting the new source is the only way forward.
+  const baselineStaleMs = fixTMs - (st.lastGps?.tMs ?? 0);
+  if (
+    st.lastGps &&
+    source != null &&
+    st.lastGps.source != null &&
+    source !== st.lastGps.source &&
+    baselineStaleMs < MAX_BASELINE_STALE_MS
+  ) {
+    return { sampled: false, reason: "source" };
+  }
+
+  const dtS = (fixTMs - (st.lastGps?.tMs ?? 0)) / 1000;
+  if (!st.lastGps || dtS < MIN_GPS_INTERVAL_S) {
+    if (!st.lastGps) {
+      st.lastGps = {
+        latitude: s.gps.latitude,
+        longitude: s.gps.longitude,
+        tMs: fixTMs,
+        source,
+      };
+    }
+    return { sampled: false, reason: "interval" };
+  }
   const prev = st.lastGps;
   st.lastGps = {
     latitude: s.gps.latitude,
     longitude: s.gps.longitude,
-    tMs: s.tMs,
+    tMs: fixTMs,
+    source,
   };
-  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" };
   }
@@ -134,7 +186,7 @@ function updateDerivedCurrent(st, s) {
     st.vKn += (v - st.vKn) * alpha;
   }
   st.sampleCount += 1;
-  st.lastSampleMs = s.tMs;
+  st.lastSampleMs = fixTMs;
   return { sampled: true, reason: null };
 }
 
@@ -152,8 +204,11 @@ function updateDerivedCurrent(st, s) {
  */
 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;
+  // Fix timestamps can sit slightly ahead of the wall clock (GPS time
+  // vs Pi time): clamp rather than treat a small negative age as
+  // "impossible" — the carry decay must still flow.
+  const ageMs = Math.max(0, nowMs - st.lastSampleMs);
+  if (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) {
@@ -177,4 +232,5 @@ module.exports = {
   CARRY_TAU_S,
   MAX_AGE_MS,
   MIN_SAMPLES,
+  MAX_BASELINE_STALE_MS,
 };

package/plugin/engine.js

@@ -65,6 +65,12 @@ class DeadReckoningEngine {
     this.tripLogNm = opts.tripLogNm ?? 0;
     /** @type {number|null} seconds since the DR origin was last reset */
     this.elapsedSinceOriginS = 0;
+    /** @type {number} seconds spent under way since the DR origin was last
+     * reset — the uncertainty cone's current-knowledge term grows only
+     * while the vessel is making way: at anchor/moored the ground holds
+     * the boat, so unknown current cannot accumulate DR error (a week on
+     * the hook must not paint a 100+ NM circle around the boat). */
+    this.underwaySinceOriginS = 0;
     /** @type {number} water-track log accumulated since the last snap-to-fix (nm)
      * — SPEC §8 uses elapsed *distance* run, not clock time, as the
      * uncertainty-polygon growth axis (DR error compounds with distance
@@ -91,6 +97,7 @@ class DeadReckoningEngine {
   snapToFix(fix, originErrorNm = 0) {
     this.origin = { latitude: fix.latitude, longitude: fix.longitude };
     this.elapsedSinceOriginS = 0;
+    this.underwaySinceOriginS = 0;
     this.logNmSinceOrigin = 0;
     this.originErrorNm = Math.max(0, originErrorNm);
   }
@@ -121,6 +128,9 @@ class DeadReckoningEngine {
    * @param {number} inputs.leewayDeg - learned leeway angle (degrees, + to leeward)
    * @param {number} inputs.speedLoss - learned speed-loss fraction [0,1]
    * @param {{setTrue: number, drift: number}} [inputs.current] - resolved current (deg true, kn)
+   * @param {boolean} [inputs.underway=true] - whether the vessel is under
+   *   way this tick (from `navigation.state`); gates the under-way clock
+   *   the uncertainty cone grows on, not the wall-clock one
    * @param {number} [inputs.dtS=1] - tick interval in seconds
    * @returns {{latitude: number, longitude: number}|null} new position, or null if no origin
    */
@@ -150,6 +160,7 @@ class DeadReckoningEngine {
     this.logNm += effectiveStw * hours;
     this.tripLogNm += effectiveStw * hours;
     this.elapsedSinceOriginS += dtS;
+    if (inputs.underway ?? true) this.underwaySinceOriginS += dtS;
     this.logNmSinceOrigin += effectiveStw * hours;
     return pos;
   }

package/plugin/fix-pipeline.js

@@ -134,6 +134,7 @@ function loadObservationsById(db, helpers, lopIds, cplIds) {
       assumed_lon: row.assumed_lon,
       azimuth_true: row.azimuth_true,
       intercept_nm: row.intercept_nm ?? 0,
+      lop_type: row.lop_type ?? null,
       timestamp_ms: Date.parse(row.timestamp),
     });
   }
@@ -262,18 +263,19 @@ function advanceToLatest(observations, advance) {
  * 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
+ * grow with the hours under way since the origin was set — anchored
+ * time doesn't count (the ground holds the boat) — 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)
+ * @param {number} underwaySinceOriginS - seconds under way 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
+function fixSanityCapNm(maxDisplacementNm, underwaySinceOriginS) {
+  const hours = Number.isFinite(underwaySinceOriginS)
+    ? Math.max(0, underwaySinceOriginS) / 3600
     : 0;
   return Math.max(maxDisplacementNm, 1.5 * hours);
 }

package/plugin/fixes.js

@@ -38,6 +38,7 @@ const {
   degToRad,
   radToDeg,
   normalizeDeg180,
+  normalizeDeg360,
   destinationPoint,
 } = require("./geo.js");
 
@@ -265,6 +266,9 @@ function distanceToCircle(center, radiusM, p) {
  * @property {number} assumed_lon
  * @property {number} azimuth_true
  * @property {number} [intercept_nm]
+ * @property {string} [lop_type] - 'bearing' marks a bearing to a known
+ *   object: the constraint is the observer-side ray, not the full line
+ *   (see {@link onObserverRay})
  *
  * @typedef {Object} CplInput
  * @property {'cpl'} kind
@@ -529,6 +533,50 @@ function gaussNewtonRefine(lops, circles, start) {
  * @param {{latitude: number, longitude: number}|null} [drPosition] - to pick the plausible side; defaults to projectionCenter
  * @returns {ResolveResult|null}
  */
+/**
+ * Along-ray slack for the bearing constraint: a foot landing this close
+ * to the object's anchor is ordinary bearing/run disagreement on a
+ * close-range sight (compass slop, DR-run error over a short interval),
+ * not the mirrored-position failure the guard exists for. The drawing
+ * keeps a 1 nm stub past the object for visibility; the resolver is
+ * stricter because a "fix" well past the object is navigationally wrong.
+ */
+const RAY_TOLERANCE_M = 100;
+
+/**
+ * Bearing-LOP ray constraint (sea trial 2026-09-13, bearing to AIS
+ * vessel MATILDA): a bearing to a *charted/known object* is a ray, not
+ * an infinite line — the observer is on the reciprocal side of the
+ * object, because the bearing itself says which side. The stored
+ * azimuth is the line's normal (= measured bearing + 90° in the UI's
+ * convention), so the observer-side direction from the anchor is
+ * `azimuth + 90°`. A resolved point on the away side would place the
+ * vessel *past* the object, from where the object would bear opposite
+ * the sighted bearing — geometrically on the line, navigationally
+ * wrong (the running fix landed 2.7 nm beyond MATILDA and "reversed"
+ * the bearing). Celestial intercept LOPs stay full lines: any point on
+ * the line is equally valid.
+ *
+ * @param {object} obs - resolver-shaped LOP observation (needs
+ *   `lop_type`, `assumed_lat/lon`, `azimuth_true`)
+ * @param {{latitude:number, longitude:number}} projectionCenter
+ * @param {{x:number, y:number}} p - candidate point, local plane
+ * @param {number} [toleranceM=RAY_TOLERANCE_M] along-ray slack
+ * @returns {boolean} true when the point is on the observer's ray (or
+ *   the observation is not a bearing — no constraint)
+ */
+function onObserverRay(obs, projectionCenter, p, toleranceM = RAY_TOLERANCE_M) {
+  if (obs.lop_type !== "bearing") return true;
+  const anchor = projectToLocal(projectionCenter, {
+    latitude: obs.assumed_lat,
+    longitude: obs.assumed_lon,
+  });
+  const obsSide = degToRad(normalizeDeg360(obs.azimuth_true + 90));
+  const dir = { x: Math.sin(obsSide), y: Math.cos(obsSide) };
+  const along = (p.x - anchor.x) * dir.x + (p.y - anchor.y) * dir.y;
+  return along >= -toleranceM;
+}
+
 function resolveFix(observations, projectionCenter, drPosition = null) {
   const dr = drPosition ?? projectionCenter;
   const drLocal = projectToLocal(projectionCenter, dr);
@@ -590,6 +638,20 @@ function resolveFix(observations, projectionCenter, drPosition = null) {
       const lop = lops[0];
       const d = signedDistanceToLop(lop, q);
       const foot = { x: q.x - d * lop.n.x, y: q.y - d * lop.n.y };
+      // A bearing constrains to the observer's ray: a foot past the
+      // object means the run and the bearing disagree by more than the
+      // geometry can absorb — the honest failure, not a mirrored fix.
+      if (
+        !onObserverRay(
+          observations.find((o) => o.kind === "lop"),
+          projectionCenter,
+          foot,
+        )
+      ) {
+        throw new Error(
+          "running fix falls past the bearing's object — the advanced fix and the observed bearing disagree by more than 90°; check the run (DR track) or re-take the bearing",
+        );
+      }
       const ll = unprojectFromLocal(projectionCenter, foot);
       return {
         latitude: ll.latitude,
@@ -639,6 +701,7 @@ function resolveFix(observations, projectionCenter, drPosition = null) {
 
   // Exactly two inputs.
   if (lops.length === 2 && cplCenters.length === 0) {
+    const lopObs = observations.filter((o) => o.kind === "lop");
     const pt = intersectLopLop(lops[0], lops[1]);
     if (!pt) {
       // Parallel LOPs: the loss is flat along the common line direction,
@@ -659,6 +722,13 @@ function resolveFix(observations, projectionCenter, drPosition = null) {
         x: foot.x + tAlong * along.x,
         y: foot.y + tAlong * along.y,
       };
+      for (let i = 0; i < lopObs.length; i++) {
+        if (!onObserverRay(lopObs[i], projectionCenter, pt2)) {
+          throw new Error(
+            "parallel bearing fix falls past a bearing's object — the DR position and the observed bearings disagree",
+          );
+        }
+      }
       const ll = unprojectFromLocal(projectionCenter, pt2);
       const residual = residualSpreadNm(lops, circles, pt2);
       return {
@@ -668,6 +738,13 @@ function resolveFix(observations, projectionCenter, drPosition = null) {
         alternate: null,
       };
     }
+    for (let i = 0; i < lopObs.length; i++) {
+      if (!onObserverRay(lopObs[i], projectionCenter, pt)) {
+        throw new Error(
+          "bearing intersection falls past a bearing's object — the observed bearings disagree with each other (or one was taken to the wrong object)",
+        );
+      }
+    }
     const ll = unprojectFromLocal(projectionCenter, pt);
     const residual = residualSpreadNm(lops, circles, pt);
     return {
@@ -680,6 +757,7 @@ function resolveFix(observations, projectionCenter, drPosition = null) {
 
   if (lops.length === 1 && cplCenters.length === 1) {
     const pts = intersectLopCircle(lops[0], cplCenters[0], cplRadii[0]);
+    const lopObs = observations.find((o) => o.kind === "lop");
     if (pts.length === 0) {
       // Non-intersecting: least-squares closest approach.
       const { point, residual } = leastSquaresFit(lops, circles, drLocal);
@@ -691,9 +769,19 @@ function resolveFix(observations, projectionCenter, drPosition = null) {
         alternate: null,
       };
     }
-    if (pts.length === 1) {
-      const ll = unprojectFromLocal(projectionCenter, pts[0]);
-      const residual = residualSpreadNm(lops, circles, pts[0]);
+    // A bearing LOP constrains both circle candidates to the observer's
+    // ray — drop the past-the-object one before picking nearest-DR.
+    const onRay = pts.map((p) => onObserverRay(lopObs, projectionCenter, p));
+    const valid = pts.filter((_, i) => onRay[i]);
+    if (valid.length === 0) {
+      throw new Error(
+        "bearing×range fix falls past the bearing's object — the bearing and the range disagree",
+      );
+    }
+    if (valid.length === 1 || pts.length === 1) {
+      const p = valid[0];
+      const ll = unprojectFromLocal(projectionCenter, p);
+      const residual = residualSpreadNm(lops, circles, p);
       return {
         latitude: ll.latitude,
         longitude: ll.longitude,
@@ -702,9 +790,10 @@ function resolveFix(observations, projectionCenter, drPosition = null) {
       };
     }
     // Two candidates: nearest DR is primary, the other is alternate.
-    const d0 = Math.hypot(pts[0].x - drLocal.x, pts[0].y - drLocal.y);
-    const d1 = Math.hypot(pts[1].x - drLocal.x, pts[1].y - drLocal.y);
-    const [primary, alt] = d0 <= d1 ? [pts[0], pts[1]] : [pts[1], pts[0]];
+    const d0 = Math.hypot(valid[0].x - drLocal.x, valid[0].y - drLocal.y);
+    const d1 = Math.hypot(valid[1].x - drLocal.x, valid[1].y - drLocal.y);
+    const [primary, alt] =
+      d0 <= d1 ? [valid[0], valid[1]] : [valid[1], valid[0]];
     const ll = unprojectFromLocal(projectionCenter, primary);
     const altLl = unprojectFromLocal(projectionCenter, alt);
     const residual = residualSpreadNm(lops, circles, primary);
@@ -815,6 +904,7 @@ function advanceObservation(obs, displacement) {
       assumed_lon: moved.longitude,
       azimuth_true: obs.azimuth_true,
       intercept_nm: obs.intercept_nm,
+      lop_type: obs.lop_type,
     };
   }
   // CPL: advance the circle's center; radius is unchanged (a circle of
@@ -850,4 +940,5 @@ module.exports = {
   leastSquaresFit,
   resolveFix,
   advanceObservation,
+  onObserverRay,
 };