sailkick-boat 0.14.5 → 0.17.0

package/README.md

@@ -27,7 +27,7 @@ One Signal K plugin, independently-toggleable modules — so the boat stays
   same contracts as the cloud, offline-first):
   - **`/ws/telemetry`** — the app's live telemetry bus, fed from local SignalK.
   - **`/api/history/{series,track}`** — the app's Trends panel + track, served
-    from the boat's local InfluxDB (or a DB-less telemetry ring) — full local history.
+    from a live ring sampled on the boat — full local history, no database.
 
 Kept as separate modules so a proxy fault can't wedge the data-critical sync path.
 
@@ -139,13 +139,79 @@ config passes through untouched. (Hand-edit `proxy.openAccess: false` to keep th
 login gate — there is no toggle, since the gate cannot complete over the mirror anyway.)
 
 ## Local history (offline Trends + track)
-Two ways, chosen automatically:
-- **Read token set** → full history queried from a **local InfluxDB** (e.g. a bucket
-  written by `signalk-to-influxdb-v2`).
-- **No token, telemetry on** → a **DB-less ring** sampled from live telemetry (the
-  same BoatState feeding `/ws/telemetry`) — for boats with no local InfluxDB, e.g.
-  **SignalK on a Victron GX / Venus OS**. Same JSON contract, fully offline, no database.
-  (`historyAvailable` reports true either way, so the app shows the Trends panel.)
+**One source: a live ring**, sampled from the same BoatState that feeds `/ws/telemetry`
+— no database, works on a Victron GX with nothing else installed. `historyAvailable` is
+forced on so the app shows the Trends panel, and the eight channels match what the cloud
+serves, `stw` included.
+
+There is deliberately **no way to point this at a local InfluxDB**. Until v0.15.0 a read
+token did exactly that, and it was a trap: the app only ever asks for a *relative* window
+clamped to 24 h, so aiming it at a bucket of older data matched nothing — Trends went
+blank **and** the working live ring was switched off. If you still have a token in your
+config it is now inert; the plugin logs `history -> live ring` regardless.
+
+A local InfluxDB is not a competitor here anyway. The app never requests finer than
+`every=5s` over a 24 h window, and the ring's floor at that window is 2 s — set
+`ringSampleSec: 5` and it matches anything the UI can draw, from live state. What an old
+database *is* good for is its contents ending up **in the cloud** — see below.
+
+## Uploading AIS targets
+The cloud app already draws other vessels, but its AIS source polls a SignalK server over
+the LAN and keeps everything in memory — which cannot work once a boat is on a mobile
+link. Enable **Upload AIS targets** and the boat pushes what its own receiver hears, so
+the web app can show other boats, their heading and their trail from stored data.
+
+Only **locally received** AIS is forwarded. A boat running an internet feed such as
+`signalk-aisstream` would otherwise spend uplink bandwidth sending data the cloud can
+fetch directly from the same API — known feeds are skipped automatically. The plugin logs
+the AIS sources it sees, so you can name your own receiver in **Only this AIS source** if
+you want to be explicit.
+
+There is no radius or rate limit: a real AIS receiver is bounded by VHF line-of-sight,
+which is the honest limiter, and offshore — where this data is most valuable, because
+commercial feeds are blind there — it tends to zero. Vessel identity (name, dimensions,
+ship type) repeats every few minutes and never changes, so it is re-sent at most hourly;
+positions are never throttled.
+
+Telemetry always wins the link. AIS buffers in its **own** spool with its own cap and
+stands down completely whenever the telemetry spool has a backlog, so a busy anchorage
+can never delay or evict your own boat's data.
+
+> ⚠️ **Requires a cloud that filters history on `self`.** Every AIS row is tagged
+> `self=false`, and the cloud's Trends and track queries must filter `self == "true"`.
+> Without that, other ships' speed and heading appear in *your* charts. Leave this off
+> until the server side is in place.
+
+## Copying older history to the cloud (one-time)
+If the boat recorded into its own InfluxDB before it started syncing — a
+`signalk-to-influxdb-v2` bucket, or an imported logbook — the **backfill** copies it up
+so the cloud holds your full history. Live sync can't do this: it only ever sees deltas
+arriving now, and the spool only replays what it captured itself while offline.
+
+Fill the **Copy older history to the cloud** section and save. It walks backwards in
+one-hour windows (newest first, so recent history lands first), resumes after a restart
+from a manifest, and stands aside whenever live telemetry has a backlog — the data-
+critical path is never starved by a bulk upload. Progress shows in the status line.
+
+It needs a **cloud read+write token**, not the write token from signup. Every hour it
+uploads is verified by counting the destination, and a write-only token cannot read. A
+`204` means InfluxDB accepted the bytes, not that every point landed — without the count
+a partial write would be marked done and lost. The token is only needed while the
+backfill runs: **revoke it afterwards**, live sync is unaffected.
+
+Safe to re-run. Points are keyed by (measurement, tagset, nanosecond timestamp), so an
+identical point overwrites rather than duplicating — an interrupted migration is simply
+run again. Everything in the bucket is copied, including AIS contexts; hand-edit
+`backfill.selfOnly: true` to restrict it to your own vessel if cloud series cardinality
+becomes a problem.
+
+**True wind comes from your instruments.** If the boat publishes
+`environment.wind.speedTrue` / `directionTrue`, those are stored verbatim — a wind
+system corrects for heel and leeway against water-referenced boat speed, and every other
+display aboard shows its numbers. Only when the boat publishes none is true wind
+derived, and then from **STW**, not SOG: true wind is relative to motion through the
+water. (Before v0.14.6 the derivation used SOG, which in 3 kt of foul tide skewed TWD by
+~12° and TWS by ~1.8 kt.) SOG is the last resort for boats with no paddlewheel.
   - **Persistent (append-log):** the ring is saved as a JSONL append-log at
     `<dataDir>/history/history-ring.jsonl` (on the SSD/USB with the tiles; override with
     `proxy.history.ringDir`), so it **survives restarts**. Each sample appends one line; the file is
@@ -158,14 +224,14 @@ Two ways, chosen automatically:
 
 The sailkick app is deployment-agnostic about history: *central Influx in the
 cloud, in-memory ring on a DB-less edge*. The boat is a third case — an edge that
-serves the app's history endpoints from its **own** data (local InfluxDB or the ring):
+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 }, …] }
 ```
 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 neither a local InfluxDB nor
-telemetry is available do these paths **fall through to the cloud mirror**, so an
+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
 online boat is never worse off than before.
 
 ## Setup: register on the web, then paste the token
@@ -205,18 +271,16 @@ in `index.js`.
 
 - **Sailkick account**: `slug` (boat name), `writeToken`
 - **Telemetry sync → cloud**: `enabled`
+- **Upload AIS targets**: `enabled` (default off), `source`
 - **Offline app & maps**: `enabled`, `proxyPort` (default 8080), `localSignalkUrl`
   (default `http://127.0.0.1:3000`), `dataDir`, `seedEnabled`, `prefetchRadiusNm`,
-  `prefetchDetailZoom`, `historyToken`
+  `prefetchDetailZoom`
 
 `dataDir` is the one storage location — cached maps, the telemetry spool and the
 history ring log all live under it. **Put it on the SSD/USB disk, not the SD card.**
 Leave it blank and each part falls back to its historical spot under the plugin data
 dir.
 
-`historyToken` is optional and only matters if the boat already runs its own InfluxDB.
-Blank — the normal case — uses the built-in DB-less ring.
-
 Cache-manifest polling is always on (no toggle): tile freshness comes from the cloud
 announcing bakes, and without it a re-baked dataset would never refresh.
 

package/index.js

@@ -6,6 +6,8 @@ const { createSync } = require('./lib/sync')
 const { createProxy } = require('./lib/proxy')
 const { createTelemetry } = require('./lib/telemetry')
 const { createHistory } = require('./lib/history')
+const { createBackfill } = require('./lib/backfill')
+const { createAis } = require('./lib/ais')
 const { resolveAccountConfig } = require('./lib/account')
 
 // sailkick-boat: one Signal K plugin, two independently-toggleable modules —
@@ -43,15 +45,8 @@ const PROXY_TUNING = { requestTimeoutMs: 20000, localPaths: ['/signalk'], teleme
 const MANIFEST = { enabled: true, path: '/api/cache-manifest', pollIntervalSec: 300 }
 const SEED_TUNING = { coastlineMaxZoom: 8, seabedMaxZoom: 6, concurrency: 4 }
 const PREFETCH_TUNING = { concurrency: 4 }
-const HISTORY_TUNING = {
-  influxUrl: 'http://127.0.0.1:8086',
-  org: 'signalk',
-  bucket: 'signalk',
-  requestTimeoutMs: 15000,
-  ringPersist: true,
-  ringWindowSec: 86400,
-  ringSampleSec: 15
-}
+const HISTORY_TUNING = { ringPersist: true, ringWindowSec: 86400, ringSampleSec: 15 }
+const BACKFILL_SRC_DEFAULTS = { influxUrl: 'http://127.0.0.1:8086', org: 'signalk', bucket: 'signalk' }
 
 // A *cloud* endpoint on a loopback or private address means telemetry never leaves the
 // LAN. On the wire that is indistinguishable from a normal offline backlog — the spool
@@ -69,6 +64,19 @@ function isPrivateHostUrl (u) {
   } catch { return false }
 }
 
+// The Signal K config UI writes every schema default on save, so a freshly pre-filled
+// `backfillOrg: "signalk"` can appear on a boat whose archive has always lived in org
+// "addiction" under the pre-0.15 `proxy.history` block — and the backfill would read an
+// empty bucket. Rule: an explicitly-changed field wins; else a legacy value that differs
+// from the default wins; else the default.
+function pickField (flat, legacy, dflt) {
+  const f = String(flat == null ? '' : flat).trim()
+  const l = String(legacy == null ? '' : legacy).trim()
+  if (f && f !== dflt) return { value: f, from: 'config' }
+  if (l && l !== dflt) return { value: l, from: 'legacy' }
+  return { value: f || l || dflt, from: 'default' }
+}
+
 // Endpoint resolution with one rule: the constant wins unless self-hosting is declared.
 // Returns { url, ignored } — `ignored` is the stale value we refused, so the caller can
 // say so out loud instead of leaving the owner to guess why nothing arrives.
@@ -84,6 +92,8 @@ module.exports = function (app) {
   let proxy = null
   let telemetry = null
   let history = null
+  let backfill = null
+  let ais = null
   let statusTimer = null
   let accountStatus = null
   let syncWarning = null
@@ -116,6 +126,28 @@ module.exports = function (app) {
           enabled: { type: 'boolean', title: 'Enable telemetry sync', default: true }
         }
       },
+      ais: {
+        type: 'object',
+        title: 'Upload AIS targets',
+        description: 'Send the AIS this boat\'s own receiver hears to the cloud, so the web app can show other vessels, their heading and their trail. Only locally received AIS is forwarded — an internet feed such as signalk-aisstream is skipped, since the cloud can fetch that itself without spending your uplink. REQUIRES a cloud that filters history on self; until then leave this off or the owner\'s SOG and heading charts will pick up other ships.',
+        properties: {
+          enabled: { type: 'boolean', title: 'Upload AIS targets', default: false },
+          source: { type: 'string', title: 'Only this AIS source', description: 'Blank forwards every source except known internet feeds. The plugin logs the AIS sources it sees — copy the one for your own receiver here if you want to be explicit.' }
+        }
+      },
+      backfill: {
+        type: 'object',
+        title: 'Copy older history to the cloud (one-time)',
+        description: 'If this boat recorded data into its own InfluxDB before it started syncing — a signalk-to-influxdb-v2 bucket, or an imported logbook — this copies it up so the app can chart it. It runs in the background, resumes after a restart, verifies every hour it uploads, and stands aside whenever live telemetry is behind. Safe to re-run: identical points overwrite rather than duplicate.',
+        properties: {
+          enabled: { type: 'boolean', title: 'Run the backfill', default: false },
+          cloudToken: { type: 'string', title: 'Cloud read+write token', description: 'A token with READ and WRITE on your cloud bucket. Your normal write token cannot read, and reading is how each uploaded hour is verified. Needed only while the backfill runs — revoke it afterwards; live sync is unaffected.' },
+          sourceToken: { type: 'string', title: 'Local InfluxDB read token' },
+          sourceUrl: { type: 'string', title: '…local InfluxDB URL', default: 'http://127.0.0.1:8086' },
+          sourceOrg: { type: 'string', title: '…organization', default: 'signalk' },
+          sourceBucket: { type: 'string', title: '…bucket', default: 'signalk' }
+        }
+      },
       proxy: {
         type: 'object',
         title: 'Offline app & maps',
@@ -140,8 +172,7 @@ module.exports = function (app) {
             enum: [12, 13, 14, 15],
             enumNames: ['Overview (z12)', 'Coastal (z13)', 'Detailed (z14)', 'Harbor (z15)'],
             default: 13
-          },
-          historyToken: { type: 'string', title: 'Local InfluxDB read token (optional)', description: 'Only if this boat already runs its own InfluxDB (e.g. signalk-to-influxdb-v2) and you want full history from it. Leave blank — the plugin then keeps its own lightweight history, which is what most boats want.' }
+          }
         }
       }
     }
@@ -220,6 +251,8 @@ module.exports = function (app) {
       const oldSeed = p.seed || {}
       const oldPrefetch = p.prefetch || {}
       const oldHistory = p.history || {}
+      console.log('[sailkick-boat] history -> live ring')
+
       if (upstream.ignored) {
         ;(app.error || console.error)(`[sailkick-boat] ignoring proxy.sailkickUrl "${upstream.ignored}" left over from an older config — mirroring ${upstream.url}. Set proxy.selfHosted:true to keep your own server.`)
       }
@@ -251,10 +284,6 @@ module.exports = function (app) {
         history: {
           ...HISTORY_TUNING,
           enabled: oldHistory.enabled !== false,
-          influxUrl: oldHistory.influxUrl || HISTORY_TUNING.influxUrl,
-          org: oldHistory.org || HISTORY_TUNING.org,
-          bucket: oldHistory.bucket || HISTORY_TUNING.bucket,
-          token: p.historyToken || oldHistory.token || '',
           ringPersist: oldHistory.ringPersist !== false,
           ringWindowSec: oldHistory.ringWindowSec || HISTORY_TUNING.ringWindowSec,
           ringSampleSec: oldHistory.ringSampleSec || HISTORY_TUNING.ringSampleSec,
@@ -295,6 +324,68 @@ module.exports = function (app) {
       }
     }
 
+    // --- AIS upload (isolated; yields to telemetry, its own spool) ---
+    const aisOpts = opts.ais || {}
+    if (aisOpts.enabled === true) {
+      if (!b.writeToken) {
+        (app.error || console.error)('[sailkick-boat] AIS upload needs a paired account for its destination bucket — skipped')
+      } else {
+        try {
+          ais = createAis(app, {
+            influxUrl: influx.url,
+            org: b.org || SYNC_TUNING.org,
+            bucket: b.bucket,
+            token: b.writeToken,
+            source: String(aisOpts.source || '').trim() || null,
+            spoolDir: store ? path.join(store, 'ais-spool') : undefined,
+            pending: sync ? sync.pending : null
+          })
+          ais.start()
+          console.log(`[sailkick-boat] ais -> ${influx.url} bucket=${b.bucket}${aisOpts.source ? ' source=' + aisOpts.source : ''}`)
+        } catch (e) {
+          (app.error || console.error)('[sailkick-boat] AIS start failed: ' + e.message)
+          ais = null
+        }
+      }
+    }
+
+    // --- backfill (best-effort, isolated: it must never disturb sync or the proxy) ---
+    const bf = opts.backfill || {}
+    const oldHist = (opts.proxy || {}).history || {}
+    if (bf.enabled === true) {
+      // Pre-0.15 installs kept the archive's coordinates in proxy.history.* — reuse them
+      // so nobody retypes an org/bucket the plugin already knows.
+      const src = {
+        url: pickField(bf.sourceUrl, oldHist.influxUrl, BACKFILL_SRC_DEFAULTS.influxUrl).value,
+        org: pickField(bf.sourceOrg, oldHist.org, BACKFILL_SRC_DEFAULTS.org).value,
+        bucket: pickField(bf.sourceBucket, oldHist.bucket, BACKFILL_SRC_DEFAULTS.bucket).value,
+        token: String(bf.sourceToken || oldHist.token || '').trim()
+      }
+      const dst = { url: influx.url, org: b.org || SYNC_TUNING.org, bucket: b.bucket, token: String(bf.cloudToken || '').trim() }
+      if (!b.writeToken) {
+        (app.error || console.error)('[sailkick-boat] backfill needs a paired account for its destination bucket — skipped')
+      } else if (!dst.token) {
+        (app.error || console.error)('[sailkick-boat] backfill needs a cloud READ+WRITE token: every uploaded hour is verified by counting the destination, which the write-only sync token cannot do — skipped')
+      } else if (!src.token) {
+        (app.error || console.error)('[sailkick-boat] backfill needs a read token for the local InfluxDB — skipped')
+      } else {
+        try {
+          backfill = createBackfill(app, {
+            src,
+            dst,
+            selfOnly: bf.selfOnly === true,
+            startBound: bf.startBound,
+            stateFile: path.join((app.getDataDirPath && app.getDataDirPath()) || '.', 'backfill.json'),
+            pending: sync ? sync.pending : null
+          })
+          backfill.start()
+        } catch (e) {
+          (app.error || console.error)('[sailkick-boat] backfill start failed: ' + e.message)
+          backfill = null
+        }
+      }
+    }
+
     statusTimer = setInterval(updateStatus, 5000)
     updateStatus()
   }
@@ -308,6 +399,8 @@ module.exports = function (app) {
     if (proxy) parts.push(proxy.status())
     if (telemetry) parts.push(telemetry.status())
     if (history) parts.push(history.status())
+    if (ais) parts.push(ais.status())
+    if (backfill) parts.push(backfill.status())
     try { app.setPluginStatus(parts.join('   |   ') || 'idle (both features off)') } catch {}
   }
 
@@ -317,10 +410,14 @@ module.exports = function (app) {
     try { if (sync) sync.stop() } catch {}
     try { if (telemetry) telemetry.stop() } catch {}
     try { if (history) history.stop() } catch {}
+    try { if (ais) ais.stop() } catch {}
+    try { if (backfill) backfill.stop() } catch {}
     try { if (proxy) proxy.stop() } catch {}
     sync = null
     telemetry = null
     history = null
+    backfill = null
+    ais = null
     proxy = null
     accountStatus = null
     syncWarning = null

package/lib/ais/index.js

@@ -0,0 +1,262 @@
+'use strict'
+
+// AIS upload — forward the targets this boat's own receiver hears, so the cloud app can
+// draw other vessels, their heading and their trail.
+//
+// The cloud already renders AIS (public/viewer/ais.js → /api/ais), but its source polls a
+// SignalK server over the LAN and keeps everything in memory. That only works while the
+// cloud can reach the boat inbound, which stops being true on a mobile link. So the boat
+// pushes instead.
+//
+// Only LOCALLY RECEIVED AIS is worth uploading. A boat running an internet feed like
+// signalk-aisstream would otherwise spend uplink bandwidth sending data the cloud could
+// fetch directly from the same API over a fat pipe. The value is what your own VHF hears
+// offshore, where commercial feeds are blind — which is also why there is no radius or
+// rate limit here: VHF line-of-sight is the honest limiter, and offshore it tends to zero.
+//
+// Two invariants this module must not break:
+//   - Telemetry always wins the link. Separate spool, separate uploader, and it stands
+//     down whenever the telemetry spool has a backlog.
+//   - Every row is tagged self=false. The cloud's history queries filter on self=="true"
+//     to keep other vessels out of the boat's own Trends and track; if that tag were
+//     wrong, AIS would land in the owner's SOG and heading charts.
+
+const fs = require('fs')
+const path = require('path')
+const { Spool } = require('../sync/spool')
+const { writeLines } = require('../sync/influxWrite')
+const { deltaToLines } = require('../sync/lineprotocol')
+
+// What the cloud's /api/ais envelope needs. Subscribing to these rather than '*' keeps
+// delta volume down without imposing a rate limit.
+const POSITION_PATHS = [
+  'navigation.position',
+  'navigation.speedOverGround',
+  'navigation.courseOverGroundTrue',
+  'navigation.headingTrue',
+  'navigation.headingMagnetic',
+  'navigation.magneticVariation',
+  'navigation.rateOfTurn'
+]
+// Static/identity data: repeats every ~6 min per vessel and essentially never changes.
+const STATIC_PATHS = ['design.length', 'design.beam', 'design.aisShipType']
+const ALL_PATHS = [...POSITION_PATHS, ...STATIC_PATHS]
+
+// Sources that are internet feeds rather than a receiver on this boat. Uploading these
+// is pure round-tripping. Matched case-insensitively as a substring of $source.
+const INTERNET_FEEDS = ['aisstream', 'aishub', 'marinetraffic', 'vesselfinder']
+
+const DEFAULTS = {
+  staticIntervalMs: 3600000, // re-send a vessel's identity at most hourly
+  flushIntervalMs: 5000,
+  batchSize: 2000,
+  maxBufferBytes: 50 * 1024 * 1024, // its own, smaller cap — see below
+  idlePollMs: 5000,
+  retryMinMs: 2000,
+  retryMaxMs: 120000,
+  requestTimeoutMs: 30000
+}
+
+const isInternetFeed = (src) => {
+  const s = String(src || '').toLowerCase()
+  return INTERNET_FEEDS.some((f) => s.includes(f))
+}
+
+function createAis (app, options) {
+  const log = (m) => (app.debug ? app.debug('[ais] ' + m) : console.log('[sailkick-boat:ais]', m))
+  const warn = (m) => (app.error ? app.error('[sailkick-boat:ais] ' + m) : console.error('[sailkick-boat:ais]', m))
+
+  const cfg = { ...DEFAULTS, ...options }
+  let state = null
+
+  function start () {
+    if (!cfg.influxUrl || !cfg.bucket || !cfg.token) {
+      warn('not started — the boat is not paired, so there is no destination bucket')
+      state = { statusLine: 'ais: not configured', stopped: true }
+      return
+    }
+    const dataDir = (app.getDataDirPath && app.getDataDirPath()) || '.'
+    // A SEPARATE spool. Sharing the telemetry one would be dangerous: it drops the
+    // OLDEST files on overflow, so an AIS flood in a busy anchorage could evict
+    // telemetry that had not been sent yet.
+    const spoolDir = cfg.spoolDir || path.join(dataDir, 'ais-spool')
+    const spool = new Spool({ dir: spoolDir, maxBytes: cfg.maxBufferBytes, logger: log })
+    const selfContext = app.selfContext || ('vessels.' + (app.selfId || 'self'))
+
+    state = {
+      spool,
+      selfContext,
+      batch: [],
+      lastStatic: new Map(), // context -> ms, so identity is re-sent at most hourly
+      sourcesSeen: new Map(), // $source -> count, for the discovery log
+      targets: new Set(),
+      forwarded: 0,
+      dropped: 0,
+      lastOkAt: null,
+      backoff: cfg.retryMinMs,
+      pumping: false,
+      stopped: false,
+      unsubscribes: [],
+      statusLine: 'ais: starting'
+    }
+
+    spool.init().then(() => {
+      // stop() can land before init resolves (disable during startup, or a fast
+      // restart). Without this the timers are installed on an already-stopped module
+      // and never cleared — a leaked interval that also keeps the host process alive.
+      if (!state || state.stopped) return
+      state.flushTimer = setInterval(flush, cfg.flushIntervalMs)
+      state.reportTimer = setInterval(reportSources, 300000)
+      // Unref every timer: this module must never be the reason the Signal K server
+      // cannot exit.
+      if (state.flushTimer.unref) state.flushTimer.unref()
+      if (state.reportTimer.unref) state.reportTimer.unref()
+      subscribe()
+      pump()
+      log(`started; ${cfg.source ? 'source "' + cfg.source + '" only' : 'all sources except known internet feeds'}; buffer ${spoolDir}`)
+    }).catch((e) => warn('init failed: ' + e.message))
+  }
+
+  // Which $source values are actually producing AIS, so the config field can be filled
+  // in from the log instead of guessed.
+  function reportSources () {
+    if (!state || !state.sourcesSeen.size) return
+    const list = [...state.sourcesSeen.entries()].sort((a, b) => b[1] - a[1])
+      .map(([s, n]) => `${s} (${n}${isInternetFeed(s) ? ', internet feed — not forwarded' : ''})`)
+    log('AIS sources seen: ' + list.join('; '))
+  }
+
+  function accept (context, source) {
+    if (!context || context === state.selfContext) return false // never our own vessel
+    if (cfg.source) return String(source) === String(cfg.source)
+    return !isInternetFeed(source)
+  }
+
+  function handleDelta (delta) {
+    if (!state || state.stopped || !delta || !Array.isArray(delta.updates)) return
+    const context = delta.context
+    if (!context || context === state.selfContext) return
+
+    for (const update of delta.updates) {
+      if (!update || !Array.isArray(update.values)) continue
+      const source = update.$source || (update.source && (update.source.label || update.source.type)) || 'unknown'
+      state.sourcesSeen.set(source, (state.sourcesSeen.get(source) || 0) + 1)
+      if (!accept(context, source)) { state.dropped++; continue }
+
+      // Split identity from position: identity repeats constantly and never changes.
+      const now = Date.now()
+      const staticDue = (now - (state.lastStatic.get(context) || 0)) >= cfg.staticIntervalMs
+      const values = update.values.filter((pv) => {
+        if (!pv || !pv.path) return false
+        if (STATIC_PATHS.includes(pv.path)) return staticDue
+        return POSITION_PATHS.includes(pv.path)
+      })
+      if (!values.length) continue
+      if (staticDue && values.some((pv) => STATIC_PATHS.includes(pv.path))) state.lastStatic.set(context, now)
+
+      // self:false is the tag the cloud filters on to keep AIS out of the owner's charts.
+      const lines = deltaToLines({ context, updates: [{ ...update, values }] }, { self: false })
+      if (lines.length) {
+        state.batch.push(...lines)
+        state.targets.add(context)
+        state.forwarded += lines.length
+      }
+      if (state.batch.length >= cfg.batchSize) flush()
+    }
+  }
+
+  function subscribe () {
+    const sub = { context: '*', subscribe: ALL_PATHS.map((p) => ({ path: p, period: cfg.periodMs || 10000 })) }
+    if (app.subscriptionmanager && app.subscriptionmanager.subscribe) {
+      app.subscriptionmanager.subscribe(sub, state.unsubscribes, (err) => warn('subscription error: ' + err), handleDelta)
+    } else if (app.signalk && app.signalk.on) {
+      const h = (d) => handleDelta(d)
+      app.signalk.on('delta', h)
+      state.unsubscribes.push(() => app.signalk.removeListener('delta', h))
+    } else {
+      warn('no subscription mechanism available — nothing will be forwarded')
+    }
+  }
+
+  function flush () {
+    if (!state || state.stopped || !state.batch.length) return
+    const lines = state.batch
+    state.batch = []
+    state.spool.append(lines).then(() => pump()).catch((e) => {
+      warn('spool append failed: ' + e.message)
+      state.batch.unshift(...lines)
+    })
+  }
+
+  async function pump () {
+    if (!state || state.stopped || state.pumping) return
+    // Telemetry always wins the link: stand down entirely while its spool is behind.
+    if (cfg.pending) {
+      let depth = 0
+      try { depth = (await cfg.pending()).count || 0 } catch {}
+      if (depth) { refreshStatus(`waiting — telemetry backlog (${depth})`); scheduleIdle(); return }
+    }
+    state.pumping = true
+    try {
+      for (const file of await state.spool.pending()) {
+        if (state.stopped) break
+        let body
+        try { body = await fs.promises.readFile(file, 'utf8') } catch { continue }
+        if (!body.trim()) { await state.spool.remove(file); continue }
+        const res = await writeLines({ influxUrl: cfg.influxUrl, org: cfg.org, bucket: cfg.bucket, token: cfg.token, timeoutMs: cfg.requestTimeoutMs }, body)
+        if (res.ok) {
+          await state.spool.remove(file); state.lastOkAt = new Date(); state.backoff = cfg.retryMinMs
+        } else if (res.retryable) {
+          state.pumping = false; scheduleRetry(res); return
+        } else {
+          warn(`batch rejected (HTTP ${res.status}) — quarantined`)
+          await state.spool.quarantine(file)
+        }
+      }
+    } catch (e) {
+      warn('pump error: ' + e.message); state.pumping = false; scheduleRetry(); return
+    }
+    state.pumping = false
+    scheduleIdle()
+    refreshStatus()
+  }
+
+  function scheduleRetry (res) {
+    if (!state || state.stopped) return
+    clearTimeout(state.pumpTimer)
+    const delay = state.backoff
+    state.backoff = Math.min(state.backoff * 2, cfg.retryMaxMs)
+    state.pumpTimer = setTimeout(pump, delay)
+    if (state.pumpTimer.unref) state.pumpTimer.unref()
+    refreshStatus(`${res && res.status ? 'HTTP ' + res.status : 'offline'} — retry ${Math.round(delay / 1000)}s`)
+  }
+  function scheduleIdle () {
+    if (!state || state.stopped) return
+    clearTimeout(state.pumpTimer)
+    state.pumpTimer = setTimeout(pump, cfg.idlePollMs)
+    if (state.pumpTimer.unref) state.pumpTimer.unref()
+  }
+  function refreshStatus (suffix) {
+    if (!state) return
+    state.statusLine = `ais: ${state.targets.size} target(s), ${state.forwarded} point(s)${state.dropped ? `, ${state.dropped} skipped` : ''}${suffix ? '; ' + suffix : ''}`
+  }
+
+  function stop () {
+    if (!state) return
+    state.stopped = true
+    clearInterval(state.flushTimer)
+    clearInterval(state.reportTimer)
+    clearTimeout(state.pumpTimer)
+    for (const u of (state.unsubscribes || [])) { try { u() } catch {} }
+    if (state.batch && state.batch.length && state.spool) {
+      try { fs.writeFileSync(path.join(state.spool.dir, `${Date.now()}-final.lp`), state.batch.join('\n') + '\n') } catch {}
+      state.batch = []
+    }
+  }
+
+  function status () { return state ? state.statusLine : 'ais: off' }
+
+  return { start, stop, status, _handleDelta: handleDelta, _state: () => state, _flush: flush }
+}
+
+module.exports = { createAis, isInternetFeed, POSITION_PATHS, STATIC_PATHS }