sailkick-boat 0.30.0 → 0.31.0

package/README.md

@@ -785,10 +785,22 @@ A useful side-effect: the auto-coarsening that keeps the ring under `MAX_SAMPLES
 longer lossy. Only the *emit* rate coarsens, never the poll, so a 30-day passage emitting
 every ~52 s still carries the true min/max within each 52 s.
 
-**Compass channels never get a band** — `twd`, `twa`, `awa`, `cog`, `heading`, `wptBrg`.
-The mean of 359° and 1° is 180°, the exact opposite of the truth, so those carry a
-last-reading snapshot and no band, ever. It is the one error here that would look entirely
-plausible on screen, so the tests pin it.
+**Compass channels are circular-meaned and never get a band** — `twd`, `twa`, `awa`,
+`cog`, `heading`, `wptBrg`. The *arithmetic* mean of 359° and 1° is 180°, the exact
+opposite of the truth, so these use the unit-vector mean `atan2(Σsin, Σcos)` instead: a
+genuine average with no seam. A min/max stays meaningless on a circle, so they carry no
+band, ever — the one error here that would look entirely plausible on screen.
+
+Two things the tests pin hard. **`twa` and `awa` stay signed, −180..180**, port negative,
+because that is what the number means; a circular mean returns 0..360, so they are folded
+back — without it a port-side wind reads as 270°, which is not a rounding difference but a
+different quantity. (Pinned as a fuzzed invariant, not two examples.) And **readings that
+cancel report nothing rather than north**: two exactly opposite bearings have no average,
+and `atan2(0, 0)` answers 0° with total confidence.
+
+Before 0.31.0 these channels served the last reading in each bucket — correct, but one
+sample per bucket, and the emit rate coarsens to ~52 s on a 30-day passage, so a direction
+trace was visibly jumpier aboard than ashore for the same minute.
 
 `chans=sog,aws` narrows the answer to the channels actually plotted; `bands` appears only
 when `stats=1` was asked *and* the provider produced them, so every client degrades to the

package/lib/history/angles.js

@@ -0,0 +1,86 @@
+// VENDORED from sailkick/shared/engine/angles.js @ a8c7153  sha256:6d001aa2e5a8f83b
+// Do not edit here — fix upstream and re-vendor. ONE definition of compass maths, so the
+// boat and the cloud answer "what was the average wind direction in this minute" the same
+// way. test/history-ring.test.js exercises it through the ring.
+//
+// Converted ESM -> CommonJS ONLY (export keywords removed, module.exports appended).
+// No logic changed.
+//
+// NB the upstream note on wrap180: it is deliberately duplicated here and in
+// perf-live.js rather than imported, so that each stays a SINGLE-FILE vendor with its own
+// pinned hash. The app fuzzes the two definitions against each other
+// (tests/test-angles.mjs); the same discipline applies to this copy.
+
+// Compass angle maths. Pure — no imports, no DOM — because shared/engine is the layer the
+// boat plugin vendors (tests/test-layering.mjs enforces both).
+//
+// The one idea worth stating: a compass reading is a point on a CIRCLE, and almost every
+// arithmetic operation you would reach for is wrong on a circle. The mean of 359° and 1° is
+// 180°, the exact reciprocal. min/max across the seam are meaningless. A line drawn from
+// 359° to 1° streaks the full height of a chart. Each of those has bitten this codebase.
+//
+// Two frames, and the whole file is about keeping them straight:
+//
+//   WRAPPED   — every value in [0,360). What instruments publish and what BoatState,
+//               /api/history/series and the dials all use. Correct for "where is it now",
+//               useless for "how did it change".
+//   UNWRAPPED — a continuous frame where 359 → 1 is recorded as 359 → 361. Differences and
+//               averages are ordinary arithmetic again. Correct for a series, meaningless
+//               as an absolute bearing until you wrap360 it at the very end.
+//
+// Same doctrine the routing field already uses for longitude — work in an unwrapped frame,
+// wrap only at the boundary (shared/engine/route-field.js:48, docs/ROUTING-FIELD.md:85).
+
+const wrap360 = (d) => ((d % 360) + 360) % 360;
+
+// Signed shortest path, (-180, 180]. NOTE: deliberately duplicated from perf-live.js:16
+// rather than imported. perf-live.js is vendored into sailkick-boat as a SINGLE FILE with a
+// pinned hash (see server/history/influx-provider.js:22); giving it an import would turn a
+// one-file copy into a two-file vendor contract. tests/test-angles.mjs fuzzes the two
+// definitions against each other, which buys the anti-drift guarantee without the coupling.
+const wrap180 = (d) => { const x = wrap360(d); return x > 180 ? x - 360 : x; };
+
+// One step of the UNBOUNDED accumulate: the nearest equivalent of `deg` to `prev`.
+// `prev` is the previous UNWRAPPED value, or null/undefined to seed the chain.
+//
+// Unbounded is the whole point, and is what separates this from the superficially identical
+// accumulators in perf-live.js:43 and mobile/main.js:352 — both of those re-wrap on every
+// step (bounded), because a dial must not spin away. A series must: after a full 360° veer
+// the result is legitimately start+360, and clamping it would reintroduce the jump this
+// exists to remove.
+const unwrapStep = (prev, deg) => (prev == null ? wrap360(deg) : prev + wrap180(deg - prev));
+
+// Lift a wrapped compass series into the unwrapped frame, in array order.
+//
+// Non-finite entries pass through untouched and DO NOT reset the chain. That is not
+// politeness about bad data: re-seeding after a dropout picks a fresh branch of the circle,
+// so every later point silently shifts by a multiple of 360 and the trace jumps for a reason
+// no one will ever track down.
+function unwrapDeg(degs) {
+  const out = new Array(degs.length);
+  let prev = null;
+  for (let i = 0; i < degs.length; i++) {
+    const d = degs[i];
+    if (!Number.isFinite(d)) { out[i] = d; continue; }
+    prev = unwrapStep(prev, d);
+    out[i] = prev;
+  }
+  return out;
+}
+
+// Circular mean of wrapped degrees — the honest average of a set of directions, via the
+// unit-vector sum. Returns wrapped degrees, or null when there is nothing to average or the
+// directions cancel exactly (opposite readings have no meaningful mean, and atan2(0,0) would
+// answer 0° with false confidence).
+function circularMeanDeg(degs) {
+  let sx = 0, sy = 0, n = 0;
+  for (const d of degs) {
+    if (!Number.isFinite(d)) continue;
+    const r = d * Math.PI / 180;
+    sx += Math.cos(r); sy += Math.sin(r); n++;
+  }
+  if (!n || Math.hypot(sx, sy) < 1e-9) return null;
+  return wrap360(Math.atan2(sy, sx) * 180 / Math.PI);
+}
+
+module.exports = { wrap360, wrap180, unwrapStep, unwrapDeg, circularMeanDeg }

package/lib/history/ring.js

@@ -63,7 +63,14 @@ const CHANNELS = [
 // mistake here would look entirely plausible on screen, which is why the test pins it.
 const WRAPPED = new Set(['twd', 'twa', 'awa', 'cog', 'heading', 'wptBrg'])
 
-const wrap360 = (d) => ((d % 360) + 360) % 360
+// Of those, TWA and AWA are SIGNED: -180..+180 with port negative, because "40° off the
+// bow to port" is what the number means. The other four are absolute bearings, 0..360.
+// A circular mean always comes back 0..360, so these two MUST be folded back or a
+// port-side wind reads as 270° — nonsense on every screen that shows it.
+const SIGNED = new Set(['twa', 'awa'])
+const rewrap = (c, d) => (SIGNED.has(c) ? wrap180(d) : wrap360(d))
+
+const { wrap360, wrap180, circularMeanDeg } = require('./angles')
 // Stored values are rounded to 3 decimals. Rows now carry a mean plus two extremes per
 // channel, so full float noise ("6.430000000000001") would inflate every persisted line
 // for precision no instrument has and no chart can draw.
@@ -134,7 +141,7 @@ class RingHistoryProvider {
     // polls counts readings seen since the last emit. Zero means the telemetry source
     // gave us nothing at all, and we push no row — a gap is the honest record, where a
     // row of nulls would be a claim that we looked and the boat had no data.
-    this._acc = { polls: 0, sum: {}, cnt: {}, lo: {}, hi: {}, last: {}, lat: null, lon: null }
+    this._acc = { polls: 0, sum: {}, cnt: {}, lo: {}, hi: {}, last: {}, sinS: {}, cosS: {}, lat: null, lon: null }
   }
 
   // BoatState -> the flat channel map this ring records. Kept separate from the
@@ -169,7 +176,18 @@ class RingHistoryProvider {
       const v = raw[c]
       if (!Number.isFinite(v)) continue
       a.last[c] = v
-      if (WRAPPED.has(c)) continue // a bearing has no meaningful mean or extreme
+      if (WRAPPED.has(c)) {
+        // A bearing still has no meaningful min/max — but it does have an average: the
+        // unit-vector (circular) mean, which is a genuine average with no seam. Serving
+        // one sample per bucket instead was correct but jumpy, and on a long passage the
+        // emit rate coarsens to ~52 s, so that would be one reading per bucket where the
+        // cloud averages every sample.
+        const r = v * DEG
+        a.sinS[c] = (a.sinS[c] || 0) + Math.sin(r)
+        a.cosS[c] = (a.cosS[c] || 0) + Math.cos(r)
+        a.cnt[c] = (a.cnt[c] || 0) + 1
+        continue
+      }
       a.sum[c] = (a.sum[c] || 0) + v
       a.cnt[c] = (a.cnt[c] || 0) + 1
       a.lo[c] = Math.min(a.lo[c] == null ? v : a.lo[c], v)
@@ -188,7 +206,15 @@ class RingHistoryProvider {
     if (!a.polls) return
     const row = { t: Date.now(), lo: {}, hi: {}, n: {} }
     for (const c of CHANNELS) {
-      if (WRAPPED.has(c)) { row[c] = a.last[c] == null ? null : round3(a.last[c]); continue }
+      if (WRAPPED.has(c)) {
+        const n = a.cnt[c] || 0
+        // A near-zero resultant means the readings cancelled (exactly opposite bearings):
+        // there is no meaningful average, and atan2(0, 0) would answer 0° — due north,
+        // with total confidence. A gap is the honest record.
+        const mag = n ? Math.hypot(a.sinS[c], a.cosS[c]) : 0
+        row[c] = mag < 1e-9 ? null : round3(rewrap(c, wrap360(Math.atan2(a.sinS[c], a.cosS[c]) / DEG)))
+        continue
+      }
       const n = a.cnt[c] || 0
       if (!n) { row[c] = null; continue }
       row[c] = round3(a.sum[c] / n)
@@ -258,9 +284,9 @@ class RingHistoryProvider {
         if (v == null) continue
         const key = step ? Math.floor(r.t / step) * step : seq++
         let b = buckets.get(key)
-        if (!b) buckets.set(key, (b = { t: step ? key + step : r.t, sum: 0, n: 0, lo: Infinity, hi: -Infinity, last: null }))
+        if (!b) buckets.set(key, (b = { t: step ? key + step : r.t, sum: 0, n: 0, lo: Infinity, hi: -Infinity, last: null, dirs: [] }))
         b.last = v
-        if (wrapped) continue
+        if (wrapped) { b.dirs.push(v); continue }
         // Rows written before v0.29.0 carry no lo/hi/n. Reading them defensively means an
         // append-log from an older version still loads and simply yields a degenerate
         // band (the point value itself) rather than an empty chart or a crash.
@@ -273,8 +299,15 @@ class RingHistoryProvider {
         if (hi > b.hi) b.hi = hi
       }
       const out = [...buckets.values()].sort((a, b) => a.t - b.t)
+      // Wrapped channels re-bucket by circular mean too — unweighted, matching the
+      // cloud's provider: a row built from 15 polls counts the same as one built from 3.
+      // A small inaccuracy, kept deliberately, because the two providers answering the
+      // same question identically is worth more here than either being marginally righter
+      // alone. Buckets whose directions cancel drop out rather than reporting north.
       const pts = wrapped
-        ? out.map((b) => [b.t, b.last])
+        ? out.map((b) => [b.t, circularMeanDeg(b.dirs)])
+          .filter(([, d]) => d != null)
+          .map(([t, d]) => [t, round3(rewrap(c, d))])
         : out.filter((b) => b.n > 0).map((b) => [b.t, round3(b.sum / b.n)])
       if (!pts.length) continue
       series[c] = pts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sailkick-boat",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "Run the sailkick app on board with no internet: charts, weather, climatology, trends and AIS all served from the boat itself. With a sailkick account it also syncs your metrics to the cloud in real time. Alpha, invite-only — info@sailkick.io",
   "main": "index.js",
   "scripts": {