@meri-imperiumi/signalk-dead-reckoning 0.14.2 → 0.15.0

package/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.15.0] - 2026-10-21
+
+### Added
+- **Current set & drift in the plotter** (work doc #38 review): the manual current override — the last webapp-only surface that mattered — now lives in Freeboard too. A **Current set & drift window** (`?view=current` mount of the extension panel) embeds the webapp's `<dr-current-panel>` verbatim: the resolved §6.2 vector with its source and TTL, a manual set/drift + TTL form (PUT `/current/manual`), and clear (DELETE) — reached from an always-visible *Current set & drift* toolbar button or by tapping the new **Current set & drift widget**, a 1×1 tile showing the resolved vector and the winning source by name (Manual / Weather API / Pilot chart / Derived / None — the source enrichment rides REST `/status`; the standard SK current paths carry only the SI vector), accenting orange while a manual override is active and opening the window on tap. Named "Current set & drift" rather than "DR current" on purpose: the widget shows the resolved hierarchy winner whatever source it came from.
+- **The sanity cap grows with the origin's age** (work doc #38 review, from sea-trial data: a DR origin set in the Cook Islands in August vetoed a legitimate fix in Tonga — 806 NM, the exact crossing — because the cap grew only with *underway* hours, which stay zero on a test server that mostly sits at anchor and restarts; the state even showed the elapsed counters reset to zero by the restart's restore-snap). The engine now tracks **when the origin was set** (`engine.originSetMs`, persisted as `dr_origin_set_ms`, restored across restarts with a fallback to the newest confirmed fix's timestamp for pre-existing installs), and the sanity cap relaxes **linearly with the origin's age** — `base × ageDays` joins `base` and `1.5 NM/underway-hour` as terms — so a month-old origin no longer vetoes the fix that re-establishes truth, while a fresh origin still catches teleports at the flat cap. From the same sea trial: a **Confirm GNSS fix** toolbar button (shown while a GNSS position is available) confirms the latest GNSS position as a fix and snaps the DR origin to truth — the bootstrap a first-time user needs before sight fixes can pass the cap at all.
+- **Fixes while stationary: the running-fix advance no longer needs a DR track at anchor or moored** (work doc #38 review — the first-try scenario is exactly an anchored boat). While the engine freezes displacement (`navigation.state` anchored/moored), zero displacement is correct by construction — the anchor holds the ground position and the DR engine deliberately freezes with it — so the plugin now records **stationary spans** (new `dr_stationary_spans` table, opened when the engine freezes, closed when it resumes, persisted at the transition so a hard kill can't lose an edge) and the fix pipeline's advancement accepts any interval fully inside a span with zero displacement, no track samples required. Fixes taken at anchor now resolve and survive restarts and track gaps; a weighed-anchor edge closes the span, so moving time is never mistaken for stationary. Also carries the advancement diagnostics in the preview response (`track_coverage`: where the DR track actually reaches, and whether the engine is holding) so the pending list's "could not be advanced" warning can say why.
+- **Dead Reckoning in the plotter: the plugin drives Freeboard-SK as a plotter extension (work doc #38).** The whole at-sea loop — mark a sight, see its position line on the chart, accumulate, resolve, confirm, snap DR — now runs inside Freeboard-SK without opening the standalone webapp. The extension manifest grows from the status tile to the full surface, reusing the webapp's own components verbatim: a **Sight / Fix panel** (`keepAlive`) that embeds `<dr-sight-panel>` and `<dr-fix-panel>` (all their same-origin REST calls, edit and running-fix advancement included), opened as a **floating window** from a new *DR Sight / Fix* toolbar button (drawer fallback on hosts without `windows`); a **Pending observations window** split out onto its own panel (the same page mounted `?view=pending`), whose *DR Pending observations* toolbar button appears only while unresolved observations are actually pending (the list's own 24 h freshness rule) — the API has no button badges, so the live count rides the open window's title ("DR Pending observations (3)", updated by the runtime on every data refresh); deletion there works by two-tap confirm (arm → red *Sure?* → delete), since extension iframes are sandboxed without `allow-modals` and a `confirm()`-guarded delete silently never fires; a **background runtime** that keeps the plotter in step with the engine without any panel open; a **DR chartwork data overlay** (`overlays.data`, Freeboard ≥ 3.4) rendering the ghost track with its dark casing, uncertainty circle, LoPs (bearing rays from the charted object, celestial position lines), CPL arcs aimed at the live DR position, confirmed fixes colored per source type, snap-to-fix vectors, the candidate-fix preview ring and the DR position marker — from the same REST rows and stream paths the webapp consumes, with stable feature ids (`lop:<id>`…) so used-observations recolor, `overlay.setData` upserts stay cheap, and LoPs/CPLs/fixes are selectable (`titleProperty: name`, the webapp's tooltip convention) with an *Edit this observation* action; **chart-object sight marking** — four context-menu actions (bearing, vertical angle, radar range, horizontal angle) on positions, chart features, waypoints and AtoNs that open the panel with the object's position and charted name pre-seeded, plus a *⊙ Pick on chart* button in the panel using `map.pick`; **OVERRIDE engage/release as visibility-switched toolbar buttons** (`buttons.visibility`) mirroring `engine.active`, publishing to the runtime which PUTs the same REST endpoint (visibility learned the hard way to speak the method's one-`{ids, visible}`-object-per-call shape — a batched array is `params must be object`, and every state silently never applied; buttons and actions are separate surfaces with separate id namespaces); and **night-mode recoloring** of the chartwork via `overlay.setLayer` (warm low-blue palette, halo included). The panel wrapper seeds the components exactly as the webapp does — default position (DR first, GPS fallback), magnetic variation, GNSS quality, position format from the plugin configuration, celestial body list — and bridges their events to the runtime over extension-scoped topics (`observations-changed`, `candidate`), with a 10 s REST poll as the fallback sync so chartwork stays honest even when the change comes from the standalone webapp or another station. Overlay pushes **diff against what the host already holds** (`overlay.setData` `upsert`/`remove`) — a full-source replacement every DR tick churned the host's vector source hard enough for chartwork to flicker out of view through zoom gestures; and the pending list's candidate event reaches the runtime as the candidate itself, so the chart preview ring and the confirm button appear the moment a preview resolves. The chart-driven loop is completed by **confirmation surfaced the way OVERRIDE is**: a *Confirm DR fix* toolbar button (`buttons.visibility`) that appears while a resolved candidate is pending — and the candidate ring itself confirms with a tap (a `default` overlayFeature action), with *Resolve fix from this* offered on unresolved LoPs/CPLs (right-click / popover) when a previous confirmed fix exists to advance from, plus *Delete this observation* on the same toolbar, so a running fix never requires opening a window at all; the **candidate ring is the loud, clickable preview** — enlarged red ring with a center dot (the traditional chartwork fix mark, and the pixel hit target: a fully transparent ring interior is not hit-testable, so a click on the ring's middle used to miss), and a primary select opens the fix-resolution window — with the runtime reacting to the invocation itself as a fallback, since the host's own window path must never leave a chart click dead; a preview that cannot resolve now guides instead of verdicting — one sight alone explains the running-fix/pairing paths, crossing failures name parallel lines and missed circles (the confirm path shares the resolve path's displacement provider, so a span-covered preview confirms identically); chart-driven actions that fail — a confirm the server rejected, a resolve without coverage, a press with nothing pending — are **drawn on the chart itself** as a transient red note at the DR position (eight seconds), because a failure only an open panel can see is not a surfaced failure; the pending window stands tall like the sight windows; chart-driven actions the server rejects — a running fix without a previous fix — surface as a calm amber note in the extension panels instead of a silent console line (red stays for real failures), and the running-fix gate follows the server's own all-time-latest-fix rule rather than the display window. Sight actions open **focused single-form windows**: the four chart-object actions open tall (`90%`) windows reusing the open Sight/Fix window (`single`, per-mode `restoreKey`) pinned to just that method's form — a new `single-tab` attribute on `<dr-sight-panel>` drops the tab strip and the wrapper hides the pending list and fix-at section — instead of a small window full of unrelated chrome. Chartwork fetches carry the **same history window as the webapp** (max 7 days, anchored at the trip boundary from `/status`), so months-old position lines don't clutter the plotter. Chartwork geometry is **clipped to the view**: the runtime tracks the chart viewport (`map.getView` + settled `map.view` events) and lines, arcs, the ghost track and the uncertainty circle are clipped to the inflated view bounds before every push — a 60 nm LoP spans ±46,500 canvas pixels at zoom 16, past the ~32,767 px precision range where canvas paths silently break (the circle-shaped candidate kept rendering while the lines vanished, which pinned it to the line builder), so long chartwork now re-clips as the view moves and stays drawn at every zoom. The clip's first cut also *folded* any line whose far end lay past the box's frame edge — the vertex unwrap is sequential relative to the previous vertex (the webapp's own antimeridian pattern), pinned by a bearing-collinearity regression. Inside host windows the components' own heading rows (title + close ✕) hide behind a new `embedded` attribute — Freeboard supplies both decorations — and the extension asset route serves code with `Cache-Control: no-cache` plus `ETag`/`Last-Modified` revalidation (images keep their lifetime): the manifest updates instantly via the resources API, and a cached hour-old iframe once wrapped that fresh manifest around stale code. A new parse smoketest (`vm.SourceTextModule` over every shipped `public/*.js`, armed by `--experimental-vm-modules` in the npm test script) keeps that other classic zero-build failure — a Markdown backtick inside a template literal killing a whole component — out of the tree; it exists because exactly that shipped in this entry's first cut. Everything beyond Freeboard 3.0's surface is capability-gated (`hasCapability`): older hosts simply offer fewer contributions, the tile everywhere, the full experience on 3.4+. Geometry and conventions live in the pure, Node-tested `public/dr-ext-chartwork.js` (24 new tests; suite 891), the style in `public/dr-ext-overlay-style.json`, the runtime in `dr-ext-runtime.js`, the panel adapter in `dr-ext-panel.js`.
+- **Plotter-extension floating windows: the host implements the `windows` capability** (work doc #27 window phase; spec: freeboard-sk plotter-extensions-api *Windows*). An extension's iframe panels can now open as floating windows over the chart — several at once, each its own bus context of kind `window` carrying `windowId` and the `params` it was opened with in its handshake, plus the five `ui.*Window` methods (`openWindow`/`updateWindow`/`focusWindow`/`closeWindow`/`listWindows`) and the `window.bounds` / `window.state` / `window.closed` events delivered to the owning extension's subscribed contexts. Windows belong to the extension (any of its contexts manages them; in a window context the windowId may be omitted to mean the window itself, so a window can close itself); the host owns the chrome — a translucent title bar with the window title and a close control the extension cannot remove (an en dash that hides under `userClose: "hide"`, a cross that closes), pointer-drag moving and south-east-handle resizing with `window.bounds` published once per settled change, raise-on-interaction, and a host window limit (`windows.limit`) of six. Geometry speaks the API's anchored form (nine anchors, inward offsets, px or % sizes, min/max limits, host floor 160×120): requests resolve against the window area (the full app viewport), the host clamps and reports the truth in `bounds`, and `restoreKey` remembers the settled geometry per extension and device in `dr.plotterext.windows.v1` — the user drags the sounder somewhere once, it opens there from then on. Hidden windows (`visible: false`) stay loaded and running with no host control over them; modal windows (`modal: true`) take a backdrop above every other window with Escape always dismissing (one at a time, `windows.modalOpen`), and at the ≤600px phone breakpoint windows present `fullscreen` instead of floating, re-evaluated on resize with bounds re-clamped and the changes published. Toolbar buttons gain the `openWindow` / `toggleWindow` actions (the button tracks the window it opened: press again shows and raises; `toggleWindow` does what the window's own close control does). Errors: `windows.badRequest`, `windows.unknownId`, `windows.limit`, `windows.modalOpen`, `UNKNOWN_PANEL`. An extension leaving the collection loses its windows silently, and its remembered geometry goes with it. New pure geometry/policy in `dr-ext-host-core.js` (parse/resolve/clamp, presentation breakpoint, geometry store), chrome and bus glue in `dr-ext-host-windows.js`; 25 new tests.
+
+### Changed
+- **The sight forms carry their ⊙ Pick button beside the coordinate inputs** (the standalone header button is gone): with the `pick` attribute, each coordinate fieldset's legend gains a small pick control that asks the host for a chart pick and lands the result in that fieldset — the horizontal-angle form's pick fills its own A/B/C slot. **The pending window stands tall** via a bumped restore key (the remembered geometry of the first, shorter open would otherwise defeat every later height request).
+- **The pending-observations list previews automatically as the selection changes** — the *Preview selected* button is gone. Resolving a candidate is cheap, local and reversible (no rows are written), so it now rides the selection: debounced ~600 ms after the last checkbox toggle, sequence-guarded so a stale response can't overwrite a newer candidate, and the preview ring on the chart stays put while the selection still spans it. The deliberate step stays deliberate: *Confirm fix* is the human confirmation that writes the fix and snaps DR (SPEC §9.1). The "could not be advanced" warning now says why — the DR track's actual coverage window, with clock skew and mid-passage restarts called out as the likely culprits.
+- **Panel `whileEnabled` is no longer honored — upstream dropped it** (freeboard-sk #921): a panel loads when first opened (`onOpen`, the default) and dies on close; only `keepAlive` parks. The host no longer preloads `whileEnabled` panels inside closed dialogs — work that must run while unseen belongs in a background runtime (`background.iframe`), which the host has offered since the chart-layer phase.
+
+### Fixed
+- **Stale observations no longer clog the pending-observations list.** Un-resolved LOPs/CPLs sat in the pending drawer forever no matter their age — a 36-day-old bearing from a port stay kept showing as work in progress. The list now drops un-resolved observations older than 24 h (`vm.isPendingStale`, `PENDING_MAX_AGE_MS`): a fix is a here-and-now operation — the running fix advances each observation to the current DR position — so anything older is chart history, not a constraint waiting for a partner. Chart/history surfaces are unaffected.
+- **Windows CI: source-structure tests no longer fail on CRLF checkouts.** The map/layout smoketests assert on `public/*.js` source structure with newline-sensitive regexes, which never matched once git's `autocrlf` converted the files to CRLF on a Windows runner. Both test readers now normalize CRLF → LF before matching.
+
 ## [0.14.2] - 2026-10-19
 
 ### Fixed

package/README.md

@@ -1,6 +1,6 @@
 # Signal K Dead Reckoning
 
-An offline-first dead reckoning and sensor fusion engine for Signal K that maintains a continuously computed "shadow boat" position from water-track sensors (speed through water, compass heading, and learned leeway and current corrections), so you always have a navigational fallback when GPS becomes unreliable — whether from jamming, spoofing, or plain receiver failure. While GPS is trusted, the engine learns vessel-specific calibration corrections against ground truth and watches for GPS anomalies; when it isn't, the same learned model keeps the dead-reckoned position, its uncertainty polygon, and a water-track log going. Fixes from celestial sights, compass bearings, radar ranges, vertical angles, and horizontal sextant angles are entered through a unified pipeline and can snap dead reckoning back on track, with optional write-through to the vessel's logbook (any Signal K `logentries` resource provider, such as `signalk-logbook`).
+An offline-first dead reckoning and sensor fusion engine for Signal K that maintains a continuously computed "shadow boat" position from water-track sensors (speed through water, compass heading, and learned leeway and current corrections), so you always have a navigational fallback when GPS becomes unreliable — whether from jamming, spoofing, or plain receiver failure. While GPS is trusted, the engine learns vessel-specific calibration corrections against ground truth and watches for GPS anomalies; when it isn't, the same learned model keeps the dead-reckoned position, its uncertainty polygon, and a water-track log going. Fixes from celestial sights, compass bearings, radar ranges, vertical angles, and horizontal sextant angles are entered through a unified pipeline and can snap dead reckoning back on track, with optional write-through to the vessel's logbook (any Signal K `logentries` resource provider, such as `signalk-logbook`). The whole toolset — sight entry, fix resolution, chartwork, override control — also runs inside [Freeboard-SK](https://github.com/SignalK/freeboard-sk) as a plotter extension, so you can work without leaving the plotter.
 
 **Note:** This is just a toy. Make your own navigation calculations and decisions.
 
@@ -31,9 +31,20 @@ Planning for life without GPS is no longer hypothetical: the UK Maritime and Coa
 
 ## Daily use
 
-Open the webapp from your Signal K server's *Web apps* menu. It shows the vessel and the shadow boat on the chart, GPS↔DR divergence, the uncertainty polygon, and the water-track log. A status tile is also available for Freeboard-SK ≥ 3.0.
+Open the webapp from your Signal K server's *Web apps* menu. It shows the vessel and the shadow boat on the chart, GPS↔DR divergence, the uncertainty polygon, and the water-track log. The same tools are available inside Freeboard-SK — see *In Freeboard-SK* below.
 
-**Entering fixes.** Open *⊕ Sight / LOP* and pick the method:
+### In Freeboard-SK
+
+With this plugin installed and enabled, [Freeboard-SK](https://github.com/SignalK/freeboard-sk) discovers it as a plotter extension — no extra configuration. What you get depends on the Freeboard version:
+
+* **any version** — the shadow boat itself: enable *Show the DR shadow boat on chart plotters* in the plugin configuration and the DR position is published as a synthetic vessel (labelled *DR Shadow* by default), so the plotter renders it alongside your own vessel with a projected COG line — on Freeboard-SK it shows as a green buddy target
+* **≥ 3.0** — a *Dead Reckoning* status tile for the widget grid: GPS↔DR divergence, uncertainty radius and DR health at a glance (place it by pressing and holding an empty widget spot)
+* **≥ 3.3** — a *DR Sight / Fix* floating window with the full sight entry, pending-observations list and fix resolution, opened from a toolbar button (or a drawer on small screens), plus *Engage/Release DR override* toolbar buttons that follow the engine state
+* **≥ 3.4** — the *DR chartwork* map layer, drawn by Freeboard itself above routes and waypoints but never covering your own vessel, AIS targets or alarms: the DR ghost track, uncertainty circle, lines and circles of position, confirmed fixes, snap-to-fix vectors and the live DR position. It can be shown, hidden and faded in the chart list's *Plugin layers*, follows night mode, and comes with chart-driven sight entry — right-click a charted object for *Bearing sight of this*, *Radar range to this* and friends (coordinates and the object's charted name pre-filled), and right-click an unresolved position line to edit it
+
+The standalone webapp stays unchanged — both front ends read the same engine and can be used side by side.
+
+**Entering fixes.** Open *⊕ Sight / LOP* in the webapp, or the *DR Sight / Fix* window in Freeboard, and pick the method:
 
 * **Bearing** — bearing to a known object (lighthouse, tower) gives a line of position; the instrument selector records whether it came from a hand-bearing compass or the radar
 * **Vert. Angle** — vertical angle to a known object of known height gives a circular position line

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@meri-imperiumi/signalk-dead-reckoning",
-  "version": "0.14.2",
+  "version": "0.15.0",
   "description": "Offline-first dead reckoning and sensor fusion engine for Signal K",
   "main": "plugin/index.js",
   "scripts": {
     "format": "npx @biomejs/biome check --use-editorconfig=true --write plugin/ tests/ public/",
     "lint": "npx @biomejs/biome check --use-editorconfig=true plugin/ public/",
-    "test": "node --test --test-force-exit \"tests/*.test.js\""
+    "test": "node --test --test-force-exit --experimental-vm-modules \"tests/*.test.js\""
   },
   "repository": {
     "type": "git",

package/plugin/db.js

@@ -185,6 +185,19 @@ const SCHEMA_DDL = [
     latitude REAL NOT NULL,
     longitude REAL NOT NULL
   )`,
+
+  // Fixes while stationary (work doc #38 review): while the engine
+  // freezes displacement (anchored/moored), a running-fix advance
+  // needs no track at all — zero displacement is correct by
+  // construction (the anchor holds the ground position and the DR
+  // engine deliberately freezes with it). Persisting the stationary
+  // spans keeps that true across restarts and track gaps — the
+  // first-try scenario is exactly an anchored boat. An open span
+  // (ended_ms NULL) is the current one.
+  `CREATE TABLE IF NOT EXISTS dr_stationary_spans (
+    started_ms INTEGER PRIMARY KEY,
+    ended_ms INTEGER
+  )`,
 ];
 
 /**
@@ -1155,6 +1168,74 @@ function loadTrackSamplesSince(db, sinceMs) {
     }));
 }
 
+/**
+ * Opens a stationary span (the engine froze displacement — anchored or
+ * moored). Idempotent on the start timestamp; a span open since the
+ * same instant is left alone.
+ *
+ * @param {import("node:sqlite").DatabaseSync|null} db
+ * @param {number} startedMs
+ * @returns {void}
+ */
+function openStationarySpan(db, startedMs) {
+  if (!db) return;
+  db.prepare(
+    "INSERT OR IGNORE INTO dr_stationary_spans (started_ms, ended_ms) VALUES (?, NULL)",
+  ).run(startedMs);
+}
+
+/**
+ * Closes the open stationary span at `endedMs` — the engine resumed
+ * displacement (underway again).
+ *
+ * @param {import("node:sqlite").DatabaseSync|null} db
+ * @param {number} startedMs
+ * @param {number} endedMs
+ * @returns {void}
+ */
+function closeStationarySpan(db, startedMs, endedMs) {
+  if (!db) return;
+  db.prepare(
+    "UPDATE dr_stationary_spans SET ended_ms = ? WHERE started_ms = ? AND ended_ms IS NULL",
+  ).run(endedMs, startedMs);
+}
+
+/**
+ * Loads stationary spans overlapping `sinceMs`, oldest first. Open
+ * spans (ended_ms NULL) are the engine's current one.
+ *
+ * @param {import("node:sqlite").DatabaseSync|null} db
+ * @param {number} sinceMs
+ * @returns {{started_ms: number, ended_ms: number|null}[]}
+ */
+function loadStationarySpans(db, sinceMs) {
+  if (!db) return [];
+  return db
+    .prepare(
+      "SELECT started_ms, ended_ms FROM dr_stationary_spans WHERE COALESCE(ended_ms, started_ms) >= ? ORDER BY started_ms",
+    )
+    .all(sinceMs)
+    .map((r) => ({
+      started_ms: Number(r.started_ms),
+      ended_ms: r.ended_ms == null ? null : Number(r.ended_ms),
+    }));
+}
+
+/**
+ * Prunes *closed* stationary spans older than the cutoff. Open spans
+ * are never pruned — they are the engine's present state.
+ *
+ * @param {import("node:sqlite").DatabaseSync|null} db
+ * @param {number} cutoffMs
+ * @returns {void}
+ */
+function pruneStationarySpansBefore(db, cutoffMs) {
+  if (!db) return;
+  db.prepare(
+    "DELETE FROM dr_stationary_spans WHERE ended_ms IS NOT NULL AND ended_ms < ?",
+  ).run(cutoffMs);
+}
+
 module.exports = {
   SCHEMA_VERSION,
   SCHEMA_DDL,
@@ -1172,6 +1253,10 @@ module.exports = {
   recordTrackSamples,
   pruneTrackSamplesBefore,
   loadTrackSamplesSince,
+  openStationarySpan,
+  closeStationarySpan,
+  loadStationarySpans,
+  pruneStationarySpansBefore,
   listLogbookPending,
   dequeueLogbookPending,
   listFixes,

package/plugin/engine.js

@@ -59,6 +59,11 @@ class DeadReckoningEngine {
   constructor(opts = {}) {
     /** @type {{latitude: number, longitude: number}|null} */
     this.origin = opts.origin ?? null;
+    /** @type {number|null} ms epoch of when the origin was set — the
+     * sanity cap's age term (a months-old origin must not veto a real
+     * fix with fresh sightwork). Null when the origin's age is unknown;
+     * persisted and restored across restarts. */
+    this.originSetMs = opts.originSetMs ?? null;
     /** @type {number} */
     this.logNm = opts.logNm ?? 0;
     /** @type {number} */
@@ -96,6 +101,7 @@ class DeadReckoningEngine {
    */
   snapToFix(fix, originErrorNm = 0) {
     this.origin = { latitude: fix.latitude, longitude: fix.longitude };
+    this.originSetMs = Date.now();
     this.elapsedSinceOriginS = 0;
     this.underwaySinceOriginS = 0;
     this.logNmSinceOrigin = 0;

package/plugin/fix-pipeline.js

@@ -274,11 +274,22 @@ function advanceToLatest(observations, advance) {
  *        origin was set (integration time)
  * @returns {number} cap in nm
  */
-function fixSanityCapNm(maxDisplacementNm, underwaySinceOriginS) {
+function fixSanityCapNm(
+  maxDisplacementNm,
+  underwaySinceOriginS,
+  originAgeMs = 0,
+) {
   const hours = Number.isFinite(underwaySinceOriginS)
     ? Math.max(0, underwaySinceOriginS) / 3600
     : 0;
-  return Math.max(maxDisplacementNm, 1.5 * hours);
+  // Age term (work doc #38 review): the cap must grow with the
+  // origin's *age*, not just under-way hours — an origin weeks old
+  // (a test server, a season's layup, a plugin down for passage) has
+  // no authority over where the boat is now, and must not veto the
+  // fix that re-establishes truth. Linear in days: a month old
+  // relaxes the cap to 30× the base.
+  const ageDays = Math.max(0, originAgeMs) / 86400000;
+  return Math.max(maxDisplacementNm, 1.5 * hours, maxDisplacementNm * ageDays);
 }
 
 function resolveCandidateFix(input) {

package/plugin/index.js

@@ -42,6 +42,10 @@ const {
   recordTrackSamples,
   pruneTrackSamplesBefore,
   loadTrackSamplesSince,
+  openStationarySpan,
+  closeStationarySpan,
+  loadStationarySpans,
+  pruneStationarySpansBefore,
 } = require("./db.js");
 const { MatrixStore } = require("./matrix.js");
 const { DeadReckoningEngine } = require("./engine.js");
@@ -442,6 +446,10 @@ const deps = {
   recordTrackSamples,
   pruneTrackSamplesBefore,
   loadTrackSamplesSince,
+  openStationarySpan,
+  closeStationarySpan,
+  loadStationarySpans,
+  pruneStationarySpansBefore,
   listFixes,
   listLinesOfPosition,
   listCircularPositionLines,
@@ -510,6 +518,16 @@ module.exports = (app) => {
    */
   let trackFlushedTs = 0;
 
+  /** Stationary spans (fixes while stationary, work doc #38 review):
+   * while the engine freezes displacement (anchored/moored), a
+   * running-fix advance needs no track — zero displacement is correct
+   * by construction. Spans persist so the stationary case survives
+   * restarts and track gaps; `stationarySince` is the open span's
+   * start (null when moving). @type {number|null} */
+  let stationarySince = null;
+  /** @type {{started_ms: number, ended_ms: number|null}[]} */
+  let stationarySpans = [];
+
   /** @type {WeatherCurrentClient|null} §6.2 tier-3 weather current poller */
   let weatherClient = null;
 
@@ -984,6 +1002,16 @@ module.exports = (app) => {
           ? groundTrack.samples[groundTrack.samples.length - 1].timestamp
           : seedTs;
 
+      // Stationary spans (fixes while stationary): restore the recent
+      // spans; an open one stays open — the engine froze displacement
+      // before the restart and (until it says otherwise) still holds.
+      stationarySpans = deps.loadStationarySpans(
+        db,
+        Date.now() - 8 * 24 * 3600 * 1000,
+      );
+      stationarySince =
+        stationarySpans.find((s) => s.ended_ms == null)?.started_ms ?? null;
+
       // §6.2 tier 3: poll the Signal K Weather API for the point-forecast
       // current at the vessel position (a current-capable provider such as
       // signalk-weather-router-plus). Off the 1 Hz hot path: slow interval,
@@ -1045,6 +1073,25 @@ module.exports = (app) => {
           const fix = JSON.parse(lastFix);
           if (fix && fix.latitude != null && fix.longitude != null) {
             engine.snapToFix(fix);
+            // The origin's set-time survives restarts too: the sanity
+            // cap's age term must see the REAL age (a months-old
+            // origin relaxes), not a fresh stamp from this restart.
+            // Falls back to the newest confirmed fix's timestamp when
+            // the key predates this feature.
+            const persistedSetMs = Number(
+              deps.getState(db, "dr_origin_set_ms"),
+            );
+            const latestFix = deps.listFixes(db, { limit: 1 })[0];
+            const fallbackMs = latestFix
+              ? Date.parse(latestFix.timestamp)
+              : NaN;
+            const setMs =
+              Number.isFinite(persistedSetMs) && persistedSetMs > 0
+                ? persistedSetMs
+                : Number.isFinite(fallbackMs)
+                  ? fallbackMs
+                  : null;
+            if (setMs != null) engine.originSetMs = setMs;
           }
         } catch {
           // Corrupt persisted state — start from scratch, the next GPS fix
@@ -1541,6 +1588,23 @@ module.exports = (app) => {
       config.tickIntervalMs / 1000,
       config.tripBoundary,
     );
+
+    // Stationary spans (fixes while stationary, work doc #38 review):
+    // record the anchored/moored stretches — while the engine freezes
+    // displacement, a running-fix advance is zero by construction and
+    // needs no track, so fixes taken at anchor resolve (and survive
+    // restarts) without any DR history. Transitions persist at once:
+    // a hard kill must not lose a span edge.
+    if (underway === false && stationarySince == null) {
+      stationarySince = Date.now();
+      deps.openStationarySpan(db, stationarySince);
+      stationarySpans.push({ started_ms: stationarySince, ended_ms: null });
+    } else if (underway === true && stationarySince != null) {
+      deps.closeStationarySpan(db, stationarySince, Date.now());
+      const open = stationarySpans.find((s) => s.ended_ms == null);
+      if (open) open.ended_ms = Date.now();
+      stationarySince = null;
+    }
     if (tripEdge.transition === "raise") {
       if (engine.tripLogNm > 0) {
         engine.resetTrip();
@@ -2593,9 +2657,13 @@ module.exports = (app) => {
       if (fresh.length > 0) {
         trackFlushedTs = fresh[fresh.length - 1].timestamp;
       }
+      // Closed stationary spans older than the retention window go too;
+      // an open span is the engine's present state and never prunes.
+      deps.pruneStationarySpansBefore(db, Date.now() - 8 * 24 * 3600 * 1000);
     }
     if (engine.origin) {
       deps.setState(db, "last_known_good_fix", JSON.stringify(engine.origin));
+      deps.setState(db, "dr_origin_set_ms", String(engine.originSetMs ?? ""));
     }
     deps.setState(db, "dr_log_nm", String(engine.logNm));
     deps.setState(db, "dr_trip_log_nm", String(engine.tripLogNm));
@@ -2625,6 +2693,55 @@ module.exports = (app) => {
 
   // --- REST API ----------------------------------------------------------
 
+  /**
+   * The ground-track displacement provider shared by the resolve and
+   * confirm paths — the track first, then stationary-span coverage
+   * (fixes while stationary, work doc #38 review): while the engine
+   * freezes displacement (anchored/moored), zero displacement is
+   * correct by construction — the anchor holds the ground position
+   * and the engine deliberately freezes with it. An interval fully
+   * inside a stationary span resolves without any track, so fixes
+   * taken at anchor survive restarts and track gaps. Both paths MUST
+   * use the same provider: a preview that resolved via a span must
+   * not confirm differently.
+   *
+   * @param {number} t0
+   * @param {number} t1
+   * @returns {{bearingTrue: number, distanceNm: number}|null}
+   */
+  function advanceDisplacement(t0, t1) {
+    const disp = groundTrack?.displacementBetween(t0, t1) ?? null;
+    if (disp) return disp;
+    const from = Math.min(t0, t1);
+    const to = Math.max(t0, t1);
+    for (const span of stationarySpans) {
+      if (from >= span.started_ms && to <= (span.ended_ms ?? Date.now())) {
+        return { bearingTrue: 0, distanceNm: 0 };
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Guiding failure text for an unresolvable observation set — the
+   * watchkeeper needs the next step, not a verdict (work doc #38
+   * review).
+   *
+   * @param {number[]} lopIds
+   * @param {number[]} cplIds
+   * @param {object[]|undefined} observations
+   * @returns {string}
+   */
+  function unresolvableMessage(lopIds, cplIds, observations) {
+    const total =
+      lopIds.length +
+      cplIds.length +
+      (Array.isArray(observations) ? observations.length : 0);
+    return total === 1
+      ? "one sight alone can't make a fix — it resolves as a running fix against the last confirmed fix (the DR track must cover the time between), or pair it with a second sight."
+      : "these sights don't cross — parallel lines, or a circle that misses them. Check the sight details, or add another sight.";
+  }
+
   /**
    * Parses the optional `since` query parameter (ISO-8601 string or
    * epoch ms) of the overlay endpoints into the db layer's `sinceMs`
@@ -3219,14 +3336,16 @@ module.exports = (app) => {
             getLineOfPosition: deps.getLineOfPosition,
             getCircularPositionLine: deps.getCircularPositionLine,
           },
-          advance: (t0, t1) => groundTrack?.displacementBetween(t0, t1) ?? null,
+          advance: advanceDisplacement,
         });
       } catch (err) {
         res.status(400).json({ message: err.message });
         return;
       }
       if (!candidate) {
-        res.status(400).json({ message: "observations not resolvable" });
+        res.status(400).json({
+          message: unresolvableMessage(lopIds, cplIds, b.observations),
+        });
         return;
       }
       // Preview context (sea trial 2026-08-31): surface how far the
@@ -3238,11 +3357,24 @@ module.exports = (app) => {
       const resolveCapNm = deps.fixSanityCapNm(
         config.fixes.maxDisplacementNm,
         engine.underwaySinceOriginS,
+        engine.originSetMs != null ? Date.now() - engine.originSetMs : 0,
       );
       res.json({
         candidate,
         displacement_nm: displacementNm,
         gross: displacementNm != null && displacementNm > resolveCapNm,
+        // Advancement diagnostics (work doc #38 review): when an
+        // observation could not be advanced, the honest message needs
+        // the WHY — where the DR track actually reaches, and whether
+        // the engine has been holding position (stationary spans
+        // cover their intervals regardless of the track).
+        track_coverage: {
+          oldest_ms: groundTrack?.samples[0]?.timestamp ?? null,
+          newest_ms:
+            groundTrack?.samples[groundTrack.samples.length - 1]?.timestamp ??
+            null,
+          stationary_since: stationarySince,
+        },
       });
     });
 
@@ -3304,6 +3436,8 @@ module.exports = (app) => {
       // Build the candidate: either a passed-back pre-resolved candidate,
       // a point fix, or a fresh LOP/CPL resolution.
       let candidate;
+      let lopIds = [];
+      let cplIds = [];
       try {
         if (b.candidate?.source_type) {
           candidate = b.candidate;
@@ -3324,12 +3458,11 @@ module.exports = (app) => {
               getLineOfPosition: deps.getLineOfPosition,
               getCircularPositionLine: deps.getCircularPositionLine,
             },
-            advance: (t0, t1) =>
-              groundTrack?.displacementBetween(t0, t1) ?? null,
+            advance: advanceDisplacement,
           });
         } else {
-          const lopIds = Array.isArray(b.lop_ids) ? b.lop_ids : [];
-          const cplIds = Array.isArray(b.cpl_ids) ? b.cpl_ids : [];
+          lopIds = Array.isArray(b.lop_ids) ? b.lop_ids : [];
+          cplIds = Array.isArray(b.cpl_ids) ? b.cpl_ids : [];
           const runningFixEligible =
             !(Array.isArray(b.observations) && b.observations.length > 0) &&
             lopIds.length + cplIds.length === 1;
@@ -3347,8 +3480,7 @@ module.exports = (app) => {
               getLineOfPosition: deps.getLineOfPosition,
               getCircularPositionLine: deps.getCircularPositionLine,
             },
-            advance: (t0, t1) =>
-              groundTrack?.displacementBetween(t0, t1) ?? null,
+            advance: advanceDisplacement,
           });
         }
       } catch (err) {
@@ -3356,7 +3488,9 @@ module.exports = (app) => {
         return;
       }
       if (!candidate) {
-        res.status(400).json({ message: "observations not resolvable" });
+        res.status(400).json({
+          message: unresolvableMessage(lopIds, cplIds, b.observations),
+        });
         return;
       }
 
@@ -3371,6 +3505,7 @@ module.exports = (app) => {
       const fixCapNm = deps.fixSanityCapNm(
         config.fixes.maxDisplacementNm,
         engine.underwaySinceOriginS,
+        engine.originSetMs != null ? Date.now() - engine.originSetMs : 0,
       );
       if (resets && engine.origin) {
         const displacementNm = deps.distanceNm(engine.origin, candidate);