sailkick-boat 0.29.0 → 0.31.0

package/README.md

@@ -363,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
@@ -745,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/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/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/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.29.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": {