speedandcurrent 2.3.4 → 2.4.0

package/correctionTable.js

@@ -1,6 +1,20 @@
 const { Table2D} = require('signalkutilities');
 const { KalmanFilter, State } = require('kalman-filter');
 
+const MAX_INTERPOLATION_DISTANCE = 2.5;
+const MIN_CELL_INDEX = 0;
+const Q_RECALCULATION_INTERVAL = 600;
+const MIN_Q_PAIR_COUNT = 3;
+const DEFAULT_Q = 0.002;
+const COVARIANCE_FLOOR = 1e-9;
+const MAX_AGING_SECONDS = 90 * 24 * 60 * 60;
+const SECONDS_PER_MONTH = 30 * 24 * 60 * 60;
+const KNOT_TO_MPS = 0.5144444444444444;
+const DEFAULT_CORRECTION_DRIFT_RATE = 0.3;
+const DEFAULT_PROCESS_NOISE_RATE = (DEFAULT_CORRECTION_DRIFT_RATE * KNOT_TO_MPS) ** 2 / SECONDS_PER_MONTH;
+const OBSERVATION_STATE_PROJECTION = [[1, 0], [0, 1]]; // observation matrix H
+const DYNAMIC_TRANSITION = [[1, 0], [0, 1]]; // state transition matrix F
+
 // Module-level helpers — avoids creating new Function objects on every Kalman update call
 function _rotateValue(cos, sin, vector) {
   return [
@@ -11,8 +25,49 @@ function _rotateValue(cos, sin, vector) {
 
 function _rotateVariance(cos, sin, vector) {
   return [
-    [vector[0] * cos ** 2 + vector[1] * sin ** 2, (vector[0] - vector[1]) * cos * sin],
-    [(vector[0] - vector[1]) * cos * sin,          vector[0] * sin ** 2 + vector[1] * cos ** 2]
+    [vector[0] * cos ** 2 + vector[1] * sin ** 2, (vector[1] - vector[0]) * cos * sin],
+    [(vector[1] - vector[0]) * cos * sin,          vector[0] * sin ** 2 + vector[1] * cos ** 2]
+  ];
+}
+
+function _addHeadingVariance(covariance, groundVector, currentVector, headingVariance) {
+  const variance = Number.isFinite(headingVariance) && headingVariance >= 0 ? headingVariance : 0;
+  if (variance === 0) return covariance;
+
+  const ux = groundVector[0] - currentVector[0];
+  const uy = groundVector[1] - currentVector[1];
+  const jx = uy;
+  const jy = -ux;
+  return [
+    [covariance[0][0] + jx * variance * jx, covariance[0][1] + jx * variance * jy],
+    [covariance[1][0] + jy * variance * jx, covariance[1][1] + jy * variance * jy]
+  ];
+}
+
+function _median(values) {
+  const sorted = values.filter(Number.isFinite).sort((a, b) => a - b);
+  if (sorted.length === 0) return null;
+  const middle = Math.floor(sorted.length / 2);
+  return sorted.length % 2 === 0
+    ? (sorted[middle - 1] + sorted[middle]) / 2
+    : sorted[middle];
+}
+
+function _symmetricCovariance(covariance, diagonalInflation = 0) {
+  if (!Array.isArray(covariance) || !Array.isArray(covariance[0]) || !Array.isArray(covariance[1])) return null;
+  const xx = covariance[0][0] + diagonalInflation;
+  const yy = covariance[1][1] + diagonalInflation;
+  const xy = (covariance[0][1] + covariance[1][0]) / 2;
+  if (![xx, xy, yy].every(Number.isFinite)) return null;
+  return [[Math.max(xx, COVARIANCE_FLOOR), xy], [xy, Math.max(yy, COVARIANCE_FLOOR)]];
+}
+
+function _inverse2(matrix) {
+  const det = matrix[0][0] * matrix[1][1] - matrix[0][1] * matrix[1][0];
+  if (!Number.isFinite(det) || det <= COVARIANCE_FLOOR ** 2) return null;
+  return [
+    [matrix[1][1] / det, -matrix[0][1] / det],
+    [-matrix[1][0] / det, matrix[0][0] / det]
   ];
 }
 
@@ -23,9 +78,10 @@ class CorrectionTable extends Table2D{
 
 
 
-  static fromJSON(data, stability) {
-    const table = new CorrectionTable(data.id, data.row, data.col, stability);
-    table.table = data.table.map(row => row.map(cellData => CorrectionEstimator.fromJSON(cellData, stability)));
+  static fromJSON(data, processNoiseRate = DEFAULT_PROCESS_NOISE_RATE) {
+    const table = new CorrectionTable(data.id, data.row, data.col, processNoiseRate);
+    table.table = data.table.map(row => row.map(cellData => CorrectionEstimator.fromJSON(cellData, processNoiseRate)));
+    table.calculateQ();
     return table;
   }
 
@@ -38,12 +94,12 @@ class CorrectionTable extends Table2D{
    * @param {CorrectionTable} oldTable - Source table to sample from
    * @param {{min:number,max:number,step:number}} newRow - New speed axis definition (SI units)
    * @param {{min:number,max:number,step:number}} newCol - New heel axis definition (SI units)
-   * @param {number} [stability=5] - Stability passed to new table filter model
+  * @param {number} [processNoiseRate=DEFAULT_PROCESS_NOISE_RATE] - SI process-noise rate
    * @param {number} [varianceFloor=1e-4] - Floor applied to cov[0][0] and cov[1][1]
    * @returns {CorrectionTable}
    */
-  static resample(oldTable, newRow, newCol, stability = 5, varianceFloor = 1e-4) {
-    const newTable = new CorrectionTable(oldTable.id, newRow, newCol, stability);
+  static resample(oldTable, newRow, newCol, processNoiseRate = DEFAULT_PROCESS_NOISE_RATE, varianceFloor = 1e-4) {
+    const newTable = new CorrectionTable(oldTable.id, newRow, newCol, processNoiseRate);
 
     const nRows = Math.round((newRow.max - newRow.min) / newRow.step) + 1;
     const nCols = Math.round((newCol.max - newCol.min) / newCol.step) + 1;
@@ -58,7 +114,8 @@ class CorrectionTable extends Table2D{
         const mean = [[(correction?.x ?? 0)], [(correction?.y ?? 0)]];
         const covXX = Math.max(Number.isFinite(variance?.x) ? variance.x : 0, varianceFloor);
         const covYY = Math.max(Number.isFinite(variance?.y) ? variance.y : 0, varianceFloor);
-        const covariance = [[covXX, 0], [0, covYY]];
+        const covXY = Number.isFinite(variance?.covariance?.[0]?.[1]) ? variance.covariance[0][1] : 0;
+        const covariance = [[covXX, covXY], [covXY, covYY]];
 
         // Decide initialization index based on coverage/support from old table
         const inBounds = (
@@ -89,64 +146,142 @@ class CorrectionTable extends Table2D{
   /**
    * Convenience to resample from serialized JSON table data
    */
-  static resampleFromJSON(data, newRow, newCol, stability = 5, varianceFloor = 1e-4) {
-    const oldTable = CorrectionTable.fromJSON(data, stability);
-    return CorrectionTable.resample(oldTable, newRow, newCol, stability, varianceFloor);
+  static resampleFromJSON(data, newRow, newCol, processNoiseRate = DEFAULT_PROCESS_NOISE_RATE, varianceFloor = 1e-4) {
+    const oldTable = CorrectionTable.fromJSON(data, processNoiseRate);
+    return CorrectionTable.resample(oldTable, newRow, newCol, processNoiseRate, varianceFloor);
   }
 
-  constructor(id, row, col, stability=5) {
-    super(id, row, col, CorrectionEstimator, CorrectionEstimator.getFilterModel(stability));
+  constructor(id, row, col, processNoiseRate = DEFAULT_PROCESS_NOISE_RATE) {
+    super(id, row, col, CorrectionEstimator, CorrectionEstimator.getFilterModel(processNoiseRate));
+    // Table2D persists the constructor param verbatim as `this.parameters`. The live filter model
+    // carries a runtime callback for observation.covariance, which JSON.stringify would silently
+    // drop. Replace it with a serializable descriptor so persisted files stay honest.
+    this.parameters = CorrectionEstimator.getModelDescriptor(processNoiseRate);
     this.lastUpdatedCell = null;
     this.lastUpdateResult = null;
     this.neighbours = [];
+    this.q = DEFAULT_Q;
+    this.qPairCount = 0;
+    this.qEstimate = null;
+    this.qSource = 'fallback';
+    this.acceptedObservationsSinceQ = 0;
+    for (const rowCells of this.table) {
+      for (const cell of rowCells) cell.setProcessNoiseRate(processNoiseRate);
+    }
+  }
+
+  setProcessNoiseRate(processNoiseRate) {
+    this.parameters = CorrectionEstimator.getModelDescriptor(processNoiseRate);
+    for (const rowCells of this.table) {
+      for (const cell of rowCells) cell.setProcessNoiseRate(processNoiseRate);
+    }
   }
   
-  update(speed, heel, groundSpeed, current, boatSpeed, heading) {
+  update(speed, heel, groundSpeed, current, boatSpeed, heading, headingVariance) {
     const cell = this.getCell(speed, heel);
-    const accepted = cell?.update(groundSpeed, current, boatSpeed, heading);
+    const accepted = cell?.update(groundSpeed, current, boatSpeed, heading, headingVariance);
     this.lastUpdatedCell = cell;
     this.lastUpdateResult = accepted === true ? 'accepted' : 'rejected';
+    if (accepted === true) {
+      this.acceptedObservationsSinceQ++;
+      if (this.acceptedObservationsSinceQ >= Q_RECALCULATION_INTERVAL) {
+        this.calculateQ();
+      }
+    }
+    return accepted === true;
   }
 
-  getCorrection(speed, heel) {
-    this.neighbours = this.findClosest(speed, heel, 5);
-    if (this.neighbours.length == 0) return { correction: {x: 0, y: 0}, variance: null };
-    // Compute the correction and variance from the neighbours
-    let x = 0;
-    let y = 0;
-    let varX = 0;
-    let varY = 0;
-    let totalWeight = 0;
-    for (const neighbour of this.neighbours) {
-      const { cell:correction, dist } = neighbour;
-      if (correction.N > 0) {
-        const weight = 1 / (dist + 1e-6); 
-        neighbour.normWeight = weight;
-        x += correction.x * weight;
-        y += correction.y * weight;
-        varX += correction.covariance[0][0] * weight ** 2;
-        varY += correction.covariance[1][1] * weight ** 2;
-        totalWeight += weight;
+  calculateQ() {
+    const pairEstimates = [];
+    for (let row = 0; row < this.n[0]; row++) {
+      for (let col = 0; col < this.n[1]; col++) {
+        const first = this.table[row][col];
+        if (first.N <= MIN_CELL_INDEX) continue;
+        for (const [rowOffset, colOffset] of [[1, 0], [0, 1]]) {
+          const second = this.table[row + rowOffset]?.[col + colOffset];
+          if (!second || second.N <= MIN_CELL_INDEX) continue;
+            const firstCovariance = _symmetricCovariance(first.covariance);
+            const secondCovariance = _symmetricCovariance(second.covariance);
+          if (!firstCovariance || !secondCovariance) continue;
+          const dx = first.x - second.x;
+          const dy = first.y - second.y;
+          const uncertainty = firstCovariance[0][0] + firstCovariance[1][1]
+            + secondCovariance[0][0] + secondCovariance[1][1];
+          pairEstimates.push((dx * dx + dy * dy - uncertainty) / 2);
+        }
       }
     }
-    if (totalWeight > 0) {
-      for (const neighbour of this.neighbours) {
-        neighbour.normWeight /= totalWeight;
+
+    const estimate = _median(pairEstimates);
+    this.qPairCount = pairEstimates.length;
+    this.qEstimate = Number.isFinite(estimate) ? estimate : null;
+    if (pairEstimates.length >= MIN_Q_PAIR_COUNT && estimate > 0) {
+      this.q = estimate;
+      this.qSource = 'derived';
+    } else {
+      this.q = DEFAULT_Q;
+      this.qSource = 'fallback';
+    }
+    this.acceptedObservationsSinceQ = 0;
+    return this.q;
+  }
+
+  _findEligibleNeighbours(speed, heel) {
+    const neighbours = [];
+    for (let row = 0; row < this.n[0]; row++) {
+      for (let col = 0; col < this.n[1]; col++) {
+        const cell = this.table[row][col];
+        cell.effectiveVariance = null;
+        if (cell.N <= MIN_CELL_INDEX) continue;
+        const rowDistance = (this.indexToValue(row, 0) - speed) / this.step[0];
+        const colDistance = (this.indexToValue(col, 1) - heel) / this.step[1];
+        const dist = Math.sqrt(rowDistance * rowDistance + colDistance * colDistance);
+        if (Number.isFinite(dist) && dist <= MAX_INTERPOLATION_DISTANCE) {
+          neighbours.push({ cell, row, col, dist, normWeight: 0 });
+        }
       }
     }
+    return neighbours.sort((a, b) => a.dist - b.dist);
+  }
 
-    if (totalWeight === 0) return { correction: { x: 0, y: 0 }, variance: { x: 0, y: 0 } };
+  getCorrection(speed, heel) {
+    this.neighbours = this._findEligibleNeighbours(speed, heel);
+    const emptyResult = { correction: { x: 0, y: 0 }, variance: { x: 0, y: 0, covariance: [[0, 0], [0, 0]] } };
+    if (this.neighbours.length === 0) return emptyResult;
 
-    // Compute the final correction and variance
-    // Variance of a weighted mean: Σ(w²·var_i) / (Σw)²
-    const tw2 = totalWeight * totalWeight;
-    x /= totalWeight;
-    y /= totalWeight;
-    varX /= tw2;
-    varY /= tw2;
-    this.totalWeight = totalWeight;
+    const precision = [[0, 0], [0, 0]];
+    const information = [0, 0];
+    let totalScalarWeight = 0;
+    for (const neighbour of this.neighbours) {
+      const effectiveCovariance = _symmetricCovariance(neighbour.cell.covariance, this.q * neighbour.dist ** 2);
+      const cellPrecision = effectiveCovariance && _inverse2(effectiveCovariance);
+      if (!cellPrecision) continue;
+
+      neighbour.effectiveCovariance = effectiveCovariance;
+      neighbour.cell.effectiveVariance = effectiveCovariance[0][0] + effectiveCovariance[1][1];
+      neighbour.scalarWeight = cellPrecision[0][0] + cellPrecision[1][1];
+      totalScalarWeight += neighbour.scalarWeight;
+      precision[0][0] += cellPrecision[0][0];
+      precision[0][1] += cellPrecision[0][1];
+      precision[1][0] += cellPrecision[1][0];
+      precision[1][1] += cellPrecision[1][1];
+      information[0] += cellPrecision[0][0] * neighbour.cell.x + cellPrecision[0][1] * neighbour.cell.y;
+      information[1] += cellPrecision[1][0] * neighbour.cell.x + cellPrecision[1][1] * neighbour.cell.y;
+    }
 
-    return { correction: { x, y }, variance: { x: varX, y: varY } };
+    const covariance = _inverse2(precision);
+    if (!covariance) return emptyResult;
+    for (const neighbour of this.neighbours) {
+      neighbour.normWeight = totalScalarWeight > 0 && Number.isFinite(neighbour.scalarWeight)
+        ? neighbour.scalarWeight / totalScalarWeight
+        : 0;
+    }
+    const x = covariance[0][0] * information[0] + covariance[0][1] * information[1];
+    const y = covariance[1][0] * information[0] + covariance[1][1] * information[1];
+    return {
+      correction: { x, y },
+      variance: { x: covariance[0][0], y: covariance[1][1], covariance }
+    };
   }
   
   report() {
@@ -178,6 +313,9 @@ class CorrectionTable extends Table2D{
           cellReport.factor = factor;
           cellReport.leeway = leeway;
           cellReport.trace = trace;
+          cellReport.effectiveVariance = Number.isFinite(correction.effectiveVariance)
+            ? correction.effectiveVariance
+            : null;
           cellReport.speedBin = speedBin;
           cellReport.heelBin = heelBin;
           // Mark selected if this is the last updated cell
@@ -194,10 +332,26 @@ class CorrectionTable extends Table2D{
         })
       ),
       displayAttributes: this.displayAttributes,
+      q: this.q,
+      qPairCount: this.qPairCount,
+      qEstimate: this.qEstimate,
+      qSource: this.qSource,
       lastUpdateResult: this.lastUpdateResult ?? null
     };
   }
 
+  toJSON() {
+    return {
+      schemaVersion: 2,
+      id: this.id,
+      row: { min: this.min[0], max: this.max[0], step: this.step[0] },
+      col: { min: this.min[1], max: this.max[1], step: this.step[1] },
+      parameters: this.parameters,
+      table: this.table.map(row => row.map(cell => cell.toJSON())),
+      displayAttributes: this.displayAttributes
+    };
+  }
+
 }
 
 class CorrectionEstimator {
@@ -205,22 +359,45 @@ class CorrectionEstimator {
    * Represents a Kalman correction at a cell in a correction table
    */
 
-  static fromJSON(data, stability) {
-    const filterModel = CorrectionEstimator.getFilterModel(stability);
+  static fromJSON(data, processNoiseRate = DEFAULT_PROCESS_NOISE_RATE) {
+    const filterModel = CorrectionEstimator.getFilterModel(processNoiseRate);
     const estimator = new CorrectionEstimator(filterModel, data.state);
+    estimator.setProcessNoiseRate(processNoiseRate);
+    estimator.lastAcceptedAt = Number.isFinite(data.lastAcceptedAt) ? data.lastAcceptedAt : null;
     return estimator;
   }
 
-  static getFilterModel(stability = 5) {
+  static getFilterModel(processNoiseRate = DEFAULT_PROCESS_NOISE_RATE) {
+    return {
+      observation: {
+        stateProjection: OBSERVATION_STATE_PROJECTION,
+        // Measurement noise R is computed per observation in update() from live sensor
+        // variances (see observationCovariance below) and supplied to the filter through
+        // the `observationCovariance` option, rather than being a fixed matrix.
+        covariance: (options) => options.observationCovariance,
+        dimension: 2
+      },
+      dynamic: {
+        transition: DYNAMIC_TRANSITION, // state transition matrix F
+        covariance: [0, 0], // aging applies process noise explicitly from elapsed time
+      }
+    };
+  }
+
+  /**
+   * Serializable descriptor of the filter model, stored in table.parameters for persistence.
+   * Unlike getFilterModel(), this never contains functions.
+   */
+  static getModelDescriptor(processNoiseRate = DEFAULT_PROCESS_NOISE_RATE) {
     return {
       observation: {
-        stateProjection: [[1, 0], [0, 1]], // observation matrix H
-        covariance: [[1, 0], [0, 1]], //measurement noise R
+        stateProjection: OBSERVATION_STATE_PROJECTION,
+        covariance: 'per-observation', // actual R supplied at runtime by CorrectionEstimator.update()
         dimension: 2
       },
       dynamic: {
-        transition: [[1, 0], [0, 1]], // state transition matrix F
-        covariance: [1/10**stability, 1/10**stability],// process noise covariance matrix Q
+        transition: DYNAMIC_TRANSITION,
+        covariance: [processNoiseRate, processNoiseRate]
       }
     };
   }
@@ -228,12 +405,45 @@ class CorrectionEstimator {
   constructor(filterModel, initialState) {
     this.filter = new KalmanFilter(filterModel);
     this.filterState = null;
+    this.effectiveVariance = null;
+    this.processNoiseRate = Number.isFinite(filterModel?.dynamic?.covariance?.[0])
+      ? filterModel.dynamic.covariance[0]
+      : DEFAULT_PROCESS_NOISE_RATE;
+    this.lastAcceptedAt = null;
     if (initialState != null) {
       this.filterState = new State(initialState);
     }
   }
+
+  setProcessNoiseRate(processNoiseRate = DEFAULT_PROCESS_NOISE_RATE) {
+    this.processNoiseRate = Number.isFinite(processNoiseRate) && processNoiseRate >= 0
+      ? processNoiseRate
+      : DEFAULT_PROCESS_NOISE_RATE;
+    return this;
+  }
+
+  getAgedCovariance(now = Date.now()) {
+    if (this.filterState == null) return null;
+    const covariance = this.filterState.covariance.map(row => row.slice());
+    if (!Number.isFinite(this.lastAcceptedAt) || !Number.isFinite(now)) return covariance;
+    const elapsedSeconds = Math.max(0, (now - this.lastAcceptedAt) / 1000);
+    const effectiveDt = Math.min(elapsedSeconds, MAX_AGING_SECONDS);
+    const agedVariance = this.processNoiseRate * effectiveDt;
+    covariance[0][0] += agedVariance;
+    covariance[1][1] += agedVariance;
+    return covariance;
+  }
+
+  _agedState(now) {
+    if (this.filterState == null) return null;
+    return new State({
+      mean: this.filterState.mean.map(row => row.slice()),
+      covariance: this.getAgedCovariance(now),
+      index: this.filterState.index
+    });
+  }
   
-  update(groundSpeed, current, boatSpeed, heading) {
+  update(groundSpeed, current, boatSpeed, heading, headingVariance) {
     if(groundSpeed.xVariance == null || groundSpeed.yVariance == null ||
        current.xVariance == null || current.yVariance == null ||
        boatSpeed.xVariance == null || boatSpeed.yVariance == null ) {
@@ -256,13 +466,19 @@ class CorrectionEstimator {
     var currentCov = _rotateVariance(cosTheta, sinTheta, current.variance);
     var boatCov = [[boatSpeed.xVariance, 0], [0, boatSpeed.yVariance]];
 
-    const observationCovariance = [[
+    let observationCovariance = [[
       groundCov[0][0] + currentCov[0][0] + boatCov[0][0],
       groundCov[0][1] + currentCov[0][1] + boatCov[0][1]],
     [
       groundCov[1][0] + currentCov[1][0] + boatCov[1][0],
       groundCov[1][1] + currentCov[1][1] + boatCov[1][1]],
     ];
+    observationCovariance = _addHeadingVariance(
+      observationCovariance,
+      groundVector,
+      currentVector,
+      headingVariance
+    );
     // Mahalanobis distance check.
     // For empty cells (filterState === null) we use a diffuse prior — mean (0,0),
     // variance DIFFUSE_PRIOR_VAR — expressing "assume no correction needed, but
@@ -270,11 +486,13 @@ class CorrectionEstimator {
     // accepting it unconditionally, preventing a single outlier from locking a
     // cell at a bad value.
     const DIFFUSE_PRIOR_VAR = 1.0; // (m/s)² — rejects corrections > ~3 m/s from zero
-    const priorMean = this.filterState !== null
-      ? [this.filterState.mean[0][0], this.filterState.mean[1][0]]
+    const now = Date.now();
+    const agedState = this._agedState(now);
+    const priorMean = agedState !== null
+      ? [agedState.mean[0][0], agedState.mean[1][0]]
       : [0, 0];
-    const priorCov = this.filterState !== null
-      ? this.filterState.covariance
+    const priorCov = agedState !== null
+      ? agedState.covariance
       : [[DIFFUSE_PRIOR_VAR, 0], [0, DIFFUSE_PRIOR_VAR]];
     const inno = [observation[0] - priorMean[0], observation[1] - priorMean[1]];
     const S = [
@@ -293,13 +511,14 @@ class CorrectionEstimator {
                + inno[1] * (Sinv[1][0] * inno[0] + Sinv[1][1] * inno[1]);
       if (d2 > 9.21) return false;
     }
-    this.filterState = this.filter.filter({ previousCorrected: this.filterState, observation, observationCovariance });
+    this.filterState = this.filter.filter({ previousCorrected: agedState, observation, observationCovariance });
+    this.lastAcceptedAt = now;
     return true;
   }
 
 
   report() {
-    return { x: this.x, y: this.y, N: this.N };
+    return { x: this.x, y: this.y, N: this.N, lastAcceptedAt: this.lastAcceptedAt };
   }
 
   get N() {
@@ -318,15 +537,26 @@ class CorrectionEstimator {
   }
 
   get covariance() {
-    return this.filterState.covariance;
+    return this.getAgedCovariance();
   }
 
 
   toJSON() {
-    return this.N != 0 ? { state: this.filterState } : { state: null };
+    return this.N != 0
+      ? { state: this.filterState, lastAcceptedAt: this.lastAcceptedAt }
+      : { state: null, lastAcceptedAt: null };
   }
 
 }
 
 
-module.exports = { CorrectionTable };
+module.exports = {
+  CorrectionTable,
+  CorrectionEstimator,
+  MAX_AGING_SECONDS,
+  MIN_CELL_INDEX,
+  SECONDS_PER_MONTH,
+  KNOT_TO_MPS,
+  DEFAULT_CORRECTION_DRIFT_RATE,
+  DEFAULT_PROCESS_NOISE_RATE
+};

package/docs/correction-table-learning.md

@@ -0,0 +1,33 @@
+# Correction-table learning model
+
+## Smoothing cadence
+
+Learning inputs always use `MovingAverageSmoother`. The configurable `smootherTimeSpan` is the observation-window duration and is clamped to a minimum of 5 seconds. The learning interval is:
+
+```text
+learningInterval = smootherTimeSpan + 1 second
+```
+
+The extra second separates observation windows. Legacy exponential/Kalman smoother selections and their obsolete parameters are removed silently; a valid legacy window is retained and shorter windows become 5 seconds.
+
+## Cell aging
+
+Each learned cell stores the UTC epoch-millisecond timestamp of its last accepted observation. Its persisted posterior covariance is never changed by a read. At time `t`, the covariance used by the learner is aged by:
+
+```text
+effectiveDt = min((t - lastAcceptedAt) / 1000, 90 days)
+Q(dt) = Q_rate * effectiveDt * I
+```
+
+The 90-day value is an internal constant. Offline time counts toward `effectiveDt`; once the cap is reached, additional offline time has no effect. The aged covariance is used consistently for Mahalanobis gating, Kalman filtering, interpolation, reporting, and spatial-q estimation. A rejected observation leaves the timestamp unchanged. An accepted observation stores the posterior covariance and current timestamp.
+
+## Eligibility and spatial q
+
+`MIN_CELL_INDEX` remains an explicit maturity gate and is currently zero. A cell is eligible only when `cell.N > MIN_CELL_INDEX`, so one accepted observation is sufficient. The same condition is used by interpolation and spatial-q pair selection. The index remains persisted and exposed in diagnostics.
+The user-facing process-noise setting is **Correction drift**, expressed in knots per month. A month is defined as 30 days. Internally the value is converted to the SI `processNoiseRate` in `(m/s)^2` per second. The default is 0.3 knots/month; the UI range is 0.0 to 3.0 in 0.1 increments.
+
+## File compatibility
+
+Schema version 1 is the historical format and is preserved in `correction-table-v1.schema.json`; the existing `correction-table.schema.json` filename remains a compatibility alias. Schema version 2 adds `schemaVersion: 2`, per-cell `lastAcceptedAt` timestamps, and the serializable current model descriptor, including the SI `processNoiseRate`. The former `stability` descriptor is accepted only for compatibility with older files and is not written by new tables.
+
+Legacy files without a discriminator and files marked version 1 are migrated on load. Every learned legacy cell receives the file's `mtimeMs`, because individual cell ages are unavailable. This is a conservative estimate. Empty cells receive `null`. If filesystem metadata is unavailable, load time is used and the fallback is recorded through debug logging. The original file is replaced only after successful deserialization and validation, using an atomic temporary-file rename. Loading an existing version-2 file never rewrites its timestamps.