@meri-imperiumi/signalk-passage-briefing 0.2.0

package/tests/sereno-physics.test.js

@@ -0,0 +1,333 @@
+const { test, describe } = require("node:test");
+const assert = require("node:assert/strict");
+
+const physicsPromise = import("../public/sereno-physics.mjs");
+const physics = async () => physicsPromise;
+
+const approx = (actual, expected, epsilon = 1e-6) =>
+  assert.ok(
+    Math.abs(actual - expected) < epsilon,
+    `expected ${actual} ≈ ${expected} (±${epsilon})`,
+  );
+
+describe("comfort bands (SPEC §5.2)", () => {
+  test("band constants", async () => {
+    const p = await physics();
+    assert.deepEqual(p.AWS_BANDS_KNOTS, [12, 18, 23, 33]);
+    assert.deepEqual(p.AZ_BANDS_MS2, [0.15, 0.315, 0.63, 1.25]);
+    assert.deepEqual(p.COMFORT_TIERS, [
+      "champagne",
+      "easy",
+      "coffee",
+      "rough",
+      "sick",
+    ]);
+    assert.deepEqual(p.STEEPNESS_RATIO_THRESHOLD, 3.28);
+  });
+
+  test("apparent wind bands", async () => {
+    const { rateApparentWind } = await physics();
+    assert.equal(rateApparentWind(11.9), "champagne");
+    assert.equal(rateApparentWind(12), "easy");
+    assert.equal(rateApparentWind(18), "coffee");
+    assert.equal(rateApparentWind(23), "rough");
+    assert.equal(rateApparentWind(33), "sick");
+  });
+
+  test("acceleration bands", async () => {
+    const { rateAcceleration } = await physics();
+    assert.equal(rateAcceleration(0.149), "champagne");
+    assert.equal(rateAcceleration(0.15), "easy");
+    assert.equal(rateAcceleration(0.315), "coffee");
+    assert.equal(rateAcceleration(0.63), "rough");
+    assert.equal(rateAcceleration(1.25), "sick");
+  });
+});
+
+describe("apparent wind", () => {
+  test("head wind adds boat speed, following wind subtracts", async () => {
+    const { apparentWindSpeedKnots } = await physics();
+    // TWA 0 (dead ahead): AWS = TWS + STW
+    approx(
+      apparentWindSpeedKnots({ twsKnots: 15, stwKnots: 5, twaRad: 0 }),
+      20,
+    );
+    // TWA π (dead astern): AWS = TWS − STW
+    approx(
+      apparentWindSpeedKnots({ twsKnots: 15, stwKnots: 5, twaRad: Math.PI }),
+      10,
+    );
+    // Beam reach: quadrature, per the SPEC formula
+    approx(
+      apparentWindSpeedKnots({
+        twsKnots: 15,
+        stwKnots: 5,
+        twaRad: Math.PI / 2,
+      }),
+      Math.sqrt(15 * 15 + 5 * 5),
+    );
+  });
+});
+
+describe("wave math", () => {
+  test("deep-water wavelength and phase speed", async () => {
+    const { waveLengthMeters, wavePhaseSpeedMs } = await physics();
+    approx(waveLengthMeters(7), (9.81 * 49) / (2 * Math.PI));
+    approx(wavePhaseSpeedMs(7), (9.81 * 7) / (2 * Math.PI));
+    // L = c·T
+    approx(waveLengthMeters(5), wavePhaseSpeedMs(5) * 5);
+  });
+
+  test("encounter period: bow seas arrive faster, astern seas slower", async () => {
+    const { encounterPeriodSeconds } = await physics();
+    // Wave travel convention: seas from astern travel with the boat's
+    // heading (travel ≈ heading), seas on the bow against it.
+    const bow = encounterPeriodSeconds({
+      tpSeconds: 7,
+      sogKnots: 6,
+      waveTravelDirectionRad: Math.PI,
+      headingRad: 0,
+    });
+    assert.ok(bow < 7, `bow Te ${bow} < Tp`);
+    const astern = encounterPeriodSeconds({
+      tpSeconds: 7,
+      sogKnots: 6,
+      waveTravelDirectionRad: 0,
+      headingRad: 0,
+    });
+    assert.ok(astern > 7, `astern Te ${astern} > Tp`);
+    // Same train met from the opposite heading: symmetric stretch
+    const reversed = encounterPeriodSeconds({
+      tpSeconds: 7,
+      sogKnots: 6,
+      waveTravelDirectionRad: Math.PI,
+      headingRad: Math.PI,
+    });
+    approx(reversed, astern);
+  });
+
+  test("surfing a slower train cannot drive Te to zero", async () => {
+    const { encounterPeriodSeconds } = await physics();
+    // 8.2 kn boat overtakes a 3 s train it matches 90% of the phase
+    // speed of: stretch |1 − 0.907| = 0.093 → floored at 0.15
+    const te = encounterPeriodSeconds({
+      tpSeconds: 3,
+      sogKnots: 8.2,
+      waveTravelDirectionRad: 0,
+      headingRad: 0,
+    });
+    approx(te, 3 / 0.15); // factor floor
+  });
+
+  test("from-conversion helper", async () => {
+    const { travelDirection } = await physics();
+    approx(travelDirection(0), Math.PI);
+    approx(travelDirection(Math.PI), 0);
+  });
+
+  test("steepness ratio", async () => {
+    const { steepnessRatio, STEEPNESS_RATIO_THRESHOLD } = await physics();
+    assert.equal(steepnessRatio(3.28, 1), STEEPNESS_RATIO_THRESHOLD);
+    assert.equal(steepnessRatio(6, 0), Infinity);
+  });
+});
+
+describe("monohull corrections (SPEC §5.2 vector 2)", () => {
+  test("heel peaks on a beam reach and scales with apparent wind", async () => {
+    const { heelAngleDeg } = await physics();
+    approx(heelAngleDeg({ awsKnots: 25, twaRad: Math.PI / 2 }), 25);
+    approx(heelAngleDeg({ awsKnots: 12.5, twaRad: Math.PI / 2 }), 12.5);
+    approx(heelAngleDeg({ awsKnots: 25, twaRad: 0 }), 0);
+    approx(heelAngleDeg({ awsKnots: 25, twaRad: Math.PI }), 0);
+    // Never beyond φ_max even in extreme wind
+    approx(heelAngleDeg({ awsKnots: 60, twaRad: Math.PI / 2 }), 25);
+  });
+
+  test("heel multiplier", async () => {
+    const { heelMultiplier } = await physics();
+    approx(heelMultiplier(0, 0.35), 1);
+    approx(heelMultiplier(25, 0.35), 1 + 0.35 * Math.sin((25 * Math.PI) / 180));
+  });
+
+  test("pitch multiplier resonates at hull length and punishes steep seas", async () => {
+    const { pitchMultiplier, waveLengthMeters, STEEPNESS_RATIO_THRESHOLD } =
+      await physics();
+    // L_wave ≈ L_wl (9.4 m) → Tp ≈ 2.45 s: full resonance term
+    const resonantTp = Math.sqrt((2 * Math.PI * 9.4) / 9.81);
+    const calm = { tpSeconds: 12, hsMeters: 1, waterlineLengthM: 9.4 };
+    const resonant = {
+      tpSeconds: resonantTp,
+      hsMeters: 1,
+      waterlineLengthM: 9.4,
+    };
+    const steep = { tpSeconds: 4, hsMeters: 2.5, waterlineLengthM: 9.4 };
+    assert.ok(pitchMultiplier(resonant, 0.4) > pitchMultiplier(calm, 0.4));
+    // Tp/Hs = 1.6 → steepness term (3.28 − 1.6)/3.28 plus the residual
+    // resonance of the 25 m wave train
+    const resonance = Math.exp(-(((waveLengthMeters(4) - 9.4) / 9.4) ** 2));
+    approx(
+      pitchMultiplier(steep, 0.4),
+      1 +
+        0.4 * resonance +
+        (STEEPNESS_RATIO_THRESHOLD - 1.6) / STEEPNESS_RATIO_THRESHOLD,
+      1e-9,
+    );
+    // Long gentle swell: essentially unity
+    assert.ok(pitchMultiplier(calm, 0.4) < 1.01);
+  });
+
+  test("vertical acceleration grows with head seas and sea height", async () => {
+    const { verticalAcceleration, heelAngleDeg, apparentWindSpeedKnots } =
+      await physics();
+    const sea = (tpSeconds, hsMeters, waveTravelDirectionRad) => ({
+      tpSeconds,
+      hsMeters,
+      waveTravelDirectionRad,
+    });
+    const vessel = {
+      sogKnots: 6,
+      headingRad: 0,
+      waterlineLengthM: 9.4,
+      kHeel: 0.35,
+      kPitch: 0.4,
+    };
+    const wind = { twsKnots: 15, twaRad: Math.PI / 2 };
+    const head = verticalAcceleration(sea(7, 2, Math.PI), vessel, wind);
+    const astern = verticalAcceleration(sea(7, 2, 0), vessel, wind);
+    assert.ok(head.value > astern.value);
+    // Proportional to Hs at fixed Te (heel/pitch identical here)
+    const mild = verticalAcceleration(sea(7, 1, Math.PI), vessel, wind);
+    assert.ok(Math.abs(head.value / mild.value - 2) < 0.05);
+    // Calm sea: no acceleration
+    approx(verticalAcceleration(sea(7, 0, 0), vessel, wind).value, 0);
+    // Beam reach heel comes out of the wind vector via AWS
+    const assessment = verticalAcceleration(sea(7, 2, 0), vessel, wind);
+    approx(
+      assessment.heelDeg,
+      heelAngleDeg({
+        awsKnots: apparentWindSpeedKnots({
+          twsKnots: wind.twsKnots,
+          stwKnots: vessel.sogKnots,
+          twaRad: wind.twaRad,
+        }),
+        twaRad: wind.twaRad,
+      }),
+    );
+  });
+});
+
+describe("serenoComfort", () => {
+  test("the worse vector sets the level", async () => {
+    const { serenoComfort } = await physics();
+    const vessel = {
+      sogKnots: 5,
+      headingRad: 0,
+      waterlineLengthM: 9.4,
+      kHeel: 0.35,
+      kPitch: 0.4,
+    };
+    // Gusty but flat: wind vector dominates (AWS ≈ 31 kt → Rough)
+    const gusty = serenoComfort(
+      { tpSeconds: 10, hsMeters: 0.5, waveTravelDirectionRad: 0 },
+      vessel,
+      { twsKnots: 26, twaRad: 0.2 },
+    );
+    assert.equal(gusty.comfort, "rough");
+    assert.equal(gusty.motionComfort, "champagne");
+    // Gentle wind but big steep head seas: motion dominates
+    const rough = serenoComfort(
+      { tpSeconds: 5, hsMeters: 3, waveTravelDirectionRad: 0 },
+      vessel,
+      { twsKnots: 6, twaRad: 0.3 },
+    );
+    assert.ok(
+      ["rough", "sick"].includes(rough.comfort),
+      `expected rough/sick, got ${rough.comfort}`,
+    );
+    // Champagne glass conditions: light following breeze, gentle swell
+    const idyllic = serenoComfort(
+      { tpSeconds: 9, hsMeters: 0.3, waveTravelDirectionRad: 0 },
+      vessel,
+      { twsKnots: 8, twaRad: 2.4 },
+    );
+    assert.equal(idyllic.comfort, "champagne");
+  });
+});
+
+describe("day/night bucket", () => {
+  test("sun altitude: equator equinox solar noon overhead, midnight below", async () => {
+    const { sunAltitudeDeg } = await physics();
+    // Solar noon at longitude 0 late March (equation of time ≈ −7 min)
+    const noon = sunAltitudeDeg(new Date("2026-03-20T12:07:00Z"), 0, 0);
+    approx(noon, 90, 1);
+    const midnight = sunAltitudeDeg(new Date("2026-03-21T00:07:00Z"), 0, 0);
+    approx(midnight, -90, 1);
+  });
+
+  test("Helsinki: midsummer noon is day, midnight is night", async () => {
+    const { sunAltitudeDeg, isNight } = await physics();
+    const lat = 60.17;
+    const lon = 24.94;
+    // Solar noon at 24.94°E in late June ≈ 10:21Z
+    const noon = sunAltitudeDeg(new Date("2026-06-21T10:21:00Z"), lat, lon);
+    approx(noon, 90 - lat + 23.44, 1.5);
+    // Solar midnight ≈ 22:21Z
+    const midnight = sunAltitudeDeg(new Date("2026-06-21T22:21:00Z"), lat, lon);
+    approx(midnight, lat + 23.44 - 90, 1.5);
+    assert.ok(!isNight(new Date("2026-06-21T10:21:00Z"), lat, lon));
+    assert.ok(isNight(new Date("2026-06-21T22:21:00Z"), lat, lon));
+    // Threshold parameterization: with a −10° threshold the Helsinki
+    // midsummer midnight (sun ≈ −6.4°) is *not* night
+    assert.ok(!isNight(new Date("2026-06-21T22:21:00Z"), lat, lon, -10));
+  });
+
+  test("default threshold is sunset", async () => {
+    const { NIGHT_SUN_ALTITUDE_DEG } = await physics();
+    assert.equal(NIGHT_SUN_ALTITUDE_DEG, 0);
+  });
+});
+
+describe("suggestSailState", () => {
+  const matrix = {
+    twsBinsKnots: [0, 5, 10, 15, 20, 25, 30, 35, 40],
+    twaBinsDegrees: [0, 30, 60, 90, 120, 150, 180],
+    matrix: [
+      {
+        twsBin: 3,
+        twaBin: 4,
+        night: false,
+        preferredSailState: "GENOA_1_MAIN",
+        minTwsGustTrigger: 16,
+        samplesCount: 2,
+      },
+      {
+        twsBin: 3,
+        twaBin: 4,
+        night: true,
+        preferredSailState: "STAYSAIL_MAIN_1_REEF",
+        minTwsGustTrigger: 16,
+        samplesCount: 3,
+      },
+    ],
+  };
+
+  test("picks the bin by folded TWA and day/night bucket", async () => {
+    const { suggestSailState } = await physics();
+    const day = suggestSailState(matrix, 16, 140, false);
+    assert.equal(day.preferredSailState, "GENOA_1_MAIN");
+    const night = suggestSailState(matrix, 16, 140, true);
+    assert.equal(night.preferredSailState, "STAYSAIL_MAIN_1_REEF");
+    // Signed TWA folds onto the magnitude range
+    assert.equal(suggestSailState(matrix, 16, -220, false).twsBin, 3);
+    // Unknown bin and missing matrix
+    assert.equal(suggestSailState(matrix, 50, 10), null);
+    assert.equal(suggestSailState(null, 16, 140), null);
+  });
+});
+
+test("binIndexFor clamps to the last bin", async () => {
+  const { binIndexFor } = await physics();
+  assert.equal(binIndexFor(0, [0, 5, 10]), 0);
+  assert.equal(binIndexFor(7, [0, 5, 10]), 1);
+  assert.equal(binIndexFor(99, [0, 5, 10]), 2);
+});

package/tests/sqlite-db.test.js

@@ -0,0 +1,164 @@
+const { test, describe } = require("node:test");
+const assert = require("node:assert/strict");
+const { mkdtempSync } = require("node:fs");
+const { tmpdir } = require("node:os");
+const { join } = require("node:path");
+
+const {
+  PassageDatabase,
+  TWS_BINS_KNOTS,
+  TWA_BINS_DEGREES,
+  EMA_ALPHA,
+  twsBinIndex,
+  twaBinIndex,
+  emaUpdate,
+} = require("../plugin/sqlite-db.js");
+
+const makeDb = (label) =>
+  new PassageDatabase(mkdtempSync(join(tmpdir(), `passage-${label}-`)));
+
+describe("sqlite db", () => {
+  test("creates the spec schema tables", () => {
+    const db = makeDb("schema");
+    try {
+      const tables = db.db
+        .prepare(
+          `SELECT name FROM sqlite_master WHERE type = 'table' ORDER BY name`,
+        )
+        .all()
+        .map((row) => row.name);
+      assert.ok(tables.includes("logbook_sail_events"));
+      assert.ok(tables.includes("wind_history_cache"));
+      assert.ok(tables.includes("learned_sail_matrix"));
+
+      const wal = db.db.prepare("PRAGMA journal_mode").get();
+      assert.equal(wal.journal_mode, "wal");
+    } finally {
+      db.close();
+    }
+  });
+
+  test("records and lists sail events", () => {
+    const db = makeDb("events");
+    try {
+      const id = db.recordSailEvent({
+        timestamp: "2026-08-01T12:00:00Z",
+        eventType: "REEF_INCREASE",
+        sailState: "REEF_1_GENOA",
+        notes: "gust line",
+      });
+      assert.equal(id, 1);
+      db.recordSailEvent({
+        timestamp: "2026-08-01T14:00:00Z",
+        eventType: "SAIL_CHANGE",
+        sailState: "MAIN_FULL_GENOA_100",
+      });
+
+      const events = db.getSailEvents();
+      assert.equal(events.length, 2);
+      assert.equal(events[0].sailState, "MAIN_FULL_GENOA_100");
+      assert.equal(events[0].notes, null);
+      assert.equal(events[1].eventType, "REEF_INCREASE");
+    } finally {
+      db.close();
+    }
+  });
+
+  test("upserts wind history keyed by timestamp", () => {
+    const db = makeDb("wind");
+    try {
+      db.upsertWindHistory({
+        timestamp: "2026-08-01T12:00:00Z",
+        twsAvg: 12.5,
+        twsPeak: 18.2,
+        twaAvg: 95,
+      });
+      db.upsertWindHistory({
+        timestamp: "2026-08-01T12:00:00Z",
+        twsAvg: 12.8,
+        twsPeak: 18.6,
+        twaAvg: 94,
+      });
+      db.upsertWindHistory({
+        timestamp: "2026-08-01T12:15:00Z",
+        twsAvg: 13.1,
+        twsPeak: 16.0,
+        twaAvg: 100,
+      });
+
+      assert.equal(
+        db.db.prepare("SELECT COUNT(*) AS n FROM wind_history_cache").get().n,
+        2,
+      );
+      const window = db.getWindHistory(
+        "2026-08-01T12:00:00Z",
+        "2026-08-01T12:15:00Z",
+      );
+      assert.equal(window.length, 2);
+      assert.equal(window[0].twsAvg, 12.8);
+    } finally {
+      db.close();
+    }
+  });
+
+  test("bins and EMA follow the spec constants", () => {
+    assert.deepEqual(TWS_BINS_KNOTS, [0, 5, 10, 15, 20, 25, 30, 35, 40]);
+    assert.deepEqual(TWA_BINS_DEGREES, [0, 30, 60, 90, 120, 150, 180]);
+    assert.equal(EMA_ALPHA, 0.2);
+
+    assert.equal(twsBinIndex(0), 0);
+    assert.equal(twsBinIndex(7.5), 1);
+    assert.equal(twsBinIndex(22), 4);
+    assert.equal(twsBinIndex(42), 8);
+    assert.equal(twaBinIndex(15), 0);
+    assert.equal(twaBinIndex(120), 4);
+    assert.equal(twaBinIndex(200), 6);
+  });
+
+  test("emaUpdate applies the 0.2 learning rate", () => {
+    // Spec formula: (1 - 0.2) * old + 0.2 * sample.
+    assert.equal(emaUpdate(10, 20), 0.8 * 10 + 0.2 * 20);
+    assert.equal(emaUpdate(null, 17.5), 17.5);
+  });
+
+  test("matrix bins round-trip in the spec shape", () => {
+    const db = makeDb("matrix");
+    try {
+      db.upsertMatrixBin({
+        twsBin: twsBinIndex(12),
+        twaBin: twaBinIndex(95),
+        preferredSail: "MAIN_FULL_GENOA_100",
+        avgTwsTrigger: 12.5,
+        peakGustTrigger: 18.0,
+        sampleCount: 3,
+      });
+      // Rebinding the same cell replaces it instead of duplicating.
+      db.upsertMatrixBin({
+        twsBin: 2,
+        twaBin: 3,
+        preferredSail: "MAIN_REEF_1_GENOA_100",
+        avgTwsTrigger: 12.1,
+        peakGustTrigger: 17.4,
+        sampleCount: 4,
+      });
+
+      const bins = db.getMatrixBins();
+      assert.equal(bins.length, 1);
+      assert.equal(bins[0].twsBin, 2);
+      assert.equal(bins[0].twaBin, 3);
+
+      const matrix = db.getSailPreferenceMatrix();
+      assert.deepEqual(matrix.twsBinsKnots, TWS_BINS_KNOTS);
+      assert.deepEqual(matrix.twaBinsDegrees, TWA_BINS_DEGREES);
+      assert.equal(matrix.matrix.length, 1);
+      assert.equal(
+        matrix.matrix[0].preferredSailState,
+        "MAIN_REEF_1_GENOA_100",
+      );
+      assert.equal(matrix.matrix[0].minTwsGustTrigger, 17.4);
+      assert.equal(matrix.matrix[0].samplesCount, 4);
+    } finally {
+      db.close();
+    }
+  });
+});

package/tests/state-machine.test.js

@@ -0,0 +1,182 @@
+const { test, describe } = require("node:test");
+const assert = require("node:assert/strict");
+
+const {
+  STATES,
+  CRON_HOURS_UTC,
+  CRON_MINUTE_UTC,
+  SOC_FULL_THRESHOLD,
+  nextCronRun,
+  PassageStateMachine,
+} = require("../plugin/state-machine.js");
+
+const d = (iso) => new Date(iso);
+
+describe("state machine", () => {
+  test("starts OFFLINE", () => {
+    const machine = new PassageStateMachine();
+    assert.equal(machine.state, STATES.OFFLINE);
+  });
+
+  test("internet edge to online fires a oneshot fetch and lands in STANDBY_OFFSHORE while sailing", () => {
+    const machine = new PassageStateMachine();
+    const result = machine.update(
+      { internetState: "online", navigationState: "sailing" },
+      d("2026-08-01T10:00:00Z"),
+    );
+    assert.equal(result.fetch, "oneshot");
+    assert.equal(result.state, STATES.STANDBY_OFFSHORE);
+    assert.equal(machine.state, STATES.STANDBY_OFFSHORE);
+  });
+
+  test("online + moored + full battery lands in PERSISTENT_CRON", () => {
+    const machine = new PassageStateMachine();
+    const result = machine.update(
+      {
+        internetState: "online",
+        navigationState: "moored",
+        soc: 0.98,
+      },
+      d("2026-08-01T10:00:00Z"),
+    );
+    assert.equal(result.fetch, "oneshot");
+    assert.equal(result.state, STATES.PERSISTENT_CRON);
+  });
+
+  test("low or unknown state of charge keeps the vessel in STANDBY_OFFSHORE", () => {
+    const machine = new PassageStateMachine();
+    machine.update(
+      { internetState: "online", navigationState: "anchored", soc: 0.5 },
+      d("2026-08-01T10:00:00Z"),
+    );
+    assert.equal(machine.state, STATES.STANDBY_OFFSHORE);
+
+    const unknown = new PassageStateMachine();
+    unknown.update(
+      { internetState: "online", navigationState: "anchored", soc: null },
+      d("2026-08-01T10:00:00Z"),
+    );
+    assert.equal(unknown.state, STATES.STANDBY_OFFSHORE);
+  });
+
+  test("soc threshold matches the spec constant", () => {
+    assert.equal(SOC_FULL_THRESHOLD, 0.95);
+  });
+
+  test("stable observations do not refetch", () => {
+    const machine = new PassageStateMachine();
+    machine.update(
+      { internetState: "online", navigationState: "sailing" },
+      d("2026-08-01T10:00:00Z"),
+    );
+    const again = machine.update(
+      { internetState: "online", navigationState: "sailing" },
+      d("2026-08-01T10:00:01Z"),
+    );
+    assert.equal(again.fetch, null);
+    assert.equal(again.transitioned, false);
+  });
+
+  test("online to metered flip is a new explicit transition and refetches", () => {
+    const machine = new PassageStateMachine();
+    machine.update(
+      { internetState: "online", navigationState: "sailing" },
+      d("2026-08-01T10:00:00Z"),
+    );
+    const result = machine.update(
+      { internetState: "metered", navigationState: "sailing" },
+      d("2026-08-01T10:05:00Z"),
+    );
+    assert.equal(result.fetch, "oneshot");
+  });
+
+  test("losing the internet connection returns to OFFLINE", () => {
+    const machine = new PassageStateMachine();
+    machine.update(
+      { internetState: "online", navigationState: "moored", soc: 1 },
+      d("2026-08-01T10:00:00Z"),
+    );
+    const result = machine.update(
+      { internetState: "offline", navigationState: "moored", soc: 1 },
+      d("2026-08-01T10:05:00Z"),
+    );
+    assert.equal(result.state, STATES.OFFLINE);
+    assert.equal(machine.scheduledCronRun, null);
+  });
+
+  test("nextCronRun returns the four UTC publication windows", () => {
+    assert.deepEqual(CRON_HOURS_UTC, [2, 8, 14, 20]);
+    assert.equal(CRON_MINUTE_UTC, 15);
+
+    // Before the first window: same day 02:15.
+    assert.equal(
+      nextCronRun(d("2026-08-01T01:00:00Z")).toISOString(),
+      "2026-08-01T02:15:00.000Z",
+    );
+    // Just after a window: the next one the same day.
+    assert.equal(
+      nextCronRun(d("2026-08-01T02:15:00Z")).toISOString(),
+      "2026-08-01T08:15:00.000Z",
+    );
+    // After the last window: wraps to 02:15 the following day.
+    assert.equal(
+      nextCronRun(d("2026-08-01T21:00:00Z")).toISOString(),
+      "2026-08-02T02:15:00.000Z",
+    );
+  });
+
+  test("cron fires once per window in PERSISTENT_CRON", () => {
+    const machine = new PassageStateMachine();
+    machine.update(
+      { internetState: "online", navigationState: "moored", soc: 1 },
+      d("2026-08-01T10:00:00Z"),
+    );
+    assert.equal(
+      machine.scheduledCronRun?.toISOString(),
+      "2026-08-01T14:15:00.000Z",
+    );
+
+    const early = machine.tick(d("2026-08-01T14:14:00Z"));
+    assert.equal(early.fetch, null);
+
+    const due = machine.tick(d("2026-08-01T14:15:30Z"));
+    assert.equal(due.fetch, "cron");
+    assert.equal(due.cronWindow.toISOString(), "2026-08-01T14:15:00.000Z");
+
+    // Already handled this window: no double fire.
+    assert.equal(machine.tick(d("2026-08-01T14:16:00Z")).fetch, null);
+  });
+
+  test("cron never fires outside PERSISTENT_CRON (execution guard)", () => {
+    const machine = new PassageStateMachine();
+    // Sailing: STANDBY_OFFSHORE, cron disabled even with internet up.
+    machine.update(
+      { internetState: "online", navigationState: "sailing", soc: 1 },
+      d("2026-08-01T10:00:00Z"),
+    );
+    assert.equal(machine.state, STATES.STANDBY_OFFSHORE);
+    assert.equal(machine.scheduledCronRun, null);
+    assert.equal(machine.tick(d("2026-08-01T14:20:00Z")).fetch, null);
+  });
+
+  test("leaving and re-entering PERSISTENT_CRON reschedules the next window", () => {
+    const machine = new PassageStateMachine();
+    machine.update(
+      { internetState: "online", navigationState: "moored", soc: 1 },
+      d("2026-08-01T10:00:00Z"),
+    );
+    machine.update(
+      { internetState: "online", navigationState: "sailing", soc: 1 },
+      d("2026-08-01T11:00:00Z"),
+    );
+    const result = machine.update(
+      { internetState: "online", navigationState: "anchored", soc: 1 },
+      d("2026-08-01T15:00:00Z"),
+    );
+    assert.equal(result.state, STATES.PERSISTENT_CRON);
+    assert.equal(
+      machine.scheduledCronRun?.toISOString(),
+      "2026-08-01T20:15:00.000Z",
+    );
+  });
+});