sailkick-boat 0.13.4

package/lib/history/index.js

@@ -0,0 +1,247 @@
+'use strict'
+
+// History module — serves the sailkick app's GET /api/history/series and
+// /api/history/track from the boat's LOCAL InfluxDB (a signalk-to-influxdb-v2
+// style bucket), so the app's Trends panel + track work offline with the full
+// local dataset.
+//
+// This is the boat-edge counterpart of the app's server/history/influx-provider.js:
+// the Flux queries and channel map are ported VERBATIM (the signalk-to-influxdb-v2 schema —
+// measurement=SignalK path, field="value", position→lat/lon — is exactly what that
+// provider assumes), and the JSON envelope is byte-for-byte the same the app's
+// server/routes/history.js returns, so the browser client can't tell the difference.
+// Keep MAP / the queries in sync with the app copy.
+//
+// When no local InfluxDB is configured (e.g. SignalK on a Victron GX / Venus OS)
+// but a telemetry source is available, it instead serves a DB-less in-memory ring
+// (lib/history/ring.js) — same JSON contract, ~1h offline window, no database.
+
+const path = require('path')
+const { RingHistoryProvider } = require('./ring')
+
+const MS_TO_KT = 1.94384
+const RAD2DEG = 180 / Math.PI
+const wrap360 = (d) => ((d % 360) + 360) % 360
+const wrap180 = (d) => { const x = wrap360(d); return x > 180 ? x - 360 : x }
+
+// SignalK path (Influx measurement) → { chan, conv }. Field key is "value".
+// Some channels have a fallback measurement (primary wins when both present).
+const MAP = {
+  'environment.wind.speedTrue': { chan: 'tws', conv: (v) => v * MS_TO_KT },
+  'environment.wind.directionTrue': { chan: 'twd', conv: (v) => wrap360(v * RAD2DEG) },
+  'environment.wind.speedApparent': { chan: 'aws', conv: (v) => v * MS_TO_KT },
+  'environment.wind.angleApparent': { chan: 'awa', conv: (v) => wrap180(v * RAD2DEG) },
+  'navigation.speedOverGround': { chan: 'sog', conv: (v) => v * MS_TO_KT },
+  'navigation.speedThroughWater': { chan: 'stw', conv: (v) => v * MS_TO_KT },
+  'navigation.headingTrue': { chan: 'heading', conv: (v) => wrap360(v * RAD2DEG) },
+  'navigation.headingMagnetic': { chan: 'heading', conv: (v) => wrap360(v * RAD2DEG), fallback: true },
+  'environment.depth.belowTransducer': { chan: 'depth', conv: (v) => v },
+  'environment.depth.belowSurface': { chan: 'depth', conv: (v) => v, fallback: true }
+}
+const MEASUREMENTS = Object.keys(MAP)
+
+// Parse a duration like "1h" / "30m" / "600s" / "3600" → seconds, clamped.
+// Ported from the app's server/routes/history.js so limits match exactly.
+function dur (s, def, min, max) {
+  if (s == null) return def
+  const m = String(s).trim().match(/^(\d+)\s*([smh]?)$/)
+  if (!m) return def
+  const n = parseInt(m[1], 10) * ({ s: 1, m: 60, h: 3600, '': 1 }[m[2]])
+  return Math.max(min, Math.min(max, n))
+}
+
+// Minimal InfluxDB v2 annotated-CSV parser (same approach as the app's
+// server/influx/client.js). Values in our long-format queries are simple.
+function parseAnnotatedCsv (text) {
+  const rows = []
+  let header = null
+  for (const raw of text.split('\n')) {
+    const line = raw.replace(/\r$/, '')
+    if (!line || line.startsWith('#')) { header = null; continue }
+    const cols = line.split(',')
+    if (!header) { header = cols; continue }
+    const o = {}
+    for (let i = 0; i < header.length; i++) o[header[i]] = cols[i]
+    rows.push(o)
+  }
+  return rows
+}
+
+function createHistory (app, options) {
+  const log = (m) => (app.debug ? app.debug('[history] ' + m) : console.log('[sailkick-boat:history]', m))
+  let cfg = null
+  let provider = null // { getSeries, getTrack, destroy? } — InfluxDB queries or the ring
+  let mode = null // 'influx' | 'ring' | null
+
+  function start () {
+    cfg = {
+      url: (options.influxUrl || 'http://127.0.0.1:8086').replace(/\/+$/, ''),
+      org: options.org || 'signalk',
+      bucket: options.bucket || 'signalk',
+      token: options.token || '',
+      timeoutMs: options.requestTimeoutMs || 15000
+    }
+    if (cfg.url && cfg.token && cfg.bucket) {
+      // Full history from a local InfluxDB.
+      provider = { getSeries: influxSeries, getTrack: influxTrack }
+      mode = 'influx'
+      log(`serving /api/history from ${cfg.url} bucket "${cfg.bucket}"`)
+    } else if (options.ringSource && options.ringSource.getState) {
+      // No local InfluxDB → DB-less rolling ring from live telemetry (GX/Venus OS).
+      // Persist the append-log so it survives restarts (unless ringPersist is off).
+      // Default location: a "history" folder under the tile cache dir (storeDir), so it
+      // sits on the SSD/USB with the tiles; `ringDir` overrides. Resolve storeDir the
+      // same way the proxy does.
+      const dataDir = (app.getDataDirPath && app.getDataDirPath()) || '.'
+      const storeDir = options.storeDir || path.join(dataDir, 'store')
+      const ringDir = options.ringDir || path.join(storeDir, 'history')
+      const persistFile = options.ringPersist !== false ? path.join(ringDir, 'history-ring.jsonl') : null
+      provider = new RingHistoryProvider({
+        source: options.ringSource,
+        windowSec: options.ringWindowSec,
+        sampleSec: options.ringSampleSec,
+        persistFile
+      })
+      mode = 'ring'
+      log(persistFile
+        ? `serving /api/history from a persistent DB-less ring (${persistFile})`
+        : 'serving /api/history from an in-memory DB-less ring')
+    } else {
+      provider = null; mode = null
+      log('no local InfluxDB and no telemetry — /api/history falls through to the mirror')
+    }
+  }
+
+  function stop () {
+    try { if (provider && provider.destroy) provider.destroy() } catch {}
+    provider = null; mode = null; cfg = null
+  }
+
+  // available() gates local serving: when false the proxy lets /api/history fall
+  // through to the cloud mirror (so we never make history worse than today).
+  function available () { return !!provider }
+
+  function status () {
+    if (!provider) return 'history: off'
+    return mode === 'ring' ? `history: ring${provider._persistFile ? ' (persistent)' : ''}` : `history: ${cfg.bucket}@local`
+  }
+
+  async function queryFlux (flux, signal) {
+    const url = `${cfg.url}/api/v2/query?org=${encodeURIComponent(cfg.org)}`
+    let resp
+    try {
+      resp = await fetch(url, {
+        method: 'POST',
+        headers: { Authorization: `Token ${cfg.token}`, 'Content-Type': 'application/vnd.flux', Accept: 'application/csv' },
+        body: flux,
+        signal: signal || AbortSignal.timeout(cfg.timeoutMs)
+      })
+    } catch (e) {
+      if (e && e.name === 'AbortError') return { ok: false, status: 0, message: 'InfluxDB query aborted/timed out' }
+      return { ok: false, status: 502, message: `Network error talking to InfluxDB: ${e.message}` }
+    }
+    if (!resp.ok) {
+      const body = await resp.text().catch(() => '')
+      return { ok: false, status: resp.status, message: `InfluxDB ${resp.status}: ${body.slice(0, 200)}` }
+    }
+    return { ok: true, rows: parseAnnotatedCsv(await resp.text()) }
+  }
+
+  async function influxSeries ({ windowSec, everySec, signal }) {
+    const filt = MEASUREMENTS.map((m) => `r._measurement == "${m}"`).join(' or ')
+    const flux = `from(bucket: "${cfg.bucket}")
+  |> range(start: -${windowSec}s)
+  |> filter(fn: (r) => r._field == "value" and (${filt}))
+  |> aggregateWindow(every: ${everySec}s, fn: mean, createEmpty: false)
+  |> keep(columns: ["_time", "_value", "_measurement"])`
+    const r = await queryFlux(flux, signal)
+    if (!r.ok) return r
+
+    const byChan = {} // chan -> { primary:[[t,v]], fallback:[[t,v]] }
+    for (const row of r.rows) {
+      const spec = MAP[row._measurement]
+      if (!spec) continue
+      const t = Date.parse(row._time)
+      const v = Number(row._value)
+      if (!Number.isFinite(t) || !Number.isFinite(v)) continue
+      const slot = (byChan[spec.chan] || (byChan[spec.chan] = { primary: [], fallback: [] }))
+      ;(spec.fallback ? slot.fallback : slot.primary).push([t, spec.conv(v)])
+    }
+    const series = {}
+    for (const [chan, { primary, fallback }] of Object.entries(byChan)) {
+      const pts = (primary.length ? primary : fallback).sort((a, b) => a[0] - b[0])
+      if (pts.length) series[chan] = pts
+    }
+    return { ok: true, series }
+  }
+
+  async function influxTrack ({ windowSec, everySec = 30, signal }) {
+    const flux = `from(bucket: "${cfg.bucket}")
+  |> range(start: -${windowSec}s)
+  |> filter(fn: (r) => r._measurement == "navigation.position" and (r._field == "lat" or r._field == "lon"))
+  |> aggregateWindow(every: ${everySec}s, fn: last, createEmpty: false)
+  |> pivot(rowKey: ["_time"], columnKey: ["_field"], valueColumn: "_value")
+  |> keep(columns: ["_time", "lat", "lon"])`
+    const r = await queryFlux(flux, signal)
+    if (!r.ok) return r
+    const track = []
+    for (const row of r.rows) {
+      const t = Date.parse(row._time)
+      const lat = Number(row.lat)
+      const lon = Number(row.lon)
+      if (Number.isFinite(t) && Number.isFinite(lat) && Number.isFinite(lon)) track.push({ t, lat, lon })
+    }
+    track.sort((a, b) => a.t - b.t)
+    return { ok: true, track }
+  }
+
+  // Abort the Influx query if the client disconnects mid-request.
+  function abortOnClose (res) {
+    const ac = new AbortController()
+    res.on('close', () => { if (!res.writableFinished) ac.abort() })
+    return ac.signal
+  }
+
+  function query (reqUrl) {
+    const qi = reqUrl.indexOf('?')
+    return new URLSearchParams(qi >= 0 ? reqUrl.slice(qi + 1) : '')
+  }
+
+  function sendJson (res, status, obj) {
+    const body = JSON.stringify(obj)
+    res.statusCode = status
+    res.setHeader('Content-Type', 'application/json')
+    res.end(body)
+  }
+
+  async function handleSeries (req, res) {
+    if (!available()) return sendJson(res, 503, { ok: false, code: 'history-unavailable', message: 'history not available' })
+    const q = query(req.url)
+    const windowSec = dur(q.get('window'), 3600, 60, 86400)
+    const everySec = dur(q.get('every'), 30, 5, 600)
+    try {
+      const r = await provider.getSeries({ windowSec, everySec, signal: abortOnClose(res) })
+      if (!r.ok) return sendJson(res, r.status || 502, { ok: false, code: 'history-error', message: r.message })
+      sendJson(res, 200, { ok: true, windowSec, everySec, from: Date.now() - windowSec * 1000, to: Date.now(), series: r.series })
+    } catch (e) {
+      sendJson(res, 502, { ok: false, code: 'history-error', message: e.message })
+    }
+  }
+
+  async function handleTrack (req, res) {
+    if (!available()) return sendJson(res, 503, { ok: false, code: 'history-unavailable', message: 'history not available' })
+    const q = query(req.url)
+    const windowSec = dur(q.get('window'), 3600, 60, 86400)
+    try {
+      const r = await provider.getTrack({ windowSec, signal: abortOnClose(res) })
+      if (!r.ok) return sendJson(res, r.status || 502, { ok: false, code: 'history-error', message: r.message })
+      sendJson(res, 200, { ok: true, windowSec, track: r.track })
+    } catch (e) {
+      sendJson(res, 502, { ok: false, code: 'history-error', message: e.message })
+    }
+  }
+
+  return { start, stop, status, available, handleSeries, handleTrack, _mode: () => mode, _getSeries: influxSeries, _getTrack: influxTrack }
+}
+
+module.exports = { createHistory }

package/lib/history/ring.js

@@ -0,0 +1,162 @@
+'use strict'
+
+// DB-less history provider — a rolling ring sampled from the live telemetry
+// BoatState (the same state that feeds /ws/telemetry). The edge path when there's
+// no local InfluxDB (e.g. SignalK on a Victron GX / Venus OS). Serves the SAME
+// series/track contract as the InfluxDB provider; TWS/TWD are derived from apparent
+// wind + boat motion (as the ribbon does), STW is simply absent.
+//
+// Persistence (optional, `persistFile`): a JSONL APPEND-LOG so the ring survives
+// restarts and can cover a long passage cheaply. Each sample is appended as one
+// line (~160 B); the file is compacted (atomic rewrite to the current window) only
+// rarely — on start, once appends exceed the ring length, and on destroy — so write
+// load is per-sample, decoupled from window size (< ~1 GB over a 30-day passage vs
+// ~600 GB for a full-rewrite-every-2min snapshot). To keep RAM/disk bounded at any
+// window, the sample rate auto-coarsens so the ring never exceeds ~MAX_SAMPLES rows
+// (24 h → 15 s, 30 d → ~52 s). All fs is guarded — a missing/corrupt file just means
+// an empty start; appends + compactions are serialized so they can't interleave.
+
+const fs = require('fs')
+const fsp = fs.promises
+const path = require('path')
+
+const DEG = Math.PI / 180
+const wrap360 = (d) => ((d % 360) + 360) % 360
+const MAX_SAMPLES = 50000
+
+// True wind (TWS kt, TWD ° the wind blows FROM) from apparent + motion over ground.
+function trueWind (s) {
+  if (!Number.isFinite(s.awsKt) || !Number.isFinite(s.awaDeg) || !Number.isFinite(s.headingDeg)) return null
+  const a = s.awaDeg * DEG
+  const x = s.awsKt * Math.cos(a) - (s.sogKt || 0); const y = s.awsKt * Math.sin(a)
+  return { tws: Math.hypot(x, y), twd: wrap360(s.headingDeg + Math.atan2(y, x) / DEG) }
+}
+
+class RingHistoryProvider {
+  constructor ({ source, sampleSec, windowSec, persistFile } = {}) {
+    this._source = source
+    this._ring = [] // [{ t, sog, cog, heading, aws, awa, depth, tws, twd, lat, lon }]
+    const win = windowSec || 3600
+    this._windowMs = win * 1000
+    this._persistFile = persistFile || null
+    this._io = Promise.resolve() // serialized fs writes (append/compact never interleave)
+    this._appendedSinceCompact = 0
+    // auto-coarsen so the ring is bounded (~MAX_SAMPLES rows) regardless of window
+    const stepSec = Math.max(sampleSec || 15, Math.ceil(win / MAX_SAMPLES))
+    this._stepSec = stepSec
+
+    this._load() // seed from disk (survives restart)
+    this._compactSync() // rewrite clean + bounded, synchronously (file exists right at start)
+    this._sample() // immediate first sample
+    this._timer = setInterval(() => this._sample(), stepSec * 1000)
+    if (this._timer.unref) this._timer.unref()
+  }
+
+  // --- sampling ---
+  _sample () {
+    const s = this._source && this._source.getState && this._source.getState()
+    if (!s) return
+    const tw = trueWind(s)
+    const num = (v) => (Number.isFinite(v) ? v : null)
+    const row = {
+      t: Date.now(),
+      sog: num(s.sogKt), cog: num(s.cogDeg), heading: num(s.headingDeg),
+      aws: num(s.awsKt), awa: num(s.awaDeg), depth: num(s.depthM),
+      tws: tw ? tw.tws : null, twd: tw ? tw.twd : null,
+      lat: num(s.lat), lon: num(s.lon)
+    }
+    this._ring.push(row)
+    const cutoff = Date.now() - this._windowMs
+    while (this._ring.length && this._ring[0].t < cutoff) this._ring.shift()
+    this._append(row)
+  }
+
+  available () { return true }
+
+  _window (windowSec) {
+    const cutoff = Date.now() - Math.min(windowSec * 1000, this._windowMs)
+    return this._ring.filter((r) => r.t >= cutoff)
+  }
+
+  getSeries ({ windowSec } = {}) {
+    const rows = this._window(windowSec)
+    const chans = ['tws', 'twd', 'aws', 'awa', 'sog', 'heading', 'depth'] // no STW in BoatState
+    const series = {}
+    for (const c of chans) {
+      const pts = rows.filter((r) => r[c] != null).map((r) => [r.t, r[c]])
+      if (pts.length) series[c] = pts
+    }
+    return { ok: true, series }
+  }
+
+  getTrack ({ windowSec } = {}) {
+    const track = this._window(windowSec)
+      .filter((r) => r.lat != null && r.lon != null)
+      .map((r) => ({ t: r.t, lat: r.lat, lon: r.lon }))
+    return { ok: true, track }
+  }
+
+  // --- persistence ---
+  _load () {
+    if (!this._persistFile) return
+    let text
+    try { text = fs.readFileSync(this._persistFile, 'utf8') } catch { return }
+    const cutoff = Date.now() - this._windowMs
+    let rows = []
+    for (const line of text.split('\n')) {
+      if (!line) continue
+      let r
+      try { r = JSON.parse(line) } catch { continue } // skip a torn/corrupt line
+      if (r && typeof r.t === 'number' && r.t >= cutoff) rows.push(r)
+    }
+    rows.sort((a, b) => a.t - b.t)
+    if (rows.length > MAX_SAMPLES) rows = rows.slice(-MAX_SAMPLES)
+    this._ring = rows
+  }
+
+  _append (row) {
+    if (!this._persistFile) return
+    const line = JSON.stringify(row) + '\n'
+    this._io = this._io.then(() => fsp.appendFile(this._persistFile, line)).catch(() => {})
+    // compact once the log has grown by ~a full window past its last rewrite
+    if (++this._appendedSinceCompact > Math.max(64, this._ring.length)) this._compact()
+  }
+
+  _serialize () {
+    return this._ring.map((r) => JSON.stringify(r)).join('\n') + (this._ring.length ? '\n' : '')
+  }
+
+  _compact () {
+    if (!this._persistFile) return
+    this._appendedSinceCompact = 0
+    const data = this._serialize()
+    const file = this._persistFile
+    this._io = this._io.then(async () => {
+      await fsp.mkdir(path.dirname(file), { recursive: true })
+      const tmp = `${file}.tmp-${process.pid}`
+      await fsp.writeFile(tmp, data)
+      await fsp.rename(tmp, file)
+    }).catch(() => {})
+  }
+
+  // synchronous compaction — only at construct, so the file exists immediately.
+  _compactSync () {
+    if (!this._persistFile) return
+    this._appendedSinceCompact = 0
+    try {
+      fs.mkdirSync(path.dirname(this._persistFile), { recursive: true })
+      const tmp = `${this._persistFile}.tmp-${process.pid}`
+      fs.writeFileSync(tmp, this._serialize())
+      fs.renameSync(tmp, this._persistFile)
+    } catch {}
+  }
+
+  _flush () { return this._io } // tests: await all pending writes
+
+  destroy () {
+    clearInterval(this._timer)
+    this._compact() // final flush of the current ring
+  }
+}
+
+module.exports = { RingHistoryProvider, MAX_SAMPLES }

package/lib/proxy/cache.js

@@ -0,0 +1,151 @@
+'use strict'
+
+// Caching mirror of a single upstream (the sailkick host). getResource() serves
+// a path from the on-disk store if present, else fetches it from the upstream,
+// stores it (bytes + content-type sidecar) atomically, and serves it — so any
+// resource (tiles, JSON, app assets) is fetched once online then served forever
+// offline. The Node/proxy_store equivalent, generalized beyond tiles.
+//
+// Freshness (v0.6.0): tiles are PINNED — never expired by time. A cached file is
+// only treated as stale when its family's bake was re-announced by the cloud (see
+// manifest.js): callers pass `invalidatedAt` = the ms timestamp at which a newer
+// bake for this path's family was learned. A file older than that is refetched
+// lazily when online (UPDATED) or served stale when offline (STALE). No blind TTLs.
+
+const fs = require('fs')
+const fsp = fs.promises
+const path = require('path')
+const crypto = require('crypto')
+
+// Map a request path (possibly with a query string) to on-disk file paths.
+// Path structure is mirrored for inspectability; a query string is folded into
+// the filename via a short hash so different query params cache separately.
+function storePaths (storeDir, reqPath) {
+  const qIdx = reqPath.indexOf('?')
+  let p = qIdx >= 0 ? reqPath.slice(0, qIdx) : reqPath
+  const q = qIdx >= 0 ? reqPath.slice(qIdx + 1) : ''
+  p = p.replace(/^\/+/, '') || 'index'
+  let rel = p.replace(/[^a-zA-Z0-9._/-]/g, '_').replace(/\.\.(\/|$)/g, '')
+  if (q) rel += '__q_' + crypto.createHash('sha1').update(q).digest('hex').slice(0, 16)
+  const file = path.resolve(storeDir, rel)
+  // safety: never escape the store dir
+  if (!file.startsWith(path.resolve(storeDir) + path.sep)) {
+    throw new Error('invalid path')
+  }
+  return { file, meta: file + '.ct' }
+}
+
+async function readFromDisk (file, meta) {
+  const buffer = await fsp.readFile(file)
+  let contentType = 'application/octet-stream'
+  try { contentType = (await fsp.readFile(meta, 'utf8')).trim() || contentType } catch {}
+  return { buffer, contentType }
+}
+
+// Fetch from upstream and persist atomically (bytes + content-type sidecar). The
+// rename stamps the file mtime ~now, which is what freshness compares against.
+async function fetchAndStore (url, file, meta, timeoutMs) {
+  let resp
+  try {
+    resp = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) })
+  } catch (e) {
+    const err = new Error(`offline / unreachable: ${e.message}`); err.offline = true; throw err
+  }
+  if (!resp.ok) {
+    if (resp.status === 404) {
+      // Negative-cache empty tiles (sparse layers — coastline/seamap — 404 on empty
+      // tiles) with a sentinel, so offline they read as "empty" (404) instead of
+      // hitting the circuit breaker, and a re-seed skips them with no network.
+      await fsp.mkdir(path.dirname(file), { recursive: true }).catch(() => {})
+      await fsp.writeFile(file + '.404', '').catch(() => {})
+    }
+    const err = new Error(`upstream HTTP ${resp.status}`); err.status = resp.status; throw err
+  }
+  const contentType = resp.headers.get('content-type') || 'application/octet-stream'
+  const buffer = Buffer.from(await resp.arrayBuffer())
+  await fsp.mkdir(path.dirname(file), { recursive: true })
+  const tmp = `${file}.tmp-${process.pid}-${buffer.length}`
+  await fsp.writeFile(tmp, buffer)
+  await fsp.rename(tmp, file)
+  await fsp.writeFile(meta, contentType).catch(() => {})
+  return { buffer, contentType }
+}
+
+// opts: { storeDir, upstream, reqPath, timeoutMs, invalidatedAt, networkFirst, health }
+// returns { buffer, contentType, cacheState, fromCache }; throws (err.offline /
+// err.status) only when neither cached nor fetchable.
+//
+// Two strategies:
+//   cache-first  (default; static assets + tiles) — serve disk if present, pinned
+//     until a bake is announced (invalidatedAt). HIT / UPDATED / STALE / MISS.
+//   networkFirst (dynamic /api data — AIS, weather) — fetch LIVE each time, fall
+//     back to the cached copy only when offline (STALE). Never serves stale live
+//     data while online.
+//
+// `health` is a shared { downUntil, cooldownMs } circuit breaker: once a fetch
+// fails offline, the upstream is treated as down for cooldownMs, so subsequent
+// uncached requests FAIL FAST (no per-request timeout hang that would starve the
+// browser's connection pool) — cached HITs are unaffected. A success clears it.
+async function getResource (opts) {
+  const { storeDir, upstream, reqPath, timeoutMs = 20000, invalidatedAt = 0, networkFirst = false, health = null } = opts
+  const { file, meta } = storePaths(storeDir, reqPath)
+  const url = upstream.replace(/\/+$/, '') + reqPath
+  const downNow = !!(health && Date.now() < health.downUntil)
+
+  const serveDisk = async (state) => ({ ...(await readFromDisk(file, meta)), cacheState: state, fromCache: true })
+  const tryFetch = async (state) => {
+    const r = await fetchAndStore(url, file, meta, timeoutMs)
+    if (health) health.downUntil = 0 // upstream answered → clear the breaker
+    return { ...r, cacheState: state, fromCache: false }
+  }
+  const noteFail = (e) => { if (health && e.offline) health.downUntil = Date.now() + (health.cooldownMs || 15000) }
+  const offline = (msg) => { const e = new Error(msg); e.offline = true; return e }
+
+  if (networkFirst) {
+    const stat = await fsp.stat(file).catch(() => null)
+    if (downNow) { if (stat) return serveDisk('STALE'); throw offline('offline / not cached') }
+    try { return await tryFetch('LIVE') } catch (e) { noteFail(e); if (stat) return serveDisk('STALE'); throw e }
+  }
+
+  // cache-first
+  const stat = await fsp.stat(file).catch(() => null)
+  if (stat) {
+    const stale = invalidatedAt && stat.mtimeMs < invalidatedAt
+    if (!stale) return serveDisk('HIT')
+    // A newer bake was announced; the on-disk copy predates it.
+    if (downNow) return serveDisk('STALE')
+    try { return await tryFetch('UPDATED') } catch (e) { noteFail(e); return serveDisk('STALE') }
+  }
+  // not cached — but maybe negative-cached (known-empty tile)
+  const emptyStat = await fsp.stat(file + '.404').catch(() => null)
+  if (emptyStat && !(invalidatedAt && emptyStat.mtimeMs < invalidatedAt)) {
+    const err = new Error('empty (404, cached)'); err.status = 404; throw err // no fetch
+  }
+  if (downNow) throw offline('offline / not cached (circuit open)') // fast-fail — don't hang the pool
+  try { return await tryFetch('MISS') } catch (e) { noteFail(e); throw e }
+}
+
+// Manual force-refresh helper. Two modes:
+//   { prefix: 'tiles/osm-standard' } — delete that subtree (a specific tileset)
+//   { keep: ['tiles', 'terrain'] }   — delete all top-level entries EXCEPT these
+// Deleted files re-fetch fresh on next request. Returns { removed }.
+async function clearStore ({ storeDir, keep = [], prefix = '' } = {}) {
+  const root = path.resolve(storeDir)
+  if (prefix) {
+    const target = path.resolve(root, String(prefix).replace(/^\/+/, ''))
+    if (target !== root && !target.startsWith(root + path.sep)) throw new Error('invalid prefix')
+    await fsp.rm(target, { recursive: true, force: true })
+    return { removed: 1, mode: 'prefix', prefix }
+  }
+  const keepSet = new Set(keep)
+  const entries = await fsp.readdir(root).catch(() => [])
+  let removed = 0
+  for (const e of entries) {
+    if (keepSet.has(e)) continue
+    await fsp.rm(path.join(root, e), { recursive: true, force: true })
+    removed++
+  }
+  return { removed, mode: 'keep', kept: [...keepSet] }
+}
+
+module.exports = { getResource, storePaths, clearStore }