@meri-imperiumi/signalk-dead-reckoning 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -5,6 +5,170 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.0] - 2026-08-29
+
+### Added
+- **A single sight or bearing can now be resolved as a running fix
+  against the last confirmed fix.** The sun-run-sun economy — one sun
+  sight per day — previously stalled at every-other-day fixes: both
+  sights of a confirmed pair get attached to that fix and disappear
+  from the pending list, so the next day's lone sight had no partner to
+  resolve against. Selecting exactly one pending observation now
+  advances the last confirmed fix along the DR track (the shadow boat's
+  water-track integration, surviving restarts) to the observation time
+  and projects it onto the observation's constraint: cross-track comes
+  from the sight, along-track is trusted from the run. Works the same
+  for a celestial sight, a compass bearing when making landfall, or a
+  vertical-angle CPL (radial projection). In the pending list the
+  preview button reads "Running fix (1)" for a single selection;
+  selecting 2+ observations still resolves an ordinary fix. The
+  confirmed fix records its provenance in a new `derived_from_fix_id`
+  column (schema v2, migrated in place on open), the logbook entry
+  reads e.g. "Celestial fix from Sun LL sight (running fix, advanced
+  from fix #3)", and the map draws the previous-fix position, the DR
+  run vector, and the advanced point. Honest failures throughout: no
+  previous confirmed fix or a sight older than the latest fix → a 400
+  explaining what's missing; no DR-track coverage over the interval →
+  no fix, rather than silently projecting a stale fix position.
+
+### Fixed
+- **Moon sights were unusable: the lunar ephemeris was off by up to 1.5°
+  in GHA** (~90 NM of LOP error) despite its stated "~0.1°" accuracy
+  — the two-term truncation was nowhere near that. Moon GHA/Dec,
+  semi-diameter and horizontal parallax are now computed by
+  astronomy-engine to arcsecond class, with the distance-driven SD/HP
+  varying correctly over the anomalistic month (the previously fixed
+  SD 0.2725°/HP 0.95° were up to ~2′ wrong near apogee). Pinned by
+  snapshot tests and sanity-checked against the Astronomical Almanac's
+  low-precision series.
+- **DR no longer steers by raw magnetic heading when a variation source
+  is available.** The magnetic-heading fallback was used directly as
+  true heading, with no variation applied anywhere in the plugin — on
+  the Aitutaki–Niue route that would have steered the shadow boat
+  ~11° off (≈110 NM of lateral error over the passage) while
+  everything looked healthy. The plugin now subscribes to
+  `navigation.magneticVariation` (radians, east-positive) and applies it
+  to the fallback; `navigation.magneticVariation.source` (e.g.
+  "WMM 2025") is recorded and surfaced in `GET /status` as
+  `heading.mode` ("true" | "magnetic+variation" | "magnetic") plus
+  `heading.variationSource`, so the watchkeeper can verify what steers
+  DR instead of trusting it silently. A WMM-style source label past its
+  ~5-year model epoch ("WMM 2015") raises a plugin-status warning the
+  same way the star-almanac expiry does. Boats with no variation
+  source keep the old behavior (magnetic as-is) — visible as
+  `heading.mode: "magnetic"`.
+- **The plugin no longer ingests its own published deltas.** `publish`
+  targets `vessels.self` — the same paths the plugin subscribes to — so
+  on a real server its output came straight back through the
+  subscription. Two consequences: the `headingTrue` it published
+  (which, on a magnetic-only boat, was the raw magnetic value) would
+  shadow the live heading and **freeze DR's steering at the first
+  tick's value** for the rest of the passage; and the same echo
+  pattern could close feedback loops on any other published path.
+  Self-sourced updates (matched on the publish source label) are now
+  skipped at ingestion, and the published `headingTrue` is the
+  computed true heading — bus value when present, magnetic + variation
+  otherwise — never raw magnetic. The fake app in tests never fed
+  handleMessage output back, which is why the loop was invisible
+  there; new tests simulate the echo explicitly.
+- **The bundled star almanac's SHA values were wrong for several
+  stars, and mixed reference epochs.** Regulus was 12.5° off (~750 NM
+  of LOP error for anyone who sighted it), Hamal 2.9°, Polaris 3.1°,
+  Sirius/Schedar/Antares/Markab/Dubhe/Capella ~0.4° each; "Capella2"
+  was a duplicate of Capella; and the J2000 table was used with
+  of-date sidereal time, adding a systematic ~20′ (equinox precession)
+  to every star LOP by 2026. The table is now consistent J2000 mean
+  places — verified entry-by-entry against a Hipparcos-derived catalog
+  (d3-celestial's stars.6.json) to within ~0.5′ — and five southern-sky
+  navigational stars are bundled (Acrux, Hadar, Achernar, Miaplacidus,
+  Peacock): the South Pacific latitudes fix by the Southern Cross, not
+  Polaris. The of-date conversion is now the library's full
+  precession/nutation/aberration (see the ephemeris entry above).
+- **The multi-fix resolver now actually converges on the least-squares
+  fix.** `leastSquaresFit()` — used for any fix combining three or more
+  lines/circles of position, and as the fallback when two don't
+  geometrically intersect — ran gradient descent with a fixed step size
+  that bounded its total travel to a few hundred metres from the DR
+  position, regardless of how far away the true answer was. With
+  realistic celestial intercepts (several to tens of nautical miles)
+  it stalled near the start point and reported it as the fix: a
+  symmetric three-star sight returned the same position for intercepts
+  from 0.1 to 50 nm, with only the residual growing in lockstep —
+  readable as a plausible cocked-hat spread. Lines-only problems are
+  now solved exactly via the normal equations (the same 2×2 solve the
+  two-LOP intersection uses, generalized to N lines), with a tiny
+  Tikhonov term so all-parallel lines return the midline point nearest
+  the DR instead of a degenerate solve; circles are refined by
+  damped Gauss-Newton (Levenberg-Marquardt) from the better of the
+  linear solution and the DR start, converging in a handful of
+  iterations and never returning a worse fit than it started with.
+- **DR track interpolation crosses the antimeridian the short way.**
+  `GroundTrack.positionAt()` interpolated longitude linearly, so a
+  dateline crossing (179.9°E → 179.9°W) interpolated through
+  Greenwich instead of over ±180° — a running-fix advance taken
+  mid-crossing measured ~half the globe instead of the actual 0.2°
+  run. Longitude now interpolates the wrapped ±180° delta and the
+  result is normalized to [-180, 180).
+- **Calibration matrix bins no longer blend the two tacks together in
+  light air.** The bin key folded AWA to |AWA| on the assumption that
+  the signed heel bin keeps the tacks apart — but at heel angles
+  below half the heel bin width both tacks quantize to `heel_bin 0`
+  (and a boat without a heel sensor lives there at every wind
+  strength), so opposite-tack observations with opposite-sign leeway
+  EMA-averaged toward zero in the same bin. `quantizeAwa()` now keeps
+  the sign: the AWA sign is the tack marker everywhere, and heel
+  remains the physics dimension. Bins written by earlier versions
+  under the folded key are simply retrained (fresh bins learn at full
+  rate); no migration is needed.
+
+### Changed
+- **Celestial ephemerides are now computed by astronomy-engine** (MIT,
+  pure JS, zero sub-dependencies, fully offline — 1.8 MB installed):
+  Sun and Moon geocentric apparent places (nautical-almanac
+  convention: geocentric, coordinates of date, parallax applied as a
+  sight correction rather than baked into the GP), stars from the
+  bundled J2000 almanac converted to the date by the library's
+  precession/nutation/aberration. The hand-rolled formulas — verified
+  against an independent Meeus reduction when written, but
+  hand-maintained data and truncations forever — are retired in favor
+  of a maintained library; the trade is 1.8 MB of disk against a reef.
+  The unused suncalc runtime dependency is removed. The wiring is
+  pinned in tests/ephemeris.test.js by snapshots plus independent
+  anchors: a from-scratch Meeus reduction for the Sun (≤0.7′, the
+  anchor's own accuracy class), the AA low-precision series for the
+  Moon (≤20′), and paper-almanac star values.
+- **The webapp's "Ghost Track" heading above the map is gone.** It
+  wasted vertical space the map could use — the map card now opens with
+  no chrome above it, so the chart starts higher on the page. The
+  "follow DR position" recenter button (◎) that lived on that heading
+  moved into the map view as a floating control in the bottom-left
+  corner (the last free corner: zoom is top-left, layers top-right, the
+  divergence chip bottom-right). It now reflects the follow state —
+  filled while auto-follow is on, outlined after a drag pans the map
+  freely, refilled on click — so a heading-less floating button still
+  reads its state at a glance.
+
+## [0.6.1] - 2026-08-28
+
+### Changed
+- **Fix logbook entries now name the fix's sources instead of repeating
+  coordinates and the watchkeeper.** A confirmed fix was logged as
+  `Manual fix by bergie: 18°51'55.5" S 159°48'04.5" W, 0.1 nm from DR`
+  — but the coordinates are already in the structured `position` field
+  and the watchkeeper in `author`, so the text wasted both while
+  omitting the useful part: *what produced the fix*. A fix resolved
+  from compass bearings now reads `Manual fix from Aitutaki Atoll
+  bearing 123°T, Vessel Foo bearing 321°T, 0.1 NM at 045°T from DR`;
+  celestial fixes list the bodies sighted; CPL fixes list the object
+  and radius. Point fixes (GPS / manual / backfill) drop the
+  coordinates and the `by {user}` clause, keeping just the label and
+  the DR deviation. The deviation clause now carries the direction
+  (`0.5 NM at 090°T from DR`) and uses `NM` (Nautical Miles) rather
+  than `nm` (nanometers). `backfill` fixes get their own label and
+  `position.source` value instead of falling through to "Manual"/"DR".
+  Bearings are degrees-true (`°T`); magnetic (`°M`) would require a
+  magnetic-variation source, which isn't subscribed yet.
+
 ## [0.6.0] - 2026-08-28
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meri-imperiumi/signalk-dead-reckoning",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Offline-first dead reckoning and sensor fusion engine for Signal K",
   "main": "plugin/index.js",
   "scripts": {
@@ -45,10 +45,10 @@
   "engines": {
     "node": ">=22.5.0"
   },
-  "dependencies": {
-    "suncalc": "^1.9.0"
-  },
   "devDependencies": {
     "@signalk/server-api": "^2.30.0"
+  },
+  "dependencies": {
+    "astronomy-engine": "^2.1.19"
   }
 }

package/plugin/bins.js

@@ -10,6 +10,8 @@
  * @file bins.js
  */
 
+const { normalizeDeg180 } = require("./geo.js");
+
 /** STW bin width in knots (SPEC §4.1 example: nearest 0.5kt). */
 const STW_BIN_WIDTH = 0.5;
 
@@ -46,18 +48,24 @@ function quantizeStw(stwKn) {
 }
 
 /**
- * Quantizes apparent wind angle (degrees, absolute) to the matrix bin.
+ * Quantizes apparent wind angle (degrees, signed) to the matrix bin.
  *
- * AWA is taken as an absolute angle (port/starboard symmetry holds for the
- * leeway/speed-loss physics the matrix learns), so we fold to [0, 180]
- * before quantizing.
+ * The sign is kept — it is the tack marker. The learned leeway angle
+ * is signed (leeward-positive), so port-tack and starboard-tack
+ * observations must never EMA-average into the same bin: their leeway
+ * signs are opposite and would blend toward zero. Heel sign separates
+ * the tacks while the boat heels, but at light-air heel (< half the
+ * heel bin width) both tacks quantize to heel_bin 0 — and a boat with
+ * no heel sensor lives there at every wind strength — so folding AWA
+ * to |AWA| would collapse the tacks exactly there. The input is
+ * normalized to [-180, 180) first so 0–360-style angles bin
+ * identically to their signed forms.
  *
  * @param {number} awaDeg - apparent wind angle in degrees (signed ok)
  * @returns {number}
  */
 function quantizeAwa(awaDeg) {
-  const folded = Math.min(Math.abs(awaDeg), 180);
-  return quantize(folded, AWA_BIN_WIDTH);
+  return quantize(normalizeDeg180(awaDeg), AWA_BIN_WIDTH);
 }
 
 /**

package/plugin/celestial.js

@@ -22,13 +22,16 @@
  *      offset by the intercept — exactly the form `recordLineOfPosition`
  *      and the fix resolver expect.
  *
- * Ephemeris (SPEC §13):
- *   - Sun and Moon: computed locally from the timestamp via standard
- *     formulas (the same `aa.quae.nl` derivation suncalc uses, but we
- *     need GHA/declination, which suncalc's public API doesn't expose).
- *   - Stars: from a bundled static almanac (plugin/star-almanac.js),
- *     GHA = GHA Aries + SHA, declination from the almanac. Proper motion
- *     is negligible over the almanac's stated valid epoch (§13).
+ * Ephemeris (SPEC §13): computed by astronomy-engine (MIT, pure JS,
+ * zero sub-dependencies, fully offline) — Sun and Moon geocentric
+ * apparent places, stars from the bundled J2000 almanac (verified
+ * against a Hipparcos-derived catalog) converted to the date by the
+ * library's precession/nutation/aberration. The nautical-almanac
+ * convention throughout is GEOCENTRIC, coordinates of date; parallax
+ * is applied as a separate sight correction (step 3), never baked into
+ * the GP. Library accuracy is arcsecond-class — far below sextant
+ * precision — and is pinned by paper-almanac anchors in
+ * tests/ephemeris.test.js.
  *
  * The module is pure: no DB, no I/O, no `new Date()` (the sight time is
  * passed in explicitly so reduction is deterministic and testable).
@@ -38,6 +41,7 @@
  * @file celestial.js
  */
 
+const Astronomy = require("astronomy-engine");
 const { normalizeDeg360 } = require("./geo.js");
 
 /** Radians per degree. */
@@ -46,35 +50,24 @@ const RAD = Math.PI / 180;
 const DEG = 180 / Math.PI;
 /** Mean obliquity of the ecliptic (J2000), degrees. */
 const OBLIQUITY_DEG = 23.4397;
+/** Sun radius, km (IAU nominal). */
+const SUN_RADIUS_KM = 695700;
+/** Moon radius, km. */
+const MOON_RADIUS_KM = 1737.4;
+/** Earth equatorial radius, km. */
+const EARTH_EQ_RADIUS_KM = 6378.14;
 
 /**
- * Greenwich Mean Sidereal Time in degrees [0, 360), for a given UTC
- * timestamp. Standard USNO formula; used to turn SHA → GHA for stars and
- * RA → GHA for Sun/Moon.
- *
- * @param {number} epochMs - Date.getTime() value (UTC ms)
- * @returns {number}
- */
-function gmstDeg(epochMs) {
-  const jd = epochMs / 86400000 + 2440587.5;
-  const T = (jd - 2451545.0) / 36525;
-  const g =
-    280.46061837 +
-    360.98564736629 * (jd - 2451545.0) +
-    0.000387933 * T * T -
-    (T * T * T) / 38710000;
-  return normalizeDeg360(g);
-}
-
-/**
- * Reduces an ecliptic longitude/latitude to right ascension (degrees).
+ * Reduces an ecliptic longitude/latitude to right ascension (degrees),
+ * for a given obliquity (degrees).
  *
  * @param {number} lonDeg - ecliptic longitude, degrees
  * @param {number} latDeg - ecliptic latitude, degrees (0 for the Sun)
+ * @param {number} [epsDeg=OBLIQUITY_DEG] - obliquity of the ecliptic
  * @returns {number} RA, degrees
  */
-function raFromEcliptic(lonDeg, latDeg) {
-  const e = OBLIQUITY_DEG * RAD;
+function raFromEcliptic(lonDeg, latDeg, epsDeg = OBLIQUITY_DEG) {
+  const e = epsDeg * RAD;
   const l = lonDeg * RAD;
   const b = latDeg * RAD;
   const ra = Math.atan2(
@@ -85,14 +78,16 @@ function raFromEcliptic(lonDeg, latDeg) {
 }
 
 /**
- * Reduces an ecliptic longitude/latitude to declination (degrees).
+ * Reduces an ecliptic longitude/latitude to declination (degrees), for
+ * a given obliquity (degrees).
  *
  * @param {number} lonDeg
  * @param {number} latDeg
+ * @param {number} [epsDeg=OBLIQUITY_DEG] - obliquity of the ecliptic
  * @returns {number} declination, degrees [-90, 90]
  */
-function decFromEcliptic(lonDeg, latDeg) {
-  const e = OBLIQUITY_DEG * RAD;
+function decFromEcliptic(lonDeg, latDeg, epsDeg = OBLIQUITY_DEG) {
+  const e = epsDeg * RAD;
   const l = lonDeg * RAD;
   const b = latDeg * RAD;
   const dec = Math.asin(
@@ -102,71 +97,96 @@ function decFromEcliptic(lonDeg, latDeg) {
 }
 
 /**
- * Sun's geographic position at a timestamp: GHA and declination.
- *
- * Derived from the low-precision solar position formulas (good to ~0.01°,
- * ample for sextant work). Same source as suncalc (aa.quae.nl).
+ * Geocentric apparent GHA/Dec from true-ecliptic-of-date coordinates.
+ * The obliquity (true, of date) and Greenwich apparent sidereal time
+ * both come from the library, so nutation is included on both sides of
+ * GHA = GAST − RA — the nautical-almanac convention.
  *
  * @param {number} epochMs
+ * @param {number} lonDeg - ecliptic longitude of date, degrees
+ * @param {number} latDeg - ecliptic latitude of date, degrees
  * @returns {{gha_deg: number, declination_deg: number}}
  */
-function sunGeographicPosition(epochMs) {
-  const d = epochMs / 86400000 - 10957.5; // days since J2000
-  const M = normalizeDeg360(357.5291 + 0.98560028 * d); // mean anomaly
-  const C =
-    1.9148 * Math.sin(M * RAD) +
-    0.02 * Math.sin(2 * M * RAD) +
-    0.0003 * Math.sin(3 * M * RAD); // equation of center
-  const lon = normalizeDeg360(280.4665 + 0.9856474 * d + C); // true ecliptic longitude
-  const ra = raFromEcliptic(lon, 0);
-  const dec = decFromEcliptic(lon, 0);
-  // GHA = GMST − RA (Greenwich hour angle of the body).
-  const gha = normalizeDeg360(gmstDeg(epochMs) - ra);
-  return { gha_deg: gha, declination_deg: dec };
+function ghaDecFromEcliptic(epochMs, lonDeg, latDeg) {
+  const date = new Date(epochMs);
+  const eps = Astronomy.e_tilt(Astronomy.MakeTime(date)).tobl;
+  const ra = raFromEcliptic(lonDeg, latDeg, eps);
+  const dec = decFromEcliptic(lonDeg, latDeg, eps);
+  const gastDeg = Astronomy.SiderealTime(date) * 15;
+  return { gha_deg: normalizeDeg360(gastDeg - ra), declination_deg: dec };
 }
 
 /**
- * Moon's geographic position at a timestamp: GHA and declination.
+ * Sun's geographic position at a timestamp: GHA, declination, and the
+ * apparent semi-diameter from the true Earth–Sun distance (varies
+ * 0.263–0.274° over the year — the fixed mean left up to ±0.3′).
  *
- * Low-precision lunar position (good to ~0.1°). Same source as suncalc.
+ * @param {number} epochMs
+ * @returns {{gha_deg: number, declination_deg: number, semi_diameter_deg: number}}
+ */
+function sunGeographicPosition(epochMs) {
+  const ecl = Astronomy.SunPosition(new Date(epochMs));
+  const distKm = ecl.vec.Length() * Astronomy.KM_PER_AU;
+  return {
+    ...ghaDecFromEcliptic(epochMs, ecl.elon, ecl.elat),
+    semi_diameter_deg: Math.asin(SUN_RADIUS_KM / distKm) * DEG,
+  };
+}
+
+/**
+ * Moon's geographic position at a timestamp: GHA, declination, plus the
+ * semi-diameter and horizontal parallax from the true distance. The
+ * distance varies ±5.5% over the anomalistic month — the previously
+ * fixed SD 0.2725°/HP 0.95° were up to ~2′ wrong near apogee.
  *
  * @param {number} epochMs
- * @returns {{gha_deg: number, declination_deg: number}}
+ * @returns {{gha_deg: number, declination_deg: number, semi_diameter_deg: number, horizontal_parallax_deg: number}}
  */
 function moonGeographicPosition(epochMs) {
-  const d = epochMs / 86400000 - 10957.5; // days since J2000
-  const L = normalizeDeg360(218.316 + 13.176396 * d); // mean longitude
-  const M = normalizeDeg360(134.963 + 13.064993 * d); // mean anomaly
-  const F = normalizeDeg360(93.272 + 13.22935 * d); // argument of latitude
-  // Ecliptic longitude with the two largest correction terms.
-  const lon =
-    L +
-    6.289 * Math.sin(M * RAD) -
-    1.274 * Math.sin((2 * L - 2 * M) * RAD) +
-    0.658 * Math.sin(2 * F * RAD) -
-    0.186 * Math.sin((2 * L - 2 * M + 2 * F) * RAD);
-  // Ecliptic latitude (small, from F).
-  const lat =
-    5.128 * Math.sin(F * RAD) +
-    0.28 * Math.sin((M + F) * RAD) -
-    0.28 * Math.sin((M - F) * RAD);
-  const ra = raFromEcliptic(lon, lat);
-  const dec = decFromEcliptic(lon, lat);
-  const gha = normalizeDeg360(gmstDeg(epochMs) - ra);
-  return { gha_deg: gha, declination_deg: dec };
+  const ecl = Astronomy.EclipticGeoMoon(new Date(epochMs));
+  const distKm = ecl.dist * Astronomy.KM_PER_AU;
+  return {
+    ...ghaDecFromEcliptic(epochMs, ecl.lon, ecl.lat),
+    semi_diameter_deg: Math.asin(MOON_RADIUS_KM / distKm) * DEG,
+    horizontal_parallax_deg: Math.asin(EARTH_EQ_RADIUS_KM / distKm) * DEG,
+  };
 }
 
 /**
- * A star's geographic position, given GHA Aries (GMST) and the star's
- * SHA + declination from the bundled almanac.
+ * A star's geographic position at a timestamp: GHA and declination.
+ * The bundled almanac's J2000 mean place is registered with the library
+ * (`DefineStar`), which returns the apparent place of date — full
+ * precession, nutation and aberration.
+ *
+ * `DefineStar` mutates its slot globally; the single-threaded
+ * sight-reduction path re-registers per lookup, which is fine for
+ * per-sight (rare) events, not per-tick use.
  *
  * @param {number} epochMs
  * @param {{sha_deg: number, declination_deg: number}} star
  * @returns {{gha_deg: number, declination_deg: number}}
  */
 function starGeographicPosition(epochMs, star) {
-  const gha = normalizeDeg360(gmstDeg(epochMs) + star.sha_deg);
-  return { gha_deg: gha, declination_deg: star.declination_deg };
+  const date = new Date(epochMs);
+  const raHours = (360 - normalizeDeg360(star.sha_deg)) / 15;
+  Astronomy.DefineStar(
+    Astronomy.Body.Star1,
+    raHours,
+    star.declination_deg,
+    100,
+  );
+  const eq = Astronomy.Equator(
+    Astronomy.Body.Star1,
+    date,
+    new Astronomy.Observer(0, 0, 0),
+    true,
+    true,
+  );
+  const gastDeg = Astronomy.SiderealTime(date) * 15;
+  return {
+    gha_deg: normalizeDeg360(gastDeg - eq.ra * 15),
+    declination_deg: eq.dec,
+  };
 }
 
 /**
@@ -312,20 +332,21 @@ function reduceSight(input) {
   const body = input.body;
   if (body === "Sun") {
     gp = sunGeographicPosition(epochMs);
-    // Sun semi-diameter ≈ 0.2666° (varies ~0.263–0.274). Use the mean;
-    // the variation is below sextant-reading precision for v1.
-    const sd = 0.2666;
+    // Apparent semi-diameter from the true Earth–Sun distance
+    // (0.263–0.274° over the year).
+    const sd = gp.semi_diameter_deg;
     semiDiameterDeg =
       input.limb === "upper" ? -sd : input.limb === "lower" ? sd : null;
   } else if (body === "Moon") {
     gp = moonGeographicPosition(epochMs);
-    // Moon semi-diameter ≈ 0.2725° (mean; HP ≈ 0.95°). Parallax-in-altitude
-    // correction ≈ HP * cos(Ha); included as a rough mean for v1.
-    const sd = 0.2725;
+    // Semi-diameter and horizontal parallax from the true distance
+    // (varies ±5.5% over the anomalistic month). Parallax-in-altitude
+    // correction = HP·cos(Ha).
+    const sd = gp.semi_diameter_deg;
     semiDiameterDeg =
       input.limb === "upper" ? -sd : input.limb === "lower" ? sd : null;
     const ha = (input.hs_deg + (input.index_correction_deg ?? 0)) * RAD;
-    parallaxDeg = 0.95 * Math.cos(ha); // horizontal parallax scaled by cos(Ha)
+    parallaxDeg = gp.horizontal_parallax_deg * Math.cos(ha);
   } else if (input.almanac) {
     const star = input.almanac.lookup(body);
     if (!star) throw new Error(`unknown body: ${body}`);
@@ -463,7 +484,6 @@ function reduceNoonSight(input) {
 }
 
 module.exports = {
-  gmstDeg,
   raFromEcliptic,
   decFromEcliptic,
   sunGeographicPosition,

package/plugin/db.js

@@ -17,8 +17,10 @@ const { DatabaseSync } = require("node:sqlite");
 const { dirname } = require("node:path");
 const { mkdirSync } = require("node:fs");
 
-/** Schema version, bumped when a migration is needed. Persisted in dr_state_store. */
-const SCHEMA_VERSION = 1;
+/** Schema version, bumped when a migration is needed. Persisted in dr_state_store.
+ * v2: `fixes.derived_from_fix_id` — provenance for single-observation
+ * running fixes advanced from a previous confirmed fix. */
+const SCHEMA_VERSION = 2;
 
 /**
  * DDL for every table in SPEC §4. Statements run in order; all are
@@ -71,6 +73,7 @@ const SCHEMA_DDL = [
     logged_to_logbook BOOLEAN NOT NULL DEFAULT 0,
     logbook_entry_ref TEXT,
     resets_dr_origin BOOLEAN NOT NULL DEFAULT 0,
+    derived_from_fix_id INTEGER,
     notes TEXT
   )`,
 
@@ -190,6 +193,15 @@ function openDatabase(dbPath) {
   for (const stmt of SCHEMA_DDL) {
     db.exec(stmt);
   }
+  // v1 → v2: running-fix provenance column on `fixes`. Fresh databases
+  // get the column from the DDL above; existing ones are altered in
+  // place. The stored version is read *after* the DDL (it creates
+  // dr_state_store on a fresh database, where there is nothing to
+  // migrate) and *before* the new version is recorded below.
+  const storedVersion = getState(db, "schema_version");
+  if (storedVersion != null && Number(storedVersion) < 2) {
+    db.exec("ALTER TABLE fixes ADD COLUMN derived_from_fix_id INTEGER");
+  }
   // Record schema version so future migrations can branch on it.
   setState(db, "schema_version", String(SCHEMA_VERSION));
   return db;
@@ -286,6 +298,8 @@ function recordCorrection(db, r) {
  * @param {number} [r.estimated_error_radius]
  * @param {string} [r.confirmed_by]
  * @param {boolean} [r.resets_dr_origin]
+ * @param {number} [r.derived_from_fix_id] - the fix this running fix was
+ *   advanced from (single-observation running fix)
  * @param {string} [r.notes]
  * @returns {number} inserted fix_id
  */
@@ -293,8 +307,9 @@ function recordFix(db, r) {
   const stmt = db.prepare(
     `INSERT INTO fixes (
        timestamp, source_type, latitude, longitude,
-       estimated_error_radius, confirmed_by, resets_dr_origin, notes
-     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+       estimated_error_radius, confirmed_by, resets_dr_origin,
+       derived_from_fix_id, notes
+     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
   );
   const info = stmt.run(
     r.timestamp,
@@ -304,6 +319,7 @@ function recordFix(db, r) {
     r.estimated_error_radius ?? null,
     r.confirmed_by ?? null,
     r.resets_dr_origin ? 1 : 0,
+    r.derived_from_fix_id ?? null,
     r.notes ?? null,
   );
   return Number(info.lastInsertRowid);
@@ -518,7 +534,8 @@ function listFixes(db, q = {}) {
   return db
     .prepare(
       `SELECT fix_id, timestamp, source_type, latitude, longitude,
-              estimated_error_radius, confirmed_by, resets_dr_origin
+              estimated_error_radius, confirmed_by, resets_dr_origin,
+              derived_from_fix_id
        FROM fixes ORDER BY fix_id DESC LIMIT ?`,
     )
     .all(q.limit ?? 100);
@@ -713,7 +730,7 @@ function getFix(db, id) {
     .prepare(
       `SELECT fix_id, timestamp, source_type, latitude, longitude,
               estimated_error_radius, confirmed_by, resets_dr_origin,
-              notes, logged_to_logbook, logbook_entry_ref
+              notes, logged_to_logbook, logbook_entry_ref, derived_from_fix_id
        FROM fixes WHERE fix_id = ?`,
     )
     .get(id);