sailkick-boat 0.23.8 → 0.27.0

package/README.md

@@ -52,6 +52,13 @@ files to send later — nothing is lost in the gap.
 
 - Network errors, `429` and `5xx` are retried with backoff (1 s → 60 s); the data stays
   on disk.
+- **Responses are decoded and checked for completeness.** Core `https` does neither, and
+  `fetch` did both silently: the upstream serves terrain tiles pre-compressed with
+  `Content-Encoding: gzip` whether asked to or not, so for one release the mirror cached
+  gzip bytes labelled as terrain and Cesium read the gzip header as a vertex count
+  ("Invalid typed array length: 11239580910"). A body shorter than its `Content-Length` is
+  now rejected too — tiles are pinned once written, so a truncated one would be served for
+  ever.
 - **All cloud traffic uses core `https`, not `fetch`** — telemetry sync, the offline
   mirror, the cache-manifest poller, the contract check, the backfill and the Sync page
   share one connection pool (`lib/net.js`), so one reset clears every subsystem. Twice in one afternoon this boat's
@@ -341,6 +348,106 @@ 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.
 
+## Alerts and alarms, evaluated on board
+
+Rules — anchor drag, wind over or under a threshold, a big wind shift, boat speed below
+polar — are evaluated **here**, in the SignalK process, against the boat's own bus. That
+is the point: the case this exists for is the anchor dragging at 3am with the phone in
+airplane mode and no uplink, which a cloud watcher cannot help with.
+
+The rule **evaluator** is vendored verbatim from the app (`shared/engine/alerts.js`, with
+its commit and sha256 in the header), exactly as the polar maths is. One definition of
+"has this rule fired", or an alarm means one thing when the boat notices and another when
+the cloud does. `test/alerts.test.js` replays the upstream suite against the vendored copy
+— flapping, wrap-around, anchor swing, data gaps, the position-source conflict and the
+two-clocks contract — and pins the boat-side host as well.
+
+**Delivery is SignalK notifications**, which is what makes this worth more than another
+screen: an alarm panel, a chart app or a Node-RED buzzer flow already listens to them.
+
+```
+notifications.navigation.anchor    anchor drag  — state "alarm",  method visual + sound
+notifications.sailkick.<ruleId>    everything else — state "alert", method visual
+```
+
+Only anchor drag takes a conventional path: a boat has one anchor, so it cannot collide,
+and it is the rule other software reacts to. Wind rules get a path of their own per rule,
+because "over 30 kt" and "under 5 kt" are two rules a sailor plausibly sets at once, and
+one shared path would make each transition overwrite the other's state. Clearing is
+`state: "normal"`, per the schema — the path is never deleted. A rule may carry its own
+`state`/`method`, validated against the SignalK enums (`nominal|normal|alert|warn|alarm|
+emergency`, `visual|sound`).
+
+**Alarms reach the cloud through the telemetry spool.** A transition is written as one
+row of Influx line protocol and handed to the same store-and-forward buffer as every other
+channel, so it inherits what that buffer was built for: ordered, gapless, nothing lost to
+a failed POST or a restart, and an alarm raised mid-ocean arrives when the link does. It
+also makes alarm history queryable afterwards — *when did we drag?* The schema:
+
+```
+alerts,context=vessels.<urn>,self=true,rule=<id>,kind=<kind>
+  raised=1i,transition="raised",state="alarm",message="…",value=111,name="Anchor" <ns>
+```
+
+`rule` and `kind` are the only tags — both bounded and stable, so cardinality stays flat.
+`transition` and `state` are deliberately **fields**: keeping them out of the series key
+means one series per rule, so "is this raised right now" is `last(raised)` on a single
+series rather than a merge-and-compare across two — a query that is easy to get wrong, and
+wrong in the direction of *no alarm*. Feed conditions ride the same measurement under
+`rule=__feed__`. With no cloud account configured, alarms still ring on board and the
+status line says `local only (no cloud sync)` rather than letting you assume otherwise.
+
+Our own notifications are **not** also uploaded through the generic delta path — they
+would arrive a second time as flattened `notifications.*` rows, describing the same event
+in a worse shape in a namespace that means "a device's own condition". Every other
+plugin's notifications (the Victron monitors, the server's own) are untouched.
+
+**Drop anchor** — `POST /api/alerts/anchor {ruleId}` — writes the boat's current fix into
+the rule and arms the watch in the same step. The datum goes into the *rule* because the
+evaluator's in-memory one does not survive a restart or a rule edit, both of which happen
+at anchor; and it is taken from the boat's own fix because that is the position the rule
+will be evaluated against. A browser would send whatever its last telemetry frame said,
+from a socket that may have dropped — which is exactly the moment this matters.
+
+**Rules live on the boat**, in the profile beside routes and polars
+(`/api/profile/alerts`), and that copy is deliberately **not** synced with the cloud. For
+alarms that is the right way round: a rule edited from ashore must not silently change
+what the boat alarms on mid-passage.
+
+Three behaviours worth knowing, because each is a way an alarm system becomes useless:
+
+- **Editing a rule re-arms its alarm.** A rebuilt evaluator has no memory of the raise, so
+  anything currently up is taken down explicitly and comes back after its hold time if the
+  condition still holds. The alternative is a notification latched at `alarm` that nothing
+  can ever clear — which is how an owner learns to mute the path.
+- **Stopping the plugin clears what it raised**, loudly, for the same reason: nothing will
+  evaluate the rule while it is stopped.
+- **A dead feed is not an alarm.** It goes to the status line and the log. It also never
+  clears a raised alarm: the input going away is not evidence the danger did.
+
+**Two sources on `navigation.position` disable the anchor alarm — silently.** Not by
+false-alarming: the far source reads as *outside* the circle and the good one as *inside*,
+and since a raise needs the condition to hold continuously, the alternation resets the
+hold time for ever and the alarm never fires at all. This boat had exactly that before its
+position source was pinned — a second source a median 2.3 km away, jumping up to 22.7 km
+between fixes, while the good receiver at rest scattered a median **1.88 m** from its
+centroid (max 2.91 m over 90 minutes). The evaluator now reports it as a feed condition
+(three implausible jumps in five minutes), and the plugin says so in the log and on the
+status line, naming the fix: set a source priority for `navigation.position`. Metres of
+ordinary GPS scatter never trip it.
+
+**A malformed rule is dropped, not stored looking armed.** Rules are validated with the
+app's own `validateRule` (vendored with the evaluator), because the evaluator treats an
+unknown kind — or a deadband on the wrong side of the threshold, which could never clear —
+as *inert*. Such a rule would otherwise sit in the list looking active and never fire. The
+status line counts them and the log names each one and why.
+
+**Feed staleness and clocks.** Rules are evaluated on the SignalK timestamp, so the timing
+is the data's own, not the machine's — but staleness has to be measured on wall clock (a
+dead feed is exactly a timestamp that stops moving). The two are reconciled by bounding
+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".
+
 ## Two paths, one reading
 
 Source priorities solve *several devices on one path*. There is a second, separate case:
@@ -605,8 +712,16 @@ 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/track?window=3600s            -> { track: [{ t, lat, lon }, …] }
+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)
 ```
+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.
+
 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
 available at all do these paths **fall through to the cloud mirror**, so an
@@ -665,6 +780,8 @@ in `index.js`.
 - **Sailkick account**: `slug` (boat name), `writeToken`
 - **Telemetry sync → cloud**: `enabled`
 - **Upload AIS targets**: `enabled` (default off), `source`
+- **Alerts & alarms**: `enabled` (default on — inert until you add a rule),
+  `notifications` (whether to put alarms on the SignalK bus)
 - **Offline app & maps**: `enabled`, `proxyPort` (default 8080), `localSignalkUrl`
   (default `http://127.0.0.1:3000`), `dataDir`, `seedEnabled`, `prefetchRadiusNm`,
   `prefetchDetailZoom`

package/index.js

@@ -11,6 +11,7 @@ const { createAis } = require('./lib/ais')
 const { createAisTargets } = require('./lib/ais/targets')
 const { createProfile } = require('./lib/profile')
 const { createPerf } = require('./lib/perf')
+const { createAlerts } = require('./lib/alerts')
 const { createCloud } = require('./lib/cloud')
 const { resolveAccountConfig } = require('./lib/account')
 
@@ -107,6 +108,7 @@ module.exports = function (app) {
   let profile = null
   let cloud = null
   let perf = null
+  let alerts = null
   let proxyPort = null // what the launcher page needs to build its links
   let pairedSlug = null
   let statusTimer = null
@@ -165,6 +167,15 @@ module.exports = function (app) {
           sourceBucket: { type: 'string', title: '…bucket', default: 'signalk' }
         }
       },
+      alerts: {
+        type: 'object',
+        title: 'Alerts & alarms',
+        description: 'Watch this boat\'s own data and raise SignalK notifications — anchor drag, wind over or under a threshold, a big wind shift, speed below polar. Evaluated here on board, so an anchor alarm still works with the phone in airplane mode and no internet. The rules themselves are set in the app (they are stored on the boat, not in the cloud); nothing is raised until you add one.',
+        properties: {
+          enabled: { type: 'boolean', title: 'Evaluate alert rules', default: true },
+          notifications: { type: 'boolean', title: 'Raise SignalK notifications', description: 'Puts alarms on the SignalK bus, where chart apps, alarm panels and buzzers pick them up (anchor drag goes to the conventional notifications.navigation.anchor). Turn off to evaluate rules without touching the bus.', default: true }
+        }
+      },
       proxy: {
         type: 'object',
         title: 'Offline app & maps',
@@ -239,6 +250,9 @@ module.exports = function (app) {
         bucket: b.bucket || s.bucket,
         token: b.writeToken || s.token,
         spoolDir,
+        // So sync can tell OUR notifications from every other plugin's: ours are relayed
+        // as `alerts` rows and must not also go up flattened (lib/sync ownNotificationsStripped).
+        pluginId: plugin.id,
         batchSize: s.batchSize || SYNC_TUNING.batchSize,
         flushIntervalMs: s.flushIntervalMs || SYNC_TUNING.flushIntervalMs,
         maxBufferBytes: s.maxBufferBytes || SYNC_TUNING.maxBufferBytes,
@@ -383,6 +397,34 @@ module.exports = function (app) {
         }
       }
 
+      // Alert rules, evaluated on board. After perf, because perf-below reads the polar %
+      // it computes; needs telemetry for everything else. Inert until the owner adds a
+      // rule, so it is on by default.
+      if (telemetry && (opts.alerts || {}).enabled !== false) {
+        try {
+          alerts = createAlerts(app, {
+            source: telemetry,
+            perfSource: perf,
+            pluginId: plugin.id,
+            notifications: (opts.alerts || {}).notifications !== false,
+            // The cloud half: transitions ride the telemetry spool as `alerts` rows, so an
+            // alarm raised offshore arrives when the link does instead of being lost.
+            // Null when sync is off — alarms then ring on board only, and say so.
+            relay: sync ? (lines) => sync.writeLines(lines) : null,
+            context: app.selfContext || ('vessels.' + (app.selfId || 'self')),
+            // For "drop anchor": the datum is written into the rule through the profile's
+            // own serialized queue, so it survives a restart and cannot race an app save.
+            profile,
+            profileFile: path.join((app.getDataDirPath && app.getDataDirPath()) || '.', 'profile.json')
+          })
+          alerts.start()
+          pOpts.alerts = alerts // so /api/config can say the rules are evaluated here
+        } catch (e) {
+          (app.error || console.error)('[sailkick-boat] alerts start failed: ' + e.message)
+          alerts = null
+        }
+      }
+
       if (pOpts.history.enabled !== false) {
         try {
           // ringSource = the telemetry module: when no local InfluxDB token is set
@@ -487,6 +529,7 @@ module.exports = function (app) {
     if (aisTargets) parts.push(aisTargets.status())
     if (profile) parts.push(profile.status())
     if (perf) parts.push(perf.status())
+    if (alerts) parts.push(alerts.status())
     if (ais) parts.push(ais.status())
     if (backfill) parts.push(backfill.status())
     try { app.setPluginStatus(parts.join('   |   ') || 'idle (both features off)') } catch {}
@@ -502,6 +545,7 @@ module.exports = function (app) {
     try { if (profile) profile.stop() } catch {}
     try { if (cloud) cloud.stop() } catch {}
     try { if (perf) perf.stop() } catch {}
+    try { if (alerts) alerts.stop() } catch {}
     try { if (ais) ais.stop() } catch {}
     try { if (backfill) backfill.stop() } catch {}
     try { if (proxy) proxy.stop() } catch {}
@@ -514,6 +558,7 @@ module.exports = function (app) {
     profile = null
     cloud = null
     perf = null
+    alerts = null
     proxyPort = null
     pairedSlug = null
     proxy = null

package/lib/alerts/alerts.js

@@ -0,0 +1,314 @@
+// VENDORED from sailkick/shared/engine/alerts.js @ d54bfc1  sha256:aeac568257bb2acc
+// Do not edit here — fix upstream and re-vendor. ONE definition of "has this rule fired",
+// or an alarm means one thing on the boat and another in the cloud. test/alerts.test.js
+// replays the upstream suite (tests/test-alerts.mjs) against this copy to prove it, and
+// test/vendored.test.js fails if this header's hash stops matching the app source.
+//
+// Converted ESM -> CommonJS ONLY (imports rewritten to require, export keywords removed,
+// module.exports appended). No logic changed.
+//
+// The two upstream imports:
+//   wrap180        <- shared/engine/perf-live.js, which this repo already vendors
+//                     (lib/perf/perf-live.js @ sha256:7ce83a1df13926f0)
+//   greatCircleKm  <- shared/engine/wind-field.js:256, copied alone into ./great-circle.js
+//                     rather than vendoring a grid-generation module for one haversine.
+//                     alerts.js itself now uses it, for the position-conflict detector.
+
+// Alert engine — ONE definition of "has this rule fired", shared by every host that will
+// evaluate it: the boat plugin (vendored, so anchor drag alarms with no internet) and the
+// cloud watcher (so you hear about it from ashore). Same evaluator both sides, or a rule
+// means two different things depending on who noticed — the drift shared/engine/perf-live.js
+// was extracted to kill.
+//
+// Pure, and deliberately narrow: rules in, state TRANSITIONS out. No timers, no delivery,
+// no notion of a buzzer or a push token, and no Date.now() of its own — the caller passes
+// `now`, so a host can replay recorded history through it and get the same answers. That
+// is also what makes the hard parts below testable.
+//
+// See docs/DESIGN-alerts.md.
+//
+//   const engine = createAlertEngine(rules);
+//   const events = engine.update(boatState, sampleMs);   // [] most ticks
+//   const feed   = engine.tick(wallClockMs);             // feed health
+//
+// TWO CLOCKS, AND THEY MUST DIFFER. `update` takes the SAMPLE's own timestamp
+// (Date.parse(state.updatedAt)) so time-weighted state replays deterministically. `tick`
+// takes the WALL CLOCK. Passing the sample stamp to both is the trap: a frozen feed keeps
+// handing back the same state, so the sample stamp stops advancing, `now - lastSample`
+// stays 0, and staleness NEVER fires — the feed dies exactly when the one condition that
+// would tell you cannot. (The boat plugin hit precisely this; its stale test caught it.)
+//
+// `perfPct` is NOT a BoatState field — nothing in server/telemetry/interface.js defines
+// it. A host that wants the `perf-below` rule must inject it (the boat plugin does, from
+// its perf module); otherwise that rule reads undefined and, correctly but uselessly,
+// never fires.
+//
+// Each event: { ruleId, kind, transition: 'raised'|'cleared', at, reason, context }
+
+const { wrap180 } = require('../perf/perf-live')
+const { greatCircleKm } = require('./great-circle')
+
+// Absent telemetry is `undefined` on the boat and `null` in the cloud — neither is a
+// number, and a rule that treats either as 0 fires the moment a sensor is missing.
+const num = (v) => (Number.isFinite(v) ? v : null);
+
+const DEFAULT_FOR_SEC = 30;      // a condition must hold this long before raising
+const DEFAULT_CLEAR_SEC = 30;    // …and fail this long before clearing
+// Default only — overridable per engine (`createAlertEngine(rules, { staleSec })`). A host
+// watching a live SignalK feed wants seconds; the cloud heartbeat, which sees a boat only
+// as often as its link allows, wants many minutes.
+const STALE_SEC = 120;
+const M_PER_KM = 1000;
+
+// Two SignalK sources publishing navigation.position produce a position that teleports
+// between them. Measured on a real boat: a median 2.3 km apart, jumps to 22.7 km. That
+// does NOT false-alarm an anchor watch — it makes it NEVER FIRE, because the fixes take
+// turns being outside the circle and reset the hold time for ever. Silent, and the worst
+// possible outcome, so the feed reports it rather than the rule swallowing it.
+const MAX_PLAUSIBLE_KT = 100;    // no sailing vessel; this is two sources or a glitch
+const JUMP_WINDOW_MS = 300_000;         // …counted over 5 minutes
+const JUMP_COUNT = 3;                   // one glitch is noise; three is a conflict
+
+// ---- rule kinds -------------------------------------------------------------
+// Each returns { active, value } — `active` is "the raw condition is true RIGHT NOW",
+// before any hold/deadband smoothing. `null` means "cannot tell" (missing input), which
+// is NOT the same as false and must never clear a raised alarm.
+
+const KINDS = {
+  // { kind:'wind-above', twsKt:25, clearKt?:22 }
+  'wind-above': (r, s) => {
+    const v = num(s.twsKt);
+    if (v == null) return null;
+    return { active: v >= r.twsKt, clearActive: v >= (r.clearKt ?? r.twsKt), value: v };
+  },
+  'wind-below': (r, s) => {
+    const v = num(s.twsKt);
+    if (v == null) return null;
+    return { active: v <= r.twsKt, clearActive: v <= (r.clearKt ?? r.twsKt), value: v };
+  },
+  // { kind:'perf-below', pct:80 } — the channel the boat now computes.
+  'perf-below': (r, s) => {
+    const v = num(s.perfPct);
+    if (v == null) return null;
+    return { active: v <= r.pct, clearActive: v <= (r.clearPct ?? r.pct), value: v };
+  },
+};
+
+// ---- validation -------------------------------------------------------------
+// Lives here, not in the route, because every host needs the same answer: the server on
+// write, the UI before submitting, the boat plugin once it vendors this. A malformed rule
+// must be REJECTED rather than stored — the engine treats an unknown kind as inert, so a
+// bad rule would otherwise sit in the list looking armed and never fire, which is the
+// worst possible failure for an alarm.
+const SPEC = {
+  'wind-above':   { req: [['twsKt', 0, 100]],   dead: ['clearKt', 'below'] },
+  'wind-below':   { req: [['twsKt', 0, 100]],   dead: ['clearKt', 'above'] },
+  'perf-below':   { req: [['pct', 0, 200]],     dead: ['clearPct', 'above'] },
+  'wind-shift':   { req: [['deg', 1, 180]],     dead: ['clearDeg', 'below'] },
+  'anchor-drift': { req: [['radiusM', 5, 5000]], dead: ['clearRadiusM', 'below'] },
+};
+
+const RULE_KINDS = Object.keys(SPEC);
+
+// → { ok: true, rule } | { ok: false, error }
+function validateRule(r) {
+  if (!r || typeof r !== 'object') return { ok: false, error: 'rule must be an object' };
+  const spec = SPEC[r.kind];
+  if (!spec) return { ok: false, error: `unknown kind "${r.kind}" — expected one of ${RULE_KINDS.join(', ')}` };
+
+  for (const [field, lo, hi] of spec.req) {
+    const v = r[field];
+    if (!Number.isFinite(v)) return { ok: false, error: `${r.kind}.${field} is required and must be a number` };
+    if (v < lo || v > hi) return { ok: false, error: `${r.kind}.${field} must be between ${lo} and ${hi}` };
+  }
+  for (const [field] of [['forSec'], ['clearSec'], ['windowSec']]) {
+    if (r[field] !== undefined && (!Number.isFinite(r[field]) || r[field] < 0 || r[field] > 86400)) {
+      return { ok: false, error: `${field} must be a number of seconds between 0 and 86400` };
+    }
+  }
+  // A deadband on the WRONG SIDE of the threshold is the subtle one: clearing a
+  // "wind above 25" at 30 means the rule can never clear, so the alarm latches forever
+  // and the user has no way to see why.
+  const [deadField, side] = spec.dead;
+  const dead = r[deadField];
+  if (dead !== undefined) {
+    if (!Number.isFinite(dead)) return { ok: false, error: `${deadField} must be a number` };
+    const threshold = r[spec.req[0][0]];
+    const wrong = side === 'below' ? dead > threshold : dead < threshold;
+    if (wrong) {
+      return { ok: false, error: `${deadField} (${dead}) must be ${side === 'below' ? 'at or below' : 'at or above'} `
+        + `${spec.req[0][0]} (${threshold}), or the alarm can never clear` };
+    }
+  }
+  if (r.kind === 'anchor-drift' && r.anchor !== undefined) {
+    const a = r.anchor;
+    if (!a || !Number.isFinite(a.lat) || !Number.isFinite(a.lon) || Math.abs(a.lat) > 90 || Math.abs(a.lon) > 180) {
+      return { ok: false, error: 'anchor must be { lat, lon } in range' };
+    }
+  }
+  return { ok: true, rule: r };
+}
+
+// ---- the engine -------------------------------------------------------------
+
+function createAlertEngine(rules = [], { staleSec = STALE_SEC } = {}) {
+  // Per-rule state. `raised` is the only thing a host ultimately cares about; the rest
+  // exists to stop it flapping.
+  const st = new Map();
+  const stateOf = (id) => {
+    if (!st.has(id)) st.set(id, { raised: false, since: null, failingSince: null, hist: [], anchor: null, lastSeen: null });
+    return st.get(id);
+  };
+  let staleRaised = false, lastState = null;
+  let jumpyRaised = false, lastFix = null, jumps = [];
+
+  // Wind shift is a CHANGE over a window, so it needs its own history rather than an
+  // instantaneous test. Compared shortest-path: a veer 350°→010° is 20°, not 340°.
+  function windShift(r, s, now, k) {
+    const d = num(s.twdDeg);
+    if (d == null) return null;
+    const win = (r.windowSec ?? 600) * 1000;
+    k.hist.push({ t: now, d });
+    while (k.hist.length && k.hist[0].t < now - win) k.hist.shift();
+    // Largest excursion from the OLDEST sample in the window — a slow steady veer and a
+    // sudden shift both matter, and comparing only first-vs-last would miss a shift that
+    // partly recovered within it.
+    let worst = 0;
+    for (const p of k.hist) {
+      const delta = Math.abs(wrap180(d - p.d));
+      if (delta > worst) worst = delta;
+    }
+    // Not enough history yet to make a claim — "cannot tell", not "false".
+    if (k.hist.length < 2 || now - k.hist[0].t < Math.min(win, (r.forSec ?? DEFAULT_FOR_SEC) * 1000)) return null;
+    return { active: worst >= r.deg, clearActive: worst >= (r.clearDeg ?? r.deg), value: Math.round(worst) };
+  }
+
+  // Anchor drift. The anchor is EXPLICIT (r.anchor = {lat, lon}) because inferring where
+  // the hook went down is the kind of cleverness that fails silently at 3am. A boat at
+  // anchor swings and a stationary GPS wanders tens of metres, so the raise still rides
+  // the hold time like every other rule.
+  function anchorDrift(r, s, k) {
+    const lat = num(s.lat), lon = num(s.lon);
+    const a = r.anchor || k.anchor;
+    if (lat == null || lon == null || !a || !Number.isFinite(a.lat) || !Number.isFinite(a.lon)) return null;
+    const m = greatCircleKm(a.lat, a.lon, lat, lon) * M_PER_KM;
+    return { active: m >= r.radiusM, clearActive: m >= (r.clearRadiusM ?? r.radiusM * 0.8), value: Math.round(m) };
+  }
+
+  function evaluate(r, s, now, k) {
+    if (r.kind === 'wind-shift') return windShift(r, s, now, k);
+    if (r.kind === 'anchor-drift') return anchorDrift(r, s, k);
+    const fn = KINDS[r.kind];
+    return fn ? fn(r, s) : null;
+  }
+
+  return {
+    // One tick. Returns the transitions that happened THIS tick (usually none).
+    update(s, now) {
+      const events = [];
+      if (!s || typeof s !== 'object') return events;
+      lastState = now;
+
+      // Position sanity, from the fixes themselves — the evaluator never sees SignalK
+      // sources, but an impossible speed between consecutive fixes is the same evidence.
+      const plat = num(s.lat), plon = num(s.lon);
+      if (plat != null && plon != null) {
+        if (lastFix && now > lastFix.t) {
+          const kt = (greatCircleKm(lastFix.lat, lastFix.lon, plat, plon) / 1.852) / ((now - lastFix.t) / 3600e3);
+          if (kt > MAX_PLAUSIBLE_KT) jumps.push(now);
+        }
+        lastFix = { t: now, lat: plat, lon: plon };
+      }
+
+      for (const r of rules) {
+        if (r.enabled === false) continue;
+        const k = stateOf(r.id);
+        const res = evaluate(r, s, now, k);
+
+        // "Cannot tell" — a missing sensor or too little history. Hold whatever state the
+        // rule is in. Critically this does NOT clear a raised alarm: the input going away
+        // is not evidence the danger did.
+        if (res == null) { k.since = null; k.failingSince = null; continue; }
+        k.lastSeen = now;
+
+        const forMs = (r.forSec ?? DEFAULT_FOR_SEC) * 1000;
+        const clearMs = (r.clearSec ?? DEFAULT_CLEAR_SEC) * 1000;
+
+        if (!k.raised) {
+          // Rising edge: the condition must hold for forSec. Wind hovering on a threshold
+          // otherwise fires every tick, and an alarm people learn to ignore has stopped
+          // being an alarm.
+          if (res.active) {
+            k.since ??= now;
+            if (now - k.since >= forMs) {
+              k.raised = true; k.since = null; k.failingSince = null;
+              events.push({ ruleId: r.id, kind: r.kind, transition: 'raised', at: now,
+                reason: r.name || r.kind, context: { value: res.value, rule: r } });
+            }
+          } else k.since = null;
+        } else {
+          // Falling edge rides a DEADBAND (clearKt / clearDeg / clearRadiusM), so the
+          // clear threshold is deliberately not the raise threshold.
+          if (!res.clearActive) {
+            k.failingSince ??= now;
+            if (now - k.failingSince >= clearMs) {
+              k.raised = false; k.failingSince = null; k.since = null;
+              events.push({ ruleId: r.id, kind: r.kind, transition: 'cleared', at: now,
+                reason: r.name || r.kind, context: { value: res.value, rule: r } });
+            }
+          } else k.failingSince = null;
+        }
+      }
+      return events;
+    },
+
+    // Staleness is its own condition, not a rule outcome: the feed dying is worth knowing
+    // in itself, and it must never be confused with a rule clearing. Hosts call this on
+    // their own tick so it fires even when no state is arriving at all.
+    tick(now) {
+      if (lastState == null) return [];
+      const out = [];
+      const stale = now - lastState >= staleSec * 1000;
+      if (stale !== staleRaised) {
+        staleRaised = stale;
+        out.push({ ruleId: '__feed__', kind: 'feed-stale', transition: stale ? 'raised' : 'cleared',
+          at: now, reason: 'telemetry feed', context: { lastStateAt: lastState } });
+      }
+      // Prune against the SAMPLE times already recorded, not this wall clock, so a quiet
+      // period ages the evidence out rather than a busy one hiding it.
+      const cut = (lastFix?.t ?? lastState) - JUMP_WINDOW_MS;
+      jumps = jumps.filter((t) => t >= cut);
+      const jumpy = jumps.length >= JUMP_COUNT;
+      if (jumpy !== jumpyRaised) {
+        jumpyRaised = jumpy;
+        out.push({ ruleId: '__feed__', kind: 'position-jumpy', transition: jumpy ? 'raised' : 'cleared',
+          at: now, reason: 'position source conflict',
+          context: { jumps: jumps.length, overKt: MAX_PLAUSIBLE_KT } });
+      }
+      return out;
+    },
+
+    // Current state, for a status line or an API — not the transition stream.
+    get active() {
+      const out = [];
+      for (const r of rules) if (st.get(r.id)?.raised) out.push(r.id);
+      if (staleRaised || jumpyRaised) out.push('__feed__');
+      return out;
+    },
+    isRaised: (id) => !!st.get(id)?.raised,
+    // Drop-anchor for a host that wants a runtime datum. IN-MEMORY ONLY — it does not
+    // survive a restart or a rule edit. The durable path is writing `anchor: {lat, lon}`
+    // into the rule itself (which is what the Config pane does).
+    setAnchor(ruleId, lat, lon) { stateOf(ruleId).anchor = { lat, lon }; },
+  };
+}
+
+module.exports = {
+  createAlertEngine,
+  validateRule,
+  RULE_KINDS,
+  DEFAULT_FOR_SEC,
+  DEFAULT_CLEAR_SEC,
+  STALE_SEC,
+  MAX_PLAUSIBLE_KT
+}

package/lib/alerts/great-circle.js

@@ -0,0 +1,21 @@
+'use strict'
+
+// VENDORED from sailkick/shared/engine/wind-field.js:256 @ 8008b0e  sha256:523a9e378fcab848
+// Do not edit here — fix upstream and re-vendor. ONE function copied rather than the whole
+// module: wind-field.js is grid generation, and hauling it in for eight lines of haversine
+// would vendor a large surface we do not use and cannot keep honest.
+//
+// The hash above is wind-field.js's, not this file's — it is what to re-check against.
+// Converted ESM -> CommonJS ONLY. No logic changed.
+
+// Helper for tests + UI: distance from (lat0, lon0) to (lat1, lon1) in km.
+function greatCircleKm (lat0, lon0, lat1, lon1) {
+  const R = 6371
+  const dLat = (lat1 - lat0) * Math.PI / 180
+  const dLon = (lon1 - lon0) * Math.PI / 180
+  const a = Math.sin(dLat / 2) ** 2 +
+          Math.cos(lat0 * Math.PI / 180) * Math.cos(lat1 * Math.PI / 180) * Math.sin(dLon / 2) ** 2
+  return 2 * R * Math.asin(Math.min(1, Math.sqrt(a)))
+}
+
+module.exports = { greatCircleKm }