sailkick-boat 0.27.0 → 0.30.0

package/README.md

@@ -188,6 +188,21 @@ POST /plugins/sailkick-boat/cache/clear?prefix=tiles/seamap        # nuke one ti
 when clearing — the default keep already does. A hand-typed `find` clear should add
 `! -name history` alongside `! -name tiles ! -name terrain`.)
 
+**A pinned file that was cached wrong stays wrong.** Tiles have no expiry, which is the
+whole point — but it means a bug in the *transport* outlives its fix. The pre-0.23.9
+client stored still-gzipped bytes as if they were the payload (core `http` hands back the
+compressed stream where `fetch` decoded it), and Cesium read the gzip header as a vertex
+count: `Invalid typed array length: 11239580910`. Fixing the transport fixed new fetches
+and nothing else: 2,391 terrain tiles and 188 vector tiles kept throwing for weeks after,
+because nothing ever re-examined a stored file.
+
+So a cache HIT is now checked — two bytes of a buffer already read. A file that claims to
+be quantized-mesh or protobuf and begins `1f 8b` is dropped and re-fetched (`REPAIRED`);
+if the upstream is unreachable the request FAILS rather than serving the poison again,
+because a renderer handed a gzip header errors hard while a missing tile simply falls back
+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.
+
 ## 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
@@ -348,6 +363,46 @@ at all. The raw channels are always recorded regardless, so the cloud can recomp
 history if the maths ever changes: the recorded channel is a materialisation, not the only
 truth.
 
+## Sails — the boat is the only writer
+
+Sailkick records every instrument value but has no idea which sails are set, so the polar
+estimator averages a full-main-and-genoa curve together with a three-reefs-and-staysail
+one. Recording the plan as a time series is what will let it tell them apart.
+
+`POST /api/sails {"plan":"genoa:0+main:2"}` publishes an ordinary SignalK delta on
+`sails.plan`, and the gapless spool carries it to the cloud like any other value. The
+**cloud refuses the same request** (`501 sail-write-not-here`), deliberately: one writer
+keeps `<id>_raw` a faithful mirror of the boat's own SignalK, the write is offline-correct
+for free — sail changes happen at sea, which is exactly when the cloud is unreachable —
+and no Influx *write* token has to live in the cloud beside the password hashes.
+
+```
+genoa:0+main:0        full main and full genoa
+main:2+staysail:0     two reefs, staysail, no headsail
+genoa:2+stormjib:0    genoa furled two steps AND the storm jib set
+bare                  nothing up
+```
+
+`<id>:<reefs>` per **set** sail, joined by `+`, **sorted by id**. Any combination is
+expressible, which is the point — a cutter flies genoa and staysail together, heavy
+weather means a partly-furled genoa *and* the storm jib, downwind means twin headsails. A
+fixed slot per station cannot say any of that.
+
+**Sorting is the contract**, so the write door validates by round-tripping through the
+vendored encoder (`shared/engine/sails.js`, pinned by hash) and **refuses** anything
+non-canonical rather than fixing it up. `main:2+genoa:0` names the right sails and hashes
+differently from `genoa:0+main:2`; accepting it would split the polar cloud this feature
+exists to unify — silently, and visible only much later as a mysteriously noisy polar. A
+client sending it is using its own encoder, which is the actual bug.
+
+`bare` rather than an empty string distinguishes "the crew says nothing is up" from "we
+have no sail data", which is null. Under bare poles in a survival storm that difference is
+real.
+
+`/api/config` gains `sailPlanWritable: true` — a **capability**, not a deployment test:
+the dev box runs the cloud server on a LAN and self-hosters run it as their edge, so "am I
+the cloud?" is the wrong question. The screen reads only the capability.
+
 ## Alerts and alarms, evaluated on board
 
 Rules — anchor drag, wind over or under a threshold, a big wind shift, boat speed below
@@ -712,15 +767,44 @@ cloud, in-memory ring on a DB-less edge*. The boat is a third case — an edge t
 serves the app's history endpoints from its **own** live data:
 ```
 GET /api/history/series?window=3600s&every=30s -> { series: { sog|heading|tws|… : [[tMs,val],…] } }
+GET /api/history/series?…&stats=1&chans=sog,aws -> { series: {…}, bands: { sog: [[t,min,max],…] } }
 GET /api/history/track?window=3600s&every=10s  -> { track: [{ t, lat, lon }, …] }
 GET /api/history/track?from=<epochMs>&to=<epochMs>   (absolute range; ISO also accepted)
 ```
+**Gusts: `stats=1` adds true min/max bands under the mean.** A mean line hides the thing
+you actually want to see — the app measured an hour of real sailing at 20 s buckets where
+the mean spanned 4.8 kt and the true envelope spanned 8.3 kt, with 1.87 kt of spread
+hidden inside an average bucket. That spread only exists if it is *recorded*: the ring
+polls BoatState every second into a per-channel `{sum, cnt, lo, hi}` accumulator and emits
+one row per sample interval carrying the mean plus the true extremes seen inside it. It
+used to snapshot instead, throwing away 14 of every 15 readings before anything could ask
+a question about them — no later bucketing, on the boat or in the browser, can bring those
+back.
+
+A useful side-effect: the auto-coarsening that keeps the ring under `MAX_SAMPLES` is no
+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.
+
+`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
+plain line. `series` is unchanged with or without either param.
+
 Both endpoints take **either** a trailing `window`, **or** an absolute `from`/`to` —
 which is what the app sends whenever the view is scrolled back in time (the historic
 trail, and a Trends flyout on a past period). The response echoes the `from`/`to` it
 actually served. Before 0.24.0 the boat parsed only `window`, so a request for a past
 hour came back `200` with the **most recent** hour: the historic trail silently showed
-live data. `every` thins a long track and always keeps the first and newest fix.
+live data. `every` thins a long track and always keeps the first and newest fix; on
+`series` it re-buckets (means weighted by the sample count behind each row, extremes as
+min-of-mins), labelling each bucket at its **end** to match the cloud's
+`aggregateWindow(timeSrc: "_stop")` — label them at the start and the two providers plot
+half a bucket apart on the same screen. It is floored so one answer stays under ~3k
+points, as the cloud route does.
 
 Same JSON the cloud returns, so the browser can't tell the difference — but it
 works **offline** with the boat's own data. Only when no telemetry source is

package/index.js

@@ -12,6 +12,7 @@ const { createAisTargets } = require('./lib/ais/targets')
 const { createProfile } = require('./lib/profile')
 const { createPerf } = require('./lib/perf')
 const { createAlerts } = require('./lib/alerts')
+const { createSails } = require('./lib/sails')
 const { createCloud } = require('./lib/cloud')
 const { resolveAccountConfig } = require('./lib/account')
 
@@ -109,6 +110,7 @@ module.exports = function (app) {
   let cloud = null
   let perf = null
   let alerts = null
+  let sails = null
   let proxyPort = null // what the launcher page needs to build its links
   let pairedSlug = null
   let statusTimer = null
@@ -425,6 +427,16 @@ module.exports = function (app) {
         }
       }
 
+      // The sail-plan write door. No config toggle: it is inert until the crew posts a
+      // plan, and a boat that cannot record its sails is the status quo this fixes.
+      try {
+        sails = createSails(app, { pluginId: plugin.id })
+        pOpts.sails = sails // proxy dispatches POST /api/sails and claims sailPlanWritable
+      } catch (e) {
+        (app.error || console.error)('[sailkick-boat] sails start failed: ' + e.message)
+        sails = null
+      }
+
       if (pOpts.history.enabled !== false) {
         try {
           // ringSource = the telemetry module: when no local InfluxDB token is set
@@ -530,6 +542,7 @@ module.exports = function (app) {
     if (profile) parts.push(profile.status())
     if (perf) parts.push(perf.status())
     if (alerts) parts.push(alerts.status())
+    if (sails) parts.push(sails.status())
     if (ais) parts.push(ais.status())
     if (backfill) parts.push(backfill.status())
     try { app.setPluginStatus(parts.join('   |   ') || 'idle (both features off)') } catch {}
@@ -559,6 +572,7 @@ module.exports = function (app) {
     cloud = null
     perf = null
     alerts = null
+    sails = null
     proxyPort = null
     pairedSlug = null
     proxy = null

package/lib/history/index.js

@@ -26,6 +26,10 @@ const wrap180 = (d) => { const x = wrap360(d); return x > 180 ? x - 360 : x }
 
 // Parse a duration like "1h" / "30m" / "600s" / "3600" → seconds, clamped.
 // Ported from the app's server/routes/history.js so limits match exactly.
+// One response has to stay drawable and sendable over a satellite link; the cloud route
+// uses the same ceiling.
+const MAX_POINTS = 3000
+
 function dur (s, def, min, max) {
   if (s == null) return def
   const m = String(s).trim().match(/^(\d+)\s*([smh]?)$/)
@@ -127,12 +131,24 @@ function createHistory (app, options) {
     if (!available()) return sendJson(res, 503, { ok: false, code: 'history-unavailable', message: 'history not available' })
     const q = query(req.url)
     const windowSec = dur(q.get('window'), 3600, 60, 86400)
-    const everySec = dur(q.get('every'), 30, 5, 600)
     const abs = absRange(q)
+    // Floor the bucket so one answer stays drawable. An absolute range can be a month
+    // wide, and at the default 30 s that is 86,400 points down a link that may be
+    // Starlink on a bad night — the cloud route floors it the same way, so both providers
+    // return the same shape for the same request.
+    const spanSec = abs ? Math.max(1, Math.round((abs.toMs - abs.fromMs) / 1000)) : windowSec
+    const everySec = Math.max(dur(q.get('every'), 30, 5, 600), Math.ceil(spanSec / MAX_POINTS))
+    // Both additive and both ignorable, so a client that knows nothing of them is served
+    // exactly what it was served before. `stats=1` asks for the true per-bucket min/max
+    // under the mean — the gusts, which a mean line hides: on an hour of real sailing the
+    // mean spanned 4.8 kt where the true envelope spanned 8.3 kt. `chans=sog,aws` narrows
+    // the answer to what is actually plotted.
+    const stats = /^(1|true|yes)$/i.test(String(q.get('stats') || ''))
+    const chans = String(q.get('chans') || '').split(',').map((c) => c.trim()).filter(Boolean)
     try {
-      const r = await provider.getSeries({ windowSec, everySec, ...(abs || {}), signal: abortOnClose(res) })
+      const r = await provider.getSeries({ windowSec, everySec, stats, chans, ...(abs || {}), signal: abortOnClose(res) })
       if (!r.ok) return sendJson(res, r.status || 502, { ok: false, code: 'history-error', message: r.message })
-      sendJson(res, 200, {
+      const body = {
         ok: true,
         windowSec,
         everySec,
@@ -140,7 +156,11 @@ function createHistory (app, options) {
         from: abs ? abs.fromMs : Date.now() - windowSec * 1000,
         to: abs ? abs.toMs : Date.now(),
         series: r.series
-      })
+      }
+      // Only when asked AND produced: a client that sent stats=1 must still degrade to
+      // the plain line rather than wait for a key that never comes.
+      if (stats && r.bands) body.bands = r.bands
+      sendJson(res, 200, body)
     } catch (e) {
       sendJson(res, 502, { ok: false, code: 'history-error', message: e.message })
     }

package/lib/history/ring.js

@@ -6,15 +6,28 @@
 // series/track contract as the InfluxDB provider; TWS/TWD are derived from apparent
 // wind + boat motion (as the ribbon does), STW is simply absent.
 //
+// Each emitted row carries, per linear channel, the MEAN over the interval plus the true
+// min/max seen inside it (`lo`/`hi`) and the sample count behind the mean (`n`) — see the
+// two-clocks note in the constructor. Compass channels carry a last-reading snapshot and
+// none of the three, because a bearing has no arithmetic mean.
+//
 // Persistence (optional, `persistFile`): a JSONL APPEND-LOG so the ring survives
-// restarts and can cover a long passage cheaply. Each sample is appended as one
-// line (~160 B); the file is compacted (atomic rewrite to the current window) only
-// rarely — on start, once appends exceed the ring length, and on destroy — so write
-// load is per-sample, decoupled from window size (< ~1 GB over a 30-day passage vs
-// ~600 GB for a full-rewrite-every-2min snapshot). To keep RAM/disk bounded at any
-// window, the sample rate auto-coarsens so the ring never exceeds ~MAX_SAMPLES rows
-// (24 h → 15 s, 30 d → ~52 s). All fs is guarded — a missing/corrupt file just means
-// an empty start; appends + compactions are serialized so they can't interleave.
+// restarts and can cover a long passage cheaply. Each row is appended as one line; the
+// file is compacted (atomic rewrite to the current window) only rarely — on start, once
+// appends exceed the ring length, and on destroy — so write load is per-sample,
+// decoupled from window size. Measured on a fully-populated row (every channel present):
+// 307 B before the bands, 844 B with them, i.e. 2.7x. A 30-day passage is ~49.8k rows
+// (the emit rate auto-coarsens to ~52 s, see below), so ~40 MB of appends plus ~2x that
+// again in compaction rewrites — against ~600 GB for a full-rewrite-every-2min snapshot,
+// and still nothing on a boat SSD.
+//
+// To keep RAM/disk bounded at any window, the EMIT rate auto-coarsens so the ring never
+// exceeds ~MAX_SAMPLES rows (24 h → 15 s, 30 d → ~52 s). That coarsening used to throw
+// readings away; it no longer does. Only the emit rate coarsens, never the poll, so a
+// 30-day passage still carries the true min/max within each ~52 s bucket.
+//
+// All fs is guarded — a missing/corrupt file just means an empty start; appends +
+// compactions are serialized so they can't interleave.
 
 const fs = require('fs')
 const fsp = fs.promises
@@ -43,7 +56,18 @@ const CHANNELS = [
   // drawn over it.
   'perf'
 ]
+// The channels whose values WRAP. A compass bearing cannot be averaged or min/max'd
+// arithmetically — the mean of 359° and 1° is 180°, the exact opposite of the truth — so
+// these keep a plain snapshot of the LAST reading in the interval and never carry a band.
+// Everything else is linear and gets both. Same split as the app's ring provider; a
+// 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
+// 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.
+const round3 = (v) => (Number.isFinite(v) ? Math.round(v * 1000) / 1000 : v)
 const MAX_SAMPLES = 50000
 
 // True wind (TWS kt, TWD ° the wind blows FROM).
@@ -71,10 +95,10 @@ function trueWind (s) {
 }
 
 class RingHistoryProvider {
-  constructor ({ source, perfSource, sampleSec, windowSec, persistFile } = {}) {
+  constructor ({ source, perfSource, sampleSec, pollSec, windowSec, persistFile } = {}) {
     this._source = source
     this._perfSource = perfSource || null
-    this._ring = [] // [{ t, ...CHANNELS, lat, lon }]
+    this._ring = [] // [{ t, ...CHANNELS, lo:{}, hi:{}, n:{}, lat, lon }]
     const win = windowSec || 3600
     this._windowMs = win * 1000
     this._persistFile = persistFile || null
@@ -83,45 +107,112 @@ class RingHistoryProvider {
     // auto-coarsen so the ring is bounded (~MAX_SAMPLES rows) regardless of window
     const stepSec = Math.max(sampleSec || 15, Math.ceil(win / MAX_SAMPLES))
     this._stepSec = stepSec
+    // TWO CLOCKS. This used to SNAPSHOT BoatState once per stepSec and store point values,
+    // which threw away 14 of every 15 readings BEFORE anything could ask a question about
+    // them: the gusts were gone before a chart ever saw the data, and no amount of later
+    // bucketing could bring them back. Now the state is POLLED at pollSec (~1 s, the rate
+    // the boat publishes) into a per-channel sum/count/min/max accumulator, and one row is
+    // EMITTED every stepSec carrying the mean plus the true extremes seen inside it.
+    //
+    // Ring length and emit rate are unchanged, so every existing budget still holds — and
+    // MAX_SAMPLES coarsening stops being lossy: a 30-day passage emitting every ~52 s
+    // still carries the true min/max within each 52 s, because the poll never coarsened.
+    this._pollSec = Math.min(stepSec, Math.max(0.2, pollSec || 1))
+    this._resetAcc()
 
     this._load() // seed from disk (survives restart)
     this._compactSync() // rewrite clean + bounded, synchronously (file exists right at start)
-    this._sample() // immediate first sample
-    this._timer = setInterval(() => this._sample(), stepSec * 1000)
+    this._sample() // immediate first row, so a fresh process is not blank for stepSec
+    this._pollTimer = setInterval(() => this._poll(), this._pollSec * 1000)
+    this._timer = setInterval(() => this._emit(), stepSec * 1000)
     if (this._timer.unref) this._timer.unref()
+    if (this._pollTimer.unref) this._pollTimer.unref()
   }
 
   // --- sampling ---
-  _sample () {
-    const s = this._source && this._source.getState && this._source.getState()
-    if (!s) return
+  _resetAcc () {
+    // 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 }
+  }
+
+  // BoatState -> the flat channel map this ring records. Kept separate from the
+  // accumulator so poll and emit share one definition of where each channel comes from.
+  _raw (s) {
     const tw = trueWind(s)
-    const num = (v) => (Number.isFinite(v) ? v : null)
-    const row = {
-      t: Date.now(),
-      sog: num(s.sogKt), cog: num(s.cogDeg), heading: num(s.headingDeg),
-      stw: num(s.stwKt),
-      aws: num(s.awsKt), awa: num(s.awaDeg), depth: num(s.depthM),
+    return {
+      sog: s.sogKt, cog: s.cogDeg, heading: s.headingDeg, stw: s.stwKt,
+      aws: s.awsKt, awa: s.awaDeg, depth: s.depthM,
       tws: tw ? tw.tws : null, twd: tw ? tw.twd : null,
       // Everything below arrived in BoatState with v0.18.6 but was never sampled here,
       // so these instrument cells had a live value and an empty history flyout.
-      twa: num(s.twaDeg), vmg: num(s.vmgKt),
-      seaTemp: num(s.seaTempC), airTemp: num(s.airTempC),
-      rpmPort: num(s.rpmPort), rpmStbd: num(s.rpmStbd),
-      // Waypoint channels are legitimately null when no destination is active — num()
-      // maps that to null and CHANNELS omits empty ones, so the flyout stays blank
-      // rather than showing a flat line at zero.
-      wptBrg: num(s.wptBrgDeg), wptDist: num(s.wptDistNm),
-      wptVmg: num(s.wptVmgKt), wptTtg: num(s.wptTtgSec),
-      perf: this._perfSource ? num(this._perfSource.getPerf()) : null,
-      lat: num(s.lat), lon: num(s.lon)
+      twa: s.twaDeg, vmg: s.vmgKt,
+      seaTemp: s.seaTempC, airTemp: s.airTempC,
+      rpmPort: s.rpmPort, rpmStbd: s.rpmStbd,
+      // Waypoint channels are legitimately null when no destination is active — the
+      // accumulator skips non-finite values and CHANNELS omits empty ones, so the flyout
+      // stays blank rather than showing a flat line at zero.
+      wptBrg: s.wptBrgDeg, wptDist: s.wptDistNm,
+      wptVmg: s.wptVmgKt, wptTtg: s.wptTtgSec,
+      perf: this._perfSource ? this._perfSource.getPerf() : null
     }
+  }
+
+  _poll () {
+    const s = this._source && this._source.getState && this._source.getState()
+    if (!s) return
+    const raw = this._raw(s)
+    const a = this._acc
+    a.polls++
+    for (const c of CHANNELS) {
+      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
+      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)
+      a.hi[c] = Math.max(a.hi[c] == null ? v : a.hi[c], v)
+    }
+    if (Number.isFinite(s.lat)) a.lat = s.lat
+    if (Number.isFinite(s.lon)) a.lon = s.lon
+  }
+
+  // One row per stepSec: the mean of everything seen since the last emit, plus the true
+  // extremes (`lo`/`hi`) and the sample count behind each mean (`n`, needed to weight a
+  // later re-bucket). Wrapped channels carry the last reading and appear in none of the
+  // three.
+  _emit () {
+    const a = this._acc
+    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 }
+      const n = a.cnt[c] || 0
+      if (!n) { row[c] = null; continue }
+      row[c] = round3(a.sum[c] / n)
+      row.lo[c] = round3(a.lo[c])
+      row.hi[c] = round3(a.hi[c])
+      row.n[c] = n
+    }
+    row.lat = a.lat == null ? null : a.lat
+    row.lon = a.lon == null ? null : a.lon
+    this._resetAcc()
+
     this._ring.push(row)
     const cutoff = Date.now() - this._windowMs
     while (this._ring.length && this._ring[0].t < cutoff) this._ring.shift()
     this._append(row)
   }
 
+  // One poll + one emit, i.e. the old single-shot behaviour. Used for the first row at
+  // construction and by the tests, which drive the clocks by hand.
+  _sample () {
+    this._poll()
+    this._emit()
+  }
+
   available () { return true }
 
   // A trailing window, or an ABSOLUTE range when the caller passes fromMs/toMs — which
@@ -137,14 +228,67 @@ class RingHistoryProvider {
     return this._ring.filter((r) => r.t >= cutoff)
   }
 
-  getSeries ({ windowSec, fromMs, toMs } = {}) {
+  // `series` is the mean line, exactly as before. Two additive extras, both ignorable:
+  //   stats -> `bands`, the true per-bucket [t, min, max] under the mean;
+  //   chans -> narrow the answer to the channels actually plotted.
+  //
+  // `everySec` is now HONOURED. It used to be ignored outright, so the history sheet's
+  // 24 h pill got raw sample-rate points whatever the pill said. Rows are re-bucketed
+  // into everySec windows: means weighted by the sample count behind each row, extremes
+  // as min-of-mins / max-of-maxes, wrapped channels taking the last reading. Buckets are
+  // labelled at their END, matching the cloud's aggregateWindow(timeSrc: "_stop") — label
+  // them at the start and the two providers plot half a bucket apart on the same screen.
+  getSeries ({ windowSec, everySec, fromMs, toMs, stats, chans } = {}) {
     const rows = this._window(windowSec, fromMs, toMs)
+    const want = chans && chans.length ? new Set(chans) : null
+    const step = Math.max(0, Math.round(everySec || 0)) * 1000
     const series = {}
+    const bands = {}
     for (const c of CHANNELS) {
-      const pts = rows.filter((r) => r[c] != null).map((r) => [r.t, r[c]])
-      if (pts.length) series[c] = pts
+      if (want && !want.has(c)) continue
+      const wrapped = WRAPPED.has(c)
+      // With no `every`, every row is its own point — which is what this endpoint has
+      // always returned, and the contract says `series` is unchanged with or without the
+      // new params. (Bucketing by r.t instead would merge two rows sharing a millisecond,
+      // which never happens in flight but does when a caller drives the clock by hand.)
+      const buckets = new Map()
+      let seq = 0
+      for (const r of rows) {
+        const v = r[c]
+        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 }))
+        b.last = v
+        if (wrapped) 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.
+        const n = (r.n && r.n[c]) || 1
+        b.sum += v * n
+        b.n += n
+        const lo = (r.lo && r.lo[c] != null) ? r.lo[c] : v
+        const hi = (r.hi && r.hi[c] != null) ? r.hi[c] : v
+        if (lo < b.lo) b.lo = lo
+        if (hi > b.hi) b.hi = hi
+      }
+      const out = [...buckets.values()].sort((a, b) => a.t - b.t)
+      const pts = wrapped
+        ? out.map((b) => [b.t, b.last])
+        : out.filter((b) => b.n > 0).map((b) => [b.t, round3(b.sum / b.n)])
+      if (!pts.length) continue
+      series[c] = pts
+      // No `|| wrapped` here: the bucket loop above never accumulates a wrapped channel,
+      // so `n` stays 0 and the filter below drops it anyway. Keeping the extra condition
+      // would be unreachable code that no test can pin — and an unpinnable guard is the
+      // kind that quietly stops matching the guard it duplicates.
+      if (!stats) continue
+      const band = out
+        .filter((b) => b.n > 0 && Number.isFinite(b.lo) && Number.isFinite(b.hi))
+        .map((b) => [b.t, b.lo, b.hi])
+      if (band.length) bands[c] = band
     }
-    return { ok: true, series }
+    return stats ? { ok: true, series, bands } : { ok: true, series }
   }
 
   getTrack ({ windowSec, fromMs, toMs, everySec } = {}) {
@@ -224,8 +368,9 @@ class RingHistoryProvider {
 
   destroy () {
     clearInterval(this._timer)
+    clearInterval(this._pollTimer)
     this._compact() // final flush of the current ring
   }
 }
 
-module.exports = { RingHistoryProvider, MAX_SAMPLES, CHANNELS }
+module.exports = { RingHistoryProvider, MAX_SAMPLES, CHANNELS, WRAPPED }

package/lib/proxy/cache.js

@@ -43,6 +43,29 @@ async function readFromDisk (file, meta) {
   return { buffer, contentType }
 }
 
+// Gzip bytes stored as if they were the payload. This is what the pre-0.23.9 transport
+// did: core http hands back the still-compressed stream where fetch() decoded it, and the
+// bytes were cached — and tiles are PINNED, so the corruption outlived the fix by weeks.
+// Cesium read the gzip header as a vertex count: "Invalid typed array length:
+// 11239580910". 2,391 terrain tiles and 188 vector tiles on this boat were still poisoned
+// three days after the transport was fixed, because nothing ever re-examines a pinned
+// file.
+//
+// So a HIT is checked, which costs two bytes of a buffer already in hand. A file that
+// claims to be quantized-mesh or protobuf and begins 1f 8b is not that file; it is
+// dropped and re-fetched. Content that is LEGITIMATELY gzip (a .gz asset, or a
+// gzip content-type) is left alone — that is a payload, not an encoding.
+function looksGzipped (buffer) {
+  return buffer && buffer.length >= 2 && buffer[0] === 0x1f && buffer[1] === 0x8b
+}
+function gzipIsThePayload (contentType, reqPath) {
+  const ct = String(contentType || '').toLowerCase()
+  return ct.includes('gzip') || ct.includes('x-gzip') || /\.gz(\?|$)/i.test(String(reqPath || ''))
+}
+function isCorruptOnDisk (r, reqPath) {
+  return looksGzipped(r.buffer) && !gzipIsThePayload(r.contentType, reqPath)
+}
+
 // Fetch from upstream and persist atomically (bytes + content-type sidecar). The
 // rename stamps the file mtime ~now, which is what freshness compares against.
 async function fetchAndStore (url, file, meta, timeoutMs) {
@@ -112,7 +135,18 @@ async function getResource (opts) {
   const stat = await fsp.stat(file).catch(() => null)
   if (stat) {
     const stale = invalidatedAt && stat.mtimeMs < invalidatedAt
-    if (!stale) return serveDisk('HIT')
+    if (!stale) {
+      const hit = await serveDisk('HIT')
+      if (!isCorruptOnDisk(hit, reqPath)) return hit
+      // Left over from the transport that cached compressed bytes. Serving it again would
+      // reproduce the original error for ever, so drop it and fetch a clean copy. If that
+      // fails, FAIL: a renderer given a gzip header errors hard, where a missing tile
+      // simply falls back to its parent.
+      await fsp.unlink(file).catch(() => {})
+      await fsp.unlink(meta).catch(() => {})
+      if (downNow) throw offline('cached copy was corrupt (gzip) and the upstream is down')
+      try { return await tryFetch('REPAIRED') } catch (e) { noteFail(e); throw e }
+    }
     // A newer bake was announced; the on-disk copy predates it.
     if (downNow) return serveDisk('STALE')
     try { return await tryFetch('UPDATED') } catch (e) { noteFail(e); return serveDisk('STALE') }
@@ -149,4 +183,4 @@ async function clearStore ({ storeDir, keep = [], prefix = '' } = {}) {
   return { removed, mode: 'keep', kept: [...keepSet] }
 }
 
-module.exports = { getResource, storePaths, clearStore }
+module.exports = { getResource, storePaths, clearStore, isCorruptOnDisk }

package/lib/proxy/index.js

@@ -97,6 +97,7 @@ function createProxy (app, options) {
       aisTargets: options.aisTargets || null,
       profile: options.profile || null,
       alerts: options.alerts || null, // claims alertsEvaluatedHere in /api/config, see serveConfig
+      sails: options.sails || null, // the sail-plan write door; claims sailPlanWritable
       boat: options.boat || null, // { perfKey, slug } — patched into /api/config, see serveConfig
       openAccess: options.openAccess !== false
     }
@@ -266,6 +267,24 @@ function createProxy (app, options) {
     if (cfg.profile && cfg.profile.available() && cfg.profile.handles(req.url)) {
       return cfg.profile.handle(req, res)
     }
+    // Set which sails are up. The boat is the ONLY host that accepts this — the cloud
+    // answers 501 sail-write-not-here — because the plan reaches InfluxDB by being
+    // published as a SignalK delta here and spooled like every other value: one writer,
+    // offline-correct by construction, and no Influx write token in the cloud. Never
+    // proxied upstream, whatever the outcome.
+    if (req.method === 'POST' && cfg.sails && cfg.sails.available() &&
+        req.url.split('?')[0] === '/api/sails') {
+      return readJsonBody(req).then((body) => {
+        const r = cfg.sails.setPlan(body || {})
+        res.statusCode = r.ok ? 200 : (r.status || 400)
+        res.setHeader('Content-Type', 'application/json')
+        res.end(JSON.stringify(r.ok ? { ok: true, plan: r.plan, at: r.at } : { ok: false, code: r.code, message: r.message }))
+      }).catch((e) => {
+        res.statusCode = 500
+        res.setHeader('Content-Type', 'application/json')
+        res.end(JSON.stringify({ ok: false, code: 'sails-error', message: e.message }))
+      })
+    }
     // /api/config drives the app's login gate + Trends toggle. On the single-tenant
     // boat we serve it with auth turned off (no cloud login over the offline HTTP
     // mirror) and history forced on when we serve it locally. All other config passes
@@ -332,6 +351,14 @@ function createProxy (app, options) {
           // banner unless a host claims them — rules stored with nothing watching them is
           // the failure it is warning about. This plugin IS that host, on board, so say so.
           if (cfg.alerts && cfg.alerts.available()) j.alertsEvaluatedHere = true
+          // A CAPABILITY, not a deployment test: the sails screen is read-only unless a
+          // host says it can publish the delta. "Am I the cloud?" is the wrong question —
+          // the dev box runs the cloud server on a LAN and self-hosters run it as their
+          // edge, so a self-hosted single-boat cloud looks exactly like a boat otherwise.
+          if (cfg.sails && cfg.sails.available()) j.sailPlanWritable = true
+          // Display only. Nothing may branch on this — that is what the capability flags
+          // above are for; this exists so the UI can tell a human where data comes from.
+          j.deployment = 'boat'
           // The cloud fills `boat` only for a logged-in session, and the mirror forwards no
           // cookie — so it always arrived as null and the app had no identity. Harmless for
           // most of the UI, but public/engine/polar-cloud.js keys the performance data cloud

package/lib/sails/index.js

@@ -0,0 +1,86 @@
+'use strict'
+
+// The sail plan write door — the one place a sail plan enters the system.
+//
+// Sailkick records every instrument value but has no idea which sails are set, so the
+// polar estimator averages a full-main-and-genoa curve together with a
+// three-reefs-and-staysail one. Recording the plan as a time series is what will let it
+// tell them apart later.
+//
+// THE WRITE HAPPENS HERE AND NOWHERE ELSE. The app posts a plan to whichever server
+// served it, and only the boat's mirror accepts one; the cloud answers 501
+// `sail-write-not-here` so a stale client gets JSON it can show a human. The reasons are
+// worth restating because they are the whole design:
+//
+//   - <id>_raw stays a faithful mirror of the boat's own SignalK: one writer.
+//   - It is offline-correct for free. Sail changes happen at sea, which is exactly when
+//     the cloud is unreachable — the gapless spool already solves that, so the app needs
+//     no outbox of its own.
+//   - No Influx WRITE token has to live in the cloud next to the password hashes.
+//
+// Publishing is an ordinary SignalK delta on `sails.plan`, so everything downstream gets
+// it for nothing: lib/sync spools it to the cloud bucket like any other value (string
+// fields already work end to end — steering.autopilot.state proves it), the vendored
+// mapper turns it into BoatState.sailPlan, and the app's sails screen renders identically
+// on the boat and in the cloud.
+
+const { isCanonicalPlan, decodePlan, describePlan, BARE } = require('./sails')
+
+function createSails (app, options = {}) {
+  const log = (m) => (app.debug ? app.debug('[sails] ' + m) : console.log('[sailkick-boat:sails]', m))
+  const warn = (m) => (app.error ? app.error('[sailkick-boat:sails] ' + m) : console.error('[sailkick-boat:sails]', m))
+
+  let last = null // { plan, at } — what we published, for the status line
+  let writes = 0
+
+  // POST /api/sails  { plan: "<canonical string>" } -> { ok, plan } | { ok:false, ... }
+  function setPlan (body) {
+    const plan = body && typeof body.plan === 'string' ? body.plan.trim() : null
+    if (!plan) {
+      return { ok: false, status: 400, code: 'bad-plan', message: 'body must be { plan: "<sail plan>" }' }
+    }
+    // Round-trip validation with the VENDORED encoder, so nothing that would decode
+    // differently than it was written ever reaches SignalK. The sort order is the whole
+    // contract — it is the key the polar work groups by — and "main:0+genoa:0" is
+    // exactly the kind of string that looks right and hashes wrong.
+    if (!isCanonicalPlan(plan)) {
+      return {
+        ok: false,
+        status: 400,
+        code: 'bad-plan',
+        message: `"${plan}" is not a canonical sail plan. Expected <id>:<reefs> per set sail, joined by "+", sorted by id (e.g. "genoa:0+main:2"), or "${BARE}".`
+      }
+    }
+    if (!app.handleMessage) {
+      return { ok: false, status: 503, code: 'no-signalk', message: 'this plugin cannot publish to SignalK' }
+    }
+    const at = new Date().toISOString()
+    try {
+      app.handleMessage(options.pluginId || 'sailkick-boat', {
+        updates: [{ timestamp: at, values: [{ path: 'sails.plan', value: plan }] }]
+      })
+    } catch (e) {
+      warn('could not publish the sail plan: ' + e.message)
+      return { ok: false, status: 500, code: 'publish-failed', message: e.message }
+    }
+    last = { plan, at }
+    writes++
+    // Worth a normal log line, not a debug one: this is crew input, and "when did we put
+    // the second reef in" is a question people ask afterwards.
+    log(`sails: ${describePlan(plan)}  (${plan})`)
+    return { ok: true, plan, at }
+  }
+
+  function status () {
+    if (!last) return 'sails: none set yet'
+    return `sails: ${describePlan(last.plan)}${writes > 1 ? ` (${writes} changes)` : ''}`
+  }
+
+  // Mirrors lib/history / lib/alerts: the proxy asks before claiming, in /api/config,
+  // that this host can accept a sail plan.
+  function available () { return !!app.handleMessage }
+
+  return { setPlan, status, available, _last: () => last, _decode: decodePlan }
+}
+
+module.exports = { createSails }

package/lib/sails/sails.js

@@ -0,0 +1,180 @@
+// VENDORED from sailkick/shared/engine/sails.js @ 1571308  sha256:7965d2e3e610e9fd
+// Do not edit here — fix upstream and re-vendor. ONE definition of how a sail plan is
+// written down, or the same plan hashes two ways and silently splits the polar cloud
+// this feature exists to unify — visible only much later, as a mysteriously noisy polar.
+// test/sails.test.js replays the upstream suite against this copy to prove it matches.
+//
+// Converted ESM -> CommonJS ONLY (export keywords removed, module.exports appended).
+// No logic changed.
+//
+// The boat is the ONLY writer of a sail plan: the app posts one to whichever server
+// served it, and only this mirror accepts it (the cloud answers 501). That keeps
+// <id>_raw a faithful mirror of the boat's own SignalK with one writer, makes the write
+// offline-correct for free — sail changes happen at sea, which is exactly when the cloud
+// is unreachable, and the gapless spool already solves that — and keeps an Influx write
+// token out of the cloud next to the password hashes.
+
+// Sail plan — ONE definition of how a sail plan is written down, shared by every host
+// that records or reads one: the boat plugin (which publishes it onto SignalK) and the
+// cloud (which displays it and will later group polar samples by it). Pure and
+// dependency-free, like shared/engine/alerts.js, for the same reason: a second
+// implementation that disagrees is the failure mode this file exists to prevent.
+//
+// THE ENCODING
+//
+//   "genoa:0+main:0"        full main and full genoa
+//   "main:2+staysail:0"     two reefs, staysail, no headsail
+//   "genoa:2+stormjib:0"    genoa furled two steps AND the storm jib set
+//   "bare"                  nothing up
+//
+// `<id>:<reefs>` per ACTIVE sail, joined by "+", SORTED BY ID. Only sails that are
+// actually set appear — "main down" is simply the main's absence, not a `down` state.
+// That is what lets any combination be expressed: a cutter's genoa + staysail, a
+// heavy-weather partly-furled genoa + storm jib, twin headsails poled out downwind.
+// A fixed slot per station cannot say any of those, which is why there isn't one.
+//
+// SORTING IS THE WHOLE CONTRACT. The string is the join key the polar work will group
+// by, so the same sail plan MUST produce the same bytes every time. An encoder that
+// emitted insertion order would split one polar cloud into several that look unrelated
+// — silently, and only visible much later as a mysteriously noisy polar. Hence
+// encodePlan sorts, and the round-trip tests assert it.
+//
+// `bare` (rather than "") distinguishes "the crew says nothing is up" from "we have no
+// sail data at all", which is null/absent. Under bare poles in a survival storm that
+// distinction is real information.
+
+// A sail id: lowercase, url-safe, and free of the encoding's own delimiters.
+const ID_RE = /^[a-z0-9][a-z0-9-]{0,31}$/;
+const STATIONS = ['main', 'head', 'flying'];
+const SAIL_STATIONS = STATIONS;
+const BARE = 'bare';
+const MAX_REEFS = 5;
+const MAX_SAILS = 12;   // a plan longer than this is a bug or an attack, not a rig
+
+// The inventory a boat gets before anyone edits it. Deliberately over-complete: it is
+// far easier to delete the sails you don't carry than to remember the ones you do.
+// `reefs` is how many REDUCED steps the sail has below full — 0 means it is all-or-
+// nothing (a spinnaker is up or it isn't). For a furling headsail these are furl steps.
+const DEFAULT_INVENTORY = [
+  { id: 'main',      name: 'Mainsail',  station: 'main',   reefs: 3 },
+  { id: 'genoa',     name: 'Genoa',     station: 'head',   reefs: 2 },
+  { id: 'jib',       name: 'Jib',       station: 'head',   reefs: 1 },
+  { id: 'staysail',  name: 'Staysail',  station: 'head',   reefs: 0 },
+  { id: 'stormjib',  name: 'Storm jib', station: 'head',   reefs: 0 },
+  { id: 'trysail',   name: 'Trysail',   station: 'main',   reefs: 0 },
+  { id: 'code0',     name: 'Code 0',    station: 'flying', reefs: 0 },
+  { id: 'spinnaker', name: 'Spinnaker', station: 'flying', reefs: 0 },
+];
+
+// [{ id, reefs }] → the canonical string. Ignores entries with an unusable id, and
+// clamps a negative/NaN reef count to 0 rather than emitting a string that won't parse:
+// a UI bug must not be able to write an unreadable record into the boat's history.
+function encodePlan(sails) {
+  if (!Array.isArray(sails)) return BARE;
+  const seen = new Map();
+  for (const s of sails) {
+    const id = typeof s?.id === 'string' ? s.id.trim().toLowerCase() : '';
+    if (!ID_RE.test(id)) continue;
+    const n = Number(s.reefs);
+    seen.set(id, Number.isFinite(n) ? Math.max(0, Math.min(MAX_REEFS, Math.round(n))) : 0);
+  }
+  if (!seen.size) return BARE;
+  return [...seen.entries()]
+    .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))   // byte order, not locale
+    .map(([id, reefs]) => `${id}:${reefs}`)
+    .join('+');
+}
+
+// The canonical string → [{ id, reefs }], in the string's own (sorted) order.
+//
+// Deliberately TOLERANT: history outlives the inventory. A sail deleted from the boat's
+// inventory today still appears in every plan recorded before it went, and a decoder
+// that threw would take the whole screen — and later the whole polar split — down with
+// it. Unparseable segments are dropped; `null`/absent/unknown input decodes to [].
+function decodePlan(str) {
+  if (typeof str !== 'string') return [];
+  const s = str.trim();
+  if (!s || s === BARE) return [];
+  const out = [];
+  const seen = new Set();
+  for (const seg of s.split('+').slice(0, MAX_SAILS)) {
+    const i = seg.indexOf(':');
+    if (i < 0) continue;
+    const id = seg.slice(0, i).trim().toLowerCase();
+    if (!ID_RE.test(id) || seen.has(id)) continue;
+    const reefs = Number(seg.slice(i + 1).trim());
+    if (!Number.isInteger(reefs) || reefs < 0 || reefs > MAX_REEFS) continue;
+    seen.add(id);
+    out.push({ id, reefs });
+  }
+  return out;
+}
+
+// True when the string is one this encoder could have produced. Used at the write door:
+// the boat validates an incoming plan by round-tripping it, so nothing that would decode
+// differently than it was written ever reaches SignalK.
+function isCanonicalPlan(str) {
+  return typeof str === 'string' && encodePlan(decodePlan(str)) === str.trim();
+}
+
+// The key polar samples will be GROUPED BY. Identity today — the plan string already is
+// the key. It exists as a named seam because the polar work will want to coarsen plans
+// into equivalence classes (a code 0 barely changes the upwind curve; a reef does), and
+// when it does, that decision belongs here next to the encoding rather than scattered
+// through the estimator.
+function sailPlanKey(str) {
+  return typeof str === 'string' && str.trim() ? str.trim() : null;
+}
+
+// Render a plan for a human: "2 reefs · Staysail". `inventory` supplies display names;
+// a sail missing from it falls back to its id, so historical plans stay readable after
+// the sail is deleted. Returns '—' for no data, 'Bare poles' for an explicit bare.
+function describePlan(str, inventory = DEFAULT_INVENTORY) {
+  if (typeof str !== 'string' || !str.trim()) return '—';
+  if (str.trim() === BARE) return 'Bare poles';
+  const byId = new Map((inventory || []).map((s) => [s.id, s]));
+  const parts = decodePlan(str).map(({ id, reefs }) => {
+    const name = byId.get(id)?.name || id;
+    if (!reefs) return name;
+    // The main is reefed; a furling headsail is furled. Same integer, different word —
+    // saying "1 reef" about a genoa reads wrong to anyone who has actually sailed.
+    return byId.get(id)?.station === 'main'
+      ? `${reefs} reef${reefs > 1 ? 's' : ''}`
+      : `${name} −${reefs}`;
+  });
+  return parts.length ? parts.join(' · ') : 'Bare poles';
+}
+
+// Validate one INVENTORY item (not a plan) — the profile section's write guard, in the
+// shape of validateRule() in shared/engine/alerts.js. A malformed sail stores looking
+// fine and then silently mislabels every polar sample recorded against it, so it is
+// rejected at the door rather than tolerated.
+function validateSail(s) {
+  if (!s || typeof s !== 'object') return { ok: false, error: 'sail must be an object' };
+  const id = typeof s.id === 'string' ? s.id.trim().toLowerCase() : '';
+  if (!ID_RE.test(id)) {
+    return { ok: false, error: `sail id "${s.id}" must be lowercase letters, digits or dashes (max 32) — it is written into every recorded plan` };
+  }
+  if (typeof s.name !== 'string' || !s.name.trim() || s.name.length > 40) {
+    return { ok: false, error: 'sail name is required (max 40 characters)' };
+  }
+  if (!STATIONS.includes(s.station)) {
+    return { ok: false, error: `sail station "${s.station}" must be one of ${STATIONS.join(', ')}` };
+  }
+  if (!Number.isInteger(s.reefs) || s.reefs < 0 || s.reefs > MAX_REEFS) {
+    return { ok: false, error: `sail reefs must be a whole number between 0 and ${MAX_REEFS}` };
+  }
+  return { ok: true };
+}
+
+module.exports = {
+  encodePlan,
+  decodePlan,
+  isCanonicalPlan,
+  sailPlanKey,
+  describePlan,
+  validateSail,
+  DEFAULT_INVENTORY,
+  SAIL_STATIONS,
+  BARE
+}

package/lib/telemetry/contract.js

@@ -27,10 +27,10 @@
 // old path no longer existed. They now fail rather than skip when the checkout is present
 // and the file is not; a guard that disappears when its subject moves is not a guard.
 
-// sha256(app shared/engine/signalk-map.js)[0..12] as ported in v0.18.6
+// sha256(app shared/engine/signalk-map.js)[0..12] as ported in v0.30.0 (the sails merge)
 const { request } = require('../net') // owned connection pool + real error codes
 
-const PINNED_APP_HASH = '3e42369c002b'
+const PINNED_APP_HASH = 'fd79e3688591'
 
 function createContractCheck (app, options = {}) {
   const warn = (m) => (app.error ? app.error('[sailkick-boat:contract] ' + m) : console.error('[sailkick-boat:contract]', m))

package/lib/telemetry/signalk-map.js

@@ -1,12 +1,13 @@
-// VENDORED from sailkick/shared/engine/signalk-map.js @ dc57057  sha256:3e42369c002b7cb7
-// (the app moved it public/engine -> shared/engine in 8fd58cf; content and hash unchanged)
+// VENDORED from sailkick/shared/engine/signalk-map.js @ 1571308  sha256:fd79e368859133d8
 // Do not edit here — fix upstream and re-vendor. One SignalK -> BoatState mapping, or
 // the boat and the app quietly disagree (it has drifted twice; both times silently).
 //
 // Converted ESM -> CommonJS ONLY. No logic changed.
 //
-// Re-vendored after b519a9f (course + depth precedence) and 348c3d9 (heading true
-// authoritative) — both of which came from findings handed over from this repo.
+// Re-vendored after b519a9f (course + depth precedence), 348c3d9 (heading true
+// authoritative) — both from findings handed over from this repo — and the sails merge
+// (1571308), which adds the `sails.plan` case: the boat's mirror is the only writer of
+// that path, so this copy has to understand what it publishes.
 
 // SignalK → BoatState mapping — pure, dependency-free, so it's shared by both
 // the client provider (public/ui/boat-panel.js, browser WebSocket) and the
@@ -152,6 +153,17 @@ function signalkValuesToPatch(values) {
       case 'navigation.datetime':                 // GNSS UTC time (from the satellites)
         if (typeof v.value === 'string') patch.gpsTime = v.value;
         break;
+      // Which sails are set — a canonical plan string (shared/engine/sails.js), not a
+      // sensor reading: the crew publishes it from the app. Kept VERBATIM here; this
+      // mapper stays pure string-passing and the encoding lives in one place.
+      //
+      // A null is SKIPPED, like every sensor path and unlike the course paths above:
+      // the plan is a step function, so "the source went quiet" must leave the last
+      // known plan standing, not blank it. "Nothing is up" is the explicit string
+      // `bare`, which is exactly why that sentinel exists.
+      case 'sails.plan':
+        if (typeof v.value === 'string' && v.value.trim()) patch.sailPlan = v.value.trim();
+        break;
       default:
         break; // ignore everything else
     }

package/package.json

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