speedandcurrent 2.3.3 → 2.4.0

package/index.js

@@ -17,18 +17,79 @@ const {
   Table2D
 } = require('signalkutilities');
 
-const { CorrectionTable } = require('./correctionTable.js');
+const {
+  CorrectionTable,
+  DEFAULT_CORRECTION_DRIFT_RATE,
+  DEFAULT_PROCESS_NOISE_RATE,
+  SECONDS_PER_MONTH,
+  KNOT_TO_MPS
+} = require('./correctionTable.js');
 
 const LONG_STABILIZING_MS = 60 * 1000;
-const ALWAYS_BLOCKING_NAVIGATION_STATES = new Set(['anchored', 'moored']);
-const OPTIONAL_BLOCKING_NAVIGATION_STATES = new Set(['motoring']);
+const MIN_SMOOTHING_WINDOW_SECONDS = 5;
+const LEARNING_GAP_SECONDS = 1;
+// navigation.state values that indicate the vessel is not moving. Only applied as an
+// override (see isVesselMoving) when options.suspendLearningOnNavigationState is enabled.
+const NOT_MOVING_NAVIGATION_STATES = new Set(['anchored', 'moored', 'motoring']);
+const OBSOLETE_SMOOTHER_KEYS = new Set(['smootherClass', 'smootherTau', 'smootherSteadyState']);
+const MAX_CORRECTION_DRIFT_RATE = 3;
+
+function correctionDriftRateToProcessNoiseRate(driftRate) {
+  const rate = Number.isFinite(Number(driftRate))
+    ? Math.min(MAX_CORRECTION_DRIFT_RATE, Math.max(0, Number(driftRate)))
+    : DEFAULT_CORRECTION_DRIFT_RATE;
+  return (rate * KNOT_TO_MPS) ** 2 / SECONDS_PER_MONTH;
+}
+
+function legacyStabilityToCorrectionDriftRate(stability) {
+  if (!Number.isFinite(Number(stability))) return DEFAULT_CORRECTION_DRIFT_RATE;
+  return Math.sqrt((10 ** -Number(stability)) * SECONDS_PER_MONTH) / KNOT_TO_MPS;
+}
 
 function normalizeNavigationState(value) {
   return typeof value === 'string' ? value.trim().toLowerCase() : null;
 }
 
 function getShortStabilizingMs(options = {}) {
-  return Math.max(0, Number(options.smootherTimeSpan) || 5) * 1000;
+  return Math.max(MIN_SMOOTHING_WINDOW_SECONDS, Number(options.smootherTimeSpan) || MIN_SMOOTHING_WINDOW_SECONDS) * 1000;
+}
+
+function getSmoothingWindowSeconds(options = {}) {
+  return Math.max(MIN_SMOOTHING_WINDOW_SECONDS, Number(options.smootherTimeSpan) || MIN_SMOOTHING_WINDOW_SECONDS);
+}
+
+function getLearningIntervalMs(options = {}) {
+  return (getSmoothingWindowSeconds(options) + LEARNING_GAP_SECONDS) * 1000;
+}
+
+function migrateCorrectionTableData(data, { filePath, statSync = fs.statSync, now = Date.now(), debug = () => {} } = {}) {
+  if (!data || (data.schemaVersion !== undefined && data.schemaVersion !== 1) || data.schemaVersion === 2) {
+    return { data, migrated: false };
+  }
+
+  let lastAcceptedAt;
+  try {
+    const stat = statSync(filePath);
+    lastAcceptedAt = Number.isFinite(stat?.mtimeMs) ? stat.mtimeMs : null;
+  } catch (err) {
+    lastAcceptedAt = null;
+  }
+  if (!Number.isFinite(lastAcceptedAt)) {
+    lastAcceptedAt = now;
+    debug(`Correction table migration used load time for ${filePath}: file modification time unavailable`);
+  }
+
+  return {
+    migrated: true,
+    data: {
+      ...data,
+      schemaVersion: 2,
+      table: data.table.map(row => row.map(cell => ({
+        ...cell,
+        lastAcceptedAt: cell?.state ? lastAcceptedAt : null
+      })))
+    }
+  };
 }
 
 function isCogOverrideActive(groundSpeedPolar, speedThreshold) {
@@ -39,45 +100,50 @@ function isCogOverrideActive(groundSpeedPolar, speedThreshold) {
     && sogHandler.value < speedThreshold;
 }
 
+/**
+ * The vessel's own "moving" state, derived from SOG. When navigation.state is known
+ * (has ever delivered a value) and the suspend-on-navigation-state setting is enabled,
+ * it can additionally force "not moving" (anchored/moored/motoring) — but it can never
+ * force "moving" when SOG says otherwise, since navigation.state can go stale or wrong
+ * without a way to verify it independently.
+ */
+function isVesselMoving({ sogMagnitude, speedThreshold, navigationStateHandler, gateEnabled }) {
+  const ownMoving = Number.isFinite(sogMagnitude) && sogMagnitude >= speedThreshold;
+  if (!ownMoving || !gateEnabled) return ownMoving;
+  const state = navigationStateHandler?.state;
+  const navigationKnown = state?.pathKnown === true && state?.hasDelta === true;
+  if (!navigationKnown) return true;
+  return !NOT_MOVING_NAVIGATION_STATES.has(normalizeNavigationState(navigationStateHandler.value));
+}
+
 /**
  * Leeway is the angle of the corrected boatspeed vector, so a small lateral
  * correction divided by a near-zero magnitude yields a large, meaningless angle.
  */
-function isLeewayValid(speed, speedThreshold, navigationStateHandler) {
+function isLeewayValid(speed, speedThreshold, vesselMoving) {
   if (!(speed >= speedThreshold)) return false;
-  const state = navigationStateHandler?.state;
-  if (state?.ready !== true) return true;
-  return !ALWAYS_BLOCKING_NAVIGATION_STATES.has(normalizeNavigationState(navigationStateHandler.value));
+  return vesselMoving;
 }
 
-function evaluateLearningMode({ options = {}, navigationState, stabilizingUntil = 0, stabilizingReason = null, now = Date.now() }) {
-  const normalizedNavigationState = normalizeNavigationState(navigationState?.value);
-  const navigationGateReady = navigationState?.ready === true;
-  const navigationGateBlocking = navigationGateReady && (
-    ALWAYS_BLOCKING_NAVIGATION_STATES.has(normalizedNavigationState)
-    || (!!options.suspendLearningOnNavigationState && OPTIONAL_BLOCKING_NAVIGATION_STATES.has(normalizedNavigationState))
-  );
-
+function evaluateLearningMode({ options = {}, vesselMoving = true, stabilizingUntil = 0, stabilizingReason = null, now = Date.now() }) {
   if (!options.updateCorrectionTable) {
-    return { state: 'off', reason: 'manual', navigationGateBlocking, normalizedNavigationState };
+    return { state: 'off', reason: 'manual' };
   }
 
-  if (navigationGateBlocking) {
-    return { state: 'suspended', reason: 'nav_state', navigationGateBlocking, normalizedNavigationState };
+  if (!vesselMoving) {
+    return { state: 'suspended', reason: 'not_moving' };
   }
 
   if (now < stabilizingUntil) {
-    return { state: 'stabilizing', reason: stabilizingReason || 'startup', navigationGateBlocking, normalizedNavigationState };
+    return { state: 'stabilizing', reason: stabilizingReason || 'startup' };
   }
 
-  return { state: 'active', reason: null, navigationGateBlocking, normalizedNavigationState };
+  return { state: 'active', reason: null };
 }
 
 function evaluateObservationGate({
   learningMode,
   inputsReady,
-  assumeCurrent,
-  currentReady,
   stw,
   sog,
   speedThreshold,
@@ -86,13 +152,13 @@ function evaluateObservationGate({
     return { state: 'skipped', reason: 'learning_off' };
   }
   if (learningMode.state === 'suspended') {
-    return { state: 'skipped', reason: learningMode.reason === 'cog_override' ? 'cog_override_active' : 'nav_state_blocked' };
+    return { state: 'skipped', reason: learningMode.reason === 'cog_override' ? 'cog_override_active' : 'not_moving_blocked' };
   }
   if (learningMode.state === 'stabilizing') {
     return { state: 'skipped', reason: 'stabilizing' };
   }
   if (!inputsReady) {
-    return { state: 'invalid', reason: assumeCurrent && !currentReady ? 'missing_current_when_required' : 'missing_input' };
+    return { state: 'invalid', reason: 'missing_input' };
   }
   if (!(stw > speedThreshold)) {
     return { state: 'skipped', reason: 'stw_below_threshold' };
@@ -118,6 +184,7 @@ function buildNavigationStateStatus(handler, gateEnabled) {
   const state = handler.state;
   const value = handler.value ?? null;
   const normalized = normalizeNavigationState(value);
+  const known = state.pathKnown === true && state.hasDelta === true;
   return {
     enabled: !!gateEnabled,
     path: handler.path,
@@ -125,10 +192,7 @@ function buildNavigationStateStatus(handler, gateEnabled) {
     ready: state.ready,
     isStale: state.isStale,
     value,
-    blocking: state.ready && (
-      ALWAYS_BLOCKING_NAVIGATION_STATES.has(normalized)
-      || (!!gateEnabled && OPTIONAL_BLOCKING_NAVIGATION_STATES.has(normalized))
-    )
+    blocking: !!gateEnabled && known && NOT_MOVING_NAVIGATION_STATES.has(normalized)
   };
 }
 
@@ -140,14 +204,14 @@ function getDerivedObservationStatus(learningMode, lastState, lastReason) {
     return { state: 'skipped', reason: 'stabilizing' };
   }
   if (learningMode.state === 'suspended') {
-    return { state: 'skipped', reason: learningMode.reason === 'cog_override' ? 'cog_override_active' : 'nav_state_blocked' };
+    return { state: 'skipped', reason: learningMode.reason === 'cog_override' ? 'cog_override_active' : 'not_moving_blocked' };
   }
   return { state: lastState, reason: lastReason };
 }
 
 module.exports = function (app) {
 
-  const DEFAULT_DIMS = { maxSpeed: 9, speedStep: 1, maxHeel: 32, heelStep: 8 };
+  const DEFAULT_DIMS = { maxSpeed: 10, speedStep: 1, maxHeel: 24, heelStep: 6 };
 
   let options = {};
   let changedOptions = {};
@@ -155,15 +219,11 @@ module.exports = function (app) {
     sogFallback: true,
     estimateBoatSpeed: false,
     updateCorrectionTable: true,
-    stability: 7,
-    assumeCurrent: false,
+    correctionDriftRate: DEFAULT_CORRECTION_DRIFT_RATE,
     suspendLearningOnNavigationState: false,
     tableName: 'correctionTable',
-    configVersion: 2,
-    smootherClass: 'MovingAverageSmoother',
-    smootherTau: 3,
+    configVersion: 3,
     smootherTimeSpan: 5,
-    smootherSteadyState: 0.2,
     showStatistics: false
   };
 
@@ -175,6 +235,10 @@ module.exports = function (app) {
     // Strip embedded table — stored separately on disk
     const { correctionTable: _drop, ...rest } = raw;
     options = { ...defaultOptions, ...rest };
+    if (!('correctionDriftRate' in rest) && Number.isFinite(Number(rest.stability))) {
+      options.correctionDriftRate = legacyStabilityToCorrectionDriftRate(rest.stability);
+    }
+    delete options.stability;
   }
 
   function saveOptions() {
@@ -193,43 +257,28 @@ module.exports = function (app) {
    * writes it back if anything changed. Called once on every start().
    */
   function migrateConfig() {
-    const obsoleteKeys = ['headingSource', 'boatSpeedSource', 'SOGSource', 'attitudeSource', 'preventDuplication', 'minSogForLearning'];
+    const obsoleteKeys = [
+      'headingSource', 'boatSpeedSource', 'SOGSource', 'attitudeSource',
+      'preventDuplication', 'minSogForLearning', 'stability', 'smootherClass',
+      'smootherTau', 'smootherSteadyState', 'assumeCurrent'
+    ];
     const hadObsolete = obsoleteKeys.some(k => k in options);
     for (const k of obsoleteKeys) delete options[k];
-    if (hadObsolete || (options.configVersion || 0) < 2) {
-      options.configVersion = 2;
+    const previousWindow = options.smootherTimeSpan;
+    options.smootherTimeSpan = getSmoothingWindowSeconds(options);
+    const windowChanged = previousWindow !== options.smootherTimeSpan;
+    if (hadObsolete || windowChanged || (options.configVersion || 0) < 4) {
+      options.configVersion = 4;
       saveOptions();
-      app.debug('Config migrated to v2: removed obsolete source-selection fields');
+      app.debug('Config migrated to v3: standardized correction-table learning smoothing');
     }
   }
 
-  /**
-   * Derives { SmootherClass, smootherOptions } from the current options.
-   * Enforces minimums so the smoother always has at least two observations for
-   * variance to be meaningful:
-   *   - MovingAverageSmoother: timeSpan >= 2 s  (≥ 2 samples at typical 1 Hz)
-   *   - ExponentialSmoother:   tau        >= 1 s
-   *   - KalmanSmoother:        steadyState in [0.01, 0.99]
-   */
+  /** Returns the fixed smoother used for all learning inputs. */
   function resolveSmootherConfig() {
-    const cls = options.smootherClass || 'MovingAverageSmoother';
-    if (cls === 'ExponentialSmoother') {
-      return {
-        SmootherClass: ExponentialSmoother,
-        smootherOptions: { timeConstant: Math.max(1, Number(options.smootherTau) || 3) }
-      };
-    }
-    if (cls === 'KalmanSmoother') {
-      const K = Math.min(0.99, Math.max(0.01, Number(options.smootherSteadyState) || 0.2));
-      return {
-        SmootherClass: KalmanSmoother,
-        smootherOptions: { steadyState: K }
-      };
-    }
-    // Default: MovingAverageSmoother
     return {
       SmootherClass: MovingAverageSmoother,
-      smootherOptions: { timeSpan: Math.max(2, Number(options.smootherTimeSpan) || 5) }
+      smootherOptions: { timeSpan: getSmoothingWindowSeconds(options) }
     };
   }
 
@@ -256,6 +305,9 @@ module.exports = function (app) {
   let smoothedResidual = null;
   let reportFull = null;
   let table = null;
+  let calculationIntervalSmoother = null;
+  let lastCalculationTime = null;
+  let lastLearningAttemptTime = null;
 
   let rawHeading = null;
   let rawAttitude = null;
@@ -299,9 +351,15 @@ module.exports = function (app) {
 
   function getLearningStatePayload() {
     const navigationState = buildNavigationStateStatus(navigationStateHandler, options.suspendLearningOnNavigationState);
+    const vesselMoving = isVesselMoving({
+      sogMagnitude: smoothedGroundSpeed?.magnitude,
+      speedThreshold: minSpeed,
+      navigationStateHandler,
+      gateEnabled: options.suspendLearningOnNavigationState
+    });
     const learningMode = evaluateLearningMode({
       options,
-      navigationState,
+      vesselMoving,
       stabilizingUntil: learningStabilizingUntil,
       stabilizingReason: learningStabilizingReason,
       now: Date.now()
@@ -319,6 +377,7 @@ module.exports = function (app) {
       observationReason: observation.reason,
       minStwForLearning: minSpeed,
       minSogForLearning: minSpeed,
+      vesselMoving,
       navigationState
     };
   }
@@ -327,6 +386,8 @@ module.exports = function (app) {
     const safePath = path || 'unknown path';
     const message = status === 'idle'
       ? `Input ${id} is idle on ${safePath}; resubscribing`
+      : status === 'incomplete'
+      ? `Input ${id} is missing ${safePath}`
       : `Input ${id} is stale on ${safePath}`;
     lifecycleWarningMap.set(id, {
       id,
@@ -394,6 +455,9 @@ module.exports = function (app) {
         const payload = reportFull.report();
         payload.lifecycleWarnings = lifecycleWarnings;
         payload.learningState = getLearningStatePayload();
+        payload.pollIntervalMs = calculationIntervalSmoother?.estimate
+          ? calculationIntervalSmoother.estimate * 1000
+          : 1000;
         res.json(payload);
       }
     });
@@ -414,7 +478,9 @@ module.exports = function (app) {
 
     // --- Settings API ---
     router.get('/api/settings', (req, res) => {
-      res.json({ ...options, ...changedOptions });
+      const active = { ...options, ...changedOptions };
+      for (const key of OBSOLETE_SMOOTHER_KEYS) delete active[key];
+      res.json(active);
     });
 
     router.put('/api/settings', (req, res) => {
@@ -429,8 +495,22 @@ module.exports = function (app) {
           return res.status(400).json({ error: `Key '${k}' is managed via the table manager` });
         }
       }
-      changedOptions = { ...changedOptions, ...body };
-      res.json({ ...options, ...changedOptions });
+      const accepted = Object.fromEntries(Object.entries(body).filter(([key]) => key !== 'stability' && !OBSOLETE_SMOOTHER_KEYS.has(key)));
+      if ('correctionDriftRate' in accepted) {
+        const driftRate = Number(accepted.correctionDriftRate);
+        if (Number.isFinite(driftRate)) {
+          accepted.correctionDriftRate = Math.min(MAX_CORRECTION_DRIFT_RATE, Math.max(0, driftRate));
+        } else {
+          delete accepted.correctionDriftRate;
+        }
+      }
+      if ('smootherTimeSpan' in accepted) {
+        accepted.smootherTimeSpan = getSmoothingWindowSeconds(accepted);
+      }
+      changedOptions = { ...changedOptions, ...accepted };
+      const active = { ...options, ...changedOptions };
+      for (const key of OBSOLETE_SMOOTHER_KEYS) delete active[key];
+      res.json(active);
     });
 
     // --- Correction Table Manager API ---
@@ -468,7 +548,7 @@ module.exports = function (app) {
       }
       const row = { min: 0, max: body.maxSpeed, step: body.speedStep };
       const col = { min: -body.maxHeel, max: body.maxHeel, step: body.heelStep };
-      const newTable = new CorrectionTable(name, row, col, options.stability || 7);
+      const newTable = new CorrectionTable(name, row, col, correctionDriftRateToProcessNoiseRate(options.correctionDriftRate));
       newTable.setDisplayAttributes({ label: name }); // Table2D API unchanged
       saveTable(newTable, path.join(app.getDataDirPath(), name + '.json'));
       if (isRunning) swapTable(newTable);
@@ -484,12 +564,25 @@ module.exports = function (app) {
         return res.status(400).json({ error: 'Invalid table name' });
       const filePath = path.join(app.getDataDirPath(), name + '.json');
       const fileData = Table2D.readFromFile(filePath);
-      if (!fileData) return res.status(404).json({ error: `Table '${name}' not found` });
-      const loadedTable = CorrectionTable.fromJSON(fileData, options.stability || 7);
-      loadedTable.setDisplayAttributes({ label: name }); // Table2D API unchanged
-      if (isRunning) swapTable(loadedTable);
-      saveTableName(name);
-      res.json({ name });
+      if (!fileData) {
+        if (!fs.existsSync(filePath)) return res.status(404).json({ error: `Table '${name}' not found` });
+        const message = `Correction table load rejected for ${name}: file could not be read`;
+        app.error(message);
+        app.debug(message);
+        return res.status(422).json({ error: message });
+      }
+      try {
+        const loadedTable = CorrectionTable.fromJSON(fileData, correctionDriftRateToProcessNoiseRate(options.correctionDriftRate));
+        loadedTable.setDisplayAttributes({ label: name }); // Table2D API unchanged
+        if (isRunning) swapTable(loadedTable);
+        saveTableName(name);
+        res.json({ name });
+      } catch (err) {
+        const message = `Correction table load rejected for ${name}: ${err.message}`;
+        app.error(message);
+        app.debug(message);
+        res.status(422).json({ error: message });
+      }
     });
 
     // Copy active table under a new name and hot-swap to it
@@ -501,7 +594,7 @@ module.exports = function (app) {
         return res.status(400).json({ error: 'Name must be alphanumeric (underscores and hyphens allowed)' });
       const data = table.toJSON();
       data.id = newName;
-      const copiedTable = CorrectionTable.fromJSON(data, options.stability || 7);
+      const copiedTable = CorrectionTable.fromJSON(data, correctionDriftRateToProcessNoiseRate(options.correctionDriftRate));
       copiedTable.setDisplayAttributes({ label: newName }); // Table2D API unchanged
       saveTable(copiedTable, path.join(app.getDataDirPath(), newName + '.json'));
       swapTable(copiedTable);
@@ -520,7 +613,7 @@ module.exports = function (app) {
       }
       const newRow = { min: 0, max: body.maxSpeed, step: body.speedStep };
       const newCol = { min: -body.maxHeel, max: body.maxHeel, step: body.heelStep };
-      const resized = CorrectionTable.resampleFromJSON(table.toJSON(), newRow, newCol, options.stability || 7, 1e-4);
+      const resized = CorrectionTable.resampleFromJSON(table.toJSON(), newRow, newCol, correctionDriftRateToProcessNoiseRate(options.correctionDriftRate), 1e-4);
       resized.setDisplayAttributes({ label: resized.id }); // Table2D API unchanged
       saveTable(resized, path.join(app.getDataDirPath(), resized.id + '.json'));
       swapTable(resized);
@@ -545,6 +638,9 @@ module.exports = function (app) {
     const tableFilePath = path.join(app.getDataDirPath(), tableName + '.json');
     table = loadTable(options, tableFilePath);
     minSpeed = table.step[0];
+    calculationIntervalSmoother = new ExponentialSmoother({ tau: 10 });
+    lastCalculationTime = null;
+    lastLearningAttemptTime = null;
 
     //#region Handler and Polar Initialization
     const { SmootherClass, smootherOptions } = resolveSmootherConfig();
@@ -581,6 +677,10 @@ module.exports = function (app) {
 
     navigationStateHandler = new MessageHandler(app, plugin.id, 'navigationState');
     navigationStateHandler.configure('navigation.state');
+    // navigation.state is an event path — it is only sent on transition, not on a regular
+    // period — so the generic telemetry staleness timer (which would otherwise mark it
+    // stale, and therefore not `ready`, within a few seconds of silence) does not apply.
+    navigationStateHandler.stalePeriod = 0;
     navigationStateHandler.onDelta = () => {
       handleNavigationStateDelta();
     };
@@ -617,7 +717,6 @@ module.exports = function (app) {
     });
     noCurrent.xSmoother.reset(0,0);
     noCurrent.ySmoother.reset(0,0);
-    PolarSmoother.send(app, plugin.id, [noCurrent]);
 
     MessageHandler.setMeta(app, plugin.id, 'navigation.leewayAngle', {
       units: 'rad',
@@ -632,23 +731,34 @@ module.exports = function (app) {
       app, pluginId: plugin.id,
       id: 'boatSpeed',
       path: 'navigation.speedThroughWater',
-      subscribe: true,
+      subscribe: false,
       SmootherClass,
       smootherOptions,
       onDelta: () => {
         clearLifecycleWarning('boatSpeed.smoothed');
+        const now = Date.now();
+        if (lastCalculationTime !== null) {
+          const interval = (now - lastCalculationTime) / 1000;
+          if (interval > 0) calculationIntervalSmoother.add(interval);
+        }
+        lastCalculationTime = now;
         // Drain any pending option changes before calculating
         if (Object.keys(changedOptions).length) applyOptionChanges();
 
         const learningMode = evaluateLearningMode({
           options,
-          navigationState: buildNavigationStateStatus(navigationStateHandler, options.suspendLearningOnNavigationState),
+          vesselMoving: isVesselMoving({
+            sogMagnitude: smoothedGroundSpeed?.magnitude,
+            speedThreshold: minSpeed,
+            navigationStateHandler,
+            gateEnabled: options.suspendLearningOnNavigationState
+          }),
           stabilizingUntil: learningStabilizingUntil,
           stabilizingReason: learningStabilizingReason,
           now: Date.now()
         });
 
-        const wellUnderway = learningMode.state !== 'stabilizing';
+        const wellUnderway = Date.now() >= learningStabilizingUntil;
         setStatus(learningMode.state === 'stabilizing' ? 'Stabilizing' : 'Running');
         if (options.estimateBoatSpeed) correct(wellUnderway);
         updateTable();
@@ -750,11 +860,6 @@ module.exports = function (app) {
     reportFull.addAttitude(smoothedAttitude);
     reportFull.addDelta(smoothedBoatSpeed);
     reportFull.addPolar(smoothedGroundSpeed);
-    // smoothedCurrent is already added by the estimateBoatSpeed block when that is on;
-    // only add it here when estimateBoatSpeed is off, to avoid a duplicate entry.
-    if (options.assumeCurrent && !options.estimateBoatSpeed) {
-      reportFull.addPolar(smoothedCurrent);
-    }
     reportFull.addTable(table);
 
     //#endregion
@@ -766,6 +871,7 @@ module.exports = function (app) {
     lastNavigationStateValue = normalizeNavigationState(navigationStateHandler?.value);
     resetLearningStabilization('startup', LONG_STABILIZING_MS);
     setStatus('Running');
+    smoothedBoatSpeed.subscribe();
     app.debug("Running");
 
   }
@@ -841,10 +947,17 @@ module.exports = function (app) {
     if (options.sogFallback && rawGroundSpeed.ready && rawBoatSpeed.ready && rawBoatSpeed.value === 0 && rawGroundSpeed.magnitude >= minSpeed) {
         correctedBoatSpeed.setVectorValue({ x: rawGroundSpeed.magnitude, y: 0 });
     }
-    else if (rawAttitude.ready) {
+    else if (rawAttitude.ready && Number.isFinite(rawAttitude.value?.roll)) {
+      clearLifecycleWarning('attitude.roll');
       if (correctedBoatSpeed.magnitude > 0) {
         const { correction, variance } = table.getCorrection(correctedBoatSpeed.magnitude, rawAttitude.value?.roll);
-        const leewayValid = isLeewayValid(correctedBoatSpeed.magnitude, minSpeed, navigationStateHandler);
+        const vesselMoving = isVesselMoving({
+          sogMagnitude: rawGroundSpeed?.magnitude,
+          speedThreshold: minSpeed,
+          navigationStateHandler,
+          gateEnabled: options.suspendLearningOnNavigationState
+        });
+        const leewayValid = isLeewayValid(correctedBoatSpeed.magnitude, minSpeed, vesselMoving);
         speedCorrection.setVectorValue(
           { x: correction.x, y: leewayValid ? correction.y : 0 },
           { x: variance.x, y: leewayValid ? variance.y : 0 }
@@ -877,23 +990,33 @@ module.exports = function (app) {
         }
       }
     }
-    // Implicit fallback: attitude not ready — correctedBoatSpeed = raw STW, no correction
+    // Implicit fallback: attitude not ready or missing roll — correctedBoatSpeed = raw STW, no correction
+    else if (rawAttitude.ready) {
+      setLifecycleWarning('attitude.roll', 'incomplete', 'navigation.attitude.roll');
+    }
 
-    PolarSmoother.send(app, plugin.id, [smoothedCurrent, smoothedResidual]);
+    PolarSmoother.send(app, plugin.id, [smoothedCurrent]);
 
     Polar.send(app, plugin.id, [correctedBoatSpeed]);
   }
 
   /**
    * Updates the correction table from the current smoothed inputs.
-   * Reads assumeCurrent and minSpeed from module-level options/state;
+    * Reads minSpeed from module-level state;
    * silently returns if any required input is not yet ready.
    */
   function updateTable() {
+    const now = Date.now();
+    if (lastLearningAttemptTime !== null && now - lastLearningAttemptTime < getLearningIntervalMs(options)) return;
     lrnBoatSpeed.setVectorValue({ x: smoothedBoatSpeed.value, y: 0 }, { x: smoothedBoatSpeed.variance ?? 0, y: 0 });
     const learningMode = evaluateLearningMode({
       options,
-      navigationState: buildNavigationStateStatus(navigationStateHandler, options.suspendLearningOnNavigationState),
+      vesselMoving: isVesselMoving({
+        sogMagnitude: smoothedGroundSpeed.magnitude,
+        speedThreshold: minSpeed,
+        navigationStateHandler,
+        gateEnabled: options.suspendLearningOnNavigationState
+      }),
       stabilizingUntil: learningStabilizingUntil,
       stabilizingReason: learningStabilizingReason,
       now: Date.now()
@@ -902,13 +1025,11 @@ module.exports = function (app) {
       learningMode.state = 'suspended';
       learningMode.reason = 'cog_override';
     }
-    const inputsReady = smoothedAttitude.ready && smoothedBoatSpeed.ready && smoothedHeading.ready && smoothedGroundSpeed.ready;
-    const currentReady = !options.assumeCurrent || smoothedCurrent.ready;
+    const inputsReady = smoothedAttitude.ready && Number.isFinite(smoothedAttitude.value?.roll)
+      && smoothedBoatSpeed.ready && smoothedHeading.ready && smoothedGroundSpeed.ready;
     const observationGate = evaluateObservationGate({
       learningMode,
       inputsReady,
-      assumeCurrent: options.assumeCurrent,
-      currentReady,
       stw: smoothedBoatSpeed.value,
       sog: smoothedGroundSpeed.magnitude,
       speedThreshold: minSpeed
@@ -916,12 +1037,22 @@ module.exports = function (app) {
 
     if (observationGate.state !== 'pending') {
       if (observationGate.state === 'invalid') {
+        setObservationStatus('rejected', observationGate.reason);
         resetLearningStabilization('observation_reset', getShortStabilizingMs(options));
       }
       return;
     }
 
-    table.update(smoothedBoatSpeed.value, smoothedAttitude.value?.roll, smoothedGroundSpeed, options.assumeCurrent ? smoothedCurrent : noCurrent, lrnBoatSpeed, smoothedHeading.value);
+    lastLearningAttemptTime = now;
+    table.update(
+      smoothedBoatSpeed.value,
+      smoothedAttitude.value?.roll,
+      smoothedGroundSpeed,
+      noCurrent,
+      lrnBoatSpeed,
+      smoothedHeading.value,
+      smoothedHeading.variance
+    );
     if (table.lastUpdateResult === 'accepted') {
       setObservationStatus('accepted', 'accepted');
     } else if (table.lastUpdateResult === 'rejected') {
@@ -935,39 +1066,55 @@ module.exports = function (app) {
    * If the file exists it is deserialized; otherwise a new table is created
    * with default dimensions and saved to disk.
    *
-   * @param {Object} options - Plugin options (stability, tableName, and dimension defaults).
+  * @param {Object} options - Plugin options (correctionDriftRate, tableName, and dimension defaults).
    * @param {string} filePath - Absolute path of the JSON file to read.
    * @returns {CorrectionTable} The loaded or newly created CorrectionTable instance.
    */
   function loadTable(options, filePath) {
-    const stability = (options.stability !== undefined) ? options.stability : 6;
+    const processNoiseRate = correctionDriftRateToProcessNoiseRate(options.correctionDriftRate);
     let fileData = Table2D.readFromFile(filePath);
-    let table;
     if (fileData) {
-      table = CorrectionTable.fromJSON(fileData, stability);
-      app.debug("Correction table loaded: " + (fileData.id || filePath));
-    } else if (fs.existsSync(filePath)) {
-      // File is present but could not be read — transient lock or parse error. Retry once.
-      app.error(`Correction table file exists but could not be read, retrying: ${filePath}`);
-      fileData = Table2D.readFromFile(filePath);
-      if (fileData) {
-        table = CorrectionTable.fromJSON(fileData, stability);
-        app.debug("Correction table loaded on retry: " + (fileData.id || filePath));
-      } else {
-        app.error(`Correction table retry failed — starting with empty table. Disk file preserved: ${filePath}`);
-        const name = options.tableName || 'correctionTable';
-        const row = { min: 0, max: SI.fromKnots(DEFAULT_DIMS.maxSpeed), step: SI.fromKnots(DEFAULT_DIMS.speedStep) };
-        const col = { min: -SI.fromDegrees(DEFAULT_DIMS.maxHeel), max: SI.fromDegrees(DEFAULT_DIMS.maxHeel), step: SI.fromDegrees(DEFAULT_DIMS.heelStep) };
-        table = new CorrectionTable(name, row, col, stability);
+      try {
+        const migration = migrateCorrectionTableData(fileData, {
+          filePath,
+          debug: message => app.debug(message)
+        });
+        const table = CorrectionTable.fromJSON(migration.data, processNoiseRate);
+        table.setDisplayAttributes({ label: table.id }); // Table2D API unchanged
+        if (migration.migrated) saveMigratedTable(table, filePath);
+        app.debug("Correction table loaded: " + (fileData.id || filePath));
+        return table;
+      } catch (err) {
+        return recoverTable(`could not deserialize ${filePath}: ${err.message}`);
       }
-    } else {
-      const name = options.tableName || 'correctionTable';
-      const row = { min: 0, max: SI.fromKnots(DEFAULT_DIMS.maxSpeed), step: SI.fromKnots(DEFAULT_DIMS.speedStep) };
-      const col = { min: -SI.fromDegrees(DEFAULT_DIMS.maxHeel), max: SI.fromDegrees(DEFAULT_DIMS.maxHeel), step: SI.fromDegrees(DEFAULT_DIMS.heelStep) };
-      table = new CorrectionTable(name, row, col, stability);
-      app.debug("Correction table created: " + name);
     }
-    table.setDisplayAttributes({ label: table.id }); // Table2D API unchanged
+
+    if (fs.existsSync(filePath)) {
+      return recoverTable(`could not read ${filePath}`);
+    }
+
+    const table = createDefaultTable(options.tableName || 'correctionTable', processNoiseRate);
+    app.debug("Correction table created: " + table.id);
+    return table;
+  }
+
+  function createDefaultTable(name, processNoiseRate = DEFAULT_PROCESS_NOISE_RATE) {
+    const row = { min: 0, max: SI.fromKnots(DEFAULT_DIMS.maxSpeed), step: SI.fromKnots(DEFAULT_DIMS.speedStep) };
+    const col = { min: -SI.fromDegrees(DEFAULT_DIMS.maxHeel), max: SI.fromDegrees(DEFAULT_DIMS.maxHeel), step: SI.fromDegrees(DEFAULT_DIMS.heelStep) };
+    const table = new CorrectionTable(name, row, col, processNoiseRate);
+    table.setDisplayAttributes({ label: name }); // Table2D API unchanged
+    return table;
+  }
+
+  function recoverTable(reason) {
+    const recoveryName = `correctionTable-${new Date().toISOString().slice(0, 10)}`;
+    const recoveryPath = path.join(app.getDataDirPath(), recoveryName + '.json');
+    const table = createDefaultTable(recoveryName, correctionDriftRateToProcessNoiseRate(options.correctionDriftRate));
+    const message = `Correction table recovery: ${reason}; loaded empty table ${recoveryName}`;
+    app.error(message);
+    app.debug(message);
+    saveTableSync(table, recoveryPath);
+    saveTableName(recoveryName);
     return table;
   }
 
@@ -995,6 +1142,18 @@ module.exports = function (app) {
     }
   }
 
+  function saveMigratedTable(correctionTable, filePath) {
+    const temporaryPath = `${filePath}.migration-${process.pid}-${Date.now()}.tmp`;
+    try {
+      fs.writeFileSync(temporaryPath, JSON.stringify(correctionTable.toJSON(), null, 2));
+      fs.renameSync(temporaryPath, filePath);
+      app.debug(`Correction table migrated to schema v2: ${filePath}`);
+    } catch (err) {
+      try { fs.unlinkSync(temporaryPath); } catch {}
+      app.debug(`Correction table migration could not be persisted for ${filePath}: ${err.message}`);
+    }
+  }
+
   /**
    * Returns true if every cell in the table has N === 0 (no learned data).
    * Used to guard against overwriting a good on-disk file with an empty table.
@@ -1024,7 +1183,7 @@ module.exports = function (app) {
           const filePath = path.join(app.getDataDirPath(), table.id + '.json');
           const fileData = Table2D.readFromFile(filePath);
           if (fileData) {
-            const reloaded = CorrectionTable.fromJSON(fileData, options.stability || 7);
+            const reloaded = CorrectionTable.fromJSON(fileData, correctionDriftRateToProcessNoiseRate(options.correctionDriftRate));
             reloaded.setDisplayAttributes({ label: reloaded.id });
             if (!isTableEmpty(reloaded)) {
               swapTable(reloaded);
@@ -1033,8 +1192,8 @@ module.exports = function (app) {
           }
         }
       }
-      // All other keys (sogFallback, estimateBoatSpeed, assumeCurrent,
-      // stability, smootherClass, etc.) are read
+      // All other keys (sogFallback, estimateBoatSpeed, correctionDriftRate,
+      // and smootherTimeSpan) are read
       // directly from options.* so no extra action needed.
       if (key === 'estimateBoatSpeed' && !value && correctedBoatSpeed) {
         Polar.clear(app, plugin.id, [correctedBoatSpeed]);
@@ -1044,10 +1203,13 @@ module.exports = function (app) {
       delete changedOptions[key];
     }
 
-    // Hot-apply smoother class / parameter changes to all user-tuned smoothers.
-    // (noCurrent and smoothedCurrent keep their own fixed Kalman settings.)
-    const SMOOTHER_KEYS = ['smootherClass', 'smootherTau', 'smootherTimeSpan', 'smootherSteadyState'];
-    if (changedKeys.some(k => SMOOTHER_KEYS.includes(k))) {
+    if (changedKeys.includes('correctionDriftRate') && table) {
+      table.setProcessNoiseRate(correctionDriftRateToProcessNoiseRate(options.correctionDriftRate));
+    }
+
+    // Hot-apply the learning window to all user-tuned smoothers.
+    if (changedKeys.includes('smootherTimeSpan')) {
+      options.smootherTimeSpan = getSmoothingWindowSeconds(options);
       const { SmootherClass: SC, smootherOptions: so } = resolveSmootherConfig();
       for (const s of [smoothedHeading, smoothedBoatSpeed, smoothedGroundSpeed]) {
         if (s) { s.setSmootherClass(SC); s.setSmootherOptions(so); }
@@ -1063,13 +1225,18 @@ module.exports = function (app) {
 module.exports._test = {
   normalizeNavigationState,
   getShortStabilizingMs,
+  getSmoothingWindowSeconds,
+  getLearningIntervalMs,
+  correctionDriftRateToProcessNoiseRate,
+  legacyStabilityToCorrectionDriftRate,
+  migrateCorrectionTableData,
+  isVesselMoving,
   evaluateLearningMode,
   isCogOverrideActive,
   isLeewayValid,
   evaluateObservationGate,
   getDerivedObservationStatus,
   buildNavigationStateStatus,
-  ALWAYS_BLOCKING_NAVIGATION_STATES,
-  OPTIONAL_BLOCKING_NAVIGATION_STATES,
+  NOT_MOVING_NAVIGATION_STATES,
   LONG_STABILIZING_MS,
 };