sailkick-boat 0.31.0 → 0.32.0

package/README.md

@@ -203,6 +203,16 @@ because a renderer handed a gzip header errors hard while a missing tile simply
 to its parent. Content that is legitimately gzip — a `.gz` asset, a gzip content-type — is
 left alone: that is a payload, not an encoding.
 
+**`/sw.js` is network-first too**, and it is the sharpest case. The mobile app is a PWA
+whose service worker answers `mobile.html` and its assets from its *own* cache — before
+the request ever reaches this mirror — and the browser installs a new worker only when
+`sw.js`'s bytes change. So `sw.js` is the one un-hashed file that *is* the update signal:
+serve a stale one and the whole mobile shell freezes, however fresh the copy of
+`mobile.html` in the store happens to be. (Strictly it was never pinned *forever* — the
+manifest's `app` family invalidates it whenever the app's sha changes — but making the
+shell's update depend on a best-effort 5-minute poller is exactly the dependency the
+entry-document rule exists to remove.)
+
 ## Offline map coverage — global base seed + region prefetch
 On-demand caching only holds what you browsed. To make a usable map exist offline
 *everywhere*, the plugin seeds a worldwide low-zoom base on start and lets you warm a
@@ -503,6 +513,44 @@ dead feed is exactly a timestamp that stops moving). The two are reconciled by b
 the skew: a SignalK clock more than a minute from system time falls back to system time
 with one warning, rather than reporting a permanent phantom "feed stale".
 
+## A dead instrument is a gap, not a frozen value
+
+The telemetry state accumulates every SignalK delta into one object, so without care
+nothing in it ever expires. When **one** instrument dies while the others keep publishing,
+its fields freeze at their last value while `updatedAt` stays fresh — and every consumer
+treats dead data as live.
+
+This is not hypothetical. In deep water the sounder loses the bottom and simply stops
+publishing. Measured on this boat: for the hour after it went quiet the cloud (which
+stores only real updates) showed an honest **gap**, while the boat's ring recorded
+`224.85 m` every 15 seconds — a dead-flat plateau, and with min/max bands a **zero-width
+envelope**, which is the most confident possible rendering of an instrument that is not
+there. Two stories about the same hour; the plateau is the lie.
+
+So every field carries the time it was last patched, and the published view omits anything
+older than `fieldTtlSec` (default 15 s). Downstream this needs no cooperation: the ring
+records nothing so the series gaps, the app's `Number.isFinite` guards show `—`, and the
+alert evaluator's own "cannot tell" semantics take over — which never clears a raised
+alarm and never raises a new one on dead data. A returning instrument reappears on its
+first fresh delta; the internal state is never mutated, only filtered on read.
+
+Two cases needed more than a timestamp:
+
+- **A position expires whole.** `lat`/`lon` arrive as one `navigation.position` value, half
+  a fix is not a fix, and an anchor watch must not watch a frozen one.
+- **`headingDeg` is computed**, not patched — it never appears in a delta, so its freshness
+  is derived from its inputs (compass + variation, or a published true heading). Without
+  that rule it would never expire, which is the frozen-heading bug surviving the fix.
+
+**The TTL is measured, not guessed.** Every path that feeds BoatState on this boat arrives
+at ~1 Hz with a worst observed inter-sample gap of 2.8 s, so 15 s is about seven times the
+worst case. Crucially the subscription is fixed-period (`{ path: '*', period: 1000 }`) and
+the server republishes unchanged values — `navigation.magneticVariation`,
+`navigation.gnss.satellites` and `propulsion.port.runTime` all arrive at 1 Hz with 100%
+repeated values — so a healthy-but-constant instrument (an engine at rest publishing
+`rpm 0`) keeps arriving and does not expire. A boat configured on-change could differ,
+which is why `proxy.fieldTtlSec` can be raised by hand.
+
 ## Two paths, one reading
 
 Source priorities solve *several devices on one path*. There is a second, separate case:

package/index.js

@@ -372,7 +372,12 @@ module.exports = function (app) {
 
       if (p.serveTelemetry !== false) {
         try {
-          telemetry = createTelemetry(app, {})
+          // fieldTtlSec is a hand-editable escape hatch, not a config field: the right
+          // value follows from the bus's publish cadence, which the owner has no way to
+          // judge. Measured on this boat, every path feeding BoatState arrives at ~1 Hz
+          // (worst gap 2.8 s), so the 15 s default is ~7x margin. A boat whose SignalK is
+          // configured on-change, or with a slow NMEA0183 source, can raise it here.
+          telemetry = createTelemetry(app, { fieldTtlSec: p.fieldTtlSec })
           telemetry.start()
           pOpts.telemetryUpgrade = (req, sock, head) => telemetry.handleUpgrade(req, sock, head)
         } catch (e) {

package/lib/proxy/index.js

@@ -48,7 +48,20 @@ const isImmutableApi = (p) => IMMUTABLE_API_PREFIXES.some((x) => p.startsWith(x)
 // copy as STALE like any network-first path, so the app still opens with no uplink.
 // /health reports the running build and uptime — pinning it freezes the version the UI
 // displays, which is its own small version of this bug.
-const LIVE_PATHS = new Set(['/health'])
+//
+// /sw.js is here for the same reason as the entry documents, and it is the sharpest case:
+// it is the mobile PWA's ONE un-hashed file, and its bytes ARE the update signal. The
+// browser installs a new service worker only when sw.js differs from the installed one,
+// and until it does, the worker keeps answering mobile.html and its assets from its own
+// cache — before the request ever reaches this mirror. So a stale sw.js freezes the whole
+// mobile shell, and a fresh mobile.html sitting in our store makes no difference at all.
+//
+// It was not, strictly, pinned FOREVER: the cache-manifest's `app` family invalidates it
+// whenever the app's sha changes (measured on this boat — the family was invalidated at
+// 03:21 on 2026-09-01). But making the shell's update depend on a best-effort 5-minute
+// poller is the dependency the entry-document rule above exists to remove, and if the
+// manifest is unreachable or its endpoint changes shape, "forever" becomes literally true.
+const LIVE_PATHS = new Set(['/health', '/sw.js'])
 const isEntryDocument = (p) => {
   const path = p.split('?')[0]
   return path === '/' || path.endsWith('/') || path.endsWith('.html') ||

package/lib/telemetry/index.js

@@ -32,6 +32,45 @@ const WS_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11'
 const SUBPROTOCOL = 'sailkick.telemetry.v1'
 const wrap360d = (d) => ((d % 360) + 360) % 360
 const wrap180 = (d) => { const w = wrap360d(d); return w > 180 ? w - 360 : w }
+// PER-FIELD FRESHNESS. The accumulated state merges every delta into one object, so
+// nothing in it ever expires: when ONE instrument dies while the others keep publishing,
+// its fields freeze at their last value while `updatedAt` stays fresh, and every consumer
+// treats dead data as live. Measured on this boat: the sounder lost the bottom in deep
+// water and stopped publishing at 05:20, and for the hour that followed the history ring
+// recorded 224.85 m every 15 s — a dead-flat plateau with a zero-width min/max band,
+// which reads as "rock steady" — while the cloud, which stores only real updates, showed
+// an honest gap for the same hour. Two stories about the same hour; the plateau is the
+// lie. The same freeze makes a wind-speed alarm unable to fire during a wind-instrument
+// outage, because it keeps seeing the last live reading.
+//
+// So each field carries the time it was last PATCHED, and the published view omits any
+// field older than the TTL. The internal state is never mutated — filtering happens on
+// read and on emit, so a returning instrument reappears on its first fresh delta.
+//
+// TTL: measured on this boat's bus, every path that feeds BoatState arrives at ~1 Hz with
+// a worst inter-sample gap of 1.1–2.1 s (magneticVariation reaches 2.8 s from its fast
+// sources). 15 s is ~7x the worst case. Critically, this subscription is FIXED-PERIOD
+// ({ path: '*', period: 1000 }), and the server republishes unchanged values — proven by
+// magneticVariation, gnss.satellites and propulsion.port.runTime arriving at 1 Hz with
+// 100% repeated values. So a healthy-but-constant instrument (an engine at rest
+// publishing rpm 0) keeps arriving and does NOT expire. A boat whose SignalK is
+// configured on-change, or with a slow NMEA0183 source, could differ — hence the knob.
+const FIELD_TTL_SEC = 15
+
+// Fields that are ONE physical reading and must expire together. A position is published
+// as a single navigation.position value; half a fix is not a fix, and a stale one should
+// disappear whole so the anchor watch stops watching a frozen position.
+const FIELD_GROUPS = [['lat', 'lon']]
+
+// headingDeg is COMPUTED at the merge site, so it never appears in a patch and has no
+// freshness of its own. Its inputs do: the compass path plus variation, or a published
+// true heading. Without this it would either never expire — the frozen-heading bug
+// surviving the fix — or expire always. (Note the `|| 0` fallback below, which is why a
+// boat with no heading source currently reads due north rather than nothing.)
+const COMPUTED_FRESHNESS = {
+  headingDeg: (fresh) => (fresh('hdgMagDeg') && fresh('magVarDeg')) || fresh('hdgTrueDeg')
+}
+
 const SEED = { sogKt: 0, cogDeg: 0, headingDeg: 0, awsKt: null, awaDeg: null }
 
 function encodeTextFrame (str) {
@@ -197,6 +236,30 @@ function createTelemetry (app, options = {}) {
     return compass
   }
 
+  // field -> ms when it was last patched. Never pruned: it is bounded by the number of
+  // BoatState fields, and an entry for a field that never returns is a few bytes.
+  const seenAt = {}
+  const ttlMs = Math.max(1, (options.fieldTtlSec || FIELD_TTL_SEC)) * 1000
+
+  // The ONE view every consumer sees — getState(), the update broadcast and the hello
+  // frame. They must not disagree: a field the ring records but the screen omits (or the
+  // reverse) is the same class of bug as the freeze itself.
+  function publicState (now = Date.now()) {
+    if (!state) return state
+    const fresh = (k) => seenAt[k] != null && (now - seenAt[k]) < ttlMs
+    const out = { updatedAt: state.updatedAt } // whole-feed staleness stays the app's job
+    for (const [k, v] of Object.entries(state)) {
+      if (k === 'updatedAt') continue
+      const rule = COMPUTED_FRESHNESS[k]
+      if (rule ? rule(fresh) : fresh(k)) out[k] = v
+    }
+    // Grouped fields go together or not at all.
+    for (const g of FIELD_GROUPS) {
+      if (g.some((k) => !(k in out))) for (const k of g) delete out[k]
+    }
+    return out
+  }
+
   function onDelta (delta) {
     if (!delta || !Array.isArray(delta.updates)) return
     const patch = {}
@@ -212,9 +275,11 @@ function createTelemetry (app, options = {}) {
       state = { ...SEED }
     }
     state = { ...state, ...patch, updatedAt: ts || new Date().toISOString() }
+    const now = Date.now()
+    for (const k of Object.keys(patch)) seenAt[k] = now
     const hd = resolveHeading(state)
     state.headingDeg = Number.isFinite(hd) ? hd : (state.headingDeg || state.cogDeg || 0)
-    broadcast({ type: 'telemetry/update', state })
+    broadcast({ type: 'telemetry/update', state: publicState(now) })
   }
 
   function start () {
@@ -260,16 +325,21 @@ function createTelemetry (app, options = {}) {
     socket.on('close', drop)
     socket.on('error', () => { drop(); try { socket.destroy() } catch {} })
     socket.on('data', (buf) => { if (buf && buf.length && (buf[0] & 0x0f) === 0x8) { drop(); try { socket.destroy() } catch {} } }) // client close frame
-    send(socket, { type: 'hello', source: 'signalk-local', state })
+    send(socket, { type: 'hello', source: 'signalk-local', state: publicState() })
   }
 
   // current BoatState (or null before the first fix) — used as the DB-less ring
   // history source, and by tests.
-  function getState () { return state }
+  // Filtered, like everything else. Consumers (the history ring, the alert engine, the
+  // polar %) then see an absent field rather than a frozen one: the ring records a gap,
+  // and the shared alert evaluator's own "cannot tell" semantics take over — which never
+  // clears a raised alarm.
+  function getState () { return publicState() }
   function _ingest (delta) { onDelta(delta) } // for tests
   const _state = getState
+  const _rawState = () => state // tests + status: the unfiltered accumulator
 
-  return { start, stop, status, handleUpgrade, getState, _ingest, _state }
+  return { start, stop, status, handleUpgrade, getState, _ingest, _state, _rawState, _seenAt: () => seenAt, _publicState: publicState }
 }
 
 module.exports = { createTelemetry, encodeTextFrame, SUBPROTOCOL }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sailkick-boat",
-  "version": "0.31.0",
+  "version": "0.32.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": {